@handamade/psi-tokens 0.18.0 → 0.19.0

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

package/dist/generate/solve.d.ts

@@ -0,0 +1,36 @@
+/** OKLCH → gamut-clamped sRGB hex. Mirrors what the resolver emits, so a
+ * solved value renders as the same colour the token build would produce. */
+export declare function hexFor(l: number, c: number, h: number): string;
+/** The repo's one WCAG implementation, shared with contrast-matrix.ts. */
+export declare function contrastOf(aHex: string, bHex: string): number;
+export interface SolvedL {
+    /** The chosen lightness. */
+    l: number;
+    /** True when `l` genuinely clears `target`. False means the target was
+     * unreachable at this chroma and hue, and `l` is merely the most legible
+     * value available — the caller MUST reduce chroma and try again. */
+    cleared: boolean;
+}
+/**
+ * Binary-search lightness until a colour clears `target` against `against`.
+ *
+ * `direction` says which way legibility lies: "darker" for ink on a light
+ * canvas, "lighter" for ink on a dark one. The search runs between the
+ * canvas-side bound and the far extreme, converging on the *least* extreme
+ * lightness that still clears the ratio — so a solved colour stays as close
+ * to the brand's intent as the target allows.
+ *
+ * If the target is unreachable at this chroma and hue, `cleared: false` is
+ * returned along with the extreme: the most legible value available rather
+ * than a thrown error. Callers pair this with a chroma reduction, which is
+ * what makes the target reachable for saturated hues — but they must check
+ * `cleared` to know when that retry is required, since a below-AA `l` looks
+ * identical to a solved one otherwise.
+ */
+export declare function solveL(opts: {
+    c: number;
+    h: number;
+    against: string;
+    target: number;
+    direction: "darker" | "lighter";
+}): SolvedL;

package/dist/generate/solve.js

@@ -0,0 +1,56 @@
+import { clampChroma, formatHex, wcagContrast } from "culori";
+/** OKLCH → gamut-clamped sRGB hex. Mirrors what the resolver emits, so a
+ * solved value renders as the same colour the token build would produce. */
+export function hexFor(l, c, h) {
+    if (!Number.isFinite(l) || !Number.isFinite(c) || !Number.isFinite(h)) {
+        // culori coerces NaN to 0, which yields #000000 — a colour that trivially
+        // clears contrast against any light canvas. Failing loudly here keeps a
+        // bug upstream from masquerading as a passing theme.
+        throw new Error(`hexFor: non-finite OKLCH (l=${l}, c=${c}, h=${h})`);
+    }
+    const clamped = clampChroma({ mode: "oklch", l, c, h }, "oklch");
+    return formatHex(clamped) ?? "#000000";
+}
+/** The repo's one WCAG implementation, shared with contrast-matrix.ts. */
+export function contrastOf(aHex, bHex) {
+    return wcagContrast(aHex, bHex);
+}
+const ITERATIONS = 28;
+/**
+ * Binary-search lightness until a colour clears `target` against `against`.
+ *
+ * `direction` says which way legibility lies: "darker" for ink on a light
+ * canvas, "lighter" for ink on a dark one. The search runs between the
+ * canvas-side bound and the far extreme, converging on the *least* extreme
+ * lightness that still clears the ratio — so a solved colour stays as close
+ * to the brand's intent as the target allows.
+ *
+ * If the target is unreachable at this chroma and hue, `cleared: false` is
+ * returned along with the extreme: the most legible value available rather
+ * than a thrown error. Callers pair this with a chroma reduction, which is
+ * what makes the target reachable for saturated hues — but they must check
+ * `cleared` to know when that retry is required, since a below-AA `l` looks
+ * identical to a solved one otherwise.
+ */
+export function solveL(opts) {
+    const { c, h, against, target, direction } = opts;
+    const extreme = direction === "darker" ? 0 : 1;
+    if (contrastOf(hexFor(extreme, c, h), against) < target) {
+        // Unreachable at this chroma — hand back the best available, flagged.
+        return { l: extreme, cleared: false };
+    }
+    let lo = direction === "darker" ? 0 : 1; // known to clear
+    let hi = direction === "darker" ? 1 : 0; // known to fail (or nearly)
+    let best = extreme;
+    for (let i = 0; i < ITERATIONS; i++) {
+        const mid = (lo + hi) / 2;
+        if (contrastOf(hexFor(mid, c, h), against) >= target) {
+            best = mid;
+            lo = mid;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    return { l: best, cleared: true };
+}

package/dist/generate/types.d.ts

@@ -0,0 +1,24 @@
+import type { BrandFonts } from "../themes/customers/index.js";
+export type ChromaWord = "muted" | "calm" | "balanced" | "vivid" | "electric";
+export type RadiusRung = 4 | 6 | 8 | 12;
+export declare const RADIUS_RUNGS: readonly RadiusRung[];
+export declare const CHROMA_WORDS: readonly ChromaWord[];
+/**
+ * The whole contract between a prompt and a theme (D57). Every producer of one
+ * is untrusted — the model behind /api/theme returns this, never colours, so
+ * nothing can reach a rendered colour without passing through the AA solver.
+ *
+ * `mode` is a presentation hint, not a derivation input: both members of the
+ * pair are always derived, and `mode` only decides which is shown first.
+ */
+export interface BrandVector {
+    hue: number;
+    chroma: ChromaWord;
+    mode: "light" | "dark";
+    radius: RadiusRung;
+    fonts?: BrandFonts;
+    name: string;
+}
+/** Schema check over a closed set. Anything failing this is discarded and the
+ * local derivation stands — see api/theme.ts and the promo boot script. */
+export declare function isBrandVector(value: unknown): value is BrandVector;

package/dist/generate/types.js

@@ -0,0 +1,48 @@
+export const RADIUS_RUNGS = [4, 6, 8, 12];
+export const CHROMA_WORDS = [
+    "muted",
+    "calm",
+    "balanced",
+    "vivid",
+    "electric",
+];
+const FONT_ROLES = ["sans", "serif", "mono", "display"];
+function isFonts(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return Object.entries(value).every(([k, v]) => FONT_ROLES.includes(k) && typeof v === "string");
+}
+/** Schema check over a closed set. Anything failing this is discarded and the
+ * local derivation stands — see api/theme.ts and the promo boot script. */
+export function isBrandVector(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (typeof v.hue !== "number" || !Number.isFinite(v.hue))
+        return false;
+    if (v.hue < 0 || v.hue >= 360)
+        return false;
+    if (!CHROMA_WORDS.includes(v.chroma))
+        return false;
+    if (v.mode !== "light" && v.mode !== "dark")
+        return false;
+    if (!RADIUS_RUNGS.includes(v.radius))
+        return false;
+    // The length bound is not cosmetic: `name` becomes a filename and a
+    // TypeScript identifier, and this guard is the only thing between an
+    // untrusted producer and both. parsePrompt's own slugify caps at 48.
+    if (typeof v.name !== "string" || v.name.length > 64)
+        return false;
+    // Single interior hyphens only — no consecutive, no trailing. The looser
+    // `^[a-z][a-z0-9-]*$` admitted `a--b` and `ab-`, which `serialize.ts`'s
+    // `ident()` turned into `a-B` and `ab-`: literal hyphens inside a TypeScript
+    // identifier, i.e. an emitted `customers/<name>.ts` that does not parse.
+    // parsePrompt's slugify already collapses runs and strips trailing hyphens,
+    // so nothing it produces is affected — this closes the untrusted path (the
+    // model-supplied name in api/theme.ts, and stored brands).
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(v.name))
+        return false;
+    if (v.fonts !== undefined && !isFonts(v.fonts))
+        return false;
+    return true;
+}

package/dist/themes/customers/acme.d.ts

@@ -0,0 +1,8 @@
+import type { Palette, SlotMap, ThemeDef } from "../../dsl/types.js";
+export declare const acmePalette: Palette;
+export declare const acmeSlots: SlotMap;
+/** D39: acme's status hues (160/85/15) have lower in-gamut chroma maxima at
+ * l 0.48 than light.ts's default caps, so the fg formulas carry acme's own
+ * clamp targets. Values are the rendered chromas from dist/resolved/acme.json
+ * — hex output is unchanged. */
+export declare const acmeOverrides: ThemeDef;

package/dist/themes/customers/acme.js

@@ -0,0 +1,31 @@
+import { token, set, cap, slot } from "../../dsl/builders.js";
+export const acmePalette = {
+    charcoal: { l: 0.22, c: 0.015, h: 30 },
+    cream: { l: 0.96, c: 0.01, h: 80 },
+    coral: { l: 0.55, c: 0.2, h: 30 },
+    // D39: c retuned to the anchor's own in-gamut max at l 0.52 (was 0.15, out
+    // of sRGB gamut) — fillSuccess reads this anchor unmodified and was already
+    // clamping to exactly this value.
+    mint: { l: 0.52, c: 0.1176, h: 160 },
+    gold: { l: 0.78, c: 0.15, h: 85 },
+    crimson: { l: 0.55, c: 0.22, h: 15 },
+    white: { l: 1.0, c: 0, h: 0 },
+    black: { l: 0.0, c: 0, h: 0 },
+};
+export const acmeSlots = {
+    ink: "charcoal",
+    canvas: "cream",
+    accent: "coral",
+    success: "mint",
+    warning: "gold",
+    danger: "crimson",
+};
+/** D39: acme's status hues (160/85/15) have lower in-gamut chroma maxima at
+ * l 0.48 than light.ts's default caps, so the fg formulas carry acme's own
+ * clamp targets. Values are the rendered chromas from dist/resolved/acme.json
+ * — hex output is unchanged. */
+export const acmeOverrides = {
+    fgSuccess: token({ from: slot.success, l: set(0.48), c: cap(0.1086) }),
+    fgWarning: token({ from: slot.warning, l: set(0.48), c: cap(0.0984) }),
+    fgDanger: token({ from: slot.danger, l: set(0.48), c: cap(0.1919) }),
+};

package/dist/themes/customers/ember.d.ts

@@ -0,0 +1,13 @@
+import type { Palette, SlotMap, ThemeDef } from "../../dsl/types.js";
+import type { BrandFonts } from "./index.js";
+/** Dark-first brand (D27) — the portfolio's ember-field identity.
+ * Anchors are culori-derived from the shipped portfolio hexes. */
+export declare const emberPalette: Palette;
+export declare const emberSlots: SlotMap;
+/** Brand-level font stacks (D29): Archivo for display/sans, IBM Plex for
+ * serif/mono. The DS ships no font files — the portfolio site loads these
+ * webfonts itself. */
+export declare const emberFonts: BrandFonts;
+/** D34 component-token overrides — emitted at [data-psi-theme="ember"] in psi.components. */
+export declare const emberComponentOverrides: Record<string, string>;
+export declare const emberOverrides: ThemeDef;