@handamade/psi-tokens 0.18.0 → 0.20.0

package/dist/dsl/validator.js

@@ -0,0 +1,97 @@
+import { isKnownScopeEntry } from "../scopes.js";
+// ── Validation error ───────────────────────────────────────────────
+export class ValidationError extends Error {
+    path;
+    constructor(message, path = []) {
+        super(message);
+        this.name = "ValidationError";
+        this.path = path;
+    }
+}
+// ── Cycle detection ────────────────────────────────────────────────
+function detectCycles(theme) {
+    const visited = new Set();
+    const inStack = new Set();
+    function dfs(name, chain) {
+        if (inStack.has(name)) {
+            const cycleStart = chain.indexOf(name);
+            const cycle = chain.slice(cycleStart).concat(name);
+            throw new ValidationError(`Circular reference detected: ${cycle.join(" → ")}`, cycle);
+        }
+        if (visited.has(name))
+            return;
+        inStack.add(name);
+        chain.push(name);
+        const token = theme[name];
+        if (token?.from.type === "ref") {
+            dfs(token.from.name, chain);
+        }
+        chain.pop();
+        inStack.delete(name);
+        visited.add(name);
+    }
+    for (const name of Object.keys(theme)) {
+        dfs(name, []);
+    }
+}
+// ── Main validator ─────────────────────────────────────────────────
+export function validate(theme, slots, existingNames = []) {
+    const slotNames = new Set(Object.keys(slots));
+    const tokenNames = new Set(Object.keys(theme));
+    // Check for duplicate names against existingNames
+    for (const name of tokenNames) {
+        if (existingNames.includes(name)) {
+            throw new ValidationError(`Duplicate token name: "${name}" already exists`, [name]);
+        }
+    }
+    // Validate each token's source
+    for (const [name, token] of Object.entries(theme)) {
+        const { from } = token;
+        if (from.type === "slot") {
+            if (!slotNames.has(from.name)) {
+                throw new ValidationError(`Unknown slot "${from.name}" in token "${name}"`, [name]);
+            }
+        }
+        else if (from.type === "ref") {
+            if (!tokenNames.has(from.name)) {
+                throw new ValidationError(`Unknown ref "${from.name}" in token "${name}"`, [name]);
+            }
+        }
+        for (const entry of token.scopes ?? []) {
+            if (!isKnownScopeEntry(entry)) {
+                throw new ValidationError(`Unknown scope entry "${entry}" in token "${name}" — not a known CSS property or declared group`, [name]);
+            }
+        }
+    }
+    // Detect cycles in ref chains
+    detectCycles(theme);
+}
+/** D46: the same token name must carry identical scopes in every theme —
+ * scopes are a property of the token's meaning, not of a theme. */
+export function validateScopeConsistency(themes) {
+    const seen = new Map();
+    for (const [themeName, theme] of Object.entries(themes)) {
+        for (const [name, def] of Object.entries(theme)) {
+            const key = JSON.stringify(def.scopes ?? null);
+            const prior = seen.get(name);
+            if (prior === undefined) {
+                seen.set(name, { theme: themeName, scopes: key });
+            }
+            else if (prior.scopes !== key) {
+                throw new ValidationError(`Scope drift for token "${name}": ${prior.theme} declares ${prior.scopes}, ${themeName} declares ${key}`, [name]);
+            }
+        }
+    }
+}
+// Both gates resolve --psi-* names scale-first, so a semantic token whose
+// kebab name starts with a scale-family prefix would be silently shadowed.
+const SCALE_FAMILY_PREFIX = /^(space|size|radius|text|font|duration|ease|z)-/;
+/** D46 follow-up (HAN-21): reject semantic token kebab names that a
+ * scale-family lookup would shadow before the semantic lookup runs. */
+export function validateNoScalePrefixShadow(kebabNames) {
+    for (const name of kebabNames) {
+        if (SCALE_FAMILY_PREFIX.test(name)) {
+            throw new ValidationError(`Semantic token "${name}" starts with a scale-family prefix — it would be shadowed by the scale lookup in the build and stylelint gates`, [name]);
+        }
+    }
+}

package/dist/emit/css.d.ts

@@ -0,0 +1,30 @@
+import type { ChannelOp, Palette, SlotMap, ThemeDef, TokenDef } from "../dsl/types.js";
+import type { BrandFonts } from "../themes/customers/index.js";
+export declare function camelToKebab(str: string): string;
+export declare function tokenVar(name: string): string;
+export declare function paletteVar(name: string): string;
+/**
+ * Convert a ChannelOp to its CSS representation within oklch(from ...).
+ * - set  → literal value
+ * - delta → calc(channel +/- value)
+ * - cap  → min(channel, value)
+ */
+export declare function opToCSS(channel: string, op: ChannelOp): string;
+/**
+ * Assemble the full oklch(from var(...) ...) expression for a token.
+ *
+ * Slot-sourced token with ops:
+ *   oklch(from var(--psi-palette-sapphire) 0.65 min(c, 0.23) h)
+ *
+ * Ref-sourced token with alpha:
+ *   oklch(from var(--psi-fg-primary) l c h / 0.7)
+ *
+ * No-op (just a slot reference, no ops, no alpha):
+ *   var(--psi-palette-platinum)
+ */
+export declare function tokenToLiveCSS(def: TokenDef, slots: SlotMap): string;
+export declare function emitBaseCSS(palette: Palette): string;
+export declare function emitThemeCSS(themeName: string, theme: ThemeDef, palette: Palette, slots: SlotMap, opts?: {
+    fonts?: BrandFonts;
+    componentOverrides?: Record<string, string>;
+}): string;

package/dist/emit/css.js

@@ -0,0 +1,120 @@
+// ── Helpers ────────────────────────────────────────────────────────
+export function camelToKebab(str) {
+    return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+export function tokenVar(name) {
+    return `--psi-${camelToKebab(name)}`;
+}
+export function paletteVar(name) {
+    return `--psi-palette-${name}`;
+}
+/**
+ * Convert a ChannelOp to its CSS representation within oklch(from ...).
+ * - set  → literal value
+ * - delta → calc(channel +/- value)
+ * - cap  → min(channel, value)
+ */
+export function opToCSS(channel, op) {
+    switch (op.op) {
+        case "set":
+            return `${op.value}`;
+        case "delta": {
+            const sign = op.value >= 0 ? "+" : "-";
+            const abs = Math.abs(op.value);
+            return `calc(${channel} ${sign} ${abs})`;
+        }
+        case "cap":
+            return `min(${channel}, ${op.value})`;
+    }
+}
+/**
+ * Assemble the full oklch(from var(...) ...) expression for a token.
+ *
+ * Slot-sourced token with ops:
+ *   oklch(from var(--psi-palette-sapphire) 0.65 min(c, 0.23) h)
+ *
+ * Ref-sourced token with alpha:
+ *   oklch(from var(--psi-fg-primary) l c h / 0.7)
+ *
+ * No-op (just a slot reference, no ops, no alpha):
+ *   var(--psi-palette-platinum)
+ */
+export function tokenToLiveCSS(def, slots) {
+    const hasOps = def.l || def.c || def.h;
+    const hasAlpha = def.alpha !== undefined;
+    // Determine the source CSS var
+    let sourceVar;
+    if (def.from.type === "slot") {
+        const paletteName = slots[def.from.name];
+        sourceVar = `var(${paletteVar(paletteName)})`;
+    }
+    else {
+        sourceVar = `var(${tokenVar(def.from.name)})`;
+    }
+    // If no operations and no alpha, just reference the var directly
+    if (!hasOps && !hasAlpha) {
+        return sourceVar;
+    }
+    // Build oklch(from ...) expression
+    const lPart = def.l ? opToCSS("l", def.l) : "l";
+    const cPart = def.c ? opToCSS("c", def.c) : "c";
+    const hPart = def.h ? opToCSS("h", def.h) : "h";
+    let expr = `oklch(from ${sourceVar} ${lPart} ${cPart} ${hPart}`;
+    if (hasAlpha) {
+        expr += ` / ${def.alpha}`;
+    }
+    expr += `)`;
+    return expr;
+}
+// ── Base CSS (palette) ────────────────────────────────────────────
+export function emitBaseCSS(palette) {
+    const lines = [];
+    lines.push("@layer psi.base, psi.theme, psi.components, psi.utilities;");
+    lines.push("");
+    lines.push("@layer psi.base {");
+    lines.push("  :root {");
+    for (const [name, entry] of Object.entries(palette)) {
+        lines.push(`    ${paletteVar(name)}: oklch(${entry.l} ${entry.c} ${entry.h});`);
+    }
+    lines.push("  }");
+    lines.push("}");
+    return lines.join("\n") + "\n";
+}
+// ── Theme CSS (semantic tokens) ───────────────────────────────────
+export function emitThemeCSS(themeName, theme, palette, slots, opts) {
+    const lines = [];
+    // Determine selector
+    const selector = themeName === "light"
+        ? `:root, [data-psi-theme="light"]`
+        : `[data-psi-theme="${themeName}"]`;
+    lines.push("@layer psi.theme {");
+    lines.push(`  ${selector} {`);
+    // Scope this theme's own palette vars inside its selector block so a
+    // customer brand's colors ship only with that theme, and two customers
+    // that happen to reuse an anchor name can't collide in a shared :root.
+    for (const [name, entry] of Object.entries(palette)) {
+        lines.push(`    ${paletteVar(name)}: oklch(${entry.l} ${entry.c} ${entry.h});`);
+    }
+    for (const [name, def] of Object.entries(theme)) {
+        const cssVar = tokenVar(name);
+        const value = tokenToLiveCSS(def, slots);
+        lines.push(`    ${cssVar}: ${value};`);
+    }
+    if (opts?.fonts) {
+        for (const [role, stack] of Object.entries(opts.fonts)) {
+            lines.push(`    --psi-font-${role}: ${stack};`);
+        }
+    }
+    lines.push("  }");
+    lines.push("}");
+    if (opts?.componentOverrides && Object.keys(opts.componentOverrides).length > 0) {
+        lines.push("@layer psi.components {");
+        lines.push(`  [data-psi-theme="${themeName}"] {`);
+        for (const [name, value] of Object.entries(opts.componentOverrides)) {
+            lines.push(`    --psi-${name}: ${value};`);
+        }
+        lines.push("  }");
+        lines.push("}");
+    }
+    return lines.join("\n") + "\n";
+}

package/dist/gamut.d.ts

@@ -0,0 +1,4 @@
+import type { Palette, SlotMap, ThemeDef } from "./dsl/types.js";
+import type { ResolvedTheme } from "./dsl/resolver.js";
+/** Warn when sRGB clamping moved a resolved value by ΔE2000 > 2 (D19). */
+export declare function gamutWarnings(resolved: ResolvedTheme, theme: ThemeDef, palette: Palette, slots: SlotMap): string[];

package/dist/gamut.js

@@ -0,0 +1,44 @@
+import { differenceCiede2000 } from "culori";
+const dE = differenceCiede2000();
+function applyOp(base, op) {
+    if (!op)
+        return base;
+    if (op.op === "set")
+        return op.value;
+    if (op.op === "delta")
+        return base + op.value;
+    return Math.min(base, op.value); // cap
+}
+/** Warn when sRGB clamping moved a resolved value by ΔE2000 > 2 (D19). */
+export function gamutWarnings(resolved, theme, palette, slots) {
+    const warnings = [];
+    const raw = new Map();
+    // Recomputes pre-clamp OKLCH values by replaying token operations WITHOUT sRGB clamping.
+    // Unlike the resolver (which clamps at each step), this intentionally propagates unclamped values
+    // through ref chains so the warning reflects cumulative drift from authored intent. Do not "fix" this
+    // to match the resolver's clamping behavior — the unclamped result is required to diagnose palette issues.
+    function rawOf(name) {
+        const hit = raw.get(name);
+        if (hit)
+            return hit;
+        const def = theme[name];
+        const base = def.from.type === "slot"
+            ? palette[slots[def.from.name]]
+            : rawOf(def.from.name);
+        const val = {
+            l: applyOp(base.l, def.l),
+            c: applyOp(base.c, def.c),
+            h: applyOp(base.h, def.h),
+        };
+        raw.set(name, val);
+        return val;
+    }
+    for (const name of Object.keys(theme)) {
+        const pre = { mode: "oklch", ...rawOf(name) };
+        const post = { mode: "oklch", ...resolved[name].oklch };
+        const d = dE(pre, post);
+        if (d > 2)
+            warnings.push(`${name}: clamped ΔE ${d.toFixed(1)} (${JSON.stringify(rawOf(name))} → hex ${resolved[name].hex}) — adjust the palette anchor`);
+    }
+    return warnings;
+}

package/dist/generate/derive.d.ts

@@ -0,0 +1,20 @@
+import { type ResolvedTheme } from "../dsl/resolver.js";
+import { type CustomerTheme } from "../themes/customers/index.js";
+import type { BrandVector } from "./types.js";
+export interface DerivedTheme {
+    mode: "light" | "dark";
+    customerTheme: CustomerTheme;
+    resolved: ResolvedTheme;
+    customProperties: Record<string, string>;
+}
+export interface DerivedPair {
+    vector: BrandVector;
+    light: DerivedTheme;
+    dark: DerivedTheme;
+}
+/**
+ * Derive both members of a brand from one vector, each solved to AA
+ * independently (D57). The header toggle then selects between them — there is
+ * nothing left to recompute.
+ */
+export declare function deriveTheme(v: BrandVector): DerivedPair;

package/dist/generate/derive.js

@@ -0,0 +1,232 @@
+import { checkContrast, componentLabelPairs, wcagAAPairs } from "../contrast-matrix.js";
+import { resolve } from "../dsl/resolver.js";
+import { cap, set, slot, token } from "../dsl/builders.js";
+import { assembleCustomerTheme, } from "../themes/customers/index.js";
+import { buildBrandPalette } from "./palette.js";
+import { hexFor, solveL } from "./solve.js";
+/** camelCase token name → --psi-kebab-case custom property. */
+function cssName(token) {
+    return `--psi-${token.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)}`;
+}
+/** The channels of `hex` with an exact alpha. checkContrast composites
+ * tok.hex (gamut-clamped, 8-bit per channel) with the unrounded alpha, so
+ * this is the only form that renders precisely what was validated. hex8
+ * cannot: it quantizes alpha to 1/255, which moves the composited result a
+ * full channel step and drops near-threshold pairs below 4.5 (measured: 384
+ * of 1225 sampled prompts had a pair render under AA with hex8). Deliberately
+ * not `oklch(l c h / a)` either — the browser would recompute RGB from OKLCH
+ * and could land a bit away from `formatHex`'s own rounding, reintroducing
+ * the same class of mismatch between what was validated and what renders. */
+function withAlpha(hex, alpha) {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return `rgb(${r} ${g} ${b} / ${alpha})`;
+}
+/**
+ * The gate, and it must be the SAME set `scripts/build.ts` runs over every
+ * committed theme: `[...wcagAAPairs, ...componentLabelPairs]`, 33 pairs.
+ *
+ * Checking only `wcagAAPairs` (28) is what let "a theme derived from any
+ * prompt clears the AA matrix by construction" ship false a third time. The
+ * five-pair delta is `componentLabelPairs` — solid variant labels on their
+ * fills — and the first of them, `fgOnAccent` on `fillAccent`, sat right at
+ * the threshold: `bold calm app` (hue 146, `vivid`) rendered it at 4.4979:1 in
+ * BOTH modes while the console printed "zero failures — by construction", and
+ * the `customers/bold-calm-app.ts` that prompt emitted threw in `pnpm build`,
+ * which had been checking all 33 the whole time.
+ *
+ * `buildBrandPalette` is what makes the extra five pass by construction (see
+ * `accentLightness` there for why the fix has to be upstream of this loop
+ * rather than another escalating target inside it).
+ */
+const AA_MATRIX = [...wcagAAPairs, ...componentLabelPairs];
+const BASE_TARGET = 4.5;
+const TARGET_ESCALATION = 0.1;
+const MAX_OUTER_ATTEMPTS = 40;
+/** The four text tokens this function solves, mapped to the palette slot
+ * their colour anchors on. The second element is the SLOT name ("accent"),
+ * not the palette key ("brandAccent") — `slot.accent` is what a TokenDef
+ * sources from, while the anchor is looked up through `slots` to reach the
+ * palette entry. */
+const TEXT_TOKENS = [
+    ["fgAccent", "accent"],
+    ["fgSuccess", "success"],
+    ["fgWarning", "warning"],
+    ["fgDanger", "danger"],
+];
+/** bg token name → the text token whose colour it derives from (light.ts /
+ * dark.ts: `fillTintAccent: token({ from: ref.fgAccent, ... })`, etc). Lets
+ * the escalation loop trace a failing pair like `{ fg: "fgPrimary", bg:
+ * "fillTintAccent" }` (the D62 selected-row pair) back to the token that
+ * actually controls it, even though that token appears nowhere in the pair
+ * itself. */
+const TINT_SOURCE = {
+    fillTintAccent: "fgAccent",
+    fillTintSuccess: "fgSuccess",
+    fillTintWarning: "fgWarning",
+    fillTintDanger: "fgDanger",
+};
+/**
+ * Per-hue overrides that keep the AA matrix clean, in exactly the shape acme
+ * carries by hand (`acmeOverrides`). Text tokens force their own L in the base
+ * themes, so the free variables here are that L and the chroma cap.
+ *
+ * Solving each text token to exactly 4.5:1 against the canvas is not enough:
+ * `wcagAAPairs` also gates the SAME foreground against its own tint fill
+ * (`fillTintAccent` etc.) — canvas tinted 12–15% toward the very colour being
+ * tested — and, for the status tokens, against `bgSecondary`. Both are
+ * strictly harder than plain canvas contrast (the tint background is closer
+ * in colour to the foreground than the canvas is), so a token solved to land
+ * exactly on the canvas threshold lands *under* AA on those pairs — this is
+ * what the initial `it.each` sweep caught (5 prompts, both text-on-canvas and
+ * text-on-tint failures, e.g. `fgAccent/fillTintAccent 3.88<4.5`).
+ *
+ * The accept/reject gate for the whole function is the FULL `AA_MATRIX`
+ * sweep against the real resolved theme, not a per-token subset: a per-token
+ * filter (`p.fg === name`) is blind to cross pairs whose `bg` a token
+ * controls indirectly but whose `fg` is something else — e.g. `{ fg:
+ * "fgPrimary", bg: "fillTintAccent" }` (D62) is only visible once
+ * `fillTintAccent`'s own dependency on `fgAccent` is traced via
+ * `TINT_SOURCE`. Solving each token in isolation and declaring victory once
+ * IT is happy would leave that pair free to fail with no one watching. Each
+ * outer pass solves all four tokens at their current targets, resolves the
+ * real theme, and checks every pair in `wcagAAPairs`; any failure escalates
+ * the target of whichever token owns it (traced through `TINT_SOURCE` when
+ * the failure isn't already `fg === token`) and the whole thing is retried.
+ * The loop cannot return successfully while any pair in the matrix fails —
+ * it either converges within `MAX_OUTER_ATTEMPTS` or throws.
+ */
+function solveOverrides(palette, slots, mode) {
+    const canvas = palette[slots.canvas];
+    const canvasHex = hexFor(canvas.l, canvas.c, canvas.h);
+    const direction = mode === "light" ? "darker" : "lighter";
+    // Solve a single text token's L/chroma against a given canvas-contrast
+    // target. Reduces chroma and re-solves when the target is unreachable at
+    // the anchor's own chroma — exactly what acme's hand-tuned caps
+    // (`acmeOverrides`) do by hand. Reading `.cleared` is not optional:
+    // `solveL` returns its most legible available value when it gives up, so
+    // ignoring the flag would ship a below-AA colour that looks like a solved
+    // one.
+    function solveOne(slotName, target) {
+        const anchor = palette[slots[slotName]];
+        let c = anchor.c;
+        let solved = solveL({ c, h: anchor.h, against: canvasHex, target, direction });
+        while (!solved.cleared && c > 0) {
+            c = Math.max(0, c - 0.008);
+            solved = solveL({ c, h: anchor.h, against: canvasHex, target, direction });
+        }
+        if (!solved.cleared) {
+            throw new Error(`solveOverrides: ${slotName} cannot clear ${target}:1 against ${canvasHex} at any chroma`);
+        }
+        // Deliberately NO `scopes`. `assembleCustomerTheme` inherits the base
+        // token's scopes when an override declares none (D46), and the base
+        // declarations are not uniform: `fgDanger` is `["text", "border"]` in both
+        // light.ts and dark.ts, while the other three are `["text"]`. Hardcoding
+        // `["text"]` here silently narrowed fgDanger — invisible in-memory (the
+        // console never runs the scope gate) but fatal in the token build, which
+        // rejects the emitted `customers/<name>.ts` with
+        // `Scope drift for token "fgDanger": light declares ["text","border"],
+        // <name> declares ["text"]` before the contrast gate is even reached.
+        return token({
+            from: slot[slotName],
+            l: set(Number(solved.l.toFixed(4))),
+            c: cap(Number(c.toFixed(4))),
+        });
+    }
+    const targets = {};
+    for (const [name] of TEXT_TOKENS)
+        targets[name] = BASE_TARGET;
+    let overrides = {};
+    let lastFailures = [];
+    for (let outer = 0; outer < MAX_OUTER_ATTEMPTS; outer++) {
+        overrides = {};
+        for (const [name, slotName] of TEXT_TOKENS) {
+            overrides[name] = solveOne(slotName, targets[name]);
+        }
+        const trialResolved = resolve(assembleCustomerTheme({ palette, slots, base: mode, overrides }), palette, slots);
+        const failures = checkContrast(trialResolved, AA_MATRIX).filter((r) => !r.pass);
+        if (failures.length === 0) {
+            lastFailures = [];
+            break;
+        }
+        lastFailures = failures.map((f) => `${f.fg}/${f.bg} ${f.ratio}<${f.minRatio}`);
+        let escalatedAny = false;
+        for (const f of failures) {
+            const owner = f.fg in targets ? f.fg : TINT_SOURCE[f.bg];
+            if (owner !== undefined && owner in targets) {
+                targets[owner] = targets[owner] + TARGET_ESCALATION;
+                escalatedAny = true;
+            }
+        }
+        // A failing pair this loop cannot trace to any of the four tokens it
+        // controls (fg isn't one of them, bg isn't a tint of one of them) is not
+        // something escalating a target will ever fix — retrying would just burn
+        // the remaining attempts for no reason, so give up immediately with the
+        // specific failures rather than a generic "still fails" after 40 no-op
+        // attempts.
+        if (!escalatedAny) {
+            throw new Error(`solveOverrides: failure(s) outside the four solved tokens' control: ${lastFailures.join(", ")}`);
+        }
+    }
+    if (lastFailures.length > 0) {
+        throw new Error(`solveOverrides: still fails after ${MAX_OUTER_ATTEMPTS} escalations: ${lastFailures.join(", ")}`);
+    }
+    return overrides;
+}
+function deriveMember(v, palette, slots, mode) {
+    const customerTheme = {
+        palette,
+        slots,
+        base: mode,
+        overrides: solveOverrides(palette, slots, mode),
+        ...(v.fonts ? { fonts: v.fonts } : {}),
+        componentOverrides: { "control-radius": `var(--psi-radius-${v.radius})` },
+    };
+    const resolved = resolve(assembleCustomerTheme(customerTheme), palette, slots);
+    const customProperties = {};
+    for (const [name, tok] of Object.entries(resolved)) {
+        // tok.hex is always opaque — formatHex discards alpha. Tokens like
+        // fillTint* and the scrims carry alpha, and dropping it makes them
+        // byte-identical to the token they derive from (e.g. fillTintAccent
+        // would render as fgAccent at full strength): checkContrast composites
+        // alpha correctly, so the AA sweep would still pass while the shipped
+        // custom property renders the guarantee false in the browser. `withAlpha`
+        // carries the exact float alpha checkContrast validated against — see its
+        // own comment for why hex8 (1/255 alpha quantization) isn't safe here.
+        const alpha = tok.oklch.alpha;
+        customProperties[cssName(name)] =
+            alpha === undefined || alpha >= 1 ? tok.hex : withAlpha(tok.hex, alpha);
+    }
+    for (const [name, value] of Object.entries(customerTheme.componentOverrides ?? {})) {
+        customProperties[`--psi-${name}`] = value;
+    }
+    return { mode, customerTheme, resolved, customProperties };
+}
+/**
+ * Derive both members of a brand from one vector, each solved to AA
+ * independently (D57). The header toggle then selects between them — there is
+ * nothing left to recompute.
+ */
+export function deriveTheme(v) {
+    const { palette, lightSlots, darkSlots } = buildBrandPalette(v);
+    const pair = {
+        vector: v,
+        light: deriveMember(v, palette, lightSlots, "light"),
+        dark: deriveMember(v, palette, darkSlots, "dark"),
+    };
+    // Belt and braces: the solver targets the text pairs directly, but the AA
+    // matrix covers more than those — including the five `componentLabelPairs`
+    // no target inside `solveOverrides` can move, which is exactly why this
+    // check runs over `AA_MATRIX` and not the narrower `wcagAAPairs`. A residual
+    // failure means a bug in the solver or the palette anchors, not bad input,
+    // so surface it loudly in development.
+    for (const member of [pair.light, pair.dark]) {
+        const failures = checkContrast(member.resolved, AA_MATRIX).filter((r) => !r.pass);
+        if (failures.length > 0) {
+            throw new Error(`deriveTheme: ${member.mode} left ${failures.length} AA failure(s): ` +
+                failures.map((f) => `${f.fg}/${f.bg} ${f.ratio}<${f.minRatio}`).join(", "));
+        }
+    }
+    return pair;
+}

package/dist/generate/dictionaries.d.ts

@@ -0,0 +1,18 @@
+import type { ChromaWord, RadiusRung } from "./types.js";
+/** Keyword → accent hue in OKLCH degrees. */
+export declare const HUES: Readonly<Record<string, number>>;
+/** Keyword → chroma character. */
+export declare const CHROMAS: Readonly<Record<string, ChromaWord>>;
+/** Words that imply the brand is shown dark-first, or light-first. */
+export declare const DARK_WORDS: ReadonlySet<string>;
+export declare const LIGHT_WORDS: ReadonlySet<string>;
+/** Keyword → on-scale radius rung (D56). */
+export declare const RADII: Readonly<Record<string, RadiusRung>>;
+/**
+ * Font roles by character. Psi ships no font files (D29) — this assigns roles
+ * only, and consumers load the webfonts.
+ */
+export declare const FONT_SETS: Readonly<Record<string, {
+    display: string;
+    sans: string;
+}>>;

package/dist/generate/dictionaries.js

@@ -0,0 +1,46 @@
+/** Keyword → accent hue in OKLCH degrees. */
+export const HUES = {
+    ocean: 235, sea: 225, water: 220, sky: 215, lagoon: 200, aqua: 185,
+    cyan: 195, teal: 190, midnight: 260, navy: 255, space: 265, cosmic: 280,
+    forest: 145, moss: 130, sage: 140, mint: 165, jungle: 150, olive: 105,
+    lime: 120, sunset: 35, ember: 30, fire: 28, rust: 30, terracotta: 35,
+    desert: 65, sand: 75, gold: 85, amber: 75, honey: 80, mustard: 90,
+    violet: 295, grape: 290, lavender: 285, plum: 320, orchid: 310,
+    rose: 350, blush: 355, coral: 20, salmon: 25, crimson: 15, wine: 5,
+    slate: 240, storm: 245, graphite: 250, cyber: 195, matrix: 140, retro: 40,
+};
+/** Keyword → chroma character. */
+export const CHROMAS = {
+    muted: "muted", faded: "muted", minimal: "muted", quiet: "muted",
+    misty: "muted", noir: "muted",
+    calm: "calm", soft: "calm", gentle: "calm", pastel: "calm", zen: "calm",
+    clean: "calm", simple: "calm", elegant: "calm",
+    bold: "vivid", punchy: "vivid", loud: "vivid", hot: "vivid",
+    vivid: "vivid", saturated: "vivid",
+    neon: "electric", electric: "electric", candy: "electric",
+    cyber: "electric", circus: "electric",
+};
+/** Words that imply the brand is shown dark-first, or light-first. */
+export const DARK_WORDS = new Set([
+    "midnight", "noir", "dark", "night", "space", "cosmic", "cyber", "matrix",
+    "storm", "graphite", "eclipse", "shadow", "deep",
+]);
+export const LIGHT_WORDS = new Set([
+    "light", "bright", "sunrise", "dawn", "day", "airy", "pastel", "cream",
+    "paper", "linen", "snow", "clean",
+]);
+/** Keyword → on-scale radius rung (D56). */
+export const RADII = {
+    sharp: 4, brutalist: 4, technical: 4, precise: 4, editorial: 4,
+    crisp: 6, modern: 6, tailored: 6,
+    soft: 12, friendly: 12, round: 12, playful: 12, whimsy: 12, candy: 12,
+};
+/**
+ * Font roles by character. Psi ships no font files (D29) — this assigns roles
+ * only, and consumers load the webfonts.
+ */
+export const FONT_SETS = {
+    editorial: { display: "Fraunces", sans: "Inter" },
+    technical: { display: "IBM Plex Sans", sans: "IBM Plex Sans" },
+    friendly: { display: "Nunito", sans: "Nunito Sans" },
+};

package/dist/generate/index.d.ts

@@ -0,0 +1,6 @@
+export { parsePrompt, fnv1a, seededRandom } from "./prompt.js";
+export { buildBrandPalette } from "./palette.js";
+export { hexFor, contrastOf, solveL } from "./solve.js";
+export { deriveTheme, type DerivedTheme, type DerivedPair } from "./derive.js";
+export { serializeCustomerTheme } from "./serialize.js";
+export { isBrandVector, CHROMA_WORDS, RADIUS_RUNGS, type BrandVector, type ChromaWord, type RadiusRung, } from "./types.js";

package/dist/generate/index.js

@@ -0,0 +1,6 @@
+export { parsePrompt, fnv1a, seededRandom } from "./prompt.js";
+export { buildBrandPalette } from "./palette.js";
+export { hexFor, contrastOf, solveL } from "./solve.js";
+export { deriveTheme } from "./derive.js";
+export { serializeCustomerTheme } from "./serialize.js";
+export { isBrandVector, CHROMA_WORDS, RADIUS_RUNGS, } from "./types.js";

package/dist/generate/palette.d.ts

@@ -0,0 +1,7 @@
+import type { Palette, SlotMap } from "../dsl/types.js";
+import type { BrandVector } from "./types.js";
+export declare function buildBrandPalette(v: BrandVector): {
+    palette: Palette;
+    lightSlots: SlotMap;
+    darkSlots: SlotMap;
+};