@labpics/colors 0.9.1 → 1.0.2

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