@caelo-cms/shared 0.11.0 → 0.11.2

package/src/lists/list-fixtures.test.ts

@@ -12,7 +12,7 @@
  */
 
 import { createSiteLinkIndex, type LinkPageVariant } from "../link-refs.js";
-import { DEFAULT_LIST_TYPES } from "./default-types.js";
+import { DEFAULT_LIST_TYPES, SITE_TEXTS_TYPE } from "./default-types.js";
 import type { ListItem } from "./items.js";
 import type { ListTypeDef } from "./list-type.js";
 import type {
@@ -116,6 +116,7 @@ const page = (
 ): ListPageRecord => ({
   id: pageId,
   title,
+  shortTitle: title,
   parentId: null,
   pageTypeSlug: "page",
   properties: {},
@@ -242,12 +243,16 @@ export function fixtureData(
     overlays?: ReadonlyMap<string, ListVariantOverlay>;
     pageVariants?: ReadonlyMap<string, LinkPageVariant>;
     pages?: readonly ListPageRecord[];
+    /** Default: the fixture home page. */
+    homePageId?: string | null;
+    /** Shared lists added to the fixture ones (e.g. a site texts list). */
+    lists?: readonly LoadedList[];
   } = {},
 ): ListRenderData {
-  const types = [...DEFAULT_LIST_TYPES, MEGA_MENU_TYPE];
+  const types = [...DEFAULT_LIST_TYPES, MEGA_MENU_TYPE, SITE_TEXTS_TYPE];
   return {
     listTypes: new Map(types.map((t, i) => [t.slug, { id: id(600 + i), def: t }])),
-    lists: new Map(LISTS.map((l) => [l.id, l])),
+    lists: new Map([...LISTS, ...(extra.lists ?? [])].map((l) => [l.id, l])),
     pageTypes: new Map([
       [
         "news",
@@ -273,6 +278,7 @@ export function fixtureData(
     ...(extra.pageVariants ? { pageVariants: extra.pageVariants } : {}),
     ...(extra.overlays ? { overlays: extra.overlays } : {}),
     siteLanguage: "en",
+    homePageId: extra.homePageId === undefined ? PAGE.home : extra.homePageId,
   };
 }
 

package/src/lists/render-data.ts

@@ -44,6 +44,8 @@ export interface LoadedPageType {
 export interface ListPageRecord {
   readonly id: string;
   readonly title: string;
+  /** `pages.short_title`: the page's label in breadcrumbs and navigation (#1142). */
+  readonly shortTitle: string;
   readonly parentId: string | null;
   readonly pageTypeSlug: string;
   readonly properties: Readonly<Record<string, unknown>>;
@@ -101,6 +103,13 @@ export interface ListRenderData {
   readonly overlays?: ReadonlyMap<string, ListVariantOverlay>;
   /** `site_settings.site_language`, for `{{date.formatted}}`. */
   readonly siteLanguage: string;
+  /**
+   * `site_defaults.home_page_id`: where every breadcrumb trail starts
+   * (#1142). A variant page's trail starts at the home page's version in
+   * that variant (same `link-resolve` group). Null while no home page is
+   * designated.
+   */
+  readonly homePageId: string | null;
 }
 
 /** Render dependencies one page collected (build manifest `render-deps.json`). */

package/src/lists/render-deps.ts

@@ -20,7 +20,7 @@
 import type { ListPageRecord, ListRenderDeps } from "./render-data.js";
 
 export const RENDER_DEPS_FILE = "render-deps.json";
-export const RENDER_DEPS_VERSION = 2;
+export const RENDER_DEPS_VERSION = 3;
 
 /** A page's filter-relevant attributes as of a build. */
 export interface RenderDepsPageAttrs {
@@ -28,6 +28,7 @@ export interface RenderDepsPageAttrs {
   readonly terms: readonly string[];
   readonly parent: string | null;
   readonly title: string;
+  readonly shortTitle: string;
   readonly inBuild: boolean;
 }
 
@@ -47,6 +48,7 @@ export function renderDepsAttrs(p: ListPageRecord): RenderDepsPageAttrs {
     terms: [...p.terms].sort(),
     parent: p.parentId,
     title: p.title,
+    shortTitle: p.shortTitle,
     inBuild: p.inBuild,
   };
 }
@@ -92,8 +94,8 @@ export interface RenderChange {
  *   page's attributes before OR after the change (entered, left or
  *   changed inside the filter);
  * - every page with page-tree deps (breadcrumbs, children, siblings,
- *   term pages) when a changed page's title, parent or build membership
- *   changed;
+ *   term pages) when a changed page's title, short title, parent or
+ *   build membership changed;
  * - every page whose system source rendered a changed page as an entry
  *   (its `props`, `terms`, `updated_at` show there).
  *
@@ -119,6 +121,7 @@ export function selectDependentPages(
       !before ||
       !after ||
       before.title !== after.title ||
+      before.shortTitle !== after.shortTitle ||
       before.parent !== after.parent ||
       before.inBuild !== after.inBuild
     ) {

package/src/lists/resolve.test.ts

@@ -8,9 +8,17 @@
 
 import { describe, expect, it } from "bun:test";
 import type { LinkPageVariant } from "../link-refs.js";
-import { fixtureData, fixtureLinkIndex, ITEM, LIST, PAGE, TERM } from "./list-fixtures.test.js";
+import {
+  fixtureData,
+  fixtureLinkIndex,
+  ITEM,
+  LIST,
+  PAGE,
+  PAGES,
+  TERM,
+} from "./list-fixtures.test.js";
 import type { QueryKnob } from "./list-type.js";
-import type { ListVariantOverlay } from "./render-data.js";
+import type { ListPageRecord, ListVariantOverlay, LoadedList } from "./render-data.js";
 import {
   createListRenderContext,
   type ListFieldSpec,
@@ -126,8 +134,9 @@ describe("system sources", () => {
     source: { kind: "system", name },
   });
 
-  it("breadcrumbs run root → current", () => {
+  it("breadcrumbs run home → root → current", () => {
     expect(entries(page(PAGE.team), sys("breadcrumbs")).map((e) => textOf(e, "title"))).toEqual([
+      "Home",
       "About",
       "Team",
     ]);
@@ -263,8 +272,8 @@ describe("render dependencies", () => {
       listTypes: ["menu"],
       queries: [{ pageType: "news", terms: [TERM.event], parent: null }],
       pageTree: true,
-      // The breadcrumb trail's pages: their values render as entries.
-      pages: [PAGE.about, PAGE.team].sort(),
+      // The breadcrumb trail's pages (home included): their values render as entries.
+      pages: [PAGE.home, PAGE.about, PAGE.team].sort(),
     });
   });
 
@@ -293,3 +302,171 @@ describe("render dependencies", () => {
     expect(ctx.deps().lists).toEqual([LIST.tags]);
   });
 });
+
+describe("breadcrumbs (#1142)", () => {
+  const CRUMBS: ListFieldSpec = {
+    name: "crumbs",
+    listType: "links",
+    bind: "source",
+    source: { kind: "system", name: "breadcrumbs" },
+  };
+  const at = (id: string): ListPageRecord => PAGES.find((p) => p.id === id) as ListPageRecord;
+  const withShort = (id: string, shortTitle: string): ListPageRecord => ({ ...at(id), shortTitle });
+
+  it("labels crumbs with the short title and marks every crumb but the last as ancestor", () => {
+    const data = fixtureData({
+      pages: PAGES.map((p) =>
+        p.id === PAGE.home
+          ? withShort(PAGE.home, "Start")
+          : p.id === PAGE.about
+            ? withShort(PAGE.about, "Us")
+            : p,
+      ),
+    });
+    const ctx = page(PAGE.team, data);
+    const got = entries(ctx, CRUMBS);
+    expect(got.map((e) => textOf(e, "short_title"))).toEqual(["Start", "Us", "Team"]);
+    expect(got.map((e) => e.get("is_ancestor"))).toEqual([
+      { kind: "bool", value: true },
+      { kind: "bool", value: true },
+      { kind: "bool", value: false },
+    ]);
+    expect(got.map((e) => e.get("is_current"))).toEqual([
+      { kind: "bool", value: false },
+      { kind: "bool", value: false },
+      { kind: "bool", value: true },
+    ]);
+    expect(ctx.breadcrumbTrail()).toEqual([PAGE.home, PAGE.about, PAGE.team]);
+    expect(ctx.deps().pageTree).toBe(true);
+    expect(ctx.deps().pages).toEqual([PAGE.home, PAGE.about, PAGE.team].sort());
+  });
+
+  it("the home page's own trail is the home page alone", () => {
+    const ctx = page(PAGE.home);
+    expect(entries(ctx, CRUMBS).map((e) => textOf(e, "title"))).toEqual(["Home"]);
+    expect(ctx.breadcrumbTrail()).toEqual([PAGE.home]);
+  });
+
+  it("without a designated home the trail is the page tree alone", () => {
+    const ctx = page(PAGE.team, fixtureData({ homePageId: null }));
+    expect(entries(ctx, CRUMBS).map((e) => textOf(e, "title"))).toEqual(["About", "Team"]);
+  });
+
+  it("a page that renders no breadcrumbs records no trail", () => {
+    expect(page(PAGE.team).breadcrumbTrail()).toBeNull();
+  });
+
+  it("follows the page tree as it is: a moved page's trail needs no edit", () => {
+    // Team moved from About to News.
+    const moved = PAGES.map((p) => (p.id === PAGE.team ? { ...p, parentId: PAGE.news } : p));
+    const ctx = page(PAGE.team, fixtureData({ pages: moved }));
+    expect(entries(ctx, CRUMBS).map((e) => textOf(e, "title"))).toEqual(["Home", "News", "Team"]);
+  });
+
+  describe("variants", () => {
+    const HOME_DE = "00000000-0000-4000-8000-0000000000d1";
+    const ABOUT_DE = "00000000-0000-4000-8000-0000000000d2";
+    const pages = [
+      ...PAGES,
+      { ...withShort(PAGE.home, "Startseite"), id: HOME_DE },
+      { ...withShort(PAGE.about, "Über uns"), id: ABOUT_DE },
+    ];
+    const pageVariants = new Map<string, LinkPageVariant>([
+      [PAGE.home, { variant: "en", group: "g-home" }],
+      [PAGE.about, { variant: "en", group: "g-about" }],
+      [HOME_DE, { variant: "de", group: "g-home" }],
+      [ABOUT_DE, { variant: "de", group: "g-about" }],
+    ]);
+
+    it("a variant page's trail starts at the home page's version in that variant", () => {
+      const ctx = page(ABOUT_DE, fixtureData({ pages, pageVariants }));
+      expect(entries(ctx, CRUMBS).map((e) => textOf(e, "short_title"))).toEqual([
+        "Startseite",
+        "Über uns",
+      ]);
+    });
+
+    it("a variant without a version of the home page shows no home crumb", () => {
+      const fr = new Map(pageVariants).set(ABOUT_DE, { variant: "fr", group: "g-about" });
+      const ctx = page(ABOUT_DE, fixtureData({ pages, pageVariants: fr }));
+      expect(entries(ctx, CRUMBS).map((e) => textOf(e, "short_title"))).toEqual(["Über uns"]);
+    });
+  });
+});
+
+describe("site texts (#1142)", () => {
+  const SITE_TEXTS = "00000000-0000-4000-8000-0000000000e1";
+  const LABEL = "00000000-0000-4000-9000-0000000000e1";
+  const MORE = "00000000-0000-4000-9000-0000000000e2";
+  const list = (items: LoadedList["items"], id = SITE_TEXTS): LoadedList => ({
+    id,
+    slug: id === SITE_TEXTS ? "site-texts" : "more-texts",
+    name: "Site texts",
+    typeSlug: "site-texts",
+    items,
+  });
+  const text = (itemId: string, key: string, value: string) => ({
+    id: itemId,
+    node: "text",
+    values: { key, text: value },
+  });
+  const read = (ctx: ListPageContext, key: string) => ctx.siteTextScope().get(key);
+
+  it("reads a text by key and records the list as a dependency", () => {
+    const ctx = page(
+      PAGE.about,
+      fixtureData({ lists: [list([text(LABEL, "breadcrumb_label", "Breadcrumb")])] }),
+    );
+    expect(read(ctx, "breadcrumb_label")).toEqual({ kind: "text", text: "Breadcrumb" });
+    expect(ctx.deps().lists).toContain(SITE_TEXTS);
+    expect(ctx.deps().listTypes).toContain("site-texts");
+  });
+
+  it("an unknown key is loud, never empty", () => {
+    const ctx = page(PAGE.about, fixtureData({ lists: [list([])] }));
+    expect(read(ctx, "breadcrumb_label")).toEqual({
+      kind: "failed",
+      marker: "site-text-missing:breadcrumb_label",
+    });
+  });
+
+  it("a key defined twice is loud", () => {
+    const ctx = page(
+      PAGE.about,
+      fixtureData({
+        lists: [
+          list([text(LABEL, "read_more", "Read more")]),
+          list([text(MORE, "read_more", "More")], "00000000-0000-4000-8000-0000000000e2"),
+        ],
+      }),
+    );
+    expect(read(ctx, "read_more")).toEqual({
+      kind: "failed",
+      marker: "site-text-duplicate:read_more",
+    });
+  });
+
+  it("a variant's overlay translates the text", () => {
+    const data = fixtureData({
+      lists: [list([text(LABEL, "breadcrumb_label", "Breadcrumb")])],
+      pageVariants: new Map([[PAGE.about, { variant: "de", group: null }]]),
+      overlays: new Map([
+        [
+          "de",
+          {
+            values: new Map([[`list/${SITE_TEXTS}/item/${LABEL}/text`, "Brotkrumen"]]),
+            hidden: new Set<string>(),
+          },
+        ],
+      ]),
+    });
+    expect(read(page(PAGE.about, data), "breadcrumb_label")).toEqual({
+      kind: "text",
+      text: "Brotkrumen",
+    });
+    expect(read(page(PAGE.home, data), "breadcrumb_label")).toEqual({
+      kind: "text",
+      text: "Breadcrumb",
+    });
+  });
+});

package/src/lists/resolve.ts

@@ -24,6 +24,7 @@
 
 import type { LinkResolver } from "../link-refs.js";
 import { parseLinkRef } from "../link-refs.js";
+import { SITE_TEXTS_LIST_TYPE } from "./default-types.js";
 import { type FieldDef, TERM_REF_RE, validateFieldValue } from "./fields.js";
 import type { ListItem } from "./items.js";
 import {
@@ -125,6 +126,19 @@ export interface ListPageContext {
   resolveField(field: ListFieldSpec, value: unknown, holder: ListHolder): ListFieldResolution;
   /** `{{page.*}}`: the rendering page as a record scope; null outside a page. */
   pageScope(): ScopeValue | null;
+  /**
+   * `{{site_text.<key>}}`: the site texts (entries of every list of type
+   * {@link SITE_TEXTS_LIST_TYPE}) in the rendering page's variant. An
+   * unknown or duplicate key resolves to a failure marker (#1142).
+   */
+  siteTextScope(): ScopeValue;
+  /**
+   * The page ids of the breadcrumb trail this render showed (home →
+   * current), or null when no `breadcrumbs` source rendered. Drives the
+   * `BreadcrumbList` JSON-LD, so structured data always matches the
+   * visible trail (#1142).
+   */
+  breadcrumbTrail(): readonly string[] | null;
   /**
    * A section name no module field declares, read as a plugin list
    * source (`{{#language_links}}` written before the field kind existed).
@@ -420,6 +434,7 @@ function createPageContext(
   >();
   let depTree = false;
   const depPages = new Set<string>();
+  let trail: readonly string[] | null = null;
   /** Entries of a page-shaped system source: their pages become deps. */
   const readPages = (pages: ListPageRecord[]): ListPageRecord[] => {
     for (const pg of pages) depPages.add(pg.id);
@@ -696,6 +711,8 @@ function createPageContext(
           return text(p.id);
         case "title":
           return text(p.title);
+        case "short_title":
+          return text(p.shortTitle);
         case "link":
           return linkValue({ href: `caelo:page/${p.id}` }, data);
         case "published_at":
@@ -728,19 +745,48 @@ function createPageContext(
     };
   };
 
-  const pageEntries = (pages: readonly ListPageRecord[]): ScopeEntry[] =>
+  /**
+   * Page-shaped entries. `ancestor` overrides `is_ancestor` where the
+   * source knows better than the page tree: a breadcrumb trail's home
+   * crumb sits above the current page without being its parent.
+   */
+  const pageEntries = (
+    pages: readonly ListPageRecord[],
+    ancestor?: (p: ListPageRecord, index: number) => boolean,
+  ): ScopeEntry[] =>
     pages.map((p, index) => {
       const get = pageValue(p);
       const pos = { index, count: pages.length, depth: 1 };
+      const isAncestor = ancestor ? bool(ancestor(p, index)) : undefined;
       return {
         id: p.id,
         itemAttr: null,
         childrenKey: null,
         depth: 1,
-        get: (key) => get(key) ?? positionValue(key, pos),
+        get: (key) =>
+          (key === "is_ancestor" ? isAncestor : undefined) ?? get(key) ?? positionValue(key, pos),
       };
     });
 
+  /**
+   * The home page in the rendering page's variant: the designated home
+   * itself, or its version in the variant's `link-resolve` group. Null
+   * when no home is designated or the variant has no version of it yet
+   * (an untranslated home is absent, never the other language's page).
+   */
+  const homeOfVariant = (): ListPageRecord | null => {
+    if (data.homePageId === null) return null;
+    const home = data.pages.get(data.homePageId) ?? null;
+    if (home === null || variant === null) return home;
+    const hv = data.pageVariants?.get(home.id);
+    if (hv === undefined || hv.variant === variant) return home;
+    if (hv.group === null) return null;
+    for (const [id, v] of data.pageVariants ?? []) {
+      if (v.group === hv.group && v.variant === variant) return data.pages.get(id) ?? null;
+    }
+    return null;
+  };
+
   const sameVariant = (p: ListPageRecord): boolean =>
     variant === null || data.pageVariants?.get(p.id)?.variant === variant;
 
@@ -792,7 +838,13 @@ function createPageContext(
           seen.add(p.id);
           p = p.parentId === null ? undefined : data.pages.get(p.parentId);
         }
-        return listValue(pageEntries(readPages(chain)));
+        // The home page is no parent in the tree, yet every trail starts
+        // there; its short name is the "Start" crumb, translated with it.
+        const home = homeOfVariant();
+        if (home && !seen.has(home.id)) chain.unshift(home);
+        trail = chain.map((pg) => pg.id);
+        const last = chain.length - 1;
+        return listValue(pageEntries(readPages(chain), (_pg, index) => index < last));
       }
       case "children": {
         depTree = true;
@@ -1039,10 +1091,56 @@ function createPageContext(
     return { ok: true, entries: entriesOf(checked.items, local, 1) };
   };
 
+  let siteTextMemo: ScopeValue | undefined;
+  /** `{{site_text.<key>}}` — see {@link ListPageContext.siteTextScope}. */
+  const siteTextScope = (): ScopeValue => {
+    if (siteTextMemo !== undefined) return siteTextMemo;
+    depTypes.add(SITE_TEXTS_LIST_TYPE);
+    const byKey = new Map<string, { list: LoadedList; item: ListItem }[]>();
+    for (const list of data.lists.values()) {
+      if (list.typeSlug !== SITE_TEXTS_LIST_TYPE) continue;
+      depLists.add(list.id);
+      for (const item of list.items) {
+        if (overlay?.listHidden.has(`${list.id}/${item.id}`)) continue;
+        const key = item.values.key;
+        if (typeof key !== "string") continue;
+        byKey.set(key, [...(byKey.get(key) ?? []), { list, item }]);
+      }
+    }
+    const memo = new Map<string, ScopeValue>();
+    siteTextMemo = {
+      kind: "record",
+      text: null,
+      present: true,
+      get(key) {
+        const hit = memo.get(key);
+        if (hit) return hit;
+        const found = byKey.get(key) ?? [];
+        let v: ScopeValue;
+        if (found.length === 0) v = { kind: "failed", marker: `site-text-missing:${key}` };
+        else if (found.length > 1) v = { kind: "failed", marker: `site-text-duplicate:${key}` };
+        else {
+          const { list, item } = found[0] as { list: LoadedList; item: ListItem };
+          const translated = overlay?.listValues.get(`${list.id}/${item.id}`)?.get("text");
+          const raw = translated ?? item.values.text;
+          v =
+            typeof raw === "string"
+              ? text(raw)
+              : { kind: "failed", marker: `site-text-missing:${key}` };
+        }
+        memo.set(key, v);
+        return v;
+      },
+    };
+    return siteTextMemo;
+  };
+
   let pageScopeMemo: ScopeValue | null | undefined;
   return {
     pageId,
     resolveField,
+    siteTextScope,
+    breadcrumbTrail: () => trail,
     pageScope: () => {
       if (pageScopeMemo === undefined) {
         if (current === null) pageScopeMemo = null;

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>',