arrayview 0.4.0__tar.gz → 0.5.1__tar.gz

{arrayview-0.4.0 → arrayview-0.5.1}/.claude/skills/invocation-consistency/SKILL.md

@@ -142,7 +142,90 @@ uv run pytest tests/test_cli.py -x          # CLI entry point
 uv run python -c "from arrayview import view; import numpy as np; view(np.zeros((10,10)))"
 ```
 
-## Red Flags — STOP
+## tmux and VS Code Terminal Detection
+
+tmux is the single most common reason `_find_vscode_ipc_hook()` fails even though the user IS in a VS Code terminal.
+
+### Why the ancestor-walk fails inside tmux
+
+Normal process tree (no tmux):
+```
+VS Code terminal shell (has VSCODE_IPC_HOOK_CLI)
+  └─ uv run python / arrayview   ← walks up, finds it ✓
+```
+
+Process tree inside tmux:
+```
+VS Code terminal shell (has VSCODE_IPC_HOOK_CLI)
+  └─ tmux (client process — also has VSCODE_IPC_HOOK_CLI)
+       ↕ socket IPC (not parent/child)
+tmux-server (independent daemon — does NOT have VSCODE_IPC_HOOK_CLI)
+  └─ pane shell
+       └─ uv run python / arrayview   ← walks up through tmux-server, never finds it ✗
+```
+
+The arrayview process's parent chain goes through `tmux-server`, which is an independent daemon that was started at some point and does NOT inherit the VS Code terminal's environment.
+
+### Why `tmux show-environment` fails
+
+`tmux show-environment VSCODE_IPC_HOOK_CLI` queries tmux's *session* environment. tmux only tracks variables listed in its `update-environment` option. The default list is:
+```
+DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAUTHORITY
+```
+`VSCODE_IPC_HOOK_CLI` is **not** in the default list, so it is never copied into tmux's session environment. The command returns `-VSCODE_IPC_HOOK_CLI` (meaning unset) even when every client has it.
+
+### Why `#{client_pid}` alone is unreliable
+
+`tmux display-message -p '#{client_pid}'` returns **one** client PID (the "current" client). This fails when:
+- Multiple clients are attached to the session (e.g., shared session, or user has the session open in both VS Code and a regular terminal)
+- A session was created outside VS Code and then attached from VS Code
+
+### Correct approach: enumerate ALL clients for the current session
+
+```python
+# Get current session ID
+session_id = subprocess.run(["tmux", "display-message", "-p", "#{session_id}"], ...).stdout.strip()
+
+# List ALL clients for this session
+client_pids = subprocess.run(
+    ["tmux", "list-clients", "-t", session_id, "-F", "#{client_pid}"], ...
+).stdout.strip().splitlines()
+
+# Check each client's environment
+for pid_str in client_pids:
+    val = _ipc_from_pid(int(pid_str))
+    if val and os.path.exists(val):
+        return val  # found VSCODE_IPC_HOOK_CLI in one of the VS Code clients ✓
+```
+
+`list-clients -t <session_id>` scopes to the current session only, so we don't accidentally pick up a `VSCODE_IPC_HOOK_CLI` from a completely different VS Code window on another session.
+
+### Detection order in `_find_vscode_ipc_hook()` (when TERM_PROGRAM=tmux)
+
+1. `tmux show-environment VSCODE_IPC_HOOK_CLI` — cheap, works if user set `update-environment`
+2. `tmux list-clients -t <session_id> -F '#{client_pid}'` → `ps ewwww` each — robust, handles all cases
+
+### What `--diagnose` should show when working
+
+```json
+"detection": {
+  "in_vscode_terminal": true,
+  "vscode_ipc_hook_recovered": "/var/folders/.../vscode-ipc-xxx.sock"
+}
+```
+
+If `vscode_ipc_hook_recovered` is `null` despite being in VS Code+tmux, the strategies above both failed. Check:
+- Is the tmux session detached (no clients attached)?
+- Is `ps ewwww -p <client_pid>` working on this OS? (Some Linux distros restrict it)
+- Is the IPC socket path valid (does the `.sock` file exist)?
+
+### Red flags for tmux detection
+
+- "I fixed it with `#{client_pid}`" → only works with one client; use `list-clients` instead
+- "I fixed it with `show-environment`" → only works if user customised `update-environment`; both strategies needed
+- "It works for me but not for the user" → check if they have multiple clients or a session created before VS Code
+
+
 
 - "I changed how the server starts but only tested CLI" → test all paths
 - "The feature works locally but not in tunnel" → check `_is_vscode_remote()` path and port exposure

{arrayview-0.4.0 → arrayview-0.5.1}/.github/workflows/python-publish.yml

@@ -20,9 +20,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.x"
 
@@ -33,7 +33,7 @@ jobs:
           python -m build
 
       - name: Upload distributions
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: release-dists
           path: dist/
@@ -59,7 +59,7 @@ jobs:
 
     steps:
       - name: Retrieve release distributions
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: release-dists
           path: dist/

arrayview-0.5.1/AGENTS.md

@@ -0,0 +1,219 @@
+# ArrayView Agent Guide
+
+This file defines how coding agents should work in this repository.
+
+## Mission
+
+Build and maintain a smooth `arrayview` experience across:
+
+- Local: CLI, Python scripts, Jupyter, Julia via PythonCall
+- Display modes: native `pywebview` and browser
+- VS Code terminals: browser opens should prefer VS Code Simple Browser
+- VS Code remote/tunnel sessions: viewer should open in the developer's VS Code client, not on the remote host browser
+
+## Product Overview
+
+`arrayview` is an interactive viewer for multi-dimensional arrays and medical/scientific volumes.
+It runs a local FastAPI server with an HTML/JS frontend, then displays it either:
+
+- in a native `pywebview` window,
+- in a browser (including VS Code Simple Browser in VS Code terminals), or
+- inline in Jupyter notebooks.
+
+## Architecture
+
+```
+CLI / Python API
+   |
+   +- view()          Python entry point  (_launcher.py)
+   +- arrayview()     CLI entry point (`uvx arrayview file.npy`)  (_launcher.py)
+      |
+      +- FastAPI server  (_server.py)
+         +- /           viewer HTML
+         +- /shell      pywebview shell HTML
+         +- /ws/{sid}   WebSocket for render updates
+         +- /load       register arrays
+         +- /ping       health check
+```
+
+## Core Files
+
+### Backend (server-side)
+
+| File | Responsibility |
+|------|---------------|
+| `src/arrayview/_launcher.py` | Entry points (`view()`, `arrayview()` CLI), process management, window opening |
+| `src/arrayview/_server.py` | FastAPI app, all REST routes, WebSocket handlers, HTML templates |
+| `src/arrayview/_session.py` | Sessions, global state, caches, render thread, constants |
+| `src/arrayview/_render.py` | Rendering pipeline: colormaps, LUTs, slice extraction, RGBA/mosaic/RGB |
+| `src/arrayview/_vscode.py` | VS Code extension management, signal-file IPC, browser opening |
+| `src/arrayview/_platform.py` | Platform/environment detection |
+| `src/arrayview/_io.py` | Array I/O (load from file, format detection) |
+| `src/arrayview/_app.py` | **Compat shim only** — re-exports from the modules above; do not add logic here |
+
+### Frontend
+
+| File | Responsibility |
+|------|---------------|
+| `src/arrayview/_viewer.html` | Viewer UI (single-file, all JS/CSS embedded) |
+| `src/arrayview/_shell.html` | Shell page for native tab/window management |
+
+### VS Code Extension
+
+| File | Responsibility |
+|------|---------------|
+| `vscode-extension/extension.js` | VS Code opener behavior |
+| `vscode-extension/package.json` | Extension metadata and version |
+| `src/arrayview/arrayview-opener.vsix` | Packaged extension installed by Python code |
+
+## Skills — When to Use
+
+**Always invoke the relevant skill before touching the corresponding area.**
+
+| Skill | Trigger |
+|-------|---------|
+| `viewer-ui-checklist` | ANY UI change: keyboard shortcuts, layout, new panels, canvas behavior. Keeps `visual_smoke.py` in sync. |
+| `modes-consistency` | ANY visual feature: zoom, eggs, colorbars, canvas events, new rendering modes. Ensures the feature works across all six viewing modes (normal, multi-view, compare, diff, registration, qMRI). |
+| `invocation-consistency` | ANY server, startup, or display-opening change. Ensures the feature works across all six invocation paths: CLI, Python script, Jupyter, Julia, VS Code tunnel, plain SSH. |
+| `vscode-simplebrowser` | ANY change to VS Code extension install logic, signal-file IPC, `_ensure_vscode_extension()`, `_VSCODE_EXT_VERSION`, or `vscode-extension/`. Encodes the root-cause history of the extension-host reload race condition. |
+| `task-workflow` | Feature or fix tasks — enforces one-commit-per-TODO-item workflow and required collateral updates (README/help/tests/CHANGELOG). |
+
+Skill files live in `.claude/skills/` and are symlinked from `~/.claude/skills/`.
+
+## Non-Negotiables
+
+- Run commands directly when possible; avoid asking the user to run routine commands.
+- Before trying a new fix, check whether it was already attempted in prior logs/notes.
+- If re-trying a previously failed approach, explicitly note why it may work now.
+- Avoid manual cleanup requirements for users. Viewer shutdown should be automatic and reliable.
+- Do not regress existing working paths while fixing tunnel/remote behavior.
+- Do not add logic to `_app.py` — it is a compat shim only. Add new logic to the appropriate module.
+
+## Testing
+
+```bash
+uv sync --group test
+uv run playwright install chromium
+
+# Fast: HTTP API only (~2s)
+uv run pytest tests/test_api.py -v
+
+# CLI entry-point tests
+uv run pytest tests/test_cli.py -v
+
+# Browser/Playwright tests (~100s)
+uv run pytest tests/test_browser.py -v
+
+# All tests
+uv run pytest tests/
+
+# Visual smoke test — run after any UI change, review screenshots
+uv run python tests/visual_smoke.py
+# Screenshots saved to tests/smoke_output/
+```
+
+Visual regression baselines are in `tests/snapshots/`. Delete a snapshot file to reset its baseline.
+
+## Validation Matrix
+
+After any change, verify the affected paths:
+
+| What changed | Minimum checks |
+|---|---|
+| Server / API | `pytest tests/test_api.py` |
+| CLI / entry points | `pytest tests/test_cli.py` |
+| Viewer UI | `pytest tests/test_browser.py` + `python tests/visual_smoke.py` |
+| VS Code / platform | Manual: VS Code local terminal, VS Code remote/tunnel |
+| Large array handling | `pytest tests/test_large_arrays.py` |
+
+Manual smoke paths (for platform/display changes):
+- Local CLI: `arrayview file.npy`
+- Python script: `view(arr)`
+- Jupyter inline (default)
+- VS Code terminal browser path
+- VS Code remote/tunnel path
+
+## Platform Behavior (Must Preserve)
+
+- Local Python/CLI: native window by default, browser fallback available
+- Jupyter: inline iframe by default; explicit window mode still supported
+- VS Code terminal: browser opens should target VS Code Simple Browser
+- VS Code tunnel/SSH remote: should open in VS Code Simple Browser, never open UI on remote host browser by mistake
+- Use `localhost` in URLs (not `127.0.0.1`) for reliable VS Code port forwarding
+
+## VS Code Integration
+
+Key functions (all in `_vscode.py`):
+
+- `_ensure_vscode_extension()` — installs/updates the VSIX; must handle stale versions robustly
+- `_configure_vscode_port_preview()` — sets up port forwarding for the viewer URL
+- `_open_via_signal_file()` — IPC mechanism to open URLs in the VS Code client
+- `_schedule_remote_open_retries()` — retries for tunnel environments where IPC may not be immediately available
+
+`_VSCODE_EXT_VERSION` is defined in `_vscode.py` and must match `vscode-extension/package.json`.
+If extension behavior changes, rebuild the VSIX and keep versioning in sync.
+
+## Rebuild VS Code Extension
+
+```bash
+cd vscode-extension
+vsce package -o ../src/arrayview/arrayview-opener.vsix
+```
+
+Then update `_VSCODE_EXT_VERSION` in `src/arrayview/_vscode.py`.
+
+## High-Risk Areas
+
+- VS Code extension install/update detection and stale extension versions
+- Recovering VS Code IPC hook when env vars are stripped (`uv run` and subprocesses)
+- Deciding when to use native window vs browser vs VS Code Simple Browser
+- Port-forward/autoforward behavior in tunnel environments
+- Shutdown lifecycle and orphan process prevention
+
+## Workflow For Complex Debugging
+
+1. Start a logfile `LOG_<FEATURE>.md`.
+2. Record each significant attempt: hypothesis → change made → result → decision (keep/revert/follow-up).
+3. Prefer incremental, testable changes.
+4. Verify behavior in the most failure-prone environments: VS Code local terminal, VS Code remote/tunnel.
+5. If behavior is not as expected, re-read the logfile before a new attempt.
+
+## Source Of Truth
+
+- End-user usage and setup: `README.md`
+
+## Changelog
+
+- **multi-overlay**: `view(arr, overlay=[mask1, mask2, ...])` now accepts a list of overlay masks, each auto-assigned a distinct palette color. Binary masks use the palette color; multi-label masks use per-label colors; continuous/float masks render as heatmap. Server compositing uses `_composite_overlays` in `_server.py`.
+- **welcome-screen**: Canvas capped to 50% viewport height; yellow hint text (⌘O / Ctrl+O · drop file) shown below canvas instead of centered overlay. `body.welcome-mode` CSS class applied.
+- **smart-colormap**: REMOVED. Automatic colormap selection at load time has been removed. `_recommend_colormap()` and `session.recommended_colormap` deleted; `/metadata` no longer returns `recommended_colormap`. `_recommend_colormap_reason()` is retained to power the info overlay (i key) Colormap row.
+- **watch-mode**: `arrayview file.npy --watch` polls file mtime every 1 s and POSTs to `/reload/{sid}` on change; server reloads array in-place, clears caches, bumps `data_version`; frontend polls `/data_version/{sid}` every 1.5 s and re-renders on version bump.
+- **export-slice**: `N` key exports the current 2-D slice (raw float data) as a `.npy` file download via `/export_slice/{sid}`. Works in all viewing modes; not available in RGB mode.
+- **view-handle**: `view()` now returns a `ViewHandle` (str subclass) exposing `.update(arr)`, `.sid`, `.url`, `.port`. `ViewHandle.update()` POSTs new .npy bytes to `/update/{sid}` endpoint, which replaces session data in-place, clears caches, recomputes stats, and bumps `data_version` so the viewer re-renders automatically.
+- **histogram-strip**: `W` key toggles a pixel-value histogram strip below the colorbar. `/histogram/{sid}` endpoint returns `{counts, edges, vmin, vmax}` for the current 2-D slice; frontend renders it on a `<canvas>` via `drawHistogram()`. Refreshes automatically on slice/index changes. Disabled in compare and RGB modes.
+- **histogram-drag-clim**: Dragging the yellow vertical lines in the histogram (W key) changes `manualVmin`/`manualVmax` live. Hit radius is 7 px. Hovering anywhere on the histogram shows a tooltip with the bin value range and count. Cursor changes to `ew-resize` near a line. Smoke: scenario 55.
+- **linked-crosshair**: REMOVED. The linked crosshair feature introduced in commit a778ab7 caused a visual bug (small array rendering in top-left corner of the window with info overlaid). All `.cv-crosshair` overlay canvases, `_drawCrossHair()`, `_clearAllCrossHairs()`, and mousemove/mouseleave listeners on compare canvases have been removed.
+- **drag-reorder**: In compare mode, dragging a panel title (`.compare-title`) and dropping it onto another swaps their order instantly without re-fetching frames. Swaps `compareDisplaySids`, `compareFrames`, and per-pane `cmpManualVmin/cmpManualVmax`. Disabled in registration mode. Drag-over pane gets a dashed outline highlight.
+- **screenshot-annotation**: `s` key screenshot now burns filename and current slice index into the bottom-left corner of the exported PNG. `_buildAnnotation()` collects name/shape/indices; `_annotateCanvas(src, lines)` renders a semi-transparent black box with white monospace text onto the offscreen canvas before `toDataURL`. Works in normal and multi-view modes.
+- **rect-roi**: `A` key toggles rectangle ROI draw mode on the main canvas. Drag to select a rectangular region; on release, fetches `/roi/{sid}` with `x0,y0,x1,y1` pixel coordinates (data-space) and displays `{n, min, max, mean, std}` in the existing `#roi-panel`. Disabled in compare, multi-view, and qMRI modes. Circular ROI draw (drag without A mode) remains unchanged.
+- **info-overlay-enhanced**: `i` key info overlay now includes a "Colormap" row showing the auto-selection reason (e.g. `"RdBu_r (signed data — vmin < 0)"`). `/info/{sid}` endpoint returns `recommended_colormap` and `recommended_colormap_reason` fields. Reason derived from `_recommend_colormap_reason()` in `_session.py`.
+- **screenshot-save-location**: `s` screenshot status now reads "Screenshot saved to Downloads." and `N` slice export reads "slice saved to Downloads (.npy)". Help overlay keys `s` and `N` updated to show "(PNG → Downloads)" and "(.npy → Downloads)" respectively.
+- **vscode-simplebrowser**: `_ensure_vscode_extension()` now skips `--force` reinstall when the correct version is already on disk (avoids extension-host reload that caused signal-file miss). `_VSCODE_SIGNAL_MAX_AGE_MS` raised from 30 s to 60 s. Local VS Code terminal path now schedules 2 retry signal writes at 10 s intervals (matches remote retry pattern) to survive any residual reload gap.
+- **shift-o-picker**: `Shift+O` now opens the picker (same as `Cmd/Ctrl+O`). Welcome hint updated to "⌘O / Shift+O · drop array in window"; empty-hint and help overlay updated to match.
+- **hover-info-immediate**: Pressing `H` to enable hover info now immediately shows the pixel tooltip at the current mouse position by dispatching a synthetic `mousemove` event on the canvas, instead of waiting for the user to move the mouse.
+- **picker-rewrite**: Picker rewritten as a single unified mode (no tabs, no Open/Compare/Overlay switching). Space toggles selection on any listed array (up to 4); Enter with 0–1 selected opens/navigates; Enter with 2–4 selected enters compare mode with exactly those arrays (current session not auto-included). Overlay mode removed from picker. `enterCompareModeByMultipleSids(sids)` added; `_compareExplicitSids` state bypasses the always-prepend-current logic in `getCompareRenderSids()`. `applyCompareLayout()` and `updateCompareTitles()` use `_compareExplicitSids` for correct pane count before first render. Selected items get a green checkmark and highlighted border. Help overlay updated.
+- **vscode-tab-title**: VS Code tab now shows "ArrayView: <array name>" instead of the URL. Extension switched from `simpleBrowser.show()` (title always "Simple Browser") to `vscode.window.createWebviewPanel()` with a custom label; title is passed in the signal payload (`data.title`) derived from `session.name`. Panels are reused by URL (revealed on repeat open). Multi-window fix: `_write_vscode_signal` now always writes to the per-window targeted file (`open-request-ipc-<hookTag>.json`) when `VSCODE_IPC_HOOK_CLI` is found — the registration-file (`window-<hookTag>.json`) existence check has been removed, eliminating the race where the shared fallback was written and claimed by the wrong window. Extension-side: shared-fallback signals with a mismatched `hookTag` are forwarded to the correct targeted file instead of being processed. Extension version bumped to 0.9.15. **Fix (v0.9.16)**: `enableScripts` was inadvertently left `false` in `createWebviewPanel`, which disabled all JavaScript inside the iframe and caused a "Connecting..." hang. Fixed by setting `enableScripts: true, enableForms: true`, adding a nonce-based CSP (`script-src 'nonce-...'`), and setting the iframe `src` via an inline script (matching VS Code's own Simple Browser pattern) rather than as an HTML attribute.
+- **vscode-tunnel-signal**: Fixed VS Code tunnel: `_write_vscode_signal` now writes to the shared fallback file (`open-request-v0900.json`) when `_is_vscode_remote()` is True, instead of the per-window targeted file. Root cause: on a remote/tunnel, the extension host is spawned by VS Code Server (not the user's terminal) and does NOT inherit `VSCODE_IPC_HOOK_CLI`, so `OWN_HOOK_TAG=""` and `TARGETED_SIGNAL_FILE=null` in the extension — it only polls the shared fallback. On a tunnel there is only one VS Code session per remote, so there is no multi-window race concern. Also: tab title now correctly passed from all `_open_browser` call sites via `title=f"ArrayView: {name}"` — previously `title` was `None` in the CLI path because the session lives in a subprocess and `SESSIONS.get(sid)` returns `None` in the calling process. Retries (2× at 10 s) now also enabled on remote path since `createWebviewPanel` is idempotent.
+- **histogram-colormap-bars**: Histogram bars (W key) are now colored using the active colormap. An offscreen 256-wide canvas draws the colormap gradient; each bar samples the gradient color at the fraction corresponding to its bin center within the current vmin/vmax window. Falls back to flat gray when no gradient stops are available. Smoke: scenario 60.
+- **histogram-left-side**: Histogram strip (W key) repositioned from below the colorbar to the left side of the canvas, vertically aligned with it. Each bin maps to a y-band (value increases upward); bars grow rightward from the left edge. Clim lines are now horizontal; drag interaction is vertical (`ns-resize`). `bottomReserve` in `scaleCanvas` no longer includes histogram height. `_histVminY`/`_histVmaxY` replace old `_histVminX`/`_histVmaxX` for hit-testing. Smoke: scenarios 54, 55, 60.
+- **axes-colormap-color**: Axis arrow indicators (`.axes-indicator`) now use a colormap-specific color instead of sampling canvas brightness. `gray` colormap → `var(--active-dim)` theme yellow; known colormaps (viridis, plasma, magma, inferno, hot, cool, RdBu_r/RdBu, bwr, seismic, coolwarm, jet, turbo, PiYG, PRGn) → a Nord/pastel color not present in that colormap; custom/unknown → white. `refreshAxesColor()` is also called on `c` and `C` (colormap change) key presses. Smoke: scenario 50.
+- **welcome-hint-text**: Welcome hint and empty-hint now show `{cmd,ctrl,shift}+o · drop to open array` (plain ASCII, no platform-specific unicode). Help overlay updated to mention `Ctrl+O, Shift+O` alongside `Cmd+O`.
+- **vscode-tmux-detection**: `_find_vscode_ipc_hook()` uses two tmux fallback strategies when `TERM_PROGRAM=tmux`. Strategy 1: `tmux show-environment VSCODE_IPC_HOOK_CLI` (works if the variable is in tmux's tracked env). Strategy 2: `tmux display-message -p '#{session_id}'` to get the current session, then `tmux list-clients -t <session_id> -F '#{client_pid}'` to enumerate ALL clients for that session, then reads each client's environment via `ps ewwww`. This correctly handles multiple attached clients (e.g. shared sessions, session created outside VS Code then attached from VS Code terminal). Scoping to the current session prevents false-positive detection from a VSCODE_IPC_HOOK_CLI belonging to a different VS Code window in another tmux session. See `invocation-consistency` skill for full tmux process-tree explanation.
+- **picker-fix**: Removed duplicate stale `showUnifiedPicker` definition that was left by the picker-rewrite commit. The old version (second in the file) referenced undefined `_UNI_MODES`/`_UNI_LABELS`/`_UNI_COLORS` constants, causing a `TypeError` crash every time the picker was opened. Also removed the duplicate `getCompareCandidates` and old `enterComparePrompt` that used the superseded return format.
+- **compare-pane-ordering**: Fixed wrong visual order and wrong pane names for 3/4-array compare. Root cause: `.compare-secondary` had CSS `order: 2` while `.compare-tertiary`/`.compare-quaternary` had no `order` (defaulting to `0`), so in a 3-pane compare the tertiary pane appeared before secondary. Fix: `applyCompareLayout()` now explicitly sets `pane.style.order = idx` overriding all class-based CSS orders. Also fixed drag-reorder to sync `_compareExplicitSids` when swapping panes.
+- **native-window-tabs**: Fixed multiple pywebview windows spawning when calling `view()` more than once from a CLI script or Julia. Root cause (subprocess path): `/load` POST was missing `notify=True`, so `_notify_shells` was never called server-side and a new shell window was always opened. Fix: add `"notify": True` to the `/load` POST; if `result["notified"]` is True the tab was injected and no new window is opened. Also fixed the in-process `view()` path: `run_coroutine_threadsafe(_notify_shells(...))` result was previously ignored — if no shell socket was connected (window closed/crashed) no new window was opened. Fix: wait for the future result (3 s timeout); if `notified=False`, open a fresh native window.
+- **histogram-in-colorbar**: Replaced the separate left-side histogram strip (`W` key toggle, `#hist-wrap`/`#hist-canvas`) with an integrated histogram that lives inside the colorbar. The colorbar is normally 8px tall; on mouse hover it smoothly expands to 40px, auto-fetches histogram data for the current slice, and draws colormap-colored bars growing upward from the gradient strip. Vertical vmin/vmax clim lines (yellow) appear when expanded and can be dragged horizontally (`ew-resize`). Hovering over the expanded colorbar shows a single-value tooltip. On mouse leave, the colorbar collapses back to 8px after a 200ms delay. The `W` key shortcut and help overlay entry have been removed. Histogram data is cached per slice and lazily re-fetched when the slice changes while expanded. Disabled in compare and RGB modes. Smoke: scenarios 54, 55.
+- **lebesgue-mode**: `w` key toggles Lebesgue integral mode. When active, the colorbar stays expanded; hovering over a histogram bin highlights all canvas pixels whose raw data values fall in that bin. Non-matching pixels are dimmed with a semi-transparent dark overlay on `#lebesgue-canvas`. The hovered bin is outlined in yellow on the histogram. A new `/lebesgue/{sid}` endpoint returns the raw 2-D slice as float32 binary (fetched once per slice, cached client-side) for per-pixel bin lookup without server round-trips. Disabled in compare and RGB modes. Smoke: scenario 61.
+- **compare-qmri**: Pressing `q` while in compare mode enters a combined compare-qMRI view: rows = compared arrays (up to 4), columns = parameter maps. Compact mode (T₁, T₂, |PD| only) is triggered by pressing `q` again when n>3; `q` once more exits. State: `compareQmriActive`, `compareQmriViews`, `compareQmriSids`, `compareQmriDim`. Render pipeline mirrors `qvRender` but uses each view's `sid`. Layout: `compareQmriScaleAllCanvases()` fits the grid into the viewport with column headers (`.cq-header-label`) and row labels (`.cq-row-label`). Per-pane slim colorbars via `drawCqSlimCb`. Smoke: scenario 62.
+- **compare-multiview**: Pressing `v` (or `V`) while in compare mode enters a combined compare × 3-plane view: rows = compared arrays (up to 4), columns = Axial/Coronal/Sagittal planes (using `defaultMultiViewDims()`). `v` again exits back to compare mode. State: `compareMvActive`, `compareMvViews`, `compareMvSids`, `compareMvDims`. Render pipeline uses per-view `dimX`/`dimY`/`sliceDir` — same message format as `mvRender` but with per-row `sid`. Layout: `compareMvScaleAllCanvases()` mirrors `compareQmriScaleAllCanvases()`. Per-pane slim colorbars via `drawCmvSlimCb` (delegates to `drawQvSlimCb`). Canvas wheel scrubs the slice along `sliceDir`. `exitCompareMode()` calls `exitCompareMv()` if active. Zoom, resize, scrollbar, border key, and egg positioning all handle `compareMvActive`. Smoke: scenario 63.
+- **ui-text-sizing**: Increased font sizes across the viewer: `#array-name` 11→13px; `#slim-cb-labels`/`#mv-cb-labels` 11→13px; `.qv-label`/`.cq-header-label` 14→16px; `.qv-cb-labels`/`.compare-pane-cb-labels` 9→11px. Row labels in compare-qMRI and compare-multiview (`.cq-row-label`) rotated 90° CCW (`writing-mode: vertical-rl; transform: rotate(180deg)`) to a narrow 24px-wide vertical strip, centered in the row. `.cq-header-row` `padding-left` removed (was a hack for the old horizontal label width). `.qv-row` `align-items` changed from `flex-start` to `center`.

arrayview-0.5.1/CHUNK_PLAN.md

@@ -0,0 +1,179 @@
+# Chunked Large-Array Support Plan (NumPy + Zarr)
+
+## 1. Considerations First
+
+### 1.1 Product goals
+- Keep `arrayview` smooth for arrays from a few GB up to tens of GB.
+- Preserve current behavior for existing users and formats.
+- Avoid regressions across local CLI, Python API, Jupyter, VS Code local, and VS Code remote/tunnel.
+
+### 1.2 User interaction model (drives chunk strategy)
+- Primary interaction is 2D slice viewing with scroll on one axis.
+- Secondary interactions are axis swaps, playback along slice dimension, compare mode, and overlay/vectorfield display.
+- Latency sensitivity:
+1. First frame should appear quickly.
+2. Scroll should feel continuous.
+3. Playback should degrade gracefully (lower FPS) instead of stalling UI.
+
+### 1.3 Technical constraints in current codebase
+- `.npy` already uses `np.load(..., mmap_mode="r")`.
+- Slice extraction is already on-demand and cached.
+- Some features force broad materialization and can blow memory/latency on huge data:
+1. FFT path materializes full array.
+2. Grid/GIF operations stack many slices.
+3. Full preload is skipped above estimated threshold.
+- Current cache limits are fixed, not adaptive.
+- Frontend loading overlay is mostly initial-load UX, not per-slice latency UX.
+
+### 1.4 Performance constraints to explicitly target
+- Storage variability: NVMe vs network filesystems.
+- CPU variability: decompression cost vs I/O savings.
+- Memory ceilings: avoid unbounded growth in session/cache paths.
+
+### 1.5 Format strategy constraints
+- Must support both classic NumPy pipelines and chunked pipelines.
+- Do not force migration to Zarr for all users.
+- Large-array users need a documented and predictable “best path.”
+
+### 1.6 Non-negotiables
+- No regressions in VS Code Simple Browser and remote/tunnel routing behavior.
+- No manual cleanup burden.
+- Keep local workflows simple (`arrayview file.npy` continues to work).
+
+## 2. Architecture Direction
+
+### 2.1 Dual-path data access model
+- Path A: `.npy` + memmap for straightforward lazy reads with low complexity.
+- Path B: `.zarr` for interaction-optimized chunked access and better random slicing behavior.
+
+### 2.2 Recommended workload mapping
+- Use `.npy` when:
+1. Access is mostly sequential in a predictable dimension.
+2. Dataset size is large but still performs acceptably with memmap on local fast disk.
+- Use `.zarr` when:
+1. Users frequently swap axes and jump around.
+2. Datasets are tens of GB and smooth random slice access matters.
+3. Storage is remote or high-latency.
+
+### 2.3 Chunking design principle
+- Chunk to match interaction, not mathematical symmetry.
+- Keep displayed dimensions broad, scrolled dimension shallow.
+- Initial target chunk byte size: 1-8 MB uncompressed (allow up to ~16 MB on fast systems).
+
+## 3. Detailed Execution Plan
+
+## Phase 0: Baseline and Logging
+- Create `LOG_LARGE_ARRAYS.md`.
+- Record each attempt with hypothesis, change, result, decision.
+- Build representative benchmark set:
+1. 3D scalar volume.
+2. 4D volume/time or channel data.
+3. Large compare use case (2-3 arrays).
+4. One remote filesystem scenario if available.
+- Capture baseline metrics for current main branch:
+1. First-frame latency.
+2. p50/p95 scroll latency.
+3. Playback FPS.
+4. Peak RSS and cache bytes.
+5. CPU utilization during scroll/playback.
+
+## Phase 1: Define and Document Chunk Presets
+- Specify chunk presets by shape archetype:
+1. 3D volume `(Y, X, Z)`: example `(512, 512, 1)` or `(1024, 1024, 1)` depending on pixel size.
+2. 4D `(Y, X, Z, T)`: example `(512, 512, 1, 2-4)`.
+3. If T-playback is dominant, increase T depth and reduce XY chunk if needed.
+- Define compression defaults for Zarr:
+1. Start with lightweight compressor to minimize decode stalls.
+2. Keep option for no compression when storage is very fast and CPU is constrained.
+- Add clear guidance in docs:
+1. “When to keep `.npy`.”
+2. “When to convert to `.zarr`.”
+3. “How to pick chunk shapes by interaction.”
+
+## Phase 2: User-Facing Conversion Workflow
+- Add a documented conversion recipe from `.npy`/NIfTI to `.zarr`.
+- Include optional rechunk step and examples per shape archetype.
+- Include verification checklist:
+1. Shape/dtype parity.
+2. Slice value parity spot checks.
+3. Compression ratio and resulting storage size.
+
+## Phase 3: Runtime Behavior Improvements for Large Arrays
+- Add per-slice “loading” indicator behavior:
+1. Only show when render exceeds a small threshold to avoid flicker.
+2. Hide immediately on frame receipt.
+- Keep latest-request-wins behavior to avoid queue buildup while scrolling.
+- Add bounded neighbor prefetch:
+1. Direction-aware (`+/-` around current index).
+2. Respect strict memory budget.
+3. Auto-throttle when latency rises.
+
+## Phase 4: Guardrails for Heavy Operations
+- Add explicit large-array guardrails/warnings for:
+1. FFT.
+2. GIF/grid generation.
+3. Full-dimension preloads.
+- Offer safe fallback behavior:
+1. Cancel heavy action with clear status message.
+2. Allow explicit override for advanced users.
+
+## Phase 5: Cache Policy and Memory Budgeting
+- Make cache budgets configurable (env var or settings).
+- Add optional adaptive defaults based on detected RAM.
+- Define hard ceilings per session and total process budget.
+- Improve visibility:
+1. Debug endpoint or logs for cache hit/miss and byte usage.
+2. Include prefetch hit rate and eviction churn metrics.
+
+## Phase 6: Validation and Regression Testing
+- Extend automated tests:
+1. API tests for `.zarr` and `.npy` parity on slice outputs.
+2. Browser tests for loading indicator behavior under artificial delay.
+3. Tests for guardrail behavior on large synthetic shapes.
+- Run validation matrix:
+1. Local CLI.
+2. Python `view(arr)` and `view(zarr_array)`.
+3. Jupyter inline.
+4. VS Code terminal local.
+5. VS Code remote/tunnel.
+- Add manual smoke checklist for large arrays:
+1. Scroll responsiveness.
+2. Axis swap responsiveness.
+3. Compare mode with large datasets.
+4. No orphan server processes after close.
+
+## Phase 7: Rollout Strategy
+- Release as staged rollout:
+1. Documentation + conversion first.
+2. UX/caching/prefetch improvements next.
+3. Guardrails + configurability final.
+- Add release notes with:
+1. Recommended format by dataset profile.
+2. Known tradeoffs.
+3. Tuning checklist for advanced users.
+
+## 4. Acceptance Criteria
+- Large dataset workflows (tens of GB) function without OOM in normal slice navigation.
+- p95 scroll latency meets target in benchmark environments.
+- First-frame latency remains acceptable on both `.npy` memmap and `.zarr`.
+- No regressions in VS Code local/remote opening behavior.
+- Heavy operations are clearly bounded or warned when unsafe.
+
+## 5. Risks and Mitigations
+- Risk: Bad chunk shapes cause many-chunk reads and stutter.
+- Mitigation: Presets + benchmark-driven tuning + documented heuristics.
+
+- Risk: Compression improves I/O but hurts CPU latency.
+- Mitigation: Offer lightweight/no-compression profiles and measure p95 latency.
+
+- Risk: Prefetch increases memory pressure.
+- Mitigation: Hard prefetch budget and eviction policy.
+
+- Risk: Feature regressions in compare/overlay paths.
+- Mitigation: Targeted integration tests for those modes with large arrays.
+
+## 6. Open Decisions (to resolve before implementation)
+- Final latency targets per environment (local NVMe vs remote FS).
+- Default chunk presets per modality/workflow.
+- Default compressor settings.
+- Whether large-array guardrails are soft warnings or hard blocks by default.