# CLAUDE.md

Tips for future agents working in this repo.

## Architecture

- `app/` — React/Three.js single-file widget (`npm run build` → `app/dist/index.html`)
- `*.m` at root — MATLAB scripts users open and run in [numbl](https://numbl.org)
- `numbl-project.json` — project metadata; `entry` is the landing page

## Data flow

**MATLAB → figure:** set `uihtml(..., 'Data', struct)` or call `sendEventToHTMLSource(src, 'eventName', data)`

**Figure → MATLAB:** call `sendToMATLAB('eventName', value)` (see `bridge.ts`); receive via `HTMLEventReceivedFcn`

## Adding a new demo

1. Create a MATLAB plumbing script (e.g. `new_demo_viewer.m`) — see `mesh_refiner.m` or `vector_field_viewer.m`
2. Create a user-facing script (e.g. `new_demo.m`) — thin wrapper that builds data and calls the viewer
3. In `App.tsx`, add a type guard for the new data format and render appropriate controls
4. Update `README.md` to link the new script

## Client-side vs. server-side interactivity

- **Low-latency control** (e.g. arrow scaling): update React state only — instant, no MATLAB round-trip
- **Computation-heavy change** (e.g. mesh refinement): `sendToMATLAB(event, value)` → MATLAB recomputes → `sendEventToHTMLSource` → React re-renders

## Key files

| File | Purpose |
|------|---------|
| `app/src/App.tsx` | Main React component; detects data type, renders controls |
| `app/src/render/SurfView.tsx` | Three.js renderer; supports surf, quiver3, plot3, bar3 traces |
| `app/src/render/types.ts` | TypeScript types for trace formats |
| `app/src/bridge.ts` | `onData` / `onHostEvent` / `sendToMATLAB` helpers |
| `mesh_refiner.m` | Opens figure, sends mesh, handles refinement callbacks |
| `vector_field_viewer.m` | Opens figure, sends surface + vector field once (no callback) |