test(determinism): deterministic waits + stableShot screenshots; drop blind sleeps/ifs/retries

Make the Playwright e2e + kicad suites deterministic so screenshot flake stops
tracing to timing races.

- Blind page.waitForTimeout -> condition waits (expect.poll, web-first
  assertions, waitUntil) + readiness helpers (waitForWxApp, waitForCanvasApp).
  Remaining sleeps are documented interaction dwells (annotated).
- Defensive "if element exists" branches -> loud asserts; label-fallback chains
  -> normalized clickMenuItemByText. First-run wizard for/if loops removed by
  seeding calculator/gerbview/pcbnew HTMLs.
- Screenshots: new stableShot(page, name) settles the render in-page (canvas
  hash over rAF) then writes a raw PNG to test-results/ for the existing offline
  gate (tools/screenshots vs baseline-screenshots). Replaces toHaveScreenshot,
  which did inline compare + its own baselines and had decoupled the specs from
  the real gate. scale:'css' pinned.
- retries: 0 in both configs.
- Guard: tests/tools/lint-determinism.ts (npm run lint:determinism) bans blind
  sleeps / toHaveScreenshot / inline retries / swallowed catches in specs;
  documented exceptions carry a marker. Rules in tests/TESTING.md.

Assertions, coverage, and renders unchanged (semantic-equivalence reviewed;
captures pixel-identical modulo inherent timer/timestamp/3d-raytrace variance).
Both suites green at retries:0 (e2e 340, kicad 92); ~35-61% faster.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BVX1pHMvRPYHdp6ZfEawrk

tests/kicad/contextmenu-scrollbar-pcbnew.spec.ts

@@ -1,6 +1,6 @@
 import type { Page } from '@playwright/test';
 import { test, expect } from './fixtures';
-import { clickByLabel, clickMenuItem, findRenderedByType } from '../e2e/utils/element-tracker';
+import { clickMenuItem, findRenderedByType, waitForEditorReady, stableShot } from '../e2e/utils/element-tracker';
 
 /**
  * Secondary in-app proof on pcbnew (the user's explicit ask): the right-side
@@ -12,22 +12,6 @@ import { clickByLabel, clickMenuItem, findRenderedByType } from '../e2e/utils/el
  * Screenshots: test-results/pcbnew-sidebar-scrollbar.png, pcbnew-context-menu.png.
  */
 
-async function waitForEditor(page: Page): Promise<void> {
-  await expect(page.locator('#canvas')).toBeVisible({ timeout: 120000 });
-  await page.waitForFunction(() => !!window.wxElementRegistry, null, { timeout: 120000 });
-  await page.waitForTimeout(2000);
-  // Dismiss the first-run setup wizard (pcbnew shows one).
-  for (let i = 0; i < 12; i++) {
-    const next = await clickByLabel(page, 'Next >');
-    if (!next) {
-      await clickByLabel(page, 'Finish');
-      break;
-    }
-    await page.waitForTimeout(400);
-  }
-  await page.waitForTimeout(2000);
-}
-
 async function getGlBox(page: Page): Promise<{ x: number; y: number; width: number; height: number }> {
   const id = await page.evaluate(() => {
     const visible = Array.from(document.querySelectorAll('[id^="glcanvas-"]'))
@@ -50,14 +34,14 @@ test.describe('pcbnew: DOM-port scrollbar + context menu', () => {
   });
 
   test('the appearance/layers panel shows a draggable scrollbar gutter', async ({ page }) => {
-    await waitForEditor(page);
+    await waitForEditorReady(page);
 
     await expect.poll(async () => (await findRenderedByType(page, 'slidertrack')).length, {
       timeout: 15000,
       message: 'the overflowing layers panel should show a built-in scrollbar gutter',
     }).toBeGreaterThan(0);
 
-    await page.screenshot({ path: 'test-results/pcbnew-sidebar-scrollbar.png', fullPage: true });
+    await stableShot(page, 'pcbnew-sidebar-scrollbar.png', { fullPage: true });
 
     const tracks = await findRenderedByType(page, 'slidertrack');
     const sliders = await findRenderedByType(page, 'slider');
@@ -69,8 +53,7 @@ test.describe('pcbnew: DOM-port scrollbar + context menu', () => {
     await page.mouse.down();
     await page.mouse.move(vTrack.centerX, vTrack.screenY + vTrack.height * 0.7, { steps: 6 });
     await page.mouse.up();
-    await page.waitForTimeout(400);
-    await page.screenshot({ path: 'test-results/pcbnew-sidebar-scrollbar-dragged.png', fullPage: true });
+    await stableShot(page, 'pcbnew-sidebar-scrollbar-dragged.png', { fullPage: true });
   });
 
   // Labels of the items in the currently-open DOM context-menu popup.
@@ -83,7 +66,7 @@ test.describe('pcbnew: DOM-port scrollbar + context menu', () => {
     page,
     testLogger,
   }) => {
-    await waitForEditor(page);
+    await waitForEditorReady(page);
 
     // Right-click the drawing canvas. pcbnew's selection tool builds its menu
     // (common/tool/tool_manager.cpp) and calls frame->PopupMenu() from inside
@@ -93,7 +76,9 @@ test.describe('pcbnew: DOM-port scrollbar + context menu', () => {
     const x = Math.round(box.x + box.width * 0.5);
     const y = Math.round(box.y + box.height * 0.5);
     await page.mouse.click(x, y); // activate the selection tool
-    await page.waitForTimeout(400);
+    // Small settle so the activation click is processed before the right-click — no
+    // JS-observable "selection tool active" signal to poll (documented interaction wait).
+    await page.waitForTimeout(400); // eslint-disable-line -- see comment above
     await page.mouse.click(x, y, { button: 'right' });
 
     // The popup items register in the e2e registry under parentId 'popupmenu'.
@@ -113,7 +98,7 @@ test.describe('pcbnew: DOM-port scrollbar + context menu', () => {
     const items = await findRenderedByType(page, 'menuitem', { parentId: 'popupmenu' });
     expect(items.every((i) => i.enabled)).toBe(true);
 
-    await page.screenshot({ path: 'test-results/pcbnew-context-menu.png', fullPage: true });
+    await stableShot(page, 'pcbnew-context-menu.png', { fullPage: true });
 
     // The menu is interactive: opening the "Zoom" submenu replaces the popup
     // with the submenu's items (so the top-level "Grid" entry disappears).
@@ -124,7 +109,7 @@ test.describe('pcbnew: DOM-port scrollbar + context menu', () => {
     }).toBe(false);
     const subLabels = await popupLabels(page);
     expect(subLabels.length, `submenu was: ${JSON.stringify(subLabels)}`).toBeGreaterThan(0);
-    await page.screenshot({ path: 'test-results/pcbnew-context-submenu.png', fullPage: true });
+    await stableShot(page, 'pcbnew-context-submenu.png', { fullPage: true });
 
     // Escape dismisses the popup without firing a command (registry clears).
     await page.keyboard.press('Escape');