@carbonenginejs/runtime 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/resource/geometry/TriGeometryRes.js

@@ -10,13 +10,25 @@ import { CjsResource } from '../CjsResource.js';
 import { Tr2RaycastGeometryRes } from './Tr2RaycastGeometryRes.js';
 import { assertResourcePayloadObject, assertResourcePayloadArray, resourcePayloadError, resourceBoundaryError } from '../resourceBoundary.js';
 
-/**
- * Resource record that owns geometry payload facts (meshes, optional
- * skeletons and animations) and LOD-force metadata, while engine packages
- * decide device buffers, vertex declarations, and draw-time state.
- *
- * Geometry inspection composes the generic math supplied by the runtime global layer
- * with resource-specific payload traversal.
+// Scratch edges for the picking cross product. Picking is synchronous and the
+// result is consumed before the next hit, so one pair is enough.
+//
+// PLAIN arrays, not `vec3.create()`, because the destination is one: the hit
+// record's `unnormalizedNormal` is `[ 0, 0, 0 ]`, so the products stay in double
+// precision the whole way. Rounding the two edges to a math array's element type
+// first perturbs the result on all but 2.5% of triangles, and by as much as 1.8%
+// relatively where the cross product cancels - which is exactly the thin sliver
+// a picking ray is most likely to graze.
+const edgeAB = [0, 0, 0];
+const edgeAC = [0, 0, 0];
+
+/**
+ * Resource record that owns geometry payload facts (meshes, optional
+ * skeletons and animations) and LOD-force metadata, while engine packages
+ * decide device buffers, vertex declarations, and draw-time state.
+ *
+ * Geometry inspection composes the generic math supplied by the runtime global layer
+ * with resource-specific payload traversal.
  */
 class TriGeometryRes extends CjsResource {
   forceLod = false;
@@ -36,12 +48,12 @@ class TriGeometryRes extends CjsResource {
     });
   }
 
-  /**
-   * Attach a plain geometry payload.
-   *
-   * @param {object|null} payload
-   * @param {object|null} options
-   * @returns {TriGeometryRes}
+  /**
+   * Attach a plain geometry payload.
+   *
+   * @param {object|null} payload
+   * @param {object|null} options
+   * @returns {TriGeometryRes}
    */
   SetPayload(payload = null, options = null) {
     if (this.#raycastUsers !== 0) {
@@ -65,38 +77,38 @@ class TriGeometryRes extends CjsResource {
     return this;
   }
 
-  /**
-   * Get mesh count from the CPU geometry payload.
-   *
-   * @returns {number}
+  /**
+   * Get mesh count from the CPU geometry payload.
+   *
+   * @returns {number}
    */
   GetMeshCount() {
     return this.GetPayload()?.meshes?.length || 0;
   }
 
-  /**
-   * Get animation count from the CPU geometry payload.
-   *
-   * @returns {number}
+  /**
+   * Get animation count from the CPU geometry payload.
+   *
+   * @returns {number}
    */
   GetAnimationCount() {
     return this.GetPayload()?.animations?.length || 0;
   }
 
-  /**
-   * Get skeleton count from the CPU geometry payload.
-   *
-   * @returns {number}
+  /**
+   * Get skeleton count from the CPU geometry payload.
+   *
+   * @returns {number}
    */
   GetSkeletonCount() {
     return this.GetPayload()?.skeletons?.length || 0;
   }
 
-  /**
-   * Get one resource-owned skeleton from the CPU geometry payload.
-   *
-   * @param {number} skeletonIndex
-   * @returns {*}
+  /**
+   * Get one resource-owned skeleton from the CPU geometry payload.
+   *
+   * @param {number} skeletonIndex
+   * @returns {*}
    */
   GetSkeletonData(skeletonIndex = 0) {
     const index = Number(skeletonIndex);
@@ -106,11 +118,11 @@ class TriGeometryRes extends CjsResource {
     return this.GetPayload()?.skeletons?.[index] || null;
   }
 
-  /**
-   * Get mesh area count from a CPU geometry payload mesh.
-   *
-   * @param {number} meshIndex
-   * @returns {number}
+  /**
+   * Get mesh area count from a CPU geometry payload mesh.
+   *
+   * @param {number} meshIndex
+   * @returns {number}
    */
   GetMeshAreaCount(meshIndex = 0) {
     const mesh = this.GetPayload()?.meshes?.[meshIndex];
@@ -138,13 +150,13 @@ class TriGeometryRes extends CjsResource {
   // comments explicitly. forceLod pins the index instead, clamped to the last
   // LOD.
 
-  /**
-   * The LOD index this mesh should be drawn at for a screen size, or -1 when the
-   * mesh does not exist.
-   *
-   * @param {number} meshIndex
-   * @param {number} screenSize
-   * @returns {number}
+  /**
+   * The LOD index this mesh should be drawn at for a screen size, or -1 when the
+   * mesh does not exist.
+   *
+   * @param {number} meshIndex
+   * @param {number} screenSize
+   * @returns {number}
    */
   GetLodIndexForScreenSize(meshIndex = 0, screenSize = Infinity) {
     const mesh = this.GetPayload()?.meshes?.[meshIndex];
@@ -170,25 +182,25 @@ class TriGeometryRes extends CjsResource {
   // mesh with an EMPTY lod list reads out of bounds there; this port returns
   // null (docs/research/carbon-known-defects.md).
 
-  /**
-   * The LOD data this mesh should be drawn at for a screen size, or null when
-   * the mesh has no LODs.
-   *
-   * @param {number} meshIndex
-   * @param {number} screenSize
-   * @returns {object|null}
+  /**
+   * The LOD data this mesh should be drawn at for a screen size, or null when
+   * the mesh has no LODs.
+   *
+   * @param {number} meshIndex
+   * @param {number} screenSize
+   * @returns {object|null}
    */
   GetMeshLod(meshIndex = 0, screenSize = Infinity) {
     return this.GetMeshLodByIndex(meshIndex, this.GetLodIndexForScreenSize(meshIndex, screenSize));
   }
 
-  /**
-   * The LOD data at an explicit index, or null when the mesh or index does not
-   * exist (Carbon TriGeometryRes.cpp:281-292).
-   *
-   * @param {number} meshIndex
-   * @param {number} lodIndex
-   * @returns {object|null}
+  /**
+   * The LOD data at an explicit index, or null when the mesh or index does not
+   * exist (Carbon TriGeometryRes.cpp:281-292).
+   *
+   * @param {number} meshIndex
+   * @param {number} lodIndex
+   * @returns {object|null}
    */
   GetMeshLodByIndex(meshIndex = 0, lodIndex = 0) {
     const mesh = this.GetPayload()?.meshes?.[meshIndex];
@@ -199,35 +211,35 @@ class TriGeometryRes extends CjsResource {
     return lodIndex === 0 && mesh.areas ? mesh : null;
   }
 
-  /**
-   * Get mesh name from a CPU geometry payload.
-   *
-   * @param {number} meshIndex
-   * @returns {string}
+  /**
+   * Get mesh name from a CPU geometry payload.
+   *
+   * @param {number} meshIndex
+   * @returns {string}
    */
   GetMeshName(meshIndex = 0) {
     return this.GetPayload()?.meshes?.[meshIndex]?.name || "";
   }
 
-  /**
-   * Get mesh area name from a CPU geometry payload.
-   *
-   * @param {number} meshIndex
-   * @param {number} areaIndex
-   * @returns {string}
+  /**
+   * Get mesh area name from a CPU geometry payload.
+   *
+   * @param {number} meshIndex
+   * @param {number} areaIndex
+   * @returns {string}
    */
   GetMeshAreaName(meshIndex = 0, areaIndex = 0) {
     return this.GetPayload()?.meshes?.[meshIndex]?.areas?.[areaIndex]?.name || "";
   }
 
-  /**
-   * Get area bounding box from geometry payload data.
-   *
-   * @param {number} meshIndex
-   * @param {number} areaIndex
-   * @param {ArrayLike<number>|null} outMin
-   * @param {ArrayLike<number>|null} outMax
-   * @returns {*|boolean}
+  /**
+   * Get area bounding box from geometry payload data.
+   *
+   * @param {number} meshIndex
+   * @param {number} areaIndex
+   * @param {ArrayLike<number>|null} outMin
+   * @param {ArrayLike<number>|null} outMax
+   * @returns {*|boolean}
    */
   GetAreaBoundingBox(meshIndex = 0, areaIndex = 0, outMin = null, outMax = null) {
     const area = TriGeometryRes.getMeshAreas(this.GetPayload()?.meshes?.[meshIndex])?.[areaIndex];
@@ -235,12 +247,12 @@ class TriGeometryRes extends CjsResource {
     return TriGeometryRes.copyBounds(bounds, outMin, outMax);
   }
 
-  /**
-   * Get mesh bounding box from geometry payload data.
-   * @param {number} meshIndex
-   * @param {ArrayLike<number>|null} outMin
-   * @param {ArrayLike<number>|null} outMax
-   * @returns {*|boolean}
+  /**
+   * Get mesh bounding box from geometry payload data.
+   * @param {number} meshIndex
+   * @param {ArrayLike<number>|null} outMin
+   * @param {ArrayLike<number>|null} outMax
+   * @returns {*|boolean}
    */
   GetBoundingBox(meshIndex = 0, outMin = null, outMax = null) {
     const payload = this.GetPayload();
@@ -248,11 +260,11 @@ class TriGeometryRes extends CjsResource {
     return TriGeometryRes.copyBounds(bounds, outMin, outMax);
   }
 
-  /**
-   * Get mesh bounding sphere from geometry payload data.
-   * @param {number} meshIndex
-   * @param {ArrayLike<number>|null} out
-   * @returns {*|boolean}
+  /**
+   * Get mesh bounding sphere from geometry payload data.
+   * @param {number} meshIndex
+   * @param {ArrayLike<number>|null} out
+   * @returns {*|boolean}
    */
   GetBoundingSphere(meshIndex = 0, out = null) {
     const payload = this.GetPayload();
@@ -263,15 +275,15 @@ class TriGeometryRes extends CjsResource {
     return true;
   }
 
-  /**
-   * Calculate a transformed bounding box from canonical CPU vertex data.
-   *
-   * Carbon stores the same matrix bytes as gl-matrix; transforming one point
-   * therefore uses the ordinary column-vector index layout.
-   *
-   * @param {number} meshIndex
-   * @param {ArrayLike<number>} transform
-   * @returns {{min: number[], max: number[]}|null}
+  /**
+   * Calculate a transformed bounding box from canonical CPU vertex data.
+   *
+   * Carbon stores the same matrix bytes as gl-matrix; transforming one point
+   * therefore uses the ordinary column-vector index layout.
+   *
+   * @param {number} meshIndex
+   * @param {ArrayLike<number>} transform
+   * @returns {{min: number[], max: number[]}|null}
    */
   CalculateBoundingBoxFromTransform(meshIndex = 0, transform = null) {
     if (!transform || transform.length < 16) {
@@ -300,10 +312,10 @@ class TriGeometryRes extends CjsResource {
     }
   }
 
-  /**
-   * Recalculate bounding sphere data from canonical CPU vertex positions.
-   *
-   * @returns {boolean}
+  /**
+   * Recalculate bounding sphere data from canonical CPU vertex positions.
+   *
+   * @returns {boolean}
    */
   RecalculateBoundingSphere() {
     let updated = false;
@@ -322,34 +334,34 @@ class TriGeometryRes extends CjsResource {
     }
   }
 
-  /**
-   * Reloading belongs to the resource manager because it owns source and
-   * canonical replacement policy.
-   *
-   * @throws {Error}
+  /**
+   * Reloading belongs to the resource manager because it owns source and
+   * canonical replacement policy.
+   *
+   * @throws {Error}
    */
   Reload() {
     throw resourceBoundaryError("TriGeometryRes", "Reload", "Request a reload through CjsResMan so source reads and canonical replacement remain manager-owned.");
   }
 
-  /**
-   * Intersect a ray with canonical CPU triangle data.
-   *
-   * @param {ArrayLike<number>} position
-   * @param {ArrayLike<number>} direction
-   * @returns {object}
+  /**
+   * Intersect a ray with canonical CPU triangle data.
+   *
+   * @param {ArrayLike<number>} position
+   * @param {ArrayLike<number>} direction
+   * @returns {object}
    */
   GetIntersectionPointNormalBone(position, direction) {
     return TriGeometryRes.intersectGeometry(this.RequireIntersectionMeshes(), position, direction, -1);
   }
 
-  /**
-   * Intersect a ray with one area index across canonical CPU meshes.
-   *
-   * @param {ArrayLike<number>} position
-   * @param {ArrayLike<number>} direction
-   * @param {number} areaIndex
-   * @returns {object}
+  /**
+   * Intersect a ray with one area index across canonical CPU meshes.
+   *
+   * @param {ArrayLike<number>} position
+   * @param {ArrayLike<number>} direction
+   * @param {number} areaIndex
+   * @returns {object}
    */
   GetAreaIntersectionPointNormalBone(position, direction, areaIndex = -1) {
     if (!Number.isInteger(areaIndex) || areaIndex < -1) {
@@ -425,27 +437,27 @@ class TriGeometryRes extends CjsResource {
     return true;
   }
 
-  /**
-   * The CPU triangle data an intersection query needs, or a loud failure.
-   *
-   * A ray query used to read `GetPayload()?.meshes`, and `intersectGeometry`
-   * loops over `meshes?.length || 0`. So an absent payload produced a clean
-   * MISS: `hit: false`, no error, indistinguishable from the ray genuinely
-   * passing the object by. Picking would appear to work and simply stop
-   * hitting things, and the symptom reads as a maths bug rather than a
-   * residency one.
-   *
-   * Carbon never has to answer this, because it holds the loaded file for the
-   * resource's lifetime and its CPU data is always resident. Ours is
-   * releasable, so the unavailable case is real and must be named.
-   *
-   * Throwing is the interim answer, not the final one: once accuracy tiers
-   * exist a query degrades to bounds or sphere and reports which produced it.
-   * What it must never do again is report absence as a miss. See
-   * `/docs/contracts/cpu-geometry-residency.md`.
-   *
-   * @returns {Array<*>} Canonical CPU meshes.
-   * @throws {Error} When the CPU geometry is not resident.
+  /**
+   * The CPU triangle data an intersection query needs, or a loud failure.
+   *
+   * A ray query used to read `GetPayload()?.meshes`, and `intersectGeometry`
+   * loops over `meshes?.length || 0`. So an absent payload produced a clean
+   * MISS: `hit: false`, no error, indistinguishable from the ray genuinely
+   * passing the object by. Picking would appear to work and simply stop
+   * hitting things, and the symptom reads as a maths bug rather than a
+   * residency one.
+   *
+   * Carbon never has to answer this, because it holds the loaded file for the
+   * resource's lifetime and its CPU data is always resident. Ours is
+   * releasable, so the unavailable case is real and must be named.
+   *
+   * Throwing is the interim answer, not the final one: once accuracy tiers
+   * exist a query degrades to bounds or sphere and reports which produced it.
+   * What it must never do again is report absence as a miss. See
+   * `/docs/contracts/cpu-geometry-residency.md`.
+   *
+   * @returns {Array<*>} Canonical CPU meshes.
+   * @throws {Error} When the CPU geometry is not resident.
    */
   RequireIntersectionMeshes() {
     const meshes = this.GetPayload()?.meshes;
@@ -455,11 +467,11 @@ class TriGeometryRes extends CjsResource {
     return meshes;
   }
 
-  /**
-   * Get vertex element descriptors for a mesh.
-   *
-   * @param {number} meshIndex
-   * @returns {Array<*>}
+  /**
+   * Get vertex element descriptors for a mesh.
+   *
+   * @param {number} meshIndex
+   * @returns {Array<*>}
    */
   GetMeshVertexElements(meshIndex = 0) {
     // The CMF reader emits the element list as `decl`, matching the CMF struct
@@ -470,10 +482,10 @@ class TriGeometryRes extends CjsResource {
     return mesh?.decl || mesh?.vertexElements || [];
   }
 
-  /**
-   * Saving belongs to the selected geometry format writer and destination.
-   *
-   * @throws {Error}
+  /**
+   * Saving belongs to the selected geometry format writer and destination.
+   *
+   * @throws {Error}
    */
   SaveMesh() {
     throw resourceBoundaryError("TriGeometryRes", "SaveMesh", "Use a geometry format writer with the resource payload and a caller-owned destination.");
@@ -486,15 +498,15 @@ class TriGeometryRes extends CjsResource {
   // multiply by three: the *3 belongs to the caller, so triangles-only is a
   // property of the mesh draw path rather than of the geometry layer.
 
-  /**
-   * The summed primitive count over `count` areas of a LOD starting at `index`,
-   * with the run clamped to the area list as Carbon clamps it; zero when the
-   * index is out of range, which callers treat as "emit no draw".
-   *
-   * @param {object|null} lod
-   * @param {number} index
-   * @param {number} count
-   * @returns {number}
+  /**
+   * The summed primitive count over `count` areas of a LOD starting at `index`,
+   * with the run clamped to the area list as Carbon clamps it; zero when the
+   * index is out of range, which callers treat as "emit no draw".
+   *
+   * @param {object|null} lod
+   * @param {number} index
+   * @param {number} count
+   * @returns {number}
    */
   static getPrimitiveCount(lod, index, count) {
     const areas = lod?.areas ?? null;
@@ -524,22 +536,22 @@ class TriGeometryRes extends CjsResource {
   // accepted above: the name is the producer's. A payload built by a reader
   // that already speaks Carbon's vocabulary is passed through unconverted.
 
-  /**
-   * One area's primitive count, under whichever name the producer used.
-   *
-   * @param {object|null} area
-   * @returns {number} Triangle count; zero when the area is absent or unnamed.
+  /**
+   * One area's primitive count, under whichever name the producer used.
+   *
+   * @param {object|null} area
+   * @returns {number} Triangle count; zero when the area is absent or unnamed.
    */
   static getAreaPrimitiveCount(area) {
     return area?.primitiveCount ?? area?.elementCount ?? 0;
   }
 
-  /**
-   * One area's first INDEX, converting a CMF first-triangle when that is what
-   * the producer wrote.
-   *
-   * @param {object|null} area
-   * @returns {number} Index offset into the LOD's index buffer.
+  /**
+   * One area's first INDEX, converting a CMF first-triangle when that is what
+   * the producer wrote.
+   *
+   * @param {object|null} area
+   * @returns {number} Index offset into the LOD's index buffer.
    */
   static getAreaFirstIndex(area) {
     if (area?.firstIndex !== undefined) return area.firstIndex;
@@ -547,17 +559,17 @@ class TriGeometryRes extends CjsResource {
     return 0;
   }
 
-  /**
-   * A LOD's total primitive count.
-   *
-   * Carbon takes this from the index stream rather than from the areas
-   * (`GetStreamElementCount( cmfLod.ib ) / 3`, TriGeometryRes.cpp:890), because
-   * an area list need not cover every triangle. Falling back to the area sum
-   * keeps a payload that carries areas but no index-stream extent usable, and
-   * only the reversed draw path reads this at all.
-   *
-   * @param {object|null} lod
-   * @returns {number}
+  /**
+   * A LOD's total primitive count.
+   *
+   * Carbon takes this from the index stream rather than from the areas
+   * (`GetStreamElementCount( cmfLod.ib ) / 3`, TriGeometryRes.cpp:890), because
+   * an area list need not cover every triangle. Falling back to the area sum
+   * keeps a payload that carries areas but no index-stream extent usable, and
+   * only the reversed draw path reads this at all.
+   *
+   * @param {object|null} lod
+   * @returns {number}
    */
   static getLodPrimitiveCount(lod) {
     if (lod?.primitiveCount !== undefined) return lod.primitiveCount;
@@ -567,21 +579,21 @@ class TriGeometryRes extends CjsResource {
     return TriGeometryRes.getPrimitiveCount(lod, 0, lod?.areas?.length ?? 0);
   }
 
-  /**
-   * Gets the canonical area list from a mesh or its first LOD.
-   *
-   * @param {object|null} mesh
-   * @returns {Array<*>|null}
+  /**
+   * Gets the canonical area list from a mesh or its first LOD.
+   *
+   * @param {object|null} mesh
+   * @returns {Array<*>|null}
   */
   static getMeshAreas(mesh) {
     return mesh?.areas || mesh?.lods?.[0]?.areas || null;
   }
 
-  /**
-   * Gets canonical bounds from a geometry payload object.
-   *
-   * @param {object|null} value
-   * @returns {{min: ArrayLike<number>, max: ArrayLike<number>}|null}
+  /**
+   * Gets canonical bounds from a geometry payload object.
+   *
+   * @param {object|null} value
+   * @returns {{min: ArrayLike<number>, max: ArrayLike<number>}|null}
   */
   static getBounds(value) {
     if (!value || typeof value !== "object") return null;
@@ -595,24 +607,24 @@ class TriGeometryRes extends CjsResource {
     return null;
   }
 
-  /**
-   * Gets the canonical bounding sphere from a geometry payload object.
-   *
-   * @param {object|null} value
-   * @returns {ArrayLike<number>|null}
+  /**
+   * Gets the canonical bounding sphere from a geometry payload object.
+   *
+   * @param {object|null} value
+   * @returns {ArrayLike<number>|null}
   */
   static getSphere(value) {
     if (!value || typeof value !== "object") return null;
     return value.sphere || value.boundingSphere || null;
   }
 
-  /**
-   * Copies bounds into caller-owned outputs, or returns the source object.
-   *
-   * @param {{min: ArrayLike<number>, max: ArrayLike<number>}|null} bounds
-   * @param {ArrayLike<number>|null} outMin
-   * @param {ArrayLike<number>|null} outMax
-   * @returns {*|boolean}
+  /**
+   * Copies bounds into caller-owned outputs, or returns the source object.
+   *
+   * @param {{min: ArrayLike<number>, max: ArrayLike<number>}|null} bounds
+   * @param {ArrayLike<number>|null} outMin
+   * @param {ArrayLike<number>|null} outMax
+   * @returns {*|boolean}
   */
   static copyBounds(bounds, outMin, outMax) {
     if (!outMin && !outMax) return bounds;
@@ -622,34 +634,34 @@ class TriGeometryRes extends CjsResource {
     return true;
   }
 
-  /**
-   * Gets canonical positions from a mesh or its first LOD.
-   *
-   * @param {object|null} mesh
-   * @returns {ArrayLike<number>|Array<ArrayLike<number>>|null}
+  /**
+   * Gets canonical positions from a mesh or its first LOD.
+   *
+   * @param {object|null} mesh
+   * @returns {ArrayLike<number>|Array<ArrayLike<number>>|null}
   */
   static getMeshPositions(mesh) {
     return mesh?.vertex?.position || mesh?.positions || mesh?.lods?.[0]?.vertex?.position || mesh?.lods?.[0]?.positions || null;
   }
 
-  /**
-   * Gets the number of vertices represented by flat or nested positions.
-   *
-   * @param {ArrayLike<number>|Array<ArrayLike<number>>|null} positions
-   * @returns {number}
+  /**
+   * Gets the number of vertices represented by flat or nested positions.
+   *
+   * @param {ArrayLike<number>|Array<ArrayLike<number>>|null} positions
+   * @returns {number}
   */
   static getPositionCount(positions) {
     if (!positions) return 0;
     return typeof positions[0] === "number" ? Math.floor(positions.length / 3) : positions.length;
   }
 
-  /**
-   * Calculates bounds from canonical positions using caller-owned scratch.
-   *
-   * @param {ArrayLike<number>} out
-   * @param {ArrayLike<number>|Array<ArrayLike<number>>|null} positions
-   * @param {ArrayLike<number>} point
-   * @returns {boolean}
+  /**
+   * Calculates bounds from canonical positions using caller-owned scratch.
+   *
+   * @param {ArrayLike<number>} out
+   * @param {ArrayLike<number>|Array<ArrayLike<number>>|null} positions
+   * @param {ArrayLike<number>} point
+   * @returns {boolean}
   */
   static setBoundsFromPositions(out, positions, point) {
     const count = this.getPositionCount(positions);
@@ -673,13 +685,13 @@ class TriGeometryRes extends CjsResource {
     return found;
   }
 
-  /**
-   * Calculates a bounding sphere from positions using caller-owned scratch.
-   *
-   * @param {ArrayLike<number>} out
-   * @param {ArrayLike<number>|Array<ArrayLike<number>>|null} positions
-   * @param {ArrayLike<number>} point
-   * @returns {boolean}
+  /**
+   * Calculates a bounding sphere from positions using caller-owned scratch.
+   *
+   * @param {ArrayLike<number>} out
+   * @param {ArrayLike<number>|Array<ArrayLike<number>>|null} positions
+   * @param {ArrayLike<number>} point
+   * @returns {boolean}
   */
   static setSphereFromPositions(out, positions, point) {
     const count = this.getPositionCount(positions);
@@ -716,13 +728,13 @@ class TriGeometryRes extends CjsResource {
     return true;
   }
 
-  /**
-   * Calculates a mesh sphere from positions or existing bounds.
-   *
-   * @param {ArrayLike<number>} out
-   * @param {object} mesh
-   * @param {ArrayLike<number>} point
-   * @returns {boolean}
+  /**
+   * Calculates a mesh sphere from positions or existing bounds.
+   *
+   * @param {ArrayLike<number>} out
+   * @param {object} mesh
+   * @param {ArrayLike<number>} point
+   * @returns {boolean}
   */
   static calculateMeshSphere(out, mesh, point) {
     if (this.setSphereFromPositions(out, this.getMeshPositions(mesh), point)) return true;
@@ -732,12 +744,12 @@ class TriGeometryRes extends CjsResource {
     return true;
   }
 
-  /**
-   * Stores a calculated sphere in the mesh's canonical sphere fields.
-   *
-   * @param {object} mesh
-   * @param {ArrayLike<number>} sphere
-   * @returns {void}
+  /**
+   * Stores a calculated sphere in the mesh's canonical sphere fields.
+   *
+   * @param {object} mesh
+   * @param {ArrayLike<number>} sphere
+   * @returns {void}
   */
   static setMeshSphere(mesh, sphere) {
     if (mesh.sphere && typeof mesh.sphere.set === "function") mesh.sphere.set(sphere);else mesh.sphere = [...sphere];
@@ -748,14 +760,14 @@ class TriGeometryRes extends CjsResource {
     }
   }
 
-  /**
-   * Intersects a ray with canonical CPU geometry.
-   *
-   * @param {Array<object>|null} meshes
-   * @param {ArrayLike<number>} position
-   * @param {ArrayLike<number>} direction
-   * @param {number} areaIndex
-   * @returns {object}
+  /**
+   * Intersects a ray with canonical CPU geometry.
+   *
+   * @param {Array<object>|null} meshes
+   * @param {ArrayLike<number>} position
+   * @param {ArrayLike<number>} direction
+   * @param {number} areaIndex
+   * @returns {object}
   */
   static intersectGeometry(meshes, position, direction, areaIndex) {
     this.validateRayVector(position, "position");
@@ -813,12 +825,12 @@ class TriGeometryRes extends CjsResource {
     }
   }
 
-  /**
-   * Validates a caller-provided ray vector.
-   *
-   * @param {ArrayLike<number>} value
-   * @param {string} name
-   * @returns {void}
+  /**
+   * Validates a caller-provided ray vector.
+   *
+   * @param {ArrayLike<number>} value
+   * @param {string} name
+   * @returns {void}
   */
   static validateRayVector(value, name) {
     if (!value || value.length < 3 || !Number.isFinite(value[0]) || !Number.isFinite(value[1]) || !Number.isFinite(value[2])) {
@@ -826,23 +838,23 @@ class TriGeometryRes extends CjsResource {
     }
   }
 
-  /**
-   * Intersects a ray with one flat face list.
-   *
-   * @param {object|null} nearest
-   * @param {ArrayLike<number>|null} faces
-   * @param {number} areaIndex
-   * @param {object} mesh
-   * @param {number} meshIndex
-   * @param {ArrayLike<number>|Array<ArrayLike<number>>} positions
-   * @param {ArrayLike<number>} rayOrigin
-   * @param {ArrayLike<number>} ray
-   * @param {ArrayLike<number>} point
-   * @param {ArrayLike<number>} vertexA
-   * @param {ArrayLike<number>} vertexB
-   * @param {ArrayLike<number>} vertexC
-   * @param {ArrayLike<number>} normal
-   * @returns {object|null}
+  /**
+   * Intersects a ray with one flat face list.
+   *
+   * @param {object|null} nearest
+   * @param {ArrayLike<number>|null} faces
+   * @param {number} areaIndex
+   * @param {object} mesh
+   * @param {number} meshIndex
+   * @param {ArrayLike<number>|Array<ArrayLike<number>>} positions
+   * @param {ArrayLike<number>} rayOrigin
+   * @param {ArrayLike<number>} ray
+   * @param {ArrayLike<number>} point
+   * @param {ArrayLike<number>} vertexA
+   * @param {ArrayLike<number>} vertexB
+   * @param {ArrayLike<number>} vertexC
+   * @param {ArrayLike<number>} normal
+   * @returns {object|null}
   */
   static intersectFaces(nearest, faces, areaIndex, mesh, meshIndex, positions, rayOrigin, ray, point, vertexA, vertexB, vertexC, normal) {
     const count = faces?.length ?? this.getPositionCount(positions);
@@ -871,9 +883,12 @@ class TriGeometryRes extends CjsResource {
       }
       nearest.boneIndex = this.getMeshBoneIndex(mesh, vertexIndexA);
       vec3.copy(nearest.position, point);
-      nearest.unnormalizedNormal[0] = (vertexB[1] - vertexA[1]) * (vertexC[2] - vertexA[2]) - (vertexB[2] - vertexA[2]) * (vertexC[1] - vertexA[1]);
-      nearest.unnormalizedNormal[1] = (vertexB[2] - vertexA[2]) * (vertexC[0] - vertexA[0]) - (vertexB[0] - vertexA[0]) * (vertexC[2] - vertexA[2]);
-      nearest.unnormalizedNormal[2] = (vertexB[0] - vertexA[0]) * (vertexC[1] - vertexA[1]) - (vertexB[1] - vertexA[1]) * (vertexC[0] - vertexA[0]);
+      // (B - A) x (C - A). This was written out in full one line above a
+      // `triangleNormalTo` call that computes the NORMALISED version of the same
+      // vector, so the winding convention lived in two places at once.
+      vec3.subtract(edgeAB, vertexB, vertexA);
+      vec3.subtract(edgeAC, vertexC, vertexA);
+      vec3.cross(nearest.unnormalizedNormal, edgeAB, edgeAC);
       triangleNormalTo(normal, vertexA, vertexB, vertexC);
       vec3.copy(nearest.normal, normal);
       nearest.distance = distance;
@@ -883,13 +898,13 @@ class TriGeometryRes extends CjsResource {
     return nearest;
   }
 
-  /**
-   * Copies one flat or nested position into caller-owned output.
-   *
-   * @param {ArrayLike<number>} out
-   * @param {ArrayLike<number>|Array<ArrayLike<number>>} positions
-   * @param {number} index
-   * @returns {boolean}
+  /**
+   * Copies one flat or nested position into caller-owned output.
+   *
+   * @param {ArrayLike<number>} out
+   * @param {ArrayLike<number>|Array<ArrayLike<number>>} positions
+   * @param {number} index
+   * @returns {boolean}
   */
   static copyPosition(out, positions, index) {
     if (!Number.isInteger(index) || index < 0) return false;
@@ -909,12 +924,12 @@ class TriGeometryRes extends CjsResource {
     return true;
   }
 
-  /**
-   * Gets the first blend index for a mesh vertex.
-   *
-   * @param {object} mesh
-   * @param {number} vertexIndex
-   * @returns {number}
+  /**
+   * Gets the first blend index for a mesh vertex.
+   *
+   * @param {object} mesh
+   * @param {number} vertexIndex
+   * @returns {number}
   */
   static getMeshBoneIndex(mesh, vertexIndex) {
     const indices = mesh?.vertex?.blendIndices || mesh?.blendIndices;