@caelo-cms/shared 0.11.0 → 0.11.2

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,
+  );
 }

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

@@ -551,3 +551,58 @@ describe("lists — loud markers", () => {
     expect(r.missingSlots).toEqual(["list-context-unavailable:bullets"]);
   });
 });
+
+describe("lists — breadcrumbs and {{site_text.*}} (#1142)", () => {
+  const SITE_TEXTS = "00000000-0000-4000-8000-0000000000e1";
+  const withTexts = (pageId: string, texts: Record<string, string>): ListPageContext =>
+    createListRenderContext(
+      fixtureData({
+        lists: [
+          {
+            id: SITE_TEXTS,
+            slug: "site-texts",
+            name: "Site texts",
+            typeSlug: "site-texts",
+            items: Object.entries(texts).map(([key, text], i) => ({
+              id: uuid(900 + i),
+              node: "text",
+              values: { key, text },
+            })),
+          },
+        ],
+      }),
+    ).forPage(pageId, { linkResolver: fixtureLinkIndex().forPage(pageId) });
+  const CRUMBS: TemplateField = {
+    name: "crumbs",
+    kind: "list",
+    listType: "links",
+    bind: "source",
+    source: { kind: "system", name: "breadcrumbs" },
+  };
+  const NAV =
+    '<nav aria-label="{{site_text.breadcrumb_label}}"><ol>{{#crumbs}}<li>{{#is_current}}<span aria-current="page">{{short_title}}</span>{{/is_current}}{{^is_current}}<a href="{{link}}">{{short_title}}</a>{{/is_current}}</li>{{/crumbs}}</ol></nav>';
+
+  it("renders a trail home → current with the aria-label from the site texts", () => {
+    const r = render(NAV, [CRUMBS], {}, withTexts(PAGE.team, { breadcrumb_label: "Breadcrumb" }));
+    expect(r.html).toBe(
+      '<nav aria-label="Breadcrumb"><ol><li><a href="/">Home</a></li><li><a href="/about/">About</a></li><li><span aria-current="page">Team</span></li></ol></nav>',
+    );
+    expect(r.missingSlots).toEqual([]);
+  });
+
+  it("a missing site text stays loud", () => {
+    const r = render(
+      '<nav aria-label="{{site_text.breadcrumb_label}}"></nav>',
+      [],
+      {},
+      withTexts(PAGE.team, {}),
+    );
+    expect(r.html).toBe('<nav aria-label="{{site_text.breadcrumb_label}}"></nav>');
+    expect(r.missingSlots).toContain("site-text-missing:breadcrumb_label");
+  });
+
+  it("is loud without a list context", () => {
+    const r = render("{{site_text.breadcrumb_label}}", [], {}, null);
+    expect(r.missingSlots).toContain("list-context-unavailable:site_text");
+  });
+});

package/src/template-sections.ts

@@ -68,6 +68,17 @@ const TAG_RE = /\{\{\s*([#^/>]\s*)?([a-zA-Z][a-zA-Z0-9_]*(?:\.[a-zA-Z0-9_]+)*)\s
 const SECTION_NAME_RE = /^[a-z][a-z0-9_]*(?:\.[a-z0-9_]+)*$/;
 const DOT_RE = /\{\{\s*\.\s*\}\}/g;
 
+/** Dotted heads the list context answers, not an entry: `{{page.*}}`, `{{site_text.*}}`. */
+const CONTEXT_HEADS = new Set(["page", "site_text"]);
+
+function contextHead(name: string): string {
+  return (name.split(".")[0] ?? "").toLowerCase();
+}
+
+function isContextHead(name: string): boolean {
+  return CONTEXT_HEADS.has(contextHead(name));
+}
+
 function tokenize(html: string): Token[] {
   const out: Token[] = [];
   TAG_RE.lastIndex = 0;
@@ -201,6 +212,9 @@ class SectionRenderer {
       v = this.env.lists?.pageScope() ?? undefined;
       if (v === undefined)
         return parts.length > 1 || st.chain.length > 0 ? { missing: true } : undefined;
+    } else if (head === "site_text") {
+      v = this.env.lists?.siteTextScope();
+      if (v === undefined) return { missing: true };
     } else {
       for (let k = st.chain.length - 1; k >= 0 && v === undefined; k -= 1) {
         v = st.chain[k]?.entry.get(head);
@@ -251,8 +265,8 @@ class SectionRenderer {
     }
     if ("missing" in v) {
       const marker =
-        t.name.split(".")[0]?.toLowerCase() === "page" && this.env.lists === undefined
-          ? "list-context-unavailable:page"
+        isContextHead(t.name) && this.env.lists === undefined
+          ? `list-context-unavailable:${contextHead(t.name)}`
           : this.notDeclared(t.name, st);
       return this.raw(source, marker);
     }
@@ -321,8 +335,8 @@ class SectionRenderer {
     if (v !== undefined) {
       if ("missing" in v) {
         const marker =
-          t.name.split(".")[0] === "page" && this.env.lists === undefined
-            ? "list-context-unavailable:page"
+          isContextHead(t.name) && this.env.lists === undefined
+            ? `list-context-unavailable:${contextHead(t.name)}`
             : this.notDeclared(t.name, st);
         return this.raw(source, marker);
       }

package/src/theme-importers/__tests__/proto-pollution.test.ts

@@ -10,6 +10,7 @@
 import { describe, expect, it } from "bun:test";
 import { isUnsafeKey } from "../../safe-keys.js";
 import { applyDtcgWrites, removeDtcgPath } from "../../themes.js";
+import { UnknownTokenName } from "../../themes-errors.js";
 import { importTailwind } from "../tailwind.js";
 
 describe("isUnsafeKey", () => {
@@ -41,10 +42,19 @@ describe("importTailwind prototype-pollution guard (S5)", () => {
 });
 
 describe("applyDtcgWrites / setLeafAtPath path guard (S5)", () => {
-  it("rejects a write whose path contains __proto__ (no pollution, no write)", () => {
-    const out = applyDtcgWrites({}, { "a.__proto__.polluted": "x" }, {});
+  it("refuses a write whose path contains __proto__, naming the path (no pollution)", () => {
+    expect(() => applyDtcgWrites({}, { "a.__proto__.polluted": "x" }, {})).toThrow(
+      /UnknownTokenName: cannot infer canonical path for 'a\.__proto__\.polluted'/,
+    );
     expect(({} as Record<string, unknown>).polluted).toBeUndefined();
-    expect(out).not.toHaveProperty("a");
+  });
+
+  it("refuses constructor/prototype segments, including as the leaf", () => {
+    expect(() => applyDtcgWrites({}, { "color.constructor": "#fff" }, {})).toThrow(
+      UnknownTokenName,
+    );
+    expect(() => applyDtcgWrites({}, { "prototype.x": "#fff" }, {})).toThrow(UnknownTokenName);
+    expect(({} as Record<string, unknown>).x).toBeUndefined();
   });
 
   it("still applies a legitimate dotted write", () => {

package/src/theme-render-sanitize.test.ts

@@ -38,6 +38,14 @@ describe("renderThemeCss CSS-token sanitization (S6)", () => {
     expect(css).not.toContain("-->");
   });
 
+  it("drops every < and > in one pass, so no nesting re-creates a breakout", () => {
+    for (const hostile of ["<</style>/style>", "<<!--!---->>", "</sty</style>le>", "a--!>b"]) {
+      const css = renderThemeCss(fontDoc(hostile));
+      expect(css).not.toMatch(/[<>]/);
+      expect(css.toLowerCase()).not.toContain("</style");
+    }
+  });
+
   it("leaves a normal fontFamily untouched", () => {
     const css = renderThemeCss(fontDoc("Inter, sans-serif"));
     expect(css).toContain("Inter, sans-serif");

package/src/theme-render.ts

@@ -519,16 +519,17 @@ function asString(value: unknown): string {
  * CSS values are otherwise unrestricted in character set (font-family
  * names legitimately contain quotes, commas, parens, hyphens), so we
  * don't HTML-encode broadly — that would break perfectly-valid
- * `font-family: "Segoe UI", sans-serif` declarations. Instead, scrub
- * the two sequences that let an attacker break out of the surrounding
- * `<style>…</style>` context:
+ * `font-family: "Segoe UI", sans-serif` declarations. Instead, drop the
+ * single characters that let a value leave its context:
  *
- *   - `</style` (case-insensitive) — premature end-tag would close
- *     the style block and let everything after it parse as HTML
- *     (`fontFamily: "Inter</style><script>alert(1)</script>"`).
- *   - `<!--` / `-->` — CDO/CDC tokens; some HTML parsers treat them
- *     specially inside `<style>` and they're never valid in a real
- *     CSS value anyway.
+ *   - `<` and `>` — every way out of the surrounding `<style>…</style>`
+ *     starts with one (`</style`, `<!--`, `-->`, `--!>`), and no color,
+ *     dimension, shadow or font name contains them. Removing single
+ *     characters cannot re-create a removed sequence, so one pass is
+ *     complete (a sequence-based scrub needs a fixed-point loop, which
+ *     CodeQL's js/incomplete-multi-character-sanitization cannot see).
+ *   - `;`, `{`, `}` — they would end the declaration or the rule and
+ *     inject CSS of the value's choosing.
  *
  * The themeColorToken / themeDimensionToken Zod regexes already
  * constrain those token types to character sets that exclude `<`, so
@@ -536,21 +537,5 @@ function asString(value: unknown): string {
  * (`typography.X.fontFamily`, `$description` if it ever lands in CSS).
  */
 function sanitizeCssTokenValue(value: string): string {
-  // Run to a fixed point: removing one sequence can re-create another
-  // (e.g. `<!--</style>-->` → `</style` only appears after the comment
-  // tokens go), which a single pass would leave behind (CodeQL
-  // js/incomplete-multi-character-sanitization). `--!>` is the HTML5
-  // alternative comment-close and must be scrubbed alongside `-->`
-  // (CodeQL js/bad-tag-filter).
-  let out = value;
-  let prev: string;
-  do {
-    prev = out;
-    out = out
-      .replace(/<\/style/gi, "")
-      .replace(/<!--/g, "")
-      .replace(/--!?>/g, "")
-      .replace(/[;{}]/g, "");
-  } while (out !== prev);
-  return out;
+  return value.replace(/[<>;{}]/g, "");
 }

package/src/themes.ts

@@ -880,21 +880,26 @@ function setLeafAtPath(doc: Record<string, unknown>, path: string, leaf: unknown
   const parts = path.split(".");
   // The dotted path comes from the caller's `writes` map (form / AI input),
   // so a segment like `__proto__` or `constructor` would let the walk below
-  // (`cur[k] = {}`, `cur[last] = leaf`) pollute the prototype chain (CodeQL
-  // js/prototype-pollution-utility). Reject the whole write on any unsafe
-  // segment rather than partially applying it.
-  if (parts.some(isUnsafeKey)) return;
+  // (`cur[k] = {}`, `cur[last] = leaf`) pollute the prototype chain. No
+  // token is named that, so the write fails loudly instead of being dropped
+  // (CLAUDE.md §2). The comparison sits inline at the assignment so CodeQL's
+  // js/prototype-pollution-utility sees the guard.
   let cur: Record<string, unknown> = doc;
-  for (let i = 0; i < parts.length - 1; i++) {
+  for (let i = 0; i < parts.length; i++) {
     const k = parts[i];
     if (!k) continue;
+    if (k === "__proto__" || k === "constructor" || k === "prototype") {
+      throw new UnknownTokenName(path, []);
+    }
+    if (i === parts.length - 1) {
+      cur[k] = leaf;
+      return;
+    }
     if (cur[k] === undefined || cur[k] === null || typeof cur[k] !== "object") {
       cur[k] = {};
     }
     cur = cur[k] as Record<string, unknown>;
   }
-  const last = parts[parts.length - 1];
-  if (last) cur[last] = leaf;
 }
 
 /**

package/src/version.ts

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