feat: vendor explicit file-focus navigation + viewed/collapse shortcuts

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

@@ -1,18 +1,11 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { z } from "zod";
 import { FilesPage } from "@/routes/files-page";
 
-const filesSearchSchema = z.object({
-	scrollTo: z.string().optional(),
-});
-
 export const Route = createFileRoute("/runs/$runId/files")({
-	validateSearch: (search) => filesSearchSchema.parse(search),
 	component: FilesRoute,
 });
 
 function FilesRoute() {
 	const { runId } = Route.useParams();
-	const { scrollTo } = Route.useSearch();
-	return <FilesPage runId={runId} scrollTo={scrollTo} />;
+	return <FilesPage runId={runId} />;
 }

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

@@ -36,7 +36,7 @@ function ChaptersRoute() {
 		<div className="@container">
 			<div className="grid grid-cols-1 gap-6 @4xl:grid-cols-[minmax(0,2fr)_minmax(0,3fr)]">
 				<div className="scrollbar-thin min-w-0 @4xl:sticky @4xl:top-[var(--content-top)] @4xl:max-h-[calc(var(--main-height)_-_var(--content-top))] @4xl:overflow-y-auto @4xl:pr-4 @4xl:pb-6">
-					<PrologueSection prologue={prologue} runId={runId} />
+					<PrologueSection prologue={prologue} />
 				</div>
 				<div className="min-w-0">
 					<ChaptersIndexPage

packages/web/src/components/chapter/chapter-navigator.tsx

@@ -73,6 +73,7 @@ export function ChapterNavigator({
 						<Link
 							to="/runs/$runId/chapters/$chapterNumber"
 							params={{ runId, chapterNumber: String(prevChapter.order) }}
+							resetScroll={false}
 							className="inline-flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
 						>
 							<ChevronLeft className="size-4" />
@@ -105,6 +106,7 @@ export function ChapterNavigator({
 									<Link
 										to="/runs/$runId/chapters/$chapterNumber"
 										params={{ runId, chapterNumber: String(ch.order) }}
+										resetScroll={false}
 										className={cn("cursor-pointer", isActive && "bg-accent")}
 									>
 										<StatusBadge
@@ -146,6 +148,7 @@ export function ChapterNavigator({
 						<Link
 							to="/runs/$runId/chapters/$chapterNumber"
 							params={{ runId, chapterNumber: String(nextChapter.order) }}
+							resetScroll={false}
 							className="inline-flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
 						>
 							<ChevronRight className="size-4" />

packages/web/src/components/chapter/file-header.tsx

@@ -8,11 +8,15 @@ import {
 } from "lucide-react";
 import type { MouseEvent } from "react";
 import { useCallback } from "react";
+import { ShortcutLabel } from "@/components/keyboard/shortcut-label";
 import { LineCounts } from "@/components/shared/line-counts";
+import { ShortcutTooltip } from "@/components/shared/shortcut-tooltip";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import { FILE_STATUS, type PullRequestFile } from "@/lib/diff-types";
 import { FILE_STATUS_ICONS, FILE_STATUS_LABELS, FILE_STATUS_TEXT_COLORS } from "@/lib/file-status";
+import { SHORTCUT_KEY } from "@/lib/keyboard-shortcuts";
 import { useIsMac } from "@/lib/use-is-mac";
+import { useShortcut } from "@/lib/use-shortcut";
 import { cn } from "@/lib/utils";
 
 function CopyableFilename({
@@ -71,6 +75,7 @@ export function FileHeader({
 }: FileHeaderProps) {
 	const isMac = useIsMac();
 	const altLabel = isMac ? "⌥" : "Alt";
+	const { label: collapseShortcutLabel } = useShortcut(SHORTCUT_KEY.TOGGLE_FILE_COLLAPSED);
 
 	const copyPath = useCallback(
 		(path: string, label: string) => {
@@ -146,7 +151,10 @@ export function FileHeader({
 					</button>
 				</TooltipTrigger>
 				<TooltipContent side="top" className="text-center">
-					<p>{isCollapsed ? "Expand file" : "Collapse file"}</p>
+					<p className="flex items-center justify-center gap-1">
+						{isCollapsed ? "Expand file" : "Collapse file"}
+						<ShortcutLabel label={collapseShortcutLabel} />
+					</p>
 					<p className="text-muted-foreground">
 						{altLabel}-click to {isCollapsed ? "expand" : "collapse"} all files
 					</p>
@@ -213,27 +221,26 @@ export function FileHeader({
 				className="relative z-10 shrink-0"
 			/>
 			{onToggleViewed && (
-				<Tooltip>
-					<TooltipTrigger asChild>
-						<button
-							type="button"
-							onClick={(e) => {
-								e.stopPropagation();
-								onToggleViewed();
-							}}
-							className={cn(
-								"relative z-10 flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-md transition-colors hover:bg-accent",
-								isViewed
-									? "text-green-600 hover:text-green-700 dark:text-green-500 dark:hover:text-green-400"
-									: "text-muted-foreground hover:text-foreground",
-							)}
-							aria-label={isViewed ? "Mark file as unviewed" : "Mark file as viewed"}
-						>
-							{isViewed ? <CircleCheck className="size-3.5" /> : <Circle className="size-3.5" />}
-						</button>
-					</TooltipTrigger>
-					<TooltipContent>{isViewed ? "Mark as unviewed" : "Mark as viewed"}</TooltipContent>
-				</Tooltip>
+				<ShortcutTooltip
+					shortcutKey={SHORTCUT_KEY.MARK_FILE_AS_VIEWED}
+					label={isViewed ? "Mark as unviewed" : "Mark as viewed"}
+				>
+					<button
+						type="button"
+						onClick={(e) => {
+							e.stopPropagation();
+							onToggleViewed();
+						}}
+						className={cn(
+							"relative z-10 flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-md transition-colors hover:bg-accent",
+							isViewed
+								? "text-green-600 hover:text-green-700 dark:text-green-500 dark:hover:text-green-400"
+								: "text-muted-foreground hover:text-foreground",
+						)}
+					>
+						{isViewed ? <CircleCheck className="size-3.5" /> : <Circle className="size-3.5" />}
+					</button>
+				</ShortcutTooltip>
 			)}
 			{handleCommentClick && (
 				<Tooltip>

packages/web/src/components/files/file-diff-list.tsx

@@ -5,6 +5,7 @@ import { PierreDiffViewer } from "@/components/chapter/pierre-diff-viewer";
 import { findRenderedDiffLine } from "@/components/chapter/rendered-line-target";
 import type { AnnotatedLineRef, DiffSide, LineRef } from "@/lib/diff-types";
 import type { FileDiffEntry } from "@/lib/parse-diff";
+import { cn } from "@/lib/utils";
 
 export interface FileDiffListHandle {
 	scrollToFile: (filePath: string) => void;
@@ -41,14 +42,24 @@ interface FileDiffListProps {
 	onToggleViewed?: (path: string) => void;
 	collapseState: CollapseState;
 	chapterOverlay?: ChapterOverlayProps;
+	/** The keyboard-focused file, outlined to mark it as the active diff. */
+	focusedFilePath?: string;
 }
 
 const FILE_TOP_PADDING = 16;
 const SCROLL_TO_LINE_POLL_MS = 100;
 const SCROLL_TO_LINE_TIMEOUT_MS = 3000;
 
 export const FileDiffList = forwardRef<FileDiffListHandle, FileDiffListProps>(function FileDiffList(
-	{ entries, emptyMessage, viewedPathSet, onToggleViewed, collapseState, chapterOverlay },
+	{
+		entries,
+		emptyMessage,
+		viewedPathSet,
+		onToggleViewed,
+		collapseState,
+		chapterOverlay,
+		focusedFilePath,
+	},
 	ref,
 ) {
 	const scrollRequestRef = useRef(0);
@@ -197,6 +208,7 @@ export const FileDiffList = forwardRef<FileDiffListHandle, FileDiffListProps>(fu
 					key={entry.file.path}
 					entry={entry}
 					isViewed={viewedPathSet?.has(entry.file.path) ?? false}
+					isFocused={entry.file.path === focusedFilePath}
 					onToggleViewed={onToggleViewed}
 					collapseState={collapseState}
 					chapterOverlay={chapterOverlay}
@@ -209,6 +221,7 @@ export const FileDiffList = forwardRef<FileDiffListHandle, FileDiffListProps>(fu
 interface FileDiffSectionProps {
 	entry: FileDiffEntry;
 	isViewed: boolean;
+	isFocused: boolean;
 	onToggleViewed?: (path: string) => void;
 	collapseState: CollapseState;
 	chapterOverlay?: ChapterOverlayProps;
@@ -217,6 +230,7 @@ interface FileDiffSectionProps {
 function FileDiffSection({
 	entry,
 	isViewed,
+	isFocused,
 	onToggleViewed,
 	collapseState,
 	chapterOverlay,
@@ -239,7 +253,11 @@ function FileDiffSection({
 	}, [onToggleViewed, file.path]);
 
 	return (
-		<div id={`file-${file.path}`}>
+		<div
+			id={`file-${file.path}`}
+			data-focused-file={isFocused ? "true" : undefined}
+			className={cn("rounded-lg", isFocused && "outline-2 outline-primary/70")}
+		>
 			<FileHeader
 				file={file}
 				isCollapsed={isCollapsed}

packages/web/src/components/prologue/prologue-section.tsx

@@ -1,6 +1,5 @@
 import type { FocusArea, FocusAreaSeverity, Prologue } from "@stagereview/types/prologue";
 import { FOCUS_AREA_SEVERITY } from "@stagereview/types/prologue";
-import { Link } from "@tanstack/react-router";
 import { AlertTriangle } from "lucide-react";
 import { cn } from "@/lib/utils";
 
@@ -18,7 +17,7 @@ function getFileName(filePath: string): string {
 	return filePath.split("/").pop() ?? filePath;
 }
 
-function PrologueDisplay({ prologue, runId }: { prologue: Prologue; runId: string }) {
+function PrologueDisplay({ prologue }: { prologue: Prologue }) {
 	const concerns = getConcerns(prologue.focusAreas);
 
 	return (
@@ -81,14 +80,9 @@ function PrologueDisplay({ prologue, runId }: { prologue: Prologue; runId: strin
 									/>
 									<span className="min-w-0 truncate">{area.title}</span>
 									{area.locations[0] && (
-										<Link
-											to="/runs/$runId/files"
-											params={{ runId }}
-											search={{ scrollTo: area.locations[0] }}
-											className="ml-auto shrink-0 text-xs text-muted-foreground transition-colors hover:text-foreground"
-										>
-											{getFileName(area.locations[0])} &rarr;
-										</Link>
+										<span className="ml-auto shrink-0 text-xs text-muted-foreground">
+											{getFileName(area.locations[0])}
+										</span>
 									)}
 								</span>
 								<p className="mt-0.5 ml-6 text-xs text-muted-foreground">{area.description}</p>
@@ -103,10 +97,9 @@ function PrologueDisplay({ prologue, runId }: { prologue: Prologue; runId: strin
 
 interface PrologueSectionProps {
 	prologue: Prologue | null | undefined;
-	runId: string;
 }
 
-export function PrologueSection({ prologue, runId }: PrologueSectionProps) {
+export function PrologueSection({ prologue }: PrologueSectionProps) {
 	if (!prologue) return null;
-	return <PrologueDisplay prologue={prologue} runId={runId} />;
+	return <PrologueDisplay prologue={prologue} />;
 }