@woosh/meep-engine 3.0.2 → 3.2.0

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

@@ -1,1786 +1,1786 @@
-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";
-import {
-    bt_mesh_compute_vertex_quadrics
-} 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";
-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";
-import { VGeoLevel } from "./VGeoLevel.js";
-import { VirtualGeometryMesh } from "./VirtualGeometryMesh.js";
-
-/**
- * Build the cluster DAG: leaves out of the source mesh, then merge steps until one cluster is left.
- *
- * The unit of work is a **round**, not a level sweep. A round holds a *frontier* — every cluster that
- * nothing has merged yet — selects a band of it by error, groups the band, locks every vertex the
- * group shares with anything outside it, halves the group's interior, and re-cuts the result into
- * new clusters, which become the parents of every cluster in the group. Locked perimeters plus a
- * group-uniform metric is the whole reason independent per-cluster LOD decisions come out
- * crack-free.
- *
- * **The band is why this is not a level sweep.** Sweeping whole levels pushes every cluster up one
- * step per level whatever its error, so a region that is nearly exact is coarsened in lockstep with
- * one that is not, and a level ends up spanning an order of magnitude of error. The cut the runtime
- * takes is a threshold on error, so a level that spans an order of magnitude is a page band that
- * spans one too: installing it brings clusters the cut does not want, and the ones it does want are
- * scattered across bands. Selecting the lowest-error band instead lets a fine region catch up before
- * the coarse one moves, and bands come out error-uniform. On geometry whose error is already uniform
- * the band is the whole frontier and this degenerates to the sweep, which is the correct behaviour
- * for that case rather than a special case for it.
- *
- * **A cluster the round cannot use simply stays.** It is not pushed up for the sake of symmetry, and
- * it does not stall the round for anyone else — which is what lets a lone island wait, untouched and
- * at zero error, until the geometry it will eventually merge with has come down to meet it.
- *
- * **Error is conformance to the source, not a sum of steps.** Vertex quadrics are built once, from
- * the source triangles, and carried through every round: a survivor absorbs its victim's quadric at
- * every collapse, so a vertex twelve rounds up still holds the planes of every source triangle
- * folded into it. Evaluating that at its current position measures the deviation from what the
- * artist authored, directly, and normalizing by the quadric's accumulated weight makes it an
- * object-space length rather than a cost whose scale depends on how many planes it happens to hold.
- * That length is what the runtime projects into pixels.
- *
- * **Termination is convergence to one root, not a stall.** Groups bundle across connected components
- * once connectivity runs out, and a group small enough to fit one cluster is merged losslessly, so a
- * frontier of separate islands still comes together. A build that cannot reach a single root throws:
- * the runtime starts its cut at the root, and "several roots" is not a shape it can start from.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * Fixed so that the same frontier always groups the same way.
- * @readonly
- * @type {number}
- */
-const GROUP_SEED = 0x6D05;
-
-const scratch_sphere = new Float32Array(4);
-
-/**
- * Every cluster nothing has merged yet, and the geometry they currently stand for.
- *
- * One mesh holds the whole frontier so that a group can be extracted with its surroundings intact —
- * the lock set is "every vertex a face outside this group touches", and that question has no answer
- * in a mesh that holds the group alone.
- */
-class VGeoFrontier {
-    /**
-     * @type {VirtualGeometryMesh}
-     */
-    mesh = null;
-
-    /**
-     * @type {VirtualGeometryCluster[]}
-     */
-    clusters = [];
-
-    /**
-     * `cluster_faces[i]` are the faces of {@link mesh} that cluster `i` owns.
-     * @type {number[][]}
-     */
-    cluster_faces = [];
-
-    /**
-     * One accumulated quadric per vertex of {@link mesh}, carried unbroken from the source mesh.
-     *
-     * This is what makes the error mean "how far this is from the geometry the artist authored"
-     * rather than "how far this is from the frontier it was simplified out of". A survivor absorbs
-     * its victim's quadric at every collapse, at every round, so a vertex twelve rounds up still
-     * carries the planes of every source triangle that was ever folded into it, and evaluating its
-     * quadric at its current position measures the deviation from the source directly. Composing
-     * per-round residuals instead only *bounds* that, by the triangle inequality, and the bound
-     * loosens with every round: measured on a unit sphere, the same ninety-triangle root read 0.36
-     * built from 3k source triangles and 13.3 built from 24k, where it is the same approximation and
-     * reads 0.0315 either way once the quadrics are carried.
-     *
-     * @type {Quadric3[]}
-     */
-    quadrics = [];
-}
-
-/**
- * Everything one group step produced, before it is committed. Kept separate so that a round which
- * fails to make progress can be discarded without having mutated the frontier.
- */
-class GroupStep {
-    /**
-     * The frontier clusters this group holds.
-     * @type {VirtualGeometryCluster[]}
-     */
-    child_clusters = [];
-
-    /**
-     * @type {VirtualGeometryCluster[]}
-     */
-    parent_clusters = [];
-
-    /**
-     * Parallel to {@link parent_clusters}: the geometry each parent was cut from, in terms of the
-     * frontier, so the next frontier can be stitched back together.
-     * @type {VGeoContribution[]}
-     */
-    parent_geometry = [];
-
-    /**
-     * The value both sides of this step store: the object-space distance from the *source* surface
-     * that this step's geometry now stands at, floored by what its children already carried.
-     * @type {number}
-     */
-    error = 0;
-
-    /**
-     * `frontier vertex id -> that vertex's quadric after this step`, for every vertex that survived
-     * it. Held rather than written straight back because a step is speculative until the round
-     * accepts it, and because two steps sharing a pinned boundary vertex must have their gains
-     * combined rather than one overwriting the other.
-     * @type {Map<number, Quadric3>}
-     */
-    quadrics = new Map();
-
-    /**
-     * The LOD-metric sphere both sides of this step store.
-     * @type {Float32Array}
-     */
-    sphere = new Float32Array(4);
-}
-
-/**
- * Several leaves re-cut into one, with nothing simplified — see {@link build_repack}.
- */
-class GroupRepack {
-    /**
-     * The leaves this removes from the DAG.
-     * @type {VirtualGeometryCluster[]}
-     */
-    replaced = [];
-
-    /**
-     * The leaves that take their place -- always fewer.
-     * @type {VirtualGeometryCluster[]}
-     */
-    clusters = [];
-
-    /**
-     * Parallel to {@link clusters}.
-     * @type {VGeoContribution[]}
-     */
-    geometry = [];
-}
-
-/**
- * One cluster's geometry expressed against the frontier it came out of, which is what lets the next
- * frontier be stitched from a mixture of freshly simplified clusters and untouched ones.
- *
- * @typedef {object} VGeoContribution
- * @property {Float32Array} positions
- * @property {Uint32Array} indices local to {@link positions}
- * @property {Uint32Array} local_vertex_ids ids in the mesh {@link topology} belongs to
- * @property {Uint32Array} source_vertex_ids the same vertices, named in the frontier's mesh
- * @property {BinaryTopology} topology the mesh {@link local_vertex_ids} name vertices of, whose
- *     vertex data block holds their attributes
- */
-
-/**
- * Encode a gathered face set into a cluster record.
- *
- * @param {VGeoGatheredFaces} gathered already within both meshlet caps
- * @param {number} level
- * @param {(BinaryDataLayer|null)[]} layers of the mesh it was gathered from
- * @returns {VirtualGeometryCluster}
- */
-function cluster_from_gathered(gathered, level, layers) {
-    const payload = vgeo_encode_cluster_payload(
-        gathered.positions,
-        vgeo_narrow_indices(gathered),
-        gathered.vertex_ids,
-        layers
-    );
-
-    const cluster = new VirtualGeometryCluster();
-
-    cluster.level = level;
-    cluster.vertex_count = gathered.vertex_ids.length;
-    cluster.triangle_count = gathered.indices.length / 3;
-    cluster.encoding_flags = payload.encoding_flags;
-    cluster.payload = payload.bytes;
-    cluster.bounds_sphere = vgeo_bounding_sphere(gathered.positions);
-
-    // the box needs no inflation, unlike the sphere above: the extremes are float32 values already,
-    // so min and max of them are exactly representable and the stored box contains the stored
-    // points by construction
-    aabb3_from_v3_array(cluster.aabb, gathered.positions, gathered.positions.length);
-
-    return cluster;
-}
-
-/**
- * Build a cluster out of a face set: gather it, bound it, encode its payload.
- *
- * @param {VirtualGeometryMesh} mesh
- * @param {number[]} face_ids
- * @param {number} level
- * @returns {{cluster: VirtualGeometryCluster, gathered: VGeoGatheredFaces}}
- */
-function build_cluster(mesh, face_ids, level) {
-    const gathered = vgeo_gather_faces(mesh, face_ids);
-
-    return { cluster: cluster_from_gathered(gathered, level, mesh.layers), gathered };
-}
-
-/**
- * Cut a mesh into leaf clusters — the frontier every round starts from.
- *
- * @param {VirtualGeometryMesh} mesh
- * @returns {VGeoFrontier}
- */
-function build_leaf_frontier(mesh) {
-    const face_graph = new VGeoFaceGraph(mesh.topology, bt_mesh_build_face_graph(mesh.topology));
-
-    const all = [];
-
-    for (let vertex = 0; vertex < face_graph.graph.vertex_count; vertex++) {
-        all.push(vertex);
-    }
-
-    const parts = vgeo_split_face_set(
-        face_graph, all, VGEO_MAX_CLUSTER_TRIANGLE_COUNT, VGEO_MAX_CLUSTER_VERTEX_COUNT
-    );
-
-    const frontier = new VGeoFrontier();
-
-    frontier.mesh = mesh;
-
-    // Built once, here, from the source triangles. Nothing rebuilds them afterwards — every later
-    // round inherits these and adds to them, which is the whole point.
-    frontier.quadrics = bt_mesh_compute_vertex_quadrics(mesh.topology);
-
-    for (const part of parts) {
-        const face_ids = part.map((dense) => face_graph.vertex_face_ids[dense]);
-
-        face_ids.sort((a, b) => a - b);
-
-        const built = build_cluster(mesh, face_ids, 0);
-
-        // A leaf's own bounds are its LOD-metric sphere, and it deviates from nothing.
-        built.cluster.self_sphere = built.cluster.bounds_sphere.slice();
-        built.cluster.self_error = 0;
-
-        frontier.clusters.push(built.cluster);
-        frontier.cluster_faces.push(face_ids);
-    }
-
-    return frontier;
-}
-
-/**
- * How much of the space two clusters would waste by being merged, as a factor in `(0, 1]`.
- *
- * The ratio of what they occupy separately to what the sphere containing both would occupy. Two
- * clusters side by side score near one; two clusters at opposite ends of the model score near zero,
- * because the sphere over both is mostly empty. Scale-free by construction — it compares a volume
- * to a volume, so it needs no notion of how big the model is or how far apart "far" is, which is
- * exactly what a distance threshold would have needed and could never have been given.
- *
- * The group's sphere is what the runtime projects to decide the whole group's fate, so a group
- * spread across empty space is one that gets refined from much further away than its geometry
- * warrants. Cutting edge weight by this steers the partitioner away from those merges without ever
- * forbidding one — when nothing better is available, a poor merge is still better than none.
- *
- * @param {Float32Array} a bounding sphere, centre then radius
- * @param {Float32Array} b
- * @returns {number}
- */
-function compactness(a, b) {
-    sphere_compute_bounding_of_2_spheres(scratch_sphere, a, b);
-
-    const merged = scratch_sphere[3];
-
-    if (merged <= 0) {
-        return 1;
-    }
-
-    // Volumes, up to the common factor of 4/3 pi, which cancels.
-    const separate = a[3] * a[3] * a[3] + b[3] * b[3] * b[3];
-
-    return Math.min(1, separate / (merged * merged * merged));
-}
-
-/**
- * The cluster adjacency graph of a frontier: clusters are the vertices, shared mesh edges are the
- * edges, and an edge weighs as much boundary as the two clusters share, discounted by how much empty
- * space merging them would enclose.
- *
- * @param {VGeoFrontier} frontier
- * @param {VGeoFaceGraph} face_graph of `frontier.mesh`
- * @returns {{edge_addresses: Uint32Array, adjacency: Uint32Array, edge_weights: Float32Array}}
- */
-function build_cluster_graph(frontier, face_graph) {
-    const cluster_of_face = new Int32Array(frontier.mesh.topology.faces.size).fill(-1);
-
-    frontier.cluster_faces.forEach((face_ids, cluster) => {
-        for (const face of face_ids) {
-            cluster_of_face[face] = cluster;
-        }
-    });
-
-    const cluster_count = frontier.clusters.length;
-
-    /**
-     * `cluster -> (neighbour cluster -> shared boundary)`.
-     * @type {Map<number, number>[]}
-     */
-    const neighbours = [];
-
-    for (let i = 0; i < cluster_count; i++) {
-        neighbours.push(new Map());
-    }
-
-    const graph = face_graph.graph;
-
-    for (let vertex = 0; vertex < graph.vertex_count; vertex++) {
-        const cluster = cluster_of_face[face_graph.vertex_face_ids[vertex]];
-
-        for (let i = graph.edge_addresses[vertex]; i < graph.edge_addresses[vertex + 1]; i++) {
-            const other_cluster = cluster_of_face[face_graph.vertex_face_ids[graph.adjacency[i]]];
-
-            if (other_cluster === cluster) {
-                continue;
-            }
-
-            const bucket = neighbours[cluster];
-
-            bucket.set(other_cluster, (bucket.get(other_cluster) ?? 0) + graph.edge_weights[i]);
-        }
-    }
-
-    const edge_addresses = new Uint32Array(cluster_count + 1);
-    const adjacency = [];
-    const edge_weights = [];
-
-    for (let cluster = 0; cluster < cluster_count; cluster++) {
-        edge_addresses[cluster] = adjacency.length;
-
-        const entries = Array.from(neighbours[cluster].entries()).sort((a, b) => a[0] - b[0]);
-
-        for (const [other, weight] of entries) {
-            adjacency.push(other);
-
-            edge_weights.push(weight * compactness(
-                frontier.clusters[cluster].bounds_sphere, frontier.clusters[other].bounds_sphere
-            ));
-        }
-    }
-
-    edge_addresses[cluster_count] = adjacency.length;
-
-    return {
-        edge_addresses,
-        adjacency: Uint32Array.from(adjacency),
-        edge_weights: Float32Array.from(edge_weights),
-    };
-}
-
-/**
- * Bundle clusters that have no one to merge with along a Morton curve.
- *
- * A cluster alone in its connected component cannot be coarsened: halving its triangles leaves one
- * cluster where there was one cluster, and the DAG stands still. The only way it ever reaches a root
- * is bundled with geometry it shares no edge with, and the only thing left to choose them by is
- * where they are. That is a real cost — a cluster spanning two islands carries a sphere containing
- * both — which is why this is the fallback and adjacency is the rule.
- *
- * @param {VGeoFrontier} frontier
- * @param {number[]} loose cluster indices, each alone in its component
- * @param {number} group_size
- * @returns {number[][]} groups of at least two; a single leftover is returned to the frontier
- */
-function bundle_loose_clusters(frontier, loose, group_size) {
-    if (loose.length < 2) {
-        return [];
-    }
-
-    const bounds = new Float32Array([
-        Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY,
-        Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY,
-    ]);
-
-    for (const cluster of loose) {
-        const centre = 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]);
-        }
-    }
-
-    /**
-     * @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));
-    }
-
-    const order = loose.slice();
-
-    order.sort((a, b) => (codes.get(a) - codes.get(b)) || (a - b));
-
-    const result = [];
-
-    let bundle = [];
-    let triangles = 0;
-    let vertices = 0;
-    let packable = true;
-
-    for (const index of order) {
-        const cluster = frontier.clusters[index];
-
-        // Leaves small enough to end up in one cluster between them are worth bundling past the
-        // group size: what happens to them is a re-cut at no error, not a simplification, so a
-        // bigger bundle costs nothing in fidelity and is the difference between a scene of small
-        // parts filling its clusters and running them at a tenth of capacity. Anything else stops at
-        // the group size, where the size is a real trade against LOD lockstep.
-        const packs = packable
-            && cluster.child_group === undefined
-            && triangles + cluster.triangle_count <= VGEO_MAX_CLUSTER_TRIANGLE_COUNT
-            && vertices + cluster.vertex_count <= VGEO_MAX_CLUSTER_VERTEX_COUNT;
-
-        if (bundle.length >= group_size && !packs) {
-            result.push(bundle);
-
-            bundle = [];
-            triangles = 0;
-            vertices = 0;
-            packable = true;
-        }
-
-        bundle.push(index);
-
-        triangles += cluster.triangle_count;
-        vertices += cluster.vertex_count;
-
-        packable = packable && cluster.child_group === undefined;
-    }
-
-    if (bundle.length === 1 && result.length > 0) {
-        // A bundle of one merges nothing. Handing it to the bundle before it costs one cluster of
-        // spatial spread and is the difference between the frontier shrinking and it standing still.
-        result[result.length - 1].push(bundle[0]);
-    } else if (bundle.length > 1) {
-        result.push(bundle);
-    }
-
-    return result.filter((group) => group.length >= 2);
-}
-
-/**
- * Fold every one-cluster piece into the adjacent piece it shares the most boundary with.
- *
- * The partitioner produces these constantly — it optimizes cut, not contiguity, so splitting its
- * parts into connected pieces routinely leaves a cluster standing on its own. Such a cluster is not
- * out of options, though: it sits inside a component that has plenty of neighbours, and the right
- * answer is the nearest of them, not the proximity pool. Letting it fall through to the pool is how
- * a lone shell sixty metres away ends up merged with a fragment of something else entirely.
- *
- * One forward pass is enough. Folding only ever grows a piece and empties the one it came from, so
- * it cannot turn a piece of two into a piece of one — the singletons are exactly the ones present
- * when the pass starts, and a singleton that has already absorbed another is no longer one.
- *
- * @param {number[][]} pieces of a single connected component of the band, each non-empty; every
- *     cluster in a singleton piece therefore has a neighbour in some other piece here
- * @param {object} cluster_graph as {@link build_cluster_graph} returns
- * @returns {number[][]} non-empty pieces, with no singletons
- */
-function absorb_singleton_pieces(pieces, cluster_graph) {
-    if (pieces.length < 2) {
-        return pieces;
-    }
-
-    /**
-     * `cluster -> index of the piece holding it`.
-     * @type {Map<number, number>}
-     */
-    const piece_of = new Map();
-
-    const alive = pieces.map((piece) => piece.slice());
-
-    alive.forEach((piece, index) => {
-        for (const cluster of piece) {
-            piece_of.set(cluster, index);
-        }
-    });
-
-    for (let index = 0; index < alive.length; index++) {
-        if (alive[index].length !== 1) {
-            continue;
-        }
-
-        const cluster = alive[index][0];
-
-        /**
-         * `piece index -> boundary shared with this cluster`.
-         * @type {Map<number, number>}
-         */
-        const shared = new Map();
-
-        for (let i = cluster_graph.edge_addresses[cluster]; i < cluster_graph.edge_addresses[cluster + 1]; i++) {
-            const target = piece_of.get(cluster_graph.adjacency[i]);
-
-            if (target === undefined || target === index) {
-                continue;
-            }
-
-            shared.set(target, (shared.get(target) ?? 0) + cluster_graph.edge_weights[i]);
-        }
-
-        let best = -1;
-        let best_weight = -1;
-
-        // Sorted, so that two pieces sharing the same boundary length resolve the same way every
-        // time rather than however the adjacency happened to be walked.
-        for (const [target, weight] of Array.from(shared.entries()).sort((a, b) => a[0] - b[0])) {
-            if (weight > best_weight) {
-                best = target;
-                best_weight = weight;
-            }
-        }
-
-        assert.notEqual(
-            best, -1,
-            'a lone cluster inside a connected component must border another piece of it'
-        );
-
-        alive[best].push(cluster);
-        alive[best].sort((a, b) => a - b);
-
-        piece_of.set(cluster, best);
-
-        alive[index] = [];
-    }
-
-    return alive.filter((piece) => piece.length > 0);
-}
-
-/**
- * Partition a band of the frontier into groups of roughly `group_size`.
- *
- * The partition runs **inside each connected component** of the cluster graph, not across the band as
- * a whole. Partitioning globally and splitting the disconnected parts afterwards looks equivalent and
- * is not: a scene assembled from thousands of separate shells has a cluster graph in thousands of
- * pieces, and a balanced global partition draws each part from several of them, so the connectivity
- * split then shreds nearly every group down to a single cluster.
- *
- * What is left over after that — every cluster alone in its component — is bundled by proximity
- * instead, because for those clusters there is no adjacency left to respect and no other way to the
- * root.
- *
- * @param {VGeoFrontier} frontier
- * @param {number[]} band cluster indices this round may consume, ascending
- * @param {object} cluster_graph as {@link build_cluster_graph} returns
- * @param {number} group_size
- * @returns {number[][]} groups of at least two clusters each; clusters left out stay in the frontier
- */
-function partition_into_groups(frontier, band, cluster_graph, group_size) {
-    const membership = new Int32Array(frontier.clusters.length).fill(-1);
-
-    for (const cluster of band) {
-        membership[cluster] = 0;
-    }
-
-    const components = vgeo_graph_components(
-        cluster_graph.edge_addresses, cluster_graph.adjacency, band, membership, 0
-    );
-
-    const result = [];
-
-    /**
-     * Clusters with nobody adjacent to merge with.
-     * @type {number[]}
-     */
-    const loose = [];
-
-    let token = 0;
-
-    /**
-     * @param {number[]} piece
-     */
-    function accept(piece) {
-        if (piece.length < 2) {
-            loose.push(piece[0]);
-
-            return;
-        }
-
-        // The format caps a group at 4096 clusters. Nothing the size policy produces comes near it,
-        // but the cap is hard, so the chunking is here rather than assumed away.
-        for (let start = 0; start < piece.length; start += VGEO_MAX_GROUP_CLUSTER_COUNT) {
-            const chunk = piece.slice(start, start + VGEO_MAX_GROUP_CLUSTER_COUNT);
-
-            if (chunk.length < 2) {
-                loose.push(chunk[0]);
-
-                continue;
-            }
-
-            result.push(chunk);
-        }
-    }
-
-    for (const component of components) {
-        if (component.length < 2) {
-            // Alone in its component: no adjacency left anywhere, so proximity is the only rule that
-            // can still place it.
-            loose.push(component[0]);
-
-            continue;
-        }
-
-        if (component.length <= group_size) {
-            accept(component);
-
-            continue;
-        }
-
-        /**
-         * @type {number[][]}
-         */
-        const pieces = [];
-
-        const part_count = Math.ceil(component.length / group_size);
-
-        token++;
-
-        for (const cluster of component) {
-            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 = [];
-
-        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) {
-                membership[cluster] = token;
-            }
-
-            for (const piece of vgeo_graph_components(
-                cluster_graph.edge_addresses, cluster_graph.adjacency, part, membership, token
-            )) {
-                pieces.push(piece);
-            }
-        }
-
-        for (const piece of absorb_singleton_pieces(pieces, cluster_graph)) {
-            accept(piece);
-        }
-    }
-
-    for (const bundle of bundle_loose_clusters(frontier, loose, group_size)) {
-        result.push(bundle);
-    }
-
-    result.sort((a, b) => a[0] - b[0]);
-
-    return result;
-}
-
-/**
- * Does any face outside this group use the edge?
- *
- * @param {BinaryTopology} topology
- * @param {number} edge
- * @param {Int32Array} group_of_face
- * @param {number} group_index
- * @returns {boolean}
- */
-function edge_touches_outside(topology, edge, group_of_face, group_index) {
-    const first_loop = topology.edge_read_loop(edge);
-
-    if (first_loop === NULL_POINTER) {
-        return false;
-    }
-
-    let loop = first_loop;
-
-    do {
-        const face = topology.loop_read_face(loop);
-
-        if (face !== NULL_POINTER && group_of_face[face] !== group_index) {
-            return true;
-        }
-
-        loop = topology.loop_read_radial_next(loop);
-    } while (loop !== first_loop && loop !== NULL_POINTER);
-
-    return false;
-}
-
-/**
- * Does any face outside this group use the vertex? Walks the vertex's disk cycle and each edge's
- * radial cycle, so the answer is local to the vertex rather than a scan of the frontier.
- *
- * @param {BinaryTopology} topology
- * @param {number} vertex
- * @param {Int32Array} group_of_face
- * @param {number} group_index
- * @returns {boolean}
- */
-function vertex_touches_outside(topology, vertex, group_of_face, group_index) {
-    const first_edge = topology.vertex_read_edge(vertex);
-
-    if (first_edge === NULL_POINTER) {
-        return false;
-    }
-
-    let edge = first_edge;
-
-    do {
-        if (edge_touches_outside(topology, edge, group_of_face, group_index)) {
-            return true;
-        }
-
-        edge = (topology.edge_read_vertex1(edge) === vertex)
-            ? topology.edge_read_v1_disk_next(edge)
-            : topology.edge_read_v2_disk_next(edge);
-    } while (edge !== first_edge && edge !== NULL_POINTER);
-
-    return false;
-}
-
-/**
- * Which vertices a group must not move, and which boundary edges must survive its simplification.
- *
- * A vertex is locked when any face outside the group touches it — not merely when it sits on a
- * shared *edge*. The weaker rule leaks: two groups can meet at a single non-manifold vertex with no
- * edge between them, and each would then move that vertex somewhere else, tearing the surface at a
- * point no boundary walk would have flagged.
- *
- * "Outside" includes frontier clusters this round left alone, which is what keeps a band's seam with
- * the rest of the frontier from opening.
- *
- * @param {BinaryTopology} topology
- * @param {number[]} group_face_ids
- * @param {Int32Array} group_of_face one entry per face slot, holding the group each face belongs to
- * @param {number} group_index
- * @returns {{locked: Set<number>, polyline: number[][]}} locked vertex ids, and the `[v1, v2]` pairs
- *     of every edge this group shares with the outside
- */
-function compute_group_boundary(topology, group_face_ids, group_of_face, group_index) {
-    const vertices = new Set();
-    const edges = new Set();
-
-    for (const face of group_face_ids) {
-        const first_loop = topology.face_read_loop(face);
-
-        let loop = first_loop;
-
-        do {
-            vertices.add(topology.loop_read_vertex(loop));
-            edges.add(topology.loop_read_edge(loop));
-
-            loop = topology.loop_read_next(loop);
-        } while (loop !== first_loop);
-    }
-
-    const locked = new Set();
-
-    for (const vertex of vertices) {
-        if (vertex_touches_outside(topology, vertex, group_of_face, group_index)) {
-            locked.add(vertex);
-        }
-    }
-
-    const polyline = [];
-
-    for (const edge of edges) {
-        if (!edge_touches_outside(topology, edge, group_of_face, group_index)) {
-            continue;
-        }
-
-        polyline.push([topology.edge_read_vertex1(edge), topology.edge_read_vertex2(edge)]);
-    }
-
-    return { locked, polyline };
-}
-
-/**
- * Largest error any of a group's clusters carries -- the floor a step above them must respect.
- *
- * @param {VirtualGeometryCluster[]} clusters
- * @returns {number}
- */
-function max_child_error(clusters) {
-    let result = 0;
-
-    for (const cluster of clusters) {
-        result = Math.max(result, cluster.self_error);
-    }
-
-    return result;
-}
-
-/**
- * Leaves with room to spare between them, re-cut into fewer and fuller leaves.
- *
- * This is not a level of the DAG and must not become one. Nothing is simplified, so the new clusters
- * carry the same error their inputs did -- zero -- and a step whose parent error equals its child
- * error is a step the cut rule can never take: a cluster is drawn only while `project(parent) > tau`,
- * and a parent at zero error projects to zero unconditionally. The leaves under it would be stored,
- * paged, and never once selected. So the re-cut *replaces* them; they were a way of cutting this
- * geometry up, and now there is a better one.
- *
- * It is what makes a scene of small separate parts tractable. A thousand twelve-triangle bolts are a
- * thousand clusters at eight per cent fill, and no simplification is what they need -- they need to
- * be cut up differently. Repacking is bounded by the grouping that proposed it, so what lands in one
- * cluster is what the adjacency and proximity rules already judged to belong together.
- *
- * Only leaves. Above them the same re-cut would orphan a subtree, since a coarser cluster cannot be
- * deleted -- something hangs off it.
- *
- * @param {VGeoFrontier} frontier
- * @param {number[]} group_clusters cluster indices
- * @param {number} parent_target how many clusters the group is aiming to become
- * @returns {GroupRepack|undefined} `undefined` when the group must be simplified instead
- */
-function try_repack(frontier, group_clusters, parent_target) {
-    const face_ids = [];
-
-    for (const cluster of group_clusters) {
-        if (frontier.clusters[cluster].child_group !== undefined) {
-            return undefined;
-        }
-
-        for (const face of frontier.cluster_faces[cluster]) {
-            face_ids.push(face);
-        }
-    }
-
-    // Only when the target is already met -- there is nothing to simplify, so the reduction has to
-    // come from re-cutting. A group over its target has real geometry to lose and belongs on the
-    // simplification path.
-    if (face_ids.length > parent_target * VGEO_MAX_CLUSTER_TRIANGLE_COUNT) {
-        return undefined;
-    }
-
-    face_ids.sort((a, b) => a - b);
-
-    const submesh = vgeo_extract_submesh(frontier.mesh, face_ids);
-
-    const face_graph = new VGeoFaceGraph(
-        submesh.mesh.topology, bt_mesh_build_face_graph(submesh.mesh.topology)
-    );
-
-    /**
-     *
-     * @type {number[]}
-     */
-    const all = [];
-
-    const vertex_count = face_graph.graph.vertex_count;
-    for (let vertex = 0; vertex < vertex_count; vertex++) {
-        all.push(vertex);
-    }
-
-    const parts = vgeo_split_face_set_packed(
-        face_graph, all, VGEO_MAX_CLUSTER_TRIANGLE_COUNT, VGEO_MAX_CLUSTER_VERTEX_COUNT
-    );
-
-    if (parts.length >= group_clusters.length) {
-        // The vertex ceiling bit before the triangle one, and re-cutting bought nothing.
-        return undefined;
-    }
-
-    const repack = new GroupRepack();
-
-    repack.replaced = group_clusters.map((cluster) => frontier.clusters[cluster]);
-
-    for (const part of parts) {
-        const part_face_ids = part.map((dense) => face_graph.vertex_face_ids[dense]);
-
-        part_face_ids.sort((a, b) => a - b);
-
-        const built = build_cluster(submesh.mesh, part_face_ids, 0);
-
-        // A leaf's own bounds are its LOD-metric sphere, and it deviates from nothing.
-        built.cluster.self_sphere = built.cluster.bounds_sphere.slice();
-        built.cluster.self_error = 0;
-
-        repack.clusters.push(built.cluster);
-
-        repack.geometry.push({
-            positions: built.gathered.positions,
-            indices: built.gathered.indices,
-            local_vertex_ids: built.gathered.vertex_ids,
-            source_vertex_ids: Uint32Array.from(
-                built.gathered.vertex_ids, (local) => submesh.source_vertex_ids[local]
-            ),
-            topology: submesh.mesh.topology,
-        });
-    }
-
-    return repack;
-}
-
-/**
- * Simplify one group and cut the result into the parent clusters of every cluster in it.
- *
- * @param {VGeoFrontier} frontier
- * @param {number[]} group_clusters cluster indices
- * @param {Int32Array} group_of_face one entry per face slot, holding the group each face belongs to
- * @param {number} group_index
- * @param {number} level of the parents this step produces
- * @param {VGeoLevelOptions} options
- * @returns {GroupStep|undefined} `undefined` when the group has no coarser form at all, and the
- *     round should leave its clusters alone
- */
-function build_group_step(frontier, group_clusters, group_of_face, group_index, level, options) {
-    /**
-     *
-     * @type {number[]}
-     */
-    const face_ids = [];
-
-    for (const cluster of group_clusters) {
-        for (const face of frontier.cluster_faces[cluster]) {
-            face_ids.push(face);
-        }
-    }
-
-    face_ids.sort((a, b) => a - b);
-
-    const child_clusters = group_clusters.map((cluster) => frontier.clusters[cluster]);
-
-    const boundary = compute_group_boundary(
-        frontier.mesh.topology, face_ids, group_of_face, group_index
-    );
-
-    /**
-     * Extract the group, simplify it to `target_face_count`, and cut the result into clusters.
-     *
-     * @param {number} target_face_count
-     * @returns {{submesh: VGeoSubmesh, face_graph: VGeoFaceGraph, parts: number[][],
-     *     quadrics: Quadric3[], error: number}}
-     */
-    function simplify_to(target_face_count) {
-        const submesh = vgeo_extract_submesh(frontier.mesh, face_ids);
-
-        // Cloned, not borrowed: the simplifier mutates these, and this whole attempt may be thrown
-        // away — by the polyline check below, by the round rejecting it, or by a wider band being
-        // tried instead. The frontier's own quadrics must survive all of that untouched.
-        const submesh_source_vertex_ids = submesh.source_vertex_ids;
-        const source_vertex_id_count = submesh_source_vertex_ids.length;
-
-        /**
-         *
-         * @type {Quadric3[]}
-         */
-        const quadrics = new Array(source_vertex_id_count);
-
-        for (let i = 0; i < source_vertex_id_count; i++) {
-            const source = submesh_source_vertex_ids[i];
-            quadrics[i] = frontier.quadrics[source].clone();
-        }
-
-        /**
-         * `source vertex id -> submesh local id`, for translating the lock set and the polyline.
-         * @type {Map<number, number>}
-         */
-        const local_of_source = new Map();
-
-        for (let local = 0; local < source_vertex_id_count; local++) {
-            const source = submesh_source_vertex_ids[local];
-            local_of_source.set(source, local);
-        }
-
-        /**
-         *
-         * @type {Set<number>}
-         */
-        const locked = new Set();
-
-        for (const vertex of boundary.locked) {
-            const local = local_of_source.get(vertex);
-
-            if (local !== undefined) {
-                locked.add(local);
-            }
-        }
-
-        // The faces carrying the group's boundary edges. Locking the endpoints keeps them where they
-        // are; protecting these faces is what keeps an edge *between* two locked vertices from
-        // losing the only face that holds it — see the polyline check below, which is the same
-        // guarantee stated as an assertion.
-
-        /**
-         *
-         * @type {Set<number>}
-         */
-        const protected_faces = new Set();
-
-        for (const [v1, v2] of boundary.polyline) {
-            const edge = bt_edge_get(
-                submesh.mesh.topology, local_of_source.get(v1), local_of_source.get(v2)
-            );
-
-            if (edge === NULL_POINTER) {
-                continue;
-            }
-
-            const first_loop = submesh.mesh.topology.edge_read_loop(edge);
-
-            let loop = first_loop;
-
-            do {
-                const face = submesh.mesh.topology.loop_read_face(loop);
-
-                if (face !== NULL_POINTER) {
-                    protected_faces.add(face);
-                }
-
-                loop = submesh.mesh.topology.loop_read_radial_next(loop);
-            } while (loop !== first_loop && loop !== NULL_POINTER);
-        }
-
-        // The simplifier measures this itself, and has to: a cluster consumed whole leaves a
-        // vertex behind that belongs to no face and is about to be swept away, and that vertex is
-        // the only thing still holding the quadric of what used to be there. Measuring survivors
-        // from out here would report a soup of separate triangles losing most of itself as free.
-        const deviation = bt_mesh_simplify_with_quadrics(
-            submesh.mesh.topology, target_face_count, locked, protected_faces, quadrics
-        );
-
-        const defects = bt_mesh_validate(submesh.mesh.topology);
-
-        if (defects.length > 0) {
-            throw new Error(
-                `simplifying a group of ${group_clusters.length} clusters left the mesh inconsistent: `
-                + defects.slice(0, 4).map((defect) => defect.detail).join('; ')
-            );
-        }
-
-        // The design asks for this explicitly: pinning a vertex does not by itself protect the
-        // *edges* between pinned vertices, and a face-kill path can strip one. A missing boundary
-        // edge is a crack between two groups that will never close, so the build stops here rather
-        // than shipping it.
-        for (const [v1, v2] of boundary.polyline) {
-            const local_1 = local_of_source.get(v1);
-            const local_2 = local_of_source.get(v2);
-
-            if (
-                local_1 === undefined
-                || local_2 === undefined
-                || bt_edge_get(submesh.mesh.topology, local_1, local_2) === NULL_POINTER
-            ) {
-                throw new Error(
-                    `group boundary edge (${v1}, ${v2}) did not survive simplification of a group of `
-                    + `${group_clusters.length} clusters`
-                );
-            }
-        }
-
-        /*
-         The step moved the geometry, so the frame that describes it has to move with it — but only
-         where the step was free to move anything. `locked` is the group's perimeter, the vertices
-         every neighbouring group also carries, and it is what a cut leans on to put two levels of
-         detail side by side without a crack. Derived here, a perimeter vertex would get the average
-         of this group's faces alone while its neighbour got the average of that group's, and the
-         seam that is watertight in geometry would show as a crease in shading.
-         */
-        vgeo_compute_vertex_normals(submesh.mesh, locked);
-        vgeo_compute_vertex_tangents(submesh.mesh, locked);
-
-        const face_graph = new VGeoFaceGraph(
-            submesh.mesh.topology, bt_mesh_build_face_graph(submesh.mesh.topology)
-        );
-
-        const all = [];
-
-        for (let vertex = 0; vertex < face_graph.graph.vertex_count; vertex++) {
-            all.push(vertex);
-        }
-
-        // Packed: this is a group, so its extent is already the group's, and one cluster per
-        // surviving island would undo the merge the group exists to make.
-        const parts = vgeo_split_face_set_packed(
-            face_graph, all, VGEO_MAX_CLUSTER_TRIANGLE_COUNT, VGEO_MAX_CLUSTER_VERTEX_COUNT
-        );
-
-        return { submesh, face_graph, parts, quadrics, error: deviation };
-    }
-
-    // Aim at a number of *clusters*, not a fraction of the triangles. Halving the triangle count is
-    // a means; halving the cluster count is the end, and asking for it directly is what keeps
-    // parents full. Where the children are already full the two coincide exactly. Where they are
-    // not, this simplifies less — because the reduction is coming from packing the geometry better
-    // rather than from destroying it, which is the outcome to prefer.
-    const parent_target = Math.max(
-        1, Math.ceil(group_clusters.length * options.simplification_ratio)
-    );
-
-    const outcome = simplify_to(Math.min(
-        parent_target * VGEO_MAX_CLUSTER_TRIANGLE_COUNT,
-        // A group of under-filled clusters can already be under the cluster-count target, in which
-        // case nothing would be simplified and the step would record no error — a step the cut rule
-        // cannot take. Falling back to the triangle ratio keeps it a real simplification.
-        Math.max(2, Math.round(face_ids.length * options.simplification_ratio))
-    ));
-
-    if (outcome.parts.length === 0) {
-        // Some small closed shells have no coarser form under edge collapse at all — a tetrahedron
-        // loses two faces to the collapse and its other two to the fuse that follows, leaving
-        // nothing. Nothing to build a parent from, so the group is refused and its clusters go back
-        // to the frontier to be grouped differently.
-        return undefined;
-    }
-
-    const submesh = outcome.submesh;
-    const submesh_face_graph = outcome.face_graph;
-    const parts = outcome.parts;
-
-    const step = new GroupStep();
-
-    step.child_clusters = child_clusters;
-
-    // Floored by what the children already carried. The accumulated quadric is a deviation from the
-    // source and nothing forces it to rise when the vertex carrying the previous maximum is the one
-    // collapsed away — but a parent that claimed to be closer to the source than its own child would
-    // make the cut oscillate, so monotonicity is imposed here rather than hoped for.
-    step.error = Math.max(outcome.error, max_child_error(child_clusters));
-
-    submesh.source_vertex_ids.forEach((source, local) => {
-        if (outcome.quadrics[local] !== null) {
-            step.quadrics.set(source, outcome.quadrics[local]);
-        }
-    });
-
-    const parent_points = [];
-
-    for (const part of parts) {
-        const part_face_ids = part.map((dense) => submesh_face_graph.vertex_face_ids[dense]);
-
-        part_face_ids.sort((a, b) => a - b);
-
-        const built = build_cluster(submesh.mesh, part_face_ids, level);
-
-        step.parent_clusters.push(built.cluster);
-
-        step.parent_geometry.push({
-            positions: built.gathered.positions,
-            indices: built.gathered.indices,
-            local_vertex_ids: built.gathered.vertex_ids,
-            source_vertex_ids: Uint32Array.from(
-                built.gathered.vertex_ids, (local) => submesh.source_vertex_ids[local]
-            ),
-            topology: submesh.mesh.topology,
-        });
-
-        parent_points.push(built.gathered.positions);
-    }
-
-    let point_count = 0;
-
-    for (const points of parent_points) {
-        point_count += points.length;
-    }
-
-    const points = new Float32Array(point_count);
-
-    let cursor = 0;
-
-    for (const part of parent_points) {
-        points.set(part, cursor);
-
-        cursor += part.length;
-    }
-
-    // One sphere for the whole step, containing both what it consumed and what it produced. Sharing
-    // it is what makes every sibling project the same value, and containing the children is what
-    // makes the pair monotonic.
-    step.sphere = vgeo_containing_sphere(
-        step.child_clusters.map((cluster) => cluster.self_sphere),
-        points
-    );
-
-    return step;
-}
-
-/**
- * Stitch a round's output back into one mesh: freshly simplified clusters, and the clusters the
- * round left alone, side by side.
- *
- * Vertices are unified by the id they had in the frontier below, never by position: a vertex two
- * groups share is pinned, so both carry it unmoved and unmistakably, while a vertex only one group
- * holds is its own even if a collapse happened to place it exactly where another landed. An
- * untouched cluster names its vertices in that same space, so it stitches to its simplified
- * neighbour along exactly the boundary that neighbour was forbidden to move.
- *
- * @param {VGeoContribution[]} contributions parallel to the clusters of the frontier being built
- * @param {(BinaryDataLayer|null)[]} template_layers the channels the frontier below carries, which
- *     the frontier being stitched carries too
- * @returns {{mesh: VirtualGeometryMesh, cluster_faces: number[][], source_vertex_ids: Uint32Array}}
- *     the last of which names, for every vertex of the new mesh, the vertex of the old one it came
- *     from — which is how its accumulated quadric follows it across the seam
- */
-function stitch_frontier(contributions, template_layers) {
-    /**
-     * `source vertex id -> index in the frontier being built`.
-     * @type {Map<number, number>}
-     */
-    const index_of_source = new Map();
-
-    const positions = [];
-    const indices = [];
-    const cluster_faces = [];
-
-    /**
-     * `[mesh the vertex came from, its id there]` per new vertex, so its attribute record can be
-     * copied across once the topology that receives it exists.
-     * @type {[BinaryTopology, number][]}
-     */
-    const attribute_sources = [];
-
-    let face_cursor = 0;
-
-    for (const geometry of contributions) {
-        const remap = new Uint32Array(geometry.local_vertex_ids.length);
-
-        geometry.local_vertex_ids.forEach((local, i) => {
-            const source = geometry.source_vertex_ids[i];
-
-            let target = index_of_source.get(source);
-
-            if (target === undefined) {
-                target = positions.length / 3;
-
-                index_of_source.set(source, target);
-
-                positions.push(
-                    geometry.positions[i * 3],
-                    geometry.positions[i * 3 + 1],
-                    geometry.positions[i * 3 + 2]
-                );
-
-                attribute_sources.push([geometry.topology, local]);
-            }
-
-            remap[i] = target;
-        });
-
-        const triangle_count = geometry.indices.length / 3;
-
-        const faces = [];
-
-        for (let i = 0; i < geometry.indices.length; i++) {
-            indices.push(remap[geometry.indices[i]]);
-        }
-
-        for (let i = 0; i < triangle_count; i++) {
-            faces.push(face_cursor + i);
-        }
-
-        face_cursor += triangle_count;
-
-        cluster_faces.push(faces);
-    }
-
-    const topology = new BinaryTopology();
-
-    // Before the vertices: adding a layer widens every record already in the block, and a frontier
-    // holds every vertex of a level.
-    const layers = vgeo_layers_like(topology, template_layers);
-
-    bt_mesh_from_indexed_geometry(topology, Uint32Array.from(indices), Float32Array.from(positions));
-
-    attribute_sources.forEach(([source, local], target) => {
-        vgeo_layers_copy_vertex(topology, source, local, target);
-    });
-
-    const mesh = new VirtualGeometryMesh(topology, layers);
-
-    const source_vertex_ids = new Uint32Array(index_of_source.size);
-
-    for (const [source, target] of index_of_source) {
-        source_vertex_ids[target] = source;
-    }
-
-    return { mesh, cluster_faces, source_vertex_ids };
-}
-
-/**
- * The frontier's clusters ordered by error, which is what a band is a slice of.
- *
- * @param {VGeoFrontier} frontier
- * @returns {{order: number[], errors: number[]}} cluster indices ascending by error, and their
- *     errors in the same order
- */
-function order_by_error(frontier) {
-    const order = frontier.clusters.map((cluster, index) => index);
-
-    order.sort(
-        (a, b) => (frontier.clusters[a].self_error - frontier.clusters[b].self_error) || (a - b)
-    );
-
-    return { order, errors: order.map((index) => frontier.clusters[index].self_error) };
-}
-
-/**
- * The bands a round tries, in the order it tries them.
- *
- * Each is one error *octave*: `[e, e · growth]` for each distinct error the frontier holds, finest
- * first. An octave rather than a running threshold is what bounds how far apart two clusters in one
- * group can be — a group shares a single parent error, so merging a nearly-exact cluster with a
- * badly-approximated one drags the exact one up to the other's error for nothing. It is also what
- * lets a cluster *wait*: geometry outside the octave is simply not this round's business.
- *
- * The last band is the whole frontier. It is the escape hatch, not the plan: a frontier of two
- * clusters an order of magnitude apart in error has no octave holding both, and merging them at a
- * wide error span still beats never reaching a root.
- *
- * @param {number[]} errors ascending, as {@link order_by_error} returns
- * @param {number} growth
- * @param {number} min_fraction least share of the frontier a band may cover
- * @returns {{start: number, end: number}[]} half-open ranges into the error order, deduplicated
- */
-function error_bands(errors, growth, min_fraction) {
-    /**
-     * @param {number} value
-     * @returns {number} first position whose error exceeds `value`
-     */
-    function upper_bound(value) {
-        let low = 0;
-        let high = errors.length;
-
-        while (low < high) {
-            const middle = (low + high) >> 1;
-
-            if (errors[middle] <= value) {
-                low = middle + 1;
-            } else {
-                high = middle;
-            }
-        }
-
-        return low;
-    }
-
-    const result = [];
-    const seen = new Set();
-
-    /**
-     * @param {number} start
-     * @param {number} end
-     */
-    function add(start, end) {
-        const key = `${start}:${end}`;
-
-        if (end - start < 2 || seen.has(key)) {
-            return;
-        }
-
-        seen.add(key);
-
-        result.push({ start, end });
-    }
-
-    const minimum = Math.max(2, Math.ceil(errors.length * min_fraction));
-
-    let cursor = 0;
-
-    while (cursor < errors.length) {
-        const low = errors[cursor];
-
-        add(cursor, Math.max(upper_bound(low * growth), Math.min(errors.length, cursor + minimum)));
-
-        cursor = upper_bound(low);
-    }
-
-    add(0, errors.length);
-
-    return result;
-}
-
-/**
- * One round: pick a band, group it, simplify each group, and report what it produced.
- *
- * Every group is speculative and judged on its own. One that comes back with no fewer clusters than
- * it consumed is simply dropped — its clusters return to the frontier, to be grouped differently by
- * a later round — rather than failing the round for everyone else. A group that cannot be
- * simplified is no different in kind from a group that could not be formed, and the frontier already
- * knows what to do with those: nothing, for now.
- *
- * The round as a whole is accepted only when it *strictly* shrinks the frontier. Failing that it
- * widens the band, and failing that it grows the group — small groups starve the simplifier, and a
- * wider band gives a fine region coarser neighbours to merge with.
- *
- * @param {VGeoFrontier} frontier
- * @param {number} level of the parents this round would produce
- * @param {VGeoLevelOptions} options
- * @returns {{steps: GroupStep[], repacks: GroupRepack[], merged: Set<number>}|undefined} what to
- *     commit and which frontier clusters it consumed; `undefined` when nothing this round could try
- *     made the frontier smaller
- */
-function run_round(frontier, level, options) {
-    const face_graph = new VGeoFaceGraph(
-        frontier.mesh.topology, bt_mesh_build_face_graph(frontier.mesh.topology)
-    );
-
-    const cluster_graph = build_cluster_graph(frontier, face_graph);
-
-    const ordered = order_by_error(frontier);
-
-    const bands = error_bands(
-        ordered.errors, options.error_band_growth, options.error_band_min_fraction
-    );
-
-    let group_size = options.group_size;
-
-    for (; ;) {
-        for (const range of bands) {
-            const band = ordered.order.slice(range.start, range.end);
-
-            band.sort((a, b) => a - b);
-
-            const groups = partition_into_groups(frontier, band, cluster_graph, group_size);
-
-            if (groups.length === 0) {
-                continue;
-            }
-
-            const group_of_face = new Int32Array(frontier.mesh.topology.faces.size).fill(-1);
-
-            groups.forEach((group, group_index) => {
-                for (const cluster of group) {
-                    for (const face of frontier.cluster_faces[cluster]) {
-                        group_of_face[face] = group_index;
-                    }
-                }
-            });
-
-            const steps = [];
-            const repacks = [];
-
-            let consumed = 0;
-            let produced = 0;
-
-            const merged = new Set();
-
-            groups.forEach((group, group_index) => {
-                const parent_target = Math.max(
-                    1, Math.ceil(group.length * options.simplification_ratio)
-                );
-
-                const repack = try_repack(frontier, group, parent_target);
-
-                if (repack !== undefined) {
-                    repacks.push(repack);
-
-                    consumed += group.length;
-                    produced += repack.clusters.length;
-
-                    for (const cluster of group) {
-                        merged.add(cluster);
-                    }
-
-                    return;
-                }
-
-                const step = build_group_step(
-                    frontier, group, group_of_face, group_index, level, options
-                );
-
-                if (step === undefined || step.parent_clusters.length >= group.length) {
-                    // Refused. Nothing has been mutated — the step worked on a copy of the geometry
-                    // and a copy of the quadrics — so its clusters simply stay where they are.
-                    return;
-                }
-
-                steps.push(step);
-
-                consumed += group.length;
-                produced += step.parent_clusters.length;
-
-                for (const cluster of group) {
-                    merged.add(cluster);
-                }
-            });
-
-            if (produced < consumed) {
-                return { steps, repacks, merged };
-            }
-        }
-
-        // No band made progress. Growing the group gives the simplifier more interior to work with
-        // relative to its locked perimeter, which is the thing that stalls first.
-        if (group_size >= frontier.clusters.length) {
-            return undefined;
-        }
-
-        group_size = Math.min(frontier.clusters.length, group_size * 2);
-    }
-}
-
-const scratch_quadric = new Quadric3();
-
-/**
- * Build the whole DAG, from a source mesh to a single root.
- *
- * @param {VirtualGeometryMesh} mesh the normalized source; consumed, not copied
- * @param {VGeoLevelOptions} options
- * @returns {VGeoLevel[]} leaves first; the last level holds exactly one cluster, the root
- */
-export function vgeo_build_levels(mesh, options) {
-    assert.isPositiveInteger(options.group_size, 'options.group_size');
-    assert.greaterThan(options.group_size, 1, 'options.group_size');
-    assert.greaterThan(options.simplification_ratio, 0, 'options.simplification_ratio');
-    assert.lessThan(options.simplification_ratio, 1, 'options.simplification_ratio');
-    assert.greaterThan(options.error_band_growth, 1, 'options.error_band_growth');
-    assert.greaterThan(options.error_band_min_fraction, 0, 'options.error_band_min_fraction');
-    assert.lessThanOrEqual(options.error_band_min_fraction, 1, 'options.error_band_min_fraction');
-    assert.isPositiveInteger(options.max_levels, 'options.max_levels');
-
-    let frontier = build_leaf_frontier(mesh);
-
-    const leaves = new VGeoLevel();
-
-    leaves.index = 0;
-    leaves.clusters = frontier.clusters.slice();
-
-    const levels = [leaves];
-
-    while (frontier.clusters.length > 1) {
-        if (levels.length >= options.max_levels) {
-            throw new Error(
-                `the DAG still holds ${frontier.clusters.length} clusters after ${levels.length} `
-                + `levels, which is as many as the container can name`
-            );
-        }
-
-        const level = levels.length;
-
-        const round = run_round(frontier, level, options);
-
-        if (round === undefined) {
-            throw new Error(
-                `the DAG stopped converging with ${frontier.clusters.length} clusters left: no `
-                + `grouping of the frontier produced fewer clusters than it consumed, so the build `
-                + `has no single root to start a cut from`
-            );
-        }
-
-        const next = new VGeoLevel();
-
-        next.index = level;
-
-        /**
-         * @type {VGeoContribution[]}
-         */
-        const contributions = [];
-
-        const clusters = [];
-
-        // Untouched clusters first, in the order they already had, then this round's output. All of
-        // them name their vertices in the frontier that is being replaced, which is what lets them
-        // be stitched into one mesh.
-        frontier.clusters.forEach((cluster, index) => {
-            if (round.merged.has(index)) {
-                return;
-            }
-
-            const gathered = vgeo_gather_faces(frontier.mesh, frontier.cluster_faces[index]);
-
-            clusters.push(cluster);
-
-            contributions.push({
-                positions: gathered.positions,
-                indices: gathered.indices,
-                local_vertex_ids: gathered.vertex_ids,
-                source_vertex_ids: gathered.vertex_ids,
-                topology: frontier.mesh.topology,
-            });
-        });
-
-        if (round.repacks.length > 0) {
-            const replaced = new Set();
-
-            for (const repack of round.repacks) {
-                for (const leaf of repack.replaced) {
-                    replaced.add(leaf);
-                }
-            }
-
-            // One pass over the leaf level for the whole round. Per repack it would be a scan of
-            // every leaf in the asset, and a scene of small parts is nothing but repacks.
-            leaves.clusters = leaves.clusters.filter((cluster) => !replaced.has(cluster));
-
-            for (const repack of round.repacks) {
-                repack.clusters.forEach((cluster, index) => {
-                    leaves.clusters.push(cluster);
-
-                    clusters.push(cluster);
-                    contributions.push(repack.geometry[index]);
-                });
-            }
-        }
-
-        for (const step of round.steps) {
-            const group = new VirtualGeometryGroup();
-
-            // The group sits one band below the parents it produced, which is what makes page order
-            // by descending level a topological order of the DAG.
-            group.level = level - 1;
-            group.clusters = step.child_clusters;
-
-            for (const cluster of step.child_clusters) {
-                cluster.parent_error = step.error;
-                cluster.parent_sphere = step.sphere;
-            }
-
-            step.parent_clusters.forEach((parent, index) => {
-                parent.self_error = step.error;
-                parent.self_sphere = step.sphere;
-                parent.child_group = group;
-
-                next.clusters.push(parent);
-                clusters.push(parent);
-                contributions.push(step.parent_geometry[index]);
-            });
-
-            levels[level - 1].groups.push(group);
-        }
-
-        if (next.clusters.length > 0) {
-            levels.push(next);
-        }
-
-        // Fold every step's quadric gains back into the frontier's own set, before it is re-indexed.
-        //
-        // Gains, not results: two steps that share a pinned boundary vertex each started from this
-        // vertex's quadric and each accumulated their own victims onto it, so the two results
-        // overlap by exactly the quadric they both began with. Adding them whole would count the
-        // source planes under that vertex twice and inflate every error above it.
-        const updated = frontier.quadrics.slice();
-
-        for (const step of round.steps) {
-            for (const [vertex, quadric] of step.quadrics) {
-
-                scratch_quadric.copy(quadric);
-                scratch_quadric.sub(frontier.quadrics[vertex]);
-
-                const next = updated[vertex].clone();
-                next.add(scratch_quadric);
-
-                updated[vertex] = next;
-
-            }
-        }
-
-        const stitched = stitch_frontier(contributions, frontier.mesh.layers);
-
-        frontier = new VGeoFrontier();
-
-        frontier.mesh = stitched.mesh;
-        frontier.clusters = clusters;
-        frontier.cluster_faces = stitched.cluster_faces;
-        frontier.quadrics = Array.from(
-            stitched.source_vertex_ids, (source) => updated[source]
-        );
-    }
-
-    const top = levels[levels.length - 1];
-
-    assert.equal(
-        top.clusters.length, 1,
-        'the topmost level must hold the single root the frontier converged to'
-    );
-
-    assert.equal(
-        top.clusters[0], frontier.clusters[0],
-        'the cluster the frontier converged to must be the one the topmost level holds'
-    );
-
-    return levels;
-}
+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";
+import {
+    bt_mesh_compute_vertex_quadrics
+} 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";
+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";
+import { VGeoLevel } from "./VGeoLevel.js";
+import { VirtualGeometryMesh } from "./VirtualGeometryMesh.js";
+
+/**
+ * Build the cluster DAG: leaves out of the source mesh, then merge steps until one cluster is left.
+ *
+ * The unit of work is a **round**, not a level sweep. A round holds a *frontier* — every cluster that
+ * nothing has merged yet — selects a band of it by error, groups the band, locks every vertex the
+ * group shares with anything outside it, halves the group's interior, and re-cuts the result into
+ * new clusters, which become the parents of every cluster in the group. Locked perimeters plus a
+ * group-uniform metric is the whole reason independent per-cluster LOD decisions come out
+ * crack-free.
+ *
+ * **The band is why this is not a level sweep.** Sweeping whole levels pushes every cluster up one
+ * step per level whatever its error, so a region that is nearly exact is coarsened in lockstep with
+ * one that is not, and a level ends up spanning an order of magnitude of error. The cut the runtime
+ * takes is a threshold on error, so a level that spans an order of magnitude is a page band that
+ * spans one too: installing it brings clusters the cut does not want, and the ones it does want are
+ * scattered across bands. Selecting the lowest-error band instead lets a fine region catch up before
+ * the coarse one moves, and bands come out error-uniform. On geometry whose error is already uniform
+ * the band is the whole frontier and this degenerates to the sweep, which is the correct behaviour
+ * for that case rather than a special case for it.
+ *
+ * **A cluster the round cannot use simply stays.** It is not pushed up for the sake of symmetry, and
+ * it does not stall the round for anyone else — which is what lets a lone island wait, untouched and
+ * at zero error, until the geometry it will eventually merge with has come down to meet it.
+ *
+ * **Error is conformance to the source, not a sum of steps.** Vertex quadrics are built once, from
+ * the source triangles, and carried through every round: a survivor absorbs its victim's quadric at
+ * every collapse, so a vertex twelve rounds up still holds the planes of every source triangle
+ * folded into it. Evaluating that at its current position measures the deviation from what the
+ * artist authored, directly, and normalizing by the quadric's accumulated weight makes it an
+ * object-space length rather than a cost whose scale depends on how many planes it happens to hold.
+ * That length is what the runtime projects into pixels.
+ *
+ * **Termination is convergence to one root, not a stall.** Groups bundle across connected components
+ * once connectivity runs out, and a group small enough to fit one cluster is merged losslessly, so a
+ * frontier of separate islands still comes together. A build that cannot reach a single root throws:
+ * the runtime starts its cut at the root, and "several roots" is not a shape it can start from.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Fixed so that the same frontier always groups the same way.
+ * @readonly
+ * @type {number}
+ */
+const GROUP_SEED = 0x6D05;
+
+const scratch_sphere = new Float32Array(4);
+
+/**
+ * Every cluster nothing has merged yet, and the geometry they currently stand for.
+ *
+ * One mesh holds the whole frontier so that a group can be extracted with its surroundings intact —
+ * the lock set is "every vertex a face outside this group touches", and that question has no answer
+ * in a mesh that holds the group alone.
+ */
+class VGeoFrontier {
+    /**
+     * @type {VirtualGeometryMesh}
+     */
+    mesh = null;
+
+    /**
+     * @type {VirtualGeometryCluster[]}
+     */
+    clusters = [];
+
+    /**
+     * `cluster_faces[i]` are the faces of {@link mesh} that cluster `i` owns.
+     * @type {number[][]}
+     */
+    cluster_faces = [];
+
+    /**
+     * One accumulated quadric per vertex of {@link mesh}, carried unbroken from the source mesh.
+     *
+     * This is what makes the error mean "how far this is from the geometry the artist authored"
+     * rather than "how far this is from the frontier it was simplified out of". A survivor absorbs
+     * its victim's quadric at every collapse, at every round, so a vertex twelve rounds up still
+     * carries the planes of every source triangle that was ever folded into it, and evaluating its
+     * quadric at its current position measures the deviation from the source directly. Composing
+     * per-round residuals instead only *bounds* that, by the triangle inequality, and the bound
+     * loosens with every round: measured on a unit sphere, the same ninety-triangle root read 0.36
+     * built from 3k source triangles and 13.3 built from 24k, where it is the same approximation and
+     * reads 0.0315 either way once the quadrics are carried.
+     *
+     * @type {Quadric3[]}
+     */
+    quadrics = [];
+}
+
+/**
+ * Everything one group step produced, before it is committed. Kept separate so that a round which
+ * fails to make progress can be discarded without having mutated the frontier.
+ */
+class GroupStep {
+    /**
+     * The frontier clusters this group holds.
+     * @type {VirtualGeometryCluster[]}
+     */
+    child_clusters = [];
+
+    /**
+     * @type {VirtualGeometryCluster[]}
+     */
+    parent_clusters = [];
+
+    /**
+     * Parallel to {@link parent_clusters}: the geometry each parent was cut from, in terms of the
+     * frontier, so the next frontier can be stitched back together.
+     * @type {VGeoContribution[]}
+     */
+    parent_geometry = [];
+
+    /**
+     * The value both sides of this step store: the object-space distance from the *source* surface
+     * that this step's geometry now stands at, floored by what its children already carried.
+     * @type {number}
+     */
+    error = 0;
+
+    /**
+     * `frontier vertex id -> that vertex's quadric after this step`, for every vertex that survived
+     * it. Held rather than written straight back because a step is speculative until the round
+     * accepts it, and because two steps sharing a pinned boundary vertex must have their gains
+     * combined rather than one overwriting the other.
+     * @type {Map<number, Quadric3>}
+     */
+    quadrics = new Map();
+
+    /**
+     * The LOD-metric sphere both sides of this step store.
+     * @type {Float32Array}
+     */
+    sphere = new Float32Array(4);
+}
+
+/**
+ * Several leaves re-cut into one, with nothing simplified — see {@link build_repack}.
+ */
+class GroupRepack {
+    /**
+     * The leaves this removes from the DAG.
+     * @type {VirtualGeometryCluster[]}
+     */
+    replaced = [];
+
+    /**
+     * The leaves that take their place -- always fewer.
+     * @type {VirtualGeometryCluster[]}
+     */
+    clusters = [];
+
+    /**
+     * Parallel to {@link clusters}.
+     * @type {VGeoContribution[]}
+     */
+    geometry = [];
+}
+
+/**
+ * One cluster's geometry expressed against the frontier it came out of, which is what lets the next
+ * frontier be stitched from a mixture of freshly simplified clusters and untouched ones.
+ *
+ * @typedef {object} VGeoContribution
+ * @property {Float32Array} positions
+ * @property {Uint32Array} indices local to {@link positions}
+ * @property {Uint32Array} local_vertex_ids ids in the mesh {@link topology} belongs to
+ * @property {Uint32Array} source_vertex_ids the same vertices, named in the frontier's mesh
+ * @property {BinaryTopology} topology the mesh {@link local_vertex_ids} name vertices of, whose
+ *     vertex data block holds their attributes
+ */
+
+/**
+ * Encode a gathered face set into a cluster record.
+ *
+ * @param {VGeoGatheredFaces} gathered already within both meshlet caps
+ * @param {number} level
+ * @param {(BinaryDataLayer|null)[]} layers of the mesh it was gathered from
+ * @returns {VirtualGeometryCluster}
+ */
+function cluster_from_gathered(gathered, level, layers) {
+    const payload = vgeo_encode_cluster_payload(
+        gathered.positions,
+        vgeo_narrow_indices(gathered),
+        gathered.vertex_ids,
+        layers
+    );
+
+    const cluster = new VirtualGeometryCluster();
+
+    cluster.level = level;
+    cluster.vertex_count = gathered.vertex_ids.length;
+    cluster.triangle_count = gathered.indices.length / 3;
+    cluster.encoding_flags = payload.encoding_flags;
+    cluster.payload = payload.bytes;
+    cluster.bounds_sphere = vgeo_bounding_sphere(gathered.positions);
+
+    // the box needs no inflation, unlike the sphere above: the extremes are float32 values already,
+    // so min and max of them are exactly representable and the stored box contains the stored
+    // points by construction
+    aabb3_from_v3_array(cluster.aabb, gathered.positions, gathered.positions.length);
+
+    return cluster;
+}
+
+/**
+ * Build a cluster out of a face set: gather it, bound it, encode its payload.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {number[]} face_ids
+ * @param {number} level
+ * @returns {{cluster: VirtualGeometryCluster, gathered: VGeoGatheredFaces}}
+ */
+function build_cluster(mesh, face_ids, level) {
+    const gathered = vgeo_gather_faces(mesh, face_ids);
+
+    return { cluster: cluster_from_gathered(gathered, level, mesh.layers), gathered };
+}
+
+/**
+ * Cut a mesh into leaf clusters — the frontier every round starts from.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @returns {VGeoFrontier}
+ */
+function build_leaf_frontier(mesh) {
+    const face_graph = new VGeoFaceGraph(mesh.topology, bt_mesh_build_face_graph(mesh.topology));
+
+    const all = [];
+
+    for (let vertex = 0; vertex < face_graph.graph.vertex_count; vertex++) {
+        all.push(vertex);
+    }
+
+    const parts = vgeo_split_face_set(
+        face_graph, all, VGEO_MAX_CLUSTER_TRIANGLE_COUNT, VGEO_MAX_CLUSTER_VERTEX_COUNT
+    );
+
+    const frontier = new VGeoFrontier();
+
+    frontier.mesh = mesh;
+
+    // Built once, here, from the source triangles. Nothing rebuilds them afterwards — every later
+    // round inherits these and adds to them, which is the whole point.
+    frontier.quadrics = bt_mesh_compute_vertex_quadrics(mesh.topology);
+
+    for (const part of parts) {
+        const face_ids = part.map((dense) => face_graph.vertex_face_ids[dense]);
+
+        face_ids.sort((a, b) => a - b);
+
+        const built = build_cluster(mesh, face_ids, 0);
+
+        // A leaf's own bounds are its LOD-metric sphere, and it deviates from nothing.
+        built.cluster.self_sphere = built.cluster.bounds_sphere.slice();
+        built.cluster.self_error = 0;
+
+        frontier.clusters.push(built.cluster);
+        frontier.cluster_faces.push(face_ids);
+    }
+
+    return frontier;
+}
+
+/**
+ * How much of the space two clusters would waste by being merged, as a factor in `(0, 1]`.
+ *
+ * The ratio of what they occupy separately to what the sphere containing both would occupy. Two
+ * clusters side by side score near one; two clusters at opposite ends of the model score near zero,
+ * because the sphere over both is mostly empty. Scale-free by construction — it compares a volume
+ * to a volume, so it needs no notion of how big the model is or how far apart "far" is, which is
+ * exactly what a distance threshold would have needed and could never have been given.
+ *
+ * The group's sphere is what the runtime projects to decide the whole group's fate, so a group
+ * spread across empty space is one that gets refined from much further away than its geometry
+ * warrants. Cutting edge weight by this steers the partitioner away from those merges without ever
+ * forbidding one — when nothing better is available, a poor merge is still better than none.
+ *
+ * @param {Float32Array} a bounding sphere, centre then radius
+ * @param {Float32Array} b
+ * @returns {number}
+ */
+function compactness(a, b) {
+    sphere_compute_bounding_of_2_spheres(scratch_sphere, a, b);
+
+    const merged = scratch_sphere[3];
+
+    if (merged <= 0) {
+        return 1;
+    }
+
+    // Volumes, up to the common factor of 4/3 pi, which cancels.
+    const separate = a[3] * a[3] * a[3] + b[3] * b[3] * b[3];
+
+    return Math.min(1, separate / (merged * merged * merged));
+}
+
+/**
+ * The cluster adjacency graph of a frontier: clusters are the vertices, shared mesh edges are the
+ * edges, and an edge weighs as much boundary as the two clusters share, discounted by how much empty
+ * space merging them would enclose.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {VGeoFaceGraph} face_graph of `frontier.mesh`
+ * @returns {{edge_addresses: Uint32Array, adjacency: Uint32Array, edge_weights: Float32Array}}
+ */
+function build_cluster_graph(frontier, face_graph) {
+    const cluster_of_face = new Int32Array(frontier.mesh.topology.faces.size).fill(-1);
+
+    frontier.cluster_faces.forEach((face_ids, cluster) => {
+        for (const face of face_ids) {
+            cluster_of_face[face] = cluster;
+        }
+    });
+
+    const cluster_count = frontier.clusters.length;
+
+    /**
+     * `cluster -> (neighbour cluster -> shared boundary)`.
+     * @type {Map<number, number>[]}
+     */
+    const neighbours = [];
+
+    for (let i = 0; i < cluster_count; i++) {
+        neighbours.push(new Map());
+    }
+
+    const graph = face_graph.graph;
+
+    for (let vertex = 0; vertex < graph.vertex_count; vertex++) {
+        const cluster = cluster_of_face[face_graph.vertex_face_ids[vertex]];
+
+        for (let i = graph.edge_addresses[vertex]; i < graph.edge_addresses[vertex + 1]; i++) {
+            const other_cluster = cluster_of_face[face_graph.vertex_face_ids[graph.adjacency[i]]];
+
+            if (other_cluster === cluster) {
+                continue;
+            }
+
+            const bucket = neighbours[cluster];
+
+            bucket.set(other_cluster, (bucket.get(other_cluster) ?? 0) + graph.edge_weights[i]);
+        }
+    }
+
+    const edge_addresses = new Uint32Array(cluster_count + 1);
+    const adjacency = [];
+    const edge_weights = [];
+
+    for (let cluster = 0; cluster < cluster_count; cluster++) {
+        edge_addresses[cluster] = adjacency.length;
+
+        const entries = Array.from(neighbours[cluster].entries()).sort((a, b) => a[0] - b[0]);
+
+        for (const [other, weight] of entries) {
+            adjacency.push(other);
+
+            edge_weights.push(weight * compactness(
+                frontier.clusters[cluster].bounds_sphere, frontier.clusters[other].bounds_sphere
+            ));
+        }
+    }
+
+    edge_addresses[cluster_count] = adjacency.length;
+
+    return {
+        edge_addresses,
+        adjacency: Uint32Array.from(adjacency),
+        edge_weights: Float32Array.from(edge_weights),
+    };
+}
+
+/**
+ * Bundle clusters that have no one to merge with along a Morton curve.
+ *
+ * A cluster alone in its connected component cannot be coarsened: halving its triangles leaves one
+ * cluster where there was one cluster, and the DAG stands still. The only way it ever reaches a root
+ * is bundled with geometry it shares no edge with, and the only thing left to choose them by is
+ * where they are. That is a real cost — a cluster spanning two islands carries a sphere containing
+ * both — which is why this is the fallback and adjacency is the rule.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {number[]} loose cluster indices, each alone in its component
+ * @param {number} group_size
+ * @returns {number[][]} groups of at least two; a single leftover is returned to the frontier
+ */
+function bundle_loose_clusters(frontier, loose, group_size) {
+    if (loose.length < 2) {
+        return [];
+    }
+
+    const bounds = new Float32Array([
+        Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY,
+        Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY,
+    ]);
+
+    for (const cluster of loose) {
+        const centre = 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]);
+        }
+    }
+
+    /**
+     * @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));
+    }
+
+    const order = loose.slice();
+
+    order.sort((a, b) => (codes.get(a) - codes.get(b)) || (a - b));
+
+    const result = [];
+
+    let bundle = [];
+    let triangles = 0;
+    let vertices = 0;
+    let packable = true;
+
+    for (const index of order) {
+        const cluster = frontier.clusters[index];
+
+        // Leaves small enough to end up in one cluster between them are worth bundling past the
+        // group size: what happens to them is a re-cut at no error, not a simplification, so a
+        // bigger bundle costs nothing in fidelity and is the difference between a scene of small
+        // parts filling its clusters and running them at a tenth of capacity. Anything else stops at
+        // the group size, where the size is a real trade against LOD lockstep.
+        const packs = packable
+            && cluster.child_group === undefined
+            && triangles + cluster.triangle_count <= VGEO_MAX_CLUSTER_TRIANGLE_COUNT
+            && vertices + cluster.vertex_count <= VGEO_MAX_CLUSTER_VERTEX_COUNT;
+
+        if (bundle.length >= group_size && !packs) {
+            result.push(bundle);
+
+            bundle = [];
+            triangles = 0;
+            vertices = 0;
+            packable = true;
+        }
+
+        bundle.push(index);
+
+        triangles += cluster.triangle_count;
+        vertices += cluster.vertex_count;
+
+        packable = packable && cluster.child_group === undefined;
+    }
+
+    if (bundle.length === 1 && result.length > 0) {
+        // A bundle of one merges nothing. Handing it to the bundle before it costs one cluster of
+        // spatial spread and is the difference between the frontier shrinking and it standing still.
+        result[result.length - 1].push(bundle[0]);
+    } else if (bundle.length > 1) {
+        result.push(bundle);
+    }
+
+    return result.filter((group) => group.length >= 2);
+}
+
+/**
+ * Fold every one-cluster piece into the adjacent piece it shares the most boundary with.
+ *
+ * The partitioner produces these constantly — it optimizes cut, not contiguity, so splitting its
+ * parts into connected pieces routinely leaves a cluster standing on its own. Such a cluster is not
+ * out of options, though: it sits inside a component that has plenty of neighbours, and the right
+ * answer is the nearest of them, not the proximity pool. Letting it fall through to the pool is how
+ * a lone shell sixty metres away ends up merged with a fragment of something else entirely.
+ *
+ * One forward pass is enough. Folding only ever grows a piece and empties the one it came from, so
+ * it cannot turn a piece of two into a piece of one — the singletons are exactly the ones present
+ * when the pass starts, and a singleton that has already absorbed another is no longer one.
+ *
+ * @param {number[][]} pieces of a single connected component of the band, each non-empty; every
+ *     cluster in a singleton piece therefore has a neighbour in some other piece here
+ * @param {object} cluster_graph as {@link build_cluster_graph} returns
+ * @returns {number[][]} non-empty pieces, with no singletons
+ */
+function absorb_singleton_pieces(pieces, cluster_graph) {
+    if (pieces.length < 2) {
+        return pieces;
+    }
+
+    /**
+     * `cluster -> index of the piece holding it`.
+     * @type {Map<number, number>}
+     */
+    const piece_of = new Map();
+
+    const alive = pieces.map((piece) => piece.slice());
+
+    alive.forEach((piece, index) => {
+        for (const cluster of piece) {
+            piece_of.set(cluster, index);
+        }
+    });
+
+    for (let index = 0; index < alive.length; index++) {
+        if (alive[index].length !== 1) {
+            continue;
+        }
+
+        const cluster = alive[index][0];
+
+        /**
+         * `piece index -> boundary shared with this cluster`.
+         * @type {Map<number, number>}
+         */
+        const shared = new Map();
+
+        for (let i = cluster_graph.edge_addresses[cluster]; i < cluster_graph.edge_addresses[cluster + 1]; i++) {
+            const target = piece_of.get(cluster_graph.adjacency[i]);
+
+            if (target === undefined || target === index) {
+                continue;
+            }
+
+            shared.set(target, (shared.get(target) ?? 0) + cluster_graph.edge_weights[i]);
+        }
+
+        let best = -1;
+        let best_weight = -1;
+
+        // Sorted, so that two pieces sharing the same boundary length resolve the same way every
+        // time rather than however the adjacency happened to be walked.
+        for (const [target, weight] of Array.from(shared.entries()).sort((a, b) => a[0] - b[0])) {
+            if (weight > best_weight) {
+                best = target;
+                best_weight = weight;
+            }
+        }
+
+        assert.notEqual(
+            best, -1,
+            'a lone cluster inside a connected component must border another piece of it'
+        );
+
+        alive[best].push(cluster);
+        alive[best].sort((a, b) => a - b);
+
+        piece_of.set(cluster, best);
+
+        alive[index] = [];
+    }
+
+    return alive.filter((piece) => piece.length > 0);
+}
+
+/**
+ * Partition a band of the frontier into groups of roughly `group_size`.
+ *
+ * The partition runs **inside each connected component** of the cluster graph, not across the band as
+ * a whole. Partitioning globally and splitting the disconnected parts afterwards looks equivalent and
+ * is not: a scene assembled from thousands of separate shells has a cluster graph in thousands of
+ * pieces, and a balanced global partition draws each part from several of them, so the connectivity
+ * split then shreds nearly every group down to a single cluster.
+ *
+ * What is left over after that — every cluster alone in its component — is bundled by proximity
+ * instead, because for those clusters there is no adjacency left to respect and no other way to the
+ * root.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {number[]} band cluster indices this round may consume, ascending
+ * @param {object} cluster_graph as {@link build_cluster_graph} returns
+ * @param {number} group_size
+ * @returns {number[][]} groups of at least two clusters each; clusters left out stay in the frontier
+ */
+function partition_into_groups(frontier, band, cluster_graph, group_size) {
+    const membership = new Int32Array(frontier.clusters.length).fill(-1);
+
+    for (const cluster of band) {
+        membership[cluster] = 0;
+    }
+
+    const components = vgeo_graph_components(
+        cluster_graph.edge_addresses, cluster_graph.adjacency, band, membership, 0
+    );
+
+    const result = [];
+
+    /**
+     * Clusters with nobody adjacent to merge with.
+     * @type {number[]}
+     */
+    const loose = [];
+
+    let token = 0;
+
+    /**
+     * @param {number[]} piece
+     */
+    function accept(piece) {
+        if (piece.length < 2) {
+            loose.push(piece[0]);
+
+            return;
+        }
+
+        // The format caps a group at 4096 clusters. Nothing the size policy produces comes near it,
+        // but the cap is hard, so the chunking is here rather than assumed away.
+        for (let start = 0; start < piece.length; start += VGEO_MAX_GROUP_CLUSTER_COUNT) {
+            const chunk = piece.slice(start, start + VGEO_MAX_GROUP_CLUSTER_COUNT);
+
+            if (chunk.length < 2) {
+                loose.push(chunk[0]);
+
+                continue;
+            }
+
+            result.push(chunk);
+        }
+    }
+
+    for (const component of components) {
+        if (component.length < 2) {
+            // Alone in its component: no adjacency left anywhere, so proximity is the only rule that
+            // can still place it.
+            loose.push(component[0]);
+
+            continue;
+        }
+
+        if (component.length <= group_size) {
+            accept(component);
+
+            continue;
+        }
+
+        /**
+         * @type {number[][]}
+         */
+        const pieces = [];
+
+        const part_count = Math.ceil(component.length / group_size);
+
+        token++;
+
+        for (const cluster of component) {
+            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 = [];
+
+        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) {
+                membership[cluster] = token;
+            }
+
+            for (const piece of vgeo_graph_components(
+                cluster_graph.edge_addresses, cluster_graph.adjacency, part, membership, token
+            )) {
+                pieces.push(piece);
+            }
+        }
+
+        for (const piece of absorb_singleton_pieces(pieces, cluster_graph)) {
+            accept(piece);
+        }
+    }
+
+    for (const bundle of bundle_loose_clusters(frontier, loose, group_size)) {
+        result.push(bundle);
+    }
+
+    result.sort((a, b) => a[0] - b[0]);
+
+    return result;
+}
+
+/**
+ * Does any face outside this group use the edge?
+ *
+ * @param {BinaryTopology} topology
+ * @param {number} edge
+ * @param {Int32Array} group_of_face
+ * @param {number} group_index
+ * @returns {boolean}
+ */
+function edge_touches_outside(topology, edge, group_of_face, group_index) {
+    const first_loop = topology.edge_read_loop(edge);
+
+    if (first_loop === NULL_POINTER) {
+        return false;
+    }
+
+    let loop = first_loop;
+
+    do {
+        const face = topology.loop_read_face(loop);
+
+        if (face !== NULL_POINTER && group_of_face[face] !== group_index) {
+            return true;
+        }
+
+        loop = topology.loop_read_radial_next(loop);
+    } while (loop !== first_loop && loop !== NULL_POINTER);
+
+    return false;
+}
+
+/**
+ * Does any face outside this group use the vertex? Walks the vertex's disk cycle and each edge's
+ * radial cycle, so the answer is local to the vertex rather than a scan of the frontier.
+ *
+ * @param {BinaryTopology} topology
+ * @param {number} vertex
+ * @param {Int32Array} group_of_face
+ * @param {number} group_index
+ * @returns {boolean}
+ */
+function vertex_touches_outside(topology, vertex, group_of_face, group_index) {
+    const first_edge = topology.vertex_read_edge(vertex);
+
+    if (first_edge === NULL_POINTER) {
+        return false;
+    }
+
+    let edge = first_edge;
+
+    do {
+        if (edge_touches_outside(topology, edge, group_of_face, group_index)) {
+            return true;
+        }
+
+        edge = (topology.edge_read_vertex1(edge) === vertex)
+            ? topology.edge_read_v1_disk_next(edge)
+            : topology.edge_read_v2_disk_next(edge);
+    } while (edge !== first_edge && edge !== NULL_POINTER);
+
+    return false;
+}
+
+/**
+ * Which vertices a group must not move, and which boundary edges must survive its simplification.
+ *
+ * A vertex is locked when any face outside the group touches it — not merely when it sits on a
+ * shared *edge*. The weaker rule leaks: two groups can meet at a single non-manifold vertex with no
+ * edge between them, and each would then move that vertex somewhere else, tearing the surface at a
+ * point no boundary walk would have flagged.
+ *
+ * "Outside" includes frontier clusters this round left alone, which is what keeps a band's seam with
+ * the rest of the frontier from opening.
+ *
+ * @param {BinaryTopology} topology
+ * @param {number[]} group_face_ids
+ * @param {Int32Array} group_of_face one entry per face slot, holding the group each face belongs to
+ * @param {number} group_index
+ * @returns {{locked: Set<number>, polyline: number[][]}} locked vertex ids, and the `[v1, v2]` pairs
+ *     of every edge this group shares with the outside
+ */
+function compute_group_boundary(topology, group_face_ids, group_of_face, group_index) {
+    const vertices = new Set();
+    const edges = new Set();
+
+    for (const face of group_face_ids) {
+        const first_loop = topology.face_read_loop(face);
+
+        let loop = first_loop;
+
+        do {
+            vertices.add(topology.loop_read_vertex(loop));
+            edges.add(topology.loop_read_edge(loop));
+
+            loop = topology.loop_read_next(loop);
+        } while (loop !== first_loop);
+    }
+
+    const locked = new Set();
+
+    for (const vertex of vertices) {
+        if (vertex_touches_outside(topology, vertex, group_of_face, group_index)) {
+            locked.add(vertex);
+        }
+    }
+
+    const polyline = [];
+
+    for (const edge of edges) {
+        if (!edge_touches_outside(topology, edge, group_of_face, group_index)) {
+            continue;
+        }
+
+        polyline.push([topology.edge_read_vertex1(edge), topology.edge_read_vertex2(edge)]);
+    }
+
+    return { locked, polyline };
+}
+
+/**
+ * Largest error any of a group's clusters carries -- the floor a step above them must respect.
+ *
+ * @param {VirtualGeometryCluster[]} clusters
+ * @returns {number}
+ */
+function max_child_error(clusters) {
+    let result = 0;
+
+    for (const cluster of clusters) {
+        result = Math.max(result, cluster.self_error);
+    }
+
+    return result;
+}
+
+/**
+ * Leaves with room to spare between them, re-cut into fewer and fuller leaves.
+ *
+ * This is not a level of the DAG and must not become one. Nothing is simplified, so the new clusters
+ * carry the same error their inputs did -- zero -- and a step whose parent error equals its child
+ * error is a step the cut rule can never take: a cluster is drawn only while `project(parent) > tau`,
+ * and a parent at zero error projects to zero unconditionally. The leaves under it would be stored,
+ * paged, and never once selected. So the re-cut *replaces* them; they were a way of cutting this
+ * geometry up, and now there is a better one.
+ *
+ * It is what makes a scene of small separate parts tractable. A thousand twelve-triangle bolts are a
+ * thousand clusters at eight per cent fill, and no simplification is what they need -- they need to
+ * be cut up differently. Repacking is bounded by the grouping that proposed it, so what lands in one
+ * cluster is what the adjacency and proximity rules already judged to belong together.
+ *
+ * Only leaves. Above them the same re-cut would orphan a subtree, since a coarser cluster cannot be
+ * deleted -- something hangs off it.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {number[]} group_clusters cluster indices
+ * @param {number} parent_target how many clusters the group is aiming to become
+ * @returns {GroupRepack|undefined} `undefined` when the group must be simplified instead
+ */
+function try_repack(frontier, group_clusters, parent_target) {
+    const face_ids = [];
+
+    for (const cluster of group_clusters) {
+        if (frontier.clusters[cluster].child_group !== undefined) {
+            return undefined;
+        }
+
+        for (const face of frontier.cluster_faces[cluster]) {
+            face_ids.push(face);
+        }
+    }
+
+    // Only when the target is already met -- there is nothing to simplify, so the reduction has to
+    // come from re-cutting. A group over its target has real geometry to lose and belongs on the
+    // simplification path.
+    if (face_ids.length > parent_target * VGEO_MAX_CLUSTER_TRIANGLE_COUNT) {
+        return undefined;
+    }
+
+    face_ids.sort((a, b) => a - b);
+
+    const submesh = vgeo_extract_submesh(frontier.mesh, face_ids);
+
+    const face_graph = new VGeoFaceGraph(
+        submesh.mesh.topology, bt_mesh_build_face_graph(submesh.mesh.topology)
+    );
+
+    /**
+     *
+     * @type {number[]}
+     */
+    const all = [];
+
+    const vertex_count = face_graph.graph.vertex_count;
+    for (let vertex = 0; vertex < vertex_count; vertex++) {
+        all.push(vertex);
+    }
+
+    const parts = vgeo_split_face_set_packed(
+        face_graph, all, VGEO_MAX_CLUSTER_TRIANGLE_COUNT, VGEO_MAX_CLUSTER_VERTEX_COUNT
+    );
+
+    if (parts.length >= group_clusters.length) {
+        // The vertex ceiling bit before the triangle one, and re-cutting bought nothing.
+        return undefined;
+    }
+
+    const repack = new GroupRepack();
+
+    repack.replaced = group_clusters.map((cluster) => frontier.clusters[cluster]);
+
+    for (const part of parts) {
+        const part_face_ids = part.map((dense) => face_graph.vertex_face_ids[dense]);
+
+        part_face_ids.sort((a, b) => a - b);
+
+        const built = build_cluster(submesh.mesh, part_face_ids, 0);
+
+        // A leaf's own bounds are its LOD-metric sphere, and it deviates from nothing.
+        built.cluster.self_sphere = built.cluster.bounds_sphere.slice();
+        built.cluster.self_error = 0;
+
+        repack.clusters.push(built.cluster);
+
+        repack.geometry.push({
+            positions: built.gathered.positions,
+            indices: built.gathered.indices,
+            local_vertex_ids: built.gathered.vertex_ids,
+            source_vertex_ids: Uint32Array.from(
+                built.gathered.vertex_ids, (local) => submesh.source_vertex_ids[local]
+            ),
+            topology: submesh.mesh.topology,
+        });
+    }
+
+    return repack;
+}
+
+/**
+ * Simplify one group and cut the result into the parent clusters of every cluster in it.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {number[]} group_clusters cluster indices
+ * @param {Int32Array} group_of_face one entry per face slot, holding the group each face belongs to
+ * @param {number} group_index
+ * @param {number} level of the parents this step produces
+ * @param {VGeoLevelOptions} options
+ * @returns {GroupStep|undefined} `undefined` when the group has no coarser form at all, and the
+ *     round should leave its clusters alone
+ */
+function build_group_step(frontier, group_clusters, group_of_face, group_index, level, options) {
+    /**
+     *
+     * @type {number[]}
+     */
+    const face_ids = [];
+
+    for (const cluster of group_clusters) {
+        for (const face of frontier.cluster_faces[cluster]) {
+            face_ids.push(face);
+        }
+    }
+
+    face_ids.sort((a, b) => a - b);
+
+    const child_clusters = group_clusters.map((cluster) => frontier.clusters[cluster]);
+
+    const boundary = compute_group_boundary(
+        frontier.mesh.topology, face_ids, group_of_face, group_index
+    );
+
+    /**
+     * Extract the group, simplify it to `target_face_count`, and cut the result into clusters.
+     *
+     * @param {number} target_face_count
+     * @returns {{submesh: VGeoSubmesh, face_graph: VGeoFaceGraph, parts: number[][],
+     *     quadrics: Quadric3[], error: number}}
+     */
+    function simplify_to(target_face_count) {
+        const submesh = vgeo_extract_submesh(frontier.mesh, face_ids);
+
+        // Cloned, not borrowed: the simplifier mutates these, and this whole attempt may be thrown
+        // away — by the polyline check below, by the round rejecting it, or by a wider band being
+        // tried instead. The frontier's own quadrics must survive all of that untouched.
+        const submesh_source_vertex_ids = submesh.source_vertex_ids;
+        const source_vertex_id_count = submesh_source_vertex_ids.length;
+
+        /**
+         *
+         * @type {Quadric3[]}
+         */
+        const quadrics = new Array(source_vertex_id_count);
+
+        for (let i = 0; i < source_vertex_id_count; i++) {
+            const source = submesh_source_vertex_ids[i];
+            quadrics[i] = frontier.quadrics[source].clone();
+        }
+
+        /**
+         * `source vertex id -> submesh local id`, for translating the lock set and the polyline.
+         * @type {Map<number, number>}
+         */
+        const local_of_source = new Map();
+
+        for (let local = 0; local < source_vertex_id_count; local++) {
+            const source = submesh_source_vertex_ids[local];
+            local_of_source.set(source, local);
+        }
+
+        /**
+         *
+         * @type {Set<number>}
+         */
+        const locked = new Set();
+
+        for (const vertex of boundary.locked) {
+            const local = local_of_source.get(vertex);
+
+            if (local !== undefined) {
+                locked.add(local);
+            }
+        }
+
+        // The faces carrying the group's boundary edges. Locking the endpoints keeps them where they
+        // are; protecting these faces is what keeps an edge *between* two locked vertices from
+        // losing the only face that holds it — see the polyline check below, which is the same
+        // guarantee stated as an assertion.
+
+        /**
+         *
+         * @type {Set<number>}
+         */
+        const protected_faces = new Set();
+
+        for (const [v1, v2] of boundary.polyline) {
+            const edge = bt_edge_get(
+                submesh.mesh.topology, local_of_source.get(v1), local_of_source.get(v2)
+            );
+
+            if (edge === NULL_POINTER) {
+                continue;
+            }
+
+            const first_loop = submesh.mesh.topology.edge_read_loop(edge);
+
+            let loop = first_loop;
+
+            do {
+                const face = submesh.mesh.topology.loop_read_face(loop);
+
+                if (face !== NULL_POINTER) {
+                    protected_faces.add(face);
+                }
+
+                loop = submesh.mesh.topology.loop_read_radial_next(loop);
+            } while (loop !== first_loop && loop !== NULL_POINTER);
+        }
+
+        // The simplifier measures this itself, and has to: a cluster consumed whole leaves a
+        // vertex behind that belongs to no face and is about to be swept away, and that vertex is
+        // the only thing still holding the quadric of what used to be there. Measuring survivors
+        // from out here would report a soup of separate triangles losing most of itself as free.
+        const deviation = bt_mesh_simplify_with_quadrics(
+            submesh.mesh.topology, target_face_count, locked, protected_faces, quadrics
+        );
+
+        const defects = bt_mesh_validate(submesh.mesh.topology);
+
+        if (defects.length > 0) {
+            throw new Error(
+                `simplifying a group of ${group_clusters.length} clusters left the mesh inconsistent: `
+                + defects.slice(0, 4).map((defect) => defect.detail).join('; ')
+            );
+        }
+
+        // The design asks for this explicitly: pinning a vertex does not by itself protect the
+        // *edges* between pinned vertices, and a face-kill path can strip one. A missing boundary
+        // edge is a crack between two groups that will never close, so the build stops here rather
+        // than shipping it.
+        for (const [v1, v2] of boundary.polyline) {
+            const local_1 = local_of_source.get(v1);
+            const local_2 = local_of_source.get(v2);
+
+            if (
+                local_1 === undefined
+                || local_2 === undefined
+                || bt_edge_get(submesh.mesh.topology, local_1, local_2) === NULL_POINTER
+            ) {
+                throw new Error(
+                    `group boundary edge (${v1}, ${v2}) did not survive simplification of a group of `
+                    + `${group_clusters.length} clusters`
+                );
+            }
+        }
+
+        /*
+         The step moved the geometry, so the frame that describes it has to move with it — but only
+         where the step was free to move anything. `locked` is the group's perimeter, the vertices
+         every neighbouring group also carries, and it is what a cut leans on to put two levels of
+         detail side by side without a crack. Derived here, a perimeter vertex would get the average
+         of this group's faces alone while its neighbour got the average of that group's, and the
+         seam that is watertight in geometry would show as a crease in shading.
+         */
+        vgeo_compute_vertex_normals(submesh.mesh, locked);
+        vgeo_compute_vertex_tangents(submesh.mesh, locked);
+
+        const face_graph = new VGeoFaceGraph(
+            submesh.mesh.topology, bt_mesh_build_face_graph(submesh.mesh.topology)
+        );
+
+        const all = [];
+
+        for (let vertex = 0; vertex < face_graph.graph.vertex_count; vertex++) {
+            all.push(vertex);
+        }
+
+        // Packed: this is a group, so its extent is already the group's, and one cluster per
+        // surviving island would undo the merge the group exists to make.
+        const parts = vgeo_split_face_set_packed(
+            face_graph, all, VGEO_MAX_CLUSTER_TRIANGLE_COUNT, VGEO_MAX_CLUSTER_VERTEX_COUNT
+        );
+
+        return { submesh, face_graph, parts, quadrics, error: deviation };
+    }
+
+    // Aim at a number of *clusters*, not a fraction of the triangles. Halving the triangle count is
+    // a means; halving the cluster count is the end, and asking for it directly is what keeps
+    // parents full. Where the children are already full the two coincide exactly. Where they are
+    // not, this simplifies less — because the reduction is coming from packing the geometry better
+    // rather than from destroying it, which is the outcome to prefer.
+    const parent_target = Math.max(
+        1, Math.ceil(group_clusters.length * options.simplification_ratio)
+    );
+
+    const outcome = simplify_to(Math.min(
+        parent_target * VGEO_MAX_CLUSTER_TRIANGLE_COUNT,
+        // A group of under-filled clusters can already be under the cluster-count target, in which
+        // case nothing would be simplified and the step would record no error — a step the cut rule
+        // cannot take. Falling back to the triangle ratio keeps it a real simplification.
+        Math.max(2, Math.round(face_ids.length * options.simplification_ratio))
+    ));
+
+    if (outcome.parts.length === 0) {
+        // Some small closed shells have no coarser form under edge collapse at all — a tetrahedron
+        // loses two faces to the collapse and its other two to the fuse that follows, leaving
+        // nothing. Nothing to build a parent from, so the group is refused and its clusters go back
+        // to the frontier to be grouped differently.
+        return undefined;
+    }
+
+    const submesh = outcome.submesh;
+    const submesh_face_graph = outcome.face_graph;
+    const parts = outcome.parts;
+
+    const step = new GroupStep();
+
+    step.child_clusters = child_clusters;
+
+    // Floored by what the children already carried. The accumulated quadric is a deviation from the
+    // source and nothing forces it to rise when the vertex carrying the previous maximum is the one
+    // collapsed away — but a parent that claimed to be closer to the source than its own child would
+    // make the cut oscillate, so monotonicity is imposed here rather than hoped for.
+    step.error = Math.max(outcome.error, max_child_error(child_clusters));
+
+    submesh.source_vertex_ids.forEach((source, local) => {
+        if (outcome.quadrics[local] !== null) {
+            step.quadrics.set(source, outcome.quadrics[local]);
+        }
+    });
+
+    const parent_points = [];
+
+    for (const part of parts) {
+        const part_face_ids = part.map((dense) => submesh_face_graph.vertex_face_ids[dense]);
+
+        part_face_ids.sort((a, b) => a - b);
+
+        const built = build_cluster(submesh.mesh, part_face_ids, level);
+
+        step.parent_clusters.push(built.cluster);
+
+        step.parent_geometry.push({
+            positions: built.gathered.positions,
+            indices: built.gathered.indices,
+            local_vertex_ids: built.gathered.vertex_ids,
+            source_vertex_ids: Uint32Array.from(
+                built.gathered.vertex_ids, (local) => submesh.source_vertex_ids[local]
+            ),
+            topology: submesh.mesh.topology,
+        });
+
+        parent_points.push(built.gathered.positions);
+    }
+
+    let point_count = 0;
+
+    for (const points of parent_points) {
+        point_count += points.length;
+    }
+
+    const points = new Float32Array(point_count);
+
+    let cursor = 0;
+
+    for (const part of parent_points) {
+        points.set(part, cursor);
+
+        cursor += part.length;
+    }
+
+    // One sphere for the whole step, containing both what it consumed and what it produced. Sharing
+    // it is what makes every sibling project the same value, and containing the children is what
+    // makes the pair monotonic.
+    step.sphere = vgeo_containing_sphere(
+        step.child_clusters.map((cluster) => cluster.self_sphere),
+        points
+    );
+
+    return step;
+}
+
+/**
+ * Stitch a round's output back into one mesh: freshly simplified clusters, and the clusters the
+ * round left alone, side by side.
+ *
+ * Vertices are unified by the id they had in the frontier below, never by position: a vertex two
+ * groups share is pinned, so both carry it unmoved and unmistakably, while a vertex only one group
+ * holds is its own even if a collapse happened to place it exactly where another landed. An
+ * untouched cluster names its vertices in that same space, so it stitches to its simplified
+ * neighbour along exactly the boundary that neighbour was forbidden to move.
+ *
+ * @param {VGeoContribution[]} contributions parallel to the clusters of the frontier being built
+ * @param {(BinaryDataLayer|null)[]} template_layers the channels the frontier below carries, which
+ *     the frontier being stitched carries too
+ * @returns {{mesh: VirtualGeometryMesh, cluster_faces: number[][], source_vertex_ids: Uint32Array}}
+ *     the last of which names, for every vertex of the new mesh, the vertex of the old one it came
+ *     from — which is how its accumulated quadric follows it across the seam
+ */
+function stitch_frontier(contributions, template_layers) {
+    /**
+     * `source vertex id -> index in the frontier being built`.
+     * @type {Map<number, number>}
+     */
+    const index_of_source = new Map();
+
+    const positions = [];
+    const indices = [];
+    const cluster_faces = [];
+
+    /**
+     * `[mesh the vertex came from, its id there]` per new vertex, so its attribute record can be
+     * copied across once the topology that receives it exists.
+     * @type {[BinaryTopology, number][]}
+     */
+    const attribute_sources = [];
+
+    let face_cursor = 0;
+
+    for (const geometry of contributions) {
+        const remap = new Uint32Array(geometry.local_vertex_ids.length);
+
+        geometry.local_vertex_ids.forEach((local, i) => {
+            const source = geometry.source_vertex_ids[i];
+
+            let target = index_of_source.get(source);
+
+            if (target === undefined) {
+                target = positions.length / 3;
+
+                index_of_source.set(source, target);
+
+                positions.push(
+                    geometry.positions[i * 3],
+                    geometry.positions[i * 3 + 1],
+                    geometry.positions[i * 3 + 2]
+                );
+
+                attribute_sources.push([geometry.topology, local]);
+            }
+
+            remap[i] = target;
+        });
+
+        const triangle_count = geometry.indices.length / 3;
+
+        const faces = [];
+
+        for (let i = 0; i < geometry.indices.length; i++) {
+            indices.push(remap[geometry.indices[i]]);
+        }
+
+        for (let i = 0; i < triangle_count; i++) {
+            faces.push(face_cursor + i);
+        }
+
+        face_cursor += triangle_count;
+
+        cluster_faces.push(faces);
+    }
+
+    const topology = new BinaryTopology();
+
+    // Before the vertices: adding a layer widens every record already in the block, and a frontier
+    // holds every vertex of a level.
+    const layers = vgeo_layers_like(topology, template_layers);
+
+    bt_mesh_from_indexed_geometry(topology, Uint32Array.from(indices), Float32Array.from(positions));
+
+    attribute_sources.forEach(([source, local], target) => {
+        vgeo_layers_copy_vertex(topology, source, local, target);
+    });
+
+    const mesh = new VirtualGeometryMesh(topology, layers);
+
+    const source_vertex_ids = new Uint32Array(index_of_source.size);
+
+    for (const [source, target] of index_of_source) {
+        source_vertex_ids[target] = source;
+    }
+
+    return { mesh, cluster_faces, source_vertex_ids };
+}
+
+/**
+ * The frontier's clusters ordered by error, which is what a band is a slice of.
+ *
+ * @param {VGeoFrontier} frontier
+ * @returns {{order: number[], errors: number[]}} cluster indices ascending by error, and their
+ *     errors in the same order
+ */
+function order_by_error(frontier) {
+    const order = frontier.clusters.map((cluster, index) => index);
+
+    order.sort(
+        (a, b) => (frontier.clusters[a].self_error - frontier.clusters[b].self_error) || (a - b)
+    );
+
+    return { order, errors: order.map((index) => frontier.clusters[index].self_error) };
+}
+
+/**
+ * The bands a round tries, in the order it tries them.
+ *
+ * Each is one error *octave*: `[e, e · growth]` for each distinct error the frontier holds, finest
+ * first. An octave rather than a running threshold is what bounds how far apart two clusters in one
+ * group can be — a group shares a single parent error, so merging a nearly-exact cluster with a
+ * badly-approximated one drags the exact one up to the other's error for nothing. It is also what
+ * lets a cluster *wait*: geometry outside the octave is simply not this round's business.
+ *
+ * The last band is the whole frontier. It is the escape hatch, not the plan: a frontier of two
+ * clusters an order of magnitude apart in error has no octave holding both, and merging them at a
+ * wide error span still beats never reaching a root.
+ *
+ * @param {number[]} errors ascending, as {@link order_by_error} returns
+ * @param {number} growth
+ * @param {number} min_fraction least share of the frontier a band may cover
+ * @returns {{start: number, end: number}[]} half-open ranges into the error order, deduplicated
+ */
+function error_bands(errors, growth, min_fraction) {
+    /**
+     * @param {number} value
+     * @returns {number} first position whose error exceeds `value`
+     */
+    function upper_bound(value) {
+        let low = 0;
+        let high = errors.length;
+
+        while (low < high) {
+            const middle = (low + high) >> 1;
+
+            if (errors[middle] <= value) {
+                low = middle + 1;
+            } else {
+                high = middle;
+            }
+        }
+
+        return low;
+    }
+
+    const result = [];
+    const seen = new Set();
+
+    /**
+     * @param {number} start
+     * @param {number} end
+     */
+    function add(start, end) {
+        const key = `${start}:${end}`;
+
+        if (end - start < 2 || seen.has(key)) {
+            return;
+        }
+
+        seen.add(key);
+
+        result.push({ start, end });
+    }
+
+    const minimum = Math.max(2, Math.ceil(errors.length * min_fraction));
+
+    let cursor = 0;
+
+    while (cursor < errors.length) {
+        const low = errors[cursor];
+
+        add(cursor, Math.max(upper_bound(low * growth), Math.min(errors.length, cursor + minimum)));
+
+        cursor = upper_bound(low);
+    }
+
+    add(0, errors.length);
+
+    return result;
+}
+
+/**
+ * One round: pick a band, group it, simplify each group, and report what it produced.
+ *
+ * Every group is speculative and judged on its own. One that comes back with no fewer clusters than
+ * it consumed is simply dropped — its clusters return to the frontier, to be grouped differently by
+ * a later round — rather than failing the round for everyone else. A group that cannot be
+ * simplified is no different in kind from a group that could not be formed, and the frontier already
+ * knows what to do with those: nothing, for now.
+ *
+ * The round as a whole is accepted only when it *strictly* shrinks the frontier. Failing that it
+ * widens the band, and failing that it grows the group — small groups starve the simplifier, and a
+ * wider band gives a fine region coarser neighbours to merge with.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {number} level of the parents this round would produce
+ * @param {VGeoLevelOptions} options
+ * @returns {{steps: GroupStep[], repacks: GroupRepack[], merged: Set<number>}|undefined} what to
+ *     commit and which frontier clusters it consumed; `undefined` when nothing this round could try
+ *     made the frontier smaller
+ */
+function run_round(frontier, level, options) {
+    const face_graph = new VGeoFaceGraph(
+        frontier.mesh.topology, bt_mesh_build_face_graph(frontier.mesh.topology)
+    );
+
+    const cluster_graph = build_cluster_graph(frontier, face_graph);
+
+    const ordered = order_by_error(frontier);
+
+    const bands = error_bands(
+        ordered.errors, options.error_band_growth, options.error_band_min_fraction
+    );
+
+    let group_size = options.group_size;
+
+    for (; ;) {
+        for (const range of bands) {
+            const band = ordered.order.slice(range.start, range.end);
+
+            band.sort((a, b) => a - b);
+
+            const groups = partition_into_groups(frontier, band, cluster_graph, group_size);
+
+            if (groups.length === 0) {
+                continue;
+            }
+
+            const group_of_face = new Int32Array(frontier.mesh.topology.faces.size).fill(-1);
+
+            groups.forEach((group, group_index) => {
+                for (const cluster of group) {
+                    for (const face of frontier.cluster_faces[cluster]) {
+                        group_of_face[face] = group_index;
+                    }
+                }
+            });
+
+            const steps = [];
+            const repacks = [];
+
+            let consumed = 0;
+            let produced = 0;
+
+            const merged = new Set();
+
+            groups.forEach((group, group_index) => {
+                const parent_target = Math.max(
+                    1, Math.ceil(group.length * options.simplification_ratio)
+                );
+
+                const repack = try_repack(frontier, group, parent_target);
+
+                if (repack !== undefined) {
+                    repacks.push(repack);
+
+                    consumed += group.length;
+                    produced += repack.clusters.length;
+
+                    for (const cluster of group) {
+                        merged.add(cluster);
+                    }
+
+                    return;
+                }
+
+                const step = build_group_step(
+                    frontier, group, group_of_face, group_index, level, options
+                );
+
+                if (step === undefined || step.parent_clusters.length >= group.length) {
+                    // Refused. Nothing has been mutated — the step worked on a copy of the geometry
+                    // and a copy of the quadrics — so its clusters simply stay where they are.
+                    return;
+                }
+
+                steps.push(step);
+
+                consumed += group.length;
+                produced += step.parent_clusters.length;
+
+                for (const cluster of group) {
+                    merged.add(cluster);
+                }
+            });
+
+            if (produced < consumed) {
+                return { steps, repacks, merged };
+            }
+        }
+
+        // No band made progress. Growing the group gives the simplifier more interior to work with
+        // relative to its locked perimeter, which is the thing that stalls first.
+        if (group_size >= frontier.clusters.length) {
+            return undefined;
+        }
+
+        group_size = Math.min(frontier.clusters.length, group_size * 2);
+    }
+}
+
+const scratch_quadric = new Quadric3();
+
+/**
+ * Build the whole DAG, from a source mesh to a single root.
+ *
+ * @param {VirtualGeometryMesh} mesh the normalized source; consumed, not copied
+ * @param {VGeoLevelOptions} options
+ * @returns {VGeoLevel[]} leaves first; the last level holds exactly one cluster, the root
+ */
+export function vgeo_build_levels(mesh, options) {
+    assert.isPositiveInteger(options.group_size, 'options.group_size');
+    assert.greaterThan(options.group_size, 1, 'options.group_size');
+    assert.greaterThan(options.simplification_ratio, 0, 'options.simplification_ratio');
+    assert.lessThan(options.simplification_ratio, 1, 'options.simplification_ratio');
+    assert.greaterThan(options.error_band_growth, 1, 'options.error_band_growth');
+    assert.greaterThan(options.error_band_min_fraction, 0, 'options.error_band_min_fraction');
+    assert.lessThanOrEqual(options.error_band_min_fraction, 1, 'options.error_band_min_fraction');
+    assert.isPositiveInteger(options.max_levels, 'options.max_levels');
+
+    let frontier = build_leaf_frontier(mesh);
+
+    const leaves = new VGeoLevel();
+
+    leaves.index = 0;
+    leaves.clusters = frontier.clusters.slice();
+
+    const levels = [leaves];
+
+    while (frontier.clusters.length > 1) {
+        if (levels.length >= options.max_levels) {
+            throw new Error(
+                `the DAG still holds ${frontier.clusters.length} clusters after ${levels.length} `
+                + `levels, which is as many as the container can name`
+            );
+        }
+
+        const level = levels.length;
+
+        const round = run_round(frontier, level, options);
+
+        if (round === undefined) {
+            throw new Error(
+                `the DAG stopped converging with ${frontier.clusters.length} clusters left: no `
+                + `grouping of the frontier produced fewer clusters than it consumed, so the build `
+                + `has no single root to start a cut from`
+            );
+        }
+
+        const next = new VGeoLevel();
+
+        next.index = level;
+
+        /**
+         * @type {VGeoContribution[]}
+         */
+        const contributions = [];
+
+        const clusters = [];
+
+        // Untouched clusters first, in the order they already had, then this round's output. All of
+        // them name their vertices in the frontier that is being replaced, which is what lets them
+        // be stitched into one mesh.
+        frontier.clusters.forEach((cluster, index) => {
+            if (round.merged.has(index)) {
+                return;
+            }
+
+            const gathered = vgeo_gather_faces(frontier.mesh, frontier.cluster_faces[index]);
+
+            clusters.push(cluster);
+
+            contributions.push({
+                positions: gathered.positions,
+                indices: gathered.indices,
+                local_vertex_ids: gathered.vertex_ids,
+                source_vertex_ids: gathered.vertex_ids,
+                topology: frontier.mesh.topology,
+            });
+        });
+
+        if (round.repacks.length > 0) {
+            const replaced = new Set();
+
+            for (const repack of round.repacks) {
+                for (const leaf of repack.replaced) {
+                    replaced.add(leaf);
+                }
+            }
+
+            // One pass over the leaf level for the whole round. Per repack it would be a scan of
+            // every leaf in the asset, and a scene of small parts is nothing but repacks.
+            leaves.clusters = leaves.clusters.filter((cluster) => !replaced.has(cluster));
+
+            for (const repack of round.repacks) {
+                repack.clusters.forEach((cluster, index) => {
+                    leaves.clusters.push(cluster);
+
+                    clusters.push(cluster);
+                    contributions.push(repack.geometry[index]);
+                });
+            }
+        }
+
+        for (const step of round.steps) {
+            const group = new VirtualGeometryGroup();
+
+            // The group sits one band below the parents it produced, which is what makes page order
+            // by descending level a topological order of the DAG.
+            group.level = level - 1;
+            group.clusters = step.child_clusters;
+
+            for (const cluster of step.child_clusters) {
+                cluster.parent_error = step.error;
+                cluster.parent_sphere = step.sphere;
+            }
+
+            step.parent_clusters.forEach((parent, index) => {
+                parent.self_error = step.error;
+                parent.self_sphere = step.sphere;
+                parent.child_group = group;
+
+                next.clusters.push(parent);
+                clusters.push(parent);
+                contributions.push(step.parent_geometry[index]);
+            });
+
+            levels[level - 1].groups.push(group);
+        }
+
+        if (next.clusters.length > 0) {
+            levels.push(next);
+        }
+
+        // Fold every step's quadric gains back into the frontier's own set, before it is re-indexed.
+        //
+        // Gains, not results: two steps that share a pinned boundary vertex each started from this
+        // vertex's quadric and each accumulated their own victims onto it, so the two results
+        // overlap by exactly the quadric they both began with. Adding them whole would count the
+        // source planes under that vertex twice and inflate every error above it.
+        const updated = frontier.quadrics.slice();
+
+        for (const step of round.steps) {
+            for (const [vertex, quadric] of step.quadrics) {
+
+                scratch_quadric.copy(quadric);
+                scratch_quadric.sub(frontier.quadrics[vertex]);
+
+                const next = updated[vertex].clone();
+                next.add(scratch_quadric);
+
+                updated[vertex] = next;
+
+            }
+        }
+
+        const stitched = stitch_frontier(contributions, frontier.mesh.layers);
+
+        frontier = new VGeoFrontier();
+
+        frontier.mesh = stitched.mesh;
+        frontier.clusters = clusters;
+        frontier.cluster_faces = stitched.cluster_faces;
+        frontier.quadrics = Array.from(
+            stitched.source_vertex_ids, (source) => updated[source]
+        );
+    }
+
+    const top = levels[levels.length - 1];
+
+    assert.equal(
+        top.clusters.length, 1,
+        'the topmost level must hold the single root the frontier converged to'
+    );
+
+    assert.equal(
+        top.clusters[0], frontier.clusters[0],
+        'the cluster the frontier converged to must be the one the topmost level holds'
+    );
+
+    return levels;
+}