@woosh/meep-engine 3.60.4 → 3.60.6

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

@@ -1,202 +0,0 @@
-# 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/gpu_primitive/indirect/NOTES.md

@@ -1,94 +0,0 @@
-# `@builtin(num_workgroups)` in an indirect dispatch
-
-**Do not read `@builtin(num_workgroups)` in a shader dispatched with `dispatchWorkgroupsIndirect`**
-— which in this engine means `ComputeShader#dispatchIndirect` or `graph_compute_indirect_pass`. On
-D3D12 every such dispatch costs about 15 µs more than one that does not read it, and it costs that
-over an empty grid as much as over a full one. A *direct* dispatch pays nothing for the builtin.
-
-## What it costs
-
-One dispatch of a 128-wide shader in its own timed compute pass, the command written by a compute
-pass just before it, as the engine's builders do. RTX 4090, Chrome 154 on D3D12, median µs:
-
-| | 0 groups | 1 group | 4096 groups |
-|---|---:|---:|---:|
-| indirect, reads `num_workgroups` | 18.4 | 18.4 | 23.6 |
-| indirect, flattens with a constant stride | 3.1 | 4.1 | 7.2 |
-| indirect, reads the extents from the command buffer | 3.1 | 4.1 | 7.2 |
-| direct, either way | 0 | 1.0 | 4.1–5.1 |
-
-In the engine, the standard raster path ran seven such dispatches per view — the mesh-to-meshlet
-expansion twice, both meshlet filters, the three meshlet bucket passes — so every view, shadow views
-included, carried a fixed ~105 µs before it did any work. Removing the builtin from those seven
-(2026-09-25) took them, summed per view on `playground/mesh_row_ceiling?rows=200000`, from 157.7 /
-156.7 / 123.9 / 169.0 µs to 44.0 / 62.5 / 20.5 / 69.6 µs (three sun cascades and the main view; the
-third cascade is empty, so that column is the pure floor).
-
-## Why
-
-Read out of Dawn's source and confirmed by probe. Two separate things happen to an indirect
-dispatch, and only one of them is the builtin.
-
-1. **Every indirect dispatch is copied, whatever the shader reads.** With validation on, which is
-   how Chrome runs, `ComputePassEncoder::TransformIndirectDispatchBuffer` (Dawn's
-   `src/dawn/native/ComputePassEncoder.cpp`) inserts a one-thread compute pass that copies the three
-   counts into a scratch buffer and zeroes them if any is over `maxComputeWorkgroupsPerDimension`.
-   The real dispatch then reads the scratch buffer. This is why an over-limit indirect dispatch runs
-   nothing at all rather than failing (see `playground/mesh_row_ceiling/README.md`). It costs about
-   2 µs: `--enable-dawn-features=skip_validation` takes a plain indirect dispatch from 3.1 µs to
-   1.0 µs.
-
-2. **The builtin changes how the dispatch is issued.** HLSL has no `num_workgroups`, so Dawn's D3D12
-   backend passes it as a root constant. A direct dispatch sets that constant from the CPU, which is
-   free. For an indirect dispatch the counts only exist on the GPU, so the validation pass writes
-   them twice (`duplicateNumWorkgroups`), and the dispatch goes through `ExecuteIndirect` with a
-   command signature that sets the root constants ahead of the dispatch
-   (`ComputePipeline::GetDispatchIndirectCommandSignature` →
-   `GetDispatchIndirectCommandSignatureWithNumWorkgroups`, in `src/dawn/native/d3d12/`). The
-   pipeline gets that signature whenever its shader uses the builtin (`UsesNumWorkgroups`).
-
-**The ~15 µs is the command signature, not the copy.** With validation off the plain dispatch
-drops to 1.0 µs, but the `num_workgroups` dispatch stays at 18.4, where the copy survives only to
-duplicate the counts. Three more words written cannot cost 15 µs.
-
-Dawn duplicates the counts only on D3D12: the base `ShouldDuplicateNumWorkgroupsForDispatchIndirect`
-returns false, so Vulkan and Metal should not pay this. Not measured there.
-
-## What to do instead
-
-- **A folded command** — from `build_indirect_compute_dispatch_command` with `fold`, or from
-  `shader_prefix_sum_to_command` — flattens with
-  `renderer/shader/chunk/grid/chunk_folded_workgroup_index.js`. Both builders fill x to
-  `WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION` before y grows, and y before z, so the
-  grid flattens with that constant as its stride. `folded_dispatch_width.spec.js` holds the two
-  builders to the same command.
-- **Any other shader that needs its extents** can read them from the command buffer, bound
-  read-only in the same dispatch that uses it as INDIRECT. WebGPU allows it, since both are
-  read-only usages in one usage scope, and it measured the same as a constant stride.
-- **A direct dispatch** may read `num_workgroups` freely.
-
-## Still paying, as of 2026-09-25
-
-These still read the builtin and are dispatched indirectly. They are correct, just 15 µs a dispatch
-dearer than they need to be:
-
-- `renderer/particles/shaders/shader_particle_emit.js`, `shader_particle_init_free_list.js`
-- `renderer/rasterize/bucket/shader_count_meshlets_by_material.js`, `shader_sort_meshlets_by_material.js`
-- `renderer/rasterize/native/avboit/shader_avboit_occupancy.js`
-- `renderer/rasterize/cull/hzb/shader_hzb_meshlet_filter_1way_full.js` (no live caller)
-
-The texture encoders also read it, but they dispatch directly, so they pay nothing.
-
-## Measuring a pass like this
-
-- **Time one dispatch per compute pass.** Rotate the order of the arms every round, and write each
-  command with a compute pass just before its dispatch, not with `writeBuffer`, so the buffer
-  transitions match the engine's.
-- **Separate the copy with `--enable-dawn-features=skip_validation`.** It removes Dawn's validation
-  copy from every dispatch that does not read `num_workgroups`.
-- **Check for other headless Chromes before trusting a run.** Other sessions benchmark on the same
-  GPU; start a run only after none has been up for a while, and discard any run one appears in.
-- **Compare heavy passes within a paired round.** At `mesh_row_ceiling?rows=2000000`, the main
-  view's 2-way filter and the mesh bucket sort each pick one of two modes per run, about 200 µs
-  apart, and hold it for the whole run. A pooled median across runs can read a mode flip as a
-  regression. Quote the p10, and attribute any regression with an arm that differs by one file.

package/src/shade/renderer/hiz/NOTES.md

@@ -1,3 +0,0 @@
-useful references:
-
-* https://github.com/GameTechDev/MaskedOcclusionCulling

package/src/shade/renderer/hiz/shader_hzb_reduce_mip0_clip.d.ts

@@ -1,8 +0,0 @@
-/**
- * Same as standard first mip reduction, but with a clipping region.
- * Primarily used for shadow maps where shadows are atlased into a single texture
- * @type {ComputeShader}
- */
-export const shader_hzb_reduce_mip0_clip: ComputeShader;
-import { ComputeShader } from "../shader/ComputeShader.js";
-//# sourceMappingURL=shader_hzb_reduce_mip0_clip.d.ts.map

package/src/shade/renderer/hiz/shader_hzb_reduce_mip0_clip.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"shader_hzb_reduce_mip0_clip.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/hiz/shader_hzb_reduce_mip0_clip.js"],"names":[],"mappings":"AAqGA;;;;GAIG;AACH,0CAFU,aAAa,CAMpB;8BA3G2B,4BAA4B"}

package/src/shade/renderer/light/cluster/NOTES.md

@@ -1,11 +0,0 @@
-* Cull lights
-    * frustum
-    * depth (hzb)
-* Classify lights by cluster
-    * `cluster ID` + `light ID`
-* count number of lights per cluster using atomics(?)
-* second pass on classified lights to bin them
-
-Extra literature to check:
-
-* https://wickedengine.net/2019/02/thoughts-on-light-culling-stream-compaction-vs-flat-bit-arrays/