@woosh/meep-engine 3.60.3 → 3.60.5

package/src/shade/renderer/postprocess/nss/NOTES.md

@@ -1,339 +0,0 @@
-# Neural Super Sampling (NSS)
-
-Port of [ARM's Neural Super Sampling](https://github.com/arm/neural-graphics-for-unreal/tree/main)
-reference design onto the engine's FrameGraph. Same role as TAA — temporal
-anti-aliasing + upscale — but the spatial reconstruction kernel is predicted
-per-pixel by a small CNN (Kernel-Prediction Network) instead of a fixed
-Catmull-Rom + variance clip.
-
-## Pipeline overview
-
-For each frame:
-
-1. **Preprocess** (compute, render-res, 8×8 workgroups) — assembles a
-   12-channel input tensor from current colour, depth-dilated velocity,
-   warped history, the network's own feedback tensor from the previous
-   frame, and a luma-derivative high-frequency hint. Also writes a
-   "nearest depth offset" texture used later by postprocess.
-2. **Network** (compute, render-res, 18 conv dispatches + 2 concats) —
-   ARM's U-Net produces:
-   - K0..K3: a 4×4 spatial reconstruction kernel (one row of weights per
-     tensor, 4 channels each).
-   - K4: temporal blend coefficients (theta, alpha).
-   - FB: a 4-channel feedback tensor consumed by next frame's preprocess.
-3. **Extract feedback** (compute, render-res) — copies the FB layer of the
-   network's 3D output texture into a standalone 2D texture so the next
-   frame's preprocess can sample it as a regular `texture_2d<f32>`.
-4. **Postprocess** (compute, output-res) — applies the predicted 4×4 KPN
-   to the jittered colour, blends with the warped history using the
-   predicted theta, tonemap-blend-inverse-tonemap.
-
-## Network architecture
-
-ARM's network is a U-Net with skip connections and 6 parallel output heads.
-Topology was reverse-engineered by parsing the SPIR-V dataflow inside
-`nss_v0_1_1_int8.vgf`:
-
-```
-Encoder (ReLU + bias):
-  conv1: 12 -> 32 (3x3)
-  conv2: 32 -> 32              -> tap to skip_B
-  conv3: 32 -> 32
-  conv4: 32 -> 32              -> tap to skip_A
-  conv5: 32 -> 64
-  conv6: 64 -> 64
-  conv7: 64 -> 32
-
-Decoder (ReLU, no bias):
-  conv8:  32 -> 16
-  concat(conv8_out, skip_A)    -> 48 ch
-  conv9:  48 -> 16
-  conv10: 16 -> 16
-  concat(conv10_out, skip_B)   -> 48 ch
-  conv11: 48 -> 16
-  conv12: 16 -> 16             -> shared by 6 heads
-
-Output heads (identity, no bias):
-  K0..K3, K4, FB: 16 -> 4 (3x3) each, 6 parallel dispatches writing
-                                 distinct z-layers of network_output.
-```
-
-The schema is encoded in `NSS_NETWORK_SCHEMA.js`; `NSSWeights` instances
-are validated against it on install.
-
-## Files
-
-- `NSS.js` — orchestrator. Manages persistent textures, weight buffers, the
-  jitter sequence, and the per-frame dispatch sequence.
-- `NSS_NETWORK_SCHEMA.js` — fixed U-Net topology spec.
-- `NSSWeights.js` — host-side weight bundle (per-layer
-  `{in_channels, out_channels, kernel_size, weights, bias, activation,
-   weight_scale, bias_scale}`); knows how to pack into the binary
-  format the conv shader binds.
-- `NSS_WEIGHTS_ACTUAL.js` — bundled weights (base64 of the packed
-  blob), decoded once on first use. Auto-generated.
-- `generate_NSS_WEIGHTS_ACTUAL.js` — build-time script that converts
-  ARM's `nss_v0_1_1_int8.vgf` (via the SDK's `Model_Parser` C-header
-  dump) into the binary format above.
-- `NSS_CONSTANTS.js` — workgroup size, channel counts, kernel size.
-- `NSS_SETTINGS_STRUCT.js` — per-frame uniforms (jitter, resolution,
-  history validity, frame index).
-- `NSS_LAYER_CONFIG_STRUCT.js` — per-layer conv config (offsets,
-  channel counts, activation, output-z offset, scales, has-bias flag).
-- `shader_nss_preprocess.js` — preprocess compute shader.
-- `shader_nss_conv_layer.js` — generic conv layer (int8-packed weights,
-  `unpack4x8snorm`-based dequant, optional bias).
-- `shader_nss_concat.js` — concat two 3D tensors along the channel-group
-  (z) axis.
-- `shader_nss_extract_feedback.js` — extracts FB layer to 2D texture.
-- `shader_nss_postprocess.js` — postprocess compute shader.
-- `chunk_nss_*.js` — supporting WGSL chunks.
-
-## Texture inventory
-
-| Texture | Channels | Format | Lifetime |
-|---|---|---|---|
-| Preprocess tensor | 12 | rgba16f (3D, depth=3) | transient (FrameGraph) |
-| Nearest-depth offset | 2 | rg8unorm (2D) | transient |
-| Activation A / B (ping-pong) | 64 | rgba16f (3D, depth=16) | persistent |
-| Skip A / B | 32 | rgba16f (3D, depth=8) | persistent |
-| Concat scratch | 48 | rgba16f (3D, depth=12) | persistent |
-| Pre-output | 16 | rgba16f (3D, depth=4) | persistent |
-| Network output | 24 | rgba16f (3D, depth=6) | persistent |
-| Feedback A / B (ping-pong) | 4 | rgba16f (2D) | persistent |
-
-All sized at render-res. At 540p render that's roughly 270 MB of VRAM
-for the network alone — substantial. Lower the render-resolution scale
-or move to a smaller architecture if memory matters.
-
-## Weights
-
-Bundled directly in the source via `NSS_WEIGHTS_ACTUAL.js` — 18 conv
-layers (~131 KB int8 weights + ~1.2 KB f32 biases), base64-encoded in
-the JS module. The `NSS` constructor decodes and uploads them
-automatically; the renderer only needs to flip
-`upscale_type = ShadeUpscalerType.NSS`.
-
-### Source
-
-Extracted from `nss_v0_1_1_int8.vgf` in the ARM Neural Graphics for
-Unreal SDK in two passes:
-
-1. **VGF constants table** via ARM's own `Model_Parser.exe` — gives
-   us the conv weights for every layer and biases for the 7 encoder
-   convs (the parser writes a `.nss_constants.h` C dump).
-2. **SPIR-V graph** via `.nss_work/extract_spirv.cjs` — gives us the
-   decoder + head biases (which live as inline `OpConstantComposite`
-   in the SPIR-V module, not as VGF constants) and the per-channel
-   RESCALE multiplier + shift for every conv layer.
-
-`generate_NSS_WEIGHTS_ACTUAL.js` combines both extracts using
-`BinaryBuffer` from `@woosh/meep-engine` and emits the base64 blob.
-
-To regenerate:
-
-```
-# 1. Run ARM's parser on the .vgf:
-Model_Parser.exe -output=<dir> nss_v0_1_1_int8.vgf
-# Copy `.nss_constants.h` to <repo>/.nss_work/_nss_constants.h
-# (the dot-prefix in the parser's output isn't great on Windows;
-# we use an underscore-prefix locally).
-
-# 2. Copy nss_v0_1_1_int8.vgf to <repo>/.nss_work/nss.vgf and dump
-# the embedded SPIR-V data:
-node .nss_work/extract_spirv.cjs > .nss_work/spirv_extract.json
-
-# 3. From repo root:
-node src/webgpu/renderer/postprocess/nss/generate_NSS_WEIGHTS_ACTUAL.js
-```
-
-### Quantization
-
-ARM's network is INT8 throughout. Two TOSA ops define how int32 conv
-accumulators are turned into int8 activations:
-
-1. **RESCALE** (`inst=65`) — per-output-channel `(acc_int32 * mult) >> shift`.
-   Saturates to int8 [-128, 127].
-2. **TABLE** (`inst=30`) — only on the 6 output heads. A 256-entry
-   int8 lookup applied after RESCALE. ARM uses this to encode the
-   trained activation function: roughly sigmoid for K4 (the temporal
-   blend probability), smoother tanh-shape for K0..K3 + FB (the
-   kernel-weight heads). Body layers don't have a LUT — they use the
-   inline ReLU activation from the RESCALE+CLAMP fused output.
-
-We extract both from the SPIR-V graph in the .vgf:
-
-```
-rescale_factor[c] = 127 * mult[c] / 2^shift[c]   # baked at conv time
-LUT[i] in [-127, 127]                             # 256 entries, 1 per head
-```
-
-Each conv shader pass:
-
-```
-acc = sum(input * weight) + bias                  // bias pre-divided by 127^2
-acc = clamp(acc * rescale, -1, 1)                 // RESCALE + int8 saturation
-if has_lut:                                       // output heads
-    acc = LUT[clamp(round(acc * 127) + 128, 0, 255)] / 127
-else:
-    acc = activation(acc)                         // ReLU for body layers
-```
-
-The LUT is the missing piece that makes the trained network's
-activation function meaningful — ThetaAlpha goes from "noisy linear"
-to "sharp sigmoid step", the KPN columns get their proper tanh shape.
-
-#### Per-head RESCALE output_zp — the LUT calibration shift
-
-TOSA RESCALE has an `output_zp` operand that biases the int8 result
-by a head-specific amount before saturation, lining up the
-saturated value with the trained transition zone of the per-head
-TABLE LUT. Without applying it, the LUT input always lands at the
-flat tail (int8 ≈ 0) and the trained activation collapses to a
-constant.
-
-The values we extract from the SPIR-V (per ARM's quantized model):
-
-| Slot | Head        | output_zp | LUT transition zone (int8 input) |
-|------|-------------|-----------|----------------------------------|
-| 0    | Feedback    |  +76      | [+41, +111]                      |
-| 1    | ThetaAlpha  |  +22      | [+18, +26]                       |
-| 2    | KPNCol3     |  +94      | [+65, +123]                      |
-| 3    | KPNCol2     |  +11      | [-29, +51]                       |
-| 4    | KPNCol1     |   -1      | [-50, +48]                       |
-| 5    | KPNCol0     |  +12      | [-25, +49]                       |
-
-The conv shader applies `output_zp` in `nss_apply_lut`:
-`int8_in = clamp(round(value_fp * 127) + output_zp, -128, 127)`
-which puts the LUT INDEX inside the trained transition zone for
-each head. LUT output dequantisation matches ARM's `Dequantize`
-(`(int8 + 127) / 255`), giving fp ∈ [0, 1].
-
-Body layers also have an output_zp (= -128, the uint8 storage zero
-point that cancels the next conv's input_zp = 128). For body
-layers the conv shader ignores it — body activations are stored in
-fp32 throughout our pipeline so the offset is implicit.
-
-#### Head ordering — ARM's quantized model
-
-The 6 heads come out of the SPIR-V in CONCAT order, which is NOT
-KPN col 0..3 + ThetaAlpha + FB. ARM's UE5.5 plugin
-(`UE5.5/Source/NSS/Private/NSS.cpp:241-246`) hard-codes the
-quantized-model `OutputIndices`:
-
-```cpp
-Result->OutputIndices.Feedback     = 0;
-Result->OutputIndices.ThetaAlpha   = 1;
-Result->OutputIndices.KPNFilterCol3 = 2;
-Result->OutputIndices.KPNFilterCol2 = 3;
-Result->OutputIndices.KPNFilterCol1 = 4;
-Result->OutputIndices.KPNFilterCol0 = 5;
-```
-
-Our postprocess shader reads the columns from `[5, 4, 3, 2]` in
-that order to recover (col 0, col 1, col 2, col 3), and reads
-ThetaAlpha from slot 1.
-
-#### Postprocess two-stage blend
-
-Mirrors ARM's `NSSPostprocess.usf` (UE5.5):
-1. Apply the 4×4 KPN to the jittered colour, normalising by
-   the (positive) weight sum. The centre tap (col=1, row=1) is also
-   captured separately.
-2. Blend the KPN colour with warped history by `theta * on_screen`.
-3. In tonemapped (max-of-channels Karis) space, blend toward the
-   centre tap by `alpha * centre_present` — sharpens output pixels
-   that have a true render-res sample under them.
-4. Inverse tonemap, divide by `EXPOSURE = e^2`, write.
-
-`theta = ThetaAlpha.x` directly (LUT output already in [0, 1]).
-`alpha = 0.35 * ThetaAlpha.y + 0.05` — remap to ARM's
-[0.05, 0.4] band.
-
-## Known divergences from ARM's reference
-
-Audited against `ffx_nss_callbacks_glsl.h`, `ffx_nss_preprocess.h`,
-`ffx_nss_postprocess.h`. Tracking what we still differ on:
-
-- **Persistent luma derivative (preprocess):** ARM
-  (`CalculateLumaDerivative`, ffx_nss_callbacks_glsl.h:627-681) uses
-  a persistent `R8G8` ping-pong texture with soft-clip + x^1.5
-  normalisation + temporal accumulation + disocclusion gating. We
-  use a single-frame `saturate(abs(luma_diff) * 4)`. The trained
-  network expects the persistent variant.
-- **Disocclusion sample location:** ARM unjitters the previous-frame
-  UV via `JitterOffsetTm1Uv()` before sampling prev depth
-  (`ffx_nss_preprocess.h:34`). We pass the raw reprojected UV.
-  Causes false-positive disocclusion on static silhouettes.
-- **Disocclusion bilinear weight threshold:** ours 0.01, ARM's 0.1.
-  We admit weak corner taps that ARM rejects.
-- **Disocclusion gather rebias:** ARM offsets the prev-depth gather
-  by the previous frame's nearest-depth-offset texture
-  (`GatherReconstructedPreviousDepthRQuad`). We don't track or feed
-  back the prev-frame nearest-offset.
-- **Motion zero-clamp + static-frame disocclusion scaling:** ARM
-  zeros tiny motion (`MotionWarpThresh=0.01`) and scales
-  disocclusion by `~0.725` on near-static frames
-  (`MotionDisThresh=0.25`). We do neither.
-- **History warp filter:** ARM uses Catmull-Rom with deringing
-  (`CatmullRomWithDering`, NSSPostprocess.usf:55). We use plain
-  bilinear via `SAMPLER_LINEAR_UPSCALE`. Slight softness on
-  high-frequency history detail.
-- **Per-tensor input scales (forward pass):** ARM's INT8
-  quantisation has per-tensor `input_scale` per CONV op (encoded as
-  TOSA quantisation metadata that we don't decode). The combined
-  `s_in * s_w / s_out` is folded into the per-channel RESCALE
-  multiplier we DO extract — so for our purposes the heads are
-  fully calibrated via output_zp (above), and any residual scale
-  drift in the body layers gets absorbed by the per-channel
-  multipliers. Symptoms would be uniform brightness / saturation
-  bias on whole-image output, not the activation collapse we had
-  before output_zp was wired up.
-- **Exposure factor:** ARM multiplies network colour reads by
-  `Exposure()` and the final write by `1/Exposure()`
-  (`ffx_nss_postprocess.h:48`). We hard-code `EXPOSURE = e^2` to
-  match ARM's `NSSCommon.ush` constant — adequate for SDR output,
-  but doesn't track engine exposure changes.
-- **2x preset KPN footprint:** ARM's 2x path uses a precomputed
-  `kernelLUT` indexed by `(out_pixel + jitter_tile_offset) % 2`,
-  selecting one of 4 sparse 4-tap patterns. We do a generic 4×4
-  walk on the input grid via `nss_solve_input_location`; the
-  trained 2x weights expect the LUT-based pattern.
-- **Feedback texture format:** ARM uses `R8_SINT` (or aliased
-  `R8G8B8A8_SNORM`) with a quantisation scale; we use raw `rgba16f`.
-  Higher precision but a different value range than the network was
-  trained against.
-
-## Engine integration
-
-Wired into `Renderer.js` behind `ShadeUpscalerType`. To switch:
-
-```js
-import { ShadeUpscalerType } from "./ShadeUpscalerType.js";
-
-renderer.upscale_type = ShadeUpscalerType.NSS;  // or .TAA
-```
-
-The renderer already advances NSS's jitter sequence (Halton(2,3) sized
-via `NSS.recommended_jitter_sequence_size(upscale_ratio)`), forwards
-`reset_history` on view changes, and bumps `frame_count` per frame.
-
-## Differences from ARM's reference
-
-| Reference | This port |
-|---|---|
-| `VK_ARM_data_graph` for the network | Generic WGSL conv compute shader, one dispatch per layer |
-| INT8 quantization with TOSA RESCALE + TABLE | Per-channel `127 * mult / 2^shift` rescale + per-head `output_zp` shift before LUT lookup; LUT dequant matches ARM's `(int8 + 127) / 255` |
-| 2× preset uses a 4-tap LUT pattern | Generic 4×4 KPN footprint for any upscale ratio |
-| Mirror-pad to round to 8 | Compute shader early-outs out-of-range threads; same effect, no extra pass |
-| UE's sparse motion vectors | Engine velocity is already dense and pixel-space; no convert pass |
-| Feedback aliased as R8G8B8A8_SNORM image | Plain rgba16f texture |
-
-## References
-
-- ARM / Unreal plugin: <https://github.com/arm/neural-graphics-for-unreal/tree/main>
-- ARM SDK (kernel sources): `Source/NG-SDK/sdk/include/FidelityFX/gpu/nss/`
-- ARM SDK Model Parser: `Source/NG-SDK/sdk/tools/binary_store/Model_Parser.exe`
-- FSR2 depth-clip (used unchanged for the disocclusion mask):
-  <https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/blob/1bbe66e7ea0d358e84af4471a90aa9c35b583de0/sdk/include/FidelityFX/gpu/fsr2/ffx_fsr2_depth_clip.h>
-- Engine TAA pass (companion alternative): `../taa/TAA.js`.

package/src/shade/renderer/postprocess/perspective/NOTES.md

@@ -1,3 +0,0 @@
-# References
-
-* https://github.com/Fubaxiusz/fubax-shaders/blob/235ab7b10fa72e75d002274d3266a4f4916e3213/Shaders/PerfectPerspective.fx

package/src/shade/renderer/postprocess/sscs/NOTES.md

@@ -1,5 +0,0 @@
-# Screen-Space Contact Shadows
-
-### References:
-
-* https://github.com/google/filament/blob/2456299337f2205db5c1dd038213a46679b4cd77/shaders/src/shadowing.fs#L379

package/src/shade/renderer/postprocess/ssr/NOTES.md

@@ -1,14 +0,0 @@
-References:
-
-* https://github.com/stride3d/stride/blob/ab954eaa23a1c09769378fa4877bd5cafe8fb37a/sources/engine/Stride.Rendering/Rendering/Images/LocalReflections/SSLRRayTracePass.sdsl
-* [AMD FidelityFx/SSR](https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/blob/main/sdk/include/FidelityFX/gpu/sssr/ffx_sssr_intersect.h)
-
-HZB tracing:
-
-* GPU Gems 5
-* https://sugulee.wordpress.com/2021/01/19/screen-space-reflections-implementation-and-optimization-part-2-hi-z-tracing-method/
-
-random articles:
-
-* https://lettier.github.io/3d-game-shaders-for-beginners/screen-space-reflection.html
-* https://zznewclear13.github.io/posts/screen-space-reflection-en/

package/src/shade/renderer/postprocess/ssr/REPROJECTION_PROPOSAL.md

@@ -1,286 +0,0 @@
-# SSR reprojection proposal
-
-Status: implemented 2026-09-08, with the limitations below. The unused, invalid
-FidelityFX reprojection translation was removed. This document retains the review
-rationale and test plan, followed by implementation and validation details.
-
-## Objective and order of work
-
-Keep reflection history attached to the reflected image under camera motion, while
-rejecting history whose correspondence cannot be established. Prefer a small,
-testable implementation over completing the abandoned denoiser port.
-
-1. Repair history validity, motion-vector selection, and final blend confidence.
-2. Add virtual-image reprojection for coherent, approximately planar reflections.
-3. Add richer motion handling or temporal statistics only when a reproducible scene
-   demonstrates the need. Profile metadata traffic before committing to its format.
-
-The exact geometric guarantee in step 2 is for a static planar ideal mirror and a
-static reflected point under a perspective camera. Roughness, curvature, mixed
-lighting sources, and moving geometry make this an approximation. They must not
-silently inherit the same confidence guarantee.
-
-## Problems identified in the original implementation
-
-- `ssr_reproject_shader.js` uses the largest 3x3 velocity, whereas depth-clip validates
-  the nearest-depth pixel's velocity. Use `depth_clip_validated_velocity()` for the
-  existing surface candidate. This restores agreement with depth-clip; it does not
-  prove that the selected neighboring surface describes the reflection itself.
-- `SSR.reset_history` is not consumed, and `PostProcess.reset_history()` is empty.
-  Implement explicit validity for first use, reset, resize, and skipped rendering.
-  Publish a history generation only after it has been produced successfully. Keep
-  radiance, metadata, previous geometry, and camera state from the same view and
-  frame. Do not infer availability solely from global frame-number parity.
-- Confidence is currently applied before clamp damping and variance reweighting.
-  Apply it to the final normalized history weight, with current weight equal to
-  one minus that result. Hard invalidation must return the current sample before
-  reading or clipping history. Zero times an invalid value is not a safe reset.
-  Treat velocity magnitude as a tuning heuristic, separate from geometric validity.
-- Define the coordinate contract explicitly: pixel centers, internal resolution,
-  UV Y direction, reverse-Z, and each frame's jitter. GPU camera uniforms include
-  projection offsets, while camera velocity uses the underlying camera matrices.
-  Do not assume the existing velocity and a new matrix lookup address the same
-  history grid. Reconstruct from the current raster grid and project into the
-  previous raster grid, adding jitter conversion exactly once where needed.
-
-## Parallax geometry
-
-For camera position C, reflector point P, and Euclidean reflected-ray length L,
-all in world space:
-
-```text
-V = P + normalize(P - C) * L
-virtualUV = project(previousViewProjection, V)
-```
-
-V is the virtual image point behind the mirror. For an ideal planar reflection it
-also equals `H - 2 * N * dot(H - P, N)`, where H is the physical hit and N is the unit
-mirror normal. Projecting H itself addresses the directly visible object, not its
-reflection. Validate clip W and UV bounds before sampling. Invalid hit metadata
-must disable the virtual candidate; a miss is not a valid zero-distance hit.
-
-Keep surface and virtual candidates separate, including their validation results.
-Choose a supported candidate; do not interpolate UVs across unrelated history.
-Prefer virtual correspondence when the reflection is smooth and coherent. A valid
-surface correspondence is only a fallback heuristic for reflection radiance.
-
-For virtual-candidate reflector validation, reconstruct the previous geometry at
-that candidate and compare it to the reflector's local plane and normal in a common
-coordinate system. The corresponding point on a mirror usually changes between
-frames. Comparing against the old location of the current reflector point, or
-comparing virtual depth with G-buffer surface depth, rejects correct parallax.
-Use roughness/material agreement and identity where available. Plane agreement
-alone cannot distinguish disconnected coplanar surfaces.
-
-Validate the radiance sampling footprint too. A valid center does not make adjacent
-Catmull-Rom taps valid. Start with validated bilinear taps, renormalizing only the
-accepted nonnegative weights and rejecting an empty footprint. Keep higher-order
-reconstruction as a measured quality improvement, not a prerequisite for correctness.
-
-## Metadata must describe the signal being accumulated
-
-Resolve already reconstructs hit positions and reuses neighboring traces. Produce
-full-resolution distance plus support/confidence there, using the same accepted
-contributions as radiance. A neighbor's distance from its original ray origin is
-not the distance from the receiving pixel. Reconstruct that distance when reused.
-
-A simple initial policy is to enable virtual reprojection only for a dominant,
-coherent group of finite SSR hits. A representative distance is acceptable within
-that group; substantial distance disagreement or mixed fallback contributions
-reduces support. Two equally weighted depths must not become a trusted imaginary
-surface at their average. Do not average invalid hits into the estimate.
-
-The spatial filter before temporal reprojection also changes the radiance mixture.
-Its accepted contributions must propagate or conservatively reduce metadata support.
-Keeping center metadata while borrowing unrelated neighboring radiance breaks the
-contract just as it does in resolve. This is part of step 2, not optional cleanup.
-
-SSR/environment/LPV mixtures generally do not share one correspondence. Initially
-disable finite-hit reprojection when its support is insufficient and shorten history
-on source transitions. Separate histories and direction-based distant-environment
-reprojection remain possible later; LPV radiance is not necessarily at infinity.
-
-Do not change the packed trace format first. Although it has spare bits, first prove
-which distance the resolved signal requires. Start with explicit metadata and test
-its semantics. Consider half precision/packing afterward using a screen-error budget,
-finite representable ranges, and real scenes at different world scales. One extra
-RG16F history pair alone costs about 16.6 MB at 1920x1080, before previous geometry
-or other transient metadata. Reuse existing frame resources where lifetimes permit.
-
-## Adversarial assessment
-
-| Challenge | Consequence for the design |
-| --- | --- |
-| Mirror is static but the reflected object moves sideways | Mirror depth, normal, and roughness can all agree while virtual correspondence is wrong. Previous hit distance can also agree. Exact handling requires reflected-object motion/previous hit correspondence; otherwise use radiance disagreement or a reactive signal to shorten history and acknowledge residual ambiguity. |
-| Reflector moves or bends | Extending the current ray and projecting with previous camera matrices is insufficient. Support previous reflector geometry/transforms later; do not claim surface velocity alone solves this. |
-| Rough rays alternate between near and far objects | A single distance and large history weight produce false stability. Reduce support for a broad or inconsistent mixture; do not invent a trusted mean depth. |
-| Two mirrors are coplanar with identical normals | Plane/normal tests cannot establish identity. Use available identity and radiance/support checks; ambiguity must reduce confidence. |
-| Only the bilinear center passes depth validation | Invalid adjacent radiance can still bleed through. Validate the actual taps used to reconstruct history. |
-| Stable shader always rejects history | It avoids trails but fails denoising. Include a positive accumulation control, not just rejection tests. |
-| Large motion with accurate correspondence | A fixed 128-pixel cutoff is resolution dependent and discards valid samples. Keep this heuristic separate and tune using pixel uncertainty/footprint rather than treating speed as proof of invalidity. |
-| New moments and counters hide a wrong lookup | More statistical state cannot repair correspondence. Defer that state until the geometry and support contract pass. |
-
-An ordinary reflection G-buffer cannot completely disambiguate all these scenes.
-The first implementation should improve camera parallax without promising exact
-dynamic-scene reconstruction. If motion support is added later, keep it inside
-candidate construction/validation rather than patching the temporal blend.
-
-## Small test plan using the current software tools
-
-Use Vitest with `ComputeShaderEmulator.fromCodeChunk()` for production math helpers,
-`fromImageShader()` for production fragment passes, and `CPUBitmapData` for fixtures.
-Reuse the patterns in `taa/shader_taa.spec.js` and
-`taa/shader_depth_occlusion_clip.spec.js`. Most fixtures need only 16x16 or 32x16
-textures and a few selected pixels; no scene loader, full renderer, golden images,
-or new test framework is required. Use wider textures only when a motion case needs
-an in-bounds lookup. Test behavioral contracts, not shader source text.
-
-| Test group | Small fixture and independent expectation | Failure it should expose |
-| --- | --- | --- |
-| 1. Planar correspondence | Fix physical hit H and a plane. In JS reflect H across the plane, then intersect the current camera-to-image ray with the plane to obtain P and L. Run the production WGSL candidate helper and compare previous UV to an independently projected mirrored H. Parameterize lateral/forward camera movement, an oblique view, and jitter-only motion. Require subpixel error with a stated tolerance, initially 0.05 pixel for ordinary scales. Include stationary and valid L=0 mathematical controls. | Surface sticking, projecting physical H, wrong matrix order, double jitter, UV sign/half-pixel errors. The oracle must not repeat the implementation's ray-extension formula. |
-| 2. Rejection cannot be undone | Put distinct finite colors in current/history, and give current a varied neighborhood so clipping cannot conceal wrong reuse. Exercise history invalidity, off-screen/behind-camera candidate, and zero confidence. Vary current variance from 0 to 10000 while history variance is 0. Require current output for hard rejection; lowering confidence must not increase history influence when other inputs are fixed. | Blend/variance logic restoring rejected history; reset reading stale data; edge clamping masquerading as a valid lookup. |
-| 3. Validate the location actually used | A depth-clip fixture selects a slow center velocity while another neighbor is faster. Distinct history colors distinguish their destinations. Add one two-surface boundary with invalid bright neighboring taps and one valid tap. Assert selected correspondence and absence of invalid-tap influence. | A second dilation after depth-clip, confidence borrowed from the other candidate, unvalidated filtering footprints. |
-| 4. Support follows resolved radiance | Feed tiny resolve/filter fixtures with all misses, a coherent borrowed hit, and two substantially different hit distances or an SSR/fallback transition. Dispatch the production metadata-producing helpers/passes and the pre-temporal filter. Misses have no virtual support, coherent reuse remains eligible, ambiguous mixtures cannot become highly trusted solely by averaging. | Center-ray metadata attached to borrowed/filtered radiance; invalid zeros contaminating distance; source changes keeping stale confidence. |
-| 5. Useful accumulation and lifecycle | Manually ping-pong tiny textures for 8 deterministic frames of the planar scene with balanced synthetic noise; require lower error than raw input against the analytical signal. Then invalidate history and require the current sample. Separately record the real host path with `SoftwareGPUDevice` across first frame, next frame, reset, resize, and a skipped frame; check generation/validity and resource identity. | An always-reject implementation passing the suite; correct helper behavior never wired into SSR; old metadata paired with new radiance. |
-
-Keep these five groups in at most two shader spec files and one host lifecycle spec.
-Add parameter rows only for a newly observed failure. Compile helpers once per file.
-For hard-rejection tests, compare complete output including variance; for valid
-accumulation use error bounds rather than frozen implementation-specific blend values.
-The dynamic reflected-object counterexample is a documented limitation of the first
-phase, not a test that should bless visibly wrong correspondence as correct forever.
-
-### What the emulator can and cannot establish
-
-- Fragment dispatch, matrix/vector helpers, texture loads, and level-zero filtered
-  sampling already work. Manually writing results into the next `CPUBitmapData` is
-  sufficient for temporal sequences.
-- Mip levels are currently ignored by the emulator texture intrinsics. These tests
-  do not validate HZB traversal or roughness-dependent radiance mip selection. Use
-  synthetic accepted hits and level-zero radiance for reprojection tests.
-- `SoftwareGPURenderPassEncoder` records draws and bindings but does not rasterize
-  or write attachment pixels. Use it for host lifecycle/wiring, not image assertions.
-- Derivatives throw in point-wise fragment emulation; workgroup barriers are no-ops.
-  Keep the initial reprojection pass point-wise and express local consistency using
-  explicit neighboring loads. No workgroup-denoiser emulation is needed.
-- Do not assume all GPU numeric and format behavior is reproduced. The current
-  texture-load intrinsic constructs a Float32Array even for integer-backed textures,
-  which can lose packed-u32 low bits. Exercise codecs as direct helper calls rather
-  than claiming packed-trace integration coverage. Float16Array can model explicit
-  half-precision storage when evaluating a future metadata format.
-- Software success does not establish GPU performance, driver validation, or visual
-  quality on curved/rough materials. A small manual mirror/moving-object scene and
-  actual GPU timing remain useful before shipping; no native GPU is required in CI.
-
-## Adversarial probes performed during the initial review
-
-Three temporary adversarial Vitest probes ran successfully through the existing
-emulator (removed after review; permanent regression coverage is described below):
-
-1. Production SSR at zero velocity confidence returned approximately 1.079, 1.098,
-   and 1.100 for current radiance 1 and history 1.1 as current variance increased
-   from 0 to 10 to 10000. An experimental final-confidence gate returned exactly
-   current radiance and variance in all three cases. This checks the suggested
-   ordering, not a complete implementation of lifecycle or invalid-value handling.
-2. With a depth-clip selection of the center pixel, the old helper returned the
-   neighboring 8-pixel vector while `depth_clip_validated_velocity()` returned the
-   selected 1-pixel vector, including an 8-bit-quantized selection value.
-3. A prototype WGSL virtual-point helper matched independently mirrored hit geometry
-   for three camera positions. Moving only the reflected object by one world unit
-   produced 142.86 pixels of lookup error at focal length 1000 pixels and virtual
-   depth 7, despite unchanged mirror geometry. This falsifies the stronger claim
-   that reflector validation alone establishes dynamic reflection correspondence.
-
-## Implemented design and validation
-
-- Resolve emits radiance and an RG32F distance/support attachment in both IBL and
-  LPV paths. Distances are measured from the receiving pixel. Missing, background,
-  off-screen, non-finite, and zero-length hits cannot supply trusted metadata.
-- The first spatial pass propagates weighted distance moments and suppresses
-  support for broad mixtures. The two post-temporal spatial passes retain their
-  radiance-only interface to avoid unnecessary metadata traffic.
-- Temporal reprojection prefers the virtual image for support at least 0.75 and
-  roughness at most 0.2. Four bilinear taps are individually checked against
-  previous depth, world-space reflector plane/normal, roughness, support, and
-  reflected distance. Confidence includes the accepted footprint weight.
-- Surface fallback uses the existing depth-clip velocity selection and a single
-  previous-minus-current raster jitter correction. A failed smooth finite virtual
-  candidate limits surface confidence to one quarter. Radiance disagreement reduces
-  confidence further. These constants are initial heuristics, not geometric proofs.
-- Reset, resize, missing previous depth, skipped frames, and a different view disable
-  history. Radiance, distance/support, and normal/roughness ping-pong together. A
-  generation is committed only after successful graph execution and command
-  submission; abandoned/failed graphs and intervening resets cannot publish it.
-- Existing chunks supply coordinate reconstruction, NDC/UV conversion, depth and
-  material decoding, plane construction/distance, screen bounds, bilinear weights,
-  finite checks, depth-clip velocity, YCoCg conversion/clipping, and statistics.
-  Three SSR-specific chunks hold metadata moments, candidate math/blending, and
-  validated history sampling. No FidelityFX port or duplicate general math library
-  was introduced; the already-used edge-stopping chunks remain in use.
-
-Persistent overhead is **32 bytes per internal pixel** beyond the existing radiance
-pair: an RG32F metadata pair plus an RGBA16F normal/roughness pair. That is about
-**66.4 MB at 1920x1080** (63.3 MiB). Resolve and pre-temporal filtering also produce
-transient RG32F metadata; two such full-size attachments total another 33.2 MB
-before graph lifetime reuse. Previous depth is borrowed from the existing view
-resources. Reducing formats is deliberately deferred until screen-space error and
-GPU bandwidth are measured; this is a material cost of the initial implementation.
-
-Permanent coverage uses three spec files, with 14 tests organized around the five
-small groups above:
-
-- `ssr_reprojection.spec.js`: independent planar mirror oracle, translation,
-  rotation and jitter, hard reset without bound history textures, final-confidence
-  weighting, validated velocity, invalid bilinear taps, depth/normal/roughness/source
-  rejection, camera parallax, and an eight-frame positive denoising control.
-- `ssr_metadata.spec.js`: actual resolve and spatial fragment emulation, all misses,
-  zero-length self hits, borrowed hit distance, fallback/mixed-distance support,
-  plus WGSL validation for both resolve variants, both spatial variants, and temporal.
-- `SSR.spec.js`: real frame-graph/software-device recording through the final
-  spatial passes, matching radiance/metadata/geometry resource identities, resets,
-  resize, skipped frames, view changes, failed/abandoned graphs, and submission timing.
-
-Validation: all 14 SSR tests pass. Related TAA/depth-clip, normal call-site and plane
-chunk suites pass (38 tests, one existing skipped test). Declaration emission is
-clean and all consumer API pins compile. The repository type-error ratchet remains
-blocked at 899 errors against a budget of 897. An in-memory declaration comparison
-with these SSR-related changes reverted yields exactly the same 899 diagnostics:
-no additional consumer-visible type errors are introduced here. The budget was not
-changed.
-
-The software render device validates host recording, not pixels. Actual pixel
-assertions execute production fragment shaders through the emulator. LPV shader
-composition is validated, but its atlas sampling is not exercised by these fixtures.
-The new SSR reflection lab at `src/shade/playground/ssr_reprojection/` renders the
-production IBL path on a native NVIDIA GPU. All six SSR shader variants compile on
-that GPU. Visual controls for parallax/surface/current-frame comparison, moving
-objects, occlusion, camera cuts, resolution and final TAA were exercised. The SSR-off
-control visibly removes the reflected targets. There is still no isolated GPU timing
-or quantitative native image-quality measurement. The emulator limitations above
-still apply. A moving reflected object or curved reflector still
-requires conservative rejection and may retain residual trails; exact dynamic
-reflection correspondence is outside this first implementation.
-
-## Long-term boundary
-
-Keep geometry/candidate construction, candidate validation, and temporal accumulation
-as small independent production helpers. Their contract is a history location,
-support/confidence, and validity; temporal accumulation should not need to know
-whether a location came from SSR, a later ray tracer, or reflected-object motion.
-Keep history ownership and generation on the host explicit. Preserve independent
-geometric oracles and positive accumulation controls as algorithms evolve.
-
-AMD's [reflection denoiser documentation](https://gpuopen.com/manuals/fidelityfx_sdk/techniques/denoiser/)
-describes separate mirror-parallax and surface reprojection paths. The integration
-choices, limitations, and test strategy above are specific to this engine.
-
-The playground README describes the repeatable visual checks and independent
-planar reflection guides. Its comparison modes share production shader code;
-changing mode invalidates history, and Parallax remains the default.
-
-Follow-up visual validation found that zero resolve variance could make spatial
-denoising nearly inert. The first spatial pass now bootstraps variance from local
-luminance and propagates the resulting uncertainty; later passes only consume it.
-A same-frame GPU probe and a zero-variance noisy-input regression now cover actual
-filter effect, not only graph wiring. See the playground README for measurements
-and the remaining sharpness/noise tradeoff. The SSR suite now contains 16 tests.