@woosh/meep-engine 3.32.0 → 3.34.0

package/src/shade/renderer/particles/ParticleConstants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;;;;;;;GAWG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;;;GAOG;AACH,2CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;GAUG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;GAOG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;GAIG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,yCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAFU,MAAM,CAEkC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAFU,MAAM,CAEkC;;AASlD;;;;;;;;;;;;;;;GAeG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;;;GAYG;AACH,uCAFU,MAAM,CAE4B"}
+{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;;;;;;;GAWG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;;;GAOG;AACH,2CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;GAUG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;GAOG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;GAIG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,yCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAFU,MAAM,CAEkC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAFU,MAAM,CAEkC;;AASlD;;;;;;;;;;;;;;;GAeG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;GAUG;AACH,uCAFU,MAAM,CAE4B"}

package/src/shade/renderer/particles/ParticleConstants.js

@@ -280,9 +280,7 @@ export const PARTICLE_SIM_PAD_SLOT = 0xffffffff;
  * Above all it is what the two passes that have to agree on a fragment's coverage agree on: the
  * AVBOIT draw, which weights the accumulators by it, and the AVBOIT splat, which records the
  * extinction the volume then hands to everything behind. A fade in one and not the other is a
- * surface that is invisible and still occludes. The blended billboard pipeline
- * (`shaders/shader_particle_render.js`) reads it too, so a particle fades over the same distance
- * whichever pipeline draws it.
+ * surface that is invisible and still occludes.
  *
  * @type {number}
  */

package/src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.d.ts

@@ -1,9 +1,8 @@
 /**
  * The billboard vertex stage, shared by every pass that rasterizes particles: the AVBOIT splat and
- * draw, and the blended pipeline `particular` draws its CPU-simulated particles with. One instance
- * per particle, six vertices per instance; the instance indexes the slot list, the vertex picks a
- * quad corner, and the corner is expanded per the emitter's projection mode and projected with the
- * camera.
+ * draw. One instance per particle, six vertices per instance; the instance indexes the slot list,
+ * the vertex picks a quad corner, and the corner is expanded per the emitter's projection mode and
+ * projected with the camera.
  *
  * The enclosing shader binds `camera` (`CAMERA_UNIFORM_STRUCT`), `pool` and `emitter_database`
  * (`array<u32>`) and `draw_list` (the slot list, `array<u32>`) under those names; this reads them

package/src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_billboard_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;GAiBG;AACH,8CAFU,SAAS,CAuE6D;0BA9FtD,oCAAoC"}
+{"version":3,"file":"chunk_particle_billboard_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,SAAS,CAuE6D;0BA7FtD,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.js

@@ -7,10 +7,9 @@ import { chunk_particle_render_math } from "./chunk_particle_render_math.js";
 
 /**
  * The billboard vertex stage, shared by every pass that rasterizes particles: the AVBOIT splat and
- * draw, and the blended pipeline `particular` draws its CPU-simulated particles with. One instance
- * per particle, six vertices per instance; the instance indexes the slot list, the vertex picks a
- * quad corner, and the corner is expanded per the emitter's projection mode and projected with the
- * camera.
+ * draw. One instance per particle, six vertices per instance; the instance indexes the slot list,
+ * the vertex picks a quad corner, and the corner is expanded per the emitter's projection mode and
+ * projected with the camera.
  *
  * The enclosing shader binds `camera` (`CAMERA_UNIFORM_STRUCT`), `pool` and `emitter_database`
  * (`array<u32>`) and `draw_list` (the slot list, `array<u32>`) under those names; this reads them

package/src/shade/renderer/postprocess/nss/NSS.d.ts

@@ -53,7 +53,7 @@ export class NSS {
      * @returns {number}
      */
     static recommended_jitter_sequence_size(upscale_ratio: number): number;
-    static "__#185@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
+    static "__#186@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
     /**
      * @param {GraphicsContext} graphics
      */

package/src/shade/renderer/rasterize/bucket/graph_meshlets_rasterize_by_bucket.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Draw one view's meshlets, of several opaque buckets at once, each bucket under its own pipeline
+ * state.
+ *
+ * The other half of cutting a view once (CUT_PLAN_2026_09_14 §7 6b). Expansion and the
+ * virtual-geometry cut run over every opaque instance of the view together, so what comes out is
+ * one collection with every bucket in it, and the buckets are separated here, after the fact: sort
+ * by bucket, then one draw per bucket over its slice.
+ *
+ * With a single bucket there is nothing to separate — every meshlet is in it — and the collection
+ * is drawn as it is.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUViewContext} options.view
+ * @param {number} options.input_meshlets every meshlet to draw, all of them in `buckets`
+ * @param {{draw_mode: number, side: number, bucket_id: number}[]} options.buckets the opaque
+ *     buckets drawn, as {@link rasterization_opaque_buckets} yields them; at least one
+ * @param {number} options.depth
+ * @param {number[]} options.color_targets
+ * @param {RenderPassDescriptor} options.pass_descriptor
+ * @param {boolean} options.clear_targets whether the first draw clears
+ * @param {Readonly<Record<number, GPUCullMode>>} options.cull_policy
+ * @param {number[]} [options.viewport]
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {[number, number[]]} depth and colour handles, as {@link graph_meshlets_rasterize}
+ */
+export function graph_meshlets_rasterize_by_bucket({ graph, view, input_meshlets, buckets, depth, color_targets, pass_descriptor, clear_targets, cull_policy, viewport, limits, }: {
+    graph: FrameGraph;
+    view: GPUViewContext;
+    input_meshlets: number;
+    buckets: {
+        draw_mode: number;
+        side: number;
+        bucket_id: number;
+    }[];
+    depth: number;
+    color_targets: number[];
+    pass_descriptor: RenderPassDescriptor;
+    clear_targets: boolean;
+    cull_policy: Readonly<Record<number, GPUCullMode>>;
+    viewport?: number[];
+    limits: GPUCollectionLimits;
+}): [number, number[]];
+//# sourceMappingURL=graph_meshlets_rasterize_by_bucket.d.ts.map

package/src/shade/renderer/rasterize/bucket/graph_meshlets_rasterize_by_bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_meshlets_rasterize_by_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/graph_meshlets_rasterize_by_bucket.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAd+B,KAAK;IACD,IAAI;IACZ,cAAc,EAA9B,MAAM;IAC0D,OAAO,EAAvE;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAC,EAAE;IAEtC,KAAK,EAArB,MAAM;IACY,aAAa,EAA/B,MAAM,EAAE;IACsB,eAAe;IAC5B,aAAa,EAA9B,OAAO;IACwC,WAAW,EAA1D,SAAS,OAAO,MAAM,cAAc,CAAC;IAClB,QAAQ,GAA3B,MAAM,EAAE;IACqB,MAAM;IACjC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAmE9B"}

package/src/shade/renderer/rasterize/bucket/graph_meshlets_rasterize_by_bucket.js

@@ -0,0 +1,99 @@
+import { assert } from "../../../../core/assert.js";
+import { graph_extract_meshlets_from_bucket } from "../expand/bucket/meshlet/graph_extract_meshlets_from_bucket.js";
+import { graph_sort_meshlets_by_bucket_id } from "../expand/bucket/meshlet/graph_sort_meshlets_by_bucket_id.js";
+import { graph_meshlets_rasterize } from "../expand/graph_meshlets_rasterize.js";
+import { construct_primitive_state } from "./construct_primitive_state.js";
+
+/**
+ * Draw one view's meshlets, of several opaque buckets at once, each bucket under its own pipeline
+ * state.
+ *
+ * The other half of cutting a view once (CUT_PLAN_2026_09_14 §7 6b). Expansion and the
+ * virtual-geometry cut run over every opaque instance of the view together, so what comes out is
+ * one collection with every bucket in it, and the buckets are separated here, after the fact: sort
+ * by bucket, then one draw per bucket over its slice.
+ *
+ * With a single bucket there is nothing to separate — every meshlet is in it — and the collection
+ * is drawn as it is.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUViewContext} options.view
+ * @param {number} options.input_meshlets every meshlet to draw, all of them in `buckets`
+ * @param {{draw_mode: number, side: number, bucket_id: number}[]} options.buckets the opaque
+ *     buckets drawn, as {@link rasterization_opaque_buckets} yields them; at least one
+ * @param {number} options.depth
+ * @param {number[]} options.color_targets
+ * @param {RenderPassDescriptor} options.pass_descriptor
+ * @param {boolean} options.clear_targets whether the first draw clears
+ * @param {Readonly<Record<number, GPUCullMode>>} options.cull_policy
+ * @param {number[]} [options.viewport]
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {[number, number[]]} depth and colour handles, as {@link graph_meshlets_rasterize}
+ */
+export function graph_meshlets_rasterize_by_bucket({
+                                                       graph,
+                                                       view,
+                                                       input_meshlets,
+                                                       buckets,
+                                                       depth,
+                                                       color_targets,
+                                                       pass_descriptor,
+                                                       clear_targets,
+                                                       cull_policy,
+                                                       viewport,
+                                                       limits,
+                                                   }) {
+    assert.isArray(buckets, 'buckets');
+    assert.greaterThanOrEqual(buckets.length, 1, 'buckets.length');
+
+    if (buckets.length === 1) {
+        const { draw_mode, side } = buckets[0];
+
+        return graph_meshlets_rasterize({
+            graph,
+            view,
+            input_meshlets,
+            depth,
+            color_targets,
+            pass_descriptor,
+            clear_targets,
+            primitive_state: construct_primitive_state(draw_mode, side, cull_policy),
+            viewport,
+        });
+    }
+
+    const sorted = graph_sort_meshlets_by_bucket_id({
+        graph,
+        input_meshlets,
+        scene_ctx: view.scene,
+        limits,
+    });
+
+    let clear = clear_targets;
+
+    for (const { draw_mode, side, bucket_id } of buckets) {
+        const meshlets = graph_extract_meshlets_from_bucket({
+            graph,
+            buckets: sorted,
+            bucket_id,
+            limits,
+        });
+
+        [depth, color_targets] = graph_meshlets_rasterize({
+            graph,
+            view,
+            input_meshlets: meshlets,
+            depth,
+            color_targets,
+            pass_descriptor,
+            clear_targets: clear,
+            primitive_state: construct_primitive_state(draw_mode, side, cull_policy),
+            viewport,
+        });
+
+        clear = false;
+    }
+
+    return [depth, color_targets];
+}

package/src/shade/renderer/rasterize/bucket/rasterization_opaque_buckets.d.ts

@@ -1,10 +1,10 @@
 /**
  * The opaque rasterization buckets a scene has anything in, once each.
  *
- * Every opaque path records one pass per bucket, and the pass is expensive — extract, expand to
- * meshlets, select a virtual-geometry cut, one render pass. So what is iterated has to be the
- * *buckets*, and iterating `ShadeDrawSide` is not that: `Front` and `Back` are one bucket, and a
- * loop over the enum visits it twice and draws the scene's single-sided geometry twice.
+ * Every opaque path records work per bucket — a filter, a slice of the sorted meshlets, a render
+ * pass. So what is iterated has to be the *buckets*, and iterating `ShadeDrawSide` is not that:
+ * `Front` and `Back` are one bucket, and a loop over the enum visits it twice and draws the scene's
+ * single-sided geometry twice.
  *
  * Which is why this exists rather than the three callers each writing the loop: the enum is the
  * obvious thing to reach for and it is wrong, and it is wrong in a way that costs a whole pass and

package/src/shade/renderer/rasterize/bucket/rasterization_opaque_buckets.js

@@ -1,36 +1,36 @@
-import { ShadeDrawMode } from "../../material/ShadeDrawMode.js";
-import { TransparencyMode } from "../../material/TransparencyMode.js";
-import { rasterization_material_bucket } from "../expand/bucket/chunk_rasterization_material_bucket.js";
-import { RASTERIZATION_BUCKET_SIDES } from "./construct_primitive_state.js";
-
-/**
- * The opaque rasterization buckets a scene has anything in, once each.
- *
- * Every opaque path records one pass per bucket, and the pass is expensive — extract, expand to
- * meshlets, select a virtual-geometry cut, one render pass. So what is iterated has to be the
- * *buckets*, and iterating `ShadeDrawSide` is not that: `Front` and `Back` are one bucket, and a
- * loop over the enum visits it twice and draws the scene's single-sided geometry twice.
- *
- * Which is why this exists rather than the three callers each writing the loop: the enum is the
- * obvious thing to reach for and it is wrong, and it is wrong in a way that costs a whole pass and
- * shows up in nothing but a frame time.
- *
- * @param {Set<number>} active_buckets bucket ids any material in the scene asks for
- * @yields {{draw_mode: ShadeDrawMode, side: ShadeDrawSide, bucket_id: number}} `side` is the
- *   bucket's representative, which is what {@link construct_primitive_state} wants
- */
-export function* rasterization_opaque_buckets(active_buckets) {
-    for (const draw_mode of Object.values(ShadeDrawMode)) {
-        for (const side of RASTERIZATION_BUCKET_SIDES) {
-
-            const bucket_id = rasterization_material_bucket(TransparencyMode.Opaque, draw_mode, side);
-
-            if (!active_buckets.has(bucket_id)) {
-                // no matching materials, skip
-                continue;
-            }
-
-            yield { draw_mode, side, bucket_id };
-        }
-    }
-}
+import { ShadeDrawMode } from "../../material/ShadeDrawMode.js";
+import { TransparencyMode } from "../../material/TransparencyMode.js";
+import { rasterization_material_bucket } from "../expand/bucket/chunk_rasterization_material_bucket.js";
+import { RASTERIZATION_BUCKET_SIDES } from "./construct_primitive_state.js";
+
+/**
+ * The opaque rasterization buckets a scene has anything in, once each.
+ *
+ * Every opaque path records work per bucket — a filter, a slice of the sorted meshlets, a render
+ * pass. So what is iterated has to be the *buckets*, and iterating `ShadeDrawSide` is not that:
+ * `Front` and `Back` are one bucket, and a loop over the enum visits it twice and draws the scene's
+ * single-sided geometry twice.
+ *
+ * Which is why this exists rather than the three callers each writing the loop: the enum is the
+ * obvious thing to reach for and it is wrong, and it is wrong in a way that costs a whole pass and
+ * shows up in nothing but a frame time.
+ *
+ * @param {Set<number>} active_buckets bucket ids any material in the scene asks for
+ * @yields {{draw_mode: ShadeDrawMode, side: ShadeDrawSide, bucket_id: number}} `side` is the
+ *   bucket's representative, which is what {@link construct_primitive_state} wants
+ */
+export function* rasterization_opaque_buckets(active_buckets) {
+    for (const draw_mode of Object.values(ShadeDrawMode)) {
+        for (const side of RASTERIZATION_BUCKET_SIDES) {
+
+            const bucket_id = rasterization_material_bucket(TransparencyMode.Opaque, draw_mode, side);
+
+            if (!active_buckets.has(bucket_id)) {
+                // no matching materials, skip
+                continue;
+            }
+
+            yield { draw_mode, side, bucket_id };
+        }
+    }
+}

package/src/shade/renderer/rasterize/bucket/shader_gather_bucket.d.ts

@@ -0,0 +1,15 @@
+/**
+ * One bucket of a bucket-sorted collection, appended to a flat collection after the gathered
+ * buckets below it.
+ *
+ * Dispatched once per gathered bucket, in ascending id order, each sized off its own bucket's
+ * header. Where a bucket lands is the sum of the gathered buckets below it, so the output is their
+ * concatenation whatever the dispatches' timing, and not one atomic is involved.
+ *
+ * @see graph_gather_meshes_from_buckets
+ * @see shader_read_out_bucket which copies a bucket to the start of an output of its own
+ * @type {ComputeShader}
+ */
+export const shader_gather_bucket: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_gather_bucket.d.ts.map

package/src/shade/renderer/rasterize/bucket/shader_gather_bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_gather_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/shader_gather_bucket.js"],"names":[],"mappings":"AAsFA;;;;;;;;;;;GAWG;AACH,mCAFU,aAAa,CAMrB;8BAhG4B,+BAA+B"}

package/src/shade/renderer/rasterize/bucket/shader_gather_bucket.js

@@ -0,0 +1,103 @@
+import { assert } from "../../../../core/assert.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { RASTERIZATION_BUCKET_LIMIT } from "../expand/bucket/RASTERIZATION_BUCKET_LIMIT.js";
+import {
+    RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_READ
+} from "../expand/bucket/RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_READ.js";
+
+// every bucket is one bit of `gathered`
+assert.lessThanOrEqual(RASTERIZATION_BUCKET_LIMIT, 32, 'RASTERIZATION_BUCKET_LIMIT');
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", WebGPUStruct.from({
+    bucket_id: u32,
+    // every bucket this gather concatenates, one bit per bucket id
+    gathered: u32,
+}));
+
+resources.createGroup()
+    .addStorageBuffer("input", RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_READ)
+    .addStorageBuffer("output", COLLECTION_U32_STRUCT_READ, true)
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+// What a bucket holds, which is not always what its header says: the classify pass counts every
+// visible mesh and writes one only while the input has room (see shader_read_out_bucket).
+fn bucket_size(bucket_id: u32) -> u32 {
+    let header = input.headers[bucket_id];
+
+    let input_capacity = arrayLength(&input.elements);
+    let available = select(0u, input_capacity - header.offset, input_capacity > header.offset);
+
+    return min(header.count, available);
+}
+
+@compute @workgroup_size(${COMPUTE_SHADER_DEFAULT_GROUP_SIZE})
+fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
+
+    let input_index = global_id.x;
+
+    let bucket_id = settings.bucket_id;
+
+    // the bucket starts where the gathered buckets below it end — each read off its own header, so
+    // no dispatch has to hand the next one where it stopped
+    var base = 0u;
+    var below = settings.gathered & ((1u << bucket_id) - 1u);
+
+    while (below != 0u) {
+        base += bucket_size(firstTrailingBit(below));
+        below &= below - 1u;
+    }
+
+    let size = bucket_size(bucket_id);
+    let output_capacity = arrayLength(&output.elements);
+
+    /*
+     Every bucket writes the count it ends at, and the buckets are dispatched in ascending order, so
+     the last one standing wrote the total. Not only the highest: a bucket with nothing in it is a
+     dispatch of no workgroups, and writes nothing at all.
+    */
+    if (input_index == 0u) {
+        output.count = min(base + size, output_capacity);
+    }
+
+    if (input_index >= size) {
+        return;
+    }
+
+    let output_index = base + input_index;
+
+    if (output_index >= output_capacity) {
+        return;
+    }
+
+    output.elements[output_index] = input.elements[input.headers[bucket_id].offset + input_index];
+}
+    `
+);
+
+/**
+ * One bucket of a bucket-sorted collection, appended to a flat collection after the gathered
+ * buckets below it.
+ *
+ * Dispatched once per gathered bucket, in ascending id order, each sized off its own bucket's
+ * header. Where a bucket lands is the sum of the gathered buckets below it, so the output is their
+ * concatenation whatever the dispatches' timing, and not one atomic is involved.
+ *
+ * @see graph_gather_meshes_from_buckets
+ * @see shader_read_out_bucket which copies a bucket to the start of an output of its own
+ * @type {ComputeShader}
+ */
+export const shader_gather_bucket = ComputeShader.from({
+    label: 'Gather bucket',
+    resources,
+    body,
+})

package/src/shade/renderer/rasterize/expand/GPUCollectionLimits.d.ts

@@ -46,6 +46,9 @@ export class GPUCollectionLimits {
     compute_buffer_size(type: RasterizationCollectionType): number;
     destroy(): void;
     /**
+     * Read this frame's counts back once `encoder` is submitted and fold them into the limits.
+     * Resolves, never rejects, when the reading is lost to a teardown — see
+     * {@link Uint32BufferSamplingStats#readback_explicit} — and the limits then stand as they were.
      *
      * @param {ShadeGPUCommandContext} encoder
      * @param {GPUBufferAllocator} buffers

package/src/shade/renderer/rasterize/expand/GPUCollectionLimits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUCollectionLimits.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/expand/GPUCollectionLimits.js"],"names":[],"mappings":"AAsBA;;GAEG;AACH;IAyBI;;;OAGG;IACH,+BAqBC;IAtCD;;;OAGG;IACH,uCAEC;IAkCD;;;;OAIG;IACH,gBAHW,2BAA2B,GAC1B,MAAM,CAMjB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAHW,2BAA2B,SAC3B,MAAM,QAQhB;IAED;;;;OAIG;IACH,0BAHW,2BAA2B,GACzB,MAAM,CAyBlB;IA+BD,gBAEC;IAED;;;;OAIG;IACH,gBAHW,sBAAsB,WACtB,kBAAkB,iBAgB5B;;CAEJ;qCA5LY,OAAO,2CAA2C,EAAE,sBAAsB;iCAC1E,OAAO,oCAAoC,EAAE,kBAAkB;0CANlC,yCAAyC;4CACvC,kCAAkC"}
+{"version":3,"file":"GPUCollectionLimits.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/expand/GPUCollectionLimits.js"],"names":[],"mappings":"AAsBA;;GAEG;AACH;IAyBI;;;OAGG;IACH,+BAqBC;IAtCD;;;OAGG;IACH,uCAEC;IAkCD;;;;OAIG;IACH,gBAHW,2BAA2B,GAC1B,MAAM,CAMjB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAHW,2BAA2B,SAC3B,MAAM,QAQhB;IAED;;;;OAIG;IACH,0BAHW,2BAA2B,GACzB,MAAM,CAyBlB;IA+BD,gBAEC;IAED;;;;;;;OAOG;IACH,gBAHW,sBAAsB,WACtB,kBAAkB,iBAkB5B;;CAEJ;qCAjMY,OAAO,2CAA2C,EAAE,sBAAsB;iCAC1E,OAAO,oCAAoC,EAAE,kBAAkB;0CANlC,yCAAyC;4CACvC,kCAAkC"}

package/src/shade/renderer/rasterize/expand/GPUCollectionLimits.js

@@ -177,6 +177,9 @@ export class GPUCollectionLimits {
     }
 
     /**
+     * Read this frame's counts back once `encoder` is submitted and fold them into the limits.
+     * Resolves, never rejects, when the reading is lost to a teardown — see
+     * {@link Uint32BufferSamplingStats#readback_explicit} — and the limits then stand as they were.
      *
      * @param {ShadeGPUCommandContext} encoder
      * @param {GPUBufferAllocator} buffers
@@ -187,7 +190,9 @@ export class GPUCollectionLimits {
 
         const stats = this.#stats;
 
-        await stats.readback_explicit(encoder, buffers);
+        if (!await stats.readback_explicit(encoder, buffers)) {
+            return;
+        }
 
         this.#clamp_stats_against_runaway();
 

package/src/shade/renderer/rasterize/expand/bucket/meshlet/graph_extract_meshlets_from_bucket.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copy one bucket's meshlets out of a bucket-sorted meshlet buffer into a flat collection a raster
+ * pass can draw.
+ *
+ * The second half of expanding and cutting a view once and bucketing afterwards
+ * (CUT_PLAN_2026_09_14 §7 6b): the bucket loop that follows rasterizes each slice with its own
+ * primitive state, and nothing upstream of the sort had to know how many buckets there were.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.buckets bucket-sorted meshlets, as {@link graph_sort_meshlets_by_bucket_id}
+ *     leaves them
+ * @param {number} options.bucket_id
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} the bucket's meshlets
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_extract_meshlets_from_bucket({ graph, buckets, bucket_id, limits, }: {
+    graph: FrameGraph;
+    buckets: number;
+    bucket_id: number;
+    limits: GPUCollectionLimits;
+}): number;
+//# sourceMappingURL=graph_extract_meshlets_from_bucket.d.ts.map

package/src/shade/renderer/rasterize/expand/bucket/meshlet/graph_extract_meshlets_from_bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_extract_meshlets_from_bucket.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/rasterize/expand/bucket/meshlet/graph_extract_meshlets_from_bucket.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAV+B,KAAK;IACT,OAAO,EAAvB,MAAM;IAEU,SAAS,EAAzB,MAAM;IACuB,MAAM;IACjC,MAAM,CAoElB"}

package/src/shade/renderer/rasterize/expand/bucket/meshlet/graph_extract_meshlets_from_bucket.js

@@ -0,0 +1,91 @@
+import { BufferResourceDescriptor } from "../../../../../device/graph/BufferResourceDescriptor.js";
+import { u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { STRUCT_DISPATCH_COMPUTE_COMMAND } from "../../../../gpu_primitive/indirect/STRUCT_DISPATCH_COMPUTE_COMMAND.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { build_indirect_compute_dispatch_command } from "../../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { RasterizationCollectionType } from "../../RasterizationCollectionType.js";
+import { shader_meshlets_extract_bucket } from "./shader_meshlets_extract_bucket.js";
+
+/**
+ * Copy one bucket's meshlets out of a bucket-sorted meshlet buffer into a flat collection a raster
+ * pass can draw.
+ *
+ * The second half of expanding and cutting a view once and bucketing afterwards
+ * (CUT_PLAN_2026_09_14 §7 6b): the bucket loop that follows rasterizes each slice with its own
+ * primitive state, and nothing upstream of the sort had to know how many buckets there were.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.buckets bucket-sorted meshlets, as {@link graph_sort_meshlets_by_bucket_id}
+ *     leaves them
+ * @param {number} options.bucket_id
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} the bucket's meshlets
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_extract_meshlets_from_bucket({
+                                                       graph,
+                                                       buckets,
+                                                       bucket_id,
+                                                       limits,
+                                                   }) {
+
+    /**
+     *
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute(data, resources, context) {
+        const encoder = context.encoder;
+
+        const buckets = resources.get(data.buckets);
+        const output = resources.get(data.output);
+        const command = resources.get(data.command);
+
+        const bucket_id = data.bucket_id;
+
+        // folded: a meshlet collection is past what one dispatch dimension reaches — see
+        // IndirectComputeCommandBuildPass
+        build_indirect_compute_dispatch_command(
+            COMPUTE_SHADER_DEFAULT_GROUP_SIZE,
+            encoder,
+            buckets,
+            // the bucketed buffer header consists of pairs of u32 values (count,offset)
+            bucket_id * (u32.size * 2),
+            command,
+            0,
+            true,
+        );
+
+        shader_meshlets_extract_bucket.dispatchIndirect({
+            encoder,
+            command,
+            bindings: {
+                bucket_index: { value: bucket_id },
+                bucket_data: buckets,
+                output: output,
+            }
+        });
+    }
+
+    const data = {};
+
+    const pass = graph.add("extract meshlets from bucket", data, execute);
+
+    data.buckets = pass.read(buckets);
+    data.bucket_id = bucket_id;
+    data.command = pass.create("command", BufferResourceDescriptor.from(
+        STRUCT_DISPATCH_COMPUTE_COMMAND.aligned_size,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
+    ));
+    data.output = pass.create("output", BufferResourceDescriptor.from(
+        limits.compute_buffer_size(RasterizationCollectionType.Meshlets),
+        GPUBufferUsage.STORAGE,
+        0, 16 // clear count
+    ));
+
+    return data.output;
+}

package/src/shade/renderer/rasterize/fast/graph_gather_meshes_from_buckets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Several buckets' mesh indices out of a bucket-sorted mesh buffer, into one flat
+ * {@link COLLECTION_U32_STRUCT_READ} buffer, end to end in bucket order.
+ *
+ * What lets the fast path expand and cut a view once rather than once per opaque bucket
+ * (CUT_PLAN_2026_09_14 §7 6b): the opaque buckets are not neighbours in the sorted buffer — the
+ * transparency mode is the low bits of a bucket id — so they cannot be read out as one range.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.buckets bucket-sorted meshes resource ID
+ * @param {number[]} options.bucket_ids the buckets to gather, ascending
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} resource ID of the gathered mesh list
+ */
+export function graph_gather_meshes_from_buckets({ graph, buckets, bucket_ids, limits, }: {
+    graph: FrameGraph;
+    buckets: number;
+    bucket_ids: number[];
+    limits: GPUCollectionLimits;
+}): number;
+//# sourceMappingURL=graph_gather_meshes_from_buckets.d.ts.map

package/src/shade/renderer/rasterize/fast/graph_gather_meshes_from_buckets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_gather_meshes_from_buckets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_gather_meshes_from_buckets.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH;IAN+B,KAAK;IACT,OAAO,EAAvB,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACqB,MAAM;IACjC,MAAM,CA6ElB"}