arrayview 0.5.1__tar.gz → 0.6.0__tar.gz

arrayview-0.6.0/.claude/skills/invocation-consistency/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: invocation-consistency
+description: Use when implementing any server-side, startup, display-opening, or environment-detection feature in arrayview. Ensures the feature works correctly across all six ways arrayview can be launched — CLI, Python script, Jupyter, Julia, VS Code tunnel, and SSH.
+---
+
+# ArrayView Invocation Consistency Checklist
+
+## Rule
+
+Every behavior that depends on *how* arrayview is started (server lifecycle, browser opening, display routing, port forwarding) must be verified across all six invocation paths before it is considered done.
+
+## The Six Invocation Paths
+
+| Path | Entry point | Display | Server model |
+|------|------------|---------|-------------|
+| **CLI** | `arrayview()` | native window → browser fallback | background thread, blocks until Ctrl-C |
+| **Python script** | `view(arr)` | native window → browser fallback | daemon thread (dies with caller) |
+| **Jupyter** | `view(arr)` | inline IFrame | daemon thread (persists across cells) |
+| **Julia (PythonCall)** | `view(arr)` | system browser | always subprocess (`_view_julia()`) — GIL |
+| **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 |
+
+## Key Detection Functions (all in `_platform.py`)
+
+```python
+_in_jupyter()           # ipykernel present → display inline IFrame
+_in_vscode_terminal()   # TERM_PROGRAM=vscode OR VSCODE_IPC_HOOK_CLI → use Simple Browser
+_is_vscode_remote()     # tunnel/SSH remote with VS Code server → shared signal fallback
+_is_julia_env()         # juliacall in sys.modules or julia in sys.executable → subprocess
+_can_native_window()    # pywebview available + not remote + display present → native window
+_find_vscode_ipc_hook() # walk process tree for VSCODE_IPC_HOOK_CLI (stripped by uv run)
+```
+
+## Detection Order in `view()`
+
+Julia → Jupyter → VS Code remote → VS Code terminal → local (native/browser)
+
+Any new detection must not break the fallback chain for paths it shouldn't match.
+
+## Julia-Specific Constraints
+
+- Never run server in-process when `_is_julia_env()` is True (GIL conflicts)
+- `_view_julia()` starts a detached subprocess; array is serialized to a temp `.npy` file
+- No interactive stdin in subprocesses; all params encoded in CLI flags or files
+
+## Jupyter-Specific Constraints
+
+- `_in_jupyter()` returns True for ipykernel (VS Code notebook, JupyterLab, classic Notebook)
+- Julia's IJulia kernel is NOT ipykernel → `_in_jupyter()` returns False in Julia notebooks
+- `inline=True` → returns `IPython.display.IFrame`; caller must return it from the cell
+- Port reuse: repeated `view()` calls reuse same port/server if already running
+
+## Port & URL Rules
+
+- Always use `localhost` (not `127.0.0.1`) so VS Code port-forwarding works
+- Default port: `8123`; CLI: `--port` flag; `view()`: `port=` kwarg
+
+## tmux and VS Code Terminal Detection
+
+tmux breaks the ancestor-walk for `VSCODE_IPC_HOOK_CLI` because the process's parent chain goes through `tmux-server` (an independent daemon with no VS Code env), not through the VS Code terminal shell.
+
+**Why `tmux show-environment` fails:** `VSCODE_IPC_HOOK_CLI` is not in tmux's default `update-environment` list.
+
+**Why `#{client_pid}` alone fails:** returns only one client; breaks with multiple attached clients.
+
+**Correct approach — enumerate all clients for the current session:**
+
+```python
+session_id = subprocess.run(["tmux", "display-message", "-p", "#{session_id}"], ...).stdout.strip()
+client_pids = subprocess.run(
+    ["tmux", "list-clients", "-t", session_id, "-F", "#{client_pid}"], ...
+).stdout.strip().splitlines()
+for pid_str in client_pids:
+    val = _ipc_from_pid(int(pid_str))
+    if val and os.path.exists(val):
+        return val
+```
+
+`list-clients -t <session_id>` scopes to current session only — prevents false-positive from a different VS Code window in another tmux session.
+
+## Step-by-Step Checklist
+
+1. **Server startup/teardown?**
+   - CLI: starts and terminates cleanly
+   - Python script: daemon thread doesn't orphan
+   - Jupyter: repeated calls don't fail on port-already-in-use
+   - Julia: `_view_julia()` passes new params via CLI flag or file
+
+2. **Browser/display opening?**
+   - Local native window (macOS): `pywebview` opens correctly
+   - VS Code terminal: Simple Browser opens via extension signal file
+   - VS Code tunnel: reaches client-side Simple Browser, not remote host
+   - Verify `_ensure_vscode_extension()` installs/updates if VSIX changed
+
+3. **Environment detection?**
+   - Check detection order: Julia → Jupyter → VS Code remote → VS Code terminal → local
+   - `_find_vscode_ipc_hook()` walks up to 12 parent processes; new subprocess wrappers may need the same
+
+4. **VS Code extension changed?**
+   - Rebuild VSIX: `cd vscode-extension && vsce package -o ../src/arrayview/arrayview-opener.vsix`
+   - Bump `_VSCODE_EXT_VERSION` in `_vscode.py` and `vscode-extension/package.json` together
+
+## Quick Automated Checks
+
+```bash
+uv run pytest tests/test_api.py -x
+uv run pytest tests/test_cli.py -x
+uv run python -c "from arrayview import view; import numpy as np; view(np.zeros((10,10)))"
+```
+
+## Red Flags — STOP
+
+- "I changed server startup but only tested CLI" → test all paths
+- "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`
+- "I bumped `package.json` but not `_VSCODE_EXT_VERSION`" → must stay in sync
+- "Server starts but leaves an orphan after Ctrl-C" → check `_shutdown_event` and subprocess reaping

{arrayview-0.5.1 → arrayview-0.6.0}/.claude/skills/task-workflow/SKILL.md

@@ -43,9 +43,13 @@ For each TODO item, ensure the following before marking the task done:
 - [ ] README or in-app help overlay (`#help-overlay` content in `src/arrayview/_viewer.html`) updated if usage changed.
 - [ ] `CHANGELOG.md` or `AGENTS.md` updated with a one-line summary.
 - [ ] Commit message follows the format above and lists affected files.
-- [ ] Run the core checks locally:
-  - `uv run pytest tests/test_api.py -q`
-  - `uv run python tests/visual_smoke.py` (and review `tests/smoke_output/`)
+- [ ] **Tests MUST be run by the agent — NEVER ask the user to run them.**
+  - After every code change, run the relevant test suite immediately:
+    - Backend/API changes → `uv run pytest tests/test_api.py -q`
+    - Viewer UI changes → `uv run pytest tests/test_interactions.py tests/test_mode_consistency.py -q`
+    - CLI changes → `uv run pytest tests/test_cli.py -q`
+  - If any test fails, fix it before considering the task done.
+  - Do NOT end a task with "run this to verify" — run it yourself and report results.
 
 ## How to use
 

arrayview-0.6.0/.claude/skills/ui-consistency-audit/SKILL.md

@@ -0,0 +1,336 @@
+---
+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.
+---
+
+# 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.
+
+---
+
+## Phase 1: Proactive (Before Coding)
+
+### Step 1 — Classify the Change
+
+What area of the UI is being touched?
+
+| Category | Examples |
+|----------|---------|
+| **Canvas rendering / sizing / zoom** | scaleCanvas, zoom cap, compact mode, miniview |
+| **Chrome element** | colorbar, dimbar, eggs, array name, logo, miniview, colormap previewer |
+| **Keyboard shortcut** | new or modified shortcut |
+| **Mode entry/exit** | toggling multiview, qMRI, compare, diff, ROI, zen, compact |
+| **Overlay feature** | ROI, vector field, histogram/Lebesgue, hover tooltip |
+| **Multi-array layout** | compare pane alignment, diff center pane, grid layout |
+
+### Step 2 — Enumerate Affected Modes
+
+Use the code-area-to-mode mapping (Section 7) to list every mode combination that could be affected. Do not skip modes — if in doubt, include them.
+
+### Step 3 — Prescribe Behavior Per Mode
+
+For **each** affected mode, explicitly state:
+
+1. How the feature behaves in this mode
+2. Whether it's the same as normal mode or different (and why)
+3. Which UI elements it could clash with (use the design rules in Section 5)
+4. What happens at fit-to-window zoom AND zoomed-in (compact/miniview) zoom
+
+### Step 4 — Check Against Design Rules
+
+Walk through the principles (Section 5a) and specific rules (Section 5b). Flag any potential violations.
+
+### Step 5 — Get Approval
+
+Present the mode-by-mode behavior plan to the user before implementing.
+
+---
+
+## Phase 2: Reactive (After Coding)
+
+After implementation, run the visual audit:
+
+```bash
+# Tier 1 only (quick, ~15 screenshots × 2 zoom levels)
+uv run python tests/ui_audit.py --tier 1
+
+# Full audit (tier 1 + tier 2, ~40 screenshots × 2 zoom levels)
+uv run python tests/ui_audit.py
+
+# Specific subset (when you know which modes are affected)
+uv run python tests/ui_audit.py --tier 2 --subset zoom,compact,compare
+
+# Update baselines after intentional changes
+uv run python tests/ui_audit.py --update-baselines
+```
+
+**Output:** Terminal summary (pass/fail per combination) + screenshots in `tests/ui_audit/screenshots/`. Visual diffs in `tests/ui_audit/diffs/` when baselines exist.
+
+### Step 3 — Visual Design Inspection (MANDATORY)
+
+DOM assertions catch mechanical violations. They **cannot** catch:
+- Bad layout decisions (elements in wrong position, wasted screen space)
+- Overlapping elements not covered by a specific rule
+- Aesthetically wrong choices (miniview floating in a weird spot, panes misaligned)
+- Features that technically work but look broken to a human
+
+After the audit script runs, you MUST:
+
+1. **Read every screenshot** from the affected tier using the Read tool (it renders PNGs visually)
+2. **For each screenshot, evaluate as a UI designer:**
+   - Are elements logically positioned? Would a user know where to look?
+   - Is screen real estate maximized? Are canvases as large as they can be?
+   - Do overlapping or adjacent elements clash? (colorbars, minimaps, eggs, labels)
+   - Is the layout consistent with the same feature in other modes?
+   - Would this look good on a 13" laptop screen?
+3. **Report findings** — list every issue found, with the screenshot name and a concrete description
+4. **Do NOT suppress assertions to make the audit pass.** If an assertion fails, the UI has a bug. Fix the UI, not the assertion. If the assertion is genuinely wrong (testing the wrong thing), fix the assertion AND explain why.
+
+**Red flags for this step:**
+- "The assertion failed so I marked it as zoomed=True" → NO. That's suppressing a real bug.
+- "All assertions passed so the UI is fine" → NO. Assertions are a minimum bar, not a complete check.
+- "I didn't look at the screenshots because the report said PASS" → NO. Always look.
+
+**This is the verification step.** The `superpowers:verification-before-completion` skill requires running this before claiming work is done.
+
+---
+
+## Section 3: Mode Matrix & Tiers
+
+### Tier 1 — Always Check
+
+| Array config | Mode | Screenshot name |
+|---|---|---|
+| 1× 3D | normal (fit) | `t1_single_normal_fit` |
+| 1× 3D | normal (zoomed) | `t1_single_normal_zoom` |
+| 1× 3D | compact | `t1_single_compact` |
+| 1× 3D | multiview | `t1_single_multiview_fit` |
+| 1× 3D | multiview (zoomed) | `t1_single_multiview_zoom` |
+| 1× 4D (dim0=5) | qMRI full | `t1_single_qmri_full` |
+| 1× 4D (dim0=5) | qMRI compact | `t1_single_qmri_compact` |
+| 1× 3D | zen | `t1_single_zen` |
+| 2× 3D | compare | `t1_compare_fit` |
+| 2× 3D | compare (zoomed) | `t1_compare_zoom` |
+| 2× 3D | diff (A-B) | `t1_compare_diff` |
+| 2× 3D | compare + multiview | `t1_compare_multiview` |
+| 1× 3D | normal + ROI | `t1_single_roi` |
+| 1× 3D | compact + ROI | `t1_compact_roi` |
+
+### Tier 2 — Check When Relevant
+
+| Array config | Mode | Trigger keywords |
+|---|---|---|
+| 1× 2D | normal | `2d, basic` |
+| 1× 4D | normal | `4d, ndim` |
+| 1× 4D | mosaic (z) | `mosaic, z-grid` |
+| 1× complex | normal | `complex, dtype` |
+| 2× 3D | diff |A-B| | `diff` |
+| 2× 3D | diff |A-B|/|A| | `diff` |
+| 2× 3D | overlay | `overlay, wipe, diff` |
+| 2× 3D | wipe | `wipe, diff` |
+| 2× 3D | registration | `registration` |
+| 2× 4D | compare + qMRI | `qmri, compare` |
+| 2× 3D | diff + ROI | `roi, diff` |
+| 3× 3D | compare grid | `compare, grid, multi-array` |
+| 3× 4D | compare + qMRI | `qmri, compare, multi-array` |
+| 3× 3D | compare + multiview | `multiview, compare, multi-array` |
+| 4× 3D | compare grid | `compare, grid, multi-array` |
+| 3-4× 4D | compare + compact qMRI | `qmri, compare, compact, multi-array` |
+| 1× 3D + vfield | vector field normal | `vector, vfield` |
+| 1× 3D + vfield | vector field + ROI | `vector, roi` |
+| 2× 3D (1+vfield) | compare with vector field | `vector, compare` |
+
+---
+
+## Section 4: The Six+ Modes (Reference)
+
+| Mode | State flag | Scale function | Entry | Canvas elements |
+|------|-----------|---------------|-------|-----------------|
+| **Normal** | (default) | `scaleCanvas()` | — | `#canvas` |
+| **Compact** | compact mode active | `scaleCanvas()` | K / auto on zoom | `#canvas` + miniview |
+| **Multi-view** | `multiViewActive` | `mvScaleAllCanvases()` | v | `.mv-canvas` × 3 |
+| **Compare** | `compareActive` | `compareScaleCanvases()` | B / P | `.compare-canvas` × 2–6 |
+| **Diff** | `diffMode > 0` | `compareScaleCanvases()` | X (in compare) | `#compare-diff-canvas` |
+| **Registration** | `registrationMode` | `compareScaleCanvases()` | R (in compare) | 3rd `.compare-canvas` |
+| **qMRI** | `qmriActive` | `qvScaleAllCanvases()` | q | `.qv-canvas` × 3–6 |
+| **Compact qMRI** | qMRI compact toggle | `qvScaleAllCanvases()` | q (second press) | `.qv-canvas` × 3 (T1,T2,|PD|) |
+| **Zen** | zen mode | — | F | fullscreen, no chrome |
+| **Vector field** | vectorfield attached | — | U toggle arrows | arrows on canvas |
+
+**Orthogonal overlays** (can be active in any mode):
+- **ROI** (A key): rect → circle → freehand → off
+- **Histogram/Lebesgue** (w key): expanded colorbar with distribution
+- **Hover tooltip** (H key): pixel value follows cursor
+- **Overlay mask** (`overlay_sid` URL param): composited server-side
+
+---
+
+## Section 5a: Design Principles
+
+1. **No overlapping chrome** — UI elements must never visually overlap each other or the canvas. If two elements compete for the same space, one must hide (e.g. colorbar hides when histogram is open).
+
+2. **Consistent positioning** — an element appearing in mode A should appear in the same logical position in mode B. The miniview overlay and the mini 3D pane previewer must share a position (top-right).
+
+3. **Zoom never clips** — canvases must stay within viewport bounds at all zoom levels. In multi-canvas modes, canvases grow until constrained, then zoom together with a single shared miniview (top-right, showing one representative slice).
+
+4. **Maximize canvas real estate** — chrome is minimal and collapses when not needed. On a laptop screen, the array data is always the primary focus. No persistent toolbars or buttons.
+
+5. **Mode transitions are reversible** — toggling a mode on then off returns to the exact prior state. No leftover artifacts, no shifted elements, no orphaned DOM.
+
+6. **Orthogonal features compose cleanly** — ROI, vector field, histogram, colorbar, hover tooltip work independently. Enabling one must not break or interfere with another. ROI mode should be possible in any mode combination.
+
+7. **Multi-array consistency** — when multiple arrays are loaded, all canvases zoom/scroll/navigate together. Colormaps on side panes match; diff center pane uses an independent colormap and dynamic range.
+
+8. **Compare panes stay close** — pane slots shrink-wrap their canvas viewport when zoomed out so that panes remain adjacent for easy visual comparison. Never use fixed pane widths that create large gaps between canvases.
+
+---
+
+## Section 5b: Specific Rules (Growing Catalog)
+
+These rules are codified as DOM assertions in `tests/ui_audit.py`. When a new inconsistency is found and fixed, add a rule here AND a corresponding assertion in the audit script.
+
+| # | Rule | DOM assertion |
+|---|------|---------------|
+| R1 | Colorbar hides when histogram/Lebesgue is open | `#slim-cb-wrap` has `display:none` or `opacity:0` when Lebesgue mode active |
+| R2 | Miniview position matches mini 3D pane previewer | Miniview overlay bounding box is anchored top-right, same position as multiview pane previewer |
+| R3 | All canvases within viewport | Every `.compare-canvas`, `.mv-canvas`, `.qv-canvas`, `#canvas` bounding box fits within `window.innerWidth × innerHeight` |
+| R4 | Diff colormaps: sides same, center different | Colormap name on diff center pane differs from side panes |
+| R5 | Diff dynamic range is independent | vmin/vmax on diff center canvas differs from side panes |
+| R6 | Eggs don't overlap colorbar | Bounding boxes of `#mode-eggs` children don't intersect `#slim-cb-wrap` |
+| R7 | Fullscreen mode overlays chrome on canvas | `#info`, `#slim-cb-wrap` have `position:fixed` and glassmorphic styling when `body.fullscreen-mode` is active |
+| R8 | ROI hover info within viewport | `.cv-pixel-info` bounding box is within viewport |
+| R9 | No element jump on mode toggle | Pressing a mode toggle key then pressing it again returns bounding boxes to ±2px of original |
+| R10 | Compare panes aligned | All `.compare-canvas` elements share the same `y` coordinate (horizontal layout) or same `x` (vertical layout) |
+| R11 | Vector field arrows hidden when U toggled off | No arrow SVG/canvas elements visible after U press |
+| R12 | Histogram not visible when colorbar is in slim mode | Lebesgue expanded state is mutually exclusive with slim colorbar |
+| R13 | Colorbars don't overlap each other | No pair of colorbar elements (slim, compare-pane, mv, qv) have intersecting bounding boxes |
+| R14 | Minimap within viewport and not overlapping colorbars | `#minimap-canvas` bounding box is within viewport and doesn't intersect any colorbar |
+| R15 | Colorbar labels flank horizontally in all modes | Every `.cb-island`, `.compare-pane-cb-island`, `.qv-cb-island` uses `flex-direction: row` with vmin/vmax spans flanking the gradient canvas — never column layout with labels below |
+| R16 | Per-pane colorbar width matches canvas viewport width (diff mode only) | Each `.compare-pane-cb` and `.qv-cb` canvas CSS width equals its data canvas viewport width. Per-pane colorbars only visible in diff mode. |
+| R17 | Fullscreen mode eggs are visible over image | `#mode-eggs .mode-badge` elements have sufficient background opacity (>= 0.5) when `body.fullscreen-mode` is active, since they overlay the canvas |
+| R18 | Histogram has visible background distinct from page | When `_cbExpanded`, the histogram area has an explicit background fill matching the dynamic island aesthetic, not transparent over the page background |
+| R19 | Shared colorbar visible in all non-diff compare modes | `#slim-cb-wrap` is visible when `compareActive && !diffMode`. Per-pane colorbars hidden. |
+| R20 | Compare panes shrink-wrap when zoomed out | Pane slot width ≤ viewport canvas width + padding, not fixed to max available. Panes stay close for visual comparison |
+| R21 | Per-pane colorbars visible only in diff mode | `.compare-pane-cb-island` elements visible only when `diffMode > 0`. Three colorbars (left, center, right) at same vertical position. |
+| R22 | Array names include logo in compare mode | Each `.compare-title` contains SVG logo + name text, styled like `#array-name` |
+| R23 | Fullscreen mode overlays are glassmorphic islands | When `body.fullscreen-mode`, `#info` and `#slim-cb-wrap` have glassmorphic styling with `backdrop-filter: blur(12px)` |
+| R24 | Diff c/d keys are mouse-aware | When `diffMode > 0`, `c` and `d` keys affect center pane when `_mouseOverCenterPane`, side panes otherwise |
+| R25 | No duplicate colorbars in multiview | `#slim-cb-wrap` hidden when `multiViewActive` or `compareMvActive` (multiview has its own per-pane colorbars) |
+| R26 | Shared colorbar width capped in compare mode | `#slim-cb-wrap` width ≤ 500px in compare mode |
+| R27 | Mode eggs hidden during loading | `#mode-eggs` empty/hidden until at least one frame has been received |
+| R28 | Compare+multiview crosshair fade works | Crosshair lines in compare+multiview fade in/out on hover, scoped to the hovered array's panes |
+
+---
+
+## Section 5c: Colorbar Layout Invariant
+
+All colorbars across ALL modes follow the same structure: `[vmin span] [gradient canvas] [vmax span]` in a horizontal flex row inside a `.cb-island` container. This applies to:
+- Normal mode: `#slim-cb-wrap` with `#slim-cb-vmin`, `#slim-cb`, `#slim-cb-vmax`
+- Compare/diff: `.compare-pane-cb-island` with `.compare-pane-cb-val` spans + `.compare-pane-cb` canvas
+- qMRI: `.qv-cb-island` with `.qv-cb-val` spans + `.qv-cb` canvas
+
+**Never** use column layout with labels below. **Never** use `flex: 1` on colorbar canvases inside inline-flex islands (causes sizing loops). Always set explicit island width = viewport canvas width, with `box-sizing: border-box` so `.cb-island` padding doesn't inflate the width beyond the canvas. Always test with non-square arrays — square arrays hide width mismatches.
+
+**Colorbar-to-canvas gap**: The gap between canvas and colorbar must be visually consistent across modes. Both single and compare mode use the shared `#slim-cb-wrap` colorbar positioned via `chromeGap` (measured from `#info` bottom to canvas top). Per-pane colorbars (`.compare-pane-cb-island`) are only visible in diff mode.
+
+**Compare mode colorbar**: A single shared `#slim-cb-wrap` replaces per-pane colorbars. All arrays share colormap and dynamic range (union of all vmins/vmaxes). Histogram aggregates bins from all sessions. Per-pane colorbars only appear in diff mode (3 colorbars: left, center, right).
+
+---
+
+## Section 6: Common Feature Categories
+
+### Zoom / Canvas Sizing
+
+Four dedicated scale functions. When changing zoom behavior, check **all four**:
+
+- `scaleCanvas(w, h)` — Normal/Compact
+- `mvScaleAllCanvases()` — Multi-view
+- `compareScaleCanvases()` — Compare / Diff / Registration
+- `qvScaleAllCanvases()` — qMRI
+
+### Eggs (Mode Badges)
+
+Positioned by `positionEggs()` which branches by mode:
+- Normal: uses `#slim-cb-wrap` bounding box if visible, else canvas bottom
+- Multi-view: uses `#mv-cb-wrap` or estimates 36px below panes
+- Compare: walks `.compare-canvas-wrap` rects for tallest pane bottom
+- qMRI: uses `.qv-canvas-wrap` rects + 36px
+
+### Colorbar
+
+Separate per-mode drawing functions — no shared abstraction:
+
+| Mode | Function |
+|------|----------|
+| Normal | `drawSlimColorbar(markerFrac)` |
+| Compare | `drawComparePaneCb(idx)` + `drawAllComparePaneCbs()` |
+| Diff | `drawDiffPaneCb(vmin, vmax)` |
+| Registration | `drawRegBlendCb()` |
+| Multi-view | `drawMvCbs()` |
+| qMRI | Inline per view in `qvRender()` |
+
+### Keyboard Shortcuts
+
+The `keydown` handler on `#keyboard-sink` dispatches by active mode. New shortcuts must:
+1. Not conflict with mode-specific keys
+2. Have explicit guards when mode-specific (e.g., `if (!compareActive) return;`)
+3. Fall through correctly when multiple modes are active
+
+---
+
+## Section 7: Code-Area-to-Mode Mapping
+
+Use this to determine which tier 2 subsets to audit based on what code you're touching.
+
+| Code area | Tier 2 subsets to include |
+|-----------|--------------------------|
+| `scaleCanvas` / zoom / `userZoom` | `zoom, compact` — all zoom-related modes |
+| `compareScaleCanvases` / `.compare-` | `compare, diff, registration, grid, multi-array` |
+| `mvScaleAllCanvases` / `.mv-` | `multiview` — single + compare multiview |
+| `qvScaleAllCanvases` / `.qv-` / `qmri` | `qmri, compare` — single + compare qMRI, compact qMRI |
+| `positionEggs` / `renderEggs` / `#mode-eggs` | all modes (eggs appear everywhere) |
+| `drawSlimColorbar` / `#slim-cb` | `zoom, compact, diff` — colorbar visibility rules |
+| Lebesgue / histogram / `w` key | `zoom, compact, diff` — mutual exclusivity with colorbar |
+| ROI / `A` key / `.roi-` | `roi` — ROI across all modes |
+| `diffMode` / `X` key / `#compare-diff` | `diff` — all diff variants |
+| Vector field / `U` key / arrows | `vector` — normal, ROI, compare |
+| `#minimap` / miniview | `zoom, compact, multiview` — position consistency |
+| Overlay / `overlay_sid` | `overlay` — server-side compositing |
+| Layout / `G` key / grid | `grid, multi-array` — 3-4 array layouts |
+
+---
+
+## Section 8: Test Arrays
+
+The audit script creates these arrays to exercise different code paths:
+
+| Array | Shape | Purpose |
+|-------|-------|---------|
+| `arr_3d` | (20, 64, 64) float32 | Primary test array, 3D navigation |
+| `arr_3d_b` | (20, 64, 64) float32 | Second 3D for compare |
+| `arr_2d` | (100, 80) float32 | 2D baseline |
+| `arr_4d` | (5, 20, 32, 32) float32 | qMRI eligible (dim0=5) |
+| `arr_4d_b` | (5, 20, 32, 32) float32 | Second 4D for compare qMRI |
+| `arr_complex` | (20, 32, 32) complex64 | Complex dtype, triggers mag/phase/real/imag |
+| `arr_3d_qmri3` | (3, 20, 32, 32) float32 | 3-panel qMRI (dim0=3) |
+| `vf_3d` | (20, 64, 64, 3) float32 | Vector field (N+1 dims, last dim=3) |
+| `arr_3d_c` | (20, 64, 64) float32 | Third array for 3-pane compare |
+| `arr_3d_d` | (20, 64, 64) float32 | Fourth array for 4-pane grid |
+
+---
+
+## Red Flags — STOP
+
+- "I only implemented it for normal mode" → enumerate all affected modes now
+- "The colorbar is visible but the histogram is also showing" → R1 violation
+- "It works but I didn't check zoomed-in" → run both zoom levels
+- "ROI mode isn't relevant here" → ROI is always relevant, it's orthogonal
+- "Compare mode doesn't need this" → if it affects the canvas or chrome, compare needs it
+- "I'll update the audit script later" → update it in the same task as the rule
+- "The screenshots look fine to me" → also check the DOM assertions passed
+- "The assertion failed so I set zoomed=True to skip it" → that's suppressing a real bug, fix the UI
+- "All assertions passed so no need to look at screenshots" → assertions are a minimum bar, always visually inspect
+- "Vector field is separate" → still check it doesn't clash with the new feature

{arrayview-0.5.1 → arrayview-0.6.0}/.gitignore

@@ -16,12 +16,15 @@ wheels/
 CLAUDE.md
 debug/
 tests/snapshots/
+tests/ui_audit/
+tests/smoke_output/
 
 *.jl
 *.ipynb
-logs/
+dev/
 *.png
 !src/arrayview/_icon.png
-.worktrees/
 
-benchmarks/data
+benchmarks/data
+.superpowers/brainstorm
+site/

arrayview-0.6.0/AGENTS.md

@@ -0,0 +1,137 @@
+# ArrayView Agent Guide
+
+## Mission
+
+Interactive viewer for multi-dimensional arrays and medical/scientific volumes. Runs a FastAPI server + HTML/JS frontend displayed in a native window, browser, VS Code Simple Browser, or Jupyter inline iframe.
+
+**Display routing defaults (sane defaults per environment):**
+
+| Where you are | Default display |
+|---|---|
+| Jupyter kernel | inline iframe |
+| VS Code terminal (local or tunnel) | VS Code Simple Browser tab |
+| Julia | system browser |
+| otherwise (CLI, Python script) | native pywebview window |
+
+VS Code Simple Browser requires the bundled `arrayview-opener.vsix` extension. VS Code provides no public API for auto-opening Simple Browser tabs — the extension uses signal-file IPC. This is fragile; load the `vscode-simplebrowser` skill before touching it.
+
+## Architecture
+
+```
+CLI / Python API
+   |
+   +- view()        Python entry  (_launcher.py)
+   +- arrayview()   CLI entry     (_launcher.py)
+      |
+      +- FastAPI server  (_server.py)
+         +- /           viewer HTML
+         +- /shell      pywebview shell HTML
+         +- /ws/{sid}   WebSocket render updates
+         +- /load       register arrays
+         +- /ping       health check
+```
+
+## Core Files
+
+### Backend
+
+| File | Responsibility |
+|------|---------------|
+| `_launcher.py` | Entry points, process management, window/browser opening |
+| `_server.py` | FastAPI app, REST routes, WebSocket handlers, HTML templates |
+| `_session.py` | Sessions, global state, caches, render thread, constants |
+| `_render.py` | Rendering: colormaps, LUTs, slice extraction, RGBA/mosaic/RGB |
+| `_vscode.py` | Extension management, signal-file IPC, browser opening |
+| `_platform.py` | Platform/environment detection |
+| `_io.py` | Array I/O, format detection |
+| `_app.py` | **Compat shim only** — re-exports; add no logic here |
+
+### Frontend
+
+| File | Responsibility |
+|------|---------------|
+| `_viewer.html` | Viewer UI (single file, all JS/CSS embedded) |
+| `_shell.html` | Shell page for native tab/window management |
+
+### VS Code Extension
+
+| File | Responsibility |
+|------|---------------|
+| `vscode-extension/extension.js` | Polls signal file, opens `createWebviewPanel` |
+| `vscode-extension/package.json` | Extension metadata and version |
+| `arrayview-opener.vsix` | Packaged extension (auto-installed by Python) |
+
+## Skills
+
+Load the relevant skill before touching the corresponding area.
+
+| Skill | Load when... |
+|-------|-------------|
+| `vscode-simplebrowser` | Touching extension install, signal-file IPC, `_ensure_vscode_extension()`, `_VSCODE_EXT_VERSION`, or `vscode-extension/` |
+| `invocation-consistency` | Any server startup, display-opening, or environment-detection change |
+| `ui-consistency-audit` | Any visual feature: zoom, colorbars, canvas events, rendering modes. Or UI changes: keyboard shortcuts, layout, new panels |
+| `frontend-designer` | Any styling/layout change to `_viewer.html` |
+| `docs-style` | Updating README, in-app help overlay, or docstrings |
+| `task-workflow` | Feature or fix tasks |
+
+## Non-Negotiables
+
+- Always use `localhost` (not `127.0.0.1`) — required for VS Code port forwarding
+- Never `--force` reinstall the extension if the correct version is already on disk
+- Do not add logic to `_app.py` — compat shim only
+- Avoid orphan processes; shutdown must be automatic
+- Do not regress working display paths when fixing another
+
+## Testing
+
+```bash
+uv sync --group test && uv run playwright install chromium
+
+uv run pytest tests/test_api.py -v       # HTTP API (~2s)
+uv run pytest tests/test_cli.py -v       # CLI entry points
+uv run pytest tests/test_browser.py -v   # Playwright (~100s)
+uv run pytest tests/                     # all
+
+uv run python tests/visual_smoke.py      # screenshots → tests/smoke_output/
+```
+
+Visual baselines: `tests/snapshots/` — delete a file to reset.
+
+| What changed | Run |
+|---|---|
+| Server / API | `test_api.py` |
+| CLI | `test_cli.py` |
+| Viewer UI | `test_browser.py` + `visual_smoke.py` |
+| VS Code / platform | manual: VS Code local terminal, VS Code tunnel |
+
+## VS Code Integration
+
+All key functions live in `_vscode.py`:
+- `_ensure_vscode_extension()` — installs VSIX only if version not already on disk
+- `_open_via_signal_file()` — writes signal; extension polls and opens panel
+- `_schedule_remote_open_retries()` — retry writes for tunnel/first-install latency
+- `_configure_vscode_port_preview()` — port forwarding settings
+
+`_VSCODE_EXT_VERSION` in `_vscode.py` must match `vscode-extension/package.json`.
+Rebuild: `cd vscode-extension && vsce package -o ../src/arrayview/arrayview-opener.vsix`
+
+## High-Risk Areas
+
+- Extension install: skip `--force` if correct version on disk; clean stale dirs first
+- IPC hook recovery when env vars are stripped by `uv run` or subprocess wrappers
+- tmux: `VSCODE_IPC_HOOK_CLI` not inherited through tmux-server; must walk client PIDs
+- Signal routing: local → per-window targeted file; remote/tunnel → shared fallback
+- Julia: always subprocess (GIL); never run server in-process
+- Port forwarding in tunnel environments; shutdown lifecycle and orphan process prevention
+
+## Documentation
+
+Docs live in `docs/` (MkDocs Material site) and `README.md` (minimal quickstart).
+
+**Style:** quiet confidence — short sentences, lead with code, imply depth rather than explain everything. No verbose prose, no "Note:", no emojis. Load the `docs-style` skill before editing.
+
+**Keep docs in sync:** when a commit adds, changes, or removes user-facing behavior (new shortcut, changed flag, removed feature), update the relevant docs page and README before committing. Skip this for purely internal changes.
+
+## Source of Truth
+
+End-user usage: `README.md` and `docs/`