1# CLAUDE.md
3Tips for future agents working in this repo.
5## Architecture
7```
8src/engine/pulseq/ vendored pulseq +mr tree (86 .m files) + LICENSE +
9 VENDORED.md; NEVER edit — re-sync with `npm run
10 vendor-pulseq` (reads ../../pulseq by default)
11src/engine/mrFiles.ts +mr tree as numbl boot files (vite ?raw glob), with
12 +mr/+aux/md5.m replaced by a wrapper over numbl's
13 `hash` builtin (the original needs Java on MATLAB)
14src/engine/runner.ts run-per-execution wrapper over numbl/browser
15 createNumblSession: boots idle (mip off, no
16 persistence) with +mr + main.m staged, executes
17 'main;', collects *.seq via a dir() snippet, disposes.
18 Cancel = dispose (works without cross-origin isolation).
19src/seq/parseSeq.ts .seq parser (v1.4.x/1.5.x), column layouts and unit
20 scales mirror pulseq's @Sequence/read.m; shape RLE
21 decompression mirrors decompressShape.m
22src/seq/reconstruct.ts ParsedSeq -> plottable polylines, mirroring
23 Sequence.waveforms_and_times (trap vertices, centers-
24 raster arbitrary grads get first/last edge points,
25 extended trapezoids use vertices as stored)
26src/viewer/ canvas Timeline (min/max pixel decimation, wheel zoom,
27 drag pan, click-to-select block), ReportPanel,
28 BlockInspector
29src/examples/ gallery: 3 curated .m (fid/epi/gre, hand-written with
30 the autoLabel toggle), catalog.ts (name/category/desc per
31 id), generated-timings.ts (AUTO), and pulseq/*.m —
32 auto-adapted demoSeq scripts written by gen-examples.mjs.
33 ExamplesModal groups them by category.
34test-data/golden/ .seq goldens generated by Octave and verified
35 byte-identical against real MATLAB R2026b
36```
38## Examples pipeline
40The gallery's pulseq demos are generated, not hand-maintained:
42- `node scripts/test-demos.mjs` batch-runs every `../../pulseq/matlab/demoSeq`
43 script on numbl in isolated child processes. It **adapts** each (strips
44 visualization/analysis/scanner-side-effect statements, truncates after the
45 first `seq.write`, re-appends trailing local functions), stages +mr with the
46 md5 + isSigPyAvailable overrides, runs it, and parses the output with the JS
47 parser. Writes `scripts/demo-results.json`.
48- `node scripts/gen-examples.mjs` reads that JSON and writes `src/examples/
49 pulseq/<id>.m` for every demo that ran cleanly AND has a `catalog.ts` entry
50 that isn't already curated (fid/epi/gre), plus `generated-timings.ts`.
51- 12 of 42 demos run on numbl today (fid, epi, EpiRS, EpiSpinEcho,
52 EpiSpinEchoRS, FastRadialGradientEcho, GradientEcho/gre, GRE_live_demo
53 [_step0], RadialGradientEcho, UTE, UTE_rs). The rest hit numbl gaps — see
54 the numbl-gap list in the `seqlab-project` memory. Re-run both scripts after
55 numbl improvements to pick up newly-working demos.
56- `adaptDemo` is exported from test-demos.mjs and reused by gen-examples; that
57 file only runs the batch when executed directly (isMain guard), so importing
58 it for `adaptDemo` is safe.
60## Key gotchas
62- **numbl >= 0.4.17.** Needs the pulseq-compat fixes (inputParser optionals,
63 dictionary FallbackValue, containers.Map sorted keys, `hash` builtin,
64 fnint/ppint, warning('off',id), sprintf -0, …). package.json points at
65 `file:../../numbl` while 0.4.17 is unpublished; switch to `^0.4.17` before
66 deploy, then `rm -rf node_modules package-lock.json && npm install`. For
67 local numbl changes run `npm run build:lib && npm run build:browser` there.
68- **The .seq filename is discovered, not assumed.** The runner lists `*.seq`
69 in the session cwd after the run (COLLECT_SNIPPET); scripts may write any
70 name(s), and each file becomes a viewer tab.
71- **`execute('main;')`, not the script text.** Running by name keeps MATLAB
72 script semantics (local functions allowed); the trailing semicolon
73 suppresses a spurious `ans` display under the REPL's displayResults.
74- **scripts/engine-test.mjs mirrors worker.ts exactly** (idle boot: cwd
75 /project, relative workspace-file names, mainScriptPath 'repl', empty
76 search paths). If numbl's browser worker changes its call shape, update the
77 mirror or the test stops being representative.
78- **Node runs the .ts sources directly** (Node >= 22.6 type stripping), which
79 is why src/seq imports use explicit `.ts` extensions.
80- **GRE takes ~30 s** in-browser/Node (interpreter mode; numbl's JIT declines
81 most pulseq code — see numbl-jit-performance). FID ~1 s, EPI ~2 s. Keep
82 gallery time labels honest.
83- **Signature hashing:** the md5 covers the file up to but excluding the
84 newline that precedes `[SIGNATURE]`.
86## Testing
88- `npm run engine-test` — FID through the exact worker call shape,
89 byte-compared against test-data/golden/fid.seq.
90- `npm run parser-test` — parser/reconstruction invariants on all 5 goldens
91 (fid, gre, seq1-3): signature verification, block/event counts, tamper
92 detection, RLE round-trip.
93- `node scripts/run-example.mjs <fid|epi|gre>` — run any example headlessly.
94- Browser verification (worker boot, editor, timeline interactions, drag &
95 drop) is manual: `npm run dev`.