@promptctl/cc-candybar 1.18.1 → 1.20.0

package/src/config/menu-keys.ts

@@ -28,17 +28,11 @@
 // can never silently collide.
 export const MENU_NS = "menus.";
 
-// The "no menu open" sentinel a key starts from and returns to on close. A
-// menu's member name is its apply-action name; an apply action named exactly
-// this would make the cycle [closed, "closed"] (two identical members, never
-// openable), which the synthesis pass rejects.
-export const MENU_CLOSED = "closed";
-
-// [LAW:representation] Disclosure glyph vocabulary — identical to group sugar so
-// every disclosure across the bar reads the same (trailing the label/content it
-// gates, per pdu.8): collapsed ▸, expanded ▾.
-export const MENU_GLYPH_CLOSED = "▸";
-export const MENU_GLYPH_OPEN = "▾";
+// [LAW:one-source-of-truth] The closed sentinel and the ▸/▾ glyphs are the shared
+// disclosure primitive, not menu-specific — they live in src/config/disclosure.ts
+// (DISCLOSURE_CLOSED / DISCLOSURE_GLYPH_*) so group sugar and {{ menu }} cannot
+// drift. This module keeps only the menu's own IDENTITY derivation (member = apply
+// name; key = optional shared key), which group sugar derives differently.
 
 // [LAW:types-are-the-program] Collapse an arbitrary name to an identifier-shaped
 // id so the synthesized var/action/SessionState-key names carry no dots or
@@ -76,3 +70,76 @@ export function menuStateKey(
 export function menuActionName(stateKey: string, member: string): string {
   return stateKey + "." + member;
 }
+
+// [LAW:single-enforcer] THE page-cursor key a menu's picker body paginates by —
+// synthesized by the loader (state var + int action, both named by this key)
+// and derived again by the renderer, so neither side hand-declares or restates
+// it. One cursor PER DISCLOSURE STATE KEY, not per menu: a shared (accordion)
+// key holds at most one open member, so its one open body is the only body the
+// cursor can belong to — sharing is exact by construction, not an
+// approximation — and the disclosure toggle's page-0 reset re-seeds it on
+// every open. [LAW:one-source-of-truth] The synthesized state VARIABLE is
+// named by this same string (the disclosure-var convention), so the renderer
+// reads the live page via this one name.
+export function menuPageKey(stateKey: string): string {
+  return stateKey + ".page";
+}
+
+// [LAW:types-are-the-program] The `{{ menu }}` rare-knob options, spelled as ONE
+// trailing `(dict …)` argument. Defaults are the canonical path: paged=true (a
+// drop menu wants bounded height; a short domain paginates to one page and shows
+// no arrows anyway), closeOnPick=false (stay-open so options can be tried in a
+// row), key omitted (an independent menu).
+export interface MenuOptions {
+  readonly closeOnPick: boolean;
+  readonly paged: boolean;
+  readonly key: string | undefined;
+}
+
+// [LAW:one-source-of-truth] THE reader of a menu's options dict — the loader
+// folds it over `staticDictEntries` (gating identity at load) and the renderer
+// folds it over the evaluated dict object (realizing the body), so the option
+// vocabulary, value types, and defaults live exactly once. An unknown name or a
+// mistyped value throws with text naming the legal shape — the blind authoring
+// agent's teaching channel [LAW:no-silent-failure]; the loader attaches segment
+// context, the renderer surfaces it via composeWithDiagnostics.
+export function parseMenuOptions(
+  entries: Readonly<Record<string, unknown>>,
+): MenuOptions {
+  for (const name of Object.keys(entries)) {
+    if (name !== "closeOnPick" && name !== "paged" && name !== "key") {
+      throw new Error(
+        `unknown {{ menu }} option "${name}" — the options dict takes "closeOnPick" (bool, default false), "paged" (bool, default true), "key" (string, accordion grouping)`,
+      );
+    }
+  }
+  const bool = (name: "closeOnPick" | "paged", def: boolean): boolean => {
+    const v = entries[name];
+    if (v === undefined) return def;
+    if (typeof v !== "boolean") {
+      throw new Error(
+        `{{ menu }} option "${name}" must be a boolean, got ${JSON.stringify(v)} (e.g. (dict "${name}" ${String(!def)}))`,
+      );
+    }
+    return v;
+  };
+  const key = entries["key"];
+  if (key !== undefined && typeof key !== "string") {
+    throw new Error(
+      `{{ menu }} option "key" must be a string naming the accordion group, got ${JSON.stringify(key)}`,
+    );
+  }
+  // [LAW:types-are-the-program] An empty shared key would collapse the state key
+  // to the bare reserved `menus.` namespace (and a `menus..member` action name) —
+  // a key, when present, must name a group.
+  if (key === "") {
+    throw new Error(
+      `{{ menu }} has an empty accordion key — a shared key must be a non-empty name (or omit "key" for an independent menu)`,
+    );
+  }
+  return {
+    closeOnPick: bool("closeOnPick", false),
+    paged: bool("paged", true),
+    key,
+  };
+}

package/src/daemon/verbs/state-validators.ts

@@ -196,42 +196,35 @@ export function listStateKeys(): readonly string[] {
   return [..._STATE_VALIDATORS.keys()];
 }
 
-// [LAW:types-are-the-program] The validator is RESIDUE of the live specs: given
-// the (uniform) kind and every live registration's content, the validator is
-// forced. An int key builds a parse-boundary validator; an allow-list key builds
-// one from the UNION of every live registration's members — so a value any live
-// config can legitimately render is a value the wire accepts, by construction.
-// The label is a pure function of (key, kind) so the built validator is identical
-// across registrations of one key. makeIntValidator/makeAllowListValidator are
-// the single validator constructors (re-validating slash/empty values), so a
-// merged allow-list that somehow held an undeliverable value would throw HERE,
-// at config-load, not at the operator's first click.
+// [LAW:types-are-the-program] The validator is RESIDUE of a SETTLED spec: given
+// one merged spec, its validator is forced. This is a pure projection — kind ⇒
+// constructor — with NO union or widen of its own. The label is a pure function
+// of (key, kind) so the built validator is identical across registrations of one
+// key. makeIntValidator/makeRangeValidator/makeAllowListValidator are the single
+// validator constructors (re-validating slash/empty values), so a merged spec
+// that somehow held an undeliverable value would throw HERE, at config-load, not
+// at the operator's first click.
+function validatorForSpec(
+  key: string,
+  spec: DerivedValidatorSpec,
+): KeyValidator {
+  if (spec.kind === "int") return makeIntValidator(`menu page "${key}"`);
+  if (spec.kind === "range")
+    return makeRangeValidator(spec.min, spec.max, `stepper "${key}"`);
+  return makeAllowListValidator(spec.allowed, `state "${key}"`);
+}
+
+// [LAW:one-source-of-truth] The validator for a key's live registrations, built
+// through the ONE collapse: mergeKeySpecs unions allow-list members, widens range
+// bounds, clamps the seed, and absorbs integer members — so the union/widen logic
+// lives in exactly one place and this builder is pure plumbing (collapse → project).
+// A value any live config can legitimately render is a value the wire accepts, by
+// construction, because the rendered options and the derived gate read one merge.
 function buildValidatorFromSpecs(
   key: string,
-  kind: DerivedValidatorSpec["kind"],
   specs: readonly DerivedValidatorSpec[],
 ): KeyValidator {
-  if (kind === "int") return makeIntValidator(`menu page "${key}"`);
-  if (kind === "range") {
-    // [LAW:types-are-the-program] Two configs declaring one stepper key with
-    // different bounds widen to the UNION range — parity with allow-list's
-    // member union: a value any live config can legitimately render (step into)
-    // is a value the wire accepts. The clamp is to the widest live bounds, so
-    // the gate never rejects a write a narrower co-resident stepper could make.
-    const mins = specs.flatMap((s) => (s.kind === "range" ? [s.min] : []));
-    const maxs = specs.flatMap((s) => (s.kind === "range" ? [s.max] : []));
-    return makeRangeValidator(
-      Math.min(...mins),
-      Math.max(...maxs),
-      `stepper "${key}"`,
-    );
-  }
-  const allowed = [
-    ...new Set(
-      specs.flatMap((s) => (s.kind === "allow-list" ? s.allowed : [])),
-    ),
-  ];
-  return makeAllowListValidator(allowed, `state "${key}"`);
+  return validatorForSpec(key, mergeKeySpecs(key, specs));
 }
 
 // [LAW:locality-or-seam] The widget config (a config-load consumer) owns the
@@ -292,17 +285,13 @@ export function registerStateValidator(
       );
     }
     existing.specs.push(spec);
-    existing.validator = buildValidatorFromSpecs(
-      key,
-      existing.kind,
-      existing.specs,
-    );
+    existing.validator = buildValidatorFromSpecs(key, existing.specs);
   } else {
     const specs = [spec];
     _STATE_VALIDATORS.set(key, {
       permanent: false,
       kind: spec.kind,
-      validator: buildValidatorFromSpecs(key, spec.kind, specs),
+      validator: buildValidatorFromSpecs(key, specs),
       specs,
     });
   }
@@ -317,7 +306,7 @@ export function registerStateValidator(
     if (entry.specs.length === 0) {
       _STATE_VALIDATORS.delete(key);
     } else {
-      entry.validator = buildValidatorFromSpecs(key, entry.kind, entry.specs);
+      entry.validator = buildValidatorFromSpecs(key, entry.specs);
     }
   };
 }
@@ -700,9 +689,17 @@ export interface RangeParams {
 export function rangeParamsFor(key: string): RangeParams | null {
   const entry = _STATE_VALIDATORS.get(key);
   if (!entry || entry.permanent || entry.kind !== "range") return null;
-  const ranges = entry.specs.flatMap((s) => (s.kind === "range" ? [s] : []));
-  if (ranges.length === 0) return null;
-  const min = Math.min(...ranges.map((r) => r.min));
-  const max = Math.max(...ranges.map((r) => r.max));
-  return { min, max, seed: clampSeed(ranges[0]!.seed, min, max) };
+  // [LAW:one-source-of-truth] The bounds/seed come from THE same collapse the
+  // validator is built from (mergeKeySpecs) — no second widen/clamp lives here.
+  const spec = mergeKeySpecs(key, entry.specs);
+  // [LAW:no-silent-failure] entry.kind === "range" means every live spec is a
+  // range (registration rejects a kind change), so the collapse is a range too;
+  // a non-range here is a broken invariant, surfaced loudly, not a silent null.
+  if (spec.kind !== "range") {
+    throw new Error(
+      `rangeParamsFor: key "${key}" holds range specs but the merge produced ` +
+        `a ${spec.kind} spec — the entry-kind invariant is broken.`,
+    );
+  }
+  return { min: spec.min, max: spec.max, seed: spec.seed };
 }

package/src/index.ts

@@ -11,7 +11,8 @@ import { tryRenderViaDaemon } from "./daemon/client";
 import { runDaemonStats } from "./daemon/client-stats";
 import { runDebug } from "./daemon/client-debug";
 import { isDebugWhat } from "./daemon/debug-types";
-import { runLint, runSchema } from "./config/cli";
+import { runSchema } from "./config/cli";
+import { runCheck } from "./check";
 import { obtainDaemonKick } from "./daemon/acquire";
 import { planOutcome } from "./render/outcome-plan";
 
@@ -66,8 +67,11 @@ Subcommands (macOS):
                            request totals. Does not spawn a daemon.
 
 Config tooling:
-  lint <config-file>       Validate a config file (parse + cross-refs + cycles)
-                           with no daemon. Exit 0 valid, 1 invalid, 2 unreadable.
+  check [config-file]      Validate a config on the full render pipeline (parse
+                           → merge → validate → register → render) with no
+                           daemon. With no path, checks the same file the daemon
+                           would load from here. Exit 0 clean (warnings on
+                           stderr), 1 invalid, 2 unreadable. "lint" is an alias.
   schema                   Print the JSON Schema for the config file shape
                            (.cc-candybar.json5). Point an editor's $schema at it
                            for autocomplete + structural validation.
@@ -113,8 +117,11 @@ async function main(): Promise<void> {
       await runDaemonStats(process.argv.slice(3));
       process.exit(0);
     }
-    if (subcommand === "lint") {
-      runLint(process.argv.slice(3)); // owns its own exit code (0/1/2)
+    // [LAW:one-type-per-behavior] `lint` is an alias of `check` — one config
+    // verdict, one pipeline, one exit-code contract (0/1/2). check subsumes the
+    // old lint (same loader, plus register + render coverage).
+    if (subcommand === "check" || subcommand === "lint") {
+      runCheck(process.argv.slice(3)); // owns its own exit code (0/1/2)
       return;
     }
     if (subcommand === "schema") {

package/src/render/action.ts

@@ -333,7 +333,13 @@ function realize(
     case "set-int": {
       // The render binds the integer to write (a picker's page nav passes the
       // target page as boundValue; a bare `{{ action }}` passes its display).
-      // The unbounded int gate accepts it; active when the key already holds it.
+      // [LAW:no-silent-failure] A bare `{{ action }}` on a set-int MUST render a
+      // NUMERIC display (the manual "open at page 0" pattern: `{{ action "openMenu"
+      // "0" }}`) — the display IS the value written, and the int gate
+      // (makeIntValidator) rejects a non-integer at click with a loud "must be an
+      // integer" BAD_REQUEST. There is no load-time check because the display is a
+      // template evaluated at render (it may be dynamic), so the shape is enforced
+      // at the wire, not silently coerced. active when the key already holds it.
       const value = boundValue ?? display;
       const current = readVar(store, c.stateVar);
       return {

package/src/render/menu.ts

@@ -36,12 +36,17 @@
 import type { RichText } from "@promptctl/rich-js";
 import type { FuncMap } from "@promptctl/go-template-js";
 import {
-  MENU_CLOSED,
-  MENU_GLYPH_CLOSED,
-  MENU_GLYPH_OPEN,
   menuMember,
+  menuPageKey,
   menuStateKey,
+  parseMenuOptions,
+  type MenuOptions,
 } from "../config/menu-keys.js";
+import {
+  DISCLOSURE_CLOSED,
+  DISCLOSURE_GLYPH_CLOSED,
+  DISCLOSURE_GLYPH_OPEN,
+} 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";
@@ -83,30 +88,11 @@ export function collectMenuDrops(
   return fragments.flatMap((f) => (f as GlyphWithDrop)[MENU_DROP] ?? []);
 }
 
-// [LAW:single-enforcer] The page cursor's SessionState key, resolved from the page
-// ACTION name the menu binds (its second arg). renderPicker proves pageName is a
-// set-int when it builds the body, but the disclosure must reset the page even
-// while CLOSED (no body is built then), so it resolves the key here too — the SAME
-// set-int action, one source. A non-int page arg is an author error surfaced
-// loudly (composeWithDiagnostics shows it), never a silent skipped reset.
-function pageKeyOf(action: ActionRuntime, pageName: string): string {
-  const page = action.compiled.get(pageName);
-  if (!page || page.kind !== "set-int") {
-    throw new Error(
-      `{{ menu }} page action "${pageName}" must be an int action ({ set, int: true })`,
-    );
-  }
-  return page.key;
-}
-
 // Realize a `{{ menu }}` against the live placement + state: return its inline
 // glyph, carrying the (open) body as out-of-band metadata for the boundary.
 function renderMenu(
   applyName: string,
-  pageName: string,
-  closeOnPick: boolean,
-  paged: boolean,
-  sharedKey: string | undefined,
+  options: MenuOptions,
   runtime: MenuRuntime,
 ): RichText {
   const placement = runtime.current;
@@ -120,7 +106,12 @@ function renderMenu(
     );
   }
   const action = runtime.action;
-  const stateKey = menuStateKey(placement.segName, applyName, sharedKey);
+  // [LAW:one-source-of-truth] Identity — and the page-cursor key derived from it
+  // — comes from the SAME menu-keys derivation the loader synthesis used, so the
+  // key this render reads/writes is the key whose state var + int gate the
+  // loader emitted. No page-action argument to mis-wire.
+  const stateKey = menuStateKey(placement.segName, applyName, options.key);
+  const pageKey = menuPageKey(stateKey);
   const member = menuMember(applyName);
 
   // [LAW:dataflow-not-control-flow] Open ⇔ the state key holds this menu's member.
@@ -142,19 +133,13 @@ function renderMenu(
   // GATE source (deriveActionValidators); both keys are independently gated, so the
   // coupled batch passes the same wire gate every click does [LAW:single-enforcer].
   const sessionId = readVar(action.store, "session.id");
-  const successor = open ? MENU_CLOSED : member;
+  const successor = open ? DISCLOSURE_CLOSED : member;
   const glyph = linkFragment(
-    open ? MENU_GLYPH_OPEN : MENU_GLYPH_CLOSED,
+    open ? DISCLOSURE_GLYPH_OPEN : DISCLOSURE_GLYPH_CLOSED,
     effectsUrl([
       {
         verb: VERB_SET_STATE,
-        args: [
-          sessionId,
-          stateKey,
-          successor,
-          pageKeyOf(action, pageName),
-          "0",
-        ],
+        args: [sessionId, stateKey, successor, pageKey, "0"],
       },
     ]),
     false,
@@ -165,40 +150,48 @@ function renderMenu(
   // No shared mutation: the boundary reads this metadata to place the body.
   // (renderPicker is pure, so it is only built when open — skipping wasted
   // computation, gating no effect.)
+  // [LAW:one-source-of-truth] The body's page cursor is the identity-derived
+  // key (its synthesized state var is named by it, the disclosure-var
+  // convention), and CLOSING — the ✕ affordance or a closeOnPick pick — writes
+  // the disclosure back to the closed sentinel and resets the page, the same
+  // coupled pair the toggle glyph above writes. What the ▾ promised, ✕ delivers.
   glyph[MENU_DROP] = open
-    ? [renderPicker(applyName, pageName, closeOnPick, paged, action)]
+    ? [
+        renderPicker(
+          applyName,
+          { key: pageKey, stateVar: pageKey },
+          [
+            [stateKey, DISCLOSURE_CLOSED],
+            [pageKey, "0"],
+          ],
+          options.closeOnPick,
+          options.paged,
+          action,
+        ),
+      ]
     : [];
   return glyph;
 }
 
-// [LAW:dataflow-not-control-flow] One func; the two action NAMES select the
-// body's apply/page effects, the two optional bools are the bounded author
-// choices (closeOnPick, paged) — identical to `{{ picker }}`, since the body IS a
-// picker — and the optional trailing key is the accordion grouping: omitted ⇒ the
-// menu is independent (its own key), present ⇒ it shares that key with siblings
-// (mutually exclusive). One value, not a mode.
+// [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.
 //
 // [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,
-        pageName: string,
-        closeOnPick?: boolean,
-        paged?: boolean,
-        key?: string,
-      ) =>
-        renderMenu(
-          applyName,
-          pageName,
-          closeOnPick === true,
-          paged === true,
-          key,
-          runtime,
-        ),
-      argTypes: ["string", "string", "bool", "bool", "string"],
+      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"],
       returnType: "T",
     },
   };

package/src/render/picker.ts

@@ -99,6 +99,24 @@ function assemble(frags: readonly RichText[], paged: boolean): RichText {
   return assembled;
 }
 
+// [LAW:types-are-the-program] The page cursor a picker paginates by: the
+// SessionState `key` its ←/→/✕ clicks write and the `stateVar` that reads the
+// live page back. The standalone `{{ picker }}` resolves it from its named
+// set-int page action; a `{{ menu }}` derives it from the menu's identity
+// (menuPageKey) — one value shape, two provenances, one renderer.
+export interface PickerPage {
+  readonly key: string;
+  readonly stateVar: string;
+}
+
+// [LAW:dataflow-not-control-flow] What a "close" WRITES, as data — the (key,
+// value) pairs folded into one atomic set-state by both the ✕ affordance and a
+// closeOnPick option click. The standalone picker closes by paging to -1 (the
+// when-gate idiom); a menu closes by writing its disclosure key back to the
+// closed sentinel and resetting its page cursor. The picker itself never
+// branches on which world it is in — the writes flow in.
+export type CloseWrites = ReadonlyArray<readonly [key: string, value: string]>;
+
 // [LAW:no-defensive-null-guards] The loader proves both picker arg names resolve
 // to declared actions; this asserts the KIND each must be (apply ⇒ set-option,
 // page ⇒ set-int) — a wrong kind is an author error surfaced loudly at render
@@ -120,18 +138,19 @@ function requireKind<K extends CompiledActionDecl["kind"]>(
 
 // [LAW:dataflow-not-control-flow] The page value (and the live width) select
 // which option cells render and which boundary arrows exist — a boundary arrow is
-// an ABSENT fragment, never a skipped branch. Every affordance click is a `set`
-// on the page key: ←/→ navigate (render-computed p±1), ✕ closes (-1). Each option
-// click APPLIES its option AND (when closeOnPick) resets the page key to -1 in one
-// atomic set-state — the picker owns the page key, so it derives the close-write
-// rather than the author re-stating the key.
+// an ABSENT fragment, never a skipped branch. ←/→ navigate the page key
+// (render-computed p±1); ✕ performs the caller-supplied close writes; each
+// option click APPLIES its option AND (when closeOnPick) folds the same close
+// writes into one atomic set-state — the caller owns what closing means, so the
+// author never re-states a key.
 // [LAW:single-enforcer] Exported so the `{{ menu }}` helper renders its body
 // through the SAME picker renderer — a menu body IS a picker grid; there is no
 // second grid implementation to drift. The menu adds only the disclosure
 // wrapper, never a parallel picker.
 export function renderPicker(
   applyName: string,
-  pageName: string,
+  page: PickerPage,
+  close: CloseWrites,
   closeOnPick: boolean,
   paged: boolean,
   runtime: ActionRuntime,
@@ -142,12 +161,6 @@ export function renderPicker(
     "set-option",
     "a set-option action ({ set, from })",
   );
-  const page = requireKind(
-    runtime,
-    pageName,
-    "set-int",
-    "an int action ({ set, int: true })",
-  );
   const store = runtime.store;
   const sessionId = readVar(store, "session.id");
   const current = readVar(store, apply.stateVar);
@@ -201,20 +214,23 @@ export function renderPicker(
     effectsUrl([
       { verb: VERB_SET_STATE, args: [sessionId, page.key, String(value)] },
     ]);
+  // [LAW:dataflow-not-control-flow] The close writes arrive as data (see
+  // CloseWrites); ✕ performs exactly them, and a closeOnPick option click folds
+  // the same pairs into its apply write — one atomic set-state either way, so
+  // "what closing means" cannot diverge between the two affordances.
+  const closeFlat = close.flatMap(([k, v]) => [k, v]);
+  const closeUrl = effectsUrl([
+    { verb: VERB_SET_STATE, args: [sessionId, ...closeFlat] },
+  ]);
   const optionUrl = (option: string): string =>
     effectsUrl([
       {
         verb: VERB_SET_STATE,
-        args: [
-          sessionId,
-          apply.key,
-          option,
-          ...(closeOnPick ? [page.key, "-1"] : []),
-        ],
+        args: [sessionId, apply.key, option, ...(closeOnPick ? closeFlat : [])],
       },
     ]);
 
-  const frags: RichText[] = [linkFragment(PICKER_CLOSE, pageUrl(-1), false)];
+  const frags: RichText[] = [linkFragment(PICKER_CLOSE, closeUrl, false)];
   if (pageIdx > 0) {
     frags.push(linkFragment(PICKER_PREV, pageUrl(pageIdx - 1), false));
   }
@@ -254,14 +270,26 @@ export function pickerFuncs(runtime: ActionRuntime): FuncMap {
         pageName: string,
         closeOnPick?: boolean,
         paged?: boolean,
-      ) =>
-        renderPicker(
-          applyName,
+      ) => {
+        // [LAW:one-source-of-truth] The standalone picker's page cursor comes
+        // from its NAMED set-int action (the documented desugaring surface);
+        // closing means paging to -1, the when-gate idiom its host row reads
+        // (`{{ ge (int .page) 0 }}`).
+        const page = requireKind(
+          runtime,
           pageName,
+          "set-int",
+          "an int action ({ set, int: true })",
+        );
+        return renderPicker(
+          applyName,
+          { key: page.key, stateVar: page.stateVar },
+          [[page.key, "-1"]],
           closeOnPick === true,
           paged === true,
           runtime,
-        ),
+        );
+      },
       argTypes: ["string", "string", "bool", "bool"],
       returnType: "T",
     },