@caelo-cms/shared 0.10.67 → 0.10.69

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

@@ -211,6 +211,83 @@ describe("renderModuleWithContent — nested module slots", () => {
   });
 });
 
+describe("renderModuleWithContent — content braces through nesting (#1053)", () => {
+  it("a nested richtext value with {{Page URL}} reaches the page literally", () => {
+    const resolver = buildResolver(
+      [
+        {
+          moduleId: PARENT_MOD_ID,
+          slug: "parent",
+          html: "<section>{{>child}}</section>",
+          css: "",
+          js: "",
+          fields: [{ name: "child", kind: "module" }],
+        },
+        {
+          moduleId: CHILD_MOD_ID,
+          slug: "child",
+          html: "<div>{{{body_html}}}</div>",
+          css: "",
+          js: "",
+          fields: [{ name: "body_html", kind: "richtext" }],
+        },
+      ],
+      [
+        {
+          id: PARENT_CI_ID,
+          moduleId: PARENT_MOD_ID,
+          values: { child: { moduleId: CHILD_MOD_ID, contentInstanceId: CHILD_CI_ID } },
+          deletedAt: null,
+        },
+        {
+          id: CHILD_CI_ID,
+          moduleId: CHILD_MOD_ID,
+          values: { body_html: "<code>link_en.href = '{{Page URL}}';</code>" },
+          deletedAt: null,
+        },
+      ],
+    );
+    const r = renderModuleWithContent(PARENT_MOD_ID, PARENT_CI_ID, resolver);
+    expect(r.html).toBe(
+      `<section><div ${tag(CHILD_MOD_ID)}><code>link_en.href = '{{Page URL}}';</code></div></section>`,
+    );
+    expect(r.missingSlots).toEqual([]);
+  });
+});
+
+describe("renderModuleWithContent — empty optional module field (#1041)", () => {
+  it("an unset or null `module` field renders an empty slot without a marker", () => {
+    for (const values of [{}, { after: null }]) {
+      const resolver = buildResolver(
+        [
+          {
+            moduleId: PARENT_MOD_ID,
+            slug: "card-grid",
+            html: "<section><h2>{{title}}</h2>{{>after}}</section>",
+            css: "",
+            js: "",
+            fields: [
+              { name: "title", kind: "text" },
+              { name: "after", kind: "module" },
+            ],
+          },
+        ],
+        [
+          {
+            id: PARENT_CI_ID,
+            moduleId: PARENT_MOD_ID,
+            values: { title: "T", ...values },
+            deletedAt: null,
+          },
+        ],
+      );
+      const r = renderModuleWithContent(PARENT_MOD_ID, PARENT_CI_ID, resolver);
+      expect(r.html).toBe("<section><h2>T</h2></section>");
+      expect(r.missingSlots).toEqual([]);
+    }
+  });
+});
+
 describe("renderModuleWithContent — list-of-primitive slots", () => {
   it("text-list iterates {{.}} per string element", () => {
     const resolver = buildResolver(

package/src/phase-timer.test.ts

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { PhaseTimer, phaseTimingSchema } from "./phase-timer.js";
+
+function clock(...ticks: number[]): () => number {
+  let i = 0;
+  return () => {
+    const t = ticks[Math.min(i, ticks.length - 1)];
+    i += 1;
+    return t ?? 0;
+  };
+}
+
+describe("PhaseTimer", () => {
+  it("each lap measures the time since the previous one", () => {
+    const t = new PhaseTimer(clock(0, 10.4, 35.6, 40));
+    t.lap("load");
+    t.lap("render");
+    expect(t.phases()).toEqual([
+      { phase: "load", ms: 10 },
+      { phase: "render", ms: 25 },
+    ]);
+    expect(t.totalMs()).toBe(40);
+  });
+
+  it("includes steps timed elsewhere under a prefix, before the lap that spans them", () => {
+    const t = new PhaseTimer(clock(0, 120));
+    t.include("generator", [
+      { phase: "compose", ms: 80 },
+      { phase: "media", ms: 30 },
+    ]);
+    t.lap("generator");
+    expect(t.phases()).toEqual([
+      { phase: "generator.compose", ms: 80 },
+      { phase: "generator.media", ms: 30 },
+      { phase: "generator", ms: 120 },
+    ]);
+  });
+
+  it("phases() is a copy and every entry passes the wire schema", () => {
+    const t = new PhaseTimer(clock(0, 5));
+    t.lap("x");
+    t.phases().pop();
+    expect(t.phases()).toHaveLength(1);
+    for (const p of t.phases()) expect(phaseTimingSchema.parse(p)).toEqual(p);
+  });
+});

package/src/phase-timer.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Wall-clock timings of the steps of one long operation (a Stage: chat
+ * merge, generator passes, upload, parity fingerprint, preview selection).
+ * The generator subprocess and the admin share this shape, so the
+ * generator's phases arrive in the admin's list prefixed and in order.
+ *
+ * Laps instead of wrapped callbacks: `lap("x")` closes the step that ran
+ * since the previous lap, so a long function gets one line per boundary
+ * and keeps its control flow (early throws, shared locals) as it is.
+ */
+
+import { z } from "zod";
+
+/** One finished step: its name and how long it took, in whole milliseconds. */
+export const phaseTimingSchema = z.object({
+  phase: z.string().min(1),
+  ms: z.number().int().nonnegative(),
+});
+export type PhaseTiming = z.infer<typeof phaseTimingSchema>;
+
+export class PhaseTimer {
+  readonly #now: () => number;
+  readonly #phases: PhaseTiming[] = [];
+  readonly #start: number;
+  #last: number;
+
+  /** @param now clock in milliseconds; injectable for tests. */
+  constructor(now: () => number = () => performance.now()) {
+    this.#now = now;
+    this.#start = now();
+    this.#last = this.#start;
+  }
+
+  /** Close the step that ran since the previous lap (or construction) as `phase`. */
+  lap(phase: string): void {
+    const t = this.#now();
+    this.#phases.push({ phase, ms: Math.round(t - this.#last) });
+    this.#last = t;
+  }
+
+  /**
+   * Append steps timed elsewhere (the generator subprocess, a publisher)
+   * as `<prefix>.<phase>`. They ran inside the current lap, so the lap that
+   * closes it still measures the whole span (the remainder is the overhead
+   * around them, e.g. spawning the subprocess).
+   */
+  include(prefix: string, phases: readonly PhaseTiming[]): void {
+    for (const p of phases) this.#phases.push({ phase: `${prefix}.${p.phase}`, ms: p.ms });
+  }
+
+  /** Milliseconds since construction. */
+  totalMs(): number {
+    return Math.round(this.#now() - this.#start);
+  }
+
+  /** The steps so far, in the order they finished. */
+  phases(): PhaseTiming[] {
+    return [...this.#phases];
+  }
+}

package/src/run-batched.test.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { runBatched } from "./run-batched.js";
+
+describe("runBatched", () => {
+  it("runs every item with at most `parallelism` in flight", async () => {
+    let inFlight = 0;
+    let peak = 0;
+    const done: number[] = [];
+    await runBatched([1, 2, 3, 4, 5, 6, 7], 3, async (n) => {
+      inFlight += 1;
+      peak = Math.max(peak, inFlight);
+      await new Promise((r) => setTimeout(r, 2));
+      done.push(n);
+      inFlight -= 1;
+    });
+    expect(done.sort()).toEqual([1, 2, 3, 4, 5, 6, 7]);
+    expect(peak).toBe(3);
+  });
+
+  it("stops starting new items after the first failure and rejects with it", async () => {
+    const started: number[] = [];
+    await expect(
+      runBatched([1, 2, 3, 4, 5, 6], 2, async (n) => {
+        started.push(n);
+        if (n === 2) throw new Error("boom 2");
+        await new Promise((r) => setTimeout(r, 5));
+      }),
+    ).rejects.toThrow("boom 2");
+    expect(started.length).toBeLessThan(6);
+  });
+
+  it("handles an empty list and refuses a non-positive parallelism", async () => {
+    await runBatched([], 4, async () => {
+      throw new Error("never");
+    });
+    await expect(runBatched([1], 0, async () => {})).rejects.toThrow("positive integer");
+  });
+});

package/src/run-batched.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Run `worker` over `items` with at most `parallelism` in flight, in item
+ * order. File and network I/O of a build (page writes, the `current/`
+ * mirror, uploads) goes through this: one-at-a-time costs a round trip per
+ * file, unbounded `Promise.all` exhausts file descriptors and memory on
+ * large sites.
+ *
+ * The first rejection rejects the whole call; workers already running
+ * finish, no new item starts.
+ */
+export async function runBatched<T>(
+  items: ReadonlyArray<T>,
+  parallelism: number,
+  worker: (item: T) => Promise<void>,
+): Promise<void> {
+  if (!Number.isInteger(parallelism) || parallelism < 1) {
+    throw new Error(`runBatched: parallelism must be a positive integer, got ${parallelism}`);
+  }
+  let cursor = 0;
+  let failed = false;
+  const next = async (): Promise<void> => {
+    while (!failed && cursor < items.length) {
+      const i = cursor++;
+      try {
+        // biome-ignore lint/style/noNonNullAssertion: cursor < length checked
+        await worker(items[i]!);
+      } catch (e) {
+        failed = true;
+        throw e;
+      }
+    }
+  };
+  const workers: Promise<void>[] = [];
+  const n = Math.min(parallelism, items.length);
+  for (let i = 0; i < n; i++) workers.push(next());
+  await Promise.all(workers);
+}

package/src/seo.test.ts

@@ -208,6 +208,56 @@ describe("injectSeoIntoHead", () => {
     expect(out).toContain("<title>PageTitle</title>\n</HEAD>");
     expect(out).toContain("<svg><title>IconTitle</title></svg>");
   });
+
+  // #1017 — the block goes early, before the inline theme CSS.
+  const THEME = '<style data-source="theme">body{}</style><link rel="stylesheet" href="/a.css">';
+
+  it("goes after charset and viewport, before the first style and stylesheet", () => {
+    const html = `<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width">${THEME}<title>Old</title></head><body><svg><title>Icon</title></svg></body></html>`;
+    const out = injectSeoIntoHead(html, "<title>Page</title>");
+    expect(out).toStartWith(
+      '<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width">\n<title>Page</title>\n<style',
+    );
+    expect(out.indexOf("<title>Page</title>")).toBeLessThan(out.indexOf("<style"));
+    expect(out.indexOf("<title>Page</title>")).toBeLessThan(out.indexOf('<link rel="stylesheet"'));
+    expect(out).not.toContain("Old");
+    expect(out).toContain("<svg><title>Icon</title></svg>");
+  });
+
+  it("goes after the charset when there is no viewport", () => {
+    const out = injectSeoIntoHead(
+      `<html><head><meta charset="utf-8">${THEME}</head><body></body></html>`,
+      "<title>Page</title>",
+    );
+    expect(out).toStartWith('<html><head><meta charset="utf-8">\n<title>Page</title>\n<style');
+  });
+
+  it("goes right after <head> when there is neither", () => {
+    const out = injectSeoIntoHead(
+      `<html><head lang="en">${THEME}</head><body></body></html>`,
+      "<title>Page</title>",
+    );
+    expect(out).toStartWith('<html><head lang="en">\n<title>Page</title>\n<style');
+  });
+
+  it("ignores a viewport-looking meta in the body", () => {
+    const out = injectSeoIntoHead(
+      '<html><head><meta charset="utf-8"></head><body><meta name="viewport"></body></html>',
+      "<title>Page</title>",
+    );
+    expect(out).toStartWith('<html><head><meta charset="utf-8">\n<title>Page</title>');
+  });
+
+  it("ignores meta tags inside a comment or a script string", () => {
+    const script = `<script>const sample = '<meta name="viewport" content="width=device-width">';</script>`;
+    const comment = '<!-- <meta name="viewport" content="x"> -->';
+    const html = `<html><head><meta charset="utf-8">${comment}${script}${THEME}</head><body></body></html>`;
+    const out = injectSeoIntoHead(html, "<title>Page</title>");
+    expect(out).toStartWith('<html><head><meta charset="utf-8">\n<title>Page</title>\n<!--');
+    // Comment and script come through byte-for-byte, nothing inserted in them.
+    expect(out).toContain(comment);
+    expect(out).toContain(script);
+  });
 });
 
 describe("schemas", () => {

package/src/seo.ts

@@ -8,6 +8,7 @@
  */
 
 import { z } from "zod";
+import { blankNonMarkup } from "./html-blank.js";
 import { trimSlashes } from "./url.js";
 
 export const CHANGEFREQ_VALUES = [
@@ -333,11 +334,18 @@ export function renderSeoHead(input: SeoMetaInput): string {
 }
 
 /**
- * Inject `renderSeoHead`'s output just before `</head>`. Replaces any
- * existing `<title>` so the page-level title wins over a layout-
- * supplied default. Pre-existing meta tags from the layout are left
- * alone — authors can still drop e.g. `<meta name="theme-color">` in
- * the layout HTML.
+ * Inject `renderSeoHead`'s output early in `<head>`: right after the last
+ * `<meta charset>` / `<meta name="viewport">`, or right after `<head>`
+ * when the layout has neither (#1017). Layouts inline the theme CSS, so a
+ * block appended before `</head>` put the title tens of kilobytes into
+ * the page, past what byte-limited crawlers and link-preview fetchers
+ * read; charset and viewport stay first, as the HTML spec wants the
+ * charset in the first 1024 bytes.
+ *
+ * Replaces any existing `<title>` so the page-level title wins over a
+ * layout-supplied default. Pre-existing meta tags from the layout are
+ * left alone — authors can still drop e.g. `<meta name="theme-color">`
+ * in the layout HTML.
  */
 export function injectSeoIntoHead(html: string, headBlock: string): string {
   const headCloseMatch = /<\/head\s*>/i.exec(html);
@@ -345,11 +353,35 @@ export function injectSeoIntoHead(html: string, headBlock: string): string {
     const headEnd = headCloseMatch.index;
     // Strip a layout-supplied <title> inside <head> only (never an SVG
     // <title> in <body>); we re-emit the page title in headBlock.
-    const beforeClose = html.slice(0, headEnd).replace(/<title\b[^>]*>[\s\S]*?<\/title>/i, "");
-    const afterClose = html.slice(headEnd);
-    return `${beforeClose}${headBlock}\n${afterClose}`;
+    const head = html.slice(0, headEnd).replace(/<title\b[^>]*>[\s\S]*?<\/title>/i, "");
+    const at = seoInsertionPoint(head);
+    return `${head.slice(0, at)}\n${headBlock}\n${head.slice(at)}${html.slice(headEnd)}`;
   }
   // No closing head tag — prepend the block to the document.
   const titleStripped = html.replace(/<title\b[^>]*>[\s\S]*?<\/title>/i, "");
   return `${headBlock}\n${titleStripped}`;
 }
+
+/**
+ * Where the SEO block goes inside `head` (the document up to `</head>`):
+ * after the last charset / viewport meta of the head, else after the
+ * `<head>` tag, else (a document with `</head>` but no `<head>` tag) at
+ * the end, where it always went.
+ */
+function seoInsertionPoint(head: string): number {
+  // Only real elements count: a meta tag inside a comment or a script
+  // string would otherwise put the block inside that comment or string.
+  const markup = blankNonMarkup(head);
+  const open = /<head\b[^>]*>/i.exec(markup);
+  if (!open) return head.length;
+  const start = open.index + open[0].length;
+  let at = start;
+  const metaRe = /<meta\b[^>]*>/gi;
+  metaRe.lastIndex = start;
+  for (let m = metaRe.exec(markup); m !== null; m = metaRe.exec(markup)) {
+    if (/\bcharset\s*=/i.test(m[0]) || /\bname\s*=\s*["']?viewport\b/i.test(m[0])) {
+      at = m.index + m[0].length;
+    }
+  }
+  return at;
+}

package/src/strip-cdata.test.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MPL-2.0
 
 import { describe, expect, it } from "bun:test";
-import { stripCdataGuards } from "./strip-cdata.js";
+import { stripCdataGuards, unwrapCdataEnvelope } from "./strip-cdata.js";
 
 describe("stripCdataGuards", () => {
   it("leaves clean HTML untouched (fast path)", () => {
@@ -39,3 +39,32 @@ describe("stripCdataGuards", () => {
     expect(stripCdataGuards(html)).toBe(html);
   });
 });
+
+describe("unwrapCdataEnvelope", () => {
+  // Shape of the add_module css the real-AI suite filed (run 39936064709).
+  const css =
+    ".consent-banner {\n  position: fixed;\n}\n@media (max-width: 640px) {\n  .x { width: 100%; }\n}";
+
+  it("decodes a whole-value envelope to its exact body", () => {
+    expect(unwrapCdataEnvelope(`<![CDATA[${css}]]>`)).toBe(css);
+    expect(unwrapCdataEnvelope(`\n  <![CDATA[${css}]]>\n`)).toBe(css);
+  });
+
+  it("leaves values without an enclosing envelope untouched", () => {
+    expect(unwrapCdataEnvelope(css)).toBe(css);
+    const guarded = `/*<![CDATA[*/ ${css} /*]]>*/`;
+    expect(unwrapCdataEnvelope(guarded)).toBe(guarded);
+    const midValue = `.a{} <![CDATA[ .b{} ]]>`;
+    expect(unwrapCdataEnvelope(midValue)).toBe(midValue);
+  });
+
+  it("does not decode two CDATA sections as one envelope", () => {
+    const two = "<![CDATA[.a{}]]> <![CDATA[.b{}]]>";
+    expect(unwrapCdataEnvelope(two)).toBe(two);
+  });
+
+  it("passes non-strings through for the schema to judge", () => {
+    expect(unwrapCdataEnvelope(undefined)).toBeUndefined();
+    expect(unwrapCdataEnvelope(42)).toBe(42);
+  });
+});

package/src/strip-cdata.ts

@@ -48,3 +48,34 @@ export function stripCdataGuards(html: string): string {
   if (!html.includes("CDATA") && !html.includes("]]>")) return html;
   return html.replace(CDATA_GUARDS, "");
 }
+
+const CDATA_ENVELOPE = /^\s*<!\[CDATA\[([\s\S]*)\]\]>\s*$/;
+
+/**
+ * Decode a whole-value `<![CDATA[ … ]]>` envelope around an AI tool
+ * argument that carries source text (module/template/layout html, css, js).
+ *
+ * Why at the tool boundary: tool parameters reach the model through an
+ * XML-shaped encoding, and for long markup strings the model sometimes
+ * escapes the WHOLE value as a CDATA section — a transport envelope, not
+ * content. The parameter descriptions say not to (issue #993's note), yet
+ * the real-AI suite still filed it on add_module css in roughly one run in
+ * seven (e.g. 39654716622 on main, 39936064709, 39971619728). Refusing it
+ * cost a tool round-trip every time and, for template/layout css (which has
+ * no CDATA refusal), stored a stylesheet the browser cannot parse.
+ *
+ * Only an envelope spanning the entire value is decoded, and only when its
+ * body contains no further `]]>` (a single CDATA section cannot). Anything
+ * else — `/*<![CDATA[*\/` guards inside the CSS, a marker mid-value — is
+ * left untouched so the op validator still refuses it loudly (CLAUDE.md §2):
+ * this decodes a malformed encoding of a value the caller did supply; it is
+ * not a fallback for missing data.
+ *
+ * @returns the envelope's body, or the input unchanged.
+ */
+export function unwrapCdataEnvelope(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  const m = CDATA_ENVELOPE.exec(value);
+  if (!m || m[1] === undefined || m[1].includes("]]>")) return value;
+  return m[1];
+}

package/src/template-engine.test.ts

@@ -269,6 +269,90 @@ describe("renderTemplate — single nested {{>name}}", () => {
   });
 });
 
+describe("renderTemplate — empty single module field (#1041)", () => {
+  const moduleField: TemplateField = { name: "after", kind: "module" };
+
+  it("an unset module field renders empty and is not a failure", () => {
+    const r = renderTemplate({
+      html: "<aside>{{>after}}</aside>",
+      fields: [moduleField],
+      contentValues: {},
+      partials: {},
+    });
+    expect(r.html).toBe("<aside></aside>");
+    expect(r.missingSlots).toEqual([]);
+  });
+
+  it("an explicit null module field renders empty and is not a failure", () => {
+    const r = renderTemplate({
+      html: "<aside>{{>after}}</aside>",
+      fields: [moduleField],
+      contentValues: { after: null },
+      partials: {},
+    });
+    expect(r.html).toBe("<aside></aside>");
+    expect(r.missingSlots).toEqual([]);
+  });
+
+  it("a present non-ref value is still module-ref-malformed", () => {
+    const r = renderTemplate({
+      html: "<aside>{{>after}}</aside>",
+      fields: [moduleField],
+      contentValues: { after: { moduleId: "m" } },
+    });
+    expect(r.missingSlots).toEqual(["module-ref-malformed:after"]);
+  });
+});
+
+describe("renderTemplate — literal braces in content are data (#1053)", () => {
+  it("a text-list item keeps a literal {{Page URL}}", () => {
+    const r = renderTemplate({
+      html: "<ul>{{#items}}<li>{{.}}</li>{{/items}}</ul>",
+      fields: [{ name: "items", kind: "text-list" }],
+      contentValues: { items: ["link.href = '{{Page URL}}';", "{{title}}"] },
+    });
+    expect(r.html).toBe("<ul><li>link.href = '{{Page URL}}';</li><li>{{title}}</li></ul>");
+    expect(r.missingSlots).toEqual([]);
+  });
+
+  it("a link-list label is never re-substituted as a placeholder", () => {
+    const r = renderTemplate({
+      html: '<nav>{{#nav}}<a href="{{href}}">{{label}}</a>{{/nav}}</nav>',
+      fields: [{ name: "nav", kind: "link-list" }],
+      contentValues: { nav: [{ label: "{{href}} {{Click URL}}", href: "/x" }] },
+    });
+    expect(r.html).toBe('<nav><a href="/x">{{href}} {{Click URL}}</a></nav>');
+  });
+
+  it("rendered nested module HTML is pasted verbatim, not parsed again", () => {
+    const r = renderTemplate({
+      html: "<section>{{>body}}</section>",
+      fields: [{ name: "body", kind: "module" }],
+      contentValues: { body: { moduleId: "m", contentInstanceId: "c" } },
+      partials: { body: "<code>{{Page URL}}</code>" },
+    });
+    expect(r.html).toBe("<section><code>{{Page URL}}</code></section>");
+  });
+
+  it("a top-level {{{body_html}}} value with braces still renders as written", () => {
+    const r = renderTemplate({
+      html: "<article>{{{body_html}}}</article>",
+      fields: [{ name: "body_html", kind: "richtext" }],
+      contentValues: { body_html: "<p><code>{{Page URL}}</code></p>" },
+    });
+    expect(r.html).toBe("<article><p><code>{{Page URL}}</code></p></article>");
+  });
+
+  it("a non-identifier tag in module HTML stays literal instead of rendering empty", () => {
+    const r = renderTemplate({
+      html: "<script>dataLayer.push({ url: '{{Page URL}}' })</script>",
+      fields: [],
+    });
+    expect(r.html).toBe("<script>dataLayer.push({ url: '{{Page URL}}' })</script>");
+    expect(r.missingSlots).toEqual([]);
+  });
+});
+
 describe("renderTemplate — loud-raw on unknown sections (AC #3)", () => {
   it("unknown {{#unknown}}…{{/unknown}} leaves raw markers + tracks field-not-declared", () => {
     const r = renderTemplate({