@promptctl/cc-candybar 1.38.0 → 1.40.0

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));
   }

package/src/themes/policy.ts

@@ -52,14 +52,30 @@ export function resolvePaletteName(name: string): string {
 // default rather than throw or render something the label disagrees with
 // [LAW:no-silent-failure] — the caller publishes what this returns as
 // `<field>.effective`, so bar and label always trace to one value.
+//
+// [LAW:one-source-of-truth] `staged` is the RIGHTMOST rung of the precedence
+// chain documented in src/config/presets.ts — a fragment some transient MODE of
+// the bar puts on top while it is on (today: edit mode's `editGlobals`). It
+// outranks even the session pick because it is decided LATER: a user picks a
+// style, then afterwards enters edit mode. That is the same lifetime rule that
+// forced the preset's own position, applied one rung further along, which is
+// why it is a parameter of THIS function rather than a check at any call site —
+// a chain with a rung missing from one field is exactly the drift a single
+// resolver exists to prevent.
+//
+// [LAW:dataflow-not-control-flow] Absent ⇒ `undefined`, which the `??` chain
+// skips by the same code path a session that never clicked skips its own rung.
+// There is no "is edit mode on" branch anywhere below this line; the mode is
+// carried entirely by whether this argument has a value.
 export function effectiveGlobal<T>(
+  staged: T | null | undefined,
   sessionPick: string | null,
   configDefault: T | null | undefined,
   floor: T,
   parseSession: (raw: string) => T | null,
 ): T {
   const picked = sessionPick === null ? null : parseSession(sessionPick);
-  return picked ?? configDefault ?? floor;
+  return staged ?? picked ?? configDefault ?? floor;
 }
 
 // The theme name a render should use, as data.
@@ -70,10 +86,12 @@ export function effectiveGlobal<T>(
 // parse is identity: there is no membership to check here, and pretending
 // otherwise would collapse names `paletteForThemeName` handles fine.
 export function effectiveThemeName(
+  stagedPalette: string | undefined,
   sessionTheme: string | null,
   globalsPalette: string | undefined,
 ): string {
   return effectiveGlobal(
+    stagedPalette,
     sessionTheme,
     globalsPalette,
     "textual-dark",
@@ -110,7 +128,12 @@ export function listResolvablePaletteNames(): readonly string[] {
 //
 // The floor's membership is a load-time guarantee, not a runtime hope: the
 // bundled stdlib ships it and merge-by-name cannot remove it.
+//
+// The staged rung runs through the SAME membership parse the other two do: a
+// fragment naming a member the config does not declare is no more a pick than a
+// stale session entry is, and collapses one rung onward rather than throwing.
 export function effectiveMemberName(
+  stagedName: string | undefined,
   sessionPick: string | null,
   configDefault: string | undefined,
   floor: string,
@@ -119,6 +142,7 @@ export function effectiveMemberName(
   const member = (raw: string): string | null =>
     Object.prototype.hasOwnProperty.call(declared, raw) ? raw : null;
   return effectiveGlobal(
+    stagedName === undefined ? null : member(stagedName),
     sessionPick,
     member(configDefault ?? floor),
     floor,
@@ -133,11 +157,18 @@ export function effectiveMemberName(
 // carries. A named wrapper (not a bare call at each site) so the floor is
 // spelled once and the three call sites cannot disagree about it.
 export function effectiveLookName(
+  stagedLook: string | undefined,
   sessionLook: string | null,
   globalsLook: string | undefined,
   declaredLooks: Readonly<Record<string, ThemeKey>>,
 ): string {
-  return effectiveMemberName(sessionLook, globalsLook, "none", declaredLooks);
+  return effectiveMemberName(
+    stagedLook,
+    sessionLook,
+    globalsLook,
+    "none",
+    declaredLooks,
+  );
 }
 
 // [LAW:single-enforcer] The one place an effective look NAME becomes the
@@ -196,11 +227,16 @@ export function isStripStyle(value: string): value is StripStyle {
 // [LAW:one-source-of-truth]; test/session-globals.test.ts pins it with a stale
 // pick over a valid non-floor default, the case the old tests never exercised.
 export function effectiveStripStyle(
+  stagedStyle: StripStyle | undefined,
   sessionStyle: string | null,
   globalsStyle: StripStyle | undefined,
 ): StripStyle {
-  return effectiveGlobal(sessionStyle, globalsStyle, "powerline", (raw) =>
-    isStripStyle(raw) ? raw : null,
+  return effectiveGlobal(
+    stagedStyle,
+    sessionStyle,
+    globalsStyle,
+    "powerline",
+    (raw) => (isStripStyle(raw) ? raw : null),
   );
 }
 
@@ -323,10 +359,12 @@ function parsePadding(raw: string): number | null {
 // Whether a render wraps over-wide rows, as data. The session's pick over the
 // config default over the on floor — `effectiveGlobal` with a boolean domain.
 export function effectiveAutoWrap(
+  stagedAutoWrap: boolean | undefined,
   sessionAutoWrap: string | null,
   globalsAutoWrap: boolean | undefined,
 ): boolean {
   return effectiveGlobal(
+    stagedAutoWrap,
     sessionAutoWrap,
     globalsAutoWrap,
     DEFAULT_WRAP,
@@ -341,10 +379,12 @@ export function effectiveAutoWrap(
 // own default is the honest answer rather than a render at a width nobody
 // chose.
 export function effectivePadding(
+  stagedPadding: number | undefined,
   sessionPadding: string | null,
   globalsPadding: number | undefined,
 ): number {
   return effectiveGlobal(
+    stagedPadding,
     sessionPadding,
     globalsPadding,
     DEFAULT_PADDING,