1# CLAUDE.md
3Tips for future agents working in this repo.
5## Architecture
7```
8matlab/
9 solve_template.m the whole solve as ONE script — mip load -> import ->
10 resample -> surfaceop -> write result.json — with
11 {{PLACEHOLDER}} tokens for the parameters. The engine's
12 buildSolveScript fills them per solve, and the UI offers
13 the filled script for download any time a mesh is loaded
14 (before solving too — a solve might fail or hang). The
15 same script runs in desktop MATLAB with the converted
16 .msh alongside: via mip, or by commenting out the mip
17 line and putting surfacefun on the path.
18src/mesh/ Pyodide + meshio upload pipeline (bridge.py runs in Pyodide)
19src/engine/ run-per-solve wrapper over numbl/browser's
20 createNumblSession: solve() fills the template and boots
21 a fresh session with the script + mesh staged, reads
22 result.json back via session.readFile, and disposes the
23 worker. numbl owns the worker, VFS, mip bootstrap, and
24 IndexedDB package persistence; prewarm() at page load
25 triggers the one-time package download.
26src/pde/presets.ts PDE definitions, presets, slow-mesh warning threshold
27src/render/ three.js SurfaceView (mesh preview / solution) + parula
28scripts/engine-test.mjs headless Node check of the whole MATLAB pipeline
29```
31## Key gotchas
33- **numbl >= 0.4.12 from npm.** Needs `NumblSession.readFile` (0.4.10),
34 enumeration-class support and the 1×1-tensor broadcast-assignment fix
35 (0.4.11 — surfacefun's `surfacemesh.patchtype` / `dealm` idiom depend on
36 both), and the 1×1-tensor gather-orientation fix (0.4.12 — surfacefun's
37 `trianglepts` recursion breaks without it; see numbl's
38 `test_scalar_tensor_vector_index_shape.m`). To develop against a local
39 numbl checkout, point package.json at
40 `file:../../numbl` and run `npm run build:lib && npm run build:browser`
41 there after source changes; when switching back to a `^` range,
42 `rm -rf node_modules package-lock.json && npm install` (else `npm ci` fails
43 on the stale `file:` link).
44- **surfacemesh.import needs MSH 4.1, one cell type.** surfacefun's gmsh
45 reader (`+surfacemesh/+import/gmsh.m`) parses MSH 4.1 node-entity blocks,
46 not 2.2, and accepts triangle (type 2) or quad (type 3) elements — but
47 errors on meshes containing both. `src/mesh/bridge.py` and
48 `scripts/make_samples.py` write the canonical 4.1 form (one surface entity
49 block, sequential 1-based ids); the bridge splits quads into triangles
50 when an upload mixes the two kinds. Uploaded .msh files in other layouts
51 pass through meshio and get rewritten to 4.1.
52- **Triangle patches are flat vectors, not grids.** An order-p tri patch
53 holds n(n+1)/2 points (n = p+1) in surfacefun's `trianglepts(n)` ordering;
54 quad patches are column-major n-by-n grids. `solve_template.m` reports
55 `ptype` plus points-per-edge `n`, and SurfaceView triangulates tri patches
56 with a JS port of surfacefun's `trilattice.m`.
57- **Solve errors reject the solve() promise** with the MATLAB error message
58 (a failed script run is a numbl bootError). Each solve is a fresh session,
59 so nothing needs to stay alive across failures.
60- **jsonencode collapses 1-element vectors to scalars.** Patch arrays are
61 at least (p+1)(p+2)/2 >= 6 long so it never bites here, but remember it
62 when adding payload fields.
63- Package caching: numbl/browser persists /system (mip + installed
64 packages) in IndexedDB, wiped after 30 min of inactivity (numbl's default;
65 lowered from 24 h so a rebuilt surfacefun package refreshes without a manual
66 clear) — the prewarm session at page load re-downloads ~28 MB after a wipe;
67 solves after that only pay a per-run `mip load` (~1 s). Delete the
68 `numbl-embed-system` IndexedDB database to force a cold boot.
70## Testing
72- `npm run engine-test` — full headless solve in Node against the local
73 numbl build (dist-lib), including a quantitative eigenfunction check. It
74 fills and runs matlab/solve_template.m standalone per solve (as the
75 browser does; the fill logic mirrors engine.ts's buildSolveScript), sharing
76 one VFS across solves as the stand-in for IndexedDB persistence, and
77 passes the mip search path explicitly, exercising the same
78 searchPaths-scan behavior the numbl/browser session relies on. Downloads
79 are cached in `.cache/` keyed by URL; delete the cache to test fresh
80 installs.
81- `python3 <venv>/bin/python` with meshio 5.3.5 can exercise
82 `src/mesh/bridge.py` outside Pyodide (redirect its `/work` constant).
83- Browser verification (Pyodide upload path, session boot, IndexedDB
84 persistence across reloads, 3D view) is manual: `npm run dev`.