@woosh/meep-engine 3.27.0 → 3.28.0

package/src/shade/renderer/geometry/virtual/build/submesh/vgeo_gather_faces.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Gather a face set: unique vertices in first-use order, local indices, coordinates copied out.
+ *
+ * First-use order is what makes the result depend only on the face list, not on the pool's history.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {number[]} face_ids allocated triangular faces
+ * @returns {VGeoGatheredFaces}
+ */
+export function vgeo_gather_faces(mesh: VirtualGeometryMesh, face_ids: number[]): VGeoGatheredFaces;
+import { VGeoGatheredFaces } from "./VGeoGatheredFaces.js";
+//# sourceMappingURL=vgeo_gather_faces.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_gather_faces.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/submesh/vgeo_gather_faces.js"],"names":[],"mappings":"AAcA;;;;;;;;GAQG;AACH,uEAHW,MAAM,EAAE,GACN,iBAAiB,CAiD7B;kCAlEiC,wBAAwB"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_gather_faces.js → submesh/vgeo_gather_faces.js}

@@ -1,7 +1,7 @@
-import { assert } from "../../../../../core/assert.js";
+import { assert } from "../../../../../../core/assert.js";
 import {
     bt_face_read_triangle_vertices
-} from "../../../../../core/geom/3d/topology/struct/binary/query/bt_face_read_triangle.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_face_read_triangle.js";
 import { VGeoGatheredFaces } from "./VGeoGatheredFaces.js";
 
 /**

package/src/shade/renderer/geometry/virtual/build/submesh/vgeo_narrow_indices.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The 8-bit local index list a cluster payload carries.
+ *
+ * @param {VGeoGatheredFaces} gathered a face set already within the meshlet limits
+ * @returns {Uint8Array}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_narrow_indices(gathered: VGeoGatheredFaces): Uint8Array;
+//# sourceMappingURL=vgeo_narrow_indices.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_narrow_indices.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/submesh/vgeo_narrow_indices.js"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,kEALa,UAAU,CAiBtB"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_narrow_indices.js → submesh/vgeo_narrow_indices.js}

@@ -1,6 +1,6 @@
-import { assert } from "../../../../../core/assert.js";
-import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "../format/cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
-import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "../format/cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
+import { assert } from "../../../../../../core/assert.js";
+import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "../../format/cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
+import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "../../format/cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
 
 /**
  * The 8-bit local index list a cluster payload carries.

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,CAyE3B;gCA9L+B,sBAAsB"}
+{"version":3,"file":"vgeo_build.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_build.js"],"names":[],"mappings":"AA4GA;;;;;;;;;;;;;;;;;;GAkBG;AACH,2EAFa,eAAe,CAyE3B;gCA3L+B,sBAAsB"}

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

@@ -1,16 +1,17 @@
 import { assert } from "../../../../../core/assert.js";
+import { aabb3_array_combine } from "../../../../../core/geom/3d/aabb/aabb3_array_combine.js";
 import { vgeo_attribute_mask } from "../format/attribute/vgeo_attribute_mask.js";
 import { vgeo_write_container } from "../format/vgeo_write_container.js";
 import { VGeoLevelRecord } from "../format/header/VGeoLevelRecord.js";
 import { VGeoWriteOptions } from "../format/VGeoWriteOptions.js";
-import { vgeo_assemble_pages } from "./vgeo_assemble_pages.js";
-import { vgeo_build_levels } from "./vgeo_build_levels.js";
-import { vgeo_build_root_group } from "./vgeo_build_root_group.js";
-import { vgeo_containing_sphere } from "./vgeo_containing_sphere.js";
-import { vgeo_normalize_source } from "./vgeo_normalize_source.js";
+import { vgeo_assemble_pages } from "./page/vgeo_assemble_pages.js";
+import { vgeo_build_levels } from "./level/vgeo_build_levels.js";
+import { vgeo_build_root_group } from "./level/vgeo_build_root_group.js";
+import { vgeo_containing_sphere } from "./sphere/vgeo_containing_sphere.js";
+import { vgeo_normalize_source } from "./mesh/vgeo_normalize_source.js";
 import { VGeoBuildResult } from "./VGeoBuildResult.js";
-import { VGeoLevelSummary } from "./VGeoLevelSummary.js";
-import { VirtualGeometryMesh } from "./VirtualGeometryMesh.js";
+import { VGeoLevelSummary } from "./level/VGeoLevelSummary.js";
+import { VirtualGeometryMesh } from "./mesh/VirtualGeometryMesh.js";
 
 /**
  * The whole builder pipeline, from a triangle soup to `.vgeo` bytes.
@@ -46,10 +47,7 @@ function compute_object_bounds(levels) {
         for (const cluster of level.clusters) {
             spheres.push(cluster.bounds_sphere);
 
-            for (let axis = 0; axis < 3; axis++) {
-                bounds[axis] = Math.min(bounds[axis], cluster.aabb[axis]);
-                bounds[axis + 3] = Math.max(bounds[axis + 3], cluster.aabb[axis + 3]);
-            }
+            aabb3_array_combine(bounds, 0, bounds, 0, cluster.aabb, 0);
         }
     }
 

package/src/shade/renderer/geometry/virtual/format/attribute/vgeo_attributes_read.d.ts

@@ -1,7 +1,13 @@
 /**
  * Read one vertex's value for one channel, falling back to the format's default for a channel this
- * geometry does not carry — which is exactly what the container does with it, since the payload
- * never omits a section and constant-compresses the missing ones to the same values.
+ * geometry does not carry.
+ *
+ * These are the **unencoded** defaults, for a caller that is going to encode what it reads.
+ * `vgeo_encode_cluster_payload` never reaches them: a channel the geometry lacks takes its
+ * `ENCODED_DEFAULTS` path instead, which emits Shade's encoded constant directly. The two are not
+ * everywhere the same value — colour's encoded default carries an alpha byte that
+ * `encode_colors_to_u32` does not write — so which of the two a caller wants is a real question,
+ * and the answer is: this one only when the value is about to be encoded from scratch.
  *
  * @param {Float32Array|number[]} target
  * @param {number} target_offset

package/src/shade/renderer/geometry/virtual/format/attribute/vgeo_attributes_read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_attributes_read.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_attributes_read.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,6CATW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,UACN,CAAC,kBAAgB,IAAI,CAAC,EAAE,aACxB,MAAM,UACN,MAAM,QAmBhB"}
+{"version":3,"file":"vgeo_attributes_read.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_attributes_read.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6CATW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,UACN,CAAC,kBAAgB,IAAI,CAAC,EAAE,aACxB,MAAM,UACN,MAAM,QAmBhB"}

package/src/shade/renderer/geometry/virtual/format/attribute/vgeo_attributes_read.js

@@ -2,8 +2,14 @@ import { VGEO_ATTRIBUTES } from "./VGEO_ATTRIBUTES.js";
 
 /**
  * Read one vertex's value for one channel, falling back to the format's default for a channel this
- * geometry does not carry — which is exactly what the container does with it, since the payload
- * never omits a section and constant-compresses the missing ones to the same values.
+ * geometry does not carry.
+ *
+ * These are the **unencoded** defaults, for a caller that is going to encode what it reads.
+ * `vgeo_encode_cluster_payload` never reaches them: a channel the geometry lacks takes its
+ * `ENCODED_DEFAULTS` path instead, which emits Shade's encoded constant directly. The two are not
+ * everywhere the same value — colour's encoded default carries an alpha byte that
+ * `encode_colors_to_u32` does not write — so which of the two a caller wants is a real question,
+ * and the answer is: this one only when the value is about to be encoded from scratch.
  *
  * @param {Float32Array|number[]} target
  * @param {number} target_offset

package/src/shade/renderer/geometry/virtual/format/page/VGEO_GROUP_OFFSET.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Group record field offsets, relative to the record's own start.
+ *
+ * The record is `VGEO_GROUP_RECORD_SIZE` bytes and `VGEO_FORMAT.md` §6.2 is where the layout is
+ * stated; this is that statement in code, so the writer, the reader and the audit address the same
+ * bytes by the same names rather than each counting them out again.
+ */
+export type VGEO_GROUP_OFFSET = number;
+export namespace VGEO_GROUP_OFFSET {
+    let CLUSTER_FIRST: number;
+    let CLUSTER_COUNT: number;
+    let PARENT_CLUSTER_COUNT: number;
+    let PARENT_FIRST: number;
+}
+//# sourceMappingURL=VGEO_GROUP_OFFSET.d.ts.map

package/src/shade/renderer/geometry/virtual/format/page/VGEO_GROUP_OFFSET.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_GROUP_OFFSET.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/page/VGEO_GROUP_OFFSET.js"],"names":[],"mappings":";;;;;;;gCAOU,MAAM"}

package/src/shade/renderer/geometry/virtual/format/page/VGEO_GROUP_OFFSET.js

@@ -0,0 +1,15 @@
+/**
+ * Group record field offsets, relative to the record's own start.
+ *
+ * The record is `VGEO_GROUP_RECORD_SIZE` bytes and `VGEO_FORMAT.md` §6.2 is where the layout is
+ * stated; this is that statement in code, so the writer, the reader and the audit address the same
+ * bytes by the same names rather than each counting them out again.
+ *
+ * @enum {number}
+ */
+export const VGEO_GROUP_OFFSET = {
+    CLUSTER_FIRST: 0,
+    CLUSTER_COUNT: 2,
+    PARENT_CLUSTER_COUNT: 4,
+    PARENT_FIRST: 6,
+};

package/src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.d.ts

@@ -7,5 +7,33 @@
  * @returns {VGeoEncodedPayload}
  */
 export function vgeo_encode_cluster_payload(positions: Float32Array, indices: Uint8Array, vertex_ids: Uint32Array, layers: (BinaryDataLayer | null)[]): VGeoEncodedPayload;
+/**
+ * Encode one cluster's geometry into a `SHADE_MESHLET_V1` payload: the local index section, then
+ * every attribute section in the frozen order, each either one value per vertex or — when every
+ * vertex agrees, or the source simply lacks the attribute — a single constant-compressed value.
+ *
+ * The encoders themselves are Shade's, unmodified. That is the whole point of the encoding's
+ * "byte-compatible with the data pool" claim: uploading a payload is a copy, so it has to be the
+ * same bits Shade's own encoder would have produced.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * The encoded word a section carries when the source lacks the attribute — Shade's
+ * `ENCODED_ATTRIBUTE_DEFAULT_VALUES`, in this format's own attribute order, so that a `.vgeo`
+ * payload and a `MeshletBatch` payload of the same geometry differ nowhere.
+ *
+ * Colour's default is opaque white with its alpha byte set, while `encode_colors_to_u32` writes only
+ * three channels and leaves alpha zero. That asymmetry is Shade's, and matching it is the point.
+ *
+ * Exported so that `vgeo_encode_cluster_payload.spec.js` can hold it against Shade's own table
+ * rather than against nothing — it is the fourth of the four tables the byte-compatibility claim
+ * rests on, and was for a long time the only one no test compared.
+ *
+ * @readonly
+ * @type {number[][]}
+ */
+export const ENCODED_DEFAULTS: number[][];
 import { VGeoEncodedPayload } from "./VGeoEncodedPayload.js";
 //# sourceMappingURL=vgeo_encode_cluster_payload.d.ts.map

package/src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_encode_cluster_payload.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.js"],"names":[],"mappings":"AAgHA;;;;;;;GAOG;AACH,uDAPW,YAAY,WACZ,UAAU,cACV,WAAW,UACX,CAAC,kBAAgB,IAAI,CAAC,EAAE,GAEtB,kBAAkB,CAiF9B;mCA1LkC,yBAAyB"}
+{"version":3,"file":"vgeo_encode_cluster_payload.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.js"],"names":[],"mappings":"AAoHA;;;;;;;GAOG;AACH,uDAPW,YAAY,WACZ,UAAU,cACV,WAAW,UACX,CAAC,kBAAgB,IAAI,CAAC,EAAE,GAEtB,kBAAkB,CAiF9B;AA5LD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;GAcG;AACH,+BAFU,MAAM,EAAE,EAAE,CAEe;mCA9BA,yBAAyB"}

package/src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.js

@@ -28,16 +28,20 @@ import { VGeoEncodedPayload } from "./VGeoEncodedPayload.js";
 
 /**
  * The encoded word a section carries when the source lacks the attribute — Shade's
- * `ENCODED_ATTRIBUTE_DEFAULT_VALUES`, reproduced so that a `.vgeo` payload and a `MeshletBatch`
- * payload of the same geometry differ nowhere.
+ * `ENCODED_ATTRIBUTE_DEFAULT_VALUES`, in this format's own attribute order, so that a `.vgeo`
+ * payload and a `MeshletBatch` payload of the same geometry differ nowhere.
  *
  * Colour's default is opaque white with its alpha byte set, while `encode_colors_to_u32` writes only
  * three channels and leaves alpha zero. That asymmetry is Shade's, and matching it is the point.
  *
+ * Exported so that `vgeo_encode_cluster_payload.spec.js` can hold it against Shade's own table
+ * rather than against nothing — it is the fourth of the four tables the byte-compatibility claim
+ * rests on, and was for a long time the only one no test compared.
+ *
  * @readonly
  * @type {number[][]}
  */
-const ENCODED_DEFAULTS = [];
+export const ENCODED_DEFAULTS = [];
 
 {
     const normal = new Uint32Array(1);

package/src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_read_page.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.js"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4CAVW,UAAU,cACV,MAAM,GAEJ,QAAQ,CAiFpB;yBAhHwB,eAAe"}
+{"version":3,"file":"vgeo_read_page.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.js"],"names":[],"mappings":"AAsCA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4CAVW,UAAU,cACV,MAAM,GAEJ,QAAQ,CAiFpB;yBAhHwB,eAAe"}

package/src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.js

@@ -10,6 +10,7 @@ import { vgeo_decode_frame_blob } from "../frame/vgeo_decode_frame_blob.js";
 import { VGEO_FRAME_HEADER_SIZE } from "../frame/VGEO_FRAME_HEADER_SIZE.js";
 import { VGEO_FRAME_OFFSET } from "../frame/VGEO_FRAME_OFFSET.js";
 import { vgeo_frame_decode_bound } from "../frame/vgeo_frame_decode_bound.js";
+import { VGEO_GROUP_OFFSET } from "../page/VGEO_GROUP_OFFSET.js";
 import { VGEO_GROUP_RECORD_SIZE } from "../page/VGEO_GROUP_RECORD_SIZE.js";
 import { VGEO_METRIC_OFFSET } from "../page/VGEO_METRIC_OFFSET.js";
 import { VGEO_NODE_OFFSET } from "../page/VGEO_NODE_OFFSET.js";
@@ -298,10 +299,14 @@ function read_group_table(page) {
     for (let i = 0; i < count; i++) {
         const record = VGEO_PAGE_HEADER_SIZE + i * VGEO_GROUP_RECORD_SIZE;
 
-        page.group_cluster_first[i] = data.getUint16(record, LE);
-        page.group_cluster_count[i] = data.getUint16(record + 2, LE);
-        page.group_parent_count[i] = data.getUint16(record + 4, LE);
-        page.group_parent_first[i] = data.getUint16(record + 6, LE);
+        page.group_cluster_first[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.CLUSTER_FIRST, LE);
+        page.group_cluster_count[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.CLUSTER_COUNT, LE);
+        page.group_parent_count[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.PARENT_CLUSTER_COUNT, LE);
+        page.group_parent_first[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.PARENT_FIRST, LE);
     }
 }
 

package/src/shade/renderer/geometry/virtual/format/vgeo_validate_container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AAgtDA;;;;;GAKG;AACH,gDAHW,YAAY,GACV,UAAU,EAAE,CAqFxB;6BAzyD4B,4CAA4C;2BAkD9C,iBAAiB"}
+{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AA6tDA;;;;;GAKG;AACH,gDAHW,YAAY,GACV,UAAU,EAAE,CAqFxB;6BAtzD4B,4CAA4C;2BAmD9C,iBAAiB"}

package/src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js

@@ -20,6 +20,7 @@ import { VGEO_FRAME_ALIGNMENT } from "./frame/VGEO_FRAME_ALIGNMENT.js";
 import { vgeo_frame_decode_bound } from "./frame/vgeo_frame_decode_bound.js";
 import { VGEO_FRAME_HEADER_SIZE } from "./frame/VGEO_FRAME_HEADER_SIZE.js";
 import { VGEO_FRAME_OFFSET } from "./frame/VGEO_FRAME_OFFSET.js";
+import { VGEO_GROUP_OFFSET } from "./page/VGEO_GROUP_OFFSET.js";
 import { VGEO_GROUP_RECORD_SIZE } from "./page/VGEO_GROUP_RECORD_SIZE.js";
 import { VGEO_HASH_ALGO_XXH3 } from "./header/VGEO_HASH_ALGO_XXH3.js";
 import { VGEO_HEADER_OFFSET } from "./header/VGEO_HEADER_OFFSET.js";
@@ -1071,13 +1072,25 @@ function read_groups(page, out) {
     let expected_parent_first = 0;
 
     for (let g = 0; g < page.group_count; g++) {
-        page.seek(VGEO_PAGE_HEADER_SIZE + g * VGEO_GROUP_RECORD_SIZE);
+        const record = VGEO_PAGE_HEADER_SIZE + g * VGEO_GROUP_RECORD_SIZE;
+
+        /**
+         * Each field is sought to by name rather than read in a run, so that this audit and
+         * `vgeo_read_page` address the record through the same table — a validator that agreed
+         * with the reader only by having been written in the same order is a validator that stops
+         * agreeing the first time a field moves.
+         */
+        const read = (field) => {
+            page.seek(record + field);
+
+            return buffer.readUint16();
+        };
 
         const group = {
-            cluster_first: buffer.readUint16(),
-            cluster_count: buffer.readUint16(),
-            parent_cluster_count: buffer.readUint16(),
-            parent_first: buffer.readUint16(),
+            cluster_first: read(VGEO_GROUP_OFFSET.CLUSTER_FIRST),
+            cluster_count: read(VGEO_GROUP_OFFSET.CLUSTER_COUNT),
+            parent_cluster_count: read(VGEO_GROUP_OFFSET.PARENT_CLUSTER_COUNT),
+            parent_first: read(VGEO_GROUP_OFFSET.PARENT_FIRST),
         };
 
         if (group.cluster_count < 1 || group.cluster_count > VGEO_MAX_GROUP_CLUSTER_COUNT) {

package/src/shade/renderer/geometry/virtual/format/vgeo_write_container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_write_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_write_container.js"],"names":[],"mappings":"AA4bA;;;;;;;;GAQG;AACH,4CANW,qBAAqB,8BAGnB,YAAY,CAmNxB;6BAppB4B,4CAA4C"}
+{"version":3,"file":"vgeo_write_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_write_container.js"],"names":[],"mappings":"AAocA;;;;;;;;GAQG;AACH,4CANW,qBAAqB,8BAGnB,YAAY,CAmNxB;6BA5pB4B,4CAA4C"}

package/src/shade/renderer/geometry/virtual/format/vgeo_write_container.js

@@ -17,6 +17,7 @@ import { VGEO_FORMAT_VERSION } from "./header/VGEO_FORMAT_VERSION.js";
 import { VGEO_FRAME_ALIGNMENT } from "./frame/VGEO_FRAME_ALIGNMENT.js";
 import { VGEO_FRAME_HEADER_SIZE } from "./frame/VGEO_FRAME_HEADER_SIZE.js";
 import { VGEO_FRAME_OFFSET } from "./frame/VGEO_FRAME_OFFSET.js";
+import { VGEO_GROUP_OFFSET } from "./page/VGEO_GROUP_OFFSET.js";
 import { VGEO_GROUP_RECORD_SIZE } from "./page/VGEO_GROUP_RECORD_SIZE.js";
 import { VGEO_HASH_ALGO_XXH3 } from "./header/VGEO_HASH_ALGO_XXH3.js";
 import { VGEO_HEADER_OFFSET } from "./header/VGEO_HEADER_OFFSET.js";
@@ -355,11 +356,18 @@ function build_page_blob(page, child_pages, parents) {
             buffer.writeUint16(parent.cluster);
         });
 
-        buffer.position = VGEO_PAGE_HEADER_SIZE + group_index * VGEO_GROUP_RECORD_SIZE;
+        const group_record = VGEO_PAGE_HEADER_SIZE + group_index * VGEO_GROUP_RECORD_SIZE;
 
+        buffer.position = group_record + VGEO_GROUP_OFFSET.CLUSTER_FIRST;
         buffer.writeUint16(cluster_index);
+
+        buffer.position = group_record + VGEO_GROUP_OFFSET.CLUSTER_COUNT;
         buffer.writeUint16(group.clusters.length);
+
+        buffer.position = group_record + VGEO_GROUP_OFFSET.PARENT_CLUSTER_COUNT;
         buffer.writeUint16(group.parent_cluster_count);
+
+        buffer.position = group_record + VGEO_GROUP_OFFSET.PARENT_FIRST;
         buffer.writeUint16(parent_first);
 
         parent_first += group_parents.length;

package/src/shade/renderer/geometry/virtual/runtime/CUT_PLAN_2026_09_14.md

@@ -435,7 +435,7 @@ the view-dependent half, with the same eviction hooks.
    another site already moved.
 
    **There are not two sites — and that is a defect, not a shape to design around.** The
-   phase-one seam call sits *inside* the `ShadeDrawMode × ShadeDrawSide` loop of
+   phase-one seam call sits *inside* the per-opaque-bucket loop of
    `graph_rasterize_partial_opaque`, so a standard view records one cut per **active opaque bucket**
    plus one for phase two. The engine already says so where rev 2 did not read it —
    `GPUVirtualGeometryRuntime`: "once per bucket per HZB pass per view".
@@ -518,7 +518,26 @@ the view-dependent half, with the same eviction hooks.
    checks instead of asking an asset its version — and `GENERATION`. `slot_range` learned the
    section, or the parent rows would never have been uploaded. Still nothing consumes them.
 
-   **A verification surface went away mid-session, and §7.5 needs it.** The `vgeo_runtime`
+   **A verification surface went away mid-session and came back — steps 1–6 are confirmed in a
+   real browser.** Chrome's regression was worked around on master (`b3919f9c3`, `34c836d4d`:
+   the four indirectly dispatched culls, and then particles and SHARC, off immediates and onto a
+   uniform), and with that in place the `vgeo_runtime` playground draws again. Re-measured
+   against it afterwards:
+
+   - the in-page container, now written at `format_version` 4 with parent tables, builds, loads
+     and draws, and the cut shaders — the coarsen path and the tenth binding included — compile
+     under Tint with no console error;
+   - the deepest converted Zorah container, which is **`format_version` 3 and carries no parent
+     tables at all**, loads and draws under the format-4 reader at every camera tried. That is
+     §2.1's back-compatibility claim tested rather than argued, on 27.9M faces;
+   - §7.1's table reproduces exactly: `descent_steps` 32 takes 5 dispatches and 16 takes 6, both
+     with `QUEUE_REMAINING` 0, while 8 takes all 8 and leaves 12–124 items queued. The default
+     of 24 sits inside the clean band.
+
+   What follows is the note written while it was broken, kept because the diagnosis is what
+   makes the gap in the record legible:
+
+   **A verification surface went away mid-session, and §7.5 needed it.** The `vgeo_runtime`
    playground draws nothing in headless Chrome: `begin_frame` runs, the feedback resource is open,
    the adapter is an NVIDIA Lovelace with subgroups, the container builds and its root page installs
    with a selectable group — and `VGEO_CUT_STAT.PAGES` stays 0, so the seed never reaches its first

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

@@ -29,18 +29,21 @@ export class GPUVirtualGeometryRuntime {
      * @param {number} [options.claim_word_capacity] words of the per-invocation claim bitmask,
      *     overriding the derivation below
      * @param {number} [options.queue_capacity] traversal items one wavefront may hold
-     * @param {number} [options.max_iterations] wavefronts before the descent is abandoned
+     * @param {number} [options.max_iterations] wavefronts before the descent is abandoned, to start
+     *     with; the runtime raises it from what the cut reports
+     * @param {number} [options.max_iteration_ceiling] as far as that raising may go
      * @param {number} [options.descent_steps] steps of the descent one traversal dispatch runs
      *     before handing back what it still holds; see the traversal kernel for why it cannot
      *     simply stop when the wave runs dry
      */
-    constructor({ pool, want_capacity, visible_instance_hint, claim_word_capacity, queue_capacity, max_iterations, descent_steps, }: {
+    constructor({ pool, want_capacity, visible_instance_hint, claim_word_capacity, queue_capacity, max_iterations, max_iteration_ceiling, descent_steps, }: {
         pool: GPUVirtualGeometryPool;
         want_capacity?: number;
         visible_instance_hint?: number;
         claim_word_capacity?: number;
         queue_capacity?: number;
         max_iterations?: number;
+        max_iteration_ceiling?: number;
         descent_steps?: number;
     });
     /**
@@ -71,9 +74,56 @@ export class GPUVirtualGeometryRuntime {
      */
     get claim_word_capacity(): number;
     /**
+     * Wavefronts the descent may run, as the runtime currently understands this scene.
+     *
+     * A **high-water mark**, not a setting: it starts where the host put it and is raised by
+     * {@link note_incomplete_descent} from what the cut reports. `graph_vgeo_expand_instances_to_meshlets`
+     * reads it while it is recording passes, so a rise lands on the next frame.
+     *
      * @returns {number}
      */
     get max_iterations(): number;
+    /**
+     * Times the bound has been raised. Zero for the whole life of almost every scene; a small
+     * number, once, for one that needed more than it was given.
+     *
+     * @returns {number}
+     */
+    get iteration_escalations(): number;
+    /**
+     * @returns {number}
+     */
+    get iteration_ceiling(): number;
+    /**
+     * A reading saying the descent stopped with work still queued — raise the bound and keep it
+     * raised.
+     *
+     * **This is the only place the engine can learn it.** How many wavefronts a cut needs is a
+     * function of the frontier's *breadth*, which is a function of the scene, the viewpoint and the
+     * render target together; the kernel cannot know it before it runs and the host cannot know it
+     * at all. So the bound is guessed low, and the one reading that says the guess was wrong —
+     * `VGEO_CUT_STAT.QUEUE_REMAINING`, non-zero exactly when items were abandoned — pays for
+     * correcting it. It is the same shape as the rasterizer's meshlet counts, which cannot be known
+     * before the expansion runs either and are grown from what the frame reported.
+     *
+     * **Doubling, because the reading does not say how much more was needed.** A remainder is a
+     * count of *items*, and what they cost in wavefronts depends on how they spill; there is no
+     * ratio to convert one into the other. So it goes up by a factor until it drains, which is at
+     * most three steps from 8 to the ceiling.
+     *
+     * **Never lowered.** A frame that drained is evidence about that frame, not that the scene got
+     * smaller — and a bound that fell back would re-learn the same lesson every time the camera
+     * turned away and back, at a hole a time. An unused wavefront is an empty indirect dispatch,
+     * which is the cheap side of that trade.
+     *
+     * What it costs when it is wrong is bounded by the readback: the cut is capped at two readings
+     * in flight and skips frames when saturated, so the scene draws with a hole for the few frames
+     * between the first truncated descent and the reading that reports it — and then never again.
+     *
+     * @param {number} remaining items the descent still held when it was abandoned
+     * @returns {boolean} whether the bound moved
+     */
+    note_incomplete_descent(remaining: number): boolean;
     /**
      * Settable, like tau, and for the same reason: it is a quality-of-schedule dial whose right
      * value is a property of the asset's depth and the scene's breadth together rather than of the

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

@@ -1 +1 @@
-{"version":3,"file":"GPUVirtualGeometryRuntime.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js"],"names":[],"mappings":"AAKA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IAwEI;;;;;;;;;;;;;OAaG;IACH;QAZ2C,IAAI,EAApC,sBAAsB;QACL,aAAa,GAA9B,MAAM;QACW,qBAAqB,GAAtC,MAAM;QAEW,mBAAmB,GAApC,MAAM;QAEW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QACW,aAAa,GAA9B,MAAM;OA+DhB;IA/GD;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,OAAO,CAEG;IAwGpB;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,6BAEC;IAWD;;;;;;OAMG;IACH,iCAKC;IArBD;;;;OAIG;IACH,4BAEC;IAgBD;;;OAGG;IACH,uBAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,yBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;OAEG;IACH;;QAvOA;;WAEG;;;4BAIH;;WAEG;MAiOF;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH;QAH+B,KAAK,EAAzB,UAAU;QACR,MAAM,CA+BlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAJ2B,iBAAiB,EAAjC,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACJ,IAAI,CAahB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;;;;;;OAUG;IACH,wGAEC;IAGD;;;;;OAKG;IACH,aAFa,IAAI,CAKhB;;CACJ;qCAtYY,OAAO,6BAA6B,EAAE,sBAAsB;yBAC5D,OAAO,iEAAiE,EAAE,UAAU"}
+{"version":3,"file":"GPUVirtualGeometryRuntime.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js"],"names":[],"mappings":"AAKA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IAkFI;;;;;;;;;;;;;;;OAeG;IACH;QAd2C,IAAI,EAApC,sBAAsB;QACL,aAAa,GAA9B,MAAM;QACW,qBAAqB,GAAtC,MAAM;QAEW,mBAAmB,GAApC,MAAM;QAEW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QAEW,qBAAqB,GAAtC,MAAM;QACW,aAAa,GAA9B,MAAM;OAkFhB;IApID;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,OAAO,CAEG;IA6HpB;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;OAQG;IACH,6BAEC;IAED;;;;;OAKG;IACH,oCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,mCAHW,MAAM,GACJ,OAAO,CAanB;IAWD;;;;;;OAMG;IACH,iCAKC;IArBD;;;;OAIG;IACH,4BAEC;IAgBD;;;OAGG;IACH,uBAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,yBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;OAEG;IACH;;QAvUA;;WAEG;;;4BAIH;;WAEG;MAiUF;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH;QAH+B,KAAK,EAAzB,UAAU;QACR,MAAM,CA+BlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAJ2B,iBAAiB,EAAjC,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACJ,IAAI,CAahB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;;;;;;OAUG;IACH,wGAEC;IAGD;;;;;OAKG;IACH,aAFa,IAAI,CAKhB;;CACJ;qCAteY,OAAO,6BAA6B,EAAE,sBAAsB;yBAC5D,OAAO,iEAAiE,EAAE,UAAU"}

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

@@ -54,6 +54,16 @@ export class GPUVirtualGeometryRuntime {
      */
     #max_iterations;
 
+    /**
+     * @type {number}
+     */
+    #iteration_ceiling;
+
+    /**
+     * @type {number}
+     */
+    #iteration_escalations = 0;
+
     /**
      * @type {number}
      */
@@ -106,7 +116,9 @@ export class GPUVirtualGeometryRuntime {
      * @param {number} [options.claim_word_capacity] words of the per-invocation claim bitmask,
      *     overriding the derivation below
      * @param {number} [options.queue_capacity] traversal items one wavefront may hold
-     * @param {number} [options.max_iterations] wavefronts before the descent is abandoned
+     * @param {number} [options.max_iterations] wavefronts before the descent is abandoned, to start
+     *     with; the runtime raises it from what the cut reports
+     * @param {number} [options.max_iteration_ceiling] as far as that raising may go
      * @param {number} [options.descent_steps] steps of the descent one traversal dispatch runs
      *     before handing back what it still holds; see the traversal kernel for why it cannot
      *     simply stop when the wave runs dry
@@ -140,7 +152,25 @@ export class GPUVirtualGeometryRuntime {
                      with work outstanding, which is the one degradation that costs a hole.
                      */
                     queue_capacity = 1 << 16,
+                    /*
+                     Where the wavefront bound *starts*. It is raised by the runtime itself when a
+                     reading says the descent could not finish — see {@link note_incomplete_descent}
+                     — so this is the cost a scene pays until it has been told otherwise rather than
+                     a limit anyone has to get right in advance.
+
+                     Eight is what almost every cut needs: one container at a modest viewport drains
+                     in six. A converted scene at 3441×1440 does not, and nothing on the host can
+                     know that before the kernel has run.
+                    */
                     max_iterations = 8,
+                    /*
+                     And where it stops. A frontier that genuinely cannot be drained inside any
+                     budget would otherwise climb until the frame graph is nothing but empty
+                     dispatches; a hole is the better failure, because it is visible and
+                     `QUEUE_REMAINING` goes on reporting it. Measured peak need on the scene that
+                     found this was 12 to 13.
+                    */
+                    max_iteration_ceiling = 64,
                     /*
                      Steps of the in-kernel descent one dispatch runs, and the knob that is *not*
                      the safety bound — `max_iterations` is, and lowering this spends it. A wave
@@ -167,6 +197,7 @@ export class GPUVirtualGeometryRuntime {
         this.#claim_word_capacity = claim_word_capacity;
         this.#queue_capacity = queue_capacity;
         this.#max_iterations = max_iterations;
+        this.#iteration_ceiling = Math.max(max_iterations, max_iteration_ceiling);
         this.#descent_steps = descent_steps;
 
 
@@ -203,12 +234,77 @@ export class GPUVirtualGeometryRuntime {
     }
 
     /**
+     * Wavefronts the descent may run, as the runtime currently understands this scene.
+     *
+     * A **high-water mark**, not a setting: it starts where the host put it and is raised by
+     * {@link note_incomplete_descent} from what the cut reports. `graph_vgeo_expand_instances_to_meshlets`
+     * reads it while it is recording passes, so a rise lands on the next frame.
+     *
      * @returns {number}
      */
     get max_iterations() {
         return this.#max_iterations;
     }
 
+    /**
+     * Times the bound has been raised. Zero for the whole life of almost every scene; a small
+     * number, once, for one that needed more than it was given.
+     *
+     * @returns {number}
+     */
+    get iteration_escalations() {
+        return this.#iteration_escalations;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get iteration_ceiling() {
+        return this.#iteration_ceiling;
+    }
+
+    /**
+     * A reading saying the descent stopped with work still queued — raise the bound and keep it
+     * raised.
+     *
+     * **This is the only place the engine can learn it.** How many wavefronts a cut needs is a
+     * function of the frontier's *breadth*, which is a function of the scene, the viewpoint and the
+     * render target together; the kernel cannot know it before it runs and the host cannot know it
+     * at all. So the bound is guessed low, and the one reading that says the guess was wrong —
+     * `VGEO_CUT_STAT.QUEUE_REMAINING`, non-zero exactly when items were abandoned — pays for
+     * correcting it. It is the same shape as the rasterizer's meshlet counts, which cannot be known
+     * before the expansion runs either and are grown from what the frame reported.
+     *
+     * **Doubling, because the reading does not say how much more was needed.** A remainder is a
+     * count of *items*, and what they cost in wavefronts depends on how they spill; there is no
+     * ratio to convert one into the other. So it goes up by a factor until it drains, which is at
+     * most three steps from 8 to the ceiling.
+     *
+     * **Never lowered.** A frame that drained is evidence about that frame, not that the scene got
+     * smaller — and a bound that fell back would re-learn the same lesson every time the camera
+     * turned away and back, at a hole a time. An unused wavefront is an empty indirect dispatch,
+     * which is the cheap side of that trade.
+     *
+     * What it costs when it is wrong is bounded by the readback: the cut is capped at two readings
+     * in flight and skips frames when saturated, so the scene draws with a hole for the few frames
+     * between the first truncated descent and the reading that reports it — and then never again.
+     *
+     * @param {number} remaining items the descent still held when it was abandoned
+     * @returns {boolean} whether the bound moved
+     */
+    note_incomplete_descent(remaining) {
+        assert.isNonNegativeInteger(remaining, 'remaining');
+
+        if (remaining === 0 || this.#max_iterations >= this.#iteration_ceiling) {
+            return false;
+        }
+
+        this.#max_iterations = Math.min(this.#max_iterations * 2, this.#iteration_ceiling);
+        this.#iteration_escalations++;
+
+        return true;
+    }
+
     /**
      * Steps of the descent one traversal dispatch runs.
      *