@labpics/colors 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@labpics/colors",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Framework-agnostic contrast engine: resolve accessible, perceptually-anchored colour roles for any background. WASM core, zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,9 @@
     "./effective-bg": {
       "types": "./effective-bg.d.ts",
       "default": "./effective-bg.js"
-    }
+    },
+    "./pkg/labcolors_bg.wasm": "./pkg/labcolors_bg.wasm",
+    "./package.json": "./package.json"
   },
   "files": [
     "index.js",

package/pkg/labcolors.d.ts

@@ -9,8 +9,10 @@ export interface SolvedColor {
     readonly kind: "color";
     /** The CSS custom-property name for this role, e.g. "--lab-label-primary". */
     readonly cssVar: string;
-    /** The resolved colour as #RRGGBB. */
+    /** The resolved colour as #RRGGBB (data; `css`/`vars` carry oklch). */
     readonly hex: string;
+    /** Ready-to-serve CSS value: "oklch(L% C H)". `vars` carries the same string. */
+    readonly css: string;
     /** Signed perceptual contrast (Lc) against the background. */
     readonly lc: number;
     /** WCAG 2.1 ratio (1–21) against the background. */
@@ -44,11 +46,11 @@ export interface UnreachableRole {
     readonly message: string;
 }
 
-/** A semi-transparent ladder / alpha-analog emission: the CSS carries rgba(), the browser composites it. */
-export interface RgbaRole {
-    readonly kind: "rgba";
+/** A semi-transparent ladder / alpha-analog emission: the CSS carries oklch(L% C H / A), the browser composites it. */
+export interface TranslucentRole {
+    readonly kind: "translucent";
     readonly cssVar: string;
-    /** The tint as #RRGGBB — the colour the rgba() carries. */
+    /** The tint as #RRGGBB (data) — the colour the oklch(… / A) carries. */
     readonly tintHex: string;
     /** The alpha of the emission, (0, 1]. */
     readonly alpha: number;
@@ -58,11 +60,11 @@ export interface RgbaRole {
     readonly compositeLc: number;
     /** WCAG 2.1 ratio of the composite. */
     readonly compositeWcag: number;
-    /** Ready-to-serve CSS value: "rgb(R G B / A)". `vars` carries the same string. */
+    /** Ready-to-serve CSS value: "oklch(L% C H / A)". `vars` carries the same string. */
     readonly css: string;
 }
 
-export type RoleResult = SolvedColor | RgbaRole | NoneRole | UnreachableRole;
+export type RoleResult = SolvedColor | TranslucentRole | NoneRole | UnreachableRole;
 
 /** Пер-темная четвёрка якорных hex (light / dark / light-ic / dark-ic). */
 export interface ThemeAnchors {
@@ -123,9 +125,15 @@ export interface ResolvedTheme {
     readonly theme: ThemeName;
     readonly background: string;
     /**
-     * Reachable roles only. Values are ready-to-serve CSS: "#RRGGBB" for solid
-     * roles, "rgb(R G B / A)" for semi-transparent ladder/alpha-analog roles —
-     * do not validate them as hex.
+     * Reachable roles only. Values are ready-to-serve CSS in ONE form:
+     * "oklch(L% C H)" for solid roles, "oklch(L% C H / A)" for semi-transparent
+     * ladder/alpha-analog roles. Solved in the sRGB gamut (oklch is the
+     * notation, not a gamut extension); byte-exact vs `SolvedColor.hex` and
+     * `TranslucentRole.tintHex` (`compositeHex` is the background-specific
+     * composite, not the emitted token).
+     * Scope: this is resolveTheme's contract (applyTheme/watchTheme inject it
+     * verbatim); adaptTheme's per-frame easing writes concrete interpolated
+     * colours and is not bound by the emission form.
      */
     readonly vars: Record<string, string>;
     /** Every role, keyed by its stable role key (without the --lab- prefix). */
@@ -192,8 +200,10 @@ export class LabColors {
      *
      * Returns a [`ResolvedTheme`] object. Per-role unreachability is part of a
      * successful result (each role carries its own `kind`); only whole-call
-     * failures (invalid hex, unknown theme) reject — as a
-     * structured `{ code, message }` error, never an unwound panic.
+     * 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.
      */
     resolveTheme(bg_hex: string, theme: string): ResolvedTheme;
 }

package/pkg/labcolors.js

@@ -161,8 +161,10 @@ export class LabColors {
      *
      * Returns a [`ResolvedTheme`] object. Per-role unreachability is part of a
      * successful result (each role carries its own `kind`); only whole-call
-     * failures (invalid hex, unknown theme) reject — as a
-     * structured `{ code, message }` error, never an unwound panic.
+     * 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.
      * @param {string} bg_hex
      * @param {string} theme
      * @returns {ResolvedTheme}