@woosh/meep-engine 3.14.0 → 3.14.2

package/src/shade/playground/ground_seam/main.js

@@ -0,0 +1,879 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { make_grid_texture } from "./make_grid_texture.js";
+import { GROUND_TRIANGULATION, make_ground } from "./make_ground.js";
+import { FramePhase } from "../../renderer/extension/FramePhase.js";
+import { CaptureSceneColor } from "./capture_scene_color.js";
+import { depth_step_across_seam } from "./depth_step_across_seam.js";
+import { attach_measurement, classify_ground, screen_line_distance } from "./measure_flicker.js";
+
+/**
+ * A ground quad that shimmers on one side of its own triangle seam — as a page that can measure it.
+ *
+ * The report this page was built from was written from *outside* the engine, by screenshotting a
+ * demo through CDP, and three of its conclusions had to be retracted: two were stated before they
+ * were measured, and one came from a sign error in a hand-rolled camera basis. So the point of this
+ * page is not to look at the artifact. It is to put every claim about the artifact on a number that
+ * comes out of the renderer's own state:
+ *
+ *  - the picture is read back from a texture this page owns, not scraped off the canvas;
+ *  - the frames are driven from JS, so the burst length is a number chosen here rather than one the
+ *    compositor handed over;
+ *  - pixels are assigned to triangles by unprojecting through `camera.view_projection_matrix` and
+ *    intersecting the ground plane, and the unprojection round-trips itself and reports the error.
+ *
+ * `npm run dev` serves it. HMR is off across the playground by design — an edit anywhere in the
+ * module graph would otherwise reset the temporal accumulation this page exists to measure.
+ */
+
+/**
+ * The camera the artifact was reported at, and which the report says it is sensitive to.
+ *
+ * Distance 45 at 0.9 rad above the horizontal: `45·sin(0.9) = 35.25` up and `45·cos(0.9) = 27.97`
+ * back. Written out as a position rather than as pitch/yaw so it does not depend on which of the
+ * two conventions ("elevation" or "polar angle") a helper happens to mean by *pitch*.
+ */
+const CAMERA = {
+    position: new Vector3(0, 35.25, 27.97),
+    target: new Vector3(0, 0, 0),
+    fov_degrees: 45,
+    near: 0.1,
+    far: 100,
+};
+
+/**
+ * Viewport the report says the seam is clearest at, at a pixel ratio of 1.
+ *
+ * Resolution-dependence is one of its claims, so this is a control rather than the window size.
+ */
+const VIEWPORT = { width: 1258, height: 566 };
+
+/**
+ * @param {number} value
+ * @param {number} [digits]
+ * @returns {string}
+ */
+function fixed(value, digits = 4) {
+    return Number.isFinite(value) ? value.toFixed(digits) : String(value);
+}
+
+export async function start() {
+
+    const element = id => document.getElementById(id);
+
+    const report_element = element('report');
+
+    /**
+     * @param {string} text
+     */
+    function report(text) {
+        report_element.textContent = text;
+        console.log(text);
+    }
+
+    const canvas = element('view');
+    const diff_canvas = element('diff');
+
+    const context = canvas.getContext('webgpu');
+
+    if (context === null) {
+        report('no WebGPU context — this browser has none, or the page is not a secure context');
+        return;
+    }
+
+    const renderer = new Renderer();
+
+    report('acquiring a device…');
+
+    await renderer.initialize({ context, pixelRatio: 1 });
+
+    /*
+     Auto-exposure is the single most important thing to pin. It keeps drifting for seconds after
+     any change, by more than the signal being measured is worth, and a burst taken while it drifts
+     reports the drift rather than the artifact.
+    */
+    renderer.feature_automatic_exposure_enabled = false;
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = CAMERA.near;
+    camera.far = CAMERA.far;
+    camera.fov = CAMERA.fov_degrees * DEG_TO_RAD;
+    camera.transform.position.copy(CAMERA.position);
+    camera.transform.lookAt(CAMERA.target);
+    camera.transform.updateMatrix();
+
+    const scene = new Scene();
+
+    const sun = make_sunlight({
+        intensity: 0.9,
+        direction: new Vector3(0.17, -1, 0.17),
+        temperature: 5500,
+    });
+
+    scene.lights.add(sun);
+
+    /**
+     * Two textures differing only in whether the sampler is granted anisotropy, built up front so
+     * switching between them costs no upload and cannot perturb the temporal history by more than
+     * the swap itself.
+     *
+     * @type {Record<string, ShadeTexture>}
+     */
+    const albedos = {
+        anisotropic: await make_grid_texture(256, true),
+        isotropic: await make_grid_texture(256, false),
+    };
+
+    /** @type {Mesh|undefined} */
+    let ground;
+
+    /**
+     * Swap the ground for one built with different topology. Everything else — the camera, the
+     * light, the texture, the material constants — is untouched, so a difference between two builds
+     * is a difference in how the quad is cut up and nothing else.
+     *
+     * @param {number} segments
+     * @param {string} triangulation key of {@link GROUND_TRIANGULATION}
+     * @param {number} [yaw_degrees] rotation about +Y; 180 swaps the two triangles without moving
+     *      the seam they share
+     * @param {boolean} [anisotropy] whether the sampler is granted 16× anisotropy
+     * @param {number} [extent] edge length of the quad, which is what sets how badly conditioned the
+     *      reconstruction is
+     */
+    function rebuild_ground(segments, triangulation, yaw_degrees = 0, anisotropy = true, extent = 425) {
+        if (ground !== undefined) {
+            scene.remove(ground);
+        }
+
+        ground = make_ground({
+            albedo: albedos[anisotropy ? 'anisotropic' : 'isotropic'],
+            extent,
+            segments,
+            indices: GROUND_TRIANGULATION[triangulation],
+            yaw_degrees,
+        });
+
+        scene.add(ground);
+
+        /*
+         Proof the index buffer actually reached the GPU differently, published so a null result on
+         an index-order A/B cannot be mistaken for 'the reconstruction does not care'. The meshlet
+         builder is free to reorder, and a builder that normalised the order away would make every
+         such test silently vacuous.
+        */
+        globalThis.__meshlet_signature = Array.from(
+            new Uint8Array(ground.geometry.meshlets.data_buffer)
+        ).join(',');
+
+        renderer.indicate_view_change();
+    }
+
+    rebuild_ground(1, 'default');
+
+    const measurement = attach_measurement({ renderer, scene, camera });
+
+    // handy from the console
+    Object.assign(globalThis, { renderer, scene, camera, measurement, classify_ground });
+
+    // ---- controls ---------------------------------------------------------------------------
+
+    let paused = false;
+
+    /**
+     * Edge length of the quad currently in the scene. Held here because the pixel classifier needs
+     * the half-extent to decide what is ground, and a stale value there would silently label the
+     * far half of a big quad as sky.
+     *
+     * @type {number}
+     */
+    let ground_extent = 425;
+
+    function apply_settings() {
+        renderer.feature_taa_enabled = element('taa').checked;
+        renderer.feature_ssao_enabled = element('ssao').checked;
+        renderer.feature_shadows_enabled = element('shadows').checked;
+        renderer.feature_sharpening_enabled = element('sharpening').checked;
+        renderer.feature_automatic_exposure_enabled = element('exposure').checked;
+
+        /*
+         Not a look control. The readback is 8-bit `bgra8unorm` — the display is not HDR — so one
+         code value is 1/255, and a ground sitting at 0.06 luma leaves the whole measurement two
+         code values wide. Lifting the fixed exposure puts the image in the middle of the range the
+         readback can actually resolve, without touching the light, the material or the sampler.
+        */
+        renderer.exposure_compensation = Number(element('exposure_compensation').value);
+
+        VIEWPORT.width = Math.max(2, Number(element('width').value) | 0);
+        VIEWPORT.height = Math.max(2, Number(element('height').value) | 0);
+
+        ground_extent = Number(element('extent').value);
+
+        rebuild_ground(
+            Number(element('segments').value),
+            element('triangulation').value,
+            Number(element('yaw').value),
+            element('anisotropy').checked,
+            ground_extent
+        );
+    }
+
+    element('apply').addEventListener('click', () => {
+        apply_settings();
+        report('applied — the temporal history was dropped, so settle before measuring');
+    });
+
+    /**
+     * Set controls by name and apply them, for driving an A/B from a script rather than by hand.
+     *
+     * The controls are the single source of truth for what the page is configured as — a script
+     * that reached past them and assigned renderer fields directly would leave the panel describing
+     * a state the renderer is not in, and the report is built from the panel.
+     *
+     * @param {Record<string, string|number|boolean>} settings keyed by input id
+     * @returns {Promise<void>}
+     */
+    globalThis.configure = async settings => {
+        for (const [id, value] of Object.entries(settings)) {
+            const input = element(id);
+
+            if (input === null) {
+                throw new Error(`no control named '${id}'`);
+            }
+
+            if (input.type === 'checkbox') {
+                if (input.checked !== Boolean(value)) {
+                    input.checked = Boolean(value);
+                    input.dispatchEvent(new Event('change'));
+                }
+            } else {
+                input.value = String(value);
+            }
+        }
+
+        apply_settings();
+
+        // the environment handler is async and fires off `change`; give it a turn to land
+        await new Promise(resolve => setTimeout(resolve, 0));
+    };
+
+    let environment_loaded = false;
+
+    element('environment').addEventListener('change', async event => {
+        if (event.target.checked) {
+            if (!environment_loaded) {
+                environment_loaded = await load_default_environment(scene);
+            }
+        } else {
+            scene.lights.environment = undefined;
+        }
+
+        renderer.indicate_view_change();
+    });
+
+    // ---- measurement ------------------------------------------------------------------------
+
+    /**
+     * Settle, take a burst, and describe the spread across it — overall, and split by which of the
+     * ground quad's triangles covers each pixel.
+     *
+     * @returns {Promise<object>} also written to `globalThis.__last_measurement`
+     */
+    async function measure() {
+        paused = true;
+
+        const settle_frames = Number(element('settle').value) | 0;
+        const frames = Number(element('frames').value) | 0;
+        const gain = Number(element('gain').value);
+
+        const { spread, mean, width, height } = await measurement.burst({ settle_frames, frames });
+
+        /*
+         The camera's matrices are whatever the last frame left them as, which is what the pixels
+         were drawn with — so the classification is taken from the same state, not recomputed from
+         the authored numbers.
+        */
+        const {
+            side,
+            side_flipped,
+            round_trip_error_px,
+            covered
+        } = classify_ground(camera, width, height, ground_extent * 0.5);
+
+        const triangulation = element('triangulation').value;
+
+        /**
+         * Split the frame by a labelling and describe the spread on each side.
+         *
+         * Both the *absolute* spread and the spread *relative to the local mean* are reported. The
+         * two halves of this view are not equally lit — one is more oblique than the other, so it
+         * is dimmer and more anisotropically filtered whatever the index buffer says — and an
+         * absolute ratio would charge that difference to the artifact. The relative figure is the
+         * one that survives it.
+         *
+         * @param {Int8Array} labels
+         * @returns {object}
+         */
+        function split(labels) {
+            const buckets = {
+                negative: { count: 0, total: 0, relative_total: 0, max: 0, luma_total: 0 },
+                positive: { count: 0, total: 0, relative_total: 0, max: 0, luma_total: 0 },
+                sky: { count: 0, total: 0, relative_total: 0, max: 0, luma_total: 0 },
+            };
+
+            for (let p = 0; p < labels.length; p++) {
+                const bucket = labels[p] === 0
+                    ? buckets.sky
+                    : (labels[p] < 0 ? buckets.negative : buckets.positive);
+
+                bucket.count++;
+                bucket.total += spread[p];
+                bucket.luma_total += mean[p];
+
+                // guard against a pixel that is exactly black, where the ratio is meaningless
+                if (mean[p] > 1e-4) {
+                    bucket.relative_total += spread[p] / mean[p];
+                }
+
+                if (spread[p] > bucket.max) {
+                    bucket.max = spread[p];
+                }
+            }
+
+            for (const bucket of Object.values(buckets)) {
+                bucket.mean = bucket.count > 0 ? bucket.total / bucket.count : 0;
+                bucket.relative = bucket.count > 0 ? bucket.relative_total / bucket.count : 0;
+                bucket.mean_luma = bucket.count > 0 ? bucket.luma_total / bucket.count : 0;
+            }
+
+            const { negative, positive } = buckets;
+
+            return {
+                negative,
+                positive,
+                sky: buckets.sky,
+                ratio: negative.mean > 0 && positive.mean > 0
+                    ? Math.max(negative.mean, positive.mean) / Math.min(negative.mean, positive.mean)
+                    : null,
+                relative_ratio: negative.relative > 0 && positive.relative > 0
+                    ? Math.max(negative.relative, positive.relative)
+                    / Math.min(negative.relative, positive.relative)
+                    : null,
+            };
+        }
+
+        /*
+         Both diagonals, always. The claim under test is that the instability is bound to the index
+         buffer, so the interesting comparison is between the split along the diagonal that *is* in
+         the mesh and the split along the one that is not — the second is a control cut through the
+         same picture, and if it shows the same asymmetry then the asymmetry is about the view, not
+         about the triangulation.
+        */
+        const along_default = split(side);
+        const along_flipped = split(side_flipped);
+
+        const stats = triangulation === 'flipped' ? along_flipped : along_default;
+
+        // ---- the difference map
+
+        diff_canvas.width = width;
+        diff_canvas.height = height;
+
+        const ctx = diff_canvas.getContext('2d');
+        const image = ctx.createImageData(width, height);
+
+        for (let p = 0; p < spread.length; p++) {
+            const v = Math.min(255, Math.round(spread[p] * gain * 255));
+
+            const i = p * 4;
+
+            image.data[i] = v;
+            image.data[i + 1] = v;
+            image.data[i + 2] = v;
+            image.data[i + 3] = 255;
+        }
+
+        ctx.putImageData(image, 0, 0);
+
+        const result = {
+            viewport: [width, height],
+            internal_resolution_scale: renderer.internal_resolution_scale,
+            segments: Number(element('segments').value),
+            triangulation,
+            taa: renderer.feature_taa_enabled,
+            settle_frames,
+            frames,
+            round_trip_error_px,
+            ground_pixels: covered,
+            stats,
+            along_default,
+            along_flipped,
+            ratio: stats.ratio,
+            relative_ratio: stats.relative_ratio,
+        };
+
+        globalThis.__last_measurement = result;
+
+        /*
+         The raw fields, kept off the summary object so a script can do its own analysis — a profile
+         across the seam, a different labelling, a histogram — without the page having to anticipate
+         it. Summaries are where a real structure goes to hide: two halves that differ by 2× in the
+         mean can be a step at the seam or a smooth gradient, and only the field tells you which.
+        */
+        globalThis.__last_fields = { spread, mean, side, side_flipped, width, height };
+
+        /*
+         The profile is what separates "a seam" from "one half of the frame is more oblique than the
+         other". A half-plane mean reports the same 2× either way; a step at ±1 px does not.
+        */
+        result.profile = {
+            'x = -z': profile_across([1, -1] /* world direction of the default seam */),
+            'x = +z': profile_across([1, 1]),
+        };
+
+        /**
+         * Mean spread and mean relative spread in 1-pixel bands of signed screen distance from a
+         * world line on the ground plane.
+         *
+         * @param {number[]} direction the line's XZ direction
+         * @returns {object}
+         */
+        function profile_across(direction) {
+            const distance = screen_line_distance(camera, width, height, direction);
+
+            const RANGE = 40;
+
+            const bins = new Float64Array(2 * RANGE);
+            const bins_relative = new Float64Array(2 * RANGE);
+            const counts = new Float64Array(2 * RANGE);
+
+            for (let py = 0; py < height; py++) {
+                for (let px = 0; px < width; px++) {
+                    const d = distance(px, py);
+
+                    const bin = Math.floor(d) + RANGE;
+
+                    if (bin < 0 || bin >= bins.length) {
+                        continue;
+                    }
+
+                    const p = py * width + px;
+
+                    bins[bin] += spread[p];
+
+                    if (mean[p] > 1e-4) {
+                        bins_relative[bin] += spread[p] / mean[p];
+                    }
+
+                    counts[bin]++;
+                }
+            }
+
+            const relative = [];
+
+            for (let i = 0; i < bins.length; i++) {
+                relative.push(counts[i] > 0 ? bins_relative[i] / counts[i] : null);
+            }
+
+            return { offset: -RANGE, relative, counts: Array.from(counts) };
+        }
+
+        report([
+            `viewport             ${width} × ${height}`,
+            `ground pixels        ${covered}`,
+            `unproject round-trip ${fixed(round_trip_error_px, 5)} px  (must be ≪ 1)`,
+            `segments             ${result.segments}   triangulation ${triangulation}`,
+            `TAA                  ${result.taa}`,
+            ``,
+            `spread, side −       ${fixed(stats.negative.mean, 6)}  rel ${fixed(stats.negative.relative, 5)}  luma ${fixed(stats.negative.mean_luma, 4)}`,
+            `spread, side +       ${fixed(stats.positive.mean, 6)}  rel ${fixed(stats.positive.relative, 5)}  luma ${fixed(stats.positive.mean_luma, 4)}`,
+            `spread, sky          ${fixed(stats.sky.mean, 6)}   (n=${stats.sky.count})`,
+            ``,
+            `asymmetry, x = −z    ${along_default.relative_ratio === null ? 'n/a' : fixed(along_default.relative_ratio, 3)}  (absolute ${fixed(along_default.ratio, 3)})`,
+            `asymmetry, x = +z    ${along_flipped.relative_ratio === null ? 'n/a' : fixed(along_flipped.relative_ratio, 3)}  (absolute ${fixed(along_flipped.ratio, 3)})`,
+        ].join('\n'));
+
+        paused = false;
+
+        return result;
+    }
+
+    /**
+     * Read the depth buffer and ask whether the two triangles' planes agree along the edge they
+     * share, and whether the depth a pixel is written with is stable frame to frame.
+     *
+     * Both halves matter and they answer different questions. A *step* at the seam would mean the
+     * rasterizer interpolated the shared edge two different ways, which is what the brief's
+     * candidate chain needs in order to start. *Instability* across frames is what a depth-driven
+     * history rejection would actually be reacting to — and with the camera still, the only thing
+     * that moves a pixel's depth is the sub-pixel jitter, so the two triangles should wobble by the
+     * same amount unless something about them differs.
+     *
+     * @param {number} [frames] how many frames of depth to compare
+     * @returns {Promise<object>}
+     */
+    async function probe_depth(frames = 16) {
+        paused = true;
+
+        await measurement.settle(Number(element('settle').value) | 0);
+
+        const first = await measurement.read_depth();
+
+        const { width, height } = first;
+
+        const { side, side_flipped } = classify_ground(camera, width, height, ground_extent * 0.5);
+
+        const triangulation = element('triangulation').value;
+        const labels = triangulation === 'flipped' ? side_flipped : side;
+
+        const distance = screen_line_distance(
+            camera, width, height,
+            triangulation === 'flipped' ? [1, 1] : [1, -1]
+        );
+
+        const step = depth_step_across_seam(first.depth, labels, distance, width, height);
+
+        // per-pixel spread of depth across a burst, split the same way the colour spread is
+        const min = Float32Array.from(first.depth);
+        const max = Float32Array.from(first.depth);
+
+        for (let i = 1; i < frames; i++) {
+            measurement.frame();
+
+            const { depth } = await measurement.read_depth();
+
+            for (let p = 0; p < depth.length; p++) {
+                if (depth[p] < min[p]) {
+                    min[p] = depth[p];
+                }
+
+                if (depth[p] > max[p]) {
+                    max[p] = depth[p];
+                }
+            }
+        }
+
+        const wobble = { negative: 0, positive: 0 };
+        const counts = { negative: 0, positive: 0 };
+
+        for (let p = 0; p < min.length; p++) {
+            if (labels[p] === 0) {
+                continue;
+            }
+
+            const bucket = labels[p] < 0 ? 'negative' : 'positive';
+
+            // relative to the depth itself: an absolute wobble means nothing without the magnitude
+            // it sits on, and depth here runs over two orders of magnitude across the frame
+            if (max[p] > 0) {
+                wobble[bucket] += (max[p] - min[p]) / max[p];
+                counts[bucket]++;
+            }
+        }
+
+        const result = {
+            resolution: [width, height],
+            triangulation,
+            segments: Number(element('segments').value),
+            depth_range: [Math.min(...first.depth.subarray(0, 4096)), Math.max(...first.depth.subarray(0, 4096))],
+            step,
+            depth_wobble: {
+                negative: counts.negative > 0 ? wobble.negative / counts.negative : 0,
+                positive: counts.positive > 0 ? wobble.positive / counts.positive : 0,
+            },
+        };
+
+        globalThis.__last_depth = result;
+
+        paused = false;
+
+        return result;
+    }
+
+    globalThis.probe_depth = probe_depth;
+
+    /**
+     * Two captures of the same record at two phases: the temporal filter's input and its output.
+     *
+     * Registered separately rather than re-phased in place — the registry resolves ordering at
+     * registration, so a phase assigned afterwards would be ignored.
+     *
+     * @type {Record<string, CaptureSceneColor>}
+     */
+    const captures = {
+        pre_taa: new CaptureSceneColor(renderer.device),
+        post_taa: new CaptureSceneColor(renderer.device),
+    };
+
+    captures.pre_taa.name = 'ground_seam/capture pre-TAA';
+    captures.pre_taa.phase = FramePhase.AfterTransparency;
+
+    captures.post_taa.name = 'ground_seam/capture post-TAA';
+    captures.post_taa.phase = FramePhase.BeforePresent;
+
+    renderer.add_extension(captures.pre_taa);
+    renderer.add_extension(captures.post_taa);
+
+    const capture_scene_color = captures.pre_taa;
+
+    /**
+     * The same burst measurement, taken on the temporal filter's **input** instead of its output.
+     *
+     * This is the experiment that splits the seam in two. If the pre-TAA frame already differs
+     * across the edge — one triangle's shading swinging more from jitter phase to jitter phase than
+     * the other's — then the fault is in what the material pass reconstructs per triangle, and TAA
+     * is only making a real difference visible. If the pre-TAA variation is flat across the edge
+     * and the post-TAA one is not, the shading agrees and the temporal filter is treating the two
+     * triangles differently.
+     *
+     * The capture is HDR and linear, upstream of the tonemap, so there is no 8-bit floor under it
+     * the way there is under the colour readback.
+     *
+     * @param {number} [frames]
+     * @returns {Promise<object>}
+     */
+    async function probe_pre_taa(frames = 16, stage = 'pre_taa') {
+        paused = true;
+
+        const capture_scene_color = captures[stage];
+
+        capture_scene_color.enabled = true;
+
+        try {
+            await measurement.settle(Number(element('settle').value) | 0);
+
+            const first = await capture_scene_color.read_luminance();
+
+            const { width, height } = first;
+
+            const min = Float32Array.from(first.luma);
+            const max = Float32Array.from(first.luma);
+            const total = Float64Array.from(first.luma);
+
+            /*
+             Total variation along the burst — the sum of the absolute frame-to-frame steps. A range
+             cannot tell a value that sweeps once from one that alternates every frame, and those
+             two defeat a neighbourhood clamp very differently: the clamp rebuilds its box from the
+             current frame, so a value that jumps to the far end each frame keeps the history outside
+             the box while a slow sweep never does. Divided by the range it is 1 for a single sweep
+             and (frames − 1) for a full alternation.
+            */
+            const variation = new Float64Array(first.luma.length);
+
+            let previous = Float32Array.from(first.luma);
+
+            for (let i = 1; i < frames; i++) {
+                measurement.frame();
+
+                const { luma } = await capture_scene_color.read_luminance();
+
+                for (let p = 0; p < luma.length; p++) {
+                    if (luma[p] < min[p]) {
+                        min[p] = luma[p];
+                    }
+
+                    if (luma[p] > max[p]) {
+                        max[p] = luma[p];
+                    }
+
+                    total[p] += luma[p];
+                    variation[p] += Math.abs(luma[p] - previous[p]);
+                }
+
+                previous = luma;
+            }
+
+            const { side, side_flipped } = classify_ground(camera, width, height, ground_extent * 0.5);
+
+            const triangulation = element('triangulation').value;
+            const labels = triangulation === 'flipped' ? side_flipped : side;
+
+            const distance = screen_line_distance(
+                camera, width, height,
+                triangulation === 'flipped' ? [1, 1] : [1, -1]
+            );
+
+            /*
+             The 3×3 standard deviation of the *last* frame captured, which is the quantity TAA's
+             neighbourhood box is built from: `taa_history_color_bounding_box_YCoCg` takes the mean
+             and σ over exactly this footprint and clips the history to `mean ± γ·σ`. How hard the
+             history gets clipped — and therefore how much of the jittering current frame is let
+             through — is the ratio of the frame-to-frame swing to that σ, so it is measured beside
+             it rather than left to be inferred.
+            */
+            const { luma: last } = await capture_scene_color.read_luminance();
+
+            const sigma = new Float32Array(width * height);
+
+            for (let py = 1; py < height - 1; py++) {
+                for (let px = 1; px < width - 1; px++) {
+                    let m1 = 0;
+                    let m2 = 0;
+
+                    for (let dy = -1; dy <= 1; dy++) {
+                        for (let dx = -1; dx <= 1; dx++) {
+                            const v = last[(py + dy) * width + px + dx];
+
+                            m1 += v;
+                            m2 += v * v;
+                        }
+                    }
+
+                    m1 /= 9;
+                    m2 /= 9;
+
+                    sigma[py * width + px] = Math.sqrt(Math.max(0, m2 - m1 * m1));
+                }
+            }
+
+            const buckets = {
+                negative: { relative: 0, count: 0, luma: 0, sigma: 0, jaggedness: 0 },
+                positive: { relative: 0, count: 0, luma: 0, sigma: 0, jaggedness: 0 },
+            };
+
+            const RANGE = 20;
+
+            const band_total = new Float64Array(2 * RANGE);
+            const band_sigma = new Float64Array(2 * RANGE);
+            const band_jagged = new Float64Array(2 * RANGE);
+            const band_count = new Float64Array(2 * RANGE);
+
+            for (let py = 1; py < height - 1; py++) {
+                for (let px = 1; px < width - 1; px++) {
+                    const p = py * width + px;
+
+                    if (labels[p] === 0) {
+                        continue;
+                    }
+
+                    const m = total[p] / frames;
+
+                    if (!(m > 1e-6)) {
+                        continue;
+                    }
+
+                    const swing = max[p] - min[p];
+                    const relative = swing / m;
+                    const relative_sigma = sigma[p] / m;
+
+                    /*
+                     How many times the value crosses its own range over the burst. 1 is a single
+                     sweep, `frames − 1` is a full alternation every frame. This is the shape a
+                     range cannot see and the one a neighbourhood clamp cares about most.
+                    */
+                    const jaggedness = swing > 1e-9 ? variation[p] / swing : 0;
+
+                    const bucket = labels[p] < 0 ? buckets.negative : buckets.positive;
+
+                    bucket.relative += relative;
+                    bucket.luma += m;
+                    bucket.sigma += relative_sigma;
+                    bucket.jaggedness += jaggedness;
+                    bucket.count++;
+
+                    const bin = Math.floor(distance(px, py)) + RANGE;
+
+                    if (bin >= 0 && bin < band_total.length) {
+                        band_total[bin] += relative;
+                        band_sigma[bin] += relative_sigma;
+                        band_jagged[bin] += jaggedness;
+                        band_count[bin]++;
+                    }
+                }
+            }
+
+            for (const bucket of Object.values(buckets)) {
+                bucket.mean_relative = bucket.count > 0 ? bucket.relative / bucket.count : 0;
+                bucket.mean_luma = bucket.count > 0 ? bucket.luma / bucket.count : 0;
+                bucket.mean_sigma = bucket.count > 0 ? bucket.sigma / bucket.count : 0;
+                bucket.mean_jaggedness = bucket.count > 0 ? bucket.jaggedness / bucket.count : 0;
+            }
+
+            const profile = [];
+            const profile_sigma = [];
+            const profile_jagged = [];
+
+            for (let i = 0; i < band_total.length; i++) {
+                profile.push(band_count[i] > 0 ? band_total[i] / band_count[i] : null);
+                profile_sigma.push(band_count[i] > 0 ? band_sigma[i] / band_count[i] : null);
+                profile_jagged.push(band_count[i] > 0 ? band_jagged[i] / band_count[i] : null);
+            }
+
+            const result = {
+                resolution: [width, height],
+                stage,
+                triangulation,
+                segments: Number(element('segments').value),
+                frames,
+                negative: buckets.negative,
+                positive: buckets.positive,
+                ratio: buckets.positive.mean_relative > 0
+                    ? buckets.negative.mean_relative / buckets.positive.mean_relative
+                    : null,
+                sigma_ratio: buckets.positive.mean_sigma > 0
+                    ? buckets.negative.mean_sigma / buckets.positive.mean_sigma
+                    : null,
+                jaggedness_ratio: buckets.positive.mean_jaggedness > 0
+                    ? buckets.negative.mean_jaggedness / buckets.positive.mean_jaggedness
+                    : null,
+                profile: {
+                    offset: -RANGE,
+                    relative: profile,
+                    sigma: profile_sigma,
+                    jaggedness: profile_jagged,
+                },
+            };
+
+            globalThis.__last_pre_taa = result;
+
+            return result;
+        } finally {
+            capture_scene_color.enabled = false;
+            paused = false;
+        }
+    }
+
+    globalThis.probe_pre_taa = probe_pre_taa;
+
+    element('measure').addEventListener('click', () => {
+        element('measure').disabled = true;
+
+        measure()
+            .catch(error => {
+                report(String(error?.stack ?? error));
+            })
+            .finally(() => {
+                element('measure').disabled = false;
+            });
+    });
+
+    globalThis.measure = measure;
+
+    // ---- frame loop -------------------------------------------------------------------------
+
+    apply_settings();
+
+    create_frame_loop(time_delta_s => {
+        if (paused) {
+            return;
+        }
+
+        renderer.pixel_ratio = 1;
+        renderer.resize(VIEWPORT.width, VIEWPORT.height);
+
+        canvas.style.width = `${VIEWPORT.width}px`;
+        canvas.style.height = `${VIEWPORT.height}px`;
+
+        camera.aspect = VIEWPORT.width / VIEWPORT.height;
+
+        renderer.render(camera, scene, time_delta_s);
+    });
+
+    report('ready — press Measure');
+}