@woosh/meep-engine 3.26.0 → 3.28.0

package/src/shade/renderer/geometry/virtual/build/mesh/VirtualGeometryMesh.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A level of geometry as the builder handles it: a `BinaryTopology` carrying the positions, the
+ * connectivity, and the per-vertex attributes all together.
+ *
+ * Everything per-vertex lives in the topology. It has to: an edge collapse moves and removes
+ * vertices, and the topology is the only thing that knows which. A vertex data layer is addressed
+ * by vertex id and sized by the vertex pool, so a channel cannot fall out of step with the mesh it
+ * describes — there is no second array to resize, no invariant to assert, and no way for the
+ * simplifier to leave a live vertex without a slot.
+ *
+ * The channels are named by their index into {@link VGEO_ATTRIBUTES}, which is the format's frozen
+ * table — {@link layers} has one slot per entry, holding a layer or null.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VirtualGeometryMesh {
+    /**
+     * Take a geometry apart into the form the builder simplifies: its positions and index become a
+     * topology, its other attributes become vertex data layers on that same topology.
+     *
+     * The attribute values are copied in, not adopted. The builder re-derives the shading frame as
+     * it coarsens, and the caller's geometry is no longer where that lands.
+     *
+     * The normal and tangent channels are declared whether or not the geometry carries them: they
+     * are what the shading model reads, so the builder owes an asset both. What it does not have,
+     * {@link synthesized} records, and {@link vgeo_normalize_source} fills.
+     *
+     * @param {Geometry} geometry triangles, with a position attribute; the index is synthesized when
+     *     the geometry does not carry one
+     * @returns {VirtualGeometryMesh}
+     */
+    static from_geometry(geometry: Geometry): VirtualGeometryMesh;
+    /**
+     * @param {BinaryTopology} topology
+     * @param {(BinaryDataLayer|null)[]} layers declared on `topology`
+     */
+    constructor(topology: BinaryTopology, layers: (BinaryDataLayer | null)[]);
+    /**
+     * Positions, connectivity, and the vertex data block the {@link layers} address.
+     * @type {BinaryTopology}
+     */
+    topology: BinaryTopology;
+    /**
+     * One slot per {@link VGEO_ATTRIBUTES} entry, holding the vertex data layer that carries that
+     * channel or null where this geometry does not carry it.
+     * {@link VGEO_ATTRIBUTE.POSITION}'s slot is always null — position is the topology's own.
+     * @type {(BinaryDataLayer|null)[]}
+     */
+    layers: (BinaryDataLayer | null)[];
+    /**
+     * One flag per {@link VGEO_ATTRIBUTES} entry, true where the channel exists because the builder
+     * added it rather than because the source geometry carried it.
+     *
+     * Read once, by {@link vgeo_normalize_source}, and for one reason: a synthesized channel has to
+     * be derived from the *welded* mesh, which does not exist yet when the channel is declared.
+     * Normalization fuses coincident vertices, and a normal derived before that fuse is the average
+     * of one side of a seam — the very defect deriving it is supposed to avoid.
+     *
+     * An authored channel is never among these. A hand-tuned normal is data, and the builder is not
+     * entitled to replace it.
+     *
+     * @type {boolean[]}
+     */
+    synthesized: boolean[];
+    /**
+     * Ids of every allocated face, ascending.
+     * @returns {number[]}
+     */
+    face_ids(): number[];
+}
+import { BinaryTopology } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+//# sourceMappingURL=VirtualGeometryMesh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VirtualGeometryMesh.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/VirtualGeometryMesh.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;GAeG;AACH;IA6CI;;;;;;;;;;;;;;OAcG;IACH,0CAFa,mBAAmB,CA8G/B;IAzID;;;OAGG;IACH,sBAHW,cAAc,UACd,CAAC,kBAAgB,IAAI,CAAC,EAAE,EAUlC;IA1CD;;;OAGG;IACH,UAFU,cAAc,CAER;IAEhB;;;;;OAKG;IACH,QAFU,CAAC,kBAAgB,IAAI,CAAC,EAAE,CAEtB;IAEZ;;;;;;;;;;;;;OAaG;IACH,aAFU,OAAO,EAAE,CAEyC;IA6I5D;;;OAGG;IACH,YAFa,MAAM,EAAE,CAcpB;CACJ;+BApN8B,yEAAyE"}

package/src/shade/renderer/geometry/virtual/build/{VirtualGeometryMesh.js → mesh/VirtualGeometryMesh.js}

@@ -1,12 +1,12 @@
-import { assert } from "../../../../../core/assert.js";
-import { BinaryTopology } from "../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { assert } from "../../../../../../core/assert.js";
+import { BinaryTopology } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 import {
     bt_mesh_from_indexed_geometry
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
-import { StandardAttributes } from "../../StandardAttributes.js";
-import { vgeo_layers_declare } from "../format/attribute/vgeo_layers_declare.js";
-import { VGEO_ATTRIBUTE } from "../format/attribute/VGEO_ATTRIBUTE.js";
-import { VGEO_ATTRIBUTES } from "../format/attribute/VGEO_ATTRIBUTES.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
+import { StandardAttributes } from "../../../StandardAttributes.js";
+import { vgeo_layers_declare } from "../../format/attribute/vgeo_layers_declare.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+import { VGEO_ATTRIBUTES } from "../../format/attribute/VGEO_ATTRIBUTES.js";
 
 /**
  * A level of geometry as the builder handles it: a `BinaryTopology` carrying the positions, the

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_compute_vertex_normals.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Area-weighted vertex normals of a mesh, written into its normal channel.
+ *
+ * The geometry a mesh actually has is the answer for that mesh: carrying a surviving vertex's
+ * original normal through a dozen collapses shades a coarse level by whichever vertices happened to
+ * win, which is visibly wrong.
+ *
+ * **Except where the vertex was pinned.** A pinned vertex is one the step was forbidden to move, and
+ * every group that touches it carries it — which is exactly what lets a cut place two levels of
+ * detail side by side without a crack. That guarantee has to cover what the vertex *carries*, not
+ * only where it is: recomputed here, a pinned vertex would get the average of the faces on this
+ * side of the seam only, the group across the seam would get the average of its own, and the two
+ * would disagree by however much the surface turns. So a pinned vertex keeps what it had, exactly
+ * as it keeps where it was, and the frame stays continuous across every cut the DAG admits.
+ *
+ * The pass itself is {@link bt_mesh_compute_vertex_normals}; all this adds is the pin rule and
+ * lifting its result out of the topology's own normal slots and into the format's normal attribute,
+ * which is where the encoder reads from.
+ *
+ * @param {VirtualGeometryMesh} mesh whose normal layer is sized by the vertex pool and so carries a
+ *     slot for every live vertex by construction
+ * @param {Set<number>} pinned vertex ids to leave exactly as they are; empty for a mesh nothing has
+ *     locked yet
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_compute_vertex_normals(mesh: VirtualGeometryMesh, pinned: Set<number>): void;
+//# sourceMappingURL=vgeo_compute_vertex_normals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_compute_vertex_normals.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_compute_vertex_normals.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,+EANW,IAAI,MAAM,CAAC,QAyCrB"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_compute_vertex_normals.js → mesh/vgeo_compute_vertex_normals.js}

@@ -1,8 +1,8 @@
-import { assert } from "../../../../../core/assert.js";
+import { assert } from "../../../../../../core/assert.js";
 import {
     bt_mesh_compute_vertex_normals
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_normals.js";
-import { VGEO_ATTRIBUTE } from "../format/attribute/VGEO_ATTRIBUTE.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_normals.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
 
 /**
  * One vertex's normal, on its way out of the topology's slot and into the format's channel.

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_compute_vertex_tangents.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Vertex tangents of a mesh, written into its tangent channel.
+ *
+ * A tangent is a direction *in the texture parameterization*, so where the mesh carries a `UV0` this
+ * is Lengyel's per-triangle solve accumulated per vertex and orthogonalized against the normal —
+ * {@link geometry_build_tangents}, the same pass {@link Geometry#computeTangents} runs, so an asset
+ * that goes through the virtual-geometry builder gets the frame it would have got anywhere else.
+ * Where the mesh carries no UVs there is no parameterization to be tangent to, and the frame becomes
+ * an arbitrary but well-conditioned basis around the normal — Frisvad's, via
+ * {@link build_tangent_from_normal}. That is not a fallback for a broken input: a shading model that
+ * reads a tangent frame reads one whether or not the surface is textured, and the alternative is
+ * the format's flat default, which is parallel to the normal over a whole band of any closed
+ * surface and degenerates the frame there.
+ *
+ * `pinned` carries the same meaning and the same reason as it does for
+ * {@link vgeo_compute_vertex_normals}: a vertex two groups share must carry byte-identical values in
+ * both, or the seam a cut is allowed to put between them shades as a crease.
+ *
+ * The flat arrays this builds are indexed by *vertex id*, holes and all, so a pool with released
+ * slots needs no compaction and no remap — a released slot is simply a triangle corner nothing
+ * names.
+ *
+ * @param {VirtualGeometryMesh} mesh whose tangent and normal layers are sized by the vertex pool
+ * @param {Set<number>} pinned vertex ids to leave exactly as they are; empty for a mesh nothing has
+ *     locked yet
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_compute_vertex_tangents(mesh: VirtualGeometryMesh, pinned: Set<number>): void;
+//# sourceMappingURL=vgeo_compute_vertex_tangents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_compute_vertex_tangents.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_compute_vertex_tangents.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,gFANW,IAAI,MAAM,CAAC,QAmGrB"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_compute_vertex_tangents.js → mesh/vgeo_compute_vertex_tangents.js}

@@ -1,10 +1,10 @@
-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";
-import { build_tangent_from_normal } from "../../normals/build_tangent_from_normal.js";
-import { geometry_build_tangents } from "../../normals/geometry_build_tangents.js";
-import { VGEO_ATTRIBUTE } from "../format/attribute/VGEO_ATTRIBUTE.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_face_read_triangle.js";
+import { build_tangent_from_normal } from "../../../normals/build_tangent_from_normal.js";
+import { geometry_build_tangents } from "../../../normals/geometry_build_tangents.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
 
 /**
  * One vertex's tangent, on its way into the format's channel.

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_normalize_source.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Bring a source mesh to the state the level loop assumes: no edge shorter than the weld tolerance,
+ * coincident vertices fused, nothing dangling, and consistent topology.
+ *
+ * The short-edge pass is not optional — the merge's own contract requires it, because merging two
+ * vertices that share a face leaves a loop cycle visiting one vertex twice, and no boundary walk can
+ * get through the non-manifold edge that produces.
+ *
+ * It **collapses** those edges rather than killing them, and the difference is the whole surface.
+ * `bt_mesh_kill_short_edges` deletes both faces of every edge it names, which is right for a soup
+ * and wrong here: the weld behind it closes most of the resulting holes and leaves the rest, and a
+ * hole left in the source is a hole in every level of the DAG built on it. Measured on the Stanford
+ * dragon, closed to begin with: killing opened 18,438 boundary edges and left 281 of them standing;
+ * collapsing leaves none.
+ *
+ * Neither is the fuse that follows it. The merge re-points vertex references but leaves the two
+ * edges that now connect the same pair as two distinct edges, and face adjacency is read off radial
+ * cycles — so without the fuse, two triangles welded along a seam still look unrelated to every
+ * query downstream, and the clusterer shreds the mesh along every UV seam it has.
+ *
+ * Nor is the degenerate-face kill. The short-edge pass clears the pairs an *edge* is short enough to
+ * name, but the merge is a hash grid: two corners of one face up to twice the tolerance apart can
+ * still land on a common master and become one vertex, leaving a face that visits it twice.
+ *
+ * The tolerance is a fraction of the mesh's own size rather than a distance, and it is resolved here
+ * — once, off the source's bounds, before any pass has removed anything — so every pass below welds
+ * the same amount of the same surface. A conversion is many geometries at many sizes, and there is
+ * no one distance that is right for all of them.
+ *
+ * The shading frame is regularized too, and last. A geometry that arrived without normals or without
+ * tangents is given them here rather than at the door, because *here* is the first point at which
+ * the mesh is the one the rest of the build will see: derived before the weld, a normal at a seam
+ * vertex would be the average of whichever side of the seam the exporter happened to split it into,
+ * and the fuse would then pick one of those halves to keep. Derived after it, the vertex has its
+ * whole ring. Channels the source did carry are left exactly as they came.
+ *
+ * @param {VirtualGeometryMesh} mesh mutated in place
+ * @param {number} weld_ratio fraction of the bounding-box diagonal; see
+ *     {@link VGeoBuildOptions#weld_ratio}
+ * @returns {number} the object-space distance the ratio came to for this mesh
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_normalize_source(mesh: VirtualGeometryMesh, weld_ratio: number): number;
+//# sourceMappingURL=vgeo_normalize_source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_normalize_source.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_normalize_source.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,6EAPW,MAAM,GAEJ,MAAM,CAyClB"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_normalize_source.js → mesh/vgeo_normalize_source.js}

@@ -1,24 +1,24 @@
-import { assert } from "../../../../../core/assert.js";
+import { assert } from "../../../../../../core/assert.js";
 import {
     bt_mesh_cleanup_faceless_references
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_cleanup_faceless_references.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_cleanup_faceless_references.js";
 import {
     bt_mesh_collapse_short_edges
-} from "../../../../../core/geom/3d/topology/struct/binary/io/edge/bt_mesh_collapse_short_edges.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/edge/bt_mesh_collapse_short_edges.js";
 import {
     bt_mesh_fuse_duplicate_edges
-} from "../../../../../core/geom/3d/topology/struct/binary/io/edge/bt_mesh_fuse_duplicate_edges.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/edge/bt_mesh_fuse_duplicate_edges.js";
 import {
     bt_mesh_kill_degenerate_faces
-} from "../../../../../core/geom/3d/topology/struct/binary/io/face/bt_mesh_kill_degenerate_faces.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/face/bt_mesh_kill_degenerate_faces.js";
 import {
     bt_merge_vertices_by_distance
-} from "../../../../../core/geom/3d/topology/struct/binary/io/vertex/bt_merge_vertices_by_distance.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/vertex/bt_merge_vertices_by_distance.js";
 import {
     bt_mesh_relative_merge_distance
-} from "../../../../../core/geom/3d/topology/struct/binary/io/vertex/bt_mesh_relative_merge_distance.js";
-import { bt_mesh_validate } from "../../../../../core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js";
-import { VGEO_ATTRIBUTE } from "../format/attribute/VGEO_ATTRIBUTE.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/vertex/bt_mesh_relative_merge_distance.js";
+import { bt_mesh_validate } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
 import { vgeo_compute_vertex_normals } from "./vgeo_compute_vertex_normals.js";
 import { vgeo_compute_vertex_tangents } from "./vgeo_compute_vertex_tangents.js";
 

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

@@ -0,0 +1,13 @@
+/**
+ * Assign groups to pages.
+ *
+ * @param {VirtualGeometryGroup[][]} groups_by_level indexed by level; every group of every level,
+ *     including the root level's
+ * @param {Float32Array} object_bounds `[min xyz, max xyz]` of the whole geometry, for the Morton grid
+ * @param {number} nominal_page_size decoded bytes per page, as a hard cap: no returned page decodes
+ *     to more, and a group that cannot fit one on its own throws
+ * @returns {VirtualGeometryPage[]} in file order, root page first
+ */
+export function vgeo_assemble_pages(groups_by_level: VirtualGeometryGroup[][], object_bounds: Float32Array, nominal_page_size: number): VirtualGeometryPage[];
+import { VirtualGeometryPage } from "../../format/dag/VirtualGeometryPage.js";
+//# sourceMappingURL=vgeo_assemble_pages.d.ts.map

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

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

package/src/shade/renderer/geometry/virtual/build/{vgeo_assemble_pages.js → page/vgeo_assemble_pages.js}

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

package/src/shade/renderer/geometry/virtual/build/page/vgeo_build_page_nodes.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Build the tree over a page's groups.
+ *
+ * Breadth-first, so that a node's children occupy a contiguous run of indices and every parent sits
+ * at a lower index than its children — which is what lets the metric be filled in by one backwards
+ * sweep, and what lets a reader walk the tree without a stack of anything but indices.
+ *
+ * @param {VirtualGeometryPage} page whose `groups` are already in the order they will be written
+ * @returns {VirtualGeometryPageNode[]} the tree, root first; never empty
+ */
+export function vgeo_build_page_nodes(page: VirtualGeometryPage): VirtualGeometryPageNode[];
+import { VirtualGeometryPageNode } from "../../format/dag/VirtualGeometryPageNode.js";
+//# sourceMappingURL=vgeo_build_page_nodes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_build_page_nodes.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/page/vgeo_build_page_nodes.js"],"names":[],"mappings":"AAsDA;;;;;;;;;GASG;AACH,kEAFa,uBAAuB,EAAE,CA8FrC;wCAvJuC,6CAA6C"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_build_page_nodes.js → page/vgeo_build_page_nodes.js}

@@ -1,9 +1,9 @@
-import { assert } from "../../../../../core/assert.js";
+import { assert } from "../../../../../../core/assert.js";
 import {
     sphere_compute_bounding_of_2_spheres
-} from "../../../../../core/geom/3d/sphere/sphere_compute_bounding_of_2_spheres.js";
-import { VGEO_NODE_FANOUT } from "../format/page/VGEO_NODE_FANOUT.js";
-import { VirtualGeometryPageNode } from "../format/dag/VirtualGeometryPageNode.js";
+} from "../../../../../../core/geom/3d/sphere/sphere_compute_bounding_of_2_spheres.js";
+import { VGEO_NODE_FANOUT } from "../../format/page/VGEO_NODE_FANOUT.js";
+import { VirtualGeometryPageNode } from "../../format/dag/VirtualGeometryPageNode.js";
 
 /**
  * Build a page's group tree, and the page's own metric with it.

package/src/shade/renderer/geometry/virtual/build/page/vgeo_page_node_count.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How many nodes {@link vgeo_build_page_nodes} will put over a page holding `group_count` groups.
+ *
+ * The tree's shape is a function of the group *count* alone — every node covers a contiguous run of
+ * the page's Morton order and splits it into as-near-equal parts as integers allow — so the node
+ * table's size is known before the tree exists. Which is what the page assembler needs: the node
+ * table is part of the decoded page, and a page whose size is a hard bound has to be measured with
+ * it included, while the tree itself cannot be built until the page's last group has arrived.
+ *
+ * This duplicates the recurrence in {@link vgeo_build_page_nodes} rather than sharing it, because
+ * the two want different things from it — one wants the ranges and one wants only how many there
+ * are — and the cost of the duplication is a spec that runs both and compares.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @param {number} group_count
+ * @returns {number} nodes, at least one
+ */
+export function vgeo_page_node_count(group_count: number): number;
+//# sourceMappingURL=vgeo_page_node_count.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_page_node_count.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/page/vgeo_page_node_count.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AACH,kDAHW,MAAM,GACJ,MAAM,CA8BlB"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_page_node_count.js → page/vgeo_page_node_count.js}

@@ -1,5 +1,5 @@
-import { assert } from "../../../../../core/assert.js";
-import { VGEO_NODE_FANOUT } from "../format/page/VGEO_NODE_FANOUT.js";
+import { assert } from "../../../../../../core/assert.js";
+import { VGEO_NODE_FANOUT } from "../../format/page/VGEO_NODE_FANOUT.js";
 
 /**
  * How many nodes {@link vgeo_build_page_nodes} will put over a page holding `group_count` groups.

package/src/shade/renderer/geometry/virtual/build/partition/VGeoFaceGraph.d.ts

@@ -0,0 +1,52 @@
+export class VGeoFaceGraph {
+    /**
+     * @param {BinaryTopology} mesh
+     * @param {BinaryTopologyFaceGraph} face_graph
+     */
+    constructor(mesh: BinaryTopology, face_graph: BinaryTopologyFaceGraph);
+    /**
+     * @type {BinaryTopology}
+     */
+    mesh: BinaryTopology;
+    /**
+     * CSR over dense face-graph vertices; edge weights are shared-edge counts.
+     * @type {MetisGraph}
+     */
+    graph: MetisGraph;
+    /**
+     * `vertex_face_ids[dense] = face id`.
+     * @type {Uint32Array}
+     */
+    vertex_face_ids: Uint32Array;
+    /**
+     * Scratch stamp for unique-vertex counting, one entry per mesh vertex slot.
+     * @type {Int32Array}
+     */
+    vertex_stamp: Int32Array;
+    /**
+     * Monotonic stamp value, so the scratch never needs clearing.
+     * @type {number}
+     */
+    stamp: number;
+    /**
+     * Scratch `graph vertex -> its position in the member list being split right now`, one entry per
+     * graph vertex. Only the entries of that member list mean anything, which is all
+     * {@link vgeo_split_face_set}'s partition step ever reads: it consults this exclusively for
+     * neighbours the membership stamp has already confirmed are members.
+     *
+     * Dense rather than a `Map` because the keys are dense face-graph vertices to begin with, and
+     * because a `Map` cannot answer this question at all past 2^24 entries — the leaf cut runs over
+     * every face of the mesh at once, so a mesh of more than 16.7M triangles in one connected
+     * component would otherwise stop the builder dead.
+     * @type {Uint32Array}
+     */
+    member_index: Uint32Array;
+    /**
+     * How many distinct mesh vertices a set of dense face-graph vertices touches.
+     *
+     * @param {number[]|Int32Array} members dense face-graph vertices
+     * @returns {number}
+     */
+    count_unique_vertices(members: number[] | Int32Array): number;
+}
+//# sourceMappingURL=VGeoFaceGraph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoFaceGraph.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/partition/VGeoFaceGraph.js"],"names":[],"mappings":"AAcA;IA4CI;;;OAGG;IACH,uEAMC;IArDD;;OAEG;IACH,qBAAY;IAEZ;;;OAGG;IACH,kBAAa;IAEb;;;OAGG;IACH,iBAFU,WAAW,CAEE;IAEvB;;;OAGG;IACH,cAFU,UAAU,CAEA;IAEpB;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;;;;OAWG;IACH,cAFU,WAAW,CAED;IAcpB;;;;;OAKG;IACH,+BAHW,MAAM,EAAE,GAAC,UAAU,GACjB,MAAM,CA2BlB;CACJ"}

package/src/shade/renderer/geometry/virtual/build/{VGeoFaceGraph.js → partition/VGeoFaceGraph.js}

@@ -1,6 +1,6 @@
 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";
 
 /**
  * A face-adjacency graph together with the mesh it came from, kept so that repeated splits over the

package/src/shade/renderer/geometry/virtual/build/partition/vgeo_graph_components.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Not re-entrant: one call's stamps are live until it returns, and it neither yields nor calls back
+ * into itself.
+ *
+ * @param {Uint32Array} edge_addresses CSR row pointers
+ * @param {Uint32Array} adjacency CSR column indices
+ * @param {number[]} members vertices of the subgraph
+ * @param {Int32Array} membership one entry per graph vertex; an entry equal to `token` marks a
+ *     member. The caller stamps it, so nested calls over shrinking sets stay correct.
+ * @param {number} token
+ * @returns {number[][]} components, each ascending, ordered by their lowest member
+ */
+export function vgeo_graph_components(edge_addresses: Uint32Array, adjacency: Uint32Array, members: number[], membership: Int32Array, token: number): number[][];
+//# sourceMappingURL=vgeo_graph_components.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_graph_components.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/partition/vgeo_graph_components.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;GAWG;AACH,sDARW,WAAW,aACX,WAAW,WACX,MAAM,EAAE,cACR,UAAU,SAEV,MAAM,GACJ,MAAM,EAAE,EAAE,CAmEtB"}