routstrd 0.4.9 → 0.4.11

package/src/tui/usage/data.ts

@@ -1,5 +1,6 @@
 import type { UsageTrackingEntry } from "../../daemon/types.ts";
 import {
+  callAuth,
   callDaemon,
   getDaemonBaseUrl,
   isDaemonRunning,
@@ -145,3 +146,112 @@ export async function fetchClients(): Promise<ClientInfo[]> {
 export function hasAnyNpubs(clients: ClientInfo[]): boolean {
   return clients.some((c) => !!c.ownerNpub);
 }
+
+/** A configured npub as returned by the auth proxy (`/npubs`). */
+export interface NpubEntry {
+  npub: string;
+  name: string | null;
+  role: string;
+}
+
+/**
+ * Fetch the configured npubs (with their display names and roles) from the
+ * auth proxy. Returns an empty list when the endpoint is unavailable — e.g. a
+ * local daemon that doesn't route `/npubs` — so the TUI degrades gracefully.
+ */
+export async function fetchNpubs(): Promise<NpubEntry[]> {
+  try {
+    const result = await callAuth("/npubs");
+    if (result.error) return [];
+
+    // Handle both wrapped { output: { npubs } } and direct { npubs } responses.
+    const direct = (result as { npubs?: NpubEntry[] }).npubs;
+    const wrapped = (result.output as { npubs?: NpubEntry[] } | undefined)?.npubs;
+    return direct ?? wrapped ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/** Number of trailing npub characters the auth proxy folds into a client id. */
+export const NPUB_SUFFIX_LENGTH = 7;
+
+/**
+ * Lookup tables for turning a raw usage `client` id (e.g.
+ * `claude-code-a1b2c3d`) back into a human label (e.g. `Alice (claude-code)`).
+ *
+ * All maps are empty in local mode, so {@link resolveClientLabel} falls back to
+ * the raw id with no behaviour change there.
+ */
+export interface ClientNaming {
+  /** Configured npubs (names + roles) from the auth proxy. */
+  npubs: NpubEntry[];
+  /** bare clientId -> owner npub, from `GET /clients`. */
+  ownersByClientId: Map<string, string>;
+  /** npub -> display name (null when unset). */
+  npubNames: Map<string, string | null>;
+  /** trailing npub suffix -> npub. */
+  npubsBySuffix: Map<string, string>;
+}
+
+export function buildClientNaming(clients: ClientInfo[], npubs: NpubEntry[]): ClientNaming {
+  const ownersByClientId = new Map<string, string>();
+  for (const c of clients) {
+    if (c.ownerNpub) ownersByClientId.set(c.clientId, c.ownerNpub);
+  }
+
+  const npubNames = new Map<string, string | null>();
+  const npubsBySuffix = new Map<string, string>();
+  const remember = (npub: string) => npubsBySuffix.set(npub.slice(-NPUB_SUFFIX_LENGTH), npub);
+
+  for (const n of npubs) {
+    npubNames.set(n.npub, n.name ?? null);
+    remember(n.npub);
+  }
+  // `GET /clients` also carries owner npubs, which covers entries whose owner
+  // isn't present in the (possibly filtered) `/npubs` response.
+  for (const owner of ownersByClientId.values()) remember(owner);
+
+  return { npubs, ownersByClientId, npubNames, npubsBySuffix };
+}
+
+/** Configured display name for an npub, or null when unset/blank. */
+function npubDisplayName(naming: ClientNaming, npub: string): string | null {
+  const name = naming.npubNames.get(npub)?.trim();
+  return name && name.length > 0 ? name : null;
+}
+
+/** `Alice (claude-code)` when the owner has a name, else the bare client id. */
+function formatClientLabel(naming: ClientNaming, bareId: string, ownerNpub: string): string {
+  const name = npubDisplayName(naming, ownerNpub);
+  return name ? `${name} (${bareId})` : bareId;
+}
+
+/**
+ * Render a usage entry's `client` value as `Name (client-id)`, where `Name` is
+ * the owner npub's display name and the `-<npub tail>` suffix is stripped.
+ * Falls back to the raw id when no owner/name can be resolved (local mode).
+ */
+export function resolveClientLabel(clientId: string | undefined, naming: ClientNaming): string {
+  const raw = clientId && clientId.length > 0 ? clientId : "unknown";
+
+  // Exact match: the raw id is a known bare clientId or its suffixed form.
+  for (const [bareId, ownerNpub] of naming.ownersByClientId) {
+    const suffixed = `${bareId}-${ownerNpub.slice(-NPUB_SUFFIX_LENGTH)}`;
+    if (raw !== bareId && raw !== suffixed) continue;
+    return formatClientLabel(naming, bareId, ownerNpub);
+  }
+
+  // Fallback: strip a trailing `-<npub tail>` that matches a known npub.
+  for (const [suffix, npub] of naming.npubsBySuffix) {
+    const marker = `-${suffix}`;
+    if (raw.length <= marker.length || !raw.endsWith(marker)) continue;
+    return formatClientLabel(naming, raw.slice(0, -marker.length), npub);
+  }
+
+  return raw;
+}
+
+export function emptyClientNaming(): ClientNaming {
+  return buildClientNaming([], []);
+}

package/src/tui/usage/render.ts

@@ -3,7 +3,8 @@ import type { Tab } from "./types.ts";
 import {
   formatNumber,
   formatTime,
-  type ClientInfo,
+  resolveClientLabel,
+  type ClientNaming,
 } from "./data.ts";
 import { vimState } from "./state.ts";
 import { stripAnsi } from "./terminal.ts";
@@ -503,20 +504,23 @@ export function renderClients(stats: UsageStats, width: number): string {
   return output;
 }
 
-export function renderNpubs(stats: UsageStats, clients: ClientInfo[], width: number): string {
+export function renderNpubs(stats: UsageStats, naming: ClientNaming, width: number): string {
   const npubStats = stats.summary.npubs;
   if (npubStats.length === 0) return renderBox(["No npub data available"], width, "Npub Breakdown");
 
+  // Index configured npubs by their npub so usage rows can show names/roles.
+  const configured = new Map(naming.npubs.map((entry) => [entry.npub, entry]));
+
   const totalCost = stats.totalSatsCost;
   const maxCost = npubStats[0]!.satsCost;
   const lines: string[] = [];
 
-  const col1 = 24; // Npub (truncated)
+  const col1 = 24; // Name (or truncated npub)
   const col2 = 12; // Requests
   const col3 = 24; // Cost
   const col4 = 12; // Tokens
 
-  const hNpub = "Npub".padEnd(col1);
+  const hNpub = "Name".padEnd(col1);
   const hReqs = "Requests".padEnd(col2);
   const hCost = "Cost".padEnd(col3);
   const hTok = "Tokens".padEnd(col4);
@@ -527,9 +531,11 @@ export function renderNpubs(stats: UsageStats, clients: ClientInfo[], width: num
   for (const npub of npubStats) {
     const pct = totalCost > 0 ? ((npub.satsCost / totalCost) * 100).toFixed(1) : "0.0";
     const avgCostFormatted = formatCost(npub.requests > 0 ? npub.satsCost / npub.requests : 0);
-    const shortNpub = truncateNpub(npub.npub);
+    const entry = configured.get(npub.npub);
+    const name = entry?.name?.trim();
+    const label = name || truncateNpub(npub.npub);
 
-    const dNpub = shortNpub.padEnd(col1);
+    const dNpub = label.slice(0, col1 - 1).padEnd(col1);
     const dReqs = formatReqs(npub.requests).padEnd(col2);
     const dCost = `${formatCost(npub.satsCost)} sats (${pct}%)`.padEnd(col3);
     const dTok = formatNumber(npub.totalTokens).padEnd(col4);
@@ -541,8 +547,9 @@ export function renderNpubs(stats: UsageStats, clients: ClientInfo[], width: num
       `${COLORS.green}${dCost}${COLORS.reset}` +
       `${COLORS.dim}${dTok}${dAvg}${COLORS.reset}`
     );
-    // Full npub on its own line for copy-ability
-    lines.push(`  ${COLORS.dim}${npub.npub}${COLORS.reset}`);
+    // Full npub (and role when known) on its own line for copy-ability.
+    const roleSuffix = entry?.role ? ` [${entry.role}]` : "";
+    lines.push(`  ${COLORS.dim}${npub.npub}${roleSuffix}${COLORS.reset}`);
     lines.push(`  ${renderBarChart("", npub.satsCost, maxCost, width - 6, COLORS.magenta, Number(pct), "npub-detail")}`);
     lines.push("");
   }
@@ -555,7 +562,9 @@ export function renderNpubs(stats: UsageStats, clients: ClientInfo[], width: num
     // Use pre-aggregated topModels from summary
     for (const topNpub of stats.summary.npubs.slice(0, 5)) {
       if (topNpub.topModels.length === 0) continue;
-      npubModelLines.push(`${COLORS.bold}${truncateNpub(topNpub.npub)}${COLORS.reset} (${formatReqs(topNpub.requests)} reqs, ${formatCost(topNpub.satsCost)} sats)`);
+      const name = configured.get(topNpub.npub)?.name?.trim();
+      const label = name || truncateNpub(topNpub.npub);
+      npubModelLines.push(`${COLORS.bold}${label}${COLORS.reset} (${formatReqs(topNpub.requests)} reqs, ${formatCost(topNpub.satsCost)} sats)`);
       for (const m of topNpub.topModels) {
         npubModelLines.push(`  ${(MODEL_COLORS[m.modelId] || MODEL_COLORS.default)}${m.modelId.padEnd(18)}${COLORS.reset} ${formatNumber(m.totalTokens).padEnd(8)} tokens  ${formatCost(m.satsCost)} sats`);
       }
@@ -576,46 +585,201 @@ function truncateNpub(npub: string): string {
   return npub.slice(0, 10) + "…" + npub.slice(-6);
 }
 
-export function renderRecent(stats: UsageStats, width: number): string {
+/**
+ * Token breakdown of a single request, split the way the TUI colours it:
+ * input read from the prompt cache (green) vs input that was not (red,
+ * i.e. cache writes plus uncached input), plus output tokens.
+ */
+export interface TokenSegments {
+  /** Input tokens served from the prompt cache. */
+  cacheRead: number;
+  /** Input tokens that were not served from the cache. */
+  notCached: number;
+  /** Total input tokens, cached and not. */
+  input: number;
+  output: number;
+  /** Input + output. */
+  total: number;
+}
+
+/**
+ * Split a usage entry into cache read / not-cached input and output tokens.
+ *
+ * Providers report prompt tokens inconsistently: OpenAI-style `prompt_tokens`
+ * already includes the cached subsets, while Anthropic-style `input_tokens`
+ * reports them alongside. If the prompt is at least as large as the cached
+ * counts it is treated as containing them (OpenAI); otherwise the cached
+ * counts are extra (Anthropic). `input` is the sum of what is drawn rather
+ * than a possibly under-counted `totalTokens`.
+ */
+export function tokenSegments(entry: {
+  promptTokens?: number;
+  completionTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+}): TokenSegments {
+  const cacheRead = Math.max(0, entry.cacheReadInputTokens || 0);
+  const cacheWrite = Math.max(0, entry.cacheCreationInputTokens || 0);
+  const prompt = Math.max(0, entry.promptTokens || 0);
+  const output = Math.max(0, entry.completionTokens || 0);
+  const cached = cacheRead + cacheWrite;
+  const uncachedInput = prompt >= cached ? prompt - cached : prompt;
+  const notCached = cacheWrite + uncachedInput;
+  const input = cacheRead + notCached;
+  return { cacheRead, notCached, input, output, total: input + output };
+}
+
+/** One coloured slice of a {@link renderStackedBar}. */
+export interface BarSegment {
+  /** Segment magnitude; negatives are treated as zero. */
+  value: number;
+  /** ANSI escape applied to this segment's cells. */
+  color: string;
+}
+
+/**
+ * Render a fixed-width stacked bar: `trackWidth` cells split between the
+ * segments in proportion to their values, so the bar conveys *composition*
+ * (magnitude is reported separately, e.g. as the token total beside it).
+ *
+ * Cell counts use largest-remainder rounding, so the segments always fill
+ * exactly `trackWidth` cells. A row with no tokens renders as an empty track.
+ */
+export function renderStackedBar(segments: BarSegment[], trackWidth: number): string {
+  const track = Math.max(0, Math.floor(trackWidth));
+  if (track === 0) return "";
+
+  const values = segments.map((segment) => Math.max(0, segment.value));
+  const total = values.reduce((sum, value) => sum + value, 0);
+  if (total <= 0) return " ".repeat(track);
+
+  const exact = values.map((value) => (value / total) * track);
+  const cells = exact.map((value) => Math.floor(value));
+  let remaining = track - cells.reduce((sum, value) => sum + value, 0);
+
+  // Largest-remainder: leftover cells go to the biggest fractional parts.
+  const remainders = exact
+    .map((value, index) => ({ index, frac: value - Math.floor(value) }))
+    .sort((a, b) => b.frac - a.frac);
+  for (let i = 0; i < remainders.length && remaining > 0; i++, remaining--) {
+    cells[remainders[i]!.index]! += 1;
+  }
+
+  const bar = segments
+    .map((segment, i) => (cells[i]! > 0 ? `${segment.color}${"█".repeat(cells[i]!)}` : ""))
+    .join("");
+  return bar.length > 0 ? bar + COLORS.reset : " ".repeat(track);
+}
+
+/** Colour coding for the Recent tab's cache-hit bars. */
+const TOKEN_BAR_COLORS = {
+  cacheRead: COLORS.green,
+  notCached: COLORS.red,
+};
+
+export function renderRecent(stats: UsageStats, width: number, naming: ClientNaming): string {
   const recentEntries = stats.entries.slice(0, 50);
   if (recentEntries.length === 0) return renderBox(["No recent entries"], width, "Recent Requests");
 
-  const clientCol = 14;
-  const tokensCol = 18;
-  const costCol = 18;
-  const providerCol = Math.max(16, width - 4 - 10 - 18 - tokensCol - costCol - clientCol - 5);
-  const msatsToSats = (msats?: number) => typeof msats === "number" ? msats / 1000 : 0;
+  const timeCol = 8;
+  const costCol = 12;
+  // Width reserved left of the token counts for the cache-hit bar. `CACHE HIT`
+  // is the header drawn over the bar, so the bar can never be narrower.
+  const minBarWidth = "CACHE HIT".length;
+  const maxBarWidth = 20;
+  const minProviderCol = 12;
+  const minModelCol = 10;
+  const minClientCol = 6;
+
+  // Remote mode: `Alice (claude-code)` — owner display name + the client id
+  // with the `-<npub tail>` suffix stripped. Local mode (no owner/name data)
+  // keeps the previous behaviour: the raw id in a fixed 14-col cell.
+  const hasOwnerInfo = naming.npubs.length > 0 || naming.ownersByClientId.size > 0;
+  const clientLabels = recentEntries.map((entry) =>
+    hasOwnerInfo ? resolveClientLabel(entry.client, naming) : entry.client || "unknown"
+  );
+  const maxLabelLen = clientLabels.reduce((max, label) => Math.max(max, label.length), 6);
+
+  // Token counts are drawn as `IN - OUT` with IN pinned to the left edge of the
+  // column and OUT to the right, so both halves need the widest value on show.
+  const tokenRows = recentEntries.map((entry) => tokenSegments(entry));
+  const inputTexts = tokenRows.map((row) => formatNumber(row.input));
+  const outputTexts = tokenRows.map((row) => formatNumber(row.output));
+  const inputCol = Math.max(...inputTexts.map((text) => text.length));
+  const outputCol = Math.max(...outputTexts.map((text) => text.length));
+  const inOutCol = inputCol + outputCol + " - ".length;
+
+  // Lay out the columns against the box's inner width: start from the widest
+  // layout, hand the slack to the provider column, then give space back in
+  // priority order (bar, provider, model, client) until everything fits.
+  const innerWidth = Math.max(0, width - 4);
+  let modelCol = 18;
+  let clientCol = hasOwnerInfo ? Math.min(32, Math.max(14, maxLabelLen)) : 14;
+  let barWidth = maxBarWidth;
+  let showProvider = false;
+  let providerCol = 0;
+  // Column widths plus one separator between each visible column.
+  const usedWidth = () =>
+    timeCol + modelCol + (barWidth + 1 + inOutCol) + costCol + clientCol +
+    (showProvider ? providerCol + 1 : 0) + 4;
+
+  if (innerWidth - usedWidth() > minProviderCol + 1) {
+    showProvider = true;
+    providerCol = innerWidth - usedWidth();
+  }
+  while (usedWidth() > innerWidth && barWidth > minBarWidth) barWidth -= 1;
+  while (usedWidth() > innerWidth && providerCol > minProviderCol) providerCol -= 1;
+  while (usedWidth() > innerWidth && modelCol > minModelCol) modelCol -= 1;
+  while (usedWidth() > innerWidth && clientCol > minClientCol) clientCol -= 1;
+
+  const tokensCol = barWidth + 1 + inOutCol;
+
   const lines: string[] = [];
-  lines.push(`${COLORS.bold}${"TIME".padEnd(10)} ${"MODEL".padEnd(18)} ${"I/CR/CW/O".padEnd(tokensCol)} ${"I/O/T in sats".padEnd(costCol)} ${"BASE:PROVIDER".padEnd(providerCol)} ${"CLIENT".slice(0, clientCol)}${COLORS.reset}`);
-  lines.push(COLORS.dim + "─".repeat(width - 4) + COLORS.reset);
+  const header = [
+    "TIME".padEnd(timeCol),
+    "MODEL".padEnd(modelCol),
+    "CACHE HIT".padEnd(tokensCol - inOutCol) + "IN".padEnd(inputCol) + " - " + "OUT".padStart(outputCol),
+    // Right-aligned like the values below it, so the column's right edge is
+    // shared by the header and every `n sats` cell.
+    "COST".padStart(costCol),
+    ...(showProvider ? ["BASE:PROVIDER".padEnd(providerCol)] : []),
+    "CLIENT".padEnd(clientCol),
+  ];
+  lines.push(`${COLORS.bold}${header.join(" ")}${COLORS.reset}`);
+  lines.push(COLORS.dim + "─".repeat(innerWidth) + COLORS.reset);
 
-  for (const entry of recentEntries) {
+  for (let i = 0; i < recentEntries.length; i++) {
+    const entry = recentEntries[i]!;
     const time = formatTime(entry.timestamp).slice(0, 8);
-    const model = entry.modelId.slice(0, 18).padEnd(18);
-    const tokens = [
-      entry.promptTokens,
-      entry.cacheReadInputTokens || 0,
-      entry.cacheCreationInputTokens || 0,
-      entry.completionTokens,
-    ].map(formatNumber).join("/");
+    const model = entry.modelId.slice(0, modelCol).padEnd(modelCol);
+    const segments = tokenRows[i]!;
+    const bar = renderStackedBar([
+      { value: segments.cacheRead, color: TOKEN_BAR_COLORS.cacheRead },
+      { value: segments.notCached, color: TOKEN_BAR_COLORS.notCached },
+    ], barWidth);
+    const tokens = `${bar} ${inputTexts[i]!.padEnd(inputCol)} - ${outputTexts[i]!.padStart(outputCol)}`;
     const totalSats = typeof entry.totalMsats === "number" ? entry.totalMsats / 1000 : entry.satsCost;
-    const cost = [
-      formatCost(msatsToSats(entry.inputMsats)),
-      formatCost(msatsToSats(entry.outputMsats)),
-      formatCost(totalSats),
-    ].join("/");
+    // Right-aligned so the `sats` unit ends at the same column on every row.
+    const cost = `${formatCost(totalSats)} sats`.padStart(costCol);
     const baseUrl = (entry.baseUrl || "unknown").replace("https://", "").replace("http://", "");
     const provider = `${baseUrl}:${entry.provider || "unknown"}`.slice(0, providerCol).padEnd(providerCol);
-    const clientName = (entry.client || "unknown").slice(0, clientCol - 1);
+    const clientLabel = clientLabels[i]!.slice(0, clientCol).padEnd(clientCol);
     const clientColor = CLIENT_COLORS[entry.client || "unknown"] || CLIENT_COLORS.default || COLORS.white;
     const modelColor = MODEL_COLORS[entry.modelId] || MODEL_COLORS.default;
-    lines.push(`${COLORS.dim}${time}${COLORS.reset} ${modelColor}${model}${COLORS.reset} ${tokens.padEnd(tokensCol)} ${COLORS.green}${cost.padEnd(costCol)}${COLORS.reset} ${COLORS.dim}${provider}${COLORS.reset} ${clientColor}${clientName}${COLORS.reset}`);
+    lines.push([
+      `${COLORS.dim}${time}${COLORS.reset}`,
+      `${modelColor}${model}${COLORS.reset}`,
+      tokens,
+      `${COLORS.green}${cost.padEnd(costCol)}${COLORS.reset}`,
+      ...(showProvider ? [`${COLORS.dim}${provider}${COLORS.reset}`] : []),
+      `${clientColor}${clientLabel}${COLORS.reset}`,
+    ].join(" "));
   }
 
   return renderBox(lines, width, `Recent Requests (${stats.entries.length} shown)`);
 }
 
-export function renderTabContent(activeTab: TabId, stats: UsageStats, balance: BalanceInfo | null, status: StatusInfo | null, width: number, clients: ClientInfo[] = []): string {
+export function renderTabContent(activeTab: TabId, stats: UsageStats, balance: BalanceInfo | null, status: StatusInfo | null, width: number, naming: ClientNaming): string {
   switch (activeTab) {
     case "overview": return renderOverview(stats, balance, status, width);
     case "today": return renderToday(stats, width);
@@ -623,8 +787,8 @@ export function renderTabContent(activeTab: TabId, stats: UsageStats, balance: B
     case "providers": return renderProviders(stats, width);
     case "tokens": return renderTokens(stats, width);
     case "clients": return renderClients(stats, width);
-    case "npubs": return renderNpubs(stats, clients, width);
-    case "recent": return renderRecent(stats, width);
+    case "npubs": return renderNpubs(stats, naming, width);
+    case "recent": return renderRecent(stats, width, naming);
     default: return "Unknown tab";
   }
 }

package/src/TUI refactor.md

@@ -1,113 +0,0 @@
-# TUI refactor plan
-
-## Goals
-- Move the usage TUI implementation out of `src/cli/usage-tui.ts` into a dedicated `src/tui/` folder.
-- Reduce the size and responsibility of the current monolithic file.
-- Keep the existing CLI entrypoint stable so current usage does not break.
-- Preserve behavior while making future TUI work easier.
-
-## Current state
-`src/cli/usage-tui.ts` currently mixes several concerns in one file:
-- TUI-specific types and constants
-- ANSI/terminal helpers
-- scroll/search/vim navigation state
-- data fetching from the daemon
-- usage aggregation/stat helpers
-- rendering for all tabs
-- app lifecycle and keyboard event handling
-
-This makes the file hard to extend safely.
-
-## Refactor strategy
-Do this incrementally and keep a thin compatibility wrapper in `src/cli/usage-tui.ts`.
-
-### Target structure
-- `src/tui/usage/index.ts`
-  - public entrypoint: `runUsageTui()`
-- `src/tui/usage/types.ts`
-  - `UsageStats`, tab ids, tab metadata, derived stat types
-- `src/tui/usage/constants.ts`
-  - tabs, colors, model/client color maps
-- `src/tui/usage/terminal.ts`
-  - ANSI helpers, width/height helpers, `stripAnsi`
-- `src/tui/usage/state.ts`
-  - vim/search/scroll state and state mutation helpers
-- `src/tui/usage/data.ts`
-  - `fetchUsage()` and usage aggregation helpers
-- `src/tui/usage/render.ts`
-  - shared render helpers and tab renderers
-- `src/tui/usage/app.ts`
-  - main loop, render orchestration, input handling, cleanup
-- `src/cli/usage-tui.ts`
-  - compatibility wrapper that re-exports or calls `runUsageTui()` from `src/tui/usage`
-
-## Design choices
-### 1. Keep CLI path compatibility
-Do not delete the CLI file outright. Turn it into a tiny wrapper:
-- minimal import from `../tui/usage/index.ts`
-- export `runUsageTui()`
-
-This avoids breaking any existing imports or scripts.
-
-### 2. Separate pure logic from side effects
-Keep these pure where possible:
-- aggregation helpers
-- formatting helpers
-- render helpers that return strings
-- scroll clamping logic
-
-Keep side effects isolated in the app layer:
-- reading terminal size
-- writing to stdout
-- raw mode setup
-- signal handling
-- interval scheduling
-
-### 3. Avoid over-engineering
-This should be a pragmatic refactor, not a framework:
-- no unnecessary classes
-- keep function-based design
-- only extract modules around clear responsibility boundaries
-
-### 4. Preserve behavior first
-No UX changes unless needed to support the extraction.
-That means:
-- same tabs
-- same keybindings
-- same output format
-- same fetch cadence
-- same search/scroll behavior
-
-## Implementation steps
-1. Create `src/tui/usage/`.
-2. Extract types/constants first.
-3. Extract terminal helpers.
-4. Extract data fetching + aggregation helpers.
-5. Extract state/search/scroll logic.
-6. Extract rendering helpers + tab renderers.
-7. Build `app.ts` using the extracted modules.
-8. Replace `src/cli/usage-tui.ts` with a thin wrapper.
-9. Run a TypeScript/bun check and fix imports.
-10. Smoke-test keyboard handling and rendering behavior.
-
-## Risks
-- circular imports between render/state/constants
-- broken relative import paths during extraction
-- subtle behavior regressions in scroll/search state
-- terminal escape handling differences if helpers are split carelessly
-
-## Validation checklist
-- `src/cli/usage-tui.ts` still exposes `runUsageTui()`
-- TUI starts from the same CLI path
-- scroll still works for long content
-- vim keys still work
-- arrow keys still work
-- tab switching still resets scroll
-- search mode still works
-- cleanup still restores cursor and alternate screen
-
-## Non-goals
-- redesigning the UI
-- changing tab contents
-- introducing tests unless needed for safety
-- adding new features unrelated to the refactor