@woosh/meep-engine 3.28.0 → 3.30.0

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

@@ -0,0 +1,147 @@
+import { bt_mesh_build_face_graph } from "../../../../../../core/graph/metis/bt_mesh_build_face_graph.js";
+import { VGeoFaceGraph } from "../partition/VGeoFaceGraph.js";
+import { vgeo_build_cluster_graph } from "./vgeo_build_cluster_graph.js";
+import { vgeo_build_group_step } from "./vgeo_build_group_step.js";
+import { vgeo_error_bands } from "./vgeo_error_bands.js";
+import { vgeo_partition_into_groups } from "./vgeo_partition_into_groups.js";
+import { vgeo_try_repack } from "./vgeo_try_repack.js";
+
+/**
+ * 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) };
+}
+
+/**
+ * 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, level, options) {
+    const face_graph = new VGeoFaceGraph(
+        frontier.mesh.topology, bt_mesh_build_face_graph(frontier.mesh.topology), frontier.wedges
+    );
+
+    const cluster_graph = vgeo_build_cluster_graph(frontier, face_graph);
+
+    const ordered = order_by_error(frontier);
+
+    const bands = vgeo_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 = vgeo_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 = vgeo_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 = vgeo_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);
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ *
+ * **Wedges are unified the same way and separately**, by the frontier wedge each contributed corner
+ * came from. Two contributions that share a pinned boundary vertex name the same wedges there, so
+ * they arrive as one and the seam shades continuously; a wedge only one group has — one a collapse
+ * inside it adopted, say — is its own, which is right, because its corners are that group's alone.
+ * The new frontier's wedge ids are handed out here, and they are what the round's accumulated
+ * attribute quadrics are re-indexed into.
+ *
+ * @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, wedges: BtWedgeSet, source_wedge_ids: Uint32Array}}
+ *     the two id maps naming, for every vertex and every wedge of the new mesh, the one of the old
+ *     mesh it came from — which is how the accumulated quadrics follow it across the seam
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_stitch_frontier(contributions: VGeoContribution[], template_layers: (BinaryDataLayer | null)[]): {
+    mesh: VirtualGeometryMesh;
+    cluster_faces: number[][];
+    source_vertex_ids: Uint32Array;
+    wedges: BtWedgeSet;
+    source_wedge_ids: Uint32Array;
+};
+import { VirtualGeometryMesh } from "../mesh/VirtualGeometryMesh.js";
+import { BtWedgeSet } from "../../../../../../core/geom/3d/topology/struct/binary/BtWedgeSet.js";
+//# sourceMappingURL=vgeo_stitch_frontier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_stitch_frontier.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_stitch_frontier.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,oDAVW,gBAAgB,EAAE,mBAClB,CAAC,kBAAgB,IAAI,CAAC,EAAE,GAEtB;IAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,iBAAiB,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,gBAAgB,EAAE,WAAW,CAAA;CAAC,CAmNrJ;oCAzOmC,gCAAgC;2BANzC,qEAAqE"}

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

@@ -0,0 +1,243 @@
+import {
+    BinaryTopology, NULL_POINTER
+} from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { BtWedgeSet } from "../../../../../../core/geom/3d/topology/struct/binary/BtWedgeSet.js";
+import {
+    bt_mesh_from_indexed_geometry
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
+import { vgeo_layers_copy_corner } from "../../format/attribute/vgeo_layers_copy_corner.js";
+import { vgeo_layers_like } from "../../format/attribute/vgeo_layers_like.js";
+import { VirtualGeometryMesh } from "../mesh/VirtualGeometryMesh.js";
+
+/**
+ * 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.
+ *
+ * **Wedges are unified the same way and separately**, by the frontier wedge each contributed corner
+ * came from. Two contributions that share a pinned boundary vertex name the same wedges there, so
+ * they arrive as one and the seam shades continuously; a wedge only one group has — one a collapse
+ * inside it adopted, say — is its own, which is right, because its corners are that group's alone.
+ * The new frontier's wedge ids are handed out here, and they are what the round's accumulated
+ * attribute quadrics are re-indexed into.
+ *
+ * @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, wedges: BtWedgeSet, source_wedge_ids: Uint32Array}}
+ *     the two id maps naming, for every vertex and every wedge of the new mesh, the one of the old
+ *     mesh it came from — which is how the accumulated quadrics follow it across the seam
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_stitch_frontier(contributions, template_layers) {
+    /**
+     * `source vertex id -> index in the frontier being built`.
+     * @type {Map<number, number>}
+     */
+    const index_of_source = new Map();
+
+    /**
+     * `source wedge id -> wedge index in the frontier being built`.
+     * @type {Map<number, number>}
+     */
+    const wedge_of_source = new Map();
+
+    const positions = [];
+    const indices = [];
+    const cluster_faces = [];
+
+    const source_wedge_ids = [];
+
+    /**
+     * The mesh each contribution's corners are named in, so a corner needs an index rather than a
+     * reference.
+     * @type {BinaryTopology[]}
+     */
+    const topologies = contributions.map((geometry) => geometry.topology);
+
+    let corner_count = 0;
+
+    for (const geometry of contributions) {
+        corner_count += geometry.indices.length;
+    }
+
+    /*
+     Per output corner, where its record comes from. Per *corner*, not per vertex: a seam vertex's
+     corners disagree, and picking a representative is exactly the thing that lost them — which is
+     six entries per triangle rather than one per vertex, so they are typed arrays sized up front
+     rather than lists that grow.
+     */
+    const corner_contribution = new Uint32Array(corner_count);
+    const corner_loop = new Uint32Array(corner_count);
+    const corner_wedge = new Uint32Array(corner_count);
+
+    let corner_cursor = 0;
+    let face_cursor = 0;
+
+    for (const geometry of contributions) {
+        const remap = new Uint32Array(geometry.local_vertex_ids.length);
+        const wedges = 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]
+                );
+            }
+
+            remap[i] = target;
+
+            const source_wedge = geometry.source_wedge_ids[i];
+
+            let wedge = wedge_of_source.get(source_wedge);
+
+            if (wedge === undefined) {
+                wedge = source_wedge_ids.length;
+
+                wedge_of_source.set(source_wedge, wedge);
+                source_wedge_ids.push(source_wedge);
+            }
+
+            wedges[i] = wedge;
+        });
+
+        const triangle_count = geometry.indices.length / 3;
+
+        const faces = [];
+
+        const contribution = cluster_faces.length;
+
+        for (let i = 0; i < geometry.indices.length; i++) {
+            const local = geometry.indices[i];
+
+            indices.push(remap[local]);
+
+            corner_contribution[corner_cursor] = contribution;
+            corner_loop[corner_cursor] = geometry.attribute_ids[local];
+            corner_wedge[corner_cursor] = wedges[local];
+
+            corner_cursor++;
+        }
+
+        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));
+
+    if (topology.faces.count() !== face_cursor) {
+        // The corner walk below reads face `t` as the `t`th triangle of the index list. See
+        // `vgeo_extract_submesh`, which throws for the same reason and cannot use an assert either.
+        throw new Error(
+            `stitching ${face_cursor} triangles produced ${topology.faces.count()} faces, so the `
+            + `corners of the result cannot be matched to the corners they came from`
+        );
+    }
+
+    const wedges = new BtWedgeSet();
+
+    wedges.count = source_wedge_ids.length;
+    wedges.parent = Uint32Array.from({ length: wedges.count }, (_, wedge) => wedge);
+    wedges.next_of_wedge = new Uint32Array(wedges.count).fill(NULL_POINTER);
+    wedges.first_of_vertex = new Uint32Array(topology.vertices.size).fill(NULL_POINTER);
+    wedges.of_loop = new Uint32Array(topology.loops.size).fill(NULL_POINTER);
+
+    /**
+     * Which vertex each new wedge sits at, so the lists below are built once each.
+     * @type {Uint32Array}
+     */
+    const vertex_of_wedge = new Uint32Array(wedges.count).fill(NULL_POINTER);
+
+    for (let face = 0; face < face_cursor; face++) {
+        let loop = topology.face_read_loop(face);
+
+        for (let corner = 0; corner < 3; corner++) {
+            const index = face * 3 + corner;
+
+            const wedge = corner_wedge[index];
+
+            const vertex = topology.loop_read_vertex(loop);
+
+            if (vertex_of_wedge[wedge] === NULL_POINTER) {
+                vertex_of_wedge[wedge] = vertex;
+            } else if (vertex_of_wedge[wedge] !== vertex) {
+                /*
+                 A wedge is a set of corners **at one vertex**, and everything above rests on two
+                 contributions that name the same frontier wedge naming the same frontier vertex too.
+                 That holds for a reason rather than by luck — a wedge a collapse moved belonged to a
+                 victim, a victim is never a group's pinned boundary, and so nothing outside that
+                 group can name it — but the reason is three steps long and nothing else would notice
+                 if it stopped being true. The corners would simply be split across two vertices with
+                 one list between them, and the asset would ship shaded from whichever face was
+                 walked last.
+                 */
+                throw new Error(
+                    `stitching put wedge ${wedge} on vertices ${vertex_of_wedge[wedge]} and `
+                    + `${vertex}: a wedge belongs to exactly one vertex`
+                );
+            }
+
+            wedges.of_loop[loop] = wedge;
+
+            const source_loop = corner_loop[index];
+
+            if (source_loop !== NULL_POINTER) {
+                vgeo_layers_copy_corner(
+                    topology, topologies[corner_contribution[index]], source_loop, loop
+                );
+            }
+
+            loop = topology.loop_read_next(loop);
+        }
+    }
+
+    for (let wedge = 0; wedge < wedges.count; wedge++) {
+        if (vertex_of_wedge[wedge] !== NULL_POINTER) {
+            wedges.attach(wedge, vertex_of_wedge[wedge]);
+        }
+    }
+
+    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,
+        wedges,
+        source_wedge_ids: Uint32Array.from(source_wedge_ids),
+    };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 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 {VGeoGroupRepack|undefined} `undefined` when the group must be simplified instead
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_try_repack(frontier: VGeoFrontier, group_clusters: number[], parent_target: number): VGeoGroupRepack | undefined;
+import { VGeoGroupRepack } from "./VGeoGroupRepack.js";
+//# sourceMappingURL=vgeo_try_repack.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_try_repack.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_try_repack.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAPW,MAAM,EAAE,iBACR,MAAM,GACJ,eAAe,GAAC,SAAS,CAsFrC;gCA7G+B,sBAAsB"}

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

@@ -0,0 +1,117 @@
+import { bt_mesh_build_face_graph } from "../../../../../../core/graph/metis/bt_mesh_build_face_graph.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 { VGeoFaceGraph } from "../partition/VGeoFaceGraph.js";
+import { vgeo_split_face_set_packed } from "../partition/vgeo_split_face_set_packed.js";
+import { vgeo_extract_submesh } from "../submesh/vgeo_extract_submesh.js";
+import { vgeo_build_cluster } from "./vgeo_build_cluster.js";
+import { VGeoGroupRepack } from "./VGeoGroupRepack.js";
+
+/**
+ * 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 {VGeoGroupRepack|undefined} `undefined` when the group must be simplified instead
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_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, frontier.wedges);
+
+    const face_graph = new VGeoFaceGraph(
+        submesh.mesh.topology, bt_mesh_build_face_graph(submesh.mesh.topology), submesh.wedges
+    );
+
+    /**
+     *
+     * @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 VGeoGroupRepack();
+
+    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 = vgeo_build_cluster(submesh.mesh, part_face_ids, 0, submesh.wedges);
+
+        // 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]
+            ),
+            attribute_ids: built.gathered.attribute_ids,
+            source_wedge_ids: Uint32Array.from(
+                built.gathered.wedge_ids, (wedge) => submesh.source_wedge_ids[wedge]
+            ),
+            topology: submesh.mesh.topology,
+        });
+    }
+
+    return repack;
+}

package/src/shade/renderer/geometry/virtual/build/mesh/VGEO_CREASE_ANGLE.d.ts

@@ -0,0 +1,46 @@
+/**
+ * How far two triangles may turn across a shared edge before the builder stops pretending the
+ * surface is smooth there, in degrees.
+ *
+ * Only ever applied to normals the builder *synthesizes*. A source that authored its own normals has
+ * already answered this question, and its answer is the one that ships.
+ *
+ * **What it is for.** Averaging every face around a vertex into one direction is right for a surface
+ * and wrong for a corner, and a mesh does not say which it is — so an angle has to. A cube is the
+ * whole argument: its eight corner vertices each meet three faces, and one direction for all three
+ * is ninety degrees wrong for two of them. Measured on Zorah's `mesh1[0]`, whose source is
+ * `POSITION`-only and so gets every normal from this pass, the angle between a shipped corner's
+ * normal and the normal of the triangle that corner belongs to ran to a mean of 8.60 degrees and a
+ * p99 of 37.66 at LOD 0 — the numbers `WEDGE_PLAN_2026_09_18.md` §1 records — before a single
+ * collapse.
+ *
+ * **Why 45.** A threshold splits a curve as readily as a corner, so it is a trade: too low and a
+ * coarsely tessellated cylinder gains a crease at every segment, too high and a box stays soft.
+ * Swept over that same primitive, over its whole DAG:
+ *
+ * | crease | vertices/triangle | LOD 0 mean | LOD 0 p99 | all levels p99 | share over 30° |
+ * |---|---|---|---|---|---|
+ * | none  | 0.641 | 8.60 | 37.66 | 54.27 | 6.5% |
+ * | 60°   | 0.646 | 8.42 | 35.26 | 52.60 | 6.2% |
+ * | **45°** | **0.661** | **8.05** | **32.19** | **50.29** | **5.3%** |
+ * | 30°   | 0.724 | 7.04 | 26.88 | 45.97 | 3.6% |
+ * | 20°   | 0.880 | 5.53 | 20.58 | 38.65 | 2.0% |
+ *
+ * A wedge is a shipped vertex, so that first column is very nearly the size of the asset: 45 degrees
+ * costs 3%, 30 costs 13% and 20 costs 37%. The curve is smooth because *this* mesh's residual is
+ * mostly tessellation rather than creases — it keeps improving as the threshold falls, right through
+ * the range where a cylinder would start faceting, which is the sign that the number below is a
+ * judgement about content and not a fact about arithmetic. Hard-surface content is where it earns
+ * its keep and where the choice is obvious: every edge of a box is ninety degrees, and any threshold
+ * under that keeps all of them.
+ *
+ * So it is also {@link VGeoBuildOptions#crease_angle}, and a conversion of one kind of content can
+ * say so.
+ *
+ * @type {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_CREASE_ANGLE: number;
+//# sourceMappingURL=VGEO_CREASE_ANGLE.d.ts.map

package/src/shade/renderer/geometry/virtual/build/mesh/VGEO_CREASE_ANGLE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_CREASE_ANGLE.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/VGEO_CREASE_ANGLE.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,gCALU,MAAM,CAKoB"}