@labpics/colors 0.9.0 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +121 -22
- package/adapt-theme.d.ts +8 -6
- package/adapt-theme.js +225 -29
- package/apply-theme.js +5 -4
- package/build-metadata.json +19 -0
- package/effective-bg.d.ts +3 -2
- package/effective-bg.js +28 -19
- package/index.d.ts +34 -1
- package/package.json +25 -5
- package/pkg/labcolors.d.ts +269 -22
- package/pkg/labcolors.js +38 -4
- package/pkg/labcolors_bg.wasm +0 -0
- package/pkg/labcolors_bg.wasm.d.ts +1 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Lab Pics
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -20,6 +20,14 @@ npm install @labpics/colors
|
|
|
20
20
|
npm run build # → pkg/ (wasm + JS-обёртка + .d.ts)
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
+
Пакет экспортирует `@labpics/colors/build-metadata.json` — self-declared
|
|
24
|
+
machine-readable metadata конкретной сборки: npm/core versions, exact source
|
|
25
|
+
SHA, digest и SHA-256 conformance manifest/family set, а также размер и SHA-256
|
|
26
|
+
WASM-байтов. Release-gate сверяет объект целиком с исходными файлами и повторяет
|
|
27
|
+
проверку после чистой установки tarball. Это integrity metadata внутри
|
|
28
|
+
артефакта, не криптографическая provenance/Sigstore-аттестация, не runtime
|
|
29
|
+
telemetry и не сетевой запрос.
|
|
30
|
+
|
|
23
31
|
---
|
|
24
32
|
|
|
25
33
|
## Как использовать
|
|
@@ -137,13 +145,51 @@ interface ResolvedTheme {
|
|
|
137
145
|
roles: Record<string, RoleResult>; // все роли с деталями
|
|
138
146
|
}
|
|
139
147
|
|
|
140
|
-
type RoleResult =
|
|
148
|
+
type RoleResult =
|
|
149
|
+
| SolvedColor
|
|
150
|
+
| TranslucentRole
|
|
151
|
+
| GlowRole
|
|
152
|
+
| MaterialRole
|
|
153
|
+
| NoneRole
|
|
154
|
+
| UnreachableRole;
|
|
141
155
|
```
|
|
142
156
|
|
|
143
|
-
Каждая роль —
|
|
157
|
+
Каждая роль — одна из шести категорий результата; у Glow есть два терминальных
|
|
158
|
+
состояния:
|
|
144
159
|
|
|
145
160
|
- `SolvedColor` — цвет найден (`kind: "color"`, поля `css` — готовое `oklch(L% C H)`, `hex` — тот же цвет как данные, `lc`, `wcagRatio`, …).
|
|
146
|
-
- `TranslucentRole` — полупрозрачная роль лестницы или альфа-аналога (`kind: "translucent"`): `css` — готовое `oklch(L% C H / A)`, `tintHex` — тинт как данные, `alpha`, плюс `compositeHex` / `compositeLc` / `compositeWcag` —
|
|
161
|
+
- `TranslucentRole` — полупрозрачная роль лестницы или альфа-аналога (`kind: "translucent"`): `css` — готовое `oklch(L% C H / A)`, `tintHex` — тинт как данные, `alpha`, плюс `compositeHex` / `compositeLc` / `compositeWcag` — exact encoded-sRGB8 reference-композит на фоне резолва и его контраст. Конкретный renderer и color-management pipeline проверяются отдельно.
|
|
162
|
+
- `GlowRole` — discriminated union. `kind: "glow"` несёт два цвета для
|
|
163
|
+
`mix-blend-mode: screen`: `cssVar` — halo, `${cssVar}-core` — core,
|
|
164
|
+
`${cssVar}-alpha` — каноническая `alphaCss`. `compositeProfile` /
|
|
165
|
+
`compositeGuarantee` описывают exact point-композит отдельно от
|
|
166
|
+
`decisionGuarantee`. `layerRecipeProfile` фиксирует общий рецепт слоёв
|
|
167
|
+
`"cam16-jprime-oklab-cusp-v1"`, а обязательный
|
|
168
|
+
`appearanceDiagnosticProfile` — CAM16 appearance-модель результата. Отдельный
|
|
169
|
+
`selectionDiagnosticProfile` сообщает, применялась ли CAM16-диагностика именно
|
|
170
|
+
при выборе состояния: для exact no-op он равен `null`, для legacy solve —
|
|
171
|
+
`"cam16-ucs-jprime-li2017-v1"`. `targetStatus` различает эти ветви явно:
|
|
172
|
+
`"exact-noop-unreachable"`, `"legacy-reached"` или
|
|
173
|
+
`"legacy-unreachable"`. Determinate-форма — union из этих трёх согласованных
|
|
174
|
+
ветвей: смешать stable/legacy profile, guarantee, selection diagnostic,
|
|
175
|
+
status и `degraded` на уровне TypeScript невозможно. Outward interval не
|
|
176
|
+
входит в Glow capability этого релиза. `kind: "glow-indeterminate"`
|
|
177
|
+
означает, что профиль `stable-v1` не выбрал target/max state без sound bound;
|
|
178
|
+
для такой роли CSS-переменные не эмитятся и legacy fallback не применяется.
|
|
179
|
+
Цель и все `*CompositeHex` / `*AchievedDj` относятся только к изолированным
|
|
180
|
+
point-слоям, а не к полному blur/overlap-эффекту, браузеру или дисплею.
|
|
181
|
+
- `MaterialRole` — union трёх терминальных исходов: satisfied transparent
|
|
182
|
+
endpoint (`alpha = 0`), satisfied bisection bracket (`alpha` побитно равна
|
|
183
|
+
`upperAlpha`) и degraded opaque endpoint (`alpha = 1`). `alphaStatus`,
|
|
184
|
+
`alphaGuarantee` и compatibility-поле `guaranteed` согласованы типом. `floor`
|
|
185
|
+
— запрошенный пол; он держится только при `alphaStatus: "satisfied"`. Primary
|
|
186
|
+
остаётся солид-каноном, `-01` — тинтом, `-02` — опаковой базой. Численный
|
|
187
|
+
профиль явно фиксирует operation order:
|
|
188
|
+
`encoded-srgb-byte-scale-affine-platform-binary64-powf-v1`: original WCAG 2.1
|
|
189
|
+
(2018) split `0.03928`, conservative binary64 channel envelope и обе стороны
|
|
190
|
+
пересечённого EOTF seam. Bracket доступен только после directed-search guard;
|
|
191
|
+
это platform-characterization, а не двухугловая теорема, глобальная
|
|
192
|
+
монотонность, первый passing state или точная минимальная alpha.
|
|
147
193
|
- `NoneRole` — роль намеренно пустая по дизайну (`kind: "none"`), не ошибка.
|
|
148
194
|
- `UnreachableRole` — ни один цвет не удовлетворяет требованиям для этого фона (`kind: "unreachable"`).
|
|
149
195
|
|
|
@@ -159,7 +205,26 @@ type RoleResult = SolvedColor | TranslucentRole | NoneRole | UnreachableRole;
|
|
|
159
205
|
|
|
160
206
|
### `engine.loadConfig(json): string`
|
|
161
207
|
|
|
162
|
-
Загружает конфиг дизайн-системы (JSON по типу `ThemeConfig`; схема — в репозитории: `docs/decisions/0001-config-boundary.md`, TS-типы — в поставляемом `labcolors.d.ts`). Это **единственный** источник словаря ролей — встроенной таблицы в движке нет: до загрузки конфига `resolveTheme` отклоняется ошибкой `config_required`. Полный preflight:
|
|
208
|
+
Загружает конфиг дизайн-системы (JSON по типу `ThemeConfig`; схема — в репозитории: `docs/decisions/0001-config-boundary.md`, TS-типы — в поставляемом `labcolors.d.ts`). Это **единственный** источник словаря ролей — встроенной таблицы в движке нет: до загрузки конфига `resolveTheme` отклоняется ошибкой `config_required`. Полный preflight проверяет не только имена ролей, но и итоговый CSS-namespace: `-core`/`-alpha` Glow и `-01`/`-02` Material не могут быть затёрты другой ролью или алиасом. Невалидный конфиг отклоняется структурной ошибкой `invalid_config: …` и НЕ меняет состояние. Возвращает отпечаток конфига — 16 hex-символов; разные конфиги дают разные отпечатки и разные кэш-пространства.
|
|
209
|
+
|
|
210
|
+
Каждый Glow-рецепт обязан явно выбрать numerical-decision profile; default и
|
|
211
|
+
неявного legacy-пути нет:
|
|
212
|
+
|
|
213
|
+
```json
|
|
214
|
+
{
|
|
215
|
+
"kind": "glow",
|
|
216
|
+
"source": { "kind": "brand" },
|
|
217
|
+
"step": "base",
|
|
218
|
+
"decision_profile": "stable-v1"
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
`stable-v1` возвращает typed `glow-indeterminate`, когда sound bound для
|
|
223
|
+
нетривиального CAM16 target/max-решения недоступен. Если существующая интеграция
|
|
224
|
+
обязана пока сохранить прежнюю CSS-эмиссию, укажите
|
|
225
|
+
`legacy-platform-dependent-v1` явно и обрабатывайте его как compatibility
|
|
226
|
+
profile, а не как численную гарантию. Полная миграция с rollback-порядком — в
|
|
227
|
+
[гайде exact alpha / typed Glow](https://github.com/Labpics-Team/lab-colors/blob/main/docs/migrations/exact-alpha-glow.md).
|
|
163
228
|
|
|
164
229
|
---
|
|
165
230
|
|
|
@@ -175,9 +240,13 @@ type RoleResult = SolvedColor | TranslucentRole | NoneRole | UnreachableRole;
|
|
|
175
240
|
|
|
176
241
|
---
|
|
177
242
|
|
|
178
|
-
### `engine.muddiness(hex): number`
|
|
243
|
+
### `engine.muddiness(hex): number`
|
|
179
244
|
|
|
180
|
-
`muddiness`
|
|
245
|
+
`muddiness` возвращает замороженный числовой выход исторической формулы. Это
|
|
246
|
+
`experimental compatibility proxy`: legacy-имя сохранено для совместимости, но
|
|
247
|
+
значение не является валидированным на наблюдателях человеческим вердиктом
|
|
248
|
+
clean/dirty и не должно использоваться как production decision. Сам диапазон
|
|
249
|
+
`[0, 1]` — свойство формулы, а не шкала человеческого восприятия.
|
|
181
250
|
|
|
182
251
|
---
|
|
183
252
|
|
|
@@ -216,7 +285,7 @@ interface WatchController {
|
|
|
216
285
|
|
|
217
286
|
### `adaptTheme(element, options): AdaptController`
|
|
218
287
|
|
|
219
|
-
Режим с
|
|
288
|
+
Режим с dwell-фильтром: дешёвая проверка каждый кадр, пересчёт и плавный переход только при устойчивом ухудшении контраста. Это один порог с выдержкой, не двухпороговый гистерезис. Применяет немедленно и возвращает контроллер.
|
|
220
289
|
|
|
221
290
|
```ts
|
|
222
291
|
interface AdaptThemeOptions {
|
|
@@ -230,7 +299,7 @@ interface AdaptThemeOptions {
|
|
|
230
299
|
sustainMs?: number; // минимальное время удержания нарушения (по умолчанию 120)
|
|
231
300
|
dwellMs?: number; // минимальный интервал между пересчётами (по умолчанию 250)
|
|
232
301
|
easeMs?: number; // длительность перехода (по умолчанию 280; уменьшается при reduced-motion)
|
|
233
|
-
strict?: boolean; //
|
|
302
|
+
strict?: boolean; // legacy characterized clamp; не universal floor certificate (по умолчанию false)
|
|
234
303
|
reducedMotion?: boolean; // переопределить системную настройку
|
|
235
304
|
}
|
|
236
305
|
|
|
@@ -243,20 +312,37 @@ interface AdaptController {
|
|
|
243
312
|
}
|
|
244
313
|
```
|
|
245
314
|
|
|
315
|
+
`strict` сохраняет прежнее runtime-поведение, но не является доказательством
|
|
316
|
+
минимального или проходящего состояния на каждом кадре: путь
|
|
317
|
+
Oklab→gamut clip→sRGB8 немонотонен. Finite hard-floor-safe replacement ведётся в
|
|
318
|
+
#287; до него этот флаг следует считать compatibility characterization.
|
|
319
|
+
|
|
246
320
|
Управляйте через `start()` (внутренний rAF-цикл) или вызывайте `tick()` из собственного цикла. Смена темы применяется мгновенно — это осознанное намерение, а не дрейф.
|
|
321
|
+
Перед применением результата контроллер проверяет provenance как stable-, так и
|
|
322
|
+
legacy-ветвей Glow. Нетипизированный внешний mock с невозможным сочетанием
|
|
323
|
+
profile/guarantee/diagnostic/status отклоняется `TypeError`; fallback-цвет из
|
|
324
|
+
такого объекта не применяется.
|
|
247
325
|
|
|
248
326
|
---
|
|
249
327
|
|
|
250
328
|
### `effectiveBackground(element, options?): string`
|
|
251
329
|
|
|
252
|
-
Возвращает непрозрачный
|
|
330
|
+
Возвращает непрозрачный reference-`#RRGGBB`, вычисленный для поддерживаемого
|
|
331
|
+
подмножества DOM `background-color`. Это не browser pixel capture и не
|
|
332
|
+
сертификат цвета, который реально видит наблюдатель. Helper обходит цепочку
|
|
333
|
+
предков и композитит распознанные слои поверх `fallback` (по умолчанию белый).
|
|
253
334
|
|
|
254
335
|
```ts
|
|
255
336
|
const bg = effectiveBackground(panel); // например "#0F1014"
|
|
256
337
|
const bg2 = effectiveBackground(panel, { fallback: "#101012" });
|
|
257
338
|
```
|
|
258
339
|
|
|
259
|
-
**Честное ограничение:** работает только с сплошными и
|
|
340
|
+
**Честное ограничение:** работает только с поддерживаемыми сплошными и
|
|
341
|
+
полупрозрачными `background-color`; неподдерживаемый CSS, неполная прозрачная
|
|
342
|
+
цепочка, `background-image`, градиент, blur и video не дают полного наблюдения.
|
|
343
|
+
Текущий compatibility helper ещё может отбросить неподдерживаемый слой или
|
|
344
|
+
использовать fallback; для correctness передайте фон явно. Typed `Unknown`
|
|
345
|
+
replacement принадлежит #283.
|
|
260
346
|
|
|
261
347
|
Дополнительно экспортируются вспомогательные функции для работы со слоями: `parseCssColor`, `compositeOver`, `compositeStackToHex`, `toHex` и `oklabLerp` (перцептуально равномерная интерполяция между двумя hex-значениями — траектория цвета при переходе).
|
|
262
348
|
|
|
@@ -264,19 +350,32 @@ const bg2 = effectiveBackground(panel, { fallback: "#101012" });
|
|
|
264
350
|
|
|
265
351
|
## Размер бандла
|
|
266
352
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
353
|
+
Размер не закреплён в документации приблизительным числом: оно устаревает при
|
|
354
|
+
любом изменении солвера. SSOT — шаг CI `report bundle size (gzip)` в `ci.yml`,
|
|
355
|
+
который для каждого коммита печатает точные raw-байты и результат `gzip -9`
|
|
356
|
+
отдельно для `labcolors_bg.wasm` и wasm-bindgen-обёртки `labcolors.js`.
|
|
357
|
+
|
|
358
|
+
Это весь движок: CAM16, солверы контраста, лестницы и граница конфига. `.wasm`
|
|
359
|
+
поставляется отдельным ассетом. Будет ли его загрузка критическим путём первого
|
|
360
|
+
рендера, определяет интеграция: до первого `resolveTheme` инициализация обязана
|
|
361
|
+
завершиться; приложение может preload/кэшировать модуль. JS-хелперы
|
|
362
|
+
(`applyTheme`, `watchTheme`, `adaptTheme`, `effectiveBackground`) имеют
|
|
363
|
+
именованные экспорты и допускают tree-shaking, но их размер также следует мерить
|
|
364
|
+
сборкой, а не описывать приблизительно.
|
|
365
|
+
|
|
366
|
+
Release packer закреплён на Node 24.14/npm 11.9; это не consumer floor.
|
|
367
|
+
Публичный контракт `Node >=22.11.0` независимо прогоняется отдельным CI job. Browser-
|
|
368
|
+
матрица использует прямую передачу wasm-байтов в `init({ module_or_path })` и
|
|
369
|
+
headless Chrome из CI. ESM/URL-обёртка генерируется wasm-pack, но совместимость
|
|
370
|
+
с конкретной версией Vite, webpack, Next или другим браузером не заявляется без
|
|
371
|
+
отдельного smoke-гейта.
|
|
277
372
|
|
|
278
373
|
### Для аудиторов цепочки поставки
|
|
279
374
|
|
|
375
|
+
- **Build metadata:** экспорт `@labpics/colors/build-metadata.json` декларирует
|
|
376
|
+
source SHA и conformance pack для установленного WASM; verifier отклоняет
|
|
377
|
+
любое лишнее, отсутствующее или несовпадающее поле. Объект не подписан и не
|
|
378
|
+
заменяет отключённую npm/Sigstore provenance-аттестацию.
|
|
280
379
|
- **Network access (Socket и др.):** единственный `fetch` в пакете (`pkg/labcolors.js`) загружает СОБСТВЕННЫЙ `.wasm`-файл пакета при `init(url)` — стандартный лоадер wasm-bindgen. Ни внешних адресов, ни отправки данных, ни исполнения при импорте. В node-пути (передача байтов) `fetch` не вызывается.
|
|
281
|
-
- **Bundlephobia `BuildError`:** их webpack-конвейер не умеет `.wasm`-ассеты («loader customization needed») — так падает почти любой WASM-пакет.
|
|
282
|
-
- **Zero runtime JS-dependencies:** npm-поле `dependencies` пусто — транзитивной JS/npm-цепочки поставки нет. Rust-крейты сборки (`serde`, `serde_json` и др.) компилируются ВНУТРЬ `.wasm` (учтены
|
|
380
|
+
- **Bundlephobia `BuildError`:** их webpack-конвейер не умеет `.wasm`-ассеты («loader customization needed») — так падает почти любой WASM-пакет. Реальный размер конкретного коммита показывает CI-шаг `report bundle size (gzip)`.
|
|
381
|
+
- **Zero runtime JS-dependencies:** npm-поле `dependencies` пусто — транзитивной JS/npm-цепочки поставки нет. Rust-крейты сборки (`serde`, `serde_json` и др.) компилируются ВНУТРЬ `.wasm` (учтены CI-замером); их цепочка аудируется на стороне сборки — `cargo audit` (RustSec) в CI lab-colors.
|
package/adapt-theme.d.ts
CHANGED
|
@@ -4,14 +4,16 @@ import type { LabColors, ThemeName } from "./pkg/labcolors.js";
|
|
|
4
4
|
|
|
5
5
|
export interface AdaptThemeOptions {
|
|
6
6
|
/**
|
|
7
|
-
* An initialised engine — needs
|
|
7
|
+
* An initialised engine — needs resolve + contrast recheck. The exact
|
|
8
|
+
* `isStableGlowPointNoop` capability is conditionally required when a result
|
|
9
|
+
* contains a stable Glow role; its absence then fails explicitly.
|
|
8
10
|
* `recheckContrastMulti` is optional: when present, a multi-sample backdrop
|
|
9
11
|
* is rechecked in ONE batched call per frame (byte-identical to the
|
|
10
12
|
* per-sample loop, locked by the wasm boundary parity test); when absent,
|
|
11
13
|
* the controller falls back to N `recheckContrast` calls.
|
|
12
14
|
*/
|
|
13
15
|
colors: Pick<LabColors, "resolveTheme" | "recheckContrast"> &
|
|
14
|
-
Partial<Pick<LabColors, "recheckContrastMulti">>;
|
|
16
|
+
Partial<Pick<LabColors, "recheckContrastMulti" | "isStableGlowPointNoop">>;
|
|
15
17
|
theme: ThemeName;
|
|
16
18
|
/**
|
|
17
19
|
* Explicit effective background, overriding the ancestor-composite. A single
|
|
@@ -34,10 +36,10 @@ export interface AdaptThemeOptions {
|
|
|
34
36
|
/** Crossfade duration in ms. Default `280` (capped to a short fade under reduced motion). */
|
|
35
37
|
easeMs?: number;
|
|
36
38
|
/**
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
* Default `false
|
|
39
|
+
* Enable the legacy characterized per-frame clamp. The current
|
|
40
|
+
* Oklab→clip→sRGB8 path is not globally monotone, so this option is not a
|
|
41
|
+
* universal floor/least-blend certificate; #287 owns the finite replacement.
|
|
42
|
+
* Default `false`.
|
|
41
43
|
*/
|
|
42
44
|
strict?: boolean;
|
|
43
45
|
/** Override reduced-motion detection (default reads `matchMedia`). */
|