arrayview 0.23.0__tar.gz → 0.24.0__tar.gz

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

@@ -18,7 +18,7 @@ edges:
     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-05-26
 ---
 
 # Architecture
@@ -63,6 +63,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.23.0 → arrayview-0.24.0}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.23.0"
+version = "0.24.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.24.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",
@@ -1002,7 +1038,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 +1206,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 +1347,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 +1389,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 +1643,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 +1653,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
 
@@ -2507,7 +2535,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 +2576,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(
@@ -2741,7 +2763,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 +3231,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:

{arrayview-0.23.0 → arrayview-0.24.0}/src/arrayview/_platform.py

@@ -6,6 +6,44 @@ import os
 import subprocess
 import sys
 
+
+def get_ppid(pid: int) -> int:
+    """Return parent PID of *pid*, or -1 if unavailable.
+
+    Cross-platform: /proc on Linux, ps on macOS, wmic on Windows.
+    """
+    if sys.platform == "win32":
+        try:
+            r = subprocess.run(
+                ["wmic", "process", "where", f"processid={pid}",
+                 "get", "parentprocessid"],
+                capture_output=True, text=True, timeout=5,
+            )
+            for line in r.stdout.strip().splitlines():
+                val = line.strip()
+                if val.isdigit():
+                    return int(val)
+        except Exception:
+            pass
+        return -1
+    try:
+        with open(f"/proc/{pid}/status") as fh:
+            for line in fh:
+                if line.startswith("PPid:"):
+                    return int(line.split()[1])
+    except Exception:
+        pass
+    try:
+        r = subprocess.run(
+            ["ps", "-p", str(pid), "-o", "ppid="],
+            capture_output=True, text=True, timeout=2,
+        )
+        return int(r.stdout.strip())
+    except Exception:
+        pass
+    return -1
+
+
 # ---------------------------------------------------------------------------
 # Jupyter
 # ---------------------------------------------------------------------------
@@ -58,26 +96,6 @@ def _in_matlab() -> bool:
         _MATLAB_CACHE = True
         return True
 
-    def _ppid(pid: int) -> int:
-        try:
-            with open(f"/proc/{pid}/status") as fh:
-                for line in fh:
-                    if line.startswith("PPid:"):
-                        return int(line.split()[1])
-        except Exception:
-            pass
-        try:
-            r = subprocess.run(
-                ["ps", "-p", str(pid), "-o", "ppid="],
-                capture_output=True,
-                text=True,
-                timeout=2,
-            )
-            return int(r.stdout.strip())
-        except Exception:
-            pass
-        return -1
-
     def _command_from_pid(pid: int) -> str:
         try:
             with open(f"/proc/{pid}/cmdline", "rb") as fh:
@@ -103,7 +121,7 @@ def _in_matlab() -> bool:
         if "matlab" in cmd:
             _MATLAB_CACHE = True
             return True
-        pid = _ppid(pid)
+        pid = get_ppid(pid)
         if pid <= 1:
             break
 
@@ -130,26 +148,6 @@ def _find_vscode_ipc_hook() -> str | None:
     if _VSCODE_IPC_HOOK_CACHE != "__unset__":
         return _VSCODE_IPC_HOOK_CACHE
 
-    def _ppid(pid: int) -> int:
-        try:
-            with open(f"/proc/{pid}/status") as fh:
-                for line in fh:
-                    if line.startswith("PPid:"):
-                        return int(line.split()[1])
-        except Exception:
-            pass
-        try:
-            r = subprocess.run(
-                ["ps", "-p", str(pid), "-o", "ppid="],
-                capture_output=True,
-                text=True,
-                timeout=2,
-            )
-            return int(r.stdout.strip())
-        except Exception:
-            pass
-        return -1
-
     def _ipc_from_pid(pid: int) -> str:
         # Linux: /proc/<pid>/environ (null-separated KEY=VALUE pairs)
         try:
@@ -184,7 +182,7 @@ def _find_vscode_ipc_hook() -> str | None:
     # Walk up to 12 ancestor processes
     pid = os.getpid()
     for _ in range(12):
-        pid = _ppid(pid)
+        pid = get_ppid(pid)
         if pid <= 1:
             break
         val = _ipc_from_pid(pid)

{arrayview-0.23.0 → arrayview-0.24.0}/src/arrayview/_routes_rendering.py

@@ -1,4 +1,5 @@
 import io
+import time
 
 import numpy as np
 from fastapi import Depends, Response
@@ -93,8 +94,11 @@ def register_rendering_routes(app, *, get_session_or_404) -> None:
         te: float | None = None,
         tr: float | None = None,
         ti: float | None = None,
+        perf: bool = False,
         session=Depends(get_session_or_404),
     ):
+        total_t0 = time.perf_counter()
+        render_t0 = total_t0
         idx_tuple = tuple(int(x) for x in indices.split(","))
         if synthetic_mri:
             try:
@@ -252,17 +256,40 @@ def register_rendering_routes(app, *, get_session_or_404) -> None:
                     vmin_override=vmin_override,
                     vmax_override=vmax_override,
                 )
+        render_ms = (time.perf_counter() - render_t0) * 1000.0
+        encode_t0 = time.perf_counter()
         img = _pil_image().fromarray(rgba[:, :, :3], mode="RGB")
         buf = io.BytesIO()
         img.save(buf, format="JPEG", quality=90)
+        payload = buf.getvalue()
+        encode_ms = (time.perf_counter() - encode_t0) * 1000.0
+        total_ms = (time.perf_counter() - total_t0) * 1000.0
+        headers = {
+            "Cache-Control": "max-age=300",
+            "X-ArrayView-Vmin": str(vmin),
+            "X-ArrayView-Vmax": str(vmax),
+        }
+        if perf:
+            payload_bytes = len(payload)
+            headers.update(
+                {
+                    "Server-Timing": (
+                        f"render;dur={render_ms:.3f}, "
+                        f"encode;dur={encode_ms:.3f}, total;dur={total_ms:.3f}"
+                    ),
+                    "X-ArrayView-Render-Ms": f"{render_ms:.3f}",
+                    "X-ArrayView-Encode-Ms": f"{encode_ms:.3f}",
+                    "X-ArrayView-Total-Ms": f"{total_ms:.3f}",
+                    "X-ArrayView-Payload-Bytes": str(payload_bytes),
+                    "X-ArrayView-Raw-Cache-Entries": str(len(session.raw_cache)),
+                    "X-ArrayView-RGBA-Cache-Entries": str(len(session.rgba_cache)),
+                    "X-ArrayView-Mosaic-Cache-Entries": str(len(session.mosaic_cache)),
+                }
+            )
         return Response(
-            content=buf.getvalue(),
+            content=payload,
             media_type="image/jpeg",
-            headers={
-                "Cache-Control": "max-age=300",
-                "X-ArrayView-Vmin": str(vmin),
-                "X-ArrayView-Vmax": str(vmax),
-            },
+            headers=headers,
         )
 
     @app.get("/diff/{sid_a}/{sid_b}")

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

@@ -1,4 +1,5 @@
 import asyncio
+import time
 
 import numpy as np
 from fastapi import WebSocket
@@ -159,6 +160,9 @@ def register_websocket_routes(app) -> None:
                 qmri_dim = int(msg.get("qmri_dim", -1))
                 qmri_role = str(msg.get("qmri_role", ""))
                 synthetic_mri = str(msg.get("synthetic_mri", ""))
+                perf = bool(msg.get("perf", False))
+                total_t0 = time.perf_counter()
+                render_t0 = total_t0
 
                 if synthetic_mri:
                     te = msg.get("te")
@@ -331,6 +335,8 @@ def register_websocket_routes(app) -> None:
                         (h, w),
                     )
 
+                render_ms = (time.perf_counter() - render_t0) * 1000.0
+                post_t0 = time.perf_counter()
                 header = np.array([seq, w, h], dtype=np.uint32).tobytes()
                 vminmax = np.array([vmin, vmax], dtype=np.float32).tobytes()
                 if canvas_w and canvas_h and (w > canvas_w or h > canvas_h):
@@ -362,6 +368,23 @@ def register_websocket_routes(app) -> None:
                         vf_scale = np.array([vf_result["scale"]], dtype=np.float32).tobytes()
                         payload += vf_hdr + vf_scale + arrows.tobytes()
                 await ws.send_bytes(payload)
+                if perf:
+                    total_ms = (time.perf_counter() - total_t0) * 1000.0
+                    await ws.send_json(
+                        {
+                            "type": "render_timing",
+                            "seq": seq,
+                            "total_ms": total_ms,
+                            "render_ms": render_ms,
+                            "post_ms": (time.perf_counter() - post_t0) * 1000.0,
+                            "payload_bytes": len(payload),
+                            "width": int(w),
+                            "height": int(h),
+                            "raw_cache_entries": len(session.raw_cache),
+                            "rgba_cache_entries": len(session.rgba_cache),
+                            "mosaic_cache_entries": len(session.mosaic_cache),
+                        }
+                    )
 
                 if slice_dim >= 0 and not (dim_z >= 0):
                     _schedule_prefetch(

{arrayview-0.23.0 → arrayview-0.24.0}/src/arrayview/_shell.html

@@ -243,26 +243,26 @@
         }
         connectShellWS();
 
-        if (!window.__av_inline) {
-            const params = new URLSearchParams(window.location.search);
-            const initSid = params.get('init_sid');
-            const initName = params.get('init_name');
-            const initCompareSid = params.get('init_compare_sid');
-            const initCompareSids = params.get('init_compare_sids');
-            if (initSid) {
-                let url = `/?sid=${initSid}`;
-                if (initCompareSid) url += `&compare_sid=${initCompareSid}&compare_sids=${initCompareSids}`;
-                addTab(initSid, initName || 'Array', url);
-            } else {
-                fetch('/sessions').then(r => r.json()).then(sessions => {
-                    if (sessions.length > 0) {
-                        sessions.forEach(s => addTab(s.sid, s.name));
-                    } else {
-                        // No arrays loaded yet — show the welcome/plasma screen
-                        addTab('__welcome__', '', '/');
-                    }
-                }).catch(() => { addTab('__welcome__', '', '/'); });
-            }
+        const initParams = new URLSearchParams(
+            window.__av_inline ? (window.__av_inlineQuery || '') : window.location.search
+        );
+        const initSid = initParams.get('init_sid');
+        const initName = initParams.get('init_name');
+        const initCompareSid = initParams.get('init_compare_sid');
+        const initCompareSids = initParams.get('init_compare_sids');
+        if (initSid) {
+            let url = `/?sid=${initSid}`;
+            if (initCompareSid) url += `&compare_sid=${initCompareSid}&compare_sids=${initCompareSids}`;
+            addTab(initSid, initName || 'Array', url);
+        } else if (!window.__av_inline) {
+            fetch('/sessions').then(r => r.json()).then(sessions => {
+                if (sessions.length > 0) {
+                    sessions.forEach(s => addTab(s.sid, s.name));
+                } else {
+                    // No arrays loaded yet — show the welcome/plasma screen
+                    addTab('__welcome__', '', '/');
+                }
+            }).catch(() => { addTab('__welcome__', '', '/'); });
         }
     </script>
 </body>