@promptctl/cc-candybar 1.26.0 → 1.28.0

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,
+  };
+}