1# CLAUDE.md
3Tips for future agents working in this repo.
5## Architecture
7```
8matlab/ the MATLAB project the numbl session runs
9 main.m `mip load --install surfacefun` -> solver_session()
10 solver_session.m opens the placeholder uihtml figure (the event bridge)
11 solve_pde.m mesh -> surfacemesh -> resample -> surfaceop -> per-patch data
12 load_gmsh_quads.m minimal MSH 2.2 ASCII reader (canonical form only)
13 surfacemesh_from_quads.m replaces surfacemesh.fromGmsh (see below)
14src/mesh/ Pyodide + meshio upload pipeline (bridge.py runs in Pyodide)
15src/engine/ thin wrapper over numbl/browser's createNumblSession:
16 the app-level solve protocol (mesh.msh + 'solve' events,
17 one in flight, timeout). numbl owns the worker, VFS, mip
18 bootstrap, and IndexedDB package persistence.
19src/pde/presets.ts PDE definitions, presets, size limits
20src/render/ three.js SurfaceView (mesh preview / solution) + parula
21scripts/engine-test.mjs headless Node check of the whole MATLAB pipeline
22```
24## Key gotchas
26- **numbl >= 0.4.9 from npm** (`numbl/browser` entry, executeCode
27 searchPaths scanning, and the flip/fieldnames/containers.Map compat fixes
28 all landed in 0.4.9). To develop against a local numbl checkout, point
29 package.json at `file:../../numbl` and run
30 `npm run build:lib && npm run build:browser` there after source changes.
31- **surfacemesh.fromGmsh is not used.** It locates the QUADS field via
32 `startsWith(fieldnames(...), 'QUADS')` (cellstr startsWith — unsupported in
33 numbl) and handles high-order gmsh quads. Our converter only emits 4-node
34 quads, so `surfacemesh_from_quads.m` builds the 2x2 patches directly.
35- **Canonical .msh only.** `load_gmsh_quads.m` assumes what
36 `src/mesh/bridge.py` writes: MSH 2.2 ASCII, sequential 1-based node ids,
37 type-3 elements, two tags. Uploaded .msh files in other layouts are fine —
38 they pass through meshio and get rewritten canonically.
39- **Solve-time errors are recoverable**: solver_session catches them and
40 sends a `solveError` event; the uihtml session stays live for the next
41 solve. Boot errors and dispatch-level interpreter errors are surfaced by
42 the engine wrapper.
43- **jsonencode collapses 1-element vectors to scalars.** Patch arrays are
44 (p+1)^2 >= 9 long so it never bites here, but remember it when adding
45 payload fields.
46- Package caching: numbl/browser persists /system (mip + installed
47 packages) in IndexedDB, wiped after 24 h of inactivity — first solve of a
48 fresh day re-downloads ~28 MB. Delete the `numbl-embed-system` IndexedDB
49 database to test cold boots.
51## Testing
53- `npm run engine-test` — full headless solve in Node against the local
54 numbl build (dist-lib), including a quantitative eigenfunction check. It
55 passes the mip search path explicitly, exercising the same
56 searchPaths-scan behavior the numbl/browser session relies on. Downloads
57 are cached in `.cache/` keyed by URL; delete the cache to test fresh
58 installs.
59- `python3 <venv>/bin/python` with meshio 5.3.5 can exercise
60 `src/mesh/bridge.py` outside Pyodide (redirect its `/work` constant).
61- Browser verification (Pyodide upload path, session boot, IndexedDB
62 persistence across reloads, 3D view) is manual: `npm run dev`.