@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,433 +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.
+# 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.