@caelo-cms/shared 0.11.1 → 0.11.3

package/dist/version.d.ts

@@ -19,7 +19,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export declare const CAELO_VERSION = "0.11.1";
+export declare const CAELO_VERSION = "0.11.3";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -31,7 +31,7 @@ export declare const CAELO_VERSION = "0.11.1";
  *
  * @deprecated use CAELO_VERSION
  */
-export declare const CALEO_VERSION = "0.11.1";
+export declare const CALEO_VERSION = "0.11.3";
 /**
  * Parsed shape — major/minor/patch + optional pre-release tag.
  * Stable interface for callers that need to feature-gate (rare —

package/dist/version.js

@@ -20,7 +20,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export const CAELO_VERSION = "0.11.1";
+export const CAELO_VERSION = "0.11.3";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caelo-cms/shared",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "private": false,
   "license": "MPL-2.0",
   "description": "Shared Zod schemas + types + the two-pass HTML composer used by every Caelo CMS workspace package. Stable enough for plugin authors and embedders to depend on directly.",

package/src/ai-tools.ts

@@ -725,6 +725,16 @@ export const moveModuleToolInput = z
   .object({
     pageId: z.string().uuid(),
     moduleId: z.string().uuid(),
+    /**
+     * #1195 — which placement of `moduleId` to move when the page holds it
+     * more than once: its block and 0-based position there. Needed only
+     * then; the error names the placements.
+     */
+    fromBlockName: z.string().min(1).max(80).optional(),
+    fromPosition: z.preprocess(
+      (v) => (typeof v === "string" && /^\d+$/.test(v) ? Number.parseInt(v, 10) : v),
+      z.number().int().min(0).max(1000).optional(),
+    ),
     toBlockName: z.string().min(1).max(80).optional(),
     position: movePositionInputSchema,
   })

package/src/bug-intake.test.ts

@@ -9,6 +9,7 @@
 
 import { describe, expect, it } from "bun:test";
 import {
+  BUG_REPORT_KIND_BEFORE_1192,
   bugIntakeReport,
   bugIntakeSigningString,
   computeBugFingerprint,
@@ -152,3 +153,49 @@ describe("bugIntakeReport", () => {
     expect(parsed.success).toBe(false);
   });
 });
+
+describe("bugIntakeReport kind (#1192)", () => {
+  const base = {
+    protocolVersion: 1,
+    reportId: "7f3c2b9e-1d4a-4e8b-9c0f-2a1b3c4d5e6f",
+    caeloVersion: "0.10.55",
+    fingerprint: "a".repeat(64),
+    source: "ai",
+    severity: "degraded",
+    blockedTask: false,
+    suspectedTool: null,
+    title: "t",
+    whatHappened: "w",
+    expected: "e",
+    evidence: null,
+  } as const;
+
+  it("parses a report without kind, as an install from before #1192 sends it, as a defect", () => {
+    expect(BUG_REPORT_KIND_BEFORE_1192).toBe("defect");
+    const parsed = bugIntakeReport.parse(base);
+    expect(parsed.kind).toBe("defect");
+    expect(parsed.severity).toBe("degraded");
+  });
+
+  it("round-trips a suggestion, which carries no severity", () => {
+    const sent = { ...base, kind: "suggestion", severity: null };
+    const parsed = bugIntakeReport.parse(sent);
+    expect(parsed).toEqual(sent);
+    expect(bugIntakeReport.parse(JSON.parse(JSON.stringify(parsed)))).toEqual(sent);
+  });
+
+  it("refuses a defect without severity, a graded suggestion and an auto-captured suggestion", () => {
+    const issues = (r: unknown) =>
+      bugIntakeReport.safeParse(r).error?.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
+    expect(issues({ ...base, kind: "defect", severity: null })).toEqual([
+      "severity: a defect needs a severity",
+    ]);
+    expect(issues({ ...base, kind: "suggestion" })).toEqual([
+      "severity: a suggestion has no severity; send null",
+    ]);
+    expect(issues({ ...base, source: "auto", kind: "suggestion", severity: null })).toEqual([
+      "kind: an auto-captured report is always a defect",
+    ]);
+    expect(issues({ ...base, kind: "feature" })?.[0]).toStartWith("kind:");
+  });
+});

package/src/bug-intake.ts

@@ -60,7 +60,41 @@ export const bugIntakeRegisterRequest = z
   .strict();
 export type BugIntakeRegisterRequest = z.infer<typeof bugIntakeRegisterRequest>;
 
-/** `POST /v1/reports` — one redacted bug report (signed). */
+/**
+ * What a report is about (#1192).
+ *   defect     — something in Caelo misbehaved: a tool contradicted its
+ *                description, a render contradicted stored state, a call
+ *                failed. Auto captures and provider errors are always this.
+ *   suggestion — nothing misbehaved, but Caelo lacks something the AI needed:
+ *                a capability, a tool, a docs page. Filed by the AI only.
+ * The intake keeps the two apart end to end: own title prefix and label, own
+ * daily issue cap, and matching never puts one kind into the other's cluster.
+ */
+export const bugReportKind = z.enum(["defect", "suggestion"]);
+export type BugReportKind = z.infer<typeof bugReportKind>;
+
+/**
+ * The kind of a report that names none. Contract rule (#1192): installs
+ * released before `kind` existed send no kind, and everything they could
+ * file was a defect, so a missing kind IS `defect`. This is a protocol rule,
+ * not a guess: it holds for every protocol-1 report, and the intake applies
+ * the same rule to the records it stored before #1192.
+ */
+export const BUG_REPORT_KIND_BEFORE_1192: BugReportKind = "defect";
+
+/** How badly a defect hurt the task. Defects only: a suggestion has no severity. */
+export const bugReportSeverity = z.enum(["blocking", "degraded", "cosmetic"]);
+export type BugReportSeverity = z.infer<typeof bugReportSeverity>;
+
+/**
+ * `POST /v1/reports` — one redacted bug report (signed).
+ *
+ * `kind` is optional on the wire only for the contract rule above; parsing
+ * always yields one. `severity` is set for a defect and `null` for a
+ * suggestion (nothing broke, so there is nothing to grade), and an
+ * auto-captured report is always a defect. A report that breaks either is
+ * refused, not repaired: it came from a broken client.
+ */
 export const bugIntakeReport = z
   .object({
     protocolVersion: z.literal(BUG_INTAKE_PROTOCOL_VERSION),
@@ -69,7 +103,8 @@ export const bugIntakeReport = z
     caeloVersion: z.string().min(1).max(64),
     fingerprint: fingerprintSchema,
     source: z.enum(["ai", "auto"]),
-    severity: z.enum(["blocking", "degraded", "cosmetic"]),
+    kind: bugReportKind.default(BUG_REPORT_KIND_BEFORE_1192),
+    severity: bugReportSeverity.nullable(),
     blockedTask: z.boolean(),
     suspectedTool: z.string().max(200).nullable(),
     title: z.string().min(1).max(BUG_INTAKE_LIMITS.title),
@@ -77,7 +112,27 @@ export const bugIntakeReport = z
     expected: z.string().min(1).max(BUG_INTAKE_LIMITS.expected),
     evidence: z.string().max(BUG_INTAKE_LIMITS.evidence).nullable(),
   })
-  .strict();
+  .strict()
+  .superRefine((r, ctx) => {
+    if (r.kind === "defect" && r.severity === null) {
+      ctx.addIssue({ code: "custom", path: ["severity"], message: "a defect needs a severity" });
+    }
+    if (r.kind === "suggestion" && r.severity !== null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["severity"],
+        message: "a suggestion has no severity; send null",
+      });
+    }
+    if (r.kind === "suggestion" && r.source === "auto") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["kind"],
+        message: "an auto-captured report is always a defect",
+      });
+    }
+  });
+/** A parsed report: `kind` is always present. */
 export type BugIntakeReport = z.infer<typeof bugIntakeReport>;
 
 /**

package/src/build-page.ts

@@ -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.ts

@@ -12,6 +12,7 @@
 
 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";
@@ -330,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(),
@@ -777,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();

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/index.ts

@@ -35,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/lists/fields.ts

@@ -53,11 +53,12 @@ export const LIST_RESERVED_NAMES: ReadonlySet<string> = new Set([
   "site_text",
   "recurse",
 ]);
-const RESERVED_PREFIXES = ["is_", "has_", "count_"] as const;
+/** Name prefixes reserved as a family (see {@link LIST_RESERVED_NAMES}). */
+export const LIST_RESERVED_PREFIXES = ["is_", "has_", "count_"] as const;
 
 /** True when `name` is taken by the engine (see {@link LIST_RESERVED_NAMES}). */
 export function isReservedListName(name: string): boolean {
-  return LIST_RESERVED_NAMES.has(name) || RESERVED_PREFIXES.some((p) => name.startsWith(p));
+  return LIST_RESERVED_NAMES.has(name) || LIST_RESERVED_PREFIXES.some((p) => name.startsWith(p));
 }
 
 export const listNameSchema = z

package/src/live-events.ts

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #1215 — the editor's live-refresh vocabulary. CLAUDE.md §11.B:
+ * clients must not poll the admin on a timer, because every request keeps an
+ * instance up. Instead the admin tells an open editor WHAT changed, as a
+ * topic, and the editor re-reads that one surface through its usual read
+ * endpoint (`/content/chat/<id>/pending`, `/api/agents`, …).
+ *
+ * A topic is a hint, never data: it carries no ids, no rows and no actor, so
+ * it is safe to hand to every signed-in tab. The read that follows goes
+ * through the endpoint's own permission checks.
+ *
+ * Topics come from the names of operations that committed (the Query API's
+ * `observeCommittedOperations`). Only WRITE operations are listed: a read
+ * classified as a change would make every refresh announce another change.
+ */
+
+/** One surface an editor tab may need to re-read. */
+export const LIVE_TOPICS = [
+  /** Running agents (turns, subagents, external MCP agents). */
+  "agents",
+  /** Pending approvals: queued proposals and paused in-chat approval cards. */
+  "pending",
+  /** One-time credentials an approval left for the operator (#971). */
+  "credentials",
+  /** Quality-audit status and the Publish gate (#553). */
+  "quality",
+  /** Site-import crawl progress (#228). */
+  "crawl",
+  /** Deploy runs (Stage, Publish live, rollback). */
+  "deploys",
+] as const;
+
+export type LiveTopic = (typeof LIVE_TOPICS)[number];
+
+const TOPIC_SET: ReadonlySet<string> = new Set(LIVE_TOPICS);
+
+/** Is `value` a known topic? */
+export function isLiveTopic(value: string): value is LiveTopic {
+  return TOPIC_SET.has(value);
+}
+
+/**
+ * Parse a comma-separated topic list (a query parameter). Unknown names are
+ * an error, not dropped: a client asking for a topic the server does not
+ * know would otherwise wait for an event that can never come.
+ */
+export function parseLiveTopics(
+  raw: string | null,
+): { ok: true; topics: LiveTopic[] } | { ok: false; unknown: string[] } {
+  const names = (raw ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  const unknown = names.filter((n) => !isLiveTopic(n));
+  if (unknown.length > 0) return { ok: false, unknown };
+  return { ok: true, topics: [...new Set(names)] as LiveTopic[] };
+}
+
+// Write ops per topic. Heartbeats (`chat.heartbeat_agent_run`,
+// `chat.renew_turn_lease`) and the audit worker's idle `claim_next` are left
+// out on purpose: they commit on a clock, and a hint on a clock is the very
+// polling this replaces.
+const EXACT: Readonly<Record<string, readonly LiveTopic[]>> = {
+  "chat.register_agent_run": ["agents"],
+  "chat.finish_agent_run": ["agents"],
+  "chat.cancel_agents": ["agents"],
+  "chat.allow_external_agent": ["agents"],
+  // An external agent's tool call: first sight of it lists it as running,
+  // and it may have queued a card.
+  "chat.touch_external_agent": ["agents", "pending"],
+  "chat.record_turn_approvals": ["pending"],
+  "chat.decide_turn_approval": ["pending"],
+  "chat.supersede_turn_approvals": ["pending"],
+  "chat.claim_turn_approvals": ["pending"],
+  // Proposal flows whose op names do not follow propose_* / *_proposal.
+  "skills.review_proposal": ["pending"],
+  "gateway.execute_rate_limit_proposal": ["pending"],
+  "gateway.reject_rate_limit_proposal": ["pending"],
+  "plugins.approve_installation": ["pending"],
+  "credentials.issue": ["credentials"],
+  "chat.stage": ["quality", "deploys"],
+  "chat.unstage": ["quality"],
+  "chat.finalize_stage": ["quality", "deploys"],
+  "chat.finalize_draft_stage": ["quality", "deploys"],
+  "chat.publish": ["quality", "deploys"],
+  "quality_audits.enqueue": ["quality"],
+  "quality_audits.record_result": ["quality"],
+  "quality_audits.retry": ["quality"],
+  "quality_audits.claim_chat_notification": ["quality"],
+  "quality_audits.ack_chat_notification": ["quality"],
+  "quality_audits.release_chat_notification": ["quality"],
+  "quality_audits.publish_anyway": ["quality"],
+  "imports.create_run": ["crawl"],
+  "imports.update_run_status": ["crawl"],
+  "imports.write_extracted_pages": ["crawl"],
+  "deploy.trigger": ["deploys"],
+  // #1211 — the Stage's steps: its run appears, ends failed, ends recorded.
+  "deploy.start_trigger": ["deploys"],
+  "deploy.fail_run": ["deploys"],
+  "deploy.finish_trigger": ["deploys"],
+  "deploy.begin_run": ["deploys"],
+  "deploy.update_progress": ["deploys"],
+  "deploy.promote": ["deploys"],
+  "deploy.rollback": ["deploys"],
+  "deploy.build_plugin_data": ["deploys"],
+};
+
+/**
+ * The topics a committed operation touches (empty for every other op).
+ *
+ * Every proposal op (`<domain>.propose_*`, `.execute_proposal`,
+ * `.reject_proposal`, `.cancel_proposal`) moves the pending strip; an
+ * applied proposal may also leave a one-time credential (#971) and, for
+ * the quality and deploy domains, move their state.
+ *
+ * @example liveTopicsOfOperation("users.execute_proposal") // ["pending", "credentials"]
+ */
+export function liveTopicsOfOperation(operationName: string): readonly LiveTopic[] {
+  const exact = EXACT[operationName];
+  if (exact) return exact;
+  const dot = operationName.lastIndexOf(".");
+  const domain = operationName.slice(0, dot);
+  const action = operationName.slice(dot + 1);
+  const extra: LiveTopic[] =
+    domain === "quality_audits" ? ["quality"] : domain === "deploy" ? ["deploys"] : [];
+  if (action === "execute_proposal") return ["pending", "credentials", ...extra];
+  if (
+    action === "propose" ||
+    action.startsWith("propose_") ||
+    action === "reject_proposal" ||
+    action === "cancel_proposal"
+  ) {
+    return ["pending"];
+  }
+  return [];
+}

package/src/markup-structure.test.ts

@@ -158,6 +158,53 @@ describe("templates and free regions", () => {
     expect(freeRegions(root, parseMarkup(stripMustache(template)))).toBeNull();
   });
 
+  it("a section inside a tag is optional: dropped by default, kept on request (#1104)", () => {
+    const t =
+      '<div class="wrapc split {{#reverse}}rev{{/reverse}}" data-x="{{^a}}1{{/a}}"><p>{{t}}</p></div>';
+    expect(stripMustache(t)).toBe('<div class="wrapc split " data-x=""><p></p></div>');
+    expect(stripMustache(t, { keepOptionalAttributeText: true })).toBe(
+      '<div class="wrapc split rev" data-x="1"><p></p></div>',
+    );
+    // A section between elements still renders its body once (a list).
+    expect(stripMustache('<ul>{{#items}}<li class="i">{{.}}</li>{{/items}}</ul>')).toBe(
+      '<ul><li class="i"></li></ul>',
+    );
+    // A `>` inside a quoted value or a partial does not end the tag.
+    expect(stripMustache('<a title="x>y" class="{{#on}}on{{/on}}">{{>p}}</a>')).toBe(
+      '<a title="x>y" class=""></a>',
+    );
+    const started = performance.now();
+    stripMustache(`<a ${"{{#x}}".repeat(50_000)}>`);
+    expect(performance.now() - started).toBeLessThan(500);
+  });
+
+  it("an optional class does not make renders without it free markup (#1104)", () => {
+    const tpl =
+      '<section class="sec"><div class="wrapc split {{#reverse}}rev{{/reverse}}"><h2>{{t}}</h2><div class="body">{{{body}}}</div></div></section>';
+    const template = parseMarkup(stripMustache(tpl));
+    for (const cls of ["wrapc split", "wrapc split rev"]) {
+      const rendered = parseMarkup(
+        `<section class="sec" data-caelo-module-id="m1"><div class="${cls}"><h2>Hi</h2><div class="body"><p>x</p></div></div></section>`,
+      );
+      const root = moduleRoots(rendered)[0];
+      if (!root) throw new Error("no module root");
+      expect(freeRegions(root, template)?.map((n) => n.tag)).toEqual(["p"]);
+    }
+  });
+
+  it("a root whose classes all sit in sections is still checked (#1104)", () => {
+    const tpl =
+      '<div class="{{#moment}}moment{{/moment}}{{^moment}}sec{{/moment}}"><h2>{{t}}</h2><div class="body">{{{body}}}</div></div>';
+    const rendered = parseMarkup(
+      `<div class="sec" data-caelo-module-id="m1"><h2>Hi</h2><div class="body">${chain(["a", "b"])}</div></div>`,
+    );
+    const root = moduleRoots(rendered)[0];
+    if (!root) throw new Error("no module root");
+    const free = freeRegions(root, parseMarkup(stripMustache(tpl)));
+    expect(free).not.toBeNull();
+    expect(outermostPatterns(free ?? []).map((f) => f.node.classes[0])).toEqual(["chain"]);
+  });
+
   it("templateShape fingerprints the template's root element", () => {
     const t = templateShape(
       '<div class="chain">{{#steps}}<div class="step"><span class="n">{{n}}</span><p>{{t}}</p></div><span class="arrow"></span>{{/steps}}</div>',

package/src/markup-structure.ts

@@ -120,13 +120,84 @@ function splitClasses(raw: string | undefined): string[] {
   return [...new Set(raw.split(/\s+/).filter((c) => c.length > 0))].sort();
 }
 
+/** Options of {@link stripMustache}. */
+export interface StripMustacheOptions {
+  /**
+   * Keep the text of a section inside a tag (`class="a {{#s}}b{{/s}}"` →
+   * `class="a b"`): every class the template CAN render. Default false:
+   * such a section is dropped, leaving the classes it ALWAYS renders.
+   */
+  readonly keepOptionalAttributeText?: boolean;
+}
+
 /**
  * Remove Mustache tags (`{{x}}`, `{{{x}}}`, `{{#s}}`, `{{/s}}`, `{{>p}}`)
  * from a module template so it parses as the markup it renders: a section
- * body stays once, a placeholder becomes empty.
+ * body between elements stays once (a list renders it per entry), a
+ * placeholder becomes empty.
+ *
+ * A section INSIDE a tag (`<div class="split {{#reverse}}rev{{/reverse}}">`,
+ * a boolean variant) is optional: the rendered element may or may not
+ * carry its text. By default it is dropped, so the template node has only
+ * the classes every render has (#1104). Keeping it made `rev` a required
+ * class — every render without it looked like free markup — and a root
+ * whose classes all sit in sections matched no render, so the module's
+ * free markup went unchecked.
+ */
+export function stripMustache(template: string, opts: StripMustacheOptions = {}): string {
+  const base = opts.keepOptionalAttributeText ? template : dropInTagSections(template);
+  return stripDelimited(stripDelimited(base, 3), 2);
+}
+
+/**
+ * Remove every `{{#s}}…{{/s}}` / `{{^s}}…{{/s}}` that opens inside a tag
+ * (between `<name` and its `>`), body included. One linear scan; Mustache
+ * tags are skipped whole, so a `>` in `{{>partial}}` never ends a tag.
  */
-export function stripMustache(template: string): string {
-  return stripDelimited(stripDelimited(template, 3), 2);
+function dropInTagSections(text: string): string {
+  let out = "";
+  let i = 0;
+  let inTag = false;
+  let quote: string | null = null;
+  // Names with no closer after some point have none after any later point
+  // either: remembering them keeps the scan linear on unclosed openers.
+  const unclosed = new Set<string>();
+  while (i < text.length) {
+    if (text.startsWith("{{", i)) {
+      const end = text.indexOf("}}", i + 2);
+      if (end < 0) break;
+      const sigil = text[i + 2];
+      if (inTag && (sigil === "#" || sigil === "^")) {
+        const name = text.slice(i + 3, end).trim();
+        const closer = `{{/${name}}}`;
+        const close = unclosed.has(name) ? -1 : text.indexOf(closer, end + 2);
+        if (close < 0) unclosed.add(name);
+        if (name.length > 0 && close >= 0) {
+          i = close + closer.length;
+          continue;
+        }
+      }
+      out += text.slice(i, end + 2);
+      i = end + 2;
+      continue;
+    }
+    const ch = text[i] as string;
+    if (inTag) {
+      if (quote !== null) {
+        if (ch === quote) quote = null;
+      } else if (ch === '"' || ch === "'") {
+        quote = ch;
+      } else if (ch === ">") {
+        inTag = false;
+      }
+    } else if (ch === "<" && /[a-zA-Z]/.test(text[i + 1] ?? "")) {
+      inTag = true;
+      quote = null;
+    }
+    out += ch;
+    i++;
+  }
+  return out + text.slice(i);
 }
 
 /**

package/src/media.ts

@@ -394,6 +394,18 @@ export type MediaSetCdnInput = z.infer<typeof mediaSetCdnInputSchema>;
 export interface MediaStorageAdapter {
   put(key: string, body: Uint8Array, contentType: string): Promise<void>;
   get(key: string): Promise<Uint8Array>;
+  /**
+   * #1216 — the object's size in bytes without reading it, so a caller can
+   * refuse an oversized object before it is loaded. Throws when the key
+   * does not exist.
+   */
+  size(key: string): Promise<number>;
+  /**
+   * #1216 — the object as a byte stream plus its size, for serving it
+   * without holding the whole file in memory. Throws when the key does not
+   * exist.
+   */
+  openStream(key: string): Promise<{ body: ReadableStream<Uint8Array>; sizeBytes: number }>;
   delete(key: string): Promise<void>;
   exists(key: string): Promise<boolean>;
   /** Bytes-on-disk for capacity reporting. */

package/src/module-id-tag.test.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { tagModuleId } from "./module-id-tag.js";
+
+describe("tagModuleId", () => {
+  it("stamps the first opening tag", () => {
+    expect(tagModuleId('<p class="a">hi</p>', "m1")).toBe(
+      '<p class="a" data-caelo-module-id="m1">hi</p>',
+    );
+  });
+
+  it("keeps a self-closing root self-closed (#1099)", () => {
+    expect(tagModuleId('<line x1="0" stroke="#E3E7EE"/>', "m1")).toBe(
+      '<line x1="0" stroke="#E3E7EE" data-caelo-module-id="m1"/>',
+    );
+    expect(tagModuleId('<circle r="2" />', "m1")).toBe('<circle r="2" data-caelo-module-id="m1"/>');
+    expect(tagModuleId("<br/>", "m1")).toBe('<br data-caelo-module-id="m1"/>');
+  });
+
+  it("does not mistake a slash inside a quoted value for self-closing", () => {
+    expect(tagModuleId('<a href="/">x</a>', "m1")).toBe(
+      '<a href="/" data-caelo-module-id="m1">x</a>',
+    );
+  });
+
+  it("is idempotent", () => {
+    const once = tagModuleId('<polyline points="0,0 1,1"/>', "m1");
+    expect(tagModuleId(once, "m2")).toBe(once);
+  });
+
+  it("stays linear on a long whitespace run inside the root tag", () => {
+    const html = `<div${"\t".repeat(200_000)}x>`;
+    const start = performance.now();
+    expect(tagModuleId(html, "m1").endsWith(' data-caelo-module-id="m1">')).toBe(true);
+    expect(performance.now() - start).toBeLessThan(500);
+  });
+});