@woosh/meep-engine 2.168.1 → 2.169.0

package/src/core/collection/list/List.js

@@ -468,6 +468,40 @@ class List {
         return this.data.slice(start, end);
     }
 
+    /**
+     * Whether every element satisfies the condition. Vacuously true when empty,
+     * matching Array.prototype.every.
+     *
+     * @param {function(element:T):boolean} condition
+     * @returns {boolean}
+     */
+    every(condition) {
+        const l = this.length;
+        const data = this.data;
+
+        for (let i = 0; i < l; i++) {
+            if (!condition(data[i])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Iterate the list's elements, so `for...of` and spread work on it the way
+     * they already do on HashMap, HashSet and Deque.
+     *
+     * @returns {Iterator<T>}
+     */
+    * [Symbol.iterator]() {
+        const data = this.data;
+
+        for (let i = 0; i < this.length; i++) {
+            yield data[i];
+        }
+    }
+
     /**
      *
      * @param {function(element:T):boolean} condition

package/src/core/collection/list/SortedListProjection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SortedListProjection.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/list/SortedListProjection.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IACI;;;;OAIG;IACH,mBAHW,KAAK,CAAC,CAAC,qBACE,CAAC,QAAC,CAAC,KAAE,MAAM,EAoB9B;IAjBG;;;OAGG;IACH,OAFU,KAAK,CAAC,CAAC,CAEC;IAElB;;;OAGG;IACH,QAFU,KAAK,CAAC,CAAC,CAEO;IAExB;;;OAGG;IACH,mBAFmB,CAAC,QAAE,CAAC,KAAG,MAAM,CAEJ;IAGhC,aAIC;IAED,eAEC;IAED;;;OAGG;IACH,mBAFW,CAAC,QAMX;IAGD,cAUC;CAEJ;iBAhEgB,WAAW"}
+{"version":3,"file":"SortedListProjection.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/list/SortedListProjection.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IACI;;;;OAIG;IACH,mBAHW,KAAK,CAAC,CAAC,qBACE,CAAC,QAAC,CAAC,KAAE,MAAM,EAoB9B;IAjBG;;;OAGG;IACH,OAFU,KAAK,CAAC,CAAC,CAEC;IAElB;;;OAGG;IACH,QAFU,KAAK,CAAC,CAAC,CAEO;IAExB;;;OAGG;IACH,mBAFmB,CAAC,QAAE,CAAC,KAAG,MAAM,CAEJ;IAGhC,aAIC;IAED,eAEC;IAED;;;OAGG;IACH,mBAFW,CAAC,QASX;IAGD,cAUC;CAEJ;iBAnEgB,WAAW"}

package/src/core/collection/list/SortedListProjection.js

@@ -45,9 +45,12 @@ export class SortedListProjection {
      * @param {T} el
      */
     handleAddition(el) {
+        // binarySearchLowIndex returns the index of the largest element <= el,
+        // or -1 when el sorts below everything. The insertion point is one past
+        // that in both cases.
         const where = binarySearchLowIndex(this.output.data, el, this.comparator);
 
-        this.output.insert(where, el);
+        this.output.insert(where + 1, el);
     }
 
 

package/src/core/collection/map/BiMap.d.ts

@@ -14,11 +14,34 @@ export class BiMap<K, V> {
      */
     backward: Map<V, K>;
     /**
+     * Note the argument order: the pair is stored as value-then-key, which is
+     * how the only in-tree consumer (EncodingBinaryBuffer) calls it. The
+     * parameter names used to claim the opposite, which made every accessor
+     * below look inverted.
      *
+     * @param {V} value
      * @param {K} key
+     */
+    add(value: V, key: K): void;
+    /**
+     * Remove a pair by its value.
+     *
      * @param {V} value
+     * @returns {boolean} whether a pair was removed
+     */
+    deleteByValue(value: V): boolean;
+    /**
+     * Remove a pair by its key.
+     *
+     * @param {K} key
+     * @returns {boolean} whether a pair was removed
+     */
+    deleteByKey(key: K): boolean;
+    /**
+     * @returns {number}
      */
-    add(key: K, value: V): void;
+    get size(): number;
+    clear(): void;
     /**
      *
      * @param {V} value
@@ -32,6 +55,6 @@ export class BiMap<K, V> {
      */
     getValueByKey(address: K): V | undefined;
     get: (address: any) => any;
-    set: (key: any, value: any) => void;
+    set: (value: any, key: any) => void;
 }
 //# sourceMappingURL=BiMap.d.ts.map

package/src/core/collection/map/BiMap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BiMap.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/map/BiMap.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH;IAEI;;;OAGG;IACH,SAFU,IAAI,CAAC,EAAE,CAAC,CAAC,CAEC;IACpB;;;OAGG;IACH,UAFU,IAAI,CAAC,EAAE,CAAC,CAAC,CAEE;IAGrB;;;;OAIG;IACH,SAHW,CAAC,SACD,CAAC,QAKX;IAED;;;;OAIG;IACH,qBAHW,CAAC,GACC,CAAC,GAAC,SAAS,CAIvB;IAED;;;;OAIG;IACH,uBAHW,CAAC,GACC,CAAC,GAAC,SAAS,CAIvB;IAGL,2BAAmB;IACnB,oCAAmB;CAHlB"}
+{"version":3,"file":"BiMap.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/map/BiMap.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH;IAEI;;;OAGG;IACH,SAFU,IAAI,CAAC,EAAE,CAAC,CAAC,CAEC;IACpB;;;OAGG;IACH,UAFU,IAAI,CAAC,EAAE,CAAC,CAAC,CAEE;IAGrB;;;;;;;;OAQG;IACH,WAHW,CAAC,OACD,CAAC,QAKX;IAED;;;;;OAKG;IACH,qBAHW,CAAC,GACC,OAAO,CAanB;IAED;;;;;OAKG;IACH,iBAHW,CAAC,GACC,OAAO,CAanB;IAED;;OAEG;IACH,mBAEC;IAED,cAGC;IAED;;;;OAIG;IACH,qBAHW,CAAC,GACC,CAAC,GAAC,SAAS,CAIvB;IAED;;;;OAIG;IACH,uBAHW,CAAC,GACC,CAAC,GAAC,SAAS,CAIvB;IAGL,2BAAmB;IACnB,oCAAmB;CAHlB"}

package/src/core/collection/map/BiMap.js

@@ -17,13 +17,67 @@ export class BiMap {
 
 
     /**
+     * Note the argument order: the pair is stored as value-then-key, which is
+     * how the only in-tree consumer (EncodingBinaryBuffer) calls it. The
+     * parameter names used to claim the opposite, which made every accessor
+     * below look inverted.
      *
+     * @param {V} value
      * @param {K} key
+     */
+    add(value, key) {
+        this.forward.set(key, value);
+        this.backward.set(value, key);
+    }
+
+    /**
+     * Remove a pair by its value.
+     *
      * @param {V} value
+     * @returns {boolean} whether a pair was removed
+     */
+    deleteByValue(value) {
+        const key = this.backward.get(value);
+
+        if (key === undefined) {
+            return false;
+        }
+
+        this.backward.delete(value);
+        this.forward.delete(key);
+
+        return true;
+    }
+
+    /**
+     * Remove a pair by its key.
+     *
+     * @param {K} key
+     * @returns {boolean} whether a pair was removed
+     */
+    deleteByKey(key) {
+        const value = this.forward.get(key);
+
+        if (value === undefined) {
+            return false;
+        }
+
+        this.forward.delete(key);
+        this.backward.delete(value);
+
+        return true;
+    }
+
+    /**
+     * @returns {number}
      */
-    add(key, value) {
-        this.forward.set(value, key);
-        this.backward.set(key, value);
+    get size() {
+        return this.forward.size;
+    }
+
+    clear() {
+        this.forward.clear();
+        this.backward.clear();
     }
 
     /**

package/src/core/debug/matchers/IsAnything.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IsAnything.d.ts","sourceRoot":"","sources":["../../../../../src/core/debug/matchers/IsAnything.js"],"names":[],"mappings":"AAEA;IAGI,8BAIC;IAND,gBAAO;IAQP,uDAEC;IAED,mCAEC;CACJ;4BAlB2B,mBAAmB"}
+{"version":3,"file":"IsAnything.d.ts","sourceRoot":"","sources":["../../../../../src/core/debug/matchers/IsAnything.js"],"names":[],"mappings":"AAEA;IAGI,8BAIC;IAND,gBAAO;IAQP,uDAMC;IAED,mCAEC;CACJ;4BAtB2B,mBAAmB"}

package/src/core/debug/matchers/IsAnything.js

@@ -10,7 +10,11 @@ export class IsAnything extends BaseMatcher {
     }
 
     matches(item, mismatch_description) {
-        return false;
+        // "anything" accepts everything; it is the identity of a conjunction and
+        // the placeholder for an argument whose value does not matter. Returning
+        // false made it match nothing at all -- and, since nothing() is defined
+        // as not(anything()), made that match everything.
+        return true;
     }
 
     describeTo(description) {

package/src/core/events/signal/Signal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Signal.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/signal/Signal.js"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AACH;IACI;;;;OAIG;IACH,iBAAqB;IAErB;;;;OAIG;IACH,cAAU;IAEV;;;OAGG;IACH,YAFU,MAAM,CAED;IAWf;;;OAGG;IACH,yBAEC;IAfD;;;OAGG;IACH,sBAEC;IAYD;;;;OAIG;IACH,cAHW,MAAM;;KAAY,GAChB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM;;KAAY,GAChB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM;;KAAY,SAClB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM;;KAAY,GAChB,OAAO,CAInB;IAGD;;;;;OAKG;IACH,4CAFa,OAAO,CAcnB;IAED,aAEC;IAED,eAEC;IAED;;;OAGG;IACH,eAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,yCAQC;IAED;;;;OAIG;IACH,sCAOC;IA8BD;;;;;OAKG;IACH,oCAFa,OAAO,CA2CnB;IAED;;;;;;;;OAQG;IACH,kBAEC;IAqDD;;;;;;;;;;;;;;OAcG;IACH,WAZY,QAAQ,EAAE,CAAC,CAkBtB;IAED;;;OAGG;IACH,+BA2CC;IAGD;;;OAGG;IACH,4BA6CC;IAED;;;;OAIG;IACH,sCA4CC;IAED;;;;OAIG;IACH,4CA2CC;IAED;;;;;OAKG;IACH,oDA2CC;IAED;;;;;;OAMG;IACH,4DA2CC;IAED;;;;;;;OAOG;IACH,oEA2CC;IAED;;;;;;;;OAQG;IACH,4EA2CC;IAED;;;;;;;;;;OAUG;IACH,4FA2CC;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,MAAM,CAalB;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB"}
+{"version":3,"file":"Signal.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/signal/Signal.js"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AACH;IACI;;;;OAIG;IACH,iBAAqB;IAErB;;;;OAIG;IACH,cAAU;IAEV;;;OAGG;IACH,YAFU,MAAM,CAED;IAWf;;;OAGG;IACH,yBAEC;IAfD;;;OAGG;IACH,sBAEC;IAYD;;;;OAIG;IACH,cAHW,MAAM;;KAAY,GAChB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM;;KAAY,GAChB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM;;KAAY,SAClB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM;;KAAY,GAChB,OAAO,CAInB;IAGD;;;;;OAKG;IACH,4CAFa,OAAO,CAcnB;IAED,aAEC;IAED,eAEC;IAED;;;OAGG;IACH,eAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,yCAQC;IAED;;;;OAIG;IACH,sCAOC;IA8BD;;;;;OAKG;IACH,oCAFa,OAAO,CA2CnB;IAED;;;;;;;;OAQG;IACH,kBAEC;IAqDD;;;;;;;;;;;;;;OAcG;IACH,WAZY,QAAQ,EAAE,CAAC,CAkBtB;IAED;;;OAGG;IACH,+BA2CC;IAGD;;;OAGG;IACH,4BA6CC;IAED;;;;OAIG;IACH,sCA4CC;IAED;;;;OAIG;IACH,4CA2CC;IAED;;;;;OAKG;IACH,oDA2CC;IAED;;;;;;OAMG;IACH,4DA2CC;IAED;;;;;;;OAOG;IACH,oEA2CC;IAED;;;;;;;;OAQG;IACH,4EA2CC;IAED;;;;;;;;;;OAUG;IACH,4FA2CC;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,MAAM,CAelB;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB"}

package/src/core/events/signal/Signal.js

@@ -798,7 +798,9 @@ export class Signal {
         const result = new Signal();
 
         function handler() {
-            result.dispatch(arguments);
+            // spread: dispatch takes varargs, so passing the arguments object
+            // forwards it as a single argument to every subscriber
+            result.dispatch(...arguments);
         }
 
         this.add(handler);

package/src/core/geom/2d/polygon/TRIANGULATION_DESIGN.md

@@ -0,0 +1,433 @@
+# Polygon triangulation — design note
+
+Status: **LANDED** · 2026-08-01
+Follows [`../../MANIFOLD_COMPARISON_2026_08_01.md`](../../MANIFOLD_COMPARISON_2026_08_01.md) §4.1.
+
+> **Outcome.** Built as designed. What it cost, and what it turned up, is in §7 —
+> including two defects in *existing* meep primitives that the work exposed and
+> that are now fixed, and one place where the plan above was simply wrong.
+
+meep has no general polygon triangulator. This note records the research behind
+the one being added: the algorithm choice, and — for every component it needs —
+the answer to *"does meep already have this, and is this how meep does it?"*
+
+---
+
+## 1. What the callers actually need
+
+Surveyed every site in meep + app that triangulates or wants to:
+
+| Site | Today | n | Holes | Needs |
+| --- | --- | --- | --- | --- |
+| [`bt_face_triangulate`](../../3d/topology/struct/binary/io/face/bt_face_triangulate.js) | fan from the first loop vertex, documented as convex-only | 4–12 | no | correct output for concave faces |
+| [`bt_mesh_triangulate`](../../3d/topology/struct/binary/io/bt_mesh_triangulate.js) | applies the above to every face unconditionally | — | no | same |
+| [`bt_mesh_close_boundary_holes`](../../3d/topology/struct/binary/io/bt_mesh_close_boundary_holes.js) | Steiner vertex at the loop centroid + fan | 3–500 | no | a fill without a Steiner point, for non-convex loops |
+| [`navmesh_build_topology`](../../../../engine/navigation/mesh/build/navmesh_build_topology.js):97,108 | *explicit TODO*: "identify flat areas and re-triangulate them to remove unnecessary triangles" | 10³–10⁴ | **yes** (obstacle footprints) | the general case |
+| [`clip_soup_against_overhangs`](../../../../engine/navigation/mesh/build/clip_soup_against_overhangs.js):378 | fan, over convex pieces from `polygon2_clip_halfplane` | ≤ 8 | no | **correct as-is** — every piece is a half-plane intersection, hence convex. Listed only so nobody "fixes" it. |
+| future: `Extrude` / `Revolve` / `Slice` / `Project`, glyph outlines (`opentype.js` is already a dependency), cross-sections | — | any | yes | the general case |
+
+Two conclusions:
+
+1. The dominant call is **tiny n, no holes** (`bt_face_triangulate`). The
+   asymptotics of the algorithm barely matter there; correctness and a small
+   constant do.
+2. The demanding call is **large n with holes** (navmesh flat regions). That one
+   is offline.
+
+Nothing in the survey needs an incremental/dynamic triangulation, and nothing
+needs Steiner points. That rules a lot of design space out immediately.
+
+---
+
+## 2. Algorithm choice
+
+### Candidates
+
+| | complexity | status structure needed | predicate set | output |
+| --- | --- | --- | --- | --- |
+| **Monotone decomposition sweep** (Lee–Preparata; what manifold uses) | O(n log n) | ordered dictionary keyed on "edge x at sweep y" | orient2d **+ inexact edge/horizontal-line comparisons** | arbitrary order |
+| **Ear clipping** (earcut-family) | O(n²), ~O(n log n) with z-order | none — a doubly-linked ring | **orient2d only** | ears, in cut order |
+| **Constrained Delaunay** | O(n log n) | ordered dictionary + flip machinery | orient2d + incircle | best quality |
+| **Seidel trapezoidation** | O(n log* n) | trapezoid DAG | orient2d | arbitrary order |
+
+### Decision: ear clipping, with exact `orient2d`
+
+Three reasons, in order of weight.
+
+**(a) meep already ships the one predicate ear clipping needs, and nothing
+else's predicate set is satisfiable.** `robust-predicates@3.0.2` is a
+first-class dependency (`package.json`), already whitelisted in the root
+`jest.conf.json` `transformIgnorePatterns`, and already used in four places —
+[`orient2d_indexed.js`](../convex-hull/orient2d_indexed.js) for the 2D hull,
+[`orient3d_robust.js`](../../3d/plane/orient3d_robust.js),
+[`in_sphere3d_robust.js`](../../3d/sphere/in_sphere3d_robust.js),
+[`TetrahedralMesh.js`](../../3d/tetrahedra/TetrahedralMesh.js).
+
+Every decision an ear clipper makes reduces to `orient2d`:
+
+- *is vertex v convex?* → `orient2d(prev, v, next)`
+- *is point p inside triangle (a,b,c)?* → three `orient2d` calls
+- *is the candidate diagonal locally valid?* → two `orient2d` calls
+
+So the whole algorithm can be made **exact**, with no epsilon anywhere in the
+combinatorial decisions. That is not true of the sweep: its status structure
+compares edges by their x-coordinate at the current sweep y, which is a
+division. You can reformulate it into orient2d tests, but the reformulation is
+subtle and a comparator that is merely *nearly* consistent corrupts an ordered
+dictionary silently.
+
+**(b) meep has no ordered dictionary, and adding one is the wrong first move.**
+`core/collection` has `BinaryHeap`, `FibonacciHeap`, `IndexedFloatMinHeap`,
+`Uint32Heap`, `Uint32Map`, `PairUint32Map`, `HashMap`, `HashSet`, `RingBuffer`,
+`Deque`, `union_find`, `RowFirstTable`, `binarySearchLowIndex/HighIndex` — no
+balanced BST, no skip list, no ordered set. The sweep needs one. Building a
+red-black tree *and* a sweep triangulator on top of it, in one change, means the
+first bug is ambiguous between the two. Ear clipping needs no new collection at
+all: its ring is two `Uint32Array`s.
+
+**(c) Ear clipping's output is directly consumable by meep's topology surgery.**
+`bt_face_triangulate`'s existing primitive is "cut triangle (l_prev, l_curr,
+l_next) off the face by inserting one edge" — that *is* an ear cut. Today it
+always picks the first ear whether or not it is one. The fix is to pick a real
+ear. A sweep would emit an arbitrary triangle set that then has to be
+re-sequenced into diagonal insertions.
+
+### What we give up, and the upgrade path
+
+Ear clipping is O(n²) in the worst case and produces sliver-heavy
+triangulations. Both are accepted, explicitly:
+
+- **Time.** The z-order acceleration (§3.6) makes the point-in-ear test local
+  rather than global, which is what turns the practical cost into ~O(n log n).
+  Per [`feedback_reuse_over_micro_opt`], the right response if this ever shows
+  up in a profile is a measurement, not a pre-emptive rewrite. The bench hook is
+  the navmesh flat-region path, which is the only large-n caller and is offline.
+- **Quality.** Deliberately *not* solved inside the triangulator. Adding a
+  "quality mode" flag would be exactly the `X = null means auto` sentinel
+  pattern that is rejected in this codebase ([`feedback_uniform_flow`]). The
+  triangulator has one behaviour: produce a valid triangulation. A caller that
+  wants Delaunay quality gets a **separate** `tri2_mesh_flip_to_delaunay` pass
+  (§6) built on `incircle` from the same `robust-predicates` package — the exact
+  2D analogue of the existing `in_sphere3d_robust.js`, and independently
+  testable.
+
+---
+
+## 3. Component-by-component meep audit
+
+For each piece: *does meep already have it? is this how meep does it?*
+
+### 3.1 Exact orientation predicate — **reuse, verbatim**
+
+`orient2d` from `robust-predicates`, wrapped the way meep already wraps it.
+[`orient2d_indexed.js`](../convex-hull/orient2d_indexed.js) is the existing
+precedent: it takes a flat `points` array plus three *indices*, which is exactly
+the call shape the triangulator wants (the ring stores point indices). **Reused
+unchanged.** No new vendor import site — per [`feedback_confine_vendor_imports`]
+the `robust-predicates` import stays inside the two existing wrapper files.
+
+### 3.2 The vertex ring — **BinaryTopology-flavoured, not object nodes**
+
+earcut uses a linked list of JS objects (`{i, x, y, prev, next, z, prevZ,
+nextZ, steiner}`). That is not how meep does it. Every comparable meep
+structure is flat typed arrays with integer handles and a `NULL_POINTER`
+sentinel — `BinaryElementPool`, `BinaryTopology`, `RowFirstTable`, `bvh8`.
+
+So the ring is:
+
+```
+ring_next  : Uint32Array   // node -> node
+ring_prev  : Uint32Array   // node -> node
+ring_point : Uint32Array   // node -> index into `points`
+ring_z     : Uint32Array   // node -> 2D Morton code (§3.6)
+ring_zprev : Uint32Array
+ring_znext : Uint32Array
+```
+
+Node ids are dense `[0, total_vertex_count)`; removal is unlinking, never
+compaction. `NULL_POINTER = 0xFFFFFFFF` is imported from
+[`BinaryTopology.js`](../../3d/topology/struct/binary/BinaryTopology.js) rather
+than redeclared — it is already the codebase-wide sentinel.
+
+Buffers are module-static and grown on demand, matching the
+`_cur` / `_tmp` / `_side` + `ensure_capacity` pattern in
+[`clip_soup_against_overhangs.js`](../../../../engine/navigation/mesh/build/clip_soup_against_overhangs.js).
+The triangulator is therefore **not re-entrant**, same as
+[`bt_mesh_simplify_by_error`](../../3d/topology/struct/binary/io/bt_mesh_simplify_by_error.js)
+(whose `_degree` / `_vboundary` caches are module-level and documented as such).
+That is stated in the JSDoc, not guarded against.
+
+### 3.3 Signed area / winding — **reuse**
+
+[`polygon2_signed_area`](polygon2_signed_area.js) already exists and already
+handles the "does the contour repeat its first point" case. Contour orientation
+(outer CCW, holes CW) is decided with it. [`tri2_signed_area`](../triangle/tri2_signed_area.js)
+is reused by the tests for area conservation.
+
+### 3.4 Hole elimination — **bridging, no new structure**
+
+Holes are eliminated the standard way: for each hole, find the outer-contour
+vertex that is mutually visible from the hole's rightmost vertex, and splice the
+hole into the outer ring through a doubled bridge edge. Requires only:
+
+- a ray cast to the right from the hole's rightmost point against outer edges —
+  plain arithmetic, no structure;
+- a visibility tie-break — `orient2d` again;
+- sorting the holes by their rightmost x so that bridges never cross.
+
+**Sorting**: meep has `array_sort_quick`, `array_quick_sort_by_comparator`,
+`array_quick_sort_by_lookup_map`, `array_quick_sort_by_lookup_uint`. Hole count
+is small (typically < 100); the comparator variant is used rather than a
+hand-rolled sort, per [`feedback_reuse_over_micro_opt`].
+
+### 3.5 Degenerate-input policy — **sentinel return, never throw, never swallow**
+
+Real input is not ε-valid: welding produces self-touching contours, imported
+geometry has duplicate and collinear points, navmesh footprints can be zero-area.
+[`feedback_no_silent_catch`] says a function with a legitimate "can be expected
+to fail" mode returns a sentinel; [`feedback_no_defensive_guards`] says do not
+guard can't-happen conditions.
+
+Applied:
+
+- **Preconditions** (finite coordinates, `contour_count >= 1`, each contour
+  `>= 3` vertices, `contour_ends` non-decreasing) are `assert.*` — free in
+  production ([`feedback_assert_stripped`]) and documented in JSDoc.
+- **Expected failure** (the polygon is self-intersecting / partially
+  degenerate and cannot be fully triangulated) is reported by the **return
+  value**: the number of triangles actually written. A caller that cares
+  compares it against the exact expected count `V + 2H − 2`, or measures area
+  conservation with the companion `polygon2_triangulation_deviation`.
+- **No throw, no try/catch, no silent zero.** A partially-triangulated result is
+  still the best available answer and the caller is told how much it got.
+
+Three recovery tiers are implemented, in this order, because without them the
+behaviour on real welded meshes is "returns almost nothing":
+
+1. plain ear clipping;
+2. *cure local intersections* — when no ear is found, remove a vertex whose
+   incident edges cross a neighbour's, then retry;
+3. *split* — find a pair of non-adjacent ring vertices whose diagonal is valid,
+   cut the ring in two, and triangulate each half.
+
+These are not bandaids ([`feedback_correctness_no_bandaid`]): they are the
+defined behaviour for input outside the ε-valid contract, each has its own
+tests, and none of them weakens an assertion about valid input.
+
+### 3.6 Z-order acceleration — **reuse `split_by_2`**
+
+The point-in-ear test is the hot loop. earcut restricts it to points whose 2D
+Morton code lies in the ear's bounding-box code range. meep already has
+[`split_by_2`](../../../binary/split_by_2.js) (bit interleave, libmorton-derived)
+and already uses it for 2D Morton in `SpatialHashGrid` and `StaticR2Tree`, plus
+a full `v3_morton_encode*` family under [`../../3d/morton/`](../../3d/morton/).
+There is no `v2_morton_encode` file, so one is added next to `split_by_2` rather
+than inlining the interleave — filling the gap in the existing family instead of
+growing a private copy.
+
+Acceleration is enabled above a vertex-count threshold. This is *not* a mode
+flag on the public API — it is an internal branch on `n`, invisible to callers,
+and both paths are asserted to produce the same triangle count in the tests.
+
+### 3.7 3D → 2D projection — **axis-aligned drop, never a rotation**
+
+Faces are 3D. The projection to 2D must not perturb coordinates, or the exact
+predicates stop being exact for the *original* geometry. So: drop the axis with
+the largest |normal| component and keep the other two verbatim, flipping the
+winding when that component is negative. Same choice manifold makes
+(`GetAxisAlignedProjection`).
+
+meep has [`v3_orthonormal_matrix_from_normal`](../../vec3/v3_orthonormal_matrix_from_normal.js)
+— used by `clip_soup_against_overhangs` — but that is a *rotation*, and rotating
+introduces rounding into every coordinate. It is deliberately **not** used here.
+The axis-drop helper is new (`v3_project_to_dominant_plane`), which is the
+honest answer to "does meep already have this": it has a related thing that is
+wrong for this job.
+
+### 3.8 Output buffer convention — **`(result, result_offset, …)` first**
+
+Matches the bvh3 query convention recorded in [`project_bvh3_review_2026_06`]
+and the `support(result, result_offset, …)` / `vertex_read_coordinate(out, offset, v)`
+shape used throughout `AbstractShape3D` and `BinaryTopology`.
+
+---
+
+## 4. API
+
+One general function. A single-contour caller passes `contour_count = 1`; there
+is no convenience overload, because two entry points for one operation is the
+kind of API surface [`feedback_uniform_flow`] rejects.
+
+```js
+/**
+ * @param {Uint32Array} result           3 point-indices per triangle
+ * @param {number}      result_offset
+ * @param {ArrayLike<number>} points     flat (x, y), stride 2
+ * @param {ArrayLike<number>} contour_ends  exclusive end vertex index per contour
+ * @param {number}      contour_count
+ * @returns {number} triangles written; < V + 2H - 2 means the input could not be
+ *                   fully triangulated
+ */
+polygon2_triangulate(result, result_offset, points, contour_ends, contour_count)
+```
+
+`contour_ends` rather than earcut's `holeIndices` (contour starts) so that
+contour `i` is uniformly `[i === 0 ? 0 : ends[i - 1], ends[i])` — no special case
+for the first contour.
+
+Contour 0 is the outer boundary; 1..n are holes. Winding is **not** a
+precondition: the implementation normalises it from `polygon2_signed_area`, so
+callers cannot get it subtly wrong. (This is the one place where inferring
+rather than demanding is right: winding is derivable from the data, so demanding
+it would be redundant state the caller can contradict.)
+
+Companions:
+
+```js
+polygon2_triangulation_deviation(result, result_offset, triangle_count, points, contour_ends, contour_count)
+```
+→ relative area error `|Σ|tri| − |polygon||/|polygon|`; `0` for a perfect
+triangulation. Used by the tests as the primary invariant and available to
+callers that need to validate untrusted input.
+
+```js
+polygon3_triangulate(result, result_offset, points3, contour_ends, contour_count, nx, ny, nz)
+```
+→ projects with §3.7 and delegates. This is what `bt_face_triangulate` calls.
+
+---
+
+## 5. Testing plan
+
+Per house rules: black-box, no mocks or spies, no assertions on call counts or
+internal paths, verbose and explicit over test frameworks, reproducible, nothing
+vacuous.
+
+The triangulator is unusually well suited to **invariant** testing, which is the
+only kind that is honest here — asserting a specific triangle list would bake in
+one valid answer out of many and break on any legitimate change.
+
+Invariants asserted for every case:
+
+1. **Triangle count** is exactly `V + 2H − 2`.
+2. **Area conservation** — `Σ|signed area of each output triangle|` equals
+   `|polygon area − Σ hole areas|` to a tight relative tolerance.
+3. **Consistent orientation** — every output triangle is CCW.
+4. **No overlap** — pairwise, for small cases: triangle interiors are disjoint
+   (sampled at each triangle's incenter, which must lie in exactly one).
+5. **Index validity** — every emitted index is in `[0, V)`.
+6. **Coverage** — a grid of sample points inside the polygon and outside every
+   hole is covered by exactly one triangle.
+
+Case families:
+
+- squares, L-shapes, combs, spirals, stars (concave), zero-area spikes;
+- squares with 1 / 2 / nested holes; a hole touching the boundary at a vertex;
+- collinear runs; duplicate consecutive points; a contour that repeats its first
+  point; a hole wound the "wrong" way (must still work — §4);
+- the two accelerated/non-accelerated paths agreeing on a large input;
+- **corpus** — `polygon2_triangulate.corpus.js`, a checked-in list of inputs
+  that have ever failed, replayed as tests. Manifold's most transferable
+  practice: `test/polygons/polygon_corpus.txt` is 2.9 MB of exactly this.
+- **fuzz** — a *seeded* generator (`seededRandom` from `core/math/random`, so
+  every failure is reproducible from its seed) producing random contours,
+  asserting the invariants that survive on invalid input: never throws, never
+  hangs, never emits an out-of-range index, and the deviation is reported
+  honestly.
+
+---
+
+## 6. What landed
+
+| File | What |
+| --- | --- |
+| [`polygon2_triangulate.js`](polygon2_triangulate.js) | the triangulator |
+| [`polygon2_triangulation_deviation.js`](polygon2_triangulation_deviation.js) | relative area error of a result |
+| [`polygon2_is_counter_clockwise.js`](polygon2_is_counter_clockwise.js) | exact winding test (see §7.1) |
+| [`../v2_morton_encode.js`](../v2_morton_encode.js) | 2D Morton code, filling the gap next to `v3_morton_encode*` |
+| [`../../3d/polygon/polygon3_triangulate.js`](../../3d/polygon/polygon3_triangulate.js) | planar 3D adapter, axis-aligned projection |
+| [`../../3d/polygon/polygon3_compute_normal.js`](../../3d/polygon/polygon3_compute_normal.js) | Newell normal for an arbitrary polygon |
+| [`polygon2_triangulate.corpus.js`](polygon2_triangulate.corpus.js) | recorded failures, replayed as tests |
+| [`bt_face_triangulate.js`](../../3d/topology/struct/binary/io/face/bt_face_triangulate.js) | rewritten onto the triangulator |
+
+Also fixed, because the work depended on them and they were wrong: §7.1 and §7.2.
+
+## 7. What the work turned up
+
+### 7.1 The plan's winding test was not exact — `polygon2_signed_area` cannot be
+
+The design above says every combinatorial decision is exact. The first
+implementation broke that promise in its very first step: it picked each
+contour's winding from `polygon2_signed_area`, a shoelace sum. A shoelace sum
+adds terms of magnitude `O(|p|²)` to reach an answer that is the area, so its
+*sign* is rounding noise whenever the polygon is small relative to its distance
+from the origin. A 1e-9-sided square at (1, 1) has a true area of 1e-18 against
+per-term rounding of ~1e-16. The ring came out backwards, every corner looked
+reflex, and the triangulator returned nothing.
+
+Fixed by [`polygon2_is_counter_clockwise`](polygon2_is_counter_clockwise.js):
+one exact `orient2d` at the contour's lexicographically smallest vertex, which
+is necessarily on the convex hull, so the turn there is the contour's own. No
+summation, no cancellation, magnitude-independent.
+
+The lesson generalises: **use the signed area when you want the area, and the
+predicate when you want the winding.** They are not the same question.
+
+### 7.2 Two existing meep primitives had the same cancellation defect
+
+Both were on the path of the new code, so both had to be right.
+
+- **`tri2_signed_area`** computed the expanded determinant of absolute
+  coordinates. Its consumers are mostly *sign* tests — the Polyanya funnel
+  (`bt_mesh_face_find_path_polyanya`), the atlas parameterisation validity check
+  — which is the worst possible exposure: a cancelled sign is a wrong path or a
+  wrongly-rejected chart, not a slightly wrong number. Now differences-first.
+- **`polygon2_signed_area`** had the same shape and now subtracts the first
+  vertex before accumulating. As a bonus the special-case closing term
+  disappeared: both edges at the reference vertex contribute zero, so the
+  open-vs-closed contour branch is gone.
+
+Neither changes any API. Both are strictly better conditioned, and both now have
+specs that fail on the old implementation.
+
+This is the same defect class as `tri3_compute_signed_volume` in
+[the manifold comparison](../../MANIFOLD_COMPARISON_2026_08_01.md) §3.1, which
+remains open.
+
+### 7.3 `V + 2H − 2` is an upper bound, not an equality
+
+The first spec asserted equality and failed on two hole cases. The triangulator
+was right: bridging a hole can leave three collinear corners, and absorbing them
+is better output than emitting a zero-area triangle. Area conservation plus
+"every input vertex is used" is the honest invariant; the exact count is asserted
+only for hole-free shapes whose vertices are all genuine corners.
+
+### 7.4 The sentinel had to be propagated, not assumed away
+
+`filter_points` returns a collapsed-ring sentinel. The recovery pass took it as a
+node id and walked it — an infinite loop on a 20-point coarse-grid soup (corpus
+entry 2). Fixed by making the recovery pass accept and propagate the sentinel,
+and stop once the ring holds fewer than three nodes. That second condition is a
+genuine termination condition, not a guard: with fewer than three nodes there is
+no triangle to cure and nothing left to walk.
+
+### 7.5 Replaying an ear sequence as topology surgery needs the ring, not the handles
+
+`bt_face_triangulate` cuts each ear by moving two existing corners onto the new
+face and giving the shrunken polygon a *fresh* corner in the ear's predecessor's
+place. The first version replayed the triangulator's output against the corner
+handles collected up front, which go stale the moment a cut happens — producing
+2-corner faces. It now walks the same index ring the dry run uses and swaps each
+replaced handle as it goes.
+
+## 8. Deliberately out of scope
+
+- **Delaunay quality** (`tri2_mesh_flip_to_delaunay` via `incircle`). Separate
+  pass, separate change; the note above explains why it must not be a flag.
+- **Steiner points / refinement.** No caller needs them.
+- **2D polygon boolean and offsetting.** Different problem, much larger; §4.2 of
+  the comparison doc.
+- **`bt_mesh_close_boundary_holes` rework.** It currently adds a centroid
+  Steiner vertex, which is a *different* output (n triangles instead of n−2) and
+  is what its tetrahedralisation consumer wants. Switching it is a behaviour
+  change with its own consumer study, tracked separately.