Served with isolation headers; start-screen capability notices; tests on the real GPU (t88 phase 1)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/TESTING.md

@@ -71,8 +71,30 @@ diff -r /tmp/before /tmp/after
   to pixels cleanly, and that the thermal lens works.
 - Run them one at a time. Two headless browsers at once can starve each other, and
   `t_smooth.py`'s half-resolution check then fails. `run_all.py` runs them one after the other.
-- Rebuild first (`python3 build.py`). They load `dist/index.html`. `run_all.py --browser`
-  rebuilds for you.
+- Rebuild first (`python3 build.py`); `run_all.py --browser` rebuilds for you. All browser tools
+  use `tools/browser.py` and `tools/server.py`: a free-port background HTTP server serves the
+  built page with COOP/COEP headers and shuts down after the browser. No `file://` loads.
+- Choose Chromium graphics with `--gpu real|soft` or `DEEPGRAIN_GPU=real|soft` (the command line
+  wins). This works for the suite runner, individual browser tests, screenshots and profiler.
+  Real mode uses ANGLE Vulkan on the host GPU; soft uses SwiftShader and sets
+  `window.__allowSoftwareGL` before load. The explicit software-fallback test still uses soft
+  mode with that override off. Firefox uses its own default graphics backend.
+  The default is **real**, including the profiler and `caps.py`. No colour tolerances were
+  changed. The play test holds the slow-save fixture open during its screenshot, waits for
+  tool/selection UI updates, disables camera lead after testing it, and gives the gamepad drill
+  a known reachable target; these checks do not depend on GPU speed or earlier digging.
+- `python3 tools/caps.py` prints isolation, actual WebGPU adapter info and the GL renderer for
+  Chromium and installed Firefox. Real mode requires a hardware Chromium adapter.
+- `test/t_caps.py` checks missing, null and rejected WebGPU adapters, both title notices, warning
+  mode and the future `REQUIRE_GPU_AND_THREADS` startup gate. Its forced notice screenshot is
+  `shots/t88-p1-notice.png`.
+- Install Firefox with `.venv/bin/python -m playwright install firefox`.
+  `python3 test/firefox_smoke.py` checks isolation and the WebGPU notice, starts a pixel world,
+  runs three seconds and checks page errors. `run_all.py --browser` includes it and prints a
+  skip note if Firefox is absent; an installed browser that fails to launch is a failure.
+- Linux WebGPU currently needs Firefox Nightly; the notice points to `about:config` →
+  `dom.webgpu.enabled`. Sources: [Mozilla's experimental features](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Experimental_features#webgpu_api)
+  and [GPUWeb implementation status](https://github.com/gpuweb/gpuweb/wiki/Implementation-Status#firefox).
 
 ## Screenshots: tools/shot.py
 
@@ -106,10 +128,9 @@ python3 tools/shot.py shots/silo.png --setup tools/scenes/clear-sky.js \
 
 ## Pitfalls
 
-- **WebGL in headless Chromium.** The browser tests use SwiftShader for portable graphics checks:
-  launch with `--use-gl=angle --use-angle=swiftshader --enable-unsafe-swiftshader`. Also set
-  `window.__allowSoftwareGL = true` before the page loads (`add_init_script`); otherwise the game
-  sees software rendering and switches to the pixel look. `tools/shot.py` does both.
+- **GPU access in headless Chromium.** Real mode needs access to GPU devices and driver caches;
+  a filesystem sandbox can silently force software rendering. Use `tools/caps.py` to check.
+  Soft mode is available for machines without a GPU. Both modes load isolated HTTP pages.
 - **Top-level `const` and `let` are not `window` properties.** In the page, `window.SM` is
   `undefined` even though `SM` exists. Write `typeof SM !== 'undefined'`, or use the bare name.
   Functions declared with `function` are on `window`.
@@ -176,12 +197,12 @@ python3 tools/shot.py shots/silo.png --setup tools/scenes/clear-sky.js \
   tiny timings and tails can be noisy, and a zero baseline has no meaningful percent change.
 
   Performance runs launch Chromium with
-  `--use-angle=vulkan --enable-features=Vulkan --enable-gpu --ignore-gpu-blocklist --enable-gpu-rasterization`.
+  `--use-angle=vulkan --enable-features=Vulkan,VulkanFromANGLE --enable-gpu --ignore-gpu-blocklist --enable-gpu-rasterization --enable-unsafe-webgpu`.
   They record the unmasked GPU/renderer, cores, browser version, viewport/world size,
-  `crossOriginIsolated`, `navigator.gpu`, source hash and elapsed time. They refuse software
-  renderers or missing isolation. Chromium needs access to the host GPU devices; a filesystem
+  `crossOriginIsolated`, `navigator.gpu`, source hash and elapsed time. Real mode refuses software
+  renderers; both modes require isolation. Chromium needs access to the host GPU devices; a filesystem
   sandbox that hides `/dev/dri`/NVIDIA devices must be lifted for this measurement. The browser
-  tests' SwiftShader numbers are not a performance baseline.
+  tests' SwiftShader numbers (and explicit `--gpu soft` profiler runs) are not a hardware performance baseline.
 
   The existing in-game Performance stats toggle shows smoothed CPU world/light/overlay times
   and movement/heat/rest per simulation tick. Detailed renderer clocks are off by default