@labpics/colors 0.9.0 → 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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Lab Pics
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -20,6 +20,14 @@ npm install @labpics/colors
20
20
  npm run build # → pkg/ (wasm + JS-обёртка + .d.ts)
21
21
  ```
22
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
+
23
31
  ---
24
32
 
25
33
  ## Как использовать
@@ -137,13 +145,51 @@ interface ResolvedTheme {
137
145
  roles: Record<string, RoleResult>; // все роли с деталями
138
146
  }
139
147
 
140
- type RoleResult = SolvedColor | TranslucentRole | NoneRole | UnreachableRole;
148
+ type RoleResult =
149
+ | SolvedColor
150
+ | TranslucentRole
151
+ | GlowRole
152
+ | MaterialRole
153
+ | NoneRole
154
+ | UnreachableRole;
141
155
  ```
142
156
 
143
- Каждая роль — одно из четырёх состояний:
157
+ Каждая роль — одна из шести категорий результата; у Glow есть два терминальных
158
+ состояния:
144
159
 
145
160
  - `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` — солид-композит на фоне резолва и его контраст (браузер композитит тинт на живой подложке).
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.
147
193
  - `NoneRole` — роль намеренно пустая по дизайну (`kind: "none"`), не ошибка.
148
194
  - `UnreachableRole` — ни один цвет не удовлетворяет требованиям для этого фона (`kind: "unreachable"`).
149
195
 
@@ -159,7 +205,26 @@ type RoleResult = SolvedColor | TranslucentRole | NoneRole | UnreachableRole;
159
205
 
160
206
  ### `engine.loadConfig(json): string`
161
207
 
162
- Загружает конфиг дизайн-системы (JSON по типу `ThemeConfig`; схема — в репозитории: `docs/decisions/0001-config-boundary.md`, TS-типы — в поставляемом `labcolors.d.ts`). Это **единственный** источник словаря ролей — встроенной таблицы в движке нет: до загрузки конфига `resolveTheme` отклоняется ошибкой `config_required`. Полный preflight: невалидный конфиг отклоняется структурной ошибкой `invalid_config: …` и НЕ меняет состояние. Возвращает отпечаток конфига — 16 hex-символов; разные конфиги дают разные отпечатки и разные кэш-пространства.
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).
163
228
 
164
229
  ---
165
230
 
@@ -175,9 +240,13 @@ type RoleResult = SolvedColor | TranslucentRole | NoneRole | UnreachableRole;
175
240
 
176
241
  ---
177
242
 
178
- ### `engine.muddiness(hex): number` · `engine.confidence(hex): number`
243
+ ### `engine.muddiness(hex): number`
179
244
 
180
- `muddiness` — оценка «грязи» цвета `hex` в диапазоне `[0, 1]` (Закон Грязи). `confidence` — надёжность этой оценки: `0` означает, что оценке нельзя доверять (у границы решения или серого фронтира), выше — увереннее. Верхний потолок — деталь калибровки, не контракт: не хардкодить.
245
+ `muddiness` возвращает замороженный числовой выход исторической формулы. Это
246
+ `experimental compatibility proxy`: legacy-имя сохранено для совместимости, но
247
+ значение не является валидированным на наблюдателях человеческим вердиктом
248
+ clean/dirty и не должно использоваться как production decision. Сам диапазон
249
+ `[0, 1]` — свойство формулы, а не шкала человеческого восприятия.
181
250
 
182
251
  ---
183
252
 
@@ -216,7 +285,7 @@ interface WatchController {
216
285
 
217
286
  ### `adaptTheme(element, options): AdaptController`
218
287
 
219
- Режим с гистерезисом: дешёвая проверка каждый кадр, пересчёт и плавный переход только при устойчивом ухудшении контраста. Применяет немедленно и возвращает контроллер.
288
+ Режим с dwell-фильтром: дешёвая проверка каждый кадр, пересчёт и плавный переход только при устойчивом ухудшении контраста. Это один порог с выдержкой, не двухпороговый гистерезис. Применяет немедленно и возвращает контроллер.
220
289
 
221
290
  ```ts
222
291
  interface AdaptThemeOptions {
@@ -230,7 +299,7 @@ interface AdaptThemeOptions {
230
299
  sustainMs?: number; // минимальное время удержания нарушения (по умолчанию 120)
231
300
  dwellMs?: number; // минимальный интервал между пересчётами (по умолчанию 250)
232
301
  easeMs?: number; // длительность перехода (по умолчанию 280; уменьшается при reduced-motion)
233
- strict?: boolean; // держать минимальный контраст на каждом кадре перехода (по умолчанию false)
302
+ strict?: boolean; // legacy characterized clamp; не universal floor certificate (по умолчанию false)
234
303
  reducedMotion?: boolean; // переопределить системную настройку
235
304
  }
236
305
 
@@ -243,20 +312,37 @@ interface AdaptController {
243
312
  }
244
313
  ```
245
314
 
315
+ `strict` сохраняет прежнее runtime-поведение, но не является доказательством
316
+ минимального или проходящего состояния на каждом кадре: путь
317
+ Oklab→gamut clip→sRGB8 немонотонен. Finite hard-floor-safe replacement ведётся в
318
+ #287; до него этот флаг следует считать compatibility characterization.
319
+
246
320
  Управляйте через `start()` (внутренний rAF-цикл) или вызывайте `tick()` из собственного цикла. Смена темы применяется мгновенно — это осознанное намерение, а не дрейф.
321
+ Перед применением результата контроллер проверяет provenance как stable-, так и
322
+ legacy-ветвей Glow. Нетипизированный внешний mock с невозможным сочетанием
323
+ profile/guarantee/diagnostic/status отклоняется `TypeError`; fallback-цвет из
324
+ такого объекта не применяется.
247
325
 
248
326
  ---
249
327
 
250
328
  ### `effectiveBackground(element, options?): string`
251
329
 
252
- Возвращает непрозрачный `#RRGGBB` — цвет, который наблюдатель реально видит за содержимым `element`. Обходит цепочку предков и выполняет альфа-композитинг каждого `background-color` до получения непрозрачного результата, поверх `fallback` (по умолчанию белый).
330
+ Возвращает непрозрачный reference-`#RRGGBB`, вычисленный для поддерживаемого
331
+ подмножества DOM `background-color`. Это не browser pixel capture и не
332
+ сертификат цвета, который реально видит наблюдатель. Helper обходит цепочку
333
+ предков и композитит распознанные слои поверх `fallback` (по умолчанию белый).
253
334
 
254
335
  ```ts
255
336
  const bg = effectiveBackground(panel); // например "#0F1014"
256
337
  const bg2 = effectiveBackground(panel, { fallback: "#101012" });
257
338
  ```
258
339
 
259
- **Честное ограничение:** работает только с сплошными и полупрозрачными `background-color` — не с `background-image`, градиентами, размытым фоном или видео. Для таких поверхностей передайте фон явно.
340
+ **Честное ограничение:** работает только с поддерживаемыми сплошными и
341
+ полупрозрачными `background-color`; неподдерживаемый CSS, неполная прозрачная
342
+ цепочка, `background-image`, градиент, blur и video не дают полного наблюдения.
343
+ Текущий compatibility helper ещё может отбросить неподдерживаемый слой или
344
+ использовать fallback; для correctness передайте фон явно. Typed `Unknown`
345
+ replacement принадлежит #283.
260
346
 
261
347
  Дополнительно экспортируются вспомогательные функции для работы со слоями: `parseCssColor`, `compositeOver`, `compositeStackToHex`, `toHex` и `oklabLerp` (перцептуально равномерная интерполяция между двумя hex-значениями — траектория цвета при переходе).
262
348
 
@@ -264,19 +350,32 @@ const bg2 = effectiveBackground(panel, { fallback: "#101012" });
264
350
 
265
351
  ## Размер бандла
266
352
 
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 })`.
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-гейта.
277
372
 
278
373
  ### Для аудиторов цепочки поставки
279
374
 
375
+ - **Build metadata:** экспорт `@labpics/colors/build-metadata.json` декларирует
376
+ source SHA и conformance pack для установленного WASM; verifier отклоняет
377
+ любое лишнее, отсутствующее или несовпадающее поле. Объект не подписан и не
378
+ заменяет отключённую npm/Sigstore provenance-аттестацию.
280
379
  - **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.
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.
package/adapt-theme.d.ts CHANGED
@@ -4,14 +4,16 @@ import type { LabColors, ThemeName } from "./pkg/labcolors.js";
4
4
 
5
5
  export interface AdaptThemeOptions {
6
6
  /**
7
- * An initialised engine — needs `resolveTheme` AND `recheckContrast`.
7
+ * An initialised engine — needs resolve + contrast recheck. The exact
8
+ * `isStableGlowPointNoop` capability is conditionally required when a result
9
+ * contains a stable Glow role; its absence then fails explicitly.
8
10
  * `recheckContrastMulti` is optional: when present, a multi-sample backdrop
9
11
  * is rechecked in ONE batched call per frame (byte-identical to the
10
12
  * per-sample loop, locked by the wasm boundary parity test); when absent,
11
13
  * the controller falls back to N `recheckContrast` calls.
12
14
  */
13
15
  colors: Pick<LabColors, "resolveTheme" | "recheckContrast"> &
14
- Partial<Pick<LabColors, "recheckContrastMulti">>;
16
+ Partial<Pick<LabColors, "recheckContrastMulti" | "isStableGlowPointNoop">>;
15
17
  theme: ThemeName;
16
18
  /**
17
19
  * Explicit effective background, overriding the ancestor-composite. A single
@@ -34,10 +36,10 @@ export interface AdaptThemeOptions {
34
36
  /** Crossfade duration in ms. Default `280` (capped to a short fade under reduced motion). */
35
37
  easeMs?: number;
36
38
  /**
37
- * Hold each role's WCAG legal floor every frame of the ease: an interpolated
38
- * colour is only shown while it still clears the role's `legalFloor` against
39
- * the live background (for text on animated content / `prefers-contrast`).
40
- * Default `false` (the free ease — brief surplus dips, destination always legal).
39
+ * Enable the legacy characterized per-frame clamp. The current
40
+ * Oklab→clip→sRGB8 path is not globally monotone, so this option is not a
41
+ * universal floor/least-blend certificate; #287 owns the finite replacement.
42
+ * Default `false`.
41
43
  */
42
44
  strict?: boolean;
43
45
  /** Override reduced-motion detection (default reads `matchMedia`). */