@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/geometry/virtual/build/submesh/vgeo_extract_submesh.js

@@ -0,0 +1,135 @@
+import {
+    BinaryTopology, NULL_POINTER
+} from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { BtWedgeSet } from "../../../../../../core/geom/3d/topology/struct/binary/BtWedgeSet.js";
+import {
+    bt_mesh_from_indexed_geometry
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
+import { vgeo_layers_copy_corner } from "../../format/attribute/vgeo_layers_copy_corner.js";
+import { vgeo_layers_like } from "../../format/attribute/vgeo_layers_like.js";
+import { vgeo_gather_faces } from "./vgeo_gather_faces.js";
+import { VGeoSubmesh } from "./VGeoSubmesh.js";
+import { VirtualGeometryMesh } from "../mesh/VirtualGeometryMesh.js";
+
+/**
+ * Extract a face set into a standalone mesh, attributes and all.
+ *
+ * **Wedges are not vertices here.** The gather deduped on the wedge, because that is what a cluster
+ * payload's vertices are; a mesh's are not. Two wedges of one vertex are one point and one piece of
+ * connectivity, and giving them a vertex each would shred face adjacency along every seam — which
+ * is the move `WEDGE_PLAN_2026_09_18.md` §8 rejects and the reason the weld exists at all. So the
+ * gather's output is folded back onto one vertex per position and the wedges travel on the corners,
+ * where they belong.
+ *
+ * @param {VirtualGeometryMesh} source
+ * @param {number[]} face_ids
+ * @param {BtWedgeSet} source_wedges which corners of `source` shade as one
+ * @returns {VGeoSubmesh}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_extract_submesh(source, face_ids, source_wedges) {
+    const gathered = vgeo_gather_faces(source, face_ids, source_wedges);
+
+    const wedge_count = gathered.wedge_ids.length;
+
+    /**
+     * `source vertex id -> local vertex id`.
+     * @type {Map<number, number>}
+     */
+    const local_of_vertex = new Map();
+
+    /**
+     * The local vertex each gathered wedge sits at.
+     * @type {Uint32Array}
+     */
+    const vertex_of_wedge = new Uint32Array(wedge_count);
+
+    const source_vertex_ids = [];
+    const positions = [];
+
+    gathered.vertex_ids.forEach((vertex, wedge) => {
+        let local = local_of_vertex.get(vertex);
+
+        if (local === undefined) {
+            local = source_vertex_ids.length;
+
+            local_of_vertex.set(vertex, local);
+            source_vertex_ids.push(vertex);
+
+            positions.push(
+                gathered.positions[wedge * 3],
+                gathered.positions[wedge * 3 + 1],
+                gathered.positions[wedge * 3 + 2]
+            );
+        }
+
+        vertex_of_wedge[wedge] = local;
+    });
+
+    const topology = new BinaryTopology();
+
+    // Before the vertices, so no record has to be widened. See {@link VirtualGeometryMesh.from_geometry}.
+    const layers = vgeo_layers_like(topology, source.layers);
+
+    bt_mesh_from_indexed_geometry(
+        topology,
+        Uint32Array.from(gathered.indices, (wedge) => vertex_of_wedge[wedge]),
+        Float32Array.from(positions)
+    );
+
+    if (topology.faces.count() !== face_ids.length) {
+        // The corner walk below reads face `t` as the `t`th triangle of the index list, so a builder
+        // that dropped or reordered one would silently hand every corner the wrong appearance. A
+        // thrown build beats a wrong asset, and this cannot be an `assert` for exactly that reason:
+        // asserts are stripped from what ships.
+        throw new Error(
+            `extracting ${face_ids.length} faces produced ${topology.faces.count()}, so the corners `
+            + `of the result cannot be matched to the corners they came from`
+        );
+    }
+
+    const wedges = new BtWedgeSet();
+
+    wedges.count = wedge_count;
+    wedges.parent = Uint32Array.from({ length: wedge_count }, (_, wedge) => wedge);
+    wedges.next_of_wedge = new Uint32Array(wedge_count).fill(NULL_POINTER);
+    wedges.first_of_vertex = new Uint32Array(topology.vertices.size).fill(NULL_POINTER);
+    wedges.of_loop = new Uint32Array(topology.loops.size).fill(NULL_POINTER);
+
+    for (let wedge = 0; wedge < wedge_count; wedge++) {
+        wedges.attach(wedge, vertex_of_wedge[wedge]);
+    }
+
+    /*
+     Corner by corner, through the wedge each one names — which is the copy §6.1 could not make.
+     Going through the *vertex* was exact only while every corner of a vertex agreed; it does not
+     agree any more, and that is the point. The two meshes' loops are matched up here because the
+     faces were built from this very index list, in this order.
+     */
+    for (let face = 0; face < face_ids.length; face++) {
+        let loop = topology.face_read_loop(face);
+
+        for (let corner = 0; corner < 3; corner++) {
+            const wedge = gathered.indices[face * 3 + corner];
+
+            wedges.of_loop[loop] = wedge;
+
+            vgeo_layers_copy_corner(
+                topology, source.topology, gathered.attribute_ids[wedge], loop
+            );
+
+            loop = topology.loop_read_next(loop);
+        }
+    }
+
+    const result = new VGeoSubmesh();
+
+    result.mesh = new VirtualGeometryMesh(topology, layers);
+    result.source_vertex_ids = Uint32Array.from(source_vertex_ids);
+    result.wedges = wedges;
+    result.source_wedge_ids = gathered.wedge_ids;
+
+    return result;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Gather a face set: unique **wedges** in first-use order, local indices, coordinates copied out,
+ * and one corner per output vertex for the appearance to be read through.
+ *
+ * A wedge, not a vertex, and that is the whole of what a seam costs. Two corners of one vertex that
+ * shade differently cannot share an output vertex: the payload carries one value per vertex, so a
+ * hard edge or a texture chart boundary has to be two of them. It costs exactly what it has always
+ * cost anywhere else — a seam is an extra vertex in every renderer ever written — and it costs it
+ * *here*, at the gather, rather than in the topology, where splitting would shred face adjacency
+ * (`WEDGE_PLAN_2026_09_18.md` §8).
+ *
+ * A mesh with no seams has one wedge per vertex, every corner of a vertex resolves to it, and this
+ * dedupes on the vertex exactly as it always did.
+ *
+ * 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
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one
+ * @returns {VGeoGatheredFaces}
+ */
+export function vgeo_gather_faces(mesh: VirtualGeometryMesh, face_ids: number[], wedges: BtWedgeSet): 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":"AAWA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uEAJW,MAAM,EAAE,uBAEN,iBAAiB,CAgE7B;kCA5FiC,wBAAwB"}

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

@@ -0,0 +1,95 @@
+import { assert } from "../../../../../../core/assert.js";
+import { NULL_POINTER } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { VGeoGatheredFaces } from "./VGeoGatheredFaces.js";
+
+/**
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const scratch_coordinate = new Float32Array(3);
+
+/**
+ * Gather a face set: unique **wedges** in first-use order, local indices, coordinates copied out,
+ * and one corner per output vertex for the appearance to be read through.
+ *
+ * A wedge, not a vertex, and that is the whole of what a seam costs. Two corners of one vertex that
+ * shade differently cannot share an output vertex: the payload carries one value per vertex, so a
+ * hard edge or a texture chart boundary has to be two of them. It costs exactly what it has always
+ * cost anywhere else — a seam is an extra vertex in every renderer ever written — and it costs it
+ * *here*, at the gather, rather than in the topology, where splitting would shred face adjacency
+ * (`WEDGE_PLAN_2026_09_18.md` §8).
+ *
+ * A mesh with no seams has one wedge per vertex, every corner of a vertex resolves to it, and this
+ * dedupes on the vertex exactly as it always did.
+ *
+ * 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
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one
+ * @returns {VGeoGatheredFaces}
+ */
+export function vgeo_gather_faces(mesh, face_ids, wedges) {
+    const topology = mesh.topology;
+
+    /**
+     * `wedge -> local`, over wedge *roots*: a merged wedge answers to the one it merged into, and
+     * two corners that resolve to the same root are one output vertex.
+     * @type {Map<number, number>}
+     */
+    const local_of_wedge = new Map();
+
+    const vertex_ids = [];
+    const wedge_ids = [];
+    const attribute_ids = [];
+    const indices = new Uint32Array(face_ids.length * 3);
+
+    face_ids.forEach((face, face_index) => {
+        const first_loop = topology.face_read_loop(face);
+
+        assert.notEqual(first_loop, NULL_POINTER, `face ${face} has no loop`);
+
+        let loop = first_loop;
+
+        for (let i = 0; i < 3; i++) {
+            const wedge = wedges.find(wedges.of_loop[loop]);
+
+            let local = local_of_wedge.get(wedge);
+
+            if (local === undefined) {
+                local = wedge_ids.length;
+
+                local_of_wedge.set(wedge, local);
+
+                wedge_ids.push(wedge);
+                vertex_ids.push(topology.loop_read_vertex(loop));
+                attribute_ids.push(loop);
+            }
+
+            indices[face_index * 3 + i] = local;
+
+            loop = topology.loop_read_next(loop);
+        }
+
+        assert.equal(loop, first_loop, `face ${face} is not an allocated triangle`);
+    });
+
+    const result = new VGeoGatheredFaces();
+
+    result.vertex_ids = Uint32Array.from(vertex_ids);
+    result.wedge_ids = Uint32Array.from(wedge_ids);
+    result.attribute_ids = Uint32Array.from(attribute_ids);
+    result.indices = indices;
+    result.positions = new Float32Array(vertex_ids.length * 3);
+
+    vertex_ids.forEach((vertex, local) => {
+        topology.vertex_read_coordinate(scratch_coordinate, 0, vertex);
+
+        result.positions[local * 3] = scratch_coordinate[0];
+        result.positions[local * 3 + 1] = scratch_coordinate[1];
+        result.positions[local * 3 + 2] = scratch_coordinate[2];
+    });
+
+    return result;
+}

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

@@ -13,10 +13,14 @@
  * geometry that arrives without them is given them by normalization, off the welded mesh — see
  * {@link vgeo_normalize_source}.
  *
+ * It is asynchronous only because the writer is, and the writer is because a page codec can be —
+ * {@link VGEO_CODEC_DEFLATE} is the platform's zlib and the platform only offers it as a stream.
+ * Every other step below is the same synchronous pipeline it has always been.
+ *
  * @param {Geometry} geometry the source, in object space
  * @param {VGeoBuildOptions} options
- * @returns {VGeoBuildResult}
+ * @returns {Promise<VGeoBuildResult>}
  */
-export function vgeo_build(geometry: Geometry, options: VGeoBuildOptions): VGeoBuildResult;
+export function vgeo_build(geometry: Geometry, options: VGeoBuildOptions): Promise<VGeoBuildResult>;
 import { VGeoBuildResult } from "./VGeoBuildResult.js";
 //# sourceMappingURL=vgeo_build.d.ts.map

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":"AA8GA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,2EAFa,QAAQ,eAAe,CAAC,CA0FpC;gCAhN+B,sBAAsB"}

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

@@ -1,16 +1,19 @@
 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 { vgeo_resolve_attribute_weights } from "./mesh/vgeo_resolve_attribute_weights.js";
+import { vgeo_subtree_bounds } from "./vgeo_subtree_bounds.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 +49,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);
         }
     }
 
@@ -123,17 +123,21 @@ function level_summary_to_record(summary) {
  * geometry that arrives without them is given them by normalization, off the welded mesh — see
  * {@link vgeo_normalize_source}.
  *
+ * It is asynchronous only because the writer is, and the writer is because a page codec can be —
+ * {@link VGEO_CODEC_DEFLATE} is the platform's zlib and the platform only offers it as a stream.
+ * Every other step below is the same synchronous pipeline it has always been.
+ *
  * @param {Geometry} geometry the source, in object space
  * @param {VGeoBuildOptions} options
- * @returns {VGeoBuildResult}
+ * @returns {Promise<VGeoBuildResult>}
  */
-export function vgeo_build(geometry, options) {
+export async function vgeo_build(geometry, options) {
     assert.greaterThan(options.weld_ratio, 0, 'options.weld_ratio');
     assert.isPositiveInteger(options.nominal_page_size, 'options.nominal_page_size');
 
     const mesh = VirtualGeometryMesh.from_geometry(geometry);
 
-    const weld_distance = vgeo_normalize_source(mesh, options.weld_ratio);
+    const weld_distance = vgeo_normalize_source(mesh, options.weld_ratio, options.crease_angle);
 
     const source_face_count = mesh.topology.faces.count();
     const source_vertex_count = mesh.topology.vertices.count();
@@ -141,7 +145,18 @@ export function vgeo_build(geometry, options) {
     assert.greaterThan(source_face_count, 0, 'the source mesh has no faces left after normalization');
     assert.greaterThanOrEqual(source_vertex_count, 3, 'source vertex count');
 
-    const levels = vgeo_build_levels(mesh, options.level_options);
+    /*
+     Resolved here, off the normalized source and before the level loop, for the same reason the weld
+     distance is a fraction of the source's own size: a conversion is many geometries at many sizes
+     and no single number is right for all of them. Once, so every level of the DAG is built against
+     the same statement of what a unit of each channel is worth -- the mesh shrinks as the build goes
+     on, and a weight re-derived per level would drift with it.
+     */
+    const levels = vgeo_build_levels(
+        mesh,
+        options.level_options,
+        vgeo_resolve_attribute_weights(mesh, options.attribute_weight_ratios)
+    );
 
     const top = levels[levels.length - 1];
 
@@ -155,6 +170,12 @@ export function vgeo_build(geometry, options) {
 
     top.groups = [vgeo_build_root_group(root, top.index)];
 
+    /*
+     After the root's own fields and before anything reads a cluster: the page assembler and the
+     writer both take clusters as they are, and this is the last thing the DAG gains.
+    */
+    vgeo_subtree_bounds(levels);
+
     const object = compute_object_bounds(levels);
 
     const pages = vgeo_assemble_pages(
@@ -185,7 +206,7 @@ export function vgeo_build(geometry, options) {
 
     const result = new VGeoBuildResult();
 
-    result.buffer = vgeo_write_container(pages, write_options);
+    result.buffer = await vgeo_write_container(pages, write_options);
     result.page_count = pages.length;
     result.source_vertex_count = source_vertex_count;
     result.source_face_count = source_face_count;

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

@@ -0,0 +1,32 @@
+/**
+ * Give every cluster of a built DAG the AABB of its own geometry and of everything reachable below
+ * it, which is the bound the runtime cut culls on (`CULL_PLAN_2026_09_16` §3.1, FORMAT §11.17).
+ *
+ * **Why the subtree and not the cluster.** A simplification step consumes one group and produces
+ * several parents, and each parent's `child_group` is the *whole* consumed group — so a cluster's
+ * subtree carries its siblings' surface as well as its own, and doubles per level. The cut's
+ * per-cluster test decides whether to descend into that group at all, so a bound that covers only
+ * the cluster would cull a parent whose descendants are on screen, and a culled subtree is a hole.
+ *
+ * **Why a memoised walk rather than a pass by level.** A round leaves unmerged clusters in the
+ * frontier, so a group formed at round L can hold members created at any lower level, and
+ * `group.level` records where the group was formed rather than where its members were. Following
+ * `child_group` instead needs no such assumption. The DAG is acyclic (format §11.3) and a group is
+ * shared by its several parents, so memoising on the cluster makes this O(clusters + edges) with the
+ * shared work done once.
+ *
+ * Recursion is explicit: these DAGs run to forty levels but a page's group can hold thousands of
+ * clusters, and a native stack deep in the fine levels of a billion-triangle build is not worth the
+ * elegance.
+ *
+ * The union is of float32 extremes, so every bound it produces is exactly representable and
+ * contains what it was built from with no inflation — unlike a sphere, which is why the validator
+ * can check this one exactly.
+ *
+ * @param {VGeoLevel[]} levels as {@link vgeo_build_levels} leaves them
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_subtree_bounds(levels: VGeoLevel[]): void;
+//# sourceMappingURL=vgeo_subtree_bounds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_subtree_bounds.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_subtree_bounds.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,4CALW,WAAW,QAiErB"}

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

@@ -0,0 +1,93 @@
+import { aabb3_array_combine } from "../../../../../core/geom/3d/aabb/aabb3_array_combine.js";
+
+/**
+ * Give every cluster of a built DAG the AABB of its own geometry and of everything reachable below
+ * it, which is the bound the runtime cut culls on (`CULL_PLAN_2026_09_16` §3.1, FORMAT §11.17).
+ *
+ * **Why the subtree and not the cluster.** A simplification step consumes one group and produces
+ * several parents, and each parent's `child_group` is the *whole* consumed group — so a cluster's
+ * subtree carries its siblings' surface as well as its own, and doubles per level. The cut's
+ * per-cluster test decides whether to descend into that group at all, so a bound that covers only
+ * the cluster would cull a parent whose descendants are on screen, and a culled subtree is a hole.
+ *
+ * **Why a memoised walk rather than a pass by level.** A round leaves unmerged clusters in the
+ * frontier, so a group formed at round L can hold members created at any lower level, and
+ * `group.level` records where the group was formed rather than where its members were. Following
+ * `child_group` instead needs no such assumption. The DAG is acyclic (format §11.3) and a group is
+ * shared by its several parents, so memoising on the cluster makes this O(clusters + edges) with the
+ * shared work done once.
+ *
+ * Recursion is explicit: these DAGs run to forty levels but a page's group can hold thousands of
+ * clusters, and a native stack deep in the fine levels of a billion-triangle build is not worth the
+ * elegance.
+ *
+ * The union is of float32 extremes, so every bound it produces is exactly representable and
+ * contains what it was built from with no inflation — unlike a sphere, which is why the validator
+ * can check this one exactly.
+ *
+ * @param {VGeoLevel[]} levels as {@link vgeo_build_levels} leaves them
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_subtree_bounds(levels) {
+    /**
+     * Clusters whose `subtree_aabb` is final.
+     * @type {Set<VirtualGeometryCluster>}
+     */
+    const done = new Set();
+
+    /**
+     * Cluster, then the mark that says its children have been visited already.
+     * @type {(VirtualGeometryCluster|boolean)[]}
+     */
+    const stack = [];
+
+    for (const level of levels) {
+        for (const root of level.clusters) {
+            if (done.has(root)) {
+                continue;
+            }
+
+            stack.push(root, false);
+
+            while (stack.length > 0) {
+                const expanded = stack.pop();
+                const cluster = stack.pop();
+
+                if (done.has(cluster)) {
+                    continue;
+                }
+
+                const group = cluster.child_group;
+
+                if (group !== undefined && !expanded) {
+                    // come back to this one once its children are final
+                    stack.push(cluster, true);
+
+                    for (const child of group.clusters) {
+                        if (!done.has(child)) {
+                            stack.push(child, false);
+                        }
+                    }
+
+                    continue;
+                }
+
+                cluster.subtree_aabb.set(cluster.aabb);
+
+                if (group !== undefined) {
+                    for (const child of group.clusters) {
+                        aabb3_array_combine(
+                            cluster.subtree_aabb, 0,
+                            cluster.subtree_aabb, 0,
+                            child.subtree_aabb, 0
+                        );
+                    }
+                }
+
+                done.add(cluster);
+            }
+        }
+    }
+}

package/src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.d.ts

@@ -9,20 +9,33 @@
  */
 export class VGeoWriteOptions {
     /**
-     * Which codec to store page blobs under. On by default because a page is a table of records and
-     * a payload of encoded words, and both repeat heavily — see the format's §5 note on what it
-     * comes to. It costs the reader an LZ4 block decode per page, which runs at gigabytes a second
-     * and lands on the page it was going to copy anyway.
+     * Which codec to store page blobs under — {@link VGEO_CODEC_RAW}, {@link VGEO_CODEC_LZ4} or
+     * {@link VGEO_CODEC_DEFLATE}. Compressed by default because a page is a table of records and a
+     * payload of encoded words, and both repeat heavily — see the format's §5 note on what it comes
+     * to. It costs the reader one block decode per page, which lands on the page it was going to
+     * copy anyway.
      *
      * It is a request rather than a promise: {@link vgeo_encode_frame_blob} stores a page raw when
      * compressing it would not make it smaller, so this can never grow a file.
      *
+     * Deflate by default, matching {@link VGeoBuildOptions}. Nothing exercises this value today —
+     * `vgeo_build` sets it from the build options and the specs that drive the writer directly set
+     * it too — so it is here to agree with the builder rather than to decide anything, and two
+     * adjacent defaults that disagreed would be a trap for whoever wrote the next caller.
+     *
+     * Deflate is the denser of the two compressing codecs, 1.369x against LZ4's 1.295x over the
+     * pages of a 240x120 torus, for about four and a half times the decode: 126 MB/s of decoded
+     * output against 562. {@link VGEO_CODEC_LZ4} is the setting for a container whose pages arrive
+     * while someone is looking at it, because that decode is a page's arrival cost.
+     *
      * @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.
+     * top of the reference's hash-chain levels. **LZ4 only, and the default codec is not LZ4** —
+     * `CompressionStream` exposes no level, so this does nothing at all unless {@link codec} was
+     * set to {@link VGEO_CODEC_LZ4}.
      *
      * **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
@@ -39,7 +52,8 @@ export class VGeoWriteOptions {
      */
     codec_level: number;
     /**
-     * One per level, coarsest last. `level_count` is its length.
+     * One per level, coarsest last. `level_count` is its length, and the header can name up to
+     * {@link VGEO_MAX_LEVEL_COUNT} of them.
      * @type {VGeoLevelRecord[]}
      */
     levels: VGeoLevelRecord[];

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoWriteOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;OAgBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;OAGG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;;OAUG;IACH,mBAFU,MAAM,CAEM;CACzB;8BA1FY,OAAO,6BAA6B,EAAE,eAAe"}
+{"version":3,"file":"VGeoWriteOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;;;;;GAKG;AACH;IACI;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAFU,MAAM,CAEW;IAE3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;;OAIG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;;OAUG;IACH,mBAFU,MAAM,CAEM;CACzB;8BAxGY,OAAO,6BAA6B,EAAE,eAAe"}

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

@@ -1,5 +1,5 @@
 import { LZ4_LEVEL } from "../../../../../core/binary/lz4/LZ4_LEVEL.js";
-import { VGEO_CODEC_LZ4 } from "./frame/VGEO_CODEC_LZ4.js";
+import { VGEO_CODEC_DEFLATE } from "./frame/VGEO_CODEC_DEFLATE.js";
 
 /**
  * @typedef {import("./header/VGeoLevelRecord.js").VGeoLevelRecord} VGeoLevelRecord
@@ -13,21 +13,34 @@ import { VGEO_CODEC_LZ4 } from "./frame/VGEO_CODEC_LZ4.js";
  */
 export class VGeoWriteOptions {
     /**
-     * Which codec to store page blobs under. On by default because a page is a table of records and
-     * a payload of encoded words, and both repeat heavily — see the format's §5 note on what it
-     * comes to. It costs the reader an LZ4 block decode per page, which runs at gigabytes a second
-     * and lands on the page it was going to copy anyway.
+     * Which codec to store page blobs under — {@link VGEO_CODEC_RAW}, {@link VGEO_CODEC_LZ4} or
+     * {@link VGEO_CODEC_DEFLATE}. Compressed by default because a page is a table of records and a
+     * payload of encoded words, and both repeat heavily — see the format's §5 note on what it comes
+     * to. It costs the reader one block decode per page, which lands on the page it was going to
+     * copy anyway.
      *
      * It is a request rather than a promise: {@link vgeo_encode_frame_blob} stores a page raw when
      * compressing it would not make it smaller, so this can never grow a file.
      *
+     * Deflate by default, matching {@link VGeoBuildOptions}. Nothing exercises this value today —
+     * `vgeo_build` sets it from the build options and the specs that drive the writer directly set
+     * it too — so it is here to agree with the builder rather than to decide anything, and two
+     * adjacent defaults that disagreed would be a trap for whoever wrote the next caller.
+     *
+     * Deflate is the denser of the two compressing codecs, 1.369x against LZ4's 1.295x over the
+     * pages of a 240x120 torus, for about four and a half times the decode: 126 MB/s of decoded
+     * output against 562. {@link VGEO_CODEC_LZ4} is the setting for a container whose pages arrive
+     * while someone is looking at it, because that decode is a page's arrival cost.
+     *
      * @type {number}
      */
-    codec = VGEO_CODEC_LZ4;
+    codec = VGEO_CODEC_DEFLATE;
 
     /**
      * 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.
+     * top of the reference's hash-chain levels. **LZ4 only, and the default codec is not LZ4** —
+     * `CompressionStream` exposes no level, so this does nothing at all unless {@link codec} was
+     * set to {@link VGEO_CODEC_LZ4}.
      *
      * **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
@@ -45,7 +58,8 @@ export class VGeoWriteOptions {
     codec_level = LZ4_LEVEL.HC_DEFAULT;
 
     /**
-     * One per level, coarsest last. `level_count` is its length.
+     * One per level, coarsest last. `level_count` is its length, and the header can name up to
+     * {@link VGEO_MAX_LEVEL_COUNT} of them.
      * @type {VGeoLevelRecord[]}
      */
     levels = [];