@promptctl/cc-candybar 1.25.0 → 1.27.0

package/src/dsl/render.ts

@@ -11,7 +11,7 @@
 // the input values (kind discriminators, layout length, palette presence)
 // govern output, not whether operations run.
 
-import type { RichText, PaletteResolver, ThemeKey } from "@promptctl/rich-js";
+import type { RichText, Palette, ThemeKey } from "@promptctl/rich-js";
 import { ColorSpec, Style, lighten, IDENTITY } from "@promptctl/rich-js";
 import type { Engine, Template } from "@promptctl/go-template-js";
 import type {
@@ -21,6 +21,8 @@ import type {
   LayoutNode,
 } from "../config/dsl-types.js";
 import { HUE_STEP_VAR } from "../config/dsl-types.js";
+import { perConfigDomainsFor } from "../config/option-domain.js";
+import { PRESET_FLOOR, presetNames, presetRoot } from "../config/presets.js";
 import type { VariableStore } from "../var-system/store.js";
 import type { SourceRegistry } from "../var-system/sources.js";
 import {
@@ -30,11 +32,12 @@ import {
 } from "../var-system/sources.js";
 import type { BuildLineOptions } from "../render/strip.js";
 import { DEFAULT_PADDING, renderStripCells } from "../render/strip.js";
-import { resolverForThemeName } from "../themes/index.js";
+import { paletteForThemeName } from "../themes/index.js";
 import { buildScope } from "../template-engine/scope.js";
 import {
   createCcCandybarEngine,
   evaluateWhen,
+  resolveSegmentColors,
 } from "../template-engine/index.js";
 import {
   compileActions,
@@ -47,6 +50,11 @@ import {
   collectMenuDrops,
   type MenuRuntime,
 } from "../render/menu.js";
+import {
+  createActiveSegmentRef,
+  type ActiveSegmentRef,
+} from "../render/active-segment.js";
+import { segmentColorFuncs } from "../render/segment-color.js";
 // [LAW:one-way-deps] The node-type registry sits below this driver: it owns the
 // compiled node shapes + each kind's compile/render, dispatched via nodeType().
 // render.ts threads the recursion (compileChild/renderChild) + the hue counter in
@@ -71,14 +79,27 @@ import {
 // owns node behavior); this driver only assembles + walks them.
 export interface CompiledConfig {
   readonly segments: CompiledSegments;
-  readonly root: CompiledNode;
-  // [LAW:locality-or-seam] The menu runtime the engine's `menu` func closes over,
-  // surfaced here so renderDsl can publish each segment's placement into it before
-  // that segment's template evaluates. One instance per compiled config; its
-  // `current` is mutated synchronously within a single renderDsl walk (renders are
-  // sequential + synchronous, so no cross-render leak) — the spatial cousin of the
-  // hue cursor, one owner. [LAW:no-ambient-temporal-coupling]
+  // [LAW:dataflow-not-control-flow] EVERY preset's layout, compiled up front and
+  // keyed by preset name — the render selects one by name rather than compiling
+  // per session. This is the same move `looks` makes one level down (every
+  // look's ThemeKey is resolved at load; the render picks one), and it is what
+  // lets a per-SESSION preset pick ride a per-ENTRY compilation: one RenderCache
+  // entry serves many sessions, so nothing session-shaped may be compiled here.
+  // Total over `presetNames` — every selectable name, floor included — so the
+  // lookup needs no absent case. A preset declaring no `root` of its own maps
+  // to the config's own compiled root: the identity element, not a special
+  // case.
+  readonly roots: ReadonlyMap<string, CompiledNode>;
+  // [LAW:locality-or-seam] The menu runtime the engine's `menu` func closes over.
   readonly menuRuntime: MenuRuntime;
+  // [LAW:one-source-of-truth] The single "which segment is rendering" record
+  // every segment-scoped template function reads — the menu's identity, the
+  // `color` func's palette, the `bgOf` func's background. Surfaced here so the
+  // walk can publish into it. One instance per compiled config; mutated
+  // synchronously within a single renderDsl walk (renders are sequential +
+  // synchronous, so no cross-render leak) — the spatial cousin of the hue
+  // cursor, one owner. [LAW:no-ambient-temporal-coupling]
+  readonly activeSegment: ActiveSegmentRef;
   // [LAW:types-are-the-program] Variable declaration failures that did NOT
   // prevent the config from loading (type mismatches, bad defaults). The
   // affected variables are absent from the store; segments that reference them
@@ -296,31 +317,56 @@ export function registerDslConfig(
   // [LAW:single-enforcer] Forward the caller's clock (the daemon's `() => new
   // Date()`, a test's frozen clock) to the one engine. Omitted ⇒ undefined ⇒
   // createCcCandybarEngine applies its single default; no second default literal.
+  // [LAW:one-source-of-truth] ONE record for "which segment is rendering", read
+  // by every segment-scoped template function: `{{ menu }}` takes its identity
+  // from the name, `{{ color }}` its palette, `{{ bgOf }}` its background. A
+  // per-feature pointer would let two features disagree about which segment is
+  // current. Built before the engine so the funcs can close over it; `current`
+  // stays null until a render walk publishes one.
+  const activeSegment = createActiveSegmentRef();
   // [LAW:locality-or-seam] The menu runtime shares the action runtime (a menu's
-  // glyph + body resolve from the same compiled table + store) and carries the
-  // walk-published current placement. Built before the engine so the `menu` func
-  // can close over it; `current` stays null until a render walk publishes one.
+  // glyph + body resolve from the same compiled table + store) and reads the
+  // active segment through the shared record above.
   const menuRuntime: MenuRuntime = {
     action: actionRuntime,
-    current: null,
+    activeSegment,
   };
   // [LAW:one-source-of-truth] The config's look names — the one PER-CONFIG
-  // option domain. Computed once here and fed to BOTH consumers (the compiled
-  // set-option domains below and the `looks()` binding), so the rendered
-  // options, a hand-authored `range looks`, and the derived click gate (which
-  // reads the same config in deriveActionValidators) trace to one map.
+  // option domain. Fed to every consumer (the `looks()` binding below, and —
+  // via perConfigDomainsFor, the SAME construction cross-ref.ts and
+  // state-validators.ts use — the compiled set-option domains), so the
+  // rendered options, a hand-authored `range looks`, and the derived click
+  // gate (which reads the same config in deriveActionValidators) trace to
+  // one source.
   const lookNames = Object.keys(config.looks);
+  const presetOptions = presetNames(config.presets);
+  const perConfigDomains = perConfigDomainsFor(config);
   const engine = createCcCandybarEngine(
-    undefined,
     {
       ...actionFuncs(actionRuntime),
       ...pickerFuncs(actionRuntime),
       ...menuFuncs(menuRuntime),
+      // [LAW:one-source-of-truth] `{{ color }}` reads the palette of the
+      // segment currently rendering — the same palette its `bg:`/`fg:` resolve
+      // from, published by the walk. Binding it to a palette captured HERE
+      // (registration runs once per config load, renders happen per tick) was
+      // the two-clocks bug this seam exists to close: a session theme click, a
+      // look, or a per-segment hue rotation moved a segment's background while
+      // every in-body color stayed where it was, so one segment painted from
+      // two palettes at once. Reading live costs nothing structurally — FuncMap
+      // bodies run at evaluate time, so parse-once/evaluate-many is untouched.
+      // `{{ bgOf }}` rides the same record. [LAW:rich-js-owns-color-math]
+      ...segmentColorFuncs(activeSegment),
       // [LAW:one-type-per-behavior] The per-config sibling of the static
       // themes()/styles() bindings (template-engine/funcs.ts): zero-arg
       // projection of the "looks" option domain. Injected here — not in the
       // static FuncMap — because the domain is this config's looks block.
       looks: { fn: () => lookNames, argTypes: [] },
+      // The presets domain's twin of the binding above — same per-config
+      // reason, same shape. A hand-authored `range presets` and a
+      // `{{ menu "applyPreset" }}` therefore enumerate the same names the
+      // derived click gate admits.
+      presets: { fn: () => presetOptions, argTypes: [] },
     },
     opts?.clock,
   );
@@ -363,7 +409,7 @@ export function registerDslConfig(
     parse,
     config.actions,
     stateKeyToVar,
-    lookNames,
+    perConfigDomains,
   );
 
   // [LAW:dataflow-not-control-flow] One variable failing to declare does not
@@ -427,9 +473,9 @@ export function registerDslConfig(
       // per-render basePalette; folding globals.palette in here too would freeze
       // it per segment and the stale copy would shadow basePalette, so a session
       // theme change could never recolor the bar.
-      paletteResolver:
+      palette:
         seg.palette !== undefined
-          ? resolverForThemeName(seg.palette)
+          ? paletteForThemeName(seg.palette)
           : undefined,
     };
   }
@@ -463,9 +509,25 @@ export function registerDslConfig(
     return nodeType(node.kind).compile(node, cctx);
   };
 
+  // [LAW:one-source-of-truth] One compiled tree per declared preset, built
+  // through the SAME compileNode the config's own root goes through —
+  // `presetRoot` resolves the fragment's `root` or falls back to the config's,
+  // so the floor preset (the empty fragment) needs no arm and no absent case
+  // downstream.
+  // Keyed by the SAME domain the menu renders and the click gate admits, so
+  // every selectable name has a compiled tree [LAW:one-source-of-truth].
+  const roots = new Map<string, CompiledNode>();
+  for (const name of presetOptions) {
+    // The path travels WITH the tree, so a preset that stages the config's own
+    // root diagnoses under `root` — the place its author actually wrote it.
+    const { node, path } = presetRoot(config, name);
+    roots.set(name, compileNode(node, path));
+  }
+
   return {
     segments: compiled,
-    root: compileNode(config.root, "root"),
+    roots,
+    activeSegment,
     menuRuntime,
     loadWarnings,
   };
@@ -545,24 +607,44 @@ export interface RenderObservers {
   readonly onSegmentError?: (segName: string, message: string) => void;
 }
 
+// [LAW:locality-or-seam] The per-render RESOLUTION the caller performs and hands
+// down — the values that are neither config (compiled once) nor payload (input
+// data), but the session's live choices resolved against the config: which
+// theme-adaptation, which preset. Bundled as ONE named bag for exactly the
+// reason RenderObservers is: `look` arrived as a positional tail, `preset` would
+// have been a second one, and the next resolution a third — each a signature
+// every caller re-counts. A new per-render choice is now one field here.
+//
+// Both fields default to their domain's own identity element, so an omitting
+// caller (a compile-only test, the demo) renders the unadapted config — a true
+// default, not a fallback [LAW:no-silent-failure].
+export interface RenderSelection {
+  // The resolved look, as a ThemeKey: effectiveLookName over SessionState/
+  // globals, then lookKeyByName — resolved by the caller exactly how basePalette
+  // is. IDENTITY is the "none" look. Composed with each segment's hue shift into
+  // ONE transposition.
+  readonly look?: ThemeKey;
+  // The resolved preset NAME: effectivePresetName over SessionState/globals,
+  // collapsed to the floor if stale. Selects which of `compiled.roots` this
+  // render walks. The name (not the fragment) crosses this seam because the
+  // fragment's two halves land in two different places — the root here, the
+  // globals in `opts`/the payload — and one name keeps them from disagreeing.
+  readonly preset?: string;
+}
+
 export function renderDsl(
   config: ValidatedConfig,
   compiled: CompiledConfig,
   store: VariableStore,
   registry: SourceRegistry,
   payload: unknown,
-  basePalette: PaletteResolver,
+  basePalette: Palette,
   opts: BuildLineOptions,
   observers?: RenderObservers,
-  // [LAW:dataflow-not-control-flow] The render's look (the session's chosen
-  // theme-adaptation), resolved per render by the caller — effectiveLookName
-  // over SessionState/globals, then lookKeyByName — exactly how basePalette
-  // resolves. IDENTITY is the domain's own no-adaptation element (the "none"
-  // look), so an omitting caller renders unadapted — a true default, not a
-  // fallback. Composed with each segment's hue shift into ONE transposition.
-  look: ThemeKey = IDENTITY,
+  selection?: RenderSelection,
 ): string {
   const { perSegmentSink, onSegmentError } = observers ?? {};
+  const { look = IDENTITY, preset = PRESET_FLOOR } = selection ?? {};
   // [LAW:one-source-of-truth] Inject the usable width as `term.cols` from the
   // SAME opts.width the strip wraps to (below), so a width-paginated widget reads
   // the exact wrap width — never a cached or independently-measured copy. This is
@@ -626,19 +708,34 @@ export function renderDsl(
       : undefined;
   };
 
-  // [LAW:single-enforcer] The menu seam, owned here. `beginSegment` publishes the
-  // segment name a `{{ menu }}` needs to derive its identity; `collectDrops` reads
-  // the open bodies the menus carried as metadata on their evaluated fragments and
-  // clears the published placement. The runtime's `current` is set/cleared around
-  // each segment eval by the walk only — never ambient.
-  // [LAW:no-ambient-temporal-coupling]
-  const beginSegment = (segName: string): void => {
-    compiled.menuRuntime.current = { segName };
-  };
-  const collectDrops = (
-    fragments: readonly RichText[],
-  ): readonly RichText[] => {
-    compiled.menuRuntime.current = null;
+  // [LAW:single-enforcer] The segment seam, owned here as a symmetric pair.
+  // `enterSegment` establishes everything a segment's templates may ask about
+  // themselves — the name `{{ menu }}` derives its identity from, the palette
+  // `{{ color }}` resolves against, the background `{{ bgOf }}` returns — and
+  // returns the resolved base Style. `exitSegment` collects the menu bodies the
+  // fragments carried as metadata and tears the record back down.
+  //
+  // [LAW:no-ambient-temporal-coupling] The record is set and cleared around each
+  // segment's evaluation by the walk ONLY, so "which segment am I in" is owned
+  // state with one writer, never ambient context a reader has to hope is
+  // current. Enter/exit are a pair by construction: every path that publishes
+  // goes through the first, every path that finishes goes through the second.
+  const enterSegment = (
+    segName: string,
+    palette: Palette,
+    bgTemplate: Template<RichText> | undefined,
+    fgTemplate: Template<RichText> | undefined,
+  ): Style =>
+    resolveSegmentColors(
+      compiled.activeSegment,
+      segName,
+      palette,
+      bgTemplate,
+      fgTemplate,
+      scope,
+    );
+  const exitSegment = (fragments: readonly RichText[]): readonly RichText[] => {
+    compiled.activeSegment.current = null;
     return collectMenuDrops(fragments);
   };
 
@@ -662,8 +759,8 @@ export function renderDsl(
       nextHueShift,
       perSegmentSink,
       onSegmentError,
-      beginSegment,
-      collectDrops,
+      enterSegment,
+      exitSegment,
       focusTint,
       lookupSegment,
       renderChild: renderNode,
@@ -676,7 +773,22 @@ export function renderDsl(
   // emit a "\n"-bearing string (FlexStrip width-overflow wrap); joining the per-
   // line results with "\n" splices those in place — byte-identical to serializing
   // each leaf row independently, since the cells and their order are unchanged.
-  return renderNode(compiled.root, true)
+  // [LAW:no-defensive-null-guards] The active preset's compiled tree. By the
+  // time a name reaches here it must be a member: effectivePresetName collapses
+  // unknown names to the floor, and every merged config declares the floor — so
+  // the throw is the loud failure for a broken invariant (a hand-built config
+  // missing the bundled presets block), never a silent fall back to some other
+  // arrangement than the one the bar's own label claims is active.
+  const root = compiled.roots.get(preset);
+  if (root === undefined) {
+    throw new Error(
+      `Preset "${preset}" has no compiled layout — registerDslConfig compiles ` +
+        `one per declared preset and effectivePresetName collapses unknown ` +
+        `names to "${PRESET_FLOOR}"; a miss here is merge/policy drift ` +
+        `(have: ${[...compiled.roots.keys()].join(", ")})`,
+    );
+  }
+  return renderNode(root, true)
     .map((line) => renderStripCells(line, opts))
     .join("\n");
 }

package/src/help-text.ts

@@ -0,0 +1,59 @@
+import { DISCLOSURE_GLYPH_CLOSED } from "./config/disclosure";
+
+// [LAW:effects-at-boundaries] Pure data, no I/O — index.ts owns the console.log
+// effect. Kept as its own module so the text is importable (and testable) without
+// pulling in index.ts's top-level `main()` call.
+// [LAW:one-source-of-truth] The disclosure glyph comes from config/disclosure.ts
+// (the same constant the theme/look picker itself renders with), so this text
+// can't drift from what a user actually sees on the bar.
+export const HELP_TEXT = `
+cc-candybar - Beautiful powerline statusline for Claude Code
+
+Usage: cc-candybar [options]
+
+Standalone Commands:
+  -h, --help               Show this help
+
+Debugging:
+  CC_CANDYBAR_DEBUG=1      Enable debug logging for troubleshooting
+
+Configuration:
+  Layout and segment options are defined in .cc-candybar.json5 (place in your
+  project dir, cwd, or ~/.config/cc-candybar/config.json5). Use CC_CANDYBAR_CONFIG
+  to point at a specific file. See the default config for all available options:
+    node dist/index.mjs debug --project-dir . --cwd .
+
+  The bundled default bar ships a settings drawer — no config needed. Click
+  ⚙ settings ${DISCLOSURE_GLYPH_CLOSED} on the bar to reveal a clickable theme/look picker and
+  other display options.
+
+Subcommands:
+  install                  One-shot setup: stages the runtime (native render
+                           binary + dist bundle) at a stable path, creates the
+                           URL handler app + cc-candybar:// scheme (macOS), and
+                           writes the staged entry as the statusLine command in
+                           ~/.claude/settings.json. Re-run to update.
+  install-url-handler      Just stage the runtime and create + register the URL
+                           handler app (macOS only).
+  url-handle URL           Internal — invoked by the URL handler app on
+                           cmd-click. Parses cc-candybar://<verb>/<value> and
+                           dispatches (currently: copy to clipboard).
+  daemon-stats [--json]    Query the running daemon for runtime stats:
+                           uptime, RSS, cache hit rates, watcher count,
+                           request totals. Does not spawn a daemon.
+
+Config tooling:
+  check [config-file]      Validate a config on the full render pipeline (parse
+                           → merge → validate → register → render) with no
+                           daemon. With no path, checks the same file the daemon
+                           would load from here. Exit 0 clean (warnings on
+                           stderr), 1 invalid, 2 unreadable. "lint" is an alias.
+  schema                   Print the JSON Schema for the config file shape
+                           (.cc-candybar.json5). Point an editor's $schema at it
+                           for autocomplete + structural validation.
+  vars [--json]            Declared variables: source kind, value, last error.
+  segments [--json]        Segment templates and their last rendered output.
+  config [--json]          The effective merged config. (All three query the
+                           running daemon; none spawn one.)
+
+`;

package/src/index.ts

@@ -15,6 +15,7 @@ import { runSchema } from "./config/cli";
 import { runCheck } from "./check";
 import { obtainDaemonKick } from "./daemon/acquire";
 import { planOutcome } from "./render/outcome-plan";
+import { HELP_TEXT } from "./help-text";
 
 // Read terminal width from the live shell context (no subprocess). Returns
 // undefined when nothing reliable is available; the daemon falls back to its
@@ -36,53 +37,7 @@ function detectTermCols(): number | undefined {
 }
 
 function showHelpText(): void {
-  console.log(`
-cc-candybar - Beautiful powerline statusline for Claude Code
-
-Usage: cc-candybar [options]
-
-Standalone Commands:
-  -h, --help               Show this help
-
-Debugging:
-  CC_CANDYBAR_DEBUG=1      Enable debug logging for troubleshooting
-
-Configuration:
-  Layout and segment options are defined in .cc-candybar.json5 (place in your
-  project dir, cwd, or ~/.config/cc-candybar/config.json5). Use CC_CANDYBAR_CONFIG
-  to point at a specific file. See the default config for all available options:
-    node dist/index.mjs debug --project-dir . --cwd .
-
-Subcommands:
-  install                  One-shot setup: stages the runtime (native render
-                           binary + dist bundle) at a stable path, creates the
-                           URL handler app + cc-candybar:// scheme (macOS), and
-                           writes the staged entry as the statusLine command in
-                           ~/.claude/settings.json. Re-run to update.
-  install-url-handler      Just stage the runtime and create + register the URL
-                           handler app (macOS only).
-  url-handle URL           Internal — invoked by the URL handler app on
-                           cmd-click. Parses cc-candybar://<verb>/<value> and
-                           dispatches (currently: copy to clipboard).
-  daemon-stats [--json]    Query the running daemon for runtime stats:
-                           uptime, RSS, cache hit rates, watcher count,
-                           request totals. Does not spawn a daemon.
-
-Config tooling:
-  check [config-file]      Validate a config on the full render pipeline (parse
-                           → merge → validate → register → render) with no
-                           daemon. With no path, checks the same file the daemon
-                           would load from here. Exit 0 clean (warnings on
-                           stderr), 1 invalid, 2 unreadable. "lint" is an alias.
-  schema                   Print the JSON Schema for the config file shape
-                           (.cc-candybar.json5). Point an editor's $schema at it
-                           for autocomplete + structural validation.
-  vars [--json]            Declared variables: source kind, value, last error.
-  segments [--json]        Segment templates and their last rendered output.
-  config [--json]          The effective merged config. (All three query the
-                           running daemon; none spawn one.)
-
-`);
+  console.log(HELP_TEXT);
 }
 
 async function main(): Promise<void> {

package/src/install/index.ts

@@ -7,6 +7,7 @@ import { tryClickViaDaemon } from "../daemon/client";
 import type { PermanentOutcome } from "../daemon/client-transport";
 import { obtainDaemonKick } from "../daemon/acquire";
 import { URL_SCHEME, VERB_COPY } from "../click/wire";
+import { DISCLOSURE_GLYPH_CLOSED } from "../config/disclosure";
 
 // [LAW:one-source-of-truth] Replaced at build time by tsdown's `define` option
 // from package.json — the single version stamp install output reports.
@@ -440,6 +441,21 @@ function formatPermanent(outcome: PermanentOutcome): string {
   }
 }
 
+// [LAW:effects-at-boundaries] Pure string builder — runInstall performs the
+// actual write. Kept separate so the message content is testable without
+// driving the full (fs + Launch Services) install side effects.
+// [LAW:one-source-of-truth] The disclosure glyph comes from config/disclosure.ts,
+// the same constant the theme/look picker itself renders with, so this tip
+// can't drift from what the bundled default bar actually shows.
+function installSuccessMessage(): string {
+  return (
+    `✓ install complete.\n` +
+    `  Restart Claude Code to pick up the new statusline.\n` +
+    `  Tip: the default bar has a settings drawer — click ⚙ settings\n` +
+    `  ${DISCLOSURE_GLYPH_CLOSED} to reveal a clickable theme/look picker and other display options.\n`
+  );
+}
+
 export function runInstall(rendererArgs: string[]): void {
   const force = rendererArgs.includes("--force");
   const filteredArgs = rendererArgs.filter((a) => a !== "--force");
@@ -459,10 +475,7 @@ export function runInstall(rendererArgs: string[]): void {
 
   updateClaudeSettings(staged.binPath, argsToInstall, force);
 
-  process.stdout.write(`✓ install complete.\n`);
-  process.stdout.write(
-    `  Restart Claude Code to pick up the new statusline.\n`,
-  );
+  process.stdout.write(installSuccessMessage());
 }
 
 function updateClaudeSettings(
@@ -529,4 +542,5 @@ export const __test__ = {
   resolveRenderEntry,
   stageFile,
   stagedEntryKind,
+  installSuccessMessage,
 };