# CLAUDE.md

Tips for future agents working in this repo.

## Architecture

```
matlab/            the MATLAB project each solve runs standalone
  main.m           `mip load --install surfacefun` -> jsondecode params.json
                   -> solve_pde('mesh.msh', params) -> write result.json
  solve_pde.m      mesh -> surfacemesh -> resample -> surfaceop -> per-patch data
  load_gmsh_quads.m       minimal MSH 2.2 ASCII reader (canonical form only)
  surfacemesh_from_quads.m  replaces surfacemesh.fromGmsh (see below)
src/mesh/          Pyodide + meshio upload pipeline (bridge.py runs in Pyodide)
src/engine/        run-per-solve wrapper over numbl/browser's
                   createNumblSession: solve() boots a fresh session with
                   mesh.msh + params.json staged, reads result.json back via
                   session.readFile, and disposes the worker. numbl owns the
                   worker, VFS, mip bootstrap, and IndexedDB package
                   persistence; prewarm() at page load triggers the one-time
                   package download.
src/pde/presets.ts PDE definitions, presets, size limits
src/render/        three.js SurfaceView (mesh preview / solution) + parula
scripts/engine-test.mjs  headless Node check of the whole MATLAB pipeline
```

## Key gotchas

- **numbl >= 0.4.10 from npm** (`NumblSession.readFile`, which the engine
  uses to fetch result.json, landed in 0.4.10; the `numbl/browser` entry and
  executeCode searchPaths scanning landed in 0.4.9). To develop against a
  local numbl checkout, point package.json at `file:../../numbl` and run
  `npm run build:lib && npm run build:browser` there after source changes.
- **surfacemesh.fromGmsh is not used.** It locates the QUADS field via
  `startsWith(fieldnames(...), 'QUADS')` (cellstr startsWith — unsupported in
  numbl) and handles high-order gmsh quads. Our converter only emits 4-node
  quads, so `surfacemesh_from_quads.m` builds the 2x2 patches directly.
- **Canonical .msh only.** `load_gmsh_quads.m` assumes what
  `src/mesh/bridge.py` writes: MSH 2.2 ASCII, sequential 1-based node ids,
  type-3 elements, two tags. Uploaded .msh files in other layouts are fine —
  they pass through meshio and get rewritten canonically.
- **Solve errors reject the solve() promise** with the MATLAB error message
  (a failed script run is a numbl bootError). Each solve is a fresh session,
  so nothing needs to stay alive across failures.
- **jsonencode collapses 1-element vectors to scalars.** Patch arrays are
  (p+1)^2 >= 9 long so it never bites here, but remember it when adding
  payload fields.
- Package caching: numbl/browser persists /system (mip + installed
  packages) in IndexedDB, wiped after 24 h of inactivity — the prewarm
  session at page load re-downloads ~28 MB on a fresh day; solves after
  that only pay a per-run `mip load` (~1 s). Delete the
  `numbl-embed-system` IndexedDB database to test cold boots.

## Testing

- `npm run engine-test` — full headless solve in Node against the local
  numbl build (dist-lib), including a quantitative eigenfunction check. It
  runs matlab/main.m standalone per solve (as the browser does), sharing
  one VFS across solves as the stand-in for IndexedDB persistence, and
  passes the mip search path explicitly, exercising the same
  searchPaths-scan behavior the numbl/browser session relies on. Downloads
  are cached in `.cache/` keyed by URL; delete the cache to test fresh
  installs.
- `python3 <venv>/bin/python` with meshio 5.3.5 can exercise
  `src/mesh/bridge.py` outside Pyodide (redirect its `/work` constant).
- Browser verification (Pyodide upload path, session boot, IndexedDB
  persistence across reloads, 3D view) is manual: `npm run dev`.