@promptctl/cc-candybar 1.39.0 → 1.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.39.0",
+  "version": "1.41.0",
   "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",
@@ -91,9 +91,9 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.39.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.39.0",
-    "@promptctl/cc-candybar-linux-x64": "1.39.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.39.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.41.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.41.0",
+    "@promptctl/cc-candybar-linux-x64": "1.41.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.41.0"
   }
 }

package/schema/cc-candybar.schema.json

@@ -1648,7 +1648,7 @@
               },
               "preset": {
                 "not": {},
-                "description": "not allowed inside a preset — a preset cannot select a preset"
+                "description": "not allowed here — a preset cannot select a preset"
               },
               "style": {
                 "enum": [
@@ -1686,6 +1686,66 @@
         "additionalProperties": false
       }
     },
+    "editGlobals": {
+      "type": "object",
+      "properties": {
+        "default_bg": {
+          "type": "string"
+        },
+        "default_fg": {
+          "type": "string"
+        },
+        "default_empty_value": {
+          "type": "string"
+        },
+        "default_separator": {
+          "type": "string"
+        },
+        "default_truncate_marker": {
+          "type": "string"
+        },
+        "palette": {
+          "type": "string"
+        },
+        "look": {
+          "type": "string"
+        },
+        "preset": {
+          "not": {},
+          "description": "not allowed here — the editGlobals fragment cannot select a preset"
+        },
+        "style": {
+          "enum": [
+            "powerline",
+            "capsule",
+            "plain"
+          ]
+        },
+        "autoWrap": {
+          "type": "boolean"
+        },
+        "padding": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 16
+        },
+        "charset": {
+          "enum": [
+            "unicode",
+            "ascii"
+          ]
+        },
+        "colorCompatibility": {
+          "enum": [
+            "truecolor",
+            "256",
+            "ansi",
+            "none"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
     "helpers": {
       "type": "object",
       "additionalProperties": {

package/src/check.ts

@@ -31,21 +31,12 @@ import { SourceRegistry } from "./var-system/sources.js";
 import { SessionState } from "./daemon/session-state.js";
 import { registerDslConfig, renderDsl } from "./dsl/render.js";
 import { deriveActionValidators } from "./daemon/verbs/state-validators.js";
-import {
-  effectiveThemeName,
-  effectiveLookName,
-  lookKeyByName,
-  effectiveStripStyle,
-  effectiveAutoWrap,
-  effectivePadding,
-} from "./themes/policy.js";
+import { lookKeyByName } from "./themes/policy.js";
 import { paletteForThemeName } from "./themes/palette-resolvers.js";
-import { effectivePresetName, presetGlobals } from "./config/presets.js";
 import {
-  DEFAULT_CHARSET,
-  DEFAULT_COLOR_COMPATIBILITY,
-} from "./render/strip.js";
-import type { EffectiveGlobals } from "./daemon/render-payload.js";
+  resolveEffectiveGlobals,
+  type EffectiveGlobals,
+} from "./daemon/render-payload.js";
 
 // [LAW:no-ambient-temporal-coupling] A fixed width keeps the verdict a function
 // of the config alone, not of whichever terminal invoked the check. Templates
@@ -302,14 +293,13 @@ function loadRegisterRender(
     // globals feed every field below, the SAME order the daemon resolves in
     // (server.ts) — so `check` renders the arrangement a fresh session actually
     // opens in, not the config's un-presetted root.
-    const preset = effectivePresetName(
-      null,
-      config.globals.preset,
-      config.presets,
-    );
-    const globals = presetGlobals(config, preset);
-    const effective: EffectiveGlobals = {
-      preset,
+    const effective: EffectiveGlobals = resolveEffectiveGlobals(
+      config,
+      // A fresh session: no clicked theme/style/look, and edit mode off. The
+      // resolution is THE daemon's (resolveEffectiveGlobals), not a copy that
+      // agrees with it today — which is the whole reason check renders what the
+      // daemon would render rather than something adjacent.
+      () => null,
       // [LAW:no-silent-failure] `check` validates a config file in isolation
       // — it never reads the daemon-owned overrides file, so there is no
       // rootOps log to be customized BY. false is the honest value for THIS
@@ -317,16 +307,8 @@ function loadRegisterRender(
       // has never customized anything. A second render pass below also
       // exercises `true`, so a `.preset.customized`-gated segment still
       // gets checked — just not through this value.
-      presetCustomized: false,
-      theme: effectiveThemeName(null, globals.palette),
-      look: effectiveLookName(null, globals.look, config.looks),
-      style: effectiveStripStyle(null, globals.style),
-      autoWrap: effectiveAutoWrap(null, globals.autoWrap),
-      padding: effectivePadding(null, globals.padding),
-      charset: globals.charset ?? DEFAULT_CHARSET,
-      colorCompatibility:
-        globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,
-    };
+      () => false,
+    );
     // [LAW:no-silent-failure] A segment whose template THROWS while evaluating
     // (an `{{ action }}` display-arity mismatch, a MissingFieldError from a
     // partially-declared variable) renders as a visible ⚠ error cell — partial
@@ -352,6 +334,7 @@ function loadRegisterRender(
         paletteForThemeName(payloadEffective.theme),
         {
           style: payloadEffective.style,
+          separator: payloadEffective.separator,
           width: CHECK_WIDTH,
           colorCompatibility: payloadEffective.colorCompatibility,
           wrap: payloadEffective.autoWrap,

package/src/config/default-dsl-config.ts

@@ -1475,6 +1475,24 @@ export const RAW_DEFAULT_DSL_CONFIG = {
     },
   },
 
+  // [LAW:one-source-of-truth] What edit mode LOOKS like, as config a user can
+  // retune — the whole point of candybar-settings-ui-aok.5, whose predecessor
+  // was renderer constants. Powerline chrome exists to make adjacent segments
+  // read as one continuous strip, which is precisely the wrong signal while a
+  // user is trying to see where one segment ends and the next begins; `plain`
+  // trades the caps for a visible separator between every cell.
+  //
+  // The separator is stated rather than left to PlainJoiner's own default: this
+  // fragment layers over the user's globals, so a config that set
+  // `default_separator` for its own powerline bar would otherwise carry that
+  // choice into edit mode, where the separator is the entire affordance. " | "
+  // (not "│") because it must survive `charset: "ascii"` — the fragment does
+  // not, and should not, know the terminal's glyph coverage.
+  editGlobals: {
+    style: "plain",
+    default_separator: " | ",
+  },
+
   // [LAW:single-enforcer] / [LAW:one-source-of-truth] Display-formatting policy
   // for the cost/token/budget family lives here as named template helpers, each
   // DEFINED ONCE and called from every segment via `{{ template "name" .arg }}`

package/src/config/disclosure.ts

@@ -89,6 +89,67 @@ export function pickCycleDisplay(
   return displays.length === 1 ? displays[0]! : displays[index]!;
 }
 
+// [LAW:one-source-of-truth] Go-template string-literal escaping for any DISPLAY
+// text a synthesis splices INSIDE a quoted `{{ }}` argument of a template it
+// emits — a group's label, a preset name in the reset banner, a `(?)` trigger's
+// closed/open glyphs. NOT for a template's own body text, which is source rather
+// than a splice: a help line is assigned verbatim (help.ts) because escaping one
+// would put a backslash on the bar. It lives here, beside the two splices
+// that need it most, because it was already two verbatim copies (loader/layout.ts
+// and edit-chrome.ts, whose comment deferred the merge until "one small rule"
+// earned its own home). The `(?)` affordance was the third caller, so it did.
+export function escapeTemplateLiteral(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+// [LAW:types-are-the-program] One open disclosure, named by the two strings that
+// decide it: the VARIABLE a body reads and the MEMBER value that means "this one
+// is open". They are distinct because a group's variable is per-group
+// (`groups.<name>`) while its state KEY may be shared with accordion siblings —
+// so the pair, never a lone key, is what identifies an open state.
+export interface DisclosureRef {
+  readonly variable: string;
+  readonly member: string;
+}
+
+// [LAW:single-enforcer] THE body predicate a disclosure implies. Variadic
+// because nesting is conjunction and nothing else: a row inside two disclosures
+// is open when both are, which is one list, not a compound spelling. Callers
+// that used to hand-write `{{ eq .x "open" }}` beside `{{ and (eq .x "open")
+// (eq .y "open") }}` now pass one ref or two to one function — the shape stops
+// varying with the depth [LAW:dataflow-not-control-flow].
+//
+// `and` is variadic in Go templates and returns its sole argument when given
+// one, so the single-disclosure case needs no separate spelling.
+//
+// [LAW:types-are-the-program] The first ref is a separate parameter so a gate
+// over ZERO disclosures — which would emit an argument-less `{{ and }}` and gate
+// on nothing — is unrepresentable, with no runtime guard to state it.
+export function disclosureGate(
+  first: DisclosureRef,
+  ...rest: readonly DisclosureRef[]
+): string {
+  const terms = [first, ...rest]
+    .map((o) => `(eq .${o.variable} "${escapeTemplateLiteral(o.member)}")`)
+    .join(" ");
+  return `{{ and ${terms} }}`;
+}
+
+// [LAW:single-enforcer] THE trigger template a disclosure's toggle segment
+// carries: one `{{ action }}` over the cycle action, binding the author's text
+// per state — closed first, matching the cycle's own closed-first member order
+// so the display index and the member index are the same number. Since .4 every
+// trigger authors its own text (the runtime appends no glyph), which makes this
+// the one place the binding is spelled; before it, five sites spelled it and the
+// `+▸` double-glyph bug lived in the gap between two of them.
+export function disclosureTrigger(
+  action: string,
+  closed: string,
+  open: string,
+): string {
+  return `{{ action "${action}" "${escapeTemplateLiteral(closed)}" "${escapeTemplateLiteral(open)}" }}`;
+}
+
 // [LAW:single-enforcer] THE backing `state` variable a disclosure key implies:
 // it holds the open member's name and defaults to `def` (the CLOSED sentinel for
 // an independent disclosure, or an initially-open member for a group's

package/src/config/dsl-loader.ts

@@ -43,7 +43,7 @@ import {
   type ValidateCtx,
 } from "./loader/validate-core.js";
 import { mergeWithDefault } from "./loader/merge.js";
-import { validateGlobals } from "./loader/globals.js";
+import { validateEditGlobals, validateGlobals } from "./loader/globals.js";
 import { validateVariables } from "./loader/variables.js";
 import { validateSegments } from "./loader/segments.js";
 import { synthesizeGroupDecls, validateRoot } from "./loader/layout.js";
@@ -280,6 +280,12 @@ function validateTopLevel(
   // was staged from.
   if (raw.presets !== undefined)
     out.presets = validatePresets(ctx, raw.presets);
+  // [LAW:one-type-per-behavior] Edit mode's staged display globals — the same
+  // fragment shape a preset carries, one rung later in the precedence chain, so
+  // it runs through the same field table (validateEditGlobals) rather than a
+  // parallel schema listing which globals edit mode may set.
+  if (raw.editGlobals !== undefined)
+    out.editGlobals = validateEditGlobals(ctx, "editGlobals", raw.editGlobals);
   if (raw.helpers !== undefined)
     out.helpers = validateHelpers(ctx, raw.helpers);
   // [LAW:one-source-of-truth] Group sugar synthesis runs AFTER every section
@@ -328,5 +334,6 @@ const TOP_LEVEL_KEYS = new Set([
   "actions",
   "looks",
   "presets",
+  "editGlobals",
   "helpers",
 ]);

package/src/config/dsl-types.ts

@@ -172,6 +172,9 @@ export interface RawDslConfig {
   // arrangement selected per session, the exact twin of `looks` one level up
   // (a look adapts the THEME; a preset adapts the LAYOUT + display globals).
   readonly presets?: Readonly<Record<string, PresetDecl>>;
+  // The display globals edit mode stages while it is on — see DslConfig's own
+  // `editGlobals` for the shape, the merge, and where it sits in the chain.
+  readonly editGlobals?: Partial<Globals>;
   // Named theme-adaptation bundles ("looks"): each is a full ThemeKey (the
   // loader normalizes absent axes to identity at parse). Applied ON TOP of the
   // active theme at render — a transform composing with every theme, selected
@@ -216,6 +219,26 @@ export interface DslConfig {
   // `{ set: …, from: "presets" }` ranges these names; the derived click gate and
   // the rendered options read this one map.
   readonly presets: Readonly<Record<string, PresetDecl>>;
+  // [LAW:one-source-of-truth] The display globals edit mode stages while it is
+  // on — the `globals` half of the fragment whose `root` half edit chrome
+  // already stages (src/config/edit-chrome.ts). Merges FIELD BY FIELD with the
+  // bundled default's (like `globals` itself, not wholesale like `root`), so a
+  // user retuning the separator keeps the bundled `style: "plain"`.
+  //
+  // [LAW:types-are-the-program] `Partial<Globals>`, deliberately NOT
+  // `PresetDecl`: a preset is root + globals, and edit mode needs only the
+  // globals half. Taking the wider type to use half of it would make "an edit
+  // fragment that restages the layout" representable — a second authority over
+  // a tree edit-chrome already owns. The loader additionally rejects `preset`
+  // inside it, for the same reason a preset may not select a preset.
+  //
+  // Its rung in the precedence chain is the RIGHTMOST one (see
+  // src/config/presets.ts): it outranks even a session pick, because entering
+  // edit mode is decided later than picking a style. Nothing writes it back to
+  // SessionState or the overrides layer, which is why leaving edit mode
+  // restores the previous look with no save/restore path
+  // [LAW:dataflow-not-control-flow].
+  readonly editGlobals: Partial<Globals>;
   // [LAW:single-enforcer] The effective helper set: a name → template-body map
   // compiled to a defines-preamble at registerDslConfig. Empty when no config
   // declares helpers — an absent `helpers` key merges to `{}` (same cascade as

package/src/config/edit-chrome.ts

@@ -36,9 +36,12 @@ import { presetRootOpsKey } from "./loader/persist-target.js";
 import { ident } from "./ident.js";
 import {
   EDIT_MODE_GATE,
+  EDIT_MODE_REF,
   EDIT_NS,
   EDIT_TOGGLE_ACTION,
 } from "./loader/edit-mode.js";
+import { declareHelp, type HelpDisclosure } from "./help.js";
+import { EDIT_MODE_HELP } from "../help-text.js";
 import { GROUP_NS } from "./loader/layout.js";
 import { SETTINGS_NS } from "./settings-menu.js";
 import {
@@ -51,6 +54,7 @@ import {
 import {
   DISCLOSURE_CLOSED,
   DISCLOSURE_GLYPH_CLOSE,
+  escapeTemplateLiteral,
   disclosureCycleAction,
   disclosureStateVar,
 } from "./disclosure.js";
@@ -88,17 +92,6 @@ function isChromeExempt(name: string): boolean {
   );
 }
 
-// [LAW:no-silent-failure] Go-template string-literal escaping for a preset
-// NAME spliced into DISPLAY text (prependCustomizedBanner) rather than an
-// identifier — the same hazard loader/layout.ts's group `label` synthesis
-// already guards against, reimplemented here since that copy is
-// module-private and this one small rule doesn't warrant its own shared
-// module the way `ident` (checked for agreement across three sites —
-// see ./ident.ts) did.
-function escapeTemplateLiteral(s: string): string {
-  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-
 // [LAW:one-source-of-truth] Every synthesized decl this pass produces, keyed
 // by its final name — one accumulator threaded through every preset's splice
 // so cross-preset names (disambiguated by `presetIdent`) can never collide.
@@ -312,17 +305,23 @@ function spliceContainer(
 // synthesized the SAME way (one reset action targeting this preset's exact
 // `persist` key, one segment hosting `{{ action }}`), UNCONDITIONALLY, with
 // visibility carried entirely by PRESET_CUSTOMIZED_GATE
-// [LAW:dataflow-not-control-flow]. Prepended as an extra ROW (not spliced
-// into the row-interleaved chrome spliceContainer builds) because it is not
-// bound to any one segment gap — it is a fact about the whole tree — so it
-// gets its own line above it, visible or not by the SAME `when` every other
-// synthesized affordance here already uses.
-function prependCustomizedBanner(
+// [LAW:dataflow-not-control-flow]. It gets its own ROW (not a slot in the
+// row-interleaved chrome spliceContainer builds) because it is not bound to any
+// one segment gap — it is a fact about the whole tree — visible or not by the
+// SAME `when` every other synthesized affordance here already uses.
+//
+// candybar-settings-ui-aok.6 hangs edit mode's `(?)` off the same content — its
+// BODY is a per-preset row on the same footing as the banner, so this function
+// now brackets the content rather than only preceding it, which is what its name
+// says and why it is no longer "prepend". Its TRIGGER is not a row; see
+// withTrailingCell.
+function wrapWithPresetRows(
   splicedRoot: LayoutNode,
   presetName: string,
   presetIdent: string,
   rootOpsKey: string,
   artifacts: ChromeArtifacts,
+  help: HelpDisclosure,
 ): LayoutNode {
   const actionName = `${EDIT_NS}${presetIdent}.resetLayout`;
   const chromeSegName = `${EDIT_NS}${presetIdent}.customized`;
@@ -365,11 +364,85 @@ function prependCustomizedBanner(
   return {
     kind: "container",
     direction: "vertical",
-    children: [{ kind: "segment", name: chromeSegName }, splicedRoot],
+    children: [
+      { kind: "segment", name: chromeSegName },
+      withTrailingCell(splicedRoot, help.trigger),
+      // The body is a ROW of its own, and only while the disclosure is open —
+      // dropping BELOW the row that revealed it, like every other disclosure
+      // body in this codebase.
+      help.body,
+    ],
     ...(splicedRoot.when !== undefined && { when: splicedRoot.when }),
   };
 }
 
+// [LAW:one-source-of-truth] `HelpDisclosure.trigger` is a CELL, and its contract
+// is that the caller joins it to a row it ALREADY HAS — the settings menu pushes
+// it into the row holding `persist?`. Edit mode's rows are the ones
+// spliceContainer just built, so the trigger joins the last of them. Two
+// constraints pin that placement and nothing else satisfies both:
+//
+//  - Closed help must cost no LINE. A trigger given its own vertical slot is a
+//    permanent row for the whole time edit mode is on, since a trigger's `when`
+//    is its host surface's, never its own open state (a trigger you must open in
+//    order to see could never be opened).
+//  - Closed help must cost no COLOUR. The hue cursor (src/dsl/render.ts:696)
+//    advances in pre-order over every segment leaf — VISIBLE OR NOT, so that
+//    toggling a disclosure never recolours the bar — which means a leaf inserted
+//    AHEAD of the content shifts the hue index of everything after it. An
+//    earlier draft put the `(?)` first and recoloured every cell of the bundled
+//    default (status row 33;41;59 → 49;36;52) with edit mode still OFF. Trailing
+//    the last row is the one position that moves no other leaf.
+//
+// Those two together disqualify the reset-banner row, which sits above the
+// content.
+//
+// A THIRD requirement decides how far the descent may go, and it outranks the
+// other two: the trigger must be visible exactly when EDIT MODE is, since a
+// trigger you must already have opened something else to reach is not a trigger.
+// A container's `when` reaches every descendant, so descending into a
+// `when`-bearing container would silently make its gate the trigger's gate.
+// `kind: "group"` is the shape that makes this concrete rather than theoretical:
+// lowerGroup emits `{vertical, children: [toggle, {…, when: groupGate}]}`, so a
+// preset root ending in a group — ordinary authoring the A-grammar endorses —
+// would otherwise put the `(?)` INSIDE that group's collapsible body, gated on
+// edit mode AND a disclosure most groups default closed. Pairing beside a gated
+// SEGMENT is a different act and stays allowed: `{h: [gatedSeg, cell]}` puts the
+// cell beside the gate rather than under it.
+//
+// For a root whose last row is gated the three requirements are jointly
+// unsatisfiable, so the priority is stated rather than left to whichever branch
+// the recursion happens to reach: visible (always) > no recolour (always, since
+// appending is still after every existing leaf) > no extra line (surrendered
+// here, in exactly the configs where riding a row was never possible).
+//
+// [LAW:dataflow-not-control-flow] Total over the node shapes with no guard: a
+// segment is a row of one that cannot hold a second cell, so it pairs into one;
+// a vertical container's rows are its children, so it descends into the last one
+// it may; anything else appends. An empty container has no last child and
+// appends, which is the same answer.
+function withTrailingCell(node: LayoutNode, cell: LayoutNode): LayoutNode {
+  if (node.kind === "segment") {
+    return {
+      kind: "container",
+      direction: "horizontal",
+      children: [node, cell],
+    };
+  }
+  const last = node.children.at(-1);
+  if (
+    node.direction === "vertical" &&
+    last !== undefined &&
+    (last.kind === "segment" || last.when === undefined)
+  ) {
+    return {
+      ...node,
+      children: [...node.children.slice(0, -1), withTrailingCell(last, cell)],
+    };
+  }
+  return { ...node, children: [...node.children, cell] };
+}
+
 // One preset's chrome-spliced root. A bare-segment root (the A-grammar
 // collapses a single top-level segment ref to `{ kind: "segment", name }`
 // with no enclosing container) is wrapped in a synthetic horizontal
@@ -379,6 +452,7 @@ function spliceEditChromeForPreset(
   config: DslConfig,
   presetName: string,
   artifacts: ChromeArtifacts,
+  help: HelpDisclosure,
 ): LayoutNode {
   const { node } = presetRoot(config, presetName);
   const rootOpsKey = presetRootOpsKey(presetName);
@@ -387,7 +461,7 @@ function spliceEditChromeForPreset(
   const posCounter = { n: 0 };
   // [LAW:no-silent-failure] The bare-segment-root case (the A-grammar's
   // `{ seg, when }` shorthand is a legal PresetDecl.root) carries its OWN
-  // `when` onto this synthetic wrapper too — prependCustomizedBanner's own
+  // `when` onto this synthetic wrapper too — wrapWithPresetRows's own
   // when-carry-up reads `splicedRoot.when`, which is this wrapper's `when`
   // once spliceContainer's `{...node, children}` passes it through
   // unchanged; without copying it here, a bare-segment preset root's own
@@ -410,12 +484,13 @@ function spliceEditChromeForPreset(
     artifacts,
     posCounter,
   );
-  return prependCustomizedBanner(
+  return wrapWithPresetRows(
     spliced,
     presetName,
     presetIdent,
     rootOpsKey,
     artifacts,
+    help,
   );
 }
 
@@ -444,9 +519,27 @@ export function synthesizeEditChrome(config: DslConfig): DslConfig {
     actions: {},
     segments: {},
   };
+  // [LAW:one-source-of-truth] Edit mode's `(?)` is minted ONCE and merely
+  // REFERENCED from every preset root — the same move the settings menu makes
+  // with its anchor, and for the same reason: one disclosure means one open
+  // state, so switching presets cannot land you beside a second `(?)` that
+  // disagrees about whether help is showing. The text is identical for every
+  // preset because what `+` and `-` do is a fact about edit mode, not about a
+  // layout.
+  const help = declareHelp(
+    `${EDIT_NS}help`,
+    EDIT_MODE_HELP,
+    [EDIT_MODE_REF],
+    artifacts,
+  );
   const presets: Record<string, PresetDecl> = { ...config.presets };
   for (const name of presetNames(config.presets)) {
-    const splicedRoot = spliceEditChromeForPreset(config, name, artifacts);
+    const splicedRoot = spliceEditChromeForPreset(
+      config,
+      name,
+      artifacts,
+      help,
+    );
     presets[name] = {
       ...presetByName(config.presets, name),
       root: splicedRoot,