tessellation: non-manifold edges in dovetail baseplate STL exports (2.89.2)

[andymai]

Summary

brepkit-wasm 2.89.2 produces tessellated meshes with non-manifold edges for dovetail-connector baseplate exports that are watertight under brepjs-opencascade (OCCT). PR #692's compound-boolean variance fix is in this release and behaves correctly — but the tessellation/winding pathology is independent and still present.

The downstream consumer is gridfinity-layout-tool; the failing tests live in src/features/generation/worker/generators/baseplateGenerator.scenario.dovetail.test.ts (originally written against issue gridfinity-layout-tool#1407).

Observed under 2.89.2

Scenario	Non-manifold edges
5×4 middle-column tile (3 join edges, tongue protrusion)	142
4×4 interior tile (4 join edges)	73

OCCT (default brepjs kernel) for the same params: 0.

The non-manifold count comes from edge-shared-by-≥3-triangles in the binary STL. The diagnostic also surfaces in stderr as [repairMeshWinding] Skipped non-manifold edges during winding repair { nonManifoldEdges: N, triangleCount: M } from the consumer's defensive winding-repair pass (which is a no-op under OCCT — see src/shared/generation/repairMeshWinding.ts).

Minimal repro

The full repro path is exportBaseplate(params, 'stl') → tessellate → binary STL. The BaseplateParams shapes that fail:

// 5×4 middle-column — 142 non-manifold edges
{
  width: 5, depth: 4, gridUnitMm: 42,
  magnetHoles: false,
  paddingLeft: 0, paddingRight: 0, paddingFront: 0, paddingBack: 0,
  fractionalEdgeX: 'end', fractionalEdgeY: 'end',
  lightweight: true,
  connectorNubs: true,
  edges: { left: 'exterior', right: 'join', front: 'join', back: 'join' },
}

// 4×4 interior — 73 non-manifold edges
{
  width: 4, depth: 4, gridUnitMm: 42,
  magnetHoles: false,
  paddingLeft: 0, paddingRight: 0, paddingFront: 0, paddingBack: 0,
  fractionalEdgeX: 'end', fractionalEdgeY: 'end',
  lightweight: true,
  connectorNubs: true,
  edges: { left: 'join', right: 'join', front: 'join', back: 'join' },
}

To reproduce in the consumer repo:

git checkout main  # brepkit-wasm pinned at ^2.87.1 — bump to ^2.89.2 first
BREPJS_KERNEL=brepkit pnpm exec vitest run \
  src/features/generation/worker/generators/baseplateGenerator.scenario.dovetail.test.ts

Expected: all 9 tests pass.
Actual under brepkit-wasm@2.89.2: at least 2 (middle-column tile, interior tile) fail with non-manifold edges: expected 142 to be +0 // Object.is equality. Older 2.89.1 run failed all 9.

Hypothesis

The 9-fail signature in 2.89.1 narrowed to 2-fail (early in the file) in 2.89.2, but the type of failure is unchanged: triangle winding emitted across face boundaries is inconsistent, causing edges to appear shared by ≥3 triangles in the merged mesh. PR #683 introduced deterministic face order in face_components; PR #692 fixed HashMap iteration in the GFA pipeline. Either:

1. A remaining non-deterministic iteration site in the tessellation/edge-emission path is producing different winding for adjacent faces, or
2. The boolean output topology is non-manifold (T-junction or shared coplanar face residue), which the tessellator then faithfully passes through.

The gridfinity-layout-tool fix that motivated these tests (TONGUE_PROTRUSION — extending the tongue's base edge a small amount INTO the slab to give the fuse shared volume rather than a degenerate coplanar face) was specifically to avoid hypothesis (2) under OCCT. If brepkit still produces non-manifold output even with the protrusion, hypothesis (1) or a separate residue case in the boolean is more likely.

Companion observation: perf

PR #692's variance fix landed cleanly — the same consumer's 4×4 with lip bench went from max 142ms / RME ±51.7% on 2.87.1 to max 21.5ms / RME ±4.0% on 2.89.2. Multi-boolean determinism is solved.

Independent of variance, the 2.89.1 test run had two outlier wall-times that are worth a sanity-check on 2.89.2 once the manifold issue is fixed:

Test	Wall-time on 2.89.1
binExporter.split-noexport > exports successfully after split preview — magnet+screw base with lip	1,139 s
baseplateGenerator.scenario.winding > magnet baseplate with lightweight floor — winding consistent	649 s

Both are likely consequences of the failure path (broken topology cascading into expensive mesh repair), so they should clear up alongside the manifold fix — flagging here in case they don't.

Environment

• brepkit-wasm@2.89.2 via npm
• brepjs@18.5.3 with BrepkitAdapter from brepjs.registerKernel('brepkit', new BrepkitAdapter(kernel))
• Node 24.11.0, vitest 4.1.6, Linux x86_64

[andymai]

Investigation update (2026-05-20)

Reproduced the bug end-to-end against current main (2.89.2): the 4×4 interior tile test reports 73 non-manifold edges (matching the issue exactly), 0 boundary edges. So this is pure topological branching, not gap-closing.

What I verified

• tessellate_solid() correctly shares boundary vertices across adjacent faces via the per-edge edge_global_indices map — so the Explore report's "HashMap iteration variance in tessellation" thesis is a red herring. The vertex IDs assigned may vary across runs, but whichever IDs they get, adjacent faces see the same IDs.
• validate_boolean_result() already detects topology-level non-manifold edges via validate_solid (Error severity), but currently only logs warnings — so a GFA result with NM topology passes the gate when Euler still equals 2.
• enforce_manifold_shell() runs on the mesh-boolean fallback path, but not on the GFA success path.

What I tried that didn't fix it

• Hard-failing validate_boolean_result on non-manifold-edge errors regressed 15 ops tests — many GFA results have minor NM edges that downstream unify_faces / heal passes already handle. The rejection criterion needs to be narrower.

Foundation contributed (PR forthcoming on fix/issue-696-tessellation-nm-foundation)

1. non_manifold_edge_count(mesh) helper — counts edges referenced by ≥3 triangles. The existing boundary_edge_count docstring claimed to measure "non-manifold" but only counted 1-sided edges. Both are needed to fully validate a watertight 2-manifold.
2. Three dovetail-pattern regression tests in tessellate/tests.rs. They currently pass — synthetic axis-aligned / trapezoidal tongue + multi-tile + hollow combinations don't reproduce the bug, confirming the failure requires the full pipeline (slab + pockets + magnet holes + lightweight floor + connector nubs + connector holes).
3. Deterministic iteration in build_manifold_shell and split_nonmanifold_edges (matches the fix(algo): two HashMap iteration sites driving 64-cut bench variance #689/fix(algo): close compound boolean variance + lay foundation for box-sphere intersect #692 pattern in algo). Doesn't move the consumer's number, but eliminates one variance source.

Where the bug lives (best guess)

The downstream repairMeshWinding reports 1133 non-manifold edges over only 535 triangles for the 4×4 case. 535 triangles is suspiciously low for a 4×4 baseplate (~250 from boxes alone, more with nubs/cuts). Combined with analyzeManifold's separate count of 73 unique branching edges, this strongly suggests overlapping coplanar faces in the boolean output — likely from the booleanPipeline step that does the nubs-fuse + connector-holes-cut. Tessellating both sides of an overlapping face pair produces duplicate triangles that share edges with the surrounding mesh on both sides → 4+ triangles per edge.

Suggested next step

A targeted fix in boolean/mod.rs after the GFA pipeline returns: detect topology-level NM edges via validate_solid, and either (a) run enforce_manifold_shell (with its nm_count > 3 threshold lifted to nm_count > 0 on this code path), or (b) drop to the mesh-boolean fallback when NM > 0. The 15-test regression I hit with broad rejection probably narrows to a small set of cases if the test specifically excludes boundary-edge issues — those are the ~25% that legitimately use the relaxed gate, but NM-edges aren't in that group.

[andymai]

PR #697 merged (commit `923d04d`). Will ship in the next release.

Result: 82–85% reduction in non-manifold mesh edges across the failing dovetail scenarios:

Scenario	Before	After
5×4 middle-column tile	142	21
4×4 interior tile	73	12
5×4 inverted middle	—	6

The residual edges (6–21 across the three tiles) are real topology-level branching in the boolean output — 3 faces with the same surface meeting at one edge. The architectural fix (extending `detect_same_domain` in the assembler with within-rank pairing + point-in-face geometric verification) is the right next step but too invasive for one PR. See the PR description for the full rationale and the four reverted approaches that informed the chosen approach.

Leaving this issue open since it's not fully resolved — the residual NM edges still break slicer manifold checks. A follow-up PR can close it once the assembler-level same-domain detection is generalized.

[andymai]

PR #699 merged (commit `dd4b53a`). Will ship with the next release after 2.90.1.

This is the architectural follow-up to #697. Generalizes the assembler's same-domain detection to handle within-rank duplicates (boolean residue from sequential operations) and adds a planar full-containment geometric pass for residue with different outer boundaries.

Cumulative reduction across both PRs:

Scenario	main pre-fix	#697	#697 + #699
5×4 middle-column	142	21	20
4×4 interior	73	12	10
5×4 inverted middle	—	6	6

The within-rank infrastructure catches the planar-full-containment subset of residue. The remaining residue follows patterns this PR doesn't address — non-planar surfaces (cylindrical nub side faces), and 3-face junctions with mixed surfaces — which need different detection strategies. Leaving this issue open for further follow-up.

[andymai]

Status: residual NM-edge investigation did not produce a shippable fix. Documenting what I learned so the next attempt has context.

What I attempted

A follow-up branch (deleted, not pushed) tried to extend the planar same-domain detection in two ways:

1. Drop the `interior_point.is_none()` skip in Step 3b — passthrough sub-faces from boolean image-fill (which never get a precomputed interior) are exactly the residue pattern we suspect. Fall back to wire centroid or `sample_interior_point` for those.
2. Use wire centroid / robust interior sample as the fallback.

What happened

Against the 4×4 interior tile (10 NM edges baseline post-#697+#699): NM count went 10 → 12 — a regression. The fallback was unioning legitimate adjacent same-plane faces, removing them from the selection and leaving open boundaries that became branching edges elsewhere in the mesh.

What I needed but couldn't get

A way to see what topology pattern produces the residual 6–20 NM edges. I added `eprintln!` diagnostics in `tessellate_solid` and `write_stl` but they didn't reach the consumer's vitest stderr — `wasm-pack --target nodejs` doesn't route Rust `eprintln` to host stderr by default. Without that visibility, every further heuristic is guesswork, and the regression above shows the cost.

Misconception cleared up

I initially called this "non-planar residue" assuming cylindrical nub features. In fact gridfinity-layout-tool's nubs are trapezoidal extrusions — entirely planar. So the geometry isn't non-planar; the residue pattern is just planar with a structure my containment test doesn't catch. Likely candidates: faces with inner wires (holes), partial overlap (one face crosses another's boundary), or 3+ faces meeting at an edge where no pairwise containment holds.

Suggested next step

Before more code: invest in a brepkit-side diagnostic path that surfaces the residual NM edges' face/surface metadata. Two options:

• Wasm side: route `log::warn` through `console_log` (or similar) so brepkit's existing validation warnings reach JS stderr. Then re-instrument `tessellate_solid` / `write_stl` with structured logging.
• Rust side: write a brepkit-level test that replicates the consumer's connector-pipeline operation sequence (slab + pockets + magnet holes + lightweight floor + nub fuses + connector hole cuts) with realistic gridfinity parameters, then assert `non_manifold_edge_count(mesh) == 0` and inspect on failure.

Either gives concrete evidence of what residue remains, which would unblock targeted fixes.

The cumulative reduction from #697 + #699 (82-92% across the three failing scenarios) holds; this is about whether to push further.