arrayview 0.24.0__tar.gz → 0.25.1__tar.gz

{arrayview-0.24.0 → arrayview-0.25.1}/.mex/ROUTER.md

@@ -6,6 +6,8 @@ edges:
     condition: when the task depends on what is currently shipped, in progress, or recently changed
   - target: context/architecture.md
     condition: when working on system design, integrations, or understanding how components connect
+  - target: context/lifecycle.md
+    condition: when working on server startup, shutdown, display ownership, VS Code tabs, orphan processes, or session release
   - target: context/stack.md
     condition: when working with specific technologies, libraries, or making tech decisions
   - target: context/conventions.md
@@ -22,7 +24,7 @@ edges:
     condition: when starting a task — check the pattern index for a matching pattern file
   - target: ../DESIGN.md
     condition: when the task touches design philosophy — new features, UI changes, mode additions, or interaction model decisions
-last_updated: 2026-05-16
+last_updated: 2026-06-05
 ---
 
 # arrayview — Router
@@ -81,6 +83,7 @@ Load `context/project-state.md` only when you need active-workstream or recent-s
 |-----------|------|
 | Checking current shipped / in-progress status | `context/project-state.md` |
 | Understanding system architecture | `context/architecture.md` |
+| Startup/shutdown/display ownership lifecycle | `context/lifecycle.md` |
 | Working with a specific technology | `context/stack.md` |
 | Writing or reviewing code | `context/conventions.md` |
 | Making a design decision | `context/decisions.md` |

{arrayview-0.24.0 → arrayview-0.25.1}/.mex/context/architecture.md

@@ -14,11 +14,13 @@ edges:
     condition: when specific technology details are needed
   - target: context/decisions.md
     condition: when understanding why the architecture is structured this way
+  - target: context/lifecycle.md
+    condition: when ownership, startup, teardown, or display routing lifecycle matters
   - target: context/frontend.md
     condition: when the task involves _viewer.html, modes, reconcilers, or the View Component System
   - target: context/render-pipeline.md
     condition: when the task involves slice extraction, colormaps, caching, or the render thread
-last_updated: 2026-05-26
+last_updated: 2026-06-05
 ---
 
 # Architecture

arrayview-0.25.1/.mex/context/lifecycle.md

@@ -0,0 +1,92 @@
+---
+name: lifecycle
+description: Ownership contract for ArrayView backends, viewer sessions, VS Code tabs, and shutdown/release behavior.
+triggers:
+  - "lifecycle"
+  - "server ownership"
+  - "startup"
+  - "shutdown"
+  - "orphan process"
+  - "VS Code tab"
+  - "backend unavailable"
+  - "Jupyter iframe"
+  - "SSH"
+edges:
+  - target: context/architecture.md
+    condition: when component boundaries or display routing need broader context
+  - target: context/stack.md
+    condition: when VS Code, FastAPI, WebSocket, or packaging details are needed
+last_updated: 2026-06-05
+---
+
+# Lifecycle
+
+This contract describes who owns the backend, when it starts, and what closes it.
+
+## Ownership Matrix
+
+| Invocation | Display owner | Backend model | Shutdown/release |
+|---|---|---|---|
+| Local VS Code CLI `arrayview file.npy` | VS Code URL webview panel | Shared transient daemon | Panel close releases URL sessions; last viewer WebSocket close stops daemon |
+| VS Code file click/custom editor | VS Code extension | Extension-owned stdio subprocess | Panel close kills subprocess |
+| Plain Python script `view(arr)` | Browser/native/VS Code display | Non-daemon background server thread | Survives caller until viewer connects then closes |
+| Jupyter `view(arr)` | Notebook kernel inline iframe | Kernel-owned daemon server thread | Iframe disappearance must not hard-kill backend |
+| Julia/PythonCall | Browser/VS Code route from subprocess | Detached subprocess | Never in-process; avoid GIL deadlock |
+| Remote/tunnel | VS Code direct webview when possible | stdio direct webview or intentional persistent server | Persistence allowed only when transport requires it |
+| Plain SSH | User-forwarded localhost URL | Transient server unless `--serve` requested | Viewer close ends transient session |
+
+## Local VS Code CLI
+
+- `arrayview file.npy` from a local VS Code terminal should return to the prompt.
+- Multiple local CLI launches may share one backend and open separate tabs.
+- Closing one tab releases only that tab's arrays/sessions.
+- Closing the last viewer tab should stop the transient daemon.
+- The VS Code wrapper must not show "backend unavailable" based on a webview-side `fetch()`; backend health checks belong in the extension host.
+
+## VS Code File Click And Custom Editor
+
+- Prefer direct extension-owned stdio subprocesses.
+- Do not require localhost or a shared port when direct mode is available.
+- Closing the tab should terminate the subprocess.
+- This path is transient and owned by the extension session, not by a long-lived server.
+
+## Python Script
+
+- `view(arr)` from a script should survive the script exiting.
+- The backend must outlive the caller until viewer instances close.
+- When the last viewer instance closes, free arrays and shut the backend down.
+- Quick viewer connect/disconnect races must count as "a viewer connected" so transient waiters do not linger until connect timeout.
+
+## Jupyter
+
+- Jupyter keeps the backend kernel-owned.
+- An iframe disappearing should not hard-kill the backend.
+- Explicit close or cleanup should free the session.
+- Repeated `view()` calls should reuse the kernel-owned server when appropriate.
+
+## Remote, Tunnel, And SSH
+
+- Remote or tunnel launches may persist when `--serve` or direct-server constraints require it.
+- Direct VS Code tunnel display should prefer stdio direct webview to avoid forwarded-port auth and public-port setup.
+- With multiple registered tunnel windows, a missing or stale `ARRAYVIEW_WINDOW_ID` must fail closed with a diagnostic rather than broadcasting to whichever window is focused.
+- An exact registered `ARRAYVIEW_WINDOW_ID` wins; do not redirect it to a newer same-parent registration because live tunnel windows can share ancestry.
+- Plain SSH should use `localhost` forwarding guidance and stay transient unless a shared server was explicitly requested.
+
+## Shared Rules
+
+- Global lifecycle state lives in `_session.py`.
+- `release_session()` is the session-release primitive.
+- Viewer WebSocket connect/disconnect owns active viewer counts.
+- URL panel disposal must release every SID encoded in the URL: `sid`, `compare_sid`, `compare_sids`, and `overlay_sid`.
+- Tunnel registration cleanup must not remove live same-tunnel sibling windows.
+- Explicit cleanup wins over implicit disappearance.
+- Any VS Code extension source change must rebuild `src/arrayview/arrayview-opener.vsix` and keep the packaged version in sync.
+
+## Verification Anchors
+
+- `tests/lifecycle_matrix.py` is the top-level lifecycle gate; it reports automated, real-process, local-state, and manual-only checks separately.
+- `tests/test_lifecycle_contract.py` covers invocation ownership, release routes, transient daemon shutdown, and bundled VSIX lifecycle content.
+- `tests/test_cli.py` covers CLI launch behavior.
+- `tests/test_api.py` contains the affected WebSocket close and CLI helper coverage.
+- `vscode-extension/test_lifecycle_helpers.js` covers URL SID collection and backend ping URL parsing.
+- `vscode-extension/extension.js` must pass Node syntax checks after any extension change.

{arrayview-0.24.0 → arrayview-0.25.1}/.mex/context/project-state.md

@@ -40,6 +40,7 @@ last_updated: 2026-05-13
 
 ## Recently Completed
 
+- VS Code tab lifecycle hardening: local VS Code CLI launches now use transient daemon shutdown instead of `persist=True`, remote/tunnel launches remain persistent only where transport requires it, URL webview backend checks run in the extension host against `/ping`, URL panel disposal releases all sessions encoded in the viewer URL via tested lifecycle helpers, quick viewer connect/disconnect races are detected by a monotonic connection counter, ambiguous multi-window tunnel routing now fails closed instead of opening in a guessed window, stale viewer SID retry state is cleared on WebSocket disconnect, and the bundled opener extension was rebuilt as v0.14.12.
 - Shift+C colormap picker redesign: the old centered shortlist is now a narrow translucent right-edge drawer with a close button, a yellow `Colormaps` title plus a `Favorites` subtitle, and a plain 12-swatch two-column quick set that stays visible above the search field. Search matches render in a separate results area below the input, Enter first exits the search field before a second Enter commits, arrow-key movement follows the visible two-column grid, and repeated `c` presses cycle through the currently visible swatches while the picker is open.
 - Detached compare-on-X: single-array non-spatial dimensions now support the same compare-center family as two-array compare. The frontend reuses compare mode with per-pane detached indices, the dimbar shows a purple `X`, the compare titles show index-over-total labels, `[` / `]` control pane A, `{` / `}` control pane B, and repeated `X` exits detached compare after cycling the center modes. Focused coverage now includes a browser regression for detached entry/scrubbing/exit plus API coverage for split `/diff` indices on the same session.
 - Normal-mode dimbar readability: inactive non-spatial dims no longer get a blanket reduced parent opacity, so the current index reads bright while `/total` stays subdued via the existing child dim-size styling.

{arrayview-0.24.0 → arrayview-0.25.1}/PKG-INFO

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

arrayview-0.25.1/docs/lifecycle.md

@@ -0,0 +1,6 @@
+# Lifecycle
+
+The authoritative lifecycle contract lives in `.mex/context/lifecycle.md`.
+
+Use that file before changing server startup, shutdown, display routing, VS Code
+tab behavior, session release, or extension packaging.

{arrayview-0.24.0 → arrayview-0.25.1}/pyproject.toml

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

{arrayview-0.24.0 → arrayview-0.25.1}/src/arrayview/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.20.0"
+__version__ = "0.25.1"
 
 __all__ = [
     "TrainingMonitor",

{arrayview-0.24.0 → arrayview-0.25.1}/src/arrayview/_analysis.py

@@ -43,8 +43,8 @@ def _build_metadata(session) -> dict:
         meta["ras_resample_active"] = bool(
             getattr(session, "ras_resample_active", False)
         )
-    if getattr(session, "npz_keys", None):
-        meta["npz_keys"] = session.npz_keys
+    if getattr(session, "array_keys", None):
+        meta["array_keys"] = session.array_keys
     return meta
 
 
@@ -268,11 +268,16 @@ def _pixel_value(
     """Return a finite pixel value or None."""
     if session.rgb_axis is not None:
         return None
-    idx_tuple = (
-        tuple(int(v) for v in indices.split(","))
-        if isinstance(indices, str)
-        else tuple(indices)
-    )
+    if isinstance(indices, str):
+        parts = indices.split(",")
+        if not parts or any(v == "" for v in parts):
+            return None
+        try:
+            idx_tuple = tuple(int(v) for v in parts)
+        except ValueError:
+            return None
+    else:
+        idx_tuple = tuple(indices)
     raw = (
         qmri_display_slice(session, dim_x, dim_y, list(idx_tuple), qmri_role)
         if qmri_role

{arrayview-0.24.0 → arrayview-0.25.1}/src/arrayview/_io.py

@@ -53,10 +53,52 @@ def list_npz_keys(filepath):
     return keys
 
 
+def list_mat_keys(filepath):
+    """Return [{key, shape, dtype}] for each array in a .mat file.
+
+    Handles both scipy-loadable .mat files and v7.3 HDF5-based files.
+    Filters out metadata keys (starting with '_') and non-array entries.
+    """
+    try:
+        import scipy.io
+
+        mat = scipy.io.loadmat(filepath)
+        keys = []
+        for k, v in mat.items():
+            if k.startswith("_"):
+                continue
+            if isinstance(v, np.ndarray) and v.ndim >= 1 and v.dtype.kind in ("b", "i", "u", "f", "c"):
+                keys.append({"key": k, "shape": list(v.shape), "dtype": str(v.dtype)})
+        return keys
+    except NotImplementedError:
+        import h5py
+
+        f = h5py.File(filepath, "r")
+        keys = []
+        for k in f.keys():
+            ds = f[k]
+            if isinstance(ds, h5py.Dataset) and len(ds.shape) >= 1 and ds.dtype.kind in ("b", "i", "u", "f", "c"):
+                keys.append({"key": k, "shape": list(ds.shape), "dtype": str(ds.dtype)})
+        f.close()
+        return keys
+
+
+def list_array_keys(filepath):
+    """Return [{key, shape, dtype}] for each array in a multi-array file.
+
+    Dispatches by extension: .npz or .mat.
+    """
+    if filepath.endswith(".npz"):
+        return list_npz_keys(filepath)
+    if filepath.endswith(".mat"):
+        return list_mat_keys(filepath)
+    return []
+
+
 def _select_npz_array(npz, filepath):
     """Load the first array from a multi-array .npz file.
 
-    The in-viewer NPZ picker handles array selection — no terminal prompt.
+    The in-viewer array picker handles array selection — no terminal prompt.
     """
     keys = list(npz.keys())
     return npz[keys[0]]
@@ -193,11 +235,13 @@ def load_data(filepath, key=None):
                 for k, v in mat.items()
                 if not k.startswith("_") and isinstance(v, np.ndarray)
             }
+            if key is not None:
+                return _fix_mat_complex(arrays[key])
             if len(arrays) == 1:
                 return _fix_mat_complex(next(iter(arrays.values())))
             raise ValueError(
                 f".mat file contains multiple arrays: {list(arrays.keys())}. "
-                "Load it manually and pass the array to view()."
+                "Select one in the viewer or pass a key."
             )
         except NotImplementedError:
             # MATLAB v7.3 files use HDF5 — scipy cannot load them; fall back to h5py.
@@ -205,11 +249,13 @@ def load_data(filepath, key=None):
 
             f = h5py.File(filepath, "r")
             arrays = {k: f[k] for k in f.keys() if isinstance(f[k], h5py.Dataset)}
+            if key is not None:
+                return np.array(arrays[key])
             if len(arrays) == 1:
                 return np.array(next(iter(arrays.values())))
             raise ValueError(
                 f".mat (v7.3) file contains multiple datasets: {list(arrays.keys())}. "
-                "Load it manually with h5py and pass the array to view()."
+                "Select one in the viewer or pass a key."
             )
     else:
         raise ValueError(