tokentrace 0.15.2 → 0.17.0

package/CHANGELOG.md

@@ -4,6 +4,107 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.17.0] - 2026-05-23
+
+### Performance
+
+- **Runtime SQLite pragmas tuned for analytics.** `src/db/client.ts` now
+  re-applies `journal_mode=WAL` on the live connection and sets
+  `synchronous=NORMAL`, `temp_store=MEMORY`, `cache_size=64MB`, and
+  `mmap_size=256MB`. Previously only `busy_timeout` and `foreign_keys`
+  were set on the runtime connection.
+- **Prepared-statement cache.** `src/db/prepared.ts` adds a tiny
+  `prepareCached(sql)` helper keyed by SQL string. The hot analytics,
+  unknown-cost-repair, scheduled-scan, and ingestion helpers now skip
+  the parse-and-plan cost on repeat queries.
+- **Overview page parallelization.** The independent sub-queries in
+  `getOverviewData` (analytics, accounting invariants, scan diff,
+  default search roots, repair workbench) now run through `Promise.all`,
+  so the async filesystem walk overlaps with the serialized SQLite
+  reads.
+- **Render-scoped overview memo.** `getOverviewPageData` is wrapped in
+  `React.cache` so any future composition that calls it twice within a
+  single server render tree pays the cost once.
+- **Lazy-loaded Recharts.** `TrendSection` and `RankBarChart` are now
+  loaded via `next/dynamic({ ssr: false })` on the overview, projects,
+  tools, and models routes, splitting the ~80KB Recharts bundle out of
+  the initial JS payload. `ChartSkeleton` keeps the chart slot from
+  collapsing during client hydration.
+- **Streaming overview with two `<Suspense>` boundaries.** The overview
+  page now splits into two cache-wrapped fetchers — `getOverviewPrimaryData`
+  (analytics-driven: pulse, summary, trend, trust, guardrails,
+  recommendations, mix) and `getOverviewRepairData` (workbench-driven:
+  review status, repair items). Each renders inside its own `<Suspense>`
+  so the page shell and period filter paint immediately, the primary
+  analytics block streams in next, and the repair lane streams in
+  independently when the workbench query resolves.
+- **`tokentrace doctor --timings`.** New flag force-enables analytics
+  timing capture and emits the analytics timing report (slow queries,
+  threshold, sample list). Combine with `--json` for machine-readable
+  output. Useful for before/after measurement of performance changes
+  since `TOKENTRACE_ANALYTICS_TIMING` is off by default in production.
+- **Scan ingestion throughput.** Adds a (path, size, mtime)-keyed
+  file-hash cache so rescans of unchanged files skip the `fs.readFile`
+  + SHA-256 step entirely. The hot scan-side `INSERT INTO scan_files`,
+  `INSERT INTO scan_runs`, and `hasImportedFile` lookups also route
+  through `prepareCached`.
+- **Next bundle optimizations.** Enables `optimizePackageImports` for
+  `lucide-react` (~37 import sites) and `recharts` so Next 16 transforms
+  named imports into per-symbol imports and prunes unused-symbol weight
+  from the client bundle. Adds an opt-in `@next/bundle-analyzer`
+  integration gated on `ANALYZE=true` for follow-up audits.
+- **Hot-path bug-hunt fixes.** `source-catalog.summarizeSourceCoverage`
+  was O(rows × entries); now uses a pre-built Map for O(1) parser tier
+  lookups. `ingestion/discovery.getDefaultSearchRoots` parallelizes its
+  `fs.access` checks via `Promise.all` instead of awaiting them
+  sequentially. `ingestion/persist.findProjectRoot` memoizes the
+  resolved project root by start directory, eliminating duplicate
+  filesystem walks when many imported sessions share the same source
+  directory.
+
+## [0.16.0] - 2026-05-23
+
+### Added
+
+- **Parser overrides.** Force a specific parser for a file or exclude it from
+  future scans without editing source code. Override is honored by the next
+  scan via `selectAdapter`. New surfaces:
+  - Dashboard: `Parser overrides` panel on `/parser-debug` (list, add, clear).
+  - REST: `GET / POST / DELETE /api/parser-overrides`.
+  - REST: `POST /api/parser-debug/preview` returns predicted parse output for
+    an alternate parser without writing to the local database.
+  - CLI: `tokentrace repair set-parser <path> --parser <id> [--note "..."]`,
+    `--exclude` variant, and `clear-parser <path>` (all support `--json`).
+  - File paths are normalized to absolute form so scan-resolved paths match
+    user-supplied overrides, regardless of relative vs absolute input.
+- **Saved reports.** Persisted local report templates that can be replayed
+  from the dashboard or the CLI. New surfaces:
+  - Dashboard: `/reports` page with create / list / delete.
+  - REST: `GET / POST /api/saved-reports`, `GET / DELETE /api/saved-reports/[id]`.
+  - CLI: `tokentrace report --saved "<name>" --format json|markdown|html`
+    and `tokentrace report --list-saved [--json]`.
+  - Standalone HTML report format escapes every user-supplied filter value
+    so opening or archiving the file is safe.
+  - Param keys are validated against an allow-list before persistence.
+- **Agent handoff.** Structured envelope plus action log for multi-agent
+  workflows.
+  - CLI: `tokentrace agent --handoff [--json]` returns the
+    `tokentrace.handoff.v1` envelope (scan state, repair queue, confidence,
+    recent actions, suggested next actions). Pure read.
+  - CLI: `tokentrace agent --actions [--limit N] [--json]` reads the local
+    agent action log.
+  - MCP: new `get_handoff` tool returns the same envelope; added to the
+    recommended workflow in `get_agent_guide`.
+  - Action log is bounded to the last 500 entries (configurable via
+    `TOKENTRACE_AGENT_ACTION_LOG_MAX`), token-shaped strings are redacted
+    before write, and the writer is best-effort so logging never breaks the
+    CLI command it observes. `tokentrace scan` now writes a row on completion.
+
+### Internal
+
+- Three new local SQLite tables: `file_parser_overrides`, `saved_reports`,
+  `agent_actions`. All additive migrations.
+
 ## [0.15.2] - 2026-05-23
 
 ### Fixed

package/app/api/parser-debug/preview/route.ts

@@ -0,0 +1,92 @@
+import fs from "node:fs/promises";
+import { NextResponse } from "next/server";
+import { adapters } from "@/src/ingestion/adapters";
+import type { FileCandidate, NormalizedInteraction } from "@/src/ingestion/types";
+
+export const dynamic = "force-dynamic";
+
+type PreviewBody = {
+  path?: unknown;
+  parserId?: unknown;
+};
+
+export async function POST(request: Request) {
+  let body: PreviewBody;
+  try {
+    body = (await request.json()) as PreviewBody;
+  } catch {
+    return NextResponse.json({ error: "Request body must be JSON." }, { status: 400 });
+  }
+
+  const filePath = typeof body.path === "string" ? body.path.trim() : "";
+  const parserId = typeof body.parserId === "string" ? body.parserId.trim() : "";
+
+  if (!filePath) {
+    return NextResponse.json({ error: "path is required" }, { status: 400 });
+  }
+  if (!parserId) {
+    return NextResponse.json({ error: "parserId is required" }, { status: 400 });
+  }
+
+  const adapter = adapters.find((candidate) => candidate.id === parserId);
+  if (!adapter) {
+    return NextResponse.json(
+      { error: `parser ${parserId} is not registered` },
+      { status: 404 }
+    );
+  }
+
+  let stat;
+  try {
+    stat = await fs.stat(filePath);
+  } catch {
+    return NextResponse.json({ error: `file not found: ${filePath}` }, { status: 404 });
+  }
+
+  const candidate: FileCandidate = {
+    path: filePath,
+    sizeBytes: stat.size,
+    modifiedTime: stat.mtime
+  };
+
+  let parseResult;
+  try {
+    parseResult = await adapter.parse(candidate, { storeRawMessageContent: false });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error: `parser ${parserId} threw while parsing: ${
+          error instanceof Error ? error.message : "Unknown error"
+        }`
+      },
+      { status: 422 }
+    );
+  }
+
+  const allInteractions: NormalizedInteraction[] = parseResult.sessions.flatMap(
+    (session) => session.interactions
+  );
+  const predictedTotalTokens = allInteractions.reduce(
+    (sum, interaction) => sum + (interaction.totalTokens ?? 0),
+    0
+  );
+
+  return NextResponse.json({
+    parserId,
+    path: filePath,
+    sessions: parseResult.sessions.map((session) => ({
+      externalId: session.externalId,
+      provider: session.provider,
+      tool: session.tool,
+      interactionCount: session.interactions.length,
+      totalTokens: session.interactions.reduce(
+        (sum, interaction) => sum + (interaction.totalTokens ?? 0),
+        0
+      )
+    })),
+    predictedInteractions: allInteractions.length,
+    predictedTotalTokens,
+    warnings: parseResult.warnings,
+    errors: parseResult.errors
+  });
+}

package/app/api/parser-overrides/route.ts

@@ -0,0 +1,65 @@
+import { NextResponse } from "next/server";
+import {
+  clearParserOverride,
+  listParserOverrides,
+  setParserOverride
+} from "@/src/lib/parser-overrides";
+
+export const dynamic = "force-dynamic";
+
+type WriteBody = {
+  path?: unknown;
+  parserId?: unknown;
+  excluded?: unknown;
+  note?: unknown;
+};
+
+export async function GET() {
+  return NextResponse.json({ overrides: listParserOverrides() });
+}
+
+export async function POST(request: Request) {
+  let body: WriteBody;
+  try {
+    body = (await request.json()) as WriteBody;
+  } catch {
+    return NextResponse.json({ error: "Request body must be JSON." }, { status: 400 });
+  }
+
+  const path = typeof body.path === "string" ? body.path.trim() : "";
+  if (!path) return NextResponse.json({ error: "path is required" }, { status: 400 });
+
+  const excluded = body.excluded === true;
+  const parserId =
+    !excluded && typeof body.parserId === "string" && body.parserId.trim()
+      ? body.parserId.trim()
+      : undefined;
+  const note = typeof body.note === "string" && body.note.trim() ? body.note.trim() : undefined;
+
+  if (!excluded && !parserId) {
+    return NextResponse.json({ error: "parserId or excluded must be provided" }, { status: 400 });
+  }
+
+  try {
+    const override = setParserOverride({ path, parserId, excluded, note });
+    return NextResponse.json({ override });
+  } catch (error) {
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : "Failed to set parser override" },
+      { status: 400 }
+    );
+  }
+}
+
+export async function DELETE(request: Request) {
+  let body: { path?: unknown };
+  try {
+    body = (await request.json()) as { path?: unknown };
+  } catch {
+    return NextResponse.json({ error: "Request body must be JSON." }, { status: 400 });
+  }
+  const path = typeof body.path === "string" ? body.path.trim() : "";
+  if (!path) return NextResponse.json({ error: "path is required" }, { status: 400 });
+  const removed = clearParserOverride(path);
+  return NextResponse.json({ removed, path });
+}

package/app/api/saved-reports/[id]/route.ts

@@ -0,0 +1,20 @@
+import { NextResponse } from "next/server";
+import { deleteSavedReport, findSavedReportById } from "@/src/lib/saved-reports-store";
+
+export const dynamic = "force-dynamic";
+
+type RouteContext = { params: Promise<{ id: string }> };
+
+export async function GET(_request: Request, context: RouteContext) {
+  const { id } = await context.params;
+  const report = findSavedReportById(id);
+  if (!report) return NextResponse.json({ error: "saved report not found" }, { status: 404 });
+  return NextResponse.json({ report });
+}
+
+export async function DELETE(_request: Request, context: RouteContext) {
+  const { id } = await context.params;
+  const removed = deleteSavedReport(id);
+  if (!removed) return NextResponse.json({ error: "saved report not found" }, { status: 404 });
+  return NextResponse.json({ removed: true, id });
+}

package/app/api/saved-reports/route.ts

@@ -0,0 +1,34 @@
+import { NextResponse } from "next/server";
+import { createSavedReport, listSavedReports } from "@/src/lib/saved-reports-store";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  return NextResponse.json({ reports: listSavedReports() });
+}
+
+export async function POST(request: Request) {
+  let body: Record<string, unknown>;
+  try {
+    body = (await request.json()) as Record<string, unknown>;
+  } catch {
+    return NextResponse.json({ error: "Request body must be JSON." }, { status: 400 });
+  }
+
+  const name = typeof body.name === "string" ? body.name : "";
+  const viewType = typeof body.viewType === "string" ? body.viewType : "";
+  const format = typeof body.format === "string" ? body.format : undefined;
+  const params =
+    body.params && typeof body.params === "object" && !Array.isArray(body.params)
+      ? (body.params as Record<string, string | number | boolean>)
+      : undefined;
+
+  try {
+    const report = createSavedReport({ name, viewType, format, params });
+    return NextResponse.json({ report }, { status: 201 });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Failed to create saved report";
+    const status = /already exists/i.test(message) ? 409 : 400;
+    return NextResponse.json({ error: message }, { status });
+  }
+}

package/app/models/page.tsx

@@ -3,7 +3,7 @@ import { EmptyState } from "@/components/empty-state";
 import { ScanNowButton } from "@/components/scan-now-button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
-import { RankBarChart } from "@/components/charts/rank-bar-chart";
+import { RankBarChart } from "@/components/charts/rank-bar-chart-lazy";
 import { PageHeader } from "@/components/ui/typography";
 import { getAnalyticsData } from "@/src/lib/analytics";
 import { formatCurrency, formatTokens } from "@/src/lib/format";

package/app/page.tsx

@@ -1,12 +1,17 @@
+import { Suspense } from "react";
 import Link from "next/link";
 import { ArrowRight } from "lucide-react";
-import { TrendSection } from "@/components/charts/trend-section";
+import { TrendSection } from "@/components/charts/trend-section-lazy";
 import { OverviewCurrentMixPanel } from "@/components/overview/current-mix-panel";
 import { DataConfidenceStrip } from "@/components/overview/data-confidence-strip";
 import { FirstRunPanel } from "@/components/overview/first-run-panel";
 import { UsageGuardrailsPanel } from "@/components/overview/guardrails-panel";
 import { OverviewRecommendationsCard } from "@/components/overview/recommendations-card";
 import { OverviewReviewStatusStrip } from "@/components/overview/review-status-strip";
+import {
+  OverviewPrimarySkeleton,
+  OverviewRepairSkeleton
+} from "@/components/overview/section-skeletons";
 import { CostSessionsCard, TokenAccountingCard } from "@/components/overview/summary-cards";
 import { TopRepairItemsStrip } from "@/components/overview/top-repair-items-strip";
 import { OverviewTrustFooter } from "@/components/overview/trust-footer";
@@ -14,9 +19,9 @@ import { UsagePulsePanel } from "@/components/overview/usage-pulse-panel";
 import { PeriodFilter } from "@/components/period-filter";
 import { Button } from "@/components/ui/button";
 import { PageHeader } from "@/components/ui/typography";
-import { resolveDateRange } from "@/src/lib/date-range";
+import { mergeHrefParams, type ResolvedDateRange, resolveDateRange } from "@/src/lib/date-range";
 import { runDueScheduledScan } from "@/src/lib/scheduled-scan";
-import { getOverviewPageData } from "@/src/lib/overview-data";
+import { getOverviewPrimaryData, getOverviewRepairData } from "@/src/lib/overview-data";
 
 export const dynamic = "force-dynamic";
 
@@ -24,51 +29,24 @@ type OverviewPageProps = {
   searchParams?: Promise<Record<string, string | string[] | undefined>>;
 };
 
-export default async function OverviewPage({ searchParams }: OverviewPageProps) {
-  void runDueScheduledScan().catch(() => undefined);
-  const params = (await searchParams) ?? {};
-  const range = resolveDateRange(params);
-  const overview = await getOverviewPageData(range);
+async function OverviewPrimarySection({ range }: { range: ResolvedDateRange }) {
   const {
     data,
     trust,
-    accountingReport,
-    postSessionReview,
-    rangeLinkParams,
     evidenceLinks,
-    doctorReport,
-    repairWorkbench,
-    repairFocusHref,
-    unknownCostEvidenceHref,
     firstRunStatus,
     summary,
-    trendDefaultWindow
-  } = overview;
+    trendDefaultWindow,
+    unknownCostEvidenceHref,
+    rangeLinkParams
+  } = await getOverviewPrimaryData(range);
+  const repairFocusHref = mergeHrefParams("/repair", rangeLinkParams);
 
   return (
     <div className="space-y-8">
-      <PageHeader
-        title="Overview"
-        description="Local token, cost, model, and session analytics across AI CLI tools."
-        actions={
-          <Button asChild>
-            <Link href="/settings#scan-controls">
-              Configure scan <ArrowRight className="h-4 w-4" />
-            </Link>
-          </Button>
-        }
-      />
-
-      <PeriodFilter range={range} />
-
-      {summary.interactions === 0 ? (
-        <FirstRunPanel status={firstRunStatus} />
-      ) : null}
-
+      {summary.interactions === 0 ? <FirstRunPanel status={firstRunStatus} /> : null}
       <UsagePulsePanel comparison={data.comparison} />
-
       <DataConfidenceStrip confidence={data.dataConfidence} />
-
       <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-6">
         <TokenAccountingCard
           summary={summary}
@@ -84,11 +62,38 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
           sessionsHref={evidenceLinks.sessions}
         />
       </div>
-
       <OverviewTrustFooter health={trust.health} pricedModelCount={trust.pricedModelCount} />
-
       <TrendSection data={data.trends} defaultWindow={trendDefaultWindow} />
+      <UsageGuardrailsPanel progress={data.usageGuardrails} />
+      <OverviewRecommendationsCard recommendations={data.recommendations} />
+      <OverviewCurrentMixPanel
+        tools={data.tools}
+        mostUsedTool={summary.mostUsedTool}
+        mostUsedModel={summary.mostUsedModel}
+      />
+    </div>
+  );
+}
+
+async function OverviewRepairSection({ range }: { range: ResolvedDateRange }) {
+  const {
+    accountingReport,
+    postSessionReview,
+    doctorReport,
+    repairWorkbench,
+    repairFocusHref,
+    evidenceLinks,
+    summary,
+    trust,
+    rangeLinkParams
+  } = await getOverviewRepairData(range);
 
+  if (summary.interactions === 0 && repairWorkbench.groups.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="space-y-8">
       {summary.interactions > 0 ? (
         <OverviewReviewStatusStrip
           report={doctorReport}
@@ -102,7 +107,6 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
           cachedEvidenceHref={evidenceLinks["cached-tokens"]}
         />
       ) : null}
-
       {repairWorkbench.groups.length ? (
         <TopRepairItemsStrip
           groups={repairWorkbench.groups}
@@ -110,17 +114,38 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
           rangeLinkParams={rangeLinkParams}
         />
       ) : null}
+    </div>
+  );
+}
 
-      <UsageGuardrailsPanel progress={data.usageGuardrails} />
-
-      <OverviewRecommendationsCard recommendations={data.recommendations} />
+export default async function OverviewPage({ searchParams }: OverviewPageProps) {
+  void runDueScheduledScan().catch(() => undefined);
+  const params = (await searchParams) ?? {};
+  const range = resolveDateRange(params);
 
-      <OverviewCurrentMixPanel
-        tools={data.tools}
-        mostUsedTool={summary.mostUsedTool}
-        mostUsedModel={summary.mostUsedModel}
+  return (
+    <div className="space-y-8">
+      <PageHeader
+        title="Overview"
+        description="Local token, cost, model, and session analytics across AI CLI tools."
+        actions={
+          <Button asChild>
+            <Link href="/settings#scan-controls">
+              Configure scan <ArrowRight className="h-4 w-4" />
+            </Link>
+          </Button>
+        }
       />
 
+      <PeriodFilter range={range} />
+
+      <Suspense fallback={<OverviewPrimarySkeleton />}>
+        <OverviewPrimarySection range={range} />
+      </Suspense>
+
+      <Suspense fallback={<OverviewRepairSkeleton />}>
+        <OverviewRepairSection range={range} />
+      </Suspense>
     </div>
   );
 }

package/app/parser-debug/page.tsx

@@ -4,7 +4,10 @@ import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@
 import { MonoText, PageHeader } from "@/components/ui/typography";
 import { EmptyState } from "@/components/empty-state";
 import { ScanNowButton } from "@/components/scan-now-button";
+import { ParserOverridesPanel } from "@/components/parser-debug/parser-overrides-panel";
 import { getScanTrustData } from "@/src/lib/analytics";
+import { adapters } from "@/src/ingestion/adapters";
+import { listParserOverrides } from "@/src/lib/parser-overrides";
 
 export const dynamic = "force-dynamic";
 
@@ -16,6 +19,11 @@ export default async function ParserDebugPage({
   const params = await searchParams;
   const selectedSource = params?.source;
   const { scanFiles, health } = getScanTrustData();
+  const initialOverrides = listParserOverrides();
+  const parserOptions = adapters.map((adapter) => ({
+    id: adapter.id,
+    displayName: adapter.displayName
+  }));
   const visibleScanFiles = selectedSource
     ? scanFiles.filter((file) => file.path === selectedSource)
     : scanFiles.slice(0, 500);
@@ -30,6 +38,8 @@ export default async function ParserDebugPage({
         description="Inspect adapter selection, parser confidence, extracted tokens, warnings, and failures."
       />
 
+      <ParserOverridesPanel initialOverrides={initialOverrides} parsers={parserOptions} />
+
       <div className="rounded-md border bg-card p-3">
         <div className="text-sm font-medium">Latest parser mix</div>
         <div className="mt-2 flex flex-wrap gap-2">

package/app/projects/page.tsx

@@ -1,5 +1,5 @@
 import Link from "next/link";
-import { RankBarChart } from "@/components/charts/rank-bar-chart";
+import { RankBarChart } from "@/components/charts/rank-bar-chart-lazy";
 import { TrendChart } from "@/components/charts/trend-chart";
 import { EmptyState } from "@/components/empty-state";
 import { ScanNowButton } from "@/components/scan-now-button";

package/app/reports/page.tsx

@@ -0,0 +1,19 @@
+import { PageHeader } from "@/components/ui/typography";
+import { SavedReportsPanel } from "@/components/reports/saved-reports-panel";
+import { listSavedReports } from "@/src/lib/saved-reports-store";
+
+export const dynamic = "force-dynamic";
+
+export default async function ReportsPage() {
+  const reports = listSavedReports();
+
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Reports"
+        description="Save reusable local report templates and replay them from the CLI."
+      />
+      <SavedReportsPanel initial={reports} />
+    </div>
+  );
+}

package/app/tools/page.tsx

@@ -1,4 +1,4 @@
-import { RankBarChart } from "@/components/charts/rank-bar-chart";
+import { RankBarChart } from "@/components/charts/rank-bar-chart-lazy";
 import { EmptyState } from "@/components/empty-state";
 import { ScanNowButton } from "@/components/scan-now-button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";

package/components/charts/rank-bar-chart-lazy.tsx

@@ -0,0 +1,9 @@
+"use client";
+
+import dynamic from "next/dynamic";
+import { ChartSkeleton } from "@/components/charts/skeleton";
+
+export const RankBarChart = dynamic(
+  () => import("./rank-bar-chart").then((m) => m.RankBarChart),
+  { ssr: false, loading: () => <ChartSkeleton heightClass="h-60" label="Loading chart…" /> }
+);

package/components/charts/skeleton.tsx

@@ -0,0 +1,16 @@
+type ChartSkeletonProps = {
+  heightClass?: string;
+  label?: string;
+};
+
+export function ChartSkeleton({ heightClass = "h-64", label = "Loading chart…" }: ChartSkeletonProps) {
+  return (
+    <div
+      className={`flex items-center justify-center rounded-md border border-dashed border-muted-foreground/30 bg-muted/30 text-xs text-muted-foreground ${heightClass}`}
+      role="status"
+      aria-live="polite"
+    >
+      {label}
+    </div>
+  );
+}

package/components/charts/trend-section-lazy.tsx

@@ -0,0 +1,9 @@
+"use client";
+
+import dynamic from "next/dynamic";
+import { ChartSkeleton } from "@/components/charts/skeleton";
+
+export const TrendSection = dynamic(
+  () => import("./trend-section").then((m) => m.TrendSection),
+  { ssr: false, loading: () => <ChartSkeleton heightClass="h-72" label="Loading trend chart…" /> }
+);

package/components/overview/current-mix-panel.tsx

@@ -1,5 +1,5 @@
 import Link from "next/link";
-import { RankBarChart } from "@/components/charts/rank-bar-chart";
+import { RankBarChart } from "@/components/charts/rank-bar-chart-lazy";
 import { Badge } from "@/components/ui/badge";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";

package/components/overview/section-skeletons.tsx

@@ -0,0 +1,35 @@
+type SectionSkeletonProps = {
+  heightClass?: string;
+  label: string;
+};
+
+export function OverviewSectionSkeleton({ heightClass = "h-48", label }: SectionSkeletonProps) {
+  return (
+    <div
+      className={`flex items-center justify-center rounded-md border border-dashed border-muted-foreground/30 bg-muted/30 text-xs text-muted-foreground ${heightClass}`}
+      role="status"
+      aria-live="polite"
+    >
+      {label}
+    </div>
+  );
+}
+
+export function OverviewPrimarySkeleton() {
+  return (
+    <div className="space-y-6">
+      <OverviewSectionSkeleton heightClass="h-20" label="Loading usage pulse…" />
+      <OverviewSectionSkeleton heightClass="h-36" label="Loading summary cards…" />
+      <OverviewSectionSkeleton heightClass="h-72" label="Loading trend chart…" />
+    </div>
+  );
+}
+
+export function OverviewRepairSkeleton() {
+  return (
+    <div className="space-y-6">
+      <OverviewSectionSkeleton heightClass="h-24" label="Loading review status…" />
+      <OverviewSectionSkeleton heightClass="h-40" label="Loading repair items…" />
+    </div>
+  );
+}