@woosh/meep-engine 3.25.0 → 3.27.0

package/src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_traverse.js

@@ -3,6 +3,7 @@ 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 { WebGPUExtensionType } from "../../../../../descriptor/WebGPUExtensionType.js";
 import { COLLECTION_U32_STRUCT_READ } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
 import { COLLECTION_U32_STRUCT_WRITE } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
 import { MESHLET_COLLECTION_WRITE_STRUCT } from "../../../../rasterize/MESHLET_COLLECTION_WRITE_STRUCT.js";
@@ -17,16 +18,19 @@ import { VGEO_NODE_ROW_OFFSET } from "../layout/VGEO_NODE_ROW_OFFSET.js";
 import { VGEO_NO_CHILD_PAGE } from "../layout/VGEO_NO_CHILD_PAGE.js";
 import { VGEO_PAGE_ROW_NONE } from "../layout/VGEO_PAGE_ROW_NONE.js";
 import { VGEO_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
+import { VGEO_PARENT_ROW_OFFSET } from "../layout/VGEO_PARENT_ROW_OFFSET.js";
+import { VGEO_QUEUE_TARGET_PARENT_BIT } from "../layout/VGEO_QUEUE_TARGET_PARENT_BIT.js";
 import { VGEO_QUEUE_TARGET_GROUP_BIT } from "../layout/VGEO_QUEUE_TARGET_GROUP_BIT.js";
 import { VGEO_WANT_WORDS } from "../layout/VGEO_WANT_WORDS.js";
 import { chunk_vgeo_cut_access } from "./chunk_vgeo_cut_access.js";
+import { VGEO_CUT_EXPAND } from "./VGEO_CUT_EXPAND.js";
+import { VGEO_CUT_FLAG_COARSEN } from "./VGEO_CUT_FLAG_COARSEN.js";
 import { VGEO_CUT_FLAG_CULL } from "./VGEO_CUT_FLAG_CULL.js";
 import { VGEO_CUT_PARAMS_STRUCT } from "./VGEO_CUT_PARAMS_STRUCT.js";
 import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
 
 /**
- * One wavefront of the virtual-geometry cut — the pass design §7 calls for, and the reason every
- * structure under it exists.
+ * The virtual-geometry cut — design §7's pass, as a descent that lives inside one dispatch.
  *
  * ## The rule
  *
@@ -35,29 +39,67 @@ import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
  * > `own group selectable AND project(parent) > tau AND (project(self) <= tau OR child group not
  * > selectable)`
  *
- * which is design §4's per-cluster form **plus its first term**. That term is not decoration, and
- * omitting it — as §4's own wording does, because §4 was written for a traversal that gets it for
- * free — double-draws: a group that is resident but not yet selectable has clusters satisfying the
- * rest of the rule while their coarse stand-in is drawn over the same surface, a few microns apart,
- * with the depth buffer choosing between them. That reads as corrupt geometry rather than as a
- * missing page, which is what makes it hard to attribute and worth stating first.
+ * which is design §4's per-cluster form together with its first term. That term is load-bearing
+ * and §4 states the rule without it: a group that is resident but not yet selectable has clusters
+ * satisfying the rest of the rule while their coarse stand-in is drawn over the same surface, a few
+ * microns apart, with the depth buffer choosing between them. That reads as corrupt geometry rather
+ * than as a missing page, which is what makes it hard to attribute and worth stating first.
  *
  * ## The shape
  *
- * A wavefront BFS, ping-ponged through two queues, one lane per item. Not persistent threads over
- * an MPMC queue: WebGPU guarantees no forward progress across workgroups, so a consumer waiting on
- * a producer in another workgroup is waiting without a bound.
+ * The loop over depth is *inside* this kernel: a dispatch is a spill generation rather than a level
+ * of the descent. Depth is what a cut costs. Measured on a 28M-face container at tau = 1 on a 4090:
+ * the descent converges at **39 levels**, carrying 15,027 items — an average frontier of 385 items,
+ * or **six workgroups of 64 on a 128-SM part** — and an empty prepare/traverse pair costs 3.9 us
+ * whatever it contains. Page depth grows like log2(triangles), so a dispatch per level gets *worse*
+ * with better assets and no better with a faster GPU.
  *
- * An item is a **node visit** or a **group-chunk visit**, distinguished by one bit of `target`. A
- * node tests its metric and either enqueues its children or, being a leaf, enqueues bounded chunks
- * of its groups' clusters. Chunks exist because a node leaf covers up to four groups of up to 4096
- * clusters each (format §11.5) — legal input, and 16,384 iterations in the lane that popped it if
- * the leaf walked them itself.
+ * What a lane cannot do is wait for another workgroup: WebGPU guarantees no forward progress across
+ * workgroups, so persistent threads over an MPMC queue — Nanite's answer — is unbounded waiting.
+ * What a lane *can* do is cooperate with the other lanes of its own subgroup, and that is enough:
  *
- * Descent crosses a page boundary by enqueueing the child page's **node 0**: uniform items, one
- * kernel, no special case for "entering a page". `SAME_PAGE` needs no special case either, because
- * the CPU resolved it to this page's own index at install, so it looks up a page that is trivially
- * resident and falls through to the only question it was really asking — is that group selectable.
+ * - Every lane executes its item and says how many children it produced. No lane walks its own
+ *   subtree while its neighbours idle; production is a **count**, at constant cost.
+ * - `subgroupExclusiveAdd` over those counts numbers the wave's whole production densely. The first
+ *   `subgroup_size` of them are taken back into the wave's own lanes — perfectly packed, one child
+ *   per lane, whoever produced them — and the descent takes another step without touching memory.
+ * - Everything past a full wave **spills** to the global queue under one `atomicAdd`. Breadth the
+ *   wave cannot hold becomes work for other waves rather than a serial loop inside this one.
+ *
+ * So the number of dispatches is the number of spill generations, and the narrow top of the DAG —
+ * twenty levels that move between 1 and 120 items and draw nothing — is one wave taking twenty
+ * steps in registers.
+ *
+ * This is Karis' "Variable sized work" (graphicrants, 2026-03) with its groupshared scatter
+ * removed. That scatter needs HLSL's `GroupMemoryBarrier()` — memory ordering with no execution
+ * sync, sound because a wave is in lockstep — and WGSL has no memory-only workgroup barrier.
+ * `workgroupBarrier` synchronizes execution as well, which pins every subgroup of the workgroup to
+ * the same number of steps and is a deadlock the moment they disagree; `workgroupUniformLoad` is
+ * that same control barrier plus a load, and what it returns is one value uniform across the
+ * workgroup, which is the opposite of the per-lane read a scatter is made of.
+ * {@link vg_child_owner} finds each item's producer by binary search over the same prefix sums
+ * instead: `log2(subgroup_size)` shuffles, no workgroup memory and no barrier anywhere in this
+ * file, so nothing here needs the workgroup to agree on anything.
+ *
+ * ## What WGSL will not let this do
+ *
+ * Every loop around a subgroup operation needs a **uniform trip count**, and nothing launders one —
+ * not `subgroupAdd`, not `subgroupMax`, not even `subgroupBroadcastFirst`, which launders a value
+ * for a use but not for control flow. Nor may such a loop carry a non-uniform `break`, `continue`
+ * or `return`. So the descent runs `params.descent_steps` times and masks; a wave that drains its
+ * subtree early pays the remaining steps at about ten instructions each rather than leaving. That
+ * makes `descent_steps` a tuning knob rather than a safety bound, and
+ * `VGEO_CUT_STAT.QUEUE_REMAINING` is what says when it is set too low.
+ *
+ * Divergence *inside* the loop is free: Tint models reconvergence, so a non-uniform `if` that opens
+ * and closes taints nothing after it, and the spill's per-lane loop is fine because it contains no
+ * subgroup operation of its own.
+ *
+ * ## One lane per cluster
+ *
+ * A leaf produces one item per cluster of its groups and the wave packs them, so what bounds a
+ * lane's work is the packing rather than a chunk size, and consecutive lanes read consecutive
+ * cluster rows instead of striding over runs of them.
  *
  * ## Why page-granular dedup is enough, and why it is necessary
  *
@@ -83,6 +125,11 @@ import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
  *   `max_parent_error` is at least `P.parent_error`, so the LOD cull cannot fire, and the frustum
  *   cull fires only where `C` is off-screen anyway.
  *
+ * Descent crosses a page boundary by producing the child page's **node 0**: uniform items, one
+ * kernel, no special case for "entering a page". `SAME_PAGE` needs no special case either, because
+ * the CPU resolved it to this page's own index at install, so it looks up a page that is trivially
+ * resident and falls through to the only question it was really asking — is that group selectable.
+ *
  * ## Bounds
  *
  * Every append is checked and every overflow is counted, and they all degrade in one direction —
@@ -92,10 +139,11 @@ import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
  *
  * ## Bindings
  *
- * Eight storage buffers against the engine's floor of ten (RUNTIME_PLAN §4.9), and the page table
- * is not one of them: a page's header is the first words of its own arena slot, so `vg_page_field`
- * is an offset into a buffer this kernel already binds rather than a second buffer to bind and keep
- * coherent.
+ * Nine storage buffers against the engine's floor of ten (RUNTIME_PLAN §4.9) — the tightest kernel
+ * of the cut, and `vgeo_cut_shaders.compile.spec.js` holds the exact count rather than the bound.
+ * The page table is not one of them: a page's header is the first words of its own arena slot, so
+ * `vg_page_field` is an offset into a buffer this kernel already binds rather than a second buffer
+ * to bind and keep coherent.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -122,9 +170,20 @@ resources.createGroup()
     // one bit per (instance, page ordinal); cleared per invocation because each expansion site
     // sees a different instance set
     .addStorageBuffer("claim", WebGPUArray.from(atomic_u32), true)
-    // header, stats, touch and want stamps, then the two lists — one per frame, shared by every
-    // view and bucket, which is what dedups a touch across them
+    /*
+     The tenth, and the last this kernel can have: `Renderer.js` requires ten storage
+     buffers per stage of an adapter and refuses one that offers fewer. It is spent on the
+     frontier because the alternative — deriving the page set afterwards from the draw
+     records — costs a pass over every drawn cluster to recover a fact the claim already
+     knew at the moment it was established.
+    */
+    .addStorageBuffer("frontier", WebGPUArray.from(atomic_u32), true)
+    // header, stats, one touch bit per page row, then the want records — one per frame, shared by
+    // every view and bucket, which is what dedups a touch across them
     .addStorageBuffer("feedback", WebGPUArray.from(atomic_u32), true)
+    // one stamp per lookup word, persistent across frames and tagged with the frame that wrote it,
+    // so a want is deduped without a lookup-sized clear every frame
+    .addStorageBuffer("vg_want_stamps", WebGPUArray.from(atomic_u32), true)
     // the same collection the static mesh expansion appends to, read downstream by the HZB meshlet
     // filter and the indirect draw with no knowledge that virtual geometry exists
     .addStorageBuffer("out_meshlets", MESHLET_COLLECTION_WRITE_STRUCT, true)
@@ -134,37 +193,52 @@ const body = CodeChunk.from(
     //language=WGSL
     `
 const VG_QUEUE_GROUP_BIT = ${VGEO_QUEUE_TARGET_GROUP_BIT}u;
+const VG_QUEUE_PARENT_BIT = ${VGEO_QUEUE_TARGET_PARENT_BIT}u;
 const VG_PAGE_ROW_NONE = ${VGEO_PAGE_ROW_NONE}u;
 const VG_NO_CHILD_PAGE = ${VGEO_NO_CHILD_PAGE}u;
 const VG_GROUP_SELECTABLE = ${VGEO_GROUP_FLAG_SELECTABLE}u;
 const VG_WANT_WORDS = ${VGEO_WANT_WORDS}u;
 
-fn vg_stat(slot: u32, amount: u32) {
-    atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + slot], amount);
-}
+const VG_EXPAND_NONE = ${VGEO_CUT_EXPAND.NONE}u;
+const VG_EXPAND_NODES = ${VGEO_CUT_EXPAND.NODES}u;
+const VG_EXPAND_CLUSTERS = ${VGEO_CUT_EXPAND.CLUSTERS}u;
+const VG_EXPAND_PAGE = ${VGEO_CUT_EXPAND.PAGE}u;
+const VG_EXPAND_PARENTS = ${VGEO_CUT_EXPAND.PARENTS}u;
 
 /**
- * Reserve count slots of the next wavefront.
+ * One unit of work: a node visit, or a single cluster of one group.
  *
- * The count is allowed to run past capacity — the prepare pass clamps it before it becomes a
- * dispatch — so every write against the returned base is bounds-checked here as well.
+ * The same four words the queue holds, and bit 31 of \`visit\` tells the two apart — a node
+ * index below it, a group index above it with \`aux\` naming the cluster inside that group.
  */
-fn vg_queue_reserve(count: u32) -> u32 {
-    return atomicAdd(&queue_out.count, count);
+struct VGItem {
+    instance_slot: u32,
+    page_row: u32,
+    visit: u32,
+    aux: u32,
 }
 
-fn vg_queue_write(slot: u32, instance_slot: u32, page_row: u32, visit: u32, first_cluster: u32) {
-    if (slot >= params.queue_capacity) {
-        vg_stat(${VGEO_CUT_STAT.QUEUE_DROPPED}u, 1u);
-        return;
-    }
+/**
+ * What an executed item wants done next, as a count and a rule for the k-th child rather than as
+ * children written somewhere.
+ *
+ * This is the whole reason the descent can stay in registers: a producer states its production at
+ * constant cost and any lane of the wave can then build child \`k\` of it from five numbers.
+ */
+struct VGExpand {
+    kind: u32,
+    count: u32,
+    page_row: u32,
+    first: u32,
+    span: u32,
+}
 
-    let base = slot * 4u;
+fn vg_expand_none() -> VGExpand {
+    return VGExpand(VG_EXPAND_NONE, 0u, 0u, 0u, 0u);
+}
 
-    queue_out.elements[base] = instance_slot;
-    queue_out.elements[base + 1u] = page_row;
-    queue_out.elements[base + 2u] = visit;
-    queue_out.elements[base + 3u] = first_cluster;
+fn vg_stat(slot: u32, amount: u32) {
+    atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + slot], amount);
 }
 
 /**
@@ -208,21 +282,12 @@ fn vg_claim_page(instance_base: u32, page_row: u32) -> bool {
  * the pages that are on screen and evicts them, which is the classic fallback-chain bug the virtual
  * texture cache already keys on touch to avoid.
  *
- * Deduped across every view and bucket of the frame by one stamp word per page row, because the
- * feedback buffer is per frame rather than per invocation.
+ * One bit per page row, because the feedback buffer is per frame rather than per invocation: the
+ * bit dedups across every view and bucket of the frame and is the record the host reads, so
+ * there is no list to fill and no touch a full list could lose.
  */
 fn vg_touch_page(page_row: u32) {
-    if (atomicExchange(&feedback[params.touch_stamp_base + page_row], 1u) != 0u) {
-        return;
-    }
-
-    let slot = atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.TOUCH_COUNT}u], 1u);
-
-    if (slot >= params.touch_capacity) {
-        return;
-    }
-
-    atomicStore(&feedback[params.touch_base + slot], page_row);
+    atomicOr(&feedback[params.touch_bits_base + (page_row >> 5u)], 1u << (page_row & 31u));
 }
 
 /**
@@ -241,9 +306,10 @@ fn vg_touch_page(page_row: u32) {
  * and VGeoResidencyManager maxes across frames.
  */
 fn vg_want(source_page_row: u32, child_ref: u32, child_page_index: u32, lookup_base: u32, projected: f32) {
-    let stamp = params.want_stamp_base + lookup_base + child_page_index;
-
-    if (atomicExchange(&feedback[stamp], 1u) != 0u) {
+    // persistent and frame-tagged rather than cleared: a stamp already holding this frame's tag
+    // was written by this frame, and anything else is a frame that has gone
+    if (atomicExchange(&vg_want_stamps[lookup_base + child_page_index], params.frame_tag)
+        == params.frame_tag) {
         return;
     }
 
@@ -282,18 +348,41 @@ fn vg_draw(page_row: u32, cluster: u32, mesh_index: u32) {
     out_meshlets.elements[slot] = ${MESHLET_DEFINITION_STRUCT.wgsl_ref}(meshlet, mesh_index);
 
     vg_stat(${VGEO_CUT_STAT.DRAWN}u, 1u);
+
+    /*
+     And remember the page for next frame. The frontier is where this cut *ended*, not
+     everywhere it went: recording at the claim instead would name every page the descent
+     passed through on its way down, and reseeding from that set is more work than the root
+     descent it replaces rather than less. A page that drew something is a page the cut is
+     standing on.
+
+     A bitmask, so the several clusters of a page that draw cost one bit and no dedup. Per view,
+     so two views keep their own answer.
+    */
+    let frontier_word = page_row >> 5u;
+
+    if (frontier_word < params.frontier_word_count) {
+        atomicOr(&frontier[frontier_word], 1u << (page_row & 31u));
+    }
 }
 
-fn vg_group_selectable(page_row: u32, group: u32) -> bool {
-    let row = vg_group_base(page_row) + group * VG_GROUP_ROW_WORDS;
+fn vg_group_row(page_row: u32, group: u32) -> u32 {
+    return vg_group_base(page_row) + group * VG_GROUP_ROW_WORDS;
+}
 
-    return (vg_arena[row + ${VGEO_GROUP_ROW_OFFSET.FLAGS}u] & VG_GROUP_SELECTABLE) != 0u;
+fn vg_group_selectable(page_row: u32, group: u32) -> bool {
+    return (vg_arena[vg_group_row(page_row, group) + ${VGEO_GROUP_ROW_OFFSET.FLAGS}u]
+        & VG_GROUP_SELECTABLE) != 0u;
 }
 
 /**
- * A node: cull, then descend or hand off.
+ * A node: cull, then say what it expands into.
+ *
+ * Nothing is enqueued here. An interior node expands into its child nodes and a leaf into every
+ * cluster of its groups, and either is a base and a count — which is what lets the wave take the
+ * first \`subgroup_size\` of them into its own lanes and spill the rest.
  */
-fn vg_visit_node(instance_slot: u32, instance_base: u32, page_row: u32, node: u32) {
+fn vg_visit_node(instance_base: u32, page_row: u32, node: u32) -> VGExpand {
     let row = vg_node_base(page_row) + node * VG_NODE_ROW_WORDS;
 
     let sphere = vg_sphere_at(row + ${VGEO_NODE_ROW_OFFSET.SPHERE}u);
@@ -301,7 +390,7 @@ fn vg_visit_node(instance_slot: u32, instance_base: u32, page_row: u32, node: u3
     if ((params.flags & ${VGEO_CUT_FLAG_CULL}u) != 0u
         && vg_sphere_outside_frustum(instance_base, sphere)) {
         vg_stat(${VGEO_CUT_STAT.CULLED_FRUSTUM}u, 1u);
-        return;
+        return vg_expand_none();
     }
 
     let eye = vg_instance_eye(instance_base);
@@ -312,11 +401,26 @@ fn vg_visit_node(instance_slot: u32, instance_base: u32, page_row: u32, node: u3
      *largest* parent error under this node still projects to no more than tau, nothing under it can
      be drawn and the whole subtree goes. The node's sphere is the union of the covered clusters'
      parent spheres, so the projection is conservative in both terms.
-     */
-    if (vg_project(vg_arena_f32(row + ${VGEO_NODE_ROW_OFFSET.MAX_PARENT_ERROR}u), sphere, eye, k)
-        <= params.tau) {
+
+     **It is a descent-only accelerator**, and the coarsen flag turns it off. Its premise is that
+     a subtree nothing can be drawn in is a subtree worth skipping, which is true of a traversal
+     that only ever looks for what to draw. A walk up is looking for something else: the groups
+     under this node are below the cut, and being below the cut is precisely what sends them to
+     their parents. Skipping them here is what made a cut seeded at the leaves draw nothing at all
+     -- the subtree carrying the whole walk was pruned at its first node, silently and by a rule
+     that is correct for the direction it was written for.
+
+     A node has no parent list of its own -- the upward edge is per group (format §6.3) -- so
+     there is nothing to coarsen *from* here, and entering the subtree is the only way to reach
+     the groups that can. That is the cost of walking up through a page: the pages on the way
+     are evaluated whole. It is why CUT_PLAN §1 keeps a frontier at all rather than re-deriving
+     one, and why the frontier is what makes this affordable rather than this pass.
+    */
+    if ((params.flags & ${VGEO_CUT_FLAG_COARSEN}u) == 0u
+        && vg_project(vg_arena_f32(row + ${VGEO_NODE_ROW_OFFSET.MAX_PARENT_ERROR}u), sphere, eye, k)
+            <= params.tau) {
         vg_stat(${VGEO_CUT_STAT.CULLED_LOD}u, 1u);
-        return;
+        return vg_expand_none();
     }
 
     let child_first = vg_arena[row + ${VGEO_NODE_ROW_OFFSET.CHILD_FIRST}u];
@@ -325,197 +429,479 @@ fn vg_visit_node(instance_slot: u32, instance_base: u32, page_row: u32, node: u3
     let child_count = child_word & VG_NODE_CHILD_COUNT_MASK;
 
     if ((child_word & VG_NODE_LEAF_BIT) == 0u) {
-        let slot = vg_queue_reserve(child_count);
-
-        for (var i = 0u; i < child_count; i = i + 1u) {
-            vg_queue_write(slot + i, instance_slot, page_row, child_first + i, 0u);
-        }
-
-        return;
+        return VGExpand(VG_EXPAND_NODES, child_count, page_row, child_first, 0u);
     }
 
-    // A leaf's children are groups. Hand them off in bounded chunks rather than walking them here:
-    // four groups of four thousand clusters is legal input and would be one lane's whole life.
-    let group_base = vg_group_base(page_row);
-
+    // a leaf's children are groups, and its production is every cluster they hold
     var total = 0u;
 
     for (var i = 0u; i < child_count; i = i + 1u) {
-        let members = vg_arena[
-            group_base + (child_first + i) * VG_GROUP_ROW_WORDS
-                + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT}u
+        total = total + vg_arena[
+            vg_group_row(page_row, child_first + i) + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT}u
         ];
-
-        total = total + (members + params.cluster_chunk - 1u) / params.cluster_chunk;
     }
 
-    var slot = vg_queue_reserve(total);
+    return VGExpand(VG_EXPAND_CLUSTERS, total, page_row, child_first, child_count);
+}
 
-    for (var i = 0u; i < child_count; i = i + 1u) {
-        let group = child_first + i;
+/**
+ * The k-th cluster under a leaf, as a group and an index inside it.
+ *
+ * Bounded by the leaf's own group count and branchless, which are both about the same hazard. Every
+ * lane of the wave runs this, including the lanes past the end of the wave's production, and those
+ * hold a \`k\` with no cluster behind it. A walk that stopped when it found the group would run off
+ * the end of the group rows for them, and a run of zero-member rows is an infinite loop rather than
+ * a wrong answer — a hung GPU, on data the builder is free to produce.
+ *
+ * Their result is nonsense and is never executed, because the lane is inactive. It only has to be
+ * in-range and finite.
+ *
+ * It is a loop with a non-uniform trip count and no subgroup operation inside, which WGSL permits
+ * and which taints nothing after it.
+ */
+fn vg_leaf_cluster(page_row: u32, group_first: u32, group_count: u32, k: u32) -> vec2<u32> {
+    var remaining = k;
+    var group = 0u;
+    var found = false;
 
+    for (var i = 0u; i < group_count; i = i + 1u) {
         let members = vg_arena[
-            group_base + group * VG_GROUP_ROW_WORDS + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT}u
+            vg_group_row(page_row, group_first + i) + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT}u
         ];
 
-        var first = 0u;
+        /*
+         The latch is the whole of it. Walking on without one is not a slower answer but a wrong
+         one: the walk keeps testing \`remaining\` against later groups, and any later group smaller
+         than the remainder it already settled on takes the item off the group that owns it. Two
+         values of k then name one cluster, and one cluster drawn twice is the exact failure the
+         claim bitmask and the own-group term exist to prevent.
+         */
+        let here = !found && remaining < members;
 
-        while (first < members) {
-            vg_queue_write(slot, instance_slot, page_row, group | VG_QUEUE_GROUP_BIT, first);
+        group = select(group, i, here);
+        found = found || here;
 
-            slot = slot + 1u;
-            first = first + params.cluster_chunk;
-        }
+        // consumed only while still searching, so this never underflows
+        remaining = select(remaining - members, remaining, found);
     }
+
+    return vec2<u32>(group_first + group, remaining);
 }
 
 /**
- * A run of one group's clusters: the rule, cluster by cluster.
+ * One cluster: the rule, once.
  */
-fn vg_visit_group(
-    instance_slot: u32,
+fn vg_visit_cluster(
     instance_base: u32,
     page_row: u32,
     group: u32,
-    first_cluster: u32
-) {
+    member: u32
+) -> VGExpand {
     /*
      The own-group term. A group that is resident but not selectable draws nothing at all — its
      coarser selectable ancestors are already covering that surface, and drawing both is the
      double-draw this whole runtime is arranged to avoid.
      */
     if (!vg_group_selectable(page_row, group)) {
-        return;
+        return vg_expand_none();
     }
 
-    let group_row = vg_group_base(page_row) + group * VG_GROUP_ROW_WORDS;
-
-    let members = vg_arena[group_row + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT}u];
-    let cluster_first = vg_arena[group_row + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_FIRST}u];
+    let group_row = vg_group_row(page_row, group);
 
-    let last = min(first_cluster + params.cluster_chunk, members);
+    let cluster = vg_arena[group_row + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_FIRST}u] + member;
 
-    let cluster_base = vg_cluster_base(page_row);
+    let row = vg_cluster_base(page_row) + cluster * VG_CLUSTER_ROW_WORDS;
 
     let eye = vg_instance_eye(instance_base);
     let k = vg_instance_f32(instance_base, ${VGEO_INSTANCE_OFFSET.PROJECTION_K}u);
     let mesh_index = instances[instance_base + ${VGEO_INSTANCE_OFFSET.MESH_INDEX}u];
     let lookup_base = instances[instance_base + ${VGEO_INSTANCE_OFFSET.LOOKUP_WORD_OFFSET}u];
 
-    for (var i = first_cluster; i < last; i = i + 1u) {
-        let cluster = cluster_first + i;
+    vg_stat(${VGEO_CUT_STAT.CLUSTERS_TESTED}u, 1u);
 
-        let row = cluster_base + cluster * VG_CLUSTER_ROW_WORDS;
+    /*
+     Before the cluster can refine, and the reason is residency rather than the draw: refining
+     claims the child page, and a claim is a touch — the LRU's whole input — so an off-screen
+     cluster that refined anyway would keep pages nobody can see hot and the tier full of them.
+     self_sphere contains the cluster's own vertices (FORMAT §7), so this rejects nothing on
+     screen; and every parent of a group shares one self_sphere, so a group's parents decide this
+     uniformly and the cut's proofs stand (RUNTIME_PLAN §4.4).
+     */
+    if ((params.flags & ${VGEO_CUT_FLAG_CULL}u) != 0u
+        && vg_sphere_outside_frustum(
+            instance_base, vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_SPHERE}u)
+        )) {
+        vg_stat(${VGEO_CUT_STAT.CULLED_CLUSTER}u, 1u);
 
-        vg_stat(${VGEO_CUT_STAT.CLUSTERS_TESTED}u, 1u);
+        return vg_expand_none();
+    }
 
-        let parent_projected = vg_project(
-            vg_arena_f32(row + ${VGEO_CLUSTER_ROW_OFFSET.PARENT_ERROR}u),
-            vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.PARENT_SPHERE}u),
-            eye, k
-        );
+    let parent_projected = vg_project(
+        vg_arena_f32(row + ${VGEO_CLUSTER_ROW_OFFSET.PARENT_ERROR}u),
+        vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.PARENT_SPHERE}u),
+        eye, k
+    );
 
-        if (parent_projected <= params.tau) {
-            // something coarser is covering this surface; this cluster is below the cut
-            continue;
+    if (parent_projected <= params.tau) {
+        /*
+         Below the cut: something coarser covers this surface. A descent from the root never
+         arrives here -- it only descends through a step that projected above tau -- so this
+         is the branch a cut that was *kept* between frames lands in when the camera pulls
+         back, and stopping is what makes such a cut unable to coarsen.
+
+         parent_error and parent_sphere are the consuming step's, and every cluster of a group
+         shares that one step (FORMAT section 11.16), so this decision is group-uniform and
+         the group's first member can carry it alone. That is an election with nothing to
+         communicate: the other members reach the same answer and defer to the same lane.
+        */
+        let group_row_here = vg_group_row(page_row, group);
+
+        let parent_count = vg_arena[group_row_here + ${VGEO_GROUP_ROW_OFFSET.PARENT_COUNT}u];
+
+        if ((params.flags & ${VGEO_CUT_FLAG_COARSEN}u) == 0u || member != 0u
+            || parent_count == 0u) {
+            return vg_expand_none();
         }
 
-        let self_projected = vg_project(
-            vg_arena_f32(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_ERROR}u),
-            vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_SPHERE}u),
-            eye, k
+        return VGExpand(
+            VG_EXPAND_PARENTS,
+            parent_count,
+            page_row,
+            vg_arena[group_row_here + ${VGEO_GROUP_ROW_OFFSET.PARENT_FIRST}u],
+            0u
         );
+    }
 
-        let child_page_index = vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX}u];
+    let self_projected = vg_project(
+        vg_arena_f32(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_ERROR}u),
+        vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_SPHERE}u),
+        eye, k
+    );
 
-        if (self_projected <= params.tau || child_page_index == VG_NO_CHILD_PAGE) {
-            vg_draw(page_row, cluster, mesh_index);
-            continue;
-        }
+    let child_page_index = vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX}u];
 
-        let child_page_row = vg_lookup[lookup_base + child_page_index];
+    if (self_projected <= params.tau || child_page_index == VG_NO_CHILD_PAGE) {
+        vg_draw(page_row, cluster, mesh_index);
+        return vg_expand_none();
+    }
 
-        if (child_page_row == VG_PAGE_ROW_NONE) {
-            /*
-             The clamp. Drawing this cluster is not a fallback for a missing one — it is the correct
-             coarser surface over exactly the region the missing page would have refined, which is
-             what makes an arriving cut watertight at every moment rather than only at the end.
-             */
-            vg_draw(page_row, cluster, mesh_index);
+    let child_page_row = vg_lookup[lookup_base + child_page_index];
 
-            vg_stat(${VGEO_CUT_STAT.CLAMPED}u, 1u);
+    if (child_page_row == VG_PAGE_ROW_NONE) {
+        /*
+         The clamp. Drawing this cluster is not a fallback for a missing one — it is the correct
+         coarser surface over exactly the region the missing page would have refined, which is
+         what makes an arriving cut watertight at every moment rather than only at the end.
+         */
+        vg_draw(page_row, cluster, mesh_index);
 
-            vg_want(
-                page_row,
-                vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_REF}u],
-                child_page_index,
-                lookup_base,
-                self_projected
-            );
+        vg_stat(${VGEO_CUT_STAT.CLAMPED}u, 1u);
 
-            continue;
-        }
+        vg_want(
+            page_row,
+            vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_REF}u],
+            child_page_index,
+            lookup_base,
+            self_projected
+        );
 
-        let child_group = vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_GROUP}u];
+        return vg_expand_none();
+    }
 
-        if (!vg_group_selectable(child_page_row, child_group)) {
-            /*
-             The bytes are here and the group is still waiting on a page holding one of its *other*
-             parents, so there is nothing to fetch from this cluster. Another cluster in this same
-             cut is clamped directly against that page and wants it — monotonicity puts every
-             ancestor of a cluster projecting above tau above tau as well.
-             */
-            vg_draw(page_row, cluster, mesh_index);
+    let child_group = vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_GROUP}u];
 
-            vg_stat(${VGEO_CUT_STAT.CLAMPED}u, 1u);
-            vg_stat(${VGEO_CUT_STAT.CLAMPED_ON_ACTIVATION}u, 1u);
+    if (!vg_group_selectable(child_page_row, child_group)) {
+        /*
+         The bytes are here and the group is still waiting on a page holding one of its *other*
+         parents, so there is nothing to fetch from this cluster. Another cluster in this same
+         cut is clamped directly against that page and wants it — monotonicity puts every
+         ancestor of a cluster projecting above tau above tau as well.
+         */
+        vg_draw(page_row, cluster, mesh_index);
 
-            continue;
-        }
+        vg_stat(${VGEO_CUT_STAT.CLAMPED}u, 1u);
+        vg_stat(${VGEO_CUT_STAT.CLAMPED_ON_ACTIVATION}u, 1u);
 
-        if (vg_claim_page(instance_base, child_page_row)) {
-            let slot = vg_queue_reserve(1u);
+        return vg_expand_none();
+    }
 
-            vg_queue_write(slot, instance_slot, child_page_row, 0u, 0u);
-        }
+    if (!vg_claim_page(instance_base, child_page_row)) {
+        // another lane, or another parent of this page, got there first
+        return vg_expand_none();
     }
+
+    return VGExpand(VG_EXPAND_PAGE, 1u, child_page_row, 0u, 0u);
 }
 
-@compute @workgroup_size(${VGEO_CUT_WORKGROUP_SIZE})
-fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
-    let item = global_id.x;
+/**
+ * One entry of a page's parent rows: the page holding that parent, claimed and queued.
+ *
+ * The mirror of the descent's page crossing, and deliberately page-granular like it. The
+ * entry names a cluster as well, and this ignores it: a page reached from any direction is
+ * evaluated whole, the rule is a pure function of each row, and visiting a cluster the walk
+ * did not need costs only the test. What the cluster half of the entry is for is the
+ * refine-side election of CUT_PLAN_2026_09_14 section 3, which is section 7.6's work.
+ *
+ * A parent that is not resident stops the walk rather than clamping. There is nothing to
+ * clamp *to* -- the surface this lane is standing on is below the cut and is not drawn -- so
+ * the honest answer is that this instance cannot be served incrementally this frame, which
+ * is the fallback section 4 already defines and section 7.6 wires up.
+ */
+fn vg_visit_parent(instance_base: u32, page_row: u32, entry: u32) -> VGExpand {
+    if (entry >= vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.PARENT_ENTRY_COUNT}u)) {
+        return vg_expand_none();
+    }
 
-    if (item == 0u && queue_in.count > 0u) {
-        /*
-         One per wavefront that actually ran. The descent is a fixed number of indirect dispatches
-         of zero workgroups once the work runs out, so this is the only way to know how deep it
-         went — and reaching the iteration budget is what turns RUNTIME_PLAN §4.7's measured depth
-         of about 48 from a fact into an assumption.
-         */
-        vg_stat(${VGEO_CUT_STAT.WAVEFRONTS}u, 1u);
+    let row = vg_parent_base(page_row) + entry * VG_PARENT_ROW_WORDS;
+
+    let parent_page_index = vg_arena[row + ${VGEO_PARENT_ROW_OFFSET.PAGE_INDEX}u];
+
+    if (parent_page_index == VG_NO_CHILD_PAGE) {
+        return vg_expand_none();
     }
 
-    if (item >= queue_in.count) {
-        return;
+    let lookup_base = instances[instance_base + ${VGEO_INSTANCE_OFFSET.LOOKUP_WORD_OFFSET}u];
+
+    let parent_page_row = vg_lookup[lookup_base + parent_page_index];
+
+    if (parent_page_row == VG_PAGE_ROW_NONE) {
+        return vg_expand_none();
+    }
+
+    if (!vg_claim_page(instance_base, parent_page_row)) {
+        // this page is already in this instance's cut, from above or from another parent
+        return vg_expand_none();
     }
 
-    let base = item * 4u;
+    return VGExpand(VG_EXPAND_PAGE, 1u, parent_page_row, 0u, 0u);
+}
 
-    let instance_slot = queue_in.elements[base];
-    let page_row = queue_in.elements[base + 1u];
-    let visit = queue_in.elements[base + 2u];
-    let first_cluster = queue_in.elements[base + 3u];
+/**
+ * Execute whatever this lane is holding.
+ */
+fn vg_execute(item: VGItem, holding: bool) -> VGExpand {
+    if (!holding) {
+        return vg_expand_none();
+    }
 
     vg_stat(${VGEO_CUT_STAT.ITEMS}u, 1u);
 
-    let instance_base = instance_slot * VG_INSTANCE_WORDS;
+    let instance_base = item.instance_slot * VG_INSTANCE_WORDS;
+
+    if ((item.visit & VG_QUEUE_GROUP_BIT) != 0u) {
+        return vg_visit_cluster(
+            instance_base, item.page_row, item.visit & ~VG_QUEUE_GROUP_BIT, item.aux
+        );
+    }
+
+    if ((item.visit & VG_QUEUE_PARENT_BIT) != 0u) {
+        return vg_visit_parent(
+            instance_base, item.page_row, item.visit & ~VG_QUEUE_PARENT_BIT
+        );
+    }
+
+    return vg_visit_node(instance_base, item.page_row, item.visit);
+}
+
+/**
+ * Child \`k\` of an expansion, as an item.
+ *
+ * Pure, and that is what lets the same rule serve both consumers: the lane that keeps a child calls
+ * it with values shuffled out of the producer's registers, and the lane that spills one calls it
+ * with its own.
+ */
+fn vg_child(instance_slot: u32, expand: VGExpand, k: u32) -> VGItem {
+    if (expand.kind == VG_EXPAND_NODES) {
+        return VGItem(instance_slot, expand.page_row, expand.first + k, 0u);
+    }
+
+    if (expand.kind == VG_EXPAND_CLUSTERS) {
+        let at = vg_leaf_cluster(expand.page_row, expand.first, expand.span, k);
+
+        return VGItem(instance_slot, expand.page_row, at.x | VG_QUEUE_GROUP_BIT, at.y);
+    }
 
-    if ((visit & VG_QUEUE_GROUP_BIT) != 0u) {
-        vg_visit_group(
-            instance_slot, instance_base, page_row, visit & ~VG_QUEUE_GROUP_BIT, first_cluster
+    if (expand.kind == VG_EXPAND_PARENTS) {
+        // entry first + k of the *producing* page's parent rows; the page it names is
+        // resolved and claimed when this item is executed, not here
+        return VGItem(
+            instance_slot, expand.page_row, (expand.first + k) | VG_QUEUE_PARENT_BIT, 0u
         );
-    } else {
-        vg_visit_node(instance_slot, instance_base, page_row, visit);
+    }
+
+    // VG_EXPAND_PAGE: the child page's node 0, which is how a descent crosses a page boundary
+    return VGItem(instance_slot, expand.page_row, 0u, 0u);
+}
+
+/**
+ * Which lane of the wave produced the item at \`index\` of its densely numbered production.
+ *
+ * The owner is the **largest** lane whose base is at or below the index — largest, because a lane
+ * that produced nothing repeats its neighbour's base, and a repeat sits at the start of the next
+ * producer's run rather than the end of the previous one. The bases are non-decreasing, so this is
+ * a binary search, and \`span\` starts at a builtin so the loop's trip count is uniform.
+ */
+fn vg_child_owner(first: u32, index: u32, lane_count: u32) -> u32 {
+    var owner = 0u;
+    var span = lane_count;
+
+    while (span > 1u) {
+        let step_half = span >> 1u;
+        let mid = owner + step_half;
+
+        // branchless: a non-uniform if around the next iteration's shuffle would not compile
+        owner = select(owner, mid, subgroupShuffle(first, mid) <= index);
+
+        span = span - step_half;
+    }
+
+    return owner;
+}
+
+fn vg_queue_write(slot: u32, item: VGItem) {
+    if (slot >= params.queue_capacity) {
+        vg_stat(${VGEO_CUT_STAT.QUEUE_DROPPED}u, 1u);
+        return;
+    }
+
+    let base = slot * 4u;
+
+    queue_out.elements[base] = item.instance_slot;
+    queue_out.elements[base + 1u] = item.page_row;
+    queue_out.elements[base + 2u] = item.visit;
+    queue_out.elements[base + 3u] = item.aux;
+}
+
+@compute @workgroup_size(${VGEO_CUT_WORKGROUP_SIZE})
+fn main(
+    @builtin(global_invocation_id) global_id: vec3<u32>,
+    @builtin(subgroup_size) lane_count: u32,
+    @builtin(subgroup_invocation_id) lane_index: u32,
+) {
+    let slot = global_id.x;
+
+    /*
+     The queue's count against what the queue holds. \`shader_vgeo_cut_queue_prepare\` runs
+     immediately before every dispatch of this kernel and stores exactly this clamp back, so the
+     bound is already there — but it was the *read* below that carried it here and not the predicate
+     that decides whether a lane executes, and those two have to agree. A lane held past capacity
+     reads the clamped index, which is the last item of the queue: it would execute a duplicate of
+     an item another lane is already holding, and a cluster visited twice from two lanes is two draw
+     records for one surface. That is the one failure the claim bitmask and the own-group term are
+     both arranged to prevent, so the predicate does not get to be the looser of the two.
+    */
+    let queue_count = min(queue_in.count, params.queue_capacity);
+
+    /*
+     One per dispatch that had work, which is one per spill generation rather than one per level of
+     the descent: the depth is inside this kernel. Reaching params.descent_steps with items still
+     held is what QUEUE_REMAINING reports, and nothing else can.
+    */
+    if (slot == 0u && queue_count > 0u) {
+        vg_stat(${VGEO_CUT_STAT.WAVEFRONTS}u, 1u);
+    }
+
+    var holding = slot < queue_count;
+
+    let base = slot * 4u;
+
+    /*
+     Read unconditionally and mask the result. A branch here would be a non-uniform if, which is
+     harmless on its own — but every lane must reach every subgroup operation below, and a lane that
+     returned early is a lane the shuffles are not allowed to read.
+    */
+    let in_bounds = min(base, params.queue_capacity * 4u - 4u);
+
+    var item = VGItem(
+        queue_in.elements[in_bounds],
+        queue_in.elements[in_bounds + 1u],
+        queue_in.elements[in_bounds + 2u],
+        queue_in.elements[in_bounds + 3u]
+    );
+
+    for (var step = 0u; step < params.descent_steps; step = step + 1u) {
+        let expand = vg_execute(item, holding);
+
+        let first = subgroupExclusiveAdd(expand.count);
+        let total = subgroupAdd(expand.count);
+
+        // ----- what this wave keeps: one child per lane, densely packed, whoever produced it -----
+
+        let owner = vg_child_owner(first, lane_index, lane_count);
+
+        let kept = vg_child(
+            subgroupShuffle(item.instance_slot, owner),
+            VGExpand(
+                subgroupShuffle(expand.kind, owner),
+                0u,
+                subgroupShuffle(expand.page_row, owner),
+                subgroupShuffle(expand.first, owner),
+                subgroupShuffle(expand.span, owner)
+            ),
+            lane_index - subgroupShuffle(first, owner)
+        );
+
+        // ----- what it cannot hold: spilled, packed, under one reservation for the whole wave -----
+
+        let mine_first = max(first, lane_count);
+        let mine_last = max(first + expand.count, lane_count);
+
+        let spill_count = mine_last - mine_first;
+
+        let spill_offset = subgroupExclusiveAdd(spill_count);
+        let spill_total = subgroupAdd(spill_count);
+
+        /*
+         Elected *before* the branch, so the branch carries no subgroup operation of its own and is
+         free to be non-uniform — which lets a wave with nothing to spill skip the reservation
+         outright. An atomic on the queue head is a global round trip; a descent step that keeps
+         everything it produced is otherwise register work, and would spend more reserving zero
+         slots than on the step.
+        */
+        let spill_elected = subgroupElect();
+
+        var reserved = 0u;
+
+        if (spill_elected && spill_total > 0u) {
+            reserved = atomicAdd(&queue_out.count, spill_total);
+        }
+
+        // after the branch closes, which Tint permits: it models reconvergence
+        let spill_base = subgroupBroadcastFirst(reserved) + spill_offset;
+
+        for (var i = 0u; i < spill_count; i = i + 1u) {
+            vg_queue_write(spill_base + i, vg_child(
+                item.instance_slot, expand, mine_first - first + i
+            ));
+        }
+
+        item = kept;
+        holding = lane_index < total;
+    }
+
+    /*
+     Whatever is still held has not been executed, so it goes back to the queue rather than being
+     dropped. This is the descent handing its unfinished frontier to the next dispatch, and at
+     lane_count items per wave it is the common case rather than an overflow path.
+    */
+    let tail_count = select(0u, 1u, holding);
+
+    let tail_offset = subgroupExclusiveAdd(tail_count);
+    let tail_total = subgroupAdd(tail_count);
+
+    let tail_elected = subgroupElect();
+
+    var tail_reserved = 0u;
+
+    // as above: a wave holding nothing does not reserve
+    if (tail_elected && tail_total > 0u) {
+        tail_reserved = atomicAdd(&queue_out.count, tail_total);
+    }
+
+    let tail_base = subgroupBroadcastFirst(tail_reserved) + tail_offset;
+
+    if (holding) {
+        vg_queue_write(tail_base, item);
     }
 }
 `, [
@@ -523,6 +909,12 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
     MESHLET_DEFINITION_STRUCT.declaration_chunk,
 ]);
 
+/*
+ The descent is a subgroup cooperating with itself — every lane's item packed into every lane's
+ register at each step — so the device has to have that capability and the source has to say so.
+*/
+body.addExtension(WebGPUExtensionType.Subgroups);
+
 export const shader_vgeo_cut_traverse = ComputeShader.from({
     label: "VGeo cut traverse",
     body,