@woosh/meep-engine 2.164.0 → 2.165.0

package/src/core/geom/3d/atlas/ATLAS_PORT_PLAN.md

@@ -0,0 +1,486 @@
+# UV Atlas — xatlas `ComputeCharts` + `PackCharts` port into meep
+
+Status: **M0–M14 IMPLEMENTED** (2026-06-25) · Target: `app/src/mir-engine/meep/src/...`
+
+> **M12–M14 (phase 2 cont.):** M12 region-atomic segmentation (default;
+> `segment/atlas_{build_region_graph,segment_charts_atomic}`). M13 multi-page +
+> **elastic density** packing (`maxResolution`/`maxPages`; `maxPages:1` = single
+> elastic page). M14 benchmark suite (`atlas_generate.bench.spec`, `.skip`,
+> `BENCH_SECONDS`) — it surfaced that the bitmap canBlit scan is O(atlas²) (13–22s
+> at 2048), fixed by a fast **skyline rectangle packer** (`core/geom/2d/packing/
+> skyline`) auto-selected for large atlases; exact bitmap kept for small / behind
+> `bruteForce`. Pack at 2048: 3–43ms, 46–95% utilization. A second `.skip` bench
+> builds a deterministic `~4M-tri` procedural scene (`soup_scene`, env
+> `BENCH_LARGE_TRIS`) for scaling measurement.
+>
+> **Benchmark findings (updated 2026-06-25):**
+> - *Sphere "over-fragmentation" was a fixture bug, not a tool bug.* The bench's
+>   `soup_uv_sphere` fanned the poles with degenerate coincident-vertex triangles
+>   that welded into slivers (125 charts, 120 "degenerate"). Fixed to skip them →
+>   **4 charts, 0 degenerate**, matching the clean indexed fixture. A clean closed
+>   sphere segments fine; the earlier "closed surfaces over-fragment" finding is
+>   retracted.
+> - *Chart extraction was O(charts × faces)* (re-scanned every face per chart +
+>   allocated a full per-vertex array per chart). Now O(faces): one face-bucket
+>   pass + a reused version-stamped vertex map. **Compute 92.8s → 35.9s (2.6×)** on
+>   a 150k-tri scene, behaviour-preserving.
+> - *New `~4M-tri` procedural-scene bench* (`soup_scene`, env `BENCH_LARGE_TRIS`):
+>   a representative field (terrain + large objects + thousands of small shapes).
+>   It quantifies the remaining scaling walls — **mesh conditioning (colocal weld +
+>   t-junction resolution + edge-data) ~75%** of compute, **LSCM ~20%**;
+>   segmentation+extraction is now negligible. Both walls are the next perf targets
+>   (conditioning lives in the shared topology layer → wider blast radius); the
+>   bench is the standing quantifier. A max-stretch outlier (133–359) on
+>   decimated/curved meshes remains the quality target.
+> - *Degenerate-triangle robustness* (collinear / needle / sliver) is now an
+>   end-to-end test: the pipeline stays finite (no NaN, no crash); degenerate faces
+>   become isolated zero-area charts, good charts stay bijective.
+
+> **Implementation status.** All milestones M0–M11 landed and green (20 spec suites, 82 tests).
+> Public entry: [`atlas_generate(mesh, options)`](atlas_generate.js) = ComputeCharts + PackCharts in one
+> call (per-corner UVs written to the loop_data channel). Pieces: M0 sparse CG/eigen
+> (`core/math/linalg/{cg,sparse}`, `eigen/matrix_symmetric_3x3_eigen`, `vec3/v3_cotangent`); M1 weld +
+> AtlasData + `io/bt_loop_uv`; M2 `fit_plane_basis` + `segment/atlas_compute_planar_regions`; M3
+> `segment/atlas_segment_charts`; M4 `atlas_extract_chart` + `param/{ortho,validity,stretch}`; M5
+> `param/atlas_chart_parameterize_lscm`; M6 `atlas_compute_charts`; M7 `core/binary/BitImage2` +
+> `2d/triangle/tri2_rasterize_conservative`; M8 `pack/atlas_pack_charts`; M9 `atlas_generate`;
+> **M10** chart rotation (`2d/oriented-box/min_area_rect_2d` + `BitImage2.transposed`); **M11**
+> `param/atlas_piecewise_resegment` (region-grow piecewise).
+>
+> **Deferred refinements** (documented in code, not yet built; §12 backlog): region-atomic segmentation
+> (currently face-granular), multi-atlas pages + blockAlign, Jacobi/IC preconditioner for the CG if
+> large charts need it, a placement-scan acceleration structure, optional `createImage`, and benchmarks.
+
+Port the two load-bearing capabilities of [xatlas](https://github.com/jpcy/xatlas) — segmentation
+into UV charts (`ComputeCharts`) and packing those charts into an atlas (`PackCharts`) — onto meep's
+existing geometry, topology, linear-algebra and packing toolkits. xatlas is a ~10k-line single C++
+file; large parts of it (half-edge mesh, union-find, heaps, eigen, BVH, sort) are **replaced wholesale**
+by primitives meep already ships. This document is the implementation contract.
+
+---
+
+## 1. Locked scope decisions
+
+| Decision | Choice | Consequence |
+|---|---|---|
+| **Fidelity** | **xatlas-grade** | Build the bitmap shifted-OR packer **and** true conformal LSCM up front (not MaxRects/harmonic stopgaps). |
+| **Output** | **In-place on `BinaryTopology`** | Per-corner UVs written to a `loop_data` pool. No indexed-geometry exporter required. |
+| **Input** | **Clean + robust colocal/non-manifold welding; NO authored UVs** | New spatial colocal merge (xatlas `createColocals`). **Drops** the `OriginalUvCharts`/`useInputMeshUvs` path **and** the `textureSeamWeight` cost term (both derive from authored input UVs we will never have). |
+
+These three choices remove three whole xatlas subsystems (authored-UV ingest, original-UV charts,
+texture-seam metric) and pin two hard build targets (bitmap packer, LSCM). Everything below is sized
+to exactly this scope.
+
+---
+
+## 2. Pipeline at a glance
+
+```
+ComputeCharts (3D, topology-coupled)                  PackCharts (2D, bitmap)
+─────────────────────────────────────                ─────────────────────────────
+ingest indexed tris ─► BinaryTopology                 per-chart scale + rotate-to-OBB
+  + colocal weld (NEW)                                  + AABB / block-align
+precompute AtlasData (NEW)                            rasterize chart ─► BitImage2 (NEW)
+  face area/normal, edge len/dihedral                  + bilinear expand + dilate(padding)
+planar-region merge (union_find)                      sort charts by perimeter (radix)
+seed + grow charts (IndexedFloatMinHeap)              placement scan: canBlit shifted-OR (NEW)
+  cost = N + roundness + straightness + normalSeam      atlas pow2-grow / multi-page spill
+  validity gate per add (ortho + self-intersect)      OR-blit mask, chart.uv -> atlas space
+                                                       (loop_data write is the separate
+                                                        atlas_write_chart_uvs step)
+Lloyd relocate / fillHoles / mergeCharts
+per-chart parameterize:
+  ortho (no solve)  ──fail──►  LSCM (sparse CG, NEW)  ──fail──► piecewise re-segment
+write per-corner UVs to loop_data
+```
+
+The two halves meet at one in-memory artifact: a **`ChartSet`** — a list of charts, each holding its
+face list, its unified-vertex↔loop mapping, its proxy basis, its per-unified-vertex UVs, and its
+`surfaceArea`/`parametricArea`. `ComputeCharts` produces it; `PackCharts` consumes it and finalizes
+the loop_data UVs into atlas space.
+
+---
+
+## 3. Data model
+
+### 3.1 Mesh substrate — reuse `BinaryTopology` verbatim
+[`BinaryTopology`](struct/binary/BinaryTopology.js) is a Blender-BMesh model: **vertex / edge / loop /
+face** pools. A **loop is a per-corner slot** carrying `radial_next/prev` (edge-radial adjacency →
+opposite-face / boundary / manifold tests) and `next/prev` (face-cycle traversal). This is the direct
+analogue of xatlas's `Mesh` + `m_oppositeEdges`. **No structural changes needed.**
+
+Verified accessors we build on: `vertex_read/write_coordinate`, `vertex_read/write_normal`,
+`edge_read_vertex1/2`, `edge_read_loop`, disk-cycle `v1/v2_disk_next/prev`, `loop_read_vertex/edge/
+face/radial_next/prev/next/prev`, `face_read_loop`, `face_read/write_normal`.
+
+### 3.2 Per-corner UVs — reuse the optional `loop_data` pool
+`BinaryTopology.create_loop_data(item_size_bytes)` (verified, line 256) allocates an opaque per-loop
+data pool, ids 1:1 with loops. **UVs live here**: `item_size = 2 * Float32 = 8 bytes` (`u`, `v`).
+Two thin helpers (NEW): `bt_loop_write_uv(mesh, loop_id, u, v)` / `bt_loop_read_uv(out, off, mesh,
+loop_id)`. Seams are implicit: corners of one geometric vertex that belong to different charts are
+different loops, hence carry different UVs — exactly xatlas per-wedge output, for free.
+
+### 3.3 Derived attribute arrays — `AtlasData` (NEW, plain parallel typed arrays)
+xatlas precomputes per-element scalars once; we mirror with parallel `Float32Array`s keyed by element
+id (no new container, follows the meep "scatter into a flat typed array" idiom):
+
+| Array | Source | xatlas name |
+|---|---|---|
+| `face_area: Float32Array` | NEW pass (`tri3_area`) | `faceAreas` |
+| `face_normal` | reuse `bt_mesh_compute_face_normals` (writes into face pool) | `faceNormals` |
+| `edge_length: Float32Array` | NEW pass (`v3_distance_sqr`→sqrt) | `edgeLengths` |
+| `edge_dihedral: Float32Array` | NEW pass (`v3_dot` of adjacent face normals; `FLT_MAX` = boundary) | `edgeDihedralAngles` |
+
+`face_normal` exists; the other three are trivial one-pass kernels.
+
+### 3.4 Chart state — typed, not stringly (honours *typed-over-magic*, *no-null-defaults*)
+```
+class Chart {                       // core/geom/3d/atlas/segment/Chart.js
+  faces = new GrowableUint32Array() // face ids
+  type = CHART_TYPE.LSCM            // enum const, NOT a string
+  basis = new Float32Array(9)       // normal(3) tangent(3) bitangent(3)
+  area = 0; boundaryLength = 0
+  // unified vertex layer, filled at parameterization:
+  unified_of_loop = new GrowableUint32Array()   // loop_id -> chart-local unified vertex
+  uv = new GrowableFloat32Array()               // per unified vertex (u,v)
+  surfaceArea = 0; parametricArea = 0
+}
+const CHART_TYPE = { PLANAR: 0, ORTHO: 1, LSCM: 2, PIECEWISE: 3 };  // frozen
+```
+
+---
+
+## 4. Module layout
+
+Generic primitives stay in their natural homes (so they're reusable beyond the atlas); only the
+orchestration is atlas-specific. New trees: `core/geom/3d/atlas/`, `core/math/linalg/cg/`,
+`core/math/linalg/sparse/`.
+
+```
+core/geom/3d/atlas/
+  atlas_compute_charts.js              # driver: mesh -> charts (local UVs on chart.uv; no mesh write)
+  atlas_write_chart_uvs.js             # actualize chart UVs onto a mesh's loop_data (per source mesh)
+  atlas_generate.js                    # one-call single mesh: compute -> pack -> write_chart_uvs
+  ChartSet.js  Chart.js                # state structs + CHART_TYPE enum
+  data/
+    atlas_build_face_areas.js
+    atlas_build_edge_lengths.js
+    atlas_build_edge_dihedrals.js
+  io/
+    atlas_mesh_create_colocals.js      # spatial colocal weld (uf_* + SpatialHashGrid)
+    bt_loop_uv.js                      # bt_loop_read_uv / bt_loop_write_uv
+  segment/
+    atlas_compute_planar_regions.js    # union_find coplanar merge (stage 2)
+    atlas_place_seeds.js               # stage 3
+    atlas_segment_cost.js              # stage 4 cost (N + roundness + straightness + normalSeam)
+    atlas_grow_charts.js               # stage 6 global min-of-mins
+    atlas_relocate_seeds.js            # stage 8 Lloyd
+    atlas_fill_holes.js
+    atlas_merge_charts.js              # stage 9
+  param/
+    fit_plane_basis.js                 # stage 5 covariance + smallest-eigvec
+    atlas_chart_parameterize_ortho.js  # stage 7/11
+    atlas_chart_parameterize_lscm.js   # stage 12 (uses the sparse CG)
+    atlas_chart_param_validity.js      # flips + boundary self-intersection + stretch gate
+    atlas_chart_stretch_metric.js      # Sander/Hoppe L2 + Linf
+    atlas_piecewise_resegment.js       # stage 13
+  pack/
+    atlas_pack_charts.js               # driver: charts -> atlas (mutates chart.uv to atlas space; no mesh)
+    atlas_chart_oriented_box.js        # rotate-to-axis via hull + min-area rect
+    atlas_estimate_resolution.js       # P0 texelsPerUnit / resolution
+
+core/math/linalg/eigen/
+  matrix_symmetric_3x3_eigen.js        # NEW closed-form symmetric 3x3 eigen (vals+vecs)
+core/math/linalg/cg/
+  cg_solve_csr.js                      # NEW generic SPD conjugate gradient over a sparse operator
+  cg_solve_csr_jacobi.js              # NEW (optional) diagonal-preconditioned variant
+core/math/linalg/sparse/
+  SparseMatrixCSR.js                   # NEW rectangular CSR (rows x cols) for LSCM A
+  spm_matvec.js  spm_matvec_transpose.js
+  cg_solve_normal_equations.js         # NEW matrix-free A^T A solve, reuses cg core
+
+core/binary/
+  BitImage2.js                         # NEW 2D bit raster: canBlit/or_blit/dilate/grow/cardinality
+core/geom/2d/triangle/
+  tri2_rasterize_conservative.js       # NEW conservative tri -> BitImage2 coverage
+core/geom/2d/segment/
+  seg2_intersect.js                    # NEW exact segment-segment test (if absent)
+core/geom/2d/oriented-box/
+  min_area_rect_2d.js                  # NEW rotating-calipers OBB over a hull
+core/geom/vec3/
+  v3_cotangent.js                      # NEW cotangent weight helper
+core/math/
+  nextPowerOfTwo.js                    # NEW trivial
+```
+
+---
+
+## 5. Reuse map (the "maximize reuse" deliverable)
+
+`reuse` = use as-is · `adapt` = thin wrapper · `new` = build · `drop` = out of scope per §1.
+
+### ComputeCharts
+| xatlas stage | meep mapping | verdict |
+|---|---|---|
+| 0 build atlas mesh | `bt_mesh_from_indexed_geometry`, `bt_mesh_compute_face_normals`, radial/disk accessors | **reuse** |
+| 0 colocal weld | `uf_init/uf_find/uf_union` + `SpatialHashGrid` (or `BVH`) → `atlas_mesh_create_colocals` | reuse + **new** driver |
+| 0 AtlasData | `tri3_area`, `v3_distance_sqr`, `v3_dot` → 3 one-pass kernels | **new** (trivial) |
+| 1 OriginalUvCharts | — | **drop** |
+| 2 planar regions | `uf_union` over coplanar (`v3_dot(n,n')≈1`) faces; areas scatter-add | reuse + **new** driver |
+| 3 placeSeeds | `IndexedFloatMinHeap` as per-chart CostQueue; `BitSet` ownership | reuse + **new** driver |
+| 4 cost metric | `v3_dot`/`v3_cross` + AtlasData; `textureSeam` term **dropped** | **new** formulas |
+| 5 chart basis fit | `matrix_symmetric_3x3_eigen` (smallest eigvec) + `v3_orthonormal_matrix_from_normal` → `fit_plane_basis` | **new** eigen + **new** wrapper |
+| 6 growCharts | per-chart `IndexedFloatMinHeap`, global min-of-mins; lazy-delete claimed faces | reuse + **new** driver |
+| 7 ortho validity | `tri2_signed_area` (flip), `SpatialHashGrid`+`shg_query_elements_line`+`seg2_intersect` (self-x) | reuse + **new** gate |
+| 8 relocate/iterate | small fixed-cap `IndexedFloatMinHeap`; reuse 3/5/6 | reuse + **new** loop |
+| 9 fillHoles/merge | chart adjacency over edges + stage-7 gate + `fit_plane_basis` | reuse + **new** driver |
+| 10 unified submesh | `uf_*` colocal weld per chart → unified vertices; loop↔unified map | reuse + **new** |
+| 11 ortho param + gate | `v3_dot` projection + `atlas_chart_stretch_metric` + validity gate | **new** |
+| 12 **LSCM** | `SparseMatrixCSR` + `cg_solve_normal_equations` + `v3_cotangent`; pins via `solve_linear_system_GEPP_2x2`; diameter pins via `bt_mesh_walk_boundary_loops` | **new** (the big one) |
+| 13 piecewise | region-grow + per-add gate (reuse 6/7) | **new** driver |
+| 14 output | write per-corner UVs to `loop_data` (`bt_loop_write_uv`) | **new** (thin) |
+
+### PackCharts (xatlas-grade bitmap path)
+| xatlas stage | meep mapping | verdict |
+|---|---|---|
+| P0 estimate res/texels | scalar + `nextPowerOfTwo` | **new** (trivial) |
+| P1 scale + rotate-to-axis + block | `convex_hull_monotone_2d` + `min_area_rect_2d`; `AABB2` | reuse + **new** OBB |
+| P2 sort by perimeter | float radix or `array_quick_sort_by_lookup_uint` | reuse / **new** radix |
+| P3 rasterize coverage | `tri2_rasterize_conservative` → `BitImage2` (+ transposed for rotation) | **new** |
+| P4 bilinear + dilate | `BitImage2.dilate(padding)`; bilinear via boundary hash-grid | **new** |
+| P5 placement scan | `BitImage2.canBlit` shifted-OR; brute-force/random | **new** |
+| P6 atlas grow / multi-page | `BitImage2.grow_preserving` + page list; `nextPowerOfTwo` | **new** |
+| P7 blit + write UVs + utilization | `BitImage2.or_blit` + `bt_loop_write_uv` | **new** |
+
+> `MaxRectanglesPacker` (real API `add/addMany/canAdd/resize/repack/clear` over `AABB2`) is **not** on
+> the xatlas-grade path — it's a *different* algorithm (max-rects free-list, no shifted-OR). It is kept
+> as a **test oracle**: pack the chart AABBs with it and assert the bitmap packer never does worse on
+> utilization, and `aabb2_validate_packing` for overlap sanity.
+
+---
+
+## 6. New primitives — signatures + per-file test plan
+
+All follow house style: one export per file, snake_case, result-first args, typed arrays, module-static
+scratch pools, `assert.*` guards (free in prod), `#private`, class fields, no `X|null` defaults.
+
+### 6.1 Numerics
+- **`matrix_symmetric_3x3_eigen(out_values, out_vectors, m)`** — closed-form symmetric 3×3
+  eigendecomposition (analytic, deterministic; xatlas `eigenSolveSymmetric3`). Returns 3 eigenvalues +
+  3 column eigenvectors. *Replaces* the wrong-axis `matrix_top_eigenvector_power_iteration` for the
+  plane fit (we need the **smallest**-eigenvalue eigenvector).
+  *Tests:* diagonal matrix → identity vectors; known covariance of a planar point set → smallest
+  eigvec ‖ plane normal (±sign); rotation-invariance; degenerate (rank-1) covariance handled.
+- **`cg_solve_csr(x, csr, diag, b, max_iterations, tolerance)`** — generic unpreconditioned CG for an
+  SPD operator `A = diag − offdiag(csr)` (cotangent Laplacian shape). Module-static `r/p/Ap` scratch
+  like the fluid PCG. Diagonal is a **separate `Float32Array`** (CSRGraph `vertex_weights` is Uint32 —
+  verified — so the float diagonal cannot live there).
+  *Tests:* 3×3 and 5×5 Laplacians with closed-form solution; symmetric RHS; iteration-count regression;
+  converges to tolerance; determinism (fixed reduction order).
+- **`cg_solve_csr_jacobi(...)`** — diagonal-preconditioned variant. **Deferred until measured** (build
+  only if plain CG iteration counts are bad on thin charts).
+- **`SparseMatrixCSR`** (`rows`, `cols`, `row_ptr`, `col_idx`, `values`) + **`spm_matvec(out, A, x)`** /
+  **`spm_matvec_transpose(out, A, x)`** — rectangular `A` for the LSCM least-squares system.
+  *Tests:* matvec vs dense reference on random small matrices; `(A^T x)·y == x·(A y)` adjoint identity.
+- **`cg_solve_normal_equations(x, A, b, max_iterations, tolerance)`** — matrix-free `AᵀA x = Aᵀb`
+  using `spm_matvec`/`spm_matvec_transpose` and the `cg_solve_csr` reduction core. The OpenNL
+  equivalent. *Tests:* overdetermined system with known least-squares solution; pinned-DOF handling.
+- **`v3_cotangent(ax,ay,az, bx,by,bz)`** → `cos/sin` of the angle between two edge vectors. The one
+  missing scalar (grep-confirmed absent). *Tests:* 90°→0, 45°→1, obtuse→negative.
+- **`nextPowerOfTwo(x)`** — trivial. *Tests:* boundaries, exact powers.
+
+### 6.2 Packing
+- **`BitImage2`** — `width`, `height`, word-aligned `Uint32Array` rows. Methods: `set/get`,
+  `canBlit(other, x, y)` (per-row shifted-OR AND collision, **trailing-word masked**), `or_blit(other,
+  x, y)`, `dilate(passes)` (3×3 OR), `cardinality()`, `grow_preserving(w, h)` (**re-strides every
+  row** — the one subtle trap), `reset()`.
+  *Tests:* explicit **truth tables** for `canBlit` (touching vs overlapping vs adjacent, across word
+  boundaries), `dilate` 1-pass result, `grow_preserving` content preservation when row stride changes,
+  blit-then-canBlit round-trip.
+- **`tri2_rasterize_conservative(image, x0,y0, x1,y1, x2,y2)`** — conservative (super-coverage) tri
+  rasterization into a `BitImage2`. *Tests:* axis triangle exact mask; conservative ⊇ center-sampled;
+  degenerate/zero-area no-crash.
+- **`min_area_rect_2d(out, hull_points, count)`** — rotating-calipers minimum-area OBB → angle + extents.
+  *Tests:* axis-aligned rect → 0°; rotated rect → recovers angle; vs brute-force on random hulls.
+- **`seg2_intersect(ax,ay,bx,by, cx,cy,dx,dy)`** — exact segment-segment intersection (orientation
+  predicates). *Tests:* crossing, collinear-overlap, shared-endpoint, disjoint.
+
+### 6.3 Atlas drivers
+Each `atlas_*` driver is a pure function over the mesh + AtlasData + ChartSet (no hidden state),
+individually unit-testable on small inline meshes. See §8.
+
+---
+
+## 7. Phased milestones
+
+Each milestone is independently shippable, ends with a **standing spec gate**, and only depends on
+earlier ones. Ordering puts reusable numerics first, then the two pipelines bottom-up, so every phase
+is testable in isolation before integration.
+
+Legend: ✅ done · ⏳ Phase 2 (§12). Actual file names note where the build superseded a tentative plan
+name. Per-milestone test counts in parentheses; total **18 suites / 72 tests**.
+
+- **M0 — Numerics foundation. ✅ (23).** `matrix_symmetric_3x3_eigen` (Jacobi), `cg_solve` (generic
+  matrix-free SPD CG via an `apply_A` callback — supersedes `cg_solve_csr`; serves LSCM *and* any
+  Laplacian), `SparseMatrixCSR` + `spm_matvec`/`spm_matvec_transpose`, `cg_solve_normal_equations`,
+  `v3_cotangent`. `nextPowerOfTwo` dropped — reused existing `ceilPowerOfTwo`. *Gate met:* closed-form
+  solves (1D Laplacian, least-squares, analytic eigen). The LSCM-solver unknown is fully retired.
+- **M1 — Mesh prep. ✅ (9).** `atlas_mesh_weld_colocals` (reuses the navmesh
+  `bt_merge_vertices_by_distance` → `bt_mesh_fuse_duplicate_edges` → T-junction sequence — supersedes a
+  from-scratch `create_colocals`), `atlas_build_{face_areas,edge_lengths,edge_dihedrals}`, `bt_loop_uv`.
+  Dihedral stores adjacent-normal **dot** (1=flat, 0=90°, sentinel `2` for boundary). *Gate met.*
+- **M2 — Planar segmentation. ✅ (6).** `fit_plane_basis`, `atlas_compute_planar_regions`. *Gate met:*
+  cube → 6 regions, fitted normals ‖ face normals.
+- **M3 — General segmentation. ✅ (5).** One driver `atlas_segment_charts` (greedy seed+grow,
+  lazy-re-eval min-heap, cost = `wN·N + wNS·NS + wR·roundness`, 73° hard reject). Face-granular;
+  region-atomic growth + Lloyd relocation + `mergeCharts` are ⏳ backlog. *Gate met:* coverage,
+  deterministic count, maxCost-monotone.
+- **M4 — Ortho + validity. ✅ (5).** `atlas_extract_chart`, `atlas_chart_parameterize_ortho`,
+  `atlas_chart_param_validity`, `atlas_chart_stretch_metric`. *Gate met.*
+- **M5 — LSCM. ✅ (4).** `atlas_chart_parameterize_lscm` — true Cauchy-Riemann least-squares
+  (two diameter pins, **1/√area weights, not cotangent weights** → obtuse-cotangent non-SPD risk does
+  not arise), solved via M0. *Gate met:* rescues a developable ribbon ortho can't flatten.
+- **M6 — Integration + piecewise. ✅ (3).** `atlas_compute_charts` + `CHART_TYPE`. Fallback is
+  region-grow piecewise (✅ M11). *Gate met.*
+- **M7 — Bitmap packer core. ✅ (9).** `BitImage2` (in `core/binary/`), `tri2_rasterize_conservative`
+  (SAT). `seg2_intersect` dropped — reused `segment2_intersects_segment2_2d`. `min_area_rect_2d` →
+  ⏳ M10. *Gate met:* truth tables.
+- **M8 — Pack driver. ✅ (5).** `atlas_pack_charts` (P0 auto-resolution, P1 scale, P3–P4 raster+dilate,
+  P5 bottom-left `canBlit` first-fit, P6 pow2 grow, P7 write-back). Chart rotation ✅ M10; multi-page +
+  blockAlign ⏳ backlog. *Gate met:* `occupied == Σ masks` (provable no-overlap), UVs ∈ [0,1],
+  deterministic.
+- **M9 — One-call API + e2e. ✅ (5).** `atlas_generate`; integration across cube, closed octahedron,
+  LSCM ribbon, welded split mesh. Benches ⏳ backlog. *Gate met.*
+
+**Critical path / parallelism:** M0 was the de-risking spike — done first and alone. M1→M6 (ComputeCharts)
+and M7→M8 (PackCharts) were largely independent after M0; they join at M9.
+
+---
+
+## 8. Testing strategy (the "very testable" deliverable)
+
+Honours the standing feedback: **black-box only** (assert observable output, never call-counts/private
+paths), **no mocks** (real `BinaryTopology`, real heaps/union-find), **run from `H:/git/moh`** with the
+root `jest.conf.json`, **no `.d.ts`**, asserts are compiled out of prod so they're free.
+
+- **Inline mesh fixtures** (small builders returning indexed geometry, colocated in spec files): unit
+  quad, cube, cube-with-duplicated-verts (colocal test), open disk (one cube face), cylinder (seam),
+  saddle/hemisphere (LSCM), torus (multi-chart), one degenerate-triangle mesh (robustness).
+- **Property-based invariants** rather than golden numbers where possible:
+  - Segmentation: partition is a **cover** (∪ charts = all faces, pairwise disjoint); chart count is a
+    deterministic function of mesh+options.
+  - Parameterization: **bijectivity** (zero flipped faces via `tri2_signed_area` sign agreement), **no
+    boundary self-intersection** (the validity gate), **bounded stretch** (`stretch ≤ 1.1`, `maxStretch
+    ≤ 1.25` to accept ortho; LSCM below a looser bound).
+  - Packing: **no two charts' texels overlap** (re-rasterize the final atlas, assert each texel covered
+    ≤ once), all UVs ∈ [0,1]² after normalization, utilization ≥ oracle.
+- **Determinism gate** (meep has a standing determinism contract): fixed CSR-row / lex reduction order
+  in CG; fixed seed-face order (union-by-min-index already deterministic); fixed sort; no wall-clock
+  early-exit. A spec runs the full pipeline twice and asserts bit-identical UVs.
+- **Numerics specs** assert against closed-form solutions (Laplace on a line/grid, least-squares of an
+  overdetermined system, analytic 3×3 eigen) — not against the implementation.
+- **Benches** as `.bench.spec.js` (matches `bakeVisibility.bench.spec.js` precedent): segmentation
+  ms/face, CG iters/solve, pack ms + utilization%.
+
+---
+
+## 9. Risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| **Cotangent weights go negative** on obtuse triangles → Laplacian non-SPD → CG breaks. *(top correctness risk)* | Clamp negative cotangents to 0, or fall to **mean-value weights** (unconditionally positive, valid Tutte embedding); detect non-convergence → ortho/piecewise fallback. Decide the default in M5 with a spec on an obtuse-heavy chart. |
+| **CG perf in V8** (fluid PCG header documents loop-overhead-bound, PCG slower per-iter than SOR). | Charts are far smaller than a 64³ grid; keep the CG kernel tight (typed arrays, inlined SpMV option, no per-iter closures). Hold `cg_solve_csr_jacobi` in reserve, gated on measured iteration counts (M5/M9). |
+| **`BitImage2.grow_preserving` re-stride bug** — naive linear copy corrupts when row word-width changes. | Explicit re-stride; truth-table spec that grows across a word boundary and checks every bit (M7). |
+| **`canBlit` trailing-word mask** off-by-one silently overlaps charts. | Mask partial trailing word; truth-table specs across word boundaries; final-atlas disjoint-coverage assertion in M8. |
+| **Data-model bridging** (xatlas face-varying ↔ meep topology). | Resolved by §3: per-corner UVs on `loop_data`, per-chart unified-vertex layer via `uf_*`, loop↔unified map. Validated end-to-end at M6. |
+| **Non-manifold / colocal input** (in scope). | `atlas_mesh_create_colocals` (uf + spatial hash) up front; radial cycle already handles n-radial loops; boundary = single-radial-loop test. Spec with a duplicated-vertex and a >2-faces-per-edge mesh (M1). |
+| **No-boundary charts** (closed genus-0) — LSCM has no pins. | Match xatlas: abandon LSCM, route to piecewise re-segment (which introduces boundaries). Spec a closed sphere chart (M5/M6). |
+| **Determinism drift** from float reductions. | Fixed iteration order everywhere; determinism spec is the standing gate (M9). |
+
+---
+
+## 10. Out of scope (deferred, with reasons)
+
+- **Authored-UV ingest / `OriginalUvCharts` / `useInputMeshUvs`** — user excluded; we always re-segment.
+- **`textureSeamWeight` cost term** — derives from authored UVs we never have; the cost metric is
+  `normalDeviationWeight·N + roundnessWeight·R + straightnessWeight·S + normalSeamWeight·NS`.
+- **`createImage` (RGBA atlas rasterization)** — not requested; loop_data UVs are the output. (Trivial
+  to add later on `tri2_rasterize_conservative`.)
+- **Indexed-geometry exporter** — user chose in-place loop_data output. (A `bt_mesh_to_indexed_geometry`
+  with a UV channel is a clean follow-up if a second consumer appears.)
+- **GPU/WASM packer or solver** — JS first; the fluid PCG header notes the perf calculus flips under
+  SIMD/WebGPU, revisit then.
+
+---
+
+## 11. Open items to confirm during M0–M1
+
+1. **Cotangent fallback default** — clamp-to-zero vs mean-value (pick in M5; mean-value is the safer default).
+2. **SpMV inline vs separate file** — house style favors separate `spm_matvec`; fluid PCG inlines for V8
+   speed. Measure in M0; inline only if the bench demands it.
+3. **`BitImage2` home** — `core/binary/` (next to `BitSet`, generic) vs `core/geom/2d/`. Plan picks
+   `core/binary/` since it's a generic 2D bit raster; revisit if only the atlas ever uses it.
+4. **Colocal spatial index** — `SpatialHashGrid` (simpler) vs `BVH` (xatlas `createColocalsBVH`). Start
+   with the hash grid; swap to BVH only if welding shows up in profiles.
+
+**Resolutions (after M0–M9):** (1) cotangent fallback is **moot** — the implemented LSCM uses
+Cauchy-Riemann 1/√area weights, not cotangent weights, so the obtuse-triangle non-SPD risk never arises;
+`v3_cotangent` stays as a utility for a future harmonic-map variant. (2) SpMV is a **separate file**
+(`spm_matvec`) per house style; perf is ample at chart sizes. (3) `BitImage2` lives in **`core/binary/`**.
+(4) Colocal welding reuses **`bt_merge_vertices_by_distance`** (its own internal hash grid), not a new
+spatial index.
+
+---
+
+## 12. Phase 2 — refinements
+
+Layered on the green M0–M9 core. Each is opt-in (behind an option) or a drop-in replacement, and must
+preserve the standing invariants: disjoint packing (`occupied == Σ masks`), bijective charts,
+determinism, all-UVs ∈ [0,1].
+
+### M10 — Chart rotation in the packer ✅ (done)
+Two xatlas `PackOptions`, both raising atlas density:
+- **`rotateChartsToAxis`** (default true): before scaling, rotate each chart's UVs so its
+  minimum-area oriented box is axis-aligned, shrinking its footprint. New
+  `core/geom/2d/oriented-box/min_area_rect_2d.js` — rotating calipers over `convex_hull_monotone_2d`
+  of the chart UVs, returning the box angle; apply the inverse rotation to `chart.uv` (rigid → validity
+  and stretch unchanged). *Tests:* axis-aligned rect → 0°; rotated rect → recovers angle + area; vs a
+  brute-force angle sweep on random hulls; a diagonal chart's AABB area shrinks after alignment.
+- **`rotateCharts`** (default true): allow a 90° orientation at placement. New `BitImage2.transposed()`
+  builds the swapped-axis mask; the placement scan tries both orientations and keeps the better fit,
+  recording the choice; UV write-back swaps `(tu,tv)` for rotated charts (a transpose — self-consistent
+  since we author the UVs, no external texture to mirror). *Tests:* a tall-thin chart set packs no
+  larger with rotation on; `occupied == Σ masks` still holds; determinism preserved.
+
+*Gate:* on a mixed-aspect chart fixture, `utilization(on) ≥ utilization(off)`, atlas no larger, all
+standing pack invariants hold.
+
+### M11 — Region-grow piecewise re-segmentation ✅ (done)
+Replace the single-triangle explode fallback with xatlas `PiecewiseParam`. New
+`param/atlas_piecewise_resegment.js`: build triangle adjacency within the invalid chart, then greedily
+grow connected sub-charts from a seed triangle, ortho-projecting and validating (flip + boundary
+self-intersection) after each tentative add; reject a triangle that breaks validity, finalize a
+sub-chart when no neighbour can be added, repeat until every triangle is covered. Each sub-chart is
+connected and ortho-valid by construction (a lone seed triangle is always valid → termination). Wired
+into `atlas_compute_charts` in place of the explode. *Tests:* a chart LSCM leaves invalid splits into
+≥2 connected, bijective sub-charts covering every triangle exactly once; an already-valid chart returns
+as one piece; fewer/larger pieces than the explode.
+
+### Backlog (not yet scheduled)
+- ✅ **Region-atomic segmentation** — M12. (Lloyd seed relocation + `mergeCharts` still open for more
+  balanced charts / fewer seams.)
+- ✅ **Placement-scan acceleration** — M14 skyline packer.
+- ✅ **Multi-atlas pages** — M13. (`blockAlign` 4×4 for BC/DXT still open.)
+- ✅ **Benchmarks** — M14.
+- ✅ **Chart extraction O(charts × faces)** — fixed: one face-bucket pass + reused version-stamped
+  vertex map → O(faces). 92.8s → 35.9s (2.6×) on a 150k-tri scene.
+- **Compute performance** *(bench finding, large-scene bench)* — at scale, **mesh conditioning**
+  dominates (~75%): profile the weld sequence (`atlas_mesh_weld_colocals` → colocal merge +
+  `bt_mesh_resolve_t_junctions`) and the edge-data builds. **LSCM is ~20%** (many curved charts; see
+  CG preconditioner / warm-start below). The boundary self-intersection check is O(boundary²).
+  *(User-deferred 2026-06-25: bench is the standing quantifier; revisit as its own task.)*
+- ~~**Closed-surface robustness**~~ — was a bench fixture bug (degenerate sphere poles), not a tool
+  bug; a clean closed sphere segments into 4 charts. Retracted. Degenerate-triangle robustness is now
+  covered by an end-to-end test (`atlas_generate.spec`).
+- **CG preconditioner** — Jacobi/IC `cg_solve` variant if large/thin charts show high iteration counts.
+- **`createImage`** — optional RGBA atlas rasterization via `tri2_rasterize_conservative`.