Add explicit first-50 puzzle chooser

frontend/src/index.css

@@ -131,6 +131,59 @@ a {
   color: #13231d;
 }
 
+.puzzle-picker {
+  display: grid;
+  gap: 10px;
+  max-height: 360px;
+  overflow: auto;
+  padding-right: 4px;
+}
+
+.puzzle-option {
+  display: grid;
+  grid-template-columns: auto 44px minmax(0, 1fr);
+  gap: 12px;
+  align-items: center;
+  padding: 14px 16px;
+  border: 1px solid rgba(28, 55, 45, 0.12);
+  border-radius: 18px;
+  background: rgba(255, 255, 255, 0.88);
+  transition:
+    border-color 140ms ease,
+    background 140ms ease,
+    transform 140ms ease;
+}
+
+.puzzle-option:hover {
+  transform: translateY(-1px);
+  border-color: rgba(28, 55, 45, 0.22);
+}
+
+.puzzle-option.selected {
+  border-color: rgba(21, 79, 58, 0.42);
+  background: rgba(220, 239, 229, 0.72);
+}
+
+.puzzle-option input {
+  margin: 0;
+}
+
+.puzzle-option-seq {
+  font-size: 0.88rem;
+  font-weight: 700;
+  color: #42685a;
+}
+
+.puzzle-option-text {
+  display: grid;
+  gap: 2px;
+}
+
+.puzzle-option-text span {
+  color: #46695d;
+  font-size: 0.88rem;
+}
+
 .primary-button,
 .secondary-button,
 .ghost-button {

frontend/src/lib/api.ts

@@ -23,6 +23,15 @@ export type SessionResponse = {
   };
 };
 
+export type PuzzleOption = {
+  puzzle_id: string;
+  title: string;
+  sequence: number;
+  puzzle_type: PuzzleType;
+  difficulty: Difficulty;
+  args: string;
+};
+
 export type SubmitResponse = {
   solved: boolean;
   elapsed_ms: number | null;
@@ -48,6 +57,7 @@ export async function createSession(input: {
   player_name: string;
   puzzle_type: PuzzleType;
   difficulty: Difficulty;
+  puzzle_id: string;
 }): Promise<SessionResponse> {
   return handle<SessionResponse>(
     await fetch("/api/sessions", {
@@ -58,6 +68,17 @@ export async function createSession(input: {
   );
 }
 
+export async function fetchPuzzleOptions(
+  puzzleType: PuzzleType,
+  difficulty: Difficulty,
+): Promise<PuzzleOption[]> {
+  const params = new URLSearchParams({
+    puzzle_type: puzzleType,
+    difficulty,
+  });
+  return handle<PuzzleOption[]>(await fetch(`/api/puzzles?${params.toString()}`));
+}
+
 export async function fetchSession(sessionId: string): Promise<SessionResponse> {
   return handle<SessionResponse>(await fetch(`/api/sessions/${sessionId}`));
 }

frontend/src/routes/DonePage.tsx

@@ -35,6 +35,7 @@ export function DonePage() {
         playerName: state?.playerName ?? "",
         puzzleType: state?.session?.puzzle_type,
         difficulty: state?.session?.difficulty,
+        puzzleId: state?.session?.puzzle_id,
       },
     });
   }
@@ -51,7 +52,7 @@ export function DonePage() {
           </p>
           <div className="button-row">
             <button className="primary-button" type="button" onClick={playAgain}>
-              Start Another Random Puzzle
+              Choose Another Puzzle
             </button>
             <button className="ghost-button" type="button" onClick={() => navigate("/")}>
               Back Home

frontend/src/routes/HomePage.tsx

@@ -1,8 +1,14 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import type { FormEvent } from "react";
 import { useLocation, useNavigate } from "react-router-dom";
 
-import { createSession, type Difficulty, type PuzzleType } from "../lib/api";
+import {
+  createSession,
+  fetchPuzzleOptions,
+  type Difficulty,
+  type PuzzleOption,
+  type PuzzleType,
+} from "../lib/api";
 
 const PUZZLE_OPTIONS: Array<{ value: PuzzleType; label: string; blurb: string }> = [
   { value: "bridges", label: "Bridges", blurb: "Connect islands with single or double links." },
@@ -17,14 +23,56 @@ export function HomePage() {
   const navigate = useNavigate();
   const location = useLocation();
   const defaults = (location.state as
-    | { playerName?: string; puzzleType?: PuzzleType; difficulty?: Difficulty }
+    | { playerName?: string; puzzleType?: PuzzleType; difficulty?: Difficulty; puzzleId?: string }
     | null) ?? { playerName: "", puzzleType: "bridges", difficulty: "easy" };
   const [playerName, setPlayerName] = useState(defaults.playerName ?? "");
   const [puzzleType, setPuzzleType] = useState(defaults.puzzleType ?? "bridges");
   const [difficulty, setDifficulty] = useState(defaults.difficulty ?? "easy");
+  const [puzzleOptions, setPuzzleOptions] = useState<PuzzleOption[]>([]);
+  const [selectedPuzzleId, setSelectedPuzzleId] = useState(defaults.puzzleId ?? "");
+  const [loadingPuzzles, setLoadingPuzzles] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [submitting, setSubmitting] = useState(false);
 
+  useEffect(() => {
+    let cancelled = false;
+    async function loadPuzzles() {
+      setLoadingPuzzles(true);
+      setError(null);
+      try {
+        const options = await fetchPuzzleOptions(puzzleType, difficulty);
+        if (cancelled) {
+          return;
+        }
+        setPuzzleOptions(options);
+        setSelectedPuzzleId((current) => {
+          if (current && options.some((option) => option.puzzle_id === current)) {
+            return current;
+          }
+          const preferred = defaults.puzzleId;
+          if (preferred && options.some((option) => option.puzzle_id === preferred)) {
+            return preferred;
+          }
+          return options[0]?.puzzle_id ?? "";
+        });
+      } catch (caught) {
+        if (!cancelled) {
+          setPuzzleOptions([]);
+          setSelectedPuzzleId("");
+          setError(caught instanceof Error ? caught.message : "Could not load puzzle choices.");
+        }
+      } finally {
+        if (!cancelled) {
+          setLoadingPuzzles(false);
+        }
+      }
+    }
+    void loadPuzzles();
+    return () => {
+      cancelled = true;
+    };
+  }, [puzzleType, difficulty, defaults.puzzleId]);
+
   async function onSubmit(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
     setSubmitting(true);
@@ -34,8 +82,11 @@ export function HomePage() {
         player_name: playerName,
         puzzle_type: puzzleType,
         difficulty,
+        puzzle_id: selectedPuzzleId,
+      });
+      navigate(`/play/${session.session_id}`, {
+        state: { session, playerName, puzzleId: selectedPuzzleId },
       });
-      navigate(`/play/${session.session_id}`, { state: { session, playerName } });
     } catch (caught) {
       setError(caught instanceof Error ? caught.message : "Could not create a session.");
     } finally {
@@ -50,9 +101,10 @@ export function HomePage() {
           <div className="eyebrow">TopoBench Space</div>
           <h1>Play the benchmark, not just the report.</h1>
           <p>
-            This Space pulls real TopoBench puzzles from Hugging Face, 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, 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.
           </p>
         </section>
 
@@ -99,11 +151,44 @@ 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>
+                    ))
+                  )}
+                </div>
+              </div>
+
               {error ? <div className="status-box error">{error}</div> : null}
 
               <div className="button-row">
-                <button className="primary-button" type="submit" disabled={submitting}>
-                  {submitting ? "Starting..." : "Start Puzzle"}
+                <button
+                  className="primary-button"
+                  type="submit"
+                  disabled={submitting || loadingPuzzles || !selectedPuzzleId}
+                >
+                  {submitting ? "Starting..." : "Start Chosen Puzzle"}
                 </button>
               </div>
             </form>

frontend/src/routes/PlayPage.tsx

@@ -28,6 +28,7 @@ function formatElapsed(ms: number) {
 type LocationState = {
   session?: SessionResponse;
   playerName?: string;
+  puzzleId?: string;
 };
 
 export function PlayPage() {
@@ -117,12 +118,13 @@ export function PlayPage() {
     }
   }
 
-  function newRandom() {
+  function chooseAnother() {
     navigate("/", {
       state: {
         playerName: state?.playerName ?? "",
         puzzleType: session?.puzzle_type,
         difficulty: session?.difficulty,
+        puzzleId: session?.puzzle_id,
       },
     });
   }
@@ -184,8 +186,8 @@ export function PlayPage() {
               <button className="ghost-button" type="button" onClick={resetBoard}>
                 Reset Board
               </button>
-              <button className="secondary-button" type="button" onClick={newRandom}>
-                New Random Puzzle
+              <button className="secondary-button" type="button" onClick={chooseAnother}>
+                Choose Another Puzzle
               </button>
             </div>
 

space_app/dataset.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import random
 from collections import defaultdict
 from typing import Iterable
 
@@ -11,7 +10,6 @@ from .models import ALLOWED_DIFFICULTIES, ALLOWED_PUZZLES, DatasetRow
 
 class DatasetStore:
     def __init__(self, rows: Iterable[DatasetRow], *, seed: int = 0) -> None:
-        self._rng = random.Random(seed)
         self._index: dict[tuple[str, str], list[DatasetRow]] = defaultdict(list)
         self._rows_by_filename: dict[str, DatasetRow] = {}
         for row in rows:
@@ -32,20 +30,17 @@ class DatasetStore:
             rows.append(DatasetRow.from_payload(row))
         return cls(rows)
 
-    def choose_row(
+    def list_rows(
         self,
         *,
         puzzle_type: str,
         difficulty: str,
-        solved_filenames: set[str],
-    ) -> DatasetRow:
+        limit: int = 50,
+    ) -> list[DatasetRow]:
         candidates = list(self._index[(puzzle_type, difficulty)])
         if not candidates:
             raise ValueError(f"No puzzles available for {puzzle_type}:{difficulty}")
-        unsolved = [row for row in candidates if row.filename not in solved_filenames]
-        pool = unsolved or candidates
-        return self._rng.choice(pool)
+        return candidates[:limit]
 
     def get_row(self, filename: str) -> DatasetRow:
         return self._rows_by_filename[filename]
-

space_app/main.py

@@ -15,6 +15,7 @@ from .db import SessionStore
 from .models import engine_for_puzzle, normalize_player_name
 from .schemas import (
     CreateSessionRequest,
+    PuzzleOptionResponse,
     SessionPayload,
     SessionResponse,
     SubmitResponse,
@@ -90,6 +91,32 @@ def create_app(
     def health() -> dict[str, str]:
         return {"status": "ok"}
 
+    @app.get("/api/puzzles", response_model=list[PuzzleOptionResponse])
+    def list_puzzles(
+        puzzle_type: str = Query(...),
+        difficulty: str = Query(...),
+        current_dataset_store: DatasetStore = Depends(get_dataset_store),
+    ) -> list[PuzzleOptionResponse]:
+        try:
+            rows = current_dataset_store.list_rows(
+                puzzle_type=puzzle_type,
+                difficulty=difficulty,
+                limit=50,
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        return [
+            PuzzleOptionResponse(
+                puzzle_id=row.filename,
+                title=row.filename,
+                sequence=index,
+                puzzle_type=row.puzzlename,
+                difficulty=row.difficulty,
+                args=row.args,
+            )
+            for index, row in enumerate(rows, start=1)
+        ]
+
     @app.post("/api/sessions", response_model=SessionResponse)
     def create_session(
         request: CreateSessionRequest,
@@ -100,16 +127,15 @@ 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.")
-        solved = current_session_store.get_solved_filenames(
-            player_name_norm=player_name_norm,
-            puzzle_type=request.puzzle_type,
-            difficulty=request.difficulty,
-        )
-        row = current_dataset_store.choose_row(
-            puzzle_type=request.puzzle_type,
-            difficulty=request.difficulty,
-            solved_filenames=solved,
-        )
+        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,

space_app/schemas.py

@@ -11,6 +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)
 
     @field_validator("puzzle_type")
     @classmethod
@@ -37,6 +38,15 @@ class SessionPayload(BaseModel):
     image_base64: str | None = None
 
 
+class PuzzleOptionResponse(BaseModel):
+    puzzle_id: str
+    title: str
+    sequence: int
+    puzzle_type: str
+    difficulty: str
+    args: str
+
+
 class SessionResponse(BaseModel):
     session_id: str
     engine: str

tests/test_api.py

@@ -64,12 +64,22 @@ class ApiTests(unittest.TestCase):
         self.tempdir.cleanup()
 
     def test_session_lifecycle(self) -> None:
+        list_response = self.client.get(
+            "/api/puzzles",
+            params={"puzzle_type": "bridges", "difficulty": "easy"},
+        )
+        self.assertEqual(list_response.status_code, 200)
+        options = list_response.json()
+        self.assertEqual(len(options), 1)
+        self.assertEqual(options[0]["puzzle_id"], "bridges_1.txt")
+
         create_response = self.client.post(
             "/api/sessions",
             json={
                 "player_name": "Ada Lovelace",
                 "puzzle_type": "bridges",
                 "difficulty": "easy",
+                "puzzle_id": "bridges_1.txt",
             },
         )
         self.assertEqual(create_response.status_code, 200)
@@ -77,6 +87,29 @@ class ApiTests(unittest.TestCase):
         self.assertEqual(session["puzzle_type"], "bridges")
         self.assertEqual(session["payload"]["problem_ascii"], "1.1\n...\n1.1")
 
+    def test_session_requires_matching_selected_puzzle(self) -> None:
+        create_response = self.client.post(
+            "/api/sessions",
+            json={
+                "player_name": "Ada Lovelace",
+                "puzzle_type": "flow_free",
+                "difficulty": "easy",
+                "puzzle_id": "bridges_1.txt",
+            },
+        )
+        self.assertEqual(create_response.status_code, 400)
+
+    def test_ready_and_submit_lifecycle(self) -> None:
+        create_response = self.client.post(
+            "/api/sessions",
+            json={
+                "player_name": "Ada Lovelace",
+                "puzzle_type": "bridges",
+                "difficulty": "easy",
+                "puzzle_id": "bridges_1.txt",
+            },
+        )
+        session = create_response.json()
         ready_response = self.client.post(f"/api/sessions/{session['session_id']}/ready")
         self.assertEqual(ready_response.status_code, 200)
         self.assertIsNotNone(ready_response.json()["started_at"])
@@ -99,4 +132,3 @@ class ApiTests(unittest.TestCase):
             headers={"Authorization": "Bearer secret-token"},
         )
         self.assertEqual(authorized.status_code, 200)
-

tests/test_core.py

@@ -14,32 +14,26 @@ class CoreTests(unittest.TestCase):
     def test_normalize_player_name(self) -> None:
         self.assertEqual(normalize_player_name("  Ada   Lovelace  "), "ada lovelace")
 
-    def test_dataset_store_skips_solved_rows_until_exhausted(self) -> None:
+    def test_dataset_store_lists_first_fifty_in_dataset_order(self) -> None:
         rows = [
             DatasetRow(
-                filename="a.txt",
+                filename=f"puzzle_{index:02d}.txt",
                 puzzlename="bridges",
                 args="5x5de",
-                problem="1",
-                solution="1",
+                problem=str(index),
+                solution=str(index),
                 difficulty="easy",
-            ),
-            DatasetRow(
-                filename="b.txt",
-                puzzlename="bridges",
-                args="5x5de",
-                problem="2",
-                solution="2",
-                difficulty="easy",
-            ),
+            )
+            for index in range(60)
         ]
         store = DatasetStore(rows, seed=0)
-        chosen = store.choose_row(
+        listed = store.list_rows(
             puzzle_type="bridges",
             difficulty="easy",
-            solved_filenames={"a.txt"},
         )
-        self.assertEqual(chosen.filename, "b.txt")
+        self.assertEqual(len(listed), 50)
+        self.assertEqual(listed[0].filename, "puzzle_00.txt")
+        self.assertEqual(listed[-1].filename, "puzzle_49.txt")
 
     def test_session_store_records_submission(self) -> None:
         with tempfile.TemporaryDirectory() as tempdir: