@woosh/meep-engine 2.168.0 → 2.169.0

package/src/core/geom/2d/polygon/polygon2_triangulation_deviation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Relative area error of a triangulation produced by {@link polygon2_triangulate}
+ * for the same `points` / `contour_ends` / `contour_count`.
+ *
+ * `0` means the triangles cover exactly the polygon's area. A positive value is
+ * the fraction of the polygon that is missing (or, for a self-intersecting input,
+ * double-covered). This is the cheap, total-order way to ask "did that work?"
+ * without pairwise triangle comparisons -- it is the primary invariant the specs
+ * assert, and it is available to callers that need to validate untrusted input at
+ * runtime.
+ *
+ * A degenerate polygon (zero total area) reports `0` when the triangulation is
+ * also empty, and `Infinity` when it is not -- there is no meaningful ratio to a
+ * zero reference, and silently reporting `0` would call a wrong answer perfect.
+ *
+ * @param {ArrayLike<number>} result triangle indices as written by {@link polygon2_triangulate}
+ * @param {number} result_offset first index of the triangulation within `result`
+ * @param {number} triangle_count as returned by {@link polygon2_triangulate}
+ * @param {ArrayLike<number>} points flat (x, y) pairs, stride 2
+ * @param {ArrayLike<number>} contour_ends exclusive end vertex index per contour
+ * @param {number} contour_count
+ * @returns {number} relative area error, `0` for an exact triangulation
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function polygon2_triangulation_deviation(result: ArrayLike<number>, result_offset: number, triangle_count: number, points: ArrayLike<number>, contour_ends: ArrayLike<number>, contour_count: number): number;
+//# sourceMappingURL=polygon2_triangulation_deviation.d.ts.map

package/src/core/geom/2d/polygon/polygon2_triangulation_deviation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon2_triangulation_deviation.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/polygon/polygon2_triangulation_deviation.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,yDAXW,UAAU,MAAM,CAAC,iBACjB,MAAM,kBACN,MAAM,UACN,UAAU,MAAM,CAAC,gBACjB,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,MAAM,CAoDlB"}

package/src/core/geom/2d/polygon/polygon2_triangulation_deviation.js

@@ -0,0 +1,77 @@
+import { tri2_signed_area } from "../triangle/tri2_signed_area.js";
+import { polygon2_signed_area } from "./polygon2_signed_area.js";
+
+/**
+ * Relative area error of a triangulation produced by {@link polygon2_triangulate}
+ * for the same `points` / `contour_ends` / `contour_count`.
+ *
+ * `0` means the triangles cover exactly the polygon's area. A positive value is
+ * the fraction of the polygon that is missing (or, for a self-intersecting input,
+ * double-covered). This is the cheap, total-order way to ask "did that work?"
+ * without pairwise triangle comparisons -- it is the primary invariant the specs
+ * assert, and it is available to callers that need to validate untrusted input at
+ * runtime.
+ *
+ * A degenerate polygon (zero total area) reports `0` when the triangulation is
+ * also empty, and `Infinity` when it is not -- there is no meaningful ratio to a
+ * zero reference, and silently reporting `0` would call a wrong answer perfect.
+ *
+ * @param {ArrayLike<number>} result triangle indices as written by {@link polygon2_triangulate}
+ * @param {number} result_offset first index of the triangulation within `result`
+ * @param {number} triangle_count as returned by {@link polygon2_triangulate}
+ * @param {ArrayLike<number>} points flat (x, y) pairs, stride 2
+ * @param {ArrayLike<number>} contour_ends exclusive end vertex index per contour
+ * @param {number} contour_count
+ * @returns {number} relative area error, `0` for an exact triangulation
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function polygon2_triangulation_deviation(
+    result, result_offset, triangle_count,
+    points, contour_ends, contour_count
+) {
+    // Outer contour area, minus every hole's.
+    let polygon_area = 0;
+
+    for (let c = 0; c < contour_count; c++) {
+        const from = c === 0 ? 0 : contour_ends[c - 1];
+        const to = contour_ends[c];
+
+        const count = to - from;
+
+        if (count < 3) {
+            continue;
+        }
+
+        const slice = from === 0
+            ? points
+            : (typeof points.subarray === "function" ? points.subarray(from * 2) : points.slice(from * 2));
+
+        const area = Math.abs(polygon2_signed_area(slice, count));
+
+        polygon_area += c === 0 ? area : -area;
+    }
+
+    let triangles_area = 0;
+
+    for (let t = 0; t < triangle_count; t++) {
+        const o = result_offset + t * 3;
+
+        const a = result[o] * 2;
+        const b = result[o + 1] * 2;
+        const c = result[o + 2] * 2;
+
+        triangles_area += Math.abs(tri2_signed_area(
+            points[a], points[a + 1],
+            points[b], points[b + 1],
+            points[c], points[c + 1]
+        ));
+    }
+
+    if (polygon_area === 0) {
+        return triangles_area === 0 ? 0 : Infinity;
+    }
+
+    return Math.abs(triangles_area - polygon_area) / Math.abs(polygon_area);
+}

package/src/core/geom/2d/triangle/tri2_rasterize_conservative.d.ts

@@ -6,9 +6,12 @@
  * candidate cell square.
  *
  * @param {{width:number, height:number, set:(x:number,y:number)=>void}} image
- * @param {number} x0 @param {number} y0
- * @param {number} x1 @param {number} y1
- * @param {number} x2 @param {number} y2
+ * @param {number} x0
+ * @param {number} y0
+ * @param {number} x1
+ * @param {number} y1
+ * @param {number} x2
+ * @param {number} y2
  */
 export function tri2_rasterize_conservative(image: {
     width: number;

package/src/core/geom/2d/triangle/tri2_rasterize_conservative.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tri2_rasterize_conservative.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/triangle/tri2_rasterize_conservative.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH;WALkB,MAAM;YAAS,MAAM;aAAS,MAAM,KAAG,MAAM,KAAG,IAAI;OAC3D,MAAM,MAAa,MAAM,MACzB,MAAM,MAAa,MAAM,MACzB,MAAM,MAAa,MAAM,QAoBnC"}
+{"version":3,"file":"tri2_rasterize_conservative.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/triangle/tri2_rasterize_conservative.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH;WARkB,MAAM;YAAS,MAAM;aAAS,MAAM,KAAG,MAAM,KAAG,IAAI;OAC3D,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAoBhB"}

package/src/core/geom/2d/triangle/tri2_rasterize_conservative.js

@@ -6,9 +6,12 @@
  * candidate cell square.
  *
  * @param {{width:number, height:number, set:(x:number,y:number)=>void}} image
- * @param {number} x0 @param {number} y0
- * @param {number} x1 @param {number} y1
- * @param {number} x2 @param {number} y2
+ * @param {number} x0
+ * @param {number} y0
+ * @param {number} x1
+ * @param {number} y1
+ * @param {number} x2
+ * @param {number} y2
  */
 export function tri2_rasterize_conservative(image, x0, y0, x1, y1, x2, y2) {
     let min_x = Math.floor(Math.min(x0, x1, x2));
@@ -33,11 +36,16 @@ export function tri2_rasterize_conservative(image, x0, y0, x1, y1, x2, y2) {
 /**
  * Separating-axis overlap test between a triangle and an axis-aligned box.
  *
- * @param {number} ax @param {number} ay first triangle vertex
- * @param {number} bx @param {number} by second triangle vertex
- * @param {number} cx @param {number} cy third triangle vertex
- * @param {number} bminx @param {number} bminy box minimum corner
- * @param {number} bmaxx @param {number} bmaxy box maximum corner
+ * @param {number} ax first triangle vertex x
+ * @param {number} ay first triangle vertex y
+ * @param {number} bx second triangle vertex x
+ * @param {number} by second triangle vertex y
+ * @param {number} cx third triangle vertex x
+ * @param {number} cy third triangle vertex y
+ * @param {number} bminx box minimum corner x
+ * @param {number} bminy box minimum corner y
+ * @param {number} bmaxx box maximum corner x
+ * @param {number} bmaxy box maximum corner y
  * @returns {boolean} true if the triangle and box overlap
  */
 function tri_box_overlap(ax, ay, bx, by, cx, cy, bminx, bminy, bmaxx, bmaxy) {
@@ -57,11 +65,16 @@ function tri_box_overlap(ax, ay, bx, by, cx, cy, bminx, bminy, bmaxx, bmaxy) {
  * Does the outward normal of edge (p->q) separate the box from the triangle?
  * `r` is the triangle's third vertex (to orient the normal inward).
  *
- * @param {number} px @param {number} py edge start vertex
- * @param {number} qx @param {number} qy edge end vertex
- * @param {number} rx @param {number} ry triangle's third vertex
- * @param {number} bminx @param {number} bminy box minimum corner
- * @param {number} bmaxx @param {number} bmaxy box maximum corner
+ * @param {number} px edge start vertex x
+ * @param {number} py edge start vertex y
+ * @param {number} qx edge end vertex x
+ * @param {number} qy edge end vertex y
+ * @param {number} rx triangle's third vertex x
+ * @param {number} ry triangle's third vertex y
+ * @param {number} bminx box minimum corner x
+ * @param {number} bminy box minimum corner y
+ * @param {number} bmaxx box maximum corner x
+ * @param {number} bmaxy box maximum corner y
  * @returns {boolean} true if this edge's axis separates the box from the triangle
  */
 function edge_separates(px, py, qx, qy, rx, ry, bminx, bminy, bmaxx, bmaxy) {

package/src/core/geom/2d/triangle/tri2_signed_area.d.ts

@@ -1,5 +1,21 @@
 /**
- * Uses Green's Theorem to compute area of a 2d triangle
+ * Signed area of a 2D triangle. Positive for counter-clockwise winding, negative
+ * for clockwise, zero when the three points are collinear.
+ *
+ * The edge vectors are formed FIRST and only then crossed. The algebraically
+ * identical expanded form -- `(x0*y1 - y0*x1) + (x1*y2 - y1*x2) + (x2*y0 - y2*x0)`,
+ * which this used to compute -- sums three products of ABSOLUTE coordinates, each
+ * `O(|p|^2)`, to reach an answer that is only the area. Those terms then cancel,
+ * and for a small triangle, or one far from the origin, the computed value -- and
+ * worse, its SIGN -- is rounding noise. A 1e-9-sided triangle at (1, 1) has a true
+ * area of ~5e-19 against per-term rounding of ~1e-16; the expanded form returns
+ * exactly 0. The callers most exposed were the ones that only want the sign: the
+ * Polyanya funnel and the atlas parameterisation validity check.
+ *
+ * This form's error is proportional to the area rather than to the coordinates'
+ * magnitude. It is still floating point: for a decision that must be exact
+ * regardless of magnitude, use `orient2d_indexed`, which is adaptive-exact.
+ *
  * @param {number} x0
  * @param {number} y0
  * @param {number} x1

package/src/core/geom/2d/triangle/tri2_signed_area.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tri2_signed_area.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/triangle/tri2_signed_area.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qCARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAclB"}
+{"version":3,"file":"tri2_signed_area.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/triangle/tri2_signed_area.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qCARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAUlB"}

package/src/core/geom/2d/triangle/tri2_signed_area.js

@@ -1,23 +1,35 @@
-/**
- * Uses Green's Theorem to compute area of a 2d triangle
- * @param {number} x0
- * @param {number} y0
- * @param {number} x1
- * @param {number} y1
- * @param {number} x2
- * @param {number} y2
- * @returns {number}
- */
-export function tri2_signed_area(
-    x0, y0,
-    x1, y1,
-    x2, y2
-) {
-
-    return (
-        (x0 * y1 - y0 * x1)
-        + (x1 * y2 - y1 * x2)
-        + (x2 * y0 - y2 * x0)
-    ) * 0.5;
-
-}
+/**
+ * Signed area of a 2D triangle. Positive for counter-clockwise winding, negative
+ * for clockwise, zero when the three points are collinear.
+ *
+ * The edge vectors are formed FIRST and only then crossed. The algebraically
+ * identical expanded form -- `(x0*y1 - y0*x1) + (x1*y2 - y1*x2) + (x2*y0 - y2*x0)`,
+ * which this used to compute -- sums three products of ABSOLUTE coordinates, each
+ * `O(|p|^2)`, to reach an answer that is only the area. Those terms then cancel,
+ * and for a small triangle, or one far from the origin, the computed value -- and
+ * worse, its SIGN -- is rounding noise. A 1e-9-sided triangle at (1, 1) has a true
+ * area of ~5e-19 against per-term rounding of ~1e-16; the expanded form returns
+ * exactly 0. The callers most exposed were the ones that only want the sign: the
+ * Polyanya funnel and the atlas parameterisation validity check.
+ *
+ * This form's error is proportional to the area rather than to the coordinates'
+ * magnitude. It is still floating point: for a decision that must be exact
+ * regardless of magnitude, use `orient2d_indexed`, which is adaptive-exact.
+ *
+ * @param {number} x0
+ * @param {number} y0
+ * @param {number} x1
+ * @param {number} y1
+ * @param {number} x2
+ * @param {number} y2
+ * @returns {number}
+ */
+export function tri2_signed_area(
+    x0, y0,
+    x1, y1,
+    x2, y2
+) {
+
+    return ((x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0)) * 0.5;
+
+}

package/src/core/geom/2d/v2_morton_encode.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Interleave two 16-bit integer coordinates into a 32-bit Morton (Z-order) code.
+ *
+ * The 2D counterpart of the {@link v3_morton_encode} family. Inputs above 16 bits
+ * are silently truncated by {@link split_by_2}'s masking, which is the same
+ * contract the 3D encoders carry: callers quantise into range first.
+ *
+ * Points close in Z-order are close in space, which is what makes a Z-sorted
+ * sequence usable as a cheap 1D proxy for a 2D range query -- the acceleration
+ * {@link polygon2_triangulate} uses to keep its point-in-ear test local.
+ *
+ * @param {number} x integer in [0, 65535]
+ * @param {number} y integer in [0, 65535]
+ * @returns {number} unsigned 32-bit Morton code
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v2_morton_encode(x: number, y: number): number;
+//# sourceMappingURL=v2_morton_encode.d.ts.map

package/src/core/geom/2d/v2_morton_encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2_morton_encode.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/2d/v2_morton_encode.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,oCAPW,MAAM,KACN,MAAM,GACJ,MAAM,CAOlB"}

package/src/core/geom/2d/v2_morton_encode.js

@@ -0,0 +1,23 @@
+import { split_by_2 } from "../../binary/split_by_2.js";
+
+/**
+ * Interleave two 16-bit integer coordinates into a 32-bit Morton (Z-order) code.
+ *
+ * The 2D counterpart of the {@link v3_morton_encode} family. Inputs above 16 bits
+ * are silently truncated by {@link split_by_2}'s masking, which is the same
+ * contract the 3D encoders carry: callers quantise into range first.
+ *
+ * Points close in Z-order are close in space, which is what makes a Z-sorted
+ * sequence usable as a cheap 1D proxy for a 2D range query -- the acceleration
+ * {@link polygon2_triangulate} uses to keep its point-in-ear test local.
+ *
+ * @param {number} x integer in [0, 65535]
+ * @param {number} y integer in [0, 65535]
+ * @returns {number} unsigned 32-bit Morton code
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v2_morton_encode(x, y) {
+    return (split_by_2(x) | (split_by_2(y) << 1)) >>> 0;
+}

package/src/core/geom/3d/atlas/segment/atlas_merge_charts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atlas_merge_charts.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/segment/atlas_merge_charts.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qEAPW,UAAU,eACV,MAAM,cACN,YAAY;IAEK,WAAW,GAA5B,MAAM;IACJ;IAAC,UAAU,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAkFzD"}
+{"version":3,"file":"atlas_merge_charts.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/segment/atlas_merge_charts.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qEAPW,UAAU,eACV,MAAM,cACN,YAAY;IAEK,WAAW,GAA5B,MAAM;IACJ;IAAC,UAAU,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAqFzD"}

package/src/core/geom/3d/atlas/segment/atlas_merge_charts.js

@@ -52,7 +52,10 @@ export function atlas_merge_charts(mesh, face_chart, chart_count, face_areas, op
     const parent = new Int32Array(chart_count);
     for (let c = 0; c < chart_count; c++) parent[c] = c;
 
-    /** @param {number} x @returns {number} root with path compression */
+    /**
+     * @param {number} x
+     * @returns {number} root with path compression
+     */
     function find(x) {
         while (parent[x] !== x) {
             parent[x] = parent[parent[x]];

package/src/core/geom/3d/polygon/polygon3_compute_normal.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Newell's method: the area-weighted normal of an arbitrary 3D polygon, written
+ * to `result` at `result_offset` as a unit vector.
+ *
+ * Unlike taking the cross product of the first three vertices
+ * (what {@link bt_mesh_compute_face_normals} does, correctly, for triangles),
+ * this is defined for any vertex count, is immune to a collinear or coincident
+ * leading triple, and for a non-planar polygon returns the normal of its
+ * best-fit plane rather than of one arbitrary corner. That is exactly what
+ * projecting an n-gon down to 2D needs.
+ *
+ * A polygon with no area -- fewer than three vertices, all collinear, or all
+ * coincident -- has no normal; `result` is then written as `(0, 0, 0)`, which
+ * callers can test with a length check. That is a real outcome of real data, not
+ * an error.
+ *
+ * @param {ArrayLike<number>} result
+ * @param {number} result_offset
+ * @param {ArrayLike<number>} points flat (x, y, z) triples, stride 3
+ * @param {number} from first vertex index of the contour
+ * @param {number} count number of vertices in the contour
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function polygon3_compute_normal(result: ArrayLike<number>, result_offset: number, points: ArrayLike<number>, from: number, count: number): void;
+//# sourceMappingURL=polygon3_compute_normal.d.ts.map

package/src/core/geom/3d/polygon/polygon3_compute_normal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon3_compute_normal.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/polygon/polygon3_compute_normal.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,gDATW,UAAU,MAAM,CAAC,iBACjB,MAAM,UACN,UAAU,MAAM,CAAC,QACjB,MAAM,SACN,MAAM,QAuChB"}

package/src/core/geom/3d/polygon/polygon3_compute_normal.js

@@ -0,0 +1,60 @@
+/**
+ * Newell's method: the area-weighted normal of an arbitrary 3D polygon, written
+ * to `result` at `result_offset` as a unit vector.
+ *
+ * Unlike taking the cross product of the first three vertices
+ * (what {@link bt_mesh_compute_face_normals} does, correctly, for triangles),
+ * this is defined for any vertex count, is immune to a collinear or coincident
+ * leading triple, and for a non-planar polygon returns the normal of its
+ * best-fit plane rather than of one arbitrary corner. That is exactly what
+ * projecting an n-gon down to 2D needs.
+ *
+ * A polygon with no area -- fewer than three vertices, all collinear, or all
+ * coincident -- has no normal; `result` is then written as `(0, 0, 0)`, which
+ * callers can test with a length check. That is a real outcome of real data, not
+ * an error.
+ *
+ * @param {ArrayLike<number>} result
+ * @param {number} result_offset
+ * @param {ArrayLike<number>} points flat (x, y, z) triples, stride 3
+ * @param {number} from first vertex index of the contour
+ * @param {number} count number of vertices in the contour
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function polygon3_compute_normal(result, result_offset, points, from, count) {
+    let nx = 0;
+    let ny = 0;
+    let nz = 0;
+
+    const to = from + count;
+
+    for (let i = from; i < to; i++) {
+        const j = (i + 1 === to) ? from : i + 1;
+
+        const i3 = i * 3;
+        const j3 = j * 3;
+
+        const ax = points[i3], ay = points[i3 + 1], az = points[i3 + 2];
+        const bx = points[j3], by = points[j3 + 1], bz = points[j3 + 2];
+
+        nx += (ay - by) * (az + bz);
+        ny += (az - bz) * (ax + bx);
+        nz += (ax - bx) * (ay + by);
+    }
+
+    const length = Math.sqrt(nx * nx + ny * ny + nz * nz);
+
+    if (length === 0) {
+        result[result_offset] = 0;
+        result[result_offset + 1] = 0;
+        result[result_offset + 2] = 0;
+
+        return;
+    }
+
+    result[result_offset] = nx / length;
+    result[result_offset + 1] = ny / length;
+    result[result_offset + 2] = nz / length;
+}

package/src/core/geom/3d/polygon/polygon3_triangulate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Triangulate a planar 3D polygon with holes, viewed along `-normal`.
+ *
+ * The polygon is projected to 2D by **dropping the axis the normal points most
+ * strongly along** and keeping the other two verbatim, swapped when that
+ * component is negative so the projection stays counter-clockwise as seen from
+ * `+normal`. Nothing is rotated and no coordinate is recomputed, which is the
+ * whole point: {@link polygon2_triangulate} decides exactly, and it can only do
+ * that on coordinates that are exactly the input's. A rotation into a fitted
+ * plane basis would round every vertex first and hand the exact predicate
+ * approximate data.
+ *
+ * `normal` need not be normalised, but it must not be zero. Derive it with
+ * {@link polygon3_compute_normal} when the caller has no authoritative one.
+ *
+ * Output indices address `points3` -- the same vertices the caller passed in --
+ * and each triangle is counter-clockwise when viewed from `+normal`.
+ *
+ * @param {Uint32Array} result receives 3 point indices per triangle
+ * @param {number} result_offset first index written in `result`
+ * @param {ArrayLike<number>} points3 flat (x, y, z) triples, stride 3
+ * @param {ArrayLike<number>} contour_ends exclusive end vertex index per contour
+ * @param {number} contour_count number of contours; contour 0 is the outer boundary
+ * @param {number} nx
+ * @param {number} ny
+ * @param {number} nz polygon normal, need not be unit length
+ * @returns {number} number of triangles written; see {@link polygon2_triangulate}
+ *     for what a short count means
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function polygon3_triangulate(result: Uint32Array, result_offset: number, points3: ArrayLike<number>, contour_ends: ArrayLike<number>, contour_count: number, nx: number, ny: number, nz: number): number;
+//# sourceMappingURL=polygon3_triangulate.d.ts.map

package/src/core/geom/3d/polygon/polygon3_triangulate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon3_triangulate.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/polygon/polygon3_triangulate.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,6CAdW,WAAW,iBACX,MAAM,WACN,UAAU,MAAM,CAAC,gBACjB,UAAU,MAAM,CAAC,iBACjB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAwDlB"}

package/src/core/geom/3d/polygon/polygon3_triangulate.js

@@ -0,0 +1,94 @@
+import { assert } from "../../../assert.js";
+import { polygon2_triangulate } from "../../2d/polygon/polygon2_triangulate.js";
+
+/**
+ * Projected (u, v) per vertex for the current call. Module-static and grown on
+ * demand, matching {@link polygon2_triangulate}'s own storage -- and, like it,
+ * this function is therefore not re-entrant.
+ * @type {Float64Array}
+ */
+let _projected = new Float64Array(0);
+
+/**
+ * Triangulate a planar 3D polygon with holes, viewed along `-normal`.
+ *
+ * The polygon is projected to 2D by **dropping the axis the normal points most
+ * strongly along** and keeping the other two verbatim, swapped when that
+ * component is negative so the projection stays counter-clockwise as seen from
+ * `+normal`. Nothing is rotated and no coordinate is recomputed, which is the
+ * whole point: {@link polygon2_triangulate} decides exactly, and it can only do
+ * that on coordinates that are exactly the input's. A rotation into a fitted
+ * plane basis would round every vertex first and hand the exact predicate
+ * approximate data.
+ *
+ * `normal` need not be normalised, but it must not be zero. Derive it with
+ * {@link polygon3_compute_normal} when the caller has no authoritative one.
+ *
+ * Output indices address `points3` -- the same vertices the caller passed in --
+ * and each triangle is counter-clockwise when viewed from `+normal`.
+ *
+ * @param {Uint32Array} result receives 3 point indices per triangle
+ * @param {number} result_offset first index written in `result`
+ * @param {ArrayLike<number>} points3 flat (x, y, z) triples, stride 3
+ * @param {ArrayLike<number>} contour_ends exclusive end vertex index per contour
+ * @param {number} contour_count number of contours; contour 0 is the outer boundary
+ * @param {number} nx
+ * @param {number} ny
+ * @param {number} nz polygon normal, need not be unit length
+ * @returns {number} number of triangles written; see {@link polygon2_triangulate}
+ *     for what a short count means
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function polygon3_triangulate(
+    result, result_offset,
+    points3, contour_ends, contour_count,
+    nx, ny, nz
+) {
+    assert.isArrayLike(points3, "points3");
+    assert.isPositiveInteger(contour_count, "contour_count");
+    assert.ok(nx !== 0 || ny !== 0 || nz !== 0, "polygon normal must not be zero");
+
+    const vertex_count = contour_ends[contour_count - 1];
+
+    if (vertex_count < 3) {
+        return 0;
+    }
+
+    if (_projected.length < vertex_count * 2) {
+        _projected = new Float64Array(vertex_count * 2);
+    }
+
+    const ax = Math.abs(nx);
+    const ay = Math.abs(ny);
+    const az = Math.abs(nz);
+
+    // Component offsets of the two axes kept, in the order that preserves
+    // counter-clockwise winding seen from +normal:
+    //   +x -> (y, z)    -x -> (z, y)
+    //   +y -> (z, x)    -y -> (x, z)
+    //   +z -> (x, y)    -z -> (y, x)
+    let u_axis;
+    let v_axis;
+
+    if (ax >= ay && ax >= az) {
+        u_axis = nx > 0 ? 1 : 2;
+        v_axis = nx > 0 ? 2 : 1;
+    } else if (ay >= az) {
+        u_axis = ny > 0 ? 2 : 0;
+        v_axis = ny > 0 ? 0 : 2;
+    } else {
+        u_axis = nz > 0 ? 0 : 1;
+        v_axis = nz > 0 ? 1 : 0;
+    }
+
+    for (let i = 0; i < vertex_count; i++) {
+        const i3 = i * 3;
+
+        _projected[i * 2] = points3[i3 + u_axis];
+        _projected[i * 2 + 1] = points3[i3 + v_axis];
+    }
+
+    return polygon2_triangulate(result, result_offset, _projected, contour_ends, contour_count);
+}

package/src/core/geom/3d/quaternion/quat3_multiply.d.ts

@@ -14,8 +14,14 @@
  *
  * @param {number[]|Float32Array|Float64Array} out
  * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
- * @param {number} ax @param {number} ay @param {number} az @param {number} aw
- * @param {number} bx @param {number} by @param {number} bz @param {number} bw
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} aw
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} bw
  */
 export function quat3_multiply(out: number[] | Float32Array | Float64Array, out_offset: number, ax: number, ay: number, az: number, aw: number, bx: number, by: number, bz: number, bw: number): void;
 //# sourceMappingURL=quat3_multiply.d.ts.map

package/src/core/geom/3d/quaternion/quat3_multiply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quat3_multiply.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_multiply.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,oCALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,MACN,MAAM,MAAa,MAAM,MAAa,MAAM,MAAa,MAAM,MAC/D,MAAM,MAAa,MAAM,MAAa,MAAM,MAAa,MAAM,QAOzE"}
+{"version":3,"file":"quat3_multiply.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_multiply.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,oCAXW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAOhB"}

package/src/core/geom/3d/quaternion/quat3_multiply.js

@@ -14,8 +14,14 @@
  *
  * @param {number[]|Float32Array|Float64Array} out
  * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
- * @param {number} ax @param {number} ay @param {number} az @param {number} aw
- * @param {number} bx @param {number} by @param {number} bz @param {number} bw
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} aw
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} bw
  */
 export function quat3_multiply(out, out_offset, ax, ay, az, aw, bx, by, bz, bw) {
     out[out_offset]     = aw * bx + ax * bw + ay * bz - az * by;

package/src/core/geom/3d/shape/ConvexHullShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConvexHullShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/ConvexHullShape3D.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA+CI;;;;;;;OAOG;IACH,sBAJW,YAAY,WACZ,WAAW,GACT,iBAAiB,CAQ7B;IAxDG;;;;OAIG;IACH,UAFU,YAAY,CAEa;IAEnC;;;;OAIG;IACH,SAFU,WAAW,CAEY;IAEjC;;;;;;OAMG;IACH,cAFU,WAAW,CAEiB;IACtC,0BAA0B;IAC1B,YADW,WAAW,CACc;IAEpC;;;;;;OAMG;IACH,iBAAmC;IAEnC,oCAAoC;IACpC,eAAiC;IACjC,8BAA8B;IAC9B,iBAAiB;IACjB,8BAA8B;IAC9B,uBAAuB;IAmB3B;;;OAGG;IACH,kBAmDC;IAKD,wCAIC;IAED;;;;;OAKG;IACH,qGAgBC;IAED;;;OAGG;IACH,oCAgBC;IAED;;;OAGG;IACH,6CAwBC;IAED,mEAEC;IAED,4DAwBC;IAED,kFAmBC;IAED;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAanB;IAcL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;CAP9C;gCAxT+B,sBAAsB"}
+{"version":3,"file":"ConvexHullShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/ConvexHullShape3D.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA+CI;;;;;;;OAOG;IACH,sBAJW,YAAY,WACZ,WAAW,GACT,iBAAiB,CAQ7B;IAxDG;;;;OAIG;IACH,UAFU,YAAY,CAEa;IAEnC;;;;OAIG;IACH,SAFU,WAAW,CAEY;IAEjC;;;;;;OAMG;IACH,cAFU,WAAW,CAEiB;IACtC,0BAA0B;IAC1B,YADW,WAAW,CACc;IAEpC;;;;;;OAMG;IACH,iBAAmC;IAEnC,oCAAoC;IACpC,eAAiC;IACjC,8BAA8B;IAC9B,iBAAiB;IACjB,8BAA8B;IAC9B,uBAAuB;IAmB3B;;;OAGG;IACH,kBAiFC;IAKD,wCAIC;IAED;;;;;OAKG;IACH,qGAgBC;IAED;;;OAGG;IACH,oCAgBC;IAED;;;OAGG;IACH,6CAwBC;IAED,mEAEC;IAED,4DAwBC;IAED,kFAmBC;IAED;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAanB;IAcL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;CAP9C;gCAtV+B,sBAAsB"}