@caelo-cms/shared 0.11.0 → 0.11.1

package/src/lists/resolve.ts

@@ -24,6 +24,7 @@
 
 import type { LinkResolver } from "../link-refs.js";
 import { parseLinkRef } from "../link-refs.js";
+import { SITE_TEXTS_LIST_TYPE } from "./default-types.js";
 import { type FieldDef, TERM_REF_RE, validateFieldValue } from "./fields.js";
 import type { ListItem } from "./items.js";
 import {
@@ -125,6 +126,19 @@ export interface ListPageContext {
   resolveField(field: ListFieldSpec, value: unknown, holder: ListHolder): ListFieldResolution;
   /** `{{page.*}}`: the rendering page as a record scope; null outside a page. */
   pageScope(): ScopeValue | null;
+  /**
+   * `{{site_text.<key>}}`: the site texts (entries of every list of type
+   * {@link SITE_TEXTS_LIST_TYPE}) in the rendering page's variant. An
+   * unknown or duplicate key resolves to a failure marker (#1142).
+   */
+  siteTextScope(): ScopeValue;
+  /**
+   * The page ids of the breadcrumb trail this render showed (home →
+   * current), or null when no `breadcrumbs` source rendered. Drives the
+   * `BreadcrumbList` JSON-LD, so structured data always matches the
+   * visible trail (#1142).
+   */
+  breadcrumbTrail(): readonly string[] | null;
   /**
    * A section name no module field declares, read as a plugin list
    * source (`{{#language_links}}` written before the field kind existed).
@@ -420,6 +434,7 @@ function createPageContext(
   >();
   let depTree = false;
   const depPages = new Set<string>();
+  let trail: readonly string[] | null = null;
   /** Entries of a page-shaped system source: their pages become deps. */
   const readPages = (pages: ListPageRecord[]): ListPageRecord[] => {
     for (const pg of pages) depPages.add(pg.id);
@@ -696,6 +711,8 @@ function createPageContext(
           return text(p.id);
         case "title":
           return text(p.title);
+        case "short_title":
+          return text(p.shortTitle);
         case "link":
           return linkValue({ href: `caelo:page/${p.id}` }, data);
         case "published_at":
@@ -728,19 +745,48 @@ function createPageContext(
     };
   };
 
-  const pageEntries = (pages: readonly ListPageRecord[]): ScopeEntry[] =>
+  /**
+   * Page-shaped entries. `ancestor` overrides `is_ancestor` where the
+   * source knows better than the page tree: a breadcrumb trail's home
+   * crumb sits above the current page without being its parent.
+   */
+  const pageEntries = (
+    pages: readonly ListPageRecord[],
+    ancestor?: (p: ListPageRecord, index: number) => boolean,
+  ): ScopeEntry[] =>
     pages.map((p, index) => {
       const get = pageValue(p);
       const pos = { index, count: pages.length, depth: 1 };
+      const isAncestor = ancestor ? bool(ancestor(p, index)) : undefined;
       return {
         id: p.id,
         itemAttr: null,
         childrenKey: null,
         depth: 1,
-        get: (key) => get(key) ?? positionValue(key, pos),
+        get: (key) =>
+          (key === "is_ancestor" ? isAncestor : undefined) ?? get(key) ?? positionValue(key, pos),
       };
     });
 
+  /**
+   * The home page in the rendering page's variant: the designated home
+   * itself, or its version in the variant's `link-resolve` group. Null
+   * when no home is designated or the variant has no version of it yet
+   * (an untranslated home is absent, never the other language's page).
+   */
+  const homeOfVariant = (): ListPageRecord | null => {
+    if (data.homePageId === null) return null;
+    const home = data.pages.get(data.homePageId) ?? null;
+    if (home === null || variant === null) return home;
+    const hv = data.pageVariants?.get(home.id);
+    if (hv === undefined || hv.variant === variant) return home;
+    if (hv.group === null) return null;
+    for (const [id, v] of data.pageVariants ?? []) {
+      if (v.group === hv.group && v.variant === variant) return data.pages.get(id) ?? null;
+    }
+    return null;
+  };
+
   const sameVariant = (p: ListPageRecord): boolean =>
     variant === null || data.pageVariants?.get(p.id)?.variant === variant;
 
@@ -792,7 +838,13 @@ function createPageContext(
           seen.add(p.id);
           p = p.parentId === null ? undefined : data.pages.get(p.parentId);
         }
-        return listValue(pageEntries(readPages(chain)));
+        // The home page is no parent in the tree, yet every trail starts
+        // there; its short name is the "Start" crumb, translated with it.
+        const home = homeOfVariant();
+        if (home && !seen.has(home.id)) chain.unshift(home);
+        trail = chain.map((pg) => pg.id);
+        const last = chain.length - 1;
+        return listValue(pageEntries(readPages(chain), (_pg, index) => index < last));
       }
       case "children": {
         depTree = true;
@@ -1039,10 +1091,56 @@ function createPageContext(
     return { ok: true, entries: entriesOf(checked.items, local, 1) };
   };
 
+  let siteTextMemo: ScopeValue | undefined;
+  /** `{{site_text.<key>}}` — see {@link ListPageContext.siteTextScope}. */
+  const siteTextScope = (): ScopeValue => {
+    if (siteTextMemo !== undefined) return siteTextMemo;
+    depTypes.add(SITE_TEXTS_LIST_TYPE);
+    const byKey = new Map<string, { list: LoadedList; item: ListItem }[]>();
+    for (const list of data.lists.values()) {
+      if (list.typeSlug !== SITE_TEXTS_LIST_TYPE) continue;
+      depLists.add(list.id);
+      for (const item of list.items) {
+        if (overlay?.listHidden.has(`${list.id}/${item.id}`)) continue;
+        const key = item.values.key;
+        if (typeof key !== "string") continue;
+        byKey.set(key, [...(byKey.get(key) ?? []), { list, item }]);
+      }
+    }
+    const memo = new Map<string, ScopeValue>();
+    siteTextMemo = {
+      kind: "record",
+      text: null,
+      present: true,
+      get(key) {
+        const hit = memo.get(key);
+        if (hit) return hit;
+        const found = byKey.get(key) ?? [];
+        let v: ScopeValue;
+        if (found.length === 0) v = { kind: "failed", marker: `site-text-missing:${key}` };
+        else if (found.length > 1) v = { kind: "failed", marker: `site-text-duplicate:${key}` };
+        else {
+          const { list, item } = found[0] as { list: LoadedList; item: ListItem };
+          const translated = overlay?.listValues.get(`${list.id}/${item.id}`)?.get("text");
+          const raw = translated ?? item.values.text;
+          v =
+            typeof raw === "string"
+              ? text(raw)
+              : { kind: "failed", marker: `site-text-missing:${key}` };
+        }
+        memo.set(key, v);
+        return v;
+      },
+    };
+    return siteTextMemo;
+  };
+
   let pageScopeMemo: ScopeValue | null | undefined;
   return {
     pageId,
     resolveField,
+    siteTextScope,
+    breadcrumbTrail: () => trail,
     pageScope: () => {
       if (pageScopeMemo === undefined) {
         if (current === null) pageScopeMemo = null;

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/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");
 }
 

package/src/source-text-transport.test.ts

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: MPL-2.0
 
 import { describe, expect, it } from "bun:test";
-import { createTemplateToolInput } from "./ai-tools.js";
+import { addModuleToolInput, createTemplateToolInput } from "./ai-tools.js";
+import { decodeEscapedLineBreaks } from "./escaped-line-breaks.js";
 import {
   decodeHtmlEscapedSource,
   decodeJsonEncodedSource,
@@ -43,13 +44,14 @@ describe("decodeJsonEncodedSource", () => {
 
 describe("decodeSourceTextTransport", () => {
   it("unwraps CDATA, then a JSON literal, then HTML escaping", () => {
-    expect(decodeSourceTextTransport(`<![CDATA[${markup}]]>`)).toBe(markup);
+    expect(decodeSourceTextTransport(`<![CDATA[${markup}]]>`, "html")).toBe(markup);
     expect(
       decodeSourceTextTransport(
         JSON.stringify(markup.replaceAll("<", "&lt;").replaceAll(">", "&gt;")),
+        "html",
       ),
     ).toBe(markup);
-    expect(decodeSourceTextTransport(42)).toBe(42);
+    expect(decodeSourceTextTransport(42, "html")).toBe(42);
   });
 
   it("is what create_template's html argument goes through", () => {
@@ -61,3 +63,96 @@ describe("decodeSourceTextTransport", () => {
     expect(r.html).toBe(markup);
   });
 });
+
+// e2e-livedit run 40532297620 (release gate v0.11.1): add_module's html, css
+// and js arrived with every line break as the two characters `\` `n`. The
+// stored footer showed literal `\n` text and the shared module <script>
+// threw `SyntaxError: Invalid or unexpected token` on every preview. These
+// are the exact values the AI sent.
+describe("decodeEscapedLineBreaks", () => {
+  const sentJs =
+    "(function () {\\n  document.querySelectorAll('.site-footer__year').forEach(function (el) {\\n    el.textContent = new Date().getFullYear();\\n  });\\n})();";
+  const sentCss =
+    ".site-footer {\\n  padding: 2rem 1.5rem;\\n  text-align: center;\\n}\\n.site-footer__link:hover {\\n  text-decoration: underline;\\n}";
+  const sentHtml =
+    '<footer class="site-footer">\\n  <nav class="site-footer__nav" aria-label="Footer">\\n    <ul class="site-footer__list">\\n      {{#nav}}\\n      <li class="site-footer__item"><a class="site-footer__link" href="{{link.href}}">{{label}}</a></li>\\n      {{/nav}}\\n    </ul>\\n  </nav>\\n</footer>';
+
+  it("turns escaped line breaks back into real ones (the run's exact values)", () => {
+    expect(decodeEscapedLineBreaks(sentJs, "js")).toBe(
+      "(function () {\n  document.querySelectorAll('.site-footer__year').forEach(function (el) {\n    el.textContent = new Date().getFullYear();\n  });\n})();",
+    );
+    expect(decodeEscapedLineBreaks(sentCss, "css")).toBe(
+      ".site-footer {\n  padding: 2rem 1.5rem;\n  text-align: center;\n}\n.site-footer__link:hover {\n  text-decoration: underline;\n}",
+    );
+    const html = decodeEscapedLineBreaks(sentHtml, "html") as string;
+    expect(html).not.toContain("\\n");
+    expect(html.split("\n")).toHaveLength(9);
+    expect(html).toContain('<footer class="site-footer">\n  <nav');
+  });
+
+  it("decodes escaped CRLF and escaped tab indentation", () => {
+    expect(decodeEscapedLineBreaks(".a {\\r\\n\\tcolor: red;\\r\\n\\t\\tx: y;\\r\\n}", "css")).toBe(
+      ".a {\n\tcolor: red;\n\t\tx: y;\n}",
+    );
+  });
+
+  it("leaves source with real line breaks, single-line code and escaped backslashes alone", () => {
+    const multiLine = "const s = 'a\\n  b';\nconsole.log(s.split('\\n  '));";
+    expect(decodeEscapedLineBreaks(multiLine, "js")).toBe(multiLine);
+    const minified = "var t=a.join('\\n');console.log(t.split('\\n'))";
+    expect(decodeEscapedLineBreaks(minified, "js")).toBe(minified);
+    const oneHit = "el.textContent = lines.join('\\n  ');";
+    expect(decodeEscapedLineBreaks(oneHit, "js")).toBe(oneHit);
+    const escapedBackslash = "a('\\\\n  x'); b('\\\\n  y');";
+    expect(decodeEscapedLineBreaks(escapedBackslash, "js")).toBe(escapedBackslash);
+    expect(decodeEscapedLineBreaks(7, "js")).toBe(7);
+  });
+
+  // PR #1189 review: an escape inside a literal is meaningful, so a value
+  // holding one is ambiguous and left exactly as sent — decoding it would
+  // turn valid source into broken source.
+  it("leaves values alone when an escaped line break sits inside a literal", () => {
+    const jsString = 'document.querySelector("pre").textContent = "Title\\n  Detail\\n  More";';
+    expect(decodeEscapedLineBreaks(jsString, "js")).toBe(jsString);
+    const jsTemplate = "(function () {\\n  el.title = `a\\n  b`;\\n})();";
+    expect(decodeEscapedLineBreaks(jsTemplate, "js")).toBe(jsTemplate);
+    const jsRegex = "(function () {\\n  var ok = /a\\n  b/.test(x);\\n})();";
+    expect(decodeEscapedLineBreaks(jsRegex, "js")).toBe(jsRegex);
+    const cssContent = '.a::after {\\n  content: "x\\n  y";\\n}';
+    expect(decodeEscapedLineBreaks(cssContent, "css")).toBe(cssContent);
+    const htmlAttr = '<div>\\n  <span title="a\\n  b">x</span>\\n</div>';
+    expect(decodeEscapedLineBreaks(htmlAttr, "html")).toBe(htmlAttr);
+    const htmlPre = '<div>\\n  <pre>printf("a\\n");</pre>\\n</div>';
+    expect(decodeEscapedLineBreaks(htmlPre, "html")).toBe(htmlPre);
+  });
+
+  it("decodes structural escapes around literals and comments that hold none", () => {
+    expect(
+      decodeEscapedLineBreaks(
+        "// it's the footer\\n(function () {\\n  var s = 'a\\\\n';\\n  /x/.test(s);\\n})();",
+        "js",
+      ),
+    ).toBe("// it's the footer\n(function () {\n  var s = 'a\\\\n';\n  /x/.test(s);\n})();");
+    expect(
+      decodeEscapedLineBreaks('<p>It\'s ours</p>\\n<p>\\n  <a href="/">Home</a>\\n</p>', "html"),
+    ).toBe('<p>It\'s ours</p>\n<p>\n  <a href="/">Home</a>\n</p>');
+  });
+
+  it("is what add_module's html / css / js arguments go through", () => {
+    const r = addModuleToolInput.parse({
+      target: "layout",
+      targetRef: "site-default",
+      blockName: "footer",
+      position: "bottom",
+      displayName: "Site Footer",
+      html: sentHtml,
+      css: sentCss,
+      js: sentJs,
+    });
+    for (const v of [r.html, r.css, r.js]) {
+      expect(v).toBeString();
+      expect(v).not.toContain("\\n");
+      expect(v).toContain("\n");
+    }
+  });
+});

package/src/source-text-transport.ts

@@ -6,7 +6,9 @@
  *
  * The model sometimes encodes a long markup string as a whole before it
  * sends it: as a CDATA section (`unwrapCdataEnvelope`), as a JSON string
- * literal (`"<footer class=\"x\">…"`), or HTML-escaped (`&lt;main&gt;…`).
+ * literal (`"<footer class=\"x\">…"`), HTML-escaped (`&lt;main&gt;…`), or
+ * with its line breaks string-escaped (`{\n  color: red;\n}`, see
+ * `escaped-line-breaks.ts`).
  * Each is an encoding of a value the caller did supply, never content:
  * a JSON string literal is not valid markup, CSS or JS as a whole, and
  * markup without a single `<` but with `&lt;tag` has no element at all.
@@ -19,6 +21,7 @@
  * a fallback for missing data (CLAUDE.md §2).
  */
 
+import { decodeEscapedLineBreaks, type SourceLanguage } from "./escaped-line-breaks.js";
 import { unwrapCdataEnvelope } from "./strip-cdata.js";
 
 /**
@@ -64,7 +67,15 @@ export function decodeHtmlEscapedSource(value: unknown): unknown {
     .replace(/&amp;/g, "&");
 }
 
-/** Every whole-value transport encoding, outermost first. */
-export function decodeSourceTextTransport(value: unknown): unknown {
-  return decodeHtmlEscapedSource(decodeJsonEncodedSource(unwrapCdataEnvelope(value)));
+/**
+ * Every whole-value transport encoding, outermost first.
+ *
+ * @param language - the grammar of the value; escaped line breaks are only
+ *   decoded where they cannot belong to a literal of it.
+ */
+export function decodeSourceTextTransport(value: unknown, language: SourceLanguage): unknown {
+  return decodeEscapedLineBreaks(
+    decodeHtmlEscapedSource(decodeJsonEncodedSource(unwrapCdataEnvelope(value))),
+    language,
+  );
 }