@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -0,0 +1,530 @@
+import { atomic_u32, u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { 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";
+import { MESHLET_DEFINITION_STRUCT } from "../../../meshlet/encoding/MESHLET_DEFINITION_STRUCT.js";
+import { VGEO_CLUSTER_ROW_OFFSET } from "../layout/VGEO_CLUSTER_ROW_OFFSET.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { VGEO_FEEDBACK_OFFSET } from "../layout/VGEO_FEEDBACK_OFFSET.js";
+import { VGEO_GROUP_FLAG_SELECTABLE } from "../layout/VGEO_GROUP_FLAG_SELECTABLE.js";
+import { VGEO_GROUP_ROW_OFFSET } from "../layout/VGEO_GROUP_ROW_OFFSET.js";
+import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
+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_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_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 rule
+ *
+ * A cluster is drawn iff
+ *
+ * > `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.
+ *
+ * ## 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * ## Why page-granular dedup is enough, and why it is necessary
+ *
+ * The page DAG is many-parented — 82 of 91 pages of a measured 98k sphere have more than one parent
+ * — so an undeduped descent would visit a page once per parent and draw its whole cut that many
+ * times. The claim is one bit per (instance, resident page), which is affordable. Cluster-granular
+ * dedup is what this avoids: the resident cluster count is exactly the number design §4 is trying
+ * not to pay per frame.
+ *
+ * Visiting a cluster the descent "should not" have reached costs only the test, because the
+ * predicate is a pure function of the row and gives the same answer from every direction. Missing
+ * one costs a hole. That asymmetry is the whole design:
+ *
+ * - **No cluster is drawn twice.** It is evaluated once per page visit, and the claim makes that at
+ *   most once per instance.
+ * - **No cluster the flat rule would draw is missed.** If `project(C.parent) > tau`, then any
+ *   parent cluster `P` of `C`'s group has `project(P.self) = project(C.parent) > tau` — every
+ *   cluster of a group shares the consuming step's sphere and error — and monotonicity gives
+ *   `project(P.parent) >= project(P.self)`, so `P` satisfies the predicate's first half and by
+ *   induction its page is visited. `P` fails `project(self) <= tau`, so it either enqueues `C`'s
+ *   page or clamps, and it clamps only when `C`'s group is not selectable, in which case `C` must
+ *   not be drawn. Neither cull intervenes: a node's sphere contains `P.parent_sphere` and its
+ *   `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.
+ *
+ * ## Bounds
+ *
+ * Every append is checked and every overflow is counted, and they all degrade in one direction —
+ * coarser or missing, never doubled. The exception worth knowing is `QUEUE_DROPPED`: a dropped item
+ * is a subtree never descended, and the parent that would have stood in over it was not drawn
+ * either, so that one is a hole.
+ *
+ * ## 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.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("params", VGEO_CUT_PARAMS_STRUCT)
+    // per geometry, `total_pages` words: container page index -> page row, or VGEO_PAGE_ROW_NONE
+    .addStorageBuffer("vg_lookup", WebGPUArray.from(u32), false)
+    // one fixed-stride slot per VRAM-resident page:
+    // [page header][node rows][group rows][cluster rows]
+    .addStorageBuffer("vg_arena", WebGPUArray.from(u32), false)
+;
+
+resources.createGroup()
+    .addStorageBuffer("instances", WebGPUArray.from(u32), false)
+    .addStorageBuffer("queue_in", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("queue_out", COLLECTION_U32_STRUCT_WRITE, true)
+;
+
+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
+    .addStorageBuffer("feedback", 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)
+;
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const VG_QUEUE_GROUP_BIT = ${VGEO_QUEUE_TARGET_GROUP_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);
+}
+
+/**
+ * Reserve count slots of the next wavefront.
+ *
+ * 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.
+ */
+fn vg_queue_reserve(count: u32) -> u32 {
+    return atomicAdd(&queue_out.count, count);
+}
+
+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;
+    }
+
+    let base = slot * 4u;
+
+    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;
+}
+
+/**
+ * Claim a page for one instance, and touch it if the claim was won.
+ *
+ * The claim is what makes "at most one draw record per (instance, cluster)" true, so an instance
+ * whose slice of the bitmask does not fit is refused upstream rather than run unclaimed.
+ */
+fn vg_claim_page(instance_base: u32, page_row: u32) -> bool {
+    let ordinal = vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.ORDINAL}u);
+
+    if (ordinal >= instances[instance_base + ${VGEO_INSTANCE_OFFSET.ORDINAL_CAPACITY}u]) {
+        return false;
+    }
+
+    let bit = instances[instance_base + ${VGEO_INSTANCE_OFFSET.CLAIM_BASE}u] + ordinal;
+
+    let word = bit >> 5u;
+
+    if (word >= params.claim_word_count) {
+        return false;
+    }
+
+    let mask = 1u << (bit & 31u);
+
+    if ((atomicOr(&claim[word], mask) & mask) != 0u) {
+        return false;
+    }
+
+    vg_stat(${VGEO_CUT_STAT.PAGES}u, 1u);
+
+    vg_touch_page(page_row);
+
+    return true;
+}
+
+/**
+ * Record that this page was selected from this frame — design §6's eviction key.
+ *
+ * LRU on last-*touched*, never on last-wanted: stamping at fetch time freezes the stamp of exactly
+ * 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.
+ */
+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);
+}
+
+/**
+ * Ask for the page a clamped cluster could not reach.
+ *
+ * Deduped on the child page, so a hundred clusters clamped against one page produce one request.
+ * The record names the page the want was discovered **through** as well as the page wanted: the
+ * source page's child table holds the exact byte range at child_ref, so the fetch costs one
+ * round trip and no metadata request, and it is also the page format §10 asks to be pinned while
+ * the child is in flight — which nothing but the cut can name, since the format stores parent counts
+ * rather than parent references.
+ *
+ * Priority is the first writer's projected error rather than the maximum over all of them. Taking a
+ * true maximum needs the record's slot, and a later writer cannot read that slot without waiting
+ * for the first writer to publish it. It is pixels of error either way, comparable across assets,
+ * 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) {
+        return;
+    }
+
+    let slot = atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.WANT_COUNT}u], 1u);
+
+    if (slot >= params.want_capacity) {
+        vg_stat(${VGEO_CUT_STAT.WANTS_DROPPED}u, 1u);
+        return;
+    }
+
+    let base = params.want_base + slot * VG_WANT_WORDS;
+
+    atomicStore(&feedback[base], source_page_row);
+    atomicStore(&feedback[base + 1u], child_ref);
+    atomicStore(&feedback[base + 2u], child_page_index);
+    atomicStore(&feedback[base + 3u], bitcast<u32>(projected));
+}
+
+/**
+ * Emit one draw record — the existing record type, into the existing collection.
+ *
+ * meshlet_base + local cluster is a row of the meshlet **metadata** pool, which is where a page
+ * install put this page's synthesized rows. Downstream reads meshlet_metadata[meshlet.index]
+ * exactly as it does for a static mesh, which is the whole of what makes the seam one call.
+ */
+fn vg_draw(page_row: u32, cluster: u32, mesh_index: u32) {
+    let slot = atomicAdd(&out_meshlets.count, 1u);
+
+    if (slot >= params.meshlet_capacity) {
+        vg_stat(${VGEO_CUT_STAT.MESHLETS_DROPPED}u, 1u);
+        return;
+    }
+
+    let meshlet = vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.MESHLET_BASE}u) + cluster;
+
+    out_meshlets.elements[slot] = ${MESHLET_DEFINITION_STRUCT.wgsl_ref}(meshlet, mesh_index);
+
+    vg_stat(${VGEO_CUT_STAT.DRAWN}u, 1u);
+}
+
+fn vg_group_selectable(page_row: u32, group: u32) -> bool {
+    let row = vg_group_base(page_row) + group * VG_GROUP_ROW_WORDS;
+
+    return (vg_arena[row + ${VGEO_GROUP_ROW_OFFSET.FLAGS}u] & VG_GROUP_SELECTABLE) != 0u;
+}
+
+/**
+ * A node: cull, then descend or hand off.
+ */
+fn vg_visit_node(instance_slot: u32, instance_base: u32, page_row: u32, node: u32) {
+    let row = vg_node_base(page_row) + node * VG_NODE_ROW_WORDS;
+
+    let sphere = vg_sphere_at(row + ${VGEO_NODE_ROW_OFFSET.SPHERE}u);
+
+    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;
+    }
+
+    let eye = vg_instance_eye(instance_base);
+    let k = vg_instance_f32(instance_base, ${VGEO_INSTANCE_OFFSET.PROJECTION_K}u);
+
+    /*
+     Format §6.2's load-bearing field. A cluster draws only while project(parent) > tau, so if the
+     *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) {
+        vg_stat(${VGEO_CUT_STAT.CULLED_LOD}u, 1u);
+        return;
+    }
+
+    let child_first = vg_arena[row + ${VGEO_NODE_ROW_OFFSET.CHILD_FIRST}u];
+    let child_word = vg_arena[row + ${VGEO_NODE_ROW_OFFSET.CHILD_COUNT_AND_FLAGS}u];
+
+    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;
+    }
+
+    // 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);
+
+    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 + (members + params.cluster_chunk - 1u) / params.cluster_chunk;
+    }
+
+    var slot = vg_queue_reserve(total);
+
+    for (var i = 0u; i < child_count; i = i + 1u) {
+        let group = child_first + i;
+
+        let members = vg_arena[
+            group_base + group * VG_GROUP_ROW_WORDS + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT}u
+        ];
+
+        var first = 0u;
+
+        while (first < members) {
+            vg_queue_write(slot, instance_slot, page_row, group | VG_QUEUE_GROUP_BIT, first);
+
+            slot = slot + 1u;
+            first = first + params.cluster_chunk;
+        }
+    }
+}
+
+/**
+ * A run of one group's clusters: the rule, cluster by cluster.
+ */
+fn vg_visit_group(
+    instance_slot: u32,
+    instance_base: u32,
+    page_row: u32,
+    group: u32,
+    first_cluster: u32
+) {
+    /*
+     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;
+    }
+
+    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 last = min(first_cluster + params.cluster_chunk, members);
+
+    let cluster_base = vg_cluster_base(page_row);
+
+    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;
+
+        let row = cluster_base + cluster * VG_CLUSTER_ROW_WORDS;
+
+        vg_stat(${VGEO_CUT_STAT.CLUSTERS_TESTED}u, 1u);
+
+        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;
+        }
+
+        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
+        );
+
+        let child_page_index = vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX}u];
+
+        if (self_projected <= params.tau || child_page_index == VG_NO_CHILD_PAGE) {
+            vg_draw(page_row, cluster, mesh_index);
+            continue;
+        }
+
+        let child_page_row = vg_lookup[lookup_base + child_page_index];
+
+        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_stat(${VGEO_CUT_STAT.CLAMPED}u, 1u);
+
+            vg_want(
+                page_row,
+                vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_REF}u],
+                child_page_index,
+                lookup_base,
+                self_projected
+            );
+
+            continue;
+        }
+
+        let child_group = vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_GROUP}u];
+
+        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);
+
+            vg_stat(${VGEO_CUT_STAT.CLAMPED}u, 1u);
+            vg_stat(${VGEO_CUT_STAT.CLAMPED_ON_ACTIVATION}u, 1u);
+
+            continue;
+        }
+
+        if (vg_claim_page(instance_base, child_page_row)) {
+            let slot = vg_queue_reserve(1u);
+
+            vg_queue_write(slot, instance_slot, 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;
+
+    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);
+    }
+
+    if (item >= queue_in.count) {
+        return;
+    }
+
+    let base = item * 4u;
+
+    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];
+
+    vg_stat(${VGEO_CUT_STAT.ITEMS}u, 1u);
+
+    let instance_base = instance_slot * VG_INSTANCE_WORDS;
+
+    if ((visit & VG_QUEUE_GROUP_BIT) != 0u) {
+        vg_visit_group(
+            instance_slot, instance_base, page_row, visit & ~VG_QUEUE_GROUP_BIT, first_cluster
+        );
+    } else {
+        vg_visit_node(instance_slot, instance_base, page_row, visit);
+    }
+}
+`, [
+    chunk_vgeo_cut_access,
+    MESHLET_DEFINITION_STRUCT.declaration_chunk,
+]);
+
+export const shader_vgeo_cut_traverse = ComputeShader.from({
+    label: "VGeo cut traverse",
+    body,
+    resources,
+});

package/src/shade/renderer/geometry/virtual/runtime/cut/vgeo_cut_feedback_layout.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Where each region of the feedback buffer starts, for one frame's worth of cutting.
+ *
+ * One function rather than two agreeing conventions: the pass that creates the buffer and the
+ * params block that tells the kernel where to write both come from here, and so does anything that
+ * reads it back. A layout computed twice is a layout that drifts, and the way it drifts is a want
+ * list written over a stamp region, which reads as wants that never resolve.
+ *
+ * The stamps are the reason the buffer is per **frame** rather than per invocation: a page touched
+ * from two buckets is one touch, and a page wanted by two views is one want. Being cleared exactly
+ * once, at creation, is what makes a plain flag enough and saves carrying a frame counter through
+ * every comparison.
+ *
+ * @param {Object} options
+ * @param {number} options.page_row_capacity one touch stamp per page-table row
+ * @param {number} options.lookup_word_count one want stamp per lookup word, so a want's stamp is
+ *     its geometry's lookup offset plus the child page index — which is the whole reason the page
+ *     lookup has its own buffer and its own allocator
+ * @param {number} options.want_capacity records
+ * @param {number} options.touch_capacity records
+ * @returns {{touch_stamp_base: number, want_stamp_base: number, want_base: number,
+ *     touch_base: number, word_count: number}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_cut_feedback_layout({ page_row_capacity, lookup_word_count, want_capacity, touch_capacity, }: {
+    page_row_capacity: number;
+    lookup_word_count: number;
+    want_capacity: number;
+    touch_capacity: number;
+}): {
+    touch_stamp_base: number;
+    want_stamp_base: number;
+    want_base: number;
+    touch_base: number;
+    word_count: number;
+};
+//# sourceMappingURL=vgeo_cut_feedback_layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_cut_feedback_layout.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/vgeo_cut_feedback_layout.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAZ2B,iBAAiB,EAAjC,MAAM;IACU,iBAAiB,EAAjC,MAAM;IAGU,aAAa,EAA7B,MAAM;IACU,cAAc,EAA9B,MAAM;IACJ;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAClF,UAAgB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,CA4B7C"}

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

@@ -0,0 +1,54 @@
+import { assert } from "../../../../../../core/assert.js";
+import { VGEO_FEEDBACK_OFFSET } from "../layout/VGEO_FEEDBACK_OFFSET.js";
+import { VGEO_WANT_WORDS } from "../layout/VGEO_WANT_WORDS.js";
+
+/**
+ * Where each region of the feedback buffer starts, for one frame's worth of cutting.
+ *
+ * One function rather than two agreeing conventions: the pass that creates the buffer and the
+ * params block that tells the kernel where to write both come from here, and so does anything that
+ * reads it back. A layout computed twice is a layout that drifts, and the way it drifts is a want
+ * list written over a stamp region, which reads as wants that never resolve.
+ *
+ * The stamps are the reason the buffer is per **frame** rather than per invocation: a page touched
+ * from two buckets is one touch, and a page wanted by two views is one want. Being cleared exactly
+ * once, at creation, is what makes a plain flag enough and saves carrying a frame counter through
+ * every comparison.
+ *
+ * @param {Object} options
+ * @param {number} options.page_row_capacity one touch stamp per page-table row
+ * @param {number} options.lookup_word_count one want stamp per lookup word, so a want's stamp is
+ *     its geometry's lookup offset plus the child page index — which is the whole reason the page
+ *     lookup has its own buffer and its own allocator
+ * @param {number} options.want_capacity records
+ * @param {number} options.touch_capacity records
+ * @returns {{touch_stamp_base: number, want_stamp_base: number, want_base: number,
+ *     touch_base: number, word_count: number}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_cut_feedback_layout({
+                                             page_row_capacity,
+                                             lookup_word_count,
+                                             want_capacity,
+                                             touch_capacity,
+                                         }) {
+    assert.isNonNegativeInteger(page_row_capacity, 'page_row_capacity');
+    assert.isNonNegativeInteger(lookup_word_count, 'lookup_word_count');
+    assert.isNonNegativeInteger(want_capacity, 'want_capacity');
+    assert.isNonNegativeInteger(touch_capacity, 'touch_capacity');
+
+    const touch_stamp_base = VGEO_FEEDBACK_OFFSET.HEADER_WORDS;
+    const want_stamp_base = touch_stamp_base + page_row_capacity;
+    const want_base = want_stamp_base + lookup_word_count;
+    const touch_base = want_base + want_capacity * VGEO_WANT_WORDS;
+
+    return {
+        touch_stamp_base,
+        want_stamp_base,
+        want_base,
+        touch_base,
+        word_count: touch_base + touch_capacity,
+    };
+}

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

@@ -0,0 +1,41 @@
+/**
+ * The seam, at a call site that does not want to know whether this scene has virtual geometry in it.
+ *
+ * Four rasterization paths call `graph_expand_meshes_to_meshlets`, and each of them gains exactly
+ * one line. That line has to be a no-op in the overwhelmingly common case — a scene of ordinary
+ * meshes — and it has to be a no-op *cheaply*: not a cut over an empty instance list, but no passes
+ * at all, because a wavefront is sixty-odd dispatches whose only output would be zero.
+ *
+ * The frame check is the second half of that. A runtime exists from the moment somebody enables it,
+ * but its feedback buffer exists only between `begin_frame` and `end_frame`; a path that runs
+ * outside a frame — a shadow view built before the main pass opens one, say — skips rather than
+ * writing into a resource that is not there.
+ *
+ * **And the graph check is the third.** `GPUSceneShadowmapContext` records through
+ * `graph_rasterize_scene_fast_raw`, which carries this seam, on a `FrameGraph` of its own — so a
+ * cube or tetra face inside an open frame would run a whole cut, at the *main camera's* projection
+ * scale, writing into a resource handle that belongs to another graph. Design §4 pins one cut per
+ * view and RUNTIME_PLAN §9 scopes shadow cuts out of v1; a graph that is not the one the frame was
+ * opened on is therefore not a graph this seam belongs in (REVIEW_LEDGER M13). When shadow views do
+ * get cuts, they get their own `begin_frame` and their own τ, and this check is what makes that a
+ * change rather than a discovery.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.input_meshes
+ * @param {number} options.output_meshlets
+ * @param {GPUViewContext} options.view
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} `output_meshlets`, cut records appended or not
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_vgeo_expand_if_enabled({ graph, input_meshes, output_meshlets, view, limits, }: {
+    graph: FrameGraph;
+    input_meshes: number;
+    output_meshlets: number;
+    view: GPUViewContext;
+    limits: GPUCollectionLimits;
+}): number;
+//# sourceMappingURL=graph_vgeo_expand_if_enabled.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_vgeo_expand_if_enabled.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_if_enabled.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAV+B,KAAK;IACT,YAAY,EAA5B,MAAM;IACU,eAAe,EAA/B,MAAM;IACkB,IAAI;IACC,MAAM;IACjC,MAAM,CAyBlB"}