loop-benchmarking

calibrate.ts (47089B)

---

 import type { Page } from "@playwright/test";
 import type {
   CalibrationResult,
   Controls,
   GridBounds,
   RendererType,
   StartMechanism,
   SurveyData,
 } from "./types";
 import { sampleBackgroundColor, readGrid } from "./grid-reader";
 
 const DEFAULT_CONTROLS: Controls = {
   left: "ArrowLeft",
   right: "ArrowRight",
   down: "ArrowDown",
   rotate: "ArrowUp",
   drop: "Space",
 };
 
 /**
  * Run all calibration steps. Never throws -- returns a result
  * with whatever could be detected.
  */
 export async function calibrate(page: Page): Promise<CalibrationResult> {
   const consoleErrors: string[] = [];
   page.on("pageerror", (err) => consoleErrors.push(err.message));
 
   // Wait for DOM to fully settle (scripts, animations, timers)
   await page.waitForTimeout(2000);
 
   let startResult = await detectStartMechanism(page);
   let startMechanism: StartMechanism = startResult.mechanism;
   let startButton = startResult.startButton;
   let { renderer, gridBounds, cellWidth, cellHeight } = await detectGrid(page);
   let backgroundColor =
     renderer === "canvas" && gridBounds
       ? await sampleBackgroundColor(page, gridBounds, cellWidth, cellHeight)
       : null;
 
   // Re-calibration fallback: if start or grid detection failed, retry with
   // longer waits and re-scan after each start attempt
   if (startMechanism === "unknown" || gridBounds === null) {
     const retry = await recalibrateWithRetry(page, startMechanism, gridBounds);
     if (retry.startMechanism !== "unknown") startMechanism = retry.startMechanism;
     if (retry.gridBounds) {
       renderer = retry.renderer;
       gridBounds = retry.gridBounds;
       cellWidth = retry.cellWidth;
       cellHeight = retry.cellHeight;
       backgroundColor =
         renderer === "canvas" && gridBounds
           ? await sampleBackgroundColor(page, gridBounds, cellWidth, cellHeight)
           : null;
     }
   }
 
   const controls = await detectControls(page);
   const scoreElementSelector = await detectScoreElement(page);
 
   // Grid confidence: poll grid reads to measure reliability
   const gridConfidence = await measureGridConfidence(page, {
     renderer,
     gridDetected: gridBounds !== null,
     gridBounds,
     cellWidth,
     cellHeight,
     controls,
     startMechanism,
     scoreElementSelector,
     backgroundColor,
     consoleErrors,
     gridConfidence: 0,
   });
 
   const result: CalibrationResult = {
     renderer,
     gridDetected: gridBounds !== null,
     gridBounds,
     cellWidth,
     cellHeight,
     controls,
     startMechanism,
     scoreElementSelector,
     backgroundColor,
     consoleErrors,
     gridConfidence,
   };
 
   if (startButton) {
     result.startButton = startButton;
   }
 
   return result;
 }
 
 /**
  * Measure grid read confidence by polling several times.
  * If the grid never changes despite the game being "started", try
  * more start mechanisms.
  */
 async function measureGridConfidence(
   page: Page,
   cal: CalibrationResult
 ): Promise<number> {
   if (!cal.gridBounds) return 0;
 
   let successes = 0;
   let attempts = 0;
   const pollCount = 6;
   let lastGrid: boolean[][] | null = null;
   let gridChanged = false;
 
   for (let i = 0; i < pollCount; i++) {
     attempts++;
     try {
       const grid = await readGrid(page, cal);
       if (grid) {
         successes++;
         if (lastGrid) {
           // Check if grid actually changed (game is running)
           for (let r = 0; r < grid.length && !gridChanged; r++) {
             for (let c = 0; c < grid[r].length && !gridChanged; c++) {
               if (grid[r][c] !== lastGrid[r][c]) gridChanged = true;
             }
           }
         }
         lastGrid = grid;
       }
     } catch {
       // read failed
     }
     await page.waitForTimeout(500);
   }
 
   // If grid reads succeed but grid never changed after 3 seconds,
   // try additional start mechanisms
   if (successes > 0 && !gridChanged && cal.startMechanism !== "unknown") {
     const additionalStarts: Array<{ name: string; action: () => Promise<void> }> = [
       { name: "space", action: async () => { await page.keyboard.press("Space"); } },
       { name: "enter", action: async () => { await page.keyboard.press("Enter"); } },
       { name: "click", action: async () => {
         const canvas = page.locator("canvas").first();
         if ((await canvas.count()) > 0) await canvas.click();
         else await page.locator("body").click({ position: { x: 200, y: 200 } });
       }},
     ];
 
     for (const start of additionalStarts) {
       try {
         await start.action();
         await page.waitForTimeout(1500);
         const grid = await readGrid(page, cal);
         if (grid && lastGrid) {
           for (let r = 0; r < grid.length && !gridChanged; r++) {
             for (let c = 0; c < grid[r].length && !gridChanged; c++) {
               if (grid[r][c] !== lastGrid[r][c]) gridChanged = true;
             }
           }
           if (gridChanged) break;
           lastGrid = grid;
         }
       } catch { /* continue */ }
     }
   }
 
   return attempts > 0 ? successes / attempts : 0;
 }
 
 /**
  * Take a screenshot and sample it into a grid of "colored" (true) / "background" (false)
  * values. Reusable building block for visual change detection.
  */
 async function sampleScreenshot(
   page: Page,
   sampleCols: number,
   sampleRows: number,
   colorThreshold: number = 40
 ): Promise<boolean[][]> {
   const shot = await page.screenshot();
   const base64 = shot.toString("base64");
   const grid = await page.evaluate(
     async ({ base64, sampleCols, sampleRows, colorThreshold }) => {
       const img = new Image();
       const loaded = new Promise<void>((resolve, reject) => {
         img.onload = () => resolve();
         img.onerror = () => reject(new Error("image decode failed"));
       });
       img.src = `data:image/png;base64,${base64}`;
       await loaded;
 
       const canvas = document.createElement("canvas");
       canvas.width = img.width;
       canvas.height = img.height;
       const ctx = canvas.getContext("2d")!;
       ctx.drawImage(img, 0, 0);
 
       const stepX = img.width / sampleCols;
       const stepY = img.height / sampleRows;
 
       const colors: number[][] = [];
       for (let r = 0; r < sampleRows; r++) {
         const row: number[] = [];
         for (let c = 0; c < sampleCols; c++) {
           const px = Math.floor(c * stepX + stepX / 2);
           const py = Math.floor(r * stepY + stepY / 2);
           const pixel = ctx.getImageData(px, py, 1, 1).data;
           row.push(pixel[0] * 1000000 + pixel[1] * 1000 + pixel[2]);
         }
         colors.push(row);
       }
 
       const colorCounts = new Map<number, number>();
       for (const row of colors) {
         for (const c of row) {
           colorCounts.set(c, (colorCounts.get(c) || 0) + 1);
         }
       }
       let bgColor = 0;
       let bgCount = 0;
       for (const [color, count] of colorCounts) {
         if (count > bgCount) {
           bgCount = count;
           bgColor = color;
         }
       }
       const bgR = Math.floor(bgColor / 1000000);
       const bgG = Math.floor((bgColor % 1000000) / 1000);
       const bgB = bgColor % 1000;
 
       const result: boolean[][] = [];
       for (let r = 0; r < sampleRows; r++) {
         const row: boolean[] = [];
         for (let c = 0; c < sampleCols; c++) {
           const v = colors[r][c];
           const pR = Math.floor(v / 1000000);
           const pG = Math.floor((v % 1000000) / 1000);
           const pB = v % 1000;
           const dist = Math.sqrt(
             (pR - bgR) ** 2 + (pG - bgG) ** 2 + (pB - bgB) ** 2
           );
           row.push(dist > colorThreshold);
         }
         result.push(row);
       }
       return result;
     },
     { base64, sampleCols, sampleRows, colorThreshold }
   );
   return grid;
 }
 
 /**
  * Detect visual change by comparing screenshots.
  *
  * Takes a "before" reference screenshot (optional) and a series of "after" screenshots.
  * If before is provided, compares before vs each after frame.
  * Otherwise compares consecutive after frames (for auto-start detection where
  * animation should be continuously visible).
  *
  * Uses raw buffer comparison: if bytes differ, something changed.
  */
 async function detectVisualChange(
   page: Page,
   options?: { frames?: number; intervalMs?: number; before?: Buffer }
 ): Promise<{ changed: boolean; gameplayDetected: boolean }> {
   const FRAMES = options?.frames ?? 6;
   const INTERVAL = options?.intervalMs ?? 200;
 
   const screenshots: Buffer[] = [];
   for (let i = 0; i < FRAMES; i++) {
     screenshots.push(await page.screenshot());
     if (i < FRAMES - 1) await page.waitForTimeout(INTERVAL);
   }
 
   let changed = false;
 
   console.log(`[detect] ${FRAMES} frames captured, sizes: [${screenshots.map(s => s.length).join(",")}]${options?.before ? `, before=${options.before.length}` : ""}`);
 
   if (options?.before) {
     // Compare before-action screenshot against each after-action frame
     for (let i = 0; i < screenshots.length; i++) {
       const same = options.before.equals(screenshots[i]);
       console.log(`[detect] before vs frame[${i}]: ${same ? "SAME" : "DIFF"} (${screenshots[i].length} bytes)`);
       if (!same) {
         changed = true;
         break;
       }
     }
   } else {
     // No before reference: compare consecutive frames (for auto-start detection)
     // Also extend window: take one more shot after a longer pause to catch slow drops
     await page.waitForTimeout(1200);
     const lateFrame = await page.screenshot();
 
     for (let f = 0; f < screenshots.length - 1; f++) {
       if (!screenshots[f].equals(screenshots[f + 1])) {
         changed = true;
         console.log(`[detect] consecutive frames ${f} vs ${f+1}: DIFF`);
         break;
       }
     }
     // Also compare first frame against the late frame (catches 1000ms drop intervals)
     if (!changed && !screenshots[0].equals(lateFrame)) {
       changed = true;
       console.log(`[detect] first vs late frame: DIFF`);
     }
     if (!changed) console.log(`[detect] all frames identical (no animation)`);
   }
 
   // gameplayDetected: if something changed, assume gameplay (simplification).
   // The old Level 2 "downward movement" check was unreliable due to sampling issues.
   // Grid reader in later phases verifies actual gameplay definitively.
   return { changed, gameplayDetected: changed };
 }
 
 /**
  * Verify that the game is actually interactive -- gameplay inputs cause
  * visible state changes. This distinguishes a truly started game from
  * animations, overlays, or other false positives.
  *
  * Sends ArrowLeft then ArrowRight and checks if the page responds.
  * A game that started will move a piece; a static page won't change.
  */
 async function verifyInteractivity(page: Page): Promise<boolean> {
   try {
     // Wait for at least one render frame before baseline
     await page.waitForTimeout(200);
 
     // Capture baseline: both screenshot and DOM state
     const baseline = await page.screenshot();
     const domBefore = await page.evaluate(() => {
       // Snapshot the largest grid-like container's child class/style state
       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;
       }
       // Also capture body innerHTML hash as fallback
       if (!best) best = document.body.innerHTML.substring(0, 5000);
       return best;
     });
 
     // Try multiple inputs
     for (const key of ["ArrowLeft", "ArrowRight", "ArrowDown"]) {
       await page.keyboard.press(key);
       await page.waitForTimeout(200);
 
       // Check screenshot change
       const after = await page.screenshot();
       if (!baseline.equals(after)) {
         return true;
       }
 
       // Check DOM state change (catches games where screenshot is identical
       // but DOM classes/styles changed -- e.g. innerHTML-rebuilt grids)
       const domAfter = await 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;
   }
 }
 
 /**
  * Cluster adjacent points using flood fill.
  * Two points are adjacent if they differ by at most 1 in both row and column.
  */
 function clusterPoints(points: [number, number][]): [number, number][][] {
   const clusters: [number, number][][] = [];
   const visited = new Set<string>();
 
   for (const [r, c] of points) {
     const key = `${r},${c}`;
     if (visited.has(key)) continue;
 
     const cluster: [number, number][] = [];
     const stack: [number, number][] = [[r, c]];
     visited.add(key);
 
     while (stack.length > 0) {
       const [cr, cc] = stack.pop()!;
       cluster.push([cr, cc]);
 
       // Check all 8 neighbors
       for (let dr = -1; dr <= 1; dr++) {
         for (let dc = -1; dc <= 1; dc++) {
           if (dr === 0 && dc === 0) continue;
           const nr = cr + dr;
           const nc = cc + dc;
           const nk = `${nr},${nc}`;
           if (!visited.has(nk) && points.some(([pr, pc]) => pr === nr && pc === nc)) {
             visited.add(nk);
             stack.push([nr, nc]);
           }
         }
       }
     }
 
     clusters.push(cluster);
   }
 
   return clusters;
 }
 
 /** Result of the 5-phase start detection. */
 interface StartDetectionResult {
   mechanism: StartMechanism;
   startButton?: CalibrationResult["startButton"];
 }
 
 /**
  * 5-phase start detection. Fully language-agnostic, visual-first.
  * No text matching of any kind -- detection is purely structural and behavioral.
  *
  * Phase 1: Auto-start (no input, visual change detection)
  * Phase 2: Keyboard triggers (Enter, Space, ArrowDown, Z -- fast, universal)
  * Phase 3: DOM button discovery (click all clickable elements by visual prominence)
  * Phase 4: Canvas click grid (for canvas-rendered buttons)
  * Phase 5: Retry phases 2-4 (some games need two interactions)
  *
  * Total budget: 30 seconds.
  */
 async function detectStartMechanism(page: Page): Promise<StartDetectionResult> {
   const deadline = Date.now() + 30000;
   const log = (msg: string) => console.log(`[start-detect] ${msg}`);
 
   const budgetExceeded = () => Date.now() >= deadline;
 
   // Quick diagnostic: what's on the page?
   try {
     const diag = await 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,
     }));
     log(`Page: "${diag.title}", ${diag.buttons.length} buttons [${diag.buttons.join(", ")}], ${diag.canvases} canvases, body=${diag.bodySize} chars`);
   } catch (e) { log(`Diagnostic failed: ${e}`); }
 
   // ---- Phase 1: Auto-start (no input, ~2.5 seconds with late check) ----
   {
     log("Phase 1: checking auto-start...");
     const result = await detectVisualChange(page, { frames: 6, intervalMs: 200 });
     log(`Phase 1 result: changed=${result.changed}`);
     if (result.changed) {
       const interactive = await verifyInteractivity(page);
       if (interactive) {
         return { mechanism: "auto" };
       }
       log("Phase 1: visual change detected but game not interactive (animation?)");
     }
   }
 
   // ---- Phase 2: Keyboard triggers (fast, language-agnostic) ----
   if (!budgetExceeded()) {
     log("Phase 2: trying keyboard triggers...");
     const phase2Result = await tryKeyboardTriggers(page, budgetExceeded);
     if (phase2Result) {
       log(`Phase 2 result: found=${phase2Result.mechanism}`);
       return phase2Result;
     }
     log("Phase 2 result: none");
   }
 
   // ---- Phase 3: DOM button discovery (language-agnostic, visual-only) ----
   if (!budgetExceeded()) {
     log("Phase 3: trying DOM buttons...");
     const phase3Result = await tryDomButtons(page, budgetExceeded);
     log(`Phase 3 result: ${phase3Result ? `found=${phase3Result.mechanism}` : "none"}`);
     if (phase3Result) return phase3Result;
   }
 
   // ---- Phase 4: Canvas click grid ----
   if (!budgetExceeded()) {
     log("Phase 4: trying canvas clicks...");
     const phase4Result = await tryCanvasClicks(page, budgetExceeded);
     if (phase4Result) return phase4Result;
   }
 
   // ---- Phase 5: Retry phases 2-4 (some games need two interactions) ----
   if (!budgetExceeded()) {
     const phase2Retry = await tryKeyboardTriggers(page, budgetExceeded);
     if (phase2Retry) return phase2Retry;
   }
   if (!budgetExceeded()) {
     const phase3Retry = await tryDomButtons(page, budgetExceeded);
     if (phase3Retry) return phase3Retry;
   }
   if (!budgetExceeded()) {
     const phase4Retry = await tryCanvasClicks(page, budgetExceeded);
     if (phase4Retry) return phase4Retry;
   }
 
   return { mechanism: "unknown" };
 }
 
 /**
  * Phase 2: Find all clickable DOM elements (fully language-agnostic, no text matching).
  * Finds buttons, anchors, role=button, onclick, and cursor:pointer elements.
  * Sort by visual prominence (size, centrality, contrast). Click each and observe.
  */
 async function tryDomButtons(
   page: Page,
   budgetExceeded: () => boolean
 ): Promise<StartDetectionResult | null> {
   try {
     // Gather element info (position, size, text) for sorting -- purely structural/visual
     const elementInfos = await 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;
       }> = [];
 
       // Phase A: structural clickable elements (type-based, no text matching)
       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);
       }
 
       // Phase B: elements with cursor:pointer computed style (catches custom divs/spans acting as buttons)
       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;
         // Skip elements that cover most of the viewport (overlays, not buttons)
         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);
 
         // Check if element has a distinct background (high contrast, likely a button)
         let hasBackground = false;
         try {
           const style = window.getComputedStyle(el as HTMLElement);
           const bg = style.backgroundColor;
           // transparent or rgba(0,0,0,0) means no background
           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++;
       }
 
       // Sort by visual prominence:
       // 1. Elements with background first (more likely to be buttons)
       // 2. Larger elements first
       // 3. Closer to center preferred
       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;
     });
 
     console.log(`[start-detect] Phase 2: found ${elementInfos.length} clickable elements`);
     // Click each element and observe for visual change
     for (const info of elementInfos) {
       if (budgetExceeded()) break;
 
       try {
         // Check if element still exists before clicking
         const wasVisible = await page.evaluate(
           ({ x, y }) => {
             const el = document.elementFromPoint(x, y);
             return el !== null;
           },
           { x: info.x, y: info.y }
         );
         if (!wasVisible) continue;
 
         // Take "before" screenshot, then click, then compare
         const before = await page.screenshot();
         console.log(`[start-detect] Clicking "${info.text}" (${info.selector}) at (${info.x},${info.y}), before=${before.length} bytes`);
         await page.mouse.click(info.x, info.y);
         await page.waitForTimeout(100);
 
         const result = await detectVisualChange(page, { frames: 3, intervalMs: 100, before });
         console.log(`[start-detect] After click "${info.text}": changed=${result.changed}`);
         if (result.changed) {
           // Wait for the game to fully initialize after button click
           await page.waitForTimeout(300);
           // Verify the game is actually interactive after clicking this button
           const interactive = await verifyInteractivity(page);
           if (!interactive) {
             console.log(`[start-detect] Button "${info.text}" caused visual change but game not interactive, continuing...`);
             // Try pressing Escape to undo and continue
             try { await page.keyboard.press("Escape"); await page.waitForTimeout(50); } catch {}
             continue;
           }
 
           // Check if the element disappeared after clicking
           const disappeared = await 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 },
             },
           };
         }
 
         // No change -- try pressing Escape to undo any menu we opened
         try {
           await page.keyboard.press("Escape");
           await page.waitForTimeout(50);
         } catch { /* ignore */ }
       } catch { /* continue to next element */ }
     }
   } catch { /* phase 2 failed entirely */ }
 
   return null;
 }
 
 /**
  * Phase 3: Click the canvas at strategic positions.
  * Center first, then upper-center, lower-center, then a 3x3 grid.
  */
 async function tryCanvasClicks(
   page: Page,
   budgetExceeded: () => boolean
 ): Promise<StartDetectionResult | null> {
   // Find the canvas or primary game container
   let targetBox: { x: number; y: number; width: number; height: number } | null = null;
 
   try {
     const canvas = page.locator("canvas").first();
     if ((await canvas.count()) > 0) {
       targetBox = await canvas.boundingBox();
     }
   } catch { /* no canvas */ }
 
   if (!targetBox) {
     // Try the viewport itself
     const viewport = page.viewportSize();
     if (viewport) {
       targetBox = { x: 0, y: 0, width: viewport.width, height: viewport.height };
     }
   }
 
   if (!targetBox) return null;
 
   const cx = targetBox.x + targetBox.width / 2;
   const cy = targetBox.y + targetBox.height / 2;
 
   // Click positions: center, upper-center, lower-center, then 3x3 grid
   const positions: Array<{ x: number; y: number; label: string }> = [
     { x: cx, y: cy, label: "center" },
     { x: cx, y: targetBox.y + targetBox.height * 0.25, label: "upper-center" },
     { x: cx, y: targetBox.y + targetBox.height * 0.75, label: "lower-center" },
   ];
 
   // Add 3x3 grid positions (skip center since we already have it)
   for (let row = 0; row < 3; row++) {
     for (let col = 0; col < 3; col++) {
       if (row === 1 && col === 1) continue; // skip center duplicate
       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 page.screenshot();
       await page.mouse.click(pos.x, pos.y);
       await page.waitForTimeout(100);
 
       const result = await detectVisualChange(page, { frames: 3, intervalMs: 100, before });
       if (result.changed) {
         const interactive = await verifyInteractivity(page);
         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) },
             },
           };
         }
         console.log(`[start-detect] Canvas click at ${pos.label} caused change but not interactive`);
       }
     } catch { /* continue */ }
   }
 
   return null;
 }
 
 /**
  * Phase 4: Keyboard triggers.
  * Try Enter, Space, ArrowDown, Z individually,
  * then click-then-Enter and click-then-Space combos.
  */
 async function tryKeyboardTriggers(
   page: Page,
   budgetExceeded: () => boolean
 ): Promise<StartDetectionResult | null> {
   const mechanismMap: Record<string, StartMechanism> = {
     Enter: "enter",
     Space: "space",
     ArrowDown: "anykey",
     z: "anykey",
   };
 
   // Single key presses
   for (const key of ["Enter", "Space", "ArrowDown", "z"]) {
     if (budgetExceeded()) break;
 
     try {
       const before = await page.screenshot();
       await page.keyboard.press(key);
       await page.waitForTimeout(100);
 
       const result = await detectVisualChange(page, { frames: 3, intervalMs: 100, before });
       if (result.changed) {
         // Verify the game is actually interactive, not just an animation
         const interactive = await verifyInteractivity(page);
         if (interactive) {
           return { mechanism: mechanismMap[key] };
         }
         console.log(`[start-detect] ${key} caused visual change but game not interactive, continuing...`);
       }
     } catch { /* continue */ }
   }
 
   // Combo: click canvas center, then Enter / Space
   for (const key of ["Enter", "Space"]) {
     if (budgetExceeded()) break;
 
     try {
       const before = await page.screenshot();
       const canvas = page.locator("canvas").first();
       if ((await canvas.count()) > 0) {
         await canvas.click();
       } else {
         const viewport = page.viewportSize();
         if (viewport) {
           await page.mouse.click(viewport.width / 2, viewport.height / 2);
         }
       }
       await page.waitForTimeout(100);
       await page.keyboard.press(key);
       await page.waitForTimeout(100);
 
       const result = await detectVisualChange(page, { frames: 3, intervalMs: 100, before });
       if (result.changed) {
         const interactive = await verifyInteractivity(page);
         if (interactive) {
           return { mechanism: mechanismMap[key] };
         }
         console.log(`[start-detect] ${key}+click caused visual change but game not interactive, continuing...`);
       }
     } catch { /* continue */ }
   }
 
   return null;
 }
 
 /**
  * Re-calibration fallback: try start mechanisms again with longer waits,
  * re-scanning for the grid after each attempt. Used when the first pass
  * failed to detect the start mechanism or the grid.
  *
  * Uses detectVisualChange() to confirm the game responded.
  */
 async function recalibrateWithRetry(
   page: Page,
   currentStart: StartMechanism,
   currentGrid: GridBounds | null
 ): Promise<GridDetection & { startMechanism: StartMechanism }> {
   let startMechanism: StartMechanism = currentStart;
   let gridResult: GridDetection = {
     renderer: "unknown",
     gridBounds: currentGrid,
     cellWidth: 0,
     cellHeight: 0,
   };
 
   const attempts: Array<{ name: StartMechanism; action: () => Promise<void> }> = [
     {
       name: "click_canvas",
       action: async () => {
         const canvas = page.locator("canvas").first();
         if ((await canvas.count()) > 0) await canvas.click();
       },
     },
     {
       name: "click_canvas",
       action: async () => {
         await page.locator("body").click({ position: { x: 200, y: 200 } });
       },
     },
     {
       name: "enter",
       action: async () => { await page.keyboard.press("Enter"); },
     },
     {
       name: "space",
       action: async () => { await page.keyboard.press("Space"); },
     },
     {
       name: "button",
       action: async () => {
         const btn = page.locator("button").first();
         if ((await btn.count()) > 0) await btn.click();
       },
     },
     {
       name: "anykey",
       action: async () => { await page.keyboard.press("ArrowDown"); },
     },
   ];
 
   for (const attempt of attempts) {
     try {
       const before = await page.screenshot();
       await attempt.action();
       await page.waitForTimeout(100);
 
       if (startMechanism === "unknown") {
         const result = await detectVisualChange(page, { frames: 3, intervalMs: 100, before });
         if (result.changed) {
           startMechanism = attempt.name;
         }
       }
 
       // Re-scan for grid after each attempt
       if (!gridResult.gridBounds) {
         const detected = await detectGrid(page);
         if (detected.gridBounds) {
           gridResult = detected;
         }
       }
 
       // If we have both, stop early
       if (startMechanism !== "unknown" && gridResult.gridBounds) {
         break;
       }
     } catch { /* continue */ }
   }
 
   return { ...gridResult, startMechanism };
 }
 
 interface GridDetection {
   renderer: RendererType;
   gridBounds: GridBounds | null;
   cellWidth: number;
   cellHeight: number;
 }
 
 /**
  * Detect the game grid: canvas, DOM-based, or SVG.
  */
 async function detectGrid(page: Page): Promise<GridDetection> {
   // Check for canvas
   try {
     const canvasCount = await page.locator("canvas").count();
     if (canvasCount > 0) {
       const bounds = await page.locator("canvas").first().boundingBox();
       if (bounds) {
         // Try to get the canvas internal dimensions (which may differ from CSS size)
         const canvasDims = await page.evaluate(() => {
           const c = document.querySelector("canvas");
           if (!c) return null;
           return { width: c.width, height: c.height };
         });
 
         const internalW = canvasDims ? canvasDims.width : bounds.width;
         const internalH = canvasDims ? canvasDims.height : bounds.height;
 
         // Standard Tetris grid is 10 cols by 20 rows
         // The canvas might include sidebars, so try to detect the grid area
         // Heuristic: if the aspect ratio is close to 1:2, the whole canvas is the grid
         const ratio = internalH / internalW;
 
         let gridX = 0;
         let gridY = 0;
         let gridW = internalW;
         let gridH = internalH;
 
         if (ratio >= 1.5 && ratio <= 2.5) {
           // Looks like the whole canvas is the grid
           gridX = 0;
           gridY = 0;
           gridW = internalW;
           gridH = internalH;
         } else if (ratio < 1.5) {
           // Canvas is wider than expected -- grid is probably a subset
           // Assume grid is centered or left-aligned with 1:2 aspect ratio
           gridW = internalH / 2;
           gridH = internalH;
           gridX = 0; // left-aligned by default
           gridY = 0;
         }
 
         const cellWidth = gridW / 10;
         const cellHeight = gridH / 20;
 
         return {
           renderer: "canvas" as RendererType,
           gridBounds: { x: gridX, y: gridY, width: gridW, height: gridH },
           cellWidth,
           cellHeight,
         };
       }
     }
   } catch { /* continue */ }
 
   // Check for DOM-based grid
   try {
     const domResult = await page.evaluate(() => {
       // Look for table-based grids
       const tables = document.querySelectorAll("table");
       for (const table of tables) {
         const rows = table.querySelectorAll("tr");
         if (rows.length >= 18) {
           // Likely a Tetris grid (might be 18-22 rows)
           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,
             };
           }
         }
       }
 
       // Look for grid/flex 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;
         // Flat list of 200 cells (or close to it)
         if (children.length >= 180 && children.length <= 220) {
           const cols = 10;
           const rows = Math.round(children.length / cols);
           const rect = container.getBoundingClientRect();
           return {
             type: "dom" as const,
             bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
             rows,
             cols,
           };
         }
         // 20 row containers
         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: look for ANY container with many same-sized children
       // arranged in a grid pattern, even without specific class/id naming
       const allElements = document.querySelectorAll("div, section, main, article");
       for (const el of allElements) {
         const ch = el.children;
         // Flat list of ~200 cells (10x20)
         if (ch.length >= 180 && ch.length <= 220) {
           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 cols = 10;
             const rows = Math.round(ch.length / cols);
             const rect = el.getBoundingClientRect();
             return {
               type: "dom" as const,
               bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
               rows,
               cols,
             };
           }
         }
         // Container with ~20 row children, each having ~10 cell children
         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) {
       const cellWidth = domResult.bounds.width / domResult.cols;
       const cellHeight = domResult.bounds.height / domResult.rows;
       return {
         renderer: "dom",
         gridBounds: domResult.bounds,
         cellWidth,
         cellHeight,
       };
     }
   } catch { /* continue */ }
 
   // Check for SVG
   try {
     const svgCount = await page.locator("svg").count();
     if (svgCount > 0) {
       const bounds = await 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 };
 }
 
 /**
  * Detect which keys the game responds to for movement and rotation.
  */
 async function detectControls(page: Page): Promise<Controls> {
   const controls: Controls = { ...DEFAULT_CONTROLS };
 
   // First, scan the page for control hints
   try {
     const pageText = await 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) || /rotate\s*(=|:)?\s*z/i.test(pageText)) {
       controls.rotate = "z";
     }
     if (/x\s*(=|:)?\s*rotate/i.test(pageText) || /rotate\s*(=|:)?\s*x/i.test(pageText)) {
       controls.rotate = "x";
     }
   } catch { /* use defaults */ }
 
   // Verify left key works by pressing and checking for visual change
   try {
     const before = await page.screenshot();
     await page.keyboard.press(controls.left);
     await page.waitForTimeout(200);
     const after = await page.screenshot();
 
     if (Buffer.from(before).equals(Buffer.from(after))) {
       // ArrowLeft didn't work, try "a"
       await page.keyboard.press("a");
       await page.waitForTimeout(200);
       const afterA = await 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 */ }
 
   // Verify rotate key
   try {
     const before = await page.screenshot();
     await page.keyboard.press(controls.rotate);
     await page.waitForTimeout(200);
     const after = await page.screenshot();
 
     if (Buffer.from(before).equals(Buffer.from(after))) {
       // Try alternative rotate keys
       for (const alt of ["z", "x", "ArrowUp"]) {
         if (alt === controls.rotate) continue;
         await page.keyboard.press(alt);
         await page.waitForTimeout(200);
         const afterAlt = await page.screenshot();
         if (!Buffer.from(before).equals(Buffer.from(afterAlt))) {
           controls.rotate = alt;
           break;
         }
       }
     }
   } catch { /* use defaults */ }
 
   return controls;
 }
 
 /**
  * Find the score display element on the page.
  *
  * Prefers elements that contain ONLY the score number (a child element
  * whose textContent is a standalone number). This avoids selecting a
  * parent that concatenates "Score: 100Level: 1Lines: 5" into one text node.
  */
 async function detectScoreElement(page: Page): Promise<string | null> {
   try {
     const selector = await 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;
       }
 
       // Strategy 1: Find a child element near "score" text that contains
       // ONLY a single number (the narrowest, most reliable match).
       const allElements = document.querySelectorAll("*");
       for (const el of allElements) {
         const text = (el as HTMLElement).innerText?.toLowerCase() || "";
         if (text.includes("score") && el.children.length < 10) {
           // Look for a child/descendant with ONLY a number
           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;
             }
           }
 
           // Check siblings of the "score" label element
           const next = el.nextElementSibling;
           if (next) {
             const nextText = next.textContent?.trim() || "";
             if (/^\d+$/.test(nextText)) {
               const sel = _buildSelector(next);
               if (sel) return sel;
             }
           }
 
           // Fall back to the element itself, but only if it looks reasonable.
           // Check if the element's own text (without children) contains "score"
           // and has a parseable score value.
           const sel = _buildSelector(el);
           if (sel) return sel;
         }
       }
 
       // Strategy 2: Look for labeled text like "Score: 123" in leaf elements
       for (const el of allElements) {
         if (el.children.length > 3) continue;
         const text = (el as HTMLElement).textContent?.trim() || "";
         const scoreMatch = text.match(/score\s*[:\-=]?\s*(\d+)/i);
         if (scoreMatch) {
           // This element contains labeled score text
           const sel = _buildSelector(el);
           if (sel) return sel;
         }
       }
 
       // Strategy 3: Fallback: look for leaf elements that contain 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 el = candidates[0];
         const sel = _buildSelector(el);
         if (sel) return sel;
       }
 
       return null;
     });
 
     return selector;
   } catch {
     return null;
   }
 }
 
 /**
  * Survey the page before any tests run. Collects information about the page
  * structure that helps inform start mechanism detection and debugging.
  */
 export async function surveyPage(page: Page): Promise<SurveyData> {
   try {
     const data = await page.evaluate(() => {
       // Check for full-screen overlay (language-agnostic: purely structural detection)
       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) {
               // Large positioned overlay detected -- no text matching needed
               hasOverlay = true;
               break;
             }
           }
         }
       }
 
       // Check for canvas
       const hasCanvas = document.querySelectorAll("canvas").length > 0;
 
       // Check for DOM grid
       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 children = container.children;
         if (
           (children.length >= 180 && children.length <= 220) ||
           (children.length >= 18 && children.length <= 22 &&
             children[0]?.children.length >= 8 && children[0]?.children.length <= 12)
         ) {
           hasDomGrid = true;
           break;
         }
       }
       // Also check tables
       if (!hasDomGrid) {
         const tables = document.querySelectorAll("table");
         for (const table of tables) {
           const rows = table.querySelectorAll("tr");
           if (rows.length >= 18) {
             const cols = rows[0]?.querySelectorAll("td").length ?? 0;
             if (cols >= 8 && cols <= 12) {
               hasDomGrid = true;
               break;
             }
           }
         }
       }
 
       // Visible text (first 500 chars, split into lines)
       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);
 
       // Count clickable elements
       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,
       };
     });
 
     return data;
   } catch {
     return {
       has_overlay: false,
       has_canvas: false,
       has_dom_grid: false,
       visible_text: [],
       clickable_elements: 0,
     };
   }
 }