@promptctl/cc-candybar 1.39.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/daemon/render-payload.ts

@@ -20,7 +20,20 @@ import path from "node:path";
 import os from "node:os";
 import type { ClaudeHookData } from "../utils/claude.js";
 import type { ClientHints } from "./protocol.js";
-import type { DslConfig, VariableDecl } from "../config/dsl-types.js";
+import type { DslConfig, Globals, VariableDecl } from "../config/dsl-types.js";
+import { effectivePresetName, presetGlobals } from "../config/presets.js";
+import { EDIT_MODE_KEY, EDIT_MODE_OPEN } from "../config/loader/edit-mode.js";
+import {
+  DEFAULT_CHARSET,
+  DEFAULT_COLOR_COMPATIBILITY,
+} from "../render/strip.js";
+import {
+  effectiveAutoWrap,
+  effectiveLookName,
+  effectivePadding,
+  effectiveStripStyle,
+  effectiveThemeName,
+} from "../themes/policy.js";
 import { walkNodes } from "../config/dsl-types.js";
 import { extractTemplateRefs } from "../config/dsl-loader.js";
 import type { GitInfo, GitInfoOptions } from "../segments/git.js";
@@ -75,12 +88,96 @@ export interface EffectiveGlobals {
   // own comment.
   readonly presetCustomized: boolean;
   readonly style: StripStyle;
+  // [LAW:one-source-of-truth] The cell separator `plain` renders between
+  // segments (globals.default_separator). `string | undefined`, not a resolved
+  // string, precisely because its floor is NOT ours: PlainJoiner owns " | " and
+  // pickJoiner already reads undefined as "use the class default", so naming a
+  // floor here would be a second copy of a constant that lives in rich-js.
+  // Like charset it has no SessionState half — the config global (as staged by
+  // whatever fragment is on top) is its whole resolution.
+  readonly separator: string | undefined;
   readonly charset: Charset;
   readonly colorCompatibility: ColorCompatibility;
   readonly autoWrap: boolean;
   readonly padding: number;
 }
 
+// [LAW:one-source-of-truth] THE resolution — one function, so the precedence
+// chain has one implementation rather than one per caller. It previously stood
+// as two structurally identical struct literals (the daemon's, in server.ts,
+// and `cc-candybar check`'s), which is two clocks: the check command's job is
+// to render what the daemon would render, and a rung added to one copy is a
+// rung silently missing from the other. The callers differ only in WHERE a
+// session value comes from and whether an overrides log exists to be customized
+// by, so both arrive as parameters and nothing else forks
+// [LAW:dataflow-not-control-flow].
+//
+// `sessionPick` is the reader for one SessionState key. `check` passes a
+// function returning null for every key — a fresh session that has never
+// clicked — rather than a null store, so "no session" travels as a VALUE
+// through the same chain a real session travels [LAW:no-mode-explosion].
+export function resolveEffectiveGlobals(
+  config: DslConfig,
+  sessionPick: (key: string) => string | null,
+  presetCustomized: (preset: string) => boolean,
+): EffectiveGlobals {
+  // The preset resolves FIRST: every field below reads globals, and which
+  // globals is exactly what the preset decides.
+  const preset = effectivePresetName(
+    sessionPick("preset"),
+    config.globals.preset,
+    config.presets,
+  );
+  const globals = presetGlobals(config, preset);
+  // [LAW:dataflow-not-control-flow] The staged fragment is a VALUE, and "edit
+  // mode is off" is the EMPTY value — the identity fragment, exactly as
+  // PRESET_FLOOR's is. Every field below is resolved by the same expression
+  // whether or not edit mode is on; only the contents of `staged` differ. This
+  // is the whole of "no render-walk branch on edit mode": there is no branch
+  // here either, so there is none to leak downstream.
+  const staged: Partial<Globals> =
+    sessionPick(EDIT_MODE_KEY) === EDIT_MODE_OPEN ? config.editGlobals : {};
+  return {
+    preset,
+    presetCustomized: presetCustomized(preset),
+    theme: effectiveThemeName(
+      staged.palette,
+      sessionPick("theme"),
+      globals.palette,
+    ),
+    look: effectiveLookName(
+      staged.look,
+      sessionPick("look"),
+      globals.look,
+      config.looks,
+    ),
+    style: effectiveStripStyle(
+      staged.style,
+      sessionPick("style"),
+      globals.style,
+    ),
+    // [LAW:one-source-of-truth] The fields with no SessionState half resolve as
+    // `staged ?? config ?? floor` — the same chain minus the rung they do not
+    // have, spelled with the same `??` rather than a second mechanism.
+    separator: staged.default_separator ?? globals.default_separator,
+    autoWrap: effectiveAutoWrap(
+      staged.autoWrap,
+      sessionPick("autoWrap"),
+      globals.autoWrap,
+    ),
+    padding: effectivePadding(
+      staged.padding,
+      sessionPick("padding"),
+      globals.padding,
+    ),
+    charset: staged.charset ?? globals.charset ?? DEFAULT_CHARSET,
+    colorCompatibility:
+      staged.colorCompatibility ??
+      globals.colorCompatibility ??
+      DEFAULT_COLOR_COMPATIBILITY,
+  };
+}
+
 // ─── Augmented payload shape ─────────────────────────────────────────────────
 
 // [LAW:types-are-the-program] The RenderPayload extends ClaudeHookData with

package/src/daemon/server.ts

@@ -63,20 +63,8 @@ import { buildDebugSnapshot } from "./debug";
 import { DEBUG_WHATS, isDebugWhat } from "./debug-types";
 import { expandHome } from "../config/dsl-loader.js";
 import { renderDsl } from "../dsl/render.js";
-import {
-  effectiveStripStyle,
-  effectiveAutoWrap,
-  effectivePadding,
-  effectiveThemeName,
-  effectiveLookName,
-  lookKeyByName,
-  paletteForThemeName,
-} from "../themes/index.js";
-import {
-  effectivePresetName,
-  presetGlobals,
-  presetIsCustomized,
-} from "../config/presets.js";
+import { lookKeyByName, paletteForThemeName } from "../themes/index.js";
+import { presetIsCustomized } from "../config/presets.js";
 import {
   renderStripCells,
   DEFAULT_CHARSET,
@@ -90,7 +78,11 @@ import {
 } from "../render/strip.js";
 import { applyClaudeCodeReserve } from "../utils/terminal-width.js";
 import type { RichText } from "@promptctl/rich-js";
-import { buildRenderPayload, type EffectiveGlobals } from "./render-payload.js";
+import {
+  buildRenderPayload,
+  resolveEffectiveGlobals,
+  type EffectiveGlobals,
+} from "./render-payload.js";
 import { ContextProvider } from "../segments/context.js";
 import { MetricsProvider } from "../segments/metrics.js";
 import { TmuxService } from "../segments/tmux.js";
@@ -860,83 +852,28 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
       // No special-case branches — same composition every render.
       let body = "";
       if (entry.state !== null) {
-        // [LAW:one-source-of-truth] Resolve the effective theme ONCE — the
-        // session's chosen theme (SessionState) over the config default. This
-        // single name drives BOTH the payload's `theme.effective` field (the
-        // trigger label reads it) AND the rendered basePalette below, so a label
-        // and the colors can never disagree. Resolved here, before the payload
-        // build, so it can be threaded into the sole payload assembler.
-        //
-        // [LAW:one-source-of-truth] Every globals field a menu/stepper can
-        // persist (candybar-config-engine-71o.3), resolved ONCE into one
-        // struct: theme/look/style/autoWrap/padding compose the session's click
-        // (SessionState) over the config default over a floor — a click
-        // recolors/reshapes the whole bar on the next render; charset and
-        // colorCompatibility describe the TERMINAL rather than a taste and so
-        // have no SessionState half at all, making the config global over its
-        // floor constant their whole resolution. This struct feeds
-        // BOTH the payload's `*.effective` fields (trigger labels) AND
-        // renderOpts below (the actual render) — one resolution, two readers,
-        // so a label can never disagree with what was rendered.
-        //
-        // [LAW:one-source-of-truth] The PRESET resolves FIRST, because every
-        // other field below reads globals — and which globals is exactly what
-        // the preset decides. `presetGlobals` is the config's globals with the
-        // active fragment's shallow-merged over them, so the preset sits at its
-        // one documented place in the precedence chain (bundled default < user
-        // file < persisted overrides < ACTIVE PRESET < session pick — see
-        // src/config/presets.ts and docs/interaction-authoring.md): later than
-        // everything read per cache ENTRY, earlier than every session click,
-        // which is the order the `??` chains below already enforce by reading
-        // SessionState first. There is no "does a preset apply?" branch — the
-        // floor preset's empty fragment merges as a no-op
-        // [LAW:dataflow-not-control-flow].
-        const preset = effectivePresetName(
-          sessionState.get(req.hookData.session_id, "preset"),
-          entry.state.config.globals.preset,
-          entry.state.config.presets,
-        );
-        const globals = presetGlobals(entry.state.config, preset);
-        const effective: EffectiveGlobals = {
-          preset,
+        // [LAW:one-source-of-truth] Every globals field resolved ONCE per
+        // render, here — before the payload build, so the same struct feeds
+        // BOTH the payload's `*.effective` fields (what a trigger label says)
+        // AND renderOpts below (what actually renders). One resolution, two
+        // readers, so a label can never disagree with the bar. The precedence
+        // the resolver applies, and why each rung sits where it does, lives
+        // with the chain (resolveEffectiveGlobals, and src/config/presets.ts).
+        // Read alongside the config, from the same entry, in one statement —
+        // which is exactly what the closure below claims about it.
+        const presetRootOps = entry.state.presetRootOps;
+        const effective: EffectiveGlobals = resolveEffectiveGlobals(
+          entry.state.config,
+          (key: string) => sessionState.get(req.hookData.session_id, key),
           // [LAW:one-source-of-truth] brandon-layout-edit-2gc.5 — read from
           // THIS entry's own presetRootOps (the record that fed the SAME
           // reload that produced entry.state.config), never a fresh
           // loadOverrides() here — a second read could race a concurrent
-          // write and disagree with the tree that actually rendered.
-          presetCustomized: presetIsCustomized(
-            entry.state.presetRootOps,
-            preset,
-          ),
-          theme: effectiveThemeName(
-            sessionState.get(req.hookData.session_id, "theme"),
-            globals.palette,
-          ),
-          look: effectiveLookName(
-            sessionState.get(req.hookData.session_id, "look"),
-            globals.look,
-            entry.state.config.looks,
-          ),
-          style: effectiveStripStyle(
-            sessionState.get(req.hookData.session_id, "style"),
-            globals.style,
-          ),
-          autoWrap: effectiveAutoWrap(
-            sessionState.get(req.hookData.session_id, "autoWrap"),
-            globals.autoWrap,
-          ),
-          padding: effectivePadding(
-            sessionState.get(req.hookData.session_id, "padding"),
-            globals.padding,
-          ),
-          // charset and colorCompatibility have no session half by design —
-          // they describe the terminal, not a taste (see CHARSETS in
-          // themes/policy.ts) — so the config global over its floor is their
-          // whole resolution.
-          charset: globals.charset ?? DEFAULT_CHARSET,
-          colorCompatibility:
-            globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,
-        };
+          // write and disagree with the tree that actually rendered. That is
+          // why it arrives as a closure over this entry rather than being
+          // looked up inside the resolver.
+          (preset: string) => presetIsCustomized(presetRootOps, preset),
+        );
         const payload = await buildRenderPayload(
           req.hookData,
           payloadDeps,
@@ -956,6 +893,10 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
         // SAME `effective` struct the payload was just built from — no second
         // `?? DEFAULT_X` computation to drift from it.
         renderOpts.style = effective.style;
+        // The `plain` joiner's cell separator. Assigned unconditionally like
+        // every field around it: `undefined` is a value pickJoiner already
+        // reads as "PlainJoiner's own default", not an absence to branch on.
+        renderOpts.separator = effective.separator;
         renderOpts.wrap = effective.autoWrap;
         renderOpts.padding = effective.padding;
         renderOpts.charset = effective.charset;

package/src/demo/dsl.ts

@@ -30,21 +30,10 @@ import { VariableStore } from "../var-system/store.js";
 import { SourceRegistry } from "../var-system/sources.js";
 import { SessionState } from "../daemon/session-state.js";
 import { listResolvablePaletteNames } from "../themes/policy.js";
-import {
-  effectiveThemeName,
-  effectiveLookName,
-  effectiveAutoWrap,
-  effectivePadding,
-  lookKeyByName,
-  paletteForThemeName,
-} from "../themes/index.js";
-import { effectivePresetName, presetGlobals } from "../config/presets.js";
+import { lookKeyByName, paletteForThemeName } from "../themes/index.js";
+import { resolveEffectiveGlobals } from "../daemon/render-payload.js";
 import { registerDslConfig, renderDsl } from "../dsl/render.js";
-import {
-  DEFAULT_CHARSET,
-  DEFAULT_COLOR_COMPATIBILITY,
-  DEFAULT_TERMINAL_WIDTH,
-} from "../render/strip.js";
+import { DEFAULT_TERMINAL_WIDTH } from "../render/strip.js";
 import { applyClaudeCodeReserve } from "../utils/terminal-width.js";
 
 const FRAMES = 4;
@@ -83,18 +72,18 @@ const payload = {
 // globals every other option reads — the same preset-first order server.ts and
 // check.ts resolve in, so the demo prints the arrangement a fresh session opens
 // in.
-const preset = effectivePresetName(null, config.globals.preset, config.presets);
-const globals = presetGlobals(config, preset);
-const basePalette = paletteForThemeName(
-  effectiveThemeName(null, globals.palette),
-);
-// Same fresh-session resolution one dimension over: the config-default look
-// over the "none" identity floor — the exact mirror of the daemon's per-render
-// effectiveLookName → lookKeyByName chain.
-const lookKey = lookKeyByName(
-  config.looks,
-  effectiveLookName(null, globals.look, config.looks),
+// [LAW:one-source-of-truth] THE daemon's resolver, not a mirror of it — a
+// fresh-session pick reader (null for every key) and no overrides log to be
+// customized by. The demo previously restated this chain field by field and had
+// already drifted: it hardcoded `style: "powerline"` below and so ignored a
+// config's own `globals.style`.
+const effective = resolveEffectiveGlobals(
+  config,
+  () => null,
+  () => false,
 );
+const basePalette = paletteForThemeName(effective.theme);
+const lookKey = lookKeyByName(config.looks, effective.look);
 
 // A fresh store + registry for this run. (A hot-reloading daemon would
 // dispose() the old pair and build new ones — see registerDslConfig's docs.)
@@ -128,26 +117,21 @@ try {
       payload,
       basePalette,
       {
-        style: "powerline",
-        // Same resolution the daemon applies: the config global over the
-        // truecolor default floor.
-        colorCompatibility:
-          globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,
+        style: effective.style,
+        separator: effective.separator,
+        colorCompatibility: effective.colorCompatibility,
         // [LAW:one-source-of-truth] Demo applies the same Claude-Code-UI
         // reserve the daemon does so demo output matches the bytes a real
         // statusline would emit at the same terminal width.
         width: applyClaudeCodeReserve(
           process.stdout.columns ?? DEFAULT_TERMINAL_WIDTH,
         ),
-        // Same resolvers the daemon applies, with a null session pick — the
-        // demo has no SessionState, so both land on the config default over
-        // their floor.
-        wrap: effectiveAutoWrap(null, globals.autoWrap),
-        padding: effectivePadding(null, globals.padding),
-        charset: globals.charset ?? DEFAULT_CHARSET,
+        wrap: effective.autoWrap,
+        padding: effective.padding,
+        charset: effective.charset,
       },
       undefined,
-      { look: lookKey, preset },
+      { look: lookKey, preset: effective.preset },
     );
     process.stdout.write(`  ${line}\n`);
     if (frame < FRAMES - 1) await sleep(FRAME_INTERVAL_MS);

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