@promptctl/cc-candybar 1.38.0 → 1.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.38.0",
+  "version": "1.39.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.38.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.38.0",
-    "@promptctl/cc-candybar-linux-x64": "1.38.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.38.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.39.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.39.0",
+    "@promptctl/cc-candybar-linux-x64": "1.39.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.39.0"
   }
 }

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

@@ -28,6 +28,14 @@
 
 import type { DslConfig, LayoutNode, SegmentDecl } from "./dsl-types.js";
 import { parseDslConfig } from "./dsl-loader.js";
+// [LAW:one-source-of-truth] The bundled drawer's menus author their own
+// disclosure glyphs now that `{{ menu }}` appends none. Interpolating the
+// shared constants keeps the stdlib bar reading like every other disclosure
+// without restating the vocabulary in three string literals.
+import {
+  DISCLOSURE_GLYPH_CLOSED,
+  DISCLOSURE_GLYPH_OPEN,
+} from "./disclosure.js";
 import { mergeWithDefault } from "./loader/merge.js";
 
 // ─── Shared template fragments ───────────────────────────────────────────────
@@ -1133,14 +1141,16 @@ export const RAW_DEFAULT_DSL_CONFIG = {
     charsetControl: {
       template:
         "{{ .charset.effective }} " +
-        '{{ menu "applyCharsetForever" }} {{ action "resetCharset" "↺" }}',
+        `{{ menu "applyCharsetForever" "${DISCLOSURE_GLYPH_CLOSED}" "${DISCLOSURE_GLYPH_OPEN}" }} ` +
+        '{{ action "resetCharset" "↺" }}',
       bg: "surface",
       fg: "foreground",
     },
     colorCompatControl: {
       template:
         "{{ .colorCompatibility.effective }} " +
-        '{{ menu "applyColorCompatForever" }} {{ action "resetColorCompat" "↺" }}',
+        `{{ menu "applyColorCompatForever" "${DISCLOSURE_GLYPH_CLOSED}" "${DISCLOSURE_GLYPH_OPEN}" }} ` +
+        '{{ action "resetColorCompat" "↺" }}',
       bg: "surface",
       fg: "foreground",
     },
@@ -1168,7 +1178,7 @@ export const RAW_DEFAULT_DSL_CONFIG = {
     directoryPaletteControl: {
       template:
         "🎨 directory " +
-        '{{ menu "applyDirectoryPaletteForever" }} ' +
+        `{{ menu "applyDirectoryPaletteForever" "${DISCLOSURE_GLYPH_CLOSED}" "${DISCLOSURE_GLYPH_OPEN}" }} ` +
         '{{ action "resetDirectoryPalette" "↺" }}',
       bg: "surface",
       fg: "foreground",

package/src/config/disclosure.ts

@@ -32,9 +32,63 @@ export const DISCLOSURE_CLOSED = "closed";
 // [LAW:representation] The disclosure glyph vocabulary — one pair for the whole
 // bar so every disclosure reads the same (trailing the label/content it gates,
 // per pdu.8): collapsed ▸, expanded ▾.
+//
+// [LAW:one-source-of-truth] These are the AUTHORED default, never an emission.
+// Every disclosure splices them into the template it synthesizes — group sugar
+// (loader/layout.ts), the settings menu (settings-menu.ts), the bundled drawer
+// — and a hand-authored config writes whichever glyph it likes, because the
+// trigger's text is a display bound at the call site like any other. Until
+// candybar-settings-ui-aok.4 `{{ menu }}` was the exception, appending ▸/▾ from
+// its own runtime where no author could see or decline it, which is how edit
+// mode's `+` came to render `+▸`.
 export const DISCLOSURE_GLYPH_CLOSED = "▸";
 export const DISCLOSURE_GLYPH_OPEN = "▾";
 
+// [LAW:one-source-of-truth] The glyph that CLOSES an open disclosure. The
+// picker body's ✕ has always been this; it lives here now because a trigger can
+// wear it too — edit mode's `+` does, since a `+` whose only open-state cue was
+// the ▸ this change removed would otherwise be indistinguishable from its
+// siblings (three insertion points render byte-identically when one is open,
+// and their dropped bodies are identical too, so row 0 is the only place the
+// answer can live). Two affordances, one meaning, one glyph.
+export const DISCLOSURE_GLYPH_CLOSE = "✕";
+
+// [LAW:single-enforcer] THE display rule every multi-state trigger obeys: bind
+// one display per member, or ONE static display that shows in every state. It
+// lives here, beside the toggle machinery, because both disclosure kinds need
+// it at different times — the loader can count a call's arguments statically
+// and wants an ISSUE to report, the renderer holds the evaluated displays and
+// wants to THROW — and a rule spelled once in each place is a rule that drifts.
+// A `{{ menu }}` folds through it with two members (its `[closed, member]`
+// cycle) and a cycle `{{ action }}` with as many as it declares; nothing about
+// the rule is disclosure-specific beyond who calls it.
+export function cycleDisplayIssue(
+  subject: string,
+  count: number,
+  members: number,
+): string | undefined {
+  if (count === 0) return `${subject} needs a display (the clickable text)`;
+  if (count !== 1 && count !== members) {
+    return `${subject} cycles ${members} members; bind one display per member (${members}) or one static display, got ${count}`;
+  }
+  return undefined;
+}
+
+// [LAW:dataflow-not-control-flow] Which display shows is a pure function of
+// (bound displays, current member index): a single static display shows in
+// every state, per-member displays index by the state. Throws the one rule's
+// text rather than silently dropping or repeating an argument.
+export function pickCycleDisplay(
+  subject: string,
+  displays: readonly string[],
+  members: number,
+  index: number,
+): string {
+  const issue = cycleDisplayIssue(subject, displays.length, members);
+  if (issue !== undefined) throw new Error(issue);
+  return displays.length === 1 ? displays[0]! : displays[index]!;
+}
+
 // [LAW:single-enforcer] THE backing `state` variable a disclosure key implies:
 // it holds the open member's name and defaults to `def` (the CLOSED sentinel for
 // an independent disclosure, or an initially-open member for a group's

package/src/config/edit-chrome.ts

@@ -50,6 +50,7 @@ import {
 } from "./menu-keys.js";
 import {
   DISCLOSURE_CLOSED,
+  DISCLOSURE_GLYPH_CLOSE,
   disclosureCycleAction,
   disclosureStateVar,
 } from "./disclosure.js";
@@ -211,8 +212,21 @@ function insertChrome(
   artifacts.actions[identity] = disclosureCycleAction(stateKey, member);
   artifacts.actions[pageKey] = { set: pageKey, int: true };
 
+  // The `+` IS the trigger — no appended arrow (candybar-settings-ui-aok.4).
+  // Beside a `-` that means something else entirely, a ▸ read as part of the
+  // affordance rather than as a disclosure hint, so the trigger names the ACTION
+  // its click performs instead: `+` inserts here, `✕` closes what `+` opened —
+  // the same glyph, and the same effect, as the body's own close cell.
+  //
+  // [LAW:no-silent-failure] It is deliberately NOT one static display. A preset
+  // has N insertion points whose rendered rows are byte-identical, and their
+  // dropped bodies are identical too — so with no per-state display, an open `+`
+  // is indistinguishable from the two beside it and the bar silently stops
+  // answering "which one did I open". The tint that marks other open menus
+  // (node-registry's `drops.length > 0`) cannot answer it either: this segment
+  // declares no bg, so there is nothing to tint.
   artifacts.segments[chromeSegName] = {
-    template: `+{{ menu "${applyName}" }}`,
+    template: `{{ menu "${applyName}" "+" "${DISCLOSURE_GLYPH_CLOSE}" }}`,
     when: EDIT_MODE_GATE,
   };
   return { kind: "segment", name: chromeSegName };

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

@@ -42,6 +42,7 @@ import {
   type MenuOptions,
 } from "../menu-keys.js";
 import {
+  cycleDisplayIssue,
   DISCLOSURE_CLOSED,
   disclosureCycleAction,
   disclosureStateVar,
@@ -60,13 +61,16 @@ import { reservedNamespaceCollisions } from "./reserved-namespace.js";
 const MENU_FUNC = "menu";
 
 // [LAW:types-are-the-program] The `{{ menu }}` surface, mirroring the render
-// helper's signature `menu "apply" [(dict …)]`: the apply name (identity member,
-// a required string literal) and ONE optional trailing options dict —
-// closeOnPick / paged / key, all statically readable via `staticDictEntries`.
-// The removed positional tail (page-action string, bare bools, 5th-arg key) is
-// detected and rejected with a migration-pointing error, never silently
+// helper's signature `menu "apply" display… [(dict …)]`: the apply name
+// (identity member, a required string literal), the trigger's authored display
+// text (one per state or one static — the arity is statically countable, so it
+// is checked here), and ONE optional trailing options dict — closeOnPick /
+// paged / key, all statically readable via `staticDictEntries`. Displays
+// themselves are NOT required to be literals; identity does not depend on
+// them, exactly as a cycle `{{ action }}`'s displays are free. Every removed
+// spelling is rejected with a migration-pointing error, never silently
 // reinterpreted [LAW:no-silent-failure].
-const MIGRATION = `the positional tail ("pageAction" closeOnPick paged "key") was removed: the page cursor is now synthesized from the menu's identity, and rare knobs are named options in ONE trailing dict — write {{ menu "applyTheme" }} or {{ menu "applyTheme" (dict "closeOnPick" true "paged" false "key" "pickers") }} (defaults: closeOnPick false, paged true, no key)`;
+const MIGRATION = `a menu binds its trigger text the way a cycle action binds a display — write {{ menu "applyTheme" "▸" "▾" }} (one per state) or {{ menu "insertHere" "+" }} (one static display for both), with the rare knobs in ONE trailing dict: {{ menu "applyTheme" "▸" "▾" (dict "closeOnPick" true "paged" false "key" "pickers") }} (defaults: closeOnPick false, paged true, no key). The renderer no longer appends ▸/▾ of its own (candybar-settings-ui-aok.4), and the older positional tail ("pageAction" closeOnPick paged "key") was removed — the page cursor is synthesized from the menu's identity`;
 
 // [LAW:dataflow-not-control-flow] One total analysis of a `{{ menu }}` call site:
 // every reachable argument shape lands in exactly one arm — a usable identity
@@ -80,33 +84,80 @@ type MenuAnalysis =
     }
   | { readonly kind: "issue"; readonly message: string };
 
+type ArgExpr = ReferencedCall["argExprs"][number];
+
+const isDictCall = (e: ArgExpr): boolean =>
+  e.kind === "call" && e.name === "dict";
+
+// [LAW:one-source-of-truth] The two sides split the tail on different evidence —
+// exprs here, evaluated values in `parseMenuArgs` — so the loader admits only
+// call sites where those two readings PROVABLY coincide. The renderer's split
+// asks one question of the last value, "is it an object", so a literal answers
+// it here: a parse-time constant evaluates to itself and can never become the
+// options dict. A literal `(dict …)` always does. Everything else in that slot
+// is classified by whatever it happens to evaluate to.
+const isNonObjectLiteral = (e: ArgExpr): boolean =>
+  e.kind === "literal" && typeof e.value !== "object";
+
+// The display-arity rule used as a predicate; the message is the caller's
+// business, so the subject never surfaces. [LAW:single-enforcer] — legality is
+// read off the disclosure primitive, never restated as a count comparison.
+const legalDisplayCount = (count: number): boolean =>
+  cycleDisplayIssue("", count, 2) === undefined;
+
 function analyzeMenuCall(call: ReferencedCall): MenuAnalysis {
   const issue = (message: string): MenuAnalysis => ({ kind: "issue", message });
-  const [applyArg, optsArg] = call.argExprs;
+  const [applyArg, ...tail] = call.argExprs;
   if (applyArg === undefined) {
     return issue(
-      `with no arguments — it takes an apply-action name (e.g. {{ menu "applyTheme" }})`,
+      `with no arguments — it takes an apply-action name and its trigger text (e.g. {{ menu "applyTheme" "▸" "▾" }})`,
     );
   }
-  if (call.argExprs.length > 2) {
-    return issue(`with more than two arguments — ${MIGRATION}`);
-  }
   if (applyArg.kind !== "literal" || typeof applyArg.value !== "string") {
     return issue(
-      `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" }})`,
+      `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" "▸" "▾" }})`,
+    );
+  }
+  // [LAW:types-are-the-program] The dict is the LAST argument when present;
+  // everything before it is a display. Splitting on that one position is the
+  // whole grammar, and it is the same split `parseMenuArgs` performs on the
+  // evaluated tail at render — one shape, read twice from the two things each
+  // side has (exprs here, values there).
+  const last = tail[tail.length - 1];
+  const optsArg = last !== undefined && isDictCall(last) ? last : undefined;
+  const displays = optsArg === undefined ? tail : tail.slice(0, -1);
+  if (displays.some(isDictCall)) {
+    return issue(
+      `whose options (dict …) is not its last argument — ${MIGRATION}`,
     );
   }
+  // [LAW:no-silent-failure] The last slot is the one both readings can claim.
+  // When the expr there is not provably one or the other AND dropping it still
+  // leaves a legal display count, the renderer's value-based split can land on
+  // a DIFFERENT reading than this one — same call, two shapes, no error either
+  // side: the options dict skips `staticDictEntries` (so a dynamic `key` derives
+  // a state key with no synthesized var behind it, and the menu never opens) or
+  // a display vanishes into the static form. Reject that call site; an explicit
+  // trailing `(dict …)` disambiguates it and keeps dynamic displays legal.
+  // Where the alternate reading is an ILLEGAL count the renderer throws instead
+  // of diverging, so it stays accepted — loudness, not refusal, is the bar.
   if (
-    optsArg !== undefined &&
-    (optsArg.kind !== "call" || optsArg.name !== "dict")
+    last !== undefined &&
+    optsArg === undefined &&
+    !isNonObjectLiteral(last) &&
+    legalDisplayCount(displays.length - 1)
   ) {
-    // A literal (the old page-action string / positional bool), a dynamic value,
-    // or a non-dict call: none is an options dict — one migration error covers
-    // the whole family [LAW:one-type-per-behavior].
     return issue(
-      `whose second argument is not an options (dict …) — ${MIGRATION}`,
+      `whose last argument is neither a literal nor a literal (dict …) — the renderer tells a display from the options dict by the value it evaluates to, so this call could be read as ${displays.length} displays or as ${displays.length - 1} plus options, and both are legal. Make the options explicit as a trailing (dict …) — {{ menu "${applyArg.value}" (printf "…") (printf "…") (dict) }} binds dynamic displays unambiguously — or bind the trigger text as literals`,
     );
   }
+  // [LAW:single-enforcer] The display-arity rule is the disclosure primitive's,
+  // the same one the renderer picks through — checked HERE too because the
+  // count is statically known, so an unauthored trigger is a load error naming
+  // the fix rather than a diagnostic glyph on the next render.
+  // "whose trigger …" completes the caller's `segment "X" has a {{ menu }} `.
+  const arity = cycleDisplayIssue("whose trigger", displays.length, 2);
+  if (arity !== undefined) return issue(`${arity} — ${MIGRATION}`);
   const entries = optsArg === undefined ? {} : staticDictEntries(optsArg);
   if (entries === null) {
     return issue(

package/src/config/settings-menu.ts

@@ -578,7 +578,8 @@ function declareSettingControls(artifacts: MenuArtifacts): void {
     artifacts.segments[seg] = {
       template:
         `${c.glyph} {{ .${c.effectiveVar} }} ` +
-        `{{ menu "${apply}" (dict "key" "${PICKER_KEY}" "closeOnPick" true) }} ` +
+        `{{ menu "${apply}" "${DISCLOSURE_GLYPH_CLOSED}" "${DISCLOSURE_GLYPH_OPEN}" ` +
+        `(dict "key" "${PICKER_KEY}" "closeOnPick" true) }} ` +
         `{{ action "${controlReset(c.name)}" "↺" }}`,
       bg: "surface",
       fg: "foreground",

package/src/render/action.ts

@@ -32,6 +32,7 @@ import {
   type ActionDecl,
 } from "../config/action.js";
 import { resolveOptionDomain } from "../config/option-domain.js";
+import { pickCycleDisplay } from "../config/disclosure.js";
 import { encodeLayoutOp, type LayoutOp } from "../config/layout-ops.js";
 import { parseSessionBoolean, type StripStyle } from "../themes/policy.js";
 import {
@@ -800,15 +801,16 @@ function selectDisplay(
     throw new Error(`action "${name}" needs a display (the clickable text)`);
   }
   if (action.kind === "set-cycle" || action.kind === "persist-cycle") {
-    if (displays.length !== 1 && displays.length !== action.members.length) {
-      throw new Error(
-        `action "${name}" cycles ${action.members.length} members; bind one display per member (${action.members.length}) or one static display, got ${displays.length}`,
-      );
-    }
-    const display =
-      displays.length === 1
-        ? displays[0]!
-        : displays[cycleIndex(action, store)]!;
+    // [LAW:single-enforcer] The arity rule and the pick are the disclosure
+    // primitive's, not this file's — `{{ menu }}` resolves its own trigger
+    // through the same function over its `[closed, member]` cycle, so the two
+    // disclosure kinds cannot disagree about what a display binding means.
+    const display = pickCycleDisplay(
+      `action "${name}"`,
+      displays,
+      action.members.length,
+      cycleIndex(action, store),
+    );
     return { display, boundValue: undefined };
   }
   if (displays.length > 2) {

package/src/render/menu.ts

@@ -1,11 +1,22 @@
 // [LAW:locality-or-seam] The runtime half of the `{{ menu }}` seam — sibling to
 // `{{ action }}`/`{{ picker }}`. A menu is a self-contained disclosure: an inline
-// glyph that toggles open/closed, and (when open) its body — a picker grid —
+// TRIGGER that toggles open/closed, and (when open) its body — a picker grid —
 // that DROPS onto the line(s) below the enclosing row. The body is the one picker
-// renderer (`renderPicker`); the glyph is a coupled set-state the menu composes
+// renderer (`renderPicker`); the trigger is a coupled set-state the menu composes
 // directly (like the picker's closeOnPick) — it toggles the open-state AND resets
 // the page cursor in one atomic batch, gated by the synthesized cycle action.
 //
+// [LAW:one-source-of-truth] The trigger's TEXT is authored, never emitted here.
+// This module used to append ▸/▾ from the glyph constants, while the codebase's
+// other disclosure — group sugar — spliced those same constants into the
+// template it synthesized, where an author could see and change them. Two
+// policies for one fact; the docs sided with the visible one ("the trigger is
+// any template content you like") while a menu appended a glyph nobody wrote,
+// which is why edit mode's `+` rendered `+▸`. A menu's disclosure IS a
+// two-member cycle, so its trigger now binds displays exactly as a cycle
+// `{{ action }}` does, through the same `pickCycleDisplay` (candybar-settings-
+// ui-aok.4).
+//
 // [LAW:effects-at-boundaries] The helper is a PURE function of its inputs (the
 // walk-published placement + the live store): it computes the inline glyph and,
 // when open, the body, and RETURNS them together — the glyph as the fragment, the
@@ -42,11 +53,7 @@ import {
   parseMenuOptions,
   type MenuOptions,
 } from "../config/menu-keys.js";
-import {
-  DISCLOSURE_CLOSED,
-  DISCLOSURE_GLYPH_CLOSED,
-  DISCLOSURE_GLYPH_OPEN,
-} from "../config/disclosure.js";
+import { DISCLOSURE_CLOSED, pickCycleDisplay } from "../config/disclosure.js";
 import { effectsUrl, VERB_SET_STATE } from "../click/wire.js";
 import { linkFragment, readVar, type ActionRuntime } from "./action.js";
 import { renderPicker } from "./picker.js";
@@ -94,9 +101,10 @@ export function collectMenuDrops(
 }
 
 // Realize a `{{ menu }}` against the live placement + state: return its inline
-// glyph, carrying the (open) body as out-of-band metadata for the boundary.
+// trigger, carrying the (open) body as out-of-band metadata for the boundary.
 function renderMenu(
   applyName: string,
+  displays: readonly string[],
   options: MenuOptions,
   runtime: MenuRuntime,
 ): RichText {
@@ -139,8 +147,14 @@ function renderMenu(
   // coupled batch passes the same wire gate every click does [LAW:single-enforcer].
   const sessionId = readVar(action.store, "session.id");
   const successor = open ? DISCLOSURE_CLOSED : member;
+  // [LAW:one-source-of-truth] The trigger's text is AUTHORED, resolved through
+  // the one display rule a cycle `{{ action }}` uses — a menu's disclosure is a
+  // two-member cycle, so binding `"▸" "▾"` gives the per-state form and binding
+  // `"+"` gives the static one. Nothing is appended here: a disclosure glyph an
+  // author never wrote is a glyph they cannot decline, which is exactly how
+  // edit mode's `+` came to read `+▸`.
   const glyph = linkFragment(
-    open ? DISCLOSURE_GLYPH_OPEN : DISCLOSURE_GLYPH_CLOSED,
+    pickCycleDisplay(`{{ menu "${applyName}" }}`, displays, 2, open ? 1 : 0),
     effectsUrl([
       {
         verb: VERB_SET_STATE,
@@ -178,25 +192,65 @@ function renderMenu(
   return glyph;
 }
 
+// [LAW:parse-dont-validate] THE crossing for a `{{ menu }}`'s argument tail.
+// The engine cannot type these slots for us — displays are strings and the
+// optional trailing knobs are a dict, so one declared slot type would refuse
+// one of them — so the tail arrives as opaque values and leaves here as a
+// record whose shape the renderer can no longer doubt: displays are strings,
+// options are parsed. Every rejected shape names the legal one.
+interface MenuArgs {
+  readonly displays: readonly string[];
+  readonly options: MenuOptions;
+}
+// [LAW:one-source-of-truth] This splits the tail on VALUES; the loader splits
+// the same tail on EXPRS (`menu-synth.ts`). They agree because the loader admits
+// only call sites where they provably must: a last argument that is neither a
+// string literal nor a literal `(dict …)` is a load error whenever both readings
+// would be legal, so what reaches here can only match the loader's reading or
+// throw below.
+const isDict = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+function parseMenuArgs(applyName: string, tail: readonly unknown[]): MenuArgs {
+  // The dict is the LAST argument when present; everything before it is a
+  // display. One position, so a reader never has to count.
+  const last = tail[tail.length - 1];
+  const optsArg = isDict(last) ? last : undefined;
+  const displayArgs = optsArg === undefined ? tail : tail.slice(0, -1);
+  const bad = displayArgs.findIndex((d) => typeof d !== "string");
+  if (bad !== -1) {
+    throw new Error(
+      `{{ menu "${applyName}" }} display #${bad + 1} is not text (${JSON.stringify(displayArgs[bad])}) — a menu binds its trigger text, then an optional trailing (dict …) of options`,
+    );
+  }
+  return {
+    displays: displayArgs as readonly string[],
+    // [LAW:one-source-of-truth] The same option reader the loader folds over
+    // the static dict — vocabulary, types, defaults live once.
+    options: parseMenuOptions(optsArg ?? {}),
+  };
+}
+
 // [LAW:dataflow-not-control-flow] One func; the apply-action NAME is the menu's
-// whole identity (the page cursor is derived from it, not passed), and the rare
-// knobs travel as ONE optional trailing `(dict …)` — closeOnPick (default
-// false: stay-open), paged (default true: a drop menu wants bounded height),
-// key (accordion grouping: omitted ⇒ independent, present ⇒ mutually exclusive
-// with siblings sharing it). Values, not modes. The loader gates the same dict
-// statically (staticDictEntries), so an old positional tail never reaches this
-// fn — it is a migration-pointing load error.
+// whole identity (the page cursor is derived from it, not passed), the TRIGGER
+// TEXT is bound like a cycle action's display (one per state, or one static),
+// and the rare knobs travel as ONE optional trailing `(dict …)` — closeOnPick
+// (default false: stay-open), paged (default true: a drop menu wants bounded
+// height), key (accordion grouping: omitted ⇒ independent, present ⇒ mutually
+// exclusive with siblings sharing it). Values, not modes. The loader gates the
+// same dict statically (staticDictEntries), so an old positional tail never
+// reaches this fn — it is a migration-pointing load error.
 //
 // [LAW:one-way-deps] Injected into the engine by registerDslConfig as data; the
 // generic engine never imports this module.
 export function menuFuncs(runtime: MenuRuntime): FuncMap {
   return {
     menu: {
-      fn: (applyName: string, opts?: Record<string, unknown>) =>
-        // [LAW:one-source-of-truth] The same option reader the loader folds
-        // over the static dict — vocabulary, types, defaults live once.
-        renderMenu(applyName, parseMenuOptions(opts ?? {}), runtime),
-      argTypes: ["string", "dict"],
+      fn: (applyName: string, ...tail: unknown[]) => {
+        const { displays, options } = parseMenuArgs(applyName, tail);
+        return renderMenu(applyName, displays, options, runtime);
+      },
+      argTypes: ["string", "value"],
       returnType: "T",
     },
   };

package/src/render/picker.ts

@@ -37,8 +37,8 @@ import {
   type ActionRuntime,
   type CompiledActionDecl,
 } from "./action.js";
+import { DISCLOSURE_GLYPH_CLOSE } from "../config/disclosure.js";
 
-const PICKER_CLOSE = "✕";
 const PICKER_PREV = "←";
 const PICKER_NEXT = "→";
 
@@ -242,7 +242,7 @@ export function renderPicker(
           2 * runtime.padding,
       )
     : Infinity;
-  const closeReserve = cellWidth(PICKER_CLOSE) + 1;
+  const closeReserve = cellWidth(DISCLOSURE_GLYPH_CLOSE) + 1;
   const arrowReserve = cellWidth(PICKER_PREV) + 1 + cellWidth(PICKER_NEXT) + 1;
   const firstPass = paginate(widths, available, closeReserve);
   const pages =
@@ -303,7 +303,9 @@ export function renderPicker(
       : effectsUrl([...effects, ...closeEffect]);
   };
 
-  const frags: RichText[] = [linkFragment(PICKER_CLOSE, closeUrl, false)];
+  const frags: RichText[] = [
+    linkFragment(DISCLOSURE_GLYPH_CLOSE, closeUrl, false),
+  ];
   if (pageIdx > 0) {
     frags.push(linkFragment(PICKER_PREV, pageUrl(pageIdx - 1), false));
   }