@woosh/meep-engine 3.14.0 → 3.14.2

package/src/shade/device/timing/profile/frame_graph_extract_topology.js

@@ -1,174 +1,164 @@
-import { assert } from "../../../../core/assert.js";
-import { gpu_texture_format_info } from "../../../descriptor/texture/format/gpu_texture_format_info.js";
-import {
-    GPUProfilePass,
-    GPUProfileResource,
-    GPUProfileResourceKind,
-    GPUProfileScope,
-    GPUProfileTopology
-} from "./GPUProfileTopology.js";
-
-/**
- * Declared bytes for a texture descriptor: the whole mip chain, at the given sample count.
- *
- * A format the engine's table does not know reports 0 rather than throwing. A capture is a
- * diagnostic; refusing to record one because a size could not be worked out would be the wrong
- * trade every time.
- *
- * @param {TextureResourceDescriptor} descriptor
- * @returns {number}
- */
-function texture_byte_size(descriptor) {
-    let info;
-
-    try {
-        info = gpu_texture_format_info(descriptor.format);
-    } catch {
-        // `gpu_texture_format_info` throws on a name it does not know. Correct for the renderer,
-        // wrong here: a capture is a diagnostic, and losing the whole recording because one
-        // resource used a format the table has not caught up with is the wrong trade every time.
-        return 0;
-    }
-
-    const { block_width, block_height, bytes_per_block } = info;
-
-    let total = 0;
-
-    for (let mip = 0; mip < descriptor.mipLevelCount; mip++) {
-        const w = Math.max(1, Math.floor(descriptor.resolution[0]) >> mip);
-        const h = Math.max(1, Math.floor(descriptor.resolution[1]) >> mip);
-        const d = Math.max(1, Math.floor(descriptor.resolution[2]) >> mip);
-
-        total += Math.ceil(w / block_width) * Math.ceil(h / block_height) * d * bytes_per_block;
-    }
-
-    return total * descriptor.sampleCount;
-}
-
-/**
- * Record the shape of a compiled frame graph.
- *
- * **Call after `compile`, and ideally after `execute`.** Reference counts and cull decisions are
- * what `compile` derives; before it every pass reads as culled, which would be recorded as a frame
- * in which nothing ran.
- *
- * Resources are keyed by **node**, one per version, matching `FrameGraph.exportToJson`. Passes
- * record the node they touched rather than the underlying resource, so a registry-keyed model would
- * leave every reference past version 0 pointing at nothing.
- *
- * @param {FrameGraph} graph
- * @returns {GPUProfileTopology}
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function frame_graph_extract_topology(graph) {
-    assert.defined(graph, 'graph');
-
-    const topology = new GPUProfileTopology();
-
-    topology.name = graph.name;
-
-    /**
-     * Scopes are reached through the nodes that were recorded inside them, and flattened to an
-     * array here. `FrameGraph` keeps them as a parent chain rather than a list, so this walk is
-     * what turns the chain into something a reader can index.
-     *
-     * @type {Map<FrameGraphScope, number>}
-     */
-    const scope_ids = new Map();
-
-    /**
-     * @param {FrameGraphScope|null} scope
-     * @returns {number} index, or -1
-     */
-    function intern_scope(scope) {
-        if (scope === null || scope === undefined) {
-            return -1;
-        }
-
-        const existing = scope_ids.get(scope);
-
-        if (existing !== undefined) {
-            return existing;
-        }
-
-        // parent first, so a parent always has a lower index than its children and a reader can
-        // resolve the chain in one forward pass
-        const parent = intern_scope(scope.parent);
-
-        const record = new GPUProfileScope();
-
-        record.name = scope.name;
-        record.parent = parent;
-
-        const id = topology.scopes.length;
-
-        topology.scopes.push(record);
-        scope_ids.set(scope, id);
-
-        return id;
-    }
-
-    for (const node of graph.__pass_nodes) {
-        const pass = new GPUProfilePass();
-
-        pass.id = node.id;
-        pass.name = node.name;
-        pass.scope = intern_scope(node.scope);
-        pass.culled = !node.can_execute();
-        pass.has_side_effects = node.has_side_effects;
-        pass.ref_count = node.ref_count;
-        pass.reads = node.resource_reads.slice();
-        pass.writes = node.resource_writes.slice();
-        pass.creates = node.resource_creates.slice();
-
-        topology.passes.push(pass);
-    }
-
-    for (const node of graph.__resource_nodes) {
-        const entry = graph.__resource_registry[node.resource_id];
-
-        const resource = new GPUProfileResource();
-
-        resource.id = node.id;
-        resource.name = node.name;
-        resource.version = node.version;
-        resource.producer = node.producer !== null ? node.producer.id : -1;
-
-        if (entry !== undefined) {
-            resource.transient = entry.isTransient();
-            resource.imported = entry.isImported();
-        }
-
-        const descriptor = entry?.resource_descriptor;
-
-        if (descriptor !== undefined && descriptor !== null) {
-            const type = descriptor.type;
-
-            if (type === 'buffer') {
-                resource.kind = GPUProfileResourceKind.BUFFER;
-                resource.size = descriptor.size;
-                resource.usage = descriptor.usage;
-                resource.byte_size = descriptor.size;
-            } else if (type === 'texture') {
-                resource.kind = GPUProfileResourceKind.TEXTURE;
-                resource.resolution = [
-                    Math.floor(descriptor.resolution[0]),
-                    Math.floor(descriptor.resolution[1]),
-                    Math.floor(descriptor.resolution[2])
-                ];
-                resource.mip_level_count = descriptor.mipLevelCount;
-                resource.sample_count = descriptor.sampleCount;
-                resource.format = descriptor.format;
-                resource.dimension = descriptor.dimension;
-                resource.usage = descriptor.usage;
-                resource.byte_size = texture_byte_size(descriptor);
-            }
-        }
-
-        topology.resources.push(resource);
-    }
-
-    return topology;
-}
+import { assert } from "../../../../core/assert.js";
+import { gpu_texture_format_memory_footprint } from "../../../descriptor/texture/format/gpu_texture_format_info.js";
+import {
+    GPUProfilePass,
+    GPUProfileResource,
+    GPUProfileResourceKind,
+    GPUProfileScope,
+    GPUProfileTopology
+} from "./GPUProfileTopology.js";
+
+/**
+ * Declared bytes for a texture descriptor: the whole mip chain, at the given sample count.
+ *
+ * A format the engine's table does not know reports 0 rather than throwing. A capture is a
+ * diagnostic; refusing to record one because a size could not be worked out would be the wrong
+ * trade every time.
+ *
+ * @param {TextureResourceDescriptor} descriptor
+ * @returns {number}
+ */
+function texture_byte_size(descriptor) {
+    try {
+        return gpu_texture_format_memory_footprint(
+            descriptor.format,
+            descriptor.resolution,
+            descriptor.dimension,
+            descriptor.mipLevelCount,
+            descriptor.sampleCount
+        );
+    } catch {
+        // `gpu_texture_format_info` throws on a name it does not know. Correct for the renderer,
+        // wrong here: a capture is a diagnostic, and losing the whole recording because one
+        // resource used a format the table has not caught up with is the wrong trade every time.
+        return 0;
+    }
+}
+
+/**
+ * Record the shape of a compiled frame graph.
+ *
+ * **Call after `compile`, and ideally after `execute`.** Reference counts and cull decisions are
+ * what `compile` derives; before it every pass reads as culled, which would be recorded as a frame
+ * in which nothing ran.
+ *
+ * Resources are keyed by **node**, one per version, matching `FrameGraph.exportToJson`. Passes
+ * record the node they touched rather than the underlying resource, so a registry-keyed model would
+ * leave every reference past version 0 pointing at nothing.
+ *
+ * @param {FrameGraph} graph
+ * @returns {GPUProfileTopology}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function frame_graph_extract_topology(graph) {
+    assert.defined(graph, 'graph');
+
+    const topology = new GPUProfileTopology();
+
+    topology.name = graph.name;
+
+    /**
+     * Scopes are reached through the nodes that were recorded inside them, and flattened to an
+     * array here. `FrameGraph` keeps them as a parent chain rather than a list, so this walk is
+     * what turns the chain into something a reader can index.
+     *
+     * @type {Map<FrameGraphScope, number>}
+     */
+    const scope_ids = new Map();
+
+    /**
+     * @param {FrameGraphScope|null} scope
+     * @returns {number} index, or -1
+     */
+    function intern_scope(scope) {
+        if (scope === null || scope === undefined) {
+            return -1;
+        }
+
+        const existing = scope_ids.get(scope);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        // parent first, so a parent always has a lower index than its children and a reader can
+        // resolve the chain in one forward pass
+        const parent = intern_scope(scope.parent);
+
+        const record = new GPUProfileScope();
+
+        record.name = scope.name;
+        record.parent = parent;
+
+        const id = topology.scopes.length;
+
+        topology.scopes.push(record);
+        scope_ids.set(scope, id);
+
+        return id;
+    }
+
+    for (const node of graph.__pass_nodes) {
+        const pass = new GPUProfilePass();
+
+        pass.id = node.id;
+        pass.name = node.name;
+        pass.scope = intern_scope(node.scope);
+        pass.culled = !node.can_execute();
+        pass.has_side_effects = node.has_side_effects;
+        pass.ref_count = node.ref_count;
+        pass.reads = node.resource_reads.slice();
+        pass.writes = node.resource_writes.slice();
+        pass.creates = node.resource_creates.slice();
+
+        topology.passes.push(pass);
+    }
+
+    for (const node of graph.__resource_nodes) {
+        const entry = graph.__resource_registry[node.resource_id];
+
+        const resource = new GPUProfileResource();
+
+        resource.id = node.id;
+        resource.name = node.name;
+        resource.version = node.version;
+        resource.producer = node.producer !== null ? node.producer.id : -1;
+
+        if (entry !== undefined) {
+            resource.transient = entry.isTransient();
+            resource.imported = entry.isImported();
+        }
+
+        const descriptor = entry?.resource_descriptor;
+
+        if (descriptor !== undefined && descriptor !== null) {
+            const type = descriptor.type;
+
+            if (type === 'buffer') {
+                resource.kind = GPUProfileResourceKind.BUFFER;
+                resource.size = descriptor.size;
+                resource.usage = descriptor.usage;
+                resource.byte_size = descriptor.size;
+            } else if (type === 'texture') {
+                resource.kind = GPUProfileResourceKind.TEXTURE;
+                resource.resolution = [
+                    Math.floor(descriptor.resolution[0]),
+                    Math.floor(descriptor.resolution[1]),
+                    Math.floor(descriptor.resolution[2])
+                ];
+                resource.mip_level_count = descriptor.mipLevelCount;
+                resource.sample_count = descriptor.sampleCount;
+                resource.format = descriptor.format;
+                resource.dimension = descriptor.dimension;
+                resource.usage = descriptor.usage;
+                resource.byte_size = texture_byte_size(descriptor);
+            }
+        }
+
+        topology.resources.push(resource);
+    }
+
+    return topology;
+}

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

@@ -0,0 +1,235 @@
+# ground seam
+
+A 425×425 ground quad, two triangles, a tiling grid albedo, a still camera. Under TAA the half of
+the quad on one side of the triangles' shared edge boils at texel granularity and the other half is
+clean, with a hard straight seam between them. It is invisible in a still frame and only exists in a
+multi-frame difference.
+
+`npm run dev`, then `/src/shade/playground/ground_seam/`. HMR is off across the playground by
+design — a reload drops the temporal accumulation this page exists to measure.
+
+## What it does differently from looking at the screen
+
+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 stated before they were
+measured, one from a sign error in a hand-rolled camera basis. So nothing here is read off a
+picture:
+
+- **Frames are read back from a texture the page owns.** A canvas texture cannot carry `COPY_SRC`
+  and is rotated away the moment it is presented; a `drawImage` off it a task later returns an empty
+  bitmap, and a comparison of two blanks reports perfect agreement. `Renderer.render_to_target`
+  shares the view context, so the history being measured is the history the on-screen path builds.
+- **Frames are driven from JS**, so the burst length is a number chosen here rather than one the
+  compositor handed over. The jitter sequence is 16 phases at scale 1, and the default burst is 16.
+- **Pixels are assigned to triangles, not to a fitted line.** Each pixel is unprojected through
+  `camera.view_projection_matrix`, intersected with the ground plane and labelled by the sign of
+  `x + z` — the shared edge, derived from the index buffer. The unprojection round-trips itself and
+  reports the error, which runs about `4e-11` px.
+- **Both diagonals are always reported.** The one in the mesh and the one that is not, so a whole-
+  frame asymmetry caused by the view cannot be mistaken for a seam.
+- **Profiles, not half-plane means.** A mean over each half reports the same number for a step at
+  the boundary and for a smooth gradient across the frame, and those are different findings.
+
+Pin `feature_automatic_exposure_enabled = false` before measuring anything — it drifts for seconds
+after any change, by more than the signal is worth. The page does this at startup. And check the
+frame is not black before believing a stability win; a black frame is perfectly stable.
+
+## What it found
+
+Reproduced at 1258×566, pixel ratio 1. Profiling the relative luminance spread across a 16-frame
+burst against screen distance from the shared edge gives a step from 0.046 to 0.022 centred on the
+edge, over about four pixels. The control cut along the *other* diagonal, through the same picture,
+is flat.
+
+**The rasterizer is not the source.** For a planar surface under reverse-Z with an infinite far
+plane the written depth is exactly affine in screen space, so each triangle's depth was fitted
+separately by least squares and the two fits evaluated on the shared edge. Residuals `6e-11`, and
+the two planes disagree by **0.23 ULP of f32** at worst. There is no depth step.
+
+**The disocclusion chain the report suspected does not exist.** `shader_depth_occlusion_clip`'s
+confidence is **exactly 1.0 at every pixel**, both sides. Velocity is ~`1e-5` px and flat.
+
+**TAA creates the step out of continuous inputs.** Captured at `AfterTransparency` — the exact
+texture the resolve reads — the incoming colour's per-pixel swing is 0.371 vs 0.366 across the edge
+and flat in profile. Captured at `BeforePresent` it is 0.046 vs 0.022 with a hard step. And it is
+not a blend-weight difference: re-running the resolve's own arithmetic with its own chunks gives
+blend 0.0222 vs 0.0248 — nearly equal, and *lower* on the noisy side. What moves is the clipped
+history. (That probe is no longer here; see "The two probes that are gone".)
+
+**The incoming colour does differ per triangle — in temporal shape, not amplitude.** Total variation
+along the burst divided by its range ("jaggedness": 1 for a single sweep, 15 for a full alternation)
+steps from **7.28 to 5.32 in a single pixel** at the edge, while the range itself is flat to 1.5%. A
+neighbourhood-clamped filter rebuilds its box from the current frame every frame, so a value that
+jumps to the far end of its range each frame keeps the history at the box boundary and never
+settles, while a value that sweeps smoothly converges.
+
+**The source is `chunk_barycentric_full`'s anchor.** The decisive control is
+`GROUND_TRIANGULATION.rotated`: the same two triangles, same diagonal, same winding, same three
+vertices per face, same UVs, same coverage, same depth — each index triple cyclically rotated so a
+different corner is first. Nothing geometric changes. The reconstruction anchors every pixel on
+`pixel - ndc0` and divides by `determinant(mat2x2(ndc2 - ndc1, ndc0 - ndc1))`, so vertex 0 is the
+origin the whole thing is measured from, and in f32 the rotation changes which differences are
+formed and how they round.
+
+| 1258×566 | jaggedness − / + | ratio | post-TAA spread − / + | ratio |
+|---|---|---|---|---|
+| default `(0,2,1) (2,3,1)` | 7.28 / 5.32 | 1.37 | 0.0458 / 0.0218 | **2.11** |
+| anchor-rotated `(2,1,0) (3,1,2)` | 4.33 / 4.36 | 0.99 | 0.0139 / 0.0149 | **0.94** |
+
+`globalThis.__meshlet_signature` is published on every rebuild so a null result on an index-order
+A/B cannot be mistaken for "the reconstruction does not care" — the two builds' meshlet data
+differ, so the change reached the GPU.
+
+This also accounts for the rest: subdividing fixes it because each small triangle's anchor is near
+its own pixels; flipping the diagonal changes each triangle's vertex set and so its conditioning;
+it is TAA-specific because a static ~`1e-4` bias is invisible until jitter turns it into a temporal
+signal; and it is resolution-dependent because the NDC magnitudes and the pixel footprint both are.
+
+## The fix
+
+`chunk_barycentric_full` was rewritten to solve the same system without an anchor and without ever
+dividing by w. A point with barycentric `l` sits at screen position
+`sum(l_i * P_i.xy) / sum(l_i * P_i.w)`; setting that equal to the pixel and adding `sum(l) == 1`
+gives a 3×3 system whose Cramer solution is three 2×2 determinants of `u = x - pixel.x*w` and
+`v = y - pixel.y*w`, normalised by their sum. Each `l_i` is the same expression in the other two, so
+rotating the corners permutes the outputs and changes nothing else. The derivatives are the same
+system solved at `pixel + (1,0)` and `pixel + (0,1)` — exactly the whole-pixel forward difference
+the old code produced by algebra, reusing every input.
+
+Measured here, 1258×566, per-pixel relative luminance spread over a 16-frame burst:
+
+| | before | after |
+|---|---|---|
+| default `(0,2,1) (2,3,1)` | 0.0458 / 0.0218 — **2.11** | 0.0153 / 0.0127 — **1.21** |
+| anchor-rotated | 0.0139 / 0.0149 — 0.94 | 0.0154 / 0.0121 — 1.27 |
+| flipped diagonal | 0.0382 / 0.0322 — 1.19 | 0.0120 / 0.0156 — 0.77 |
+| 8×8 subdivided | 0.0185 / 0.0164 — 1.13 | 0.0154 / 0.0127 — 1.21 |
+| 1898×926 anchor-rotated | 0.0216 / 0.0062 — **3.49** | 0.0105 / 0.0076 — 1.38 |
+| 640×360 default | 0.0218 / 0.0534 — **0.41** | 0.0216 / 0.0208 — 1.04 |
+
+Repeated three times from a fresh page, the first row reads 1.205 / 1.206 / 1.206 — so the change
+from 2.11 is some three orders of magnitude larger than the run-to-run spread. (The brief that
+prompted this warned that its whole-frame "pixels changed" number swung between 0.5% and 3.8% on
+identical configurations. A metric that is profiled against a classified boundary rather than summed
+over the frame does not have that problem.)
+
+The two-triangle quad now measures the same as the same quad subdivided 8×8 — 1.21 against 1.21 —
+and the subdivided case is the reference for "no seam is possible here", so the residual asymmetry
+is the view's own, one half being more oblique than the other. The absolute flicker also falls 3×
+on the side that was boiling and 1.7× on the side that was not, so this is a stability improvement
+everywhere and not only at the edge.
+
+It changes stability, not appearance, and does not cost anything:
+
+- the converged image is unchanged — mean luminance per side 0.02902 / 0.03243 before,
+  0.02918 / 0.03244 after;
+- on Sponza, two builds differ by *less* than two runs of the same build (mean channel difference
+  0.0277 against a 0.0295 run-to-run control, and the same 191 maximum on TAA edge pixels either
+  way — that control is what makes the 191 readable, and without it the number looks alarming);
+- in a g-buffer-bound configuration (2400×1300, full-screen geometry, post chain off) it is
+  *faster*: 1.440 ms/frame against 1.502, medians of five 120-frame runs. Three reciprocals replace
+  seven divides, which is where that comes from;
+- all 35 pre-existing tests in `chunk_barycentric_full.spec.js` pass unchanged, 8 were added for
+  the case that was failing, and the full `src/shade` suite (3051 tests) passes.
+
+Of the 8 new tests, **6 also pass against the old implementation** — the algebra was never wrong
+for `w != 0`, so those are characterisation, not regression. The two that fail against it are the
+ones that matter: a vertex exactly on the eye plane (the old code divides by its w), and cyclic
+rotation of the corners. On that second one the old code moves by exactly one f32 ULP even with the
+emulator's f64 arithmetic; the new code is bit-identical.
+
+Residual order-dependence is not zero — the anchor-rotated build still differs slightly, because
+`barycentric_interpolate_uv` and the attribute interpolators sum `uv_i * l_i` in index order. That
+is a sum of three same-signed terms with no catastrophic cancellation, and it no longer produces a
+seam.
+
+### Why the pixel-relative offsets use `fma`
+
+`u` and `v` are formed with `fma(-pixel.x, w, x)` rather than `x - pixel.x * w`. It is the one place
+in the function where operands cancel, so it is the one place a fused multiply-add is worth asking
+for: a single rounding, with the error bounded relative to the result rather than to the
+intermediate product.
+
+Measured rather than assumed, because our own tooling cannot answer it — `WGSLLanguageCore`
+implements `fma` as plain `x * y + z`, so no emulator test observes fusion:
+
+- **it changes the emitted code.** Full-precision aggregates over 356k pixels are bit-reproducible
+  within a build and move in the fifth digit between the two forms, so this driver was *not* already
+  contracting the plain expression;
+- **it is faster** — 2.230 / 2.298 ms per frame against 2.429 for the plain form, medians of seven
+  120-frame runs, alternating between builds. One op instead of two. Absolute frame times drift
+  between sessions by more than this difference, so only the adjacent pairs mean anything;
+- **it buys no measurable image quality**, because there is none left to buy: the two-triangle quad
+  already matches its own 32×32 subdivision at extents of 425, 4000 and 40000, and the residual is
+  texture aliasing that subdivision does not fix either. The `extent` control exists to look for
+  headroom, and there is none up to a quad 94× the size of the repro.
+
+An attempt to measure reconstruction accuracy directly — treating the subdivided quad as ground
+truth for the same surface — **does not work**: 1×1 and 32×32 differ by about 1% in mean luminance
+from causes unrelated to reconstruction, which swamps the effect. Recorded here so nobody spends the
+afternoon on it twice.
+
+What WGSL *guarantees* about fusion is not established either; the spec's §15.7.5 and §17.5.32 did
+not come back legible. Portably the claim is "at worst a no-op, measured to help here".
+
+The other cancellation site is `u.y*v.z - u.z*v.y` in `chunk_barycentric_solve`, a difference of two
+products, which cancels hardest when a pixel sits near an edge. **The rewrite created it**, and it
+is worth being clear about that rather than filing it as inherited debt: the old formulation
+evaluated *one* 2×2 determinant, via the `determinant()` builtin, and it was a per-triangle constant
+that only cancelled for slivers. This one evaluates *nine* — three cofactors in each of three solves
+— and they depend on the pixel.
+
+That trade is deliberate and it measures out well: when a cofactor cancels, the weight it produces
+is near zero, so the absolute error in the interpolated attribute stays small, which is the benign
+direction. The badly conditioned part of the old code was never its determinant but the
+`deltaVec`/`interpInvW` chain that followed, and that is gone.
+
+Kahan's fma-based 2×2 determinant would hold each of the nine to ~1.5 ulp regardless of
+cancellation, for about 27 extra operations across the three solves. Nothing measurable currently
+demands it; it is where to go if conditioning bites here again.
+
+## What is not established
+
+- **The anchor rotation was a diagnostic, not a fix.** Before the rewrite it removed the seam at
+  1258×566 and made it *worse* at 1898×926 (ratio 3.49 against the default's 1.11) — which is what
+  a rounding-conditioning story predicts, and why the fix had to remove the anchor rather than pick
+  a better one.
+- **Jaggedness is a strong correlate, not a proven complete chain.** It tracks the output seam in
+  five of six configurations measured and fails in one (1898×926 anchor-rotated: jaggedness flat,
+  output ratio 3.49).
+- **Which term dominates is unknown.** The anchor subtraction, the determinant and the gradient
+  terms were not separated.
+- Anisotropy is *not* it: dropping the sampler to 1× leaves the step nearly intact (jaggedness ratio
+  1.34, output ratio 1.86).
+
+## The two probes that are gone
+
+Ruling out the disocclusion chain took reaching two things no extension can see: the velocity and
+disocclusion buffers are not published to any frame record — `ViewTextures` says so deliberately —
+and the resolve's blend weight is a local in a fragment shader. `capture_taa_inputs.js` and
+`capture_taa_decision.js` read them through two hooks added to `Renderer` for the purpose, the
+second one importing the resolve's own code chunks so the arithmetic it reports is the frame's
+rather than a re-implementation of it.
+
+Both are **removed**, along with the hooks. They were instrumentation for one question, that
+question is answered above, and the cost of keeping them is two permanent fields on `Renderer` and
+a per-frame branch in the hot path for everyone who never runs this page. Their findings survive in
+"What it found"; the code survives in the history — `git log -- src/shade/playground/ground_seam`,
+commit `df0b623f6`. Anything needing them again should restore the pair together and delete them
+again afterwards.
+
+What is left needs no hooks: `capture_scene_color.js` uses the sanctioned `RenderExtension` API,
+and the depth readback goes through the public `Renderer.texture_depth_current`.
+
+## Reproducing
+
+```js
+await configure({ segments: 1, triangulation: 'default', taa: true });
+
+await measure();            // burst, difference map, per-side split, profile across both diagonals
+await probe_depth();        // do the two triangles' depth planes meet on the shared edge?
+await probe_pre_taa(16, 'pre_taa');   // the resolve's input
+await probe_pre_taa(16, 'post_taa');  // its output
+```
+
+Every one leaves its full result on `globalThis.__last_*`.

package/src/shade/playground/ground_seam/capture_scene_color.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The scene colour *before* the temporal filter, made readable.
+ *
+ * This exists to split one question in two. The burst measurement sees the picture the temporal
+ * filter produced, and a seam in it can come from either side of that filter: the shading may be
+ * responding differently to the sub-pixel jitter on the two triangles, or the shading may be
+ * identical and the filter may be resolving it differently. Those want opposite fixes, and no
+ * amount of staring at the output distinguishes them.
+ *
+ * {@link FramePhase.AfterTransparency} is the last phase before the upscale, so what is captured
+ * here is the full pre-TAA frame at internal resolution — the temporal filter's *input*.
+ *
+ * The pass writes an imported texture, which the graph treats as a side effect, so it is not elided
+ * for having no consumer inside the frame.
+ */
+export class CaptureSceneColor extends RenderExtension {
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device: GPUDevice);
+    /**
+     * Whether to record at all. Off by default: a capture costs a full-resolution copy every frame,
+     * and the burst measurement this page mostly runs does not want one.
+     *
+     * @type {boolean}
+     */
+    enabled: boolean;
+    /**
+     * Luminance of the captured frame, one entry per pixel.
+     *
+     * Rec. 709 weights on the linear HDR values — this is upstream of the tonemap, so the numbers
+     * are radiance rather than display code values and there is no 8-bit quantization floor under
+     * the measurement.
+     *
+     * @returns {Promise<{luma: Float32Array, width: number, height: number}>}
+     */
+    read_luminance(): Promise<{
+        luma: Float32Array;
+        width: number;
+        height: number;
+    }>;
+    #private;
+}
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+//# sourceMappingURL=capture_scene_color.d.ts.map

package/src/shade/playground/ground_seam/capture_scene_color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture_scene_color.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ground_seam/capture_scene_color.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;GAcG;AACH;IA2CI;;OAEG;IACH,+BAIC;IAfD;;;;;OAKG;IACH,SAFU,OAAO,CAED;IAuEhB;;;;;;;;OAQG;IACH;cAF4B,YAAY;eAAS,MAAM;gBAAU,MAAM;OAwCtE;;CACJ;gCA5N+B,6CAA6C"}