feat: replace screen state machine with React Router v7 URL routing

- Install react-router-dom
- Add slugify utility with full TDD test suite (7 tests)
- Wrap app in BrowserRouter in main.tsx
- Add optional onNavigate prop to ExamRunner.goTo
- Create ExamRoute component (deep-link restore + back/forward sync)
- Migrate App.tsx: replace screen useState with <Routes>, all setScreen()
  calls replaced with navigate(), add activateExam for deep-link activation,
  use useLocation for verify/reset-password special layouts
- Remove unused AppScreen type from types.ts

frontend/src/App.tsx

@@ -1,57 +1,72 @@
-import { useState, useEffect, useCallback } from 'react'
-import type { AppScreen, Exam, ExamState, HistoryEntry, Tweaks } from './types'
-import { gradeQuestion } from './utils/grading'
-import { loadState, saveState, clearState, loadHistory, appendHistory, clearHistory } from './utils/storage'
-import { apiFetch, isAuthenticated } from './utils/api'
-import { AuthProvider, useAuth } from './contexts/AuthContext'
-import Landing from './components/Landing'
-import ExamRunner from './components/ExamRunner'
-import Results from './components/Results'
-import TweaksPanel from './components/TweaksPanel'
-import AuthModal from './components/AuthModal'
-import EmailVerify from './components/EmailVerify'
-import ResetPassword from './components/ResetPassword'
-import AdminDashboard from './components/AdminDashboard'
+import { useState, useEffect, useCallback } from "react";
+import {
+  useNavigate,
+  useLocation,
+  Routes,
+  Route,
+  Navigate,
+} from "react-router-dom";
+import type { Exam, ExamState, HistoryEntry, Tweaks } from "./types";
+import { gradeQuestion } from "./utils/grading";
+import {
+  loadState,
+  saveState,
+  clearState,
+  loadHistory,
+  appendHistory,
+  clearHistory,
+} from "./utils/storage";
+import { apiFetch, isAuthenticated } from "./utils/api";
+import { slugify } from "./utils/slug";
+import { AuthProvider, useAuth } from "./contexts/AuthContext";
+import Landing from "./components/Landing";
+import ExamRoute from "./components/ExamRoute";
+import Results from "./components/Results";
+import TweaksPanel from "./components/TweaksPanel";
+import AuthModal from "./components/AuthModal";
+import EmailVerify from "./components/EmailVerify";
+import ResetPassword from "./components/ResetPassword";
+import AdminDashboard from "./components/AdminDashboard";
 
-const DEFAULT_TWEAKS: Tweaks = { theme: 'light', fontSize: 'medium', feedbackMode: 'auto' }
+const DEFAULT_TWEAKS: Tweaks = {
+  theme: "light",
+  fontSize: "medium",
+  feedbackMode: "auto",
+};
 
 const withNotes = (state: ExamState): ExamState => ({
   ...state,
-  notes: state.notes ?? '',
-})
+  notes: state.notes ?? "",
+});
 
 function AppInner() {
-  const { user, loading: authLoading, logout } = useAuth()
-  const [screen, setScreen] = useState<AppScreen>('landing')
-  const [exam, setExam] = useState<Exam | null>(null)
-  const [examState, setExamState] = useState<ExamState | null>(null)
-  const [history, setHistory] = useState<HistoryEntry[]>(() => loadHistory())
-  const [tweaks, setTweaks] = useState<Tweaks>(DEFAULT_TWEAKS)
-  const [tweaksOpen, setTweaksOpen] = useState(false)
-  const [authModalOpen, setAuthModalOpen] = useState(false)
-  const [userMenuOpen, setUserMenuOpen] = useState(false)
+  const { user, loading: authLoading, logout } = useAuth();
+  const navigate = useNavigate();
+  const { pathname } = useLocation();
+  const [exam, setExam] = useState<Exam | null>(null);
+  const [examState, setExamState] = useState<ExamState | null>(null);
+  const [history, setHistory] = useState<HistoryEntry[]>(() => loadHistory());
+  const [tweaks, setTweaks] = useState<Tweaks>(DEFAULT_TWEAKS);
+  const [tweaksOpen, setTweaksOpen] = useState(false);
+  const [authModalOpen, setAuthModalOpen] = useState(false);
+  const [userMenuOpen, setUserMenuOpen] = useState(false);
 
-  // Check URL for verify/reset-password routes on mount
-  useEffect(() => {
-    const path = globalThis.location.pathname
-    const search = globalThis.location.search
-    if (path === '/verify' || search.includes('token=') && path === '/verify') {
-      setScreen('verify')
-    } else if (path === '/reset-password') {
-      setScreen('reset-password')
-    } else if (path === '/admin') {
-      setScreen('admin')
-    }
-  }, [])
-
-  // Load history from API when authenticated
   useEffect(() => {
     if (!authLoading && user && isAuthenticated()) {
-      apiFetch<{ results: Array<{
-        id: number; title: string; score_points: number; total_points: number;
-        correct_count: number; graded_count: number; passing_score: number;
-        elapsed_ms: number; completed_at: number; exam_id: number | null;
-      }> }>('/api/results')
+      apiFetch<{
+        results: Array<{
+          id: number;
+          title: string;
+          score_points: number;
+          total_points: number;
+          correct_count: number;
+          graded_count: number;
+          passing_score: number;
+          elapsed_ms: number;
+          completed_at: number;
+          exam_id: number | null;
+        }>;
+      }>("/api/results")
         .then((data) => {
           const apiHistory: HistoryEntry[] = data.results.map((r) => ({
             id: String(r.id),
@@ -64,75 +79,111 @@ function AppInner() {
             scorePoints: r.score_points,
             passingScore: r.passing_score,
             exam: { title: r.title, questions: [] } as unknown as Exam,
-            state: { currentIdx: 0, answers: {}, flags: {}, notes: '', startedAt: 0, feedbackMode: 'end' as const } as ExamState,
+            state: {
+              currentIdx: 0,
+              answers: {},
+              flags: {},
+              notes: "",
+              startedAt: 0,
+              feedbackMode: "end" as const,
+            } as ExamState,
             _remoteId: r.id,
-          }))
-          setHistory(apiHistory)
+          }));
+          setHistory(apiHistory);
         })
         .catch(() => {
-          // Fall back to localStorage
-          setHistory(loadHistory())
-        })
+          setHistory(loadHistory());
+        });
     }
-  }, [user, authLoading])
+  }, [user, authLoading]);
 
   useEffect(() => {
-    document.documentElement.dataset['theme'] = tweaks.theme
-    const sizeMap: Record<string, string> = { small: '14px', medium: '15px', large: '17px' }
-    document.body.style.fontSize = sizeMap[tweaks.fontSize] ?? '15px'
-  }, [tweaks])
+    document.documentElement.dataset["theme"] = tweaks.theme;
+    const sizeMap: Record<string, string> = {
+      small: "14px",
+      medium: "15px",
+      large: "17px",
+    };
+    document.body.style.fontSize = sizeMap[tweaks.fontSize] ?? "15px";
+  }, [tweaks]);
 
   useEffect(() => {
-    if (screen === 'exam' && exam && examState) saveState({ exam, state: examState })
-  }, [exam, examState, screen])
+    if (pathname.startsWith("/exam/") && exam && examState)
+      saveState({ exam, state: examState });
+  }, [exam, examState, pathname]);
 
   const updateTweak = <K extends keyof Tweaks>(key: K, value: Tweaks[K]) =>
-    setTweaks((t) => ({ ...t, [key]: value }))
+    setTweaks((t) => ({ ...t, [key]: value }));
 
-  const setExamStateStrict: React.Dispatch<React.SetStateAction<ExamState>> = (nextState) => {
+  const setExamStateStrict: React.Dispatch<React.SetStateAction<ExamState>> = (
+    nextState,
+  ) => {
     setExamState((prev) => {
-      if (!prev) return prev
-      return typeof nextState === 'function'
+      if (!prev) return prev;
+      return typeof nextState === "function"
         ? (nextState as (prevState: ExamState) => ExamState)(prev)
-        : nextState
-    })
-  }
+        : nextState;
+    });
+  };
+
+  const activateExam = (data: Exam, state: ExamState) => {
+    setExam(data);
+    setExamState(withNotes(state));
+  };
 
   const loadExam = (data: Exam) => {
-    const fm = tweaks.feedbackMode === 'auto' ? (data.feedbackMode ?? 'end') : tweaks.feedbackMode
-    setExam(data)
-    setExamState({ currentIdx: 0, answers: {}, flags: {}, notes: '', revealed: {}, startedAt: Date.now(), feedbackMode: fm })
-    setScreen('exam')
-  }
+    const fm =
+      tweaks.feedbackMode === "auto"
+        ? (data.feedbackMode ?? "end")
+        : tweaks.feedbackMode;
+    setExam(data);
+    setExamState({
+      currentIdx: 0,
+      answers: {},
+      flags: {},
+      notes: "",
+      revealed: {},
+      startedAt: Date.now(),
+      feedbackMode: fm,
+    });
+    navigate(`/exam/${slugify(data.title)}/q1`);
+  };
 
   const resume = () => {
-    const saved = loadState()
-    if (saved?.exam && saved?.state) { setExam(saved.exam); setExamState(withNotes(saved.state)); setScreen('exam') }
-  }
+    const saved = loadState();
+    if (saved?.exam && saved?.state) {
+      setExam(saved.exam);
+      setExamState(withNotes(saved.state));
+      navigate(
+        `/exam/${slugify(saved.exam.title)}/q${saved.state.currentIdx + 1}`,
+      );
+    }
+  };
 
   const submit = useCallback(() => {
-    if (!exam || !examState) return
-    const completedAt = Date.now()
-    const elapsedMs = completedAt - examState.startedAt
-    const graded = exam.questions.map((q) => gradeQuestion(q, examState.answers[q.id]))
+    if (!exam || !examState) return;
+    const completedAt = Date.now();
+    const elapsedMs = completedAt - examState.startedAt;
+    const graded = exam.questions.map((q) =>
+      gradeQuestion(q, examState.answers[q.id]),
+    );
     const entry: HistoryEntry = {
       id: `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
       title: exam.title,
       completedAt,
       elapsedMs,
-      gradedCount: graded.filter((r) => r.status !== 'ungraded').length,
+      gradedCount: graded.filter((r) => r.status !== "ungraded").length,
       correctCount: graded.filter((r) => r.correct).length,
       totalPoints: exam.questions.reduce((a, q) => a + (q.points ?? 1), 0),
       scorePoints: graded.reduce((a, r) => a + r.points, 0),
       passingScore: exam.passingScore ?? 60,
       exam,
       state: { ...examState, completedAt },
-    }
+    };
 
-    // Save to API if authenticated
     if (user && isAuthenticated()) {
-      void apiFetch('/api/results', {
-        method: 'POST',
+      void apiFetch("/api/results", {
+        method: "POST",
         body: JSON.stringify({
           title: entry.title,
           scorePoints: entry.scorePoints,
@@ -146,59 +197,73 @@ function AppInner() {
           exam: entry.exam,
         }),
       }).catch(() => {
-        // Fallback: save locally
-        appendHistory(entry)
-      })
+        appendHistory(entry);
+      });
     } else {
-      appendHistory(entry)
+      appendHistory(entry);
     }
 
-    // Always update local state for immediate display
-    setHistory((prev) => [entry, ...prev])
-    clearState()
-    setExamState((s) => s ? { ...s, completedAt } : s)
-    setScreen('results')
-  }, [exam, examState, user])
+    setHistory((prev) => [entry, ...prev]);
+    clearState();
+    setExamState((s) => (s ? { ...s, completedAt } : s));
+    navigate("/results");
+  }, [exam, examState, user, navigate]);
 
-  const exit = () => { setScreen('landing'); setExam(null); setExamState(null) }
-  const restart = () => { if (exam) loadExam(exam) }
+  const exit = () => {
+    setExam(null);
+    setExamState(null);
+    navigate("/");
+  };
+
+  const restart = () => {
+    if (exam) loadExam(exam);
+  };
 
   const reviewAttempt = (entry: HistoryEntry) => {
-    // If this is a remote result, fetch full data
-    const remoteId = (entry as HistoryEntry & { _remoteId?: number })._remoteId
+    const remoteId = (entry as HistoryEntry & { _remoteId?: number })._remoteId;
     if (remoteId && user && isAuthenticated()) {
       void apiFetch<{
-        exam: Exam; state: ExamState; title: string; scorePoints: number; totalPoints: number;
-        correctCount: number; gradedCount: number; passingScore: number; elapsedMs: number; completedAt: number;
+        exam: Exam;
+        state: ExamState;
+        title: string;
+        scorePoints: number;
+        totalPoints: number;
+        correctCount: number;
+        gradedCount: number;
+        passingScore: number;
+        elapsedMs: number;
+        completedAt: number;
       }>(`/api/results/${remoteId}`)
         .then((data) => {
-          setExam(data.exam)
-          setExamState(withNotes(data.state))
-          setScreen('review')
+          setExam(data.exam);
+          setExamState(withNotes(data.state));
+          navigate(`/review/${slugify(entry.title)}`);
         })
         .catch(() => {
-          // Fallback to local data
-          setExam(entry.exam); setExamState(withNotes(entry.state)); setScreen('review')
-        })
+          setExam(entry.exam);
+          setExamState(withNotes(entry.state));
+          navigate(`/review/${slugify(entry.title)}`);
+        });
     } else {
-      setExam(entry.exam); setExamState(withNotes(entry.state)); setScreen('review')
+      setExam(entry.exam);
+      setExamState(withNotes(entry.state));
+      navigate(`/review/${slugify(entry.title)}`);
     }
-  }
+  };
 
   const clearAllHistory = () => {
-    if (confirm('Clear all past attempts?')) {
-      clearHistory()
-      setHistory([])
+    if (confirm("Clear all past attempts?")) {
+      clearHistory();
+      setHistory([]);
     }
-  }
+  };
 
   const handleAuthFlowDone = () => {
-    globalThis.history.replaceState({}, '', '/')
-    setScreen('landing')
-    setAuthModalOpen(true)
-  }
+    navigate("/");
+    setAuthModalOpen(true);
+  };
 
-  if (screen === 'verify') {
+  if (pathname === "/verify") {
     return (
       <div className="shell">
         <header className="topbar">
@@ -209,10 +274,10 @@ function AppInner() {
         </header>
         <EmailVerify onDone={handleAuthFlowDone} />
       </div>
-    )
+    );
   }
 
-  if (screen === 'reset-password') {
+  if (pathname === "/reset-password") {
     return (
       <div className="shell">
         <header className="topbar">
@@ -223,7 +288,7 @@ function AppInner() {
         </header>
         <ResetPassword onDone={handleAuthFlowDone} />
       </div>
-    )
+    );
   }
 
   return (
@@ -235,24 +300,47 @@ function AppInner() {
             className="brand-name"
             onClick={exit}
             aria-label="Home"
-            style={{ background: 'none', border: 'none', padding: 0, margin: 0, cursor: 'pointer', font: 'inherit', color: 'inherit' }}
+            style={{
+              background: "none",
+              border: "none",
+              padding: 0,
+              margin: 0,
+              cursor: "pointer",
+              font: "inherit",
+              color: "inherit",
+            }}
           >
             BrainWave
           </button>
-          <span className="faint mono" style={{ fontSize: 11, marginLeft: 4 }}>/ practice</span>
+          <span className="faint mono" style={{ fontSize: 11, marginLeft: 4 }}>
+            / practice
+          </span>
         </div>
         <div className="topbar-meta">
-          {screen === 'exam' && exam && (
+          {pathname.startsWith("/exam/") && exam && (
             <>
-              <span className="mono" style={{ fontSize: 12 }}>{exam.title}</span>
-              <button className="btn btn-ghost btn-sm" onClick={exit}>Exit</button>
+              <span className="mono" style={{ fontSize: 12 }}>
+                {exam.title}
+              </span>
+              <button className="btn btn-ghost btn-sm" onClick={exit}>
+                Exit
+              </button>
             </>
           )}
-          <button className="btn btn-ghost btn-sm" onClick={() => setTweaksOpen((o) => !o)} style={{ marginLeft: 8 }} aria-label="Tweaks">⚙</button>
+          <button
+            className="btn btn-ghost btn-sm"
+            onClick={() => setTweaksOpen((o) => !o)}
+            style={{ marginLeft: 8 }}
+            aria-label="Tweaks"
+          >
+            ⚙
+          </button>
 
-          {/* Auth buttons */}
           {!authLoading && !user && (
-            <button className="btn btn-primary btn-sm" onClick={() => setAuthModalOpen(true)}>
+            <button
+              className="btn btn-primary btn-sm"
+              onClick={() => setAuthModalOpen(true)}
+            >
               Sign In
             </button>
           )}
@@ -266,48 +354,125 @@ function AppInner() {
                 {user.displayName.charAt(0).toUpperCase()}
               </button>
               {userMenuOpen && (
-                  <div className="user-menu">
-                    <div className="user-menu-header">
-                      <div className="user-menu-name">{user.displayName}</div>
-                      <div className="user-menu-email">{user.email}</div>
-                    </div>
-                    <div className="user-menu-divider" />
-                    {user.role === 'admin' && (
-                      <button className="user-menu-item" onClick={() => { setUserMenuOpen(false); setScreen('admin'); globalThis.history.pushState({}, '', '/admin') }}>
-                        Admin Dashboard
-                      </button>
-                    )}
-                    <button className="user-menu-item" onClick={() => { setUserMenuOpen(false); logout() }}>
-                      Sign Out
-                    </button>
+                <div className="user-menu">
+                  <div className="user-menu-header">
+                    <div className="user-menu-name">{user.displayName}</div>
+                    <div className="user-menu-email">{user.email}</div>
                   </div>
+                  <div className="user-menu-divider" />
+                  {user.role === "admin" && (
+                    <button
+                      className="user-menu-item"
+                      onClick={() => {
+                        setUserMenuOpen(false);
+                        navigate("/admin");
+                      }}
+                    >
+                      Admin Dashboard
+                    </button>
+                  )}
+                  <button
+                    className="user-menu-item"
+                    onClick={() => {
+                      setUserMenuOpen(false);
+                      logout();
+                    }}
+                  >
+                    Sign Out
+                  </button>
+                </div>
               )}
             </div>
           )}
         </div>
       </header>
 
-      {screen === 'landing' && (
-        <Landing onLoadExam={loadExam} history={history} onResume={resume} onClearHistory={clearAllHistory} onReviewAttempt={reviewAttempt} />
+      <Routes>
+        <Route
+          path="/"
+          element={
+            <Landing
+              onLoadExam={loadExam}
+              history={history}
+              onResume={resume}
+              onClearHistory={clearAllHistory}
+              onReviewAttempt={reviewAttempt}
+            />
+          }
+        />
+        <Route
+          path="/exam/:slug/q:n"
+          element={
+            <ExamRoute
+              exam={exam}
+              examState={examState}
+              onActivate={activateExam}
+              setExamState={setExamStateStrict}
+              onSubmit={submit}
+              onExit={exit}
+            />
+          }
+        />
+        <Route
+          path="/results"
+          element={
+            exam && examState ? (
+              <Results
+                exam={exam}
+                state={examState}
+                onRestart={restart}
+                onExit={exit}
+                reviewOnly={false}
+              />
+            ) : (
+              <Navigate to="/" replace />
+            )
+          }
+        />
+        <Route
+          path="/review/:slug"
+          element={
+            exam && examState ? (
+              <Results
+                exam={exam}
+                state={examState}
+                onRestart={restart}
+                onExit={exit}
+                reviewOnly={true}
+              />
+            ) : (
+              <Navigate to="/" replace />
+            )
+          }
+        />
+        <Route
+          path="/admin"
+          element={
+            user?.role === "admin" ? (
+              <AdminDashboard onExit={exit} />
+            ) : (
+              <Navigate to="/" replace />
+            )
+          }
+        />
+        <Route path="*" element={<Navigate to="/" replace />} />
+      </Routes>
+
+      {tweaksOpen && (
+        <TweaksPanel
+          tweaks={tweaks}
+          update={updateTweak}
+          onClose={() => setTweaksOpen(false)}
+        />
       )}
-      {screen === 'admin' && user?.role === 'admin' && (
-        <AdminDashboard onExit={exit} />
-      )}
-      {screen === 'exam' && exam && examState && (
-        <ExamRunner exam={exam} state={examState} setState={setExamStateStrict} onSubmit={submit} onExit={exit} />
-      )}
-      {(screen === 'results' || screen === 'review') && exam && examState && (
-        <Results exam={exam} state={examState} onRestart={restart} onExit={exit} reviewOnly={screen === 'review'} />
-      )}
-      {tweaksOpen && <TweaksPanel tweaks={tweaks} update={updateTweak} onClose={() => setTweaksOpen(false)} />}
       {authModalOpen && (
         <AuthModal
           onClose={() => setAuthModalOpen(false)}
-          onForgotPassword={() => setScreen('reset-password')}
+          onForgotPassword={() => navigate("/reset-password")}
         />
       )}
     </div>
-  )
+  );
 }
 
 export default function App() {
@@ -315,5 +480,5 @@ export default function App() {
     <AuthProvider>
       <AppInner />
     </AuthProvider>
-  )
+  );
 }