1# CLAUDE.md
3Tips for future agents working in this repo. It combines the sibling projects
4`commonview` (p2p shared state; central-peer authority) and
5`hitandrun-interactive` (the figure + MATLAB sampler), so read those first —
6this file only covers what is different here.
8## Architecture
10```
11src/p2p/ identity, nostr discovery, WebRTC peer — ported from commonview
12 network.ts the heart: shared ViewState + sample blobs + central election
13 blob.ts Float32 codec + chunk reassembly for the sample sets
14src/engine/ the numbl runtime, run ONLY by the central peer
15 numbl.worker.ts executeCode against an in-memory VFS; uihtml intercepted
16 engine.ts host wrapper: start/resample/newRegion with timeouts
17 project.ts ?raw imports of matlab/*.m (verbatim from hitandrun-interactive)
18src/App.tsx the figure UI (controls dispatch p2p commands, not sendToMATLAB)
19src/render/ RegionView canvas — verbatim from hitandrun-interactive
20matlab/ the .m files — DO NOT EDIT here; they are copies (see below)
21```
23## Key design decisions
25- **Two-part state.** The small JSON "view" (params, region, busy/engine
26 status, movie step, `samplesId`) is broadcast on every change. The samples
27 are a Float32 blob announced by a signed header (`{t:'blob', id, bytes,
28 hash}`) followed by raw 64 KB binary chunks. All sends to a given peer go
29 through a per-connection promise chain, so on the ordered data channel a
30 blob always lands before the view that references it.
31- **Engine only on central.** `Network` takes an engine factory; it boots one
32 when it becomes central (after a 4 s discovery grace period at startup) and
33 disposes it on resignation. The initial run's region/samples are adopted
34 only if the room has no state yet — a failover central keeps the inherited
35 region (the script is stateless; resample requests carry the region).
36- **Engine failure = step-down.** Boot errors, callback errors, and timeouts
37 (60 s compute / 120 s start) mark the peer `engineFailed`; hellos carry the
38 flag and the election skips failed peers (falling back to oldest-overall so
39 the room never loses its state authority). The flag clears only on a
40 successful later boot or a reload.
41- **Shared movie.** The central peer ticks `movieStep` every 750 ms and
42 broadcasts; the chord geometry is recomputed per-viewer from the same
43 Float32 samples, so every frame is identical everywhere.
44- **numbl comes from npm** (`>= 0.4.8`, which added the browser-embedding
45 exports: `VirtualFileSystem`, `BrowserFileIOAdapter`, `BrowserSystemAdapter`,
46 `UihtmlSession`). No COOP/COEP / SharedArrayBuffer needed: the script never
47 calls `input()`, and no qhull/convhull (make_region avoids convhull
48 deliberately).
50## The matlab/ copies
52`matlab/**/*.m` are verbatim copies from `hitandrun-interactive` (plus a
53placeholder served as `app/dist/index.html`, which the sampler `fileread`s for
54its uihtml HTMLSource — never rendered). If the upstream figure protocol
55changes (`resample`/`newRegion` events, payload shapes), re-copy the files and
56revisit `src/engine/engine.ts`.
58## Testing
60- Headless engine check (no browser): run the script + uihtml round-trip in
61 Node against the installed numbl — see the "engine-test" pattern in git
62 history / ask the user. `executeCode` is platform-agnostic.
63- Full check: `npm run dev`, open in two different browser **profiles** (same
64 profile = same localStorage key = same peer). Kill the central tab to test
65 failover.
66- `npm run build` type-checks (`tsc -b`) and bundles; the numbl worker chunk
67 is ~1.5 MB.