@nredd/pi-session-kit 0.0.0-stage → 0.3.0

package/src/stats/component.ts

@@ -0,0 +1,496 @@
+/**
+ * The `/stats` overlay: Claude Code's Stats pane rebuilt over pi sessions. Overview has the activity
+ * heatmap, headline numbers and the token chart; Models has the chart and the per-model breakdown
+ * grouped by provider. `r` cycles the date range, `m` / `M` the provider/model filter.
+ */
+
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { type Color, type Component, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { sanitize } from "../diff/view.ts";
+import {
+	chartSeries,
+	dailySeries,
+	dailyTotals,
+	type Filter,
+	filterCycle,
+	filterLabel,
+	hourlySeries,
+	inRange,
+	isHourly,
+	type ModelTotals,
+	matches,
+	modelName,
+	modelTotals,
+	overview,
+	RANGE_LABEL,
+	RANGES,
+	type Range,
+	rangeStart,
+	TOKENS_NOTE,
+	tokensOf,
+} from "./aggregate.ts";
+import { bucketize, GUTTER, plot, TICKS, xAxis } from "./chart.ts";
+import { dayKey, shortDate } from "./days.ts";
+import { duration, formatTokens, money, percent } from "./format.ts";
+import { DAY_LABEL_WIDTH, heatmap, weeksFor, YEAR_WEEKS } from "./heatmap.ts";
+import type { Call, Session } from "./load.ts";
+import { seriesPalette } from "./palette.ts";
+
+type ThemeLike = Pick<Theme, "fg" | "bg" | "bold" | "style" | "colors">;
+export type Tab = "Overview" | "Models";
+const TABS: readonly Tab[] = ["Overview", "Models"];
+/** Chart lines, at most; their colours are shared by the chart, its legend and the model list. */
+const SERIES = 3;
+/** Narrowest plot `plot` can draw; only panes too narrow for a 6-week heatmap hit it. */
+const MIN_PLOT_WIDTH = 2;
+/** Share of the pane the heatmap and chart span. */
+export const CONTENT_SHARE = 0.75;
+
+/**
+ * Columns the heatmap and the chart both span in a `paneWidth` pane (after the 1-column margin):
+ * `CONTENT_SHARE` of it, but never narrower than a year of heatmap when that fits.
+ */
+export function contentWidth(paneWidth: number): number {
+	const inner = Math.max(1, paneWidth - 1);
+	return Math.min(inner, Math.max(Math.round(inner * CONTENT_SHARE), DAY_LABEL_WIDTH + YEAR_WEEKS));
+}
+
+/** Tallest chart, in rows above the zero line. */
+const MAX_CHART_HEIGHT = 40;
+
+/** Chart rows for `available` lines: whole tick steps (so every tick is a row), 5 to 40. */
+export function chartHeight(available: number): number {
+	const steps = Math.floor(available / TICKS) * TICKS;
+	return Math.max(TICKS, Math.min(MAX_CHART_HEIGHT, steps));
+}
+
+/** Model list goes two-up from this width. */
+const TWO_COLUMN_WIDTH = 80;
+
+export interface StatsViewOptions {
+	calls: readonly Call[];
+	sessions: readonly Session[];
+	theme: ThemeLike;
+	rows: () => number;
+	requestRender: () => void;
+	onClose: () => void;
+	/** Unparseable assistant lines found while loading. */
+	badLines?: number;
+	/** Injected for tests; defaults to the local today. */
+	today?: string;
+	now?: number;
+	coverage?: string;
+	tab?: Tab;
+}
+
+/** One scroll step of the model list: a provider header, or one or two models side by side. */
+interface ListRow {
+	lines: string[];
+	/** Positions of its models in list order, for the `1-4 of N` hint. */
+	models: number[];
+}
+
+export class StatsView implements Component {
+	private tab: Tab;
+	private range: Range = "all";
+	private filterIndex = 0;
+	private scroll = 0;
+	private readonly palettes = new Map<number, Color[]>();
+	private readonly filters: Filter[];
+	private readonly today: string;
+	private readonly now: number;
+
+	constructor(private readonly o: StatsViewOptions) {
+		this.tab = o.tab ?? "Overview";
+		this.now = o.now ?? Date.now();
+		this.filters = filterCycle(o.calls.filter((c) => c.ms <= this.now));
+		this.today = o.today ?? dayKey(this.now);
+	}
+
+	invalidate(): void {
+		// Nothing themed is cached: every render rebuilds colours from the live theme.
+	}
+
+	get state(): { tab: Tab; range: Range; filter: Filter; scroll: number } {
+		return { tab: this.tab, range: this.range, filter: this.filter, scroll: this.scroll };
+	}
+
+	private get filter(): Filter {
+		return this.filters[this.filterIndex] ?? { kind: "all" };
+	}
+
+	// --- input -------------------------------------------------------------------------------
+
+	handleInput(data: string): void {
+		if (data === "q" || matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			this.o.onClose();
+			return;
+		}
+		if (matchesKey(data, Key.tab) || matchesKey(data, Key.shift("tab"))) {
+			this.tab = this.tab === "Overview" ? "Models" : "Overview";
+			this.scroll = 0;
+		} else if (data === "r") {
+			this.range = RANGES[(RANGES.indexOf(this.range) + 1) % RANGES.length] ?? "all";
+			this.scroll = 0;
+		} else if (data === "m") this.stepFilter(1);
+		else if (data === "M" || matchesKey(data, Key.shift("m"))) this.stepFilter(-1);
+		else if (data === "j" || matchesKey(data, Key.down)) this.scroll++;
+		else if (data === "k" || matchesKey(data, Key.up)) this.scroll = Math.max(0, this.scroll - 1);
+		else return;
+		this.o.requestRender();
+	}
+
+	private stepFilter(delta: number): void {
+		const n = this.filters.length;
+		this.filterIndex = (((this.filterIndex + delta) % n) + n) % n;
+		this.scroll = 0;
+	}
+
+	// --- render ------------------------------------------------------------------------------
+
+	render(width: number): string[] {
+		const w = Math.max(1, Math.floor(width));
+		const rows = Math.max(4, Math.floor(this.o.rows()));
+		const header = [this.tabsLine(), this.paint("muted", this.o.coverage ?? "local-only · never synced")];
+		const room = Math.max(0, rows - header.length - 2);
+		let body: string[];
+		let hint = "";
+		if (this.tab === "Overview") body = this.scrolled(this.overviewBody(w, room), room);
+		else {
+			const models = this.modelsBody(w, room);
+			body = this.scrolled(models.lines, room);
+			hint = this.modelHint(models.owners.slice(this.scroll, this.scroll + room), models.count);
+		}
+		while (body.length < room) body.push("");
+		return [...header, ...body, "", this.help(hint)].map((line) => truncateToWidth(` ${line}`, w, ""));
+	}
+
+	/**
+	 * `↑ ↓ 3-6 of 14 models` from the list positions on screen; arrows only where more models are.
+	 * The list follows the chart, so a window with no model in it is always above the list. Empty when
+	 * every model is visible. Lives in the help row, so it shows however short the pane.
+	 */
+	private modelHint(owners: readonly (readonly number[])[], count: number): string {
+		const shown = owners.flat();
+		if (count === 0 || new Set(shown).size === count) return "";
+		if (shown.length === 0) return `  ↓ ${count} models below`;
+		const first = Math.min(...shown) + 1;
+		const last = Math.max(...shown) + 1;
+		return `${first > 1 ? "↑" : " "} ${last < count ? "↓" : " "} ${first}-${last} of ${count} models`;
+	}
+
+	/** Clamp `scroll` and cut a `room`-line window out of `lines`. */
+	private scrolled(lines: string[], room: number): string[] {
+		this.scroll = Math.min(this.scroll, Math.max(0, lines.length - room));
+		return lines.slice(this.scroll, this.scroll + room);
+	}
+
+	private paint(color: ThemeColor, text: string): string {
+		return this.o.theme.fg(color, sanitize(text));
+	}
+
+	/**
+	 * Paint in colour `index` of a `count`-colour series palette. Hues are spread evenly for the series
+	 * actually drawn, so two providers get opposite hues (blue and orange on most themes).
+	 */
+	private paintSeries(index: number, count: number, text: string): string {
+		let palette = this.palettes.get(count);
+		if (!palette) {
+			palette = seriesPalette(this.o.theme.colors.accent, count);
+			this.palettes.set(count, palette);
+		}
+		const fg = palette[index];
+		return fg ? this.o.theme.style(sanitize(text), { fg }) : this.paint("muted", text);
+	}
+
+	private tabsLine(): string {
+		const t = this.o.theme;
+		const tabs = TABS.map((tab) => (tab === this.tab ? t.bg("selectedBg", t.bold(` ${tab} `)) : ` ${tab} `)).join(" ");
+		const bad = this.o.badLines ? `  ${this.paint("warning", `! ${this.o.badLines} unreadable lines`)}` : "";
+		return `${t.bold(this.paint("accent", "/stats"))}  ${tabs}${bad}`;
+	}
+
+	private selectors(): string {
+		const t = this.o.theme;
+		const ranges = RANGES.map((r) =>
+			r === this.range ? t.bold(this.paint("accent", RANGE_LABEL[r])) : this.paint("dim", RANGE_LABEL[r]),
+		).join(this.paint("dim", " · "));
+		return `${ranges}    ${this.paint("muted", "filter:")} ${t.bold(sanitize(filterLabel(this.filter)))}`;
+	}
+
+	private help(hint = ""): string {
+		const keys = this.paint("dim", "tab tabs · r dates · m/M filter · ↑↓ scroll · q close");
+		return hint ? `${this.paint("muted", hint)}  ${keys}` : keys;
+	}
+
+	private scoped(): { all: Call[]; ranged: Call[] } {
+		const all = this.o.calls.filter((c) => matches(this.filter, c) && inRange("all", this.today, c.ms, this.now));
+		return { all, ranged: all.filter((c) => inRange(this.range, this.today, c.ms, this.now)) };
+	}
+
+	private overviewBody(width: number, room: number): string[] {
+		const { all, ranged } = this.scoped();
+		const t = this.o.theme;
+		const out: string[] = [];
+		const daily = dailyTotals(all);
+		if (!isHourly(this.range))
+			out.push(
+				...heatmap(daily, this.today, contentWidth(width), (color, text) =>
+					color === "heat" ? this.paint("accent", text) : this.paint(color === "empty" ? "dim" : "muted", text),
+				),
+			);
+		out.push("", this.selectors(), "");
+		if (ranged.length === 0) {
+			out.push(this.paint("muted", "No usage in this range."));
+			return out;
+		}
+		const ov = overview(ranged, this.o.sessions, this.range, this.today, daily.keys());
+		const v = (s: string) => this.paint("accent", s);
+		const pairs: [string, string][] = [
+			[
+				`Favorite model: ${t.bold(v(ov.favorite ?? "-"))}`,
+				`Total tokens: ${v(formatTokens(ov.totalTokens))} ${this.paint("muted", TOKENS_NOTE)}`,
+			],
+			[`Sessions: ${v(String(ov.sessions))}`, `Longest session: ${v(duration(ov.longestSessionMs))}`],
+			[
+				`Active days: ${v(String(ov.activeDays))}${this.paint("muted", `/${ov.rangeDays}`)}`,
+				`Longest streak: ${t.bold(v(String(ov.longestStreak)))} ${ov.longestStreak === 1 ? "day" : "days"}`,
+			],
+			[
+				`Most active day: ${v(ov.mostActiveDay ? shortDate(ov.mostActiveDay) : "-")}`,
+				`Current streak: ${t.bold(v(String(ov.currentStreak)))} ${ov.currentStreak === 1 ? "day" : "days"}`,
+			],
+			[
+				`Cache tokens: ${v(formatTokens(ov.cacheRead))} read · ${v(formatTokens(ov.cacheWrite))} write`,
+				`Notional cost: ${v(money(ov.cost))}`,
+			],
+		];
+		const col = Math.max(36, Math.min(48, Math.floor(width / 2)));
+		const twoCol = width >= col * 2;
+		for (const [left, right] of pairs) {
+			if (twoCol) out.push(`${left}${" ".repeat(Math.max(2, col - visibleWidth(left)))}${right}`);
+			else out.push(left, right);
+		}
+		// Grow the chart into whatever the pane has left, in whole tick steps.
+		const smallest = this.chart(ranged, width, TICKS).lines;
+		const height = chartHeight(room - out.length - 1 - smallest.length + TICKS);
+		out.push("", ...(height === TICKS ? smallest : this.chart(ranged, width, height).lines));
+		return out;
+	}
+
+	/**
+	 * "Tokens per <bucket>", x-axis, peak/average caption and legend. One line per provider under
+	 * the "all" filter, else one per model; top three.
+	 */
+	private chart(
+		ranged: readonly Call[],
+		width: number,
+		height: number,
+	): { lines: string[]; colors: Map<string, number> } {
+		const t = this.o.theme;
+		const out: string[] = [];
+		const { by, keys: top } = chartSeries(this.filter, ranged, SERIES);
+		const colors = new Map(top.map((k, i): [string, number] => [k.key, i]));
+		if (isHourly(this.range)) {
+			const series = hourlySeries(ranged, this.range, this.now, by === "provider" ? (c) => c.provider : modelName);
+			const plotWidth = Math.max(MIN_PLOT_WIDTH, contentWidth(width) - GUTTER);
+			const p = plot(
+				top.map((k, i) => ({ values: series.map((s) => s.byKey.get(k.key) ?? 0), color: i })),
+				{
+					width: plotWidth,
+					height,
+					paint: (color, text) =>
+						color === "axis" ? this.paint("muted", text) : this.paintSeries(color, top.length, text),
+				},
+			);
+			out.push(t.bold("Tokens per hour") + this.paint("muted", `  ${TOKENS_NOTE} · by ${by}`), ...p.lines);
+			out.push(this.paint("muted", `From: ${series[0]?.day}`), this.paint("muted", `To:   ${series.at(-1)?.day}`));
+			// Repeated wall-clock hours get an explicit offset-bearing label, even between axis edges.
+			const labels = new Map<string, string>();
+			for (const point of series) {
+				const local = point.day.split(" UTC")[0] ?? point.day;
+				const prior = labels.get(local);
+				if (prior)
+					out.push(this.paint("muted", `Repeated hour: ${prior}`), this.paint("muted", `               ${point.day}`));
+				labels.set(local, point.day);
+			}
+			const peak = Math.max(0, ...series.map((s) => s.total));
+			const avg = series.reduce((n, s) => n + s.total, 0) / series.length;
+			out.push(
+				this.paint("muted", `total: peak ${formatTokens(peak)}/hour · avg ${formatTokens(avg)}/bucket · partial edges`),
+			);
+			out.push(
+				...this.legend(
+					top.map((k) => k.key),
+					colors,
+					width - 1,
+				),
+			);
+			return { lines: out, colors };
+		}
+		const from = rangeStart(this.range, this.today) ?? dayKey(ranged[0]?.ms ?? Date.now());
+		const series = dailySeries(ranged, from, this.today, by === "provider" ? (c) => c.provider : modelName);
+		const byDay = new Map(series.map((p) => [p.day, top.map((k) => p.byKey.get(k.key) ?? 0)]));
+		// Same total width as the heatmap above it: its day labels + weeks == the y gutter + plot.
+		const plotWidth = Math.max(MIN_PLOT_WIDTH, DAY_LABEL_WIDTH + weeksFor(contentWidth(width)) - GUTTER);
+		const bucketed = bucketize(from, this.today, (d) => byDay.get(d) ?? [], top.length, plotWidth + 1);
+		out.push(t.bold(`Tokens per ${bucketed.unit}`) + this.paint("muted", `  ${TOKENS_NOTE} · by ${by}`));
+		if (series.length < 2) {
+			out.push(this.paint("muted", "Not enough data for a chart yet"));
+		} else {
+			const p = plot(
+				top.map((k, i) => ({
+					values: bucketed.buckets.map((b) => b.values[i] ?? 0),
+					color: colors.get(k.key) ?? 0,
+				})),
+				{
+					width: plotWidth,
+					height,
+					paint: (color, text) =>
+						color === "axis" ? this.paint("muted", text) : this.paintSeries(color, top.length, text),
+				},
+			);
+			out.push(...p.lines, this.paint("muted", xAxis(bucketed.buckets, plotWidth, p.gutter)));
+			let peak = series[0];
+			for (const point of series) if (point.total > (peak?.total ?? 0)) peak = point;
+			const avg = series.reduce((n, point) => n + point.total, 0) / series.length;
+			out.push(
+				this.paint(
+					"muted",
+					`total: peak ${formatTokens(peak?.total ?? 0)} on ${shortDate(peak?.day ?? this.today)} · avg ${formatTokens(avg)}/day`,
+				),
+			);
+		}
+		out.push(
+			...this.legend(
+				top.map((k) => k.key),
+				colors,
+				width - 1,
+			),
+		);
+		return { lines: out, colors };
+	}
+
+	/** `● a · ● b · ● c`, wrapped onto more lines rather than cutting a series name off. */
+	private legend(keys: readonly string[], colors: ReadonlyMap<string, number>, width: number): string[] {
+		const sepText = " · ";
+		const lines: string[] = [];
+		let line = "";
+		let used = 0;
+		for (const key of keys) {
+			const cell = `${this.paintSeries(colors.get(key) ?? 0, colors.size, "●")} ${sanitize(key)}`;
+			const cellWidth = 2 + visibleWidth(sanitize(key));
+			if (used > 0 && used + sepText.length + cellWidth > width) {
+				lines.push(line);
+				line = "";
+				used = 0;
+			}
+			line += used > 0 ? `${this.paint("dim", sepText)}${cell}` : cell;
+			used += (used > 0 ? sepText.length : 0) + cellWidth;
+		}
+		if (line) lines.push(line);
+		return lines;
+	}
+
+	/**
+	 * Chart, range line and the model list, scrolled as one body like Overview so even a short pane
+	 * reaches every model. `owners[i]` holds the list positions of the models drawn on line `i`.
+	 */
+	private modelsBody(width: number, room: number): { lines: string[]; owners: number[][]; count: number } {
+		const { ranged } = this.scoped();
+		const totals = modelTotals(ranged);
+		if (totals.length === 0) {
+			const lines = [this.selectors(), "", this.paint("muted", "No usage in this range.")];
+			return { lines, owners: lines.map(() => []), count: 0 };
+		}
+		// The list scrolls under the chart, so the chart gets about half the pane.
+		const chart = this.chart(ranged, width, chartHeight(Math.floor(room / 2) - 5));
+		const head = [...chart.lines, "", this.selectors(), ""];
+		const list = this.listRows(totals, width, chart.colors);
+		return {
+			lines: [...head, ...list.flatMap((row) => row.lines)],
+			owners: [...head.map(() => []), ...list.flatMap((row) => row.lines.map(() => row.models))],
+			count: totals.length,
+		};
+	}
+
+	/**
+	 * Provider headers, then that provider's models: two per row when the pane is `TWO_COLUMN_WIDTH`
+	 * or wider, else one. Rows are indented two columns inside the overlay's one-column margin.
+	 */
+	private listRows(totals: readonly ModelTotals[], width: number, colors: ReadonlyMap<string, number>): ListRow[] {
+		const t = this.o.theme;
+		const grand = totals.reduce((n, m) => n + tokensOf(m), 0);
+		const twoUp = width >= TWO_COLUMN_WIDTH;
+		const inner = Math.max(1, width - 3);
+		const colWidth = twoUp ? Math.floor(inner / 2) : inner;
+		const bullet = (key: string) => {
+			const index = colors.get(key);
+			return index === undefined ? this.paint("muted", "•") : this.paintSeries(index, colors.size, "•");
+		};
+		const entry = (m: ModelTotals): string[] => [
+			`${bullet(m.name)} ${t.bold(sanitize(m.model))} ${this.paint("muted", `(${percent(tokensOf(m), grand)})`)}`,
+			this.paint("muted", `  In: ${formatTokens(m.input)} · Out: ${formatTokens(m.output)}`),
+			this.paint(
+				"muted",
+				`  Cache: ${formatTokens(m.cacheRead)} read · ${formatTokens(m.cacheWrite)} write · ${money(m.cost)} notional`,
+			),
+		];
+		const rows: ListRow[] = [];
+		let position = 0;
+		for (const provider of [...new Set(totals.map((m) => m.provider))]) {
+			const models = totals.filter((m) => m.provider === provider).map((m) => ({ m, i: position++ }));
+			const sum = models.reduce((n, { m }) => n + tokensOf(m), 0);
+			rows.push({
+				lines: [
+					`${bullet(provider)} ${t.bold(sanitize(provider))}  ${formatTokens(sum)} ${this.paint("muted", `(${percent(sum, grand)})`)}`,
+				],
+				models: [],
+			});
+			const per = twoUp ? 2 : 1;
+			for (let k = 0; k < models.length; k += per) {
+				const group = models.slice(k, k + per);
+				const blocks = group.map(({ m }) => entry(m));
+				const lines = [0, 1, 2].map((line) =>
+					blocks
+						.map((b, col) => {
+							const cell = truncateToWidth(
+								b[line] ?? "",
+								Math.max(1, colWidth - (col < blocks.length - 1 ? 2 : 0)),
+								"…",
+							);
+							return col < blocks.length - 1 ? cell + " ".repeat(Math.max(0, colWidth - visibleWidth(cell))) : cell;
+						})
+						.join(""),
+				);
+				rows.push({ lines: lines.map((l) => `  ${l}`), models: group.map(({ i }) => i) });
+			}
+		}
+		return rows;
+	}
+}
+
+/** Plain-text per-model table for print/json/rpc modes, all time. */
+export function summary(calls: readonly Call[]): string {
+	const totals = modelTotals(calls);
+	if (totals.length === 0) return "/stats: no usage recorded yet";
+	const grand = totals.reduce((n, m) => n + tokensOf(m), 0);
+	const head = ["provider", "model", "in", "out", "cache read", "cache write", "cost", "%"];
+	const body = totals.map((m) => [
+		sanitize(m.provider),
+		sanitize(m.model),
+		formatTokens(m.input),
+		formatTokens(m.output),
+		formatTokens(m.cacheRead),
+		formatTokens(m.cacheWrite),
+		money(m.cost),
+		percent(tokensOf(m), grand),
+	]);
+	const widths = head.map((h, c) => Math.max(h.length, ...body.map((r) => (r[c] ?? "").length)));
+	const fmt = (r: string[]) =>
+		r
+			.map((cell, c) => (c < 2 ? cell.padEnd(widths[c] ?? 0) : cell.padStart(widths[c] ?? 0)))
+			.join("  ")
+			.trimEnd();
+	return [`/stats: ${formatTokens(grand)} tokens ${TOKENS_NOTE}, all time`, fmt(head), ...body.map(fmt)].join("\n");
+}

package/src/stats/days.ts

@@ -0,0 +1,46 @@
+/** Local-calendar day keys (`YYYY-MM-DD`) and day arithmetic for `/stats`. DST-safe: built from `Date(y, m, d)`. */
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+
+function pad(n: number): string {
+	return n < 10 ? `0${n}` : String(n);
+}
+
+/** Local day key of an instant. */
+export function dayKey(ms: number | Date): string {
+	const d = ms instanceof Date ? ms : new Date(ms);
+	return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+/** Local midnight of a day key. */
+export function keyDate(key: string): Date {
+	const [y, m, d] = key.split("-").map(Number);
+	return new Date(y ?? 1970, (m ?? 1) - 1, d ?? 1);
+}
+
+export function addDays(key: string, n: number): string {
+	const d = keyDate(key);
+	return dayKey(new Date(d.getFullYear(), d.getMonth(), d.getDate() + n));
+}
+
+/** Whole days from `a` to `b` (positive when `b` is later). */
+export function daysBetween(a: string, b: string): number {
+	return Math.round((keyDate(b).getTime() - keyDate(a).getTime()) / 86_400_000);
+}
+
+/** Every key from `from` to `to`, inclusive. Empty when `from` is after `to`. */
+export function dayRange(from: string, to: string): string[] {
+	const out: string[] = [];
+	for (let k = from; k <= to; k = addDays(k, 1)) out.push(k);
+	return out;
+}
+
+export function monthName(month: number): string {
+	return MONTHS[month] ?? "";
+}
+
+/** `Oct 3` */
+export function shortDate(key: string): string {
+	const d = keyDate(key);
+	return `${monthName(d.getMonth())} ${d.getDate()}`;
+}

package/src/stats/format.ts

@@ -0,0 +1,49 @@
+/** Number and duration formatting for `/stats`. */
+
+/**
+ * `999`, `12k`, `999k`, `1M`, `1.2M`, `3.4B`: whole numbers below 1k, `k` with no decimals, `M`/`B`
+ * with one decimal minus a trailing `.0`. A value that rounds up to 1000 of a unit moves up a unit.
+ */
+export function formatTokens(n: number): string {
+	const abs = Math.abs(n);
+	if (abs < 999.5) return String(Math.round(n));
+	if (abs < 999_500) return `${Math.round(n / 1e3)}k`;
+	if (abs < 999_950_000) return `${trim((n / 1e6).toFixed(1))}M`;
+	return `${trim((n / 1e9).toFixed(1))}B`;
+}
+
+/**
+ * A y-axis tick. Same as `formatTokens` unless that would round the tick (a `2.5k` step), in which
+ * case one decimal is kept so labels never lie about where the gridline is.
+ */
+export function axisLabel(n: number): string {
+	const plain = formatTokens(n);
+	const unit = plain.endsWith("k") ? 1e3 : plain.endsWith("M") ? 1e6 : plain.endsWith("B") ? 1e9 : 1;
+	if (unit === 1 || Math.abs(Number.parseFloat(plain) * unit - n) < unit / 1e4) return plain;
+	return `${trim((n / unit).toFixed(1))}${plain.slice(-1)}`;
+}
+
+function trim(fixed: string): string {
+	return fixed.endsWith(".0") ? fixed.slice(0, -2) : fixed;
+}
+
+/** `$0.42`, `$12.30`, `$1.2k` */
+export function money(n: number): string {
+	return n >= 1000 ? `$${trim((n / 1e3).toFixed(1))}k` : `$${n.toFixed(2)}`;
+}
+
+/** `27s`, `14m`, `3h 5m`, `2d 4h` */
+export function duration(ms: number): string {
+	const s = Math.max(0, Math.round(ms / 1000));
+	if (s < 60) return `${s}s`;
+	const m = Math.floor(s / 60);
+	if (m < 60) return `${m}m`;
+	const h = Math.floor(m / 60);
+	if (h < 24) return m % 60 ? `${h}h ${m % 60}m` : `${h}h`;
+	const d = Math.floor(h / 24);
+	return h % 24 ? `${d}d ${h % 24}h` : `${d}d`;
+}
+
+export function percent(part: number, whole: number): string {
+	return whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : "0.0%";
+}

package/src/stats/heatmap.ts

@@ -0,0 +1,98 @@
+/**
+ * GitHub-style activity heatmap, Claude Code's layout: one column per week (Sunday first), Mon/Wed/Fri
+ * labels, month names over the week they start in, and four intensity levels at the quartiles of
+ * the non-zero days.
+ */
+
+import { addDays, keyDate, monthName } from "./days.ts";
+
+/** A year: the heatmap shows at least this many weeks whenever the pane fits them. */
+export const YEAR_WEEKS = 52;
+export const DAY_LABEL_WIDTH = 4;
+const LEVEL_CHARS = ["·", "░", "▒", "▓", "█"] as const;
+
+export type HeatColor = "heat" | "empty" | "label";
+
+export function quartiles(values: Iterable<number>): [number, number, number] | undefined {
+	const sorted = [...values].filter((v) => v > 0).sort((a, b) => a - b);
+	if (sorted.length === 0) return undefined;
+	const at = (q: number) => sorted[Math.floor(sorted.length * q)] ?? 0;
+	return [at(0.25), at(0.5), at(0.75)];
+}
+
+export function level(value: number, q: [number, number, number] | undefined): 0 | 1 | 2 | 3 | 4 {
+	if (value <= 0 || !q) return 0;
+	if (value >= q[2]) return 4;
+	if (value >= q[1]) return 3;
+	if (value >= q[0]) return 2;
+	return 1;
+}
+
+/**
+ * Month names over the week each month starts in. A month whose columns cannot hold its name plus
+ * a space (the clipped month at the left edge) goes unlabelled rather than crowding out the next;
+ * the newest month is always labelled, even when its name runs past the last column.
+ */
+export function monthRow(start: string, weeks: number): string {
+	const starts: { week: number; month: number }[] = [];
+	for (let w = 0; w < weeks; w++) {
+		const month = keyDate(addDays(start, w * 7)).getMonth();
+		if (starts[starts.length - 1]?.month !== month) starts.push({ week: w, month });
+	}
+	const row = new Array<string>(weeks).fill(" ");
+	starts.forEach(({ week, month }, i) => {
+		const name = monthName(month);
+		const next = starts[i + 1]?.week;
+		// The newest month may run past the grid's right edge; the others need their name plus a space.
+		if (next !== undefined && next - week < name.length + 1) return;
+		for (let c = 0; c < name.length; c++) row[week + c] = name[c] ?? " ";
+	});
+	return row.join("").trimEnd();
+}
+
+/** How many week columns fit `width`: one per column after the day labels, so wider shows more history. */
+export function weeksFor(width: number): number {
+	return Math.max(1, width - DAY_LABEL_WIDTH);
+}
+
+/**
+ * Render the heatmap for `daily` (tokens per day key) ending at `today`. Returns 7 day rows plus the
+ * month row on top and a legend row at the bottom.
+ */
+export function heatmap(
+	daily: ReadonlyMap<string, number>,
+	today: string,
+	width: number,
+	paint: (color: HeatColor, text: string) => string,
+): string[] {
+	const weeks = weeksFor(width);
+	const q = quartiles(daily.values());
+	const todayDate = keyDate(today);
+	const weekStart = addDays(today, -todayDate.getDay());
+	const start = addDays(weekStart, -(weeks - 1) * 7);
+
+	const rows: string[][] = Array.from({ length: 7 }, () => []);
+	const months = monthRow(start, weeks);
+	for (let w = 0; w < weeks; w++) {
+		const sunday = addDays(start, w * 7);
+		for (let d = 0; d < 7; d++) {
+			const day = addDays(sunday, d);
+			if (day > today) {
+				rows[d]?.push(" ");
+				continue;
+			}
+			const lv = level(daily.get(day) ?? 0, q);
+			rows[d]?.push(lv === 0 ? paint("empty", LEVEL_CHARS[0]) : paint("heat", LEVEL_CHARS[lv]));
+		}
+	}
+
+	const labels = ["   ", "Mon", "   ", "Wed", "   ", "Fri", "   "];
+	const out = [`${" ".repeat(DAY_LABEL_WIDTH)}${paint("label", months)}`];
+	for (let d = 0; d < 7; d++) out.push(`${paint("label", `${labels[d]} `)}${(rows[d] ?? []).join("")}`);
+	out.push(
+		`${" ".repeat(DAY_LABEL_WIDTH)}${paint("label", "Less ")}${[1, 2, 3, 4]
+			.map((lv) => paint("heat", LEVEL_CHARS[lv] ?? ""))
+			.join(" ")}${paint("label", " More")}`,
+	);
+	return out;
+}