Validation report

Build: three-voxel-reflections@1.0.0-rc.1

Date: 2026-09-17

Installed dependencies: Three.js / @types/three 0.186.0, TypeScript 5.9.3, Playwright 1.56.1

Native hardware run: Apple M4, macOS 26.4, Google Chrome 152.0.7977.84

Results

The package was installed from npm dependencies using a real lockfile. Both the native WebGPU backend and the WebGL2 comparison executed on the Apple M4. Native mode rejects Three.js's WebGL fallback. Browser reports record the GPU device, driver, browser version, feature status, captures, numerical comparisons and errors.

CPU/GPU oracle

A 32×20 float target is read back for three roughness values (0.02, 0.18, 0.45) and two ray directions, including an oblique ray. This gives 3,840 rays and 15,360 RGBA channel comparisons per backend. Readback Y orientation is measured independently with a UV ramp.

The native run's maximum absolute channel error was 0.002003 or less, and its largest per-case mean absolute error was 0.000133 or less, with zero non-finite channels. Required bounds are max < 0.03 and mean < 0.004. Six additional fixed mip-level samples agree with the CPU hierarchy within 0.003. Exact values are in each backend's results.json; small differences are expected from half-float storage and backend arithmetic.

The oracle independently implements traversal/sampling over the same baked voxel field. It validates that representation, not agreement with an exact triangle path tracer.

Off-screen and image proof

Every corner of every colored source's world bounding box is behind the primary camera's forward half-space. Sources remain visible in the scene graph; the cache collector is camera-independent.

Native captures establish these changes, rather than relying on a plausible still image:

• Reflection toggle: 91,012 pixels changed by more than 15/255 in at least one RGB channel.
• Center-source occlusion: average green in the fixed center ROI changed from 215/255 to 0/255.
• Moving the hidden source: 8,393 pixels changed.
• Moving the camera: 19,414 pixels changed.
• Restoring the scene/camera: 0/255 maximum difference from the original.
• Gallery toggle: 63,032 pixels changed across floor and curved receivers.

These are fixture checks, not perceptual quality scores or an SSR performance benchmark.

Integration and lifecycle checks

The portable volume tests change a readable source texture, move a directional light while preserving baked geometry, empty and rebuild GPU textures, restore bindings for multiple receivers on repeated disposal, and change a receiver normal map to verify reflected directions change.

The native VXGI tests run the actual npm r186 GPU voxelizer in isotropic and directional modes. They verify textured emission on both Z ray signs, rough-cone sampling, black occluders, moved-source occupancy clearing, and restoration. They caught a real bug where shared lazy shader expressions in the directional sampling branch produced black sharp reflections. Coordinates and direction are now materialized before the branch, and both regression cases pass.

The device test deliberately destroys a separate WebGPU device, awaits device.lost, disposes the renderer and creates a new renderer/resources. The replacement renders the expected red pixel. Three.js intentionally suppresses its unexpected-loss callback for reason destroyed; the test verifies that behavior. This checks explicit destruction and application-driven recreation, not an unprovoked driver reset or automatic recovery of an existing renderer.

Reproduce

npm ci
npx playwright install chromium
npm run validate

To use the same installed browser on macOS:

CHROME_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" npm run validate

Individual commands:

npm run check
npm run test:browser:webgl
npm run test:browser
npm run test:package
npm run build:site
npm run test:site

VXR_SOFTWARE=1 npm run test:browser:webgl requests SwiftShader for CPU-only hosts. GitHub Actions runs the software WebGL comparison and site checks explicitly as WebGL, plus semantic/unit/clean-package checks on Node 22 and 24. It does not label software CI as native WebGPU validation. Native testing remains an explicit release gate.

Remaining stable-v1 gates

This remains 1.0.0-rc.1. Native validation covers one GPU vendor and browser implementation. A second independent GPU/browser run, target-hardware performance characterization, and unexpected device/driver-loss behavior remain outstanding. The VXGI fixture is not a general validation of all upstream diffuse bounce modes, lighting combinations or axes. See releasing.

Finite voxel resolution, bounded scene coverage, coarse sharp silhouettes and broad-cone leakage remain algorithmic limits. No cross-vendor performance, exact-mirror accuracy or complete specular light transport claim is made.

Evidence map

• Native report and WebGL report: device metadata, measurements and all runtime checks.
• validation/webgpu/*.png and validation/webgl/*.png: 12 rendered fixtures per backend.
• validation/lab-desktop.png, lab-mobile.png, docs-mobile.png and site-results.json: actual rendered layouts and site checks.
• validation/package-contents.json: the real packed archive inventory.
• validation/source-manifest.json: source hashes for the final local validation run.
• validation/shaders/*.wgsl: historical representative shader generation from the input archive; these are not the current native compilation evidence. The current native evidence is execution and readback above.

This report supersedes the input archive's software-only report. No historical success is substituted for a fresh native run.