@caelo-cms/shared 0.10.22 → 0.10.23

package/src/theme-importers/tailwind.ts

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * v0.11.1 (issue #76) — Tailwind 4 `@theme { … }` block importer.
+ *
+ * Tailwind 4 defines theme tokens in a `@theme` (or `@theme inline`) at-rule:
+ *
+ *   @theme {
+ *     --color-primary: #ff6600;
+ *     --spacing-md: 1rem;
+ *     --font-sans: Inter, system-ui;
+ *   }
+ *
+ * The importer extracts each `--<namespace>-<rest>: <value>;` line from
+ * the brace pair and maps it onto a DTCG path via the inverse of
+ * `theme-render.ts`'s namespace table (`color.<rest>`, `spacing.<rest>`,
+ * etc.). The result is validated by `validateThemeTokens`.
+ *
+ * Deliberately forgiving — handles `@theme inline`, single-line / block
+ * comments, blank lines. Hard-fails (TailwindImportError) on calc() /
+ * nested at-rules so the operator gets a concrete fix-it message
+ * instead of silently-truncated output.
+ */
+
+import { isUnsafeKey } from "../safe-keys.js";
+import { type ThemeDocument, validateThemeTokens } from "../themes.js";
+import { NotTailwindShape, TailwindImportError } from "../themes-errors.js";
+import { stripCssComments } from "./css-comments.js";
+
+interface CssVarEntry {
+  readonly name: string;
+  readonly value: string;
+}
+
+export function importTailwind(body: string): ThemeDocument {
+  const block = extractAtThemeBlock(body);
+  if (block === null) {
+    throw new NotTailwindShape();
+  }
+  const entries = parseCssVarBlock(block);
+  if (entries.length === 0) {
+    throw new NotTailwindShape("@theme block found but no `--name: value;` pairs inside");
+  }
+  const doc = mapEntriesToDtcg(entries);
+  return validateThemeTokens(doc);
+}
+
+/**
+ * Locate the body of the first `@theme` (or `@theme inline`) at-rule.
+ * Returns the contents inside the matching `{ … }` (no braces, no
+ * outer whitespace) or null when no block is present.
+ */
+function extractAtThemeBlock(body: string): string | null {
+  const stripped = stripCssComments(body);
+  const match = /@theme\s+(?:inline\s+)?\{/i.exec(stripped);
+  if (!match) return null;
+  const start = match.index + match[0].length;
+  let depth = 1;
+  let i = start;
+  while (i < stripped.length && depth > 0) {
+    const ch = stripped[i];
+    if (ch === "{") depth += 1;
+    else if (ch === "}") depth -= 1;
+    if (depth === 0) break;
+    i += 1;
+  }
+  if (depth !== 0) return null;
+  return stripped.slice(start, i);
+}
+
+function parseCssVarBlock(block: string): CssVarEntry[] {
+  const entries: CssVarEntry[] = [];
+  // Split on `;` so each entry is one declaration. Skip empty
+  // fragments and any line that doesn't start with `--`.
+  for (const raw of block.split(";")) {
+    const line = raw.trim();
+    if (line.length === 0) continue;
+    if (line.startsWith("//")) continue;
+    if (!line.startsWith("--")) {
+      // Catch nested at-rules; the importer doesn't handle them.
+      if (line.startsWith("@")) {
+        throw new TailwindImportError("nested @-rule", line);
+      }
+      // Tolerate plain identifiers (`color-scheme: dark` etc.) — skip silently.
+      continue;
+    }
+    const colonIdx = line.indexOf(":");
+    if (colonIdx <= 0) continue;
+    const name = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    if (value.length === 0) continue;
+    if (/\bcalc\s*\(/i.test(value)) {
+      throw new TailwindImportError("calc()", line);
+    }
+    if (/\bvar\s*\(/i.test(value)) {
+      throw new TailwindImportError("var()", line);
+    }
+    entries.push({ name, value });
+  }
+  return entries;
+}
+
+/**
+ * Map each `--<namespace>-<rest>` entry to a DTCG group. The namespace
+ * table mirrors theme-render.ts's emit table inverted.
+ */
+function mapEntriesToDtcg(entries: readonly CssVarEntry[]): ThemeDocument {
+  const out: Record<string, Record<string, unknown>> = {};
+  for (const entry of entries) {
+    // Strip the leading `--` and split on the first hyphen.
+    const stripped = entry.name.slice(2);
+    const firstHyphen = stripped.indexOf("-");
+    if (firstHyphen <= 0) continue; // no category prefix → skip
+    const ns = stripped.slice(0, firstHyphen);
+    const rest = stripped.slice(firstHyphen + 1);
+
+    let category: string;
+    let leafName: string;
+    let extraSubField: string | null = null;
+    switch (ns) {
+      case "color":
+        category = "color";
+        leafName = rest;
+        break;
+      case "spacing":
+        category = "spacing";
+        leafName = rest;
+        break;
+      case "radius":
+        category = "radius";
+        leafName = rest;
+        break;
+      case "shadow":
+        category = "shadow";
+        leafName = rest;
+        break;
+      case "breakpoint":
+        category = "breakpoint";
+        leafName = rest;
+        break;
+      case "duration":
+        category = "duration";
+        leafName = rest;
+        break;
+      case "ease":
+        category = "ease";
+        leafName = rest;
+        break;
+      case "font":
+        // --font-sans → typography.sans.fontFamily
+        category = "typography";
+        leafName = rest;
+        extraSubField = "fontFamily";
+        break;
+      case "text":
+        // --text-base → typography.base.fontSize
+        category = "typography";
+        leafName = rest;
+        extraSubField = "fontSize";
+        break;
+      default:
+        // Unknown namespace — bucket under its own root so the renderer
+        // still emits the var (forward-compat).
+        category = ns;
+        leafName = rest;
+    }
+
+    // `category` and `leafName` are derived from the imported CSS variable
+    // name, so a hostile token like `--__proto__-x` could otherwise pollute
+    // the prototype chain via `out[category]` / `group[leafName]` (CodeQL
+    // js/prototype-polluting-assignment). Skip the entry on any unsafe key.
+    if (isUnsafeKey(category) || isUnsafeKey(leafName)) continue;
+
+    if (!out[category]) out[category] = {};
+    const group = out[category] ?? {};
+    if (extraSubField !== null) {
+      // Typography composite: merge into the existing leaf's $value.
+      const existing = group[leafName];
+      const baseObj =
+        existing && typeof existing === "object" && "$value" in existing
+          ? ((existing as { $value: unknown }).$value as Record<string, unknown>)
+          : {};
+      group[leafName] = {
+        $value: { ...baseObj, [extraSubField]: entry.value },
+        $type: "typography",
+      };
+    } else {
+      // v0.11.1 (issue #76 Copilot review #4): if `leafName` looks like
+      // a Tailwind ramp suffix (`primary-50` … `primary-900`,
+      // `primary-DEFAULT`), nest it as `<group>.<stop>` so the result
+      // matches the OKLCh ramp's DTCG group shape. Without this,
+      // `--color-primary-50` would land at the flat key `color['primary-50']`
+      // and downstream ramp-aware logic (DEFAULT-alias resolver, the
+      // ColorEditor's color.primary swatch, the propose-create explicit-
+      // stop override path) wouldn't see the stops as a group.
+      const rampMatch = /^(.+)-(50|100|200|300|400|500|600|700|800|900|DEFAULT)$/.exec(leafName);
+      const tokenLeaf = {
+        $value: entry.value,
+        $type: category === "color" ? "color" : category === "duration" ? "duration" : "dimension",
+      };
+      if (rampMatch && category === "color") {
+        const [, baseName, stop] = rampMatch as unknown as [string, string, string];
+        // `baseName` is the ramp prefix parsed from the token name; guard it
+        // before it becomes a `group[baseName]` assignment target. `stop` is
+        // a fixed enum (50…900|DEFAULT), so it needs no guard.
+        if (isUnsafeKey(baseName)) continue;
+        if (!group[baseName] || typeof group[baseName] !== "object") {
+          group[baseName] = {};
+        }
+        (group[baseName] as Record<string, unknown>)[stop] = tokenLeaf;
+      } else {
+        group[leafName] = tokenLeaf;
+      }
+    }
+  }
+  return out as ThemeDocument;
+}

package/src/theme-literal-binding.test.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #164 slice 2 — mechanical token binding: value-map parsing from
+ * renderer output (aliases + ramps included by construction), color +
+ * whole-gradient rewrites, stop-color protection inside unmatched
+ * gradients, dimension suggestions (never auto-rewritten), reporting.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  applyThemeLiteralBinding,
+  buildThemeValueMap,
+  formatBindingReport,
+} from "./theme-literal-binding.js";
+import type { ThemeDocument } from "./themes.js";
+
+const TOKENS = {
+  color: {
+    primary: { $type: "color", $value: "#4F46E5" },
+    foreground: { $type: "color", $value: "#0f172a" },
+    accent: { $type: "color", $value: "{color.primary}" },
+  },
+  gradient: {
+    hero: { $type: "gradient", $value: "linear-gradient(135deg, #4f46e5, #7c3aed)" },
+  },
+  spacing: { xl: { $type: "dimension", $value: "6rem" } },
+} as unknown as ThemeDocument;
+
+describe("buildThemeValueMap", () => {
+  it("maps normalized renderer-emitted values to var names (aliases resolved)", () => {
+    const map = buildThemeValueMap(TOKENS);
+    expect(map.colors.get("#4f46e5")).toBe("--color-primary"); // first-declared wins over alias
+    expect(map.colors.get("#0f172a")).toBe("--color-foreground");
+    expect(map.gradients.get("linear-gradient(135deg, #4f46e5, #7c3aed)")).toBe("--gradient-hero");
+    expect(map.dimensions.get("6rem")).toBe("--spacing-xl");
+  });
+});
+
+describe("applyThemeLiteralBinding", () => {
+  it("binds whole gradients before stop colors, and matching colors elsewhere", () => {
+    const css =
+      ".hero{background:linear-gradient(135deg, #4F46E5, #7c3aed)}.cta{background:#4f46e5;color:#fff}";
+    const r = applyThemeLiteralBinding(css, TOKENS);
+    expect(r.css).toContain("background:var(--gradient-hero)");
+    expect(r.css).toContain("background:var(--color-primary)");
+    expect(r.css).toContain("color:#fff"); // unknown literal stays
+    expect(r.rewrites.map((x) => x.to).sort()).toEqual(["--color-primary", "--gradient-hero"]);
+  });
+
+  it("leaves stop colors inside UNMATCHED gradients literal (no half-tokenising)", () => {
+    const css = ".x{background:linear-gradient(90deg, #4f46e5, #000000)}";
+    const r = applyThemeLiteralBinding(css, TOKENS);
+    expect(r.css).toBe(css);
+    expect(r.rewrites).toEqual([]);
+  });
+
+  it("suggests dimension tokens without rewriting", () => {
+    const css = ".s{padding:6rem 2rem}";
+    const r = applyThemeLiteralBinding(css, TOKENS);
+    expect(r.css).toBe(css);
+    expect(r.suggestions).toEqual([{ literal: "6rem", varName: "--spacing-xl" }]);
+  });
+
+  it("formats a report and stays silent on no-ops", () => {
+    const bound = applyThemeLiteralBinding(".a{color:#0F172A}", TOKENS);
+    expect(formatBindingReport(bound)).toContain("#0F172A→var(--color-foreground)");
+    const noop = applyThemeLiteralBinding(".a{color:#123456}", TOKENS);
+    expect(formatBindingReport(noop)).toBeNull();
+  });
+});

package/src/theme-literal-binding.ts

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #164 slice 2 — mechanical token binding ("AI decides, code
+ * executes"). During Genesis materialisation the theme is created FROM
+ * the draft's palette, so module CSS copied from the draft contains
+ * literals that EQUAL theme token values. Hand-translating them to
+ * `var(--…)` is transcription work the model can get subtly wrong;
+ * this module does it mechanically:
+ *
+ *   - colors + gradients whose literal value equals an emitted token's
+ *     value are rewritten to `var(--name)` (unambiguous: the value IS
+ *     the token's value);
+ *   - dimension-ish matches (a `6rem` that equals `--spacing-2xl`) are
+ *     reported as SUGGESTIONS only — generic lengths are too ambiguous
+ *     to rewrite silently.
+ *
+ * The value map is parsed from `renderThemeCss` output so binding uses
+ * exactly what the renderer emits (aliases resolved, ramps included) —
+ * no second resolution path to drift.
+ */
+
+import { replaceCssGradients } from "./css-gradient-scan.js";
+import { renderThemeCss } from "./theme-render.js";
+import type { ThemeDocument } from "./themes.js";
+
+const COLOR_LITERAL_RE = /#[0-9a-fA-F]{3,8}\b|(?:oklch|rgba?|hsla?|lab|lch|hwb)\([^()]*\)/g;
+const DIMENSION_VALUE_RE = /^-?\d+(\.\d+)?(rem|em|px|%)$/;
+
+export interface ThemeValueMap {
+  /** normalized color value → var name (first-declared wins). */
+  readonly colors: ReadonlyMap<string, string>;
+  /** exact gradient string (normalized whitespace) → var name. */
+  readonly gradients: ReadonlyMap<string, string>;
+  /** dimension value → var name (suggestion-only tier). */
+  readonly dimensions: ReadonlyMap<string, string>;
+}
+
+function normalizeColor(v: string): string {
+  return v.trim().toLowerCase();
+}
+function normalizeGradient(v: string): string {
+  return v.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+/**
+ * Parse the light-branch declarations the renderer emits for this
+ * document into value → var-name maps.
+ */
+export function buildThemeValueMap(tokens: ThemeDocument): ThemeValueMap {
+  const css = renderThemeCss(tokens);
+  // Only the light branch: `.dark` overrides carry the same names.
+  const lightEnd = css.indexOf(".dark{");
+  const light = lightEnd === -1 ? css : css.slice(0, lightEnd);
+
+  const colors = new Map<string, string>();
+  const gradients = new Map<string, string>();
+  const dimensions = new Map<string, string>();
+  // Regex-free declaration split (a `(--name):(value);` regex is the
+  // #113 polynomial shape on adversarial dash runs). The light block
+  // is `:root{--a:v;--b:v;}` — split on `;`, take name:value pairs.
+  for (const rawSeg of light.split(";")) {
+    const seg = rawSeg.slice(rawSeg.lastIndexOf("{") + 1);
+    const colon = seg.indexOf(":");
+    if (colon <= 0) continue;
+    const name = seg.slice(0, colon).trim();
+    const value = seg.slice(colon + 1).trim();
+    if (!name.startsWith("--") || value.length === 0) continue;
+    if (name.startsWith("--gradient-")) {
+      const key = normalizeGradient(value);
+      if (!gradients.has(key)) gradients.set(key, name);
+    } else if (name.startsWith("--color-")) {
+      const key = normalizeColor(value);
+      if (!colors.has(key)) colors.set(key, name);
+    } else if (DIMENSION_VALUE_RE.test(value)) {
+      if (!dimensions.has(value)) dimensions.set(value, name);
+    }
+  }
+  return { colors, gradients, dimensions };
+}
+
+export interface LiteralBindingResult {
+  readonly css: string;
+  /** Applied rewrites: literal → var name, with occurrence counts. */
+  readonly rewrites: readonly { from: string; to: string; count: number }[];
+  /** Dimension matches left in place (too ambiguous to auto-rewrite). */
+  readonly suggestions: readonly { literal: string; varName: string }[];
+}
+
+/**
+ * Rewrite color/gradient literals that equal theme token values to
+ * `var(--name)`. Longest-first (gradients before their stop colors) so
+ * a gradient binds as a whole instead of stop-by-stop.
+ */
+export function applyThemeLiteralBinding(css: string, tokens: ThemeDocument): LiteralBindingResult {
+  const map = buildThemeValueMap(tokens);
+  const counts = new Map<string, { to: string; count: number }>();
+  let out = css;
+
+  out = replaceCssGradients(out, (literal) => {
+    const varName = map.gradients.get(normalizeGradient(literal));
+    if (varName === undefined) return literal;
+    const entry = counts.get(literal) ?? { to: varName, count: 0 };
+    entry.count += 1;
+    counts.set(literal, entry);
+    return `var(${varName})`;
+  });
+
+  out = out.replace(COLOR_LITERAL_RE, (literal, offset: number) => {
+    // Never rewrite inside an already-produced var(...) fallback or a
+    // remaining gradient (a gradient that did NOT match stays literal
+    // by decision — rebinding its stops would half-tokenise it).
+    const before = out.slice(Math.max(0, offset - 64), offset);
+    if (/gradient\([^()]*$/i.test(before)) return literal;
+    const varName = map.colors.get(normalizeColor(literal));
+    if (varName === undefined) return literal;
+    const entry = counts.get(literal) ?? { to: varName, count: 0 };
+    entry.count += 1;
+    counts.set(literal, entry);
+    return `var(${varName})`;
+  });
+
+  const suggestions: { literal: string; varName: string }[] = [];
+  const seen = new Set<string>();
+  for (const m of out.matchAll(/-?\d+(?:\.\d+)?(?:rem|em|px|%)\b/g)) {
+    const literal = m[0];
+    if (seen.has(literal)) continue;
+    seen.add(literal);
+    const varName = map.dimensions.get(literal);
+    if (varName !== undefined) suggestions.push({ literal, varName });
+  }
+
+  return {
+    css: out,
+    rewrites: [...counts.entries()].map(([from, e]) => ({ from, to: e.to, count: e.count })),
+    suggestions,
+  };
+}
+
+/** Tool-result suffix describing what binding did. Null on no-op. */
+export function formatBindingReport(result: LiteralBindingResult): string | null {
+  const parts: string[] = [];
+  if (result.rewrites.length > 0) {
+    const total = result.rewrites.reduce((n, r) => n + r.count, 0);
+    parts.push(
+      `🔗 bound ${total} literal(s) to theme vars: ${result.rewrites
+        .map((r) => `${r.from}→var(${r.to})${r.count > 1 ? `×${r.count}` : ""}`)
+        .join(", ")}`,
+    );
+  }
+  if (result.suggestions.length > 0) {
+    parts.push(
+      `consider tokens for: ${result.suggestions
+        .map((s) => `${s.literal}≈var(${s.varName})`)
+        .join(", ")} (dimensions are never auto-rewritten)`,
+    );
+  }
+  return parts.length > 0 ? ` ${parts.join(". ")}.` : null;
+}

package/src/theme-motion.test.ts

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * A live build turn failed on `set_theme_tokens` because the `motion`
+ * token accepted only a DTCG duration, a `cubicBezier` [x1,y1,x2,y2]
+ * tuple, or a dimension — NOT the CSS easing forms a model naturally
+ * emits for `motion.easing` (a keyword like `ease-in-out`, or a literal
+ * `cubic-bezier(0.4, 0, 0.2, 1)` string). The rejection message was a
+ * bare "motion token invalid: Invalid input" that told the model
+ * nothing about the accepted shape (CLAUDE.md §11 — AI-actionable
+ * errors). This pins the loosened validation + the actionable message.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { themeDocument } from "./themes.js";
+
+function docWithMotion(name: string, value: unknown): unknown {
+  return {
+    color: { primary: { $type: "color", $value: "#4f46e5" } },
+    motion: { [name]: { $value: value } },
+  };
+}
+
+describe("motion.easing accepts the common CSS easing forms", () => {
+  it("accepts every CSS easing keyword", () => {
+    for (const kw of [
+      "linear",
+      "ease",
+      "ease-in",
+      "ease-out",
+      "ease-in-out",
+      "step-start",
+      "step-end",
+    ]) {
+      const r = themeDocument.safeParse(docWithMotion("easing", kw));
+      expect(r.success).toBe(true);
+    }
+  });
+
+  it("accepts a literal cubic-bezier(...) string", () => {
+    for (const v of ["cubic-bezier(0.4, 0, 0.2, 1)", "cubic-bezier(.25,.1,.25,1)"]) {
+      expect(themeDocument.safeParse(docWithMotion("easing", v)).success).toBe(true);
+    }
+  });
+
+  it("accepts a steps(...) timing function", () => {
+    expect(themeDocument.safeParse(docWithMotion("easing", "steps(4, end)")).success).toBe(true);
+  });
+
+  it("still accepts the DTCG cubicBezier tuple, a duration, and an alias", () => {
+    expect(themeDocument.safeParse(docWithMotion("ease", [0.4, 0, 0.2, 1])).success).toBe(true);
+    expect(themeDocument.safeParse(docWithMotion("fast", "200ms")).success).toBe(true);
+    expect(themeDocument.safeParse(docWithMotion("smooth", "{motion.ease}")).success).toBe(true);
+  });
+});
+
+describe("motion tokens reject junk loudly with an actionable message", () => {
+  it("rejects a number, a boolean, and an empty string", () => {
+    for (const v of [42, true, ""]) {
+      expect(themeDocument.safeParse(docWithMotion("easing", v)).success).toBe(false);
+    }
+  });
+
+  it("rejects a bogus keyword", () => {
+    expect(themeDocument.safeParse(docWithMotion("easing", "wobble")).success).toBe(false);
+  });
+
+  it("the rejection message names the token, the accepted shapes, and the value", () => {
+    const r = themeDocument.safeParse(docWithMotion("easing", 42));
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const msg = r.error.issues[0]!.message;
+    expect(msg).toContain('motion token "easing" invalid');
+    expect(msg).toContain('expected a duration (e.g. "200ms")');
+    expect(msg).toContain("cubic-bezier(...)");
+    expect(msg).toContain("ease-in-out");
+    expect(msg).toContain("got 42");
+    // The old vague text must be gone.
+    expect(msg).not.toContain("Invalid input");
+  });
+});
+
+/**
+ * 2026-07-28 — a model wrote `motion: "180ms ease"`, the CSS transition
+ * shorthand. Listing the accepted forms did not tell it what was actually
+ * wrong (two tokens in one string), so it took three attempts to correct —
+ * and, because gated proposals were validated only AFTER approval, three
+ * operator clicks. The message now names the mistake.
+ */
+describe("a CSS shorthand names the real mistake, not just the legal forms", () => {
+  it("tells the caller to split duration and easing", () => {
+    const r = themeDocument.safeParse(docWithMotion("motion", "180ms ease"));
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const msg = r.error.issues[0]!.message;
+    expect(msg).toContain("CSS transition shorthand");
+    expect(msg).toContain('put "180ms" in a duration token');
+    expect(msg).toContain('"ease" in an easing token');
+  });
+
+  it("covers the seconds form too", () => {
+    const r = themeDocument.safeParse(docWithMotion("motion", "0.2s ease-in-out"));
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    expect(r.error.issues[0]!.message).toContain('put "0.2s" in a duration token');
+  });
+
+  it("stays silent when the value is not a shorthand", () => {
+    // A plain bad value must not get a shorthand lecture it cannot act on.
+    const r = themeDocument.safeParse(docWithMotion("motion", "banana"));
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    expect(r.error.issues[0]!.message).not.toContain("shorthand");
+  });
+});

package/src/theme-normalize-envelope.test.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * issue #242 (F11) — normalizeTokens accepts BOTH the DTCG envelope
+ * (`{$type, $value}`) and the raw `$value` form for composite values,
+ * plus JSON-encoded object strings. Garbage still fails downstream
+ * validation — this layer only repairs encoding, never content.
+ */
+import { describe, expect, it } from "bun:test";
+import { normalizeTokens } from "./theme-normalize.js";
+
+describe("normalizeTokens envelope tolerance (#242)", () => {
+  const typographyValue = { fontFamily: "Inter, sans-serif", fontSize: "1rem", fontWeight: 600 };
+
+  it("accepts the raw composite $value object", () => {
+    const r = normalizeTokens({ "typography.body": typographyValue });
+    expect(r.set["typography.body"]).toEqual(typographyValue);
+  });
+
+  it("unwraps the full DTCG envelope to its $value", () => {
+    const r = normalizeTokens({
+      "typography.body": { $type: "typography", $value: typographyValue },
+    });
+    expect(r.set["typography.body"]).toEqual(typographyValue);
+  });
+
+  it("parses a JSON-encoded composite string, then unwraps", () => {
+    const r = normalizeTokens({
+      "typography.body": JSON.stringify({ $type: "typography", $value: typographyValue }),
+    });
+    expect(r.set["typography.body"]).toEqual(typographyValue);
+  });
+
+  it("keeps plain scalar values untouched", () => {
+    const r = normalizeTokens({ "color.primary": "#7c2d12" });
+    expect(r.set["color.primary"]).toBe("#7c2d12");
+  });
+
+  it("still rejects garbage loudly — encoding repair never validates content", () => {
+    expect(() => normalizeTokens({ "color.primary": "{not json" })).toThrow(
+      /not a recognised CSS color/,
+    );
+  });
+});