@woosh/meep-engine 3.26.0 → 3.28.0

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

@@ -4,36 +4,33 @@
  * 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.
+ * list written over the touch bits, 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.
+ * **Header, touch bits, want records — and the whole of it is read back.** Two regions used to sit
+ * between the header and the lists and neither was the CPU's business: a stamp word per page row
+ * and a stamp word per lookup word, cleared with the transient every frame and mapped back with
+ * it. At the playground's 4,096 slots that was 344 KB a frame across the bus for 33 KB of lists,
+ * and the lookup-sized half of it grew with every registered geometry rather than with anything
+ * seen. The touch stamps are the touch bits now — one bit per row, which is both the dedup and
+ * the record — and the want stamps live in a persistent, frame-tagged buffer the pool owns and
+ * nothing reads back (RUNTIME_PLAN_2026_09_14 §2.2, §2.3).
  *
  * @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.page_row_capacity one touch bit per page-table row
  * @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}}
+ * @returns {{touch_bits_base: number, touch_word_count: number, want_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, }: {
+export function vgeo_cut_feedback_layout({ page_row_capacity, want_capacity }: {
     page_row_capacity: number;
-    lookup_word_count: number;
     want_capacity: number;
-    touch_capacity: number;
 }): {
-    touch_stamp_base: number;
-    want_stamp_base: number;
+    touch_bits_base: number;
+    touch_word_count: 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

@@ -1 +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"}
+{"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;IAR2B,iBAAiB,EAAjC,MAAM;IACU,aAAa,EAA7B,MAAM;IACJ;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAClF,UAAgB,EAAE,MAAM,CAAA;CAAC,CAmBzB"}

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

@@ -8,47 +8,38 @@ import { VGEO_WANT_WORDS } from "../layout/VGEO_WANT_WORDS.js";
  * 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.
+ * list written over the touch bits, 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.
+ * **Header, touch bits, want records — and the whole of it is read back.** Two regions used to sit
+ * between the header and the lists and neither was the CPU's business: a stamp word per page row
+ * and a stamp word per lookup word, cleared with the transient every frame and mapped back with
+ * it. At the playground's 4,096 slots that was 344 KB a frame across the bus for 33 KB of lists,
+ * and the lookup-sized half of it grew with every registered geometry rather than with anything
+ * seen. The touch stamps are the touch bits now — one bit per row, which is both the dedup and
+ * the record — and the want stamps live in a persistent, frame-tagged buffer the pool owns and
+ * nothing reads back (RUNTIME_PLAN_2026_09_14 §2.2, §2.3).
  *
  * @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.page_row_capacity one touch bit per page-table row
  * @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}}
+ * @returns {{touch_bits_base: number, touch_word_count: number, want_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,
-                                         }) {
+export function vgeo_cut_feedback_layout({ page_row_capacity, want_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;
+    const touch_bits_base = VGEO_FEEDBACK_OFFSET.HEADER_WORDS;
+    const touch_word_count = Math.max(1, Math.ceil(page_row_capacity / 32));
+    const want_base = touch_bits_base + touch_word_count;
 
     return {
-        touch_stamp_base,
-        want_stamp_base,
+        touch_bits_base,
+        touch_word_count,
         want_base,
-        touch_base,
-        word_count: touch_base + touch_capacity,
+        word_count: want_base + want_capacity * VGEO_WANT_WORDS,
     };
 }

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

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

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

@@ -9,6 +9,7 @@ import { graph_prefix_scan_csdldf } from "../../../gpu_primitive/prefix_sum/v1/g
 import { RasterizationCollectionType } from "../../../rasterize/expand/RasterizationCollectionType.js";
 import { shader_vgeo_cut_collect } from "./cut/shader_vgeo_cut_collect.js";
 import { shader_vgeo_cut_queue_prepare } from "./cut/shader_vgeo_cut_queue_prepare.js";
+import { shader_vgeo_cut_queue_remainder } from "./cut/shader_vgeo_cut_queue_remainder.js";
 import { shader_vgeo_cut_seed } from "./cut/shader_vgeo_cut_seed.js";
 import { shader_vgeo_cut_traverse } from "./cut/shader_vgeo_cut_traverse.js";
 import { VGEO_CUT_WORKGROUP_SIZE } from "./cut/VGEO_CUT_WORKGROUP_SIZE.js";
@@ -87,6 +88,30 @@ export function graph_vgeo_expand_instances_to_meshlets({
         meshlet_capacity: Math.max(1, limits.get_limit(RasterizationCollectionType.Meshlets)),
     });
 
+    /*
+     This view's own uniform, written here rather than when the frame opened. `projection_k` is
+     the render target's height over the camera's field of view, so it belongs to a view and not
+     to a frame — one buffer for the frame meant a shadow cascade cutting against whichever view
+     opened it. The capacities above are frame-global and collapse to a `Math.min` across sites,
+     and writing after `declare_collections` is what puts the smallest of them in the buffer that
+     this view's passes read.
+    */
+    const view_cut = view.virtual_geometry_cut;
+
+    view_cut.set_projection({
+        screen_height: Math.max(1, view.resolution[1]),
+        fov_y: view.camera.camera.fov,
+    });
+
+    /*
+     Sized against the tier this cut names rows of, before the params that carry its bound.
+     A page row is what the frontier records, so the tier's capacity is the only thing it
+     has to agree with.
+    */
+    view_cut.resize_frontier(pool.page_row_capacity);
+
+    view_cut.write_params({ runtime });
+
     // ----- collect: which of these instances are virtual, and where is the camera in each one -----
 
     const collect_command = graph_build_indirect_dispatch_command(
@@ -100,7 +125,7 @@ export function graph_vgeo_expand_instances_to_meshlets({
             encoder: context.encoder,
             command: resources.get(data.command),
             bindings: {
-                params: runtime.params_buffer,
+                params: view_cut.params_buffer,
                 camera: view.camera.buffer,
                 scene_database: scene.scene_database_buffer,
                 geometries: scene.geometries.buffer_metadata,
@@ -162,7 +187,7 @@ export function graph_vgeo_expand_instances_to_meshlets({
             encoder: context.encoder,
             command: resources.get(data.command),
             bindings: {
-                params: runtime.params_buffer,
+                params: view_cut.params_buffer,
                 vg_arena: pool.buffer_arena,
                 prefix_sums: resources.get(data.prefix_sums),
                 instances: resources.get(data.instances),
@@ -196,8 +221,7 @@ export function graph_vgeo_expand_instances_to_meshlets({
     /*
      The two queues ping-pong, so *which* of them holds work is not a property of either buffer —
      it moves every iteration. Carrying the roles rather than the buffers is what makes the tail
-     pass below correct at any `max_iterations`: it was written as `queue_a`, which is the produced
-     queue only when the iteration count is even, and the default of 64 is (REVIEW_LEDGER M8).
+     pass below correct at any `max_iterations` rather than only at an even one (REVIEW_LEDGER M8).
      */
     let ready_queue = seed_data.queue_out;
     let spare_queue = spare_spawn.create("vg queue b", queue_descriptor);
@@ -218,11 +242,10 @@ export function graph_vgeo_expand_instances_to_meshlets({
                 shader_vgeo_cut_queue_prepare.dispatch({
                     encoder: context.encoder,
                     bindings: {
-                        params: runtime.params_buffer,
+                        params: view_cut.params_buffer,
                         queue_ready: resources.get(data.queue_ready),
                         queue_spare: resources.get(data.queue_spare),
                         command: resources.get(data.command),
-                        feedback: resources.get(data.feedback),
                     }
                 });
             }
@@ -238,8 +261,6 @@ export function graph_vgeo_expand_instances_to_meshlets({
         const ready = prepare_data.queue_ready = prepare_pass.write(ready_queue);
         const spare = prepare_data.queue_spare = prepare_pass.write(spare_queue);
 
-        feedback = prepare_data.feedback = prepare_pass.write(feedback);
-
         prepare_data.command = prepare_pass.create(
             `vg command ${iteration}`, INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
         );
@@ -252,14 +273,16 @@ export function graph_vgeo_expand_instances_to_meshlets({
                     encoder: context.encoder,
                     command: resources.get(data.command),
                     bindings: {
-                        params: runtime.params_buffer,
+                        params: view_cut.params_buffer,
                         vg_lookup: pool.buffer_lookup,
                         vg_arena: pool.buffer_arena,
+                        vg_want_stamps: pool.buffer_want_stamps,
                         instances: resources.get(data.instances),
                         queue_in: resources.get(data.queue_in),
                         queue_out: resources.get(data.queue_out),
                         claim: resources.get(data.claim),
                         feedback: resources.get(data.feedback),
+                        frontier: view_cut.frontier_buffer,
                         out_meshlets: resources.get(data.out_meshlets),
                     }
                 });
@@ -282,35 +305,32 @@ export function graph_vgeo_expand_instances_to_meshlets({
     }
 
     /*
-     One more prepare, for its counters alone. The loop above records a fixed number of
-     prepare/traverse pairs and the queue can still hold work when the last of them finishes — a
-     subtree never descended, which is a hole rather than a coarse stand-in, and the one degradation
-     §4.5 admits. Nothing recorded it. This pass leaves the outstanding count in
-     `VGEO_CUT_STAT.QUEUE_REMAINING`, and the dispatch command it also produces is simply not used.
-
-     `ready_queue` and not `queue_a`: the prepare pass reports the count of `queue_ready` and
-     *zeroes* `queue_spare`, so binding the drained queue as ready would report a count of work
-     already done and destroy the count of the work that was left. Which buffer holds which
+     One more pass, for one number. The loop above records a fixed number of prepare/traverse pairs
+     and the queue can still hold work when the last of them finishes — a subtree never descended,
+     which is a hole rather than a coarse stand-in, and the one degradation §4.5 admits. This is
+     where `VGEO_CUT_STAT.QUEUE_REMAINING` comes from.
+
+     It is not the prepare pass: that one runs *between* wavefronts and once per iteration per
+     expansion site, so what it could report is a frontier rather than a remainder, and the next
+     site would overwrite it. See {@link shader_vgeo_cut_queue_remainder}.
+
+     `ready_queue` and not either buffer by name: which of the two holds the produced queue
      alternates per iteration, so the roles are carried through the loop rather than named here.
      */
     const tail_data = {};
 
     const tail_pass = graph.add("vg queue tail", tail_data, (data, resources, context) => {
-        shader_vgeo_cut_queue_prepare.dispatch({
+        shader_vgeo_cut_queue_remainder.dispatch({
             encoder: context.encoder,
             bindings: {
-                params: runtime.params_buffer,
+                params: view_cut.params_buffer,
                 queue_ready: resources.get(data.queue_ready),
-                queue_spare: resources.get(data.queue_spare),
-                command: resources.get(data.command),
                 feedback: resources.get(data.feedback),
             }
         });
     });
 
-    tail_data.queue_ready = tail_pass.write(ready_queue);
-    tail_data.queue_spare = tail_pass.write(spare_queue);
-    tail_data.command = tail_pass.create("vg command tail", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
+    tail_data.queue_ready = tail_pass.read(ready_queue);
 
     feedback = tail_data.feedback = tail_pass.write(feedback);
 

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT.d.ts

@@ -13,5 +13,6 @@ export namespace VGEO_CUT_STAT {
     let INSTANCES_DROPPED: number;
     let WAVEFRONTS: number;
     let QUEUE_REMAINING: number;
+    let CULLED_CLUSTER: number;
 }
 //# sourceMappingURL=VGEO_CUT_STAT.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT.js

@@ -96,4 +96,15 @@ export const VGEO_CUT_STAT = {
      * number that was outstanding at the end.
      */
     QUEUE_REMAINING: 13,
+    /**
+     * Clusters discarded by the frustum before they could draw, clamp or refine.
+     *
+     * {@link CULLED_FRUSTUM} is a node's whole subtree; this is one cluster, and it is the one that
+     * matters for residency. A cluster claims — and touches — its child page the moment it refines,
+     * and the frustum used to be consulted only at the child's nodes, after the claim. Zoomed in on
+     * a wall, every cluster of the wall at that level refined whether or not it was on screen,
+     * 4,044 rows of 4,096 were touched a frame, and nothing was ever cold enough to evict
+     * (RUNTIME_PLAN_2026_09_14 §0, §2.1).
+     */
+    CULLED_CLUSTER: 14,
 };

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT_COUNT.js

@@ -5,4 +5,4 @@
  * @copyright Company Named Limited (c) 2026
  * @type {number}
  */
-export const VGEO_CUT_STAT_COUNT = 14;
+export const VGEO_CUT_STAT_COUNT = 15;

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_FEEDBACK_OFFSET.d.ts

@@ -1,6 +1,5 @@
 export namespace VGEO_FEEDBACK_OFFSET {
     let WANT_COUNT: number;
-    let TOUCH_COUNT: number;
     let STATS: number;
     let HEADER_WORDS: number;
 }

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_FEEDBACK_OFFSET.js

@@ -4,24 +4,26 @@ import { VGEO_CUT_STAT_COUNT } from "./VGEO_CUT_STAT_COUNT.js";
  * Word offsets in the feedback buffer — the one thing the cut hands back to the CPU, and the only
  * place in the runtime where a GPU pass and a host frame meet.
  *
- * Header first, then the two lists, so a readback of the header alone tells a saturated frame how
- * much of the rest is worth mapping. Design §6: the wants loop tolerates its transport — multi-frame
- * `mapAsync` latency, a small in-flight cap, and frames where feedback is skipped entirely.
+ * Header first, then the touch bits, then the want records; see `vgeo_cut_feedback_layout` for the
+ * two that move. Design §6: the wants loop tolerates its transport — multi-frame `mapAsync`
+ * latency, a small in-flight cap, and frames where feedback is skipped entirely.
+ *
+ * There is no touch count any more. A touch is one bit per page row (RUNTIME_PLAN_2026_09_14
+ * §2.2), so the list it used to count, and the capacity that list could overflow, are gone.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
 export const VGEO_FEEDBACK_OFFSET = {
     WANT_COUNT: 0,
-    TOUCH_COUNT: 1,
     /**
-     * Counters live in the header so that a frame whose lists overflowed still says so.
+     * Counters live in the header so that a frame whose list overflowed still says so.
      */
-    STATS: 2,
+    STATS: 1,
     /**
-     * Where the want records begin. The lists themselves are sized by the caller's options and
-     * their bases travel in the params block, because a graph resource's size is a host-side
-     * decision and the kernel must not assume one.
+     * Where the touch bits begin. The want records follow them, and their base travels in the
+     * params block because a graph resource's size is a host-side decision and the kernel must not
+     * assume one.
      */
-    HEADER_WORDS: 2 + VGEO_CUT_STAT_COUNT,
+    HEADER_WORDS: 1 + VGEO_CUT_STAT_COUNT,
 };

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_GROUP_ROW_OFFSET.d.ts

@@ -3,5 +3,6 @@ export namespace VGEO_GROUP_ROW_OFFSET {
     let CLUSTER_COUNT: number;
     let FLAGS: number;
     let PARENT_COUNT: number;
+    let PARENT_FIRST: number;
 }
 //# sourceMappingURL=VGEO_GROUP_ROW_OFFSET.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_GROUP_ROW_OFFSET.js

@@ -33,4 +33,12 @@ export const VGEO_GROUP_ROW_OFFSET = {
      * copy has been evicted underneath this tier still has a correct answer.
      */
     PARENT_COUNT: 3,
+    /**
+     * Where this group's run in the page's parent rows starts; {@link PARENT_COUNT} is its length.
+     *
+     * Zero on a page from a container written before `format_version` 4, which carries no upward
+     * edge — and so is that page's `PARENT_ENTRY_COUNT`, which is what a reader checks rather than
+     * asking the container its version.
+     */
+    PARENT_FIRST: 4,
 };

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_GROUP_ROW_WORDS.d.ts

@@ -1,6 +1,11 @@
 /**
- * Words in one group row. Four rather than three so a group block stays 16-byte aligned, which
- * costs nothing — a page carries a handful of groups against hundreds of clusters.
+ * Words in one group row.
+ *
+ * Five, and not padded back up to eight. Four used to buy a 16-byte-aligned group block for nothing,
+ * and the fifth word — `PARENT_FIRST` — spends that alignment rather than doubling the row: the
+ * cluster block that follows is 13 words a row and was never 16-byte aligned internally either, so
+ * there was nothing downstream the property was protecting. A page carries a handful of groups
+ * against hundreds of clusters, so neither choice is measurable; this one is only smaller.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

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

@@ -1 +1 @@
-{"version":3,"file":"VGEO_GROUP_ROW_WORDS.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_GROUP_ROW_WORDS.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,mCAFU,MAAM,CAEsB"}
+{"version":3,"file":"VGEO_GROUP_ROW_WORDS.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_GROUP_ROW_WORDS.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,mCAFU,MAAM,CAEsB"}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_GROUP_ROW_WORDS.js

@@ -1,9 +1,14 @@
 /**
- * Words in one group row. Four rather than three so a group block stays 16-byte aligned, which
- * costs nothing — a page carries a handful of groups against hundreds of clusters.
+ * Words in one group row.
+ *
+ * Five, and not padded back up to eight. Four used to buy a 16-byte-aligned group block for nothing,
+ * and the fifth word — `PARENT_FIRST` — spends that alignment rather than doubling the row: the
+ * cluster block that follows is 13 words a row and was never 16-byte aligned internally either, so
+ * there was nothing downstream the property was protecting. A page carries a handful of groups
+ * against hundreds of clusters, so neither choice is measurable; this one is only smaller.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  * @type {number}
  */
-export const VGEO_GROUP_ROW_WORDS = 4;
+export const VGEO_GROUP_ROW_WORDS = 5;

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_PAGE_ROW_OFFSET.d.ts

@@ -7,5 +7,7 @@ export namespace VGEO_PAGE_ROW_OFFSET {
     let ORDINAL: number;
     let GEOMETRY_ROW: number;
     let DECODED_SIZE: number;
+    let PARENT_ENTRY_COUNT: number;
+    let GENERATION: number;
 }
 //# sourceMappingURL=VGEO_PAGE_ROW_OFFSET.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_PAGE_ROW_OFFSET.js

@@ -58,4 +58,23 @@ export const VGEO_PAGE_ROW_OFFSET = {
      * down itself cannot drift.
      */
     DECODED_SIZE: 7,
+    /**
+     * Entries in this page's parent rows — the sum of every group's `PARENT_COUNT`, and the bound
+     * a walk up must stay inside.
+     *
+     * **Zero says the container has no upward edge**, which is every container written before
+     * `format_version` 4. A kernel that wants to coarsen reads this rather than asking what version
+     * the asset is, and takes zero as "re-descend instead".
+     */
+    PARENT_ENTRY_COUNT: 8,
+    /**
+     * `VGeoRuntimeTables`' own generation for this row, mirrored here at install.
+     *
+     * A page row is reused: an eviction bumps the counter, so a value stored beside a row reference
+     * stays true only while the row still holds the occupant it was written against. Anything that
+     * outlives a frame — a cut kept between frames is the case this is for — stores the generation
+     * it saw and compares, which is one equality and no clock. A frame number would need an
+     * ordering argument instead, and would still not separate two installs inside one frame.
+     */
+    GENERATION: 9,
 };

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

@@ -1 +1 @@
-{"version":3,"file":"VGEO_PAGE_ROW_WORDS.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_PAGE_ROW_WORDS.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,kCAFU,MAAM,CAEqB"}
+{"version":3,"file":"VGEO_PAGE_ROW_WORDS.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_PAGE_ROW_WORDS.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,kCAFU,MAAM,CAEsB"}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_PAGE_ROW_WORDS.js

@@ -5,4 +5,4 @@
  * @copyright Company Named Limited (c) 2026
  * @type {number}
  */
-export const VGEO_PAGE_ROW_WORDS = 8;
+export const VGEO_PAGE_ROW_WORDS = 10;

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_PARENT_ROW_OFFSET.d.ts

@@ -0,0 +1,5 @@
+export namespace VGEO_PARENT_ROW_OFFSET {
+    let PAGE_INDEX: number;
+    let CLUSTER: number;
+}
+//# sourceMappingURL=VGEO_PARENT_ROW_OFFSET.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_PARENT_ROW_OFFSET.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_PARENT_ROW_OFFSET.js"],"names":[],"mappings":""}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_PARENT_ROW_OFFSET.js

@@ -0,0 +1,22 @@
+/**
+ * Word offsets within one parent row.
+ *
+ * A group's parents are the clusters that would be drawn in its place if the camera pulled back, so
+ * the row names a cluster the way a cluster row names its child: a global page index, and an index
+ * within that page. What a coarsening kernel does with the pair is what the descent already does
+ * with `CHILD_PAGE_INDEX`/`CHILD_GROUP` — resolve the page through `vg_lookup`, then read the row.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_PARENT_ROW_OFFSET = {
+    /**
+     * The container page index holding this parent, resolved at install: `SAME_PAGE` has already
+     * become this page's own index, so a reader here never meets a sentinel.
+     */
+    PAGE_INDEX: 0,
+    /**
+     * Cluster index within that page.
+     */
+    CLUSTER: 1,
+};

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_PARENT_ROW_WORDS.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Words in one parent row — the arena's copy of a group-parent entry (`VGEO_FORMAT.md` §6.3).
+ *
+ * Two, where the file's entry is one word, because the file's `parent_ref` indexes a per-page table
+ * and the arena's does not: an install resolves it to a **global container page index**, exactly as
+ * it resolves `child_ref`, so the kernel's lookup path is the same in both directions and there is
+ * no `SAME_PAGE` branch in the shader.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_PARENT_ROW_WORDS: number;
+//# sourceMappingURL=VGEO_PARENT_ROW_WORDS.d.ts.map

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

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

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_PARENT_ROW_WORDS.js

@@ -0,0 +1,13 @@
+/**
+ * Words in one parent row — the arena's copy of a group-parent entry (`VGEO_FORMAT.md` §6.3).
+ *
+ * Two, where the file's entry is one word, because the file's `parent_ref` indexes a per-page table
+ * and the arena's does not: an install resolves it to a **global container page index**, exactly as
+ * it resolves `child_ref`, so the kernel's lookup path is the same in both directions and there is
+ * no `SAME_PAGE` branch in the shader.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_PARENT_ROW_WORDS = 2;

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_TARGET_PARENT_BIT.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Set in a queue item's `target` when it names an entry of a page's parent rows — one step of a
+ * walk *up* — rather than a node to descend or a group to evaluate.
+ *
+ * It is its own item kind rather than a page visit produced directly because of the claim. A page
+ * visit carries the promise that its producer already claimed the page, and a group with several
+ * parents produces several of them at once: the producer would have to claim each, count only the
+ * ones it won, and then hand any lane of the wave a rule for building the k-th *won* page out of
+ * five numbers. One extra hop costs a queue round trip on a path that moves under one entry a frame
+ * (CUT_PLAN_2026_09_14 §6.7) and keeps the claim exactly where every other page visit puts it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_QUEUE_TARGET_PARENT_BIT: number;
+//# sourceMappingURL=VGEO_QUEUE_TARGET_PARENT_BIT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_QUEUE_TARGET_PARENT_BIT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_TARGET_PARENT_BIT.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,2CAFU,MAAM,CAEuC"}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_TARGET_PARENT_BIT.js

@@ -0,0 +1,16 @@
+/**
+ * Set in a queue item's `target` when it names an entry of a page's parent rows — one step of a
+ * walk *up* — rather than a node to descend or a group to evaluate.
+ *
+ * It is its own item kind rather than a page visit produced directly because of the claim. A page
+ * visit carries the promise that its producer already claimed the page, and a group with several
+ * parents produces several of them at once: the producer would have to claim each, count only the
+ * ones it won, and then hand any lane of the wave a rule for building the k-th *won* page out of
+ * five numbers. One extra hop costs a queue round trip on a path that moves under one entry a frame
+ * (CUT_PLAN_2026_09_14 §6.7) and keeps the claim exactly where every other page visit puts it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_QUEUE_TARGET_PARENT_BIT = 0x40000000;

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

@@ -0,0 +1,15 @@
+/**
+ * Spawn one page-fetch worker.
+ *
+ * The `new Worker(new URL(..., import.meta.url), { type: "module" })` form is what the consumer's
+ * bundler detects and what vite serves as-is, and it lives in a module no spec imports, because
+ * `import.meta` is a parse error under a CommonJS transform — the same arrangement
+ * `makeClothWorker` keeps for the same reason.
+ *
+ * @returns {Worker}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function make_vgeo_page_worker(): Worker;
+//# sourceMappingURL=make_vgeo_page_worker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"make_vgeo_page_worker.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/make_vgeo_page_worker.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,yCALa,MAAM,CAOlB"}

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

@@ -0,0 +1,16 @@
+/**
+ * Spawn one page-fetch worker.
+ *
+ * The `new Worker(new URL(..., import.meta.url), { type: "module" })` form is what the consumer's
+ * bundler detects and what vite serves as-is, and it lives in a module no spec imports, because
+ * `import.meta` is a parse error under a CommonJS transform — the same arrangement
+ * `makeClothWorker` keeps for the same reason.
+ *
+ * @returns {Worker}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function make_vgeo_page_worker() {
+    return new Worker(new URL("./vgeo_page.worker.js", import.meta.url), { type: "module" });
+}