@woosh/meep-engine 3.28.0 → 3.30.0

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

@@ -0,0 +1,545 @@
+import { assert } from "../../../../../../core/assert.js";
+import { NULL_POINTER } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import {
+    bt_mesh_simplify_with_quadrics
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js";
+import {
+    bt_wedges_live_count
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_wedges_live_count.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 {
+    quadric_attribute_size
+} from "../../../../../../core/geom/3d/quadric/quadric_attribute_size.js";
+import { bt_mesh_build_face_graph } from "../../../../../../core/graph/metis/bt_mesh_build_face_graph.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.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_attribute_vector_layout } from "../mesh/vgeo_attribute_vector_layout.js";
+import { vgeo_attribute_vector_read } from "../mesh/vgeo_attribute_vector_read.js";
+import { vgeo_attribute_vector_write } from "../mesh/vgeo_attribute_vector_write.js";
+import { vgeo_compute_vertex_tangents } from "../mesh/vgeo_compute_vertex_tangents.js";
+import { VGeoFaceGraph } from "../partition/VGeoFaceGraph.js";
+import { vgeo_split_face_set_packed } from "../partition/vgeo_split_face_set_packed.js";
+import { vgeo_containing_sphere } from "../sphere/vgeo_containing_sphere.js";
+import { vgeo_extract_submesh } from "../submesh/vgeo_extract_submesh.js";
+import { vgeo_build_cluster } from "./vgeo_build_cluster.js";
+import { vgeo_compute_group_boundary } from "./vgeo_compute_group_boundary.js";
+import { VGeoGroupStep } from "./VGeoGroupStep.js";
+
+/**
+ * The defects a simplified group carries, as one line, or `''` when it carries none.
+ *
+ * Reached only from inside an `assert`, and that is the whole point of it being a function.
+ * {@link bt_mesh_validate} is a full reference, disk-cycle, radial-cycle and finite-value sweep of
+ * the submesh, and {@link reduce_to} would run it on every attempt: measured at 4.3% of a build of
+ * a 200k-face primitive. What it guards is real — a defect here is a crack that would be paged and
+ * drawn — but it guards against this file and the collapse below it being wrong, not against
+ * anything a source mesh can do, so it belongs where the other asserts are: on in development, and
+ * gone where they go.
+ *
+ * @param {BinaryTopology} topology
+ * @returns {string} at most the first four, joined
+ */
+function describe_defects(topology) {
+    return bt_mesh_validate(topology).slice(0, 4).map((defect) => defect.detail).join('; ');
+}
+
+/**
+ * A tangent derived from a normal is a pure function of it, so a vertex whose normal was restored
+ * unchanged gets its tangent back unchanged too — there is nothing for a pin to protect.
+ * @type {Set<number>}
+ */
+const NOTHING_PINNED = new Set();
+
+/**
+ * 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;
+}
+
+/**
+ * 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 {VGeoGroupStep|undefined} `undefined` when the group has no coarser form at all, and the
+ *     round should leave its clusters alone
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_build_group_step(
+    frontier, group_clusters, group_of_face, group_index, level, options
+) {
+    // A group of one has nothing to merge, and the ceiling below — one fewer cluster than the group
+    // holds — would be zero. The grouping never produces one: a cluster it cannot place beside at
+    // least one other is returned to the frontier instead.
+    assert.greaterThan(group_clusters.length, 1, 'group_clusters.length');
+
+    /**
+     *
+     * @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 = vgeo_compute_group_boundary(
+        frontier.mesh.topology, face_ids, group_of_face, group_index
+    );
+
+    const submesh = vgeo_extract_submesh(frontier.mesh, face_ids, frontier.wedges);
+
+    const topology = submesh.mesh.topology;
+
+    // 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();
+    }
+
+    /*
+     The shading channels, lifted out of the layers so the simplifier can carry them through every
+     collapse, and the fields it fits them from — cloned from the frontier's for the same reason the
+     geometric quadrics are, since this whole attempt may be thrown away.
+
+     Read once and carried across all of `reduce_to`'s attempts: a second pass is a continuation of
+     the first, not a fresh start.
+     */
+    const attribute_layout = frontier.attribute_layout;
+    const attribute_components = attribute_layout.components;
+
+    let attributes = null;
+
+    /**
+     * What travels but is never fitted -- the tangent's handedness. Read once and handed straight
+     * back: the simplifier is not given it, so a survivor's entry is still a survivor's.
+     * @type {Float64Array|null}
+     */
+    let verbatim = null;
+
+    if (attribute_components > 0) {
+        const stride = quadric_attribute_size(attribute_components);
+
+        const wedge_count = submesh.wedges.count;
+
+        const quadrics_of_local = new Float64Array(wedge_count * stride);
+
+        for (let local = 0; local < wedge_count; local++) {
+            const source = submesh.source_wedge_ids[local];
+
+            quadrics_of_local.set(
+                frontier.attribute_quadrics.subarray(source * stride, source * stride + stride),
+                local * stride
+            );
+        }
+
+        // Empty wherever the tangent is derived rather than carried, which is every mesh without a
+        // `UV0` -- there is no flag to keep when the whole frame is a function of the normal.
+        verbatim = attribute_layout.verbatim_components === 0
+            ? null
+            : vgeo_attribute_vector_read(
+                submesh.mesh, attribute_layout.verbatim_components, attribute_layout.verbatim,
+                submesh.wedges
+            );
+
+        attributes = {
+            values: vgeo_attribute_vector_read(
+                submesh.mesh, attribute_components, attribute_layout.channels, submesh.wedges
+            ),
+            components: attribute_components,
+            quadrics: quadrics_of_local,
+            weights: frontier.attribute_weights,
+        };
+    }
+
+    /**
+     * `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(topology, local_of_source.get(v1), local_of_source.get(v2));
+
+        if (edge === NULL_POINTER) {
+            continue;
+        }
+
+        const first_loop = topology.edge_read_loop(edge);
+
+        let loop = first_loop;
+
+        do {
+            const face = topology.loop_read_face(loop);
+
+            if (face !== NULL_POINTER) {
+                protected_faces.add(face);
+            }
+
+            loop = topology.loop_read_radial_next(loop);
+        } while (loop !== first_loop && loop !== NULL_POINTER);
+    }
+
+    /**
+     * Largest deviation any attempt measured, rather than the last one's.
+     *
+     * Each call reports what *its own* collapses cost ({@link bt_mesh_simplify_with_quadrics}), and
+     * the attempts below are one simplification continued rather than several, so no single call's
+     * answer is the step's. Carrying the maximum across them is what makes it one. The surface only
+     * ever moves further from the source as this loop tightens, so a maximum is also the whole of
+     * what is needed — no attempt can undo what an earlier one charged for.
+     * @type {number}
+     */
+    let deviation = 0;
+
+    /**
+     * Simplify *further*, down to `target_face_count`, and cut what is left into clusters.
+     *
+     * Further, not afresh: the submesh and its quadrics are carried across calls, which is what
+     * `bt_mesh_simplify_with_quadrics` is for. A second pass over the same geometry therefore
+     * accumulates onto the same quadrics and measures the same deviation from the source that one
+     * pass straight to the lower target would have — re-extracting instead would restart the
+     * collapse from the frontier and throw away everything the first attempt learned.
+     *
+     * @param {number} target_face_count
+     * @returns {{face_graph: VGeoFaceGraph, parts: number[][]}}
+     */
+    function reduce_to(target_face_count) {
+        deviation = Math.max(deviation, bt_mesh_simplify_with_quadrics(
+            topology, target_face_count, locked, protected_faces, quadrics, attributes,
+            submesh.wedges
+        ));
+
+        assert.equal(
+            describe_defects(topology), '',
+            `simplifying a group of ${group_clusters.length} clusters left the mesh inconsistent`
+        );
+
+        // 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(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`
+                );
+            }
+        }
+
+        const face_graph = new VGeoFaceGraph(
+            topology, bt_mesh_build_face_graph(topology), submesh.wedges
+        );
+
+        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 { face_graph, parts };
+    }
+
+    // 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 target = 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))
+    );
+
+    let outcome = reduce_to(target);
+
+    /**
+     * Most clusters this step may come back with and still be worth taking.
+     *
+     * `parent_target` is what it aims at; this is what it has to clear. A step that hands the round
+     * as many clusters as the group gave it has merged nothing, and the round drops it — so the loop
+     * below chases the requirement rather than the aim, and a step that overshot the aim but cleared
+     * the requirement is left exactly as it is.
+     * @type {number}
+     */
+    const ceiling = group_clusters.length - 1;
+
+    // A triangle target is a guess at a cluster count, and it is a guess that only accounts for one
+    // of the two numbers a cluster is bounded by. On geometry that has come apart — seams, small
+    // separate parts, patches the collapse has eaten the connective tissue out of — there are two or
+    // three vertices per triangle rather than a half, so the vertex ceiling is what binds, and
+    // halving the triangles does not halve the vertices. The result then needs as many clusters as
+    // the group started with, and the guess had no way of knowing.
+    //
+    // So the cluster count is measured and the target tightened until it holds. That is the same
+    // thing the guess was for, done where the answer is actually available: `parts` is the re-cut,
+    // and its length is the number this step exists to bring down.
+    //
+    // It is a loop, but it is not a search: over 25 of the Zorah primitives that could not be built
+    // at all, 70,665 of 70,752 steps cleared on the first attempt, 87 needed a second, and none took
+    // more than three extra. The step is the overshoot rather than the cluster ratio precisely so
+    // that it lands near, and what it costs where it does not is a pass over a group of at most a
+    // few hundred faces.
+    for (; ;) {
+        if (outcome.parts.length <= ceiling || outcome.parts.length === 0) {
+            break;
+        }
+
+        const faces = topology.faces.count();
+
+        // Wedges, not `vertices.count()`. A meshlet's vertex limit counts what it *carries*, and a
+        // vertex whose corners shade two ways is two of them — so asking the pool reads low at every
+        // crease and every chart boundary, and the step then aims at a target it has already missed.
+        const vertices = bt_wedges_live_count(topology, submesh.wedges);
+
+        // How far over the step is, on whichever of the two ceilings it actually broke.
+        const overshoot = Math.max(
+            faces / (ceiling * VGEO_MAX_CLUSTER_TRIANGLE_COUNT),
+            vertices / (ceiling * VGEO_MAX_CLUSTER_VERTEX_COUNT)
+        );
+
+        // Under both ceilings and still too many clusters: the geometry would fit, the packing did
+        // not. Nothing local says by how much, so aim at the share of it that would have.
+        const next = overshoot > 1
+            ? Math.floor(faces / overshoot)
+            : Math.floor((faces * ceiling) / outcome.parts.length);
+
+        if (next >= faces) {
+            break;
+        }
+
+        outcome = reduce_to(Math.max(1, next));
+
+        if (topology.faces.count() >= faces) {
+            // The simplifier has nothing left it is willing to collapse — every remaining edge is
+            // pinned, would fold, or has already been tried. Asking for less will not change that,
+            // and the round is the one that decides what to do with a group that cannot move.
+            break;
+        }
+    }
+
+    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;
+    }
+
+    /*
+     The frame the step's vertices carry, back into the layers the cluster encoder reads.
+
+     It was decided at the collapses, not here. Deriving it here — the area-weighted normal of the
+     mesh the simplifier just left — describes *that* mesh, which is a different surface from the one
+     the asset was authored as, and the difference is what a LOD transition pops by. Worse, it could
+     only ever be derived for the vertices the step was free to move: the group's perimeter is shared
+     with every neighbouring group and has to carry byte-identical values in all of them, so it would
+     have kept the frame it inherited while its own neighbours got a fresh one. Two rules over one
+     mesh, meeting along every triangle that straddles the perimeter — a third of the vertices at the
+     first level and half of them by the seventh, disagreeing by up to 175 degrees.
+     `ATTRIBUTE_PLAN_2026_09_18.md` §1.1 has the measurement.
+
+     Carried instead, both follow one rule, and the pin is back to meaning only what it is for.
+     */
+    if (attributes !== null) {
+        vgeo_attribute_vector_write(
+            submesh.mesh, attribute_layout, attributes.values, verbatim, locked, submesh.wedges
+        );
+    }
+
+    /*
+     With no `UV0` there is no parameterization for a tangent to be tangent to, and the frame is an
+     arbitrary well-conditioned basis around the normal — a *pure function* of it. So it is derived
+     rather than carried, which is both cheaper and safer: Frisvad's basis turns discontinuously with
+     the normal, and two neighbours' tangents can be nearly opposite and blend to nothing. A pure
+     function of a byte-identical normal is byte-identical, so the perimeter needs no exception
+     beyond the one `vgeo_compute_vertex_tangents` already makes. Where the mesh does carry `UV0`,
+     the tangent came through the vector above with the rest of the frame.
+     */
+    if (submesh.mesh.layers[VGEO_ATTRIBUTE.UV0] === null) {
+        /*
+         Nothing pinned, and that is not a hole in the pin. Without a parameterization the frame is
+         `build_tangent_from_normal` of the normal and nothing else, the write above has just restored
+         every pinned vertex's normal to what it had, and a pure function of an unchanged input is an
+         unchanged output — bit for bit, which the byte-identity gate in `WEDGE_PLAN_2026_09_18.md`
+         §6.1 is what proves.
+
+         Passing `locked` instead would leave a pinned vertex's *donated* corners — the ones a
+         collapse re-pointed onto it — carrying the tangent they arrived with, which is the one thing
+         corner storage changed about what pinning has to cover.
+         */
+        vgeo_compute_vertex_tangents(submesh.mesh, NOTHING_PINNED, submesh.wedges);
+    }
+
+    const submesh_face_graph = outcome.face_graph;
+    const parts = outcome.parts;
+
+    const step = new VGeoGroupStep();
+
+    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(deviation, max_child_error(child_clusters));
+
+    submesh.source_vertex_ids.forEach((source, local) => {
+        if (quadrics[local] !== null) {
+            step.quadrics.set(source, quadrics[local]);
+        }
+    });
+
+    if (attributes !== null) {
+        // Handed over whole, with the roots named separately. Liveness is no longer a question about
+        // the *vertex*: a collapse can leave a victim's wedge standing, adopted by the survivor and
+        // carrying corners of its own, so the vertex map would call a live wedge dead.
+        step.attribute_quadrics = attributes.quadrics;
+        step.attribute_source_wedge_ids = submesh.source_wedge_ids;
+
+        for (let wedge = 0; wedge < submesh.wedges.count; wedge++) {
+            if (submesh.wedges.find(wedge) === wedge) {
+                step.live_wedges.add(wedge);
+            }
+        }
+    }
+
+    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 = vgeo_build_cluster(submesh.mesh, part_face_ids, level, submesh.wedges);
+
+        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]
+            ),
+            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,
+        });
+
+        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;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Cut a mesh into leaf clusters — the frontier every round starts from.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {Float64Array} [attribute_weights] what a unit of each component of the shading vector is
+ *     worth in object-space position error, from {@link vgeo_resolve_attribute_weights} over the
+ *     **source** mesh. Defaulted here from the shipped ratios rather than left out, so that a caller
+ *     driving the level loop directly gets the build a conversion gets.
+ * @returns {VGeoFrontier}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_build_leaf_frontier(mesh: VirtualGeometryMesh, attribute_weights?: Float64Array): VGeoFrontier;
+import { VGeoFrontier } from "./VGeoFrontier.js";
+//# sourceMappingURL=vgeo_build_leaf_frontier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_build_leaf_frontier.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_build_leaf_frontier.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;GAYG;AACH,wFATW,YAAY,GAIV,YAAY,CAgFxB;6BA1F4B,mBAAmB"}

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

@@ -0,0 +1,110 @@
+import {
+    bt_mesh_compute_wedge_attribute_quadrics
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compute_wedge_attribute_quadrics.js";
+import {
+    bt_mesh_compute_vertex_quadrics
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadrics.js";
+import { vgeo_mesh_wedges } from "../../format/attribute/vgeo_mesh_wedges.js";
+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 {
+    VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS
+} from "../mesh/VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.js";
+import { vgeo_attribute_vector_layout } from "../mesh/vgeo_attribute_vector_layout.js";
+import { vgeo_attribute_vector_read } from "../mesh/vgeo_attribute_vector_read.js";
+import { vgeo_resolve_attribute_weights } from "../mesh/vgeo_resolve_attribute_weights.js";
+import { VGeoFaceGraph } from "../partition/VGeoFaceGraph.js";
+import { vgeo_split_face_set } from "../partition/vgeo_split_face_set.js";
+import { vgeo_build_cluster } from "./vgeo_build_cluster.js";
+import { VGeoFrontier } from "./VGeoFrontier.js";
+
+/**
+ * Cut a mesh into leaf clusters — the frontier every round starts from.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {Float64Array} [attribute_weights] what a unit of each component of the shading vector is
+ *     worth in object-space position error, from {@link vgeo_resolve_attribute_weights} over the
+ *     **source** mesh. Defaulted here from the shipped ratios rather than left out, so that a caller
+ *     driving the level loop directly gets the build a conversion gets.
+ * @returns {VGeoFrontier}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_build_leaf_frontier(
+    mesh,
+    attribute_weights = vgeo_resolve_attribute_weights(mesh, VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS)
+) {
+    const frontier = new VGeoFrontier();
+
+    frontier.mesh = mesh;
+
+    /*
+     Which corners of each vertex shade as one, read off the values the source's own corners carry.
+     This is the only place in the builder that *decides* a partition; every level above carries this
+     one forward by provenance, merging wedges at collapses and never splitting one.
+     */
+    frontier.wedges = vgeo_mesh_wedges(mesh.topology);
+
+    const face_graph = new VGeoFaceGraph(
+        mesh.topology, bt_mesh_build_face_graph(mesh.topology), frontier.wedges
+    );
+
+    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
+    );
+
+    // 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);
+
+    /*
+     And the same for the shading channels, which is what lets a vertex twelve rounds up be given the
+     value the *source's* field has where it now sits, rather than one read off whatever the collapses
+     left behind. The two sets are kept apart on purpose: the geometric one alone is what an error is
+     reported from, and that is what keeps the error an object-space length whatever the attribute
+     term does to the placement.
+     */
+    frontier.attribute_layout = vgeo_attribute_vector_layout(mesh.layers);
+
+    if (frontier.attribute_layout.components > 0) {
+        frontier.attribute_weights = attribute_weights;
+
+        frontier.attribute_quadrics = bt_mesh_compute_wedge_attribute_quadrics(
+            mesh.topology,
+            vgeo_attribute_vector_read(
+                mesh,
+                frontier.attribute_layout.components,
+                frontier.attribute_layout.channels,
+                frontier.wedges
+            ),
+            frontier.attribute_layout.components,
+            frontier.attribute_weights,
+            frontier.wedges
+        );
+    }
+
+    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 = vgeo_build_cluster(mesh, face_ids, 0, frontier.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;
+
+        frontier.clusters.push(built.cluster);
+        frontier.cluster_faces.push(face_ids);
+    }
+
+    return frontier;
+}