arrayview 0.40.0__tar.gz → 0.41.0__tar.gz

{arrayview-0.40.0 → arrayview-0.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.40.0
+Version: 0.41.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.40.0 → arrayview-0.41.0}/pyproject.toml

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

{arrayview-0.40.0 → arrayview-0.41.0}/src/arrayview/ARCHITECTURE.md

@@ -169,7 +169,7 @@ A refactoring in progress that introduces a View/Layer/Slicer/LayoutStrategy/Mod
 **Status:** Phases 1–15 complete. Phase 12 (keybind collapse) and Phase 17 (final cleanup) pending completion of render-pipeline migration from legacy globals to `displayState`.
 
 ### Command Registry
-All keybinds flow through a VS Code-style command registry in `_viewer.html`. Three tables: `commands` (id → `{title, when, run}`), `keybinds` (key+modifiers → command id), and `makeContext(state)` (mode/state flag bag). `dispatchCommand(e)` is wired as a prefix to the keydown handler; on a match it evaluates `when` against the context and runs the command, otherwise falls through. The help overlay is rendered at runtime from the `GUIDE_TABS` static data structure in `_viewer.html` — when adding or changing a keybind, update `GUIDE_TABS` manually. A `/`-triggered command palette fuzzy-searches all commands. Cross-mode enablement is guarded by `tests/test_command_reachability.py`.
+All keybinds flow through a VS Code-style command registry in `_viewer.html`. Three tables: `commands` (id → `{title, when, run}`), `keybinds` (key+modifiers → command id), and `makeContext(state)` (mode/state flag bag). `dispatchCommand(e)` is wired as a prefix to the keydown handler; on a match it evaluates `when` against the context and runs the command, otherwise falls through. The help overlay is rendered at runtime from the `GUIDE_TABS` static data structure in `_viewer.html` — when adding or changing a keybind, update `GUIDE_TABS` manually. A `/`-triggered command palette fuzzy-searches all commands.
 
 ### Reconcilers
 Functions in the "UI Validation and Reconciliation" section (~line 13666) that enforce consistent UI state. When mode changes happen, reconcilers update visibility of containers, colorbars, dynamic islands, and compare sub-mode UI. There are four:

{arrayview-0.40.0 → arrayview-0.41.0}/src/arrayview/_launch_plan.py

@@ -267,6 +267,8 @@ def _completion_target(
     if plan.display is Display.BROWSER:
         if _placement(evidence) is Placement.SSH:
             return CompletionTarget.GUIDANCE_PRINTED
+        if _placement(evidence) is Placement.VSCODE_REMOTE:
+            return CompletionTarget.FRAME_READY
         return CompletionTarget.DISPATCH_ACCEPTED
     if invocation in {Invocation.CLI, Invocation.VSCODE_EXPLORER}:
         return CompletionTarget.FRAME_READY
@@ -412,7 +414,9 @@ def plan_launch(
         window=None if remote_jupyter else window,
         inline=False if remote_jupyter else intent.inline,
         environment=environment,
-        native_available=facts.native_backend is not None, reasons=reasons,
+        native_available=facts.native_backend is not None,
+        in_vscode_tunnel=facts.in_vscode_tunnel,
+        reasons=reasons,
     )
     if display is Display.VSCODE and environment not in {
         Environment.VSCODE_LOCAL, Environment.VSCODE_REMOTE
@@ -436,6 +440,7 @@ def _display_policy(
     inline: bool | None,
     environment: Environment,
     native_available: bool,
+    in_vscode_tunnel: bool,
     reasons: list[str],
 ) -> tuple[Display, Display | None, bool]:
     if window == "none":
@@ -461,6 +466,9 @@ def _display_policy(
             return Display.VSCODE, None, False
         return Display.VSCODE, Display.BROWSER, True
     if window == "browser":
+        if environment is Environment.VSCODE_REMOTE and in_vscode_tunnel:
+            reasons.append("remote_external_browser")
+            return Display.BROWSER, None, False
         if environment is Environment.VSCODE_REMOTE:
             reasons.append("remote_browser_redirected_to_vscode")
             return Display.VSCODE, None, False

{arrayview-0.40.0 → arrayview-0.41.0}/src/arrayview/_launcher.py

@@ -1813,6 +1813,9 @@ def _handle_cli_existing_server(
             expected_server_id=expected_server_id,
             native_request_id=native_request_id,
         )
+        # Inside this try on purpose: the generated bundle is removed in the
+        # finally below, and these sessions read from it.
+        _register_tutorial_extras(port, expected_server_id)
     except Exception as e:
         err = str(e)
         stale_stack_server = (
@@ -2065,7 +2068,14 @@ def _handle_cli_spawned_daemon(
             and is_remote
         ) or (launch_context is None and not use_native_shell):
             _configure_vscode_port_preview(
-                port, in_vscode=not is_remote, is_remote=is_remote
+                port,
+                in_vscode=not is_remote,
+                is_remote=is_remote,
+                is_tunnel=(
+                    launch_context.evidence.in_vscode_tunnel
+                    if launch_context is not None
+                    else None
+                ),
             )
 
         daemon_connect_timeout = (
@@ -2201,6 +2211,9 @@ def _handle_cli_spawned_daemon(
         print(f"Error while loading compare array: {e}")
         sys.exit(1)
 
+    # Before the bundle is cleaned up below: these sessions read from it.
+    _register_tutorial_extras(port, daemon_server_id)
+
     try:
         _open_cli_spawned_view(
             port=port,
@@ -2709,6 +2722,77 @@ _FAILED_LOAD_EXIT_GRACE_SECONDS = float(
 )
 
 
+# The tutorial's extra sessions. Two of its sections cannot share the main
+# session — a vector field disables statistical projections for whatever
+# session it is attached to, and a ragged collection is a single session made
+# of differently shaped files — so they are registered separately and the tour
+# navigates to them by sid. Set once per CLI invocation, read when the viewer
+# URL is built; empty for every launch that is not the tutorial, in which case
+# the tour simply does not offer those sections.
+_TUTORIAL_BUNDLE = None
+_TUTORIAL_EXTRAS: dict[str, str] = {}
+
+
+def _register_tutorial_extras(port: int, expected_server_id: str | None = None) -> None:
+    """Register the tutorial's vector-field and ragged-collection sessions.
+
+    Best effort: a failure here costs two sections, not the tour, so it is
+    traced and swallowed rather than allowed to fail a launch that has already
+    loaded the main array.
+
+    The collection loads eagerly on purpose. The generated bundle is deleted as
+    soon as registration returns, and a lazy collection would still be holding
+    paths into it.
+    """
+    bundle = _TUTORIAL_BUNDLE
+    if bundle is None:
+        return
+    try:
+        _register_tutorial_extras_impl(port, bundle, expected_server_id)
+    finally:
+        from arrayview._tutorial import cleanup_tutorial_bundle
+
+        cleanup_tutorial_bundle(bundle.extras_directory)
+
+
+def _register_tutorial_extras_impl(port, bundle, expected_server_id) -> None:
+    try:
+        flow = _load_session_from_filepath(
+            port,
+            bundle.flow_file,
+            "flow",
+            expected_server_id=expected_server_id,
+        )
+        flow_sid = flow.get("sid")
+        if flow_sid and "error" not in flow:
+            attached = _attach_vectorfield_to_session(
+                port,
+                str(flow_sid),
+                bundle.flow_field_file,
+                expected_server_id=expected_server_id,
+            )
+            if "error" not in attached:
+                _TUTORIAL_EXTRAS["flow"] = str(flow_sid)
+    except Exception as exc:  # pragma: no cover - best effort
+        _trace_launch_event("tutorial.extra_failed", extra="flow", error=str(exc))
+
+    try:
+        stack = _load_session_from_filepath(
+            port,
+            "",
+            "cases",
+            dir_patterns=[bundle.stack_pattern],
+            collection_stack="ragged",
+            collection_load="eager",
+            expected_server_id=expected_server_id,
+        )
+        stack_sid = stack.get("sid")
+        if stack_sid and "error" not in stack:
+            _TUTORIAL_EXTRAS["stack"] = str(stack_sid)
+    except Exception as exc:  # pragma: no cover - best effort
+        _trace_launch_event("tutorial.extra_failed", extra="stack", error=str(exc))
+
+
 def _join_query_values(values: _CSVValues) -> str:
     if isinstance(values, str):
         return values
@@ -2743,6 +2827,11 @@ def _viewer_query(
         parts.append(f"dim_y={dims[1]}")
     if inline:
         parts.append("inline=1")
+    if _TUTORIAL_EXTRAS:
+        # The tour needs these to survive the navigations it makes between
+        # its own sessions, so they ride in the URL rather than in memory.
+        for key, extra_sid in sorted(_TUTORIAL_EXTRAS.items()):
+            parts.append(f"tutorial_{key}_sid={extra_sid}")
     return "?" + "&".join(parts)
 
 
@@ -3397,9 +3486,8 @@ def view(
             launch_context=_launch_context,
         )
 
-    # VS Code tunnel/remote: use the server + WebSocket path.
-    # WS works through the devtunnel when the port is public — the extension
-    # calls ensurePortPublic() before asExternalUri.
+    # VS Code tunnel/remote: use the server + WebSocket path. The opener owns
+    # private client-side delivery for tunnel sessions.
     # Fall through to the server-based path below (don't return early).
 
     # With a planned existing server: register arrays via /load. Keep display
@@ -3644,7 +3732,10 @@ def view(
                 and _launch_plan.display is Display.VSCODE
             ):
                 _configure_vscode_port_preview(
-                    port, in_vscode=False, is_remote=True
+                    port,
+                    in_vscode=False,
+                    is_remote=True,
+                    is_tunnel=_launch_context.evidence.in_vscode_tunnel,
                 )
             _platform_mod._jupyter_server_port = port
     except Exception:
@@ -4935,6 +5026,8 @@ def _configure_tutorial_args(args):
     """Turn a file-less CLI request into the generated tutorial bundle."""
     from arrayview._tutorial import create_tutorial_bundle
 
+    global _TUTORIAL_BUNDLE
+
     tutorial = create_tutorial_bundle()
     args.files = [tutorial.base_file, tutorial.compare_file]
     args.overlay = [f"Regions={tutorial.overlay_file}"]
@@ -4942,6 +5035,8 @@ def _configure_tutorial_args(args):
     args._demo_cleanup = False
     args._tutorial_cleanup_dir = tutorial.directory
     args.rgb = False
+    _TUTORIAL_BUNDLE = tutorial
+    _TUTORIAL_EXTRAS.clear()
     return tutorial
 
 
@@ -5123,8 +5218,7 @@ def arrayview():
         action="store_true",
         help=(
             "Start a persistent server on the given port without loading any data. "
-            "Useful on VS Code remote tunnel: run this first, set the port to Public "
-            "in the Ports tab, then use 'arrayview FILE' freely."
+            "Useful for reusing one ArrayView server across repeated launches."
         ),
     )
     parser.add_argument(
@@ -5522,8 +5616,7 @@ def arrayview():
                 _revalidate_launch_server(serve_context, args.port)
                 print(
                     f"[ArrayView] Server already running on port {args.port}. "
-                    "Set port to Public in VS Code Ports tab if not done yet, "
-                    "then run: arrayview your_file.npy"
+                    "Run: arrayview your_file.npy"
                 )
                 return
 
@@ -5553,6 +5646,7 @@ def arrayview():
                 args.port,
                 in_vscode=serve_context.evidence.in_vscode_terminal,
                 is_remote=serve_context.evidence.is_vscode_remote,
+                is_tunnel=serve_context.evidence.in_vscode_tunnel,
             )
             script = (
                 "from arrayview._launcher import _serve_empty; "
@@ -5874,10 +5968,6 @@ def arrayview():
             "--window native is not available over a VS Code remote/tunnel "
             "session; opening a VS Code tab instead."
         ),
-        "remote_browser_redirected_to_vscode": (
-            "--window browser cannot reach a browser on the remote host; "
-            "opening a VS Code tab instead."
-        ),
         "native_unavailable": (
             "--window native found no usable GUI backend (no display server "
             "or no Qt/GTK for pywebview); opening a browser instead."

{arrayview-0.40.0 → arrayview-0.41.0}/src/arrayview/_lifecycle.py

@@ -13,6 +13,7 @@ from arrayview._session import (
     SESSIONS,
     VIEWER_CONNECTION_EPOCHS,
     VIEWER_PHASE_JOURNALS,
+    VIEWER_LAUNCH_ROUTES,
     VIEWER_RELEASE_TASKS,
 )
 
@@ -88,6 +89,9 @@ def release_session(sid: str, *, cancel_if_missing: bool = False) -> bool:
         if retire_journals:
             journals = VIEWER_PHASE_JOURNALS.pop(sid, {})
             for journal in journals.values():
+                navigation_key = journal.get("navigation_key")
+                if navigation_key:
+                    VIEWER_LAUNCH_ROUTES.pop(navigation_key, None)
                 journal_task = journal.get("release_task")
                 if journal_task is not None and not journal_task.done():
                     try:

{arrayview-0.40.0 → arrayview-0.41.0}/src/arrayview/_routes_query.py

@@ -1,5 +1,7 @@
 import asyncio
 import io
+import re
+from urllib.parse import parse_qs
 
 import numpy as np
 from fastapi import Depends, HTTPException, Request, Response
@@ -73,6 +75,52 @@ def register_query_routes(app, *, get_session_or_404, pil_image, pil_imageops) -
         journals = _session_mod.VIEWER_PHASE_JOURNALS.setdefault(sid, {})
         if phase == "launch-prepared":
             previous_journal = journals.get(request_id)
+            viewer_query = body.get("viewer_query")
+            tab_key = body.get("tab_key")
+            navigation_key = body.get("navigation_key")
+            navigation_attempt = body.get("navigation_attempt")
+            short_route = any(
+                value is not None
+                for value in (
+                    viewer_query,
+                    tab_key,
+                    navigation_key,
+                    navigation_attempt,
+                )
+            )
+            if short_route:
+                if (
+                    not isinstance(viewer_query, str)
+                    or not viewer_query.startswith("?")
+                    or len(viewer_query) > 65536
+                ):
+                    raise HTTPException(status_code=400, detail="Invalid viewer query")
+                parsed_query = parse_qs(
+                    viewer_query.removeprefix("?"),
+                    keep_blank_values=True,
+                )
+                if parsed_query.get("sid") != [sid]:
+                    raise HTTPException(
+                        status_code=409,
+                        detail="Viewer primary session changed",
+                    )
+                if any(key.startswith("_av_") for key in parsed_query):
+                    raise HTTPException(
+                        status_code=400,
+                        detail="Reserved viewer query field",
+                    )
+                if (
+                    not isinstance(tab_key, str)
+                    or re.fullmatch(r"[A-Za-z0-9_-]{16,64}", tab_key) is None
+                    or not isinstance(navigation_key, str)
+                    or re.fullmatch(r"[A-Za-z0-9_-]{16,64}", navigation_key) is None
+                    or not isinstance(navigation_attempt, int)
+                    or not 0 <= navigation_attempt <= 32
+                ):
+                    raise HTTPException(
+                        status_code=400,
+                        detail="Invalid short viewer route identity",
+                    )
             previous_release_task = (
                 previous_journal.get("release_task")
                 if previous_journal is not None
@@ -83,9 +131,23 @@ def register_query_routes(app, *, get_session_or_404, pil_image, pil_imageops) -
                 and not previous_release_task.done()
             ):
                 previous_release_task.cancel()
+            previous_navigation_key = (
+                previous_journal.get("navigation_key")
+                if previous_journal is not None
+                else None
+            )
+            if previous_navigation_key:
+                _session_mod.VIEWER_LAUNCH_ROUTES.pop(
+                    previous_navigation_key,
+                    None,
+                )
             journal = journals[request_id] = {
                 "token": token,
                 "window_id": window_id,
+                "viewer_query": viewer_query,
+                "tab_key": tab_key,
+                "navigation_key": navigation_key,
+                "navigation_attempt": navigation_attempt,
                 "viewer_instance_ids": [],
                 "phases": [],
                 "related_sids": None,
@@ -93,12 +155,20 @@ def register_query_routes(app, *, get_session_or_404, pil_image, pil_imageops) -
                 "release_task": None,
                 "disconnect_release_grace_seconds": 30.0,
             }
+            if navigation_key:
+                _session_mod.VIEWER_LAUNCH_ROUTES[navigation_key] = (
+                    sid,
+                    request_id,
+                )
             return {
                 "sid": sid,
                 "request_id": request_id,
                 "window_id": window_id,
                 "server_id": _session_mod.SERVER_RUNTIME.instance_id,
                 "token": token,
+                "tab_key": tab_key,
+                "navigation_key": navigation_key,
+                "navigation_attempt": navigation_attempt,
                 "phases": [],
                 "viewer_instance_ids": [],
                 "related_sids": [],

{arrayview-0.40.0 → arrayview-0.41.0}/src/arrayview/_server.py

@@ -10,6 +10,7 @@ import os
 import time
 import uuid
 from dataclasses import dataclass, replace
+from urllib.parse import urlencode
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.responses import HTMLResponse, JSONResponse, Response
 from importlib.resources import files as _pkg_files
@@ -338,25 +339,45 @@ def status():
 
 # ── Root UI Route ─────────────────────────────────────────────────
 
-@app.get("/")
-def get_ui(request: Request, sid: str = None):
-    """Viewer page."""
-    # VS Code's asExternalUri() strips query parameters, so ?sid= is often lost
-    # before the page loads.  Embed the SID directly in the HTML so the viewer
-    # JS can find it regardless of the URL.
-    if not sid:
-        # No sid in URL — VS Code strips the query string before loading the
-        # page, so ?sid= is lost.  Inject the latest valid session
-        # server-side so the viewer JS can find it regardless of the URL.
-        if SESSIONS:
-            latest_sid = list(SESSIONS.keys())[-1]
-            query_val = json.dumps(f"?sid={latest_sid}")
-        else:
-            query_val = "null"  # viewer will show "Session not found or expired"
-    else:
-        # sid is present in the URL (valid or not) — let the JS fetch /metadata/{sid}
-        # and handle errors itself (shows "Session not found or expired" on 404).
-        query_val = "null"
+def _trace_page_request(
+    request: Request,
+    *,
+    request_id: str | None = None,
+    navigation_attempt: str | None = None,
+) -> None:
+    """Record that a viewer page fetch reached this backend.
+
+    A tunnel-delivered launch that never logs ``script-loaded`` is ambiguous
+    from the opener's side alone: the relay may have dropped the page request,
+    or the page may have arrived and the script stalled.  This distinguishes
+    the two.  Inert unless ``ARRAYVIEW_LAUNCH_TRACE`` is set.
+    """
+    if not os.environ.get("ARRAYVIEW_LAUNCH_TRACE"):
+        return
+    try:
+        from arrayview._launch_trace import emit_launch_event
+
+        params = request.query_params
+        emit_launch_event(
+            "page.requested",
+            request_id=request_id or params.get("_av_launch_request_id"),
+            navigation_attempt=(
+                navigation_attempt
+                or params.get("_av_navigation_attempt")
+                or "0"
+            ),
+        )
+    except Exception:
+        pass
+
+
+def _viewer_ui_response(
+    request: Request,
+    *,
+    sid: str | None,
+    query_val: str,
+):
+    """Render one viewer page with its launch query already chosen."""
     _init_luts()
     _cfg_colormaps = get_viewer_colormaps()
     _valid_cfg_colormaps = (
@@ -390,7 +411,72 @@ def get_ui(request: Request, sid: str = None):
         html,
         request=request,
         media_type="text/html; charset=utf-8",
-        # no-store stays: when the URL carries no ?sid=, the body embeds the
-        # latest session id, so a cached copy would resurrect a dead session.
         headers={"Cache-Control": "no-store"},
     )
+
+
+@app.get("/_av/{tab_key}/{navigation_key}")
+def get_short_viewer_ui(
+    request: Request,
+    tab_key: str,
+    navigation_key: str,
+):
+    """Resolve a private integrated-browser launch without exposing its query."""
+    owner = _session_mod.VIEWER_LAUNCH_ROUTES.get(navigation_key)
+    if owner is None:
+        raise HTTPException(status_code=404, detail="Viewer launch route expired")
+    sid, request_id = owner
+    journal = (
+        _session_mod.VIEWER_PHASE_JOURNALS
+        .get(sid, {})
+        .get(request_id)
+    )
+    if (
+        journal is None
+        or journal.get("tab_key") != tab_key
+        or journal.get("navigation_key") != navigation_key
+    ):
+        raise HTTPException(status_code=409, detail="Viewer launch route changed")
+    bootstrap_query = journal["viewer_query"] + "&" + urlencode(
+        {
+            "_av_integrated_browser": "1",
+            "_av_launch_request_id": request_id,
+            "_av_launch_server_id": _session_mod.SERVER_RUNTIME.instance_id,
+            "_av_launch_window_id": journal["window_id"],
+            "_av_launch_token": journal["token"],
+            "_av_navigation_attempt": journal["navigation_attempt"],
+        }
+    )
+    _trace_page_request(
+        request,
+        request_id=request_id,
+        navigation_attempt=str(journal["navigation_attempt"]),
+    )
+    return _viewer_ui_response(
+        request,
+        sid=sid,
+        query_val=json.dumps(bootstrap_query),
+    )
+
+
+@app.get("/")
+def get_ui(request: Request, sid: str = None):
+    """Viewer page."""
+    _trace_page_request(request)
+    # VS Code's asExternalUri() strips query parameters, so ?sid= is often lost
+    # before the page loads.  Embed the SID directly in the HTML so the viewer
+    # JS can find it regardless of the URL.
+    if not sid:
+        # No sid in URL — VS Code strips the query string before loading the
+        # page, so ?sid= is lost.  Inject the latest valid session
+        # server-side so the viewer JS can find it regardless of the URL.
+        if SESSIONS:
+            latest_sid = list(SESSIONS.keys())[-1]
+            query_val = json.dumps(f"?sid={latest_sid}")
+        else:
+            query_val = "null"  # viewer will show "Session not found or expired"
+    else:
+        # sid is present in the URL (valid or not) — let the JS fetch /metadata/{sid}
+        # and handle errors itself (shows "Session not found or expired" on 404).
+        query_val = "null"
+    return _viewer_ui_response(request, sid=sid, query_val=query_val)

{arrayview-0.40.0 → arrayview-0.41.0}/src/arrayview/_session.py

@@ -40,6 +40,9 @@ NATIVE_READY_REQUESTS: set[tuple[str, str]] = set()
 # Launch readiness is control-plane state and must exist before a large array
 # finishes loading. Keyed by SID, then request ID; release_session owns cleanup.
 VIEWER_PHASE_JOURNALS: dict[str, dict[str, dict]] = {}
+# Short integrated-browser navigation key -> (primary SID, request ID).
+# The full launch query stays in the fenced journal instead of the visible URL.
+VIEWER_LAUNCH_ROUTES: dict[str, tuple[str, str]] = {}
 _window_process = None
 PENDING_SESSIONS: set = set()  # sids whose data is still loading in a background thread
 PENDING_SESSION_EVENTS: dict[str, threading.Event] = {}
@@ -630,6 +633,7 @@ __all__ = [
     "VIEWER_SIDS",
     "VIEWER_CONNECTIONS_SEEN",
     "VIEWER_PHASE_JOURNALS",
+    "VIEWER_LAUNCH_ROUTES",
     "SHELL_SOCKETS",
     "_window_process",
     "PENDING_SESSIONS",