@promptctl/cc-candybar 1.10.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.10.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.10.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.10.0",
-    "@promptctl/cc-candybar-linux-x64": "1.10.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.10.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

@@ -40,6 +40,20 @@
           "type": "integer",
           "minimum": 0,
           "maximum": 16
+        },
+        "charset": {
+          "enum": [
+            "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 { StripStyle } from "../themes/policy.js";
+import type {
+  Charset,
+  ColorCompatibility,
+  StripStyle,
+} from "../themes/policy.js";
 
 // [LAW:types-are-the-program] Three stages, three names.
 //
@@ -204,6 +208,24 @@ export interface Globals {
   // [config-only] The daemon resolves `globals.padding ?? 1` into
   // renderOpts.padding; no SessionState/click half.
   readonly padding?: number;
+
+  // The legacy display.charset knob: which glyph vocabulary the strip joiners
+  // render with. Default "unicode" (current behavior — rich-js's powerline
+  // caps, U+E0Bx). "ascii" swaps the caps for single-column ASCII glyphs so
+  // terminals/fonts without powerline glyphs render cleanly instead of tofu.
+  // Orthogonal to `style`: style picks the joiner shape, charset the glyphs.
+  // [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 { 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",
@@ -37,6 +72,12 @@ const GLOBALS_SCHEMA: RecordSchema<Globals> = {
     // [LAW:no-silent-failure] — an absurd value is a loud load error, not a
     // silently-huge render.
     padding: optionalIntSpec({ min: 0, max: 16 }),
+    // [LAW:types-are-the-program] Closed enum like `style`: the joiner glyph
+    // 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

@@ -46,10 +46,14 @@ import {
 } from "../themes/index.js";
 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";
@@ -780,6 +784,19 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
         // reserve) derives from. [LAW:one-source-of-truth]
         renderOpts.padding =
           entry.state.config.globals.padding ?? DEFAULT_PADDING;
+        // [config-only] globals.charset, same shape as autoWrap/padding: the
+        // config global over the base floor is the whole resolution — the ONE
+        // home of the glyph-vocabulary choice pickJoiner derives from.
+        // [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
@@ -884,7 +901,12 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
             compiled: dbgEntry.compiled,
             lastRenderBySegment:
               req.what === "segments"
-                ? serializeSegmentCells(dbgEntry.lastRenderCellsBySegment)
+                ? serializeSegmentCells(
+                    dbgEntry.lastRenderCellsBySegment,
+                    dbgEntry.config.globals.charset ?? DEFAULT_CHARSET,
+                    dbgEntry.config.globals.colorCompatibility ??
+                      DEFAULT_COLOR_COMPATIBILITY,
+                  )
                 : EMPTY_RENDER_MAP,
           };
     return stay({ ok: true, debug: buildDebugSnapshot(req.what, dbgState) });
@@ -1069,9 +1091,10 @@ 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,
 };
 const DEBUG_RENDER_OPTS: BuildLineOptions = {
   ...RENDER_OPTS_BASE,
@@ -1083,12 +1106,27 @@ 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 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));
+    out.set(
+      name,
+      renderStripCells(segCells, {
+        ...DEBUG_RENDER_OPTS,
+        charset,
+        colorCompatibility,
+      }),
+    );
   }
   return out;
 }

package/src/demo/dsl.ts

@@ -32,6 +32,8 @@ import { listResolvablePaletteNames } from "../themes/policy.js";
 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,
@@ -107,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.
@@ -118,6 +123,7 @@ try {
         // default-on floor.
         wrap: config.globals.autoWrap ?? DEFAULT_WRAP,
         padding: config.globals.padding ?? DEFAULT_PADDING,
+        charset: config.globals.charset ?? DEFAULT_CHARSET,
       },
     );
     process.stdout.write(`  ${line}\n`);

package/src/render/strip.ts

@@ -8,9 +8,14 @@ import {
   FlexStrip,
   renderToString,
   type Joiner,
-  type ColorSystemSpec,
+  type PowerlineJoinerOptions,
+  type CapsuleJoinerOptions,
 } from "@promptctl/rich-js";
-import type { StripStyle } from "../themes/policy.js";
+import type {
+  Charset,
+  ColorCompatibility,
+  StripStyle,
+} from "../themes/policy.js";
 
 export interface RenderedSegmentLike {
   type: string;
@@ -19,11 +24,11 @@ export interface RenderedSegmentLike {
   fgHex?: string;
 }
 
-// [LAW:one-source-of-truth] `StripStyle` and its value list live in
-// themes/policy.ts (the style-identifier policy module, importable by the
+// [LAW:one-source-of-truth] `StripStyle`/`Charset` and their value lists live
+// 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 it from the strip module.
-export type { StripStyle };
+// here so render-layer consumers can keep importing them from the strip module.
+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
@@ -43,9 +48,27 @@ export const DEFAULT_WRAP = true;
 // (`globals.padding ?? DEFAULT_PADDING`) derives from this constant.
 export const DEFAULT_PADDING = 1;
 
+// [LAW:one-source-of-truth] The one statement of the globals.charset default
+// (powerline unicode glyphs — current behavior, matching the legacy
+// display.charset). Every resolver of the config global
+// (`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.
@@ -65,20 +88,51 @@ export interface BuildLineOptions {
   // site states the resolved value; the cell builders derive from it and
   // never re-default.
   padding: number;
+  // [LAW:one-source-of-truth] Which glyph vocabulary the joiners render with
+  // (globals.charset, default "unicode" — the legacy display.charset).
+  // Required for the same reason as padding: the resolved value reaches every
+  // render explicitly; pickJoiner derives from it and never re-defaults.
+  charset: Charset;
 }
 
-function pickJoiner(style: StripStyle, separator?: string): Joiner {
+// [LAW:dataflow-not-control-flow] Charset variability lives in these VALUES,
+// not in branches: per style, each charset names the joiner-construction
+// options. The unicode entries are empty on purpose — rich-js owns its
+// canonical powerline glyphs (U+E0B0 / U+E0B6+U+E0B4) and restating them here
+// would be a second source that could drift [LAW:one-source-of-truth]. The
+// ascii glyphs are DELIBERATELY single-column (same display width as the
+// unicode caps) so stripChromeCols stays charset-invariant; the
+// measured-chrome pin in test/picker-pagination.test.ts checks that for every
+// style × charset. Widen a glyph and that pin fails loudly.
+const POWERLINE_GLYPHS: Record<Charset, PowerlineJoinerOptions> = {
+  unicode: {},
+  ascii: { glyph: ">" },
+};
+const CAPSULE_GLYPHS: Record<Charset, CapsuleJoinerOptions> = {
+  unicode: {},
+  ascii: { left: "(", right: ")" },
+};
+
+function pickJoiner(
+  style: StripStyle,
+  charset: Charset,
+  separator?: string,
+): Joiner {
   // [LAW:dataflow-not-control-flow] joiner choice is data-driven; one arm per
-  // shape. [LAW:types-are-the-program] Total over StripStyle — the `never`
+  // shape. Style picks the joiner CLASS, charset indexes the glyph options fed
+  // to it — the two dimensions stay orthogonal (any style renders under either
+  // charset). Plain takes no charset lookup: its separator is already user
+  // data (globals.default_separator) and its default (" | ") is ASCII-safe.
+  // [LAW:types-are-the-program] Total over StripStyle — the `never`
   // default makes adding a STRIP_STYLES member a compile error here until it
   // gets a joiner, so the picker's domain can never offer an unrenderable shape.
   switch (style) {
     case "capsule":
-      return new CapsuleJoiner();
+      return new CapsuleJoiner(CAPSULE_GLYPHS[charset]);
     case "plain":
       return new PlainJoiner(separator !== undefined ? { separator } : {});
     case "powerline":
-      return new PowerlineJoiner();
+      return new PowerlineJoiner(POWERLINE_GLYPHS[charset]);
     default: {
       const _exhaustive: never = style;
       return _exhaustive;
@@ -96,10 +150,13 @@ function pickJoiner(style: StripStyle, separator?: string): Joiner {
 // [LAW:dataflow-not-control-flow] / [LAW:types-are-the-program] Total over
 // StripStyle — the `never` default makes adding a STRIP_STYLES member a compile
 // error here until its chrome is declared, the same guard pickJoiner carries. The
-// numbers are the default cap glyphs pickJoiner constructs: powerline appends ONE
-// trailing separator (U+E0B0, 1 col); capsule brackets BOTH edges (U+E0B6 +
-// U+E0B4, 2 cols); plain has no caps. test/picker-pagination.test.ts measures the
-// real rendered chrome against these so the declaration cannot drift from rich-js.
+// numbers are the cap glyphs pickJoiner constructs: powerline appends ONE
+// trailing separator (1 col); capsule brackets BOTH edges (2 cols); plain has no
+// caps. Charset does NOT change these — both glyph vocabularies use
+// single-column caps by construction (see the glyph tables above), which is why
+// this stays total over StripStyle alone. test/picker-pagination.test.ts
+// measures the real rendered chrome against these for every style × charset so
+// the declaration cannot drift from rich-js or from the ascii glyph choice.
 export function stripChromeCols(style: StripStyle): number {
   switch (style) {
     case "powerline":
@@ -144,7 +201,7 @@ export function renderStripCells(
   options: BuildLineOptions,
 ): string {
   if (cells.length === 0) return "";
-  const joiner = pickJoiner(options.style, options.separator);
+  const joiner = pickJoiner(options.style, options.charset, options.separator);
   if (options.wrap && Number.isFinite(options.width)) {
     const flex = new FlexStrip([...cells], { joiner });
     const out = renderToString(flex, {

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 ---
 
@@ -79,3 +79,45 @@ export function effectiveStripStyle(
   const chosen = sessionStyle ?? globalsStyle ?? "powerline";
   return isStripStyle(chosen) ? chosen : "powerline";
 }
+
+// --- Joiner charset identifiers ---
+
+// [LAW:one-source-of-truth][LAW:types-are-the-program] The single canonical set
+// of glyph vocabularies the strip joiners can render with (the legacy
+// display.charset). Same species as STRIP_STYLES — a closed render-vocabulary
+// enum hosted in this leaf policy module so the config loader (validation +
+// JSON-schema emit) and the render layer (glyph dispatch) both derive from one
+// literal without a config↔render cycle [LAW:one-way-deps]. "ascii" swaps the
+// powerline-private-use cap glyphs (U+E0Bx — tofu without a Nerd Font) for
+// plain-ASCII equivalents; it is orthogonal to StripStyle: style picks the
+// joiner SHAPE, charset picks the glyph VALUES fed to it.
+// [config-only] Unlike STRIP_STYLES there is no SessionState/click half, so no
+// narrowing guard or effective* resolver — the config global over the default
+// 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];