@labpics/colors 0.5.0 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
 # @labpics/colors
 
-Адаптивные цветовые роли для дизайн-системы. Получает фоновый цвет и тему — возвращает полный набор ролей (`--lab-label-primary`, `--lab-icon`, `--lab-border-base`, …) как `#RRGGBB`-значения CSS-переменных. Ядро написано на Rust и скомпилировано в WebAssembly; пакет не имеет runtime-зависимостей.
+Адаптивные цветовые роли для дизайн-системы. Получает фоновый цвет и тему — возвращает полный набор ролей (`--lab-label-primary`, `--lab-icon`, `--lab-border-base`, …). CSS-переменные несут готовое значение `oklch(L% C H)` (для полупрозрачных ролей — `oklch(L% C H / A)`); сырой `#RRGGBB` остаётся данными роли (`roles.<ключ>.hex`). Ядро написано на Rust и скомпилировано в WebAssembly; пакет не имеет runtime-зависимостей.
 
 Ядро возвращает **данные**, не затрагивает DOM. Три вспомогательные функции переводят эти данные в живые CSS-переменные: `applyTheme` (разовое применение), `watchTheme` (реактивное — обновляется при изменении фона) и `adaptTheme` (плавная адаптация для фона, меняющегося каждый кадр).
 
@@ -33,8 +33,9 @@ await init();                       // загрузить WASM-модуль (о
 const engine = new LabColors();     // движок по умолчанию
 
 const result = engine.resolveTheme("#FFFFFF", "light");
-// result.vars  → { "--lab-label-primary": "#1a1a1a", "--lab-icon": "#5b5b5b", ... }
-// result.roles → детали каждой роли (hex, контраст, флаги)
+// result.vars  → { "--lab-label-primary": "oklch(14.79140% 0.012878 284.717)",
+//                  "--lab-icon": "oklch(66.97448% 0.014606 285.999)", ... }
+// result.roles → детали каждой роли (css, hex, контраст, флаги)
 
 applyTheme(document.documentElement, result);   // записать все --lab-* в элемент
 ```
@@ -128,16 +129,17 @@ adaptTheme(hero, {
 interface ResolvedTheme {
   theme: ThemeName;
   background: string;                     // нормализованный #RRGGBB
-  vars: Record<string, string>;           // достижимые роли: "--lab-<ключ>" → hex
+  vars: Record<string, string>;           // достижимые роли: "--lab-<ключ>" → готовое CSS-значение oklch
   roles: Record<string, RoleResult>;      // все роли с деталями
 }
 
-type RoleResult = SolvedColor | NoneRole | UnreachableRole;
+type RoleResult = SolvedColor | TranslucentRole | NoneRole | UnreachableRole;
 ```
 
-Каждая роль — одно из трёх состояний:
+Каждая роль — одно из четырёх состояний:
 
-- `SolvedColor` — цвет найден (`kind: "color"`, поля `hex`, `lc`, `wcagRatio`, …).
+- `SolvedColor` — цвет найден (`kind: "color"`, поля `css` — готовое `oklch(L% C H)`, `hex` — тот же цвет как данные, `lc`, `wcagRatio`, …).
+- `TranslucentRole` — полупрозрачная роль лестницы или альфа-аналога (`kind: "translucent"`): `css` — готовое `oklch(L% C H / A)`, `tintHex` — тинт как данные, `alpha`, плюс `compositeHex` / `compositeLc` / `compositeWcag` — солид-композит на фоне резолва и его контраст (браузер композитит тинт на живой подложке).
 - `NoneRole` — роль намеренно пустая по дизайну (`kind: "none"`), не ошибка.
 - `UnreachableRole` — ни один цвет не удовлетворяет требованиям для этого фона (`kind: "unreachable"`).
 
@@ -150,6 +152,24 @@ type RoleResult = SolvedColor | NoneRole | UnreachableRole;
 
 ---
 
+### `engine.loadConfig(json): string`
+
+Загружает конфиг дизайн-системы (JSON по типу `ThemeConfig`) — главная фича конфиг-границы: движок начинает эмитить роли и подтон конфига вместо встроенной таблицы. Полный preflight: невалидный конфиг отклоняется структурной ошибкой `invalid_config: …` и НЕ меняет состояние. Возвращает отпечаток конфига — 16 hex-символов; разные конфиги дают разные отпечатки и разные кэш-пространства.
+
+---
+
+### `engine.recheckContrast(bgHex, fgHexes, theme): Float64Array`
+
+Дешёвая покадровая проверка: какие контрасты дают цвета `fgHexes` на фоне `bgHex` под темой `theme`, без полного резолва (один прямой ход модели на фон плюс по одному на каждый передний план). Возвращает `Float64Array` пар `[lc, wcagRatio]` в порядке `fgHexes`: индекс `2·i` — знаковый `Lc` цвета `i`, `2·i+1` — его WCAG-отношение. Это примитив, которым `adaptTheme` решает, пора ли пересчитывать.
+
+---
+
+### `engine.muddiness(hex): number` · `engine.confidence(hex): number`
+
+`muddiness` — оценка «грязи» цвета `hex` в диапазоне `[0, 1]` (Закон Грязи). `confidence` — надёжность этой оценки: `0` означает, что оценке нельзя доверять (у границы решения или серого фронтира), выше — увереннее. Верхний потолок — деталь калибровки, не контракт: не хардкодить.
+
+---
+
 ### `applyTheme(element, result): void`
 
 Записывает все достижимые роли из `result.vars` в `element.style` через `setProperty`. Устаревшие `--lab-*` от предыдущего вызова сбрасываются перед записью — роль, потерявшая достижимость, не остаётся висеть.
@@ -168,6 +188,7 @@ interface WatchThemeOptions {
   target?: HTMLElement;                  // куда писать переменные (по умолчанию: element)
   fallback?: string;                     // фон при полностью прозрачной цепочке (по умолчанию "#FFFFFF")
   observe?: boolean;                     // авто-обновление при DOM-мутациях (по умолчанию true)
+  root?: Node;                           // корень MutationObserver (по умолчанию: documentElement)
 }
 
 interface WatchController {
@@ -232,10 +253,12 @@ const bg2 = effectiveBackground(panel, { fallback: "#101012" });
 
 ## Размер бандла
 
-| Артефакт | raw | gzip | brotli |
-|----------|-----|------|--------|
-| `labcolors_bg.wasm` | ~313 КБ | ~138 КБ | ~116 КБ |
-| `labcolors.js` (JS-обёртка) | ~17 КБ | ~4 КБ | ~4 КБ |
+| Артефакт | raw | gzip |
+|----------|-----|------|
+| `labcolors_bg.wasm` | ~313 КБ | ~138 КБ |
+| `labcolors.js` (JS-обёртка) | ~17 КБ | ~4 КБ |
+
+Замер CI-шага `report bundle size` (ci.yml) — raw и gzip.
 
 Это ВЕСЬ движок: перцептивная модель CAM16, солверы контраста, лестницы, граница конфига. `.wasm` — не JS-байты бандла, а ассет: он **не на критическом пути рендера** — грузится параллельно, компилируется потоково вне главного треда, кэшируется браузером после первой загрузки. Вспомогательные функции (`applyTheme`, `watchTheme`, `adaptTheme`, `effectiveBackground`) — несколько сотен байт чистого JavaScript с tree-shaking через именованные экспорты.
 

package/adapt-theme.js

@@ -150,6 +150,12 @@ export function adaptTheme(element, options) {
   let theme = options.theme;
   /** @type {{ cssVar: string, key: string, lc: number, hex: string, legalFloor: number|null }[]} stable role order */
   let roles = [];
+  /** Full canonical var set from the last solve — the `result.vars` of EVERY
+   * reachable role (color AND translucent), each an oklch string. Every apply is
+   * `applyTheme(target, {...baseVars, ...easedColorOverlay})`, so translucent
+   * roles are never dropped by `applyTheme`'s clear-then-write and always carry
+   * the current theme's value. Only `kind === "color"` roles (in `roles`) ease. */
+  let baseVars = {};
   /** @type {Map<string,{from:string,to:string}>} in-flight ease per cssVar */
   let easing = new Map();
   let easeStart = 0;
@@ -209,6 +215,9 @@ export function adaptTheme(element, options) {
   // Resolve a fresh set and adopt it as the current colours (no ease).
   const solveAndAdopt = (bg, now) => {
     const result = colors.resolveTheme(bg, theme);
+    // Carry the FULL canonical var set (color + translucent) so no reachable
+    // role is dropped by a subsequent apply; only color roles feed the ease.
+    baseVars = result.vars && typeof result.vars === "object" ? result.vars : {};
     roles = Object.entries(result.roles)
       .filter(([, r]) => r && r.kind === "color")
       .map(([key, r]) => ({
@@ -241,13 +250,15 @@ export function adaptTheme(element, options) {
     }
   };
 
-  const applyHexes = (hexByVar) => applyTheme(target, { vars: hexByVar });
+  // Every write goes through the full canonical set with the (optional) eased
+  // color overlay on top — so translucent roles in `baseVars` persist through
+  // `applyTheme`'s clear-then-write, and non-eased color roles keep their
+  // canonical oklch form. `overlay` carries only in-flight color roles as hex.
+  const applyHexes = (overlay) => applyTheme(target, { vars: { ...baseVars, ...overlay } });
 
-  const applyRolesDirect = () => {
-    const vars = {};
-    for (const r of roles) vars[r.cssVar] = r.hex;
-    applyHexes(vars);
-  };
+  // Apply the canonical set as-is (no ease in flight): color roles show their
+  // oklch form, translucent roles their tint+alpha.
+  const applyRolesDirect = () => applyHexes({});
 
   // Begin an ease from the currently-applied colours toward the role colours.
   // `held` latches the per-role displayed blend so it only ever advances toward
@@ -289,15 +300,29 @@ export function adaptTheme(element, options) {
 
   const stepEase = (now, samples) => {
     const t = easeMs <= 0 ? 1 : (now - easeStart) / easeMs;
+    // Terminate the ease when it is done (`t >= 1`) OR when the clock went
+    // non-finite (a NaN/±∞ `now` making `t` non-finite): drop the segments and
+    // re-apply the canonical set, so the just-eased color roles snap back from
+    // their interpolated hex to their oklch form (translucent roles stay put).
+    // The non-finite guard is load-bearing for STATE, not just paint: without it
+    // a persistently bad clock would leave `easing` in flight forever, freezing
+    // color roles at their hex destination and never reverting to canonical
+    // oklch. (`easeOut` separately guards the interpolation math from
+    // `#NANNANNAN`; this guards the controller's easing state.)
+    if (t >= 1 || !Number.isFinite(t)) {
+      easing = new Map();
+      applyRolesDirect();
+      return;
+    }
     const e = easeOut(t);
     const bgLums = strict ? samples.map(relativeLuminanceHex) : null;
-    const vars = {};
+    // Overlay carries ONLY in-flight color roles (as interpolated hex); every
+    // other role — non-eased color and all translucent — keeps its canonical
+    // `baseVars` value under the merge in `applyHexes`.
+    const overlay = {};
     for (const r of roles) {
       const seg = easing.get(r.cssVar);
-      if (!seg) {
-        vars[r.cssVar] = r.hex;
-        continue;
-      }
+      if (!seg) continue;
       let blend = e;
       if (strict && r.legalFloor != null) {
         // Hold the floor (against the worst sample), then LATCH: the displayed
@@ -311,17 +336,19 @@ export function adaptTheme(element, options) {
         blend = Math.max(floorBlend(seg, e, bgLums, r.legalFloor), seg.held);
         seg.held = blend;
       }
-      vars[r.cssVar] = lerpHex(seg.from, seg.to, blend);
+      overlay[r.cssVar] = lerpHex(seg.from, seg.to, blend);
     }
-    applyHexes(vars);
-    if (t >= 1) easing = new Map();
+    applyHexes(overlay);
   };
 
+  // The full applied picture: the canonical set (color + translucent) with each
+  // in-flight color role reported at its LOGICAL target (`seg.to`), so a reader
+  // sees where the ease is going, not a mid-transition frame.
   const currentApplied = () => {
-    const vars = {};
+    const vars = { ...baseVars };
     for (const r of roles) {
       const seg = easing.get(r.cssVar);
-      vars[r.cssVar] = seg ? seg.to : r.hex; // logical target during/after ease
+      if (seg) vars[r.cssVar] = seg.to;
     }
     return vars;
   };

package/effective-bg.d.ts

@@ -29,11 +29,13 @@ export declare function compositeOver(top: Rgba, bottom: Rgba): Rgba;
 export declare function toHex(rgb: Rgba | [number, number, number]): string;
 
 /**
- * Interpolate two `#RRGGBB` colours in Oklab at `t ∈ [0,1]` → `#RRGGBB`.
- * Perceptually uniform (even crossfade timing, non-muddy chroma path); endpoints
- * are exact and out-of-gamut intermediates are clamped per channel.
+ * Interpolate two colours in Oklab at `t ∈ [0,1]` → `#RRGGBB`. `from`/`to` may be
+ * any string `parseCssColor` accepts (`#hex`, `rgb()`/`rgba()`, `oklch()`,
+ * `transparent`), not only `#RRGGBB`. Perceptually uniform (even crossfade timing,
+ * non-muddy chroma path); endpoints are exact and out-of-gamut intermediates are
+ * clamped per channel.
  */
-export declare function oklabLerp(fromHex: string, toHex_: string, t: number): string;
+export declare function oklabLerp(from: string, to: string, t: number): string;
 
 /** Composite an ordered front-to-back layer stack over an opaque base → `#RRGGBB`. */
 export declare function compositeStackToHex(layersFrontToBack: Rgba[], opaqueBase: Rgba): string;

package/effective-bg.js

@@ -18,15 +18,36 @@
 // `background` option of `watchTheme`, or a sampled average). What it does cover —
 // translucent panels over solid parents — is the common case and is composited
 // *correctly* (true source-over alpha), not approximated.
+//
+// COLOUR FORMS: `parseCssColor` reads the forms this package actually meets —
+// `#hex`, `rgb()/rgba()` (legacy comma and modern space/slash), `transparent`,
+// and `oklch()` (the engine's OWN emission form since 0.4.0, and what a browser
+// serialises `background-color` back to for an oklch-painted surface). Other
+// modern forms — `lab()`, `lch()`, `color(srgb …)`, `color-mix()`, `hsl()`,
+// named colours beyond `transparent` — are NOT parsed and return `null` (a
+// dropped layer). If a surface's background is authored in one of those, pass the
+// effective background explicitly via the `background` option.
 
 /** @typedef {[number, number, number, number]} Rgba  r,g,b in 0..255, a in 0..1 */
 
 /**
  * Parse a CSS colour string into `[r, g, b, a]`, or `null` if unrecognised.
  *
- * Handles the forms computed style actually yields (`rgb(r, g, b)`,
- * `rgba(r, g, b, a)`, the modern `rgb(r g b / a)`) plus `#rgb`/`#rrggbb` and the
- * `transparent` keyword. Unknown keywords return `null` (treated as "no layer").
+ * Handles the forms computed style actually yields:
+ *   - `rgb(r, g, b)` / `rgba(r, g, b, a)` and the modern `rgb(r g b / a)`;
+ *   - `#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`;
+ *   - the `transparent` keyword;
+ *   - `oklch(L C H)` / `oklch(L C H / A)` — the engine's own emission form and
+ *     what a browser serialises an oklch-painted `background-color` back to.
+ *     `L` accepts both a `0..1` number (Chrome's computed form) and a percentage
+ *     (the engine's literal form); `C` a number or a `%` (100% = 0.4 per CSS
+ *     Color 4); `H` degrees (bare or `deg`-suffixed); a missing component
+ *     (`none`) is 0. Conversion to sRGB bytes reuses the file's Oklab↔sRGB
+ *     transform and is byte-exact to the core's round-trip proof.
+ *
+ * Any other form — `lab()`, `lch()`, `color(srgb …)`, `color-mix()`, `hsl()`,
+ * named colours other than `transparent` — returns `null` (treated as "no
+ * layer"); supply such backgrounds explicitly via the `background` option.
  *
  * @param {string} css
  * @returns {Rgba | null}
@@ -36,6 +57,8 @@ export function parseCssColor(css) {
   const s = css.trim().toLowerCase();
   if (s === "transparent") return [0, 0, 0, 0];
 
+  if (s.startsWith("oklch(") && s.endsWith(")")) return parseOklch(s.slice(6, -1));
+
   if (s[0] === "#") {
     const h = s.slice(1);
     if (h.length === 3 || h.length === 4) {
@@ -73,6 +96,83 @@ function clamp255(v) {
   return Math.min(255, Math.max(0, v));
 }
 
+/**
+ * Parse the inside of an `oklch(...)` (the part between the parens) into sRGB
+ * `[r, g, b, a]`, or `null` on any malformed component.
+ *
+ * The engine emits `oklch(L% C H)` / `oklch(L% C H / A)`; a browser's computed
+ * form is `oklch(<L 0..1> C H [/ A])`. Components are whitespace-separated with
+ * an optional `/`-separated alpha, exactly like `rgb()`'s modern syntax.
+ * oklch → Oklab is `a = C·cos(H)`, `b = C·sin(H)`; then the file's own
+ * `oklabToLinearRgb` + `linearToSrgb` land it in sRGB — the SAME transform (and
+ * the SAME clamp-then-round the core uses in `hex_from_srgb`) that carries the
+ * emitter's byte-exact round-trip, so an emitted string decodes to its source
+ * bytes. Out-of-gamut channels clamp per channel, matching `oklabLerp`/`toHex`.
+ *
+ * @param {string} inner  the text between `oklch(` and `)`
+ * @returns {Rgba | null}
+ */
+function parseOklch(inner) {
+  const slash = inner.indexOf("/");
+  const lch = (slash >= 0 ? inner.slice(0, slash) : inner).trim();
+  const alphaTok = slash >= 0 ? inner.slice(slash + 1).trim() : null;
+  const comps = lch.split(/\s+/).filter((p) => p.length > 0);
+  if (comps.length !== 3) return null;
+
+  const L = oklchLightness(comps[0]);
+  const C = oklchChroma(comps[1]);
+  const H = oklchHue(comps[2]);
+  const a = alphaTok === null ? 1 : oklchAlpha(alphaTok);
+  if (L === null || C === null || H === null || a === null) return null;
+
+  const hRad = (H * Math.PI) / 180;
+  const lin = oklabToLinearRgb(L, C * Math.cos(hRad), C * Math.sin(hRad));
+  const byte = (i) => Math.round(clamp255(linearToSrgb(lin[i]) * 255));
+  return [byte(0), byte(1), byte(2), a];
+}
+
+/** Strict CSS `<number>` (no trailing junk, unlike `parseFloat`), else `null`. */
+function cssNumber(tok) {
+  return /^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i.test(tok) ? parseFloat(tok) : null;
+}
+
+/** L: a percentage → `/100` into `0..1`; a bare number is already `0..1`; `none`
+ * → 0. Lightness clamps to `[0, 1]` (CSS Color 4) — a byte-level clamp alone
+ * masks out-of-range L only at low chroma, not high, so clamp L explicitly. */
+function oklchLightness(tok) {
+  if (tok === "none") return 0;
+  const pct = tok.endsWith("%");
+  const n = cssNumber(pct ? tok.slice(0, -1) : tok);
+  if (n === null) return null;
+  return Math.min(1, Math.max(0, pct ? n / 100 : n));
+}
+
+/** C: a bare number is absolute chroma; a percentage is a fraction of 0.4
+ * (CSS Color 4: 100% = 0.4); `none` → 0. Negative chroma clamps to 0. */
+function oklchChroma(tok) {
+  if (tok === "none") return 0;
+  const pct = tok.endsWith("%");
+  const n = cssNumber(pct ? tok.slice(0, -1) : tok);
+  if (n === null) return null;
+  return Math.max(0, pct ? (n / 100) * 0.4 : n);
+}
+
+/** H: degrees, bare or `deg`-suffixed; `none` → 0. (grad/rad/turn are out of
+ * scope — the engine and browsers emit bare degrees.) */
+function oklchHue(tok) {
+  if (tok === "none") return 0;
+  return cssNumber(tok.endsWith("deg") ? tok.slice(0, -3) : tok);
+}
+
+/** Alpha: a number `0..1` or a percentage; `none` → 0; clamped to `[0, 1]`. */
+function oklchAlpha(tok) {
+  if (tok === "none") return 0;
+  const pct = tok.endsWith("%");
+  const n = cssNumber(pct ? tok.slice(0, -1) : tok);
+  if (n === null) return null;
+  return Math.min(1, Math.max(0, pct ? n / 100 : n));
+}
+
 /**
  * Source-over composite of `top` onto `bottom` (Porter-Duff "over").
  *
@@ -156,23 +256,25 @@ function oklabToLinearRgb(L, A, B) {
 }
 
 /**
- * Interpolate two `#RRGGBB` colours in Oklab at `t ∈ [0,1]`, returning `#RRGGBB`.
+ * Interpolate two colours in Oklab at `t ∈ [0,1]`, returning `#RRGGBB`.
  *
- * Perceptually uniform: equal steps in `t` are equal steps in perceived
- * lightness (and a straight, non-muddy path in hue/chroma), so a crossfade feels
- * even rather than lingering bright. Endpoints are returned exactly (`t ≤ 0` →
- * `from`, `t ≥ 1` → `to`, both re-normalised through `toHex`); out-of-gamut
+ * `from`/`to` may be ANY string `parseCssColor` accepts (`#rgb`/`#rrggbb`,
+ * `rgb()`/`rgba()`, `oklch()`, `transparent`) — not only `#RRGGBB`. Perceptually
+ * uniform: equal steps in `t` are equal steps in perceived lightness (and a
+ * straight, non-muddy path in hue/chroma), so a crossfade feels even rather than
+ * lingering bright. Endpoints are returned exactly (`t ≤ 0` → `from`, `t ≥ 1` →
+ * `to`), always normalised to `#RRGGBB` through `toHex`; out-of-gamut
  * intermediates are clamped per channel. Unparseable input falls back to the
- * nearer endpoint.
+ * nearer parseable endpoint.
  *
- * @param {string} fromHex
- * @param {string} toHex_
+ * @param {string} from  any colour string `parseCssColor` accepts
+ * @param {string} to    any colour string `parseCssColor` accepts
  * @param {number} t
- * @returns {string}
+ * @returns {string} a `#RRGGBB` string
  */
-export function oklabLerp(fromHex, toHex_, t) {
-  const a = parseCssColor(fromHex);
-  const b = parseCssColor(toHex_);
+export function oklabLerp(from, to, t) {
+  const a = parseCssColor(from);
+  const b = parseCssColor(to);
   if (!a || !b) return (b && t >= 0.5) || !a ? (b ? toHex(b) : "#000000") : toHex(a);
   if (t <= 0) return toHex(a);
   if (t >= 1) return toHex(b);

package/index.d.ts

@@ -14,6 +14,7 @@ export {
 export type {
   ThemeName,
   SolvedColor,
+  TranslucentRole,
   NoneRole,
   UnreachableRole,
   RoleResult,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@labpics/colors",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Framework-agnostic contrast engine: resolve accessible, perceptually-anchored colour roles for any background. WASM core, zero runtime dependencies.",
   "type": "module",
   "license": "MIT",

package/pkg/labcolors.d.ts

@@ -19,6 +19,17 @@ export interface SolvedColor {
     readonly wcagRatio: number;
     /** The legal floor squeezed this role onto the smallest step below its senior. */
     readonly compressed: boolean;
+    /**
+     * `true` when a coloured family label (M1) lost perceptible colour on its
+     * contract-solved lightness: the colour's M′ fell below the tint perceptibility
+     * floor, so at the family curve's extremes (near-white / near-black) the hue is
+     * physically indistinguishable. An honest, flagged outcome — not a silent
+     * degradation to grey. `false` for neutral labels and coloured labels that kept
+     * a distinguishable colour.
+     */
+    readonly hueVanished: boolean;
+    /** Честный замер |ΔJ'| на отданном hex для dJ'-ролей; null у контраст-ролей (метрика — lc). */
+    readonly achievedDj: number | null;
     /** The WCAG floor overrode the perceptual target. */
     readonly floorOverride: boolean;
     /**
@@ -60,11 +71,48 @@ export interface TranslucentRole {
     readonly compositeLc: number;
     /** WCAG 2.1 ratio of the composite. */
     readonly compositeWcag: number;
+    /**
+     * `true` when the requested alpha was raised to the smallest resolvable value
+     * (α_min) because the requested transparency is not reproducible in gamut — an
+     * honest, flagged contract degradation (mirrors `SolvedColor.compressed` /
+     * `GlowRole.degraded`). The colour never lies: the composite still equals the
+     * target solid byte-for-byte; only `alpha` differs from what was asked. Always
+     * `false` for a direct ladder emission.
+     */
+    readonly alphaCoerced: boolean;
+    /**
+     * `true` when a solid family border (`border-<family>-strong`, M2) was darkened
+     * along the family curve to meet the AA UI floor (3:1), because the raw family
+     * tint did not clear it on this background — an honest, flagged minimal legal
+     * shift (family hue/chroma preserved, only lightness moved). `false` for a
+     * direct ladder emission and for legal family solids.
+     */
+    readonly floorCoerced: boolean;
     /** Ready-to-serve CSS value: "oklch(L% C H / A)". `vars` carries the same string. */
     readonly css: string;
 }
 
-export type RoleResult = SolvedColor | TranslucentRole | NoneRole | UnreachableRole;
+/** Свечение (kind glow, labui ADR-0002 §5): screen-слои + решённая интенсивность.
+ *  Потребитель красит слои с mix-blend-mode: screen; `vars` несёт
+ *  --lab-<role> (halo, oklch), --lab-<role>-core и --lab-<role>-alpha. */
+export interface GlowRole {
+    readonly kind: "glow";
+    readonly cssVar: string;
+    /** Слой пересвета (малый радиус), #RRGGBB. */
+    readonly coreHex: string;
+    /** Слой ореола — источник, #RRGGBB. */
+    readonly haloHex: string;
+    /** Интенсивность screen-слоя, (0, 1]. */
+    readonly alpha: number;
+    /** Фактический |ΔJ'| композита от фона. */
+    readonly achievedDj: number;
+    /** Цель недостижима — ближайший достижимый шаг (ADR-0002, закон 2). */
+    readonly degraded: boolean;
+    /** Ready-to-serve CSS value халo: "oklch(L% C H)". */
+    readonly css: string;
+}
+
+export type RoleResult = SolvedColor | TranslucentRole | GlowRole | NoneRole | UnreachableRole;
 
 /** Пер-темная четвёрка якорных hex (light / dark / light-ic / dark-ic). */
 export interface ThemeAnchors {
@@ -87,11 +135,23 @@ export type RoleRecipe =
 | { kind: "dj-anchor"; light: number; dark: number }
 | { kind: "decorative-lc"; magnitude: number }
 | { kind: "ladder"; source: LadderSource; position: string }
+| { kind: "glow"; source: LadderSource; step: "subtle" | "base" | "bloom" }
+| { kind: "pair-fill"; source: LadderSource }
 | { kind: "alpha-analog"; of: LadderSource; alpha: number }
 | { kind: "zero" };
 
+/** Именованный пресет ролей. Тонкий конфиг несёт `preset` вместо простыни `roles`. */
+export type RolePreset = "labui";
+
 /** Полный конфиг дизайн-системы клиента — вход loadConfig (JSON.stringify(config)). */
 export interface ThemeConfig {
+    /**
+     * Пресет ролей: наполняет словарь дизайн-системы целиком, чтобы клиент вносил
+     * ТОЛЬКО значения (якоря, ручки), не семантику. Тонкий конфиг задаёт `preset` и
+     * ОПУСКАЕТ `roles`/`aliases`. Задать `preset` вместе с непустыми `roles` —
+     * ошибка `invalid_config` (оверрайд отдельных ролей — не этот слой).
+     */
+    readonly preset?: RolePreset;
     readonly brand: ThemeAnchors;
     readonly neutral: {
         readonly anchors: { light: string; mid: string; dark: string };
@@ -116,7 +176,8 @@ export interface ThemeConfig {
         readonly chroma_fraction: number;
     };
     readonly themes: ReadonlyArray<{ name: string; preset: "srgb" | "dim" | "srgb-ic" | "dim-ic" }>;
-    readonly roles: ReadonlyArray<{ name: string; recipe: RoleRecipe }>;
+    /** Опускается в тонком конфиге (задан `preset`); иначе — полный словарь ролей. */
+    readonly roles?: ReadonlyArray<{ name: string; recipe: RoleRecipe }>;
     readonly aliases?: ReadonlyArray<{ alias: string; target: string }>;
 }
 
@@ -143,28 +204,22 @@ export interface ResolvedTheme {
 
 
 /**
- * A configured contrast engine. Construct with [`LabColors::new`], then call
- * [`resolve_theme`](LabColors::resolve_theme) many times; identical calls are
- * served from the contract cache.
+ * A contrast engine over a consumer-supplied design system. Construct with
+ * [`LabColors::new`], load a config with [`loadConfig`](LabColors::load_config),
+ * then call [`resolve_theme`](LabColors::resolve_theme) many times; identical
+ * calls are served from the contract cache.
  */
 export class LabColors {
     free(): void;
     [Symbol.dispose](): void;
-    /**
-     * Calculate a relative confidence score for the [`muddiness`](Self::muddiness)
-     * call on an sRGB hex colour: `0` means the call is unreliable (near the
-     * decision boundary or the grey frontier), higher means more confident.
-     * The practical ceiling is an internal calibration detail, not a public
-     * contract — do not hardcode an upper bound against this value.
-     */
-    confidence(hex: string): number;
     /**
      * Загрузить конфиг дизайн-системы (JSON по типу `ThemeConfig` из `.d.ts`).
      *
      * Полный preflight движка: невалидный конфиг отклоняется структурной
      * ошибкой `invalid_config: …` и НЕ меняет состояние. После успешной
      * загрузки `resolveTheme` эмитит роли конфига (включая полупрозрачные
-     * `rgba`-роли лестницы). Возвращает отпечаток конфига — 16 hex-символов;
+     * роли лестницы — эмиссия `oklch(L% C H / α)`). Возвращает отпечаток
+     * конфига — 16 hex-символов;
      * разные конфиги дают разные отпечатки (и разные кэш-пространства).
      */
     loadConfig(json: string): string;
@@ -173,12 +228,11 @@ export class LabColors {
      */
     muddiness(hex: string): number;
     /**
-     * Create a zero-config engine on the default role table and the default
-     * per-theme viewing conditions.
+     * Create an engine with no design system loaded.
      *
-     * `v1` takes no config; the brand/anchor seam is left for a future
-     * version. Adding an optional config object later is additive — it does
-     * not change this signature.
+     * The engine is agnostic (ADR-0001): it carries no built-in role table, so
+     * [`resolveTheme`](LabColors::resolve_theme) rejects with `config_required`
+     * until [`loadConfig`](LabColors::load_config) supplies a design system.
      */
     constructor();
     /**
@@ -198,12 +252,12 @@ export class LabColors {
      * Resolve every role for `bgHex` under `theme` (`"light" | "dark" |
      * "light-ic" | "dark-ic"`).
      *
-     * Returns a [`ResolvedTheme`] object. Per-role unreachability is part of a
+     * Returns a `ResolvedTheme` object. Per-role unreachability is part of a
      * successful result (each role carries its own `kind`); only whole-call
-     * failures reject (invalid hex, unknown theme, and the
-     * by-construction-unreachable oklch serialisation failure as
-     * `internal_error`) — as a structured `"<code>: <message>"` error,
-     * never an unwound panic.
+     * failures reject (no config loaded yet as `config_required`, invalid hex,
+     * unknown theme, and the by-construction-unreachable oklch serialisation
+     * failure as `internal_error`) — as a structured `"<code>: <message>"`
+     * error, never an unwound panic.
      */
     resolveTheme(bg_hex: string, theme: string): ResolvedTheme;
 }
@@ -213,7 +267,6 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_labcolors_free: (a: number, b: number) => void;
-    readonly labcolors_confidence: (a: number, b: number, c: number, d: number) => void;
     readonly labcolors_loadConfig: (a: number, b: number, c: number, d: number) => void;
     readonly labcolors_muddiness: (a: number, b: number, c: number, d: number) => void;
     readonly labcolors_new: () => number;

package/pkg/labcolors.js

@@ -1,9 +1,10 @@
 /* @ts-self-types="./labcolors.d.ts" */
 
 /**
- * A configured contrast engine. Construct with [`LabColors::new`], then call
- * [`resolve_theme`](LabColors::resolve_theme) many times; identical calls are
- * served from the contract cache.
+ * A contrast engine over a consumer-supplied design system. Construct with
+ * [`LabColors::new`], load a config with [`loadConfig`](LabColors::load_config),
+ * then call [`resolve_theme`](LabColors::resolve_theme) many times; identical
+ * calls are served from the contract cache.
  */
 export class LabColors {
     __destroy_into_raw() {
@@ -16,39 +17,14 @@ export class LabColors {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_labcolors_free(ptr, 0);
     }
-    /**
-     * Calculate a relative confidence score for the [`muddiness`](Self::muddiness)
-     * call on an sRGB hex colour: `0` means the call is unreliable (near the
-     * decision boundary or the grey frontier), higher means more confident.
-     * The practical ceiling is an internal calibration detail, not a public
-     * contract — do not hardcode an upper bound against this value.
-     * @param {string} hex
-     * @returns {number}
-     */
-    confidence(hex) {
-        try {
-            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            const ptr0 = passStringToWasm0(hex, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-            const len0 = WASM_VECTOR_LEN;
-            wasm.labcolors_confidence(retptr, this.__wbg_ptr, ptr0, len0);
-            var r0 = getDataViewMemory0().getFloat64(retptr + 8 * 0, true);
-            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
-            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
-            if (r3) {
-                throw takeObject(r2);
-            }
-            return r0;
-        } finally {
-            wasm.__wbindgen_add_to_stack_pointer(16);
-        }
-    }
     /**
      * Загрузить конфиг дизайн-системы (JSON по типу `ThemeConfig` из `.d.ts`).
      *
      * Полный preflight движка: невалидный конфиг отклоняется структурной
      * ошибкой `invalid_config: …` и НЕ меняет состояние. После успешной
      * загрузки `resolveTheme` эмитит роли конфига (включая полупрозрачные
-     * `rgba`-роли лестницы). Возвращает отпечаток конфига — 16 hex-символов;
+     * роли лестницы — эмиссия `oklch(L% C H / α)`). Возвращает отпечаток
+     * конфига — 16 hex-символов;
      * разные конфиги дают разные отпечатки (и разные кэш-пространства).
      * @param {string} json
      * @returns {string}
@@ -102,12 +78,11 @@ export class LabColors {
         }
     }
     /**
-     * Create a zero-config engine on the default role table and the default
-     * per-theme viewing conditions.
+     * Create an engine with no design system loaded.
      *
-     * `v1` takes no config; the brand/anchor seam is left for a future
-     * version. Adding an optional config object later is additive — it does
-     * not change this signature.
+     * The engine is agnostic (ADR-0001): it carries no built-in role table, so
+     * [`resolveTheme`](LabColors::resolve_theme) rejects with `config_required`
+     * until [`loadConfig`](LabColors::load_config) supplies a design system.
      */
     constructor() {
         const ret = wasm.labcolors_new();
@@ -159,12 +134,12 @@ export class LabColors {
      * Resolve every role for `bgHex` under `theme` (`"light" | "dark" |
      * "light-ic" | "dark-ic"`).
      *
-     * Returns a [`ResolvedTheme`] object. Per-role unreachability is part of a
+     * Returns a `ResolvedTheme` object. Per-role unreachability is part of a
      * successful result (each role carries its own `kind`); only whole-call
-     * failures reject (invalid hex, unknown theme, and the
-     * by-construction-unreachable oklch serialisation failure as
-     * `internal_error`) — as a structured `"<code>: <message>"` error,
-     * never an unwound panic.
+     * failures reject (no config loaded yet as `config_required`, invalid hex,
+     * unknown theme, and the by-construction-unreachable oklch serialisation
+     * failure as `internal_error`) — as a structured `"<code>: <message>"`
+     * error, never an unwound panic.
      * @param {string} bg_hex
      * @param {string} theme
      * @returns {ResolvedTheme}

package/pkg/labcolors_bg.wasm.d.ts

@@ -2,7 +2,6 @@
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
 export const __wbg_labcolors_free: (a: number, b: number) => void;
-export const labcolors_confidence: (a: number, b: number, c: number, d: number) => void;
 export const labcolors_loadConfig: (a: number, b: number, c: number, d: number) => void;
 export const labcolors_muddiness: (a: number, b: number, c: number, d: number) => void;
 export const labcolors_new: () => number;