1# CLAUDE.md
3Tips for future agents working in this repo.
5## Architecture
7- `app/` — React/Three.js single-file widget (`npm run build` → `app/dist/index.html`)
8- `*.m` at root — MATLAB scripts users open and run in [numbl](https://numbl.org)
9- `numbl-project.json` — project metadata; `entry` is the landing page
11## Data flow
13**MATLAB → figure:** set `uihtml(..., 'Data', struct)` or call `sendEventToHTMLSource(src, 'eventName', data)`
15**Figure → MATLAB:** call `sendToMATLAB('eventName', value)` (see `bridge.ts`); receive via `HTMLEventReceivedFcn`
17## Adding a new demo
191. Create a MATLAB plumbing script (e.g. `new_demo_viewer.m`) — see `mesh_refiner.m` or `vector_field_viewer.m`
202. Create a user-facing script (e.g. `new_demo.m`) — thin wrapper that builds data and calls the viewer
213. In `App.tsx`, add a type guard for the new data format and render appropriate controls
224. Update `README.md` to link the new script
24## Client-side vs. server-side interactivity
26- **Low-latency control** (e.g. arrow scaling): update React state only — instant, no MATLAB round-trip
27- **Computation-heavy change** (e.g. mesh refinement): `sendToMATLAB(event, value)` → MATLAB recomputes → `sendEventToHTMLSource` → React re-renders
29## Key files
31| File | Purpose |
32|------|---------|
33| `app/src/App.tsx` | Main React component; detects data type, renders controls |
34| `app/src/render/SurfView.tsx` | Three.js renderer; supports surf, quiver3, plot3, bar3 traces |
35| `app/src/render/types.ts` | TypeScript types for trace formats |
36| `app/src/bridge.ts` | `onData` / `onHostEvent` / `sendToMATLAB` helpers |
37| `mesh_refiner.m` | Opens figure, sends mesh, handles refinement callbacks |
38| `vector_field_viewer.m` | Opens figure, sends surface + vector field once (no callback) |