arrayview 0.24.0__tar.gz → 0.25.0__tar.gz

{arrayview-0.24.0 → arrayview-0.25.0}/.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.0}/.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.0/.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.0}/.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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.24.0
+Version: 0.25.0
 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.0/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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.24.0"
+version = "0.25.0"
 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.0}/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.0}/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:
+                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:
+                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(

{arrayview-0.24.0 → arrayview-0.25.0}/src/arrayview/_launcher.py

@@ -984,7 +984,13 @@ def _handle_cli_spawned_daemon(
         f" rgb={rgb},"
         f")"
     )
-    subprocess.Popen([sys.executable, "-c", script])
+    subprocess.Popen(
+        [sys.executable, "-c", script],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        close_fds=True,
+    )
 
     early_webview_opened = False
     early_webview_notified = False
@@ -2282,13 +2288,18 @@ async def _stop_server_when_viewer_closes(
     Used in script mode so the non-daemon server thread exits cleanly when done."""
     import arrayview._session as _sm
 
+    connections_before = _sm.VIEWER_CONNECTIONS_SEEN
     deadline = time.monotonic() + connect_timeout
-    while _sm.VIEWER_SOCKETS == 0:
+    while (
+        _sm.VIEWER_SOCKETS == 0
+        and _sm.VIEWER_CONNECTIONS_SEEN == connections_before
+    ):
         if time.monotonic() > deadline:
             server.should_exit = True  # no viewer connected; give up
             return
         await asyncio.sleep(0.2)
-    # At least one viewer connected — now wait for all to disconnect.
+    # At least one viewer connected, even if it already disconnected between
+    # polling ticks. Now wait for all viewer sockets to be closed.
     while True:
         while _sm.VIEWER_SOCKETS > 0:
             await asyncio.sleep(0.2)
@@ -2323,10 +2334,14 @@ def _wait_for_viewer_close(
     """
     import arrayview._session as _sm
 
+    connections_before = _sm.VIEWER_CONNECTIONS_SEEN
     connect_deadline = (
         None if connect_timeout is None else time.monotonic() + connect_timeout
     )
-    while _sm.VIEWER_SOCKETS == 0:
+    while (
+        _sm.VIEWER_SOCKETS == 0
+        and _sm.VIEWER_CONNECTIONS_SEEN == connections_before
+    ):
         if connect_deadline is not None and time.monotonic() >= connect_deadline:
             return
         time.sleep(0.2)
@@ -2603,7 +2618,7 @@ def _serve_daemon(
     threading.Thread(target=_warm_luts, daemon=True).start()
 
     def _load():
-        from arrayview._io import load_data, load_data_with_meta, list_npz_keys
+        from arrayview._io import load_data, load_data_with_meta, list_array_keys
 
         try:
             data, spatial_meta = load_data_with_meta(filepath)
@@ -2617,13 +2632,13 @@ def _serve_daemon(
             )
             session.sid = sid
             session.spatial_meta = spatial_meta
-            # Multi-array .npz: store keys so the viewer can show a picker
-            if filepath.endswith(".npz") and not cleanup:
+            # Multi-array .npz/.mat: store keys so the viewer can show a picker
+            if (filepath.endswith(".npz") or filepath.endswith(".mat")) and not cleanup:
                 try:
-                    keys = list_npz_keys(filepath)
+                    keys = list_array_keys(filepath)
                     if len(keys) > 1:
-                        session.npz_keys = keys
-                        session.npz_filepath = filepath
+                        session.array_keys = keys
+                        session.array_filepath = filepath
                 except Exception:
                     pass
             if spatial_meta is not None:

arrayview-0.25.0/src/arrayview/_lifecycle.py

@@ -0,0 +1,39 @@
+"""Session lifecycle helpers shared by REST and WebSocket close paths."""
+
+from __future__ import annotations
+
+from arrayview._session import PENDING_SESSION_EVENTS, PENDING_SESSIONS, SESSIONS
+
+
+def release_session(sid: str) -> bool:
+    """Drop a loaded or pending session and release its cached array memory."""
+    PENDING_SESSIONS.discard(sid)
+    event = PENDING_SESSION_EVENTS.pop(sid, None)
+    if event is not None:
+        try:
+            event.set()
+        except Exception:
+            pass
+
+    session = SESSIONS.pop(sid, None)
+    if session is None:
+        return False
+
+    try:
+        session.reset_caches()
+    except Exception:
+        pass
+    try:
+        session.data = None
+    except Exception:
+        pass
+
+    try:
+        from arrayview._routes_persistence import _CROP_LOCK, _CROP_STATE
+
+        with _CROP_LOCK:
+            _CROP_STATE.pop(sid, None)
+    except Exception:
+        pass
+
+    return True

{arrayview-0.24.0 → arrayview-0.25.0}/src/arrayview/_routes_loading.py

@@ -3,10 +3,11 @@ import io
 import os
 
 import numpy as np
-from fastapi import File, HTTPException, Request, UploadFile
+from fastapi import File, Form, HTTPException, Request, UploadFile
 from fastapi.responses import JSONResponse
 
 from arrayview._io import _SUPPORTED_EXTS, _peek_file_shape, load_data
+from arrayview._lifecycle import release_session
 from arrayview._session import SESSIONS, Session
 
 
@@ -112,16 +113,16 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
                 except ImportError:
                     pass
         try:
-            from ._io import load_data_with_meta, list_npz_keys
+            from ._io import load_data_with_meta, list_array_keys
 
-            # Multi-array .npz: if no key provided, return the key list so the
-            # client can show a picker instead of blocking on terminal input.
+            # Multi-array .npz/.mat: if no key provided, return the key list so
+            # the client can show a picker instead of blocking on terminal input.
             _key = body.get("key")
-            _npz_keys = None
-            if filepath.endswith(".npz"):
-                _npz_keys = await asyncio.to_thread(list_npz_keys, filepath)
-                if len(_npz_keys) > 1 and not _key:
-                    return {"npz_keys": _npz_keys, "filepath": filepath}
+            _array_keys = None
+            if filepath.endswith(".npz") or filepath.endswith(".mat"):
+                _array_keys = await asyncio.to_thread(list_array_keys, filepath)
+                if len(_array_keys) > 1 and not _key:
+                    return {"array_keys": _array_keys, "filepath": filepath}
 
             data, spatial_meta = await asyncio.to_thread(load_data_with_meta, filepath, key=_key)
         except Exception as e:
@@ -130,9 +131,9 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
         if spatial_meta is not None:
             session.spatial_meta = spatial_meta
             session.original_volume = data
-        if _npz_keys and len(_npz_keys) > 1:
-            session.npz_keys = _npz_keys
-            session.npz_filepath = filepath
+        if _array_keys and len(_array_keys) > 1:
+            session.array_keys = _array_keys
+            session.array_filepath = filepath
         if body.get("rgb"):
             try:
                 await asyncio.to_thread(setup_rgb, session)
@@ -169,22 +170,27 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
         )
         return {"sid": session.sid, "name": name, "notified": notified}
 
-    @app.post("/session/{sid}/reload-npz")
-    async def reload_npz_key(sid: str, request: Request):
-        """Reload a session's data from an .npz file with a different key."""
+    @app.post("/release/{sid}")
+    def release_viewer_session(sid: str):
+        """Release a session when its owning viewer tab/window closes."""
+        return {"sid": sid, "released": release_session(sid)}
+
+    @app.post("/session/{sid}/reload-key")
+    async def reload_array_key(sid: str, request: Request):
+        """Reload a session's data from a multi-array file with a different key."""
         session = SESSIONS.get(sid)
         if session is None:
             raise HTTPException(status_code=404, detail="Session not found")
-        npz_filepath = getattr(session, "npz_filepath", None)
-        if not npz_filepath:
-            raise HTTPException(status_code=400, detail="Session is not an npz")
+        array_filepath = getattr(session, "array_filepath", None)
+        if not array_filepath:
+            raise HTTPException(status_code=400, detail="Session has no array keys")
         body = await request.json()
         key = body.get("key")
         if not key:
             raise HTTPException(status_code=400, detail="key is required")
         try:
             from ._io import load_data
-            data = await asyncio.to_thread(load_data, npz_filepath, key=key)
+            data = await asyncio.to_thread(load_data, array_filepath, key=key)
         except Exception as e:
             return {"error": str(e)}
         session.data = data
@@ -197,7 +203,7 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
         session._rgba_bytes = 0
         session._mosaic_bytes = 0
         session._estimated_mem = session._estimate_memory()
-        # Keep npz_keys so the user can switch again, but don't auto-prompt
+        # Keep array_keys so the user can switch again, but don't auto-prompt
         return {"ok": True}
 
     @app.get("/fs/list")
@@ -278,7 +284,10 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
         return {"cwd": target, "parent": parent, "home": home, "entries": entries}
 
     @app.post("/load-upload")
-    async def load_upload(file: UploadFile = File(...)):
+    async def load_upload(
+        file: UploadFile = File(...),
+        key: str | None = Form(None),
+    ):
         """Accept a drag-and-dropped .npy or .mat file and create a new session."""
         import tempfile
 
@@ -294,16 +303,25 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
             tmp.write(contents)
             tmp_path = tmp.name
 
+        _returned_keys = False
         try:
-            data = await asyncio.to_thread(load_data, tmp_path)
+            from ._io import list_array_keys
+
+            if ext == ".mat" and not key:
+                array_keys = await asyncio.to_thread(list_array_keys, tmp_path)
+                if len(array_keys) > 1:
+                    _returned_keys = True
+                    return {"array_keys": array_keys}
+            data = await asyncio.to_thread(load_data, tmp_path, key=key)
         except Exception as e:
             os.unlink(tmp_path)
             raise HTTPException(status_code=400, detail=str(e))
         finally:
-            try:
-                os.unlink(tmp_path)
-            except OSError:
-                pass
+            if not _returned_keys:
+                try:
+                    os.unlink(tmp_path)
+                except OSError:
+                    pass
 
         session = await asyncio.to_thread(Session, data, name=filename)
         SESSIONS[session.sid] = session

{arrayview-0.24.0 → arrayview-0.25.0}/src/arrayview/_routes_websocket.py

@@ -7,6 +7,7 @@ from starlette.websockets import WebSocketDisconnect
 
 import arrayview._session as _session_mod
 from arrayview._analysis import _build_metadata
+from arrayview._lifecycle import release_session
 from arrayview._overlays import _composite_overlays
 from arrayview._render import (
     LUTS,
@@ -80,14 +81,8 @@ def register_websocket_routes(app) -> None:
                 msg = await ws.receive_json()
                 if msg.get("action") == "close":
                     sid = msg.get("sid")
-                    if sid in SESSIONS:
-                        SESSIONS[sid].reset_caches()
-                        SESSIONS[sid].data = None
-                        del SESSIONS[sid]
-                        from arrayview._routes_persistence import _CROP_LOCK, _CROP_STATE
-
-                        with _CROP_LOCK:
-                            _CROP_STATE.pop(sid, None)
+                    if sid:
+                        release_session(sid)
         except Exception:
             pass
         finally:
@@ -110,6 +105,10 @@ def register_websocket_routes(app) -> None:
             pass
 
         _session_mod.VIEWER_SOCKETS += 1
+        _session_mod.VIEWER_CONNECTIONS_SEEN += 1
+        _session_mod.VIEWER_SID_COUNTS[sid] = (
+            _session_mod.VIEWER_SID_COUNTS.get(sid, 0) + 1
+        )
         _session_mod.VIEWER_SIDS.add(sid)
         loop = asyncio.get_running_loop()
         _pending: asyncio.Queue[dict | None] = asyncio.Queue()
@@ -402,3 +401,9 @@ def register_websocket_routes(app) -> None:
             except asyncio.CancelledError:
                 pass
             _session_mod.VIEWER_SOCKETS = max(0, _session_mod.VIEWER_SOCKETS - 1)
+            sid_count = max(0, _session_mod.VIEWER_SID_COUNTS.get(sid, 0) - 1)
+            if sid_count:
+                _session_mod.VIEWER_SID_COUNTS[sid] = sid_count
+            else:
+                _session_mod.VIEWER_SID_COUNTS.pop(sid, None)
+                _session_mod.VIEWER_SIDS.discard(sid)

{arrayview-0.24.0 → arrayview-0.25.0}/src/arrayview/_session.py

@@ -28,6 +28,8 @@ SERVER_LOOP = None
 SERVER_PORT: int | None = None  # actual port the uvicorn server is bound to
 VIEWER_SOCKETS = 0  # count of active viewer WebSocket connections
 VIEWER_SIDS: set = set()  # session IDs with at least one active viewer WS
+VIEWER_SID_COUNTS: dict[str, int] = {}  # active viewer WS count per session ID
+VIEWER_CONNECTIONS_SEEN = 0  # monotonic count of accepted viewer WS connections
 SHELL_SOCKETS = []  # webview shell WS connections (for tab injection)
 _window_process = None
 PENDING_SESSIONS: set = set()  # sids whose data is still loading in a background thread
@@ -446,6 +448,7 @@ __all__ = [
     "SERVER_LOOP",
     "VIEWER_SOCKETS",
     "VIEWER_SIDS",
+    "VIEWER_CONNECTIONS_SEEN",
     "SHELL_SOCKETS",
     "_window_process",
     "PENDING_SESSIONS",