arrayview 0.27.0__tar.gz → 0.28.0__tar.gz

{arrayview-0.27.0 → arrayview-0.28.0}/.agents/skills/invocation-consistency/SKILL.md

@@ -20,14 +20,16 @@ Every behavior that depends on *how* arrayview is started (server lifecycle, bro
 | **VS Code terminal** | `arrayview()` or `view()` | VS Code Simple Browser | in-process or subprocess |
 | **Plain SSH (no VS Code)** | `arrayview()` or `view()` | prints port-forward hint | in-process or subprocess |
 
-## Transport Split
+## Transport
 
-ArrayView has two backend transports. Invocation-sensitive fixes must account for both:
+ArrayView uses one viewer backend transport:
 
 - **Network mode**: FastAPI routes and WebSocket server. File registration goes through `/load` in `_routes_loading.py`; spawned CLI sessions load in `_launcher._serve_daemon()`.
-- **VS Code direct mode**: stdio subprocess. VS Code tunnel launches write a signal file; the extension runs `python -m arrayview --mode stdio <file>`, and file registration goes through `_stdio_server._handle_register()`.
 
-Do not assume a `/load` or daemon fix covers VS Code tunnel. Shared behavior such as file-format key selection belongs in `_io.py` helpers and must be used by both transports.
+VS Code local and remote/tunnel sessions both use signal-file opening plus the
+HTTP/WebSocket viewer. Shared behavior such as file-format key selection belongs
+in `_io.py` helpers and must be used by `/load`, daemon startup, and in-process
+session creation.
 
 ## Key Detection Functions (all in `_platform.py`)
 
@@ -98,8 +100,6 @@ for pid_str in client_pids:
 2. **File/session registration consistent?**
    - FastAPI `/load` path handles the feature
    - CLI spawned daemon path handles the feature
-   - VS Code direct stdio `_handle_register()` path handles the feature
-   - Direct `--mode stdio <file>` CLI path handles the feature
    - Multi-array/default-key behavior is centralized in `_io.py`
 
 3. **Browser/display opening?**
@@ -127,8 +127,8 @@ uv run python -c "from arrayview import view; import numpy as np; view(np.zeros(
 ## Red Flags — STOP
 
 - "I changed server startup but only tested CLI" → test all paths
-- "I fixed `/load` but not `_stdio_server.py`" → VS Code tunnel can still be broken
-- "I fixed `_serve_daemon()` but `--diagnose` says `is_vscode_remote: true`" → tunnel uses stdio direct mode, not the daemon
+- "I fixed `/load` but not daemon startup" → spawned CLI sessions can still be broken
+- "I fixed `_serve_daemon()` but `--diagnose` says `is_vscode_remote: true`" → verify the tunnel signal-file, port exposure, and `asExternalUri` path too
 - "Works locally but not in tunnel" → check `_is_vscode_remote()` path and port exposure
 - "I used `127.0.0.1` in the URL" → use `localhost`
 - "I fixed tmux with `#{client_pid}`" → only works with one client; use `list-clients`

arrayview-0.28.0/.mex/ROUTER.md

@@ -0,0 +1,62 @@
+---
+name: router
+description: Entry point for task routing, project non-negotiables, and behavioral guardrails. Start here, then load only the minimum extra context a task needs.
+last_updated: 2026-07-01
+---
+
+# arrayview — Router
+
+Python package for interactively viewing multi-dimensional arrays (numpy, NIfTI, zarr, …) with a FastAPI backend, single-file HTML/JS frontend, and multi-environment display routing (Jupyter, VS Code, SSH, native window).
+
+## Non-Negotiables
+
+- Never split `_viewer.html` — entire frontend is one self-contained file, no build step.
+- All heavy imports (numpy, matplotlib, nibabel, FastAPI, uvicorn) must be lazy — CLI fast path stays near-zero cost.
+- New rendering features must be consistent across all six invocation environments.
+- Global state lives in `_session.py` only — `SESSIONS`, `SERVER_LOOP`, `VIEWER_SOCKETS` never redefined elsewhere.
+- Render thread must remain a raw `threading.Thread` + `SimpleQueue`, not `concurrent.futures`.
+
+## Context Budget
+
+- Start with this file plus **one context file and/or one pattern file**, loaded only when the task actually needs them.
+- Do **not** reopen this router or already-loaded docs on routine follow-ups in the same thread. Reuse what's loaded unless blocked.
+- When blocked, load **one more** file — do not recursively fan out through second-hop references.
+- For `_viewer.html` follow-ups with a known symbol: go straight to an exact `rg` search and a narrow code read. Do **not** auto-load `context/frontend.md`.
+- For UI behavior, animation, or UX-expectation tasks: ask a plain-English clarification question **before** reading git history, large diffs, or broad source sweeps.
+- Normal work never loads `.mex/SETUP.md`, `.mex/SYNC.md`, or `patterns/README.md` — those are scaffold-maintenance files.
+
+## Where to Look
+
+Load only the file(s) matching the task. One is usually enough.
+
+| Task | File |
+|------|------|
+| Current shipped / in-progress status | `context/project-state.md` |
+| System architecture, component connections | `context/architecture.md` |
+| Startup, shutdown, display ownership, orphans, VS Code tabs, session release | `context/lifecycle.md` |
+| Specific technology / library choices | `context/stack.md` |
+| Code patterns when writing or reviewing | `context/conventions.md` |
+| Why something is built the way it is / a new architectural choice | `context/decisions.md` |
+| First-time dev environment setup | `context/setup.md` |
+| `_viewer.html` — modes, reconcilers, command registry, View Component System | `context/frontend.md` (+ `patterns/frontend-change.md` if changing code) |
+| Rendering, colormaps, LUTs, caching, render thread | `context/render-pipeline.md` |
+| Any task — scan for a matching pattern first | `patterns/INDEX.md` |
+| Adding a file format | `patterns/add-file-format.md` |
+| Adding a server route / WebSocket endpoint | `patterns/add-server-endpoint.md` |
+| Visual bugs / render artifacts | `patterns/debug-render.md` |
+| Verifying animation changes (frame captures) | `patterns/animation-verify.md` |
+| Design philosophy, new features, mode additions, interaction model | `../DESIGN.md` |
+
+## Commands
+
+- Test: run `uv run pytest` against `tests/`
+- Visual smoke: run `uv run python` on `tests/visual_smoke.py`
+- CLI: `uvx arrayview <file>`
+- Build: `uv build`
+- Drift check: `mex check --quiet`
+
+## After Completing a Task
+
+- [ ] Update `context/project-state.md` if shipped or in-progress status changed.
+- [ ] Update any stale `.mex/context/` or `.mex/patterns/` files touched by the task.
+- [ ] If this revealed a repeatable workflow, add or update a pattern in `.mex/patterns/`.

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/context/architecture.md

@@ -30,13 +30,12 @@ last_updated: 2026-06-11
 ```
 CLI / Python API (view() or uvx arrayview <file>)
   └─ _launcher.py  →  FastAPI server (_server.py + _routes_*.py, uvicorn)   [network mode]
-                    →  _stdio_server.py                        [VS Code direct webview]
 
-Server (either mode)
+Server
    ├─ _session.py   Session objects, global state, render thread, caches
    ├─ _render.py    extract_slice → apply_complex_mode → render_rgba → PNG pipeline
    ├─ _analysis.py / _diff.py / _overlays.py / _vectorfield.py
-   │                Shared helpers used by FastAPI and stdio transports
+   │                Shared helpers used by route modules and WebSocket handlers
    └─ _io.py        load_data() — npy/npz/nii/zarr/h5/mat/tif/pt routing
 
 Browser (_viewer.html — single self-contained HTML+JS+CSS file)
@@ -47,7 +46,7 @@ Browser (_viewer.html — single self-contained HTML+JS+CSS file)
 
 A `view()` call creates a `Session`, starts the FastAPI server if not running,
 registers the session via HTTP POST `/load`, then opens a display for the detected
-environment (Jupyter inline, VS Code webview panel or direct webview, native
+environment (Jupyter inline, VS Code webview panel, native
 pywebview, or system browser).
 
 ## Key Components
@@ -57,12 +56,11 @@ pywebview, or system browser).
 - **`_routes_*.py`** — Feature-route modules grouped by domain (analysis, loading, persistence, segmentation, state, query, export, preload, vectorfield, rendering, websocket transport). Each module exposes `register_*_routes(app, ...)` and keeps `_server.py` focused on assembly and shared dependencies.
 - **`_session.py`** — Single source of global mutable state: `SESSIONS`, `SERVER_LOOP`, `VIEWER_SOCKETS`, `VIEWER_SIDS`, `SHELL_SOCKETS`. Owns the render thread (`_RENDER_QUEUE`, `_RENDER_THREAD`), prefetch pool, and the `Session` class with its three LRU caches.
 - **`_render.py`** — Stateless rendering functions: `extract_slice()`, `apply_complex_mode()`, `render_rgba()`, `render_rgb_rgba()`, `render_mosaic()`, `extract_projection()`. Owns colormap LUTs (`LUTS` dict, lazy-initialized by `_init_luts()`). Also provides `_build_mosaic_grid()` (shared grid builder) and `_evict_lru()` (shared cache eviction).
-- **`_imaging.py`** — Shared lazy PIL accessors (`ensure_image()`, `ensure_imageops()`) used by `_diff`, `_server`, `_routes_rendering`, `_routes_websocket`, `_stdio_server`.
-- **`_analysis.py`, `_diff.py`, `_overlays.py`, `_vectorfield.py`** — Shared backend helpers for metadata, analysis endpoints, compare/diff rendering, overlay compositing, vector field validation, and arrow sampling. Imported by both `_server.py` and `_stdio_server.py`.
+- **`_imaging.py`** — Shared lazy PIL accessors (`ensure_image()`, `ensure_imageops()`) used by `_diff`, `_server`, `_routes_rendering`, and `_routes_websocket`.
+- **`_analysis.py`, `_diff.py`, `_overlays.py`, `_vectorfield.py`** — Shared backend helpers for metadata, analysis endpoints, compare/diff rendering, overlay compositing, vector field validation, and arrow sampling.
 - **`_io.py`** — All file-format loading behind `load_data(filepath)`. Lazy nibabel import for NIfTI. Handles `.npy`, `.npz`, `.nii` and `.nii.gz`, `.zarr`, `.zarr.zip`, `.pt` and `.pth`, `.h5` and `.hdf5`, `.tif` and `.tiff`, `.mat`. Extensions registered in `_SUPPORTED_EXTS`.
 - **`_platform.py`** — Environment detection: checks jupyter → vscode → julia → ssh → terminal in priority order. Results cached. Never short-circuit this order.
-- **`_vscode.py`** — VS Code integration facade. Submodules: `_vscode_extension.py` (install), `_vscode_signal.py` (signal-file IPC), `_vscode_shm.py` (shared-memory transport), `_vscode_browser.py` (browser/SSH guidance).
-- **`_stdio_server.py`** — Alternative to FastAPI for VS Code tunnel (direct webview): JSON on stdin, length-prefixed binary on stdout.
+- **`_vscode.py`** — VS Code integration facade. Submodules: `_vscode_extension.py` (install), `_vscode_signal.py` (signal-file IPC), `_vscode_browser.py` (browser/SSH guidance).
 - **`_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
@@ -83,7 +81,7 @@ Tool launch, tool activation, and drawer visibility are separate states.
 |---|---|---|
 | Jupyter | Inline iframe | network |
 | VS Code local | Webview panel | network |
-| VS Code tunnel | Direct webview (stdio) | stdio |
+| VS Code tunnel | Webview panel (forwarded WebSocket) | network |
 | Julia | System browser | network |
 | CLI / Python script | Native pywebview | network |
 | SSH terminal | Prints URL — user forwards port with `ssh -L` | network |
@@ -96,8 +94,7 @@ File parsing belongs in `_io.py`, but session registration happens through diffe
 
 - **Network `/load`**: existing FastAPI server path in `_routes_loading.py`.
 - **Spawned CLI daemon**: `_launcher._serve_daemon()` loads before publishing the pending session.
-- **VS Code tunnel direct webview**: `_stdio_server._handle_register()` handles `python -m arrayview --mode stdio <file>` spawned by the extension.
-- **Direct stdio CLI mode**: `_launcher.arrayview()` preloads positional files before starting `run_stdio_server()`.
+All file registration paths use either FastAPI `/load`, spawned daemon startup, or in-process `Session` creation. Keep format-specific key filtering/default selection in `_io.py` helpers so every launch path sees the same behavior.
 
 For multi-array formats or formats with non-displayable members, keep key filtering/default selection in `_io.py` helpers and call those helpers from every registration path. A fix in `/load` alone does not cover VS Code tunnel.
 

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/context/conventions.md

@@ -18,7 +18,7 @@ edges:
     condition: when applying frontend conventions (section separators, reconcilers, command registry)
   - target: context/render-pipeline.md
     condition: when applying render pipeline conventions (pipeline order, cache patterns, LUT usage)
-last_updated: 2026-06-19
+last_updated: 2026-07-01
 ---
 
 # Conventions
@@ -34,11 +34,11 @@ last_updated: 2026-06-19
 ## Structure
 
 - **Lazy imports everywhere** — any import that costs >10 ms must be deferred. Pattern: module-level `_cache = None` + accessor function (see `_server_mod()`, `_uvicorn()`, `_nib()`, `_init_luts()`). The CLI fast path (server already running) must stay near-zero cost.
-- **Global state lives in `_session.py`** — `SESSIONS`, `SERVER_LOOP`, `VIEWER_SOCKETS`, `SHELL_SOCKETS`. Other modules import these by name, never redefine them.
+- **Global state lives in `_session.py`** — `SESSIONS`, `SERVER_LOOP`, `SERVER_PORT`, `VIEWER_SOCKETS`, `VIEWER_SIDS`, `VIEWER_SID_COUNTS`, `VIEWER_CONNECTIONS_SEEN`, `SHELL_SOCKETS`, `PENDING_SESSIONS`, `PENDING_SESSION_EVENTS`, `_window_process`, plus the render pool (`_RENDER_QUEUE`, `_RENDER_THREADS`, `_RENDER_WORKERS`). Other modules import these by name, never redefine them.
 - **Render pipeline is pure functions** — `_render.py` exports stateless functions that take `session` + parameters. No class hierarchy.
 - **One HTML file for the entire frontend** — all CSS and JS live in `_viewer.html`. Do not split into separate files.
 - **Tests live in `tests/`** — not next to source files. Visual/browser tests use playwright and are marked `@pytest.mark.browser`.
-- **All file-format loading goes through `_io.load_data(filepath)`** — no direct format imports in `_server.py` or `_launcher.py`.
+- **All file-format loading goes through `_io.py`** — `load_data_with_meta(filepath, key=None, select=None)` is the canonical primary-load path (returns `(data, spatial_meta)` and is what `_launcher.py` uses). `load_data(filepath, key=None)` still exists for loads that don't need spatial metadata. No direct format imports in `_server.py` or `_launcher.py`.
 - **Server features usually live in `_routes_*.py`** — keep `_server.py` as the assembly layer unless the route is tiny infrastructure.
 
 ## Patterns
@@ -90,7 +90,7 @@ Always check in this priority order. Never short-circuit.
 Before presenting any code change:
 - [ ] New heavy imports are lazy (wrapped in a `_mod = None` / accessor function pattern)
 - [ ] Any new `Session` field is initialized in `Session.__init__` and cleared in `reset_caches()` if it's cache-related
-- [ ] New file format support goes through `_io.load_data()` and adds the extension to `_SUPPORTED_EXTS`
+- [ ] New file format support goes through `_io.load_data_with_meta()` (and `load_data()`), and adds the extension to `_SUPPORTED_EXTS`
 - [ ] Frontend changes are in `_viewer.html` only — no new JS/CSS files
 - [ ] New rendering functions follow the `extract_slice → apply_complex_mode → apply_colormap_rgba` pipeline order
 - [ ] Environment detection changes go in `_platform.py`, not inline in `_launcher.py` or `_vscode.py`

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/context/decisions.md

@@ -53,13 +53,12 @@ last_updated: 2026-06-19
 **Alternatives considered:** `ThreadPoolExecutor` (rejected — shutdown race); `asyncio.run_in_executor` with default executor (same issue).
 **Consequences:** The prefetch pool *does* use `concurrent.futures.ThreadPoolExecutor` (it submits non-critical background work and gracefully handles `RuntimeError` on shutdown). Only the critical render path must stay on `SimpleQueue`.
 
-### stdio transport for VS Code tunnel (direct webview)
+### VS Code tunnel uses forwarded WebSocket transport
 **Date:** 2024
-**Status:** Active
-**Decision:** When a VS Code tunnel is detected, `_stdio_server.py` replaces FastAPI+WebSocket. Messages are JSON on stdin, length-prefixed binary on stdout. The VS Code extension bridges `postMessage` ↔ subprocess stdio.
-**Reasoning:** VS Code tunnel environments block arbitrary TCP ports. The Direct WebView API bypasses the network entirely by running the viewer as a subprocess of the extension. This gives reliable display without requiring port forwarding.
-**Alternatives considered:** Port forwarding via VS Code tunnel (rejected — unreliable, depends on tunnel configuration); WebSocket over stdio tunnel (rejected — more complex than length-prefixed binary).
-**Consequences:** `_stdio_server.py` must mirror every route and feature of `_server.py`. New server features must be implemented in both. The `_vscode.py` signal-file and shared-memory IPC are part of this same display path.
+**Status:** Superseded
+**Decision:** Older tunnel builds used a now-removed stdio-based server module and direct webview `postMessage` IPC to avoid unreliable forwarded ports. Current builds use the same FastAPI/WebSocket transport as local VS Code and have the extension expose/promote the tunnel port before opening the tab.
+**Reasoning:** The direct transport duplicated every server feature and created drift between FastAPI and stdio behavior. The VS Code port-forwarding path is now reliable enough to make one transport simpler and easier to test.
+**Consequences:** New viewer features only need the FastAPI routes/WebSocket path; the VS Code extension remains responsible for signal-file routing, external URI resolution, and port privacy.
 
 ### ROI in qMRI uses per-pane overlay canvases, not a shared overlay
 **Date:** 2026-04-16

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/context/frontend.md

@@ -18,7 +18,7 @@ edges:
     condition: when writing new frontend code and need section separator conventions
   - target: patterns/frontend-change.md
     condition: when making a concrete change to _viewer.html
-last_updated: 2026-06-05
+last_updated: 2026-07-01
 ---
 
 # Frontend (_viewer.html)
@@ -46,7 +46,7 @@ For a small follow-up tweak, prefer exact code search in `_viewer.html` and skip
 - Section separators: `/* ── Section Name ── */` in CSS, `// ── Section Name ──` in JS
 - Reconcilers: grep `UI Validation and Reconciliation`, `_reconcileUI`, `_reconcileLayout`
 - Keybinds/help: grep `commands`, `keybinds`, `GUIDE_TABS`, `dispatchCommand`
-- Mode system: grep `Mode Registry`, `modeManager`, `enterMultiView`, `enterCompare`, `enterQmri`
+- Mode system: grep `Mode Registry`, `modeManager`, `enterMultiView`, `enterCompareModeBySid`, `enterQmri`
 - Layout/scale: grep `scaleCanvas`, `mvScaleAllCanvases`, `compareScaleCanvases`, `qvScaleAllCanvases`
 - Colorbars: grep `ColorBar class`, `drawSlimColorbar`, `drawMvColorbar`
 
@@ -73,7 +73,7 @@ For a small follow-up tweak, prefer exact code search in `_viewer.html` and skip
 
 - **Reconcilers** — UI visibility/state should converge here after mode changes
 - **Command registry** — `commands`, `keybinds`, `dispatchCommand`, `GUIDE_TABS`
-- **View component system** — `View`, `Slicer`, `Layer`, `LayoutStrategy`, `modeManager`; still coexists with legacy rendering
+- **View component system** — `View`, `Slicer`, `LayoutStrategy`, `modeManager`, plus concrete layer classes `VectorFieldLayer`, `OverlayLayer`, `CrosshairLayer`; still coexists with legacy rendering
 - **Dual-write state** — when legacy globals are changed, matching `displayState` fields may need updating too
 - **Manual range state** — `manualVmin` / `manualVmax` and per-view locked ranges are real state, not derived UI
 - **Tool menu and dynamic island** — central owners for several multi-feature UI surfaces; touch deliberately

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/context/lifecycle.md

@@ -28,11 +28,10 @@ This contract describes who owns the backend, when it starts, and what closes it
 | Invocation | Display owner | Backend model | Shutdown/release |
 |---|---|---|---|
 | Local VS Code CLI `arrayview file.npy` | VS Code URL webview panel | Shared transient daemon | Panel close releases URL sessions; last viewer WebSocket close stops daemon |
-| VS Code file click/custom editor | VS Code extension | Extension-owned stdio subprocess | Panel close kills subprocess |
 | Plain Python script `view(arr)` | Browser/native/VS Code display | Non-daemon background server thread | Survives caller until viewer connects then closes |
 | Jupyter `view(arr)` | Notebook kernel inline iframe | Kernel-owned daemon server thread | Iframe disappearance must not hard-kill backend |
 | Julia/PythonCall | Browser/VS Code route from subprocess | Detached subprocess | Never in-process; avoid GIL deadlock |
-| Remote/tunnel | VS Code direct webview when possible | stdio direct webview or intentional persistent server | Persistence allowed only when transport requires it |
+| Remote/tunnel | VS Code URL webview panel | Forwarded WebSocket server | Persistent only when `--serve` or tunnel ownership requires it |
 | Plain SSH | User-forwarded localhost URL | Transient server unless `--serve` requested | Viewer close ends transient session |
 
 ## Local VS Code CLI
@@ -43,13 +42,6 @@ This contract describes who owns the backend, when it starts, and what closes it
 - Closing the last viewer tab should stop the transient daemon.
 - The VS Code wrapper must not show "backend unavailable" based on a webview-side `fetch()`; backend health checks belong in the extension host.
 
-## VS Code File Click And Custom Editor
-
-- Prefer direct extension-owned stdio subprocesses.
-- Do not require localhost or a shared port when direct mode is available.
-- Closing the tab should terminate the subprocess.
-- This path is transient and owned by the extension session, not by a long-lived server.
-
 ## Python Script
 
 - `view(arr)` from a script should survive the script exiting.
@@ -66,8 +58,8 @@ This contract describes who owns the backend, when it starts, and what closes it
 
 ## Remote, Tunnel, And SSH
 
-- Remote or tunnel launches may persist when `--serve` or direct-server constraints require it.
-- Direct VS Code tunnel display should prefer stdio direct webview to avoid forwarded-port auth and public-port setup.
+- Remote or tunnel launches may persist when `--serve` or tunnel display ownership requires it.
+- VS Code tunnel display uses forwarded localhost URLs; the extension should configure the port, promote privacy when available, and resolve the URL with `asExternalUri`.
 - With multiple registered tunnel windows, a missing or stale `ARRAYVIEW_WINDOW_ID` must fail closed with a diagnostic rather than broadcasting to whichever window is focused.
 - An exact registered `ARRAYVIEW_WINDOW_ID` wins; do not redirect it to a newer same-parent registration because live tunnel windows can share ancestry.
 - Plain SSH should use `localhost` forwarding guidance and stay transient unless a shared server was explicitly requested.

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/context/project-state.md

@@ -7,7 +7,7 @@ triggers:
   - "recent work"
   - "active feature"
   - "shipped recently"
-last_updated: 2026-06-05
+last_updated: 2026-06-30
 ---
 
 # Project State
@@ -15,12 +15,13 @@ last_updated: 2026-06-05
 ## Working
 
 - CLI (`uvx arrayview file.npy`) and Python API (`view(arr)`) — both stable
-- Display environments: Jupyter inline, VS Code local, VS Code tunnel (stdio), Julia, native pywebview, SSH URL print (user forwards port with `ssh -L`)
+- Display environments: Jupyter inline, VS Code local, VS Code tunnel via forwarded WebSocket, Julia, native pywebview, SSH URL print (user forwards port with `ssh -L`)
 - File formats: `.npy`, `.npz`, `.nii`/`.nii.gz`, `.zarr`, `.h5`/`.hdf5`, `.mat`, `.tif`/`.tiff`, `.pt`/`.pth`
 - Rendering pipeline: colormaps, complex modes, mosaic, RGB/RGBA, projections, overlays
-- Backend transport parity: FastAPI and stdio now share metadata/analysis helpers, compare/diff helpers, overlay compositing, and vector field layout/arrow sampling via `_analysis.py`, `_diff.py`, `_overlays.py`, and `_vectorfield.py`
+- Backend transport: FastAPI HTTP/WebSocket is the single viewer transport; shared helpers keep route modules small for metadata/analysis, compare/diff, overlay compositing, and vector field layout/arrow sampling.
 - NIfTI spatial metadata, RAS resampling
-- VS Code extension v0.14.4 — stable window ID via `EnvironmentVariableCollection`; `arrayview.openInFloatingWindow` setting moves new tabs to a floating window; `view(arr, floating=True)` and `arrayview file.npy --floating` open in a floating window per-call regardless of global setting; `!vscode.env.remoteName` guard removed (remote VS Code supports floating windows); floating mode now uses a single persistent shell hub panel (`_shell.html`) so all arrays share one floating window as tabs instead of opening separate windows; fixed: second CLI call now injects tab via `new_tab` postMessage relay (extension -> hub wrapper -> shell iframe) instead of relying on WebSocket notify which wasn't sent in VS Code mode; custom-editor fallback now pins `uv` to Python 3.12 so tunnel workspaces with older project interpreters still open arrays
+- NIfTI series: `--stack-nifti DIR` + `--select PATTERN` stacks a directory of same-shape NIfTI files into a lazy 4D/5D array; `view_dir()` Python helper; recursive patient-folder grouping, LRU volume cache, spatial meta from first file
+- VS Code extension v0.14.27 — stable window ID via `EnvironmentVariableCollection`; `arrayview.openInFloatingWindow` setting moves new tabs to a floating window; `view(arr, floating=True)` and `arrayview file.npy --floating` open in a floating window per-call regardless of global setting; remote/tunnel display uses the same forwarded HTTP/WebSocket path as local VS Code; floating mode uses a single persistent shell hub panel (`_shell.html`) so all arrays share one floating window as tabs instead of opening separate windows; second CLI calls inject tabs via `new_tab` postMessage relay (extension -> hub wrapper -> shell iframe)
 - Colorbar refactor: `ColorBar` JS class partially migrated (in progress)
 - Colormap picker: `c` opens an expanded colorbar-island grid without changing the colormap; subsequent `c` taps cycle, hover/hjkl/arrows live-preview, Enter/click commits, Esc cancels, and auto-dismiss pauses while hovered
 - Cold-start loading spinner in VS Code and native shell
@@ -37,7 +38,7 @@ last_updated: 2026-06-05
 - Island collapse affordance: inline `~` at the island's top-right animates the panel into the bottom-left `~` hint circle; external `~` hint only visible while the island is actually collapsed. New `/` hint circle at bottom-right opens the tool menu
 - Compare center tool menu: `/` now re-opens the last-used compare center mode from the tool menu, while compare pane header buttons select diff / overlay / wipe directly. Eligible two-array compare layouts can switch into a big-left arrangement with a wider center pane, and the diff colorbar now matches that center-pane width.
 - Compare center + ortho auto-layout: layout choice is now auto-picked once on entry from a shared viewport-profile helper, stays stable across resize, and becomes sticky only after manual `G` / `g` override. Compare big-left also now supports in-pane A/B source badges and a shared source colorbar parked in the gap between the stacked source panes.
-- Detached compare-on-X: with a single array and a non-spatial active dimension, `X` now enters compare mode by treating two indices from that dimension as A/B sources. Pane titles switch to index-over-total labels, the dimbar marks the detached dimension with a purple `X`, `[` / `]` scrub the left pane index, `{` / `}` scrub the right pane index, and repeated `X` presses cycle the existing compare-center modes before exiting back to normal view. The split-index diff path now works in both FastAPI and stdio transports.
+- Detached compare-on-X: with a single array and a non-spatial active dimension, `X` now enters compare mode by treating two indices from that dimension as A/B sources. Pane titles switch to index-over-total labels, the dimbar marks the detached dimension with a purple `X`, `[` / `]` scrub the left pane index, `{` / `}` scrub the right pane index, and repeated `X` presses cycle the existing compare-center modes before exiting back to normal view. The split-index diff path works through the FastAPI/WebSocket transport.
 
 ## Recently Completed
 

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/context/render-pipeline.md

@@ -20,7 +20,7 @@ edges:
     condition: when writing new render functions or extending the pipeline
   - target: patterns/debug-render.md
     condition: when a render produces wrong output or the wrong cache is hit
-last_updated: 2026-06-19
+last_updated: 2026-07-01
 ---
 
 # Render Pipeline
@@ -34,29 +34,34 @@ Every slice request follows this fixed order. Do not skip steps or reorder.
    → returns float32 2D numpy array (raw slice from ND array)
    → result cached in session.raw_cache (LRU, keyed by (dim_x, dim_y, key_idx))
 
-2. apply_complex_mode(arr, mode)
-   → applies FFT, magnitude, phase, real, imag transforms to complex arrays
-   → skip if data is not complex
+2. _prepare_display(session, raw, complex_mode, dr, log_scale, vmin_override, vmax_override)
+   → calls apply_complex_mode(raw, complex_mode) internally (mag/phase/real/imag)
+   → returns (float32 data, vmin, vmax) — NOT uint8; normalization to [0,255]
+     happens later inside apply_colormap_rgba
 
-3. _prepare_display(arr, vmin, vmax, log_scale)
-   → normalizes to [0, 255] uint8
-
-4. render_rgba(arr_uint8, lut_name) / render_rgb_rgba(arr) / render_mosaic(...)
-   → applies LUT (colormap) → returns RGBA uint8 2D array
+3. render_rgba(session, ...) / render_rgb_rgba(session, ...) / render_mosaic(session, ...)
+   → each takes a session + dims/idx/colormap params (NOT a pre-extracted array),
+     calls extract_slice internally, then applies LUT → RGBA uint8 2D array
    → result cached in session.rgba_cache or session.mosaic_cache
 
-5. PNG encode (Pillow)
-   → sent as binary WebSocket frame
+4. WebSocket binary frame
+   → raw RGBA bytes prefixed by a binary header (seq, w, h as uint32 +
+     vmin, vmax as float32). Pillow PNG encoding is ONLY used by the
+     HTTP export endpoints (e.g. /grid/{sid}), not the live WS render path.
 ```
 
+Note: FFT is NOT part of `apply_complex_mode`. It is a separate data-level
+transform applied in the `/fft/{sid}` endpoint (`_routes_state.py`), which
+mutates `session.data` and stashes the original in `session.fft_original_data`.
+
 ## Colormap LUTs
 
 `LUTS` dict in `_render.py` — maps colormap name → 256×4 uint8 numpy array (RGBA).
 
 - Initialized lazily by `_init_luts()` on first use. Not initialized at import time.
-- Available colormaps: `gray`, `lipari`, `navia`, `viridis`, `plasma`, `magma`, `inferno`, `cividis`, `rainbow`, `RdBu_r`, `twilight_shifted`, plus `RdBu_r_black` (diff mode).
+- Available colormaps: `gray`, `lipari`, `navia`, `viridis`, `plasma`, `magma`, `inferno`, `cividis`, `rainbow`, `RdBu_r`, `twilight_shifted`, `turbo`, plus `RdBu_r_black` (diff mode).
 - `lipari` and `navia` require `qmricolors` to be imported first (done inside `_init_luts()`).
-- To add a colormap: add name to `COLORMAPS` list in `_session.py`, then add LUT construction in `_init_luts()` in `_render.py`. Restart required.
+- To add a colormap: add the name to `COLORMAPS` in `_session.py`. `_init_luts()` iterates `COLORMAPS` and builds each LUT from `matplotlib.colormaps[name]` automatically, so standard matplotlib colormaps need no extra work. Only a custom (non-matplotlib) colormap like `RdBu_r_black` needs manual LUT construction in `_init_luts()`. Env vars are read once at import, so a restart is required.
 
 ## Session Caches
 
@@ -68,7 +73,7 @@ Each `Session` has three LRU caches, all `OrderedDict`:
 | `rgba_cache` | derived | RGBA uint8 tiles | `ARRAYVIEW_RGBA_CACHE_MB` (10% RAM) |
 | `mosaic_cache` | derived | mosaic RGBA | `ARRAYVIEW_MOSAIC_CACHE_MB` (2.5% RAM) |
 
-Cache budgets are computed once at import time from available RAM (via `psutil`). Override per-session via env vars.
+Cache budgets are computed once at module import time from available RAM (via `psutil`), with a 64 MB floor. The env vars below are read once at import — there is no per-session override; changing a value requires a process restart.
 
 LRU eviction pattern:
 ```python
@@ -83,14 +88,14 @@ while session._raw_bytes > session.RAW_CACHE_BYTES and session.raw_cache:
 
 ## Render Thread
 
-`_RENDER_QUEUE: SimpleQueue` in `_session.py`. The render thread (`arrayview-render`, daemon) drains the queue and resolves `asyncio.Future`s on the server event loop.
+`_RENDER_QUEUE: SimpleQueue` in `_session.py`. A pool of `_RENDER_WORKERS = max(2, min(4, os.cpu_count() or 2))` daemon threads (named `arrayview-render-{N}`, tracked in `_RENDER_THREADS`) drains the queue and resolves `asyncio.Future`s on the server event loop. `_ensure_render_thread()` keeps the pool at the configured worker count.
 
 ```python
 await _render(loop, lambda: extract_slice(session, dim_x, dim_y, idx))
 ```
 
 - Never use `asyncio.run_in_executor` for render work — the executor's `_global_shutdown` flag races with daemon thread cleanup.
-- The queue accepts `None` as a sentinel to stop the thread.
+- The queue accepts `None` as a sentinel to stop a worker.
 
 ## Prefetch Pool
 
@@ -99,7 +104,7 @@ Separate 1-thread `ThreadPoolExecutor` (`arrayview-prefetch`). Warms `raw_cache`
 ## Special Array Types
 
 - **RGB arrays** — detected by `_setup_rgb()`. Skip colormap; go directly to `render_rgb_rgba()`. `session.rgb_axis` holds the axis index; `session.spatial_shape` is shape without that axis.
-- **Complex arrays** — `apply_complex_mode()` transforms to real before colormapping. Supported modes: magnitude, phase, real, imag, FFT (various).
+- **Complex arrays** — `apply_complex_mode()` transforms to real before colormapping. Supported modes: magnitude, phase, real, imag. FFT is a separate data-level transform (see note above).
 - **NIfTI** — canonical-reoriented on load by `_load_nifti_with_meta()`. `session.spatial_meta` holds affine, voxel sizes, axis labels. RAS resample cached in `session.resampled_volume`.
 - **Large memmap arrays** — `_default_start_dims_for_data()` may override the default startup axes to avoid high-stride reads.
 

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/context/setup.md

@@ -13,7 +13,7 @@ edges:
     condition: when specific technology versions or library details are needed
   - target: context/architecture.md
     condition: when understanding how components connect during setup
-last_updated: 2026-06-19
+last_updated: 2026-07-01
 ---
 
 # Setup
@@ -29,7 +29,7 @@ last_updated: 2026-06-19
 1. Clone the repo
 2. `uv sync --all-groups` — installs all dependencies including dev and test groups
 3. Run `uv run arrayview` on `debug/cig_meeting_examples/BraTS2021_00009_t1.nii.gz` — smoke test: should open the viewer with a sample array
-4. Run `uv run pytest` on `tests/test_mode_consistency.py` — verify core render consistency passes
+4. Run `uv run pytest` on `tests/test_mode_consistency.py` — verify core render consistency passes (this is a browser-marked suite: run `uv run playwright install chromium` first, see step below)
 
 For browser-based tests (playwright):
 - `uv run playwright install chromium` — one-time browser install
@@ -48,7 +48,7 @@ No `.env` file is needed. All env vars are optional overrides; the server runs w
 - `uv run arrayview <file>` — launch viewer on a file (CLI entry point)
 - `uvx arrayview <file>` — launch from anywhere without activating the venv
 - Run `uv run pytest` on `tests/<target>` — run a specific test file
-- Run `uv run pytest` on `tests/test_mode_consistency.py` — mode consistency suite after render changes
+- Run `uv run pytest` on `tests/test_mode_consistency.py` — mode consistency suite after render changes (browser-marked; requires `uv run playwright install chromium`)
 - Run `uv run python` on `tests/visual_smoke.py` — browser smoke tests (requires playwright)
 - `uv run pytest -m "not browser"` — all non-browser tests
 - `uv build` — build wheel + sdist in the default build output directory

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/patterns/INDEX.md

@@ -28,7 +28,7 @@ Lookup table for all pattern files in this directory. Check here before starting
 | [add-file-format.md](add-file-format.md) | Adding support for a new file format in `_io.py` |
 | [animation-verify.md](animation-verify.md) | Verifying animation quality after GSAP, rAF, or CSS transition changes |
 | [add-server-endpoint.md](add-server-endpoint.md) | Adding a new REST or WebSocket route to `_server.py` |
-| [debug-vscode-extension-python.md](debug-vscode-extension-python.md) | Diagnosing VS Code custom-editor failures caused by Python selection, workspace virtualenv drift, or uv fallback behavior |
+| [debug-vscode-extension-python.md](debug-vscode-extension-python.md) | Diagnosing VS Code opener failures in the signal-file and forwarded WebSocket path |
 | [debug-render.md](debug-render.md) | Visual rendering failures — wrong colors, blank canvas, artifacts, colormap issues |
 | [extend-compare-mode.md](extend-compare-mode.md) | Extending compare mode in `_viewer.html`, including new compare entry paths, pane labels, or per-pane diff/render state |
 | [extract-server-route-module.md](extract-server-route-module.md) | Moving an existing route cluster out of `_server.py` into a dedicated `_routes_*.py` module |

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/patterns/add-file-format.md

@@ -31,8 +31,7 @@ All file parsing goes through `_io.load_data(filepath)` or `_io.load_data_with_m
 Transport/session creation is separate from parsing:
 
 - FastAPI `/load`: `src/arrayview/_routes_loading.py`
-- CLI spawned daemon and direct stdio CLI mode: `src/arrayview/_launcher.py`
-- VS Code tunnel direct webview: `src/arrayview/_stdio_server.py`
+- CLI spawned daemon and in-process sessions: `src/arrayview/_launcher.py`
 
 The server and CLI must not import format libraries directly. They may call generic `_io` helpers such as `list_array_keys()` or `default_array_key()` when they need to choose a key before creating a session.
 
@@ -82,7 +81,7 @@ The server and CLI must not import format libraries directly. They may call gene
 
 7. **Keep key/default selection consistent across transports** for multi-array formats (`.npz`, `.mat`, HDF5-like containers):
    - Put filtering and default-key logic in `_io.py`, not in a route or launcher branch.
-   - Use the same helper from FastAPI `/load`, CLI daemon/direct paths, and `_stdio_server.py`.
+   - Use the same helper from FastAPI `/load`, CLI daemon startup, and in-process session creation.
    - If `/load` returns picker keys for multiple arrays, define what non-picker transports do (usually first displayable key).
 
 ## Gotchas
@@ -90,8 +89,8 @@ The server and CLI must not import format libraries directly. They may call gene
 - **Do not import the format library at the top of `_io.py`** without checking import cost first. Nibabel is the reference: it is lazy because it costs ~200 ms on first import.
 - **`.nii.gz` is two extensions** — the dispatch checks the full suffix, not just the last dot. New formats with compound extensions (`.foo.bar`) need special suffix handling in `load_data()`.
 - **Zarr is not loaded via `load_data()`** in all paths — zarr arrays can also be passed directly to `view()` as array objects. Ensure zarr-specific logic lives in `_session.py` / `_render.py`, not only in the file-load path.
-- **No format-specific parsing code in `_server.py`, `_launcher.py`, or `_stdio_server.py`** — if you find yourself adding a format import or dtype/shape filter in those modules, move it to `_io.py`.
-- **VS Code tunnel is stdio, not HTTP** — `arrayview file.ext` in a VS Code tunnel writes a signal file; the extension then runs `python -m arrayview --mode stdio file.ext`. A `/load` fix alone does not cover this path.
+- **No format-specific parsing code in `_server.py` or `_launcher.py`** — if you find yourself adding a format import or dtype/shape filter in those modules, move it to `_io.py`.
+- **VS Code tunnel uses the WebSocket server path** — remote/tunnel launches still need `/load` and daemon startup behavior to stay consistent.
 
 ## Verify
 
@@ -100,8 +99,7 @@ The server and CLI must not import format libraries directly. They may call gene
 - [ ] `load_data("myfile.myext")` returns a numpy array with correct shape and dtype
 - [ ] If the format can contain multiple arrays or non-displayable members, add tests for `list_array_keys()` / `default_array_key()` and direct `load_data(..., key=...)`
 - [ ] FastAPI `/load` works for the file, including picker/default-key behavior
-- [ ] `_stdio_server._handle_register()` works for the file, because VS Code tunnel direct webview uses stdio instead of `/load`
-- [ ] CLI daemon/direct paths use generic `_io` helpers for key selection instead of duplicating format rules
+- [ ] CLI daemon and in-process paths use generic `_io` helpers for key selection instead of duplicating format rules
 - [ ] `view(load_data("myfile.myext"))` opens the viewer without errors
 - [ ] If full-load format, added to `FULL_LOAD_EXTS`
 - [ ] `uv run pytest` on `tests/test_mode_consistency.py` still passes (no dtype regressions)

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/patterns/add-server-endpoint.md

@@ -1,6 +1,6 @@
 ---
 name: add-server-endpoint
-description: Adding a new REST or WebSocket route to the FastAPI server (_server.py) — includes session lookup, render dispatch, and stdio transport parity.
+description: Adding a new REST or WebSocket route to the FastAPI server (_server.py) — includes session lookup and render dispatch.
 triggers:
   - "endpoint"
   - "route"
@@ -27,8 +27,6 @@ last_updated: 2026-06-19
 
 Heavy render work must go to the render thread via `_render()` from `_session.py` — never block the async event loop with CPU work.
 
-If the feature involves the VS Code direct webview (stdio transport), `_stdio_server.py` must also be updated to handle the new message type. The two servers must stay feature-equivalent.
-
 ## Steps
 
 1. **Pick the owning module first:** add the route to the matching `_routes_*.py` module if the domain already exists. Only add it inline to `_server.py` if it is tiny infrastructure or shared app plumbing.
@@ -61,8 +59,6 @@ If the feature involves the VS Code direct webview (stdio transport), `_stdio_se
 
 6. **Wire the frontend:** If the route is called by JavaScript, add the fetch/WebSocket call in the correct section of `_viewer.html`. Follow the dual-write pattern if it updates display state.
 
-7. **Update `_stdio_server.py`** if the feature is needed in VS Code direct webview mode. The stdio server handles messages as JSON objects on stdin — add a new `elif msg_type == "my_type":` branch in the message dispatch loop.
-
 ## Gotchas
 
 - **Do not add logic to `_app.py`** — `_app.py` is a backward-compat shim only. New routes belong in `_routes_*.py` or `_server.py`.
@@ -70,15 +66,12 @@ If the feature involves the VS Code direct webview (stdio transport), `_stdio_se
 - **WebSocket binary protocol is tightly coupled** — the byte layout (offset, header fields, RGBA payload) is shared between `_server.py` and the WS handler in `_viewer.html`. Change one → change both. Mismatch causes the canvas to render garbage or stay blank.
 - **Never block the event loop** — even a small `np.array()` call on a large array can block for hundreds of milliseconds. Use `await _render(loop, func)` for all numpy work.
 - **`VIEWER_SOCKETS` is a module-level integer in `_session.py`** — increment/decrement via `_session_mod.VIEWER_SOCKETS` (the module reference), not the locally imported name. Same for `VIEWER_SIDS`.
-- **`_stdio_server.py` parity** — if your endpoint returns data that the viewer needs in any environment, it must work in the stdio transport too. VS Code tunnel users will silently get a broken feature otherwise.
-
 ## Verify
 
 - [ ] Route validates `sid` and returns 404 for unknown sessions
 - [ ] CPU/render work dispatched via `await _render(loop, ...)`, not called directly
 - [ ] WebSocket binary frame layout matches `_viewer.html` expectations (if applicable)
 - [ ] No new logic added to `_app.py`
-- [ ] `_stdio_server.py` updated if the feature is needed in VS Code direct webview
 - [ ] `uv run pytest` on `tests/test_view_component_integration.py` passes
 - [ ] Manual test: run `uv run arrayview` on `debug/test_array.npy` and confirm the new route is reachable
 

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/patterns/animation-verify.md

@@ -16,7 +16,7 @@ triggers:
 edges:
   - target: patterns/frontend-change.md
     condition: always — animation changes are always frontend changes
-last_updated: 2026-06-19
+last_updated: 2026-07-01
 ---
 
 # Animation Verify
@@ -101,18 +101,17 @@ Open the frame directory and scan the sequence:
 
 ### 3. Scrub at key progress points
 
-For pinch immersive crossfade: exercise `rawP` at 0 → 0.25 → 0.5 → 0.75 → 1.0 via
-`window.__pinchDebug = true` and the Playwright console:
+For pinch immersive crossfade: drive `immersiveTl.progress()` at 0 → 0.25 → 0.5 → 0.75 → 1.0 from the Playwright console (the pinch path writes `immersiveTl.progress()` directly; `_crossfadeP` mirrors the same value):
 
 - [ ] Canvas size progresses monotonically (grows without shrinking mid-transition)
 - [ ] Chrome elements stay at freeze position until their fade-out begins
-- [ ] No layout jump at the rawP=0 or rawP=1 boundary
+- [ ] No layout jump at the progress=0 or progress=1 boundary
 - [ ] After `_settleImmersive()` fires: chrome visible at overlay positions, `_scrubDetached` is false
 
 ### 4. Verify reverse path
 
 - [ ] Exit animation (reverse scrub) shows the same freeze behavior as entry
-- [ ] Chrome elements rejoin document flow cleanly at rawP=0 (no leftover fixed positioning)
+- [ ] Chrome elements rejoin document flow cleanly at progress=0 (no leftover fixed positioning)
 - [ ] `_resetImmersiveTransforms()` clears all detach inline styles
 
 ## Regression Table

{arrayview-0.27.0 → arrayview-0.28.0}/.mex/patterns/debug-render.md

@@ -22,7 +22,7 @@ edges:
     condition: only after Step 1 points to `_viewer.html` rather than the Python pipeline
   - target: context/conventions.md
     condition: for the Verify Checklist after fixing
-last_updated: 2026-06-19
+last_updated: 2026-07-01
 ---
 
 # Debug Render
@@ -95,7 +95,7 @@ print(vmin, vmax)  # should not be equal
 
 **Step 5 — Check WebSocket binary frame format**
 In the browser console: look for `ArrayBuffer` size. Expected: `H * W * 4` bytes (RGBA, row-major).
-If size is wrong → server is sending wrong shape. Add a print to the `/ws/{sid}` handler in `_server.py`.
+If size is wrong → server is sending wrong shape. Add a print to the `/ws/{sid}` handler in `_routes_websocket.py` (registered into the app via `register_websocket_routes(app)`; the handler is no longer in `_server.py`).
 
 **Step 6 — Check mosaic grid layout**
 For mosaic artifacts: `mosaic_shape(n)` returns `(rows, cols)`. Verify `rows * cols >= n`.
@@ -107,7 +107,7 @@ Run `_composite_overlay_mask(rgba, ov_raw, is_label=True)` on a test RGBA and ma
 ## Gotchas
 
 - **Cache stale after data change** — if `session.data` is modified without calling `session.reset_caches()`, stale slices will be served. Always call `reset_caches()` after modifying session data.
-- **Complex dtype from `.mat`** — scipy structured dtypes with `real`/`imag` fields are converted in `extract_slice`, not in `_io.load_data`. If you bypass `extract_slice`, you must call `_fix_mat_complex()` yourself.
+- **Complex dtype from `.mat`** — scipy structured dtypes with `real`/`imag` fields are converted in `_io.load_data()` (via `_fix_mat_complex()`), not in `extract_slice`. If you bypass `load_data()`, you must call `_fix_mat_complex()` yourself.
 - **RGB arrays skip colormap** — `render_rgb_rgba` does NOT call `apply_colormap_rgba`. If your code assumes all renders go through colormap, it breaks for RGB sessions.
 - **Mosaic gap pixels** — the grid is filled with `np.nan` first, then NaN pixels are colored `[22, 22, 22, 255]`. A NaN in actual data will look like a grid gap — use `extract_slice` which calls `nan_to_num`.
 - **Colormap not in LUTS** — custom colormaps added after `_init_luts()` go through `_ensure_lut()`. Never access `LUTS[name]` without calling `_ensure_lut(name)` first.