@woosh/meep-engine 3.26.0 → 3.27.0

package/src/shade/playground/vgeo_viewer/sample_asset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sample_asset.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_viewer/sample_asset.js"],"names":[],"mappings":"AAyFA;;;;;;;;;;;GAWG;AACH,2CALW,MAAM,UACN,MAAM,cACN,MAAM,GACJ;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAiBtD;+BAzGM,+DAA+D"}
+{"version":3,"file":"sample_asset.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_viewer/sample_asset.js"],"names":[],"mappings":"AA0GA;;;;;;;;;;;GAWG;AACH,2CALW,MAAM,UACN,MAAM,cACN,MAAM,GACJ;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAiBtD;+BA1HM,+DAA+D"}

package/src/shade/playground/vgeo_viewer/sample_asset.js

@@ -56,13 +56,30 @@ function torus(major, minor) {
 
     const stride = minor + 1;
 
+    /*
+     Wound so that a triangle seen from **outside** the tube is counter-clockwise, which is what
+     `CullPolicy.Standard` means by a front face and what `vgeo_compute_vertex_normals` takes the
+     sign of its normals from.
+
+     It was the other way round, and both of the pages that build this were blind to it: the viewer
+     draws its cut with `cullMode: 'none'` and colours it per cluster, so neither the culling nor
+     the shading could report it. The moment the same sample went through the engine's material
+     path — `playground/vgeo_runtime/`, where a `Front`-sided material culls back faces — the torus
+     rendered as its own far inner wall with the near surface missing, and the normals pointed into
+     the tube so what survived was lit from inside.
+
+     The winding of a sample is not a detail of the sample. Everything downstream of the builder
+     carries it: the cluster's triangles are stored in this order, the DAG's simplification
+     preserves it, and the pool hands it to the rasterizer untouched — so this one line decides
+     whether the whole chain has ever been seen drawing a surface the right way out.
+     */
     for (let i = 0; i < major; i++) {
         for (let j = 0; j < minor; j++) {
             const a = i * stride + j;
             const b = a + stride;
 
-            indices.push(a, b, a + 1);
-            indices.push(a + 1, b, b + 1);
+            indices.push(a, a + 1, b);
+            indices.push(a + 1, b + 1, b);
         }
     }
 

package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.d.ts

@@ -72,6 +72,17 @@ export class GPUGeometryBVHManager {
      */
     get empty_tree_address(): number;
     get gpu_memory_usage(): number;
+    /**
+     * Bytes of the node arena that trees actually occupy: its capacity, less every region
+     * {@link #allocator} still holds free.
+     *
+     * Beside {@link gpu_memory_usage}, which is what the arenas cost whether or not anything is
+     * in them. The gap between the two is what a released tree gives back and what the next tree
+     * of that size takes, so it is the one worth watching.
+     *
+     * @returns {number} in bytes
+     */
+    get gpu_memory_usage_occupied(): number;
     /**
      * The tree belonging to `owner`, registered against `source`'s shape if it does not exist yet.
      *

package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryBVHManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js"],"names":[],"mappings":"AAmBA;;;GAGG;AAEH;;;;;GAKG;AACH,gDAGG;AAEH;;;;;;;;;;;GAWG;AACH,sCAFU,MAAM,CAEyB;AAoBzC;;;;;;;;;;;;;;GAcG;AACH;IA0II;;;OAGG;IACH,+BAoDC;IA1LD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,6BAEC;IAuCD;;OAEG;IACH,gCAEC;IAOD;;OAEG;IACH,mCAEC;IA+BD;;OAEG;IACH,gCAEC;IA6ED;;;;OAIG;IACH,iCAEC;IAED,+BAoBC;IAED;;;;;;;;;;;;;;OAcG;IACH,cALW,MAAM,UACN,eAAe,GAEb,sBAAsB,CAalC;IA8DD;;;;;;;;;;;;OAYG;IACH,wBAHW,MAAM,GACJ;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAqB3I;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAU5B;IAED;;;;;;;;;OASG;IACH,0BAFW,WAAW,QAQrB;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,GACJ,OAAO,CA8BnB;IA4LD;;;;;;;OAOG;IACH,eAOC;;CAuIJ;8BAxzBY,OAAO,uBAAuB,EAAE,eAAe;yBAC/C,OAAO,sDAAsD,EAAE,UAAU;6BAbzD,mCAAmC;uCASzB,6BAA6B"}
+{"version":3,"file":"GPUGeometryBVHManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js"],"names":[],"mappings":"AAkBA;;;GAGG;AAEH;;;;;GAKG;AACH,gDAGG;AAEH;;;;;;;;;;;GAWG;AACH,sCAFU,MAAM,CAEyB;AAoBzC;;;;;;;;;;;;;;GAcG;AACH;IA0II;;;OAGG;IACH,+BAoDC;IA1LD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,6BAEC;IAuCD;;OAEG;IACH,gCAEC;IAOD;;OAEG;IACH,mCAEC;IA+BD;;OAEG;IACH,gCAEC;IA6ED;;;;OAIG;IACH,iCAEC;IAED,+BAoBC;IAED;;;;;;;;;OASG;IACH,wCAIC;IAED;;;;;;;;;;;;;;OAcG;IACH,cALW,MAAM,UACN,eAAe,GAEb,sBAAsB,CAalC;IA8DD;;;;;;;;;;;;OAYG;IACH,wBAHW,MAAM,GACJ;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAqB3I;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAU5B;IAED;;;;;;;;;OASG;IACH,0BAFW,WAAW,QAQrB;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,GACJ,OAAO,CA8BnB;IA4LD;;;;;;;OAOG;IACH,eAOC;;CAgIJ;8BAj0BY,OAAO,uBAAuB,EAAE,eAAe;yBAC/C,OAAO,sDAAsD,EAAE,UAAU;6BAbzD,mCAAmC;uCASzB,6BAA6B"}

package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js

@@ -4,7 +4,6 @@ import { platform_compute_endianness } from "../../../../core/binary/platform_co
 import { array_buffer_copy } from "../../../../core/collection/array/typed/array_buffer_copy.js";
 import { Deque } from "../../../../core/collection/queue/Deque.js";
 import { round_up } from "../../../../core/math/round_up.js";
-import { number_format_by_thousands } from "../../../../core/primitives/numbers/number_format_by_thousands.js";
 import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 import { BVH2_NODE_STRUCT } from "../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
@@ -307,6 +306,22 @@ export class GPUGeometryBVHManager {
         return r;
     }
 
+    /**
+     * Bytes of the node arena that trees actually occupy: its capacity, less every region
+     * {@link #allocator} still holds free.
+     *
+     * Beside {@link gpu_memory_usage}, which is what the arenas cost whether or not anything is
+     * in them. The gap between the two is what a released tree gives back and what the next tree
+     * of that size takes, so it is the one worth watching.
+     *
+     * @returns {number} in bytes
+     */
+    get gpu_memory_usage_occupied() {
+        const free_nodes = this.#allocator.storageReport().totalFreeSpace;
+
+        return (this.#node_capacity - free_nodes) * BVH2_NODE_STRUCT.size;
+    }
+
     /**
      * The tree belonging to `owner`, registered against `source`'s shape if it does not exist yet.
      *
@@ -828,13 +843,6 @@ export class GPUGeometryBVHManager {
             );
         }
 
-        const free_nodes = this.#allocator.storageReport().freeStorage;
-
-        console.warn(
-            `BLAS size: ${number_format_by_thousands((this.#node_capacity - free_nodes) * BVH2_NODE_STRUCT.size)} bytes` +
-            ` of ${number_format_by_thousands(this.#node_capacity * BVH2_NODE_STRUCT.size)}`
-        );
-
         device.queue.submit([encoder.finish()])
 
         // free up the temp buffer

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshletManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/GPUMeshletManager.js"],"names":[],"mappings":"AAuFA;IAqEI;;;;;;OAMG;IACH;QAJ8B,MAAM;QACR,qBAAqB,GAAtC,MAAM;QACW,yBAAyB,GAA1C,MAAM;OAkChB;IAzFD,6BAEC;IAOD,iCAEC;IAgFD,gBAKC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,sBAHW,MAAM,uBACN,MAAM,QAuHhB;IAqRD;;;;;;;;;;;OAWG;IACH,qBAJW,4BAA4B,GAE1B,OAAO,CAmBnB;IAgCD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+BAHW,4BAA4B,GAC1B,4BAA4B,CA8BxC;IAED;;;;;;;;;;;;OAYG;IACH,gBAFW,sBAAsB,QA8GhC;IAED,gBAGC;IAED;;;;OAIG;IACH,iBAHW,YAAY,GACV,4BAA4B,CA6BxC;IAED,mCASC;IAED,wCAQC;IAED,+BAYC;;CACJ;yBA/4BY,OAAO,sDAAsD,EAAE,UAAU;qCACzE,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;AA6BrD;IACI;;OAEG;IACH,UAFU,UAAU,CAEZ;IACR;;OAEG;IACH,MAFU,UAAU,CAEhB;IAEJ;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,0BAFU,WAAW,CAEI;IAEzB;;;OAGG;IACH,aAAsB;CACzB"}
+{"version":3,"file":"GPUMeshletManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/GPUMeshletManager.js"],"names":[],"mappings":"AAuFA;IA4EI;;;;;;OAMG;IACH;QAJ8B,MAAM;QACR,qBAAqB,GAAtC,MAAM;QACW,yBAAyB,GAA1C,MAAM;OAkChB;IAhGD,6BAEC;IAOD,iCAEC;IAuFD,gBAKC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,sBAHW,MAAM,uBACN,MAAM,QAuHhB;IAoRD;;;;;;;;;;;OAWG;IACH,qBAJW,4BAA4B,GAE1B,OAAO,CAkBnB;IAgCD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+BAHW,4BAA4B,GAC1B,4BAA4B,CA8BxC;IAED;;;;;;;;;;;;OAYG;IACH,gBAFW,sBAAsB,QA8GhC;IAED,gBAGC;IAED;;;;OAIG;IACH,iBAHW,YAAY,GACV,4BAA4B,CA6BxC;IAED,mCASC;IAED,wCAQC;IAED,+BAYC;;CACJ;yBAp5BY,OAAO,sDAAsD,EAAE,UAAU;qCACzE,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;AA6BrD;IACI;;OAEG;IACH,UAFU,UAAU,CAEZ;IACR;;OAEG;IACH,MAFU,UAAU,CAEhB;IAEJ;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,0BAFU,WAAW,CAEI;IAEzB;;;OAGG;IACH,aAAsB;CACzB"}

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.js

@@ -129,10 +129,17 @@ export class GPUMeshletManager {
     #deallocations_since_last_rebuild = 0;
 
     /**
+     * Every live allocation, in the order it was made — which is the order a rebuild packs them in.
      *
-     * @type {MeshletBatchAllocationRecord[]}
+     * A `Set` and not an array: {@link remove_batch} used to find its record with `indexOf` and take
+     * it out with `splice`, a walk of every record the manager held per removal. A static scene
+     * never noticed. A virtual-geometry tier evicts pages every frame, and each eviction paid a
+     * scan of every resident page and every static batch — 15 µs at 64,000 records, and an asset's
+     * unregister paid it once per page (RUNTIME_PLAN_2026_09_14 §0, step 0).
+     *
+     * @type {Set<MeshletBatchAllocationRecord>}
      */
-    #records = [];
+    #records = new Set();
 
     /**
      * Queue of GPU-side clones that have been allocated but not yet
@@ -407,7 +414,7 @@ export class GPUMeshletManager {
         const device = this.#device;
 
         const records = this.#records;
-        const record_count = records.length;
+        const record_count = records.size;
         const new_allocator_data = new OffsetAllocator(
             new_data_size,
             Math.max(record_count * 2, ALLOCATION_LIMIT)
@@ -438,9 +445,8 @@ export class GPUMeshletManager {
 
         const moved_records = [];
 
-        // move data
-        for (let i = 0; i < record_count; i++) {
-            const record = records[i];
+        // move data, in allocation order, which is the order the set keeps
+        for (const record of records) {
 
             const new_allocation_data = new_allocator_data.allocate(record.data_size);
             const new_allocation_metadata = new_allocator_metadata.allocate(record.meshlet_count);
@@ -613,7 +619,7 @@ export class GPUMeshletManager {
 
         record.metadata_buffer_original = batch.metadata_buffer;
 
-        this.#records.push(record);
+        this.#records.add(record);
 
         return record;
     }
@@ -633,8 +639,7 @@ export class GPUMeshletManager {
     remove_batch(record) {
         assert.defined(record, 'record');
 
-        const index = this.#records.indexOf(record);
-        if (index === -1) {
+        if (!this.#records.has(record)) {
             return false;
         }
 
@@ -643,7 +648,7 @@ export class GPUMeshletManager {
         this.#allocator_data.free(record.data);
         this.#allocator_metadata.free(record.metadata);
 
-        this.#records.splice(index, 1);
+        this.#records.delete(record);
         this.#deallocations_since_last_rebuild++;
 
         return true;
@@ -722,7 +727,7 @@ export class GPUMeshletManager {
         // the clone's metadata correctly under its new data offset.
         record.metadata_buffer_original = source.metadata_buffer_original;
 
-        this.#records.push(record);
+        this.#records.add(record);
 
         // The queue names the two records rather than the addresses they
         // hold right now. Both are in `#records`, so a rebuild between

package/src/shade/renderer/geometry/virtual/VGEO_FORMAT.md

@@ -116,7 +116,7 @@ All u64/u128 fields are naturally 8-byte aligned.
 | offset | type      | field                    | notes |
 |-------:|-----------|--------------------------|-------|
 | 0      | u32       | magic                    | `'VGEO'` = 0x4F454756 |
-| 4      | u16       | format_version           | 3 today; breaking layout changes only |
+| 4      | u16       | format_version           | 4 today; breaking layout changes only |
 | 6      | u16       | min_reader_version       | 3 today; reader MUST reject if its version is lower |
 | 8      | u16       | header_size              | = 256 |
 | 10     | u8        | hash_algo                | 0 = xxHash3; readers MUST reject unknown values |
@@ -145,6 +145,15 @@ All u64/u128 fields are naturally 8-byte aligned.
 | 160    | [u8; 88]  | reserved                 | |
 | 248    | u64       | header_checksum          | xxh3-64 of bytes 0–255 with this field zeroed (`asset_id` already final) |
 
+**`format_version` 4 moved and `min_reader_version` did not**, which is the pair working as
+intended rather than an oversight. 4 added the parent tables (§6.3, §6.4): they occupy bytes that
+were reserved and written as zero, and they sit between the cluster records and the payload, so
+every offset a version-3 reader computes lands exactly where it did and such a reader reads a
+version-4 file correctly by ignoring them. In the other direction a version-4 reader meets
+`parent_table_offset = 0` on an older file and takes it as "this container has no upward edge",
+which is true — so neither direction needs a version test, and nothing has to be rebuilt to stay
+readable.
+
 ### 4.1 Level table (`level_count` × 32 B, immediately after the header)
 
 Statistics per level, at `256 + 32·i`, ending where the root page frame begins. Small —
@@ -293,9 +302,15 @@ about 0.6 ms for a 256 KB page.
 ## 6. Decoded page
 
 ```
-[ PageHeader (56 B) ] [ Group table ] [ Node table ] [ Cluster records ] [ Payload ]
+[ PageHeader (56 B) ] [ Group table ] [ Node table ] [ Cluster records ]
+[ Parent-page table ] [ Group-parent table ] [ Payload ]
 ```
 
+The two parent tables sit between the cluster records and the payload, and that placement is the
+reason `min_reader_version` did not move (§4): `node_table_offset`'s `= 56 + 8·group_count` stays
+true, every earlier offset is where it was, and both tables hold 4-byte entries over sections that
+are already multiples of four, so §11.8's word-aligned payload survives.
+
 PageHeader:
 
 | offset | type | field                 | notes |
@@ -309,7 +324,9 @@ PageHeader:
 | 12     | u32  | payload_offset        | |
 | 16     | u32  | payload_size          | |
 | 20     | u32  | node_table_offset     | = `56 + 8·group_count`; the node table follows the group table |
-| 24     | [u8; 8] | reserved           | |
+| 24     | u32  | parent_table_offset   | start of the parent section — the parent-page table, then the group-parent table. **0 means the page carries neither**, which is what every container written before `format_version` 4 says about itself |
+| 28     | u16  | parent_entry_count    | entries in the group-parent table (§6.3) = Σ `parent_cluster_count` over this page's groups |
+| 30     | u16  | parent_page_count     | entries in the parent-page table (§6.4) |
 | 32     | metric | metric             | this page's own traversal metric (§6.2) — the root node's, repeated here so an installed page can be tested from itself |
 
 Group table — `group_count` × 8 B. Groups are the atomic LOD/residency unit; because a
@@ -320,8 +337,44 @@ construction — no global group index exists or is needed:
 |-------:|------|----------------------|-------|
 | 0      | u16  | cluster_first        | index into this page's cluster records |
 | 2      | u16  | cluster_count        | ≥ 1; ≤ 4096 (format cap, §11.5) |
-| 4      | u16  | parent_cluster_count | number of parent clusters referencing this group, `SAME_PAGE` references included; 0 exactly for the root page's topmost-level groups — drives activation (§10) |
-| 6      | u16  | reserved             | |
+| 4      | u16  | parent_cluster_count | number of parent clusters referencing this group, `SAME_PAGE` references included; 0 exactly for the root page's topmost-level groups — drives activation (§10). Also the length of this group's run in the group-parent table |
+| 6      | u16  | parent_first         | index of that run's first entry (§6.3). Groups tile the table in order, exactly as `cluster_first` tiles the cluster records |
+
+### 6.3 Group-parent table (`parent_entry_count` × 4 B)
+
+The format's **only upward edge**, and the mirror of the child table with everything a parent does
+not need taken out. Every entry here is the reverse of exactly one cluster's
+`child_ref`/`child_group` pair, and §11.16 holds the two to each other.
+
+| offset | type | field          | notes |
+|-------:|------|----------------|-------|
+| 0      | u16  | parent_ref     | index into the parent-page table (§6.4), or `SAME_PAGE` |
+| 2      | u16  | parent_cluster | cluster index within that page |
+
+**Four bytes an entry, against the child table's 48**, because the two directions are not
+symmetric. A child reference carries a fetch range and a metric copy because the child may be
+absent and the decision to fetch it is taken before it arrives. A parent of a group in the cut is
+resident already — `VGEO_GROUP_FLAG_SELECTABLE` is exactly "every parent reference is live" — so a
+parent reference has nothing to decide and only has to say where.
+
+Measured across 8,899 pages of 30 converted containers: 17.4 entries a page on average and 26 at
+the worst, so the table runs to about 70 bytes against pages of 56–256 KB, and compresses with the
+rest of them (§5: tables are 7% of page bytes at 1.6×).
+
+What it is *for* is a cut that is kept between frames. A cut that has descended to a group and then
+sees the camera pull back has to draw the clusters that consumed that group instead, and without
+this it could only find them by descending from the root again — which is the cost keeping a cut is
+meant to remove, paid on the common case.
+
+### 6.4 Parent-page table (`parent_page_count` × 4 B)
+
+One `page_index u32` per **distinct other** page holding a parent of one of this page's groups,
+deduplicated and ascending. A parent inside this page spends `SAME_PAGE` in §6.3 instead and has no
+entry here, so a page never appears in its own table.
+
+It lives in the decoded page rather than beside the plaintext child table because nothing needs it
+before decode: no fetch range is computed from it, and in the blob it compresses with the other
+tables. Measured: 4.9 entries a page on average, 18 at the worst.
 
 ### 6.1 Node table (`node_count` × 32 B)
 
@@ -734,6 +787,21 @@ clustering and simplification dominate regardless.
    into more bytes than a page holds has no layout, and the builder refuses it naming the page size
    that would work, rather than writing a page over the size the header states.
 
+15. **Parent-table bounds.** `parent_entry_count ≤ 65,535`, so that a group record's u16
+    `parent_first` can index the whole table, and `parent_page_count ≤ parent_entry_count`, since
+    no entry can name more than one page. The first is a cap rather than a wider field because the
+    distance is not close: the worst page of 8,899 measured carries 26 entries, which leaves the
+    bound standing 2,521× above it, and widening `parent_first` would cost the group record its
+    8-byte size. A builder that ever approached the cap would split the page.
+
+16. **The two edges agree.** Every entry of a page's group-parent table (§6.3) resolves to a
+    cluster whose `child_group` is the group whose run the entry is in; each group's run holds
+    exactly the clusters that name it, with no repeats; and the run is sorted by
+    (page index, cluster index). The first is what makes a coarsen legal at all. The third is what
+    lets a runtime elect one appender out of a group's several parents by taking the first entry of
+    the run, rather than carrying a dedup bitmask sized by instances × groups — so the order is
+    load-bearing and not presentation.
+
 ## 12. Open
 
 - Page codec ids beyond raw and LZ4 (§5). LZ4 is the default and is where the cheap

package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md

@@ -245,8 +245,12 @@ Pinned:
   same answer as by stopping its descent rather than by evaluating it everywhere: draw a
   cluster iff
 
-  `project(parent) > τ AND (project(self) ≤ τ OR child group non-selectable)`
+  `own group selectable AND project(parent) > τ AND (project(self) ≤ τ OR child group
+  non-selectable)`
 
+  The first term is not decoration: a group that is resident but not yet selectable satisfies
+  the rest of the rule while the coarser stand-in still covers the same surface, and both are
+  drawn a few microns apart — which reads as corrupt geometry rather than as a missing page.
   The clamp is what makes "no holes, ever" (§6) true: without it, when the τ-selected
   level lies below the streaming frontier, *no* resident cluster on that path satisfies
   the pure rule and the guaranteed stand-in is never selected. The child-group
@@ -265,10 +269,12 @@ Pinned:
   scale this design targets is millions of clusters every frame, most of them off-screen. A
   traversal costs the cut. It also gets two things for free that the flat rule pays for
   separately — a missing page simply stops the descent, which *is* the residency clamp, and
-  culling at an interior node discards a whole region rather than one cluster. The parallelism
-  objection is answered by nvpro's persistent-thread and subgroup-ballot scheme (see the
-  vk_lod_clusters comparison, §2.4); and the hierarchy it descends exists at two granularities. Pages
-  form a rooted, acyclic, fully-reachable DAG (§11.3–11.4 of the format), measurably
+  culling at an interior node discards a whole region rather than one cluster. WebGPU guarantees no
+  forward progress across workgroups, so the persistent-thread answer (nvpro, vk_lod_clusters
+  comparison §2.4) is unbounded waiting and is not available; a wave redistributes its own
+  production among its lanes instead, and the descent's depth runs inside one dispatch. The
+  hierarchy it descends exists at two granularities. Pages form a rooted, acyclic,
+  fully-reachable DAG (§11.3–11.4 of the format), measurably
   many-parented on any asset large enough to have more than one page per band, and every
   child-table entry and page header now carries a **traversal metric** so a page can be tested
   *before* it is fetched. Below page granularity, each page carries a tree over its own groups
@@ -493,12 +499,11 @@ because activation is safe at every arrival order). RAM eviction is no longer op
    material upstream of the builder), so the mesh-keyed material buckets downstream stay
    unchanged.
 
-   What it reads is the **VG selection buffer** — a VG-owned, densely maintained table of
-   resident clusters (two (sphere, error) pairs, geometry id, own-page and child-page/group
-   indices, child-group selectable bit — the page indices are what touch and want emission
-   stamp), plus per-geometry resident-cluster index tables. The existing metadata buffer is
-   *not* usable for this (freed slices hold garbage, and it carries no error pairs), which is
-   why the selection buffer exists.
+   What it reads is the **page arena** — one fixed-stride slot per resident page, holding that
+   page's header, node rows, group rows and cluster rows — and the per-geometry lookup that
+   resolves a child page index to a slot (RUNTIME_PLAN §3.1). There is no selection buffer and
+   no page table: a page's header is the first words of its own slot, and the two (sphere,
+   error) pairs are in its cluster rows.
 
    Superseded: this step previously specified a **flat** evaluation of the rule over every
    row of that buffer, at a cost of `O(Σ over visible instances of resident(geometry))`. §4
@@ -513,10 +518,16 @@ because activation is safe at every arrival order). RAM eviction is no longer op
    instances enter through their own expansion step. M0 was where that seam was to be fixed
    and it was not (§10); it is the first thing M1 has to do.
 
-Open: shadow views (v1 takes the one cut per view of §4, sharing setup rather than results,
-and a proxy where a view does not justify a cut); DRS τ semantics; the traversal's GPU shape —
-persistent threads over a queue, per nvpro, against what WebGPU without 64-bit atomics actually
-makes affordable.
+The traversal's GPU shape is settled and built: one indirect dispatch per spill generation, the
+descent's depth inside the kernel, work redistributed across a subgroup's lanes by prefix sum. A
+step costs about 0.5 µs whatever the wave holds, so a light asset pays for the shape of its descent
+rather than for its geometry, while a container with real work in the frontier pays mostly for the
+work. How many dispatches a cut needs is a queue-drain quantity rather than depth divided by the
+step count: a wave keeps `subgroup_size` children and spills the rest to the next dispatch.
+CUT_PLAN_2026_09_14 proposes to stop re-walking from the root by keeping the cut between frames.
+
+Open: shadow views (v1 takes the one cut per view of §4, sharing setup rather than results, and a
+proxy where a view does not justify a cut); DRS τ semantics.
 
 Settled since: **flat evaluation versus a hierarchy is no longer a measurement to take.** §4
 pins the traversal, and the hierarchy it descends is already written into every built asset

package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_PLAN.md

@@ -339,9 +339,11 @@ several cuts per frame for exactly this reason.
 
 So the plan is **a cut per view**, with the setup shared rather than the result: the traversal
 kernel, the residency state, and the page working set are all view-independent, and only the
-projection and threshold differ. And where a view does not justify a cut at all — a distant
-cascade, a low-resolution reflection — it should be able to take a proxy (§3.2) instead. That
-choice belongs to the view, not to the geometry.
+projection and threshold differ. That half is built — a cut runs per expansion site per view, and
+what it costs is measured in CUT_PLAN_2026_09_14 §0, which also plans to keep each view's cut
+between frames rather than re-walking it from the root. And where a view does not justify a cut
+at all — a distant cascade, a low-resolution reflection — it should be able to take a proxy
+(§3.2) instead. That choice belongs to the view, not to the geometry.
 
 ### 3.4 GPU-driven allocation `[V §4.3]`
 

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.d.ts

@@ -17,6 +17,24 @@ export class VGeoBuildOptions {
      * @type {number}
      */
     codec: number;
+    /**
+     * How hard the codec looks for matches, from {@link LZ4_LEVEL}. Nine by default, which is the
+     * top of the reference's hash-chain levels.
+     *
+     * **It changes nothing about the file.** Every level writes the same LZ4 block format, so a
+     * container built at any of them reads in every build of the reader that exists; the level is
+     * how long the *encoder* spent, and that is all.
+     *
+     * Nine rather than twelve because the ladder above it is not worth its time on this payload:
+     * measured over 2,718 real pages, the whole run from 3 to 12 is 0.077 percentage points of
+     * ratio, and 10 to 12 cost 15-40% more time for the last thousandth of it. Nine rather than
+     * three for the same reason in the other direction — it is 0.077 points smaller for about 5%
+     * more time. Nine rather than one because the fast encoder gives up 2.5% of every page to save
+     * compression time that is a couple of percent of a build.
+     *
+     * @type {number}
+     */
+    codec_level: number;
     /**
      * How close two source vertices have to be to count as one point, as a fraction of the
      * geometry's own bounding-box diagonal. **Leave it alone.** It is the one knob here that can

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCA1EgC,uBAAuB"}
+{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;OAgBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCA7FgC,uBAAuB"}

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js

@@ -1,3 +1,4 @@
+import { LZ4_LEVEL } from "../../../../../core/binary/lz4/LZ4_LEVEL.js";
 import { VGEO_CODEC_LZ4 } from "../format/frame/VGEO_CODEC_LZ4.js";
 import { VGEO_DEFAULT_PAGE_SIZE } from "../format/page/VGEO_DEFAULT_PAGE_SIZE.js";
 import { VGeoLevelOptions } from "./VGeoLevelOptions.js";
@@ -22,6 +23,25 @@ export class VGeoBuildOptions {
      */
     codec = VGEO_CODEC_LZ4;
 
+    /**
+     * How hard the codec looks for matches, from {@link LZ4_LEVEL}. Nine by default, which is the
+     * top of the reference's hash-chain levels.
+     *
+     * **It changes nothing about the file.** Every level writes the same LZ4 block format, so a
+     * container built at any of them reads in every build of the reader that exists; the level is
+     * how long the *encoder* spent, and that is all.
+     *
+     * Nine rather than twelve because the ladder above it is not worth its time on this payload:
+     * measured over 2,718 real pages, the whole run from 3 to 12 is 0.077 percentage points of
+     * ratio, and 10 to 12 cost 15-40% more time for the last thousandth of it. Nine rather than
+     * three for the same reason in the other direction — it is 0.077 points smaller for about 5%
+     * more time. Nine rather than one because the fast encoder gives up 2.5% of every page to save
+     * compression time that is a couple of percent of a build.
+     *
+     * @type {number}
+     */
+    codec_level = LZ4_LEVEL.HC_DEFAULT;
+
     /**
      * How close two source vertices have to be to count as one point, as a fraction of the
      * geometry's own bounding-box diagonal. **Leave it alone.** It is the one knob here that can

package/src/shade/renderer/geometry/virtual/build/vgeo_assemble_pages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_assemble_pages.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_assemble_pages.js"],"names":[],"mappings":"AA2JA;;;;;;;;;GASG;AACH,qDAPW,sBAAsB,EAAE,iBAExB,YAAY,qBACZ,MAAM,GAEJ,mBAAmB,EAAE,CA+HjC;oCA5RmC,sCAAsC"}
+{"version":3,"file":"vgeo_assemble_pages.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_assemble_pages.js"],"names":[],"mappings":"AAwMA;;;;;;;;;GASG;AACH,qDAPW,sBAAsB,EAAE,iBAExB,YAAY,qBACZ,MAAM,GAEJ,mBAAmB,EAAE,CAiIjC;oCAzUmC,sCAAsC"}

package/src/shade/renderer/geometry/virtual/build/vgeo_assemble_pages.js

@@ -4,6 +4,8 @@ import { VGEO_CLUSTER_RECORD_SIZE } from "../format/cluster/VGEO_CLUSTER_RECORD_
 import { VGEO_GROUP_RECORD_SIZE } from "../format/page/VGEO_GROUP_RECORD_SIZE.js";
 import { VGEO_NODE_RECORD_SIZE } from "../format/page/VGEO_NODE_RECORD_SIZE.js";
 import { VGEO_PAGE_HEADER_SIZE } from "../format/page/VGEO_PAGE_HEADER_SIZE.js";
+import { VGEO_PARENT_ENTRY_SIZE } from "../format/page/VGEO_PARENT_ENTRY_SIZE.js";
+import { VGEO_PARENT_PAGE_ENTRY_SIZE } from "../format/page/VGEO_PARENT_PAGE_ENTRY_SIZE.js";
 import { VirtualGeometryPage } from "../format/dag/VirtualGeometryPage.js";
 import { vgeo_build_page_nodes } from "./vgeo_build_page_nodes.js";
 import { vgeo_page_node_count } from "./vgeo_page_node_count.js";
@@ -31,18 +33,59 @@ import { vgeo_page_node_count } from "./vgeo_page_node_count.js";
  * @copyright Company Named Limited (c) 2026
  */
 
+/**
+ * How many clusters, anywhere in the build, name each group as their child.
+ *
+ * The same count {@link vgeo_write_container} recomputes as `parent_cluster_count`, needed a step
+ * earlier because it is also the length of the group's slice of the page's group-parent table
+ * (format §6.3) and therefore part of what a page costs. It is a property of the DAG, which
+ * assembly does not change, so counting it here and counting it again at write time cannot
+ * disagree.
+ *
+ * @param {VirtualGeometryGroup[][]} groups_by_level
+ * @returns {Map<VirtualGeometryGroup, number>}
+ */
+function count_group_parents(groups_by_level) {
+    const counts = new Map();
+
+    for (const groups of groups_by_level) {
+        for (const group of groups) {
+            for (const cluster of group.clusters) {
+                const child = cluster.child_group;
+
+                if (child !== undefined) {
+                    counts.set(child, (counts.get(child) ?? 0) + 1);
+                }
+            }
+        }
+    }
+
+    return counts;
+}
+
 /**
  * @param {VirtualGeometryGroup} group
+ * @param {Map<VirtualGeometryGroup, number>} parent_counts
  * @returns {number} bytes this group adds to a decoded page
  */
-function group_size_in_page(group) {
+function group_size_in_page(group, parent_counts) {
     let size = VGEO_GROUP_RECORD_SIZE;
 
     for (const cluster of group.clusters) {
         size += VGEO_CLUSTER_RECORD_SIZE + cluster.payload.byteLength;
     }
 
-    return size;
+    /*
+     The group's slice of the group-parent table, plus an upper bound on what it contributes to the
+     page's parent-page table. The exact parent-page count is not knowable here — it is how many
+     *distinct* pages the parents land in, and which page a parent lands in is what this function is
+     helping to decide — so bound it by one page per entry, which no group can exceed. Measured on
+     converted assets the real ratio is 17.4 entries to 4.9 pages, so the bound overstates a page's
+     parent section by about half of a number that is itself a fifth of a percent of the page.
+    */
+    const parents = parent_counts.get(group) ?? 0;
+
+    return size + parents * (VGEO_PARENT_ENTRY_SIZE + VGEO_PARENT_PAGE_ENTRY_SIZE);
 }
 
 /**
@@ -96,10 +139,11 @@ function page_decoded_size(group_count, content) {
  * its own, which is one group and therefore one node.
  *
  * @param {VirtualGeometryGroup} group
+ * @param {Map<VirtualGeometryGroup, number>} parent_counts
  * @returns {number}
  */
-function group_minimum_page_size(group) {
-    return page_decoded_size(1, group_size_in_page(group));
+function group_minimum_page_size(group, parent_counts) {
+    return page_decoded_size(1, group_size_in_page(group, parent_counts));
 }
 
 /**
@@ -111,8 +155,9 @@ function group_minimum_page_size(group) {
  *
  * @param {VirtualGeometryGroup[][]} groups_by_level
  * @param {number} nominal_page_size
+ * @param {Map<VirtualGeometryGroup, number>} parent_counts
  */
-function reject_groups_larger_than_a_page(groups_by_level, nominal_page_size) {
+function reject_groups_larger_than_a_page(groups_by_level, nominal_page_size, parent_counts) {
     let worst = undefined;
     let worst_level = 0;
     let worst_index = 0;
@@ -125,7 +170,7 @@ function reject_groups_larger_than_a_page(groups_by_level, nominal_page_size) {
         groups.forEach((group, index) => {
             total_count++;
 
-            const needs = group_minimum_page_size(group);
+            const needs = group_minimum_page_size(group, parent_counts);
 
             if (needs > nominal_page_size) {
                 over_count++;
@@ -167,7 +212,9 @@ export function vgeo_assemble_pages(groups_by_level, object_bounds, nominal_page
     assert.isPositiveInteger(nominal_page_size, 'nominal_page_size');
     assert.greaterThan(groups_by_level.length, 0, 'groups_by_level.length');
 
-    reject_groups_larger_than_a_page(groups_by_level, nominal_page_size);
+    const parent_counts = count_group_parents(groups_by_level);
+
+    reject_groups_larger_than_a_page(groups_by_level, nominal_page_size, parent_counts);
 
     const pages = [];
 
@@ -214,7 +261,7 @@ export function vgeo_assemble_pages(groups_by_level, object_bounds, nominal_page
             for (const group of groups) {
                 place(page, group);
 
-                content += group_size_in_page(group);
+                content += group_size_in_page(group, parent_counts);
             }
 
             // The cap has no exception, and this is the one page the fill rule below does not get to
@@ -250,7 +297,7 @@ export function vgeo_assemble_pages(groups_by_level, object_bounds, nominal_page
         let content = 0;
 
         for (const entry of keyed) {
-            const size = group_size_in_page(entry.group);
+            const size = group_size_in_page(entry.group, parent_counts);
 
             // What the page would come to *with* this group, node table and all — not what it came
             // to without it. The node table grows with the group count, so a page measured before

package/src/shade/renderer/geometry/virtual/build/vgeo_build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_build.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_build.js"],"names":[],"mappings":"AA8GA;;;;;;;;;;;;;;;;;;GAkBG;AACH,2EAFa,eAAe,CAwE3B;gCA7L+B,sBAAsB"}
+{"version":3,"file":"vgeo_build.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_build.js"],"names":[],"mappings":"AA8GA;;;;;;;;;;;;;;;;;;GAkBG;AACH,2EAFa,eAAe,CAyE3B;gCA9L+B,sBAAsB"}

package/src/shade/renderer/geometry/virtual/build/vgeo_build.js

@@ -168,6 +168,7 @@ export function vgeo_build(geometry, options) {
     const write_options = new VGeoWriteOptions();
 
     write_options.codec = options.codec;
+    write_options.codec_level = options.codec_level;
 
     // The table the header carries. A runtime reads it before any cluster record exists to it, and
     // brackets an instance's level range from the errors and radii alone — which is what lets a