arrayview 0.23.0__tar.gz → 0.25.0__tar.gz

{arrayview-0.23.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.23.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-05
+last_updated: 2026-06-05
 ---
 
 # Architecture
@@ -63,6 +65,18 @@ pywebview, or system browser).
 - **`_stdio_server.py`** — Alternative to FastAPI for VS Code tunnel (direct webview): JSON on stdin, length-prefixed binary on stdout.
 - **`_viewer.html`** — The entire frontend (~24 100 lines). CSS + JS in one file, no build step. Canvas-based rendering, WebSocket binary protocol, all viewing modes, reconcilers, command registry. See `context/frontend.md`.
 
+## Frontend Tool Lifecycle
+
+Tool launch, tool activation, and drawer visibility are separate states.
+
+- Selecting an actionable tool activates it immediately and opens the right drawer.
+- Closing the right drawer hides controls only; it does not deactivate the active tool.
+- Re-selecting an active tool reopens its drawer when hidden, or hides the drawer when already visible.
+- `Esc` targets visible UI first: drawer, launcher, picker, or help before exiting active tools.
+- Passive tools such as Save open a drawer without entering a mode.
+- Overlay and vector tools show their rendered layer immediately when selected and available.
+- Existing tool output persists after mode exit unless the tool has an explicit destructive action.
+
 ## Display Routing
 
 | Environment | Default display | Server mode |

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.23.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.23.0 → arrayview-0.25.0}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.23.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.23.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.23.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.23.0 → arrayview-0.25.0}/src/arrayview/_launcher.py

@@ -156,6 +156,7 @@ def _vprint(*args, **kwargs) -> None:
 # ── Subprocess GUI Launcher ───────────────────────────────────────
 
 _ICON_PNG_PATH: str | None = None
+_LOOPBACK_HOST = "localhost"
 
 
 def _get_icon_png_path() -> str | None:
@@ -177,6 +178,57 @@ def _get_icon_png_path() -> str | None:
     return _ICON_PNG_PATH or None
 
 
+def _build_inline_shell_html(url: str, shell_port: int) -> str | None:
+    """Return embedded shell HTML for a cold-start native window."""
+    try:
+        shell_html = _pkg_files("arrayview").joinpath("_shell.html").read_text(
+            encoding="utf-8"
+        )
+        parsed = urllib.parse.urlparse(url)
+        inline_query = parsed.query
+        shell_html = shell_html.replace(
+            "</head>",
+            f"<script>"
+            f"window.__av_inline=true;"
+            f"window.__av_inlineQuery={inline_query!r};"
+            f"</script>\n"
+            f'<base href="http://{_LOOPBACK_HOST}:{shell_port}/">\n'
+            f"</head>",
+            1,
+        )
+        # Fix WebSocket URL — location.host is "" in inline html= mode
+        shell_html = shell_html.replace(
+            "`${proto}//${location.host}/ws/shell`",
+            f"`ws://{_LOOPBACK_HOST}:{shell_port}/ws/shell`",
+        )
+        return shell_html
+    except Exception:
+        return None
+
+
+def _make_loopback_socket(port: int) -> "socket.socket":
+    """Bind a TCP listener on the same loopback host the viewer URLs use."""
+    for family, socktype, proto, _, sockaddr in socket.getaddrinfo(
+        _LOOPBACK_HOST,
+        port,
+        type=socket.SOCK_STREAM,
+    ):
+        sock = None
+        try:
+            sock = socket.socket(family, socktype, proto)
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            sock.bind(sockaddr)
+            sock.listen(128)
+            sock.set_inheritable(True)
+            return sock
+        except OSError:
+            try:
+                sock.close()
+            except Exception:
+                pass
+    raise OSError(f"Could not bind {_LOOPBACK_HOST}:{port}")
+
+
 def _open_webview(
     url: str,
     win_w: int,
@@ -199,25 +251,9 @@ def _open_webview(
     inline_html_b64 = None
 
     if shell_port is not None:
-        try:
-            from importlib.resources import files as _pkg_files
-            shell_html = _pkg_files("arrayview").joinpath("_shell.html").read_text(encoding="utf-8")
-            # Inject inline-mode flag and hardcoded host (location.host is empty in html= mode)
-            shell_html = shell_html.replace(
-                "</head>",
-                f'<script>window.__av_inline=true;</script>\n'
-                f'<base href="http://localhost:{shell_port}/">\n'
-                f"</head>",
-                1,
-            )
-            # Fix WebSocket URL — location.host is "" in inline html= mode
-            shell_html = shell_html.replace(
-                "`${proto}//${location.host}/ws/shell`",
-                f"`ws://localhost:{shell_port}/ws/shell`",
-            )
+        shell_html = _build_inline_shell_html(url, shell_port)
+        if shell_html is not None:
             inline_html_b64 = _b64.b64encode(shell_html.encode()).decode()
-        except Exception:
-            pass  # fall back to URL mode
 
     if inline_html_b64:
         script_lines = [
@@ -469,7 +505,7 @@ def _open_webview_cli(
 
 def _server_alive(port: int, timeout: float = 0.5) -> bool:
     """Return True only if an ArrayView server is responding on the port."""
-    url = f"http://127.0.0.1:{port}/ping"
+    url = f"http://{_LOOPBACK_HOST}:{port}/ping"
     try:
         with urllib.request.urlopen(url, timeout=timeout) as resp:
             if resp.status != 200:
@@ -482,7 +518,7 @@ def _server_alive(port: int, timeout: float = 0.5) -> bool:
 
 def _server_pid(port: int) -> int | None:
     """Return the pid of the responding ArrayView server, or None if unreachable."""
-    url = f"http://127.0.0.1:{port}/ping"
+    url = f"http://{_LOOPBACK_HOST}:{port}/ping"
     try:
         with urllib.request.urlopen(url, timeout=0.5) as resp:
             if resp.status != 200:
@@ -497,7 +533,7 @@ def _server_pid(port: int) -> int | None:
 
 def _server_hostname(port: int, timeout: float = 0.5) -> str | None:
     """Return the hostname reported by the ArrayView server on ``port``, or None."""
-    url = f"http://127.0.0.1:{port}/ping"
+    url = f"http://{_LOOPBACK_HOST}:{port}/ping"
     try:
         with urllib.request.urlopen(url, timeout=timeout) as resp:
             if resp.status != 200:
@@ -515,7 +551,7 @@ def _relay_array_to_server(
     port: int,
     name: str,
     rgb: bool = False,
-    relay_host: str = "127.0.0.1",
+    relay_host: str = _LOOPBACK_HOST,
 ) -> None:
     """Load *filepath* locally and POST the bytes to an ArrayView relay server.
 
@@ -523,7 +559,7 @@ def _relay_array_to_server(
     ArrayView server (e.g. tunnel-remote).  The relay server registers the
     session and writes its own VS Code signal file so a viewer tab opens there.
 
-    ``relay_host`` defaults to 127.0.0.1; only change it when the relay server
+    ``relay_host`` defaults to localhost; only change it when the relay server
     is genuinely on a different network interface (rare).
     """
     import base64
@@ -567,7 +603,7 @@ type _CompareSids = list[str] | tuple[str, ...]
 
 def _server_json_request(port: int, path: str, payload: dict) -> dict:
     req = urllib.request.Request(
-        f"http://127.0.0.1:{port}{path}",
+        f"http://{_LOOPBACK_HOST}:{port}{path}",
         data=json.dumps(payload).encode(),
         headers={"Content-Type": "application/json"},
         method="POST",
@@ -948,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
@@ -1002,7 +1044,7 @@ def _handle_cli_spawned_daemon(
         window_mode=window_mode,
         floating=floating,
         is_remote=is_remote,
-        webview_already_opened=early_webview_notified,
+        webview_already_opened=early_webview_opened,
     )
 
 
@@ -1170,7 +1212,7 @@ def _promote_view_to_vscode_terminal(
 
 def _port_in_use(port: int) -> bool:
     try:
-        with socket.create_connection(("127.0.0.1", port), timeout=0.3):
+        with socket.create_connection((_LOOPBACK_HOST, port), timeout=0.3):
             return True
     except OSError:
         return False
@@ -1311,25 +1353,17 @@ async def _serve_background(port: int, stop_when_closed: bool = False):
     _loading_port = None  # reset for this server lifetime
     _session_mod.SERVER_LOOP = asyncio.get_running_loop()
     _session_mod.SERVER_PORT = port
-    import socket as _socket
-
-    # Pre-create the socket with SO_REUSEADDR so we can rebind immediately after
-    # a previous server on this port was killed (avoids TIME_WAIT Errno 48).
-    sock = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
-    sock.setsockopt(_socket.SOL_SOCKET, _socket.SO_REUSEADDR, 1)
-    sock.bind(("127.0.0.1", port))
-    sock.listen(128)
-    sock.set_inheritable(True)
+    # Bind on the same loopback hostname the viewer URLs use. On macOS,
+    # localhost often resolves to ::1 first, so binding only 127.0.0.1 can
+    # leave the native shell stuck on its loading overlay forever.
+    sock = _make_loopback_socket(port)
 
     # Bind the loading-page server on an OS-chosen ephemeral port.
     # This uses only stdlib so it starts in microseconds — well before
     # uvicorn's heavy imports finish.  _loading_port is read by the main
     # thread after _server_ready_event fires.
     try:
-        _lsock = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
-        _lsock.setsockopt(_socket.SOL_SOCKET, _socket.SO_REUSEADDR, 1)
-        _lsock.bind(("127.0.0.1", 0))
-        _lsock.listen(16)
+        _lsock = _make_loopback_socket(0)
         _loading_port = _lsock.getsockname()[1]
         threading.Thread(
             target=_run_loading_server, args=(_lsock,), daemon=True
@@ -1361,7 +1395,7 @@ def _with_loading(url: str) -> str:
     """
     if _loading_port is not None:
         encoded = urllib.parse.quote(url, safe="")
-        return f"http://127.0.0.1:{_loading_port}/?target={encoded}"
+        return f"http://{_LOOPBACK_HOST}:{_loading_port}/?target={encoded}"
     return url
 
 
@@ -1615,7 +1649,7 @@ class ViewHandle(str):
         _np.save(buf, arr)
         body = buf.getvalue()
         request = _req.Request(
-            f"http://127.0.0.1:{self._port}/update/{self._sid}",
+            f"http://{_LOOPBACK_HOST}:{self._port}/update/{self._sid}",
             data=body,
             method="POST",
         )
@@ -1625,7 +1659,7 @@ class ViewHandle(str):
         except Exception as e:
             raise RuntimeError(
                 f"[ArrayView] Failed to update viewer: {e}\n"
-                f"  URL: http://127.0.0.1:{self._port}/update/{self._sid}\n"
+                f"  URL: http://{_LOOPBACK_HOST}:{self._port}/update/{self._sid}\n"
                 f"  Is the ArrayView server still running?"
             ) from e
 
@@ -2254,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)
@@ -2295,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)
@@ -2507,7 +2550,7 @@ def _serve_empty(port: int) -> None:
     threading.Thread(
         target=lambda: _uvicorn().run(
             _server_mod().app,
-            host="127.0.0.1",
+            host=_LOOPBACK_HOST,
             port=port,
             log_level="error",
             timeout_keep_alive=30,
@@ -2548,13 +2591,7 @@ def _serve_daemon(
     _session_mod.PENDING_SESSION_EVENTS[sid] = _pending_event
     _session_mod.SERVER_PORT = port
 
-    import socket as _socket
-
-    sock = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
-    sock.setsockopt(_socket.SOL_SOCKET, _socket.SO_REUSEADDR, 1)
-    sock.bind(("127.0.0.1", port))
-    sock.listen(128)
-    sock.set_inheritable(True)
+    sock = _make_loopback_socket(port)
 
     def _run_uvicorn_on_socket():
         config = _uvicorn().Config(
@@ -2581,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)
@@ -2595,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:
@@ -2741,7 +2778,7 @@ def _start_watch_thread(filepath: str, sid: str, port: int) -> None:
                 last_mtime = mtime
                 try:
                     req = _urlreq.Request(
-                        f"http://127.0.0.1:{port}/reload/{sid}",
+                        f"http://{_LOOPBACK_HOST}:{port}/reload/{sid}",
                         data=b"",
                         method="POST",
                     )
@@ -3209,7 +3246,7 @@ def arrayview():
         if ":" in relay_str:
             relay_host, relay_port_str = relay_str.rsplit(":", 1)
         else:
-            relay_host, relay_port_str = "127.0.0.1", relay_str
+            relay_host, relay_port_str = _LOOPBACK_HOST, relay_str
         try:
             relay_port = int(relay_port_str)
         except ValueError: