@labpics/colors 0.1.0

package/effective-bg.js

@@ -0,0 +1,255 @@
+// Effective background resolution — zero dependencies.
+//
+// `labcolors` resolves roles against a *solid* background. A real UI surface is
+// often translucent (a panel at `rgba(…, .8)` over its parents) or has no
+// background of its own (inheriting whatever is behind it). To resolve such a
+// surface honestly you need the **effective** background: the opaque colour a
+// viewer actually sees behind the element's own content.
+//
+// This module computes it by walking the ancestor chain and **alpha-compositing**
+// each element's `background-color` (front-to-back) until the stack is opaque,
+// over an opaque fallback (white by default). It is the bridge from the DOM's
+// layered, translucent reality to the single solid hex the WASM core consumes.
+//
+// HONEST LIMIT: this composites solid/translucent `background-color` layers only.
+// It does NOT sample `background-image`s, gradients, blurred backdrops, video, or
+// content showing through — those have no single colour to read from computed
+// style. For those, the caller supplies the effective background explicitly (the
+// `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.
+
+/** @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").
+ *
+ * @param {string} css
+ * @returns {Rgba | null}
+ */
+export function parseCssColor(css) {
+  if (typeof css !== "string") return null;
+  const s = css.trim().toLowerCase();
+  if (s === "transparent") return [0, 0, 0, 0];
+
+  if (s[0] === "#") {
+    const h = s.slice(1);
+    if (h.length === 3 || h.length === 4) {
+      const r = parseInt(h[0] + h[0], 16);
+      const g = parseInt(h[1] + h[1], 16);
+      const b = parseInt(h[2] + h[2], 16);
+      const a = h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1;
+      return [r, g, b, a].some(Number.isNaN) ? null : [r, g, b, a];
+    }
+    if (h.length === 6 || h.length === 8) {
+      const r = parseInt(h.slice(0, 2), 16);
+      const g = parseInt(h.slice(2, 4), 16);
+      const b = parseInt(h.slice(4, 6), 16);
+      const a = h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1;
+      return [r, g, b, a].some(Number.isNaN) ? null : [r, g, b, a];
+    }
+    return null;
+  }
+
+  const m = s.match(/^rgba?\(([^)]+)\)$/);
+  if (!m) return null;
+  // Split on commas or whitespace and an optional "/" alpha separator.
+  const parts = m[1].split(/[,\s/]+/).filter((p) => p.length > 0);
+  if (parts.length < 3) return null;
+  const chan = (p) => (p.endsWith("%") ? (parseFloat(p) / 100) * 255 : parseFloat(p));
+  const r = chan(parts[0]);
+  const g = chan(parts[1]);
+  const b = chan(parts[2]);
+  const a = parts.length >= 4 ? (parts[3].endsWith("%") ? parseFloat(parts[3]) / 100 : parseFloat(parts[3])) : 1;
+  if ([r, g, b, a].some((v) => Number.isNaN(v))) return null;
+  return [clamp255(r), clamp255(g), clamp255(b), Math.min(1, Math.max(0, a))];
+}
+
+function clamp255(v) {
+  return Math.min(255, Math.max(0, v));
+}
+
+/**
+ * Source-over composite of `top` onto `bottom` (Porter-Duff "over").
+ *
+ * @param {Rgba} top
+ * @param {Rgba} bottom
+ * @returns {Rgba}
+ */
+export function compositeOver(top, bottom) {
+  const at = top[3];
+  const ab = bottom[3];
+  const a = at + ab * (1 - at);
+  if (a === 0) return [0, 0, 0, 0];
+  const c = (i) => (top[i] * at + bottom[i] * ab * (1 - at)) / a;
+  return [c(0), c(1), c(2), a];
+}
+
+/**
+ * `[r, g, b]` (0..255) → `#RRGGBB`, channels rounded and clamped.
+ *
+ * @param {Rgba | [number, number, number]} rgb
+ * @returns {string}
+ */
+export function toHex(rgb) {
+  // Coerce non-finite channels (NaN/±Infinity, e.g. from a malformed `Rgba`
+  // passed by a caller) to 0, so a bad input yields a valid `#RRGGBB` rather
+  // than an invalid CSS string like `"#NAN0000"`.
+  const h = (v) => {
+    const n = Math.round(clamp255(Number.isFinite(v) ? v : 0));
+    return n.toString(16).padStart(2, "0");
+  };
+  return `#${h(rgb[0])}${h(rgb[1])}${h(rgb[2])}`.toUpperCase();
+}
+
+// --- Perceptual interpolation (Oklab) -------------------------------------
+//
+// A crossfade should feel even: equal progress should be equal *perceived*
+// change. A straight sRGB-channel blend is not that — it lingers in the brighter
+// half (black→white at t=0.5 is #808080, but the perceived midpoint grey is
+// ~#606060). Interpolating in Oklab — a perceptually-uniform space — fixes the
+// timing and, for chromatic endpoints, avoids the muddy desaturated midpoint a
+// raw RGB blend produces. Björn Ottosson's sRGB↔Oklab transform, self-contained.
+
+/** sRGB gamma transfer (IEC 61966-2-1): encoded channel 0..1 → linear 0..1. */
+function srgbToLinear(c) {
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+/** Inverse sRGB transfer: linear 0..1 → encoded 0..1. */
+function linearToSrgb(c) {
+  return c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055;
+}
+
+/** Linear-light sRGB `[r,g,b]` (0..1) → Oklab `[L, a, b]`. */
+function linearRgbToOklab(r, g, b) {
+  const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+  const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+  const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+  return [
+    0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_,
+    1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_,
+    0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_,
+  ];
+}
+
+/** Oklab `[L, a, b]` → linear-light sRGB `[r,g,b]` (0..1, may be out of gamut). */
+function oklabToLinearRgb(L, A, B) {
+  const l_ = L + 0.3963377774 * A + 0.2158037573 * B;
+  const m_ = L - 0.1055613458 * A - 0.0638541728 * B;
+  const s_ = L - 0.0894841775 * A - 1.291485548 * B;
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+
+/**
+ * Interpolate two `#RRGGBB` 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
+ * intermediates are clamped per channel. Unparseable input falls back to the
+ * nearer endpoint.
+ *
+ * @param {string} fromHex
+ * @param {string} toHex_
+ * @param {number} t
+ * @returns {string}
+ */
+export function oklabLerp(fromHex, toHex_, t) {
+  const a = parseCssColor(fromHex);
+  const b = parseCssColor(toHex_);
+  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);
+  const la = linearRgbToOklab(srgbToLinear(a[0] / 255), srgbToLinear(a[1] / 255), srgbToLinear(a[2] / 255));
+  const lb = linearRgbToOklab(srgbToLinear(b[0] / 255), srgbToLinear(b[1] / 255), srgbToLinear(b[2] / 255));
+  const lin = oklabToLinearRgb(
+    la[0] + (lb[0] - la[0]) * t,
+    la[1] + (lb[1] - la[1]) * t,
+    la[2] + (lb[2] - la[2]) * t,
+  );
+  return toHex([linearToSrgb(lin[0]) * 255, linearToSrgb(lin[1]) * 255, linearToSrgb(lin[2]) * 255]);
+}
+
+/**
+ * Compose an ordered stack of colour layers (front-to-back) over an opaque base
+ * into a single opaque `#RRGGBB`. Pure — no DOM. Exposed for testing and for
+ * callers that sample their own layers.
+ *
+ * @param {Rgba[]} layersFrontToBack  index 0 is the topmost layer
+ * @param {Rgba} opaqueBase  must have alpha 1
+ * @returns {string}
+ */
+export function compositeStackToHex(layersFrontToBack, opaqueBase) {
+  let result = opaqueBase;
+  // Apply from the back (closest to base) forward, so index 0 lands on top.
+  for (let i = layersFrontToBack.length - 1; i >= 0; i--) {
+    result = compositeOver(layersFrontToBack[i], result);
+  }
+  return toHex(result);
+}
+
+/**
+ * The opaque effective background `#RRGGBB` visible behind `element`'s own
+ * content, by walking ancestors and compositing their `background-color`s.
+ *
+ * Walks from `element` upward, collecting each `background-color` layer, and
+ * stops at the first fully-opaque layer (which becomes the base). If the chain
+ * reaches the root without an opaque layer, `fallback` (default white) is the
+ * base — matching how a browser shows the page's default canvas.
+ *
+ * Pure and injectable: pass `getStyle` and `parentOf` to test without a DOM; in
+ * the browser they default to `getComputedStyle` and `el.parentElement`.
+ *
+ * @param {*} element
+ * @param {object} [opts]
+ * @param {string} [opts.fallback="#FFFFFF"]  base when the chain is fully translucent
+ * @param {(el: *) => { getPropertyValue: (p: string) => string }} [opts.getStyle]
+ * @param {(el: *) => *} [opts.parentOf]
+ * @param {number} [opts.maxDepth=64]  guard against detached/cyclic chains
+ * @returns {string}
+ */
+export function effectiveBackground(element, opts = {}) {
+  const fallback = opts.fallback ?? "#FFFFFF";
+  const getStyle =
+    opts.getStyle ?? ((el) => (typeof getComputedStyle === "function" ? getComputedStyle(el) : { getPropertyValue: () => "" }));
+  const parentOf = opts.parentOf ?? ((el) => el.parentElement);
+  const maxDepth = opts.maxDepth ?? 64;
+
+  /** @type {Rgba[]} */
+  const layers = [];
+  let el = element;
+  let depth = 0;
+  let base = parseCssColor(fallback) ?? [255, 255, 255, 1];
+
+  while (el && depth < maxDepth) {
+    const css = getStyle(el).getPropertyValue("background-color");
+    const c = parseCssColor(css);
+    if (c && c[3] > 0) {
+      if (c[3] >= 1) {
+        base = c; // first opaque layer is the base; nothing behind it shows
+        break;
+      }
+      layers.push(c);
+    }
+    el = parentOf(el);
+    depth++;
+  }
+
+  return compositeStackToHex(layers, base);
+}

package/index.d.ts

@@ -0,0 +1,36 @@
+// Public types for @labpics/colors.
+//
+// Re-exports the wasm-bindgen-generated types (the rich `ResolvedTheme` /
+// `RoleResult` union and the `LabColors` engine) and the vanilla `applyTheme`
+// helper, so a consumer gets full typing from the package root.
+
+export {
+  default,
+  default as init,
+  initSync,
+  LabColors,
+} from "./pkg/labcolors.js";
+
+export type {
+  ThemeName,
+  SolvedColor,
+  NoneRole,
+  UnreachableRole,
+  RoleResult,
+  ResolvedTheme,
+} from "./pkg/labcolors.js";
+
+export { applyTheme } from "./apply-theme.js";
+export { watchTheme } from "./watch-theme.js";
+export type { WatchThemeOptions, WatchController } from "./watch-theme.js";
+export { adaptTheme } from "./adapt-theme.js";
+export type { AdaptThemeOptions, AdaptController } from "./adapt-theme.js";
+export {
+  effectiveBackground,
+  parseCssColor,
+  compositeOver,
+  compositeStackToHex,
+  toHex,
+  oklabLerp,
+} from "./effective-bg.js";
+export type { Rgba, EffectiveBackgroundOptions, StyleLike } from "./effective-bg.js";

package/index.js

@@ -0,0 +1,21 @@
+// Public entry for @labpics/colors.
+//
+// Re-exports the wasm-bindgen surface (the default `init` loader, `initSync`,
+// and the `LabColors` engine class) plus the vanilla DOM runtime helpers:
+// `applyTheme` (one-shot apply), `watchTheme` (reactive sync), and the
+// effective-background resolver. The wasm glue is the generated `pkg/` artifact
+// (built by `npm run build`).
+
+export { default, default as init, initSync, LabColors } from "./pkg/labcolors.js";
+
+export { applyTheme } from "./apply-theme.js";
+export { watchTheme } from "./watch-theme.js";
+export { adaptTheme } from "./adapt-theme.js";
+export {
+  effectiveBackground,
+  parseCssColor,
+  compositeOver,
+  compositeStackToHex,
+  toHex,
+  oklabLerp,
+} from "./effective-bg.js";

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@labpics/colors",
+  "version": "0.1.0",
+  "description": "Framework-agnostic contrast engine: resolve accessible, perceptually-anchored colour roles for any background. WASM core, zero runtime dependencies.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Labpics-Team/lab-colors",
+    "directory": "packages/colors"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./apply-theme": {
+      "types": "./apply-theme.d.ts",
+      "default": "./apply-theme.js"
+    },
+    "./watch-theme": {
+      "types": "./watch-theme.d.ts",
+      "default": "./watch-theme.js"
+    },
+    "./adapt-theme": {
+      "types": "./adapt-theme.d.ts",
+      "default": "./adapt-theme.js"
+    },
+    "./effective-bg": {
+      "types": "./effective-bg.d.ts",
+      "default": "./effective-bg.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "apply-theme.js",
+    "apply-theme.d.ts",
+    "watch-theme.js",
+    "watch-theme.d.ts",
+    "adapt-theme.js",
+    "adapt-theme.d.ts",
+    "effective-bg.js",
+    "effective-bg.d.ts",
+    "pkg/labcolors.js",
+    "pkg/labcolors.d.ts",
+    "pkg/labcolors_bg.wasm",
+    "pkg/labcolors_bg.wasm.d.ts"
+  ],
+  "scripts": {
+    "//build": "wasm-pack resolves --out-dir relative to the CRATE dir (crates/labcolors-wasm), not the cwd, so the ../../packages path is correct and unambiguous regardless of where npm runs it.",
+    "build": "wasm-pack build ../../crates/labcolors-wasm --release --target web --out-dir ../../packages/colors/pkg --out-name labcolors",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "types": "./index.d.ts",
+  "sideEffects": false
+}

package/pkg/labcolors.d.ts

@@ -0,0 +1,239 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/** The stable theme contract. `-ic` variants apply increased contrast; all four spellings are fully supported. */
+export type ThemeName = "light" | "dark" | "light-ic" | "dark-ic";
+
+/** A solved colour and the contrasts it actually achieves. */
+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. */
+    readonly hex: string;
+    /** Signed perceptual contrast (Lc) against the background. */
+    readonly lc: number;
+    /** WCAG 2.1 ratio (1–21) against the background. */
+    readonly wcagRatio: number;
+    /** The legal floor squeezed this role onto the smallest step below its senior. */
+    readonly compressed: boolean;
+    /** The WCAG floor overrode the perceptual target. */
+    readonly floorOverride: boolean;
+    /**
+     * The minimum WCAG ratio this role is legally clamped to (4.5 for AA text,
+     * 3.0 for AA UI), or `null` for decorative / zero roles. A property of
+     * the role's contract, not of this solve: a runtime easing between themes
+     * uses it to hold the floor every frame of the transition.
+     */
+    readonly legalFloor: number | null;
+}
+
+/** The explicit zero token: no colour here, by design (not a failure). */
+export interface NoneRole {
+    readonly kind: "none";
+    readonly cssVar: string;
+}
+
+/** No colour can satisfy this role on this background, with the reason. */
+export interface UnreachableRole {
+    readonly kind: "unreachable";
+    readonly cssVar: string;
+    /** Stable machine code, e.g. "floor_unreachable". */
+    readonly code: string;
+    /** Human-readable explanation. */
+    readonly message: string;
+}
+
+/** A semi-transparent ladder / alpha-analog emission: the CSS carries rgba(), the browser composites it. */
+export interface RgbaRole {
+    readonly kind: "rgba";
+    readonly cssVar: string;
+    /** The tint as #RRGGBB — the colour the rgba() carries. */
+    readonly tintHex: string;
+    /** The alpha of the emission, (0, 1]. */
+    readonly alpha: number;
+    /** The solid the tint composites to on the resolve background. */
+    readonly compositeHex: string;
+    /** Signed perceptual contrast (Lc) of the composite. */
+    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. */
+    readonly css: string;
+}
+
+export type RoleResult = SolvedColor | RgbaRole | NoneRole | UnreachableRole;
+
+/** Пер-темная четвёрка якорных hex (light / dark / light-ic / dark-ic). */
+export interface ThemeAnchors {
+    readonly light: string;
+    readonly dark: string;
+    readonly light_ic: string;
+    readonly dark_ic: string;
+}
+
+/** Источник тинта лестницы/альфа-аналога. */
+export type LadderSource =
+| { kind: "brand" }
+| { kind: "family"; key: string }
+| { kind: "sentiment"; name: string }
+| { kind: "neutral"; pick: "mid" | "edge" | "inverted" | "light" | "dark" };
+
+/** Рецепт роли из физического меню движка. */
+export type RoleRecipe =
+| { kind: "text-anchor"; fraction: number; floor: "aa-text" | "aa-ui" | "none" }
+| { kind: "dj-anchor"; light: number; dark: number }
+| { kind: "decorative-lc"; magnitude: number }
+| { kind: "ladder"; source: LadderSource; position: string }
+| { kind: "alpha-analog"; of: LadderSource; alpha: number }
+| { kind: "zero" };
+
+/** Полный конфиг дизайн-системы клиента — вход loadConfig (JSON.stringify(config)). */
+export interface ThemeConfig {
+    readonly brand: ThemeAnchors;
+    readonly neutral: {
+        readonly anchors: { light: string; mid: string; dark: string };
+        readonly tint: {
+            ratio: number;
+            target_mp: number;
+            hue_stiffness: number;
+            hue_override_deg?: number;
+        };
+        readonly edge?: ThemeAnchors;
+        readonly inverted?: ThemeAnchors;
+    };
+    readonly palette: ReadonlyArray<{ key: string; anchors: ThemeAnchors }>;
+    readonly sentiments: {
+        readonly categories: ReadonlyArray<{
+            name: string;
+            family: string;
+            hue_floor_deg?: number;
+            preferred_side?: -1 | 1;
+        }>;
+        readonly hardness: number;
+        readonly chroma_fraction: number;
+    };
+    readonly themes: ReadonlyArray<{ name: string; preset: "srgb" | "dim" | "srgb-ic" | "dim-ic" }>;
+    readonly roles: ReadonlyArray<{ name: string; recipe: RoleRecipe }>;
+    readonly aliases?: ReadonlyArray<{ alias: string; target: string }>;
+}
+
+/** The full result of resolving one background under one theme. */
+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.
+     */
+    readonly vars: Record<string, string>;
+    /** Every role, keyed by its stable role key (without the --lab- prefix). */
+    readonly roles: Record<string, RoleResult>;
+}
+
+
+
+/**
+ * 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.
+ */
+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-символов;
+     * разные конфиги дают разные отпечатки (и разные кэш-пространства).
+     */
+    loadConfig(json: string): string;
+    /**
+     * Calculate the muddiness score (0 to 1) of an sRGB hex colour.
+     */
+    muddiness(hex: string): number;
+    /**
+     * Create a zero-config engine on the default role table and the default
+     * per-theme viewing conditions.
+     *
+     * `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.
+     */
+    constructor();
+    /**
+     * Recheck the contrasts `fgHexes` achieve against `bgHex` under `theme` —
+     * the cheap per-frame primitive a reactive runtime uses to decide whether
+     * already-resolved colours still pass against a changed background (re-solve
+     * only when they stably do not). No full solve: one perceptual-model forward
+     * for the background plus one per foreground.
+     *
+     * Returns a `Float64Array` of `[lc, wcagRatio]` pairs, interleaved and in the
+     * order of `fgHexes`: index `2*i` is foreground `i`'s signed `Lc`, `2*i+1`
+     * its WCAG ratio. Rejects (structured `{code, message}`) on an invalid hex or
+     * an unknown theme.
+     */
+    recheckContrast(bg_hex: string, fg_hexes: string[], theme: string): Float64Array;
+    /**
+     * Resolve every role for `bgHex` under `theme` (`"light" | "dark" |
+     * "light-ic" | "dark-ic"`).
+     *
+     * 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.
+     */
+    resolveTheme(bg_hex: string, theme: string): ResolvedTheme;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+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;
+    readonly labcolors_recheckContrast: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly labcolors_resolveTheme: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;