@promptctl/cc-candybar 1.25.0 → 1.27.0

package/src/render/action.ts

@@ -25,17 +25,17 @@ import type { FuncMap, Template } from "@promptctl/go-template-js";
 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,
-  STRIP_STYLES,
-  type StripStyle,
-} from "../themes/policy.js";
+import type { ActionDecl } from "../config/action.js";
+import { resolveOptionDomain } from "../config/option-domain.js";
+import type { StripStyle } from "../themes/policy.js";
 import {
   effectsUrl,
   VERB_COPY,
   VERB_OPEN_VSCODE,
+  VERB_RESET_CONFIG,
+  VERB_SET_CONFIG,
   VERB_SET_STATE,
+  VERB_STEP_CONFIG,
   VERB_STEP_STATE,
   type Effect,
 } from "../click/wire.js";
@@ -102,24 +102,65 @@ export type CompiledActionDecl =
       readonly members: readonly string[];
     }
   | { readonly kind: "copy"; readonly text: Template<RichText> }
-  | { readonly kind: "open"; readonly target: Template<RichText> };
+  | { readonly kind: "open"; readonly target: Template<RichText> }
+  // [LAW:one-source-of-truth] `persist`'s twin of the set-* kinds above,
+  // MINUS set-int (a page cursor is never persisted — see action.ts). Carries
+  // the SAME shapes for the SAME reason: a persistent write is gated and
+  // realized exactly like a session write, only the wire verb (VERB_SET_CONFIG/
+  // VERB_STEP_CONFIG) and the write's durability differ.
+  | {
+      readonly kind: "persist-literal";
+      readonly key: string;
+      readonly value: string;
+      readonly stateVar: string;
+    }
+  | {
+      readonly kind: "persist-option";
+      readonly key: string;
+      readonly stateVar: string;
+      readonly options: readonly string[];
+    }
+  | {
+      readonly kind: "persist-bounded";
+      readonly key: string;
+      readonly by: number;
+    }
+  | {
+      readonly kind: "persist-cycle";
+      readonly key: string;
+      readonly stateVar: string;
+      readonly members: readonly string[];
+    }
+  // [LAW:one-source-of-truth] The gated undo for a persistent write: clears
+  // one config-overrides key. Carries only the key — there is no value to
+  // realize, so it shares copy/open's "no gate" shape at compile time (the
+  // GATE is the key-membership check the reset-config verb handler applies).
+  | { readonly kind: "reset"; readonly key: string };
 
 export type CompiledActions = ReadonlyMap<string, CompiledActionDecl>;
 
-// [LAW:one-source-of-truth] An option source resolves to the SAME canonical list
-// the `themes()`/`styles()`/`looks()` bindings and the derived gate consult —
-// rendered options and the gate cannot diverge. The render-side resolver (the
-// daemon's validator-derivation has its own that must agree — themes/styles from
-// themes/policy, looks from the config's merged look names, threaded in as data
-// because that one domain is per-config, not registry-static).
-export function optionDomain(
-  src: OptionSource,
-  lookNames: readonly string[],
-): readonly string[] {
-  if (src === "themes") return listResolvablePaletteNames();
-  if (src === "styles") return STRIP_STYLES;
-  return lookNames;
-}
+// [LAW:one-source-of-truth] Globals fields whose CURRENT resolved value is
+// exposed to templates under a different var name than the field itself (the
+// daemon publishes this resolution once per render — e.g. `theme.effective`
+// for `palette`, src/daemon/render-payload.ts). A `persist` action with no
+// entry here reads back through its own key name as an input var (mirrors
+// compileActions' stateKeyToVar fallback), so every persistable globals field
+// needs an entry unless its `.effective` projection happens to be named
+// exactly the bare field (none are — every projection carries the
+// `.effective` suffix). Every field with a projection is listed
+// (candybar-config-engine-71o.3 added style/charset/colorCompatibility/
+// autoWrap/padding to palette/look's original two); a field with no entry
+// here still writes correctly on `persist` — only its "current selection"
+// highlight is inert (readVar falls back to "" since no such var exists).
+const CONFIG_KEY_TO_EFFECTIVE_VAR: ReadonlyMap<string, string> = new Map([
+  ["palette", "theme.effective"],
+  ["look", "look.effective"],
+  ["style", "style.effective"],
+  ["charset", "charset.effective"],
+  ["colorCompatibility", "colorCompatibility.effective"],
+  ["autoWrap", "autoWrap.effective"],
+  ["padding", "padding.effective"],
+]);
 
 // [LAW:locality-or-seam] The runtime holder the `action` template function closes
 // over. Populated after the engine is constructed (the func references the
@@ -165,13 +206,17 @@ export function compileActions(
   parse: (src: string) => Template<RichText>,
   actions: Readonly<Record<string, ActionDecl>>,
   stateKeyToVar: ReadonlyMap<string, string>,
-  // The config's look names — the one per-config option domain optionDomain
-  // resolves from (themes/styles stay registry-static).
-  lookNames: readonly string[],
+  // This config's per-config option domains (currently just "looks" — the
+  // config's merged look names) — resolveOptionDomain checks these before
+  // falling back to the global registry (themes/styles).
+  perConfigDomains: ReadonlyMap<string, readonly string[]>,
 ): CompiledActions {
   const out = new Map<string, CompiledActionDecl>();
   for (const [name, action] of Object.entries(actions)) {
-    out.set(name, compileAction(parse, name, action, stateKeyToVar, lookNames));
+    out.set(
+      name,
+      compileAction(parse, name, action, stateKeyToVar, perConfigDomains),
+    );
   }
   return out;
 }
@@ -185,7 +230,7 @@ function compileAction(
   name: string,
   action: ActionDecl,
   stateKeyToVar: ReadonlyMap<string, string>,
-  lookNames: readonly string[],
+  perConfigDomains: ReadonlyMap<string, readonly string[]>,
 ): CompiledActionDecl {
   if ("set" in action) {
     const stateVar = stateKeyToVar.get(action.set) ?? action.set;
@@ -202,7 +247,7 @@ function compileAction(
         kind: "set-option",
         key: action.set,
         stateVar,
-        options: [...optionDomain(action.from, lookNames)],
+        options: [...resolveOptionDomain(action.from, perConfigDomains)],
       };
     }
     if ("int" in action) {
@@ -222,16 +267,52 @@ function compileAction(
       by: action.by,
     };
   }
+  if ("persist" in action) {
+    const stateVar =
+      CONFIG_KEY_TO_EFFECTIVE_VAR.get(action.persist) ?? action.persist;
+    if ("to" in action) {
+      return {
+        kind: "persist-literal",
+        key: action.persist,
+        value: action.to,
+        stateVar,
+      };
+    }
+    if ("from" in action) {
+      return {
+        kind: "persist-option",
+        key: action.persist,
+        stateVar,
+        options: [...resolveOptionDomain(action.from, perConfigDomains)],
+      };
+    }
+    if ("cycle" in action) {
+      return {
+        kind: "persist-cycle",
+        key: action.persist,
+        stateVar,
+        members: action.cycle,
+      };
+    }
+    return {
+      kind: "persist-bounded",
+      key: action.persist,
+      by: action.by,
+    };
+  }
   if ("copy" in action) {
     return {
       kind: "copy",
       text: parseActionTemplate(parse, action.copy, name),
     };
   }
-  return {
-    kind: "open",
-    target: parseActionTemplate(parse, action.open, name),
-  };
+  if ("open" in action) {
+    return {
+      kind: "open",
+      target: parseActionTemplate(parse, action.open, name),
+    };
+  }
+  return { kind: "reset", key: action.reset };
 }
 
 function parseActionTemplate(
@@ -292,7 +373,7 @@ export function linkFragment(
 // renders the first display and clicks to the second member (an accordion
 // sibling's path "counts as closed", a never-written toggle "counts as off").
 function cycleIndex(
-  c: Extract<CompiledActionDecl, { kind: "set-cycle" }>,
+  c: Extract<CompiledActionDecl, { kind: "set-cycle" | "persist-cycle" }>,
   store: VariableStore,
 ): number {
   return Math.max(c.members.indexOf(readVar(store, c.stateVar)), 0);
@@ -400,6 +481,47 @@ function realize(
         },
         active: false,
       };
+    // [LAW:one-source-of-truth] The persist-* arms mirror set-*'s realization
+    // verbatim (same literal/option/cycle/bounded semantics), only the wire
+    // verb differs (VERB_SET_CONFIG/VERB_STEP_CONFIG instead of
+    // VERB_SET_STATE/VERB_STEP_STATE) — the daemon-side handler is what makes
+    // the write durable, not the click itself.
+    case "persist-literal": {
+      const current = readVar(store, c.stateVar);
+      return {
+        effect: { verb: VERB_SET_CONFIG, args: [sessionId, c.key, c.value] },
+        active: current === c.value,
+      };
+    }
+    case "persist-option": {
+      const value = boundValue ?? display;
+      const current = readVar(store, c.stateVar);
+      return {
+        effect: { verb: VERB_SET_CONFIG, args: [sessionId, c.key, value] },
+        active: current === value,
+      };
+    }
+    case "persist-cycle": {
+      const next = c.members[(cycleIndex(c, store) + 1) % c.members.length]!;
+      return {
+        effect: { verb: VERB_SET_CONFIG, args: [sessionId, c.key, next] },
+        active: false,
+      };
+    }
+    case "persist-bounded": {
+      return {
+        effect: {
+          verb: VERB_STEP_CONFIG,
+          args: [sessionId, c.key, String(c.by)],
+        },
+        active: false,
+      };
+    }
+    case "reset":
+      return {
+        effect: { verb: VERB_RESET_CONFIG, args: [sessionId, c.key] },
+        active: false,
+      };
   }
 }
 
@@ -419,7 +541,7 @@ function selectDisplay(
   if (displays.length === 0) {
     throw new Error(`action "${name}" needs a display (the clickable text)`);
   }
-  if (action.kind === "set-cycle") {
+  if (action.kind === "set-cycle" || action.kind === "persist-cycle") {
     if (displays.length !== 1 && displays.length !== action.members.length) {
       throw new Error(
         `action "${name}" cycles ${action.members.length} members; bind one display per member (${action.members.length}) or one static display, got ${displays.length}`,

package/src/render/active-segment.ts

@@ -0,0 +1,78 @@
+// The one record describing the segment a template is being evaluated for.
+//
+// [LAW:one-source-of-truth] Several template features need to know something
+// about the enclosing segment — `{{ menu }}` derives its identity from the
+// segment's name, `{{ color }}` must read the segment's own (transposed)
+// palette, `{{ bgOf }}` must read the segment's own resolved background. Each
+// of those could have carried its own published "current segment" pointer, and
+// then two features could disagree about which segment is current. One record,
+// one publisher, one clock.
+//
+// [LAW:no-ambient-temporal-coupling] This is *published state*, not ambient
+// context: the render walk sets it before evaluating a segment's templates and
+// clears it after, and nothing else writes it. The phase structure within a
+// segment is likewise state rather than luck — `bg` is genuinely undefined
+// while the `bg:` template is itself being evaluated, because at that moment
+// the background is the thing being computed. Readers get a message naming the
+// phase instead of a plausible-looking wrong color.
+
+import type { ColorRgba, Palette } from "@promptctl/rich-js";
+
+export interface ActiveSegment {
+  /** The segment's declared name — `{{ menu }}` derives its identity from it. */
+  readonly segName: string;
+  /**
+   * The palette this segment's colors resolve from: the base theme (session
+   * choice over config default, or an explicit per-segment `palette:` pin)
+   * after the render's look and this segment's hue shift.
+   *
+   * Template bodies read colors through THIS, not through a palette captured
+   * when the config was loaded — otherwise `{{ color "primary" }}` inside a
+   * segment paints from a different palette than the cell it sits in.
+   */
+  readonly palette: Palette;
+  /**
+   * The segment's resolved background, once known.
+   *
+   * Undefined during evaluation of the segment's own `bg:` template — the
+   * ordering is bg, then fg, then body, and a background cannot be an input to
+   * computing itself.
+   */
+  bg: ColorRgba | undefined;
+}
+
+/** The published pointer. Null between segments. */
+export interface ActiveSegmentRef {
+  current: ActiveSegment | null;
+}
+
+export function createActiveSegmentRef(): ActiveSegmentRef {
+  return { current: null };
+}
+
+/**
+ * Read the active segment, or fail with a message that says *why* nothing is
+ * active rather than what is missing.
+ *
+ * [LAW:no-defensive-null-guards] Null here is never a state to route around —
+ * it means a segment-scoped template function fired outside a segment render,
+ * which is either a wiring bug or an author using the function somewhere it
+ * cannot mean anything (a variable template, a node `when`). Both need to be
+ * seen, and in cc-candybar a thrown template error surfaces as a visible ⚠
+ * cell that `cc-candybar check` fails on. [LAW:no-silent-failure]
+ */
+export function requireActiveSegment(
+  ref: ActiveSegmentRef,
+  func: string,
+): ActiveSegment {
+  const active = ref.current;
+  if (active === null) {
+    throw new Error(
+      `{{ ${func} }} is only available inside a segment's templates — ` +
+        `there is no active segment here. Segment-scoped functions cannot be ` +
+        `used in variable declarations or layout-node "when" predicates, ` +
+        `which are evaluated outside any segment.`,
+    );
+  }
+  return active;
+}

package/src/render/menu.ts

@@ -50,25 +50,30 @@ import {
 import { effectsUrl, VERB_SET_STATE } from "../click/wire.js";
 import { linkFragment, readVar, type ActionRuntime } from "./action.js";
 import { renderPicker } from "./picker.js";
+import type { ActiveSegmentRef } from "./active-segment.js";
 
-// [LAW:types-are-the-program] One menu placement: the structural fact a context-
-// free `{{ menu }}` cannot see about itself — the name of the segment it renders
-// inside. Published by the walk per segment render; the helper reads the live
-// value to derive identity.
-export interface MenuPlacement {
-  readonly segName: string;
-}
+// [LAW:one-type-per-behavior] A `{{ menu }}` needs one structural fact it cannot
+// see about itself — the name of the segment it renders inside. That used to be
+// its own `MenuPlacement` type; it is now a field on the ONE active-segment
+// record the walk publishes (see render/active-segment.ts), because "which
+// segment is rendering" is a single fact and a per-feature copy of it is a
+// second clock. The menu reads `segName` and ignores the rest.
 
 // [LAW:locality-or-seam] The runtime the `menu` func closes over. It shares the
 // ACTION runtime (the menu's glyph and body resolve their actions/state from the
 // same compiled table + store as every other helper) and READS the walk-published
-// current placement — both inputs, never written by the helper. `current` is
-// mutated only by the single owner (the render walk, before each segment eval) —
+// active segment — both inputs, never written by the helper. The record is
+// mutated only by the single owner (the render walk, around each segment eval) —
 // the spatial cousin of the hue cursor, one mutator, never ambient.
 // [LAW:no-ambient-temporal-coupling]
 export interface MenuRuntime {
   readonly action: ActionRuntime;
-  current: MenuPlacement | null;
+  // [LAW:one-source-of-truth] The menu does not publish its own "which segment
+  // is current" pointer — it reads the ONE record the render walk publishes for
+  // every segment-scoped feature (the palette `{{ color }}` resolves against and
+  // the background `{{ bgOf }}` returns ride the same record). A second pointer
+  // would be a second clock for the same fact.
+  readonly activeSegment: ActiveSegmentRef;
 }
 
 // [LAW:effects-at-boundaries] The body a `{{ menu }}` drops below its row rides as
@@ -95,7 +100,7 @@ function renderMenu(
   options: MenuOptions,
   runtime: MenuRuntime,
 ): RichText {
-  const placement = runtime.current;
+  const placement = runtime.activeSegment.current;
   // [LAW:no-defensive-null-guards] The walk publishes a placement before every
   // segment template evaluates; a `{{ menu }}` only renders inside a segment. A
   // null here is a wiring bug (the func fired with no current segment), surfaced

package/src/render/picker.ts

@@ -28,7 +28,7 @@ import type { FuncMap } from "@promptctl/go-template-js";
 import { toNumber } from "../var-system/types.js";
 import { stripChromeCols } from "./strip.js";
 import { TERM_COLS_VAR } from "../config/dsl-types.js";
-import { effectsUrl, VERB_SET_STATE } from "../click/wire.js";
+import { effectsUrl, VERB_SET_CONFIG, VERB_SET_STATE } from "../click/wire.js";
 import {
   linkFragment,
   readVar,
@@ -136,6 +136,31 @@ function requireKind<K extends CompiledActionDecl["kind"]>(
   return action as Extract<CompiledActionDecl, { kind: K }>;
 }
 
+// [LAW:one-source-of-truth] The apply action a picker grid binds to is EITHER
+// of set-option's two durability twins (src/render/action.ts's persist-*
+// mirrors set-*'s shapes one for one) — a picker over `persist("charset",
+// from:"charsets")` is exactly as legal as one over `set("theme",
+// from:"themes")`, differing only in which wire verb the option click emits
+// (VERB_SET_CONFIG vs VERB_SET_STATE), never in shape (both carry key,
+// stateVar, options). Rejecting persist-option here would be an artificial
+// gap: the same option-domain gate (deriveActionValidators) covers both kinds
+// identically, so there is nothing about "picker" that's set-only.
+function requireOptionKind(
+  runtime: ActionRuntime,
+  name: string,
+): Extract<CompiledActionDecl, { kind: "set-option" | "persist-option" }> {
+  const action = runtime.compiled.get(name);
+  if (
+    !action ||
+    (action.kind !== "set-option" && action.kind !== "persist-option")
+  ) {
+    throw new Error(
+      `picker references action "${name}" which must be a set-option or persist-option action ({ set, from } or { persist, from }), got ${action ? `a ${action.kind} action` : "no such action"}`,
+    );
+  }
+  return action;
+}
+
 // [LAW:dataflow-not-control-flow] The page value (and the live width) select
 // which option cells render and which boundary arrows exist — a boundary arrow is
 // an ABSENT fragment, never a skipped branch. ←/→ navigate the page key
@@ -155,12 +180,7 @@ export function renderPicker(
   paged: boolean,
   runtime: ActionRuntime,
 ): RichText {
-  const apply = requireKind(
-    runtime,
-    applyName,
-    "set-option",
-    "a set-option action ({ set, from })",
-  );
+  const apply = requireOptionKind(runtime, applyName);
   const store = runtime.store;
   const sessionId = readVar(store, "session.id");
   const current = readVar(store, apply.stateVar);
@@ -222,13 +242,31 @@ export function renderPicker(
   const closeUrl = effectsUrl([
     { verb: VERB_SET_STATE, args: [sessionId, ...closeFlat] },
   ]);
+  // [LAW:one-source-of-truth] A set-option apply folds its closeOnPick pairs
+  // into ONE set-state batch (setState is variadic — see daemon/verbs). A
+  // persist-option apply cannot: setConfig takes exactly one (key, value), so
+  // its close pairs (always SessionState — open/page live there regardless of
+  // the apply's durability) ride as a SECOND effect in the same dispatch,
+  // still one atomic click via effectsUrl's array.
   const optionUrl = (option: string): string =>
-    effectsUrl([
-      {
-        verb: VERB_SET_STATE,
-        args: [sessionId, apply.key, option, ...(closeOnPick ? closeFlat : [])],
-      },
-    ]);
+    apply.kind === "persist-option"
+      ? effectsUrl([
+          { verb: VERB_SET_CONFIG, args: [sessionId, apply.key, option] },
+          ...(closeOnPick
+            ? [{ verb: VERB_SET_STATE, args: [sessionId, ...closeFlat] }]
+            : []),
+        ])
+      : effectsUrl([
+          {
+            verb: VERB_SET_STATE,
+            args: [
+              sessionId,
+              apply.key,
+              option,
+              ...(closeOnPick ? closeFlat : []),
+            ],
+          },
+        ]);
 
   const frags: RichText[] = [linkFragment(PICKER_CLOSE, closeUrl, false)];
   if (pageIdx > 0) {

package/src/render/segment-color.ts

@@ -0,0 +1,74 @@
+// Segment-scoped color functions: the seam between rich-js's palette-free
+// color vocabulary and cc-candybar's notion of a segment.
+//
+// rich-js owns every color operation and knows nothing about segments;
+// cc-candybar owns segments and performs no color arithmetic of its own
+// [LAW:rich-js-owns-color-math]. This module is exactly the join: it supplies
+// rich-js's `color` with *which* palette, and adds the one function whose
+// meaning is candybar-specific — `bgOf`, the background of the segment
+// currently rendering. [LAW:one-way-deps]
+
+import type { FuncMap, TemplateFunc } from "@promptctl/go-template-js";
+import { paletteFuncs } from "@promptctl/rich-js/template-bindings";
+import {
+  requireActiveSegment,
+  type ActiveSegmentRef,
+} from "./active-segment.js";
+
+/**
+ * Bind `color` and `bgOf` to the segment the walk has published.
+ *
+ * **Why `color` reads a live palette.** A segment's rendered palette is not a
+ * property of the loaded config — it is the base theme (session choice over
+ * config default) adapted by the render's look and the segment's hue shift,
+ * all resolved per render, per segment. Binding `color` to a palette captured
+ * when the config loaded put the *body* of a template on a different palette
+ * than the `bg:`/`fg:` of the very same segment, so `{{ color "primary" }}`
+ * and `bg: "primary"` could name one thing and paint two.
+ * [LAW:one-source-of-truth]
+ *
+ * That divergence was not exotic. Any session theme click moved the segment's
+ * background while leaving every in-body semantic color where it was; a look
+ * or a per-segment hue rotation did the same. Reading the live palette makes
+ * the two agree by construction rather than by coincidence.
+ *
+ * **Why `bgOf` exists.** De-emphasis — drawing labels, punctuation and ids
+ * quieter than the facts they frame — is "move this color toward the
+ * background." A palette's own `foreground-muted` blends toward the *theme's*
+ * background, which is the wrong target for any segment not painted in it: a
+ * segment on `surface-active` needs its muted text blended toward
+ * `surface-active`. Only the segment knows its own background, so only the
+ * segment can supply it:
+ *
+ * ```
+ * {{ $muted := mix (color "foreground") (bgOf) 65 }}
+ * {{ fg $muted .git.repoName }} {{ fg (color "primary") .git.branch }}
+ * ```
+ *
+ * This is also what makes contrast reachable: `{{ fg (contrastOn (bgOf)) … }}`
+ * asks a question about a real background, where the old spec-grammar `"auto"`
+ * could only ever be handed a hardcoded literal.
+ */
+export function segmentColorFuncs(ref: ActiveSegmentRef): FuncMap {
+  const bgOf: TemplateFunc = {
+    fn: (() => {
+      const active = requireActiveSegment(ref, "bgOf");
+      if (active.bg === undefined) {
+        throw new Error(
+          `{{ bgOf }} is not available while segments.${active.segName}'s own ` +
+            `"bg:" is being evaluated — the background is what that template ` +
+            `computes. Reach for a palette color there instead, e.g. ` +
+            `bg: '{{ darken (color "surface") 1 }}'.`,
+        );
+      }
+      return active.bg.hex;
+    }) as TemplateFunc["fn"],
+    argTypes: [],
+    returnType: "string",
+  };
+
+  return {
+    ...paletteFuncs(() => requireActiveSegment(ref, "color").palette),
+    bgOf,
+  };
+}