@labpics/colors 0.10.0 → 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/LICENSE +1 -1
- package/LICENSES/CC-BY-4.0.txt +396 -0
- package/LICENSES/CC-BY-SA-4.0.txt +428 -0
- package/NOTICE.md +65 -0
- package/README.md +303 -333
- package/build-metadata.json +16 -12
- package/evidence/point-support-reference-surplus-q55-bps-proof-v1.json +1 -0
- package/evidence/wcag22-srgb8-q55-proof-v1.json +1 -0
- package/evidence/wcag22-srgb8-q55-v1.bin +0 -0
- package/evidence/wcag22-srgb8-v1.json +1 -0
- package/index.d.ts +204 -63
- package/index.js +495 -17
- package/package.json +32 -34
- package/pkg/labcolors.d.ts +227 -491
- package/pkg/labcolors.js +943 -177
- package/pkg/labcolors_bg.wasm +0 -0
- package/pkg/labcolors_bg.wasm.d.ts +61 -12
- package/pkg/snippets/labcolors-wasm-9fb8b927594c3d6f/inline0.js +98 -0
- package/program-wire/abi-v1.d.ts +84 -0
- package/program-wire/abi-v1.js +332 -0
- package/program-wire/abi-v2.d.ts +17 -0
- package/program-wire/abi-v2.js +61 -0
- package/program-wire/encoding.js +218 -0
- package/wcag22.d.ts +6 -0
- package/adapt-theme.d.ts +0 -76
- package/adapt-theme.js +0 -738
- package/apply-theme.d.ts +0 -16
- package/apply-theme.js +0 -45
- package/effective-bg.d.ts +0 -51
- package/effective-bg.js +0 -501
- package/watch-theme.d.ts +0 -57
- package/watch-theme.js +0 -144
package/README.md
CHANGED
|
@@ -1,381 +1,351 @@
|
|
|
1
1
|
# @labpics/colors
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Компилятор и runtime проверяемых цветовых Program-графов.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
---
|
|
5
|
+
Клиент передаёт канонические Program wire-байты. Ядро атомарно проверяет граф, создаёт Session, принимает наблюдения среды и возвращает только сертифицированные Paint outputs. Recipe-меню ролей и специальные Material/Glow runtime-пути удалены из публичного API.
|
|
8
6
|
|
|
9
7
|
## Установка
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
npm install @labpics/colors
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
При сборке из монорепо:
|
|
18
|
-
|
|
19
|
-
```sh
|
|
20
|
-
npm run build # → pkg/ (wasm + JS-обёртка + .d.ts)
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
Пакет экспортирует `@labpics/colors/build-metadata.json` — self-declared
|
|
24
|
-
machine-readable metadata конкретной сборки: npm/core versions, exact source
|
|
25
|
-
SHA, digest и SHA-256 conformance manifest/family set, а также размер и SHA-256
|
|
26
|
-
WASM-байтов. Release-gate сверяет объект целиком с исходными файлами и повторяет
|
|
27
|
-
проверку после чистой установки tarball. Это integrity metadata внутри
|
|
28
|
-
артефакта, не криптографическая provenance/Sigstore-аттестация, не runtime
|
|
29
|
-
telemetry и не сетевой запрос.
|
|
30
|
-
|
|
31
|
-
---
|
|
9
|
+
Команда установки проверенного архива указана на [странице актуального релиза](https://github.com/Labpics-Team/lab-colors/releases/latest).
|
|
10
|
+
Она использует прямой URL конкретной версии, поэтому сохранённый lockfile
|
|
11
|
+
не зависит от будущих обновлений. Имя пакета и импорты остаются `@labpics/colors`.
|
|
32
12
|
|
|
33
|
-
|
|
13
|
+
[Готовый пример адаптации к фону](https://github.com/Labpics-Team/lab-colors/blob/main/docs/how-to/adapt-contrast.md) показывает выбор цвета и отказ при несовместимых требованиях.
|
|
34
14
|
|
|
35
|
-
|
|
15
|
+
## Первый маршрут
|
|
36
16
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
import dsConfig from "./theme.config.json"; // паспорт вашей дизайн-системы (ThemeConfig)
|
|
40
|
-
|
|
41
|
-
await init(); // загрузить WASM-модуль (один раз)
|
|
42
|
-
const engine = new LabColors(); // пустой движок: словаря ролей ещё нет
|
|
43
|
-
engine.loadConfig(JSON.stringify(dsConfig)); // без этого шага resolveTheme отклонится: config_required
|
|
44
|
-
|
|
45
|
-
const result = engine.resolveTheme("#FFFFFF", "light");
|
|
46
|
-
// result.vars → готовые CSS-значения по ролям ВАШЕГО конфига:
|
|
47
|
-
// { "--lab-label-primary": "oklch(<L>% <C> <H>)", … }
|
|
48
|
-
// result.roles → детали каждой роли (css, hex, контраст, флаги)
|
|
49
|
-
|
|
50
|
-
applyTheme(document.documentElement, result); // записать все --lab-* в элемент
|
|
51
|
-
```
|
|
17
|
+
Инициализируйте WASM один раз выбранным способом, затем выполните общий пример
|
|
18
|
+
ниже в том же модуле.
|
|
52
19
|
|
|
53
|
-
###
|
|
20
|
+
### Браузер
|
|
54
21
|
|
|
55
|
-
|
|
22
|
+
В ESM-проекте с настройкой разрешения npm-импортов:
|
|
56
23
|
|
|
57
24
|
```ts
|
|
58
|
-
import init
|
|
25
|
+
import init from "@labpics/colors";
|
|
59
26
|
|
|
60
27
|
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
28
|
```
|
|
72
29
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
30
|
+
Сборщик или сервер должен публиковать `pkg/labcolors_bg.wasm` рядом с
|
|
31
|
+
сгенерированным `pkg/labcolors.js`; `init()` загружает файл относительно этого
|
|
32
|
+
модуля. Если сборщик переносит WASM, передайте его URL явно через
|
|
33
|
+
`init({ module_or_path: wasmUrl })`.
|
|
77
34
|
|
|
78
|
-
###
|
|
35
|
+
### Node.js
|
|
79
36
|
|
|
80
|
-
|
|
37
|
+
В Node.js 22.11 или новее используйте ESM (`.mjs` или `"type": "module"` в
|
|
38
|
+
`package.json`) и передайте байты файла. Node.js не загружает `file:` URL через
|
|
39
|
+
`fetch`, поэтому браузерный вызов без аргументов здесь не подходит.
|
|
81
40
|
|
|
82
41
|
```ts
|
|
83
|
-
import
|
|
42
|
+
import { readFileSync } from "node:fs";
|
|
43
|
+
import init from "@labpics/colors";
|
|
84
44
|
|
|
85
|
-
await init(
|
|
86
|
-
|
|
87
|
-
|
|
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" }),
|
|
45
|
+
await init({
|
|
46
|
+
module_or_path: readFileSync(
|
|
47
|
+
new URL(import.meta.resolve("@labpics/colors/pkg/labcolors_bg.wasm")),
|
|
48
|
+
),
|
|
94
49
|
});
|
|
95
|
-
|
|
96
|
-
adaptive.start(); // запустить внутренний requestAnimationFrame-цикл
|
|
97
|
-
adaptive.setTheme("dark"); // смена темы применяется мгновенно
|
|
98
|
-
adaptive.stop(); // остановить цикл
|
|
99
50
|
```
|
|
100
51
|
|
|
101
|
-
|
|
52
|
+
### Объявление графа и чтение результата
|
|
102
53
|
|
|
103
54
|
```ts
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
}
|
|
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
|
+
}
|
|
110
98
|
```
|
|
111
99
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
##
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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.
|
|
139
134
|
|
|
140
135
|
```ts
|
|
141
|
-
|
|
142
|
-
theme: ThemeName;
|
|
143
|
-
background: string; // нормализованный #RRGGBB
|
|
144
|
-
vars: Record<string, string>; // достижимые роли: "--lab-<ключ>" → готовое CSS-значение oklch
|
|
145
|
-
roles: Record<string, RoleResult>; // все роли с деталями
|
|
146
|
-
}
|
|
136
|
+
import { attachProgramWire } from "@labpics/colors";
|
|
147
137
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
входит в 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"
|
|
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();
|
|
219
166
|
}
|
|
220
167
|
```
|
|
221
168
|
|
|
222
|
-
`
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
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-*` переменные с фактическим фоном элемента. Применяет немедленно при создании и возвращает контроллер.
|
|
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()`:
|
|
262
191
|
|
|
263
192
|
```ts
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
target?: HTMLElement; // куда писать переменные (по умолчанию: element)
|
|
269
|
-
fallback?: string; // фон при полностью прозрачной цепочке (по умолчанию "#FFFFFF")
|
|
270
|
-
observe?: boolean; // авто-обновление при DOM-мутациях (по умолчанию true)
|
|
271
|
-
root?: Node; // корень MutationObserver (по умолчанию: documentElement)
|
|
272
|
-
}
|
|
193
|
+
import {
|
|
194
|
+
decodeCertificateEnvelope,
|
|
195
|
+
issueSourceCertificateEnvelope,
|
|
196
|
+
} from "@labpics/colors";
|
|
273
197
|
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
setTheme(theme: ThemeName): void; // переключить тему и применить
|
|
277
|
-
background(): string; // последний вычисленный фон (hex)
|
|
278
|
-
stop(): void; // отключить наблюдателей
|
|
279
|
-
}
|
|
198
|
+
const bytes = issueSourceCertificateEnvelope();
|
|
199
|
+
const metadata = decodeCertificateEnvelope(bytes);
|
|
280
200
|
```
|
|
281
201
|
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
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
|
+
]);
|
|
313
321
|
```
|
|
314
322
|
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
323
|
+
Группы расположены от предпочтительной к следующей. Каждое состояние описывает
|
|
324
|
+
одновременно все конечные цели. Перечень должен покрывать полное произведение
|
|
325
|
+
доменов без повторов. Внутри одной группы порядок списка не влияет на решение:
|
|
326
|
+
ничья разрешается каноническими байтами непрозрачного ID состояния. Ревизия и
|
|
327
|
+
группы входят в идентичность выпуска выбора.
|
|
319
328
|
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
329
|
+
Core проверяет каждое состояние на всех наблюдаемых сценариях и выбирает первое,
|
|
330
|
+
которое прошло все обязательные ограничения. Неизвестный вход и конфликт
|
|
331
|
+
сохраняют существующие состояния Session и отзыв установленного результата.
|
|
332
|
+
Порядок задаёт предпочтения клиента; он не определяет cleanliness, не подбирает
|
|
333
|
+
научные коэффициенты и не ослабляет ограничения.
|
|
325
334
|
|
|
326
|
-
|
|
335
|
+
V2 допускает один выпуск выбора, до 4096 состояний и 4096 назначений суммарно.
|
|
336
|
+
V1 сохраняет прежние байты и отказывается от конечного графа без доступного ему
|
|
337
|
+
выпуска выбора. Нативные функции с суффиксом `_v1` остаются строго V1; функции
|
|
338
|
+
`check_program_wire` и `compile_program_wire` распознают обе поддерживаемые версии.
|
|
327
339
|
|
|
328
|
-
### `effectiveBackground(element, options?): string`
|
|
329
340
|
|
|
330
|
-
|
|
331
|
-
подмножества DOM `background-color`. Это не browser pixel capture и не
|
|
332
|
-
сертификат цвета, который реально видит наблюдатель. Helper обходит цепочку
|
|
333
|
-
предков и композитит распознанные слои поверх `fallback` (по умолчанию белый).
|
|
341
|
+
### Ошибки оценки и чтения результата
|
|
334
342
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
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 сохраняется.
|
|
339
348
|
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
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.
|
|
349
|
+
Текст `message` служит диагностикой. Проверка читает каждое поле один раз,
|
|
350
|
+
не преобразует значения и возвращает `false` для неизвестной пары или ошибки
|
|
351
|
+
чтения. Контракт принадлежит также прямым WASM-входам.
|