@woosh/meep-engine 3.27.0 → 3.28.0

package/src/shade/renderer/geometry/virtual/build/{vgeo_build_levels.js → level/vgeo_build_levels.js}

@@ -1,45 +1,45 @@
-import { assert } from "../../../../../core/assert.js";
-import { aabb3_from_v3_array } from "../../../../../core/geom/3d/aabb/aabb3_from_v3_array.js";
-import { v3_morton_encode_bounded } from "../../../../../core/geom/3d/morton/v3_morton_encode_bounded.js";
-import { Quadric3 } from "../../../../../core/geom/3d/quadric/Quadric3.js";
+import { assert } from "../../../../../../core/assert.js";
+import { aabb3_from_v3_array } from "../../../../../../core/geom/3d/aabb/aabb3_from_v3_array.js";
+import { v3_morton_encode_bounded } from "../../../../../../core/geom/3d/morton/v3_morton_encode_bounded.js";
+import { Quadric3 } from "../../../../../../core/geom/3d/quadric/Quadric3.js";
 import {
     sphere_compute_bounding_of_2_spheres
-} from "../../../../../core/geom/3d/sphere/sphere_compute_bounding_of_2_spheres.js";
-import { BinaryTopology, NULL_POINTER, } from "../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+} from "../../../../../../core/geom/3d/sphere/sphere_compute_bounding_of_2_spheres.js";
+import { BinaryTopology, NULL_POINTER, } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 import {
     bt_mesh_compute_vertex_quadrics
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadrics.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadrics.js";
 import {
     bt_mesh_from_indexed_geometry
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
 import {
     bt_mesh_simplify_with_quadrics
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js";
-import { bt_edge_get } from "../../../../../core/geom/3d/topology/struct/binary/query/bt_edge_get.js";
-import { bt_mesh_validate } from "../../../../../core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js";
-import { bt_mesh_build_face_graph } from "../../../../../core/graph/metis/bt_mesh_build_face_graph.js";
-import { vgeo_encode_cluster_payload } from "../format/payload/vgeo_encode_cluster_payload.js";
-import { vgeo_layers_copy_vertex } from "../format/attribute/vgeo_layers_copy_vertex.js";
-import { vgeo_layers_like } from "../format/attribute/vgeo_layers_like.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 { VGEO_MAX_GROUP_CLUSTER_COUNT } from "../format/page/VGEO_MAX_GROUP_CLUSTER_COUNT.js";
-import { VirtualGeometryCluster } from "../format/dag/VirtualGeometryCluster.js";
-import { VirtualGeometryGroup } from "../format/dag/VirtualGeometryGroup.js";
-import { vgeo_bounding_sphere } from "./vgeo_bounding_sphere.js";
-import { vgeo_compute_vertex_normals } from "./vgeo_compute_vertex_normals.js";
-import { vgeo_compute_vertex_tangents } from "./vgeo_compute_vertex_tangents.js";
-import { vgeo_containing_sphere } from "./vgeo_containing_sphere.js";
-import { vgeo_extract_submesh } from "./vgeo_extract_submesh.js";
-import { vgeo_gather_faces } from "./vgeo_gather_faces.js";
-import { vgeo_graph_components } from "./vgeo_graph_components.js";
-import { vgeo_narrow_indices } from "./vgeo_narrow_indices.js";
-import { vgeo_partition_graph } from "./vgeo_partition_graph.js";
-import { vgeo_split_face_set } from "./vgeo_split_face_set.js";
-import { vgeo_split_face_set_packed } from "./vgeo_split_face_set_packed.js";
-import { VGeoFaceGraph } from "./VGeoFaceGraph.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js";
+import { bt_edge_get } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_edge_get.js";
+import { bt_mesh_validate } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js";
+import { bt_mesh_build_face_graph } from "../../../../../../core/graph/metis/bt_mesh_build_face_graph.js";
+import { vgeo_encode_cluster_payload } from "../../format/payload/vgeo_encode_cluster_payload.js";
+import { vgeo_layers_copy_vertex } from "../../format/attribute/vgeo_layers_copy_vertex.js";
+import { vgeo_layers_like } from "../../format/attribute/vgeo_layers_like.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 { VGEO_MAX_GROUP_CLUSTER_COUNT } from "../../format/page/VGEO_MAX_GROUP_CLUSTER_COUNT.js";
+import { VirtualGeometryCluster } from "../../format/dag/VirtualGeometryCluster.js";
+import { VirtualGeometryGroup } from "../../format/dag/VirtualGeometryGroup.js";
+import { vgeo_bounding_sphere } from "../sphere/vgeo_bounding_sphere.js";
+import { vgeo_compute_vertex_normals } from "../mesh/vgeo_compute_vertex_normals.js";
+import { vgeo_compute_vertex_tangents } from "../mesh/vgeo_compute_vertex_tangents.js";
+import { vgeo_containing_sphere } from "../sphere/vgeo_containing_sphere.js";
+import { vgeo_extract_submesh } from "../submesh/vgeo_extract_submesh.js";
+import { vgeo_gather_faces } from "../submesh/vgeo_gather_faces.js";
+import { vgeo_graph_components } from "../partition/vgeo_graph_components.js";
+import { vgeo_narrow_indices } from "../submesh/vgeo_narrow_indices.js";
+import { vgeo_partition_subgraph } from "../partition/vgeo_partition_subgraph.js";
+import { vgeo_split_face_set } from "../partition/vgeo_split_face_set.js";
+import { vgeo_split_face_set_packed } from "../partition/vgeo_split_face_set_packed.js";
+import { VGeoFaceGraph } from "../partition/VGeoFaceGraph.js";
 import { VGeoLevel } from "./VGeoLevel.js";
-import { VirtualGeometryMesh } from "./VirtualGeometryMesh.js";
+import { VirtualGeometryMesh } from "../mesh/VirtualGeometryMesh.js";
 
 /**
  * Build the cluster DAG: leaves out of the source mesh, then merge steps until one cluster is left.
@@ -434,30 +434,32 @@ function bundle_loose_clusters(frontier, loose, group_size) {
         return [];
     }
 
-    const bounds = new Float32Array([
-        Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY,
-        Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY,
-    ]);
+    // Gathered rather than read through the cluster list twice: the bounds and the codes are the
+    // same points, and this is the shape `vgeo_split_face_set_packed` already packs in.
+    const centres = new Float32Array(loose.length * 3);
 
-    for (const cluster of loose) {
-        const centre = frontier.clusters[cluster].bounds_sphere;
+    loose.forEach((cluster, index) => {
+        const sphere = frontier.clusters[cluster].bounds_sphere;
 
-        for (let axis = 0; axis < 3; axis++) {
-            bounds[axis] = Math.min(bounds[axis], centre[axis]);
-            bounds[axis + 3] = Math.max(bounds[axis + 3], centre[axis]);
-        }
-    }
+        centres[index * 3] = sphere[0];
+        centres[index * 3 + 1] = sphere[1];
+        centres[index * 3 + 2] = sphere[2];
+    });
+
+    const bounds = new Float32Array(6);
+
+    aabb3_from_v3_array(bounds, centres, centres.length);
 
     /**
      * @type {Map<number, number>}
      */
     const codes = new Map();
 
-    for (const cluster of loose) {
-        const centre = frontier.clusters[cluster].bounds_sphere;
-
-        codes.set(cluster, v3_morton_encode_bounded(centre[0], centre[1], centre[2], bounds));
-    }
+    loose.forEach((cluster, index) => {
+        codes.set(cluster, v3_morton_encode_bounded(
+            centres[index * 3], centres[index * 3 + 1], centres[index * 3 + 2], bounds
+        ));
+    });
 
     const order = loose.slice();
 
@@ -621,6 +623,14 @@ function absorb_singleton_pieces(pieces, cluster_graph) {
 function partition_into_groups(frontier, band, cluster_graph, group_size) {
     const membership = new Int32Array(frontier.clusters.length).fill(-1);
 
+    /**
+     * Dense rather than a `Map`, and hoisted out of the component loop so it is one allocation per
+     * level. See {@link vgeo_partition_subgraph} for why the density is load-bearing rather than a
+     * micro-optimisation.
+     * @type {Uint32Array}
+     */
+    const local_index = new Uint32Array(frontier.clusters.length);
+
     for (const cluster of band) {
         membership[cluster] = 0;
     }
@@ -692,55 +702,11 @@ function partition_into_groups(frontier, band, cluster_graph, group_size) {
             membership[cluster] = token;
         }
 
-        const local_index = new Map();
-
-        component.forEach((cluster, index) => local_index.set(cluster, index));
-
-        const local_addresses = new Uint32Array(component.length + 1);
-        const local_adjacency = [];
-        const local_weights = [];
-
-        component.forEach((cluster, index) => {
-            local_addresses[index] = local_adjacency.length;
-
-            for (let i = cluster_graph.edge_addresses[cluster]; i < cluster_graph.edge_addresses[cluster + 1]; i++) {
-                const other = cluster_graph.adjacency[i];
-
-                if (membership[other] !== token) {
-                    continue;
-                }
-
-                local_adjacency.push(local_index.get(other));
-                local_weights.push(cluster_graph.edge_weights[i]);
-            }
-        });
-
-        local_addresses[component.length] = local_adjacency.length;
-
-        const assignment = vgeo_partition_graph(
-            component.length,
-            part_count,
-            local_addresses,
-            Uint32Array.from(local_adjacency),
-            Float32Array.from(local_weights),
-            GROUP_SEED
+        const parts = vgeo_partition_subgraph(
+            cluster_graph, component, membership, token, part_count, GROUP_SEED, local_index
         );
 
-        const parts = [];
-
-        for (let i = 0; i < part_count; i++) {
-            parts.push([]);
-        }
-
-        component.forEach((cluster, index) => {
-            parts[assignment[index]].push(cluster);
-        });
-
         for (const part of parts) {
-            if (part.length === 0) {
-                continue;
-            }
-
             token++;
 
             for (const cluster of part) {

package/src/shade/renderer/geometry/virtual/build/level/vgeo_build_root_group.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The root cluster has no simplification step above it, so nothing grouped it, and the format still
+ * wants every cluster in exactly one group. It gets a group of its own: the always-selectable entry
+ * point the runtime starts its cut from.
+ *
+ * There is exactly one of these because the DAG has exactly one root — a build that ends with
+ * several parentless clusters has not finished, and bundling them into a synthetic group would only
+ * hide that (see `vgeo_build_levels`).
+ *
+ * @param {VirtualGeometryCluster} cluster the root
+ * @param {number} level
+ * @returns {VirtualGeometryGroup}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_build_root_group(cluster: VirtualGeometryCluster, level: number): VirtualGeometryGroup;
+import { VirtualGeometryGroup } from "../../format/dag/VirtualGeometryGroup.js";
+//# sourceMappingURL=vgeo_build_root_group.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_build_root_group.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_build_root_group.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,8EANW,MAAM,GACJ,oBAAoB,CAYhC;qCAzBoC,0CAA0C"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_build_root_group.js → level/vgeo_build_root_group.js}

@@ -1,4 +1,4 @@
-import { VirtualGeometryGroup } from "../format/dag/VirtualGeometryGroup.js";
+import { VirtualGeometryGroup } from "../../format/dag/VirtualGeometryGroup.js";
 
 /**
  * The root cluster has no simplification step above it, so nothing grouped it, and the format still

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,12 +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 { 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 { 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";
 

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.