fix(3d): blank viewer after raytracing round-trip — owner-context FFP routing + VAO isolation (gl1)

Switching OpenGL → raytracing → OpenGL could leave the viewer showing only the
background gradient, with mid-session "[gl1] WebGL context changed" thrash and
INVALID_OPERATION storms on BOTH WebGL contexts. Traced mechanism: the shim's
FFP draw routing keyed on one process-global client-array flag; an interrupted
fixed-function window (MODEL_3D::BeginDrawMulti loops, or the switch-back
reload re-recording display lists with the GL context lock released across
JSPI suspensions) left it set, after which the raytracer blit's and the 2D
GAL's glDrawArrays were routed through the FFP pipeline — and one misrouted
draw permanently repointed the VICTIM's own VAO attributes at shim buffers
(the blit's attribute 0 collides with ATTR_POSITION), so both stayed
broken/blank even after the flag cleared.

Shim fixes (wasm/gl1):
- Owner-context routing gate: __wrap_glDrawArrays/Elements route into the FFP
  pipeline only under the shim's owner context (adopted at the first FFP
  client-state mutation or programSync in a context); foreign-context draws
  always pass through — the 2D GAL can never be misrouted and the context
  guard can never thrash.
- VAO isolation (ScopedDefaultVAO): draw executors do their attribute setup on
  VAO 0 and restore the caller's binding — a misrouted draw can no longer
  corrupt the caller.
- contextSync() resets the whole client-array mirror on a context change
  (enables/pointers/VBO names all described the dead context).

kicad pointer bump (d6e3dc1a87a): blit preamble disables the four client
arrays (same-context firewall) + DoRePaint hidden-parent early return now
clears m_is_currently_painting like its six siblings (a standalone
sufficient cause of a permanently blank viewer).

TDD (each observed red before its fix, green after; harness = authoritative):
- T1 VAO corruption, T2 foreign-context routing + guard thrash, T3 stale
  client-state surviving context recreation — tests/e2e/3d-webgl.spec.ts over
  new harness choreography (appQuad/ffpMakeStale/createSecondContext/
  quadDrawFresh). Parity stays 47/47 with zero drift.
- tests/kicad/3d-viewer-engine-toggle.spec.ts (new, CI-skipped like the
  deadlock spec): real round-trip happy-path gate — board re-renders, zero
  [gl1] lines, zero INVALID_OPERATION. (The raytraced image itself never
  displays on the wasm build — the pre-existing inert-toggle KNOWN ISSUE in
  3d-viewer-deadlock.spec.ts, out of scope here; the engine switch and the
  poisoning reload path run regardless.)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Istvan Matejcsok 2026-08-25 11:24:26 +02:00
commit daaff1f973
13 changed files with 542 additions and 8 deletions

View file

@ -34,11 +34,28 @@ Link sites (both read `sources.txt` + `wrapped_symbols.txt`):
## Draw routing
A `glDrawArrays`/`glDrawElements` call is FFP traffic iff `GL_VERTEX_ARRAY`
client state is enabled: only GL1 code calls `glEnableClientState`, while the
raytracer blit (`eda_3d_canvas_wasm.cpp`) and the 2D WebGL GAL drive their own
GLSL programs and never touch client state — their draws pass through
untouched.
A `glDrawArrays`/`glDrawElements` call is FFP traffic iff BOTH hold:
- the CURRENT WebGL context is the shim's **owner context** (`contextIsOwner()`,
adopted at the first FFP client-state mutation or `programSync()` in a
context — a draw under any other context is a modern-GL consumer by
definition and always passes through, even mid-display-list-recording);
- `GL_VERTEX_ARRAY` client state is enabled (only GL1 code calls
`glEnableClientState`; the raytracer blit and the 2D WebGL GAL drive their
own GLSL programs).
The owner gate exists because the client-state flag is process-global and an
interrupted FFP window (e.g. `MODEL_3D::BeginDrawMulti` loops crossing a JSPI
suspension) can leave it set — without the gate, the 2D GAL's draws got routed
through the FFP pipeline (the engine-toggle blank-viewer bug). Two further
hardenings from the same bug:
- **VAO isolation** (`ScopedDefaultVAO`, gl1_draw.cpp): draw executors bind
VAO 0 for their attribute setup and restore the caller's binding — a routed
draw arriving with the caller's VAO bound (the blit's attribute 0 collides
with `ATTR_POSITION`) must never scribble it.
- `contextSync()` resets the client-array mirror entirely on a context change:
enables, pointers and captured VBO names all described the dead context.
## Invariants that are easy to break (learned from the native goldens)