@labpics/colors 0.10.0 → 1.0.3

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,381 +1,363 @@
1
- # @labpics/colors
1
+ # Lab Colors
2
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-зависимостей.
3
+ Библиотека адаптивных цветов для интерфейсов и дизайн-систем.
4
+ Вы задаёте цвета, фоны и ограничения, например контраст текста.
5
+ Lab Colors выбирает подходящие значения с учётом наложения слоёв
6
+ и пересчитывает результат, когда приложение передаёт изменения фона.
4
7
 
5
- Ядро возвращает **данные**, не затрагивает DOM. Три вспомогательные функции переводят эти данные в живые CSS-переменные: `applyTheme` (разовое применение), `watchTheme` (реактивное — обновляется при изменении фона) и `adaptTheme` (плавная адаптация для фона, меняющегося каждый кадр).
6
-
7
- ---
8
+ [![npm](https://img.shields.io/npm/v/%40labpics%2Fcolors)](https://www.npmjs.com/package/@labpics/colors)
9
+ [![CI](https://github.com/Labpics-Team/lab-colors/actions/workflows/ci.yml/badge.svg)](https://github.com/Labpics-Team/lab-colors/actions/workflows/ci.yml)
10
+ [![Код: MIT](https://img.shields.io/badge/code-MIT-blue)](https://github.com/Labpics-Team/lab-colors/blob/main/LICENSE)
8
11
 
9
12
  ## Установка
10
13
 
11
- Пакет публикуется в npm-реестр Labpics:
12
-
13
- ```sh
14
- npm install @labpics/colors
15
- ```
16
-
17
- При сборке из монорепо:
18
-
19
14
  ```sh
20
- npm run build # → pkg/ (wasm + JS-обёртка + .d.ts)
15
+ npm install @labpics/colors@^1
21
16
  ```
22
17
 
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 и не сетевой запрос.
18
+ JavaScript и TypeScript, ESM. Ядро на Rust/WASM включено в пакет.
19
+ Сохраните lockfile, чтобы закрепить версию.
30
20
 
31
- ---
21
+ [Пример подбора цвета под фон](https://github.com/Labpics-Team/lab-colors/blob/main/docs/how-to/adapt-contrast.md)
22
+ выбирает чёрный или белый текст по требованию контраста WCAG 2.2
23
+ и показывает отказ, когда ни один вариант не подходит.
32
24
 
33
- ## Как использовать
25
+ <a id="первый-маршрут"></a>
34
26
 
35
- ### Разовое применение
27
+ ## Первый запуск
36
28
 
37
- ```ts
38
- import init, { LabColors, applyTheme } from "@labpics/colors";
39
- import dsConfig from "./theme.config.json"; // паспорт вашей дизайн-системы (ThemeConfig)
29
+ Инициализируйте WASM один раз выбранным способом, затем выполните общий пример
30
+ ниже в том же модуле.
40
31
 
41
- await init(); // загрузить WASM-модуль (один раз)
42
- const engine = new LabColors(); // пустой движок: словаря ролей ещё нет
43
- engine.loadConfig(JSON.stringify(dsConfig)); // без этого шага resolveTheme отклонится: config_required
32
+ ### Браузер
44
33
 
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` синхронизирует переменные с фактическим фоном элемента автоматически.
34
+ В ESM-проекте с настройкой разрешения npm-импортов:
56
35
 
57
36
  ```ts
58
- import init, { LabColors, watchTheme } from "@labpics/colors";
37
+ import init from "@labpics/colors";
59
38
 
60
39
  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
40
  ```
72
41
 
73
- Поддерживает два режима изменений:
74
-
75
- - **Дискретные** (переключение темы, обновление класса, DOM-мутация) — отслеживаются `MutationObserver` автоматически.
76
- - **Непрерывные** (CSS-анимация, кадровый фон, который никогда не мутирует `inline style`) — управляются вручную через `refresh()` из собственного цикла `requestAnimationFrame`. `refresh()` дёшев: пересчитывает только при реальном изменении строки фона.
42
+ Сборщик или сервер должен публиковать `pkg/labcolors_bg.wasm` рядом с
43
+ сгенерированным `pkg/labcolors.js`; `init()` загружает файл относительно этого
44
+ модуля. Если сборщик переносит WASM, передайте его URL явно через
45
+ `init({ module_or_path: wasmUrl })`.
77
46
 
78
- ### Плавная адаптация к анимированному фону
47
+ ### Node.js
79
48
 
80
- `watchTheme` пересчитывает весь набор при каждом изменении фона. Для фона, меняющегося **каждый кадр** (анимация, параллакс, размытый фон), `adaptTheme` — более элегантный вариант: проверяет дёшево каждый кадр, пересчитывает и плавно переходит к новым цветам только когда контраст реально ухудшается.
49
+ В Node.js 22.11 или новее используйте ESM (`.mjs` или `"type": "module"` в
50
+ `package.json`) и передайте байты файла. Node.js не загружает `file:` URL через
51
+ `fetch`, поэтому браузерный вызов без аргументов здесь не подходит.
81
52
 
82
53
  ```ts
83
- import init, { LabColors, adaptTheme, effectiveBackground } from "@labpics/colors";
54
+ import { readFileSync } from "node:fs";
55
+ import init from "@labpics/colors";
84
56
 
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" }),
57
+ await init({
58
+ module_or_path: readFileSync(
59
+ new URL(import.meta.resolve("@labpics/colors/pkg/labcolors_bg.wasm")),
60
+ ),
94
61
  });
95
-
96
- adaptive.start(); // запустить внутренний requestAnimationFrame-цикл
97
- adaptive.setTheme("dark"); // смена темы применяется мгновенно
98
- adaptive.stop(); // остановить цикл
99
62
  ```
100
63
 
101
- Для фона с градиентом или изображением можно передать несколько образцов — цвета будут корректны для наиболее сложного из них:
64
+ ### Объявление графа и чтение результата
102
65
 
103
66
  ```ts
104
- adaptTheme(hero, {
105
- colors,
106
- theme: "light",
107
- strict: true,
108
- background: () => sampleBackdrop(hero), // например ["#0B0B0E", "#3A3A40"]
109
- });
67
+ import { compileProgramWire } from "@labpics/colors";
68
+ import {
69
+ ProgramWireBuilderV1,
70
+ SURROUND_AVERAGE_V1,
71
+ WCAG22_SC1411_UI_COMPONENT_OR_STATE_V1,
72
+ } from "@labpics/colors/program-wire/abi-v1.js";
73
+
74
+ const programBytes = new ProgramWireBuilderV1()
75
+ .source(11, [20, 20, 20])
76
+ .fixedTarget(21, 11)
77
+ .surfaceInputPort(31)
78
+ .solidPaint(41, 21)
79
+ .inputSurface(51, 31)
80
+ .sourceOverOccurrence(61, 41, 51, 64, 0.2, SURROUND_AVERAGE_V1)
81
+ .presentationRoot(71, 61)
82
+ .presentationTarget(71, 61)
83
+ .wcag22VisibleUnary(true, 81, 61, WCAG22_SC1411_UI_COMPONENT_OR_STATE_V1)
84
+ .output(91, 41)
85
+ .finish();
86
+ const runtime = compileProgramWire(programBytes, 1);
87
+ try {
88
+ const snapshot = runtime.updateObserved(
89
+ 1n,
90
+ new Uint32Array([1]),
91
+ new Uint8Array([255, 255, 255]),
92
+ 1,
93
+ );
94
+ try {
95
+ if (snapshot.state === "ready") {
96
+ for (let index = 0; index < snapshot.outputCount(); index += 1) {
97
+ console.log(
98
+ snapshot.outputSlot(index),
99
+ snapshot.outputRgb(index),
100
+ snapshot.outputOpacity(index),
101
+ );
102
+ }
103
+ }
104
+ } finally {
105
+ snapshot.free();
106
+ }
107
+ } finally {
108
+ runtime.free();
109
+ }
110
110
  ```
111
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`:
112
+ Канонические `LCPW` v1 bytes создаются `ProgramWireBuilderV1` или другим реализационно-независимым энкодером того же контракта.
113
+
114
+ ## Явная конвенция cleanliness
115
+
116
+ Чтобы выбранный результат удовлетворял встроенной конвенции sRGB8, добавьте
117
+ `.declaredSrgb8CleanSet(true, 82, 71, 61)` в цепочку примера перед `.finish()`.
118
+ Здесь `82` — ID ограничения, `71` — presentation root, `61` — occurrence.
119
+ Проверяется финальный encoded-sRGB8 результат этой точки с учётом композиции,
120
+ а не только исходный цвет. `true` задаёт обязательное ограничение; `false`
121
+ не ограничивает выдачу outputs. Результаты отдельных report-only ограничений
122
+ публичный `ProgramSnapshot` не раскрывает.
123
+
124
+ Это явно выбранная, закреплённая версией пакета конвенция. Она не включается
125
+ автоматически и не подтверждает человеческое восприятие, фактическую отрисовку
126
+ или универсальную «чистоту» цвета.
127
+
128
+ Контракт использует закреплённый в пакете выпуск
129
+ `exact-nominal-srgb8-point-clean-set-v2`; его точная SHA-256 указана в `NOTICE.md`
130
+ пакета (в репозитории — `crates/labcolors-core/NOTICE.md`).
131
+ Это условная дискретная nominal-модель с воспроизводимым выводом, а не гарантия
132
+ человеческого восприятия. При обновлении пакета сохранённый wire следует заново
133
+ компилировать и оценивать: семантическая идентичность Program включает выпуск
134
+ конвенции, поэтому старые сертификаты не удостоверяют новый набор.
135
+
136
+ ## Подключение к внешнему sink
137
+
138
+ Для сценария, где приложение само владеет DOM или другим renderer-surface,
139
+ используйте `attachProgramWire`. Синхронный `host` получает полный typed intent
140
+ (`setAll`, `revokeAll` или `confirmExact`) и должен вернуть `true` только после
141
+ атомарной установки всего принадлежащего ему scope; `false` отклоняет update.
142
+ Пакет не пишет DOM и не выдаёт authority из исходного или промежуточного Paint.
143
+ В примере `applyOwnedPointIntent` и `revokeOwnedPointScope` реализует приложение:
144
+ первая функция атомарно применяет intent и возвращает `boolean`, вторая
145
+ возвращает управление только после отзыва всего принадлежащего sink scope.
139
146
 
140
147
  ```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
- }
148
+ import { attachProgramWire } from "@labpics/colors";
147
149
 
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"
150
+ const attachment = attachProgramWire(programBytes, 1, 91, 501, 71, 61, (intent) => {
151
+ // Приложение проверяет sinkOutput, expectedSequence и bindingEpoch,
152
+ // затем одним действием обновляет собственный renderer-surface.
153
+ return applyOwnedPointIntent(intent);
154
+ });
155
+ try {
156
+ const snapshot = attachment.updateObserved(
157
+ 1n,
158
+ new Uint32Array([1]),
159
+ new Uint8Array([255, 255, 255]),
160
+ 1,
161
+ );
162
+ try {
163
+ if (snapshot.state === "ready") {
164
+ const authority = attachment.materializationAuthority();
165
+ try {
166
+ console.log(authority.terminalCompositeRgb());
167
+ } finally {
168
+ authority.free();
169
+ }
170
+ }
171
+ } finally {
172
+ snapshot.free();
173
+ }
174
+ } finally {
175
+ revokeOwnedPointScope();
176
+ attachment.dispose(true);
177
+ attachment.free();
219
178
  }
220
179
  ```
221
180
 
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-*` переменные с фактическим фоном элемента. Применяет немедленно при создании и возвращает контроллер.
181
+ `materializationAuthority()` читает только успешно установленный
182
+ attachment head. Его `rendererProvenance` остаётся `"unverified"`: результат —
183
+ модельная terminal materialization с проверенными identity, revision, sink stamp,
184
+ binding epoch и отсутствием downstream point, а не доказательство browser paint
185
+ или человеческого восприятия. При отказе host предыдущий head сохраняется.
186
+ Пока host callback исполняется синхронно, повторный вызов любой операции attachment,
187
+ включая `free()`, получает typed-отказ busy; освобождайте attachment после возврата
188
+ из callback. `free()` также получает typed-отказ `program_attachment_revoke_unconfirmed`,
189
+ пока внешний scope не отозван и `dispose(true)` не завершился успешно. Внешний scope
190
+ отзывается владельцем host до `dispose(true)`. Подтверждением служит только
191
+ примитивный `true`; числа, строки и объекты не приводятся к boolean и получают
192
+ `program_attachment_revoke_unconfirmed`.
193
+
194
+ `Symbol.dispose` и TypeScript `using` выполняют тот же защищённый `free()`.
195
+ До выхода из `using` приложение должно отозвать scope и вызвать `dispose(true)`;
196
+ автоматическое освобождение не подтверждает отзыв за внешнего владельца.
197
+
198
+ ## Создание и инспекция certificate envelope
199
+
200
+ После инициализации WASM `issueSourceCertificateEnvelope()` возвращает новый
201
+ `Uint8Array` с envelope встроенного source producer Core. Функция не принимает
202
+ payload или identity. Например, после `await init()`:
262
203
 
263
204
  ```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
- }
205
+ import {
206
+ decodeCertificateEnvelope,
207
+ issueSourceCertificateEnvelope,
208
+ } from "@labpics/colors";
273
209
 
274
- interface WatchController {
275
- refresh(force?: boolean): ResolvedTheme | null; // пересчитать и применить, если фон изменился
276
- setTheme(theme: ThemeName): void; // переключить тему и применить
277
- background(): string; // последний вычисленный фон (hex)
278
- stop(): void; // отключить наблюдателей
279
- }
210
+ const bytes = issueSourceCertificateEnvelope();
211
+ const metadata = decodeCertificateEnvelope(bytes);
280
212
  ```
281
213
 
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
- }
214
+ Обе функции импортируются из `@labpics/colors`. `metadata.producerRevision` —
215
+ полный Git tree object ID исходников Core, а content identity адресует встроенный
216
+ source descriptor. Эти данные не утверждают равенство исполняемых файлов,
217
+ аутентичность удалённого отправителя или научные свойства цвета.
218
+
219
+ Если при сборке проверенный source descriptor недоступен, issuance бросает
220
+ ошибку с `operation: "issueSourceCertificateEnvelope"` и
221
+ `code: "certificate_producer_identity_unavailable"`. Её распознаёт
222
+ `isCertificateError`; untrusted decode и остальные операции остаются доступны.
223
+
224
+ `decodeCertificateEnvelope(bytes)` разбирает только фиксированный `LCEN` v1
225
+ transport envelope и возвращает замороженный metadata-object
226
+ `UntrustedCertificateEnvelopeV1`. Результат — метаданные framing и проверенные digest,
227
+ а не authority result и не доказательство
228
+ истины payload. Тело payload остаётся opaque и не передаётся в JavaScript.
229
+
230
+ До вызова WASM-функции фасад проверяет intrinsic storage `Uint8Array` и создаёт
231
+ собственный snapshot по правилам [допуска массивов](#массивы-на-границе-wasm).
232
+ Размер больше `MAX_CERTIFICATE_ENVELOPE_BYTES`
233
+ (`2097152`) отвергается до копирования, поскольку `wasm-bindgen` копирует typed array
234
+ в linear memory до входа Rust. Неизвестная schema, authority,
235
+ operation, payload type/version, неканоничные строки, trailing bytes и digest
236
+ mismatch дают typed error; `isCertificateError(value)` проверяет только
237
+ допустимую пару `operation`/`code`.
238
+
239
+ Заморожен внешний metadata-object; его три byte-поля — отдельные detached snapshots,
240
+ поэтому изменение буфера результата не меняет состояние WASM или следующий decode.
241
+
242
+ Создать envelope из произвольных JS-байтов, `ProgramSnapshot`, Paint, CSS, DOM или
243
+ materialization authority нельзя. Producer capability и admission ledger остаются
244
+ владением Rust Core; в r13 нет persistence, network relay, CLI, science authority
245
+ или registry publication.
246
+
247
+ ## Контракт
248
+
249
+ - Один публичный runtime-root: `compileProgramWire` → `ProgramRuntime` → `ProgramSnapshot`.
250
+ - Обновление атомарно: отказ не публикует частичный state.
251
+ - Output появляется только при выполненных всех обязательных (`hard: true`) ограничениях. Это внутренняя проверка в рамках Session, а не публичный переносимый сертификат или гарантия конечного видимого результата приложения.
252
+ - Канонические байты имеют одну `ContentIdentity`.
253
+ - Невалидные wire-байты, графы, observation и resource bounds возвращают typed-отказы; fallback отсутствует.
254
+ - DOM и CSS не входят в ядро. Применение output принадлежит приложению.
255
+
256
+ ## Числовые входы
257
+
258
+ ID потока и причины, число подложек и индекс output принимаются только как
259
+ конечные целые `number` в диапазоне `0..4294967295`. Ревизия принимается как
260
+ `bigint` в диапазоне `0n..18446744073709551615n`. Строки, нечисловые значения,
261
+ дроби и выход за диапазон не приводятся к допустимому значению. Допуск входа
262
+ предшествует изменению Session; после отказа корректную ревизию можно повторить.
263
+ Допустимость конкретного индекса, формы observations и порядка ревизий
264
+ по-прежнему проверяет соответствующий контракт runtime.
265
+
266
+ ## Массивы на границе WASM
267
+
268
+ Program wire, поверхности и content identity принимают реальный `Uint8Array`,
269
+ ID сценариев — `Uint32Array`. Обычные массивы, другие виды typed array,
270
+ Proxy-обёртки, detached storage и собственные свойства `length`/`byteLength`
271
+ дают типизированный отказ до generated copier. Числа не оборачиваются и не
272
+ округляются неявно.
273
+
274
+ Допустимы `Buffer`, subclasses, subarray и массивы из другого realm, если их
275
+ внутренний тип соответствует аргументу. Фасад использует intrinsic storage,
276
+ не читает пользовательские getters и не обходит цепочку прототипов. Унаследованные
277
+ свойства размеров не участвуют в копировании; WASM получает отдельный snapshot.
278
+ Отказ observations сохраняет предыдущий head и допускает повтор той же ревизии.
279
+ Для `materializationAuthorityFor` identity должна содержать ровно 32 байта;
280
+ неверная длина отвергается до выделения snapshot.
281
+
282
+ ## Распознавание ошибок
283
+
284
+ `isProgramError(value)` распознаёт ошибки Program по принадлежности текущему
285
+ `Error` и допустимой паре `operation`/`code`. Неизвестное значение, чужая пара
286
+ или исключение при чтении возвращают `false`, не заменяя исходную ошибку
287
+ новым исключением. Каждое поле читается не более одного раза, без преобразования
288
+ его значения; читаемые унаследованные поля и getters допустимы.
289
+
290
+ Нехватка ресурсов при compile/instantiate/update возвращает
291
+ `program_resource_exhausted`, внутренний сбой — `program_internal_invariant`.
292
+ Attachment сохраняет те же классы в `program_attachment_resource_exhausted`
293
+ и `program_attachment_internal_invariant`. Эти причины не означают, что
294
+ пользовательский граф или observation семантически недопустимы; отказ update
295
+ сохраняет предыдущий committed head и допускает повтор той же ревизии.
296
+ Нехватка памяти при подготовке identity для `materializationAuthorityFor`
297
+ также возвращает `program_attachment_resource_exhausted` с операцией
298
+ `materializationAuthority`.
299
+
300
+ Проверка описывает только наблюдённые значения. Она не удостоверяет происхождение
301
+ ошибки, не замораживает объект и не гарантирует неизменность следующих чтений
302
+ пользовательских getters. Непознанная ошибка остаётся у вызывающего приложения.
303
+
304
+ ## Дополнительные функции
305
+
306
+ - `evaluateWcag22` — точная оценка WCAG 2.2 в finite sRGB8/Q55-профиле.
307
+ - `numericalCapabilityManifest` — манифест численных возможностей и доказательств сборки.
308
+
309
+ ## Снимок входных массивов
310
+
311
+ Program wire, scenario IDs, surface bytes и certificate envelope принимают
312
+ типизированные массивы на обычном `ArrayBuffer`. Buffer, срезы и массивы из
313
+ другого JavaScript realm поддерживаются. Пакет делает собственную копию до
314
+ передачи в WASM и сохраняет прежнее состояние при отказе входа.
315
+
316
+ Массивы на `SharedArrayBuffer`, включая growable storage, получают штатный
317
+ typed-отказ входа: параллельный писатель может менять данные во время копирования.
318
+ Производитель наблюдения должен завершить запись и передать принадлежащий ему
319
+ обычный буфер. Это правило общее для компиляции, обновлений и идентичностей.
320
+
321
+ ## Конечные варианты и явный порядок выбора
322
+
323
+ Для графа с `finiteTarget` используйте `ProgramWireBuilderV2` из
324
+ `@labpics/colors/program-wire/abi-v2.js`. Остальные методы описания графа
325
+ совпадают с V1. Готовые байты принимает прежний `compileProgramWire` или
326
+ `attachProgramWire`; второй решатель или отдельный lifecycle не нужны.
327
+
328
+ ```js
329
+ builder.selectionRelease(1n, [
330
+ [{ id: 1, choices: [{ target: 21, candidate: 201 }] }],
331
+ [{ id: 2, choices: [{ target: 21, candidate: 202 }] }],
332
+ ]);
313
333
  ```
314
334
 
315
- `strict` сохраняет прежнее runtime-поведение, но не является доказательством
316
- минимального или проходящего состояния на каждом кадре: путь
317
- Oklab→gamut clip→sRGB8 немонотонен. Finite hard-floor-safe replacement ведётся в
318
- #287; до него этот флаг следует считать compatibility characterization.
335
+ Группы расположены от предпочтительной к следующей. Каждое состояние описывает
336
+ одновременно все конечные цели. Перечень должен покрывать полное произведение
337
+ доменов без повторов. Внутри одной группы порядок списка не влияет на решение:
338
+ ничья разрешается каноническими байтами непрозрачного ID состояния. Ревизия и
339
+ группы входят в идентичность выпуска выбора.
319
340
 
320
- Управляйте через `start()` (внутренний rAF-цикл) или вызывайте `tick()` из собственного цикла. Смена темы применяется мгновенно — это осознанное намерение, а не дрейф.
321
- Перед применением результата контроллер проверяет provenance как stable-, так и
322
- legacy-ветвей Glow. Нетипизированный внешний mock с невозможным сочетанием
323
- profile/guarantee/diagnostic/status отклоняется `TypeError`; fallback-цвет из
324
- такого объекта не применяется.
341
+ Core проверяет каждое состояние на всех наблюдаемых сценариях и выбирает первое,
342
+ которое прошло все обязательные ограничения. Неизвестный вход и конфликт
343
+ сохраняют существующие состояния Session и отзыв установленного результата.
344
+ Порядок задаёт предпочтения клиента; он не определяет cleanliness, не подбирает
345
+ научные коэффициенты и не ослабляет ограничения.
325
346
 
326
- ---
347
+ V2 допускает один выпуск выбора, до 4096 состояний и 4096 назначений суммарно.
348
+ V1 сохраняет прежние байты и отказывается от конечного графа без доступного ему
349
+ выпуска выбора. Нативные функции с суффиксом `_v1` остаются строго V1; функции
350
+ `check_program_wire` и `compile_program_wire` распознают обе поддерживаемые версии.
327
351
 
328
- ### `effectiveBackground(element, options?): string`
329
352
 
330
- Возвращает непрозрачный reference-`#RRGGBB`, вычисленный для поддерживаемого
331
- подмножества DOM `background-color`. Это не browser pixel capture и не
332
- сертификат цвета, который реально видит наблюдатель. Helper обходит цепочку
333
- предков и композитит распознанные слои поверх `fallback` (по умолчанию белый).
353
+ ### Ошибки оценки и чтения результата
334
354
 
335
- ```ts
336
- const bg = effectiveBackground(panel); // например "#0F1014"
337
- const bg2 = effectiveBackground(panel, { fallback: "#101012" });
338
- ```
355
+ `isBindingError(error)` распознаёт `Error` по паре `operation` и `code`.
356
+ Для `evaluateWcag22` причины: `invalid_color`, `unknown_wcag22_criterion`,
357
+ `internal_error`. Для `numericalCapabilityManifest` доступен `internal_error`.
358
+ Неверный индекс в `outputSlot`, `outputRgb` или `outputOpacity` возвращает
359
+ `invalid_output_index` с операцией `readProgramOutput`; snapshot сохраняется.
339
360
 
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.
361
+ Текст `message` служит диагностикой. Проверка читает каждое поле один раз,
362
+ не преобразует значения и возвращает `false` для неизвестной пары или ошибки
363
+ чтения. Контракт принадлежит также прямым WASM-входам.