@labpics/colors 0.8.0 → 0.9.1

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/README.md CHANGED
@@ -1,271 +1,282 @@
1
- # @labpics/colors
2
-
3
- Адаптивные цветовые роли для дизайн-системы. Получает фоновый цвет и тему — возвращает полный набор ролей (`--lab-label-primary`, `--lab-icon`, `--lab-border-base`, …). 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
- ```ts
30
- import init, { LabColors, applyTheme } from "@labpics/colors";
31
-
32
- await init(); // загрузить WASM-модуль (один раз)
33
- const engine = new LabColors(); // движок по умолчанию
34
-
35
- const result = engine.resolveTheme("#FFFFFF", "light");
36
- // result.vars → { "--lab-label-primary": "oklch(14.79140% 0.012878 284.717)",
37
- // "--lab-icon": "oklch(66.97448% 0.014606 285.999)", ... }
38
- // result.roles → детали каждой роли (css, hex, контраст, флаги)
39
-
40
- applyTheme(document.documentElement, result); // записать все --lab-* в элемент
41
- ```
42
-
43
- ### Реактивное отслеживание
44
-
45
- `watchTheme` синхронизирует переменные с фактическим фоном элемента автоматически.
46
-
47
- ```ts
48
- import init, { LabColors, watchTheme } from "@labpics/colors";
49
-
50
- await init();
51
- const colors = new LabColors();
52
-
53
- const panel = document.querySelector(".panel") as HTMLElement;
54
- const watcher = watchTheme(panel, { colors, theme: "light" });
55
- // panel теперь несёт правильные --lab-* для своего фона
56
-
57
- watcher.setTheme("dark"); // переключить тему
58
- watcher.refresh(); // принудительная пересинхронизация
59
- watcher.stop(); // отключить наблюдателя
60
- ```
61
-
62
- Поддерживает два режима изменений:
63
-
64
- - **Дискретные** (переключение темы, обновление класса, DOM-мутация) — отслеживаются `MutationObserver` автоматически.
65
- - **Непрерывные** (CSS-анимация, кадровый фон, который никогда не мутирует `inline style`) — управляются вручную через `refresh()` из собственного цикла `requestAnimationFrame`. `refresh()` дёшев: пересчитывает только при реальном изменении строки фона.
66
-
67
- ### Плавная адаптация к анимированному фону
68
-
69
- `watchTheme` пересчитывает весь набор при каждом изменении фона. Для фона, меняющегося **каждый кадр** (анимация, параллакс, размытый фон), `adaptTheme` — более элегантный вариант: проверяет дёшево каждый кадр, пересчитывает и плавно переходит к новым цветам только когда контраст реально ухудшается.
70
-
71
- ```ts
72
- import init, { LabColors, adaptTheme, effectiveBackground } from "@labpics/colors";
73
-
74
- await init();
75
- const colors = new LabColors();
76
-
77
- const surface = document.querySelector(".hero") as HTMLElement;
78
- const adaptive = adaptTheme(surface, {
79
- colors,
80
- theme: "light",
81
- background: () => effectiveBackground(surface, { fallback: "#101012" }),
82
- });
83
-
84
- adaptive.start(); // запустить внутренний requestAnimationFrame-цикл
85
- adaptive.setTheme("dark"); // смена темы применяется мгновенно
86
- adaptive.stop(); // остановить цикл
87
- ```
88
-
89
- Для фона с градиентом или изображением можно передать несколько образцов — цвета будут корректны для наиболее сложного из них:
90
-
91
- ```ts
92
- adaptTheme(hero, {
93
- colors,
94
- theme: "light",
95
- strict: true,
96
- background: () => sampleBackdrop(hero), // например ["#0B0B0E", "#3A3A40"]
97
- });
98
- ```
99
-
100
- ---
101
-
102
- ## Темы
103
-
104
- | Имя темы | Назначение |
105
- |----------|------------|
106
- | `"light"` | Светлая тема |
107
- | `"dark"` | Тёмная тема |
108
- | `"light-ic"` | Светлая с повышенным контрастом |
109
- | `"dark-ic"` | Тёмная с повышенным контрастом |
110
-
111
- ---
112
-
113
- ## Справочник публичного API
114
-
115
- ### `new LabColors()`
116
-
117
- Создаёт движок с таблицей ролей и условиями наблюдения по умолчанию. Повторные одинаковые вызовы `resolveTheme` обслуживаются из внутреннего кэша.
118
-
119
- ---
120
-
121
- ### `engine.resolveTheme(bgHex, theme): ResolvedTheme`
122
-
123
- - `bgHex` — фон в формате `#RGB` или `#RRGGBB`.
124
- - `theme` — `"light" | "dark" | "light-ic" | "dark-ic"`.
125
-
126
- Возвращает объект `ResolvedTheme`:
127
-
128
- ```ts
129
- interface ResolvedTheme {
130
- theme: ThemeName;
131
- background: string; // нормализованный #RRGGBB
132
- vars: Record<string, string>; // достижимые роли: "--lab-<ключ>" → готовое CSS-значение oklch
133
- roles: Record<string, RoleResult>; // все роли с деталями
134
- }
135
-
136
- type RoleResult = SolvedColor | TranslucentRole | NoneRole | UnreachableRole;
137
- ```
138
-
139
- Каждая роль — одно из четырёх состояний:
140
-
141
- - `SolvedColor` — цвет найден (`kind: "color"`, поля `css` — готовое `oklch(L% C H)`, `hex` — тот же цвет как данные, `lc`, `wcagRatio`, …).
142
- - `TranslucentRole` — полупрозрачная роль лестницы или альфа-аналога (`kind: "translucent"`): `css` — готовое `oklch(L% C H / A)`, `tintHex` — тинт как данные, `alpha`, плюс `compositeHex` / `compositeLc` / `compositeWcag` — солид-композит на фоне резолва и его контраст (браузер композитит тинт на живой подложке).
143
- - `NoneRole` — роль намеренно пустая по дизайну (`kind: "none"`), не ошибка.
144
- - `UnreachableRole` — ни один цвет не удовлетворяет требованиям для этого фона (`kind: "unreachable"`).
145
-
146
- Недостижимость отдельных ролей — **часть успешного результата**. Отклоняет весь вызов (как `Error`) только при невалидном аргументе:
147
-
148
- | Код ошибки | Причина |
149
- |------------|---------|
150
- | `invalid_background` | `bgHex` не является `#RGB` или `#RRGGBB` |
151
- | `unknown_theme` | `theme` не входит в список допустимых |
152
-
153
- ---
154
-
155
- ### `engine.loadConfig(json): string`
156
-
157
- Загружает конфиг дизайн-системы (JSON по типу `ThemeConfig`) — главная фича конфиг-границы: движок начинает эмитить роли и подтон конфига вместо встроенной таблицы. Полный preflight: невалидный конфиг отклоняется структурной ошибкой `invalid_config: …` и НЕ меняет состояние. Возвращает отпечаток конфига — 16 hex-символов; разные конфиги дают разные отпечатки и разные кэш-пространства.
158
-
159
- ---
160
-
161
- ### `engine.recheckContrast(bgHex, fgHexes, theme): Float64Array`
162
-
163
- Дешёвая покадровая проверка: какие контрасты дают цвета `fgHexes` на фоне `bgHex` под темой `theme`, без полного резолва (один прямой ход модели на фон плюс по одному на каждый передний план). Возвращает `Float64Array` пар `[lc, wcagRatio]` в порядке `fgHexes`: индекс `2·i` — знаковый `Lc` цвета `i`, `2·i+1` — его WCAG-отношение. Это примитив, которым `adaptTheme` решает, пора ли пересчитывать.
164
-
165
- ---
166
-
167
- ### `engine.muddiness(hex): number` · `engine.confidence(hex): number`
168
-
169
- `muddiness` — оценка «грязи» цвета `hex` в диапазоне `[0, 1]` (Закон Грязи). `confidence` — надёжность этой оценки: `0` означает, что оценке нельзя доверять (у границы решения или серого фронтира), выше — увереннее. Верхний потолок — деталь калибровки, не контракт: не хардкодить.
170
-
171
- ---
172
-
173
- ### `applyTheme(element, result): void`
174
-
175
- Записывает все достижимые роли из `result.vars` в `element.style` через `setProperty`. Устаревшие `--lab-*` от предыдущего вызова сбрасываются перед записью — роль, потерявшая достижимость, не остаётся висеть.
176
-
177
- ---
178
-
179
- ### `watchTheme(element, options): WatchController`
180
-
181
- Синхронизирует `--lab-*` переменные с фактическим фоном элемента. Применяет немедленно при создании и возвращает контроллер.
182
-
183
- ```ts
184
- interface WatchThemeOptions {
185
- colors: LabColors;
186
- theme: ThemeName;
187
- background?: string | (() => string); // явный фон (если автоматический невозможен)
188
- target?: HTMLElement; // куда писать переменные (по умолчанию: element)
189
- fallback?: string; // фон при полностью прозрачной цепочке (по умолчанию "#FFFFFF")
190
- observe?: boolean; // авто-обновление при DOM-мутациях (по умолчанию true)
191
- root?: Node; // корень MutationObserver (по умолчанию: documentElement)
192
- }
193
-
194
- interface WatchController {
195
- refresh(force?: boolean): ResolvedTheme | null; // пересчитать и применить, если фон изменился
196
- setTheme(theme: ThemeName): void; // переключить тему и применить
197
- background(): string; // последний вычисленный фон (hex)
198
- stop(): void; // отключить наблюдателей
199
- }
200
- ```
201
-
202
- Для поверхности над изображением, градиентом или размытым фоном — где автоматическое вычисление невозможно — передайте явный `background` (hex-строку или функцию, возвращающую hex).
203
-
204
- ---
205
-
206
- ### `adaptTheme(element, options): AdaptController`
207
-
208
- Режим с гистерезисом: дешёвая проверка каждый кадр, пересчёт и плавный переход только при устойчивом ухудшении контраста. Применяет немедленно и возвращает контроллер.
209
-
210
- ```ts
211
- interface AdaptThemeOptions {
212
- colors: LabColors;
213
- theme: ThemeName;
214
- background?: string | string[] | (() => string | string[]);
215
- // один hex или несколько образцов фона (наихудший учитывается)
216
- target?: HTMLElement; // куда писать переменные (по умолчанию: element)
217
- fallback?: string; // фон при прозрачной цепочке (по умолчанию "#FFFFFF")
218
- dropFraction?: number; // запас контраста до пересчёта (по умолчанию 0.2)
219
- sustainMs?: number; // минимальное время удержания нарушения (по умолчанию 120)
220
- dwellMs?: number; // минимальный интервал между пересчётами (по умолчанию 250)
221
- easeMs?: number; // длительность перехода (по умолчанию 280; уменьшается при reduced-motion)
222
- strict?: boolean; // держать минимальный контраст на каждом кадре перехода (по умолчанию false)
223
- reducedMotion?: boolean; // переопределить системную настройку
224
- }
225
-
226
- interface AdaptController {
227
- tick(now?: number): void; // один шаг (или использовать start())
228
- setTheme(theme: ThemeName): void; // переключить тему мгновенно
229
- start(): void; // запустить внутренний requestAnimationFrame-цикл
230
- stop(): void; // остановить цикл
231
- current(): Record<string, string>; // текущие применённые --lab-* переменные
232
- }
233
- ```
234
-
235
- Управляйте через `start()` (внутренний rAF-цикл) или вызывайте `tick()` из собственного цикла. Смена темы применяется мгновенно — это осознанное намерение, а не дрейф.
236
-
237
- ---
238
-
239
- ### `effectiveBackground(element, options?): string`
240
-
241
- Возвращает непрозрачный `#RRGGBB` — цвет, который наблюдатель реально видит за содержимым `element`. Обходит цепочку предков и выполняет альфа-композитинг каждого `background-color` до получения непрозрачного результата, поверх `fallback` (по умолчанию белый).
242
-
243
- ```ts
244
- const bg = effectiveBackground(panel); // например "#0F1014"
245
- const bg2 = effectiveBackground(panel, { fallback: "#101012" });
246
- ```
247
-
248
- **Честное ограничение:** работает только с сплошными и полупрозрачными `background-color` — не с `background-image`, градиентами, размытым фоном или видео. Для таких поверхностей передайте фон явно.
249
-
250
- Дополнительно экспортируются вспомогательные функции для работы со слоями: `parseCssColor`, `compositeOver`, `compositeStackToHex`, `toHex` и `oklabLerp` (перцептуально равномерная интерполяция между двумя hex-значениями — траектория цвета при переходе).
251
-
252
- ---
253
-
254
- ## Размер бандла
255
-
256
- | Артефакт | raw | gzip |
257
- |----------|-----|------|
258
- | `labcolors_bg.wasm` | ~313 КБ | ~138 КБ |
259
- | `labcolors.js` (JS-обёртка) | ~17 КБ | ~4 КБ |
260
-
261
- Замер CI-шага `report bundle size` (ci.yml) — raw и gzip.
262
-
263
- Это ВЕСЬ движок: перцептивная модель CAM16, солверы контраста, лестницы, граница конфига. `.wasm` — не JS-байты бандла, а ассет: он **не на критическом пути рендера** — грузится параллельно, компилируется потоково вне главного треда, кэшируется браузером после первой загрузки. Вспомогательные функции (`applyTheme`, `watchTheme`, `adaptTheme`, `effectiveBackground`) — несколько сотен байт чистого JavaScript с tree-shaking через именованные экспорты.
264
-
265
- Требует современных браузеров (2023+): сборщики Vite / webpack 5 / Next штатно понимают `new URL('….wasm', import.meta.url)` (вывод wasm-pack). В node передавайте wasm-байты напрямую в `init({ module_or_path })`.
266
-
267
- ### Для аудиторов цепочки поставки
268
-
269
- - **Network access (Socket и др.):** единственный `fetch` в пакете (`pkg/labcolors.js`) загружает СОБСТВЕННЫЙ `.wasm`-файл пакета при `init(url)` — стандартный лоадер wasm-bindgen. Ни внешних адресов, ни отправки данных, ни исполнения при импорте. В node-пути (передача байтов) `fetch` не вызывается.
270
- - **Bundlephobia `BuildError`:** их webpack-конвейер не умеет `.wasm`-ассеты («loader customization needed») — так падает почти любой WASM-пакет. Реальные размеры — в таблице выше (замер CI-шага `report bundle size`).
271
- - **Zero runtime JS-dependencies:** npm-поле `dependencies` пусто — транзитивной JS/npm-цепочки поставки нет. Rust-крейты сборки (`serde`, `serde_json` и др.) компилируются ВНУТРЬ `.wasm` (учтены в его размере выше); их цепочка аудируется на стороне сборки — `cargo audit` (RustSec) в CI lab-colors.
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
+ ```ts
30
+ import init, { LabColors, applyTheme } from "@labpics/colors";
31
+ import dsConfig from "./theme.config.json"; // паспорт вашей дизайн-системы (ThemeConfig)
32
+
33
+ await init(); // загрузить WASM-модуль (один раз)
34
+ const engine = new LabColors(); // пустой движок: словаря ролей ещё нет
35
+ engine.loadConfig(JSON.stringify(dsConfig)); // без этого шага resolveTheme отклонится: config_required
36
+
37
+ const result = engine.resolveTheme("#FFFFFF", "light");
38
+ // result.vars → готовые CSS-значения по ролям ВАШЕГО конфига:
39
+ // { "--lab-label-primary": "oklch(<L>% <C> <H>)", … }
40
+ // result.roles → детали каждой роли (css, hex, контраст, флаги)
41
+
42
+ applyTheme(document.documentElement, result); // записать все --lab-* в элемент
43
+ ```
44
+
45
+ ### Реактивное отслеживание
46
+
47
+ `watchTheme` синхронизирует переменные с фактическим фоном элемента автоматически.
48
+
49
+ ```ts
50
+ import init, { LabColors, watchTheme } from "@labpics/colors";
51
+
52
+ await init();
53
+ const colors = new LabColors();
54
+ colors.loadConfig(JSON.stringify(dsConfig)); // конфиг дизайн-системы (см. квик-старт)
55
+
56
+ const panel = document.querySelector(".panel") as HTMLElement;
57
+ const watcher = watchTheme(panel, { colors, theme: "light" });
58
+ // panel теперь несёт правильные --lab-* для своего фона
59
+
60
+ watcher.setTheme("dark"); // переключить тему
61
+ watcher.refresh(); // принудительная пересинхронизация
62
+ watcher.stop(); // отключить наблюдателя
63
+ ```
64
+
65
+ Поддерживает два режима изменений:
66
+
67
+ - **Дискретные** (переключение темы, обновление класса, DOM-мутация) — отслеживаются `MutationObserver` автоматически.
68
+ - **Непрерывные** (CSS-анимация, кадровый фон, который никогда не мутирует `inline style`) — управляются вручную через `refresh()` из собственного цикла `requestAnimationFrame`. `refresh()` дёшев: пересчитывает только при реальном изменении строки фона.
69
+
70
+ ### Плавная адаптация к анимированному фону
71
+
72
+ `watchTheme` пересчитывает весь набор при каждом изменении фона. Для фона, меняющегося **каждый кадр** (анимация, параллакс, размытый фон), `adaptTheme` — более элегантный вариант: проверяет дёшево каждый кадр, пересчитывает и плавно переходит к новым цветам только когда контраст реально ухудшается.
73
+
74
+ ```ts
75
+ import init, { LabColors, adaptTheme, effectiveBackground } from "@labpics/colors";
76
+
77
+ await init();
78
+ const colors = new LabColors();
79
+ colors.loadConfig(JSON.stringify(dsConfig)); // конфиг дизайн-системы (см. квик-старт)
80
+
81
+ const surface = document.querySelector(".hero") as HTMLElement;
82
+ const adaptive = adaptTheme(surface, {
83
+ colors,
84
+ theme: "light",
85
+ background: () => effectiveBackground(surface, { fallback: "#101012" }),
86
+ });
87
+
88
+ adaptive.start(); // запустить внутренний requestAnimationFrame-цикл
89
+ adaptive.setTheme("dark"); // смена темы применяется мгновенно
90
+ adaptive.stop(); // остановить цикл
91
+ ```
92
+
93
+ Для фона с градиентом или изображением можно передать несколько образцов — цвета будут корректны для наиболее сложного из них:
94
+
95
+ ```ts
96
+ adaptTheme(hero, {
97
+ colors,
98
+ theme: "light",
99
+ strict: true,
100
+ background: () => sampleBackdrop(hero), // например ["#0B0B0E", "#3A3A40"]
101
+ });
102
+ ```
103
+
104
+ ---
105
+
106
+ ## Темы
107
+
108
+ | Имя темы | Назначение |
109
+ |----------|------------|
110
+ | `"light"` | Светлая тема |
111
+ | `"dark"` | Тёмная тема |
112
+ | `"light-ic"` | Светлая с повышенным контрастом |
113
+ | `"dark-ic"` | Тёмная с повышенным контрастом |
114
+
115
+ ---
116
+
117
+ ## Справочник публичного API
118
+
119
+ ### `new LabColors()`
120
+
121
+ Создаёт движок **без** словаря ролей: до `loadConfig` любой вызов `resolveTheme` отклоняется ошибкой `config_required`. Повторные одинаковые вызовы `resolveTheme` обслуживаются из внутреннего кэша (кэш-пространство привязано к отпечатку конфига).
122
+
123
+ ---
124
+
125
+ ### `engine.resolveTheme(bgHex, theme): ResolvedTheme`
126
+
127
+ - `bgHex` — фон в формате `#RGB` или `#RRGGBB`.
128
+ - `theme` — `"light" | "dark" | "light-ic" | "dark-ic"`.
129
+
130
+ Возвращает объект `ResolvedTheme`:
131
+
132
+ ```ts
133
+ interface ResolvedTheme {
134
+ theme: ThemeName;
135
+ background: string; // нормализованный #RRGGBB
136
+ vars: Record<string, string>; // достижимые роли: "--lab-<ключ>" → готовое CSS-значение oklch
137
+ roles: Record<string, RoleResult>; // все роли с деталями
138
+ }
139
+
140
+ type RoleResult = SolvedColor | TranslucentRole | NoneRole | UnreachableRole;
141
+ ```
142
+
143
+ Каждая роль — одно из четырёх состояний:
144
+
145
+ - `SolvedColor` — цвет найден (`kind: "color"`, поля `css` — готовое `oklch(L% C H)`, `hex` — тот же цвет как данные, `lc`, `wcagRatio`, …).
146
+ - `TranslucentRole` — полупрозрачная роль лестницы или альфа-аналога (`kind: "translucent"`): `css` — готовое `oklch(L% C H / A)`, `tintHex` — тинт как данные, `alpha`, плюс `compositeHex` / `compositeLc` / `compositeWcag` — солид-композит на фоне резолва и его контраст (браузер композитит тинт на живой подложке).
147
+ - `NoneRole` — роль намеренно пустая по дизайну (`kind: "none"`), не ошибка.
148
+ - `UnreachableRole` — ни один цвет не удовлетворяет требованиям для этого фона (`kind: "unreachable"`).
149
+
150
+ Недостижимость отдельных ролей — **часть успешного результата**. Отклоняет весь вызов (как `Error`) только при невалидном аргументе:
151
+
152
+ | Код ошибки | Причина |
153
+ |------------|---------|
154
+ | `config_required` | конфиг ещё не загружен (`loadConfig` не вызывался) |
155
+ | `invalid_background` | `bgHex` не является `#RGB` или `#RRGGBB` |
156
+ | `unknown_theme` | `theme` не входит в список допустимых |
157
+
158
+ ---
159
+
160
+ ### `engine.loadConfig(json): string`
161
+
162
+ Загружает конфиг дизайн-системы (JSON по типу `ThemeConfig`; схема — в репозитории: `docs/decisions/0001-config-boundary.md`, TS-типы — в поставляемом `labcolors.d.ts`). Это **единственный** источник словаря ролей — встроенной таблицы в движке нет: до загрузки конфига `resolveTheme` отклоняется ошибкой `config_required`. Полный preflight: невалидный конфиг отклоняется структурной ошибкой `invalid_config: …` и НЕ меняет состояние. Возвращает отпечаток конфига — 16 hex-символов; разные конфиги дают разные отпечатки и разные кэш-пространства.
163
+
164
+ ---
165
+
166
+ ### `engine.recheckContrast(bgHex, fgHexes, theme): Float64Array`
167
+
168
+ Дешёвая покадровая проверка: какие контрасты дают цвета `fgHexes` на фоне `bgHex` под темой `theme`, без полного резолва (один прямой ход модели на фон плюс по одному на каждый передний план). Возвращает `Float64Array` пар `[lc, wcagRatio]` в порядке `fgHexes`: индекс `2·i` — знаковый `Lc` цвета `i`, `2·i+1` — его WCAG-отношение. Это примитив, которым `adaptTheme` решает, пора ли пересчитывать.
169
+
170
+ ---
171
+
172
+ ### `engine.recheckContrastMulti(bgHexes, fgHexes, theme): Float64Array`
173
+
174
+ Батч-вариант `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`.
175
+
176
+ ---
177
+
178
+ ### `engine.muddiness(hex): number` · `engine.confidence(hex): number`
179
+
180
+ `muddiness` — оценка «грязи» цвета `hex` в диапазоне `[0, 1]` (Закон Грязи). `confidence` — надёжность этой оценки: `0` означает, что оценке нельзя доверять (у границы решения или серого фронтира), выше — увереннее. Верхний потолок — деталь калибровки, не контракт: не хардкодить.
181
+
182
+ ---
183
+
184
+ ### `applyTheme(element, result): void`
185
+
186
+ Записывает все достижимые роли из `result.vars` в `element.style` через `setProperty`. Устаревшие `--lab-*` от предыдущего вызова сбрасываются перед записью — роль, потерявшая достижимость, не остаётся висеть.
187
+
188
+ ---
189
+
190
+ ### `watchTheme(element, options): WatchController`
191
+
192
+ Синхронизирует `--lab-*` переменные с фактическим фоном элемента. Применяет немедленно при создании и возвращает контроллер.
193
+
194
+ ```ts
195
+ interface WatchThemeOptions {
196
+ colors: LabColors;
197
+ theme: ThemeName;
198
+ background?: string | (() => string); // явный фон (если автоматический невозможен)
199
+ target?: HTMLElement; // куда писать переменные (по умолчанию: element)
200
+ fallback?: string; // фон при полностью прозрачной цепочке (по умолчанию "#FFFFFF")
201
+ observe?: boolean; // авто-обновление при DOM-мутациях (по умолчанию true)
202
+ root?: Node; // корень MutationObserver (по умолчанию: documentElement)
203
+ }
204
+
205
+ interface WatchController {
206
+ refresh(force?: boolean): ResolvedTheme | null; // пересчитать и применить, если фон изменился
207
+ setTheme(theme: ThemeName): void; // переключить тему и применить
208
+ background(): string; // последний вычисленный фон (hex)
209
+ stop(): void; // отключить наблюдателей
210
+ }
211
+ ```
212
+
213
+ Для поверхности над изображением, градиентом или размытым фоном — где автоматическое вычисление невозможно — передайте явный `background` (hex-строку или функцию, возвращающую hex).
214
+
215
+ ---
216
+
217
+ ### `adaptTheme(element, options): AdaptController`
218
+
219
+ Режим с гистерезисом: дешёвая проверка каждый кадр, пересчёт и плавный переход только при устойчивом ухудшении контраста. Применяет немедленно и возвращает контроллер.
220
+
221
+ ```ts
222
+ interface AdaptThemeOptions {
223
+ colors: LabColors;
224
+ theme: ThemeName;
225
+ background?: string | string[] | (() => string | string[]);
226
+ // один hex или несколько образцов фона (наихудший учитывается)
227
+ target?: HTMLElement; // куда писать переменные (по умолчанию: element)
228
+ fallback?: string; // фон при прозрачной цепочке (по умолчанию "#FFFFFF")
229
+ dropFraction?: number; // запас контраста до пересчёта (по умолчанию 0.2)
230
+ sustainMs?: number; // минимальное время удержания нарушения (по умолчанию 120)
231
+ dwellMs?: number; // минимальный интервал между пересчётами (по умолчанию 250)
232
+ easeMs?: number; // длительность перехода (по умолчанию 280; уменьшается при reduced-motion)
233
+ strict?: boolean; // держать минимальный контраст на каждом кадре перехода (по умолчанию false)
234
+ reducedMotion?: boolean; // переопределить системную настройку
235
+ }
236
+
237
+ interface AdaptController {
238
+ tick(now?: number): void; // один шаг (или использовать start())
239
+ setTheme(theme: ThemeName): void; // переключить тему мгновенно
240
+ start(): void; // запустить внутренний requestAnimationFrame-цикл
241
+ stop(): void; // остановить цикл
242
+ current(): Record<string, string>; // текущие применённые --lab-* переменные
243
+ }
244
+ ```
245
+
246
+ Управляйте через `start()` (внутренний rAF-цикл) или вызывайте `tick()` из собственного цикла. Смена темы применяется мгновенно — это осознанное намерение, а не дрейф.
247
+
248
+ ---
249
+
250
+ ### `effectiveBackground(element, options?): string`
251
+
252
+ Возвращает непрозрачный `#RRGGBB` — цвет, который наблюдатель реально видит за содержимым `element`. Обходит цепочку предков и выполняет альфа-композитинг каждого `background-color` до получения непрозрачного результата, поверх `fallback` (по умолчанию белый).
253
+
254
+ ```ts
255
+ const bg = effectiveBackground(panel); // например "#0F1014"
256
+ const bg2 = effectiveBackground(panel, { fallback: "#101012" });
257
+ ```
258
+
259
+ **Честное ограничение:** работает только с сплошными и полупрозрачными `background-color` — не с `background-image`, градиентами, размытым фоном или видео. Для таких поверхностей передайте фон явно.
260
+
261
+ Дополнительно экспортируются вспомогательные функции для работы со слоями: `parseCssColor`, `compositeOver`, `compositeStackToHex`, `toHex` и `oklabLerp` (перцептуально равномерная интерполяция между двумя hex-значениями — траектория цвета при переходе).
262
+
263
+ ---
264
+
265
+ ## Размер бандла
266
+
267
+ | Артефакт | raw | gzip |
268
+ |----------|-----|------|
269
+ | `labcolors_bg.wasm` | ~313 КБ | ~138 КБ |
270
+ | `labcolors.js` (JS-обёртка) | ~17 КБ | ~4 КБ |
271
+
272
+ Замер CI-шага `report bundle size` (ci.yml) — raw и gzip.
273
+
274
+ Это ВЕСЬ движок: перцептивная модель CAM16, солверы контраста, лестницы, граница конфига. `.wasm` — не JS-байты бандла, а ассет: он **не на критическом пути рендера** — грузится параллельно, компилируется потоково вне главного треда, кэшируется браузером после первой загрузки. Вспомогательные функции (`applyTheme`, `watchTheme`, `adaptTheme`, `effectiveBackground`) — несколько сотен байт чистого JavaScript с tree-shaking через именованные экспорты.
275
+
276
+ Требует современных браузеров (2023+): сборщики Vite / webpack 5 / Next штатно понимают `new URL('….wasm', import.meta.url)` (вывод wasm-pack). В node передавайте wasm-байты напрямую в `init({ module_or_path })`.
277
+
278
+ ### Для аудиторов цепочки поставки
279
+
280
+ - **Network access (Socket и др.):** единственный `fetch` в пакете (`pkg/labcolors.js`) загружает СОБСТВЕННЫЙ `.wasm`-файл пакета при `init(url)` — стандартный лоадер wasm-bindgen. Ни внешних адресов, ни отправки данных, ни исполнения при импорте. В node-пути (передача байтов) `fetch` не вызывается.
281
+ - **Bundlephobia `BuildError`:** их webpack-конвейер не умеет `.wasm`-ассеты («loader customization needed») — так падает почти любой WASM-пакет. Реальные размеры — в таблице выше (замер CI-шага `report bundle size`).
282
+ - **Zero runtime JS-dependencies:** npm-поле `dependencies` пусто — транзитивной JS/npm-цепочки поставки нет. Rust-крейты сборки (`serde`, `serde_json` и др.) компилируются ВНУТРЬ `.wasm` (учтены в его размере выше); их цепочка аудируется на стороне сборки — `cargo audit` (RustSec) в CI lab-colors.