@caelo-cms/shared 0.10.57 → 0.10.59

package/src/link-refs.test.ts

@@ -123,6 +123,7 @@ describe("resolution", () => {
     expect(index("staging").forPage(null).resolve(ref)).toEqual({
       status: "unpublished",
       url: "/pricing/",
+      pageId: DRAFT,
     });
     expect(index("preview").forPage(null).resolve(ref)).toEqual({
       status: "resolved",
@@ -300,6 +301,27 @@ describe("composer — nav-menu sets and pre-rendered modules", () => {
       },
     ]);
   });
+
+  it("resolves references in the layout's own HTML and flags a broken one", () => {
+    // Rollout C stores layout HTML links as references; the page frame
+    // must resolve them like module HTML, never ship `caelo:` hrefs.
+    const out = composePageWithLayout({
+      layoutHtml:
+        `<html><head></head><body><a class="home" href="caelo:page/${PAGE}#top">Home</a>` +
+        `<a class="old" href="caelo:page/${GONE}">Old</a><caelo-slot name="content"></caelo-slot></body></html>`,
+      layoutCss: "",
+      layoutBlocks: [],
+      templateHtml: '<caelo-slot name="content"></caelo-slot>',
+      templateCss: "",
+      blocks: [],
+      structuredSets: { byKindSlug: {} },
+      linkResolver: index().forPage(PAGE),
+    });
+    expect(out.html).toContain('<a class="home" href="/company/about/#top">Home</a>');
+    expect(out.html).toContain(`<a class="old" href="caelo:page/${GONE}">Old</a>`);
+    expect(out.missingSlots).toContain(`link-target-missing:page/${GONE}`);
+    expect(out.moduleFailures).toEqual([]);
+  });
 });
 
 describe("grammar edge cases — boundaries, contexts, malformed references", () => {
@@ -497,6 +519,190 @@ describe("scanner stays linear on adversarial input (CodeQL js/polynomial-redos)
   }
 });
 
+// Rollout D — the `link-resolve` composition point's answer: pages in
+// variants (locales) grouped by "versions of each other".
+const EN_ABOUT = "a1111111-1111-4111-8111-111111111111";
+const DE_ABOUT = "a2222222-2222-4222-8222-222222222222";
+const EN_PRICING = "b1111111-1111-4111-8111-111111111111";
+const DE_PRICING = "b2222222-2222-4222-8222-222222222222";
+const EN_SOLO = "c1111111-1111-4111-8111-111111111111";
+const EN_HOME = "d1111111-1111-4111-8111-111111111111";
+const DE_HOME = "d2222222-2222-4222-8222-222222222222";
+
+function variantIndex(env: "preview" | "staging" = "staging") {
+  return createSiteLinkIndex({
+    env,
+    pageUrlStyle: "directory",
+    pages: [
+      { id: EN_ABOUT, path: "/about", status: "published" },
+      { id: DE_ABOUT, path: "/de/ueber", status: "published" },
+      { id: EN_PRICING, path: "/pricing", status: "published" },
+      { id: DE_PRICING, path: "/de/preise", status: "draft" },
+      { id: EN_SOLO, path: "/solo", status: "published" },
+      { id: EN_HOME, path: "/", status: "published" },
+      { id: DE_HOME, path: "/de", status: "published" },
+    ],
+    media: [{ id: MEDIA, slug: "hero-shot" }],
+    pageVariants: new Map([
+      [EN_ABOUT, { variant: "en", group: "g-about" }],
+      [DE_ABOUT, { variant: "de", group: "g-about" }],
+      [EN_PRICING, { variant: "en", group: "g-pricing" }],
+      [DE_PRICING, { variant: "de", group: "g-pricing" }],
+      [EN_SOLO, { variant: "en", group: null }],
+      [EN_HOME, { variant: "en", group: "g-home" }],
+      [DE_HOME, { variant: "de", group: "g-home" }],
+    ]),
+  });
+}
+
+const pageRef = (pageId: string, anchor: string | null = null): LinkRef => ({
+  kind: "page",
+  pageId,
+  query: null,
+  anchor,
+});
+
+describe("page variants (link-resolve) — links go to the rendering page's variant", () => {
+  it("maps a reference to the same-variant sibling, keeping the anchor", () => {
+    const de = variantIndex().forPage(DE_HOME);
+    expect(de.resolve(pageRef(EN_ABOUT, "team"))).toEqual({
+      status: "resolved",
+      url: "/de/ueber/#team",
+    });
+    // Already in the rendering variant: unchanged.
+    expect(de.resolve(pageRef(DE_ABOUT))).toEqual({ status: "resolved", url: "/de/ueber/" });
+    // A source-variant page renders its own variant's page.
+    const en = variantIndex().forPage(EN_HOME);
+    expect(en.resolve(pageRef(DE_ABOUT))).toEqual({ status: "resolved", url: "/about/" });
+    expect(en.resolve(pageRef(EN_ABOUT))).toEqual({ status: "resolved", url: "/about/" });
+  });
+
+  it("refuses two pages claiming the same variant in one group", () => {
+    expect(() =>
+      createSiteLinkIndex({
+        env: "staging",
+        pageUrlStyle: "directory",
+        pages: [
+          { id: EN_ABOUT, path: "/about", status: "published" },
+          { id: DE_ABOUT, path: "/de/ueber", status: "published" },
+        ],
+        media: [],
+        pageVariants: new Map([
+          [EN_ABOUT, { variant: "de", group: "g-about" }],
+          [DE_ABOUT, { variant: "de", group: "g-about" }],
+        ]),
+      }),
+    ).toThrow(/both the "de" version in variant group g-about/);
+  });
+
+  it("applies the environment policy to the SIBLING (an unpublished German version)", () => {
+    expect(variantIndex("staging").forPage(DE_HOME).resolve(pageRef(EN_PRICING))).toEqual({
+      status: "unpublished",
+      url: "/de/preise/",
+      pageId: DE_PRICING,
+    });
+    expect(variantIndex("preview").forPage(DE_HOME).resolve(pageRef(EN_PRICING))).toEqual({
+      status: "resolved",
+      url: "/de/preise/",
+    });
+  });
+
+  it("refuses a target without a sibling in the rendering variant, loudly", () => {
+    const missing: string[] = [];
+    const out = resolveLinkRefsInHtml(
+      `<a href="caelo:page/${EN_SOLO}">Solo</a>`,
+      variantIndex().forPage(DE_HOME),
+      missing,
+    );
+    expect(out).toBe(`<a href="caelo:page/${EN_SOLO}">Solo</a>`);
+    expect(missing).toEqual([`link-variant-missing:page/${EN_SOLO}:de`]);
+    expect(linkIssueSeverity("preview", "no-variant")).toBe("block");
+    expect(linkIssueSeverity("staging", "no-variant")).toBe("block");
+  });
+
+  it("maps nothing for a page no plugin has an opinion about, or a render outside a page", () => {
+    expect(variantIndex().forPage(PAGE).resolve(pageRef(EN_SOLO))).toEqual({
+      status: "resolved",
+      url: "/solo/",
+    });
+    expect(variantIndex().forPage(null).resolve(pageRef(DE_ABOUT))).toEqual({
+      status: "resolved",
+      url: "/de/ueber/",
+    });
+  });
+
+  it("covers HTML href, rich text, link field and link-list in one render", () => {
+    const r = renderTemplate({
+      html: `<a href="caelo:page/${EN_HOME}">Home</a><a href="{{cta_href}}">Go</a>{{#nav}}<a href="{{href}}">{{label}}</a>{{/nav}}<div>{{body}}</div>`,
+      fields: [
+        { name: "cta_href", kind: "link" },
+        { name: "nav", kind: "link-list" },
+        { name: "body", kind: "richtext" },
+      ],
+      contentValues: {
+        cta_href: `caelo:page/${EN_PRICING}#plans`,
+        nav: [
+          { label: "About", href: `caelo:page/${EN_ABOUT}` },
+          { label: "Solo", href: `caelo:page/${EN_SOLO}` },
+        ],
+        body: `<p><a href="caelo:page/${EN_ABOUT}?x=1">about</a></p>`,
+      },
+      linkResolver: variantIndex("preview").forPage(DE_PRICING),
+    });
+    expect(r.html).toBe(
+      '<a href="/de/">Home</a><a href="/de/preise/#plans">Go</a>' +
+        `<a href="/de/ueber/">About</a><a href="caelo:page/${EN_SOLO}">Solo</a>` +
+        '<div><p><a href="/de/ueber/?x=1">about</a></p></div>',
+    );
+    expect(r.missingSlots).toEqual([`link-variant-missing:page/${EN_SOLO}:de`]);
+  });
+
+  it("covers nav-menu sets in the composer and attributes a missing sibling to the nav", () => {
+    const out = composePageWithLayout({
+      layoutHtml:
+        '<html><head></head><body><caelo-slot name="header"></caelo-slot><caelo-slot name="content"></caelo-slot></body></html>',
+      layoutCss: "",
+      layoutBlocks: [
+        {
+          blockName: "header",
+          modules: [
+            {
+              moduleId: "m-nav",
+              slug: "nav-menu-main",
+              displayName: "Nav",
+              html: "",
+              css: "",
+              js: "",
+            },
+          ],
+        },
+      ],
+      templateHtml: '<caelo-slot name="content"></caelo-slot>',
+      templateCss: "",
+      blocks: [],
+      structuredSets: {
+        byKindSlug: {
+          "nav-menu/main": [
+            { label: "About", href: `caelo:page/${EN_ABOUT}` },
+            { label: "Solo", href: `caelo:page/${EN_SOLO}` },
+          ],
+        },
+      },
+      linkResolver: variantIndex().forPage(DE_ABOUT),
+    });
+    expect(out.html).toContain('<a href="/de/ueber/">About</a>');
+    expect(out.moduleFailures).toEqual([
+      {
+        blockName: "header",
+        moduleId: "m-nav",
+        moduleSlug: "nav-menu-main",
+        field: "",
+        reason: `link-variant-missing:page/${EN_SOLO}:de`,
+      },
+    ]);
+  });
+});
+
 describe("humanise — reads show paths, never ids", () => {
   it("maps references back to authorable paths and keeps broken ones raw", () => {
     const lookup = {

package/src/link-refs.ts

@@ -40,11 +40,18 @@
  * environment's policy (warn at Stage, block at Publish live — the
  * blocking check is rollout F).
  *
+ * Page variants (rollout D): a plugin that splits the site into page
+ * variants — international-site: one variant per language — answers
+ * the `link-resolve` composition point with each page's variant and
+ * variant group ({@link LinkPageVariant}). {@link SiteLinkIndex.forPage}
+ * then maps every page reference onto the target's sibling in the
+ * RENDERING page's variant, so a German page's links go to German pages
+ * wherever the link lives (module HTML, rich text, link fields, link
+ * lists, nav-menu sets, chrome). A target with no sibling in that
+ * variant is a loud failure (`link-variant-missing:page/<id>:<variant>`),
+ * never a silent link into another language.
+ *
  * Seams for the later rollout steps:
- *   - D (locale composition point): {@link SiteLinkIndex.forPage} is the
- *     per-rendering-page hook. A `link-resolve` contribution maps the
- *     target to the rendering page's same-locale sibling there; nothing
- *     in the engine or composer changes.
  *   - E (data migration): {@link mapLinkRefsDeep} / the canonicaliser's
  *     pure core walk the same shapes the migration rewrites.
  *   - F (reference integrity): {@link RecordingLinkResolver.observed}
@@ -104,6 +111,21 @@ const QUERY_SRC = "[A-Za-z0-9_\\-.~%=&;+/:@!$()*]{1,512}";
 // Fragment: what an HTML id / URL fragment realistically carries.
 const ANCHOR_SRC = "[A-Za-z0-9_\\-.~%:]{1,256}";
 const VARIANT_SRC = "[a-z][a-z0-9-]{0,63}";
+
+/**
+ * Whole-string tests for the query, anchor and media-variant parts of a
+ * reference — built from the grammar's own sources, so a writer that
+ * validates author input with them (write-time canonicalisation, #724
+ * rollout C) accepts exactly what {@link formatLinkRef} accepts and a bad
+ * suffix is a validation issue, never a thrown error.
+ */
+export const LINK_REF_PART_PATTERNS: Readonly<{ query: RegExp; anchor: RegExp; variant: RegExp }> =
+  {
+    query: new RegExp(`^${QUERY_SRC}$`),
+    anchor: new RegExp(`^${ANCHOR_SRC}$`),
+    variant: new RegExp(`^${VARIANT_SRC}$`),
+  };
+
 // `caelo:` is a scheme only where a scheme can start: `xcaelo:page/…`
 // is some other scheme's text, not a reference.
 const REF_START_SRC = "(?<![A-Za-z0-9+.\\-])caelo:";
@@ -312,11 +334,20 @@ export type LinkResolution =
   /**
    * The target exists but is not published, so a deploy build will not
    * contain it. Rendered with its URL; the caller applies the
-   * environment's policy ({@link linkIssueSeverity}).
+   * environment's policy ({@link linkIssueSeverity}). `pageId` is the
+   * page the URL points at — the referenced page, or its sibling in the
+   * rendering page's variant.
    */
-  | { readonly status: "unpublished"; readonly url: string }
+  | { readonly status: "unpublished"; readonly url: string; readonly pageId: string }
   /** No live target (never existed, deleted, another chat's branch). */
-  | { readonly status: "missing" };
+  | { readonly status: "missing" }
+  /**
+   * The target exists, but has no sibling in the rendering page's
+   * variant (a German page linking to a page that has no German
+   * version). Not rendered — linking into another variant instead is
+   * exactly the silent fallback CLAUDE.md §2 forbids.
+   */
+  | { readonly status: "no-variant"; readonly variant: string };
 
 /**
  * Turns references into URLs for ONE rendering page. Synchronous: the
@@ -354,14 +385,25 @@ export const LINK_TARGET_MISSING = "link-target-missing";
 export const LINK_RESOLVER_UNAVAILABLE = "link-resolver-unavailable";
 
 /**
- * True for every link failure marker: a missing target, a malformed
- * reference and a render without a resolver. The static generator's
+ * `missingSlots` marker for a page reference whose target has no sibling
+ * in the rendering page's variant:
+ * `link-variant-missing:page/<targetId>:<variant>` (variant = the
+ * rendering page's, e.g. a locale code). Blocks a deploy like a missing
+ * target.
+ */
+export const LINK_VARIANT_MISSING = "link-variant-missing";
+
+/**
+ * True for every link failure marker: a missing target, a target with
+ * no version in the rendering page's variant, a malformed reference and
+ * a render without a resolver. The static generator's
  * render gate and the nested-module echo filter both key on this, so a
  * new marker added here blocks a deploy everywhere at once.
  */
 export function isLinkFailureMarker(marker: string): boolean {
   return (
     marker.startsWith(`${LINK_TARGET_MISSING}:`) ||
+    marker.startsWith(`${LINK_VARIANT_MISSING}:`) ||
     marker.startsWith(`${LINK_REF_MALFORMED}:`) ||
     marker.startsWith(`${LINK_RESOLVER_UNAVAILABLE}:`)
   );
@@ -400,6 +442,10 @@ export function resolveLinkRefsInHtml(
       missing.push(`${LINK_TARGET_MISSING}:${linkRefTargetKey(ref)}`);
       return raw;
     }
+    if (r.status === "no-variant") {
+      missing.push(`${LINK_VARIANT_MISSING}:${linkRefTargetKey(ref)}:${r.variant}`);
+      return raw;
+    }
     return r.url;
   });
 }
@@ -409,13 +455,15 @@ export function resolveLinkRefsInHtml(
  * cleanly (maintainer decision on #724): a missing target blocks
  * everywhere; an unpublished one is a warning at Stage and blocks
  * Publish live / promote. The editor preview shows drafts, so nothing
- * there is an issue beyond a missing target.
+ * there is an issue beyond a missing target. A target without a sibling
+ * in the rendering page's variant counts as missing: there is no page
+ * the link could go to.
  */
 export function linkIssueSeverity(
   env: LinkRenderEnv,
   status: LinkResolution["status"],
 ): "block" | "warning" | null {
-  if (status === "missing") return "block";
+  if (status === "missing" || status === "no-variant") return "block";
   if (status === "unpublished") {
     if (env === "production") return "block";
     if (env === "staging") return "warning";
@@ -442,6 +490,17 @@ export interface LinkIndexMedia {
   readonly slug: string;
 }
 
+/**
+ * One page's place in a plugin's page-variant partition (the
+ * `link-resolve` composition point): its `variant` (international-site:
+ * the locale code) and the `group` of pages that are versions of each
+ * other (null = the page has no versions besides itself).
+ */
+export interface LinkPageVariant {
+  readonly variant: string;
+  readonly group: string | null;
+}
+
 /** What a render-wide link index is built from. */
 export interface SiteLinkIndexInput {
   /** Every live (non-deleted) page visible to the render's scope, drafts included. */
@@ -455,6 +514,14 @@ export interface SiteLinkIndexInput {
    * internal link, and byte-identical with the canonical (#590).
    */
   readonly pageUrlStyle: PageUrlStyle;
+  /**
+   * The `link-resolve` composition point's answer: page id → its variant
+   * and variant group. Absent or empty = no plugin partitions the site,
+   * every page reference resolves to the referenced page. A page missing
+   * from a non-empty map is one no plugin has an opinion about: links
+   * FROM it resolve as referenced, and a link TO it is not remapped.
+   */
+  readonly pageVariants?: ReadonlyMap<string, LinkPageVariant>;
 }
 
 /**
@@ -464,10 +531,11 @@ export interface SiteLinkIndexInput {
 export interface SiteLinkIndex {
   readonly env: LinkRenderEnv;
   /**
-   * The resolver for rendering page `renderingPageId`. Today every page
-   * gets the same answers; rollout D's `link-resolve` composition point
-   * hooks in here to map a target onto the rendering page's locale.
-   * Each call returns a fresh {@link RecordingLinkResolver}.
+   * The resolver for rendering page `renderingPageId`: page references
+   * resolve to the target's sibling in the rendering page's variant
+   * ({@link SiteLinkIndexInput.pageVariants}); null = a render outside
+   * any page, which maps nothing. Each call returns a fresh
+   * {@link RecordingLinkResolver}.
    */
   forPage(renderingPageId: string | null): RecordingLinkResolver;
   /** The page's public path (no style applied), or null when unknown. */
@@ -504,29 +572,59 @@ function pageRefUrl(ref: PageLinkRef, path: string, style: PageUrlStyle): string
 export function createSiteLinkIndex(input: SiteLinkIndexInput): SiteLinkIndex {
   const pages = new Map(input.pages.map((p) => [p.id, p]));
   const media = new Map(input.media.map((m) => [m.id, m]));
-  const resolve = (ref: LinkRef): LinkResolution => {
+  const variants = input.pageVariants ?? new Map<string, LinkPageVariant>();
+  // group → variant → page: the sibling lookup. Only pages the index
+  // knows count — a sibling deleted or on another chat's branch is no
+  // sibling.
+  const siblings = new Map<string, Map<string, string>>();
+  for (const [pageId, v] of variants) {
+    if (v.group === null || !pages.has(pageId)) continue;
+    const members = siblings.get(v.group) ?? new Map<string, string>();
+    const clash = members.get(v.variant);
+    if (clash !== undefined) {
+      // Two versions of one page in one variant: a link could go to
+      // either, and picking one silently hides the broken partition.
+      throw new Error(
+        `link index: pages ${clash} and ${pageId} are both the "${v.variant}" version in variant group ${v.group}. A group holds at most one page per variant — unlink one of them from the group.`,
+      );
+    }
+    members.set(v.variant, pageId);
+    siblings.set(v.group, members);
+  }
+  /** The page a link to `targetId` goes to when rendered in `variant`. */
+  const pageInVariant = (targetId: string, variant: string | null): string | null => {
+    const target = variants.get(targetId);
+    if (variant === null || target === undefined || target.variant === variant) return targetId;
+    if (target.group === null) return null;
+    return siblings.get(target.group)?.get(variant) ?? null;
+  };
+  const resolve = (ref: LinkRef, variant: string | null): LinkResolution => {
     if (ref.kind === "media") {
       const asset = media.get(ref.mediaId);
       if (!asset) return { status: "missing" };
       return { status: "resolved", url: buildMediaUrl(asset.slug, ref.variant ?? "orig") };
     }
-    const page = pages.get(ref.pageId);
-    if (!page) return { status: "missing" };
+    if (!pages.has(ref.pageId)) return { status: "missing" };
+    const pageId = pageInVariant(ref.pageId, variant);
+    const page = pageId === null ? undefined : pages.get(pageId);
+    if (pageId === null || !page) return { status: "no-variant", variant: variant as string };
     const url = pageRefUrl(ref, page.path, input.pageUrlStyle);
     if (input.env !== "preview" && page.status !== "published") {
-      return { status: "unpublished", url };
+      return { status: "unpublished", url, pageId };
     }
     return { status: "resolved", url };
   };
   return {
     env: input.env,
     pathOf: (pageId) => pages.get(pageId)?.path ?? null,
-    forPage: () => {
+    forPage: (renderingPageId) => {
       const observed: ObservedLinkResolution[] = [];
+      const variant =
+        renderingPageId === null ? null : (variants.get(renderingPageId)?.variant ?? null);
       return {
         observed,
         resolve(ref) {
-          const resolution = resolve(ref);
+          const resolution = resolve(ref, variant);
           observed.push({ ref, resolution });
           return resolution;
         },

package/src/media.ts

@@ -227,9 +227,25 @@ export function extractMediaRefs(html: string): MediaRef[] {
     seen.add(key);
     out.push({ ref, isSlug, variant });
   }
+  // Epic #724 — stored references `caelo:media/<id>[/<variant>]` name the
+  // asset by id, like the legacy form, so usage tracking and the delete
+  // guards keep seeing embeds after write-time canonicalisation. (The
+  // grammar lives in link-refs.ts, which imports this module; the pattern
+  // is repeated here instead of importing back.)
+  for (const m of html.matchAll(mediaRefPattern)) {
+    const ref = m[1] as string;
+    const variant = m[2] ?? "orig";
+    const key = `i:${ref}/${variant}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ ref, isSlug: false, variant });
+  }
   return out;
 }
 
+const mediaRefPattern =
+  /caelo:media\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:\/([a-z][a-z0-9-]{0,63}))?/g;
+
 // ---------------------------------------------------------------------
 // Zod schemas — exposed at the Query-API boundary.
 // ---------------------------------------------------------------------

package/src/nested-module-render.ts

@@ -341,11 +341,25 @@ function renderPartial(
   values: Readonly<Record<string, unknown>>,
   ctx: RenderContext,
 ): string | undefined {
+  const hit = nestedRefForPartial(key, fieldByName, values);
+  if (!hit) return undefined;
+  return renderInner(hit.ref.moduleId, hit.ref.contentInstanceId, descend(ctx, hit.step));
+}
+
+/**
+ * The nested ref behind partial `key`, with its field trail step
+ * (`name` or `name[i]`); `undefined` when the key names no well-formed
+ * ref. The one place that maps the engine's partial keys to values.
+ */
+function nestedRefForPartial(
+  key: string,
+  fieldByName: ReadonlyMap<string, TemplateField>,
+  values: Readonly<Record<string, unknown>>,
+): { readonly ref: NestedRefValue; readonly field: string; readonly step: string } | undefined {
   const single = fieldByName.get(key);
   if (single?.kind === "module") {
     const ref = values[key];
-    if (!isNestedRef(ref)) return undefined;
-    return renderInner(ref.moduleId, ref.contentInstanceId, descend(ctx, key));
+    return isNestedRef(ref) ? { ref, field: key, step: key } : undefined;
   }
   const sep = key.lastIndexOf("__");
   const index = key.slice(sep + 2);
@@ -357,8 +371,49 @@ function renderPartial(
   if (!Array.isArray(raw)) return undefined;
   const i = Number(index);
   const el = raw[i];
-  if (!isNestedRef(el)) return undefined;
-  return renderInner(el.moduleId, el.contentInstanceId, descend(ctx, `${name}[${i}]`));
+  return isNestedRef(el) ? { ref: el, field: name, step: `${name}[${i}]` } : undefined;
+}
+
+/** A nested ref a module's template dispatches (see {@link dispatchedNestedRefs}). */
+export interface DispatchedNestedRef extends NestedRefValue {
+  /** The `module` / `module-list` field holding it. */
+  readonly field: string;
+}
+
+/**
+ * Epic #724 (rollout F) — the nested refs that render when this module
+ * renders with these values: exactly the refs {@link renderPlacedModule}
+ * recurses into. Rendering is lazy (a declared `module` / `module-list`
+ * field the HTML never dispatches with `{{>name}}` / `{{#name}}` is not
+ * rendered), so a checker that walks every declared field would report
+ * links that never ship. This asks the template engine itself which
+ * partials it dispatches, so it follows the grammar exactly.
+ *
+ * @returns one entry per dispatched ref, in render order, deduplicated.
+ */
+export function dispatchedNestedRefs(
+  html: string,
+  fields: readonly TemplateField[],
+  values: Readonly<Record<string, unknown>>,
+): DispatchedNestedRef[] {
+  const fieldByName = new Map(fields.map((f) => [f.name, f]));
+  const out: DispatchedNestedRef[] = [];
+  const asked = new Set<string>();
+  renderTemplate({
+    html,
+    fields,
+    contentValues: values,
+    partials: (key) => {
+      const hit = nestedRefForPartial(key, fieldByName, values);
+      if (!hit) return undefined;
+      if (!asked.has(key)) {
+        asked.add(key);
+        out.push({ ...hit.ref, field: hit.field });
+      }
+      return "";
+    },
+  });
+  return out;
 }
 
 /** The context for rendering the nested module at `step` under ctx's module. */

package/src/preview-compose.ts

@@ -918,8 +918,16 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
     jsParts.push(NAV_TOGGLE_JS);
   }
 
-  // 3. Render the layout HTML, substituting all named slots.
-  const replaced = applySlotReplacements(input.layoutHtml, {
+  // 3. Render the layout HTML, substituting all named slots. The
+  //    layout's own markup (the page frame around the blocks) stores
+  //    internal links as references too (#724 rollout C canonicalises
+  //    layouts.create / .update), so they resolve here like module HTML
+  //    — BEFORE the slots are filled, so already-resolved block HTML is
+  //    not scanned twice. A failure lands in `missingSlots` (the
+  //    preview's missing-content surface; the static build refuses it).
+  const layoutLinkMarkers: string[] = [];
+  const layoutHtml = resolveLinkRefsInHtml(input.layoutHtml, input.linkResolver, layoutLinkMarkers);
+  const replaced = applySlotReplacements(layoutHtml, {
     contentByName: layoutContentByName,
   });
   let html = replaced.html;
@@ -971,6 +979,7 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
   ]);
   const missingSet = new Set<string>([...renderedTemplate.missingSlots, ...replaced.missingSlots]);
   for (const name of replacedSet) missingSet.delete(name);
+  for (const marker of layoutLinkMarkers) missingSet.add(marker);
   return {
     html,
     replacedSlots: [...replacedSet],

package/src/theme-normalize-typography-subfields.test.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Regression: saving the Typography tab posts every sub-field of a named
+ * style as its own `typography.<style>.<sub>` key, with lineHeight /
+ * fontWeight coerced to numbers. Numbers used to skip the composite wrap
+ * (so `$value` became a bare `1.6`) and sibling sub-fields overwrote each
+ * other on the shared composite path.
+ */
+import { describe, expect, it } from "bun:test";
+import { normalizeTokens } from "./theme-normalize.js";
+import { applyDtcgWrites, themeDocument } from "./themes.js";
+
+describe("normalizeTokens typography sub-fields", () => {
+  it("wraps numeric sub-field values into the composite", () => {
+    const r = normalizeTokens({ "typography.body.lineHeight": 1.6 });
+    expect(r.set["typography.body"]).toEqual({ lineHeight: 1.6 });
+  });
+
+  it("merges several sub-fields of one style into one composite", () => {
+    const r = normalizeTokens({
+      fontHeading: "Inter, sans-serif",
+      "typography.heading.fontSize": "3rem",
+      "typography.heading.fontWeight": 650,
+      "typography.heading.lineHeight": 1.08,
+    });
+    expect(r.set["typography.heading"]).toEqual({
+      fontFamily: "Inter, sans-serif",
+      fontSize: "3rem",
+      fontWeight: 650,
+      lineHeight: 1.08,
+    });
+    expect(r.canonicalPaths).toEqual(["typography.heading"]);
+  });
+
+  it("produces a valid document when applied over an existing theme", () => {
+    const current = {
+      typography: {
+        body: { $type: "typography", $value: { fontFamily: "Inter", fontSize: "1rem" } },
+      },
+    };
+    const r = normalizeTokens({
+      "typography.body.fontWeight": 400,
+      "typography.body.lineHeight": 1.6,
+    });
+    const next = applyDtcgWrites(current as never, r.set, r.types);
+    expect(themeDocument.safeParse(next).success).toBe(true);
+    expect((next.typography as Record<string, { $value: unknown }>).body?.$value).toEqual({
+      fontFamily: "Inter",
+      fontSize: "1rem",
+      fontWeight: 400,
+      lineHeight: 1.6,
+    });
+  });
+});