@stridge/noctis-theme-engine 1.0.0-beta.0

package/README.md

@@ -0,0 +1,39 @@
+# @stridge/noctis-theme-engine
+
+The framework-agnostic OKLCH theme generator at the base of the design system. From a
+`{ background, accent, contrast }` input it produces the complete private primitive ramp
+(`--noctis-engine-*`) — plus the elevation-scope re-derivations — as CSS variables, with
+APCA-guaranteed text contrast. `@stridge/noctis-design-tokens` maps this output to intent-named semantic
+roles; only the semantic layer consumes the engine primitives, never components directly.
+
+## Usage
+
+Consumers reach it through the umbrella package as `@stridge/noctis/theme` (+ `/theme/react`); it
+is also publishable standalone as `@stridge/noctis-theme-engine`.
+
+```ts
+import { generateTheme, applyTheme } from "@stridge/noctis-theme-engine";
+
+const theme = generateTheme({ background: "#0b0b0c", accent: "#3b82f6", contrast: 1 });
+applyTheme(document.documentElement, theme);
+```
+
+The core exports include `generateTheme` / `generateScopeTheme`, the `applyTheme` /
+`applyScopeTheme` / `applyEngineVars` appliers, the OKLCH color toolkit (`parseColor`, `mix`,
+`adjust`, `toCss`, …), the APCA/WCAG contrast solvers (`apcaContrast`, `solveTextColor`, …),
+the `presets` / `defaultPreset` catalog, and the `ThemeInput` / `ThemeMap` / `ElevationLevel`
+types.
+
+```tsx
+// React bindings — @stridge/noctis-theme-engine/react
+import { ThemeProvider, useTheme } from "@stridge/noctis-theme-engine/react";
+
+<ThemeProvider>{children}</ThemeProvider>;
+```
+
+## Build & checks
+
+`build` runs `tsdown`; `check:publish` runs `publint`. React is an optional peer dependency.
+
+See [/AGENTS.md](../../AGENTS.md) for repo-wide rules and `@stridge/noctis-design-tokens` for how engine
+primitives become semantic roles.

package/dist/apply/apply.d.ts

@@ -0,0 +1,50 @@
+import { ElevationLevel, ThemeInput, ThemeMap, ThemeOverrides } from "../generate/tokens.js";
+import { GenerateThemeOptions } from "../generate/theme.js";
+
+//#region src/apply/apply.d.ts
+/** FNV-1a string hash → short hex. Stable across runs; used only as a memo/seed key. */
+declare function hashString(value: string): string;
+/**
+ * Stable hash of a theme input plus its overrides — the memo/seed key for a generated theme.
+ * Overrides serialize as the JSON of their sorted `[key, value]` entries, so key order never
+ * changes the hash and no value can forge another map's serialization (delimiter characters in a
+ * value cannot collide two distinct override maps). Without overrides the hashed string is the
+ * bare `background|accent|contrast|mode` form.
+ */
+declare function hashInput(input: ThemeInput, overrides?: ThemeOverrides): string;
+/**
+ * Merge `vars` into `target`'s declaration set in the per-document engine sheet (default target
+ * `:root`). Names must carry the engine namespace. Re-applying an already-present set is a no-op
+ * unless the emission surface was cleared externally; any value change rewrites the whole sheet.
+ */
+declare function applyEngineVars(vars: Readonly<Record<string, string>>, target?: Element): void;
+/**
+ * Emit `map` for `target` (default `:root`) through the engine sheet, inside
+ * `@layer noctis.engine`. Memoized per target: re-applying the same map is a no-op — unless the
+ * sheet was cleared or detached since, in which case it is re-emitted. Pass any element to scope
+ * a subtree (e.g. a sidebar with its own seed); its rule is keyed by a stable generated
+ * `data-noctis-theme-scope` attribute.
+ *
+ * Because the emission is layered, a plain unlayered rule (`:root { --noctis-engine-bg-3: … }`)
+ * beats the engine by cascade. A cascade override replaces that one variable only — dependents do
+ * not re-derive. Pass `overrides` to {@link generateTheme} when dependents should follow.
+ */
+declare function applyTheme(map: ThemeMap, target?: Element): void;
+/**
+ * Generate and emit an elevation scope's full token set for `target`. Use on a subtree element
+ * (a sidebar, a portalled popover) so every variable inside it resolves to that elevation —
+ * `elevated` for raised surfaces, `sunken` for recessed ones. Subtree rules live in the engine
+ * sheet until released: call {@link clearEngineVars} when the target unmounts, or churning
+ * portalled elements accrete dead selectors in the sheet.
+ */
+declare function applyScopeTheme(target: Element, input: ThemeInput, level: ElevationLevel, options?: GenerateThemeOptions): void;
+/**
+ * Release `target`'s rule from the per-document engine sheet — the disposer for
+ * {@link applyScopeTheme} / {@link applyEngineVars} on a subtree target. Deletes the selector's
+ * declarations, strips the `data-noctis-theme-scope` attribute, and re-commits the sheet, so
+ * mount/unmount churn (portalled overlays) never accretes dead selectors. A no-op for targets
+ * that were never applied.
+ */
+declare function clearEngineVars(target?: Element): void;
+//#endregion
+export { applyEngineVars, applyScopeTheme, applyTheme, clearEngineVars, hashInput, hashString };

package/dist/apply/apply.js

@@ -0,0 +1,189 @@
+import { ENGINE_LAYER } from "../generate/tokens.js";
+import { generateScopeTheme } from "../generate/theme.js";
+//#region src/apply/apply.ts
+/**
+* Runtime application — emit the generated variables through one engine stylesheet per document.
+*
+* No inline styles and no per-variable `setProperty`: every target's declarations land in a
+* single constructed stylesheet (`document.adoptedStyleSheets`), with a
+* `<style data-noctis-engine>` head fallback where constructed sheets are unavailable (jsdom).
+* All rules live in `@layer noctis.engine`, so any unlayered author rule on an engine variable
+* outranks the engine by cascade. Application is memoized per target so identical declaration
+* sets are a no-op.
+*/
+const engineSheets = /* @__PURE__ */ new WeakMap();
+let scopeCounter = 0;
+/**
+* The CSS selector a target's declarations are scoped to: `:root` for the document element,
+* otherwise a stable generated `data-noctis-theme-scope` attribute stamped on the element.
+*/
+function selectorFor(target, doc) {
+	if (target === doc.documentElement) return ":root";
+	let id = target.getAttribute("data-noctis-theme-scope");
+	if (id === null) {
+		id = String(++scopeCounter);
+		target.setAttribute("data-noctis-theme-scope", id);
+	}
+	return `[data-noctis-theme-scope="${id}"]`;
+}
+/** Serialize every selector's declarations into the engine's single `@layer` block. */
+function renderCss(rules) {
+	let body = "";
+	for (const [selector, declarations] of rules) {
+		body += `${selector}{`;
+		for (const [name, value] of declarations) body += `${name}:${value};`;
+		body += "}";
+	}
+	return `@layer ${ENGINE_LAYER}{${body}}`;
+}
+/**
+* The document's window when it supports constructed stylesheets; `null` selects the `<style>`
+* fallback. The feature test reads `Document.prototype` (not the instance), so an expando
+* assignment to `document.adoptedStyleSheets` in a non-supporting runtime (jsdom) cannot fake
+* support.
+*/
+function constructedSheetView(doc) {
+	const view = doc.defaultView;
+	if (view && typeof view.CSSStyleSheet === "function" && "adoptedStyleSheets" in view.Document.prototype) return view;
+	return null;
+}
+/**
+* Whether the engine's emission surface is still live in the document. Guards the memo against
+* external clears — an adopted sheet dropped from `adoptedStyleSheets`, or the fallback `<style>`
+* removed from the head.
+*/
+function stillApplied(doc, state) {
+	if (state.sheet) return doc.adoptedStyleSheets.includes(state.sheet);
+	if (state.styleElement) return state.styleElement.isConnected;
+	return false;
+}
+/** Render the layer block and push it through the live emission surface, (re)attaching it if needed. */
+function commit(doc, state) {
+	const css = renderCss(state.rules);
+	const view = constructedSheetView(doc);
+	if (view) {
+		state.sheet ??= new view.CSSStyleSheet();
+		if (!doc.adoptedStyleSheets.includes(state.sheet)) doc.adoptedStyleSheets = [...doc.adoptedStyleSheets, state.sheet];
+		state.sheet.replaceSync(css);
+		return;
+	}
+	if (!state.styleElement || !state.styleElement.isConnected) {
+		const element = state.styleElement ?? doc.createElement("style");
+		element.setAttribute("data-noctis-engine", "");
+		(doc.head ?? doc.documentElement)?.appendChild(element);
+		state.styleElement = element;
+	}
+	state.styleElement.textContent = css;
+}
+/** FNV-1a string hash → short hex. Stable across runs; used only as a memo/seed key. */
+function hashString(value) {
+	let hash = 2166136261;
+	for (let i = 0; i < value.length; i++) {
+		hash ^= value.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16);
+}
+/**
+* Stable hash of a theme input plus its overrides — the memo/seed key for a generated theme.
+* Overrides serialize as the JSON of their sorted `[key, value]` entries, so key order never
+* changes the hash and no value can forge another map's serialization (delimiter characters in a
+* value cannot collide two distinct override maps). Without overrides the hashed string is the
+* bare `background|accent|contrast|mode` form.
+*/
+function hashInput(input, overrides) {
+	let serialized = `${input.background}|${input.accent}|${input.contrast}|${input.mode ?? "auto"}`;
+	if (overrides) {
+		const entries = Object.keys(overrides).filter((key) => overrides[key] !== void 0).sort().map((key) => [key, overrides[key]]);
+		if (entries.length > 0) serialized += `|${JSON.stringify(entries)}`;
+	}
+	return hashString(serialized);
+}
+function resolveTarget(target) {
+	if (target) return target;
+	if (typeof document !== "undefined") return document.documentElement;
+}
+/**
+* Merge `vars` into `target`'s declaration set in the per-document engine sheet (default target
+* `:root`). Names must carry the engine namespace. Re-applying an already-present set is a no-op
+* unless the emission surface was cleared externally; any value change rewrites the whole sheet.
+*/
+function applyEngineVars(vars, target) {
+	const element = resolveTarget(target);
+	if (!element) return;
+	const doc = element.ownerDocument;
+	let state = engineSheets.get(doc);
+	if (!state) {
+		state = {
+			rules: /* @__PURE__ */ new Map(),
+			sheet: null,
+			styleElement: null
+		};
+		engineSheets.set(doc, state);
+	}
+	const selector = selectorFor(element, doc);
+	let declarations = state.rules.get(selector);
+	if (!declarations) {
+		declarations = /* @__PURE__ */ new Map();
+		state.rules.set(selector, declarations);
+	}
+	let changed = false;
+	for (const [name, value] of Object.entries(vars)) if (declarations.get(name) !== value) {
+		declarations.set(name, value);
+		changed = true;
+	}
+	if (!changed && stillApplied(doc, state)) return;
+	commit(doc, state);
+}
+/**
+* Emit `map` for `target` (default `:root`) through the engine sheet, inside
+* `@layer noctis.engine`. Memoized per target: re-applying the same map is a no-op — unless the
+* sheet was cleared or detached since, in which case it is re-emitted. Pass any element to scope
+* a subtree (e.g. a sidebar with its own seed); its rule is keyed by a stable generated
+* `data-noctis-theme-scope` attribute.
+*
+* Because the emission is layered, a plain unlayered rule (`:root { --noctis-engine-bg-3: … }`)
+* beats the engine by cascade. A cascade override replaces that one variable only — dependents do
+* not re-derive. Pass `overrides` to {@link generateTheme} when dependents should follow.
+*/
+function applyTheme(map, target) {
+	applyEngineVars(map, target);
+}
+/**
+* Generate and emit an elevation scope's full token set for `target`. Use on a subtree element
+* (a sidebar, a portalled popover) so every variable inside it resolves to that elevation —
+* `elevated` for raised surfaces, `sunken` for recessed ones. Subtree rules live in the engine
+* sheet until released: call {@link clearEngineVars} when the target unmounts, or churning
+* portalled elements accrete dead selectors in the sheet.
+*/
+function applyScopeTheme(target, input, level, options) {
+	applyTheme(generateScopeTheme(input, level, options), target);
+}
+/**
+* The selector `target`'s declarations are currently scoped to, or `null` when the target was
+* never applied — unlike {@link selectorFor}, never stamps a new scope id.
+*/
+function existingSelectorFor(target, doc) {
+	if (target === doc.documentElement) return ":root";
+	const id = target.getAttribute("data-noctis-theme-scope");
+	return id === null ? null : `[data-noctis-theme-scope="${id}"]`;
+}
+/**
+* Release `target`'s rule from the per-document engine sheet — the disposer for
+* {@link applyScopeTheme} / {@link applyEngineVars} on a subtree target. Deletes the selector's
+* declarations, strips the `data-noctis-theme-scope` attribute, and re-commits the sheet, so
+* mount/unmount churn (portalled overlays) never accretes dead selectors. A no-op for targets
+* that were never applied.
+*/
+function clearEngineVars(target) {
+	const element = resolveTarget(target);
+	if (!element) return;
+	const doc = element.ownerDocument;
+	const state = engineSheets.get(doc);
+	const selector = state && existingSelectorFor(element, doc);
+	if (element !== doc.documentElement) element.removeAttribute("data-noctis-theme-scope");
+	if (!state || !selector || !state.rules.delete(selector)) return;
+	commit(doc, state);
+}
+//#endregion
+export { applyEngineVars, applyScopeTheme, applyTheme, clearEngineVars, hashInput, hashString };

package/dist/color/contrast.d.ts

@@ -0,0 +1,32 @@
+import { Oklch } from "./oklch.js";
+
+//#region src/color/contrast.d.ts
+/** sRGB-relative luminance Y of an OKLCH color (gamut-clamped to sRGB channels). */
+declare function luminance(o: Oklch): number;
+/** APCA lightness contrast `Lc` (0…~108) of `text` against `bg`. Polarity-aware. */
+declare function apcaContrast(text: Oklch, bg: Oklch): number;
+/** WCAG 2.1 contrast ratio (1…21) — the dev-only cross-check metric. */
+declare function wcagContrast(a: Oklch, b: Oklch): number;
+/** Whether `text` clears the APCA `Lc` target on `bg` (default 38 — the readable floor). */
+declare function sufficientContrastForText(text: Oklch, bg: Oklch, target?: number): boolean;
+/** True when dark text contrasts better than light text on `bg` (the modeless brightness switch). */
+declare function isBright(bg: Oklch): boolean;
+/**
+ * Auto-invert text seed: pure white or black (whichever contrasts more), carrying the
+ * background hue at half chroma so primary text is a faint tint of its surface, not flat gray.
+ */
+declare function getTextColor(bg: Oklch): Oklch;
+/**
+ * Solve a neutral-but-tinted text color at a target APCA `Lc` on `bg` by binary-searching
+ * lightness on the legible side. Falls back to the maximum-contrast extreme if the target
+ * is unreachable. Used for the secondary/muted/faint text tiers.
+ */
+declare function solveTextColor(bg: Oklch, targetLc: number): Oklch;
+/**
+ * Guarantee a hue-bearing color (status/category) is legible on `bg`: if the seed already
+ * clears the target it is kept verbatim; otherwise its lightness is binary-searched,
+ * desaturating in four steps if no lightness works at full chroma.
+ */
+declare function solveOnBackground(seed: Oklch, bg: Oklch, target: number): Oklch;
+//#endregion
+export { apcaContrast, getTextColor, isBright, luminance, solveOnBackground, solveTextColor, sufficientContrastForText, wcagContrast };

package/dist/color/contrast.js

@@ -0,0 +1,165 @@
+import { clamp, normalizeHue } from "./oklch.js";
+import { converter } from "culori";
+//#region src/color/contrast.ts
+/**
+* Perceptual contrast: a genuine APCA `Lc` estimate (luminance-based, using the
+* APCA-W3 soft-clamp and polarity constants) plus a WCAG 2.1 cross-check, and the
+* legibility solvers that guarantee every text/status tier clears its target.
+*/
+const toRgb = converter("rgb");
+const BLACK = {
+	l: 0,
+	c: 0,
+	h: 0
+};
+const WHITE = {
+	l: 1,
+	c: 0,
+	h: 0
+};
+/** APCA soft black-clamp constants. */
+const BLACK_THRESHOLD = .022;
+const BLACK_EXPONENT = 1.414;
+/** APCA polarity exponents (BoW = dark text on light; WoB = light text on dark). */
+const BOW_BG = .56;
+const BOW_TEXT = .57;
+const WOB_TEXT = .62;
+const WOB_BG = .65;
+const SCALE = 1.14;
+const OUTPUT_CLAMP = .027;
+const MIN_DELTA = .1;
+function channelToLinear(value) {
+	const v = clamp(value, 0, 1);
+	return v <= .04045 ? v / 12.92 : ((v + .055) / 1.055) ** 2.4;
+}
+/** sRGB-relative luminance Y of an OKLCH color (gamut-clamped to sRGB channels). */
+function luminance(o) {
+	const { r, g, b } = toRgb({
+		mode: "oklch",
+		l: o.l,
+		c: o.c,
+		h: o.h
+	});
+	return .2126 * channelToLinear(r) + .7152 * channelToLinear(g) + .0722 * channelToLinear(b);
+}
+function softClamp(y) {
+	return y >= BLACK_THRESHOLD ? y : y + (BLACK_THRESHOLD - y) ** BLACK_EXPONENT;
+}
+/** APCA lightness contrast `Lc` (0…~108) of `text` against `bg`. Polarity-aware. */
+function apcaContrast(text, bg) {
+	const yText = softClamp(luminance(text));
+	const yBg = softClamp(luminance(bg));
+	if (Math.abs(yBg - yText) < 5e-4) return 0;
+	const sapc = yBg > yText ? (yBg ** BOW_BG - yText ** BOW_TEXT) * SCALE : (yBg ** WOB_BG - yText ** WOB_TEXT) * SCALE;
+	const output = Math.abs(sapc) < MIN_DELTA ? 0 : sapc > 0 ? sapc - OUTPUT_CLAMP : sapc + OUTPUT_CLAMP;
+	return Math.abs(output * 100);
+}
+/** WCAG 2.1 contrast ratio (1…21) — the dev-only cross-check metric. */
+function wcagContrast(a, b) {
+	const la = luminance(a);
+	const lb = luminance(b);
+	const lighter = Math.max(la, lb);
+	const darker = Math.min(la, lb);
+	return (lighter + .05) / (darker + .05);
+}
+/** Whether `text` clears the APCA `Lc` target on `bg` (default 38 — the readable floor). */
+function sufficientContrastForText(text, bg, target = 38) {
+	return apcaContrast(text, bg) > target;
+}
+/** True when dark text contrasts better than light text on `bg` (the modeless brightness switch). */
+function isBright(bg) {
+	return apcaContrast(BLACK, bg) > apcaContrast(WHITE, bg);
+}
+/**
+* Auto-invert text seed: pure white or black (whichever contrasts more), carrying the
+* background hue at half chroma so primary text is a faint tint of its surface, not flat gray.
+*/
+function getTextColor(bg) {
+	return {
+		l: apcaContrast(WHITE, bg) >= apcaContrast(BLACK, bg) ? 1 : 0,
+		c: Math.min(bg.c / 2, .02),
+		h: bg.h
+	};
+}
+const MAX_TINT = .02;
+/**
+* Solve a neutral-but-tinted text color at a target APCA `Lc` on `bg` by binary-searching
+* lightness on the legible side. Falls back to the maximum-contrast extreme if the target
+* is unreachable. Used for the secondary/muted/faint text tiers.
+*/
+function solveTextColor(bg, targetLc) {
+	const bright = isBright(bg);
+	const chroma = Math.min(bg.c / 2, MAX_TINT);
+	const hue = bg.h;
+	let lo = 0;
+	let hi = 1;
+	for (let i = 0; i < 32; i++) {
+		const mid = (lo + hi) / 2;
+		const lc = apcaContrast({
+			l: mid,
+			c: chroma,
+			h: hue
+		}, bg);
+		if (bright) if (lc < targetLc) hi = mid;
+		else lo = mid;
+		else if (lc < targetLc) lo = mid;
+		else hi = mid;
+	}
+	return {
+		l: (lo + hi) / 2,
+		c: chroma,
+		h: hue
+	};
+}
+function searchContrastL(c, h, bg, target) {
+	const bright = isBright(bg);
+	let lo = 0;
+	let hi = 1;
+	let found = false;
+	let result = bright ? 0 : 1;
+	for (let i = 0; i < 28; i++) {
+		const mid = (lo + hi) / 2;
+		const passes = apcaContrast({
+			l: mid,
+			c,
+			h
+		}, bg) >= target;
+		if (bright) if (passes) {
+			found = true;
+			result = mid;
+			lo = mid;
+		} else hi = mid;
+		else if (passes) {
+			found = true;
+			result = mid;
+			hi = mid;
+		} else lo = mid;
+	}
+	return found ? result : null;
+}
+/**
+* Guarantee a hue-bearing color (status/category) is legible on `bg`: if the seed already
+* clears the target it is kept verbatim; otherwise its lightness is binary-searched,
+* desaturating in four steps if no lightness works at full chroma.
+*/
+function solveOnBackground(seed, bg, target) {
+	if (apcaContrast(seed, bg) >= target) return seed;
+	for (const factor of [
+		1,
+		.75,
+		.5,
+		.25,
+		0
+	]) {
+		const chroma = seed.c * factor;
+		const l = searchContrastL(chroma, seed.h, bg, target);
+		if (l !== null) return {
+			l,
+			c: chroma,
+			h: normalizeHue(seed.h)
+		};
+	}
+	return seed;
+}
+//#endregion
+export { apcaContrast, getTextColor, isBright, luminance, solveOnBackground, solveTextColor, sufficientContrastForText, wcagContrast };

package/dist/color/oklch.d.ts

@@ -0,0 +1,38 @@
+//#region src/color/oklch.d.ts
+/** A color in OKLCH: `l` ∈ [0,1], `c` ≥ 0, `h` ∈ [0,360), optional `a` ∈ [0,1]. */
+interface Oklch {
+  l: number;
+  c: number;
+  h: number;
+  a?: number;
+}
+/** A partial per-axis offset or target applied by {@link adjust} / {@link adjustTo}. */
+interface OklchDelta {
+  l?: number;
+  c?: number;
+  h?: number;
+  a?: number;
+}
+declare function clamp(value: number, lo: number, hi: number): number;
+/** Wrap a hue into [0,360). */
+declare function normalizeHue(h: number): number;
+/** Clamp an OKLCH color to its valid axis ranges (no upper chroma clamp). */
+declare function clampOklch(o: Oklch): Oklch;
+/** Parse any CSS color string into OKLCH. Throws on an unparseable input. */
+declare function parseColor(css: string): Oklch;
+/** Add per-axis deltas to a color, then clamp. */
+declare function adjust(o: Oklch, delta: OklchDelta): Oklch;
+/** Set the provided axes (leaving the rest), then clamp. */
+declare function adjustTo(o: Oklch, set: OklchDelta): Oklch;
+/** Perceptual blend through OKLab (`t` clamped to [0,1]; 0 → `x`, 1 → `y`). Alpha lerps linearly. */
+declare function mix(x: Oklch, y: Oklch, t: number): Oklch;
+/** Reduce chroma until the color sits inside the sRGB gamut, preserving L, H and alpha. */
+declare function toSrgbGamut(o: Oklch): Oklch;
+/**
+ * Serialize to a gamut-mapped `oklch(...)` string. The input is clamped to its valid axis
+ * ranges first, so an out-of-range `Oklch` can never serialize into an invalid token. Alpha
+ * is emitted only when below 1.
+ */
+declare function toCss(o: Oklch): string;
+//#endregion
+export { Oklch, OklchDelta, adjust, adjustTo, clamp, clampOklch, mix, normalizeHue, parseColor, toCss, toSrgbGamut };

package/dist/color/oklch.js

@@ -0,0 +1,108 @@
+import { clampChroma, converter, parse } from "culori";
+//#region src/color/oklch.ts
+/**
+* OKLCH color primitives — the working and output space for the engine.
+*
+* Every emitted color is gamut-mapped into sRGB by reducing chroma (P3 is opt-in
+* elsewhere). Chroma has no upper clamp here: it is bounded only by the gamut map,
+* never hard-clipped to a fixed ceiling.
+*/
+const toOklch = converter("oklch");
+const toOklab = converter("oklab");
+function clamp(value, lo, hi) {
+	return Math.max(lo, Math.min(hi, value));
+}
+/** Wrap a hue into [0,360). */
+function normalizeHue(h) {
+	if (!Number.isFinite(h)) return 0;
+	return (h % 360 + 360) % 360;
+}
+/** Clamp an OKLCH color to its valid axis ranges (no upper chroma clamp). */
+function clampOklch(o) {
+	return {
+		l: clamp(o.l, 0, 1),
+		c: Math.max(0, o.c),
+		h: normalizeHue(o.h),
+		a: clamp(o.a ?? 1, 0, 1)
+	};
+}
+function fromCulori(color, fallbackHue = 0) {
+	return {
+		l: color.l ?? 0,
+		c: color.c ?? 0,
+		h: Number.isFinite(color.h) ? color.h : fallbackHue,
+		a: color.alpha ?? 1
+	};
+}
+function toCulori(o) {
+	return {
+		mode: "oklch",
+		l: o.l,
+		c: o.c,
+		h: o.h,
+		alpha: o.a ?? 1
+	};
+}
+/** Parse any CSS color string into OKLCH. Throws on an unparseable input. */
+function parseColor(css) {
+	const parsed = parse(css);
+	if (!parsed) throw new Error(`theme-engine: cannot parse color "${css}"`);
+	return clampOklch(fromCulori(toOklch(parsed)));
+}
+/** Add per-axis deltas to a color, then clamp. */
+function adjust(o, delta) {
+	return clampOklch({
+		l: o.l + (delta.l ?? 0),
+		c: o.c + (delta.c ?? 0),
+		h: o.h + (delta.h ?? 0),
+		a: (o.a ?? 1) + (delta.a ?? 0)
+	});
+}
+/** Set the provided axes (leaving the rest), then clamp. */
+function adjustTo(o, set) {
+	return clampOklch({
+		l: set.l ?? o.l,
+		c: set.c ?? o.c,
+		h: set.h ?? o.h,
+		a: set.a ?? o.a ?? 1
+	});
+}
+/** Perceptual blend through OKLab (`t` clamped to [0,1]; 0 → `x`, 1 → `y`). Alpha lerps linearly. */
+function mix(x, y, t) {
+	const amount = clamp(t, 0, 1);
+	const a = toOklab(toCulori(x));
+	const b = toOklab(toCulori(y));
+	const lerp = (m, n) => (m ?? 0) * (1 - amount) + (n ?? 0) * amount;
+	return clampOklch(fromCulori(toOklch({
+		mode: "oklab",
+		l: lerp(a.l, b.l),
+		a: lerp(a.a, b.a),
+		b: lerp(a.b, b.b),
+		alpha: lerp(x.a ?? 1, y.a ?? 1)
+	}), x.h));
+}
+/** Reduce chroma until the color sits inside the sRGB gamut, preserving L, H and alpha. */
+function toSrgbGamut(o) {
+	const mapped = clampChroma(toCulori(o), "oklch", "rgb");
+	return mapped ? fromCulori(mapped, o.h) : o;
+}
+function round(value, places) {
+	const f = 10 ** places;
+	return Math.round(value * f) / f;
+}
+/**
+* Serialize to a gamut-mapped `oklch(...)` string. The input is clamped to its valid axis
+* ranges first, so an out-of-range `Oklch` can never serialize into an invalid token. Alpha
+* is emitted only when below 1.
+*/
+function toCss(o) {
+	const g = toSrgbGamut(clampOklch(o));
+	const l = round(g.l, 4);
+	const c = round(g.c, 4);
+	const h = c === 0 ? 0 : round(g.h, 2);
+	const a = g.a ?? 1;
+	const base = `oklch(${l} ${c} ${h}`;
+	return a < 1 ? `${base} / ${round(a, 3)})` : `${base})`;
+}
+//#endregion
+export { adjust, adjustTo, clamp, clampOklch, mix, normalizeHue, parseColor, toCss, toSrgbGamut };

package/dist/generate/theme.d.ts

@@ -0,0 +1,31 @@
+import { ElevationLevel, ThemeInput, ThemeMap, ThemeOverrides } from "./tokens.js";
+
+//#region src/generate/theme.d.ts
+/** Options accepted by the generators and everything that threads into them. */
+interface GenerateThemeOptions {
+  /** Generation-time primitive overrides — see {@link ThemeOverrides}. */
+  overrides?: ThemeOverrides;
+}
+/**
+ * Turn `{ background, accent, contrast, mode? }` into the flat L1 primitive token map.
+ * Pure and deterministic — no DOM, no globals.
+ *
+ * `options.overrides` entries replace their primitive's computed value (the override string is
+ * emitted verbatim) and feed every dependent derivation; scope-qualified entries are validated
+ * here but consumed only by the matching scope's run in {@link generateScopeTheme}.
+ */
+declare function generateTheme(input: ThemeInput, options?: GenerateThemeOptions): ThemeMap;
+/**
+ * Generate the full token map for an elevation scope. `root` is the base theme; `elevated`
+ * (dialogs/sheets/popovers), `menu` (dropdowns/context menus/command palette — a higher float),
+ * and `sunken` (sidebar/wells) re-run the whole generator at a shifted base, so every role —
+ * surfaces, text, borders, status — stays internally consistent at that elevation. Apply the
+ * result to a scope element with {@link applyTheme}.
+ *
+ * Overrides scope precisely: a root `"bg-1"` entry moves the base every scope shifts from, a
+ * scope-qualified entry (`"el-bg-3"`) acts as that scope's own override map, and unqualified
+ * entries otherwise stay at the root — they never leak into a scope's run.
+ */
+declare function generateScopeTheme(input: ThemeInput, level: ElevationLevel, options?: GenerateThemeOptions): ThemeMap;
+//#endregion
+export { GenerateThemeOptions, generateScopeTheme, generateTheme };