loop-benchmarking

driver.ts (134928B)

---

 // PlaywrightDriver: TetrisDriver implementation using Playwright
 // "The Eyes and Hands" -- handles ALL webpage interaction
 
 import type { Page } from "@playwright/test";
 import type {
   Grid,
   GridBounds,
   RendererType,
   Controls,
   ControlMap,
   ControlMapping,
   GameAction,
   StartMechanism,
   StartCandidate,
   TryStartResult,
   SurveyData,
   GameLandmarks,
   PieceType,
   DriverCalibration,
   CalibrationDrift,
   GridSnapshot,
   TetrisDriver,
 } from "./types";
 
 const GRID_ROWS = 20;
 const GRID_COLS = 10;
 
 export class InactivityAbortError extends Error {
   constructor(message: string) {
     super(message);
     this.name = "InactivityAbortError";
   }
 }
 
 const DEFAULT_CONTROLS: Controls = {
   left: "ArrowLeft",
   right: "ArrowRight",
   down: "ArrowDown",
   rotate: "ArrowUp",
   drop: "Space",
 };
 
 /**
  * Candidate keys to try for each abstract game action, in priority order.
  * The discovery loop tries these from top to bottom until one matches the
  * expected behaviour (e.g. moves piece 1 column left).
  */
 const CONTROL_CANDIDATES: Record<GameAction, string[]> = {
   move_left: ["ArrowLeft", "a", "h"],
   move_right: ["ArrowRight", "d", "l"],
   // ArrowDown LAST: some games treat it as hard_drop, so we try alternatives
   // first and fall through. This is the key insight of the discovery system.
   soft_drop: ["s", "ArrowDown"],
   // ArrowDown also gets tried as hard_drop because some games bind the down
   // arrow to hard drop instead of soft drop. Order: conventional hard-drop
   // keys first, then the ambiguous ArrowDown last.
   hard_drop: ["Space", "Enter", "ArrowUp", "ArrowDown"],
   rotate_cw: ["ArrowUp", "x", "w"],
   rotate_ccw: ["z", "Control"],
   // pause/hold are not currently discovered; we keep these entries for type
   // completeness but they remain at default "not_found".
   pause: ["p", "Escape"],
   hold: ["c", "Shift"],
 };
 
 function emptyControlMap(): ControlMap {
   const notFound = (): ControlMapping => ({
     key: null,
     confidence: "not_found",
     observation: "",
   });
   return {
     move_left: notFound(),
     move_right: notFound(),
     soft_drop: notFound(),
     hard_drop: notFound(),
     rotate_cw: notFound(),
     rotate_ccw: notFound(),
     key_observations: {},
   };
 }
 
 // ---------------------------------------------------------------------------
 // GridSnapshot factory
 // ---------------------------------------------------------------------------
 
 function makeSnapshot(
   grid: Grid | null,
   settledGrid?: Grid | null
 ): GridSnapshot {
   const filledCount = grid
     ? grid.reduce((s, row) => s + row.filter(Boolean).length, 0)
     : 0;
 
   const activePieceCells = detectActivePieceCells(grid, settledGrid ?? null);
   const activePieceType = activePieceCells ? identifyPieceType(activePieceCells) : null;
   const completeRows = grid ? countCompleteRows(grid) : 0;
 
   return {
     grid,
     filledCount,
     filledInBottom(rows: number): number {
       if (!grid) return 0;
       let count = 0;
       const start = Math.max(0, grid.length - rows);
       for (let r = start; r < grid.length; r++) {
         for (let c = 0; c < grid[r].length; c++) {
           if (grid[r][c]) count++;
         }
       }
       return count;
     },
     hasFilledInTop(rows: number): boolean {
       if (!grid) return false;
       for (let r = 0; r < Math.min(rows, grid.length); r++) {
         for (let c = 0; c < grid[r].length; c++) {
           if (grid[r][c]) return true;
         }
       }
       return false;
     },
     completeRows,
     activePieceCells,
     activePieceType,
   };
 }
 
 // ---------------------------------------------------------------------------
 // Pure grid utility functions
 // ---------------------------------------------------------------------------
 
 function countCompleteRows(grid: Grid): number {
   let count = 0;
   for (const row of grid) {
     if (row.every(Boolean)) count++;
   }
   return count;
 }
 
 function detectActivePieceCells(
   current: Grid | null,
   settled: Grid | null
 ): [number, number][] | null {
   if (!current) return null;
 
   if (settled && settled.length === current.length) {
     const cells: [number, number][] = [];
     for (let row = 0; row < current.length; row++) {
       for (let col = 0; col < current[row].length; col++) {
         if (current[row][col] && !settled[row][col]) {
           cells.push([row, col]);
         }
       }
     }
     if (cells.length < 3 || cells.length > 5) return null;
     return cells;
   }
 
   // Fallback: find a connected 3-5 cell cluster in the top 4 rows.
   // (A fresh tetromino spawns at the top and forms a single connected
   // component; filled cells elsewhere are usually UI chrome or false
   // positives from canvas reading.)
   const topRows = Math.min(4, current.length);
   const filled: [number, number][] = [];
   for (let row = 0; row < topRows; row++) {
     for (let col = 0; col < current[row].length; col++) {
       if (current[row][col]) filled.push([row, col]);
     }
   }
   if (filled.length < 3) return null;
 
   // BFS to find connected components (4-connectivity)
   const key = (r: number, c: number) => `${r},${c}`;
   const filledSet = new Set(filled.map(([r, c]) => key(r, c)));
   const seen = new Set<string>();
   const components: [number, number][][] = [];
 
   for (const [r0, c0] of filled) {
     if (seen.has(key(r0, c0))) continue;
     const stack: [number, number][] = [[r0, c0]];
     const comp: [number, number][] = [];
     while (stack.length > 0) {
       const [r, c] = stack.pop()!;
       const k = key(r, c);
       if (seen.has(k)) continue;
       seen.add(k);
       comp.push([r, c]);
       for (const [dr, dc] of [[-1, 0], [1, 0], [0, -1], [0, 1]] as const) {
         const nr = r + dr, nc = c + dc;
         if (nr >= 0 && nr < topRows && nc >= 0 && current[nr] && nc < current[nr].length) {
           if (filledSet.has(key(nr, nc)) && !seen.has(key(nr, nc))) {
             stack.push([nr, nc]);
           }
         }
       }
     }
     components.push(comp);
   }
 
   // Pick the first component sized 3-5 (a tetromino). If several match,
   // prefer the one closest to the center column (spawn position).
   const tetrominoCandidates = components.filter((c) => c.length >= 3 && c.length <= 5);
   if (tetrominoCandidates.length === 0) return null;
 
   tetrominoCandidates.sort((a, b) => {
     const avgColA = a.reduce((s, [, c]) => s + c, 0) / a.length;
     const avgColB = b.reduce((s, [, c]) => s + c, 0) / b.length;
     const centerDistA = Math.abs(avgColA - 4.5);
     const centerDistB = Math.abs(avgColB - 4.5);
     return centerDistA - centerDistB;
   });
 
   return tetrominoCandidates[0];
 }
 
 function identifyPieceType(cells: [number, number][]): PieceType {
   if (cells.length !== 4) return "unknown";
 
   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));
   const w = maxCol - minCol + 1;
   const h = maxRow - minRow + 1;
 
   const norm = cells.map(([r, c]) => [r - minRow, c - minCol] as [number, number]);
   const key = norm
     .sort((a, b) => a[0] - b[0] || a[1] - b[1])
     .map(([r, c]) => `${r},${c}`)
     .join("|");
 
   if (w === 4 && h === 1) return "I";
   if (w === 1 && h === 4) return "I";
   if (w === 2 && h === 2) return "O";
 
   const tPatterns = [
     "0,0|0,1|0,2|1,1", "0,0|1,0|1,1|2,0", "0,1|1,0|1,1|1,2",
     "0,0|0,1|1,0|2,0", "0,1|1,0|1,1|2,1", "0,0|0,1|1,1|2,1",
   ];
   if (tPatterns.includes(key)) return "T";
 
   const sPatterns = ["0,1|0,2|1,0|1,1", "0,0|1,0|1,1|2,1"];
   if (sPatterns.includes(key)) return "S";
 
   const zPatterns = ["0,0|0,1|1,1|1,2", "0,1|1,0|1,1|2,0"];
   if (zPatterns.includes(key)) return "Z";
 
   const jPatterns = [
     "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,0|1,0|2,0|2,1", "0,1|1,1|2,0|2,1",
   ];
   if (jPatterns.includes(key)) return "J";
 
   const lPatterns = [
     "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",
   ];
   if (lPatterns.includes(key)) return "L";
 
   return "unknown";
 }
 
 // ---------------------------------------------------------------------------
 // Calibration cache helpers
 // ---------------------------------------------------------------------------
 
 function cloneCalibration(cal: DriverCalibration): DriverCalibration {
   const copy: DriverCalibration = {
     renderer: cal.renderer,
     gridDetected: cal.gridDetected,
     gridBounds: cal.gridBounds ? { ...cal.gridBounds } : null,
     cellWidth: cal.cellWidth,
     cellHeight: cal.cellHeight,
     controls: { ...cal.controls },
     controlMap: cal.controlMap ? cloneControlMap(cal.controlMap) : cal.controlMap ?? null,
     startMechanism: cal.startMechanism,
     scoreElementSelector: cal.scoreElementSelector,
     levelElementSelector: cal.levelElementSelector,
     backgroundColor: cal.backgroundColor ? [...cal.backgroundColor] as [number, number, number] : null,
     consoleErrors: [...cal.consoleErrors],
     gridConfidence: cal.gridConfidence,
     gridDetectedAt: cal.gridDetectedAt,
   };
   if (cal.startButton) {
     copy.startButton = {
       selector: cal.startButton.selector,
       text: cal.startButton.text,
       disappeared: cal.startButton.disappeared,
       position: { ...cal.startButton.position },
     };
   }
   return copy;
 }
 
 function cloneControlMap(map: ControlMap): ControlMap {
   return {
     move_left: { ...map.move_left },
     move_right: { ...map.move_right },
     soft_drop: { ...map.soft_drop },
     hard_drop: { ...map.hard_drop },
     rotate_cw: { ...map.rotate_cw },
     rotate_ccw: { ...map.rotate_ccw },
     key_observations: { ...map.key_observations },
   };
 }
 
 function gridBoundsSimilar(a: GridBounds, b: GridBounds): boolean {
   // Tolerate rendering jitter but flag anything beyond ~10% size change.
   const tol = Math.max(20, Math.min(a.width, b.width) * 0.15);
   return (
     Math.abs(a.x - b.x) < tol &&
     Math.abs(a.y - b.y) < tol &&
     Math.abs(a.width - b.width) < tol &&
     Math.abs(a.height - b.height) < tol
   );
 }
 
 /**
  * Returns a list of field names that differ between the baseline calibration
  * and a fresh one. Empty list means no drift detected.
  */
 function diffCalibrations(baseline: DriverCalibration, fresh: DriverCalibration): string[] {
   const changes: string[] = [];
 
   if (baseline.startMechanism !== fresh.startMechanism) {
     changes.push("start_mechanism");
   }
   const baseSel = baseline.startButton?.selector ?? null;
   const freshSel = fresh.startButton?.selector ?? null;
   if (baseSel !== freshSel) changes.push("start_button_selector");
 
   if (baseline.renderer !== fresh.renderer) changes.push("renderer");
 
   if (!!baseline.gridBounds !== !!fresh.gridBounds) {
     changes.push("grid_bounds");
   } else if (baseline.gridBounds && fresh.gridBounds) {
     if (!gridBoundsSimilar(baseline.gridBounds, fresh.gridBounds)) {
       changes.push("grid_bounds");
     }
   }
 
   const bc = baseline.controls;
   const fc = fresh.controls;
   if (bc.left !== fc.left || bc.right !== fc.right || bc.down !== fc.down ||
       bc.rotate !== fc.rotate || bc.drop !== fc.drop) {
     changes.push("controls");
   }
 
   if (baseline.scoreElementSelector !== fresh.scoreElementSelector) {
     changes.push("score_element");
   }
   if (baseline.levelElementSelector !== fresh.levelElementSelector) {
     changes.push("level_element");
   }
 
   return changes;
 }
 
 // ---------------------------------------------------------------------------
 // PlaywrightDriver
 // ---------------------------------------------------------------------------
 
 export class PlaywrightDriver implements TetrisDriver {
   private page: Page;
   private cal: DriverCalibration | null = null;
   // First successful calibration, used as the cache baseline across reloads.
   private firstCal: DriverCalibration | null = null;
   // Candidate confirmed by the bot's verification bridge. When set, calibrate()
   // replays this candidate instead of rediscovering the start mechanism.
   private confirmedCandidate: StartCandidate | null = null;
   // Set by the bot when bridge verification definitively failed -- the legacy
   // detectStartMechanism() fallback must NOT run and override the bot's verdict.
   private startRejected: boolean = false;
   // Result of discoverControls(). Persists across calibration cache hits so
   // downstream phases reuse the discovered mapping without re-running the
   // expensive discovery loop. null = not yet discovered.
   private discoveredControls: ControlMap | null = null;
   // Cumulative drift info across the session.
   private drift: CalibrationDrift = {
     drifted: false,
     changes: [],
     recalibrations: 0,
     cacheHits: 0,
     cacheMisses: 0,
   };
   private consoleErrors: string[] = [];
   private log = (msg: string) => console.log(`[driver] ${msg}`);
 
   // Inactivity watchdog: set by armInactivityWatchdog() once the game has
   // started and we expect regular grid reads. If more than
   // INACTIVITY_TIMEOUT_MS elapses without a successful grid read, readGrid
   // and wait() throw InactivityAbortError so the bot can exit fast and
   // still write whatever partial data it has.
   private watchdogArmed = false;
   private lastSuccessfulReadAt = 0;
   private static readonly INACTIVITY_TIMEOUT_MS = 120_000;
 
   constructor(page: Page) {
     this.page = page;
   }
 
   armInactivityWatchdog(): void {
     this.watchdogArmed = true;
     this.lastSuccessfulReadAt = Date.now();
   }
 
   private checkInactivity(): void {
     if (!this.watchdogArmed) return;
     const elapsed = Date.now() - this.lastSuccessfulReadAt;
     if (elapsed > PlaywrightDriver.INACTIVITY_TIMEOUT_MS) {
       throw new InactivityAbortError(
         `no successful grid read in ${Math.round(elapsed / 1000)}s (watchdog)`
       );
     }
   }
 
   // -- Lifecycle --
 
   async loadPage(url: string): Promise<{ loaded: boolean; detail: string; errorsOnLoad: number }> {
     this.consoleErrors = [];
     this.page.on("pageerror", (err) => {
       this.consoleErrors.push(err.message);
     });
 
     const errorsBefore = this.consoleErrors.length;
 
     try {
       const response = await this.page.goto(url, {
         timeout: 15000,
         waitUntil: "networkidle",
       });
       if (!response || !response.ok()) {
         return {
           loaded: false,
           detail: `page load failed: HTTP ${response?.status()}`,
           errorsOnLoad: this.consoleErrors.length - errorsBefore,
         };
       }
       await this.page.waitForTimeout(3000);
     } catch (err) {
       return {
         loaded: false,
         detail: `page load failed: ${err instanceof Error ? err.message : String(err)}`,
         errorsOnLoad: this.consoleErrors.length - errorsBefore,
       };
     }
 
     const newErrors = this.consoleErrors.slice(errorsBefore);
     return {
       loaded: true,
       detail: newErrors.length === 0
         ? "no console errors"
         : `${newErrors.length} console error(s): ${newErrors[0]}`,
       errorsOnLoad: newErrors.length,
     };
   }
 
   async surveyPage(): Promise<SurveyData> {
     try {
       return await this.page.evaluate(() => {
         let hasOverlay = false;
         const allEls = document.querySelectorAll("*");
         const vw = window.innerWidth;
         const vh = window.innerHeight;
         for (const el of allEls) {
           const style = window.getComputedStyle(el);
           const pos = style.position;
           if (pos === "fixed" || pos === "absolute") {
             const zIndex = parseInt(style.zIndex, 10);
             if (zIndex > 0 || style.zIndex === "auto") {
               const rect = (el as HTMLElement).getBoundingClientRect();
               if (rect.width > vw * 0.5 && rect.height > vh * 0.5) {
                 hasOverlay = true;
                 break;
               }
             }
           }
         }
 
         const hasCanvas = document.querySelectorAll("canvas").length > 0;
 
         let hasDomGrid = false;
         const containers = document.querySelectorAll(
           '[class*="board"], [class*="grid"], [class*="field"], [id*="board"], [id*="grid"], [id*="field"]'
         );
         for (const container of containers) {
           const ch = container.children;
           if (
             (ch.length >= 180 && ch.length <= 230) ||
             (ch.length >= 18 && ch.length <= 22 &&
               ch[0]?.children.length >= 8 && ch[0]?.children.length <= 12)
           ) {
             hasDomGrid = true;
             break;
           }
         }
         if (!hasDomGrid) {
           const tables = document.querySelectorAll("table");
           for (const table of tables) {
             const rows = table.querySelectorAll("tr");
             if (rows.length >= 18 && (rows[0]?.querySelectorAll("td").length ?? 0) >= 8) {
               hasDomGrid = true;
               break;
             }
           }
         }
         // Heuristic scan for unlabeled grids
         if (!hasDomGrid) {
           const allElements = document.querySelectorAll("div, section, main, article");
           for (const el of allElements) {
             const ch = el.children;
             if (ch.length >= 180 && ch.length <= 230) {
               const firstChild = ch[0] as HTMLElement;
               if (!firstChild) continue;
               const firstRect = firstChild.getBoundingClientRect();
               if (firstRect.width < 5 || firstRect.height < 5) continue;
               let uniform = true;
               for (let i = 1; i < Math.min(10, ch.length); i++) {
                 const r = (ch[i] as HTMLElement).getBoundingClientRect();
                 if (Math.abs(r.width - firstRect.width) > 2 || Math.abs(r.height - firstRect.height) > 2) {
                   uniform = false;
                   break;
                 }
               }
               if (uniform) { hasDomGrid = true; break; }
             }
             if (ch.length >= 18 && ch.length <= 22) {
               const firstRowCells = ch[0]?.children;
               if (firstRowCells && firstRowCells.length >= 8 && firstRowCells.length <= 12) {
                 const rect = el.getBoundingClientRect();
                 if (rect.width > 50 && rect.height > 100) { hasDomGrid = true; break; }
               }
             }
           }
         }
 
         const bodyText = (document.body?.innerText || "").trim();
         const visibleText = bodyText
           .split("\n")
           .map((line: string) => line.trim())
           .filter((line: string) => line.length > 0)
           .slice(0, 20);
 
         const clickableSelector =
           'button, a, [role="button"], [onclick], input[type="button"], input[type="submit"]';
         const clickableElements = document.querySelectorAll(clickableSelector).length;
 
         return { has_overlay: hasOverlay, has_canvas: hasCanvas, has_dom_grid: hasDomGrid, visible_text: visibleText, clickable_elements: clickableElements };
       });
     } catch {
       return { has_overlay: false, has_canvas: false, has_dom_grid: false, visible_text: [], clickable_elements: 0 };
     }
   }
 
   async detectGameLandmarks(): Promise<GameLandmarks> {
     return await this.page.evaluate(() => {
       const body = document.body;
       const bodyText = body?.innerText?.trim() || "";
       const bodyHasContent = body !== null &&
         (bodyText.length > 0 || body.children.length > 0);
 
       // Check for canvas
       const canvases = document.querySelectorAll("canvas");
       let hasCanvas = false;
       for (const c of canvases) {
         const rect = (c as HTMLCanvasElement).getBoundingClientRect();
         if (rect.width >= 50 && rect.height >= 50) {
           hasCanvas = true;
           break;
         }
       }
 
       // Check for named DOM grid containers
       const namedContainers = document.querySelectorAll(
         '[class*="board"], [class*="grid"], [class*="field"], [id*="board"], [id*="grid"]'
       );
       let hasDomGrid = false;
       for (const el of namedContainers) {
         const rect = (el as HTMLElement).getBoundingClientRect();
         if (rect.width >= 50 && rect.height >= 50) {
           hasDomGrid = true;
           break;
         }
       }
 
       // Check for tetris-grid-aspect element (2:1 height:width)
       let hasTetrisRatioElement = false;
       const allElements = document.querySelectorAll("div, section, main, article");
       for (const el of allElements) {
         const rect = (el as HTMLElement).getBoundingClientRect();
         if (rect.width < 100 || rect.height < 200) continue;
         const ratio = rect.height / rect.width;
         if (ratio >= 1.5 && ratio <= 2.5) {
           hasTetrisRatioElement = true;
           break;
         }
       }
 
       // Check for large container with many same-sized children
       let hasManyCellsContainer = false;
       for (const el of allElements) {
         const children = el.children;
         if (children.length < 50 || children.length > 400) continue;
         const sizes = new Set<string>();
         const sampleCount = Math.min(10, children.length);
         for (let i = 0; i < sampleCount; i++) {
           const child = children[Math.floor(i * children.length / sampleCount)] as HTMLElement;
           const r = child.getBoundingClientRect();
           if (r.width > 0 && r.height > 0) {
             sizes.add(`${Math.round(r.width)}x${Math.round(r.height)}`);
           }
         }
         if (sizes.size <= 3 && sizes.size > 0) {
           hasManyCellsContainer = true;
           break;
         }
       }
 
       const landmarksFound: string[] = [];
       if (bodyHasContent) landmarksFound.push("body_content");
       if (hasCanvas) landmarksFound.push("canvas");
       if (hasDomGrid) landmarksFound.push("dom_grid");
       if (hasTetrisRatioElement) landmarksFound.push("tetris_ratio");
       if (hasManyCellsContainer) landmarksFound.push("cells_container");
 
       return {
         bodyHasContent,
         hasCanvas,
         hasDomGrid,
         hasTetrisRatioElement,
         hasManyCellsContainer,
         landmarksFound,
       };
     });
   }
 
   async calibrate(): Promise<DriverCalibration> {
     // Fast path: try applying the cached calibration from a prior run.
     if (this.firstCal) {
       this.drift.recalibrations++;
       const cached = await this.applyCachedCalibration();
       if (cached) {
         this.drift.cacheHits++;
         this.cal = cached;
         this.log(
           `[cache] hit: replayed start="${cached.startMechanism}" renderer=${cached.renderer} ` +
           `(hits=${this.drift.cacheHits}, misses=${this.drift.cacheMisses})`
         );
         return cached;
       }
       this.drift.cacheMisses++;
       this.log(
         `[cache] miss: cached calibration no longer works, doing full recalibration ` +
         `(hits=${this.drift.cacheHits}, misses=${this.drift.cacheMisses})`
       );
     }
 
     const fresh = await this.fullCalibrate();
     this.cal = fresh;
 
     if (!this.firstCal) {
       // First time -- freeze a copy as the baseline for drift detection.
       this.firstCal = cloneCalibration(fresh);
     } else {
       // Not the first time: compute drift vs baseline.
       const changes = diffCalibrations(this.firstCal, fresh);
       if (changes.length > 0) {
         this.drift.drifted = true;
         for (const c of changes) {
           if (!this.drift.changes.includes(c)) this.drift.changes.push(c);
         }
         this.log(`CONFLICT: calibration drifted: [${changes.join(", ")}]`);
       }
     }
 
     return fresh;
   }
 
   // Runs the full (expensive) calibration flow. Does not touch firstCal/drift.
   private async fullCalibrate(): Promise<DriverCalibration> {
     await this.page.waitForTimeout(2000);
 
     let startMechanism: StartMechanism;
     let startButton: DriverCalibration["startButton"] | undefined;
 
     if (this.confirmedCandidate) {
       // Bot already verified the start. Replay it instead of rediscovering.
       this.log(
         `[bridge] replaying confirmed candidate: ${this.confirmedCandidate.label}`
       );
       const applied = await this.applyCandidate(this.confirmedCandidate);
       startMechanism = applied.ok ? this.confirmedCandidate.mechanism : "unknown";
       if (applied.ok && (this.confirmedCandidate.mechanism === "button" || this.confirmedCandidate.mechanism === "click_canvas")) {
         startButton = {
           selector: this.confirmedCandidate.selector ?? "canvas",
           text: this.confirmedCandidate.text ?? this.confirmedCandidate.label,
           disappeared: false,
           position: this.confirmedCandidate.position ?? { x: 0, y: 0 },
         };
       }
       await this.page.waitForTimeout(this.confirmedCandidate.waitMs ?? 400);
     } else if (this.startRejected) {
       // Bot's bridge verification rejected every candidate. Do NOT run the
       // legacy fallback; it has historically produced false positives
       // (e.g. clicking Pause) that the bridge was designed to prevent.
       this.log(`[bridge] start rejected by bot; skipping legacy detection`);
       startMechanism = "unknown";
       startButton = undefined;
     } else {
       const startResult = await this.detectStartMechanism();
       startMechanism = startResult.mechanism;
       startButton = startResult.startButton;
     }
 
     let gridDetection = await this.detectGrid();
     let { renderer, gridBounds, cellWidth, cellHeight } = gridDetection;
     let backgroundColor =
       renderer === "canvas" && gridBounds
         ? await this.sampleBackgroundColor(gridBounds, cellWidth, cellHeight)
         : null;
 
     // Re-calibration fallback (skipped when bot already confirmed or rejected the start).
     if (!this.confirmedCandidate && !this.startRejected && (startMechanism === "unknown" || gridBounds === null)) {
       const retry = await this.recalibrateWithRetry(startMechanism, gridBounds);
       if (retry.startMechanism !== "unknown") startMechanism = retry.startMechanism;
       if (retry.startButton) startButton = retry.startButton;
       if (retry.gridBounds) {
         renderer = retry.renderer;
         gridBounds = retry.gridBounds;
         cellWidth = retry.cellWidth;
         cellHeight = retry.cellHeight;
         backgroundColor =
           renderer === "canvas" && gridBounds
             ? await this.sampleBackgroundColor(gridBounds, cellWidth, cellHeight)
             : null;
       }
     }
 
     const controls = await this.detectControls();
     const scoreElementSelector = await this.detectScoreElement();
     const levelElementSelector = await this.detectLevelElement();
 
     const gridConfidence = await this.measureGridConfidence({
       renderer, gridDetected: gridBounds !== null, gridBounds, cellWidth, cellHeight,
       controls, startMechanism, scoreElementSelector, levelElementSelector,
       backgroundColor, consoleErrors: [...this.consoleErrors], gridConfidence: 0,
       gridDetectedAt: "initial",
     });
 
     const cal: DriverCalibration = {
       renderer,
       gridDetected: gridBounds !== null,
       gridBounds,
       cellWidth,
       cellHeight,
       controls,
       startMechanism,
       scoreElementSelector,
       levelElementSelector,
       backgroundColor,
       consoleErrors: [...this.consoleErrors],
       gridConfidence,
       gridDetectedAt: "initial",
     };
 
     if (startButton) cal.startButton = startButton;
     return cal;
   }
 
   /**
    * Attempt to replay the cached calibration on the current page.
    * Returns a completed DriverCalibration on success, null on failure.
    * On success, the game should be started and the grid detected.
    */
   private async applyCachedCalibration(): Promise<DriverCalibration | null> {
     const base = this.firstCal;
     if (!base) return null;
 
     try {
       // Small settle delay -- a freshly-loaded page may still be booting.
       await this.page.waitForTimeout(800);
 
       // Step 1: re-apply the cached start mechanism.
       const started = await this.replayStartMechanism(base);
       if (!started) {
         this.log(
           `CONFLICT: cached start mechanism '${base.startMechanism}` +
           (base.startButton ? ` ${base.startButton.selector}` : "") +
           `' no longer works`
         );
         return null;
       }
 
       // Step 2: verify the grid is back (same renderer, similar bounds).
       await this.page.waitForTimeout(300);
       const grid = await this.detectGrid();
       if (!grid.gridBounds) {
         this.log("CONFLICT: cached start worked but no grid detected");
         return null;
       }
       if (base.gridBounds && !gridBoundsSimilar(base.gridBounds, grid.gridBounds)) {
         this.log(
           `CONFLICT: grid bounds changed significantly ` +
           `(was ${JSON.stringify(base.gridBounds)}, now ${JSON.stringify(grid.gridBounds)})`
         );
         return null;
       }
       if (base.renderer !== "unknown" && grid.renderer !== base.renderer) {
         this.log(`CONFLICT: renderer changed from ${base.renderer} to ${grid.renderer}`);
         return null;
       }
 
       const backgroundColor =
         grid.renderer === "canvas" && grid.gridBounds
           ? await this.sampleBackgroundColor(grid.gridBounds, grid.cellWidth, grid.cellHeight)
           : base.backgroundColor;
 
       const cal: DriverCalibration = {
         renderer: grid.renderer,
         gridDetected: true,
         gridBounds: grid.gridBounds,
         cellWidth: grid.cellWidth,
         cellHeight: grid.cellHeight,
         controls: { ...base.controls },
         controlMap: base.controlMap ? cloneControlMap(base.controlMap) : null,
         startMechanism: base.startMechanism,
         scoreElementSelector: base.scoreElementSelector,
         levelElementSelector: base.levelElementSelector,
         backgroundColor,
         consoleErrors: [...this.consoleErrors],
         gridConfidence: base.gridConfidence,
         gridDetectedAt: "initial",
         fromCache: true,
       };
       if (base.startButton) cal.startButton = { ...base.startButton };
       return cal;
     } catch (err) {
       this.log(
         `[cache] replay threw: ${err instanceof Error ? err.message : String(err)}`
       );
       return null;
     }
   }
 
   /**
    * Perform the cached start action. Returns true if a visual change occurred.
    */
   private async replayStartMechanism(base: DriverCalibration): Promise<boolean> {
     try {
       const before = await this.page.screenshot();
 
       switch (base.startMechanism) {
         case "auto":
           // Nothing to replay -- game should already be running.
           await this.page.waitForTimeout(400);
           break;
         case "enter":
           await this.page.keyboard.press("Enter");
           break;
         case "space":
           await this.page.keyboard.press("Space");
           break;
         case "anykey":
           await this.page.keyboard.press("ArrowDown");
           break;
         case "click_canvas": {
           const pos = base.startButton?.position;
           if (pos) {
             await this.page.mouse.click(pos.x, pos.y);
           } else {
             const canvas = this.page.locator("canvas").first();
             if ((await canvas.count()) > 0) await canvas.click();
             else return false;
           }
           break;
         }
         case "button": {
           // Prefer the cached selector; fall back to coordinate click.
           let clicked = false;
           const sel = base.startButton?.selector;
           if (sel) {
             try {
               const locator = this.page.locator(sel).first();
               const count = await locator.count();
               if (count > 0) {
                 await locator.click({ timeout: 2000 });
                 clicked = true;
               }
             } catch { /* fall through to coordinate click */ }
           }
           if (!clicked && base.startButton?.position) {
             const pos = base.startButton.position;
             await this.page.mouse.click(pos.x, pos.y);
             clicked = true;
           }
           if (!clicked) return false;
           break;
         }
         default:
           return false;
       }
 
       await this.page.waitForTimeout(500);
 
       // For auto-start, we already have no input -- just verify something changed
       // relative to the blank/initial page state.
       if (base.startMechanism === "auto") {
         const after = await this.page.screenshot();
         return !before.equals(after);
       }
 
       // For the other mechanisms, a visual change after the action is the signal.
       const result = await this.detectVisualChange({ frames: 3, intervalMs: 100, before });
       return result.changed;
     } catch {
       return false;
     }
   }
 
   async recalibrate(): Promise<DriverCalibration> {
     const prev = this.cal;
     await this.page.waitForTimeout(500);
 
     const gridDetection = await this.detectGrid();
     if (gridDetection.gridBounds && prev) {
       const backgroundColor =
         gridDetection.renderer === "canvas" && gridDetection.gridBounds
           ? await this.sampleBackgroundColor(gridDetection.gridBounds, gridDetection.cellWidth, gridDetection.cellHeight)
           : null;
 
       this.cal = {
         ...prev,
         renderer: gridDetection.renderer,
         gridDetected: true,
         gridBounds: gridDetection.gridBounds,
         cellWidth: gridDetection.cellWidth,
         cellHeight: gridDetection.cellHeight,
         backgroundColor,
         gridDetectedAt: "after_start",
       };
     } else if (!prev) {
       return this.calibrate();
     }
 
     return this.cal!;
   }
 
   /**
    * Lightweight grid re-detection without any side effects. Unlike
    * recalibrate() / calibrate(), this never clicks, presses keys, or
    * runs detectStartMechanism(). Safe to call from verifyGameStarted()
    * mid-start-discovery -- if the page has since spawned its grid (e.g.
    * a DOM game that builds cells inside requestAnimationFrame after a
    * start button click), the cached calibration gets updated; otherwise
    * this.cal is left untouched.
    */
   async refreshGridDetection(): Promise<void> {
     // Short settle delay: some games build their grid inside the first few
     // animation frames after startGame() runs, so the initial detectGrid()
     // inside tryStartMechanism() may have fired before the DOM was ready.
     await this.page.waitForTimeout(200);
     const gridDetection = await this.detectGrid();
     if (!gridDetection.gridBounds) return;
 
     const backgroundColor =
       gridDetection.renderer === "canvas"
         ? await this.sampleBackgroundColor(
             gridDetection.gridBounds,
             gridDetection.cellWidth,
             gridDetection.cellHeight
           )
         : null;
 
     if (this.cal) {
       this.cal = {
         ...this.cal,
         renderer: gridDetection.renderer,
         gridDetected: true,
         gridBounds: gridDetection.gridBounds,
         cellWidth: gridDetection.cellWidth,
         cellHeight: gridDetection.cellHeight,
         backgroundColor,
         gridDetectedAt: "after_start",
       };
     } else {
       this.cal = {
         renderer: gridDetection.renderer,
         gridDetected: true,
         gridBounds: gridDetection.gridBounds,
         cellWidth: gridDetection.cellWidth,
         cellHeight: gridDetection.cellHeight,
         controls: { ...DEFAULT_CONTROLS },
         startMechanism: "unknown",
         scoreElementSelector: null,
         levelElementSelector: null,
         backgroundColor,
         consoleErrors: [...this.consoleErrors],
         gridConfidence: 0,
         gridDetectedAt: "after_start",
       };
     }
   }
 
   getCalibration(): DriverCalibration {
     if (!this.cal) throw new Error("calibrate() must be called before getCalibration()");
     return this.cal;
   }
 
   getCalibrationDrift(): CalibrationDrift {
     return {
       drifted: this.drift.drifted,
       changes: [...this.drift.changes],
       recalibrations: this.drift.recalibrations,
       cacheHits: this.drift.cacheHits,
       cacheMisses: this.drift.cacheMisses,
     };
   }
 
   // -- Start-mechanism verification bridge --
   //
   // The bot drives start detection explicitly via this trio:
   //   1. discoverStartCandidates() -- returns ordered list
   //   2. tryStartMechanism(candidate) -- applies one, reports deltas
   //   3. confirmStartMechanism(candidate) -- commits after bot verification
   //
   // Unlike detectStartMechanism(), tryStartMechanism() does NOT judge the
   // outcome. It only reports observable deltas so the bot can run its own
   // gameplay-based checks before committing.
 
   async discoverStartCandidates(): Promise<StartCandidate[]> {
     const candidates: StartCandidate[] = [];
 
     // 1. Auto-start: no action, just wait briefly.
     candidates.push({
       mechanism: "auto",
       label: "auto-start (wait 1.2s)",
       waitMs: 1200,
     });
 
     // 2. DOM buttons, sorted by prominence (start-ish first, disabled/pause-ish last).
     try {
       const buttons = await this.collectButtonCandidates();
       for (const b of buttons) {
         // Skip disabled buttons -- they cannot start a game.
         if (b.disabled) continue;
         candidates.push({
           mechanism: "button",
           label: `button "${b.text || b.selector}"`,
           selector: b.selector,
           text: b.text,
           position: { x: b.x, y: b.y },
         });
       }
     } catch { /* no buttons */ }
 
     // 3. Keyboard triggers.
     candidates.push({ mechanism: "enter", label: "key Enter", key: "Enter" });
     candidates.push({ mechanism: "space", label: "key Space", key: "Space" });
     candidates.push({ mechanism: "anykey", label: "key ArrowDown", key: "ArrowDown" });
 
     // 4. Canvas clicks (if a canvas exists).
     try {
       const canvas = this.page.locator("canvas").first();
       if ((await canvas.count()) > 0) {
         const box = await canvas.boundingBox();
         if (box) {
           const cx = box.x + box.width / 2;
           const cy = box.y + box.height / 2;
           candidates.push({
             mechanism: "click_canvas",
             label: "canvas click center",
             position: { x: Math.round(cx), y: Math.round(cy) },
           });
           candidates.push({
             mechanism: "click_canvas",
             label: "canvas click upper",
             position: { x: Math.round(cx), y: Math.round(box.y + box.height * 0.25) },
           });
           candidates.push({
             mechanism: "click_canvas",
             label: "canvas click lower",
             position: { x: Math.round(cx), y: Math.round(box.y + box.height * 0.75) },
           });
         }
       }
     } catch { /* no canvas */ }
 
     return candidates;
   }
 
   async tryStartMechanism(candidate: StartCandidate): Promise<TryStartResult> {
     const errorsBefore = this.consoleErrors.length;
 
     let before: Buffer | null = null;
     let domBefore = "";
     let clickableBefore = 0;
     try {
       before = await this.page.screenshot();
       const snap = await this.snapshotDomState();
       domBefore = snap.domKey;
       clickableBefore = snap.clickableCount;
     } catch { /* screenshot can fail on teardown */ }
 
     let applied = { ok: false };
     try {
       applied = await this.applyCandidate(candidate);
     } catch { /* treat as not applied */ }
 
     if (!applied.ok) {
       return {
         visualChanged: false,
         domChanged: false,
         errorOccurred: this.consoleErrors.length > errorsBefore,
         newClickableElements: 0,
         removedElements: 0,
       };
     }
 
     // Give the game a moment to react.
     await this.page.waitForTimeout(candidate.waitMs ?? 300);
 
     let visualChanged = false;
     let domChanged = false;
     let newClickableElements = 0;
     let removedElements = 0;
 
     try {
       if (before) {
         const after = await this.page.screenshot();
         visualChanged = !before.equals(after);
       }
       const snap = await this.snapshotDomState();
       domChanged = snap.domKey !== domBefore;
       const delta = snap.clickableCount - clickableBefore;
       if (delta > 0) newClickableElements = delta;
       else if (delta < 0) removedElements = -delta;
     } catch { /* report what we have */ }
 
     // Populate a minimal calibration so verifyGameStarted can call readGrid().
     // The bot may reject this candidate, in which case clearConfirmedStartMechanism()
     // will wipe this.cal along with the rest of the bridge state.
     try {
       const gridDetection = await this.detectGrid();
       if (gridDetection.gridBounds) {
         const backgroundColor =
           gridDetection.renderer === "canvas"
             ? await this.sampleBackgroundColor(
                 gridDetection.gridBounds,
                 gridDetection.cellWidth,
                 gridDetection.cellHeight
               )
             : null;
         this.cal = {
           renderer: gridDetection.renderer,
           gridDetected: true,
           gridBounds: gridDetection.gridBounds,
           cellWidth: gridDetection.cellWidth,
           cellHeight: gridDetection.cellHeight,
           controls: { ...DEFAULT_CONTROLS },
           startMechanism: candidate.mechanism,
           scoreElementSelector: null,
           levelElementSelector: null,
           backgroundColor,
           consoleErrors: [...this.consoleErrors],
           gridConfidence: 0,
           gridDetectedAt: "after_start",
         };
       }
     } catch { /* no grid detected yet */ }
 
     return {
       visualChanged,
       domChanged,
       errorOccurred: this.consoleErrors.length > errorsBefore,
       newClickableElements,
       removedElements,
     };
   }
 
   confirmStartMechanism(candidate: StartCandidate): void {
     this.confirmedCandidate = candidate;
     this.startRejected = false;
     this.log(`[bridge] confirmed start candidate: ${candidate.label}`);
   }
 
   clearConfirmedStartMechanism(): void {
     if (this.confirmedCandidate) {
       this.log(`[bridge] cleared confirmed start candidate`);
     }
     this.confirmedCandidate = null;
     // Drop cached calibrations so a reload starts fresh.
     this.firstCal = null;
     this.cal = null;
   }
 
   rejectStartMechanism(): void {
     this.startRejected = true;
     this.confirmedCandidate = null;
     // Drop cached calibrations; subsequent calibrate() calls must run fresh
     // but MUST NOT attempt any start detection.
     this.firstCal = null;
     this.cal = null;
     this.log(`[bridge] start mechanism rejected by bot`);
   }
 
   /** Shared helper: apply a candidate without judging the outcome. */
   private async applyCandidate(candidate: StartCandidate): Promise<{ ok: boolean }> {
     try {
       switch (candidate.mechanism) {
         case "auto":
           // Nothing to click/press; the wait happens in tryStartMechanism.
           return { ok: true };
         case "enter":
         case "space":
         case "anykey": {
           const key = candidate.key
             ?? (candidate.mechanism === "enter" ? "Enter"
               : candidate.mechanism === "space" ? "Space"
               : "ArrowDown");
           await this.page.keyboard.press(key);
           return { ok: true };
         }
         case "button": {
           const sel = candidate.selector;
           let clicked = false;
           if (sel) {
             try {
               const locator = this.page.locator(sel).first();
               if ((await locator.count()) > 0) {
                 await locator.click({ timeout: 2000 });
                 clicked = true;
               }
             } catch { /* fall through */ }
           }
           if (!clicked && candidate.position) {
             await this.page.mouse.click(candidate.position.x, candidate.position.y);
             clicked = true;
           }
           return { ok: clicked };
         }
         case "click_canvas": {
           if (candidate.position) {
             await this.page.mouse.click(candidate.position.x, candidate.position.y);
             return { ok: true };
           }
           const canvas = this.page.locator("canvas").first();
           if ((await canvas.count()) > 0) {
             await canvas.click();
             return { ok: true };
           }
           return { ok: false };
         }
         default:
           return { ok: false };
       }
     } catch {
       return { ok: false };
     }
   }
 
   /**
    * DOM snapshot used to cheaply detect whether tryStartMechanism() caused
    * meaningful structural changes on the page.
    */
   private async snapshotDomState(): Promise<{ domKey: string; clickableCount: number }> {
     try {
       return await this.page.evaluate(() => {
         const clickableSelector =
           'button, a, [role="button"], [onclick], input[type="button"], input[type="submit"]';
         const clickable = document.querySelectorAll(clickableSelector);
         const clickableCount = clickable.length;
 
         // Compact key describing the interactive skeleton.
         const parts: string[] = [];
         clickable.forEach((el, i) => {
           if (i > 40) return;
           const rect = (el as HTMLElement).getBoundingClientRect();
           parts.push(
             `${el.tagName.toLowerCase()}:${(el.textContent || "").trim().slice(0, 20)}:${Math.round(rect.width)}x${Math.round(rect.height)}`
           );
         });
         const canvasCount = document.querySelectorAll("canvas").length;
         parts.push(`canvas=${canvasCount}`);
 
         // Also include a short excerpt of body text so things like "Paused"
         // toggling to "Game Over" register as changes.
         const bodyText = (document.body?.innerText || "")
           .replace(/\s+/g, " ")
           .trim()
           .slice(0, 300);
         parts.push(`body=${bodyText}`);
 
         return { domKey: parts.join("|"), clickableCount };
       });
     } catch {
       return { domKey: "", clickableCount: 0 };
     }
   }
 
   /**
    * Return clickable elements sorted by prominence. Used by
    * discoverStartCandidates(). Boosts "start"-like labels and demotes
    * "pause"-like labels.
    */
   private async collectButtonCandidates(): Promise<Array<{
     text: string; selector: string; x: number; y: number; disabled: boolean;
   }>> {
     return await this.page.evaluate(() => {
       const seen = new Set<Element>();
       const results: Array<{
         index: number; text: string; x: number; y: number;
         width: number; height: number; area: number; centerDist: number;
         selector: string; hasBackground: boolean; disabled: boolean;
       }> = [];
 
       const clickableSelector =
         'button, a, [role="button"], [onclick], input[type="button"], input[type="submit"]';
       for (const el of document.querySelectorAll(clickableSelector)) {
         if (!seen.has(el)) seen.add(el);
       }
 
       const allEls = document.querySelectorAll("*");
       for (const el of allEls) {
         if (seen.has(el)) continue;
         try {
           const style = window.getComputedStyle(el);
           if (style.cursor === "pointer") seen.add(el);
         } catch { /* skip */ }
       }
 
       const pageW = window.innerWidth;
       const pageH = window.innerHeight;
       const pageCenterX = pageW / 2;
       const pageCenterY = pageH / 2;
 
       let idx = 0;
       for (const el of seen) {
         const rect = el.getBoundingClientRect();
         if (rect.width < 5 || rect.height < 5) continue;
         // Skip elements that are far outside the document (negative coords or
         // > 3x the viewport) but allow buttons that are below the fold -- we
         // use locator.click() which scrolls them into view.
         if (rect.top < -200 || rect.left < -200) continue;
         if (rect.top > pageH * 3 || rect.left > pageW * 3) continue;
         if (rect.width > pageW * 0.8 && rect.height > pageH * 0.8) continue;
 
         const cx = rect.left + rect.width / 2;
         const cy = rect.top + rect.height / 2;
         const centerDist = Math.sqrt((cx - pageCenterX) ** 2 + (cy - pageCenterY) ** 2);
 
         let hasBackground = false;
         try {
           const style = window.getComputedStyle(el as HTMLElement);
           const bg = style.backgroundColor;
           if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") hasBackground = true;
         } catch { /* skip */ }
 
         // Check for a stable id or class selector; disabled buttons are still
         // surfaced so the bot can verify that clicking them doesn't start
         // the game (fail fast on false positives).
         const disabled = (el as HTMLInputElement).disabled === true
           || el.getAttribute("aria-disabled") === "true";
 
         let selector = "";
         if (el.id) selector = `#${el.id}`;
         else if ((el as HTMLElement).className) {
           const cls = (el as HTMLElement).className.toString().split(" ")[0];
           if (cls) selector = `${el.tagName.toLowerCase()}.${cls}`;
         }
         if (!selector) selector = `${el.tagName.toLowerCase()}:nth-of-type(${idx + 1})`;
 
         results.push({
           index: idx, text: (el.textContent || "").trim().slice(0, 50),
           x: Math.round(cx), y: Math.round(cy),
           width: rect.width, height: rect.height,
           area: rect.width * rect.height, centerDist, selector, hasBackground,
           disabled,
         });
         idx++;
       }
 
       // Sort: prefer "start"-like labels first, "pause"/"restart"-like last,
       // disabled elements demoted, then prominence.
       const isStartish = (text: string): number => {
         const t = text.toLowerCase();
         if (/\bstart\b|\bplay\b|\bbegin\b|\bgo\b|\binicio\b|\bjugar\b|\bempezar\b|\bcomenzar\b|\bnueva\b|new game/.test(t)) return 0;
         if (/\brestart\b|\breset\b|\bplay again\b/.test(t)) return 2;
         if (/\bpause\b|\bstop\b|\bquit\b|\bexit\b|\bpausa\b|\bsalir\b/.test(t)) return 3;
         return 1;
       };
 
       results.sort((a, b) => {
         const ai = isStartish(a.text);
         const bi = isStartish(b.text);
         if (ai !== bi) return ai - bi;
         if (a.disabled !== b.disabled) return a.disabled ? 1 : -1;
         if (a.hasBackground !== b.hasBackground) return a.hasBackground ? -1 : 1;
         if (Math.abs(b.area - a.area) > 100) return b.area - a.area;
         return a.centerDist - b.centerDist;
       });
 
       return results.map(r => ({
         text: r.text, selector: r.selector, x: r.x, y: r.y, disabled: r.disabled,
       }));
     });
   }
 
   // -- Grid Reading --
 
   async readGrid(settledGrid?: Grid | null): Promise<GridSnapshot> {
     this.checkInactivity();
     try {
       const cal = this.cal;
       if (!cal) return makeSnapshot(null);
 
       let grid: Grid | null = null;
 
       if (cal.renderer === "canvas" && cal.gridBounds) {
         grid = await this.readCanvasGrid(cal.gridBounds, cal.cellWidth, cal.cellHeight, cal.backgroundColor);
       }
       if (!grid && cal.renderer === "dom") {
         grid = await this.readDomGrid();
       }
       if (!grid && cal.gridBounds) {
         grid = await this.readCanvasGrid(cal.gridBounds, cal.cellWidth, cal.cellHeight, cal.backgroundColor);
       }
       if (!grid) {
         grid = await this.readDomGrid();
       }
 
       if (grid) this.lastSuccessfulReadAt = Date.now();
       return makeSnapshot(grid, settledGrid);
     } catch (err) {
       if (err instanceof InactivityAbortError) throw err;
       return makeSnapshot(null);
     }
   }
 
   gridsAreDifferent(a: Grid | null, b: Grid | null): boolean {
     if (a === null || b === null) return a !== b;
     if (a.length !== b.length) return true;
     for (let r = 0; r < a.length; r++) {
       if (a[r].length !== b[r].length) return true;
       for (let c = 0; c < a[r].length; c++) {
         if (a[r][c] !== b[r][c]) return true;
       }
     }
     return false;
   }
 
   // -- Input --
 
   async pressKey(action: "left" | "right" | "down" | "rotate" | "drop"): Promise<void> {
     // Prefer the discovered control map when available, falling back to the
     // legacy controls field. If the discovered soft_drop is null (no soft
     // drop on this game), pressing "down" becomes a no-op -- callers that
     // care about distinguishing the two should check getControl("soft_drop")
     // first.
     const discovered = this.discoveredControls;
     if (discovered) {
       const mapped = this.mapLegacyActionToDiscovered(action, discovered);
       if (mapped === null) {
         // Explicit no-op: the game doesn't have this action. We still swallow
         // the call silently rather than throwing so the bot's play loops that
         // sprinkle in optional soft_drop presses don't crash.
         return;
       }
       if (mapped !== undefined) {
         await this.page.keyboard.press(mapped);
         return;
       }
     }
     const cal = this.cal;
     const key = cal ? cal.controls[action] : DEFAULT_CONTROLS[action];
     await this.page.keyboard.press(key);
   }
 
   /**
    * Translate the legacy pressKey action names to the discovered control map.
    * Returns:
    *  - a string key if discovered and valid
    *  - null if the action maps to soft_drop and soft_drop is explicitly
    *    not_found (no-op signal)
    *  - undefined if no discovery info for this action (caller falls back)
    */
   private mapLegacyActionToDiscovered(
     action: "left" | "right" | "down" | "rotate" | "drop",
     map: ControlMap
   ): string | null | undefined {
     switch (action) {
       case "left":
         return map.move_left.key ?? undefined;
       case "right":
         return map.move_right.key ?? undefined;
       case "down":
         // Distinguish "discovery ran and found no soft drop" from "discovery
         // never ran for this action". The first returns null (no-op), the
         // second returns undefined (fall through to defaults).
         if (map.soft_drop.confidence === "not_found") return null;
         return map.soft_drop.key ?? undefined;
       case "rotate":
         return map.rotate_cw.key ?? undefined;
       case "drop":
         return map.hard_drop.key ?? undefined;
     }
   }
 
   async pressRawKey(key: string): Promise<void> {
     await this.page.keyboard.press(key);
   }
 
   // -- Control discovery --
 
   getControl(action: GameAction): string | null {
     const map = this.discoveredControls;
     if (map) {
       switch (action) {
         case "move_left": return map.move_left.key;
         case "move_right": return map.move_right.key;
         case "soft_drop": return map.soft_drop.key;
         case "hard_drop": return map.hard_drop.key;
         case "rotate_cw": return map.rotate_cw.key;
         case "rotate_ccw": return map.rotate_ccw.key;
         case "pause": return null;
         case "hold": return null;
       }
     }
     // Fallback to legacy controls field.
     const cal = this.cal;
     const controls = cal ? cal.controls : DEFAULT_CONTROLS;
     switch (action) {
       case "move_left": return controls.left;
       case "move_right": return controls.right;
       case "soft_drop": return controls.down;
       case "hard_drop": return controls.drop;
       case "rotate_cw": return controls.rotate;
       case "rotate_ccw": return null;
       case "pause": return null;
       case "hold": return null;
     }
   }
 
   /**
    * Discover the control mapping by pressing candidate keys and watching
    * grid deltas. This is expensive (can reload the page several times) so
    * callers should only invoke it once per session.
    *
    * The result is cached on the driver and flows through getControl() and
    * pressKey() from the moment it returns.
    */
   async discoverControls(serverUrl: string): Promise<ControlMap> {
     const log = (msg: string) => console.log(`[discover] ${msg}`);
     // 50s hard budget. Discovery happens between bridge verification and the
     // first test phase, so we want to be quick. Each reload costs ~2s, so
     // this is ~25 reloads max.
     const deadline = Date.now() + 50_000;
     const budgetExceeded = () => Date.now() >= deadline;
 
     // Start from an empty map. If any key probe fails, we simply leave that
     // slot as "not_found" with no observation.
     const map = emptyControlMap();
 
     // IMPORTANT: tests run after discovery expect the driver state to
     // resemble "game freshly started". Discovery is destructive (it presses
     // keys, stacks pieces, may even trigger game_over), so we always
     // RELOAD between discovery trials and after discovery finishes.
 
     // Helper: reload the page, re-apply the confirmed start, and wait for
     // a piece to become observable.
     const freshStart = async (): Promise<GridSnapshot | null> => {
       try {
         await this.loadPage(serverUrl);
       } catch {
         return null;
       }
       try {
         // calibrate() will replay the confirmed candidate (if one is set)
         // and populate this.cal. Discovery runs AFTER bridge verification,
         // so confirmedCandidate is already committed at this point.
         await this.calibrate();
       } catch {
         return null;
       }
       // Grid might still be spawning; give it a brief window.
       await this.wait(300);
       // Fall back to refresh in case the grid wasn't detected at the first
       // calibrate() pass (DOM games that build cells post-click).
       if (!this.cal?.gridDetected) {
         try {
           await this.refreshGridDetection();
         } catch { /* ignore */ }
       }
       // Poll for an active piece so the delta classification works.
       const emptyGrid: Grid = Array.from({ length: GRID_ROWS }, () =>
         Array.from({ length: GRID_COLS }, () => false)
       );
       let snap = await this.readGrid(emptyGrid);
       let tries = 0;
       while ((!snap.grid || snap.filledCount === 0) && tries < 20) {
         await this.wait(100);
         snap = await this.readGrid(emptyGrid);
         tries++;
       }
       if (!snap.grid) return null;
       return snap;
     };
 
     // Helper: classify the delta between two grids.
     // Returns a label indicating what probably happened, or "no_change".
     const classifyDelta = (
       before: Grid,
       after: Grid
     ):
       | { kind: "no_change" }
       | { kind: "move_left"; distance: number }
       | { kind: "move_right"; distance: number }
       | { kind: "move_down"; distance: number }
       | { kind: "hard_drop"; distance: number }
       | { kind: "rotate" }
       | { kind: "other"; detail: string } => {
       // Extract fill cells from each grid.
       const cellsA: [number, number][] = [];
       const cellsB: [number, number][] = [];
       for (let r = 0; r < before.length; r++) {
         for (let c = 0; c < before[r].length; c++) {
           if (before[r][c]) cellsA.push([r, c]);
           if (after[r][c]) cellsB.push([r, c]);
         }
       }
       // Same cells? No change.
       const keyA = cellsA.map(([r, c]) => `${r},${c}`).sort().join("|");
       const keyB = cellsB.map(([r, c]) => `${r},${c}`).sort().join("|");
       if (keyA === keyB) return { kind: "no_change" };
 
       // If cell counts are similar (+/- 1), try to detect a rigid translation
       // of the active piece. We do this by looking at the symmetric
       // differences: cells that disappeared and cells that appeared.
       const setA = new Set(keyA.split("|"));
       const setB = new Set(keyB.split("|"));
       const disappeared: [number, number][] = [];
       const appeared: [number, number][] = [];
       for (const [r, c] of cellsA) {
         if (!setB.has(`${r},${c}`)) disappeared.push([r, c]);
       }
       for (const [r, c] of cellsB) {
         if (!setA.has(`${r},${c}`)) appeared.push([r, c]);
       }
       if (disappeared.length === 0 && appeared.length === 0) {
         return { kind: "no_change" };
       }
 
       // Compute centroids + shapes of the disappeared/appeared sets.
       const avg = (arr: [number, number][]) => {
         const sumR = arr.reduce((s, [r]) => s + r, 0);
         const sumC = arr.reduce((s, [, c]) => s + c, 0);
         return [sumR / arr.length, sumC / arr.length] as [number, number];
       };
       const normalize = (cells: [number, number][]): string => {
         if (cells.length === 0) return "";
         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("|");
       };
 
       // Case 1: equal-size symmetric diff -> pure translation or rotation
       // of the active piece. When a 4-cell piece moves 1 column, some cells
       // overlap between old/new position (e.g. O-piece has 2 overlapping
       // cells), so the symmetric diff can be as small as 2 cells. We allow
       // 1-4 cells here.
       if (
         disappeared.length === appeared.length &&
         disappeared.length >= 1 &&
         disappeared.length <= 4
       ) {
         const [avgRA, avgCA] = avg(disappeared);
         const [avgRB, avgCB] = avg(appeared);
         const dRow = avgRB - avgRA;
         const dCol = avgCB - avgCA;
         const shapeA = normalize(disappeared);
         const shapeB = normalize(appeared);
         // Compare full-piece footprints: if a 4-cell piece rotates, the
         // set of cells in the "disappeared" union with the settled grid
         // can be very different from before. A cleaner rotation signal is
         // the total cell count in before vs after. For a pure translation,
         // the piece has the same bounding-box footprint (same shape) but
         // shifted. For a rotation, the bounding box dimensions usually
         // change (tall->wide or wide->tall).
         const fullBB = (cells: [number, number][]) => {
           if (cells.length === 0) return { w: 0, h: 0 };
           return {
             w: Math.max(...cells.map(([, c]) => c)) - Math.min(...cells.map(([, c]) => c)) + 1,
             h: Math.max(...cells.map(([r]) => r)) - Math.min(...cells.map(([r]) => r)) + 1,
           };
         };
         const bbA = fullBB(cellsA);
         const bbB = fullBB(cellsB);
         // Total-cells test: if the piece count didn't change and the
         // bounding box aspect flipped (e.g. 4x1 -> 1x4), that's rotation.
         // This catches I-piece rotation reliably.
         if (
           cellsA.length === cellsB.length &&
           ((bbA.w !== bbB.w) || (bbA.h !== bbB.h)) &&
           Math.abs(bbA.w - bbB.h) <= 1 && Math.abs(bbA.h - bbB.w) <= 1
         ) {
           return { kind: "rotate" };
         }
 
         // Rotation by shape change: if the disappeared/appeared shapes
         // differ, and the centroid drift doesn't look like a clean 1-col
         // horizontal translation, classify as rotation. Checked BEFORE the
         // horizontal/vertical translation tests so rotations that coincide
         // with auto-drop are still tagged as rotations, not translations.
         if (shapeA !== shapeB) {
           // A clean horizontal translation has dCol >= 1 and dRow small.
           // A clean vertical translation has dRow >= 1 and dCol small.
           // Anything else is rotation when the shape differs.
           const looksLikeClearHorizontal =
             Math.abs(dCol) >= 0.9 && Math.abs(dRow) < 0.6;
           const looksLikeClearVertical =
             Math.abs(dCol) < 0.6 && dRow >= 0.9;
           if (!looksLikeClearHorizontal && !looksLikeClearVertical) {
             return { kind: "rotate" };
           }
         }
 
         // Horizontal translation: large dCol dominates, shape is stable.
         if (shapeA === shapeB && Math.abs(dCol) >= 0.9 && Math.abs(dRow) <= 1.2) {
           if (dCol <= -0.9) return { kind: "move_left", distance: Math.max(1, Math.round(-dCol)) };
           if (dCol >= 0.9) return { kind: "move_right", distance: Math.max(1, Math.round(dCol)) };
         }
         // Vertical translation: dRow dominates, small dCol drift allowed.
         if (shapeA === shapeB && Math.abs(dCol) < 0.7 && dRow >= 0.5) {
           const distance = Math.max(1, Math.round(dRow));
           if (distance >= 5) return { kind: "hard_drop", distance };
           return { kind: "move_down", distance };
         }
         // Shape same but neither clearly horizontal nor vertical -> fall
         // through to "other". This avoids misclassifying noise as motion.
       }
 
       // Case 2: 4 cells appeared near the bottom and 4 (or fewer) disappeared
       // from higher up -> hard drop that teleported the piece.
       if (appeared.length >= 3 && disappeared.length >= 3) {
         const avgAppearedRow = avg(appeared)[0];
         const avgDisappearedRow = avg(disappeared)[0];
         const dRow = avgAppearedRow - avgDisappearedRow;
         if (dRow >= 4) {
           return { kind: "hard_drop", distance: Math.round(dRow) };
         }
       }
 
       // Case 3: more appeared than disappeared (a new piece spawned while
       // the old one dropped and locked). Treat as hard drop if the old
       // piece ended up near the bottom.
       if (appeared.length > disappeared.length && appeared.length >= 4) {
         // Find the set of appeared cells in the bottom half.
         const bottomAppeared = appeared.filter(([r]) => r >= GRID_ROWS / 2);
         if (bottomAppeared.length >= 3 && disappeared.length <= 4) {
           const avgDisappearedRow = disappeared.length > 0
             ? avg(disappeared)[0]
             : 0;
           const avgBottomRow = avg(bottomAppeared)[0];
           const dRow = avgBottomRow - avgDisappearedRow;
           if (dRow >= 4) {
             return { kind: "hard_drop", distance: Math.round(dRow) };
           }
         }
       }
 
       return { kind: "other", detail: `disappeared=${disappeared.length}, appeared=${appeared.length}` };
     };
 
     // Helper: try a single candidate key for an action, return whether it
     // matched the expected classification.
     const tryCandidateKey = async (
       action: GameAction,
       key: string,
       expected: (
         delta: ReturnType<typeof classifyDelta>
       ) => { matched: boolean; observation: string }
     ): Promise<boolean> => {
       // Snapshot before.
       const before = await this.readGrid();
       if (!before.grid) {
         map.key_observations[key] = "grid read failed before press";
         return false;
       }
       // Ignore keys on a fully-empty grid -- the candidate might do nothing
       // simply because there's no active piece yet.
       if (before.filledCount === 0) {
         map.key_observations[key] = "grid empty before press (no piece)";
         return false;
       }
       try {
         await this.pressRawKey(key);
       } catch {
         map.key_observations[key] = "keyboard press threw";
         return false;
       }
       await this.wait(120);
       const after = await this.readGrid();
       if (!after.grid) {
         map.key_observations[key] = "grid read failed after press";
         return false;
       }
       const delta = classifyDelta(before.grid, after.grid);
       const result = expected(delta);
       // Only record this observation if we don't already have one for the key
       // (first observation wins -- keeps the report meaningful).
       if (!map.key_observations[key]) {
         map.key_observations[key] = result.observation;
       }
       if (result.matched) {
         const slot: ControlMapping = {
           key,
           confidence: "suspected",
           observation: result.observation,
         };
         switch (action) {
           case "move_left": map.move_left = slot; break;
           case "move_right": map.move_right = slot; break;
           case "soft_drop": map.soft_drop = slot; break;
           case "hard_drop": map.hard_drop = slot; break;
           case "rotate_cw": map.rotate_cw = slot; break;
           case "rotate_ccw": map.rotate_ccw = slot; break;
           default: break;
         }
         return true;
       }
       return false;
     };
 
     // ---- Movement discovery (order: least disruptive first) ----
     // Try each action in priority order, reloading between actions to get
     // a fresh piece that hasn't already moved from the previous probe.
 
     // move_left
     if (!budgetExceeded()) {
       log("phase: move_left");
       await freshStart();
       for (const key of CONTROL_CANDIDATES.move_left) {
         if (budgetExceeded()) break;
         const matched = await tryCandidateKey("move_left", key, (delta) => {
           if (delta.kind === "move_left") {
             return { matched: true, observation: `moved ${delta.distance} col(s) left` };
           }
           if (delta.kind === "move_right") {
             return { matched: false, observation: `moved ${delta.distance} col(s) right (wrong direction)` };
           }
           if (delta.kind === "hard_drop") {
             return { matched: false, observation: `hard_drop (${delta.distance} rows)` };
           }
           if (delta.kind === "move_down") {
             return { matched: false, observation: `moved ${delta.distance} row(s) down` };
           }
           if (delta.kind === "rotate") {
             return { matched: false, observation: "rotation" };
           }
           if (delta.kind === "no_change") {
             return { matched: false, observation: "no change" };
           }
           return { matched: false, observation: `other change (${delta.detail})` };
         });
         if (matched) { log(`  move_left: ${key}`); break; }
       }
     }
 
     // move_right -- no need to reload if move_left probe succeeded without
     // disrupting the board meaningfully.
     if (!budgetExceeded()) {
       log("phase: move_right");
       await freshStart();
       for (const key of CONTROL_CANDIDATES.move_right) {
         if (budgetExceeded()) break;
         const matched = await tryCandidateKey("move_right", key, (delta) => {
           if (delta.kind === "move_right") {
             return { matched: true, observation: `moved ${delta.distance} col(s) right` };
           }
           if (delta.kind === "move_left") {
             return { matched: false, observation: `moved ${delta.distance} col(s) left (wrong direction)` };
           }
           if (delta.kind === "hard_drop") {
             return { matched: false, observation: `hard_drop (${delta.distance} rows)` };
           }
           if (delta.kind === "move_down") {
             return { matched: false, observation: `moved ${delta.distance} row(s) down` };
           }
           if (delta.kind === "rotate") {
             return { matched: false, observation: "rotation" };
           }
           if (delta.kind === "no_change") {
             return { matched: false, observation: "no change" };
           }
           return { matched: false, observation: `other change (${delta.detail})` };
         });
         if (matched) { log(`  move_right: ${key}`); break; }
       }
     }
 
     // rotate_cw. Fast path: if an earlier phase observed this key producing
     // a rotation, promote it without re-testing.
     if (!budgetExceeded()) {
       log("phase: rotate_cw");
       // Check if a prior phase already saw one of the rotate candidates as
       // a rotation.
       let promotedEarly = false;
       for (const key of CONTROL_CANDIDATES.rotate_cw) {
         const obs = map.key_observations[key];
         if (obs === "rotation" || obs === "shape changed (rotation)") {
           map.rotate_cw = {
             key,
             confidence: "suspected",
             observation: "rotation (promoted from earlier phase)",
           };
           log(`  rotate_cw: ${key} (promoted from observation)`);
           promotedEarly = true;
           break;
         }
       }
       if (!promotedEarly) {
         await freshStart();
         for (const key of CONTROL_CANDIDATES.rotate_cw) {
           if (budgetExceeded()) break;
           const matched = await tryCandidateKey("rotate_cw", key, (delta) => {
             if (delta.kind === "rotate") {
               return { matched: true, observation: "shape changed (rotation)" };
             }
             if (delta.kind === "hard_drop") {
               return { matched: false, observation: `hard_drop (${delta.distance} rows)` };
             }
             if (delta.kind === "move_down") {
               return { matched: false, observation: `moved ${delta.distance} row(s) down` };
             }
             if (delta.kind === "move_left") {
               return { matched: false, observation: `moved ${delta.distance} col(s) left` };
             }
             if (delta.kind === "move_right") {
               return { matched: false, observation: `moved ${delta.distance} col(s) right` };
             }
             if (delta.kind === "no_change") {
               return { matched: false, observation: "no change" };
             }
             return { matched: false, observation: `other change (${delta.detail})` };
           });
           if (matched) { log(`  rotate_cw: ${key}`); break; }
         }
       }
     }
 
     // hard_drop (do this BEFORE soft_drop so we know which key teleports).
     // IMPORTANT: hard drop candidates include keys like Space that may be
     // bound to other functions (pause, confirm, etc). Pressing Space on a
     // game that uses it for pause will freeze all subsequent probes. So we
     // RELOAD before every hard_drop attempt to guarantee a clean state.
     if (!budgetExceeded()) {
       log("phase: hard_drop");
       for (const key of CONTROL_CANDIDATES.hard_drop) {
         if (budgetExceeded()) break;
         if (map.hard_drop.confidence !== "not_found") break;
         // Prior observation fast-path: if we already saw this key act like
         // a rotation/left/right/etc. in an earlier phase, skip retesting.
         const priorObs = map.key_observations[key];
         if (priorObs && !priorObs.includes("teleported") && !priorObs.includes("hard_drop")) {
           continue;
         }
         // Always reload before a hard_drop probe.
         await freshStart();
         const matched = await tryCandidateKey("hard_drop", key, (delta) => {
           if (delta.kind === "hard_drop") {
             return { matched: true, observation: `teleported ${delta.distance} rows to bottom` };
           }
           if (delta.kind === "move_down") {
             return {
               matched: false,
               observation: `moved ${delta.distance} row(s) down (soft drop, not hard drop)`,
             };
           }
           if (delta.kind === "rotate") {
             return { matched: false, observation: "rotation" };
           }
           if (delta.kind === "move_left") {
             return { matched: false, observation: `moved ${delta.distance} col(s) left` };
           }
           if (delta.kind === "move_right") {
             return { matched: false, observation: `moved ${delta.distance} col(s) right` };
           }
           if (delta.kind === "no_change") {
             return { matched: false, observation: "no change" };
           }
           return { matched: false, observation: `other change (${delta.detail})` };
         });
         if (matched) { log(`  hard_drop: ${key}`); break; }
       }
     }
 
     // soft_drop -- this is where the main bug lives. Try alternatives FIRST.
     // ArrowDown is tried only if it wasn't already claimed as hard_drop.
     if (!budgetExceeded()) {
       log("phase: soft_drop");
       await freshStart();
       // Skip ArrowDown if we already discovered it maps to hard_drop on
       // this game. Same for any key already claimed by another action.
       const claimedKeys = new Set<string>();
       for (const slot of [map.move_left, map.move_right, map.hard_drop, map.rotate_cw]) {
         if (slot.key) claimedKeys.add(slot.key);
       }
       for (const key of CONTROL_CANDIDATES.soft_drop) {
         if (budgetExceeded()) break;
         if (claimedKeys.has(key)) {
           // ArrowDown was already claimed as hard_drop etc.
           map.key_observations[key] =
             map.key_observations[key] || "already claimed by another action";
           continue;
         }
         const matched = await tryCandidateKey("soft_drop", key, (delta) => {
           if (delta.kind === "move_down") {
             return {
               matched: delta.distance >= 1 && delta.distance <= 3,
               observation: `moved ${delta.distance} row(s) down`,
             };
           }
           if (delta.kind === "hard_drop") {
             return {
               matched: false,
               observation: `teleported ${delta.distance} rows (hard_drop, not soft_drop)`,
             };
           }
           if (delta.kind === "rotate") {
             return { matched: false, observation: "rotation" };
           }
           if (delta.kind === "move_left") {
             return { matched: false, observation: `moved ${delta.distance} col(s) left` };
           }
           if (delta.kind === "move_right") {
             return { matched: false, observation: `moved ${delta.distance} col(s) right` };
           }
           if (delta.kind === "no_change") {
             return { matched: false, observation: "no change" };
           }
           return { matched: false, observation: `other change (${delta.detail})` };
         });
         if (matched) { log(`  soft_drop: ${key}`); break; }
       }
       if (map.soft_drop.confidence === "not_found") {
         log("  soft_drop: NOT FOUND");
       }
     }
 
     // rotate_ccw (best effort; cheap skip if budget exceeded)
     if (!budgetExceeded()) {
       log("phase: rotate_ccw");
       await freshStart();
       for (const key of CONTROL_CANDIDATES.rotate_ccw) {
         if (budgetExceeded()) break;
         const matched = await tryCandidateKey("rotate_ccw", key, (delta) => {
           if (delta.kind === "rotate") {
             return { matched: true, observation: "shape changed (rotation)" };
           }
           if (delta.kind === "no_change") {
             return { matched: false, observation: "no change" };
           }
           return { matched: false, observation: `other change` };
         });
         if (matched) { log(`  rotate_ccw: ${key}`); break; }
       }
     }
 
     // Final reload so tests start from a clean state.
     await freshStart();
 
     this.discoveredControls = map;
     // Mirror into the cached calibration so bot-side code that reads
     // cal.controlMap sees the discovery result.
     if (this.cal) {
       this.cal.controlMap = map;
       // Also back-port the discovered keys into the legacy controls field
       // so any code that still reads cal.controls.<x> keeps working.
       if (map.move_left.key) this.cal.controls.left = map.move_left.key;
       if (map.move_right.key) this.cal.controls.right = map.move_right.key;
       if (map.rotate_cw.key) this.cal.controls.rotate = map.rotate_cw.key;
       if (map.hard_drop.key) this.cal.controls.drop = map.hard_drop.key;
       // Only override the legacy `down` if we found a distinct soft drop key.
       // If soft_drop is not_found, leave `down` alone so legacy callers still
       // have SOMETHING to press -- pressKey() will intercept and no-op anyway.
       if (map.soft_drop.key) this.cal.controls.down = map.soft_drop.key;
     }
     // Persist into the first-cal baseline too so cache replays preserve the
     // discovered map.
     if (this.firstCal) {
       this.firstCal.controlMap = cloneControlMap(map);
       if (map.move_left.key) this.firstCal.controls.left = map.move_left.key;
       if (map.move_right.key) this.firstCal.controls.right = map.move_right.key;
       if (map.rotate_cw.key) this.firstCal.controls.rotate = map.rotate_cw.key;
       if (map.hard_drop.key) this.firstCal.controls.drop = map.hard_drop.key;
       if (map.soft_drop.key) this.firstCal.controls.down = map.soft_drop.key;
     }
     return map;
   }
 
   async wait(ms: number): Promise<void> {
     this.checkInactivity();
     await this.page.waitForTimeout(ms);
   }
 
   // -- Score/Level --
 
   async readScore(): Promise<number | null> {
     const cal = this.cal;
     if (!cal?.scoreElementSelector) return null;
     try {
       const scoreText = await this.page.textContent(cal.scoreElementSelector);
       const nums = this.extractScoreFromText(scoreText);
       return nums.length > 0 ? Math.max(...nums) : null;
     } catch {
       return null;
     }
   }
 
   async readLevel(): Promise<number | null> {
     try {
       return await this.page.evaluate(() => {
         const allElements = document.querySelectorAll("*");
         for (const el of allElements) {
           const text = ((el as HTMLElement).innerText || "").toLowerCase();
           if (text.includes("level") && el.children.length < 5) {
             const match = text.match(/level\s*[:\-=]?\s*(\d+)/i);
             if (match) return parseInt(match[1], 10);
 
             const children = el.querySelectorAll("span, div, p, td, strong, em, b");
             for (const child of children) {
               const childText = (child.textContent || "").trim();
               if (/^\d+$/.test(childText)) return parseInt(childText, 10);
             }
 
             const next = el.nextElementSibling;
             if (next) {
               const nextText = (next.textContent || "").trim();
               if (/^\d+$/.test(nextText)) return parseInt(nextText, 10);
             }
           }
         }
         // Also try nivel (Spanish)
         for (const el of allElements) {
           const text = ((el as HTMLElement).innerText || "").toLowerCase();
           if (text.includes("nivel") && el.children.length < 5) {
             const match = text.match(/nivel\s*[:\-=]?\s*(\d+)/i);
             if (match) return parseInt(match[1], 10);
           }
         }
         return null;
       });
     } catch {
       return null;
     }
   }
 
   // -- Page State Queries --
 
   /**
    * Detect if a game-over modal/overlay is visible on the page.
    * Language-agnostic: looks for a NEW visible element that wasn't there during
    * gameplay, covering a significant portion of the viewport, with position
    * fixed/absolute and meaningful z-index. Returns a description like "modal"
    * or "overlay" rather than extracted text.
    */
   async detectGameOverText(): Promise<string | null> {
     try {
       return await this.page.evaluate(() => {
         const vw = window.innerWidth;
         const vh = window.innerHeight;
         const viewportArea = vw * vh;
 
         // Find elements that look like modals/overlays
         const all = document.querySelectorAll<HTMLElement>("*");
         for (const el of all) {
           const style = window.getComputedStyle(el);
           const pos = style.position;
           if (pos !== "fixed" && pos !== "absolute") continue;
 
           // Must be visible
           if (style.display === "none" || style.visibility === "hidden" ||
               parseFloat(style.opacity) === 0) continue;
 
           const rect = el.getBoundingClientRect();
           if (rect.width === 0 || rect.height === 0) continue;
 
           const area = rect.width * rect.height;
           // Significant coverage: 15% or more of viewport
           if (area < viewportArea * 0.15) continue;
 
           // Must have visible background or children (not a transparent wrapper)
           const hasBg = style.backgroundColor !== "rgba(0, 0, 0, 0)" &&
                         style.backgroundColor !== "transparent";
           const hasContent = el.children.length > 0 || (el.textContent || "").trim().length > 0;
           if (!hasBg && !hasContent) continue;
 
           // High z-index relative to the page
           const z = parseInt(style.zIndex, 10);
           if (!isNaN(z) && z < 1) continue;
 
           return "modal";
         }
 
         return null;
       });
     } catch {
       return null;
     }
   }
 
   /**
    * Detect if a restart/new-game option is visible.
    * Language-agnostic: looks for a clickable element that appears NOW and
    * wasn't there during initial play. We approximate this by finding any
    * visible clickable element (button, [role=button], cursor:pointer) inside
    * a visible modal/overlay, or a clickable element that wasn't present at
    * calibration time. This avoids text matching.
    */
   async detectRestartOption(): Promise<boolean> {
     try {
       return await this.page.evaluate(() => {
         const vw = window.innerWidth;
         const vh = window.innerHeight;
         const viewportArea = vw * vh;
 
         // Find modals/overlays
         const all = document.querySelectorAll<HTMLElement>("*");
         for (const el of all) {
           const style = window.getComputedStyle(el);
           const pos = style.position;
           if (pos !== "fixed" && pos !== "absolute") continue;
           if (style.display === "none" || style.visibility === "hidden" ||
               parseFloat(style.opacity) === 0) continue;
           const rect = el.getBoundingClientRect();
           if (rect.width === 0 || rect.height === 0) continue;
           if (rect.width * rect.height < viewportArea * 0.15) continue;
 
           // Look for clickable elements inside this modal
           const clickables = el.querySelectorAll<HTMLElement>(
             "button, [role=button], a, input[type=button], input[type=submit]"
           );
           for (const c of clickables) {
             const cRect = c.getBoundingClientRect();
             if (cRect.width > 0 && cRect.height > 0) return true;
           }
 
           // Also check for elements with cursor: pointer
           const all2 = el.querySelectorAll<HTMLElement>("*");
           for (const c of all2) {
             if (window.getComputedStyle(c).cursor === "pointer") {
               const cRect = c.getBoundingClientRect();
               if (cRect.width > 0 && cRect.height > 0) return true;
             }
           }
         }
 
         return false;
       });
     } catch {
       return false;
     }
   }
 
   async detectNextPiecePreview(): Promise<boolean> {
     try {
       return await this.page.evaluate(() => {
         const allElements = document.querySelectorAll("*");
         for (const el of allElements) {
           const text = ((el as HTMLElement).innerText || "").toLowerCase();
           if ((text.includes("next") || text.includes("siguiente")) && el.children.length < 10) {
             const rect = (el as HTMLElement).getBoundingClientRect();
             if (rect.width > 20 && rect.height > 20) return true;
           }
         }
 
         const canvases = document.querySelectorAll("canvas");
         if (canvases.length >= 2) {
           const mainRect = canvases[0].getBoundingClientRect();
           for (let i = 1; i < canvases.length; i++) {
             const rect = canvases[i].getBoundingClientRect();
             if (rect.width < mainRect.width * 0.5 && rect.height < mainRect.height * 0.5 &&
                 rect.width > 20 && rect.height > 20) return true;
           }
         }
 
         const nextContainers = document.querySelectorAll(
           '[class*="next"], [id*="next"], [class*="preview"], [id*="preview"], [class*="siguiente"], [id*="siguiente"]'
         );
         for (const container of nextContainers) {
           const rect = (container as HTMLElement).getBoundingClientRect();
           if (rect.width > 20 && rect.height > 20) return true;
         }
         return false;
       });
     } catch {
       return false;
     }
   }
 
   getConsoleErrors(): string[] {
     return [...this.consoleErrors];
   }
 
   // -- Screenshots --
 
   async screenshot(): Promise<Buffer> {
     return await this.page.screenshot();
   }
 
   async screenshotGridArea(): Promise<Buffer | null> {
     const cal = this.cal;
     if (!cal || !cal.gridBounds) return null;
     const b = cal.gridBounds;
     // For DOM renderers, gridBounds are viewport coordinates and can be clipped
     // directly. For canvas renderers they are internal canvas coordinates, so
     // re-derive the on-page bounds from the canvas location to stay accurate.
     try {
       if (cal.renderer === "canvas") {
         const boundingBox = await this.page.locator("canvas").first().boundingBox();
         if (!boundingBox) return null;
         return await this.page.screenshot({
           clip: {
             x: Math.max(0, Math.round(boundingBox.x)),
             y: Math.max(0, Math.round(boundingBox.y)),
             width: Math.max(1, Math.round(boundingBox.width)),
             height: Math.max(1, Math.round(boundingBox.height)),
           },
         });
       }
       return await this.page.screenshot({
         clip: {
           x: Math.max(0, Math.round(b.x)),
           y: Math.max(0, Math.round(b.y)),
           width: Math.max(1, Math.round(b.width)),
           height: Math.max(1, Math.round(b.height)),
         },
       });
     } catch {
       return null;
     }
   }
 
   async captureGridDomFingerprint(): Promise<string> {
     try {
       return await this.page.evaluate(() => {
         // Locate the most plausible grid container. Mirrors the detection in
         // detectGrid() but runs standalone so the fingerprint works even when
         // the calibration has not committed to a specific grid yet.
         const findContainer = (): Element | null => {
           const tables = document.querySelectorAll("table");
           for (const table of tables) {
             const rows = table.querySelectorAll("tr");
             if (rows.length >= 18) {
               const firstRow = rows[0].querySelectorAll("td");
               if (firstRow.length >= 8 && firstRow.length <= 12) return table;
             }
           }
           const namedCandidates = document.querySelectorAll(
             '[class*="board"], [class*="grid"], [class*="field"], ' +
             '[id*="board"], [id*="grid"], [id*="field"]'
           );
           for (const c of namedCandidates) {
             const ch = c.children;
             if (ch.length >= 180 && ch.length <= 230) return c;
             if (
               ch.length >= 18 && ch.length <= 22 &&
               ch[0] && ch[0].children.length >= 8 && ch[0].children.length <= 12
             ) {
               return c;
             }
           }
           // Heuristic scan for any container with ~200 uniform children.
           const allElements = document.querySelectorAll("div, section, main, article");
           for (const el of allElements) {
             const ch = el.children;
             if (ch.length >= 180 && ch.length <= 230) return el;
           }
           return null;
         };
 
         const container = findContainer();
         if (!container) return "";
 
         const parts: string[] = [];
         parts.push(`count=${container.children.length}`);
 
         // Serialize each child: class, inline position, inline background.
         // Only inline styles (not computed) -- avoids paying for
         // getComputedStyle() on 200+ elements per fingerprint, and in practice
         // absolute-positioned piece overlays always use inline top/left/bg.
         let i = 0;
         for (const child of container.children) {
           if (i >= 260) break; // hard cap to bound work
           const el = child as HTMLElement;
           const cls = el.className || "";
           const style = el.style;
           const left = style.left || "";
           const top = style.top || "";
           const bg = style.backgroundColor || "";
           const color = style.getPropertyValue("--color") || "";
           parts.push(`${i}:${cls}:${left}:${top}:${bg}:${color}`);
           i++;
         }
 
         return parts.join("|");
       });
     } catch {
       return "";
     }
   }
 
   async measureDropInterval(): Promise<number> {
     try {
       const intervals: number[] = [];
       let lastChangeTime = Date.now();
       let prevSnap = await this.readGrid();
 
       for (let i = 0; i < 10; i++) {
         await this.page.waitForTimeout(100);
         const snap = await this.readGrid();
         if (snap.grid && prevSnap.grid && this.gridsAreDifferent(snap.grid, prevSnap.grid)) {
           const now = Date.now();
           const interval = now - lastChangeTime;
           if (interval > 50 && interval < 3000) intervals.push(interval);
           lastChangeTime = now;
           prevSnap = snap;
         }
       }
 
       if (intervals.length >= 2) {
         return intervals.reduce((a, b) => a + b, 0) / intervals.length;
       }
     } catch { /* ignore */ }
     return 0;
   }
 
   // =========================================================================
   // PRIVATE METHODS
   // =========================================================================
 
   // -- Grid reading internals --
 
   private async readCanvasGrid(
     bounds: GridBounds, cellW: number, cellH: number,
     bgColor: [number, number, number] | null
   ): Promise<Grid | null> {
     const bgR = bgColor ? bgColor[0] : 0;
     const bgG = bgColor ? bgColor[1] : 0;
     const bgB = bgColor ? bgColor[2] : 0;
     const threshold = 50;
 
     const grid = await this.page.evaluate(
       ({ x, y, cellW, cellH, rows, cols, bgR, bgG, bgB, threshold }) => {
         const canvas = document.querySelector("canvas") as HTMLCanvasElement | null;
         if (!canvas) return null;
         const ctx = canvas.getContext("2d");
         if (!ctx) return null;
 
         const offsets = [
           [0, 0],
           [-Math.floor(cellW / 4), 0],
           [Math.floor(cellW / 4), 0],
           [0, -Math.floor(cellH / 4)],
           [0, Math.floor(cellH / 4)],
         ];
 
         const result: boolean[][] = [];
         for (let row = 0; row < rows; row++) {
           const rowData: boolean[] = [];
           for (let col = 0; col < cols; col++) {
             const cx = Math.floor(x + col * cellW + cellW / 2);
             const cy = Math.floor(y + row * cellH + cellH / 2);
 
             let filledCount = 0;
             for (const [ox, oy] of offsets) {
               const px = Math.min(Math.max(cx + ox, 0), canvas.width - 1);
               const py = Math.min(Math.max(cy + oy, 0), canvas.height - 1);
               const pixel = ctx.getImageData(px, py, 1, 1).data;
               const dr = pixel[0] - bgR;
               const dg = pixel[1] - bgG;
               const db = pixel[2] - bgB;
               const dist = Math.sqrt(dr * dr + dg * dg + db * db);
               if (dist > threshold) filledCount++;
             }
             rowData.push(filledCount >= 3);
           }
           result.push(rowData);
         }
         return result;
       },
       { x: bounds.x, y: bounds.y, cellW, cellH, rows: GRID_ROWS, cols: GRID_COLS, bgR, bgG, bgB, threshold }
     );
 
     if (grid) {
       const totalCells = GRID_ROWS * GRID_COLS;
       const filledCells = grid.reduce((sum, row) => sum + row.filter(Boolean).length, 0);
       if (filledCells / totalCells > 0.60) return null;
     }
 
     return grid;
   }
 
   private async readDomGrid(): Promise<Grid | null> {
     const grid = await this.page.evaluate(({ rows, cols }) => {
       function isCellFilled(cell: HTMLElement, emptyBg?: string): boolean {
         const style = window.getComputedStyle(cell);
         const bg = style.backgroundColor;
         const cls = cell.className.toLowerCase();
 
         if (
           cls.includes("filled") || cls.includes("active") ||
           cls.includes("block") || cls.includes("piece") ||
           cls.includes("occupied") || cls.includes("locked") ||
           cell.dataset.filled === "true" || cell.dataset.type !== undefined
         ) return true;
 
         if (emptyBg && bg === emptyBg) return false;
 
         return (
           bg !== "" && bg !== "rgba(0, 0, 0, 0)" &&
           bg !== "transparent" && bg !== "rgb(0, 0, 0)"
         );
       }
 
       function detectEmptyBg(cells: HTMLElement[]): string | undefined {
         const colorCounts = new Map<string, number>();
         for (const cell of cells) {
           const bg = window.getComputedStyle(cell).backgroundColor;
           colorCounts.set(bg, (colorCounts.get(bg) || 0) + 1);
         }
         let maxCount = 0;
         let emptyBg: string | undefined;
         for (const [color, count] of colorCounts) {
           if (count > maxCount) { maxCount = count; emptyBg = color; }
         }
         if (emptyBg && maxCount > cells.length * 0.6) return emptyBg;
         return undefined;
       }
 
       // Strategy 1: table-based grid
       const tables = document.querySelectorAll("table");
       for (const table of tables) {
         const trs = table.querySelectorAll("tr");
         if (trs.length >= rows) {
           const allCells: HTMLElement[] = [];
           for (let r = 0; r < rows; r++) {
             const tds = trs[r].querySelectorAll("td");
             for (let c = 0; c < Math.min(cols, tds.length); c++) allCells.push(tds[c] as HTMLElement);
           }
           const emptyBg = detectEmptyBg(allCells);
           const result: boolean[][] = [];
           for (let r = 0; r < rows; r++) {
             const tds = trs[r].querySelectorAll("td");
             const rowData: boolean[] = [];
             for (let c = 0; c < cols; c++) {
               rowData.push(c < tds.length ? isCellFilled(tds[c] as HTMLElement, emptyBg) : false);
             }
             result.push(rowData);
           }
           return result;
         }
       }
 
       // Overlay detection: some games render the active piece as absolute-
       // positioned sibling divs inside the grid container (so they float
       // over the static cell grid). These are NOT part of the cell loop but
       // their position tells us which grid cell they occupy. Called after
       // building the cell-based grid; only overwrites empty cells.
       function applyOverlayPieces(
         container: Element, cellGrid: boolean[][], cellsConsumed: number,
         actualRows: number, actualCols: number
       ): void {
         const containerRect = container.getBoundingClientRect();
         if (containerRect.width <= 0 || containerRect.height <= 0) return;
         const cellW = containerRect.width / actualCols;
         const cellH = containerRect.height / actualRows;
         if (cellW < 5 || cellH < 5) return;
 
         const allChildren = container.children;
         for (let i = cellsConsumed; i < allChildren.length; i++) {
           const el = allChildren[i] as HTMLElement;
           const style = window.getComputedStyle(el);
           // Skip statically-positioned siblings -- we only want pieces
           // that float over the grid.
           if (style.position !== "absolute" && style.position !== "fixed") continue;
           const rect = el.getBoundingClientRect();
           if (rect.width <= 0 || rect.height <= 0) continue;
           // Center of the overlay element, relative to the container
           const cx = rect.left + rect.width / 2 - containerRect.left;
           const cy = rect.top + rect.height / 2 - containerRect.top;
           const col = Math.floor(cx / cellW);
           const row = Math.floor(cy / cellH);
           if (row < 0 || row >= actualRows || col < 0 || col >= actualCols) continue;
           cellGrid[row][col] = true;
         }
       }
 
       // Strategy 2: named grid containers
       const containers = document.querySelectorAll(
         '[class*="board"], [class*="grid"], [class*="field"], [id*="board"], [id*="grid"], [id*="field"]'
       );
       for (const container of containers) {
         const children = container.children;
         // Container has rows*cols (+/- 10) static cells, optionally followed
         // by a handful of absolute-positioned children that act as piece
         // overlays (e.g. the active piece rendered on top of the static grid).
         // Accept up to 30 extra children beyond the cell count.
         if (children.length >= rows * cols - 10 && children.length <= rows * cols + 30) {
           const actualCols = cols;
           // If we're at the short end of the range, fall back to the old
           // behaviour and derive actualRows from the child count. Otherwise
           // assume the extras are overlays and use the full grid dimensions.
           const isShortGrid = children.length <= rows * cols + 4;
           const actualRows = isShortGrid
             ? Math.round(children.length / actualCols)
             : rows;
           const cellsConsumed = actualRows * actualCols;
           const allCells = Array.from(children).slice(0, cellsConsumed) as HTMLElement[];
           const emptyBg = detectEmptyBg(allCells);
           const result: boolean[][] = [];
           for (let r = 0; r < actualRows; r++) {
             const rowData: boolean[] = [];
             for (let c = 0; c < actualCols; c++) {
               const cell = allCells[r * actualCols + c];
               rowData.push(cell ? isCellFilled(cell, emptyBg) : false);
             }
             result.push(rowData);
           }
           // Overlay detection is a no-op when there are no extra children
           // past the static cell grid, so it's safe to always call.
           applyOverlayPieces(container, result, cellsConsumed, actualRows, actualCols);
           return result;
         }
         if (children.length >= rows - 2 && children.length <= rows + 2) {
           const firstRowCells = children[0]?.children;
           if (firstRowCells && firstRowCells.length >= cols - 2 && firstRowCells.length <= cols + 2) {
             const actualRows = children.length;
             const actualCols = firstRowCells.length;
             const allCells: HTMLElement[] = [];
             for (let r = 0; r < actualRows; r++) {
               const cells = children[r].children;
               for (let c = 0; c < Math.min(actualCols, cells.length); c++) allCells.push(cells[c] as HTMLElement);
             }
             const emptyBg = detectEmptyBg(allCells);
             let valid = true;
             const result: boolean[][] = [];
             for (let r = 0; r < actualRows; r++) {
               const cells = children[r].children;
               if (cells.length < actualCols) { valid = false; break; }
               const rowData: boolean[] = [];
               for (let c = 0; c < actualCols; c++) rowData.push(isCellFilled(cells[c] as HTMLElement, emptyBg));
               result.push(rowData);
             }
             if (valid) return result;
           }
         }
       }
 
       // Strategy 3: heuristic scan for ANY container with many same-sized children
       const allElements = document.querySelectorAll("div, section, main, article");
       for (const el of allElements) {
         const ch = el.children;
         if (ch.length >= 180 && ch.length <= 230) {
           const firstChild = ch[0] as HTMLElement;
           if (!firstChild) continue;
           const firstRect = firstChild.getBoundingClientRect();
           if (firstRect.width < 5 || firstRect.height < 5) continue;
           let uniform = true;
           for (let i = 1; i < Math.min(10, ch.length); i++) {
             const r = (ch[i] as HTMLElement).getBoundingClientRect();
             if (Math.abs(r.width - firstRect.width) > 2 || Math.abs(r.height - firstRect.height) > 2) { uniform = false; break; }
           }
           if (uniform) {
             const actualCols = cols;
             const actualRows = Math.round(ch.length / actualCols);
             const allCells = Array.from(ch).slice(0, actualRows * actualCols) as HTMLElement[];
             const emptyBg = detectEmptyBg(allCells);
             const result: boolean[][] = [];
             for (let r = 0; r < actualRows; r++) {
               const rowData: boolean[] = [];
               for (let c = 0; c < actualCols; c++) {
                 const cell = allCells[r * actualCols + c];
                 rowData.push(cell ? isCellFilled(cell, emptyBg) : false);
               }
               result.push(rowData);
             }
             return result;
           }
         }
         if (ch.length >= 18 && ch.length <= 22) {
           const firstRowCells = ch[0]?.children;
           if (firstRowCells && firstRowCells.length >= 8 && firstRowCells.length <= 12) {
             const rect = el.getBoundingClientRect();
             if (rect.width > 50 && rect.height > 100) {
               const actualRows = ch.length;
               const actualCols = firstRowCells.length;
               const allCells: HTMLElement[] = [];
               for (let r = 0; r < actualRows; r++) {
                 const cells = ch[r].children;
                 for (let c = 0; c < Math.min(actualCols, cells.length); c++) allCells.push(cells[c] as HTMLElement);
               }
               const emptyBg = detectEmptyBg(allCells);
               let valid = true;
               const result: boolean[][] = [];
               for (let r = 0; r < actualRows; r++) {
                 const cells = ch[r].children;
                 if (cells.length < actualCols) { valid = false; break; }
                 const rowData: boolean[] = [];
                 for (let c = 0; c < actualCols; c++) rowData.push(isCellFilled(cells[c] as HTMLElement, emptyBg));
                 result.push(rowData);
               }
               if (valid) return result;
             }
           }
         }
       }
 
       return null;
     }, { rows: GRID_ROWS, cols: GRID_COLS });
 
     return grid;
   }
 
   private async sampleBackgroundColor(
     bounds: GridBounds, cellW: number, cellH: number
   ): Promise<[number, number, number] | null> {
     try {
       return await this.page.evaluate(
         ({ x, y, cellW, cellH }) => {
           const canvas = document.querySelector("canvas") as HTMLCanvasElement | null;
           if (!canvas) return null;
           const ctx = canvas.getContext("2d");
           if (!ctx) return null;
           const px = Math.floor(x + cellW / 2);
           const py = Math.floor(y + cellH / 2);
           const pixel = ctx.getImageData(px, py, 1, 1).data;
           return [pixel[0], pixel[1], pixel[2]] as [number, number, number];
         },
         { x: bounds.x, y: bounds.y, cellW, cellH }
       );
     } catch {
       return null;
     }
   }
 
   // -- Start detection --
 
   private async detectStartMechanism(): Promise<{
     mechanism: StartMechanism;
     startButton?: DriverCalibration["startButton"];
   }> {
     const deadline = Date.now() + 30000;
     const budgetExceeded = () => Date.now() >= deadline;
 
     try {
       const diag = await this.page.evaluate(() => ({
         title: document.title,
         buttons: Array.from(document.querySelectorAll("button")).map(b => b.textContent?.trim()),
         canvases: Array.from(document.querySelectorAll("canvas")).length,
         bodySize: document.body?.innerHTML?.length ?? 0,
       }));
       this.log(`Page: "${diag.title}", ${diag.buttons.length} buttons, ${diag.canvases} canvases`);
     } catch { /* continue */ }
 
     // Phase 1: Auto-start check
     {
       this.log("Phase 1: checking auto-start...");
       const result = await this.detectVisualChange({ frames: 6, intervalMs: 200 });
       if (result.changed) {
         const interactive = await this.verifyInteractivity();
         if (interactive) {
           this.log("Auto-start detected and interactive");
           return { mechanism: "auto" };
         }
         this.log("Visual change but not interactive (animation?)");
       }
     }
 
     // Phase 2: DOM buttons FIRST (more reliable for DOM games, language-agnostic)
     if (!budgetExceeded()) {
       this.log("Phase 2: trying DOM buttons...");
       const buttonResult = await this.tryDomButtons(budgetExceeded);
       if (buttonResult) return buttonResult;
     }
 
     // Phase 3: Keyboard triggers
     if (!budgetExceeded()) {
       this.log("Phase 3: trying keyboard triggers...");
       const keyResult = await this.tryKeyboardTriggers(budgetExceeded);
       if (keyResult) return keyResult;
     }
 
     // Phase 4: Canvas clicks
     if (!budgetExceeded()) {
       this.log("Phase 4: trying canvas clicks...");
       const canvasResult = await this.tryCanvasClicks(budgetExceeded);
       if (canvasResult) return canvasResult;
     }
 
     // Phase 5: Retry all
     if (!budgetExceeded()) {
       const r2 = await this.tryDomButtons(budgetExceeded);
       if (r2) return r2;
     }
     if (!budgetExceeded()) {
       const r3 = await this.tryKeyboardTriggers(budgetExceeded);
       if (r3) return r3;
     }
     if (!budgetExceeded()) {
       const r4 = await this.tryCanvasClicks(budgetExceeded);
       if (r4) return r4;
     }
 
     return { mechanism: "unknown" };
   }
 
   private async detectVisualChange(
     options?: { frames?: number; intervalMs?: number; before?: Buffer }
   ): Promise<{ changed: boolean }> {
     const FRAMES = options?.frames ?? 6;
     const INTERVAL = options?.intervalMs ?? 200;
 
     const screenshots: Buffer[] = [];
     for (let i = 0; i < FRAMES; i++) {
       screenshots.push(await this.page.screenshot());
       if (i < FRAMES - 1) await this.page.waitForTimeout(INTERVAL);
     }
 
     let changed = false;
 
     if (options?.before) {
       for (const shot of screenshots) {
         if (!options.before.equals(shot)) { changed = true; break; }
       }
     } else {
       // Compare consecutive frames
       for (let f = 0; f < screenshots.length - 1; f++) {
         if (!screenshots[f].equals(screenshots[f + 1])) { changed = true; break; }
       }
       // Also check with a late frame
       if (!changed) {
         await this.page.waitForTimeout(1200);
         const lateFrame = await this.page.screenshot();
         if (!screenshots[0].equals(lateFrame)) changed = true;
       }
     }
 
     return { changed };
   }
 
   private async verifyInteractivity(): Promise<boolean> {
     try {
       await this.page.waitForTimeout(200);
 
       const baseline = await this.page.screenshot();
       const domBefore = await this.page.evaluate(() => {
         const candidates = document.querySelectorAll(
           '[class*="board"], [class*="grid"], [class*="field"], [id*="board"], [id*="grid"], table'
         );
         let best = "";
         for (const el of candidates) {
           const snap = Array.from(el.children).map(c =>
             (c as HTMLElement).className + (c as HTMLElement).style.cssText
           ).join("|");
           if (snap.length > best.length) best = snap;
         }
         if (!best) best = document.body.innerHTML.substring(0, 5000);
         return best;
       });
 
       for (const key of ["ArrowLeft", "ArrowRight", "ArrowDown"]) {
         await this.page.keyboard.press(key);
         await this.page.waitForTimeout(100);
 
         const after = await this.page.screenshot();
         if (!baseline.equals(after)) return true;
 
         const domAfter = await this.page.evaluate(() => {
           const candidates = document.querySelectorAll(
             '[class*="board"], [class*="grid"], [class*="field"], [id*="board"], [id*="grid"], table'
           );
           let best = "";
           for (const el of candidates) {
             const snap = Array.from(el.children).map(c =>
               (c as HTMLElement).className + (c as HTMLElement).style.cssText
             ).join("|");
             if (snap.length > best.length) best = snap;
           }
           if (!best) best = document.body.innerHTML.substring(0, 5000);
           return best;
         });
         if (domAfter !== domBefore) return true;
       }
       return false;
     } catch {
       return false;
     }
   }
 
   private async tryDomButtons(
     budgetExceeded: () => boolean
   ): Promise<{ mechanism: StartMechanism; startButton?: DriverCalibration["startButton"] } | null> {
     try {
       const elementInfos = await this.page.evaluate(() => {
         const seen = new Set<Element>();
         const results: Array<{
           index: number; text: string; x: number; y: number;
           width: number; height: number; area: number; centerDist: number;
           selector: string; hasBackground: boolean;
         }> = [];
 
         const clickableSelector =
           'button, a, [role="button"], [onclick], input[type="button"], input[type="submit"]';
         for (const el of document.querySelectorAll(clickableSelector)) {
           if (!seen.has(el)) seen.add(el);
         }
 
         const allEls = document.querySelectorAll("*");
         for (const el of allEls) {
           if (seen.has(el)) continue;
           try {
             const style = window.getComputedStyle(el);
             if (style.cursor === "pointer") seen.add(el);
           } catch { /* skip */ }
         }
 
         const pageW = window.innerWidth;
         const pageH = window.innerHeight;
         const pageCenterX = pageW / 2;
         const pageCenterY = pageH / 2;
 
         let idx = 0;
         for (const el of seen) {
           const rect = el.getBoundingClientRect();
           if (rect.width < 5 || rect.height < 5) continue;
           if (rect.top > pageH || rect.left > pageW) continue;
           if (rect.width > pageW * 0.8 && rect.height > pageH * 0.8) continue;
 
           const cx = rect.left + rect.width / 2;
           const cy = rect.top + rect.height / 2;
           const centerDist = Math.sqrt((cx - pageCenterX) ** 2 + (cy - pageCenterY) ** 2);
 
           let hasBackground = false;
           try {
             const style = window.getComputedStyle(el as HTMLElement);
             const bg = style.backgroundColor;
             if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") hasBackground = true;
           } catch { /* skip */ }
 
           let selector = "";
           if (el.id) selector = `#${el.id}`;
           else if ((el as HTMLElement).className) {
             const cls = (el as HTMLElement).className.toString().split(" ")[0];
             if (cls) selector = `${el.tagName.toLowerCase()}.${cls}`;
           }
           if (!selector) selector = `${el.tagName.toLowerCase()}:nth-of-type(${idx + 1})`;
 
           results.push({
             index: idx, text: (el.textContent || "").trim().slice(0, 50),
             x: Math.round(cx), y: Math.round(cy),
             width: rect.width, height: rect.height,
             area: rect.width * rect.height, centerDist, selector, hasBackground,
           });
           idx++;
         }
 
         results.sort((a, b) => {
           if (a.hasBackground !== b.hasBackground) return a.hasBackground ? -1 : 1;
           if (Math.abs(b.area - a.area) > 100) return b.area - a.area;
           return a.centerDist - b.centerDist;
         });
 
         return results;
       });
 
       for (const info of elementInfos) {
         if (budgetExceeded()) break;
         try {
           const wasVisible = await this.page.evaluate(
             ({ x, y }) => document.elementFromPoint(x, y) !== null,
             { x: info.x, y: info.y }
           );
           if (!wasVisible) continue;
 
           const before = await this.page.screenshot();
           this.log(`Clicking "${info.text}" (${info.selector}) at (${info.x},${info.y})`);
           await this.page.mouse.click(info.x, info.y);
           // Wait 300ms for JS to initialize after button click
           await this.page.waitForTimeout(300);
 
           const result = await this.detectVisualChange({ frames: 3, intervalMs: 100, before });
           if (result.changed) {
             // Check for immediate game over text (false start rejection)
             await this.page.waitForTimeout(200);
             const gameOverText = await this.detectGameOverText();
             if (gameOverText) {
               this.log(`Button "${info.text}" triggered game over immediately, rejecting`);
               continue;
             }
 
             const interactive = await this.verifyInteractivity();
             if (!interactive) {
               this.log(`Button "${info.text}" not interactive, continuing`);
               try { await this.page.keyboard.press("Escape"); await this.page.waitForTimeout(50); } catch {}
               continue;
             }
 
             const disappeared = await this.page.evaluate(
               ({ selector }) => {
                 if (!selector) return false;
                 try {
                   const el = document.querySelector(selector);
                   if (!el) return true;
                   const rect = el.getBoundingClientRect();
                   return rect.width === 0 || rect.height === 0;
                 } catch { return false; }
               },
               { selector: info.selector }
             );
 
             return {
               mechanism: "button",
               startButton: {
                 selector: info.selector, text: info.text,
                 disappeared, position: { x: info.x, y: info.y },
               },
             };
           }
 
           try { await this.page.keyboard.press("Escape"); await this.page.waitForTimeout(50); } catch {}
         } catch { /* continue */ }
       }
     } catch { /* phase failed */ }
     return null;
   }
 
   private async tryKeyboardTriggers(
     budgetExceeded: () => boolean
   ): Promise<{ mechanism: StartMechanism } | null> {
     const mechanismMap: Record<string, StartMechanism> = {
       Enter: "enter",
       Space: "space",
       ArrowDown: "anykey",
       z: "anykey",
     };
 
     for (const key of ["Enter", "Space", "ArrowDown", "z"]) {
       if (budgetExceeded()) break;
       try {
         const before = await this.page.screenshot();
         await this.page.keyboard.press(key);
         await this.page.waitForTimeout(100);
 
         const result = await this.detectVisualChange({ frames: 3, intervalMs: 100, before });
         if (result.changed) {
           const interactive = await this.verifyInteractivity();
           if (interactive) return { mechanism: mechanismMap[key] };
         }
       } catch { /* continue */ }
     }
 
     // Combo: click then key
     for (const key of ["Enter", "Space"]) {
       if (budgetExceeded()) break;
       try {
         const before = await this.page.screenshot();
         const canvas = this.page.locator("canvas").first();
         if ((await canvas.count()) > 0) await canvas.click();
         else {
           const vp = this.page.viewportSize();
           if (vp) await this.page.mouse.click(vp.width / 2, vp.height / 2);
         }
         await this.page.waitForTimeout(100);
         await this.page.keyboard.press(key);
         await this.page.waitForTimeout(100);
 
         const result = await this.detectVisualChange({ frames: 3, intervalMs: 100, before });
         if (result.changed) {
           const interactive = await this.verifyInteractivity();
           if (interactive) return { mechanism: mechanismMap[key] };
         }
       } catch { /* continue */ }
     }
 
     return null;
   }
 
   private async tryCanvasClicks(
     budgetExceeded: () => boolean
   ): Promise<{ mechanism: StartMechanism; startButton?: DriverCalibration["startButton"] } | null> {
     let targetBox: { x: number; y: number; width: number; height: number } | null = null;
 
     try {
       const canvas = this.page.locator("canvas").first();
       if ((await canvas.count()) > 0) targetBox = await canvas.boundingBox();
     } catch { /* no canvas */ }
 
     if (!targetBox) {
       const vp = this.page.viewportSize();
       if (vp) targetBox = { x: 0, y: 0, width: vp.width, height: vp.height };
     }
     if (!targetBox) return null;
 
     const cx = targetBox.x + targetBox.width / 2;
     const cy = targetBox.y + targetBox.height / 2;
 
     const positions = [
       { x: cx, y: cy, label: "center" },
       { x: cx, y: targetBox.y + targetBox.height * 0.25, label: "upper" },
       { x: cx, y: targetBox.y + targetBox.height * 0.75, label: "lower" },
     ];
 
     for (let row = 0; row < 3; row++) {
       for (let col = 0; col < 3; col++) {
         if (row === 1 && col === 1) continue;
         positions.push({
           x: targetBox.x + targetBox.width * (col + 0.5) / 3,
           y: targetBox.y + targetBox.height * (row + 0.5) / 3,
           label: `grid_${row}_${col}`,
         });
       }
     }
 
     for (const pos of positions) {
       if (budgetExceeded()) break;
       try {
         const before = await this.page.screenshot();
         await this.page.mouse.click(pos.x, pos.y);
         await this.page.waitForTimeout(300);
 
         const result = await this.detectVisualChange({ frames: 3, intervalMs: 100, before });
         if (result.changed) {
           const interactive = await this.verifyInteractivity();
           if (interactive) {
             return {
               mechanism: "click_canvas",
               startButton: {
                 selector: "canvas",
                 text: `canvas click at ${pos.label}`,
                 disappeared: false,
                 position: { x: Math.round(pos.x), y: Math.round(pos.y) },
               },
             };
           }
         }
       } catch { /* continue */ }
     }
 
     return null;
   }
 
   private async recalibrateWithRetry(
     currentStart: StartMechanism,
     currentGrid: GridBounds | null
   ): Promise<{
     renderer: RendererType; gridBounds: GridBounds | null;
     cellWidth: number; cellHeight: number; startMechanism: StartMechanism;
     startButton?: DriverCalibration["startButton"];
   }> {
     let startMechanism: StartMechanism = currentStart;
     let gridResult = { renderer: "unknown" as RendererType, gridBounds: currentGrid, cellWidth: 0, cellHeight: 0 };
     let startButton: DriverCalibration["startButton"] | undefined;
 
     const attempts: Array<{ name: StartMechanism; action: () => Promise<void> }> = [
       { name: "button", action: async () => {
         const btn = this.page.locator("button").first();
         if ((await btn.count()) > 0) await btn.click();
       }},
       { name: "click_canvas", action: async () => {
         const canvas = this.page.locator("canvas").first();
         if ((await canvas.count()) > 0) await canvas.click();
       }},
       { name: "click_canvas", action: async () => {
         await this.page.locator("body").click({ position: { x: 200, y: 200 } });
       }},
       { name: "enter", action: async () => { await this.page.keyboard.press("Enter"); } },
       { name: "space", action: async () => { await this.page.keyboard.press("Space"); } },
       { name: "anykey", action: async () => { await this.page.keyboard.press("ArrowDown"); } },
     ];
 
     for (const attempt of attempts) {
       try {
         const before = await this.page.screenshot();
         await attempt.action();
         await this.page.waitForTimeout(300);
 
         if (startMechanism === "unknown") {
           const result = await this.detectVisualChange({ frames: 3, intervalMs: 100, before });
           if (result.changed) {
             const interactive = await this.verifyInteractivity();
             if (interactive) {
               startMechanism = attempt.name;
             }
           }
         }
 
         if (!gridResult.gridBounds) {
           const detected = await this.detectGrid();
           if (detected.gridBounds) gridResult = detected;
         }
 
         if (startMechanism !== "unknown" && gridResult.gridBounds) break;
       } catch { /* continue */ }
     }
 
     return { ...gridResult, startMechanism, startButton };
   }
 
   // -- Grid detection --
 
   private async detectGrid(): Promise<{
     renderer: RendererType; gridBounds: GridBounds | null;
     cellWidth: number; cellHeight: number;
   }> {
     // Check for canvas
     try {
       const canvasCount = await this.page.locator("canvas").count();
       if (canvasCount > 0) {
         const bounds = await this.page.locator("canvas").first().boundingBox();
         if (bounds) {
           const canvasDims = await this.page.evaluate(() => {
             const c = document.querySelector("canvas");
             return c ? { width: c.width, height: c.height } : null;
           });
 
           const internalW = canvasDims ? canvasDims.width : bounds.width;
           const internalH = canvasDims ? canvasDims.height : bounds.height;
           const ratio = internalH / internalW;
 
           let gridX = 0, gridY = 0, gridW = internalW, gridH = internalH;
 
           if (ratio >= 1.5 && ratio <= 2.5) {
             // Whole canvas is the grid
           } else if (ratio < 1.5) {
             gridW = internalH / 2;
             gridH = internalH;
             gridX = 0;
             gridY = 0;
           }
 
           return {
             renderer: "canvas" as RendererType,
             gridBounds: { x: gridX, y: gridY, width: gridW, height: gridH },
             cellWidth: gridW / 10,
             cellHeight: gridH / 20,
           };
         }
       }
     } catch { /* continue */ }
 
     // Check for DOM-based grid
     try {
       const domResult = await this.page.evaluate(() => {
         const tables = document.querySelectorAll("table");
         for (const table of tables) {
           const rows = table.querySelectorAll("tr");
           if (rows.length >= 18) {
             const firstRow = rows[0].querySelectorAll("td");
             if (firstRow.length >= 8 && firstRow.length <= 12) {
               const rect = table.getBoundingClientRect();
               return { type: "dom" as const, bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }, rows: rows.length, cols: firstRow.length };
             }
           }
         }
 
         const containers = document.querySelectorAll(
           '[class*="board"], [class*="grid"], [class*="field"], [id*="board"], [id*="grid"], [id*="field"]'
         );
         for (const container of containers) {
           const children = container.children;
           if (children.length >= 180 && children.length <= 230) {
             const rect = container.getBoundingClientRect();
             return { type: "dom" as const, bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }, rows: Math.round(children.length / 10), cols: 10 };
           }
           if (children.length >= 18 && children.length <= 22) {
             const firstRowCells = children[0].children;
             if (firstRowCells.length >= 8 && firstRowCells.length <= 12) {
               const rect = container.getBoundingClientRect();
               return { type: "dom" as const, bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }, rows: children.length, cols: firstRowCells.length };
             }
           }
         }
 
         // Heuristic scan
         const allElements = document.querySelectorAll("div, section, main, article");
         for (const el of allElements) {
           const ch = el.children;
           if (ch.length >= 180 && ch.length <= 230) {
             const firstChild = ch[0] as HTMLElement;
             if (!firstChild) continue;
             const firstRect = firstChild.getBoundingClientRect();
             if (firstRect.width < 5 || firstRect.height < 5) continue;
             let uniform = true;
             for (let i = 1; i < Math.min(10, ch.length); i++) {
               const r = (ch[i] as HTMLElement).getBoundingClientRect();
               if (Math.abs(r.width - firstRect.width) > 2 || Math.abs(r.height - firstRect.height) > 2) { uniform = false; break; }
             }
             if (uniform) {
               const rect = el.getBoundingClientRect();
               return { type: "dom" as const, bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }, rows: Math.round(ch.length / 10), cols: 10 };
             }
           }
           if (ch.length >= 18 && ch.length <= 22) {
             const firstRowCells = ch[0]?.children;
             if (firstRowCells && firstRowCells.length >= 8 && firstRowCells.length <= 12) {
               const rect = el.getBoundingClientRect();
               if (rect.width > 50 && rect.height > 100) {
                 return { type: "dom" as const, bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }, rows: ch.length, cols: firstRowCells.length };
               }
             }
           }
         }
 
         return null;
       });
 
       if (domResult) {
         return {
           renderer: "dom",
           gridBounds: domResult.bounds,
           cellWidth: domResult.bounds.width / domResult.cols,
           cellHeight: domResult.bounds.height / domResult.rows,
         };
       }
     } catch { /* continue */ }
 
     // Check for SVG
     try {
       const svgCount = await this.page.locator("svg").count();
       if (svgCount > 0) {
         const bounds = await this.page.locator("svg").first().boundingBox();
         if (bounds) {
           return {
             renderer: "svg",
             gridBounds: { x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height },
             cellWidth: bounds.width / 10,
             cellHeight: bounds.height / 20,
           };
         }
       }
     } catch { /* continue */ }
 
     return { renderer: "unknown", gridBounds: null, cellWidth: 0, cellHeight: 0 };
   }
 
   // -- Control detection --
 
   private async detectControls(): Promise<Controls> {
     const controls: Controls = { ...DEFAULT_CONTROLS };
 
     try {
       const pageText = await this.page.evaluate(() => document.body.innerText.toLowerCase());
       if (pageText.includes("wasd") || pageText.includes("w,a,s,d")) {
         controls.left = "a"; controls.right = "d"; controls.down = "s"; controls.rotate = "w";
       }
       if (/z\s*(=|:)?\s*rotate/i.test(pageText)) controls.rotate = "z";
       if (/x\s*(=|:)?\s*rotate/i.test(pageText)) controls.rotate = "x";
     } catch { /* use defaults */ }
 
     try {
       const before = await this.page.screenshot();
       await this.page.keyboard.press(controls.left);
       await this.page.waitForTimeout(200);
       const after = await this.page.screenshot();
       if (Buffer.from(before).equals(Buffer.from(after))) {
         await this.page.keyboard.press("a");
         await this.page.waitForTimeout(200);
         const afterA = await this.page.screenshot();
         if (!Buffer.from(before).equals(Buffer.from(afterA))) {
           controls.left = "a"; controls.right = "d"; controls.down = "s"; controls.rotate = "w";
         }
       }
     } catch { /* use defaults */ }
 
     try {
       const before = await this.page.screenshot();
       await this.page.keyboard.press(controls.rotate);
       await this.page.waitForTimeout(200);
       const after = await this.page.screenshot();
       if (Buffer.from(before).equals(Buffer.from(after))) {
         for (const alt of ["z", "x", "ArrowUp"]) {
           if (alt === controls.rotate) continue;
           await this.page.keyboard.press(alt);
           await this.page.waitForTimeout(200);
           const afterAlt = await this.page.screenshot();
           if (!Buffer.from(before).equals(Buffer.from(afterAlt))) {
             controls.rotate = alt;
             break;
           }
         }
       }
     } catch { /* use defaults */ }
 
     return controls;
   }
 
   // -- Score/Level element detection --
 
   private async detectScoreElement(): Promise<string | null> {
     try {
       return await this.page.evaluate(() => {
         function _buildSelector(el: Element): string | null {
           if (el.id) return `#${el.id}`;
           if ((el as HTMLElement).className) {
             const cls = (el as HTMLElement).className.split(" ")[0];
             if (cls) return `.${cls}`;
           }
           return null;
         }
 
         const allElements = document.querySelectorAll("*");
 
         // Strategy 1: child near "score"/"puntuacion"/"puntaje" text with only a number
         for (const el of allElements) {
           const text = ((el as HTMLElement).innerText || "").toLowerCase();
           if ((text.includes("score") || text.includes("puntuacion") || text.includes("puntaje") || text.includes("puntos")) && el.children.length < 10) {
             const descendants = el.querySelectorAll("span, div, p, td, strong, em, b");
             for (const desc of descendants) {
               const descText = desc.textContent?.trim() || "";
               if (/^\d+$/.test(descText) && desc.children.length === 0) {
                 const sel = _buildSelector(desc);
                 if (sel) return sel;
               }
             }
             const next = el.nextElementSibling;
             if (next) {
               const nextText = next.textContent?.trim() || "";
               if (/^\d+$/.test(nextText)) {
                 const sel = _buildSelector(next);
                 if (sel) return sel;
               }
             }
             const sel = _buildSelector(el);
             if (sel) return sel;
           }
         }
 
         // Strategy 2: labeled text like "Score: 123"
         for (const el of allElements) {
           if (el.children.length > 3) continue;
           const text = (el as HTMLElement).textContent?.trim() || "";
           const scoreMatch = text.match(/(?:score|puntuacion|puntaje|puntos)\s*[:\-=]?\s*(\d+)/i);
           if (scoreMatch) {
             const sel = _buildSelector(el);
             if (sel) return sel;
           }
         }
 
         // Strategy 3: leaf elements with just a number
         const candidates: HTMLElement[] = [];
         for (const el of allElements) {
           const text = (el as HTMLElement).textContent?.trim() || "";
           if (/^\d+$/.test(text) && el.children.length === 0) candidates.push(el as HTMLElement);
         }
         if (candidates.length > 0) {
           const sel = _buildSelector(candidates[0]);
           if (sel) return sel;
         }
 
         return null;
       });
     } catch {
       return null;
     }
   }
 
   private async detectLevelElement(): Promise<string | null> {
     try {
       return await this.page.evaluate(() => {
         function _buildSelector(el: Element): string | null {
           if (el.id) return `#${el.id}`;
           if ((el as HTMLElement).className) {
             const cls = (el as HTMLElement).className.split(" ")[0];
             if (cls) return `.${cls}`;
           }
           return null;
         }
 
         const allElements = document.querySelectorAll("*");
         for (const el of allElements) {
           const text = ((el as HTMLElement).innerText || "").toLowerCase();
           if ((text.includes("level") || text.includes("nivel")) && el.children.length < 5) {
             const sel = _buildSelector(el);
             if (sel) return sel;
           }
         }
         return null;
       });
     } catch {
       return null;
     }
   }
 
   // -- Grid confidence --
 
   private async measureGridConfidence(cal: DriverCalibration): Promise<number> {
     if (!cal.gridBounds) return 0;
 
     let successes = 0;
     let attempts = 0;
     const pollCount = 6;
     let lastGrid: Grid | null = null;
     let gridChanged = false;
 
     for (let i = 0; i < pollCount; i++) {
       attempts++;
       try {
         const snap = await this.readGrid();
         if (snap.grid) {
           successes++;
           if (lastGrid) {
             if (this.gridsAreDifferent(snap.grid, lastGrid)) gridChanged = true;
           }
           lastGrid = snap.grid;
         }
       } catch { /* read failed */ }
       await this.page.waitForTimeout(500);
     }
 
     if (successes > 0 && !gridChanged && cal.startMechanism !== "unknown") {
       const additionalStarts: Array<{ name: string; action: () => Promise<void> }> = [
         { name: "space", action: async () => { await this.page.keyboard.press("Space"); } },
         { name: "enter", action: async () => { await this.page.keyboard.press("Enter"); } },
         { name: "click", action: async () => {
           const canvas = this.page.locator("canvas").first();
           if ((await canvas.count()) > 0) await canvas.click();
           else await this.page.locator("body").click({ position: { x: 200, y: 200 } });
         }},
       ];
 
       for (const start of additionalStarts) {
         try {
           await start.action();
           await this.page.waitForTimeout(1500);
           const snap = await this.readGrid();
           if (snap.grid && lastGrid) {
             if (this.gridsAreDifferent(snap.grid, lastGrid)) { gridChanged = true; break; }
             lastGrid = snap.grid;
           }
         } catch { /* continue */ }
       }
     }
 
     return attempts > 0 ? successes / attempts : 0;
   }
 
   // -- Helpers --
 
   private extractScoreFromText(text: string | null): number[] {
     if (!text) return [0];
     const labeledMatch = text.match(/(?:score|puntuacion|puntaje|puntos)\s*[:\-=]?\s*(\d+)/i);
     if (labeledMatch) return [parseInt(labeledMatch[1], 10)];
     const allNumbers = (text.match(/\d+/g) || []).map(Number);
     return allNumbers.length > 0 ? allNumbers : [0];
   }
 }