@flighthq/mesh 0.3.0 → 0.3.1-next.1041.35b950c

package/dist/meshGeometryBuilders.js

@@ -1,13 +1,12 @@
 import { createMeshGeometry } from './meshGeometry';
-import { refreshMeshGeometryBounds } from './meshGeometryCompute';
+import { computeMeshGeometryTangents, refreshMeshGeometryBounds } from './meshGeometryCompute';
 // Primitive builders for the canonical interleaved PBR vertex record:
 //   position(3) + normal(3) + tangent(4, w = handedness) + uv0(2) = 12 f32 / 48 bytes.
 // Coordinate and winding convention is pinned across the 3D suite: RIGHT-HANDED coordinates,
 // COUNTER-CLOCKWISE (CCW) front faces, and the tangent `w` component is the bitangent sign per
 // glTF — bitangent = cross(normal, tangent.xyz) * tangent.w. Every builder writes outward-facing
-// normals, generates UVs, computes per-vertex tangents, and fills the cached local-space bounds.
-// Builder topology already duplicates every UV discontinuity, so its compact tangent finalizer does
-// not need the general authoring API's topology reconciliation.
+// normals, generates UVs, computes per-vertex tangents (via computeMeshGeometryTangents, which
+// sets the correct w-sign from the UV gradient), and fills the cached local-space bounds.
 // Builds an axis-aligned box of the given dimensions centered at the origin, one quad per face
 // with per-face outward normals and per-face 0..1 UVs (so each face textures independently).
 export function createBoxMeshGeometry(width = 1, height = 1, depth = 1) {
@@ -41,9 +40,10 @@ export function createBoxMeshGeometry(width = 1, height = 1, depth = 1) {
 // (excluding the caps) centered at the origin, with `radialSegments` around the axis and
 // `capSegments` latitudinal divisions per hemisphere. Normals are smooth across the seam between
 // the caps and the side wall. UVs run v from 0 (top) to 1 (bottom) along the full length.
+// Segment counts must be finite; fractional values are floored after clamping to their minima.
 export function createCapsuleMeshGeometry(radius = 0.5, height = 1, radialSegments = 16, capSegments = 8) {
-    const rSeg = Math.max(3, radialSegments);
-    const cSeg = Math.max(1, capSegments);
+    const rSeg = normalizeMeshCount(radialSegments, 3);
+    const cSeg = normalizeMeshCount(capSegments, 1);
     const halfH = height * 0.5;
     const positions = [];
     const normals = [];
@@ -63,17 +63,20 @@ export function createCapsuleMeshGeometry(radius = 0.5, height = 1, radialSegmen
         }
     };
     const ringVertexCount = rSeg + 1;
-    const vDivisor = 2 * cSeg + 1; // total number of rings minus 1
+    const ringCount = 2 * cSeg + 2;
+    const vDivisor = ringCount - 1;
     // Top hemisphere (phi from 0 to PI/2).
     for (let j = 0; j <= cSeg; j++) {
         addRing((j / cSeg) * (Math.PI * 0.5), halfH);
     }
+    // Duplicate the equator at the bottom of the cylindrical span. The two equators share radial
+    // normals but need distinct positions (and UV rows) to form the side wall between the caps.
+    addRing(Math.PI * 0.5, -halfH);
     // Bottom hemisphere (phi from PI/2 to PI).
     for (let j = 1; j <= cSeg; j++) {
         addRing(Math.PI * 0.5 + (j / cSeg) * (Math.PI * 0.5), -halfH);
     }
     // Fix up the v UV coordinate.
-    const ringCount = 2 * cSeg + 1;
     for (let j = 0; j < ringCount; j++) {
         const v = j / vDivisor;
         for (let i = 0; i <= rSeg; i++) {
@@ -81,14 +84,15 @@ export function createCapsuleMeshGeometry(radius = 0.5, height = 1, radialSegmen
         }
     }
     // Connect rings into quads.
-    const totalRings = 2 * cSeg + 1;
-    for (let j = 0; j < totalRings - 1; j++) {
+    for (let j = 0; j < ringCount - 1; j++) {
         for (let i = 0; i < rSeg; i++) {
             const a = j * ringVertexCount + i;
             const b = a + 1;
             const c = a + ringVertexCount;
             const d = c + 1;
-            indices.push(a, c, b, b, c, d);
+            // Reversed against the sphere's identical-looking line on purpose: this builder walks its
+            // rings the opposite way round, so the same index order faces the other way.
+            indices.push(a, b, c, b, d, c);
         }
     }
     return buildCanonicalMeshGeometry(positions, normals, uvs, indices);
@@ -97,8 +101,9 @@ export function createCapsuleMeshGeometry(radius = 0.5, height = 1, radialSegmen
 // `radius` is the outer radius; `segments` is the number of rim vertices. A center vertex fans
 // out to `segments` rim vertices via a triangle fan, so the result is `segments` triangles.
 // UVs map from the disc plane onto 0..1 with (0.5, 0.5) at the center.
+// `segments` must be finite; a fractional value is floored after clamping to the minimum of 3.
 export function createCircleMeshGeometry(radius = 0.5, segments = 32) {
-    const segs = Math.max(3, segments);
+    const segs = normalizeMeshCount(segments, 3);
     const positions = [];
     const normals = [];
     const uvs = [];
@@ -109,6 +114,7 @@ export function createCircleMeshGeometry(radius = 0.5, segments = 32) {
 // Builds a right circular cone of `radius` and `height` centered at the origin, apex at +Y, base
 // at -Y, with `radialSegments` around the axis. A capped base disc is included when `capped` is
 // true (default). Side normals are smooth around the ring and slanted by the cone half-angle.
+// `radialSegments` must be finite; a fractional value is floored after clamping to 3.
 export function createConeMeshGeometry(radius = 0.5, height = 1, radialSegments = 32, capped = true) {
     return createCylinderMeshGeometry(0, radius, height, radialSegments, capped);
 }
@@ -116,15 +122,17 @@ export function createConeMeshGeometry(radius = 0.5, height = 1, radialSegments
 // top (`topRadius`) and bottom (`bottomRadius`) radii so it also serves as a truncated cone (a
 // zero top radius yields a cone). `radialSegments` rings around the axis; `capped` adds top and
 // bottom discs (skipping a zero-radius cap).
+// `radialSegments` must be finite; a fractional value is floored after clamping to 3. A zero
+// height is a valid collapsed cylinder and uses stable radial side normals.
 export function createCylinderMeshGeometry(topRadius = 0.5, bottomRadius = 0.5, height = 1, radialSegments = 32, capped = true) {
-    const segments = Math.max(3, radialSegments);
+    const segments = normalizeMeshCount(radialSegments, 3);
     const halfHeight = height * 0.5;
     const positions = [];
     const normals = [];
     const uvs = [];
     const indices = [];
     // Side wall: slope of the silhouette feeds the radial normal tilt.
-    const slope = (bottomRadius - topRadius) / height;
+    const slope = height !== 0 ? (bottomRadius - topRadius) / height : 0;
     const sideStart = positions.length / 3;
     for (let y = 0; y <= 1; y++) {
         const radius = y === 0 ? bottomRadius : topRadius;
@@ -143,12 +151,24 @@ export function createCylinderMeshGeometry(topRadius = 0.5, bottomRadius = 0.5,
             uvs.push(s / segments, y);
         }
     }
+    // Each segment is a quad split into (a, c, b) and (b, c, d). When one radius is zero that ring
+    // collapses to a single point, so one of the two triangles has two coincident corners and encloses no
+    // area: it consumes index bandwidth and a vertex-shader invocation to rasterise nothing. A cone is
+    // exactly that case — it is this cylinder with a zero top radius — so a third of its triangles were
+    // dead. Dropping the collapsed triangle leaves the surviving fan untouched, vertices included: the
+    // apex ring keeps one vertex per segment because each carries its own u, which is what lets the
+    // texture vary around the cone.
+    const topCollapsed = topRadius === 0;
+    const bottomCollapsed = bottomRadius === 0;
     for (let s = 0; s < segments; s++) {
         const a = sideStart + s;
         const b = sideStart + s + 1;
         const c = sideStart + (segments + 1) + s;
         const d = sideStart + (segments + 1) + s + 1;
-        indices.push(a, c, b, b, c, d);
+        if (!bottomCollapsed)
+            indices.push(a, c, b);
+        if (!topCollapsed)
+            indices.push(b, c, d);
     }
     if (capped) {
         if (bottomRadius > 0) {
@@ -161,11 +181,13 @@ export function createCylinderMeshGeometry(topRadius = 0.5, bottomRadius = 0.5,
     return buildCanonicalMeshGeometry(positions, normals, uvs, indices);
 }
 // Builds a regular dodecahedron (12 pentagonal faces, triangulated) inscribed in a sphere of `radius`.
+// `detail` must be finite; a fractional value is floored after clamping to 0..5.
 export function createDodecahedronMeshGeometry(radius = 0.5, detail = 0) {
     return createPolyhedronMeshGeometry(DODECAHEDRON_VERTS, DODECAHEDRON_FACES, radius, detail);
 }
 // Builds a regular icosahedron (20 triangular faces) inscribed in a sphere of `radius`.
 // This is the base shape for createIcosphereMeshGeometry at detail=0.
+// `detail` must be finite; a fractional value is floored after clamping to 0..5.
 export function createIcosahedronMeshGeometry(radius = 0.5, detail = 0) {
     return createPolyhedronMeshGeometry(ICOSAHEDRON_VERTS, ICOSAHEDRON_FACES, radius, detail);
 }
@@ -174,8 +196,9 @@ export function createIcosahedronMeshGeometry(radius = 0.5, detail = 0) {
 // from a regular icosahedron, each face is subdivided `subdivisions` times (0 = raw icosahedron,
 // 1 = 80 triangles, 2 = 320, etc.). Normals are the unit-sphere position direction; UVs are
 // spherical (longitude/latitude).
+// `subdivisions` must be finite; a fractional value is floored after clamping to 0..6.
 export function createIcosphereMeshGeometry(radius = 0.5, subdivisions = 2) {
-    const subs = Math.max(0, Math.min(subdivisions, 6)); // cap at 6 to prevent > 262k triangles
+    const subs = normalizeMeshCount(subdivisions, 0, 6); // cap at 6 to prevent > 262k triangles
     // Icosahedron base vertices (unit sphere).
     const phi = (1 + Math.sqrt(5)) * 0.5;
     const scale = 1 / Math.sqrt(1 + phi * phi);
@@ -250,18 +273,18 @@ export function createIcosphereMeshGeometry(radius = 0.5, subdivisions = 2) {
     const normals = [];
     const uvs = [];
     const faceIndices = [];
-    // Emit unique vertices with spherical UVs. Since the seam is complex for an icosphere,
-    // we emit independent vertices per face (non-indexed, then buildCanonicalMeshGeometry).
+    // Emit unique vertices with spherical UVs. Independent vertices per face (non-indexed, then
+    // buildCanonicalMeshGeometry) are what let a seam vertex carry a different u on each face it touches;
+    // correctSeamU then chooses those values, which is the half that makes the seam actually work.
     for (const [a, b, c] of faces) {
-        for (const vi of [a, b, c]) {
-            const v = verts[vi];
+        const corner = [a, b, c];
+        const seamU = faceSphericalU(verts[a], verts[b], verts[c]);
+        for (let k = 0; k < 3; k++) {
+            const v = verts[corner[k]];
             const nx = v[0], ny = v[1], nz = v[2];
             positions.push(radius * nx, radius * ny, radius * nz);
             normals.push(nx, ny, nz);
-            // Spherical UV: u=longitude (0..1), v=latitude (0..1, 0=top).
-            const u = 0.5 + Math.atan2(nz, nx) / (Math.PI * 2);
-            const sv = 0.5 - Math.asin(Math.max(-1, Math.min(1, ny))) / Math.PI;
-            uvs.push(u, sv);
+            uvs.push(seamU[k], sphericalV(ny));
         }
     }
     for (let i = 0; i < positions.length / 3; i++) {
@@ -270,15 +293,17 @@ export function createIcosphereMeshGeometry(radius = 0.5, subdivisions = 2) {
     return buildCanonicalMeshGeometry(positions, normals, uvs, faceIndices);
 }
 // Builds a regular octahedron (8 triangular faces) inscribed in a sphere of `radius`.
+// `detail` must be finite; a fractional value is floored after clamping to 0..5.
 export function createOctahedronMeshGeometry(radius = 0.5, detail = 0) {
     return createPolyhedronMeshGeometry(OCTAHEDRON_VERTS, OCTAHEDRON_FACES, radius, detail);
 }
 // Builds a flat plane in the XZ plane (Y up, normal +Y) centered at the origin, subdivided into
 // `widthSegments` x `depthSegments` quads with a 0..1 UV grid. Suitable as a ground plane or a
 // textured "panel" mesh.
+// Segment counts must be finite; fractional values are floored after clamping to 1.
 export function createPlaneMeshGeometry(width = 1, depth = 1, widthSegments = 1, depthSegments = 1) {
-    const wSeg = Math.max(1, widthSegments);
-    const dSeg = Math.max(1, depthSegments);
+    const wSeg = normalizeMeshCount(widthSegments, 1);
+    const dSeg = normalizeMeshCount(depthSegments, 1);
     const hw = width * 0.5, hd = depth * 0.5;
     const positions = [];
     const normals = [];
@@ -313,8 +338,9 @@ export function createPlaneMeshGeometry(width = 1, depth = 1, widthSegments = 1,
 // This is the shared backend for the Platonic solid builders and is also exported for custom
 // polyhedra. Vertices are projected onto the unit sphere before scaling so the output is a
 // geodesic sphere approximation.
+// `detail` must be finite; a fractional value is floored after clamping to 0..5.
 export function createPolyhedronMeshGeometry(vertexPositions, faceIndices, radius = 0.5, detail = 0) {
-    const subs = Math.max(0, Math.min(detail, 5));
+    const subs = normalizeMeshCount(detail, 0, 5);
     const verts = vertexPositions.map(([x, y, z]) => {
         const len = Math.sqrt(x * x + y * y + z * z);
         return [x / len, y / len, z / len];
@@ -353,14 +379,14 @@ export function createPolyhedronMeshGeometry(vertexPositions, faceIndices, radiu
     const uvs = [];
     const flatIndices = [];
     for (const [a, b, c] of faces) {
-        for (const vi of [a, b, c]) {
-            const v = verts[vi];
+        const corner = [a, b, c];
+        const seamU = faceSphericalU(verts[a], verts[b], verts[c]);
+        for (let k = 0; k < 3; k++) {
+            const v = verts[corner[k]];
             const nx = v[0], ny = v[1], nz = v[2];
             positions.push(radius * nx, radius * ny, radius * nz);
             normals.push(nx, ny, nz);
-            const u = 0.5 + Math.atan2(nz, nx) / (Math.PI * 2);
-            const sv = 0.5 - Math.asin(Math.max(-1, Math.min(1, ny))) / Math.PI;
-            uvs.push(u, sv);
+            uvs.push(seamU[k], sphericalV(ny));
         }
     }
     for (let i = 0; i < positions.length / 3; i++)
@@ -381,8 +407,9 @@ export function createQuadMeshGeometry(width = 1, height = 1) {
 // Builds a flat ring (annulus) in the XZ plane centered at the origin. `innerRadius` is the
 // hole radius and `outerRadius` is the ring's outer edge. Normal is +Y. `segments` is the
 // number of vertices around the ring. UVs map inner radius to u=0 and outer to u=1.
+// `segments` must be finite; a fractional value is floored after clamping to 3.
 export function createRingMeshGeometry(innerRadius = 0.25, outerRadius = 0.5, segments = 32) {
-    const segs = Math.max(3, segments);
+    const segs = normalizeMeshCount(segments, 3);
     const positions = [];
     const normals = [];
     const uvs = [];
@@ -412,9 +439,10 @@ export function createRingMeshGeometry(innerRadius = 0.25, outerRadius = 0.5, se
 // Builds a UV sphere of `radius` centered at the origin, with `widthSegments` longitudinal and
 // `heightSegments` latitudinal divisions. Normals are the unit position direction; UVs map
 // longitude to u and latitude to v.
+// Segment counts must be finite; fractional values are floored after clamping to 3x2.
 export function createSphereMeshGeometry(radius = 0.5, widthSegments = 32, heightSegments = 16) {
-    const wSeg = Math.max(3, widthSegments);
-    const hSeg = Math.max(2, heightSegments);
+    const wSeg = normalizeMeshCount(widthSegments, 3);
+    const hSeg = normalizeMeshCount(heightSegments, 2);
     const positions = [];
     const normals = [];
     const uvs = [];
@@ -448,15 +476,17 @@ export function createSphereMeshGeometry(radius = 0.5, widthSegments = 32, heigh
     return buildCanonicalMeshGeometry(positions, normals, uvs, indices);
 }
 // Builds a regular tetrahedron (4 triangular faces) inscribed in a sphere of `radius`.
+// `detail` must be finite; a fractional value is floored after clamping to 0..5.
 export function createTetrahedronMeshGeometry(radius = 0.5, detail = 0) {
     return createPolyhedronMeshGeometry(TETRAHEDRON_VERTS, TETRAHEDRON_FACES, radius, detail);
 }
 // Builds a torus knot: a torus-shaped curve wound `p` times around the Z axis and `q` times
 // around the tube axis. `radius` is the distance from the center to the tube center line;
 // `tube` is the tube radius. Normals and UVs are generated per the standard torus knot geometry.
+// Segment counts must be finite; fractional values are floored after clamping to 3.
 export function createTorusKnotMeshGeometry(radius = 0.5, tube = 0.15, tubularSegments = 64, radialSegments = 8, p = 2, q = 3) {
-    const tSeg = Math.max(3, tubularSegments);
-    const rSeg = Math.max(3, radialSegments);
+    const tSeg = normalizeMeshCount(tubularSegments, 3);
+    const rSeg = normalizeMeshCount(radialSegments, 3);
     const positions = [];
     const normals = [];
     const uvs = [];
@@ -517,7 +547,9 @@ export function createTorusKnotMeshGeometry(radius = 0.5, tube = 0.15, tubularSe
             const b = a + 1;
             const c = a + rowStride;
             const d = c + 1;
-            indices.push(a, c, b, b, c, d);
+            // Reversed for the same reason as the capsule: this builder sweeps its tube rings the
+            // opposite way round from the sphere, so the same index order faced inward.
+            indices.push(a, b, c, b, d, c);
         }
     }
     return buildCanonicalMeshGeometry(positions, normals, uvs, indices);
@@ -525,9 +557,10 @@ export function createTorusKnotMeshGeometry(radius = 0.5, tube = 0.15, tubularSe
 // Builds a torus in the XY plane: a ring of `radius` (center to tube center) with a tube of
 // `tube` radius, divided into `radialSegments` around the ring and `tubularSegments` around the
 // tube. Normals point radially outward from the tube center.
+// Segment counts must be finite; fractional values are floored after clamping to 3.
 export function createTorusMeshGeometry(radius = 0.5, tube = 0.2, radialSegments = 24, tubularSegments = 48) {
-    const rSeg = Math.max(3, radialSegments);
-    const tSeg = Math.max(3, tubularSegments);
+    const rSeg = normalizeMeshCount(radialSegments, 3);
+    const tSeg = normalizeMeshCount(tubularSegments, 3);
     const positions = [];
     const normals = [];
     const uvs = [];
@@ -584,17 +617,81 @@ function addDisc(positions, normals, uvs, indices, segments, radius, y, directio
     for (let s = 0; s < segments; s++) {
         const a = ringStart + s;
         const b = ringStart + s + 1;
+        // Right-hand rule over the winding: for an up-facing disc the ring must be walked b-then-a to
+        // put (p1 - p0) x (p2 - p0) along +Y, which is the direction the authored normals already point.
         if (direction > 0) {
-            indices.push(center, a, b);
+            indices.push(center, b, a);
         }
         else {
-            indices.push(center, b, a);
+            indices.push(center, a, b);
         }
     }
 }
+function normalizeMeshCount(value, min, max = Number.POSITIVE_INFINITY) {
+    if (!Number.isFinite(value))
+        throw new RangeError('mesh segment and subdivision counts must be finite');
+    return Math.floor(Math.max(min, Math.min(value, max)));
+}
 // Interleaves separate position/normal/uv0 arrays into the canonical 12-float record, allocates
 // the MeshGeometry (indices auto-promote past 65k), then fills tangents from the UV gradient and
 // the cached local bounds. The single finalize path every builder funnels through.
+// Spherical UV for one direction on the unit sphere: u is longitude in 0..1, v is latitude with 0 at
+// the top. Shared by every builder that projects onto a sphere so the two call sites cannot drift.
+function sphericalU(nx, nz) {
+    return 0.5 + Math.atan2(nz, nx) / (Math.PI * 2);
+}
+function sphericalV(ny) {
+    return 0.5 - Math.asin(Math.max(-1, Math.min(1, ny))) / Math.PI;
+}
+// ★ THE SPHERICAL-UV BUILDERS EXPECT A REPEATING ADDRESSING MODE. Every builder that routes through
+// faceSphericalU — icosphere, and the polyhedra (dodecahedron, icosahedron, octahedron, tetrahedron)
+// via createPolyhedronMeshGeometry — emits u > 1 on the faces that cross the longitude seam. That is a
+// property of a wrapped parameterisation, not an accident: no assignment confined to 0..1 can describe
+// a face crossing the seam continuously. Sampled with a REPEAT wrap those values land where they should;
+// sampled with clamp-to-edge, the part past 1 collapses onto the edge texel. Flight's default sampler is
+// clamp-to-edge (texture/src/sampler.ts) and createTilingSampler is the repeating one, so a texture
+// applied to these solids wants the latter.
+//
+// The three corner longitudes of one face, with both spherical-mapping degeneracies resolved.
+//
+// SEAM: longitude wraps at u = 0/1, so a face with corners either side gets values like 0.99 and 0.01
+// and interpolates BACKWARDS across the whole texture — the entire map crushed into one triangle.
+// Lifting the low corners past 1 makes the face interpolate forward through the seam instead. A seam
+// face therefore carries u > 1 BY DESIGN: no parameterisation confined to 0..1 can express a face
+// crossing the seam continuously, and sampling wraps it.
+//
+// POLE: a vertex on the Y axis has zero horizontal radius, so atan2 gives it an arbitrary longitude
+// (0, hence u = 0.5) unrelated to the face it belongs to. It has no longitude of its own to preserve —
+// every meridian meets there — so it takes the average of its face-mates and the face stays narrow.
+//
+// Order matters: the face-mates are seam-corrected FIRST, then the pole averages the corrected values.
+// Averaging raw 0.99 and 0.01 would put the pole at 0.5, on the far side of the sphere from both.
+//
+// Emitting per-face vertices is what makes any of this possible — a shared vertex could only carry one
+// u — but it is not sufficient on its own: the values still have to be chosen, which is the half that
+// was missing.
+function faceSphericalU(a, b, c) {
+    const directions = [a, b, c];
+    const isPole = directions.map((d) => Math.hypot(d[0], d[2]) <= POLE_EPSILON);
+    const u = [sphericalU(a[0], a[2]), sphericalU(b[0], b[2]), sphericalU(c[0], c[2])];
+    const defined = [0, 1, 2].filter((i) => !isPole[i]);
+    if (defined.length > 0) {
+        const min = Math.min(...defined.map((i) => u[i]));
+        const max = Math.max(...defined.map((i) => u[i]));
+        if (max - min > 0.5) {
+            for (const i of defined)
+                if (u[i] < 0.5)
+                    u[i] += 1;
+        }
+        const mean = defined.reduce((sum, i) => sum + u[i], 0) / defined.length;
+        for (let i = 0; i < 3; i++)
+            if (isPole[i])
+                u[i] = mean;
+    }
+    return u;
+}
+// A direction within this of the Y axis has no meaningful longitude: every meridian meets at a pole.
+const POLE_EPSILON = 1e-6;
 function buildCanonicalMeshGeometry(positions, normals, uvs, indices) {
     const vertexCount = positions.length / 3;
     const vertices = new Float32Array(vertexCount * CANONICAL_FLOATS_PER_VERTEX);
@@ -617,92 +714,10 @@ function buildCanonicalMeshGeometry(positions, normals, uvs, indices) {
         layout: CANONICAL_VERTEX_LAYOUT,
         vertices: vertices,
     });
-    computeCanonicalMeshTangents(vertices, indexArray);
+    computeMeshGeometryTangents(geometry, geometry);
     refreshMeshGeometryBounds(geometry);
     return geometry;
 }
-// Primitive builders own their topology and already emit separate records at normal and UV seams.
-// Keeping this trusted-topology path local avoids pulling the general, topology-repairing tangent
-// authoring routine into applications that only create Flight primitives.
-function computeCanonicalMeshTangents(vertices, indices) {
-    const vertexCount = vertices.length / CANONICAL_FLOATS_PER_VERTEX;
-    const tangents = new Float32Array(vertexCount * 3);
-    const bitangents = new Float32Array(vertexCount * 3);
-    for (let element = 0; element + 2 < indices.length; element += 3) {
-        const i0 = indices[element];
-        const i1 = indices[element + 1];
-        const i2 = indices[element + 2];
-        const p0 = i0 * CANONICAL_FLOATS_PER_VERTEX;
-        const p1 = i1 * CANONICAL_FLOATS_PER_VERTEX;
-        const p2 = i2 * CANONICAL_FLOATS_PER_VERTEX;
-        const x1 = vertices[p1] - vertices[p0];
-        const y1 = vertices[p1 + 1] - vertices[p0 + 1];
-        const z1 = vertices[p1 + 2] - vertices[p0 + 2];
-        const x2 = vertices[p2] - vertices[p0];
-        const y2 = vertices[p2 + 1] - vertices[p0 + 1];
-        const z2 = vertices[p2 + 2] - vertices[p0 + 2];
-        const du1 = vertices[p1 + 10] - vertices[p0 + 10];
-        const dv1 = vertices[p1 + 11] - vertices[p0 + 11];
-        const du2 = vertices[p2 + 10] - vertices[p0 + 10];
-        const dv2 = vertices[p2 + 11] - vertices[p0 + 11];
-        const determinant = du1 * dv2 - du2 * dv1;
-        const reciprocal = determinant === 0 ? 0 : 1 / determinant;
-        const tx = (dv2 * x1 - dv1 * x2) * reciprocal;
-        const ty = (dv2 * y1 - dv1 * y2) * reciprocal;
-        const tz = (dv2 * z1 - dv1 * z2) * reciprocal;
-        const bx = (du1 * x2 - du2 * x1) * reciprocal;
-        const by = (du1 * y2 - du2 * y1) * reciprocal;
-        const bz = (du1 * z2 - du2 * z1) * reciprocal;
-        for (let corner = 0; corner < 3; corner++) {
-            const vertex = corner === 0 ? i0 : corner === 1 ? i1 : i2;
-            const tangent = vertex * 3;
-            tangents[tangent] += tx;
-            tangents[tangent + 1] += ty;
-            tangents[tangent + 2] += tz;
-            bitangents[tangent] += bx;
-            bitangents[tangent + 1] += by;
-            bitangents[tangent + 2] += bz;
-        }
-    }
-    for (let vertex = 0; vertex < vertexCount; vertex++) {
-        const base = vertex * CANONICAL_FLOATS_PER_VERTEX;
-        const tangent = vertex * 3;
-        const nx = vertices[base + 3];
-        const ny = vertices[base + 4];
-        const nz = vertices[base + 5];
-        const normalDot = nx * tangents[tangent] + ny * tangents[tangent + 1] + nz * tangents[tangent + 2];
-        let tx = tangents[tangent] - nx * normalDot;
-        let ty = tangents[tangent + 1] - ny * normalDot;
-        let tz = tangents[tangent + 2] - nz * normalDot;
-        let length = Math.hypot(tx, ty, tz);
-        if (length === 0) {
-            if (Math.abs(nx) < Math.abs(nz)) {
-                tx = 0;
-                ty = nz;
-                tz = -ny;
-            }
-            else {
-                tx = ny;
-                ty = -nx;
-                tz = 0;
-            }
-            length = Math.hypot(tx, ty, tz) || 1;
-        }
-        tx /= length;
-        ty /= length;
-        tz /= length;
-        vertices[base + 6] = tx;
-        vertices[base + 7] = ty;
-        vertices[base + 8] = tz;
-        vertices[base + 9] =
-            (ny * tz - nz * ty) * bitangents[tangent] +
-                (nz * tx - nx * tz) * bitangents[tangent + 1] +
-                (nx * ty - ny * tx) * bitangents[tangent + 2] <
-                0
-                ? -1
-                : 1;
-    }
-}
 const CANONICAL_FLOATS_PER_VERTEX = 12;
 // The canonical interleaved PBR vertex layout shared by every builder: position + normal +
 // tangent(w = handedness) + uv0, stride 48 bytes.
@@ -813,11 +828,14 @@ const DODECAHEDRON_VERTS = [
     [_phi, 0, -_d],
     [_phi, 0, _d],
 ];
+// Nine of these faces were wound the opposite way from the other twenty-seven, which put their
+// geometric face normals against the outward vertex normals the builder authors. Only those nine
+// are reversed; the winding here is per-face data, not a convention the whole table shares.
 const DODECAHEDRON_FACES = [
     [3, 11, 7],
     [3, 7, 15],
     [3, 15, 13],
-    [7, 19, 11],
+    [7, 11, 19],
     [7, 11, 9],
     [7, 9, 19],
     [15, 7, 19],
@@ -832,21 +850,21 @@ const DODECAHEDRON_FACES = [
     [11, 17, 1],
     [11, 1, 9],
     [9, 1, 5],
-    [5, 1, 17],
+    [5, 17, 1],
     [5, 17, 4],
-    [5, 4, 14],
-    [9, 5, 14],
-    [9, 14, 12],
-    [9, 12, 0],
+    [5, 14, 4],
+    [9, 14, 5],
+    [9, 12, 14],
+    [9, 0, 12],
     [1, 0, 12],
     [1, 12, 4],
-    [1, 4, 17],
+    [1, 17, 4],
     [6, 18, 8],
     [6, 8, 10],
     [6, 10, 2],
     [18, 19, 8],
-    [19, 7, 8],
-    [7, 15, 8],
+    [19, 8, 7],
+    [7, 8, 15],
     [2, 10, 16],
     [10, 8, 0],
     [0, 8, 12],