@woosh/meep-engine 3.25.0 → 3.27.0

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

@@ -0,0 +1,100 @@
+/**
+ * @typedef {import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime} GPUVirtualGeometryRuntime
+ */
+/**
+ * What cutting is per **view** rather than per frame.
+ *
+ * A view owns this the way it owns its HZB and its previous camera, and for the same reason: these
+ * are the things two views must not share. The runtime above it owns what a *scene* has — the page
+ * tables, the arena, the pool — and a frame owns the feedback buffer every view writes into.
+ *
+ * ## Why the params are here and not on the runtime
+ *
+ * `projection_k` is `screen_height / (2·tan(fov_y/2))`: a property of a render target and a camera,
+ * which is to say of a view. One buffer on the runtime meant one value for the frame, written from
+ * whichever view opened it — so a shadow cascade cut against the main view's projection and
+ * selected a level for a screen it is not drawn to. That is a live defect independent of anything
+ * a kept cut needs, and the fix is that each view writes its own.
+ *
+ * **One buffer per view, not one buffer with an offset per view.** Views are few — a main view and
+ * a handful of cascades — and a uniform is tens of bytes, so the saving from packing them would be
+ * nothing against giving every per-view value a second index to be wrong in.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoViewCut {
+    /**
+     * @param {Object} options
+     * @param {GPUDevice} options.device
+     * @param {string} [options.label] names the buffer in a capture
+     */
+    constructor({ device, label }: {
+        device: GPUDevice;
+        label?: string;
+    });
+    /**
+     * The uniform every pass of this view's cut reads.
+     *
+     * @returns {GPUBuffer}
+     */
+    get params_buffer(): GPUBuffer;
+    /**
+     * @returns {number}
+     */
+    get projection_k(): number;
+    /**
+     * Where this view's last cut stood, as one bit per page row.
+     *
+     * @returns {GPUBuffer|undefined}
+     */
+    get frontier_buffer(): any;
+    /**
+     * @returns {number}
+     */
+    get frontier_word_count(): number;
+    /**
+     * Size the frontier to the tier it will name rows of.
+     *
+     * Lazily, and re-made rather than grown when the tier's capacity changes: what it holds
+     * is row indices of that tier, so a bigger tier does not extend the old answer, it
+     * invalidates it. Dropping it costs one frame of root descent, which is the fallback
+     * every other invalidation takes too.
+     *
+     * @param {number} page_row_capacity
+     * @returns {void}
+     */
+    resize_frontier(page_row_capacity: number): void;
+    /**
+     * Take this view's projection from the target it draws to and the camera it draws with.
+     *
+     * @param {Object} options
+     * @param {number} options.screen_height pixels of the render target
+     * @param {number} options.fov_y radians
+     * @returns {void}
+     */
+    set_projection({ screen_height, fov_y }: {
+        screen_height: number;
+        fov_y: number;
+    }): void;
+    /**
+     * Publish the frame's shared settings and this view's own, as one uniform.
+     *
+     * Everything but `projection_k` and `flags` is a property of the runtime or the frame, so it is
+     * read from the runtime at write time rather than mirrored here — a second copy of `tau` is a
+     * second thing to forget to update.
+     *
+     * @param {Object} options
+     * @param {GPUVirtualGeometryRuntime} options.runtime inside an open frame
+     * @param {boolean} [options.coarsen] whether this view's cut may walk up
+     * @returns {void}
+     */
+    write_params({ runtime, coarsen }: {
+        runtime: GPUVirtualGeometryRuntime;
+        coarsen?: boolean;
+    }): void;
+    destroy(): void;
+    #private;
+}
+export type GPUVirtualGeometryRuntime = import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime;
+//# sourceMappingURL=VGeoViewCut.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoViewCut.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoViewCut.js"],"names":[],"mappings":"AAOA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAwCI;;;;OAIG;IACH;QAH8B,MAAM;QACR,KAAK,GAAtB,MAAM;OAehB;IAED;;;;OAIG;IACH,+BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,2BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;;;OAUG;IACH,mCAHW,MAAM,GACJ,IAAI,CAkBhB;IAED;;;;;;;OAOG;IACH;QAJ2B,aAAa,EAA7B,MAAM;QACU,KAAK,EAArB,MAAM;QACJ,IAAI,CAShB;IAED;;;;;;;;;;;OAWG;IACH;QAJ8C,OAAO,EAA1C,yBAAyB;QACP,OAAO,GAAzB,OAAO;QACL,IAAI,CA8BhB;IAED,gBAIC;;CACJ;wCAlNY,OAAO,gCAAgC,EAAE,yBAAyB"}

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

@@ -0,0 +1,219 @@
+import { assert } from "../../../../../core/assert.js";
+import { VGEO_CUT_FLAG_COARSEN } from "./cut/VGEO_CUT_FLAG_COARSEN.js";
+import { VGEO_CUT_FLAG_CULL } from "./cut/VGEO_CUT_FLAG_CULL.js";
+import { VGEO_CUT_PARAMS_STRUCT } from "./cut/VGEO_CUT_PARAMS_STRUCT.js";
+import { vgeo_frontier_words } from "./vgeo_frontier_words.js";
+import { write_gpu_typed_buffer } from "../../../shader/type/serde/write_gpu_typed_buffer.js";
+
+/**
+ * @typedef {import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime} GPUVirtualGeometryRuntime
+ */
+
+/**
+ * What cutting is per **view** rather than per frame.
+ *
+ * A view owns this the way it owns its HZB and its previous camera, and for the same reason: these
+ * are the things two views must not share. The runtime above it owns what a *scene* has — the page
+ * tables, the arena, the pool — and a frame owns the feedback buffer every view writes into.
+ *
+ * ## Why the params are here and not on the runtime
+ *
+ * `projection_k` is `screen_height / (2·tan(fov_y/2))`: a property of a render target and a camera,
+ * which is to say of a view. One buffer on the runtime meant one value for the frame, written from
+ * whichever view opened it — so a shadow cascade cut against the main view's projection and
+ * selected a level for a screen it is not drawn to. That is a live defect independent of anything
+ * a kept cut needs, and the fix is that each view writes its own.
+ *
+ * **One buffer per view, not one buffer with an offset per view.** Views are few — a main view and
+ * a handful of cascades — and a uniform is tens of bytes, so the saving from packing them would be
+ * nothing against giving every per-view value a second index to be wrong in.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoViewCut {
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * @type {string}
+     */
+    #label;
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #params;
+
+    /**
+     * Scratch for one params write, so a per-frame write allocates nothing.
+     * @type {ArrayBuffer}
+     */
+    #scratch;
+
+    /**
+     * `screen_height / (2 · tan(fov_y / 2))`, this view's.
+     * @type {number}
+     */
+    #projection_k = 1;
+
+    /**
+     * One bit per page row: the pages this view's cut drew from, kept between frames.
+     * Undefined until the first frame that knows how big the tier is.
+     * @type {GPUBuffer|undefined}
+     */
+    #frontier;
+
+    /**
+     * @type {number}
+     */
+    #frontier_word_count = 0;
+
+    /**
+     * @param {Object} options
+     * @param {GPUDevice} options.device
+     * @param {string} [options.label] names the buffer in a capture
+     */
+    constructor({ device, label = 'a view' }) {
+        assert.defined(device, 'device');
+
+        this.#device = device;
+        this.#label = label;
+
+        this.#params = device.createBuffer({
+            label: `VGeoViewCut/params (${label})`,
+            size: VGEO_CUT_PARAMS_STRUCT.aligned_size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+
+        this.#scratch = new ArrayBuffer(VGEO_CUT_PARAMS_STRUCT.aligned_size);
+    }
+
+    /**
+     * The uniform every pass of this view's cut reads.
+     *
+     * @returns {GPUBuffer}
+     */
+    get params_buffer() {
+        return this.#params;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get projection_k() {
+        return this.#projection_k;
+    }
+
+    /**
+     * Where this view's last cut stood, as one bit per page row.
+     *
+     * @returns {GPUBuffer|undefined}
+     */
+    get frontier_buffer() {
+        return this.#frontier;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get frontier_word_count() {
+        return this.#frontier_word_count;
+    }
+
+    /**
+     * Size the frontier to the tier it will name rows of.
+     *
+     * Lazily, and re-made rather than grown when the tier's capacity changes: what it holds
+     * is row indices of that tier, so a bigger tier does not extend the old answer, it
+     * invalidates it. Dropping it costs one frame of root descent, which is the fallback
+     * every other invalidation takes too.
+     *
+     * @param {number} page_row_capacity
+     * @returns {void}
+     */
+    resize_frontier(page_row_capacity) {
+        const words = vgeo_frontier_words(page_row_capacity);
+
+        if (this.#frontier !== undefined && words === this.#frontier_word_count) {
+            return;
+        }
+
+        this.#frontier?.destroy();
+
+        this.#frontier_word_count = words;
+
+        this.#frontier = this.#device.createBuffer({
+            label: `VGeoViewCut/frontier (${this.#label})`,
+            size: Math.max(4, words * 4),
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+    }
+
+    /**
+     * Take this view's projection from the target it draws to and the camera it draws with.
+     *
+     * @param {Object} options
+     * @param {number} options.screen_height pixels of the render target
+     * @param {number} options.fov_y radians
+     * @returns {void}
+     */
+    set_projection({ screen_height, fov_y }) {
+        assert.isNumber(screen_height, 'screen_height');
+        assert.greaterThan(screen_height, 0, 'screen_height');
+        assert.isNumber(fov_y, 'fov_y');
+        assert.greaterThan(fov_y, 0, 'fov_y');
+
+        this.#projection_k = screen_height / (2 * Math.tan(fov_y * 0.5));
+    }
+
+    /**
+     * Publish the frame's shared settings and this view's own, as one uniform.
+     *
+     * Everything but `projection_k` and `flags` is a property of the runtime or the frame, so it is
+     * read from the runtime at write time rather than mirrored here — a second copy of `tau` is a
+     * second thing to forget to update.
+     *
+     * @param {Object} options
+     * @param {GPUVirtualGeometryRuntime} options.runtime inside an open frame
+     * @param {boolean} [options.coarsen] whether this view's cut may walk up
+     * @returns {void}
+     */
+    write_params({ runtime, coarsen = false }) {
+        assert.defined(runtime, 'runtime');
+
+        const layout = runtime.feedback_layout;
+
+        assert.defined(layout, 'runtime.feedback_layout — begin_frame must have run');
+
+        write_gpu_typed_buffer({
+            tau: runtime.tau,
+            projection_k: this.#projection_k,
+            queue_capacity: runtime.queue_capacity,
+            claim_word_count: runtime.claim_word_capacity,
+            descent_steps: runtime.descent_steps,
+            page_slot_words: runtime.pool.page_slot_words,
+            touch_bits_base: layout.touch_bits_base,
+            want_base: layout.want_base,
+            want_capacity: runtime.want_capacity,
+            frontier_word_count: this.#frontier_word_count,
+            frame_tag: runtime.pool.frame,
+            instance_capacity: runtime.instance_capacity,
+            meshlet_capacity: runtime.meshlet_capacity,
+            flags: (runtime.cull_enabled ? VGEO_CUT_FLAG_CULL : 0)
+                | (coarsen ? VGEO_CUT_FLAG_COARSEN : 0),
+        }, VGEO_CUT_PARAMS_STRUCT, this.#scratch, 0);
+
+        this.#device.queue.writeBuffer(
+            this.#params, 0, this.#scratch, 0, VGEO_CUT_PARAMS_STRUCT.aligned_size
+        );
+    }
+
+    destroy() {
+        this.#params.destroy();
+
+        this.#frontier?.destroy();
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * What an executed cut item expands into — the three shapes a child can have.
+ *
+ * The traversal states its production as a *kind*, a count and a base rather than as children
+ * written anywhere, because any lane of the subgroup has to be able to build child `k` of any other
+ * lane's item out of a handful of shuffled words. A kind is what makes those words mean something
+ * without a second read of the row that produced them.
+ */
+export type VGEO_CUT_EXPAND = number;
+export namespace VGEO_CUT_EXPAND {
+    let NONE: number;
+    let NODES: number;
+    let CLUSTERS: number;
+    let PAGE: number;
+    let PARENTS: number;
+}
+//# sourceMappingURL=VGEO_CUT_EXPAND.d.ts.map

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

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

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

@@ -0,0 +1,47 @@
+/**
+ * What an executed cut item expands into — the three shapes a child can have.
+ *
+ * The traversal states its production as a *kind*, a count and a base rather than as children
+ * written anywhere, because any lane of the subgroup has to be able to build child `k` of any other
+ * lane's item out of a handful of shuffled words. A kind is what makes those words mean something
+ * without a second read of the row that produced them.
+ *
+ * @see shader_vgeo_cut_traverse
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @enum {number}
+ */
+export const VGEO_CUT_EXPAND = {
+    /**
+     * Nothing. Culled, below the cut, drawn, or clamped — every terminal case of the rule.
+     */
+    NONE: 0,
+    /**
+     * `count` child nodes of the same page, starting at node index `first`.
+     */
+    NODES: 1,
+    /**
+     * `count` clusters, spread over the `span` groups starting at group index `first`.
+     *
+     * The count is every cluster the leaf covers rather than a number of chunks: a lane no longer
+     * walks a run of them, so there is nothing to chunk. `span` is carried instead of assumed
+     * because the walk that maps child `k` back to a group has to terminate on a row the builder
+     * wrote, not on a bound this file believes about the format.
+     */
+    CLUSTERS: 2,
+    /**
+     * One node 0, in the page at `page_row` — a descent crossing a page boundary, already claimed
+     * by the lane that produced it.
+     */
+    PAGE: 3,
+    /**
+     * `count` entries of the parent rows of the page at `page_row`, starting at entry `first` —
+     * a group's whole parent list, which is one step of a walk up.
+     *
+     * Unlike {@link PAGE} these are **not** claimed by the producer; each child claims the page
+     * it resolves to when it is executed. See `VGEO_QUEUE_TARGET_PARENT_BIT` for why the claim
+     * cannot be hoisted into the producer the way the descent's can.
+     */
+    PARENTS: 4,
+};

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

@@ -0,0 +1,20 @@
+/**
+ * `VGEO_CUT_PARAMS_STRUCT.flags`: a cluster below the cut walks **up** instead of stopping.
+ *
+ * Every edge the descent follows points down, so a traversal that finds itself below the cut — its
+ * consuming step already projecting to no more than tau — can only stop, and a runtime that wanted
+ * to keep a cut between frames would have to answer every coarsening camera by re-descending from
+ * the root. With this set, such a cluster expands into the pages holding its group\x27s parents
+ * instead (format §6.3), and the walk continues until it reaches clusters the rule draws.
+ *
+ * Off by default, and the descent with it off is byte for byte the descent that shipped: the root
+ * seed reaches every group through a parent that projected above tau, so the branch this opens is
+ * one the descent does not take. It is a flag rather than a behaviour because the cut it belongs to
+ * is a *kept* one, which is per view, and CUT_PLAN_2026_09_14 §7.6 is where a view gets to say so.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_CUT_FLAG_COARSEN: number;
+//# sourceMappingURL=VGEO_CUT_FLAG_COARSEN.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_CUT_FLAG_COARSEN.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/VGEO_CUT_FLAG_COARSEN.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,oCAFU,MAAM,CAEuB"}

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

@@ -0,0 +1,19 @@
+/**
+ * `VGEO_CUT_PARAMS_STRUCT.flags`: a cluster below the cut walks **up** instead of stopping.
+ *
+ * Every edge the descent follows points down, so a traversal that finds itself below the cut — its
+ * consuming step already projecting to no more than tau — can only stop, and a runtime that wanted
+ * to keep a cut between frames would have to answer every coarsening camera by re-descending from
+ * the root. With this set, such a cluster expands into the pages holding its group\x27s parents
+ * instead (format §6.3), and the walk continues until it reaches clusters the rule draws.
+ *
+ * Off by default, and the descent with it off is byte for byte the descent that shipped: the root
+ * seed reaches every group through a parent that projected above tau, so the branch this opens is
+ * one the descent does not take. It is a flag rather than a behaviour because the cut it belongs to
+ * is a *kept* one, which is per view, and CUT_PLAN_2026_09_14 §7.6 is where a view gets to say so.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_CUT_FLAG_COARSEN = 2;

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

@@ -1 +1 @@
-{"version":3,"file":"VGEO_CUT_PARAMS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/VGEO_CUT_PARAMS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,kDA+D2B;6BAjFE,yCAAyC"}
+{"version":3,"file":"VGEO_CUT_PARAMS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/VGEO_CUT_PARAMS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,kDAiF2B;6BAnGE,yCAAyC"}

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

@@ -41,9 +41,25 @@ export const VGEO_CUT_PARAMS_STRUCT = WebGPUStruct.from({
      */
     claim_word_count: u32,
     /**
-     * How many clusters one group-chunk item covers.
+     * Words of this view's frontier bitmask — one bit per page row, and the bound a write
+     * into it is clamped against.
+     *
+     * Zero says this view keeps no frontier, which is what every cut did before one existed
+     * and what a cut still does when the flag is off: the bound rejects every write rather
+     * than a branch having to ask.
+     */
+    frontier_word_count: u32,
+    /**
+     * Steps of the descent one dispatch of the traversal runs before handing what it still holds
+     * back to the queue.
+     *
+     * WGSL will not let a loop around a subgroup operation have a non-uniform trip count, and
+     * nothing launders one — so the descent cannot stop when the wave runs dry. It runs this many
+     * times and masks, at about ten instructions a step for a wave with nothing left. That makes
+     * this a tuning knob between idle steps and dispatches, and not a safety bound:
+     * `VGEO_CUT_STAT.QUEUE_REMAINING` is what says it was set too low.
      */
-    cluster_chunk: u32,
+    descent_steps: u32,
     /**
      * Arena words one page slot holds — the stride a page row is multiplied by.
      *
@@ -53,19 +69,21 @@ export const VGEO_CUT_PARAMS_STRUCT = WebGPUStruct.from({
      */
     page_slot_words: u32,
     /**
-     * Word offset in the feedback buffer of the per-page-row touch stamps.
+     * Word offset in the feedback buffer of the touch bits — one per page row, set with an
+     * `atomicOr` when a page's claim is won. The bit is the dedup and the record at once, so there
+     * is no list to overflow and nothing per row to clear beyond the transient itself.
      */
-    touch_stamp_base: u32,
-    /**
-     * Word offset in the feedback buffer of the per-lookup-word want stamps. A want's stamp index
-     * is this plus the geometry's lookup offset plus the child page index, which is why the page
-     * lookup has its own buffer and its own allocator: it makes that a compact, dense index.
-     */
-    want_stamp_base: u32,
+    touch_bits_base: u32,
     want_base: u32,
     want_capacity: u32,
-    touch_base: u32,
-    touch_capacity: u32,
+    /**
+     * What this frame writes into the want-stamp buffer to claim a want, and what it compares
+     * against to dedup one. The stamps are persistent and one per lookup word — one per page of
+     * every registered geometry — so they are not cleared per frame; a stamp holding this frame's
+     * tag was written this frame, and any other value was not. Never zero, which is what a fresh
+     * buffer holds.
+     */
+    frame_tag: u32,
     /**
      * Records the VG instance buffer holds, for the one append in the cut that had no bound.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_vgeo_cut_access.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_access.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;GAeG;AACH,oCAFU,SAAS,CAqIZ;0BA/JmB,0CAA0C"}
+{"version":3,"file":"chunk_vgeo_cut_access.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_access.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;GAeG;AACH,oCAFU,SAAS,CAmJZ;0BA9KmB,0CAA0C"}

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

@@ -9,6 +9,7 @@ import { VGEO_NODE_ROW_OFFSET } from "../layout/VGEO_NODE_ROW_OFFSET.js";
 import { VGEO_NODE_ROW_WORDS } from "../layout/VGEO_NODE_ROW_WORDS.js";
 import { VGEO_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
 import { VGEO_PAGE_ROW_WORDS } from "../layout/VGEO_PAGE_ROW_WORDS.js";
+import { VGEO_PARENT_ROW_WORDS } from "../layout/VGEO_PARENT_ROW_WORDS.js";
 
 /**
  * Addressing and arithmetic shared by every pass of the cut — how to find a row, and how to project
@@ -33,6 +34,7 @@ const VG_PAGE_ROW_WORDS = ${VGEO_PAGE_ROW_WORDS}u;
 const VG_NODE_ROW_WORDS = ${VGEO_NODE_ROW_WORDS}u;
 const VG_GROUP_ROW_WORDS = ${VGEO_GROUP_ROW_WORDS}u;
 const VG_CLUSTER_ROW_WORDS = ${VGEO_CLUSTER_ROW_WORDS}u;
+const VG_PARENT_ROW_WORDS = ${VGEO_PARENT_ROW_WORDS}u;
 const VG_INSTANCE_WORDS = ${VGEO_INSTANCE_WORDS}u;
 const VG_GEOMETRY_ROW_WORDS = ${VGEO_GEOMETRY_ROW_WORDS}u;
 
@@ -80,6 +82,19 @@ fn vg_cluster_base(page_row: u32) -> u32 {
         + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.GROUP_COUNT}u) * VG_GROUP_ROW_WORDS;
 }
 
+/**
+ * The fourth section: this page's parent rows, which is where a walk *up* reads.
+ *
+ * It may be empty, and a reader has to check rather than assume: the page row's parent
+ * entry count is zero for
+ * every page of a container written before format 4, which has no upward edge at all. Zero is not a
+ * malformed page; it is an asset that can only be re-descended.
+ */
+fn vg_parent_base(page_row: u32) -> u32 {
+    return vg_cluster_base(page_row)
+        + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT}u) * VG_CLUSTER_ROW_WORDS;
+}
+
 fn vg_arena_f32(word: u32) -> f32 {
     return bitcast<f32>(vg_arena[word]);
 }

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

@@ -1 +1 @@
-{"version":3,"file":"shader_vgeo_cut_collect.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_collect.js"],"names":[],"mappings":"AA0PA,oDAIG;8BAxP2B,qCAAqC"}
+{"version":3,"file":"shader_vgeo_cut_collect.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_collect.js"],"names":[],"mappings":"AA2QA,oDAIG;8BAzQ2B,qCAAqC"}

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

@@ -102,7 +102,24 @@ fn vg_store_plane(base: u32, plane: u32, row_w: vec4<f32>, row: vec4<f32>, sign:
 fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
     let input_index = global_id.x;
 
-    if (input_index >= input_meshes.count) {
+    /*
+     The count, against what the collection can actually hold, the way every sibling filter over
+     this shape reads it. The producer feeding this seam — \`shader_hzb_mesh_filter_2way\` — reserves
+     a slot with an unconditional \`atomicAdd\` and bounds-checks only the element *write*, so a
+     bucket whose positive set overflows hands over a count past the end of its own elements. The
+     indirect dispatch is built from that same count, so the overshoot arrives here as extra lanes
+     rather than as a loop bound this pass could have ignored.
+
+     Reading past the end is not the failure — robustness bounds that. The failure is what the
+     bounded read comes back with: a mesh row this bucket never selected, which the lines below
+     treat as a real instance, and if that row's geometry happens to be virtual it is collected and
+     cut. Every other bound in this pass degrades toward *fewer* instances; this one degraded into a
+     cut of geometry nobody asked for, which is the one direction a silently-wrong picture comes
+     from.
+     */
+    let input_size = min(input_meshes.count, arrayLength(&input_meshes.elements));
+
+    if (input_index >= input_size) {
         return;
     }
 

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

@@ -1 +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"}
+{"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":"AAiEA,0DAIG;8BAnE2B,qCAAqC"}

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

@@ -1,5 +1,3 @@
-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";
@@ -8,8 +6,6 @@ import {
 } 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";
 
@@ -27,6 +23,11 @@ import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
  * the buffer this iteration reads is the one the next iteration writes, and there is exactly one
  * moment when neither pass is touching it.
  *
+ * **It records no statistic.** There is another wavefront after it, so the count it sees is a
+ * frontier rather than a remainder, and it runs once per iteration per expansion site, so anything
+ * it stored would be overwritten by the next iteration and then by the next site. What the descent
+ * was left holding is {@link shader_vgeo_cut_queue_remainder}, recorded once, after the loop.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -40,8 +41,6 @@ resources.createGroup()
     // 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(
@@ -56,15 +55,6 @@ fn main() {
     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;

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

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

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

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