@woosh/meep-engine 2.168.1 → 2.169.1

package/src/core/geom/3d/topology/struct/TopoTriangle.d.ts

@@ -42,10 +42,10 @@ export class TopoTriangle {
     clone(): TopoTriangle;
     /**
      *
-     * @param {function(reason:string)} error_consumer
+     * @param {(reason: string) => void} error_consumer
      * @return {boolean}
      */
-    validate(error_consumer: any): boolean;
+    validate(error_consumer: (reason: string) => void): boolean;
     /**
      *
      * @return {boolean}

package/src/core/geom/3d/topology/struct/TopoTriangle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TopoTriangle.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/topology/struct/TopoTriangle.js"],"names":[],"mappings":"AAWA;IAmRI;;;;;;;;;;;;OAYG;IACH,sBAXW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,CA4CvB;IAzUD;;;OAGG;IACH,OAFU,MAAM,CAEQ;IACxB;;;OAGG;IACH,UAFU,UAAU,EAAE,CAER;IACd;;;OAGG;IACH,OAFU,QAAQ,EAAE,CAET;IAEX;;;OAGG;IACH,QAFU,MAAM,EAAE,OAAK,CAEJ;IAEnB,uBAEC;IAED;;;OAGG;IACH,YAFW,YAAY,QAQtB;IAED,sBAMC;IAED;;;;OAIG;IACH,+BAFY,OAAO,CA0ClB;IAED;;;OAGG;IACH,YAFY,OAAO,CAKlB;IAED;;;;OAIG;IACH,sBAHW,QAAQ,eACR,QAAQ,QAIlB;IAED;;;;OAIG;IACH,wBAHW,UAAU,eACV,UAAU,QAMpB;IAED;;OAEG;IACH,gCASC;IAED;;OAEG;IACH,eAmBC;IAED;;;OAGG;IACH,WAFW,QAAQ,QAMlB;IAED;;;;OAIG;IACH,iBAHW,QAAQ,GACP,OAAO,CAIlB;IAED;;;OAGG;IACH,cAFW,QAAQ,QAQlB;IAED;;;;OAIG;IACH,mBAHW,QAAQ,GACN,OAAO,CAKnB;IAED,sBAaC;IAGD;;;;OAIG;IACH,mBAHW,MAAM,UACN,UAAU,QAOpB;IAED;;;;OAIG;IACH,uBAHW,UAAU,GACT,OAAO,CAIlB;IAED;;;;;OAKG;IACH,0BAJW,YAAY,EAAE,iBACd,MAAM,GACJ,MAAM,CA8BlB;IA4DL;;;OAGG;IACH,qBAFU,OAAO,CAEgB;CANhC;2BA/U0B,iBAAiB;yBADnB,eAAe"}
+{"version":3,"file":"TopoTriangle.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/topology/struct/TopoTriangle.js"],"names":[],"mappings":"AAWA;IAmRI;;;;;;;;;;;;OAYG;IACH,sBAXW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,CA4CvB;IAzUD;;;OAGG;IACH,OAFU,MAAM,CAEQ;IACxB;;;OAGG;IACH,UAFU,UAAU,EAAE,CAER;IACd;;;OAGG;IACH,OAFU,QAAQ,EAAE,CAET;IAEX;;;OAGG;IACH,QAFU,MAAM,EAAE,OAAK,CAEJ;IAEnB,uBAEC;IAED;;;OAGG;IACH,YAFW,YAAY,QAQtB;IAED,sBAMC;IAED;;;;OAIG;IACH,kCAHoB,MAAM,KAAK,IAAI,GACvB,OAAO,CA0ClB;IAED;;;OAGG;IACH,YAFY,OAAO,CAKlB;IAED;;;;OAIG;IACH,sBAHW,QAAQ,eACR,QAAQ,QAIlB;IAED;;;;OAIG;IACH,wBAHW,UAAU,eACV,UAAU,QAMpB;IAED;;OAEG;IACH,gCASC;IAED;;OAEG;IACH,eAmBC;IAED;;;OAGG;IACH,WAFW,QAAQ,QAMlB;IAED;;;;OAIG;IACH,iBAHW,QAAQ,GACP,OAAO,CAIlB;IAED;;;OAGG;IACH,cAFW,QAAQ,QAQlB;IAED;;;;OAIG;IACH,mBAHW,QAAQ,GACN,OAAO,CAKnB;IAED,sBAaC;IAGD;;;;OAIG;IACH,mBAHW,MAAM,UACN,UAAU,QAOpB;IAED;;;;OAIG;IACH,uBAHW,UAAU,GACT,OAAO,CAIlB;IAED;;;;;OAKG;IACH,0BAJW,YAAY,EAAE,iBACd,MAAM,GACJ,MAAM,CA8BlB;IA4DL;;;OAGG;IACH,qBAFU,OAAO,CAEgB;CANhC;2BA/U0B,iBAAiB;yBADnB,eAAe"}

package/src/core/geom/3d/topology/struct/TopoTriangle.js

@@ -58,7 +58,7 @@ export class TopoTriangle {
 
     /**
      *
-     * @param {function(reason:string)} error_consumer
+     * @param {(reason: string) => void} error_consumer
      * @return {boolean}
      */
     validate(error_consumer) {

package/src/core/geom/3d/topology/struct/TopoVertex.d.ts

@@ -56,10 +56,10 @@ export class TopoVertex {
     clone(): TopoVertex;
     /**
      *
-     * @param {function(reason:string)} error_consumer
+     * @param {(reason: string) => void} error_consumer
      * @return {boolean}
      */
-    validate(error_consumer: any): boolean;
+    validate(error_consumer: (reason: string) => void): boolean;
     /**
      *
      * @param {TopoVertex} other

package/src/core/geom/3d/topology/struct/TopoVertex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TopoVertex.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/topology/struct/TopoVertex.js"],"names":[],"mappings":"AAQA;IAkRI;;;;;;OAMG;IACH,eALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,UAAU,CAYrB;IAjSD;;;OAGG;IACH,OAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,OAFU,UAAU,CAET;IAEX;;;OAGG;IACH,OAFU,cAAc,CAEb;IAEX;;;OAGG;IACH,GAFU,MAAM,CAEV;IACN;;;OAGG;IACH,GAFU,MAAM,CAEV;IACN;;;OAGG;IACH,GAFU,MAAM,CAEV;IAEN,gBAEC;IAED,gBAEC;IAED,gBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,YAFW,UAAU,QAYpB;IAED;;OAEG;IACH,SAFa,UAAU,CAQtB;IAED;;;;OAIG;IACH,+BAFY,OAAO,CA8BlB;IAED;;;;OAIG;IACH,kBAHW,UAAU,GACT,MAAM,CAWjB;IAED;;;OAGG;IACH,+BAKC;IAED;;;;OAIG;IACH,gCAFY,OAAO,CAMlB;IAED;;;;OAIG;IACH,kCAFY,OAAO,CAKlB;IAED;;;OAGG;IACH,kCAKC;IAED;;;OAGG;IACH,2BAMC;IAED;;;;OAIG;IACH,4BAFY,OAAO,CAOlB;IAED;;;;OAIG;IACH,2DAaC;IAED;;;;OAIG;IACH,8BAFa,OAAO,CAMnB;IAED;;;;OAIG;IACH,yBAFa,OAAO,CAWnB;IAED;;;;;OAKG;IACH,iCAJW,UAAU,EAAE,iBACZ,MAAM,GACJ,MAAM,CAoBlB;IAsBL;;;OAGG;IACH,uBAFU,OAAO,CAEgB;CANhC"}
+{"version":3,"file":"TopoVertex.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/topology/struct/TopoVertex.js"],"names":[],"mappings":"AAQA;IAkRI;;;;;;OAMG;IACH,eALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,UAAU,CAYrB;IAjSD;;;OAGG;IACH,OAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,OAFU,UAAU,CAET;IAEX;;;OAGG;IACH,OAFU,cAAc,CAEb;IAEX;;;OAGG;IACH,GAFU,MAAM,CAEV;IACN;;;OAGG;IACH,GAFU,MAAM,CAEV;IACN;;;OAGG;IACH,GAFU,MAAM,CAEV;IAEN,gBAEC;IAED,gBAEC;IAED,gBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,YAFW,UAAU,QAYpB;IAED;;OAEG;IACH,SAFa,UAAU,CAQtB;IAED;;;;OAIG;IACH,kCAHoB,MAAM,KAAK,IAAI,GACvB,OAAO,CA8BlB;IAED;;;;OAIG;IACH,kBAHW,UAAU,GACT,MAAM,CAWjB;IAED;;;OAGG;IACH,+BAKC;IAED;;;;OAIG;IACH,gCAFY,OAAO,CAMlB;IAED;;;;OAIG;IACH,kCAFY,OAAO,CAKlB;IAED;;;OAGG;IACH,kCAKC;IAED;;;OAGG;IACH,2BAMC;IAED;;;;OAIG;IACH,4BAFY,OAAO,CAOlB;IAED;;;;OAIG;IACH,2DAaC;IAED;;;;OAIG;IACH,8BAFa,OAAO,CAMnB;IAED;;;;OAIG;IACH,yBAFa,OAAO,CAWnB;IAED;;;;;OAKG;IACH,iCAJW,UAAU,EAAE,iBACZ,MAAM,GACJ,MAAM,CAoBlB;IAsBL;;;OAGG;IACH,uBAFU,OAAO,CAEgB;CANhC"}

package/src/core/geom/3d/topology/struct/TopoVertex.js

@@ -91,7 +91,7 @@ export class TopoVertex {
 
     /**
      *
-     * @param {function(reason:string)} error_consumer
+     * @param {(reason: string) => void} error_consumer
      * @return {boolean}
      */
     validate(error_consumer) {

package/src/core/geom/3d/topology/struct/binary/io/face/bt_face_triangulate.d.ts

@@ -1,13 +1,30 @@
 /**
- * Triangulate a face in a binary topology mesh.
+ * Split one face of a {@link BinaryTopology} into triangles, in place.
  *
- * Assumes that each face is a convex polygon.
+ * Handles any simple polygon, convex or not: the corner order is projected onto
+ * the plane of the face's own Newell normal and triangulated by
+ * {@link polygon3_triangulate}, whose decisions are exact. The resulting ear
+ * sequence is then replayed as topology surgery, so existing corners keep their
+ * identity (and any per-loop data) and only the diagonals are new. Each new face
+ * inherits the original's stored normal.
  *
- * If the face is already a triangle, no action is taken.
+ * Superseded the previous fan-from-the-first-corner implementation, which was
+ * correct only for convex faces and produced silently overlapping triangles for
+ * anything else.
+ *
+ * Nothing is changed, and `1` is returned, when the face is already a triangle,
+ * has no area (so no plane to project onto), or projects to a self-intersecting
+ * outline -- which is a non-planar or otherwise malformed face, and cannot be cut
+ * into ears at all. Leaving it whole is the honest outcome; half-cutting it would
+ * corrupt the mesh.
  *
  * @param {BinaryTopology} mesh
- * @param {number} face Face ID
- * @return {boolean} True if the face was triangulated, false if it was already a triangle.
+ * @param {number} face
+ * @returns {number} how many faces the input face became: `1` when it was left
+ *     untouched, otherwise the number of triangles it was split into
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
  */
-export function bt_face_triangulate(mesh: BinaryTopology, face: number): boolean;
+export function bt_face_triangulate(mesh: BinaryTopology, face: number): number;
 //# sourceMappingURL=bt_face_triangulate.d.ts.map

package/src/core/geom/3d/topology/struct/binary/io/face/bt_face_triangulate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bt_face_triangulate.d.ts","sourceRoot":"","sources":["../../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/face/bt_face_triangulate.js"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,gEAHW,MAAM,GACL,OAAO,CA8GlB"}
+{"version":3,"file":"bt_face_triangulate.d.ts","sourceRoot":"","sources":["../../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/face/bt_face_triangulate.js"],"names":[],"mappings":"AAqKA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,gEAPW,MAAM,GACJ,MAAM,CAgFlB"}

package/src/core/geom/3d/topology/struct/binary/io/face/bt_face_triangulate.js

@@ -1,124 +1,268 @@
-import { NULL_POINTER } from "../../BinaryTopology.js";
-import { bt_radial_loop_add } from "../bt_radial_loop_add.js";
-import { bt_edge_create } from "../edge/bt_edge_create.js";
-
-/**
- * Triangulate a face in a binary topology mesh.
- *
- * Assumes that each face is a convex polygon.
- *
- * If the face is already a triangle, no action is taken.
- *
- * @param {BinaryTopology} mesh
- * @param {number} face Face ID
- * @return {boolean} True if the face was triangulated, false if it was already a triangle.
- */
-export function bt_face_triangulate(
-    mesh,
-    face
-) {
-    // 1. Validate Face and Count Loops
-    const first_loop = mesh.face_read_loop(face);
-    if (first_loop === NULL_POINTER){
-        // should never happen, but just in case
-        return false;
-    }
-
-    let count = 0;
-    let iter = first_loop;
-    do {
-        count++;
-        iter = mesh.loop_read_next(iter);
-    } while (iter !== first_loop);
-
-    if (count < 4) {
-        // looks like a triangle
-        return false;
-    }
-
-    // 2. Prepare for Triangulation (Fan method at first vertex)
-    let l_prev = first_loop;                  // Vertex 0 (Anchor)
-    let l_curr = mesh.loop_read_next(l_prev); // Vertex 1
-    let l_next = mesh.loop_read_next(l_curr); // Vertex 2
-
-    const cuts = count - 3;
-
-    // Cache normal to apply to new faces
-    const normal = new Float32Array(3);
-    mesh.face_read_normal(normal, 0, face);
-
-    for (let i = 0; i < cuts; i++) {
-        // We cut the triangle (l_prev, l_curr, l_next) out of 'face'.
-        // New Edge connects V(l_prev) <-> V(l_next).
-
-        const v_anchor = mesh.loop_read_vertex(l_prev);
-        const v_target = mesh.loop_read_vertex(l_next);
-
-        // --- A. Create Topology Elements ---
-        // Reuse: Handles allocation and Vertex Disk Cycle linking
-        const e_new = bt_edge_create(mesh, v_anchor, v_target);
-
-        const f_new = mesh.faces.allocate();
-        const l_tri = mesh.loop_create();  // Loop at v_target (for the Triangle)
-        const l_poly = mesh.loop_create(); // Loop at v_anchor (for the Polygon)
-
-        // --- B. Setup Loops & Radial Cycles ---
-
-        // 1. Setup l_tri properties
-        mesh.loop_write_vertex(l_tri, v_target);
-        mesh.loop_write_face(l_tri, f_new);
-
-        // 2. Setup l_poly properties
-        mesh.loop_write_vertex(l_poly, v_anchor);
-        mesh.loop_write_face(l_poly, face); // Stays part of the shrinking polygon
-
-        // 3. Reuse: Link loops to the edge's Radial Cycle
-        bt_radial_loop_add(mesh, l_tri, e_new);
-        bt_radial_loop_add(mesh, l_poly, e_new);
-
-        // --- C. Re-link Face Loop Topology (Next/Prev) ---
-
-        // 1. Get the loop entering the anchor from the polygon side
-        const l_prev_prev = mesh.loop_read_prev(l_prev);
-
-        // 2. Assign l_prev and l_curr to the new Triangle Face
-        mesh.loop_write_face(l_prev, f_new);
-        mesh.loop_write_face(l_curr, f_new);
-
-        // 3. Close the New Triangle (l_prev -> l_curr -> l_tri)
-        mesh.loop_write_next(l_prev, l_curr);
-        mesh.loop_write_prev(l_prev, l_tri);
-
-        mesh.loop_write_next(l_curr, l_tri);
-        mesh.loop_write_prev(l_curr, l_prev);
-
-        mesh.loop_write_next(l_tri, l_prev);
-        mesh.loop_write_prev(l_tri, l_curr);
-
-        // Set properties for the new face
-        mesh.face_write_loop(f_new, l_prev);
-        mesh.face_write_normal(f_new, normal, 0);
-
-        // 4. Close the Remaining Polygon (l_prev_prev -> l_poly -> l_next)
-        mesh.loop_write_next(l_prev_prev, l_poly);
-        // l_prev_prev's prev pointer remains unchanged
-
-        mesh.loop_write_prev(l_poly, l_prev_prev);
-        mesh.loop_write_next(l_poly, l_next);
-
-        mesh.loop_write_prev(l_next, l_poly);
-        // l_next's next pointer remains unchanged
-
-        // Update Polygon Face pointer (ensure it points to a valid loop in the poly)
-        mesh.face_write_loop(face, l_poly);
-
-        // --- D. Advance Fan ---
-        // The polygon now starts at l_poly (at v0).
-        // The next triangle will use l_poly as its "prev", l_next as "curr".
-        l_prev = l_poly;
-        l_curr = l_next;
-        l_next = mesh.loop_read_next(l_next);
-    }
-
-    return true;
-}
+import { polygon3_compute_normal } from "../../../../../polygon/polygon3_compute_normal.js";
+import { polygon3_triangulate } from "../../../../../polygon/polygon3_triangulate.js";
+import { NULL_POINTER } from "../../BinaryTopology.js";
+import { bt_radial_loop_add } from "../bt_radial_loop_add.js";
+import { bt_edge_create } from "../edge/bt_edge_create.js";
+
+// Per-call scratch, grown on demand. Faces are small, so these stay tiny in
+// practice; module-static so triangulating a whole mesh allocates nothing.
+let _loops = new Uint32Array(0);
+let _positions = new Float64Array(0);
+let _triangles = new Uint32Array(0);
+let _ring_next = new Uint32Array(0);
+let _ring_prev = new Uint32Array(0);
+
+const _contour_ends = new Uint32Array(1);
+const _normal = new Float64Array(3);
+const _stored_normal = new Float32Array(3);
+const _coordinate = new Float32Array(3);
+
+/**
+ * @param {number} corner_count
+ */
+function ensure_capacity(corner_count) {
+    if (_loops.length >= corner_count) {
+        return;
+    }
+
+    _loops = new Uint32Array(corner_count);
+    _positions = new Float64Array(corner_count * 3);
+    _triangles = new Uint32Array(Math.max(0, corner_count - 2) * 3);
+    _ring_next = new Uint32Array(corner_count);
+    _ring_prev = new Uint32Array(corner_count);
+}
+
+/**
+ * Cut the triangle `(prev(l_ear), l_ear, next(l_ear))` off `face` as a new face,
+ * leaving `face` one corner smaller.
+ *
+ * The two existing corners move to the new face and two fresh loops are created:
+ * one closing the triangle at the far vertex, one continuing the shrunken polygon
+ * at the near vertex. Both are attached to the new diagonal edge's radial cycle.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} face
+ * @param {number} l_ear the corner being cut away
+ * @param {Float32Array} normal applied to the new face
+ * @returns {number} the replacement corner the shrunken polygon now has at the
+ *     ear's predecessor vertex -- the old one moved to the new triangle, so any
+ *     caller holding it must swap in this one
+ */
+function cut_ear(mesh, face, l_ear, normal) {
+    const l_prev = mesh.loop_read_prev(l_ear);
+    const l_next = mesh.loop_read_next(l_ear);
+
+    const v_anchor = mesh.loop_read_vertex(l_prev);
+    const v_target = mesh.loop_read_vertex(l_next);
+
+    // handles allocation and vertex-disk linking for the diagonal
+    const e_new = bt_edge_create(mesh, v_anchor, v_target);
+
+    const f_new = mesh.faces.allocate();
+    const l_tri = mesh.loop_create();  // closes the triangle, at v_target
+    const l_poly = mesh.loop_create(); // continues the polygon, at v_anchor
+
+    mesh.loop_write_vertex(l_tri, v_target);
+    mesh.loop_write_face(l_tri, f_new);
+
+    mesh.loop_write_vertex(l_poly, v_anchor);
+    mesh.loop_write_face(l_poly, face);
+
+    bt_radial_loop_add(mesh, l_tri, e_new);
+    bt_radial_loop_add(mesh, l_poly, e_new);
+
+    const l_prev_prev = mesh.loop_read_prev(l_prev);
+
+    mesh.loop_write_face(l_prev, f_new);
+    mesh.loop_write_face(l_ear, f_new);
+
+    // triangle: l_prev -> l_ear -> l_tri
+    mesh.loop_write_next(l_prev, l_ear);
+    mesh.loop_write_prev(l_prev, l_tri);
+
+    mesh.loop_write_next(l_ear, l_tri);
+    mesh.loop_write_prev(l_ear, l_prev);
+
+    mesh.loop_write_next(l_tri, l_prev);
+    mesh.loop_write_prev(l_tri, l_ear);
+
+    mesh.face_write_loop(f_new, l_prev);
+    mesh.face_write_normal(f_new, normal, 0);
+
+    // remaining polygon: l_prev_prev -> l_poly -> l_next
+    mesh.loop_write_next(l_prev_prev, l_poly);
+
+    mesh.loop_write_prev(l_poly, l_prev_prev);
+    mesh.loop_write_next(l_poly, l_next);
+
+    mesh.loop_write_prev(l_next, l_poly);
+
+    mesh.face_write_loop(face, l_poly);
+
+    return l_poly;
+}
+
+/**
+ * Reset the corner index ring to `0 -> 1 -> ... -> corner_count - 1 -> 0`, the
+ * order the corners were collected in.
+ *
+ * @param {number} corner_count
+ */
+function reset_ring(corner_count) {
+    for (let i = 0; i < corner_count; i++) {
+        _ring_next[i] = (i + 1) % corner_count;
+        _ring_prev[i] = (i + corner_count - 1) % corner_count;
+    }
+}
+
+/**
+ * Remove index `i` from the corner ring.
+ *
+ * @param {number} i
+ */
+function unlink_ring(i) {
+    _ring_next[_ring_prev[i]] = _ring_next[i];
+    _ring_prev[_ring_next[i]] = _ring_prev[i];
+}
+
+/**
+ * Replay the emitted triangle list against a plain index ring without touching the
+ * mesh, checking that every triple is an ear of the ring at the moment it is
+ * reached. Only then is it safe to perform the same sequence as topology surgery.
+ *
+ * Ear clipping emits exactly this sequence for a simple polygon. Its recovery
+ * passes, which run for a self-intersecting projection, do not -- and half-applying
+ * those would leave the mesh structurally broken rather than merely untriangulated.
+ *
+ * @param {number} corner_count
+ * @param {number} triangle_count
+ * @returns {boolean}
+ */
+function is_ear_sequence(corner_count, triangle_count) {
+    if (triangle_count !== corner_count - 2) {
+        return false;
+    }
+
+    reset_ring(corner_count);
+
+    for (let t = 0; t < triangle_count; t++) {
+        const a = _triangles[t * 3];
+        const b = _triangles[t * 3 + 1];
+        const c = _triangles[t * 3 + 2];
+
+        const forward = _ring_prev[b] === a && _ring_next[b] === c;
+        const backward = _ring_prev[b] === c && _ring_next[b] === a;
+
+        if (!forward && !backward) {
+            return false;
+        }
+
+        unlink_ring(b);
+    }
+
+    return true;
+}
+
+/**
+ * Split one face of a {@link BinaryTopology} into triangles, in place.
+ *
+ * Handles any simple polygon, convex or not: the corner order is projected onto
+ * the plane of the face's own Newell normal and triangulated by
+ * {@link polygon3_triangulate}, whose decisions are exact. The resulting ear
+ * sequence is then replayed as topology surgery, so existing corners keep their
+ * identity (and any per-loop data) and only the diagonals are new. Each new face
+ * inherits the original's stored normal.
+ *
+ * Superseded the previous fan-from-the-first-corner implementation, which was
+ * correct only for convex faces and produced silently overlapping triangles for
+ * anything else.
+ *
+ * Nothing is changed, and `1` is returned, when the face is already a triangle,
+ * has no area (so no plane to project onto), or projects to a self-intersecting
+ * outline -- which is a non-planar or otherwise malformed face, and cannot be cut
+ * into ears at all. Leaving it whole is the honest outcome; half-cutting it would
+ * corrupt the mesh.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} face
+ * @returns {number} how many faces the input face became: `1` when it was left
+ *     untouched, otherwise the number of triangles it was split into
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_face_triangulate(mesh, face) {
+    const first_loop = mesh.face_read_loop(face);
+
+    if (first_loop === NULL_POINTER) {
+        return 1;
+    }
+
+    let corner_count = 0;
+    let iter = first_loop;
+
+    do {
+        corner_count++;
+        iter = mesh.loop_read_next(iter);
+    } while (iter !== first_loop);
+
+    if (corner_count < 4) {
+        return 1;
+    }
+
+    ensure_capacity(corner_count);
+
+    iter = first_loop;
+
+    for (let i = 0; i < corner_count; i++) {
+        _loops[i] = iter;
+
+        mesh.vertex_read_coordinate(_coordinate, 0, mesh.loop_read_vertex(iter));
+
+        _positions[i * 3] = _coordinate[0];
+        _positions[i * 3 + 1] = _coordinate[1];
+        _positions[i * 3 + 2] = _coordinate[2];
+
+        iter = mesh.loop_read_next(iter);
+    }
+
+    polygon3_compute_normal(_normal, 0, _positions, 0, corner_count);
+
+    if (_normal[0] === 0 && _normal[1] === 0 && _normal[2] === 0) {
+        // no area, so no plane to project onto
+        return 1;
+    }
+
+    _contour_ends[0] = corner_count;
+
+    const triangle_count = polygon3_triangulate(
+        _triangles, 0,
+        _positions, _contour_ends, 1,
+        _normal[0], _normal[1], _normal[2]
+    );
+
+    if (!is_ear_sequence(corner_count, triangle_count)) {
+        return 1;
+    }
+
+    mesh.face_read_normal(_stored_normal, 0, face);
+
+    // The last triple is the residual triangle, which is what `face` itself
+    // becomes; the other n-3 are cut off it one at a time.
+    //
+    // The ring is re-walked alongside the cuts because each cut hands the shrunken
+    // polygon a NEW corner in place of the ear's predecessor -- `_loops` has to
+    // follow that swap or the next cut would reach into the triangle just made.
+    reset_ring(corner_count);
+
+    for (let t = 0; t < triangle_count - 1; t++) {
+        const ear = _triangles[t * 3 + 1];
+        const predecessor = _ring_prev[ear];
+
+        _loops[predecessor] = cut_ear(mesh, face, _loops[ear], _stored_normal);
+
+        unlink_ring(ear);
+    }
+
+    return triangle_count;
+}

package/src/core/geom/3d/topology/struct/binary/query/bt_mesh_assert_valid.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Run {@link bt_mesh_validate} and throw if the mesh is structurally broken.
+ *
+ * Uses a real `throw` rather than `assert.*` on purpose: `assert.*` is stripped
+ * from production bundles, and this is the check a spec relies on to fail. A
+ * caller that wants the free-in-production behaviour should call
+ * {@link bt_mesh_validate} inside its own `assert.ok(...)`.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {string} [context] prepended to the message, e.g. the operation under test
+ * @throws {Error} when any structural invariant is broken
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_mesh_assert_valid(mesh: BinaryTopology, context?: string): void;
+//# sourceMappingURL=bt_mesh_assert_valid.d.ts.map

package/src/core/geom/3d/topology/struct/binary/query/bt_mesh_assert_valid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_mesh_assert_valid.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/query/bt_mesh_assert_valid.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;GAcG;AACH,qEANW,MAAM,QAwBhB"}

package/src/core/geom/3d/topology/struct/binary/query/bt_mesh_assert_valid.js

@@ -0,0 +1,44 @@
+import { bt_mesh_validate } from "./bt_mesh_validate.js";
+
+/**
+ * Maximum number of defects quoted in the thrown message. A corrupted cycle
+ * typically reports one defect per element on it, and a 10k-element dump helps
+ * nobody read the first one.
+ * @type {number}
+ */
+const REPORTED_DEFECT_LIMIT = 20;
+
+/**
+ * Run {@link bt_mesh_validate} and throw if the mesh is structurally broken.
+ *
+ * Uses a real `throw` rather than `assert.*` on purpose: `assert.*` is stripped
+ * from production bundles, and this is the check a spec relies on to fail. A
+ * caller that wants the free-in-production behaviour should call
+ * {@link bt_mesh_validate} inside its own `assert.ok(...)`.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {string} [context] prepended to the message, e.g. the operation under test
+ * @throws {Error} when any structural invariant is broken
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_mesh_assert_valid(mesh, context = "") {
+    const defects = bt_mesh_validate(mesh);
+
+    if (defects.length === 0) {
+        return;
+    }
+
+    const quoted = defects.slice(0, REPORTED_DEFECT_LIMIT);
+
+    const lines = quoted.map(d => `  [code ${d.code}] ${d.detail}`);
+
+    if (defects.length > quoted.length) {
+        lines.push(`  ... and ${defects.length - quoted.length} more`);
+    }
+
+    const prefix = context === "" ? "" : `${context}: `;
+
+    throw new Error(`${prefix}mesh has ${defects.length} structural defect(s)\n${lines.join("\n")}`);
+}

package/src/core/geom/3d/topology/struct/binary/query/bt_mesh_count_edge_faces.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Number of loops on an edge's radial cycle, i.e. how many faces use that edge.
+ *
+ * `0` is a wire edge, `1` a boundary edge, `2` a manifold interior edge, and `3`
+ * or more a non-manifold edge. {@link bt_edge_is_boundary} answers the `1` case
+ * on its own; this is the counting version the manifoldness queries need.
+ *
+ * The walk is bounded by the loop pool's size so a corrupted radial cycle cannot
+ * hang the caller. A cycle that long is itself broken -- run
+ * {@link bt_mesh_validate} to find out where.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id
+ * @returns {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_mesh_count_edge_faces(mesh: BinaryTopology, edge_id: number): number;
+//# sourceMappingURL=bt_mesh_count_edge_faces.d.ts.map

package/src/core/geom/3d/topology/struct/binary/query/bt_mesh_count_edge_faces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_mesh_count_edge_faces.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/query/bt_mesh_count_edge_faces.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,wEANW,MAAM,GACJ,MAAM,CAwBlB"}

package/src/core/geom/3d/topology/struct/binary/query/bt_mesh_count_edge_faces.js

@@ -0,0 +1,40 @@
+import { NULL_POINTER } from "../BinaryTopology.js";
+
+/**
+ * Number of loops on an edge's radial cycle, i.e. how many faces use that edge.
+ *
+ * `0` is a wire edge, `1` a boundary edge, `2` a manifold interior edge, and `3`
+ * or more a non-manifold edge. {@link bt_edge_is_boundary} answers the `1` case
+ * on its own; this is the counting version the manifoldness queries need.
+ *
+ * The walk is bounded by the loop pool's size so a corrupted radial cycle cannot
+ * hang the caller. A cycle that long is itself broken -- run
+ * {@link bt_mesh_validate} to find out where.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id
+ * @returns {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_mesh_count_edge_faces(mesh, edge_id) {
+    const start = mesh.edge_read_loop(edge_id);
+
+    if (start === NULL_POINTER) {
+        return 0;
+    }
+
+    const limit = mesh.loops.size;
+
+    let l = start;
+    let count = 0;
+
+    do {
+        count++;
+
+        l = mesh.loop_read_radial_next(l);
+    } while (l !== start && l !== NULL_POINTER && count <= limit);
+
+    return count;
+}