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
• 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)