[Epic] Web deployment parity & divergence-testing sprint #387

New issue

Open

opened 2026-07-16 16:47:18 +00:00 by john · 0 comments

john commented

2026-07-16 16:47:18 +00:00

Owner

Keystone insight

#347 + #239 + #381 compose into one thing: an automated cross-backend divergence harness. Render the snippet corpus on the web backend (via a headless browser), capture the canvas, and diff against the deterministic desktop-headless PNG oracle. That single harness turns "manually eyeball parity per game" into a CI signal and serves parity, divergence-testing, and SDL-hardening at once.

Bucket map

Web parity (fidelity):

#347 — renderer parity investigation (GLSL ES dialect, geometry-shader absence, RenderTexture round-trip, integer-scaling/half-pixel rounding, text AA) — the anchor; spins out granular defect issues
Parity boundaries to document, not fix: #62 multi-window and #336 free-threading are desktop-only by nature; #337 rules numpy-on-web out of scope

WASM divergence testing:

#239 — Playwright headless-Chromium runner (execution substrate)
#381 — deterministic snippet screenshots (visual-regression oracle, desktop-only today)
NEW: cross-backend screenshot diff harness (the keystone)

SDL validation & hardening:

NEW: SDL2Renderer hardening pass (Fail-Early on shader/program compile, GL context loss, canvas resize)
NEW: input parity test (SDL-event → SFML-enum table)

DX for web deployment:

#386 — make deploy-playground ✅ done
#346 — WASM profiling workflow docs

Recommended sequence

#346 (profiling docs) + input-parity test — fast, low-risk warmups
#239 — stand up the Playwright rig (prereq for the keystone)
Cross-backend diff harness (keystone) — the payload
#347 defects + SDL hardening — fix whatever the harness surfaces

Child issues are linked as dependencies below.

Tracking epic for the web-deployment sprint. The desktop backend is SFML; the web backend is SDL2 + OpenGL ES 2. Game code is written against the SFML API and SDL2 types mirror it, but rendering *fidelity* parity is unestablished and nothing automatically catches desktop↔web divergence. This epic coordinates the work to change that. ## Keystone insight **#347 + #239 + #381 compose into one thing: an automated cross-backend divergence harness.** Render the snippet corpus on the web backend (via a headless browser), capture the canvas, and diff against the deterministic desktop-headless PNG oracle. That single harness turns "manually eyeball parity per game" into a CI signal and serves parity, divergence-testing, and SDL-hardening at once. ## Bucket map **Web parity (fidelity):** - #347 — renderer parity investigation (GLSL ES dialect, geometry-shader absence, RenderTexture round-trip, integer-scaling/half-pixel rounding, text AA) — the anchor; spins out granular defect issues - Parity *boundaries to document, not fix:* #62 multi-window and #336 free-threading are desktop-only by nature; #337 rules numpy-on-web out of scope **WASM divergence testing:** - #239 — Playwright headless-Chromium runner (execution substrate) - #381 — deterministic snippet screenshots (visual-regression oracle, desktop-only today) - NEW: cross-backend screenshot diff harness (the keystone) **SDL validation & hardening:** - NEW: SDL2Renderer hardening pass (Fail-Early on shader/program compile, GL context loss, canvas resize) - NEW: input parity test (SDL-event → SFML-enum table) **DX for web deployment:** - #386 — `make deploy-playground` ✅ done - #346 — WASM profiling workflow docs ## Recommended sequence 1. #346 (profiling docs) + input-parity test — fast, low-risk warmups 2. #239 — stand up the Playwright rig (prereq for the keystone) 3. Cross-backend diff harness (keystone) — the payload 4. #347 defects + SDL hardening — fix whatever the harness surfaces Child issues are linked as dependencies below.