@woosh/meep-engine 3.27.0 → 3.29.0

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

package/src/shade/renderer/geometry/virtual/build/mesh/VGEO_CREASE_ANGLE.js

@@ -0,0 +1,45 @@
+/**
+ * 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 = 45;

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

@@ -0,0 +1,64 @@
+/**
+ * What a full unit of each channel is worth in position error, as a fraction of the geometry's own
+ * bounding-box diagonal. See {@link VGeoBuildOptions#attribute_weight_ratios}.
+ *
+ * ## What the number does and does not control
+ *
+ * It does **not** control the value a coarse vertex carries. That is a least-squares fit to the
+ * accumulated fields, and the weight cancels out of it exactly — multiplied in when the quadric is
+ * built, divided out when it is solved. The fit is the larger of the two wins by a long way and it
+ * needs no tuning at all.
+ *
+ * What the number controls is how much the channels get to move the vertex and price the collapse.
+ * A collapse that would smear a crease is charged for it, in units of length, at exactly the rate
+ * this names.
+ *
+ * ## How it was chosen
+ *
+ * Swept from `1e-9` — the term effectively off — to `1/2`, measuring how far the shipped normal field
+ * sits from the source's and what happened to `self_error`, which is the number the runtime's cut is
+ * driven by.
+ *
+ * On a 31,874-triangle Zorah primitive, the content the defect was found on:
+ *
+ * ```
+ * ratio      normal error, mean over the DAG      self_error at the root
+ * 1e-9       2.076 deg                            1.00x
+ * 1/1024     1.857 deg                            1.08x
+ * 1/64       1.807 deg                            1.35x
+ * 1/8        2.059 deg                           18.09x
+ * 1/4        2.191 deg                            6.81x
+ * 1/2        2.326 deg                           14.02x
+ * ```
+ *
+ * Above `1/64` it is not a trade, it is a loss: eighteen times the geometric error for a normal field
+ * that is *worse* than leaving the term off. The reason is that this content is mostly smooth, and on
+ * smooth geometry there is no crease for the term to defend — a 48x24 sphere reads 5.29 degrees of
+ * worst-case normal error at every ratio from `1e-9` to `1/4`, unchanged to three figures.
+ *
+ * So `1/1024`: inside the 20% the plan allows `self_error` to move, worth about a tenth of a degree,
+ * and far enough below the cliff that no content falls off it by accident.
+ *
+ * ## When to raise it
+ *
+ * Content with hard creases, which is what the term is actually for. A cube subdivided sixteen ways
+ * per face — flat faces meeting at right angles, where collapsing *within* a face costs exactly zero
+ * geometric error and the metric has nothing else to say — goes from 14.9 degrees of worst-case
+ * normal error to **1.38** at `1/4`. (Subdivided twenty-four ways it reads a hundredth of a degree at
+ * every ratio, which is how sharply this depends on the geometry rather than on the setting.) That
+ * is the trade the number exists to make, and it is a per-asset decision rather than a default,
+ * because the same setting on Zorah costs seven times the error for nothing.
+ *
+ * The other channels take the same ratio for want of their own measurement. A texture coordinate and
+ * a colour are bounded the way a normal component is — roughly `[0, 1]`, roughly `[-1, 1]` — so the
+ * number is at least in the right place, and none of the content this was measured on carries them.
+ * Naming that here rather than implying they were each swept.
+ *
+ * @readonly
+ * @type {number[]}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS: number[];
+//# sourceMappingURL=VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,mDALU,MAAM,EAAE,CAOhB"}

package/src/shade/renderer/geometry/virtual/build/mesh/VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.js

@@ -0,0 +1,68 @@
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+import { VGEO_ATTRIBUTES } from "../../format/attribute/VGEO_ATTRIBUTES.js";
+
+/**
+ * What a full unit of each channel is worth in position error, as a fraction of the geometry's own
+ * bounding-box diagonal. See {@link VGeoBuildOptions#attribute_weight_ratios}.
+ *
+ * ## What the number does and does not control
+ *
+ * It does **not** control the value a coarse vertex carries. That is a least-squares fit to the
+ * accumulated fields, and the weight cancels out of it exactly — multiplied in when the quadric is
+ * built, divided out when it is solved. The fit is the larger of the two wins by a long way and it
+ * needs no tuning at all.
+ *
+ * What the number controls is how much the channels get to move the vertex and price the collapse.
+ * A collapse that would smear a crease is charged for it, in units of length, at exactly the rate
+ * this names.
+ *
+ * ## How it was chosen
+ *
+ * Swept from `1e-9` — the term effectively off — to `1/2`, measuring how far the shipped normal field
+ * sits from the source's and what happened to `self_error`, which is the number the runtime's cut is
+ * driven by.
+ *
+ * On a 31,874-triangle Zorah primitive, the content the defect was found on:
+ *
+ * ```
+ * ratio      normal error, mean over the DAG      self_error at the root
+ * 1e-9       2.076 deg                            1.00x
+ * 1/1024     1.857 deg                            1.08x
+ * 1/64       1.807 deg                            1.35x
+ * 1/8        2.059 deg                           18.09x
+ * 1/4        2.191 deg                            6.81x
+ * 1/2        2.326 deg                           14.02x
+ * ```
+ *
+ * Above `1/64` it is not a trade, it is a loss: eighteen times the geometric error for a normal field
+ * that is *worse* than leaving the term off. The reason is that this content is mostly smooth, and on
+ * smooth geometry there is no crease for the term to defend — a 48x24 sphere reads 5.29 degrees of
+ * worst-case normal error at every ratio from `1e-9` to `1/4`, unchanged to three figures.
+ *
+ * So `1/1024`: inside the 20% the plan allows `self_error` to move, worth about a tenth of a degree,
+ * and far enough below the cliff that no content falls off it by accident.
+ *
+ * ## When to raise it
+ *
+ * Content with hard creases, which is what the term is actually for. A cube subdivided sixteen ways
+ * per face — flat faces meeting at right angles, where collapsing *within* a face costs exactly zero
+ * geometric error and the metric has nothing else to say — goes from 14.9 degrees of worst-case
+ * normal error to **1.38** at `1/4`. (Subdivided twenty-four ways it reads a hundredth of a degree at
+ * every ratio, which is how sharply this depends on the geometry rather than on the setting.) That
+ * is the trade the number exists to make, and it is a per-asset decision rather than a default,
+ * because the same setting on Zorah costs seven times the error for nothing.
+ *
+ * The other channels take the same ratio for want of their own measurement. A texture coordinate and
+ * a colour are bounded the way a normal component is — roughly `[0, 1]`, roughly `[-1, 1]` — so the
+ * number is at least in the right place, and none of the content this was measured on carries them.
+ * Naming that here rather than implying they were each swept.
+ *
+ * @readonly
+ * @type {number[]}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS = Object.freeze(
+    VGEO_ATTRIBUTES.map((_, attribute) => attribute === VGEO_ATTRIBUTE.POSITION ? 0 : 1 / 1024)
+);

package/src/shade/renderer/geometry/virtual/build/{VirtualGeometryMesh.d.ts → mesh/VirtualGeometryMesh.d.ts}

@@ -2,11 +2,15 @@
  * A level of geometry as the builder handles it: a `BinaryTopology` carrying the positions, the
  * connectivity, and the per-vertex attributes all together.
  *
- * Everything per-vertex lives in the topology. It has to: an edge collapse moves and removes
- * vertices, and the topology is the only thing that knows which. A vertex data layer is addressed
- * by vertex id and sized by the vertex pool, so a channel cannot fall out of step with the mesh it
- * describes — there is no second array to resize, no invariant to assert, and no way for the
- * simplifier to leave a live vertex without a slot.
+ * Everything per-element lives in the topology. It has to: a collapse moves and removes vertices and
+ * kills faces, and the topology is the only thing that knows which. A data layer is sized by its own
+ * pool, so a channel cannot fall out of step with the mesh it describes — there is no second array
+ * to resize, no invariant to assert, and no way for the simplifier to leave a live element without a
+ * slot.
+ *
+ * **Position is the vertex's; appearance is the corner's.** A hard edge and a texture seam are both
+ * one geometric vertex that shades two ways, and no per-vertex record can hold that — so the
+ * channels are loop data. See `WEDGE_PLAN_2026_09_18.md` §2.
  *
  * The channels are named by their index into {@link VGEO_ATTRIBUTES}, which is the format's frozen
  * table — {@link layers} has one slot per entry, holding a layer or null.
@@ -42,9 +46,10 @@ export class VirtualGeometryMesh {
      */
     topology: BinaryTopology;
     /**
-     * One slot per {@link VGEO_ATTRIBUTES} entry, holding the vertex data layer that carries that
+     * One slot per {@link VGEO_ATTRIBUTES} entry, holding the **loop** data layer that carries that
      * channel or null where this geometry does not carry it.
-     * {@link VGEO_ATTRIBUTE.POSITION}'s slot is always null — position is the topology's own.
+     * {@link VGEO_ATTRIBUTE.POSITION}'s slot is always null — position is the topology's own, and is
+     * the one value that really is a vertex's rather than a corner's.
      * @type {(BinaryDataLayer|null)[]}
      */
     layers: (BinaryDataLayer | null)[];
@@ -69,5 +74,5 @@ export class VirtualGeometryMesh {
      */
     face_ids(): number[];
 }
-import { BinaryTopology } from "../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { BinaryTopology } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 //# sourceMappingURL=VirtualGeometryMesh.d.ts.map