@woosh/meep-engine 3.28.0 → 3.29.0

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"}

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

@@ -0,0 +1,337 @@
+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 { 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 { vgeo_graph_components } from "../partition/vgeo_graph_components.js";
+import { vgeo_partition_subgraph } from "../partition/vgeo_partition_subgraph.js";
+
+/**
+ * Fixed so that the same frontier always groups the same way.
+ * @readonly
+ * @type {number}
+ */
+const GROUP_SEED = 0x6D05;
+
+/**
+ * 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 vgeo_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 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, 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;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * One round: pick a band, group it, simplify each group, and report what it produced.
+ *
+ * Every group is speculative and judged on its own. One that comes back with no fewer clusters than
+ * it consumed is simply dropped — its clusters return to the frontier, to be grouped differently by
+ * a later round — rather than failing the round for everyone else. A group that cannot be
+ * simplified is no different in kind from a group that could not be formed, and the frontier already
+ * knows what to do with those: nothing, for now.
+ *
+ * The round as a whole is accepted only when it *strictly* shrinks the frontier. Failing that it
+ * widens the band, and failing that it grows the group — small groups starve the simplifier, and a
+ * wider band gives a fine region coarser neighbours to merge with.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {number} level of the parents this round would produce
+ * @param {VGeoLevelOptions} options
+ * @returns {{steps: VGeoGroupStep[], repacks: VGeoGroupRepack[], 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
+ */
+export function vgeo_run_round(frontier: VGeoFrontier, level: number, options: VGeoLevelOptions): {
+    steps: VGeoGroupStep[];
+    repacks: VGeoGroupRepack[];
+    merged: Set<number>;
+} | undefined;
+//# sourceMappingURL=vgeo_run_round.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_run_round.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_run_round.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8DATW,MAAM,8BAEJ;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,IAAI,MAAM,CAAC,CAAA;CAAC,GAAC,SAAS,CAyG/F"}