@promptctl/cc-candybar 1.8.1 → 1.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "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",
@@ -85,16 +85,16 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@promptctl/go-template-js": "^0.5.0",
+    "@promptctl/go-template-js": "^0.6.0",
     "@promptctl/rich-js": "^0.6.0",
     "json5": "^2.2.3",
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.8.1",
-    "@promptctl/cc-candybar-darwin-x64": "1.8.1",
-    "@promptctl/cc-candybar-linux-x64": "1.8.1",
-    "@promptctl/cc-candybar-linux-arm64": "1.8.1"
+    "@promptctl/cc-candybar-darwin-arm64": "1.8.3",
+    "@promptctl/cc-candybar-darwin-x64": "1.8.3",
+    "@promptctl/cc-candybar-linux-x64": "1.8.3",
+    "@promptctl/cc-candybar-linux-arm64": "1.8.3"
   },
   "pnpm": {
     "supportedArchitectures": {

package/src/config/default-dsl-config.ts

@@ -496,10 +496,12 @@ export const DEFAULT_DSL_CONFIG = {
     // and the render's read are one value. Empty default ⇒ the daemon's
     // "powerline" floor is in effect and styleControl shows "(default)".
     activeStyle: { kind: "state", key: "style", default: "" },
-    // The style menu's page cursor: −1 closed / 0..N open, mirroring how a theme
-    // picker's page key gates its reveal row. The stylePage action declares the
-    // int gate; this var reads it back for the reveal `when`.
-    stylePage: { kind: "state", key: "style-page", default: "-1" },
+    // The style picker's page index. Open/closed is the synthesized menus.* key
+    // the styleControl's {{ menu }} owns — NOT this var, which is purely the page
+    // the picker paginates by (default page 0; the disclosure resets it to 0 on
+    // every toggle, so a reopened menu never lands on a stale page). The stylePage
+    // action below declares the int gate this var reads back.
+    stylePage: { kind: "state", key: "style-page", default: "0" },
   },
 
   // ─── Segments ──────────────────────────────────────────────────────────────
@@ -736,26 +738,22 @@ export const DEFAULT_DSL_CONFIG = {
         " .metrics.sessionDuration .metrics.messageCount" +
         " .metrics.linesAdded .metrics.linesRemoved }}",
     },
-    // Style control — the powerline-shape switcher's trigger. [LAW:locality-or-
-    // seam] The ✦ glyph + current-style label is the REPRESENTATION; the
-    // `openStyleMenu` action is the BEHAVIOR; the name is the seam. Shows the
-    // active shape (or "(default)" when unset) and a ▸ that opens the picker
-    // row. [LAW:dataflow-not-control-flow] No display state from the provider —
-    // the label is the one "style" value the click writes and the render reads.
+    // Style control — the powerline-shape switcher. A self-contained {{ menu }}
+    // disclosure: the ✦ glyph + current-style label is the REPRESENTATION, and the
+    // ▸/▾ disclosure (whose identity is DERIVED from this segment + the applyStyle
+    // action, see menu-keys.ts) toggles the picker body, which DROPS full-width
+    // onto the line below this row when open. [LAW:one-type-per-behavior] "a menu
+    // that opens and closes" is one behavior the substrate already expresses — no
+    // bespoke open-action + page-cursor-as-open-state + when-gated reveal row.
+    // paged omitted ⇒ false ⇒ one full-width page (the 3 powerline shapes are a
+    // small domain; FlexStrip soft-wraps if needed). closeOnPick omitted ⇒ false
+    // ⇒ stay-open, so shapes can be tried in a row; the ▾ collapses.
+    // [LAW:dataflow-not-control-flow] No display state from the provider — the
+    // label is the one "style" value the click writes and the render reads.
     styleControl: {
       template:
         "✦ {{ if .activeStyle }}{{ .activeStyle }}{{ else }}(default){{ end }} " +
-        '{{ action "openStyleMenu" "▸" }}',
-      bg: "surface",
-      fg: "foreground",
-    },
-    // The expanded style picker: one full-width page (paged=false) over the
-    // `applyStyle` option domain — the 3 powerline shapes. closeOnPick defaults
-    // false (omitted here), so a pick reshapes the bar live and LEAVES THE ROW
-    // OPEN — shapes can be tried in a row; the ✕ affordance closes. The active
-    // shape is marked by the picker helper.
-    stylePicker: {
-      template: '{{ picker "applyStyle" "stylePage" }}',
+        '{{ menu "applyStyle" "stylePage" }}',
       bg: "surface",
       fg: "foreground",
     },
@@ -764,10 +762,11 @@ export const DEFAULT_DSL_CONFIG = {
   // Default layout — the canonical LayoutNode tree (`satisfies DslConfig`
   // requires the lowered form here; the terse Option-A `{ h/v/seg }` grammar is
   // the loader's authoring surface for user JSON, not this typed literal).
-  // [LAW:dataflow-not-control-flow] Two rows: an always-on control row, and a
-  // picker reveal row that EXISTS only while the style menu cursor is ≥ 0 — the
-  // row's presence is a value test on stylePage, not a branch in render code.
-  // The picker itself draws the ✕/←/→ affordances from the page + term width.
+  // [LAW:dataflow-not-control-flow] One always-on control row. The styleControl's
+  // {{ menu }} disclosure drops its picker body onto the line directly below this
+  // row when open — openness is the value of the derived menus.* key, NOT a when-
+  // gated reveal row. The picker draws the ✕/←/→ affordances from the page + term
+  // width; the vertical container stacks the dropped body under row 0.
   root: {
     kind: "container",
     direction: "vertical",
@@ -786,11 +785,6 @@ export const DEFAULT_DSL_CONFIG = {
           { kind: "segment", name: "styleControl" },
         ],
       },
-      {
-        kind: "segment",
-        name: "stylePicker",
-        when: "{{ ge (int .stylePage) 0 }}",
-      },
     ],
   },
 
@@ -814,14 +808,16 @@ export const DEFAULT_DSL_CONFIG = {
     openProject: { open: "{{ .project_dir }}" },
     openTranscript: { open: "{{ .transcript_path }}" },
 
-    // [LAW:locality-or-seam] The style picker's behaviors, decoupled by NAME
-    // from styleControl/stylePicker above. Three declarations, all gated by
-    // derivation (deriveActionValidators): openStyleMenu/stylePage write the
-    // page cursor (a literal page-open subsumed by the int gate); applyStyle
-    // writes the chosen shape, gated to the STRIP_STYLES allow-list because its
-    // value source is `from: "styles"`. The rendered click and the wire gate
-    // share that one source — a template cannot smuggle an un-gated style write.
-    openStyleMenu: { set: "style-page", to: "0" },
+    // [LAW:locality-or-seam] The style menu's behaviors, decoupled by NAME from the
+    // styleControl {{ menu }} above. The disclosure's open-state toggle + its
+    // backing state var are SYNTHESIZED by the menu pass (under the reserved
+    // menus.* namespace) — no hand-authored open/close action. These two are the
+    // picker body's effects, both gated by derivation (deriveActionValidators):
+    // applyStyle writes the chosen shape, gated to the STRIP_STYLES allow-list
+    // because its value source is `from: "styles"`; stylePage is the page cursor's
+    // unbounded int gate (←/→ navigation + the disclosure's page-0 reset). The
+    // rendered click and the wire gate share that one source — a template cannot
+    // smuggle an un-gated style write.
     applyStyle: { set: "style", from: "styles" },
     stylePage: { set: "style-page", int: true },
   },

package/src/config/dsl-loader.ts

@@ -71,7 +71,7 @@ export { mergeWithDefault } from "./loader/merge.js";
 export {
   extractTemplateRefs,
   extractActionRefs,
-  extractPickerRefs,
+  extractPickerMenuRefs,
 } from "./loader/refs.js";
 
 // ─── Three-stage pipeline ────────────────────────────────────────────────────

package/src/config/loader/cross-ref.ts

@@ -17,7 +17,7 @@ import { findKeyLine } from "./diagnostics.js";
 import { isPlainObject, type ValidateCtx } from "./validate-core.js";
 import {
   extractActionRefs,
-  extractPickerRefs,
+  extractPickerMenuRefs,
   extractTemplateRefs,
   refResolves,
 } from "./refs.js";
@@ -145,14 +145,16 @@ export function validateCrossReferences(
           });
         }
       }
-      // [LAW:locality-or-seam] A `{{ picker "apply" "page" … }}` references two
-      // named actions — both resolve against the action table at load, same
-      // existence-check shape as a bare action ref.
-      for (const pref of extractPickerRefs(tpl)) {
+      // [LAW:locality-or-seam] A `{{ picker "apply" "page" … }}` OR `{{ menu
+      // "apply" "page" … }}` references two named actions — both resolve against
+      // the action table at load, same existence-check shape as a bare action ref.
+      // A menu binds the same pair as a picker, so it routes through the SAME
+      // check rather than failing only when the disclosure is opened.
+      for (const pref of extractPickerMenuRefs(tpl)) {
         if (!Object.prototype.hasOwnProperty.call(cfg.actions, pref)) {
           ctx.issues.push({
             path: `segments.${segName}.${field}`,
-            message: `${field} references unknown action "${pref}" (in a picker)`,
+            message: `${field} references unknown action "${pref}" (in a picker or menu)`,
             line: findKeyLine(ctx.source, ["segments", segName, field]),
           });
         }

package/src/config/loader/menu-synth.ts

@@ -2,8 +2,8 @@
 // `{{ menu }}` render helper. A menu is the group-accordion mechanism with its
 // trigger living inside an arbitrary user segment rather than a synthesized
 // toggle segment — so this emits exactly what group sugar does MINUS the segment
-// (the helper IS the trigger): one `state` var per row key (default "closed")
-// and one `cycle` action per (row, menu-bearing segment) under the reserved
+// (the helper IS the trigger): one `state` var per menu state key (default
+// "closed") and one `cycle` action per (state key, member) under the reserved
 // `menus.` namespace. Both land in the raw sections so they merge over the
 // default and, crucially, so `deriveActionValidators(config.actions)` derives the
 // click gate from them through the ONE existing path — a menu toggle is gated
@@ -12,12 +12,15 @@
 // Runs in `parseDslConfig` after group synthesis and after every section parsed,
 // so the reserved-namespace collision check sees the fully-parsed user sections.
 //
-// [LAW:types-are-the-program] WHICH segments host a menu is read from the parsed
-// AST (`referencedFunctions`), not a source-text scan — robust against whitespace,
-// pipelines, and `.menu`/"menu" lookalikes. Detection bare-parses the segment
-// template; a parse failure here is treated as "no menu" because the authoritative
-// parse error is surfaced loudly by `registerDslConfig` when it compiles the same
-// template (so this pass never swallows a real error, it just declines to guess).
+// [LAW:types-are-the-program] WHICH segments host a menu, and with WHAT apply
+// action + optional shared key, is read from the parsed AST (`referencedCalls`),
+// not a source-text scan — robust against whitespace, pipelines, and
+// `.menu`/"menu" lookalikes, and it yields each call's literal string arguments
+// so a menu's identity (member = apply name; key = optional shared key) is the
+// SAME fact the render helper reads from those same argument positions. A parse
+// failure here is treated as "no menu" because the authoritative parse error is
+// surfaced loudly by `registerDslConfig` when it compiles the same template (so
+// this pass never swallows a real error, it just declines to guess).
 
 import { createEngine } from "@promptctl/go-template-js";
 import type { ActionDecl } from "../action.js";
@@ -25,11 +28,15 @@ import type { Mutable, ValidateCtx } from "./validate-core.js";
 import {
   MENU_CLOSED,
   MENU_NS,
-  forEachSegmentPlacement,
   menuActionName,
+  menuMember,
   menuStateKey,
 } from "../menu-keys.js";
-import type { RawDslConfig, VariableDecl } from "../dsl-types.js";
+import {
+  walkNodes,
+  type RawDslConfig,
+  type VariableDecl,
+} from "../dsl-types.js";
 import { findKeyLine } from "./diagnostics.js";
 
 // [LAW:single-enforcer] The helper-name a `{{ menu … }}` call uses — the same
@@ -37,17 +44,52 @@ import { findKeyLine } from "./diagnostics.js";
 // references this function.
 const MENU_FUNC = "menu";
 
+// [LAW:types-are-the-program] The `{{ menu }}` argument positions, mirroring the
+// render helper's signature `menu apply page closeOnPick paged key`. Only the
+// apply name (identity member) and the optional shared key (accordion grouping)
+// affect synthesis; page/closeOnPick/paged are render-only and ignored here.
+const ARG_APPLY = 0;
+const ARG_KEY = 4;
+
+// [LAW:types-are-the-program] One menu call's identity-bearing arguments. Each
+// arg has three states the synthesis must tell apart: a literal string (usable),
+// `null` (a slot present but non-literal — its value is eval-time, so it cannot
+// be gated at load → author error), and `undefined` (the slot was omitted). The
+// apply slot is required; the key slot is optional (undefined ⇒ independent menu).
+interface MenuCall {
+  readonly apply: string | null;
+  readonly key: string | null | undefined;
+}
+
 // [LAW:no-defensive-null-guards] A bare engine purely for AST introspection: it
 // never evaluates, so `fromString` is identity and no funcs are registered (parse
 // does not resolve function existence — that is an eval-time concern).
-function segmentReferencesMenu(template: string): boolean {
+function parseCalls(template: string): readonly MenuCall[] | "parse-failed" {
   const engine = createEngine<string>({ fromString: (s) => s });
   try {
-    return engine.parse(template).referencedFunctions().has(MENU_FUNC);
+    return engine
+      .parse(template)
+      .referencedCalls()
+      .filter((c) => c.name === MENU_FUNC)
+      .map((c) => ({
+        apply: c.args[ARG_APPLY] ?? null,
+        // `referencedCalls` reports an omitted positional slot as absent and a
+        // present non-literal as null; preserve that distinction.
+        key: c.args.length > ARG_KEY ? c.args[ARG_KEY] : undefined,
+      }));
   } catch {
     // A malformed template can host no usable menu; registerDslConfig re-parses
     // and reports the real error. [LAW:no-silent-failure] — not swallowed, just
     // not the place that reports it.
+    return "parse-failed";
+  }
+}
+
+function segmentReferencesMenu(template: string): boolean {
+  const engine = createEngine<string>({ fromString: (s) => s });
+  try {
+    return engine.parse(template).referencedFunctions().has(MENU_FUNC);
+  } catch {
     return false;
   }
 }
@@ -77,73 +119,204 @@ export function synthesizeMenuDecls(
     }
   }
 
-  // [LAW:no-silent-failure] A menu derives its accordion identity from its host
-  // SEGMENT's tree position; a `{{ define }}` helper is shared and placement-
-  // agnostic, so a `{{ menu }}` reached through one has no row to key on and would
-  // never get its backing state var/cycle action synthesized — failing at render.
-  // Reject it loudly at load, pointing the author to inline the menu in a segment.
-  // [LAW:no-mode-explosion] We reject rather than build helper-call-graph
-  // resolution speculatively; revisit only if a real shared-menu need appears.
+  // [LAW:no-silent-failure] A menu derives its identity from the SEGMENT it sits
+  // in (the published segment name) plus its own apply arg; a `{{ define }}`
+  // helper is shared across segments, so the synthesis pass — which scans each
+  // segment's own template — cannot see a menu reached only through `{{ template
+  // }}` and would never synthesize its backing state var/cycle action, failing at
+  // render. Reject it loudly at load, pointing the author to inline the menu.
+  // [LAW:no-mode-explosion] We reject rather than resolve the helper call graph
+  // speculatively; revisit only if a real shared-menu need appears.
   for (const [name, body] of Object.entries(out.helpers ?? {})) {
     if (segmentReferencesMenu(body)) {
       ctx.issues.push({
         path: `helpers.${name}`,
-        message: `helper "${name}" uses {{ menu }}, but a menu must live directly in a segment template — its accordion identity is derived from the segment's position in the layout, which a shared helper does not have. Inline the {{ menu }} call into each segment that needs it.`,
+        message: `helper "${name}" uses {{ menu }}, but a menu must live directly in a segment template — its identity is derived from the segment it sits in, which a shared helper does not have. Inline the {{ menu }} call into each segment that needs it.`,
         line: findKeyLine(ctx.source, ["helpers", name]),
       });
     }
   }
 
-  if (out.root === undefined) return;
   const segments = out.segments ?? {};
 
-  // [LAW:dataflow-not-control-flow] Memoize detection by segment name — a segment
-  // placed in N rows is parsed once, then each placement reads the cached verdict.
-  const hostsMenu = new Map<string, boolean>();
-  const referencesMenu = (segName: string): boolean => {
-    const cached = hostsMenu.get(segName);
-    if (cached !== undefined) return cached;
-    const seg = segments[segName];
-    const result =
-      seg !== undefined ? segmentReferencesMenu(seg.template) : false;
-    hostsMenu.set(segName, result);
-    return result;
-  };
-
-  // One state key per row (default "closed"); one cycle action per (row,segment).
-  const stateKeys = new Map<string, string>(); // stateKey → rowKey (for vars)
-  const actions: Record<string, ActionDecl> = {};
-  forEachSegmentPlacement(out.root, (segName, rowKey) => {
-    if (!referencesMenu(segName)) return;
-    // [LAW:types-are-the-program] A menu's member name IS its host segment name;
-    // a segment named exactly the closed-state sentinel would make the cycle
-    // [closed, "closed"] — two identical members, so the toggle could never leave
-    // the closed state. Reject that one collision at load (the only segment name
-    // that breaks a menu), rather than silently synthesizing an unopenable menu.
-    if (segName === MENU_CLOSED) {
+  // [LAW:locality-or-seam] A menu publishes its placement ONLY around the segment
+  // `template` eval; bg/fg evaluate after that window and a node/segment `when`
+  // before it, so a {{ menu }} in any of them throws at render. The template is
+  // the menu's one valid seam — reject it anywhere else at load, rather than
+  // admit a config that parses but crashes on render.
+  for (const [segName, seg] of Object.entries(segments)) {
+    for (const field of ["bg", "fg", "when"] as const) {
+      const tpl = seg[field];
+      if (typeof tpl === "string" && segmentReferencesMenu(tpl)) {
+        menuIssue(
+          ctx,
+          `segments.${segName}.${field}`,
+          `segment "${segName}" uses {{ menu }} in its "${field}" — a menu is only valid in a segment's "template" (its placement is published only there; "${field}" needs a ${field === "when" ? "predicate" : "color"}). Move the {{ menu }} into the template.`,
+        );
+      }
+    }
+  }
+
+  // One walk over the layout: reject {{ menu }} in node `when` predicates (same
+  // template-only rule), and count each segment's placements for the reuse check.
+  const placementCounts = new Map<string, number>();
+  if (out.root !== undefined) {
+    for (const node of walkNodes(out.root)) {
+      if (typeof node.when === "string" && segmentReferencesMenu(node.when)) {
+        menuIssue(
+          ctx,
+          "root",
+          `a layout node's "when" predicate uses {{ menu }} — a menu is only valid in a segment's "template", not a node predicate. Move it into a segment.`,
+        );
+      }
+      if (node.kind === "segment") {
+        placementCounts.set(
+          node.name,
+          (placementCounts.get(node.name) ?? 0) + 1,
+        );
+      }
+    }
+  }
+
+  // [LAW:types-are-the-program] A menu-bearing segment placed in more than one
+  // layout slot is ambiguous: its disclosure open-state is keyed by segment name
+  // (one state for the segment), so two placements would share it and a click on
+  // one would toggle both. Reject the repeated placement — the ambiguity is
+  // unrepresentable, and identity stays name-derived (no placement path threaded
+  // into the key). Two independent disclosures = two named segments.
+  for (const [segName, seg] of Object.entries(segments)) {
+    if (!segmentReferencesMenu(seg.template)) continue;
+    if ((placementCounts.get(segName) ?? 0) > 1) {
       menuIssue(
         ctx,
         `segments.${segName}`,
-        `segment "${segName}" hosts a {{ menu }}, but a menu cannot live in a segment named "${MENU_CLOSED}" — that name collides with the menu's closed-state sentinel, leaving the menu unopenable. Rename the segment.`,
+        `segment "${segName}" hosts a {{ menu }} and is placed in the layout more than once — a menu's open-state is keyed by segment name, so the copies would share one state (clicking one would toggle both). Give each placement its own named segment.`,
       );
-      return;
     }
-    const stateKey = menuStateKey(rowKey);
-    stateKeys.set(stateKey, rowKey);
-    // [LAW:one-source-of-truth] Members ordered closed-first: an unset/foreign
-    // value counts as the first member (the cycle's "unknown ⇒ first" rule), so a
-    // never-clicked menu renders ▸ and a click opens it, auto-closing a row-mate
-    // because the shared key can hold only one member name.
-    actions[menuActionName(rowKey, segName)] = {
-      set: stateKey,
-      cycle: [MENU_CLOSED, segName],
-    };
-  });
+  }
+
+  // One state var per state key (default "closed"); one cycle action per
+  // (stateKey, member). [LAW:dataflow-not-control-flow] Independent menus each
+  // contribute their own key; shared-key menus contribute distinct members to one
+  // key, and the same-key validator merge unions them into one accordion gate.
+  const stateKeys = new Set<string>();
+  const actions: Record<string, ActionDecl> = {};
+  // Guard against two menus claiming one identity (same key + same member): for
+  // independent menus that means the literal same `{{ menu }}` twice in a
+  // segment; for shared-key menus it means two menus with the same apply name
+  // sharing a key — neither can be addressed distinctly, so reject.
+  const claimed = new Set<string>();
+  // [LAW:types-are-the-program] The state key is `ident()`-normalized so it carries
+  // no separators; that normalization is lossy (`a-b` and `a_b` collapse), so two
+  // DISTINCT declarations could map to one key and silently share open-state (an
+  // unintended accordion). Track the raw "owner" each key legitimately belongs to
+  // — a shared key is owned by its raw key string (every sibling agrees); an
+  // independent menu by its raw (segment, apply). A second owner on the same key
+  // is a normalization collision, rejected at load so it is unrepresentable
+  // [LAW:no-silent-failure] rather than corrupting grouping.
+  const ownerByStateKey = new Map<string, string>();
+
+  for (const [segName, seg] of Object.entries(segments)) {
+    if (!segmentReferencesMenu(seg.template)) continue;
+    const calls = parseCalls(seg.template);
+    if (calls === "parse-failed") continue;
+    for (const call of calls) {
+      if (call.apply === null) {
+        menuIssue(
+          ctx,
+          `segments.${segName}`,
+          `segment "${segName}" has a {{ menu }} whose apply action is not a string literal — a menu's identity is its apply-action name, which must be a literal so it can be gated at load (e.g. {{ menu "applyTheme" "themePage" }}).`,
+        );
+        continue;
+      }
+      if (call.key === null) {
+        menuIssue(
+          ctx,
+          `segments.${segName}`,
+          `segment "${segName}" has a {{ menu }} whose accordion key is not a string literal — a shared key must be a literal so the mutually-exclusive group can be gated at load (e.g. {{ menu "applyTheme" "themePage" false false "pickers" }}).`,
+        );
+        continue;
+      }
+      // [LAW:types-are-the-program] An empty shared key collapses the state key to
+      // the bare reserved `menus.` namespace (and a `menus..member` action name).
+      // Reject it — a shared key, when present, must name a group.
+      if (call.key === "") {
+        menuIssue(
+          ctx,
+          `segments.${segName}`,
+          `segment "${segName}" has a {{ menu }} with an empty accordion key — a shared key must be a non-empty name (or omit it for an independent menu).`,
+        );
+        continue;
+      }
+      // [LAW:types-are-the-program] An empty apply name → empty member, and the
+      // store returns "" for an absent state key, so `open = read === member`
+      // would be true before any click — the menu would render open spuriously.
+      // Reject it (the member must never alias the absent-state sentinel).
+      if (call.apply === "") {
+        menuIssue(
+          ctx,
+          `segments.${segName}`,
+          `segment "${segName}" has a {{ menu }} with an empty apply-action name — an empty member aliases the absent-state sentinel ("") so the menu would render open before any click. Name the apply action.`,
+        );
+        continue;
+      }
+      const member = menuMember(call.apply);
+      // [LAW:types-are-the-program] A member equal to the closed sentinel makes
+      // the cycle [closed, "closed"] — two identical members, leaving the menu
+      // unopenable. The only apply name that breaks a menu; reject it at load.
+      if (member === MENU_CLOSED) {
+        menuIssue(
+          ctx,
+          `segments.${segName}`,
+          `segment "${segName}" has a {{ menu }} whose apply action is named "${MENU_CLOSED}", which collides with the menu's closed-state sentinel and leaves it unopenable. Rename the action.`,
+        );
+        continue;
+      }
+      const stateKey = menuStateKey(segName, call.apply, call.key);
+      // The raw declaration this key legitimately belongs to. Shared-key siblings
+      // all share one owner (their raw key); an independent menu owns its key alone
+      // (its raw segment+apply, NUL-joined so the two parts can't run together).
+      const owner =
+        call.key !== undefined
+          ? `key${call.key}`
+          : `ind${segName}${call.apply}`;
+      const priorOwner = ownerByStateKey.get(stateKey);
+      if (priorOwner !== undefined && priorOwner !== owner) {
+        menuIssue(
+          ctx,
+          `segments.${segName}`,
+          `two {{ menu }} disclosures normalize to the same state key ("${stateKey}") but were declared differently — distinct names that differ only by non-alphanumeric characters (e.g. "a-b" vs "a_b") collapse to one key and would silently share open-state. Rename so they don't collide.`,
+        );
+        continue;
+      }
+      ownerByStateKey.set(stateKey, owner);
+      const identity = menuActionName(stateKey, member);
+      if (claimed.has(identity)) {
+        menuIssue(
+          ctx,
+          `segments.${segName}`,
+          `two {{ menu }} disclosures resolve to the same identity ("${identity}") — ${
+            call.key !== undefined
+              ? `menus sharing key "${call.key}" must have distinct apply actions`
+              : `a segment cannot contain two menus over the same apply action "${call.apply}"`
+          }.`,
+        );
+        continue;
+      }
+      claimed.add(identity);
+      stateKeys.add(stateKey);
+      // [LAW:one-source-of-truth] Members ordered closed-first: an unset/foreign
+      // value counts as the first member (the cycle's "unknown ⇒ first" rule), so
+      // a never-clicked menu renders ▸ and a click opens it; a shared key holding
+      // one member auto-closes its siblings.
+      actions[identity] = { set: stateKey, cycle: [MENU_CLOSED, member] };
+    }
+  }
 
   if (stateKeys.size === 0) return;
 
   const variables: Record<string, VariableDecl> = {};
-  for (const stateKey of stateKeys.keys()) {
+  for (const stateKey of stateKeys) {
     variables[stateKey] = {
       kind: "state",
       key: stateKey,

package/src/config/loader/refs.ts

@@ -54,25 +54,28 @@ export function extractActionRefs(template: string): Set<string> {
   return refs;
 }
 
-// [LAW:dataflow-not-control-flow] Extract the action names a `picker` call
-// references — its FIRST TWO string-literal args are the apply action and the
-// page action (`{{ picker "applyTheme" "themePage" true true }}`). Same code/
-// string-span walk as extractActionRefs; the picker keyword arms the next literal
-// as the apply name and the one after it as the page name (the trailing bool args
-// are not string literals, so they are never captured).
-const PICKER_ARG_RE = /\bpicker\s+$/;
-export function extractPickerRefs(template: string): Set<string> {
+// [LAW:dataflow-not-control-flow] Extract the action names a `picker` OR `menu`
+// call references — both bind the SAME (apply, page) action pair as their FIRST
+// TWO string-literal args (`{{ picker "applyTheme" "themePage" true true }}`,
+// `{{ menu "applyTheme" "themePage" false true "key" }}`). A menu's body IS a
+// picker, so the existence check on those two refs is identical; one extractor
+// arms on either keyword [LAW:single-enforcer]. Same code/string-span walk as
+// extractActionRefs; the keyword arms the next literal as the apply name and the
+// one after as the page name (trailing bools/the menu key are captured only if
+// they fall in the first two literal slots, which they never do).
+const PICKER_OR_MENU_ARG_RE = /\b(?:picker|menu)\s+$/;
+export function extractPickerMenuRefs(template: string): Set<string> {
   const refs = new Set<string>();
   TEMPLATE_BLOCK_RE.lastIndex = 0;
   let m: RegExpExecArray | null;
   while ((m = TEMPLATE_BLOCK_RE.exec(template)) !== null) {
     const block = m[1]!;
     let cursor = 0;
-    let pending = 0; // remaining name args to capture for the current picker call
+    let pending = 0; // remaining name args to capture for the current call
     let s: RegExpExecArray | null;
     STRING_LITERAL_RE.lastIndex = 0;
     while ((s = STRING_LITERAL_RE.exec(block)) !== null) {
-      if (PICKER_ARG_RE.test(block.slice(cursor, s.index))) pending = 2;
+      if (PICKER_OR_MENU_ARG_RE.test(block.slice(cursor, s.index))) pending = 2;
       if (pending > 0) {
         refs.add(s[0].slice(1, -1));
         pending--;