arrayview 0.20.0__tar.gz → 0.21.0__tar.gz

arrayview-0.21.0/.agents/skills/frontend-designer/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: frontend-designer
+description: Use when making styling or layout changes to `_viewer.html`. Keeps UI work aligned with arrayview's established visual language without dragging in release-only or cross-mode audit steps by default.
+---
+
+# ArrayView Frontend Design Skill
+
+## Fast Path
+
+Use this for real styling/layout work.
+For behavior-only edits, code cleanup, or tiny copy changes with no design decision, do not expand beyond this file unless blocked.
+
+## Design Direction
+
+Minimal chrome. The array is the product.
+
+- Controls stay dim or hidden until interaction
+- Text is small and monospaced
+- No decorative chrome
+- All four themes must work
+
+## Core Rules
+
+- Use existing CSS vars only. Especially: `--surface`, `--border`, `--text`, `--muted`, `--active-dim`, `--overlay-bg`, `--radius`, `--radius-lg`.
+- Never hardcode colors.
+- Typography is always monospace:
+  `'SF Mono', ui-monospace, 'Cascadia Code', 'JetBrains Mono', monospace`
+- Match the existing size scale. Most UI text is `10px` to `13px`; headers are `15px` to `16px`.
+- Keep inactive UI dimmed with color/opacity, not permanent visibility.
+- Prefer opacity/color transitions over motion that changes layout.
+- Canvas dimensions are owned by JS layout functions, not CSS.
+- Test themes with `T`.
+
+## Defaults
+
+- Passive info: `var(--muted)`
+- Active text: `var(--text)`
+- Selected/highlighted state: `var(--active-dim)`
+- Panel/overlay: `var(--surface)` + `1px solid var(--border)` + `var(--radius-lg)`
+- Modal backdrop: `var(--overlay-bg)` with the existing blur treatment
+
+## Avoid
+
+- Persistent toolbar-style controls
+- New font families
+- New one-off sizes or accent colors
+- Layout animations that fight canvas sizing
+
+## Before Shipping
+
+- [ ] All four themes still look correct
+- [ ] No hardcoded color values
+- [ ] Font and sizing match existing UI
+- [ ] New panels/overlays use existing surface/border/radius tokens
+- [ ] `viewer-ui-checklist` is used only if the user asked for docs/help/test sync or this is release prep
+- [ ] `modes-consistency` is used if canvas/colorbar/layout behavior crosses modes

arrayview-0.21.0/.agents/skills/modes-consistency/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: modes-consistency
+description: Use when a visual feature touches canvas rendering, zoom, eggs, colorbars, shortcuts, or layout across modes. Keeps implementation and verification consistent without escalating to a full audit by default.
+---
+
+# ArrayView Modes Consistency Checklist
+
+## Fast Path
+
+Use this when a change can affect more than one viewing mode.
+Skip it for tiny local text/style tweaks that do not touch canvas behavior, colorbars, shortcuts, layout, or mode transitions.
+If the user explicitly asks for a full visual audit or release validation, use `ui-consistency-audit` instead.
+
+## Rule
+
+If a feature applies to more than one mode, implement it for all applicable modes now. Shipping “normal mode only” is a bug.
+
+## Mode Map
+
+| Mode | Main owner |
+|------|------------|
+| Normal | `scaleCanvas()` |
+| Multi-view | `mvScaleAllCanvases()` |
+| Compare / Diff / Registration | `compareScaleCanvases()` |
+| qMRI | `qvScaleAllCanvases()` |
+
+## Check These Areas
+
+- Zoom or canvas sizing: update every relevant scale function
+- Eggs: update `positionEggs()` branches
+- Colorbars and range interaction: check each per-mode colorbar path
+- Shortcuts: guard by mode and update help/registry consistently
+- Canvas listeners: attach to the correct canvas set, not just `#canvas`
+- New UI state: persist it through snapshot/restore if needed
+
+## Backend Note
+
+If the feature changes rendered image composition, check the rendering backend in:
+
+- `_routes_rendering.py` for `/slice`, `/diff`, and related routes
+- `_render.py` / `_overlays.py` for overlay compositing such as `_composite_overlay_mask()`
+
+Do not treat `_app.py` as the implementation surface; it is a compat shim.
+
+## Minimal Workflow
+
+1. Identify which modes the feature should affect.
+2. Implement normal mode first.
+3. Implement compare-family behavior.
+4. Implement multiview behavior.
+5. Implement qMRI behavior if applicable.
+6. Verify snapshot/restore if new state was added.
+
+## Red Flags
+
+- Only normal mode was changed
+- Similar logic diverges between `scaleCanvas()` and `compareScaleCanvases()`
+- A listener was attached only to `#canvas`
+- Render-route params changed in one backend path but not the others
+
+## Verification
+
+- [ ] Works in normal view
+- [ ] Works in compare or diff if applicable
+- [ ] Works in multiview if applicable
+- [ ] Works in qMRI if applicable
+- [ ] Eggs/colorbars/layout anchors still line up after the change

{arrayview-0.20.0 → arrayview-0.21.0}/.agents/skills/ui-consistency-audit/SKILL.md

@@ -5,6 +5,16 @@ description: Use when the user explicitly requests a full visual audit, when val
 
 # ArrayView UI Consistency Audit
 
+## Read Budget
+
+On entry, read only:
+
+- `Rule`
+- `Phase 1`
+- the tier commands in `Phase 2`
+
+Treat the mode matrix and rule catalog below as reference sections to revisit only if the task actually reaches the full audit stage.
+
 ## Rule
 
 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.21.0/.agents/skills/visual-bug-fixing/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: visual-bug-fixing
+description: Use when fixing a real visual bug, layout glitch, rendering artifact, or UI regression in arrayview. Requires visual evidence, but keeps the default path targeted unless the bug has broad cross-mode risk.
+---
+
+# Visual Bug Fixing
+
+## Rule
+
+Fix visual bugs with evidence, not guesswork. Capture the broken state, fix the cause, capture the result, then run only as much regression coverage as the risk justifies.
+
+## Use This When
+
+- The user reports a visual bug
+- You see a layout/rendering regression while working
+- A screenshot-based test or `tests/ui_audit.py` fails
+
+Do not use this for brand-new feature design or docs/test sync work.
+
+## Targeted Path
+
+For a small bug in one known area:
+
+1. Capture one baseline screenshot of the broken state
+2. Inspect the owning code path
+3. Apply the smallest real fix
+4. Capture one post-fix screenshot
+5. Check the most likely neighboring mode(s)
+
+Escalate to the broader audit path only when the bug touches shared layout, shared chrome, zoom, or multiple modes.
+
+## Where To Look
+
+| Area | Owner |
+|------|-------|
+| UI structure, CSS, JS layout | `_viewer.html` |
+| Rendering routes | `_server.py` + `_routes_rendering.py` |
+| Render/compositing helpers | `_render.py`, `_overlays.py` |
+| Colorbar behavior | `ColorBar` class in `_viewer.html` |
+
+Do not treat `_app.py` as the implementation surface; it is a compat shim.
+
+## Diagnose First
+
+- CSS positioning / overflow / z-index problem?
+- Layout calculation bug in a mode-specific scale function?
+- Missing branch for compare, multiview, or qMRI?
+- Zoom-specific issue?
+- Animation/timing issue? If yes, use the animation verification pattern instead of static screenshots alone.
+
+## Common Fix Patterns
+
+- Overlap bug: inspect bounds and z-order
+- Wrong size: trace the relevant scale/layout function
+- Mode-only regression: find the missing mode branch
+- Render mismatch: inspect route params and backend render helpers
+
+## Broader Audit Path
+
+Use this when the bug has shared-chrome or cross-mode risk:
+
+```bash
+uv run python tests/ui_audit.py --tier 1
+```
+
+Go to tier 2 only when the affected feature or regression area actually needs it.
+
+## Red Flags
+
+- The fix works only in normal mode
+- The patch hides the symptom instead of fixing placement/ownership
+- Verification skipped screenshots entirely
+- `_app.py` was edited for new behavior
+
+## Verification
+
+- [ ] Baseline screenshot captured
+- [ ] Post-fix screenshot captured
+- [ ] Nearby modes checked based on risk
+- [ ] `tests/ui_audit.py --tier 1` run if the bug touched shared layout/chrome/cross-mode behavior

{arrayview-0.20.0 → arrayview-0.21.0}/.mex/AGENTS.md

@@ -1,11 +1,12 @@
 ---
 name: agents
 description: Lightweight pointer to ROUTER.md for task routing.
-last_updated: 2026-04-29
+last_updated: 2026-05-01
 ---
 
 # arrayview
 
-Use `.mex/ROUTER.md` first when you need project state, routing, or a matching task pattern.
+Use `.mex/ROUTER.md` at the start of a new task or when the task family changes.
+Do not reload it for routine follow-up work in the same area unless blocked.
 After finishing work, update any stale `.mex` files you touched and run `mex check --quiet`.
 If drift remains, use `.mex/sync.sh` for the repo-local sync path.

{arrayview-0.20.0 → arrayview-0.21.0}/.mex/ROUTER.md

@@ -20,11 +20,20 @@ edges:
     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-29
+  - target: ../DESIGN.md
+    condition: when the task touches design philosophy — new features, UI changes, mode additions, or interaction model decisions
+last_updated: 2026-05-02
 ---
 
 # arrayview — Router
 
+## Fast Path
+
+- New task or changed task family: read this file, then load at most one pattern and one context file.
+- Follow-up in the same thread and same subsystem: do **not** reopen this router. Reuse what is already loaded unless blocked.
+- Small localized `_viewer.html` fix with a known symbol: go straight to exact code search. Do **not** auto-load `context/frontend.md`.
+- Normal work should **not** load `.mex/SETUP.md`, `.mex/SYNC.md`, or `patterns/README.md`. Those are scaffold-maintenance files only.
+
 ## 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).
 
@@ -50,6 +59,17 @@ Python package for interactively viewing multi-dimensional arrays (numpy, NIfTI,
 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.
+6. For follow-up work in the same thread: prefer reusing already-loaded context over reopening router/context/pattern files.
+
+## Common Cases
+
+| Situation | Load |
+|-----------|------|
+| Follow-up in same area, no task-family change | No new `.mex` files by default |
+| Small `_viewer.html` tweak, exact function/id already known | Exact `rg` + narrow code read only |
+| `_viewer.html` change touching modes, reconcilers, keybind registry, or unfamiliar sections | `patterns/frontend-change.md`, then `context/frontend.md` only if still needed |
+| Backend/server change in a known file family | Matching pattern first, then one context file only if blocked |
+| Release validation or broad cross-mode audit | Matching pattern + relevant context file(s) deliberately |
 
 ## Current Project State
 
@@ -71,11 +91,12 @@ Load `context/project-state.md` only when you need active-workstream or recent-s
 | Adding a server route / WebSocket endpoint | `patterns/add-server-endpoint.md` |
 | Visual bugs / render artifacts | `patterns/debug-render.md` |
 | Verifying animation changes | `patterns/animation-verify.md` |
+| Design philosophy, new features, UI changes, mode additions, interaction model | `DESIGN.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.
+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, and do not reopen docs on routine follow-ups.
 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`.

{arrayview-0.20.0 → arrayview-0.21.0}/.mex/context/architecture.md

@@ -18,7 +18,7 @@ edges:
     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-29
+last_updated: 2026-05-05
 ---
 
 # Architecture
@@ -54,11 +54,12 @@ pywebview, or system browser).
 - **`_server.py`** — FastAPI app initialization, route-registration orchestrator, and infrastructure routes. Feature domains are delegated to `_routes_*.py` modules via `register_*()` calls. Remaining inline routes are `/`, `/ping`, `/colormap/{name}`, `/shell`, and the GSAP asset route that serves `src/arrayview/gsap.min.js`, plus shared helpers like `get_session_or_404()`.
 - **`_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()`).
+- **`_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`.
 - **`_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 extension install/management, signal-file IPC, shared-memory IPC, webview panel and direct webview opening.
+- **`_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.
 - **`_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`.
 

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

@@ -0,0 +1,83 @@
+---
+name: frontend
+description: Deeper _viewer.html map for cross-section frontend work. Do not load for small localized follow-up fixes with a known symbol.
+triggers:
+  - "_viewer.html"
+  - "reconciler"
+  - "command registry"
+  - "GUIDE_TABS"
+  - "modeManager"
+  - "ColorBar class"
+  - "LayoutStrategy"
+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-05-01
+---
+
+# Frontend (_viewer.html)
+
+Load this only when the task crosses sections or when the relevant symbol is not already known.
+For a small follow-up tweak, prefer exact code search in `_viewer.html` and skip this file.
+
+`_viewer.html` is a single-file frontend with inline CSS and JS. No build step.
+
+## Load This When
+
+- The change touches reconcilers, mode transitions, `modeManager`, or layout auto-pickers
+- A keybind/command change needs the registry + `GUIDE_TABS` rules
+- The task spans multiple frontend subsystems and local code reads are no longer enough
+- You need the high-level map before editing an unfamiliar area
+
+## Skip This When
+
+- The user is asking for ideas, review, or a tiny follow-up fix in one known function/section
+- The target id/function/command is already known and can be reached with one exact `rg`
+- The task is local styling or text copy near an already-known DOM node
+
+## Quick Anchors
+
+- 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`
+- Layout/scale: grep `scaleCanvas`, `mvScaleAllCanvases`, `compareScaleCanvases`, `qvScaleAllCanvases`
+- Colorbars: grep `ColorBar class`, `drawSlimColorbar`, `drawMvColorbar`
+
+## Rules That Matter
+
+- Visibility changes belong in reconcilers, not scattered `style.display` or `classList` toggles
+- Keybind changes must update both the command/keybind registry and `GUIDE_TABS`
+- Reuse shared layout helpers for viewport/layout decisions; do not add ad hoc per-mode heuristics
+- `ColorBar` usage is mixed legacy/new: stay consistent within the section you touch
+- Canvas dimensions should be owned by the mode scale/layout functions, not ad hoc writes
+
+## Mode Map
+
+| Area | Main owner |
+|------|------------|
+| Normal / immersive / compact | `scaleCanvas()` |
+| Multiview / ortho | `mvScaleAllCanvases()` |
+| Compare / diff / registration | `compareScaleCanvases()` |
+| Compare + MV | `compareMvScaleAllCanvases()` |
+| qMRI / qMRI mosaic | `qvScaleAllCanvases()` |
+| MIP | dedicated WebGL path |
+
+## Important Concepts
+
+- **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
+- **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
+
+## Verification Reminder
+
+If a change touches multiple modes, reconcilers, or layout routing, verify cross-mode behavior instead of trusting a single local interaction.

{arrayview-0.20.0 → arrayview-0.21.0}/.mex/context/project-state.md

@@ -7,7 +7,7 @@ triggers:
   - "recent work"
   - "active feature"
   - "shipped recently"
-last_updated: 2026-04-29
+last_updated: 2026-05-05
 ---
 
 # Project State
@@ -20,7 +20,7 @@ last_updated: 2026-04-29
 - 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`
 - 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
+- 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
 - 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

{arrayview-0.20.0 → arrayview-0.21.0}/.mex/patterns/INDEX.md

@@ -26,6 +26,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-render.md](debug-render.md) | Visual rendering failures — wrong colors, blank canvas, artifacts, colormap issues |
 | [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 |
 | [frontend-change.md](frontend-change.md) | Any change to `_viewer.html` — CSS, JS, new mode, keybind, layout, colorbar |

arrayview-0.21.0/.mex/patterns/debug-vscode-extension-python.md

@@ -0,0 +1,95 @@
+---
+name: debug-vscode-extension-python
+description: Diagnosing VS Code custom-editor or direct-webview failures caused by Python resolution, workspace virtualenv drift, or uv fallback behavior.
+triggers:
+  - "ArrayView failed to open"
+  - "Python process exited with code 1"
+  - "vscode extension"
+  - "custom editor"
+  - "remote tunnel"
+  - "uv run --with arrayview"
+  - "python 3.12"
+edges:
+  - target: context/conventions.md
+    condition: when making code changes after confirming the failure mode
+last_updated: 2026-05-06
+---
+
+# Debug VS Code Extension Python
+
+## Context
+
+The VS Code opener extension starts ArrayView in two different ways:
+1. Signal-file mode from Python (`view(...)`, CLI, Julia, etc.)
+2. Custom-editor mode when the user clicks `.npy` / `.nii` / similar files in VS Code
+
+Custom-editor mode lives in `vscode-extension/extension.js` and spawns:
+- explicit `pythonPath` from a signal file when present
+- workspace `.venv/bin/python` when present
+- `python3`
+- `python`
+- `uv run --python 3.12 --with arrayview python`
+
+ArrayView requires Python `>=3.12`. A common tunnel failure is a workspace `.venv`
+or default shell Python at `3.11`, which makes the final `uv` fallback fail with
+an unsatisfiable dependency error.
+
+## Steps
+
+1. **Check the extension log first**
+   ```bash
+   tail -n 120 ~/.arrayview/extension.log
+   ```
+   Look for `CUSTOM-EDITOR:`, `PYTHON: spawning`, stderr lines, and the final exit code.
+
+2. **Identify which candidate failed**
+   The log shows the exact command order. Typical failure pattern:
+   ```
+   PYTHON: spawning /path/to/.venv/bin/python -m arrayview --mode stdio file.npy
+   PYTHON: ... No module named arrayview
+   PYTHON: spawning uv run --python 3.12 --with arrayview python -m arrayview --mode stdio file.npy
+   ```
+
+3. **Reproduce from the failing workspace root**
+   ```bash
+   timeout 10s sh -c 'uv run --python 3.12 --with arrayview python -m arrayview --mode stdio file.npy </dev/null'
+   ```
+   Success is a `SESSION:{...}` line on stderr. If it exits `1`, keep the stderr.
+
+4. **Check the workspace virtualenv directly**
+   ```bash
+   .venv/bin/python - <<'PY'
+   import arrayview, sys
+   print(sys.executable)
+   print(arrayview.__file__)
+   print(getattr(arrayview, '__version__', 'missing'))
+   PY
+   ```
+   If this raises `ModuleNotFoundError`, the workspace `.venv` exists but does not
+   have ArrayView installed.
+
+5. **Interpret the usual root causes**
+   - `No module named arrayview` from `.venv/bin/python`: project env exists but lacks ArrayView
+   - `current Python version ... does not satisfy Python>=3.12`: the fallback is using an older interpreter
+   - `SESSION:{...}` appears: stdio startup is healthy; any remaining issue is on the extension/webview side
+
+6. **If editing `extension.js`**
+   Follow the VS Code extension skill checklist: bump `vscode-extension/package.json`, bump `_VSCODE_EXT_VERSION` in `src/arrayview/_vscode_extension.py`, rebuild `src/arrayview/arrayview-opener.vsix`, and verify the embedded version.
+
+## Gotchas
+
+- Running `python -m arrayview --mode stdio ...` directly from a shell script without redirecting stdin can feed shell text into the stdio server. Use `</dev/null` for bounded startup checks.
+- In tunnel workspaces, the clicked-file custom editor does **not** use the current repo checkout automatically unless that workspace `.venv` points to it.
+- A reboot or deleting `~/.vscode-server` can change the default interpreter resolution without changing the extension code.
+
+## Verify
+
+- [ ] `~/.arrayview/extension.log` shows the expected candidate order
+- [ ] The failing workspace reproducer emits `SESSION:{...}` with the intended interpreter
+- [ ] If `extension.js` changed, `vscode-extension/package.json`, `_VSCODE_EXT_VERSION`, and the VSIX version all match
+- [ ] After reinstalling or reloading, the custom editor opens the target array without `Python process exited with code 1`
+
+## Update Scaffold
+- [ ] Update `.mex/context/project-state.md` if the shipped fallback behavior changed
+- [ ] Update any `.mex/context/` files that are now out of date
+- [ ] Add this pattern to `.mex/patterns/INDEX.md`

arrayview-0.21.0/.mex/patterns/frontend-change.md

@@ -0,0 +1,72 @@
+---
+name: frontend-change
+description: Editing `_viewer.html`. Prefer exact code-local search first; load deeper frontend context only when the change crosses sections or modes.
+triggers:
+  - "_viewer.html"
+  - "keyboard shortcut"
+  - "layout"
+  - "reconciler"
+  - "GUIDE_TABS"
+edges:
+  - target: context/frontend.md
+    condition: when the change spans multiple frontend sections or the target area is not already known
+  - target: context/architecture.md
+    condition: when understanding how the frontend connects to the server
+  - target: context/conventions.md
+    condition: for shared conventions and the Verify Checklist
+  - target: patterns/debug-render.md
+    condition: when the change produces wrong visual output
+last_updated: 2026-05-01
+---
+
+# Frontend Change
+
+## Fast Path
+
+- If the target function/id/section is already known, do **not** load extra `.mex` files first.
+- Run one exact `rg`, read one narrow local slice, then edit.
+- Load `context/frontend.md` only if the change touches reconcilers, mode routing, command registry, or another unfamiliar cross-section area.
+
+## Context
+
+The frontend lives in `src/arrayview/_viewer.html`. No build step. No separate files.
+Section separators are the navigation primitive:
+- CSS: `/* ── Section Name ── */`
+- JS: `// ── Section Name ──`
+
+## Steps
+
+1. If the desired behavior is still ambiguous, ask 2-3 plain-English clarification questions before reading git history, large diffs, or broad sections of `_viewer.html`.
+2. Scope the affected modes/panes. If the user explicitly asked for a full visual check, or this is release validation, invoke `ui-consistency-audit`.
+3. Navigate by exact identifier or section separator, not broad keyword sweeps.
+4. Read only the local CSS/JS slice you need.
+5. Make the change in place and preserve section separator style.
+6. If adding a keyboard shortcut: update both the command/keybind registry and `GUIDE_TABS`.
+7. If adding a new mode: register it in the `Mode Registry`.
+8. Run narrow verification for the touched behavior.
+9. If the change affects mode routing/layout behavior across modes, run the targeted mode test.
+10. Only run the broader visual audit path when explicitly requested or doing release validation.
+
+## Gotchas
+
+- Never sweep `_viewer.html` broadly when a known symbol or section marker can get you there.
+- Modes are exclusive; mode-entry work often needs explicit exit or reconcile logic.
+- The help overlay is static via `GUIDE_TABS`; it is easy to forget.
+- Some colorbars use `ColorBar`, some use legacy code. Do not mix styles within one local path.
+- Reuse shared layout helpers for layout auto-pickers instead of adding new heuristics.
+- Full visual audit is not the default path.
+
+## Verify
+
+- [ ] Section separator style matches: `/* ── Section Name ── */` (CSS) or `// ── Section Name ──` (JS)
+- [ ] No new external JS/CSS files created — everything stays in `_viewer.html`
+- [ ] Help overlay updated if a keyboard shortcut was added or changed
+- [ ] Narrow verification for the touched behavior completed
+- [ ] If full visual audit was requested, or this is release validation, `ui-consistency-audit` and `uv run python` on `tests/visual_smoke.py` pass
+- [ ] If mode routing/layout behavior changed across modes, `uv run pytest` on `tests/test_mode_consistency.py` passes
+
+## Debug
+
+If `visual_smoke.py` fails: see `patterns/debug-render.md`.
+If the mode doesn't activate: check Mode Registry — the `enter()` function must be registered by exact mode name string.
+If layout breaks in one environment but not others: check mode-specific CSS rules; immersive/compact mode may override your styles.

{arrayview-0.20.0 → arrayview-0.21.0}/AGENTS.md

@@ -32,6 +32,16 @@ Use **subagent-driven development**. Work in **feature branches**.
 
 Read `CONTRIBUTING.md` before any user-facing change or PR.
 
+For follow-up work in `src/arrayview/_viewer.html`, do not run broad searches.
+Do not use regex alternations or generic keyword sweeps across `_viewer.html`.
+Search for one exact identifier at a time: an id, function name, command id, or
+section marker already suggested by the user or current context. After each hit,
+read only one narrow `sed` window around the match. If the needed identifier is
+not known, ask or infer from recent context instead of exploring broadly. If more
+than three exact searches would be needed, stop and explain why before continuing.
+Do not reload `.mex` docs or skills on small follow-up UI fixes unless the task
+clearly needs fresh context.
+
 ## Testing
 
 Verify narrowly — do not run the full suite unless asked.