@promptctl/cc-candybar 1.19.0 → 1.21.0

package/src/config/default-dsl-config.ts

@@ -197,6 +197,16 @@ export const DEFAULT_DSL_CONFIG = {
       path: "theme.effective",
       default: "",
     },
+    // [LAW:one-type-per-behavior] The effective LOOK name, the exact twin of
+    // theme.effective one dimension over — effectiveLookName(sessionState.look,
+    // globals.look, looks), the SAME name whose ThemeKey adapts the rendered
+    // palette. A look-picker trigger reads `{{ .look.effective }}` for its
+    // label; the label and the colors trace to one resolution.
+    "look.effective": {
+      kind: "input",
+      path: "look.effective",
+      default: "",
+    },
 
     // [LAW:one-source-of-truth] The usable terminal width for THIS render —
     // the exact post-reserve cell count FlexStrip wraps to. renderDsl injects
@@ -887,6 +897,60 @@ export const DEFAULT_DSL_CONFIG = {
     applyStyle: { set: "style", from: "styles" },
   },
 
+  // ─── Looks ───────────────────────────────────────────────────────────────
+  // Named theme ADAPTATIONS — each is a full rich-js ThemeKey applied on top
+  // of whatever base theme is active (a transform, not a palette), so every
+  // look composes with every theme: pick theme, then pick look. Selected per
+  // session via the `look` SessionState key (an action `{ set: "look", from:
+  // "looks" }` + a `{{ menu }}`), exactly the theme/style selection seam.
+  // [LAW:one-source-of-truth] Merges by name (user wins per name), so this
+  // stdlib — including the "none" identity floor effectiveLookName collapses
+  // to — is present in every merged config by construction.
+  looks: {
+    // [LAW:dataflow-not-control-flow] "none" is just the identity look — the
+    // resolution floor as a value, not a special case (rich-js's isIdentityKey
+    // fast-path makes it free). Spelled literally (not rich-js IDENTITY /
+    // INVERT_LIGHTNESS) so the bundled default remains inert JSON-shaped data
+    // a user file can mirror axis-for-axis; the loader normalizes user specs
+    // onto the same identity axes.
+    none: { hueShift: 0, chromaScale: 1, lightnessScale: 1, lightnessShift: 0 },
+    // Saturation up/down — chroma is multiplicative, hue and lightness held.
+    vivid: {
+      hueShift: 0,
+      chromaScale: 1.35,
+      lightnessScale: 1,
+      lightnessShift: 0,
+    },
+    muted: {
+      hueShift: 0,
+      chromaScale: 0.55,
+      lightnessScale: 1,
+      lightnessShift: 0,
+    },
+    // Lightness down (scale) / up (shift) — dim compresses toward black,
+    // bright lifts everything a step; anchors stay hue-locked by rich-js.
+    dim: {
+      hueShift: 0,
+      chromaScale: 1,
+      lightnessScale: 0.85,
+      lightnessShift: 0,
+    },
+    bright: {
+      hueShift: 0,
+      chromaScale: 1,
+      lightnessScale: 1,
+      lightnessShift: 0.08,
+    },
+    // The dark↔light "octave" flip (rich-js INVERT_LIGHTNESS: L' = 1 - L) —
+    // errors stay red, dark-on-light becomes light-on-dark.
+    inverted: {
+      hueShift: 0,
+      chromaScale: 1,
+      lightnessScale: -1,
+      lightnessShift: 1,
+    },
+  },
+
   // [LAW:single-enforcer] / [LAW:one-source-of-truth] Display-formatting policy
   // for the cost/token/budget family lives here as named template helpers, each
   // DEFINED ONCE and called from every segment via `{{ template "name" .arg }}`

package/src/config/dsl-loader.ts

@@ -50,6 +50,7 @@ import { validateSegments } from "./loader/segments.js";
 import { synthesizeGroupDecls, validateRoot } from "./loader/layout.js";
 import { synthesizeMenuDecls } from "./loader/menu-synth.js";
 import { validateActions } from "./loader/actions.js";
+import { validateLooks } from "./loader/looks.js";
 import { validateHelpers } from "./loader/helpers.js";
 import { validateCrossReferences } from "./loader/cross-ref.js";
 import { validateNoCycles } from "./loader/cycles.js";
@@ -242,6 +243,7 @@ function validateTopLevel(
   if (raw.root !== undefined) out.root = validateRoot(ctx, "root", raw.root);
   if (raw.actions !== undefined)
     out.actions = validateActions(ctx, raw.actions);
+  if (raw.looks !== undefined) out.looks = validateLooks(ctx, raw.looks);
   if (raw.helpers !== undefined)
     out.helpers = validateHelpers(ctx, raw.helpers);
   // [LAW:one-source-of-truth] Group sugar synthesis runs AFTER every section
@@ -269,5 +271,6 @@ const TOP_LEVEL_KEYS = new Set([
   "layout",
   "root",
   "actions",
+  "looks",
   "helpers",
 ]);

package/src/config/dsl-types.ts

@@ -14,6 +14,12 @@
 // references it here. The dependency is one-way (this file → action.ts), never
 // the reverse, so that shape can be lifted out without a cycle.
 import type { ActionDecl } from "./action.js";
+// [LAW:one-source-of-truth] A look IS a rich-js ThemeKey (four numeric axes:
+// hueShift / chromaScale / lightnessScale / lightnessShift) — the config type
+// references the vocabulary owner's type verbatim, so a rich-js axis rename is
+// a compile error here, never silent drift. Type-only: no runtime rich-js
+// dependency enters the config layer.
+import type { ThemeKey } from "@promptctl/rich-js";
 import type {
   Charset,
   ColorCompatibility,
@@ -129,6 +135,11 @@ export interface RawDslConfig {
   readonly segments?: Readonly<Record<string, SegmentDecl>>;
   readonly root?: LayoutNode;
   readonly actions?: Readonly<Record<string, ActionDecl>>;
+  // Named theme-adaptation bundles ("looks"): each is a full ThemeKey (the
+  // loader normalizes absent axes to identity at parse). Applied ON TOP of the
+  // active theme at render — a transform composing with every theme, selected
+  // per session exactly like theme/style (session key `look`).
+  readonly looks?: Readonly<Record<string, ThemeKey>>;
   // [LAW:single-enforcer] Config-level shared helper templates: name → Go-template
   // body. Each compiles to one `{{ define "name" }}body{{ end }}` block, and the
   // whole set into a single output-neutral preamble prepended to every template
@@ -153,6 +164,13 @@ export interface DslConfig {
   // template cannot smuggle an un-gated write. Empty when no config declares
   // actions — an absent `actions` key merges to `{}`.
   readonly actions: Readonly<Record<string, ActionDecl>>;
+  // [LAW:one-source-of-truth] The effective look set: name → full ThemeKey.
+  // Merges by name with the bundled default (user wins per name), like
+  // segments/actions/variables — so the default's `none` (the identity look and
+  // the resolution floor of effectiveLookName) is present in EVERY merged
+  // config by construction. An action `{ set: …, from: "looks" }` ranges these
+  // names; the derived click gate and the rendered options read this one map.
+  readonly looks: Readonly<Record<string, ThemeKey>>;
   // [LAW:single-enforcer] The effective helper set: a name → template-body map
   // compiled to a defines-preamble at registerDslConfig. Empty when no config
   // declares helpers — an absent `helpers` key merges to `{}` (same cascade as
@@ -186,6 +204,16 @@ export interface Globals {
   // `palette` is an explicit override that ignores the session theme.
   readonly palette?: string;
 
+  // [LAW:one-type-per-behavior] The config default for the LOOK (a named
+  // theme-adaptation from the `looks` block) — the exact twin of `palette` one
+  // dimension over: the daemon resolves the live look per render as
+  // `sessionState.look ?? globals.look ?? "none"` (effectiveLookName), so a
+  // look click recolors the bar live and a config can set a default adaptation
+  // without an edit-per-session. Membership in the merged `looks` map is
+  // validated post-merge (cross-ref) — a user's globals.look may name a
+  // default-provided look.
+  readonly look?: string;
+
   // [LAW:one-type-per-behavior] The config default for the powerline cap/
   // separator SHAPE — the exact twin of `palette` one dimension over: the
   // daemon resolves the live strip style per render as

package/src/config/loader/cross-ref.ts

@@ -36,6 +36,20 @@ export function validateCrossReferences(
   ctx: ValidateCtx,
   cfg: DslConfig,
 ): void {
+  // [LAW:locality-or-seam] globals.look names a member of the MERGED looks
+  // block (a user's default may be a bundled look — same reason every cross-ref
+  // runs post-merge). Same existence-check shape as layout→segments; an unknown
+  // name is a load error, never a silent identity fallback.
+  if (
+    cfg.globals.look !== undefined &&
+    !Object.prototype.hasOwnProperty.call(cfg.looks, cfg.globals.look)
+  ) {
+    ctx.issues.push({
+      path: "globals.look",
+      message: `globals.look "${cfg.globals.look}" does not match any declared look (have: ${Object.keys(cfg.looks).join(", ")})`,
+      line: findKeyLine(ctx.source, ["globals", "look"]),
+    });
+  }
   // [LAW:one-source-of-truth] THE set of resolvable variable names — a
   // faithful mirror of the runtime store's key set (declareOne in
   // src/dsl/render.ts registers globals under their bare names and segment

package/src/config/loader/emit-schema.ts

@@ -16,6 +16,7 @@ import { globalsJson } from "./globals.js";
 import { variablesMapJson } from "./variables.js";
 import { segmentsJson } from "./segments.js";
 import { actionsJson } from "./actions.js";
+import { looksJson } from "./looks.js";
 import {
   layoutNodeJson,
   LAYOUT_NODE_DEF_NAME,
@@ -46,6 +47,7 @@ export function emitConfigSchema(): JsonNode {
       segments: segmentsJson(),
       root: { $ref: LAYOUT_NODE_REF },
       actions: actionsJson(),
+      looks: looksJson(),
       helpers: { type: "object", additionalProperties: { type: "string" } },
     },
     definitions: {

package/src/config/loader/globals.ts

@@ -62,6 +62,12 @@ const GLOBALS_SCHEMA: RecordSchema<Globals> = {
     default_separator: optionalStringSpec(),
     default_truncate_marker: optionalStringSpec(),
     palette: paletteSpec(),
+    // [LAW:types-are-the-program] The config-default LOOK name. Unlike the
+    // registry-static palette set, the look domain is per-config (the merged
+    // `looks` block), so membership is a cross-ref check on the MERGED config —
+    // a user's globals.look may name a default-provided look. Shape-only here,
+    // exactly the shape/meaning split paletteSpec's schema facet keeps.
+    look: optionalStringSpec(),
     // [LAW:types-are-the-program] The strip style is a CLOSED enum (the powerline
     // shapes the joiner can render), unlike the open-ended palette NAME — so it
     // validates by membership and emits a JSON-Schema `enum`.

package/src/config/loader/layout.ts

@@ -575,14 +575,18 @@ export function synthesizeGroupDecls(
   ctx: ValidateCtx,
   out: Mutable<RawDslConfig>,
 ): void {
-  const groups = ctx.groups;
-  if (groups.length === 0) return;
-
   // [LAW:single-enforcer] The disclosure primitive's shared reserved-namespace
   // enforcer (mirroring {{ menu }}'s `menus.`) — a user name under `groups.`
-  // would silently shadow a synthesized artifact.
+  // would silently shadow a synthesized artifact. Reserved UNCONDITIONALLY,
+  // before the no-groups early return, so the reservation is a stable contract
+  // ("you never author groups.*"), not a rule that only switches on when a
+  // group node happens to be declared this load — same placement as the menus
+  // pass (synthesizeMenuDecls).
   reservedNamespaceCollisions(ctx, out, GROUP_NS, "group nodes");
 
+  const groups = ctx.groups;
+  if (groups.length === 0) return;
+
   const seen = new Set<string>();
   for (const g of groups) {
     if (seen.has(g.name)) {

package/src/config/loader/looks.ts

@@ -0,0 +1,96 @@
+// [LAW:types-are-the-program] The `looks` schema: each look is a named rich-js
+// ThemeKey — an ADAPTATION applied on top of whatever base theme is active (a
+// transform, not a palette), so one look composes with every theme. The config
+// spelling mirrors ThemeKey's field names VERBATIM (hueShift / chromaScale /
+// lightnessScale / lightnessShift) and the parsed output IS a rich-js ThemeKey —
+// no translation layer to drift, and a rich-js field rename fails this module's
+// compile instead of silently diverging. [LAW:one-source-of-truth]
+//
+// The adaptation vocabulary is CAPPED at ThemeKey's four axes. Role remap (the
+// old surface/button "role emphasis") is deferred; its exit plan is a future
+// rich-js resolver-level role→role operation carried as an additive `roles`
+// field here — growing the vocabulary means growing rich-js, never adding color
+// math to cc-candybar.
+
+import type { ThemeKey } from "@promptctl/rich-js";
+import { IDENTITY } from "@promptctl/rich-js";
+import {
+  describeType,
+  isPlainObject,
+  optionalNumberSpec,
+  record,
+  recordJson,
+  type JsonNode,
+  type RecordSchema,
+  type ValidateCtx,
+} from "./validate-core.js";
+import { findKeyLine } from "./diagnostics.js";
+
+// [LAW:types-are-the-program] The AUTHORING shape: every axis optional, absent =
+// identity. Distinct from ThemeKey (all fields required) so the record engine's
+// omit-absent output is honestly typed; validateLooks normalizes each parsed
+// spec onto IDENTITY, and past this module a partial look is unrepresentable.
+interface LookSpec {
+  readonly hueShift?: number;
+  readonly chromaScale?: number;
+  readonly lightnessScale?: number;
+  readonly lightnessShift?: number;
+}
+
+// [LAW:one-source-of-truth] The four axes, declared once as DATA the record
+// engine interprets for both validation and schema emit. chromaScale is a
+// multiplier on saturation — negative chroma is not a color, so the one bound.
+const LOOK_SCHEMA: RecordSchema<LookSpec> = {
+  noun: "look key",
+  fields: {
+    hueShift: optionalNumberSpec(),
+    chromaScale: optionalNumberSpec({ min: 0 }),
+    lightnessScale: optionalNumberSpec(),
+    lightnessShift: optionalNumberSpec(),
+  },
+};
+
+// An absent looks block is handled by the caller (absence survives the parse);
+// a non-object is a reported error recovering to empty — parseDslConfig throws
+// once any issue exists, so the recovery value never renders.
+export function validateLooks(
+  ctx: ValidateCtx,
+  raw: unknown,
+): Readonly<Record<string, ThemeKey>> {
+  if (!isPlainObject(raw)) {
+    ctx.issues.push({
+      path: "looks",
+      message: `looks must be an object mapping look names to adaptation objects, got ${describeType(raw)}`,
+      line: findKeyLine(ctx.source, ["looks"]),
+    });
+    return {};
+  }
+  const out: Record<string, ThemeKey> = {};
+  for (const [name, value] of Object.entries(raw)) {
+    // [LAW:no-silent-fallbacks] A look name is a deliverable set-state value —
+    // a look picker writes it on the wire, which rejects empty values and
+    // splits on "/". Rejecting the shape HERE surfaces the error on every
+    // config load, not only once an action ranges the "looks" domain (the same
+    // wire shape cycle members and `to` literals enforce in actions.ts).
+    if (name === "" || name.includes("/")) {
+      ctx.issues.push({
+        path: `looks.${name}`,
+        message: `look name ${JSON.stringify(name)} must be non-empty and slash-free — a look picker writes the name on the set-state wire, which rejects empty values and splits on "/"`,
+        line: findKeyLine(ctx.source, ["looks", name]),
+      });
+      continue;
+    }
+    const parsed = record(ctx, LOOK_SCHEMA, `looks.${name}`, value);
+    // [LAW:one-source-of-truth] Normalization onto IDENTITY is the single
+    // "absent axis = identity" site — downstream consumers receive a total
+    // ThemeKey and never re-default a missing axis.
+    if (parsed !== null) out[name] = { ...IDENTITY, ...parsed };
+  }
+  return out;
+}
+
+// [LAW:one-source-of-truth] The schema emitter derives from the SAME declaration
+// the validator interprets — a map of look names to the closed four-axis object.
+export function looksJson(): JsonNode {
+  return { type: "object", additionalProperties: recordJson(LOOK_SCHEMA) };
+}

package/src/config/loader/merge.ts

@@ -32,6 +32,10 @@ export function mergeWithDefault(
     // declares only the actions that differ from the bundled default (which
     // ships none).
     actions: { ...dflt.actions, ...(raw.actions ?? {}) },
+    // [LAW:one-source-of-truth] looks merge by name, same cascade — a user
+    // overrides one adaptation by re-declaring its name; the bundled stdlib
+    // (incl. the "none" identity floor) survives every merge by construction.
+    looks: { ...dflt.looks, ...(raw.looks ?? {}) },
     // [LAW:one-source-of-truth] helpers merge by name, same cascade — a user
     // overrides one formatter helper by re-declaring its name; the rest inherit
     // from the bundled default.

package/src/config/loader/validate-core.ts

@@ -582,6 +582,41 @@ export function optionalIntSpec(bounds: {
   };
 }
 
+// [LAW:dataflow-not-control-flow] An optional finite-number field: the optional
+// lower bound is DATA feeding both interpreters — `parse` checks it and
+// interpolates it into the one message, `json` emits it as `minimum` — so the
+// validator and the editor-facing schema cannot describe different ranges.
+// Finite matters: JSON5 admits `NaN`/`Infinity` literals, and a non-finite axis
+// would corrupt every OKLCH channel it touches downstream.
+export function optionalNumberSpec(
+  bounds: { readonly min?: number } = {},
+): FieldSpec<number> {
+  const { min } = bounds;
+  return {
+    required: false,
+    json: { type: "number", ...(min !== undefined && { minimum: min }) },
+    parse: (ctx, path, field, raw) => {
+      const v = raw[field];
+      if (v === undefined) return undefined;
+      const bad =
+        typeof v !== "number" ||
+        !Number.isFinite(v) ||
+        (min !== undefined && v < min);
+      if (bad) {
+        const shape =
+          min !== undefined ? `a finite number >= ${min}` : "a finite number";
+        ctx.issues.push({
+          path: `${path}.${field}`,
+          message: `${field} must be ${shape}, got ${describeValue(v)}`,
+          line: findKeyLine(ctx.source, [field]),
+        });
+        return undefined;
+      }
+      return v;
+    },
+  };
+}
+
 // [LAW:single-enforcer] The palette field defers to the one palette-name
 // authority; the field key is conventionally "palette", which validatePaletteName
 // reads directly.

package/src/daemon/render-payload.ts

@@ -63,6 +63,12 @@ export interface RenderPayload extends ClaudeHookData {
   // domain truth is "always present". A `?` here would let a callsite believe it
   // could be undefined and guard defensively against an impossibility.
   readonly theme: { readonly effective: string };
+  // [LAW:one-type-per-behavior] The daemon-resolved effective LOOK name —
+  // effectiveLookName(sessionState.look, globals.look, looks) — the exact twin
+  // of `theme` one dimension over: the SAME name whose ThemeKey adapts the
+  // rendered palette, surfaced so a trigger label can display the active look.
+  // Required for the same reason as theme: resolved unconditionally per render.
+  readonly look: { readonly effective: string };
 
   // Usage-family. Each provider returns null when it has no data (no
   // transcript yet, no rate-limit window active, etc.); we drop the field
@@ -582,6 +588,11 @@ export async function buildRenderPayload(
   // in (not re-resolved here) because the daemon already computes it for the
   // palette; this is that same value, threaded to the sole payload assembler.
   effectiveTheme: string,
+  // [LAW:one-source-of-truth] The effective look name, resolved ONCE by the
+  // daemon beside the theme (effectiveLookName over SessionState/globals/looks)
+  // and used for BOTH the rendered adaptation and this payload field — so a
+  // trigger label reading `.look.effective` can never disagree with the colors.
+  effectiveLook: string,
 ): Promise<RenderPayload> {
   const wants = (prefix: string): boolean =>
     anyPathStartsWith(neededInputPaths, prefix);
@@ -788,6 +799,8 @@ export async function buildRenderPayload(
     // No `wants` gate: it costs nothing (a string already in hand) and a
     // config that reads `.theme.effective` must always find it.
     theme: { effective: effectiveTheme },
+    // Same contract as theme: always present, a string already in hand.
+    look: { effective: effectiveLook },
     ...(sessionPayload !== undefined && { session: sessionPayload }),
     ...(todayPayload !== undefined && { today: todayPayload }),
     ...(costPerHour !== undefined && { burn: { costPerHour } }),

package/src/daemon/server.ts

@@ -59,6 +59,8 @@ import { renderDsl } from "../dsl/render.js";
 import {
   effectiveStripStyle,
   effectiveThemeName,
+  effectiveLookName,
+  lookKeyByName,
   resolverForThemeName,
 } from "../themes/index.js";
 import {
@@ -802,12 +804,24 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
           sessionState.get(req.hookData.session_id, "theme"),
           entry.state.config.globals.palette,
         );
+        // [LAW:one-type-per-behavior] The LOOK, resolved per render the exact
+        // way the theme is: the session's clicked look (SessionState) over the
+        // config default over the "none" floor — so a look click recolors the
+        // whole bar on the next render, composing with whatever theme is
+        // active. The name feeds the payload's `look.effective`; its ThemeKey
+        // (lookKeyByName) feeds renderDsl below — one resolution, two readers.
+        const effectiveLook = effectiveLookName(
+          sessionState.get(req.hookData.session_id, "look"),
+          entry.state.config.globals.look,
+          entry.state.config.looks,
+        );
         const payload = await buildRenderPayload(
           req.hookData,
           payloadDeps,
           req.cwd,
           entry.state.neededInputPaths,
           effectiveTheme,
+          effectiveLook,
         );
         // [LAW:one-source-of-truth][LAW:dataflow-not-control-flow] basePalette
         // is derived from the same effective theme resolved above — so a theme
@@ -869,7 +883,8 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
           // in place. Cells are cheap (already computed during the render);
           // the per-segment ANSI serialization happens lazily inside the
           // debug handler so normal renders pay no extra serializer cost.
-          entry.state.lastRenderCellsBySegment,
+          { perSegmentSink: entry.state.lastRenderCellsBySegment },
+          lookKeyByName(entry.state.config.looks, effectiveLook),
         );
       }
       // [LAW:one-source-of-truth] Consume the transient click error written by

package/src/daemon/verbs/state-validators.ts

@@ -431,11 +431,18 @@ export function makeRangeValidator(
 }
 
 // [LAW:one-source-of-truth] The option members a picker draws from ARE the same
-// canonical lists the `themes()`/`styles()` bindings and the baseline theme/
-// style validators consult — the rendered options and the derived gate cannot
-// diverge because there is no second enumeration.
-function optionValuesFor(src: OptionSource): readonly string[] {
-  return src === "themes" ? RESOLVABLE_THEMES_LIST : STRIP_STYLES;
+// canonical lists the `themes()`/`styles()`/`looks()` bindings and the baseline
+// theme/style validators consult — the rendered options and the derived gate
+// cannot diverge because there is no second enumeration. "looks" is the one
+// per-config domain: its names come from the config's merged looks block,
+// threaded in as data (the render-side optionDomain takes the same list).
+function optionValuesFor(
+  src: OptionSource,
+  lookNames: readonly string[],
+): readonly string[] {
+  if (src === "themes") return RESOLVABLE_THEMES_LIST;
+  if (src === "styles") return STRIP_STYLES;
+  return lookNames;
 }
 
 // [LAW:types-are-the-program] Collapse one key's spec contributions into the
@@ -564,6 +571,7 @@ function mergeContributions(
 function actionKeySpecs(
   a: ActionDecl,
   seeds: ReadonlyMap<string, number>,
+  lookNames: readonly string[],
 ): KeySpecContribution[] {
   if (!("set" in a)) return [];
   if ("to" in a) {
@@ -573,7 +581,10 @@ function actionKeySpecs(
     return [
       {
         key: a.set,
-        spec: { kind: "allow-list", allowed: optionValuesFor(a.from) },
+        spec: {
+          kind: "allow-list",
+          allowed: optionValuesFor(a.from, lookNames),
+        },
       },
     ];
   }
@@ -635,8 +646,11 @@ function stateKeySeeds(config: DslConfig): ReadonlyMap<string, number> {
 // realizes a click from are the gate the wire enforces.
 function actionContributions(config: DslConfig): KeySpecContribution[] {
   const seeds = stateKeySeeds(config);
+  const lookNames = Object.keys(config.looks);
   return dropBaselineAllowLists(
-    Object.values(config.actions).flatMap((a) => actionKeySpecs(a, seeds)),
+    Object.values(config.actions).flatMap((a) =>
+      actionKeySpecs(a, seeds, lookNames),
+    ),
   );
 }
 

package/src/demo/dsl.ts

@@ -29,7 +29,12 @@ import { VariableStore } from "../var-system/store.js";
 import { SourceRegistry } from "../var-system/sources.js";
 import { SessionState } from "../daemon/session-state.js";
 import { listResolvablePaletteNames } from "../themes/policy.js";
-import { effectiveThemeName, resolverForThemeName } from "../themes/index.js";
+import {
+  effectiveThemeName,
+  effectiveLookName,
+  lookKeyByName,
+  resolverForThemeName,
+} from "../themes/index.js";
 import { registerDslConfig, renderDsl } from "../dsl/render.js";
 import {
   DEFAULT_CHARSET,
@@ -75,6 +80,13 @@ const payload = {
 const basePalette = resolverForThemeName(
   effectiveThemeName(null, config.globals.palette),
 );
+// Same fresh-session resolution one dimension over: the config-default look
+// over the "none" identity floor — the exact mirror of the daemon's per-render
+// effectiveLookName → lookKeyByName chain.
+const lookKey = lookKeyByName(
+  config.looks,
+  effectiveLookName(null, config.globals.look, config.looks),
+);
 
 // A fresh store + registry for this run. (A hot-reloading daemon would
 // dispose() the old pair and build new ones — see registerDslConfig's docs.)
@@ -125,6 +137,8 @@ try {
         padding: config.globals.padding ?? DEFAULT_PADDING,
         charset: config.globals.charset ?? DEFAULT_CHARSET,
       },
+      undefined,
+      lookKey,
     );
     process.stdout.write(`  ${line}\n`);
     if (frame < FRAMES - 1) await sleep(FRAME_INTERVAL_MS);

package/src/dsl/node-registry.ts

@@ -22,8 +22,8 @@
 // carries NO structural meaning — unit cohesion is structural (one segment = one
 // strip item), not a function of matching backgrounds.
 
-import { RichText } from "@promptctl/rich-js";
-import type { PaletteResolver, Style } from "@promptctl/rich-js";
+import { RichText, IDENTITY } from "@promptctl/rich-js";
+import type { PaletteResolver, Style, ThemeKey } from "@promptctl/rich-js";
 import type { Template } from "@promptctl/go-template-js";
 import type {
   LayoutNode,
@@ -100,6 +100,12 @@ export interface NodeCompileCtx {
 export interface NodeRenderCtx {
   readonly scope: object;
   readonly basePalette: PaletteResolver;
+  // [LAW:one-source-of-truth] The render-wide look (the session's chosen
+  // theme-adaptation, resolved by the caller via effectiveLookName →
+  // lookKeyByName), threaded by the driver — one ThemeKey per render, IDENTITY
+  // when no look is chosen. Composed with the per-segment hue shift into ONE
+  // transposition key at the segment leaf.
+  readonly look: ThemeKey;
   readonly visible: boolean;
   // [LAW:one-source-of-truth] The render-wide intra-cell padding (resolved
   // globals.padding), threaded by the driver from BuildLineOptions into every
@@ -108,6 +114,13 @@ export interface NodeRenderCtx {
   // Advance the walk-owned hue cursor by one unit and return that unit's shift.
   nextHueShift(): number;
   readonly perSegmentSink?: Map<string, readonly RichText[]>;
+  // [LAW:no-silent-failure] Optional observer for the per-segment render catch
+  // below: a caught evaluation error renders as a visible ⚠ error cell (partial
+  // rendering — the daemon's channel), AND is reported here so a headless caller
+  // (`cc-candybar check`, a blind authoring agent's eyes) can turn it into a
+  // text verdict instead of blessing a bar it cannot see. Trusted non-throwing
+  // (the registry-dispose contract) — see RenderObservers.onSegmentError.
+  readonly onSegmentError?: (segName: string, message: string) => void;
   // [LAW:locality-or-seam] The menu seam, injected as capabilities so this module
   // never imports the menu feature. `beginSegment` runs BEFORE a segment template
   // evaluates: it publishes the segment name so a `{{ menu }}` can derive its
@@ -261,10 +274,19 @@ const segmentType: NodeType<"segment"> = {
 
       // [LAW:dataflow-not-control-flow] The per-segment variability is WHICH
       // palette — the base resolver (per-segment override or basePalette)
-      // transposed by hueShift. bg and fg then resolve from this one palette.
+      // transposed by the render's look + this segment's hueShift, folded into
+      // ONE ThemeKey for a SINGLE transposePalette call (chaining two
+      // transpositions would double-pay OKLCH quantization and collide the
+      // transpose memo — see transposedResolver). bg and fg then resolve from
+      // this one palette. An explicit per-segment `palette:` pin IGNORES the
+      // look, exactly as it ignores the session theme: the pin's presence is
+      // the discriminator, and its arm carries the identity look — a value
+      // choice, not a skipped operation.
+      const lookKey =
+        segCompiled.paletteResolver !== undefined ? IDENTITY : ctx.look;
       const resolver = transposedResolver(
         segCompiled.paletteResolver ?? ctx.basePalette,
-        hueShift,
+        { ...lookKey, hueShift: lookKey.hueShift + hueShift },
       );
       const resolvedStyle = resolveSegmentColors(
         resolver,
@@ -312,13 +334,9 @@ const segmentType: NodeType<"segment"> = {
       }
       return laidLines;
     } catch (err) {
-      return [
-        [
-          new RichText(
-            `⚠ ${node.name}: ${(err as Error).message ?? String(err)}`,
-          ),
-        ],
-      ];
+      const message = (err as Error).message ?? String(err);
+      ctx.onSegmentError?.(node.name, message);
+      return [[new RichText(`⚠ ${node.name}: ${message}`)]];
     }
   },
 };