@promptctl/cc-candybar 1.20.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Statusline renderer for Claude Code — a JSON5-configurable DSL with daemon-cached data sources, byte-clean palette-aware composition, and OSC8 click verbs.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -95,10 +95,10 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.20.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.20.0",
-    "@promptctl/cc-candybar-linux-x64": "1.20.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.20.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.21.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.21.0",
+    "@promptctl/cc-candybar-linux-x64": "1.21.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.21.0"
   },
   "pnpm": {
     "supportedArchitectures": {

package/schema/cc-candybar.schema.json

@@ -26,6 +26,9 @@
         "palette": {
           "type": "string"
         },
+        "look": {
+          "type": "string"
+        },
         "style": {
           "enum": [
             "powerline",
@@ -1140,7 +1143,8 @@
               "from": {
                 "enum": [
                   "themes",
-                  "styles"
+                  "styles",
+                  "looks"
                 ]
               }
             },
@@ -1239,6 +1243,28 @@
         ]
       }
     },
+    "looks": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "hueShift": {
+            "type": "number"
+          },
+          "chromaScale": {
+            "type": "number",
+            "minimum": 0
+          },
+          "lightnessScale": {
+            "type": "number"
+          },
+          "lightnessShift": {
+            "type": "number"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "helpers": {
       "type": "object",
       "additionalProperties": {

package/src/check.ts

@@ -30,7 +30,12 @@ import { SourceRegistry } from "./var-system/sources.js";
 import { SessionState } from "./daemon/session-state.js";
 import { registerDslConfig, renderDsl } from "./dsl/render.js";
 import { deriveActionValidators } from "./daemon/verbs/state-validators.js";
-import { effectiveThemeName, effectiveStripStyle } from "./themes/policy.js";
+import {
+  effectiveThemeName,
+  effectiveLookName,
+  lookKeyByName,
+  effectiveStripStyle,
+} from "./themes/policy.js";
 import { resolverForThemeName } from "./themes/palette-resolvers.js";
 import {
   DEFAULT_CHARSET,
@@ -61,7 +66,10 @@ const CHECK_WIDTH = 200;
 // test/example-configs.test.ts asserts rendered content against these literal
 // values (780s → "◷ 13m", cost $0.39, version 1.15.0, …); changing one here
 // fails that suite loudly rather than drifting silently.
-export function checkPayload(effectiveTheme: string): Record<string, unknown> {
+export function checkPayload(
+  effectiveTheme: string,
+  effectiveLook: string,
+): Record<string, unknown> {
   const home = "/home/tester";
   const nowSec = Math.floor(Date.now() / 1000);
   return {
@@ -108,6 +116,7 @@ export function checkPayload(effectiveTheme: string): Record<string, unknown> {
     cache: { expiresAt: nowSec + 15 * 60 },
     tmux: { session: "work" },
     theme: { effective: effectiveTheme },
+    look: { effective: effectiveLook },
   };
 }
 
@@ -265,12 +274,28 @@ function loadRegisterRender(
     // resolution is null — the config default over the floor, exactly what the
     // daemon renders for a session that has never clicked.
     const effectiveTheme = effectiveThemeName(null, config.globals.palette);
-    return renderDsl(
+    // Same fresh-session shape one dimension over: no clicked look, so the
+    // config default over the "none" floor — exactly what the daemon renders
+    // for a session that has never clicked.
+    const effectiveLook = effectiveLookName(
+      null,
+      config.globals.look,
+      config.looks,
+    );
+    // [LAW:no-silent-failure] A segment whose template THROWS while evaluating
+    // (an `{{ action }}` display-arity mismatch, a MissingFieldError from a
+    // partially-declared variable) renders as a visible ⚠ error cell — partial
+    // rendering, the daemon's channel for a human looking at the bar. The blind
+    // authoring agent is not looking at the bar; check collects the same errors
+    // through the render's observer seam and fails the verdict, so exit 0 never
+    // blesses a bar that renders ⚠.
+    const segmentErrors: string[] = [];
+    const rendered = renderDsl(
       config,
       compiled,
       store,
       registry,
-      checkPayload(effectiveTheme),
+      checkPayload(effectiveTheme, effectiveLook),
       resolverForThemeName(effectiveTheme),
       {
         style: effectiveStripStyle(null, config.globals.style),
@@ -281,7 +306,21 @@ function loadRegisterRender(
         padding: config.globals.padding ?? DEFAULT_PADDING,
         charset: config.globals.charset ?? DEFAULT_CHARSET,
       },
+      {
+        onSegmentError: (segName, message) =>
+          segmentErrors.push(`segment "${segName}": ${message}`),
+      },
+      lookKeyByName(config.looks, effectiveLook),
     );
+    if (segmentErrors.length > 0) {
+      throw new Error(
+        `config renders with ${segmentErrors.length} segment error${
+          segmentErrors.length === 1 ? "" : "s"
+        } (the daemon would render ⚠ error cells):\n` +
+          segmentErrors.map((m) => `  ${m}`).join("\n"),
+      );
+    }
+    return rendered;
   } finally {
     // [LAW:single-enforcer] The registry owns every async handle the config
     // declared (timers, fs watchers, git subscriptions); a one-shot check must

package/src/config/action.ts

@@ -25,11 +25,18 @@
 // discriminator the loader and the validator-derivation match on.
 
 // [LAW:one-source-of-truth] The domain lists a picker draws options from. Same
-// canonical sources the `themes()`/`styles()` bindings and the set-state
-// validators consult — the rendered options and the derived gate cannot diverge
-// because there is no second enumeration.
-export type OptionSource = "themes" | "styles";
-export const OPTION_SOURCES: readonly OptionSource[] = ["themes", "styles"];
+// canonical sources the `themes()`/`styles()`/`looks()` bindings and the
+// set-state validators consult — the rendered options and the derived gate
+// cannot diverge because there is no second enumeration. themes/styles are
+// static registry lists; "looks" is the one PER-CONFIG domain (the merged
+// `looks` block's names), so its resolution sites take the config's look names
+// as data rather than consulting a module constant.
+export type OptionSource = "themes" | "styles" | "looks";
+export const OPTION_SOURCES: readonly OptionSource[] = [
+  "themes",
+  "styles",
+  "looks",
+];
 
 // [LAW:types-are-the-program] The top-level discriminator of an ActionDecl — the
 // click effect is keyed by which of these is present. The loader proves

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/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