Profiler: real-GPU breakdown by zoom, look and scene, with a baseline (t88 phase 0)

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

docs/TESTING.md

@@ -106,7 +106,7 @@ python3 tools/shot.py shots/silo.png --setup tools/scenes/clear-sky.js \
 
 ## Pitfalls
 
-- **WebGL in headless Chromium.** There is no GPU, so the smooth look needs SwiftShader:
+- **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.
@@ -128,7 +128,66 @@ python3 tools/shot.py shots/silo.png --setup tools/scenes/clear-sky.js \
 
 ## Measuring
 
-- `tools/perf.py`: renderer and tick times in the browser.
+- `tools/perf.py`: the phase 0 CPU/frame profiler, served over HTTP with COOP/COEP isolation.
+  Rebuilds automatically. Run on an otherwise idle machine, without another browser test:
+
+  ```sh
+  python3 tools/perf.py --json tools/perf-baseline.json
+  python3 tools/perf.py --json /tmp/perf-now.json --compare tools/perf-baseline.json
+  python3 tools/perf.py --viewport 1920x1080 --world 2048x1024 --zooms 12,6,4,3,2 \
+      --looks pixel,smooth --scenes settled,factory,heat --seconds 10 --json /tmp/perf.json
+  python3 tools/test_perf.py
+  ```
+
+  The default matrix is three scenes × two looks × five zooms × lighting full/off. The world
+  seed is 424242; fog is off so all visible grains are shaded. Settings otherwise use game
+  defaults (including glow and the minimap), with autosave, camera lead and shake disabled.
+  `settled` runs 600 ticks; `factory` reuses the furnace/transport layout from
+  `experiments/factory_cost.js`, adding screws, a sand filter and full silos for sustained sand
+  and ore flow; `heat` places water over magma beside a rock floor. The latter two settle for
+  another 60 ticks. Each rebuild resets the power-rebuild scheduler, weather random stream and all statistics to
+  fresh-page values; fixture hashes are checked by `test/t_perf.js`. No save/load snapshot is used: it would quantize heat and land flyers.
+
+  **World** is the whole `drawWorld` CPU call. **Light** is the lighting work inside that call;
+  **Prep** sets up the view/masks/joins; **Colour** fills CPU grain buffers (including ghosts and
+  flyers); **Upload** submits the pixel buffer or smooth textures; **Blit** submits drawing,
+  including pixel light/glow composition or the smooth shader and Canvas2D copy. These are CPU
+  wall times, including driver stalls; they are not GPU timestamp measurements. In pixel look,
+  the glow upload is part of Blit. The separate `computeLight_ms` times an unconditional light
+  call even when the row has lighting off. World includes Light: do not add them together.
+  Overlay totals and each individual draw call are in JSON, with ms/frame and invocation counts; conditional
+  overlays absent from the fixture have zero calls, not a measured zero execution cost.
+
+  Five calls warm each render configuration before 30 measured calls. Simulation warms five
+  full 120-tick periods on a disposable scene, then rebuilds the same seeded fixture and
+  measures 240 consecutive ticks. Every direct `simTick` callee is discovered from its source;
+  JSON records per-call and amortized per-tick costs and invocation counts, including periodic
+  functions. Inactive paths (e.g. load wake, saplings, flow tracking) have zero calls and null
+  per-call cost. Unattributed time includes tick bookkeeping and clock/wrapper overhead.
+  Awake/hot chunk counts are recorded at the start/end of simulation and real runs.
+
+  Real-loop tests independently rebuild each scene for zooms 2 and 6 in both requested looks,
+  regardless of `--zooms`. `--seconds` applies to each of these twelve default runs. Raw samples
+  retain frame interval (rAF timestamps, including waiting/scheduling), CPU frame work, total
+  simulation work per frame and number of ticks. p50/p95/p99 use interpolated sorted samples;
+  five warm-up frames are excluded. Zero-tick frames correctly have zero simulation time.
+  JSON also records the smooth renderer's adaptive resolution scale: compare it as well as time.
+  Comparisons require identical options, print all timing changes, and mark >10% regressions;
+  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`.
+  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
+  sandbox that hides `/dev/dri`/NVIDIA devices must be lifted for this measurement. The browser
+  tests' SwiftShader numbers are not a 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
+  (`PERF_MARKS = false`); the raw frame hook (`PERF_FRAME`) is also off outside the profiler.
+  `tools/server.py` shares the isolation/no-cache headers with `tools/serve.py`, and supplies a
+  free-port background server with cleanup for measurement tools.
 - `tools/experiments/factory_cost.js`: what running factories cost the simulation.
 - `tools/experiments/flow.js`: belt and screw conveyor throughput in grains a second.
 - `tools/experiments/worldgen.js`: material counts and timings of world generation.