@caelo-cms/shared 0.10.66 → 0.10.68

package/src/build-page.test.ts

@@ -70,19 +70,20 @@ describe("buildPageInputSchema — page target modes", () => {
     expect(r.data.page.metaDescription).toBe("Plans and prices.");
   });
 
-  it("rejects a blank meta description and one given with pageId (fill-once is autofill_page_seo's job there)", () => {
+  it("rejects a blank meta description", () => {
     const blank = buildPageInputSchema.safeParse({
       page: { slug: "pricing", title: "Pricing", metaDescription: "   " },
       modules: [],
     });
     expect(blank.success).toBe(false);
+  });
+
+  it("takes a meta description with pageId (the existing page's first fill; run 40018361466)", () => {
     const existing = buildPageInputSchema.safeParse({
       page: { pageId: UUID, metaDescription: "Plans and prices." },
       modules: [],
     });
-    expect(existing.success).toBe(false);
-    if (existing.success) return;
-    expect(existing.error.issues[0]!.message).toContain("autofill_page_seo");
+    expect(existing.success).toBe(true);
   });
 
   it("rejects a page target with neither pageId nor slug+title", () => {

package/src/build-page.ts

@@ -20,7 +20,7 @@
  */
 
 import { z } from "zod";
-import { positionInputSchema } from "./ai-tools.js";
+import { positionInputSchema, sourceTextArg } from "./ai-tools.js";
 import {
   contentInstanceCreateSchema,
   MODULE_CSS_MAX,
@@ -155,9 +155,9 @@ export const buildPageModuleSchema = z
     description: z.string().max(1000).optional(),
     kind: moduleKindSchema.optional(),
     type: slugSchema.optional(),
-    html: z.string().min(1).max(MODULE_HTML_MAX).optional(),
-    css: z.string().max(MODULE_CSS_MAX).optional(),
-    js: z.string().max(MODULE_JS_MAX).optional(),
+    html: sourceTextArg(z.string().min(1).max(MODULE_HTML_MAX)).optional(),
+    css: sourceTextArg(z.string().max(MODULE_CSS_MAX)).optional(),
+    js: sourceTextArg(z.string().max(MODULE_JS_MAX)).optional(),
     fields: z.array(moduleFieldSchema).max(64).optional(),
     /** issue #164 slice 2 — opt-in mechanical token binding (tool layer). */
     bindThemeLiterals: z.boolean().optional(),
@@ -239,9 +239,13 @@ export const buildPageTargetSchema = z
      * The new page's meta description, written in the same transaction
      * with the fill-once semantics of `pages_seo.autofill` (CLAUDE.md §2).
      * A staging build refuses a published page without one, so the page
-     * is Stage-ready from the call that creates it. Create mode (or an
-     * importPageId rebuild) only — an existing page gets its first
-     * description from `autofill_page_seo`.
+     * is Stage-ready from the call that creates it. With `pageId` it is the
+     * existing page's FIRST description, same fill-once rule: a page that
+     * already has a different one keeps it (`kept-existing`, never an
+     * overwrite). Refusing it there (as #993 did) failed the natural "build
+     * the page's content and describe it in one pass" call (e2e-livedit run
+     * 40018361466) although the op applied it safely for importPageId
+     * rebuilds of existing pages all along.
      */
     metaDescription: z.string().trim().min(1).max(SEO_DESCRIPTION_HARD_MAX).optional(),
   })
@@ -251,13 +255,6 @@ export const buildPageTargetSchema = z
       ["slug", "title", "name", "templateId", "status", "parentPageId"] as const
     ).filter((k) => page[k] !== undefined);
     if (page.pageId !== undefined) {
-      if (page.metaDescription !== undefined) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message:
-            "page.metaDescription is written only for a page this call CREATES — drop it with pageId; an existing page without a description gets one via autofill_page_seo.",
-        });
-      }
       if (createKeys.length > 0) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
@@ -309,6 +306,12 @@ export type BuildPageInput = z.infer<typeof buildPageInputSchema>;
 
 /** `pages.build_page` op output — one row per placed module, in input order. */
 export const buildPagePlacementResultSchema = z.object({
+  /**
+   * The entry's index in the call's `modules` array. Detached (nested-only)
+   * entries are not placed, so the row's position in `placements` is NOT
+   * the input index once one precedes it — label results with this.
+   */
+  index: z.number().int().nonnegative(),
   blockName: z.string(),
   position: z.number().int().nonnegative(),
   moduleId: z.string(),

package/src/cloud-shell-install.test.ts

@@ -9,19 +9,14 @@ import {
 } from "./cloud-shell-install.js";
 
 describe("cloudShellInstallUrl", () => {
-  it("pins the release branch of the install repo and the provider's tutorial", () => {
-    expect(cloudShellInstallUrl("0.10.47", "gcp")).toBe(
-      "https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/caelo-cms/install&cloudshell_git_branch=release-v0.10.47&cloudshell_tutorial=gcp.md",
+  it("names no version: the install repo's main installs the newest release", () => {
+    expect(cloudShellInstallUrl("gcp")).toBe(
+      "https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/caelo-cms/install&cloudshell_git_branch=main&cloudshell_tutorial=gcp.md",
     );
-    expect(cloudShellInstallUrl("v1.2.3", "gcp-firebase")).toContain(
-      "cloudshell_git_branch=release-v1.2.3&cloudshell_tutorial=gcp-firebase.md",
+    expect(cloudShellInstallUrl("gcp-firebase")).toContain(
+      "cloudshell_git_branch=main&cloudshell_tutorial=gcp-firebase.md",
     );
   });
-
-  it("refuses pre-releases and garbage: they have no pinned branch", () => {
-    expect(() => cloudShellInstallUrl("0.11.0-rc.1", "gcp")).toThrow(/only stable releases/);
-    expect(() => cloudShellInstallUrl("latest", "gcp")).toThrow();
-  });
 });
 
 describe("cloudShellUpgradeUrl (#816)", () => {

package/src/cloud-shell-install.ts

@@ -1,14 +1,16 @@
 // SPDX-License-Identifier: MPL-2.0
 
 /**
- * The "Open in Google Cloud Shell" install link (epic #696, Phase 3).
+ * The "Open in Google Cloud Shell" links (epic #696, Phase 3).
  *
- * The link opens github.com/caelo-cms/install on the `release-v<version>`
- * branch that repository's track-release workflow creates for every stable
- * release (and never moves), with the provider's walkthrough tutorial. Its
- * `run.sh` pins and verifies exactly that release of the provisioner. One
- * builder for every place that shows the link — README, docs, and the
- * admin's "run this release in Cloud Shell" hint — so they can't drift.
+ * The INSTALL link names no version: it opens github.com/caelo-cms/install
+ * on `main`, whose `run.sh` resolves the newest stable release itself (npm
+ * `latest`) and verifies it before anything runs, so the link is right for
+ * every release and never moves. The UPGRADE link names one target release:
+ * it opens that release's `release-v<version>` branch (created by the
+ * install repository's track-release workflow, never moved), and `run.sh`
+ * there takes the version from the branch name. One builder per link for
+ * every place that shows it, so they can't drift.
  */
 
 import { isNewerVersion } from "./version.js";
@@ -25,25 +27,16 @@ export type CloudShellProvider = "gcp" | "gcp-firebase";
 const STABLE = /^v?(\d+\.\d+\.\d+)$/;
 
 /**
- * The Cloud Shell install link for a stable release.
+ * The Cloud Shell install link: always the newest stable release.
  *
- * @throws for a pre-release or non-SemVer version — only stable releases
- *   get a `release-v<version>` branch in the install repository
- *
- * @example cloudShellInstallUrl("0.10.47", "gcp")
- *   // → "https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/caelo-cms/install&cloudshell_git_branch=release-v0.10.47&cloudshell_tutorial=gcp.md"
+ * @example cloudShellInstallUrl("gcp")
+ *   // → "https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/caelo-cms/install&cloudshell_git_branch=main&cloudshell_tutorial=gcp.md"
  */
-export function cloudShellInstallUrl(version: string, provider: CloudShellProvider): string {
-  const m = STABLE.exec(version);
-  if (!m) {
-    throw new Error(
-      `no Cloud Shell install link for "${version}": only stable releases are pinned in ${CLOUD_SHELL_INSTALL_REPO}`,
-    );
-  }
+export function cloudShellInstallUrl(provider: CloudShellProvider): string {
   return [
     "https://shell.cloud.google.com/cloudshell/editor",
     `?cloudshell_git_repo=${CLOUD_SHELL_INSTALL_REPO}`,
-    `&cloudshell_git_branch=release-v${m[1]}`,
+    "&cloudshell_git_branch=main",
     `&cloudshell_tutorial=${provider}.md`,
   ].join("");
 }

package/src/index.ts

@@ -47,6 +47,7 @@ export * from "./mcp-access.js";
 export * from "./media.js";
 export * from "./nested-module-render.js";
 export * from "./page-log.js";
+export * from "./phase-timer.js";
 export * from "./platform-updates.js";
 export * from "./plugin-preview.js";
 export * from "./preview-compose.js";
@@ -64,6 +65,7 @@ export * from "./redirect-target.js";
 export * from "./release-manifest.js";
 export * from "./responsive-images.js";
 export * from "./result.js";
+export * from "./run-batched.js";
 export * from "./safe-keys.js";
 export * from "./screenshot-capture.js";
 export * from "./seo.js";

package/src/phase-timer.test.ts

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { PhaseTimer, phaseTimingSchema } from "./phase-timer.js";
+
+function clock(...ticks: number[]): () => number {
+  let i = 0;
+  return () => {
+    const t = ticks[Math.min(i, ticks.length - 1)];
+    i += 1;
+    return t ?? 0;
+  };
+}
+
+describe("PhaseTimer", () => {
+  it("each lap measures the time since the previous one", () => {
+    const t = new PhaseTimer(clock(0, 10.4, 35.6, 40));
+    t.lap("load");
+    t.lap("render");
+    expect(t.phases()).toEqual([
+      { phase: "load", ms: 10 },
+      { phase: "render", ms: 25 },
+    ]);
+    expect(t.totalMs()).toBe(40);
+  });
+
+  it("includes steps timed elsewhere under a prefix, before the lap that spans them", () => {
+    const t = new PhaseTimer(clock(0, 120));
+    t.include("generator", [
+      { phase: "compose", ms: 80 },
+      { phase: "media", ms: 30 },
+    ]);
+    t.lap("generator");
+    expect(t.phases()).toEqual([
+      { phase: "generator.compose", ms: 80 },
+      { phase: "generator.media", ms: 30 },
+      { phase: "generator", ms: 120 },
+    ]);
+  });
+
+  it("phases() is a copy and every entry passes the wire schema", () => {
+    const t = new PhaseTimer(clock(0, 5));
+    t.lap("x");
+    t.phases().pop();
+    expect(t.phases()).toHaveLength(1);
+    for (const p of t.phases()) expect(phaseTimingSchema.parse(p)).toEqual(p);
+  });
+});

package/src/phase-timer.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Wall-clock timings of the steps of one long operation (a Stage: chat
+ * merge, generator passes, upload, parity fingerprint, preview selection).
+ * The generator subprocess and the admin share this shape, so the
+ * generator's phases arrive in the admin's list prefixed and in order.
+ *
+ * Laps instead of wrapped callbacks: `lap("x")` closes the step that ran
+ * since the previous lap, so a long function gets one line per boundary
+ * and keeps its control flow (early throws, shared locals) as it is.
+ */
+
+import { z } from "zod";
+
+/** One finished step: its name and how long it took, in whole milliseconds. */
+export const phaseTimingSchema = z.object({
+  phase: z.string().min(1),
+  ms: z.number().int().nonnegative(),
+});
+export type PhaseTiming = z.infer<typeof phaseTimingSchema>;
+
+export class PhaseTimer {
+  readonly #now: () => number;
+  readonly #phases: PhaseTiming[] = [];
+  readonly #start: number;
+  #last: number;
+
+  /** @param now clock in milliseconds; injectable for tests. */
+  constructor(now: () => number = () => performance.now()) {
+    this.#now = now;
+    this.#start = now();
+    this.#last = this.#start;
+  }
+
+  /** Close the step that ran since the previous lap (or construction) as `phase`. */
+  lap(phase: string): void {
+    const t = this.#now();
+    this.#phases.push({ phase, ms: Math.round(t - this.#last) });
+    this.#last = t;
+  }
+
+  /**
+   * Append steps timed elsewhere (the generator subprocess, a publisher)
+   * as `<prefix>.<phase>`. They ran inside the current lap, so the lap that
+   * closes it still measures the whole span (the remainder is the overhead
+   * around them, e.g. spawning the subprocess).
+   */
+  include(prefix: string, phases: readonly PhaseTiming[]): void {
+    for (const p of phases) this.#phases.push({ phase: `${prefix}.${p.phase}`, ms: p.ms });
+  }
+
+  /** Milliseconds since construction. */
+  totalMs(): number {
+    return Math.round(this.#now() - this.#start);
+  }
+
+  /** The steps so far, in the order they finished. */
+  phases(): PhaseTiming[] {
+    return [...this.#phases];
+  }
+}

package/src/run-batched.test.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { runBatched } from "./run-batched.js";
+
+describe("runBatched", () => {
+  it("runs every item with at most `parallelism` in flight", async () => {
+    let inFlight = 0;
+    let peak = 0;
+    const done: number[] = [];
+    await runBatched([1, 2, 3, 4, 5, 6, 7], 3, async (n) => {
+      inFlight += 1;
+      peak = Math.max(peak, inFlight);
+      await new Promise((r) => setTimeout(r, 2));
+      done.push(n);
+      inFlight -= 1;
+    });
+    expect(done.sort()).toEqual([1, 2, 3, 4, 5, 6, 7]);
+    expect(peak).toBe(3);
+  });
+
+  it("stops starting new items after the first failure and rejects with it", async () => {
+    const started: number[] = [];
+    await expect(
+      runBatched([1, 2, 3, 4, 5, 6], 2, async (n) => {
+        started.push(n);
+        if (n === 2) throw new Error("boom 2");
+        await new Promise((r) => setTimeout(r, 5));
+      }),
+    ).rejects.toThrow("boom 2");
+    expect(started.length).toBeLessThan(6);
+  });
+
+  it("handles an empty list and refuses a non-positive parallelism", async () => {
+    await runBatched([], 4, async () => {
+      throw new Error("never");
+    });
+    await expect(runBatched([1], 0, async () => {})).rejects.toThrow("positive integer");
+  });
+});

package/src/run-batched.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Run `worker` over `items` with at most `parallelism` in flight, in item
+ * order. File and network I/O of a build (page writes, the `current/`
+ * mirror, uploads) goes through this: one-at-a-time costs a round trip per
+ * file, unbounded `Promise.all` exhausts file descriptors and memory on
+ * large sites.
+ *
+ * The first rejection rejects the whole call; workers already running
+ * finish, no new item starts.
+ */
+export async function runBatched<T>(
+  items: ReadonlyArray<T>,
+  parallelism: number,
+  worker: (item: T) => Promise<void>,
+): Promise<void> {
+  if (!Number.isInteger(parallelism) || parallelism < 1) {
+    throw new Error(`runBatched: parallelism must be a positive integer, got ${parallelism}`);
+  }
+  let cursor = 0;
+  let failed = false;
+  const next = async (): Promise<void> => {
+    while (!failed && cursor < items.length) {
+      const i = cursor++;
+      try {
+        // biome-ignore lint/style/noNonNullAssertion: cursor < length checked
+        await worker(items[i]!);
+      } catch (e) {
+        failed = true;
+        throw e;
+      }
+    }
+  };
+  const workers: Promise<void>[] = [];
+  const n = Math.min(parallelism, items.length);
+  for (let i = 0; i < n; i++) workers.push(next());
+  await Promise.all(workers);
+}

package/src/strip-cdata.test.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MPL-2.0
 
 import { describe, expect, it } from "bun:test";
-import { stripCdataGuards } from "./strip-cdata.js";
+import { stripCdataGuards, unwrapCdataEnvelope } from "./strip-cdata.js";
 
 describe("stripCdataGuards", () => {
   it("leaves clean HTML untouched (fast path)", () => {
@@ -39,3 +39,32 @@ describe("stripCdataGuards", () => {
     expect(stripCdataGuards(html)).toBe(html);
   });
 });
+
+describe("unwrapCdataEnvelope", () => {
+  // Shape of the add_module css the real-AI suite filed (run 39936064709).
+  const css =
+    ".consent-banner {\n  position: fixed;\n}\n@media (max-width: 640px) {\n  .x { width: 100%; }\n}";
+
+  it("decodes a whole-value envelope to its exact body", () => {
+    expect(unwrapCdataEnvelope(`<![CDATA[${css}]]>`)).toBe(css);
+    expect(unwrapCdataEnvelope(`\n  <![CDATA[${css}]]>\n`)).toBe(css);
+  });
+
+  it("leaves values without an enclosing envelope untouched", () => {
+    expect(unwrapCdataEnvelope(css)).toBe(css);
+    const guarded = `/*<![CDATA[*/ ${css} /*]]>*/`;
+    expect(unwrapCdataEnvelope(guarded)).toBe(guarded);
+    const midValue = `.a{} <![CDATA[ .b{} ]]>`;
+    expect(unwrapCdataEnvelope(midValue)).toBe(midValue);
+  });
+
+  it("does not decode two CDATA sections as one envelope", () => {
+    const two = "<![CDATA[.a{}]]> <![CDATA[.b{}]]>";
+    expect(unwrapCdataEnvelope(two)).toBe(two);
+  });
+
+  it("passes non-strings through for the schema to judge", () => {
+    expect(unwrapCdataEnvelope(undefined)).toBeUndefined();
+    expect(unwrapCdataEnvelope(42)).toBe(42);
+  });
+});

package/src/strip-cdata.ts

@@ -48,3 +48,34 @@ export function stripCdataGuards(html: string): string {
   if (!html.includes("CDATA") && !html.includes("]]>")) return html;
   return html.replace(CDATA_GUARDS, "");
 }
+
+const CDATA_ENVELOPE = /^\s*<!\[CDATA\[([\s\S]*)\]\]>\s*$/;
+
+/**
+ * Decode a whole-value `<![CDATA[ … ]]>` envelope around an AI tool
+ * argument that carries source text (module/template/layout html, css, js).
+ *
+ * Why at the tool boundary: tool parameters reach the model through an
+ * XML-shaped encoding, and for long markup strings the model sometimes
+ * escapes the WHOLE value as a CDATA section — a transport envelope, not
+ * content. The parameter descriptions say not to (issue #993's note), yet
+ * the real-AI suite still filed it on add_module css in roughly one run in
+ * seven (e.g. 39654716622 on main, 39936064709, 39971619728). Refusing it
+ * cost a tool round-trip every time and, for template/layout css (which has
+ * no CDATA refusal), stored a stylesheet the browser cannot parse.
+ *
+ * Only an envelope spanning the entire value is decoded, and only when its
+ * body contains no further `]]>` (a single CDATA section cannot). Anything
+ * else — `/*<![CDATA[*\/` guards inside the CSS, a marker mid-value — is
+ * left untouched so the op validator still refuses it loudly (CLAUDE.md §2):
+ * this decodes a malformed encoding of a value the caller did supply; it is
+ * not a fallback for missing data.
+ *
+ * @returns the envelope's body, or the input unchanged.
+ */
+export function unwrapCdataEnvelope(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  const m = CDATA_ENVELOPE.exec(value);
+  if (!m || m[1] === undefined || m[1].includes("]]>")) return value;
+  return m[1];
+}

package/src/theme-dimension.test.ts

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Dimension values accept CSS math functions (e2e-livedit run 40018361466:
+ * set_theme_tokens refused `typography.display` with a fluid
+ * `clamp(2.5rem, 2rem + 2.5vw, 4rem)` font size, and the error printed the
+ * truncated composite value, which hid the field it was about).
+ */
+
+import { describe, expect, it } from "bun:test";
+import { themeDocument } from "./themes.js";
+
+const display = (fontSize: string) => ({
+  typography: {
+    display: {
+      $type: "typography",
+      $value: {
+        fontFamily: "Inter, system-ui, -apple-system, 'Segoe UI', sans-serif",
+        fontSize,
+        fontWeight: 800,
+        lineHeight: 1.05,
+      },
+    },
+  },
+});
+
+describe("theme dimension values", () => {
+  it("accept clamp() / calc() / min() / max() font sizes and spacing", () => {
+    for (const v of [
+      "clamp(2.5rem, 2rem + 2.5vw, 4rem)",
+      "calc(1rem + 0.5vw)",
+      "min(4rem, 10vw)",
+      "max(1rem, calc(0.75rem + 1vw))",
+    ]) {
+      expect(themeDocument.safeParse(display(v)).success).toBe(true);
+    }
+    const spacing = {
+      spacing: { section: { $type: "dimension", $value: "clamp(2rem, 5vw, 5rem)" } },
+    };
+    expect(themeDocument.safeParse(spacing).success).toBe(true);
+  });
+
+  it("still refuse values that are not a length, and math functions that could close the declaration", () => {
+    for (const v of [
+      "large",
+      "clamp(1rem; } body { display:none }",
+      "calc(1rem)</style>",
+      "url(x)",
+    ]) {
+      expect(themeDocument.safeParse(display(v)).success).toBe(false);
+    }
+  });
+
+  it("name the offending field's value, not the truncated composite", () => {
+    const r = themeDocument.safeParse(display("large"));
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const message = r.error.issues.map((i) => i.message).join(" ");
+    expect(message).toContain('(got "large")');
+  });
+});

package/src/themes.ts

@@ -51,14 +51,26 @@ const colorValueString = z
     "color value must be #hex, oklch(...), rgb(...), or a CSS named color",
   );
 
-/** Dimension: a CSS length / percentage / numeric value. */
+/**
+ * Dimension: a CSS length / percentage / numeric value, or a CSS math
+ * function over them (`clamp()`, `calc()`, `min()`, `max()`).
+ *
+ * The math functions are accepted because fluid type is the idiomatic way to
+ * size a display heading — `clamp(2.5rem, 2rem + 2.5vw, 4rem)` — and token
+ * values are emitted verbatim as CSS custom properties, where a browser
+ * resolves them like any length. Refusing them (e2e-livedit run 40018361466,
+ * set_theme_tokens `typography.display`) cost a retry and the AI downgraded to
+ * a fixed size it had not chosen. The arguments are limited to numbers,
+ * units, operators, commas and nested parentheses, so a value cannot close
+ * the declaration (`;`, `{`, `}`) or carry markup.
+ */
 const dimensionValueString = z
   .string()
   .min(1)
-  .max(80)
+  .max(120)
   .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",
+    /^-?\d+(\.\d+)?(rem|em|px|%|vh|vw|vmin|vmax|pt|pc|ch|ex|fr|deg|rad|turn|s|ms)?$|^auto$|^0$|^(calc|clamp|min|max)\([0-9a-zA-Z.%+\-*/,\s()]+\)$/,
+    "dimension must be a CSS length / number / percentage, or clamp()/calc()/min()/max() over them",
   );
 
 /** Font-weight: keyword or 1-1000 number. */
@@ -422,6 +434,16 @@ const CATEGORY_EXPECTATIONS: Record<string, string> = {
 };
 
 /** Compact, human-readable render of a rejected `$value` for the error tail. */
+/** The value `path` points at inside `root`; `root` itself for an empty path. */
+function valueAtPath(root: unknown, path: readonly PropertyKey[]): unknown {
+  let node = root;
+  for (const key of path) {
+    if (node === null || typeof node !== "object") return node;
+    node = (node as Record<PropertyKey, unknown>)[key];
+  }
+  return node;
+}
+
 function describeValue(value: unknown): string {
   if (typeof value === "string") return JSON.stringify(value);
   if (value === undefined) return "undefined";
@@ -488,10 +510,13 @@ function refineKnownCategoryLeaves(
         });
       } else {
         for (const issue of sub.error.issues) {
+          // Name the offending LEAF, not the whole composite `$value`: a
+          // typography value prints `fontFamily` first, so the truncated
+          // object hid the `fontSize` the issue was about.
           ctx.addIssue({
             code: "custom",
             path: [...path, ...issue.path],
-            message: `${category} token "${String(name)}" invalid: ${issue.message} (got ${describeValue(obj.$value)})`,
+            message: `${category} token "${String(name)}" invalid: ${issue.message} (got ${describeValue(valueAtPath(obj, issue.path))})`,
           });
         }
       }

package/src/version.ts

@@ -22,7 +22,7 @@
  * follow standard SemVer.
  */
 
-export const CAELO_VERSION = "0.10.66";
+export const CAELO_VERSION = "0.10.68";
 
 /**
  * Deprecated alias for back-compat — early P17 work spelled this