Add admin leaderboard, LLM comparison, random puzzles, clearer rules

Frontend
- Random puzzle assignment by default on home page; manual picker hidden
behind ?dev=1 (sessionStorage-persisted)
- Per-family tutorial video links on home + play (puzzles.ts is single
source of truth, replaces local PUZZLE_OPTIONS / PUZZLE_HELP maps)
- Rewrote per-family rules (3-4 sentences each) matching the actual
editor cycle behavior; sidebar now shows a How to play box
- Removed duplicate reference PNG + ASCII preview from play sidebar
- Added a Use 'test' for practice hint under the player name input
- Wrong-submit feedback moved to a colored banner directly under the
editor; collapsed to a single 'Not solved yet' message regardless of
invalid vs valid-but-wrong (strict LLM parity)
- New done page: per-puzzle LLM comparison panel (solved/failed columns)
- Admin auth: sessionStorage-backed useAdmin hook, top-right unlock
button, AdminButton + Leaderboard components that auto-mount on play +
done pages when admin is unlocked

Backend
- POST /api/sessions now accepts puzzle_id=null and picks server-side,
excluding puzzles already solved by this player_name_norm (falls back
to full pool when exhausted)
- New submission_attempts table + per-attempt INSERT so every wrong
submission is logged with board content and timing (sessions row keeps
the rolled-up summary)
- New endpoints behind admin Bearer auth:
- GET /api/admin/check (token validator)
- GET /api/admin/leaderboard/{puzzle_id} (per-puzzle leaderboard,
test filter, sorted solved-by-time then unsolved-by-attempts)
- New GET /api/llm-results/{puzzle_id} reading from
space_app/llm_results.json (ASCII-variant verdicts for 9 models x 900
puzzles, sourced from multimodal_cot/evals)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

frontend/src/App.tsx

@@ -1,5 +1,6 @@
 import { BrowserRouter, Route, Routes } from "react-router-dom";
 
+import { AdminButton } from "./components/AdminButton";
 import { DonePage } from "./routes/DonePage";
 import { HomePage } from "./routes/HomePage";
 import { PlayPage } from "./routes/PlayPage";
@@ -7,6 +8,7 @@ import { PlayPage } from "./routes/PlayPage";
 export default function App() {
   return (
     <BrowserRouter>
+      <AdminButton />
       <Routes>
         <Route path="/" element={<HomePage />} />
         <Route path="/play/:sessionId" element={<PlayPage />} />

frontend/src/components/AdminButton.tsx

@@ -0,0 +1,91 @@
+import { useState } from "react";
+import type { FormEvent } from "react";
+
+import { lockAdmin, unlockAdmin, useAdmin } from "../lib/admin";
+
+export function AdminButton() {
+  const { enabled } = useAdmin();
+  const [open, setOpen] = useState(false);
+  const [token, setToken] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+
+  async function onSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setSubmitting(true);
+    setError(null);
+    try {
+      const ok = await unlockAdmin(token);
+      if (!ok) {
+        setError("Invalid token.");
+        return;
+      }
+      setToken("");
+      setOpen(false);
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  function onLogout() {
+    lockAdmin();
+    setOpen(false);
+  }
+
+  return (
+    <div className="admin-button-wrap">
+      <button
+        type="button"
+        className={`admin-button ${enabled ? "admin-button-on" : ""}`}
+        onClick={() => setOpen((value) => !value)}
+        aria-expanded={open}
+      >
+        {enabled ? "Admin ✓" : "Admin 🔒"}
+      </button>
+      {open ? (
+        <div className="admin-panel" role="dialog" aria-label="Admin token">
+          {enabled ? (
+            <>
+              <div className="admin-panel-text">
+                Admin features are unlocked for this browser tab.
+              </div>
+              <button type="button" className="ghost-button" onClick={onLogout}>
+                Log out
+              </button>
+            </>
+          ) : (
+            <form className="admin-form" onSubmit={onSubmit}>
+              <label htmlFor="adminToken">Admin token</label>
+              <input
+                id="adminToken"
+                type="password"
+                value={token}
+                onChange={(event) => setToken(event.target.value)}
+                placeholder="paste the admin token"
+                autoComplete="off"
+                autoFocus
+              />
+              {error ? <div className="admin-panel-error">{error}</div> : null}
+              <div className="button-row">
+                <button
+                  type="submit"
+                  className="primary-button"
+                  disabled={submitting || !token.trim()}
+                >
+                  {submitting ? "Checking..." : "Unlock"}
+                </button>
+                <button
+                  type="button"
+                  className="ghost-button"
+                  onClick={() => setOpen(false)}
+                >
+                  Cancel
+                </button>
+              </div>
+            </form>
+          )}
+        </div>
+      ) : null}
+    </div>
+  );
+}

frontend/src/components/Leaderboard.tsx

@@ -0,0 +1,130 @@
+import { useEffect, useState } from "react";
+
+import { useAdmin } from "../lib/admin";
+import { fetchLeaderboard, type Leaderboard as LeaderboardData } from "../lib/api";
+
+function formatElapsed(ms: number | null) {
+  if (ms === null) {
+    return "—";
+  }
+  const totalSeconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(totalSeconds / 60)
+    .toString()
+    .padStart(2, "0");
+  const seconds = (totalSeconds % 60).toString().padStart(2, "0");
+  const centiseconds = Math.floor((ms % 1000) / 10)
+    .toString()
+    .padStart(2, "0");
+  return `${minutes}:${seconds}.${centiseconds}`;
+}
+
+type Props = {
+  puzzleId: string;
+};
+
+export function Leaderboard({ puzzleId }: Props) {
+  const { enabled, token } = useAdmin();
+  const [data, setData] = useState<LeaderboardData | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [includeTest, setIncludeTest] = useState(false);
+
+  useEffect(() => {
+    if (!enabled || !puzzleId) {
+      setData(null);
+      return;
+    }
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    fetchLeaderboard(puzzleId, { includeTest })
+      .then((result) => {
+        if (!cancelled) {
+          setData(result);
+        }
+      })
+      .catch((caught) => {
+        if (!cancelled) {
+          setError(caught instanceof Error ? caught.message : "Could not load leaderboard.");
+        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [enabled, puzzleId, includeTest, token]);
+
+  if (!enabled) {
+    return null;
+  }
+
+  const entries = data?.entries ?? [];
+  const solvedCount = entries.filter((entry) => entry.solved).length;
+
+  return (
+    <section className="panel leaderboard-panel">
+      <div className="leaderboard-header">
+        <div>
+          <div className="eyebrow">Leaderboard · admin</div>
+          <div className="leaderboard-summary">
+            {loading
+              ? "Loading…"
+              : `${entries.length} session${entries.length === 1 ? "" : "s"} · ${solvedCount} solved`}
+          </div>
+        </div>
+        <label className="leaderboard-toggle">
+          <input
+            type="checkbox"
+            checked={includeTest}
+            onChange={(event) => setIncludeTest(event.target.checked)}
+          />
+          include <code>test</code>
+        </label>
+      </div>
+
+      {error ? <div className="status-box error">{error}</div> : null}
+
+      {!loading && entries.length === 0 ? (
+        <div className="leaderboard-empty">No sessions for this puzzle yet.</div>
+      ) : null}
+
+      {entries.length > 0 ? (
+        <div className="leaderboard-table-wrap">
+          <table className="leaderboard-table">
+            <thead>
+              <tr>
+                <th>#</th>
+                <th>Player</th>
+                <th>Time</th>
+                <th>Attempts</th>
+                <th>Status</th>
+              </tr>
+            </thead>
+            <tbody>
+              {entries.map((entry, index) => (
+                <tr
+                  key={`${entry.player_name}-${entry.started_at}-${index}`}
+                  className={entry.solved ? "row-solved" : "row-unsolved"}
+                >
+                  <td className="leaderboard-rank">{entry.solved ? index + 1 : "—"}</td>
+                  <td className="leaderboard-player">{entry.player_name}</td>
+                  <td className="leaderboard-time">
+                    {entry.solved ? formatElapsed(entry.elapsed_ms) : "—"}
+                  </td>
+                  <td className="leaderboard-attempts">{entry.submission_count}</td>
+                  <td className="leaderboard-status">
+                    {entry.solved ? "solved" : "attempted"}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      ) : null}
+    </section>
+  );
+}

frontend/src/index.css

@@ -243,6 +243,232 @@ a {
   margin-bottom: 6px;
 }
 
+.admin-button-wrap {
+  position: fixed;
+  top: 18px;
+  right: 18px;
+  z-index: 1000;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 8px;
+}
+
+.admin-button {
+  border: 1px solid rgba(18, 49, 41, 0.18);
+  background: rgba(255, 255, 255, 0.85);
+  color: #2a4a3d;
+  padding: 6px 12px;
+  border-radius: 999px;
+  font-size: 0.82rem;
+  font-weight: 500;
+  backdrop-filter: blur(10px);
+  cursor: pointer;
+}
+
+.admin-button:hover {
+  border-color: rgba(18, 49, 41, 0.4);
+}
+
+.admin-button-on {
+  background: rgba(34, 145, 92, 0.18);
+  border-color: rgba(34, 145, 92, 0.45);
+  color: #145a37;
+}
+
+.admin-panel {
+  background: rgba(255, 255, 255, 0.96);
+  border: 1px solid rgba(18, 49, 41, 0.18);
+  border-radius: 14px;
+  padding: 14px;
+  width: 280px;
+  box-shadow: 0 18px 40px rgba(31, 51, 42, 0.16);
+  display: grid;
+  gap: 10px;
+}
+
+.admin-form {
+  display: grid;
+  gap: 8px;
+}
+
+.admin-form label {
+  font-size: 0.78em;
+  color: #46695d;
+  font-weight: 500;
+}
+
+.admin-form input {
+  padding: 8px 10px;
+  border-radius: 8px;
+  border: 1px solid rgba(18, 49, 41, 0.18);
+  font-size: 0.9rem;
+}
+
+.admin-panel-text {
+  font-size: 0.88em;
+  color: #46695d;
+}
+
+.admin-panel-error {
+  font-size: 0.85em;
+  color: #7f1e1e;
+}
+
+.leaderboard-panel {
+  margin-top: 18px;
+  padding: 20px 24px;
+  display: grid;
+  gap: 14px;
+}
+
+.leaderboard-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-end;
+  gap: 12px;
+}
+
+.leaderboard-summary {
+  font-size: 0.92rem;
+  color: #46695d;
+  margin-top: 2px;
+}
+
+.leaderboard-toggle {
+  font-size: 0.82em;
+  color: #46695d;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.leaderboard-empty {
+  font-size: 0.92em;
+  color: #5a7568;
+  font-style: italic;
+}
+
+.leaderboard-table-wrap {
+  overflow-x: auto;
+}
+
+.leaderboard-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.92rem;
+}
+
+.leaderboard-table th,
+.leaderboard-table td {
+  text-align: left;
+  padding: 8px 10px;
+  border-bottom: 1px solid rgba(18, 49, 41, 0.08);
+}
+
+.leaderboard-table th {
+  font-size: 0.74em;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  font-weight: 600;
+  color: #46695d;
+}
+
+.leaderboard-table .row-solved td {
+  background: rgba(34, 145, 92, 0.05);
+}
+
+.leaderboard-table .row-unsolved td {
+  color: #6b7a73;
+}
+
+.leaderboard-rank {
+  width: 36px;
+  font-variant-numeric: tabular-nums;
+}
+
+.leaderboard-time {
+  font-variant-numeric: tabular-nums;
+}
+
+.leaderboard-status {
+  font-size: 0.82em;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: #46695d;
+}
+
+.submit-banner {
+  margin-top: 14px;
+  padding: 14px 18px;
+  border-radius: 14px;
+  font-weight: 500;
+  font-size: 1.02rem;
+  text-align: center;
+  border: 1px solid transparent;
+  animation: submit-banner-pop 220ms ease-out;
+}
+
+.submit-banner-wrong {
+  background: rgba(204, 142, 41, 0.12);
+  border-color: rgba(204, 142, 41, 0.32);
+  color: #8a5a14;
+}
+
+.submit-banner-error {
+  background: rgba(170, 44, 44, 0.1);
+  border-color: rgba(170, 44, 44, 0.32);
+  color: #7f1e1e;
+}
+
+@keyframes submit-banner-pop {
+  0% { transform: translateY(-6px); opacity: 0; }
+  100% { transform: translateY(0); opacity: 1; }
+}
+
+.field-hint {
+  display: block;
+  margin-top: 6px;
+  font-size: 0.82em;
+  color: #5a7568;
+  line-height: 1.4;
+}
+
+.field-hint code {
+  background: rgba(18, 54, 44, 0.08);
+  padding: 1px 6px;
+  border-radius: 6px;
+  font-size: 0.95em;
+}
+
+.rules-box strong {
+  display: block;
+  font-size: 0.78em;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: #46695d;
+  margin-bottom: 6px;
+}
+
+.rules-box p {
+  margin: 0;
+  line-height: 1.5;
+}
+
+.tutorial-link {
+  display: inline-block;
+  margin-top: 8px;
+  font-size: 0.85em;
+  color: #2a6151;
+  text-decoration: none;
+  border-bottom: 1px solid rgba(42, 97, 81, 0.3);
+}
+
+.tutorial-link:hover {
+  color: #18402f;
+  border-bottom-color: rgba(24, 64, 47, 0.65);
+}
+
 .play-layout {
   max-width: 1400px;
   margin: 0 auto;
@@ -690,6 +916,8 @@ a {
   max-width: 820px;
   margin: 0 auto;
   padding-top: 64px;
+  display: grid;
+  gap: 18px;
 }
 
 .done-card {
@@ -698,6 +926,99 @@ a {
   gap: 16px;
 }
 
+.comparison-card {
+  padding: 28px;
+  display: grid;
+  gap: 16px;
+}
+
+.comparison-headline {
+  margin: 0;
+  font-size: 1.15rem;
+  font-weight: 600;
+  line-height: 1.4;
+  color: #18402f;
+}
+
+.comparison-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 16px;
+}
+
+.comparison-column {
+  display: grid;
+  gap: 10px;
+}
+
+.comparison-column-title {
+  font-size: 0.78em;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  font-weight: 600;
+}
+
+.comparison-solved {
+  color: #1d6b46;
+}
+
+.comparison-failed {
+  color: #7a3a3a;
+}
+
+.comparison-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.comparison-pill {
+  display: inline-block;
+  padding: 4px 10px;
+  border-radius: 999px;
+  font-size: 0.88em;
+  border: 1px solid transparent;
+}
+
+.comparison-pill-solved {
+  background: rgba(34, 145, 92, 0.12);
+  border-color: rgba(34, 145, 92, 0.28);
+  color: #145a37;
+}
+
+.comparison-pill-failed {
+  background: rgba(170, 70, 70, 0.1);
+  border-color: rgba(170, 70, 70, 0.25);
+  color: #7a3030;
+}
+
+.comparison-empty {
+  font-size: 0.9em;
+  color: #5a7568;
+  font-style: italic;
+}
+
+.comparison-footnote {
+  margin: 0;
+  font-size: 0.82em;
+  color: #5a7568;
+}
+
+.comparison-footnote code {
+  background: rgba(18, 54, 44, 0.08);
+  padding: 1px 6px;
+  border-radius: 6px;
+}
+
+@media (max-width: 640px) {
+  .comparison-grid {
+    grid-template-columns: 1fr;
+  }
+}
+
 @media (max-width: 980px) {
   .play-grid {
     grid-template-columns: 1fr;

frontend/src/lib/admin.ts

@@ -0,0 +1,71 @@
+import { useEffect, useState } from "react";
+
+const ADMIN_TOKEN_KEY = "topobench:admin-token";
+const ADMIN_CHANGE_EVENT = "topobench:admin-change";
+
+export function getAdminToken(): string | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  return window.sessionStorage.getItem(ADMIN_TOKEN_KEY);
+}
+
+function emitChange(): void {
+  if (typeof window !== "undefined") {
+    window.dispatchEvent(new Event(ADMIN_CHANGE_EVENT));
+  }
+}
+
+export async function validateAdminToken(token: string): Promise<boolean> {
+  try {
+    const response = await fetch("/api/admin/check", {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function unlockAdmin(token: string): Promise<boolean> {
+  const trimmed = token.trim();
+  if (!trimmed) {
+    return false;
+  }
+  const ok = await validateAdminToken(trimmed);
+  if (!ok) {
+    return false;
+  }
+  window.sessionStorage.setItem(ADMIN_TOKEN_KEY, trimmed);
+  emitChange();
+  return true;
+}
+
+export function lockAdmin(): void {
+  if (typeof window !== "undefined") {
+    window.sessionStorage.removeItem(ADMIN_TOKEN_KEY);
+    emitChange();
+  }
+}
+
+export function useAdmin(): { enabled: boolean; token: string | null } {
+  const [token, setToken] = useState<string | null>(getAdminToken);
+  useEffect(() => {
+    const handler = () => setToken(getAdminToken());
+    window.addEventListener(ADMIN_CHANGE_EVENT, handler);
+    return () => window.removeEventListener(ADMIN_CHANGE_EVENT, handler);
+  }, []);
+  return { enabled: Boolean(token), token };
+}
+
+export async function adminFetch(
+  input: string,
+  init: RequestInit = {},
+): Promise<Response> {
+  const token = getAdminToken();
+  const headers = new Headers(init.headers);
+  if (token) {
+    headers.set("Authorization", `Bearer ${token}`);
+  }
+  return fetch(input, { ...init, headers });
+}

frontend/src/lib/api.ts

@@ -1,3 +1,5 @@
+import { adminFetch } from "./admin";
+
 export type Difficulty = "easy" | "medium" | "hard";
 export type PuzzleType =
   | "bridges"
@@ -39,6 +41,26 @@ export type SubmitResponse = {
   verification: Record<string, unknown>;
 };
 
+export type LLMResults = {
+  puzzle_id: string;
+  models_solved: string[];
+  models_failed: string[];
+};
+
+export type LeaderboardEntry = {
+  player_name: string;
+  elapsed_ms: number | null;
+  submission_count: number;
+  solved: boolean;
+  started_at: string | null;
+  submitted_at: string | null;
+};
+
+export type Leaderboard = {
+  puzzle_id: string;
+  entries: LeaderboardEntry[];
+};
+
 async function handle<T>(response: Response): Promise<T> {
   if (!response.ok) {
     let message = response.statusText;
@@ -57,7 +79,7 @@ export async function createSession(input: {
   player_name: string;
   puzzle_type: PuzzleType;
   difficulty: Difficulty;
-  puzzle_id: string;
+  puzzle_id?: string;
 }): Promise<SessionResponse> {
   return handle<SessionResponse>(
     await fetch("/api/sessions", {
@@ -91,6 +113,29 @@ export async function readySession(
   );
 }
 
+export async function fetchLeaderboard(
+  puzzleId: string,
+  options: { includeTest?: boolean } = {},
+): Promise<Leaderboard> {
+  const params = new URLSearchParams();
+  if (options.includeTest) {
+    params.set("include_test", "true");
+  }
+  const qs = params.toString() ? `?${params.toString()}` : "";
+  const response = await adminFetch(
+    `/api/admin/leaderboard/${encodeURIComponent(puzzleId)}${qs}`,
+  );
+  return handle<Leaderboard>(response);
+}
+
+export async function fetchLLMResults(puzzleId: string): Promise<LLMResults | null> {
+  const response = await fetch(`/api/llm-results/${encodeURIComponent(puzzleId)}`);
+  if (response.status === 404) {
+    return null;
+  }
+  return handle<LLMResults>(response);
+}
+
 export async function submitSession(
   sessionId: string,
   boardAscii: string,

frontend/src/lib/puzzles.ts

@@ -0,0 +1,66 @@
+import type { PuzzleType } from "./api";
+
+export type PuzzleFamily = {
+  value: PuzzleType;
+  label: string;
+  blurb: string;
+  helpText: string;
+  tutorialUrl: string;
+};
+
+// To add a tutorial: paste a URL into the matching `tutorialUrl`.
+// Empty string -> the "Watch tutorial" link is hidden.
+export const PUZZLE_FAMILIES: PuzzleFamily[] = [
+  {
+    value: "bridges",
+    label: "Bridges",
+    blurb: "Connect islands with single or double links.",
+    helpText:
+      "Connect every numbered island into one network of bridges. The number on each island is exactly how many bridge-ends must touch it. Bridges run horizontally or vertically, never cross, and you may use at most two between any pair of islands. Click between two islands to cycle no bridge → single → double.",
+    tutorialUrl: "https://www.youtube.com/watch?v=i9RL_3cn4mo",
+  },
+  {
+    value: "flow_free",
+    label: "Flow Free",
+    blurb: "Fill the board with non-crossing color paths.",
+    helpText:
+      "Connect each pair of matching colored endpoints with a continuous path, leaving no empty cell. Paths cannot cross or share a cell. Click an endpoint to pick its color, then click adjacent empty cells to extend the path; clicking a filled cell with that same color erases it. The board is solved when every color is paired and every cell is covered.",
+    tutorialUrl: "https://www.youtube.com/shorts/mli8IdECi-g",
+  },
+  {
+    value: "galaxies",
+    label: "Galaxies",
+    blurb: "Draw region boundaries around rotationally symmetric clusters.",
+    helpText:
+      "Partition the board with interior walls so each region contains exactly one dot and is 180°-rotationally symmetric around that dot. For every cell in a galaxy, the cell on the opposite side of the dot must also belong to it. Click an interior segment to add or remove a wall. Submit when every cell is assigned to exactly one valid galaxy.",
+    tutorialUrl: "https://www.youtube.com/watch?v=legK2UDyHlg",
+  },
+  {
+    value: "loopy",
+    label: "Loopy",
+    blurb: "Toggle loop edges around numeric clues.",
+    helpText:
+      "Draw exactly one closed loop along the grid edges. The loop cannot branch or cross itself, and the number in each cell counts how many of its four sides are part of the loop. Click any segment (including the outer border) to toggle it between part of the loop and not part of it. The board is solved when every numeric clue is satisfied by a single continuous loop.",
+    tutorialUrl: "https://www.youtube.com/watch?v=nSLdxmHefts&t=22s",
+  },
+  {
+    value: "pattern",
+    label: "Pattern",
+    blurb: "Fill cells to satisfy run clues for every row and column.",
+    helpText:
+      "Each row and column clue lists the lengths of consecutive black runs, in order, separated by at least one white cell. Click a cell to toggle it between white and filled black. Solve by filling cells so every row and column simultaneously matches its clues — only the run lengths matter, no other connectivity rule applies.",
+    tutorialUrl: "https://www.youtube.com/watch?v=CRVEAxP-UUk",
+  },
+  {
+    value: "undead",
+    label: "Undead",
+    blurb: "Place monsters around mirrors and sightline clues.",
+    helpText:
+      "Place ghosts (G), vampires (V), and zombies (Z) so each edge clue equals the number of monsters seen looking down that row or column from that side. Vampires are visible only along direct line of sight; ghosts are visible only when at least one mirror redirects the sight; zombies are visible either way. The / and \\ symbols are fixed mirrors that bend the sightline by 90°. Click any empty cell to cycle blank → G → V → Z.",
+    tutorialUrl: "https://www.youtube.com/watch?v=L72V9O_anbg&t=187s",
+  },
+];
+
+export const PUZZLE_FAMILY_BY_TYPE: Record<PuzzleType, PuzzleFamily> = Object.fromEntries(
+  PUZZLE_FAMILIES.map((family) => [family.value, family]),
+) as Record<PuzzleType, PuzzleFamily>;

frontend/src/routes/DonePage.tsx

@@ -1,6 +1,9 @@
-import { useNavigate, useParams, useLocation } from "react-router-dom";
+import { useEffect, useState } from "react";
+import { useNavigate, useLocation } from "react-router-dom";
 
-import type { SessionResponse, SubmitResponse } from "../lib/api";
+import { Leaderboard } from "../components/Leaderboard";
+import { fetchLLMResults, type LLMResults, type SessionResponse, type SubmitResponse } from "../lib/api";
+import { PUZZLE_FAMILY_BY_TYPE } from "../lib/puzzles";
 
 type DoneState = {
   result?: SubmitResponse;
@@ -24,11 +27,48 @@ function formatElapsed(ms: number | null) {
 }
 
 export function DonePage() {
-  const { sessionId = "" } = useParams();
   const location = useLocation();
   const navigate = useNavigate();
   const state = (location.state as DoneState | null) ?? null;
 
+  const puzzleId = state?.session?.puzzle_id ?? "";
+  const puzzleType = state?.session?.puzzle_type ?? "";
+  const family = puzzleType ? PUZZLE_FAMILY_BY_TYPE[puzzleType as keyof typeof PUZZLE_FAMILY_BY_TYPE] : undefined;
+
+  const [llmResults, setLlmResults] = useState<LLMResults | null>(null);
+  const [llmLoading, setLlmLoading] = useState<boolean>(Boolean(puzzleId));
+  const [llmError, setLlmError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!puzzleId) {
+      setLlmLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setLlmLoading(true);
+    setLlmError(null);
+    fetchLLMResults(puzzleId)
+      .then((data) => {
+        if (cancelled) {
+          return;
+        }
+        setLlmResults(data);
+      })
+      .catch((caught) => {
+        if (!cancelled) {
+          setLlmError(caught instanceof Error ? caught.message : "Could not load LLM comparison.");
+        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setLlmLoading(false);
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [puzzleId]);
+
   function playAgain() {
     navigate("/", {
       state: {
@@ -40,6 +80,12 @@ export function DonePage() {
     });
   }
 
+  const totalModels = llmResults
+    ? llmResults.models_solved.length + llmResults.models_failed.length
+    : 0;
+  const solvedCount = llmResults?.models_solved.length ?? 0;
+  const familyLabel = family?.label ?? puzzleType;
+
   return (
     <div className="shell">
       <div className="done-layout">
@@ -47,8 +93,8 @@ export function DonePage() {
           <div className="eyebrow">Solved</div>
           <h1 style={{ margin: 0 }}>Puzzle complete.</h1>
           <p style={{ margin: 0, color: "#46695d" }}>
-            Session <code>{sessionId}</code> finished in{" "}
-            <strong>{formatElapsed(state?.result?.elapsed_ms ?? null)}</strong>.
+            {familyLabel ? <><strong>{familyLabel}</strong> · </> : null}
+            finished in <strong>{formatElapsed(state?.result?.elapsed_ms ?? null)}</strong>.
           </p>
           <div className="button-row">
             <button className="primary-button" type="button" onClick={playAgain}>
@@ -59,6 +105,62 @@ export function DonePage() {
             </button>
           </div>
         </section>
+
+        <section className="panel comparison-card">
+          <div className="eyebrow">LLM comparison · this exact puzzle</div>
+          {llmLoading ? (
+            <div className="status-box">Loading LLM comparison…</div>
+          ) : llmError ? (
+            <div className="status-box error">{llmError}</div>
+          ) : !llmResults ? (
+            <div className="status-box">
+              No LLM benchmark data recorded for this puzzle yet. Comparisons will appear once results are added.
+            </div>
+          ) : totalModels === 0 ? (
+            <div className="status-box">No models have been benchmarked on this puzzle.</div>
+          ) : (
+            <>
+              <h2 className="comparison-headline">
+                You solved it. {solvedCount} of {totalModels} benchmarked LLMs also solved this exact puzzle.
+              </h2>
+              <div className="comparison-grid">
+                <div className="comparison-column">
+                  <div className="comparison-column-title comparison-solved">
+                    Solved ({llmResults.models_solved.length})
+                  </div>
+                  {llmResults.models_solved.length === 0 ? (
+                    <div className="comparison-empty">No LLM solved this — you got something none of them could.</div>
+                  ) : (
+                    <ul className="comparison-list">
+                      {llmResults.models_solved.map((model) => (
+                        <li key={model} className="comparison-pill comparison-pill-solved">{model}</li>
+                      ))}
+                    </ul>
+                  )}
+                </div>
+                <div className="comparison-column">
+                  <div className="comparison-column-title comparison-failed">
+                    Failed ({llmResults.models_failed.length})
+                  </div>
+                  {llmResults.models_failed.length === 0 ? (
+                    <div className="comparison-empty">Every benchmarked LLM solved this one too.</div>
+                  ) : (
+                    <ul className="comparison-list">
+                      {llmResults.models_failed.map((model) => (
+                        <li key={model} className="comparison-pill comparison-pill-failed">{model}</li>
+                      ))}
+                    </ul>
+                  )}
+                </div>
+              </div>
+              <p className="comparison-footnote">
+                Puzzle id <code>{puzzleId}</code>. LLM verdicts come from the TopoBench paper's eval on this same board — not a probabilistic comparison.
+              </p>
+            </>
+          )}
+        </section>
+
+        <Leaderboard puzzleId={puzzleId} />
       </div>
     </div>
   );

frontend/src/routes/HomePage.tsx

@@ -9,17 +9,29 @@ import {
   type PuzzleOption,
   type PuzzleType,
 } from "../lib/api";
+import { PUZZLE_FAMILIES } from "../lib/puzzles";
 
-const PUZZLE_OPTIONS: Array<{ value: PuzzleType; label: string; blurb: string }> = [
-  { value: "bridges", label: "Bridges", blurb: "Connect islands with single or double links." },
-  { value: "flow_free", label: "Flow Free", blurb: "Fill the board with non-crossing color paths." },
-  { value: "galaxies", label: "Galaxies", blurb: "Draw region boundaries around rotationally symmetric clusters." },
-  { value: "loopy", label: "Loopy", blurb: "Toggle loop edges around numeric clues." },
-  { value: "pattern", label: "Pattern", blurb: "Fill cells to satisfy run clues while keeping one connected shape." },
-  { value: "undead", label: "Undead", blurb: "Place monsters around mirrors and sightline clues." },
-];
+const DEV_FLAG_KEY = "topobench:dev";
+
+function readDevMode(): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+  const params = new URLSearchParams(window.location.search);
+  const urlValue = params.get("dev");
+  if (urlValue === "1") {
+    window.sessionStorage.setItem(DEV_FLAG_KEY, "1");
+    return true;
+  }
+  if (urlValue === "0") {
+    window.sessionStorage.removeItem(DEV_FLAG_KEY);
+    return false;
+  }
+  return window.sessionStorage.getItem(DEV_FLAG_KEY) === "1";
+}
 
 export function HomePage() {
+  const [devMode] = useState(readDevMode);
   const navigate = useNavigate();
   const location = useLocation();
   const defaults = (location.state as
@@ -30,11 +42,14 @@ export function HomePage() {
   const [difficulty, setDifficulty] = useState(defaults.difficulty ?? "easy");
   const [puzzleOptions, setPuzzleOptions] = useState<PuzzleOption[]>([]);
   const [selectedPuzzleId, setSelectedPuzzleId] = useState(defaults.puzzleId ?? "");
-  const [loadingPuzzles, setLoadingPuzzles] = useState(true);
+  const [loadingPuzzles, setLoadingPuzzles] = useState(devMode);
   const [error, setError] = useState<string | null>(null);
   const [submitting, setSubmitting] = useState(false);
 
   useEffect(() => {
+    if (!devMode) {
+      return;
+    }
     let cancelled = false;
     async function loadPuzzles() {
       setLoadingPuzzles(true);
@@ -71,7 +86,7 @@ export function HomePage() {
     return () => {
       cancelled = true;
     };
-  }, [puzzleType, difficulty, defaults.puzzleId]);
+  }, [devMode, puzzleType, difficulty, defaults.puzzleId]);
 
   async function onSubmit(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
@@ -82,10 +97,14 @@ export function HomePage() {
         player_name: playerName,
         puzzle_type: puzzleType,
         difficulty,
-        puzzle_id: selectedPuzzleId,
+        ...(devMode && selectedPuzzleId ? { puzzle_id: selectedPuzzleId } : {}),
       });
       navigate(`/play/${session.session_id}`, {
-        state: { session, playerName, puzzleId: selectedPuzzleId },
+        state: {
+          session,
+          playerName,
+          puzzleId: session.puzzle_id,
+        },
       });
     } catch (caught) {
       setError(caught instanceof Error ? caught.message : "Could not create a session.");
@@ -98,13 +117,15 @@ export function HomePage() {
     <div className="shell">
       <div className="home-layout">
         <section className="panel hero">
-          <div className="eyebrow">TopoBench Space</div>
+          <div className="eyebrow">TopoBench Space{devMode ? " · dev mode" : ""}</div>
           <h1>Play the benchmark, not just the report.</h1>
           <p>
-            This Space pulls real TopoBench puzzles from Hugging Face, lets you choose
-            intentionally from the first 50 boards in each set, times each solve on the
-            server, and verifies your submission against the same native logic used by
-            the benchmark repo.
+            This Space pulls real TopoBench puzzles from Hugging Face,{" "}
+            {devMode
+              ? "lets you choose intentionally from the first 50 boards in each set, "
+              : "assigns you a random board from each set, "}
+            times each solve on the server, and verifies your submission against the same
+            native logic used by the benchmark repo.
           </p>
         </section>
 
@@ -121,6 +142,9 @@ export function HomePage() {
                   maxLength={80}
                   required
                 />
+                <small className="field-hint">
+                  Use <code>test</code> as your name to practice. Any other name (your real name or a handle) counts toward the study.
+                </small>
               </div>
 
               <div className="field">
@@ -130,7 +154,7 @@ export function HomePage() {
                   value={puzzleType}
                   onChange={(event) => setPuzzleType(event.target.value as PuzzleType)}
                 >
-                  {PUZZLE_OPTIONS.map((option) => (
+                  {PUZZLE_FAMILIES.map((option) => (
                     <option key={option.value} value={option.value}>
                       {option.label}
                     </option>
@@ -151,34 +175,36 @@ export function HomePage() {
                 </select>
               </div>
 
-              <div className="field">
-                <label>Pick one of the first 50 puzzles</label>
-                <div className="puzzle-picker">
-                  {loadingPuzzles ? (
-                    <div className="status-box">Loading puzzle choices...</div>
-                  ) : (
-                    puzzleOptions.map((option) => (
-                      <label
-                        key={option.puzzle_id}
-                        className={`puzzle-option ${selectedPuzzleId === option.puzzle_id ? "selected" : ""}`}
-                      >
-                        <input
-                          type="radio"
-                          name="puzzleId"
-                          value={option.puzzle_id}
-                          checked={selectedPuzzleId === option.puzzle_id}
-                          onChange={() => setSelectedPuzzleId(option.puzzle_id)}
-                        />
-                        <span className="puzzle-option-seq">{option.sequence.toString().padStart(2, "0")}</span>
-                        <span className="puzzle-option-text">
-                          <strong>{option.title}</strong>
-                          <span>{option.args}</span>
-                        </span>
-                      </label>
-                    ))
-                  )}
+              {devMode ? (
+                <div className="field">
+                  <label>Pick one of the first 50 puzzles</label>
+                  <div className="puzzle-picker">
+                    {loadingPuzzles ? (
+                      <div className="status-box">Loading puzzle choices...</div>
+                    ) : (
+                      puzzleOptions.map((option) => (
+                        <label
+                          key={option.puzzle_id}
+                          className={`puzzle-option ${selectedPuzzleId === option.puzzle_id ? "selected" : ""}`}
+                        >
+                          <input
+                            type="radio"
+                            name="puzzleId"
+                            value={option.puzzle_id}
+                            checked={selectedPuzzleId === option.puzzle_id}
+                            onChange={() => setSelectedPuzzleId(option.puzzle_id)}
+                          />
+                          <span className="puzzle-option-seq">{option.sequence.toString().padStart(2, "0")}</span>
+                          <span className="puzzle-option-text">
+                            <strong>{option.title}</strong>
+                            <span>{option.args}</span>
+                          </span>
+                        </label>
+                      ))
+                    )}
+                  </div>
                 </div>
-              </div>
+              ) : null}
 
               {error ? <div className="status-box error">{error}</div> : null}
 
@@ -186,19 +212,33 @@ export function HomePage() {
                 <button
                   className="primary-button"
                   type="submit"
-                  disabled={submitting || loadingPuzzles || !selectedPuzzleId}
+                  disabled={submitting || (devMode && (loadingPuzzles || !selectedPuzzleId))}
                 >
-                  {submitting ? "Starting..." : "Start Chosen Puzzle"}
+                  {submitting
+                    ? "Starting..."
+                    : devMode
+                      ? "Start Chosen Puzzle"
+                      : "Start Random Puzzle"}
                 </button>
               </div>
             </form>
           </section>
 
           <section className="panel card hint-grid">
-            {PUZZLE_OPTIONS.map((option) => (
+            {PUZZLE_FAMILIES.map((option) => (
               <div key={option.value} className="hint-box">
                 <strong>{option.label}</strong>
                 <div>{option.blurb}</div>
+                {option.tutorialUrl ? (
+                  <a
+                    className="tutorial-link"
+                    href={option.tutorialUrl}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                  >
+                    Watch tutorial →
+                  </a>
+                ) : null}
               </div>
             ))}
           </section>

frontend/src/routes/PlayPage.tsx

@@ -1,17 +1,10 @@
 import { useEffect, useState } from "react";
 import { useLocation, useNavigate, useParams } from "react-router-dom";
 
+import { Leaderboard } from "../components/Leaderboard";
 import { PuzzleEditor } from "../components/PuzzleEditor";
-import { fetchSession, readySession, submitSession, type SessionResponse } from "../lib/api";
-
-const PUZZLE_HELP: Record<string, string> = {
-  bridges: "Connect every numbered island into a single network. Each route cycles empty, single bridge, then double bridge.",
-  flow_free: "Choose a color from the palette, then paint a continuous path between matching endpoints without changing the endpoints themselves.",
-  galaxies: "Partition the board with interior walls so each region has exactly one dot-symmetry center.",
-  loopy: "Build one single loop. Every segment toggles between part of the loop and definitely not part of it, including the outer perimeter.",
-  pattern: "Every square starts white. Click a square to toggle it between white and filled black so the row and column clues match.",
-  undead: "Place ghosts, vampires, and zombies so the side clues and the global monster counts all line up.",
-};
+import { fetchSession, readySession, submitSession, type PuzzleType, type SessionResponse } from "../lib/api";
+import { PUZZLE_FAMILY_BY_TYPE } from "../lib/puzzles";
 
 function formatElapsed(ms: number) {
   const totalSeconds = Math.floor(ms / 1000);
@@ -41,7 +34,7 @@ export function PlayPage() {
   const [startedAt, setStartedAt] = useState<string | null>(state?.session?.started_at ?? null);
   const [elapsedMs, setElapsedMs] = useState(0);
   const [error, setError] = useState<string | null>(null);
-  const [statusMessage, setStatusMessage] = useState<string | null>(null);
+  const [feedback, setFeedback] = useState<{ kind: "wrong" | "error"; message: string } | null>(null);
   const [submitting, setSubmitting] = useState(false);
 
   useEffect(() => {
@@ -54,7 +47,6 @@ export function PlayPage() {
         }
         setSession(payload);
         setBoardAscii(payload.payload.current_board_ascii);
-        setStatusMessage(null);
         if (!payload.started_at) {
           const ready = await readySession(sessionId);
           if (!cancelled) {
@@ -91,8 +83,7 @@ export function PlayPage() {
       return;
     }
     setSubmitting(true);
-    setError(null);
-    setStatusMessage(null);
+    setFeedback(null);
     try {
       const result = await submitSession(session.session_id, boardAscii);
       if (result.solved) {
@@ -105,14 +96,13 @@ export function PlayPage() {
           },
         });
       } else {
-        if (!result.verification.board_valid) {
-          setError("That board is not structurally valid yet. Double-check fixed clues, endpoints, and wall or bridge placement.");
-        } else {
-          setStatusMessage("Close, but not solved yet. Keep going and submit again when you are ready.");
-        }
+        setFeedback({ kind: "wrong", message: "Not solved yet — keep trying." });
       }
     } catch (caught) {
-      setError(caught instanceof Error ? caught.message : "Could not submit the puzzle.");
+      setFeedback({
+        kind: "error",
+        message: caught instanceof Error ? caught.message : "Could not submit the puzzle.",
+      });
     } finally {
       setSubmitting(false);
     }
@@ -134,8 +124,7 @@ export function PlayPage() {
       return;
     }
     setBoardAscii(session.payload.current_board_ascii);
-    setError(null);
-    setStatusMessage("Board reset to the original puzzle.");
+    setFeedback(null);
   }
 
   if (!session) {
@@ -168,6 +157,15 @@ export function PlayPage() {
               boardAscii={boardAscii}
               onChange={setBoardAscii}
             />
+            {feedback ? (
+              <div
+                className={`submit-banner submit-banner-${feedback.kind}`}
+                role="status"
+                aria-live="polite"
+              >
+                {feedback.message}
+              </div>
+            ) : null}
           </section>
 
           <aside className="panel sidebar">
@@ -175,9 +173,25 @@ export function PlayPage() {
               Timer starts once the puzzle appears. The server keeps the official solve time.
             </div>
 
-            {error ? <div className="status-box error">{error}</div> : null}
-            {statusMessage ? <div className="status-box">{statusMessage}</div> : null}
-            <div className="status-box">{PUZZLE_HELP[session.puzzle_type] ?? "Solve the puzzle, then submit to verify it."}</div>
+            {(() => {
+              const family = PUZZLE_FAMILY_BY_TYPE[session.puzzle_type as PuzzleType];
+              return (
+                <div className="status-box rules-box">
+                  <strong>How to play</strong>
+                  <p>{family?.helpText ?? "Solve the puzzle, then submit to verify it."}</p>
+                  {family?.tutorialUrl ? (
+                    <a
+                      className="tutorial-link"
+                      href={family.tutorialUrl}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                    >
+                      Watch tutorial →
+                    </a>
+                  ) : null}
+                </div>
+              );
+            })()}
 
             <div className="button-row">
               <button className="primary-button" type="button" onClick={onSubmit} disabled={submitting}>
@@ -190,22 +204,10 @@ export function PlayPage() {
                 Choose Another Puzzle
               </button>
             </div>
-
-            {session.payload.image_base64 ? (
-              <div className="image-frame">
-                <img
-                  src={`data:image/png;base64,${session.payload.image_base64}`}
-                  alt="Reference rendering of the puzzle"
-                />
-              </div>
-            ) : null}
-
-            <div>
-              <strong>ASCII board</strong>
-              <pre className="ascii-preview">{boardAscii}</pre>
-            </div>
           </aside>
         </div>
+
+        <Leaderboard puzzleId={session.puzzle_id} />
       </div>
     </div>
   );

space_app/db.py

@@ -64,6 +64,28 @@ class SessionStore:
                 ON sessions (player_name_norm, puzzle_type, difficulty, solved)
                 """
             )
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS submission_attempts (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    session_id TEXT NOT NULL,
+                    attempt_n INTEGER NOT NULL,
+                    submitted_at TEXT NOT NULL,
+                    elapsed_ms INTEGER NOT NULL,
+                    board_ascii TEXT NOT NULL,
+                    solved INTEGER NOT NULL,
+                    board_valid INTEGER NOT NULL,
+                    verification_payload TEXT NOT NULL,
+                    FOREIGN KEY (session_id) REFERENCES sessions (id)
+                )
+                """
+            )
+            conn.execute(
+                """
+                CREATE INDEX IF NOT EXISTS idx_attempts_session
+                ON submission_attempts (session_id, attempt_n)
+                """
+            )
 
     def create_session(
         self,
@@ -176,7 +198,28 @@ class SessionStore:
         elapsed_ms = max(0, int((submitted_at - started_at).total_seconds() * 1000))
         submission_count = int(session["submission_count"]) + 1
         status = "solved" if solved else "attempted"
+        board_valid = bool(verification_payload.get("board_valid", False))
+        verification_json = json.dumps(verification_payload)
+        submitted_at_iso = to_iso(submitted_at)
         with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO submission_attempts (
+                    session_id, attempt_n, submitted_at, elapsed_ms,
+                    board_ascii, solved, board_valid, verification_payload
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    session_id,
+                    submission_count,
+                    submitted_at_iso,
+                    elapsed_ms,
+                    submitted_artifact,
+                    int(solved),
+                    int(board_valid),
+                    verification_json,
+                ),
+            )
             conn.execute(
                 """
                 UPDATE sessions
@@ -185,13 +228,13 @@ class SessionStore:
                 WHERE id = ?
                 """,
                 (
-                    to_iso(submitted_at),
+                    submitted_at_iso,
                     elapsed_ms,
                     submission_count,
                     int(solved),
                     status,
                     submitted_artifact,
-                    json.dumps(verification_payload),
+                    verification_json,
                     session_id,
                 ),
             )
@@ -199,6 +242,29 @@ class SessionStore:
         assert updated is not None
         return updated
 
+    def list_leaderboard(
+        self,
+        *,
+        puzzle_id: str,
+        include_test: bool = False,
+    ) -> list[dict[str, Any]]:
+        params: list[Any] = [puzzle_id]
+        where = ["puzzle_filename = ?", "started_at IS NOT NULL"]
+        if not include_test:
+            where.append("LOWER(player_name_norm) != 'test'")
+        query = f"""
+            SELECT player_name_raw, elapsed_ms, submission_count, solved, started_at, submitted_at
+            FROM sessions
+            WHERE {' AND '.join(where)}
+            ORDER BY solved DESC,
+                     CASE WHEN solved = 1 THEN elapsed_ms END ASC,
+                     submission_count DESC,
+                     started_at DESC
+        """
+        with self._connect() as conn:
+            rows = conn.execute(query, params).fetchall()
+        return [dict(row) for row in rows]
+
     def list_solves(self, filters: dict[str, str | None]) -> list[dict[str, Any]]:
         clauses = ["submitted_at IS NOT NULL"]
         params: list[str] = []

space_app/llm_results.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+class LLMResultsStore:
+    def __init__(self, results: dict[str, dict[str, list[str]]]) -> None:
+        self._results = results
+
+    @classmethod
+    def from_file(cls, path: Path) -> "LLMResultsStore":
+        if not path.exists():
+            return cls({})
+        with path.open("r", encoding="utf-8") as f:
+            payload: dict[str, Any] = json.load(f)
+        results = payload.get("results", {}) if isinstance(payload, dict) else {}
+        clean: dict[str, dict[str, list[str]]] = {}
+        for puzzle_id, verdicts in results.items():
+            if not isinstance(verdicts, dict):
+                continue
+            solved = [str(m) for m in verdicts.get("models_solved", []) if isinstance(m, str)]
+            failed = [str(m) for m in verdicts.get("models_failed", []) if isinstance(m, str)]
+            clean[str(puzzle_id)] = {"models_solved": solved, "models_failed": failed}
+        return cls(clean)
+
+    def get_for_puzzle(self, puzzle_id: str) -> dict[str, list[str]] | None:
+        return self._results.get(puzzle_id)

space_app/main.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import random
 from pathlib import Path
 from typing import Any
 
@@ -12,9 +13,13 @@ from .board_utils import normalize_board_for_display, normalize_board_for_submis
 from .config import Settings
 from .dataset import DatasetStore
 from .db import SessionStore
+from .llm_results import LLMResultsStore
 from .models import engine_for_puzzle, normalize_player_name
 from .schemas import (
     CreateSessionRequest,
+    LeaderboardEntry,
+    LeaderboardResponse,
+    LLMResultsResponse,
     PuzzleOptionResponse,
     SessionPayload,
     SessionResponse,
@@ -58,6 +63,7 @@ def create_app(
     dataset_store: DatasetStore | None = None,
     session_store: SessionStore | None = None,
     verifier: VerificationService | None = None,
+    llm_results_store: LLMResultsStore | None = None,
 ) -> FastAPI:
     resolved_settings = settings or Settings.from_env()
     resolved_settings.prepare()
@@ -66,6 +72,9 @@ def create_app(
     app.state.dataset_store = dataset_store or DatasetStore.load_huggingface()
     app.state.session_store = session_store or SessionStore(resolved_settings.database_path)
     app.state.verifier = verifier or VerificationService()
+    app.state.llm_results_store = llm_results_store or LLMResultsStore.from_file(
+        Path(__file__).parent / "llm_results.json"
+    )
 
     def get_settings() -> Settings:
         return app.state.settings
@@ -79,6 +88,9 @@ def create_app(
     def get_verifier() -> VerificationService:
         return app.state.verifier
 
+    def get_llm_results_store() -> LLMResultsStore:
+        return app.state.llm_results_store
+
     def require_admin(
         authorization: str | None = Header(default=None),
         current_settings: Settings = Depends(get_settings),
@@ -127,15 +139,32 @@ def create_app(
         player_name_norm = normalize_player_name(player_name_raw)
         if not player_name_norm:
             raise HTTPException(status_code=400, detail="Player name is required.")
-        try:
-            row = current_dataset_store.get_row(request.puzzle_id)
-        except KeyError:
-            raise HTTPException(status_code=404, detail="Puzzle not found.") from None
-        if row.puzzlename != request.puzzle_type or row.difficulty != request.difficulty:
-            raise HTTPException(
-                status_code=400,
-                detail="Selected puzzle does not match the chosen family and difficulty.",
+        if request.puzzle_id is None:
+            try:
+                pool = current_dataset_store.list_rows(
+                    puzzle_type=request.puzzle_type,
+                    difficulty=request.difficulty,
+                    limit=50,
+                )
+            except ValueError as exc:
+                raise HTTPException(status_code=404, detail=str(exc)) from exc
+            already_solved = current_session_store.get_solved_filenames(
+                player_name_norm=player_name_norm,
+                puzzle_type=request.puzzle_type,
+                difficulty=request.difficulty,
             )
+            unseen = [item for item in pool if item.filename not in already_solved]
+            row = random.choice(unseen) if unseen else random.choice(pool)
+        else:
+            try:
+                row = current_dataset_store.get_row(request.puzzle_id)
+            except KeyError:
+                raise HTTPException(status_code=404, detail="Puzzle not found.") from None
+            if row.puzzlename != request.puzzle_type or row.difficulty != request.difficulty:
+                raise HTTPException(
+                    status_code=400,
+                    detail="Selected puzzle does not match the chosen family and difficulty.",
+                )
         session = current_session_store.create_session(
             player_name_raw=player_name_raw,
             player_name_norm=player_name_norm,
@@ -217,6 +246,50 @@ def create_app(
             verification=verification,
         )
 
+    @app.get("/api/llm-results/{puzzle_id}", response_model=LLMResultsResponse)
+    def llm_results(
+        puzzle_id: str,
+        current_llm_results_store: LLMResultsStore = Depends(get_llm_results_store),
+    ) -> LLMResultsResponse:
+        verdicts = current_llm_results_store.get_for_puzzle(puzzle_id)
+        if verdicts is None:
+            raise HTTPException(
+                status_code=404,
+                detail="No LLM results recorded for this puzzle.",
+            )
+        return LLMResultsResponse(
+            puzzle_id=puzzle_id,
+            models_solved=verdicts["models_solved"],
+            models_failed=verdicts["models_failed"],
+        )
+
+    @app.get("/api/admin/check", dependencies=[Depends(require_admin)])
+    def admin_check() -> dict[str, bool]:
+        return {"ok": True}
+
+    @app.get("/api/admin/leaderboard/{puzzle_id}", response_model=LeaderboardResponse, dependencies=[Depends(require_admin)])
+    def admin_leaderboard(
+        puzzle_id: str,
+        include_test: bool = Query(default=False),
+        current_session_store: SessionStore = Depends(get_session_store),
+    ) -> LeaderboardResponse:
+        rows = current_session_store.list_leaderboard(
+            puzzle_id=puzzle_id,
+            include_test=include_test,
+        )
+        entries = [
+            LeaderboardEntry(
+                player_name=str(row["player_name_raw"]),
+                elapsed_ms=row["elapsed_ms"],
+                submission_count=int(row["submission_count"]),
+                solved=bool(row["solved"]),
+                started_at=row["started_at"],
+                submitted_at=row["submitted_at"],
+            )
+            for row in rows
+        ]
+        return LeaderboardResponse(puzzle_id=puzzle_id, entries=entries)
+
     @app.get("/api/admin/solves", dependencies=[Depends(require_admin)])
     def admin_solves(
         player_name_norm: str | None = Query(default=None),

space_app/schemas.py

@@ -11,7 +11,7 @@ class CreateSessionRequest(BaseModel):
     player_name: str = Field(min_length=1, max_length=80)
     puzzle_type: str
     difficulty: str
-    puzzle_id: str = Field(min_length=1)
+    puzzle_id: str | None = Field(default=None, min_length=1)
 
     @field_validator("puzzle_type")
     @classmethod
@@ -64,3 +64,23 @@ class SubmitResponse(BaseModel):
     elapsed_ms: int | None
     status: str
     verification: dict[str, Any]
+
+
+class LLMResultsResponse(BaseModel):
+    puzzle_id: str
+    models_solved: list[str]
+    models_failed: list[str]
+
+
+class LeaderboardEntry(BaseModel):
+    player_name: str
+    elapsed_ms: int | None
+    submission_count: int
+    solved: bool
+    started_at: str | None
+    submitted_at: str | None
+
+
+class LeaderboardResponse(BaseModel):
+    puzzle_id: str
+    entries: list[LeaderboardEntry]