Skip to content

99 K1: headless mesh kernel (src/lib/meshKernel/, not wired in) - #588

Open
AlexZ005 wants to merge 5 commits into
mainfrom
feat/99-kernel
Open

AlexZ005 wants to merge 5 commits into
mainfrom
feat/99-kernel

Conversation

@AlexZ005

@AlexZ005 AlexZ005 commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Roadmap 99 K1: a headless mesh kernel in src/lib/meshKernel/. Nothing imports it yet: no editor behaviour changes, nothing in src/ outside the new folder. It rides the next int and has no release of its own.

What it is

  • A face-vertex mesh in flat typed arrays (BMesh disk + radial cycles), with no three.js in the core (it runs in node, a Worker or the page). three.js is the one adapter that imports three.
  • Stable vertex / edge / face IDs: a slot is never reused until compact(), which returns old→new maps.
  • n-gons, per-corner attributes (uv, normal, colour, anything), material per face, a CSR spatial hash.
  • Triangulation is output only: a per-face cache with order keys, so geometry → kernel → geometry is value-identical.
  • Edits: splitEdge, splitFace, dissolveEdge, mergeVertices, collapseEdge, weldByDistance, flipFace, plus removals.
  • Adapters: BufferGeometry ⇄ kernel, kernel ⇄ the CSR __topo packing, and the meshgeo payload, with optional ID channels.
  • The one-page API is src/lib/meshKernel/API.md.

Findings

  • __topo survives GLTF autosave for a single-material mesh (GLTFExporter writes userData as primitive extras and GLTFLoader reads them back). A multi-slot mesh is split per group; those copies fail facesValidFor and are dropped, and the toJSON sidecar keeps the partition. CLAUDE.md said the opposite and is corrected.
  • Every mesh of every scene round-trips value-identically: 50 scenes, 1818 meshes, 245138 triangles (scenes repo, templates and fixtures). None of them carries __topo today.

Node bench (Ryzen Z2 Extreme, node 24)

tris kernel build build + weld 1e-4 today enter-edit kernel B/tri today heap B/tri
10k 32 ms 33 ms 114 ms 195 797
67k 60 ms 156 ms 879 ms 195 687
100k 74 ms 220 ms 1304 ms 195 686
1M 678 ms 2114 ms 17795 ms 195 689

"today enter-edit" is readTriangles + groupFaces + pairQuads on the same sphere soup. The full table (one-ring, output, quad-topo import, dissolve to quads, spatial hash) is printed by NODE_OPTIONS='--expose-gc' npx vitest run --config tests/bench/vitest.bench.config.js. The browser runner (tests/bench/meshKernelBrowser.cjs) runs the same module on a dev server through a Playwright route, since vite does not serve tests/.

Deck browser bench (HeadlessChrome 156, same module)

tris kernel build build + weld 1e-4 today enter-edit kernel B/tri today heap B/tri
10k 23 ms 39 ms 139 ms 195 472
67k 49 ms 183 ms 678 ms 195 406
100k 63 ms 246 ms 1078 ms 195 407
1M 603 ms 2437 ms not run 195 n/a

Test plan

  • tests/unit/meshKernel.test.js: 53 tests. Seeded property tests (Euler characteristic, manifold check, ID stability across random edits, validate() after every step), plus a 300-seed × 300-step stress run (green).
  • tests/unit/meshKernelScenes.test.js: round trip of every scene mesh (SCENES_DIR).
  • tests/unit/meshKernelGltfTopo.test.js: GLTFExporter → GLTFLoader.
  • Full unit run, 5403 green; check-ratchet 274/37 = baseline; check:tokens clean; npm run build green.

🤖 Generated with Claude Code

AlexZ005 and others added 5 commits November 21, 2026 18:07
A face-vertex mesh with full adjacency in flat typed arrays (BMesh's disk and
radial cycles, flattened), pure JS with no three.js import in the core, so it
runs in node, a Worker and the page. Stable vertex / edge / face IDs (slots,
never reused until compact(), which returns old -> new maps), n-gons, per-corner
attributes (uv, normal, colour, any attribute), material slot per face, a CSR
spatial hash, and triangulation only as output (a per-face cache in local corner
indices with an order key, so an imported mesh re-emits its source triangles).

Euler-style edits for K4 to build on: splitEdge, splitFace, dissolveEdge,
mergeVertices, collapseEdge, flipFace, remove*, weldByDistance (neighbour cells,
so pairs across a cell wall merge). validate() checks every invariant.

Adapters: plain arrays <-> kernel (lossless: exact weld, stored partition ->
n-gons, source order kept), BufferGeometry by duck type, kernel -> BufferGeometry
(three.js, the one file importing it), the CSR face packing and the meshgeo
payload, with optional vertex / face ID channels so a receiver rebuilds the
sender's IDs.

Nothing in the app imports it yet: no editor behaviour change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
meshKernelScenes: every geometry of every .tpscene in the templates, the
fixtures and SCENES_DIR goes geometry -> kernel -> geometry and must come back
value-identical (every attribute de-indexed, per-triangle material slot, the
stored partition), then through the meshgeo wire with IDs. Scenes repo 3d3c99c
+ templates + fixtures: 50 scenes, 1818 meshes, 245138 triangles, all equal.

meshKernelGltfTopo: measured answer to "does __topo survive the GLTF autosave
path": YES for a single-material mesh (geometry.userData rides as primitive
extras and validates on load); a multi-slot mesh is split into per-group
primitives whose copies fail validation and are dropped (never trusted), and
autosave restores those from the toJSON multiMaterial sidecar, which keeps it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tests/bench/: one bench module run by node (vitest bench config, outside the unit run) and by
the browser through the vite dev server. Sphere soups and quad grids at 10k / 67k / 100k / 1M
triangles; kernel build, weld 1e-4, one-ring, output, quad-topo import, dissolve-to-quads,
spatial hash, against today's readTriangles + groupFaces + pairQuads.
Kernel: import weld via the SpatialHash, trim() after import, allocation-free bucket dedupe.
src/lib/meshKernel/API.md: the one-page API. CLAUDE.md: GLTF autosave DOES carry __topo for a
single-material mesh (measured); meshKernel entry; index regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…fuses tests/)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant