@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_cut_descent.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../../shader/ComputeShader.js").ComputeShader} ComputeShader
+ * @typedef {import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime} GPUVirtualGeometryRuntime
+ * @typedef {import("./VGeoViewCut.js").VGeoViewCut} VGeoViewCut
+ */
+/**
+ * A cut's descent, design §7's cut pass after its collect: seed one item per instance at its root page's node 0,
+ * run the wavefront the cut's own bound of times, and count what it left. The camera's seam and a box cut both run
+ * it; what differs between them is their collect, which writes the instance records and scans their claim widths,
+ * and their traverse kernel, which is `chunk_vgeo_cut_descent` with that cut's culls and its take.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUVirtualGeometryRuntime} options.runtime inside an open frame
+ * @param {VGeoViewCut} options.cut whose params, slot and wavefront bound this is; its params written this frame
+ * @param {number} options.instances the instance records, `VGEO_INSTANCE_WORDS` each
+ * @param {number} options.prefix_sums their claim widths, scanned inclusive, with their count
+ * @param {number} options.feedback the frame's feedback, at the version the collect wrote
+ * @param {ComputeShader} options.traverse the cut's traverse kernel
+ * @param {Object} [options.bindings] the traverse's own bindings beyond the descent's, by name, which no pass of this
+ *   graph writes
+ * @param {Object<string, number>} [options.outputs] the traverse's own outputs, as graph resources by name; every
+ *   wavefront writes them
+ * @returns {{feedback: number, instances: number, outputs: Object<string, number>}} the feedback, the instance
+ *   records and the outputs at the versions the descent last wrote: the records with their claim bases, which the
+ *   seed writes
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_vgeo_cut_descent({ graph, runtime, cut, instances, prefix_sums, feedback, traverse, bindings, outputs, }: {
+    graph: FrameGraph;
+    runtime: GPUVirtualGeometryRuntime;
+    cut: VGeoViewCut;
+    instances: number;
+    prefix_sums: number;
+    feedback: number;
+    traverse: ComputeShader;
+    bindings?: any;
+    outputs?: {
+        [x: string]: number;
+    };
+}): {
+    feedback: number;
+    instances: number;
+    outputs: {
+        [x: string]: number;
+    };
+};
+export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type ComputeShader = import("../../../shader/ComputeShader.js").ComputeShader;
+export type GPUVirtualGeometryRuntime = import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime;
+export type VGeoViewCut = import("./VGeoViewCut.js").VGeoViewCut;
+//# sourceMappingURL=graph_vgeo_cut_descent.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_cut_descent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_vgeo_cut_descent.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/graph_vgeo_cut_descent.js"],"names":[],"mappings":"AAaA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAlB+B,KAAK,EAAzB,UAAU;IACyB,OAAO,EAA1C,yBAAyB;IACJ,GAAG,EAAxB,WAAW;IACK,SAAS,EAAzB,MAAM;IACU,WAAW,EAA3B,MAAM;IACU,QAAQ,EAAxB,MAAM;IACiB,QAAQ,EAA/B,aAAa;IACI,QAAQ;IAEQ,OAAO;YAAjC,MAAM,GAAE,MAAM;;IAEnB;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO;YAAS,MAAM,GAAE,MAAM;MAAC;CAAC,CAiNlF;yBAzOY,OAAO,iEAAiE,EAAE,UAAU;4BACpF,OAAO,kCAAkC,EAAE,aAAa;wCACxD,OAAO,gCAAgC,EAAE,yBAAyB;0BAClE,OAAO,kBAAkB,EAAE,WAAW"}

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_cut_descent.js

@@ -0,0 +1,248 @@
+import { assert } from "../../../../../core/assert.js";
+import { noop } from "../../../../../core/function/noop.js";
+import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
+import {
+    graph_build_indirect_dispatch_command,
+    INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
+} from "../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { shader_vgeo_cut_queue_prepare } from "./cut/shader_vgeo_cut_queue_prepare.js";
+import { shader_vgeo_cut_queue_remainder } from "./cut/shader_vgeo_cut_queue_remainder.js";
+import { shader_vgeo_cut_seed } from "./cut/shader_vgeo_cut_seed.js";
+import { VGEO_CUT_WORKGROUP_SIZE } from "./cut/VGEO_CUT_WORKGROUP_SIZE.js";
+import { VGEO_QUEUE_ITEM_WORDS } from "./layout/VGEO_QUEUE_ITEM_WORDS.js";
+
+/**
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../../shader/ComputeShader.js").ComputeShader} ComputeShader
+ * @typedef {import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime} GPUVirtualGeometryRuntime
+ * @typedef {import("./VGeoViewCut.js").VGeoViewCut} VGeoViewCut
+ */
+
+/**
+ * A cut's descent, design §7's cut pass after its collect: seed one item per instance at its root page's node 0,
+ * run the wavefront the cut's own bound of times, and count what it left. The camera's seam and a box cut both run
+ * it; what differs between them is their collect, which writes the instance records and scans their claim widths,
+ * and their traverse kernel, which is `chunk_vgeo_cut_descent` with that cut's culls and its take.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUVirtualGeometryRuntime} options.runtime inside an open frame
+ * @param {VGeoViewCut} options.cut whose params, slot and wavefront bound this is; its params written this frame
+ * @param {number} options.instances the instance records, `VGEO_INSTANCE_WORDS` each
+ * @param {number} options.prefix_sums their claim widths, scanned inclusive, with their count
+ * @param {number} options.feedback the frame's feedback, at the version the collect wrote
+ * @param {ComputeShader} options.traverse the cut's traverse kernel
+ * @param {Object} [options.bindings] the traverse's own bindings beyond the descent's, by name, which no pass of this
+ *   graph writes
+ * @param {Object<string, number>} [options.outputs] the traverse's own outputs, as graph resources by name; every
+ *   wavefront writes them
+ * @returns {{feedback: number, instances: number, outputs: Object<string, number>}} the feedback, the instance
+ *   records and the outputs at the versions the descent last wrote: the records with their claim bases, which the
+ *   seed writes
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_vgeo_cut_descent({
+                                           graph,
+                                           runtime,
+                                           cut,
+                                           instances,
+                                           prefix_sums,
+                                           feedback,
+                                           traverse,
+                                           bindings = {},
+                                           outputs = {},
+                                       }) {
+    assert.defined(graph, 'graph');
+    assert.defined(runtime, 'runtime');
+    assert.equal(runtime.frame_open, true, 'runtime.frame_open — begin_frame must have run');
+    assert.defined(cut, 'cut');
+    assert.isNonNegativeInteger(instances, 'instances');
+    assert.isNonNegativeInteger(prefix_sums, 'prefix_sums');
+    assert.isNonNegativeInteger(feedback, 'feedback');
+    assert.defined(traverse, 'traverse');
+
+    const pool = runtime.pool;
+
+    // and this cut's own wavefront bound, raised from its own readings
+    const max_iterations = cut.iterations_under(runtime);
+
+    // ----- seed: one item per instance, naming its root page's node 0 -----
+
+    const seed_command = graph_build_indirect_dispatch_command(
+        graph, prefix_sums, VGEO_CUT_WORKGROUP_SIZE
+    );
+
+    const queue_descriptor = BufferResourceDescriptor.from(
+        16 + runtime.queue_capacity * VGEO_QUEUE_ITEM_WORDS * 4,
+        GPUBufferUsage.STORAGE,
+        0, 16
+    );
+
+    const seed_data = {};
+
+    const seed_pass = graph.add("seed vg wavefront", seed_data, (data, resources, context) => {
+        shader_vgeo_cut_seed.dispatchIndirect({
+            encoder: context.encoder,
+            command: resources.get(data.command),
+            bindings: {
+                params: cut.params_buffer,
+                vg_arena: pool.buffer_arena,
+                prefix_sums: resources.get(data.prefix_sums),
+                instances: resources.get(data.instances),
+                queue_out: resources.get(data.queue_out),
+                claim: resources.get(data.claim),
+                feedback: resources.get(data.feedback),
+            }
+        });
+    });
+
+    seed_data.command = seed_pass.read(seed_command);
+    seed_data.prefix_sums = seed_pass.read(prefix_sums);
+    seed_data.instances = seed_pass.write(instances);
+
+    /*
+     Cleared per invocation, and that is not an optimization that could be traded away: each
+     expansion site sees a different instance set, so a claim carried over from the previous site
+     would make every page of this one look already visited. The stamps in the feedback buffer are
+     the opposite case — per frame, shared, and not cleared here.
+     */
+    seed_data.claim = seed_pass.create("vg claim", BufferResourceDescriptor.empty(
+        runtime.claim_word_capacity * 4,
+        GPUBufferUsage.STORAGE
+    ));
+
+    seed_data.feedback = seed_pass.write(feedback);
+    seed_data.queue_out = seed_pass.create("vg queue a", queue_descriptor);
+
+    const spare_spawn = graph.add("vg queue b", {}, noop);
+
+    /*
+     The two queues ping-pong, so *which* of them holds work is not a property of either buffer —
+     it moves every iteration. Carrying the roles rather than the buffers is what makes the tail
+     pass below correct at any `max_iterations` rather than only at an even one (REVIEW_LEDGER M8).
+     */
+    let ready_queue = seed_data.queue_out;
+    let spare_queue = spare_spawn.create("vg queue b", queue_descriptor);
+
+    let claim = seed_data.claim;
+
+    feedback = seed_data.feedback;
+
+    const records = seed_data.instances;
+
+    const latest = { ...outputs };
+
+    // ----- the wavefront -----
+
+    for (let iteration = 0; iteration < max_iterations; iteration++) {
+        const prepare_data = {};
+
+        const prepare_pass = graph.add(
+            `vg prepare ${iteration}`, prepare_data, (data, resources, context) => {
+                shader_vgeo_cut_queue_prepare.dispatch({
+                    encoder: context.encoder,
+                    bindings: {
+                        params: cut.params_buffer,
+                        queue_ready: resources.get(data.queue_ready),
+                        queue_spare: resources.get(data.queue_spare),
+                        command: resources.get(data.command),
+                    }
+                });
+            }
+        );
+
+        /*
+         Both queues, because this pass does two things at once and they belong together: it clamps
+         what the last wavefront produced — the count runs past capacity by design, and handing
+         *that* to an indirect dispatch would dispatch lanes over the end of a pooled buffer — and
+         it empties the one the next wavefront will write. There is exactly one moment when neither
+         wavefront is touching either, and this is it.
+         */
+        const ready = prepare_data.queue_ready = prepare_pass.write(ready_queue);
+        const spare = prepare_data.queue_spare = prepare_pass.write(spare_queue);
+
+        prepare_data.command = prepare_pass.create(
+            `vg command ${iteration}`, INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
+        );
+
+        const traverse_data = { outputs: {} };
+
+        const traverse_pass = graph.add(
+            `vg traverse ${iteration}`, traverse_data, (data, resources, context) => {
+                const dispatch_bindings = {
+                    ...bindings,
+                    params: cut.params_buffer,
+                    vg_lookup: pool.buffer_lookup,
+                    vg_arena: pool.buffer_arena,
+                    vg_want_stamps: pool.buffer_want_stamps,
+                    instances: resources.get(data.instances),
+                    queue_in: resources.get(data.queue_in),
+                    queue_out: resources.get(data.queue_out),
+                    claim: resources.get(data.claim),
+                    feedback: resources.get(data.feedback),
+                };
+
+                for (const name in data.outputs) {
+                    dispatch_bindings[name] = resources.get(data.outputs[name]);
+                }
+
+                traverse.dispatchIndirect({
+                    encoder: context.encoder,
+                    command: resources.get(data.command),
+                    bindings: dispatch_bindings,
+                });
+            }
+        );
+
+        traverse_data.command = traverse_pass.read(prepare_data.command);
+        traverse_data.instances = traverse_pass.read(records);
+        traverse_data.queue_in = traverse_pass.read(ready);
+
+        const produced = traverse_data.queue_out = traverse_pass.write(spare);
+
+        claim = traverse_data.claim = traverse_pass.write(claim);
+        feedback = traverse_data.feedback = traverse_pass.write(feedback);
+
+        for (const name in latest) {
+            latest[name] = traverse_data.outputs[name] = traverse_pass.write(latest[name]);
+        }
+
+        // what this wavefront produced is what the next one consumes, and the drained one is spare
+        ready_queue = produced;
+        spare_queue = ready;
+    }
+
+    /*
+     One more pass, for one number. The loop above records a fixed number of prepare/traverse pairs
+     and the queue can still hold work when the last of them finishes — a subtree never descended,
+     which is a hole rather than a coarse stand-in, and the one degradation §4.5 admits. This is
+     where `VGEO_CUT_STAT.QUEUE_REMAINING` comes from.
+
+     It is not the prepare pass: that one runs *between* wavefronts and once per iteration per
+     expansion site, so what it could report is a frontier rather than a remainder, and the next
+     site would overwrite it. See {@link shader_vgeo_cut_queue_remainder}.
+
+     `ready_queue` and not either buffer by name: which of the two holds the produced queue
+     alternates per iteration, so the roles are carried through the loop rather than named here.
+     */
+    const tail_data = {};
+
+    const tail_pass = graph.add("vg queue tail", tail_data, (data, resources, context) => {
+        shader_vgeo_cut_queue_remainder.dispatch({
+            encoder: context.encoder,
+            bindings: {
+                params: cut.params_buffer,
+                queue_ready: resources.get(data.queue_ready),
+                feedback: resources.get(data.feedback),
+            }
+        });
+    });
+
+    tail_data.queue_ready = tail_pass.read(ready_queue);
+
+    feedback = tail_data.feedback = tail_pass.write(feedback);
+
+    return { feedback, instances: records, outputs: latest };
+}

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_vgeo_expand_instances_to_meshlets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;IAX+B,KAAK;IACT,YAAY,EAA5B,MAAM;IACU,eAAe,EAA/B,MAAM;IACkB,IAAI;IACO,OAAO;IACb,MAAM;IACjC,MAAM,CA6TlB"}
+{"version":3,"file":"graph_vgeo_expand_instances_to_meshlets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;IAX+B,KAAK;IACT,YAAY,EAA5B,MAAM;IACU,eAAe,EAA/B,MAAM;IACkB,IAAI;IACO,OAAO;IACb,MAAM;IACjC,MAAM,CAqKlB"}

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.js

@@ -1,10 +1,6 @@
 import { assert } from "../../../../../core/assert.js";
-import { noop } from "../../../../../core/function/noop.js";
 import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
-import {
-    graph_build_indirect_dispatch_command,
-    INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
-} from "../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { graph_build_indirect_dispatch_command } from "../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
 import {
     graph_prefix_scan_csdldf,
     prefix_scan_csdldf_output_descriptor
@@ -12,13 +8,10 @@ import {
 import { RasterizationCollectionType } from "../../../rasterize/expand/RasterizationCollectionType.js";
 import { graph_create_buffer } from "../../../shader/graph/graph_create_buffer.js";
 import { shader_vgeo_cut_collect } from "./cut/shader_vgeo_cut_collect.js";
-import { shader_vgeo_cut_queue_prepare } from "./cut/shader_vgeo_cut_queue_prepare.js";
-import { shader_vgeo_cut_queue_remainder } from "./cut/shader_vgeo_cut_queue_remainder.js";
-import { shader_vgeo_cut_seed } from "./cut/shader_vgeo_cut_seed.js";
 import { shader_vgeo_cut_traverse } from "./cut/shader_vgeo_cut_traverse.js";
 import { VGEO_CUT_WORKGROUP_SIZE } from "./cut/VGEO_CUT_WORKGROUP_SIZE.js";
+import { graph_vgeo_cut_descent } from "./graph_vgeo_cut_descent.js";
 import { VGEO_INSTANCE_WORDS } from "./layout/VGEO_INSTANCE_WORDS.js";
-import { VGEO_QUEUE_ITEM_WORDS } from "./layout/VGEO_QUEUE_ITEM_WORDS.js";
 
 /**
  * **The seam.**
@@ -135,9 +128,6 @@ export function graph_vgeo_expand_instances_to_meshlets({
     // the frame's feedback buffer, as this graph knows it: imported on first use, cleared by the first
     const feedback_in = runtime.feedback_in(graph);
 
-    // and this view's own wavefront bound, raised from its own readings
-    const max_iterations = view_cut.iterations_under(runtime);
-
     // ----- collect: which of these instances are virtual, and where is the camera in each one -----
 
     const collect_command = graph_build_indirect_dispatch_command(
@@ -195,171 +185,22 @@ export function graph_vgeo_expand_instances_to_meshlets({
         element_max_count: instance_capacity,
     });
 
-    // ----- seed: one item per instance, naming its root page's node 0 -----
-
-    const seed_command = graph_build_indirect_dispatch_command(
-        graph, prefix_sums, VGEO_CUT_WORKGROUP_SIZE
-    );
-
-    const queue_descriptor = BufferResourceDescriptor.from(
-        16 + runtime.queue_capacity * VGEO_QUEUE_ITEM_WORDS * 4,
-        GPUBufferUsage.STORAGE,
-        0, 16
-    );
-
-    const seed_data = {};
-
-    const seed_pass = graph.add("seed vg wavefront", seed_data, (data, resources, context) => {
-        shader_vgeo_cut_seed.dispatchIndirect({
-            encoder: context.encoder,
-            command: resources.get(data.command),
-            bindings: {
-                params: view_cut.params_buffer,
-                vg_arena: pool.buffer_arena,
-                prefix_sums: resources.get(data.prefix_sums),
-                instances: resources.get(data.instances),
-                queue_out: resources.get(data.queue_out),
-                claim: resources.get(data.claim),
-                feedback: resources.get(data.feedback),
-            }
-        });
-    });
-
-    seed_data.command = seed_pass.read(seed_command);
-    seed_data.prefix_sums = seed_pass.read(prefix_sums);
-    seed_data.instances = seed_pass.write(collect_data.instances);
-
-    /*
-     Cleared per invocation, and that is not an optimization that could be traded away: each
-     expansion site sees a different instance set, so a claim carried over from the previous site
-     would make every page of this one look already visited. The stamps in the feedback buffer are
-     the opposite case — per frame, shared, and not cleared here.
-     */
-    seed_data.claim = seed_pass.create("vg claim", BufferResourceDescriptor.empty(
-        runtime.claim_word_capacity * 4,
-        GPUBufferUsage.STORAGE
-    ));
-
-    seed_data.feedback = seed_pass.write(collect_data.feedback);
-    seed_data.queue_out = seed_pass.create("vg queue a", queue_descriptor);
-
-    const spare_spawn = graph.add("vg queue b", {}, noop);
-
-    /*
-     The two queues ping-pong, so *which* of them holds work is not a property of either buffer —
-     it moves every iteration. Carrying the roles rather than the buffers is what makes the tail
-     pass below correct at any `max_iterations` rather than only at an even one (REVIEW_LEDGER M8).
-     */
-    let ready_queue = seed_data.queue_out;
-    let spare_queue = spare_spawn.create("vg queue b", queue_descriptor);
+    // ----- the descent: seed, the wavefront, and what it left -----
 
-    let claim = seed_data.claim;
-    let feedback = seed_data.feedback;
-    let meshlets = output_meshlets;
-
-    const instances = seed_data.instances;
-
-    // ----- the wavefront -----
-
-    for (let iteration = 0; iteration < max_iterations; iteration++) {
-        const prepare_data = {};
-
-        const prepare_pass = graph.add(
-            `vg prepare ${iteration}`, prepare_data, (data, resources, context) => {
-                shader_vgeo_cut_queue_prepare.dispatch({
-                    encoder: context.encoder,
-                    bindings: {
-                        params: view_cut.params_buffer,
-                        queue_ready: resources.get(data.queue_ready),
-                        queue_spare: resources.get(data.queue_spare),
-                        command: resources.get(data.command),
-                    }
-                });
-            }
-        );
-
-        /*
-         Both queues, because this pass does two things at once and they belong together: it clamps
-         what the last wavefront produced — the count runs past capacity by design, and handing
-         *that* to an indirect dispatch would dispatch lanes over the end of a pooled buffer — and
-         it empties the one the next wavefront will write. There is exactly one moment when neither
-         wavefront is touching either, and this is it.
-         */
-        const ready = prepare_data.queue_ready = prepare_pass.write(ready_queue);
-        const spare = prepare_data.queue_spare = prepare_pass.write(spare_queue);
-
-        prepare_data.command = prepare_pass.create(
-            `vg command ${iteration}`, INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
-        );
-
-        const traverse_data = {};
-
-        const traverse_pass = graph.add(
-            `vg traverse ${iteration}`, traverse_data, (data, resources, context) => {
-                shader_vgeo_cut_traverse.dispatchIndirect({
-                    encoder: context.encoder,
-                    command: resources.get(data.command),
-                    bindings: {
-                        params: view_cut.params_buffer,
-                        vg_lookup: pool.buffer_lookup,
-                        vg_arena: pool.buffer_arena,
-                        vg_want_stamps: pool.buffer_want_stamps,
-                        instances: resources.get(data.instances),
-                        queue_in: resources.get(data.queue_in),
-                        queue_out: resources.get(data.queue_out),
-                        claim: resources.get(data.claim),
-                        feedback: resources.get(data.feedback),
-                        frontier: view_cut.frontier_buffer,
-                        out_meshlets: resources.get(data.out_meshlets),
-                    }
-                });
-            }
-        );
-
-        traverse_data.command = traverse_pass.read(prepare_data.command);
-        traverse_data.instances = traverse_pass.read(instances);
-        traverse_data.queue_in = traverse_pass.read(ready);
-
-        const produced = traverse_data.queue_out = traverse_pass.write(spare);
-
-        claim = traverse_data.claim = traverse_pass.write(claim);
-        feedback = traverse_data.feedback = traverse_pass.write(feedback);
-        meshlets = traverse_data.out_meshlets = traverse_pass.write(meshlets);
-
-        // what this wavefront produced is what the next one consumes, and the drained one is spare
-        ready_queue = produced;
-        spare_queue = ready;
-    }
-
-    /*
-     One more pass, for one number. The loop above records a fixed number of prepare/traverse pairs
-     and the queue can still hold work when the last of them finishes — a subtree never descended,
-     which is a hole rather than a coarse stand-in, and the one degradation §4.5 admits. This is
-     where `VGEO_CUT_STAT.QUEUE_REMAINING` comes from.
-
-     It is not the prepare pass: that one runs *between* wavefronts and once per iteration per
-     expansion site, so what it could report is a frontier rather than a remainder, and the next
-     site would overwrite it. See {@link shader_vgeo_cut_queue_remainder}.
-
-     `ready_queue` and not either buffer by name: which of the two holds the produced queue
-     alternates per iteration, so the roles are carried through the loop rather than named here.
-     */
-    const tail_data = {};
-
-    const tail_pass = graph.add("vg queue tail", tail_data, (data, resources, context) => {
-        shader_vgeo_cut_queue_remainder.dispatch({
-            encoder: context.encoder,
-            bindings: {
-                params: view_cut.params_buffer,
-                queue_ready: resources.get(data.queue_ready),
-                feedback: resources.get(data.feedback),
-            }
-        });
+    const descent = graph_vgeo_cut_descent({
+        graph,
+        runtime,
+        cut: view_cut,
+        instances: collect_data.instances,
+        prefix_sums,
+        feedback: collect_data.feedback,
+        traverse: shader_vgeo_cut_traverse,
+        bindings: { frontier: view_cut.frontier_buffer },
+        outputs: { out_meshlets: output_meshlets },
     });
 
-    tail_data.queue_ready = tail_pass.read(ready_queue);
-
-    feedback = tail_data.feedback = tail_pass.write(feedback);
+    const feedback = descent.feedback;
+    const meshlets = descent.outputs.out_meshlets;
 
     /*
      Every expansion of this graph writes into one feedback buffer, so the next one has to start

package/src/shade/renderer/geometry/virtual/sdf/VGEO_SDF.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Words of the payload's header for `job_count` jobs: their counters, then the cut's own counters from its feedback
+ * slot (`VGEO_CUT_STAT`), which say whether the cut left a subtree undescended.
+ *
+ * @param {number} job_count
+ * @returns {number}
+ */
+export function vgeo_sdf_header_words(job_count: number): number;
+/**
+ * The extraction's settings, an immediate of each of its passes.
+ * @type {WebGPUStruct}
+ */
+export const VGEO_SDF_SETTINGS: WebGPUStruct;
+/**
+ * A job the frame cuts, as the host writes it: the vgeo geometry row it cuts and the projection constant that puts its
+ * error against a τ of 1, `1 / (½ voxel)` in the geometry's own units. A job the frame writes out (`decode` 1) has its
+ * room in the payload: `vertex_count` vertices from `vertex_base` and `triangle_count` triangles from `triangle_base`,
+ * what its last complete cut held.
+ * @type {WebGPUStruct}
+ */
+export const VGEO_SDF_JOB_STRUCT: WebGPUStruct;
+/**
+ * A job's counters, atomics the frame's passes add into: the clusters its cut took, the stand-ins among them (a
+ * cluster taken for a page not resident or a group held), those dropped past the cluster list, the vertices and
+ * triangles of its listed clusters, and of those, what the decode wrote into its room.
+ */
+export const VGEO_SDF_COUNTER: Readonly<{
+    TAKEN: 0;
+    STAND_INS: 1;
+    DROPPED: 2;
+    VERTICES: 3;
+    TRIANGLES: 4;
+    VERTICES_WRITTEN: 5;
+    TRIANGLES_WRITTEN: 6;
+}>;
+/**
+ * Words of a job's counters.
+ * @type {number}
+ */
+export const VGEO_SDF_COUNTER_WORDS: number;
+/**
+ * Words of a cluster list entry: its job, then its meshlet row.
+ * @type {number}
+ */
+export const VGEO_SDF_CLUSTER_WORDS: number;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=VGEO_SDF.d.ts.map

package/src/shade/renderer/geometry/virtual/sdf/VGEO_SDF.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_SDF.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/sdf/VGEO_SDF.js"],"names":[],"mappings":"AAsEA;;;;;;GAMG;AACH,iDAHW,MAAM,GACJ,MAAM,CAIlB;AArED;;;GAGG;AACH,gCAFU,YAAY,CAWA;AAEtB;;;;;;GAMG;AACH,kCAFU,YAAY,CAWL;AAEjB;;;;GAIG;AACH;;;;;;;;GAQG;AAEH;;;GAGG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;GAGG;AACH,qCAFU,MAAM,CAEwB;6BAnEX,sCAAsC"}

package/src/shade/renderer/geometry/virtual/sdf/VGEO_SDF.js

@@ -0,0 +1,80 @@
+import { f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { VGEO_CUT_STAT_COUNT } from "../runtime/layout/VGEO_CUT_STAT_COUNT.js";
+
+/*
+ The layouts of a vgeo geometry's proxy extraction (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8, as S8 built it): each geometry
+ whose cache is asked for is cut whole at half its cache's level-0 voxel, its cut's clusters listed, and, once a cut
+ stands nothing in, its vertices and triangles written out and read back for the proxy the mesh bake bakes.
+*/
+
+/**
+ * The extraction's settings, an immediate of each of its passes.
+ * @type {WebGPUStruct}
+ */
+export const VGEO_SDF_SETTINGS = WebGPUStruct.from({
+    /** jobs the frame cuts */
+    job_count: u32,
+    /** entries the cluster list holds */
+    cluster_capacity: u32,
+    /** the word of the payload its vertices start at, 3 floats a vertex */
+    vertex_offset: u32,
+    /** the word of the payload its triangles start at, 3 indices a triangle */
+    index_offset: u32,
+}, "VGeoSDFSettings");
+
+/**
+ * A job the frame cuts, as the host writes it: the vgeo geometry row it cuts and the projection constant that puts its
+ * error against a τ of 1, `1 / (½ voxel)` in the geometry's own units. A job the frame writes out (`decode` 1) has its
+ * room in the payload: `vertex_count` vertices from `vertex_base` and `triangle_count` triangles from `triangle_base`,
+ * what its last complete cut held.
+ * @type {WebGPUStruct}
+ */
+export const VGEO_SDF_JOB_STRUCT = WebGPUStruct.from({
+    vg_row: u32,
+    projection_k: f32,
+    decode: u32,
+    vertex_base: u32,
+    triangle_base: u32,
+    vertex_count: u32,
+    triangle_count: u32,
+    pad: u32,
+}, "VGeoSDFJob");
+
+/**
+ * A job's counters, atomics the frame's passes add into: the clusters its cut took, the stand-ins among them (a
+ * cluster taken for a page not resident or a group held), those dropped past the cluster list, the vertices and
+ * triangles of its listed clusters, and of those, what the decode wrote into its room.
+ */
+export const VGEO_SDF_COUNTER = Object.freeze({
+    TAKEN: 0,
+    STAND_INS: 1,
+    DROPPED: 2,
+    VERTICES: 3,
+    TRIANGLES: 4,
+    VERTICES_WRITTEN: 5,
+    TRIANGLES_WRITTEN: 6,
+});
+
+/**
+ * Words of a job's counters.
+ * @type {number}
+ */
+export const VGEO_SDF_COUNTER_WORDS = 8;
+
+/**
+ * Words of a cluster list entry: its job, then its meshlet row.
+ * @type {number}
+ */
+export const VGEO_SDF_CLUSTER_WORDS = 2;
+
+/**
+ * Words of the payload's header for `job_count` jobs: their counters, then the cut's own counters from its feedback
+ * slot (`VGEO_CUT_STAT`), which say whether the cut left a subtree undescended.
+ *
+ * @param {number} job_count
+ * @returns {number}
+ */
+export function vgeo_sdf_header_words(job_count) {
+    return job_count * VGEO_SDF_COUNTER_WORDS + VGEO_CUT_STAT_COUNT;
+}