@nredd/pi-session-kit 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-session-kit
 
-Published to npm as `@nredd/pi-session-kit` (public). Each version is cut by the monorepo `Publish` workflow from a signed `@nredd/pi-session-kit@<version>` tag, with npm provenance and a GitHub release carrying the tarball, checksums and manifest (`docs/releases.md`). `0.4.0` adds `createSessionKit(options)` (explicit `config`, `agentDir`, `monitorRoot`, injectable `clock` and `spawnMonitor`; the default export is unchanged) and fixes leaderless orphan-group sweeps at `ps` start-time resolution.
+Published to npm as `@nredd/pi-session-kit` (public). From `0.4.0`, each version is cut by the monorepo `Publish` workflow from a signed `@nredd/pi-session-kit@<version>` tag, with npm provenance and a GitHub release carrying the tarball, checksums and manifest (`docs/releases.md`); earlier versions were published manually without provenance. `0.4.0` adds `createSessionKit(options)` (explicit `config`, `agentDir`, `monitorRoot`, injectable `clock` and `spawnMonitor`; the default export is unchanged) and fixes leaderless orphan-group sweeps at `ps` start-time resolution. `0.5.0` redesigns `/stats` around the full pane (pinned header, aligned stat cells, a Models table on wide panes) and gives every chart a clock- or calendar-aligned time axis, including the 5h and 24h hourly views.
 Use the [monorepo development commands](https://github.com/nredd/pi-harness/blob/main/README.md). The Git install and standalone harness
 references below describe the legacy deployment, not installation or candidate verification of
 this package.
@@ -96,21 +96,37 @@ non-triggering display message. The overlay is TUI-only and works in Plan mode.
 `/stats` is Claude Code's `/stats` pane over fresh local sessions plus imported machine snapshots,
 split by provider and model. It NEVER performs network I/O. Machine coverage and the last successful
 remote import are shown; unsynced machines show `local-only` / `never synced`. Invalid or missing
-snapshots retain last-good data and show `incomplete coverage`. Overview: an activity heatmap (one column per week), headline numbers (favorite model, total tokens,
-sessions, longest session, active days, streaks, cache tokens, notional cost) and the token chart.
-Models: the chart, then every model grouped under its provider with in/out/cache/cost, two-up from
-80 columns. Tab switches tabs, `r` cycles All / 7d / 30d / 5h / 24h (default All), `m`/`M` cycle the filter
-(All, each provider, each `provider/model`), `j/k` or arrows scroll, `q` or Escape closes.
+snapshots retain last-good data and show `incomplete coverage`.
+
+Pinned header: tabs and the coverage note, then the date ranges and the model filter, then a rule.
+Overview: an activity heatmap (one column per week) with the headline numbers (favorite model,
+total tokens, sessions, longest session, active days, streaks, cache tokens, notional cost) beside
+it from about 105 columns and under it below that, then the token chart. Models: the chart, then every
+model grouped under its provider. From about 100 columns that is a table (tokens, share, in, out, cache
+read, cache write, notional cost; a subtotal line per provider), else three-line cards. Tab switches
+tabs, `r` cycles All / 7d / 30d / 5h / 24h (default All), `m`/`M` cycle the filter (All, each provider,
+each `provider/model`), `j/k` or arrows scroll, `q` or Escape closes.
 
 - The chart is an asciichart-style line plot (`╭╮╰╯`), one line per provider under All, else the top
   three models. Where lines overlap they merge into junctions (`┴┬├┤┼`) so every line stays
   connected; the larger series keeps the colour. Line colours start at the theme's `accent` hue,
   saturated, with hues spread evenly over the lines drawn (two providers get opposite hues), so
-  muted themes still separate them. The heatmap and the chart span 75% of the pane, with the same right edge; the heatmap shows as
-  many weeks as fit, never less than a year when the pane allows. Days sum into 1/2/3/7/14/30-day buckets (longer
-  when needed) so the range fits the width; short ranges are interpolated, not stepped. Y ticks land
-  on round values with little headroom. Height follows the pane in whole tick steps (5 to 40 rows):
-  Overview grows the chart into the rows it has left, Models gives it about half.
+  muted themes still separate them. The title row carries the legend on its right (it wraps under the
+  title on narrow panes). Every block spans the whole pane, except the heatmap, which shows as many
+  weeks as fit up to two years. Days sum into 1/2/3/7/14/30-day buckets (longer when needed) so the
+  range fits the width; short ranges are interpolated, not stepped. Y ticks land on round values with
+  little headroom. Height follows the pane in whole tick steps (5 to 40 rows): Overview grows the chart
+  into the rows it has left, Models gives it what a short list leaves, at least half.
+- X axis: a baseline with a mark under every tick, labels centred on their bucket's column (the first and
+  last clamp to the plot edges). Ticks are evenly spaced, at most 13, never overlap and are never cut; the
+  finest set whose labels fit wins, so a wider pane gets more of them. 5h and 24h label hours starting on
+  the clock (`09:00`, or `9a` / `12p` when narrow; every hour, 2, 3, 4, 6, 12 or 24 hours apart; across a
+  DST change they stay evenly spaced, so later labels shift by the hour) with a row of dates where they
+  fit: each new local day first, then the first bucket. Day buckets: a week of single days gets `Wed 7`
+  (or `Wed`), longer ranges get dates on every day, 2 or 3 days, every Monday or every other Monday
+  (counted back from today for multi-day buckets), then month names, quarters, half years and years, with
+  `'26` only where the ticks span more than one year. A pane too narrow for any label draws the baseline
+  alone.
 - Rolling 5h/24h use the original call timestamps in zero-filled one-hour UTC buckets, with
   partial edges labeled. Labels use viewer-local time and UTC offsets, including repeated DST
   hours. The same rolling filter feeds chart/model/overview totals; future calls are ignored in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nredd/pi-session-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },

package/src/stats/aggregate.ts

@@ -34,6 +34,8 @@ export interface ModelTotals {
 
 export interface DayPoint {
 	day: string;
+	/** Bucket start instant; hourly series only. */
+	ms?: number;
 	/** Tokens per series key (provider, or `provider/model`). */
 	byKey: Map<string, number>;
 	total: number;
@@ -210,6 +212,7 @@ export function hourlySeries(
 	const points: DayPoint[] = [];
 	for (let ms = from; ms <= to; ms += HOUR_MS)
 		points.push({
+			ms,
 			day: `${hourLabel(ms)}${ms < start || ms + HOUR_MS > now ? " (partial)" : ""}`,
 			byKey: new Map(),
 			total: 0,

package/src/stats/chart.ts

@@ -1,13 +1,13 @@
 /**
  * The "Tokens per day" line chart: an asciichart-style plot (`╭╮╰╯│─`) with nice y-axis ticks and
- * date labels. Pure: colours go through a `paint` callback so tests can render plain text.
+ * time ticks in `ticks.ts`. Pure: colours go through a `paint` callback so tests can render plain text.
  *
  * Days are bucketed (1, 2, 3, 7, 14 or 30 days) so the whole range fits the width, then sampled
  * with linear interpolation across every column so a short range draws a smooth curve rather
  * than a staircase.
  */
 
-import { addDays, daysBetween, shortDate } from "./days.ts";
+import { addDays, daysBetween } from "./days.ts";
 import { axisLabel } from "./format.ts";
 
 export const BUCKET_SIZES = [1, 2, 3, 7, 14, 30] as const;
@@ -194,7 +194,7 @@ export function plot<C extends string | number>(series: readonly Series<C>[], op
 		const y = height - r;
 		const tick = Number.isInteger(y / perTick) ? y / perTick : -1;
 		const label = tick >= 0 ? (labels[tick] ?? "") : "";
-		const axis = y === 0 ? "┼" : tick >= 0 ? "┤" : "│";
+		const axis = tick >= 0 ? "┤" : "│";
 		let body = "";
 		let run = "";
 		let runColor: C | undefined;
@@ -214,34 +214,3 @@ export function plot<C extends string | number>(series: readonly Series<C>[], op
 	}
 	return { lines, gutter: labelWidth + 2, max };
 }
-
-/**
- * Two to five date labels under a plot of `width` columns spanning `buckets`: first and last always,
- * evenly spaced ones between when they fit with two spaces of air. Never past the plot's right edge.
- */
-export function xAxis(buckets: readonly Bucket[], width: number, gutter: number): string {
-	if (buckets.length === 0 || width <= 0) return "";
-	const last = buckets.length - 1;
-	const at = (col: number) => buckets[Math.round((col * last) / Math.max(1, width))]?.start ?? "";
-	const line = new Array<string>(width).fill(" ");
-	const place = (col: number, text: string): boolean => {
-		const start = Math.max(0, Math.min(width - text.length, col));
-		for (let i = Math.max(0, start - 2); i < Math.min(width, start + text.length + 2); i++) {
-			if (line[i] !== " ") return false;
-		}
-		for (let i = 0; i < text.length && start + i < width; i++) line[start + i] = text[i] ?? " ";
-		return true;
-	};
-	const first = shortDate(buckets[0]?.start ?? "");
-	const end = shortDate(buckets[last]?.start ?? "");
-	// The newest date first: on a plot too narrow for both, today's end of the range wins.
-	if (last > 0) place(width - end.length, end);
-	place(0, first);
-	if (last === 0) return `${" ".repeat(gutter)}${line.join("").trimEnd()}`;
-	const slots = Math.max(1, Math.min(4, Math.floor(width / 14)));
-	for (let i = 1; i < slots; i++) {
-		const col = Math.round((i * width) / slots);
-		place(col - 3, shortDate(at(col)));
-	}
-	return `${" ".repeat(gutter)}${line.join("").trimEnd()}`;
-}

package/src/stats/component.ts

@@ -21,6 +21,7 @@ import {
 	matches,
 	modelName,
 	modelTotals,
+	type Overview,
 	overview,
 	RANGE_LABEL,
 	RANGES,
@@ -29,12 +30,13 @@ import {
 	TOKENS_NOTE,
 	tokensOf,
 } from "./aggregate.ts";
-import { bucketize, GUTTER, plot, TICKS, xAxis } from "./chart.ts";
-import { dayKey, shortDate } from "./days.ts";
+import { bucketize, GUTTER, plot, TICKS } from "./chart.ts";
+import { dayKey, keyDate, shortDate } from "./days.ts";
 import { duration, formatTokens, money, percent } from "./format.ts";
-import { DAY_LABEL_WIDTH, heatmap, weeksFor, YEAR_WEEKS } from "./heatmap.ts";
+import { DAY_LABEL_WIDTH, heatmap, MAX_WEEKS, MONTH_OVERFLOW, weeksFor, YEAR_WEEKS } from "./heatmap.ts";
 import type { Call, Session } from "./load.ts";
 import { seriesPalette } from "./palette.ts";
+import { timeAxis } from "./ticks.ts";
 
 type ThemeLike = Pick<Theme, "fg" | "bg" | "bold" | "style" | "colors">;
 export type Tab = "Overview" | "Models";
@@ -43,16 +45,10 @@ const TABS: readonly Tab[] = ["Overview", "Models"];
 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.
- */
+/** Columns every block spans in a `paneWidth` pane: all of it after the 1-column margin. */
 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));
+	return Math.max(1, paneWidth - 1);
 }
 
 /** Tallest chart, in rows above the zero line. */
@@ -64,8 +60,8 @@ export function chartHeight(available: number): number {
 	return Math.max(TICKS, Math.min(MAX_CHART_HEIGHT, steps));
 }
 
-/** Model list goes two-up from this width. */
-const TWO_COLUMN_WIDTH = 80;
+/** Columns between the heatmap and the numbers beside it, and between number columns. */
+const GAP = 4;
 
 export interface StatsViewOptions {
 	calls: readonly Call[];
@@ -84,6 +80,9 @@ export interface StatsViewOptions {
 }
 
 /** One scroll step of the model list: a provider header, or one or two models side by side. */
+/** Per-provider or per-model sums the list shows. */
+type Totals = Pick<ModelTotals, "input" | "output" | "cacheRead" | "cacheWrite" | "cost">;
+
 interface ListRow {
 	lines: string[];
 	/** Positions of its models in list order, for the `1-4 of N` hint. */
@@ -151,7 +150,7 @@ export class StatsView implements Component {
 	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 header = this.header(contentWidth(w), rows);
 		const room = Math.max(0, rows - header.length - 2);
 		let body: string[];
 		let hint = "";
@@ -165,6 +164,24 @@ export class StatsView implements Component {
 		return [...header, ...body, "", this.help(hint)].map((line) => truncateToWidth(` ${line}`, w, ""));
 	}
 
+	/**
+	 * Tabs and warning with the coverage note flush right, then the range and filter (what `r` and `m`
+	 * change), then a rule. Pinned above the scrolling body. Coverage drops under the selectors when the
+	 * tabs row cannot hold it; on a very short pane the rule goes first.
+	 */
+	private header(inner: number, rows: number): string[] {
+		const coverage = this.paint("muted", this.o.coverage ?? "local-only · never synced");
+		const tabs = this.tabsLine();
+		const joined = spread(tabs, coverage, inner);
+		const lines = [
+			joined ?? tabs,
+			...this.selectors(inner),
+			...(joined ? [] : [coverage]),
+			this.paint("dim", "─".repeat(inner)),
+		];
+		return lines.slice(0, Math.max(2, Math.min(lines.length, rows - 2)));
+	}
+
 	/**
 	 * `↑ ↓ 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
@@ -210,12 +227,31 @@ export class StatsView implements Component {
 		return `${t.bold(this.paint("accent", "/stats"))}  ${tabs}${bad}`;
 	}
 
-	private selectors(): string {
+	/** Range choices and the filter on one line, or the filter on its own line when they do not fit. */
+	private selectors(inner: number): 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)))}`;
+		const filter = `${this.paint("muted", "filter:")} ${t.bold(sanitize(filterLabel(this.filter)))}`;
+		const line = `${ranges}    ${filter}`;
+		return visibleWidth(line) <= inner ? [line] : [ranges, truncateToWidth(filter, inner, "…")];
+	}
+
+	/** Muted `parts` joined by a dim ` · `, wrapped onto more lines rather than cut. */
+	private wrapParts(parts: readonly string[], inner: number): string[] {
+		const sep = this.paint("dim", " · ");
+		const lines: string[] = [];
+		let line = "";
+		for (const part of parts.map((p) => this.paint("muted", p))) {
+			if (line && visibleWidth(line) + 3 + visibleWidth(part) > inner) {
+				lines.push(line);
+				line = "";
+			}
+			line += (line ? sep : "") + part;
+		}
+		if (line) lines.push(line);
+		return lines.map((l) => truncateToWidth(l, inner, "…"));
 	}
 
 	private help(hint = ""): string {
@@ -228,49 +264,96 @@ export class StatsView implements Component {
 		return { all, ranged: all.filter((c) => inRange(this.range, this.today, c.ms, this.now)) };
 	}
 
+	/**
+	 * Headline numbers as `label  value` cells, in reading order: favorite model and total tokens,
+	 * sessions and longest session, and so on.
+	 */
+	private statCells(ov: Overview): { label: string; value: string }[] {
+		const t = this.o.theme;
+		const v = (s: string) => this.paint("accent", s);
+		const days = (n: number) => `${t.bold(v(String(n)))} ${n === 1 ? "day" : "days"}`;
+		return [
+			{ label: "Favorite model", value: t.bold(v(ov.favorite ?? "-")) },
+			{ label: "Total tokens", value: `${v(formatTokens(ov.totalTokens))} ${this.paint("muted", TOKENS_NOTE)}` },
+			{ label: "Sessions", value: v(String(ov.sessions)) },
+			{ label: "Longest session", value: v(duration(ov.longestSessionMs)) },
+			{ label: "Active days", value: `${v(String(ov.activeDays))}${this.paint("muted", `/${ov.rangeDays}`)}` },
+			{ label: "Longest streak", value: days(ov.longestStreak) },
+			{ label: "Most active day", value: v(ov.mostActiveDay ? shortDate(ov.mostActiveDay) : "-") },
+			{ label: "Current streak", value: days(ov.currentStreak) },
+			{
+				label: "Cache tokens",
+				value: `${v(formatTokens(ov.cacheRead))} read · ${v(formatTokens(ov.cacheWrite))} write`,
+			},
+			{ label: "Notional cost", value: v(money(ov.cost)) },
+		];
+	}
+
+	/**
+	 * Cells in `columns` columns, row-major, each column's labels and values aligned; `columns` shrinks
+	 * until the grid fits `width`.
+	 */
+	private statGrid(cells: readonly { label: string; value: string }[], width: number, columns: number): string[] {
+		const widthOf = (cols: number) => {
+			const per = Array.from({ length: cols }, (_, c) => cells.filter((_, i) => i % cols === c));
+			// Every label is padded to the column's longest, so a cell is that plus the widest value.
+			return per.map((col) => {
+				const label = Math.max(0, ...col.map((x) => x.label.length));
+				return { label, cell: label + 2 + Math.max(0, ...col.map((x) => visibleWidth(x.value))) };
+			});
+		};
+		let cols = Math.max(1, Math.min(columns, cells.length));
+		while (cols > 1 && widthOf(cols).reduce((n, c) => n + c.cell, 0) + GAP * (cols - 1) > width) cols--;
+		const sizes = widthOf(cols);
+		const out: string[] = [];
+		for (let r = 0; r < cells.length; r += cols) {
+			out.push(
+				cells
+					.slice(r, r + cols)
+					.map((cell, c) => {
+						const size = sizes[c];
+						const text = `${this.paint("muted", cell.label.padEnd(size?.label ?? 0))}  ${cell.value}`;
+						return c < cols - 1 ? padTo(text, (size?.cell ?? 0) + GAP) : text;
+					})
+					.join(""),
+			);
+		}
+		return out.map((line) => truncateToWidth(line, width, "…"));
+	}
+
 	private overviewBody(width: number, room: number): string[] {
 		const { all, ranged } = this.scoped();
-		const t = this.o.theme;
+		const inner = contentWidth(width);
 		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),
-				),
+		const showHeat = !isHourly(this.range);
+		if (ranged.length === 0 && !showHeat) return [this.paint("muted", "No usage in this range.")];
+		const cells =
+			ranged.length === 0
+				? []
+				: this.statCells(overview(ranged, this.o.sessions, this.range, this.today, daily.keys()));
+		const heat = (area: number) =>
+			heatmap(daily, this.today, area, (color, text) =>
+				color === "heat" ? this.paint("accent", text) : this.paint(color === "empty" ? "dim" : "muted", text),
 			);
-		out.push("", this.selectors(), "");
+		if (showHeat) {
+			// Numbers beside the heatmap when a year of it still fits next to them, else underneath.
+			const column = this.statGrid(cells, inner, 1);
+			const beside = Math.max(0, ...column.map(visibleWidth));
+			const area = Math.min(inner - GAP - beside, DAY_LABEL_WIDTH + MAX_WEEKS + MONTH_OVERFLOW);
+			if (cells.length > 0 && weeksFor(area) >= YEAR_WEEKS) {
+				const left = heat(area);
+				for (let i = 0; i < Math.max(left.length, column.length); i++)
+					out.push(`${padTo(left[i] ?? "", area + GAP)}${column[i] ?? ""}`.trimEnd());
+			} else {
+				out.push(...heat(inner));
+				if (cells.length > 0) out.push("", ...this.statGrid(cells, inner, 2));
+			}
+		} else out.push(...this.statGrid(cells, inner, width >= 130 ? 3 : 2));
 		if (ranged.length === 0) {
-			out.push(this.paint("muted", "No usage in this range."));
+			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);
@@ -279,8 +362,8 @@ export class StatsView implements Component {
 	}
 
 	/**
-	 * "Tokens per <bucket>", x-axis, peak/average caption and legend. One line per provider under
-	 * the "all" filter, else one per model; top three.
+	 * Title, legend, plot, time axis and a peak/average caption. One line per provider under the "all"
+	 * filter, else one per model; top three. The legend shares the title row when both fit.
 	 */
 	private chart(
 		ranged: readonly Call[],
@@ -288,23 +371,49 @@ export class StatsView implements Component {
 		height: number,
 	): { lines: string[]; colors: Map<string, number> } {
 		const t = this.o.theme;
-		const out: string[] = [];
+		const inner = contentWidth(width);
 		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 hourly = isHourly(this.range);
+		const unit = hourly ? "hour" : undefined;
+		const title = (name: string) => t.bold(name) + this.paint("muted", `  ${TOKENS_NOTE} · by ${by}`);
+		const legend = this.legend(
+			top.map((k) => k.key),
+			colors,
+			inner,
+		);
+		const head = (name: string): string[] => {
+			const row = legend.length === 1 ? spread(title(name), legend[0] ?? "", inner) : undefined;
+			if (row) return [row];
+			// A pane too narrow for the title splits the name from its unit note.
+			const lines =
+				visibleWidth(title(name)) <= inner
+					? [title(name)]
+					: [t.bold(name), this.paint("muted", truncateToWidth(`${TOKENS_NOTE} · by ${by}`, inner, "…"))];
+			return [...lines, ...legend];
+		};
+		const paint = (color: number | "axis", text: string) =>
+			color === "axis" ? this.paint("muted", text) : this.paintSeries(color, top.length, text);
+		const plotWidth = Math.max(MIN_PLOT_WIDTH, inner - GUTTER);
+		if (hourly) {
+			const series = hourlySeries(
+				ranged,
+				this.range as "5h" | "24h",
+				this.now,
+				by === "provider" ? (c) => c.provider : modelName,
+			);
 			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),
-				},
+				{ width: plotWidth, height, paint },
 			);
-			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}`));
+			const axis = timeAxis(
+				series.map((s) => s.ms ?? 0),
+				{ kind: "hour" },
+				plotWidth,
+				p.gutter,
+			);
+			const out = [...head(`Tokens per ${unit}`), ...p.lines, ...axis.lines.map((l) => this.paint("muted", l))];
+			out.push(...this.wrapParts([`From: ${series[0]?.day}`, `To: ${series.at(-1)?.day}`], inner));
 			// 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) {
@@ -317,13 +426,9 @@ export class StatsView implements Component {
 			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,
+				...this.wrapParts(
+					[`total: peak ${formatTokens(peak)}/hour`, `avg ${formatTokens(avg)}/hour`, "partial edges"],
+					inner,
 				),
 			);
 			return { lines: out, colors };
@@ -331,41 +436,36 @@ export class StatsView implements Component {
 		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}`));
+		const out = head(`Tokens per ${bucketed.unit}`);
 		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`,
-				),
-			);
+			return { lines: out, colors };
 		}
+		const p = plot(
+			top.map((k, i) => ({
+				values: bucketed.buckets.map((b) => b.values[i] ?? 0),
+				color: colors.get(k.key) ?? i,
+			})),
+			{ width: plotWidth, height, paint },
+		);
+		const axis = timeAxis(
+			bucketed.buckets.map((b) => keyDate(b.start).getTime()),
+			{ kind: "day", size: bucketed.size },
+			plotWidth,
+			p.gutter,
+		);
+		out.push(...p.lines, ...axis.lines.map((l) => this.paint("muted", l)));
+		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.legend(
-				top.map((k) => k.key),
-				colors,
-				width - 1,
+			...this.wrapParts(
+				[
+					`total: peak ${formatTokens(peak?.total ?? 0)} on ${shortDate(peak?.day ?? this.today)}`,
+					`avg ${formatTokens(avg)}/day`,
+				],
+				inner,
 			),
 		);
 		return { lines: out, colors };
@@ -393,20 +493,22 @@ export class StatsView implements Component {
 	}
 
 	/**
-	 * 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`.
+	 * Chart 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.")];
+			const lines = [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);
+		// The list scrolls under the chart: the chart gets what a short list leaves, at least half the pane.
+		const colors = this.chart(ranged, width, TICKS).colors;
+		const list = this.listRows(totals, contentWidth(width), colors);
+		const listLines = list.reduce((n, row) => n + row.lines.length, 0);
+		const chart = this.chart(ranged, width, chartHeight(Math.max(Math.floor(room / 2), room - listLines) - 7));
+		const head = [...chart.lines, ""];
 		return {
 			lines: [...head, ...list.flatMap((row) => row.lines)],
 			owners: [...head.map(() => []), ...list.flatMap((row) => row.lines.map(() => row.models))],
@@ -415,19 +517,75 @@ export class StatsView implements Component {
 	}
 
 	/**
-	 * 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.
+	 * Models grouped under their provider: a table when its columns fit, one aligned line per model with a
+	 * provider subtotal line above its models, else three-line cards one per row. Indented two columns.
 	 */
-	private listRows(totals: readonly ModelTotals[], width: number, colors: ReadonlyMap<string, number>): ListRow[] {
+	private listRows(totals: readonly ModelTotals[], inner: 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 sumOf = (models: readonly ModelTotals[]): Totals => ({
+			input: models.reduce((n, m) => n + m.input, 0),
+			output: models.reduce((n, m) => n + m.output, 0),
+			cacheRead: models.reduce((n, m) => n + m.cacheRead, 0),
+			cacheWrite: models.reduce((n, m) => n + m.cacheWrite, 0),
+			cost: models.reduce((n, m) => n + m.cost, 0),
+		});
+		const providers = [...new Set(totals.map((m) => m.provider))].map((provider) => {
+			const models = totals.filter((m) => m.provider === provider);
+			const sub = sumOf(models);
+			return { provider, models, sub, sum: models.reduce((n, m) => n + tokensOf(m), 0) };
+		});
+		const rows: ListRow[] = [];
+		let position = 0;
+		const numbers = (m: Totals, sum: number) => [
+			formatTokens(sum),
+			percent(sum, grand),
+			formatTokens(m.input),
+			formatTokens(m.output),
+			formatTokens(m.cacheRead),
+			formatTokens(m.cacheWrite),
+			money(m.cost),
+		];
+		const heads = ["Tokens", "Share", "In", "Out", "Cache read", "Cache write", "Cost (notional)"];
+		const nameWidth = Math.max(
+			...totals.map((m) => visibleWidth(sanitize(m.model)) + 4),
+			...providers.map((p) => visibleWidth(sanitize(p.provider)) + 2),
+		);
+		const widths = heads.map((h, c) =>
+			Math.max(
+				h.length,
+				...totals.map((m) => (numbers(m, tokensOf(m))[c] ?? "").length),
+				...providers.map((p) => (numbers(p.sub, p.sum)[c] ?? "").length),
+			),
+		);
+		const tableWidth = 2 + nameWidth + widths.reduce((n, x) => n + x + 2, 0);
+		if (tableWidth <= inner) {
+			const line = (name: string, cells: readonly string[], paint: (s: string) => string) =>
+				`  ${padTo(name, nameWidth)}${cells.map((cell, c) => paint(cell.padStart((widths[c] ?? 0) + 2))).join("")}`;
+			rows.push({ lines: [line("", heads, (s) => this.paint("muted", s))], models: [] });
+			for (const { provider, models, sub, sum } of providers) {
+				rows.push({
+					lines: [line(`${bullet(provider)} ${t.bold(sanitize(provider))}`, numbers(sub, sum), (s) => t.bold(s))],
+					models: [],
+				});
+				for (const m of models)
+					rows.push({
+						lines: [
+							line(
+								`${colors.has(m.name) ? `  ${bullet(m.name)} ` : "    "}${sanitize(m.model)}`,
+								numbers(m, tokensOf(m)),
+								(s) => this.paint("muted", s),
+							),
+						],
+						models: [position++],
+					});
+			}
+			return rows;
+		}
 		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)}`),
@@ -436,40 +594,34 @@ export class StatsView implements Component {
 				`  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);
+		for (const { provider, models, sum } of providers) {
 			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) });
-			}
+			for (const m of models)
+				rows.push({
+					lines: entry(m).map((l) => `  ${truncateToWidth(l, Math.max(1, inner - 2), "…")}`),
+					models: [position++],
+				});
 		}
 		return rows;
 	}
 }
 
+/** `text` padded with spaces to `width` columns (ANSI-aware); never cuts. */
+function padTo(text: string, width: number): string {
+	return text + " ".repeat(Math.max(0, width - visibleWidth(text)));
+}
+
+/** `left` and `right` on one `width`-column line, right flush; `undefined` if they would touch. */
+function spread(left: string, right: string, width: number): string | undefined {
+	const gap = width - visibleWidth(left) - visibleWidth(right);
+	return gap >= 3 ? `${left}${" ".repeat(gap)}${right}` : undefined;
+}
+
 /** Plain-text per-model table for print/json/rpc modes, all time. */
 export function summary(calls: readonly Call[]): string {
 	const totals = modelTotals(calls);

package/src/stats/days.ts

@@ -35,6 +35,13 @@ export function dayRange(from: string, to: string): string[] {
 	return out;
 }
 
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const;
+
+/** `Mon` for `Date#getDay()` 1. */
+export function weekdayName(day: number): string {
+	return WEEKDAYS[day] ?? "";
+}
+
 export function monthName(month: number): string {
 	return MONTHS[month] ?? "";
 }

package/src/stats/heatmap.ts

@@ -8,6 +8,10 @@ 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;
+/** Two years: older weeks are dead space, so wide panes stop here. */
+export const MAX_WEEKS = 104;
+/** Columns the newest month's name can run past the last week: callers leave this much room. */
+export const MONTH_OVERFLOW = 2;
 export const DAY_LABEL_WIDTH = 4;
 const LEVEL_CHARS = ["·", "░", "▒", "▓", "█"] as const;
 
@@ -50,9 +54,12 @@ export function monthRow(start: string, weeks: number): string {
 	return row.join("").trimEnd();
 }
 
-/** How many week columns fit `width`: one per column after the day labels, so wider shows more history. */
+/**
+ * How many week columns fit `width`: one per column after the day labels and the room the newest
+ * month's name may run into, up to `MAX_WEEKS`.
+ */
 export function weeksFor(width: number): number {
-	return Math.max(1, width - DAY_LABEL_WIDTH);
+	return Math.min(MAX_WEEKS, Math.max(1, width - DAY_LABEL_WIDTH - MONTH_OVERFLOW));
 }
 
 /**

package/src/stats/ticks.ts

@@ -0,0 +1,241 @@
+/**
+ * X-axis ticks for the `/stats` time-series charts, one rule for every timescale.
+ *
+ * A chart has `n` buckets stretched over `width` plot columns, bucket `k` on column
+ * `round(k * width / (n - 1))` (see `stretch`). A tick is a bucket. Candidate tick sets run from fine
+ * to coarse (every hour, every 2 hours, ... / every day, every Monday, every 14 days, ... / every
+ * month, every quarter, ...), each with a wide and a narrow label format. The first set whose labels
+ * all fit, with air between them and at most `MAX_TICKS` of them, wins. So ticks are evenly spaced
+ * (clock- or calendar-aligned), never overlap, and are never cut: a label that cannot fit is not drawn.
+ */
+
+import { dayKey, monthName, shortDate, weekdayName } from "./days.ts";
+
+/** What one bucket spans. `size` is days per bucket for the daily scale. */
+export type Timescale = { kind: "hour" } | { kind: "day"; size: number };
+
+export interface Tick {
+	/** Bucket index. */
+	bucket: number;
+	/** Plot column the bucket sits on. */
+	column: number;
+	label: string;
+	/** Column the label's first character is drawn in. */
+	start: number;
+}
+
+export interface TimeAxis {
+	ticks: Tick[];
+	/** Baseline with a mark per tick, labels, and for hourly charts a row of dates. */
+	lines: string[];
+}
+
+/** More labels than this stop reading as an axis. */
+export const MAX_TICKS = 13;
+/** Hours between ticks, finest first; all divide a day so ticks land on the clock. */
+const HOUR_STRIDES = [1, 2, 3, 4, 6, 12, 24] as const;
+/** Days between ticks for the daily scale, finest first. */
+const DAY_STRIDES = [1, 2, 3, 7, 14] as const;
+/** Months between ticks, finest first. */
+const MONTH_STRIDES = [1, 2, 3, 6, 12] as const;
+/** Weekday names label every bucket up to this many days. */
+const WEEKDAY_MAX = 8;
+/** Blank columns required between two labels, for the wide and the narrow variant. */
+const GAP = [3, 2] as const;
+
+interface Mark {
+	bucket: number;
+	/** Wide to narrow. */
+	labels: string[];
+}
+
+const pad2 = (n: number): string => (n < 10 ? `0${n}` : String(n));
+
+/** `09:00`, or `05:30` where the zone's hours start at :30. */
+export function hourWide(ms: number): string {
+	const d = new Date(ms);
+	return `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+
+/** `9a`, `12p`: the short 12-hour form. Half-hour zones keep `05:30`, already as short as it gets. */
+export function hourNarrow(ms: number): string {
+	const d = new Date(ms);
+	if (d.getMinutes()) return hourWide(ms);
+	return `${d.getHours() % 12 || 12}${d.getHours() < 12 ? "a" : "p"}`;
+}
+
+/** Bucket column on a `width`-column plot, the last bucket on the last column. */
+export function bucketColumn(bucket: number, count: number, width: number): number {
+	if (count <= 1 || width <= 1) return 0;
+	return Math.min(width - 1, Math.round((bucket * width) / (count - 1)));
+}
+
+/**
+ * Every `stride`-th bucket from the first one on the clock. Stepping by bucket, not by local hour,
+ * keeps ticks evenly spaced across a DST change; labels after it shift by the hour gained or lost.
+ */
+function hourLevels(starts: readonly number[]): Mark[][] {
+	return HOUR_STRIDES.map((stride) => {
+		const marks: Mark[] = [];
+		const anchor = starts.findIndex((ms) => new Date(ms).getHours() % stride === 0);
+		for (let bucket = anchor; anchor >= 0 && bucket < starts.length; bucket += stride) {
+			const ms = starts[bucket] ?? 0;
+			marks.push({ bucket, labels: [hourWide(ms), hourNarrow(ms)] });
+		}
+		return marks;
+	});
+}
+
+/** Buckets `stride` apart counted back from the newest, so today is always labelled. */
+function fromNewest(count: number, stride: number): number[] {
+	const out: number[] = [];
+	for (let k = count - 1; k >= 0; k -= stride) out.unshift(k);
+	return out;
+}
+
+function dayLevels(starts: readonly number[], size: number): Mark[][] {
+	const n = starts.length;
+	const levels: Mark[][] = [];
+	if (size === 1 && n <= WEEKDAY_MAX) {
+		levels.push(
+			starts.map((ms, bucket) => ({
+				bucket,
+				labels: [`${weekdayName(new Date(ms).getDay())} ${new Date(ms).getDate()}`],
+			})),
+		);
+		levels.push(starts.map((ms, bucket) => ({ bucket, labels: [weekdayName(new Date(ms).getDay())] })));
+	}
+	for (const days of DAY_STRIDES) {
+		if (days % size !== 0) continue;
+		const stride = days / size;
+		let buckets = fromNewest(n, stride);
+		if (size === 1 && days % 7 === 0) {
+			// Whole weeks: every `days`-th Monday, newest first.
+			const newest = starts.map((ms) => new Date(ms).getDay()).lastIndexOf(1);
+			buckets = newest < 0 ? [] : fromNewest(newest + 1, stride);
+		}
+		levels.push(buckets.map((bucket) => ({ bucket, labels: [shortDate(dayKey(starts[bucket] ?? 0))] })));
+	}
+	// A bucket carries the month whose first day it contains; the first label of a year carries it.
+	// A bucket ends where the next starts (the first is often partial, DST days are 23 or 25 hours);
+	// the last spans `size` calendar days.
+	const firsts: { bucket: number; month: number; year: number }[] = [];
+	starts.forEach((ms, bucket) => {
+		const d = new Date(ms);
+		const end = starts[bucket + 1] ?? new Date(d.getFullYear(), d.getMonth(), d.getDate() + size).getTime();
+		const first = d.getDate() === 1 ? d : new Date(d.getFullYear(), d.getMonth() + 1, 1);
+		if (first.getTime() < end) firsts.push({ bucket, month: first.getMonth(), year: first.getFullYear() });
+	});
+	for (const stride of MONTH_STRIDES) {
+		const picked = firsts.filter((f) => f.month % stride === 0);
+		// Years only when the ticks span more than one, on the first tick and every January; then no
+		// variant drops them, so `Jan`, `Jan` never repeats unlabelled.
+		const years = new Set(picked.map((f) => f.year)).size > 1;
+		levels.push(
+			picked.map((f, i) => {
+				const plain = monthName(f.month);
+				const tagged = years && (i === 0 || f.month === 0) ? `${plain} '${pad2(f.year % 100)}` : plain;
+				return { bucket: f.bucket, labels: years ? [tagged] : [plain] };
+			}),
+		);
+	}
+	return levels;
+}
+
+/** Label start columns when `marks` use label variant `variant`, or `undefined` if any collide or overflow. */
+function place(marks: readonly Mark[], variant: number, count: number, width: number): Tick[] | undefined {
+	const gap = GAP[Math.min(variant, GAP.length - 1)] ?? 2;
+	const ticks: Tick[] = [];
+	let end = -gap;
+	for (const m of marks) {
+		const label = m.labels[Math.min(variant, m.labels.length - 1)] ?? "";
+		const column = bucketColumn(m.bucket, count, width);
+		if (label.length > width) return undefined;
+		const start = Math.max(0, Math.min(width - label.length, column - Math.floor(label.length / 2)));
+		if (start < end + gap) return undefined;
+		ticks.push({ bucket: m.bucket, column, label, start });
+		end = start + label.length;
+	}
+	return ticks;
+}
+
+/**
+ * Pick the ticks for buckets starting at `starts` (local instants) on a `width`-column plot. Falls
+ * back to the first and last bucket, then the last alone, when no regular set fits.
+ */
+export function chooseTicks(starts: readonly number[], scale: Timescale, width: number): Tick[] {
+	const n = starts.length;
+	if (n === 0 || width <= 0) return [];
+	const levels = scale.kind === "hour" ? hourLevels(starts) : dayLevels(starts, scale.size);
+	const endLabel = (b: number): Mark => ({
+		bucket: b,
+		labels: [scale.kind === "hour" ? hourWide(starts[b] ?? 0) : shortDate(dayKey(starts[b] ?? 0))],
+	});
+	const ends = [[endLabel(0), endLabel(n - 1)], [endLabel(n - 1)]];
+	for (const [i, marks] of [...levels, ...ends].entries()) {
+		const regular = i < levels.length;
+		if (marks.length === 0 || (regular && (marks.length < 2 || marks.length > MAX_TICKS))) continue;
+		if (n === 1 && marks.length > 1) continue;
+		for (let variant = 0; variant < 2; variant++) {
+			const ticks = place(marks, variant, n, width);
+			if (ticks) return ticks;
+		}
+	}
+	return [];
+}
+
+/** A row of `text` pieces at their start columns; callers pass non-overlapping pieces. */
+function row(width: number, pieces: readonly { start: number; text: string }[]): string {
+	const cells = new Array<string>(width).fill(" ");
+	for (const p of pieces)
+		for (let i = 0; i < p.text.length && p.start + i < width; i++) cells[p.start + i] = p.text[i] ?? " ";
+	return cells.join("").trimEnd();
+}
+
+/**
+ * Dates under an hourly axis: one at every bucket that starts a new local day and, room allowing, one
+ * under the first bucket, so a 24h chart reads `Oct 12 ... Oct 13` across its midnight.
+ */
+function dateRow(starts: readonly number[], width: number): string {
+	const n = starts.length;
+	const pieces: { start: number; text: string }[] = [];
+	const free = (start: number, len: number) =>
+		pieces.every((p) => start >= p.start + p.text.length + 2 || start + len + 2 <= p.start);
+	const add = (bucket: number) => {
+		const text = shortDate(dayKey(starts[bucket] ?? 0));
+		const column = bucketColumn(bucket, n, width);
+		const start = Math.max(0, Math.min(width - text.length, column));
+		if (text.length <= width && free(start, text.length)) pieces.push({ start, text });
+	};
+	// Every bucket on a new local day: midnight, or 00:30 in half-hour zones, wherever DST puts it.
+	starts.forEach((ms, bucket) => {
+		if (bucket > 0 && dayKey(ms) !== dayKey(starts[bucket - 1] ?? ms)) add(bucket);
+	});
+	add(0);
+	return row(width, pieces);
+}
+
+/**
+ * The x-axis under a plot: a baseline (`└──┬──┬──`), the tick labels, and for hourly charts the dates.
+ * `gutter` is the plot's left margin (`GUTTER`); lines are plain text, painted by the caller.
+ */
+export function timeAxis(starts: readonly number[], scale: Timescale, width: number, gutter: number): TimeAxis {
+	const ticks = chooseTicks(starts, scale, width);
+	const base = new Array<string>(width).fill("─");
+	for (const t of ticks) base[t.column] = "┬";
+	const margin = " ".repeat(gutter);
+	const lines = [`${" ".repeat(Math.max(0, gutter - 1))}└${base.join("")}`];
+	if (ticks.length > 0)
+		lines.push(
+			margin +
+				row(
+					width,
+					ticks.map((t) => ({ start: t.start, text: t.label })),
+				),
+		);
+	if (scale.kind === "hour") {
+		const dates = dateRow(starts, width);
+		if (dates) lines.push(margin + dates);
+	}
+	return { ticks, lines };
+}