@woosh/meep-engine 3.27.0 → 3.29.0

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

@@ -0,0 +1,45 @@
+/**
+ * Area-weighted normals of a mesh, split at its creases, written into its normal channel.
+ *
+ * The geometry a mesh actually has is the answer for that mesh: carrying a surviving vertex's
+ * original normal through a dozen collapses shades a coarse level by whichever vertices happened to
+ * win, which is visibly wrong.
+ *
+ * **Per corner group, not per vertex.** Averaging every face around a vertex is right for a surface
+ * and wrong for a corner. Two faces sharing an edge belong to the same group when the surface turns
+ * less than {@link VGEO_CREASE_ANGLE} across it; groups are the connected components that leaves,
+ * and each gets its own area-weighted average. A vertex on a smooth surface has exactly one, and
+ * this is then the pass it has always been. A box corner has three, and the eight vertices of a cube
+ * stop carrying a normal that is ninety degrees wrong for every face using it.
+ *
+ * Area weighting falls out of the arithmetic rather than being applied: Newell's normal *is* the
+ * face normal scaled by twice the area, so summing the raw face normals is the area-weighted sum.
+ * Which is the same thing {@link bt_mesh_compute_vertex_normals} does, one level down, for the whole
+ * vertex — and this reproduces its arithmetic step for step, down to the float32 face scratch and
+ * the reciprocal it scales by, so that a mesh without a crease in it comes out bit for bit the same
+ * as it did before any of this existed.
+ *
+ * An edge with anything other than two live triangles on it — a mesh boundary, a non-manifold fin —
+ * joins nothing. There is no pair of faces to ask the question of, and splitting is the conservative
+ * answer: it keeps each side's own normal rather than inventing an average across a join the mesh
+ * itself does not make.
+ *
+ * **Except where the vertex was pinned.** A pinned vertex is one the step was forbidden to move, and
+ * every group that touches it carries it — which is exactly what lets a cut place two levels of
+ * detail side by side without a crack. That guarantee has to cover what the vertex *carries*, not
+ * only where it is: recomputed here, a pinned vertex would get the average of the faces on this
+ * side of the seam only, the group across the seam would get the average of its own, and the two
+ * would disagree by however much the surface turns. So a pinned vertex keeps what it had, exactly
+ * as it keeps where it was, and the frame stays continuous across every cut the DAG admits.
+ *
+ * @param {VirtualGeometryMesh} mesh whose normal layer is sized by the loop pool and so carries a
+ *     slot for every live corner by construction
+ * @param {Set<number>} pinned vertex ids to leave exactly as they are; empty for a mesh nothing has
+ *     locked yet
+ * @param {number} [crease_angle] degrees; see {@link VGEO_CREASE_ANGLE}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_compute_vertex_normals(mesh: VirtualGeometryMesh, pinned: Set<number>, crease_angle?: number): void;
+//# sourceMappingURL=vgeo_compute_vertex_normals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_compute_vertex_normals.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_compute_vertex_normals.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,+EAPW,IAAI,MAAM,CAAC,iBAEX,MAAM,QA4MhB"}

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

@@ -0,0 +1,300 @@
+import { assert } from "../../../../../../core/assert.js";
+import {
+    NULL_POINTER
+} from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import {
+    bt_face_compute_newell_normal
+} from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_face_compute_newell_normal.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+import { VGEO_CREASE_ANGLE } from "./VGEO_CREASE_ANGLE.js";
+
+/**
+ * One corner's normal, on its way into the format's channel.
+ * @type {Float32Array}
+ */
+const scratch_normal = new Float32Array(3);
+
+/**
+ * One face's normal, scaled by twice its area.
+ *
+ * Float32 because {@link bt_mesh_compute_vertex_normals} accumulates from a float32 scratch, and
+ * this pass has to reproduce that sum exactly: on a mesh with no crease it *is* that pass, and the
+ * whole claim below is that only geometry with a crease or a seam in it moves.
+ * @type {Float32Array}
+ */
+const scratch_face = new Float32Array(3);
+
+/**
+ * Area-weighted normals of a mesh, split at its creases, written into its normal channel.
+ *
+ * The geometry a mesh actually has is the answer for that mesh: carrying a surviving vertex's
+ * original normal through a dozen collapses shades a coarse level by whichever vertices happened to
+ * win, which is visibly wrong.
+ *
+ * **Per corner group, not per vertex.** Averaging every face around a vertex is right for a surface
+ * and wrong for a corner. Two faces sharing an edge belong to the same group when the surface turns
+ * less than {@link VGEO_CREASE_ANGLE} across it; groups are the connected components that leaves,
+ * and each gets its own area-weighted average. A vertex on a smooth surface has exactly one, and
+ * this is then the pass it has always been. A box corner has three, and the eight vertices of a cube
+ * stop carrying a normal that is ninety degrees wrong for every face using it.
+ *
+ * Area weighting falls out of the arithmetic rather than being applied: Newell's normal *is* the
+ * face normal scaled by twice the area, so summing the raw face normals is the area-weighted sum.
+ * Which is the same thing {@link bt_mesh_compute_vertex_normals} does, one level down, for the whole
+ * vertex — and this reproduces its arithmetic step for step, down to the float32 face scratch and
+ * the reciprocal it scales by, so that a mesh without a crease in it comes out bit for bit the same
+ * as it did before any of this existed.
+ *
+ * An edge with anything other than two live triangles on it — a mesh boundary, a non-manifold fin —
+ * joins nothing. There is no pair of faces to ask the question of, and splitting is the conservative
+ * answer: it keeps each side's own normal rather than inventing an average across a join the mesh
+ * itself does not make.
+ *
+ * **Except where the vertex was pinned.** A pinned vertex is one the step was forbidden to move, and
+ * every group that touches it carries it — which is exactly what lets a cut place two levels of
+ * detail side by side without a crack. That guarantee has to cover what the vertex *carries*, not
+ * only where it is: recomputed here, a pinned vertex would get the average of the faces on this
+ * side of the seam only, the group across the seam would get the average of its own, and the two
+ * would disagree by however much the surface turns. So a pinned vertex keeps what it had, exactly
+ * as it keeps where it was, and the frame stays continuous across every cut the DAG admits.
+ *
+ * @param {VirtualGeometryMesh} mesh whose normal layer is sized by the loop pool and so carries a
+ *     slot for every live corner by construction
+ * @param {Set<number>} pinned vertex ids to leave exactly as they are; empty for a mesh nothing has
+ *     locked yet
+ * @param {number} [crease_angle] degrees; see {@link VGEO_CREASE_ANGLE}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_compute_vertex_normals(mesh, pinned, crease_angle = VGEO_CREASE_ANGLE) {
+    const normals = mesh.layers[VGEO_ATTRIBUTE.NORMAL];
+
+    assert.notNull(normals, 'mesh normal channel');
+
+    const topology = mesh.topology;
+
+    const face_pool = topology.faces;
+    const loop_pool = topology.loops;
+
+    /**
+     * Each face's normal scaled by twice its area, which is Newell's as it comes.
+     * @type {Float64Array}
+     */
+    const face_normal = new Float64Array(face_pool.size * 3);
+
+    /**
+     * Its length, so the angle test does not recompute one.
+     * @type {Float64Array}
+     */
+    const face_length = new Float64Array(face_pool.size);
+
+    for (let face = 0; face < face_pool.size; face++) {
+        if (!face_pool.is_allocated(face)) {
+            continue;
+        }
+
+        if (topology.face_read_loop(face) === NULL_POINTER) {
+            continue;
+        }
+
+        bt_face_compute_newell_normal(scratch_face, 0, topology, face);
+
+        const nx = scratch_face[0];
+        const ny = scratch_face[1];
+        const nz = scratch_face[2];
+
+        face_normal[face * 3] = nx;
+        face_normal[face * 3 + 1] = ny;
+        face_normal[face * 3 + 2] = nz;
+
+        face_length[face] = Math.sqrt(nx * nx + ny * ny + nz * nz);
+    }
+
+    /**
+     * Union-find over corners: two corners of one vertex share a root when the surface between them
+     * never turned far enough to be a crease.
+     * @type {Uint32Array}
+     */
+    const group = new Uint32Array(loop_pool.size);
+
+    for (let loop = 0; loop < loop_pool.size; loop++) {
+        group[loop] = loop;
+    }
+
+    const smooth_cosine = Math.cos((crease_angle * Math.PI) / 180);
+
+    const edge_pool = topology.edges;
+
+    for (let edge = 0; edge < edge_pool.size; edge++) {
+        if (!edge_pool.is_allocated(edge)) {
+            continue;
+        }
+
+        const first_loop = topology.edge_read_loop(edge);
+
+        if (first_loop === NULL_POINTER) {
+            continue;
+        }
+
+        let left = NULL_POINTER;
+        let right = NULL_POINTER;
+        let live = 0;
+
+        let loop = first_loop;
+
+        do {
+            const face = topology.loop_read_face(loop);
+
+            if (face !== NULL_POINTER && face_pool.is_allocated(face) && face_length[face] > 0) {
+                live++;
+
+                if (live === 1) {
+                    left = loop;
+                } else if (live === 2) {
+                    right = loop;
+                }
+            }
+
+            loop = topology.loop_read_radial_next(loop);
+        } while (loop !== first_loop && loop !== NULL_POINTER);
+
+        if (live !== 2) {
+            continue;
+        }
+
+        const left_face = topology.loop_read_face(left);
+        const right_face = topology.loop_read_face(right);
+
+        const cosine = (
+            face_normal[left_face * 3] * face_normal[right_face * 3]
+            + face_normal[left_face * 3 + 1] * face_normal[right_face * 3 + 1]
+            + face_normal[left_face * 3 + 2] * face_normal[right_face * 3 + 2]
+        ) / (face_length[left_face] * face_length[right_face]);
+
+        if (cosine < smooth_cosine) {
+            continue;
+        }
+
+        /*
+         A loop's edge runs from its own vertex to the next loop's, so on an edge's loop those two
+         are the edge's endpoints. Matching them up by vertex is what pairs the corner of one face
+         with the corner of the other *at the same point* -- the two faces may be wound oppositely,
+         which is exactly when the naive pairing would join the wrong ends.
+         */
+        const left_next = topology.loop_read_next(left);
+        const right_next = topology.loop_read_next(right);
+
+        if (topology.loop_read_vertex(left) === topology.loop_read_vertex(right)) {
+            join(group, left, right);
+            join(group, left_next, right_next);
+        } else {
+            join(group, left, right_next);
+            join(group, left_next, right);
+        }
+    }
+
+    /**
+     * Each group's area-weighted sum, accumulated at its root.
+     * @type {Float64Array}
+     */
+    const accumulated = new Float64Array(loop_pool.size * 3);
+
+    /*
+     Over faces and then their corners, which is the order `bt_mesh_compute_vertex_normals` sums in.
+     The order of a float64 sum is part of its answer, and reproducing it is what makes a mesh with
+     no crease byte-identical rather than merely equivalent.
+     */
+    for (let face = 0; face < face_pool.size; face++) {
+        if (!face_pool.is_allocated(face)) {
+            continue;
+        }
+
+        const first_loop = topology.face_read_loop(face);
+
+        if (first_loop === NULL_POINTER) {
+            continue;
+        }
+
+        const nx = face_normal[face * 3];
+        const ny = face_normal[face * 3 + 1];
+        const nz = face_normal[face * 3 + 2];
+
+        let loop = first_loop;
+
+        do {
+            const root = find(group, loop) * 3;
+
+            accumulated[root] += nx;
+            accumulated[root + 1] += ny;
+            accumulated[root + 2] += nz;
+
+            loop = topology.loop_read_next(loop);
+        } while (loop !== first_loop);
+    }
+
+    for (let loop = 0; loop < loop_pool.size; loop++) {
+        if (!loop_pool.is_allocated(loop)) {
+            continue;
+        }
+
+        if (pinned.has(topology.loop_read_vertex(loop))) {
+            continue;
+        }
+
+        const root = find(group, loop) * 3;
+
+        const x = accumulated[root];
+        const y = accumulated[root + 1];
+        const z = accumulated[root + 2];
+
+        const length = Math.sqrt(x * x + y * y + z * z);
+
+        if (length === 0) {
+            // An isolated corner, or a group whose faces cancel: no surface to take a normal from,
+            // so leave whatever it carried rather than inventing a direction.
+            continue;
+        }
+
+        // Scaled by the reciprocal rather than divided, because that is what
+        // `bt_mesh_compute_vertex_normals` does and `x * (1 / l)` is not `x / l`.
+        const scale = 1 / length;
+
+        scratch_normal[0] = x * scale;
+        scratch_normal[1] = y * scale;
+        scratch_normal[2] = z * scale;
+
+        normals.write(loop, scratch_normal, 0);
+    }
+}
+
+/**
+ * @param {Uint32Array} group
+ * @param {number} index
+ * @returns {number}
+ */
+function find(group, index) {
+    let root = index;
+
+    while (group[root] !== root) {
+        group[root] = group[group[root]];
+
+        root = group[root];
+    }
+
+    return root;
+}
+
+/**
+ * @param {Uint32Array} group
+ * @param {number} a
+ * @param {number} b
+ */
+function join(group, a, b) {
+    const root_a = find(group, a);
+    const root_b = find(group, b);
+
+    if (root_a !== root_b) {
+        group[root_b] = root_a;
+    }
+}

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

@@ -1,8 +1,8 @@
 /**
- * Vertex tangents of a mesh, written into its tangent channel.
+ * Tangents of a mesh, written into its tangent channel.
  *
  * A tangent is a direction *in the texture parameterization*, so where the mesh carries a `UV0` this
- * is Lengyel's per-triangle solve accumulated per vertex and orthogonalized against the normal —
+ * is Lengyel's per-triangle solve accumulated per **wedge** and orthogonalized against the normal —
  * {@link geometry_build_tangents}, the same pass {@link Geometry#computeTangents} runs, so an asset
  * that goes through the virtual-geometry builder gets the frame it would have got anywhere else.
  * Where the mesh carries no UVs there is no parameterization to be tangent to, and the frame becomes
@@ -12,20 +12,24 @@
  * the format's flat default, which is parallel to the normal over a whole band of any closed
  * surface and degenerates the frame there.
  *
+ * **Per wedge, and that is not a re-indexing of a per-vertex solve.** Lengyel's accumulation is over
+ * the triangles that share a value, and at a chart boundary the two sides do not: their UVs run in
+ * different directions and averaging them gives a tangent that is tangent to neither. So the solve
+ * is fed a mesh whose *vertices are the wedges* — the same substitution the cluster gather makes,
+ * and for the same reason — and the answer comes back one per wedge, which is then written to every
+ * corner of it.
+ *
  * `pinned` carries the same meaning and the same reason as it does for
  * {@link vgeo_compute_vertex_normals}: a vertex two groups share must carry byte-identical values in
  * both, or the seam a cut is allowed to put between them shades as a crease.
  *
- * The flat arrays this builds are indexed by *vertex id*, holes and all, so a pool with released
- * slots needs no compaction and no remap — a released slot is simply a triangle corner nothing
- * names.
- *
- * @param {VirtualGeometryMesh} mesh whose tangent and normal layers are sized by the vertex pool
+ * @param {VirtualGeometryMesh} mesh whose tangent and normal layers are sized by the loop pool
  * @param {Set<number>} pinned vertex ids to leave exactly as they are; empty for a mesh nothing has
  *     locked yet
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_compute_vertex_tangents(mesh: VirtualGeometryMesh, pinned: Set<number>): void;
+export function vgeo_compute_vertex_tangents(mesh: VirtualGeometryMesh, pinned: Set<number>, wedges: BtWedgeSet): void;
 //# sourceMappingURL=vgeo_compute_vertex_tangents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_compute_vertex_tangents.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_compute_vertex_tangents.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,gFAPW,IAAI,MAAM,CAAC,4BA2GrB"}

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

@@ -0,0 +1,151 @@
+import { assert } from "../../../../../../core/assert.js";
+import { build_tangent_from_normal } from "../../../normals/build_tangent_from_normal.js";
+import { geometry_build_tangents } from "../../../normals/geometry_build_tangents.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+
+/**
+ * One corner's tangent, on its way into the format's channel.
+ * @type {Float32Array}
+ */
+const scratch_tangent = new Float32Array(4);
+
+/**
+ * One corner's normal, read back out of the channel it ships in.
+ * @type {Float32Array}
+ */
+const scratch_normal = new Float32Array(3);
+
+/**
+ * Tangents of a mesh, written into its tangent channel.
+ *
+ * A tangent is a direction *in the texture parameterization*, so where the mesh carries a `UV0` this
+ * is Lengyel's per-triangle solve accumulated per **wedge** and orthogonalized against the normal —
+ * {@link geometry_build_tangents}, the same pass {@link Geometry#computeTangents} runs, so an asset
+ * that goes through the virtual-geometry builder gets the frame it would have got anywhere else.
+ * Where the mesh carries no UVs there is no parameterization to be tangent to, and the frame becomes
+ * an arbitrary but well-conditioned basis around the normal — Frisvad's, via
+ * {@link build_tangent_from_normal}. That is not a fallback for a broken input: a shading model that
+ * reads a tangent frame reads one whether or not the surface is textured, and the alternative is
+ * the format's flat default, which is parallel to the normal over a whole band of any closed
+ * surface and degenerates the frame there.
+ *
+ * **Per wedge, and that is not a re-indexing of a per-vertex solve.** Lengyel's accumulation is over
+ * the triangles that share a value, and at a chart boundary the two sides do not: their UVs run in
+ * different directions and averaging them gives a tangent that is tangent to neither. So the solve
+ * is fed a mesh whose *vertices are the wedges* — the same substitution the cluster gather makes,
+ * and for the same reason — and the answer comes back one per wedge, which is then written to every
+ * corner of it.
+ *
+ * `pinned` carries the same meaning and the same reason as it does for
+ * {@link vgeo_compute_vertex_normals}: a vertex two groups share must carry byte-identical values in
+ * both, or the seam a cut is allowed to put between them shades as a crease.
+ *
+ * @param {VirtualGeometryMesh} mesh whose tangent and normal layers are sized by the loop pool
+ * @param {Set<number>} pinned vertex ids to leave exactly as they are; empty for a mesh nothing has
+ *     locked yet
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_compute_vertex_tangents(mesh, pinned, wedges) {
+    const tangents = mesh.layers[VGEO_ATTRIBUTE.TANGENT];
+    const normals = mesh.layers[VGEO_ATTRIBUTE.NORMAL];
+
+    assert.notNull(tangents, 'mesh tangent channel');
+    assert.notNull(normals, 'mesh normal channel');
+
+    const topology = mesh.topology;
+
+    const loop_pool = topology.loops;
+
+    const uv = mesh.layers[VGEO_ATTRIBUTE.UV0];
+
+    if (uv === null) {
+        for (let loop = 0; loop < loop_pool.size; loop++) {
+            if (!loop_pool.is_allocated(loop)) {
+                continue;
+            }
+
+            if (pinned.has(topology.loop_read_vertex(loop))) {
+                continue;
+            }
+
+            normals.read(scratch_normal, 0, loop);
+
+            build_tangent_from_normal(
+                scratch_normal[0], scratch_normal[1], scratch_normal[2], 0, scratch_tangent
+            );
+
+            tangents.write(loop, scratch_tangent, 0);
+        }
+
+        return;
+    }
+
+    const wedge_count = wedges.count;
+
+    const position_data = new Float32Array(wedge_count * 3);
+    const normal_data = new Float32Array(wedge_count * 3);
+    const uv_data = new Float32Array(wedge_count * 2);
+
+    const face_pool = topology.faces;
+
+    const indices = [];
+
+    for (let face = 0; face < face_pool.size; face++) {
+        if (!face_pool.is_allocated(face)) {
+            continue;
+        }
+
+        const first_loop = topology.face_read_loop(face);
+
+        let loop = first_loop;
+
+        for (let corner = 0; corner < 3; corner++) {
+            const wedge = wedges.find(wedges.of_loop[loop]);
+
+            indices.push(wedge);
+
+            topology.vertex_read_coordinate(
+                position_data, wedge * 3, topology.loop_read_vertex(loop)
+            );
+
+            normals.read(normal_data, wedge * 3, loop);
+            uv.read(uv_data, wedge * 2, loop);
+
+            loop = topology.loop_read_next(loop);
+        }
+
+        assert.equal(loop, first_loop, `face ${face} is not an allocated triangle`);
+    }
+
+    const tangent_data = new Float32Array(wedge_count * 4);
+
+    geometry_build_tangents(
+        indices.length, indices, wedge_count,
+        uv_data, position_data, normal_data, tangent_data
+    );
+
+    for (let loop = 0; loop < loop_pool.size; loop++) {
+        if (!loop_pool.is_allocated(loop)) {
+            continue;
+        }
+
+        if (pinned.has(topology.loop_read_vertex(loop))) {
+            continue;
+        }
+
+        const address = wedges.find(wedges.of_loop[loop]) * 4;
+
+        // A tangent that came out non-finite is a frame the shading model cannot use and the
+        // octahedral encoder cannot represent, and it would reach the asset as a silently wrong
+        // word. Nothing in the solve should produce one on a mesh normalization has already passed.
+        assert.isFinite(tangent_data[address], 'tangent x');
+        assert.isFinite(tangent_data[address + 1], 'tangent y');
+        assert.isFinite(tangent_data[address + 2], 'tangent z');
+        assert.isFinite(tangent_data[address + 3], 'tangent handedness');
+
+        tangents.write(loop, tangent_data, address);
+    }
+}

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

@@ -34,13 +34,20 @@
  * and the fuse would then pick one of those halves to keep. Derived after it, the vertex has its
  * whole ring. Channels the source did carry are left exactly as they came.
  *
+ * **And the weld no longer flattens what it fused.** It merges *positions*, because connectivity is
+ * what it is for; the corners it re-points keep the values they arrived with, so a vertex the source
+ * split to say its two sides shade differently comes out of here still saying it. That is
+ * `WEDGE_PLAN_2026_09_18.md` §6.2, and the line it deleted was a whole module.
+ *
  * @param {VirtualGeometryMesh} mesh mutated in place
  * @param {number} weld_ratio fraction of the bounding-box diagonal; see
  *     {@link VGeoBuildOptions#weld_ratio}
+ * @param {number} [crease_angle] degrees; see {@link VGeoBuildOptions#crease_angle}. Only reaches a
+ *     channel the source did not author.
  * @returns {number} the object-space distance the ratio came to for this mesh
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_normalize_source(mesh: VirtualGeometryMesh, weld_ratio: number): number;
+export function vgeo_normalize_source(mesh: VirtualGeometryMesh, weld_ratio: number, crease_angle?: number): number;
 //# sourceMappingURL=vgeo_normalize_source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_normalize_source.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_normalize_source.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,6EATW,MAAM,iBAEN,MAAM,GAEJ,MAAM,CA+ClB"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_normalize_source.js → mesh/vgeo_normalize_source.js}

@@ -1,24 +1,26 @@
-import { assert } from "../../../../../core/assert.js";
+import { assert } from "../../../../../../core/assert.js";
 import {
     bt_mesh_cleanup_faceless_references
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_cleanup_faceless_references.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_cleanup_faceless_references.js";
 import {
     bt_mesh_collapse_short_edges
-} from "../../../../../core/geom/3d/topology/struct/binary/io/edge/bt_mesh_collapse_short_edges.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/edge/bt_mesh_collapse_short_edges.js";
 import {
     bt_mesh_fuse_duplicate_edges
-} from "../../../../../core/geom/3d/topology/struct/binary/io/edge/bt_mesh_fuse_duplicate_edges.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/edge/bt_mesh_fuse_duplicate_edges.js";
 import {
     bt_mesh_kill_degenerate_faces
-} from "../../../../../core/geom/3d/topology/struct/binary/io/face/bt_mesh_kill_degenerate_faces.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/face/bt_mesh_kill_degenerate_faces.js";
 import {
     bt_merge_vertices_by_distance
-} from "../../../../../core/geom/3d/topology/struct/binary/io/vertex/bt_merge_vertices_by_distance.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/vertex/bt_merge_vertices_by_distance.js";
 import {
     bt_mesh_relative_merge_distance
-} from "../../../../../core/geom/3d/topology/struct/binary/io/vertex/bt_mesh_relative_merge_distance.js";
-import { bt_mesh_validate } from "../../../../../core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js";
-import { VGEO_ATTRIBUTE } from "../format/attribute/VGEO_ATTRIBUTE.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/vertex/bt_mesh_relative_merge_distance.js";
+import { bt_mesh_validate } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+import { vgeo_mesh_wedges } from "../../format/attribute/vgeo_mesh_wedges.js";
+import { VGEO_CREASE_ANGLE } from "./VGEO_CREASE_ANGLE.js";
 import { vgeo_compute_vertex_normals } from "./vgeo_compute_vertex_normals.js";
 import { vgeo_compute_vertex_tangents } from "./vgeo_compute_vertex_tangents.js";
 
@@ -65,15 +67,22 @@ const NOTHING_PINNED = new Set();
  * and the fuse would then pick one of those halves to keep. Derived after it, the vertex has its
  * whole ring. Channels the source did carry are left exactly as they came.
  *
+ * **And the weld no longer flattens what it fused.** It merges *positions*, because connectivity is
+ * what it is for; the corners it re-points keep the values they arrived with, so a vertex the source
+ * split to say its two sides shade differently comes out of here still saying it. That is
+ * `WEDGE_PLAN_2026_09_18.md` §6.2, and the line it deleted was a whole module.
+ *
  * @param {VirtualGeometryMesh} mesh mutated in place
  * @param {number} weld_ratio fraction of the bounding-box diagonal; see
  *     {@link VGeoBuildOptions#weld_ratio}
+ * @param {number} [crease_angle] degrees; see {@link VGeoBuildOptions#crease_angle}. Only reaches a
+ *     channel the source did not author.
  * @returns {number} the object-space distance the ratio came to for this mesh
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_normalize_source(mesh, weld_ratio) {
+export function vgeo_normalize_source(mesh, weld_ratio, crease_angle = VGEO_CREASE_ANGLE) {
     const topology = mesh.topology;
 
     const weld_distance = bt_mesh_relative_merge_distance(topology, weld_ratio);
@@ -101,11 +110,17 @@ export function vgeo_normalize_source(mesh, weld_ratio) {
     // Normals first: the tangent solve reads them, and a synthesized normal beside an authored
     // tangent is still the pair the frame is built from.
     if (mesh.synthesized[VGEO_ATTRIBUTE.NORMAL]) {
-        vgeo_compute_vertex_normals(mesh, NOTHING_PINNED);
+        vgeo_compute_vertex_normals(mesh, NOTHING_PINNED, crease_angle);
     }
 
+    /*
+     And the wedges only once the normals are settled, because a crease the pass above just made is
+     one of the things a wedge is. A tangent it has not computed yet is uniform and splits nothing,
+     and the one it is about to compute is a function of the wedge -- so this partition is the same
+     one `vgeo_build_leaf_frontier` reads back afterwards, with or without the tangent in it.
+     */
     if (mesh.synthesized[VGEO_ATTRIBUTE.TANGENT]) {
-        vgeo_compute_vertex_tangents(mesh, NOTHING_PINNED);
+        vgeo_compute_vertex_tangents(mesh, NOTHING_PINNED, vgeo_mesh_wedges(topology));
     }
 
     return weld_distance;