@promptctl/cc-candybar 1.37.0 → 1.39.0

package/src/config/loader/actions.ts

@@ -20,6 +20,7 @@
 
 import {
   ACTION_KEYS,
+  PERSIST_WHEN,
   type ActionDecl,
   type ActionKey,
   type OptionDomain,
@@ -103,6 +104,16 @@ function validateActionDecl(
     );
     return null;
   }
+  // [LAW:dataflow-not-control-flow] A dual-destination action
+  // (candybar-settings-ui-aok.3) carries BOTH `set` and `persist`, so it
+  // cannot be reached through the exactly-one-of eliminator below —
+  // `persistWhen` is its own discriminator, and its presence selects the arm
+  // exactly as the presence of `set` selects that one. The dual arm owns its
+  // own siblings (the two destination keys plus its value source), like every
+  // other arm here.
+  if (PERSIST_WHEN in raw) {
+    return valueSourceAction(ctx, path, raw, "dual", DUAL_ARMS);
+  }
   const present = (ACTION_KEYS as readonly string[]).filter((k) => k in raw);
   if (present.length !== 1) {
     issue(
@@ -124,24 +135,9 @@ function validateActionDecl(
 // sibling. The present key indexes this map — the eliminator never branches on
 // the key name.
 const ACTION_ARMS: Record<ActionKey, ArmParse<ActionDecl>> = {
-  set: (ctx, path, raw) =>
-    valueSourceAction(
-      ctx,
-      path,
-      raw,
-      "set",
-      SET_ARMS,
-      "the SessionState key to write",
-    ),
+  set: (ctx, path, raw) => valueSourceAction(ctx, path, raw, "set", SET_ARMS),
   persist: (ctx, path, raw) =>
-    valueSourceAction(
-      ctx,
-      path,
-      raw,
-      "persist",
-      PERSIST_ARMS,
-      "the config globals field to write",
-    ),
+    valueSourceAction(ctx, path, raw, "persist", PERSIST_ARMS),
   copy: templateArm("copy"),
   open: templateArm("open"),
   reset: resetArm,
@@ -169,6 +165,7 @@ function actionDeclJson(): JsonNode {
     anyOf: [
       ...SET_ARMS.map((arm) => arm.json),
       ...PERSIST_ARMS.map((arm) => arm.json),
+      ...DUAL_ARMS.map((arm) => arm.json),
       templateArmJson("copy"),
       templateArmJson("open"),
       templateArmJson("reset"),
@@ -305,37 +302,100 @@ function slashFreeString(
   return v;
 }
 
-// [LAW:dataflow-not-control-flow] The discriminator key ("set" or "persist")
-// is validated once for every value source (it is shared across all arms of
-// that discriminator), before the source is detected — so a bad key and an
-// ambiguous source both surface in one pass. It is therefore NOT a field of
+// [LAW:types-are-the-program] Which KEYS a value-source action carries beside
+// its value source, as data — one for a single-destination `set`/`persist`,
+// three for a `dual` (both destination keys plus the selector naming which is
+// written). Every consumer below (the key validation, the unknown-key
+// allow-list, the emitted JSON schema, the reconstructed member) reads this
+// one table, so adding the dual arm never meant a second dispatcher: the
+// discriminator stopped being ONE key and became a LIST of them, and the
+// existing machinery folds over the list [LAW:dataflow-not-control-flow].
+type Discriminator = "set" | "persist" | "dual";
+
+const DISCRIMINATOR_KEYS: Readonly<
+  Record<Discriminator, ReadonlyArray<readonly [string, string]>>
+> = {
+  set: [["set", "the SessionState key to write"]],
+  persist: [["persist", "the config globals field to write"]],
+  dual: [
+    ["set", "the SessionState key written while persistWhen is off"],
+    ["persist", "the config globals field written while persistWhen is on"],
+    [
+      PERSIST_WHEN,
+      "the SessionState key whose boolean value chooses the destination",
+    ],
+  ],
+};
+
+// [LAW:dataflow-not-control-flow] The discriminator keys are validated once
+// for every value source (they are shared across all arms of that
+// discriminator), before the source is detected — so a bad key and an
+// ambiguous source both surface in one pass. They are therefore NOT fields of
 // any arm's `fields` map; the arm parses only the value-source payload, and
-// the dispatcher re-attaches the discriminator.
-function validateValueSourceKey(
+// the dispatcher re-attaches them.
+//
+// [LAW:no-silent-failure] Returns null when ANY key fails, after reporting
+// every one of them — the caller threads that null exactly as it threads a
+// failed payload, so a partly-valid dual never reconstructs into a member
+// missing a destination.
+function validateDiscriminatorKeys(
   ctx: ValidateCtx,
   path: string,
   raw: Record<string, unknown>,
-  discriminator: "set" | "persist",
-  keyNoun: string,
-): string | null {
-  return slashFreeString(
-    ctx,
-    path,
-    discriminator,
-    raw,
-    `${discriminator} key must be non-empty (${keyNoun})`,
-    (v) => `${discriminator} key "${v}" contains "/" — keys must be slash-free`,
-  );
+  discriminator: Discriminator,
+): Record<string, string> | null {
+  const out: Record<string, string> = {};
+  const keys = DISCRIMINATOR_KEYS[discriminator];
+  let ok = true;
+  for (const [key, noun] of keys) {
+    // [LAW:no-silent-failure] An ABSENT key gets the shape, not a type
+    // mismatch. A single-destination arm cannot reach this (its key is the
+    // discriminator that selected the arm), so this only ever fires on a dual
+    // that named one destination and not the other — where "persist must be a
+    // string, got undefined" describes the symptom and teaches nothing, and
+    // the author needs to be told the three keys travel together.
+    if (!(key in raw)) {
+      issue(
+        ctx,
+        path,
+        `${key} is required here (${noun}) — a dual-destination action declares ${keys
+          .map(([k]) => k)
+          .join(", ")} together, plus one value source`,
+      );
+      ok = false;
+      continue;
+    }
+    const value = slashFreeString(
+      ctx,
+      path,
+      key,
+      raw,
+      `${key} key must be non-empty (${noun})`,
+      (v) => `${key} key "${v}" contains "/" — keys must be slash-free`,
+    );
+    if (value === null) {
+      ok = false;
+      continue;
+    }
+    out[key] = value;
+  }
+  // [LAW:no-silent-failure] Every failing key is reported before returning, so
+  // an author who omits two of a dual's three keys sees both in one pass —
+  // matching every other multi-issue check in this file, and matching what the
+  // comment above promises.
+  return ok ? out : null;
 }
 
 // [LAW:one-source-of-truth] The wire verb name a discriminator's writes
 // travel over — `set-state` for `set` (SessionState), `set-config` for
-// `persist` (the config-overrides layer). Threaded into the shared field
-// specs below so their "cannot be delivered on the X wire" messages name
-// the wire the value actually crosses, and the field/value noun ("set
+// `persist` (the config-overrides layer), and BOTH for a dual, whose one
+// value crosses whichever wire the selector names. Threaded into the shared
+// field specs below so their "cannot be delivered on the X wire" messages
+// name the wire the value actually crosses, and the field/value noun ("set
 // value" / "persist value") names the actual action kind, not always `set`.
-function wireName(discriminator: "set" | "persist"): string {
-  return discriminator === "set" ? "set-state" : "set-config";
+function wireName(discriminator: Discriminator): string {
+  if (discriminator === "set") return "set-state";
+  return discriminator === "persist" ? "set-config" : "set-state/set-config";
 }
 
 // [LAW:types-are-the-program] Each value source's payload as a field map — the
@@ -366,6 +426,15 @@ const INT_FIELDS: FieldSpecMap<{ int: true }> = { int: intMarkerSpec() };
 const CYCLE_FIELDS_SET: FieldSpecMap<{ cycle: readonly string[] }> = {
   cycle: cycleSpec("set"),
 };
+const TO_FIELDS_DUAL: FieldSpecMap<{ to: string }> = {
+  to: setLiteralSpec("dual"),
+};
+const FROM_FIELDS_DUAL: FieldSpecMap<{ from: OptionDomain }> = {
+  from: fromSpec("dual"),
+};
+const CYCLE_FIELDS_DUAL: FieldSpecMap<{ cycle: readonly string[] }> = {
+  cycle: cycleSpec("dual"),
+};
 const CYCLE_FIELDS_PERSIST: FieldSpecMap<{ cycle: readonly string[] }> = {
   cycle: cycleSpec("persist"),
 };
@@ -466,13 +535,14 @@ interface ValueSourceArm {
 // discriminator (the field no sibling arm carries) here; omit it when the
 // field set already is disjoint from every sibling, as it is everywhere else.
 function valueSourceArm<P extends object>(
-  discriminator: "set" | "persist",
+  discriminator: Discriminator,
   fieldMap: FieldSpecMap<P>,
   checks: ReadonlyArray<Refinement<P>> = [],
   detectKeys?: readonly string[],
 ): ValueSourceArm {
   const fullKeys = Object.keys(fieldMap);
   const detect = detectKeys ?? fullKeys;
+  const keys = DISCRIMINATOR_KEYS[discriminator].map(([k]) => k);
   const inner: ArmParse<P> = (ctx, path, raw) =>
     fields(ctx, fieldMap, path, raw);
   const source = objectJson(fieldMap) as {
@@ -481,12 +551,15 @@ function valueSourceArm<P extends object>(
   };
   return {
     detect,
-    allowed: [discriminator, ...fullKeys],
+    allowed: [...keys, ...fullKeys],
     label: fullKeys.join("/"),
     json: {
       type: "object",
-      properties: { [discriminator]: { type: "string" }, ...source.properties },
-      required: [discriminator, ...(source.required ?? [])],
+      properties: {
+        ...Object.fromEntries(keys.map((k) => [k, { type: "string" }])),
+        ...source.properties,
+      },
+      required: [...keys, ...(source.required ?? [])],
       additionalProperties: false,
     },
     parse: (checks.length
@@ -531,12 +604,25 @@ const PERSIST_ARMS: readonly ValueSourceArm[] = [
   ),
 ];
 
+// [LAW:one-type-per-behavior] A dual declares any value source BOTH
+// destinations share — `set` minus `int` (a page cursor has no durable
+// meaning), which is also `persist` minus its structural-edit arms (those are
+// persist-only by design, so they have no destination to choose between).
+// The field maps are the SET ones with dual wording, so a dual's value obeys
+// exactly the shape a `set` and a `persist` of that source each obey.
+const DUAL_ARMS: readonly ValueSourceArm[] = [
+  valueSourceArm("dual", TO_FIELDS_DUAL),
+  valueSourceArm("dual", FROM_FIELDS_DUAL),
+  valueSourceArm("dual", BOUNDED_FIELDS, [minLessThanMax, byNonZero]),
+  valueSourceArm("dual", CYCLE_FIELDS_DUAL),
+];
+
 // [LAW:one-source-of-truth] The clause list, not the joined string, is the
 // data that varies per discriminator — the "or" belongs on the LAST clause
 // only, and which clause is last differs between `set` (ends at cycle) and
 // `persist` (ends at insertSegment), so building a list and joining it is
 // what keeps that placement correct without a second copy of the sentence.
-function valueSourceClauses(discriminator: "set" | "persist"): string[] {
+function valueSourceClauses(discriminator: Discriminator): string[] {
   const clauses = [
     `"to" (a literal value)`,
     `"from" (an option domain — a registered domain name like "themes"/"styles"/"looks", or an inline array of literal values)`,
@@ -555,7 +641,7 @@ function valueSourceClauses(discriminator: "set" | "persist"): string[] {
   return clauses;
 }
 
-function VALUE_SOURCE_MESSAGE(discriminator: "set" | "persist"): string {
+function VALUE_SOURCE_MESSAGE(discriminator: Discriminator): string {
   const clauses = valueSourceClauses(discriminator);
   const last = clauses[clauses.length - 1]!;
   const list =
@@ -576,17 +662,10 @@ function valueSourceAction(
   ctx: ValidateCtx,
   path: string,
   raw: Record<string, unknown>,
-  discriminator: "set" | "persist",
+  discriminator: Discriminator,
   arms: readonly ValueSourceArm[],
-  keyNoun: string,
 ): ActionDecl | null {
-  const stateKey = validateValueSourceKey(
-    ctx,
-    path,
-    raw,
-    discriminator,
-    keyNoun,
-  );
+  const keys = validateDiscriminatorKeys(ctx, path, raw, discriminator);
 
   const present = arms.filter((arm) => arm.detect.some((k) => k in raw));
   if (present.length !== 1) {
@@ -613,9 +692,9 @@ function valueSourceAction(
   }
 
   const payload = arm.parse(ctx, path, raw);
-  return stateKey === null || payload === null
+  return keys === null || payload === null
     ? null
-    : ({ [discriminator]: stateKey, ...payload } as unknown as ActionDecl);
+    : ({ ...keys, ...payload } as unknown as ActionDecl);
 }
 
 // [LAW:no-silent-fallbacks] A literal `to` and the discriminator key share
@@ -624,7 +703,7 @@ function valueSourceAction(
 // arm's, the shape is the shared enforcer's. Built once per discriminator
 // (see TO_FIELDS_SET/TO_FIELDS_PERSIST) so a `persist` action's message names
 // "persist value" and the set-config wire, never `set`'s wording.
-function setLiteralSpec(discriminator: "set" | "persist"): FieldSpec<string> {
+function setLiteralSpec(discriminator: Discriminator): FieldSpec<string> {
   const wire = wireName(discriminator);
   return {
     required: true,
@@ -654,7 +733,7 @@ function setLiteralSpec(discriminator: "set" | "persist"): FieldSpec<string> {
 // symmetric to how a layout node's segment ref or a `{{ action }}` ref
 // resolves post-merge. Built once per discriminator, same reason as
 // setLiteralSpec.
-function fromSpec(discriminator: "set" | "persist"): FieldSpec<OptionDomain> {
+function fromSpec(discriminator: Discriminator): FieldSpec<OptionDomain> {
   const wire = wireName(discriminator);
   return {
     required: true,
@@ -733,9 +812,7 @@ function fromSpec(discriminator: "set" | "persist"): FieldSpec<OptionDomain> {
 // duplicated member is ambiguous). Members double as the derived allow-list
 // gate, so a member this spec admits is a value the wire delivers, by
 // construction. Built once per discriminator, same reason as setLiteralSpec.
-function cycleSpec(
-  discriminator: "set" | "persist",
-): FieldSpec<readonly string[]> {
+function cycleSpec(discriminator: Discriminator): FieldSpec<readonly string[]> {
   const wire = wireName(discriminator);
   return {
     required: true,

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

@@ -19,6 +19,8 @@ import {
   actionBindsRedo,
   actionBindsReset,
   actionBindsSet,
+  actionIsDual,
+  PERSIST_WHEN,
   actionBindsUndo,
   type ActionDecl,
 } from "../action.js";
@@ -160,6 +162,30 @@ export function validateCrossReferences(
       });
     }
   }
+  // [LAW:no-silent-failure] A dual action's `persistWhen` must name a key some
+  // `state` variable declares. The structural pass proves only that it is a
+  // deliverable wire key; whether it RESOLVES is a cross-ref concern, exactly
+  // as `from`'s domain is above.
+  //
+  // Without this, a typo loads perfectly cleanly and then does nothing
+  // forever: compileDual falls back to the raw key name, activeDestination
+  // reads it, finds nothing, and `parseSessionBoolean` answers null — which
+  // means "session". So the checkbox the author wired to the real key flips a
+  // value no control reads, the destination never changes, and there is no
+  // error anywhere to explain why. A silently-permanent session write is the
+  // worst possible shape for this failure, since it looks exactly like
+  // working software.
+  for (const [name, a] of Object.entries(cfg.actions)) {
+    if (!actionIsDual(a)) continue;
+    const selector = a[PERSIST_WHEN];
+    if (!declaresStateKey(cfg, selector)) {
+      ctx.issues.push({
+        path: `actions.${name}.${PERSIST_WHEN}`,
+        message: `actions.${name} ${PERSIST_WHEN}: "${selector}" is not a declared state key — a dual action's selector must name a { kind: "state", key: "${selector}" } variable, or the destination can never change`,
+        line: findKeyLine(ctx.source, ["actions", name, PERSIST_WHEN]),
+      });
+    }
+  }
   // [LAW:no-silent-failure] A `persist`/`reset` target must name a REAL
   // Globals field OR a declared segment's `palette` (candybar-config-engine-
   // 71o.6 — `segments.<name>.palette`, parsed by the one shared authority in
@@ -537,17 +563,29 @@ function checkPresetRootOpsTarget(
   }
 }
 
+// [LAW:one-source-of-truth] Every `state` variable a config declares, in BOTH
+// scopes — global `variables` and each segment's own `vars`. A segment-local
+// state variable is fully legitimate: src/dsl/render.ts's stateKeyToVar
+// registers them (as `<segment>.<var>`) and it is the map a dual's selector is
+// resolved through at render, so a load-time check that scanned only the
+// global scope would reject configs that work.
+function stateVars(cfg: DslConfig): VariableDecl[] {
+  return [
+    ...Object.values(cfg.variables),
+    ...Object.values(cfg.segments).flatMap((seg) =>
+      Object.values(seg.vars ?? {}),
+    ),
+  ].filter((v) => v.kind === "state");
+}
+
 function hasStateKind(cfg: DslConfig): boolean {
-  for (const v of Object.values(cfg.variables)) {
-    if (v.kind === "state") return true;
-  }
-  for (const seg of Object.values(cfg.segments)) {
-    if (!seg.vars) continue;
-    for (const v of Object.values(seg.vars)) {
-      if (v.kind === "state") return true;
-    }
-  }
-  return false;
+  return stateVars(cfg).length > 0;
+}
+
+// Does any declared `state` variable hold this key? The question a dual's
+// `persistWhen` selector has to answer, asked over the same two scopes.
+function declaresStateKey(cfg: DslConfig, key: string): boolean {
+  return stateVars(cfg).some((v) => v.kind === "state" && v.key === key);
 }
 
 // [LAW:dataflow-not-control-flow] A config emits a set-state, set-config,

package/src/config/loader/globals.ts

@@ -7,6 +7,7 @@ import { type Globals } from "../dsl-types.js";
 import {
   CHARSETS,
   COLOR_COMPATIBILITIES,
+  DEFAULT_PADDING,
   PADDING_RANGE,
   STRIP_STYLES,
   type ColorCompatibility,
@@ -193,3 +194,42 @@ export function isGlobalsField(key: string): key is keyof Globals {
 export function listGlobalsFieldNames(): readonly string[] {
   return [...GLOBALS_FIELD_NAMES];
 }
+
+// [LAW:types-are-the-program] Every NUMERIC globals field with the value that
+// renders when a config declares none, typed TOTAL over those fields — so
+// adding a numeric globals field without a floor is a COMPILE error, not a
+// silent seed-from-`min` (the bug this table exists to prevent, recurring for
+// the new field). It lives here rather than beside DEFAULT_PADDING in
+// themes/policy.ts because it must name `Globals`, and policy.ts is the leaf
+// dsl-types imports FROM — a table that needs both belongs on this side of
+// that edge [LAW:one-way-deps].
+// The direction matters: `NonNullable<Globals[K]> extends number` asks "is this
+// field's type a number", which is what the totality claim needs. The mirror
+// (`number extends …`) happens to agree for a field declared as plain `number`
+// — the two are symmetric there — but silently drops a field typed as a
+// literal union (`zoom?: 1 | 2 | 3`), which is a perfectly ordinary way to
+// declare a bounded numeric setting and exactly the case this guard exists for.
+type NumericGlobalsField = {
+  [K in keyof Globals]-?: NonNullable<Globals[K]> extends number ? K : never;
+}[keyof Globals];
+
+const NUMERIC_GLOBALS_FLOORS: Readonly<Record<NumericGlobalsField, number>> = {
+  padding: DEFAULT_PADDING,
+};
+
+// [LAW:single-enforcer] THE seed for a bounded stepper over a globals field:
+// what the bar renders with no write of any kind — the config's own value, or
+// the field's floor when it declares none. Both write gates read it (the
+// SessionState one through stateKeySeeds, the config-overrides one through
+// configKeySeeds), so a session stepper and its durable twin can never start
+// from different numbers, and neither can silently start from `min`.
+export function numericGlobalsSeeds(
+  globals: Globals,
+): ReadonlyMap<string, number> {
+  const seeds = new Map<string, number>();
+  for (const [field, floor] of Object.entries(NUMERIC_GLOBALS_FLOORS)) {
+    const declared = globals[field as keyof Globals];
+    seeds.set(field, typeof declared === "number" ? declared : floor);
+  }
+  return seeds;
+}

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(