arrayview 0.12.1__tar.gz → 0.12.2__tar.gz

{arrayview-0.12.1 → arrayview-0.12.2}/.claude/skills/viewer-ui-checklist/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: viewer-ui-checklist
-description: Use when adding keyboard shortcuts, changing layout, or making any UI change to arrayview. Ensures visual_smoke.py stays in sync.
+description: Use when adding keyboard shortcuts, changing layout, or making any UI change to arrayview. Ensures visual_smoke.py, help overlay, and README stay in sync.
 ---
 
 # ArrayView UI Checklist
 
 ## Rule
 
-Every UI change to arrayview MUST be reflected in `tests/visual_smoke.py` before the task is complete.
+Every UI change to arrayview MUST be reflected in `tests/visual_smoke.py`, the help overlay, and (when user-facing) `README.md` before the task is complete.
 
 ## What counts as a UI change
 
@@ -35,6 +35,14 @@ Every UI change to arrayview MUST be reflected in `tests/visual_smoke.py` before
 
 4. **Open and review** the new screenshots in `tests/smoke_output/`
 
+5. **Update `GUIDE_TABS`** in `_viewer.html` if you added, removed, or changed a keybinding
+   - Add/update the entry in the appropriate tab and section
+   - Include a `hint` for non-obvious shortcuts
+   - Use the `docs-style` skill for formatting rules
+
+6. **Update `README.md`** if the change is user-facing (new CLI flag, new API, new mode)
+   - Use the `docs-style` skill for formatting rules
+
 ## Red flags — STOP
 
 - "The shortcut is too simple to need a smoke test" → ALL shortcuts need entries

{arrayview-0.12.1 → arrayview-0.12.2}/AGENTS.md

@@ -15,7 +15,8 @@ Load the relevant skill before touching the corresponding area.
 | `frontend-designer` | Styling/layout changes to `_viewer.html` |
 | `vscode-simplebrowser` | Extension, signal-file IPC, `_VSCODE_EXT_VERSION` |
 | `invocation-consistency` | Server startup, display-opening, env detection |
-| `docs-style` | README, help overlay, docstrings |
+| `viewer-ui-checklist` | Any UI change (smoke tests, help overlay, README sync) |
+| `docs-style` | README, help overlay, docstrings (formatting rules) |
 
 ## Non-Negotiables
 

{arrayview-0.12.1 → arrayview-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.12.1
+Version: 0.12.2
 Summary: Fast multi-dimensional array viewer
 Project-URL: Home, https://github.com/oscarvanderheide/arrayview
 Project-URL: Source, https://github.com/oscarvanderheide/arrayview

{arrayview-0.12.1 → arrayview-0.12.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.12.1"
+version = "0.12.2"
 description = "Fast multi-dimensional array viewer"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12"

{arrayview-0.12.1 → arrayview-0.12.2}/src/arrayview/_stdio_server.py

@@ -637,7 +637,7 @@ def _handle_get_viewer_html(msg: dict) -> None:
     """Return the rendered viewer HTML with template substitutions."""
     from importlib.resources import files as _pkg_files
 
-    from arrayview._config import get_viewer_colormaps
+    from arrayview._config import get_viewer_colormaps, get_viewer_theme
     from arrayview._render import COLORMAP_GRADIENT_STOPS, COMPLEX_MODES, REAL_MODES
     from arrayview._session import COLORMAPS
 
@@ -650,12 +650,17 @@ def _handle_get_viewer_html(msg: dict) -> None:
 
     query_val = json.dumps(f"?sid={sid}&transport=postMessage") if sid else "null"
 
+    _theme_names = ["dark", "light", "solarized", "nord"]
+    _cfg_theme = get_viewer_theme()
+    _default_theme_idx = _theme_names.index(_cfg_theme) if _cfg_theme in _theme_names else 0
+
     html = (
         template.replace("__COLORMAPS__", str(_active_colormaps))
         .replace("__COLORMAP_GRADIENT_STOPS__", json.dumps(COLORMAP_GRADIENT_STOPS))
         .replace("__COMPLEX_MODES__", str(COMPLEX_MODES))
         .replace("__REAL_MODES__", str(REAL_MODES))
         .replace("__ARRAYVIEW_QUERY__", query_val)
+        .replace("__DEFAULT_THEME_IDX__", str(_default_theme_idx))
     )
 
     _write_json({"html": html})

{arrayview-0.12.1 → arrayview-0.12.2}/src/arrayview/_viewer.html

@@ -535,14 +535,7 @@
             width: min(820px, 92vw); height: min(520px, 86vh);
             overflow: hidden;
         }
-        .help-topbar {
-            display: flex; justify-content: space-between; align-items: center;
-            margin-bottom: 14px; flex-shrink: 0;
-        }
-        .help-mode-hint {
-            font-size: 11px; color: var(--muted); letter-spacing: 0.04em;
-        }
-        .help-mode-hint kbd, .help-footer kbd {
+        .help-footer kbd {
             display: inline-block; border: 1px solid var(--border);
             border-radius: 4px; padding: 0px 5px;
             font-family: 'SF Mono', ui-monospace, monospace;
@@ -579,13 +572,23 @@
             margin-bottom: 8px; padding-bottom: 4px;
             border-bottom: 1px solid var(--border-subtle);
         }
+        .help-section-title:not(:first-child) { margin-top: 16px; }
+        .help-subsection-title {
+            font-size: 12px; font-weight: 600; color: var(--text);
+            margin-top: 18px; margin-bottom: 4px;
+        }
+        .help-subsection-title:first-child { margin-top: 0; }
+        .help-subsection-desc {
+            color: var(--muted); font-size: 11.5px;
+            line-height: 1.6; margin-bottom: 10px;
+        }
         .help-section { margin-bottom: 18px; }
         .help-columns { display: flex; gap: 28px; }
         .help-column { flex: 1; min-width: 0; }
         .help-entry { margin-bottom: 8px; }
         .help-entry-row { display: flex; align-items: baseline; }
         .help-entry-key {
-            flex-shrink: 0; width: 88px;
+            flex-shrink: 0; width: 100px;
             color: var(--help-key); font-weight: 600;
             font-family: 'SF Mono', ui-monospace, 'Cascadia Code', monospace;
             font-size: 12px;
@@ -593,15 +596,14 @@
         .help-entry-action { color: var(--text); font-size: 12.5px; }
         .help-entry-hint {
             color: var(--muted); font-size: 11px;
-            margin-left: 88px; margin-top: 1px;
+            margin-left: 100px; margin-top: 1px;
         }
         .help-footer {
             flex-shrink: 0; border-top: 1px solid var(--border-subtle);
             margin-top: 14px; padding-top: 10px;
-            display: flex; justify-content: space-between; align-items: center;
+            display: flex; justify-content: flex-end; align-items: center;
             font-size: 11px; color: var(--muted); letter-spacing: 0.04em;
         }
-        .help-footer-nav kbd { margin-right: 2px; }
         .help-footer-link {
             color: var(--muted); text-decoration: none;
             font-size: 11px; letter-spacing: 0.04em;
@@ -1501,14 +1503,10 @@
     </div>
     <div id="help-overlay">
         <div id="help-box">
-            <div class="help-topbar">
-                <span class="help-mode-hint">press <kbd>?</kbd> to close</span>
-            </div>
             <div id="help-tabs"></div>
             <div id="help-content"></div>
             <div class="help-footer">
-                <span class="help-footer-nav"><kbd>h</kbd><kbd>l</kbd> / <kbd>← →</kbd> switch tabs</span>
-                <a class="help-footer-link" href="https://github.com/brainhack-school2024/arrayview#keybindings" target="_blank" rel="noopener">Full reference →</a>
+                <a class="help-footer-link" href="https://oscarvanderheide.github.io/arrayview/" target="_blank" rel="noopener">Full reference →</a>
             </div>
         </div>
     </div>
@@ -1749,7 +1747,8 @@
         let lebesgueMode = false;       // Lebesgue integral: highlight pixels matching hovered bin
         let _lebesgueSlice = null;      // Float32Array of raw 2-D slice values (row-major)
         let _lebesgueVersion = null;    // version key for cached _lebesgueSlice
-        let _lebesgueFetching = false;  // prevents concurrent fetches
+        let _lebesgueFetchCtrl = null;  // AbortController for in-flight Lebesgue fetch
+        let _hoverPrefetchTimer = null; // debounce for hover prefetch during rapid scrolling
         let _lastLebesgueBin = -1;      // tracks which histogram bin is currently highlighted
         let _lebesgueSliceW = 0, _lebesgueSliceH = 0; // dimensions of cached raw slice
         let rgbMode = false;
@@ -5035,6 +5034,16 @@
             }
         }
 
+        /** Debounced prefetch — safe to call on every wheel / key event. */
+        function _debouncedHoverPrefetch() {
+            if (!_pixelInfoVisible && !lebesgueMode) return;
+            clearTimeout(_hoverPrefetchTimer);
+            _hoverPrefetchTimer = setTimeout(() => {
+                _fetchLebesgueSlice();
+                if (_pixelInfoVisible) _prefetchHoverSlices();
+            }, 80);
+        }
+
         async function _fetchLebesgueSliceForSid(fetchSid, fetchDimX, fetchDimY) {
             const params = new URLSearchParams({
                 dim_x: fetchDimX, dim_y: fetchDimY,
@@ -5058,32 +5067,37 @@
         }
 
         async function _fetchLebesgueSlice() {
-            if (!sid || !indices.length || _lebesgueFetching) return;
-            _lebesgueFetching = true;
-            if (compareActive) {
-                // Fetch for all compare sessions in parallel
-                const sids = getCompareRenderSids();
-                await Promise.all(sids.map(s => _fetchLebesgueSliceForSid(s, dim_x, dim_y)));
-                // Also cache in legacy variables for single-session fallback
-                const first = _lebesguePerSession[sids[0]];
-                if (first) {
-                    _lebesgueSlice = first.slice;
-                    _lebesgueSliceW = first.w;
-                    _lebesgueSliceH = first.h;
-                    _lebesgueVersion = first.version;
-                }
-            } else {
-                const entry = await _fetchLebesgueSliceForSid(sid, dim_x, dim_y);
-                if (entry) {
-                    _lebesgueSlice = entry.slice;
-                    _lebesgueSliceW = entry.w;
-                    _lebesgueSliceH = entry.h;
-                    _lebesgueVersion = entry.version;
+            if (!sid || !indices.length) return;
+            // Abort any in-flight fetch so rapid slice changes always fetch the latest
+            if (_lebesgueFetchCtrl) _lebesgueFetchCtrl.abort();
+            const ctrl = new AbortController();
+            _lebesgueFetchCtrl = ctrl;
+            try {
+                if (compareActive) {
+                    const sids = getCompareRenderSids();
+                    await Promise.all(sids.map(s => _fetchLebesgueSliceForSid(s, dim_x, dim_y)));
+                    if (ctrl.signal.aborted) return;
+                    const first = _lebesguePerSession[sids[0]];
+                    if (first) {
+                        _lebesgueSlice = first.slice;
+                        _lebesgueSliceW = first.w;
+                        _lebesgueSliceH = first.h;
+                        _lebesgueVersion = first.version;
+                    }
                 } else {
-                    _lebesgueSlice = null;
+                    const entry = await _fetchLebesgueSliceForSid(sid, dim_x, dim_y);
+                    if (ctrl.signal.aborted) return;
+                    if (entry) {
+                        _lebesgueSlice = entry.slice;
+                        _lebesgueSliceW = entry.w;
+                        _lebesgueSliceH = entry.h;
+                        _lebesgueVersion = entry.version;
+                    } else {
+                        _lebesgueSlice = null;
+                    }
                 }
-            }
-            _lebesgueFetching = false;
+            } catch (_) { /* aborted or network error */ }
+            if (_lebesgueFetchCtrl === ctrl) _lebesgueFetchCtrl = null;
         }
 
         function _clearLebesgueOverlay() {
@@ -7142,14 +7156,18 @@
             renderInfo();
             // Invalidate cached histogram data so next colorbar hover re-fetches
             _histDataVersion = null;
-            // Invalidate and clear Lebesgue overlay (slice changed)
-            _lebesgueVersion = null;
-            Object.keys(_lebesguePerSession).forEach(k => delete _lebesguePerSession[k]);
-            Object.keys(_hoverSliceCache).forEach(k => delete _hoverSliceCache[k]);
+            // Lebesgue / hover caches are version-keyed, so stale entries are
+            // never served for the wrong slice.  Don't eagerly clear — the old
+            // data remains harmless while the async re-fetch is in flight, and
+            // clearing creates a window where hover falls to the slow /pixel path.
+            // Cap cache size to prevent unbounded memory growth.
+            const _hscKeys = Object.keys(_hoverSliceCache);
+            if (_hscKeys.length > 64) _hscKeys.slice(0, _hscKeys.length - 32).forEach(k => delete _hoverSliceCache[k]);
+            const _lpsKeys = Object.keys(_lebesguePerSession);
+            if (_lpsKeys.length > 32) _lpsKeys.slice(0, _lpsKeys.length - 16).forEach(k => delete _lebesguePerSession[k]);
             if (lebesgueMode || _pixelInfoVisible) {
                 if (lebesgueMode) _clearLebesgueOverlay();
-                _fetchLebesgueSlice();
-                if (_pixelInfoVisible) _prefetchHoverSlices();
+                _debouncedHoverPrefetch();
             }
             if (compareQmriActive) {
                 compareQmriViews.forEach(v => compareQmriRender(v));
@@ -9232,19 +9250,53 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
             },
             'overlay.cycleVisibility': {
                 title: 'Cycle overlay visibility',
-                when: ['hasOverlay'],
+                when: [],
                 run: (ctx, e) => {
+                    const hasOv = !!overlay_sid;
+                    const hasVf = hasVectorfield;
+                    if (!hasOv && !hasVf) return;
+
+                    // Helper: show or hide vector field arrows
+                    const setVfield = (show) => {
+                        if (!hasVf) return;
+                        vfieldVisible = show;
+                        if (!show) {
+                            if (_vfieldAbort) { _vfieldAbort.abort(); _vfieldAbort = null; }
+                            vfieldCanvas.style.display = 'none';
+                            if (multiViewActive) {
+                                _mvVfieldAborts.forEach(ac => ac.abort());
+                                _mvVfieldAborts.clear();
+                                _mvVfieldCache.clear();
+                                document.querySelectorAll('.mv-vfield-overlay').forEach(el => el.style.display = 'none');
+                            }
+                        } else {
+                            if (multiViewActive) mvDrawAllVectorOverlays();
+                            else drawVectorOverlay();
+                        }
+                    };
+
+                    // Vector field only (no masks): simple toggle
+                    if (!hasOv) {
+                        setVfield(!vfieldVisible);
+                        showStatus(`arrows: ${vfieldVisible ? 'on' : 'off'}`);
+                        saveState();
+                        return;
+                    }
+
                     // Cycle overlay visibility: all → none → mask0 → mask1 → ... → all
                     const sids = overlay_sid.split(',');
                     const nMasks = sids.length;
                     if (_overlayVisibility === 'all') {
                         _overlayVisibility = 'none';
+                        setVfield(false);
                     } else if (_overlayVisibility === 'none') {
                         _overlayVisibility = nMasks > 1 ? 0 : 'all';
+                        if (_overlayVisibility === 'all') setVfield(true);
                     } else {
                         // Currently showing individual mask
                         const next = _overlayVisibility + 1;
                         _overlayVisibility = next >= nMasks ? 'all' : next;
+                        if (_overlayVisibility === 'all') setVfield(true);
                     }
                     // Status message
                     if (_overlayVisibility === 'all') {
@@ -9258,6 +9310,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                         showStatus(`overlay ${_overlayVisibility + 1}/${nMasks}${colorTag}`);
                     }
                     updateView();
+                    saveState();
                 },
             },
             'overlay.openPicker': {
@@ -9874,7 +9927,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                 when: [],
                 run: (ctx, e) => {
                     if (!hasVectorfield) {
-                        showStatus('U: no vector field loaded');
+                        showStatus('no vector field loaded');
                         return;
                     } // kept inline: emits toast
                     vfieldVisible = !vfieldVisible;
@@ -10038,6 +10091,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                         v.rendering = false; v.pending = false; v.seq++;
                     });
                     mvViews.forEach(v => { mvDrawFrame(v); mvRender(v); });
+                    _debouncedHoverPrefetch();
                     showStatus('origin reset');
                 },
             },
@@ -10185,6 +10239,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                         indices[activeDim] = Math.min(shape[activeDim] - 1, indices[activeDim] + 1);
                         renderInfo();
                         mvViews.forEach(v => { mvDrawFrame(v); mvRender(v); });
+                        _debouncedHoverPrefetch();
                         saveState();
                     } else if (activeDim === dim_x) {
                         flip_x = !flip_x;
@@ -10215,6 +10270,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                         indices[activeDim] = Math.max(0, indices[activeDim] - 1);
                         renderInfo();
                         mvViews.forEach(v => { mvDrawFrame(v); mvRender(v); });
+                        _debouncedHoverPrefetch();
                         saveState();
                     } else if (activeDim === dim_x) {
                         flip_x = !flip_x;
@@ -10337,7 +10393,6 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
             // Order matters: seg.exit (when segMode) takes precedence over slice.cancelJump
             { key: 'Escape', command: 'seg.exit' },
             { key: 'Escape', command: 'slice.cancelJump' },
-            { key: 'U', command: 'vfield.toggleArrows' },
             { key: 'u', command: 'ruler.toggle' },
         ];
 
@@ -10362,97 +10417,189 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
         const GUIDE_TABS = [
             {
                 id: 'basics', label: 'Basics',
-                desc: 'The essentials for navigating and adjusting any array.',
+                desc: 'The essentials for exploring any array. Move through slices, zoom into details, or play through a volume as an animation. These controls work everywhere.',
+                columns: 2,
+                sections: [
+                    {
+                        title: 'Slices & Dimensions',
+                        entries: [
+                            { key: '← → ↑ ↓', action: 'Step through slices' },
+                            { key: 'x / y', action: 'Change viewing dimension', hint: 'choose which axes map to horizontal and vertical' },
+                            { key: 'z', action: 'Mosaic — tile all slices in a grid' },
+                            { key: '1–9 Enter', action: 'Jump to a specific slice number' },
+                        ]
+                    },
+                    {
+                        title: 'Playback',
+                        entries: [
+                            { key: 'Space', action: 'Play / pause animation' },
+                            { key: '< >', action: 'Slower / faster playback' },
+                        ]
+                    },
+                    {
+                        title: 'Info & Search',
+                        entries: [
+                            { key: 'i', action: 'Toggle hover pixel info', hint: 'shows coordinates and value under cursor' },
+                            { key: 'I', action: 'Info panel', hint: 'array shape, dtype, memory layout' },
+                            { key: '/', action: 'Command palette', hint: 'search all available commands' },
+                        ]
+                    },
+                    {
+                        title: 'Zoom & Pan', columnBreak: true,
+                        entries: [
+                            { key: 'Pinch / ⌘Scroll', action: 'Zoom in / out', hint: 'Ctrl+Scroll on Windows / Linux' },
+                            { key: '0', action: 'Reset zoom to fit' },
+                            { key: 'Drag', action: 'Pan the image (when zoomed in)' },
+                            { key: 'F', action: 'Zen mode — hide UI chrome', hint: 'strips away panels and controls to focus on the image' },
+                        ]
+                    },
+                    {
+                        title: 'Export',
+                        entries: [
+                            { key: 's', action: 'Save screenshot' },
+                            { key: 'g', action: 'Save GIF animation' },
+                            { key: 'e', action: 'Copy shareable URL' },
+                        ]
+                    }
+                ]
+            },
+            {
+                id: 'display', label: 'Display',
+                desc: 'Control how your data looks. Adjust colors and the display range to bring out features that aren\u2019t visible with default settings.',
                 columns: 2,
                 sections: [
                     {
-                        title: 'Navigation',
+                        title: 'Color & Range',
+                        entries: [
+                            { key: 'c', action: 'Cycle colormap', hint: 'grayscale, viridis, turbo, and more' },
+                            { key: 'd', action: 'Cycle display range presets', hint: 'clips outliers — press repeatedly to tighten' },
+                            { key: 'L', action: 'Toggle log scale', hint: 'when values span several orders of magnitude' },
+                            { key: 'T', action: 'Cycle theme', hint: 'dark, light, solarized, nord' },
+                            { key: 'b', action: 'Toggle canvas borders' },
+                        ]
+                    },
+                    {
+                        title: 'Colorbar',
                         entries: [
-                            { key: '← → ↑ ↓', action: 'navigate slices', hint: 'step through the volume one slice at a time' },
-                            { key: 'x / y', action: 'change viewing dimension', hint: 'choose which axes map to screen x and y' },
-                            { key: 'z', action: 'toggle mosaic', hint: 'tile all slices of the current axis in a grid' },
-                            { key: 'scroll', action: 'zoom in / out', hint: 'pinch-to-zoom on trackpad' },
-                            { key: '0', action: 'reset zoom to fit' },
-                            { key: 'space', action: 'play / pause', hint: '< > adjust playback speed' },
+                            { key: 'Scroll', action: 'Narrow or widen the display range' },
+                            { key: 'Drag handles', action: 'Adjust min / max bounds' },
+                            { key: 'Drag bar', action: 'Shift the visible range up or down' },
+                            { key: 'Dbl-click', action: 'Expand histogram' },
+                            { key: 'Dbl-click label', action: 'Type an exact min or max value' },
                         ]
                     },
                     {
-                        title: 'Display',
+                        title: 'Transforms', columnBreak: true,
                         entries: [
-                            { key: 'i', action: 'toggle hover pixel info', hint: 'show coordinates and value under cursor' },
-                            { key: 'c', action: 'cycle colormap', hint: 'grayscale, viridis, turbo, etc.' },
-                            { key: 'd', action: 'open histogram / cycle quantiles', hint: 'press repeatedly to tighten the intensity range' },
-                            { key: 'I', action: 'info panel', hint: 'array shape, dtype, memory layout' },
-                            { key: '/', action: 'command palette', hint: 'search all commands' },
+                            { key: 'f', action: 'FFT — view frequency domain', hint: 'press again to return to spatial domain' },
+                            { key: 'p', action: 'Cycle projections', hint: 'MAX → MIN → MEAN → STD → off' },
+                            { key: 'm', action: 'Complex mode cycle', hint: 'magnitude → phase → real → imaginary' },
                         ]
                     }
                 ]
             },
             {
                 id: 'ortho', label: 'Ortho View',
-                desc: 'Three synchronized panels showing axial, sagittal, and coronal views of a 3D volume. Crosshairs link the views so clicking in one updates the others.',
+                desc: 'Three synchronized panels showing your volume from three directions at once. A crosshair links the views — clicking in one panel updates the other two. Great for exploring 3D data like MRI scans, where you need to see axial, sagittal, and coronal slices together.',
                 sections: [
                     {
+                        title: 'Controls',
                         entries: [
-                            { key: 'V', action: 'Toggle ortho view', hint: 'Enter or exit the three-panel layout' },
-                            { key: 'Click', action: 'Set crosshair position', hint: 'Click any panel to jump all views to that point' },
-                            { key: '← → ↑ ↓', action: 'Move crosshair', hint: 'Fine-tune position with arrow keys' },
-                            { key: 'Scroll', action: 'Zoom focused panel', hint: 'Zoom applies to the panel under the cursor' },
-                            { key: 'X Y Z', action: 'Switch axis', hint: 'View the volume from a different orientation' },
+                            { key: 'v', action: 'Enter or exit ortho view' },
+                            { key: 'Click / Drag', action: 'Set crosshair position', hint: 'click any panel to jump all views to that point, or drag to scrub' },
+                            { key: 'Drag lines', action: 'Reposition slice planes', hint: 'each colored line corresponds to a slice in another panel' },
+                            { key: 'p', action: 'Maximum intensity projection (MIP)', hint: '3D volume rendering — drag to rotate' },
+                            { key: 'o', action: 'Reset to origin' },
                         ]
                     }
                 ]
             },
             {
-                id: 'roi', label: 'ROI',
-                desc: 'Draw a region of interest to see local statistics (mean, std, min, max) and restrict the histogram to that region.',
+                id: 'compare', label: 'Compare',
+                desc: 'View two or more arrays side by side, blend them together, or compute a difference map. Useful for checking registration, comparing model outputs, or inspecting before-and-after changes. Open multiple arrays with the file picker first.',
                 sections: [
                     {
+                        title: 'Layout',
                         entries: [
-                            { key: 'Shift+R', action: 'Toggle ROI mode', hint: 'Enter or exit ROI drawing mode' },
-                            { key: 'Drag', action: 'Draw ROI rectangle', hint: 'Click and drag on the image to select a region' },
-                            { key: 'R', action: 'Cycle ROI shape', hint: 'Switch between rectangle, ellipse, and freehand' },
-                            { key: 'Esc', action: 'Clear ROI', hint: 'Remove the current selection and exit ROI mode' },
+                            { key: 'G', action: 'Cycle layout', hint: 'horizontal → vertical → grid' },
+                            { key: 'Drag title', action: 'Reorder panes by dragging their title bar' },
+                        ]
+                    },
+                    {
+                        title: 'Operations (requires exactly 2 arrays)',
+                        entries: [
+                            { key: 'X', action: 'Cycle compare operation', hint: 'off → A−B → |A−B| → relative → overlay → wipe → flicker → checkerboard' },
+                            { key: '[ ]', action: 'Adjust operation parameter', hint: 'blend amount, flicker speed, or checkerboard tile size' },
                         ]
                     }
                 ]
             },
             {
-                id: 'seg', label: 'Segmentation',
-                desc: 'Overlay label maps on your image. Load a segmentation array and toggle visibility, adjust opacity, or pick labels interactively.',
+                id: 'tools', label: 'Tools',
+                desc: 'Draw on the image to measure, segment, or crop. Each tool uses click or drag to define a region, and shows results in real time.',
                 sections: [
                     {
+                        subsection: 'ROI — Region of Interest',
+                        subdesc: 'Draw a region to see live statistics (mean, std, min, max). The histogram updates to show only the selected area.',
+                        entries: [
+                            { key: 'R', action: 'Toggle ROI mode' },
+                            { key: 'r', action: 'Cycle shape', hint: 'rectangle → circle → freehand → flood fill' },
+                            { key: 'Drag', action: 'Draw ROI region' },
+                            { key: 'Right-click', action: 'Delete ROI under cursor' },
+                            { key: 'Esc', action: 'Clear all and exit' },
+                        ]
+                    },
+                    {
+                        subsection: 'Ruler',
+                        subdesc: 'Click two points to measure pixel distance.',
+                        entries: [
+                            { key: 'u', action: 'Toggle ruler mode' },
+                        ]
+                    },
+                    {
+                        subsection: 'Segmentation',
+                        subdesc: 'Interactive segmentation with nnInteractive. Click to add or exclude regions from the label.',
                         entries: [
-                            { key: 'S', action: 'Cycle segmentation mode', hint: 'Toggle through available segmentation overlays' },
-                            { key: 'M', action: 'Toggle mask / adjust alpha', hint: 'Control overlay transparency' },
-                            { key: 'Click', action: 'Pick label', hint: 'Click on the image to identify a segmentation label' },
-                            { key: 'Esc', action: 'Exit segmentation mode' },
+                            { key: 'S', action: 'Toggle segmentation mode' },
+                            { key: 'Click', action: 'Add region (positive prompt)' },
+                            { key: 'Shift+Click', action: 'Exclude region (negative prompt)' },
+                            { key: 'Esc', action: 'Exit segmentation' },
                         ]
                     }
                 ]
             },
             {
-                id: 'compare', label: 'Compare',
-                desc: 'View two arrays side by side, overlay them, or compute a difference map. Useful for checking registration, model outputs, or before/after changes.',
+                id: 'overlays', label: 'Overlays',
+                desc: 'Extra layers displayed on top of your array. Load segmentation masks with --overlay or deformation fields with --vectorfield when launching arrayview. Press O to toggle visibility for all overlays at once.',
                 sections: [
                     {
+                        subsection: 'Segmentation Masks',
+                        subdesc: 'Binary masks rendered as colored layers on the image. Load one or more with --overlay mask1.nii,mask2.nii. Each mask gets its own color.',
+                        entries: [
+                            { key: 'O', action: 'Cycle visibility', hint: 'all → none → individual masks (if multiple)' },
+                            { key: '[ ]', action: 'Adjust opacity' },
+                        ]
+                    },
+                    {
+                        subsection: 'Vector Field',
+                        subdesc: 'Deformation or flow fields rendered as arrows. Load with --vectorfield field.nii.',
                         entries: [
-                            { key: 'n', action: 'cycle compare target', hint: 'switch which array you\'re comparing against' },
-                            { key: 'G', action: 'Cycle compare layout', hint: 'Side-by-side, overlay, checkerboard, or diff' },
-                            { key: 'Z', action: 'Toggle focus mode', hint: 'Zoom into the comparison view' },
+                            { key: 'O', action: 'Toggle visibility' },
+                            { key: '[ ]', action: 'Adjust arrow density' },
+                            { key: '{ }', action: 'Adjust arrow length' },
                         ]
                     }
                 ]
             },
             {
                 id: 'qmri', label: 'qMRI',
-                desc: 'Quantitative MRI mode for parameter maps (T1, T2, FA, etc.). Displays voxel values with proper units and provides tissue-specific presets.',
+                desc: 'For quantitative MRI parameter maps — T1, T2, FA, and others. Voxel values are shown with proper units and the display adjusts to tissue-specific intensity ranges. Use this when viewing parameter maps to get meaningful readouts instead of raw numbers.',
                 sections: [
                     {
+                        title: 'Controls',
                         entries: [
-                            { key: 'q', action: 'enter / cycle / exit qMRI', hint: 'step through available qMRI parameter modes' },
-                            { key: 'Z', action: 'Toggle qMRI mosaic', hint: 'See all parameter maps in a grid' },
-                            { key: 'R', action: 'Cycle range preset', hint: 'Tissue-specific intensity ranges for each parameter' },
+                            { key: 'q', action: 'Enter / cycle / exit qMRI mode', hint: 'steps through available parameter types' },
+                            { key: 'z', action: 'Toggle qMRI mosaic', hint: 'see all parameter maps side by side in a grid' },
                         ]
                     }
                 ]
@@ -10491,10 +10638,37 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                 const wrapper = document.createElement('div');
                 if (tab.columns === 2) wrapper.className = 'help-columns';
 
+                let col = null; // current column container
                 for (const section of tab.sections) {
-                    const col = document.createElement('div');
-                    if (tab.columns === 2) col.className = 'help-column';
+                    // Start a new column if 2-column layout and this is the first section or a columnBreak
+                    if (tab.columns === 2) {
+                        if (!col || section.columnBreak) {
+                            col = document.createElement('div');
+                            col.className = 'help-column';
+                            wrapper.appendChild(col);
+                        }
+                    } else {
+                        if (!col) {
+                            col = wrapper; // single-column: append directly to wrapper
+                        }
+                    }
+
+                    // Subsection header (bold title + description paragraph)
+                    if (section.subsection) {
+                        const subTitle = document.createElement('div');
+                        subTitle.className = 'help-subsection-title';
+                        subTitle.textContent = section.subsection;
+                        col.appendChild(subTitle);
 
+                        if (section.subdesc) {
+                            const subDesc = document.createElement('div');
+                            subDesc.className = 'help-subsection-desc';
+                            subDesc.textContent = section.subdesc;
+                            col.appendChild(subDesc);
+                        }
+                    }
+
+                    // Section title (uppercase label with divider)
                     if (section.title) {
                         const titleEl = document.createElement('div');
                         titleEl.className = 'help-section-title';
@@ -10530,8 +10704,6 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
 
                         col.appendChild(entryEl);
                     }
-
-                    wrapper.appendChild(col);
                 }
 
                 panel.appendChild(wrapper);
@@ -11577,6 +11749,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                     activeDim = view.sliceDir;
                     renderInfo();
                     mvViews.forEach(v => { mvDrawFrame(v); mvRender(v); });
+                    _debouncedHoverPrefetch();
                     saveState();
                 }, { passive: false });
                 cv.addEventListener('mousedown', (e) => {
@@ -12319,6 +12492,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                         indices[current_slice_dim] = Math.max(0, Math.min(shape[current_slice_dim] - 1, indices[current_slice_dim] + delta));
                         renderInfo();
                         qmriViews.forEach(v => qvRender(v));
+                        _debouncedHoverPrefetch();
                         saveState();
                     }, { passive: false });
                     cv.addEventListener('mousemove', (e) => {
@@ -12538,6 +12712,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                         indices[current_slice_dim] = Math.max(0, Math.min(shape[current_slice_dim] - 1, indices[current_slice_dim] + delta));
                         renderInfo();
                         compareQmriViews.forEach(v => compareQmriRender(v));
+                        _debouncedHoverPrefetch();
                         saveState();
                     }, { passive: false });
                     cv.addEventListener('mousemove', (e) => {
@@ -12891,6 +13066,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                         indices[view.sliceDir] = Math.max(0, Math.min(shape[view.sliceDir] - 1, indices[view.sliceDir] + delta));
                         renderInfo();
                         compareMvViews.forEach(v => compareMvRender(v));
+                        _debouncedHoverPrefetch();
                         saveState();
                     }, { passive: false });
                     cv.addEventListener('mousedown', (e) => {
@@ -12995,6 +13171,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                 fy ? shape[view.dimY] - 1 - Math.floor(py) : Math.floor(py)));
             renderInfo();
             compareMvViews.forEach(v => { compareMvDrawFrame(v); compareMvRender(v); });
+            _debouncedHoverPrefetch();
         }
 
         function exitCompareMv() {
@@ -13641,6 +13818,7 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                 renderInfo();
                 mvViews.forEach(v => { mvDrawFrame(v); mvRender(v); });
             }
+            _debouncedHoverPrefetch();
         }
 
         async function mvRenderOblique(v) {
@@ -14333,7 +14511,8 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                 else if (compareMvActive) compareMvViews.forEach(v => compareMvRender(v));
                 else if (multiViewActive) mvViews.forEach(v => { mvDrawFrame(v); mvRender(v); });
                 else if (qmriActive) qmriViews.forEach(v => qvRender(v));
-                else updateView();
+                else { updateView(); return; }
+                _debouncedHoverPrefetch();
             }
         });
         document.addEventListener('mouseup', (e) => {
@@ -14388,7 +14567,10 @@ h1{font-size:22px;border-bottom:1px solid #2c2c2c;padding-bottom:12px;}</style><
                 qmriViews.forEach(v => qvRender(v));
             } else {
                 updateView();
+                saveState();
+                return;
             }
+            _debouncedHoverPrefetch();
             saveState();
         }, { passive: false });
 

{arrayview-0.12.1 → arrayview-0.12.2}/src/arrayview/_vscode.py

@@ -733,11 +733,48 @@ def _write_vscode_signal(payload: dict, delay: float = 0.0, skip_compat: bool =
                     uses_pid = _reg_data.get("fallbackId", False)
                 except Exception:
                     uses_pid = env_wid.isdigit()
+
+                # Guard against stale ARRAYVIEW_WINDOW_ID: when the extension
+                # host restarts (e.g. tunnel reconnection), the old process may
+                # still be alive but is no longer connected to a VS Code client.
+                # Detect this by looking for a newer registration from the same
+                # server (same first ppid — the tunnel/server parent process).
+                _env_ts = _reg_data.get("ts", 0)
+                _env_ppids = _reg_data.get("ppids", [])
+                try:
+                    for _fname in os.listdir(signal_dir):
+                        if not (_fname.startswith("window-") and _fname.endswith(".json")):
+                            continue
+                        _other_wid = _fname[7:-5]
+                        if _other_wid == env_wid:
+                            continue
+                        with open(os.path.join(signal_dir, _fname)) as _f:
+                            _other = json.load(_f)
+                        _other_ts = _other.get("ts", 0)
+                        _other_ppids = _other.get("ppids", [])
+                        if (
+                            _other_ts > _env_ts
+                            and len(_env_ppids) >= 1
+                            and len(_other_ppids) >= 1
+                            and _env_ppids[0] == _other_ppids[0]
+                        ):
+                            _vprint(
+                                f"[ArrayView] signal: ARRAYVIEW_WINDOW_ID={env_wid} is stale "
+                                f"(newer registration {_other_wid} found), redirecting",
+                                flush=True,
+                            )
+                            env_wid = _other_wid
+                            _reg_data = _other
+                            uses_pid = _other.get("fallbackId", False)
+                            _env_ts = _other_ts
+                except Exception:
+                    pass
+
                 _prefix = "pid" if uses_pid else "ipc"
                 filenames = (f"open-request-{_prefix}-{env_wid}.json",)
                 targeted_via_env = True
                 _vprint(
-                    f"[ArrayView] signal: ARRAYVIEW_WINDOW_ID={env_wid} → {filenames[0]}",
+                    f"[ArrayView] signal: ARRAYVIEW_WINDOW_ID → {filenames[0]}",
                     flush=True,
                 )
 
@@ -868,6 +905,39 @@ def _write_vscode_signal(payload: dict, delay: float = 0.0, skip_compat: bool =
                         _uses_pid = _reg_data.get("fallbackId", False)
                     except Exception:
                         _uses_pid = env_wid.isdigit()
+
+                    # Same stale-env guard as the primary check above.
+                    _env_ts = _reg_data.get("ts", 0)
+                    _env_ppids = _reg_data.get("ppids", [])
+                    try:
+                        for _fname in os.listdir(signal_dir):
+                            if not (_fname.startswith("window-") and _fname.endswith(".json")):
+                                continue
+                            _other_wid = _fname[7:-5]
+                            if _other_wid == env_wid:
+                                continue
+                            with open(os.path.join(signal_dir, _fname)) as _f:
+                                _other = json.load(_f)
+                            _other_ts = _other.get("ts", 0)
+                            _other_ppids = _other.get("ppids", [])
+                            if (
+                                _other_ts > _env_ts
+                                and len(_env_ppids) >= 1
+                                and len(_other_ppids) >= 1
+                                and _env_ppids[0] == _other_ppids[0]
+                            ):
+                                _vprint(
+                                    f"[ArrayView] signal: remote env {env_wid} is stale "
+                                    f"(newer {_other_wid}), redirecting",
+                                    flush=True,
+                                )
+                                env_wid = _other_wid
+                                _reg_data = _other
+                                _uses_pid = _other.get("fallbackId", False)
+                                _env_ts = _other_ts
+                    except Exception:
+                        pass
+
                     _prefix = "pid" if _uses_pid else "ipc"
                     _vprint(f"[ArrayView] signal: env window match → {_prefix}-{env_wid}", flush=True)
                     filenames = (f"open-request-{_prefix}-{env_wid}.json",)

{arrayview-0.12.1 → arrayview-0.12.2}/uv.lock

@@ -44,7 +44,7 @@ wheels = [
 
 [[package]]
 name = "arrayview"
-version = "0.12.1"
+version = "0.12.2"
 source = { editable = "." }
 dependencies = [
     { name = "fastapi" },

{arrayview-0.12.1 → arrayview-0.12.2}/vscode-extension/extension.js

@@ -824,6 +824,34 @@ function activate(context) {
 
     cleanupStaleFiles();
 
+    // Clean up stale registrations from previous tunnel sessions.
+    // When the extension host restarts (e.g. tunnel reconnect), the old
+    // process may still be alive but is no longer connected to a VS Code
+    // client.  Detect by finding registrations with the same first ppid
+    // (same server/tunnel) but an older timestamp.
+    if (EXT_PPIDS.length >= 1) {
+        try {
+            const now = Date.now();
+            for (const f of fs.readdirSync(SIGNAL_DIR)) {
+                if (!f.startsWith('window-') || !f.endsWith('.json')) continue;
+                const wid = f.slice(7, -5);
+                if (wid === windowId) continue;
+                try {
+                    const data = JSON.parse(fs.readFileSync(path.join(SIGNAL_DIR, f), 'utf8'));
+                    const sameTunnel = data.ppids && data.ppids.length >= 1 &&
+                        data.ppids[0] === EXT_PPIDS[0];
+                    if (sameTunnel && data.ts && data.ts < now - 5000) {
+                        fs.unlinkSync(path.join(SIGNAL_DIR, f));
+                        log(`CLEANUP: removed stale same-tunnel registration ${f} (ts=${data.ts})`);
+                        // Also remove any stale signal files targeting that window
+                        const prefix = data.fallbackId ? 'pid' : 'ipc';
+                        try { fs.unlinkSync(path.join(SIGNAL_DIR, `open-request-${prefix}-${wid}.json`)); } catch (_) {}
+                    }
+                } catch (_) {}
+            }
+        } catch (_) {}
+    }
+
     void tryOpenSignalFile();
 
     const interval = setInterval(() => void tryOpenSignalFile(), 1000);