@caelo-cms/shared 0.11.0 → 0.11.2

package/src/markup-structure.ts

@@ -120,13 +120,84 @@ function splitClasses(raw: string | undefined): string[] {
   return [...new Set(raw.split(/\s+/).filter((c) => c.length > 0))].sort();
 }
 
+/** Options of {@link stripMustache}. */
+export interface StripMustacheOptions {
+  /**
+   * Keep the text of a section inside a tag (`class="a {{#s}}b{{/s}}"` →
+   * `class="a b"`): every class the template CAN render. Default false:
+   * such a section is dropped, leaving the classes it ALWAYS renders.
+   */
+  readonly keepOptionalAttributeText?: boolean;
+}
+
 /**
  * Remove Mustache tags (`{{x}}`, `{{{x}}}`, `{{#s}}`, `{{/s}}`, `{{>p}}`)
  * from a module template so it parses as the markup it renders: a section
- * body stays once, a placeholder becomes empty.
+ * body between elements stays once (a list renders it per entry), a
+ * placeholder becomes empty.
+ *
+ * A section INSIDE a tag (`<div class="split {{#reverse}}rev{{/reverse}}">`,
+ * a boolean variant) is optional: the rendered element may or may not
+ * carry its text. By default it is dropped, so the template node has only
+ * the classes every render has (#1104). Keeping it made `rev` a required
+ * class — every render without it looked like free markup — and a root
+ * whose classes all sit in sections matched no render, so the module's
+ * free markup went unchecked.
+ */
+export function stripMustache(template: string, opts: StripMustacheOptions = {}): string {
+  const base = opts.keepOptionalAttributeText ? template : dropInTagSections(template);
+  return stripDelimited(stripDelimited(base, 3), 2);
+}
+
+/**
+ * Remove every `{{#s}}…{{/s}}` / `{{^s}}…{{/s}}` that opens inside a tag
+ * (between `<name` and its `>`), body included. One linear scan; Mustache
+ * tags are skipped whole, so a `>` in `{{>partial}}` never ends a tag.
  */
-export function stripMustache(template: string): string {
-  return stripDelimited(stripDelimited(template, 3), 2);
+function dropInTagSections(text: string): string {
+  let out = "";
+  let i = 0;
+  let inTag = false;
+  let quote: string | null = null;
+  // Names with no closer after some point have none after any later point
+  // either: remembering them keeps the scan linear on unclosed openers.
+  const unclosed = new Set<string>();
+  while (i < text.length) {
+    if (text.startsWith("{{", i)) {
+      const end = text.indexOf("}}", i + 2);
+      if (end < 0) break;
+      const sigil = text[i + 2];
+      if (inTag && (sigil === "#" || sigil === "^")) {
+        const name = text.slice(i + 3, end).trim();
+        const closer = `{{/${name}}}`;
+        const close = unclosed.has(name) ? -1 : text.indexOf(closer, end + 2);
+        if (close < 0) unclosed.add(name);
+        if (name.length > 0 && close >= 0) {
+          i = close + closer.length;
+          continue;
+        }
+      }
+      out += text.slice(i, end + 2);
+      i = end + 2;
+      continue;
+    }
+    const ch = text[i] as string;
+    if (inTag) {
+      if (quote !== null) {
+        if (ch === quote) quote = null;
+      } else if (ch === '"' || ch === "'") {
+        quote = ch;
+      } else if (ch === ">") {
+        inTag = false;
+      }
+    } else if (ch === "<" && /[a-zA-Z]/.test(text[i + 1] ?? "")) {
+      inTag = true;
+      quote = null;
+    }
+    out += ch;
+    i++;
+  }
+  return out + text.slice(i);
 }
 
 /**

package/src/media.ts

@@ -394,6 +394,18 @@ export type MediaSetCdnInput = z.infer<typeof mediaSetCdnInputSchema>;
 export interface MediaStorageAdapter {
   put(key: string, body: Uint8Array, contentType: string): Promise<void>;
   get(key: string): Promise<Uint8Array>;
+  /**
+   * #1216 — the object's size in bytes without reading it, so a caller can
+   * refuse an oversized object before it is loaded. Throws when the key
+   * does not exist.
+   */
+  size(key: string): Promise<number>;
+  /**
+   * #1216 — the object as a byte stream plus its size, for serving it
+   * without holding the whole file in memory. Throws when the key does not
+   * exist.
+   */
+  openStream(key: string): Promise<{ body: ReadableStream<Uint8Array>; sizeBytes: number }>;
   delete(key: string): Promise<void>;
   exists(key: string): Promise<boolean>;
   /** Bytes-on-disk for capacity reporting. */

package/src/module-id-tag.test.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { tagModuleId } from "./module-id-tag.js";
+
+describe("tagModuleId", () => {
+  it("stamps the first opening tag", () => {
+    expect(tagModuleId('<p class="a">hi</p>', "m1")).toBe(
+      '<p class="a" data-caelo-module-id="m1">hi</p>',
+    );
+  });
+
+  it("keeps a self-closing root self-closed (#1099)", () => {
+    expect(tagModuleId('<line x1="0" stroke="#E3E7EE"/>', "m1")).toBe(
+      '<line x1="0" stroke="#E3E7EE" data-caelo-module-id="m1"/>',
+    );
+    expect(tagModuleId('<circle r="2" />', "m1")).toBe('<circle r="2" data-caelo-module-id="m1"/>');
+    expect(tagModuleId("<br/>", "m1")).toBe('<br data-caelo-module-id="m1"/>');
+  });
+
+  it("does not mistake a slash inside a quoted value for self-closing", () => {
+    expect(tagModuleId('<a href="/">x</a>', "m1")).toBe(
+      '<a href="/" data-caelo-module-id="m1">x</a>',
+    );
+  });
+
+  it("is idempotent", () => {
+    const once = tagModuleId('<polyline points="0,0 1,1"/>', "m1");
+    expect(tagModuleId(once, "m2")).toBe(once);
+  });
+
+  it("stays linear on a long whitespace run inside the root tag", () => {
+    const html = `<div${"\t".repeat(200_000)}x>`;
+    const start = performance.now();
+    expect(tagModuleId(html, "m1").endsWith(' data-caelo-module-id="m1">')).toBe(true);
+    expect(performance.now() - start).toBeLessThan(500);
+  });
+});

package/src/module-id-tag.ts

@@ -22,9 +22,12 @@ export const MODULE_ID_ATTRIBUTE = "data-caelo-module-id";
  * stays attributed to itself. Comments / DOCTYPE / leading whitespace
  * before the first tag are tolerated. HTML without an opening tag (pure
  * text, a failure comment) returns unchanged because there's nothing to
- * attach to.
+ * attach to. A self-closing root (`<line … />`, common for SVG parts)
+ * gets the attribute before its `/` (#1099) — after it, the tag would no
+ * longer self-close and swallow every following sibling.
  *
  * @example tagModuleId("<p>hi</p>", "abc") // '<p data-caelo-module-id="abc">hi</p>'
+ * @example tagModuleId('<line x1="0"/>', "abc") // '<line x1="0" data-caelo-module-id="abc"/>'
  */
 export function tagModuleId(html: string, moduleId: string): string {
   if (!html) return html;
@@ -33,6 +36,12 @@ export function tagModuleId(html: string, moduleId: string): string {
   if (!m) return html;
   const tagAttrs = m[2] ?? "";
   if (/\sdata-caelo-module-id\s*=/.test(tagAttrs)) return html;
-  const replaced = `<${m[1]}${tagAttrs} ${MODULE_ID_ATTRIBUTE}="${moduleId}">`;
+  // String ops, not a `\s*\/\s*$` regex: that backtracks polynomially on
+  // long whitespace runs (CodeQL js/polynomial-redos).
+  const trimmed = tagAttrs.trimEnd();
+  const selfClosing = trimmed.endsWith("/");
+  const attrs = selfClosing ? trimmed.slice(0, -1).trimEnd() : tagAttrs;
+  const close = selfClosing ? "/>" : ">";
+  const replaced = `<${m[1]}${attrs} ${MODULE_ID_ATTRIBUTE}="${moduleId}"${close}`;
   return html.slice(0, m.index) + replaced + html.slice(m.index + m[0].length);
 }

package/src/nested-module-render.test.ts

@@ -29,6 +29,7 @@ import {
   type NestedRenderResolver,
   renderModuleWithContent,
   renderPlacedModule,
+  rewriteNestedRefs,
 } from "./nested-module-render.js";
 
 function buildResolver(
@@ -461,6 +462,44 @@ describe("renderModuleWithContent — list fields (epic #1107)", () => {
       }),
     ).toEqual([{ moduleId: MODULE.teaser, contentInstanceId: INSTANCE.teaser }]);
   });
+
+  it("rewriteNestedRefs remaps every ref collectNestedRefs finds and copies the rest", () => {
+    const COPY = "00000000-0000-4000-8000-00000000c0c0";
+    const values = {
+      heading: "Keep me",
+      cta: { moduleId: MODULE.teaser, contentInstanceId: INSTANCE.teaser },
+      cards: [{ moduleId: MODULE.teaser, contentInstanceId: INSTANCE.teaser }],
+      mega: [
+        {
+          id: T(1),
+          node: "entry",
+          values: { label: "Entry" },
+          children: [
+            {
+              id: T(2),
+              node: "promo",
+              values: { teaser: { moduleId: MODULE.teaser, contentInstanceId: INSTANCE.teaser } },
+            },
+          ],
+        },
+      ],
+    };
+    const rewritten = rewriteNestedRefs(values, (id) => {
+      if (id !== INSTANCE.teaser) throw new Error(`no copy for ${id}`);
+      return COPY;
+    });
+    expect(collectNestedRefs(rewritten)).toEqual([
+      { moduleId: MODULE.teaser, contentInstanceId: COPY },
+      { moduleId: MODULE.teaser, contentInstanceId: COPY },
+      { moduleId: MODULE.teaser, contentInstanceId: COPY },
+    ]);
+    expect(rewritten.heading).toBe("Keep me");
+    expect((rewritten.mega as { values: unknown }[])[0]?.values).toEqual({ label: "Entry" });
+    // The source is not mutated.
+    expect(collectNestedRefs(values).every((r) => r.contentInstanceId === INSTANCE.teaser)).toBe(
+      true,
+    );
+  });
 });
 
 describe("renderModuleWithContent — safety invariants", () => {

package/src/nested-module-render.ts

@@ -542,5 +542,40 @@ export function collectNestedRefs(values: Readonly<Record<string, unknown>>): Ne
   return refs;
 }
 
+/**
+ * A copy of `values` in which every nested-module reference
+ * {@link collectNestedRefs} finds points at `remap(contentInstanceId)`.
+ * Walks exactly the shapes the collector walks, so every ref the collector
+ * reports is the ref this rewrites; everything else is copied unchanged.
+ * Deep copies (`pages.duplicate`, `placement.fork_content`) use it to point
+ * a copied parent at its copied children instead of the source's.
+ *
+ * @param remap the new instance id for a source id. It should throw for an
+ *   id it has no copy for: keeping the source id would leave the copy
+ *   sharing nested content with the original.
+ */
+export function rewriteNestedRefs(
+  values: Readonly<Record<string, unknown>>,
+  remap: (contentInstanceId: string) => string,
+): Record<string, unknown> {
+  const visitAll = (v: object, depth: number): unknown =>
+    Array.isArray(v)
+      ? v.map((el) => visit(el, depth))
+      : Object.fromEntries(Object.entries(v).map(([k, el]) => [k, visit(el, depth)]));
+  const visit = (v: unknown, depth: number): unknown => {
+    if (depth > MAX_COLLECT_DEPTH || typeof v !== "object" || v === null) return v;
+    if (isNestedRef(v)) return { ...v, contentInstanceId: remap(v.contentInstanceId) };
+    if (Array.isArray(v)) return v.map((el) => visit(el, depth + 1));
+    const entry = v as { values?: unknown; children?: unknown };
+    const out: Record<string, unknown> = { ...(v as Record<string, unknown>) };
+    if (typeof entry.values === "object" && entry.values !== null) {
+      out.values = visitAll(entry.values, depth + 1);
+    }
+    if (Array.isArray(entry.children)) out.children = visit(entry.children, depth + 1);
+    return out;
+  };
+  return visitAll(values, 0) as Record<string, unknown>;
+}
+
 /** Bound for {@link collectNestedRefs}: list depth (8) × two levels per entry, plus slack. */
 const MAX_COLLECT_DEPTH = 24;

package/src/preview-compose-deferrals.test.ts

@@ -245,3 +245,47 @@ function liveScripts(html: string): string[] {
   parser.end();
   return scripts;
 }
+
+describe("composer — omitted modules", () => {
+  const omitted = (editorNotice: { html: string; css: string } | null): ComposeDeferral => ({
+    pluginSlug: "consent-manager",
+    reason: "unclassified",
+    omit: true,
+    editorNotice,
+  });
+  const MODULE_WITH_ASSETS = { ...VIDEO, css: ".video-frame{}", js: "fetch('https://t.example')" };
+  const composeOmitted = (d: ComposeDeferral) =>
+    composePageWithLayout({
+      templateHtml: TEMPLATE,
+      templateCss: "",
+      blocks: [{ blockName: "main", modules: [MODULE_WITH_ASSETS] }],
+      layoutHtml: LAYOUT,
+      layoutCss: "",
+      layoutBlocks: [],
+      deferredModules: { [VIDEO.moduleId]: d },
+    }).html;
+
+  it("leaves a build with nothing in the module's place", () => {
+    // A visitor cannot release it, so no placeholder and no parked copy:
+    // neither the markup nor the module's CSS/JS reach the page.
+    const html = composeOmitted(omitted(null));
+    expect(html).not.toContain("youtube.com");
+    expect(html).not.toContain(".video-frame");
+    expect(html).not.toContain("t.example");
+    expect(html).not.toContain("data-caelo-deferred");
+    expect(html).not.toContain("<template");
+  });
+
+  it("shows the editor notice in the preview, attributed to the module", () => {
+    const html = composeOmitted(
+      omitted({ html: '<div class="note">Hidden</div>', css: ".note{color:red}" }),
+    );
+    expect(html).toContain('<div class="note">Hidden</div>');
+    expect(html).toContain(".note{color:red}");
+    expect(html).toContain("data-caelo-deferred-omitted");
+    // The chat affordances reference the module the notice stands in for.
+    expect(html).toContain(`data-caelo-module-id="${VIDEO.moduleId}"`);
+    expect(html).not.toContain("youtube.com");
+    expect(html).not.toContain("<template");
+  });
+});

package/src/preview-compose.ts

@@ -30,7 +30,7 @@ import type { ModuleFieldKind } from "./content.js";
 import { findInteractionIds, interactionAssets } from "./interactions.js";
 import { type LinkResolver, resolveLinkRefsInHtml } from "./link-refs.js";
 import type { ListPageContext } from "./lists/resolve.js";
-import { tagModuleId } from "./module-id-tag.js";
+import { MODULE_ID_ATTRIBUTE, tagModuleId } from "./module-id-tag.js";
 import {
   type NestedModuleResource,
   type NestedRenderFailure,
@@ -530,12 +530,28 @@ function recordFailures(
  * A module withheld from this render, as resolved by the plugin host
  * (#450). The composer never decides this — it only knows the verdict.
  */
-export interface ComposeDeferral {
+export type ComposeDeferral = ComposeGateDeferral | ComposeOmitDeferral;
+
+/** Withheld behind a placeholder until the plugin's runtime releases it. */
+export interface ComposeGateDeferral {
   readonly pluginSlug: string;
   readonly reason: string;
   readonly placeholderModuleSlug: string;
   readonly placeholderHtml: string;
   readonly placeholderCss: string;
+  readonly omit?: undefined;
+}
+
+/**
+ * Left out entirely: nothing on the visitor's side can release it. The
+ * plugin host passes the editor notice only to the editor preview; a
+ * build gets `null` and the module's place stays empty.
+ */
+export interface ComposeOmitDeferral {
+  readonly pluginSlug: string;
+  readonly reason: string;
+  readonly omit: true;
+  readonly editorNotice: { readonly html: string; readonly css: string } | null;
 }
 
 /**
@@ -566,10 +582,8 @@ function wrapDeferredModule(
   moduleHtml: string,
   module: Pick<ComposeModule, "moduleId" | "slug" | "css" | "js">,
   nestedModules: readonly Pick<NestedModuleResource, "moduleId" | "css" | "js">[],
-  deferral: ComposeDeferral,
+  deferral: ComposeGateDeferral,
 ): string {
-  const attr = (v: string): string =>
-    v.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
   // Inside the inert <template>, only an element's own end tag ends a
   // <style> / <script>; a `</template` there is text. So CSS needs just
   // its own close escaped, JS that could end its <script> ships base64
@@ -598,6 +612,25 @@ function wrapDeferredModule(
   ].join("");
 }
 
+/**
+ * Emit an omitted module: nothing in a build, the editor notice in the
+ * preview. The module's markup, CSS and JS never reach the page — not
+ * even in a `<template>`, since nothing would ever clone it out. The
+ * notice carries the module id (and its slug as the label) so the
+ * editor's chat affordances reference the module it stands in for.
+ */
+function omittedModuleNotice(
+  module: Pick<ComposeModule, "moduleId" | "slug">,
+  deferral: ComposeOmitDeferral,
+): string {
+  if (deferral.editorNotice === null) return "";
+  return `<div data-caelo-deferred="${attr(deferral.pluginSlug)}" data-reason="${attr(deferral.reason)}" data-module="${attr(module.slug)}" data-caelo-deferred-omitted ${MODULE_ID_ATTRIBUTE}="${attr(module.moduleId)}" aria-label="${attr(module.slug)}">${deferral.editorNotice.html}</div>`;
+}
+
+function attr(v: string): string {
+  return v.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+}
+
 export interface ComposeLayoutBlock {
   readonly blockName: string;
   readonly modules: readonly ComposeModule[];
@@ -693,9 +726,9 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
   // Duplicate rule blocks made the cascade order-dependent and bloated
   // every page the same module appeared on twice.
   const seenAssetModules = new Set<string>();
-  // Placeholder CSS, keyed by placeholder slug: one withheld module's
-  // placeholder used on five placements is emitted once.
-  const deferredCss = new Map<string, string>();
+  // Placeholder and notice CSS: one withheld module's placeholder used
+  // on five placements is emitted once.
+  const deferredCss = new Set<string>();
   const moduleFailures: ComposeModuleFailure[] = [];
   // Nested modules rendered since the last asset flush (see flushNestedAssets).
   const nestedAssetIds: string[] = [];
@@ -734,7 +767,11 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
     }
     const tagged = tagModuleId(baseHtml, m.moduleId);
     if (!deferral) return tagged;
-    deferredCss.set(deferral.placeholderModuleSlug, deferral.placeholderCss);
+    if (deferral.omit) {
+      if (deferral.editorNotice) deferredCss.add(deferral.editorNotice.css);
+      return omittedModuleNotice(m, deferral);
+    }
+    deferredCss.add(deferral.placeholderCss);
     const gatedNested = [...gatedNestedIds].map((id) => {
       const nested = input.nestedModules?.getModule(id);
       // renderModuleFields resolved every id it reports through this
@@ -791,7 +828,7 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
     flushNestedAssets();
   }
 
-  for (const css of deferredCss.values()) {
+  for (const css of deferredCss) {
     if (css.trim().length > 0) cssParts.push(css);
   }
 

package/src/redirect-plan.test.ts

@@ -11,6 +11,7 @@ import {
   formatRedirectsFile,
   parseRedirectsFile,
   type RedirectTableRow,
+  redirectsToUnservedPaths,
 } from "./redirect-plan.js";
 
 const NO_FILES: ReadonlySet<string> = new Set();
@@ -141,3 +142,27 @@ describe("buildRedirectPlan", () => {
     expect(plan(rows)).toEqual(plan([...rows]));
   });
 });
+
+describe("redirectsToUnservedPaths (#1157)", () => {
+  const served = new Set(["index.html", "live/index.html", "doc.pdf"]);
+  it("reports redirects whose target the build does not serve, nothing else", () => {
+    const p = plan(
+      [
+        row("/a", "/live"),
+        row("/b", "/draft-page"),
+        row("/c", "/doc.pdf"),
+        row("/d", "/missing.pdf"),
+        row("/e", "/api/forms/x"),
+        row("/f", "/live?ref=1"),
+        row("/g", "/"),
+      ],
+      served,
+    );
+    expect(redirectsToUnservedPaths(p, served).map((r) => r.fromPath)).toEqual(["/b", "/d"]);
+  });
+
+  it("judges a chain by its final hop", () => {
+    const p = plan([row("/x", "/y"), row("/y", "/live")], served);
+    expect(redirectsToUnservedPaths(p, served)).toEqual([]);
+  });
+});

package/src/redirect-plan.ts

@@ -178,6 +178,30 @@ export function buildRedirectPlan(args: BuildRedirectPlanArgs): RedirectPlan {
   return { redirects, gone, shadowedByBuild };
 }
 
+/**
+ * The planned redirects whose Location is a same-site path the build does
+ * not serve (#1157). Redirects reach the live site on save, pages only with
+ * Publish live, so a redirect to a page that is still a draft answers 404 at
+ * its target until that page is published. Callers report these; they are
+ * not an error. Paths under `/api/` are answered by the gateway, not the
+ * build, and are never reported.
+ *
+ * @example
+ *   redirectsToUnservedPaths(plan, new Set(["index.html"]))
+ *   // → the entries of `plan.redirects` pointing anywhere but `/`
+ */
+export function redirectsToUnservedPaths(
+  plan: RedirectPlan,
+  servedFiles: ReadonlySet<string>,
+): PlannedRedirect[] {
+  return plan.redirects.filter((r) => {
+    const path = pathBeforeQuery(r.location);
+    if (path === "/api" || path.startsWith("/api/")) return false;
+    if (looksLikeFile(path)) return !servedFiles.has(path.slice(1));
+    return !servedByBuild(stripTrailingSlash(path), servedFiles);
+  });
+}
+
 function normaliseRows(rows: readonly RedirectTableRow[]): NormalisedRow[] {
   const byBare = new Map<string, NormalisedRow>();
   const out: NormalisedRow[] = [];

package/src/seo.test.ts

@@ -2,6 +2,7 @@
 
 import { describe, expect, it } from "bun:test";
 import {
+  breadcrumbJsonLdItems,
   checkPublicSiteBaseUrl,
   injectSeoIntoHead,
   renderSeoHead,
@@ -402,3 +403,60 @@ describe("checkPublicSiteBaseUrl", () => {
     }
   });
 });
+
+describe("BreadcrumbList JSON-LD (#1142)", () => {
+  const base = {
+    title: "Team",
+    metaDescription: "",
+    canonical: "https://example.com/about/team/",
+    noindex: false,
+    ogImageUrl: null,
+    organization: {},
+  };
+  const ldBlocks = (head: string): unknown[] =>
+    [...head.matchAll(/<script type="application\/ld\+json">(.*?)<\/script>/g)].map((m) =>
+      JSON.parse(m[1] as string),
+    );
+
+  it("lists the trail with positions, short titles and public URLs", () => {
+    const head = renderSeoHead({
+      ...base,
+      breadcrumbs: [
+        { name: "Start", url: "https://example.com/" },
+        { name: "About </script>", url: "https://example.com/about/" },
+        { name: "Team", url: "https://example.com/about/team/" },
+      ],
+    });
+    expect(head).not.toContain("About </script>");
+    expect(ldBlocks(head)[1]).toEqual({
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      itemListElement: [
+        { "@type": "ListItem", position: 1, name: "Start", item: "https://example.com/" },
+        {
+          "@type": "ListItem",
+          position: 2,
+          name: "About </script>",
+          item: "https://example.com/about/",
+        },
+        { "@type": "ListItem", position: 3, name: "Team", item: "https://example.com/about/team/" },
+      ],
+    });
+  });
+
+  it("emits no BreadcrumbList without a trail", () => {
+    expect(ldBlocks(renderSeoHead(base))).toHaveLength(1);
+    expect(ldBlocks(renderSeoHead({ ...base, breadcrumbs: [] }))).toHaveLength(1);
+  });
+
+  it("builds items from the trail, leaving out pages without a public URL", () => {
+    const known: Record<string, { name: string; url: string }> = {
+      home: { name: "Start", url: "https://example.com/" },
+      team: { name: "Team", url: "https://example.com/about/team/" },
+    };
+    expect(
+      breadcrumbJsonLdItems(["home", "draft-parent", "team"], (id) => known[id] ?? null),
+    ).toEqual([known.home, known.team]);
+    expect(breadcrumbJsonLdItems(null, () => null)).toEqual([]);
+  });
+});

package/src/seo.ts

@@ -265,6 +265,40 @@ export interface SeoMetaInput {
   noindex: boolean;
   ogImageUrl: string | null;
   organization: SiteSeoSettings["organization"];
+  /**
+   * #1142 — the breadcrumb trail the page SHOWS (home → current), as
+   * built by {@link breadcrumbJsonLdItems}; null or empty = the page shows
+   * none and gets no `BreadcrumbList`, so structured data never claims a
+   * trail a visitor cannot see.
+   */
+  breadcrumbs?: readonly BreadcrumbJsonLdItem[] | null;
+}
+
+/** One crumb of a `BreadcrumbList`: the page's short title and public URL. */
+export interface BreadcrumbJsonLdItem {
+  readonly name: string;
+  readonly url: string;
+}
+
+/**
+ * The `BreadcrumbList` items of a rendered trail (#1142). `lookup` answers
+ * a trail page's short title and public URL, or null when the page has no
+ * public URL in this render (not published). Such a crumb is left out:
+ * its visible link is already flagged by the unpublished-link gate, and a
+ * `ListItem` without a URL is only valid in the last position. The
+ * generator and the editor preview both build their items through here.
+ */
+export function breadcrumbJsonLdItems(
+  trail: readonly string[] | null,
+  lookup: (pageId: string) => BreadcrumbJsonLdItem | null,
+): BreadcrumbJsonLdItem[] {
+  if (trail === null) return [];
+  const out: BreadcrumbJsonLdItem[] = [];
+  for (const id of trail) {
+    const item = lookup(id);
+    if (item !== null) out.push(item);
+  }
+  return out;
 }
 
 /**
@@ -330,6 +364,21 @@ export function renderSeoHead(input: SeoMetaInput): string {
   lines.push(
     `<script type="application/ld+json">${JSON.stringify(ld).replace(/</g, "\\u003c")}</script>`,
   );
+  if (input.breadcrumbs && input.breadcrumbs.length > 0) {
+    const list = {
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      itemListElement: input.breadcrumbs.map((b, i) => ({
+        "@type": "ListItem",
+        position: i + 1,
+        name: b.name,
+        item: b.url,
+      })),
+    };
+    lines.push(
+      `<script type="application/ld+json">${JSON.stringify(list).replace(/</g, "\\u003c")}</script>`,
+    );
+  }
   return lines.join("\n");
 }