@woosh/meep-engine 3.11.3 → 3.13.0

package/src/shade/device/timing/ShadeGPUContextProfiler.js

@@ -0,0 +1,182 @@
+import { assert } from "../../../core/assert.js";
+import { ShadeGPUComputePassEncoder } from "../pass/ShadeGPUComputePassEncoder.js";
+import { ShadeGPURenderPassEncoder } from "../pass/ShadeGPURenderPassEncoder.js";
+import { GPUTimerArray } from "./GPUTimerArray.js";
+
+/**
+ * Everything one {@link ShadeGPUCommandContext} needs in order to be profiled: its timer array, the
+ * recorder its timings go to, and which query set it is within the frame.
+ *
+ * **It opens the passes itself.** Two values are needed at two different instants — the
+ * `timestampWrites` before the encoder exists, the {@link GPUProfileWork} after — and any shape that
+ * hands both back to the caller has to carry them across that gap. The predecessor carried them in a
+ * private field on the command context, consumed by whatever ran next, which is the kind of coupling
+ * that breaks the moment a line is inserted between the two halves. Handing the profiler the encoder
+ * collapses the gap: both values are produced and consumed inside one method and there is nothing to
+ * carry.
+ *
+ * Off by default and constructed only by `enable_profiling`, so a context that is not being profiled
+ * holds one null field and allocates no query set.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ShadeGPUContextProfiler {
+
+    /**
+     * @type {GPUTimerArray}
+     */
+    #timers;
+
+    /**
+     * @type {GPUFrameRecorder}
+     */
+    #recorder;
+
+    /**
+     * Which query set this context is, within its frame. Carried into every span it records —
+     * timestamps from two query sets are not specified to share a clock domain, and a frame has one
+     * set per context.
+     *
+     * @type {number}
+     */
+    #query_set_id;
+
+    /**
+     * @type {Promise<void>}
+     */
+    #absorbed;
+
+    /**
+     * @type {function}
+     */
+    #absorbed_resolve;
+
+    /**
+     * @param {GPUDevice} device
+     * @param {GPUFrameRecorder} recorder
+     * @param {number} query_set_id this context's index within the frame
+     */
+    constructor(device, recorder, query_set_id) {
+        assert.defined(device, 'device');
+        assert.defined(recorder, 'recorder');
+        assert.isNonNegativeInteger(query_set_id, 'query_set_id');
+
+        this.#timers = new GPUTimerArray(device);
+        this.#recorder = recorder;
+        this.#query_set_id = query_set_id;
+
+        this.#absorbed = new Promise(resolve => {
+            this.#absorbed_resolve = resolve;
+        });
+    }
+
+    /**
+     * Resolves after this context's timings have been read back and handed to the recorder.
+     *
+     * @returns {Promise<void>}
+     */
+    get absorbed() {
+        return this.#absorbed;
+    }
+
+    /**
+     * @param {GPUCommandEncoder} encoder
+     * @param {GPUComputePassDescriptor} [descriptor]
+     * @returns {ShadeGPUComputePassEncoder}
+     */
+    begin_compute_pass(encoder, descriptor) {
+        const writes = this.#timers.getComputeWrites(descriptor?.label);
+
+        if (writes === undefined) {
+            return new ShadeGPUComputePassEncoder(encoder.beginComputePass(descriptor), null);
+        }
+
+        const gpu_pass = encoder.beginComputePass(this.#timed(descriptor, writes));
+
+        return new ShadeGPUComputePassEncoder(gpu_pass, this.#note_slot(writes));
+    }
+
+    /**
+     * @param {GPUCommandEncoder} encoder
+     * @param {GPURenderPassDescriptor} descriptor
+     * @returns {ShadeGPURenderPassEncoder}
+     */
+    begin_render_pass(encoder, descriptor) {
+        const writes = this.#timers.getRenderWrites(descriptor?.label);
+
+        if (writes === undefined) {
+            return new ShadeGPURenderPassEncoder(encoder.beginRenderPass(descriptor), null);
+        }
+
+        const gpu_pass = encoder.beginRenderPass(this.#timed(descriptor, writes));
+
+        return new ShadeGPURenderPassEncoder(gpu_pass, this.#note_slot(writes));
+    }
+
+    /**
+     * The descriptor a timed pass should be begun with.
+     *
+     * A copy, never a write-through. Several call sites reuse one descriptor across passes, and
+     * stamping `timestampWrites` onto it left the next pass carrying the previous pass's query
+     * indices. `{...undefined}` is `{}`, which is also how the no-descriptor form of
+     * `beginComputePass` stays legal.
+     *
+     * @param {GPUComputePassDescriptor|GPURenderPassDescriptor} [descriptor]
+     * @param {GPUComputePassTimestampWrites|GPURenderPassTimestampWrites} writes
+     * @returns {GPUComputePassDescriptor|GPURenderPassDescriptor}
+     */
+    #timed(descriptor, writes) {
+        return { ...descriptor, timestampWrites: writes };
+    }
+
+    /**
+     * Tell the recorder which graph pass owns the slot just claimed.
+     *
+     * The one moment the join can be made. The recorder knows which frame graph pass is executing
+     * right now; the slot is what the timings will come back keyed by. Neither fact is recoverable
+     * later — see {@link GPUFrameRecorder}.
+     *
+     * @param {GPUComputePassTimestampWrites|GPURenderPassTimestampWrites} writes
+     * @returns {GPUProfileWork|null} null below {@link GPUProfileLevel.WORKLOAD}
+     */
+    #note_slot(writes) {
+        return this.#recorder.note_pass_slot(
+            this.#query_set_id,
+            writes.beginningOfPassWriteIndex / 2
+        );
+    }
+
+    /**
+     * @param {GPUCommandEncoder} encoder
+     * @returns {void}
+     */
+    resolve(encoder) {
+        this.#timers.resolve(encoder);
+    }
+
+    /**
+     * Read the timings back and hand them to the recorder. Resolves {@link absorbed} either way.
+     *
+     * @returns {void}
+     */
+    absorb() {
+        const timers = this.#timers;
+
+        timers
+            .download_results()
+            .then(() => {
+                this.#recorder.absorb(timers, this.#query_set_id);
+            })
+            .finally(() => {
+                timers.destroy();
+
+                /*
+                 In `finally` so a failed readback still releases whoever is waiting on the frame. A
+                 profile session that hangs because one download rejected is worse than one missing a
+                 frame.
+                */
+                this.#absorbed_resolve();
+            });
+    }
+}

package/src/shade/device/timing/profile/GPUProfileSession.d.ts

@@ -20,10 +20,10 @@
  * application that never mentions the profiler does not carry any of it. The feature ships without
  * a build flag, a strip-plugin interaction, or a dead branch anyone has to keep honest.
  *
- * Two leaf helpers under this directory *are* linked unconditionally, because
- * {@link ShadeGPUCommandContext} needs them while encoding: `make_profiling_pass_encoder` and
- * `parse_workgroup_size`. They import `assert` and nothing else, and neither knows what a capture
- * is. What remains in the engine beyond those is a nullable field and the null checks around it.
+ * Nothing under this directory is linked unconditionally. The pass encoders count dispatches into a
+ * {@link GPUProfileWork} when handed one, but they hold it as a bag of counters and never name the
+ * type; the workgroup size they record comes off {@link ComputePipelineDescriptor}, which reads it
+ * as its code is set. What remains in the engine is a nullable field and the null checks around it.
  *
  * Recording is an **open-ended forward stream**: `frame_limit` defaults to `Infinity` and
  * everything captured is kept. There is no ring buffer. Uncapped means a per-frame cost is also a

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

@@ -43,10 +43,10 @@ const DEFAULT_BYTE_BUDGET = 512 * 1024 * 1024;
  * application that never mentions the profiler does not carry any of it. The feature ships without
  * a build flag, a strip-plugin interaction, or a dead branch anyone has to keep honest.
  *
- * Two leaf helpers under this directory *are* linked unconditionally, because
- * {@link ShadeGPUCommandContext} needs them while encoding: `make_profiling_pass_encoder` and
- * `parse_workgroup_size`. They import `assert` and nothing else, and neither knows what a capture
- * is. What remains in the engine beyond those is a nullable field and the null checks around it.
+ * Nothing under this directory is linked unconditionally. The pass encoders count dispatches into a
+ * {@link GPUProfileWork} when handed one, but they hold it as a bag of counters and never name the
+ * type; the workgroup size they record comes off {@link ComputePipelineDescriptor}, which reads it
+ * as its code is set. What remains in the engine is a nullable field and the null checks around it.
  *
  * Recording is an **open-ended forward stream**: `frame_limit` defaults to `Infinity` and
  * everything captured is kept. There is no ring buffer. Uncapped means a per-frame cost is also a

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_blas_audit_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js"],"names":[],"mappings":"AAqBA,2CAA4C;AA4D5C;;;;;;;;;;;;;;;;GAgBG;AACH,+CAFU,aAAa,CAOpB;8BApG2B,wCAAwC"}
+{"version":3,"file":"shader_blas_audit_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js"],"names":[],"mappings":"AAqBA,2CAA4C;AA8D5C;;;;;;;;;;;;;;;;GAgBG;AACH,+CAFU,aAAa,CAMpB;8BArG2B,wCAAwC"}

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js

@@ -22,8 +22,10 @@ import {
 export const BLAS_AUDIT_WORKGROUP_SIZE = 64;
 
 const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, 16 bytes, read-only: immediate data rather than a uniform buffer
+resources.setImmediate("settings", BLAS_LEAF_BOUNDS_SETTINGS_STRUCT);
 resources.createGroup()
-    .addUniform("settings", BLAS_LEAF_BOUNDS_SETTINGS_STRUCT)
     .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
     .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
     .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT), false)
@@ -100,5 +102,4 @@ export const shader_blas_audit_leaf_triangles = ComputeShader.from({
     label: "BLAS/AuditLeafTriangles",
     resources,
     body,
-    group_size: [BLAS_AUDIT_WORKGROUP_SIZE, 1, 1],
 });

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_points.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_blas_audit_points.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_points.js"],"names":[],"mappings":"AAkBA,4CAA6C;AAE7C;;GAEG;AACH,0CAFU,YAAY,CAOG;AA8CzB;;;;;;;;;;;;;GAaG;AACH,uCAFU,aAAa,CAOpB;6BA3F0B,4CAA4C;8BAE3C,wCAAwC"}
+{"version":3,"file":"shader_blas_audit_points.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_points.js"],"names":[],"mappings":"AAkBA,4CAA6C;AAE7C;;GAEG;AACH,0CAFU,YAAY,CAOG;AAgDzB;;;;;;;;;;;;;GAaG;AACH,uCAFU,aAAa,CAMpB;6BA5F0B,4CAA4C;8BAE3C,wCAAwC"}

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_points.js

@@ -29,8 +29,10 @@ export const BLAS_POINTS_SETTINGS_STRUCT = WebGPUStruct.from({
 }, "BlasPointsSettings");
 
 const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, 32 bytes, read-only: immediate data rather than a uniform buffer
+resources.setImmediate("settings", BLAS_POINTS_SETTINGS_STRUCT);
 resources.createGroup()
-    .addUniform("settings", BLAS_POINTS_SETTINGS_STRUCT)
     // three f32 per point, in the geometry's own space
     .addStorageBuffer("targets", WebGPUArray.from(f32), false)
     .addStorageBuffer("blas_lookup", WebGPUArray.from(u32), false)
@@ -90,5 +92,4 @@ export const shader_blas_audit_points = ComputeShader.from({
     label: "BLAS/AuditPoints",
     resources,
     body,
-    group_size: [BLAS_POINTS_WORKGROUP_SIZE, 1, 1],
 });

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_visibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_blas_audit_visibility.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_visibility.js"],"names":[],"mappings":"AAyBA,gDAAiD;AAEjD;;GAEG;AACH,8CAFU,YAAY,CASO;AA0E7B;;;;;;;;;;;;;;;;GAgBG;AACH,2CAFU,aAAa,CAOpB;6BAnI0B,4CAA4C;8BAE3C,wCAAwC"}
+{"version":3,"file":"shader_blas_audit_visibility.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_visibility.js"],"names":[],"mappings":"AAyBA,gDAAiD;AAEjD;;GAEG;AACH,8CAFU,YAAY,CASO;AA4E7B;;;;;;;;;;;;;;;;GAgBG;AACH,2CAFU,aAAa,CAMpB;6BApI0B,4CAA4C;8BAE3C,wCAAwC"}

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_visibility.js

@@ -1,134 +1,135 @@
-import { f32, u32, vec3f } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../renderer/shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
-import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
-import {
-    BVH_NODE_CHILD_2_WORD,
-    BVH_NODE_STRIDE_WORDS
-} from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
-import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
-import { BVH_TRAVERSAL_STACK_SIZE } from "../../renderer/shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
-import {
-    chunk_ray_query_blas_nearest
-} from "../../renderer/shader/chunk/geometry/ray/chunk_ray_query_blas_nearest.js";
-import {
-    chunk_geometry_read_triangle_vertices
-} from "../../renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_vertices.js";
-import { RAY_STRUCT } from "../../renderer/shader/chunk/geometry/ray/RAY_STRUCT.js";
-import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
-import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../renderer/geometry/GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
-import {
-    MESHLET_METADATA_STRUCT
-} from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-
-export const BLAS_VISIBILITY_WORKGROUP_SIZE = 64;
-
-/**
- * @type {WebGPUStruct}
- */
-export const BLAS_VISIBILITY_SETTINGS_STRUCT = WebGPUStruct.from({
-    origin: vec3f,
-    leaf_count: u32,
-    node_word_offset: u32,
-    leaf_nodes_offset: u32,
-    geometry_index: u32,
-    tmax: f32,
-}, "BlasVisibilitySettings");
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addUniform("settings", BLAS_VISIBILITY_SETTINGS_STRUCT)
-    .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
-    .addStorageBuffer("blas_lookup", WebGPUArray.from(u32), false)
-    .addStorageBuffer("blas_data", WebGPUArray.from(BVH2_NODE_STRUCT), false)
-    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
-    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT), false)
-    .addStorageBuffer("meshlet_data", GEOMETRY_ATTRIBUTE_DATA_TYPE, false)
-    .addStorageBuffer("nodes", WebGPUArray.from(f32), false)
-    // per leaf: the parametric t the traversal came back with, negative for a miss
-    .addStorageBuffer("out_t", WebGPUArray.from(f32), true)
-    // per leaf: the triangle the traversal returned, or 0xFFFFFFFF
-    .addStorageBuffer("out_triangle", WebGPUArray.from(u32), true)
-    // per leaf: the distance to the point the ray was aimed at, which the answer cannot exceed
-    .addStorageBuffer("out_expected_t", WebGPUArray.from(f32), true);
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-const NODE_STRIDE = ${BVH_NODE_STRIDE_WORDS}u;
-const NODE_CHILD_2 = ${BVH_NODE_CHILD_2_WORD}u;
-
-@compute @workgroup_size(${BLAS_VISIBILITY_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
-    let i = gid.x;
-
-    if (i >= settings.leaf_count) {
-        return;
-    }
-
-    let leaf_node = leaf_nodes[settings.leaf_nodes_offset + i];
-
-    let node_word = settings.node_word_offset + leaf_node * NODE_STRIDE;
-
-    let meshlet_triangle_id = bitcast<u32>(nodes[node_word + NODE_CHILD_2]);
-
-    let triangle = geometry_read_triangle_vertices(
-        geometries[settings.geometry_index],
-        meshlet_triangle_id
-    );
-
-    // Aim at the triangle's own centroid, which is strictly inside it. The ray provably intersects
-    // this triangle, so the traversal has to come back with *something* — this one, or something
-    // occluding it. A miss is not a geometric possibility; it is the traversal failing to reach a
-    // leaf whose box, by construction, the ray passes through.
-    let centre = (triangle.a.position + triangle.b.position + triangle.c.position) / 3.0;
-
-    var ray: ${RAY_STRUCT.wgsl_ref};
-
-    ray.origin = settings.origin;
-    ray.direction = normalize(centre - settings.origin);
-    ray.tmax = settings.tmax;
-
-    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
-
-    let hit = ray_query_blas_nearest(ray, settings.geometry_index, &stack, 0u);
-
-    out_t[i] = hit.t;
-    out_triangle[i] = select(0xFFFFFFFFu, hit.triangle, hit.t >= 0.0);
-
-    // The ray was aimed at a point on this triangle, so the nearest surface along it is at most
-    // this far. An answer beyond it is not an occlusion and not a miss — it is the traversal
-    // walking past a surface it was pointed at, which is what a hole in the traced image is.
-    out_expected_t[i] = length(centre - settings.origin);
-}
-`, [
-    RAY_STRUCT.declaration_chunk,
-    chunk_geometry_read_triangle_vertices,
-    chunk_ray_query_blas_nearest,
-]);
-
-/**
- * Ask the traversal, once per triangle, whether it can find that triangle.
- *
- * Every structural check on the tree has passed, which narrows the fault to the traversal itself —
- * and traversal is the one thing no readback of the tree can exercise. So this runs the real
- * `ray_query_blas_nearest`, the same function the path tracer calls, along a ray whose answer is
- * known in advance.
- *
- * The ray goes from the camera to a triangle's centroid. That point is inside the triangle, so the
- * ray intersects it, so the query must return a hit — this triangle if nothing is in front, some
- * other one if something is. Only a miss is impossible, and a miss is therefore a traversal that
- * failed to reach a leaf whose box it was inside.
- *
- * Which triangles miss, and where they are, is the whole diagnosis.
- *
- * @type {ComputeShader}
- */
-export const shader_blas_audit_visibility = ComputeShader.from({
-    label: "BLAS/AuditVisibility",
-    resources,
-    body,
-    group_size: [BLAS_VISIBILITY_WORKGROUP_SIZE, 1, 1],
-});
+import { f32, u32, vec3f } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../renderer/shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    BVH_NODE_CHILD_2_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import { BVH_TRAVERSAL_STACK_SIZE } from "../../renderer/shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
+import {
+    chunk_ray_query_blas_nearest
+} from "../../renderer/shader/chunk/geometry/ray/chunk_ray_query_blas_nearest.js";
+import {
+    chunk_geometry_read_triangle_vertices
+} from "../../renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_vertices.js";
+import { RAY_STRUCT } from "../../renderer/shader/chunk/geometry/ray/RAY_STRUCT.js";
+import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
+import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../renderer/geometry/GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
+import {
+    MESHLET_METADATA_STRUCT
+} from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+
+export const BLAS_VISIBILITY_WORKGROUP_SIZE = 64;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const BLAS_VISIBILITY_SETTINGS_STRUCT = WebGPUStruct.from({
+    origin: vec3f,
+    leaf_count: u32,
+    node_word_offset: u32,
+    leaf_nodes_offset: u32,
+    geometry_index: u32,
+    tmax: f32,
+}, "BlasVisibilitySettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, 32 bytes, read-only: immediate data rather than a uniform buffer
+resources.setImmediate("settings", BLAS_VISIBILITY_SETTINGS_STRUCT);
+resources.createGroup()
+    .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
+    .addStorageBuffer("blas_lookup", WebGPUArray.from(u32), false)
+    .addStorageBuffer("blas_data", WebGPUArray.from(BVH2_NODE_STRUCT), false)
+    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
+    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT), false)
+    .addStorageBuffer("meshlet_data", GEOMETRY_ATTRIBUTE_DATA_TYPE, false)
+    .addStorageBuffer("nodes", WebGPUArray.from(f32), false)
+    // per leaf: the parametric t the traversal came back with, negative for a miss
+    .addStorageBuffer("out_t", WebGPUArray.from(f32), true)
+    // per leaf: the triangle the traversal returned, or 0xFFFFFFFF
+    .addStorageBuffer("out_triangle", WebGPUArray.from(u32), true)
+    // per leaf: the distance to the point the ray was aimed at, which the answer cannot exceed
+    .addStorageBuffer("out_expected_t", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const NODE_STRIDE = ${BVH_NODE_STRIDE_WORDS}u;
+const NODE_CHILD_2 = ${BVH_NODE_CHILD_2_WORD}u;
+
+@compute @workgroup_size(${BLAS_VISIBILITY_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let i = gid.x;
+
+    if (i >= settings.leaf_count) {
+        return;
+    }
+
+    let leaf_node = leaf_nodes[settings.leaf_nodes_offset + i];
+
+    let node_word = settings.node_word_offset + leaf_node * NODE_STRIDE;
+
+    let meshlet_triangle_id = bitcast<u32>(nodes[node_word + NODE_CHILD_2]);
+
+    let triangle = geometry_read_triangle_vertices(
+        geometries[settings.geometry_index],
+        meshlet_triangle_id
+    );
+
+    // Aim at the triangle's own centroid, which is strictly inside it. The ray provably intersects
+    // this triangle, so the traversal has to come back with *something* — this one, or something
+    // occluding it. A miss is not a geometric possibility; it is the traversal failing to reach a
+    // leaf whose box, by construction, the ray passes through.
+    let centre = (triangle.a.position + triangle.b.position + triangle.c.position) / 3.0;
+
+    var ray: ${RAY_STRUCT.wgsl_ref};
+
+    ray.origin = settings.origin;
+    ray.direction = normalize(centre - settings.origin);
+    ray.tmax = settings.tmax;
+
+    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
+
+    let hit = ray_query_blas_nearest(ray, settings.geometry_index, &stack, 0u);
+
+    out_t[i] = hit.t;
+    out_triangle[i] = select(0xFFFFFFFFu, hit.triangle, hit.t >= 0.0);
+
+    // The ray was aimed at a point on this triangle, so the nearest surface along it is at most
+    // this far. An answer beyond it is not an occlusion and not a miss — it is the traversal
+    // walking past a surface it was pointed at, which is what a hole in the traced image is.
+    out_expected_t[i] = length(centre - settings.origin);
+}
+`, [
+    RAY_STRUCT.declaration_chunk,
+    chunk_geometry_read_triangle_vertices,
+    chunk_ray_query_blas_nearest,
+]);
+
+/**
+ * Ask the traversal, once per triangle, whether it can find that triangle.
+ *
+ * Every structural check on the tree has passed, which narrows the fault to the traversal itself —
+ * and traversal is the one thing no readback of the tree can exercise. So this runs the real
+ * `ray_query_blas_nearest`, the same function the path tracer calls, along a ray whose answer is
+ * known in advance.
+ *
+ * The ray goes from the camera to a triangle's centroid. That point is inside the triangle, so the
+ * ray intersects it, so the query must return a hit — this triangle if nothing is in front, some
+ * other one if something is. Only a miss is impossible, and a miss is therefore a traversal that
+ * failed to reach a leaf whose box it was inside.
+ *
+ * Which triangles miss, and where they are, is the whole diagnosis.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_blas_audit_visibility = ComputeShader.from({
+    label: "BLAS/AuditVisibility",
+    resources,
+    body,
+});