@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -0,0 +1,255 @@
+import { atomic_u32, u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.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 { ComputeShader } from "../../../../shader/ComputeShader.js";
+import { GEOMETRY_METADATA_STRUCT } from "../../../GEOMETRY_METADATA_STRUCT.js";
+import { chunk_mat3_singular_values } from "../../../../shader/chunk/geometry/mat3/chunk_mat3_singular_values.js";
+import { chunk_mat4_inverse } from "../../../../shader/chunk/geometry/mat4/chunk_mat4_inverse.js";
+import { chunk_scene_database_access } from "../../../../scene/chunk_scene_database_access.js";
+import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { VGEO_FEEDBACK_OFFSET } from "../layout/VGEO_FEEDBACK_OFFSET.js";
+import { VGEO_GEOMETRY_ROW_NONE } from "../layout/VGEO_GEOMETRY_ROW_NONE.js";
+import { VGEO_GEOMETRY_ROW_OFFSET } from "../layout/VGEO_GEOMETRY_ROW_OFFSET.js";
+import { VGEO_GEOMETRY_ROW_WORDS } from "../layout/VGEO_GEOMETRY_ROW_WORDS.js";
+import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
+import { VGEO_INSTANCE_WORDS } from "../layout/VGEO_INSTANCE_WORDS.js";
+import { VGEO_CUT_PARAMS_STRUCT } from "./VGEO_CUT_PARAMS_STRUCT.js";
+import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
+
+/**
+ * Pick the virtual-geometry instances out of a list of visible meshes, and put each one into object
+ * space once.
+ *
+ * This is `MICRON_COMPARISON_2026_08_20.md` §2.7 as design §3.1 adopted it, and it is the only
+ * place the transform is touched: multiply the camera's view-projection by the instance transform,
+ * take the frustum out of the result, invert the transform once for the eye, and every cull and
+ * error test downstream runs against untransformed cluster bounds. One matrix per instance instead
+ * of a transform per cluster — with thousands of instances sharing one geometry, that difference is
+ * the entire cost.
+ *
+ * It also emits each instance's claim width, which the prefix scan turns into the base the seed
+ * pass writes back. The width is the geometry's **ordinal capacity** rather than its resident page
+ * count, because ordinals come from a free list and can be sparse; a bitmask indexed by a sparse
+ * ordinal has to be as wide as the highest one handed out.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("params", VGEO_CUT_PARAMS_STRUCT)
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32), false)
+    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
+    .addStorageBuffer("vg_geometries", WebGPUArray.from(u32), false)
+;
+
+resources.createGroup()
+    .addStorageBuffer("input_meshes", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("instances", WebGPUArray.from(u32), true)
+    .addStorageBuffer("claim_widths", COLLECTION_U32_STRUCT_WRITE, true)
+    // the frame's counters, so an instance this pass refuses is counted where every other drop is
+    .addStorageBuffer("feedback", WebGPUArray.from(atomic_u32), true)
+;
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const VG_GEOMETRY_ROW_NONE = ${VGEO_GEOMETRY_ROW_NONE}u;
+const VG_INSTANCE_WORDS = ${VGEO_INSTANCE_WORDS}u;
+const VG_GEOMETRY_ROW_WORDS = ${VGEO_GEOMETRY_ROW_WORDS}u;
+
+fn vg_store(base: u32, field: u32, value: f32) {
+    instances[base + field] = bitcast<u32>(value);
+}
+
+/**
+ * One frustum plane out of a row combination of the object-space view-projection, normalized so a
+ * sphere test is a plain signed distance.
+ *
+ * Gribb-Hartmann, and the far plane is simply not extracted: the projection is infinite reverse-Z,
+ * so its row is degenerate and normalizing it produces nothing a test can use. Ordering near last
+ * is what makes the traversal's "test the first five" true by construction.
+ *
+ * **The near plane is w − z, and it was w + z here.** Under reverse-Z the near plane is the one
+ * clip space bounds by z <= w; w + z is the row an *infinite* projection makes degenerate, which is
+ * exactly the row this function then normalized into a plane the test could not use.
+ * Camera.construct_frustum_planes has had the sign right all along and is worth comparing against
+ * rather than re-deriving.
+ */
+fn vg_store_plane(base: u32, plane: u32, row_w: vec4<f32>, row: vec4<f32>, sign: f32) {
+    let raw = row_w + row * sign;
+
+    let length_xyz = length(raw.xyz);
+
+    let normalized = select(raw, raw / length_xyz, length_xyz > 0.0);
+
+    let word = base + ${VGEO_INSTANCE_OFFSET.FRUSTUM}u + plane * 4u;
+
+    instances[word] = bitcast<u32>(normalized.x);
+    instances[word + 1u] = bitcast<u32>(normalized.y);
+    instances[word + 2u] = bitcast<u32>(normalized.z);
+    instances[word + 3u] = bitcast<u32>(normalized.w);
+}
+
+@compute @workgroup_size(${VGEO_CUT_WORKGROUP_SIZE})
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let input_index = global_id.x;
+
+    if (input_index >= input_meshes.count) {
+        return;
+    }
+
+    let mesh_index = input_meshes.elements[input_index];
+
+    let mesh = scene_read_mesh(&scene_database, mesh_index);
+
+    let geometry_row = geometries[mesh.geometry].vg_row;
+
+    if (geometry_row == VG_GEOMETRY_ROW_NONE) {
+        // an ordinary mesh; the static expansion beside this pass is what draws it
+        return;
+    }
+
+    let node = scene_read_node(&scene_database, mesh.node);
+
+    let linear = mat3x3<f32>(
+        node.global[0].xyz, node.global[1].xyz, node.global[2].xyz
+    );
+
+    /*
+     Error and distance are both object-space, so a **uniform** scale cancels out of r_e * k / d
+     exactly and needs no term at all. A non-uniform one does not, and the correction is the ratio
+     of the largest stretch this transform applies to any direction to the smallest — which is the
+     ratio of its singular values, not of its column lengths. A shear has unit columns and stretches
+     space without bound, so column lengths report 1 and under-refine, which is the direction a
+     conservative correction is not allowed to fail in.
+     */
+    let stretch = mat3_singular_values(linear);
+
+    if (!(abs(determinant(linear)) > 0.0) || !(stretch.y > 0.0)) {
+        /*
+         A singular transform — an instance scaled to zero in some direction. mat4_inverse says so
+         by dividing by a zero determinant, and the NaN that comes back makes **every** comparison
+         in vg_project and the frustum test fail open, so one zero-scaled instance draws its whole
+         resident set. It covers no pixels, so dropping it is also the right picture.
+
+         **The determinant is the test, and sigma_min alone was not.** This guard used to be
+         !(sigma_min > 0) on its own, and the closed form's own doc offered sigma_min as a
+         degeneracy test — true in exact arithmetic, false in f32. An axis-aligned flatten makes
+         MtM exactly diagonal and takes the exact branch, which does return zero. A ROTATED one
+         takes the trigonometric branch, where sigma_min is a difference of nearly equal numbers
+         with an absolute error of about sqrt(eps_f32) * sigma_max — so it came back near 1e-4
+         rather than 0, and thirty-six of forty rotated zero-scale instances passed this line with
+         a NaN eye and a projection scale of 6.2e10 behind it (REVIEW_LEDGER M3, re-review
+         2026-09-12). The determinant does not have that problem: a flattened instance has one
+         exactly-zero column at every rotation, and every term of the expansion carries a factor
+         from it. It is also, exactly, the number mat4_inverse divides by two lines below.
+
+         sigma_min is kept beside it because it is not redundant: a matrix that is merely very
+         close to singular has a non-zero determinant and can still report sigma_min as zero, and
+         the ratio below would then be an infinity rather than a correction.
+
+         Both written as !(x > 0) rather than x <= 0 so that a NaN — which compares false against
+         everything — is caught rather than passed through.
+         */
+        atomicAdd(
+            &feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.INSTANCES_DROPPED}u], 1u
+        );
+
+        return;
+    }
+
+    let slot = atomicAdd(&claim_widths.count, 1u);
+
+    if (slot >= params.instance_capacity) {
+        /*
+         Bounded like every other append in the cut. As the seam is wired this cannot fire — one
+         instance record per element of input_meshes, and both collections are sized from the same
+         limit — but the invariant lives a call away and the buffer is created here, so the check
+         belongs here too. Dropping the instance is the safe direction: a cut run without a claim
+         slice draws every page once per parent that reaches it.
+         */
+        atomicAdd(
+            &feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.INSTANCES_DROPPED}u], 1u
+        );
+
+        return;
+    }
+
+    let base = slot * VG_INSTANCE_WORDS;
+
+    let to_object = mat4_inverse(node.global);
+
+    // the camera's position in this instance's object space, out of the camera's own world transform
+    let eye = to_object * vec4<f32>(camera.transform[3].xyz, 1.0);
+
+    vg_store(base, ${VGEO_INSTANCE_OFFSET.EYE}u, eye.x / eye.w);
+    vg_store(base, ${VGEO_INSTANCE_OFFSET.EYE + 1}u, eye.y / eye.w);
+    vg_store(base, ${VGEO_INSTANCE_OFFSET.EYE + 2}u, eye.z / eye.w);
+
+    vg_store(
+        base, ${VGEO_INSTANCE_OFFSET.PROJECTION_K}u,
+        params.projection_k * (stretch.x / stretch.y)
+    );
+
+    // one matrix multiply, and every plane below comes out of it
+    let object_view_projection = camera.view_projection_matrix * node.global;
+
+    // WGSL matrices are column-major, so a row of the matrix is a component across its columns
+    let row_x = vec4<f32>(
+        object_view_projection[0].x, object_view_projection[1].x,
+        object_view_projection[2].x, object_view_projection[3].x
+    );
+    let row_y = vec4<f32>(
+        object_view_projection[0].y, object_view_projection[1].y,
+        object_view_projection[2].y, object_view_projection[3].y
+    );
+    let row_z = vec4<f32>(
+        object_view_projection[0].z, object_view_projection[1].z,
+        object_view_projection[2].z, object_view_projection[3].z
+    );
+    let row_w = vec4<f32>(
+        object_view_projection[0].w, object_view_projection[1].w,
+        object_view_projection[2].w, object_view_projection[3].w
+    );
+
+    vg_store_plane(base, 0u, row_w, row_x, 1.0);
+    vg_store_plane(base, 1u, row_w, row_x, -1.0);
+    vg_store_plane(base, 2u, row_w, row_y, 1.0);
+    vg_store_plane(base, 3u, row_w, row_y, -1.0);
+    vg_store_plane(base, 4u, row_w, row_z, -1.0);
+
+    let geometry_base = geometry_row * VG_GEOMETRY_ROW_WORDS;
+
+    let ordinal_capacity = vg_geometries[
+        geometry_base + ${VGEO_GEOMETRY_ROW_OFFSET.ORDINAL_CAPACITY}u
+    ];
+
+    instances[base + ${VGEO_INSTANCE_OFFSET.MESH_INDEX}u] = mesh_index;
+    instances[base + ${VGEO_INSTANCE_OFFSET.ROOT_PAGE_ROW}u] =
+        vg_geometries[geometry_base + ${VGEO_GEOMETRY_ROW_OFFSET.ROOT_PAGE_ROW}u];
+    instances[base + ${VGEO_INSTANCE_OFFSET.LOOKUP_WORD_OFFSET}u] =
+        vg_geometries[geometry_base + ${VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET}u];
+    instances[base + ${VGEO_INSTANCE_OFFSET.ORDINAL_CAPACITY}u] = ordinal_capacity;
+    instances[base + ${VGEO_INSTANCE_OFFSET.CLAIM_BASE}u] = 0u;
+
+    claim_widths.elements[slot] = ordinal_capacity;
+}
+`, [
+    chunk_scene_database_access,
+    chunk_mat3_singular_values,
+    chunk_mat4_inverse,
+]);
+
+export const shader_vgeo_cut_collect = ComputeShader.from({
+    label: "VGeo cut collect instances",
+    body,
+    resources,
+});

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

@@ -0,0 +1,3 @@
+export const shader_vgeo_cut_queue_prepare: ComputeShader;
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vgeo_cut_queue_prepare.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vgeo_cut_queue_prepare.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_queue_prepare.js"],"names":[],"mappings":"AA2EA,0DAIG;8BA3E2B,qCAAqC"}

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

@@ -0,0 +1,80 @@
+import { atomic_u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { COLLECTION_U32_STRUCT_WRITE } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+import {
+    STRUCT_DISPATCH_COMPUTE_COMMAND
+} from "../../../../gpu_primitive/indirect/STRUCT_DISPATCH_COMPUTE_COMMAND.js";
+import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_divide_round_up_u32 } from "../../../../shader/chunk/math/chunk_divide_round_up_u32.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { VGEO_FEEDBACK_OFFSET } from "../layout/VGEO_FEEDBACK_OFFSET.js";
+import { VGEO_CUT_PARAMS_STRUCT } from "./VGEO_CUT_PARAMS_STRUCT.js";
+import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
+
+/**
+ * Between two wavefronts: clamp what the last one produced, turn it into a dispatch, and empty the
+ * queue the next one will write.
+ *
+ * The clamp is the load-bearing half. A wavefront reserves its output slots with `atomicAdd` and
+ * bounds-checks each write, so an overflowing iteration writes what fits and counts the rest — but
+ * the count itself runs past capacity, and handing *that* to an indirect dispatch would dispatch
+ * lanes over the end of a pooled buffer. Clamping here is what keeps the overflow a lost subtree
+ * rather than a read of somebody else's transient.
+ *
+ * Zeroing the *other* queue is here for the same reason it is here at all: the two ping-pong, so
+ * the buffer this iteration reads is the one the next iteration writes, and there is exactly one
+ * moment when neither pass is touching it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("params", VGEO_CUT_PARAMS_STRUCT)
+    // what the wavefront just produced, and what the next one consumes
+    .addStorageBuffer("queue_ready", COLLECTION_U32_STRUCT_WRITE, true)
+    // what the next wavefront will produce into
+    .addStorageBuffer("queue_spare", COLLECTION_U32_STRUCT_WRITE, true)
+    .addStorageBuffer("command", STRUCT_DISPATCH_COMPUTE_COMMAND, true)
+    // the frame's counters: this is the only pass that can see how deep the descent went
+    .addStorageBuffer("feedback", WebGPUArray.from(atomic_u32), true)
+;
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(1)
+fn main() {
+    let produced = atomicLoad(&queue_ready.count);
+
+    let count = min(produced, params.queue_capacity);
+
+    atomicStore(&queue_ready.count, count);
+    atomicStore(&queue_spare.count, 0u);
+
+    /*
+     What was outstanding when this pass ran. A plain store rather than an add, so the last prepare
+     of the frame is the one that is read — and the seam records one extra prepare after the
+     wavefront loop, whose whole purpose is to leave this number behind. A descent that stops with
+     work still queued is the one degradation that costs a hole rather than coarseness, and until
+     now nothing anywhere counted it (REVIEW_LEDGER M8).
+     */
+    atomicStore(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.QUEUE_REMAINING}u], count);
+
+    command.workgroupCountX = divide_round_up_u32(count, ${VGEO_CUT_WORKGROUP_SIZE}u);
+    command.workgroupCountY = 1u;
+    command.workgroupCountZ = 1u;
+}
+`, [
+    chunk_divide_round_up_u32,
+]);
+
+export const shader_vgeo_cut_queue_prepare = ComputeShader.from({
+    label: "VGeo cut queue prepare",
+    body,
+    resources,
+});

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

@@ -0,0 +1,3 @@
+export const shader_vgeo_cut_seed: ComputeShader;
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vgeo_cut_seed.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vgeo_cut_seed.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_seed.js"],"names":[],"mappings":"AA2IA,iDAIG;8BA1I2B,qCAAqC"}

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

@@ -0,0 +1,144 @@
+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 { 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 { ComputeShader } from "../../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { VGEO_FEEDBACK_OFFSET } from "../layout/VGEO_FEEDBACK_OFFSET.js";
+import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
+import { VGEO_INSTANCE_WORDS } from "../layout/VGEO_INSTANCE_WORDS.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_CUT_PARAMS_STRUCT } from "./VGEO_CUT_PARAMS_STRUCT.js";
+import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
+
+/**
+ * Seed the wavefront: one item per visible VG instance, naming its root page's node 0.
+ *
+ * This is also where each instance learns where its slice of the claim bitmask starts, out of the
+ * prefix scan over instance ordinal capacities — the same scan shape `graph_expand_meshes_to_meshlets`
+ * runs to size its meshlet output, for the same reason.
+ *
+ * **An instance whose slice does not fit is refused**, and that direction is not arbitrary. A cut
+ * run without a claim visits every page once per parent page that reaches it and emits its whole
+ * cut that many times over; the failure reads as corrupt geometry rather than as a missing
+ * instance, and a missing instance is the one a human can see and attribute.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("params", VGEO_CUT_PARAMS_STRUCT)
+    // the page slots; this pass reads one header field out of one of them
+    .addStorageBuffer("vg_arena", WebGPUArray.from(u32), false)
+    .addStorageBuffer("prefix_sums", COLLECTION_U32_STRUCT_READ, false)
+;
+
+resources.createGroup()
+    .addStorageBuffer("instances", WebGPUArray.from(u32), true)
+    .addStorageBuffer("queue_out", COLLECTION_U32_STRUCT_WRITE, true)
+    .addStorageBuffer("claim", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("feedback", WebGPUArray.from(atomic_u32), true)
+;
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${VGEO_CUT_WORKGROUP_SIZE})
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let instance_slot = global_id.x;
+
+    if (instance_slot >= prefix_sums.count) {
+        return;
+    }
+
+    let instance_base = instance_slot * ${VGEO_INSTANCE_WORDS}u;
+
+    // inclusive scan: this instance's base is the total below it
+    var claim_base = 0u;
+
+    if (instance_slot > 0u) {
+        claim_base = prefix_sums.elements[instance_slot - 1u];
+    }
+
+    let capacity = instances[instance_base + ${VGEO_INSTANCE_OFFSET.ORDINAL_CAPACITY}u];
+
+    if ((claim_base + capacity + 31u) >> 5u > params.claim_word_count) {
+        atomicAdd(
+            &feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.INSTANCES_DROPPED}u], 1u
+        );
+
+        // left with a capacity of zero, so nothing downstream can claim on its behalf either
+        instances[instance_base + ${VGEO_INSTANCE_OFFSET.ORDINAL_CAPACITY}u] = 0u;
+
+        return;
+    }
+
+    instances[instance_base + ${VGEO_INSTANCE_OFFSET.CLAIM_BASE}u] = claim_base;
+
+    let page_row = instances[instance_base + ${VGEO_INSTANCE_OFFSET.ROOT_PAGE_ROW}u];
+
+    /*
+     A geometry whose root page is not resident draws nothing, and saying so here is one compare.
+     The host refuses to register such a geometry at all, but it used to say so through
+     \`assert.notEqual\`, and this engine ships with \`assert.*\` stripped — so in a shipped build the
+     sentinel reached this line, was multiplied by the slot stride as a u32, and wrapped into a live
+     word of the feedback buffer (REVIEW_LEDGER C7). A guard the build cannot remove costs less than
+     the failure it prevents is worth diagnosing.
+     */
+    if (page_row == ${VGEO_PAGE_ROW_NONE}u) {
+        return;
+    }
+
+    /*
+     The root page is pinned, so this claim always wins — but it is taken rather than assumed,
+     because it is also what stamps the root page as touched, and a root that never reports a touch
+     is a root that ages out of the touch-LRU while it is on screen.
+     */
+    let ordinal = vg_arena[
+        page_row * params.page_slot_words + ${VGEO_PAGE_ROW_OFFSET.ORDINAL}u
+    ];
+
+    let bit = claim_base + ordinal;
+
+    atomicOr(&claim[bit >> 5u], 1u << (bit & 31u));
+
+    atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.PAGES}u], 1u);
+
+    if (atomicExchange(&feedback[params.touch_stamp_base + page_row], 1u) == 0u) {
+        let touch_slot = atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.TOUCH_COUNT}u], 1u);
+
+        if (touch_slot < params.touch_capacity) {
+            atomicStore(&feedback[params.touch_base + touch_slot], page_row);
+        }
+    }
+
+    let slot = atomicAdd(&queue_out.count, 1u);
+
+    if (slot >= params.queue_capacity) {
+        atomicAdd(
+            &feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${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] = 0u;
+    queue_out.elements[base + 3u] = 0u;
+}
+`, []);
+
+export const shader_vgeo_cut_seed = ComputeShader.from({
+    label: "VGeo cut seed",
+    body,
+    resources,
+});

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

@@ -0,0 +1,3 @@
+export const shader_vgeo_cut_traverse: ComputeShader;
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vgeo_cut_traverse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vgeo_cut_traverse.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_traverse.js"],"names":[],"mappings":"AA6gBA,qDAIG;8BA9gB2B,qCAAqC"}