@labpics/colors 0.9.1 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +381 -282
- package/adapt-theme.d.ts +76 -74
- package/adapt-theme.js +738 -542
- package/apply-theme.d.ts +16 -16
- package/apply-theme.js +45 -44
- package/build-metadata.json +19 -0
- package/effective-bg.d.ts +51 -50
- package/effective-bg.js +501 -492
- package/index.d.ts +70 -37
- package/index.js +21 -21
- package/package.json +11 -5
- package/pkg/labcolors.d.ts +282 -37
- package/pkg/labcolors.js +65 -33
- package/pkg/labcolors_bg.wasm +0 -0
- package/pkg/labcolors_bg.wasm.d.ts +2 -1
- package/watch-theme.d.ts +57 -57
- package/watch-theme.js +144 -144
package/README.md
CHANGED
|
@@ -1,282 +1,381 @@
|
|
|
1
|
-
# @labpics/colors
|
|
2
|
-
|
|
3
|
-
Агностичный контраст-движок для дизайн-систем. Получает фоновый цвет и тему — возвращает полный набор цветовых ролей **вашей** системы. Словарь ролей не встроен в пакет: его задаёт конфиг дизайн-системы (`ThemeConfig`), загружаемый через `loadConfig`; имена вида `--lab-label-primary`, `--lab-border-base` в примерах ниже — из конфига дизайн-системы labui. CSS-переменные несут готовое значение `oklch(L% C H)` (для полупрозрачных ролей — `oklch(L% C H / A)`); сырой `#RRGGBB` остаётся данными роли (`roles.<ключ>.hex`). Ядро написано на Rust и скомпилировано в WebAssembly; пакет не имеет runtime-зависимостей.
|
|
4
|
-
|
|
5
|
-
Ядро возвращает **данные**, не затрагивает DOM. Три вспомогательные функции переводят эти данные в живые CSS-переменные: `applyTheme` (разовое применение), `watchTheme` (реактивное — обновляется при изменении фона) и `adaptTheme` (плавная адаптация для фона, меняющегося каждый кадр).
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## Установка
|
|
10
|
-
|
|
11
|
-
Пакет публикуется в npm-реестр Labpics:
|
|
12
|
-
|
|
13
|
-
```sh
|
|
14
|
-
npm install @labpics/colors
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
При сборке из монорепо:
|
|
18
|
-
|
|
19
|
-
```sh
|
|
20
|
-
npm run build # → pkg/ (wasm + JS-обёртка + .d.ts)
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
adaptive
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
---
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
|
153
|
-
|
|
154
|
-
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
1
|
+
# @labpics/colors
|
|
2
|
+
|
|
3
|
+
Агностичный контраст-движок для дизайн-систем. Получает фоновый цвет и тему — возвращает полный набор цветовых ролей **вашей** системы. Словарь ролей не встроен в пакет: его задаёт конфиг дизайн-системы (`ThemeConfig`), загружаемый через `loadConfig`; имена вида `--lab-label-primary`, `--lab-border-base` в примерах ниже — из конфига дизайн-системы labui. CSS-переменные несут готовое значение `oklch(L% C H)` (для полупрозрачных ролей — `oklch(L% C H / A)`); сырой `#RRGGBB` остаётся данными роли (`roles.<ключ>.hex`). Ядро написано на Rust и скомпилировано в WebAssembly; пакет не имеет runtime-зависимостей.
|
|
4
|
+
|
|
5
|
+
Ядро возвращает **данные**, не затрагивает DOM. Три вспомогательные функции переводят эти данные в живые CSS-переменные: `applyTheme` (разовое применение), `watchTheme` (реактивное — обновляется при изменении фона) и `adaptTheme` (плавная адаптация для фона, меняющегося каждый кадр).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Установка
|
|
10
|
+
|
|
11
|
+
Пакет публикуется в npm-реестр Labpics:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npm install @labpics/colors
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
При сборке из монорепо:
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
npm run build # → pkg/ (wasm + JS-обёртка + .d.ts)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Пакет экспортирует `@labpics/colors/build-metadata.json` — self-declared
|
|
24
|
+
machine-readable metadata конкретной сборки: npm/core versions, exact source
|
|
25
|
+
SHA, digest и SHA-256 conformance manifest/family set, а также размер и SHA-256
|
|
26
|
+
WASM-байтов. Release-gate сверяет объект целиком с исходными файлами и повторяет
|
|
27
|
+
проверку после чистой установки tarball. Это integrity metadata внутри
|
|
28
|
+
артефакта, не криптографическая provenance/Sigstore-аттестация, не runtime
|
|
29
|
+
telemetry и не сетевой запрос.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Как использовать
|
|
34
|
+
|
|
35
|
+
### Разовое применение
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import init, { LabColors, applyTheme } from "@labpics/colors";
|
|
39
|
+
import dsConfig from "./theme.config.json"; // паспорт вашей дизайн-системы (ThemeConfig)
|
|
40
|
+
|
|
41
|
+
await init(); // загрузить WASM-модуль (один раз)
|
|
42
|
+
const engine = new LabColors(); // пустой движок: словаря ролей ещё нет
|
|
43
|
+
engine.loadConfig(JSON.stringify(dsConfig)); // без этого шага resolveTheme отклонится: config_required
|
|
44
|
+
|
|
45
|
+
const result = engine.resolveTheme("#FFFFFF", "light");
|
|
46
|
+
// result.vars → готовые CSS-значения по ролям ВАШЕГО конфига:
|
|
47
|
+
// { "--lab-label-primary": "oklch(<L>% <C> <H>)", … }
|
|
48
|
+
// result.roles → детали каждой роли (css, hex, контраст, флаги)
|
|
49
|
+
|
|
50
|
+
applyTheme(document.documentElement, result); // записать все --lab-* в элемент
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Реактивное отслеживание
|
|
54
|
+
|
|
55
|
+
`watchTheme` синхронизирует переменные с фактическим фоном элемента автоматически.
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
import init, { LabColors, watchTheme } from "@labpics/colors";
|
|
59
|
+
|
|
60
|
+
await init();
|
|
61
|
+
const colors = new LabColors();
|
|
62
|
+
colors.loadConfig(JSON.stringify(dsConfig)); // конфиг дизайн-системы (см. квик-старт)
|
|
63
|
+
|
|
64
|
+
const panel = document.querySelector(".panel") as HTMLElement;
|
|
65
|
+
const watcher = watchTheme(panel, { colors, theme: "light" });
|
|
66
|
+
// panel теперь несёт правильные --lab-* для своего фона
|
|
67
|
+
|
|
68
|
+
watcher.setTheme("dark"); // переключить тему
|
|
69
|
+
watcher.refresh(); // принудительная пересинхронизация
|
|
70
|
+
watcher.stop(); // отключить наблюдателя
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Поддерживает два режима изменений:
|
|
74
|
+
|
|
75
|
+
- **Дискретные** (переключение темы, обновление класса, DOM-мутация) — отслеживаются `MutationObserver` автоматически.
|
|
76
|
+
- **Непрерывные** (CSS-анимация, кадровый фон, который никогда не мутирует `inline style`) — управляются вручную через `refresh()` из собственного цикла `requestAnimationFrame`. `refresh()` дёшев: пересчитывает только при реальном изменении строки фона.
|
|
77
|
+
|
|
78
|
+
### Плавная адаптация к анимированному фону
|
|
79
|
+
|
|
80
|
+
`watchTheme` пересчитывает весь набор при каждом изменении фона. Для фона, меняющегося **каждый кадр** (анимация, параллакс, размытый фон), `adaptTheme` — более элегантный вариант: проверяет дёшево каждый кадр, пересчитывает и плавно переходит к новым цветам только когда контраст реально ухудшается.
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
import init, { LabColors, adaptTheme, effectiveBackground } from "@labpics/colors";
|
|
84
|
+
|
|
85
|
+
await init();
|
|
86
|
+
const colors = new LabColors();
|
|
87
|
+
colors.loadConfig(JSON.stringify(dsConfig)); // конфиг дизайн-системы (см. квик-старт)
|
|
88
|
+
|
|
89
|
+
const surface = document.querySelector(".hero") as HTMLElement;
|
|
90
|
+
const adaptive = adaptTheme(surface, {
|
|
91
|
+
colors,
|
|
92
|
+
theme: "light",
|
|
93
|
+
background: () => effectiveBackground(surface, { fallback: "#101012" }),
|
|
94
|
+
});
|
|
95
|
+
|
|
96
|
+
adaptive.start(); // запустить внутренний requestAnimationFrame-цикл
|
|
97
|
+
adaptive.setTheme("dark"); // смена темы применяется мгновенно
|
|
98
|
+
adaptive.stop(); // остановить цикл
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Для фона с градиентом или изображением можно передать несколько образцов — цвета будут корректны для наиболее сложного из них:
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
adaptTheme(hero, {
|
|
105
|
+
colors,
|
|
106
|
+
theme: "light",
|
|
107
|
+
strict: true,
|
|
108
|
+
background: () => sampleBackdrop(hero), // например ["#0B0B0E", "#3A3A40"]
|
|
109
|
+
});
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Темы
|
|
115
|
+
|
|
116
|
+
| Имя темы | Назначение |
|
|
117
|
+
|----------|------------|
|
|
118
|
+
| `"light"` | Светлая тема |
|
|
119
|
+
| `"dark"` | Тёмная тема |
|
|
120
|
+
| `"light-ic"` | Светлая с повышенным контрастом |
|
|
121
|
+
| `"dark-ic"` | Тёмная с повышенным контрастом |
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Справочник публичного API
|
|
126
|
+
|
|
127
|
+
### `new LabColors()`
|
|
128
|
+
|
|
129
|
+
Создаёт движок **без** словаря ролей: до `loadConfig` любой вызов `resolveTheme` отклоняется ошибкой `config_required`. Повторные одинаковые вызовы `resolveTheme` обслуживаются из внутреннего кэша (кэш-пространство привязано к отпечатку конфига).
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
### `engine.resolveTheme(bgHex, theme): ResolvedTheme`
|
|
134
|
+
|
|
135
|
+
- `bgHex` — фон в формате `#RGB` или `#RRGGBB`.
|
|
136
|
+
- `theme` — `"light" | "dark" | "light-ic" | "dark-ic"`.
|
|
137
|
+
|
|
138
|
+
Возвращает объект `ResolvedTheme`:
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
interface ResolvedTheme {
|
|
142
|
+
theme: ThemeName;
|
|
143
|
+
background: string; // нормализованный #RRGGBB
|
|
144
|
+
vars: Record<string, string>; // достижимые роли: "--lab-<ключ>" → готовое CSS-значение oklch
|
|
145
|
+
roles: Record<string, RoleResult>; // все роли с деталями
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
type RoleResult =
|
|
149
|
+
| SolvedColor
|
|
150
|
+
| TranslucentRole
|
|
151
|
+
| GlowRole
|
|
152
|
+
| MaterialRole
|
|
153
|
+
| NoneRole
|
|
154
|
+
| UnreachableRole;
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Каждая роль — одна из шести категорий результата; у Glow есть два терминальных
|
|
158
|
+
состояния:
|
|
159
|
+
|
|
160
|
+
- `SolvedColor` — цвет найден (`kind: "color"`, поля `css` — готовое `oklch(L% C H)`, `hex` — тот же цвет как данные, `lc`, `wcagRatio`, …).
|
|
161
|
+
- `TranslucentRole` — полупрозрачная роль лестницы или альфа-аналога (`kind: "translucent"`): `css` — готовое `oklch(L% C H / A)`, `tintHex` — тинт как данные, `alpha`, плюс `compositeHex` / `compositeLc` / `compositeWcag` — exact encoded-sRGB8 reference-композит на фоне резолва и его контраст. Конкретный renderer и color-management pipeline проверяются отдельно.
|
|
162
|
+
- `GlowRole` — discriminated union. `kind: "glow"` несёт два цвета для
|
|
163
|
+
`mix-blend-mode: screen`: `cssVar` — halo, `${cssVar}-core` — core,
|
|
164
|
+
`${cssVar}-alpha` — каноническая `alphaCss`. `compositeProfile` /
|
|
165
|
+
`compositeGuarantee` описывают exact point-композит отдельно от
|
|
166
|
+
`decisionGuarantee`. `layerRecipeProfile` фиксирует общий рецепт слоёв
|
|
167
|
+
`"cam16-jprime-oklab-cusp-v1"`, а обязательный
|
|
168
|
+
`appearanceDiagnosticProfile` — CAM16 appearance-модель результата. Отдельный
|
|
169
|
+
`selectionDiagnosticProfile` сообщает, применялась ли CAM16-диагностика именно
|
|
170
|
+
при выборе состояния: для exact no-op он равен `null`, для legacy solve —
|
|
171
|
+
`"cam16-ucs-jprime-li2017-v1"`. `targetStatus` различает эти ветви явно:
|
|
172
|
+
`"exact-noop-unreachable"`, `"legacy-reached"` или
|
|
173
|
+
`"legacy-unreachable"`. Determinate-форма — union из этих трёх согласованных
|
|
174
|
+
ветвей: смешать stable/legacy profile, guarantee, selection diagnostic,
|
|
175
|
+
status и `degraded` на уровне TypeScript невозможно. Outward interval не
|
|
176
|
+
входит в Glow capability этого релиза. `kind: "glow-indeterminate"`
|
|
177
|
+
означает, что профиль `stable-v1` не выбрал target/max state без sound bound;
|
|
178
|
+
для такой роли CSS-переменные не эмитятся и legacy fallback не применяется.
|
|
179
|
+
Цель и все `*CompositeHex` / `*AchievedDj` относятся только к изолированным
|
|
180
|
+
point-слоям, а не к полному blur/overlap-эффекту, браузеру или дисплею.
|
|
181
|
+
- `MaterialRole` — union трёх терминальных исходов: satisfied transparent
|
|
182
|
+
endpoint (`alpha = 0`), satisfied bisection bracket (`alpha` побитно равна
|
|
183
|
+
`upperAlpha`) и degraded opaque endpoint (`alpha = 1`). `alphaStatus`,
|
|
184
|
+
`alphaGuarantee` и compatibility-поле `guaranteed` согласованы типом. `floor`
|
|
185
|
+
— запрошенный пол; он держится только при `alphaStatus: "satisfied"`. Primary
|
|
186
|
+
остаётся солид-каноном, `-01` — тинтом, `-02` — опаковой базой. Численный
|
|
187
|
+
профиль явно фиксирует operation order:
|
|
188
|
+
`encoded-srgb-byte-scale-affine-platform-binary64-powf-v1`: original WCAG 2.1
|
|
189
|
+
(2018) split `0.03928`, conservative binary64 channel envelope и обе стороны
|
|
190
|
+
пересечённого EOTF seam. Bracket доступен только после directed-search guard;
|
|
191
|
+
это platform-characterization, а не двухугловая теорема, глобальная
|
|
192
|
+
монотонность, первый passing state или точная минимальная alpha.
|
|
193
|
+
- `NoneRole` — роль намеренно пустая по дизайну (`kind: "none"`), не ошибка.
|
|
194
|
+
- `UnreachableRole` — ни один цвет не удовлетворяет требованиям для этого фона (`kind: "unreachable"`).
|
|
195
|
+
|
|
196
|
+
Недостижимость отдельных ролей — **часть успешного результата**. Отклоняет весь вызов (как `Error`) только при невалидном аргументе:
|
|
197
|
+
|
|
198
|
+
| Код ошибки | Причина |
|
|
199
|
+
|------------|---------|
|
|
200
|
+
| `config_required` | конфиг ещё не загружен (`loadConfig` не вызывался) |
|
|
201
|
+
| `invalid_background` | `bgHex` не является `#RGB` или `#RRGGBB` |
|
|
202
|
+
| `unknown_theme` | `theme` не входит в список допустимых |
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
### `engine.loadConfig(json): string`
|
|
207
|
+
|
|
208
|
+
Загружает конфиг дизайн-системы (JSON по типу `ThemeConfig`; схема — в репозитории: `docs/decisions/0001-config-boundary.md`, TS-типы — в поставляемом `labcolors.d.ts`). Это **единственный** источник словаря ролей — встроенной таблицы в движке нет: до загрузки конфига `resolveTheme` отклоняется ошибкой `config_required`. Полный preflight проверяет не только имена ролей, но и итоговый CSS-namespace: `-core`/`-alpha` Glow и `-01`/`-02` Material не могут быть затёрты другой ролью или алиасом. Невалидный конфиг отклоняется структурной ошибкой `invalid_config: …` и НЕ меняет состояние. Возвращает отпечаток конфига — 16 hex-символов; разные конфиги дают разные отпечатки и разные кэш-пространства.
|
|
209
|
+
|
|
210
|
+
Каждый Glow-рецепт обязан явно выбрать numerical-decision profile; default и
|
|
211
|
+
неявного legacy-пути нет:
|
|
212
|
+
|
|
213
|
+
```json
|
|
214
|
+
{
|
|
215
|
+
"kind": "glow",
|
|
216
|
+
"source": { "kind": "brand" },
|
|
217
|
+
"step": "base",
|
|
218
|
+
"decision_profile": "stable-v1"
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
`stable-v1` возвращает typed `glow-indeterminate`, когда sound bound для
|
|
223
|
+
нетривиального CAM16 target/max-решения недоступен. Если существующая интеграция
|
|
224
|
+
обязана пока сохранить прежнюю CSS-эмиссию, укажите
|
|
225
|
+
`legacy-platform-dependent-v1` явно и обрабатывайте его как compatibility
|
|
226
|
+
profile, а не как численную гарантию. Полная миграция с rollback-порядком — в
|
|
227
|
+
[гайде exact alpha / typed Glow](https://github.com/Labpics-Team/lab-colors/blob/main/docs/migrations/exact-alpha-glow.md).
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
### `engine.recheckContrast(bgHex, fgHexes, theme): Float64Array`
|
|
232
|
+
|
|
233
|
+
Дешёвая покадровая проверка: какие контрасты дают цвета `fgHexes` на фоне `bgHex` под темой `theme`, без полного резолва (один прямой ход модели на фон плюс по одному на каждый передний план). Возвращает `Float64Array` пар `[lc, wcagRatio]` в порядке `fgHexes`: индекс `2·i` — знаковый `Lc` цвета `i`, `2·i+1` — его WCAG-отношение. Это примитив, которым `adaptTheme` решает, пора ли пересчитывать.
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
### `engine.recheckContrastMulti(bgHexes, fgHexes, theme): Float64Array`
|
|
238
|
+
|
|
239
|
+
Батч-вариант `recheckContrast` для меняющегося фона (градиент / картинка / bg-blur / стекло): проверяет один набор `fgHexes` сразу против НЕСКОЛЬКИХ сэмплов фона `bgHexes` за один вызов, разделяя прямой ход модели каждого переднего плана между всеми сэмплами (он от фона не зависит). Байт-в-байт равен N отдельным вызовам `recheckContrast`, пара за парой — это закреплено parity-тестом границы, — только быстрее: ~2.5× на 3 сэмплах. Возвращает плоский background-major `Float64Array`: сэмпл `s`, цвет `i` лежит в `(s · fgHexes.length + i) · 2` (`lc`) и `+1` (`wcagRatio`). Именно этим вызовом `adaptTheme` схлопывает worst-case цикл по сэмплам в одно обращение к движку; на одном сэмпле выигрыша нет — контроллер остаётся на `recheckContrast`.
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
### `engine.muddiness(hex): number`
|
|
244
|
+
|
|
245
|
+
`muddiness` возвращает замороженный числовой выход исторической формулы. Это
|
|
246
|
+
`experimental compatibility proxy`: legacy-имя сохранено для совместимости, но
|
|
247
|
+
значение не является валидированным на наблюдателях человеческим вердиктом
|
|
248
|
+
clean/dirty и не должно использоваться как production decision. Сам диапазон
|
|
249
|
+
`[0, 1]` — свойство формулы, а не шкала человеческого восприятия.
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
### `applyTheme(element, result): void`
|
|
254
|
+
|
|
255
|
+
Записывает все достижимые роли из `result.vars` в `element.style` через `setProperty`. Устаревшие `--lab-*` от предыдущего вызова сбрасываются перед записью — роль, потерявшая достижимость, не остаётся висеть.
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
### `watchTheme(element, options): WatchController`
|
|
260
|
+
|
|
261
|
+
Синхронизирует `--lab-*` переменные с фактическим фоном элемента. Применяет немедленно при создании и возвращает контроллер.
|
|
262
|
+
|
|
263
|
+
```ts
|
|
264
|
+
interface WatchThemeOptions {
|
|
265
|
+
colors: LabColors;
|
|
266
|
+
theme: ThemeName;
|
|
267
|
+
background?: string | (() => string); // явный фон (если автоматический невозможен)
|
|
268
|
+
target?: HTMLElement; // куда писать переменные (по умолчанию: element)
|
|
269
|
+
fallback?: string; // фон при полностью прозрачной цепочке (по умолчанию "#FFFFFF")
|
|
270
|
+
observe?: boolean; // авто-обновление при DOM-мутациях (по умолчанию true)
|
|
271
|
+
root?: Node; // корень MutationObserver (по умолчанию: documentElement)
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
interface WatchController {
|
|
275
|
+
refresh(force?: boolean): ResolvedTheme | null; // пересчитать и применить, если фон изменился
|
|
276
|
+
setTheme(theme: ThemeName): void; // переключить тему и применить
|
|
277
|
+
background(): string; // последний вычисленный фон (hex)
|
|
278
|
+
stop(): void; // отключить наблюдателей
|
|
279
|
+
}
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Для поверхности над изображением, градиентом или размытым фоном — где автоматическое вычисление невозможно — передайте явный `background` (hex-строку или функцию, возвращающую hex).
|
|
283
|
+
|
|
284
|
+
---
|
|
285
|
+
|
|
286
|
+
### `adaptTheme(element, options): AdaptController`
|
|
287
|
+
|
|
288
|
+
Режим с dwell-фильтром: дешёвая проверка каждый кадр, пересчёт и плавный переход только при устойчивом ухудшении контраста. Это один порог с выдержкой, не двухпороговый гистерезис. Применяет немедленно и возвращает контроллер.
|
|
289
|
+
|
|
290
|
+
```ts
|
|
291
|
+
interface AdaptThemeOptions {
|
|
292
|
+
colors: LabColors;
|
|
293
|
+
theme: ThemeName;
|
|
294
|
+
background?: string | string[] | (() => string | string[]);
|
|
295
|
+
// один hex или несколько образцов фона (наихудший учитывается)
|
|
296
|
+
target?: HTMLElement; // куда писать переменные (по умолчанию: element)
|
|
297
|
+
fallback?: string; // фон при прозрачной цепочке (по умолчанию "#FFFFFF")
|
|
298
|
+
dropFraction?: number; // запас контраста до пересчёта (по умолчанию 0.2)
|
|
299
|
+
sustainMs?: number; // минимальное время удержания нарушения (по умолчанию 120)
|
|
300
|
+
dwellMs?: number; // минимальный интервал между пересчётами (по умолчанию 250)
|
|
301
|
+
easeMs?: number; // длительность перехода (по умолчанию 280; уменьшается при reduced-motion)
|
|
302
|
+
strict?: boolean; // legacy characterized clamp; не universal floor certificate (по умолчанию false)
|
|
303
|
+
reducedMotion?: boolean; // переопределить системную настройку
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
interface AdaptController {
|
|
307
|
+
tick(now?: number): void; // один шаг (или использовать start())
|
|
308
|
+
setTheme(theme: ThemeName): void; // переключить тему мгновенно
|
|
309
|
+
start(): void; // запустить внутренний requestAnimationFrame-цикл
|
|
310
|
+
stop(): void; // остановить цикл
|
|
311
|
+
current(): Record<string, string>; // текущие применённые --lab-* переменные
|
|
312
|
+
}
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
`strict` сохраняет прежнее runtime-поведение, но не является доказательством
|
|
316
|
+
минимального или проходящего состояния на каждом кадре: путь
|
|
317
|
+
Oklab→gamut clip→sRGB8 немонотонен. Finite hard-floor-safe replacement ведётся в
|
|
318
|
+
#287; до него этот флаг следует считать compatibility characterization.
|
|
319
|
+
|
|
320
|
+
Управляйте через `start()` (внутренний rAF-цикл) или вызывайте `tick()` из собственного цикла. Смена темы применяется мгновенно — это осознанное намерение, а не дрейф.
|
|
321
|
+
Перед применением результата контроллер проверяет provenance как stable-, так и
|
|
322
|
+
legacy-ветвей Glow. Нетипизированный внешний mock с невозможным сочетанием
|
|
323
|
+
profile/guarantee/diagnostic/status отклоняется `TypeError`; fallback-цвет из
|
|
324
|
+
такого объекта не применяется.
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
### `effectiveBackground(element, options?): string`
|
|
329
|
+
|
|
330
|
+
Возвращает непрозрачный reference-`#RRGGBB`, вычисленный для поддерживаемого
|
|
331
|
+
подмножества DOM `background-color`. Это не browser pixel capture и не
|
|
332
|
+
сертификат цвета, который реально видит наблюдатель. Helper обходит цепочку
|
|
333
|
+
предков и композитит распознанные слои поверх `fallback` (по умолчанию белый).
|
|
334
|
+
|
|
335
|
+
```ts
|
|
336
|
+
const bg = effectiveBackground(panel); // например "#0F1014"
|
|
337
|
+
const bg2 = effectiveBackground(panel, { fallback: "#101012" });
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
**Честное ограничение:** работает только с поддерживаемыми сплошными и
|
|
341
|
+
полупрозрачными `background-color`; неподдерживаемый CSS, неполная прозрачная
|
|
342
|
+
цепочка, `background-image`, градиент, blur и video не дают полного наблюдения.
|
|
343
|
+
Текущий compatibility helper ещё может отбросить неподдерживаемый слой или
|
|
344
|
+
использовать fallback; для correctness передайте фон явно. Typed `Unknown`
|
|
345
|
+
replacement принадлежит #283.
|
|
346
|
+
|
|
347
|
+
Дополнительно экспортируются вспомогательные функции для работы со слоями: `parseCssColor`, `compositeOver`, `compositeStackToHex`, `toHex` и `oklabLerp` (перцептуально равномерная интерполяция между двумя hex-значениями — траектория цвета при переходе).
|
|
348
|
+
|
|
349
|
+
---
|
|
350
|
+
|
|
351
|
+
## Размер бандла
|
|
352
|
+
|
|
353
|
+
Размер не закреплён в документации приблизительным числом: оно устаревает при
|
|
354
|
+
любом изменении солвера. SSOT — шаг CI `report bundle size (gzip)` в `ci.yml`,
|
|
355
|
+
который для каждого коммита печатает точные raw-байты и результат `gzip -9`
|
|
356
|
+
отдельно для `labcolors_bg.wasm` и wasm-bindgen-обёртки `labcolors.js`.
|
|
357
|
+
|
|
358
|
+
Это весь движок: CAM16, солверы контраста, лестницы и граница конфига. `.wasm`
|
|
359
|
+
поставляется отдельным ассетом. Будет ли его загрузка критическим путём первого
|
|
360
|
+
рендера, определяет интеграция: до первого `resolveTheme` инициализация обязана
|
|
361
|
+
завершиться; приложение может preload/кэшировать модуль. JS-хелперы
|
|
362
|
+
(`applyTheme`, `watchTheme`, `adaptTheme`, `effectiveBackground`) имеют
|
|
363
|
+
именованные экспорты и допускают tree-shaking, но их размер также следует мерить
|
|
364
|
+
сборкой, а не описывать приблизительно.
|
|
365
|
+
|
|
366
|
+
Release packer закреплён на Node 24.14/npm 11.9; это не consumer floor.
|
|
367
|
+
Публичный контракт `Node >=22.11.0` независимо прогоняется отдельным CI job. Browser-
|
|
368
|
+
матрица использует прямую передачу wasm-байтов в `init({ module_or_path })` и
|
|
369
|
+
headless Chrome из CI. ESM/URL-обёртка генерируется wasm-pack, но совместимость
|
|
370
|
+
с конкретной версией Vite, webpack, Next или другим браузером не заявляется без
|
|
371
|
+
отдельного smoke-гейта.
|
|
372
|
+
|
|
373
|
+
### Для аудиторов цепочки поставки
|
|
374
|
+
|
|
375
|
+
- **Build metadata:** экспорт `@labpics/colors/build-metadata.json` декларирует
|
|
376
|
+
source SHA и conformance pack для установленного WASM; verifier отклоняет
|
|
377
|
+
любое лишнее, отсутствующее или несовпадающее поле. Объект не подписан и не
|
|
378
|
+
заменяет отключённую npm/Sigstore provenance-аттестацию.
|
|
379
|
+
- **Network access (Socket и др.):** единственный `fetch` в пакете (`pkg/labcolors.js`) загружает СОБСТВЕННЫЙ `.wasm`-файл пакета при `init(url)` — стандартный лоадер wasm-bindgen. Ни внешних адресов, ни отправки данных, ни исполнения при импорте. В node-пути (передача байтов) `fetch` не вызывается.
|
|
380
|
+
- **Bundlephobia `BuildError`:** их webpack-конвейер не умеет `.wasm`-ассеты («loader customization needed») — так падает почти любой WASM-пакет. Реальный размер конкретного коммита показывает CI-шаг `report bundle size (gzip)`.
|
|
381
|
+
- **Zero runtime JS-dependencies:** npm-поле `dependencies` пусто — транзитивной JS/npm-цепочки поставки нет. Rust-крейты сборки (`serde`, `serde_json` и др.) компилируются ВНУТРЬ `.wasm` (учтены CI-замером); их цепочка аудируется на стороне сборки — `cargo audit` (RustSec) в CI lab-colors.
|