@woosh/meep-engine 3.3.0 → 3.4.0

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

@@ -0,0 +1,116 @@
+import { Node3D } from "../../renderer/scene/Node3D.js";
+
+/**
+ * Stand one loaded character on the floor at `(x, 0, z)`.
+ *
+ * ## Why the mesh node is not the placement point
+ *
+ * It is tempting, and it is what this page used to do: the mesh is the visible thing, so move the
+ * mesh. For a {@link SkinnedMesh} that is a no-op, and the reason is the glTF skinning formula
+ * itself. A skinned vertex lands at
+ *
+ * ```
+ * mesh.global × inverse(mesh.global) × joint.global × inverse_bind × v
+ * ```
+ *
+ * — `chunk_skin_blend_mesh_local` folds the leftmost inverse into each joint matrix and the
+ * rasterizer re-applies `mesh.global` afterwards, so the mesh node's own transform **cancels
+ * exactly** and the vertex is at `joint.global × inverse_bind × v`. `compute_skin_world_bounds`
+ * composes the published box the same way and does not read the mesh node either. So a skinned
+ * character is placed by its **joints**, and the only thing that moves them is an ancestor they
+ * actually sit under.
+ *
+ * Michelle is the shape that makes this concrete. Her file is one root carrying the centimetre
+ * scale and the Z-up rotation, with the mesh node and the joint root as *siblings* beneath it:
+ *
+ * ```
+ * "Character"            R=(0.70711, 0, 0, 0.70711)  S=(0.01, 0.01, 0.01)
+ * ├── "Ch03"             mesh 0, skin 0 — no local transform of its own
+ * └── "mixamorig:Hips"   the joint root
+ * ```
+ *
+ * Nothing under `Ch03` drives a joint, so writing a grid offset there — to either transform —
+ * moves nothing at all.
+ *
+ * ## Why a placement node rather than the character's own root
+ *
+ * `"Character"`'s local transform is the file's, and it is load-bearing twice over: the 0.01 scale
+ * is what makes the inverse-bind matrices agree with the vertex positions, and a `Transform64`
+ * composes as `T · R · S`, so a translation written there is *not* the world offset — it is an
+ * offset the file's own rotation and scale then act on. A fresh parent keeps the two apart: the
+ * grid offset is this node's whole transform, the file's is untouched below it, and the
+ * composition happens where it always happens.
+ *
+ * A node under {@link TransformAuthority.GPU} still follows a CPU-driven parent — the hierarchy
+ * pass composes `global` from the node's own TRS and the parent chain — so the joints the pose
+ * accumulator owns are carried by this without anyone writing to their rows.
+ *
+ * ## Why the local transform
+ *
+ * The same reason the floor is placed that way, and it is worth restating because this page has
+ * now been bitten by it twice. `Node3D.transform_global` is **derived** — its doc comment says so
+ * — and `updateMatrices` recomputes it from the local transform and the parent chain. The GPU is
+ * handed the node's local TRS and composes `node.global` from it, so a placement that only ever
+ * reached `transform_global` is discarded at both ends. See `add_floor` for the version of this
+ * where the two ends disagreed and produced two different pictures; here they agreed on the wrong
+ * answer, which is quieter and took longer to see.
+ *
+ * @param {Scene} scene
+ * @param {SceneBundle} bundle a freshly loaded character — its roots must not be parented yet
+ * @param {number} x
+ * @param {number} z
+ * @returns {Node3D} the placement node, now the parent of every root in `bundle.scenes`
+ */
+export function place_character(scene, bundle, x, z) {
+    const placement = new Node3D();
+
+    placement.name = `placement(${x}, ${z})`;
+
+    // `Transform64` keeps its matrix by hand: setting a component leaves the matrix holding what it
+    // held before, so the write is only real after `updateMatrix`.
+    placement.transform_local.setTranslation(x, 0, z);
+    placement.transform_local.updateMatrix();
+
+    placement.addChildren(bundle.scenes);
+
+    placement.updateMatrices();
+
+    // `updateMatrices` walks pre-order, and a glTF character's joint root is the mesh node's
+    // sibling — so the `updateBoundsBasic` a SkinnedMesh inherits mid-walk reads joints the walk
+    // has not reached yet, and bounds the mesh where the character stood before the move. The walk
+    // is over by here, so this pass reads a settled skeleton. `GPUSceneContext` re-derives the box
+    // again on its way to the `meshes` row for exactly this reason; this is so the mesh is not
+    // carrying a stale one in the meantime.
+    placement.traverse(node => {
+        if (node.isMesh === true) {
+            node.updateBoundsBasic();
+        }
+    });
+
+    scene.add(placement);
+
+    return placement;
+}
+
+/**
+ * Where the `index`-th of `count` characters stands: a square-ish grid centred on the origin, laid
+ * out in rows along +x.
+ *
+ * Centred rather than growing from the origin so that `?count=N` frames the same way for every N —
+ * the camera is aimed at the union of the cast, and a grid that walks away from the origin as it
+ * grows pushes that union off with it.
+ *
+ * @param {number} index
+ * @param {number} count
+ * @param {number} spacing distance between neighbours
+ * @returns {{x: number, z: number}}
+ */
+export function grid_position(index, count, spacing) {
+    const columns = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / columns);
+
+    return {
+        x: ((index % columns) - (columns - 1) / 2) * spacing,
+        z: (Math.floor(index / columns) - (rows - 1) / 2) * spacing,
+    };
+}

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

@@ -0,0 +1,21 @@
+export const BLAS_AUDIT_WORKGROUP_SIZE: 64;
+/**
+ * Read every leaf's triangle back through the path the *intersector* uses.
+ *
+ * The refit computes a leaf's box with `geometry_read_triangle_bounds`; `ray_query_blas_nearest`
+ * fetches the triangle it actually tests with `geometry_read_triangle_vertices`. Those are two
+ * different functions over the same encoded payload, and nothing until now has held them against
+ * each other on real data — only on a synthetic case in `blas_refit_leaf_bounds.spec.js`.
+ *
+ * If they disagree, a ray descends into a box, tests a triangle that is somewhere else, and misses.
+ * Whole meshlets go absent while the tree itself checks out perfectly, which is exactly the shape of
+ * failure that survived every structural test of the tree.
+ *
+ * Writes the intersector's view of each leaf's triangle so the host can compare it against the box
+ * the tree is carrying.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_blas_audit_leaf_triangles: ComputeShader;
+import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
+//# sourceMappingURL=shader_blas_audit_leaf_triangles.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,104 @@
+import { f32, u32 } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../renderer/shader/type/WebGPUArray.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 {
+    chunk_geometry_read_triangle_vertices
+} from "../../renderer/shader/chunk/geometry/format/chunk_geometry_read_triangle_vertices.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";
+import {
+    BLAS_LEAF_BOUNDS_SETTINGS_STRUCT
+} from "../../renderer/geometry/bvh/shader_blas_refit_leaf_bounds.js";
+
+export const BLAS_AUDIT_WORKGROUP_SIZE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+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)
+    .addStorageBuffer("meshlet_data", GEOMETRY_ATTRIBUTE_DATA_TYPE, false)
+    .addStorageBuffer("nodes", WebGPUArray.from(f32), false)
+    // six floats per leaf: the AABB of the triangle as the *intersection* path sees it
+    .addStorageBuffer("out_bounds", 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_AUDIT_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]);
+
+    // The reader the ray-triangle test uses, not the one the refit used. If the two ever name
+    // different triangles for one payload, the tree bounds a triangle the intersector never tests.
+    let triangle = geometry_read_triangle_vertices(
+        geometries[settings.geometry_index],
+        meshlet_triangle_id
+    );
+
+    let a = triangle.a.position;
+    let b = triangle.b.position;
+    let c = triangle.c.position;
+
+    let low = min(a, min(b, c));
+    let high = max(a, max(b, c));
+
+    let base = i * 6u;
+
+    out_bounds[base] = low.x;
+    out_bounds[base + 1u] = low.y;
+    out_bounds[base + 2u] = low.z;
+    out_bounds[base + 3u] = high.x;
+    out_bounds[base + 4u] = high.y;
+    out_bounds[base + 5u] = high.z;
+}
+`, [
+    chunk_geometry_read_triangle_vertices,
+]);
+
+/**
+ * Read every leaf's triangle back through the path the *intersector* uses.
+ *
+ * The refit computes a leaf's box with `geometry_read_triangle_bounds`; `ray_query_blas_nearest`
+ * fetches the triangle it actually tests with `geometry_read_triangle_vertices`. Those are two
+ * different functions over the same encoded payload, and nothing until now has held them against
+ * each other on real data — only on a synthetic case in `blas_refit_leaf_bounds.spec.js`.
+ *
+ * If they disagree, a ray descends into a box, tests a triangle that is somewhere else, and misses.
+ * Whole meshlets go absent while the tree itself checks out perfectly, which is exactly the shape of
+ * failure that survived every structural test of the tree.
+ *
+ * Writes the intersector's view of each leaf's triangle so the host can compare it against the box
+ * the tree is carrying.
+ *
+ * @type {ComputeShader}
+ */
+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

@@ -0,0 +1,23 @@
+export const BLAS_POINTS_WORKGROUP_SIZE: 64;
+/**
+ * @type {WebGPUStruct}
+ */
+export const BLAS_POINTS_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * Ask the traversal about points the caller chooses, rather than about triangle centroids.
+ *
+ * Centroid rays answer "is this triangle reachable at all", and every triangle of a large flat
+ * surface can be reachable at its middle while a band of it is not reachable at its edge — which is
+ * the shape of failure a centroid audit reports as clean. Sampling the surface on a grid asks the
+ * finer question, and answers it in the geometry's own coordinates rather than in pixels, so the
+ * region that fails can be pointed at rather than described.
+ *
+ * A point known to lie on a surface must produce a hit at or before its own distance. Anything
+ * further, or nothing at all, is the traversal declining a surface it was aimed at.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_blas_audit_points: ComputeShader;
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
+//# sourceMappingURL=shader_blas_audit_points.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,94 @@
+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 { 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 { 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_POINTS_WORKGROUP_SIZE = 64;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const BLAS_POINTS_SETTINGS_STRUCT = WebGPUStruct.from({
+    origin: vec3f,
+    point_count: u32,
+    geometry_index: u32,
+    tmax: f32,
+}, "BlasPointsSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+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)
+    .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("out_t", WebGPUArray.from(f32), true)
+    .addStorageBuffer("out_expected", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${BLAS_POINTS_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let i = gid.x;
+
+    if (i >= settings.point_count) {
+        return;
+    }
+
+    let target = vec3<f32>(targets[i * 3u], targets[i * 3u + 1u], targets[i * 3u + 2u]);
+
+    var ray: ${RAY_STRUCT.wgsl_ref};
+
+    ray.origin = settings.origin;
+    ray.direction = normalize(target - 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_expected[i] = length(target - settings.origin);
+}
+`, [
+    RAY_STRUCT.declaration_chunk,
+    chunk_ray_query_blas_nearest,
+]);
+
+/**
+ * Ask the traversal about points the caller chooses, rather than about triangle centroids.
+ *
+ * Centroid rays answer "is this triangle reachable at all", and every triangle of a large flat
+ * surface can be reachable at its middle while a band of it is not reachable at its edge — which is
+ * the shape of failure a centroid audit reports as clean. Sampling the surface on a grid asks the
+ * finer question, and answers it in the geometry's own coordinates rather than in pixels, so the
+ * region that fails can be pointed at rather than described.
+ *
+ * A point known to lie on a surface must produce a hit at or before its own distance. Anything
+ * further, or nothing at all, is the traversal declining a surface it was aimed at.
+ *
+ * @type {ComputeShader}
+ */
+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

@@ -0,0 +1,26 @@
+export const BLAS_VISIBILITY_WORKGROUP_SIZE: 64;
+/**
+ * @type {WebGPUStruct}
+ */
+export const BLAS_VISIBILITY_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * 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;
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
+//# sourceMappingURL=shader_blas_audit_visibility.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,134 @@
+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],
+});

package/src/shade/playground/skinned_blas_refit/sweep_views.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Run the traced-against-rasterized comparison from many directions and report the worst.
+ *
+ * One view proves nothing. Every check that has come back clean so far has come back clean from
+ * *a* camera, and the disagreement people actually see is reported from cameras they orbited to —
+ * so "which views fail" is the question, and answering it by looking is what has cost the most time
+ * on this.
+ *
+ * Views are placed on a sphere around the instance being examined, at several elevations including
+ * from below, because a mesh of long thin slivers presents completely differently edge-on than
+ * face-on and a horizon-only ring would miss half of it.
+ *
+ * The camera is driven directly rather than through the orbital controller, so a sweep does not
+ * depend on the controller's state and leaves it where it found it.
+ */
+/**
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {PerspectiveCamera} options.camera
+ * @param {Scene} options.scene
+ * @param {Mesh} options.mesh the instance to orbit and to frame on
+ * @param {function(boolean): void} [options.suspend]
+ * @param {number} [options.azimuths]
+ * @param {number[]} [options.elevations] radians; negative looks up from below
+ * @param {number} [options.distance] multiples of the instance's bounding radius
+ * @param {number} [options.samples] samples per pixel at each view
+ * @returns {Promise<object>}
+ */
+export function sweep_views({ renderer, camera, scene, mesh, suspend, azimuths, elevations, distance, samples, }: {
+    renderer: Renderer;
+    camera: PerspectiveCamera;
+    scene: Scene;
+    mesh: Mesh;
+    suspend?: (arg0: boolean) => void;
+    azimuths?: number;
+    elevations?: number[];
+    distance?: number;
+    samples?: number;
+}): Promise<object>;
+//# sourceMappingURL=sweep_views.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sweep_views.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/sweep_views.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AACH;IAX6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACN,IAAI;IACgB,OAAO,UAAhC,OAAO,KAAG,IAAI;IACN,QAAQ,GAAzB,MAAM;IACa,UAAU,GAA7B,MAAM,EAAE;IACS,QAAQ,GAAzB,MAAM;IACW,OAAO,GAAxB,MAAM;IACJ,QAAQ,MAAM,CAAC,CAwG3B"}