feat: Migrate web UI to TanStack Router

biome.json

@@ -17,7 +17,8 @@
       "!**/node_modules",
       "!**/dist",
       "!**/web-dist",
-      "!**/drizzle"
+      "!**/drizzle",
+      "!packages/web/src/routeTree.gen.ts"
     ]
   },
   "linter": {

packages/cli/src/show.ts

@@ -14,7 +14,7 @@ export async function show(jsonPath: string): Promise<void> {
 		routes: [...runRoutes(db), ...viewStateRoutes(db), ...diffRoutes(db)],
 	});
 	const { port } = handle;
-	const url = `http://${LOOPBACK_HOST}:${port}/#/runs/${runId}`;
+	const url = `http://${LOOPBACK_HOST}:${port}/runs/${encodeURIComponent(runId)}`;
 
 	process.stdout.write(`Listening on ${url}\n`);
 	process.stdout.write("Press Ctrl+C to exit.\n");

packages/web/package.json

@@ -21,6 +21,7 @@
     "@radix-ui/react-tooltip": "^1.2.8",
     "@stage-cli/types": "workspace:*",
     "@tanstack/react-query": "^5.100.7",
+    "@tanstack/react-router": "^1.169.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.562.0",
@@ -34,6 +35,7 @@
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/router-plugin": "^1.167.32",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.5",
     "@types/react-dom": "^19.2.3",

packages/web/src/app/__root.tsx

@@ -0,0 +1,16 @@
+import type { QueryClient } from "@tanstack/react-query";
+import { createRootRouteWithContext, Outlet } from "@tanstack/react-router";
+
+export const Route = createRootRouteWithContext<{
+	queryClient: QueryClient;
+}>()({
+	component: RootLayout,
+});
+
+function RootLayout() {
+	return (
+		<div className="flex min-h-screen flex-col bg-background text-foreground">
+			<Outlet />
+		</div>
+	);
+}

packages/web/src/app/index.tsx

@@ -0,0 +1,23 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { Topbar } from "@/components/layout/topbar";
+
+export const Route = createFileRoute("/")({
+	component: NoRunSelected,
+});
+
+function NoRunSelected() {
+	return (
+		<>
+			<Topbar runId={null} />
+			<div className="flex flex-1 items-center justify-center p-6">
+				<div className="max-w-md text-center">
+					<h1 className="font-semibold text-lg">No run selected</h1>
+					<p className="mt-2 text-muted-foreground text-sm">
+						The URL is missing a <code>/runs/&lt;runId&gt;</code> path. Open the app via{" "}
+						<code>stage-cli show &lt;path&gt;</code>.
+					</p>
+				</div>
+			</div>
+		</>
+	);
+}

packages/web/src/app/runs.$runId.files.tsx

@@ -0,0 +1,11 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { FilesPage } from "@/routes/files-page";
+
+export const Route = createFileRoute("/runs/$runId/files")({
+	component: FilesRoute,
+});
+
+function FilesRoute() {
+	const { runId } = Route.useParams();
+	return <FilesPage runId={runId} />;
+}

packages/web/src/app/runs.$runId.index.tsx

@@ -0,0 +1,29 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { useMemo } from "react";
+import { useChapters } from "@/lib/use-chapters";
+import { countViewedChapters, useViewStateData } from "@/lib/use-view-state";
+import { ChaptersIndexPage } from "@/routes/chapters-index-page";
+
+export const Route = createFileRoute("/runs/$runId/")({
+	component: ChaptersRoute,
+});
+
+function ChaptersRoute() {
+	const { runId } = Route.useParams();
+	const { data, isLoading } = useChapters(runId);
+	const { chapterIdSet } = useViewStateData(runId);
+	const chapters = data?.chapters;
+	const viewedCount = useMemo(
+		() => countViewedChapters(chapters, chapterIdSet),
+		[chapters, chapterIdSet],
+	);
+
+	return (
+		<ChaptersIndexPage
+			chapters={chapters}
+			runId={runId}
+			viewedCount={viewedCount}
+			isLoading={isLoading}
+		/>
+	);
+}

packages/web/src/app/runs.$runId.tsx

@@ -0,0 +1,17 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { Topbar } from "@/components/layout/topbar";
+import { PullRequestLayout } from "@/routes/pull-request-layout";
+
+export const Route = createFileRoute("/runs/$runId")({
+	component: RunLayout,
+});
+
+function RunLayout() {
+	const { runId } = Route.useParams();
+	return (
+		<>
+			<Topbar runId={runId} />
+			<PullRequestLayout runId={runId} />
+		</>
+	);
+}

packages/web/src/lib/use-chapters.ts

@@ -17,5 +17,6 @@ export function useChapters(runId: string | null) {
 	return useQuery<ChaptersResponse>({
 		queryKey: ["chapters", runId],
 		queryFn: runId === null ? skipToken : () => fetchChapters(runId),
+		staleTime: Number.POSITIVE_INFINITY,
 	});
 }

packages/web/src/lib/use-diff-patch.ts

@@ -17,5 +17,6 @@ export function useDiffPatch(runId: string): UseQueryResult<string> {
 			return res.text();
 		},
 		enabled: runId !== "",
+		staleTime: Number.POSITIVE_INFINITY,
 	});
 }

packages/web/src/lib/use-view-state.ts

@@ -95,6 +95,16 @@ export interface UseViewStateResult extends UseViewStateDataResult {
 	unmarkFileViewed: (filePath: string) => void;
 }
 
+export function countViewedChapters(
+	chapters: ReadonlyArray<{ externalId: string }> | undefined,
+	chapterIdSet: ReadonlySet<string>,
+): number {
+	if (!chapters) return 0;
+	let count = 0;
+	for (const c of chapters) if (chapterIdSet.has(c.externalId)) count++;
+	return count;
+}
+
 // Returns stable Sets so callers can use them as effect/memo deps.
 // Read-only — `useViewState` adds the mutation hooks on top of this.
 export function useViewStateData(runId: string): UseViewStateDataResult {

packages/web/src/main.tsx

@@ -1,33 +1,23 @@
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { RouterProvider } from "@tanstack/react-router";
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
-import { App } from "./App";
 import { ThemeProvider } from "./lib/theme";
 import { DiffSettingsProvider } from "./lib/use-diff-settings";
+import { queryClient, router } from "./router";
 import "./styles/globals.css";
 
 const rootElement = document.getElementById("root");
 if (!rootElement) {
 	throw new Error("Root element #root not found");
 }
 
-const queryClient = new QueryClient({
-	defaultOptions: {
-		queries: {
-			// Two browser tabs on the same run see synchronized state via refetch on focus
-			// (acceptance criterion). 30s staleTime keeps a single tab from re-fetching too eagerly.
-			staleTime: 30_000,
-			refetchOnWindowFocus: true,
-		},
-	},
-});
-
 createRoot(rootElement).render(
 	<StrictMode>
 		<ThemeProvider>
 			<QueryClientProvider client={queryClient}>
 				<DiffSettingsProvider>
-					<App />
+					<RouterProvider router={router} />
 				</DiffSettingsProvider>
 			</QueryClientProvider>
 		</ThemeProvider>