@woosh/meep-engine 3.27.0 → 3.29.0

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

@@ -0,0 +1,11 @@
+/**
+ * Build the whole DAG, from a source mesh to a single root.
+ *
+ * @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: VirtualGeometryMesh, options: VGeoLevelOptions, attribute_weights?: Float64Array): VGeoLevel[];
+import { VGeoLevel } from "./VGeoLevel.js";
+//# sourceMappingURL=vgeo_build_levels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_build_levels.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_build_levels.js"],"names":[],"mappings":"AAoEA;;;;;;;GAOG;AACH,4GAHW,YAAY,GACV,SAAS,EAAE,CAyOvB;0BA3SyB,gBAAgB"}

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

@@ -0,0 +1,308 @@
+import { assert } from "../../../../../../core/assert.js";
+import { Quadric3 } from "../../../../../../core/geom/3d/quadric/Quadric3.js";
+import {
+    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";
+
+/**
+ * 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 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`).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+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
+ * @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, 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');
+    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 = vgeo_build_leaf_frontier(mesh, attribute_weights);
+
+    const leaves = new VGeoLevel();
+
+    leaves.index = 0;
+    leaves.clusters = frontier.clusters.slice();
+
+    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 deep as a build is allowed to go`
+            );
+        }
+
+        const level = levels.length;
+
+        const round = vgeo_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], frontier.wedges
+            );
+
+            clusters.push(cluster);
+
+            contributions.push({
+                positions: gathered.positions,
+                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,
+            });
+        });
+
+        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();
+
+        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) {
+
+                scratch_quadric.copy(quadric);
+                scratch_quadric.sub(frontier.quadrics[vertex]);
+
+                const next = updated[vertex].clone();
+                next.add(scratch_quadric);
+
+                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 = vgeo_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]
+        );
+
+        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];
+
+    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;
+}

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

@@ -15,5 +15,5 @@
  * @copyright Company Named Limited (c) 2026
  */
 export function vgeo_build_root_group(cluster: VirtualGeometryCluster, level: number): VirtualGeometryGroup;
-import { VirtualGeometryGroup } from "../format/dag/VirtualGeometryGroup.js";
+import { VirtualGeometryGroup } from "../../format/dag/VirtualGeometryGroup.js";
 //# sourceMappingURL=vgeo_build_root_group.d.ts.map

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

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

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

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

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

@@ -0,0 +1,26 @@
+/**
+ * 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
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_compute_group_boundary(topology: BinaryTopology, group_face_ids: number[], group_of_face: Int32Array, group_index: number): {
+    locked: Set<number>;
+    polyline: number[][];
+};
+//# sourceMappingURL=vgeo_compute_group_boundary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_compute_group_boundary.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_compute_group_boundary.js"],"names":[],"mappings":"AAiEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sFATW,MAAM,EAAE,iBACR,UAAU,eACV,MAAM,GACJ;IAAC,MAAM,EAAE,IAAI,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAA;CAAC,CA0CvD"}

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

@@ -0,0 +1,123 @@
+import { NULL_POINTER } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+
+/**
+ * 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
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_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 };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * 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 the frontier's cluster errors, ascending
+ * @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
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_error_bands(errors: number[], growth: number, min_fraction: number): {
+    start: number;
+    end: number;
+}[];
+//# sourceMappingURL=vgeo_error_bands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_error_bands.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_error_bands.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,yCARW,MAAM,EAAE,UACR,MAAM,gBACN,MAAM,GACJ;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,EAAE,CA6D1C"}

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

@@ -0,0 +1,78 @@
+/**
+ * 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 the frontier's cluster errors, ascending
+ * @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
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_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;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * 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 vgeo_build_cluster_graph} returns
+ * @param {number} group_size
+ * @returns {number[][]} groups of at least two clusters each; clusters left out stay in the frontier
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_partition_into_groups(frontier: VGeoFrontier, band: number[], cluster_graph: object, group_size: number): number[][];
+//# sourceMappingURL=vgeo_partition_into_groups.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_partition_into_groups.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_partition_into_groups.js"],"names":[],"mappings":"AA0MA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yEARW,MAAM,EAAE,iBACR,MAAM,cACN,MAAM,GACJ,MAAM,EAAE,EAAE,CAqHtB"}