@woosh/meep-engine 2.168.0 → 2.169.0

package/src/core/geom/MANIFOLD_COMPARISON_2026_08_01.md

@@ -0,0 +1,554 @@
+# meep `core/geom` vs. `elalish/manifold` — comparative review
+
+Date: 2026-08-01 · Reviewer: Claude (Opus 5) · Upstream reviewed: `elalish/manifold@master`
+(`src/`, `include/manifold/`, `test/`, `bindings/wasm/`)
+
+Motivating question: *an agent working on an offline computational-geometry task
+abandoned meep and pulled in `manifold` instead. Why, and what would make that
+unlikely next time?* Performance was **not** the reason.
+
+---
+
+## 0. TL;DR
+
+**meep and manifold are not competitors — they barely overlap.** manifold is a
+*solid modelling kernel*: its entire reason to exist is "given two watertight
+solids, produce a third watertight solid", plus the ~40 operations that orbit
+that guarantee. meep's `core/geom` is a *geometry-processing and simulation
+toolbox*: half-edge topology surgery, BVHs, decimation, UV atlasing, LSCM/BFF
+parameterisation, tetrahedralisation, navmesh, collision shapes.
+
+The agent did not switch because meep's geometry was worse. It switched because
+**meep has no solid modelling at all** — no mesh boolean, no polygon boolean,
+no offset, no convex hull, no isosurfacing, no extrude/revolve, and no
+manifoldness contract. Any task phrased as "subtract this from that and give me
+a clean mesh" has a zero-line answer in manifold and no answer at all in meep.
+
+Concretely, the review found:
+
+- **3 gaps that alone justify reaching for another library** (§4.1–4.3): mesh
+  boolean, 2D polygon boolean/offset, and general polygon triangulation.
+- **6 further "A and C but not B" gaps** (§4.4) where meep has the hard parts
+  either side of a missing cheap middle — most glaringly, a full SDF shape
+  algebra (`AbstractShape3D.signed_distance_at_point`, `UnionShape3D`) with
+  **no way to turn a field into a mesh**, and no `IntersectionShape3D` /
+  `DifferenceShape3D` to go with `UnionShape3D`.
+- **1 hard numerical defect with a reproduced failure** (§3.1): meep's signed
+  volume returns `256` for a unit cube at `(1e6, 1e6, 1e6)` and `−262144` at
+  `1e7`. Correct answer: `1`.
+- **A missing structural invariant checker** for `BinaryTopology` (§3.4), which
+  is the single biggest reason manifold *feels* trustworthy and meep's topology
+  layer does not.
+
+Where meep leads, it leads decisively (§5): UV atlasing, parameterisation,
+BVH8, geodesic/navmesh queries, tetrahedralisation, physics shapes. manifold has
+none of it and never will.
+
+---
+
+## 1. Why the agent switched — the direct answer
+
+For an offline computational-geometry task, the decision tree an agent walks is
+roughly:
+
+| Question the task asks | manifold | meep |
+| --- | --- | --- |
+| "union / subtract / intersect these meshes" | `a + b`, `a - b`, `a ^ b` | — |
+| "give me the result as a *valid* mesh" | guaranteed manifold, or `Status()` says why not | no manifoldness contract anywhere |
+| "extrude this outline / revolve this profile" | `Manifold::Extrude` / `Revolve` | — |
+| "triangulate this polygon with holes" | `Triangulate(polys, ε)` | — (only a convex fan, §3.3) |
+| "offset this outline by 2mm, round joins" | `CrossSection::Offset` | — |
+| "convex hull of these points" | `Manifold::Hull(pts)` | — (`ConvexHullShape3D` *consumes* a hull, does not compute one) |
+| "mesh this SDF" | `Manifold::LevelSet(sdf, bounds, edgeLength)` | — (can voxelize, cannot isosurface) |
+| "what is its volume / genus / is it closed?" | `Volume()`, `Genus()`, `Status()` | volume only, and see §3.1 |
+| "slice it at z=0 / project its silhouette" | `Slice()`, `Project()` | — |
+
+That is nine consecutive misses on the operations that define the domain. The
+switch was not a judgement call; it was the absence of an alternative.
+
+The second-order reason is the **contract**. manifold's central promise is that
+every `Manifold` value is a closed, oriented, ε-valid 2-manifold, or is empty
+with an `Error` explaining why. Every operation preserves that. An agent can
+chain twenty operations and trust the twentieth. meep's `BinaryTopology` is a
+BMesh-style structure that *permits* wire edges, n-gons, non-manifold radial
+cycles and pinched vertices by design — which is right for a modelling/authoring
+substrate, but means no operation can state a post-condition, and there is no
+validator to check one (§3.4).
+
+---
+
+## 2. Capability map
+
+Legend: **✔** present and comparable · **~** partial / narrower · **✘** absent.
+
+### 2.1 Solid modelling (manifold's core)
+
+| manifold | meep | Notes |
+| --- | --- | --- |
+| `Boolean` / `BatchBoolean` (`src/boolean3.cpp`, `boolean_result.cpp`) | ✘ | The flagship. Smith & Dodgson robust boolean over a halfedge mesh. |
+| `Split`, `SplitByPlane`, `TrimByPlane` | ✘ | `clip_soup_against_overhangs.js` clips a *soup* against a height field only. |
+| `MinkowskiSum` / `MinkowskiDifference` (`src/minkowski.cpp`) | ✘ | meep has `gjk/minkowski_support.js` — the support function only, not the sum. |
+| `Hull()` (3D quickhull, `src/quickhull.cpp`) | ✘ | See §4.3. |
+| `Decompose()` / `Compose()` (connected components) | ~ | `bt_mesh_compute_face_islands`, `bt_mesh_face_decouple_islands` cover component splitting on a topology mesh. |
+| `LevelSet` (marching tetrahedra over an SDF, `src/sdf.cpp`) | ✘ | See §4.4-a. |
+| `Extrude`, `Revolve` | ✘ | `TubeX` sweeps a circle along a path — not a general profile extrude. |
+| `Slice`, `Project` (`src/face_op.cpp`) | ✘ | |
+| `Cube/Sphere/Cylinder/Tetrahedron` as *solids* | ~ | meep has these as `AbstractShape3D` colliders and as three.js geometry, not as topology solids. |
+| `Genus()`, `IsConvex()`, `Status()/Error` | ✘ | `mesh_convex_hull.js` has a bespoke convexity test for tet meshes. |
+| `Volume()`, `SurfaceArea()` | ~ | Present but see §3.1/§3.2. |
+| `MinGap(other, searchLength)` | ✘ | Distance queries exist per-primitive; no mesh-mesh minimum gap. |
+| `RayCast`, `WindingNumber` | ~ | Raycast: **meep is ahead** (bvh2/bvh3/bvh8, `refine_ray_hit`). Winding number: ✘. |
+| `epsilon_` / `tolerance_` model, `SetTolerance`, `Simplify(tol)` | ~ | meep passes ad-hoc `eps` per function; no per-mesh tolerance carried with the data. See §4.5. |
+
+### 2.2 2D
+
+| manifold | meep | Notes |
+| --- | --- | --- |
+| `CrossSection` boolean (`src/boolean2*.cpp` — own sweep-line engine, replaced Clipper2) | ✘ | meep has `polygon2_clip_halfplane` / `_axis_halfplane` only. |
+| `CrossSection::Offset` (Square/Round/Miter joins) | ✘ | See §4.2. |
+| `CrossSection::Hull` | ✔ | `convex_hull_monotone_2d`, `convex_hull_jarvis_2d`, plus fixed-count variants meep has and manifold lacks. |
+| `TriangulateIdx` (monotone sweep, arbitrary hole nesting) | ✘ | See §3.3/§4.1. |
+| `Simplify` (2D contour) | ✘ | |
+| `Rect`, `Area`, `Bounds`, `Decompose` | ~ | `Rectangle`, `compute_polygon_area_2d`, `polygon2_signed_area` cover the scalars. |
+
+### 2.3 Mesh processing
+
+| Area | manifold | meep | Verdict |
+| --- | --- | --- | --- |
+| Halfedge structure | compact triangle-only halfedge (`src/impl.h`) | BMesh-style vertex/edge/loop/face pools with disk + radial cycles (`BinaryTopology.js`, 984 lines) | **meep is more general** (n-gons, wire edges, per-element data pools); manifold is more constrained *on purpose*. |
+| Decimation / simplify | `SimplifyTopology` = dedupe + collapse-short + collapse-colinear + swap-degenerates (`src/edge_op.cpp`) | QEM half-edge decimation to a face target (`bt_mesh_simplify`) and error-bounded cleanup (`bt_mesh_simplify_by_error`) | **meep is ahead on quality** (true quadrics + Fibonacci heap + fold guard); manifold's is a robustness pass, not an LOD tool. |
+| Vertex welding | `Merge` + Morton sort + union-find (`src/sort.cpp`, `disjoint_sets.h`) | `bt_merge_vertices_by_distance` (open-addressed spatial hash, 27-cell fallback) | Comparable. meep's is order-dependent; manifold's is deterministic by construction. |
+| Degenerate removal | `RemoveDegenerates`, `SwapDegenerates`, `RemoveIfFolded`, `SplitPinchedVerts`, `DedupeEdges` | `collapse_all_degenerate_edges`, `bt_mesh_kill_short_edges`, `bt_mesh_fuse_duplicate_edges`, `bt_face_is_degenerate` | Roughly comparable coverage. manifold's `SplitPinchedVerts` has no meep equivalent. |
+| T-junctions | handled inside the boolean | `bt_mesh_resolve_t_junctions` | **meep has an explicit tool manifold lacks.** |
+| Hole filling | ✘ | `bt_mesh_close_boundary_holes`, `bt_mesh_fill_small_holes` | **meep only.** |
+| Refine / subdivide / smooth | `Refine`, `RefineToLength`, `RefineToTolerance`, `SmoothByNormals`, `SmoothOut`, `Smooth` (Bézier, `src/subdivision.cpp`, `smoothing.cpp` — 70KB combined) | ✘ | **manifold only.** See §4.4-c. |
+| Normals | `CalculateNormals(minSharpAngle)`, angle-weighted pseudo-normals, sharp-edge splitting | `bt_mesh_compute_face_normals`, `tm_vertex_compute_normal` | manifold's sharp-angle-aware version has no meep equivalent. |
+| Curvature | `CalculateCurvature(gaussian, mean)` | ✘ | |
+| Self-intersection test | `IsSelfIntersecting()` (BVH + tri-tri distance, ε-tolerant) | ✘ | Note: `tri_dist.h` (`DistanceTriangleTriangleSquared`) has no meep equivalent either. |
+| Structural validation | `IsManifold()`, `Is2Manifold()`, `IsFinite()`, `IsIndexInBounds()`, `MatchesTriNormals()`, `NumDegenerateTris()` | `topology_find_broken_links` / `debugValidateMesh` — **legacy `TopoMesh` only** | See §3.4. |
+| UV atlas / parameterisation | ✘ | `atlas/` — charts, LSCM, BFF, stretch metric, bitmap + skyline packing, multi-page | **meep only, decisively.** |
+| Tetrahedralisation | ✘ | `compute_delaunay_tetrahedral_mesh`, `compute_tetrahedral_mesh_from_surface` | **meep only.** |
+| Geodesic / path queries on a mesh | ✘ | `bt_mesh_face_find_path`, `_polyanya`, eikonal distance fields, `funnel_string_pull` | **meep only.** |
+| BVH | `src/collider.h` — linear BVH, Morton-ordered | `bvh2`, `bvh3`, `bvh8` (wide, compressed, `imask`), binary-serialisable | **meep is well ahead.** |
+
+---
+
+## 3. Implementation defects found in meep
+
+### 3.1 `tri3_compute_signed_volume` catastrophically cancels away from the origin — **HIGH**
+
+`core/geom/3d/triangle/tri3_compute_signed_volume.js` evaluates the *fully
+expanded* 3×3 determinant of **absolute** coordinates:
+
+```js
+const v321 = cx * by * az;   // … six triple products, each O(|p|³)
+return ONE_OVER_SIX * (-v321 + v231 + v312 - v132 - v213 + v123);
+```
+
+Every term is `O(|p|³)` while the result is `O(1)`, so all the significant
+digits cancel. Reproduced (unit cube, 12 triangles, `double`):
+
+| translation applied to every vertex | meep result | correct |
+| --- | --- | --- |
+| `(0, 0, 0)` | `1.00000000000` | `1` |
+| `(1e5, 1e5, 1e5)` | `0.999999999985` | `1` |
+| `(1e6, 1e6, 1e6)` | **`256.000000000`** | `1` |
+| `(1e7, 1e7, 1e7)` | **`−262144.000000`** | `1` |
+
+manifold computes the same quantity as `dot(cross(b − v, c − v), v) / 6`
+(`src/properties.cpp:265`), forming the *differences first*. With the identical
+inputs that form returns `1.00000000012` at `1e6` and `0.999999999069` at `1e7`
+— i.e. the defect is entirely in the formulation, not in double precision.
+
+The existing spec does test translation invariance
+(`triangle_mesh_compute_signed_volume.spec.js:48`) but only by `(5, −3, 17)`,
+which is ~5 orders of magnitude too small to expose it.
+
+**Fix.** Replace the expanded determinant with the edge-difference form. For the
+mesh-level wrapper, additionally subtract a reference point (bbox centre, or
+simply `positions[0..2]`) from every vertex once — signed volume is
+translation-invariant, so this is free and removes the failure mode entirely
+rather than merely postponing it. Extend the spec to `1e6`/`1e7` offsets.
+
+The same class of formulation appears in `tri3_compute_signed_volume`'s only
+sibling, `tetrahedron_compute_signed_volume.js`, which delegates to it.
+
+### 3.2 `ConvexHullShape3D.recompute()` repeats the pattern — **LOW**
+
+`core/geom/3d/shape/ConvexHullShape3D.js:133`:
+
+```js
+vol6 += ax * (by * cz - bz * cy) + ay * (bz * cx - bx * cz) + az * (bx * cy - by * cx);
+```
+
+Same absolute-coordinate triple products. Blast radius is small — collider
+vertices are in body-local space near the origin — but the fix is the same
+one-liner and worth taking while the area is open.
+
+### 3.3 No mesh-level compensated summation — **LOW**
+
+`tri3_mesh_compute_signed_volume.js:22` accumulates with a plain `+=`.
+manifold's `GetProperty` (`src/properties.cpp:265`) uses explicit Kahan
+summation for **both** volume and surface area, precisely because these are
+sums of signed terms over millions of triangles. Given that meep's own atlas
+benchmark already builds ~4M-triangle scenes, this is worth matching. It is
+strictly secondary to §3.1 — fix the formulation first, then the summation.
+
+### 3.4 `BinaryTopology` has no structural invariant checker — **HIGH (process defect)**
+
+`topology_find_broken_links.js` and `debugValidateMesh.js` both operate on the
+legacy object-based `TopoMesh`. The primary structure — `BinaryTopology`, the
+one every `bt_*` operation mutates — has **no validator at all**: no
+`bt_mesh_validate`, no `bt_mesh_is_manifold`, no disk/radial-cycle consistency
+check.
+
+This matters more than any individual algorithm. manifold's operations are
+trusted because `ManifoldParams().intermediateChecks` re-runs `IsManifold()`
+between stages and the test suite calls `CheckStrictly()` on nearly every
+result. meep has ~40 `bt_*` mutators (`bt_edge_collapse`, `bt_vert_splice`,
+`bt_radial_loop_remove`, `bt_face_poke`, …) each of which can corrupt a disk or
+radial cycle, and nothing that would notice.
+
+It also explains a real behavioural difference in decimation. When a collapse
+would violate the link condition, manifold **splits the mesh topologically**
+(`FormLoop` / `RemoveIfFolded`, `src/edge_op.cpp:492`) so the result stays
+2-manifold and the genus change is explicit. meep instead collapses first and
+repairs after, via `bt_edge_kill_parallels` + `bt_vertex_fuse_duplicate_edges`
+(`bt_mesh_simplify_by_error.js:582`). That may well be fine — but with no
+invariant checker there is no way to know, and `bt_mesh_simplify.spec.js:522`
+("handles a non-manifold T-junction edge without throwing") asserts only that it
+doesn't throw, not that the output is well-formed.
+
+### 3.5 `bt_face_triangulate` is a convex fan applied unconditionally — **MEDIUM**
+
+`bt_face_triangulate.js` fans from the first loop vertex and documents
+"Assumes that each face is a convex polygon". `bt_mesh_triangulate.js` then
+applies it to **every** face in the mesh with no convexity test. For a concave
+n-gon this emits inverted and overlapping triangles, silently.
+
+This is a documented precondition rather than a coding error, so I am not
+proposing a guard — the right response is that meep should have a real
+triangulator (§4.1) and `bt_mesh_triangulate` should call it. As it stands,
+"triangulate my mesh" is a public API that quietly produces garbage on the
+input a caller is most likely to hand it (an imported OBJ/FBX with n-gons).
+
+`bt_mesh_close_boundary_holes.js:131` has the same shape: it fans from the
+loop's centroid, which for a non-convex or strongly non-planar boundary lies
+outside the hole. It is scoped ("downstream tetrahedralization is
+position-only"), but it is the second place where a real triangulator is the
+missing dependency.
+
+---
+
+## 4. Gaps — where manifold is better with no trade-off
+
+### 4.1 General polygon triangulation (with holes) — the highest-leverage single gap
+
+`src/polygon.cpp` (38KB) + `polygon_internal.h` + `tree2d.h` implement a
+monotone sweep triangulator with:
+
+- arbitrary depth of nested holes and any number of separate polygons;
+- an explicit ε-validity contract (documented on `SimplePolygonIdx`);
+- a self-checking mode (`intermediateChecks`) that verifies the halfedge
+  triangulation it produced;
+- a **fuzz harness** (`test/polygon_fuzz.cpp`, FuzzTest + timeout + signal
+  handling) and a **regression corpus** of real-world failures
+  (`test/polygons/polygon_corpus.txt`, `sponge.txt`, `zebra.txt`,
+  `zebra3.txt` — 2.9MB of recorded failing inputs, replayed as tests).
+
+meep has no polygon triangulator. This is the dependency under `Extrude`,
+`Revolve`, `Slice`, `Project`, n-gon import, hole filling, planar chart
+re-meshing, and the face-splitting half of any future boolean. **Building this
+first unblocks more of the list than anything else on it.**
+
+Note the corpus approach specifically: manifold's triangulator got robust by
+recording every polygon that ever broke it and replaying them forever. That is
+directly transferable and cheap.
+
+### 4.2 2D polygon boolean + offset
+
+`src/boolean2.cpp` / `boolean2_sweep.cpp` / `boolean2_offset.cpp` /
+`boolean2_predicates.cpp` (~70KB) — manifold wrote its own sweep-line
+replacement for Clipper2, with `JoinType::{Square, Round, Miter}` offsetting and
+a dedicated offset corpus test (`test/cross_section_offset_corpus_test.cpp`,
+`test/models/Offset{1..4}.obj`).
+
+meep has half-plane clipping only. Anything phrased as "union these footprints",
+"inset this outline by the agent radius", "subtract these obstacle polygons" has
+no answer. This is also the natural way to build navmesh obstacle carving —
+which meep currently does by voxel/soup clipping instead.
+
+### 4.3 3D convex hull
+
+`src/quickhull.cpp` (30KB, derived from Kuukka's public-domain quickhull) with a
+dedicated test file covering the cases that break naive implementations:
+`Hull.Degenerate2D`, `Hull.Degenerate1D`, `Hull.NotEnoughPoints`, `Hull.Hollow`,
+`Hull.MengerSponge`, plus two recorded real-world failures.
+
+meep's `ConvexHullShape3D` *consumes* a hull (`static from(vertices, indices)`)
+and `mesh_convex_hull.js` only *detects* whether a tet mesh is already convex.
+There is no way to compute a hull from a point set. That blocks: authoring
+colliders from arbitrary meshes, convex decomposition quality (the greedy
+decomposer in `convex_decomposition.js` explicitly notes it fragments convex
+input), bounding-volume construction, and `Hull()`-based modelling
+(rounded frames, sweeps between poses — manifold's `Hull(vector<Manifold>)` is
+one of its most-used operations in practice).
+
+### 4.4 "A and C but not B" — cheap middles missing between expensive ends
+
+**a) SDF → mesh.** meep has a complete implicit-shape algebra:
+`AbstractShape3D.signed_distance_at_point`, `signed_distance_gradient_at_point`,
+`contains_point`, `support`, `raycast`, plus `shape3_voxelize_to_grid`, plus
+`probe_sdf_grid` / `probe_place_sdf_cover` in the sound simulator. It has
+world-class mesh *processing* downstream. It has **no isosurface extraction** —
+no marching cubes, no marching tetrahedra, no dual contouring. So a field can be
+sampled but never turned into geometry. manifold's `LevelSet(sdf, bounds,
+edgeLength, level, tolerance)` is ~22KB and is the single cheapest way for meep
+to acquire *approximate* boolean modelling: union/intersect/subtract of SDFs is
+`min`/`max`/`max(−)`, and the mesher does the rest.
+
+**b) `UnionShape3D` with no siblings.** `core/geom/3d/shape/` has
+`UnionShape3D` and no `IntersectionShape3D`, no `DifferenceShape3D`, no
+`TransformedShape3D`-style negation. This is the literal shape of the
+user's concern: a caller who finds `UnionShape3D` reasonably expects the other
+two Boolean combinators to exist. Both are ~30 lines each given the existing
+`AbstractShape3D` interface (`max`, and `max(a, −b)` for signed distance;
+intersect/complement for `contains_point`; bounds from the intersection /
+from `a`).
+
+**c) Refine / smooth / subdivide.** manifold ships `Refine(n)`,
+`RefineToLength`, `RefineToTolerance`, `SmoothByNormals`, `SmoothOut`, and
+`Smooth(mesh, sharpenedEdges)` — a full Bézier-triangle subdivision surface
+with per-halfedge tangents, sharp-edge control, and 18 dedicated tests.
+meep can *decimate* well and *parameterise* excellently but cannot refine at
+all. For offline work (the stated context) refinement is as common as
+decimation.
+
+**d) Genus / Euler characteristic.** meep has connected components, boundary
+loop walking, and manifoldness predicates on edges — every ingredient — but no
+`genus()`. manifold's is three lines (`χ = V − E + F`, `genus = 1 − χ/2`,
+`src/properties.cpp:241`).
+
+**e) Winding number.** meep has BVH raycasting and `bt_mesh_segment_penetrates_surface`
+but no point-in-mesh / winding number for arbitrary point sets. manifold's
+`WindingNumber(points)` is ray-parity over its collider, with tests specifically
+for the watertight-vertex and silhouette-edge cases that break naive parity
+counting (`measurement_test.cpp`).
+
+**f) Mesh-mesh minimum distance.** meep has per-pair narrowphase distance for
+collision shapes but no `MinGap(other, searchLength)` for triangle meshes, and
+no triangle-triangle distance primitive (manifold's `src/tri_dist.h`). That
+primitive is also the missing piece for a self-intersection test (§2.3).
+
+### 4.5 API-level: the tolerance model
+
+manifold carries `epsilon_` (numerical validity floor, derived from the bounding
+box) and `tolerance_` (user-facing simplification budget) **on the mesh**, sets
+them once (`SetEpsilon`, `src/impl.cpp:684`), and threads them through every
+operation. `MeshGL.tolerance` round-trips through serialisation. There are four
+dedicated tests (`Properties.Epsilon`, `Epsilon2`, `Tolerance`,
+`ToleranceSphere`) asserting the propagation rules.
+
+meep passes tolerances ad hoc: `max_error` to `bt_mesh_simplify_by_error`,
+`tolerance` to `tm_weld_duplicate_vertices`, `EPSILON` defaults scattered per
+call site. Nothing carries a tolerance with the data, so a pipeline of five
+operations has five independently-chosen epsilons and no way to reason about
+accumulated drift. manifold's design is strictly better here and costs one
+field on `BinaryTopology`.
+
+Two related API notes:
+
+- **Error reporting.** `Manifold::Status()` returns a 15-value `Error` enum
+  (`NotManifold`, `NonFiniteVertex`, `VertexOutOfBounds`, `ResultTooLarge`, …)
+  and operations propagate it rather than throwing — with an entire test family
+  (`Manifold.ErrorPropagation*`, 13 tests) verifying that an invalid input stays
+  invalid through every operation. meep's topology layer generally asserts (and
+  asserts compile out in production).
+- **Provenance.** `MeshGL`'s `runIndex` / `runOriginalID` / `runTransform` /
+  `faceID` let a caller recover, for every output triangle, which input mesh and
+  which original face it came from — through booleans. That is what makes
+  "re-apply the original materials to the boolean result" a solved problem.
+  meep's `BinaryTopology` has per-element data pools that could carry the same
+  information but no convention for doing so.
+
+---
+
+## 5. Where meep leads
+
+Not a courtesy section — these are areas where manifold has nothing and the
+right advice is "do not migrate away from meep for this":
+
+- **UV atlasing** (`core/geom/3d/atlas/`): chart segmentation, region-atomic
+  segmentation, LSCM *and* BFF parameterisation, stretch metrics, chart merging,
+  piecewise re-segmentation, bitmap + skyline packing, multi-page elastic
+  density. manifold has no UV pipeline at all.
+- **Acceleration structures**: `bvh8` (wide, compressed, `imask` authority,
+  binary-serialisable) vs manifold's single linear Morton BVH.
+- **Tetrahedralisation** and volumetric meshing.
+- **Geodesic / navigation queries**: Polyanya, funnel string-pull, eikonal
+  boundary distance fields, face islands.
+- **Physics-grade shape queries**: GJK/EPA, exact SAT manifolds, convex
+  decomposition, capsule/box/heightmap primitives with exact closed forms.
+- **Half-edge generality**: n-gons, wire edges, per-element attribute pools,
+  T-junction resolution, hole closing — manifold's triangle-only halfedge
+  cannot represent most of this.
+- **Error-bounded decimation with a true quadric heap** — manifold's
+  `SimplifyTopology` is a cleanup pass, not an LOD tool.
+
+---
+
+## 6. Recommendations
+
+Ordered by (unblocks-other-work × confidence) ÷ effort.
+
+### P0 — correctness, small
+
+1. **Fix `tri3_compute_signed_volume`** (§3.1). Edge-difference form; subtract a
+   reference point at the mesh level. Add specs at `1e6`/`1e7` offsets. Same fix
+   in `ConvexHullShape3D.recompute()`. *(~1h)*
+2. **Add Kahan summation to `tri3_mesh_compute_signed_volume`** and to any
+   surface-area accumulator. *(~30m)*
+3. **Write `bt_mesh_validate(mesh)`** for `BinaryTopology` (§3.4): disk-cycle
+   closure and slot convention, radial-cycle closure, loop `next`/`prev`
+   inverse, loop→face→loop reachability, edge→loop→edge agreement, allocation
+   consistency, no dangling `NULL_POINTER`. Then a `bt_mesh_is_manifold` /
+   `bt_mesh_is_2_manifold` pair on top. Call it from every `bt_*` spec's
+   arrange/assert. This is the highest-value item in the whole document: it
+   converts ~40 mutators from "probably fine" to "checked", and it is the
+   prerequisite for trusting anything built later. *(~1–2 days incl. retrofitting specs)*
+
+### P1 — the unblocking primitive
+
+4. **Port a polygon triangulator with hole support** (§4.1). Monotone sweep is
+   the right choice (manifold's, and it's the one that survives fuzzing). Ship
+   it with: an ε parameter, a self-check mode, a fuzz spec, and a *corpus file*
+   of recorded failures replayed as tests. Then rewire `bt_face_triangulate` /
+   `bt_mesh_triangulate` and `bt_mesh_close_boundary_holes` onto it. *(~1 week)*
+
+### P2 — the cheap middles
+
+5. **`IntersectionShape3D` + `DifferenceShape3D`** to complete `UnionShape3D`
+   (§4.4-b). *(~half a day, including specs)*
+6. **Isosurface extraction** (`shape3_to_topology` / marching tetrahedra over
+   `AbstractShape3D.signed_distance_at_point`) (§4.4-a). With #5 this gives meep
+   approximate CSG immediately, over the shape algebra it already has, and feeds
+   straight into the existing decimation + atlas pipeline. Follow manifold's
+   `sdf.cpp` in using marching **tetrahedra** rather than cubes — no ambiguous
+   cases, guaranteed manifold output. *(~3–4 days)*
+7. **3D convex hull (quickhull)** (§4.3). Improves `convex_decomposition`
+   quality, unblocks `ConvexHullShape3D.from(points)`, and is the basis of
+   `Hull`-based modelling. Copy manifold's degenerate-case test list verbatim —
+   collinear points, coplanar points, <4 points, duplicate points. *(~3–4 days)*
+8. **`bt_mesh_genus` / `bt_mesh_euler_characteristic`** (§4.4-d) and
+   **`bt_mesh_winding_number`** (§4.4-e). *(~1 day together)*
+
+### P3 — the tolerance model
+
+9. **Carry `epsilon` / `tolerance` on `BinaryTopology`** (§4.5), derived from the
+   bounding box, settable, propagated by operations, serialised. Retrofit the
+   `bt_*` operations that currently take an `eps` argument to default to it.
+   *(~2–3 days, mostly mechanical)*
+10. **A `Status()`-style error channel** for topology operations, so a pipeline
+    can carry "this mesh is invalid because X" instead of asserting (and
+    asserts compile out in production, so today the failure is silent).
+
+### P4 — larger, only if the domain demands it
+
+11. **2D polygon boolean + offset** (§4.2). Big, but it is the correct
+    foundation for navmesh obstacle carving, footprint union, and inset/outset.
+    If the appetite isn't there, note that a well-specified subset (union of
+    simple polygons + inset/outset with miter joins) covers most in-engine uses.
+12. **Refine / subdivide** (§4.4-c). Comparatively self-contained; loop or
+    Bézier-triangle subdivision over `BinaryTopology`.
+13. **Full 3D mesh boolean.** Deliberately last. It is the largest single piece
+    of work in the comparison (manifold spends ~90KB across `boolean3.cpp` +
+    `boolean_result.cpp` + `boolean2*.cpp` and years of corpus-driven hardening),
+    and #6 (SDF level-set CSG) covers a large fraction of the practical demand
+    at a fraction of the cost. **Recommendation: do not build this.** If exact
+    boolean is genuinely required, depending on manifold's WASM build for that
+    one operation is the honest answer — the review found no evidence meep should
+    own it.
+
+### The meta-recommendation
+
+The reason an agent left is not that any one of these was missing — it is that
+**the first three questions it asked all missed**. The cheapest way to change
+that outcome is P1 + P2 (#4–#8): a triangulator, the two missing shape
+combinators, an isosurfacer, and a hull. That is roughly two to three weeks and
+it converts meep from "cannot do solid modelling" to "can do solid modelling
+approximately, over its own shape algebra, feeding its own best-in-class
+downstream pipeline". Combined with P0 #3 (the validator), it also makes the
+result trustworthy enough to chain — which is the other half of why manifold
+gets picked.
+
+---
+
+## 7. Test-design lessons worth stealing
+
+manifold's suite is unusually good and several patterns transfer directly:
+
+1. **Universal invariant assertions.** `test/test.h` defines `CheckStrictly()`,
+   `CheckGL()`, `CheckFinite()`, `Identical()`, `RelatedGL()` and nearly every
+   test calls one. The assertion is on *the invariant*, not on specific values —
+   which is exactly meep's stated black-box testing preference.
+2. **Recorded-failure corpora.** `test/polygons/*.txt` (2.9MB) and
+   `test/models/*.obj` are literally the inputs that once broke the library,
+   replayed forever. Cheap to build, permanently valuable. meep's atlas suite
+   already hints at this (the retracted "sphere over-fragmentation" finding
+   turned out to be a fixture bug) — formalising it as a corpus would have
+   caught that earlier.
+3. **Fuzzing the fragile primitive.** `polygon_fuzz.cpp` / `manifold_fuzz.cpp`
+   fuzz the triangulator and the boolean specifically, with timeouts, because
+   those are the two things that hang rather than fail.
+4. **Determinism as a first-class test family.** `Boolean.DeterminismSimple{Subtract,
+   Union,Intersect}`, `Manifold.MeshDeterminism`. meep already does this for
+   physics (`determinism.spec.js`); the topology layer should too, especially
+   given order-dependent welding.
+5. **Error-propagation as a test family.** 13 `Manifold.ErrorPropagation*` tests
+   assert that an invalid input remains invalid through every single operation.
+   Pairs with recommendation #10.
+6. **Named real-world regression tests.** `BooleanComplex.GenericTwinBooleanTest7081`,
+   `Havocglass8Bool`, `CraycloudBool`, `OpenscadCrash` — each one a bug report
+   frozen into a test with the model checked in.
+
+---
+
+## Appendix A — manifold source map
+
+| File | Size | What it is |
+| --- | --- | --- |
+| `src/boolean3.cpp` + `boolean_result.cpp` | 60KB | 3D mesh boolean (Smith & Dodgson) |
+| `src/boolean2*.cpp` | 70KB | 2D polygon boolean + offset (own sweep-line, replaced Clipper2) |
+| `src/polygon.cpp` + `polygon_internal.h` + `tree2d.cpp` | 45KB | Monotone-sweep triangulator with holes |
+| `src/quickhull.cpp` | 30KB | 3D convex hull |
+| `src/sdf.cpp` | 22KB | `LevelSet` — marching tetrahedra |
+| `src/subdivision.cpp` + `smoothing.cpp` | 75KB | Refine + Bézier-triangle smoothing |
+| `src/edge_op.cpp` | 35KB | Collapse / swap / dedupe / pinched-vert splitting |
+| `src/impl.cpp` + `impl.h` | 60KB | Halfedge mesh, epsilon/tolerance, normals |
+| `src/properties.cpp` | 16KB | Volume, area, curvature, genus, manifoldness, self-intersection |
+| `src/csg_tree.cpp` | 36KB | Lazy CSG evaluation + batch boolean scheduling |
+| `src/minkowski.cpp` | 8KB | Minkowski sum/difference via hull + boolean |
+| `src/sort.cpp` | 24KB | Morton ordering, vertex merge, halfedge reordering |
+| `src/collider.h` | 12KB | Linear BVH |
+| `src/face_op.cpp` | 17KB | `Face2Tri`, `Slice`, `Project` |
+| `test/` | ~450KB + 5MB models | 9 gtest files, 2 fuzz harnesses, polygon corpus, 17 regression OBJs |
+
+## Appendix B — reproduction of §3.1
+
+```js
+// meep form: fully expanded determinant of absolute coordinates
+function meep(a, b, c) {
+  const [ax,ay,az]=a, [bx,by,bz]=b, [cx,cy,cz]=c;
+  return (-(cx*by*az) + bx*cy*az + cx*ay*bz - ax*cy*bz - bx*ay*cz + ax*by*cz) / 6;
+}
+// manifold form: differences first
+function manifoldForm(a, b, c) {
+  const u = [b[0]-a[0], b[1]-a[1], b[2]-a[2]];
+  const w = [c[0]-a[0], c[1]-a[1], c[2]-a[2]];
+  const cr = [u[1]*w[2]-u[2]*w[1], u[2]*w[0]-u[0]*w[2], u[0]*w[1]-u[1]*w[0]];
+  return (cr[0]*a[0] + cr[1]*a[1] + cr[2]*a[2]) / 6;
+}
+// Summed over the 12 triangles of a unit cube translated by (1e7, 1e7, 1e7):
+//   meep          → -262144
+//   manifoldForm  →       0.999999999069
+```

package/src/core/geom/vec3/v3_cotangent.d.ts

@@ -12,8 +12,12 @@
  * non-finite — callers exclude degenerate faces upstream rather than guarding
  * here.
  *
- * @param {number} ax @param {number} ay @param {number} az
- * @param {number} bx @param {number} by @param {number} bz
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
  * @returns {number}
  */
 export function v3_cotangent(ax: number, ay: number, az: number, bx: number, by: number, bz: number): number;

package/src/core/geom/vec3/v3_cotangent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_cotangent.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_cotangent.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,iCAJW,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,GAC1C,MAAM,CAUlB"}
+{"version":3,"file":"v3_cotangent.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_cotangent.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iCARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAUlB"}

package/src/core/geom/vec3/v3_cotangent.js

@@ -14,8 +14,12 @@ import { v3_dot } from "./v3_dot.js";
  * non-finite — callers exclude degenerate faces upstream rather than guarding
  * here.
  *
- * @param {number} ax @param {number} ay @param {number} az
- * @param {number} bx @param {number} by @param {number} bz
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
  * @returns {number}
  */
 export function v3_cotangent(ax, ay, az, bx, by, bz) {

package/src/core/geom/vec3/v3_cross.d.ts

@@ -7,8 +7,12 @@
  *
  * @param {number[]|Float32Array|Float64Array} result destination
  * @param {number} result_offset offset into `result`
- * @param {number} ax @param {number} ay @param {number} az  first vector
- * @param {number} bx @param {number} by @param {number} bz  second vector
+ * @param {number} ax  first vector x
+ * @param {number} ay  first vector y
+ * @param {number} az  first vector z
+ * @param {number} bx  second vector x
+ * @param {number} by  second vector y
+ * @param {number} bz  second vector z
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

package/src/core/geom/vec3/v3_cross.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_cross.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_cross.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,iCARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,MACN,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAStD"}
+{"version":3,"file":"v3_cross.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_cross.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,iCAZW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAShB"}

package/src/core/geom/vec3/v3_cross.js

@@ -7,8 +7,12 @@
  *
  * @param {number[]|Float32Array|Float64Array} result destination
  * @param {number} result_offset offset into `result`
- * @param {number} ax @param {number} ay @param {number} az  first vector
- * @param {number} bx @param {number} by @param {number} bz  second vector
+ * @param {number} ax  first vector x
+ * @param {number} ay  first vector y
+ * @param {number} az  first vector z
+ * @param {number} bx  second vector x
+ * @param {number} by  second vector y
+ * @param {number} bz  second vector z
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

package/src/core/geom/vec3/v3_multiply.d.ts

@@ -6,8 +6,12 @@
  *
  * @param {number[]|Float32Array|Float64Array} result destination
  * @param {number} result_offset offset into `result`
- * @param {number} ax @param {number} ay @param {number} az  first factor
- * @param {number} bx @param {number} by @param {number} bz  second factor
+ * @param {number} ax  first factor x
+ * @param {number} ay  first factor y
+ * @param {number} az  first factor z
+ * @param {number} bx  second factor x
+ * @param {number} by  second factor y
+ * @param {number} bz  second factor z
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

package/src/core/geom/vec3/v3_multiply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_multiply.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_multiply.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,oCARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,MACN,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAStD"}
+{"version":3,"file":"v3_multiply.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_multiply.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,oCAZW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAShB"}