@promptctl/cc-candybar 1.26.0 → 1.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.26.0",
+  "version": "1.27.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",
@@ -86,14 +86,14 @@
     "tsx": "^4.21.0",
     "typescript": "^5.0.0",
     "@promptctl/go-template-js": "^0.7.0",
-    "@promptctl/rich-js": "^0.6.0",
+    "@promptctl/rich-js": "^0.7.0",
     "json5": "^2.2.3",
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.26.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.26.0",
-    "@promptctl/cc-candybar-linux-x64": "1.26.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.26.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.27.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.27.0",
+    "@promptctl/cc-candybar-linux-x64": "1.27.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.27.0"
   }
 }

package/schema/cc-candybar.schema.json

@@ -29,6 +29,9 @@
         "look": {
           "type": "string"
         },
+        "preset": {
+          "type": "string"
+        },
         "style": {
           "enum": [
             "powerline",
@@ -1141,10 +1144,20 @@
                 "type": "string"
               },
               "from": {
-                "enum": [
-                  "themes",
-                  "styles",
-                  "looks"
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "minItems": 1,
+                    "uniqueItems": true
+                  }
                 ]
               }
             },
@@ -1216,6 +1229,98 @@
             ],
             "additionalProperties": false
           },
+          {
+            "type": "object",
+            "properties": {
+              "persist": {
+                "type": "string"
+              },
+              "to": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "persist",
+              "to"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "persist": {
+                "type": "string"
+              },
+              "from": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "minItems": 1,
+                    "uniqueItems": true
+                  }
+                ]
+              }
+            },
+            "required": [
+              "persist",
+              "from"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "persist": {
+                "type": "string"
+              },
+              "min": {
+                "type": "integer"
+              },
+              "max": {
+                "type": "integer"
+              },
+              "by": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "persist",
+              "min",
+              "max",
+              "by"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "persist": {
+                "type": "string"
+              },
+              "cycle": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 2,
+                "uniqueItems": true
+              }
+            },
+            "required": [
+              "persist",
+              "cycle"
+            ],
+            "additionalProperties": false
+          },
           {
             "type": "object",
             "properties": {
@@ -1239,6 +1344,18 @@
               "open"
             ],
             "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "reset": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "reset"
+            ],
+            "additionalProperties": false
           }
         ]
       }
@@ -1265,6 +1382,78 @@
         "additionalProperties": false
       }
     },
+    "presets": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "root": {
+            "$ref": "#/definitions/LayoutNode"
+          },
+          "globals": {
+            "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 inside a preset — a preset 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
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "helpers": {
       "type": "object",
       "additionalProperties": {

package/src/check.ts

@@ -37,13 +37,15 @@ import {
   lookKeyByName,
   effectiveStripStyle,
 } from "./themes/policy.js";
-import { resolverForThemeName } from "./themes/palette-resolvers.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";
 
 // [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
@@ -60,16 +62,16 @@ const CHECK_WIDTH = 200;
 // field-name typo in the git/directory/metrics/budget branches slip through —
 // those branches only run when their data is present.
 //
-// `effectiveTheme` is threaded in exactly as the daemon threads it (server.ts
-// resolves effectiveThemeName once and feeds BOTH the payload's
-// `theme.effective` field and the basePalette below) [LAW:one-source-of-truth].
+// `effective` is threaded in exactly as the daemon threads it (server.ts
+// resolves one EffectiveGlobals struct per render and feeds BOTH the
+// payload's `*.effective` fields and BuildLineOptions/basePalette below)
+// [LAW:one-source-of-truth].
 //
 // test/example-configs.test.ts asserts rendered content against these literal
 // values (780s → "◷ 13m", cost $0.39, version 1.15.0, …); changing one here
 // fails that suite loudly rather than drifting silently.
 export function checkPayload(
-  effectiveTheme: string,
-  effectiveLook: string,
+  effective: EffectiveGlobals,
 ): Record<string, unknown> {
   const home = "/home/tester";
   const nowSec = Math.floor(Date.now() / 1000);
@@ -87,6 +89,7 @@ export function checkPayload(
     },
     git: {
       repoName: "cc-candybar",
+      repoUrl: "https://github.com/promptctl/cc-candybar",
       branch: "main",
       sha: "abc1234",
       ahead: 2,
@@ -116,8 +119,13 @@ export function checkPayload(
     weekly: { percentage: 21, resetsAt: nowSec + 5 * 86400 },
     cache: { expiresAt: nowSec + 15 * 60 },
     tmux: { session: "work" },
-    theme: { effective: effectiveTheme },
-    look: { effective: effectiveLook },
+    theme: { effective: effective.theme },
+    look: { effective: effective.look },
+    style: { effective: effective.style },
+    charset: { effective: effective.charset },
+    colorCompatibility: { effective: effective.colorCompatibility },
+    autoWrap: { effective: effective.autoWrap },
+    padding: { effective: effective.padding },
   };
 }
 
@@ -271,18 +279,30 @@ function loadRegisterRender(
     // validator registry, which a one-shot check has no wire to serve.
     deriveActionValidators(config);
 
-    // Fresh session (no clicked theme/style), so the session half of each
-    // resolution is null — the config default over the floor, exactly what the
-    // daemon renders for a session that has never clicked.
-    const effectiveTheme = effectiveThemeName(null, config.globals.palette);
-    // Same fresh-session shape one dimension over: no clicked look, so the
-    // config default over the "none" floor — exactly what the daemon renders
-    // for a session that has never clicked.
-    const effectiveLook = effectiveLookName(
+    // Fresh session (no clicked theme/style/look), so the session half of
+    // each resolution is null — the config default over the floor, exactly
+    // what the daemon renders for a session that has never clicked.
+    // [LAW:one-source-of-truth] The preset resolves first and its fragment's
+    // 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.look,
-      config.looks,
+      config.globals.preset,
+      config.presets,
     );
+    const globals = presetGlobals(config, preset);
+    const effective: EffectiveGlobals = {
+      preset,
+      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,
+      charset: globals.charset ?? DEFAULT_CHARSET,
+      colorCompatibility:
+        globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,
+    };
     // [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
@@ -296,22 +316,24 @@ function loadRegisterRender(
       compiled,
       store,
       registry,
-      checkPayload(effectiveTheme, effectiveLook),
-      resolverForThemeName(effectiveTheme),
+      checkPayload(effective),
+      paletteForThemeName(effective.theme),
       {
-        style: effectiveStripStyle(null, config.globals.style),
+        style: effective.style,
         width: CHECK_WIDTH,
-        colorCompatibility:
-          config.globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,
-        wrap: config.globals.autoWrap ?? DEFAULT_WRAP,
-        padding: config.globals.padding ?? DEFAULT_PADDING,
-        charset: config.globals.charset ?? DEFAULT_CHARSET,
+        colorCompatibility: effective.colorCompatibility,
+        wrap: effective.autoWrap,
+        padding: effective.padding,
+        charset: effective.charset,
       },
       {
         onSegmentError: (segName, message) =>
           segmentErrors.push(`segment "${segName}": ${message}`),
       },
-      lookKeyByName(config.looks, effectiveLook),
+      {
+        look: lookKeyByName(config.looks, effective.look),
+        preset: effective.preset,
+      },
     );
     if (segmentErrors.length > 0) {
       throw new Error(

package/src/click/wire.ts

@@ -50,6 +50,22 @@ export const VERB_SHOW_CONFIG_WARNING = "show-config-warning";
 // reads it at the cache-lookup boundary. Clicking a different config is a
 // side-effect isolated to the verb handler; the renderer only sees the result.
 export const VERB_LOAD_CONFIG = "load-config";
+// [LAW:one-source-of-truth] `persist`'s twin of set-state/step-state: writes
+// land in the daemon-owned config-overrides layer (never the hand-authored
+// config file), which RenderCache merges on top of the user file every
+// reload — the SAME file-watcher path a hand edit already takes
+// (candybar-config-engine-71o.2). Args: `[sessionId, key, value]` — the
+// sessionId is carried only for click.error surfacing, exactly like
+// set-state; the write itself is daemon-global, not session-scoped.
+export const VERB_SET_CONFIG = "set-config";
+// [LAW:types-are-the-program] A RELATIVE nudge to a bounded config-overrides
+// key (e.g. a padding stepper) — the config twin of step-state. Args:
+// `[sessionId, key, by]`.
+export const VERB_STEP_CONFIG = "step-config";
+// [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. Args: `[sessionId, key]`.
+export const VERB_RESET_CONFIG = "reset-config";
 
 // [LAW:types-are-the-program] An effect to EMIT: a verb plus its raw (unencoded)
 // positional args. The wire owns all encoding — callers never percent-encode.

package/src/config/action.ts

@@ -24,24 +24,26 @@
 // These are the shapes a picker draws options from and the set/copy/open/int
 // discriminator the loader and the validator-derivation match on.
 
-// [LAW:one-source-of-truth] The domain lists a picker draws options from. Same
-// canonical sources the `themes()`/`styles()`/`looks()` bindings and the
-// set-state validators consult — the rendered options and the derived gate
-// cannot diverge because there is no second enumeration. themes/styles are
-// static registry lists; "looks" is the one PER-CONFIG domain (the merged
-// `looks` block's names), so its resolution sites take the config's look names
-// as data rather than consulting a module constant.
-export type OptionSource = "themes" | "styles" | "looks";
-export const OPTION_SOURCES: readonly OptionSource[] = [
-  "themes",
-  "styles",
-  "looks",
-];
+// [LAW:one-source-of-truth] The domain a picker draws options from. Resolved
+// through option-domain.ts's registry — themes/styles are registry-backed
+// static lists, "looks" is the one PER-CONFIG domain (the merged `looks`
+// block's names, threaded as data rather than consulted from a module
+// constant), and an inline array is its own domain, needing no registration
+// at all. Re-exported here so ActionDecl stays self-contained to read.
+import type { OptionDomain } from "./option-domain.js";
+export type { OptionDomain } from "./option-domain.js";
 
 // [LAW:types-are-the-program] The top-level discriminator of an ActionDecl — the
 // click effect is keyed by which of these is present. The loader proves
 // exactly-one-of; the renderer and validator-derivation match with no fallthrough.
-export const ACTION_KEYS = ["set", "copy", "open"] as const;
+//
+// [LAW:one-source-of-truth] `persist` is `set`'s PERSISTENT twin
+// (candybar-config-engine-71o.2): `set` mutates per-session SessionState,
+// `persist` mutates the config's `globals` DEFAULT through the daemon-owned
+// overrides layer (never the hand-authored config file). `reset` clears one
+// persisted override — the gated undo `persist` needs, since a machine-owned
+// write with no way back would be a one-way ratchet.
+export const ACTION_KEYS = ["set", "persist", "copy", "open", "reset"] as const;
 export type ActionKey = (typeof ACTION_KEYS)[number];
 
 // [LAW:types-are-the-program] An ActionDecl is the click effect a named action
@@ -53,7 +55,9 @@ export type ActionKey = (typeof ACTION_KEYS)[number];
 //
 //   set + to            — write a literal value -> allow-list {to}
 //   set + from          — write the option the template binds at render
-//                         (a picker ranges the domain) -> allow-list {options}
+//                         (a picker ranges the domain — a registered name like
+//                         "themes", or an inline literal array) -> allow-list
+//                         {options}
 //   set + min/max/by    — write wrap(current ± by) clamped to [min,max]
 //                         (a stepper affordance) -> range [min,max]
 //   set + int           — write any integer the render binds (a paged cursor:
@@ -72,12 +76,20 @@ export type ActionKey = (typeof ACTION_KEYS)[number];
 //   copy                — copy templated text to the clipboard -> no gate
 //   open                — open a templated target in the editor -> no gate
 //
-// [LAW:one-source-of-truth] Only `set` writes SessionState, so only `set`
-// derives a validator. copy/open write nothing — they derive nothing. The
-// vocabulary grows by arms (a future `run`/`open-url`), not by validator plumbing.
+// [LAW:one-source-of-truth] `set` writes SessionState and `persist` writes
+// the config-overrides layer, so only those two derive a validator (through
+// the SAME shared registry algebra — see validator-registry.ts). copy/open/
+// reset write nothing SPEC-shaped (reset's target is gated by key membership,
+// not a value domain) — they derive nothing. The vocabulary grows by arms (a
+// future `run`/`open-url`), not by validator plumbing.
+//
+// [LAW:one-type-per-behavior] `persist` mirrors `set`'s four value-source
+// arms verbatim (to/from/min-max-by/cycle) MINUS `int`: an unbounded page
+// cursor is a UI-only paging concept (a picker's own navigation state) with
+// no meaning as a persisted config default.
 export type ActionDecl =
   | { readonly set: string; readonly to: string }
-  | { readonly set: string; readonly from: OptionSource }
+  | { readonly set: string; readonly from: OptionDomain }
   | {
       readonly set: string;
       readonly min: number;
@@ -86,13 +98,36 @@ export type ActionDecl =
     }
   | { readonly set: string; readonly int: true }
   | { readonly set: string; readonly cycle: readonly string[] }
+  | { readonly persist: string; readonly to: string }
+  | { readonly persist: string; readonly from: OptionDomain }
+  | {
+      readonly persist: string;
+      readonly min: number;
+      readonly max: number;
+      readonly by: number;
+    }
+  | { readonly persist: string; readonly cycle: readonly string[] }
   | { readonly copy: string }
-  | { readonly open: string };
+  | { readonly open: string }
+  | { readonly reset: string };
 
 // [LAW:dataflow-not-control-flow] Does this action write a SessionState key? A
 // `set` action composes a set-state click URL whose first segment is session.id;
-// copy/open embed none. One predicate the loader's session.id requirement folds
-// over — no per-arm branching at the callsite.
+// copy/open/persist/reset embed none. One predicate the loader's session.id
+// requirement folds over — no per-arm branching at the callsite.
 export function actionBindsSet(a: ActionDecl): boolean {
   return "set" in a;
 }
+
+// [LAW:dataflow-not-control-flow] Does this action write the config-overrides
+// layer? Mirrors actionBindsSet for the `persist` arm.
+export function actionBindsPersist(a: ActionDecl): boolean {
+  return "persist" in a;
+}
+
+// [LAW:dataflow-not-control-flow] Does this action clear a config-overrides
+// key? `reset` carries session.id on the wire too (for click-error surfacing,
+// same as set/persist), so it joins the same requirement.
+export function actionBindsReset(a: ActionDecl): boolean {
+  return "reset" in a;
+}