CLAUDE.md#

Tips for future agents working in this repo.

Architecture#

src/engine/pulseq/   vendored pulseq +mr tree (86 .m files) + LICENSE +
                     VENDORED.md; NEVER edit — re-sync with `npm run
                     vendor-pulseq` (reads ../../pulseq by default)
src/engine/mrFiles.ts  +mr tree as numbl boot files (vite ?raw glob), with
                     +mr/+aux/md5.m replaced by a wrapper over numbl's
                     `hash` builtin (the original needs Java on MATLAB)
src/engine/runner.ts run-per-execution wrapper over numbl/browser
                     createNumblSession: boots idle (mip off, no
                     persistence) with +mr + main.m staged, executes
                     'main;', collects *.seq via a dir() snippet, disposes.
                     Cancel = dispose (works without cross-origin isolation).
src/seq/parseSeq.ts  .seq parser (v1.4.x/1.5.x), column layouts and unit
                     scales mirror pulseq's @Sequence/read.m; shape RLE
                     decompression mirrors decompressShape.m
src/seq/reconstruct.ts  ParsedSeq -> plottable polylines, mirroring
                     Sequence.waveforms_and_times (trap vertices, centers-
                     raster arbitrary grads get first/last edge points,
                     extended trapezoids use vertices as stored)
src/viewer/          canvas Timeline (min/max pixel decimation, wheel zoom,
                     drag pan, click-to-select block), ReportPanel,
                     BlockInspector
src/examples/        gallery: 3 curated .m (fid/epi/gre, hand-written with
                     the autoLabel toggle), catalog.ts (name/category/desc per
                     id), generated-timings.ts (AUTO), and pulseq/*.m —
                     auto-adapted demoSeq scripts written by gen-examples.mjs.
                     ExamplesModal groups them by category.
test-data/golden/    .seq goldens generated by Octave and verified
                     byte-identical against real MATLAB R2026b

Examples pipeline#

The gallery's pulseq demos are generated, not hand-maintained:

• node scripts/test-demos.mjs batch-runs every ../../pulseq/matlab/demoSeq script on numbl in isolated child processes. It adapts each (strips visualization/analysis/scanner-side-effect statements, truncates after the first seq.write, re-appends trailing local functions), stages +mr with the md5 + isSigPyAvailable overrides, runs it, and parses the output with the JS parser. Writes scripts/demo-results.json.
• node scripts/gen-examples.mjs reads that JSON and writes src/examples/ pulseq/<id>.m for every demo that ran cleanly AND has a catalog.ts entry that isn't already curated (fid/epi/gre), plus generated-timings.ts.
• 12 of 42 demos run on numbl today (fid, epi, EpiRS, EpiSpinEcho, EpiSpinEchoRS, FastRadialGradientEcho, GradientEcho/gre, GRE_live_demo [_step0], RadialGradientEcho, UTE, UTE_rs). The rest hit numbl gaps — see the numbl-gap list in the seqlab-project memory. Re-run both scripts after numbl improvements to pick up newly-working demos.
• adaptDemo is exported from test-demos.mjs and reused by gen-examples; that file only runs the batch when executed directly (isMain guard), so importing it for adaptDemo is safe.

Key gotchas#

• numbl >= 0.4.17. Needs the pulseq-compat fixes (inputParser optionals, dictionary FallbackValue, containers.Map sorted keys, hash builtin, fnint/ppint, warning('off',id), sprintf -0, …). package.json points at file:../../numbl while 0.4.17 is unpublished; switch to ^0.4.17 before deploy, then rm -rf node_modules package-lock.json && npm install. For local numbl changes run npm run build:lib && npm run build:browser there.
• The .seq filename is discovered, not assumed. The runner lists *.seq in the session cwd after the run (COLLECT_SNIPPET); scripts may write any name(s), and each file becomes a viewer tab.
• execute('main;'), not the script text. Running by name keeps MATLAB script semantics (local functions allowed); the trailing semicolon suppresses a spurious ans display under the REPL's displayResults.
• scripts/engine-test.mjs mirrors worker.ts exactly (idle boot: cwd /project, relative workspace-file names, mainScriptPath 'repl', empty search paths). If numbl's browser worker changes its call shape, update the mirror or the test stops being representative.
• Node runs the .ts sources directly (Node >= 22.6 type stripping), which is why src/seq imports use explicit .ts extensions.
• GRE takes ~30 s in-browser/Node (interpreter mode; numbl's JIT declines most pulseq code — see numbl-jit-performance). FID ~1 s, EPI ~2 s. Keep gallery time labels honest.
• Signature hashing: the md5 covers the file up to but excluding the newline that precedes [SIGNATURE].

Testing#

• npm run engine-test — FID through the exact worker call shape, byte-compared against test-data/golden/fid.seq.
• npm run parser-test — parser/reconstruction invariants on all 5 goldens (fid, gre, seq1-3): signature verification, block/event counts, tamper detection, RLE round-trip.
• node scripts/run-example.mjs <fid|epi|gre> — run any example headlessly.
• Browser verification (worker boot, editor, timeline interactions, drag & drop) is manual: npm run dev.