@promptctl/cc-candybar 1.7.3 → 1.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.7.3",
+  "version": "1.8.1",
   "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",
@@ -85,16 +85,16 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@promptctl/go-template-js": "^0.3.0",
-    "@promptctl/rich-js": "^0.5.2",
+    "@promptctl/go-template-js": "^0.5.0",
+    "@promptctl/rich-js": "^0.6.0",
     "json5": "^2.2.3",
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.7.3",
-    "@promptctl/cc-candybar-darwin-x64": "1.7.3",
-    "@promptctl/cc-candybar-linux-x64": "1.7.3",
-    "@promptctl/cc-candybar-linux-arm64": "1.7.3"
+    "@promptctl/cc-candybar-darwin-arm64": "1.8.1",
+    "@promptctl/cc-candybar-darwin-x64": "1.8.1",
+    "@promptctl/cc-candybar-linux-x64": "1.8.1",
+    "@promptctl/cc-candybar-linux-arm64": "1.8.1"
   },
   "pnpm": {
     "supportedArchitectures": {

package/src/config/dsl-loader.ts

@@ -48,6 +48,7 @@ import { validateGlobals } from "./loader/globals.js";
 import { validateVariables } from "./loader/variables.js";
 import { validateSegments } from "./loader/segments.js";
 import { synthesizeGroupDecls, validateRoot } from "./loader/layout.js";
+import { synthesizeMenuDecls } from "./loader/menu-synth.js";
 import { validateActions } from "./loader/actions.js";
 import { validateHelpers } from "./loader/helpers.js";
 import { validateCrossReferences } from "./loader/cross-ref.js";
@@ -249,6 +250,13 @@ function validateTopLevel(
   // default and cross-ref like any user declaration), and user names under the
   // reserved namespace are rejected against the fully-parsed sections.
   synthesizeGroupDecls(ctx, out);
+  // [LAW:one-source-of-truth] Menu synthesis runs AFTER group synthesis (a group
+  // body may host menu-bearing segments) and after every section parsed: each
+  // menu placement detected in the root walk emits its state var + cycle action
+  // into the raw sections, so they merge over the default, derive the click gate
+  // through deriveActionValidators, and collide loudly with any user name under
+  // the reserved namespace.
+  synthesizeMenuDecls(ctx, out);
   return out;
 }
 

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

@@ -0,0 +1,156 @@
+// [LAW:one-source-of-truth] The menu synthesis pass: the load-side mirror of the
+// `{{ menu }}` render helper. A menu is the group-accordion mechanism with its
+// trigger living inside an arbitrary user segment rather than a synthesized
+// toggle segment — so this emits exactly what group sugar does MINUS the segment
+// (the helper IS the trigger): one `state` var per row key (default "closed")
+// and one `cycle` action per (row, menu-bearing segment) under the reserved
+// `menus.` namespace. Both land in the raw sections so they merge over the
+// default and, crucially, so `deriveActionValidators(config.actions)` derives the
+// click gate from them through the ONE existing path — a menu toggle is gated
+// like every other set, no parallel verb. [LAW:single-enforcer]
+//
+// Runs in `parseDslConfig` after group synthesis and after every section parsed,
+// so the reserved-namespace collision check sees the fully-parsed user sections.
+//
+// [LAW:types-are-the-program] WHICH segments host a menu is read from the parsed
+// AST (`referencedFunctions`), not a source-text scan — robust against whitespace,
+// pipelines, and `.menu`/"menu" lookalikes. Detection bare-parses the segment
+// template; a parse failure here is treated as "no menu" because the authoritative
+// parse error is surfaced loudly by `registerDslConfig` when it compiles the same
+// template (so this pass never swallows a real error, it just declines to guess).
+
+import { createEngine } from "@promptctl/go-template-js";
+import type { ActionDecl } from "../action.js";
+import type { Mutable, ValidateCtx } from "./validate-core.js";
+import {
+  MENU_CLOSED,
+  MENU_NS,
+  forEachSegmentPlacement,
+  menuActionName,
+  menuStateKey,
+} from "../menu-keys.js";
+import type { RawDslConfig, VariableDecl } from "../dsl-types.js";
+import { findKeyLine } from "./diagnostics.js";
+
+// [LAW:single-enforcer] The helper-name a `{{ menu … }}` call uses — the same
+// string the render FuncMap registers. A segment "hosts a menu" iff its template
+// references this function.
+const MENU_FUNC = "menu";
+
+// [LAW:no-defensive-null-guards] A bare engine purely for AST introspection: it
+// never evaluates, so `fromString` is identity and no funcs are registered (parse
+// does not resolve function existence — that is an eval-time concern).
+function segmentReferencesMenu(template: string): boolean {
+  const engine = createEngine<string>({ fromString: (s) => s });
+  try {
+    return engine.parse(template).referencedFunctions().has(MENU_FUNC);
+  } catch {
+    // A malformed template can host no usable menu; registerDslConfig re-parses
+    // and reports the real error. [LAW:no-silent-failure] — not swallowed, just
+    // not the place that reports it.
+    return false;
+  }
+}
+
+function menuIssue(ctx: ValidateCtx, path: string, message: string): void {
+  ctx.issues.push({ path, message, line: findKeyLine(ctx.source, ["root"]) });
+}
+
+export function synthesizeMenuDecls(
+  ctx: ValidateCtx,
+  out: Mutable<RawDslConfig>,
+): void {
+  // [LAW:single-enforcer] The `menus.` namespace is reserved UNCONDITIONALLY — a
+  // user name under it is rejected whether or not any menu is placed this load, so
+  // the reservation is a stable contract ("you never author menus.*"), not a rule
+  // that only switches on when synthesis happens to collide. Runs before any early
+  // return so a `menus.*` user name can never load silently.
+  for (const section of ["variables", "actions", "segments"] as const) {
+    for (const name of Object.keys(out[section] ?? {})) {
+      if (name.startsWith(MENU_NS)) {
+        menuIssue(
+          ctx,
+          `${section}.${name}`,
+          `"${name}" is in the reserved "${MENU_NS}" namespace (synthesized by {{ menu }} helpers) — rename it`,
+        );
+      }
+    }
+  }
+
+  // [LAW:no-silent-failure] A menu derives its accordion identity from its host
+  // SEGMENT's tree position; a `{{ define }}` helper is shared and placement-
+  // agnostic, so a `{{ menu }}` reached through one has no row to key on and would
+  // never get its backing state var/cycle action synthesized — failing at render.
+  // Reject it loudly at load, pointing the author to inline the menu in a segment.
+  // [LAW:no-mode-explosion] We reject rather than build helper-call-graph
+  // resolution speculatively; revisit only if a real shared-menu need appears.
+  for (const [name, body] of Object.entries(out.helpers ?? {})) {
+    if (segmentReferencesMenu(body)) {
+      ctx.issues.push({
+        path: `helpers.${name}`,
+        message: `helper "${name}" uses {{ menu }}, but a menu must live directly in a segment template — its accordion identity is derived from the segment's position in the layout, which a shared helper does not have. Inline the {{ menu }} call into each segment that needs it.`,
+        line: findKeyLine(ctx.source, ["helpers", name]),
+      });
+    }
+  }
+
+  if (out.root === undefined) return;
+  const segments = out.segments ?? {};
+
+  // [LAW:dataflow-not-control-flow] Memoize detection by segment name — a segment
+  // placed in N rows is parsed once, then each placement reads the cached verdict.
+  const hostsMenu = new Map<string, boolean>();
+  const referencesMenu = (segName: string): boolean => {
+    const cached = hostsMenu.get(segName);
+    if (cached !== undefined) return cached;
+    const seg = segments[segName];
+    const result =
+      seg !== undefined ? segmentReferencesMenu(seg.template) : false;
+    hostsMenu.set(segName, result);
+    return result;
+  };
+
+  // One state key per row (default "closed"); one cycle action per (row,segment).
+  const stateKeys = new Map<string, string>(); // stateKey → rowKey (for vars)
+  const actions: Record<string, ActionDecl> = {};
+  forEachSegmentPlacement(out.root, (segName, rowKey) => {
+    if (!referencesMenu(segName)) return;
+    // [LAW:types-are-the-program] A menu's member name IS its host segment name;
+    // a segment named exactly the closed-state sentinel would make the cycle
+    // [closed, "closed"] — two identical members, so the toggle could never leave
+    // the closed state. Reject that one collision at load (the only segment name
+    // that breaks a menu), rather than silently synthesizing an unopenable menu.
+    if (segName === MENU_CLOSED) {
+      menuIssue(
+        ctx,
+        `segments.${segName}`,
+        `segment "${segName}" hosts a {{ menu }}, but a menu cannot live in a segment named "${MENU_CLOSED}" — that name collides with the menu's closed-state sentinel, leaving the menu unopenable. Rename the segment.`,
+      );
+      return;
+    }
+    const stateKey = menuStateKey(rowKey);
+    stateKeys.set(stateKey, rowKey);
+    // [LAW:one-source-of-truth] Members ordered closed-first: an unset/foreign
+    // value counts as the first member (the cycle's "unknown ⇒ first" rule), so a
+    // never-clicked menu renders ▸ and a click opens it, auto-closing a row-mate
+    // because the shared key can hold only one member name.
+    actions[menuActionName(rowKey, segName)] = {
+      set: stateKey,
+      cycle: [MENU_CLOSED, segName],
+    };
+  });
+
+  if (stateKeys.size === 0) return;
+
+  const variables: Record<string, VariableDecl> = {};
+  for (const stateKey of stateKeys.keys()) {
+    variables[stateKey] = {
+      kind: "state",
+      key: stateKey,
+      default: MENU_CLOSED,
+    };
+  }
+
+  out.variables = { ...(out.variables ?? {}), ...variables };
+  out.actions = { ...(out.actions ?? {}), ...actions };
+}

package/src/config/menu-keys.ts

@@ -0,0 +1,101 @@
+// [LAW:one-source-of-truth] THE derivation of a menu's accordion identity from
+// layout structure — the single place both the loader (which SYNTHESIZES the
+// state var + cycle action) and the renderer (which READS openness + emits the
+// toggle) agree on "which key holds which open menu". A `{{ menu }}` helper is
+// context-free (it cannot see its own tree position), so its row key and member
+// name are NOT in the helper string — they are derived here from where its host
+// segment sits, and the two consumers MUST derive identical strings or a click
+// would write a key the render never reads. Keeping the rule in one module makes
+// that agreement structural rather than a coincidence of two copies.
+//
+// [LAW:decomposition] "The row IS the key": menus mutually exclude exactly when
+// they share an enclosing horizontal container — so the row key is that
+// container's structural path, and a menu outside any horizontal container gets
+// its own path as a singleton key (it can only toggle itself). The member name a
+// row key holds is the host segment's name.
+
+import type { LayoutNode } from "./dsl-types.js";
+
+// [LAW:one-source-of-truth] The reserved namespace every synthesized menu
+// artifact (state var + cycle action) lives under, mirroring group sugar's
+// `groups.`. A user-authored name under this prefix is a load error so synthesis
+// can never silently collide.
+export const MENU_NS = "menus.";
+
+// The "no menu open" sentinel a row key starts from and returns to on close.
+// A menu's member name is its host segment name; segment names cannot equal this
+// (a row holding "closed" means every menu in it is shut).
+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:types-are-the-program] A row key is a structural path (e.g.
+// `root.children[1]`); collapse it to an identifier-shaped id so the synthesized
+// var/action/SessionState-key names carry no dots or brackets. Distinct tree
+// paths never collide under this map (sibling indices stay distinct: `[1]` vs
+// `[11]` → `_1_` vs `_11_`).
+function menuRowId(rowKey: string): string {
+  return rowKey.replace(/[^A-Za-z0-9]+/g, "_");
+}
+
+// The SessionState key (and the state-var name reading it) for one row's open
+// menu. One key per row holds at most one open member name → accordion.
+export function menuStateKey(rowKey: string): string {
+  return MENU_NS + menuRowId(rowKey);
+}
+
+// The synthesized cycle action a menu's disclosure toggle realizes: writing this
+// row key between MENU_CLOSED and the host segment's name. Named per (row,
+// segment) so two menus sharing a row contribute two cycles on one key — the
+// existing same-key validator merge unions their members into the gate.
+export function menuActionName(rowKey: string, segName: string): string {
+  return MENU_NS + menuRowId(rowKey) + "." + segName;
+}
+
+// [LAW:single-enforcer] THE rule for a segment placement's row key: the nearest
+// enclosing horizontal container's path, or the segment's own path when none.
+// Both the loader walk and the compile walk call this with the values they
+// already track, so neither restates the rule.
+export function rowKeyFor(
+  nearestHorizontalPath: string | undefined,
+  ownPath: string,
+): string {
+  return nearestHorizontalPath ?? ownPath;
+}
+
+// [LAW:single-enforcer] THE one walk that assigns every segment placement its
+// path and row key. The path format (`root` + `.children[i]`) MUST match the
+// compile walk's (`registerDslConfig`'s `compileNode`), since the row key a click
+// targets is keyed by that path; this is the load-side mirror of that walk, so
+// the two produce identical paths over the same tree. `visit` receives the
+// segment name, its row key, and its own path (in case a consumer needs to map
+// by exact placement).
+export function forEachSegmentPlacement(
+  root: LayoutNode,
+  visit: (segName: string, rowKey: string, ownPath: string) => void,
+): void {
+  const recur = (
+    node: LayoutNode,
+    path: string,
+    nearestHorizontalPath: string | undefined,
+  ): void => {
+    if (node.kind === "segment") {
+      visit(node.name, rowKeyFor(nearestHorizontalPath, path), path);
+      return;
+    }
+    // [LAW:dataflow-not-control-flow] A horizontal container REPLACES the nearest-
+    // horizontal path for its subtree; any other container PASSES it through. The
+    // direction is a value selecting which path the children inherit, not a branch
+    // that skips the recursion.
+    const childNearestHorizontal =
+      node.direction === "horizontal" ? path : nearestHorizontalPath;
+    node.children.forEach((child, i) =>
+      recur(child, `${path}.children[${i}]`, childNearestHorizontal),
+    );
+  };
+  recur(root, "root", undefined);
+}

package/src/dsl/node-registry.ts

@@ -23,7 +23,7 @@
 // strip item), not a function of matching backgrounds.
 
 import { RichText } from "@promptctl/rich-js";
-import type { PaletteResolver } from "@promptctl/rich-js";
+import type { PaletteResolver, Style } from "@promptctl/rich-js";
 import type { Template } from "@promptctl/go-template-js";
 import type {
   LayoutNode,
@@ -49,6 +49,12 @@ export interface CompiledSegmentNode {
   readonly kind: "segment";
   readonly when?: Template<RichText>;
   readonly name: string;
+  // [LAW:one-source-of-truth] The menu accordion row key for THIS placement —
+  // the nearest enclosing horizontal container's path, or this segment's own path
+  // (singleton). Computed once at compile from the SAME walk the loader synthesis
+  // uses (menu-keys/forEachSegmentPlacement), so the key a `{{ menu }}` toggle
+  // writes is provably the key the loader declared a state var + gate for.
+  readonly rowKey: string;
 }
 export interface CompiledContainerNode {
   readonly kind: "container";
@@ -88,6 +94,11 @@ export interface NodeCompileCtx {
   readonly path: string;
   // The node's own `when`, already parsed by the driver (one parse-when site).
   readonly when?: Template<RichText>;
+  // [LAW:one-source-of-truth] Path → menu row key, precomputed by the driver from
+  // the SAME structural walk the loader synthesis uses. A segment node reads its
+  // own rowKey here rather than re-deriving the nearest-horizontal rule, so the
+  // two walks cannot drift.
+  readonly rowKeyByPath: ReadonlyMap<string, string>;
   // Compile a child node (the recursion, injected so this module needn't import
   // the driver).
   compileChild(node: LayoutNode, path: string): CompiledNode;
@@ -104,6 +115,15 @@ export interface NodeRenderCtx {
   // Advance the walk-owned hue cursor by one unit and return that unit's shift.
   nextHueShift(): number;
   readonly perSegmentSink?: Map<string, readonly RichText[]>;
+  // [LAW:locality-or-seam] The menu seam, injected as a capability so this module
+  // never imports the menu feature. Called once per segment render, BEFORE its
+  // template evaluates: it publishes this placement (segName + rowKey) so a
+  // `{{ menu }}` in the template can resolve its accordion identity, and returns
+  // the baseStyle to use — lightened when this segment's own menu is open, so the
+  // whole focused segment (inline trigger + dropped body band) reads as
+  // highlighted. The driver owns the menu runtime + state read; this module only
+  // hands it the values it has (name, compiled rowKey, resolved baseStyle).
+  prepareSegment(segName: string, rowKey: string, baseStyle: Style): Style;
   // Resolve a segment name to its decl + compiled form (the driver closes over
   // config.segments + the compiled segments).
   lookupSegment(
@@ -120,9 +140,17 @@ export interface NodeRenderCtx {
 // [LAW:dataflow-not-control-flow] A container's `direction` is the projection it
 // applies to its already-rendered child blocks — DATA selecting a fold, not a
 // branch that skips work. `vertical` STACKS (concatenate the children's line-
-// lists); `horizontal` ZIPS (row i is every child's row-i cells concatenated, so
-// the joiner caps ACROSS the seam — there is no abut). The switch is exhaustive
-// over `Direction`; adding `outline` to DIRECTIONS forces a new arm here.
+// lists). The switch is exhaustive over `Direction`; adding `outline` to
+// DIRECTIONS forces a new arm here.
+//
+// [LAW:decomposition] `horizontal` composes ONLY row 0 across the seam — row 0 is
+// every child's FIRST line zipped (the inline powerline run, so the joiner caps
+// across the seam, no abut). Every line BELOW row 0 is a child's DROP (a menu body
+// dropping below its trigger, a genuinely multi-line segment): drops STACK full-
+// width in child order, never zipped. Multi-line side-by-side column alignment is
+// explicitly UNSUPPORTED — aligning two children's row-i cells would require
+// background-as-structure, and bg is never structural. For an all-single-line row
+// (no child has a drop) this is byte-identical to a plain per-row zip.
 function composeBlocks(
   direction: Direction,
   blocks: readonly RenderedLines[],
@@ -131,12 +159,15 @@ function composeBlocks(
     case "vertical":
       return blocks.flatMap((b) => b);
     case "horizontal": {
+      // [LAW:dataflow-not-control-flow] height 0 (every child hidden/empty) ⇒ the
+      // container contributes NO line — not one empty row. This is the value-driven
+      // identity of the fold, preserved from the per-row zip it replaces; a stray
+      // [[]] here would render as a spurious blank line.
       const height = blocks.reduce((m, b) => Math.max(m, b.length), 0);
-      const rows: RichText[][] = [];
-      for (let i = 0; i < height; i++) {
-        rows.push(blocks.flatMap((b) => b[i] ?? []));
-      }
-      return rows;
+      if (height === 0) return [];
+      const row0 = blocks.flatMap((b) => b[0] ?? []);
+      const drops = blocks.flatMap((b) => b.slice(1));
+      return [row0, ...drops];
     }
   }
 }
@@ -185,7 +216,15 @@ const containerType: NodeType<"container"> = {
 
 const segmentType: NodeType<"segment"> = {
   compile(node, cctx) {
-    return { kind: "segment", when: cctx.when, name: node.name };
+    return {
+      kind: "segment",
+      when: cctx.when,
+      name: node.name,
+      // [LAW:no-defensive-null-guards] Every segment path is visited by the
+      // driver's placement walk, so the map has it; the `?? path` is the singleton
+      // degenerate (a segment outside any horizontal container is its own row).
+      rowKey: cctx.rowKeyByPath.get(cctx.path) ?? cctx.path,
+    };
   },
   render(node, ctx) {
     const found = ctx.lookupSegment(node.name);
@@ -222,12 +261,21 @@ const segmentType: NodeType<"segment"> = {
         segCompiled.paletteResolver ?? ctx.basePalette,
         hueShift,
       );
-      const baseStyle = resolveSegmentColors(
+      const resolvedStyle = resolveSegmentColors(
         resolver,
         segCompiled.bg,
         segCompiled.fg,
         ctx.scope,
       );
+      // [LAW:single-enforcer] Publish this placement to the menu seam and adopt
+      // its baseStyle (focus-lightened iff this segment's menu is open) BEFORE
+      // evaluating the template — a `{{ menu }}` inside reads the placement, and
+      // the (possibly tinted) baseStyle flows into every cell + the line fill.
+      const baseStyle = ctx.prepareSegment(
+        node.name,
+        node.rowKey,
+        resolvedStyle,
+      );
 
       const fragments = segCompiled.template.evaluate(ctx.scope);
       const segCells = fragmentsToCells(fragments, baseStyle);

package/src/dsl/render.ts

@@ -12,6 +12,7 @@
 // govern output, not whether operations run.
 
 import type { RichText, PaletteResolver } from "@promptctl/rich-js";
+import { ColorSpec, Style, lighten } from "@promptctl/rich-js";
 import type { Engine, Template } from "@promptctl/go-template-js";
 import type {
   ValidatedConfig,
@@ -38,9 +39,12 @@ import {
 import {
   compileActions,
   actionFuncs,
+  readVar,
   type ActionRuntime,
 } from "../render/action.js";
 import { pickerFuncs } from "../render/picker.js";
+import { menuFuncs, type MenuRuntime } from "../render/menu.js";
+import { forEachSegmentPlacement, menuStateKey } from "../config/menu-keys.js";
 // [LAW:one-way-deps] The node-type registry sits below this driver: it owns the
 // compiled node shapes + each kind's compile/render, dispatched via nodeType().
 // render.ts threads the recursion (compileChild/renderChild) + the hue counter in
@@ -66,6 +70,13 @@ import {
 export interface CompiledConfig {
   readonly segments: CompiledSegments;
   readonly root: CompiledNode;
+  // [LAW:locality-or-seam] The menu runtime the engine's `menu` func closes over,
+  // surfaced here so renderDsl can publish each segment's placement into it before
+  // that segment's template evaluates. One instance per compiled config; its
+  // `current` is mutated synchronously within a single renderDsl walk (renders are
+  // sequential + synchronous, so no cross-render leak) — the spatial cousin of the
+  // hue cursor, one owner. [LAW:no-ambient-temporal-coupling]
+  readonly menuRuntime: MenuRuntime;
   // [LAW:types-are-the-program] Variable declaration failures that did NOT
   // prevent the config from loading (type mismatches, bad defaults). The
   // affected variables are absent from the store; segments that reference them
@@ -276,11 +287,17 @@ export function registerDslConfig(
   // [LAW:single-enforcer] Forward the caller's clock (the daemon's `() => new
   // Date()`, a test's frozen clock) to the one engine. Omitted ⇒ undefined ⇒
   // createCcCandybarEngine applies its single default; no second default literal.
+  // [LAW:locality-or-seam] The menu runtime shares the action runtime (a menu's
+  // glyph + body resolve from the same compiled table + store) and carries the
+  // walk-published current placement. Built before the engine so the `menu` func
+  // can close over it; `current` stays null until a render walk publishes one.
+  const menuRuntime: MenuRuntime = { action: actionRuntime, current: null };
   const engine = createCcCandybarEngine(
     undefined,
     {
       ...actionFuncs(actionRuntime),
       ...pickerFuncs(actionRuntime),
+      ...menuFuncs(menuRuntime),
     },
     opts?.clock,
   );
@@ -406,6 +423,14 @@ export function registerDslConfig(
       );
     }
   };
+  // [LAW:one-source-of-truth] Precompute every segment placement's menu row key
+  // from the SAME walk the loader synthesis used, so the compiled segment node's
+  // rowKey is provably the key the loader declared a state var + gate for. Each
+  // segment node reads its own entry by path in compile.
+  const rowKeyByPath = new Map<string, string>();
+  forEachSegmentPlacement(config.root, (_segName, rowKey, ownPath) => {
+    rowKeyByPath.set(ownPath, rowKey);
+  });
   const compileNode = (node: LayoutNode, path: string): CompiledNode => {
     const cctx: NodeCompileCtx = {
       path,
@@ -413,6 +438,7 @@ export function registerDslConfig(
         node.when === undefined
           ? undefined
           : parseNodeField(node.when, path, "when"),
+      rowKeyByPath,
       compileChild: compileNode,
     };
     return nodeType(node.kind).compile(node, cctx);
@@ -421,10 +447,27 @@ export function registerDslConfig(
   return {
     segments: compiled,
     root: compileNode(config.root, "root"),
+    menuRuntime,
     loadWarnings,
   };
 }
 
+// [LAW:dataflow-not-control-flow] The focus tint: when a segment's own menu is
+// open it is "focused", so its base background is lightened (rich-js owns the
+// math — see [[rich-js-owns-color-math]]). The transform is RELATIVE to the
+// resolved background, so any host theme tints to a consistent step above its own
+// surface; a segment with no background (transparent) has nothing to lighten and
+// passes through unchanged. One level ≈ 10% lightness — a subtle "this is active".
+const MENU_FOCUS_LIGHTEN_LEVELS = 1;
+function focusTint(style: Style): Style {
+  const bg = style.bgcolor;
+  if (bg === undefined) return style;
+  const lit = ColorSpec.fromRgba(
+    lighten(bg.getTruecolor(), MENU_FOCUS_LIGHTEN_LEVELS),
+  );
+  return new Style({ bgcolor: lit, color: style.color });
+}
+
 // ─── renderDsl ───────────────────────────────────────────────────────────────
 
 /**
@@ -525,6 +568,23 @@ export function renderDsl(
       : undefined;
   };
 
+  // [LAW:single-enforcer] The menu seam, owned here: publish the placement the
+  // about-to-evaluate segment template needs (so a `{{ menu }}` resolves its
+  // accordion identity) and, when this segment's own menu is open, focus-tint its
+  // baseStyle so the whole segment (inline trigger + dropped body band) reads as
+  // highlighted. [LAW:no-defensive-null-guards] "menu never opened" is a real
+  // state — has() discriminates an unset key (no menu in this row) from a value.
+  const prepareSegment = (
+    segName: string,
+    rowKey: string,
+    baseStyle: Style,
+  ): Style => {
+    compiled.menuRuntime.current = { rowKey, segName };
+    const stateKey = menuStateKey(rowKey);
+    const open = store.has(stateKey) && readVar(store, stateKey) === segName;
+    return open ? focusTint(baseStyle) : baseStyle;
+  };
+
   // [LAW:dataflow-not-control-flow] ONE walk renders any node to LINES OF CELLS
   // (serialization deferred to the root). The driver owns the cross-cutting
   // `when`: `visible` ANDs the node's own predicate with its ancestors'. It then
@@ -542,6 +602,7 @@ export function renderDsl(
       visible,
       nextHueShift,
       perSegmentSink,
+      prepareSegment,
       lookupSegment,
       renderChild: renderNode,
     };