@woosh/meep-engine 3.28.0 → 3.30.0

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

@@ -1,1573 +1,68 @@
 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 "../sphere/vgeo_bounding_sphere.js";
-import { vgeo_compute_vertex_normals } from "../mesh/vgeo_compute_vertex_normals.js";
-import { vgeo_compute_vertex_tangents } from "../mesh/vgeo_compute_vertex_tangents.js";
-import { vgeo_containing_sphere } from "../sphere/vgeo_containing_sphere.js";
-import { vgeo_extract_submesh } from "../submesh/vgeo_extract_submesh.js";
-import { vgeo_gather_faces } from "../submesh/vgeo_gather_faces.js";
-import { vgeo_graph_components } from "../partition/vgeo_graph_components.js";
-import { vgeo_narrow_indices } from "../submesh/vgeo_narrow_indices.js";
-import { vgeo_partition_subgraph } from "../partition/vgeo_partition_subgraph.js";
-import { vgeo_split_face_set } from "../partition/vgeo_split_face_set.js";
-import { vgeo_split_face_set_packed } from "../partition/vgeo_split_face_set_packed.js";
-import { VGeoFaceGraph } from "../partition/VGeoFaceGraph.js";
-import { VGeoLevel } from "./VGeoLevel.js";
-import { VirtualGeometryMesh } from "../mesh/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 [];
-    }
-
-    // Gathered rather than read through the cluster list twice: the bounds and the codes are the
-    // same points, and this is the shape `vgeo_split_face_set_packed` already packs in.
-    const centres = new Float32Array(loose.length * 3);
-
-    loose.forEach((cluster, index) => {
-        const sphere = frontier.clusters[cluster].bounds_sphere;
-
-        centres[index * 3] = sphere[0];
-        centres[index * 3 + 1] = sphere[1];
-        centres[index * 3 + 2] = sphere[2];
-    });
-
-    const bounds = new Float32Array(6);
-
-    aabb3_from_v3_array(bounds, centres, centres.length);
-
-    /**
-     * @type {Map<number, number>}
-     */
-    const codes = new Map();
-
-    loose.forEach((cluster, index) => {
-        codes.set(cluster, v3_morton_encode_bounded(
-            centres[index * 3], centres[index * 3 + 1], centres[index * 3 + 2], bounds
-        ));
-    });
-
-    const order = loose.slice();
-
-    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);
-
-    /**
-     * Dense rather than a `Map`, and hoisted out of the component loop so it is one allocation per
-     * level. See {@link vgeo_partition_subgraph} for why the density is load-bearing rather than a
-     * micro-optimisation.
-     * @type {Uint32Array}
-     */
-    const local_index = new Uint32Array(frontier.clusters.length);
-
-    for (const cluster of band) {
-        membership[cluster] = 0;
-    }
-
-    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 parts = vgeo_partition_subgraph(
-            cluster_graph, component, membership, token, part_count, GROUP_SEED, local_index
-        );
-
-        for (const part of parts) {
-            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) };
-}
+    quadric_attribute_size
+} from "../../../../../../core/geom/3d/quadric/quadric_attribute_size.js";
+import { VirtualGeometryGroup } from "../../format/dag/VirtualGeometryGroup.js";
+import { vgeo_gather_faces } from "../submesh/vgeo_gather_faces.js";
+import { VGeoFrontier } from "./VGeoFrontier.js";
+import { VGeoLevel } from "./VGeoLevel.js";
+import { vgeo_build_leaf_frontier } from "./vgeo_build_leaf_frontier.js";
+import { vgeo_run_round } from "./vgeo_run_round.js";
+import { vgeo_stitch_frontier } from "./vgeo_stitch_frontier.js";
 
 /**
- * The bands a round tries, in the order it tries them.
+ * Build the cluster DAG: leaves out of the source mesh, then merge steps until one cluster is left.
  *
- * 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 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 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.
+ * **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.
  *
- * @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.
+ * **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.
  *
- * 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.
+ * **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.
  *
- * 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.
+ * **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 group whose re-cut wants as many clusters as
+ * it consumed is simplified further rather than dropped — a cluster is bounded by its vertices as
+ * well as by its triangles, and on geometry that has come apart it is the vertices that bind, so a
+ * triangle target alone cannot say whether the result will fit. 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.
+ *
+ * The round itself is `vgeo_run_round`: it builds the cluster graph (`vgeo_build_cluster_graph`),
+ * slices the frontier into error octaves (`vgeo_error_bands`), groups a band
+ * (`vgeo_partition_into_groups`), and asks each group for a re-cut (`vgeo_try_repack`) or a
+ * simplification (`vgeo_build_group_step`, which locks the perimeter through
+ * `vgeo_compute_group_boundary`). What is left here is what a round cannot do on its own: the leaf
+ * frontier it starts from (`vgeo_build_leaf_frontier`), committing a round's output into levels and
+ * groups, folding the quadric gains back, and stitching the next frontier (`vgeo_stitch_frontier`).
  *
- * @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
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
  */
-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();
 
@@ -1576,9 +71,10 @@ const scratch_quadric = new Quadric3();
  *
  * @param {VirtualGeometryMesh} mesh the normalized source; consumed, not copied
  * @param {VGeoLevelOptions} options
+ * @param {Float64Array} [attribute_weights] see {@link vgeo_build_leaf_frontier}, which defaults it
  * @returns {VGeoLevel[]} leaves first; the last level holds exactly one cluster, the root
  */
-export function vgeo_build_levels(mesh, options) {
+export function vgeo_build_levels(mesh, options, attribute_weights) {
     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');
@@ -1588,7 +84,7 @@ export function vgeo_build_levels(mesh, options) {
     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);
+    let frontier = vgeo_build_leaf_frontier(mesh, attribute_weights);
 
     const leaves = new VGeoLevel();
 
@@ -1597,17 +93,22 @@ export function vgeo_build_levels(mesh, options) {
 
     const levels = [leaves];
 
+    // Constant for the whole build: the channel set is the source's, and the weights were resolved
+    // off its bounds before any pass had removed anything.
+    const attribute_layout = frontier.attribute_layout;
+    const resolved_attribute_weights = frontier.attribute_weights;
+
     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`
+                + `levels, which is as deep as a build is allowed to go`
             );
         }
 
         const level = levels.length;
 
-        const round = run_round(frontier, level, options);
+        const round = vgeo_run_round(frontier, level, options);
 
         if (round === undefined) {
             throw new Error(
@@ -1636,7 +137,9 @@ export function vgeo_build_levels(mesh, options) {
                 return;
             }
 
-            const gathered = vgeo_gather_faces(frontier.mesh, frontier.cluster_faces[index]);
+            const gathered = vgeo_gather_faces(
+                frontier.mesh, frontier.cluster_faces[index], frontier.wedges
+            );
 
             clusters.push(cluster);
 
@@ -1645,6 +148,10 @@ export function vgeo_build_levels(mesh, options) {
                 indices: gathered.indices,
                 local_vertex_ids: gathered.vertex_ids,
                 source_vertex_ids: gathered.vertex_ids,
+                attribute_ids: gathered.attribute_ids,
+                // Already the frontier's own ids: an untouched cluster is named in the space it is
+                // being stitched out of.
+                source_wedge_ids: gathered.wedge_ids,
                 topology: frontier.mesh.topology,
             });
         });
@@ -1710,6 +217,15 @@ export function vgeo_build_levels(mesh, options) {
         // source planes under that vertex twice and inflate every error above it.
         const updated = frontier.quadrics.slice();
 
+        const attribute_stride = frontier.attribute_layout.components > 0
+            ? quadric_attribute_size(frontier.attribute_layout.components)
+            : 0;
+
+        // One copy of the whole set, then gains added into it in place. The attribute quadrics are
+        // one flat buffer rather than an object each, so this is a single `slice` where the
+        // geometric set above is an array of references and a `clone` per vertex that moved.
+        const updated_attributes = frontier.attribute_quadrics.slice();
+
         for (const step of round.steps) {
             for (const [vertex, quadric] of step.quadrics) {
 
@@ -1722,9 +238,26 @@ export function vgeo_build_levels(mesh, options) {
                 updated[vertex] = next;
 
             }
+
+            step.attribute_source_wedge_ids.forEach((wedge, local) => {
+                // `live_wedges` is what says the wedge survived the step; the attribute buffer is
+                // handed over whole and has an entry for every slot the submesh ever had. A wedge
+                // that merged into another gave that one its quadric and has nothing left to fold.
+                if (!step.live_wedges.has(local)) {
+                    return;
+                }
+
+                const base = wedge * attribute_stride;
+                const from = local * attribute_stride;
+
+                for (let i = 0; i < attribute_stride; i++) {
+                    updated_attributes[base + i] +=
+                        step.attribute_quadrics[from + i] - frontier.attribute_quadrics[base + i];
+                }
+            });
         }
 
-        const stitched = stitch_frontier(contributions, frontier.mesh.layers);
+        const stitched = vgeo_stitch_frontier(contributions, frontier.mesh.layers);
 
         frontier = new VGeoFrontier();
 
@@ -1734,6 +267,29 @@ export function vgeo_build_levels(mesh, options) {
         frontier.quadrics = Array.from(
             stitched.source_vertex_ids, (source) => updated[source]
         );
+
+        frontier.attribute_layout = attribute_layout;
+        frontier.attribute_weights = resolved_attribute_weights;
+        frontier.wedges = stitched.wedges;
+
+        if (attribute_stride > 0) {
+            // Re-indexed by *wedge*, which the stitch has just handed out fresh ids for, exactly as
+            // the geometric set above is re-indexed by vertex.
+            const next_attributes = new Float64Array(
+                stitched.source_wedge_ids.length * attribute_stride
+            );
+
+            stitched.source_wedge_ids.forEach((source, target) => {
+                next_attributes.set(
+                    updated_attributes.subarray(
+                        source * attribute_stride, (source + 1) * attribute_stride
+                    ),
+                    target * attribute_stride
+                );
+            });
+
+            frontier.attribute_quadrics = next_attributes;
+        }
     }
 
     const top = levels[levels.length - 1];