CLAUDE.md#

Tips for future agents working in this repo.

Architecture#

matlab/            the MATLAB project the numbl session runs
  main.m           `mip load --install surfacefun` -> solver_session()
  solver_session.m opens the placeholder uihtml figure (the event bridge)
  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/        thin wrapper over numbl/browser's createNumblSession:
                   the app-level solve protocol (mesh.msh + 'solve' events,
                   one in flight, timeout). numbl owns the worker, VFS, mip
                   bootstrap, and IndexedDB package persistence.
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.9 from npm (numbl/browser entry, executeCode searchPaths scanning, and the flip/fieldnames/containers.Map compat fixes all 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-time errors are recoverable: solver_session catches them and sends a solveError event; the uihtml session stays live for the next solve. Boot errors and dispatch-level interpreter errors are surfaced by the engine wrapper.
• 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 — first solve of a fresh day re-downloads ~28 MB. 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 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.