@promptctl/cc-candybar 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.6.0",
+  "version": "1.7.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.6.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.6.0",
-    "@promptctl/cc-candybar-linux-x64": "1.6.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.6.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.7.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.7.0",
+    "@promptctl/cc-candybar-linux-x64": "1.7.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.7.0"
   },
   "pnpm": {
     "supportedArchitectures": {

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

@@ -425,6 +425,17 @@ export const DEFAULT_DSL_CONFIG = {
       type: "number",
       default: -1,
     },
+    // Recent burn-rate trend: a comma-delimited series of total-lane tok/s the
+    // daemon folds from its sample ring (render-payload.ts). A series cannot
+    // cross the scalar var-system seam, so it travels as a string the
+    // `sparkline` helper decodes. Default "" is the genuine "no history yet"
+    // form (the helper renders nothing); the segment gates on it being present.
+    "speed.history": {
+      kind: "input",
+      path: "speed.history",
+      type: "string",
+      default: "",
+    },
 
     // Context — daemon fetches via ContextProvider; contextLeftPercentage.
     "context.totalTokens": {
@@ -656,6 +667,21 @@ export const DEFAULT_DSL_CONFIG = {
       fg: "foreground",
       when: "{{ gt .session.tokens 0 }}",
     },
+    // Burn-rate sparkline: the recent total-lane tok/s trend as a unicode
+    // mini-graph. Declared-but-opt-in (NOT in the default root, like speed /
+    // block / weekly): a user adds `tokenSparkline` to their layout. The
+    // `sparkline` helper decodes the daemon-owned series and draws it; `24`
+    // caps the glyph count to the cell, showing the live tail of the ring. The
+    // segment's fg colors the whole graph (no per-glyph color). Gated on the
+    // history being present so the cell never renders empty (the series needs
+    // two samples before its first bar). [LAW:effects-at-boundaries] — all the
+    // history lives in the daemon ring, the template only draws.
+    tokenSparkline: {
+      template: " ⚡ {{ sparkline .speed.history 24 }} ",
+      bg: "panel",
+      fg: "foreground",
+      when: '{{ ne .speed.history "" }}',
+    },
     // 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]

package/src/daemon/cache/session-usage-store.ts

@@ -61,14 +61,24 @@ export interface SpeedSample {
   readonly atMs: number;
 }
 
-// The prior observation (absent on the very first render of a session) and the
-// one just taken. The pure rate projection lives at the render-payload boundary;
-// this store only remembers and reports the pair.
+// The prior observation (absent on the very first render of a session), the one
+// just taken, and the recent ring (oldest→newest, INCLUDING `cur`). The pure
+// projections live at the render-payload boundary; this store only remembers and
+// reports. [LAW:one-source-of-truth] `prev === samples[samples.length - 2]` — the
+// tok/s baseline and the burn-rate history fold from the SAME owned ring, not two
+// parallel stores. tok/s reads the last pair; the sparkline reads every pair.
 export interface SpeedObservation {
   readonly prev?: SpeedSample;
   readonly cur: SpeedSample;
+  readonly samples: readonly SpeedSample[];
 }
 
+// How many recent samples the burn-rate ring retains per session. A render-cadence
+// trend, not an archive: enough to fill a wide sparkline cell, capped so an
+// idle-but-alive session can't grow it without bound. The window the sparkline
+// draws is a tail slice of this (the `width` arg), so this only sets the ceiling.
+const SPEED_RING_CAPACITY = 64;
+
 function speedSampleOf(
   breakdown: TokenBreakdown | null,
   atMs: number,
@@ -202,11 +212,13 @@ export class SessionUsageStore {
   // first seed completes every later read awaits an already-settled promise —
   // zero rescan. A rejected seed is dropped so the next read retries.
   private readonly seeded = new Map<string, Promise<void>>();
-  // [LAW:one-source-of-truth] The prior tok/s observation per session. tok/s is
-  // a derivative of the SAME token totals the records map already owns; the
-  // baseline (prev counts + time) lives HERE, not in a parallel counter. One
-  // call to observeSpeed advances it; the pure delta math is render-payload's.
-  private readonly speedSamples = new Map<string, SpeedSample>();
+  // [LAW:one-source-of-truth] The recent tok/s observations per session, a
+  // bounded ring (oldest→newest). tok/s is a derivative of the SAME token totals
+  // the records map already owns; the baseline (prior counts + time) is the ring's
+  // last element, not a parallel counter. The burn-rate sparkline folds over the
+  // whole ring; tok/s folds over its final pair. One call to observeSpeed appends;
+  // the pure delta math is render-payload's.
+  private readonly speedRings = new Map<string, SpeedSample[]>();
   // [LAW:no-ambient-temporal-coupling] Explicit owner of observe/commit ordering
   // for the speed sample. Concurrent renders observing the SAME transcript state
   // (key = `${sessionId}:${mtime}`) share ONE observation and commit the baseline
@@ -356,9 +368,33 @@ export class SessionUsageStore {
       const breakdown =
         record.kind === "ok" ? record.value.sessionInfo.tokenBreakdown : null;
       const cur = speedSampleOf(breakdown, nowMs);
-      const prev = this.speedSamples.get(sessionId);
-      this.speedSamples.set(sessionId, cur);
-      return ok({ ...(prev !== undefined && { prev }), cur });
+      const ring = this.speedRings.get(sessionId) ?? [];
+      // [LAW:no-ambient-temporal-coupling] Observation time (atMs, the render
+      // clock) owns ring order — NOT ingest-completion order. Two concurrent
+      // observes with different mtimes don't coalesce in speedFlight and each
+      // awaits ingest before this mutation, so a plain append would record
+      // samples in whichever-ingest-settled-first order and invert oldest→newest.
+      // prev is the latest sample strictly before this observation; the post-
+      // insert sort by atMs makes the ring's order independent of completion
+      // order. (get→insert→set is synchronous after the await, so each resumed
+      // continuation mutates atomically — no lost update.)
+      let prev: SpeedSample | undefined;
+      for (const s of ring) {
+        if (s.atMs < cur.atMs && (prev === undefined || s.atMs > prev.atMs)) {
+          prev = s;
+        }
+      }
+      ring.push(cur);
+      ring.sort((a, b) => a.atMs - b.atMs);
+      // Drop oldest (smallest atMs ⇒ ring[0]) beyond the cap — a tail window,
+      // not an archive.
+      if (ring.length > SPEED_RING_CAPACITY) ring.shift();
+      this.speedRings.set(sessionId, ring);
+      return ok({
+        ...(prev !== undefined && { prev }),
+        cur,
+        samples: [...ring],
+      });
     });
   }
 
@@ -494,7 +530,7 @@ export class SessionUsageStore {
     for (const [sid, record] of this.entries) {
       if (now - record.lastSeenAt > this.staleAgeMs) {
         this.entries.delete(sid);
-        this.speedSamples.delete(sid);
+        this.speedRings.delete(sid);
         dropped++;
       }
     }
@@ -510,7 +546,7 @@ export class SessionUsageStore {
       const oldest = this.entries.keys().next().value;
       if (oldest === undefined) break;
       this.entries.delete(oldest);
-      this.speedSamples.delete(oldest);
+      this.speedRings.delete(oldest);
       dlog("info", `usageStore evict ${oldest}`);
     }
   }
@@ -522,6 +558,6 @@ export class SessionUsageStore {
     }
     this.entries.clear();
     this.seeded.clear();
-    this.speedSamples.clear();
+    this.speedRings.clear();
   }
 }

package/src/daemon/render-payload.ts

@@ -140,6 +140,14 @@ export interface SpeedPayload {
   readonly input?: number;
   readonly output?: number;
   readonly total?: number;
+  // [LAW:one-type-per-behavior] The recent burn-rate trend: a delimited series
+  // of total-lane tok/s over the store's sample ring, for the `sparkline` helper.
+  // It rides the speed lane because it folds from the SAME observation the three
+  // instantaneous rates do, but it is INDEPENDENTLY optional — a session that
+  // burst then went idle has no current rate yet still has a history to draw. It
+  // travels as a string because a series cannot cross the scalar var-system seam;
+  // the helper decodes it. Absent (no measurable in-window pair) → missing → "".
+  readonly history?: string;
 }
 
 export interface BlockPayload {
@@ -330,6 +338,42 @@ function projectSpeed(obs: SpeedObservation): SpeedPayload | undefined {
   };
 }
 
+// [LAW:effects-at-boundaries] Pure fold of the observation's sample ring into the
+// burn-rate history string. Each adjacent pair becomes one total-lane tok/s; an
+// un-projectable pair (no new tokens, or a gap outside the sample window) is a
+// real ZERO-throughput interval, not absence — the series is a string of numbers,
+// and 0 is the honest value for "burned nothing here" ([LAW:no-silent-failure] —
+// the gap is reported, not dropped to misalign the graph). Fewer than two samples
+// ⇒ no pair ⇒ undefined (the whole field drops to the "" default).
+function projectSpeedHistory(obs: SpeedObservation): string | undefined {
+  const { samples } = obs;
+  const rates: number[] = [];
+  for (let i = 1; i < samples.length; i++) {
+    const prev = samples[i - 1]!;
+    const cur = samples[i]!;
+    // [LAW:no-silent-failure] Only an in-window interval is a measurable reading.
+    // An out-of-window pair — samples too close to time a rate reliably, or a
+    // stale gap spanning idle time — is UNMEASURABLE, not zero burn, so it is
+    // SKIPPED rather than fabricated as a 0 bar that would read as real activity.
+    // projectTokensPerSecond stays the single formula+window authority (same
+    // module constants); this classifier disambiguates its undefined: out-of-
+    // window ⇒ skip, in-window ⇒ undefined means a non-positive token delta, a
+    // genuine zero-burn reading that stays 0.
+    const deltaMs = cur.atMs - prev.atMs;
+    if (deltaMs < MIN_SPEED_SAMPLE_MS || deltaMs > MAX_SPEED_SAMPLE_MS)
+      continue;
+    const rate = projectTokensPerSecond(
+      prev.total,
+      prev.atMs,
+      cur.total,
+      cur.atMs,
+    );
+    rates.push(rate ?? 0);
+  }
+  if (rates.length === 0) return undefined;
+  return rates.join(",");
+}
+
 // ─── Builder ─────────────────────────────────────────────────────────────────
 
 // ─── Config-driven provider gating ───────────────────────────────────────────
@@ -657,8 +701,22 @@ export async function buildRenderPayload(
   // that data here at the edge. Absent observation (lane skipped/failed) or no
   // projectable lane → no `speed` key → every lane reads its -1 default.
   const speedObs = take(speed);
-  const speedPayload =
+  // [LAW:dataflow-not-control-flow] The instantaneous rates and the burn-rate
+  // history fold independently from one observation — either can be present
+  // without the other (a fresh burst has rates but a one-sample history; an
+  // idle-after-burst session has a history but no current rate). Merge whatever
+  // each yields; the whole `speed` key drops only when both are absent.
+  const speedRates =
     speedObs !== undefined ? projectSpeed(speedObs) : undefined;
+  const speedHistory =
+    speedObs !== undefined ? projectSpeedHistory(speedObs) : undefined;
+  const speedPayload =
+    speedRates !== undefined || speedHistory !== undefined
+      ? {
+          ...speedRates,
+          ...(speedHistory !== undefined && { history: speedHistory }),
+        }
+      : 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

package/src/template-engine/engine.ts

@@ -20,7 +20,8 @@
 //    `dict` lets a helper take multiple named inputs through its one dot arg.
 //  • richTextFuncs: bold, italic, red, green, … (styling from rich-js).
 //  • paletteFuncs (when resolver provided): primary, accent, palette, paletteOver, auto.
-//  • ccCandybarFuncs: basename, dirname, int, string, bool, urlEncode.
+//  • ccCandybarFuncs: basename, dirname, int, string, bool, urlEncode,
+//    themes, styles, sparkline.
 //  • formatterFuncs: minutesUntilReset (clock-reading numeric primitive),
 //    formatInteger, round, formatModelName, shortenModelName. (The cost/token/
 //    budget AND duration/time-remaining formatters moved to DSL helper templates

package/src/template-engine/funcs.ts

@@ -17,6 +17,7 @@ import {
   shortenModelName,
 } from "../utils/formatters.js";
 import { listResolvablePaletteNames, STRIP_STYLES } from "../themes/policy.js";
+import { renderSparkline, parseSeries } from "./sparkline.js";
 
 // [LAW:one-source-of-truth] The DSL `themes()` and `styles()` bindings
 // project the SAME canonical sources the set-state validator consults
@@ -128,6 +129,22 @@ export function ccCandybarFuncs(): FuncMap {
       fn: () => STYLES_LIST,
       argTypes: [],
     },
+
+    // [LAW:effects-at-boundaries] Pure trend renderer: a numeric series (the
+    // daemon-owned ring, projected through the payload as a delimited string)
+    // becomes a unicode mini-graph. The series crosses the scalar var-system
+    // seam as a string, so the FuncMap slot is "string"; `parseSeries` decodes
+    // it and `renderSparkline` draws it — neither accumulates state. The
+    // optional trailing "int" slot caps the glyph count to fit a cell (the
+    // evaluator validates only supplied args, so `{{ sparkline .series }}` and
+    // `{{ sparkline .series 24 }}` are both well-typed). Returns a bare string;
+    // the engine lifts it to RichText so the segment's fg/bg palette colors the
+    // whole graph — no per-glyph color math here.
+    sparkline: {
+      fn: (series: string, width?: number) =>
+        renderSparkline(parseSeries(series), width),
+      argTypes: ["string", "int"],
+    },
   };
 }
 

package/src/template-engine/sparkline.ts

@@ -0,0 +1,79 @@
+// [LAW:effects-at-boundaries] A sparkline is a PURE projection: a numeric
+// series in, a string of block glyphs out. It reads no clock, touches no
+// store, accumulates nothing — any history it draws is owned by the daemon
+// cache and handed in as data (cf. session-usage-store's burn-rate ring).
+// [LAW:one-source-of-truth] The renderer operates on number[] (the real
+// domain); the var-system can only carry a scalar across the payload→template
+// seam, so `parseSeries` decodes the delimited string form at that one edge —
+// the wire shape and the domain shape have a single, tested conversion.
+
+// The eight-level block ramp, lowest→highest. Index into this is the only
+// place a value's normalized height becomes a glyph.
+export const SPARK_LEVELS = [
+  "▁", // ▁
+  "▂", // ▂
+  "▃", // ▃
+  "▄", // ▄
+  "▅", // ▅
+  "▆", // ▆
+  "▇", // ▇
+  "█", // █
+] as const;
+
+const LEVELS = SPARK_LEVELS.length;
+
+// Render a numeric series as a unicode mini-graph.
+//
+// `width` caps the glyph count to fit a cell: the MOST RECENT `width` samples
+// are shown (tail slice), so a fixed-width cell tracks the live tail of a
+// growing series. Omitted → every sample renders; `width <= 0` → empty.
+//
+// Heights are RELATIVE to the rendered window's own min/max — a sparkline shows
+// shape, never absolute magnitude, so the full ramp is always used when the
+// window varies. [LAW:dataflow-not-control-flow] The mapping is one unconditional
+// fold over the values; the only data-driven value is `range`, and a flat
+// window (range === 0) falls to the lowest tier by the same formula's limit
+// (height-above-min is 0 for every sample), not a special-cased branch.
+export function renderSparkline(values: number[], width?: number): string {
+  const window =
+    width === undefined ? values : width <= 0 ? [] : values.slice(-width);
+  if (window.length === 0) return "";
+
+  let min = window[0]!;
+  let max = window[0]!;
+  for (const v of window) {
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  const range = max - min;
+
+  let out = "";
+  for (const v of window) {
+    // range === 0 ⇒ every sample sits at its own min ⇒ height 0 ⇒ lowest tier.
+    const idx =
+      range === 0 ? 0 : Math.round(((v - min) / range) * (LEVELS - 1));
+    out += SPARK_LEVELS[idx]!;
+  }
+  return out;
+}
+
+// Decode the delimited string a series travels as across the scalar var-system
+// seam into the number[] the renderer consumes. Empty / blank tokens are the
+// genuine "no sample" form (an empty payload field is ""), so they drop; a
+// non-empty, non-numeric token is malformed input and fails LOUDLY rather than
+// being silently skipped into a wrong-shaped graph. [LAW:no-silent-failure]
+export function parseSeries(s: string): number[] {
+  const out: number[] = [];
+  for (const tok of s.split(",")) {
+    const t = tok.trim();
+    if (t === "") continue;
+    const n = Number(t);
+    if (!Number.isFinite(n)) {
+      throw new TypeError(
+        `sparkline: non-numeric series element ${JSON.stringify(tok)}`,
+      );
+    }
+    out.push(n);
+  }
+  return out;
+}