arrayview 0.42.2__tar.gz → 0.43.0__tar.gz

{arrayview-0.42.2 → arrayview-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.42.2
+Version: 0.43.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.42.2 → arrayview-0.43.0}/pyproject.toml

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

{arrayview-0.42.2 → arrayview-0.43.0}/src/arrayview/_diagnostics.py

@@ -75,6 +75,23 @@ _DIAGNOSES: list[tuple[str, str, str, str]] = [
      "fine.",
      _RETRY),
 
+    # ── A window that is alive but not answering ──────────────────────────
+    # Its process exists, so nothing treats it as dead and no other window may
+    # take the request from it — targeted requests are invisible to everyone
+    # else. The user sees nothing happen at all, and reloading that one window
+    # is the only recovery, so say so rather than suggesting a plain retry:
+    # retrying sends the next launch to the same stuck window.
+    (r"integrated browser open timeout|command discovery timeout|"
+     r"browser command did not return", ACTION,
+     "The VS Code window handling this request has stopped responding. It is "
+     "still running, so nothing else will take the request from it.",
+     _RELOAD + "  Retrying without reloading sends the next launch to the "
+     "same window."),
+    (r"claimed but never|no progress after being claimed", ACTION,
+     "A VS Code window took this request and then went quiet, so the launch is "
+     "stuck with it.",
+     _RELOAD),
+
     # ── Timing — slow, not broken ─────────────────────────────────────────
     (r"did not start the viewer script", ACTION,
      "VS Code opened an integrated-browser tab, but the tab did not navigate "
@@ -131,7 +148,7 @@ _DIAGNOSES: list[tuple[str, str, str, str]] = [
      "Check the path — and that the share it lives on is mounted."),
     (r"not a directory", FATAL,
      "That path is not a directory.",
-     "Point --stack at a directory of arrays."),
+     "Point --match at a directory of arrays."),
     (r"invalid vector ?field", FATAL,
      "The vector field file could not be used with this array.",
      "It needs the array's spatial shape plus a trailing components axis."),

arrayview-0.43.0/src/arrayview/_extra_ports.py

@@ -0,0 +1,181 @@
+"""Extra listening ports on the already-running server.
+
+Why this exists
+---------------
+
+In VS Code the viewer is fetched over a forwarded port.  Measured 2026-08-06 on
+the real host: a forward that VS Code has *just created* never loses a page
+request (4/4, and 3/3 on a genuine cold start), while one that already exists
+and has sat idle for tens of seconds drops the first two to four.  A dropped
+request never arrives — the opener can only discard the tab and open another,
+which the user sees as the viewer flickering before the array appears.
+
+While any viewer is open the server keeps the forward from going idle (see the
+nudge in ``_routes_websocket``).  The case that leaves is the cold one: no
+viewer is open, so nothing has kept the forward alive, and the first launch pays.
+
+A port that has never been forwarded does not have that problem.  So a cold
+launch is served from a fresh port, which VS Code forwards for the first time.
+This module adds that port to the process that is *already* running, rather than
+starting another server: same process, same loaded arrays, nothing extra to shut
+down, and repeat opens keep using the original port.
+
+Lifetime
+--------
+
+An extra port is closed as soon as no viewer is connected **on that port**.
+Viewers report the port they arrived on, so a port is released the moment its
+own viewer goes away, rather than waiting for every viewer everywhere to close —
+otherwise one cold start early in a session would leave a port listening for the
+rest of the day.
+
+It must not be closed while a viewer loaded from it is alive: the viewer keeps
+using HTTP on its own origin long after the page has rendered, so pulling the
+port out from under it would break the viewer rather than tidy up after it.
+
+A port that never receives a viewer at all — the launch failed, or the user
+closed the tab before it loaded — is closed after ``UNUSED_GRACE_S``.  Without
+that, a failed cold start would leak a port with nothing to trigger its release.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+import time
+
+import arrayview._session as _session_mod
+from arrayview._session import _vprint
+
+# Cold starts are rare — one per session in practice, because the first launch
+# leaves a viewer open and every launch after that is warm.  The cap is a guard
+# against a pathological caller, not an expected working set.
+MAX_EXTRA_PORTS = 3
+
+# How long a freshly opened port may sit with no viewer on it before it is
+# reclaimed.  This is the leak guard for a launch that never produced a viewer;
+# it has to outlast a slow array load, because the port is opened before the
+# page is even requested and a large file can take a while to reach its socket.
+UNUSED_GRACE_S = 180.0
+
+# port -> {"socket", "server", "task", "viewers", "opened_at"}
+_EXTRA_PORTS: dict[int, dict] = {}
+
+
+def extra_ports() -> list[int]:
+    """Ports currently being served in addition to the main one."""
+    return sorted(_EXTRA_PORTS)
+
+
+def _bind_free_port() -> socket.socket:
+    """Bind a port the OS says is free, so nothing has to be guessed."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind(("localhost", 0))
+    sock.listen(128)
+    return sock
+
+
+async def open_extra_port() -> int | None:
+    """Serve the running app on one more, never-before-used port.
+
+    Returns the port, or ``None`` if one could not be added.  Never raises: a
+    launch that cannot get a fresh port is still a working launch on the main
+    port, only with the cold-start flicker it would have had anyway.
+    """
+    if len(_EXTRA_PORTS) >= MAX_EXTRA_PORTS:
+        _vprint(
+            f"[ArrayView] not adding another port; {len(_EXTRA_PORTS)} already open"
+        )
+        return None
+    try:
+        import uvicorn
+
+        from arrayview import _server as _server_mod
+
+        sock = _bind_free_port()
+        port = sock.getsockname()[1]
+        config = uvicorn.Config(
+            _server_mod.app,
+            log_level="error",
+            timeout_keep_alive=30,
+            ws_ping_interval=None,
+            ws="websockets",
+            ws_per_message_deflate=True,
+        )
+        server = uvicorn.Server(config)
+        task = asyncio.create_task(server.serve(sockets=[sock]))
+        _EXTRA_PORTS[port] = {
+            "socket": sock,
+            "server": server,
+            "task": task,
+            "viewers": 0,
+            "opened_at": time.monotonic(),
+        }
+        asyncio.create_task(_close_if_unused(port))
+        # The socket is already listening and accepting before serve() runs, so
+        # a client that connects immediately is queued rather than refused.
+        _vprint(f"[ArrayView] serving a cold-start port on {port}")
+        return port
+    except Exception as exc:  # pragma: no cover - defensive
+        _vprint(f"[ArrayView] could not add a cold-start port: {exc}")
+        return None
+
+
+def viewer_connected(port: int | None) -> None:
+    """Note that a viewer arrived on *port*, if it is one of ours."""
+    entry = _EXTRA_PORTS.get(port)
+    if entry is not None:
+        entry["viewers"] += 1
+
+
+async def viewer_disconnected(port: int | None) -> None:
+    """Note a viewer left *port*, and release the port if it was the last one."""
+    entry = _EXTRA_PORTS.get(port)
+    if entry is None:
+        return
+    entry["viewers"] = max(0, entry["viewers"] - 1)
+    if entry["viewers"] == 0:
+        await _close_port(port)
+
+
+async def _close_if_unused(port: int) -> None:
+    """Reclaim a port that never got a viewer.
+
+    Its own release is driven by the viewer that loaded from it, so a launch
+    that never produced one would otherwise leave the port listening forever.
+    """
+    await asyncio.sleep(UNUSED_GRACE_S)
+    entry = _EXTRA_PORTS.get(port)
+    if entry is not None and entry["viewers"] == 0:
+        _vprint(f"[ArrayView] cold-start port {port} was never used")
+        await _close_port(port)
+
+
+async def _close_port(port: int) -> None:
+    entry = _EXTRA_PORTS.pop(port, None)
+    if entry is None:
+        return
+    try:
+        entry["server"].should_exit = True
+        await asyncio.wait_for(entry["task"], timeout=5)
+    except Exception:
+        entry["task"].cancel()
+    finally:
+        try:
+            entry["socket"].close()
+        except Exception:
+            pass
+    _vprint(f"[ArrayView] released cold-start port {port}")
+
+
+async def close_extra_ports() -> None:
+    """Release every extra port.  Only safe with no viewer connected anywhere.
+
+    A backstop for the per-port release above: if a viewer is lost without its
+    disconnect being seen, this still reclaims the port once the server is idle.
+    """
+    if not _EXTRA_PORTS or _session_mod.VIEWER_SOCKETS > 0:
+        return
+    for port in list(_EXTRA_PORTS):
+        await _close_port(port)

{arrayview-0.42.2 → arrayview-0.43.0}/src/arrayview/_io.py

@@ -1139,7 +1139,7 @@ def load_dir_collection(
     overlay match.
     """
     if not base_patterns:
-        raise ValueError("--stack requires at least one positional image pattern.")
+        raise ValueError("--match requires at least one positional image pattern.")
     overlays = overlays or []
 
     inferred_case_depth = None
@@ -1338,7 +1338,7 @@ def _load_file_series(path, *, load="lazy", stack="auto"):
 
     One file per patient folder → 4D ``(*vol, P)``.  When a folder holds
     several arrays side by side there is no per-folder case to key on, so every
-    file becomes its own case — the same collection ``--stack`` builds for that
+    file becomes its own case — the same collection ``--match`` builds for that
     directory.
 
     If every file is NIfTI (.nii/.nii.gz), delegates to
@@ -1383,9 +1383,9 @@ def _load_file_series(path, *, load="lazy", stack="auto"):
 
     # A folder holding several arrays side by side is a flat collection: one
     # case per file. This used to raise and tell the user to retype the command
-    # with --stack, which made "open this folder" unreachable from any caller
+    # with --match, which made "open this folder" unreachable from any caller
     # that can only hand over a path (VS Code Explorer, drag-and-drop, the
-    # /load route). Route it through the same builder --stack uses so both
+    # /load route). Route it through the same builder --match uses so both
     # spellings produce the same session instead of one of them failing.
     if any(len(files) != 1 for files in patients.values()):
         flat = sorted(fpath for files in patients.values() for fpath in files)
@@ -1445,7 +1445,7 @@ def _load_nifti_series(path, *, load="lazy", stack="auto"):
             raise ValueError(
                 f"Patient folder {pdir!r} contains {len(nii_files)} NIfTI "
                 f"files: {[os.path.basename(f) for f in nii_files]}. "
-                "Use --stack with explicit file patterns for multi-file folders."
+                "Use --match with explicit file patterns for multi-file folders."
             )
 
     return _series_from_file_matrix(file_matrix, load=load, stack=stack)

{arrayview-0.42.2 → arrayview-0.43.0}/src/arrayview/_launcher.py

@@ -2314,6 +2314,16 @@ def _handle_cli_spawned_daemon(
                 expected_server_id=daemon_server_id,
             ):
                 raise RuntimeError("ArrayView could not confirm no-display session cleanup")
+            # Say what happened. This mode loads the array, proves it registers,
+            # and then deliberately releases it so nothing is left holding the
+            # source — which is the whole point of it, and is why no server
+            # survives and no window opens. Printing nothing at all made a
+            # successful check indistinguishable from silently doing nothing.
+            print(
+                f"[ArrayView] {name}: loaded and released. "
+                f"No display was opened and no server is left running.",
+                flush=True,
+            )
     except Exception:
         _terminate_owned_process(daemon_proc)
         _cleanup_source_staging_dirs(source_staging_dirs)
@@ -5079,7 +5089,7 @@ class _CliCollectionScanProgress:
 
 
 def _print_dir_collection_summary(summary):
-    print("[ArrayView] --stack matched collection:")
+    print("[ArrayView] --match matched collection:")
     print(f"  cases: {len(summary['cases'])}")
     print(f"  spatial shape: {summary['spatial_shape']}")
     print(f"  image shape: {summary['shape']}")
@@ -5396,7 +5406,7 @@ def arrayview():
         default=None,
         help=(
             "Segmentation mask overlay. In file mode, pass a concrete mask file. "
-            "In --stack mode, pass NAME=PATTERN to add a named overlay role. "
+            "In --match mode, pass NAME=PATTERN to add a named overlay role. "
             "Repeat --overlay to load multiple overlays."
         ),
     )
@@ -5406,7 +5416,7 @@ def arrayview():
         action="append",
         default=None,
         help=(
-            "In --stack mode, discover mask filenames below matching per-case "
+            "In --match mode, discover mask filenames below matching per-case "
             "directories as sparse overlay roles. Missing masks render as empty. "
             "Case directories are inferred automatically; --case-regex can "
             "override unusual layouts. Repeat to include multiple directories."
@@ -5493,7 +5503,7 @@ def arrayview():
         help="Display name for the array",
     )
     parser.add_argument(
-        "--stack",
+        "--match",
         action="store_true",
         dest="stack_mode",
         help=(
@@ -5502,6 +5512,16 @@ def arrayview():
             "--overlay values become overlay role patterns."
         ),
     )
+    # --stack was renamed to --match. Without this it would not error: argparse
+    # matches unambiguous prefixes, and --stack is a prefix of --stack-policy,
+    # which takes an optional value — so an old command would run and quietly
+    # ignore what the user asked for. Failing loudly is the point of it.
+    parser.add_argument(
+        "--stack",
+        action="store_true",
+        dest="stack_flag_removed",
+        help=argparse.SUPPRESS,
+    )
     parser.add_argument(
         "--series",
         default=None,
@@ -5515,7 +5535,7 @@ def arrayview():
         default=None,
         dest="case_regex",
         help=(
-            "Regex used in --stack mode to extract a case id. Must define "
+            "Regex used in --match mode to extract a case id. Must define "
             "a named (?P<case>...) group."
         ),
     )
@@ -5523,7 +5543,7 @@ def arrayview():
         "--dry-run",
         action="store_true",
         dest="dry_run",
-        help="In --stack mode, print matched cases and roles without opening a viewer.",
+        help="In --match mode, print matched cases and roles without opening a viewer.",
     )
     parser.add_argument(
         "--stack-policy",
@@ -5532,7 +5552,7 @@ def arrayview():
         choices=("auto", "dense", "ragged"),
         dest="stack_policy",
         help=(
-            "Collection stacking policy for --stack mode: auto picks dense when "
+            "Collection stacking policy for --match mode: auto picks dense when "
             "shapes agree and ragged otherwise; dense requires matching shapes; "
             "ragged always keeps per-item shapes."
         ),
@@ -5643,19 +5663,25 @@ def arrayview():
                 f"--dims {args.dims!r} is invalid. "
                 "Use e.g. 'x,y,:,:' or ':,:,x,y' or '0,1'."
             )
+    if getattr(args, "stack_flag_removed", False):
+        parser.error(
+            "--stack has been renamed to --match, because it never controlled "
+            "stacking: a directory of arrays is stacked either way. It selects "
+            "which files form the collection."
+        )
     if args.dry_run and not args.stack_mode:
-        parser.error("--dry-run requires --stack.")
+        parser.error("--dry-run requires --match.")
     excluded_cases = set()
     if args.stack_mode:
         if not args.files:
-            parser.error("--stack requires at least one image pattern.")
+            parser.error("--match requires at least one image pattern.")
         if args.compare or args.vectorfield or args.watch or args.rgb:
             parser.error(
-                "--stack is incompatible with --compare, --vectorfield, "
+                "--match is incompatible with --compare, --vectorfield, "
                 "--watch, and --rgb."
             )
         if args.relay:
-            parser.error("--stack is incompatible with --relay.")
+            parser.error("--match is incompatible with --relay.")
     if args.stack_policy and not args.stack_mode:
         if len(args.files) != 1:
             parser.error(
@@ -5866,7 +5892,7 @@ def arrayview():
             if mount is not None or nested_mount is not None:
                 _print_failure(
                     "network directory collections are not accessed directly. "
-                    "Copy the collection to local storage before using --stack."
+                    "Copy the collection to local storage before using --match."
                 )
                 sys.exit(1)
         if len(dir_patterns) == 1 and os.path.isdir(dir_patterns[0]):
@@ -5906,11 +5932,11 @@ def arrayview():
                 break
             except MissingOverlayCasesError as e:
                 if not _confirm_partial_overlay_match(e):
-                    _print_failure(f"--stack could not match collection: {e}")
+                    _print_failure(f"--match could not match collection: {e}")
                     sys.exit(1)
                 excluded_cases.update(e.missing_cases)
             except Exception as e:
-                _print_failure(f"--stack could not match collection: {e}")
+                _print_failure(f"--match could not match collection: {e}")
                 sys.exit(1)
         _print_dir_collection_summary(summary)
         if args.dry_run:
@@ -5919,7 +5945,7 @@ def arrayview():
         from arrayview._source_safety import lexical_abspath
 
         if args.overlay_dir:
-            parser.error("--overlay-dir requires --stack.")
+            parser.error("--overlay-dir requires --match.")
         try:
             file_overlay_specs = _normalize_file_overlay_specs(args.overlay)
         except ValueError as e:

{arrayview-0.42.2 → arrayview-0.43.0}/src/arrayview/_routes_websocket.py

@@ -147,6 +147,79 @@ async def _await_session_reporting_read_progress(ws, sid):
         return _session_mod.SESSIONS.get(sid)
 
 
+# How often to consider nudging, how long the path must have been unused
+# before it is worth nudging, and how many connections the nudge opens.
+_PATH_NUDGE_INTERVAL_S = 15.0
+_PATH_NUDGE_IDLE_S = 20.0
+_PATH_NUDGE_CONNECTIONS = 3
+_PATH_NUDGE_TASK: "asyncio.Task | None" = None
+
+
+async def _nudge_client_path_forever() -> None:
+    """Keep the client's connection to this server from going idle.
+
+    In VS Code the viewer is reached over a forwarded port.  Measured
+    2026-08-06: once that forward has sat unused for tens of seconds, the first
+    two or three connections through it are dropped outright — the tab opens,
+    nothing is ever requested, and the opener has to discard the tab and open
+    another, which the user sees as flickering.  Traffic through the forward
+    prevents it; an open viewer is the only thing on the client side that can
+    produce that traffic on demand.
+
+    Exactly one viewer is asked, so the cost does not grow with the number of
+    open tabs — which matters, because many open viewers already push against a
+    per-window connection ceiling, and scaling the nudge with tab count would
+    push hardest exactly when there is least headroom.  Nothing is sent while
+    arrays are being opened: a page served in the last ``_PATH_NUDGE_IDLE_S``
+    means the path is already in use.
+    """
+    while True:
+        try:
+            await asyncio.sleep(_PATH_NUDGE_INTERVAL_S)
+            sockets = _session_mod.LIVE_VIEWER_SOCKETS
+            if not sockets:
+                continue
+            idle_for = time.time() - _session_mod.LAST_PAGE_SERVED_AT
+            if idle_for < _PATH_NUDGE_IDLE_S:
+                continue
+            # Newest first: the most recently opened viewer is the most likely
+            # to still be on screen, and a socket that has died but not yet
+            # been cleaned up would otherwise swallow every nudge in silence —
+            # which is exactly how this failed on its first measurement.  Stop
+            # at the first viewer that actually accepts it, so the traffic
+            # stays one burst no matter how many viewers are open.
+            payload = {
+                "type": "warm_path",
+                "connections": _PATH_NUDGE_CONNECTIONS,
+            }
+            for ws in reversed(list(sockets)):
+                try:
+                    await ws.send_json(payload)
+                    break
+                except Exception:
+                    try:
+                        sockets.remove(ws)
+                    except ValueError:
+                        pass
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            # A nudge is best-effort.  It must never take the server down or
+            # end the loop, or the next launch silently loses its protection.
+            pass
+
+
+def _ensure_path_nudge_task() -> None:
+    """Start the nudge loop once, when the first viewer connects."""
+    global _PATH_NUDGE_TASK
+    if _PATH_NUDGE_TASK is not None and not _PATH_NUDGE_TASK.done():
+        return
+    try:
+        _PATH_NUDGE_TASK = asyncio.create_task(_nudge_client_path_forever())
+    except RuntimeError:
+        _PATH_NUDGE_TASK = None
+
+
 async def _send_json_quietly(ws, payload):
     try:
         await ws.send_json(payload)
@@ -287,6 +360,18 @@ def register_websocket_routes(app) -> None:
 
         _session_mod.VIEWER_SOCKETS += 1
         _session_mod.VIEWER_CONNECTIONS_SEEN += 1
+        _session_mod.LIVE_VIEWER_SOCKETS.append(ws)
+        _ensure_path_nudge_task()
+        # Which port this viewer arrived on, so a cold-start port can be
+        # released the moment its own viewer goes away rather than waiting for
+        # every viewer everywhere to close.
+        arrived_on = (ws.scope.get("server") or (None, None))[1]
+        try:
+            from arrayview import _extra_ports
+
+            _extra_ports.viewer_connected(arrived_on)
+        except Exception:
+            pass
         _session_mod.VIEWER_SID_COUNTS[sid] = (
             _session_mod.VIEWER_SID_COUNTS.get(sid, 0) + 1
         )
@@ -672,6 +757,23 @@ def register_websocket_routes(app) -> None:
             except asyncio.CancelledError:
                 pass
             _session_mod.VIEWER_SOCKETS = max(0, _session_mod.VIEWER_SOCKETS - 1)
+            try:
+                _session_mod.LIVE_VIEWER_SOCKETS.remove(ws)
+            except ValueError:
+                pass
+            try:
+                from arrayview import _extra_ports
+
+                # Release this viewer's own cold-start port as soon as it is
+                # the last one there — not when the whole server goes idle, or
+                # a single cold start would keep a port listening all session.
+                asyncio.create_task(_extra_ports.viewer_disconnected(arrived_on))
+                if _session_mod.VIEWER_SOCKETS == 0:
+                    # Backstop: if a viewer was lost without its disconnect
+                    # being seen, an idle server still reclaims everything.
+                    asyncio.create_task(_extra_ports.close_extra_ports())
+            except Exception:
+                pass
             sid_count = max(0, _session_mod.VIEWER_SID_COUNTS.get(sid, 0) - 1)
             if sid_count:
                 _session_mod.VIEWER_SID_COUNTS[sid] = sid_count

{arrayview-0.42.2 → arrayview-0.43.0}/src/arrayview/_server.py

@@ -292,6 +292,23 @@ def get_shell():
     return HTMLResponse(content=_SHELL_HTML)
 
 
+@app.post("/cold-start-port")
+async def cold_start_port():
+    """Serve this same server on one more, never-before-forwarded port.
+
+    Asked for only when no viewer is connected.  A forward VS Code has just
+    created does not drop its first requests, while one that has sat idle does,
+    and that is what makes a cold launch flicker.  The port is released as soon
+    as no viewer is connected anywhere.
+    """
+    from arrayview import _extra_ports
+
+    if _session_mod.VIEWER_SOCKETS > 0:
+        return {"port": None, "reason": "a viewer is already connected"}
+    port = await _extra_ports.open_extra_port()
+    return {"port": port}
+
+
 @app.get("/ping")
 def ping():
     """Health marker so clients can verify this is an ArrayView server."""
@@ -351,7 +368,12 @@ def _trace_page_request(
     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.
+
+    Also stamps when a page was last served, which the idle nudge in
+    ``_routes_websocket`` uses to stay silent while arrays are being opened.
+    That stamp is not diagnostic and is kept before the trace guard below.
     """
+    _session_mod.LAST_PAGE_SERVED_AT = time.time()
     if not os.environ.get("ARRAYVIEW_LAUNCH_TRACE"):
         return
     try:

{arrayview-0.42.2 → arrayview-0.43.0}/src/arrayview/_session.py

@@ -33,6 +33,13 @@ VIEWER_SID_COUNTS: dict[str, int] = {}  # active viewer WS count per session ID
 VIEWER_CONNECTION_EPOCHS: dict[str, int] = {}
 VIEWER_RELEASE_TASKS: dict[str, asyncio.Task] = {}
 VIEWER_CONNECTIONS_SEEN = 0  # monotonic count of accepted viewer WS connections
+# Live viewer WebSockets, oldest first.  Only the first one is ever asked to
+# keep the client's connection to this server from going idle, so the nudge
+# traffic stays the same whether the user has one viewer open or twenty.
+LIVE_VIEWER_SOCKETS: list = []
+# When a viewer page was last served.  The path only decays while nothing is
+# being opened, so the nudge is skipped entirely while the user is working.
+LAST_PAGE_SERVED_AT: float = 0.0
 SHELL_SOCKETS = []  # webview shell WS connections (for tab injection)
 SHELL_REQUEST_IDS: set[str] = set()
 VIEWER_REQUEST_COUNTS: dict[tuple[str, str], int] = {}