@oh-my-pi/pi-tui 18.4.2 → 18.4.4

package/src/overlays/usage-dashboard.ts

@@ -40,6 +40,10 @@ import {
 import { OverlayPanel, PanelDivider, PanelRows } from "../chrome/overlay-box";
 import { formatKeyHint } from "../app-keybindings";
 import { editorKey, editorKeys } from "../chrome/keybinding-hints";
+import type { TspSpan, TspTableColumn, TspText, TspTone } from "@oh-my-pi/pi-wire";
+import { col, elapsed, node, span, text } from "../native/describe";
+import { type DescribeContext, leafKey, type NativeChild, type NativeNode, type NativeUiEvent } from "../native/node";
+import { actionButton } from "../native/overlay";
 
 /** Local calendar-day activity consumed by the usage heatmap. */
 export interface DailyActivityPoint {
@@ -281,6 +285,8 @@ export interface HeatmapLayout {
 	cells: (number | null)[][];
 	totalCost: number;
 	totalRequests: number;
+	/** Local midnight of the first cell (column 0, Monday). */
+	start: Date;
 }
 
 const MONTH_NAMES = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
@@ -346,9 +352,129 @@ export function buildHeatmapLayout(points: DailyActivityPoint[], weeks: number,
 		cells,
 		totalCost: inRange.reduce((sum, point) => sum + point.cost, 0),
 		totalRequests: inRange.reduce((sum, point) => sum + point.requests, 0),
+		start,
 	};
 }
 
+// =============================================================================
+// Native description helpers
+// =============================================================================
+
+/** Weeks of history the native heatmap carries (a year, GitHub-style). */
+const NATIVE_HEATMAP_WEEKS = 53;
+/** Span tokens for heatmap intensity levels 1..4 (the `table` fallback). */
+const HEAT_LEVEL_TOKENS = ["dim", "accent dim", "accent", "accent strong"];
+/** Heatmap row labels, Monday first like omp's grid: M/W/F only. */
+const HEATMAP_ROW_LABELS = ["M", "", "W", "", "F", "", ""];
+const WEEKDAY_NAMES = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+/** Meter tone of a quota window: ok is the accent fill, pressure warns, exhaustion errors. */
+function statusTone(status: UsageLimit["status"]): TspTone {
+	if (status === "exhausted") return "error";
+	if (status === "warning") return "warning";
+	if (status === "ok") return "accent";
+	return "muted";
+}
+
+/** Status dot of a provider frame, toned by the card's aggregate status. */
+function statusDot(status: UsageLimit["status"]): NativeNode {
+	const token =
+		status === "exhausted" ? "error" : status === "warning" ? "warning" : status === "ok" ? "success" : "dim";
+	const label =
+		status === "exhausted"
+			? "Exhausted"
+			: status === "warning"
+				? "Under pressure"
+				: status === "ok"
+					? "OK"
+					: "Unknown";
+	return text([span("●", token)], { title: label, aria: label });
+}
+
+/**
+ * Used-fraction bar of a quota window, toned by status: a `meter` where the
+ * terminal draws one, else a `progress` bar.
+ */
+function usageMeter(fraction: number, status: UsageLimit["status"], meter: boolean): NativeNode {
+	const value = Math.min(Math.max(fraction, 0), 1);
+	const tone = statusTone(status);
+	return meter ? node("meter", { value, style: "bar", size: "md", tone }) : node("progress", { value, tone, grow: 1 });
+}
+
+/** `62% left` for a used fraction (overage reads as 0%). */
+function leftText(fraction: number): string {
+	return `${Math.max(0, Math.round((1 - fraction) * 100))}% left`;
+}
+
+/** `Mon 28 Sep` for a local date. */
+function shortDate(date: Date): string {
+	return `${WEEKDAY_NAMES[date.getDay()]} ${date.getDate()} ${MONTH_NAMES[date.getMonth()]}`;
+}
+
+/** `18:00` for a local time. */
+function clockTime(date: Date): string {
+	return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}
+
+/**
+ * When a window resets, relative to `nowMs`: `resets 18:00` today, `resets
+ * Tue 18:00` within the week, `resets 3 Oct` beyond; the title carries the
+ * absolute date and the countdown.
+ */
+function resetLabel(nowMs: number, resetMs: number): { text: string; title: string } {
+	const at = new Date(nowMs + resetMs);
+	const now = new Date(nowMs);
+	const sameDay = at.toDateString() === now.toDateString();
+	const text = sameDay
+		? `resets ${clockTime(at)}`
+		: resetMs < 6 * 86_400_000
+			? `resets ${WEEKDAY_NAMES[at.getDay()]} ${clockTime(at)}`
+			: `resets ${at.getDate()} ${MONTH_NAMES[at.getMonth()]}`;
+	return {
+		text,
+		title: `Resets ${shortDate(at)} ${at.getFullYear()}, ${clockTime(at)} (in ${formatDuration(resetMs)})`,
+	};
+}
+
+function mutedText(content: string, wrap = false): NativeNode {
+	return text([span(content, "muted")], wrap ? { wrap: "word" } : { truncate: "end" });
+}
+
+/** Stable, human account name for a report in the detail view. */
+function reportAccountLabel(report: UsageReport, limit: UsageLimit | undefined, index: number): string {
+	const metadata = report.metadata;
+	const pick = (value: unknown): string | undefined => (typeof value === "string" && value ? value : undefined);
+	const identity =
+		pick(metadata?.email) ??
+		pick(metadata?.accountId) ??
+		pick(metadata?.projectId) ??
+		pick(limit?.scope.projectId) ??
+		`account ${index + 1}`;
+	const org = pick(metadata?.orgName);
+	return sanitizeDisplayLine(org && org !== identity ? `${identity} (${org})` : identity);
+}
+
+/** Window qualifier worth showing after a limit title (none when the title already names it). */
+function detailWindowLabel(label: string, limit: UsageLimit): string | undefined {
+	const windowLabel = limit.window?.label ?? limit.window?.id ?? limit.scope.windowId;
+	if (!windowLabel) return undefined;
+	const normalized = windowLabel.toLowerCase();
+	if (normalized === "quota window" || label.toLowerCase().includes(normalized)) return undefined;
+	return sanitizeDisplayLine(windowLabel);
+}
+
+/** `$1,234 · 5.6K requests` totals for the activity summary. */
+function formatActivityTotals(layout: HeatmapLayout): string {
+	const cost =
+		layout.totalCost >= 1
+			? `$${new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 }).format(layout.totalCost)}`
+			: `$${layout.totalCost.toFixed(2)}`;
+	const requests = new Intl.NumberFormat("en-US", { notation: "compact", maximumFractionDigits: 1 }).format(
+		layout.totalRequests,
+	);
+	return `${cost} · ${requests} requests`;
+}
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -358,10 +484,10 @@ export interface UsageDashboardOptions {
 	reports: UsageReport[];
 	unavailableAccounts?: readonly UnavailableUsageAccount[];
 	/**
-	 * Full classic `/usage` report for the expanded detail view; re-invoked per
-	 * terminal width.
+	 * Full classic `/usage` report of `reports` (the latest refresh) for the
+	 * expanded detail view; re-invoked per terminal width.
 	 */
-	renderDetail: (width: number) => string;
+	renderDetail: (width: number, reports: UsageReport[]) => string;
 	/**
 	 * Stream daily activity into the heatmap: push cached DB rows immediately,
 	 * then push again after an incremental session sync. Resolves when the sync
@@ -369,6 +495,8 @@ export interface UsageDashboardOptions {
 	 * the dashboard closes so an in-flight sync can stop early.
 	 */
 	loadActivity: (push: (points: DailyActivityPoint[]) => void, signal: AbortSignal) => Promise<void>;
+	/** Re-fetch the usage reports (`r`); omitted when the host can't. Resolves null when nothing came back. */
+	refresh?: () => Promise<UsageReport[] | null>;
 	requestRender: () => void;
 	onClose: () => void;
 }
@@ -403,9 +531,16 @@ interface CardRowLayout {
 }
 
 export class UsageDashboardComponent implements Component {
+	/** The terminal draws the sheet: a large glass overlay titled Usage. */
+	readonly nativeOverlay = { role: "omp.overlay.usage", size: "lg", anchor: "center", head: "Usage" } as const;
 	#options: UsageDashboardOptions;
+	#reports: UsageReport[];
 	#cards: ProviderCard[];
 	#nowMs: number;
+	#refreshing = false;
+	#refreshError: string | null = null;
+	/** Bumped whenever anything the native description shows changes. */
+	#revision = 0;
 	#view: "overview" | "detail" = "overview";
 	#scroll = 0;
 	#activity: DailyActivityPoint[] | null = null;
@@ -419,12 +554,14 @@ export class UsageDashboardComponent implements Component {
 	readonly #body: PanelRows;
 	readonly #footer: PanelRows;
 	readonly #closeController = new AbortController();
+	#nativeCache: { revision: number; meter: boolean; chart: boolean; node: NativeNode } | undefined;
 
 	constructor(options: UsageDashboardOptions) {
 		ensureThemeSync();
 		this.#options = options;
+		this.#reports = options.reports;
 		this.#nowMs = Date.now();
-		this.#cards = buildProviderCards(options.reports, this.#nowMs, options.unavailableAccounts);
+		this.#cards = buildProviderCards(this.#reports, this.#nowMs, options.unavailableAccounts);
 		this.#panel = new OverlayPanel("Usage");
 		this.#header = new PanelRows();
 		this.#header.setHeight(1);
@@ -443,13 +580,13 @@ export class UsageDashboardComponent implements Component {
 			await this.#options.loadActivity(points => {
 				if (this.#closed) return;
 				this.#activity = points;
-				this.#options.requestRender();
+				this.#changed();
 			}, this.#closeController.signal);
 		} catch (error) {
 			this.#activityError = error instanceof Error ? error.message : String(error);
 		} finally {
 			this.#syncing = false;
-			if (!this.#closed) this.#options.requestRender();
+			if (!this.#closed) this.#changed();
 		}
 	}
 
@@ -748,7 +885,10 @@ export class UsageDashboardComponent implements Component {
 
 	#detailLines(innerWidth: number): string[] {
 		if (this.#detailCache?.width !== innerWidth) {
-			this.#detailCache = { width: innerWidth, lines: this.#options.renderDetail(innerWidth).split("\n") };
+			this.#detailCache = {
+				width: innerWidth,
+				lines: this.#options.renderDetail(innerWidth, this.#reports).split("\n"),
+			};
 		}
 		return this.#detailCache.lines;
 	}
@@ -764,16 +904,21 @@ export class UsageDashboardComponent implements Component {
 		const maxScroll = Math.max(0, contentSource.length - contentRows);
 		if (this.#scroll > maxScroll) this.#scroll = maxScroll;
 
-		const latestFetchedAt = Math.max(0, ...this.#options.reports.map(report => report.fetchedAt ?? 0));
-		const checkedText = latestFetchedAt ? `checked ${formatDuration(this.#nowMs - latestFetchedAt)} ago` : "";
+		const latestFetchedAt = Math.max(0, ...this.#reports.map(report => report.fetchedAt ?? 0));
+		const checkedText = this.#refreshing
+			? "refreshing…"
+			: latestFetchedAt
+				? `checked ${formatDuration(this.#nowMs - latestFetchedAt)} ago`
+				: "";
 		const title = this.#view === "detail" ? "Usage · Details" : "Usage";
 
 		const scrollHint = maxScroll > 0 ? `${editorKeys("tui.select.up", "tui.select.down")} scroll · ` : "";
 		const cancel = editorKey("tui.select.cancel");
+		const refreshHint = this.#options.refresh ? "r refresh · " : "";
 		const hint =
 			this.#view === "detail"
-				? `${scrollHint}${cancel} back`
-				: `${scrollHint}${formatKeyHint("enter")} details · ${cancel} close`;
+				? `${scrollHint}${refreshHint}${cancel} back`
+				: `${scrollHint}${refreshHint}${formatKeyHint("enter")} details · ${cancel} close`;
 		this.#panel.title = title;
 		this.#header.setLines([checkedText ? theme.fg("dim", checkedText) : ""]);
 		this.#body.setLines(contentSource.slice(this.#scroll, this.#scroll + contentRows));
@@ -782,6 +927,432 @@ export class UsageDashboardComponent implements Component {
 		return this.#panel.render(width);
 	}
 
+	// ---------------------------------------------------------------------------
+	// Native description
+	// ---------------------------------------------------------------------------
+
+	/**
+	 * The sheet body (the terminal's `lg` overlay is the frame): a head row
+	 * (checked ago, Overview/Details tabs, Refresh), then either the provider
+	 * grid of frames with window meters and the activity heatmap, or the
+	 * per-provider detail tables. `meter`/`chart` fall back to
+	 * `progress`/`table` on terminals without them. Rebuilt only when its
+	 * inputs change.
+	 */
+	describe(cx: DescribeContext): NativeNode {
+		const meter = cx.supports("meter");
+		const chart = cx.supports("chart");
+		const cache = this.#nativeCache;
+		if (cache && cache.revision === this.#revision && cache.meter === meter && cache.chart === chart) {
+			return cache.node;
+		}
+		const body = this.#view === "detail" ? this.#describeDetail() : this.#describeOverview(meter, chart);
+		const root = col([this.#describeHead(), node("col", { gap: "lg" }, body, this.#view)], { gap: "lg" });
+		this.#nativeCache = { revision: this.#revision, meter, chart, node: root };
+		return root;
+	}
+
+	/** Tab clicks switch views like Enter/Esc; the Refresh button runs `r`. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action") {
+			if (event.act === "refresh") void this.#refresh();
+			return;
+		}
+		if (event.type !== "select" && event.type !== "activate") return;
+		if (leafKey(event.key) !== "tabs") return;
+		if ((event.item === "overview" || event.item === "detail") && event.item !== this.#view) {
+			this.#setView(event.item);
+		}
+	}
+
+	#describeHead(): NativeNode {
+		const checked: NativeChild[] = [];
+		const latestFetchedAt = Math.max(0, ...this.#reports.map(report => report.fetchedAt ?? 0));
+		if (this.#refreshing) {
+			checked.push(node("spinner", { label: [span("Refreshing…", "dim")] }));
+		} else if (this.#refreshError) {
+			checked.push(
+				text([span(`Refresh failed: ${sanitizeDisplayLine(this.#refreshError)}`, "warning")], {
+					truncate: "end",
+				}),
+			);
+		} else if (latestFetchedAt) {
+			checked.push(
+				text([span("checked", "dim")]),
+				elapsed(Date.now() - latestFetchedAt),
+				text([span("ago", "dim")]),
+			);
+		}
+		const children: NativeChild[] = [
+			node("row", { gap: "xs", align: "baseline", shrink: 1 }, checked, "checked"),
+			node("spacer", { grow: 1 }),
+			node(
+				"tabs",
+				{
+					items: [
+						{ id: "overview", label: "Overview" },
+						{ id: "detail", label: "Details" },
+					],
+					active: this.#view,
+				},
+				undefined,
+				"tabs",
+			),
+		];
+		if (this.#options.refresh) children.push(actionButton("Refresh", "refresh", { keys: "r" }));
+		return node("row", { role: "omp.usage.head", gap: "sm", align: "center" }, children, "head");
+	}
+
+	#describeOverview(meter: boolean, chart: boolean): NativeChild[] {
+		const children: NativeChild[] = [];
+		if (this.#cards.length === 0) {
+			children.push(
+				node("text", { spans: [span("No usage data available.")], role: "omp.usage.untouched" }, undefined, "none"),
+			);
+		} else {
+			// Unlimited providers keep a frame reading "No limits"; only untouched ones collapse.
+			const active = this.#cards.filter(entry => !entry.idle || entry.unlimited);
+			const idle = this.#cards.filter(entry => entry.idle && !entry.unlimited);
+			if (active.length > 0) {
+				children.push(
+					node(
+						"row",
+						{ wrap: true, gap: "md", role: "omp.usage.grid" },
+						active.map(entry => this.#describeCard(entry, meter)),
+						"providers",
+					),
+				);
+			}
+			if (idle.length > 0) {
+				children.push(
+					node(
+						"text",
+						{
+							spans: [span(`Untouched: ${idle.map(entry => entry.name).join(", ")}`)],
+							wrap: "word",
+							role: "omp.usage.untouched",
+						},
+						undefined,
+						"idle",
+					),
+				);
+			}
+		}
+		children.push(this.#describeActivity(chart));
+		return children;
+	}
+
+	#describeCard(entry: ProviderCard, meter: boolean): NativeNode {
+		const cardStatus =
+			entry.unavailableAccounts.length > 0
+				? statusWithUnavailableAccounts(entry.windows)
+				: entry.unlimited
+					? "ok"
+					: aggregateStatus(entry.windows);
+		const head: NativeChild[] = [text([span(entry.name, "strong")], { truncate: "end" })];
+		if (entry.accounts > 1) head.push(text([span(`${entry.accounts} accounts`, "muted")]));
+		head.push(node("spacer", { grow: 1 }), statusDot(cardStatus));
+		const children: NativeChild[] = [
+			node("row", { role: "omp.usage.provider.head", gap: "sm", align: "center" }, head, "title"),
+		];
+		for (const account of entry.daybreakAccounts ?? []) {
+			children.push(text([span(`Daybreak · ${sanitizeDisplayLine(account)}`, "success")], { truncate: "end" }));
+		}
+		if (entry.resetCredits) {
+			const resets = entry.resetCredits;
+			const details: string[] = [];
+			if (resets.redeemableCount !== resets.bankedCount) details.push(`${resets.redeemableCount} usable now`);
+			if (resets.soonestExpiryMs !== undefined) {
+				details.push(
+					resets.soonestExpiryMs > 0 ? `expires in ${formatDuration(resets.soonestExpiryMs)}` : "expired",
+				);
+			}
+			if (resets.redeemableCount === 0 && resets.unavailableReasons.length > 0) {
+				details.push(`unavailable: ${sanitizeDisplayLine(resets.unavailableReasons.join(" • "))}`);
+			}
+			const label = `${resets.bankedCount} reset${resets.bankedCount === 1 ? "" : "s"} banked`;
+			children.push(
+				node(
+					"row",
+					{ gap: "sm", align: "center" },
+					[
+						node("badge", {
+							text: label,
+							tone: resets.redeemableCount > 0 ? "success" : "warning",
+							title: details.length > 0 ? `${label} · ${details.join(" · ")}` : label,
+						}),
+					],
+					"resets",
+				),
+			);
+		}
+		for (const account of entry.unavailableAccounts) {
+			children.push(mutedText(`${sanitizeDisplayLine(account)}: usage unavailable`, true));
+		}
+		if (entry.unlimited) {
+			children.push(mutedText("No limits"));
+		} else {
+			for (const [index, window] of entry.windows.slice(0, CARD_MAX_WINDOWS).entries()) {
+				const label: TspSpan[] = [span(sanitizeDisplayLine(window.label))];
+				if (window.windowTag) label.push(span(` ${sanitizeDisplayLine(window.windowTag)}`, "dim"));
+				const cells: NativeChild[] = [
+					text(label, { role: "omp.usage.label", truncate: "middle", title: sanitizeDisplayLine(window.label) }),
+				];
+				if (window.fraction === undefined) {
+					cells.push(text([span(window.usedText ?? "No data", "muted")], { truncate: "end" }));
+				} else {
+					const token =
+						window.status === "exhausted" ? "error" : window.status === "warning" ? "warning" : undefined;
+					cells.push(
+						usageMeter(window.fraction, window.status, meter),
+						text([span(leftText(window.fraction), token)], { role: "omp.usage.pct" }),
+					);
+					if (window.resetMs !== undefined) {
+						const reset = resetLabel(this.#nowMs, window.resetMs);
+						cells.push(text([span(reset.text, "dim")], { role: "omp.usage.reset", title: reset.title }));
+					}
+				}
+				children.push(node("row", { role: "omp.usage.window", gap: "sm", align: "center" }, cells, `w${index}`));
+			}
+			const hidden = entry.windows.length - CARD_MAX_WINDOWS;
+			if (hidden > 0) children.push(mutedText(`+${hidden} more`));
+		}
+		return node(
+			"card",
+			{ role: "omp.usage.provider", grow: 1, min: { w: `${CARD_MIN_WIDTH}ch` } },
+			children,
+			entry.provider,
+		);
+	}
+
+	#describeActivity(chart: boolean): NativeNode {
+		const head: NativeChild[] = [text([span("Activity", "strong")])];
+		if (this.#syncing && this.#activity) head.push(node("spinner", { label: [span("Syncing", "dim")] }));
+		const children: NativeChild[] = [node("row", { gap: "sm", align: "center" }, head, "head")];
+		const points = this.#activity;
+		if (this.#activityError) {
+			const detail = formatActivityErrorDetail(this.#activityError);
+			children.push(
+				mutedText(detail ? `Usage history unavailable (${detail}).` : "Usage history unavailable.", true),
+			);
+		} else if (!points) {
+			children.push(node("spinner", { label: [span("Loading usage history…", "muted")] }));
+		} else {
+			const layout = buildHeatmapLayout(points, NATIVE_HEATMAP_WEEKS);
+			const summary =
+				layout.totalRequests > 0 || layout.totalCost > 0
+					? `${formatActivityTotals(layout)} · last ${NATIVE_HEATMAP_WEEKS} weeks`
+					: `No activity in the last ${NATIVE_HEATMAP_WEEKS} weeks`;
+			children.push(chart ? this.#heatmapChart(layout, points, summary) : this.#heatmapTable(layout, summary));
+		}
+		return node("col", { role: "omp.usage.activity", gap: "sm" }, children, "activity");
+	}
+
+	/** The heatmap as a `chart`: 0–1 intensities, month columns, M/W/F rows, per-day tooltips. */
+	#heatmapChart(layout: HeatmapLayout, points: readonly DailyActivityPoint[], summary: string): NativeNode {
+		const byDay = new Map(points.map(point => [point.day, point]));
+		const cells = layout.cells.map(days => days.map(level => (level === null ? null : level / 4)));
+		const tips = layout.cells.map((days, day) =>
+			days.map((level, week) => {
+				if (level === null) return null;
+				const date = addDays(layout.start, week * 7 + day);
+				const point = byDay.get(localIso(date));
+				if (!point || (point.cost <= 0 && point.requests <= 0)) return `${shortDate(date)} · No activity`;
+				const requests = `${point.requests} request${point.requests === 1 ? "" : "s"}`;
+				const cost = point.cost >= 100 ? `$${Math.round(point.cost)}` : `$${point.cost.toFixed(2)}`;
+				return `${shortDate(date)} · ${cost} · ${requests}`;
+			}),
+		);
+		// A month label needs room: drop one whose successor starts within two columns (GitHub's rule).
+		const starts = layout.monthLabels.flatMap((label, at) => (label ? [{ at, label }] : []));
+		const cols = starts.filter((entry, index) => {
+			const next = starts[index + 1];
+			return !next || next.at - entry.at > 2;
+		});
+		return node(
+			"chart",
+			{ kind: "heatmap", cells, cols, rows: HEATMAP_ROW_LABELS, tips, token: "accent", summary, size: "md" },
+			undefined,
+			"heatmap",
+		);
+	}
+
+	/** The heatmap as a `table` of glyph cells, for terminals without `chart`. */
+	#heatmapTable(layout: HeatmapLayout, summary: string): NativeNode {
+		const cols: TspTableColumn[] = [{ id: "day", priority: NATIVE_HEATMAP_WEEKS }];
+		for (let week = 0; week < NATIVE_HEATMAP_WEEKS; week++) {
+			cols.push({ id: `w${week}`, align: "center", priority: week });
+		}
+		const rows = HEATMAP_DAY_LABELS.map((label, day) => {
+			const cells: Record<string, TspText> = { day: [span(label, "dim")] };
+			for (let week = 0; week < NATIVE_HEATMAP_WEEKS; week++) {
+				const level = layout.cells[day][week];
+				if (level === null) continue;
+				cells[`w${week}`] = level === 0 ? [span("·", "dim")] : [span("■", HEAT_LEVEL_TOKENS[level - 1])];
+			}
+			return { id: `d${day}`, cells };
+		});
+		return node(
+			"col",
+			{ gap: "sm" },
+			[mutedText(summary), node("table", { cols, rows }, undefined, "table")],
+			"heatmap",
+		);
+	}
+
+	/** Per provider: notes and saved resets as a `kv`, the limit buckets as a `table` (one row per account). */
+	#describeDetail(): NativeChild[] {
+		const nowMs = this.#nowMs;
+		const grouped = new Map<string, UsageReport[]>();
+		for (const report of collapseSharedUsageReports(this.#reports)) {
+			const list = grouped.get(report.provider) ?? [];
+			list.push(report);
+			grouped.set(report.provider, list);
+		}
+		const unavailable = this.#options.unavailableAccounts ?? [];
+		const sections: NativeChild[] = [];
+		for (const entry of this.#cards) {
+			const reports = grouped.get(entry.provider) ?? [];
+			const children: NativeChild[] = [];
+			for (const account of unavailable) {
+				if (account.provider !== entry.provider) continue;
+				children.push(mutedText(`${sanitizeDisplayLine(account.label)}: usage unavailable`, true));
+			}
+
+			const facts: { k: TspText; v: TspText }[] = [];
+			const notes = [...new Set(reports.flatMap(report => report.notes ?? []))];
+			if (notes.length > 0) facts.push({ k: [span("Notes", "muted")], v: sanitizeDisplayLine(notes.join(" • ")) });
+			for (const [index, report] of reports.entries()) {
+				const resets = summarizeUsageResetCredits(report.resetCredits, nowMs);
+				if (!resets || resets.bankedCount <= 0) continue;
+				const value: TspSpan[] = [
+					span(
+						`${resets.bankedCount} saved reset${resets.bankedCount === 1 ? "" : "s"}`,
+						resets.redeemableCount > 0 ? "success" : "warning",
+					),
+				];
+				if (resets.redeemableCount !== resets.bankedCount) {
+					value.push(span(` · ${resets.redeemableCount} usable now`, "muted"));
+				}
+				if (resets.soonestExpiry) {
+					const remaining = Date.parse(resets.soonestExpiry) - nowMs;
+					const date = resets.soonestExpiry.slice(0, 10);
+					value.push(
+						span(
+							remaining > 0 ? ` · expires in ${formatDuration(remaining)} (${date})` : ` · expired (${date})`,
+							"muted",
+						),
+					);
+				}
+				if (resets.redeemableCount === 0 && resets.unavailableReason) {
+					value.push(span(` · unavailable: ${sanitizeDisplayLine(resets.unavailableReason)}`, "muted"));
+				}
+				facts.push({
+					k: [span(`Resets · ${reportAccountLabel(report, report.limits[0], index)}`, "muted")],
+					v: value,
+				});
+			}
+			if (facts.length > 0) children.push(node("kv", { items: facts, layout: "grid" }, undefined, "facts"));
+
+			const buckets = new Map<string, { label: string; window?: string; rows: Record<string, TspText>[] }>();
+			const limitNotes: string[] = [];
+			for (const [index, report] of reports.entries()) {
+				for (const limit of report.limits) {
+					const label = sanitizeDisplayLine(formatLimitTitle(limit));
+					const key = `${label}|${limit.window?.id ?? limit.scope.windowId ?? "default"}`;
+					let bucket = buckets.get(key);
+					if (!bucket) {
+						bucket = { label, window: detailWindowLabel(label, limit), rows: [] };
+						buckets.set(key, bucket);
+					}
+					const fraction = resolveUsedFraction(limit);
+					const token =
+						limit.status === "exhausted" ? "error" : limit.status === "warning" ? "warning" : undefined;
+					const resetsAt = limit.window?.resetsAt;
+					bucket.rows.push({
+						account: [span(reportAccountLabel(report, limit, index), "muted")],
+						left:
+							fraction === undefined
+								? [span(formatAbsoluteOnlyAmount([limit]) ?? "No data", "muted")]
+								: [span(leftText(fraction), token)],
+						reset:
+							resetsAt !== undefined && resetsAt > nowMs
+								? [
+										span(
+											`${limit.window?.resetLabel ?? "resets"} in ${formatDuration(resetsAt - nowMs)}`,
+											"dim",
+										),
+									]
+								: "",
+					});
+					for (const note of limit.notes ?? []) limitNotes.push(sanitizeDisplayLine(note));
+				}
+			}
+			if (buckets.size > 0) {
+				const rows: { id: string; cells: Record<string, TspText> }[] = [];
+				for (const bucket of buckets.values()) {
+					for (const [index, cells] of bucket.rows.entries()) {
+						const limitCell: TspSpan[] =
+							index === 0
+								? [span(bucket.label), ...(bucket.window ? [span(` ${bucket.window}`, "dim")] : [])]
+								: [];
+						rows.push({ id: `r${rows.length}`, cells: { limit: limitCell, ...cells } });
+					}
+				}
+				const cols: TspTableColumn[] = [
+					{ id: "limit", head: "Limit", grow: 1, priority: 4 },
+					{ id: "account", head: "Account", truncate: "middle", priority: 1 },
+					{ id: "left", head: "Left", align: "end", priority: 3 },
+					{ id: "reset", head: "Resets", align: "end", priority: 2 },
+				];
+				children.push(node("table", { cols, rows }, undefined, "limits"));
+				for (const note of new Set(limitNotes)) children.push(mutedText(note, true));
+			} else if (unavailable.every(account => account.provider !== entry.provider)) {
+				children.push(mutedText("No limits"));
+			}
+			sections.push(
+				node(
+					"section",
+					{ head: [span(entry.name, "strong")], role: "omp.usage.report" },
+					[col(children, { gap: "sm" })],
+					entry.provider,
+				),
+			);
+		}
+		if (sections.length === 0) sections.push(mutedText("No usage data available."));
+		return sections;
+	}
+
+	/** Re-fetch the reports (`r` / Refresh); the last reports stay on failure, with the error in the head. */
+	async #refresh(): Promise<void> {
+		const refresh = this.#options.refresh;
+		if (!refresh || this.#refreshing || this.#closed) return;
+		this.#refreshing = true;
+		this.#refreshError = null;
+		this.#changed();
+		try {
+			const reports = await refresh();
+			if (this.#closed) return;
+			if (reports) {
+				this.#reports = reports;
+				this.#nowMs = Date.now();
+				this.#cards = buildProviderCards(reports, this.#nowMs, this.#options.unavailableAccounts);
+				this.#detailCache = null;
+			}
+		} catch (error) {
+			this.#refreshError = error instanceof Error ? error.message : String(error);
+		} finally {
+			this.#refreshing = false;
+			if (!this.#closed) this.#changed();
+		}
+	}
+
+	/** Invalidate the native description and repaint. */
+	#changed(): void {
+		this.#revision++;
+		this.#options.requestRender();
+	}
+
 	#scrollBy(delta: number): void {
 		this.#scroll = Math.max(0, this.#scroll + delta);
 		this.#options.requestRender();
@@ -790,7 +1361,7 @@ export class UsageDashboardComponent implements Component {
 	#setView(view: "overview" | "detail"): void {
 		this.#view = view;
 		this.#scroll = 0;
-		this.#options.requestRender();
+		this.#changed();
 	}
 
 	handleInput(data: string): void {
@@ -812,6 +1383,10 @@ export class UsageDashboardComponent implements Component {
 			this.#options.onClose();
 			return;
 		}
+		if (matchesKey(data, "r")) {
+			void this.#refresh();
+			return;
+		}
 		if (
 			this.#view === "overview" &&
 			(matchesKey(data, "return") || matchesKey(data, "tab") || matchesKey(data, "d"))