arrayview 0.14.0__tar.gz → 0.16.0__tar.gz

{arrayview-0.14.0 → arrayview-0.16.0}/.claude/skills/ui-consistency-audit/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: ui-consistency-audit
-description: Use when implementing or modifying any visual feature, layout, keyboard shortcut, or mode-specific behavior in arrayview. Proactively identifies all affected mode combinations before coding, prescribes per-mode behavior, checks for UI clashes, and runs a Playwright-based visual audit after implementation. Absorbs and replaces the modes-consistency skill.
+description: Use when the user explicitly requests a full visual audit, when validating UI work for a release, or when diagnosing a cross-mode visual regression in arrayview. Proactively identifies all affected mode combinations, prescribes per-mode behavior, checks for UI clashes, and runs a Playwright-based visual audit after implementation. Absorbs and replaces the modes-consistency skill.
 ---
 
 # ArrayView UI Consistency Audit
 
 ## Rule
 
-Every visual change must be verified across **all applicable mode × array-count combinations** before it ships. This skill has two phases: a **proactive phase** (before coding) that plans the cross-mode behavior, and a **reactive phase** (after coding) that runs an automated visual audit.
+This is the **full** visual audit path. Do not invoke it by default for every UI change. During normal feature development, do targeted verification for the specific area touched. Use this skill when the user explicitly asks for a broad visual check, when a regression spans modes/layouts, or when validating UI work for a release. This skill has two phases: a **proactive phase** (before coding) that plans the cross-mode behavior, and a **reactive phase** (after coding) that runs an automated visual audit.
 
 ---
 

{arrayview-0.14.0 → arrayview-0.16.0}/.claude/skills/viewer-ui-checklist/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: viewer-ui-checklist
-description: Use when adding keyboard shortcuts, changing layout, or making any UI change to arrayview. Ensures visual_smoke.py, help overlay, and docs/ stay in sync.
+description: Use when the user explicitly asks to sync UI docs/help/test coverage, or when preparing a UI change for release. Ensures visual_smoke.py, help overlay, and docs/ stay in sync.
 ---
 
 # ArrayView UI Checklist
 
 ## Rule
 
-Every UI change to arrayview MUST be reflected in `tests/visual_smoke.py`, the help overlay, and the relevant `docs/*.md` page before the task is complete.
+This is the release/explicit-sync checklist for UI work. Do not invoke it by default for every UI edit during development. Use it when the user explicitly asks for the full sync, or when preparing a UI change for release.
 
 `README.md` is intentionally minimal and stable — do **not** add per-feature shortcuts or behavior to it. User-facing docs live in `docs/` and are organized by topic (`display.md`, `viewing.md`, `comparing.md`, `loading.md`, `measurement.md`, `remote.md`, `configuration.md`).
 
@@ -19,7 +19,7 @@ Every UI change to arrayview MUST be reflected in `tests/visual_smoke.py`, the h
 - Layout changes (canvas sizing, colorbar position, overlays)
 - New overlay, dialog, or panel
 
-## Steps (mandatory, in order)
+## Steps (when this checklist is invoked)
 
 1. **Update coverage table** at the top of `visual_smoke.py`
    - If shortcut is now testable: change `✗` to `✓ NN` with scenario number

arrayview-0.16.0/.github/copilot-instructions.md

@@ -0,0 +1,39 @@
+---
+name: agents
+description: Always-loaded project anchor. Read this first. Contains project identity, non-negotiables, commands, and pointer to ROUTER.md for full context.
+last_updated: [YYYY-MM-DD]
+---
+
+# [Project Name]
+
+## What This Is
+<!-- One sentence. What does this project do?
+     Length: 1 sentence maximum.
+     Not a tagline — a factual description of what the software does.
+     Example: "A REST API for managing inventory across multiple warehouse locations." -->
+
+## Non-Negotiables
+<!-- Hard rules the agent must never violate. Not preferences — rules.
+     These are the things that, if broken, cause real damage to the codebase.
+     Length: 3-7 items maximum. More than 7 means the list has not been prioritised.
+     Example:
+     - Never write database queries outside of the repository layer
+     - Never commit secrets or API keys
+     - Always handle errors explicitly — no silent failures -->
+
+## Commands
+<!-- The exact commands needed to work on this project.
+     Include: run dev server, run tests, run linter, build.
+     Use the actual commands from this codebase — not placeholders.
+     Example:
+     - Dev: `npm run dev`
+     - Test: `npm test`
+     - Lint: `npm run lint`
+     - Build: `npm run build` -->
+
+## After Every Task
+After completing any task: update `.mex/ROUTER.md` project state and any `.mex/` files that are now out of date. If no pattern existed for the task you just completed, create one in `.mex/patterns/`.
+
+## Navigation
+At the start of every session, read `.mex/ROUTER.md` before doing anything else.
+For full project context, patterns, and task guidance — everything is there.

{arrayview-0.14.0 → arrayview-0.16.0}/.gitignore

@@ -34,4 +34,5 @@ van_gogh/
 cig_presentation/
 docs/superpowers
 .playwright-mcp/
-dev/TODO.md
+dev/TODO.md
+.nninteractive_weights/

arrayview-0.16.0/.ignore

@@ -0,0 +1 @@
+.worktrees/

arrayview-0.16.0/.mex/AGENTS.md

@@ -0,0 +1,9 @@
+---
+name: agents
+description: Lightweight pointer to ROUTER.md for task routing.
+last_updated: 2026-04-14
+---
+
+# arrayview
+
+Use `.mex/ROUTER.md` only when you need project state, routing, or a matching task pattern.

arrayview-0.16.0/.mex/ROUTER.md

@@ -0,0 +1,86 @@
+---
+name: router
+description: Navigation hub for task routing, project state, and behavioral guidance. Start here, then load the minimum extra context needed for the task.
+edges:
+  - target: context/project-state.md
+    condition: when the task depends on what is currently shipped, in progress, or recently changed
+  - target: context/architecture.md
+    condition: when working on system design, integrations, or understanding how components connect
+  - target: context/stack.md
+    condition: when working with specific technologies, libraries, or making tech decisions
+  - target: context/conventions.md
+    condition: when writing new code, reviewing code, or unsure about project patterns
+  - target: context/decisions.md
+    condition: when making architectural choices or understanding why something is built a certain way
+  - target: context/setup.md
+    condition: when setting up the dev environment or running the project for the first time
+  - target: context/frontend.md
+    condition: when working on _viewer.html — modes, reconcilers, command registry, View Component System
+  - target: context/render-pipeline.md
+    condition: when working on rendering, colormaps, LUTs, caching, or the render thread
+  - target: patterns/INDEX.md
+    condition: when starting a task — check the pattern index for a matching pattern file
+last_updated: 2026-04-17
+---
+
+# arrayview — Router
+
+## What This Is
+Python package for interactively viewing multi-dimensional arrays (numpy, NIfTI, zarr, etc.) 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`
+
+## Commands
+- Test: `uv run pytest tests/`
+- Visual smoke: `uv run pytest tests/visual_smoke.py`
+- CLI: `uvx arrayview <file>`
+- Build: `uv build`
+
+## Context Budget
+
+1. Start with this file plus **at most one pattern and one context file**.
+2. Treat frontmatter `edges` as **optional suggestions**, not a preload list.
+3. Follow **one extra edge only when blocked**. Do not recursively fan out through second-hop edges.
+4. Load `context/project-state.md` only when the task depends on current shipped or in-progress work.
+5. For UI, animation, or behavior bugs: ask plain-English clarification questions **before** reading git history, large diffs, or broad source sweeps.
+
+## Current Project State
+
+Load `context/project-state.md` only when you need active-workstream or recent-shipping detail.
+
+## Routing Table
+
+| Task type | Load |
+|-----------|------|
+| Checking current shipped / in-progress status | `context/project-state.md` |
+| Understanding system architecture | `context/architecture.md` |
+| Working with a specific technology | `context/stack.md` |
+| Writing or reviewing code | `context/conventions.md` |
+| Making a design decision | `context/decisions.md` |
+| Setting up or running the project | `context/setup.md` |
+| Editing `_viewer.html` (frontend) | `context/frontend.md` + `patterns/frontend-change.md` |
+| Render pipeline, colormaps, caching | `context/render-pipeline.md` |
+| Adding a new 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` |
+| Any specific task | Check `patterns/INDEX.md` for a matching pattern |
+
+## Behavioural Contract
+
+1. **CONTEXT** — Load from the routing table. Start small: this file + one pattern + one context file is the default cap. Do not preload unrelated docs.
+2. **CLARIFY** — If the task is about UI behavior, animation, or UX expectations, ask plain-English questions before deep investigation.
+3. **BUILD** — Do the work. If deviating from an established pattern, say so before writing code.
+4. **VERIFY** — If a pattern file was loaded, use its Verify section. Otherwise use the shared Verify Checklist in `context/conventions.md`.
+5. **DEBUG** — If verification fails, check `patterns/INDEX.md` for one debug pattern, fix, then re-run VERIFY.
+6. **GROW** — After completing the task: create/update patterns, update stale context files, and update `context/project-state.md` if significant.
+
+## 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.14.0 → arrayview-0.16.0}/.mex/SETUP.md

@@ -224,5 +224,5 @@ A well-populated scaffold should give the agent enough to:
 Once the scaffold is populated, use these to keep it aligned with your codebase:
 
 - **`mex check`** — detect drift (zero tokens, zero AI)
-- **`.mex/sync.sh`** — interactive drift check + targeted or full resync
+- **`.mex/SYNC.md`** — interactive drift check + targeted or full resync
 - **`mex watch`** — auto drift score after every commit

arrayview-0.16.0/.mex/context/architecture.md

@@ -0,0 +1,90 @@
+---
+name: architecture
+description: How the major pieces of arrayview connect and flow. Load when working on system design, integrations, or understanding how components interact.
+triggers:
+  - "architecture"
+  - "system design"
+  - "how does X connect to Y"
+  - "integration"
+  - "flow"
+  - "data flow"
+  - "display routing"
+edges:
+  - target: context/stack.md
+    condition: when specific technology details are needed
+  - target: context/decisions.md
+    condition: when understanding why the architecture is structured this way
+  - target: context/frontend.md
+    condition: when the task involves _viewer.html, modes, reconcilers, or the View Component System
+  - target: context/render-pipeline.md
+    condition: when the task involves slice extraction, colormaps, caching, or the render thread
+last_updated: 2026-04-15
+---
+
+# Architecture
+
+## System Overview
+
+```
+CLI / Python API (view() or uvx arrayview <file>)
+   └─ _launcher.py  →  FastAPI server (_server.py, uvicorn)   [network mode]
+                    →  _stdio_server.py                        [VS Code direct webview]
+
+Server (either mode)
+   ├─ _session.py   Session objects, global state, render thread, caches
+   ├─ _render.py    extract_slice → apply_complex_mode → render_rgba → PNG pipeline
+   └─ _io.py        load_data() — npy/npz/nii/zarr/h5/mat/tif/pt routing
+
+Browser (_viewer.html — single self-contained HTML+JS+CSS file)
+   ├─ WebSocket /ws/{sid}   binary PNG slices from server
+   ├─ GET /meta/{sid}       session metadata on first load
+   └─ Canvas + UI           colorbars, eggs, dynamic islands, mode transitions
+```
+
+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
+pywebview, or system browser).
+
+## Key Components
+
+- **`_launcher.py`** — CLI parser, `view()` API, `ViewHandle`, server lifecycle, reverse-tunnel relay (`--relay`), file watching. Heavy imports (`_session`, `_render`, `_io`, uvicorn) are all lazy to keep the CLI fast path near-zero cost.
+- **`_server.py`** — FastAPI app with all REST and WebSocket routes (`/meta/{sid}`, `/load`, `/slice`, `/ws/{sid}`, `/seg/*`, `/reload`, etc.). Dispatches render work to the render thread via `_render()` from `_session.py`.
+- **`_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()`).
+- **`_io.py`** — All file-format loading behind `load_data(filepath)`. Lazy nibabel import for NIfTI. Handles `.npy`, `.npz`, `.nii/.nii.gz`, `.zarr`, `.zarr.zip`, `.pt/.pth`, `.h5/.hdf5`, `.tif/.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 extension install/management, signal-file IPC, shared-memory IPC, webview panel and direct webview opening.
+- **`_stdio_server.py`** — Alternative to FastAPI for VS Code tunnel (direct webview): JSON on stdin, length-prefixed binary on stdout.
+- **`_viewer.html`** — The entire frontend (~15 600 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`.
+
+## Display Routing
+
+| Environment | Default display | Server mode |
+|---|---|---|
+| Jupyter | Inline iframe | network |
+| VS Code local | Webview panel | network |
+| VS Code tunnel | Direct webview (stdio) | stdio |
+| Julia | System browser | network |
+| CLI / Python script | Native pywebview | network |
+| SSH terminal | Prints URL — user forwards port with `ssh -L` | network |
+
+Detection logic: `_platform.py`. Display opening: `_launcher.py` + `_vscode.py`.
+
+## External Dependencies
+
+- **FastAPI + uvicorn** — async HTTP/WebSocket server, lazy-imported in `_launcher.py`. Never call uvicorn directly — use the `_uvicorn()` accessor.
+- **nibabel** — NIfTI file loading. Lazy-imported in `_io.py` via `_nib()`. Only loaded for `.nii` / `.nii.gz`.
+- **numpy** — Core array type throughout. The only non-lazy import in the render path.
+- **matplotlib** — Colormap LUT generation only. Lazy, initialized once by `_init_luts()` in `_render.py`.
+- **qmricolors** — Registers the `lipari` and `navia` colormaps. Git dependency (`oscarvanderheide/qmricolors`).
+- **zarr** — Lazy chunk access for `.zarr` / `.zarr.zip`. Chunk presets via `zarr_chunk_preset()` in `_session.py`.
+- **pywebview** — Native OS window. Lazy, only started when `_can_native_window()` is true.
+
+## What Does NOT Exist Here
+
+- No persistent storage — sessions are in-memory only; nothing is written to disk by the server.
+- No authentication or multi-user access control — server binds to localhost.
+- No build step for the frontend — `_viewer.html` is a single static file served from package resources.
+- No background job queue — heavy ops run in the render thread or prefetch pool, both owned by `_session.py`.
+- No nnInteractive server — `_segmentation.py` is a pure HTTP client to a separately running nnInteractive process.

{arrayview-0.14.0 → arrayview-0.16.0}/.mex/context/conventions.md

@@ -1,6 +1,6 @@
 ---
 name: conventions
-description: How code is written in arrayview — naming, structure, lazy imports, and frontend organization. Load when writing new code or reviewing existing code.
+description: How code is written in arrayview — naming, structure, lazy imports, frontend organization, and the shared Verify Checklist.
 triggers:
   - "convention"
   - "pattern"
@@ -14,9 +14,11 @@ edges:
     condition: when a convention depends on understanding the system structure
   - target: context/stack.md
     condition: when the convention is library-specific
-  - target: patterns/frontend-change.md
-    condition: when writing frontend (HTML/CSS/JS) code
-last_updated: 2026-04-13
+  - target: context/frontend.md
+    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-04-15
 ---
 
 # Conventions
@@ -77,6 +79,11 @@ Always check in this priority order. Never short-circuit.
 
 **Float rendering convention** — slices are always converted to `np.float32` before applying colormap. RGB uint8 arrays skip colormap and go directly to RGBA. Complex arrays are transformed by `apply_complex_mode()` before any colormap step.
 
+## Context Discipline
+
+- Load this as the shared reference alongside a task pattern; do not use it to fan out into more task-specific files.
+- If you need a different task workflow, go back to `ROUTER.md` or `patterns/INDEX.md` and pick one pattern deliberately.
+
 ## Verify Checklist
 
 Before presenting any code change:
@@ -86,4 +93,4 @@ Before presenting any code change:
 - [ ] 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`
-- [ ] Cross-mode consistency: any new visual feature verified in all six invocation environments (see `invocation-consistency` skill)
+- [ ] Cross-mode consistency: any new visual feature is checked in all six invocation environments when the task or verification scope requires it

arrayview-0.16.0/.mex/context/decisions.md

@@ -0,0 +1,78 @@
+---
+name: decisions
+description: Key architectural and technical decisions with reasoning. Load when making design choices or understanding why something is built a certain way.
+triggers:
+  - "why do we"
+  - "why is it"
+  - "decision"
+  - "alternative"
+  - "we chose"
+edges:
+  - target: context/architecture.md
+    condition: when a decision relates to system structure
+  - target: context/stack.md
+    condition: when a decision relates to technology choice
+  - target: context/frontend.md
+    condition: when a decision relates to the frontend architecture or viewer modes
+last_updated: 2026-04-16
+---
+
+# Decisions
+
+## Decision Log
+
+### Single self-contained _viewer.html — no build step
+**Date:** pre-2024 (initial design)
+**Status:** Active
+**Decision:** The entire frontend (CSS + JS) lives in one `_viewer.html` file with no bundler or build step.
+**Reasoning:** The package is installed as a Python wheel. Shipping a single file that works as a package resource eliminates build infrastructure (npm, webpack, etc.) and makes the project trivially installable. The file is served directly from package resources via `importlib.resources`.
+**Alternatives considered:** Separate JS/CSS files with a bundler (rejected — adds npm as a required toolchain and a build step to every contribution); Jinja2 templating (rejected — adds complexity without benefit when one file is sufficient).
+**Consequences:** Frontend is ~15 600 lines in one file. All edits happen in `_viewer.html` only — never create companion JS/CSS files.
+
+### Lazy imports everywhere in _launcher.py
+**Date:** 2024 (extracted from _app.py)
+**Status:** Active
+**Decision:** `_launcher.py` does not import numpy, _session, _render, _io, or uvicorn at module level. All are deferred to first use via accessor functions (`_server_mod()`, `_uvicorn()`, etc.) or `_LazyMod`.
+**Reasoning:** The CLI fast path — when the server is already running — only needs to send a `/load` HTTP request. Eager imports add ~300–350 ms per invocation, which is unacceptable for a tool used interactively dozens of times per session.
+**Alternatives considered:** Importing everything eagerly (rejected — too slow); using `importlib.import_module` everywhere (equivalent, but the `_mod_cache = None` + accessor pattern is more readable and explicit).
+**Consequences:** Any new heavy import added to `_launcher.py` must follow the accessor pattern. Violating this breaks the fast path.
+
+### Global state lives exclusively in _session.py
+**Date:** 2024 (modular refactor from _app.py)
+**Status:** Active
+**Decision:** `SESSIONS`, `SERVER_LOOP`, `VIEWER_SOCKETS`, `VIEWER_SIDS`, `SHELL_SOCKETS`, `_RENDER_QUEUE`, `_RENDER_THREAD` are all defined in `_session.py` and imported by name elsewhere. No other module defines or shadows these.
+**Reasoning:** Before the refactor, global state was scattered across `_app.py`. Centralizing it in one module makes concurrent access patterns explicit and prevents accidental redefinition.
+**Alternatives considered:** Thread-local storage (rejected — server loop and sessions need to be shared across threads); a dedicated `State` singleton class (rejected — no benefit over module-level globals for this use case).
+**Consequences:** Any new global mutable state must be added to `_session.py`. Never redefine these names in `_server.py`, `_launcher.py`, or anywhere else.
+
+### Render thread is threading.Thread + SimpleQueue, not concurrent.futures
+**Date:** 2024
+**Status:** Active
+**Decision:** The CPU-bound render work runs in a raw `threading.Thread` driven by `_queue.SimpleQueue`, not a `ThreadPoolExecutor`.
+**Reasoning:** During Python interpreter shutdown, `concurrent.futures` sets a `_global_shutdown` flag that prevents submitting new work. Because the server can still receive requests during shutdown, this caused render failures. Raw `threading.Thread` with `daemon=True` is unaffected by the executor lifecycle.
+**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)
+**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.
+
+### ROI in qMRI uses per-pane overlay canvases, not a shared overlay
+**Date:** 2026-04-16
+**Status:** Active
+**Decision:** Each qMRI pane gets its own `.qv-roi-overlay` canvas element. ROI shapes are drawn on all overlays simultaneously during drag, and stats are fetched per parameter map.
+**Reasoning:** In qMRI mode, the single main canvas is hidden and replaced by N independent pane canvases, each with its own coordinate system and scale. A shared overlay (like the main `#roi-overlay`) cannot span multiple independently-positioned canvases. Per-pane overlays also allow the ROI mirroring UX where drawing on one pane instantly shows the same shape on all others.
+**Alternatives considered:** A single overlay canvas spanning the entire `#qmri-view-wrap` (rejected — would need to track pane positions and clip per-pane, fragile across resize/mosaic layout changes); reusing the main `#roi-overlay` (rejected — it's inside `#canvas-viewport` which is hidden in qMRI mode).
+**Consequences:** Overlay canvases must set `background: transparent` to override the global `canvas { background: var(--bg) }` rule. qMRI view objects carry `roiOverlay` and `roiCtx` properties. `_drawAllQvRois()` replaces `_drawAllRois()` in qMRI mode; `_redrawRoiOverlays()` dispatches to the correct function based on mode.
+
+### UI visibility changes go through reconcilers, not ad hoc style/classList calls
+**Date:** 2025 (View Component System refactor)
+**Status:** Active
+**Decision:** All visibility and layout state changes in `_viewer.html` must go through the four reconciler functions (unified UI reconciler, layout container visibility, compare sub-mode state, CB/island visibility).
+**Reasoning:** Before reconcilers, mode-switch functions each managed their own ad hoc `style.display` toggles. This caused regressions where fixing one mode's layout broke another. Reconcilers enforce a single source of truth for UI state.
+**Alternatives considered:** Each mode function manages its own visibility (previous approach, rejected due to regression rate); CSS class toggling with no reconciler (rejected — same problem in a different form).
+**Consequences:** When adding a new UI element, wire it into the appropriate reconciler. Never set `style.display` or toggle classes in mode-entry/exit functions — that work belongs in the reconcilers.

arrayview-0.16.0/.mex/context/frontend.md

@@ -0,0 +1,146 @@
+---
+name: frontend
+description: _viewer.html internals — mode matrix, reconcilers, command registry, View Component System, CSS architecture. Load for any task touching _viewer.html.
+triggers:
+  - "_viewer.html"
+  - "frontend"
+  - "mode"
+  - "reconciler"
+  - "keybind"
+  - "colorbar"
+  - "canvas"
+  - "dynamic island"
+  - "egg"
+  - "command registry"
+  - "View Component"
+  - "modeManager"
+edges:
+  - target: context/architecture.md
+    condition: when understanding how the frontend connects to the server
+  - target: context/decisions.md
+    condition: when understanding why the frontend is a single file or why reconcilers exist
+  - target: context/conventions.md
+    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-04-17
+---
+
+# Frontend (_viewer.html)
+
+~15 600 lines. Single file, no build step. All CSS and JS inline.
+
+## Section Organization
+
+Section separators: `/* ── Section Name ── */` in CSS, `// ── Section Name ──` in JS.
+
+**CSS (lines ~7–1500)**
+| Section | What it covers |
+|---------|----------------|
+| Theme Variables and Base Layout | CSS custom properties, dark theme palette, root layout grid |
+| ColorBar and Dynamic Islands | Colorbar positioning, egg badges, info bar, dimension sliders |
+| Generic ColorBar class styles | Shared `.av-colorbar` styles used by the `ColorBar` JS class |
+| Compare, Overlay, and Prompt Styles | Side-by-side panes, overlay blend, prompt dialogs |
+| Help and Info Overlays | Help shortcut overlay, array-info panel |
+| Immersive, Fullscreen, and Compact Mode | Zen mode hide rules, fullscreen layout, compact overrides |
+
+**JavaScript (lines ~1500–14750)**
+| Section | What it covers |
+|---------|----------------|
+| Constants and Transport Setup | WS URL construction, stdio/postMessage transport abstraction |
+| Viewer State Variables | All mutable state: slice indices, zoom, mode flags |
+| Mode Registry | Mode name → enter/exit function mapping |
+| PanManager | Canvas panning state machine |
+| Canvas Scaling and Layout | `scaleCanvas()`, `mvScaleAllCanvases()`, `compareScaleCanvases()`, `qvScaleAllCanvases()` |
+| Compare Mode | Multi-pane compare infrastructure, drag-to-reorder |
+| Colorbar Rendering and Histogram | Colorbar draw routines, histogram morph |
+| ColorBar class | Reusable `ColorBar` class (~900 lines) |
+| WebSocket and Data Transport | Binary slice receive, request queueing, reconnect |
+| Initialization and Metadata Fetch | `/meta` fetch, loading screen |
+| Info Bar and Pixel Display | Bottom info bar, hover pixel readout |
+| State Persistence and Restore | URL hash state, `sessionStorage` save/restore |
+| Rendering Pipeline | `updateView()`, play/animate, screenshot |
+| ROI and Selection Modes | Rectangle/circle/freehand ROI, statistics computation, qMRI cross-pane mirroring |
+| nnInteractive Segmentation | Click-to-segment UI, mask overlay, undo stack |
+| Keyboard Shortcuts | Command registry + command palette |
+| Mode Transitions | Compare/multiview/qMRI enter/exit, crosshair animation |
+| Scroll, Zoom, and Pan | Mouse wheel, pinch zoom |
+| Immersive Mode, Cross-Fade, and Visual Effects | Zen mode, fullscreen, animated transitions |
+| UI Validation and Reconciliation | Reconcilers (~line 13666) |
+| Colormap Strip and Wipe/Flicker Compare Tools | A/B wipe, flicker, checkerboard |
+| Ruler, Line Profile, and Mini-Map | Distance measurement, intensity profile |
+| Compact Mode and Touch Input | Touch gesture handling |
+| File Picker and Session Management | File browser, drag-and-drop |
+
+## Mode Matrix
+
+| Mode | Scale function | `modeManager.modeName` |
+|------|---------------|------------------------|
+| Normal | `scaleCanvas()` | `'normal'` |
+| Immersive (Zen) | `scaleCanvas()` | `'normal'` |
+| Compact | `scaleCanvas()` | `'normal'` |
+| Multiview (3-pane oblique) | `mvScaleAllCanvases()` | `'multiview'` |
+| Compare | `compareScaleCanvases()` | `'compare'` |
+| Diff / Registration / Wipe/Flicker/Checker | `compareScaleCanvases()` | `'compare'` |
+| Compare + MV | `compareMvScaleAllCanvases()` | `'compare-mv'` |
+| Compare + qMRI | `compareQmriScaleAllCanvases()` | `'compare-qmri'` |
+| qMRI | `qvScaleAllCanvases()` | `'qmri'` |
+| qMRI Mosaic | `qvScaleAllCanvases()` | `'qmri-mosaic'` |
+| MIP (3-D volume) | N/A (WebGL) | `'mip'` |
+
+## Key Concepts
+
+### Reconcilers (~line 13666)
+Four functions enforcing consistent UI state across mode changes:
+1. **Unified UI reconciler** — master state enforcer
+2. **Layout container visibility reconciler** — show/hide mode-specific containers
+3. **Compare sub-mode state reconciler** — diff/overlay/wipe/flicker/checkerboard
+4. **CB / island visibility reconciler** — colorbar and dynamic island show/hide
+
+**Rule:** All visibility changes go through reconcilers. Never set `style.display` or toggle classes in mode-entry/exit functions — that belongs in the reconcilers.
+
+### Command Registry
+Three tables: `commands` (id → `{title, when, run}`), `keybinds` (key+modifiers → command id), `makeContext(state)` (mode/state flag bag). `dispatchCommand(e)` is the keydown prefix handler.
+
+**Rule:** When adding or changing a keybind, update both `commands`/`keybinds` tables AND `GUIDE_TABS` (the static data structure that renders the help overlay). Do not edit overlay HTML directly.
+
+### View Component System (Phases 1–15 complete)
+Introduces `View`, `Slicer`, `Layer`, `LayoutStrategy`, `modeManager` alongside the legacy render pipeline.
+
+| Primitive | What it owns |
+|-----------|-------------|
+| `makeDisplayState(overrides)` | Plain-object factory: `{vmin, vmax, cmapIdx, logScale, complexMode, renderMode, projectionMode, …}` |
+| `class View` | Canvas + ColorBar + DisplayState + Slicer + Layers[]. Has `init()`, `render()`, `requestRender()` |
+| `class Slicer` | `FreeSliceSlicer`, `OrthogonalSlicer(axis)` |
+| `class Layer` | `CrosshairLayer`, `VectorFieldLayer`, `OverlayLayer` — duck-typed, composable |
+| `class LayoutStrategy` | `NormalLayout`, `MultiViewLayout`, `CompareLayout`, `QmriLayout`, etc. |
+| `const modeManager` | Singleton: `{currentViews[], currentLayout, modeName, enterMode(), …}` |
+
+**Sync-block pattern:** Every `enterXxx()` function ends with a block that creates thin `View` wrappers over existing legacy canvases/colorbars and populates `modeManager.currentViews` + `modeName`. The legacy render pipeline is unchanged.
+
+**Dual-write pattern:** Where commands update legacy globals (`logScale`, `colormap_idx`, etc.), they also write to `view.displayState.xField` so both systems stay in sync.
+
+**Shim layer (Section 7):** `Object.defineProperty(window, 'manualVmin', …)` intercepts all bare writes to `manualVmin`/`manualVmax` (27 sites) and routes them to `modeManager.currentViews[0].displayState.vmin/vmax`.
+
+### Plugin Shelf (`/` menu)
+`SPECIAL_MODE_TILES` array defines five plugins: qMRI, Segmentation, ROI, Overlay, Vector field. The shelf supports multi-select (spacebar toggles, Enter applies). Mutual exclusion is enforced via `tile.excludes` arrays — ROI ↔ Segmentation, and Overlay/Vector field are reciprocally exclusive with all other plugins. `_applyShelfSelection()` diffs current state against selection, exits removed plugins, then enters new ones wrapped in `crossfade()`. Overlay and Vector field auto-seed the shelf at init when arrays are present (`_overlaySids.length > 0`, `hasVectorfield`); their per-tile state lives in `_shelfSelection.has(id)` since there is no separate mode flag.
+
+### Eggs
+Pill badges below the canvas showing active transforms: `FFT` `LOG` `MAGNITUDE` `PHASE` `REAL` `IMAG` `RGB` `ALPHA` `PROJECTION`. **ROI** and **SEGMENT** are NOT eggs — they are interaction modes with their own dynamic island UI.
+
+### Dynamic Islands
+Floating UI panels. `renderIsland()` collects all active plugins (`qmriActive`, `rectRoiMode`, `_segMode`/`_segActivating`, `_shelfSelection.has('overlay')`, `_shelfSelection.has('vectorfield')`) and renders sections for each with dividers between them. ROI/Segmentation share the same shape-toolbar + rows + magnifier-action layout; segmentation also renders a pulsing "connecting" loading row during `_segActivating`. Overlay section renders per-overlay rows (swatch + editable label + eye + `×`) with a shared opacity slider and a `+ add overlay` button that opens the filesystem picker. Vector field section renders a visibility row plus density and length sliders wired to `vfDensityLevel` / `vfLengthLevel` (both directions — keyboard `[ ] { }` also re-renders the island). An inline `~` collapse button at the island's top-right triggers `_collapseIslandToHint()`. `renderIsland()` early-returns while `_islandSliderDragging` is true so a mid-drag DOM rebuild doesn't kill the grab. Use absolute/fixed positioning — must be tested across normal, immersive, multiview, and compare modes.
+
+### ROI in qMRI Mode
+Each qMRI pane has a `.qv-roi-overlay` canvas (transparent, `position: absolute`, `pointer-events: none`). Drawing a ROI on any pane mirrors it to all panes in real-time via `_drawAllQvRois()`. On finalize, `_fetchQvRoiStats()` fetches per-parameter-map statistics in parallel. Results stored as `roi.qmriStats[]` and displayed as sub-rows in the island. Key functions: `_drawAllQvRois`, `_clearQvRoiOverlays`, `_redrawRoiOverlays`, `_finalizeQvRoi`, `_fetchQvRoiStats`. **Important:** the global `canvas { background: var(--bg) }` rule makes all canvas elements opaque — overlay canvases must set `background: transparent` to avoid covering the underlying content.
+
+## CSS Architecture
+
+- **Dark theme only.** `#0c0c0c` background, `#d8d8d8` text, `#f5c842` yellow accents.
+- **No CSS framework.** All custom properties in `:root`.
+- **Mode-specific overrides** use `.immersive-mode`, `.compact-mode`, `.multiview-mode` classes on `body`.
+- **`av-loading` class** on `body` during initial load — hides UI until data arrives.
+- **Canvas size management:** `scaleCanvas()` (and variants) are the only legitimate way to set canvas dimensions. Never set canvas `width`/`height` directly.
+
+## WebSocket Binary Protocol
+Slice data arrives as raw RGBA bytes. Header format and byte offsets are tightly coupled between `_server.py` (Python) and the WS handler in `_viewer.html` (JS). Changes to one must match the other exactly.

arrayview-0.16.0/.mex/context/project-state.md

@@ -0,0 +1,45 @@
+---
+name: project-state
+description: Current working, in-progress, and shelved status. Load only when the task depends on active workstreams or recent shipped behavior.
+triggers:
+  - "current state"
+  - "what's in progress"
+  - "recent work"
+  - "active feature"
+  - "shipped recently"
+last_updated: 2026-04-17
+---
+
+# Project State
+
+## 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`)
+- 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
+- NIfTI spatial metadata, RAS resampling
+- VS Code extension v0.14.5 — 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
+- Colorbar refactor: `ColorBar` JS class partially migrated (in progress)
+- Colorbar island flip: `c` and `d` keys trigger 3D `rotateX` card flip (front=colorbar, back=cmap thumbnails/histogram)
+- Cold-start loading spinner in VS Code and native shell
+- Plugin shelf (`/` menu) supports multi-select: spacebar toggles plugins, Enter applies selection. Mutual exclusion enforced (ROI ↔ Segmentation, and overlay/vectorfield ↔ everything else). Cursor indicator shows focused tile via yellow background + left accent bar
+- Dynamic island renders sections for all active plugins simultaneously (qMRI pills + ROI shapes/stats separated by divider), replacing the old single-plugin priority chain
+- ROI mode works alongside qMRI: drawing on any pane mirrors the ROI to all panes in real-time via per-pane overlay canvases; stats fetched per parameter map and shown as sub-rows in the island
+- qMRI map toggle (`_islandToggleQmriMap`) fade animation now covers dimbar and array-name in addition to panes and colorbars
+- Segmentation menu shares the ROI layout (yellow accent, magnifier action icon, common `#export-overlay` modal). Pre-activation shows a pulsing "nnInteractive · connecting" row that morphs into the normal shape toolbar once `/seg/activate` resolves
+- Overlays are a plugin tile (`OV`): per-overlay row with colour swatch, editable label, eye toggle, × delete; shared opacity slider; `+ add overlay` opens a filesystem picker rooted at the launched file's directory
+- Vector field is a plugin tile (`VF`): row with visibility toggle + density/length sliders bi-directionally wired to the `[ ] { }` keyboard commands
+- CLI `--overlay FILE` can be repeated to load multiple overlays at launch
+- Filesystem picker endpoint (`GET /fs/list`) clamped to `$HOME`. Accepts `base_sid` + `mode` (`overlay` | `vectorfield`) to filter entries by a cheap header-shape peek (`.npy`, `.nii`/`.nii.gz`, `.h5`, `.zarr`); overlay mode requires identical shape, vectorfield mode requires base shape plus one axis of size 3
+- 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 plugin shelf
+
+## In Progress
+
+- Smooth immersive transition — stale scrub geometry handoff is fixed, immersive overlay fade-in is held until after the class switch, shared slim colorbar returns through `drawSlimColorbar()` on reverse, and active scrub suppresses minimap/overflow/drag side effects. Single-pane scrub now targets the actual centered immersive viewport rect instead of a hardcoded corner box, the dimbar stays above the pane during scrub, the shared colorbar sits behind the growing pane, and the phantom extra `av-view-wrap` footprint in normal mode was removed by rebinding `NormalLayout` to the real `#viewer` canvas. Cross-mode parity and deeper reverse-pinch validation still need manual verification.
+- ROI + qMRI integration refinements: floodfill not yet supported on qMRI panes; ROI hover tooltip not yet wired for qMRI canvases; per-pane stats are re-fetched on each ROI draw but not updated on slice scroll
+
+## Not Yet Built
+
+- Independent split view for mismatched-shape arrays (designed, shelved)
+- Admin/config UI (file-based `~/.arrayview/config.toml` only)