@promptctl/cc-candybar 1.1.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.1.1",
+  "version": "1.3.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.1.1",
-    "@promptctl/cc-candybar-darwin-x64": "1.1.1",
-    "@promptctl/cc-candybar-linux-x64": "1.1.1",
-    "@promptctl/cc-candybar-linux-arm64": "1.1.1"
+    "@promptctl/cc-candybar-darwin-arm64": "1.3.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.3.0",
+    "@promptctl/cc-candybar-linux-x64": "1.3.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.3.0"
   },
   "pnpm": {
     "supportedArchitectures": {

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

@@ -108,6 +108,29 @@ function blockLikeFg(pctRef: string): string {
   );
 }
 
+// [LAW:dataflow-not-control-flow] The burn segment heats as the cap NEARS, so
+// the cascade reads the projected minutes-to-cap (smaller = hotter), the
+// inverse direction of blockLikeBg's fuller-is-hotter. The not-projectable
+// sentinel (-1, sorts below every threshold) is caught first so "we cannot
+// project" colors calm, never error. Thresholds are var refs so a user
+// overrides them through the same by-name variables cascade.
+function etaHeatBg(etaRef: string, warnRef: string, errRef: string): string {
+  return (
+    `{{ if lt ${etaRef} 0 }}panel` +
+    `{{ else }}{{ if lt ${etaRef} ${errRef} }}error` +
+    `{{ else }}{{ if lt ${etaRef} ${warnRef} }}warning` +
+    `{{ else }}panel{{ end }}{{ end }}{{ end }}`
+  );
+}
+
+function etaHeatFg(etaRef: string, warnRef: string): string {
+  return (
+    `{{ if lt ${etaRef} 0 }}foreground` +
+    `{{ else }}{{ if lt ${etaRef} ${warnRef} }}button-color-foreground` +
+    `{{ else }}foreground{{ end }}{{ end }}`
+  );
+}
+
 // ─── The default config ──────────────────────────────────────────────────────
 
 export const DEFAULT_DSL_CONFIG = {
@@ -136,6 +159,14 @@ export const DEFAULT_DSL_CONFIG = {
       path: "workspace.project_dir",
       default: "",
     },
+    // Transcript path (a top-level hookData field, spread onto the payload
+    // root by buildRenderPayload). Read by the quick-action tray's
+    // openTranscript action — pass-through, no projection.
+    transcript_path: {
+      kind: "input",
+      path: "transcript_path",
+      default: "",
+    },
     "model.display_name": {
       kind: "input",
       path: "model.display_name",
@@ -327,6 +358,34 @@ export const DEFAULT_DSL_CONFIG = {
     },
     "weekly.budget.warningThreshold": { kind: "literal", value: 80 },
 
+    // Burn rate + cap projection — daemon-derived (see render-payload.ts).
+    // Each projection is ABSENT when not projectable; the var-system fills the
+    // -1 default, a structurally-impossible value the burnrate helpers read as
+    // "—" [LAW:no-silent-failure] (0 minutes / $0-per-hr are real, displayable
+    // values, so they cannot double as the absence marker).
+    "burn.costPerHour": {
+      kind: "input",
+      path: "burn.costPerHour",
+      type: "number",
+      default: -1,
+    },
+    "block.etaMinutes": {
+      kind: "input",
+      path: "block.etaMinutes",
+      type: "number",
+      default: -1,
+    },
+    "weekly.etaMinutes": {
+      kind: "input",
+      path: "weekly.etaMinutes",
+      type: "number",
+      default: -1,
+    },
+    // ETA-heat thresholds (minutes-to-cap) — overridable per-config through the
+    // variables-merge-by-name cascade, like the *.budget.warningThreshold knobs.
+    "burn.eta.warnMinutes": { kind: "literal", value: 60 },
+    "burn.eta.errorMinutes": { kind: "literal", value: 30 },
+
     // Context — daemon fetches via ContextProvider; contextLeftPercentage.
     "context.totalTokens": {
       kind: "input",
@@ -446,10 +505,16 @@ export const DEFAULT_DSL_CONFIG = {
       fg: "foreground",
       when: '{{ ne .git.branch "" }}',
     },
+    // Quick-action tray — copy the session id / cwd, open the project dir /
+    // transcript in the editor. [LAW:locality-or-seam] The glyph is the
+    // REPRESENTATION; the named action (below) is the BEHAVIOR; the action
+    // name is the seam between them. Re-glyph without touching behavior;
+    // re-target without touching this template. Each `{{ action … }}` emits
+    // one OSC-8 clickable region whose URL the wire codec owns end-to-end.
     toolbar: {
       template:
-        ' {{ link (printf "cc-candybar://open-vscode/%s" (urlEncode .current_dir)) "\u{1F4C2}" }}' +
-        ' {{ link (printf "cc-candybar://copy/%s" (urlEncode (trunc 8 .session.id))) "⎘" }} ',
+        ' {{ action "copySession" "⎘ id" }} {{ action "copyDir" "⎘ cwd" }}' +
+        ' {{ action "openProject" "↗ proj" }} {{ action "openTranscript" "↗ log" }} ',
       bg: "surface",
       fg: "foreground",
     },
@@ -486,6 +551,24 @@ export const DEFAULT_DSL_CONFIG = {
       fg: blockLikeFg(".weekly.percentage"),
       when: "{{ gt .weekly.resetsAt 0 }}",
     },
+    // Burn rate + cap projection: "$X/hr · Nm to 5h · Nd to wk". The headline
+    // number of a usage monitor — how fast you are spending and when you hit
+    // the wall. All math is daemon-side (render-payload.ts); the template only
+    // formats. Heats as the 5h cap nears (etaHeat*). Shown when either
+    // rate-limit window is active — the same signal block/weekly gate on.
+    burnrate: {
+      template:
+        ' ⚡ {{ template "formatRate" .burn.costPerHour }} · ' +
+        '{{ template "formatEta" .block.etaMinutes }} to 5h · ' +
+        '{{ template "formatEta" .weekly.etaMinutes }} to wk ',
+      bg: etaHeatBg(
+        ".block.etaMinutes",
+        ".burn.eta.warnMinutes",
+        ".burn.eta.errorMinutes",
+      ),
+      fg: etaHeatFg(".block.etaMinutes", ".burn.eta.warnMinutes"),
+      when: "{{ or (gt .block.resetsAt 0) (gt .weekly.resetsAt 0) }}",
+    },
     // Prompt-cache warmth countdown. minutesUntilReset clamps a past expiry
     // to 0, so an expired cache renders "cold" (and reads red via the ≤8
     // arm) rather than a negative number. [LAW:dataflow-not-control-flow]
@@ -543,7 +626,7 @@ export const DEFAULT_DSL_CONFIG = {
   },
 
   // Default layout — a single horizontal row of segment refs.
-  // A-grammar equivalent: { h: ["directory","git","model","session","today","context"] }
+  // A-grammar equivalent: { h: ["directory","git","model","session","today","context","toolbar"] }
   // [LAW:one-source-of-truth] The bundled default now authors the same terse
   // surface every user config lowers to, so the default is the reference spelling.
   // Adding rows = wrapping in { kind:"container", direction:"vertical", children:[...] };
@@ -558,14 +641,30 @@ export const DEFAULT_DSL_CONFIG = {
       { kind: "segment", name: "session" },
       { kind: "segment", name: "today" },
       { kind: "segment", name: "context" },
+      { kind: "segment", name: "toolbar" },
     ],
   },
 
-  // [LAW:locality-or-seam] No decoupled actions in the bundled default either —
-  // the baseline statusline binds no clickable regions. A user config declares
-  // named actions and binds them from a segment template via
-  // `{{ action "name" … }}`; the merge cascade adds them by name.
-  actions: {},
+  // [LAW:locality-or-seam] The quick-action tray's behaviors, decoupled by NAME
+  // from the `toolbar` segment's glyphs above. copy/open evaluate a Go-template
+  // against the live render scope at click time and write NO SessionState, so
+  // they derive no state validator (no gate) — they are pure click effects.
+  //
+  // [LAW:single-enforcer] Each template emits a RAW value; the click-wire codec
+  // (effectsUrl → encodeSegments) owns ALL percent-encoding and the verb's
+  // `oneArg` owns the single matching decode — so the template never hand-rolls
+  // a `urlEncode`, and the path round-trips untouched through one codec.
+  //
+  // open* route through the open-vscode verb (`open -a "Visual Studio Code"
+  // <path>`), so they pass a bare filesystem path — a directory or a file the
+  // editor opens directly — NOT a `vscode://` URL (which `open -a` would treat
+  // as a literal filename, not a deep link).
+  actions: {
+    copySession: { copy: "{{ .session.id }}" },
+    copyDir: { copy: "{{ .current_dir }}" },
+    openProject: { open: "{{ .project_dir }}" },
+    openTranscript: { open: "{{ .transcript_path }}" },
+  },
 
   // [LAW:single-enforcer] / [LAW:one-source-of-truth] Display-formatting policy
   // for the cost/token/budget family lives here as named template helpers, each
@@ -592,6 +691,16 @@ export const DEFAULT_DSL_CONFIG = {
       '{{ else if ge . 1000 }}{{ printf "%.1f" (divf . 1000) }}K' +
       "{{ else }}{{ . }}{{ end }}",
     formatTokens: '{{ template "formatTokenCount" . }} tokens',
+    // Burn rate: "$X.XX/hr" when projectable, "—/hr" otherwise. The daemon
+    // emits -1 (a structurally-impossible rate) for not-projectable, so the
+    // branch reads a VALUE, never a hidden control-flow flag. Reuses formatCost
+    // so the dollar policy has one home.
+    formatRate:
+      '{{ if lt . 0 }}—/hr{{ else }}{{ template "formatCost" . }}/hr{{ end }}',
+    // ETA to a rate-limit cap: humanized minutes when projectable, "—" when the
+    // daemon could not project (-1 sentinel). Reuses the long-remaining cascade.
+    formatEta:
+      '{{ if lt . 0 }}—{{ else }}{{ template "formatLongTimeRemaining" . }}{{ end }}',
     // Breakdown over a dict {input, output, cacheCreation, cacheRead}; each present
     // part is formatted by the shared formatTokenCount and joined with " + ". A
     // `$first` flag (reassigned across if-frames) inserts the separator before all

package/src/daemon/cache/render.ts

@@ -300,12 +300,11 @@ export class RenderCache {
     // reloadInto preserves the prior last-known-good with nothing half-installed.
     const validatorDisposers: Array<() => void> = [];
     try {
-      // [LAW:locality-or-seam] Pass the store so the config's `widget`
-      // references can read session.id + current picker values from the same
-      // source the rest of the render reads.
+      // [LAW:one-source-of-truth] The action runtime reads session.id + current
+      // picker values from registry.variableStore — the same store this entry's
+      // registry declares into — so no store reference is threaded separately.
       compiled = registerDslConfig(config, registry, {
         cwd: entry.cwd,
-        store,
       });
       // [LAW:one-source-of-truth] Derive the writable-key validators from the
       // config's action table (the sole interaction authority) through one

package/src/daemon/render-payload.ts

@@ -64,6 +64,7 @@ export interface RenderPayload extends ClaudeHookData {
   // exactly like a missing top-level field.
   readonly session?: SessionPayload;
   readonly today?: TodayPayload;
+  readonly burn?: BurnPayload;
   readonly block?: BlockPayload;
   readonly weekly?: WeeklyPayload;
   readonly cache?: CachePayload;
@@ -105,14 +106,31 @@ export interface TodayPayload {
   readonly tokens?: number;
 }
 
+// [LAW:one-type-per-behavior] The burn rate is the session's spend velocity —
+// dollars per wall-clock hour — a derivative of the same cost the `session`
+// segment totals, so it is its own concept, not a field bolted onto the
+// totals. Optional because a too-young session yields no honest rate
+// ([LAW:no-silent-failure] — absence over a single-turn artifact).
+export interface BurnPayload {
+  readonly costPerHour?: number;
+}
+
 export interface BlockPayload {
   readonly nativeUtilization: number;
   readonly resetsAt: number;
+  // [LAW:types-are-the-program] Linear projection of nativeUtilization → 100%
+  // at the current rate, in whole minutes. Absent (not 0, not a sentinel
+  // in the type) when the window is too young or shows no usage to project
+  // from — the ETA's "we cannot say" state is unrepresentable as a number,
+  // so it travels as a missing field to the DSL default. [LAW:no-silent-failure]
+  readonly etaMinutes?: number;
 }
 
 export interface WeeklyPayload {
   readonly percentage: number;
   readonly resetsAt: number;
+  // Same projection as BlockPayload.etaMinutes over the seven-day window.
+  readonly etaMinutes?: number;
 }
 
 // Prompt-cache warmth. One field — the epoch-seconds expiry instant —
@@ -158,6 +176,64 @@ export interface RenderPayloadDeps {
   // buildRenderPayload is the ONE place lane failures are logged, so the
   // providers' interiors never log and never double-log.
   readonly log: DaemonLogger;
+  // [LAW:single-enforcer] The one clock the projection math reads "now" from —
+  // the same seam threaded to the template engine's `minutesUntilReset`, so
+  // an ETA and the reset countdown beside it agree on the instant. Omitted ⇒
+  // wall clock; tests inject a frozen clock for determinism.
+  readonly clock?: () => Date;
+}
+
+// ─── Rate-limit projection (pure) ──────────────────────────────────────────────
+//
+// [LAW:effects-at-boundaries] The math is pure — utilization, reset instant,
+// window length and `now` in; minutes-to-cap out. The only effect (reading the
+// clock) stays in buildRenderPayload; these stay testable in isolation.
+
+// Window lengths are facts of Claude's rate-limit cadence, not config: the
+// five-hour block and the seven-day window.
+const FIVE_HOUR_MS = 5 * 60 * 60 * 1000;
+const SEVEN_DAY_MS = 7 * 24 * 60 * 60 * 1000;
+// Below this much elapsed in a window, a linear projection from one early data
+// point is noise — surface no ETA rather than a confidently-wrong number.
+const MIN_PROJECTABLE_ELAPSED_MS = 5 * 60 * 1000;
+// The same floor for the spend rate: under a minute of session wall-clock,
+// $/hr is dominated by a single turn rather than a sustained burn.
+const MIN_BURN_SECONDS = 60;
+
+/**
+ * Linearly extrapolate a rate-limit window's utilization to its 100% cap.
+ * The window started `windowMs` before `resetsAtSec`; elapsed time and the
+ * used-% give a rate, and the remaining headroom divided by that rate is the
+ * minutes-to-cap. Returns undefined when the window is too young to project
+ * or shows no usage yet — the caller drops the field and the segment renders
+ * "—" rather than a fabricated ETA. [LAW:no-silent-failure]
+ */
+export function projectEtaMinutes(
+  usedPercentage: number,
+  resetsAtSec: number,
+  windowMs: number,
+  nowMs: number,
+): number | undefined {
+  const elapsedMs = windowMs - (resetsAtSec * 1000 - nowMs);
+  if (elapsedMs < MIN_PROJECTABLE_ELAPSED_MS || usedPercentage <= 0)
+    return undefined;
+  const pctPerMs = usedPercentage / elapsedMs;
+  const etaMs = (100 - usedPercentage) / pctPerMs;
+  return Math.max(0, Math.round(etaMs / 60000));
+}
+
+/**
+ * Session spend rate in dollars per hour: cost over wall-clock duration.
+ * Returns undefined under a wall-clock floor where the rate is a single-turn
+ * artifact, not a sustained burn. A real $0 over enough time is a true 0/hr,
+ * not absence. [LAW:no-silent-failure]
+ */
+export function projectCostPerHour(
+  cost: number,
+  durationSeconds: number,
+): number | undefined {
+  if (durationSeconds < MIN_BURN_SECONDS) return undefined;
+  return (cost * 3600) / durationSeconds;
 }
 
 // ─── Builder ─────────────────────────────────────────────────────────────────
@@ -376,8 +452,13 @@ export async function buildRenderPayload(
           hookData.workspace?.project_dir,
         ),
       ),
-      lane("session", wants("session.cost") || wants("session.tokens"), () =>
-        deps.usageStore.getUsageInfo(hookData.session_id, hookData),
+      // [LAW:dataflow-not-control-flow] The burn segment reads `burn.costPerHour`,
+      // a derivative of session cost and metrics duration — so wanting `burn`
+      // pulls in exactly the two lanes it is folded from.
+      lane(
+        "session",
+        wants("session.cost") || wants("session.tokens") || wants("burn"),
+        () => deps.usageStore.getUsageInfo(hookData.session_id, hookData),
       ),
       lane("today", wants("today"), () =>
         deps.usageStore.getTodayInfo(hookData),
@@ -385,7 +466,7 @@ export async function buildRenderPayload(
       lane("context", wants("context"), () =>
         deps.contextProvider.getContextInfo(hookData),
       ),
-      lane("metrics", wants("metrics"), () =>
+      lane("metrics", wants("metrics") || wants("burn"), () =>
         deps.metricsProvider.getMetricsInfo(hookData.session_id, hookData),
       ),
       lane("tmux", wants("tmux"), () => deps.tmuxService.getSessionId()),
@@ -423,6 +504,34 @@ export async function buildRenderPayload(
   // `minutesUntilReset(resets_at)`, which the DSL template composes via
   // the formatter func — a duplicate code path was retired.)
   const fiveHour = hookData.rate_limits?.five_hour;
+  const sevenDay = hookData.rate_limits?.seven_day;
+  // [LAW:single-enforcer] One clock read feeds every projection this render.
+  const nowMs = (deps.clock ?? (() => new Date()))().getTime();
+  const blockEta = fiveHour
+    ? projectEtaMinutes(
+        fiveHour.used_percentage,
+        fiveHour.resets_at,
+        FIVE_HOUR_MS,
+        nowMs,
+      )
+    : undefined;
+  const weeklyEta = sevenDay
+    ? projectEtaMinutes(
+        sevenDay.used_percentage,
+        sevenDay.resets_at,
+        SEVEN_DAY_MS,
+        nowMs,
+      )
+    : undefined;
+  // [LAW:dataflow-not-control-flow] Gated by `wants("burn")` so the rate is
+  // computed only when a layout segment reads it; absent cost/duration (lane
+  // skipped or provider empty) yields no rate, never a fabricated one.
+  const burnCost = usageValue?.session.cost;
+  const burnDuration = metricsValue?.sessionDuration;
+  const costPerHour =
+    wants("burn") && burnCost != null && burnDuration != null
+      ? projectCostPerHour(burnCost, burnDuration)
+      : undefined;
 
   // [LAW:one-source-of-truth] The theme variable surfaces the session's
   // resolved theme so the toolbar/tray DSL templates can encode it into
@@ -487,6 +596,7 @@ export async function buildRenderPayload(
     ...(theme !== undefined && { theme }),
     ...(sessionPayload !== undefined && { session: sessionPayload }),
     ...(todayPayload !== undefined && { today: todayPayload }),
+    ...(costPerHour !== undefined && { burn: { costPerHour } }),
     ...(wants("block") &&
       fiveHour !== undefined && {
         block: {
@@ -496,12 +606,14 @@ export async function buildRenderPayload(
           // projection rule, two segments.
           nativeUtilization: fiveHour.used_percentage,
           resetsAt: fiveHour.resets_at,
+          ...(blockEta !== undefined && { etaMinutes: blockEta }),
         },
       }),
-    ...(hookData.rate_limits?.seven_day !== undefined && {
+    ...(sevenDay !== undefined && {
       weekly: {
-        percentage: hookData.rate_limits.seven_day.used_percentage,
-        resetsAt: hookData.rate_limits.seven_day.resets_at,
+        percentage: sevenDay.used_percentage,
+        resetsAt: sevenDay.resets_at,
+        ...(weeklyEta !== undefined && { etaMinutes: weeklyEta }),
       },
     }),
     ...(cacheValue !== undefined && {

package/src/daemon/server.ts

@@ -1076,6 +1076,9 @@ const payloadDeps = {
   // [LAW:single-enforcer] buildRenderPayload is the one log site for the
   // outcome-carrying provider lanes (git, cache).
   log: dlog,
+  // [LAW:single-enforcer] The daemon's wall clock — the same instant source
+  // the rate-limit ETA projection and the template's reset countdown read.
+  clock: () => new Date(),
 };
 
 function handleClick(verb: string, value: string): Response {

package/src/demo/dsl.ts

@@ -79,7 +79,6 @@ const registry = new SourceRegistry(store);
 try {
   const compiled = registerDslConfig(config, registry, {
     cwd: process.cwd(),
-    store,
   });
 
   process.stdout.write(

package/src/dsl/render.ts

@@ -252,7 +252,7 @@ function compileHelperPreamble(
 export function registerDslConfig(
   config: ValidatedConfig,
   registry: SourceRegistry,
-  opts?: { cwd?: string; store?: VariableStore; clock?: () => Date },
+  opts?: { cwd?: string; clock?: () => Date },
 ): CompiledConfig {
   const cwd = opts?.cwd ?? process.cwd();
 
@@ -262,11 +262,12 @@ export function registerDslConfig(
   // because the action set is config-scoped. The runtime holder is populated below
   // — the `action`/`picker` funcs reference the engine, and the compiled actions
   // reference the engine, so the holder breaks that cycle.
-  // [LAW:no-defensive-null-guards] store may be absent for compile-only callers
-  // with no actions; renderAction throws loudly if an action is actually used
-  // without a store, rather than silently rendering an empty click.
+  // [LAW:one-source-of-truth] The action runtime reads through the SAME store the
+  // registry declares into and the renderer reads back — sourced from the registry
+  // itself, not a redundant opts field a caller could forget (or pass a divergent
+  // store for). Every config has a registry, so the action store is never null.
   const actionRuntime: ActionRuntime = {
-    store: opts?.store ?? null,
+    store: registry.variableStore,
     compiled: new Map(),
   };
   // [LAW:one-way-deps] Inject action + picker feature funcs as data — the engine

package/src/render/action.ts

@@ -117,7 +117,11 @@ export function optionDomain(src: OptionSource): readonly string[] {
 // reads session.id and the current value from the same source the rest of the
 // render does.
 export interface ActionRuntime {
-  store: VariableStore | null;
+  // [LAW:types-are-the-program] Always present — registerDslConfig sources it
+  // from the registry it is handed (registry.variableStore), so "no store" is
+  // structurally unrepresentable. The action reads session.id and current
+  // values from the same store the renderer reads.
+  store: VariableStore;
   compiled: CompiledActions;
 }
 
@@ -416,11 +420,6 @@ export function renderAction(
     throw new Error(`action "${name}" is not declared in this config`);
   }
   const store = runtime.store;
-  if (!store) {
-    throw new Error(
-      `action "${name}" rendered without a VariableStore — registerDslConfig was not given one`,
-    );
-  }
   const { display, boundValue } = selectDisplay(name, action, displays, store);
   const sessionId = readVar(store, "session.id");
   const { effect, active } = realize(

package/src/render/picker.ts

@@ -144,11 +144,6 @@ function renderPicker(
     "an int action ({ set, int: true })",
   );
   const store = runtime.store;
-  if (!store) {
-    throw new Error(
-      `picker "${applyName}" rendered without a VariableStore — registerDslConfig was not given one`,
-    );
-  }
   const sessionId = readVar(store, "session.id");
   const current = readVar(store, apply.stateVar);
   const widths = apply.options.map(cellWidth);

package/src/var-system/sources.ts

@@ -580,6 +580,15 @@ export class SourceRegistry {
     this.sessionState = sessionState;
   }
 
+  // [LAW:one-source-of-truth] The registry IS the owner of its store — every
+  // variable it declares lives there, and the renderer reads back through it.
+  // Exposing it read-only lets a caller that already holds the registry obtain
+  // the one store without threading a second reference that could diverge (the
+  // action runtime reads session.id/current values from this exact store).
+  get variableStore(): VariableStore {
+    return this.store;
+  }
+
   // ─── Synchronous source kinds ─────────────────────────────────────────────
 
   // literal: type inferred from value; box written once at declaration and never again.