@woosh/meep-engine 3.27.0 → 3.29.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/attribute/vgeo_layers_copy_corner.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copy one corner's every channel between two meshes declared from the same template.
+ *
+ * One run of bytes, not one call per channel: the channels of a corner are one interleaved record,
+ * and {@link vgeo_layers_like} is what guarantees the two records line up.
+ *
+ * @param {BinaryTopology} target
+ * @param {BinaryTopology} source
+ * @param {number} source_loop
+ * @param {number} target_loop
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_layers_copy_corner(target: BinaryTopology, source: BinaryTopology, source_loop: number, target_loop: number): void;
+//# sourceMappingURL=vgeo_layers_copy_corner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_layers_copy_corner.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_layers_copy_corner.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,qGANW,MAAM,eACN,MAAM,QAoBhB"}

package/src/shade/renderer/geometry/virtual/format/attribute/{vgeo_layers_copy_vertex.js → vgeo_layers_copy_corner.js}

@@ -1,23 +1,23 @@
 import { assert } from "../../../../../../core/assert.js";
 
 /**
- * Copy one vertex's every channel between two meshes declared from the same template.
+ * Copy one corner's every channel between two meshes declared from the same template.
  *
- * One run of bytes, not one call per channel: the channels of a vertex are one interleaved record,
+ * One run of bytes, not one call per channel: the channels of a corner are one interleaved record,
  * and {@link vgeo_layers_like} is what guarantees the two records line up.
  *
  * @param {BinaryTopology} target
  * @param {BinaryTopology} source
- * @param {number} source_vertex
- * @param {number} target_vertex
+ * @param {number} source_loop
+ * @param {number} target_loop
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_layers_copy_vertex(target, source, source_vertex, target_vertex) {
-    const target_data = target.vertex_data;
+export function vgeo_layers_copy_corner(target, source, source_loop, target_loop) {
+    const target_data = target.loop_data;
 
-    const source_data = source.vertex_data;
+    const source_data = source.loop_data;
 
     if (target_data === null) {
         // a geometry with position and nothing else — there is no record to move
@@ -28,5 +28,5 @@ export function vgeo_layers_copy_vertex(target, source, source_vertex, target_ve
 
     assert.notNull(source_data, 'target was declared with channels the source does not carry');
 
-    target_data.copy_record(target_vertex, source_data, source_vertex);
+    target_data.copy_record(target_loop, source_data, source_loop);
 }

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

@@ -1,14 +1,25 @@
 /**
- * Declare vertex data layers on a topology for the channels `carried` marks.
+ * Declare loop data layers on a topology for the channels `carried` marks.
  *
- * The vertex attributes a `.vgeo` carries live as vertex data layers on the `BinaryTopology` the
- * builder simplifies, rather than beside it, because that is the only place a per-vertex value can
- * survive what the builder does to a mesh: an edge collapse frees vertices, and the topology is
- * what knows when. A layer is addressed by vertex id and sized by the vertex pool, so a channel is
- * never a slot short of the mesh it describes and never has to be resized by hand.
+ * The attributes a `.vgeo` carries live on the `BinaryTopology` the builder simplifies rather than
+ * beside it, because that is the only place a value can survive what the builder does to a mesh: a
+ * collapse frees vertices and kills faces, and the topology is what knows when. A layer is sized by
+ * its pool, so a channel is never a slot short of the mesh it describes and never has to be resized
+ * by hand.
+ *
+ * **On loops — corners — and not on vertices.** A vertex has one position and the surface has one
+ * shape there, but it does not have one *appearance*: a hard edge and a texture seam are both a
+ * single geometric vertex that shades two ways, and a per-vertex record cannot hold that. Welding
+ * the position is what the clusterer needs and splitting the appearance is what the artist authored,
+ * and those are different questions (`WEDGE_PLAN_2026_09_18.md` §2). `bt_loop_uv` reached the same
+ * place for the same reason, and `bt_mesh_compact` already compacts loop data with everything else.
+ *
+ * What a *loop* is rather than a vertex costs is duplication — three records per triangle against
+ * roughly one per two — and buys the only representation a seam has.
  *
  * Position is not among them. It lives in the topology's own vertex record, where the quadric solve
- * moves it; keeping a second copy here would only be a copy to keep in step.
+ * moves it — and it is the one value that genuinely is the vertex's, which is the whole distinction
+ * this storage is drawn along.
  *
  * The returned *channel set* is an array with one slot per {@link VGEO_ATTRIBUTES} entry, holding
  * that channel's layer or null where the geometry does not carry it — the format has a fixed,

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_layers_declare.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_layers_declare.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,uEANW,OAAO,EAAE,GACP,CAAC,kBAAgB,IAAI,CAAC,EAAE,CAmBpC"}
+{"version":3,"file":"vgeo_layers_declare.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_layers_declare.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,uEANW,OAAO,EAAE,GACP,CAAC,kBAAgB,IAAI,CAAC,EAAE,CAmBpC"}

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

@@ -3,16 +3,27 @@ import { VGEO_ATTRIBUTE } from "./VGEO_ATTRIBUTE.js";
 import { VGEO_ATTRIBUTES } from "./VGEO_ATTRIBUTES.js";
 
 /**
- * Declare vertex data layers on a topology for the channels `carried` marks.
+ * Declare loop data layers on a topology for the channels `carried` marks.
  *
- * The vertex attributes a `.vgeo` carries live as vertex data layers on the `BinaryTopology` the
- * builder simplifies, rather than beside it, because that is the only place a per-vertex value can
- * survive what the builder does to a mesh: an edge collapse frees vertices, and the topology is
- * what knows when. A layer is addressed by vertex id and sized by the vertex pool, so a channel is
- * never a slot short of the mesh it describes and never has to be resized by hand.
+ * The attributes a `.vgeo` carries live on the `BinaryTopology` the builder simplifies rather than
+ * beside it, because that is the only place a value can survive what the builder does to a mesh: a
+ * collapse frees vertices and kills faces, and the topology is what knows when. A layer is sized by
+ * its pool, so a channel is never a slot short of the mesh it describes and never has to be resized
+ * by hand.
+ *
+ * **On loops — corners — and not on vertices.** A vertex has one position and the surface has one
+ * shape there, but it does not have one *appearance*: a hard edge and a texture seam are both a
+ * single geometric vertex that shades two ways, and a per-vertex record cannot hold that. Welding
+ * the position is what the clusterer needs and splitting the appearance is what the artist authored,
+ * and those are different questions (`WEDGE_PLAN_2026_09_18.md` §2). `bt_loop_uv` reached the same
+ * place for the same reason, and `bt_mesh_compact` already compacts loop data with everything else.
+ *
+ * What a *loop* is rather than a vertex costs is duplication — three records per triangle against
+ * roughly one per two — and buys the only representation a seam has.
  *
  * Position is not among them. It lives in the topology's own vertex record, where the quadric solve
- * moves it; keeping a second copy here would only be a copy to keep in step.
+ * moves it — and it is the one value that genuinely is the vertex's, which is the whole distinction
+ * this storage is drawn along.
  *
  * The returned *channel set* is an array with one slot per {@link VGEO_ATTRIBUTES} entry, holding
  * that channel's layer or null where the geometry does not carry it — the format has a fixed,
@@ -37,7 +48,7 @@ export function vgeo_layers_declare(topology, carried) {
             continue;
         }
 
-        result[attribute] = topology.vertex_data_add_layer(
+        result[attribute] = topology.loop_data_add_layer(
             BinaryDataType.Float32, VGEO_ATTRIBUTES[attribute].components
         );
     }

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

@@ -1,9 +1,9 @@
 /**
  * Declare the same channels `template` holds on another topology.
  *
- * Used wherever the builder rebuilds a vertex set — extracting a group, stitching a level — and
- * needs somewhere to copy the old values into. Because the declarations are the same, in the same
- * order, the two blocks share a record layout and a vertex can be moved across as one run of bytes.
+ * Used wherever the builder rebuilds a mesh — extracting a group, stitching a level — and needs
+ * somewhere to copy the old values into. Because the declarations are the same, in the same order,
+ * the two blocks share a record layout and a corner can be moved across as one run of bytes.
  *
  * @param {BinaryTopology} topology receives the layers
  * @param {(BinaryDataLayer|null)[]} template channel set to mirror

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

@@ -3,9 +3,9 @@ import { vgeo_layers_declare } from "./vgeo_layers_declare.js";
 /**
  * Declare the same channels `template` holds on another topology.
  *
- * Used wherever the builder rebuilds a vertex set — extracting a group, stitching a level — and
- * needs somewhere to copy the old values into. Because the declarations are the same, in the same
- * order, the two blocks share a record layout and a vertex can be moved across as one run of bytes.
+ * Used wherever the builder rebuilds a mesh — extracting a group, stitching a level — and needs
+ * somewhere to copy the old values into. Because the declarations are the same, in the same order,
+ * the two blocks share a record layout and a corner can be moved across as one run of bytes.
  *
  * @param {BinaryTopology} topology receives the layers
  * @param {(BinaryDataLayer|null)[]} template channel set to mirror

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

@@ -0,0 +1,27 @@
+/**
+ * Read a mesh's wedges off the values its corners already carry.
+ *
+ * **The values are the wedge.** A wedge is a set of corners at one vertex that shade the same, so
+ * the partition is not an extra fact to be stored and kept in step — it is a fact about the records,
+ * recoverable from them, and this is the one place in the builder that recovers it. Everywhere else
+ * wedges travel by provenance, because everywhere else the answer is already known and re-deriving
+ * it would be re-deciding it.
+ *
+ * Here is where the source gets to decide. A hard edge and a texture-chart boundary reach the
+ * builder as exactly this — corners of one vertex holding different records — and the weld in
+ * {@link vgeo_normalize_source} deliberately no longer flattens them.
+ *
+ * Grouped on **byte equality of the whole record**, which makes the partition an equivalence
+ * relation and so independent of the order corners are visited in. A tolerance would not be: it is
+ * not transitive, and two runs over one mesh could disagree about the same vertex. Tolerance belongs
+ * where a *decision* is made — the collapse — and not where a fact is read.
+ *
+ * @param {BinaryTopology} topology
+ * @returns {BtWedgeSet}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_mesh_wedges(topology: BinaryTopology): BtWedgeSet;
+import { BtWedgeSet } from "../../../../../../core/geom/3d/topology/struct/binary/BtWedgeSet.js";
+//# sourceMappingURL=vgeo_mesh_wedges.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_mesh_wedges.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_mesh_wedges.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,4DALa,UAAU,CAuEtB;2BA/F0B,qEAAqE"}

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

@@ -0,0 +1,97 @@
+import { NULL_POINTER } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { BtWedgeSet } from "../../../../../../core/geom/3d/topology/struct/binary/BtWedgeSet.js";
+import {
+    bt_wedges_per_vertex
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_wedges_per_vertex.js";
+
+/**
+ * Read a mesh's wedges off the values its corners already carry.
+ *
+ * **The values are the wedge.** A wedge is a set of corners at one vertex that shade the same, so
+ * the partition is not an extra fact to be stored and kept in step — it is a fact about the records,
+ * recoverable from them, and this is the one place in the builder that recovers it. Everywhere else
+ * wedges travel by provenance, because everywhere else the answer is already known and re-deriving
+ * it would be re-deciding it.
+ *
+ * Here is where the source gets to decide. A hard edge and a texture-chart boundary reach the
+ * builder as exactly this — corners of one vertex holding different records — and the weld in
+ * {@link vgeo_normalize_source} deliberately no longer flattens them.
+ *
+ * Grouped on **byte equality of the whole record**, which makes the partition an equivalence
+ * relation and so independent of the order corners are visited in. A tolerance would not be: it is
+ * not transitive, and two runs over one mesh could disagree about the same vertex. Tolerance belongs
+ * where a *decision* is made — the collapse — and not where a fact is read.
+ *
+ * @param {BinaryTopology} topology
+ * @returns {BtWedgeSet}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_mesh_wedges(topology) {
+    const loop_data = topology.loop_data;
+
+    if (loop_data === null) {
+        // Position and nothing else: there is no record to disagree about, so every vertex shades
+        // one way and the degenerate set is the whole answer.
+        return bt_wedges_per_vertex(topology);
+    }
+
+    const loop_pool = topology.loops;
+    const vertex_pool = topology.vertices;
+
+    const of_loop = new Uint32Array(loop_pool.size).fill(NULL_POINTER);
+    const first_of_vertex = new Uint32Array(vertex_pool.size).fill(NULL_POINTER);
+
+    /**
+     * One representative corner per wedge, which is what a candidate is compared against.
+     * @type {number[]}
+     */
+    const corner_of_wedge = [];
+
+    const parent = [];
+    const next_of_wedge = [];
+
+    for (let loop = 0; loop < loop_pool.size; loop++) {
+        if (!loop_pool.is_allocated(loop)) {
+            continue;
+        }
+
+        const vertex = topology.loop_read_vertex(loop);
+
+        let wedge = first_of_vertex[vertex];
+
+        while (wedge !== NULL_POINTER) {
+            if (loop_data.record_equal(corner_of_wedge[wedge], loop)) {
+                break;
+            }
+
+            wedge = next_of_wedge[wedge];
+        }
+
+        if (wedge === NULL_POINTER) {
+            // A scan of the vertex's wedges rather than a hash of the record: on smooth geometry
+            // that list has one entry, on a crease two or three, and a key built per corner would
+            // cost more than the comparison it saves.
+            wedge = parent.length;
+
+            parent.push(wedge);
+            corner_of_wedge.push(loop);
+
+            next_of_wedge.push(first_of_vertex[vertex]);
+            first_of_vertex[vertex] = wedge;
+        }
+
+        of_loop[loop] = wedge;
+    }
+
+    const wedges = new BtWedgeSet();
+
+    wedges.count = parent.length;
+    wedges.parent = Uint32Array.from(parent);
+    wedges.next_of_wedge = Uint32Array.from(next_of_wedge);
+    wedges.first_of_vertex = first_of_vertex;
+    wedges.of_loop = of_loop;
+
+    return wedges;
+}

package/src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET.d.ts

@@ -1,5 +1,10 @@
 /**
- * Cluster record field offsets, relative to the record's own start.
+ * Cluster record field offsets, relative to the record's own start — `format_version` 5.
+ *
+ * {@link VGEO_CLUSTER_OFFSET_V4 } is what this was, and every field from offset 40 on has moved:
+ * `subtree_aabb` took the twenty-four bytes that `bounds_sphere` and `cone_reserved` were spending
+ * on a sphere nothing at runtime read and a column that was always zero. The record is still 112
+ * bytes.
  */
 export type VGEO_CLUSTER_OFFSET = number;
 export namespace VGEO_CLUSTER_OFFSET {
@@ -7,11 +12,10 @@ export namespace VGEO_CLUSTER_OFFSET {
     let SELF_ERROR: number;
     let PARENT_ERROR: number;
     let PARENT_SPHERE: number;
-    let BOUNDS_SPHERE: number;
+    let SUBTREE_AABB: number;
     let AABB: number;
     let CHILD_REF: number;
     let CHILD_GROUP: number;
-    let CONE_RESERVED: number;
     let ENCODING_FLAGS: number;
     let PAYLOAD_OFFSET: number;
     let PAYLOAD_SIZE: number;

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

@@ -1 +1 @@
-{"version":3,"file":"VGEO_CLUSTER_OFFSET.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET.js"],"names":[],"mappings":";;;kCAEU,MAAM"}
+{"version":3,"file":"VGEO_CLUSTER_OFFSET.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET.js"],"names":[],"mappings":";;;;;;;;kCAQU,MAAM"}

package/src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET.js

@@ -1,5 +1,11 @@
 /**
- * Cluster record field offsets, relative to the record's own start.
+ * Cluster record field offsets, relative to the record's own start — `format_version` 5.
+ *
+ * {@link VGEO_CLUSTER_OFFSET_V4} is what this was, and every field from offset 40 on has moved:
+ * `subtree_aabb` took the twenty-four bytes that `bounds_sphere` and `cone_reserved` were spending
+ * on a sphere nothing at runtime read and a column that was always zero. The record is still 112
+ * bytes.
+ *
  * @enum {number}
  */
 export const VGEO_CLUSTER_OFFSET = {
@@ -7,14 +13,18 @@ export const VGEO_CLUSTER_OFFSET = {
     SELF_ERROR: 16,
     PARENT_ERROR: 20,
     PARENT_SPHERE: 24,
-    BOUNDS_SPHERE: 40,
-    AABB: 56,
-    CHILD_REF: 80,
-    CHILD_GROUP: 82,
-    CONE_RESERVED: 84,
-    ENCODING_FLAGS: 88,
-    PAYLOAD_OFFSET: 92,
-    PAYLOAD_SIZE: 96,
-    VERTEX_COUNT: 100,
-    TRIANGLE_COUNT: 101,
+    /**
+     * Object-space AABB of this cluster's own vertices **and of every cluster reachable below it**
+     * through child groups — what the cut's per-cluster frustum test needs, because culling a
+     * cluster removes its whole subtree from the descent (CULL_PLAN_2026_09_16 §3.1).
+     */
+    SUBTREE_AABB: 40,
+    AABB: 64,
+    CHILD_REF: 88,
+    CHILD_GROUP: 90,
+    ENCODING_FLAGS: 92,
+    PAYLOAD_OFFSET: 96,
+    PAYLOAD_SIZE: 100,
+    VERTEX_COUNT: 104,
+    TRIANGLE_COUNT: 105,
 };

package/src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET_V4.d.ts

@@ -0,0 +1,21 @@
+/**
+ * *
+ */
+export type VGEO_CLUSTER_OFFSET_V4 = number;
+export namespace VGEO_CLUSTER_OFFSET_V4 {
+    let SELF_SPHERE: number;
+    let SELF_ERROR: number;
+    let PARENT_ERROR: number;
+    let PARENT_SPHERE: number;
+    let BOUNDS_SPHERE: number;
+    let AABB: number;
+    let CHILD_REF: number;
+    let CHILD_GROUP: number;
+    let CONE_RESERVED: number;
+    let ENCODING_FLAGS: number;
+    let PAYLOAD_OFFSET: number;
+    let PAYLOAD_SIZE: number;
+    let VERTEX_COUNT: number;
+    let TRIANGLE_COUNT: number;
+}
+//# sourceMappingURL=VGEO_CLUSTER_OFFSET_V4.d.ts.map

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

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

package/src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET_V4.js

@@ -0,0 +1,41 @@
+/**
+ * Cluster record field offsets as `format_version` 4 and earlier laid them out, kept so that the
+ * reader can still take the containers that exist.
+ *
+ * Version 5 dropped `bounds_sphere` and `cone_reserved` and put {@link
+ * VGEO_CLUSTER_OFFSET.SUBTREE_AABB} in their place, which moved every field from offset 40 on. A
+ * version-4 record read by the version-5 sequence hands back a `child_ref` taken out of the middle
+ * of a bounding box, so the decoder branches on the container's version rather than trusting one
+ * layout — and this is the other branch. Nothing but {@link vgeo_read_page} should need it.
+ *
+ * The writer and the validator have no such branch: one writes the current version and the other
+ * refuses anything else.
+ *
+ * @enum {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_CLUSTER_OFFSET_V4 = {
+    SELF_SPHERE: 0,
+    SELF_ERROR: 16,
+    PARENT_ERROR: 20,
+    PARENT_SPHERE: 24,
+    /**
+     * The cluster's own miniball. Version 5 has no such field: nothing at runtime read it, and the
+     * builder keeps its own copy.
+     */
+    BOUNDS_SPHERE: 40,
+    AABB: 56,
+    CHILD_REF: 80,
+    CHILD_GROUP: 82,
+    /**
+     * Always zero, for a cone cull that was declined outright. Version 5 reclaimed it.
+     */
+    CONE_RESERVED: 84,
+    ENCODING_FLAGS: 88,
+    PAYLOAD_OFFSET: 92,
+    PAYLOAD_SIZE: 96,
+    VERTEX_COUNT: 100,
+    TRIANGLE_COUNT: 101,
+};

package/src/shade/renderer/geometry/virtual/format/dag/VirtualGeometryCluster.d.ts

@@ -34,7 +34,13 @@ export class VirtualGeometryCluster {
      */
     parent_error: number;
     /**
-     * This cluster's own tight bounding sphere — culling only, never the cut test.
+     * This cluster's own tight bounding sphere.
+     *
+     * **Build-time only — the container does not carry it.** Nothing at runtime ever read it, and
+     * `format_version` 5 spent its bytes on {@link subtree_aabb}. It stays here because the build
+     * does use it: the header's `object_sphere`, the page assembler's group centroids, the cluster
+     * adjacency graph and a leaf's own `self_sphere` are all built from it.
+     *
      * @type {Float32Array}
      */
     bounds_sphere: Float32Array;
@@ -43,6 +49,18 @@ export class VirtualGeometryCluster {
      * @type {Float32Array}
      */
     aabb: Float32Array;
+    /**
+     * {@link aabb} unioned with the `subtree_aabb` of every cluster of this one's child group, so it
+     * contains every vertex anywhere below this cluster in the DAG.
+     *
+     * It is what the cut's per-cluster frustum test reads, and the reason it has to bound the whole
+     * subtree rather than this cluster is that culling a cluster removes everything under it from the
+     * descent — the child group is only ever reached *through* it (CULL_PLAN_2026_09_16 §1, §3.1).
+     * A leaf's equals its {@link aabb}.
+     *
+     * @type {Float32Array}
+     */
+    subtree_aabb: Float32Array;
     /**
      * The group this cluster refines into, or `undefined` when it is a leaf and refines into
      * nothing.

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

@@ -1 +1 @@
-{"version":3,"file":"VirtualGeometryCluster.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/dag/VirtualGeometryCluster.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,aAFU,YAAY,CAEY;IAElC;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,cAFU,MAAM,CAEwB;IAExC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,MAFU,YAAY,CAEK;IAE3B;;;;OAIG;IACH,aAFU,uBAAqB,SAAS,CAEhB;IAExB;;;;;;;;;;OAUG;IACH,eAFU,MAAM,CAEE;IAElB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,SAFU,UAAU,CAEQ;CAC/B"}
+{"version":3,"file":"VirtualGeometryCluster.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/dag/VirtualGeometryCluster.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,aAFU,YAAY,CAEY;IAElC;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,cAFU,MAAM,CAEwB;IAExC;;;;;;;;;OASG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,MAFU,YAAY,CAEK;IAE3B;;;;;;;;;;OAUG;IACH,cAFU,YAAY,CAEa;IAEnC;;;;OAIG;IACH,aAFU,uBAAqB,SAAS,CAEhB;IAExB;;;;;;;;;;OAUG;IACH,eAFU,MAAM,CAEE;IAElB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,SAFU,UAAU,CAEQ;CAC/B"}

package/src/shade/renderer/geometry/virtual/format/dag/VirtualGeometryCluster.js

@@ -39,7 +39,13 @@ export class VirtualGeometryCluster {
     parent_error = Number.POSITIVE_INFINITY;
 
     /**
-     * This cluster's own tight bounding sphere — culling only, never the cut test.
+     * This cluster's own tight bounding sphere.
+     *
+     * **Build-time only — the container does not carry it.** Nothing at runtime ever read it, and
+     * `format_version` 5 spent its bytes on {@link subtree_aabb}. It stays here because the build
+     * does use it: the header's `object_sphere`, the page assembler's group centroids, the cluster
+     * adjacency graph and a leaf's own `self_sphere` are all built from it.
+     *
      * @type {Float32Array}
      */
     bounds_sphere = new Float32Array(4);
@@ -50,6 +56,19 @@ export class VirtualGeometryCluster {
      */
     aabb = new Float32Array(6);
 
+    /**
+     * {@link aabb} unioned with the `subtree_aabb` of every cluster of this one's child group, so it
+     * contains every vertex anywhere below this cluster in the DAG.
+     *
+     * It is what the cut's per-cluster frustum test reads, and the reason it has to bound the whole
+     * subtree rather than this cluster is that culling a cluster removes everything under it from the
+     * descent — the child group is only ever reached *through* it (CULL_PLAN_2026_09_16 §1, §3.1).
+     * A leaf's equals its {@link aabb}.
+     *
+     * @type {Float32Array}
+     */
+    subtree_aabb = new Float32Array(6);
+
     /**
      * The group this cluster refines into, or `undefined` when it is a leaf and refines into
      * nothing.

package/src/shade/renderer/geometry/virtual/format/frame/VGEO_CODEC_DEFLATE.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `codec` value for a blob stored as one raw DEFLATE stream (RFC 1951), no zlib or gzip wrapper.
+ *
+ * Bare for the same reason {@link VGEO_CODEC_LZ4} is a bare block: both wrappers carry a magic, a
+ * length and a checksum that the frame header already carries better — `decoded_size` is what the
+ * stream is decoded against and the identity-seeded `checksum` is what proves the stored bytes
+ * arrived. A zlib header would be two bytes of restating and a gzip one eighteen.
+ *
+ * This is the hosted codec: `CompressionStream`/`DecompressionStream` are the platform's own zlib,
+ * so it costs no bytes of library and runs off the JS thread — and it is *asynchronous*, which is
+ * why everything from {@link vgeo_decode_frame_blob} up to {@link vgeo_build} is.
+ *
+ * What it is worth, measured over the 44 pages of a 240x120 torus: **1.369x** against LZ4's 1.295x
+ * on the same pages, for a decode of every page that cost 16.9 ms against LZ4's 3.8 ms — 126 MB/s
+ * of decoded output against 562.
+ *
+ * **This is what the builder and the converter write by default.** An asset is built once and
+ * fetched forever, so the denser side of that trade is the one worth taking without being asked;
+ * {@link VGEO_CODEC_LZ4} is a deliberate choice for a container whose pages arrive while someone is
+ * looking at it, where the decode is a page's arrival cost rather than a build's.
+ *
+ * @type {number}
+ */
+export const VGEO_CODEC_DEFLATE: number;
+//# sourceMappingURL=VGEO_CODEC_DEFLATE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_CODEC_DEFLATE.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/VGEO_CODEC_DEFLATE.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,iCAFU,MAAM,CAEoB"}

package/src/shade/renderer/geometry/virtual/format/frame/VGEO_CODEC_DEFLATE.js

@@ -0,0 +1,24 @@
+/**
+ * `codec` value for a blob stored as one raw DEFLATE stream (RFC 1951), no zlib or gzip wrapper.
+ *
+ * Bare for the same reason {@link VGEO_CODEC_LZ4} is a bare block: both wrappers carry a magic, a
+ * length and a checksum that the frame header already carries better — `decoded_size` is what the
+ * stream is decoded against and the identity-seeded `checksum` is what proves the stored bytes
+ * arrived. A zlib header would be two bytes of restating and a gzip one eighteen.
+ *
+ * This is the hosted codec: `CompressionStream`/`DecompressionStream` are the platform's own zlib,
+ * so it costs no bytes of library and runs off the JS thread — and it is *asynchronous*, which is
+ * why everything from {@link vgeo_decode_frame_blob} up to {@link vgeo_build} is.
+ *
+ * What it is worth, measured over the 44 pages of a 240x120 torus: **1.369x** against LZ4's 1.295x
+ * on the same pages, for a decode of every page that cost 16.9 ms against LZ4's 3.8 ms — 126 MB/s
+ * of decoded output against 562.
+ *
+ * **This is what the builder and the converter write by default.** An asset is built once and
+ * fetched forever, so the denser side of that trade is the one worth taking without being asked;
+ * {@link VGEO_CODEC_LZ4} is a deliberate choice for a container whose pages arrive while someone is
+ * looking at it, where the decode is a page's arrival cost rather than a build's.
+ *
+ * @type {number}
+ */
+export const VGEO_CODEC_DEFLATE = 2;

package/src/shade/renderer/geometry/virtual/format/frame/VGEO_CODEC_LZ4.d.ts

@@ -6,6 +6,11 @@
  * its identity-seeded `checksum` covers the stored bytes. So the blob is the bare block, and the
  * frame header is what tells a decoder how much to expect out of it.
  *
+ * Not the builder's default — {@link VGEO_CODEC_DEFLATE} is, because it stores a container in fewer
+ * bytes and a build happens once where a fetch happens forever. This is what to set for a container
+ * whose pages arrive during play: it decodes at 562 MB/s against deflate's 126, and that decode is
+ * a page's arrival cost on the residency path.
+ *
  * @type {number}
  */
 export const VGEO_CODEC_LZ4: number;