@woosh/meep-engine 3.39.0 → 3.40.0

package/src/format/image/avif/api/convert_to_rgba.js

@@ -3,7 +3,6 @@ import { clamp_sample } from "../color/clamp_sample.js";
 import { colour_transform_init } from "../color/ColourTransform.js";
 import { LINEAR_REFERENCE_NITS } from "../color/transfer_to_linear.js";
 import { MC_BT_601 } from "../av1/tables/av1_symbols.js";
-import { to_half_float_uint16 } from "../../../../core/binary/to_half_float_uint16.js";
 import { transfer_row_to_linear } from "../color/transfer_to_linear.js";
 import { UPSAMPLE_BILINEAR, UPSAMPLE_NEAREST, upsample_chroma_row } from "../color/upsample_chroma_row.js";
 import { ycbcr_row_to_rgb } from "../color/ycbcr_row_to_rgb.js";
@@ -50,7 +49,7 @@ export const CHROMA_UPSAMPLING_BEST = 2;
  *   for, in nits; defaults to {@link LINEAR_REFERENCE_NITS}. Only read for `COLOUR_SPACE_LINEAR`,
  *   and the exact counterpart of {@link encode_avif}'s option of the same name
  * @param {number} [options.chroma_upsampling] one of the `CHROMA_UPSAMPLING_*` constants
- * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ * @returns {{data: (Uint8ClampedArray|Uint16Array|Float16Array), width: number, height: number}}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -98,9 +97,9 @@ export function convert_to_rgba(decoder, image, options = {}) {
 
     const samples = width * height * 4;
 
-    const data = output_float16 || output_bit_depth > 8
-        ? new Uint16Array(samples)
-        : new Uint8ClampedArray(samples);
+    const data = output_float16
+        ? new Float16Array(samples)
+        : output_bit_depth > 8 ? new Uint16Array(samples) : new Uint8ClampedArray(samples);
 
     const maximum = (1 << output_bit_depth) - 1;
 
@@ -180,10 +179,12 @@ export function convert_to_rgba(decoder, image, options = {}) {
                 : clamp01((image.alpha[alpha_row + x] - alpha_offset) * alpha_scale);
 
             if (output_float16) {
-                data[out] = to_half_float_uint16(rgb_row[i]);
-                data[out + 1] = to_half_float_uint16(rgb_row[i + 1]);
-                data[out + 2] = to_half_float_uint16(rgb_row[i + 2]);
-                data[out + 3] = to_half_float_uint16(alpha);
+                for (let c = 0; c < 3; c++) {
+                    const value = rgb_row[i + c];
+                    // Preserve finite HDR saturation, even with a very small reference white.
+                    data[out + c] = Number.isFinite(value) ? Math.min(Math.max(value, -65504), 65504) : value;
+                }
+                data[out + 3] = alpha;
             } else {
                 data[out] = quantise(rgb_row[i], maximum);
                 data[out + 1] = quantise(rgb_row[i + 1], maximum);

package/src/format/image/avif/api/decode_avif.d.ts

@@ -10,13 +10,13 @@
  *   file's declared orientation — off by default, because the decoder this replaces left it to its
  *   caller and a caller that already handles orientation would otherwise apply it twice
  * @param {AvifDecoder} [decoder] pass one back in to decode many images without reallocating
- * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ * @returns {{data: (Uint8ClampedArray|Uint16Array|Float16Array), width: number, height: number}}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
 export function decode_avif(buffer: ArrayBuffer | Uint8Array, options?: object, decoder?: AvifDecoder): {
-    data: (Uint8ClampedArray | Uint16Array);
+    data: (Uint8ClampedArray | Uint16Array | Float16Array);
     width: number;
     height: number;
 };

package/src/format/image/avif/api/decode_avif.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decode_avif.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/api/decode_avif.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;GAgBG;AACH,oCAVW,WAAW,GAAC,UAAU,YACtB,MAAM,YAGN,WAAW,GACT;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAmClF;4BA/D2B,kBAAkB"}
+{"version":3,"file":"decode_avif.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/api/decode_avif.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;GAgBG;AACH,oCAVW,WAAW,GAAC,UAAU,YACtB,MAAM,YAGN,WAAW,GACT;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,eAAa,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAmC/F;4BA/D2B,kBAAkB"}

package/src/format/image/avif/api/decode_avif.js

@@ -26,7 +26,7 @@ const ALPHA_AUX_TYPE = "urn:mpeg:mpegB:cicp:systems:auxiliary:alpha";
  *   file's declared orientation — off by default, because the decoder this replaces left it to its
  *   caller and a caller that already handles orientation would otherwise apply it twice
  * @param {AvifDecoder} [decoder] pass one back in to decode many images without reallocating
- * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ * @returns {{data: (Uint8ClampedArray|Uint16Array|Float16Array), width: number, height: number}}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

package/src/shade/playground/ssr_reprojection/README.md

@@ -1,103 +1,111 @@
-# SSR reflection lab
-
-Run `npm run dev` from `packages/meep-engine`, then open
-<http://localhost:5173/src/shade/playground/ssr_reprojection/>.
-The page uses the actual WebGPU renderer and production SSR shaders. Geometry and
-environment lighting are procedural; only the engine's bundled lookup/noise textures
-are loaded. The browser must meet the renderer's WebGPU feature requirements.
-
-## Five-minute check
-
-1. Start with **Lateral camera**, **Parallax**, roughness **0.03**, and final TAA off.
-   Watch the reflected coloured blocks move relative to the floor grid. Solid crosses
-   mark ideal planar-mirror image centres. Dashed crosses are fixed floor positions,
-   aligned at the start of the path. Their separation illustrates surface sticking.
-2. Select **Surface only**, then **No temporal history**. Switching mode restarts
-   the path and resets histories. Compare edge lag and noise at the same part of the
-   repeatable path. Surface only uses the new validation/blending, not the old shader.
-3. Try **Forward camera** and **Orbit camera**, then raise roughness through 0.2.
-   The virtual candidate is deliberately restricted to smooth, coherent reflections.
-4. Use **Moving object** and **Occluder** to expose residual trails and disocclusion.
-   Moving reflected geometry is an acknowledged limitation. Missing off-screen or
-   hidden source geometry is also an SSR limitation, not necessarily a reprojection bug.
-5. Press **Camera cut**, **Reset reflection history**, and change resolution.
-   Old reflections should not persist. **SSR off** is a useful control proving that
-   the visible reflection comes from SSR rather than the flat environment.
-
-The guides reflect physical object centres across y=0 independently of the temporal
-ray-extension formula. They are geometry guides, not colour references: visible
-front faces, occlusion and roughness do not necessarily centre on the marker. The
-floor is planar and its top is exactly y=0. Grid strips slightly above it are visible
-surface landmarks. Guides do not perform occlusion testing.
-
-The page fixes exposure and disables bloom, sharpening, ambient occlusion and motion
-blur. Final-image TAA defaults off to expose SSR's own temporal behaviour. Pause
-motion leaves temporal sampling running; **Still camera / noise** does the same at
-the initial view. **Step frame** advances the motion by 1/60 second. For exact manual
-frame counts, append `?manual` to the URL: no animation loop is scheduled, and the
-step button submits one frame at a time. From the browser console,
-`ssr_lab.step(60)` advances 60 deterministic frames at 1/60 second.
-
-**Validate GPU shaders** compiles trace, both resolves, both spatial variants, and
-temporal reprojection on the live GPU. This checks native WGSL compilation, while
-running the playground also exercises IBL pipeline creation and frame-graph wiring.
-The page reports and stops on uncaptured GPU errors. LPV composition is checked but
-the procedural scene uses IBL, so this does not test LPV atlas content or lighting.
-
-Production integration is small: `renderer.ssr.reprojection_mode` selects
-`SSRReprojectionMode.Parallax`, `.Surface`, or `.CurrentFrame`. Changing it invalidates
-SSR history. Default rendering continues to use Parallax.
-
-Do not use frame rate on this page as an SSR-only GPU timing measurement. It includes
-the entire renderer, the browser, and the overlay. Profile the actual passes before
-making performance claims. HMR is disabled by the playground Vite config; reload
-the browser explicitly after source edits.
-
-## Validation performed
-
-The page was exercised on the native NVIDIA adapter: IBL rendering, all four
-comparison modes, a moving target and occluder, camera cut, resolution change,
-and final TAA toggle. The SSR-off control visibly removes the reflections.
-All six SSR shader modules compile on that device, and the 14 SSR regression
-tests pass. Declaration emission and consumer API pins pass; the existing
-repository type-error budget is still exceeded (899 errors versus 897).
-
-## Spatial denoising
-
-The **Spatial denoising** checkbox defaults on. It toggles one spatial pass before
-reprojection and two afterward; the chosen reprojection mode stays unchanged.
-Changing this setting resets SSR history so filtered and unfiltered inputs are not
-mixed across the transition. The runtime setting is
-`renderer.ssr.spatial_denoising_enabled`. With the box unchecked and **No temporal
-history** selected, the output comes directly from resolve. Resolve still borrows
-neighbouring ray hits and uses roughness-dependent radiance filtering; this switch
-does not turn the resolve stage into a raw one-ray-per-pixel view.
-
-## Measuring actual filter effectiveness
-
-**Measure spatial filter** records the first spatial pass's input and output in
-one GPU frame. It reports the fraction of upward-facing mirror pixels whose maximum
-RGB-channel difference exceeds 0.001, mean/max difference in linear HDR radiance,
-and the fraction whose input variance is effectively zero. It is an effect check,
-not an image-quality score or an SSR performance benchmark. Readback runs only on
-request; its temporary texture is released afterward. Ordinary playback has no
-probe passes. SSR must be enabled. With spatial filtering off, the bypass is compared
-with itself and the measured difference is zero.
-
-This probe exposed a filter failure on 2026-09-08: roughly 98% of this scene's mirror
-pixels had resolve variance ≤1e-6. The old first pass changed radiance by just 0.00137
-on average; the sparse noisy samples were being rejected as colour edges. Resolve's
-within-pixel ray variance is not sufficient evidence of low spatial noise when only
-one hit supplies radiance or the hit confidence switches between SSR and fallback.
-
-The first pass now bootstraps uncertainty from a Gaussian-weighted 3×3 luminance
-neighbourhood, using the existing geometry weights, and carries that uncertainty
-through the subsequent spatial passes. It does not bootstrap again at larger radii.
-A representative corrected GPU measurement gave mean change 0.00552 with filtering
-on, and 0 with it off. These are separate frames, not a matched-noise quality metric.
-The native images visibly differ, and an emulator regression verifies reduced
-checker noise with zero input variance, unchanged constant colour (within float
-precision), and rejection across opposite normals. The full SSR suite has 16 tests.
-
-Spatial filtering trades sharpness for noise reduction, including at reflected
-colour edges; these guides and tests do not establish an optimal filter bandwidth.
+# SSR reflection lab
+
+Run `npm run dev` from `packages/meep-engine`, then open
+<http://localhost:5173/src/shade/playground/ssr_reprojection/>.
+The page uses the actual WebGPU renderer and production SSR shaders. Geometry and
+environment lighting are procedural; only the engine's bundled lookup/noise textures
+are loaded. The browser must meet the renderer's WebGPU feature requirements.
+
+## Five-minute check
+
+1. Start with **Lateral camera**, **Parallax**, roughness **0.03**, and final TAA off.
+   Watch the reflected coloured blocks move relative to the floor grid. Solid crosses
+   mark ideal planar-mirror image centres. Dashed crosses are fixed floor positions,
+   aligned at the start of the path. Their separation illustrates surface sticking.
+2. Select **Surface only**, then **No temporal history**. Switching mode restarts
+   the path and resets histories. Compare edge lag and noise at the same part of the
+   repeatable path. Surface only uses the new validation/blending, not the old shader.
+3. Try **Forward camera** and **Orbit camera**, then raise roughness through 0.2.
+   The virtual candidate is deliberately restricted to smooth, coherent reflections.
+4. Use **Moving object** and **Occluder** to expose residual trails and disocclusion.
+   Moving reflected geometry is an acknowledged limitation. Missing off-screen or
+   hidden source geometry is also an SSR limitation, not necessarily a reprojection bug.
+5. Press **Camera cut**, **Reset reflection history**, and change resolution.
+   Old reflections should not persist. **SSR off** is a useful control proving that
+   the visible reflection comes from SSR rather than the flat environment.
+
+The guides reflect physical object centres across y=0 independently of the temporal
+ray-extension formula. They are geometry guides, not colour references: visible
+front faces, occlusion and roughness do not necessarily centre on the marker. The
+floor is planar and its top is exactly y=0. Grid strips slightly above it are visible
+surface landmarks. Guides do not perform occlusion testing.
+
+The page fixes exposure and disables bloom, sharpening, ambient occlusion and motion
+blur. Final-image TAA defaults off to expose SSR's own temporal behaviour. Pause
+motion leaves temporal sampling running; **Still camera / noise** does the same at
+the initial view. **Step frame** advances the motion by 1/60 second. For exact manual
+frame counts, append `?manual` to the URL: no animation loop is scheduled, and the
+step button submits one frame at a time. From the browser console,
+`ssr_lab.step(60)` advances 60 deterministic frames at 1/60 second.
+
+**Validate GPU shaders** compiles trace, both resolves, both spatial variants, and
+temporal reprojection on the live GPU. This checks native WGSL compilation, while
+running the playground also exercises IBL pipeline creation and frame-graph wiring.
+The page reports and stops on uncaptured GPU errors. LPV composition is checked but
+the procedural scene uses IBL, so this does not test LPV atlas content or lighting.
+
+Production integration is small: `renderer.ssr.reprojection_mode` selects
+`SSRReprojectionMode.Parallax`, `.Surface`, or `.CurrentFrame`. Changing it invalidates
+SSR history. Default rendering continues to use Parallax.
+
+Do not use frame rate on this page as an SSR-only GPU timing measurement. It includes
+the entire renderer, the browser, and the overlay. Profile the actual passes before
+making performance claims. HMR is disabled by the playground Vite config; reload
+the browser explicitly after source edits.
+
+## Validation performed
+
+The page was exercised on the native NVIDIA adapter: IBL rendering, all four
+comparison modes, a moving target and occluder, camera cut, resolution change,
+and final TAA toggle. The SSR-off control visibly removes the reflections.
+All six SSR shader modules compile on that device, and the 14 SSR regression
+tests pass. Declaration emission and consumer API pins pass; the existing
+repository type-error budget is still exceeded (899 errors versus 897).
+
+## Spatial denoising
+
+The **Spatial denoising** checkbox defaults on. It toggles one spatial pass before
+reprojection and two afterward; the chosen reprojection mode stays unchanged.
+Changing this setting resets SSR history so filtered and unfiltered inputs are not
+mixed across the transition. The runtime setting is
+`renderer.ssr.spatial_denoising_enabled`. With the box unchecked and **No temporal
+history** selected, the output comes directly from resolve. Resolve still borrows
+neighbouring ray hits and uses roughness-dependent radiance filtering; this switch
+does not turn the resolve stage into a raw one-ray-per-pixel view.
+
+**Coverage tile denoising** is opt-in through `renderer.ssr.tile_denoising_enabled`.
+It classifies 8×8 internal-pixel tiles and protects the full spatial/temporal filter
+reach with a two-tile halo. Only stationary, constant radiance with no SSR support,
+uncertainty, or changing history can skip spatial work. Temporal geometry validation
+and history age still run; only proven constant neighborhood statistics are bypassed.
+Changing the setting resets history. Classification adds overhead, so profile
+the intended scene and device before enabling it, especially at low resolutions.
+
+## Measuring actual filter effectiveness
+
+**Measure spatial filter** records the first spatial pass's input and output in
+one GPU frame. It reports the fraction of upward-facing mirror pixels whose maximum
+RGB-channel difference exceeds 0.001, mean/max difference in linear HDR radiance,
+and the fraction whose input variance is effectively zero. It is an effect check,
+not an image-quality score or an SSR performance benchmark. Readback runs only on
+request; its temporary texture is released afterward. Ordinary playback has no
+probe passes. SSR must be enabled. With spatial filtering off, the bypass is compared
+with itself and the measured difference is zero.
+
+This probe exposed a filter failure on 2026-09-08: roughly 98% of this scene's mirror
+pixels had resolve variance ≤1e-6. The old first pass changed radiance by just 0.00137
+on average; the sparse noisy samples were being rejected as colour edges. Resolve's
+within-pixel ray variance is not sufficient evidence of low spatial noise when only
+one hit supplies radiance or the hit confidence switches between SSR and fallback.
+
+The first pass now bootstraps uncertainty from a Gaussian-weighted 3×3 luminance
+neighbourhood, using the existing geometry weights, and carries that uncertainty
+through the subsequent spatial passes. It does not bootstrap again at larger radii.
+A representative corrected GPU measurement gave mean change 0.00552 with filtering
+on, and 0 with it off. These are separate frames, not a matched-noise quality metric.
+The native images visibly differ, and an emulator regression verifies reduced
+checker noise with zero input variance, unchanged constant colour (within float
+precision), and rejection across opposite normals. The full SSR suite has 16 tests.
+
+Spatial filtering trades sharpness for noise reduction, including at reflected
+colour edges; these guides and tests do not establish an optimal filter bandwidth.

package/src/shade/playground/ssr_reprojection/SpatialFilterProbe.js

@@ -1,68 +1,68 @@
-import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
-import { ImageShader } from "../../renderer/shader/ImageShader.js";
-import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
-import { chunk_decode_g_buffer_normal } from "../../renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
-import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
-import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
-import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
-import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
-import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
-import { download_texture_data } from "../../renderer/texture/download_texture_data.js";
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup().addTexture('tBefore').addTexture('tAfter').addTexture('tNormal', 'uint');
-const shader = new ImageShader({
-    descriptor: ShaderDescriptor.from({label:'SSR lab / spatial effect',resources,
-        body:CodeChunk.from(/* language=WGSL */ `
-@fragment fn main(@builtin(position) coord:vec4f) -> @location(0) vec4f {
-    let p = vec2i(coord.xy);
-    if (decode_g_buffer_normal(textureLoad(tNormal,p,0).xy).y < 0.99) { return vec4f(-1.0); }
-    let a = textureLoad(tBefore,p,0);
-    let b = textureLoad(tAfter,p,0);
-    let difference = abs(a.rgb-b.rgb);
-    return vec4f(max(difference.r,max(difference.g,difference.b)),a.w,b.w,1.0);
-}`, [chunk_decode_g_buffer_normal])}),
-    targets:[{format:'rgba32float'}],
-});
-
-/** Same-frame GPU input/output comparison. Opt-in; no cost during ordinary playback. */
-export class SpatialFilterProbe extends RenderExtension {
-    name = 'SSR lab / measure spatial filter';
-    enabled = false;
-    texture;
-    device;
-    constructor(device) { super(); this.device=device; }
-    record(frame) {
-        if (!this.enabled) { return; }
-        // This diagnostic intentionally inspects the playground's production graph.
-        const pass=frame.graph.__pass_nodes.find(p=>p.name==='SSR / spatial denoise with metadata');
-        const resolve=frame.graph.__pass_nodes.find(p=>p.name==='SSR resolve / IBL');
-        if (!resolve) { throw new Error('Enable SSR to measure its spatial filter.'); }
-        const before=pass ? pass.data.tInput : resolve.data['@output'][0];
-        const after=pass ? pass.data['@output'][0] : before;
-        const [width,height]=frame.resolution;
-        if (!this.texture || this.texture.width!==width || this.texture.height!==height) {
-            this.texture?.destroy();
-            this.texture=GPUTextureContext.fromTexture(this.device.createTexture({
-                size:[width,height,1],format:'rgba32float',
-                usage:GPUTextureUsage.RENDER_ATTACHMENT|GPUTextureUsage.COPY_SRC,
-            }),this.device);
-        }
-        graph_image_pass({graph:frame.graph,shader,
-            inputs:{tBefore:before,tAfter:after,tNormal:resolve.data.tNormal},
-            output:[graph_import_texture(frame.graph,this.texture,'SSR spatial measurement')],
-        });
-    }
-    async read() {
-        const data=await download_texture_data({device:this.device,source:this.texture.gpu_texture});
-        let pixels=0,changed=0,zero_variance=0,mean=0,max=0;
-        for(let i=0;i<data.length;i+=4) {
-            if(data[i]<0) { continue; }
-            if(!Number.isFinite(data[i])) { throw new Error('Non-finite denoising output.'); }
-            pixels++; changed+=data[i]>0.001 ? 1 : 0; zero_variance+=data[i+1]<=1e-6 ? 1 : 0;
-            mean+=data[i]; max=Math.max(max,data[i]);
-        }
-        if(pixels===0) { throw new Error('No upward-facing mirror pixels in this view.'); }
-        return {pixels,changed_percent:100*changed/pixels,zero_variance_percent:100*zero_variance/pixels,mean:mean/pixels,max};
-    }
-}
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+import { ImageShader } from "../../renderer/shader/ImageShader.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { chunk_decode_g_buffer_normal } from "../../renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
+import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
+import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
+import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
+import { download_texture_data } from "../../renderer/texture/download_texture_data.js";
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup().addTexture('tBefore').addTexture('tAfter').addTexture('tNormal', 'uint');
+const shader = new ImageShader({
+    descriptor: ShaderDescriptor.from({label:'SSR lab / spatial effect',resources,
+        body:CodeChunk.from(/* language=WGSL */ `
+@fragment fn main(@builtin(position) coord:vec4f) -> @location(0) vec4f {
+    let p = vec2i(coord.xy);
+    if (decode_g_buffer_normal(textureLoad(tNormal,p,0).xy).y < 0.99) { return vec4f(-1.0); }
+    let a = textureLoad(tBefore,p,0);
+    let b = textureLoad(tAfter,p,0);
+    let difference = abs(a.rgb-b.rgb);
+    return vec4f(max(difference.r,max(difference.g,difference.b)),a.w,b.w,1.0);
+}`, [chunk_decode_g_buffer_normal])}),
+    targets:[{format:'rgba32float'}],
+});
+
+/** Same-frame GPU input/output comparison. Opt-in; no cost during ordinary playback. */
+export class SpatialFilterProbe extends RenderExtension {
+    name = 'SSR lab / measure spatial filter';
+    enabled = false;
+    texture;
+    device;
+    constructor(device) { super(); this.device=device; }
+    record(frame) {
+        if (!this.enabled) { return; }
+        // This diagnostic intentionally inspects the playground's production graph.
+        const pass=frame.graph.__pass_nodes.find(p=>p.name.startsWith('SSR / spatial denoise with metadata'));
+        const resolve=frame.graph.__pass_nodes.find(p=>p.name==='SSR resolve / IBL');
+        if (!resolve) { throw new Error('Enable SSR to measure its spatial filter.'); }
+        const before=pass ? pass.data.tInput : resolve.data['@output'][0];
+        const after=pass ? pass.data['@output'][0] : before;
+        const [width,height]=frame.resolution;
+        if (!this.texture || this.texture.width!==width || this.texture.height!==height) {
+            this.texture?.destroy();
+            this.texture=GPUTextureContext.fromTexture(this.device.createTexture({
+                size:[width,height,1],format:'rgba32float',
+                usage:GPUTextureUsage.RENDER_ATTACHMENT|GPUTextureUsage.COPY_SRC,
+            }),this.device);
+        }
+        graph_image_pass({graph:frame.graph,shader,
+            inputs:{tBefore:before,tAfter:after,tNormal:resolve.data.tNormal},
+            output:[graph_import_texture(frame.graph,this.texture,'SSR spatial measurement')],
+        });
+    }
+    async read() {
+        const data=await download_texture_data({device:this.device,source:this.texture.gpu_texture});
+        let pixels=0,changed=0,zero_variance=0,mean=0,max=0;
+        for(let i=0;i<data.length;i+=4) {
+            if(data[i]<0) { continue; }
+            if(!Number.isFinite(data[i])) { throw new Error('Non-finite denoising output.'); }
+            pixels++; changed+=data[i]>0.001 ? 1 : 0; zero_variance+=data[i+1]<=1e-6 ? 1 : 0;
+            mean+=data[i]; max=Math.max(max,data[i]);
+        }
+        if(pixels===0) { throw new Error('No upward-facing mirror pixels in this view.'); }
+        return {pixels,changed_percent:100*changed/pixels,zero_variance_percent:100*zero_variance/pixels,mean:mean/pixels,max};
+    }
+}

package/src/shade/playground/ssr_reprojection/index.html

@@ -1,79 +1,80 @@
-<!doctype html>
-<html lang="en">
-<head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>Meep — SSR reflection lab</title>
-    <style>
-        :root { color-scheme: dark; font: 14px/1.5 system-ui, sans-serif; background: #11151c; color: #e4eaf2; }
-        * { box-sizing: border-box; }
-        body { margin: 0; padding: 24px; }
-        header { display: flex; align-items: baseline; gap: 16px; margin-bottom: 18px; }
-        h1 { font-size: 24px; margin: 0; font-weight: 600; }
-        header span, .hint, small { color: #a2afc1; }
-        main { display: grid; grid-template-columns: minmax(0, 1fr) 290px; gap: 20px; align-items: start; }
-        .stage { position: relative; background: #090c11; border: 1px solid #344153; border-radius: 8px; overflow: hidden; }
-        /* Renderer writes inline presentation dimensions; both layers must scale together. */
-        canvas { display: block; width: 100% !important; height: auto !important; }
-        #overlay { position: absolute; inset: 0; pointer-events: none; }
-        aside { background: #1a212c; border: 1px solid #344153; border-radius: 8px; padding: 18px; }
-        label { display: block; margin-bottom: 13px; }
-        label > span { display: block; font-size: 12px; color: #a2afc1; margin-bottom: 4px; }
-        select, button { width: 100%; background: #252f3e; border: 1px solid #45556a; color: inherit; border-radius: 5px; padding: 8px; font: inherit; }
-        button { cursor: pointer; }
-        button:hover { background: #344359; }
-        button:disabled { opacity: .4; cursor: default; }
-        .buttons { display: flex; gap: 8px; margin-bottom: 10px; }
-        .check { display: flex; gap: 8px; align-items: center; }
-        input[type=range] { width: 100%; accent-color: #74c8ff; }
-        hr { border: 0; border-top: 1px solid #344153; margin: 18px 0; }
-        #status { font: 12px/1.5 ui-monospace, Consolas, monospace; white-space: pre-wrap; color: #95d6b4; }
-        #status.error { color: #ff9a9a; }
-        #hint { min-height: 3em; margin: 14px 0 0; }
-        .legend { display: flex; gap: 24px; flex-wrap: wrap; margin-top: 12px; color: #a2afc1; font-size: 12px; }
-        .legend b { color: #dce9ff; }
-        details { margin-top: 18px; max-width: 85ch; color: #a2afc1; }
-        summary { color: #dce9ff; cursor: pointer; }
-        @media (max-width: 850px) { main { grid-template-columns: 1fr; } aside { width: 100%; } header { display: block; } }
-    </style>
-</head>
-<body tabindex="0">
-<header><h1>SSR reflection lab</h1><span>Camera parallax · temporal stability · rejection</span></header>
-<main>
-    <section>
-        <div class="stage"><canvas id="view" width="960" height="600" tabindex="0" aria-label="Interactive WebGPU reflection scene"></canvas><canvas id="overlay" width="960" height="600" aria-hidden="true"></canvas></div>
-        <div class="legend"><span><b>Solid cross</b> — ideal reflected centre</span><span><b>Dashed cross</b> — point fixed to the floor</span></div>
-        <p id="hint" class="hint"></p>
-        <details open><summary>A quick visual check</summary>
-            <ol>
-                <li>Run <b>Lateral camera</b> with <b>Parallax</b>. Reflections should follow the solid crosses as the floor moves underneath.</li>
-                <li>Restart the same motion with <b>Surface only</b>, then <b>No temporal history</b>. Look for trails, delayed edges, and changes in noise.</li>
-                <li>Try <b>Moving object</b> and <b>Occluder</b>. Inspect the magenta object’s trail and newly revealed floor. Use <b>Camera cut</b> to check reset.</li>
-            </ol>
-            <p><b>Spatial denoising</b> smooths neighbouring reflection pixels in three passes. It is on by default and independent of reprojection. Turn it off and select <b>No temporal history</b> to inspect the resolve output; resolve still reuses neighbouring ray hits and filters radiance for roughness.</p>
-            <p>The crosses are geometric guides for object centres, not a pixel-perfect lighting reference. SSR loses information when reflected objects are hidden or off-screen. Surface only retains the new validation and blending fixes; it is not the old shader.</p>
-        </details>
-    </section>
-    <aside>
-        <label><span>Reprojection</span><select id="mode"><option value="0">Parallax</option><option value="1">Surface only</option><option value="2">No temporal history</option><option value="off">SSR off</option></select></label>
-        <label><span>Experiment</span><select id="experiment"><option value="lateral">Lateral camera</option><option value="forward">Forward camera</option><option value="orbit">Orbit camera</option><option value="object">Moving object</option><option value="occluder">Occluder</option><option value="still">Still camera / noise</option><option value="free">Free camera</option></select></label>
-        <label><span>Motion speed <output id="speed-value">1.0×</output></span><input id="speed" aria-label="Motion speed" type="range" min="0.2" max="2" value="1" step="0.1"></label>
-        <label><span>Mirror roughness <output id="roughness-value">0.03</output></span><input id="roughness" aria-label="Mirror roughness" type="range" min="0.01" max="0.7" value="0.03" step="0.01"></label>
-        <label><span>Render resolution</span><select id="resolution"><option value="640">640 × 400</option><option value="960" selected>960 × 600</option><option value="1280">1280 × 800</option></select></label>
-        <label class="check"><input id="guides" type="checkbox" checked>Show geometric guides</label>
-        <label class="check"><input id="denoising" type="checkbox" checked>Spatial denoising</label>
-        <label class="check"><input id="taa" type="checkbox">Final-image TAA</label>
-        <hr>
-        <div class="buttons"><button id="play">Pause motion</button><button id="step">Step frame</button></div>
-        <div class="buttons"><button id="restart">Restart path</button><button id="cut">Camera cut</button></div>
-        <button id="reset">Reset reflection history</button>
-        <hr>
-        <button id="measure">Measure spatial filter</button>
-        <button id="compile">Validate GPU shaders</button>
-        <p id="status" role="status">Starting WebGPU…</p>
-        <small>Fixed exposure. Bloom, sharpening, and motion blur are off. Free camera: drag to orbit, right-drag to pan, wheel to zoom.</small>
-    </aside>
-</main>
-<script type="module" src="./main.js"></script>
-</body>
-</html>
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Meep — SSR reflection lab</title>
+    <style>
+        :root { color-scheme: dark; font: 14px/1.5 system-ui, sans-serif; background: #11151c; color: #e4eaf2; }
+        * { box-sizing: border-box; }
+        body { margin: 0; padding: 24px; }
+        header { display: flex; align-items: baseline; gap: 16px; margin-bottom: 18px; }
+        h1 { font-size: 24px; margin: 0; font-weight: 600; }
+        header span, .hint, small { color: #a2afc1; }
+        main { display: grid; grid-template-columns: minmax(0, 1fr) 290px; gap: 20px; align-items: start; }
+        .stage { position: relative; background: #090c11; border: 1px solid #344153; border-radius: 8px; overflow: hidden; }
+        /* Renderer writes inline presentation dimensions; both layers must scale together. */
+        canvas { display: block; width: 100% !important; height: auto !important; }
+        #overlay { position: absolute; inset: 0; pointer-events: none; }
+        aside { background: #1a212c; border: 1px solid #344153; border-radius: 8px; padding: 18px; }
+        label { display: block; margin-bottom: 13px; }
+        label > span { display: block; font-size: 12px; color: #a2afc1; margin-bottom: 4px; }
+        select, button { width: 100%; background: #252f3e; border: 1px solid #45556a; color: inherit; border-radius: 5px; padding: 8px; font: inherit; }
+        button { cursor: pointer; }
+        button:hover { background: #344359; }
+        button:disabled { opacity: .4; cursor: default; }
+        .buttons { display: flex; gap: 8px; margin-bottom: 10px; }
+        .check { display: flex; gap: 8px; align-items: center; }
+        input[type=range] { width: 100%; accent-color: #74c8ff; }
+        hr { border: 0; border-top: 1px solid #344153; margin: 18px 0; }
+        #status { font: 12px/1.5 ui-monospace, Consolas, monospace; white-space: pre-wrap; color: #95d6b4; }
+        #status.error { color: #ff9a9a; }
+        #hint { min-height: 3em; margin: 14px 0 0; }
+        .legend { display: flex; gap: 24px; flex-wrap: wrap; margin-top: 12px; color: #a2afc1; font-size: 12px; }
+        .legend b { color: #dce9ff; }
+        details { margin-top: 18px; max-width: 85ch; color: #a2afc1; }
+        summary { color: #dce9ff; cursor: pointer; }
+        @media (max-width: 850px) { main { grid-template-columns: 1fr; } aside { width: 100%; } header { display: block; } }
+    </style>
+</head>
+<body tabindex="0">
+<header><h1>SSR reflection lab</h1><span>Camera parallax · temporal stability · rejection</span></header>
+<main>
+    <section>
+        <div class="stage"><canvas id="view" width="960" height="600" tabindex="0" aria-label="Interactive WebGPU reflection scene"></canvas><canvas id="overlay" width="960" height="600" aria-hidden="true"></canvas></div>
+        <div class="legend"><span><b>Solid cross</b> — ideal reflected centre</span><span><b>Dashed cross</b> — point fixed to the floor</span></div>
+        <p id="hint" class="hint"></p>
+        <details open><summary>A quick visual check</summary>
+            <ol>
+                <li>Run <b>Lateral camera</b> with <b>Parallax</b>. Reflections should follow the solid crosses as the floor moves underneath.</li>
+                <li>Restart the same motion with <b>Surface only</b>, then <b>No temporal history</b>. Look for trails, delayed edges, and changes in noise.</li>
+                <li>Try <b>Moving object</b> and <b>Occluder</b>. Inspect the magenta object’s trail and newly revealed floor. Use <b>Camera cut</b> to check reset.</li>
+            </ol>
+            <p><b>Spatial denoising</b> smooths neighbouring reflection pixels in three passes. It is on by default and independent of reprojection. Turn it off and select <b>No temporal history</b> to inspect the resolve output; resolve still reuses neighbouring ray hits and filters radiance for roughness.</p>
+            <p>The crosses are geometric guides for object centres, not a pixel-perfect lighting reference. SSR loses information when reflected objects are hidden or off-screen. Surface only retains the new validation and blending fixes; it is not the old shader.</p>
+        </details>
+    </section>
+    <aside>
+        <label><span>Reprojection</span><select id="mode"><option value="0">Parallax</option><option value="1">Surface only</option><option value="2">No temporal history</option><option value="off">SSR off</option></select></label>
+        <label><span>Experiment</span><select id="experiment"><option value="lateral">Lateral camera</option><option value="forward">Forward camera</option><option value="orbit">Orbit camera</option><option value="object">Moving object</option><option value="occluder">Occluder</option><option value="still">Still camera / noise</option><option value="free">Free camera</option></select></label>
+        <label><span>Motion speed <output id="speed-value">1.0×</output></span><input id="speed" aria-label="Motion speed" type="range" min="0.2" max="2" value="1" step="0.1"></label>
+        <label><span>Mirror roughness <output id="roughness-value">0.03</output></span><input id="roughness" aria-label="Mirror roughness" type="range" min="0.01" max="0.7" value="0.03" step="0.01"></label>
+        <label><span>Render resolution</span><select id="resolution"><option value="640">640 × 400</option><option value="960" selected>960 × 600</option><option value="1280">1280 × 800</option></select></label>
+        <label class="check"><input id="guides" type="checkbox" checked>Show geometric guides</label>
+        <label class="check"><input id="denoising" type="checkbox" checked>Spatial denoising</label>
+        <label class="check"><input id="tile-denoising" type="checkbox">Coverage tile denoising</label>
+        <label class="check"><input id="taa" type="checkbox">Final-image TAA</label>
+        <hr>
+        <div class="buttons"><button id="play">Pause motion</button><button id="step">Step frame</button></div>
+        <div class="buttons"><button id="restart">Restart path</button><button id="cut">Camera cut</button></div>
+        <button id="reset">Reset reflection history</button>
+        <hr>
+        <button id="measure">Measure spatial filter</button>
+        <button id="compile">Validate GPU shaders</button>
+        <p id="status" role="status">Starting WebGPU…</p>
+        <small>Fixed exposure. Bloom, sharpening, and motion blur are off. Free camera: drag to orbit, right-drag to pan, wheel to zoom.</small>
+    </aside>
+</main>
+<script type="module" src="./main.js"></script>
+</body>
+</html>