Allow viewer data to be updated in real-time (supersedes #142)

[mvdoc]

Supersedes #142 by @r-b-g-b, whose branch predates the history rewrite and can no longer be merged (refusing to merge unrelated histories). The idea and the original patch are theirs; this re-applies them to current main, fixes what no longer fit, and adds tests.

What this does

JSMixer.addData lets you push new data into an already running cortex.webshow viewer, without restarting the server:

client = cortex.webshow(volume)
client.addData(second=other_volume)

Why the original patch needed rework

addData on main was dead code in two ways:

• it called _convert_dataset(Dataset(...)), and neither name exists in cortex.webgl.view — any call raised NameError (there was an xfailed test pinning exactly that);
• it proxied to window.viewers.addData, but mixer.html only ever defines window.viewer, a mriview.Viewer rather than the mriview.MultiView the original patch modified.

Changes

• show() keeps the packaged metadata as a dict instead of a JSON string, and serializes it when the mixer page is generated (this part is unchanged from Allow viewer data to be updated in real-time #142). That is what lets addData merge new dataviews into it, so reloading the page shows everything added so far.
• addData builds a Package for the new dataviews, runs Package.reorder against the ctm files the viewer was started with (vertex data is uploaded as a raw vertex attribute array, so it has to match the CTM vertex order), registers the new images with the data handler, merges the metadata, and sends only the new dataviews to the browser — Allow viewer data to be updated in real-time #142 sent the whole accumulated metadata, which would re-create every brain on each call.
• Adding a name that is already displayed replaces it, and the images of the replaced dataview are dropped, so repeatedly refreshing the same dataview does not pile up unused image buffers in the server.
• Data for a subject the viewer was not started with is rejected with a clear ValueError, since surfaces are baked into the page at startup and cannot be added to a running viewer.
• mriview.Viewer.addData (and mriview.MultiView.addData) accept the raw metadata package in addition to dataset.DataView objects.

Tests

The xfailed test_addData_no_crash is replaced by a TestAddData group in cortex/tests/test_webgl_headless.py covering:

• the new dataview being registered and becoming the active one, with no JS page errors;
• the metadata served by mixer.html after the call, including that every referenced image URL still returns a PNG;
• the rendered image actually changing when switching between the original and the added dataview;
• re-adding a name replacing it rather than duplicating it, and the replaced brain being pruned;
• the unknown-subject ValueError.

Plus test_addData_vertex_data, which exercises the reorder path and checks the added vertex data is served as a raw .npy blob rather than a PNG mosaic.

All six fail against the pre-fix code (NameError) and pass with it; the two pruning assertions were separately confirmed to fail without the pruning change.

🤖 Generated with Claude Code

https://claude.ai/code/session_013MCFG1Uez4JMFZK65KeTeT

---

Generated by Claude Code

[kroq-gar78]

This PR may have introduced a race condition. See this failed run for an unrelated change: https://github.com/gallantlab/pycortex/actions/runs/32525918728/job/96907786022

FAILED cortex/tests/test_webgl_headless.py::test_addData_vertex_data - OSError: image file is truncated