@promptctl/cc-candybar 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.3.0",
+  "version": "1.4.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,10 +91,10 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.3.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.3.0",
-    "@promptctl/cc-candybar-linux-x64": "1.3.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.3.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.4.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.4.0",
+    "@promptctl/cc-candybar-linux-x64": "1.4.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.4.0"
   },
   "pnpm": {
     "supportedArchitectures": {

package/schema/cc-candybar.schema.json

@@ -25,6 +25,13 @@
         },
         "palette": {
           "type": "string"
+        },
+        "style": {
+          "enum": [
+            "powerline",
+            "capsule",
+            "plain"
+          ]
         }
       },
       "additionalProperties": false

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

@@ -437,6 +437,18 @@ export const DEFAULT_DSL_CONFIG = {
       type: "number",
       default: 0,
     },
+
+    // ── Style picker state (the live powerline-shape switcher) ───────────────
+    // [LAW:one-source-of-truth] `activeStyle` reads the SAME "style" SessionState
+    // key the daemon resolves into the strip joiner per render (see
+    // effectiveStripStyle wiring in src/daemon/server.ts) — the picker's write
+    // and the render's read are one value. Empty default ⇒ the daemon's
+    // "powerline" floor is in effect and styleControl shows "(default)".
+    activeStyle: { kind: "state", key: "style", default: "" },
+    // The style menu's page cursor: −1 closed / 0..N open, mirroring how a theme
+    // picker's page key gates its reveal row. The stylePage action declares the
+    // int gate; this var reads it back for the reveal `when`.
+    stylePage: { kind: "state", key: "style-page", default: "-1" },
   },
 
   // ─── Segments ──────────────────────────────────────────────────────────────
@@ -623,25 +635,60 @@ export const DEFAULT_DSL_CONFIG = {
         " .metrics.sessionDuration .metrics.messageCount" +
         " .metrics.linesAdded .metrics.linesRemoved }}",
     },
+    // Style control — the powerline-shape switcher's trigger. [LAW:locality-or-
+    // seam] The ✦ glyph + current-style label is the REPRESENTATION; the
+    // `openStyleMenu` action is the BEHAVIOR; the name is the seam. Shows the
+    // active shape (or "(default)" when unset) and a ▸ that opens the picker
+    // row. [LAW:dataflow-not-control-flow] No display state from the provider —
+    // the label is the one "style" value the click writes and the render reads.
+    styleControl: {
+      template:
+        "✦ {{ if .activeStyle }}{{ .activeStyle }}{{ else }}(default){{ end }} " +
+        '{{ action "openStyleMenu" "▸" }}',
+      bg: "surface",
+      fg: "foreground",
+    },
+    // The expanded style picker: one full-width page (paged=false) over the
+    // `applyStyle` option domain — the 3 powerline shapes. closeOnPick folds a
+    // page-reset into the apply, so a pick reshapes the bar and closes the row
+    // in one click. The active shape is marked by the picker helper.
+    stylePicker: {
+      template: '{{ picker "applyStyle" "stylePage" true false }}',
+      bg: "surface",
+      fg: "foreground",
+    },
   },
 
-  // Default layout — a single horizontal row of segment refs.
-  // A-grammar equivalent: { h: ["directory","git","model","session","today","context","toolbar"] }
-  // [LAW:one-source-of-truth] The bundled default now authors the same terse
-  // surface every user config lowers to, so the default is the reference spelling.
-  // Adding rows = wrapping in { kind:"container", direction:"vertical", children:[...] };
-  // every segment is already declared above.
+  // Default layout — the canonical LayoutNode tree (`satisfies DslConfig`
+  // requires the lowered form here; the terse Option-A `{ h/v/seg }` grammar is
+  // the loader's authoring surface for user JSON, not this typed literal).
+  // [LAW:dataflow-not-control-flow] Two rows: an always-on control row, and a
+  // picker reveal row that EXISTS only while the style menu cursor is ≥ 0 — the
+  // row's presence is a value test on stylePage, not a branch in render code.
+  // The picker itself draws the ✕/←/→ affordances from the page + term width.
   root: {
     kind: "container",
-    direction: "horizontal",
+    direction: "vertical",
     children: [
-      { kind: "segment", name: "directory" },
-      { kind: "segment", name: "git" },
-      { kind: "segment", name: "model" },
-      { kind: "segment", name: "session" },
-      { kind: "segment", name: "today" },
-      { kind: "segment", name: "context" },
-      { kind: "segment", name: "toolbar" },
+      {
+        kind: "container",
+        direction: "horizontal",
+        children: [
+          { kind: "segment", name: "directory" },
+          { kind: "segment", name: "git" },
+          { kind: "segment", name: "model" },
+          { kind: "segment", name: "session" },
+          { kind: "segment", name: "today" },
+          { kind: "segment", name: "context" },
+          { kind: "segment", name: "toolbar" },
+          { kind: "segment", name: "styleControl" },
+        ],
+      },
+      {
+        kind: "segment",
+        name: "stylePicker",
+        when: "{{ ge (int .stylePage) 0 }}",
+      },
     ],
   },
 
@@ -664,6 +711,17 @@ export const DEFAULT_DSL_CONFIG = {
     copyDir: { copy: "{{ .current_dir }}" },
     openProject: { open: "{{ .project_dir }}" },
     openTranscript: { open: "{{ .transcript_path }}" },
+
+    // [LAW:locality-or-seam] The style picker's behaviors, decoupled by NAME
+    // from styleControl/stylePicker above. Three declarations, all gated by
+    // derivation (deriveActionValidators): openStyleMenu/stylePage write the
+    // page cursor (a literal page-open subsumed by the int gate); applyStyle
+    // writes the chosen shape, gated to the STRIP_STYLES allow-list because its
+    // value source is `from: "styles"`. The rendered click and the wire gate
+    // share that one source — a template cannot smuggle an un-gated style write.
+    openStyleMenu: { set: "style-page", to: "0" },
+    applyStyle: { set: "style", from: "styles" },
+    stylePage: { set: "style-page", int: true },
   },
 
   // [LAW:single-enforcer] / [LAW:one-source-of-truth] Display-formatting policy

package/src/config/dsl-types.ts

@@ -14,6 +14,7 @@
 // references it here. The dependency is one-way (this file → action.ts), never
 // the reverse, so that shape can be lifted out without a cycle.
 import type { ActionDecl } from "./action.js";
+import type { StripStyle } from "../themes/policy.js";
 
 // [LAW:types-are-the-program] Three stages, three names.
 //
@@ -180,6 +181,14 @@ export interface Globals {
   // `sessionState.theme ?? globals.palette ?? default`, and a per-segment
   // `palette` is an explicit override that ignores the session theme.
   readonly palette?: string;
+
+  // [LAW:one-type-per-behavior] The config default for the powerline cap/
+  // separator SHAPE — the exact twin of `palette` one dimension over: the
+  // daemon resolves the live strip style per render as
+  // `sessionState.style ?? globals.style ?? "powerline"` (effectiveStripStyle),
+  // so a style click reshapes the bar live and a config can set the default
+  // shape without an edit-per-session.
+  readonly style?: StripStyle;
 }
 
 // [LAW:one-type-per-behavior] One discriminated union covers every source

package/src/config/loader/globals.ts

@@ -4,7 +4,9 @@
 // add a key to GLOBALS_SCHEMA and Globals; the engine does the rest.
 
 import { type Globals } from "../dsl-types.js";
+import { STRIP_STYLES } from "../../themes/policy.js";
 import {
+  optionalEnumSpec,
   optionalStringSpec,
   paletteSpec,
   record,
@@ -23,6 +25,10 @@ const GLOBALS_SCHEMA: RecordSchema<Globals> = {
     default_separator: optionalStringSpec(),
     default_truncate_marker: optionalStringSpec(),
     palette: paletteSpec(),
+    // [LAW:types-are-the-program] The strip style is a CLOSED enum (the powerline
+    // shapes the joiner can render), unlike the open-ended palette NAME — so it
+    // validates by membership and emits a JSON-Schema `enum`.
+    style: optionalEnumSpec(STRIP_STYLES),
   },
 };
 

package/src/daemon/server.ts

@@ -39,7 +39,11 @@ 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 { effectiveThemeName, resolverForThemeName } from "../themes/index.js";
+import {
+  effectiveStripStyle,
+  effectiveThemeName,
+  resolverForThemeName,
+} from "../themes/index.js";
 import {
   renderStripCells,
   DEFAULT_TERMINAL_WIDTH,
@@ -753,6 +757,16 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
             entry.state.config.globals.palette,
           ),
         );
+        // [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,
+        );
         // [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

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

@@ -24,7 +24,7 @@
 // numeric stepper with int-range bounds), this same shape extends — the
 // validator becomes the parsing boundary, the verb body the dataflow.
 
-import { listResolvablePaletteNames, STYLE_ORDER } from "../../themes/policy";
+import { listResolvablePaletteNames, STRIP_STYLES } from "../../themes/policy";
 import type { ActionDecl, OptionSource } from "../../config/action";
 import type { DslConfig } from "../../config/dsl-types";
 
@@ -88,13 +88,13 @@ export type DerivedValidatorSpec =
 //
 // [LAW:single-enforcer] Each validator's accepted-set is one constant
 // lookup structure — a Set for O(1) `has` (matching the BOOLEAN_*
-// validators below). The theme registry (rich-js THEMES) and STYLE_ORDER
+// validators below). The theme registry (rich-js THEMES) and STRIP_STYLES
 // are module-init-static, so caching at module load is correct by
 // construction; the (list, set) pair is built from the same source so
 // the error-message ordering and the lookup membership cannot drift.
 const RESOLVABLE_THEMES_LIST: readonly string[] = listResolvablePaletteNames();
 const RESOLVABLE_THEMES: ReadonlySet<string> = new Set(RESOLVABLE_THEMES_LIST);
-const RESOLVABLE_STYLES: ReadonlySet<string> = new Set(STYLE_ORDER);
+const RESOLVABLE_STYLES: ReadonlySet<string> = new Set(STRIP_STYLES);
 
 const validateTheme: KeyValidator = (raw) => {
   if (!raw) return { ok: false, reason: "theme name is required" };
@@ -112,7 +112,7 @@ const validateStyle: KeyValidator = (raw) => {
   if (!RESOLVABLE_STYLES.has(raw)) {
     return {
       ok: false,
-      reason: `unknown style "${raw}" (have: ${STYLE_ORDER.join(", ")})`,
+      reason: `unknown style "${raw}" (have: ${STRIP_STYLES.join(", ")})`,
     };
   }
   return { ok: true, value: raw };
@@ -446,7 +446,7 @@ export function makeRangeValidator(
 // style validators consult — the rendered options and the derived gate cannot
 // diverge because there is no second enumeration.
 function optionValuesFor(src: OptionSource): readonly string[] {
-  return src === "themes" ? RESOLVABLE_THEMES_LIST : STYLE_ORDER;
+  return src === "themes" ? RESOLVABLE_THEMES_LIST : STRIP_STYLES;
 }
 
 // [LAW:types-are-the-program] Collapse one key's spec contributions into the

package/src/demo/dsl.ts

@@ -27,6 +27,7 @@ import {
 } from "../config/dsl-loader.js";
 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, resolverForThemeName } from "../themes/index.js";
 import { registerDslConfig, renderDsl } from "../dsl/render.js";
@@ -75,7 +76,12 @@ const basePalette = resolverForThemeName(
 // registry, so dispose() must run even if registration or rendering throws —
 // otherwise those handles keep the process alive. try/finally guarantees it.
 const store = new VariableStore();
-const registry = new SourceRegistry(store);
+// [LAW:no-silent-failure] An EMPTY SessionState — `kind: "state"` variables
+// (the default config's style picker, any interactive config) require one at
+// registration; without it declareState fails and the segment renders an error
+// cell. The demo never clicks, so an empty store is correct: every state var
+// resolves to its declared default (closed pickers, "(default)" labels).
+const registry = new SourceRegistry(store, "", undefined, new SessionState());
 try {
   const compiled = registerDslConfig(config, registry, {
     cwd: process.cwd(),

package/src/render/action.ts

@@ -26,7 +26,7 @@ import type { VariableStore } from "../var-system/store.js";
 import { toString as varToString } from "../var-system/types.js";
 import { buildScope } from "../template-engine/scope.js";
 import type { ActionDecl, OptionSource } from "../config/action.js";
-import { listResolvablePaletteNames, STYLE_ORDER } from "../themes/policy.js";
+import { listResolvablePaletteNames, STRIP_STYLES } from "../themes/policy.js";
 import {
   effectsUrl,
   VERB_COPY,
@@ -107,7 +107,7 @@ export type CompiledActions = ReadonlyMap<string, CompiledActionDecl>;
 // options and the gate cannot diverge. The render-side resolver (the daemon's
 // validator-derivation has its own that must agree, both reading themes/policy).
 export function optionDomain(src: OptionSource): readonly string[] {
-  return src === "themes" ? listResolvablePaletteNames() : STYLE_ORDER;
+  return src === "themes" ? listResolvablePaletteNames() : STRIP_STYLES;
 }
 
 // [LAW:locality-or-seam] The runtime holder the `action` template function closes

package/src/render/strip.ts

@@ -10,6 +10,7 @@ import {
   type Joiner,
   type ColorSystemSpec,
 } from "@promptctl/rich-js";
+import type { StripStyle } from "../themes/policy.js";
 
 export interface RenderedSegmentLike {
   type: string;
@@ -18,7 +19,11 @@ export interface RenderedSegmentLike {
   fgHex?: string;
 }
 
-export type StripStyle = "powerline" | "capsule" | "plain";
+// [LAW:one-source-of-truth] `StripStyle` and its value list live in
+// themes/policy.ts (the style-identifier policy module, importable by the
+// option-source machinery without a render→template-engine cycle). Re-exported
+// here so render-layer consumers can keep importing it from the strip module.
+export type { StripStyle };
 
 // [LAW:one-source-of-truth] Raw terminal cols we assume when the wire
 // didn't give us one (older client, env-stripped spawn). RAW — not
@@ -38,13 +43,22 @@ export interface BuildLineOptions {
 }
 
 function pickJoiner(style: StripStyle, separator?: string): Joiner {
-  // [LAW:dataflow-not-control-flow] joiner choice is data-driven; one branch
-  // per shape, no nested conditionals.
-  if (style === "capsule") return new CapsuleJoiner();
-  if (style === "plain") {
-    return new PlainJoiner(separator !== undefined ? { separator } : {});
+  // [LAW:dataflow-not-control-flow] joiner choice is data-driven; one arm per
+  // shape. [LAW:types-are-the-program] Total over StripStyle — the `never`
+  // default makes adding a STRIP_STYLES member a compile error here until it
+  // gets a joiner, so the picker's domain can never offer an unrenderable shape.
+  switch (style) {
+    case "capsule":
+      return new CapsuleJoiner();
+    case "plain":
+      return new PlainJoiner(separator !== undefined ? { separator } : {});
+    case "powerline":
+      return new PowerlineJoiner();
+    default: {
+      const _exhaustive: never = style;
+      return _exhaustive;
+    }
   }
-  return new PowerlineJoiner();
 }
 
 function toCell(seg: RenderedSegmentLike): RichText {

package/src/template-engine/funcs.ts

@@ -16,22 +16,22 @@ import {
   formatModelName,
   shortenModelName,
 } from "../utils/formatters.js";
-import { listResolvablePaletteNames, STYLE_ORDER } from "../themes/policy.js";
+import { listResolvablePaletteNames, STRIP_STYLES } from "../themes/policy.js";
 
 // [LAW:one-source-of-truth] The DSL `themes()` and `styles()` bindings
 // project the SAME canonical sources the set-state validator consults
-// (listResolvablePaletteNames / STYLE_ORDER). A picker (or a config that
+// (listResolvablePaletteNames / STRIP_STYLES). A picker (or a config that
 // `range`s over themes() to emit OSC-8 cells) iterates the allow-list the
 // validator will enforce on the resulting click — the list and the gate cannot
 // diverge because there is no second list.
 //
 // Module-init caching is correct by construction: rich-js THEMES is a
 // static import (no dynamic palette registration at runtime) and
-// STYLE_ORDER is a const array. The "reactivity" requirement from the
+// STRIP_STYLES is a const array. The "reactivity" requirement from the
 // ticket is satisfied vacuously — the lists never change during a
 // daemon lifetime, so a cached snapshot IS the current truth.
 const THEMES_LIST: readonly string[] = listResolvablePaletteNames();
-const STYLES_LIST: readonly string[] = [...STYLE_ORDER];
+const STYLES_LIST: readonly string[] = [...STRIP_STYLES];
 
 // Normalize an engine-supplied numeric argument. The "number" argType admits
 // both number and bigint (per @promptctl/go-template-js); the underlying

package/src/themes/index.ts

@@ -6,12 +6,16 @@
 export {
   resolvePaletteName,
   effectiveThemeName,
+  effectiveStripStyle,
+  isStripStyle,
   listResolvablePaletteNames,
   listAvailableThemes,
   pickRandomTheme,
+  STRIP_STYLES,
   STYLE_ORDER,
   DISPLAY_STYLES,
 } from "./policy.js";
+export type { StripStyle } from "./policy.js";
 
 export {
   resolverForThemeName,

package/src/themes/policy.ts

@@ -55,8 +55,43 @@ export function listAvailableThemes(): string[] {
   return [...allNames].sort();
 }
 
-// --- Style identifiers ---
+// --- Powerline strip-style identifiers ---
 
+// [LAW:one-source-of-truth][LAW:types-are-the-program] The single canonical set
+// of powerline cap/separator shapes a render can take. The `StripStyle` type is
+// DERIVED from this const, so the picker's option domain, the SessionState
+// validator, the `styles()` template binding, and `pickJoiner`'s dispatch all
+// trace to one literal — adding a shape here forces a new `pickJoiner` arm at
+// compile time (the joiner switch is total over `StripStyle`). This is where the
+// drift between "what you can pick" and "what actually renders" is closed.
+export const STRIP_STYLES = ["powerline", "capsule", "plain"] as const;
+export type StripStyle = (typeof STRIP_STYLES)[number];
+
+// [LAW:types-are-the-program] The trust-boundary narrowing from a raw
+// SessionState string (or a config default) to the closed `StripStyle` union.
+export function isStripStyle(value: string): value is StripStyle {
+  return (STRIP_STYLES as readonly string[]).includes(value);
+}
+
+// The strip style a render should use, as data. [LAW:dataflow-not-control-flow]
+// [LAW:one-type-per-behavior] The exact shape of `effectiveThemeName`, one
+// dimension over: session choice over config default over the "powerline" floor,
+// no "if the session has a style" branch. A value outside the domain (a stale
+// SessionState entry from a prior option vocabulary) collapses to the floor —
+// `pickJoiner` would render it as powerline anyway, so the floor keeps the
+// returned type honest rather than silently widening.
+export function effectiveStripStyle(
+  sessionStyle: string | null,
+  globalsStyle: StripStyle | undefined,
+): StripStyle {
+  const chosen = sessionStyle ?? globalsStyle ?? "powerline";
+  return isStripStyle(chosen) ? chosen : "powerline";
+}
+
+// --- Legacy palette-preset identifiers (per-session random feature only) ---
+// [LAW:no-silent-failure] NOT the picker's style domain — these were the
+// pre-DSL bg/fg derivation presets, surviving only as the random pool for
+// session-random.ts. The interactive style picker resolves over STRIP_STYLES.
 export const STYLE_ORDER: readonly string[] = [
   "surface",
   "muted",