@woosh/meep-engine 3.2.0 → 3.4.0

package/src/shade/renderer/gpu_primitive/bvh/PHASE1_HANDOVER.md

@@ -0,0 +1,201 @@
+# Hand-over: implement Phase 1 of the GPU BVH builder
+
+You are implementing **Phase 1 only** of `GPU_BVH_BUILD_PLAN.md` (same directory — read it in
+full before writing any code; it is the authoritative design, this file is the execution brief).
+Phase 1 = two deliverables, in this order:
+
+1. **A key-value radix sort** built around CSDLDF, re-founding `src/shade/renderer/gpu_primitive/sort/`.
+2. **A GPU TLAS build** (LBVH: extract → morton → sort → Karras emission → refit) replacing the
+   CPU-side work in `GPUInstancesAccelerationStructure.push_to_gpu()`.
+
+Do **not** start phases 2–4 (treelets, BLAS, BVH8), do not redesign node formats, do not add
+frameworks. Everything you need exists in the tree or in git history; this project's explicit
+standard is *port and reuse, don't invent*.
+
+## Read these before writing code
+
+In order, each for a stated reason:
+
+1. `src/shade/renderer/gpu_primitive/bvh/GPU_BVH_BUILD_PLAN.md` — the design. §2.1 is the byte
+   contract, §4 is what you are building, §4.2.1 is the sort, §4.5 is the test plan you must
+   satisfy, §6/§7 explain decisions — do not relitigate them.
+2. `src/core/bvh2/bvh3/ebvh_build_hierarchy_radix.js` (+ its `.spec.js`) — the CPU oracle your
+   emission kernel transliterates: `delta` with the `32 + clz32(i^j)` duplicate-key tiebreak,
+   `determineRange`, `find_split`. Read the comment block at `find_split` about why duplicate
+   codes must NOT be midpoint-split — that bug produces a shared-node non-tree.
+3. `src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js` and
+   `graph_prefix_scan_csdldf.js` — the blessed scan you reuse as the sort's spine, and the house
+   subgroup idioms (`subgroup_size` builtin, `MIN_SUBGROUP_SIZE = 4`,
+   `@diagnostic(off, subgroup_uniformity)` helpers, split flag words, bounded spin + fallback).
+4. Git history of the deleted OneSweep port — orchestration + scatter/ranking reference:
+   `git show 370542c3f:src/shade/renderer/gpu_primitive/sort/one_sweep/graph_radix_sort.js`
+   (graph orchestration template), `...shader_digit_binning_pass_pairs.js` (workgroup ranking
+   machinery + two pinned WebGPU lessons), `...one_sweep.spec.js` and
+   `...verify_radix_sort_one_sweep.js` (spec/verify templates). List the directory with
+   `git show 370542c3f:src/shade/renderer/gpu_primitive/sort/one_sweep/ 2>$null` or
+   `git ls-tree 370542c3f -- src/shade/renderer/gpu_primitive/sort/one_sweep/`.
+5. `src/shade/renderer/animation/skinning/bounds_refresh/shader_meshlet_bounds_reduce.js` +
+   `chunk_aabb_atomic_f32.js` — the reduce-then-atomic-merge pattern for the scene-bounds pass,
+   and the "same buffer bound as `array<atomic<u32>>` in one pass, typed in another" idiom the
+   refit pass needs. Note its comment about `bitcast<f32>(0x7F800000u)` not const-folding.
+6. `src/shade/renderer/scene/GPUInstancesAccelerationStructure.js`,
+   `src/shade/renderer/scene/GPUSceneContext.js` (how `instance_add/remove/update` and
+   `update()` drive it), `src/shade/renderer/geometry/bvh/bvh_to_gpu_buffer.js` +
+   `bvh2_compress.js` (the legacy path you keep behind a flag),
+   `src/shade/renderer/scene/MESH_INSTANCE_METADATA_STRUCT.js` (where per-row world AABBs live).
+7. `src/shade/renderer/shader/chunk/geometry/ray/chunk_ray_query_nearest.js` — the traversal
+   consumer; internalize its leaf/root conventions before emitting a single node.
+8. Testing machinery: `src/shade/wgsl/emulator/ComputeShaderEmulator.js` + its `.spec.js` and a
+   couple of existing chunk specs under `src/shade/renderer/shader/chunk/math/` (the established
+   pattern for emulator-testing individual WGSL functions);
+   `src/shade/device/mock/SoftwareGPUDevice.js` + `SoftwareGPUComputePassEncoder.js` (a
+   **recording** device — executes no shaders; assert on what was encoded and on host-written
+   bytes only); `src/shade/renderer/gpu_primitive/prefix_sum/v1/test_prefix_sum.js` and
+   `src/shade/renderer/buffer/graph_inspect_gpu_buffer.js` (browser verify pattern);
+   `src/shade/playground/bvh_repro/` — the standalone page where the `verify_*` functions get
+   registered and run against a real device (`npm run dev`, then
+   <http://localhost:5173/src/shade/playground/bvh_repro/index.html>).
+
+## Non-negotiable contracts
+
+**Output bytes** (every RT consumer depends on this; there is no versioning):
+- Node = 32 bytes: `[min.x, min.y, min.z, max.x, max.y, max.z] : f32` then `child_1 : u32`,
+  `child_2 : u32`.
+- Leaf ⇔ `child_1 == 0xFFFFFFFF` (`BVH_NULL_NODE`); then `child_2` = scene-database `meshes`
+  row. Internal ⇒ both children are valid node indices with meaningful bounds.
+- TLAS buffer = `u32 root` at byte 0, nodes from byte 4. Your layout: root is node 0
+  (Karras internal 0), internals `[0, N-2]`, leaves `[N-1, 2N-2]`. Still write the root word.
+- `N == 0` ⇒ write `root = BVH_NULL_NODE` host-side. `N == 1` ⇒ single leaf as node 0, root 0.
+
+**House rules:**
+- **Subgroups are a baseline engine requirement.** Use them wherever they pay. But do not bake
+  wave-*width* assumptions into algorithm structure — subgroup size is a runtime value 4–128;
+  workgroup memory is the correctness layer across subgroup boundaries.
+- **CSDLDF discipline:** no unbounded cross-workgroup waiting, ever. Bounded spin + fallback
+  (the csdldf shader) or no spin at all (arrival counters where the loser exits — the refit).
+  All cross-workgroup-communicated state goes through `array<atomic<u32>>` accesses exclusively.
+- **A vitest spec may never stand up a real GPU device.** Shade specs run under vitest
+  (`npm test`); the four validation tiers of plan §4.5 are all mandatory.
+- Match existing code style exactly: `assert.*` guards on public entry points, `#private`
+  fields, `chunk_*`/`shader_*`/`graph_*` naming, `CodeChunk.from(wgsl, [deps])` composition,
+  `ShaderResourceSetDescriptor` for bindings, JSDoc in the house voice. Read neighbours, write
+  like them.
+- Commit directly to `master`, conventional style with scope (`feat(shade): …`), incremental —
+  one commit per milestone below is about right. Do not amend, do not branch.
+
+## Milestones, in order
+
+**M1 — the sort.** `src/shade/renderer/gpu_primitive/sort/`:
+`graph_radix_sort({graph, keys, values, element_count}) → {keys, values}` — u32 keys + u32
+values, ascending, stable, result back in the caller's buffers. Reduce-then-scan LSD, 8-bit
+digits × 4 passes; per pass: (a) per-tile 256-bin histogram; (b) spine scan through
+`graph_prefix_scan_csdldf` **reused as-is** — adopt its `{count: u32, elements: array<vec4u>}`
+16-byte-aligned layout, write the count word host-side or in the histogram pass, size with
+`element_max_count = tiles × 256`, flatten column-major (bin-major) so one scan yields global
+digit offsets and per-tile offsets together; (c) rank-and-scatter. The scan is **in-place and
+inclusive-only**: the scatter recomputes its own tile's local histogram and ranks in workgroup
+memory anyway (it must, for stability), so the global exclusive offset is
+`spine_value − own_tile_count` — do not try to preserve pre-scan counts. Include a
+`warn_limited` guard on workgroup counts like the scan has. Definition of done: WGSL validity
+spec green; chunk-level emulator specs for the pure helpers (digit extraction, rank math);
+a `SoftwareGPUDevice` spec asserting the encoded dispatch sequence; a browser
+`verify_radix_sort.js` (template in history) registered in the playground; `npm test` green.
+
+**M2 — morton + emission chunks.** New `chunk_v3_morton_encode` in
+`src/shade/renderer/shader/chunk/bvh/morton/` composing the existing
+`shader/chunk/binary/chunk_split_by_3.js` as `split_by_3(x) | split_by_3(y)<<1 | split_by_3(z)<<2`
+— bit-exact with `src/core/geom/3d/morton/v3_morton_encode_magicbits.js`. The emission logic
+(`delta`, `determine_range`, `find_split`) goes into separate `chunk_bvh_*` files under
+`gpu_primitive/bvh/` so tier-2 tests can execute each function directly against its CPU
+counterpart (`Math.clz32` ⇔ `countLeadingZeros`). DoD: emulator specs proving bit-parity on
+randomized inputs **salted with duplicate-key runs**.
+
+**M3 — builder shaders + recorder.** In `gpu_primitive/bvh/`: `shader_bvh_morton`,
+`shader_bvh_emit_hierarchy`, `shader_bvh_refit`, plus `graph_bvh_build_lbvh({graph, leaf_bounds,
+leaf_payload, element_count, nodes, root…})` per plan §4.2 (pass table) and §4.3 (layout,
+transient sizing). The scene-aware extraction shader (`shader_bvh_extract_instance_leaves`,
+reads the rows list + `meshes` table, subgroup pre-reduce → workgroup reduce →
+`chunk_aabb_atomic_f32` merge into the scene-bounds cell) lives with the scene code in
+`src/shade/renderer/scene/`, not in the primitive (plan AR10). Emission: thread `i` writes leaf
+`(N-1)+i` from `leaf_bounds[values[i]]` / `leaf_payload[values[i]]`; threads `i < N-1` also emit
+internal `i` and write `parents[]` for both children; write `parents[0] = NULL_NODE`. Refit: one
+thread per leaf climbs `parents`, `atomicAdd` arrival counter per internal node, first arrival
+exits, second recomputes bounds; bind the node buffer as flat `array<atomic<u32>>` in this pass.
+DoD: WGSL validity for all; emulator executes morton + emission kernels end-to-end point-wise
+against the CPU oracle (they are pure — keep them barrier/atomic-free); refit gets validity +
+tier 3/4 only.
+
+**M4 — integration.** `GPUInstancesAccelerationStructure`: keep the CPU dynamic tree and all
+`instance_*` methods untouched (CPU consumers query `tlas.bvh` — see
+`DirectionalLightShadowmap`); add a compact live-rows `Uint32Array` mirror + persistent GPU
+buffer re-uploaded only on membership churn; `push_to_gpu()` gains the GPU path — grow the
+output buffer via `ensure_buffer_capacity` to `4 + 32·(2N−1)`, build a `FrameGraph`, import
+rows/scene-database/output, record extraction + `graph_bvh_build_lbvh`, encode + submit via
+`ShadeGPUCommandContext` (the `test_prefix_sum.js` idiom); handle N ∈ {0, 1} host-side. The GPU
+path is the default; the legacy CPU path (treelet + flatten + upload, verbatim, treelet call
+included) stays behind a module flag `USE_GPU_TLAS_BUILD` for A/B only. `GPUSceneContext` and
+all consumers: zero changes. DoD: a `SoftwareGPUDevice` orchestration spec asserting dispatch
+sequence, bindings resolving to the right buffers, transient sizes/clears, rows upload only on
+churn, and the N=0/1 short-circuits (host-written bytes only — the mock runs no shaders).
+
+**M5 — locking specs + verify harness.** `bvh_format.spec.js` pinning the §2.1 byte contract
+for BOTH the legacy compressor and the GPU layout against the same golden bytes.
+`verify_gpu_bvh_build.js` in the playground "review checks": randomized instance sets
+(duplicates, degenerate AABBs, N ∈ {0,1,2,3, 2^k±1, ~100k}), readback, assert structural
+validity (every leaf exactly once, both children valid, parent AABB ⊇ children, root word),
+payload permutation, **depth histogram**, SAH cost vs the CPU oracle fed the same sorted order
+(topology must match node-for-node modulo the index mapping). Wire `GPUTimer` numbers for the
+build via `encoder.enable_debug_timers` (the `timer` param on `graph_compute_pass` is silently
+dropped — known quirk, don't use it).
+
+**M6 — hand back.** You cannot run the browser playground (meep is a library; the host repo
+mounts it). When `npm test` is green and everything above is in place: update
+`GPU_BVH_BUILD_PLAN.md`'s status header (PLANNED → phase 1 landed, note any deviations), then
+stop and hand over with exact instructions for the human: which playground buttons to run
+(sort verify, BVH verify), and that path-tracer/RTX-shadows A/B via the flag is the final gate.
+**Never report browser-tier or on-device results you did not observe.**
+
+## Traps (each of these has already cost someone a day)
+
+- Duplicate morton codes: the index tiebreak must be in `delta`, and there must be **no**
+  midpoint-split special case. Test with long runs of identical keys.
+- Scene-bounds seeding: pool-cleared buffers are **zeroed**, and zero is not ±inf. Seed the
+  6-word cell with the ±inf u32 bit patterns (`0x7F800000` / `0xFF800000`) via a tiny init pass
+  or `writeBuffer`. In-shader accumulators can't const-fold `bitcast<f32>(0x7F800000u)` — use
+  `±3.4028234e38` there (see the meshlet bounds shader's comment).
+- Refit counters must be zero every build: declare the transient with
+  `BufferResourceDescriptor.from(size, usage, 0, size)` so pool-reused buffers get cleared
+  (fresh ones arrive zeroed already).
+- Tint uniformity: conditions guarding `workgroupBarrier` must derive from uniform builtins, not
+  `var<private>` copies; the deleted binning shader's `subgroup_size`/`sg_size` fix and manual
+  unrolls are the worked example. Use the `@diagnostic(off, subgroup_uniformity)` wrapper idiom
+  from the csdldf shader only where the analysis over-approximates, never to silence a real race.
+- The csdldf scan reads its element count from `data[0]` and dispatches indirectly; it is
+  inclusive-only and 16-byte-aligned — do not "fix" it, adapt to it.
+- `ensure_buffer_capacity` may return a **new** `GPUBuffer` (old one destroyed) — consumers are
+  safe because they read `tlas.buffer` per frame at execute time; just make sure the class field
+  is reassigned before the graph imports it.
+- WGSL `if (someU32)` is invalid (needs `!= 0`) — the old adaptive-morton chunks in
+  `shader/chunk/bvh/morton/` contain exactly this bug; they are dead code, do not import them.
+- `SOURCE_STRIDE = 10` (CPU node, words) vs `TARGET_STRIDE = 8` (GPU) — only relevant in the
+  legacy path and `bvh_format.spec.js`; don't confuse the two layouts.
+
+## Deviation protocol
+
+The plan was verified against the tree on 2026-08-26, but the tree moves. Where plan and code
+disagree, **the code wins** — verify, implement against reality, and record the deviation in the
+plan doc (one line, in place). If you hit a genuine design fork the plan doesn't cover (not a
+detail — a fork), stop and ask rather than inventing. Do not delete anything beyond what a
+milestone explicitly requires; the cleanup backlog (§8) is not phase-1 scope except where a
+milestone touches it. Pre-existing unrelated test failures: note them, don't fix them, don't
+let them block you.
+
+## Definition of done (phase 1)
+
+- [ ] Sort: all four tiers green, verify harness registered.
+- [ ] Builder: emulator parity with `ebvh_build_hierarchy_radix` (duplicates included), WGSL
+      validity everywhere, orchestration spec green.
+- [ ] Integration: GPU path default, legacy verbatim behind flag, consumers untouched,
+      `npm test` fully green.
+- [ ] `bvh_format.spec.js` + `verify_gpu_bvh_build.js` in place.
+- [ ] Plan doc status updated; hand-over message with the human's browser checklist.

package/src/shade/renderer/gpu_primitive/bvh/check_bvh_structure.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The two views of a node buffer a checker needs: the words as `u32`, and the same bytes as `f32`
+ * for the bounds.
+ *
+ * Normalises what a readback hands back, which is not necessarily a typed array — decoding a
+ * `WebGPUArray` through `read_gpu_typed_buffer` produces a plain JS `Array` of numbers. Building a
+ * `Float32Array` view straight off one of those silently yields an empty array (its `.buffer` is
+ * `undefined`), and every bounds read then comes back `undefined`, which reads as a broken tree
+ * rather than as a broken reader.
+ *
+ * @param {Uint32Array|number[]} tree node buffer as u32 words — `[root][node 0][node 1]...`
+ * @returns {{words: Uint32Array, floats: Float32Array}}
+ */
+export function bvh_tree_views(tree: Uint32Array | number[]): {
+    words: Uint32Array;
+    floats: Float32Array;
+};
+/**
+ * A node, read out of the buffer the way the traversal shaders read it.
+ *
+ * @param {Uint32Array} words
+ * @param {Float32Array} floats
+ * @param {number} node
+ * @returns {{child_1: number, child_2: number, low: number[], high: number[]}}
+ */
+export function read_bvh_node(words: Uint32Array, floats: Float32Array, node: number): {
+    child_1: number;
+    child_2: number;
+    low: number[];
+    high: number[];
+};
+/**
+ * Surface area of a box — the SAH's only ingredient.
+ *
+ * @param {number[]} low
+ * @param {number[]} high
+ * @returns {number}
+ */
+export function surface_area(low: number[], high: number[]): number;
+/**
+ * Everything a traversal consumer assumes about a tree, checked against the bytes that came back
+ * from the device — plus the two things the plan's risk register asks to be measured rather than
+ * assumed.
+ *
+ * Deliberately knows nothing about how the tree was built: it takes a node buffer and the set of
+ * payloads that should be in it. Both the primitive builder's harness and the TLAS's use it, and a
+ * later BLAS one can too.
+ *
+ * `problems` are correctness failures. `warnings` are quality signals — chiefly depth against the
+ * shared traversal stack, which is a real output constraint on an LBVH but not a broken tree.
+ *
+ * @param {Uint32Array|number[]} tree the whole node buffer, as words — `[root][node 0][node 1]...`
+ * @param {number} leaf_count
+ * @param {number[]|Uint32Array} expected_payloads the payload every leaf should carry, in any order
+ * @returns {{problems: string[], warnings: string[], depth_histogram: number[], max_depth: number, sah: number, leaf_node_of_payload: Map<number, number>, words: Uint32Array, floats: Float32Array}}
+ */
+export function check_bvh_structure(tree: Uint32Array | number[], leaf_count: number, expected_payloads: number[] | Uint32Array): {
+    problems: string[];
+    warnings: string[];
+    depth_histogram: number[];
+    max_depth: number;
+    sah: number;
+    leaf_node_of_payload: Map<number, number>;
+    words: Uint32Array;
+    floats: Float32Array;
+};
+/**
+ * The depth histogram as one line — `depth:leaves`, ascending.
+ *
+ * @param {number[]} depth_histogram
+ * @returns {string}
+ */
+export function format_depth_histogram(depth_histogram: number[]): string;
+/**
+ * @type {number}
+ */
+export const BVH_NULL_NODE: number;
+/**
+ * The traversal stack is shared between TLAS and BLAS within one query, and the occlusion variant's
+ * `(pointer & 31) != 0` loop condition *truncates* at overflow rather than erroring. A TLAS as deep
+ * as this leaves no room for any BLAS at all, so depth is a first-class output of any on-device
+ * check, not a curiosity.
+ *
+ * @see BVH_TRAVERSAL_STACK_SIZE
+ * @type {number}
+ */
+export const TRAVERSAL_STACK_SIZE: number;
+//# sourceMappingURL=check_bvh_structure.d.ts.map

package/src/shade/renderer/gpu_primitive/bvh/check_bvh_structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check_bvh_structure.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/check_bvh_structure.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;GAYG;AACH,qCAHW,WAAW,GAAC,MAAM,EAAE;WACV,WAAW;YAAU,YAAY;EASrD;AAED;;;;;;;GAOG;AACH,qCALW,WAAW,UACX,YAAY,QACZ,MAAM,GACJ;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAC,CAY7E;AAED;;;;;;GAMG;AACH,kCAJW,MAAM,EAAE,QACR,MAAM,EAAE,GACN,MAAM,CAQlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,0CALW,WAAW,GAAC,MAAM,EAAE,cACpB,MAAM,qBACN,MAAM,EAAE,GAAC,WAAW;cACP,MAAM,EAAE;cAAY,MAAM,EAAE;qBAAmB,MAAM,EAAE;eAAa,MAAM;SAAO,MAAM;0BAAwB,IAAI,MAAM,EAAE,MAAM,CAAC;WAAS,WAAW;YAAU,YAAY;EA2HnM;AAED;;;;;GAKG;AACH,wDAHW,MAAM,EAAE,GACN,MAAM,CAOlB;AAhOD;;GAEG;AACH,4BAFU,MAAM,CAEwB;AAExC;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEuB"}

package/src/shade/renderer/gpu_primitive/bvh/check_bvh_structure.js

@@ -0,0 +1,233 @@
+import {
+    BVH_HEADER_WORDS,
+    BVH_NODE_BOUNDS_WORD,
+    BVH_NODE_CHILD_1_WORD,
+    BVH_NODE_CHILD_2_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "./BVH_BUFFER_LAYOUT.js";
+
+/**
+ * @type {number}
+ */
+export const BVH_NULL_NODE = 0xffffffff;
+
+/**
+ * The traversal stack is shared between TLAS and BLAS within one query, and the occlusion variant's
+ * `(pointer & 31) != 0` loop condition *truncates* at overflow rather than erroring. A TLAS as deep
+ * as this leaves no room for any BLAS at all, so depth is a first-class output of any on-device
+ * check, not a curiosity.
+ *
+ * @see BVH_TRAVERSAL_STACK_SIZE
+ * @type {number}
+ */
+export const TRAVERSAL_STACK_SIZE = 32;
+
+/**
+ * The two views of a node buffer a checker needs: the words as `u32`, and the same bytes as `f32`
+ * for the bounds.
+ *
+ * Normalises what a readback hands back, which is not necessarily a typed array — decoding a
+ * `WebGPUArray` through `read_gpu_typed_buffer` produces a plain JS `Array` of numbers. Building a
+ * `Float32Array` view straight off one of those silently yields an empty array (its `.buffer` is
+ * `undefined`), and every bounds read then comes back `undefined`, which reads as a broken tree
+ * rather than as a broken reader.
+ *
+ * @param {Uint32Array|number[]} tree node buffer as u32 words — `[root][node 0][node 1]...`
+ * @returns {{words: Uint32Array, floats: Float32Array}}
+ */
+export function bvh_tree_views(tree) {
+    const words = tree instanceof Uint32Array ? tree : Uint32Array.from(tree);
+
+    return {
+        words,
+        floats: new Float32Array(words.buffer, words.byteOffset, words.length),
+    };
+}
+
+/**
+ * A node, read out of the buffer the way the traversal shaders read it.
+ *
+ * @param {Uint32Array} words
+ * @param {Float32Array} floats
+ * @param {number} node
+ * @returns {{child_1: number, child_2: number, low: number[], high: number[]}}
+ */
+export function read_bvh_node(words, floats, node) {
+    const base = BVH_HEADER_WORDS + node * BVH_NODE_STRIDE_WORDS;
+    const bounds = base + BVH_NODE_BOUNDS_WORD;
+
+    return {
+        child_1: words[base + BVH_NODE_CHILD_1_WORD],
+        child_2: words[base + BVH_NODE_CHILD_2_WORD],
+        low: [floats[bounds], floats[bounds + 1], floats[bounds + 2]],
+        high: [floats[bounds + 3], floats[bounds + 4], floats[bounds + 5]],
+    };
+}
+
+/**
+ * Surface area of a box — the SAH's only ingredient.
+ *
+ * @param {number[]} low
+ * @param {number[]} high
+ * @returns {number}
+ */
+export function surface_area(low, high) {
+    const dx = Math.max(0, high[0] - low[0]);
+    const dy = Math.max(0, high[1] - low[1]);
+    const dz = Math.max(0, high[2] - low[2]);
+
+    return 2 * (dx * dy + dy * dz + dz * dx);
+}
+
+/**
+ * Everything a traversal consumer assumes about a tree, checked against the bytes that came back
+ * from the device — plus the two things the plan's risk register asks to be measured rather than
+ * assumed.
+ *
+ * Deliberately knows nothing about how the tree was built: it takes a node buffer and the set of
+ * payloads that should be in it. Both the primitive builder's harness and the TLAS's use it, and a
+ * later BLAS one can too.
+ *
+ * `problems` are correctness failures. `warnings` are quality signals — chiefly depth against the
+ * shared traversal stack, which is a real output constraint on an LBVH but not a broken tree.
+ *
+ * @param {Uint32Array|number[]} tree the whole node buffer, as words — `[root][node 0][node 1]...`
+ * @param {number} leaf_count
+ * @param {number[]|Uint32Array} expected_payloads the payload every leaf should carry, in any order
+ * @returns {{problems: string[], warnings: string[], depth_histogram: number[], max_depth: number, sah: number, leaf_node_of_payload: Map<number, number>, words: Uint32Array, floats: Float32Array}}
+ */
+export function check_bvh_structure(tree, leaf_count, expected_payloads) {
+
+    const node_count = 2 * leaf_count - 1;
+
+    const problems = [];
+    const warnings = [];
+
+    const { words, floats } = bvh_tree_views(tree);
+
+    const root = words[0];
+
+    if (root !== 0) {
+        problems.push(`root word is ${root}, expected 0`);
+    }
+
+    const visited = new Uint8Array(node_count);
+    const leaf_node_of_payload = new Map();
+
+    const depth_histogram = [];
+
+    let max_depth = 0;
+    let sah = 0;
+
+    /** @type {[number, number][]} */
+    const stack = [[root, 1]];
+
+    let steps = 0;
+
+    while (stack.length > 0) {
+        const [node, depth] = stack.pop();
+
+        steps += 1;
+
+        if (steps > node_count * 2 + 8) {
+            problems.push('traversal did not terminate — the tree is not a tree');
+            break;
+        }
+
+        if (node >= node_count) {
+            problems.push(`node index ${node} is past the ${node_count} nodes this tree has`);
+            break;
+        }
+
+        if (visited[node] === 1) {
+            problems.push(`node ${node} is reachable twice — a shared node, not a tree`);
+            break;
+        }
+
+        visited[node] = 1;
+
+        const entry = read_bvh_node(words, floats, node);
+
+        for (const value of [...entry.low, ...entry.high]) {
+            if (!Number.isFinite(value)) {
+                problems.push(`node ${node} has a non-finite bound: ${value}`);
+                break;
+            }
+        }
+
+        if (entry.child_1 === BVH_NULL_NODE) {
+            max_depth = Math.max(max_depth, depth);
+            depth_histogram[depth] = (depth_histogram[depth] ?? 0) + 1;
+
+            if (leaf_node_of_payload.has(entry.child_2)) {
+                problems.push(`payload ${entry.child_2} appears on two leaves`);
+            }
+
+            leaf_node_of_payload.set(entry.child_2, node);
+
+            continue;
+        }
+
+        sah += surface_area(entry.low, entry.high);
+
+        // Both children are dereferenced before descending by the distance-ordered point queries,
+        // so both have to be real nodes with real bounds.
+        for (const child of [entry.child_1, entry.child_2]) {
+            if (child >= node_count) {
+                problems.push(`node ${node} names child ${child}, past the end of the tree`);
+                continue;
+            }
+
+            const child_entry = read_bvh_node(words, floats, child);
+
+            for (let axis = 0; axis < 3; axis++) {
+                if (child_entry.low[axis] < entry.low[axis] || child_entry.high[axis] > entry.high[axis]) {
+                    problems.push(
+                        `node ${node} does not contain child ${child} on axis ${axis}: `
+                        + `[${entry.low[axis]}, ${entry.high[axis]}] vs [${child_entry.low[axis]}, ${child_entry.high[axis]}]`
+                    );
+                    break;
+                }
+            }
+
+            stack.push([child, depth + 1]);
+        }
+    }
+
+    if (leaf_node_of_payload.size !== leaf_count) {
+        problems.push(`${leaf_node_of_payload.size} leaves reachable, expected ${leaf_count}`);
+    }
+
+    for (const payload of expected_payloads) {
+        if (!leaf_node_of_payload.has(payload)) {
+            problems.push(`payload ${payload} never appears in the tree`);
+            break;
+        }
+    }
+
+    if (max_depth > TRAVERSAL_STACK_SIZE) {
+        warnings.push(
+            `depth ${max_depth} exceeds the ${TRAVERSAL_STACK_SIZE}-entry traversal stack, which is `
+            + `SHARED with the BLAS in one query — the occlusion path truncates silently past it`
+        );
+    } else if (max_depth * 2 > TRAVERSAL_STACK_SIZE) {
+        warnings.push(
+            `depth ${max_depth} leaves ${TRAVERSAL_STACK_SIZE - max_depth} stack entries for the BLAS`
+        );
+    }
+
+    return { problems, warnings, depth_histogram, max_depth, sah, leaf_node_of_payload, words, floats };
+}
+
+/**
+ * The depth histogram as one line — `depth:leaves`, ascending.
+ *
+ * @param {number[]} depth_histogram
+ * @returns {string}
+ */
+export function format_depth_histogram(depth_histogram) {
+    return depth_histogram
+        .map((leaves, depth) => (leaves === undefined ? null : `${depth}:${leaves}`))
+        .filter(Boolean)
+        .join(' ');
+}

package/src/shade/renderer/gpu_primitive/bvh/chunk_bvh_delta.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Karras longest-common-prefix length between the Morton codes at `i` and `j`, transliterated from
+ * `delta` inside {@link ebvh_build_hierarchy_radix}.
+ *
+ * `-1` for a `j` outside `[0, n-1]` — the canonical Karras out-of-range sentinel, and the reason
+ * this returns `i32` rather than `u32`.
+ *
+ * The `32 + countLeadingZeros(i ^ j)` branch for identical codes is the duplicate-key tiebreak, and
+ * it is load-bearing rather than defensive: identical instance positions collide long before a
+ * 30-bit grid fills, and without a tiebreak an internal node's range can collapse to a single leaf,
+ * which is a tree the traversal cannot walk. `countLeadingZeros` is the exact counterpart of the
+ * oracle's `Math.clz32`, zero included (both answer 32).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_delta: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bvh_delta.d.ts.map

package/src/shade/renderer/gpu_primitive/bvh/chunk_bvh_delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bvh_delta.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/chunk_bvh_delta.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,8BAFU,SAAS,CAsBhB;0BArCuB,oCAAoC"}

package/src/shade/renderer/gpu_primitive/bvh/chunk_bvh_delta.js

@@ -0,0 +1,38 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Karras longest-common-prefix length between the Morton codes at `i` and `j`, transliterated from
+ * `delta` inside {@link ebvh_build_hierarchy_radix}.
+ *
+ * `-1` for a `j` outside `[0, n-1]` — the canonical Karras out-of-range sentinel, and the reason
+ * this returns `i32` rather than `u32`.
+ *
+ * The `32 + countLeadingZeros(i ^ j)` branch for identical codes is the duplicate-key tiebreak, and
+ * it is load-bearing rather than defensive: identical instance positions collide long before a
+ * 30-bit grid fills, and without a tiebreak an internal node's range can collapse to a single leaf,
+ * which is a tree the traversal cannot walk. `countLeadingZeros` is the exact counterpart of the
+ * oracle's `Math.clz32`, zero included (both answer 32).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_delta = CodeChunk.from(
+    //language=WGSL
+    `
+fn bvh_delta(codes: ptr<storage, array<u32>>, n: u32, i: u32, j: i32) -> i32 {
+    if (j < 0 || u32(j) >= n) {
+        return -1;
+    }
+
+    let other = u32(j);
+
+    let code_i = codes[i];
+    let code_j = codes[other];
+
+    if (code_i == code_j) {
+        // identical codes: break the tie by index, so every internal node still owns a >= 2-leaf range
+        return 32 + i32(countLeadingZeros(i ^ other));
+    }
+
+    return i32(countLeadingZeros(code_i ^ code_j));
+}
+`);

package/src/shade/renderer/gpu_primitive/bvh/chunk_bvh_determine_range.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `[first, last]` code range internal node `idx` covers — a transliteration of `determineRange`
+ * inside {@link ebvh_build_hierarchy_radix}: pick the direction the node grows in by comparing the
+ * prefixes shared with either neighbour, find an upper bound on its length by doubling, then binary
+ * search inside that bound.
+ *
+ * Node 0 is short-circuited to the whole array, as on the CPU, so callers do not special-case the
+ * root.
+ *
+ * Returned as `vec2<u32>(first, last)`; both ends are always valid leaf indices.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_determine_range: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bvh_determine_range.d.ts.map

package/src/shade/renderer/gpu_primitive/bvh/chunk_bvh_determine_range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bvh_determine_range.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/chunk_bvh_determine_range.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,wCAFU,SAAS,CAgEhB;0BA9EuB,oCAAoC"}