@caelo-cms/shared 0.10.68 → 0.10.69

package/src/markup-structure.ts

@@ -244,6 +244,60 @@ export function outermostPatterns(roots: readonly MarkupNode[]): FoundPattern[]
   return found;
 }
 
+/**
+ * Copies of one pattern side by side at which free markup reads as a
+ * hand-written list (#1068): three cards in a row are a list of items, two
+ * may still be a deliberate pair (a before/after, a two-column split).
+ */
+export const MIN_SIBLING_REPEATS = 3;
+
+/** A pattern repeated side by side in one piece of markup. */
+export interface RepeatedSiblings {
+  /** The first copy. */
+  readonly node: MarkupNode;
+  readonly shape: SubtreeShape;
+  /** How many siblings share its signature. */
+  readonly count: number;
+}
+
+/**
+ * Patterns that repeat {@link MIN_SIBLING_REPEATS}+ times as siblings: the
+ * same component written out once per item (83 tool cards in one richtext
+ * value) instead of a list field rendering one module per item. Roots of
+ * the forest that share a parent are siblings too (the free regions of one
+ * rendered module). A repeated set is reported once and not searched
+ * inside; anything else is searched all the way down. Nested module roots
+ * are skipped: their own module owns them.
+ */
+export function repeatedSiblingPatterns(roots: readonly MarkupNode[]): RepeatedSiblings[] {
+  const shapes = new Map<MarkupNode, SubtreeShape>();
+  for (const r of roots) if (r.moduleId === null) shapeTree(r, shapes);
+  const found: RepeatedSiblings[] = [];
+  const visitSiblings = (siblings: readonly MarkupNode[]) => {
+    const bySig = new Map<string, MarkupNode[]>();
+    for (const n of siblings) {
+      if (n.moduleId !== null) continue;
+      const shape = shapes.get(n);
+      if (!shape || !isPattern(shape)) continue;
+      bySig.set(shape.signature, [...(bySig.get(shape.signature) ?? []), n]);
+    }
+    const reported = new Set<MarkupNode>();
+    for (const copies of bySig.values()) {
+      if (copies.length < MIN_SIBLING_REPEATS) continue;
+      const first = copies[0] as MarkupNode;
+      found.push({ node: first, shape: shapes.get(first) as SubtreeShape, count: copies.length });
+      for (const c of copies) reported.add(c);
+    }
+    for (const n of siblings) {
+      if (n.moduleId === null && !reported.has(n)) visitSiblings(n.children);
+    }
+  };
+  const byParent = new Map<MarkupNode | null, MarkupNode[]>();
+  for (const r of roots) byParent.set(r.parent, [...(byParent.get(r.parent) ?? []), r]);
+  for (const group of byParent.values()) visitSiblings(group);
+  return found;
+}
+
 /** The shape of a whole module template (its first element), or null. */
 export function templateShape(templateHtml: string): SubtreeShape | null {
   const root = parseMarkup(stripMustache(templateHtml))[0];

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/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/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({

package/src/template-engine.ts

@@ -187,6 +187,12 @@ const SECTION_RE =
   /\{\{\s*#\s*([a-z][a-z0-9_]*)\s*\}\}((?:(?!\{\{\s*\/\s*\1\s*\}\})[\s\S])*)\{\{\s*\/\s*\1\s*\}\}/g;
 const PARTIAL_RE = /\{\{\s*>\s*([a-z][a-z0-9_]*)\s*\}\}/g;
 const PRIMITIVE_RE = /\{\{\s*([a-zA-Z][a-zA-Z0-9_]*)\s*\}\}/g;
+// A plain tag (no Mustache sigil) of any name, and the identifier test
+// that tells a field placeholder from literal text such as `{{Page URL}}`.
+// No `\s*` before the close: it would overlap `[^{}]*` (polynomial
+// backtracking); the callback trims instead.
+const NON_IDENTIFIER_TAG_RE = /\{\{\s*([^#^/>!&={}\s][^{}]*)\}\}/g;
+const IDENTIFIER_RE = /^[a-zA-Z][a-zA-Z0-9_]*$/;
 
 // Section-dispatch kinds (the engine's `{{#name}}` operand). Imported
 // from content.ts so new list-shaped kinds wire through automatically
@@ -284,6 +290,14 @@ export function renderTemplate(input: RenderTemplateInput): RenderTemplateOutput
   // pattern into their HTML can't break loud-raw restore by
   // intercepting the sentinel for a known-key sentinel — they would
   // have to guess the UUID minted at render time.
+  //
+  // The same sentinels also carry DATA through the render (#1053): every
+  // value the engine pastes into the template before Mustache runs — a
+  // list item, a link label/href, a conditional's `{{.}}`, a plugin list
+  // value, a rendered nested module — is wrapped, so literal `{{…}}` in
+  // content (a GTM `{{Page URL}}` in a code example) is never parsed as a
+  // tag a second time. Values Mustache substitutes itself are never
+  // re-parsed, so only these pre-pasted ones need it.
   const sentinels = new Map<string, string>();
   const sentinelPrefix = `__CAELO_TPL_${globalThis.crypto.randomUUID()}_`;
   const mkSentinel = (original: string): string => {
@@ -380,15 +394,28 @@ export function renderTemplate(input: RenderTemplateInput): RenderTemplateOutput
     return mkSentinel(match);
   });
 
+  // 3b. A tag whose name is not a field identifier (`{{Page URL}}`, a
+  //     Google Tag Manager variable in a snippet) can never be a
+  //     placeholder — field names are snake_case. Mustache would look it
+  //     up and silently render "", so it stays literal (#1053).
+  html = html.replace(NON_IDENTIFIER_TAG_RE, (match, name: string) =>
+    IDENTIFIER_RE.test(name.trim()) ? match : mkSentinel(match),
+  );
+
   // 4. Render. The view holds only lowercase keys; sentinels survive
   //    untouched; sections + partials are already substituted.
   const rendered = Mustache.render(html, view);
 
-  // 5. Restore loud-raw sentinels.
-  let final = rendered;
-  for (const [sentinel, original] of sentinels) {
-    final = final.split(sentinel).join(original);
-  }
+  // 5. Restore sentinels in one pass. A single replace never re-scans
+  //    the text it inserts, so restored content cannot be mistaken for a
+  //    sentinel (and a list of N items costs one scan, not N).
+  let final =
+    sentinels.size === 0
+      ? rendered
+      : rendered.replace(
+          new RegExp(`${sentinelPrefix}\\d+__`, "g"),
+          (key) => sentinels.get(key) ?? key,
+        );
 
   // 6. Resolve internal references (epic #724). Last, so values,
   //    defaults and list items substituted above are covered; nested
@@ -417,7 +444,7 @@ function renderSection(
     // fields are looked up FIRST by construction, so a plugin can never
     // shadow something the module's author declared.
     const items = dataLists[name];
-    if (items) return renderDataList(inner, items);
+    if (items) return renderDataList(inner, items, mkSentinel);
     // Declared by an installed plugin that is NOT running. Naming the
     // plugin turns "unknown field" (hunt for a typo) into "switch that
     // plugin back on", which is the actual fix.
@@ -430,13 +457,13 @@ function renderSection(
     return mkSentinel(match);
   }
   if (field.kind === "module-list") {
-    return renderModuleList(name, field, cvs, partials, missing);
+    return renderModuleList(name, field, cvs, partials, missing, mkSentinel);
   }
   if (field.kind === "text-list") {
-    return renderTextList(name, inner, field, cvs, missing);
+    return renderTextList(name, inner, field, cvs, missing, mkSentinel);
   }
   if (field.kind === "link-list") {
-    return renderLinkList(name, inner, field, cvs, missing);
+    return renderLinkList(name, inner, field, cvs, missing, mkSentinel);
   }
   // Any NON-list field used as a `{{#name}}…{{/name}}` section is a
   // CONDITIONAL (Mustache semantics): render the inner block once when the
@@ -449,7 +476,7 @@ function renderSection(
   // partial pass); `{{.}}`/`{{item}}` are substituted here for parity with
   // the *-list renderers. An empty conditional is intentional, not
   // "missing" — nothing is pushed to `missing`.
-  return renderConditionalSection(name, inner, field, cvs);
+  return renderConditionalSection(name, inner, field, cvs, mkSentinel);
 }
 
 /**
@@ -461,11 +488,14 @@ function renderConditionalSection(
   inner: string,
   field: TemplateField,
   cvs: Readonly<Record<string, unknown>>,
+  mkSentinel: (original: string) => string,
 ): string {
   const raw = Object.hasOwn(cvs, name) ? cvs[name] : field.default;
   if (!isPresentSectionValue(raw)) return "";
   const value = scalarSectionString(raw);
-  return value.length > 0 ? inner.replace(/\{\{\s*(?:\.|item)\s*\}\}/g, () => value) : inner;
+  return value.length > 0
+    ? inner.replace(/\{\{\s*(?:\.|item)\s*\}\}/g, () => mkSentinel(value))
+    : inner;
 }
 
 /**
@@ -498,6 +528,7 @@ function renderTextList(
   field: TemplateField,
   cvs: Readonly<Record<string, unknown>>,
   missing: string[],
+  mkSentinel: (original: string) => string,
 ): string {
   const raw = Object.hasOwn(cvs, name) ? cvs[name] : field.default;
   if (!Array.isArray(raw)) return "";
@@ -510,7 +541,7 @@ function renderTextList(
       continue;
     }
     const value = String(el);
-    parts.push(inner.replace(/\{\{\s*(?:\.|item)\s*\}\}/g, () => value));
+    parts.push(inner.replace(/\{\{\s*(?:\.|item)\s*\}\}/g, () => mkSentinel(value)));
   }
   return parts.join("");
 }
@@ -529,13 +560,16 @@ function renderTextList(
 function renderDataList(
   inner: string,
   items: ReadonlyArray<Readonly<Record<string, string>>>,
+  mkSentinel: (original: string) => string,
 ): string {
   const parts: string[] = [];
   for (const item of items) {
     let rendered = inner;
     for (const [key, value] of Object.entries(item)) {
       const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      rendered = rendered.replace(new RegExp(`\\{\\{\\s*${escaped}\\s*\\}\\}`, "g"), () => value);
+      rendered = rendered.replace(new RegExp(`\\{\\{\\s*${escaped}\\s*\\}\\}`, "g"), () =>
+        mkSentinel(value),
+      );
     }
     parts.push(rendered);
   }
@@ -548,6 +582,7 @@ function renderLinkList(
   field: TemplateField,
   cvs: Readonly<Record<string, unknown>>,
   missing: string[],
+  mkSentinel: (original: string) => string,
 ): string {
   const raw = Object.hasOwn(cvs, name) ? cvs[name] : field.default;
   if (!Array.isArray(raw)) return "";
@@ -566,7 +601,9 @@ function renderLinkList(
     }
     const { label, href } = el as { label: string; href: string };
     parts.push(
-      inner.replace(/\{\{\s*label\s*\}\}/g, () => label).replace(/\{\{\s*href\s*\}\}/g, () => href),
+      inner
+        .replace(/\{\{\s*label\s*\}\}/g, () => mkSentinel(label))
+        .replace(/\{\{\s*href\s*\}\}/g, () => mkSentinel(href)),
     );
   }
   return parts.join("");
@@ -578,6 +615,7 @@ function renderModuleList(
   cvs: Readonly<Record<string, unknown>>,
   partials: PartialResolver,
   missing: string[],
+  mkSentinel: (original: string) => string,
 ): string {
   const raw = Object.hasOwn(cvs, name) ? cvs[name] : field.default;
   if (!Array.isArray(raw)) return "";
@@ -601,7 +639,7 @@ function renderModuleList(
       parts.push(`<!-- caelo:module-list ${name} needs recursive renderer (compose path) -->`);
       continue;
     }
-    parts.push(partialHtml);
+    parts.push(mkSentinel(partialHtml));
   }
   return parts.join("");
 }
@@ -625,7 +663,14 @@ function renderPartialRef(
     missing.push(reason);
     return comment(reason);
   }
-  const ref = cvs[name];
+  const ref = Object.hasOwn(cvs, name) ? cvs[name] : undefined;
+  // An unset or explicitly null single `module` field is an EMPTY slot,
+  // the same as an empty module-list / text-list: it renders nothing and
+  // is not a failure (#1041). The static generator refuses a Stage on any
+  // marker, so flagging "empty" here made an optional nested slot
+  // impossible to leave blank. A present value that is not a ref is still
+  // malformed and stays loud.
+  if (ref === undefined || ref === null) return "";
   if (!isNestedRef(ref)) {
     missing.push(`module-ref-malformed:${name}`);
     return comment(`module-ref-malformed ${name}`);
@@ -636,5 +681,5 @@ function renderPartialRef(
     missing.push(`${NESTED_RENDERER_UNAVAILABLE}:${name}`);
     return `<!-- caelo:module ${name} needs recursive renderer (compose path) -->`;
   }
-  return partialHtml;
+  return mkSentinel(partialHtml);
 }

package/src/version.ts

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