feat: visual regression guard for the Pixi client

[N1k4G]

Closes #127. Required before WP-08 starts moving real scenes.

compare-rendering.mjs gates the legacy canvas client only, so nothing watched the Pixi one. The worked example is the silt regression in #119 — silt assigned to terrain, below structure, putting 31 of its 48 particles behind the hull's opaque fill. It passed lint, typecheck, unit, parity and e2e, and was found by reading the diff.

Frames and statistics, verified rather than assumed

You said statistics alone can miss displaced or missing objects. That turned out to be exactly measurable: reintroducing the silt regression fails all three scenes on frame delta (max channel delta 35 against a budget of 24) while no statistic breaches at all.

Silt behind the hull and silt drawn correctly produce nearly identical frame-wide numbers. Statistics would have shipped it.

Why committed PNGs work here

The usual reason pixel baselines are unusable is GPU variance. Playwright's headless Chromium rasterises through SwiftShader — software, not the GPU:

ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero)), SwiftShader driver)

Measured before building anything: 0 differing bytes, same browser and across fresh browser processes.

Whether that holds across operating systems is the open question, and this PR is the experiment — CI runs on Linux against frames recorded on Windows. If it does not hold, the guard says so on this PR rather than passing quietly, and the honest response is a platform-aware baseline rather than a loosened threshold.

Determinism needed more than seeding Math.random

GameController.#tick takes the requestAnimationFrame timestamp and advances both the diver's position and elapsedRealS — which drives the bubbles — by however long the frame really took. Waiting a fixed number of milliseconds does not reproduce a scene.

The first version of this guard failed against its own freshly recorded references with a max channel delta of 128. rAF is now replaced by a queue the harness steps explicitly, with a virtual clock advancing exactly one 60 Hz frame per step, and scenes are driven in frames rather than milliseconds. A guard that is flaky by construction is worse than none.

Two traps worth knowing about

Statistics come from the decoded screenshot, not a canvas readback. Drawing a WebGL canvas into a 2D one returns transparent black without preserveDrawingBuffer. The first version recorded meanLuma 0 for every scene — and zero compares equal to zero, so that half of the guard would have passed whatever the renderer did. There is now an explicit check that refuses to record a uniformly black frame.

The capture pins locale to en-US. The boundary copy is localised and the button is matched by name, so without it the run fails on a German desktop and passes in CI.

Using it

npm run pixi:visual-check     verify against the committed references
npm run pixi:visual-update    re-record them, deliberately

An intended change lands in the diff as new frames for review rather than as a raised threshold. A failing scene writes <scene>.actual.png beside its reference for eyeballing; those are gitignored.

Scope

Three scenes, each exercising a layer the others do not: as-mounted, after a descent (culling and marker pooling resynced), and torch on. The Pixi client is currently the wreck exterior shell only — SITE_ID is hardcoded to wreck — so that is all there is to cover today. The set grows with WP-08.

A correction

I previously advised doing this alongside #124 because they "share the reference-frame artefact". That was wrong, and I have corrected it on #124: this is the Pixi client, #124 is the legacy canvas client, and they share no scenes or files. Batching them would have meant one PR touching two renderers for unrelated reasons.

Verification

typecheck, lint, sites:check, build, 133 unit, 28 parity, 36 e2e, and the guard passing against its own references at 0% pixels changed.

[N1k4G]

[P2] Capture the torch while it is actually enabled

GameController starts with torchOn=true, and keyboard.press('t') synchronously toggles it false. The committed wreck-exterior-start frame visibly contains the beam, while the frame named wreck-torch-on has no beam and its torch control is unpressed. This dedicated scene therefore exercises torch-off, contrary to its name/comment, and does not provide the claimed unique foreground-layer coverage. Please either capture before toggling (ideally assert aria-pressed=true before the screenshot) or rename/document it as the off-state and make the intended torch-on coverage explicit.

[N1k4G]

[P2] Make the visual commands build the client they are checking

Both advertised commands consume dist/, but neither npm script builds it; the checker only verifies that dist/index.html exists. Because dist is gitignored and persists locally, npm run pixi:visual-check can report a perfect 0% delta after a Pixi source change while testing an older build, and pixi:visual-update can record references from stale code. CI happens to run build first, but the documented standalone commands are not trustworthy. Please add build prehooks for both check and update (as test:e2e already does) or have the harness build/serve current sources itself.

[N1k4G]

[P2] Upload the actual frames when this CI step fails

On a breach the checker writes tests/fixtures/reference-frames/pixi/linux/*.actual.png and tells the reviewer to inspect those files, but neither workflow uploads that path. The runner then exits and the only copy is lost; the existing always-upload steps cover screenshots/ and playwright-report/ only. This is especially blocking for a platform-keyed guard because a Windows maintainer cannot reproduce the Linux pixels locally. Please add an if: failure()/always() artifact step for the actual PNGs (in PR and preferably deploy workflows) so the promised diagnostic is retrievable.

[N1k4G]

All three confirmed and fixed — 635fac4

[1] The torch scene captured the torch off

Verified against aria-pressed on the [data-torch] control:

before press:  ◉ pressed=true
after  press:  ◉ pressed=false

So the scene recorded the opposite of its name, and the coverage it claimed to add was already provided by the two scenes above it — which were the ones actually showing the beam, unlabelled.

Renamed to wreck-torch-off, which is the state that genuinely earns a scene of its own, and every scene now declares the torch state it expects and asserts it before capturing.

That assertion is the real fix. A frame is a frame: without it, a mislabelled scene records cleanly, compares cleanly, and goes on being wrong indefinitely — which is exactly what happened. Claiming the wrong state now fails:

Error: wreck-torch-off: expected the torch on but it is off
       — the scene is not exercising what its name says.

[2] Standalone commands could test a stale build

Correct, and worse than it looks: dist is gitignored and persists, so pixi:visual-update could have recorded references from stale code — baking a wrong baseline in rather than just reporting a wrong result.

Both commands now have build prehooks, matching the existing pretest:e2e precedent:

"prepixi:visual-check": "npm run build",
"prepixi:visual-update": "npm run build",

[3] CI discarded the failure PNGs

Also correct, and your point about platform-keying is the sharp end of it: I cannot reproduce Linux pixels on this machine, so an artifact that dies with the runner leaves a CI-only failure with numbers and no image. Both workflows now upload them on failure, with if-no-files-found: ignore so a passing run does not warn.

Verification

typecheck, lint, sites:check, 133 unit, 28 parity, 36 e2e, and the guard at 0% changed pixels on all three scenes.

Also worth noting: package.json briefly showed all 110 lines changed in my working tree from a line-ending rewrite. Restored from main and re-applied by hand — the diff is now 5 added lines.

[N1k4G]

Rereviewed 635fac4: no remaining findings. The standalone visual command now runs its build prehook, all three scenes assert their declared torch state, the renamed torch-off references compare at 0% changed pixels, and both workflows preserve *.actual.png diagnostics on failure. Current CI is green.