arrayview 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -0,0 +1,152 @@
+---
+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 | Key detection | Server model |
+|------|------------|--------------|-------------|
+| **CLI** | `arrayview()` in `_app.py` | — (always CLI path) | `_run_server_subprocess()` or in-process thread |
+| **Python script** | `view(arr)` | `_in_jupyter()` → False | In-process daemon thread |
+| **Jupyter / VS Code interactive** | `view(arr)` | `_in_jupyter()` → True | In-process daemon thread |
+| **Julia (PythonCall)** | `view(arr)` | `_is_julia_env()` → True | Always subprocess (`_view_julia()`) |
+| **VS Code tunnel / SSH remote** | `arrayview()` or `view()` | `_is_vscode_remote()` → True | Subprocess server |
+| **Plain SSH (no VS Code)** | `arrayview()` or `view()` | `SSH_CONNECTION` set, no VS Code remote | In-process or subprocess; prints port-forward hint |
+
+## Key Detection Functions (all in `_app.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 → subprocess + extension routing
+_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)
+```
+
+## Feature Categories & Where Each Path Diverges
+
+### Server Lifecycle
+
+| Path | Server model | Implication |
+|------|-------------|-------------|
+| CLI | Background thread in `main()` → blocks until Ctrl-C | `_shutdown_event` drives cleanup |
+| Python script | `_start_server_thread()` → daemon thread | Dies with caller process |
+| Jupyter | `_start_server_thread()` → daemon thread | Persists across cells; port reuse matters |
+| Julia | `_view_julia()` spawns detached subprocess | Caller (Julia) may not share GIL; subprocess manages its own lifecycle |
+| VS Code remote | Subprocess via `_run_server_subprocess()` | Caller exits; server stays alive independently |
+| Plain SSH | In-process or subprocess | No GUI; user must port-forward manually |
+
+When changing server startup or shutdown logic, check whether daemonized threads, subprocess reaping, and port reuse are all handled correctly for each path.
+
+### Browser / Display Opening
+
+| Path | Opens how | Key function |
+|------|-----------|-------------|
+| CLI local | Native window (`pywebview`) OR system browser | `_open_webview_with_fallback()` → `_open_browser()` |
+| Python script local | Same as CLI local | Same |
+| Jupyter | Inline IFrame via `IPython.display.IFrame` | `view()` returns IFrame object |
+| Julia | System browser via subprocess signal | `_view_julia()` writes signal file |
+| VS Code terminal (local) | VS Code Simple Browser via extension | `_open_via_signal_file()` + `_ensure_vscode_extension()` |
+| VS Code tunnel/remote | VS Code Simple Browser on *client* side | signal file + extension + port auto-forward |
+| Plain SSH | Prints `ssh -L <port>:localhost:<port>` hint | `_open_browser()` fallback |
+
+When changing URL construction, port logic, or display routing, trace through `_open_browser()` and its callers for each path — particularly the VS Code tunnel path where the *client's* VS Code picks up the signal file.
+
+### VS Code Extension (`arrayview-opener.vsix`)
+
+- Extension is auto-installed by `_ensure_vscode_extension()` when `_in_vscode_terminal()` is True
+- Version must match `_VSCODE_EXT_VERSION` in `_app.py` AND `vscode-extension/package.json`
+- After rebuilding the VSIX: update `_VSCODE_EXT_VERSION` in `_app.py`
+- IPC hook may be stripped by `uv run` → `_find_vscode_ipc_hook()` walks parent process env
+- Tunnel path: extension must configure `remote.portsAttributes` to make port public/silent
+
+### Port & URL Construction
+
+- Always use `localhost` (not `127.0.0.1`) so VS Code port-forwarding works
+- Port default: `8123`; CLI: `--port` flag; `view()`: `port=` kwarg
+- Compare mode URLs include `?compare_sid=...&compare_sids=...`
+- Overlay URLs include `?overlay_sid=...`
+- Mosaic/qMRI state is in the JS (not URL params); no server changes needed for those
+
+### Julia-Specific Constraints
+
+- GIL conflicts: never run server in-process when `_is_julia_env()` is True
+- `_view_julia()` starts a detached subprocess running `arrayview_server` CLI tool
+- Array data is serialized to a temp `.npy` file and loaded by the subprocess
+- Julia arrays use PythonCall → numpy conversion before any arrayview API call
+- No interactive stdin in subprocesses; all params must be 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 (use Julia path instead)
+- `inline=True` → returns `IPython.display.IFrame`; caller must return it from the cell for display
+- Port reuse: calling `view()` multiple times reuses same port and server if already running
+- `window='native'` override still works in Jupyter; viewer opens as separate window
+
+## Step-by-Step Checklist
+
+When implementing a new feature, ask:
+
+1. **Does it touch server startup, teardown, or port selection?**
+   - Test CLI (`uv run arrayview file.npy`) — server must start and terminate cleanly
+   - Test Python script (`python script.py`) — daemon thread must not orphan
+   - Test Jupyter cell — repeated calls must not fail on port-already-in-use
+   - Check Julia path — `_view_julia()` must pass any new params via CLI flag or file
+
+2. **Does it touch browser/display opening?**
+   - Test local native window (macOS) — `pywebview` opens correctly
+   - Test local system browser — `open http://localhost:8123` path works
+   - Test VS Code terminal — Simple Browser opens via extension signal file
+   - Test VS Code tunnel — route reaches client-side Simple Browser, not remote host browser
+   - Verify `_ensure_vscode_extension()` installs/updates if VSIX changed
+
+3. **Does it touch URL construction or query params?**
+   - Verify `localhost` (not `127.0.0.1`)
+   - Verify all modes still get the right params (compare, overlay, vectorfield)
+
+4. **Does it touch environment detection?**
+   - Check the detection order in `view()`: Julia → Jupyter → VS Code remote → VS Code terminal → local
+   - Any new detection must not break the fallback chain for paths it shouldn't match
+   - `_find_vscode_ipc_hook()` walks up to 12 parent processes — new subprocess wrappers may need the same treatment
+
+5. **Does it change the VS Code extension?**
+   - Rebuild VSIX: `cd vscode-extension && vsce package -o ../src/arrayview/arrayview-opener.vsix`
+   - Bump `_VSCODE_EXT_VERSION` in `_app.py` and `vscode-extension/package.json` together
+   - Test install in a fresh VS Code profile
+
+## Validation Matrix
+
+After implementing, run through this matrix manually or in CI:
+
+| Check | CLI | Python script | Jupyter | Julia | VS Code local | VS Code tunnel |
+|-------|-----|--------------|---------|-------|--------------|----------------|
+| Server starts | ✓? | ✓? | ✓? | ✓? | ✓? | ✓? |
+| Array loads & renders | ✓? | ✓? | ✓? | ✓? | ✓? | ✓? |
+| Display opens (window/browser/inline) | ✓? | ✓? | inline IFrame | browser | Simple Browser | Simple Browser on client |
+| Ctrl-C / kernel stop cleans up | ✓? | ✓? | ✓? | ✓? | ✓? | ✓? |
+| Compare mode works (if file-based) | ✓? | N/A | N/A | N/A | ✓? | ✓? |
+
+Quick automated checks:
+```bash
+uv run pytest tests/test_api.py -x          # API contract
+uv run pytest tests/test_cli.py -x          # CLI entry point
+uv run python -c "from arrayview import view; import numpy as np; view(np.zeros((10,10)))"
+```
+
+## Red Flags — STOP
+
+- "I changed how the server starts but only tested CLI" → test all paths
+- "The feature works locally but not in tunnel" → check `_is_vscode_remote()` path and port exposure
+- "I used `127.0.0.1` in the URL" → use `localhost` so VS Code port-forwarding intercepts it
+- "Julia works but I only tested the Python path" → Julia always uses subprocess — test `_view_julia()` explicitly
+- "I bumped the extension version in package.json but not `_VSCODE_EXT_VERSION`" → they must stay in sync
+- "The server starts but leaves an orphan process after Ctrl-C" → check `_shutdown_event`, signal handlers, and subprocess reaping

arrayview-0.4.0/.claude/skills/modes-consistency/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: modes-consistency
+description: Use when implementing any visual feature in arrayview that touches canvas rendering, zoom, eggs, colorbars, keyboard shortcuts, or layout. Ensures the feature is applied consistently across ALL viewing modes, not just the one being worked on.
+---
+
+# ArrayView Modes Consistency Checklist
+
+## Rule
+
+Every visual feature in `_viewer.html` MUST be implemented for all applicable modes. Implementing it only in one mode and shipping is a bug, not a partial feature.
+
+## The Six Modes
+
+| Mode | State flag | Scale function | Entry key |
+|------|-----------|---------------|-----------|
+| **Normal** | (default) | `scaleCanvas()` | — |
+| **Multi-view** | `multiViewActive` | `mvScaleAllCanvases()` | V / v |
+| **Compare** | `compareActive` | `compareScaleCanvases()` | B / P |
+| **Diff** | `diffMode > 0` (inside compare) | `compareScaleCanvases()` | X (in compare) |
+| **Registration** | `registrationMode` (inside compare) | `compareScaleCanvases()` | R (in compare) |
+| **qMRI** | `qmriActive` | `qvScaleAllCanvases()` | q |
+
+Note: Overlay mode (`overlay_sid` URL param) is composited server-side into the normal frame — check backend rendering too.
+
+## Common Feature Categories & Where to Implement
+
+### Zoom / Canvas Sizing
+
+Every mode has a dedicated scale function. When changing zoom behavior, check **all four**:
+
+- `scaleCanvas(w, h)` [Normal] — applies `baseScale * userZoom`, snaps `userZoom` to cap at top
+- `mvScaleAllCanvases()` [Multi-view] — iterates `mvViews`, caps `userZoom` via per-view calculation
+- `compareScaleCanvases()` [Compare / Diff / Registration] — grid layout, caps `userZoom` before applying
+- `qvScaleAllCanvases()` [qMRI] — grid layout for parameter maps
+
+**Cap pattern** (already applied in compare): compute `capZoom` from max allowable scale across all panes, then `if (userZoom > capZoom) userZoom = capZoom;` before the sizing loop.
+
+### Eggs (Mode Indicator Dots — LOG, complex, mask, overlay badges)
+
+All eggs are positioned by `positionEggs()`. The function branches by mode. When changing egg placement rules, check:
+
+- Normal branch: uses `#slim-cb-wrap` bounding box if visible, else canvas bottom
+- Multi-view branch: uses `#mv-cb-wrap` bounding box if present, else estimates 36px below panes
+- Compare branch: walks `.compare-canvas-wrap` rects to find the tallest pane bottom
+- qMRI branch: uses `.qv-canvas-wrap` rects + 36px estimate
+
+When adding new egg types or changing vertical anchor, update all four branches.
+
+### Colorbar / Window-Level Interaction
+
+Colorbars are drawn by separate per-mode functions — there is no shared abstraction:
+
+| Mode | Colorbar function(s) |
+|------|---------------------|
+| Normal | `drawSlimColorbar(markerFrac)` |
+| Compare | `drawComparePaneCb(idx)` + `drawAllComparePaneCbs()` |
+| Diff (in compare) | `drawDiffPaneCb(vmin, vmax)` |
+| Registration (in compare) | `drawRegBlendCb()` |
+| Multi-view | `drawMvCbs()` (called inside `mvScaleAllCanvases`) |
+| qMRI | Drawn inline per view in `qvRender()` |
+
+When adding colorbar interactivity (e.g., drag, scroll), check which colorbars the feature should apply to, and implement it per-element.
+
+### Keyboard Shortcuts
+
+The `keydown` handler on `#keyboard-sink` dispatches by active mode. New shortcuts must:
+
+1. Not conflict with mode-specific keys — check the table in _viewer.html's keyboard section
+2. Have an explicit guard when the shortcut only makes sense in specific modes (e.g., `if (!compareActive) return;`)
+3. Fall through correctly when multiple modes are active (e.g., `registrationMode` requires `compareActive`)
+
+### Canvas Elements Present Per Mode
+
+| Mode | Canvas elements |
+|------|----------------|
+| Normal | `#canvas` |
+| Multi-view | `.mv-canvas` × 3  (inside `.mv-view`) |
+| Compare | `.compare-canvas` × 2–6  (inside `.compare-canvas-inner`) |
+| Diff | `#compare-diff-canvas` (shown only when `diffMode > 0` and `compareSids.length === 2`) |
+| Registration | 3rd `.compare-canvas` = blended overlay; `compareRegistrationFrame` drives it |
+| qMRI | `.qv-canvas` × 3–6 |
+
+Features that attach event listeners to canvas elements (mouse, wheel, etc.) must attach to the correct per-mode set of canvases, not just `document.getElementById('canvas')`.
+
+## Step-by-Step Implementation Checklist
+
+When implementing a new feature, run through this list:
+
+1. **Identify applicable modes**: Does this feature affect canvas sizing? colorbars? eggs? cursor? Yes → all modes.
+
+2. **Normal mode** — implement first, verify it works.
+
+3. **Compare mode** (includes Diff and Registration) — `compareScaleCanvases()` or the relevant compare-specific functions.
+
+4. **Multi-view mode** — `mvScaleAllCanvases()`, or per-view listener attachment if it's an event feature.
+
+5. **qMRI mode** — `qvScaleAllCanvases()`, or inline in `qvRender()` if it's a per-pane colorbar feature.
+
+6. **Overlay mode (backend)** — if the feature affects how frames are composited, check the `/slice`, `/frame`, `/diff`, and `/mosaic` endpoints in `_app.py`. Overlay compositing happens in `_composite_overlay_mask()` before PNG encoding.
+
+7. **Mosaic / z-grid** — when feature involves the diff endpoint (`/diff`), check that `dim_z` is correctly passed and handled server-side (backend `get_diff` must produce a mosaic grid when `dim_z >= 0`).
+
+8. **State snapshot** — if the feature introduces a new state variable, add it to `collectStateSnapshot()` and `applyStateSnapshot()` so it is preserved across page reloads and compare mode transitions.
+
+## Red Flags — STOP
+
+- "I only changed it for normal mode, the others are TODO" → implement all applicable modes now
+- "`compareScaleCanvases` and `scaleCanvas` now behave differently for zoom capping" → pick one pattern and apply to both
+- "I added a canvas listener to `#canvas` and now it doesn't work in compare" → multi-canvas modes have different DOM structures
+- "I only pass `dim_z` to some endpoints but not others" → check every endpoint that renders an image and needs the mosaic path
+
+## Quick Sanity Test
+
+After implementing, run:
+```
+uv run pytest tests/test_api.py -x
+uv run python tests/visual_smoke.py   # then review smoke_output/
+```
+
+And manually verify:
+- [ ] Feature works in normal view
+- [ ] Feature works in compare (press B → pick second array)
+- [ ] Feature works in diff (press X while in compare)
+- [ ] Feature works in multi-view (press v)
+- [ ] Feature works in qMRI if applicable (press q — needs array with 3–6 dim of size 3–6)
+- [ ] Eggs remain correctly anchored below canvases in each mode after feature is applied

arrayview-0.4.0/.claude/skills/task-workflow/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: task-workflow
+description: Enforce one-commit-per-TODO-item workflow and required collateral updates (README/help/tests/CHANGELOG) for arrayview feature/fix tasks.
+---
+
+# ArrayView Task Workflow Skill
+
+## Purpose
+
+Use this skill whenever implementing or fixing a TODO item. It enforces a disciplined workflow so each TODO becomes a single, self-contained commit (and ideally a single PR) that also updates documentation, help text, and tests.
+
+## Rule
+
+Every completed TODO item must:
+
+- Be implemented in a single commit with a clear commit message (see Commit Message format below).
+- Include or update automated tests that validate the feature/fix where possible.
+- Update `README.md` or the in-app help overlay if usage or shortcuts changed.
+- Update `tests/visual_smoke.py` for UI/layout changes (add a numbered scenario and screenshot capture).
+- Add a short entry to `CHANGELOG.md` or `AGENTS.md` (if CHANGELOG.md doesn't exist, add to `AGENTS.md` under a "Changelog" or the Skills section).
+
+If any of these steps cannot be completed (e.g., untestable UI dialog that requires human review), the implementer must document the reason in the PR description and add a smoke-test TODO row in `tests/visual_smoke.py` with `✗ (reason)`.
+
+## Commit Message Format
+
+- Use a concise, searchable prefix describing the TODO ID or short label, then a clear subject, then an optional body.
+- Recommended: `todo: <short-label>: <one-line-summary>`
+- Example: `todo: picker-two-column: add two-column compare picker and shape-filtering`
+
+Include a bullet list in the commit body showing collateral updates, e.g.:
+
+- Tests: `tests/test_picker.py` and `tests/visual_smoke.py#NN`
+- Docs: `README.md` updated section "Compare Picker"
+- Changelog: `AGENTS.md` / `CHANGELOG.md`
+
+## Checklist (enforced by this skill)
+
+For each TODO item, ensure the following before marking the task done:
+
+- [ ] Code implements the feature/fix and passes `python -m mccabe`/lint checks (if configured).
+- [ ] Unit tests or API tests added/updated in `tests/`.
+- [ ] If UI changes, `tests/visual_smoke.py` updated with a numbered scenario and `_shot()` call.
+- [ ] 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/`)
+
+## How to use
+
+1. Create a branch for the TODO item: `git checkout -b todo/<short-label>`.
+2. Implement the change and add tests and docs as required.
+3. Run tests and smoke script locally until passing (or document failures).
+4. Stage and commit only the files relevant to this TODO with a single commit message as defined above.
+5. Push and open a PR.
+
+## Special cases
+
+- If a TODO necessarily spans multiple commits (e.g., large refactor), use a temporary feature branch with descriptive commits, then squash into a single commit before merging. The PR must include a description explaining why squashing is required and ensure tests/docs are included in the final squashed commit.
+
+- If a fix must touch unrelated files (rare), keep those touches minimal and include an explanation in the commit body.
+
+## Automation hints for maintainers
+
+- Prefer adding a simple CI check that asserts commits touching `src/arrayview/` are accompanied by changes in `tests/` or `README.md`. This can be implemented as a lightweight script in `.github/workflows/`.
+
+- Encourage using `git commit --no-verify -m "..."` only when CI is temporarily failing for reasons unrelated to the task; prefer fixing CI first.
+
+
+## Red Flags — STOP
+
+- "I'll do tests later" — must add tests or justify why not and add smoke test TODO entry.
+- "I'll bundle multiple unrelated TODOs into one commit" — split them or squash locally, but final PR should present one item per commit semantics.
+- "Docs unchanged although usage changed" — update README/help or explain in PR why docs remain unchanged.
+
+
+# End of skill

arrayview-0.4.0/.claude/skills/viewer-ui-checklist/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: viewer-ui-checklist
+description: Use when adding keyboard shortcuts, changing layout, or making any UI change to arrayview. Ensures visual_smoke.py stays in sync.
+---
+
+# ArrayView UI Checklist
+
+## Rule
+
+Every UI change to arrayview MUST be reflected in `tests/visual_smoke.py` before the task is complete.
+
+## What counts as a UI change
+
+- New keyboard shortcut
+- Changed keyboard shortcut behavior
+- New view mode or display mode
+- Layout changes (canvas sizing, colorbar position, overlays)
+- New overlay, dialog, or panel
+
+## Steps (mandatory, in order)
+
+1. **Update coverage table** at the top of `visual_smoke.py`
+   - If shortcut is now testable: change `✗` to `✓ NN` with scenario number
+   - If new shortcut: add a row
+   - Mark untestable shortcuts with `✗ (reason)`
+
+2. **Add or update scenario** in `run_smoke()` with a numbered section comment
+   - Follow the existing pattern: `# ── NN: description ──────`
+   - Capture at least one screenshot with `_shot(page, "NN_descriptive_name")`
+
+3. **Run the smoke test** to verify the new scenario works:
+   ```
+   uv run python tests/visual_smoke.py
+   ```
+
+4. **Open and review** the new screenshots in `tests/smoke_output/`
+
+## Red flags — STOP
+
+- "The shortcut is too simple to need a smoke test" → ALL shortcuts need entries
+- "I'll add the test later" → add it in the same task
+- "The coverage table says ✗, that's fine" → only fine if you document WHY (requires dialog, etc.)
+
+## Stability check pattern
+
+When verifying a key causes no visual jumps:
+
+```python
+def _check_no_jump(page, key, selectors, shot_name):
+    before = {s: page.locator(s).bounding_box() for s in selectors}
+    _press(page, key)
+    after = {s: page.locator(s).bounding_box() for s in selectors}
+    _shot(page, shot_name)
+    for s in selectors:
+        b, a = before[s], after[s]
+        if b and a:
+            dx = abs(b["x"] - a["x"]); dy = abs(b["y"] - a["y"])
+            if dx > 2 or dy > 2:
+                print(f"  JUMP: {s} moved {dx:.0f}px/{dy:.0f}px after {key}")
+```
+
+Key selectors to check: `#canvas-wrap`, `#slim-cb-wrap`, `#info`

{arrayview-0.3.0 → arrayview-0.4.0}/.gitignore

@@ -11,6 +11,17 @@ wheels/
 
 *.npy
 .claude/
+!.claude/skills/
+!.claude/skills/**
 CLAUDE.md
 debug/
 tests/snapshots/
+
+*.jl
+*.ipynb
+logs/
+*.png
+!src/arrayview/_icon.png
+.worktrees/
+
+benchmarks/data