@caelo-cms/shared 0.10.53 → 0.10.55

package/src/template-balance.ts

@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Keep an HTML fragment from closing a `<template>` it is placed inside.
+ *
+ * The composer parks a consent-withheld module inside an inert
+ * `<template data-caelo-deferred-content>` (#450). In the HTML parser the
+ * only thing that ends a template from within is a `</template` end tag
+ * (an ASCII-case-insensitive literal; tag names never decode character
+ * references), so a fragment with an unmatched one would put the rest of
+ * the module live on the page before the visitor consents. Balanced nested
+ * templates are legitimate markup and must survive, which rules out
+ * escaping every `</template`.
+ *
+ * The walk is FAIL-CLOSED: it does not have to agree with the browser's
+ * tokenizer and tree builder everywhere, only in one direction. Every
+ * `</template` it does not keep as the close of a template it counted is
+ * rewritten — inside tags, attribute values, comments and raw text too,
+ * because those are exactly the places where a hand-written walk and the
+ * HTML parser can disagree (abrupt comments like `<!-->`, raw-text
+ * elements that are ordinary elements in SVG/MathML, ...). A template is
+ * only counted where it is certainly an HTML `<template>`: never inside
+ * `<svg>` / `<math>`, where the tree builder can pop a foreign `template`
+ * element implicitly (e.g. by `</svg>`) and a following `</template>`
+ * would then close the wrapper. When the walk and the browser disagree,
+ * the worst outcome is a template that stays open and keeps the rest of
+ * the page inert — never withheld content running before consent.
+ *
+ * Rewrites: `&lt;/template` in markup, attribute values and comments (the
+ * same characters once decoded or shown); `<\/template` in `<script>` /
+ * `<style>` text (the same string in JS and CSS). Templates the fragment
+ * leaves open are closed at its end so the wrapper's own `</template>`
+ * closes the wrapper.
+ */
+
+/** Elements whose content the HTML tokenizer reads as text until their end tag. */
+const RAW_TEXT_ELEMENTS = new Set([
+  "script",
+  "style",
+  "textarea",
+  "title",
+  "xmp",
+  "iframe",
+  "noembed",
+  "noframes",
+  "noscript",
+]);
+
+/** Raw-text elements whose content is JS or CSS, where `<\/` keeps the meaning. */
+const CODE_ELEMENTS = new Set(["script", "style"]);
+
+/** Roots of foreign (SVG / MathML) content. */
+const FOREIGN_ROOTS = new Set(["svg", "math"]);
+
+/** The HTML tokenizer's whitespace (not JS `\s`, which also matches U+00A0 etc.). */
+const HTML_WS = /[\t\n\f\r ]/;
+
+/** A tag name ends at HTML whitespace, `/` or `>`. */
+const TAG_NAME_END = /[\t\n\f\r />]/;
+
+const TEMPLATE_CLOSE_RE = /<\/template/gi;
+
+/** Neutralize every `</template` in markup / attribute / comment text. */
+function neutralizeMarkup(s: string): string {
+  return s.replace(TEMPLATE_CLOSE_RE, (m) => `&lt;${m.slice(1)}`);
+}
+
+/** Neutralize every `</template` in JS / CSS text. */
+function neutralizeCode(s: string): string {
+  return s.replace(TEMPLATE_CLOSE_RE, (m) => `<\\${m.slice(1)}`);
+}
+
+/**
+ * Rewrite `<!--` in script text to `<\!--`. A `<!--` puts the HTML
+ * tokenizer's script data into its escaped states, where a nested
+ * `<script` makes the next `</script>` NOT end the element — the browser's
+ * script would then run past the end this walk found. Without `<!--` both
+ * agree. `\!` is `!` in JS strings and non-unicode regexes.
+ */
+function neutralizeScriptEscapes(s: string): string {
+  return s.replaceAll("<!--", () => "<\\!--");
+}
+
+/** ASCII-only lowercase: same length as the input, like the HTML tokenizer. */
+function asciiLower(s: string): string {
+  return s.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
+}
+
+/** Neutralize unmatched `</template>` closes and close templates left open. */
+export function balanceTemplateCloses(html: string): string {
+  let out = "";
+  let depth = 0;
+  let foreignDepth = 0;
+  let i = 0;
+  while (i < html.length) {
+    const lt = html.indexOf("<", i);
+    if (lt === -1) {
+      out += html.slice(i);
+      break;
+    }
+    out += html.slice(i, lt);
+    if (html.startsWith("<!--", lt)) {
+      const end = commentEnd(html, lt + 4);
+      out += neutralizeMarkup(html.slice(lt, end));
+      i = end;
+      continue;
+    }
+    if (html[lt + 1] === "!" || html[lt + 1] === "?") {
+      // Doctype / CDATA / bogus comment: text up to the next `>`.
+      const end = html.indexOf(">", lt);
+      const stop = end === -1 ? html.length : end + 1;
+      out += neutralizeMarkup(html.slice(lt, stop));
+      i = stop;
+      continue;
+    }
+    const isEnd = html[lt + 1] === "/";
+    const nameStart = lt + (isEnd ? 2 : 1);
+    if (!/[A-Za-z]/.test(html[nameStart] ?? "")) {
+      // Not a tag (`a < b`, `</ >`): the `<` is text.
+      out += "<";
+      i = lt + 1;
+      continue;
+    }
+    let nameEnd = nameStart;
+    while (nameEnd < html.length && !TAG_NAME_END.test(html[nameEnd] ?? "")) nameEnd++;
+    const name = asciiLower(html.slice(nameStart, nameEnd));
+    const tagEnd = tagClose(html, nameEnd);
+    const tag = html.slice(lt, tagEnd);
+    const selfClosing = tag.endsWith("/>");
+    i = tagEnd;
+    if (isEnd) {
+      if (name === "template" && depth > 0 && foreignDepth === 0) {
+        depth--;
+        out += `</template${neutralizeMarkup(tag.slice("</template".length))}`;
+        continue;
+      }
+      if (FOREIGN_ROOTS.has(name) && foreignDepth > 0) foreignDepth--;
+      out += neutralizeMarkup(tag);
+      continue;
+    }
+    out += neutralizeMarkup(tag);
+    if (foreignDepth > 0) {
+      // Foreign content: no raw-text elements, no HTML templates counted.
+      if (FOREIGN_ROOTS.has(name) && !selfClosing) foreignDepth++;
+      continue;
+    }
+    if (name === "template") {
+      depth++;
+    } else if (FOREIGN_ROOTS.has(name)) {
+      if (!selfClosing) foreignDepth++;
+    } else if (RAW_TEXT_ELEMENTS.has(name)) {
+      const close = rawTextEnd(html, tagEnd, name);
+      const body = html.slice(tagEnd, close);
+      out +=
+        name === "script"
+          ? neutralizeScriptEscapes(neutralizeCode(body))
+          : CODE_ELEMENTS.has(name)
+            ? neutralizeCode(body)
+            : neutralizeMarkup(body);
+      i = close;
+    }
+  }
+  return out + "</template>".repeat(depth);
+}
+
+/**
+ * Index just past the comment whose `<!--` ends at `from`. Per the HTML
+ * tokenizer `<!-->` and `<!--->` are complete (empty) comments; otherwise
+ * the comment ends at `-->` or `--!>`, or at the end of input.
+ */
+function commentEnd(html: string, from: number): number {
+  if (html[from] === ">") return from + 1;
+  if (html.startsWith("->", from)) return from + 2;
+  const m = /--!?>/g;
+  m.lastIndex = from;
+  const hit = m.exec(html);
+  return hit === null ? html.length : hit.index + hit[0].length;
+}
+
+/**
+ * Index just past the `>` that ends the tag whose name ends at `from`.
+ * Quoted attribute values may hold `>`; they are only quotes after `=`.
+ */
+function tagClose(html: string, from: number): number {
+  let i = from;
+  while (i < html.length) {
+    const ch = html[i];
+    if (ch === ">") return i + 1;
+    if (ch === "=") {
+      i++;
+      while (i < html.length && HTML_WS.test(html[i] ?? "")) i++;
+      const quote = html[i];
+      if (quote === '"' || quote === "'") {
+        const close = html.indexOf(quote, i + 1);
+        if (close === -1) return html.length;
+        i = close + 1;
+        continue;
+      }
+      continue;
+    }
+    i++;
+  }
+  return html.length;
+}
+
+/** Index where the raw-text element `name`'s end tag starts, or the end. */
+function rawTextEnd(html: string, from: number, name: string): number {
+  const lower = asciiLower(html);
+  let at = lower.indexOf(`</${name}`, from);
+  while (at !== -1) {
+    const next = html[at + 2 + name.length];
+    if (next === undefined || TAG_NAME_END.test(next)) return at;
+    at = lower.indexOf(`</${name}`, at + 1);
+  }
+  return html.length;
+}

package/src/template-engine.ts

@@ -41,6 +41,12 @@
  * v0.11.1 (issue #76): `theme-asset-unbound:<slot>` for the four
  * `{{theme_<slot>_url}}` placeholders when the active theme's asset
  * slot isn't bound.
+ * Epic #724: `link-target-missing:page/<id>` / `…:media/<id>` for an
+ * internal reference (`caelo:page/<id>`, `caelo:media/<id>`) whose
+ * target does not exist, `link-resolver-unavailable:<kind>/<id>` for
+ * one rendered without a resolver, and `link-ref-malformed:<text>` for
+ * text that starts like a reference but breaks the grammar (see
+ * `link-refs.ts`).
  * The chat-runner diag pass + editor missing-content surface read
  * these literal strings; any rename is a silent regression for them.
  *
@@ -63,6 +69,7 @@
 
 import Mustache from "mustache";
 import { MODULE_FIELD_SECTION_KINDS, type ModuleFieldKind } from "./content.js";
+import { type LinkResolver, resolveLinkRefsInHtml } from "./link-refs.js";
 import { stripCdataGuards } from "./strip-cdata.js";
 
 // Override Mustache's default HTML escape — module HTML substitutes
@@ -139,6 +146,16 @@ export interface RenderTemplateInput {
     readonly favicon: string | null;
     readonly socialShare: string | null;
   };
+  /**
+   * Epic #724 — turns internal references (`caelo:page/<id>`,
+   * `caelo:media/<id>`) into URLs for the page being rendered. Applied
+   * to the fully substituted output, so a reference resolves wherever it
+   * came from: module HTML attributes, a field value, a field default, a
+   * link-list item, rich text. A missing target stays raw and pushes
+   * `link-target-missing:<kind>/<id>`; with no resolver every reference
+   * pushes `link-resolver-unavailable:<kind>/<id>` (loud, never empty).
+   */
+  readonly linkResolver?: LinkResolver;
 }
 
 export interface RenderTemplateOutput {
@@ -373,6 +390,12 @@ export function renderTemplate(input: RenderTemplateInput): RenderTemplateOutput
     final = final.split(sentinel).join(original);
   }
 
+  // 6. Resolve internal references (epic #724). Last, so values,
+  //    defaults and list items substituted above are covered; nested
+  //    partials arrive already resolved by their own render, and a
+  //    resolved URL never matches the reference grammar again.
+  final = resolveLinkRefsInHtml(final, input.linkResolver, missing);
+
   return { html: final, missingSlots: missing };
 }
 

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

@@ -42,4 +42,44 @@ describe("renderThemeCss CSS-token sanitization (S6)", () => {
     const css = renderThemeCss(fontDoc("Inter, sans-serif"));
     expect(css).toContain("Inter, sans-serif");
   });
+
+  it("scrubs </style> from string shadow tokens", () => {
+    const doc = {
+      shadow: {
+        card: { $value: "0 2px 4px #000</style><script>alert(1)</script>", $type: "shadow" },
+      },
+    } as unknown as ThemeDocument;
+    const css = renderThemeCss(doc);
+    expect(css.toLowerCase()).not.toContain("</style");
+  });
+
+  it("rejects selectors containing CSS block delimiters or </style>", () => {
+    expect(() => renderThemeCss(fontDoc("Inter"), { selector: ":root{color:red}body" })).toThrow(
+      /Invalid CSS selector/,
+    );
+    expect(() => renderThemeCss(fontDoc("Inter"), { selector: "</style><script>" })).toThrow(
+      /Invalid CSS selector/,
+    );
+  });
+
+  it("escapes token keys outside CSS identifier characters instead of letting them end the rule", () => {
+    const doc = {
+      color: {
+        "primary;--x:1}</style><script>": { $type: "color", $value: "#000" },
+        valid: { $type: "color", $value: "#fff" },
+      },
+    } as unknown as ThemeDocument;
+    const css = renderThemeCss(doc);
+    expect(css.toLowerCase()).not.toContain("</style");
+    expect(css).not.toContain("}</");
+    expect(css).toContain("--color-primary\\3b --x\\3a 1\\7d \\3c \\2f style\\3e ");
+    expect(css).toContain("--color-valid:#fff;");
+  });
+
+  it("keeps non-ASCII token names as they are (valid CSS identifiers)", () => {
+    const doc = {
+      color: { grün: { $type: "color", $value: "#0a0" } },
+    } as unknown as ThemeDocument;
+    expect(renderThemeCss(doc)).toContain("--color-grün:#0a0;");
+  });
 });

package/src/theme-render.ts

@@ -34,9 +34,13 @@ import { type AnyThemeToken, flattenTokens, type ThemeDocument } from "./themes.
 
 /** Renderer-level error for cyclic / unresolved aliases. */
 export class ThemeRenderError extends Error {
-  readonly kind: "cyclic-alias" | "missing-alias";
+  readonly kind: "cyclic-alias" | "missing-alias" | "invalid-selector";
   readonly path: string;
-  constructor(kind: "cyclic-alias" | "missing-alias", path: string, message: string) {
+  constructor(
+    kind: "cyclic-alias" | "missing-alias" | "invalid-selector",
+    path: string,
+    message: string,
+  ) {
     super(message);
     this.name = "ThemeRenderError";
     this.kind = kind;
@@ -74,6 +78,13 @@ export interface RenderThemeCssOptions {
  */
 export function renderThemeCss(tokens: ThemeDocument, options: RenderThemeCssOptions = {}): string {
   const selector = options.selector ?? ":root";
+  if (/[{};]|<\/style|<!--|--!?>/i.test(selector)) {
+    throw new ThemeRenderError(
+      "invalid-selector",
+      selector,
+      `Invalid CSS selector for theme rendering: '${selector}'`,
+    );
+  }
   const flat = flattenTokens(tokens);
   const resolveCache = new Map<string, unknown>();
   const lightLines: string[] = [];
@@ -337,6 +348,25 @@ function lookupPath(doc: ThemeDocument, path: string): AnyThemeToken | null {
 // Per-category CSS emission
 // ────────────────────────────────────────────────────────────────────
 
+/**
+ * Serialize a token-path segment as part of a CSS custom-property name, the
+ * way `CSS.escape` does: ASCII letters, digits, `-`, `_` and every
+ * non-ASCII character stay as they are (so `color.grün` is still
+ * `--color-grün`), anything else becomes a hex escape. A theme key can
+ * therefore never end the declaration, the rule, or the surrounding
+ * `<style>` element.
+ */
+function escapeCssIdentPart(part: string): string {
+  let out = "";
+  for (const ch of part) {
+    const cp = ch.codePointAt(0) ?? 0;
+    if (cp === 0) out += "\\fffd ";
+    else if (/[A-Za-z0-9_-]/.test(ch) || cp >= 0x80) out += ch;
+    else out += `\\${cp.toString(16)} `;
+  }
+  return out;
+}
+
 function emitTokenLines(
   category: string,
   path: string,
@@ -358,10 +388,12 @@ function emitTokenLines(
   // every category (color/spacing/radius/etc.) so any future
   // DTCG-group-with-DEFAULT-alias works the same way.
   const restRaw = path.slice(category.length + 1);
-  const rest = restRaw.endsWith(".DEFAULT")
-    ? restRaw.slice(0, -".DEFAULT".length).replace(/\./g, "-")
-    : restRaw.replace(/\./g, "-");
-  const baseName = `--${category === "ease" ? "ease" : category}-${rest}`;
+  const rest = escapeCssIdentPart(
+    restRaw.endsWith(".DEFAULT")
+      ? restRaw.slice(0, -".DEFAULT".length).replace(/\./g, "-")
+      : restRaw.replace(/\./g, "-"),
+  );
+  const baseName = `--${category === "ease" ? "ease" : escapeCssIdentPart(category)}-${rest}`;
 
   switch (category) {
     case "color":
@@ -430,9 +462,9 @@ function emitTypography(rest: string, value: unknown, out: string[]): void {
 
 function emitShadow(baseName: string, value: unknown, out: string[]): void {
   // Literal CSS box-shadow string (the tolerant `shadowValueString` form).
-  // Emit verbatim — the DTCG object form is expanded below.
+  // Scrubbed through sanitizeCssTokenValue like every other token value.
   if (typeof value === "string") {
-    const s = value.trim();
+    const s = sanitizeCssTokenValue(value.trim());
     if (s.length > 0) out.push(`${baseName}:${s};`);
     return;
   }

package/src/version.ts

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