loop-benchmarking

bot.ts (94206B)

---

 // Bot: "The Brain" -- phase orchestration, AI decisions, test derivation
 // NEVER imports from Playwright directly. Uses only TetrisDriver interface.
 
 import type {
   Grid,
   PieceType,
   TetrisDriver,
   DriverCalibration,
   CalibrationDrift,
   GridSnapshot,
   StartCandidate,
   TestResult,
   GameplayStats,
   GameSession,
   CompetitivePlayResult,
   SurveyData,
 } from "./types";
 
 // ---------------------------------------------------------------------------
 // Pierre Dellacherie's 4-heuristic Tetris AI (2003) with Colin Fahey's
 // GA-optimized weights. Reference implementation: LeeYiyuan/tetrisai (MIT)
 // ---------------------------------------------------------------------------
 
 const W_HEIGHT = -0.510066;
 const W_LINES = 0.760666;
 const W_HOLES = -0.35663;
 const W_BUMPINESS = -0.184483;
 
 const GRID_ROWS = 20;
 const GRID_COLS = 10;
 
 const PIECES: Record<string, [number, number][][]> = {
   I: [
     [[0, 0], [0, 1], [0, 2], [0, 3]],
     [[0, 0], [1, 0], [2, 0], [3, 0]],
     [[0, 0], [0, 1], [0, 2], [0, 3]],
     [[0, 0], [1, 0], [2, 0], [3, 0]],
   ],
   O: [
     [[0, 0], [0, 1], [1, 0], [1, 1]],
     [[0, 0], [0, 1], [1, 0], [1, 1]],
     [[0, 0], [0, 1], [1, 0], [1, 1]],
     [[0, 0], [0, 1], [1, 0], [1, 1]],
   ],
   T: [
     [[0, 1], [1, 0], [1, 1], [1, 2]],
     [[0, 0], [1, 0], [1, 1], [2, 0]],
     [[0, 0], [0, 1], [0, 2], [1, 1]],
     [[0, 1], [1, 0], [1, 1], [2, 1]],
   ],
   S: [
     [[0, 1], [0, 2], [1, 0], [1, 1]],
     [[0, 0], [1, 0], [1, 1], [2, 1]],
     [[0, 1], [0, 2], [1, 0], [1, 1]],
     [[0, 0], [1, 0], [1, 1], [2, 1]],
   ],
   Z: [
     [[0, 0], [0, 1], [1, 1], [1, 2]],
     [[0, 1], [1, 0], [1, 1], [2, 0]],
     [[0, 0], [0, 1], [1, 1], [1, 2]],
     [[0, 1], [1, 0], [1, 1], [2, 0]],
   ],
   J: [
     [[0, 0], [1, 0], [1, 1], [1, 2]],
     [[0, 0], [0, 1], [1, 0], [2, 0]],
     [[0, 0], [0, 1], [0, 2], [1, 2]],
     [[0, 1], [1, 1], [2, 1], [2, 0]],
   ],
   L: [
     [[0, 2], [1, 0], [1, 1], [1, 2]],
     [[0, 0], [1, 0], [2, 0], [2, 1]],
     [[0, 0], [0, 1], [0, 2], [1, 0]],
     [[0, 0], [0, 1], [1, 1], [2, 1]],
   ],
 };
 
 interface Placement {
   rotations: number;
   column: number;
   score: number;
   linesCleared: number;
   pieceType: string;
 }
 
 function findBestPlacement(board: Grid, pieceType: PieceType): Placement | null {
   const rotations = PIECES[pieceType];
   if (!rotations) return findBestPlacementGeneric(board);
 
   let bestScore = -Infinity;
   let bestPlacement: Placement | null = null;
 
   for (let rot = 0; rot < rotations.length; rot++) {
     const shape = rotations[rot];
     const minCol = Math.min(...shape.map(([, c]) => c));
     const maxCol = Math.max(...shape.map(([, c]) => c));
     const pieceWidth = maxCol - minCol + 1;
 
     for (let col = -minCol; col <= GRID_COLS - pieceWidth + (-minCol); col++) {
       const simResult = simulateDropPiece(board, shape, col);
       if (!simResult) continue;
 
       const { cleared, resultBoard } = simResult;
       const score =
         W_HEIGHT * aggregateHeight(resultBoard) +
         W_LINES * cleared +
         W_HOLES * countHoles(resultBoard) +
         W_BUMPINESS * bumpiness(resultBoard);
 
       if (score > bestScore) {
         bestScore = score;
         bestPlacement = { rotations: rot, column: col, score, linesCleared: cleared, pieceType };
       }
     }
   }
 
   return bestPlacement;
 }
 
 function findBestPlacementGeneric(board: Grid): Placement | null {
   let bestScore = -Infinity;
   let bestPlacement: Placement | null = null;
 
   for (let col = 0; col < GRID_COLS; col++) {
     const simGrid = simulateDropSingleCell(board, col);
     if (!simGrid) continue;
     const { cleared, resultBoard } = clearLines(simGrid);
     const score =
       W_HEIGHT * aggregateHeight(resultBoard) +
       W_LINES * cleared +
       W_HOLES * countHoles(resultBoard) +
       W_BUMPINESS * bumpiness(resultBoard);
     if (score > bestScore) {
       bestScore = score;
       bestPlacement = { rotations: 0, column: col, score, linesCleared: cleared, pieceType: "unknown" };
     }
   }
   return bestPlacement;
 }
 
 function simulateDropPiece(
   board: Grid, shape: [number, number][], col: number
 ): { cleared: number; resultBoard: Grid } | null {
   let landRow = -1;
 
   for (let row = 0; row <= GRID_ROWS; row++) {
     let valid = true;
     for (const [dr, dc] of shape) {
       const r = row + dr;
       const c = col + dc;
       if (r >= GRID_ROWS || c < 0 || c >= GRID_COLS) { valid = false; break; }
       if (r >= 0 && board[r][c]) { valid = false; break; }
     }
     if (!valid) { landRow = row - 1; break; }
   }
 
   if (landRow < 0) {
     let valid = true;
     for (const [dr, dc] of shape) {
       const r = dr;
       const c = col + dc;
       if (r >= GRID_ROWS || c < 0 || c >= GRID_COLS || (r >= 0 && board[r][c])) { valid = false; break; }
     }
     if (valid) landRow = 0;
     else return null;
   }
 
   const newBoard: Grid = board.map((row) => [...row]);
   for (const [dr, dc] of shape) {
     const r = landRow + dr;
     const c = col + dc;
     if (r >= 0 && r < GRID_ROWS && c >= 0 && c < GRID_COLS) newBoard[r][c] = true;
   }
 
   return clearLines(newBoard);
 }
 
 function simulateDropSingleCell(board: Grid, col: number): Grid | null {
   if (col < 0 || col >= GRID_COLS) return null;
   let landRow = -1;
   for (let r = GRID_ROWS - 1; r >= 0; r--) {
     if (!board[r][col]) { landRow = r; break; }
   }
   if (landRow < 0) return null;
   const newGrid: Grid = board.map((row) => [...row]);
   newGrid[landRow][col] = true;
   return newGrid;
 }
 
 function stripActivePiece(grid: Grid, activeCells: [number, number][]): Grid {
   const result: Grid = grid.map((row) => [...row]);
   for (const [r, c] of activeCells) {
     if (r >= 0 && r < result.length && c >= 0 && c < result[r].length) result[r][c] = false;
   }
   return result;
 }
 
 function clearLines(grid: Grid): { cleared: number; resultBoard: Grid } {
   const remaining: boolean[][] = [];
   let cleared = 0;
   for (const row of grid) {
     if (row.every(Boolean)) cleared++;
     else remaining.push([...row]);
   }
   while (remaining.length < GRID_ROWS) remaining.unshift(new Array(GRID_COLS).fill(false));
   return { cleared, resultBoard: remaining };
 }
 
 function aggregateHeight(grid: Grid): number {
   let total = 0;
   for (let col = 0; col < GRID_COLS; col++) {
     for (let row = 0; row < GRID_ROWS; row++) {
       if (grid[row]?.[col]) { total += GRID_ROWS - row; break; }
     }
   }
   return total;
 }
 
 function countHoles(grid: Grid): number {
   let holes = 0;
   for (let col = 0; col < GRID_COLS; col++) {
     let blockFound = false;
     for (let row = 0; row < GRID_ROWS; row++) {
       if (grid[row]?.[col]) blockFound = true;
       else if (blockFound) holes++;
     }
   }
   return holes;
 }
 
 function bumpiness(grid: Grid): number {
   const heights: number[] = [];
   for (let col = 0; col < GRID_COLS; col++) {
     let h = 0;
     for (let row = 0; row < GRID_ROWS; row++) {
       if (grid[row]?.[col]) { h = GRID_ROWS - row; break; }
     }
     heights.push(h);
   }
   let bump = 0;
   for (let i = 0; i < heights.length - 1; i++) bump += Math.abs(heights[i] - heights[i + 1]);
   return bump;
 }
 
 function countFilled(grid: Grid): number {
   let count = 0;
   for (const row of grid) for (const cell of row) if (cell) count++;
   return count;
 }
 
 // ---------------------------------------------------------------------------
 // Helper
 // ---------------------------------------------------------------------------
 
 function boundingBox(cells: [number, number][]): { w: number; h: number } {
   const minRow = Math.min(...cells.map(([r]) => r));
   const maxRow = Math.max(...cells.map(([r]) => r));
   const minCol = Math.min(...cells.map(([, c]) => c));
   const maxCol = Math.max(...cells.map(([, c]) => c));
   return { w: maxCol - minCol + 1, h: maxRow - minRow + 1 };
 }
 
 /**
  * Compute a position-invariant key for an active piece shape. Subtracts the
  * minimum row/col so the shape is translated to (0,0), then sorts and joins.
  * Two active-piece cell sets that differ only by position (e.g. because the
  * piece auto-dropped during the test) will produce the same key.
  */
 function normalizedShapeKey(cells: [number, number][]): string {
   if (cells.length === 0) return "";
   const minRow = Math.min(...cells.map(([r]) => r));
   const minCol = Math.min(...cells.map(([, c]) => c));
   return cells
     .map(([r, c]) => `${r - minRow},${c - minCol}`)
     .sort()
     .join("|");
 }
 
 function countFilledInTopRows(grid: Grid, rows: number): number {
   let count = 0;
   for (let r = 0; r < Math.min(rows, grid.length); r++) {
     for (let c = 0; c < grid[r].length; c++) if (grid[r][c]) count++;
   }
   return count;
 }
 
 // ---------------------------------------------------------------------------
 // Phase orchestration
 // ---------------------------------------------------------------------------
 
 interface LoadResult {
   loaded: boolean;
   detail: string;
   errorsOnLoad: number;
 }
 
 interface PhaseState {
   gameStarted: boolean;
   mechanicsWork: boolean;
   piecesWork: boolean;
   gameplayWorks: boolean;
 }
 
 const ALL_TEST_NAMES = [
   "game_loads",
   "game_starts",
   "auto_drop",
   "move_left",
   "move_right",
   "move_down",
   "rotate",
   "hard_drop",
   "all_pieces_rotate",
   "piece_locks",
   "new_piece_spawns",
   "multiple_pieces",
   "line_clear",
   "score_increases_on_clear",
   "score_element_visible",
   "game_over",
   "playable_30s",
   "multi_line_clear",
   "score_scaling",
   "level_progression",
   "speed_progression",
   "next_piece_preview",
   "game_over_display",
   "counter_clockwise_rotation",
   "soft_drop_distinct",
   "rendering_clean",
 ];
 
 function emptyCalibration(consoleErrors: string[]): DriverCalibration {
   return {
     renderer: "unknown",
     gridDetected: false,
     gridBounds: null,
     cellWidth: 0,
     cellHeight: 0,
     controls: { left: "ArrowLeft", right: "ArrowRight", down: "ArrowDown", rotate: "ArrowUp", drop: "Space" },
     controlMap: null,
     startMechanism: "unknown",
     scoreElementSelector: null,
     levelElementSelector: null,
     backgroundColor: null,
     consoleErrors,
     gridConfidence: 0,
     gridDetectedAt: "initial",
   };
 }
 
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
 
 export async function runAllTests(
   driver: TetrisDriver,
   serverUrl: string
 ): Promise<{
   testResults: TestResult[];
   calibration: DriverCalibration;
   gameplay: GameplayStats;
   session: GameSession;
   survey: SurveyData;
   competitivePlay: CompetitivePlayResult | null;
   calibrationDrift: CalibrationDrift;
 }> {
   const gameplay: GameplayStats = {
     pieces_placed: 0,
     lines_cleared: 0,
     max_score_observed: 0,
     play_duration_seconds: 0,
     errors_during_play: 0,
   };
 
   const session: GameSession = {
     started: false,
     startMechanism: "unknown",
     piecesSpawned: 0,
     piecesLocked: 0,
     linesCleared: 0,
     rotationsObserved: 0,
     movementsObserved: 0,
     hardDropsObserved: 0,
     gameOverDetected: false,
     gameOverText: null,
     gameOverRestartAvailable: false,
     consoleErrors: [],
     durationSeconds: 0,
     pieceTypes: new Set<string>(),
     scoreValues: [],
     gridReadSuccess: 0,
     gridReadFail: 0,
     frames: 0,
     events: [],
     skippedPhases: [],
     distinctRotationShapes: 0,
     rotationShapesByPiece: new Map<string, Set<string>>(),
   };
 
   let survey: SurveyData = {
     has_overlay: false,
     has_canvas: false,
     has_dom_grid: false,
     visible_text: [],
     clickable_elements: 0,
   };
 
   let competitivePlay: CompetitivePlayResult | null = null;
 
   // ---- Phase 1: Load the page ----
   const loadResult = await driver.loadPage(serverUrl);
   if (!loadResult.loaded) {
     const failedTests = ALL_TEST_NAMES.map((name) => ({
       name, pass: false, detail: loadResult.detail,
     }));
     return {
       testResults: failedTests,
       calibration: emptyCalibration(driver.getConsoleErrors()),
       gameplay, session, survey, competitivePlay,
       calibrationDrift: driver.getCalibrationDrift(),
     };
   }
 
   // ---- Pre-test survey ----
   survey = await driver.surveyPage();
 
   // ---- Detect game-shaped landmarks for the game_loads test ----
   try {
     session.gameLoadLandmarks = await driver.detectGameLandmarks();
   } catch {
     session.gameLoadLandmarks = undefined;
   }
 
   // ---- Phase 2: Discover + verify start, then calibrate ----
   // Bridge flow: try each candidate, ask verifyGameStarted() to confirm,
   // commit the first verified candidate. On false positive, reload and try
   // the next. If nothing verifies, tell the driver to reject and skip the
   // legacy fuzzy detector (which historically clicked Pause buttons etc.).
   let cal: DriverCalibration;
   let verified: { candidate: StartCandidate } | null = null;
   try {
     verified = await detectStartWithVerification(driver, serverUrl);
   } catch (err) {
     console.log(`[bot] bridge detection threw: ${err instanceof Error ? err.message : String(err)}`);
   }
 
   try {
     if (verified) {
       driver.confirmStartMechanism(verified.candidate);
     } else {
       driver.rejectStartMechanism();
     }
     cal = await driver.calibrate();
     session.started = cal.startMechanism !== "unknown";
     session.startMechanism = cal.startMechanism;
   } catch (err) {
     cal = emptyCalibration(driver.getConsoleErrors());
   }
 
   // Merge console errors from calibration
   for (const e of cal.consoleErrors) {
     if (!session.consoleErrors.includes(e)) session.consoleErrors.push(e);
   }
 
   let gameStarted = session.started;
   if (!gameStarted) {
     session.skippedPhases.push(
       "mechanics: game did not start",
       "pieces: game did not start",
       "gameplay: game did not start",
       "gameover: game did not start",
       "endurance: game did not start",
       "competitive: game did not start"
     );
   } else {
     driver.armInactivityWatchdog();
   }
 
   // Re-calibrate after start: DOM games may create grid cells dynamically
   if (gameStarted && !cal.gridDetected) {
     try {
       await driver.wait(500);
       const recal = await driver.recalibrate();
       if (recal.gridDetected) {
         cal = recal;
       }
     } catch { /* keep original */ }
   }
 
   // Control discovery: probe what each key actually does. This is the
   // difference between "ArrowDown is soft drop" (assumption) and "on this
   // particular game, ArrowDown is hard drop" (measurement). Runs only once
   // per session -- the result is cached on the driver and flows through
   // subsequent pressKey() calls automatically.
   if (gameStarted && cal.gridDetected) {
     try {
       const controlMap = await driver.discoverControls(serverUrl);
       console.log(
         `[bot] control discovery complete: ` +
         `move_left=${controlMap.move_left.key ?? "?"}, ` +
         `move_right=${controlMap.move_right.key ?? "?"}, ` +
         `soft_drop=${controlMap.soft_drop.key ?? "NONE"}, ` +
         `hard_drop=${controlMap.hard_drop.key ?? "?"}, ` +
         `rotate_cw=${controlMap.rotate_cw.key ?? "?"}`
       );
       // Refresh the working calibration from the driver -- discoverControls()
       // updates cal.controlMap and cal.controls on the cached calibration
       // object in-place.
       cal = driver.getCalibration();
     } catch (err) {
       console.log(`[bot] control discovery threw: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 
   // ---- Phases 3-8 wrapped in an inactivity guard: if the driver's
   // watchdog fires, we bail out of gameplay phases early but still write
   // a partial report with whatever did run. ----
   let mechanicsWork = false;
   let piecesWork = false;
   let gameplayWorks = false;
 
   try {
     // ---- Phase 3: Basic mechanics ----
     if (gameStarted && cal.gridDetected) {
       await runBasicMechanicsPhase(driver, session);
       mechanicsWork =
         session.movementsObserved > 0 ||
         session.rotationsObserved > 0 ||
         session.hardDropsObserved > 0 ||
         session.events.some((e) => e.type === "piece_moved");
     }
 
     if (gameStarted && !mechanicsWork) {
       session.skippedPhases.push(
         "pieces: mechanics failed",
         "gameplay: mechanics failed",
         "gameover: mechanics failed",
         "endurance: mechanics failed",
         "competitive: mechanics failed"
       );
     }
 
     // ---- Phase 4: Piece lifecycle ----
     if (mechanicsWork) {
       piecesWork = session.piecesLocked > 0 || session.hardDropsObserved > 0;
     }
 
     if (mechanicsWork && !piecesWork) {
       session.skippedPhases.push(
         "gameplay: piece lifecycle failed",
         "gameover: piece lifecycle failed",
         "endurance: piece lifecycle failed",
         "competitive: piece lifecycle failed"
       );
     }
 
     // ---- Phase 5: Gameplay ----
     if (piecesWork) {
       try {
         await driver.loadPage(serverUrl);
         cal = await driver.calibrate();
         if (gameStarted && !cal.gridDetected) {
           await driver.wait(500);
           const recal = await driver.recalibrate();
           if (recal.gridDetected) cal = recal;
         }
         session.started = session.started || cal.startMechanism !== "unknown";
       } catch (err) {
         if (err instanceof Error && err.name === "InactivityAbortError") throw err;
       }
 
       await runGameplayPhase(driver, session, gameplay);
       gameplayWorks = gameplay.pieces_placed > 0;
     }
 
     if (piecesWork && !gameplayWorks) {
       session.skippedPhases.push(
         "endurance: gameplay failed",
         "competitive: gameplay failed"
       );
     }
 
     // ---- Phase 6: Game over ----
     if (piecesWork) {
       try {
         await driver.loadPage(serverUrl);
         cal = await driver.calibrate();
         if (!cal.gridDetected) {
           await driver.wait(500);
           const recal = await driver.recalibrate();
           if (recal.gridDetected) cal = recal;
         }
       } catch (err) {
         if (err instanceof Error && err.name === "InactivityAbortError") throw err;
       }
 
       await runGameOverPhase(driver, session);
     }
 
     // ---- Phase 7: Endurance ----
     if (gameplayWorks) {
       try {
         await driver.loadPage(serverUrl);
         cal = await driver.calibrate();
         if (!cal.gridDetected) {
           await driver.wait(500);
           const recal = await driver.recalibrate();
           if (recal.gridDetected) cal = recal;
         }
       } catch (err) {
         if (err instanceof Error && err.name === "InactivityAbortError") throw err;
       }
 
       await runEndurancePhase(driver, session, gameplay);
     }
 
     // ---- Phase 8: Competitive play ----
     if (gameplayWorks) {
       try {
         await driver.loadPage(serverUrl);
         cal = await driver.calibrate();
         if (!cal.gridDetected) {
           await driver.wait(500);
           const recal = await driver.recalibrate();
           if (recal.gridDetected) cal = recal;
         }
       } catch (err) {
         if (err instanceof Error && err.name === "InactivityAbortError") throw err;
       }
 
       competitivePlay = await runCompetitivePlayPhase(driver, session, gameplay, serverUrl);
     } else if (!session.skippedPhases.some((p) => p.startsWith("competitive:"))) {
       session.skippedPhases.push("competitive: gameplay failed");
     }
   } catch (err) {
     if (err instanceof Error && err.name === "InactivityAbortError") {
       console.log(`[bot] inactivity watchdog fired: ${err.message}`);
       session.skippedPhases.push(`inactivity_abort: ${err.message}`);
     } else {
       throw err;
     }
   }
 
   session.durationSeconds = gameplay.play_duration_seconds;
 
   // ---- Derive test results ----
   const phaseState = { gameStarted, mechanicsWork, piecesWork, gameplayWorks };
   const testResults = deriveTestResults(session, cal, loadResult, driver.getConsoleErrors(), gameplay, phaseState, competitivePlay);
 
   const calibrationDrift = driver.getCalibrationDrift();
   return { testResults, calibration: cal, gameplay, session, survey, competitivePlay, calibrationDrift };
 }
 
 // ---------------------------------------------------------------------------
 // Phase implementations (use driver, never Playwright directly)
 // ---------------------------------------------------------------------------
 
 async function runBasicMechanicsPhase(
   driver: TetrisDriver,
   session: GameSession
 ): Promise<void> {
   // Auto-drop test: read grid twice with 5s gap, no input
   const snapT0 = await driver.readGrid();
   if (snapT0.grid) session.gridReadSuccess++;
   else session.gridReadFail++;
   session.frames++;
 
   await driver.wait(5000);
 
   const snapT1 = await driver.readGrid();
   if (snapT1.grid) session.gridReadSuccess++;
   else session.gridReadFail++;
   session.frames++;
 
   if (snapT0.grid && snapT1.grid && driver.gridsAreDifferent(snapT0.grid, snapT1.grid)) {
     const topBefore = countFilledInTopRows(snapT0.grid, 10);
     const topAfter = countFilledInTopRows(snapT1.grid, 10);
     const bottomBefore = snapT0.filledInBottom(10);
     const bottomAfter = snapT1.filledInBottom(10);
     if (bottomAfter > bottomBefore || topAfter < topBefore || driver.gridsAreDifferent(snapT0.grid, snapT1.grid)) {
       session.events.push({ type: "piece_moved", direction: "down", frame: session.frames });
     }
   }
 
   // Movement tests
   for (const dir of ["left", "right", "down"] as const) {
     const snapBefore = await driver.readGrid();
     if (snapBefore.grid) session.gridReadSuccess++;
     else session.gridReadFail++;
     session.frames++;
 
     await driver.pressKey(dir);
     await driver.wait(300);
 
     const snapAfter = await driver.readGrid();
     if (snapAfter.grid) session.gridReadSuccess++;
     else session.gridReadFail++;
     session.frames++;
 
     if (snapBefore.grid && snapAfter.grid && driver.gridsAreDifferent(snapBefore.grid, snapAfter.grid)) {
       session.movementsObserved++;
       session.events.push({ type: "piece_moved", direction: dir, frame: session.frames });
     }
   }
 
   // Rotation test: press rotate 4 times and check how many DISTINCT shapes
   // the piece cycles through. A correctly working Tetris game lets you
   // rotate a non-O piece to at least 2 different states (I/S/Z have 2 total
   // states, J/L/T have 4). A broken game where rotation only changes the
   // piece once (then gets stuck) will only show 1 non-baseline shape, which
   // is not enough to pass this test.
   //
   // Shape comparison is position-invariant (see normalizedShapeKey) so that
   // auto-drop between presses doesn't confuse the detector.
   const snapBeforeRot = await driver.readGrid();
   if (snapBeforeRot.grid) session.gridReadSuccess++;
   else session.gridReadFail++;
   session.frames++;
 
   const observedShapes = new Set<string>();
   if (snapBeforeRot.activePieceCells && snapBeforeRot.activePieceCells.length > 0) {
     observedShapes.add(normalizedShapeKey(snapBeforeRot.activePieceCells));
   }
 
   let lastRotationSnap = snapBeforeRot;
   for (let i = 0; i < 4; i++) {
     await driver.pressKey("rotate");
     await driver.wait(100);
 
     const snap = await driver.readGrid();
     if (snap.grid) session.gridReadSuccess++;
     else session.gridReadFail++;
     session.frames++;
 
     if (snap.activePieceCells && snap.activePieceCells.length > 0) {
       observedShapes.add(normalizedShapeKey(snap.activePieceCells));
     }
     lastRotationSnap = snap;
 
     // Any observed change in the grid between successive rotations counts as
     // a "rotation observed" event for legacy metrics. This keeps the gameplay
     // phase's counters consistent with the old behavior for downstream tests
     // that still use session.rotationsObserved.
     if (
       i === 0 &&
       snapBeforeRot.grid &&
       snap.grid &&
       driver.gridsAreDifferent(snapBeforeRot.grid, snap.grid)
     ) {
       session.rotationsObserved++;
       session.events.push({ type: "piece_rotated", frame: session.frames });
     }
   }
 
   // Record the max number of distinct shapes ever seen in a single rotation
   // test. Later gameplay-phase probes may overwrite this if they see more.
   if (observedShapes.size > session.distinctRotationShapes) {
     session.distinctRotationShapes = observedShapes.size;
   }
 
   // Silence unused-variable warning: lastRotationSnap is kept for potential
   // debugging/extension.
   void lastRotationSnap;
 
   // Hard drop test
   const snapBeforeDrop = await driver.readGrid();
   if (snapBeforeDrop.grid) session.gridReadSuccess++;
   else session.gridReadFail++;
   session.frames++;
 
   await driver.pressKey("drop");
   await driver.wait(500);
 
   const snapAfterDrop = await driver.readGrid();
   if (snapAfterDrop.grid) session.gridReadSuccess++;
   else session.gridReadFail++;
   session.frames++;
 
   if (snapBeforeDrop.grid && snapAfterDrop.grid && driver.gridsAreDifferent(snapBeforeDrop.grid, snapAfterDrop.grid)) {
     const bottomFilled = snapAfterDrop.filledInBottom(5);
     if (bottomFilled > 0) {
       session.hardDropsObserved++;
       session.piecesLocked++;
       session.events.push({ type: "hard_drop", frame: session.frames });
       session.events.push({ type: "piece_locked", frame: session.frames, filledDelta: bottomFilled });
     }
   }
 
   // New piece spawns
   await driver.wait(500);
   const snapAfterSpawn = await driver.readGrid(snapAfterDrop.grid);
   if (snapAfterSpawn.grid) {
     session.gridReadSuccess++;
     session.frames++;
     if (snapAfterSpawn.hasFilledInTop(4)) {
       session.piecesSpawned++;
       if (snapAfterSpawn.activePieceCells) {
         const pt = snapAfterSpawn.activePieceType || "unknown";
         session.pieceTypes.add(pt);
         session.events.push({ type: "piece_spawned", pieceType: pt as PieceType, frame: session.frames });
       }
     }
   } else {
     session.gridReadFail++;
     session.frames++;
   }
 
   // Piece locks persistence test
   const snapPersist1 = await driver.readGrid();
   await driver.wait(2000);
   const snapPersist2 = await driver.readGrid();
   if (snapPersist1.grid && snapPersist2.grid) {
     session.gridReadSuccess += 2;
     session.frames += 2;
     const bottom1 = snapPersist1.filledInBottom(4);
     const bottom2 = snapPersist2.filledInBottom(4);
     if (bottom1 > 0 && bottom2 >= bottom1) {
       if (session.piecesLocked === 0) session.piecesLocked++;
     }
   }
 }
 
 async function runGameplayPhase(
   driver: TetrisDriver,
   session: GameSession,
   gameplay: GameplayStats
 ): Promise<void> {
   const snapBefore = await driver.readGrid();
   const filledBefore = snapBefore.filledCount;
   if (snapBefore.grid) session.gridReadSuccess++;
   else session.gridReadFail++;
   session.frames++;
 
   // Read initial score
   const initialScore = await driver.readScore();
   if (initialScore !== null) session.scoreValues.push(initialScore);
 
   // Play using AI
   const result = await playGame(driver, {
     maxPieces: 60,
     maxDurationMs: 45000,
     rotationTrack: session.rotationShapesByPiece,
   });
   gameplay.pieces_placed += result.piecesPlaced;
   gameplay.errors_during_play += result.errors;
   session.gridReadSuccess += result.gridReads;
   session.gridReadFail += result.gridReadFails;
   session.frames += result.gridReads + result.gridReadFails;
   session.piecesLocked += result.piecesPlaced;
 
   for (const sv of result.scoreValues) {
     session.scoreValues.push(sv);
     if (sv > gameplay.max_score_observed) gameplay.max_score_observed = sv;
   }
 
   if (result.linesCleared > 0) {
     session.linesCleared += result.linesCleared;
     gameplay.lines_cleared += result.linesCleared;
     for (let i = 0; i < result.linesCleared; i++) {
       session.events.push({ type: "line_cleared", count: 1, frame: session.frames });
     }
   }
 
   // Propagate score-before/after-clear from AI play
   if (result.scoreBeforeClear !== undefined && session.scoreBeforeClear === undefined) {
     session.scoreBeforeClear = result.scoreBeforeClear;
   }
   if (result.scoreAfterClear !== undefined && session.scoreAfterClear === undefined) {
     session.scoreAfterClear = result.scoreAfterClear;
   }
 
   // Read final score
   const finalScore = await driver.readScore();
   if (finalScore !== null) {
     session.scoreValues.push(finalScore);
     if (finalScore > gameplay.max_score_observed) gameplay.max_score_observed = finalScore;
   }
 
   // If no score element found, try to detect changing numbers
   if (session.scoreValues.length === 0) {
     // We cannot scan page text without Playwright directly, so skip this fallback
     // The driver's readScore handles the detection
   }
 
   if (result.piecesPlaced > 0) {
     session.events.push({
       type: "piece_locked",
       frame: session.frames,
       filledDelta: result.piecesPlaced * 4,
     });
   }
 
   // If no lines cleared by AI, try brute-force
   if (session.linesCleared === 0) {
     // Capture score before brute-force line clear attempt
     if (session.scoreBeforeClear === undefined) {
       const preScore = await driver.readScore();
       if (preScore !== null) session.scoreBeforeClear = preScore;
     }
 
     const cleared = await tryFillRow(driver, 10);
     gameplay.pieces_placed += 10;
     if (cleared) {
       session.linesCleared++;
       gameplay.lines_cleared++;
       session.events.push({ type: "line_cleared", count: 1, frame: session.frames });
 
       // Capture score after brute-force line clear
       if (session.scoreAfterClear === undefined) {
         await driver.wait(200);
         const postScore = await driver.readScore();
         if (postScore !== null) session.scoreAfterClear = postScore;
       }
     }
   }
 
   // Check if total filled decreased
   if (session.linesCleared === 0) {
     const snapAfter = await driver.readGrid();
     const filledAfter = snapAfter.filledCount;
     if (filledAfter < filledBefore && filledBefore > 0) {
       // Capture score around grid-verified line clear
       if (session.scoreBeforeClear === undefined) {
         // Use the last known score reading as proxy
         const lastKnown = session.scoreValues.length > 0
           ? session.scoreValues[session.scoreValues.length - 1]
           : null;
         if (lastKnown !== null) session.scoreBeforeClear = lastKnown;
       }
 
       session.linesCleared++;
       gameplay.lines_cleared++;
       session.events.push({ type: "line_cleared", count: 1, frame: session.frames });
 
       if (session.scoreAfterClear === undefined) {
         const postScore = await driver.readScore();
         if (postScore !== null) session.scoreAfterClear = postScore;
       }
     }
   }
 }
 
 async function runGameOverPhase(
   driver: TetrisDriver,
   session: GameSession
 ): Promise<void> {
   const MAX_DROPS = 40;
   const BATCH_SIZE = 5;
 
   // Capture game over text + restart option immediately after triggering game
   // over, before anything (e.g. Phase 8 page reload) can clear it.
   const captureGameOverDisplay = async (): Promise<void> => {
     try {
       session.gameOverText = await driver.detectGameOverText();
     } catch {
       session.gameOverText = null;
     }
     try {
       session.gameOverRestartAvailable = await driver.detectRestartOption();
     } catch {
       session.gameOverRestartAvailable = false;
     }
   };
 
   for (let i = 0; i < MAX_DROPS; i++) {
     await driver.pressKey("drop");
     await driver.wait(150);
 
     if ((i + 1) % BATCH_SIZE === 0) {
       const snap = await driver.readGrid();
       if (snap.grid) {
         session.gridReadSuccess++;
         session.frames++;
 
         if (snap.hasFilledInTop(4)) {
           await driver.pressKey("drop");
           await driver.wait(300);
           const snapAfter = await driver.readGrid();
           if (snapAfter.grid) {
             session.gridReadSuccess++;
             session.frames++;
             if (!driver.gridsAreDifferent(snap.grid, snapAfter.grid)) {
               session.gameOverDetected = true;
               session.events.push({ type: "game_over", frame: session.frames });
               await captureGameOverDisplay();
               return;
             }
           }
         }
       } else {
         session.gridReadFail++;
         session.frames++;
       }
     }
   }
 
   // Check for game over text in DOM
   const gameOverText = await driver.detectGameOverText();
   if (gameOverText) {
     const finalSnap = await driver.readGrid();
     if (finalSnap.grid && finalSnap.filledCount > 10) {
       session.gameOverDetected = true;
       session.events.push({ type: "game_over", frame: session.frames });
       // We already have the text; capture restart too.
       session.gameOverText = gameOverText;
       try {
         session.gameOverRestartAvailable = await driver.detectRestartOption();
       } catch {
         session.gameOverRestartAvailable = false;
       }
     }
   }
 }
 
 async function runEndurancePhase(
   driver: TetrisDriver,
   session: GameSession,
   gameplay: GameplayStats
 ): Promise<void> {
   const errorsBefore = driver.getConsoleErrors().length;
   const start = Date.now();
 
   const result = await playGame(driver, {
     maxDurationMs: 30000,
     rotationTrack: session.rotationShapesByPiece,
   });
 
   const elapsed = Math.round((Date.now() - start) / 1000);
   gameplay.pieces_placed += result.piecesPlaced;
   gameplay.lines_cleared += result.linesCleared;
   session.linesCleared += result.linesCleared;
   gameplay.play_duration_seconds += elapsed;
   gameplay.errors_during_play += result.errors;
   session.gridReadSuccess += result.gridReads;
   session.gridReadFail += result.gridReadFails;
   session.frames += result.gridReads + result.gridReadFails;
 
   const newErrors = driver.getConsoleErrors().slice(errorsBefore);
   for (const e of newErrors) {
     if (!session.consoleErrors.includes(e)) session.consoleErrors.push(e);
   }
 }
 
 /**
  * Test whether the game supports counter-clockwise rotation.
  *
  * The naive "press Z then press rotate, compare" approach is broken because
  * rotation state is ordinal: after Z (state 0->3) then rotate (3->0), the
  * piece returns to the original state regardless of direction, so the two
  * intermediate snapshots always differ. That test is a tautology.
  *
  * Instead we run each key against a FRESH baseline game by reloading the
  * page between presses. Both presses are then measured from rotation
  * state 0. If the two resulting grids match, both keys rotate in the same
  * direction; if they differ, they rotate opposite.
  *
  * Returns { done: false, ccw: null } when a reliable signal is unavailable
  * (e.g. no active piece, O-piece baseline, rotate key doesn't rotate at all).
  */
 async function testRotationDirection(
   driver: TetrisDriver,
   serverUrl: string
 ): Promise<{ done: boolean; ccw: boolean | null }> {
   // Helper: reload, start game, wait for an active piece to be visible.
   // On a fresh game the settled grid is empty, so we read WITHOUT passing a
   // settled grid and let readGrid use its top-6-rows fallback to detect the
   // active piece.
   const freshBaseline = async (): Promise<{
     piece: PieceType | null;
     grid: Grid | null;
     settled: Grid | null;
   }> => {
     try {
       const load = await driver.loadPage(serverUrl);
       if (!load.loaded) return { piece: null, grid: null, settled: null };
     } catch {
       return { piece: null, grid: null, settled: null };
     }
     try {
       await driver.calibrate();
     } catch {
       return { piece: null, grid: null, settled: null };
     }
 
     // Use an empty grid as the "settled" reference so the active piece is
     // detected as the full delta (any filled cell in current == active).
     // This is robust even when the game hasn't yet spawned a piece at the
     // moment of the first read.
     const emptySettled: Grid = Array.from({ length: GRID_ROWS }, () =>
       Array.from({ length: GRID_COLS }, () => false)
     );
 
     // Poll up to ~3s for an active piece to appear.
     let snap = await driver.readGrid(emptySettled);
     let attempts = 0;
     while (
       (!snap.activePieceCells || snap.activePieceCells.length !== 4) &&
       attempts < 30
     ) {
       await driver.wait(100);
       snap = await driver.readGrid(emptySettled);
       attempts++;
     }
 
     if (!snap.activePieceCells || snap.activePieceCells.length !== 4) {
       return { piece: null, grid: snap.grid, settled: emptySettled };
     }
     return {
       piece: snap.activePieceType,
       grid: snap.grid,
       settled: emptySettled,
     };
   };
 
   // Extract the active piece cells from a grid (assumes the grid contains
   // only the active piece, which is the case on a fresh game where the
   // settled grid is empty). Returns a position-normalized shape string so
   // that comparisons ignore where on the board the piece sits.
   const shapeKey = (grid: Grid): string | null => {
     const cells: [number, number][] = [];
     for (let r = 0; r < grid.length; r++) {
       for (let c = 0; c < grid[r].length; c++) {
         if (grid[r][c]) cells.push([r, c]);
       }
     }
     if (cells.length !== 4) return null;
     const minR = Math.min(...cells.map(([r]) => r));
     const minC = Math.min(...cells.map(([, c]) => c));
     return cells
       .map(([r, c]) => `${r - minR},${c - minC}`)
       .sort()
       .join("|");
   };
 
   // Helper: press a key, wait briefly for the game to process it, and
   // return the post-press grid if the piece's SHAPE differs from baseline.
   // We compare shape (not full grid) so that piece falling during the wait
   // does not confound the rotation measurement.
   const measureKeyShape = async (
     pressFn: () => Promise<void>,
     baseShape: string
   ): Promise<string | null> => {
     await pressFn();
     await driver.wait(80);
     const snap = await driver.readGrid();
     if (!snap.grid) return null;
     const shape = shapeKey(snap.grid);
     if (!shape) return null;
     if (shape === baseShape) return null;
     return shape;
   };
 
   // Only J, L, T pieces have 4 visually-distinct rotation states. I, S, Z
   // have only 2 (rotating CW vs CCW from state 0 produces an identical
   // visual). O is rotationally symmetric. So we can only distinguish
   // rotation directions using J, L, or T pieces.
   const DISTINGUISHABLE: Set<PieceType> = new Set<PieceType>(["J", "L", "T"]);
   const log = (msg: string) => console.log(`[ccw] ${msg}`);
 
   // Per-piece-type sample: the shape after pressing the calibrated rotate
   // key from a fresh-spawn baseline. Keyed by piece type so Trial 2 can
   // match whatever piece type its fresh reload happens to produce.
   const trial1Shapes = new Map<PieceType, string>();
 
   // ----- Trial 1: collect rotate-key shape samples for several piece types -----
   for (let attempt = 0; attempt < 10; attempt++) {
     const b = await freshBaseline();
     if (!b.grid || !b.piece) continue;
     if (!DISTINGUISHABLE.has(b.piece)) continue;
     if (trial1Shapes.has(b.piece)) continue;
     const baseShape = shapeKey(b.grid);
     if (!baseShape) continue;
     const afterShape = await measureKeyShape(
       () => driver.pressKey("rotate"),
       baseShape
     );
     if (afterShape) {
       trial1Shapes.set(b.piece, afterShape);
       log(`trial1: rotate changed ${b.piece} (samples: ${trial1Shapes.size})`);
       if (trial1Shapes.size >= DISTINGUISHABLE.size) break;
     } else {
       log(`trial1: rotate did NOT change ${b.piece}`);
     }
   }
   if (trial1Shapes.size === 0) {
     log("could not establish any Trial 1 reference direction");
     return { done: false, ccw: null };
   }
 
   // ----- Trial 2: press the raw "z" key from a fresh baseline whose piece
   // type matches one of our Trial 1 samples, and compare the resulting
   // shape to the corresponding Trial 1 shape. -----
   for (let attempt = 0; attempt < 10; attempt++) {
     const b = await freshBaseline();
     if (!b.grid || !b.piece) continue;
     const rotateShape = trial1Shapes.get(b.piece);
     if (!rotateShape) continue;
     const baseShape = shapeKey(b.grid);
     if (!baseShape) continue;
     const afterShape = await measureKeyShape(
       () => driver.pressRawKey("z"),
       baseShape
     );
     if (!afterShape) {
       log(`trial2: z caused no shape change on ${b.piece} -> CCW not supported`);
       return { done: true, ccw: false };
     }
     const opposite = afterShape !== rotateShape;
     log(
       `trial2: ${b.piece} rotate=${rotateShape} z=${afterShape} opposite=${opposite}`
     );
     return { done: true, ccw: opposite };
   }
 
   log("could not find Trial 2 baseline with matching piece");
   return { done: false, ccw: null };
 }
 
 async function runCompetitivePlayPhase(
   driver: TetrisDriver,
   session: GameSession,
   gameplay: GameplayStats,
   serverUrl: string
 ): Promise<CompetitivePlayResult> {
   // Dedicated rotation-direction test (run BEFORE the main play loop so that
   // each key press is measured from a fresh baseline game state). See
   // testRotationDirection() for details.
   let ccwTestDone = false;
   let ccwResult: boolean | null = null;
   try {
     const rotResult = await testRotationDirection(driver, serverUrl);
     ccwTestDone = rotResult.done;
     ccwResult = rotResult.ccw;
   } catch {
     ccwTestDone = false;
     ccwResult = null;
   }
 
   // Reload once more so competitive play starts from a clean game state.
   try {
     await driver.loadPage(serverUrl);
     await driver.calibrate();
   } catch {
     /* continue: play loop will still attempt to run */
   }
 
   const start = Date.now();
   const maxDuration = 60000;
 
   const result: CompetitivePlayResult & {
     _ccwResult?: boolean | null;
     _ccwTestDone?: boolean;
     _softDropDistinct?: boolean | null;
     _softDropTestDone?: boolean;
   } = {
     duration_seconds: 0,
     pieces_placed: 0,
     total_lines_cleared: 0,
     single_clears: 0,
     double_clears: 0,
     triple_clears: 0,
     tetris_clears: 0,
     max_combo: 0,
     score_readings: [],
     score_final: 0,
     score_increases: [],
     level_readings: [],
     level_final: 0,
     game_over_reached: false,
     game_over_text_found: null,
     restart_available: false,
     next_piece_visible: false,
     speed_increased: false,
     bugs_detected: [],
   };
 
   // Read initial score
   let lastScore = 0;
   const initialScore = await driver.readScore();
   if (initialScore !== null) {
     lastScore = initialScore;
     result.score_readings.push(lastScore);
   }
 
   // Read initial level
   const initialLevel = await driver.readLevel();
   if (initialLevel !== null) result.level_readings.push(initialLevel);
 
   // Measure initial drop speed
   const initialDropInterval = await driver.measureDropInterval();
 
   // Play loop
   // settledGrid = the locked board WITHOUT any active piece. Recomputed
   // after each placement by reading the fresh grid and stripping the newly-
   // spawned piece.
   let settledGrid: Grid | null = null;
   let pollCount = 0;
   let consecutiveClears = 0;
   let maxCombo = 0;
   let softDropTestDone = false;
   let softDropDistinct: boolean | null = null;
 
   let filledCellSamples: number[] = [];
   let trailCheckPieceMark = 0;
 
   while (Date.now() - start < maxDuration) {
     try {
       const snap = await driver.readGrid(settledGrid);
       pollCount++;
 
       if (!snap.grid) {
         await driver.wait(60);
         continue;
       }
 
       // Score tracking every 5th poll
       if (pollCount % 5 === 0) {
         const score = await driver.readScore();
         if (score !== null && score > 0) {
           result.score_readings.push(score);
           if (score > lastScore) {
             result.score_increases.push(score - lastScore);
             lastScore = score;
           }
         }
       }
 
       // Level tracking every 10th poll
       if (pollCount % 10 === 0) {
         const level = await driver.readLevel();
         if (level !== null) result.level_readings.push(level);
       }
 
       // Active piece detection + AI placement
       if (snap.activePieceCells && snap.activePieceCells.length === 4) {
         const pieceType = snap.activePieceType || "unknown";
         session.pieceTypes.add(pieceType);
 
         // Rotation probe for all_pieces_rotate: for the first time we see
         // this piece type in competitive play, press rotate 4 times and
         // record distinct normalized shapes. A correctly working game
         // returns to baseline after 4 presses so the placement logic below
         // continues from the same rotation state. Skip O and unknown.
         if (
           pieceType !== "unknown" &&
           pieceType !== "O" &&
           !session.rotationShapesByPiece.has(pieceType)
         ) {
           const shapes = new Set<string>();
           shapes.add(normalizedShapeKey(snap.activePieceCells));
           for (let r = 0; r < 4; r++) {
             await driver.pressKey("rotate");
             await driver.wait(80);
             const rotSnap = await driver.readGrid(settledGrid);
             if (rotSnap.activePieceCells && rotSnap.activePieceCells.length > 0) {
               shapes.add(normalizedShapeKey(rotSnap.activePieceCells));
             }
           }
           session.rotationShapesByPiece.set(pieceType, shapes);
         }
 
         // Soft drop test
         if (!softDropTestDone && result.pieces_placed > 3 && result.pieces_placed % 5 === 0) {
           const snapBeforeDown = await driver.readGrid(settledGrid);
           await driver.pressKey("down");
           await driver.wait(60);
           const snapAfterDown = await driver.readGrid(settledGrid);
 
           if (snapBeforeDown.activePieceCells && snapAfterDown.activePieceCells) {
             const avgRowBefore = snapBeforeDown.activePieceCells.reduce((s, [r]) => s + r, 0) / snapBeforeDown.activePieceCells.length;
             const avgRowAfter = snapAfterDown.activePieceCells.reduce((s, [r]) => s + r, 0) / snapAfterDown.activePieceCells.length;
             const rowDelta = avgRowAfter - avgRowBefore;
             softDropDistinct = rowDelta >= 0.5 && rowDelta <= 3;
             softDropTestDone = true;
           }
         }
 
         // Rendering trail sampling
         if (result.pieces_placed > 0 && result.pieces_placed % 10 === 0 && result.pieces_placed !== trailCheckPieceMark) {
           trailCheckPieceMark = result.pieces_placed;
           const sampleSnap = await driver.readGrid();
           if (sampleSnap.grid) filledCellSamples.push(sampleSnap.filledCount);
         }
 
         // Compute clean locked board (without active piece) for AI eval
         // and as the diff base for the next iteration.
         const boardBeforePlacement = stripActivePiece(snap.grid, snap.activePieceCells);
         const placement = findBestPlacement(boardBeforePlacement, pieceType as PieceType);
 
         if (placement) {
           await executePlacement(driver, placement, snap.activePieceCells);
         } else {
           await driver.pressKey("drop");
         }
 
         result.pieces_placed++;
 
         // Wait for lock + new piece spawn, then re-read and strip the new
         // active piece so settledGrid reflects only the locked board.
         await driver.wait(350);
 
         const afterSnap = await driver.readGrid(boardBeforePlacement);
         if (afterSnap.grid) {
           // Line-clear detection: compare filled count of locked boards
           // before and after placement (before + 4 = expected, minus clears).
           const filledBefore = countFilled(boardBeforePlacement) + 4;
           const filledNow = countFilled(afterSnap.grid) -
             (afterSnap.activePieceCells ? afterSnap.activePieceCells.length : 0);
 
           if (filledNow < filledBefore - 5 && filledBefore > 10) {
             const clearedCount = Math.round((filledBefore - filledNow) / GRID_COLS);
             if (clearedCount > 0 && clearedCount <= 4) {
               result.total_lines_cleared += clearedCount;
               consecutiveClears++;
               if (consecutiveClears > maxCombo) maxCombo = consecutiveClears;
 
               switch (clearedCount) {
                 case 1: result.single_clears++; break;
                 case 2: result.double_clears++; break;
                 case 3: result.triple_clears++; break;
                 case 4: result.tetris_clears++; break;
               }
             }
           } else if (filledNow >= filledBefore - 1) {
             consecutiveClears = 0;
           }
 
           if (afterSnap.activePieceCells && afterSnap.activePieceCells.length >= 3 && afterSnap.activePieceCells.length <= 5) {
             settledGrid = stripActivePiece(afterSnap.grid, afterSnap.activePieceCells);
           } else {
             settledGrid = afterSnap.grid;
           }
         }
       } else {
         // No active piece visible -- wait briefly for spawn.
         await driver.wait(60);
       }
     } catch {
       await driver.wait(60);
     }
   }
 
   result.duration_seconds = Math.round((Date.now() - start) / 1000);
   result.max_combo = maxCombo;
 
   // Read final score
   const finalScore = await driver.readScore();
   if (finalScore !== null) {
     result.score_final = finalScore;
     result.score_readings.push(finalScore);
   }
 
   // Read final level
   const finalLevel = await driver.readLevel();
   if (finalLevel !== null) {
     result.level_final = finalLevel;
     result.level_readings.push(finalLevel);
   }
 
   // Measure final drop speed
   const finalDropInterval = await driver.measureDropInterval();
   if (initialDropInterval > 0 && finalDropInterval > 0 && finalDropInterval < initialDropInterval * 0.8) {
     result.speed_increased = true;
   }
 
   // Game over check
   const gameOverText = await driver.detectGameOverText();
   if (gameOverText) {
     result.game_over_reached = true;
     result.game_over_text_found = gameOverText;
   }
 
   result.restart_available = await driver.detectRestartOption();
   result.next_piece_visible = await driver.detectNextPiecePreview();
 
   // Bug detection
   if (result.score_increases.length > 3) {
     const singleDeltas = result.score_increases.filter((d) => d > 0 && d <= 200);
     const multiDeltas = result.score_increases.filter((d) => d > 200);
     if (singleDeltas.length > 0 && multiDeltas.length === 0 &&
         (result.double_clears + result.triple_clears + result.tetris_clears) > 0) {
       result.bugs_detected.push("score_does_not_scale_with_simultaneous_clears");
     }
   }
 
   if (result.level_readings.length > 1) {
     const uniqueLevels = [...new Set(result.level_readings)];
     if (uniqueLevels.length === 1 && result.total_lines_cleared >= 10) {
       result.bugs_detected.push("level_does_not_increase");
     }
   }
 
   if (result.level_readings.length > 1) {
     const uniqueLevels = [...new Set(result.level_readings)];
     if (uniqueLevels.length > 1 && !result.speed_increased) {
       result.bugs_detected.push("speed_does_not_increase");
     }
   }
 
   // Rendering trail detection
   if (result.pieces_placed >= 10 && filledCellSamples.length >= 2) {
     const maxFilled = Math.max(...filledCellSamples);
     if (maxFilled > result.pieces_placed * 8) {
       result.rendering_trail_detected = true;
       result.bugs_detected.push("rendering_trail");
     } else {
       const onlyIncreasing = filledCellSamples.every((v, i) =>
         i === 0 || v >= filledCellSamples[i - 1]
       );
       if (onlyIncreasing && filledCellSamples.length >= 3 && maxFilled > result.pieces_placed * 6) {
         result.rendering_trail_detected = true;
         result.bugs_detected.push("rendering_trail");
       } else {
         result.rendering_trail_detected = false;
       }
     }
   }
 
   result._ccwResult = ccwResult;
   result._ccwTestDone = ccwTestDone;
   result._softDropDistinct = softDropDistinct;
   result._softDropTestDone = softDropTestDone;
 
   return result;
 }
 
 // ---------------------------------------------------------------------------
 // Play helpers (use driver, never Playwright directly)
 // ---------------------------------------------------------------------------
 
 async function playGame(
   driver: TetrisDriver,
   options: {
     maxPieces?: number;
     maxDurationMs?: number;
     rotationTrack?: Map<string, Set<string>>;
   }
 ): Promise<{ piecesPlaced: number; linesCleared: number; errors: number; gridReads: number; gridReadFails: number; scoreValues: number[]; scoreBeforeClear?: number; scoreAfterClear?: number }> {
   const maxPieces = options.maxPieces ?? 100;
   const maxDuration = options.maxDurationMs ?? 30000;
   const rotationTrack = options.rotationTrack;
   const start = Date.now();
   let piecesPlaced = 0;
   let linesCleared = 0;
   let errors = 0;
   let gridReads = 0;
   let gridReadFails = 0;
   let consecutiveReadFails = 0;
   const scoreValues: number[] = [];
   let scorePollCounter = 0;
   let scoreBeforeClear: number | undefined;
   let scoreAfterClear: number | undefined;
   /** The most recent score reading, kept up to date so we can snapshot it
    *  immediately before a line clear is detected. */
   let lastScoreReading: number | null = null;
 
   // settledGrid = the locked board WITHOUT any active piece. We recompute
   // it after each placement by reading the fresh grid and stripping out the
   // new active piece (the one that just spawned after our drop).
   let settledGrid: Grid | null = null;
 
   while (piecesPlaced < maxPieces && Date.now() - start < maxDuration) {
     try {
       const snap = await driver.readGrid(settledGrid);
 
       if (!snap.grid) {
         gridReadFails++;
         consecutiveReadFails++;
         if (consecutiveReadFails > 10) {
           await playRandomForDuration(driver, Math.min(5000, maxDuration - (Date.now() - start)));
           piecesPlaced += 3;
           break;
         }
         await driver.wait(60);
         continue;
       }
 
       gridReads++;
       consecutiveReadFails = 0;
 
       // Score tracking
       scorePollCounter++;
       if (scorePollCounter % 5 === 0) {
         const score = await driver.readScore();
         if (score !== null) {
           scoreValues.push(score);
           lastScoreReading = score;
         }
       }
 
       if (snap.activePieceCells && snap.activePieceCells.length === 4) {
         const pieceType = snap.activePieceType || "unknown";
 
         // Rotation probe: for the first time we see this piece type, press
         // rotate 4 times and record each resulting shape. A correctly
         // working game cycles through the piece's rotation states and
         // returns to baseline after 4 presses (so executePlacement below
         // can proceed normally from the same rotation state). A broken
         // game where rotation only fires once (or stalls) will record
         // fewer distinct shapes -- which is exactly what the
         // all_pieces_rotate test is looking for.
         if (
           rotationTrack &&
           pieceType !== "unknown" &&
           pieceType !== "O" &&
           !rotationTrack.has(pieceType)
         ) {
           const shapes = new Set<string>();
           shapes.add(normalizedShapeKey(snap.activePieceCells));
           for (let r = 0; r < 4; r++) {
             await driver.pressKey("rotate");
             await driver.wait(80);
             const rotSnap = await driver.readGrid(settledGrid);
             if (rotSnap.activePieceCells && rotSnap.activePieceCells.length > 0) {
               shapes.add(normalizedShapeKey(rotSnap.activePieceCells));
             }
           }
           rotationTrack.set(pieceType, shapes);
         }
 
         // Re-read snap after rotation probe so activePieceCells reflects
         // the current position (auto-drop may have shifted the piece).
         let workingSnap = snap;
         if (rotationTrack && pieceType !== "unknown" && pieceType !== "O") {
           const freshSnap = await driver.readGrid(settledGrid);
           if (freshSnap.grid && freshSnap.activePieceCells && freshSnap.activePieceCells.length === 4) {
             workingSnap = freshSnap;
           }
         }
 
         // Save the locked board as-of right now (no active piece). This is
         // what findBestPlacement evaluates against, and what we use as the
         // diff base for the NEXT iteration's active-piece detection.
         const boardBeforePlacement = stripActivePiece(workingSnap.grid!, workingSnap.activePieceCells!);
         const placement = findBestPlacement(boardBeforePlacement, pieceType as PieceType);
 
         // Track whether this placement will produce a line clear so we can
         // snapshot the score before and after.
         const expectsClear = placement ? placement.linesCleared > 0 : false;
         // Snapshot score just before executing the drop (for score_increases_on_clear)
         if (expectsClear && scoreBeforeClear === undefined) {
           const preClearScore = await driver.readScore();
           if (preClearScore !== null) {
             scoreBeforeClear = preClearScore;
             lastScoreReading = preClearScore;
           } else if (lastScoreReading !== null) {
             scoreBeforeClear = lastScoreReading;
           }
         }
 
         if (placement) {
           await executePlacement(driver, placement, workingSnap.activePieceCells!);
           linesCleared += placement.linesCleared;
           piecesPlaced++;
         } else {
           await driver.pressKey("drop");
           piecesPlaced++;
         }
 
         // Wait long enough for lock + line clears + new piece spawn. Then
         // read the fresh grid. The "active piece" in this afterSnap is the
         // NEW piece that just spawned at the top -- we must detect it using
         // boardBeforePlacement (NOT the current snap which has our just-
         // dropped piece baked in) and strip it to get a clean settledGrid
         // for the next iteration.
         await driver.wait(350);
 
         const afterSnap = await driver.readGrid(boardBeforePlacement);
         if (afterSnap.grid) {
           // Line-clear detection by filled-count delta.
           const filledBefore = countFilled(boardBeforePlacement) + 4;
           const filledAfter = countFilled(afterSnap.grid);
           let clearsThisPlacement = 0;
           if (filledAfter < filledBefore) {
             const possibleClears = Math.round((filledBefore - filledAfter) / GRID_COLS);
             if (possibleClears > 0 && possibleClears <= 4) {
               linesCleared += possibleClears;
               clearsThisPlacement = possibleClears;
             }
           }
 
           // If a line clear happened (AI-predicted or grid-verified) and we
           // haven't captured the post-clear score yet, read it now.
           if ((expectsClear || clearsThisPlacement > 0) && scoreAfterClear === undefined) {
             // If we didn't snapshot the before-clear score yet (grid-detected
             // clear that the AI didn't predict), capture it retroactively from
             // the last known reading.
             if (scoreBeforeClear === undefined && lastScoreReading !== null) {
               scoreBeforeClear = lastScoreReading;
             }
             const postClearScore = await driver.readScore();
             if (postClearScore !== null) {
               scoreAfterClear = postClearScore;
               scoreValues.push(postClearScore);
               lastScoreReading = postClearScore;
             }
           }
 
           if (afterSnap.activePieceCells && afterSnap.activePieceCells.length >= 3 && afterSnap.activePieceCells.length <= 5) {
             settledGrid = stripActivePiece(afterSnap.grid, afterSnap.activePieceCells);
           } else {
             // No new piece detected yet (maybe still locking/clearing).
             // Fall back to using the raw grid; next iteration will re-diff.
             settledGrid = afterSnap.grid;
           }
         }
       } else {
         // No active piece visible yet -- wait briefly for spawn.
         await driver.wait(60);
       }
     } catch {
       errors++;
       await playRandomMove(driver);
       piecesPlaced++;
       await driver.wait(60);
     }
   }
 
   return { piecesPlaced, linesCleared, errors, gridReads, gridReadFails, scoreValues, scoreBeforeClear, scoreAfterClear };
 }
 
 
 async function executePlacement(
   driver: TetrisDriver,
   placement: Placement,
   _activeCells: [number, number][]
 ): Promise<void> {
   // Slam-left strategy (LeeYiyuan approach): don't track live position.
   // 1. Rotate N times. 2. Left ~10 to slam against wall. 3. Right to target.
   // 4. Hard drop. This is position-independent so rotation-column shifts
   // don't matter.
   for (let i = 0; i < placement.rotations; i++) {
     await driver.pressKey("rotate");
     await driver.wait(30);
   }
 
   for (let i = 0; i < GRID_COLS; i++) {
     await driver.pressKey("left");
     await driver.wait(15);
   }
 
   for (let i = 0; i < placement.column; i++) {
     await driver.pressKey("right");
     await driver.wait(15);
   }
 
   await driver.pressKey("drop");
   await driver.wait(60);
 }
 
 async function playRandomMove(driver: TetrisDriver): Promise<void> {
   const actions = ["left", "right", "rotate", "down"] as const;
   const randomMoves = Math.floor(Math.random() * 4) + 1;
   for (let i = 0; i < randomMoves; i++) {
     const action = actions[Math.floor(Math.random() * actions.length)];
     await driver.pressKey(action);
     await driver.wait(50);
   }
   await driver.pressKey("drop");
   await driver.wait(100);
 }
 
 async function playRandomForDuration(driver: TetrisDriver, durationMs: number): Promise<void> {
   const start = Date.now();
   const actions = ["left", "right", "rotate", "down", "drop"] as const;
   while (Date.now() - start < durationMs) {
     const action = actions[Math.floor(Math.random() * actions.length)];
     await driver.pressKey(action);
     await driver.wait(100);
   }
 }
 
 async function tryFillRow(driver: TetrisDriver, maxAttempts: number): Promise<boolean> {
   const columns = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
   let attempts = 0;
 
   for (const targetCol of columns) {
     if (attempts >= maxAttempts) break;
 
     for (let i = 0; i < 6; i++) {
       await driver.pressKey("left");
       await driver.wait(30);
     }
 
     for (let i = 0; i < targetCol; i++) {
       await driver.pressKey("right");
       await driver.wait(30);
     }
 
     await driver.pressKey("drop");
     await driver.wait(200);
     attempts++;
   }
 
   const snap = await driver.readGrid();
   if (!snap.grid) return false;
 
   const bottomFilled = snap.filledInBottom(1);
   return bottomFilled < 8;
 }
 
 // ---------------------------------------------------------------------------
 // Test derivation (pure data, no driver needed)
 // ---------------------------------------------------------------------------
 
 function deriveTestResults(
   session: GameSession,
   cal: DriverCalibration,
   loadResult: LoadResult,
   consoleErrors: string[],
   gameplay: GameplayStats,
   phaseState: PhaseState,
   competitivePlay: CompetitivePlayResult | null
 ): TestResult[] {
   const results: TestResult[] = [];
   const gridReliable = session.gridReadSuccess > 0 &&
     session.gridReadSuccess / (session.gridReadSuccess + session.gridReadFail) > 0.5;
 
   const skipResult = (name: string, reason: string): TestResult => ({
     name, pass: false, detail: `skipped: ${reason}`,
   });
 
   // 1. game_loads: page loaded with non-trivial content and at least one
   // game-shaped landmark. Console errors are captured in the report for
   // informational purposes but do NOT gate this test.
   {
     const loaded = loadResult.loaded;
     const landmarks = session.gameLoadLandmarks;
     const hasLandmark = landmarks && (
       landmarks.hasCanvas ||
       landmarks.hasDomGrid ||
       landmarks.hasTetrisRatioElement ||
       landmarks.hasManyCellsContainer
     );
     const bodyHasContent = landmarks?.bodyHasContent ?? false;
     const pass = loaded && bodyHasContent && !!hasLandmark;
     let detail: string;
     if (!loaded) detail = loadResult.detail || "page failed to load";
     else if (!bodyHasContent) detail = "blank page (body has no content)";
     else if (!hasLandmark) detail = "no game landmarks found (no canvas, grid, or game-shaped element)";
     else detail = `loaded with landmarks: ${landmarks!.landmarksFound.join(", ")}`;
     results.push({ name: "game_loads", pass, detail });
   }
 
   // 2. game_starts
   {
     let startDetail: string;
     if (session.started) {
       startDetail = `started via ${session.startMechanism}`;
       if (cal.startButton) {
         const btn = cal.startButton;
         startDetail += ` (${btn.selector}, "${btn.text}"${btn.disappeared ? ", disappeared after click" : ""})`;
       }
     } else {
       startDetail = "could not start game with any mechanism";
     }
     results.push({ name: "game_starts", pass: session.started, detail: startDetail });
   }
 
   // 3. auto_drop
   if (!phaseState.gameStarted) {
     results.push(skipResult("auto_drop", "game did not start"));
   } else {
     const autoDropEvents = session.events.filter(
       (e) => e.type === "piece_moved" && e.direction === "down" && e.frame <= 2
     );
     if (autoDropEvents.length > 0) {
       results.push({ name: "auto_drop", pass: true, detail: "grid state changed after 5s with no input (grid-verified)" });
     } else if (!gridReliable) {
       results.push({ name: "auto_drop", pass: false, detail: "grid reader unreliable, cannot verify auto-drop" });
     } else {
       results.push({ name: "auto_drop", pass: false, detail: "piece did not move down in 5 seconds (grid-verified)" });
     }
   }
 
   // 4-6. movement tests
   for (const dir of ["left", "right", "down"] as const) {
     if (!phaseState.gameStarted) {
       results.push(skipResult(`move_${dir}`, "game did not start"));
       continue;
     }
     // Not applicable: if control discovery determined that this game has no
     // soft_drop (no key produced a single-row downward move), then move_down
     // is a feature the game genuinely lacks rather than something that's
     // broken. Report as skipped with a clear reason so it does not drag the
     // score down.
     if (dir === "down" && cal.controlMap && cal.controlMap.soft_drop.confidence === "not_found") {
       results.push(skipResult("move_down", "no soft_drop key (game has only hard_drop)"));
       continue;
     }
     const moveEvents = session.events.filter((e) => e.type === "piece_moved" && e.direction === dir);
     if (moveEvents.length > 0) {
       results.push({ name: `move_${dir}`, pass: true, detail: "grid state changed after key press (grid-verified)" });
     } else if (!gridReliable) {
       results.push({ name: `move_${dir}`, pass: false, detail: "grid reader unreliable, cannot verify movement" });
     } else {
       results.push({ name: `move_${dir}`, pass: false, detail: "no grid change detected after key press" });
     }
   }
 
   // 7. rotate
   //
   // A correctly working game should cycle a non-O piece through at least 2
   // rotation states (I/S/Z have 2 states; J/L/T have 4). We press rotate 4
   // times and count distinct normalized shapes; a broken game where
   // rotation only fires once will only produce 2 shapes total (initial +
   // first rotation), which is NOT enough. We require 3 distinct shapes
   // overall (initial + at least 2 other states).
   //
   // Fallback: if the Phase 3 probe landed on an O piece (only 1 shape) or
   // the grid reader couldn't identify the active piece cells, we also
   // consult the gameplay-phase per-piece tracking -- any piece type with
   // 3+ distinct shapes observed there proves the game rotates correctly.
   const gameplayRotationShapesMax = [...session.rotationShapesByPiece.values()]
     .reduce((max, set) => Math.max(max, set.size), 0);
   const maxShapesSeen = Math.max(session.distinctRotationShapes, gameplayRotationShapesMax);
   if (!phaseState.gameStarted) {
     results.push(skipResult("rotate", "game did not start"));
   } else if (maxShapesSeen >= 3) {
     results.push({
       name: "rotate",
       pass: true,
       detail: `piece cycled through ${maxShapesSeen} distinct shapes after 4 rotate presses (grid-verified)`,
     });
   } else if (!gridReliable) {
     results.push({ name: "rotate", pass: false, detail: "grid reader unreliable, cannot verify rotation" });
   } else if (maxShapesSeen === 2) {
     results.push({
       name: "rotate",
       pass: false,
       detail: "piece only reached 1 rotation state then stalled (expected at least 2 distinct non-baseline shapes)",
     });
   } else {
     results.push({
       name: "rotate",
       pass: false,
       detail: `no shape change detected after rotate key (${maxShapesSeen} distinct shape(s))`,
     });
   }
 
   // 8. hard_drop
   if (!phaseState.gameStarted) {
     results.push(skipResult("hard_drop", "game did not start"));
   } else if (session.hardDropsObserved > 0) {
     results.push({ name: "hard_drop", pass: true, detail: "piece immediately dropped to bottom (grid-verified)" });
   } else if (!gridReliable) {
     results.push({ name: "hard_drop", pass: false, detail: "grid reader unreliable, cannot verify hard drop" });
   } else {
     results.push({ name: "hard_drop", pass: false, detail: "no grid change with bottom cells detected after hard drop key" });
   }
 
   // 9. all_pieces_rotate
   //
   // During gameplay we probe each new piece type by pressing rotate 4
   // times and recording distinct normalized shapes. A correctly working
   // game cycles J/L/T through 4 rotation states (we expect to observe 3+
   // distinct shapes even accounting for timing jitter).
   //
   // Pass rule: at least 2 multi-state piece types (J/L/T) reached 3+
   // distinct shapes (baseline + at least 2 other states). This excludes
   // broken games that rotate exactly once before getting stuck (2 shapes
   // total). We require multi-state pieces because I/S/Z in classic-style
   // games only have 2 rotation states, so we can't distinguish "broken
   // rotation stuck at state 1" from "working 2-state S/Z".
   //
   // Skip if fewer than 2 J/L/T types were ever seen in the gameplay
   // phase -- not enough data to make the claim.
   if (!phaseState.gameStarted) {
     results.push(skipResult("all_pieces_rotate", "game did not start"));
   } else {
     // Union of piece types visible via session.pieceTypes AND the tracking
     // map keys, since the tracking map is populated in gameplay phases that
     // don't add to pieceTypes.
     const allSeenTypes = new Set<string>([
       ...session.pieceTypes,
       ...session.rotationShapesByPiece.keys(),
     ]);
     const multiStateTypesSeen = [...allSeenTypes].filter((t) =>
       ["J", "L", "T"].includes(t)
     );
     const trackedTypes = [...session.rotationShapesByPiece.entries()];
     const multiStateRotated = trackedTypes.filter(
       ([t, shapes]) => ["J", "L", "T"].includes(t) && shapes.size >= 3
     );
     if (multiStateTypesSeen.length < 2) {
       results.push(
         skipResult(
           "all_pieces_rotate",
           `not enough piece types to verify (saw ${multiStateTypesSeen.length} of J/L/T, need 2)`
         )
       );
     } else if (multiStateRotated.length >= 2) {
       const detail = multiStateRotated
         .map(([t, s]) => `${t}:${s.size}`)
         .join(" ");
       results.push({
         name: "all_pieces_rotate",
         pass: true,
         detail: `${multiStateRotated.length} J/L/T piece type(s) rotated to 3+ distinct shapes [${detail}]`,
       });
     } else if (!gridReliable) {
       results.push({
         name: "all_pieces_rotate",
         pass: false,
         detail: "grid reader unreliable, cannot verify per-piece rotation",
       });
     } else {
       const detail = trackedTypes
         .filter(([t]) => ["J", "L", "T"].includes(t))
         .map(([t, s]) => `${t}:${s.size}`)
         .join(" ");
       results.push({
         name: "all_pieces_rotate",
         pass: false,
         detail: `only ${multiStateRotated.length} of ${multiStateTypesSeen.length} J/L/T rotated to 3+ distinct shapes (need 2) [${detail}]`,
       });
     }
   }
 
   // 10. piece_locks
   if (!phaseState.gameStarted) {
     results.push(skipResult("piece_locks", "game did not start"));
   } else if (!gridReliable) {
     results.push({ name: "piece_locks", pass: false, detail: "grid reader unreliable, cannot verify piece locking" });
   } else {
     const lockEvents = session.events.filter((e) => e.type === "piece_locked");
     if (lockEvents.length > 0) {
       results.push({ name: "piece_locks", pass: true, detail: `filled cells persist at bottom (grid-verified, ${lockEvents.length} lock event(s))` });
     } else if (session.piecesLocked > 0 && session.piecesSpawned > 0) {
       results.push({ name: "piece_locks", pass: true, detail: `${session.piecesLocked} piece(s) locked during play` });
     } else if (session.piecesLocked > 0 && session.piecesSpawned === 0) {
       results.push({ name: "piece_locks", pass: false, detail: `${session.piecesLocked} lock event(s) but 0 spawns detected - likely false positive from UI misread` });
     } else {
       results.push({ name: "piece_locks", pass: false, detail: "could not verify piece locking via grid reader" });
     }
   }
 
   // 11. new_piece_spawns
   if (!phaseState.gameStarted) {
     results.push(skipResult("new_piece_spawns", "game did not start"));
   } else if (session.piecesSpawned > 0) {
     results.push({ name: "new_piece_spawns", pass: true, detail: `${session.piecesSpawned} new piece(s) detected at top of grid` });
   } else {
     results.push({ name: "new_piece_spawns", pass: false, detail: "could not detect new piece spawning at top via grid reader" });
   }
 
   // 12. multiple_pieces
   if (!phaseState.mechanicsWork) {
     results.push(skipResult("multiple_pieces", "mechanics phase failed"));
   } else if (session.piecesLocked >= 3 && session.piecesSpawned > 0) {
     results.push({ name: "multiple_pieces", pass: true, detail: `${session.piecesLocked} pieces placed during play session` });
   } else {
     results.push({ name: "multiple_pieces", pass: false, detail: `only ${session.piecesLocked} piece(s) detected, need at least 3` });
   }
 
   // 13. line_clear
   if (!phaseState.mechanicsWork) {
     results.push(skipResult("line_clear", "mechanics phase failed"));
   } else if (session.linesCleared > 0) {
     results.push({ name: "line_clear", pass: true, detail: `${session.linesCleared} line(s) cleared (grid-verified)` });
   } else {
     results.push({ name: "line_clear", pass: false, detail: "could not trigger or detect a line clear via grid reader" });
   }
 
   // 14a. score_increases_on_clear
   if (!phaseState.mechanicsWork) {
     results.push(skipResult("score_increases_on_clear", "mechanics phase failed"));
   } else if (session.linesCleared > 0) {
     if (session.scoreBeforeClear !== undefined && session.scoreAfterClear !== undefined) {
       const scoreIncreased = session.scoreAfterClear > session.scoreBeforeClear;
       results.push({
         name: "score_increases_on_clear",
         pass: scoreIncreased,
         detail: scoreIncreased
           ? `score went from ${session.scoreBeforeClear} to ${session.scoreAfterClear} after line clear`
           : `score stayed at ${session.scoreBeforeClear} after clearing ${session.linesCleared} line(s)`,
       });
     } else if (!cal.scoreElementSelector) {
       results.push(skipResult("score_increases_on_clear", "no score element found, cannot verify scoring on clear"));
     } else {
       results.push(skipResult("score_increases_on_clear", "lines cleared but could not read score before/after"));
     }
   } else {
     results.push(skipResult("score_increases_on_clear", "no lines cleared, cannot verify scoring"));
   }
 
   // 14b. score_element_visible
   {
     const hasScoreElement = !!cal.scoreElementSelector;
     results.push({
       name: "score_element_visible",
       pass: hasScoreElement,
       detail: hasScoreElement
         ? `score display found (${cal.scoreElementSelector})`
         : "no score display detected",
     });
   }
 
   // 15. game_over
   if (!phaseState.piecesWork) {
     results.push(skipResult("game_over", "piece lifecycle failed"));
   } else {
     results.push({
       name: "game_over",
       pass: session.gameOverDetected,
       detail: session.gameOverDetected
         ? "game stopped after stacking to top (grid-verified)"
         : "could not trigger or detect game over via grid reader",
     });
   }
 
   // 16. playable_30s
   if (!phaseState.gameplayWorks) {
     results.push(skipResult("playable_30s", "gameplay phase failed"));
   } else {
     // Only count errors during play, not pre-start errors
     const playErrors = gameplay.errors_during_play;
     const crashed = playErrors > 3;
     if (!crashed && gameplay.play_duration_seconds >= 10) {
       results.push({ name: "playable_30s", pass: true, detail: `played for ${gameplay.play_duration_seconds}s, placed ${gameplay.pieces_placed} pieces, no crashes` });
     } else if (crashed) {
       results.push({ name: "playable_30s", pass: false, detail: `${playErrors} play errors` });
     } else {
       results.push({ name: "playable_30s", pass: false, detail: `only played for ${gameplay.play_duration_seconds}s` });
     }
   }
 
   // 17-25: Competitive play tests
 
   // 17. multi_line_clear
   if (!phaseState.gameplayWorks || !competitivePlay) {
     results.push(skipResult("multi_line_clear", "competitive play phase did not run"));
   } else if (competitivePlay.double_clears + competitivePlay.triple_clears + competitivePlay.tetris_clears > 0) {
     const hasMultiLineBug = competitivePlay.bugs_detected.includes("multi_line_clear_only_removes_one_row");
     results.push({
       name: "multi_line_clear",
       pass: !hasMultiLineBug,
       detail: hasMultiLineBug
         ? "multi-line clear detected but only 1 row was removed"
         : `multi-line clears work: ${competitivePlay.double_clears}x double, ${competitivePlay.triple_clears}x triple, ${competitivePlay.tetris_clears}x tetris`,
     });
   } else {
     results.push(skipResult("multi_line_clear", "no multi-line clear opportunity occurred during play"));
   }
 
   // 18. score_scaling
   if (!phaseState.gameplayWorks || !competitivePlay) {
     results.push(skipResult("score_scaling", "competitive play phase did not run"));
   } else if (competitivePlay.double_clears + competitivePlay.triple_clears + competitivePlay.tetris_clears > 0) {
     const hasBug = competitivePlay.bugs_detected.includes("score_does_not_scale_with_simultaneous_clears");
     results.push({
       name: "score_scaling",
       pass: !hasBug,
       detail: hasBug
         ? "multi-line clears give same points as single clears"
         : `score scales with clear type (${competitivePlay.score_increases.length} score changes observed)`,
     });
   } else {
     results.push(skipResult("score_scaling", "no multi-line clear occurred to test scaling"));
   }
 
   // 19. level_progression
   if (!phaseState.gameplayWorks || !competitivePlay) {
     results.push(skipResult("level_progression", "competitive play phase did not run"));
   } else if (competitivePlay.total_lines_cleared < 10) {
     results.push(skipResult("level_progression", `only ${competitivePlay.total_lines_cleared} lines cleared (need 10+)`));
   } else {
     const hasBug = competitivePlay.bugs_detected.includes("level_does_not_increase");
     if (competitivePlay.level_readings.length < 2) {
       results.push(skipResult("level_progression", "could not read level display"));
     } else {
       results.push({
         name: "level_progression",
         pass: !hasBug,
         detail: hasBug
           ? `level stayed at ${competitivePlay.level_readings[0]} despite ${competitivePlay.total_lines_cleared} lines cleared`
           : `level progressed from ${competitivePlay.level_readings[0]} to ${competitivePlay.level_final}`,
       });
     }
   }
 
   // 20. speed_progression
   if (!phaseState.gameplayWorks || !competitivePlay) {
     results.push(skipResult("speed_progression", "competitive play phase did not run"));
   } else if (competitivePlay.level_readings.length < 2 || new Set(competitivePlay.level_readings).size <= 1) {
     results.push(skipResult("speed_progression", "level did not increase, cannot test speed change"));
   } else {
     const hasBug = competitivePlay.bugs_detected.includes("speed_does_not_increase");
     results.push({
       name: "speed_progression",
       pass: !hasBug && competitivePlay.speed_increased,
       detail: competitivePlay.speed_increased
         ? "drop speed increased with level"
         : "drop speed did not change after level increased",
     });
   }
 
   // 21. next_piece_preview
   if (!phaseState.gameplayWorks || !competitivePlay) {
     results.push(skipResult("next_piece_preview", "competitive play phase did not run"));
   } else {
     results.push({
       name: "next_piece_preview",
       pass: competitivePlay.next_piece_visible,
       detail: competitivePlay.next_piece_visible ? "next piece preview display found" : "no next piece preview found",
     });
   }
 
   // 22. game_over_display
   // Verifies the game SHOWS a game-over UI after the internal game over
   // state is reached. Two structural signals (no language matching):
   //   1. A modal or overlay element appeared (position fixed/absolute,
   //      covering >15% viewport, visible). Captured in Phase 6 after
   //      game over was triggered via grid stacking.
   //   2. A clickable element (restart) is visible inside that overlay.
   // The test passes if EITHER a modal is present OR a restart option is
   // visible, because different games show different UI styles.
   if (!phaseState.gameplayWorks || !competitivePlay) {
     results.push(skipResult("game_over_display", "competitive play phase did not run"));
   } else if (!competitivePlay.game_over_reached && !session.gameOverDetected) {
     results.push(skipResult("game_over_display", "game over not reached during play"));
   } else {
     const usePhase6 = session.gameOverDetected;
     const modalFound = usePhase6
       ? (session.gameOverText !== null && session.gameOverText !== undefined)
       : (competitivePlay.game_over_text_found !== null);
     const hasRestart = usePhase6
       ? session.gameOverRestartAvailable === true
       : competitivePlay.restart_available;
     const source = usePhase6 ? "phase6" : "phase8";
     const pass = modalFound || hasRestart;
     const details: string[] = [];
     if (modalFound) details.push("overlay detected");
     if (hasRestart) details.push("restart clickable present");
     if (!pass) details.push("no overlay or restart UI found");
     results.push({
       name: "game_over_display",
       pass,
       detail: `${details.join(", ")} (${source})`,
     });
   }
 
   // 23. counter_clockwise_rotation
   if (!phaseState.gameplayWorks || !competitivePlay) {
     results.push(skipResult("counter_clockwise_rotation", "competitive play phase did not run"));
   } else {
     const ccwTestDone = (competitivePlay as any)._ccwTestDone === true;
     const ccwResult = (competitivePlay as any)._ccwResult;
     if (!ccwTestDone) {
       results.push(skipResult("counter_clockwise_rotation", "could not test rotation direction"));
     } else {
       results.push({
         name: "counter_clockwise_rotation",
         pass: ccwResult === true,
         detail: ccwResult === true
           ? "Z key rotates opposite direction from Up arrow"
           : ccwResult === false
           ? "Z key does same as Up arrow or does not rotate"
           : "could not determine rotation direction",
       });
     }
   }
 
   // 24. soft_drop_distinct
   if (!phaseState.gameplayWorks || !competitivePlay) {
     results.push(skipResult("soft_drop_distinct", "competitive play phase did not run"));
   } else if (cal.controlMap && cal.controlMap.soft_drop.confidence === "not_found") {
     // Game has no soft drop at all -- not applicable.
     results.push(skipResult("soft_drop_distinct", "no soft_drop key (game has only hard_drop)"));
   } else {
     const softDropTestDone = (competitivePlay as any)._softDropTestDone === true;
     const softDropDistinct = (competitivePlay as any)._softDropDistinct;
     if (!softDropTestDone) {
       results.push(skipResult("soft_drop_distinct", "could not test soft drop behavior"));
     } else {
       results.push({
         name: "soft_drop_distinct",
         pass: softDropDistinct === true,
         detail: softDropDistinct === true
           ? "Down arrow moves piece 1 row (distinct from hard drop)"
           : "Down arrow acts like hard drop (drops to bottom)",
       });
     }
   }
 
   // 25. rendering_clean
   if (!phaseState.gameplayWorks || !competitivePlay) {
     results.push(skipResult("rendering_clean", "competitive play phase did not run"));
   } else if (competitivePlay.rendering_trail_detected === undefined) {
     results.push(skipResult("rendering_clean", "not enough data to assess rendering trails"));
   } else {
     results.push({
       name: "rendering_clean",
       pass: !competitivePlay.rendering_trail_detected,
       detail: competitivePlay.rendering_trail_detected
         ? "rendering trail bug: falling piece leaves old cells colored after moving"
         : "piece movement clears old cells correctly",
     });
   }
 
   return results;
 }
 
 // ---------------------------------------------------------------------------
 // Start-mechanism verification bridge
 // ---------------------------------------------------------------------------
 
 /**
  * The bot's gameplay-grounded check for "did the game really start?"
  *
  * This is the feedback channel the driver leans on. The driver can only see
  * pixel and DOM deltas, so it can be fooled by Pause buttons, overlays, or
  * spurious animations. The bot reads the grid, presses real gameplay keys,
  * and watches for tetris-like behavior.
  *
  * Returns true only when the evidence clearly points to a started game:
  *   - grid detected and populated in a sane range (pieces, not chrome)
  *   - ArrowLeft causes a piece-like change, OR
  *   - waiting ~1s causes the grid to change (auto-drop), OR
  *   - the grid transitions in any measurable way that's not just chrome
  *   - no immediate game over text
  */
 async function verifyGameStarted(driver: TetrisDriver): Promise<{
   ok: boolean;
   reason: string;
 }> {
   // 1. Instant rejection: game over text visible means we started into a
   //    dead state, or clicked a Restart that then immediately ended again.
   try {
     const gameOverText = await driver.detectGameOverText();
     if (gameOverText) {
       return { ok: false, reason: `immediate game over: "${gameOverText}"` };
     }
   } catch { /* continue */ }
 
   // 2. tryStartMechanism() populated a minimal calibration for us, but some
   //    games create their grid cells dynamically inside an animation frame
   //    after the start button is clicked -- the initial detectGrid() can run
   //    before the grid is fully populated. Refresh grid detection now so we
   //    pick up any cells that appeared in the meantime.
   try {
     await driver.refreshGridDetection();
   } catch { /* leave whatever tryStartMechanism populated */ }
 
   let cal;
   try {
     cal = driver.getCalibration();
   } catch {
     cal = null;
   }
   if (!cal || !cal.gridDetected) {
     return { ok: false, reason: "no grid detected after start attempt" };
   }
 
   // 3. Read the grid. Need a sane fill level (pieces, not chrome).
   const snap = await driver.readGrid();
   if (!snap.grid) {
     return { ok: false, reason: "grid read failed" };
   }
   const totalCells = snap.grid.length * (snap.grid[0]?.length || 0);
   if (totalCells === 0) {
     return { ok: false, reason: "grid has zero cells" };
   }
   const fillRatio = snap.filledCount / totalCells;
   // A running game may legitimately start empty, so 0 cells is allowed.
   // But >60% filled likely means we're reading chrome as cells.
   if (fillRatio > 0.6) {
     return {
       ok: false,
       reason: `grid ${Math.round(fillRatio * 100)}% filled (likely reading chrome)`,
     };
   }
 
   // 4. Evidence: press ArrowLeft and see if the grid changes (movement works).
   //    Capture pixel + DOM fingerprint snapshots at each step so we can fall
   //    back to either signal for games that render the active piece outside
   //    the cell layout (e.g. absolute-positioned divs floating over the grid).
   //    Pixel diff is clipped to the grid area; DOM fingerprint catches changes
   //    even when the piece is currently off-screen.
   let movementSeen = false;
   let movementPixelsChanged = false;
   let movementDomChanged = false;
   try {
     const pxBefore = await driver.screenshotGridArea();
     const fpBefore = await driver.captureGridDomFingerprint();
     const before = await driver.readGrid();
     await driver.pressKey("left");
     await driver.wait(250);
     const after = await driver.readGrid();
     const pxAfter = await driver.screenshotGridArea();
     const fpAfter = await driver.captureGridDomFingerprint();
     if (before.grid && after.grid && driver.gridsAreDifferent(before.grid, after.grid)) {
       movementSeen = true;
     }
     if (pxBefore && pxAfter && !pxBefore.equals(pxAfter)) {
       movementPixelsChanged = true;
     }
     if (fpBefore && fpAfter && fpBefore !== fpAfter) {
       movementDomChanged = true;
     }
   } catch { /* fall through to auto-drop check */ }
 
   // 5. Evidence: wait 1.1s and see if the grid changes on its own (auto-drop).
   let autoDropSeen = false;
   let autoDropPixelsChanged = false;
   let autoDropDomChanged = false;
   try {
     const pxBefore = await driver.screenshotGridArea();
     const fpBefore = await driver.captureGridDomFingerprint();
     const before = await driver.readGrid();
     await driver.wait(1100);
     const after = await driver.readGrid();
     const pxAfter = await driver.screenshotGridArea();
     const fpAfter = await driver.captureGridDomFingerprint();
     if (before.grid && after.grid && driver.gridsAreDifferent(before.grid, after.grid)) {
       autoDropSeen = true;
     }
     if (pxBefore && pxAfter && !pxBefore.equals(pxAfter)) {
       autoDropPixelsChanged = true;
     }
     if (fpBefore && fpAfter && fpBefore !== fpAfter) {
       autoDropDomChanged = true;
     }
   } catch { /* fall through */ }
 
   // 6. Second chance at game-over after interaction.
   try {
     const gameOverText = await driver.detectGameOverText();
     if (gameOverText) {
       return { ok: false, reason: `game over after interaction: "${gameOverText}"` };
     }
   } catch { /* continue */ }
 
   if (movementSeen && autoDropSeen) {
     return { ok: true, reason: "movement and auto-drop both observed" };
   }
   if (movementSeen) {
     return { ok: true, reason: "movement key changes the grid" };
   }
   if (autoDropSeen) {
     return { ok: true, reason: "grid changes on its own (auto-drop)" };
   }
 
   // 6b. Pixel-based fallback: if the grid reader can't see movement but the
   //     grid-area pixels changed both on key press AND during auto-drop, we're
   //     almost certainly looking at a running Tetris game that renders its
   //     active piece outside the cell layout (absolute divs, canvas overlay,
   //     etc). Require BOTH signals to avoid accepting spurious animations
   //     (cursor blink, score tick) as gameplay.
   if (movementPixelsChanged && autoDropPixelsChanged) {
     return {
       ok: true,
       reason: "grid-area pixels change on key press and on auto-drop (piece rendered outside cells)",
     };
   }
 
   // 6c. DOM-fingerprint fallback: when the active piece is an absolute-
   //     positioned overlay that happens to be off-screen in the current
   //     viewport (tall sidebars that push the grid out of frame), pixel diff
   //     can come back clean while the DOM still reflects the moving piece.
   //     Require BOTH a key-press-driven change AND an auto-drop-driven change
   //     so static pages with idle timers don't slip through.
   if (movementDomChanged && autoDropDomChanged) {
     return {
       ok: true,
       reason: "grid container DOM changes on key press and on auto-drop (piece rendered outside cells)",
     };
   }
 
   // 7. Weaker fallback: if the grid is populated in a plausible range
   //    (some pieces visible somewhere) and there's no game over, accept it
   //    provisionally. The downstream phases will weed out dead starts.
   if (snap.filledCount > 0 && snap.filledCount < totalCells * 0.5) {
     return {
       ok: false,
       reason: `grid populated (${snap.filledCount} cells) but no movement or auto-drop observed`,
     };
   }
 
   return { ok: false, reason: "no gameplay evidence detected" };
 }
 
 /**
  * Full discovery loop: ask the driver for candidates, try each, verify with
  * verifyGameStarted(), and return the first candidate the bot trusts. Reloads
  * the page between candidates so each attempt starts from a clean state.
  */
 async function detectStartWithVerification(
   driver: TetrisDriver,
   serverUrl: string
 ): Promise<{ candidate: StartCandidate } | null> {
   const log = (msg: string) => console.log(`[bot:start] ${msg}`);
 
   const candidates = await driver.discoverStartCandidates();
   log(`discovered ${candidates.length} candidate(s)`);
 
   for (let i = 0; i < candidates.length; i++) {
     const candidate = candidates[i];
     log(`(${i + 1}/${candidates.length}) trying: ${candidate.label}`);
 
     // Apply without committing.
     let tryResult;
     try {
       tryResult = await driver.tryStartMechanism(candidate);
     } catch (err) {
       log(`  tryStartMechanism threw: ${err instanceof Error ? err.message : String(err)}`);
       await reloadAndClear(driver, serverUrl);
       continue;
     }
 
     // Skip candidates with no observable effect at all.
     if (!tryResult.visualChanged && !tryResult.domChanged && candidate.mechanism !== "auto") {
       log(`  no visual/DOM change, skipping`);
       continue;
     }
     if (tryResult.errorOccurred) {
       log(`  JS error fired during attempt, skipping`);
       await reloadAndClear(driver, serverUrl);
       continue;
     }
 
     // Ask the bot's own verification.
     let verification;
     try {
       verification = await verifyGameStarted(driver);
     } catch (err) {
       log(`  verifyGameStarted threw: ${err instanceof Error ? err.message : String(err)}`);
       await reloadAndClear(driver, serverUrl);
       continue;
     }
 
     if (verification.ok) {
       log(`  VERIFIED: ${verification.reason}`);
       // Important: the page is already in a started state. We clear the
       // driver's cached calibration (without reloading) so the follow-up
       // calibrate() call will re-apply the candidate from scratch -- that
       // way the phase separation (load -> apply -> verify) stays consistent
       // across downstream phases that reload the page.
       await reloadAndClear(driver, serverUrl);
       return { candidate };
     }
 
     log(`  REJECTED: ${verification.reason}`);
     await reloadAndClear(driver, serverUrl);
   }
 
   log("no candidate verified");
   return null;
 }
 
 /** Reload the page and clear any in-flight confirmed candidate. */
 async function reloadAndClear(driver: TetrisDriver, serverUrl: string): Promise<void> {
   try {
     driver.clearConfirmedStartMechanism();
   } catch { /* ignore */ }
   try {
     await driver.loadPage(serverUrl);
   } catch { /* ignore */ }
 }