@caelo-cms/shared 0.10.22 → 0.10.24

package/dist/themes.js

@@ -0,0 +1,697 @@
+// 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",
+];
+/**
+ * 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,
+]);
+const tokenGroupSchema = 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 = {
+    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 = {
+    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) {
+    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, value) {
+    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, schema, node, path, ctx) {
+    if (node === null || typeof node !== "object" || Array.isArray(node))
+        return;
+    const obj = node;
+    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 = 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);
+        }
+    }
+});
+/**
+ * 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) {
+    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());
+/**
+ * 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) {
+    if (!overrides)
+        return { primaryColor: undefined, rest: {} };
+    const { primaryColor, ...rest } = overrides;
+    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) {
+    const out = [];
+    walk(tokens, [], out);
+    return out;
+}
+function walk(node, prefix, out) {
+    if (node === null || typeof node !== "object")
+        return;
+    const obj = node;
+    // Leaf: carries `$value`.
+    if ("$value" in obj) {
+        out.push({ path: prefix.join("."), token: obj });
+        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) {
+    const counts = new Map();
+    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 = [];
+    // 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, n) {
+    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, writes, types) {
+    const out = 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 = value;
+        if (existing &&
+            typeof existing === "object" &&
+            typeof existing.$value === "object" &&
+            existing.$value !== null &&
+            typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value)) {
+            nextValue = {
+                ...existing.$value,
+                ...value,
+            };
+        }
+        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, path) {
+    const parts = path.split(".");
+    let cur = doc;
+    for (const k of parts) {
+        if (!k)
+            return undefined;
+        if (cur === null || typeof cur !== "object")
+            return undefined;
+        cur = cur[k];
+    }
+    if (cur && typeof cur === "object" && "$value" in cur) {
+        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, path, leaf) {
+    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 = 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];
+    }
+    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, path) {
+    const out = JSON.parse(JSON.stringify(doc));
+    const parts = path.split(".");
+    let cur = 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;
+    }
+    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 };
+}
+//# sourceMappingURL=themes.js.map