Skip to content

Signal viewer: open inline, enlarge into the modal on demand - #218

Merged
neuromechanist merged 3 commits into
stagingfrom
feature/issue-217-viewer-inline-enlarge
Jul 31, 2026
Merged

neuromechanist merged 3 commits into
stagingfrom
feature/issue-217-viewer-inline-enlarge

Conversation

@neuromechanist

Copy link
Copy Markdown
Contributor

Closes #217.

What changed

The EEG/MEG/iEEG/EMG signal viewer opens inline again, in the clicked BIDS tree row's own preview panel. The full-screen dialog added in #206 stays, but it is no longer the entry point: it sits behind an Enlarge control in the inline panel.

src/lib/render-dir-listing.ts — signal rows get a [data-preview-slot] again, and the eeg branch collapses into the shared previewable-file branch since it now uses the same aria-expanded toggle semantics as md/json/tsv. Only the tooltip still distinguishes them. The slot is marked tree__preview--signal, which carries two differences from a text preview:

  • No height cap. The scope's height is derived from its width, so the 480px cap that suits a table would bury the plot behind a scrollbar inside an already-scrolling page.
  • No aria-live. A live region wrapped around a mounted viewer would announce every cursor-readout and legend update. The transient messages that genuinely need announcing carry role="status" / role="alert" themselves, which is the targeted mechanism anyway.

src/pages/dataset/[id].astro — openEegViewerModal becomes openEegViewerInline, plus enlargeEegViewer and a rewritten dialog-close handler. State moves from a bare (seq, destroy) pair to an eegLive record holding the row, the portable host, and the teardown handle, since three different events (a new open, a collapse, a dialog close) now each need to find the current instance and its DOM.

src/components/EegViewerDialog.astro — receives an already-mounted host rather than hosting a mount. Dropped aria-live (it no longer receives the loading/unavailable messages, only a live viewer) and grew to min(92vw, 1800px) x min(90vh, 1100px) from ~70%, since the user now arrives here by explicitly asking for more room than the inline panel gives.

src/components/BidsTree.astro — is:global styles for the inline bar, the Enlarge button, the stand-in marker, and the signal panel's sizing.

Design decisions

Move the host, don't remount. This is the whole feature. Montage, filter, gain, channel page and time window are closure state inside a single mountEegViewer call, so remounting on enlarge would reset exactly the state the user enlarged in order to look at more closely. Instead the viewer mounts into a dedicated [data-eegv-host] child of the panel (not the panel itself, so the row's chrome stays behind), and enlarging moves that one node into the dialog.

The move is safe, and specifically so for this instance: its MutationObserver watches document.documentElement for theme flips rather than its host, so relocation does not trip it, and its ResizeObserver watches the viewer root inside the moved subtree, so the move triggers exactly one repaint at the new width. It also works mid-mount, since mountEegViewer holds a reference to the host element and moving a node does not invalidate that.

One live viewer page-wide, kept. This constraint arrived with the modal in #199, but it was never really about the modal: each mount holds a WebGL context and browsers cap those (~16), so a viewer per row accumulates toward a hard limit. Opening a second signal file therefore releases the first and collapses its row. Collapsing the previous row is a deliberate choice over leaving it expanded-but-emptied, which would read as a rendering failure.

Rows expanded without a live instance. A row showing a recorded "unavailable" message has no instance to release, so releaseEegViewer alone would not collapse it. openEegViewerInline calls resetEegRow unconditionally alongside it; both are idempotent.

Ordering in releaseEegViewer. eegLive is cleared before dialog.close(), because the close handler's job is to hand a live viewer back to its row and there is about to be neither. Seeing null, it empties the dialog instead, which is also what the release-while-enlarged case needs.

No aria-haspopup on the row button. It toggles its adjacent panel now; the dialog is a second step behind a separate control, so claiming aria-haspopup="dialog" would misdescribe what the button does.

What I verified in the browser

Puppeteer against the dev server on nm000103 (HBN-EEG NC), real 129-channel recordings, both themes:

  • Inline mount: 4 canvases at 778x389, panel expanded, data-loaded="true", dialog untouched.
  • Enlarge preserves state — advanced the window to 4.0-14.0 s and bumped the scale twice (285 uV -> 127 uV), then enlarged: beforeCanvas === afterCanvas (same DOM node, so no remount), canvas repainted at 1257x540, window and scale and status line all unchanged.
  • Return: close puts the same canvas back inline at 778x389, window still 4.0-14.0 s, anchor removed, bar intact, row still expanded, dialog slot empty.
  • Collapse: re-clicking the row resets it to hidden/empty/aria-expanded=false, 0 canvases.
  • One-instance rule: opening a second file collapses the first and leaves exactly 4 canvases page-wide.
  • Rapid open A then B 40ms later: resolves to B alone, A collapsed, one instance.
  • Enlarge 120ms into a mount, before the store opens: mount completes into the moved host inside the dialog, returns inline on close.
  • Collapse 120ms into a mount: row reset, and after the superseded mount fully resolves there are 0 canvases anywhere.
  • Recorded zarrAvailable="false": surfaces the reason plus a download link routed through data.nemar.org/<id>/<v>/<bids-path>, role="status", no Enlarge offered, collapses cleanly.
  • Light and dark, inline and enlarged.

bun run test 1012/1012, typecheck 0 errors, lint clean, build complete.

The viewer mounts into the clicked row's own preview panel; an Enlarge
control moves the mounted host into the page-level dialog and the dialog
close moves it back. Moving rather than remounting keeps the montage,
filter, gain and time window across the transition.

At most one viewer is live page-wide, as before: each mount holds a WebGL
context and browsers cap those.

Closes #217
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Jul 31, 2026 •

Copy link
Copy Markdown

Deploying nemar-website with  Cloudflare Pages  Cloudflare Pages

Latest commit: 63188aa
Status: ✅  Deploy successful!
Preview URL: https://b5aecc52.nemar-website.pages.dev
Branch Preview URL: https://feature-issue-217-viewer-inl.nemar-website.pages.dev

View logs

mountEegViewer returns no disposer exactly when it mounted nothing and
left an unavailable message instead. The inline bar was surviving that,
offering an Enlarge that opened a full-screen modal onto one line of
text, and the row kept counting as the live instance despite holding no
observers or GL context to release.

Also corrects the viewer module docs, which still described the slot as
a modal body and told callers to dispose on dialog close -- disposing on
a move is now the specific bug to avoid.
Three review findings, none reachable through the UI today but all
one refactor away from being reachable:

- releaseEegViewer empties the dialog synchronously instead of relying
  on the queued close event, which can fire after eegLive has moved on
  to a different row.
- The !host guard now clears aria-busy/data-loaded and shows an error.
  It returns before eegSeq/eegLive exist, so the try/finally cannot
  clean up after it and a bare return left the row spinning forever.
- The close handler warns when it recovers a viewer whose inline anchor
  vanished, rather than silently patching a broken invariant, and no
  longer mistakes a newly opened row for the one being returned.
@neuromechanist

Copy link
Copy Markdown
Contributor Author

Review round 1

Four reviewers (code, error-handling, comments, tests). Every finding is addressed below; none deferred.

Fixed

1. Enlarge control survived a "resolved but no viewer" mount failure. Found independently by the error-handling and test reviewers. mountEegViewer has two failure shapes: it throws, or it resolves to undefined after writing an "unavailable" message into the host (store won't open, no channel groups, no 2D context). Only the throw path was handled. On the resolve path eegLive stayed non-null with destroy: null, and the inline bar — rendered before the mount starts and untouched by renderUnavailable, which only writes into the host — was left offering an Enlarge that opened a full-screen modal onto one line of text. The row also kept counting as the live instance despite holding no observers and no GL context.

Reproduced by rejecting zarr requests at the network layer, which is a real state (unreachable or corrupt store), not a synthetic one. Confirmed the modal-onto-a-message behavior, then fixed: !destroy now strips the bar and clears eegLive. Re-verified — bar gone, message plus download link intact, aria-busy cleared, data-loaded="true", and opening a different file afterwards mounts cleanly at 4 canvases with one instance page-wide. Commit 69aa7e6.

2. releaseEegViewer depended on the dialog being modal. close() only queues the close event, and openEegViewerInline assigns a new eegLive synchronously before its first await — so the handler could run while eegLive already points at a different row, and would not recognise the old host as something to clear. Safe today only because a modal <dialog> makes the rest of the document inert, so no tree row is clickable while it is open. That is a guarantee about the dialog, not about this function, and it cost one line not to depend on it: the dialog slot is now emptied synchronously. Commit 63188aa.

3. The !host guard returned before the cleanup machinery existed. It sits ahead of the eegSeq/eegLive assignments, so the try/finally could never clean up after it: a bare return left the row spinning on "Loading viewer…" behind a stuck aria-busy, with an Enlarge control that silently no-oped. Now clears all three and surfaces a download fallback. Commit 63188aa.

4. Silent recovery in the close handler. The anchor-missing else branch was a reasonable functional recovery but said nothing about the invariant violation that caused it. Now warns, and no longer mistakes a newly opened row for the one being returned. Commit 63188aa.

5. Comment rot in src/lib/eeg-viewer/viewer.ts — not in the original diff, which is why it was missed. The module header still asserted the slot is a modal body "rather than an inline row in the BIDS tree," exactly inverted by this PR, and the mountEegViewer doc told callers to dispose when the host modal closes. Disposing on a move is now precisely the bug to avoid, so both were corrected. Also trimmed a "called on tree teardown" clause from releaseEegViewer that named a call site that does not exist. Commits 69aa7e6, 63188aa.

Verified, no change needed

The code reviewer traced every interleaving and found the state machine sound, resting on one browser guarantee it confirmed: a superseded mid-flight mount checks isStale() immediately after its own await, before allocating any GL context or observers, so it never has resources to leak. It also confirmed is:global is correct rather than a scoping violation here — the host physically relocates into the dialog's subtree, which Astro's data-astro-cid-* scoping would not follow.

The test reviewer mutation-tested the new negative assertion by reintroducing aria-live on the signal slot and confirming it fails, rather than only confirming it passes. It also confirmed slots.length === 4 is a real pin (3 before this PR), and that nothing in the new state machine is extractable as pure logic without mocks, which the project forbids.

Not actionable

"Open a row while another is enlarged" is unreachable: showModal() makes the document inert, so the tree rows cannot be clicked. Noted rather than tested.

Re-verified after all fixes: enlarge round trip preserves the same canvas element (1257x540 enlarged, 778x389 inline) and the 2.0-12.0 s window in both directions; anchor removed; dialog slot empty; switching files collapses the previous row and leaves one instance page-wide; no spurious warnings. test 1012/1012, typecheck 0 errors, lint clean.

@neuromechanist
neuromechanist merged commit 1a7a103 into staging Jul 31, 2026
5 checks passed
@neuromechanist
neuromechanist deleted the feature/issue-217-viewer-inline-enlarge branch July 31, 2026 02:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant