@promptctl/cc-candybar 1.30.0 → 1.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.30.0",
+  "version": "1.32.0",
   "description": "Statusline renderer for Claude Code — a JSON5-configurable DSL with daemon-cached data sources, byte-clean palette-aware composition, and OSC8 click verbs.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -91,9 +91,9 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.30.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.30.0",
-    "@promptctl/cc-candybar-linux-x64": "1.30.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.30.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.32.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.32.0",
+    "@promptctl/cc-candybar-linux-x64": "1.32.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.32.0"
   }
 }

package/schema/cc-candybar.schema.json

@@ -1364,6 +1364,47 @@
             ],
             "additionalProperties": false
           },
+          {
+            "type": "object",
+            "properties": {
+              "persist": {
+                "type": "string"
+              },
+              "insertSegmentFrom": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "minItems": 1,
+                    "uniqueItems": true
+                  }
+                ]
+              },
+              "anchor": {
+                "type": "string"
+              },
+              "relation": {
+                "enum": [
+                  "before",
+                  "after"
+                ]
+              }
+            },
+            "required": [
+              "persist",
+              "insertSegmentFrom",
+              "anchor",
+              "relation"
+            ],
+            "additionalProperties": false
+          },
           {
             "type": "object",
             "properties": {
@@ -1399,6 +1440,30 @@
               "reset"
             ],
             "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "undo": {
+                "const": true
+              }
+            },
+            "required": [
+              "undo"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "redo": {
+                "const": true
+              }
+            },
+            "required": [
+              "redo"
+            ],
+            "additionalProperties": false
           }
         ]
       }

package/src/click/wire.ts

@@ -77,6 +77,15 @@ export const VERB_RESET_CONFIG = "reset-config";
 // differs, which is exactly why this is its own verb rather than another
 // VERB_SET_CONFIG value.
 export const VERB_APPLY_LAYOUT_OP = "apply-layout-op";
+// [LAW:one-source-of-truth] brandon-layout-edit-2gc.2's global history step
+// over the config-overrides layer — the fine-grained sibling of
+// VERB_RESET_CONFIG's coarse "clear one key". Args: `[sessionId]` — there is
+// no key: the history is ONE stack over every persist/reset write ever made
+// to the overrides file (config-overrides-store.ts), not a per-key log. An
+// empty stack is a loud BAD_REQUEST surfaced through click.error like any
+// other verb failure, never a silent no-op.
+export const VERB_UNDO = "undo";
+export const VERB_REDO = "redo";
 
 // [LAW:types-are-the-program] An effect to EMIT: a verb plus its raw (unencoded)
 // positional args. The wire owns all encoding — callers never percent-encode.

package/src/config/action.ts

@@ -43,7 +43,24 @@ export type { OptionDomain } from "./option-domain.js";
 // overrides layer (never the hand-authored config file). `reset` clears one
 // persisted override — the gated undo `persist` needs, since a machine-owned
 // write with no way back would be a one-way ratchet.
-export const ACTION_KEYS = ["set", "persist", "copy", "open", "reset"] as const;
+//
+// [LAW:one-source-of-truth] `undo`/`redo` (brandon-layout-edit-2gc.2) are
+// `reset`'s FINE-GRAINED siblings: `reset` clears one named key outright
+// (the coarse "forget this override" case); `undo`/`redo` step ONE GLOBAL
+// history of every `persist`/`reset` write ever made to the overrides layer
+// — every key, not just structural layout edits — back and forth. Neither
+// carries a key: the history is a single stack over the whole overrides
+// file (config-overrides-store.ts owns it), so the action is a bare marker,
+// like `int: true` is for a set-int cursor.
+export const ACTION_KEYS = [
+  "set",
+  "persist",
+  "copy",
+  "open",
+  "reset",
+  "undo",
+  "redo",
+] as const;
 export type ActionKey = (typeof ACTION_KEYS)[number];
 
 // [LAW:types-are-the-program] An ActionDecl is the click effect a named action
@@ -75,6 +92,14 @@ export type ActionKey = (typeof ACTION_KEYS)[number];
 //                         -> allow-list {members}
 //   copy                — copy templated text to the clipboard -> no gate
 //   open                — open a templated target in the editor -> no gate
+//   undo                — step the config-overrides layer's GLOBAL history one
+//                         entry back (any persist/reset write, not just a
+//                         layout op) -> no gate, no key: there is nothing a
+//                         template could smuggle, since the value restored is
+//                         whatever the daemon's own history recorded, never
+//                         wire input
+//   redo                — the inverse of undo: re-apply the most recently
+//                         undone entry -> no gate, no key
 //   removeSegment       — (persist only) remove the named segment from the
 //                         preset-root the `persist` key addresses
 //                         (`presets.<name>.rootOps`) -> allow-list {one op
@@ -83,6 +108,13 @@ export type ActionKey = (typeof ACTION_KEYS)[number];
 //     anchor + relation  — (persist only) insert a named segment before/after
 //                         an existing one, same key shape -> allow-list {one
 //                         op token}
+//   insertSegmentFrom +
+//     anchor + relation  — (persist only) insertSegment's domain-sourced
+//                         sibling (brandon-layout-edit-2gc.3): the segment
+//                         name is picked from an option domain at render
+//                         (a `{{ menu }}`'s bound option) rather than fixed
+//                         at author time -> allow-list {one op token per
+//                         domain member}
 //
 // [LAW:one-source-of-truth] `set` writes SessionState and `persist` writes
 // the config-overrides layer, so only those two derive a validator (through
@@ -131,9 +163,29 @@ export type ActionDecl =
       readonly anchor: string;
       readonly relation: "before" | "after";
     }
+  // [LAW:one-source-of-truth] brandon-layout-edit-2gc.3's DOMAIN-SOURCED
+  // sibling of `insertSegment`: the same tree op, but the segment name comes
+  // from the template's bound option (a picker/menu cell) instead of being
+  // fixed at config-author time — exactly the `to`-vs-`from` split `set`/
+  // `persist` already draw, one arm over. `anchor`/`relation` stay literal
+  // (the POSITION is still author-time data; only WHICH segment lands there
+  // is picked at render). This is what makes a `{{ menu "insertHere" }}`
+  // legal over a structural edit: `requireOptionKind` (render/picker.ts)
+  // admits it alongside set-option/persist-option, and the click writes
+  // `encodeLayoutOp({ op: "insert", segment: <picked>, anchor, relation })` —
+  // the SAME wire shape a literal `insertSegment` action emits, so undo/redo
+  // and the daemon's apply-layout-op handler need no changes at all.
+  | {
+      readonly persist: string;
+      readonly insertSegmentFrom: OptionDomain;
+      readonly anchor: string;
+      readonly relation: "before" | "after";
+    }
   | { readonly copy: string }
   | { readonly open: string }
-  | { readonly reset: string };
+  | { readonly reset: string }
+  | { readonly undo: true }
+  | { readonly redo: true };
 
 // [LAW:dataflow-not-control-flow] Does this action write a SessionState key? A
 // `set` action composes a set-state click URL whose first segment is session.id;
@@ -155,3 +207,14 @@ export function actionBindsPersist(a: ActionDecl): boolean {
 export function actionBindsReset(a: ActionDecl): boolean {
   return "reset" in a;
 }
+
+// [LAW:dataflow-not-control-flow] Does this action step the config-overrides
+// history? `undo`/`redo` carry session.id on the wire too — same reason as
+// `reset`: an empty stack is a loud, session-scoped click.error, not a
+// silent no-op (the ticket's own done-gate).
+export function actionBindsUndo(a: ActionDecl): boolean {
+  return "undo" in a;
+}
+export function actionBindsRedo(a: ActionDecl): boolean {
+  return "redo" in a;
+}

package/src/config/dsl-loader.ts

@@ -48,6 +48,8 @@ import { validateVariables } from "./loader/variables.js";
 import { validateSegments } from "./loader/segments.js";
 import { synthesizeGroupDecls, validateRoot } from "./loader/layout.js";
 import { synthesizeMenuDecls } from "./loader/menu-synth.js";
+import { synthesizeEditModeToggle } from "./loader/edit-mode.js";
+import { synthesizeEditChrome } from "./edit-chrome.js";
 import { validateActions } from "./loader/actions.js";
 import { validateLooks } from "./loader/looks.js";
 import { validatePresets } from "./loader/presets.js";
@@ -143,7 +145,15 @@ export function validateConfig(
   if (issues.length > 0) {
     throw new ConfigError(filePath, issues);
   }
-  return config as ValidatedConfig;
+  // [LAW:one-source-of-truth] Edit-mode's CHROME half (brandon-layout-edit-
+  // 2gc.3), synthesized HERE — not in parseDslConfig alongside the toggle —
+  // because it needs the fully merged, preset-resolved, rootOps-replayed
+  // tree cross-ref/cycles just proved sound. Its own output (segment refs
+  // into freshly-synthesized segments, actions into freshly-synthesized
+  // actions) is correct by construction and does not re-enter cross-ref/
+  // cycle checking, exactly as group/menu synthesis's output doesn't either.
+  const withChrome = synthesizeEditChrome(config);
+  return withChrome as ValidatedConfig;
 }
 
 /**
@@ -278,6 +288,13 @@ function validateTopLevel(
   // through deriveActionValidators, and collide loudly with any user name under
   // the reserved namespace.
   synthesizeMenuDecls(ctx, out);
+  // [LAW:one-source-of-truth] Edit-mode's TOGGLE half (brandon-layout-edit-
+  // 2gc.3) — unconditional, like the reservation above, so `edit.mode`/
+  // `edit.toggle` exist in EVERY parsed file and a hand-authored trigger
+  // segment cross-ref-checks normally. The CHROME half (the per-position +/-
+  // affordances) runs later, in validateConfig, once the merged/preset-
+  // resolved/rootOps-replayed tree exists to derive it from.
+  synthesizeEditModeToggle(ctx, out);
   return out;
 }
 

package/src/config/edit-chrome.ts

@@ -0,0 +1,329 @@
+// [LAW:one-source-of-truth] brandon-layout-edit-2gc.3's CHROME half — the
+// LOWERING that turns "edit mode is a session toggle" into "each row's
+// segments render interleaved with +/- affordances" without a render-walk
+// branch [LAW:dataflow-not-control-flow]. Follows the SAME move `kind:
+// "group"` sugar makes (src/config/loader/layout.ts): one pass produces a NEW
+// tree with synthesized nodes spliced in, each gated by an ordinary `when` —
+// the walk that renders it learns nothing new. The difference from group
+// sugar is WHEN this can run: a group is authored data, lowered per file
+// before merge; edit chrome is DERIVED from which segments are actually in
+// the tree, which is only known after merge, preset-root resolution, and
+// rootOps replay. So this runs from validateConfig, on the fully resolved
+// config each declared preset stages — see synthesizeEditChrome below.
+//
+// [LAW:single-enforcer] The +/- affordances reuse EXISTING primitives
+// wholesale rather than inventing parallel ones: `-` is an ordinary
+// `{ persist, removeSegment }` action behind `{{ action }}` (2gc.1); `+` is an
+// ordinary `{ persist, insertSegmentFrom }` action behind `{{ menu }}`
+// (2gc.3's new arm — see action.ts), synthesized by calling the SAME pure
+// functions `{{ menu }}`'s own load-time synthesis calls
+// (menu-keys.ts/disclosure.ts) so a synthesized menu and a hand-authored one
+// are indistinguishable at render. Nothing here is a new render concept.
+
+import type { ActionDecl as ActionDeclType, OptionDomain } from "./action.js";
+import type {
+  ContainerNode,
+  DslConfig,
+  LayoutNode,
+  PresetDecl,
+  SegmentDecl,
+  SegmentNode,
+  VariableDecl,
+} from "./dsl-types.js";
+import { collectSegmentNames } from "./layout-ops.js";
+import { presetByName, presetNames, presetRoot } from "./presets.js";
+import {
+  EDIT_MODE_GATE,
+  EDIT_NS,
+  EDIT_TOGGLE_ACTION,
+} from "./loader/edit-mode.js";
+import { GROUP_NS } from "./loader/layout.js";
+import {
+  menuActionName,
+  menuMember,
+  menuPageKey,
+  menuStateKey,
+  MENU_NS,
+} from "./menu-keys.js";
+import {
+  DISCLOSURE_CLOSED,
+  disclosureCycleAction,
+  disclosureStateVar,
+} from "./disclosure.js";
+
+// [LAW:one-source-of-truth] group/menu-synthesized segments (`groups.`/
+// `menus.`) and edit mode's own trigger/chrome (`edit.`) are structural —
+// removing one via `-` would strand its sibling artifacts (a toggle segment
+// with no body, a menu with no host), and offering one back via `+` would
+// insert a bare ref with none of the synthesis that made it work. Ordinary
+// content segments only.
+function isChromeExempt(name: string): boolean {
+  return (
+    name.startsWith(EDIT_NS) ||
+    name.startsWith(MENU_NS) ||
+    name.startsWith(GROUP_NS)
+  );
+}
+
+// [LAW:types-are-the-program] Collapse an arbitrary name to a template-
+// identifier-safe fragment — the SAME shape menu-keys.ts's `ident` enforces,
+// reimplemented here rather than imported (menu-keys.ts's copy is
+// module-private) since both need only the one rule: alphanumerics survive,
+// everything else collapses to `_`.
+function ident(name: string): string {
+  return name.replace(/[^A-Za-z0-9]+/g, "_");
+}
+
+// [LAW:one-source-of-truth] Every synthesized decl this pass produces, keyed
+// by its final name — one accumulator threaded through every preset's splice
+// so cross-preset names (disambiguated by `presetIdent`) can never collide.
+interface ChromeArtifacts {
+  readonly variables: Record<string, VariableDecl>;
+  readonly actions: Record<string, ActionDeclType>;
+  readonly segments: Record<string, SegmentDecl>;
+}
+
+// [LAW:one-source-of-truth] The domain name a preset's `+` pickers range —
+// computed once per preset (declared segments minus the ones already present
+// in ITS current tree) and consumed two ways: here (by name, for every
+// insertSegmentFrom action this preset's splice synthesizes) and by
+// registerDslConfig/deriveConfigActionValidators (which call
+// `addableSegmentDomains` directly to populate `perConfigDomains` before
+// resolving `from`). Both read the SAME string shape so a synthesized
+// action's domain name always resolves.
+export function addableDomainName(presetName: string): string {
+  return `${EDIT_NS}addable.${presetName}`;
+}
+
+// [LAW:one-source-of-truth] THE per-preset "what can `+` offer here" set:
+// every declared, non-exempt segment name minus the ones already present
+// anywhere in that preset's CURRENT (merged, rootOps-replayed) tree. Exported
+// so render.ts's registerDslConfig and config-validators.ts's
+// deriveConfigActionValidators — the two sites that resolve `from` domains —
+// merge this into `perConfigDomainsFor`'s map without each re-deriving it
+// [LAW:locality-or-seam]; option-domain.ts itself stays untouched (its
+// `perConfigDomainsFor` deliberately never imports dsl-types.ts — see that
+// file's own header — so a third per-preset domain merges at the two call
+// sites instead of inside it).
+export function addableSegmentDomains(
+  config: DslConfig,
+): ReadonlyMap<string, readonly string[]> {
+  const declared = Object.keys(config.segments).filter(
+    (n) => !isChromeExempt(n),
+  );
+  const domains = new Map<string, readonly string[]>();
+  for (const name of presetNames(config.presets)) {
+    const { node } = presetRoot(config, name);
+    const present = collectSegmentNames(node);
+    domains.set(
+      addableDomainName(name),
+      declared.filter((n) => !present.has(n)),
+    );
+  }
+  return domains;
+}
+
+// Synthesize the `-` affordance for one segment instance: a literal
+// `removeSegment` action plus the segment that hosts its `{{ action }}`.
+function removeChrome(
+  presetIdent: string,
+  rootOpsKey: string,
+  segName: string,
+  artifacts: ChromeArtifacts,
+): SegmentNode {
+  const actionName = `${EDIT_NS}${presetIdent}.remove.${ident(segName)}`;
+  const chromeSegName = `${EDIT_NS}${presetIdent}.removeSeg.${ident(segName)}`;
+  artifacts.actions[actionName] = {
+    persist: rootOpsKey,
+    removeSegment: segName,
+  };
+  artifacts.segments[chromeSegName] = {
+    template: `{{ action "${actionName}" "-" }}`,
+    when: EDIT_MODE_GATE,
+  };
+  return { kind: "segment", name: chromeSegName };
+}
+
+// Synthesize the `+` affordance for one gap: an `insertSegmentFrom` action
+// over this preset's addable domain, plus a segment hosting `{{ menu }}` over
+// it. The menu's own disclosure (open state, page cursor, toggle action) is
+// synthesized here by calling the SAME pure functions menu-synth.ts's
+// file-parse-time pass calls — this pass runs too late to piggyback on that
+// pass directly (it needs post-merge/post-rootOps data menu-synth.ts's
+// per-file timing does not have), so parity is achieved by sharing the
+// functions, not by re-deriving the shape.
+function insertChrome(
+  presetIdent: string,
+  rootOpsKey: string,
+  posIdent: string,
+  domainName: OptionDomain,
+  anchor: string,
+  relation: "before" | "after",
+  artifacts: ChromeArtifacts,
+): SegmentNode {
+  const applyName = `${EDIT_NS}${presetIdent}.insert.${posIdent}`;
+  const chromeSegName = `${EDIT_NS}${presetIdent}.insertSeg.${posIdent}`;
+  artifacts.actions[applyName] = {
+    persist: rootOpsKey,
+    insertSegmentFrom: domainName,
+    anchor,
+    relation,
+  };
+
+  const member = menuMember(applyName);
+  const stateKey = menuStateKey(chromeSegName, applyName, undefined);
+  const pageKey = menuPageKey(stateKey);
+  const identity = menuActionName(stateKey, member);
+  artifacts.variables[stateKey] = disclosureStateVar(
+    stateKey,
+    DISCLOSURE_CLOSED,
+  );
+  artifacts.variables[pageKey] = { kind: "state", key: pageKey, default: "0" };
+  artifacts.actions[identity] = disclosureCycleAction(stateKey, member);
+  artifacts.actions[pageKey] = { set: pageKey, int: true };
+
+  artifacts.segments[chromeSegName] = {
+    template: `+{{ menu "${applyName}" }}`,
+    when: EDIT_MODE_GATE,
+  };
+  return { kind: "segment", name: chromeSegName };
+}
+
+// [LAW:dataflow-not-control-flow] One recursive splice: a container's
+// non-exempt segment children get a `+` before and a `-` after (so N
+// consecutive segments read `+ [seg1 -] + [seg2 -] + [seg3 -] +` — N+1 insert
+// points, N remove points); a container child recurses; an exempt segment
+// (a group toggle, a menu host, edit mode's own chrome) passes through
+// untouched. `posCounter` is threaded by reference so position identifiers
+// stay unique across the WHOLE preset tree, not just one container.
+function spliceContainer(
+  node: ContainerNode,
+  presetIdent: string,
+  rootOpsKey: string,
+  domainName: OptionDomain,
+  artifacts: ChromeArtifacts,
+  posCounter: { n: number },
+): ContainerNode {
+  const children: LayoutNode[] = [];
+  for (const child of node.children) {
+    if (child.kind === "container") {
+      children.push(
+        spliceContainer(
+          child,
+          presetIdent,
+          rootOpsKey,
+          domainName,
+          artifacts,
+          posCounter,
+        ),
+      );
+      continue;
+    }
+    if (isChromeExempt(child.name)) {
+      children.push(child);
+      continue;
+    }
+    children.push(
+      insertChrome(
+        presetIdent,
+        rootOpsKey,
+        String(posCounter.n++),
+        domainName,
+        child.name,
+        "before",
+        artifacts,
+      ),
+    );
+    children.push(child);
+    children.push(removeChrome(presetIdent, rootOpsKey, child.name, artifacts));
+  }
+  const last = node.children[node.children.length - 1];
+  if (
+    last !== undefined &&
+    last.kind === "segment" &&
+    !isChromeExempt(last.name)
+  ) {
+    children.push(
+      insertChrome(
+        presetIdent,
+        rootOpsKey,
+        String(posCounter.n++),
+        domainName,
+        last.name,
+        "after",
+        artifacts,
+      ),
+    );
+  }
+  return { ...node, children };
+}
+
+// One preset's chrome-spliced root. A bare-segment root (the A-grammar
+// collapses a single top-level segment ref to `{ kind: "segment", name }`
+// with no enclosing container) is wrapped in a synthetic horizontal
+// container for splicing purposes — the wrap becomes the real returned root,
+// which is exactly right: a lone segment needs a `+` on each side too.
+function spliceEditChromeForPreset(
+  config: DslConfig,
+  presetName: string,
+  artifacts: ChromeArtifacts,
+): LayoutNode {
+  const { node } = presetRoot(config, presetName);
+  const rootOpsKey = `presets.${presetName}.rootOps`;
+  const domainName = addableDomainName(presetName);
+  const presetIdent = ident(presetName);
+  const posCounter = { n: 0 };
+  const container: ContainerNode =
+    node.kind === "container"
+      ? node
+      : { kind: "container", direction: "horizontal", children: [node] };
+  return spliceContainer(
+    container,
+    presetIdent,
+    rootOpsKey,
+    domainName,
+    artifacts,
+    posCounter,
+  );
+}
+
+// [LAW:single-enforcer] THE synthesis entry point, called once from
+// validateConfig after cross-ref/cycle checks pass. Every declared preset
+// (the floor "default" included — presetNames/presetByName/presetRoot
+// already treat it uniformly) gets an explicit `presets[name].root` carrying
+// its spliced tree; `config.root` itself is left untouched (presetRoot falls
+// back to it only when a preset declares no root of its own, and every name
+// now does). The synthesized variables/actions/segments merge additively —
+// nothing here can collide with user data, since every name it mints lives
+// under the `edit.`/`menus.` namespaces `synthesizeEditModeToggle` and
+// `synthesizeMenuDecls` already reserve unconditionally at parse time.
+export function synthesizeEditChrome(config: DslConfig): DslConfig {
+  // [LAW:carrying-cost] Demand-driven, mirroring synthesizeEditModeToggle's
+  // own gate: `edit.toggle` exists in the merged config iff SOME file's
+  // Phase A synthesis fired (iff some segment referenced it), which iff some
+  // author actually placed an edit-mode trigger. A config that never opted
+  // in gets back the identical config, untouched — no extra segments,
+  // actions, or variables, and critically no NEW `set`/`state` surface that
+  // would force session.id onto an otherwise fully static bar.
+  if (!(EDIT_TOGGLE_ACTION in config.actions)) return config;
+  const artifacts: ChromeArtifacts = {
+    variables: {},
+    actions: {},
+    segments: {},
+  };
+  const presets: Record<string, PresetDecl> = { ...config.presets };
+  for (const name of presetNames(config.presets)) {
+    const splicedRoot = spliceEditChromeForPreset(config, name, artifacts);
+    presets[name] = {
+      ...presetByName(config.presets, name),
+      root: splicedRoot,
+    };
+  }
+  return {
+    ...config,
+    variables: { ...config.variables, ...artifacts.variables },
+    actions: { ...config.actions, ...artifacts.actions },
+    segments: { ...config.segments, ...artifacts.segments },
+    presets,
+  };
+}

package/src/config/layout-ops.ts

@@ -79,6 +79,27 @@ export function decodeLayoutOp(token: string): LayoutOp | null {
   return null;
 }
 
+// [LAW:single-enforcer] THE one collector of "which segment names does this
+// tree contain" — brandon-layout-edit-2gc.3's edit-chrome synthesis
+// (src/config/edit-chrome.ts) uses it to compute both halves of the +/-
+// affordances: which segments are PRESENT (get a `-`) and, by set difference
+// against every declared segment, which are ADDABLE (populate the `+`
+// picker's domain). A name appearing more than once collapses to one entry —
+// callers that care about occurrence COUNT (none currently do) need a
+// different walk.
+export function collectSegmentNames(root: LayoutNode): ReadonlySet<string> {
+  const out = new Set<string>();
+  const walk = (node: LayoutNode): void => {
+    if (node.kind === "segment") {
+      out.add(node.name);
+      return;
+    }
+    for (const child of node.children) walk(child);
+  };
+  walk(root);
+  return out;
+}
+
 // [LAW:dataflow-not-control-flow] Ops are DATA folded over the tree in
 // order — replaying zero ops is the identity fold, replaying N is the same
 // reduce for every N. No branch on "are there ops to apply."