WebGL save/restore: transform not preserved across save/restore (3 tests fail when WebGL2 runs)

[obiot]

Problem

`tests/webgl_save_restore.spec.js` has three tests that fail when WebGL2 is actually available in the test environment:

1. "should preserve transform across save/restore"
2. "should handle nested save/restore correctly"
3. "should handle deep nesting (20 levels)"

All three fail at the same assertion shape: after a `save()` → mutate → `restore()` sequence, `renderer.currentTransform.val[0]` reads as `0` instead of the expected `1` (the identity-matrix top-left).

These were silently masked because the tests guard with:

```js
if (!isWebGL) {
return;
}
```

The `failIfMajorPerformanceCaveat: true` option in the test setup means chromium headless without GPU flags falls back to Canvas, the guard returns early, and the failure never reports.

Why this is being filed now

While landing #1480 (mesh-depth single-clear refactor), I temporarily added chromium swiftshader launch flags to `vitest.config.ts` so the new WebGL2 pixel-level tests would run in CI. That surfaced these three failures. The flags were reverted to keep #1480's scope tight; this issue tracks the underlying bug.

Repro

Add to `vitest.config.ts`:

```ts
provider: playwright({
launchOptions: {
args: [
"--use-gl=angle",
"--use-angle=swiftshader",
"--enable-unsafe-swiftshader",
"--ignore-gpu-blocklist",
],
},
}),
```

Then `pnpm vitest run tests/webgl_save_restore.spec.js` produces:

```
3 failed | 10 passed (13)

• should preserve transform across save/restore
  AssertionError: expected +0 to be close to 1
• should handle nested save/restore correctly
  AssertionError: expected +0 to be close to 1
• should handle deep nesting (20 levels)
  AssertionError: expected +0 to be close to 1
  ```

Reproduces on a clean checkout of master (no #1480 changes) — pre-existing bug.

Suspected area

The test predates the RenderState refactor (commit af34dd3 "Refactor renderer state into RenderState with zero-allocation save/restore"). One of:

1. The pre-allocated index-based stack indexes the wrong slot for transform state
2. `save()` captures by reference instead of cloning — mutations to currentTransform between save/restore leak into the saved value
3. `restore()` writes the post-mutation matrix back instead of the saved one

Color save/restore tests pass; only transform fails. So the bug is specific to how the transform matrix is captured / restored, not the broader save/restore stack mechanics.

Acceptance

• All 13 tests in `tests/webgl_save_restore.spec.js` pass under WebGL2 (verified by re-enabling swiftshader flags + running locally)
• `vitest.config.ts` can ship the swiftshader flags so WebGL2-dependent tests run in CI instead of skipping (this unlocks the mesh-depth pixel tests from feat(renderer): single depth clear per target for mesh draws (#1468) #1480 to actually run in CI)
• No regression in Canvas-renderer behaviour (the early-out guard becomes irrelevant once the bug is fixed)

Related

• feat(renderer): single depth clear per target for mesh draws (#1468) #1480 (mesh-depth refactor — surfaced this when its swiftshader flags briefly ran)

[obiot]

Post-mortem: false alarm — the engine is fine, the tests were broken

After running with WebGL actually available, the engine's save/restore is fully working. The three failing assertions hardcoded the wrong indices for the matrix layout.

The bug in the tests

`Matrix3d.val` is a 16-element `Float32Array` — a 4×4 column-major matrix. The 4×4 identity has `val[0] = val[5] = val[10] = val[15] = 1`, everything else zero.

The three failing tests asserted:

```js
expect(val[0]).toBeCloseTo(1, 5); // ✓ correct for 4×4
expect(val[1]).toBeCloseTo(0, 5); // ✓ correct
expect(val[3]).toBeCloseTo(0, 5); // ✓ correct
expect(val[4]).toBeCloseTo(1, 5); // ✗ WRONG — val[4] is 0 in a 4×4 identity
expect(val[6]).toBeCloseTo(0, 5); // ✓ correct (incidentally)
expect(val[7]).toBeCloseTo(0, 5); // ✓ correct
```

The author wrote the assertions assuming a 3×3 column-major layout where `val[4]` is the [1,1] diagonal entry — probably copy-pasted from older 2D affine math (`Matrix2d` is 3×3 / 9 elements). For a 4×4 matrix the diagonal is at `val[0], val[5], val[10], val[15]`, not `val[0], val[4], val[8]`.

The save/restore code in `RenderState` is correct. The other 10 tests in the spec pass under real WebGL, including the "preserve translate" test (which uses an element-wise `before === after` comparison and doesn't hardcode indices).

How this slipped past CI for months

The spec used the silent-skip anti-pattern:

```js
it("name", () => {
if (!isWebGL) {
return; // ← reports as PASSED, not skipped
}
// assertions...
});
```

Combined with `failIfMajorPerformanceCaveat: true` in the test setup, headless chromium without GPU flags fails to create a WebGL context, falls back to `CanvasRenderer`, `isWebGL = false`, every test returns immediately. The reporter shows "13 passed" with no skipped count, no warning. The assertions never ran a single time in CI since the spec was committed in `af34dd341` (Mar 2026). Three years of green ticks for tests that weren't actually running.

If the author had used `ctx.skip("WebGL not available")` instead of bare `return`, the reporter would have shown "13 skipped" instead of "13 passed" — which would have prompted "why are our WebGL tests skipped?" months ago.

The fix landing now

PR (incoming):

1. Replace the three broken index-based assertions with `expect(renderer.currentTransform.isIdentity()).toBe(true)` — layout-agnostic, says what we actually mean.
2. Switch all 13 `if (!isWebGL) return` to `requireWebGL(ctx)` helper that calls `ctx.skip(...)` — skips now surface in the reporter so a future regression doesn't hide behind silent passes.
3. `failIfMajorPerformanceCaveat` flipped to `false` in the spec's `beforeAll` so local devs / GPU-backed runners can actually run these tests (software-WebGL works fine for save/restore validation).

Follow-up (separate from this issue)

`tests/webgl_pipeline_adversarial.spec.js` has the same silent-skip anti-pattern at 22 sites. When SwiftShader is enabled in CI to actually exercise these tests, the fuzz test surfaces some flakiness under parallel runs. That's an independent cleanup — needs its own pass to (a) convert the skip pattern and (b) stabilize the surfaced fuzz behaviour under software WebGL. Tracked separately to keep this issue's scope tight.

Closing as "false alarm — tests fixed" once the PR merges.