@caelo-cms/shared 0.11.0 → 0.11.2

package/src/build-page.ts

@@ -43,10 +43,10 @@ const contentValuesSchema = z.record(z.string(), z.unknown());
  * existing content paths so build_page adds NO new semantics, only batching:
  *
  *   - `inline`   → mint a private (unsynced) content_instance carrying
- *     `values`, exactly what `set_page_module_content` produces for a
+ *     `values`, exactly what `set_page_module_content_many` produces for a
  *     fresh placement.
  *   - `shared`   → mint a reusable content_instance (purpose required —
- *     same decision-support contract as `create_content_instance`) and
+ *     same decision-support contract as `create_content_instances`) and
  *     bind this placement to it, `synced` by default.
  *   - `existing` → bind an already-minted content_instance (reuse-first
  *     per CLAUDE.md §1A) — the batched form of `set_placement_content`.
@@ -94,7 +94,7 @@ export type BuildPageContent = z.infer<typeof buildPageContentSchema>;
  *     extra authoring keys are TOLERATED (§1A/§11 — a placement that can
  *     succeed must not fail over an extra field) but NOT applied; the op
  *     surfaces an info naming any carried field whose value differs from the
- *     module's stored one, pointing at edit_module (§2 — no silent drop).
+ *     module's stored one, pointing at update_modules_many (§2 — no silent drop).
  *
  * The element-level superRefine reports issues WITH the element's array
  * index in the Zod path, so a mode error fails as `modules[3]: …`.
@@ -159,9 +159,9 @@ export const buildPageModuleSchema = z
     description: z.string().max(1000).optional(),
     kind: moduleKindSchema.optional(),
     type: slugSchema.optional(),
-    html: sourceTextArg(z.string().min(1).max(MODULE_HTML_MAX)).optional(),
-    css: sourceTextArg(z.string().max(MODULE_CSS_MAX)).optional(),
-    js: sourceTextArg(z.string().max(MODULE_JS_MAX)).optional(),
+    html: sourceTextArg(z.string().min(1).max(MODULE_HTML_MAX), "html").optional(),
+    css: sourceTextArg(z.string().max(MODULE_CSS_MAX), "css").optional(),
+    js: sourceTextArg(z.string().max(MODULE_JS_MAX), "js").optional(),
     fields: z.array(moduleFieldSchema).max(64).optional(),
     /** issue #164 slice 2 — opt-in mechanical token binding (tool layer). */
     bindThemeLiterals: z.boolean().optional(),
@@ -192,7 +192,7 @@ export const buildPageModuleSchema = z
     // (build_page places; it does not re-author a shared module). To avoid a
     // SILENT dropped change (§2), the HANDLER surfaces an INFO in the result
     // naming any ignored authoring field whose value DIFFERS from the module's
-    // stored one, and points at edit_module. The schema can't do that check (no
+    // stored one, and points at update_modules_many. The schema can't do that check (no
     // DB), so it just allows the entry through.
     if (entry.moduleId !== undefined) return;
     if (entry.displayName === undefined || entry.html === undefined) {
@@ -220,7 +220,7 @@ export const buildPageTargetSchema = z
     pageId: z.string().uuid().optional(),
     slug: slugSchema.optional(),
     title: z.string().min(1).max(256).optional(),
-    name: z.string().min(1).max(256).optional(),
+    shortTitle: pageCreateSchema.shape.shortTitle,
     templateId: z.string().uuid().optional(),
     status: pageStatusSchema.optional(),
     /**
@@ -268,7 +268,7 @@ export const buildPageTargetSchema = z
       [
         "slug",
         "title",
-        "name",
+        "shortTitle",
         "templateId",
         "status",
         "parentPageId",
@@ -283,6 +283,11 @@ export const buildPageTargetSchema = z
           code: z.ZodIssueCode.custom,
           message:
             `pageId targets an EXISTING page — drop ${createKeys.join(", ")}. ` +
+            // #1152 — status is a create-time field; publishing an existing
+            // page has its own tool.
+            (createKeys.includes("status")
+              ? "`status` only applies to a page this call creates; publish an existing page with set_pages_status_many. "
+              : "") +
             "To create a new page instead, omit pageId and pass slug + title.",
         });
       }

package/src/content.test.ts

@@ -91,7 +91,32 @@ describe("moduleCreateSchema", () => {
     expect(moduleCreateSchema.safeParse({ ...base, js: 'xml += "]]>";' }).success).toBe(true);
   });
 
-  it("rejects CDATA on the update path too (edit_module / edit_content funnel)", () => {
+  // e2e-livedit run 40532297620 — html / css whose line breaks arrived as
+  // literal `\n` sequences rendered `\n` text and broke the CSS. AI tool
+  // arguments are decoded first (`decodeEscapedLineBreaks`); every other
+  // writer is refused with the fix.
+  it("rejects html and css whose line breaks are escaped, with the fix", () => {
+    const base = { slug: "site-footer", displayName: "Site footer", html: "<footer></footer>" };
+    const html = moduleCreateSchema.safeParse({
+      ...base,
+      html: '<footer class="f">\\n  <nav>\\n    <a href="/">Home</a>\\n  </nav>\\n</footer>',
+    });
+    expect(html.success).toBe(false);
+    if (!html.success) {
+      expect(html.error.issues.map((i) => i.message).join(" ")).toContain("real line breaks");
+    }
+    const css = moduleUpdateSchema.safeParse({
+      moduleId: "8c2f2f2a-0000-4000-8000-000000000432",
+      css: ".f {\\n  padding: 2rem;\\n}\\n.f a {\\n  color: inherit;\\n}",
+    });
+    expect(css.success).toBe(false);
+    // One escaped newline inside a CSS string on a single line is not the pattern.
+    expect(
+      moduleCreateSchema.safeParse({ ...base, css: '.f::after { content: "\\n  " }' }).success,
+    ).toBe(true);
+  });
+
+  it("rejects CDATA on the update path too (update_modules_many / edit_content funnel)", () => {
     const r = moduleUpdateSchema.safeParse({
       moduleId: "8c2f2f2a-0000-4000-8000-000000000432",
       css: "/*<![CDATA[*/ .x{} /*]]>*/",

package/src/content.ts

@@ -11,6 +11,8 @@
  */
 
 import { z } from "zod";
+import { hasEscapedLineBreaks } from "./escaped-line-breaks.js";
+import { DEFAULT_LIST_TYPES, SITE_TEXTS_LIST_TYPE } from "./lists/default-types.js";
 import { listItemInputSchema } from "./lists/items.js";
 import { LIST_MAX_ITEMS, sourceDefSchema } from "./lists/list-type.js";
 import { LIST_REF_RE } from "./lists/refs.js";
@@ -126,14 +128,34 @@ export function htmlEscapedMarkupMessage(field: string, value: string): string |
   return `${field} is HTML-escaped (&lt;…&gt; instead of <…>) — send the markup itself, unescaped.`;
 }
 
-const noCorruptMarkup = (field: string) => (value: string, ctx: z.RefinementCtx) => {
-  const message = jsonEncodedCodeMessage(field, value) ?? htmlEscapedMarkupMessage(field, value);
+/**
+ * See {@link jsonEncodedCodeMessage}: source whose line breaks arrived as
+ * literal `\n` sequences (`hasEscapedLineBreaks`) — the page shows the
+ * `\n` text and the CSS rules after it break. AI tool arguments are decoded
+ * first (`decodeEscapedLineBreaks`); this guards every other writer. Module
+ * js is checked by parsing it (admin-core `module-js-syntax.ts`), which
+ * catches this and every other syntax error.
+ */
+export function escapedLineBreaksMessage(field: "html" | "css", value: string): string | null {
+  if (!hasEscapedLineBreaks(value, field)) return null;
+  return `${field} has its line breaks escaped (literal \\n sequences, no real line break) — send the ${field} with real line breaks.`;
+}
+
+const noCorruptMarkup = (field: "html") => (value: string, ctx: z.RefinementCtx) => {
+  const message =
+    jsonEncodedCodeMessage(field, value) ??
+    htmlEscapedMarkupMessage(field, value) ??
+    escapedLineBreaksMessage(field, value);
   if (message) ctx.addIssue({ code: "custom", message });
 };
 const noJsonEncodedCode = (field: string) => (value: string, ctx: z.RefinementCtx) => {
   const message = jsonEncodedCodeMessage(field, value);
   if (message) ctx.addIssue({ code: "custom", message });
 };
+const noCorruptCss = (value: string, ctx: z.RefinementCtx) => {
+  const message = jsonEncodedCodeMessage("css", value) ?? escapedLineBreaksMessage("css", value);
+  if (message) ctx.addIssue({ code: "custom", message });
+};
 
 const moduleHtml = z
   .string()
@@ -168,7 +190,7 @@ const moduleCss = z
   .string()
   .max(MODULE_CSS_MAX, `css exceeds ${MODULE_CSS_MAX} bytes`)
   .refine(noCdata, cdataMessage("css"))
-  .superRefine(noJsonEncodedCode("css"));
+  .superRefine(noCorruptCss);
 const moduleJs = z
   .string()
   .max(MODULE_JS_MAX, `js exceeds ${MODULE_JS_MAX} bytes`)
@@ -276,7 +298,7 @@ const moduleFieldModuleSchema = z
      * stable `modules.type` class, e.g. `button` — NOT the unique
      * `modules.slug` like `button-mpqxq3ch`). When absent, any module is
      * permitted. The op-layer validator enforces the whitelist against
-     * the referenced module's `type` at `set_content_instance_values`
+     * the referenced module's `type` at `content_instances.set_values`
      * time. v0.12.3 (issue #106) renamed this from `allowedModuleSlugs`:
      * an exact-slug whitelist could never match an AI-minted module
      * because every minted slug carries a uniqueness suffix.
@@ -309,13 +331,31 @@ const moduleFieldModuleListSchema = z
  * written, and the renderer reports `list-type-missing:<slug>` for a type
  * that is gone.
  */
+/** The shipped list types, quoted, for the missing-listType message. */
+const SHIPPED_LIST_TYPE_SLUGS = [...DEFAULT_LIST_TYPES.map((t) => t.slug), SITE_TEXTS_LIST_TYPE]
+  .map((slug) => `"${slug}"`)
+  .join(", ");
+
 const moduleFieldListSchema = z
   .object({
     name: moduleFieldName,
     kind: z.literal("list"),
     label: moduleFieldLabel,
-    /** Slug of the list type that defines the entries. */
-    listType: slugSchema,
+    /**
+     * Slug of the list type that defines the entries. REQUIRED — a missing
+     * one says which types exist (#1190), not just "expected string".
+     */
+    listType: z
+      .string({
+        error: (iss) =>
+          iss.input === undefined
+            ? `a list field needs listType: ${SHIPPED_LIST_TYPE_SLUGS} or a custom type's slug (list_list_types shows them)`
+            : undefined,
+      })
+      .regex(
+        /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/,
+        "slug must be lowercase letters, digits, or hyphens (1–64 chars, no leading/trailing hyphen)",
+      ),
     bind: z.enum(["local", "shared", "source"]).optional(),
     /** `bind: "shared"` — fix the list for every placement (`caelo:list/<id>`). */
     list: z.string().regex(LIST_REF_RE, "list must be caelo:list/<id>").optional(),
@@ -491,7 +531,7 @@ export type ModuleKind = (typeof MODULE_KINDS)[number];
 /**
  * v0.12.0 — description is `.default("")` at the Zod boundary so the
  * 82+ legacy callers in tests/seed scripts keep working unchanged.
- * AI tool descriptions (create_module / edit_module) require the AI
+ * AI tool descriptions (add_module / build_page / update_modules_many) require the AI
  * to supply a real description explicitly — see CLAUDE.md §1A.
  */
 const moduleDescription = z.string().max(1000);
@@ -627,6 +667,15 @@ export const templateBlocksSetSchema = z
 
 export const pageStatusSchema = z.enum(["draft", "published"]);
 
+/** `pages.short_title` (#1142): a crumb-sized public label, never blank. */
+export const pageShortTitleSchema = z
+  .string()
+  .trim()
+  .min(1, "the short title is the page's breadcrumb label and cannot be blank")
+  // Same bound as the title it is backfilled and defaulted from, so every
+  // stored page stays editable; keeping it crumb-sized is guidance.
+  .max(256);
+
 /**
  * Page payloads are `.strict()` — passing an `html` field is rejected by Zod
  * before the handler runs. This is the §3.1 "no raw HTML on pages" invariant
@@ -636,9 +685,13 @@ export const pageStatusSchema = z.enum(["draft", "published"]);
 export const pageCreateSchema = z
   .object({
     slug: slugSchema,
-    /** P6.7.5 — internal editor label. Defaults to title if omitted. */
-    name: z.string().min(1).max(256).optional(),
     title: z.string().min(1).max(256),
+    /**
+     * #1142 — the page's public label in breadcrumbs, navigation and the
+     * page picker ("Pricing" for "Pricing for teams of every size").
+     * Omitted = the create-time resolver stores `title` (stored data).
+     */
+    shortTitle: pageShortTitleSchema.optional(),
     /**
      * P6.7.6 — optional. When omitted, the handler resolves to
      * `site_defaults.default_template_id` at create time. Stored data,
@@ -703,9 +756,9 @@ export const pageUpdateSchema = z
      * Routes that load the page first should always pass it back.
      */
     expectedVersion: z.number().int().nonnegative().optional(),
-    /** P6.7.5 — three independently-editable identifiers. */
-    name: z.string().min(1).max(256).optional(),
     title: z.string().min(1).max(256).optional(),
+    /** #1142 — the breadcrumb / navigation label; see {@link pageCreateSchema}. */
+    shortTitle: pageShortTitleSchema.optional(),
     slug: slugSchema.optional(),
     templateId: z.string().uuid().optional(),
     status: pageStatusSchema.optional(),
@@ -743,8 +796,23 @@ export const pageSetModulesSchema = z
         .object({
           blockName: slugSchema,
           moduleIds: z.array(z.string().uuid()),
+          /**
+           * #1195 — the placement each entry of `moduleIds` IS, by its
+           * content instance (same index; null = a new placement). Given,
+           * a placement keeps its content wherever it moves — across
+           * blocks too — and two placements of one module never trade
+           * content. Omitted, bindings carry over per (block, module) in
+           * order, which cannot tell repeated placements apart.
+           */
+          contentInstanceIds: z.array(z.string().uuid().nullable()).optional(),
         })
-        .strict(),
+        .strict()
+        .refine(
+          (b) =>
+            b.contentInstanceIds === undefined ||
+            b.contentInstanceIds.length === b.moduleIds.length,
+          { message: "contentInstanceIds needs one entry (or null) per moduleIds entry" },
+        ),
     ),
   })
   .strict();
@@ -780,10 +848,10 @@ const contentValuesSchema = z.record(z.string(), z.unknown());
 
 /**
  * v0.12.0 — why this row exists as a shared/reusable instance.
- * Surfaced in the `## Content Library` system-prompt block so the AI
- * can decide *reuse the synced row* vs *fork to unsynced* vs *mint
- * new* without a tool round-trip. Required by the AI's
- * create_content_instance tool description; legacy callers may pass
+ * Shown by the AI's list_content_instances tool so the AI can decide
+ * *reuse the synced row* vs *fork to unsynced* vs *mint new* without
+ * asking the operator. Required by the AI's
+ * create_content_instances tool description; legacy callers may pass
  * null (the migration-0093 unsynced rows have purpose=NULL).
  * See CLAUDE.md §1A.
  */

package/src/css-scope-scan.ts

@@ -7,7 +7,7 @@
  * that is not tied to the module bleeds into every other module on the
  * page: an `h1 {}` in the hero restyles the pricing table's heading, a
  * `.card {}` in one module restyles another module's cards. The
- * convention (edit_module description, design-quality skill) is to nest
+ * convention (update_modules_many description, design-quality skill) is to nest
  * module CSS under the module's own root class; this scanner is the
  * mechanical write-time check that rides the authoring tool's result,
  * so the AI fixes the selector in the same turn. A warning, not a gate:

package/src/css-var-scan.ts

@@ -143,11 +143,11 @@ export function formatUnknownCssVarWarning(unknown: readonly UnknownCssVar[]): s
     const hint = u.suggestion !== null ? ` (did you mean \`${u.suggestion}\`?)` : "";
     const fallback = u.hasFallback
       ? " — its hardcoded fallback is what visitors will see, detached from the theme"
-      : " — the declaration is invalid and the property won't apply";
+      : " — nothing defines it, so the property won't apply";
     return `\`${u.name}\`${hint}${fallback}`;
   });
   return (
-    `⚠️ Unknown CSS vars (the active theme does not emit them): ${parts.join("; ")}. ` +
-    "Use the exact names from the `## Theme` inventory, or define the custom property in this CSS if it's intentional."
+    `⚠️ Unknown CSS vars (neither the active theme nor any layout or template CSS defines them): ${parts.join("; ")}. ` +
+    "Use the exact token names (`get_theme`), or define the custom property in this CSS if it's intentional."
   );
 }

package/src/escaped-line-breaks.ts

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Source text whose line breaks arrived string-escaped as a whole.
+ *
+ * e2e-livedit run 40532297620 (release gate v0.11.1): `add_module`'s html,
+ * css and js came in with every line break as the two characters `\` `n`
+ * (`(function () {\n  document…`). Stored as sent, the footer showed `\n`
+ * text, its CSS broke, and the page's shared module `<script>` threw
+ * `SyntaxError: Invalid or unexpected token` — a backslash outside a string
+ * is not JavaScript. Like the other whole-value transport encodings
+ * (`source-text-transport.ts`) the AI tool boundary decodes it, once.
+ *
+ * The same two characters are legitimate inside a string literal (`"a\nb"`
+ * in JS or a CSS `content`), a regex, an HTML attribute value, or the body
+ * of a raw-text element. A value is only decoded when EVERY escaped line
+ * break sits where a real line break could have stood — between tokens of
+ * code, or in markup text between tags. One escape inside a literal makes
+ * the value ambiguous and it is left exactly as sent: decoding it would
+ * turn valid source into broken source (a raw newline inside a JS string
+ * is a syntax error). The op validators still refuse what is left broken
+ * (module js is parsed in admin-core `module-js-syntax.ts`).
+ */
+
+/** Which grammar a source value is written in; decides what counts as a literal. */
+export type SourceLanguage = "html" | "css" | "js";
+
+/** `\n` or `\r\n` escape starting at `i` (a single backslash, not an escaped one). */
+function escapedLineBreakLength(value: string, i: number): number {
+  if (value[i] !== "\\") return 0;
+  if (value[i + 1] === "n") return 2;
+  if (value[i + 1] === "r" && value[i + 2] === "\\" && value[i + 3] === "n") return 4;
+  return 0;
+}
+
+/** Characters after which a `/` in JS starts a regex literal rather than a division. */
+const REGEX_PRECEDERS = new Set([..."(,=:[!&|?{};+-*%<>~^"]);
+
+/**
+ * Index just past a quoted literal starting at `start` (its quote char), or
+ * -1 when an escaped line break sits inside it.
+ */
+function skipQuoted(value: string, start: number): number {
+  const quote = value[start];
+  let j = start + 1;
+  while (j < value.length) {
+    const ch = value[j];
+    if (ch === "\\") {
+      if (value[j + 1] === "n" || value[j + 1] === "r") return -1;
+      j += 2;
+      continue;
+    }
+    if (ch === quote) return j + 1;
+    j += 1;
+  }
+  return j;
+}
+
+/** True when an escaped line break sits inside a JS string, template, or regex literal. */
+function jsLiteralHoldsEscape(value: string): boolean {
+  let prev = "";
+  let i = 0;
+  while (i < value.length) {
+    const ch = value[i] as string;
+    const lineBreak = escapedLineBreakLength(value, i);
+    if (lineBreak > 0) {
+      prev = "";
+      i += lineBreak;
+      continue;
+    }
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const end = skipQuoted(value, i);
+      if (end < 0) return true;
+      prev = ch;
+      i = end;
+      continue;
+    }
+    if (ch === "/" && value[i + 1] === "/") {
+      // A line comment runs to the next (escaped) line break.
+      i += 2;
+      while (i < value.length && escapedLineBreakLength(value, i) === 0) i += 1;
+      continue;
+    }
+    if (ch === "/" && value[i + 1] === "*") {
+      const close = value.indexOf("*/", i + 2);
+      i = close < 0 ? value.length : close + 2;
+      continue;
+    }
+    if (ch === "/" && (prev === "" || REGEX_PRECEDERS.has(prev))) {
+      let j = i + 1;
+      let inClass = false;
+      while (j < value.length) {
+        const r = value[j];
+        if (r === "\\") {
+          if (value[j + 1] === "n" || value[j + 1] === "r") return true;
+          j += 2;
+          continue;
+        }
+        if (r === "[") inClass = true;
+        else if (r === "]") inClass = false;
+        else if (r === "/" && !inClass) break;
+        j += 1;
+      }
+      prev = "/";
+      i = j + 1;
+      continue;
+    }
+    if (ch !== " " && ch !== "\t") prev = ch;
+    i += 1;
+  }
+  return false;
+}
+
+/** True when an escaped line break sits inside a CSS string. */
+function cssLiteralHoldsEscape(value: string): boolean {
+  let i = 0;
+  while (i < value.length) {
+    const ch = value[i];
+    if (ch === "/" && value[i + 1] === "*") {
+      const close = value.indexOf("*/", i + 2);
+      i = close < 0 ? value.length : close + 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      const end = skipQuoted(value, i);
+      if (end < 0) return true;
+      i = end;
+      continue;
+    }
+    i += ch === "\\" ? 2 : 1;
+  }
+  return false;
+}
+
+/** Elements whose body is not markup text: an escape there belongs to that body. */
+const RAW_TEXT_ELEMENTS = new Set(["script", "style", "pre", "textarea"]);
+
+/** True when an escaped line break sits inside an attribute value, a comment, or a raw-text element body. */
+function htmlLiteralHoldsEscape(value: string): boolean {
+  const lower = value.toLowerCase();
+  let i = 0;
+  while (i < value.length) {
+    if (value[i] !== "<") {
+      i += 1;
+      continue;
+    }
+    if (value.startsWith("<!--", i)) {
+      const close = value.indexOf("-->", i + 4);
+      const end = close < 0 ? value.length : close + 3;
+      if (/(?<!\\)\\[nr]/.test(value.slice(i, end))) return true;
+      i = end;
+      continue;
+    }
+    const name = /^<([a-zA-Z][a-zA-Z0-9-]*)/.exec(value.slice(i, i + 64))?.[1]?.toLowerCase();
+    let j = i + 1;
+    while (j < value.length && value[j] !== ">") {
+      if (value[j] === '"' || value[j] === "'") {
+        const end = skipQuoted(value, j);
+        if (end < 0) return true;
+        j = end;
+        continue;
+      }
+      j += 1;
+    }
+    i = j + 1;
+    if (name && RAW_TEXT_ELEMENTS.has(name)) {
+      const close = lower.indexOf(`</${name}`, i);
+      const end = close < 0 ? value.length : close;
+      if (/(?<!\\)\\[nr]/.test(value.slice(i, end))) return true;
+      i = end;
+    }
+  }
+  return false;
+}
+
+const LITERAL_HOLDS_ESCAPE: Readonly<Record<SourceLanguage, (value: string) => boolean>> = {
+  html: htmlLiteralHoldsEscape,
+  css: cssLiteralHoldsEscape,
+  js: jsLiteralHoldsEscape,
+};
+
+/** An escaped line break (`\n`, `\r\n`) not preceded by another backslash. */
+const ESCAPED_LINE_BREAK = /(?<!\\)(?:\\r)?\\n/g;
+
+/**
+ * True when a source value's line breaks were string-escaped as a whole:
+ * no real line break at all, at least two escaped ones, one of them
+ * followed by indentation (the signature of pretty-printed source), and
+ * none inside a literal of `language` (see the file comment).
+ *
+ * @param value - the source text as sent.
+ * @param language - the grammar the value is written in.
+ */
+export function hasEscapedLineBreaks(value: string, language: SourceLanguage): boolean {
+  if (/[\r\n]/.test(value)) return false;
+  const hits = value.match(ESCAPED_LINE_BREAK)?.length ?? 0;
+  if (hits < 2) return false;
+  if (!/(?<!\\)\\n(?:[ \t]|\\t)/.test(value)) return false;
+  return !LITERAL_HOLDS_ESCAPE[language](value);
+}
+
+/**
+ * The value with every escaped line break turned back into a real one (and
+ * the escaped tabs indenting the next line into real tabs) when
+ * `hasEscapedLineBreaks` holds; the input unchanged otherwise. Nothing else
+ * is unescaped: quotes and backslashes arrived as they were meant.
+ *
+ * @param value - the tool argument (non-strings pass through).
+ * @param language - the grammar the value is written in.
+ */
+export function decodeEscapedLineBreaks(value: unknown, language: SourceLanguage): unknown {
+  if (typeof value !== "string" || !hasEscapedLineBreaks(value, language)) return value;
+  return value.replace(
+    /(?<!\\)(?:\\r)?\\n((?:\\t)*)/g,
+    (_m, tabs: string) => `\n${"\t".repeat(tabs.length / 2)}`,
+  );
+}

package/src/index.ts

@@ -20,6 +20,7 @@ export * from "./database-url.js";
 export * from "./design-draft-shell.js";
 export * from "./document-language.js";
 export * from "./edit-markers.js";
+export * from "./escaped-line-breaks.js";
 export * from "./font-assets.js";
 export * from "./font-axis-policy.js";
 export * from "./font-usage.js";
@@ -34,6 +35,7 @@ export * from "./interactions.js";
 export * from "./link-canonicalise.js";
 export * from "./link-refs.js";
 export * from "./lists/index.js";
+export * from "./live-events.js";
 export {
   type LogContext,
   type Logger,

package/src/interactions.ts

@@ -195,9 +195,9 @@ export function interactionAssets(used: ReadonlySet<InteractionId>): {
  * guidance cannot drift from the snippets above.
  */
 export const INTERACTION_MARKUP_CONTRACT =
-  '**Vetted interactions - use these instead of writing JS for them.** Add `data-caelo-ui="<id>"` to the markup and Caelo ships accessible, dependency-free behaviour once per page; style it freely in the module CSS. ' +
-  '`accordion` (FAQ, collapsible sections): `<div data-caelo-ui="accordion" data-single>` containing `<details id="..."><summary>Question</summary><div>Answer</div></details>` items - `data-single` keeps one open; a link to `#<details id>` opens it. ' +
-  '`tabs`: `<div data-caelo-ui="tabs"><div role="tablist" aria-label="..."><button type="button" role="tab" id="t1" aria-controls="p1" aria-selected="true">...</button><button type="button" role="tab" id="t2" aria-controls="p2" aria-selected="false" tabindex="-1">...</button></div><div role="tabpanel" id="p1" aria-labelledby="t1">...</div><div role="tabpanel" id="p2" aria-labelledby="t2" hidden>...</div></div>` - ids must be unique on the page. ' +
-  '`carousel` (slider, testimonials): `<section data-caelo-ui="carousel" aria-roledescription="carousel" aria-label="..."><div data-caelo-carousel-track tabindex="0"><div role="group" aria-roledescription="slide" aria-label="1 of 3">...</div>...</div><button type="button" data-caelo-carousel-prev aria-label="Previous slide"><span aria-hidden="true">&lsaquo;</span></button><button type="button" data-caelo-carousel-next aria-label="Next slide"><span aria-hidden="true">&rsaquo;</span></button></section>` (an icon button keeps its visible content aria-hidden; a text button needs no aria-label) - one slide per view by default; set the slides\' `flex-basis` in module CSS to show more. ' +
-  '`mobile-nav` (menu collapsing behind a toggle on small screens): `<nav class="caelo-nav-menu" data-caelo-ui="mobile-nav" data-nav-open="false"><button type="button" class="caelo-nav-toggle" aria-expanded="false" aria-label="Menu"><span class="caelo-nav-bar"></span><span class="caelo-nav-bar"></span><span class="caelo-nav-bar"></span></button><ul>{{#menu}}<li>…</li>{{/menu}}</ul></nav>` around the module\'s menu `list` field. ' +
+  "`data-caelo-ui` kit — use it instead of JS for these (accessible, shipped once per page, style freely in module CSS):\n" +
+  '- `accordion` (FAQ, collapsible): `<div data-caelo-ui="accordion" data-single>` with `<details id="..."><summary>Question</summary><div>Answer</div></details>` items; `data-single` keeps one open; a link to `#<details id>` opens it.\n' +
+  '- `tabs`: `<div data-caelo-ui="tabs"><div role="tablist" aria-label="..."><button type="button" role="tab" id="t1" aria-controls="p1" aria-selected="true">...</button><button type="button" role="tab" id="t2" aria-controls="p2" aria-selected="false" tabindex="-1">...</button></div><div role="tabpanel" id="p1" aria-labelledby="t1">...</div><div role="tabpanel" id="p2" aria-labelledby="t2" hidden>...</div></div>`; ids unique on the page.\n' +
+  '- `carousel` (slider, testimonials): `<section data-caelo-ui="carousel" aria-roledescription="carousel" aria-label="..."><div data-caelo-carousel-track tabindex="0"><div role="group" aria-roledescription="slide" aria-label="1 of 3">...</div>...</div><button type="button" data-caelo-carousel-prev aria-label="Previous slide"><span aria-hidden="true">&lsaquo;</span></button><button type="button" data-caelo-carousel-next aria-label="Next slide"><span aria-hidden="true">&rsaquo;</span></button></section>`; icon buttons keep visible content aria-hidden, text buttons need no aria-label. One slide per view; set the slides\' `flex-basis` in module CSS to show more.\n' +
+  '- `mobile-nav` (menu collapsing behind a toggle on small screens): `<nav class="caelo-nav-menu" data-caelo-ui="mobile-nav" data-nav-open="false"><button type="button" class="caelo-nav-toggle" aria-expanded="false" aria-label="Menu"><span class="caelo-nav-bar"></span><span class="caelo-nav-bar"></span><span class="caelo-nav-bar"></span></button><ul>{{#menu}}<li>…</li>{{/menu}}</ul></nav>` around the module\'s menu `list` field.\n' +
   "Write module JS only for behaviour the kit does not cover.";

package/src/link-refs.test.ts

@@ -39,6 +39,7 @@ const lists = createListRenderContext({
   pages: new Map(),
   media: new Map(),
   siteLanguage: "en",
+  homePageId: null,
 }).forPage(null);
 const uid = (n: number) => `00000000-0000-4000-9000-${String(n).padStart(12, "0")}`;
 const links = (...ls: [string, string][]) =>

package/src/lists/default-types.ts

@@ -100,3 +100,42 @@ export const DEFAULT_LIST_TYPES: readonly ListTypeDef[] = [
     },
   },
 ];
+
+/** Slug of the list type whose entries are the site texts (`{{site_text.<key>}}`, #1142). */
+export const SITE_TEXTS_LIST_TYPE = "site-texts";
+
+/**
+ * The site texts type: fixed interface strings of the website that are no
+ * page content ("Start" in a trail, the breadcrumb `aria-label`, "Read
+ * more"). Module HTML reads one by key with `{{site_text.<key>}}`, so the
+ * string is translatable (shared-list overlays) instead of frozen into
+ * the module. Seeded by migration 0358 together with the "Site texts"
+ * list; installs that ran 0352 never had it, so it is not part of
+ * {@link DEFAULT_LIST_TYPES} (whose seed is pinned to 0352).
+ */
+export const SITE_TEXTS_TYPE: ListTypeDef = {
+  slug: SITE_TEXTS_LIST_TYPE,
+  name: "Site texts",
+  purpose:
+    "Fixed interface texts of the website, read by key in module HTML with {{site_text.<key>}}: the breadcrumb aria-label, button and link texts that repeat across modules. Not page content.",
+  role: "content",
+  root: { allow: ["text"] },
+  nodes: {
+    text: {
+      label: "Site text",
+      fields: [
+        // The lookup key is code, not copy: a translated key would stop
+        // `{{site_text.<key>}}` from finding the entry in that language.
+        {
+          name: "key",
+          label: "Key",
+          type: "text",
+          required: true,
+          maxLength: 64,
+          ext: { "international-site": { translate: false } },
+        },
+        { name: "text", label: "Text", type: "text", required: true },
+      ],
+    },
+  },
+};

package/src/lists/fields.ts

@@ -50,6 +50,7 @@ export const LIST_RESERVED_NAMES: ReadonlySet<string> = new Set([
   "last",
   "items",
   "page",
+  "site_text",
   "recurse",
 ]);
 const RESERVED_PREFIXES = ["is_", "has_", "count_"] as const;