@woosh/meep-engine 3.28.0 → 3.29.0

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

@@ -0,0 +1,243 @@
+import { assert } from "../../../../../../core/assert.js";
+import { build_tangent_from_normal } from "../../../normals/build_tangent_from_normal.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+
+/**
+ * One vertex's widest channel record on its way into a layer.
+ * @type {Float32Array}
+ */
+const scratch_record = new Float32Array(4);
+
+/**
+ * The normal the tangent of the same vertex is squared up against.
+ * @type {Float32Array}
+ */
+const scratch_normal = new Float32Array(3);
+
+/**
+ * Frisvad's basis, when the carried tangent has degenerated.
+ * @type {Float32Array}
+ */
+const scratch_fallback = new Float32Array(4);
+
+/**
+ * Put the simplifier's vector back into the mesh's layers, and square up the frame it describes.
+ *
+ * **Nothing is *derived* for a pinned vertex.** That is the whole of what pinning means here and it
+ * is what lets a cut place two levels of detail side by side: a vertex two groups share must carry
+ * byte-identical values in both payloads, or the seam that is watertight in geometry shades as a
+ * crease (`ATTRIBUTE_PLAN_2026_09_18.md` §3, invariant 2).
+ *
+ * Its corners are still *written*, with what the vector says it already had, and that is not a
+ * loophole — it is the same guarantee under corner storage. A collapse re-points the victim's corners
+ * onto the survivor and they arrive carrying the victim's appearance, so leaving a pinned vertex
+ * alone no longer means leaving its value alone. The write is exact: those float32 records are where
+ * the vector was read from.
+ *
+ * Two channels need more than a copy:
+ *
+ * - **The normal** is renormalized. A blend of two unit vectors is not one, and a normal that is
+ *   not unit is not a normal. Two exactly opposing normals blend to nothing, which has no direction
+ *   to report and so keeps whatever the vertex already carried, the same answer
+ *   {@link bt_mesh_compute_vertex_normals} gives for a vertex whose faces cancel.
+ * - **The colour** is clamped to `[0, 1]`. The value a collapse carries is a *fit*, not an average,
+ *   and a fit extrapolates — which is right for a texture coordinate and wrong for a channel with a
+ *   range. The encoder saturates anyway, so what this stops is not a corrupt word but the drift:
+ *   an out-of-range value left in the layer is what the next level's field is fitted from, and it
+ *   would walk further out at every round.
+ * - **The tangent** is re-orthogonalized against that normal and renormalized, and its fourth
+ *   component — handedness, a discrete `±1` — is left exactly as the survivor had it, because it is
+ *   a flag rather than a quantity and there is no average of `+1` and `-1`. A tangent that has
+ *   blended its way onto the normal has no perpendicular component left to keep, and falls back to
+ *   Frisvad's basis rather than to a zero vector the octahedral encoder cannot represent.
+ *
+ * @param {VirtualGeometryMesh} mesh mutated in place
+ * @param {{components: number, channels: {attribute: number, offset: number, count: number}[]}} layout
+ *     from {@link vgeo_attribute_vector_layout}, the same one {@link vgeo_attribute_vector_read} used
+ * @param {Float64Array} values indexed by wedge id, as the simplifier left it
+ * @param {Float64Array|null} verbatim indexed by wedge id, as it was read — the simplifier does not
+ *     take it and has nothing to say about it. `null` where the layout has no such component, which
+ *     is every mesh whose tangent is derived rather than carried.
+ * @param {Set<number>} pinned vertex ids nothing may be *derived* for
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one, as the simplifier left it
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_write(mesh, layout, values, verbatim, pinned, wedges) {
+    assert.greaterThan(layout.components, 0, 'layout.components');
+
+    const topology = mesh.topology;
+
+    const components = layout.components;
+    const channels = layout.channels;
+
+    const normal_layer = mesh.layers[VGEO_ATTRIBUTE.NORMAL];
+
+    const carries_tangent = channels.some(
+        (channel) => channel.attribute === VGEO_ATTRIBUTE.TANGENT
+    );
+
+    /*
+     Over corners. The value is decided per *wedge* and stored per corner, so every corner of a wedge
+     gets the same one — and the frame fixups below, being functions of that value, agree corner for
+     corner without having to be told to. Two corners of one vertex in different wedges get different
+     ones, which is a hard edge, and is the entire point.
+     */
+    const loop_pool = topology.loops;
+
+    for (let loop = 0; loop < loop_pool.size; loop++) {
+        if (!loop_pool.is_allocated(loop)) {
+            continue;
+        }
+
+        const vertex = topology.loop_read_vertex(loop);
+
+        /*
+         A pinned vertex IS written, and writing it is what keeps it pinned. The vector holds what it
+         had -- nothing in the simplifier touches a restricted survivor's entry -- while its *corners*
+         do not, because a collapse re-points the victim's onto it and those arrive carrying the
+         victim's appearance. Writing the vector back over all of them is what puts that right, and it
+         is exact: the value came out of these same float32 records and goes back into them unchanged.
+
+         What it must not do is *derive* anything for a pinned vertex, so the fixups below are the
+         one thing that stays behind the flag.
+         */
+        const restore = pinned.has(vertex);
+
+        const wedge = wedges.find(wedges.of_loop[loop]);
+
+        const base = wedge * components;
+
+        for (const channel of channels) {
+            const layer = mesh.layers[channel.attribute];
+
+            // Read first: a channel the vector carries only part of — the tangent, whose handedness
+            // stays with the survivor — keeps the rest of its record this way.
+            layer.read(scratch_record, 0, loop);
+
+            for (let component = 0; component < channel.count; component++) {
+                const value = values[base + channel.offset + component];
+
+                assert.isFinite(value, 'carried attribute component');
+
+                scratch_record[channel.source + component] = value;
+            }
+
+            if (restore) {
+                layer.write(loop, scratch_record, 0);
+
+                continue;
+            }
+
+            if (channel.attribute === VGEO_ATTRIBUTE.NORMAL) {
+                normalize_in_place(scratch_record, layer, loop);
+            } else if (channel.attribute === VGEO_ATTRIBUTE.COLOR) {
+                for (let component = 0; component < channel.count; component++) {
+                    scratch_record[component] = Math.min(1, Math.max(0, scratch_record[component]));
+                }
+            }
+
+            layer.write(loop, scratch_record, 0);
+        }
+
+        // After the loop rather than inside it, so the normal it squares up against is the one just
+        // written rather than whichever order the channel list happens to be in.
+        if (carries_tangent && !restore) {
+            orthogonalize_tangent(mesh, normal_layer, loop);
+        }
+
+        /*
+         Last, and over every corner whether the vertex is pinned or not. These components never
+         travelled through the fit and never will -- they are the survivor's, and putting them back
+         is what stops a corner a collapse donated from keeping the flag it arrived with.
+         */
+        if (verbatim === null) {
+            continue;
+        }
+
+        const verbatim_base = wedge * layout.verbatim_components;
+
+        for (const channel of layout.verbatim) {
+            const layer = mesh.layers[channel.attribute];
+
+            layer.read(scratch_record, 0, loop);
+
+            for (let component = 0; component < channel.count; component++) {
+                scratch_record[channel.source + component] =
+                    verbatim[verbatim_base + channel.offset + component];
+            }
+
+            layer.write(loop, scratch_record, 0);
+        }
+    }
+}
+
+/**
+ * Scale a channel record's first three components to unit length, leaving them alone when there is
+ * no direction there to scale.
+ *
+ * @param {Float32Array} record
+ * @param {BinaryDataLayer} layer the record came from, read again when the blend cancelled
+ * @param {number} loop
+ */
+function normalize_in_place(record, layer, loop) {
+    const length = Math.hypot(record[0], record[1], record[2]);
+
+    if (length === 0) {
+        layer.read(record, 0, loop);
+
+        return;
+    }
+
+    record[0] /= length;
+    record[1] /= length;
+    record[2] /= length;
+}
+
+/**
+ * Square one vertex's tangent up against its normal.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {BinaryDataLayer} normal_layer
+ * @param {number} loop
+ */
+function orthogonalize_tangent(mesh, normal_layer, loop) {
+    const tangent_layer = mesh.layers[VGEO_ATTRIBUTE.TANGENT];
+
+    normal_layer.read(scratch_normal, 0, loop);
+    tangent_layer.read(scratch_record, 0, loop);
+
+    const nx = scratch_normal[0];
+    const ny = scratch_normal[1];
+    const nz = scratch_normal[2];
+
+    const dot = nx * scratch_record[0] + ny * scratch_record[1] + nz * scratch_record[2];
+
+    const tx = scratch_record[0] - nx * dot;
+    const ty = scratch_record[1] - ny * dot;
+    const tz = scratch_record[2] - nz * dot;
+
+    const length = Math.hypot(tx, ty, tz);
+
+    if (length === 0) {
+        // Nothing perpendicular survived: the carried tangent had blended its way onto the normal.
+        build_tangent_from_normal(nx, ny, nz, 0, scratch_fallback);
+
+        scratch_record[0] = scratch_fallback[0];
+        scratch_record[1] = scratch_fallback[1];
+        scratch_record[2] = scratch_fallback[2];
+    } else {
+        scratch_record[0] = tx / length;
+        scratch_record[1] = ty / length;
+        scratch_record[2] = tz / length;
+    }
+
+    // A frame the shading model cannot use and the octahedral encoder cannot represent would reach
+    // the asset as a silently wrong word.
+    assert.isFinite(scratch_record[0], 'tangent x');
+    assert.isFinite(scratch_record[1], 'tangent y');
+    assert.isFinite(scratch_record[2], 'tangent z');
+
+    tangent_layer.write(loop, scratch_record, 0);
+}

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

@@ -1,10 +1,29 @@
 /**
- * Area-weighted vertex normals of a mesh, written into its normal channel.
+ * 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
@@ -13,17 +32,14 @@
  * 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.
  *
- * The pass itself is {@link bt_mesh_compute_vertex_normals}; all this adds is the pin rule and
- * lifting its result out of the topology's own normal slots and into the format's normal attribute,
- * which is where the encoder reads from.
- *
- * @param {VirtualGeometryMesh} mesh whose normal layer is sized by the vertex pool and so carries a
- *     slot for every live vertex by construction
+ * @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>): void;
+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

@@ -1 +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":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,+EANW,IAAI,MAAM,CAAC,QAyCrB"}
+{"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

@@ -1,22 +1,55 @@
 import { assert } from "../../../../../../core/assert.js";
 import {
-    bt_mesh_compute_vertex_normals
-} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_normals.js";
+    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 vertex's normal, on its way out of the topology's slot and into the format's channel.
+ * One corner's normal, on its way into the format's channel.
  * @type {Float32Array}
  */
 const scratch_normal = new Float32Array(3);
 
 /**
- * Area-weighted vertex normals of a mesh, written into its normal channel.
+ * 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
@@ -25,51 +58,243 @@ const scratch_normal = new Float32Array(3);
  * 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.
  *
- * The pass itself is {@link bt_mesh_compute_vertex_normals}; all this adds is the pin rule and
- * lifting its result out of the topology's own normal slots and into the format's normal attribute,
- * which is where the encoder reads from.
- *
- * @param {VirtualGeometryMesh} mesh whose normal layer is sized by the vertex pool and so carries a
- *     slot for every live vertex by construction
+ * @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) {
+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;
 
-    bt_mesh_compute_vertex_normals(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;
 
-    const vertex_pool = topology.vertices;
+        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 vertex = 0; vertex < vertex_pool.size; vertex++) {
-        if (!vertex_pool.is_allocated(vertex)) {
-            // a released slot's normal is whatever the vertex that used to live there left behind
+    for (let edge = 0; edge < edge_pool.size; edge++) {
+        if (!edge_pool.is_allocated(edge)) {
             continue;
         }
 
-        if (pinned.has(vertex)) {
+        const first_loop = topology.edge_read_loop(edge);
+
+        if (first_loop === NULL_POINTER) {
             continue;
         }
 
-        topology.vertex_read_normal(scratch_normal, 0, vertex);
+        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;
+                }
+            }
 
-        const x = scratch_normal[0];
-        const y = scratch_normal[1];
-        const z = scratch_normal[2];
+            loop = topology.loop_read_radial_next(loop);
+        } while (loop !== first_loop && loop !== NULL_POINTER);
 
-        if (x === 0 && y === 0 && z === 0) {
-            // An isolated or fully degenerate vertex has no surface to take a normal from; leave
-            // whatever it carried rather than inventing a direction.
+        if (live !== 2) {
             continue;
         }
 
-        normals.write(vertex, scratch_normal, 0);
+        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/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

@@ -1 +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":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,gFANW,IAAI,MAAM,CAAC,QAmGrB"}
+{"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"}