@promptctl/cc-candybar 1.35.0 → 1.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.35.0",
+  "version": "1.37.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.35.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.35.0",
-    "@promptctl/cc-candybar-linux-x64": "1.35.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.35.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.37.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.37.0",
+    "@promptctl/cc-candybar-linux-x64": "1.37.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.37.0"
   }
 }

package/src/check.ts

@@ -36,14 +36,14 @@ import {
   effectiveLookName,
   lookKeyByName,
   effectiveStripStyle,
+  effectiveAutoWrap,
+  effectivePadding,
 } from "./themes/policy.js";
 import { paletteForThemeName } from "./themes/palette-resolvers.js";
 import { effectivePresetName, presetGlobals } from "./config/presets.js";
 import {
   DEFAULT_CHARSET,
   DEFAULT_COLOR_COMPATIBILITY,
-  DEFAULT_PADDING,
-  DEFAULT_WRAP,
 } from "./render/strip.js";
 import type { EffectiveGlobals } from "./daemon/render-payload.js";
 
@@ -321,8 +321,8 @@ function loadRegisterRender(
       theme: effectiveThemeName(null, globals.palette),
       look: effectiveLookName(null, globals.look, config.looks),
       style: effectiveStripStyle(null, globals.style),
-      autoWrap: globals.autoWrap ?? DEFAULT_WRAP,
-      padding: globals.padding ?? DEFAULT_PADDING,
+      autoWrap: effectiveAutoWrap(null, globals.autoWrap),
+      padding: effectivePadding(null, globals.padding),
       charset: globals.charset ?? DEFAULT_CHARSET,
       colorCompatibility:
         globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,

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

@@ -28,6 +28,7 @@
 
 import type { DslConfig, LayoutNode, SegmentDecl } from "./dsl-types.js";
 import { parseDslConfig } from "./dsl-loader.js";
+import { BOOLEAN_MEMBERS, PADDING_RANGE } from "../themes/policy.js";
 import { mergeWithDefault } from "./loader/merge.js";
 
 // ─── Shared template fragments ───────────────────────────────────────────────
@@ -250,7 +251,11 @@ function etaHeatFg(etaRef: string, warnRef: string): string {
 // theme/style/look/preset (session `set` for a per-conversation preview, PLUS
 // a persist-forever twin — candybar-config-engine-71o.5, brandon-presets-0yk.3
 // — for pinning the choice as everyone's default), the four .3 globals
-// steppers (persist-only, no SessionState half at all), and one .6
+// steppers (persist-only HERE — `autoWrap`/`padding` have gained a session
+// half since, but the drawer's own controls stay durable-by-default until
+// candybar-settings-ui-aok.3 gives the panel one `persist?` toggle instead of
+// a spelling per row; `charset`/`colorCompatibility` have no session half at
+// all, by design), and one .6
 // segment-scoped persist control (directoryPaletteControl, persist-only like
 // the four steppers — a per-segment palette pin, not a whole-bar default).
 // Placed as a sibling in row 1's horizontal container, toggled from beside the
@@ -1222,8 +1227,11 @@ export const RAW_DEFAULT_DSL_CONFIG = {
     // ── The four .3 globals steppers, folded into the settingsDrawer group
     // (candybar-config-engine-71o.4) alongside theme/style/look above. Each
     // pairs a `persist` control with a `↺` reset (docs' persist/reset
-    // convention) — these four have no SessionState half at all, so persist
-    // is their only seam, unlike theme/style/look's session `set`. Labels
+    // convention) — `charset`/`colorCompatibility` have no SessionState half
+    // at all, so persist is genuinely their only seam, while
+    // `autoWrap`/`padding` do have one and are simply spelled durable here
+    // (candybar-settings-ui-aok.3 owns whether the panel offers the choice).
+    // Labels
     // read `.field.effective` (the daemon-resolved value BuildLineOptions
     // actually rendered with), never a restated literal.
     charsetControl: {
@@ -1421,8 +1429,11 @@ export const RAW_DEFAULT_DSL_CONFIG = {
     // (candybar-config-engine-71o.4), decoupled by NAME from
     // charsetControl/colorCompatControl/wrapToggleControl/paddingControl
     // below. Unlike theme/style/look (a per-session experiment via `set`),
-    // these four have no SessionState half at all — .3's handoff established
-    // `persist` as their ONLY seam — so every one of these writes the
+    // these four are spelled durable: `charset`/`colorCompatibility` have no
+    // SessionState half at all, and `autoWrap`/`padding` have one
+    // (candybar-settings-ui-aok.2) but keep persist as the DRAWER's spelling
+    // until .3 collapses the twins behind one `persist?`. So every one of
+    // these writes the
     // config-file DEFAULT through the daemon-owned overrides layer (never the
     // hand-authored file itself), gated by the SAME deriveActionValidators
     // pass as a `set` (persist mirrors set's value-source shapes one for
@@ -1435,10 +1446,14 @@ export const RAW_DEFAULT_DSL_CONFIG = {
       from: "colorCompatibilities",
     },
     resetColorCompat: { reset: "colorCompatibility" },
-    toggleWrapForever: { persist: "autoWrap", cycle: ["true", "false"] },
+    // [LAW:one-source-of-truth] The toggle's members and the stepper's bounds
+    // are the SAME literals the resolvers parse a session pick with
+    // (BOOLEAN_MEMBERS / PADDING_RANGE in themes/policy.ts) — a click cannot
+    // write a value the render's own resolution would then refuse.
+    toggleWrapForever: { persist: "autoWrap", cycle: [...BOOLEAN_MEMBERS] },
     resetAutoWrap: { reset: "autoWrap" },
-    paddingDownForever: { persist: "padding", min: 0, max: 16, by: -1 },
-    paddingUpForever: { persist: "padding", min: 0, max: 16, by: 1 },
+    paddingDownForever: { persist: "padding", ...PADDING_RANGE, by: -1 },
+    paddingUpForever: { persist: "padding", ...PADDING_RANGE, by: 1 },
     resetPadding: { reset: "padding" },
 
     // [LAW:locality-or-seam] The segment-palette control's behavior

package/src/config/dsl-loader.ts

@@ -50,6 +50,8 @@ import { synthesizeGroupDecls, validateRoot } from "./loader/layout.js";
 import { synthesizeMenuDecls } from "./loader/menu-synth.js";
 import { synthesizeEditModeToggle } from "./loader/edit-mode.js";
 import { synthesizeEditChrome } from "./edit-chrome.js";
+import { SETTINGS_NS, synthesizeSettingsMenu } from "./settings-menu.js";
+import { reservedNamespaceCollisions } from "./loader/reserved-namespace.js";
 import { validateActions } from "./loader/actions.js";
 import { validateLooks } from "./loader/looks.js";
 import { validatePresets } from "./loader/presets.js";
@@ -152,7 +154,12 @@ export function validateConfig(
   // into freshly-synthesized segments, actions into freshly-synthesized
   // actions) is correct by construction and does not re-enter cross-ref/
   // cycle checking, exactly as group/menu synthesis's output doesn't either.
-  const withChrome = synthesizeEditChrome(config);
+  // [LAW:dataflow-not-control-flow] candybar-settings-ui-aok.1's global settings
+  // menu, spliced BEFORE edit chrome so edit chrome walks the final content tree
+  // and treats the menu's reserved `settings.` names as chrome-exempt — the
+  // full ordering argument lives in settings-menu.ts's header, beside the pass
+  // it governs.
+  const withChrome = synthesizeEditChrome(synthesizeSettingsMenu(config));
   return withChrome as ValidatedConfig;
 }
 
@@ -295,6 +302,18 @@ function validateTopLevel(
   // affordances) runs later, in validateConfig, once the merged/preset-
   // resolved/rootOps-replayed tree exists to derive it from.
   synthesizeEditModeToggle(ctx, out);
+  // [LAW:one-source-of-truth] The global settings menu reserves its namespace
+  // here and synthesizes NOTHING here: the tree it must be present in only
+  // exists after merge (a user `root` replaces the default's), so the artifacts
+  // are minted in validateConfig. The reservation is unconditional all the same,
+  // mirroring every other namespace above — "you never author settings.*" is a
+  // stable contract, not a rule that switches on when the pass happens to fire.
+  reservedNamespaceCollisions(
+    ctx,
+    out,
+    SETTINGS_NS,
+    "the global settings menu",
+  );
   return out;
 }
 

package/src/config/edit-chrome.ts

@@ -40,6 +40,7 @@ import {
   EDIT_TOGGLE_ACTION,
 } from "./loader/edit-mode.js";
 import { GROUP_NS } from "./loader/layout.js";
+import { SETTINGS_NS } from "./settings-menu.js";
 import {
   menuActionName,
   menuMember,
@@ -61,7 +62,11 @@ import {
 // knowledge, so the banner below is spliced UNCONDITIONALLY for every
 // preset — same shape, every reload — and this predicate is what decides
 // whether it's visible, never a branch in this synthesis pass.
-const PRESET_CUSTOMIZED_GATE = "{{ .preset.customized }}";
+// [LAW:one-source-of-truth] Exported: test/helpers/ambient-chrome.ts filters this
+// ensured name out of "what did the AUTHOR declare" assertions and must read the
+// same string, never a second copy that a rename here would leave behind.
+export const PRESET_CUSTOMIZED_VAR = "preset.customized";
+const PRESET_CUSTOMIZED_GATE = `{{ .${PRESET_CUSTOMIZED_VAR} }}`;
 
 // [LAW:one-source-of-truth] group/menu-synthesized segments (`groups.`/
 // `menus.`) and edit mode's own trigger/chrome (`edit.`) are structural —
@@ -73,7 +78,12 @@ function isChromeExempt(name: string): boolean {
   return (
     name.startsWith(EDIT_NS) ||
     name.startsWith(MENU_NS) ||
-    name.startsWith(GROUP_NS)
+    name.startsWith(GROUP_NS) ||
+    // The global settings menu is the entry point edit mode is REACHED from
+    // (candybar-settings-ui-aok.1) — offering a `-` beside it would let one
+    // click delete the door back in, the self-lockout the `toolbar` trigger's
+    // placement was chosen to avoid. Structural, like the three above it.
+    name.startsWith(SETTINGS_NS)
   );
 }
 
@@ -93,6 +103,11 @@ function escapeTemplateLiteral(s: string): string {
 // so cross-preset names (disambiguated by `presetIdent`) can never collide.
 interface ChromeArtifacts {
   readonly variables: Record<string, VariableDecl>;
+  // [LAW:no-silent-failure] Declarations this synthesis DEPENDS on rather than
+  // OWNS: merged UNDER the config so a user's own declaration of the same name
+  // wins, unlike `variables` above, which lives in a reserved namespace no user
+  // may write and therefore merges over.
+  readonly ensured: Record<string, VariableDecl>;
   readonly actions: Record<string, ActionDeclType>;
   readonly segments: Record<string, SegmentDecl>;
 }
@@ -219,7 +234,18 @@ function spliceContainer(
   posCounter: { n: number },
 ): ContainerNode {
   const children: LayoutNode[] = [];
-  for (const child of node.children) {
+  // [LAW:one-source-of-truth] The trailing `+`'s position is "after the last
+  // CONTENT segment", not "after the last child". Those coincided until a
+  // synthesis started appending exempt chrome (the global settings menu,
+  // candybar-settings-ui-aok.1) to a row's end, at which point reading the last
+  // child silently dropped the row's final insert point — N segments offering
+  // only N insert points instead of N+1.
+  const lastContent = node.children.reduce(
+    (idx, child, i) =>
+      child.kind === "segment" && !isChromeExempt(child.name) ? i : idx,
+    -1,
+  );
+  for (const [i, child] of node.children.entries()) {
     if (child.kind === "container") {
       children.push(
         spliceContainer(
@@ -250,24 +276,19 @@ function spliceContainer(
     );
     children.push(child);
     children.push(removeChrome(presetIdent, rootOpsKey, child.name, artifacts));
-  }
-  const last = node.children[node.children.length - 1];
-  if (
-    last !== undefined &&
-    last.kind === "segment" &&
-    !isChromeExempt(last.name)
-  ) {
-    children.push(
-      insertChrome(
-        presetIdent,
-        rootOpsKey,
-        String(posCounter.n++),
-        domainName,
-        last.name,
-        "after",
-        artifacts,
-      ),
-    );
+    if (i === lastContent) {
+      children.push(
+        insertChrome(
+          presetIdent,
+          rootOpsKey,
+          String(posCounter.n++),
+          domainName,
+          child.name,
+          "after",
+          artifacts,
+        ),
+      );
+    }
   }
   return { ...node, children };
 }
@@ -301,6 +322,20 @@ function prependCustomizedBanner(
   // edited down to zero non-exempt segments (no removeChrome/insertChrome
   // persist actions left to register it) doesn't orphan this exact click.
   artifacts.actions[actionName] = { reset: rootOpsKey };
+  // [LAW:one-source-of-truth] The banner reads `.preset.customized`, so THIS
+  // pass is what requires that variable — not whichever config happens to
+  // declare it. The bundled default does, which is why the dependency stayed
+  // invisible until the global settings menu made edit mode reachable from
+  // configs that never declared it, and the missing field surfaced as a ⚠ on
+  // the bar. Ensured, never overridden: a user declaration of the same name
+  // wins (see the merge in synthesizeEditChrome), so this only supplies the
+  // floor the synthesis itself depends on.
+  artifacts.ensured[PRESET_CUSTOMIZED_VAR] = {
+    kind: "input",
+    path: PRESET_CUSTOMIZED_VAR,
+    type: "boolean",
+    default: false,
+  };
   const label = escapeTemplateLiteral(presetName);
   artifacts.segments[chromeSegName] = {
     template: `{{ action "${actionName}" "↺ ${label} customized" }}`,
@@ -391,6 +426,7 @@ export function synthesizeEditChrome(config: DslConfig): DslConfig {
   if (!(EDIT_TOGGLE_ACTION in config.actions)) return config;
   const artifacts: ChromeArtifacts = {
     variables: {},
+    ensured: {},
     actions: {},
     segments: {},
   };
@@ -404,7 +440,11 @@ export function synthesizeEditChrome(config: DslConfig): DslConfig {
   }
   return {
     ...config,
-    variables: { ...config.variables, ...artifacts.variables },
+    variables: {
+      ...artifacts.ensured,
+      ...config.variables,
+      ...artifacts.variables,
+    },
     actions: { ...config.actions, ...artifacts.actions },
     segments: { ...config.segments, ...artifacts.segments },
     presets,

package/src/config/loader/cross-ref.ts

@@ -29,6 +29,13 @@ import {
 import { listGlobalsFieldNames } from "./globals.js";
 import { parsePersistTarget } from "./persist-target.js";
 import { presetNames } from "../presets.js";
+import {
+  canHostSessionState,
+  countAnchors,
+  isSettingsAnchor,
+  SESSION_ID_VAR,
+  SETTINGS_ANCHOR,
+} from "../settings-menu.js";
 import { ident } from "../ident.js";
 import { findKeyLine } from "./diagnostics.js";
 import { isPlainObject, type ValidateCtx } from "./validate-core.js";
@@ -248,11 +255,30 @@ export function validateCrossReferences(
   // never a second traversal that could learn a different idea of what a valid
   // layout is. This is what makes `cc-candybar check` catch a preset staging a
   // segment nobody declared.
+  //
+  // [LAW:single-enforcer] The menu precondition is asked once, of the same
+  // predicate synthesizeSettingsMenu gates on, and read by every tree walked.
+  const menuWillSynthesize = canHostSessionState(cfg);
   const checkLayoutTree = (
     root: LayoutNode,
     layoutKey: string,
     layoutLine: number | undefined,
   ): void => {
+    // [LAW:one-source-of-truth] The global settings menu's anchor is a POSITION
+    // an author may place and this walk must therefore accept, even though no
+    // config declares a segment by that name — synthesizeSettingsMenu provides
+    // it unconditionally, immediately after these checks pass. Two placements is
+    // the real error: one state key holds one open state, so a second anchor
+    // would be a second toggle writing one disclosure, with two bodies claiming
+    // to be it. Counted over the SAME census the synthesis reads, so "placed"
+    // means one thing [LAW:single-enforcer].
+    if (countAnchors(root) > 1) {
+      ctx.issues.push({
+        path: layoutKey,
+        message: `${layoutKey} places the global settings menu anchor "${SETTINGS_ANCHOR}" ${countAnchors(root)} times — it may appear at most once per layout (it is one disclosure, and one state key holds one open state). Remove all but the placement you want; removing every placement puts the menu at its default position.`,
+        line: layoutLine,
+      });
+    }
     for (const node of walkNodes(root)) {
       // [LAW:locality-or-seam] A node's `when` reads the global scope (bare
       // globals + namespaced segment vars) — the same existence-check shape as a
@@ -263,6 +289,24 @@ export function validateCrossReferences(
         });
       }
       if (node.kind !== "segment") continue;
+      if (isSettingsAnchor(node.name)) {
+        // [LAW:one-source-of-truth] Accepting the anchor asserts that
+        // synthesizeSettingsMenu WILL declare a segment by this name, so the
+        // acceptance reads the very predicate that pass decides by rather than
+        // assuming its answer. When it is false the reference is genuinely
+        // dangling, and the error names the unmet precondition: the author
+        // placed a documented anchor, they did not typo a segment name, and the
+        // generic "does not match any declared segment" would teach the wrong
+        // lesson [LAW:no-silent-failure].
+        if (!menuWillSynthesize) {
+          ctx.issues.push({
+            path: layoutKey,
+            message: `${layoutKey} places the global settings menu anchor "${SETTINGS_ANCHOR}", but this config declares no "${SESSION_ID_VAR}" variable — the menu is a click surface and every click composes a URL from "${SESSION_ID_VAR}", so it is not synthesized for a config without it. Declare a "${SESSION_ID_VAR}" variable (any config merged onto the bundled default inherits one) or remove the anchor placement.`,
+            line: layoutLine,
+          });
+        }
+        continue;
+      }
       if (!Object.prototype.hasOwnProperty.call(cfg.segments, node.name)) {
         const renamed = RENAMED_SEGMENTS[node.name];
         const hint =

package/src/config/loader/edit-mode.ts

@@ -29,6 +29,20 @@
 // of this pass caused. The reserved namespace stays reserved unconditionally
 // (mirroring reservedNamespaceCollisions' own contract); only the SYNTHESIS is
 // conditional.
+//
+// WHAT candybar-settings-ui-aok.1 CHANGED, and what it did not: the gate above
+// is intact and still the only way edit mode is reached — but it now has a
+// PERMANENT DEMANDER. synthesizeSettingsMenu mints a `settings.edit` segment
+// referencing `edit.toggle` into every config it can host, so in practice the
+// demand is satisfied for essentially every config a user writes, and reading
+// this section as "most bars carry no edit mode" is no longer true. The
+// separation the gate protects still holds exactly where it always mattered:
+// the menu declines to synthesize for a config with no `session.id`
+// (canHostSessionState in settings-menu.ts), which is precisely the static,
+// non-interactive bar this comment was written to keep clean. Production blast
+// radius was nil either way — the bundled default's `toolbar` segment already
+// referenced `edit.toggle`, so every config merging it already demanded edit
+// mode before the menu existed.
 
 import { createEngine } from "@promptctl/go-template-js";
 import type { Mutable, ValidateCtx } from "./validate-core.js";

package/src/config/loader/globals.ts

@@ -7,6 +7,7 @@ import { type Globals } from "../dsl-types.js";
 import {
   CHARSETS,
   COLOR_COMPATIBILITIES,
+  PADDING_RANGE,
   STRIP_STYLES,
   type ColorCompatibility,
 } from "../../themes/policy.js";
@@ -84,7 +85,11 @@ const GLOBALS_FIELDS: FieldSpecMap<Globals> = {
   // drive an unbounded `" ".repeat` allocation in the daemon
   // [LAW:no-silent-failure] — an absurd value is a loud load error, not a
   // silently-huge render.
-  padding: optionalIntSpec({ min: 0, max: 16 }),
+  // [LAW:one-source-of-truth] The bound comes from PADDING_RANGE, the same
+  // literal the bundled default's stepper actions bound clicks by and the
+  // session-half parse admits values from — so the file, the click, and the
+  // session pick cannot end up honouring three different ranges.
+  padding: optionalIntSpec(PADDING_RANGE),
   // [LAW:types-are-the-program] Closed enum like `style`: the joiner glyph
   // vocabularies pickJoiner can render — validates by membership, emits a
   // JSON-Schema `enum` from the same CHARSETS literal.

package/src/config/presets.ts

@@ -168,9 +168,14 @@ export function presetGlobals(config: DslConfig, name: string): Globals {
 // that is a typo in a file the author can see and fix — but a value that
 // only exists because the overrides layer supplied it gets the SAME
 // treatment a stale SessionState pick already gets from effectivePresetName:
-// collapse to the floor, visibly, never throw. Dropping the field here (so
-// it never reaches validateConfig) is what makes that collapse happen for
-// this layer too, instead of a fatal error replacing the whole bar.
+// an undeclared name is not a pick at all, so the resolution moves on to the
+// next rung of the precedence chain — visibly, never a throw. (For a stale
+// SESSION pick that next rung is the config's own `globals.preset`, and only
+// then the floor; for the field dropped here it is whatever the config file
+// itself declares. Same rule, different starting rung —
+// see effectiveGlobal in themes/policy.ts.) Dropping the field here (so it
+// never reaches validateConfig) is what applies that rule to this layer too,
+// instead of a fatal error replacing the whole bar.
 export function sanitizePersistedPresetOverride(
   globalsOverride: Partial<Globals>,
   declaredPresets: Readonly<Record<string, PresetDecl>>,