@promptctl/cc-candybar 1.11.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.11.0",
+  "version": "1.12.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",
@@ -91,10 +91,10 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.11.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.11.0",
-    "@promptctl/cc-candybar-linux-x64": "1.11.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.11.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.12.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.12.0",
+    "@promptctl/cc-candybar-linux-x64": "1.12.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.12.0"
   },
   "pnpm": {
     "supportedArchitectures": {

package/schema/cc-candybar.schema.json

@@ -46,6 +46,14 @@
             "unicode",
             "ascii"
           ]
+        },
+        "colorCompatibility": {
+          "enum": [
+            "truecolor",
+            "256",
+            "ansi",
+            "none"
+          ]
         }
       },
       "additionalProperties": false

package/src/config/dsl-types.ts

@@ -14,7 +14,11 @@
 // 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";
-import type { Charset, StripStyle } from "../themes/policy.js";
+import type {
+  Charset,
+  ColorCompatibility,
+  StripStyle,
+} from "../themes/policy.js";
 
 // [LAW:types-are-the-program] Three stages, three names.
 //
@@ -213,6 +217,15 @@ export interface Globals {
   // [config-only] The daemon resolves `globals.charset ?? "unicode"` into
   // renderOpts.charset; no SessionState/click half.
   readonly charset?: Charset;
+
+  // The legacy display.colorCompatibility knob: the color depth rich-js
+  // downsamples output to. Default "truecolor" (current behavior — NOT the
+  // legacy "auto" default, which would change rendering for existing users).
+  // The type excludes "auto" entirely: the daemon is detached, so env
+  // detection would read the wrong terminal — see COLOR_COMPATIBILITIES.
+  // [config-only] The daemon resolves `globals.colorCompatibility ??
+  // "truecolor"` into renderOpts.colorCompatibility; no SessionState/click half.
+  readonly colorCompatibility?: ColorCompatibility;
 }
 
 // [LAW:one-type-per-behavior] One discriminated union covers every source

package/src/config/loader/globals.ts

@@ -4,19 +4,54 @@
 // add a key to GLOBALS_SCHEMA and Globals; the engine does the rest.
 
 import { type Globals } from "../dsl-types.js";
-import { CHARSETS, STRIP_STYLES } from "../../themes/policy.js";
+import {
+  CHARSETS,
+  COLOR_COMPATIBILITIES,
+  STRIP_STYLES,
+  type ColorCompatibility,
+} from "../../themes/policy.js";
 import {
   optionalBooleanSpec,
+  optionalEnum,
   optionalEnumSpec,
   optionalIntSpec,
   optionalStringSpec,
   paletteSpec,
   record,
   recordJson,
+  type FieldSpec,
   type JsonNode,
   type RecordSchema,
   type ValidateCtx,
 } from "./validate-core.js";
+import { findKeyLine } from "./diagnostics.js";
+
+// [LAW:types-are-the-program] Closed enum like `charset`, plus one
+// migration-pointing rejection: "auto" was the LEGACY default, so migrating
+// configs will carry it — but the daemon runs detached, so rich-js env
+// detection would downsample against the daemon's terminal, not the client's.
+// Rather than ship that silent lie [LAW:no-silent-failure], "auto" is outside
+// the ColorCompatibility domain and gets an error that says why (same species
+// as the removed-layout migration errors in layout.ts). The json emit and the
+// membership check derive from the same COLOR_COMPATIBILITIES literal.
+const colorCompatibilitySpec: FieldSpec<ColorCompatibility> = {
+  required: false,
+  json: { enum: [...COLOR_COMPATIBILITIES] },
+  parse: (ctx, path, field, raw) => {
+    if (raw[field] === "auto") {
+      ctx.issues.push({
+        path: `${path}.${field}`,
+        message:
+          `${path}.${field}: "auto" is not supported — the render daemon runs detached, ` +
+          `so terminal detection would read the daemon's environment, not your terminal's. ` +
+          `Pick an explicit depth: ${COLOR_COMPATIBILITIES.join(", ")}`,
+        line: findKeyLine(ctx.source, [...path.split("."), field]),
+      });
+      return undefined;
+    }
+    return optionalEnum(ctx, path, raw, field, COLOR_COMPATIBILITIES);
+  },
+};
 
 const GLOBALS_SCHEMA: RecordSchema<Globals> = {
   noun: "globals key",
@@ -41,6 +76,8 @@ const GLOBALS_SCHEMA: RecordSchema<Globals> = {
     // vocabularies pickJoiner can render — validates by membership, emits a
     // JSON-Schema `enum` from the same CHARSETS literal.
     charset: optionalEnumSpec(CHARSETS),
+    // Closed enum with a bespoke "auto" rejection — see colorCompatibilitySpec.
+    colorCompatibility: colorCompatibilitySpec,
   },
 };
 

package/src/daemon/server.ts

@@ -47,11 +47,13 @@ import {
 import {
   renderStripCells,
   DEFAULT_CHARSET,
+  DEFAULT_COLOR_COMPATIBILITY,
   DEFAULT_PADDING,
   DEFAULT_TERMINAL_WIDTH,
   DEFAULT_WRAP,
   type BuildLineOptions,
   type Charset,
+  type ColorCompatibility,
 } from "../render/strip.js";
 import { applyClaudeCodeReserve } from "../utils/terminal-width.js";
 import type { RichText } from "@promptctl/rich-js";
@@ -788,6 +790,13 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
         // [LAW:one-source-of-truth]
         renderOpts.charset =
           entry.state.config.globals.charset ?? DEFAULT_CHARSET;
+        // [config-only] globals.colorCompatibility, same shape as charset:
+        // the config global over the base floor is the whole resolution —
+        // the ONE home of the color-depth choice rich-js downsamples to.
+        // [LAW:one-source-of-truth]
+        renderOpts.colorCompatibility =
+          entry.state.config.globals.colorCompatibility ??
+          DEFAULT_COLOR_COMPATIBILITY;
         // [LAW:single-enforcer] renderDsl internally calls
         // `registry.applyInput(payload)` as its first step (see step 1 in
         // src/dsl/render.ts). The daemon must not pre-apply — doing so
@@ -895,6 +904,8 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
                 ? serializeSegmentCells(
                     dbgEntry.lastRenderCellsBySegment,
                     dbgEntry.config.globals.charset ?? DEFAULT_CHARSET,
+                    dbgEntry.config.globals.colorCompatibility ??
+                      DEFAULT_COLOR_COMPATIBILITY,
                   )
                 : EMPTY_RENDER_MAP,
           };
@@ -1080,7 +1091,7 @@ const verbCtx = { sessionState, dlog };
 // is rendered standalone (wrap doesn't apply to a one-segment projection).
 const RENDER_OPTS_BASE = {
   style: "powerline" as const,
-  colorCompatibility: "truecolor" as const,
+  colorCompatibility: DEFAULT_COLOR_COMPATIBILITY,
   wrap: DEFAULT_WRAP,
   padding: DEFAULT_PADDING,
   charset: DEFAULT_CHARSET,
@@ -1095,21 +1106,26 @@ const DEBUG_RENDER_OPTS: BuildLineOptions = {
 // the DaemonDslState type requires the field.
 const EMPTY_RENDER_MAP = new Map<string, string>();
 
-// [LAW:one-source-of-truth] The joiner glyph vocabulary is a serialization-time
-// choice, and charset is config-only (no SessionState half) — so the faithful
-// value is fully derivable from the sampled entry's config, unlike style, whose
-// live session-over-config resolution needs a session a debug request doesn't
-// carry. The caller threads the entry-resolved charset; this serializer never
-// re-defaults it.
+// [LAW:one-source-of-truth] The joiner glyph vocabulary and the color depth
+// are serialization-time choices, and both are config-only (no SessionState
+// half) — so the faithful values are fully derivable from the sampled entry's
+// config, unlike style, whose live session-over-config resolution needs a
+// session a debug request doesn't carry. The caller threads the
+// entry-resolved values; this serializer never re-defaults them.
 function serializeSegmentCells(
   cells: ReadonlyMap<string, readonly RichText[]>,
   charset: Charset,
+  colorCompatibility: ColorCompatibility,
 ): Map<string, string> {
   const out = new Map<string, string>();
   for (const [name, segCells] of cells) {
     out.set(
       name,
-      renderStripCells(segCells, { ...DEBUG_RENDER_OPTS, charset }),
+      renderStripCells(segCells, {
+        ...DEBUG_RENDER_OPTS,
+        charset,
+        colorCompatibility,
+      }),
     );
   }
   return out;

package/src/demo/dsl.ts

@@ -33,6 +33,7 @@ import { effectiveThemeName, resolverForThemeName } from "../themes/index.js";
 import { registerDslConfig, renderDsl } from "../dsl/render.js";
 import {
   DEFAULT_CHARSET,
+  DEFAULT_COLOR_COMPATIBILITY,
   DEFAULT_PADDING,
   DEFAULT_TERMINAL_WIDTH,
   DEFAULT_WRAP,
@@ -108,7 +109,10 @@ try {
       basePalette,
       {
         style: "powerline",
-        colorCompatibility: "truecolor",
+        // Same resolution the daemon applies: the config global over the
+        // truecolor default floor.
+        colorCompatibility:
+          config.globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,
         // [LAW:one-source-of-truth] Demo applies the same Claude-Code-UI
         // reserve the daemon does so demo output matches the bytes a real
         // statusline would emit at the same terminal width.

package/src/render/strip.ts

@@ -8,11 +8,14 @@ import {
   FlexStrip,
   renderToString,
   type Joiner,
-  type ColorSystemSpec,
   type PowerlineJoinerOptions,
   type CapsuleJoinerOptions,
 } from "@promptctl/rich-js";
-import type { Charset, StripStyle } from "../themes/policy.js";
+import type {
+  Charset,
+  ColorCompatibility,
+  StripStyle,
+} from "../themes/policy.js";
 
 export interface RenderedSegmentLike {
   type: string;
@@ -25,7 +28,7 @@ export interface RenderedSegmentLike {
 // in themes/policy.ts (the render-identifier policy module, importable by the
 // option-source machinery without a render→template-engine cycle). Re-exported
 // here so render-layer consumers can keep importing them from the strip module.
-export type { Charset, StripStyle };
+export type { Charset, ColorCompatibility, StripStyle };
 
 // [LAW:one-source-of-truth] Raw terminal cols we assume when the wire
 // didn't give us one (older client, env-stripped spawn). RAW — not
@@ -51,9 +54,21 @@ export const DEFAULT_PADDING = 1;
 // (`globals.charset ?? DEFAULT_CHARSET`) derives from this constant.
 export const DEFAULT_CHARSET: Charset = "unicode";
 
+// [LAW:one-source-of-truth] The one statement of the globals.colorCompatibility
+// default (truecolor — the CURRENT pinned value, deliberately NOT the legacy
+// "auto" default, which would change rendering for existing users). Every
+// resolver of the config global (`globals.colorCompatibility ??
+// DEFAULT_COLOR_COMPATIBILITY`) derives from this constant.
+export const DEFAULT_COLOR_COMPATIBILITY: ColorCompatibility = "truecolor";
+
 export interface BuildLineOptions {
   style: StripStyle;
-  colorCompatibility: ColorSystemSpec;
+  // [LAW:types-are-the-program] Narrower than rich-js ColorSystemSpec on
+  // purpose: the four explicit depths only. "auto"/null never reach a render —
+  // the daemon is detached, so env detection would read the wrong terminal;
+  // the loader rejects "auto" at the trust boundary (see COLOR_COMPATIBILITIES
+  // in themes/policy.ts), and every construction site states a resolved depth.
+  colorCompatibility: ColorCompatibility;
   separator?: string;
   // [LAW:types-are-the-program] Every render carries a width. Required (not
   // optional) so callers cannot silently drop the wire's value.

package/src/themes/policy.ts

@@ -5,7 +5,7 @@
 // PaletteResolver, no ColorRgba, no hex. The semantic/anchor knowledge
 // (which tokens keep their hue) stays in rich-js (ANCHORED_ROOTS), not here.
 
-import { listThemePalettes } from "@promptctl/rich-js";
+import { listThemePalettes, type ColorSystemSpec } from "@promptctl/rich-js";
 
 // --- Theme name aliasing ---
 
@@ -96,3 +96,28 @@ export function effectiveStripStyle(
 // is the whole resolution.
 export const CHARSETS = ["unicode", "ascii"] as const;
 export type Charset = (typeof CHARSETS)[number];
+
+// --- Color-depth identifiers ---
+
+// [LAW:one-source-of-truth][LAW:types-are-the-program] The single canonical set
+// of color depths a config can pin (the legacy display.colorCompatibility).
+// Same species as CHARSETS: a closed render-vocabulary enum hosted in this leaf
+// policy module so the config loader (validation + JSON-schema emit) and the
+// render layer both derive from one literal without a config↔render cycle
+// [LAW:one-way-deps]. `satisfies` ties every member to rich-js's
+// ColorSystemSpec at compile time WITHOUT widening the derived union — if
+// rich-js renames a depth, this literal fails to compile rather than drifting.
+//
+// Deliberately NARROWER than ColorSystemSpec: "auto" (and null) are excluded.
+// The daemon is long-lived and detached, so its process env is NOT the client
+// terminal's — rich-js env detection would silently downsample against the
+// wrong terminal [LAW:no-silent-failure]. Honoring "auto" needs a client
+// capability hint over the wire (the termCols pattern); until that lands, the
+// loader rejects "auto" with a pointer instead of shipping a lie.
+export const COLOR_COMPATIBILITIES = [
+  "truecolor",
+  "256",
+  "ansi",
+  "none",
+] as const satisfies readonly ColorSystemSpec[];
+export type ColorCompatibility = (typeof COLOR_COMPATIBILITIES)[number];