@promptctl/cc-candybar 1.19.0 → 1.21.0

package/src/dsl/render.ts

@@ -11,8 +11,8 @@
 // the input values (kind discriminators, layout length, palette presence)
 // govern output, not whether operations run.
 
-import type { RichText, PaletteResolver } from "@promptctl/rich-js";
-import { ColorSpec, Style, lighten } from "@promptctl/rich-js";
+import type { RichText, PaletteResolver, 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 {
   ValidatedConfig,
@@ -304,12 +304,23 @@ export function registerDslConfig(
     action: actionRuntime,
     current: null,
   };
+  // [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.
+  const lookNames = Object.keys(config.looks);
   const engine = createCcCandybarEngine(
     undefined,
     {
       ...actionFuncs(actionRuntime),
       ...pickerFuncs(actionRuntime),
       ...menuFuncs(menuRuntime),
+      // [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: [] },
     },
     opts?.clock,
   );
@@ -348,7 +359,12 @@ export function registerDslConfig(
   // [LAW:one-source-of-truth] Actions resolve their set key → the reading
   // variable through the stateKeyToVar map, so an apply action and the picker
   // that references it read one value.
-  actionRuntime.compiled = compileActions(parse, config.actions, stateKeyToVar);
+  actionRuntime.compiled = compileActions(
+    parse,
+    config.actions,
+    stateKeyToVar,
+    lookNames,
+  );
 
   // [LAW:dataflow-not-control-flow] One variable failing to declare does not
   // abort the rest. Errors are data (accumulated in loadWarnings); the store
@@ -501,14 +517,11 @@ function focusTint(style: Style): Style {
  * into nested containers keeps every segment's color; toggling a node's
  * visibility does not recolor the nodes after it.
  */
-export function renderDsl(
-  config: ValidatedConfig,
-  compiled: CompiledConfig,
-  store: VariableStore,
-  registry: SourceRegistry,
-  payload: unknown,
-  basePalette: PaletteResolver,
-  opts: BuildLineOptions,
+// [LAW:locality-or-seam] The optional render observers, bundled as ONE named bag
+// so a caller states what it passes by name — no positional tail to count, no
+// `undefined` holes to reach a later observer, and a new observer is one field
+// here rather than a signature change every caller re-counts.
+export interface RenderObservers {
   // [LAW:dataflow-not-control-flow] Optional per-segment cell sink. When
   // present, each rendered segment's RichText array (post-layout, pre-
   // serialization) is written to this map under its segment name. Storing
@@ -521,8 +534,35 @@ export function renderDsl(
   // joined line (powerline joiners sit *between* segments and have no
   // place in a one-segment render), but for debug visibility this is the
   // natural per-segment shape.
-  perSegmentSink?: Map<string, readonly RichText[]>,
+  readonly perSegmentSink?: Map<string, readonly RichText[]>;
+  // [LAW:no-silent-failure] Optional observer for per-segment evaluation errors.
+  // A failing segment renders as a visible ⚠ error cell (partial rendering, the
+  // daemon's author-facing channel) — a headless caller with no one looking at
+  // the bar (`cc-candybar check`) passes this to receive the same errors as
+  // data and fold them into its text verdict. Trusted non-throwing (the
+  // registry-dispose contract): an observer that throws is a caller bug
+  // surfaced loudly, never caught and absorbed by the render walk.
+  readonly onSegmentError?: (segName: string, message: string) => void;
+}
+
+export function renderDsl(
+  config: ValidatedConfig,
+  compiled: CompiledConfig,
+  store: VariableStore,
+  registry: SourceRegistry,
+  payload: unknown,
+  basePalette: PaletteResolver,
+  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,
 ): string {
+  const { perSegmentSink, onSegmentError } = observers ?? {};
   // [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
@@ -616,10 +656,12 @@ export function renderDsl(
     const ctx: NodeRenderCtx = {
       scope,
       basePalette,
+      look,
       visible,
       padding: opts.padding,
       nextHueShift,
       perSegmentSink,
+      onSegmentError,
       beginSegment,
       collectDrops,
       focusTint,

package/src/index.ts

@@ -11,7 +11,8 @@ import { tryRenderViaDaemon } from "./daemon/client";
 import { runDaemonStats } from "./daemon/client-stats";
 import { runDebug } from "./daemon/client-debug";
 import { isDebugWhat } from "./daemon/debug-types";
-import { runLint, runSchema } from "./config/cli";
+import { runSchema } from "./config/cli";
+import { runCheck } from "./check";
 import { obtainDaemonKick } from "./daemon/acquire";
 import { planOutcome } from "./render/outcome-plan";
 
@@ -66,8 +67,11 @@ Subcommands (macOS):
                            request totals. Does not spawn a daemon.
 
 Config tooling:
-  lint <config-file>       Validate a config file (parse + cross-refs + cycles)
-                           with no daemon. Exit 0 valid, 1 invalid, 2 unreadable.
+  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.
@@ -113,8 +117,11 @@ async function main(): Promise<void> {
       await runDaemonStats(process.argv.slice(3));
       process.exit(0);
     }
-    if (subcommand === "lint") {
-      runLint(process.argv.slice(3)); // owns its own exit code (0/1/2)
+    // [LAW:one-type-per-behavior] `lint` is an alias of `check` — one config
+    // verdict, one pipeline, one exit-code contract (0/1/2). check subsumes the
+    // old lint (same loader, plus register + render coverage).
+    if (subcommand === "check" || subcommand === "lint") {
+      runCheck(process.argv.slice(3)); // owns its own exit code (0/1/2)
       return;
     }
     if (subcommand === "schema") {

package/src/render/action.ts

@@ -107,11 +107,18 @@ export type CompiledActionDecl =
 export type CompiledActions = ReadonlyMap<string, CompiledActionDecl>;
 
 // [LAW:one-source-of-truth] An option source resolves to the SAME canonical list
-// the `themes()`/`styles()` 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, both reading themes/policy).
-export function optionDomain(src: OptionSource): readonly string[] {
-  return src === "themes" ? listResolvablePaletteNames() : STRIP_STYLES;
+// 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:locality-or-seam] The runtime holder the `action` template function closes
@@ -158,10 +165,13 @@ 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[],
 ): CompiledActions {
   const out = new Map<string, CompiledActionDecl>();
   for (const [name, action] of Object.entries(actions)) {
-    out.set(name, compileAction(parse, name, action, stateKeyToVar));
+    out.set(name, compileAction(parse, name, action, stateKeyToVar, lookNames));
   }
   return out;
 }
@@ -175,6 +185,7 @@ function compileAction(
   name: string,
   action: ActionDecl,
   stateKeyToVar: ReadonlyMap<string, string>,
+  lookNames: readonly string[],
 ): CompiledActionDecl {
   if ("set" in action) {
     const stateVar = stateKeyToVar.get(action.set) ?? action.set;
@@ -191,7 +202,7 @@ function compileAction(
         kind: "set-option",
         key: action.set,
         stateVar,
-        options: [...optionDomain(action.from)],
+        options: [...optionDomain(action.from, lookNames)],
       };
     }
     if ("int" in action) {

package/src/themes/index.ts

@@ -6,6 +6,8 @@
 export {
   resolvePaletteName,
   effectiveThemeName,
+  effectiveLookName,
+  lookKeyByName,
   effectiveStripStyle,
   isStripStyle,
   listResolvablePaletteNames,

package/src/themes/palette-resolvers.ts

@@ -1,18 +1,20 @@
 // Memoized PaletteResolver construction over rich-js. cc-candybar moves theme
-// NAMES and hue shifts (data); rich-js owns every color value operation. Two
-// memos live here: a theme name -> base resolver, and a (base, hueShift) ->
+// 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
-// per-segment transposition.
+// 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 + hueShift). rich-js palettes are immutable registry
-// singletons, so a cached resolver never goes stale. Key spaces are bounded by
-// #themes and #themes × #distinct hueShifts (hueShift = segIndex*hueStep,
-// segIndex bounded by layout) — both small. Shared on purpose: a theme's base
-// resolver 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.
+// name; palette name + the four ThemeKey axes). rich-js palettes are immutable
+// registry singletons, so a cached resolver 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
+// computed once per process, not once per RenderCache entry or per render.
+// Read/written only through the two functions below.
 
 import {
   PaletteResolver,
@@ -54,32 +56,36 @@ export function resolverForThemeName(name: string): PaletteResolver {
 }
 
 /**
- * The PaletteResolver for `base`'s palette transposed by `hueShift` degrees.
+ * The PaletteResolver for `base`'s palette transposed by a full ThemeKey — the
+ * adapted-resolver constructor: (base resolver, key) → resolver. 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
+ * memo (a transposed palette keeps the base palette's name, so a re-transposed
+ * gruvbox-with-look and plain gruvbox would share cache keys).
  *
- * [LAW:dataflow-not-control-flow] hueShift is data; 0 flows through
- * transposePalette's identity fast-path (byte-exact, no round-trip) — no branch
- * here. Chroma and lightness are held identity: only hue rotates. rich-js
- * hue-locks ANCHORED_ROOTS (error/success/warning), so semantic meaning is
- * preserved by construction — no local exemption list to drift.
+ * [LAW:dataflow-not-control-flow] The key is data; the identity key flows
+ * through transposePalette's isIdentityKey fast-path (byte-exact, no
+ * round-trip) — no branch here. rich-js hue-locks ANCHORED_ROOTS
+ * (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. The memo
- * miss (undefined) is genuine optionality — not-yet-computed — not a defended
- * invariant.
+ * [LAW:single-enforcer] The sole place a transposed resolver 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,
-  hueShift: number,
+  key: ThemeKey,
 ): PaletteResolver {
-  const cacheKey = `${base.palette.name} ${hueShift}`;
+  const cacheKey =
+    `${base.palette.name} ${key.hueShift} ${key.chromaScale} ` +
+    `${key.lightnessScale} ${key.lightnessShift}`;
   const hit = transposeCache.get(cacheKey);
   if (hit !== undefined) return hit;
 
-  const key: ThemeKey = {
-    hueShift,
-    chromaScale: 1,
-    lightnessScale: 1,
-    lightnessShift: 0,
-  };
   const resolver = new PaletteResolver(transposePalette(base.palette, key));
   transposeCache.set(cacheKey, resolver);
   return resolver;

package/src/themes/policy.ts

@@ -5,7 +5,11 @@
 // PaletteResolver, no ColorRgba, no hex. The semantic/anchor knowledge
 // (which tokens keep their hue) stays in rich-js (ANCHORED_ROOTS), not here.
 
-import { listThemePalettes, type ColorSystemSpec } from "@promptctl/rich-js";
+import {
+  listThemePalettes,
+  type ColorSystemSpec,
+  type ThemeKey,
+} from "@promptctl/rich-js";
 
 // --- Theme name aliasing ---
 
@@ -47,6 +51,52 @@ export function listResolvablePaletteNames(): readonly string[] {
   return [...listThemePalettes(), ...listThemeAliases()];
 }
 
+// --- 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.
+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";
+}
+
+// [LAW:single-enforcer] The one place an effective look NAME becomes the
+// ThemeKey a render transposes with. By the time a name reaches here it must be
+// a member: effectiveLookName collapses unknown names to the "none" floor, and
+// mergeWithDefault guarantees the bundled "none" exists in every DslConfig.
+// [LAW:no-defensive-null-guards] the throw is the loud failure for that broken
+// invariant (a hand-built config missing the stdlib), never a silent identity
+// fallback that would hide the drift.
+export function lookKeyByName(
+  looks: Readonly<Record<string, ThemeKey>>,
+  name: string,
+): ThemeKey {
+  const key = looks[name];
+  if (key === undefined) {
+    throw new Error(
+      `Look "${name}" is not declared in this config — effectiveLookName ` +
+        `collapses unknown names to "none", and every merged config carries ` +
+        `"none"; a miss here is merge/policy drift`,
+    );
+  }
+  return key;
+}
+
 // --- Powerline strip-style identifiers ---
 
 // [LAW:one-source-of-truth][LAW:types-are-the-program] The single canonical set