loop-benchmarking

REFACTOR_SPEC.md (30796B)

---

 # Two-Tier Refactor Spec: Driver + Bot
 
 ## Problem Statement
 
 The gameplay bot is ~3500 lines across 6 files, with two distinct concerns tangled
 together: understanding the webpage (finding grids, clicking buttons, reading pixels,
 sending keystrokes) and playing Tetris (phase orchestration, AI decisions, test
 derivation, bug detection). The boundary between them is blurred:
 
 - `calibrate.ts` handles grid detection, start mechanism detection, control detection,
   overlay detection, interactivity verification, screenshot sampling, visual change
   detection, and page surveying -- all in one 1300-line file.
 - `tests.ts` does phase orchestration, BUT ALSO calls `readGrid` directly during
   mechanics tests, reads score elements, detects game over text, measures drop
   intervals, detects next piece previews, and reads level displays.
 - `player.ts` calls both `readGrid` and `page.keyboard.press` directly, coupling
   AI logic to the Playwright API.
 - `grid-reader.ts` is the cleanest module but still exports low-level grid analysis
   utilities (bounding boxes, cell counts, piece identification) that the bot calls
   directly instead of going through an abstraction.
 
 The result: any change to how the page is read ripples through all files. You cannot
 test the AI player without a live Playwright page. You cannot swap the grid reader
 without touching the test orchestrator.
 
 ## Proposed Architecture
 
 ```
                  +------------------+
                  |    index.ts      |  Entry point: HTTP server, Playwright test,
                  |                  |  report output. Unchanged.
                  +--------+---------+
                           |
                           v
                  +------------------+
                  |     bot.ts       |  Layer 2: "The Brain"
                  |                  |  Phase orchestration, AI decisions, test
                  |                  |  derivation, competitive play, bug detection.
                  |                  |  Calls only the Driver interface.
                  +--------+---------+
                           |
                           v
                  +------------------+
                  |    driver.ts     |  Layer 1: "The Eyes and Hands"
                  |                  |  Abstracts the webpage. Exposes a clean API.
                  |                  |  Handles grid reading, start detection,
                  |                  |  control detection, keyboard input.
                  +--------+---------+
                           |
                 +---------+---------+
                 |                   |
                 v                   v
         +-----------+       +------------+
         | types.ts  |       | player.ts  |  Pure Tetris logic: AI heuristics,
         |           |       |            |  board simulation, placement finding.
         +-----------+       |            |  NO Playwright imports. NO page access.
                             +------------+
 ```
 
 ### What goes where
 
 **driver.ts** -- "I can see and interact with this webpage"
 - Grid detection (finding the grid on the page)
 - Grid reading (10x20 boolean matrix from canvas/DOM/SVG)
 - Start mechanism detection (the 5-phase cascade)
 - Control detection (which keys the game responds to)
 - Score/level/lines reading
 - Keyboard input (move, rotate, drop)
 - Screenshot capture
 - Interactivity verification
 - Page surveying (pre-test data collection)
 - Background color sampling
 - Visual change detection
 - Next piece preview detection
 - Game over text detection
 - Re-calibration
 
 **bot.ts** -- "I know Tetris rules and test logic"
 - Phase orchestration (the 8 conditional phases)
 - Test derivation from session data (the 24 tests)
 - Score/timing/event tracking (GameSession bookkeeping)
 - Competitive play with bug detection
 - Line clear detection logic (watching grid state transitions)
 - Game over triggering strategy (stack pieces to fill grid)
 - Endurance testing
 - Report assembly (BotReport construction)
 
 **player.ts** -- "I know where to put pieces" (pure computation, no I/O)
 - 4-heuristic scoring (aggregate height, lines, holes, bumpiness)
 - Piece definitions (rotations, dimensions)
 - Board simulation (drop piece, clear lines)
 - Best placement finding
 - No `Page` import, no `readGrid` call, no `keyboard.press`
 
 **types.ts** -- unchanged, all interfaces stay
 
 **grid-reader.ts** -- absorbed into driver.ts (see migration plan)
 
 **index.ts** -- unchanged except it calls bot.ts instead of tests.ts
 
 ---
 
 ## Driver Interface
 
 ```typescript
 import type { Page } from "@playwright/test";
 import type {
   Grid,
   GridBounds,
   RendererType,
   Controls,
   StartMechanism,
   SurveyData,
   PieceType,
 } from "./types";
 
 // ---------------------------------------------------------------------------
 // Configuration returned by calibration, passed through subsequent calls.
 // Replaces CalibrationResult for internal use within the Driver.
 // ---------------------------------------------------------------------------
 
 export interface DriverCalibration {
   renderer: RendererType;
   gridDetected: boolean;
   gridBounds: GridBounds | null;
   cellWidth: number;
   cellHeight: number;
   controls: Controls;
   startMechanism: StartMechanism;
   scoreElementSelector: string | null;
   levelElementSelector: string | null;
   backgroundColor: [number, number, number] | null;
   consoleErrors: string[];
   gridConfidence: number;
   startButton?: {
     selector: string;
     text: string;
     disappeared: boolean;
     position: { x: number; y: number };
   };
 }
 
 // ---------------------------------------------------------------------------
 // Grid snapshot: the grid state plus derived information the bot needs.
 // ---------------------------------------------------------------------------
 
 export interface GridSnapshot {
   /** The 10x20 boolean grid. null if reading failed. */
   grid: Grid | null;
   /** Total filled cells. 0 if grid is null. */
   filledCount: number;
   /** Filled cells in the bottom N rows. */
   filledInBottom(rows: number): number;
   /** Whether any cell in the top N rows is filled. */
   hasFilledInTop(rows: number): boolean;
   /** Number of fully complete rows. */
   completeRows: number;
   /** Active piece cells (diff against settled grid). null if undetectable. */
   activePieceCells: [number, number][] | null;
   /** Identified piece type from active piece cells. null if no active piece. */
   activePieceType: PieceType | null;
 }
 
 // ---------------------------------------------------------------------------
 // The Driver interface. This is what the Bot sees.
 // ---------------------------------------------------------------------------
 
 export interface TetrisDriver {
   // -- Lifecycle --
 
   /**
    * Navigate to the game URL, wait for load, begin console error collection.
    * Returns false if the page failed to load.
    */
   loadPage(url: string): Promise<{ loaded: boolean; detail: string; errorsOnLoad: number }>;
 
   /**
    * Survey the page structure before any interaction.
    * Returns information about overlays, canvas elements, DOM grids, visible text.
    */
   surveyPage(): Promise<SurveyData>;
 
   /**
    * Run full calibration: grid detection, start mechanism detection,
    * control detection, score element detection, grid confidence measurement.
    * Includes re-calibration fallback if initial detection fails.
    * Never throws.
    */
   calibrate(): Promise<DriverCalibration>;
 
   /**
    * Re-run calibration after the game state may have changed
    * (e.g., after starting, grid might appear that wasn't there before).
    * Keeps the current calibration if re-calibration finds nothing better.
    */
   recalibrate(): Promise<DriverCalibration>;
 
   /**
    * Get the current calibration. Throws if calibrate() hasn't been called.
    */
   getCalibration(): DriverCalibration;
 
   // -- Grid Reading --
 
   /**
    * Read the current grid state. Returns a GridSnapshot with the raw grid
    * and derived metrics. If settled grid is provided, active piece detection
    * is diffed against it.
    *
    * Returns a snapshot with grid: null if reading fails.
    */
   readGrid(settledGrid?: Grid | null): Promise<GridSnapshot>;
 
   /**
    * Compare two grids for equality. True if they differ.
    */
   gridsAreDifferent(a: Grid | null, b: Grid | null): boolean;
 
   // -- Input --
 
   /**
    * Press a game control key. Uses the controls detected during calibration.
    */
   pressKey(action: "left" | "right" | "down" | "rotate" | "drop"): Promise<void>;
 
   /**
    * Press an arbitrary key (for testing CCW rotation with 'z', etc.).
    */
   pressRawKey(key: string): Promise<void>;
 
   /**
    * Wait for a specified duration (milliseconds).
    */
   wait(ms: number): Promise<void>;
 
   // -- Score/Level/Lines Reading --
 
   /**
    * Read the current score from the detected score element.
    * Returns null if no score element was found or reading fails.
    */
   readScore(): Promise<number | null>;
 
   /**
    * Read the current level from the page.
    * Returns null if no level display found or reading fails.
    */
   readLevel(): Promise<number | null>;
 
   // -- Page State Queries --
 
   /**
    * Check if "Game Over" (or equivalent) text is visible on the page.
    * Returns the matched text, or null if not found.
    */
   detectGameOverText(): Promise<string | null>;
 
   /**
    * Check if a restart button/prompt is visible.
    */
   detectRestartOption(): Promise<boolean>;
 
   /**
    * Check if a next piece preview display exists.
    */
   detectNextPiecePreview(): Promise<boolean>;
 
   /**
    * Get all console errors collected since loadPage() was called.
    */
   getConsoleErrors(): string[];
 
   // -- Screenshots --
 
   /**
    * Take a screenshot. Returns raw PNG buffer.
    */
   screenshot(): Promise<Buffer>;
 
   /**
    * Measure the auto-drop interval (time between gravity-driven grid changes
    * with no input). Returns average interval in ms, or 0 if unmeasurable.
    */
   measureDropInterval(): Promise<number>;
 }
 ```
 
 ### Method-to-Source Mapping
 
 Each Driver method maps to existing code as follows:
 
 | Driver Method | Current Source | Current Function(s) |
 |---|---|---|
 | `loadPage()` | tests.ts:277-303 | `loadAndCheckPage()`, `loadGamePage()` |
 | `surveyPage()` | calibrate.ts:1300-1393 | `surveyPage()` |
 | `calibrate()` | calibrate.ts:24-94 | `calibrate()`, `detectGrid()`, `detectStartMechanism()`, `detectControls()`, `detectScoreElement()`, `measureGridConfidence()` |
 | `recalibrate()` | tests.ts:152-163 | inline re-calibration after start |
 | `readGrid()` | grid-reader.ts:15-38, 46-118, 142-364 | `readGrid()`, `readCanvasGrid()`, `readDomGrid()`, plus `countFilled()`, `countFilledInBottomRows()`, `hasFilledInTopRows()`, `countCompleteRows()`, `detectActivePieceCells()`, `identifyPieceType()` |
 | `gridsAreDifferent()` | grid-reader.ts:400-410 | `gridsAreDifferent()` |
 | `pressKey()` | player.ts:251-277 | inline `page.keyboard.press()` calls using `cal.controls` |
 | `pressRawKey()` | tests.ts:841-842 | inline `page.keyboard.press("z")` |
 | `wait()` | everywhere | `page.waitForTimeout()` |
 | `readScore()` | tests.ts:490-497, 529-538, 743-749 | inline score element reading |
 | `readLevel()` | tests.ts:1597-1630 | `readLevelFromPage()` |
 | `detectGameOverText()` | tests.ts:929-940 | inline `page.evaluate()` for game over text |
 | `detectRestartOption()` | tests.ts:943-955 | inline `page.evaluate()` for restart buttons |
 | `detectNextPiecePreview()` | tests.ts:1669-1717 | `detectNextPiecePreview()` |
 | `getConsoleErrors()` | tests.ts:94-98 | `consoleErrors` array |
 | `screenshot()` | player.ts:370-371 | `page.screenshot()` |
 | `measureDropInterval()` | tests.ts:1636-1664 | `measureDropInterval()` |
 
 ### How the Driver handles different renderers
 
 The Driver encapsulates renderer differences entirely. The Bot never knows or cares
 whether the game uses canvas, DOM, SVG, or WebGL.
 
 ```
 readGrid() internally:
   if renderer === "canvas" && gridBounds:
     -> readCanvasGrid() via page.evaluate(getImageData)
   if renderer === "dom":
     -> readDomGrid() via page.evaluate(DOM traversal)
   if renderer === "svg":
     -> future: readSvgGrid()
   fallback:
     -> try canvas if bounds exist, then try DOM
 ```
 
 The `GridSnapshot` returned to the Bot is always the same shape regardless of renderer.
 
 ### Re-calibration
 
 The Driver maintains mutable internal state:
 
 ```typescript
 class PlaywrightDriver implements TetrisDriver {
   private page: Page;
   private cal: DriverCalibration | null = null;
   private consoleErrors: string[] = [];
 }
 ```
 
 `recalibrate()` re-runs grid detection and start detection, but preserves
 the existing calibration if the new one is worse (e.g., grid detection fails
 on re-calibration but worked initially). This handles:
 
 - Games where the grid appears only after clicking "Start"
 - Games where the grid is rebuilt on game restart (new DOM elements)
 - Games where the canvas resizes after initialization
 
 ### Error handling
 
 | Scenario | Driver behavior |
 |---|---|
 | Grid read returns null | `readGrid()` returns `GridSnapshot` with `grid: null`, `filledCount: 0` |
 | Grid read throws | Same as null -- caught internally, never thrown to Bot |
 | No score element found | `readScore()` returns `null` |
 | Score element disappeared | `readScore()` returns `null` (caught internally) |
 | Console error during play | Accumulated in `consoleErrors`, accessible via `getConsoleErrors()` |
 | Page navigation fails | `loadPage()` returns `{ loaded: false, detail: "..." }` |
 | Canvas getImageData all zeros (no GPU) | Grid validation rejects (>60% filled), returns null |
 | Calibration finds nothing | Returns calibration with `gridDetected: false`, `startMechanism: "unknown"` |
 
 The Driver never throws. All errors are represented in return values.
 
 ---
 
 ## Bot Interface
 
 ### How the Bot calls the Driver
 
 The Bot receives a `TetrisDriver` instance. It never imports `Page` or
 anything from Playwright. It never calls `page.evaluate()`, `page.keyboard`,
 or `page.screenshot()` directly.
 
 ```typescript
 // bot.ts
 import type { TetrisDriver, DriverCalibration, GridSnapshot } from "./driver";
 import type {
   TestResult,
   GameplayStats,
   GameSession,
   CompetitivePlayResult,
   SurveyData,
   BotReport,
   Grid,
 } from "./types";
 import { findBestPlacement } from "./player";
 
 export async function runAllTests(
   driver: TetrisDriver,
   serverUrl: string
 ): Promise<{
   testResults: TestResult[];
   calibration: DriverCalibration;
   gameplay: GameplayStats;
   session: GameSession;
   survey: SurveyData;
   competitivePlay: CompetitivePlayResult | null;
 }> {
   // Phase 1: Load
   const loadResult = await driver.loadPage(serverUrl);
   // ...
 
   // Phase 2: Calibrate
   const cal = await driver.calibrate();
   // ...
 
   // Phase 3-8: Use only driver.readGrid(), driver.pressKey(), etc.
 }
 ```
 
 ### Phase execution flow using Driver methods
 
 **Phase 1: Page Load**
 ```
 driver.loadPage(url) -> { loaded, detail, errorsOnLoad }
 driver.wait(3000)
 ```
 
 **Phase 2: Calibrate + Start**
 ```
 survey = driver.surveyPage()
 cal = driver.calibrate()
   // Internally: detectStartMechanism(), detectGrid(), etc.
 if cal.startMechanism === "unknown" || !cal.gridDetected:
   cal = driver.recalibrate()
 ```
 
 **Phase 3: Basic Mechanics**
 ```
 // Auto-drop test
 snap0 = driver.readGrid()
 driver.wait(5000)
 snap1 = driver.readGrid()
 gridChanged = driver.gridsAreDifferent(snap0.grid, snap1.grid)
 
 // Movement tests
 for dir in [left, right, down]:
   snapBefore = driver.readGrid()
   driver.pressKey(dir)
   driver.wait(300)
   snapAfter = driver.readGrid()
   // compare
 
 // Rotation test
 snapBefore = driver.readGrid()
 driver.pressKey("rotate")
 driver.wait(300)
 snapAfter = driver.readGrid()
 // compare bounding boxes of active piece cells
 
 // Hard drop test
 driver.pressKey("drop")
 driver.wait(500)
 snapAfter = driver.readGrid()
 // check bottom rows
 ```
 
 **Phase 4: Piece Lifecycle**
 ```
 // Already tested during Phase 3 mechanics
 // Piece locks: bottom cells persist across reads
 // New piece spawns: top rows have cells after drop
 // Multiple pieces: piecesLocked counter >= 3
 ```
 
 **Phase 5: Gameplay**
 ```
 driver.loadPage(url)
 cal = driver.calibrate()
 initialScore = driver.readScore()
 // Play loop (60 pieces / 45s):
 while pieces < 60 && elapsed < 45s:
   snap = driver.readGrid(settledGrid)
   if snap.activePieceCells:
     placement = findBestPlacement(settledGrid, snap.activePieceType)
     // Execute placement using driver.pressKey()
     for i in 0..placement.rotations:
       driver.pressKey("rotate")
       driver.wait(50)
     // Move to column
     driver.pressKey("left" or "right") * N
     driver.pressKey("drop")
     driver.wait(100)
     settledGrid = (await driver.readGrid()).grid
   driver.wait(60)
 finalScore = driver.readScore()
 ```
 
 **Phase 6: Game Over**
 ```
 driver.loadPage(url)
 driver.calibrate()
 // Hard drop 40 times, checking grid after every 5
 for i in 0..40:
   driver.pressKey("drop")
   driver.wait(150)
   if i % 5 === 0:
     snap = driver.readGrid()
     if snap.hasFilledInTop(4):
       driver.pressKey("drop")
       driver.wait(300)
       snap2 = driver.readGrid()
       if !driver.gridsAreDifferent(snap.grid, snap2.grid):
         // Game over detected
 gameOverText = driver.detectGameOverText()
 ```
 
 **Phase 7: Endurance**
 ```
 driver.loadPage(url)
 driver.calibrate()
 // Play for 30 seconds using same play loop as Phase 5
 ```
 
 **Phase 8: Competitive Play**
 ```
 driver.loadPage(url)
 driver.calibrate()
 initialDropInterval = driver.measureDropInterval()
 initialLevel = driver.readLevel()
 // Play for 60 seconds with detailed tracking
 // Every 5th poll: driver.readScore()
 // Every 10th poll: driver.readLevel()
 // Periodic: driver.pressRawKey("z") for CCW test
 // Periodic: soft drop test via driver.pressKey("down")
 finalDropInterval = driver.measureDropInterval()
 nextPieceVisible = driver.detectNextPiecePreview()
 gameOverText = driver.detectGameOverText()
 restartAvailable = driver.detectRestartOption()
 ```
 
 ### Test derivation
 
 `deriveTestResults()` stays in bot.ts. It receives the `GameSession` data
 that the Bot accumulated during phases, and produces the 24 `TestResult[]` array.
 It does not need the Driver at all -- it operates on pure data.
 
 The function signature is unchanged:
 
 ```typescript
 function deriveTestResults(
   session: GameSession,
   cal: DriverCalibration,
   loadResult: LoadResult,
   consoleErrors: string[],
   gameplay: GameplayStats,
   phaseState: PhaseState,
   competitivePlay: CompetitivePlayResult | null
 ): TestResult[]
 ```
 
 ### Where the AI player logic lives
 
 `player.ts` becomes a pure computation module. It keeps:
 
 - `PIECES` definitions
 - `findBestPlacement()` (exported)
 - `findBestPlacementGeneric()`
 - `simulateDropPiece()`
 - `clearLines()`
 - `aggregateHeight()`, `countHoles()`, `bumpiness()`
 - `stripActivePiece()` (exported)
 - `Placement` interface (exported)
 
 It loses:
 
 - `playGame()` -- moves to bot.ts (it orchestrates grid reads + AI + key presses)
 - `hardDrop()` -- replaced by `driver.pressKey("drop")`
 - `playRandomMove()` -- moves to bot.ts
 - `playRandomForDuration()` -- moves to bot.ts
 - `tryFillRow()` -- moves to bot.ts
 - `stackToGameOver()` -- moves to bot.ts
 - `executePlacement()` -- moves to bot.ts (it calls driver.pressKey)
 - `countTotalFilled()` -- redundant with GridSnapshot.filledCount
 
 After refactor, `player.ts` has zero Playwright imports.
 
 ---
 
 ## Migration Plan
 
 ### New files created
 
 | File | Purpose | Est. lines |
 |---|---|---|
 | `driver.ts` | TetrisDriver interface + PlaywrightDriver implementation | ~900 |
 | `bot.ts` | Phase orchestration, play loops, test derivation | ~1100 |
 
 ### Files modified
 
 | File | Change |
 |---|---|
 | `player.ts` | Remove all Playwright-dependent functions, keep pure AI logic | ~350 -> ~250 |
 | `types.ts` | Add `DriverCalibration`, `GridSnapshot` interfaces (or keep in driver.ts). Minor additions. | ~205 -> ~220 |
 | `index.ts` | Change import from `tests.ts` to `bot.ts`, instantiate `PlaywrightDriver`, pass to `runAllTests`. | ~260 -> ~270 |
 
 ### Files deleted
 
 | File | Reason |
 |---|---|
 | `calibrate.ts` | Absorbed into `driver.ts` |
 | `grid-reader.ts` | Absorbed into `driver.ts` |
 | `tests.ts` | Replaced by `bot.ts` |
 
 ### What stays
 
 - `types.ts` -- interfaces stay the same, report format unchanged
 - `index.ts` -- HTTP server, Playwright test structure, report writing all stay
 - `SPEC.md` -- unchanged
 - `COMPETITIVE_PLAY_SPEC.md` -- unchanged
 - Report format (`BotReport`) -- identical JSON output
 
 ### Incremental migration (4 phases)
 
 **Phase A: Create driver.ts with the interface + implementation (no callers yet)**
 
 1. Create `driver.ts` with `TetrisDriver` interface and `PlaywrightDriver` class.
 2. Move into it from `calibrate.ts`:
    - `detectStartMechanism()` and its sub-functions (`tryKeyboardTriggers`, `tryDomButtons`, `tryCanvasClicks`)
    - `detectGrid()`
    - `detectControls()`
    - `detectScoreElement()`
    - `measureGridConfidence()`
    - `surveyPage()`
    - `sampleScreenshot()`
    - `detectVisualChange()`
    - `verifyInteractivity()`
    - `clusterPoints()`
    - `recalibrateWithRetry()`
 3. Move into it from `grid-reader.ts`:
    - `readGrid()`, `readCanvasGrid()`, `readDomGrid()`
    - `sampleBackgroundColor()`
    - `validateGridBounds()`
    - `gridsAreDifferent()`
    - `countFilled()`, `countFilledInBottomRows()`, `hasFilledInTopRows()`
    - `countCompleteRows()`, `isRowComplete()`
    - `getColumnHeights()`
    - `detectActivePieceCells()`, `identifyPieceType()`
 4. Move into it from `tests.ts`:
    - `readLevelFromPage()`
    - `measureDropInterval()`
    - `detectNextPiecePreview()`
    - `extractScoreFromText()` (internal helper)
 5. Wrap everything behind `PlaywrightDriver` methods.
 6. Export both the interface and the class.
 7. At this point, old code still works -- `calibrate.ts`, `grid-reader.ts`, and `tests.ts` are unchanged.
 
 **Commit A**: "Add driver.ts: TetrisDriver interface and PlaywrightDriver implementation"
 
 **Phase B: Create bot.ts (calls driver.ts, replaces tests.ts)**
 
 1. Create `bot.ts` with the new `runAllTests()` that accepts `TetrisDriver`.
 2. Move into it from `tests.ts`:
    - `runAllTests()` (rewritten to call Driver instead of Playwright directly)
    - `runBasicMechanicsPhase()`
    - `runGameplayPhase()`
    - `runGameOverPhase()`
    - `runEndurancePhase()`
    - `runCompetitivePlayPhase()`
    - `deriveTestResults()`
    - `ALL_TEST_NAMES`
    - `emptyCalibration()` (adapted to return `DriverCalibration`)
    - `loadAndCheckPage()` (replaced by `driver.loadPage()`)
    - `boundingBox()` helper
    - `countFilledInTopRows()` helper (local in tests.ts, replaced by GridSnapshot method)
 3. Move into it from `player.ts`:
    - `playGame()` (rewritten to call Driver)
    - `executePlacement()` (rewritten to call Driver)
    - `playRandomMove()` (rewritten to call Driver)
    - `playRandomForDuration()` (rewritten to call Driver)
    - `tryFillRow()` (rewritten to call Driver)
    - `stackToGameOver()` (rewritten to call Driver)
 4. bot.ts imports `findBestPlacement`, `stripActivePiece`, `Placement` from `player.ts`
    and everything else from `driver.ts`.
 
 **Commit B**: "Add bot.ts: phase orchestration using TetrisDriver"
 
 **Phase C: Rewire index.ts, slim player.ts**
 
 1. Update `index.ts`:
    - Import `PlaywrightDriver` from `./driver`
    - Import `runAllTests` from `./bot` (not `./tests`)
    - In the test body: `const driver = new PlaywrightDriver(page); const results = await runAllTests(driver, serverUrl);`
 2. Remove from `player.ts`:
    - `playGame()`, `hardDrop()`, `executePlacement()`, `playRandomMove()`, `playRandomForDuration()`, `tryFillRow()`, `stackToGameOver()`
    - `import type { Page }` and `import { readGrid, ... }` from grid-reader
    - `countTotalFilled()` (redundant)
 3. `player.ts` now exports only:
    - `findBestPlacement()` (accepts `Grid` and `PieceType`, returns `Placement | null`)
    - `stripActivePiece()` (accepts `Grid` and cells, returns `Grid`)
    - `Placement` interface
 
 **Commit C**: "Rewire index.ts to use bot.ts + driver.ts, slim player.ts"
 
 **Phase D: Delete old files**
 
 1. Delete `calibrate.ts`
 2. Delete `grid-reader.ts`
 3. Delete `tests.ts`
 4. Verify all imports resolve
 5. Run the full eval pipeline against a known artifact to confirm identical report output
 
 **Commit D**: "Remove old calibrate.ts, grid-reader.ts, tests.ts"
 
 ### Backwards compatibility
 
 The report format (`BotReport`) does not change. The JSON output is byte-identical
 for the same game input. The summary score calculation is unchanged. The test names
 are unchanged. The competitive play data structure is unchanged.
 
 The only external-facing change is the internal file structure. Nothing downstream
 (the scoring pipeline, the dashboard, the harness) needs to change.
 
 ---
 
 ## File Structure After Refactor
 
 ```
 gameplay-bot/
   types.ts          ~220 lines   Interfaces (unchanged)
   driver.ts         ~900 lines   TetrisDriver interface + PlaywrightDriver class
   player.ts         ~250 lines   Pure AI: heuristics, simulation, placement finding
   bot.ts           ~1100 lines   Phases, play loops, test derivation, competitive play
   index.ts          ~270 lines   Playwright test entry, HTTP server, report output
   SPEC.md                        Unchanged
   COMPETITIVE_PLAY_SPEC.md       Unchanged
   REFACTOR_SPEC.md               This document
 ```
 
 Total: ~2740 lines (down from ~3500 because of deduplication and removing
 redundant helpers that now live behind the Driver).
 
 ### Import/dependency graph
 
 ```
 index.ts
   -> driver.ts (PlaywrightDriver constructor)
   -> bot.ts (runAllTests)
   -> types.ts (BotReport)
 
 bot.ts
   -> driver.ts (TetrisDriver interface, DriverCalibration, GridSnapshot)
   -> player.ts (findBestPlacement, stripActivePiece, Placement)
   -> types.ts (all data interfaces)
 
 driver.ts
   -> types.ts (Grid, GridBounds, RendererType, Controls, etc.)
   -> @playwright/test (Page)
 
 player.ts
   -> types.ts (Grid, PieceType)
   (NO @playwright/test import)
 ```
 
 Key constraint: `bot.ts` does NOT import `@playwright/test`. It depends on the
 `TetrisDriver` interface, not the implementation. This means the Bot can be tested
 with a mock driver that returns canned grid states -- no browser needed.
 
 ---
 
 ## Edge Cases
 
 ### Games that need re-calibration mid-session
 
 **Scenario**: Grid appears only after clicking "Start". On page load, there is no
 canvas and no DOM grid -- just a splash screen.
 
 **Current behavior**: `calibrate()` runs on the splash screen, finds nothing.
 Then `tests.ts` tries start mechanisms, and after starting, re-runs `calibrate()`.
 
 **Driver behavior**: `calibrate()` includes start detection. If it starts the game
 but finds no grid, it waits and re-scans. `recalibrate()` is also available for the
 Bot to call explicitly after any phase reload.
 
 **Bot flow**:
 ```
 cal = driver.calibrate()
 if cal.gridDetected === false && cal.startMechanism !== "unknown":
   // Game started but grid not found yet -- wait and retry
   driver.wait(500)
   cal = driver.recalibrate()
 ```
 
 ### Games where the Driver cannot read the grid at all
 
 **Scenario**: Canvas game without GPU access. `getImageData()` returns all zeros.
 
 **Driver behavior**: `readGrid()` returns `GridSnapshot { grid: null }` every time.
 The Bot sees grid failures accumulate.
 
 **Bot flow**: Phase 3 (mechanics) detects that `gridReadSuccess === 0`. The Bot
 marks all grid-dependent tests as failed with detail "grid reader unavailable".
 It does NOT fall back to screenshot-only testing (per the "NO FALSE POSITIVES" rule).
 Competitive play is skipped.
 
 ### Games that pause themselves
 
 **Scenario**: Player accidentally triggers a pause menu (Escape key, or a pause
 button that overlaps with the game area).
 
 **Driver behavior**: `readGrid()` may return null (if an overlay covers the grid)
 or return a static grid (same state on every read). The Driver does not know about
 pausing -- it just reports what it sees.
 
 **Bot flow**: The play loop in bot.ts already handles stale grids. If the grid
 hasn't changed for 8 seconds, it tries pressing the drop key (which may unpause).
 If grid reads start returning null, the Bot counts consecutive failures. After 10
 consecutive null reads, it falls back to random key presses for a brief period,
 then re-reads.
 
 The Bot could also try pressing Escape or P to dismiss a pause screen:
 ```
 if consecutiveUnchanged > 80: // 80 polls * 60ms = ~5 seconds
   driver.pressRawKey("Escape")
   driver.wait(500)
   driver.pressRawKey("p")
   driver.wait(500)
 ```
 
 ### Games with overlays that block gameplay
 
 **Scenario**: A modal overlay (tutorial, cookie consent, "enter your name" dialog)
 appears on top of the game, blocking input.
 
 **Driver behavior**: `surveyPage()` detects overlays (positioned elements covering
 >50% of viewport). The start mechanism detection already tries clicking overlays
 and pressing Escape to dismiss them.
 
 **Bot flow**: If the game started but mechanics tests show no response to input
 (movementsObserved === 0), the Bot can request a recalibrate, which may re-run
 start detection and dismiss a new overlay.
 
 ### Games in different languages
 
 **Scenario**: The game UI is in Spanish, Japanese, or any non-English language.
 "Start", "Game Over", "Score" have different text.
 
 **Driver behavior**: Start mechanism detection is already fully language-agnostic
 (visual change detection + interactivity verification, no text matching). Score
 element detection falls back from labeled text ("Score: 0") to structural heuristics
 (leaf element containing a standalone number). Game over text detection checks
 multiple languages ("game over", "fin del juego", etc.) or falls back to
 grid-state-based detection (grid frozen after filling to top).
 
 **Bot flow**: The Bot does not do any text matching. It delegates all text-based
 detection to the Driver. Tests like `game_over` use `driver.detectGameOverText()`
 which is the Driver's responsibility. The Bot adds a grid-based game over check
 (frozen grid after stacking) as a secondary signal that doesn't depend on language.
 
 The `detectGameOverText()` method could be extended with more languages:
 ```typescript
 // Inside driver.ts
 const gameOverPatterns = [
   "game over", "gameover", "you lose", "try again",
   "play again", "restart", "fin del juego", "juego terminado",
   "ゲームオーバー", "游戏结束"
 ];
 ```
 
 But the primary game over detection in bot.ts (Phase 6) does not depend on text --
 it watches the grid freeze after filling to the top.
 
 ---
 
 ## What This Spec Does NOT Cover
 
 - WebGL grid reading (not implemented yet, out of scope)
 - New tests beyond the existing 24
 - Changes to the report format or scoring
 - Dashboard changes
 - Harness changes
 - Performance optimization of grid reading
 - Testability improvements beyond the Driver/Bot split (e.g., mock Driver tests)
 
 These are natural follow-ups after the refactor lands, but they are separate work items.