@promptctl/cc-candybar 1.8.1 → 1.8.3

package/src/render/menu.ts

@@ -1,58 +1,112 @@
 // [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 —
-// dropped onto the next line. It composes the two existing helpers, adding only
-// the disclosure: the glyph is realized through the synthesized cycle action
-// (`renderAction`), the body through the one picker renderer (`renderPicker`).
+// 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
+// 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] A menu is CONTEXT-FREE in the template but its
-// accordion identity (which row key, which member name) is a fact about WHERE its
-// host segment sits — derived once in menu-keys and published into this runtime
-// by the render walk before each segment's template evaluates. The helper reads
-// that placement; it never invents a key from its own argument string, so the
-// rendered toggle and the loader-synthesized state var + gate share one source.
+// [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
+// body carried as out-of-band metadata on that returned RichText (a symbol the
+// segment boundary reads). It mutates no shared sink; the EFFECT of placing the
+// body below the row is performed at the boundary (collectMenuDrops + the segment
+// walk). Pure core returns a description; the edge performs it.
 //
-// [LAW:dataflow-not-control-flow] Openness is the value of the row key, not a
-// when-gated reveal: open ⇔ the row key holds THIS menu's member name. Open is a
-// length-1 drop appended after a "\n"; closed is just the glyph. One expression,
-// one returned RichText (the "\n" splits into a dropped line downstream).
+// [LAW:decomposition] The glyph and the body travel on SEPARATE channels: the
+// glyph is the visible fragment, the body rides as metadata invisible to the
+// inline render. This is the fix for the old `\n`-in-the-stream representation —
+// the body never enters the visible inline text, so a menu may sit ANYWHERE in a
+// template (content after it stays inline on row 0), and a segment may contain
+// ANY NUMBER of menus (each returned glyph carries its own body).
+//
+// [LAW:one-source-of-truth] A menu is CONTEXT-FREE about its NAME in the template
+// (it cannot see the segment it sits in), so the host segment name is published
+// into this runtime by the render walk before each segment's template evaluates.
+// The helper combines that segment name with its own apply-action arg (and an
+// optional shared key) to derive identity via menu-keys — the SAME derivation the
+// loader synthesis uses — so the rendered toggle and the loader-synthesized state
+// var + gate share one source.
+//
+// [LAW:dataflow-not-control-flow] Openness is the value of the menu's state key,
+// not a when-gated reveal: open ⇔ the state key holds THIS menu's member name.
+// The body metadata is a list whose length carries open/closed (1 open, 0 closed).
 
-import { RichText } from "@promptctl/rich-js";
+import type { RichText } from "@promptctl/rich-js";
 import type { FuncMap } from "@promptctl/go-template-js";
 import {
+  MENU_CLOSED,
   MENU_GLYPH_CLOSED,
   MENU_GLYPH_OPEN,
-  menuActionName,
+  menuMember,
   menuStateKey,
 } from "../config/menu-keys.js";
-import { readVar, renderAction, type ActionRuntime } from "./action.js";
+import { effectsUrl, VERB_SET_STATE } from "../click/wire.js";
+import { linkFragment, readVar, type ActionRuntime } from "./action.js";
 import { renderPicker } from "./picker.js";
 
-// [LAW:types-are-the-program] One menu placement: the structural facts a context-
-// free `{{ menu }}` cannot see about itself. Published by the walk per segment
-// render; the helper reads the live value.
+// [LAW:types-are-the-program] One menu placement: the structural fact a context-
+// free `{{ menu }}` cannot see about itself — the name of the segment it renders
+// inside. Published by the walk per segment render; the helper reads the live
+// value to derive identity.
 export interface MenuPlacement {
-  readonly rowKey: string;
   readonly segName: string;
 }
 
 // [LAW:locality-or-seam] The runtime the `menu` func closes over. It shares the
 // ACTION runtime (the menu's glyph and body resolve their actions/state from the
-// same compiled table + store as every other helper) and reads the walk-published
-// current placement. `current` is mutated by the single owner (the render walk,
-// set immediately before each segment template eval) — the spatial cousin of the
-// hue cursor, one mutator, never ambient. [LAW:no-ambient-temporal-coupling]
+// same compiled table + store as every other helper) and READS the walk-published
+// current placement — both inputs, never written by the helper. `current` is
+// mutated only by the single owner (the render walk, before each segment eval) —
+// the spatial cousin of the hue cursor, one mutator, never ambient.
+// [LAW:no-ambient-temporal-coupling]
 export interface MenuRuntime {
   readonly action: ActionRuntime;
   current: MenuPlacement | null;
 }
 
-// Realize a `{{ menu }}` against the live placement + state into ONE RichText.
+// [LAW:effects-at-boundaries] The body a `{{ menu }}` drops below its row rides as
+// out-of-band metadata on the returned glyph (a symbol the boundary reads), so the
+// helper returns a description rather than mutating a shared sink. A list whose
+// length carries open/closed — `[body]` open, `[]` closed.
+const MENU_DROP = Symbol("cc-candybar.menuDrop");
+type GlyphWithDrop = RichText & { [MENU_DROP]?: readonly RichText[] };
+
+// [LAW:single-enforcer] THE reader of the drop metadata, used by the segment
+// boundary (injected by the driver — node-registry never imports this module).
+// Scans a segment's evaluated fragments in template order and returns every menu
+// body carried on them; a fragment with no metadata contributes nothing.
+export function collectMenuDrops(
+  fragments: readonly RichText[],
+): readonly RichText[] {
+  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,
   runtime: MenuRuntime,
 ): RichText {
   const placement = runtime.current;
@@ -65,35 +119,64 @@ function renderMenu(
       "{{ menu }} rendered with no active segment placement — the render walk must publish one before evaluating a segment template",
     );
   }
-  const { rowKey, segName } = placement;
   const action = runtime.action;
+  const stateKey = menuStateKey(placement.segName, applyName, sharedKey);
+  const member = menuMember(applyName);
 
-  // [LAW:single-enforcer] The disclosure glyph IS the synthesized cycle action —
-  // displays bound one-per-member (closed ▸ / open ▾), the current member's glyph
-  // renders, the click writes the successor. Same toggle as group sugar.
-  const glyph = renderAction(
-    menuActionName(rowKey, segName),
-    [MENU_GLYPH_CLOSED, MENU_GLYPH_OPEN],
-    action,
-  );
+  // [LAW:dataflow-not-control-flow] Open ⇔ the state key holds this menu's member.
+  // A foreign value (an accordion sibling's member under a shared key) reads as
+  // closed here — exactly the binary [closed, member] cycle the synthesized action
+  // gates. This ONE read drives both the glyph and the body, so what the glyph
+  // promises and what drops below cannot disagree.
+  const open = readVar(action.store, stateKey) === member;
 
-  // [LAW:dataflow-not-control-flow] Open ⇔ the row key holds this menu's member.
-  // Closed ⇒ just the glyph; open ⇒ glyph + "\n" + body. The "\n" is the sole
-  // vertical sentinel (splitCellsIntoLines drops the body below the row).
-  const open = readVar(action.store, menuStateKey(rowKey)) === segName;
-  if (!open) return glyph;
+  // [LAW:one-source-of-truth] / [LAW:locality-or-seam] The disclosure click is ONE
+  // atomic set-state that keeps the two split keys coherent: it toggles the open-
+  // state (the binary cycle — successor is closed when open, the member when
+  // closed) AND resets the page cursor to page 0, in one batch. So a reopened menu
+  // is never stranded on a stale page left by ←/→ before the last close. This
+  // mirrors the picker's closeOnPick page-reset fold: the picker builds its set-
+  // state URLs directly (not via renderAction) so it can couple two writes; the
+  // menu — the one part that knows BOTH the open-state key and the page key
+  // [LAW:decomposition] — does the same. The synthesized cycle action stays the
+  // 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 glyph = linkFragment(
+    open ? MENU_GLYPH_OPEN : MENU_GLYPH_CLOSED,
+    effectsUrl([
+      {
+        verb: VERB_SET_STATE,
+        args: [
+          sessionId,
+          stateKey,
+          successor,
+          pageKeyOf(action, pageName),
+          "0",
+        ],
+      },
+    ]),
+    false,
+  ) as GlyphWithDrop;
 
-  const body = renderPicker(applyName, pageName, closeOnPick, paged, action);
-  const combined = RichText.fromFragments([glyph, new RichText("\n"), body]);
-  combined.end = "";
-  return combined;
+  // [LAW:effects-at-boundaries] The body is a VALUE whose length carries open/
+  // closed — `[body]` open, `[]` closed — attached to the glyph the helper returns.
+  // 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.)
+  glyph[MENU_DROP] = open
+    ? [renderPicker(applyName, pageName, closeOnPick, 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 surface to `{{ picker }}`, since the
-// body IS a picker. The disclosure takes no argument: its identity is derived
-// from placement, never authored.
+// 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:one-way-deps] Injected into the engine by registerDslConfig as data; the
 // generic engine never imports this module.
@@ -105,15 +188,17 @@ export function menuFuncs(runtime: MenuRuntime): FuncMap {
         pageName: string,
         closeOnPick?: boolean,
         paged?: boolean,
+        key?: string,
       ) =>
         renderMenu(
           applyName,
           pageName,
           closeOnPick === true,
           paged === true,
+          key,
           runtime,
         ),
-      argTypes: ["string", "string", "bool", "bool"],
+      argTypes: ["string", "string", "bool", "bool", "string"],
       returnType: "T",
     },
   };