@promptctl/cc-candybar 1.26.0 → 1.27.0

package/src/daemon/server.ts

@@ -68,8 +68,9 @@ import {
   effectiveThemeName,
   effectiveLookName,
   lookKeyByName,
-  resolverForThemeName,
+  paletteForThemeName,
 } from "../themes/index.js";
+import { effectivePresetName, presetGlobals } from "../config/presets.js";
 import {
   renderStripCells,
   DEFAULT_CHARSET,
@@ -83,7 +84,7 @@ import {
 } from "../render/strip.js";
 import { applyClaudeCodeReserve } from "../utils/terminal-width.js";
 import type { RichText } from "@promptctl/rich-js";
-import { buildRenderPayload } from "./render-payload.js";
+import { buildRenderPayload, type EffectiveGlobals } from "./render-payload.js";
 import { ContextProvider } from "../segments/context.js";
 import { MetricsProvider } from "../segments/metrics.js";
 import { TmuxService } from "../segments/tmux.js";
@@ -855,70 +856,79 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
         // 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.
-        const effectiveTheme = effectiveThemeName(
-          sessionState.get(req.hookData.session_id, "theme"),
-          entry.state.config.globals.palette,
-        );
-        // [LAW:one-type-per-behavior] The LOOK, resolved per render the exact
-        // way the theme is: the session's clicked look (SessionState) over the
-        // config default over the "none" floor — so a look click recolors the
-        // whole bar on the next render, composing with whatever theme is
-        // active. The name feeds the payload's `look.effective`; its ThemeKey
-        // (lookKeyByName) feeds renderDsl below — one resolution, two readers.
-        const effectiveLook = effectiveLookName(
-          sessionState.get(req.hookData.session_id, "look"),
-          entry.state.config.globals.look,
-          entry.state.config.looks,
+        //
+        // [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 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/colorCompatibility/autoWrap/
+        // padding have no SessionState half today, so their "effective" value
+        // is just the config global over its floor constant. 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,
+          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: globals.autoWrap ?? DEFAULT_WRAP,
+          padding: globals.padding ?? DEFAULT_PADDING,
+          charset: globals.charset ?? DEFAULT_CHARSET,
+          colorCompatibility:
+            globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,
+        };
         const payload = await buildRenderPayload(
           req.hookData,
           payloadDeps,
           req.cwd,
           entry.state.neededInputPaths,
-          effectiveTheme,
-          effectiveLook,
+          effective,
         );
         // [LAW:one-source-of-truth][LAW:dataflow-not-control-flow] basePalette
         // is derived from the same effective theme resolved above — so a theme
         // click recolors the whole bar on the next render. Not frozen on the
-        // cache entry (one entry serves many sessions). resolverForThemeName
+        // cache entry (one entry serves many sessions). paletteForThemeName
         // memoizes, so the per-render cost is one Map lookup once the theme is
         // warm.
-        const basePalette = resolverForThemeName(effectiveTheme);
-        // [LAW:one-type-per-behavior][LAW:dataflow-not-control-flow] The powerline
-        // cap/separator SHAPE, resolved per render the exact way the theme is: the
-        // session's clicked style (SessionState) over the config default over the
-        // "powerline" floor — so a style click reshapes the whole bar on the next
-        // render. The base style on renderOpts is only the floor; this is the live
-        // override fed to the one joiner dispatch in renderStripCells.
-        renderOpts.style = effectiveStripStyle(
-          sessionState.get(req.hookData.session_id, "style"),
-          entry.state.config.globals.style,
-        );
-        // [config-only] globals.autoWrap has no SessionState half (no click
-        // verb) — the config global over the base floor is the whole
-        // resolution. Width stays finite regardless: it also feeds the
-        // picker's pagination (term.cols), which no-wrap must not break.
-        renderOpts.wrap = entry.state.config.globals.autoWrap ?? DEFAULT_WRAP;
-        // [config-only] globals.padding, same shape as autoWrap: the config
-        // global over the base floor is the whole resolution — the ONE home
-        // of the value every cell builder (and the picker's pagination
-        // reserve) derives from. [LAW:one-source-of-truth]
-        renderOpts.padding =
-          entry.state.config.globals.padding ?? DEFAULT_PADDING;
-        // [config-only] globals.charset, same shape as autoWrap/padding: the
-        // config global over the base floor is the whole resolution — the ONE
-        // home of the glyph-vocabulary choice pickJoiner derives from.
-        // [LAW:one-source-of-truth]
-        renderOpts.charset =
-          entry.state.config.globals.charset ?? DEFAULT_CHARSET;
-        // [config-only] globals.colorCompatibility, same shape as charset:
-        // the config global over the base floor is the whole resolution —
-        // the ONE home of the color-depth choice rich-js downsamples to.
-        // [LAW:one-source-of-truth]
-        renderOpts.colorCompatibility =
-          entry.state.config.globals.colorCompatibility ??
-          DEFAULT_COLOR_COMPATIBILITY;
+        const basePalette = paletteForThemeName(effective.theme);
+        // [LAW:one-source-of-truth] Every renderOpts field below reuses the
+        // SAME `effective` struct the payload was just built from — no second
+        // `?? DEFAULT_X` computation to drift from it.
+        renderOpts.style = effective.style;
+        renderOpts.wrap = effective.autoWrap;
+        renderOpts.padding = effective.padding;
+        renderOpts.charset = effective.charset;
+        renderOpts.colorCompatibility = effective.colorCompatibility;
         // [LAW:single-enforcer] renderDsl internally calls
         // `registry.applyInput(payload)` as its first step (see step 1 in
         // src/dsl/render.ts). The daemon must not pre-apply — doing so
@@ -939,7 +949,10 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
           // the per-segment ANSI serialization happens lazily inside the
           // debug handler so normal renders pay no extra serializer cost.
           { perSegmentSink: entry.state.lastRenderCellsBySegment },
-          lookKeyByName(entry.state.config.looks, effectiveLook),
+          {
+            look: lookKeyByName(entry.state.config.looks, effective.look),
+            preset: effective.preset,
+          },
         );
       }
       // [LAW:one-source-of-truth] Consume the transient click error written by

package/src/daemon/verbs/config-validators.ts

@@ -0,0 +1,127 @@
+// [LAW:one-source-of-truth] The persistent-config-write instance of the
+// shared keyed-validator registry (validator-registry.ts) — the twin of
+// state-validators.ts for `persist` actions instead of `set` actions.
+// Gates stay derived the same way as session writes: a `persist` action
+// carries its target key and value SOURCE as literal data, so the
+// writable-key gate DERIVES from the action table exactly like
+// deriveActionValidators does for `set`. No baseline keys: every config
+// globals field becomes writable ONLY when a config declares a `persist`
+// action for it — the epic's "zero engine edits to add a menu-able field"
+// goal, realized more strictly here than SessionState's legacy baseline
+// theme/style/toolbar-expanded keys.
+
+import type { ActionDecl } from "../../config/action";
+import {
+  perConfigDomainsFor,
+  resolveOptionDomain,
+} from "../../config/option-domain";
+import type { DslConfig } from "../../config/dsl-types";
+import { isGlobalsField } from "../config-overrides-store";
+import {
+  clampSeed,
+  createValidatorRegistry,
+  mergeContributions,
+  type DerivedValidatorSpec,
+  type KeySpecContribution,
+  type RangeParams,
+  type ValidateResult,
+} from "./validator-registry";
+
+// [LAW:no-silent-fallbacks] No baseline entries: a config globals field is
+// writable ONLY when some `persist` action names it.
+const registry = createValidatorRegistry({}, "config");
+
+export function listConfigKeys(): readonly string[] {
+  return registry.listKeys();
+}
+
+export function validateConfigWrite(
+  key: string,
+  rawValue: string,
+): ValidateResult {
+  return registry.validate(key, rawValue);
+}
+
+export function rangeParamsForConfig(key: string): RangeParams | null {
+  return registry.rangeParamsFor(key);
+}
+
+// [LAW:one-source-of-truth] The ONE place mapping a `persist` ACTION to the
+// validator key SPEC it declares — the mirror of state-validators.ts's
+// actionKeySpecs for `set`. `persist` has no `int` arm: a page cursor is a
+// UI-only paging concept with no meaning as a persisted config default.
+function actionKeySpecs(
+  a: ActionDecl,
+  seeds: ReadonlyMap<string, number>,
+  perConfigDomains: ReadonlyMap<string, readonly string[]>,
+): KeySpecContribution[] {
+  if (!("persist" in a)) return [];
+  if ("to" in a) {
+    return [{ key: a.persist, spec: { kind: "allow-list", allowed: [a.to] } }];
+  }
+  if ("from" in a) {
+    return [
+      {
+        key: a.persist,
+        spec: {
+          kind: "allow-list",
+          allowed: resolveOptionDomain(a.from, perConfigDomains),
+        },
+      },
+    ];
+  }
+  if ("cycle" in a) {
+    return [{ key: a.persist, spec: { kind: "allow-list", allowed: a.cycle } }];
+  }
+  return [
+    {
+      key: a.persist,
+      spec: {
+        kind: "range",
+        min: a.min,
+        max: a.max,
+        seed: clampSeed(seeds.get(a.persist), a.min, a.max),
+      },
+    },
+  ];
+}
+
+// [LAW:one-source-of-truth] The unset seed for a bounded `persist` key (e.g.
+// a padding stepper) is the value that would render with NO override yet —
+// the merged config's OWN globals field, before this reload's overrides are
+// applied. Mirrors stateKeySeeds' "the bar's current display, not silently
+// min" rule for SessionState steppers.
+function configKeySeeds(config: DslConfig): ReadonlyMap<string, number> {
+  const seeds = new Map<string, number>();
+  for (const [key, value] of Object.entries(config.globals)) {
+    if (isGlobalsField(key) && typeof value === "number") {
+      seeds.set(key, value);
+    }
+  }
+  return seeds;
+}
+
+function actionContributions(config: DslConfig): KeySpecContribution[] {
+  const seeds = configKeySeeds(config);
+  const perConfigDomains = perConfigDomainsFor(config);
+  return Object.values(config.actions).flatMap((a) =>
+    actionKeySpecs(a, seeds, perConfigDomains),
+  );
+}
+
+// [LAW:single-enforcer] The SOLE install-site derivation: a config's
+// persistent-config-writable-key surface is the merge of every `persist`
+// ACTION it declares, through the SAME coherence pass deriveActionValidators
+// uses for `set`.
+export function deriveConfigActionValidators(
+  config: DslConfig,
+): readonly KeySpecContribution[] {
+  return mergeContributions(actionContributions(config), "config");
+}
+
+export function registerConfigValidator(
+  key: string,
+  spec: DerivedValidatorSpec,
+): () => void {
+  return registry.register(key, spec);
+}

package/src/daemon/verbs/index.ts

@@ -19,12 +19,26 @@
 //   cc-candybar://<verb>/<value>   where <value> may itself contain `/`.
 
 import { launchSync } from "../../proc/launch";
+import type { Globals } from "../../config/dsl-types";
 import type { SessionStateRW } from "../session-state";
 import {
   listStateKeys,
   rangeParamsFor,
   validateStateWrite,
 } from "./state-validators";
+import {
+  listConfigKeys,
+  rangeParamsForConfig,
+  validateConfigWrite,
+} from "./config-validators";
+import {
+  clearConfigOverride,
+  coercePersistValue,
+  isGlobalsField,
+  loadConfigOverrides,
+  writeConfigOverride,
+} from "../config-overrides-store";
+import { configOverridesPath } from "../paths";
 import {
   decodeSegments,
   parseEffects,
@@ -32,7 +46,10 @@ import {
   VERB_DISPATCH,
   VERB_OPEN_VSCODE,
   VERB_LOAD_CONFIG,
+  VERB_RESET_CONFIG,
+  VERB_SET_CONFIG,
   VERB_SET_STATE,
+  VERB_STEP_CONFIG,
   VERB_STEP_STATE,
   VERB_SHOW_CONFIG_ERROR,
   VERB_SHOW_CONFIG_WARNING,
@@ -324,6 +341,109 @@ const stepState: VerbHandler = (rawValue, ctx) => {
   );
 };
 
+// [LAW:no-defensive-null-guards] Range-bounded (stepper) persist targets are
+// globals-only by construction: loader/cross-ref.ts (candybar-config-engine-
+// 71o.6) rejects a `min`/`max`/`by` persist arm over a `segments.<name>.
+// palette` target at config-LOAD time, so a validated write reaching
+// stepConfig with a range spec is a real Globals field by construction —
+// this assertion is the type-narrowing boundary (for the `overrides[key]`
+// index below), not a runtime possibility. setConfig has no such need:
+// coercePersistValue classifies a bare string key itself.
+function assertGlobalsField(key: string): asserts key is keyof Globals {
+  if (!isGlobalsField(key)) {
+    throw new Error(
+      `step-config: "${key}" validated as a bounded config-writable key but ` +
+        `is not a Globals field — registration/loader invariant broken`,
+    );
+  }
+}
+
+// [LAW:single-enforcer] `persist`'s twin of setState: the SAME validate-then-
+// write shape, writing through config-overrides-store instead of
+// SessionState. The write is DURABLE — RenderCache's file watcher on
+// configOverridesPath() (src/daemon/cache/render.ts) picks it up on the next
+// reload, exactly as an edit to the hand-authored config file would.
+// [LAW:no-silent-fallbacks] Unknown key or out-of-domain value is a loud
+// BAD_REQUEST — the SAME gate `set-state` uses (validateConfigWrite),
+// derived from the SAME action table (deriveConfigActionValidators).
+const setConfig: VerbHandler = (rawValue, ctx) => {
+  const [sessionId = "", key = "", incoming = ""] = decodeWire(() =>
+    decodeSegments(rawValue),
+  );
+  const sid = requireSessionId(sessionId);
+  if (!key) {
+    throw new BadVerbArgs(
+      `set-config: <key>/<value> is required (have keys: ${listConfigKeys().join(", ")})`,
+    );
+  }
+  const result = validateConfigWrite(key, incoming);
+  if (!result.ok) throw new BadVerbArgs(`set-config: ${result.reason}`);
+  const typed = coercePersistValue(key, result.value);
+  writeConfigOverride(configOverridesPath(), key, typed, ctx.dlog);
+  ctx.dlog("info", `set-config: ${key}=${result.value} (session=${sid})`);
+};
+
+// [LAW:one-source-of-truth] `persist`'s twin of stepState: a RELATIVE nudge
+// against the current override (or the merged config's own value when
+// unset — rangeParamsForConfig's seed), wrapped and re-validated through the
+// SAME range gate, then written durably.
+const stepConfig: VerbHandler = (rawValue, ctx) => {
+  const [sessionId = "", key = "", byRaw = ""] = decodeWire(() =>
+    decodeSegments(rawValue),
+  );
+  const sid = requireSessionId(sessionId);
+  if (!key) {
+    throw new BadVerbArgs(
+      "step-config: <key> is required (shape: <sessionId>/<key>/<by>)",
+    );
+  }
+  if (!STEP_INT_RE.test(byRaw)) {
+    throw new BadVerbArgs(
+      `step-config: delta must be an integer, got "${byRaw}"`,
+    );
+  }
+  const by = parseInt(byRaw, 10);
+  const params = rangeParamsForConfig(key);
+  if (!params) {
+    throw new BadVerbArgs(
+      `step-config: key "${key}" is not a bounded (range) config key ` +
+        `(have keys: ${listConfigKeys().join(", ")})`,
+    );
+  }
+  assertGlobalsField(key);
+  const overrides = loadConfigOverrides(configOverridesPath(), ctx.dlog);
+  const stored = overrides[key];
+  const current =
+    typeof stored === "number"
+      ? Math.max(params.min, Math.min(params.max, stored))
+      : params.seed;
+  const next = wrapStep(current + by, params.min, params.max);
+  const result = validateConfigWrite(key, String(next));
+  if (!result.ok) throw new BadVerbArgs(`step-config: ${result.reason}`);
+  const typed = coercePersistValue(key, result.value);
+  writeConfigOverride(configOverridesPath(), key, typed, ctx.dlog);
+  ctx.dlog(
+    "info",
+    `step-config: ${key} ${current}→${result.value} (by ${by}, session=${sid})`,
+  );
+};
+
+// [LAW:one-source-of-truth] The gated undo for `persist`: clears one
+// config-overrides key, restoring the user-file/bundled-default value on the
+// next reload. Gated by key MEMBERSHIP (listConfigKeys) rather than a value
+// domain — there is no value to validate, only a legitimate target to clear.
+const resetConfig: VerbHandler = (value, ctx) => {
+  const [sessionId = "", key = ""] = decodeWire(() => decodeSegments(value));
+  const sid = requireSessionId(sessionId);
+  if (!key || !listConfigKeys().includes(key)) {
+    throw new BadVerbArgs(
+      `reset-config: unknown config key "${key}" (have: ${listConfigKeys().join(", ")})`,
+    );
+  }
+  clearConfigOverride(configOverridesPath(), key, ctx.dlog);
+  ctx.dlog("info", `reset-config: ${key} (session=${sid})`);
+};
+
 // ─── Registry ───────────────────────────────────────────────────────────────
 
 // [LAW:one-source-of-truth] The LEAF verbs — every click effect that does real
@@ -382,6 +502,9 @@ const LEAF_VERBS = new Map<string, VerbHandler>([
   [VERB_OPEN_VSCODE, openVscode],
   [VERB_SET_STATE, setState],
   [VERB_STEP_STATE, stepState],
+  [VERB_SET_CONFIG, setConfig],
+  [VERB_STEP_CONFIG, stepConfig],
+  [VERB_RESET_CONFIG, resetConfig],
   [VERB_SHOW_CONFIG_ERROR, showConfigError],
   [VERB_SHOW_CONFIG_WARNING, showConfigWarning],
   [VERB_TOOLBAR_TOGGLE, toolbarToggle],
@@ -413,12 +536,16 @@ const dispatch: VerbHandler = (rawValue, ctx) => {
   let sessionId: string | null = null;
   for (const { verb, value } of parseEffects(rawValue)) {
     // Extract session ID from the first session-bearing effect for error display.
-    // set-state, step-state, and toolbar-toggle all carry the session id as their
-    // first segment, so a failing step surfaces in the bar like any other.
+    // set-state, step-state, set-config, step-config, reset-config, and
+    // toolbar-toggle all carry the session id as their first segment, so a
+    // failing step surfaces in the bar like any other.
     if (
       !sessionId &&
       (verb === VERB_SET_STATE ||
         verb === VERB_STEP_STATE ||
+        verb === VERB_SET_CONFIG ||
+        verb === VERB_STEP_CONFIG ||
+        verb === VERB_RESET_CONFIG ||
         verb === VERB_TOOLBAR_TOGGLE)
     ) {
       const parts = decodeSegments(value);