@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.d.ts

@@ -1,8 +1,12 @@
 export class GPUGeometryMeshletsBVH {
     /**
-     * @type {ArrayBuffer}
+     * The tree's bytes as they were copied into the arena, once they have been. Not taken at
+     * registration: a geometry may be registered before its tree exists, and the upload reads the
+     * geometry's tree when it runs, so a tree that arrives late is uploaded late rather than never.
+     *
+     * @type {ArrayBuffer|undefined}
      */
-    bvh: ArrayBuffer;
+    bvh: ArrayBuffer | undefined;
     /**
      * Node index this tree's root sits at within the manager's arena. Not a byte offset — the
      * traversal shaders index `blas_data` by node.
@@ -25,6 +29,15 @@ export class GPUGeometryMeshletsBVH {
      * @type {boolean}
      */
     resident: boolean;
+    /**
+     * Bytes of {@link bvh} that {@link GPUGeometryBVHManager#update} actually copied into the arena
+     * at {@link address}. `get_refit_target` holds it against the shape's node count: a record
+     * registered before its geometry had a tree is uploaded as nothing, and a shape derived later,
+     * from the bytes that exist by then, must not be answered for at that empty region.
+     *
+     * @type {number}
+     */
+    uploaded_byte_length: number;
     /**
      * Set when the geometry has been removed. A record can still sit in the manager's update
      * queue when it is removed in the same frame it was registered; the update pass skips

package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryMeshletsBVH.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.js"],"names":[],"mappings":"AAAA;IAEI;;OAEG;IACH,KAFU,WAAW,CAEjB;IAEJ;;;;;OAKG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,UAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;OAKG;IACH,UAFU,OAAO,CAEA;CACpB"}
+{"version":3,"file":"GPUGeometryMeshletsBVH.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.js"],"names":[],"mappings":"AAAA;IAEI;;;;;;OAMG;IACH,KAFU,WAAW,GAAC,SAAS,CAE3B;IAEJ;;;;;OAKG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,UAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,sBAFU,MAAM,CAES;IAEzB;;;;;OAKG;IACH,UAFU,OAAO,CAEA;CACpB"}

package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.js

@@ -1,7 +1,11 @@
 export class GPUGeometryMeshletsBVH {
 
     /**
-     * @type {ArrayBuffer}
+     * The tree's bytes as they were copied into the arena, once they have been. Not taken at
+     * registration: a geometry may be registered before its tree exists, and the upload reads the
+     * geometry's tree when it runs, so a tree that arrives late is uploaded late rather than never.
+     *
+     * @type {ArrayBuffer|undefined}
      */
     bvh;
 
@@ -30,6 +34,16 @@ export class GPUGeometryMeshletsBVH {
      */
     resident = false;
 
+    /**
+     * Bytes of {@link bvh} that {@link GPUGeometryBVHManager#update} actually copied into the arena
+     * at {@link address}. `get_refit_target` holds it against the shape's node count: a record
+     * registered before its geometry had a tree is uploaded as nothing, and a shape derived later,
+     * from the bytes that exist by then, must not be answered for at that empty region.
+     *
+     * @type {number}
+     */
+    uploaded_byte_length = 0;
+
     /**
      * Set when the geometry has been removed. A record can still sit in the manager's update
      * queue when it is removed in the same frame it was registered; the update pass skips

package/src/shade/renderer/geometry/bvh/shader_blas_refit_batch.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Leaves per workgroup. A workgroup serves one tree and one aligned run of this many of its leaves,
+ * which is what the lookup's `leaf_base` counts in.
+ *
+ * @type {number}
+ */
+export const BLAS_REFIT_BATCH_WORKGROUP_SIZE: number;
+/**
+ * Refit every tree in a batch, from one dispatch.
+ *
+ * One lane per leaf, across every tree the batch lists: the lane finds its tree and its leaf through
+ * the workgroup lookup, rewrites that leaf's box from the triangle it names as the vertex buffer
+ * holds it *now*, and climbs — {@link chunk_bvh_refit_climb}, the same arrival-counter climb the
+ * LBVH build ends with, at this tree's positions in the shared arenas. Topology is untouched:
+ * nothing is sorted, nothing is emitted, no node's children change.
+ *
+ * Batched rather than per tree because a refit's cost is not the refit. A tree's climb is a chain
+ * of dependent atomics as long as the tree is deep, with half the live lanes exiting at every
+ * level; on its own it is a long tail of a nearly idle GPU, and a dispatch per tree serialises
+ * `N` such tails behind `2N` pass boundaries. In one dispatch a small tree's climb overlaps the
+ * next tree's, and the command count is the same for one skinned mesh as for three hundred.
+ *
+ * Fused rather than two passes: the leaf box is stored through the same atomic words the climb
+ * reads, before the lane's first arrival, so the handshake that makes an internal node's box
+ * visible to the second arrival at its parent makes a leaf's visible the same way. That is the
+ * builder plan's R1 assumption made one level lower, not a new one — and one pass boundary, one
+ * barrier and one re-read of every leaf box fewer.
+ *
+ * For a skinned mesh this runs against the per-instance clone, after the skinning pass has deformed
+ * its vertex region; `geometry_index` on the row is the clone's, and reading the source instead
+ * would produce the rest pose.
+ *
+ * Recorded by {@link GPUBLASRefitBatch}, which builds the tables and paginates the dispatch.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_blas_refit_batch: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_blas_refit_batch.d.ts.map

package/src/shade/renderer/geometry/bvh/shader_blas_refit_batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_blas_refit_batch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/shader_blas_refit_batch.js"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,8CAFU,MAAM,CAEkC;AA+ElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,sCAFU,aAAa,CAMpB;8BAlI2B,+BAA+B"}

package/src/shade/renderer/geometry/bvh/shader_blas_refit_batch.js

@@ -0,0 +1,134 @@
+import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { BVH_NODE_LAYOUT_DEFINITION } from "../../gpu_primitive/bvh/BVH_NODE_LAYOUT_DEFINITION.js";
+import { chunk_bvh_refit_climb } from "../../gpu_primitive/bvh/chunk_bvh_refit_climb.js";
+import {
+    chunk_geometry_read_triangle_bounds
+} from "../../shader/chunk/geometry/format/chunk_geometry_read_triangle_bounds.js";
+import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
+import { GEOMETRY_METADATA_STRUCT } from "../GEOMETRY_METADATA_STRUCT.js";
+import { MESHLET_METADATA_STRUCT } from "../meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { BLAS_REFIT_TARGET_STRUCT } from "./BLAS_REFIT_TARGET_STRUCT.js";
+
+/**
+ * Leaves per workgroup. A workgroup serves one tree and one aligned run of this many of its leaves,
+ * which is what the lookup's `leaf_base` counts in.
+ *
+ * @type {number}
+ */
+export const BLAS_REFIT_BATCH_WORKGROUP_SIZE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+
+// Workgroups already covered by earlier sub-dispatches of the same batch, for a batch larger than
+// the device's per-dimension cap. Four bytes, per dispatch: immediate data.
+resources.setImmediate("dispatch_offset", u32);
+
+resources.createGroup()
+    // one row per tree in the batch — where it lives, and where its counters live
+    .addStorageBuffer("targets", WebGPUArray.from(BLAS_REFIT_TARGET_STRUCT), false)
+    // `(target_index, leaf_base)` per workgroup, flat
+    .addStorageBuffer("lookup", WebGPUArray.from(u32), false)
+    // node index of each leaf ordinal, per tree, at the tree's `leaf_nodes_offset`
+    .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
+    // parent of every node, per tree, at the tree's `parents_offset`
+    .addStorageBuffer("parents", WebGPUArray.from(u32), false)
+    // one arrival counter per node slot of every tree, at each tree's `counters_offset`; zero at
+    // the start of every batch
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
+    // The node arena, flat and atomic. Every word this kernel writes is communicated between
+    // workgroups — a leaf box to the second arrival at its parent, a node box to the next — so every
+    // access to it is an atomic one, the discipline the builder plan's R1 rests on.
+    .addStorageBuffer("nodes", WebGPUArray.from(atomic_u32), true)
+    .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);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${BLAS_REFIT_BATCH_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg: vec3<u32>,
+    @builtin(local_invocation_id) lid: vec3<u32>,
+) {
+    // Which tree, and which run of its leaves: one lookup pair per workgroup, so the row read below
+    // is uniform across the workgroup and the leaf list read is one contiguous run.
+    let pair = (wg.x + dispatch_offset) * 2u;
+
+    // ("target" is a reserved word in WGSL)
+    let tree = targets[lookup[pair]];
+
+    let leaf = lookup[pair + 1u] + lid.x;
+
+    if (leaf >= tree.leaf_count) {
+        // the tail of a tree's last run; the next workgroup is another tree's
+        return;
+    }
+
+    let leaf_node = leaf_nodes[tree.leaf_nodes_offset + leaf];
+
+    let leaf_word = tree.node_word_offset + leaf_node * BVH_NODE_STRIDE;
+
+    // The leaf already says which triangle it holds — its payload is what the ray query hands to
+    // the triangle test. Reading it back means no side table has to agree with the tree about
+    // which leaf is which.
+    let payload = atomicLoad(&nodes[leaf_word + BVH_NODE_CHILD_2]);
+
+    let box = geometry_read_triangle_bounds(geometries[tree.geometry_index], payload);
+
+    // This leaf's box, then the climb from it. The box is written before this lane's first arrival
+    // at the parent, through the same atomic words the climb reads every other box through, so the
+    // second arrival at the parent finds it exactly as it finds an internal node's.
+    bvh_node_store_bounds(leaf_word, box.min, box.max);
+
+    bvh_refit_climb(
+        tree.node_word_offset,
+        tree.parents_offset,
+        tree.counters_offset,
+        leaf_node
+    );
+}
+`, [
+    BVH_NODE_LAYOUT_DEFINITION,
+    chunk_bvh_refit_climb,
+    chunk_geometry_read_triangle_bounds,
+]);
+
+/**
+ * Refit every tree in a batch, from one dispatch.
+ *
+ * One lane per leaf, across every tree the batch lists: the lane finds its tree and its leaf through
+ * the workgroup lookup, rewrites that leaf's box from the triangle it names as the vertex buffer
+ * holds it *now*, and climbs — {@link chunk_bvh_refit_climb}, the same arrival-counter climb the
+ * LBVH build ends with, at this tree's positions in the shared arenas. Topology is untouched:
+ * nothing is sorted, nothing is emitted, no node's children change.
+ *
+ * Batched rather than per tree because a refit's cost is not the refit. A tree's climb is a chain
+ * of dependent atomics as long as the tree is deep, with half the live lanes exiting at every
+ * level; on its own it is a long tail of a nearly idle GPU, and a dispatch per tree serialises
+ * `N` such tails behind `2N` pass boundaries. In one dispatch a small tree's climb overlaps the
+ * next tree's, and the command count is the same for one skinned mesh as for three hundred.
+ *
+ * Fused rather than two passes: the leaf box is stored through the same atomic words the climb
+ * reads, before the lane's first arrival, so the handshake that makes an internal node's box
+ * visible to the second arrival at its parent makes a leaf's visible the same way. That is the
+ * builder plan's R1 assumption made one level lower, not a new one — and one pass boundary, one
+ * barrier and one re-read of every leaf box fewer.
+ *
+ * For a skinned mesh this runs against the per-instance clone, after the skinning pass has deformed
+ * its vertex region; `geometry_index` on the row is the clone's, and reading the source instead
+ * would produce the rest pose.
+ *
+ * Recorded by {@link GPUBLASRefitBatch}, which builds the tables and paginates the dispatch.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_blas_refit_batch = ComputeShader.from({
+    label: "BLAS/RefitBatch",
+    resources,
+    body,
+});

package/src/shade/renderer/geometry/virtual/build/gltf/gltf_collect_geometries.js

@@ -2,11 +2,11 @@ import { assert } from "../../../../../../core/assert.js";
 import {
     GLTF_PRIMITIVE_MODE,
     GLTF_PRIMITIVE_MODE_DEFAULT,
-} from "../../../../loader/gltf/GLTF_PRIMITIVE_MODE.js";
+} from "../../../../../../format/scene/gltf/GLTF_PRIMITIVE_MODE.js";
 import {
     GLTF_GEOMETRY_EXTENSIONS
-} from "../../../../loader/gltf/ext/gltf_geometry_extensions.js";
-import { gltf_node_world_matrices } from "../../../../loader/gltf/gltf_node_world_matrices.js";
+} from "../../../../../../format/scene/gltf/ext/gltf_geometry_extensions.js";
+import { gltf_node_world_matrices } from "../../../../../../format/scene/gltf/gltf_node_world_matrices.js";
 import { GltfCollectReport } from "./GltfCollectReport.js";
 import { GltfGeometry } from "./GltfGeometry.js";
 import { GltfGeometryInstance } from "./GltfGeometryInstance.js";

package/src/shade/renderer/geometry/virtual/build/gltf/gltf_open_document.js

@@ -1,14 +1,14 @@
 import { assert } from "../../../../../../core/assert.js";
 import {
     GLTF_BUFFER_VIEW_EXTENSIONS
-} from "../../../../loader/gltf/ext/gltf_buffer_view_extensions.js";
+} from "../../../../../../format/scene/gltf/ext/gltf_buffer_view_extensions.js";
 import {
     gltf_undecodable_geometry_extensions
-} from "../../../../loader/gltf/ext/gltf_geometry_extensions.js";
+} from "../../../../../../format/scene/gltf/ext/gltf_geometry_extensions.js";
 import {
     gltf_read_container_layout,
     gltf_require_supported_version,
-} from "../../../../loader/gltf/gltf_parse_container.js";
+} from "../../../../../../format/scene/gltf/gltf_parse_container.js";
 import { GltfByteSource } from "./GltfByteSource.js";
 import { GltfDocument } from "./GltfDocument.js";
 

package/src/shade/renderer/geometry/virtual/build/gltf/gltf_read_geometry.js

@@ -4,7 +4,7 @@ import { AttributeSpec } from "../../../../../../engine/graphics/geometry/Attrib
 import {
     gltf_accessor_to_float32,
     gltf_read_accessor,
-} from "../../../../loader/gltf/gltf_read_accessor.js";
+} from "../../../../../../format/scene/gltf/gltf_read_accessor.js";
 import { Attribute } from "../../../Attribute.js";
 import { Geometry } from "../../../Geometry.js";
 import { vgeo_attribute_allocate } from "../../format/attribute/vgeo_attribute_allocate.js";

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

@@ -0,0 +1,17 @@
+/**
+ * The node layout of {@link BVH_BUFFER_LAYOUT}, as WGSL constants, for kernels that address a node
+ * buffer as flat words rather than as typed structs.
+ *
+ * One declaration shared by every chunk and kernel that climbs or writes nodes word-wise, so that a
+ * kernel importing two of them does not declare the same constant twice — a module-scope `const`
+ * declared twice is a WGSL error. Prefixed for the same reason: several builder kernels still carry
+ * their own unprefixed `NODE_*` copies, and those must not collide with these.
+ *
+ * Generated from the struct rather than restated: `.pack()` and WGSL layout rules decide these
+ * offsets, and a literal here would be one struct edit away from writing nodes nothing can traverse.
+ *
+ * @type {CodeChunk}
+ */
+export const BVH_NODE_LAYOUT_DEFINITION: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=BVH_NODE_LAYOUT_DEFINITION.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BVH_NODE_LAYOUT_DEFINITION.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/BVH_NODE_LAYOUT_DEFINITION.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AACH,yCAFU,SAAS,CAShB;0BA7BuB,oCAAoC"}

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

@@ -0,0 +1,30 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import {
+    BVH_NODE_BOUNDS_WORD,
+    BVH_NODE_CHILD_1_WORD,
+    BVH_NODE_CHILD_2_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "./BVH_BUFFER_LAYOUT.js";
+
+/**
+ * The node layout of {@link BVH_BUFFER_LAYOUT}, as WGSL constants, for kernels that address a node
+ * buffer as flat words rather than as typed structs.
+ *
+ * One declaration shared by every chunk and kernel that climbs or writes nodes word-wise, so that a
+ * kernel importing two of them does not declare the same constant twice — a module-scope `const`
+ * declared twice is a WGSL error. Prefixed for the same reason: several builder kernels still carry
+ * their own unprefixed `NODE_*` copies, and those must not collide with these.
+ *
+ * Generated from the struct rather than restated: `.pack()` and WGSL layout rules decide these
+ * offsets, and a literal here would be one struct edit away from writing nodes nothing can traverse.
+ *
+ * @type {CodeChunk}
+ */
+export const BVH_NODE_LAYOUT_DEFINITION = CodeChunk.from(
+    //language=WGSL
+    `
+const BVH_NODE_STRIDE = ${BVH_NODE_STRIDE_WORDS}u;
+const BVH_NODE_BOUNDS = ${BVH_NODE_BOUNDS_WORD}u;
+const BVH_NODE_CHILD_1 = ${BVH_NODE_CHILD_1_WORD}u;
+const BVH_NODE_CHILD_2 = ${BVH_NODE_CHILD_2_WORD}u;
+`);

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

@@ -826,7 +826,8 @@ Two sub-phases, in value order:
   phase-1 refit pass unchanged. Four deviations, all recorded here because the code is what won:
 
   - **The extraction pass writes node bounds directly, not a `leaf_bounds` array.** A refit has no
-    sort and no emission, so nothing consumes a separate array — `shader_blas_refit_leaf_bounds`
+    sort and no emission, so nothing consumes a separate array — the refit kernel (originally
+    `shader_blas_refit_leaf_bounds`, now the leaf half of `shader_blas_refit_batch`)
     puts each triangle's box straight into the leaf node and the climb reads it there. It gets the
     triangle id by reading the leaf's own `child_2` payload back, so no side table has to agree
     with the tree about which leaf is which.
@@ -844,6 +845,12 @@ Two sub-phases, in value order:
     is a tenant in shared ones. Counters are sized by *node*, not by leaf — they are indexed by
     node id, and a tree read off an arena numbers its nodes with holes in.
 
+  - **[deviation] The refit is one batch per frame, not one per tree** (2026-09-02). The per-tree
+    recorder and its leaf kernel are gone. `GPUBLASRefitBatch` records `shader_blas_refit_batch`
+    once over every skinned clone, through a per-workgroup lookup and a residency version on the
+    BLAS manager, and the climb is shared with this builder's pass 4 as `chunk_bvh_refit_climb`.
+    Plan, adversarial review and commit ledger: `geometry/bvh/BLAS_REFIT_BATCH_PLAN.md`.
+
   Verified on an NVIDIA Lovelace device by `src/shade/playground/skinned_blas_refit/`, which holds
   the refit's root box against the bounds-refresh chain's independently computed box over the same
   deformed vertices — two paths sharing no code, and `min`/`max` do not round, so the bar is bit

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

@@ -0,0 +1,34 @@
+/**
+ * The bottom-up AABB refit climb, as a function a kernel calls once per leaf.
+ *
+ * Starting above `leaf_node`, the caller climbs the `parents` chain, taking an arrival counter at
+ * each internal node on the way. An internal node has exactly two children, so exactly two climbs
+ * pass through it. The first arrival exits — its sibling's subtree is still being fitted, and it
+ * has nothing to wait ON: no spin, no assumption about anyone else's forward progress. The second
+ * arrival finds both children written and owns the node from here up. That is the whole
+ * synchronisation, and it assumes atomic-word visibility rather than any scheduling fairness —
+ * which is why it sits on the accepted side of the engine's line on cross-workgroup communication.
+ *
+ * Every word this climb communicates between workgroups — bounds and counters — goes through
+ * atomic accesses only, never a plain load or store gated by an atomic: the strictest formulation
+ * WGSL offers, and the discipline the builder plan's R1 rests on.
+ *
+ * Three offsets, so one climb serves a tree that owns its arrays and a tree that is a tenant in
+ * somebody else's. `node_word_offset` is where node 0 starts in the bound node buffer, in words;
+ * `parents_offset` is where this tree's parents start in the bound parents array;
+ * `counters_offset` is where this tree's arrival counters start in the bound counters array. A
+ * build passes 0 for all three. A refit of a tree living in a shared arena passes its position in
+ * each — including the counters, when one buffer holds the counters of many trees at once.
+ *
+ * The counters must be zero when the climb starts, one per node of the tree: a leftover count lets
+ * a first arrival believe it is a second and fit a node from a sibling nothing has written yet.
+ *
+ * Assumes the module-scope bindings `parents` (`array<u32>`), `counters` (`array<atomic<u32>>`)
+ * and `nodes` (`array<atomic<u32>>`, the node buffer bound flat) — by name, the same way
+ * `read_meshlet_triangle_bounds` assumes `meshlet_metadata`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_refit_climb: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bvh_refit_climb.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bvh_refit_climb.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/chunk_bvh_refit_climb.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,oCAFU,SAAS,CAoEhB;0BArGuB,oCAAoC"}

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

@@ -0,0 +1,102 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { BVH_NULL_NODE_DEFINITION } from "../../shader/chunk/bvh/BVH_NULL_NODE_DEFINITION.js";
+import { BVH_NODE_LAYOUT_DEFINITION } from "./BVH_NODE_LAYOUT_DEFINITION.js";
+
+/**
+ * The bottom-up AABB refit climb, as a function a kernel calls once per leaf.
+ *
+ * Starting above `leaf_node`, the caller climbs the `parents` chain, taking an arrival counter at
+ * each internal node on the way. An internal node has exactly two children, so exactly two climbs
+ * pass through it. The first arrival exits — its sibling's subtree is still being fitted, and it
+ * has nothing to wait ON: no spin, no assumption about anyone else's forward progress. The second
+ * arrival finds both children written and owns the node from here up. That is the whole
+ * synchronisation, and it assumes atomic-word visibility rather than any scheduling fairness —
+ * which is why it sits on the accepted side of the engine's line on cross-workgroup communication.
+ *
+ * Every word this climb communicates between workgroups — bounds and counters — goes through
+ * atomic accesses only, never a plain load or store gated by an atomic: the strictest formulation
+ * WGSL offers, and the discipline the builder plan's R1 rests on.
+ *
+ * Three offsets, so one climb serves a tree that owns its arrays and a tree that is a tenant in
+ * somebody else's. `node_word_offset` is where node 0 starts in the bound node buffer, in words;
+ * `parents_offset` is where this tree's parents start in the bound parents array;
+ * `counters_offset` is where this tree's arrival counters start in the bound counters array. A
+ * build passes 0 for all three. A refit of a tree living in a shared arena passes its position in
+ * each — including the counters, when one buffer holds the counters of many trees at once.
+ *
+ * The counters must be zero when the climb starts, one per node of the tree: a leftover count lets
+ * a first arrival believe it is a second and fit a node from a sibling nothing has written yet.
+ *
+ * Assumes the module-scope bindings `parents` (`array<u32>`), `counters` (`array<atomic<u32>>`)
+ * and `nodes` (`array<atomic<u32>>`, the node buffer bound flat) — by name, the same way
+ * `read_meshlet_triangle_bounds` assumes `meshlet_metadata`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_refit_climb = CodeChunk.from(
+    //language=WGSL
+    `
+fn bvh_node_read_bounds_low(node_word: u32) -> vec3<f32> {
+    return vec3<f32>(
+        bitcast<f32>(atomicLoad(&nodes[node_word + BVH_NODE_BOUNDS])),
+        bitcast<f32>(atomicLoad(&nodes[node_word + BVH_NODE_BOUNDS + 1u])),
+        bitcast<f32>(atomicLoad(&nodes[node_word + BVH_NODE_BOUNDS + 2u])),
+    );
+}
+
+fn bvh_node_read_bounds_high(node_word: u32) -> vec3<f32> {
+    return vec3<f32>(
+        bitcast<f32>(atomicLoad(&nodes[node_word + BVH_NODE_BOUNDS + 3u])),
+        bitcast<f32>(atomicLoad(&nodes[node_word + BVH_NODE_BOUNDS + 4u])),
+        bitcast<f32>(atomicLoad(&nodes[node_word + BVH_NODE_BOUNDS + 5u])),
+    );
+}
+
+fn bvh_node_store_bounds(node_word: u32, low: vec3<f32>, high: vec3<f32>) {
+    atomicStore(&nodes[node_word + BVH_NODE_BOUNDS], bitcast<u32>(low.x));
+    atomicStore(&nodes[node_word + BVH_NODE_BOUNDS + 1u], bitcast<u32>(low.y));
+    atomicStore(&nodes[node_word + BVH_NODE_BOUNDS + 2u], bitcast<u32>(low.z));
+    atomicStore(&nodes[node_word + BVH_NODE_BOUNDS + 3u], bitcast<u32>(high.x));
+    atomicStore(&nodes[node_word + BVH_NODE_BOUNDS + 4u], bitcast<u32>(high.y));
+    atomicStore(&nodes[node_word + BVH_NODE_BOUNDS + 5u], bitcast<u32>(high.z));
+}
+
+fn bvh_refit_climb(node_word_offset: u32, parents_offset: u32, counters_offset: u32, leaf_node: u32) {
+    // Start above the leaf and climb. Which node that leaf is comes from the caller rather than
+    // from a layout this function assumes, so a tree that was built and a tree that was copied
+    // refit alike.
+    var node = parents[parents_offset + leaf_node];
+
+    loop {
+        if (node == BVH_NULL_NODE) {
+            // climbed past the root
+            break;
+        }
+
+        let arrivals = atomicAdd(&counters[counters_offset + node], 1u);
+
+        if (arrivals == 0u) {
+            // first arrival: the sibling subtree is still being fitted, and this is not a wait
+            break;
+        }
+
+        let node_word = node_word_offset + node * BVH_NODE_STRIDE;
+
+        let child_1 = atomicLoad(&nodes[node_word + BVH_NODE_CHILD_1]);
+        let child_2 = atomicLoad(&nodes[node_word + BVH_NODE_CHILD_2]);
+
+        let word_1 = node_word_offset + child_1 * BVH_NODE_STRIDE;
+        let word_2 = node_word_offset + child_2 * BVH_NODE_STRIDE;
+
+        let low = min(bvh_node_read_bounds_low(word_1), bvh_node_read_bounds_low(word_2));
+        let high = max(bvh_node_read_bounds_high(word_1), bvh_node_read_bounds_high(word_2));
+
+        bvh_node_store_bounds(node_word, low, high);
+
+        node = parents[parents_offset + node];
+    }
+}
+`, [
+    BVH_NULL_NODE_DEFINITION,
+    BVH_NODE_LAYOUT_DEFINITION,
+]);

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

@@ -3,19 +3,21 @@ export const BVH_REFIT_WORKGROUP_SIZE: 64;
  * Bottom-up AABB refit — pass 4 of {@link graph_bvh_build_lbvh}, and the last thing a build does.
  *
  * One thread per leaf climbs the `parents` chain from the node `leaf_nodes` says that leaf occupies,
- * taking an arrival counter at each internal node on the way. Nothing waits: the thread that arrives first at a node simply
- * dies, and the one that arrives second is guaranteed both children are complete, because the only
- * way to arrive is to have finished a child. That is the whole synchronisation, and it assumes
- * atomic-word visibility rather than any scheduling fairness — which is why it sits on the accepted
- * side of the engine's line on cross-workgroup communication.
+ * taking an arrival counter at each internal node on the way. Nothing waits: the thread that arrives
+ * first at a node simply dies, and the one that arrives second is guaranteed both children are
+ * complete, because the only way to arrive is to have finished a child. That is the whole
+ * synchronisation, and it assumes atomic-word visibility rather than any scheduling fairness — which
+ * is why it sits on the accepted side of the engine's line on cross-workgroup communication.
+ *
+ * The climb itself is {@link chunk_bvh_refit_climb}, shared with the batched per-frame BLAS refit,
+ * which runs the same climb over many trees from one dispatch. This kernel is the build's framing
+ * of it: one thread per leaf, settings from immediate data, counters of its own.
  *
  * The counters must be zero when the pass starts; the graph declares them with a clear range so a
  * pool-reused buffer is cleared and a fresh one arrives zeroed already.
  *
- * The same pass serves refit-only updates (topology frozen, leaf bounds rewritten) — which is what
- * per-frame skinned BLAS needs — so it exists as a standalone dispatch rather than fused into
- * emission. Node indices are local to the tree and `settings.node_word_offset` says where node 0
- * lands, so a BLAS living inside the shared geometry arena refits through this same kernel.
+ * Node indices are local to the tree and `settings.node_word_offset` says where node 0 lands, so a
+ * tree living inside a shared arena refits through this same kernel.
  *
  * @type {ComputeShader}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"shader_bvh_refit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_refit.js"],"names":[],"mappings":"AAcA,0CAA2C;AAwG3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,+BAFU,aAAa,CAMpB;8BA1I2B,+BAA+B"}
+{"version":3,"file":"shader_bvh_refit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_refit.js"],"names":[],"mappings":"AAQA,0CAA2C;AA8C3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,+BAFU,aAAa,CAMpB;8BA7E2B,+BAA+B"}