@caelo-cms/shared 0.10.21 → 0.10.23

package/src/themes.ts

@@ -0,0 +1,842 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * v0.11.0 — DTCG-aligned Zod schemas for the `themes` primitive (#45).
+ *
+ * Mirrors the W3C Design Tokens Format spec (2025.10 stable). Storage
+ * is a single jsonb document grouped by category (color / typography /
+ * spacing / radius / shadow / motion / breakpoint); each leaf carries a
+ * `$value` (required), optional `$type`, optional `$description`, and
+ * may use DTCG aliasing (`{group.token}`) to reference another token.
+ *
+ * Why DTCG: import/export from Figma / Tokens Studio / Style Dictionary
+ * works out of the box. The admin UI doesn't show raw DTCG to
+ * operators — it renders categorized panels — but the storage layer is
+ * the lingua franca so design tooling round-trips cleanly.
+ *
+ * Caelo extensions over plain DTCG:
+ * - Color tokens may carry `{ light, dark }` instead of a flat `$value`
+ *   so the renderer can emit `:root { … }` + `:root.dark { … }` from
+ *   one declaration.
+ * - The `$extensions` namespace is tolerated (DTCG-spec-compatible)
+ *   for tooling-specific metadata; we never inspect it server-side.
+ */
+
+import { z } from "zod";
+import { isUnsafeKey } from "./safe-keys.js";
+
+// ────────────────────────────────────────────────────────────────────
+// Primitives
+// ────────────────────────────────────────────────────────────────────
+
+/** DTCG alias: `"{group.token}"` references another token by path. */
+const aliasRegex = /^\{[a-zA-Z0-9_.-]+\}$/;
+
+const aliasString = z.string().regex(aliasRegex, "DTCG alias must look like '{group.token}'");
+
+/**
+ * Color value: hex, oklch(...), rgb(...), hsl(...), or a named color.
+ * Loose enough to accept anything a browser would render; strict
+ * rejection lives at the loose-name normalizer where the AI can
+ * recover with a structured error.
+ */
+const colorValueString = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(
+    /^(#[0-9a-fA-F]{3,8}|(oklch|rgb|rgba|hsl|hsla|lab|lch|color|hwb)\(.+\)|transparent|currentColor|[a-zA-Z]+)$/,
+    "color value must be #hex, oklch(...), rgb(...), or a CSS named color",
+  );
+
+/** Dimension: a CSS length / percentage / numeric value. */
+const dimensionValueString = z
+  .string()
+  .min(1)
+  .max(80)
+  .regex(
+    /^-?\d+(\.\d+)?(rem|em|px|%|vh|vw|vmin|vmax|pt|pc|ch|ex|fr|deg|rad|turn|s|ms)?$|^auto$|^0$/,
+    "dimension must be a CSS length / number / percentage",
+  );
+
+/** Font-weight: keyword or 1-1000 number. */
+const fontWeightValue = z.union([
+  z.number().int().min(1).max(1000),
+  z.enum(["normal", "bold", "lighter", "bolder"]),
+]);
+
+const optionalDescription = z.string().max(500).optional();
+
+// ────────────────────────────────────────────────────────────────────
+// Per-type token shapes
+// ────────────────────────────────────────────────────────────────────
+
+const flatOrAliasColor = z.union([colorValueString, aliasString]);
+const flatOrAliasDimension = z.union([dimensionValueString, aliasString]);
+
+/**
+ * Color token. Either a flat `$value` or a `{light, dark}` pair where
+ * the renderer emits the light value in `:root { … }` and the dark
+ * value in `:root.dark { … }`.
+ */
+export const themeColorToken = z
+  .object({
+    $value: z.union([
+      flatOrAliasColor,
+      z
+        .object({
+          light: flatOrAliasColor,
+          dark: flatOrAliasColor,
+        })
+        .strict(),
+    ]),
+    $type: z.literal("color").optional(),
+    $description: optionalDescription,
+    $extensions: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+export const themeDimensionToken = z
+  .object({
+    $value: flatOrAliasDimension,
+    $type: z.literal("dimension").optional(),
+    $description: optionalDescription,
+    $extensions: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+/**
+ * Typography composite. Each sub-field is independently optional so a
+ * document can ship a heading family without forcing a size, and vice
+ * versa. The renderer emits one CSS variable per declared sub-field
+ * (`--font-<name>`, `--text-<name>`, `--font-weight-<name>`, ...).
+ */
+export const themeTypographyComposite = z
+  .object({
+    $value: z.union([
+      z
+        .object({
+          fontFamily: z.string().min(1).max(200).optional(),
+          fontSize: dimensionValueString.optional(),
+          fontWeight: fontWeightValue.optional(),
+          lineHeight: z.union([z.number().positive(), dimensionValueString]).optional(),
+          letterSpacing: dimensionValueString.optional(),
+        })
+        .strict(),
+      aliasString,
+    ]),
+    $type: z.literal("typography").optional(),
+    $description: optionalDescription,
+    $extensions: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+/** Shadow composite (single or layered). */
+const shadowValueObject = z
+  .object({
+    color: flatOrAliasColor,
+    offsetX: dimensionValueString,
+    offsetY: dimensionValueString,
+    blur: dimensionValueString,
+    spread: dimensionValueString.optional(),
+    inset: z.boolean().optional(),
+  })
+  .strict()
+  .refine(
+    (v) => {
+      // Reject negative blur — physically meaningless, signals AI confusion.
+      const m = /^-?(\d+(\.\d+)?)/.exec(v.blur);
+      return !m || Number(m[0]) >= 0;
+    },
+    { message: "shadow blur must be ≥ 0", path: ["blur"] },
+  );
+
+/**
+ * Literal CSS `box-shadow` string — the form a model naturally emits
+ * ("0 4px 6px -1px rgba(0,0,0,0.1)", "none", comma-separated layers). The
+ * DTCG object form (`shadowValueObject`) is the canonical shape; this is the
+ * tolerant fallback so a correct CSS shadow isn't rejected as "must be a
+ * DTCG alias" (the same tolerance `gradientValueString` gives gradients).
+ * Char-class only (no nested quantifiers) → ReDoS-safe; the renderer emits
+ * the string verbatim.
+ */
+const shadowValueString = z
+  .string()
+  .min(3)
+  .max(600)
+  .regex(
+    /^(none|[\w\s.,%#()/-]+)$/i,
+    "shadow must be a CSS box-shadow value, the DTCG object form, or an alias",
+  );
+
+export const themeShadowComposite = z
+  .object({
+    $value: z.union([
+      shadowValueObject,
+      z.array(shadowValueObject).min(1),
+      aliasString,
+      shadowValueString,
+    ]),
+    $type: z.literal("shadow").optional(),
+    $description: optionalDescription,
+    $extensions: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+export const themeDurationToken = z
+  .object({
+    $value: z.union([
+      z.string().regex(/^\d+(\.\d+)?(ms|s)$/, "duration must end in ms or s"),
+      aliasString,
+    ]),
+    $type: z.literal("duration").optional(),
+    $description: optionalDescription,
+    $extensions: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+export const themeCubicBezierToken = z
+  .object({
+    $value: z.union([
+      z
+        .tuple([z.number().min(0).max(1), z.number(), z.number().min(0).max(1), z.number()])
+        .describe("[x1, y1, x2, y2]"),
+      aliasString,
+    ]),
+    $type: z.literal("cubicBezier").optional(),
+    $description: optionalDescription,
+    $extensions: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+/** The seven CSS `<easing-function>` keywords, in `transition-timing-function` grammar. */
+const EASING_KEYWORDS = [
+  "linear",
+  "ease",
+  "ease-in",
+  "ease-out",
+  "ease-in-out",
+  "step-start",
+  "step-end",
+] as const;
+
+/**
+ * Easing value as a literal CSS string — the form a model naturally
+ * reaches for on `motion.easing`: a timing keyword (`ease-in-out`) or a
+ * literal `cubic-bezier(a, b, c, d)` / `steps(...)`. The DTCG
+ * `cubicBezier` *tuple* (`themeCubicBezierToken`) is the canonical
+ * structured shape; this is the tolerant fallback so a correct CSS
+ * easing isn't rejected as "Invalid input" (the same tolerance
+ * `shadowValueString` gives shadows and `gradientValueString` gradients).
+ *
+ * ReDoS-safe: the function-call forms use a bounded char class with no
+ * nested quantifiers, and exclude `;<>{}` so a value can never break out
+ * of the emitted declaration. The renderer emits the string verbatim.
+ */
+// Longest-first so the alternation prefers `ease-in-out` over `ease`.
+const EASING_KEYWORD_ALT = [...EASING_KEYWORDS].sort((a, b) => b.length - a.length).join("|");
+const easingValueString = z
+  .string()
+  .min(1)
+  .max(80)
+  .regex(
+    new RegExp(
+      `^(?:${EASING_KEYWORD_ALT}|cubic-bezier\\([\\d\\s.,+-]+\\)|steps\\([\\w\\s.,+-]+\\))$`,
+      "i",
+    ),
+    `easing must be a keyword (${EASING_KEYWORDS.join("|")}) or a cubic-bezier(...) / steps(...) value`,
+  );
+
+/**
+ * Easing token for `motion.easing`. Accepts, in order of how models
+ * emit them: a CSS easing keyword / `cubic-bezier(...)` string, the DTCG
+ * `cubicBezier` `[x1,y1,x2,y2]` tuple, or a DTCG alias. `$type` may be
+ * omitted, `cubicBezier` (DTCG), or `easing` (Caelo shorthand).
+ */
+export const themeEasingToken = z
+  .object({
+    $value: z.union([
+      easingValueString,
+      z
+        .tuple([z.number().min(0).max(1), z.number(), z.number().min(0).max(1), z.number()])
+        .describe("[x1, y1, x2, y2]"),
+      aliasString,
+    ]),
+    $type: z.union([z.literal("cubicBezier"), z.literal("easing")]).optional(),
+    $description: optionalDescription,
+    $extensions: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+/**
+ * issue #153 — first-class gradient token. Pragmatic CSS-string form
+ * (`linear-gradient(135deg, #4f46e5, #7c3aed)`) rather than DTCG's
+ * structured-stops draft: the renderer emits values verbatim into
+ * `--gradient-<name>` and module CSS consumes them via `var()`, so the
+ * CSS string IS the useful representation. The value regex uses an
+ * unambiguous char class (ReDoS-aware per issue #113) and excludes
+ * `;<>{}` so a token can never break out of the emitted declaration;
+ * `sanitizeCssTokenValue` still runs at render as defense-in-depth.
+ */
+const gradientValueString = z
+  .string()
+  .min(12)
+  .max(600)
+  .regex(
+    /^(?:repeating-)?(?:linear|radial|conic)-gradient\([^;<>{}]*\)$/i,
+    "gradient must be a CSS *-gradient(...) value (no url(), no declarations)",
+  )
+  .refine((v) => !/url\s*\(/i.test(v), "gradient must not contain url()");
+
+export const themeGradientToken = z
+  .object({
+    $value: z.union([gradientValueString, aliasString]),
+    $type: z.literal("gradient").optional(),
+    $description: optionalDescription,
+    $extensions: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+/**
+ * Any token, in any category. The discriminator is the parent group
+ * key (`color.*` → color, `spacing.*` → dimension, ...), but DTCG
+ * doesn't strictly require `$type` so we accept any leaf carrying a
+ * valid `$value`. Per-category strictness is enforced at the
+ * normalizer + the renderer (which know which namespace the token
+ * is being emitted into).
+ */
+const anyThemeToken = z.union([
+  themeColorToken,
+  themeDimensionToken,
+  themeTypographyComposite,
+  themeShadowComposite,
+  themeDurationToken,
+  themeCubicBezierToken,
+  themeEasingToken,
+  themeGradientToken,
+]);
+
+// ────────────────────────────────────────────────────────────────────
+// Document shape
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * One category group: a flat record of token-name → (token | sub-group
+ * | `$`-prefixed metadata). DTCG allows arbitrary nesting; the
+ * structural constraints (every non-`$` key must validate as a token
+ * or nested group; `$description` must be a string) are enforced by
+ * the `superRefine` walker at runtime — the TS type stays a permissive
+ * `Record<string, unknown>` to match Zod's inferred type.
+ *
+ * Per DTCG spec, any group (including the document root) MAY carry
+ * `$description` / `$extensions` metadata alongside its real children.
+ * AI-composed documents do this at the root, and Figma / Tokens
+ * Studio / Style Dictionary exports do it at every level.
+ */
+type TokenGroup = Record<string, unknown>;
+
+const tokenGroupSchema: z.ZodType<TokenGroup> = z.lazy(() =>
+  z.record(z.string(), z.unknown()).superRefine((obj, ctx) => {
+    for (const [k, v] of Object.entries(obj)) {
+      if (k.startsWith("$")) {
+        // DTCG group-level metadata. $description must be a string;
+        // every other $-prefixed key is tooling extension data and
+        // passes through unmodified (the spec leaves these open).
+        if (k === "$description" && typeof v !== "string") {
+          ctx.addIssue({
+            code: "custom",
+            path: [k],
+            message: "$description must be a string",
+          });
+        }
+        continue;
+      }
+      const sub = z.union([anyThemeToken, tokenGroupSchema]).safeParse(v);
+      if (!sub.success) {
+        for (const issue of sub.error.issues) {
+          ctx.addIssue({
+            code: "custom",
+            path: [k, ...issue.path],
+            message: issue.message,
+          });
+        }
+      }
+    }
+  }),
+);
+
+/**
+ * issue #153 — per-category leaf enforcement for the KNOWN vocabulary.
+ *
+ * The recursive group walker deliberately tolerates unknown shapes
+ * (DTCG leaves the category vocabulary open), but that tolerance had a
+ * hole: a leaf whose `$value` failed every token schema fell back to
+ * validating as a "group" whose `$`-keys pass through — so an invalid
+ * `color.primary` (or a `url()`-smuggling `gradient.hero`) passed the
+ * document boundary silently and STILL got emitted into CSS by the
+ * renderer. That is the exact silent-acceptance CLAUDE.md §2 forbids.
+ *
+ * Fix: inside the known categories, any object carrying `$value` IS a
+ * token and must match that category's schema. Unknown root categories
+ * keep the open-vocabulary tolerance (Figma / Tokens Studio imports).
+ */
+const CATEGORY_TOKEN_SCHEMAS: Record<string, z.ZodTypeAny> = {
+  color: themeColorToken,
+  gradient: themeGradientToken,
+  spacing: themeDimensionToken,
+  radius: themeDimensionToken,
+  breakpoint: themeDimensionToken,
+  typography: themeTypographyComposite,
+  shadow: themeShadowComposite,
+  // motion mixes duration + easing leaves (duration.fast, ease.smooth,
+  // easing.standard nested under motion or flat); accept either shape.
+  // themeEasingToken covers the CSS-string easings (`ease-in-out`,
+  // `cubic-bezier(...)`) a model naturally emits; themeCubicBezierToken
+  // covers the DTCG tuple; themeDurationToken/themeDimensionToken the
+  // timing leaves.
+  motion: z.union([
+    themeDurationToken,
+    themeCubicBezierToken,
+    themeEasingToken,
+    themeDimensionToken,
+  ]),
+  duration: themeDurationToken,
+  ease: z.union([themeCubicBezierToken, themeEasingToken]),
+};
+
+/**
+ * Per-category "what shape is accepted" clause, spliced into the
+ * rejection message so the AI can self-correct in one step (CLAUDE.md
+ * §11 — AI-actionable errors) instead of seeing a bare "Invalid input".
+ * Categories absent here fall back to the raw Zod issue message.
+ */
+const CATEGORY_EXPECTATIONS: Record<string, string> = {
+  motion:
+    'a duration (e.g. "200ms"), a cubic-bezier(...) or easing keyword ' +
+    "(linear|ease|ease-in|ease-out|ease-in-out|step-start|step-end), or a dimension token",
+  ease: 'a cubic-bezier(...) string, an easing keyword (linear|ease|ease-in|ease-out|ease-in-out|step-start|step-end), a DTCG [x1,y1,x2,y2] tuple, or an alias like "{motion.ease}"',
+  duration: 'a duration string ending in ms or s (e.g. "200ms", "0.5s") or an alias',
+};
+
+/** Compact, human-readable render of a rejected `$value` for the error tail. */
+function describeValue(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === undefined) return "undefined";
+  const s = JSON.stringify(value);
+  if (s === undefined) return String(value);
+  return s.length > 80 ? `${s.slice(0, 77)}...` : s;
+}
+
+/**
+ * Name the mistake when a value looks like a CSS shorthand packing several
+ * design tokens into one string. Design tokens are single-valued by
+ * definition, so `"180ms ease"` is not a malformed duration — it is a
+ * duration and an easing that belong in separate tokens, and saying so is
+ * what lets the caller fix it on the first try.
+ */
+function shorthandHint(category: string, value: unknown): string {
+  if (typeof value !== "string") return "";
+  const v = value.trim();
+  if (category === "duration" || category === "motion") {
+    // A duration followed by anything else: "180ms ease", "0.2s ease-in-out".
+    if (/^\d*\.?\d+\s*(ms|s)\s+\S/i.test(v)) {
+      return (
+        ` — that looks like a CSS transition shorthand (duration + easing) in ONE token. ` +
+        `Design tokens hold a single value: put "${v.split(/\s+/)[0]}" in a duration token ` +
+        `and "${v.split(/\s+/).slice(1).join(" ")}" in an easing token.`
+      );
+    }
+  }
+  return "";
+}
+
+function refineKnownCategoryLeaves(
+  category: string,
+  schema: z.ZodTypeAny,
+  node: unknown,
+  path: (string | number)[],
+  ctx: z.RefinementCtx,
+): void {
+  if (node === null || typeof node !== "object" || Array.isArray(node)) return;
+  const obj = node as Record<string, unknown>;
+  if ("$value" in obj) {
+    const sub = schema.safeParse(obj);
+    if (!sub.success) {
+      const name = path[path.length - 1];
+      const expectation = CATEGORY_EXPECTATIONS[category];
+      if (expectation) {
+        // Union-based categories surface a single, actionable message
+        // (naming the token, the accepted shapes, and the offending
+        // value) instead of one "Invalid input" issue per union member.
+        //
+        // 2026-07-28: listing accepted shapes was not enough. A model wrote
+        // `motion` as the CSS shorthand `"180ms ease"` — idiomatic in a
+        // `transition:` declaration, but two design tokens in one string. The
+        // message enumerated the legal forms without naming the actual
+        // mistake, so the fix took three attempts (and, because gated
+        // proposals were validated only after approval, three operator
+        // clicks). Naming the likely mistake turns that into one attempt.
+        ctx.addIssue({
+          code: "custom",
+          path: [...path],
+          message:
+            `${category} token "${String(name)}" invalid: expected ${expectation}; got ${describeValue(obj.$value)}` +
+            shorthandHint(category, obj.$value),
+        });
+      } else {
+        for (const issue of sub.error.issues) {
+          ctx.addIssue({
+            code: "custom",
+            path: [...path, ...issue.path],
+            message: `${category} token "${String(name)}" invalid: ${issue.message} (got ${describeValue(obj.$value)})`,
+          });
+        }
+      }
+    }
+    return;
+  }
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.startsWith("$")) continue;
+    refineKnownCategoryLeaves(category, schema, v, [...path, k], ctx);
+  }
+}
+
+/**
+ * Top-level DTCG document. Known category keys:
+ *
+ *   color, typography, spacing, radius, shadow, motion (duration +
+ *   cubicBezier sub-groups), breakpoint, gradient (issue #153 — CSS
+ *   gradient strings emitted as `--gradient-<name>`).
+ *
+ * Unknown root keys are tolerated because DTCG explicitly leaves the
+ * category vocabulary open — we don't want to reject a future
+ * `effect` category that operators bring from Figma.
+ * Root-level `$description` / `$extensions` are also tolerated (DTCG
+ * documents routinely carry these — the seeded default theme and
+ * Figma/Tokens Studio exports all have a root `$description`).
+ */
+export const themeDocument: z.ZodType<TokenGroup> = tokenGroupSchema.superRefine((doc, ctx) => {
+  for (const [category, schema] of Object.entries(CATEGORY_TOKEN_SCHEMAS)) {
+    if (category in doc) {
+      refineKnownCategoryLeaves(category, schema, doc[category], [category], ctx);
+    }
+  }
+});
+
+export type ThemeDocument = z.infer<typeof themeDocument>;
+export type ThemeColorToken = z.infer<typeof themeColorToken>;
+export type ThemeDimensionToken = z.infer<typeof themeDimensionToken>;
+export type ThemeTypographyComposite = z.infer<typeof themeTypographyComposite>;
+export type ThemeShadowComposite = z.infer<typeof themeShadowComposite>;
+export type ThemeGradientToken = z.infer<typeof themeGradientToken>;
+export type ThemeDurationToken = z.infer<typeof themeDurationToken>;
+export type ThemeCubicBezierToken = z.infer<typeof themeCubicBezierToken>;
+export type ThemeEasingToken = z.infer<typeof themeEasingToken>;
+export type AnyThemeToken = z.infer<typeof anyThemeToken>;
+
+/**
+ * Theme aggregate — row + resolved asset URLs. The asset URLs are
+ * derived server-side by joining `media`; the `{mediaId, url}` shape
+ * lets the renderer / system-prompt emit either form without re-loading.
+ */
+export interface ThemeAssetRef {
+  readonly mediaId: string;
+  readonly url: string;
+}
+
+/**
+ * v0.11.4 (issue #76 follow-up) — provenance of the current state.
+ * `seed`: untouched starter palette (e.g. shadcn-default populated by
+ * migration 0099). `ai`: most recent write was by an AI actor. `operator`:
+ * most recent write was by a human actor. The system-prompt `## Theme`
+ * block surfaces this so the AI knows whether it should evolve the
+ * palette for the site being built or treat it as an operator choice.
+ */
+export type ThemeOrigin = "seed" | "ai" | "operator";
+
+export interface Theme {
+  readonly id: string;
+  readonly slug: string;
+  readonly displayName: string;
+  readonly description: string | null;
+  readonly origin: ThemeOrigin;
+  readonly isActive: boolean;
+  readonly tokens: ThemeDocument;
+  readonly assets: {
+    readonly logo: ThemeAssetRef | null;
+    readonly logoDark: ThemeAssetRef | null;
+    readonly favicon: ThemeAssetRef | null;
+    readonly socialShare: ThemeAssetRef | null;
+  };
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+/**
+ * Validate a tokens document. Returns the parsed tree on success;
+ * throws a ZodError on failure (caller wraps into the op's HandlerError
+ * shape per CLAUDE.md §4).
+ */
+export function validateThemeTokens(tokens: unknown): ThemeDocument {
+  return themeDocument.parse(tokens);
+}
+
+/**
+ * v0.11.1 (issue #76) — Zod schema for `propose_create_theme.overrides`.
+ *
+ * The base shape is a permissive `Record<string, unknown>` (same as
+ * v0.11.0) so loose names like `primaryColor` / `fontHeading` /
+ * `spacing-lg` continue to flow through `normalizeTokens`. The explicit
+ * `primaryColor` recognition (v0.11.1) is documented here — when set,
+ * the propose-create handler derives a `color.primary.{50..900}`
+ * OKLCh ramp from the value (each stop `_derived: true`) instead of
+ * landing a single `color.primary` leaf via the normalizer.
+ *
+ * Operator-supplied `color.primary.<stop>` paths in the same overrides
+ * map layer over the derived ramp (explicit-wins precedence).
+ */
+export const createThemeOverridesSchema = z.record(z.string(), z.unknown());
+export type CreateThemeOverrides = z.infer<typeof createThemeOverridesSchema>;
+
+/**
+ * v0.11.1 (issue #76) — extract the `primaryColor` sentinel from a
+ * loose-name overrides map. Returns `{primaryColor, rest}` where `rest`
+ * is the same map minus the `primaryColor` key. Used by the propose-
+ * create handler to split the ramp-seed off before normalizing the
+ * remaining loose names.
+ */
+export function extractPrimaryColorSeed(overrides: Record<string, unknown> | undefined): {
+  primaryColor: string | undefined;
+  rest: Record<string, unknown>;
+} {
+  if (!overrides) return { primaryColor: undefined, rest: {} };
+  const { primaryColor, ...rest } = overrides as { primaryColor?: unknown } & Record<
+    string,
+    unknown
+  >;
+  return {
+    primaryColor: typeof primaryColor === "string" ? primaryColor : undefined,
+    rest,
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Walk a tokens document and produce a flat list of `(path, token)`
+ * pairs. Used by the renderer + alias resolver + summary formatter.
+ * Paths use dot-notation: `color.primary`, `typography.heading`,
+ * `color.brand.primary`, ...
+ */
+export function flattenTokens(
+  tokens: ThemeDocument,
+): Array<{ path: string; token: AnyThemeToken }> {
+  const out: Array<{ path: string; token: AnyThemeToken }> = [];
+  walk(tokens, [], out);
+  return out;
+}
+
+function walk(
+  node: unknown,
+  prefix: readonly string[],
+  out: Array<{ path: string; token: AnyThemeToken }>,
+): void {
+  if (node === null || typeof node !== "object") return;
+  const obj = node as Record<string, unknown>;
+  // Leaf: carries `$value`.
+  if ("$value" in obj) {
+    out.push({ path: prefix.join("."), token: obj as AnyThemeToken });
+    return;
+  }
+  // Group: recurse.
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.startsWith("$")) continue; // tolerate DTCG group-level metadata
+    walk(v, [...prefix, k], out);
+  }
+}
+
+/**
+ * Build a one-line category summary for the system-prompt `## Theme`
+ * block ("8 colors, 5 typography, 6 spacing, 5 radii, 3 shadows").
+ */
+export function summarizeTokens(tokens: ThemeDocument): string {
+  const counts = new Map<string, number>();
+  for (const { path } of flattenTokens(tokens)) {
+    const category = path.split(".")[0] ?? "(uncategorised)";
+    counts.set(category, (counts.get(category) ?? 0) + 1);
+  }
+  if (counts.size === 0) return "no tokens";
+  const parts: string[] = [];
+  // Stable order so cached system prompts hit.
+  for (const k of [
+    "color",
+    "typography",
+    "spacing",
+    "radius",
+    "shadow",
+    "duration",
+    "ease",
+    "breakpoint",
+  ]) {
+    const n = counts.get(k);
+    if (n) parts.push(`${n} ${pluralise(k, n)}`);
+  }
+  for (const [k, n] of counts) {
+    if (
+      ![
+        "color",
+        "typography",
+        "spacing",
+        "radius",
+        "shadow",
+        "duration",
+        "ease",
+        "breakpoint",
+      ].includes(k)
+    ) {
+      parts.push(`${n} ${k}`);
+    }
+  }
+  return parts.join(", ");
+}
+
+function pluralise(category: string, n: number): string {
+  if (n === 1) return category;
+  if (category === "radius") return "radii";
+  if (category.endsWith("y")) return `${category.slice(0, -1)}ies`;
+  return `${category}s`;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Patch helpers (shared between themes.update_tokens + themes.execute_proposal)
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * v0.11.0 (#45, step-11 opt §5) — apply a canonical-path → value patch
+ * to a DTCG document. Returns a fresh document; the input is not
+ * mutated.
+ *
+ * Each entry in `writes` becomes a `{$value, $type}` leaf at the dotted
+ * canonical path. The `types` map carries the inferred DTCG `$type` for
+ * each path (already known to the normalizer) so the leaf advertises
+ * the right shape to consumers.
+ *
+ * Both themes.update_tokens (loose-input set path) and
+ * themes.propose_create's execute branch (tokens + overrides merge)
+ * use this same logic — extracted so the dotted-path merge lives in
+ * one place and v0.11.1's OKLCH auto-ramp can extend it without
+ * forking.
+ */
+export function applyDtcgWrites(
+  current: ThemeDocument,
+  writes: Record<string, unknown>,
+  types: Record<string, string>,
+): ThemeDocument {
+  const out: ThemeDocument = JSON.parse(JSON.stringify(current));
+  for (const [path, value] of Object.entries(writes)) {
+    const inferredType = types[path];
+    // v0.11.0 fix (#45 review thread on theme-normalize.ts:149) — when
+    // the incoming value is a partial composite object (e.g. typography's
+    // `{fontFamily: "Inter"}` from a loose `fontHeading` input), MERGE
+    // it into any existing leaf's `$value` instead of overwriting. This
+    // is the only sensible semantics for typography: setting fontFamily
+    // must not erase fontSize / fontWeight / etc. set previously.
+    const existing = readLeafAtPath(out, path);
+    let nextValue: unknown = value;
+    if (
+      existing &&
+      typeof existing === "object" &&
+      typeof (existing as { $value?: unknown }).$value === "object" &&
+      (existing as { $value: unknown }).$value !== null &&
+      typeof value === "object" &&
+      value !== null &&
+      !Array.isArray(value)
+    ) {
+      nextValue = {
+        ...(existing as { $value: Record<string, unknown> }).$value,
+        ...(value as Record<string, unknown>),
+      };
+    }
+    setLeafAtPath(out, path, {
+      $value: nextValue,
+      ...(inferredType ? { $type: inferredType } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * Read the existing leaf at a dotted DTCG path, returning the node if
+ * it already carries `$value` (i.e. is a token leaf) and `undefined`
+ * otherwise. Used by `applyDtcgWrites` to detect composite leaves
+ * where the new value should MERGE into the existing `$value` instead
+ * of replacing it.
+ */
+function readLeafAtPath(doc: Record<string, unknown>, path: string): unknown {
+  const parts = path.split(".");
+  let cur: unknown = doc;
+  for (const k of parts) {
+    if (!k) return undefined;
+    if (cur === null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string, unknown>)[k];
+  }
+  if (cur && typeof cur === "object" && "$value" in (cur as Record<string, unknown>)) {
+    return cur;
+  }
+  return undefined;
+}
+
+/**
+ * Walk a dotted DTCG path and set the leaf in-place. Caller passes a
+ * cloned document (never the original) — `applyDtcgWrites` enforces
+ * that for the public surface.
+ */
+function setLeafAtPath(doc: Record<string, unknown>, path: string, leaf: unknown): void {
+  const parts = path.split(".");
+  // The dotted path comes from the caller's `writes` map (form / AI input),
+  // so a segment like `__proto__` or `constructor` would let the walk below
+  // (`cur[k] = {}`, `cur[last] = leaf`) pollute the prototype chain (CodeQL
+  // js/prototype-pollution-utility). Reject the whole write on any unsafe
+  // segment rather than partially applying it.
+  if (parts.some(isUnsafeKey)) return;
+  let cur: Record<string, unknown> = doc;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const k = parts[i];
+    if (!k) continue;
+    if (cur[k] === undefined || cur[k] === null || typeof cur[k] !== "object") {
+      cur[k] = {};
+    }
+    cur = cur[k] as Record<string, unknown>;
+  }
+  const last = parts[parts.length - 1];
+  if (last) cur[last] = leaf;
+}
+
+/**
+ * Companion to `applyDtcgWrites` — drop the leaf at a canonical path
+ * if it exists. Returns `{tokens, removed}` so the caller can report
+ * which paths were actually removed (silent on missing paths so a
+ * remove-list that includes already-absent keys is idempotent).
+ */
+export function removeDtcgPath(
+  doc: ThemeDocument,
+  path: string,
+): { tokens: ThemeDocument; removed: boolean } {
+  const out: ThemeDocument = JSON.parse(JSON.stringify(doc));
+  const parts = path.split(".");
+  let cur: Record<string, unknown> = out;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const k = parts[i];
+    if (!k) continue;
+    const next = cur[k];
+    if (!next || typeof next !== "object") return { tokens: doc, removed: false };
+    cur = next as Record<string, unknown>;
+  }
+  const last = parts[parts.length - 1];
+  if (!last) return { tokens: doc, removed: false };
+  if (!(last in cur)) return { tokens: doc, removed: false };
+  delete cur[last];
+  return { tokens: out, removed: true };
+}