diff --git a/.specs/features/web-usage-redesign/spec.md b/.specs/features/web-usage-redesign/spec.md
new file mode 100644
index 0000000..1359014
--- /dev/null
+++ b/.specs/features/web-usage-redesign/spec.md
@@ -0,0 +1,122 @@
+# Web usage redesign
+
+## Goal
+
+Replace the current `/usage` page of `codedeck ui` with the approved "mock D" design: a black + blue analytics
+dashboard in the Cloudflare/Vercel language, with masked numbers, charts and working controls. Introduce the
+CodeDeck brand (edge-on deck logo, palette) as a shared web module so later pages can reuse it.
+
+The approved visual reference was a static mock ("mock D") built from real local usage data. It is kept out of
+the repository because that data names private repositories. Where the mock and this spec disagree, this spec
+wins. The known mock defects are listed under R9 and must not ship.
+
+## Out of scope
+
+- Restyling Home, Setup and Review pages (a follow-up feature reuses the brand module).
+- A sessions endpoint and the "Recent sessions" widget from the mock (dropped: the usage API has no sessions).
+- Fixing the repository grouping that reports worktree/cwd basenames (`e174`, `.claude`, `dev`) as repositories.
+- Changes to the daemon, the usage query, the store, or `/api/usage` response shape.
+- New runtime dependencies. The page stays a self-contained server-rendered string with inline CSS, SVG and script.
+
+## Brand (source of truth for tokens)
+
+- Colors: `--bg #000000`, `--surface #0a0a0a`, `--surface-hover #111111`, `--surface-raised #161616`,
+  `--border #1f1f1f`, `--border-strong #2e2e2e`, `--grid #1a1a1a`, `--text #ededed`, `--text-muted #a1a1a1`,
+  `--text-faint #6b6b6b`, `--blue #0070f3`, `--blue-chart #3b82f6`, categorical ramp
+  `#3b82f6 #93c5fd #1d4ed8 #60a5fa #bfdbfe #1e3a8a`, other `#737373 #404040`, success `#10b981`, error `#e5484d`.
+- Type: sans `"Geist", "Inter", ui-sans-serif, system-ui, sans-serif`; mono `"Geist Mono", ui-monospace, "JetBrains Mono", monospace`.
+- Logo "edge-on deck" (viewBox 0 0 64 64):
+  cards `m13 25 34-8 6 4-34 8zM13 32l34-8 6 4-34 8zM13 39l34-8 6 4-34 8zM13 46l34-8 6 4-34 8z` fill `#000`, stroke `#ededed`;
+  top card `m13 25 34-8 6 4-34 8z` fill and stroke `#0070f3`. Stroke width scales up as size drops
+  (about 2.2 at 64px, 5 at 20px, 6 at 16px). Wordmark: lowercase `codedeck`, sans 600.
+
+## Requirements
+
+### R1. Page loads data in a real browser
+
+- R1.1 WHEN the usage page script runs in a browser THEN it SHALL call `fetch`, `setInterval` and `clearInterval`
+  with the global object as receiver, so a native `fetch` never throws "Illegal invocation".
+- R1.2 WHEN `/usage` is opened in headless Chromium against a running `codedeck ui` THEN the console SHALL log no
+  uncaught error and the page SHALL show the totals of the default range.
+
+### R2. Brand and chrome
+
+- R2.1 The page SHALL render a 52px top bar with the edge-on deck logo, the `codedeck` wordmark, the page name and
+  quiet nav links to every page registered in the route table, with Usage marked active.
+- R2.2 The page SHALL declare the edge-on deck logo as its favicon (inline data URI), replacing `data:,`.
+- R2.3 The palette and type tokens above SHALL live in one shared web module that exports the CSS custom
+  properties, the logo SVG (sized) and the top bar renderer, and the usage page SHALL consume them from there.
+- R2.4 The page SHALL render exactly one range picker.
+
+### R3. Number masks
+
+- R3.1 Token and count values ≥ 1,000,000,000 SHALL render as `1.19B`, ≥ 1,000,000 as `16.8M`, ≥ 10,000 as `842K`;
+  smaller counts SHALL render with thousands separators (`2,427`).
+- R3.2 Currency SHALL render as `$1,865.42` (two decimals, thousands separators); axis ticks SHALL use at most two decimals.
+- R3.3 Percentages SHALL render with one decimal (`47.8%`) and name the base they are a share of ("of spend", "of sessions").
+- R3.4 Every masked value SHALL carry its unmasked value in a `title` attribute.
+- R3.5 WHEN `costComplete` is false THEN the cost SHALL render as `≥ $X` next to a neutral pill "`N` unpriced" using
+  `sessionsWithoutCost`; a bare trailing `?` SHALL NOT appear anywhere on the page.
+
+### R4. Range, filters and refresh
+
+- R4.1 The range picker SHALL offer Today, Last 3 days, Last 7 days, Last 30 days, All time and Custom; Custom SHALL
+  reveal since/until date inputs. Changing it SHALL re-query `/api/usage` with the same parameters the page accepts today.
+- R4.2 "Add filter" SHALL open a menu to add a repository, model or agent filter; an applied filter SHALL render as a
+  removable chip, and adding or removing a chip SHALL re-query with that filter.
+- R4.3 WHILE Live refresh is on the page SHALL poll at the configured interval; WHEN it is toggled off THEN polling SHALL stop.
+- R4.4 A background poll SHALL NOT replace rendered content with a loading state; a loading indicator SHALL appear only
+  for the first load and for user-initiated changes.
+- R4.5 IF a query fails THEN the page SHALL keep the last good data visible and show the error in a dismissible banner.
+- R4.6 WHEN `/usage` is opened with `period`, `repo`, `model`, `agent`, `since`, `until` or `by` in its query string THEN
+  the page SHALL start with those values.
+- R4.7 WHEN the range, a filter or the breakdown tab changes THEN the page SHALL update its URL query with
+  `history.replaceState` so "Copy link" copies a URL that reopens the same view.
+
+### R5. KPI row
+
+- R5.1 The page SHALL show four KPI cards: Spend, Sessions, Total tokens, Cache hit rate (cached / (input + cached)),
+  each with a sparkline from `byDay` bleeding to the card's bottom edge.
+- R5.2 WHEN the range is 3d, 7d or 30d THEN each KPI SHALL show a delta arrow and percentage versus the immediately
+  preceding window of equal length, labeled "vs previous 7d" (or 3d/30d), from a second `/api/usage` query with
+  explicit since/until.
+- R5.3 WHEN the range is Today, All time or Custom, or the previous window has zero for that metric, THEN the delta SHALL be hidden.
+
+### R6. Charts
+
+- R6.1 "Spend over time" SHALL plot `byDay` as a line with area fill and dashed grid, with a legend switch between
+  Spend, Tokens and Sessions, and a crosshair tooltip showing date and masked value.
+- R6.2 "Spend by model" SHALL be a donut of `byModel.costUsd` with the top 6 models plus one "Other" slice, its center
+  showing the masked total spend, and a legend with model id (mono), value and share of spend.
+- R6.3 "Spend by repository" SHALL list `byRepository` by cost descending with a thin blue bar scaled to the top row,
+  scrolling inside its card.
+- R6.4 "Sessions by outcome" SHALL show completed, failed, active and other (sessions minus the three) as one
+  segmented bar with counts and share of sessions; failed SHALL use the error color.
+- R6.5 "Harness" SHALL show, per `byAgent` key, share of spend and share of sessions, both labeled, each on one line at 1440px.
+- R6.6 "Origin" SHALL show worker vs orchestrator share of sessions and of spend, both labeled.
+- R6.7 Every chart segment or point SHALL have a hover tooltip; SVG text SHALL never be stretched
+  (no `preserveAspectRatio="none"` on any SVG containing text) and charts SHALL re-render on resize.
+- R6.8 WHEN a breakdown or series is empty THEN its card SHALL show "No usage in this range" instead of an empty chart.
+
+### R7. Breakdown table
+
+- R7.1 Tabs Day, Repository, Model, Agent, Run, Origin SHALL switch the table rows to the selected breakdown, and only
+  the selected breakdown SHALL be visible.
+- R7.2 Clicking a column header SHALL sort by that column, toggling ascending/descending.
+- R7.3 The table SHALL show the top 10 rows and a "Show all N" toggle when there are more.
+- R7.4 A search input SHALL filter the visible rows by label; pressing `/` outside an input SHALL focus it.
+- R7.5 Columns SHALL be Name, Sessions, Spend, Tokens, Share of spend (thin bar left-aligned in its own column).
+
+### R8. Layout
+
+- R8.1 At 1440px wide the layout SHALL follow the mock order: header, filter bar, KPI row (4), spend over time,
+  model + repository row, outcome + harness + origin row, breakdown.
+- R8.2 At 390px wide the page SHALL have no page-level horizontal scroll (`document.documentElement.scrollWidth <= 390`),
+  cards SHALL stack in one column, and axis labels SHALL render at 10px or larger.
+- R8.3 Cards in the same row SHALL size to content without leaving a region taller than 120px empty.
+
+### R9. Mock defects that must not ship
+
+- R9.1 No native control SHALL render with a light/white background (profile or range selects included).
+- R9.2 The donut center SHALL show total spend as currency, never a token/count abbreviation.
+- R9.3 No duplicated control (range picker, refresh) SHALL appear.
diff --git a/.specs/features/web-usage-redesign/tasks.md b/.specs/features/web-usage-redesign/tasks.md
new file mode 100644
index 0000000..67e0571
--- /dev/null
+++ b/.specs/features/web-usage-redesign/tasks.md
@@ -0,0 +1,76 @@
+# Web usage redesign: tasks
+
+Source of truth: `spec.md` in this folder. The visual reference mock is local only (see `spec.md`).
+
+## Design notes
+
+- Keep the current architecture: `renderUsagePage` returns a self-contained HTML string; browser behavior is shipped
+  by serializing named functions with `Function.prototype.toString` into the inline script. Every function the
+  browser calls must be in that list and must not reference module imports or closures outside itself.
+- Chart and formatting code are pure functions that return strings or plain data (for example `formatCompact`,
+  `formatUsd`, `formatShare`, `previousWindow`, `computeDelta`, `donutSlices`, `renderDonutSvg`,
+  `renderLineChartSvg`, `renderSparklineSvg`). DOM code only inserts their output. This keeps them unit-testable
+  under vitest's node environment without a DOM library.
+- `src/web/brand.ts` owns tokens, logo and top bar. It is server-side only (it renders strings into the page).
+- The nav in the top bar comes from the route table: `createUiRoutes` already computes `pages`; pass them to the
+  usage page through `UsageRoutesOptions.page`.
+- Default range stays `today` (current behavior and existing tests).
+
+## Coverage matrix
+
+| Layer | Test type | Location | Command |
+| --- | --- | --- | --- |
+| Brand module `src/web/brand.ts` | unit | `tests/web-brand.test.ts` | `npx vitest run tests/web-brand.test.ts` |
+| Usage pure logic (formatters, deltas, previous window, donut slices, SVG builders, controller) | unit | `tests/usage-page.test.ts` | `npx vitest run tests/usage-page.test.ts` |
+| Usage inline script (serialized functions run, receiver binding) | unit via `node:vm` | `tests/usage-page.test.ts` | same as above |
+| Route wiring (nav passed to usage page) | unit | `tests/usage-web.test.ts`, `tests/web-cli.test.ts` | `npx vitest run tests/usage-web.test.ts tests/web-cli.test.ts` |
+| Rendered page in a real browser (R1.2, R8, R9) | manual e2e gate | none committed; evidence is screenshots + console log | T3 commands |
+
+## T1. Brand module
+
+- Requirement: R2.2, R2.3.
+- Files: new `src/web/brand.ts`, new `tests/web-brand.test.ts`.
+- Produces: `BRAND_CSS` (custom properties + base resets for black surfaces, native controls styled dark per R9.1),
+  `renderLogoSvg(size: 16 | 20 | 64)`, `LOGO_FAVICON_HREF` (data URI), `renderTopBar({ pages, activePath, title })`
+  with escaped labels.
+- Tests: tokens present with exact hex values; logo contains both path data strings and the blue top card; stroke
+  width grows as size drops; favicon is a `data:image/svg+xml` URI; top bar lists every page, marks the active one
+  with `aria-current="page"`, escapes HTML in labels.
+- Gate: `npx vitest run tests/web-brand.test.ts` passes; `npx tsc --noEmit` clean.
+
+## T2. Usage page redesign
+
+- Requirement: R1.1, R2.1, R2.4, R3.*, R4.*, R5.*, R6.*, R7.*, R8.1, R9.*.
+- Files: `src/web/usage-page.ts`, `src/web/usage-routes.ts`, `src/cli/commands/ui.ts`, `tests/usage-page.test.ts`,
+  `tests/usage-web.test.ts`, `tests/web-cli.test.ts` (only if the wiring assertion belongs there).
+- Tests (ship with the code):
+  - R1.1: in `node:vm`, run the page script with a `fetch`/`setInterval`/`clearInterval` that throw
+    `TypeError("Illegal invocation")` when `this` is not the context global; start the page with a minimal fake DOM
+    or call the environment wiring the script uses, and assert no throw and one fetch.
+  - R3.*: table-driven cases for `formatCompact` (999, 10_000, 842_310, 16_756_717, 1_193_095_059), `formatUsd`
+    (1865.421706 → `$1,865.42`), share formatting, incomplete-cost rendering (`≥` + unpriced pill, no bare `?`).
+  - R5.2/R5.3: `previousWindow` for 3d/7d/30d returns an equal-length window ending where the current begins;
+    `computeDelta` hides on zero base and for today/all/custom.
+  - R6.2/R9.2: `donutSlices` returns top 6 + Other summing to the total; donut center renders currency.
+  - R6.7: no SVG builder output that contains `<text` also contains `preserveAspectRatio="none"`.
+  - R6.8: empty buckets render "No usage in this range".
+  - R7.*: controller or pure table helpers: tab switch selects only that breakdown, sort toggles, top 10 + show all, search filter.
+  - R4.3/R4.4: toggling live refresh off clears the interval; a poll-triggered refresh does not set the loading flag.
+  - R2.1/R2.4: rendered HTML contains the top bar with Usage active, the favicon, exactly one range picker.
+  - R4.6: the `/usage` route passes query values into the page options (test in `tests/usage-web.test.ts`).
+  - R4.7: a pure `buildUsagePageSearch(state)` returns the query string the page writes; the controller calls the
+    injected `replaceUrl` on range, filter and tab changes.
+  - Update existing assertions that pinned the old markup; keep the behavior they protected (filters, re-query, error keeps last result).
+- Gate: `npx vitest run tests/usage-page.test.ts tests/usage-web.test.ts tests/web-cli.test.ts tests/web-brand.test.ts tests/ui-render.test.ts` passes; `npx tsc --noEmit` clean; `npm run build` succeeds.
+
+## T3. Browser gate
+
+- Requirement: R1.2, R8.2, R8.3, R9.1, R9.3.
+- Commands (after `npm run build`):
+  1. `node dist/cli/index.js ui --no-open --port 3141` (prints a URL with `?t=<token>`).
+  2. `chromium --headless=new --disable-gpu --hide-scrollbars --window-size=1440,2600 --virtual-time-budget=5000 --screenshot=<scratch>/usage-1440.png "<url>/usage?t=<token>&period=7d"`.
+  3. Same at `--window-size=390,4200` → `usage-390.png`.
+  4. `chromium --headless=new --disable-gpu --enable-logging=stderr --v=0 --virtual-time-budget=5000 --dump-dom "<url>" 2>&1 | grep -i -e uncaught -e "illegal invocation"` → empty.
+  5. Stop the server.
+- Tests: none (manual gate per the matrix).
+- Gate: screenshots show real data with masked numbers and no white controls; no console errors; no page-level horizontal scroll at 390px.
diff --git a/src/cli/commands/ui.ts b/src/cli/commands/ui.ts
index c01c285..c59ca95 100644
--- a/src/cli/commands/ui.ts
+++ b/src/cli/commands/ui.ts
@@ -20,13 +20,17 @@ export interface UiCommandDependencies {
 export function createUiRoutes(dependencies: Pick<UiCommandDependencies, "setup" | "usage"> = {}): WebRoute[] {
   const reviewRoutes = createReviewRoutes().filter((route) => route.path !== "/");
   const setupRoutes = createSetupRoutes(dependencies.setup);
-  const usageRoutes = createUsageRoutes(dependencies.usage ?? { fetchUsageQuery }).map((route) =>
+  const usageOptions = dependencies.usage ?? { fetchUsageQuery };
+  const labeledUsageRoutes = createUsageRoutes(usageOptions).map((route) =>
     route.path === "/usage" ? { ...route, label: "Usage" } : route,
   );
-  const routes = [...reviewRoutes, ...setupRoutes, ...usageRoutes];
-  const pages = routes.flatMap((route) =>
+  const routes = [...reviewRoutes, ...setupRoutes];
+  const pages = [...routes, ...labeledUsageRoutes].flatMap((route) =>
     route.kind === "page" && route.label ? [{ label: route.label, path: route.path }] : [],
   );
+  const usageRoutes = createUsageRoutes({ ...usageOptions, pages }).map((route) =>
+    route.path === "/usage" ? { ...route, label: "Usage" } : route,
+  );
   const home: WebRoute = {
     path: "/",
     kind: "page",
@@ -35,7 +39,7 @@ export function createUiRoutes(dependencies: Pick<UiCommandDependencies, "setup"
       response.end(renderHomePage(pages));
     },
   };
-  return [home, ...routes];
+  return [home, ...routes, ...usageRoutes];
 }
 
 export function registerUiCommand(program: Command, dependencies: UiCommandDependencies = {}): void {
diff --git a/src/web/brand.ts b/src/web/brand.ts
new file mode 100644
index 0000000..0b7e44d
--- /dev/null
+++ b/src/web/brand.ts
@@ -0,0 +1,74 @@
+const CARDS_PATH = "m13 25 34-8 6 4-34 8zM13 32l34-8 6 4-34 8zM13 39l34-8 6 4-34 8zM13 46l34-8 6 4-34 8z";
+const TOP_CARD_PATH = "m13 25 34-8 6 4-34 8z";
+
+export const BRAND_CSS = `
+:root {
+  --bg: #000000;
+  --surface: #0a0a0a;
+  --surface-hover: #111111;
+  --surface-raised: #161616;
+  --border: #1f1f1f;
+  --border-strong: #2e2e2e;
+  --grid: #1a1a1a;
+  --text: #ededed;
+  --text-muted: #a1a1a1;
+  --text-faint: #6b6b6b;
+  --blue: #0070f3;
+  --blue-chart: #3b82f6;
+  --blue-2: #93c5fd;
+  --blue-3: #1d4ed8;
+  --blue-4: #60a5fa;
+  --blue-5: #bfdbfe;
+  --blue-6: #1e3a8a;
+  --neutral: #737373;
+  --neutral-dark: #404040;
+  --success: #10b981;
+  --error: #e5484d;
+  --font-sans: "Geist", "Inter", ui-sans-serif, system-ui, sans-serif;
+  --font-mono: "Geist Mono", ui-monospace, "JetBrains Mono", monospace;
+  color-scheme: dark;
+  font-family: var(--font-sans);
+  background: var(--bg);
+  color: var(--text);
+}
+*, *::before, *::after { box-sizing: border-box; }
+html { min-width: 320px; background: var(--bg); }
+body { margin: 0; background: var(--bg); color: var(--text); font-family: var(--font-sans); }
+button, input, select { color-scheme: dark; font: inherit; }
+`;
+
+export function renderLogoSvg(size: 16 | 20 | 64): string {
+  const strokeWidth = size === 64 ? 2.2 : size === 20 ? 5 : 6;
+  return `<svg width="${size}" height="${size}" viewBox="0 0 64 64" aria-hidden="true" focusable="false"><path d="${CARDS_PATH}" fill="#000" stroke="#ededed" stroke-width="${strokeWidth}" stroke-linejoin="round"/><path d="${TOP_CARD_PATH}" fill="#0070f3" stroke="#0070f3" stroke-width="${strokeWidth}" stroke-linejoin="round"/></svg>`;
+}
+
+export const LOGO_FAVICON_HREF = `data:image/svg+xml,${encodeURIComponent(renderLogoSvg(64))}`;
+
+export interface WebPageLink {
+  label: string;
+  path: string;
+}
+
+export interface TopBarOptions {
+  pages: WebPageLink[];
+  activePath: string;
+  title: string;
+}
+
+export function renderTopBar(options: TopBarOptions): string {
+  const links = options.pages.map(({ label, path }) => {
+    const active = path === options.activePath;
+    return `<a href="${escapeHtml(path)}"${active ? ' aria-current="page" class="active"' : ""}>${escapeHtml(label)}</a>`;
+  }).join("");
+  return `<header class="topbar"><a class="brand" href="/" aria-label="CodeDeck home">${renderLogoSvg(20)}<span>codedeck</span></a><span class="topbar-title">${escapeHtml(options.title)}</span><nav aria-label="Main navigation">${links}</nav></header>`;
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (character) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+  })[character] ?? character);
+}
diff --git a/src/web/usage-page.ts b/src/web/usage-page.ts
index 9b3b452..75cfd6d 100644
--- a/src/web/usage-page.ts
+++ b/src/web/usage-page.ts
@@ -1,36 +1,20 @@
 import type { UsageMetricBucket, UsageQueryResult } from "../daemon/protocol.js";
+import { BRAND_CSS, LOGO_FAVICON_HREF, renderTopBar, type WebPageLink } from "./brand.js";
 
 export type UsageBreakdown = "day" | "repo" | "model" | "agent" | "run" | "origin";
-
-export interface UsagePageFilters {
-  period: string;
-  repo: string;
-  model: string;
-  agent: string;
-  since: string;
-  until: string;
-}
-
-export interface UsagePageData extends Omit<UsageQueryResult, "byOrigin"> {
-  byOrigin: UsageMetricBucket[];
-}
-
+export interface UsagePageFilters { period: string; repo: string; model: string; agent: string; since: string; until: string; }
+export interface UsagePageData extends Omit<UsageQueryResult, "byOrigin"> { byOrigin: UsageMetricBucket[]; }
 export interface UsagePageState {
   filters: UsagePageFilters;
   result: UsagePageData | null;
+  previous: UsagePageData | null;
   error?: string;
   loading: boolean;
   selectedBreakdown: UsageBreakdown;
   breakdowns: UsageBreakdown[];
   intervalSeconds: number;
 }
-
-export interface UsagePageFetchResponse {
-  ok: boolean;
-  status?: number;
-  json(): Promise<unknown>;
-}
-
+export interface UsagePageFetchResponse { ok: boolean; status?: number; json(): Promise<unknown>; }
 export interface UsagePageControllerOptions {
   initialFilters?: Partial<UsagePageFilters>;
   initialBy?: UsageBreakdown;
@@ -38,36 +22,33 @@ export interface UsagePageControllerOptions {
   fetch: (url: string) => Promise<UsagePageFetchResponse>;
   setInterval: (callback: () => void, milliseconds: number) => unknown;
   clearInterval: (handle: unknown) => void;
+  replaceUrl?: (search: string) => void;
   render: (state: UsagePageState) => void;
 }
-
 export interface UsagePageController {
   getState(): UsagePageState;
-  refresh(): Promise<UsagePageState>;
+  refresh(userInitiated?: boolean): Promise<UsagePageState>;
   setFilter(name: keyof UsagePageFilters, value: string): Promise<UsagePageState>;
+  setFilters(values: Partial<UsagePageFilters>): Promise<UsagePageState>;
   setBreakdown(name: UsageBreakdown): void;
-  start(): Promise<void>;
   stop(): void;
+  start(): Promise<void>;
 }
-
-export interface UsagePageOptions {
-  by?: UsageBreakdown;
-  interval?: unknown;
-  filters?: Partial<UsagePageFilters>;
-}
-
+export interface UsagePageOptions { by?: UsageBreakdown; interval?: unknown; filters?: Partial<UsagePageFilters>; pages?: WebPageLink[]; }
 export interface UsagePageEnvironment {
   fetch: (url: string) => Promise<UsagePageFetchResponse>;
   setInterval: (callback: () => void, milliseconds: number) => unknown;
   clearInterval: (handle: unknown) => void;
   document: UsagePageDocument;
+  location?: { search: string; href?: string };
+  replaceUrl?: (search: string) => void;
+  copyToClipboard?: (text: string) => void;
+  window?: { addEventListener(type: string, listener: () => void): void };
+  setTimeout?: (callback: () => void, milliseconds: number) => unknown;
+  clearTimeout?: (handle: unknown) => void;
 }
-
 interface UsagePageElement {
-  hidden: boolean;
-  textContent: string | null;
-  className: string;
-  value: string;
+  hidden: boolean; textContent: string | null; innerHTML: string; className: string; value: string;
   dataset: Record<string, string | undefined>;
   querySelector<T extends UsagePageElement = UsagePageElement>(selector: string): T | null;
   querySelectorAll<T extends UsagePageElement = UsagePageElement>(selector: string): T[];
@@ -76,53 +57,212 @@ interface UsagePageElement {
   append(...nodes: UsagePageElement[]): void;
   addEventListener(type: string, listener: (event: UsagePageEvent) => void): void;
   closest<T extends UsagePageElement = UsagePageElement>(selector: string): T | null;
+  focus(): void;
+  click(): void;
+  clientWidth: number;
+  getAttribute(name: string): string | null;
+  getBoundingClientRect(): { left: number; top: number; width: number; height: number };
+  style: { left: string; top: string };
+  selectionStart?: number | null;
+  selectionEnd?: number | null;
+  setSelectionRange?(start: number, end: number): void;
 }
-
 interface UsagePageDocument {
   getElementById(id: string): UsagePageElement | null;
   createElement(tagName: string): UsagePageElement;
+  addEventListener(type: string, listener: (event: UsagePageEvent) => void): void;
+  activeElement?: { tagName?: string } | null;
 }
+interface UsagePageEvent { target?: UsagePageElement | null; key?: string; clientX?: number; clientY?: number; preventDefault?(): void; }
 
-interface UsagePageEvent {
-  target?: UsagePageElement | null;
-}
-
-export function normalizeUsageInterval(value: unknown): number {
-  return Math.max(1, Number(value) || 2);
-}
+export function normalizeUsageInterval(value: unknown): number { return Math.max(1, Number(value) || 2); }
 
 export function buildUsageApiUrl(filters: UsagePageFilters): string {
   const params: string[] = [];
   for (const name of ["period", "repo", "model", "agent", "since", "until"] as const) {
-    const value = filters[name];
-    if (value) params.push(`${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+    if (filters[name]) params.push(`${encodeURIComponent(name)}=${encodeURIComponent(filters[name])}`);
   }
   const query = params.join("&");
   return query ? `/api/usage?${query}` : "/api/usage";
 }
 
+export interface UsageUrlState { filters: UsagePageFilters; by: UsageBreakdown; }
+export function buildUsagePageSearch(state: UsageUrlState): string {
+  const params: string[] = [];
+  for (const name of ["period", "repo", "model", "agent", "since", "until"] as const) {
+    if (state.filters[name]) params.push(`${encodeURIComponent(name)}=${encodeURIComponent(state.filters[name])}`);
+  }
+  if (state.by !== "day") params.push(`by=${encodeURIComponent(state.by)}`);
+  const query = params.join("&");
+  return query ? `?${query}` : "";
+}
+
+export function formatCompact(value: number): string {
+  const absolute = Math.abs(value);
+  if (absolute >= 1_000_000_000) return `${(value / 1_000_000_000).toFixed(2)}B`;
+  if (absolute >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
+  if (absolute >= 10_000) return `${(value / 1_000).toFixed(0)}K`;
+  return new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 }).format(value);
+}
+export function formatUsd(value: number): string {
+  return `$${new Intl.NumberFormat("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 }).format(value)}`;
+}
+export function formatAxisTick(value: number, currency = false): string {
+  return currency
+    ? `$${new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 }).format(value)}`
+    : formatCompact(value);
+}
+export function formatShare(value: number, base: "spend" | "sessions"): string {
+  return `${value.toFixed(1)}% of ${base}`;
+}
+export function formatCost(value: number, complete: boolean, sessionsWithoutCost: number): string {
+  return `${complete ? "" : "≥ "}${formatUsd(value)}${complete ? "" : ` <span class="pill" title="${sessionsWithoutCost}">${formatCompact(sessionsWithoutCost)} unpriced</span>`}`;
+}
+export function previousWindow(period: string, now: Date): { since: string; until: string } | undefined {
+  const days = Number(period.replace(/d$/, ""));
+  if (![3, 7, 30].includes(days) || !/^[0-9]+d$/.test(period)) return undefined;
+  const currentStart = new Date(now);
+  currentStart.setDate(currentStart.getDate() - days);
+  const until = new Date(currentStart.getTime() - 1);
+  const since = new Date(until);
+  since.setDate(since.getDate() - days);
+  return { since: since.toISOString(), until: until.toISOString() };
+}
+export function computeDelta(current: number, previous: number, period: string): { direction: "up" | "down"; percent: number } | undefined {
+  if (!["3d", "7d", "30d"].includes(period) || previous === 0) return undefined;
+  const difference = ((current - previous) / Math.abs(previous)) * 100;
+  return { direction: difference >= 0 ? "up" : "down", percent: Math.abs(difference) };
+}
+export function donutSlices(rows: UsageMetricBucket[], limit = 6): UsageMetricBucket[] {
+  const sorted = [...rows].sort((a, b) => b.costUsd - a.costUsd);
+  const top = sorted.slice(0, limit);
+  const remaining = sorted.slice(limit);
+  if (!remaining.length) return top;
+  const other: UsageMetricBucket = remaining.reduce((sum, row) => ({
+    key: "other", label: "Other", sessionCount: sum.sessionCount + row.sessionCount,
+    inputTokens: sum.inputTokens + row.inputTokens, outputTokens: sum.outputTokens + row.outputTokens,
+    cachedTokens: sum.cachedTokens + row.cachedTokens, totalTokens: sum.totalTokens + row.totalTokens,
+    costUsd: sum.costUsd + row.costUsd, costComplete: sum.costComplete && row.costComplete, trend: [],
+  }), { key: "other", label: "Other", sessionCount: 0, inputTokens: 0, outputTokens: 0, cachedTokens: 0, totalTokens: 0, costUsd: 0, costComplete: true, trend: [] });
+  return [...top, other];
+}
+export function renderDonutSvg(rows: UsageMetricBucket[]): string {
+  const slices = donutSlices(rows);
+  const total = slices.reduce((sum, row) => sum + row.costUsd, 0);
+  if (!slices.length || total === 0) return '<p class="empty">No usage in this range</p>';
+  const palette = ["#3b82f6", "#93c5fd", "#1d4ed8", "#60a5fa", "#bfdbfe", "#1e3a8a", "#737373"];
+  const circumference = 2 * Math.PI * 54;
+  let offset = 0;
+  const segments = slices.map((row, index) => {
+    const length = circumference * row.costUsd / total;
+    const segment = `<circle class="donut-seg" cx="85" cy="85" r="54" stroke="${palette[index]}" stroke-dasharray="${length} ${circumference - length}" stroke-dashoffset="${-offset}" tabindex="0"><title>${escapeHtml(row.label ?? row.key)}: ${formatUsd(row.costUsd)}, ${formatShare(row.costUsd / total * 100, "spend")} (${row.costUsd / total * 100})</title></circle>`;
+    offset += length;
+    return segment;
+  }).join("");
+  const center = formatUsd(total);
+  return `<svg class="donut-svg" viewBox="0 0 170 170" role="img" aria-label="Spend by model"> <g transform="rotate(-90 85 85)">${segments}</g><text class="donut-center" x="85" y="82" style="font-size:${donutCenterFontSize(center)}px" title="${total}">${center}</text><text class="donut-sub" x="85" y="103">total spend</text></svg>`;
+}
+export function donutCenterFontSize(value: string): number { return value.length >= 9 ? 10 : value.length >= 8 ? 11 : 13; }
+export function renderModelLegend(rows: UsageMetricBucket[]): string {
+  const models = donutSlices(rows);
+  const total = rows.reduce((sum, row) => sum + row.costUsd, 0);
+  return models.map((row) => `<div class="legend-row" title="${escapeHtml(row.label ?? row.key)}, ${row.costUsd}"><span class="model-name">${escapeHtml(row.label ?? row.key)}</span><strong>${formatUsd(row.costUsd)}</strong><small title="${total ? row.costUsd / total * 100 : 0}">${formatShare(total ? row.costUsd / total * 100 : 0, "spend")}</small></div>`).join("") || '<p class="empty">No usage in this range</p>';
+}
+export function renderSparklineSvg(values: number[], label: string): string {
+  if (!values.length) return '<p class="empty">No usage in this range</p>';
+  const width = 280, height = 48, max = Math.max(...values, 1), min = Math.min(...values, 0), span = max - min || 1;
+  const safeLabel = escapeHtml(label);
+  if (values.length < 2) {
+    const y = (height / 2).toFixed(1);
+    return `<svg class="spark" viewBox="0 0 ${width} ${height}" role="img" aria-label="${safeLabel} trend"><path class="spark-line" d="M0 ${y} L${width} ${y}"/></svg>`;
+  }
+  const points = values.map((value, index) => `${index ? "L" : "M"}${(index * width / Math.max(values.length - 1, 1)).toFixed(1)} ${(height - 3 - (value - min) / span * 38).toFixed(1)}`);
+  const line = points.join(" ");
+  return `<svg class="spark" viewBox="0 0 ${width} ${height}" role="img" aria-label="${safeLabel} trend"><path class="spark-area" d="${line} L ${width} ${height} L 0 ${height} Z"/><path class="spark-line" d="${line}"/>${values.map((value, index) => `<circle cx="${(index * width / Math.max(values.length - 1, 1)).toFixed(1)}" cy="${(height - 3 - (value - min) / span * 38).toFixed(1)}" r="2.5"><title>${safeLabel}: ${value}</title></circle>`).join("")}</svg>`;
+}
+export function renderLineChartSvg(rows: UsageMetricBucket[], metric: "costUsd" | "totalTokens" | "sessionCount" = "costUsd", width = 880): string {
+  if (!rows.length) return '<p class="empty">No usage in this range</p>';
+  if (rows.length === 1) {
+    const row = rows[0];
+    const raw = row[metric] ?? 0;
+    const masked = metric === "costUsd" ? formatUsd(raw) : formatCompact(raw);
+    const center = width / 2;
+    return `<div class="single-day-chart"><svg class="line-chart" width="${width}" height="248" viewBox="0 0 ${width} 248" role="img" aria-label="${metric} over time"><circle class="chart-point" cx="${center}" cy="124" r="4"><title>${escapeHtml(row.label ?? row.key)}: ${masked}</title></circle><text class="axis" x="${center}" y="110" text-anchor="middle" title="${raw}">${masked}</text></svg><p class="single-day-caption">Single day. Pick a longer range for a trend.</p></div>`;
+  }
+  const height = 248, right = 14, top = 12, bottom = 30;
+  const values = rows.map((row) => row[metric] ?? 0), max = Math.max(...values, 1);
+  const longestTick = Math.max(...[0, .25, .5, .75, 1].map((part) => formatAxisTick(max * part, metric === "costUsd").length));
+  const left = Math.max(width < 500 ? 52 : 66, Math.ceil(longestTick * 6.7 + 8));
+  const x = (index: number) => left + index * (width - left - right) / Math.max(values.length - 1, 1);
+  const y = (value: number) => top + (height - top - bottom) * (1 - value / max);
+  const path = values.map((value, index) => `${index ? "L" : "M"}${x(index)} ${y(value)}`).join(" ");
+  const area = `${path} L ${x(values.length - 1)} ${height - bottom} L ${left} ${height - bottom} Z`;
+  const grid = [0, .25, .5, .75, 1].map((part) => {
+    const yy = y(max * part);
+    return `<line class="gridline" x1="${left}" y1="${yy}" x2="${width - right}" y2="${yy}"/><text class="axis" x="${left - 8}" y="${yy + 3}" text-anchor="end" title="${max * part}">${formatAxisTick(max * part, metric === "costUsd")}</text>`;
+  }).join("");
+  const points = rows.map((row, index) => `<circle class="chart-point" data-index="${index}" cx="${x(index)}" cy="${y(values[index])}" r="4" tabindex="0"><title>${escapeHtml(row.label ?? row.key)}: ${values[index]}</title></circle>`).join("");
+  const labels = rows.filter((_, index) => index % Math.max(1, Math.ceil(rows.length / 7)) === 0 || index === rows.length - 1).map((row) => {
+    const index = rows.indexOf(row);
+    const anchor = index === 0 && index !== rows.length - 1 ? "start" : index === rows.length - 1 && index !== 0 ? "end" : "middle";
+    return `<text class="axis" x="${x(index)}" y="${height - 7}" text-anchor="${anchor}" title="${escapeHtml(row.label ?? row.key)}">${escapeHtml(row.key.slice(5))}</text>`;
+  }).join("");
+  return `<svg class="line-chart" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="${metric} over time"><defs><linearGradient id="chart-fill" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#3b82f6" stop-opacity=".2"/><stop offset="1" stop-color="#3b82f6" stop-opacity="0"/></linearGradient></defs>${grid}${labels}<path class="chart-area" d="${area}"/><path class="chart-line" d="${path}"/><line class="chart-crosshair" data-crosshair x1="0" y1="${top}" x2="0" y2="${height - bottom}" visibility="hidden"/>${points}</svg>`;
+}
+
+export function createUsageChartView(initialSeries: "costUsd" | "totalTokens" | "sessionCount" = "costUsd") {
+  let series = initialSeries;
+  return {
+    getSeries: () => series,
+    select: (next: "costUsd" | "totalTokens" | "sessionCount") => { series = next; },
+    render: (rows: UsageMetricBucket[], width: number) => renderLineChartSvg(rows, series, width),
+  };
+}
+
+export function formatChartTooltip(row: UsageMetricBucket, series: "costUsd" | "totalTokens" | "sessionCount"): { text: string; title: string } {
+  const value = row[series] ?? 0;
+  return {
+    text: `${row.label ?? row.key} · ${series === "costUsd" ? formatUsd(value) : formatCompact(value)}`,
+    title: String(value),
+  };
+}
+
+export function attachChartInteractions(wrapper: UsagePageElement, rows: UsageMetricBucket[], series: "costUsd" | "totalTokens" | "sessionCount"): void {
+  const points = wrapper.querySelectorAll(".chart-point");
+  const crosshair = wrapper.querySelector("[data-crosshair]");
+  const tooltip = wrapper.querySelector("[data-chart-tooltip]");
+  if (!points.length || !crosshair || !tooltip) return;
+  const show = (event: UsagePageEvent) => {
+    const bounds = wrapper.getBoundingClientRect();
+    const x = Math.min(bounds.width, Math.max(0, (event.clientX ?? bounds.left) - bounds.left));
+    const nearest = points.reduce((best, point) => {
+      const pointX = Number(point.getAttribute("cx") ?? 0);
+      return Math.abs(pointX - x) < Math.abs(Number(best.getAttribute("cx") ?? 0) - x) ? point : best;
+    }, points[0]);
+    const index = Number(nearest.getAttribute("data-index") ?? 0);
+    const pointX = Number(nearest.getAttribute("cx") ?? 0);
+    const row = rows[index];
+    if (!row) return;
+    const formatted = formatChartTooltip(row, series);
+    crosshair.setAttribute("x1", String(pointX));
+    crosshair.setAttribute("x2", String(pointX));
+    crosshair.setAttribute("visibility", "visible");
+    tooltip.textContent = formatted.text;
+    tooltip.setAttribute("title", formatted.title);
+    tooltip.hidden = false;
+    tooltip.style.left = `${Math.min(bounds.width - 170, Math.max(0, pointX))}px`;
+    tooltip.style.top = `${Math.max(0, (event.clientY ?? bounds.top) - bounds.top - 38)}px`;
+  };
+  wrapper.addEventListener("pointermove", show);
+  wrapper.addEventListener("pointerdown", show);
+  wrapper.addEventListener("pointerleave", () => { crosshair.setAttribute("visibility", "hidden"); tooltip.hidden = true; });
+}
+
 export function toUsagePageData(result: UsageQueryResult): UsagePageData {
   return {
-    range: { ...result.range },
-    totals: {
-      sessionCount: result.totals.sessionCount,
-      activeSessionCount: result.totals.activeSessionCount,
-      completedSessionCount: result.totals.completedSessionCount,
-      failedSessionCount: result.totals.failedSessionCount,
-      inputTokens: result.totals.inputTokens,
-      outputTokens: result.totals.outputTokens,
-      cachedTokens: result.totals.cachedTokens,
-      totalTokens: result.totals.totalTokens,
-      costUsd: result.totals.costUsd,
-      costComplete: result.totals.costComplete,
-      sessionsWithoutCost: result.totals.sessionsWithoutCost,
-    },
-    byDay: [...result.byDay],
-    byRepository: [...result.byRepository],
-    byModel: [...result.byModel],
-    byAgent: [...result.byAgent],
-    byRun: [...result.byRun],
-    byOrigin: [...(result.byOrigin ?? [])],
+    range: { ...result.range }, totals: { ...result.totals }, byDay: [...result.byDay],
+    byRepository: [...result.byRepository], byModel: [...result.byModel], byAgent: [...result.byAgent],
+    byRun: [...result.byRun], byOrigin: [...(result.byOrigin ?? [])],
   };
 }
 
@@ -131,302 +271,350 @@ export function createUsagePageController(options: UsagePageControllerOptions):
   const state: UsagePageState = {
     filters: {
       period: options.initialFilters?.period ?? (options.initialFilters?.since ? "" : "today"),
-      repo: options.initialFilters?.repo ?? "",
-      model: options.initialFilters?.model ?? "",
-      agent: options.initialFilters?.agent ?? "",
-      since: options.initialFilters?.since ?? "",
-      until: options.initialFilters?.until ?? "",
-    },
-    result: null,
-    error: undefined,
-    loading: false,
-    selectedBreakdown: breakdowns.includes(options.initialBy as UsageBreakdown)
-      ? options.initialBy as UsageBreakdown
-      : "day",
-    breakdowns,
-    intervalSeconds: normalizeUsageInterval(options.interval),
+      repo: options.initialFilters?.repo ?? "", model: options.initialFilters?.model ?? "", agent: options.initialFilters?.agent ?? "",
+      since: options.initialFilters?.since ?? "", until: options.initialFilters?.until ?? "",
+    }, result: null, previous: null, error: undefined, loading: false,
+    selectedBreakdown: breakdowns.includes(options.initialBy as UsageBreakdown) ? options.initialBy as UsageBreakdown : "day",
+    breakdowns, intervalSeconds: normalizeUsageInterval(options.interval),
   };
   let timer: unknown;
   let started = false;
-
-  function getState(): UsagePageState {
-    return {
-      ...state,
-      filters: { ...state.filters },
-      breakdowns: [...state.breakdowns],
-    };
-  }
-
-  function publish(): void {
-    options.render(getState());
-  }
-
-  async function refresh(): Promise<UsagePageState> {
-    state.loading = true;
+  let hasLoaded = false;
+  let requestSequence = 0;
+  const snapshot = (): UsagePageState => ({ ...state, filters: { ...state.filters }, breakdowns: [...state.breakdowns] });
+  const publish = () => options.render(snapshot());
+  const query = async (url: string): Promise<UsagePageData> => {
+    const response = await options.fetch(url);
+    let payload: unknown;
+    try { payload = await response.json(); } catch { payload = undefined; }
+    if (!response.ok) {
+      const message = payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string"
+        ? payload.error : `Usage query failed with HTTP ${response.status ?? 500}`;
+      throw new Error(message);
+    }
+    return toUsagePageData(payload as UsageQueryResult);
+  };
+  const updateUrl = () => options.replaceUrl?.(buildUsagePageSearch({ filters: state.filters, by: state.selectedBreakdown }));
+  async function refresh(userInitiated = true): Promise<UsagePageState> {
+    const sequence = ++requestSequence;
+    state.loading = userInitiated;
     publish();
     try {
-      const response = await options.fetch(buildUsageApiUrl(state.filters));
-      let payload: unknown;
-      try {
-        payload = await response.json();
-      } catch {
-        payload = undefined;
-      }
-      if (!response.ok) {
-        const message =
-          payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string"
-            ? payload.error
-            : `Usage query failed with HTTP ${response.status ?? 500}`;
-        throw new Error(message);
-      }
-      state.result = toUsagePageData(payload as UsageQueryResult);
+      const result = await query(buildUsageApiUrl(state.filters));
+      if (sequence !== requestSequence) return snapshot();
+      state.result = result;
       state.error = undefined;
+      hasLoaded = true;
+      const previous = previousWindow(state.filters.period, new Date(result.range.until));
+      const previousResult = previous ? await query(buildUsageApiUrl({ ...state.filters, period: "", ...previous })) : null;
+      if (sequence !== requestSequence) return snapshot();
+      state.previous = previousResult;
     } catch (error) {
+      if (sequence !== requestSequence) return snapshot();
       state.error = error instanceof Error ? error.message : String(error);
     } finally {
-      state.loading = false;
-      publish();
+      if (sequence === requestSequence) {
+        state.loading = false;
+        publish();
+      }
     }
-    return getState();
+    return snapshot();
   }
-
   async function setFilter(name: keyof UsagePageFilters, value: string): Promise<UsagePageState> {
-    if (!(name in state.filters)) return getState();
-    const nextValue = String(value);
-    if (state.filters[name] === nextValue) return getState();
-    state.filters[name] = nextValue;
-    return refresh();
+    return setFilters({ [name]: String(value) });
+  }
+  async function setFilters(values: Partial<UsagePageFilters>): Promise<UsagePageState> {
+    let changed = false;
+    for (const name of Object.keys(values) as (keyof UsagePageFilters)[]) {
+      if (!(name in state.filters) || state.filters[name] === String(values[name] ?? "")) continue;
+      state.filters[name] = String(values[name] ?? "");
+      changed = true;
+    }
+    if (!changed) return snapshot();
+    updateUrl();
+    return refresh(true);
   }
-
   function setBreakdown(name: UsageBreakdown): void {
-    if (!state.breakdowns.includes(name)) return;
+    if (!breakdowns.includes(name)) return;
     state.selectedBreakdown = name;
+    updateUrl();
     publish();
   }
-
   async function start(): Promise<void> {
     if (started) return;
     started = true;
-    await refresh();
-    timer = options.setInterval(() => {
-      void refresh();
-    }, state.intervalSeconds * 1000);
+    await refresh(true);
+    timer = options.setInterval(() => { void refresh(false); }, state.intervalSeconds * 1000);
   }
-
   function stop(): void {
     if (!started) return;
     started = false;
     options.clearInterval(timer);
     timer = undefined;
   }
-
-  return { getState, refresh, setFilter, setBreakdown, start, stop };
-}
-
-export function renderUsagePageState(root: UsagePageElement, state: UsagePageState, document: UsagePageDocument): void {
-  const error = root.querySelector("[data-error]");
-  if (error) {
-    error.hidden = !state.error;
-    error.textContent = state.error ?? "";
-  }
-
-  const loading = root.querySelector("[data-loading]");
-  if (loading) loading.textContent = state.loading ? "Updating usage..." : "";
-
-  for (const button of root.querySelectorAll("[data-breakdown]")) {
-    button.setAttribute("aria-pressed", String(button.dataset.breakdown === state.selectedBreakdown));
-  }
-
-  const totalsRoot = root.querySelector("[data-totals]");
-  const breakdownRoot = root.querySelector("[data-breakdowns]");
-  totalsRoot?.replaceChildren();
-  breakdownRoot?.replaceChildren();
-  if (!state.result) return;
-
-  const totalLabels: Record<keyof UsageQueryResult["totals"], string> = {
-    sessionCount: "Sessions",
-    activeSessionCount: "Active sessions",
-    completedSessionCount: "Completed sessions",
-    failedSessionCount: "Failed sessions",
-    inputTokens: "Input tokens",
-    outputTokens: "Output tokens",
-    cachedTokens: "Cached tokens",
-    totalTokens: "Total tokens",
-    costUsd: "Cost (USD)",
-    costComplete: "Cost complete",
-    sessionsWithoutCost: "Sessions without cost",
-  };
-  for (const [name, label] of Object.entries(totalLabels) as [keyof UsageQueryResult["totals"], string][]) {
-    const card = document.createElement("article");
-    card.className = "usage-total";
-    const heading = document.createElement("h3");
-    heading.textContent = label;
-    const value = document.createElement("p");
-    const rawValue = state.result.totals[name];
-    value.textContent = name === "costUsd"
-      ? `$${Number(rawValue).toFixed(2)}${state.result.totals.costComplete ? "" : "?"}`
-      : name === "costComplete"
-        ? rawValue ? "Complete" : "Incomplete"
-        : String(rawValue);
-    card.append(heading, value);
-    totalsRoot?.append(card);
-  }
-
-  const groups: [UsageBreakdown, string, UsageMetricBucket[]][] = [
-    ["day", "By day", state.result.byDay],
-    ["repo", "By repository", state.result.byRepository],
-    ["model", "By model", state.result.byModel],
-    ["agent", "By agent", state.result.byAgent],
-    ["run", "By run", state.result.byRun],
-    ["origin", "By origin", state.result.byOrigin],
-  ];
-  for (const [name, title, buckets] of groups) {
-    const section = document.createElement("section");
-    section.className = name === state.selectedBreakdown ? "usage-breakdown selected" : "usage-breakdown";
-    section.dataset.breakdownSection = name;
-    const heading = document.createElement("h2");
-    heading.textContent = title;
-    section.append(heading);
-    if (buckets.length === 0) {
-      const empty = document.createElement("p");
-      empty.className = "empty";
-      empty.textContent = "No usage recorded.";
-      section.append(empty);
-    }
-    for (const bucket of buckets) {
-      const row = document.createElement("article");
-      row.className = "usage-bucket";
-      const label = document.createElement("strong");
-      label.textContent = bucket.label ?? bucket.key;
-      const metrics = document.createElement("span");
-      const cost = `$${bucket.costUsd.toFixed(2)}${bucket.costComplete ? "" : "?"}`;
-      metrics.textContent = `${bucket.sessionCount} sessions · ${bucket.inputTokens} input · ${bucket.outputTokens} output · ${bucket.cachedTokens} cached · ${cost}`;
-      row.append(label, metrics);
-      section.append(row);
-    }
-    breakdownRoot?.append(section);
-  }
+  return { getState: snapshot, refresh, setFilter, setFilters, setBreakdown, start, stop };
 }
 
 export function startUsagePage(options: UsagePageOptions, environment: UsagePageEnvironment): UsagePageController | undefined {
   const root = environment.document.getElementById("usage-root");
-  if (!root) return undefined;
-
-  for (const control of root.querySelectorAll("[data-filter]")) {
-    const name = control.dataset.filter as keyof UsagePageFilters | undefined;
-    if (name && options.filters?.[name] !== undefined) control.value = options.filters[name] ?? "";
+  if (!root) return;
+  const params = new URLSearchParams(environment.location?.search ?? "");
+  const filters = { ...options.filters };
+  for (const key of ["period", "repo", "model", "agent", "since", "until"] as const) {
+    if (params.has(key)) filters[key] = params.get(key) ?? "";
   }
-
+  const requestedBy = params.get("by") as UsageBreakdown | null;
+  const initialBy = requestedBy ?? options.by;
+  const tableView = { sortKey: "costUsd", direction: -1, expanded: false, search: "" };
+  const chartView = createUsageChartView();
+  let resizeTimer: unknown;
   const controller = createUsagePageController({
-    initialFilters: options.filters,
-    initialBy: options.by,
-    interval: options.interval,
-    fetch: environment.fetch,
-    setInterval: environment.setInterval,
-    clearInterval: environment.clearInterval,
-    render: (state) => renderUsagePageState(root, state, environment.document),
+    initialFilters: filters, initialBy, interval: options.interval,
+    fetch: environment.fetch, setInterval: environment.setInterval, clearInterval: environment.clearInterval,
+    replaceUrl: environment.replaceUrl,
+    render: (state) => renderUsageDashboard(root, state, environment.document, controller, tableView, chartView),
+  });
+  environment.window?.addEventListener("resize", () => {
+    if (resizeTimer !== undefined) environment.clearTimeout?.(resizeTimer);
+    resizeTimer = environment.setTimeout?.(() => {
+      renderActiveUsageChart(root, controller.getState(), chartView);
+      resizeTimer = undefined;
+    }, 150);
+  });
+  const range = root.querySelector("[data-range]");
+  if (range) range.value = controller.getState().filters.period;
+  for (const name of ["since", "until"] as const) {
+    const input = root.querySelector(`[data-filter="${name}"]`);
+    if (input) input.value = controller.getState().filters[name];
+  }
+  const dateFields = root.querySelectorAll("[data-date-field]");
+  for (const field of dateFields) field.hidden = Boolean(controller.getState().filters.period);
+  range?.addEventListener("change", (event) => {
+    const value = event.target?.value ?? "";
+    for (const field of dateFields) field.hidden = Boolean(value);
+    void controller.setFilters(value ? { period: value, since: "", until: "" } : { period: value });
   });
-
   root.addEventListener("change", (event) => {
     const target = event.target ?? null;
     const name = target?.dataset.filter as keyof UsagePageFilters | undefined;
-    if (target && name) void controller.setFilter(name, target.value);
+    if (name) void controller.setFilter(name, target?.value ?? "");
   });
-  root.addEventListener("click", (event) => {
-    const target = event.target ?? null;
-    const button = target?.closest("[data-breakdown]");
-    const name = button?.dataset.breakdown as UsageBreakdown | undefined;
-    if (name) controller.setBreakdown(name);
+  root.querySelector("[data-add-filter]")?.addEventListener("click", () => {
+    const menu = root.querySelector("[data-filter-menu]");
+    if (menu) menu.hidden = !menu.hidden;
+  });
+  for (const button of root.querySelectorAll("[data-filter-kind]")) button.addEventListener("click", () => {
+    const kind = button.dataset.filterKind as "repo" | "model" | "agent" | undefined;
+    const menu = root.querySelector("[data-filter-menu]");
+    const result = controller.getState().result;
+    if (!kind || !menu || !result) return;
+    const groups = { repo: result.byRepository, model: result.byModel, agent: result.byAgent };
+    const field = environment.document.createElement("select");
+    field.dataset.filterChoice = kind;
+    field.innerHTML = renderUsageFilterOptions(groups[kind], kind);
+    menu.replaceChildren(field);
+    field.addEventListener("change", (event) => {
+      const value = event.target?.value ?? "";
+      if (value) void controller.setFilter(kind, value);
+      menu.hidden = true;
+    });
+  });
+  root.querySelector("[data-live]")?.addEventListener("click", (event) => {
+    const target = event.target?.closest("[data-live]");
+    if (!target) return;
+    target.className = target.className.includes(" on") ? "live" : "live on";
+    if (target.className.includes(" on")) void controller.start();
+    else controller.stop();
+  });
+  root.querySelector("[data-dismiss-error]")?.addEventListener("click", () => {
+    const banner = root.querySelector("[data-error]");
+    if (banner) banner.hidden = true;
+  });
+  root.querySelector("[data-copy]")?.addEventListener("click", () => {
+    environment.copyToClipboard?.(environment.location?.href ?? "");
+  });
+  root.querySelector("[data-export]")?.addEventListener("click", () => {
+    const result = controller.getState().result;
+    if (!result) return;
+    const rows = selectedRows(result, controller.getState().selectedBreakdown);
+    const csv = ["name,sessions,spend,tokens", ...rows.map((row) => [csvQuote(row.label ?? row.key), row.sessionCount, row.costUsd, row.totalTokens].join(","))].join("\n");
+    const anchor = environment.document.createElement("a");
+    anchor.setAttribute("href", `data:text/csv;charset=utf-8,${encodeURIComponent(csv)}`);
+    anchor.setAttribute("download", `usage-${controller.getState().filters.period}.csv`);
+    anchor.click();
+  });
+  environment.document.addEventListener("keydown", (event) => {
+    if (event.key === "/" && !["INPUT", "TEXTAREA"].includes(environment.document.activeElement?.tagName ?? "")) {
+      event.preventDefault?.();
+      root.querySelector("[data-search]")?.focus();
+    }
   });
   void controller.start();
   return controller;
 }
 
+export function filterAndSortUsageRows(rows: UsageMetricBucket[], search: string, sortKey: string, direction: number): UsageMetricBucket[] {
+  const matches = rows.filter((row) => (row.label ?? row.key).toLowerCase().includes(search.toLowerCase()));
+  const key = sortKey === "share" ? "costUsd" : sortKey;
+  return matches.sort((left, right) => {
+    const first = key === "key" ? left.label ?? left.key : left[key as keyof UsageMetricBucket];
+    const second = key === "key" ? right.label ?? right.key : right[key as keyof UsageMetricBucket];
+    return (typeof first === "number" && typeof second === "number" ? first - second : String(first).localeCompare(String(second))) * direction;
+  });
+}
+
+export interface UsageSearchFocus { focused: boolean; value?: string; selectionStart?: number | null; selectionEnd?: number | null; }
+export function captureUsageSearchFocus(document: UsagePageDocument, input: UsagePageElement | null): UsageSearchFocus {
+  if (!input || document.activeElement !== input) return { focused: false };
+  return { focused: true, value: input.value, selectionStart: input.selectionStart, selectionEnd: input.selectionEnd };
+}
+export function restoreUsageSearchFocus(input: UsagePageElement | null, focus: UsageSearchFocus): void {
+  if (!input || !focus.focused) return;
+  if (focus.value !== undefined) input.value = focus.value;
+  input.focus();
+  if (focus.selectionStart != null && focus.selectionEnd != null) input.setSelectionRange?.(focus.selectionStart, focus.selectionEnd);
+}
+
+export function csvQuote(value: string): string { return `"${value.replaceAll('"', '""')}"`; }
+export function renderUsageFilterOptions(rows: UsageMetricBucket[], kind: "repo" | "model" | "agent"): string {
+  return `<option value="">Select ${kind}</option>${rows.map((row) => `<option value="${escapeHtml(row.key)}">${escapeHtml(row.label ?? row.key)}</option>`).join("")}`;
+}
+export function renderUsageTableRows(rows: UsageMetricBucket[], tableSpend: number, expanded: boolean): string {
+  return rows.map((row, index) => {
+    const label = row.label ?? row.key;
+    const share = tableSpend ? row.costUsd / tableSpend * 100 : 0;
+    return `<tr${index >= 10 && !expanded ? " hidden" : ""}><td title="${escapeHtml(label)}">${escapeHtml(label)}</td><td title="${row.sessionCount}">${formatCompact(row.sessionCount)}</td><td title="${row.costUsd}">${row.costComplete ? "" : "≥ "}${formatUsd(row.costUsd)}</td><td title="${row.totalTokens}">${formatCompact(row.totalTokens)}</td><td title="${share}"><span class="share"><i style="width:${share}%"></i></span>${formatShare(share, "spend")}</td></tr>`;
+  }).join("");
+}
+
+function renderUsageDashboard(
+  root: UsagePageElement,
+  state: UsagePageState,
+  document: UsagePageDocument,
+  controller: UsagePageController,
+  tableView: { sortKey: string; direction: number; expanded: boolean; search: string },
+  chartView: ReturnType<typeof createUsageChartView>,
+): void {
+  const loading = root.querySelector("[data-loading]");
+  if (loading) { loading.textContent = state.loading ? "Loading usage…" : ""; loading.hidden = !state.loading; }
+  const error = root.querySelector("[data-error]");
+  if (error) {
+    error.hidden = !state.error;
+    const message = error.querySelector("span");
+    if (message) message.textContent = state.error ?? "";
+  }
+  const content = root.querySelector("[data-dashboard]");
+  if (!content) return;
+  const priorSearch = content.querySelector("[data-search]");
+  const focus = captureUsageSearchFocus(document, priorSearch);
+  for (const button of root.querySelectorAll("[data-breakdown]")) button.setAttribute("aria-pressed", String(button.dataset.breakdown === state.selectedBreakdown));
+  if (!state.result) return;
+  const data = state.result;
+  const rows = data.byDay;
+  const totals = data.totals;
+  const chips = root.querySelector("[data-chips]");
+  if (chips) {
+    const activeFilters = (["repo", "model", "agent"] as const).filter((name) => state.filters[name]);
+    chips.innerHTML = activeFilters.map((name) => `<span class="filter-chip">${name}: ${escapeHtml(state.filters[name])}<button data-remove-filter="${name}" aria-label="Remove ${name} filter">×</button></span>`).join("");
+    chips.querySelectorAll("[data-remove-filter]").forEach((button) => button.addEventListener("click", () => {
+      void controller.setFilter(button.dataset.removeFilter as "repo" | "model" | "agent", "");
+    }));
+  }
+  const cache = totals.cachedTokens / (totals.inputTokens + totals.cachedTokens || 1) * 100;
+  const kpis = [
+    ["Spend", formatCost(totals.costUsd, totals.costComplete, totals.sessionsWithoutCost), totals.costUsd, "spend"],
+    ["Sessions", escapeHtml(formatCompact(totals.sessionCount)), totals.sessionCount, "sessions"],
+    ["Total tokens", escapeHtml(formatCompact(totals.totalTokens)), totals.totalTokens, "tokens"],
+    ["Cache hit rate", `${cache.toFixed(1)}%`, cache, "cache"],
+  ] as const;
+  const previous = state.previous?.totals;
+  const periodLabel = state.filters.period;
+  const kpiHtml = kpis.map(([label, value, current, key], index) => {
+    const previousValue = key === "spend" ? previous?.costUsd : key === "sessions" ? previous?.sessionCount : key === "tokens" ? previous?.totalTokens : previous ? previous.cachedTokens / (previous.inputTokens + previous.cachedTokens || 1) * 100 : undefined;
+    const delta = previousValue === undefined ? undefined : computeDelta(current, previousValue, periodLabel);
+    const deltaHtml = delta ? `<p class="delta">${delta.direction === "up" ? "↗" : "↘"} ${delta.percent.toFixed(1)}% <span>vs previous ${periodLabel}</span></p>` : "";
+    const raw = key === "spend" ? formatUsd(current) : key === "cache" ? `${current.toFixed(2)}%` : new Intl.NumberFormat("en-US").format(current);
+    return `<article class="card kpi"><div class="kpi-heading">${label}<span class="range-tag">${escapeHtml(periodLabel || "custom")}</span></div><strong class="kpi-value" title="${raw}">${value}</strong>${deltaHtml}${key === "cache" ? '<span class="kpi-note">Share of input + cached tokens</span>' : ""}${renderSparklineSvg(rows.map((row) => key === "spend" ? row.costUsd : key === "sessions" ? row.sessionCount : key === "tokens" ? row.totalTokens : row.cachedTokens / (row.inputTokens + row.cachedTokens || 1) * 100), label)}</article>`;
+  }).join("");
+  const modelLegend = renderModelLegend(data.byModel);
+  const repoMax = Math.max(...data.byRepository.map((row) => row.costUsd), 1);
+  const repoRows = [...data.byRepository].sort((a, b) => b.costUsd - a.costUsd).map((row) => `<div class="rank-row" title="${escapeHtml(row.label ?? row.key)}: ${formatUsd(row.costUsd)}"><span>${escapeHtml(row.label ?? row.key)}</span><i><b style="width:${row.costUsd / repoMax * 100}%"></b></i><strong>${formatUsd(row.costUsd)}</strong></div>`).join("") || '<p class="empty">No usage in this range</p>';
+  const outcomes = [["Completed", totals.completedSessionCount, "#3b82f6"], ["Failed", totals.failedSessionCount, "#e5484d"], ["Active", totals.activeSessionCount, "#93c5fd"], ["Other", Math.max(0, totals.sessionCount - totals.completedSessionCount - totals.failedSessionCount - totals.activeSessionCount), "#404040"]] as const;
+  const outcomeBar = outcomes.map(([name, count, color]) => `<i style="width:${totals.sessionCount ? count / totals.sessionCount * 100 : 0}%;background:${color}" title="${name}: ${formatCompact(count)}, ${formatShare(totals.sessionCount ? count / totals.sessionCount * 100 : 0, "sessions")}"></i>`).join("");
+  const outcomeLegend = outcomes.map(([name, count]) => { const share = totals.sessionCount ? count / totals.sessionCount * 100 : 0; return `<div><span>${name}</span><strong title="${count}">${formatCompact(count)}</strong><small title="${share}">${formatShare(share, "sessions")}</small></div>`; }).join("");
+  const harness = data.byAgent.map((row) => { const spendShare = totals.costUsd ? row.costUsd / totals.costUsd * 100 : 0; const sessionShare = totals.sessionCount ? row.sessionCount / totals.sessionCount * 100 : 0; return `<div class="harness-row"><strong>${escapeHtml(row.label ?? row.key)}</strong><span class="track"><i style="width:${spendShare}%"></i></span><small title="${spendShare}">${formatShare(spendShare, "spend")}</small><span class="track"><i style="width:${sessionShare}%"></i></span><small title="${sessionShare}">${formatShare(sessionShare, "sessions")}</small></div>`; }).join("") || '<p class="empty">No usage in this range</p>';
+  const origins = data.byOrigin.map((row) => { const sessionShare = totals.sessionCount ? row.sessionCount / totals.sessionCount * 100 : 0; const spendShare = totals.costUsd ? row.costUsd / totals.costUsd * 100 : 0; return `<div class="origin-row"><strong>${escapeHtml(row.label ?? row.key)}</strong><span title="${sessionShare}">${formatShare(sessionShare, "sessions")}</span><span title="${spendShare}">${formatShare(spendShare, "spend")}</span></div>`; }).join("") || '<p class="empty">No usage in this range</p>';
+  const sourceRows = selectedRows(data, state.selectedBreakdown);
+  const tableSpend = sourceRows.reduce((sum, row) => sum + row.costUsd, 0);
+  const allRows = filterAndSortUsageRows(sourceRows, tableView.search, tableView.sortKey, tableView.direction);
+  const table = allRows.length ? `<div class="table-scroll"><table><thead><tr><th><button data-sort="key">Name${tableView.sortKey === "key" ? (tableView.direction < 0 ? " ↓" : " ↑") : ""}</button></th><th><button data-sort="sessionCount">Sessions${tableView.sortKey === "sessionCount" ? (tableView.direction < 0 ? " ↓" : " ↑") : ""}</button></th><th><button data-sort="costUsd">Spend${tableView.sortKey === "costUsd" ? (tableView.direction < 0 ? " ↓" : " ↑") : ""}</button></th><th><button data-sort="totalTokens">Tokens${tableView.sortKey === "totalTokens" ? (tableView.direction < 0 ? " ↓" : " ↑") : ""}</button></th><th><button data-sort="share">Share of spend${tableView.sortKey === "share" ? (tableView.direction < 0 ? " ↓" : " ↑") : ""}</button></th></tr></thead><tbody>${renderUsageTableRows(allRows, tableSpend, tableView.expanded)}</tbody></table></div>` : '<p class="empty">No usage in this range</p>';
+  content.innerHTML = `<section class="kpis">${kpiHtml}</section><section class="card chart-card"><div class="card-heading"><h2>Spend over time</h2><div class="series-switch">${(["costUsd", "totalTokens", "sessionCount"] as const).map((series) => `<button data-series="${series}" aria-pressed="${chartView.getSeries() === series}">${series === "costUsd" ? "Spend" : series === "totalTokens" ? "Tokens" : "Sessions"}</button>`).join("")}</div></div><div class="chart-wrap"><div data-chart-svg>${renderLineChartSvg(rows, chartView.getSeries(), 880)}</div><div class="chart-tooltip" data-chart-tooltip hidden></div></div></section><section class="two-col"><article class="card"><div class="card-heading"><h2>Spend by model</h2><span>${escapeHtml(periodLabel || "custom")}</span></div><div class="donut-layout">${renderDonutSvg(data.byModel)}<div class="model-legend">${modelLegend}</div></div></article><article class="card"><div class="card-heading"><h2>Spend by repository</h2><span>${escapeHtml(periodLabel || "custom")}</span></div><div class="rank-list">${repoRows}</div></article></section><section class="three-col"><article class="card"><div class="card-heading"><h2>Sessions by outcome</h2></div><div class="outcome-bar">${outcomeBar}</div><div class="outcome-legend">${outcomeLegend}</div></article><article class="card"><div class="card-heading"><h2>Harness</h2><span>Spend and sessions</span></div><div class="harness-list">${harness}</div></article><article class="card"><div class="card-heading"><h2>Origin</h2><span>Worker and orchestrator</span></div><div class="origin-list">${origins}</div></article></section><section class="card table-card"><div class="card-heading"><h2>Breakdown</h2><input data-search type="search" placeholder="Search rows" aria-label="Search rows" value="${escapeHtml(tableView.search)}"></div><nav class="tabs" aria-label="Usage breakdowns">${state.breakdowns.map((name) => `<button data-breakdown="${name}" aria-pressed="${name === state.selectedBreakdown}">${name === "repo" ? "Repository" : name[0].toUpperCase() + name.slice(1)}</button>`).join("")}</nav>${allRows.length > 10 ? `<button class="show-all" data-show-all>${tableView.expanded ? "Show top 10" : `Show all ${allRows.length}`}</button>` : ""}${table}</section>`;
+  restoreUsageSearchFocus(content.querySelector("[data-search]"), focus);
+  renderActiveUsageChart(root, state, chartView);
+  content.querySelectorAll("[data-breakdown]").forEach((button) => button.addEventListener("click", () => controller.setBreakdown(button.dataset.breakdown as UsageBreakdown)));
+  content.querySelectorAll("[data-series]").forEach((button) => button.addEventListener("click", () => {
+    chartView.select(button.dataset.series as "costUsd" | "totalTokens" | "sessionCount");
+    renderActiveUsageChart(root, state, chartView);
+    content.querySelectorAll("[data-series]").forEach((seriesButton) => seriesButton.setAttribute("aria-pressed", String(seriesButton.dataset.series === chartView.getSeries())));
+  }));
+  const search = content.querySelector("[data-search]");
+  search?.addEventListener("input", () => {
+    tableView.search = search.value ?? "";
+    renderUsageDashboard(root, state, document, controller, tableView, chartView);
+  });
+  content.querySelectorAll("[data-sort]").forEach((button) => button.addEventListener("click", () => {
+    const key = button.dataset.sort ?? "costUsd";
+    tableView.direction = tableView.sortKey === key ? tableView.direction * -1 : -1;
+    tableView.sortKey = key;
+    renderUsageDashboard(root, state, document, controller, tableView, chartView);
+  }));
+  content.querySelector("[data-show-all]")?.addEventListener("click", () => {
+    tableView.expanded = !tableView.expanded;
+    renderUsageDashboard(root, state, document, controller, tableView, chartView);
+  });
+}
+
+function renderActiveUsageChart(root: UsagePageElement, state: UsagePageState, chartView: ReturnType<typeof createUsageChartView>): void {
+  const wrapper = root.querySelector(".chart-wrap");
+  const target = wrapper?.querySelector("[data-chart-svg]");
+  if (!wrapper || !target || !state.result) return;
+  const width = wrapper.clientWidth || 880;
+  target.innerHTML = chartView.render(state.result.byDay, width);
+  attachChartInteractions(wrapper, state.result.byDay, chartView.getSeries());
+}
+
+function selectedRows(data: UsagePageData, by: UsageBreakdown): UsageMetricBucket[] {
+  const groups: Record<UsageBreakdown, UsageMetricBucket[]> = { day: data.byDay, repo: data.byRepository, model: data.byModel, agent: data.byAgent, run: data.byRun, origin: data.byOrigin };
+  return [...groups[by]].sort((a, b) => b.costUsd - a.costUsd);
+}
+function escapeHtml(value: string): string { return value.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char] ?? char); }
+
 export function renderUsagePage(options: UsagePageOptions = {}): string {
-  const pageOptions = {
-    by: options.by ?? "day",
-    interval: options.interval ?? 2,
-    filters: options.filters ?? {},
-  };
+  const pageOptions = { by: options.by ?? "day", interval: options.interval ?? 2, filters: options.filters ?? {} };
   const serializedOptions = JSON.stringify(pageOptions).replaceAll("<", "\\u003c");
-  const behaviorSource = [
-    normalizeUsageInterval,
-    buildUsageApiUrl,
-    toUsagePageData,
-    createUsagePageController,
-    renderUsagePageState,
-    startUsagePage,
-  ].map((behavior) => Function.prototype.toString.call(behavior)).join("\n\n");
-
-  return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>CodeDeck usage</title>
-<link rel="icon" href="data:,">
-<style>
-  :root { color-scheme: dark; font-family: system-ui, sans-serif; background: #0b0d12; color: #edf0f5; }
-  * { box-sizing: border-box; }
-  body { margin: 0; }
-  header { padding: 24px clamp(18px, 4vw, 48px); border-bottom: 1px solid #252a34; background: #11151d; }
-  header h1 { margin: 0 0 5px; font-size: 24px; }
-  header p { margin: 0; color: #9ba5b4; font-size: 13px; }
-  main { max-width: 1440px; margin: 0 auto; padding: 24px clamp(18px, 4vw, 48px) 56px; }
-  .filters { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 12px; margin-bottom: 18px; }
-  label { display: grid; gap: 6px; color: #aeb7c5; font-size: 12px; }
-  input, select { min-width: 0; width: 100%; border: 1px solid #333b49; border-radius: 7px; padding: 9px 10px; background: #151a23; color: #edf0f5; font: inherit; }
-  [data-loading] { min-height: 18px; color: #9ba5b4; font-size: 12px; }
-  [data-error] { margin: 12px 0; padding: 12px; border: 1px solid #713d46; border-radius: 8px; background: #301a21; color: #ffb8c0; }
-  [data-error][hidden] { display: none; }
-  h2 { margin: 25px 0 12px; font-size: 16px; }
-  .totals { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 10px; }
-  .usage-total, .usage-breakdown { border: 1px solid #252c38; border-radius: 9px; background: #11151d; }
-  .usage-total { padding: 13px; }
-  .usage-total h3 { margin: 0 0 8px; color: #9ba5b4; font-size: 11px; font-weight: 500; }
-  .usage-total p { margin: 0; font-size: 20px; font-variant-numeric: tabular-nums; }
-  .breakdown-tabs { display: flex; flex-wrap: wrap; gap: 7px; padding: 0; border: 0; }
-  .breakdown-tabs button { border: 1px solid #333b49; border-radius: 99px; padding: 7px 12px; background: #151a23; color: #bac3d0; cursor: pointer; font: inherit; font-size: 12px; }
-  .breakdown-tabs button[aria-pressed="true"] { border-color: #7399ff; background: #20315a; color: #fff; }
-  .usage-breakdown { margin: 10px 0; padding: 14px; }
-  .usage-breakdown.selected { border-color: #526eaa; }
-  .usage-breakdown h2 { margin: 0 0 10px; }
-  .usage-bucket { display: flex; justify-content: space-between; gap: 18px; border-top: 1px solid #252c38; padding: 10px 0; font-size: 12px; }
-  .usage-bucket span, .empty { color: #9ba5b4; text-align: right; }
-  @media (max-width: 680px) { .usage-bucket { display: grid; gap: 5px; } .usage-bucket span { text-align: left; } }
-</style>
-</head>
-<body>
-<header><h1>Usage</h1><p>Token totals, costs, and session breakdowns</p></header>
-<main id="usage-root">
-  <div class="filters" role="group" aria-label="Usage filters">
-    <label>Period<select data-filter="period" name="period">
-      <option value="today">Today</option><option value="3d">Last 3 days</option><option value="7d">Last 7 days</option><option value="30d">Last 30 days</option><option value="all">All time</option><option value="">Custom range</option>
-    </select></label>
-    <label>Repository<input data-filter="repo" name="repo" type="text" autocomplete="off"></label>
-    <label>Model<input data-filter="model" name="model" type="text" autocomplete="off"></label>
-    <label>Agent<input data-filter="agent" name="agent" type="text" autocomplete="off"></label>
-    <label>Since<input data-filter="since" name="since" type="date"></label>
-    <label>Until<input data-filter="until" name="until" type="date"></label>
-  </div>
-  <div data-loading role="status" aria-live="polite"></div>
-  <div data-error role="alert" hidden></div>
-  <section aria-labelledby="totals-heading"><h2 id="totals-heading">Totals</h2><div class="totals" data-totals></div></section>
-  <section aria-labelledby="breakdowns-heading"><h2 id="breakdowns-heading">Breakdowns</h2>
-    <nav class="breakdown-tabs" aria-label="Usage breakdowns">
-      <button type="button" data-breakdown="day">Day</button><button type="button" data-breakdown="repo">Repository</button>
-      <button type="button" data-breakdown="model">Model</button><button type="button" data-breakdown="agent">Agent</button>
-      <button type="button" data-breakdown="run">Run</button><button type="button" data-breakdown="origin">Origin</button>
-    </nav>
-    <div data-breakdowns></div>
-  </section>
-</main>
-<script>
+  const behaviorSource = [normalizeUsageInterval, buildUsageApiUrl, buildUsagePageSearch, formatCompact, formatUsd, formatAxisTick, formatShare, formatCost, previousWindow, computeDelta, donutSlices, donutCenterFontSize, renderModelLegend, renderDonutSvg, renderSparklineSvg, renderLineChartSvg, createUsageChartView, formatChartTooltip, attachChartInteractions, toUsagePageData, createUsagePageController, startUsagePage, filterAndSortUsageRows, captureUsageSearchFocus, restoreUsageSearchFocus, csvQuote, renderUsageFilterOptions, renderUsageTableRows, renderUsageDashboard, renderActiveUsageChart, selectedRows, escapeHtml]
+    .map((behavior) => Function.prototype.toString.call(behavior)).join("\n\n");
+  const topbar = renderTopBar({ pages: options.pages ?? [{ label: "Home", path: "/" }, { label: "Review", path: "/review" }, { label: "Setup", path: "/setup" }, { label: "Usage", path: "/usage" }], activePath: "/usage", title: "Usage" });
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>CodeDeck usage</title><link rel="icon" href="${LOGO_FAVICON_HREF}"><style>${BRAND_CSS}
+${USAGE_CSS}
+</style></head><body>${topbar}<main id="usage-root"><header class="usage-header"><h1>Usage</h1><div class="usage-actions"><label class="range-picker" aria-label="Range"><select data-range data-filter="period"><option value="today">Today</option><option value="3d">Last 3 days</option><option value="7d">Last 7 days</option><option value="30d">Last 30 days</option><option value="all">All time</option><option value="">Custom</option></select><span aria-hidden="true">⌄</span></label><label class="date-picker" data-date-field>Since<input data-filter="since" type="date"></label><label class="date-picker" data-date-field>Until<input data-filter="until" type="date"></label><button class="button ghost-button" data-copy>Copy link</button><button class="button ghost-button" data-export>Export CSV</button></div></header><section class="filterbar"><div class="filter-tools"><button class="button" data-add-filter>Add filter</button><div data-filter-menu hidden><button data-filter-kind="repo" data-filter="repo">Repository</button><button data-filter-kind="model" data-filter="model">Model</button><button data-filter-kind="agent" data-filter="agent">Agent</button></div><div data-chips></div><button data-live class="live on">● Live refresh</button></div></section><div data-loading role="status" hidden></div><div data-error class="error" role="alert" hidden><span></span><button data-dismiss-error>Dismiss</button></div><div data-dashboard class="dashboard"></div></main><script>
 ${behaviorSource}
-startUsagePage(${serializedOptions}, { fetch, setInterval, clearInterval, document });
-</script>
-</body>
-</html>`;
+const usageScript=document.currentScript;
+const usageEnvironment={fetch:(...args)=>globalThis.fetch(...args),setInterval:(...args)=>globalThis.setInterval(...args),clearInterval:(...args)=>globalThis.clearInterval(...args),setTimeout:(...args)=>globalThis.setTimeout(...args),clearTimeout:(...args)=>globalThis.clearTimeout(...args),document:globalThis.document,location:globalThis.location,window:globalThis,replaceUrl:(search)=>globalThis.history.replaceState(null,"",globalThis.location.pathname+search),copyToClipboard:(text)=>globalThis.navigator.clipboard.writeText(text)};
+startUsagePage(${serializedOptions},usageEnvironment);
+</script></body></html>`;
 }
 
+export const USAGE_CSS = `
+.topbar{height:52px;display:flex;align-items:center;gap:24px;padding:0 28px;border-bottom:1px solid var(--border);background:var(--bg)}.brand{display:flex;align-items:center;gap:8px;color:var(--text);text-decoration:none;font-weight:600;font-size:15px;letter-spacing:-.3px}.brand svg{display:block}.topbar-title{font-size:13px;color:var(--text-muted);border-left:1px solid var(--border-strong);padding-left:18px}.topbar nav{display:flex;gap:20px;margin-left:auto}.topbar nav a{color:var(--text-faint);font-size:12px;text-decoration:none}.topbar nav a.active{color:var(--text);font-weight:550}
+main{max-width:1440px;margin:0 auto;padding:24px 30px 60px}.usage-header{display:flex;align-items:center;justify-content:space-between;gap:16px;margin-bottom:14px}.usage-header h1{margin:0;font-size:21px;font-weight:600;letter-spacing:-.3px}.usage-actions{display:flex;align-items:center;gap:8px}.range-picker{position:relative;display:flex;align-items:center}.range-picker select{appearance:none;padding-right:28px!important;min-width:122px!important}.range-picker span{position:absolute;right:10px;color:var(--text-faint);pointer-events:none}.date-picker{display:flex;align-items:center;gap:8px;color:var(--text-muted);font-size:11px}.date-picker input{height:34px;padding:0 8px;border:1px solid var(--border);border-radius:6px;background:var(--surface);color:var(--text);font-size:12px}.ghost-button{background:transparent}.filterbar{display:flex;align-items:center;gap:12px;margin-bottom:18px;flex-wrap:wrap}.filterbar label{display:grid;gap:6px;color:var(--text-muted);font-size:11px}.filterbar select,.filterbar input,.table-card input,.range-picker select{height:34px;min-width:130px;padding:0 10px;border:1px solid var(--border-strong);border-radius:6px;background:#0a0a0a;color:var(--text);font-size:12px}.filter-tools{display:flex;gap:7px;align-items:center;width:100%;position:relative}.filter-tools [data-live]{margin-left:auto}.button,.filter-tools button,.show-all{border:1px solid var(--border);border-radius:6px;background:var(--surface);color:var(--text-muted);padding:8px 10px;font-size:11px;cursor:pointer}.filter-tools button:hover,.show-all:hover{background:var(--surface-hover);color:var(--text)}[data-filter-menu]{position:absolute;z-index:4;top:38px;left:0;padding:6px;background:var(--surface-raised);border:1px solid var(--border-strong);border-radius:7px}[data-filter-menu] button{display:block;width:100%;text-align:left}.live{color:var(--success)!important}.live:not(.on){color:var(--text-faint)!important}.pill{display:inline-block;border:1px solid var(--border-strong);border-radius:99px;background:var(--surface-raised);color:var(--text-muted);font-size:10px;padding:3px 7px;white-space:nowrap}
+.filter-chip{display:inline-flex;align-items:center;gap:6px;border:1px solid var(--border-strong);border-radius:99px;background:var(--surface-raised);color:var(--text-muted);font-size:10px;padding:4px 7px}.filter-chip button{border:0!important;padding:0!important;background:transparent!important;color:var(--text-faint)!important}
+.error{display:flex;justify-content:space-between;align-items:center;margin:0 0 14px;padding:10px 12px;border:1px solid #65363a;border-radius:6px;background:#1c0d0e;color:#f2a5a7;font-size:12px}[hidden]{display:none!important}[data-loading]{color:var(--text-muted);font-size:12px;margin:8px 0}.dashboard{display:grid;gap:14px}.card{min-width:0;border:1px solid var(--border);border-radius:8px;background:var(--surface);padding:16px}.kpis{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px}.kpi{position:relative;min-height:142px;padding-bottom:34px;overflow:hidden}.kpi-heading{display:flex;align-items:center;gap:8px;color:var(--text-muted);font-size:11px}.range-tag{margin-left:auto;font:10px var(--font-mono);color:var(--text-faint)}.kpi-value{display:block;margin-top:14px;font-size:25px;letter-spacing:-.7px;font-weight:550;font-variant-numeric:tabular-nums}.delta{margin:4px 0 0;color:var(--blue-2);font-size:10px}.delta span,.kpi-note{color:var(--text-faint)}.kpi-note{font-size:10px}.spark{position:absolute;left:0;right:0;bottom:0;width:100%;height:38px;overflow:visible}.spark-area{fill:url(#chart-fill)}.spark-line{fill:none;stroke:var(--blue-chart);stroke-width:1.6}.spark circle{fill:var(--blue-chart)}
+th button{border:0;background:transparent;color:var(--text-faint);padding:0;font:inherit;cursor:pointer}
+.card-heading{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px}.card-heading h2{margin:0;font-size:13px;font-weight:550}.card-heading>span{font-size:10px;color:var(--text-faint);font-family:var(--font-mono)}.series-switch,.tabs{display:flex;gap:4px}.series-switch button,.tabs button{border:1px solid transparent;border-radius:5px;background:transparent;color:var(--text-faint);padding:5px 8px;font-size:10px;cursor:pointer}.series-switch button:focus,.series-switch button:hover,.tabs button[aria-pressed="true"]{border-color:var(--border-strong);background:var(--surface-raised);color:var(--text)}.chart-wrap{width:100%;overflow:hidden;position:relative}.line-chart{display:block;width:100%;height:auto}.single-day-caption{margin:0;color:var(--text-faint);font-size:11px;text-align:center}.chart-crosshair{stroke:#bfdbfe;stroke-width:1;stroke-dasharray:3 3;pointer-events:none}.chart-tooltip{position:absolute;z-index:2;max-width:170px;padding:7px 9px;border:1px solid var(--border-strong);border-radius:6px;background:#111;color:var(--text);font:11px var(--font-mono);pointer-events:none;white-space:nowrap}.gridline{stroke:var(--grid);stroke-dasharray:3 4}.axis{font:11px var(--font-mono);fill:var(--text-faint)}.chart-area{fill:url(#chart-fill)}.chart-line{fill:none;stroke:var(--blue-chart);stroke-width:2}.chart-point{fill:var(--blue-chart);stroke:var(--bg);stroke-width:2}.two-col,.three-col{display:grid;gap:12px;align-items:stretch}.two-col{grid-template-columns:1fr 1fr}.three-col{grid-template-columns:1fr 1.1fr 1fr}.donut-layout{display:grid;grid-template-columns:minmax(130px, .85fr) 1.15fr;align-items:center;gap:12px}.donut-svg{width:100%;max-height:210px;overflow:visible}.donut-seg{fill:none;stroke-width:22;cursor:pointer}.donut-center{text-anchor:middle;font:600 13px var(--font-mono);fill:var(--text)}.donut-sub{text-anchor:middle;font:10px var(--font-sans);fill:var(--text-faint)}.model-legend{display:grid;align-content:start;gap:4px;min-width:0}.legend-row{display:grid;grid-template-columns:minmax(0,1fr) auto;align-items:center;gap:2px 8px;padding:6px 0;border-bottom:1px solid var(--border);font-size:10px}.legend-row .model-name{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:10px var(--font-mono);color:var(--text-muted)}.legend-row strong{font:11px var(--font-mono)}.legend-row small{grid-column:1/-1;color:var(--text-faint);font-size:10px}.rank-list{max-height:246px;overflow:auto}.rank-row{display:grid;grid-template-columns:minmax(80px,1.1fr) minmax(50px,1fr) auto;align-items:center;gap:9px;padding:7px 0;border-bottom:1px solid var(--border);font-size:10px}.rank-row>span{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--text-muted)}.rank-row>strong{font:10px var(--font-mono)}.rank-row>i,.track{height:4px;background:var(--surface-raised);border-radius:5px;overflow:hidden}.rank-row>i>b,.track>i{display:block;height:100%;background:var(--blue-chart);border-radius:5px}
+.outcome-bar{display:flex;height:9px;border-radius:8px;overflow:hidden;background:var(--surface-raised)}.outcome-bar i{min-width:0}.outcome-legend{display:grid;gap:8px;margin-top:14px}.outcome-legend>div{display:grid;grid-template-columns:1fr auto;gap:3px 10px;font-size:10px;color:var(--text-muted)}.outcome-legend strong{font:11px var(--font-mono);color:var(--text)}.outcome-legend small{grid-column:1/-1;color:var(--text-faint);font-size:10px}.harness-list,.origin-list{display:grid;gap:12px}.harness-row{display:grid;grid-template-columns:minmax(56px,.7fr) minmax(38px,1fr) auto minmax(38px,1fr) auto;gap:8px;align-items:center;font-size:10px}.harness-row strong,.origin-row strong{font:10px var(--font-mono);color:var(--text-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.harness-row small{font-size:10px;color:var(--text-faint);white-space:nowrap}.origin-row{display:grid;grid-template-columns:1fr auto auto;gap:12px;border-bottom:1px solid var(--border);padding:8px 0;font-size:10px}.origin-row span{color:var(--text-muted);white-space:nowrap}.empty{margin:20px 0;color:var(--text-faint);font-size:11px;text-align:center}.table-card{padding-bottom:10px}.table-card .card-heading{margin-bottom:8px}.table-card input{height:29px;min-width:160px}.tabs{border-bottom:1px solid var(--border);margin-bottom:5px}.tabs button{padding:8px 10px;border-radius:0}.tabs button[aria-pressed="true"]{border:0;border-bottom:2px solid var(--blue);background:transparent}.table-scroll{width:100%;overflow:auto}table{width:100%;border-collapse:collapse;font-size:11px}th{text-align:left;color:var(--text-faint);font-weight:450;border-bottom:1px solid var(--border)}th,td{padding:10px 9px;white-space:nowrap}td{border-bottom:1px solid var(--border);color:var(--text-muted)}td:first-child{max-width:280px;overflow:hidden;text-overflow:ellipsis;color:var(--text)}td:nth-child(2),td:nth-child(3),td:nth-child(4){font-family:var(--font-mono);font-variant-numeric:tabular-nums}.share{display:inline-block;width:65px;height:4px;margin-right:8px;background:var(--surface-raised);vertical-align:middle}.share i{display:block;height:100%;background:var(--blue-chart)}.show-all{margin:6px 0}
+@media(max-width:900px){main{padding:18px 18px 40px}.three-col{grid-template-columns:repeat(2,minmax(0,1fr))}.three-col>.card:last-child{grid-column:1/-1}}
+@media(max-width:600px){.usage-header{align-items:flex-start;flex-direction:column}.usage-actions{width:100%;flex-wrap:wrap}.range-picker{flex:1}.range-picker select{width:100%}.usage-actions .ghost-button{flex:1}.topbar{padding:0 14px;gap:12px}.topbar-title{padding-left:10px}.topbar nav{gap:10px}.topbar nav a{font-size:10px}main{padding:14px 12px 36px}.filterbar{align-items:center;display:flex;gap:8px}.filter-tools{margin:0;display:flex;flex-wrap:wrap}.filter-tools button{padding:8px}.kpis{grid-template-columns:1fr;gap:8px}.kpi{min-height:128px;padding:12px 10px 32px}.kpi-value{font-size:20px}.two-col,.three-col{grid-template-columns:1fr}.three-col>.card:last-child{grid-column:auto}.card{padding:13px}.donut-layout{grid-template-columns:1fr;gap:6px}.donut-svg{width:180px;height:180px;max-height:none;justify-self:center}.donut-center{font-size:13px}.rank-list{max-height:230px}.harness-row{grid-template-columns:minmax(55px,.7fr) minmax(30px,1fr) auto minmax(30px,1fr) auto;gap:5px}.harness-row small{font-size:10px}.axis{font-size:11px}table{font-size:10px}th,td{padding:9px 6px}td:first-child{max-width:110px}.table-card input{min-width:120px}.series-switch button{padding:5px 4px;font-size:10px}}
+`;
+
 export const USAGE_PAGE = renderUsagePage();
diff --git a/src/web/usage-routes.ts b/src/web/usage-routes.ts
index b517a0f..3908413 100644
--- a/src/web/usage-routes.ts
+++ b/src/web/usage-routes.ts
@@ -3,12 +3,14 @@ import { buildUsageQueryParams, type UsageQueryOptions } from "../core/usage-que
 import type { UsageQueryParams, UsageQueryResult } from "../daemon/protocol.js";
 import type { WebRoute } from "./server.js";
 import { renderUsagePage, type UsagePageOptions } from "./usage-page.js";
+import type { WebPageLink } from "./brand.js";
 
 export interface UsageRoutesOptions {
   fetchUsageQuery: (params: UsageQueryParams) => Promise<UsageQueryResult>;
   cwd?: string;
   now?: () => Date;
   page?: UsagePageOptions;
+  pages?: WebPageLink[];
 }
 
 export function parseUsageWebQuery(
@@ -40,9 +42,23 @@ export function createUsageRoutes(options: UsageRoutesOptions): WebRoute[] {
     {
       path: "/usage",
       kind: "page",
-      handler: (_request, response) => {
+      handler: (request, response) => {
         response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
-        response.end(renderUsagePage(options.page));
+        const search = new URL(request.url ?? "/usage", "http://127.0.0.1").searchParams;
+        response.end(renderUsagePage({
+          ...options.page,
+          pages: options.pages ?? options.page?.pages,
+          filters: {
+            ...options.page?.filters,
+            period: search.get("period") ?? options.page?.filters?.period,
+            repo: search.get("repo") ?? options.page?.filters?.repo,
+            model: search.get("model") ?? options.page?.filters?.model,
+            agent: search.get("agent") ?? options.page?.filters?.agent,
+            since: search.get("since") ?? options.page?.filters?.since,
+            until: search.get("until") ?? options.page?.filters?.until,
+          },
+          by: (search.get("by") as UsagePageOptions["by"]) ?? options.page?.by,
+        }));
       },
     },
     {
diff --git a/tests/usage-page.test.ts b/tests/usage-page.test.ts
index 35c0043..297f453 100644
--- a/tests/usage-page.test.ts
+++ b/tests/usage-page.test.ts
@@ -3,8 +3,31 @@ import { describe, expect, it, vi } from "vitest";
 import type { UsageMetricBucket, UsageQueryResult } from "../src/daemon/protocol.js";
 import {
   createUsagePageController,
+  buildUsagePageSearch,
+  computeDelta,
+  captureUsageSearchFocus,
+  csvQuote,
+  createUsageChartView,
+  donutSlices,
+  donutCenterFontSize,
+  formatChartTooltip,
+  formatCompact,
+  formatCost,
+  formatShare,
+  formatUsd,
+  filterAndSortUsageRows,
   normalizeUsageInterval,
+  previousWindow,
+  renderDonutSvg,
+  renderLineChartSvg,
+  renderModelLegend,
+  renderSparklineSvg,
+  renderUsageFilterOptions,
+  renderUsageTableRows,
+  restoreUsageSearchFocus,
   renderUsagePage,
+  startUsagePage,
+  USAGE_CSS,
   toUsagePageData,
   USAGE_PAGE,
   type UsagePageControllerOptions,
@@ -68,6 +91,63 @@ function controllerOptions(overrides: Partial<UsagePageControllerOptions> = {})
   };
 }
 
+function createUsageDashboardDom() {
+  let activeElement: Record<string, unknown> | null = null;
+  let currentSearch: ReturnType<typeof makeElement> | null = null;
+  let dashboardHtml = "";
+  function makeElement() {
+    const listeners = new Map<string, (event: Record<string, unknown>) => void>();
+    const element = {
+      hidden: false,
+      textContent: "",
+      className: "",
+      value: "",
+      dataset: {} as Record<string, string | undefined>,
+      style: { left: "", top: "" },
+      selectionStart: 0,
+      selectionEnd: 0,
+      addEventListener(type: string, listener: (event: Record<string, unknown>) => void) { listeners.set(type, listener); },
+      dispatch(type: string) { listeners.get(type)?.({ target: element }); },
+      focus() { activeElement = element; },
+      setSelectionRange(start: number, end: number) { element.selectionStart = start; element.selectionEnd = end; },
+      setAttribute() {},
+      getAttribute() { return null; },
+      replaceChildren() {},
+      append() {},
+      click() {},
+      closest() { return element; },
+      getBoundingClientRect() { return { left: 0, top: 0, width: 880, height: 248 }; },
+      querySelector(selector: string) { return selector === "[data-search]" ? currentSearch : null; },
+      querySelectorAll() { return []; },
+    };
+    return element;
+  }
+  const dashboard = makeElement() as ReturnType<typeof makeElement> & { innerHTML: string };
+  Object.defineProperty(dashboard, "innerHTML", {
+    get: () => dashboardHtml,
+    set: (html: string) => {
+      dashboardHtml = html;
+      currentSearch = makeElement();
+      currentSearch.value = html.match(/<input data-search[^>]* value="([^"]*)"/)?.[1] ?? "";
+    },
+  });
+  currentSearch = makeElement();
+  const root = makeElement();
+  root.querySelector = (selector: string) => selector === "[data-dashboard]" ? dashboard : null;
+  const document = {
+    get activeElement() { return activeElement; },
+    getElementById: (id: string) => id === "usage-root" ? root : null,
+    createElement: () => makeElement(),
+    addEventListener() {},
+  };
+  return {
+    document,
+    get html() { return dashboardHtml; },
+    get search() { return currentSearch; },
+    focusSearch() { currentSearch?.focus(); },
+  };
+}
+
 describe("usage page data", () => {
   it("exposes every total and all available breakdown buckets", () => {
     const data = toUsagePageData(usageResult);
@@ -94,6 +174,43 @@ describe("usage page data", () => {
 });
 
 describe("usage page behavior", () => {
+  it("ignores a stale response when overlapping refreshes resolve out of order", async () => {
+    let resolveFirst!: (value: UsagePageFetchResponse) => void;
+    const first = new Promise<UsagePageFetchResponse>((resolve) => { resolveFirst = resolve; });
+    const secondResult = { ...usageResult, totals: { ...totals, sessionCount: 22 } };
+    const fetch = vi.fn().mockReturnValueOnce(first).mockResolvedValueOnce(response(secondResult));
+    const controller = createUsagePageController(controllerOptions({ fetch }));
+    const staleRefresh = controller.refresh();
+    await controller.refresh();
+    resolveFirst(response(usageResult));
+    await staleRefresh;
+    expect(controller.getState().result?.totals.sessionCount).toBe(22);
+  });
+
+  it("ignores an older previous-window response after a newer refresh", async () => {
+    let resolveOldPrevious!: (value: UsagePageFetchResponse) => void;
+    const oldPrevious = new Promise<UsagePageFetchResponse>((resolve) => { resolveOldPrevious = resolve; });
+    const currentNew = { ...usageResult, totals: { ...totals, sessionCount: 22 } };
+    const previousNew = { ...usageResult, totals: { ...totals, sessionCount: 11 } };
+    let calls = 0;
+    const fetch = vi.fn(async () => {
+      calls += 1;
+      if (calls === 1) return response(usageResult);
+      if (calls === 2) return oldPrevious;
+      if (calls === 3) return response(currentNew);
+      return response(previousNew);
+    });
+    const controller = createUsagePageController(controllerOptions({ fetch, initialFilters: { period: "3d" } }));
+    const older = controller.refresh();
+    await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(2));
+    const newer = controller.refresh();
+    await newer;
+    resolveOldPrevious(response(usageResult));
+    await older;
+    expect(controller.getState().result?.totals.sessionCount).toBe(22);
+    expect(controller.getState().previous?.totals.sessionCount).toBe(11);
+  });
+
   it("re-queries when period, repo, model, agent, since, and until change", async () => {
     const options = controllerOptions({
       initialFilters: { period: "3d", repo: "/old", model: "", agent: "", since: "", until: "" },
@@ -143,10 +260,11 @@ describe("usage page behavior", () => {
     await controller.start();
     await controller.setFilter("model", "gpt-5.6-luna");
     poll?.();
+    await vi.waitFor(() => expect(options.fetch).toHaveBeenCalledTimes(6));
 
     const lastUrl = new URL(String(options.fetch.mock.lastCall?.[0]), "http://localhost");
-    expect(options.fetch).toHaveBeenCalledTimes(3);
-    expect(lastUrl.searchParams.get("period")).toBe("7d");
+    expect(options.fetch).toHaveBeenCalledTimes(6);
+    expect(lastUrl.searchParams.get("period")).toBeNull();
     expect(lastUrl.searchParams.get("model")).toBe("gpt-5.6-luna");
     controller.stop();
     expect(options.clearInterval).toHaveBeenCalledWith(24);
@@ -190,6 +308,35 @@ describe("usage page behavior", () => {
     expect(render.mock.lastCall?.[0].error).toBe("daemon unavailable");
   });
 
+  it("writes the active filters and breakdown to the shareable URL", async () => {
+    const replaceUrl = vi.fn();
+    const options = controllerOptions({ replaceUrl });
+    const controller = createUsagePageController(options);
+    await controller.setFilter("period", "7d");
+    await controller.setFilter("repo", "/workspace");
+    controller.setBreakdown("repo");
+    expect(replaceUrl).toHaveBeenLastCalledWith("?period=7d&repo=%2Fworkspace&by=repo");
+  });
+
+  it("does not show loading for a background poll and clears its timer when stopped", async () => {
+    let poll: (() => void) | undefined;
+    const render = vi.fn((_state: UsagePageState) => {});
+    const clearInterval = vi.fn();
+    const options = controllerOptions({
+      render,
+      clearInterval,
+      setInterval: vi.fn((callback: () => void) => { poll = callback; return 42; }),
+    });
+    const controller = createUsagePageController(options);
+    await controller.start();
+    render.mockClear();
+    poll?.();
+    await vi.waitFor(() => expect(options.fetch).toHaveBeenCalledTimes(2));
+    expect(render.mock.calls.every(([state]) => !state.loading)).toBe(true);
+    controller.stop();
+    expect(clearInterval).toHaveBeenCalledWith(42);
+  });
+
   it("injects executable behavior functions into the standalone page", async () => {
     const script = USAGE_PAGE.match(/<script>([\s\S]*?)<\/script>/)?.[1];
     if (!script) throw new Error("usage page inline script is missing");
@@ -233,16 +380,225 @@ describe("usage page behavior", () => {
   it("renders the filter controls and every breakdown section", () => {
     const html = renderUsagePage({ by: "origin" });
 
+    expect(html.match(/data-range(?=\s)/g)).toHaveLength(1);
+    expect(html.match(/data-live(?=\s)/g)).toHaveLength(1);
+    expect(html).not.toContain('data-action="refresh"');
+    expect(html).toContain('aria-current="page" class="active">Usage</a>');
+    expect(html).toContain('<h1>Usage</h1>');
+    expect(html).toContain('class="usage-actions"');
+    expect(html).toContain('data-copy>Copy link</button>');
+    expect(html).toContain('data-export>Export CSV</button>');
+    expect(html.indexOf('class="usage-header"')).toBeLessThan(html.indexOf('class="filterbar"'));
+    expect(html).toContain('href="/"');
     expect(html).toContain('data-filter="period"');
-    expect(html).toContain('data-filter="repo"');
-    expect(html).toContain('data-filter="model"');
-    expect(html).toContain('data-filter="agent"');
+    expect(html).toContain('data-filter-kind="repo"');
+    expect(html).toContain('data-filter-kind="model"');
+    expect(html).toContain('data-filter-kind="agent"');
     expect(html).toContain('data-filter="since"');
     expect(html).toContain('data-filter="until"');
-    for (const breakdown of ["day", "repo", "model", "agent", "run", "origin"]) {
-      expect(html).toContain(`data-breakdown="${breakdown}"`);
-    }
+    expect(html).toContain('data-breakdown="${name}"');
+    for (const breakdown of ["day", "repo", "model", "agent", "run", "origin"]) expect(html).toContain(`"${breakdown}"`);
     expect(html).toContain('"by":"origin"');
     expect(html).toContain("sessionsWithoutCost");
   });
+
+  it("binds native browser functions to the global receiver", async () => {
+    const context = vm.createContext({
+      fetchCalls: 0,
+      document: { getElementById: () => null },
+    });
+    vm.runInContext(`
+      fetch = function() { if (this !== globalThis) throw new TypeError("Illegal invocation"); fetchCalls += 1; return Promise.resolve({}); };
+      setInterval = function() { if (this !== globalThis) throw new TypeError("Illegal invocation"); return 19; };
+      clearInterval = function(handle) { if (this !== globalThis || handle !== 19) throw new TypeError("Illegal invocation"); };
+    `, context);
+    const script = USAGE_PAGE.match(/<script>([\s\S]*?)<\/script>/)?.[1];
+    if (!script) throw new Error("usage page inline script is missing");
+    vm.runInContext(script, context);
+    await vm.runInContext("usageEnvironment.fetch('/api/usage').then(() => { const timer=usageEnvironment.setInterval(() => {},20); usageEnvironment.clearInterval(timer); })", context);
+    expect((context as unknown as { fetchCalls: number }).fetchCalls).toBe(1);
+  });
+});
+
+describe("usage page formatting and chart helpers", () => {
+  it("escapes hostile labels in SVG titles, the model legend and table rows", () => {
+    const hostile = { ...bucket, key: '<img src=x onerror=alert(1)>', label: '<img src=x onerror=alert(1)>' };
+    const donut = renderDonutSvg([hostile]);
+    const line = renderLineChartSvg([hostile]);
+    const legend = renderModelLegend([hostile]);
+    const table = renderUsageTableRows([hostile], hostile.costUsd, false);
+    for (const html of [donut, line, legend, table]) expect(html).not.toMatch(/<img\b/i);
+    expect(donut).toContain("&lt;img");
+    expect(line).toContain("&lt;img");
+  });
+
+  it("filters rows before applying the top ten limit", () => {
+    const rows = Array.from({ length: 30 }, (_, index) => ({ ...bucket, key: `row-${index + 1}`, label: `row-${index + 1}` }));
+    const filtered = filterAndSortUsageRows(rows, "row-15", "costUsd", -1);
+    const html = renderUsageTableRows(filtered, filtered[0].costUsd, false);
+    expect(filtered).toHaveLength(1);
+    expect(html).toContain(">row-15</td>");
+    expect(html).not.toContain("hidden");
+  });
+
+  it("restores search focus and its selection after a render", () => {
+    const selection = vi.fn();
+    const focus = vi.fn();
+    const input = { value: "row-15", selectionStart: 3, selectionEnd: 5, focus, setSelectionRange: selection };
+    const state = captureUsageSearchFocus({ activeElement: input } as never, input as never);
+    const replacement = { value: "", focus, setSelectionRange: selection };
+    restoreUsageSearchFocus(replacement as never, state);
+    expect(state.focused).toBe(true);
+    expect(replacement.value).toBe("row-15");
+    expect(focus).toHaveBeenCalledOnce();
+    expect(selection).toHaveBeenCalledWith(3, 5);
+  });
+
+  it("keeps search focus and selection through a dashboard render", async () => {
+    const rows = Array.from({ length: 30 }, (_, index) => ({ ...bucket, key: `run-${index + 1}`, label: `row-${index + 1}` }));
+    const result = { ...usageResult, byRun: rows };
+    const dom = createUsageDashboardDom();
+    startUsagePage({ by: "run" }, {
+      fetch: async () => response(result), setInterval: () => 1, clearInterval: () => {}, document: dom.document as never,
+    });
+    await vi.waitFor(() => expect(dom.html).toContain('data-search'));
+    const search = dom.search!;
+    search.value = "row-15";
+    search.selectionStart = 3;
+    search.selectionEnd = 5;
+    dom.focusSearch();
+    search.dispatch("input");
+    expect(dom.document.activeElement).toBe(dom.search);
+    expect(dom.search?.selectionStart).toBe(3);
+    expect(dom.search?.selectionEnd).toBe(5);
+  });
+
+  it("filters dashboard rows before applying the top ten limit", async () => {
+    const rows = Array.from({ length: 30 }, (_, index) => ({ ...bucket, key: `run-${index + 1}`, label: `row-${index + 1}` }));
+    const result = { ...usageResult, byRun: rows };
+    const dom = createUsageDashboardDom();
+    startUsagePage({ by: "run" }, {
+      fetch: async () => response(result), setInterval: () => 1, clearInterval: () => {}, document: dom.document as never,
+    });
+    await vi.waitFor(() => expect(dom.html).toContain("row-10"));
+    const search = dom.search!;
+    search.value = "row-15";
+    search.dispatch("input");
+    expect(dom.html).toContain('<tr><td title="row-15">row-15</td>');
+    expect(dom.html).not.toContain(">row-1</td>");
+    expect(dom.html.match(/<tbody><tr/g)).toHaveLength(1);
+  });
+
+  it("quotes CSV fields by doubling embedded quotes", () => {
+    expect(csvQuote('model "fast", v2')).toBe('"model ""fast"", v2"');
+  });
+
+  it("uses a stable key for filter option values and the label for display", () => {
+    const options = renderUsageFilterOptions([{ ...bucket, key: "model-id", label: "Friendly model" }], "model");
+    expect(options).toContain('<option value="model-id">Friendly model</option>');
+  });
+
+  it.each([[999, "999"], [10_000, "10K"], [842_310, "842K"], [16_756_717, "16.8M"], [1_193_095_059, "1.19B"]])(
+    "formats %s as %s", (value, expected) => expect(formatCompact(value)).toBe(expected),
+  );
+  it("formats currency, shares, incomplete cost and deltas", () => {
+    expect(formatUsd(1865.421706)).toBe("$1,865.42");
+    expect(formatShare(47.84, "spend")).toBe("47.8% of spend");
+    expect(formatCost(1865.421706, false, 104)).toContain("≥ $1,865.42");
+    expect(formatCost(1865.421706, false, 104)).toContain("104 unpriced");
+    expect(formatCost(1865.421706, false, 104)).not.toContain("?");
+    expect(computeDelta(10, 0, "7d")).toBeUndefined();
+    expect(computeDelta(10, 5, "today")).toBeUndefined();
+    expect(computeDelta(10, 5, "7d")).toEqual({ direction: "up", percent: 100 });
+  });
+  it("uses calendar days for a 30d previous window across the New York DST change", () => {
+    const priorTimezone = process.env.TZ;
+    process.env.TZ = "America/New_York";
+    try {
+      const window = previousWindow("30d", new Date("2026-04-01T12:00:00.000Z"))!;
+      expect(window.until).toBe("2026-03-02T12:59:59.999Z");
+      expect(window.since).toBe("2026-01-31T12:59:59.999Z");
+      const crossing = previousWindow("30d", new Date("2026-04-10T12:00:00.000Z"))!;
+      expect(crossing.until).toBe("2026-03-11T11:59:59.999Z");
+      expect(crossing.since).toBe("2026-02-09T12:59:59.999Z");
+    } finally {
+      if (priorTimezone === undefined) delete process.env.TZ;
+      else process.env.TZ = priorTimezone;
+    }
+  });
+  it("groups model slices into the top six plus Other and formats the donut center as spend", () => {
+    const rows = Array.from({ length: 8 }, (_, index) => ({ ...bucket, key: `model-${index}`, label: `model-${index}`, costUsd: 8 - index }));
+    const slices = donutSlices(rows);
+    expect(slices).toHaveLength(7);
+    expect(slices.at(-1)?.label).toBe("Other");
+    expect(slices.reduce((sum, row) => sum + row.costUsd, 0)).toBe(rows.reduce((sum, row) => sum + row.costUsd, 0));
+    expect(renderDonutSvg(rows)).toContain("$36.00");
+    const legend = renderModelLegend(rows);
+    expect((legend.match(/class="legend-row"/g) ?? [])).toHaveLength(7);
+    expect(legend).toContain("model-5");
+    expect(legend).toContain("Other");
+    expect(donutCenterFontSize("$1,890.76")).toBe(10);
+    expect(renderDonutSvg([{ ...bucket, costUsd: 1890.76 }])).toContain('font-size:10px');
+    expect(formatChartTooltip({ ...bucket, totalTokens: 16_756_717 }, "totalTokens")).toEqual({ text: "Codex · 16.8M", title: "16756717" });
+  });
+  it("renders measured-width charts with stable axis text and a crosshair", () => {
+    const rows = [bucket, { ...bucket, key: "2026-09-23", costUsd: 0.3 }];
+    const narrow = renderLineChartSvg(rows, "costUsd", 360);
+    const wide = renderLineChartSvg(rows, "costUsd", 1200);
+    expect(narrow).toContain('width="360" height="248" viewBox="0 0 360 248"');
+    expect(wide).toContain('width="1200" height="248" viewBox="0 0 1200 248"');
+    expect(USAGE_CSS.match(/\.axis\{font:(\d+)px/)?.[1]).toBe("11");
+    expect(narrow).toContain('class="chart-crosshair" data-crosshair');
+    expect(narrow).not.toContain('preserveAspectRatio="none"');
+    expect(renderLineChartSvg([])).toContain("No usage in this range");
+    expect(renderDonutSvg([])).toContain("No usage in this range");
+  });
+  it("renders a one-point sparkline as a flat line without an area path", () => {
+    const svg = renderSparklineSvg([0.25], "Spend");
+
+    expect(svg).toContain('<path class="spark-line" d="M0 24.0 L280 24.0"/>');
+    expect(svg).not.toContain('class="spark-area"');
+  });
+  it("renders one day as a masked point with a trend caption", () => {
+    const svg = renderLineChartSvg([{ ...bucket, key: "2026-04-01", label: "Apr 1", costUsd: 12.5 }]);
+
+    expect(svg).toContain('<circle class="chart-point" cx="440" cy="124" r="4">');
+    expect(svg).toContain('title="12.5">$12.50</text>');
+    expect(svg).toContain("Single day. Pick a longer range for a trend.");
+    expect(svg).not.toContain('class="chart-area"');
+  });
+  it("reserves enough chart space for the longest y-axis tick", () => {
+    const svg = renderLineChartSvg([{ ...bucket, costUsd: 565.47 }, { ...bucket, key: "2026-09-23", costUsd: 500 }], "costUsd", 360);
+    const ticks = [...svg.matchAll(/<text class="axis" x="([\d.]+)" y="[\d.]+" text-anchor="end" title="[\d.]+">(.*?)<\/text>/g)];
+
+    expect(ticks).toHaveLength(5);
+    for (const [, x, label] of ticks) expect(Number(x)).toBeGreaterThanOrEqual(label.length * 6.7);
+  });
+  it("keeps the last x-axis label inside the chart width", () => {
+    const rows = [
+      { ...bucket, key: "2026-09-22", costUsd: 10 },
+      { ...bucket, key: "2026-09-23", costUsd: 20 },
+    ];
+    const width = 360;
+    const svg = renderLineChartSvg(rows, "costUsd", width);
+    const labels = [...svg.matchAll(/<text class="axis" x="([\d.]+)" y="[\d.]+" text-anchor="(start|middle|end)"[^>]*>(.*?)<\/text>/g)];
+    const [, x, anchor, label] = labels.at(-1)!;
+
+    expect(label).toBe("09-23");
+    expect(anchor).toBe("end");
+    expect(Number(x)).toBeLessThanOrEqual(width);
+  });
+  it("keeps the selected chart series when a resize renders at a new width", () => {
+    const chart = createUsageChartView();
+    chart.select("totalTokens");
+    const before = chart.render([bucket], 360);
+    const after = chart.render([bucket], 1200);
+    expect(before).toContain('aria-label="totalTokens over time"');
+    expect(after).toContain('aria-label="totalTokens over time"');
+    expect(chart.getSeries()).toBe("totalTokens");
+  });
+  it("builds stable shareable query strings", () => {
+    expect(buildUsagePageSearch({ filters: { period: "7d", repo: "a/b", model: "", agent: "codex", since: "", until: "" }, by: "repo" }))
+      .toBe("?period=7d&repo=a%2Fb&agent=codex&by=repo");
+  });
 });
diff --git a/tests/usage-web.test.ts b/tests/usage-web.test.ts
index 8ae924c..feb1f7d 100644
--- a/tests/usage-web.test.ts
+++ b/tests/usage-web.test.ts
@@ -61,6 +61,25 @@ describe("usage web routes", () => {
     expect(await response.text()).toContain("/api/usage");
   });
 
+  it("passes the accepted page filters and breakdown from the URL into the page", async () => {
+    const handle = await startWebServer({
+      routes: createUsageRoutes({ fetchUsageQuery: vi.fn(async () => usageResult), cwd, now: () => now,
+        pages: [{ label: "Home", path: "/" }, { label: "Usage", path: "/usage" }] }),
+      port: 0, initialPath: "/usage", open: false, log: vi.fn(), signalTarget: new EventEmitter(), exit: vi.fn(),
+    });
+    handles.push(handle);
+    const response = await fetch(`${handle.baseUrl}/usage?period=7d&repo=work&model=m1&agent=codex&since=2026-09-01&until=2026-09-22&by=repo`);
+    const html = await response.text();
+    expect(html).toContain('"period":"7d"');
+    expect(html).toContain('"repo":"work"');
+    expect(html).toContain('"model":"m1"');
+    expect(html).toContain('"agent":"codex"');
+    expect(html).toContain('"since":"2026-09-01"');
+    expect(html).toContain('"until":"2026-09-22"');
+    expect(html).toContain('"by":"repo"');
+    expect(html).toContain('aria-current="page" class="active">Usage</a>');
+  });
+
   it.each([
     ["default today", "", { period: "today" }],
     ["all period", "?period=all", { period: "all" }],
diff --git a/tests/web-brand.test.ts b/tests/web-brand.test.ts
new file mode 100644
index 0000000..9c72a0e
--- /dev/null
+++ b/tests/web-brand.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { BRAND_CSS, LOGO_FAVICON_HREF, renderLogoSvg, renderTopBar } from "../src/web/brand.js";
+
+describe("web brand", () => {
+  it("exports the usage palette and type tokens", () => {
+    for (const token of [
+      "--bg: #000000", "--surface: #0a0a0a", "--surface-hover: #111111", "--surface-raised: #161616",
+      "--border: #1f1f1f", "--border-strong: #2e2e2e", "--grid: #1a1a1a", "--text: #ededed",
+      "--text-muted: #a1a1a1", "--text-faint: #6b6b6b", "--blue: #0070f3", "--blue-chart: #3b82f6",
+      "--success: #10b981", "--error: #e5484d", '"Geist", "Inter", ui-sans-serif',
+      '"Geist Mono", ui-monospace, "JetBrains Mono"',
+    ]) expect(BRAND_CSS).toContain(token);
+  });
+
+  it("renders the stacked deck mark with a heavier stroke at smaller sizes", () => {
+    const large = renderLogoSvg(64);
+    expect(large).toContain("m13 25 34-8 6 4-34 8zM13 32l34-8 6 4-34 8zM13 39l34-8 6 4-34 8zM13 46l34-8 6 4-34 8z");
+    expect(large).toContain('fill="#000" stroke="#ededed"');
+    expect(large).toContain('fill="#0070f3" stroke="#0070f3"');
+    expect(Number(renderLogoSvg(16).match(/stroke-width="([\d.]+)/)?.[1])).toBeGreaterThan(Number(large.match(/stroke-width="([\d.]+)/)?.[1]));
+    expect(Number(renderLogoSvg(20).match(/stroke-width="([\d.]+)/)?.[1])).toBeGreaterThan(Number(large.match(/stroke-width="([\d.]+)/)?.[1]));
+  });
+
+  it("uses the logo data URI as a favicon", () => {
+    expect(LOGO_FAVICON_HREF).toMatch(/^data:image\/svg\+xml,/);
+    expect(decodeURIComponent(LOGO_FAVICON_HREF)).toContain("#0070f3");
+  });
+
+  it("renders every nav link and escapes labels", () => {
+    const html = renderTopBar({
+      pages: [{ label: "Home", path: "/" }, { label: "Usage <today>", path: "/usage?x=1&y=2" }],
+      activePath: "/usage?x=1&y=2",
+      title: "Usage & analytics",
+    });
+    expect(html).toContain('href="/"');
+    expect(html).toContain('href="/usage?x=1&amp;y=2" aria-current="page" class="active"');
+    expect(html).toContain("Usage &lt;today&gt;");
+    expect(html).toContain("Usage &amp; analytics");
+  });
+});