@promptctl/cc-candybar 1.40.0 → 1.41.0

package/src/config/settings-menu.ts

@@ -49,8 +49,13 @@ import {
   DISCLOSURE_GLYPH_CLOSED,
   DISCLOSURE_GLYPH_OPEN,
   disclosureCycleAction,
+  disclosureGate,
   disclosureStateVar,
+  disclosureTrigger,
+  type DisclosureRef,
 } from "./disclosure.js";
+import { declareHelp, type HelpDisclosure } from "./help.js";
+import { PERSIST_HELP } from "../help-text.js";
 import {
   EDIT_MODE_KEY,
   EDIT_MODE_OPEN,
@@ -127,11 +132,34 @@ const CONFIG_SEG = `${SETTINGS_NS}config`;
 // cannot silently write a durable default today — SessionState is per session.
 const PERSIST_KEY = PERSIST_SEG;
 
-// [LAW:one-source-of-truth] The config menu's own disclosure, spelled the same
-// way the anchor above is: ONE name that is the segment, the state variable and
-// the cycle action, so its toggle's click and its body's `when` cannot address
-// different keys.
-const CONFIG_OPEN_GATE = `{{ and (eq .${SETTINGS_ANCHOR} "${SETTINGS_OPEN}") (eq .${CONFIG_SEG} "${SETTINGS_OPEN}") }}`;
+// [LAW:one-source-of-truth] The two disclosures this menu IS, as refs rather
+// than as gate strings: every gate below — and every `(?)` nested inside them —
+// derives from these, so the toggle that writes a key and the `when` that reads
+// it cannot name different variables.
+const SETTINGS_REF: DisclosureRef = {
+  variable: SETTINGS_ANCHOR,
+  member: SETTINGS_OPEN,
+};
+const CONFIG_REF: DisclosureRef = {
+  variable: CONFIG_SEG,
+  member: SETTINGS_OPEN,
+};
+
+// Gated on BOTH keys — a config row left open yesterday must not render beside
+// a closed menu today. Nesting is conjunction, which is why it is one list.
+const CONFIG_OPEN_GATE = disclosureGate(SETTINGS_REF, CONFIG_REF);
+
+// The `(?)` that explains `persist?` — the one control in this menu whose
+// behaviour a user cannot infer from its label, which is exactly why the ticket
+// named it as a required use site. Its body says what the NEXT click does, in
+// the same two sentences `--help` prints.
+const PERSIST_HELP_SEG = `${SETTINGS_NS}help.persist`;
+
+// [LAW:one-source-of-truth] The panel's surface colours, spelled once. The help
+// cells must wear the same ones as the controls they explain — a `(?)` body in
+// a different colour reads as a different panel — and that agreement is only
+// guaranteed if there is one value to hand both.
+const SETTINGS_SURFACE = { bg: "surface", fg: "foreground" } as const;
 
 // [LAW:one-source-of-truth] One accordion key for every picker in the menu:
 // one key holds one open member, so opening a theme picker closes the look
@@ -278,7 +306,7 @@ const controlReset = (name: string): string => `${SETTINGS_NS}reset.${name}`;
 // from the same anchor string the toggle's cycle writes — spelled once here,
 // exactly as lowerGroup derives a group body's `when` from the group's own
 // reference name.
-const SETTINGS_OPEN_GATE = `{{ eq .${SETTINGS_ANCHOR} "${SETTINGS_OPEN}" }}`;
+const SETTINGS_OPEN_GATE = disclosureGate(SETTINGS_REF);
 
 // [LAW:single-enforcer] The one answer to "is this segment reference the global
 // menu's anchor". cross-ref.ts asks it to accept an authored placement of a name
@@ -379,7 +407,10 @@ export function countAnchors(node: LayoutNode): number {
 // a vertical pair of the toggle segment and a `when`-gated body. Replaces the
 // anchor leaf wherever it sits, so the author's chosen position is the menu's
 // position with nothing else moved.
-function expandAnchor(node: AnchoredRoot | LayoutNode): LayoutNode {
+function expandAnchor(
+  node: AnchoredRoot | LayoutNode,
+  help: HelpDisclosure,
+): LayoutNode {
   if (node.kind === "segment") {
     return isSettingsAnchor(node.name)
       ? {
@@ -395,6 +426,32 @@ function expandAnchor(node: AnchoredRoot | LayoutNode): LayoutNode {
               direction: "horizontal",
               children: [
                 { kind: "segment", name: PERSIST_SEG },
+                // The `(?)` rides the row that already exists, immediately
+                // after the control it explains — so closed help costs no row
+                // and widens the bar by one cell, and open help reads as an
+                // answer to the checkbox on its left.
+                //
+                // Mid-row, DELIBERATELY, unlike edit mode's `(?)`, which
+                // edit-chrome.ts goes to lengths to trail. The difference is
+                // structural, not a discipline applied in one file and skipped
+                // here. `nextHueShift` (src/dsl/render.ts:697) counts segment
+                // leaves in pre-order, so a leaf's hue index is the number of
+                // leaves before it — which makes the consequence arithmetic:
+                // reordering leaves WITHIN a subtree cannot change the index of
+                // any leaf AFTER it, since the subtree's leaf count does not
+                // move. Edit chrome WRAPS the whole tree, so trailing there is
+                // after every existing leaf and costs zero. This menu splices
+                // MID-TREE at an anchor `withAnchor` lets the author put
+                // anywhere, so no position inside it is after the rest of the
+                // bar: the leaves it adds — this trigger plus one per
+                // PERSIST_HELP line, a count that lives in help-text.ts and is
+                // deliberately not copied here — shift everything past the
+                // anchor wherever inside the menu they sit. Trailing would cost
+                // the adjacency that IS the affordance. The fix is decoupling
+                // colour from tree position — candybar-render-y5h, which fixes
+                // every mid-tree synthesis at once rather than one file at a
+                // time.
+                help.trigger,
                 ...PRIMARY_CONTROLS.map(
                   (c): LayoutNode => ({
                     kind: "segment",
@@ -406,6 +463,9 @@ function expandAnchor(node: AnchoredRoot | LayoutNode): LayoutNode {
               ],
               when: SETTINGS_OPEN_GATE,
             },
+            // The help body: one row, present only while the `(?)` is open,
+            // directly under the row that asked the question.
+            help.body,
             // Row two: the display settings, behind their own disclosure so
             // the menu opens narrow. Gated on BOTH keys — a config row left
             // open yesterday must not render beside a closed menu today; one
@@ -429,7 +489,10 @@ function expandAnchor(node: AnchoredRoot | LayoutNode): LayoutNode {
         }
       : node;
   }
-  return { ...node, children: node.children.map(expandAnchor) };
+  return {
+    ...node,
+    children: node.children.map((child) => expandAnchor(child, help)),
+  };
 }
 
 // ─── The artifacts ──────────────────────────────────────────────────────────
@@ -476,7 +539,10 @@ function declareHostedMenu(
 // reference, and a second reference to one declaration is a reuse, not the
 // self-collision a second `kind: "group"` node would be (see the settingsDrawer
 // comment in default-dsl-config.ts for that hazard in its original form).
-function settingsArtifacts(): MenuArtifacts {
+function settingsArtifacts(): {
+  artifacts: MenuArtifacts;
+  help: HelpDisclosure;
+} {
   const artifacts: MenuArtifacts = {
     variables: {
       [SETTINGS_ANCHOR]: disclosureStateVar(SETTINGS_ANCHOR, DISCLOSURE_CLOSED),
@@ -497,22 +563,27 @@ function settingsArtifacts(): MenuArtifacts {
       // [LAW:representation] The glyph trails the label it gates, per the
       // disclosure vocabulary every other toggle in the bar reads by.
       [SETTINGS_ANCHOR]: {
-        template: `{{ action "${SETTINGS_ANCHOR}" "☰ ${DISCLOSURE_GLYPH_CLOSED}" "☰ ${DISCLOSURE_GLYPH_OPEN}" }}`,
-        bg: "surface",
-        fg: "foreground",
+        template: disclosureTrigger(
+          SETTINGS_ANCHOR,
+          `☰ ${DISCLOSURE_GLYPH_CLOSED}`,
+          `☰ ${DISCLOSURE_GLYPH_OPEN}`,
+        ),
+        ...SETTINGS_SURFACE,
       },
       // [LAW:representation] The checkbox states what the NEXT write does,
       // which is why the glyph and the word live together: "☑ persist?" is
       // the whole explanation of where the click below it lands.
       [PERSIST_SEG]: {
         template: `{{ action "${PERSIST_SEG}" "☐ persist?" "☑ persist?" }}`,
-        bg: "surface",
-        fg: "foreground",
+        ...SETTINGS_SURFACE,
       },
       [CONFIG_SEG]: {
-        template: `{{ action "${CONFIG_SEG}" "⚙ config ${DISCLOSURE_GLYPH_CLOSED}" "⚙ config ${DISCLOSURE_GLYPH_OPEN}" }}`,
-        bg: "surface",
-        fg: "foreground",
+        template: disclosureTrigger(
+          CONFIG_SEG,
+          `⚙ config ${DISCLOSURE_GLYPH_CLOSED}`,
+          `⚙ config ${DISCLOSURE_GLYPH_OPEN}`,
+        ),
+        ...SETTINGS_SURFACE,
       },
       // [LAW:one-type-per-behavior] Both non-picker controls read the same
       // `.effective` projection their picker siblings read, and write the
@@ -522,8 +593,7 @@ function settingsArtifacts(): MenuArtifacts {
         template:
           `{{ action "${controlApply("wrap")}" "wrap: on" "wrap: off" }} ` +
           `{{ action "${controlReset("wrap")}" "↺" }}`,
-        bg: "surface",
-        fg: "foreground",
+        ...SETTINGS_SURFACE,
       },
       [PADDING_SEG]: {
         template:
@@ -531,8 +601,7 @@ function settingsArtifacts(): MenuArtifacts {
           "padding {{ .padding.effective }} " +
           `{{ action "${controlApply("padding")}.up" "▶" }} ` +
           `{{ action "${controlReset("padding")}" "↺" }}`,
-        bg: "surface",
-        fg: "foreground",
+        ...SETTINGS_SURFACE,
       },
       // The entry point edit mode never had: `edit.toggle` is a reserved action
       // whose only bundled reference lives in the `toolbar` segment, which a
@@ -540,8 +609,7 @@ function settingsArtifacts(): MenuArtifacts {
       // from a segment no config can drop.
       [EDIT_SEG]: {
         template: `{{ action "${EDIT_TOGGLE_ACTION}" "✎ edit" "✎ done" }}`,
-        bg: "surface",
-        fg: "foreground",
+        ...SETTINGS_SURFACE,
       },
     },
   };
@@ -555,7 +623,19 @@ function settingsArtifacts(): MenuArtifacts {
     DISCLOSURE_CLOSED,
   );
   declareSettingControls(artifacts);
-  return artifacts;
+  // [LAW:one-source-of-truth] The `(?)` is minted here, with the panel it
+  // belongs to, and its two NODES are returned so `expandAnchor` places them by
+  // the value it is handed rather than by re-deriving names this pass already
+  // owns. Nested in SETTINGS_REF, so closing the menu takes the open help with
+  // it.
+  const help = declareHelp(
+    PERSIST_HELP_SEG,
+    PERSIST_HELP,
+    [SETTINGS_REF],
+    artifacts,
+    SETTINGS_SURFACE,
+  );
+  return { artifacts, help };
 }
 
 // [LAW:one-source-of-truth] Every setting the menu offers, minted from the one
@@ -581,8 +661,7 @@ function declareSettingControls(artifacts: MenuArtifacts): void {
         `{{ menu "${apply}" "${DISCLOSURE_GLYPH_CLOSED}" "${DISCLOSURE_GLYPH_OPEN}" ` +
         `(dict "key" "${PICKER_KEY}" "closeOnPick" true) }} ` +
         `{{ action "${controlReset(c.name)}" "↺" }}`,
-      bg: "surface",
-      fg: "foreground",
+      ...SETTINGS_SURFACE,
     };
     artifacts.actions[apply] = {
       set: c.sessionKey,
@@ -676,14 +755,14 @@ export function canHostSessionState(config: DslConfig): boolean {
 // and every name now declares one.
 export function synthesizeSettingsMenu(config: DslConfig): DslConfig {
   if (!canHostSessionState(config)) return config;
-  const artifacts = settingsArtifacts();
+  const { artifacts, help } = settingsArtifacts();
   ensureEditToggle(artifacts);
   const presets: Record<string, PresetDecl> = { ...config.presets };
   for (const name of presetNames(config.presets)) {
     const { node } = presetRoot(config, name);
     presets[name] = {
       ...presetByName(config.presets, name),
-      root: expandAnchor(withAnchor(node)),
+      root: expandAnchor(withAnchor(node), help),
     };
   }
   return {

package/src/help-text.ts

@@ -1,4 +1,5 @@
 import { DISCLOSURE_GLYPH_CLOSED } from "./config/disclosure";
+import { HELP_GLYPH_CLOSED } from "./config/help";
 
 // [LAW:effects-at-boundaries] Pure data, no I/O — index.ts owns the console.log
 // effect. Kept as its own module so the text is importable (and testable) without
@@ -6,6 +7,29 @@ import { DISCLOSURE_GLYPH_CLOSED } from "./config/disclosure";
 // [LAW:one-source-of-truth] The disclosure glyph comes from config/disclosure.ts
 // (the same constant the theme/look picker itself renders with), so this text
 // can't drift from what a user actually sees on the bar.
+// [LAW:one-source-of-truth] THE help corpus, as data. `--help` and the bar's
+// own `(?)` disclosures are two RENDERINGS of these arrays, never two copies of
+// the sentences: a `(?)` segment's template IS one of these strings, and the
+// paragraphs below interpolate the same values. A help sentence typed into a
+// segment template — where nothing would ever notice it drifting from the CLI's
+// wording — is the defect this shape exists to make unrepresentable.
+//
+// [LAW:representation] One line is one CELL on the bar, so each is a complete
+// thought that stands alone and each stays short: `(?)` bodies drop below their
+// row, and a body that overflows `term.cols` wraps into more rows than the fact
+// it explains is worth. Every line leads with the glyph it explains, so the
+// reader matches text to affordance by shape rather than by reading order.
+export const EDIT_MODE_HELP = [
+  "+ inserts here",
+  "- removes the one left of it",
+  "↺ undoes edits",
+] as const;
+
+export const PERSIST_HELP = [
+  "☐ this session only",
+  "☑ default for every session",
+] as const;
+
 export const HELP_TEXT = `
 cc-candybar - Beautiful powerline statusline for Claude Code
 
@@ -27,8 +51,10 @@ Configuration:
   needed, and writing your own \`root\` cannot delete it. Click
   ☰ ${DISCLOSURE_GLYPH_CLOSED} on the bar for preset switching, edit mode, and a config menu
   of clickable theme/look/style/wrap/padding controls. The \`persist?\`
-  checkbox there chooses where a change lands: unchecked it applies to this
-  session only, checked it becomes the default every session opens with.
+  checkbox there chooses where a change lands: ${PERSIST_HELP.join(", ")}.
+
+  Anywhere the bar shows ${HELP_GLYPH_CLOSED}, clicking it reveals these same instructions
+  in place. In edit mode: ${EDIT_MODE_HELP.join(", ")}.
 
 Subcommands:
   install                  One-shot setup: stages the runtime (native render