arrayview 0.11.0__tar.gz → 0.12.0__tar.gz

{arrayview-0.11.0 → arrayview-0.12.0}/AGENTS.md

@@ -2,6 +2,9 @@ Read `src/arrayview/ARCHITECTURE.md` for codebase orientation.
 
 # ArrayView
 
+I haven't written or read a single line of code in src so when you ask me questions/input,
+keep it simple with some simple examples.
+
 ## Skills
 
 Load the relevant skill before touching the corresponding area.
@@ -24,6 +27,7 @@ Load the relevant skill before touching the corresponding area.
 - For visual/animation features, propose 2-3 options BEFORE implementing
 - UI visibility changes go through reconcilers (`_reconcileUI`/`_reconcileLayout`/`_reconcileCompareState`/`_reconcileCbVisibility`), not inline `style.display` or `classList` toggles in mode functions
 - All colorbar state (animation, window/level, hover, drag) flows through `primaryCb` ColorBar instance — never read/write legacy globals. Multiview colorbars sync via `primaryCb`.
+- Keybinds flow through the command registry (`commands` / `keybinds` in `_viewer.html`), not inline keydown branches. The help overlay auto-generates from command `title` fields — do not hand-edit it.
 
 ## Execution
 
@@ -32,9 +36,11 @@ Always use **subagent-driven development** for implementation. Commit completed
 ## Testing
 
 ```bash
-uv run pytest tests/test_api.py -v       # HTTP API
-uv run pytest tests/test_browser.py -v   # Playwright
-uv run python tests/visual_smoke.py      # screenshots
+uv run pytest tests/test_api.py -v                    # HTTP API
+uv run pytest tests/test_browser.py -v                # Playwright
+uv run pytest tests/test_mode_roundtrip.py -v         # mode state round-trip
+uv run pytest tests/test_command_reachability.py -v   # command when-clause matrix
+uv run python tests/visual_smoke.py                   # screenshots
 ```
 
 After any UI change, use `/ui-consistency-audit` to verify across all modes.

arrayview-0.12.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: arrayview
+Version: 0.12.0
+Summary: Fast multi-dimensional array viewer
+Project-URL: Home, https://github.com/oscarvanderheide/arrayview
+Project-URL: Source, https://github.com/oscarvanderheide/arrayview
+Author-email: Oscar <oscarvanderheide@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: array,mri,npy,viewer,visualization
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.129.0
+Requires-Dist: h5py>=3.0
+Requires-Dist: matplotlib>=3.9.0
+Requires-Dist: nibabel>=5.3.3
+Requires-Dist: numpy>=2.4.2
+Requires-Dist: pillow>=12.1.1
+Requires-Dist: pyqt5>=5.15; sys_platform == 'linux'
+Requires-Dist: pyqtwebengine>=5.15; sys_platform == 'linux'
+Requires-Dist: python-multipart>=0.0.22
+Requires-Dist: pywebview>=6.1
+Requires-Dist: qmricolors>=0.1.2
+Requires-Dist: qtpy>=2.0; sys_platform == 'linux'
+Requires-Dist: scipy>=1.10
+Requires-Dist: tifffile>=2023.1.1
+Requires-Dist: uvicorn>=0.41.0
+Requires-Dist: websockets>=14.0
+Requires-Dist: zarr>=2.17
+Description-Content-Type: text/markdown
+
+# <img src="docs/logo.png" height="36"> arrayview
+
+This is what looking at arrays should feel like.
+
+Load up `.npy`, `.nii`, `.h5`, `.mat` and friends. Works locally, in Jupyter, over SSH and VS Code tunnels. Press `?` once you're in.
+
+## CLI
+
+```bash
+uvx arrayview your_array.npy
+```
+
+## Python
+
+```bash
+uv add arrayview
+```
+
+```python
+from arrayview import view
+view(arr)
+```
+
+[docs →](https://oscarvanderheide.github.io/arrayview/)
+

arrayview-0.12.0/README.md

@@ -0,0 +1,25 @@
+# <img src="docs/logo.png" height="36"> arrayview
+
+This is what looking at arrays should feel like.
+
+Load up `.npy`, `.nii`, `.h5`, `.mat` and friends. Works locally, in Jupyter, over SSH and VS Code tunnels. Press `?` once you're in.
+
+## CLI
+
+```bash
+uvx arrayview your_array.npy
+```
+
+## Python
+
+```bash
+uv add arrayview
+```
+
+```python
+from arrayview import view
+view(arr)
+```
+
+[docs →](https://oscarvanderheide.github.io/arrayview/)
+

{arrayview-0.11.0 → arrayview-0.12.0}/pyproject.toml

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

{arrayview-0.11.0 → arrayview-0.12.0}/src/arrayview/ARCHITECTURE.md

@@ -52,7 +52,7 @@ Detection logic lives in `_platform.py`. Display opening logic lives in `_launch
 | `_stdio_server.py` | 791 | Stdio transport for VS Code direct webview — JSON stdin, binary stdout |
 | `_torch.py` | 217 | PyTorch integration: `view_batch()`, `TrainingMonitor` (lazy torch import) |
 | `_vscode.py` | 1014 | VS Code extension install/management, signal-file IPC, shared-memory IPC, browser opening |
-| `_viewer.html` | 14480 | **The entire frontend** — CSS + JS in a single file, all viewing modes |
+| `_viewer.html` | 15600 | **The entire frontend** — CSS + JS in a single file, all viewing modes |
 | `_shell.html` | 174 | Tab-bar shell for native pywebview — wraps viewer iframes, manages multi-tab sessions |
 
 ## Frontend (_viewer.html)
@@ -89,7 +89,7 @@ The frontend is a single self-contained HTML file (~15k lines). No build step, n
 | Rendering Pipeline | `updateView()`, play/animate, screenshot capture |
 | ROI and Selection Modes | Rectangle/ellipse ROI drawing, statistics computation |
 | nnInteractive Segmentation | Click-to-segment UI, mask overlay, undo stack |
-| Keyboard Shortcuts | All hotkey bindings — single master switch/case block |
+| Keyboard Shortcuts | Command registry (`commands` / `keybinds` / `makeContext` / `evalWhen` / `dispatchCommand`) + `/`-triggered command palette. Keydown handler is a thin dispatcher prefix |
 | Mode Transitions | Compare/multiview/qMRI enter/exit, crosshair animation |
 | Scroll, Zoom, and Pan | Mouse wheel slice scroll, pinch zoom, scroll-to-zoom |
 | Immersive Mode, Cross-Fade, and Visual Effects | Zen mode, fullscreen (K), animated transitions |
@@ -136,6 +136,9 @@ Pill-shaped badges below the canvas showing active visualization transforms. **C
 ### Dynamic Islands
 Floating UI panels that appear/disappear based on context: ROI statistics, segmentation controls, colorbar hover, dimension sliders. Must be tested across all viewing modes (normal, immersive, multiview, compare).
 
+### Command Registry
+All keybinds flow through a VS Code-style command registry in `_viewer.html`. Three tables: `commands` (id → `{title, when, run}`), `keybinds` (key+modifiers → command id), and `makeContext(state)` (mode/state flag bag). `dispatchCommand(e)` is wired as a prefix to the keydown handler; on a match it evaluates `when` against the context and runs the command, otherwise falls through. The help overlay is auto-generated from command `title` fields — never hand-edit it. A `/`-triggered command palette fuzzy-searches all commands. Cross-mode enablement is guarded by `tests/test_command_reachability.py`.
+
 ### Reconcilers
 Functions in the "UI Validation and Reconciliation" section (~line 13666) that enforce consistent UI state. When mode changes happen, reconcilers update visibility of containers, colorbars, dynamic islands, and compare sub-mode UI. There are four:
 1. **Unified UI reconciler** — master state enforcer
@@ -156,6 +159,9 @@ A dedicated daemon thread (`_session.py`) runs all CPU-heavy rendering off the a
 ### Dynamic Islands
 Must verify island positioning and visibility across normal, immersive, multiview, and compare modes. Islands use absolute/fixed positioning that breaks if parent containers change.
 
+### Keybind Changes
+Keybinds live in the `commands` + `keybinds` tables, not in the keydown handler. Adding or changing a keybind means editing those tables and (if needed) extending `makeContext` / `evalWhen`. The help overlay regenerates itself from command `title` fields — do not edit overlay HTML directly.
+
 ### Layout Debugging
 When debugging layout issues: identify the root cause (which scale function, which reconciler, which CSS rule) before applying fixes. Symptoms in one mode often originate from shared code affecting all modes.
 

{arrayview-0.11.0 → arrayview-0.12.0}/src/arrayview/_io.py

@@ -124,6 +124,71 @@ def _select_npz_array(npz, filepath):
         print(f"  Please enter a number between 1 and {len(entries)}.")
 
 
+def _load_nifti_with_meta(filepath):
+    """Load a NIfTI file, canonical-reorient, return (array, meta).
+
+    meta is a dict with keys:
+      affine            : original 4x4 affine (RAS+ mm)
+      affine_canonical  : 4x4 affine after as_closest_canonical
+      voxel_sizes       : tuple (sx, sy, sz) in mm, post-reorient
+      axis_labels       : tuple of 3 strs from {"R","L","A","P","S","I"}
+                          — positive direction of each canonical axis
+      is_oblique        : bool — True if rotation part has off-diagonal magnitude > 1e-3
+                          after normalizing voxel sizes
+    """
+    nib = _nib()
+    img = nib.load(filepath)
+    original_affine = np.asarray(img.affine, dtype=np.float64)
+    canon = nib.as_closest_canonical(img)
+    affine_canonical = np.asarray(canon.affine, dtype=np.float64)
+
+    # NOTE: reorient requires materializing axis permutes/flips. .nii.gz is
+    # already eager (gzip not seekable), so this is free; .nii loses mmap as a
+    # necessary cost to apply the reorient.
+    arr = np.asarray(canon.dataobj)
+
+    rot = affine_canonical[:3, :3]
+    voxel_sizes = tuple(float(np.linalg.norm(rot[:, i])) for i in range(3))
+
+    # Direction of each canonical axis (sign of diagonal after normalizing)
+    norm_rot = np.zeros((3, 3))
+    for i in range(3):
+        if voxel_sizes[i] > 0:
+            norm_rot[:, i] = rot[:, i] / voxel_sizes[i]
+    pos_labels = ("R", "A", "S")
+    neg_labels = ("L", "P", "I")
+    axis_labels = tuple(
+        pos_labels[i] if norm_rot[i, i] >= 0 else neg_labels[i] for i in range(3)
+    )
+
+    # Oblique = off-diagonal of normalized rotation has |val| > tol
+    off_diag_max = 0.0
+    for i in range(3):
+        for j in range(3):
+            if i != j:
+                off_diag_max = max(off_diag_max, abs(norm_rot[i, j]))
+    is_oblique = bool(off_diag_max > 1e-3)
+
+    meta = {
+        "affine": original_affine,
+        "affine_canonical": affine_canonical,
+        "voxel_sizes": voxel_sizes,
+        "axis_labels": axis_labels,
+        "is_oblique": is_oblique,
+    }
+    return arr, meta
+
+
+def load_data_with_meta(filepath):
+    """Like load_data but also returns spatial metadata for NIfTI files.
+
+    Returns (array, meta_or_None). meta is None for non-NIfTI formats.
+    """
+    if filepath.endswith(".nii") or filepath.endswith(".nii.gz"):
+        return _load_nifti_with_meta(filepath)
+    return load_data(filepath), None
+
+
 def load_data(filepath):
     if filepath.endswith(".npy"):
         return np.load(filepath, mmap_mode="r")

{arrayview-0.11.0 → arrayview-0.12.0}/src/arrayview/_launcher.py

@@ -1654,10 +1654,10 @@ def _serve_daemon(
     ).start()
 
     def _load():
-        from arrayview._io import load_data
+        from arrayview._io import load_data, load_data_with_meta
 
         try:
-            data = load_data(filepath)
+            data, spatial_meta = load_data_with_meta(filepath)
             if cleanup:
                 try:
                     os.unlink(filepath)
@@ -1667,6 +1667,9 @@ def _serve_daemon(
                 data, filepath=None if cleanup else filepath, name=name
             )
             session.sid = sid
+            session.spatial_meta = spatial_meta
+            if spatial_meta is not None:
+                session.original_volume = data
             if rgb:
                 from arrayview._render import _setup_rgb
 

{arrayview-0.11.0 → arrayview-0.12.0}/src/arrayview/_render.py

@@ -667,10 +667,12 @@ def render_mosaic(
     complex_mode=0,
     log_scale=False,
     mosaic_cols=None,
+    vmin_override=None,
+    vmax_override=None,
 ):
     idx_norm = list(idx_tuple)
     idx_norm[dim_z] = 0
-    key = (dim_x, dim_y, dim_z, tuple(idx_norm), colormap, dr, complex_mode, log_scale, mosaic_cols)
+    key = (dim_x, dim_y, dim_z, tuple(idx_norm), colormap, dr, complex_mode, log_scale, mosaic_cols, vmin_override, vmax_override)
     if key in session.mosaic_cache:
         session.mosaic_cache.move_to_end(key)
         return session.mosaic_cache[key]
@@ -690,7 +692,9 @@ def render_mosaic(
         frames = [np.log1p(np.abs(f)).astype(np.float32) for f in frames]
     all_data = np.stack(frames)
 
-    if complex_mode == 1 and np.iscomplexobj(session.data):
+    if vmin_override is not None and vmax_override is not None:
+        vmin, vmax = float(vmin_override), float(vmax_override)
+    elif complex_mode == 1 and np.iscomplexobj(session.data):
         vmin, vmax = -float(np.pi), float(np.pi)
     else:
         vmin = float(np.percentile(all_data, 1))

{arrayview-0.11.0 → arrayview-0.12.0}/src/arrayview/_server.py

@@ -404,6 +404,8 @@ async def websocket_endpoint(ws: WebSocket, sid: str):
                         complex_mode,
                         log_scale,
                         mosaic_cols=mosaic_cols,
+                        vmin_override=vmin_override,
+                        vmax_override=vmax_override,
                     ),
                 )
                 h, w = rgba.shape[:2]
@@ -744,7 +746,7 @@ async def get_metadata(sid: str):
     if not session:
         return Response(status_code=404)
     try:
-        return {
+        meta_dict = {
             "shape": [
                 int(s)
                 for s in (
@@ -759,6 +761,17 @@ async def get_metadata(sid: str):
             "vfield_n_times": _vfield_n_times(session),
             "is_rgb": session.rgb_axis is not None,
         }
+        if getattr(session, "spatial_meta", None) is not None:
+            sm = session.spatial_meta
+            meta_dict["spatial_meta"] = {
+                "voxel_sizes": list(sm["voxel_sizes"]),
+                "axis_labels": list(sm["axis_labels"]),
+                "is_oblique": bool(sm["is_oblique"]),
+            }
+            meta_dict["ras_resample_active"] = bool(
+                getattr(session, "ras_resample_active", False)
+            )
+        return meta_dict
     except Exception as e:
         import traceback
 
@@ -2124,9 +2137,116 @@ def get_info(sid: str, session: "Session" = Depends(get_session_or_404)):
         info["recommended_colormap_reason"] = None
     if session.fft_axes is not None:
         info["fft_axes"] = list(session.fft_axes)
+    if getattr(session, "spatial_meta", None) is not None:
+        sm = session.spatial_meta
+        info["spatial_meta"] = {
+            "voxel_sizes": list(sm["voxel_sizes"]),
+            "axis_labels": list(sm["axis_labels"]),
+            "is_oblique": bool(sm["is_oblique"]),
+        }
+        info["ras_resample_active"] = bool(getattr(session, "ras_resample_active", False))
     return info
 
 
+@app.post("/resample_ras/{sid}")
+async def resample_ras(sid: str, request: Request):
+    """Toggle RAS resample for a NIfTI session.
+
+    Body: {"enabled": true/false}
+    Returns:
+      - {"skipped": true, "reason": "axis_aligned"} if scan needs no resample
+      - {"skipped": true, "reason": "not_nifti"} if no spatial_meta
+      - {"ok": true, "shape": [...], "elapsed_ms": ...}  on success
+    """
+    import time
+
+    session = SESSIONS.get(sid)
+    if session is None:
+        return {"error": "session not found"}
+    body = await request.json()
+    enabled = bool(body.get("enabled", False))
+    sm = getattr(session, "spatial_meta", None)
+    if sm is None or session.original_volume is None:
+        return {"skipped": True, "reason": "not_nifti"}
+
+    if enabled:
+        if not sm["is_oblique"]:
+            return {"skipped": True, "reason": "axis_aligned"}
+        t0 = time.time()
+        if session.resampled_volume is None:
+            try:
+                from scipy.ndimage import affine_transform
+            except ImportError:
+                return {"error": "scipy not available"}
+            vol = session.original_volume
+            # Only resample the leading 3 spatial axes; pass higher dims through
+            # by resampling per-frame would be expensive — for v1 require ndim==3.
+            if vol.ndim != 3:
+                return {"skipped": True, "reason": "ndim_not_3"}
+            affine_canonical = sm["affine_canonical"]
+            rot = np.asarray(affine_canonical[:3, :3], dtype=np.float64)
+            iso = float(min(sm["voxel_sizes"]))
+            # Map all 8 input-volume corners to RAS to find output bounding box.
+            shp = vol.shape
+            corners_idx = np.array(
+                [[i, j, k]
+                 for i in (0, shp[0] - 1)
+                 for j in (0, shp[1] - 1)
+                 for k in (0, shp[2] - 1)],
+                dtype=np.float64,
+            )
+            origin = np.asarray(affine_canonical[:3, 3], dtype=np.float64)
+            ras = corners_idx @ rot.T + origin
+            ras_min = ras.min(axis=0)
+            ras_max = ras.max(axis=0)
+            out_shape = tuple(
+                int(np.ceil((ras_max[i] - ras_min[i]) / iso)) + 1 for i in range(3)
+            )
+            # Output index -> RAS: ras_min + idx * iso
+            # RAS -> input voxel: inv(rot) @ (ras - origin)
+            inv_rot = np.linalg.inv(rot)
+            matrix = inv_rot * iso  # output index -> input voxel (linear part)
+            offset = inv_rot @ (ras_min - origin)
+            try:
+                resampled = affine_transform(
+                    np.asarray(vol),
+                    matrix=matrix,
+                    offset=offset,
+                    output_shape=out_shape,
+                    order=1,
+                    cval=0.0,
+                    prefilter=False,
+                )
+            except Exception as exc:
+                return {"error": f"resample failed: {exc}"}
+            session.resampled_volume = resampled
+        session.data = session.resampled_volume
+        session.shape = session.resampled_volume.shape
+        if session.rgb_axis is None:
+            session.spatial_shape = session.shape
+        session.ras_resample_active = True
+        session.raw_cache.clear()
+        session.rgba_cache.clear()
+        session.mosaic_cache.clear()
+        session._raw_bytes = session._rgba_bytes = session._mosaic_bytes = 0
+        return {
+            "ok": True,
+            "shape": list(session.shape),
+            "elapsed_ms": int((time.time() - t0) * 1000),
+        }
+    else:
+        session.data = session.original_volume
+        session.shape = session.original_volume.shape
+        if session.rgb_axis is None:
+            session.spatial_shape = session.shape
+        session.ras_resample_active = False
+        session.raw_cache.clear()
+        session.rgba_cache.clear()
+        session.mosaic_cache.clear()
+        session._raw_bytes = session._rgba_bytes = session._mosaic_bytes = 0
+        return {"ok": True, "shape": list(session.shape)}
+
+
 @app.post("/fft/{sid}")
 async def toggle_fft(sid: str, request: Request):
     session = SESSIONS.get(sid)
@@ -2278,26 +2398,31 @@ def get_slice(
             complex_mode,
             log_scale,
             mosaic_cols=mosaic_cols,
+            vmin_override=vmin_override,
+            vmax_override=vmax_override,
         )
-        idx_norm = list(idx_tuple)
-        idx_norm[dim_z] = 0
-        frames_raw = [
-            extract_slice(
-                session,
-                dim_x,
-                dim_y,
-                [i if j == dim_z else idx_tuple[j] for j in range(len(session.shape))],
-            )
-            for i in range(session.shape[dim_z])
-        ]
-        frames = [apply_complex_mode(frame, complex_mode) for frame in frames_raw]
-        if log_scale:
-            frames = [np.log1p(np.abs(frame)).astype(np.float32) for frame in frames]
-            all_data = np.stack(frames)
-            vmin = float(np.percentile(all_data, 1))
-            vmax = float(np.percentile(all_data, 99))
+        if vmin_override is not None and vmax_override is not None:
+            vmin, vmax = float(vmin_override), float(vmax_override)
         else:
-            vmin, vmax = _compute_vmin_vmax(session, np.stack(frames), dr, complex_mode)
+            idx_norm = list(idx_tuple)
+            idx_norm[dim_z] = 0
+            frames_raw = [
+                extract_slice(
+                    session,
+                    dim_x,
+                    dim_y,
+                    [i if j == dim_z else idx_tuple[j] for j in range(len(session.shape))],
+                )
+                for i in range(session.shape[dim_z])
+            ]
+            frames = [apply_complex_mode(frame, complex_mode) for frame in frames_raw]
+            if log_scale:
+                frames = [np.log1p(np.abs(frame)).astype(np.float32) for frame in frames]
+                all_data = np.stack(frames)
+                vmin = float(np.percentile(all_data, 1))
+                vmax = float(np.percentile(all_data, 99))
+            else:
+                vmin, vmax = _compute_vmin_vmax(session, np.stack(frames), dr, complex_mode)
     else:
         if session.rgb_axis is not None:
             rgba = render_rgb_rgba(session, dim_x, dim_y, list(idx_tuple))
@@ -3174,10 +3299,14 @@ async def load_file(request: Request):
             except ImportError:
                 pass  # psutil not available — skip guard
     try:
-        data = await asyncio.to_thread(load_data, filepath)
+        from ._io import load_data_with_meta
+        data, spatial_meta = await asyncio.to_thread(load_data_with_meta, filepath)
     except Exception as e:
         return {"error": str(e)}
     session = await asyncio.to_thread(Session, data, filepath=filepath, name=name)
+    if spatial_meta is not None:
+        session.spatial_meta = spatial_meta
+        session.original_volume = data
     if body.get("rgb"):
         try:
             await asyncio.to_thread(_setup_rgb, session)

{arrayview-0.11.0 → arrayview-0.12.0}/src/arrayview/_session.py

@@ -173,8 +173,23 @@ class Session:
         self.vfield_time_dim = None  # optional time axis in the raw vfield array
         self.vfield_spatial_axes = None  # image spatial dim -> vfield axis mapping
 
+        # Spatial metadata for NIfTI files (None for other formats).
+        # Set externally after construction by the loader.
+        self.spatial_meta = None
+        # RAS resample (tier 2 of NIfTI orientation feature).
+        # original_volume holds the canonical-reoriented array; resampled_volume
+        # caches the RAS-resampled volume after first computation. active_volume
+        # is None when the original is in use.
+        self.original_volume = None
+        self.resampled_volume = None
+        self.ras_resample_active = False
+
     def reset_caches(self):
-        """Clear all three render caches and reset their byte counters to 0."""
+        """Clear all three render caches and reset their byte counters to 0.
+
+        Does NOT touch the RAS-resample toggle — that's independent state,
+        managed exclusively by the /resample_ras endpoint.
+        """
         self.raw_cache.clear()
         self.rgba_cache.clear()
         self.mosaic_cache.clear()

{arrayview-0.11.0 → arrayview-0.12.0}/src/arrayview/_shell.html

@@ -130,8 +130,6 @@
             if (e.data.phase === 'tab-cycle') cycleTab(e.data.detail?.dir ?? 1);
         });
 
-        const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
-        let ws = new WebSocket(`${proto}//${location.host}/ws/shell`);
         // Mark this window as the native shell so embedded viewer iframes
         // can distinguish themselves from Jupyter embeds and enable the picker.
         window.__arrayviewShell = true;
@@ -141,14 +139,34 @@
         // the web content area already starts below the native title bar and
         // window.innerHeight reflects the usable height.  No padding needed.
 
-        ws.onmessage = (e) => {
-            const msg = JSON.parse(e.data);
-            if (msg.action === 'new_tab') {
-                // Close the welcome placeholder tab when a real array arrives
-                if (tabs['__welcome__']) closeTab('__welcome__');
-                addTab(msg.sid, msg.name, msg.url);
-            }
-        };
+        // Shell WebSocket with keepalive + auto-reconnect.
+        // macOS WebKit (pywebview) drops idle WebSocket connections after ~30-60s.
+        // Without this, tab injection via _notify_shells() fails on the second
+        // `arrayview` CLI call because SHELL_SOCKETS is empty on the server.
+        const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+        let ws = null;
+        let heartbeatId = null;
+        function connectShellWS() {
+            ws = new WebSocket(`${proto}//${location.host}/ws/shell`);
+            ws.onopen = () => {
+                clearInterval(heartbeatId);
+                heartbeatId = setInterval(() => {
+                    if (ws.readyState === WebSocket.OPEN) ws.send('{"action":"ping"}');
+                }, 15000);
+            };
+            ws.onmessage = (e) => {
+                const msg = JSON.parse(e.data);
+                if (msg.action === 'new_tab') {
+                    if (tabs['__welcome__']) closeTab('__welcome__');
+                    addTab(msg.sid, msg.name, msg.url);
+                }
+            };
+            ws.onclose = () => {
+                clearInterval(heartbeatId);
+                setTimeout(connectShellWS, 1000);
+            };
+        }
+        connectShellWS();
 
         const params = new URLSearchParams(window.location.search);
         const initSid = params.get('init_sid');

{arrayview-0.11.0 → arrayview-0.12.0}/src/arrayview/_stdio_server.py

@@ -22,7 +22,7 @@ import uuid
 
 import numpy as np
 
-from arrayview._io import load_data
+from arrayview._io import load_data, load_data_with_meta
 from arrayview._render import (
     _composite_overlay_mask,
     _extract_overlay_mask,
@@ -236,8 +236,11 @@ def _handle_register(msg: dict) -> None:
     name = msg.get("name") or __import__("os").path.basename(file_path)
     options = msg.get("options", {})
 
-    data = load_data(file_path)
+    data, spatial_meta = load_data_with_meta(file_path)
     session = Session(data=data, filepath=file_path, name=name)
+    session.spatial_meta = spatial_meta
+    if spatial_meta is not None:
+        session.original_volume = data
 
     if options.get("rgb"):
         _setup_rgb(session)