@caelo-cms/shared 0.10.23 → 0.10.26

package/src/template-engine-data-lists.test.ts

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Plugin data lists in the template engine: `{{#name}}…{{/name}}` over
+ * data a plugin supplies per page, with the module owning the markup.
+ *
+ * The load-bearing case is the third one. Plugin activation is a hard
+ * state, so a module written while a plugin ran keeps its
+ * `{{#language_links}}` after the plugin is switched off. Rendering
+ * that as an empty string would be a silent fallback (CLAUDE.md §2) and
+ * would read to the operator as "the switcher vanished for no reason".
+ * It has to stay visible AND say which plugin to turn back on.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { renderTemplate } from "./template-engine.js";
+
+const SWITCHER =
+  '<nav>{{#language_links}}<a href="{{href}}">{{label}}</a>{{/language_links}}</nav>';
+
+describe("template engine — plugin data lists", () => {
+  it("iterates a plugin list with the module's own markup", () => {
+    const r = renderTemplate({
+      html: SWITCHER,
+      fields: [],
+      dataLists: {
+        language_links: [
+          { href: "/", label: "English", locale: "en" },
+          { href: "/de", label: "Deutsch", locale: "de" },
+        ],
+      },
+    });
+    expect(r.html).toBe('<nav><a href="/">English</a><a href="/de">Deutsch</a></nav>');
+    expect(r.missingSlots).toEqual([]);
+  });
+
+  it("renders nothing for an empty list — that is data, not breakage", () => {
+    // A page with no published translations legitimately has no links.
+    const r = renderTemplate({
+      html: SWITCHER,
+      fields: [],
+      dataLists: { language_links: [] },
+    });
+    expect(r.html).toBe("<nav></nav>");
+    expect(r.missingSlots).toEqual([]);
+  });
+
+  it("stays loud and names the plugin when its plugin is switched off", () => {
+    const r = renderTemplate({
+      html: SWITCHER,
+      fields: [],
+      dormantDataLists: { language_links: "international-site" },
+    });
+    // Loud-raw: the section survives in the output rather than
+    // silently collapsing.
+    expect(r.html).toContain("{{#language_links}}");
+    expect(r.missingSlots).toContain(
+      "plugin-list-unavailable:language_links plugin=international-site",
+    );
+  });
+
+  it("keeps an unknown name a plain undeclared field", () => {
+    // No plugin claims it — this really is a typo, and must not be
+    // reported as a deactivated plugin.
+    const r = renderTemplate({ html: "<p>{{#nope}}x{{/nope}}</p>", fields: [] });
+    expect(r.missingSlots).toContain("field-not-declared:nope");
+  });
+
+  it("lets a module's own field win over a plugin list of the same name", () => {
+    // Module fields are resolved first by construction, so a plugin can
+    // never shadow content the author declared.
+    const r = renderTemplate({
+      html: "<ul>{{#items}}<li>{{label}}</li>{{/items}}</ul>",
+      fields: [{ name: "items", kind: "link-list" }],
+      contentValues: { items: [{ label: "authored", href: "/a" }] },
+      dataLists: { items: [{ label: "from-plugin" }] },
+    });
+    expect(r.html).toContain("authored");
+    expect(r.html).not.toContain("from-plugin");
+  });
+
+  it("leaves a key the items do not carry raw", () => {
+    const r = renderTemplate({
+      html: "{{#l}}<a href={{href}}>{{missing_key}}</a>{{/l}}",
+      fields: [],
+      dataLists: { l: [{ href: "/x" }] },
+    });
+    expect(r.html).toContain("{{missing_key}}");
+  });
+});

package/src/template-engine.ts

@@ -93,6 +93,24 @@ export interface RenderTemplateInput {
    * Preview-render path: built from RenderResolver walks.
    */
   readonly partials?: Readonly<Record<string, string>>;
+  /**
+   * Plugin-provided lists for THIS page, keyed by the claimed name a
+   * module iterates as `{{#name}}`. The plugin supplies the data, the
+   * module owns the markup — so a language switcher looks like the site
+   * it lives on instead of carrying a plugin's fixed HTML.
+   *
+   * Resolved per page, which is what lets a module carrying one sit in
+   * a LAYOUT and cover every page. The `staticRender` placeholder can't:
+   * it needs the page's own id baked into its HTML.
+   */
+  readonly dataLists?: Readonly<Record<string, ReadonlyArray<Readonly<Record<string, string>>>>>;
+  /**
+   * Names an INSTALLED plugin declares that are not live right now,
+   * mapped to the owning plugin. A module written while the plugin ran
+   * still says `{{#language_links}}`; this is what lets the render
+   * report "that plugin is switched off" instead of "unknown field".
+   */
+  readonly dormantDataLists?: Readonly<Record<string, string>>;
   /**
    * v0.11.1 (issue #76) — active theme's resolved asset URLs. When
    * present, `{{theme_logo_url}}` / `{{theme_logo_dark_url}}` /
@@ -243,7 +261,18 @@ export function renderTemplate(input: RenderTemplateInput): RenderTemplateOutput
 
   // 1. {{#name}}…{{/name}} sections.
   let html = sourceHtml.replace(SECTION_RE, (match, name: string, inner: string) =>
-    renderSection(match, name, inner, fieldByName, cvs, partials, missing, mkSentinel),
+    renderSection(
+      match,
+      name,
+      inner,
+      fieldByName,
+      cvs,
+      partials,
+      missing,
+      mkSentinel,
+      input.dataLists ?? {},
+      input.dormantDataLists ?? {},
+    ),
   );
 
   // 2. {{>name}} single partials.
@@ -333,9 +362,24 @@ function renderSection(
   partials: Readonly<Record<string, string>>,
   missing: string[],
   mkSentinel: (original: string) => string,
+  dataLists: Readonly<Record<string, ReadonlyArray<Readonly<Record<string, string>>>>>,
+  dormantLists: Readonly<Record<string, string>>,
 ): string {
   const field = fields.get(name);
   if (!field) {
+    // No declared field — a plugin may still offer this name. Module
+    // fields are looked up FIRST by construction, so a plugin can never
+    // shadow something the module's author declared.
+    const items = dataLists[name];
+    if (items) return renderDataList(inner, items);
+    // Declared by an installed plugin that is NOT running. Naming the
+    // plugin turns "unknown field" (hunt for a typo) into "switch that
+    // plugin back on", which is the actual fix.
+    const owner = dormantLists[name];
+    if (owner) {
+      missing.push(`plugin-list-unavailable:${name} plugin=${owner}`);
+      return mkSentinel(match);
+    }
     missing.push(`field-not-declared:${name}`);
     return mkSentinel(match);
   }
@@ -425,6 +469,33 @@ function renderTextList(
   return parts.join("");
 }
 
+/**
+ * Iterate a plugin-provided list, substituting each item's keys inside
+ * the section body.
+ *
+ * Unlike `link-list` no shape is imposed: the keys are whatever the
+ * plugin declared in `itemFields`, so a language switcher uses
+ * href/label/locale and a comment list something else entirely. A
+ * `{{key}}` the item does not carry is left raw, matching the engine's
+ * loud-raw rule everywhere else — a typo'd key stays visible instead of
+ * quietly rendering as nothing.
+ */
+function renderDataList(
+  inner: string,
+  items: ReadonlyArray<Readonly<Record<string, string>>>,
+): string {
+  const parts: string[] = [];
+  for (const item of items) {
+    let rendered = inner;
+    for (const [key, value] of Object.entries(item)) {
+      const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      rendered = rendered.replace(new RegExp(`\\{\\{\\s*${escaped}\\s*\\}\\}`, "g"), () => value);
+    }
+    parts.push(rendered);
+  }
+  return parts.join("");
+}
+
 function renderLinkList(
   name: string,
   inner: string,

package/src/theme-importers/loose.ts

@@ -46,7 +46,7 @@ export function importLoose(body: string): ThemeDocument {
   // ambiguity, per the v0.11.0 normalizer's failure surface).
   const normalized = normalizeTokens(obj);
   // Apply to an empty document so the result is a complete tokens tree.
-  const written = applyDtcgWrites({}, normalized.set, normalized.types);
+  const written = applyDtcgWrites({}, normalized.set, normalized.types, normalized.descriptions);
   return validateThemeTokens(written);
 }
 

package/src/theme-normalize.ts

@@ -48,6 +48,15 @@ export interface NormalizeResult {
     CanonicalPath,
     "color" | "dimension" | "typography" | "shadow" | "duration" | "cubicBezier" | "gradient"
   >;
+  /**
+   * issue #430 — the token's ROLE, per canonical path: what this token
+   * is for and, crucially, where it must NOT be used ("CTAs and links
+   * only — never large background fills"). Lifted off the `$description`
+   * of a DTCG envelope the caller passed in `set`, so a value and its
+   * role land in ONE write instead of a value call plus a prose-metadata
+   * call. The ops layer stores it back on the leaf as `$description`.
+   */
+  readonly descriptions: Record<CanonicalPath, string>;
   /** Echo-back list for the AI tool's result content. */
   readonly canonicalPaths: readonly CanonicalPath[];
 }
@@ -218,6 +227,7 @@ const DEFAULT_TIER = "sm"; // shadowSm / radiusMd default
 export function normalizeTokens(input: Record<string, unknown>): NormalizeResult {
   const set: Record<CanonicalPath, unknown> = {};
   const types: Record<CanonicalPath, NormalizeResult["types"][string]> = {};
+  const descriptions: Record<CanonicalPath, string> = {};
   const paths: CanonicalPath[] = [];
 
   for (const [rawName, rawValueIn] of Object.entries(input)) {
@@ -235,13 +245,35 @@ export function normalizeTokens(input: Record<string, unknown>): NormalizeResult
         // Not JSON after all — keep the literal string.
       }
     }
-    if (
-      rawValue !== null &&
-      typeof rawValue === "object" &&
-      !Array.isArray(rawValue) &&
-      "$value" in (rawValue as Record<string, unknown>)
-    ) {
-      rawValue = (rawValue as Record<string, unknown>).$value;
+    // issue #430 — the envelope may also carry `$description` (the token's
+    // role). Lift it BEFORE unwrapping, then re-attach it at the canonical
+    // path so "what this colour is for" survives the same call that sets
+    // the colour. Without this the role is silently dropped on the way in.
+    let envelopeDescription: string | undefined;
+    const isEnvelope =
+      rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue);
+    if (isEnvelope && "$value" in (rawValue as Record<string, unknown>)) {
+      const envelope = rawValue as Record<string, unknown>;
+      if (typeof envelope.$description === "string" && envelope.$description.trim().length > 0) {
+        envelopeDescription = envelope.$description;
+      }
+      rawValue = envelope.$value;
+    } else if (isEnvelope && "$description" in (rawValue as Record<string, unknown>)) {
+      // ROLE-ONLY patch: `{$description}` with no `$value`. The anchor-page
+      // design review annotates tokens whose VALUES are already settled, so
+      // it must be able to write the role without restating (and risking
+      // drift on) every value. Resolve the path without the value — which
+      // only canonical / CSS-var names allow, since loose names infer their
+      // category FROM the value — and record no `set` entry, so
+      // applyDtcgWrites patches the leaf's metadata and leaves `$value` alone.
+      const role = (rawValue as Record<string, unknown>).$description;
+      // A blank role is nothing to write — same tolerance the value-carrying
+      // envelope gives it. The tool reports the resulting no-op.
+      if (typeof role !== "string" || role.trim().length === 0) continue;
+      const path = resolvePathWithoutValue(rawName);
+      descriptions[path] = role.trim();
+      if (!paths.includes(path)) paths.push(path);
+      continue;
     }
     const resolved = resolveOne(rawName, rawValue);
     // v0.11.0 fix (#45 review thread on theme-normalize.ts:149) —
@@ -273,10 +305,11 @@ export function normalizeTokens(input: Record<string, unknown>): NormalizeResult
     }
     set[resolved.path] = storedValue;
     types[resolved.path] = resolved.inferredType;
+    if (envelopeDescription !== undefined) descriptions[resolved.path] = envelopeDescription;
     paths.push(resolved.path);
   }
 
-  return { set, types, canonicalPaths: paths };
+  return { set, types, descriptions, canonicalPaths: paths };
 }
 
 interface ResolvedToken {
@@ -291,6 +324,35 @@ interface ResolvedToken {
   readonly compositeWrap?: string;
 }
 
+/**
+ * issue #430 — resolve a canonical path for a ROLE-ONLY patch, where no
+ * value is supplied to infer the category from.
+ *
+ * Only the two name forms that carry their own category work here:
+ * a canonical DTCG path (`color.primary`) and the CSS-var form
+ * (`--color-primary`) — which is what a caller annotating an existing
+ * theme naturally has, since it just read the document or the module CSS.
+ * A loose name (`primaryColor`) infers its category FROM the value, so
+ * without one it is genuinely unresolvable: say so rather than guess
+ * (CLAUDE.md §2).
+ */
+function resolvePathWithoutValue(rawName: string): CanonicalPath {
+  if (/^[a-z][a-z0-9_-]*(\.[a-z0-9_-]+)+$/i.test(rawName)) return rawName;
+  if (rawName.startsWith("--")) {
+    const stripped = rawName.slice(2);
+    const firstHyphen = stripped.indexOf("-");
+    if (firstHyphen > 0) {
+      const category = stripped.slice(0, firstHyphen);
+      const rest = stripped.slice(firstHyphen + 1);
+      // --font-heading / --text-heading are two emitted vars for ONE
+      // typography composite; a role belongs on the composite.
+      if (category === "font" || category === "text") return `typography.${rest}`;
+      return `${category}.${rest}`;
+    }
+  }
+  throw new UnknownTokenName(rawName, []);
+}
+
 function resolveOne(rawName: string, rawValue: unknown): ResolvedToken {
   // 1. Direct canonical DTCG paths: pass through unchanged. Typography
   //    sub-paths (`typography.X.fontFamily` / `.fontSize` / …) collapse

package/src/theme-render.ts

@@ -139,6 +139,41 @@ export function listThemeCssVarNames(tokens: ThemeDocument): readonly string[] {
   return [...names].sort();
 }
 
+/**
+ * issue #430 — map every emitted CSS variable name to the ROLE recorded
+ * on its token (`$description`): what the token is for and where it must
+ * not be used. Returns `{}` when no token carries a role.
+ *
+ * This is how a design decision reaches the point of use. The write-time
+ * design guard looks up the vars a module's CSS actually references and
+ * replays their roles back at the author, so "primary is for CTAs, never
+ * for large background fills" is enforced on page nine as firmly as on
+ * page one — without a separate design-system document to maintain.
+ *
+ * A composite (typography) emits several vars from one token; each
+ * inherits the same role, which is what a reader expects.
+ */
+export function listTokenRoles(tokens: ThemeDocument): Record<string, string> {
+  const flat = flattenTokens(tokens);
+  const resolveCache = new Map<string, unknown>();
+  const roles: Record<string, string> = {};
+  for (const { path, token } of flat) {
+    const description = (token as { $description?: unknown }).$description;
+    if (typeof description !== "string" || description.trim().length === 0) continue;
+    const category = path.split(".")[0] ?? "";
+    const value = resolveTokenValue(token, tokens, resolveCache, new Set([path]));
+    const lines: string[] = [];
+    emitTokenLines(category, path, value, lines, []);
+    for (const line of lines) {
+      const colon = line.indexOf(":");
+      if (colon <= 0) continue;
+      const name = line.slice(0, colon).trim();
+      if (name.startsWith("--")) roles[name] = description.trim();
+    }
+  }
+  return roles;
+}
+
 /**
  * Emit a Tailwind 4 `@theme inline { … }` block. The body re-uses the
  * same per-category emission as `renderThemeCss` so the variable names
@@ -387,6 +422,7 @@ function emitTypography(rest: string, value: unknown, out: string[]): void {
   const v = value as Record<string, unknown>;
   if (v.fontFamily !== undefined) out.push(`--font-${rest}:${asString(v.fontFamily)};`);
   if (v.fontSize !== undefined) out.push(`--text-${rest}:${asString(v.fontSize)};`);
+  if (v.fontStyle !== undefined) out.push(`--font-style-${rest}:${asString(v.fontStyle)};`);
   if (v.fontWeight !== undefined) out.push(`--font-weight-${rest}:${asString(v.fontWeight)};`);
   if (v.lineHeight !== undefined) out.push(`--leading-${rest}:${asString(v.lineHeight)};`);
   if (v.letterSpacing !== undefined) out.push(`--tracking-${rest}:${asString(v.letterSpacing)};`);

package/src/theme-token-roles.test.ts

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #430 — a token's ROLE is set in the same call as its value and
+ * must survive every later value-only edit.
+ *
+ * Before this, `applyDtcgWrites` rebuilt each leaf as `{$value, $type}`
+ * and silently dropped `$description`, so recording a role was pointless:
+ * the next `set_theme_tokens` erased it. These tests pin the write path
+ * (normalizer lifts the role off the DTCG envelope), the preserve path,
+ * and the lookup the design guard uses to replay roles at the point of
+ * use.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { normalizeTokens } from "./theme-normalize.js";
+import { listTokenRoles } from "./theme-render.js";
+import { applyDtcgWrites, type ThemeDocument, validateThemeTokens } from "./themes.js";
+
+const ROLE = "CTAs and links only — never large background fills";
+
+function write(doc: ThemeDocument, set: Record<string, unknown>): ThemeDocument {
+  const n = normalizeTokens(set);
+  return applyDtcgWrites(doc, n.set, n.types, n.descriptions);
+}
+
+describe("token roles ride with the value (issue #430)", () => {
+  it("lifts $description off the envelope onto the canonical path", () => {
+    const n = normalizeTokens({
+      "color.primary": { $type: "color", $value: "#4f46e5", $description: ROLE },
+    });
+    expect(n.descriptions["color.primary"]).toBe(ROLE);
+    // The envelope is still unwrapped for the value itself.
+    expect(n.set["color.primary"]).toBe("#4f46e5");
+  });
+
+  it("stores the role on the leaf and keeps the document valid", () => {
+    const doc = write(
+      {},
+      {
+        "color.primary": { $type: "color", $value: "#4f46e5", $description: ROLE },
+      },
+    );
+    expect((doc.color as Record<string, { $description?: string }>).primary.$description).toBe(
+      ROLE,
+    );
+    expect(() => validateThemeTokens(doc)).not.toThrow();
+  });
+
+  it("PRESERVES the role across a later value-only edit", () => {
+    let doc = write(
+      {},
+      {
+        "color.primary": { $type: "color", $value: "#4f46e5", $description: ROLE },
+      },
+    );
+    doc = write(doc, { primaryColor: "#ff6600" });
+    const leaf = (doc.color as Record<string, { $value: unknown; $description?: string }>).primary;
+    expect(leaf.$value).toBe("#ff6600");
+    expect(leaf.$description).toBe(ROLE);
+  });
+
+  it("lets an explicit new role overwrite the old one", () => {
+    let doc = write(
+      {},
+      {
+        "color.primary": { $type: "color", $value: "#4f46e5", $description: ROLE },
+      },
+    );
+    doc = write(doc, {
+      "color.primary": { $type: "color", $value: "#4f46e5", $description: "Buttons only" },
+    });
+    expect((doc.color as Record<string, { $description?: string }>).primary.$description).toBe(
+      "Buttons only",
+    );
+  });
+
+  it("maps roles onto the CSS var names module CSS actually references", () => {
+    const doc = write(
+      {},
+      {
+        "color.primary": { $type: "color", $value: "#4f46e5", $description: ROLE },
+        "color.border": "#e5e5e5",
+      },
+    );
+    const roles = listTokenRoles(doc);
+    expect(roles["--color-primary"]).toBe(ROLE);
+    // A token with no recorded role contributes nothing — no invented text.
+    expect(roles["--color-border"]).toBeUndefined();
+  });
+
+  it("gives every var a typography composite emits the same role", () => {
+    const doc = write(
+      {},
+      {
+        "typography.heading": {
+          $type: "typography",
+          $value: { fontFamily: "Poppins, sans-serif", fontSize: "2rem" },
+          $description: "Section headings only",
+        },
+      },
+    );
+    const roles = listTokenRoles(doc);
+    expect(roles["--font-heading"]).toBe("Section headings only");
+    expect(roles["--text-heading"]).toBe("Section headings only");
+  });
+
+  it("ignores a blank role rather than storing an empty string", () => {
+    const n = normalizeTokens({
+      "color.primary": { $type: "color", $value: "#4f46e5", $description: "   " },
+    });
+    expect(n.descriptions["color.primary"]).toBeUndefined();
+  });
+});
+
+/**
+ * The anchor-page design review annotates tokens whose values are already
+ * settled. Restating each value just to attach a role is both a round-trip
+ * (read the document first) and a chance to drift one, so a `$value`-less
+ * envelope patches the metadata alone.
+ */
+describe("role-only patches (issue #430)", () => {
+  const DOC: ThemeDocument = {
+    color: { primary: { $type: "color", $value: "#4f46e5" } },
+    typography: {
+      heading: { $type: "typography", $value: { fontFamily: "Poppins, sans-serif" } },
+    },
+  };
+
+  it("sets the role and leaves $value and $type untouched", () => {
+    const doc = write(DOC, { "color.primary": { $description: ROLE } });
+    const leaf = (doc.color as Record<string, Record<string, unknown>>).primary;
+    expect(leaf.$value).toBe("#4f46e5");
+    expect(leaf.$type).toBe("color");
+    expect(leaf.$description).toBe(ROLE);
+  });
+
+  it("accepts the CSS-var form the AI reads off module CSS", () => {
+    const doc = write(DOC, { "--color-primary": { $description: ROLE } });
+    expect((doc.color as Record<string, Record<string, unknown>>).primary.$description).toBe(ROLE);
+  });
+
+  it("maps --font-<name> onto the typography composite", () => {
+    const doc = write(DOC, { "--font-heading": { $description: "Section headings only" } });
+    const leaf = (doc.typography as Record<string, Record<string, unknown>>).heading;
+    expect(leaf.$description).toBe("Section headings only");
+    expect(leaf.$value).toEqual({ fontFamily: "Poppins, sans-serif" });
+  });
+
+  it("annotates several tokens in ONE call", () => {
+    const doc = write(DOC, {
+      "color.primary": { $description: ROLE },
+      "typography.heading": { $description: "Section headings only" },
+    });
+    expect((doc.color as Record<string, Record<string, unknown>>).primary.$description).toBe(ROLE);
+    expect((doc.typography as Record<string, Record<string, unknown>>).heading.$description).toBe(
+      "Section headings only",
+    );
+  });
+
+  it("rejects a loose name — category is unresolvable without a value", () => {
+    expect(() => write(DOC, { primaryColor: { $description: ROLE } })).toThrow(/UnknownTokenName/);
+  });
+
+  it("rejects annotating a token that does not exist", () => {
+    expect(() => write(DOC, { "color.nonexistent": { $description: ROLE } })).toThrow(
+      /UnknownTokenName/,
+    );
+  });
+
+  it("a blank role-only patch writes nothing", () => {
+    const n = normalizeTokens({ "color.primary": { $description: "  " } });
+    expect(n.canonicalPaths).toHaveLength(0);
+    expect(n.descriptions).toEqual({});
+  });
+
+  it("still validates as a DTCG document afterwards", () => {
+    expect(() =>
+      validateThemeTokens(write(DOC, { "color.primary": { $description: ROLE } })),
+    ).not.toThrow();
+  });
+});

package/src/themes.ts

@@ -24,6 +24,7 @@
 
 import { z } from "zod";
 import { isUnsafeKey } from "./safe-keys.js";
+import { UnknownTokenName } from "./themes-errors.js";
 
 // ────────────────────────────────────────────────────────────────────
 // Primitives
@@ -117,6 +118,7 @@ export const themeTypographyComposite = z
       z
         .object({
           fontFamily: z.string().min(1).max(200).optional(),
+          fontStyle: z.enum(["normal", "italic"]).optional(),
           fontSize: dimensionValueString.optional(),
           fontWeight: fontWeightValue.optional(),
           lineHeight: z.union([z.number().positive(), dimensionValueString]).optional(),
@@ -728,11 +730,18 @@ function pluralise(category: string, n: number): string {
  * 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.
+ *
+ * issue #430 — `$description` (the token's ROLE: what it is for and
+ * where it must not be used) is preserved across value-only edits and
+ * overwritten only when `descriptions` supplies a new one. Before this,
+ * every routine value edit silently erased the role, so recording a
+ * role at all was pointless: the next `set_theme_tokens` wiped it.
  */
 export function applyDtcgWrites(
   current: ThemeDocument,
   writes: Record<string, unknown>,
   types: Record<string, string>,
+  descriptions: Record<string, string> = {},
 ): ThemeDocument {
   const out: ThemeDocument = JSON.parse(JSON.stringify(current));
   for (const [path, value] of Object.entries(writes)) {
@@ -759,9 +768,53 @@ export function applyDtcgWrites(
         ...(value as Record<string, unknown>),
       };
     }
+    // Role precedence: an explicitly supplied description wins; otherwise
+    // the leaf keeps the one it already carries. Only a token that never
+    // had a role ends up without one.
+    const existingDescription =
+      existing && typeof existing === "object"
+        ? (existing as { $description?: unknown }).$description
+        : undefined;
+    const nextDescription =
+      descriptions[path] ??
+      (typeof existingDescription === "string" ? existingDescription : undefined);
+    const extensions =
+      existing && typeof existing === "object"
+        ? { ...((existing as { $extensions?: Record<string, unknown> }).$extensions ?? {}) }
+        : {};
+    const oldValue = (existing as { $value?: { fontFamily?: string } } | undefined)?.$value;
+    if (
+      path.startsWith("typography.") &&
+      nextValue &&
+      typeof nextValue === "object" &&
+      (nextValue as { fontFamily?: string }).fontFamily !== oldValue?.fontFamily
+    )
+      delete extensions["caelo.font"];
     setLeafAtPath(out, path, {
+      ...(Object.keys(extensions).length ? { $extensions: extensions } : {}),
       $value: nextValue,
       ...(inferredType ? { $type: inferredType } : {}),
+      ...(nextDescription !== undefined ? { $description: nextDescription } : {}),
+    });
+  }
+
+  // issue #430 — ROLE-ONLY paths: a description with no value in `writes`.
+  // The anchor-page design review annotates tokens whose values are already
+  // settled, so it must not have to restate them (a restated value is a
+  // chance to drift one). Patch the metadata, leave `$value` and `$type`
+  // exactly as they are.
+  for (const [path, description] of Object.entries(descriptions)) {
+    if (path in writes) continue;
+    const existing = readLeafAtPath(out, path);
+    if (!existing) {
+      // Annotating a token that does not exist is a mistake worth naming —
+      // silently minting a value-less leaf would produce a document the
+      // renderer can't emit (CLAUDE.md §2).
+      throw new UnknownTokenName(path, []);
+    }
+    setLeafAtPath(out, path, {
+      ...(existing as Record<string, unknown>),
+      $description: description,
     });
   }
   return out;

package/src/url.test.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { isDesignatedHomePage, isHomeSlug } from "./url.js";
+
+describe("isHomeSlug", () => {
+  it("recognises the magic-slug sentinels regardless of surrounding slashes", () => {
+    for (const s of ["", "home", "index", "/", "/home/", "/index"]) {
+      expect(isHomeSlug(s)).toBe(true);
+    }
+  });
+
+  it("rejects ordinary slugs", () => {
+    for (const s of ["about", "homepage", "index2", "blog/home"]) {
+      expect(isHomeSlug(s)).toBe(false);
+    }
+  });
+});
+
+describe("isDesignatedHomePage (0184 shared predicate)", () => {
+  const PAGE = "11111111-1111-1111-1111-111111111111";
+  const OTHER = "22222222-2222-2222-2222-222222222222";
+
+  it("explicit designation wins regardless of slug", () => {
+    expect(isDesignatedHomePage(PAGE, "welcome", PAGE)).toBe(true);
+  });
+
+  it("magic slug is the fallback when no designation exists", () => {
+    expect(isDesignatedHomePage(PAGE, "home", null)).toBe(true);
+    expect(isDesignatedHomePage(PAGE, "home", undefined)).toBe(true);
+  });
+
+  it("a designation pointing at ANOTHER page does not claim this one", () => {
+    expect(isDesignatedHomePage(PAGE, "welcome", OTHER)).toBe(false);
+  });
+
+  it("plain page, no designation: not home", () => {
+    expect(isDesignatedHomePage(PAGE, "about", null)).toBe(false);
+  });
+});