@handamade/psi-tokens 0.17.0 → 0.19.0

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;
+};

package/dist/generate/palette.js

@@ -0,0 +1,93 @@
+import { contrastOf, hexFor, solveL } from "./solve.js";
+/** Accent chroma by character. Values sit inside sRGB for most hues; the
+ * solver (Task 4) caps per-hue where a given hue cannot carry them. */
+const ACCENT_CHROMA = {
+    muted: 0.06,
+    calm: 0.10,
+    balanced: 0.15,
+    vivid: 0.20,
+    electric: 0.26,
+};
+/** Status hues are fixed: green reads as success and red as danger regardless
+ * of the brand. Only their chroma follows the brand's character. */
+const STATUS_HUES = { success: 155, warning: 75, danger: 25 };
+/** The accent's nominal lightness — kept unless a white label cannot sit on it. */
+const ACCENT_L = 0.55;
+/**
+ * `fgOnAccent` is `ref.fgStaticWhite` in both base themes — pure white — and
+ * `fillAccent` is `slot.accent` untouched, so `componentLabelPairs`' first
+ * entry (`fgOnAccent` on `fillAccent`, the Button/Tag/Checkbox label) is
+ * decided entirely here, by the accent anchor's own lightness. Nothing
+ * downstream can rescue it: `solveOverrides` only controls the four text
+ * tokens, and neither `fgOnAccent` nor `fillAccent` traces to any of them.
+ *
+ * At a flat `l: 0.55` the pair is not safe by construction. Swept over 360
+ * hues × 5 chroma words, the worst case is hue 146 at `vivid` (c 0.20), which
+ * renders white-on-accent at **4.4979:1** — under AA, and the exact failure
+ * the prompt "bold calm app" produced. It cleared CI only because `derive.ts`
+ * checked the 28-pair `wcagAAPairs` while `scripts/build.ts` gates committed
+ * themes on all 33.
+ *
+ * So the accent is darkened — never lightened — to the lightest value that
+ * still carries a white label at `LABEL_TARGET`, a deliberate margin above
+ * 4.5 so that OKLCH→sRGB rounding and the 4-decimal truncation below cannot
+ * eat the guarantee. Most hue/chroma combinations already clear it and keep
+ * `l: 0.55` exactly.
+ *
+ * The alternative — solving `fgOnAccent` as a fifth escalating token — was
+ * rejected: a failure on that pair traces to none of the tokens
+ * `solveOverrides` escalates, so wiring the pair into the accept gate without
+ * this fix converts a rare AA miss into a rare hard throw ("derivation
+ * failed"), which is worse. Fixing the anchor makes the pair pass by
+ * construction, which is what the headline claim actually says.
+ *
+ * The three other solid-label pairs (`fgStaticWhite` on `fillSuccess` /
+ * `fillDanger`, `fgStaticBlack` on `fillWarning`) sit on fixed hues and were
+ * measured at 5.16 / 5.21 / 6.94:1 worst-case across the same sweep, so they
+ * need no equivalent treatment — but the sweep in
+ * `__tests__/generate-derive.test.ts` gates all 33 pairs, not just this one.
+ */
+const LABEL_TARGET = 4.65;
+function accentLightness(c, h) {
+    const white = "#ffffff";
+    if (contrastOf(hexFor(ACCENT_L, c, h), white) >= LABEL_TARGET)
+        return ACCENT_L;
+    // Contrast against white rises monotonically as lightness falls, and black
+    // clears any target, so `direction: "darker"` always converges — it returns
+    // the LEAST extreme (lightest) L that still clears, keeping the accent as
+    // close to the brand's intent as legibility allows.
+    const solved = solveL({ c, h, against: white, target: LABEL_TARGET, direction: "darker" });
+    // Truncate rather than round: the emitted `customers/<name>.ts` carries this
+    // literal, and rounding UP would hand the token build a lightness a hair
+    // above the one that was solved.
+    return Math.floor(Math.min(ACCENT_L, solved.l) * 10_000) / 10_000;
+}
+export function buildBrandPalette(v) {
+    const accentC = ACCENT_CHROMA[v.chroma];
+    // Neutrals carry a trace of the brand hue so the pair reads as one family.
+    const neutralC = Math.min(0.02, accentC * 0.12);
+    const statusC = Math.max(0.14, Math.min(0.22, accentC));
+    const palette = {
+        brandInkLight: { l: 0.25, c: neutralC, h: v.hue },
+        brandInkDark: { l: 0.95, c: neutralC, h: v.hue },
+        brandCanvasLight: { l: 0.96, c: neutralC * 0.5, h: v.hue },
+        brandCanvasDark: { l: 0.15, c: neutralC * 0.5, h: v.hue },
+        brandAccent: { l: accentLightness(accentC, v.hue), c: accentC, h: v.hue },
+        brandSuccess: { l: 0.52, c: statusC, h: STATUS_HUES.success },
+        brandWarning: { l: 0.75, c: statusC, h: STATUS_HUES.warning },
+        brandDanger: { l: 0.55, c: statusC, h: STATUS_HUES.danger },
+        white: { l: 1.0, c: 0, h: 0 },
+        black: { l: 0.0, c: 0, h: 0 },
+    };
+    const shared = {
+        accent: "brandAccent",
+        success: "brandSuccess",
+        warning: "brandWarning",
+        danger: "brandDanger",
+    };
+    return {
+        palette,
+        lightSlots: { ink: "brandInkLight", canvas: "brandCanvasLight", ...shared },
+        darkSlots: { ink: "brandInkDark", canvas: "brandCanvasDark", ...shared },
+    };
+}

package/dist/generate/prompt.d.ts

@@ -0,0 +1,7 @@
+import { type BrandVector } from "./types.js";
+/** FNV-1a, 32-bit. Seeds the PRNG so unknown prompts still derive something
+ * coherent, and the same prompt always derives the same brand. */
+export declare function fnv1a(input: string): number;
+/** Small counter-based PRNG. Deterministic given its seed. */
+export declare function seededRandom(seed: number): () => number;
+export declare function parsePrompt(prompt: string): BrandVector;

package/dist/generate/prompt.js

@@ -0,0 +1,62 @@
+import { CHROMAS, DARK_WORDS, FONT_SETS, HUES, LIGHT_WORDS, RADII } from "./dictionaries.js";
+import { CHROMA_WORDS, RADIUS_RUNGS } from "./types.js";
+/** FNV-1a, 32-bit. Seeds the PRNG so unknown prompts still derive something
+ * coherent, and the same prompt always derives the same brand. */
+export function fnv1a(input) {
+    let h = 2166136261;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+/** Small counter-based PRNG. Deterministic given its seed. */
+export function seededRandom(seed) {
+    let t = seed | 0;
+    return () => {
+        t = (t + 1831565813) | 0;
+        let r = Math.imul(t ^ (t >>> 15), 1 | t);
+        r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r;
+        return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function slugify(prompt) {
+    const slug = prompt
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48)
+        .replace(/-+$/g, "");
+    // A name must start with a letter to be a valid identifier stem.
+    return /^[a-z]/.test(slug) ? slug : `brand-${fnv1a(prompt).toString(36)}`;
+}
+function firstMatch(words, table) {
+    for (const w of words) {
+        const hit = table[w];
+        if (hit !== undefined)
+            return hit;
+    }
+    return undefined;
+}
+export function parsePrompt(prompt) {
+    const normalized = prompt.trim().toLowerCase();
+    const words = normalized.split(/[^a-z0-9]+/).filter(Boolean);
+    const rand = seededRandom(fnv1a(normalized));
+    const hue = firstMatch(words, HUES) ?? Math.floor(rand() * 360);
+    const chroma = firstMatch(words, CHROMAS) ??
+        CHROMA_WORDS[Math.floor(rand() * CHROMA_WORDS.length)];
+    const hasDark = words.some((w) => DARK_WORDS.has(w));
+    const hasLight = words.some((w) => LIGHT_WORDS.has(w));
+    // A prompt naming both, or neither, leans light — the site's default.
+    const mode = hasDark && !hasLight ? "dark" : "light";
+    const radius = firstMatch(words, RADII) ?? RADIUS_RUNGS[Math.floor(rand() * RADIUS_RUNGS.length)];
+    const fontSet = firstMatch(words, Object.fromEntries(Object.keys(FONT_SETS).map((k) => [k, k])));
+    return {
+        hue,
+        chroma,
+        mode,
+        radius,
+        ...(fontSet ? { fonts: FONT_SETS[fontSet] } : {}),
+        name: slugify(normalized),
+    };
+}

package/dist/generate/serialize.d.ts

@@ -0,0 +1,10 @@
+import type { DerivedPair } from "./derive.js";
+/**
+ * Emit the `customers/<name>.ts` source for a derived pair, plus the two lines
+ * that register it. Shape matches `scripts/new-theme.ts`, extended to a pair.
+ */
+export declare function serializeCustomerTheme(pair: DerivedPair): {
+    filename: string;
+    source: string;
+    registration: string;
+};

package/dist/generate/serialize.js

@@ -0,0 +1,167 @@
+/**
+ * kebab-slug → camelCase identifier stem.
+ *
+ * The trailing `[^A-Za-z0-9]` strip and the `-+` (rather than `-`) are both
+ * load-bearing. `-([a-z0-9])` alone left any hyphen with no following
+ * alphanumeric in place: `ident("a--b")` returned `"a-B"` and `ident("ab-")`
+ * returned `"ab-"` — a literal hyphen inside what is spliced in as a
+ * TypeScript identifier, so the emitted `customers/<name>.ts` would not parse.
+ * `parsePrompt`'s slugify cannot produce either shape, but `isBrandVector` and
+ * `api/theme.ts` accept a model-supplied name, and that is the untrusted path.
+ * Both now reject consecutive and trailing hyphens as well — this collapse is
+ * the second line, not the only one.
+ */
+function ident(name) {
+    return name
+        .replace(/-+([a-z0-9])/g, (_, ch) => ch.toUpperCase())
+        .replace(/[^A-Za-z0-9]/g, "");
+}
+function entryLine(name, e) {
+    return `  ${name}: { l: ${e.l}, c: ${e.c}, h: ${e.h} },`;
+}
+function slotsLiteral(slots) {
+    return Object.entries(slots)
+        .map(([k, v]) => `  ${k}: "${v}",`)
+        .join("\n");
+}
+function opLiteral(op) {
+    return `${op.op}(${op.value})`;
+}
+/** Which of the DSL's builder functions actually appear in the given
+ * overrides body text — `set`/`cap` from ChannelOp literals, `slot`/`ref`
+ * from `from:` sources, `token` wrapping each entry, `delta` only if a
+ * DeltaOp was emitted. `solveOverrides` never emits `delta` or `ref` today
+ * (it only sets l/c against a slot anchor), so importing them unconditionally
+ * would name two identifiers no emitted file ever uses — an
+ * `@typescript-eslint/no-unused-vars` error under this repo's lint config,
+ * which is one of the five required gates. */
+function usedBuilders(overridesBody) {
+    const builders = ["cap", "delta", "ref", "set", "slot", "token"];
+    return builders.filter((b) => new RegExp(`\\b${b}[.(]`).test(overridesBody));
+}
+/**
+ * Serialize the solved AA overrides.
+ *
+ * These are NOT optional decoration. The default theme formulas fail the
+ * contrast matrix on most generated palettes — that is the entire reason
+ * `solveOverrides` exists — so a `customers/<name>.ts` emitted without them
+ * would not merely render differently from the console preview: it would
+ * throw in the token build, whose WCAG gate runs over every committed theme.
+ * An unbuildable file is not "a real customer theme out".
+ *
+ * The emitted shape matches `acmeOverrides` in `customers/acme.ts`, which
+ * carries exactly this kind of per-hue correction by hand.
+ */
+function overridesLiteral(overrides) {
+    return Object.entries(overrides)
+        .map(([name, def]) => {
+        const parts = [];
+        if (def.from.type === "slot")
+            parts.push(`from: slot.${def.from.name}`);
+        else
+            parts.push(`from: ref.${def.from.name}`);
+        if (def.l)
+            parts.push(`l: ${opLiteral(def.l)}`);
+        if (def.c)
+            parts.push(`c: ${opLiteral(def.c)}`);
+        if (def.h)
+            parts.push(`h: ${opLiteral(def.h)}`);
+        if (def.alpha !== undefined)
+            parts.push(`alpha: ${def.alpha}`);
+        if (def.scopes)
+            parts.push(`scopes: ${JSON.stringify(def.scopes)}`);
+        return `  ${name}: token({ ${parts.join(", ")} }),`;
+    })
+        .join("\n");
+}
+/**
+ * The brand's font-role block, in exactly the shape `customers/ember.ts`
+ * carries by hand (`emberFonts`). Empty string when the vector names no
+ * fonts, so a colour-only brand emits no block and no `BrandFonts` import.
+ * `BrandFonts` comes from `./index.js` — a type-only import back into the
+ * registry that imports this file, same as ember's, erased at build time.
+ */
+function fontsLiteral(id, fonts) {
+    if (!fonts)
+        return "";
+    const body = Object.entries(fonts)
+        .map(([role, stack]) => `  ${role}: ${JSON.stringify(stack)},`)
+        .join("\n");
+    return `
+/** Brand-level font roles (D29). Psi ships no font files — the consumer loads
+ * these webfonts; the roles travel with the theme so the emitted brand is the
+ * whole vector, not just its colour half. */
+export const ${id}Fonts: BrandFonts = {
+${body}
+};
+`;
+}
+/**
+ * Emit the `customers/<name>.ts` source for a derived pair, plus the two lines
+ * that register it. Shape matches `scripts/new-theme.ts`, extended to a pair.
+ */
+export function serializeCustomerTheme(pair) {
+    const { vector, light, dark } = pair;
+    const id = ident(vector.name);
+    const palette = light.customerTheme.palette;
+    const radius = `var(--psi-radius-${vector.radius})`;
+    // A prompt containing `editorial`, `technical` or `friendly` gives the
+    // vector a font-role set (dictionaries.ts FONT_SETS), and `deriveMember`
+    // puts it on the CustomerTheme — but it used to stop there: nothing emitted
+    // it, so the copied-out source silently dropped half of what the prompt
+    // asked for. Not applying fonts in the live preview is fine (the site loads
+    // no webfonts); dropping them from the emitted brand is not.
+    const fontsBlock = fontsLiteral(id, vector.fonts);
+    const lightOverridesBody = overridesLiteral(light.customerTheme.overrides ?? {});
+    const darkOverridesBody = overridesLiteral(dark.customerTheme.overrides ?? {});
+    const builders = usedBuilders(`${lightOverridesBody}\n${darkOverridesBody}`);
+    const buildersImport = builders.length > 0
+        ? `import { ${builders.join(", ")} } from "../../dsl/builders.js";\n`
+        : "";
+    const fontsImport = fontsBlock ? `import type { BrandFonts } from "./index.js";\n` : "";
+    const source = `${buildersImport}import type { Palette, SlotMap, ThemeDef } from "../../dsl/types.js";
+${fontsImport}
+// Generated by the Psi theme console from the prompt:
+//   "${vector.name.replace(/-/g, " ")}"
+// Every pair in the WCAG AA matrix is solved, in both modes, by construction.
+
+export const ${id}Palette: Palette = {
+${Object.entries(palette).map(([n, e]) => entryLine(n, e)).join("\n")}
+};
+
+/** Light member — ink is dark, canvas is light. */
+export const ${id}Slots: SlotMap = {
+${slotsLiteral(light.customerTheme.slots)}
+};
+
+/** Dark member — the same brand hue, lightness anchors inverted. */
+export const ${id}DarkSlots: SlotMap = {
+${slotsLiteral(dark.customerTheme.slots)}
+};
+
+/** Solved AA corrections for the light member. Without these the default
+ * formulas miss the contrast matrix on this palette and the build throws. */
+export const ${id}Overrides: ThemeDef = {
+${lightOverridesBody}
+};
+
+/** Solved AA corrections for the dark member. */
+export const ${id}DarkOverrides: ThemeDef = {
+${darkOverridesBody}
+};
+
+${fontsBlock}
+/** One dial for control shape (D56). */
+export const ${id}ComponentOverrides: Record<string, string> = {
+  "control-radius": "${radius}",
+};
+`;
+    // BOTH keys are quoted. A kebab slug is not a valid bare object key, and
+    // every multi-word prompt produces one. `fonts` is registered on both
+    // members — an exported const nothing registers would be dead source, and
+    // the brand's typography is not a light-mode-only property.
+    const fontsField = fontsBlock ? `fonts: ${id}Fonts, ` : "";
+    const registration = `  "${vector.name}": { palette: ${id}Palette, slots: ${id}Slots, overrides: ${id}Overrides, ${fontsField}componentOverrides: ${id}ComponentOverrides },
+  "${vector.name}-dark": { palette: ${id}Palette, slots: ${id}DarkSlots, base: "dark", overrides: ${id}DarkOverrides, ${fontsField}componentOverrides: ${id}ComponentOverrides },`;
+    return { filename: `${vector.name}.ts`, source, registration };
+}