@promptctl/cc-candybar 1.26.0 → 1.28.0

package/src/template-engine/colors.ts

@@ -1,6 +1,15 @@
 // [LAW:single-enforcer] All per-segment bg/fg resolution flows through
 // resolveSegmentColors. No second path; a second path would silently drift
-// from the two-stage pipeline (bg first, fg with auto-contrast context second).
+// from the ordered pipeline this function owns.
+//
+// [LAW:no-ambient-temporal-coupling] That ordering — publish the segment's
+// palette, resolve bg, publish bg, resolve fg, then hand the body its turn —
+// is not incidental execution order that happens to work. It is the phase
+// structure of a segment's color resolution, and this function is its one
+// owner. Each phase's output is *published* into the active-segment record
+// before the next phase runs, so a later template can read an earlier
+// phase's result (`fg: '{{ contrastOn (bgOf) }}'`) and an earlier one
+// cannot read a later one — it gets a message naming the phase instead.
 //
 // [LAW:dataflow-not-control-flow] Steps execute unconditionally; the option
 // values (undefined template = no spec) are what decides the output, not
@@ -8,60 +17,72 @@
 // → fragmentsToStripCells's baseStyle merge is a no-op, cells flow through
 // unchanged.
 
-import { Style, ColorSpec } from "@promptctl/rich-js";
-import type { ColorRgba, PaletteResolver } from "@promptctl/rich-js";
+import {
+  Style,
+  ColorSpec,
+  resolveColorRef,
+  ColorRefError,
+} from "@promptctl/rich-js";
+import type { ColorRgba, Palette } from "@promptctl/rich-js";
 import type { RichText } from "@promptctl/rich-js";
 import type { Template } from "@promptctl/go-template-js";
+import type { ActiveSegmentRef } from "../render/active-segment.js";
 
 export class ColorSpecError extends Error {
-  constructor(spec: string, role: "bg" | "fg") {
-    super(`Invalid ${role} color spec: ${JSON.stringify(spec)}`);
+  constructor(spec: string, role: "bg" | "fg", detail: string) {
+    super(`Invalid ${role} color ${JSON.stringify(spec)}: ${detail}`);
     this.name = "ColorSpecError";
   }
 }
 
 /**
- * Resolve per-segment bg and fg template strings into a Style for baseStyle
- * injection in fragmentsToStripCells().
+ * Resolve a segment's `bg:` and `fg:` templates into the Style that becomes
+ * its baseStyle, publishing each phase's result into `ref` as it goes.
  *
- * Pipeline:
- *   1. Evaluate bgTemplate → plain text color-spec string.
- *   2. resolver.resolve(bgSpec) → ColorRgba.
- *   3. Evaluate fgTemplate → plain text color-spec string.
- *   4. resolver.resolve(fgSpec, { against: bgColor }) → ColorRgba (auto-contrast).
- *   5. Wrap as Style({ bgcolor, color }).
+ * A `bg:`/`fg:` field is a template evaluated to a **color reference** — a
+ * palette variable name (`"surface-active"`) or a `#RRGGBB` literal. Since
+ * rich-js's `resolveColorRef` accepts both and is idempotent, the plain
+ * authoring form and a computed one take the identical path:
  *
- * Undefined template → that color is not set in the returned Style, so cells
- * fall through to their own style (or no color if they have none).
+ * ```json5
+ * bg: "surface-active"                             // a name, evaluated as itself
+ * bg: '{{ darken (color "surface-active") 1 }}'    // a computed literal
+ * ```
  *
- * Throws ColorSpecError if a non-empty spec string resolves to null.
+ * There is no "is this a name or a color" branch anywhere — one total
+ * function over both. [LAW:dataflow-not-control-flow]
  *
- * Hue rotation is not this function's concern: per-segment hue lives upstream as
- * WHICH palette `resolver` carries (a transposed palette), so bg and fg resolve
- * from the same transposed palette and their theme-designed relationship is
- * preserved. [LAW:dataflow-not-control-flow]
+ * Undefined template → that color is not set in the returned Style, so cells
+ * fall through to their own style (or no color if they have none).
  *
- * [LAW:dataflow-not-control-flow] Steps are ordered data transformations, not
- * guarded branches. The "no spec" case is represented as undefined, which flows
- * through to produce an absent Style field — not a skipped step.
+ * Hue rotation and looks are not this function's concern: they live upstream
+ * as WHICH palette it is handed, so bg, fg, and the body all resolve from one
+ * palette and their theme-designed relationships are preserved.
  */
 export function resolveSegmentColors(
-  resolver: PaletteResolver,
+  ref: ActiveSegmentRef,
+  segName: string,
+  palette: Palette,
   bgTemplate: Template<RichText> | undefined,
   fgTemplate: Template<RichText> | undefined,
   scope: object,
 ): Style {
+  // Phase 0 — the palette is live from here until the walk clears it, so
+  // `{{ color … }}` in the bg template, the fg template, and the body all read
+  // this one palette. `bg` starts undefined: it is what phase 1 computes.
+  const active = { segName, palette, bg: undefined as ColorRgba | undefined };
+  ref.current = active;
+
+  // Phase 1 — background.
   const bgSpec = evalToPlainText(bgTemplate, scope);
   const bgColor =
-    bgSpec !== undefined
-      ? resolveSpec(resolver, bgSpec, undefined, "bg")
-      : undefined;
+    bgSpec !== undefined ? resolveRef(palette, bgSpec, "bg") : undefined;
 
+  // Phase 2 — publish it, then foreground, which may now ask about it.
+  active.bg = bgColor;
   const fgSpec = evalToPlainText(fgTemplate, scope);
   const fgColor =
-    fgSpec !== undefined
-      ? resolveSpec(resolver, fgSpec, bgColor, "fg")
-      : undefined;
+    fgSpec !== undefined ? resolveRef(palette, fgSpec, "fg") : undefined;
 
   return new Style({
     bgcolor: bgColor !== undefined ? ColorSpec.fromRgba(bgColor) : undefined,
@@ -82,21 +103,22 @@ function evalToPlainText(
     .join("");
 }
 
-// Resolve a color spec string through the palette resolver.
-// Throws ColorSpecError (loud failure) if the spec is unknown or the required
-// `against` context is missing — never silently falls back to a default.
-// [LAW:no-defensive-null-guards] null from resolver.resolve signals broken
-// config; the fix is the config, not a silent fallback.
-function resolveSpec(
-  resolver: PaletteResolver,
-  spec: string,
-  against: ColorRgba | undefined,
+// [LAW:one-source-of-truth] The same rich-js checkpoint the `{{ color }}`
+// template function crosses, so a reference that works in a body works in a
+// `bg:` field and vice versa. Re-thrown with the field's role attached —
+// rich-js knows the reference failed, only cc-candybar knows it came from a
+// `fg:`. [LAW:no-silent-failure] never a substituted default: a broken color
+// reference is a config bug, and the fix is the config.
+function resolveRef(
+  palette: Palette,
+  ref: string,
   role: "bg" | "fg",
 ): ColorRgba {
-  const color = resolver.resolve(
-    spec.trim(),
-    against !== undefined ? { against } : undefined,
-  );
-  if (color === null) throw new ColorSpecError(spec, role);
-  return color;
+  try {
+    return resolveColorRef(palette, ref);
+  } catch (e) {
+    if (e instanceof ColorRefError)
+      throw new ColorSpecError(ref, role, e.message);
+    throw e;
+  }
 }

package/src/template-engine/engine.ts

@@ -18,8 +18,13 @@
 //    (int here is shadowed by ccCandybarFuncs' var-system cast below).
 //  • sprigDicts: dict, get, set, keys, values, pick, omit, hasKey, merge —
 //    `dict` lets a helper take multiple named inputs through its one dot arg.
-//  • richTextFuncs: bold, italic, red, green, … (styling from rich-js).
-//  • paletteFuncs (when resolver provided): primary, accent, palette, paletteOver, auto.
+//  • richTextFuncs: fg, bg, bold, italic, link, style (painting) PLUS the
+//    palette-free color math (darken, lighten, mix, contrastOn, readableOn,
+//    shiftHue, scaleChroma, scaleLightness, shiftLightness) — all from rich-js.
+//    Naming a THEME color (`{{ color "primary" }}`) and asking for the current
+//    segment's background (`{{ bgOf }}`) are segment-scoped, so they arrive
+//    through `extraFuncs` from the DSL render layer, which is the only place
+//    that knows which segment is rendering.
 //  • ccCandybarFuncs: basename, dirname, int, string, bool, urlEncode,
 //    themes, styles, sparkline.
 //  • formatterFuncs: minutesUntilReset (clock-reading numeric primitive),
@@ -39,29 +44,24 @@ import {
   sprigConversions,
   sprigDicts,
 } from "@promptctl/go-template-js";
-import type { PaletteResolver } from "@promptctl/rich-js";
 import { richTextFuncs, RichText } from "@promptctl/rich-js";
-import { paletteFuncs } from "@promptctl/rich-js/template-bindings";
 import { ccCandybarFuncs, formatterFuncs } from "./funcs.js";
 
 // [LAW:single-enforcer] fromString/toString are declared once here.
-// richTextFuncs() provides style functions (bold, red, link, …).
-// paletteFuncs(resolver) registers semantic palette functions when a theme
-// resolver is provided — same engine instance, no second parse path.
+// richTextFuncs() provides the theme-independent vocabulary: painting, color
+// math, attributes, links. It needs no configuration, so it is unconditional.
 // [LAW:one-way-deps] `extraFuncs` is an INJECTED FuncMap (e.g. the action +
 // picker feature funcs, built in render/action.ts + render/picker.ts). The
 // generic engine never imports a specific feature — the caller hands it the
 // capability as data, so the dependency runs caller → engine, never engine → feature.
-// [LAW:one-type-per-behavior] resolver?/extraFuncs? are values, not modes —
-// one factory, one engine shape; the data (their presence) governs what's
-// registered.
+// [LAW:one-type-per-behavior] extraFuncs? is a value, not a mode — one factory,
+// one engine shape; the data (its presence) governs what's registered.
 // [LAW:single-enforcer] `clock` is the one time source. It feeds sprigDatetime
 // (the funcs that read "now") AND createEngine's clock option, so every
 // time-dependent evaluation in this engine reads from one seam. Defaulted here
 // so the default literal `() => new Date()` lives in exactly one place; callers
 // that omit it (and forwarders passing `undefined`) inherit it unchanged.
 export function createCcCandybarEngine(
-  resolver?: PaletteResolver,
   extraFuncs?: FuncMap,
   clock: () => Date = () => new Date(),
 ): Engine<RichText> {
@@ -88,7 +88,6 @@ export function createCcCandybarEngine(
       // decoupled from any payload's nesting — no per-payload helper variant.
       ...sprigDicts(),
       ...richTextFuncs(),
-      ...(resolver !== undefined ? paletteFuncs(resolver) : {}),
       // Domain-specific overrides last (wins on collision with sprig aliases).
       // [LAW:one-source-of-truth] ccCandybarFuncs' `int` is the var-system cast
       // (toNumber over VarValue); it intentionally shadows sprigConversions' `int`

package/src/themes/index.ts

@@ -15,7 +15,4 @@ export {
 } from "./policy.js";
 export type { StripStyle } from "./policy.js";
 
-export {
-  resolverForThemeName,
-  transposedResolver,
-} from "./palette-resolvers.js";
+export { paletteForThemeName, transposedPalette } from "./palette-resolvers.js";

package/src/themes/palette-resolvers.ts

@@ -1,36 +1,32 @@
-// Memoized PaletteResolver construction over rich-js. cc-candybar moves theme
+// Memoized Palette construction over rich-js. cc-candybar moves theme
 // NAMES and ThemeKey axes (data); rich-js owns every color value operation. Two
-// memos live here: a theme name -> base resolver, and a (base, ThemeKey) ->
-// transposed resolver. They compose — the per-render base palette feeds the
+// memos live here: a theme name -> base palette, and a (base, ThemeKey) ->
+// transposed palette. They compose — the per-render base palette feeds the
 // per-segment transposition (the session look's axes + the segment's hue shift,
 // folded into one key by the caller).
 //
 // [LAW:no-shared-mutable-globals] Single owner: this module. Both Maps are pure
 // memos of pure rich-js functions, keyed by immutable inputs (resolved theme
 // name; palette name + the four ThemeKey axes). rich-js palettes are immutable
-// registry singletons, so a cached resolver never goes stale. Key spaces are
+// registry singletons, so a cached palette never goes stale. Key spaces are
 // bounded by #themes and #themes × #declared looks × #distinct hueShifts
 // (hueShift = look shift + segIndex*hueStep, segIndex bounded by layout; look
 // axes bounded by the loaded configs' looks blocks) — both small. Shared on
-// purpose: a theme's base resolver and its gruvbox+42° transposition are each
+// purpose: a theme's base palette and its gruvbox+42° transposition are each
 // computed once per process, not once per RenderCache entry or per render.
 // Read/written only through the two functions below.
 
-import {
-  PaletteResolver,
-  transposePalette,
-  getThemePalette,
-} from "@promptctl/rich-js";
-import type { ThemeKey } from "@promptctl/rich-js";
+import { transposePalette, getThemePalette } from "@promptctl/rich-js";
+import type { ThemeKey, Palette } from "@promptctl/rich-js";
 import { resolvePaletteName } from "./policy.js";
 
-const baseCache = new Map<string, PaletteResolver>();
-const transposeCache = new Map<string, PaletteResolver>();
+const baseCache = new Map<string, Palette>();
+const transposeCache = new Map<string, Palette>();
 
 /**
- * The PaletteResolver for a theme name (aliases resolved). Memoized.
+ * The Palette for a theme name (aliases resolved). Memoized.
  *
- * [LAW:single-enforcer] The one place a theme name becomes a PaletteResolver —
+ * [LAW:single-enforcer] The one place a theme name becomes a Palette —
  * the per-render base palette and per-segment `palette:` overrides both flow
  * through here. A name that does not resolve is registry/resolver drift, never
  * user error: the loader validates `globals.palette` and the set-state verb
@@ -38,7 +34,7 @@ const transposeCache = new Map<string, PaletteResolver>();
  * name reaches here it must resolve. [LAW:no-defensive-null-guards] the throw is
  * the loud failure for that broken invariant, not a fallback.
  */
-export function resolverForThemeName(name: string): PaletteResolver {
+export function paletteForThemeName(name: string): Palette {
   const resolved = resolvePaletteName(name);
   const hit = baseCache.get(resolved);
   if (hit !== undefined) return hit;
@@ -50,14 +46,13 @@ export function resolverForThemeName(name: string): PaletteResolver {
         `theme registry — allowed names and the registry are inconsistent`,
     );
   }
-  const resolver = new PaletteResolver(palette);
-  baseCache.set(resolved, resolver);
-  return resolver;
+  baseCache.set(resolved, palette);
+  return palette;
 }
 
 /**
- * The PaletteResolver for `base`'s palette transposed by a full ThemeKey — the
- * adapted-resolver constructor: (base resolver, key) → resolver. The caller
+ * `base` transposed by a full ThemeKey — the adapted-palette constructor:
+ * (base palette, key) → palette. The caller
  * composes whatever axes it carries (a look's four axes, the per-segment hue
  * shift) into ONE key and this makes ONE transposePalette call — never chain
  * two transpositions: chaining double-pays OKLCH quantization AND collides this
@@ -70,23 +65,20 @@ export function resolverForThemeName(name: string): PaletteResolver {
  * (error/success/warning), so semantic meaning is preserved by construction —
  * no local exemption list to drift.
  *
- * [LAW:single-enforcer] The sole place a transposed resolver is built — a
+ * [LAW:single-enforcer] The sole place a transposed palette is built — a
  * future look `roles` remap is additive at this one seam. The memo miss
  * (undefined) is genuine optionality — not-yet-computed — not a defended
  * invariant. [LAW:one-source-of-truth] The cache key carries every axis of the
  * ThemeKey: two keys differing on any axis are distinct palettes.
  */
-export function transposedResolver(
-  base: PaletteResolver,
-  key: ThemeKey,
-): PaletteResolver {
+export function transposedPalette(base: Palette, key: ThemeKey): Palette {
   const cacheKey =
-    `${base.palette.name} ${key.hueShift} ${key.chromaScale} ` +
+    `${base.name} ${key.hueShift} ${key.chromaScale} ` +
     `${key.lightnessScale} ${key.lightnessShift}`;
   const hit = transposeCache.get(cacheKey);
   if (hit !== undefined) return hit;
 
-  const resolver = new PaletteResolver(transposePalette(base.palette, key));
-  transposeCache.set(cacheKey, resolver);
-  return resolver;
+  const transposed = transposePalette(base, key);
+  transposeCache.set(cacheKey, transposed);
+  return transposed;
 }

package/src/themes/policy.ts

@@ -2,7 +2,7 @@
 // theme registry. cc-candybar selects theme NAMES and style IDENTIFIERS here;
 // every color *value* operation (hydrate hex, resolve specs, darken/contrast,
 // hue/transpose) lives in rich-js. This module only moves strings — no
-// PaletteResolver, no ColorRgba, no hex. The semantic/anchor knowledge
+// Palette, no ColorRgba, no hex. The semantic/anchor knowledge
 // (which tokens keep their hue) stays in rich-js (ANCHORED_ROOTS), not here.
 
 import {
@@ -51,28 +51,49 @@ export function listResolvablePaletteNames(): readonly string[] {
   return [...listThemePalettes(), ...listThemeAliases()];
 }
 
+// --- Per-config member selection ---
+
+// [LAW:one-type-per-behavior] THE resolution shape shared by every selection
+// whose domain is PER-CONFIG (declared in the config, not a registry-static
+// list): session choice over config default over a floor, then collapse to the
+// floor if the chosen name is not a declared member. `looks` and `presets` are
+// both exactly this — what differs between them is only the floor name and
+// which map holds the members, i.e. DATA. Written once here rather than twice,
+// so a change to the collapse rule cannot land on one and miss the other.
+//
+// [LAW:dataflow-not-control-flow] The `??` chain IS the precedence — no "if the
+// session has one" branch anywhere. [LAW:no-silent-failure] the collapse is the
+// visible floor, not a throw: a stale SessionState entry from a prior config's
+// vocabulary (config edits can orphan a name the per-config gate once admitted)
+// must render the floor, and the caller publishes the RESOLVED name onto the
+// payload so a menu label can never claim a member the render did not use.
+//
+// The floor's membership is a load-time guarantee, not a runtime hope: the
+// bundled stdlib ships it and merge-by-name cannot remove it.
+export function effectiveMemberName(
+  sessionPick: string | null,
+  configDefault: string | undefined,
+  floor: string,
+  declared: Readonly<Record<string, unknown>>,
+): string {
+  const chosen = sessionPick ?? configDefault ?? floor;
+  return Object.prototype.hasOwnProperty.call(declared, chosen)
+    ? chosen
+    : floor;
+}
+
 // --- Look (theme-adaptation) identifiers ---
 
-// The look name 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 "none" floor, no
-// "if the session has a look" branch. Unlike the registry-static theme/style
-// domains, the look domain is PER-CONFIG (the merged `looks` block), so the
-// declared names arrive as data. A value outside them (a stale SessionState
-// entry from a prior config's look vocabulary — config edits can orphan a
-// clicked name the per-config gate once admitted) collapses to "none", which
-// every merged DslConfig carries by construction (the bundled stdlib ships it;
-// merge-by-name cannot remove it) — the same collapse-to-floor that keeps
-// effectiveStripStyle's return honest rather than silently widening.
+// [LAW:one-source-of-truth] The look domain's instance of the shared resolver
+// above — the floor is `"none"`, the identity adaptation every merged config
+// carries. A named wrapper (not a bare call at each site) so the floor is
+// spelled once and the three call sites cannot disagree about it.
 export function effectiveLookName(
   sessionLook: string | null,
   globalsLook: string | undefined,
   declaredLooks: Readonly<Record<string, ThemeKey>>,
 ): string {
-  const chosen = sessionLook ?? globalsLook ?? "none";
-  return Object.prototype.hasOwnProperty.call(declaredLooks, chosen)
-    ? chosen
-    : "none";
+  return effectiveMemberName(sessionLook, globalsLook, "none", declaredLooks);
 }
 
 // [LAW:single-enforcer] The one place an effective look NAME becomes the