@woosh/meep-engine 3.35.0 → 3.37.0

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

@@ -1,201 +1,202 @@
-# 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 GPU timings for the build via
-`encoder.enable_profiling` and a `GPUFrameRecorder` (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.
+# 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` +
+   `src/shade/renderer/shader/chunk/atomic/chunk_atomic_min_f32_storage.js` /
+   `chunk_atomic_max_f32_storage.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_atomic_min_f32_storage` / `chunk_atomic_max_f32_storage` 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 GPU timings for the build via
+`encoder.enable_profiling` and a `GPUFrameRecorder` (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/light/environment/chunk_roughness_to_mip_ratio.js

@@ -0,0 +1,24 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { SPHERE_PROBE_MIP_MAX_ROUGHNESS } from "./DEFINES.js";
+
+/**
+ * Input roughness is linear (blender calls it "UI roughness")
+ * @see https://projects.blender.org/blender/blender/src/commit/866ef5b468589587395b1ee7480ea75b4c0fbc26/source/blender/draw/engines/eevee_next/shaders/eevee_lightprobe_sphere_mapping_lib.glsl#L102
+ * @type {CodeChunk}
+ */
+export const chunk_roughness_to_mip_ratio = CodeChunk.from(
+//language=WGSL
+    `
+fn roughness_to_mip_ratio(roughness: f32) -> f32 {
+  /* From "Moving Frostbite to Physically Based Rendering 3.0" eq 53. */
+  let ratio = saturate( roughness / ${SPHERE_PROBE_MIP_MAX_ROUGHNESS} );
+  
+  let ratio_sqrt = sqrt(ratio);
+  
+  /* Mix with linear to avoid mip 1 being too sharp. */
+  let mip_ratio = mix(ratio, ratio_sqrt, 0.4);
+  
+  return mip_ratio;
+}
+    `, []
+);

package/src/shade/renderer/light/environment/chunk_sphere_probe_roughness_to_lod.js

@@ -1,29 +1,6 @@
-import { chunk_fast_sqrt } from "../../shader/chunk/math/fast/chunk_fast_sqrt.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { SPHERE_PROBE_MIP_MAX_ROUGHNESS, SPHERE_PROBE_MIPMAP_LEVELS } from "./DEFINES.js";
-
-/**
- * Input roughness is linear (blender calls it "UI roughness")
- * @see https://projects.blender.org/blender/blender/src/commit/866ef5b468589587395b1ee7480ea75b4c0fbc26/source/blender/draw/engines/eevee_next/shaders/eevee_lightprobe_sphere_mapping_lib.glsl#L102
- * @type {CodeChunk}
- */
-export const chunk_roughness_to_mip_ratio = CodeChunk.from(
-//language=WGSL
-    `
-fn roughness_to_mip_ratio(roughness: f32) -> f32 {
-  /* From "Moving Frostbite to Physically Based Rendering 3.0" eq 53. */
-  let ratio = saturate( roughness / ${SPHERE_PROBE_MIP_MAX_ROUGHNESS} );
-  
-  let ratio_sqrt = sqrt(ratio);
-  
-  /* Mix with linear to avoid mip 1 being too sharp. */
-  let mip_ratio = mix(ratio, ratio_sqrt, 0.4);
-  
-  return mip_ratio;
-}
-    `, [
-    ]
-);
+import { chunk_roughness_to_mip_ratio } from "./chunk_roughness_to_mip_ratio.js";
+import { SPHERE_PROBE_MIPMAP_LEVELS } from "./DEFINES.js";
 
 /**
  * Input roughness is linear (blender calls it "UI roughness")

package/src/shade/renderer/light/environment/shader_project_environment_sh.d.ts

@@ -10,8 +10,8 @@
 export const ENVIRONMENT_SH_TYPE: WebGPUArray;
 /**
  * Directions the projection samples, spread evenly over the sphere (`sphere_fibonacci_point`).
- * The field is the environment at the roughness diffuse reads it at, so this is far more than its
- * two bands can hold, and it costs nothing that recurs: the pass runs when the environment changes.
+ * The field is already prefiltered at the roughness diffuse reads it at; these samples project
+ * that smooth field into two bands. The pass runs only when the environment changes.
  *
  * @type {number}
  */

package/src/shade/renderer/light/environment/shader_project_environment_sh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_project_environment_sh.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/shader_project_environment_sh.js"],"names":[],"mappings":"AAUA;;;;;;;;GAQG;AACH,kCAFU,WAAW,CAEyC;AAE9D;;;;;;GAMG;AACH,0CAFU,MAAM,CAEgC;AAyDhD;;;;;;;;;;;;;;GAcG;AACH,4CAFU,aAAa,CAMpB;4BAjGyB,kCAAkC;8BAFhC,+BAA+B"}
+{"version":3,"file":"shader_project_environment_sh.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/shader_project_environment_sh.js"],"names":[],"mappings":"AAWA;;;;;;;;GAQG;AACH,kCAFU,WAAW,CAEyC;AAE9D;;;;;;GAMG;AACH,0CAFU,MAAM,CAE+B;AAuF/C;;;;;;;;;;;;;;GAcG;AACH,4CAFU,aAAa,CAMpB;4BA/HyB,kCAAkC;8BAFhC,+BAA+B"}