arrayview 0.3.0__tar.gz → 0.5.1__tar.gz

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

@@ -0,0 +1,235 @@
+---
+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)))"
+```
+
+## tmux and VS Code Terminal Detection
+
+tmux is the single most common reason `_find_vscode_ipc_hook()` fails even though the user IS in a VS Code terminal.
+
+### Why the ancestor-walk fails inside tmux
+
+Normal process tree (no tmux):
+```
+VS Code terminal shell (has VSCODE_IPC_HOOK_CLI)
+  └─ uv run python / arrayview   ← walks up, finds it ✓
+```
+
+Process tree inside tmux:
+```
+VS Code terminal shell (has VSCODE_IPC_HOOK_CLI)
+  └─ tmux (client process — also has VSCODE_IPC_HOOK_CLI)
+       ↕ socket IPC (not parent/child)
+tmux-server (independent daemon — does NOT have VSCODE_IPC_HOOK_CLI)
+  └─ pane shell
+       └─ uv run python / arrayview   ← walks up through tmux-server, never finds it ✗
+```
+
+The arrayview process's parent chain goes through `tmux-server`, which is an independent daemon that was started at some point and does NOT inherit the VS Code terminal's environment.
+
+### Why `tmux show-environment` fails
+
+`tmux show-environment VSCODE_IPC_HOOK_CLI` queries tmux's *session* environment. tmux only tracks variables listed in its `update-environment` option. The default list is:
+```
+DISPLAY SSH_ASKPASS SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAUTHORITY
+```
+`VSCODE_IPC_HOOK_CLI` is **not** in the default list, so it is never copied into tmux's session environment. The command returns `-VSCODE_IPC_HOOK_CLI` (meaning unset) even when every client has it.
+
+### Why `#{client_pid}` alone is unreliable
+
+`tmux display-message -p '#{client_pid}'` returns **one** client PID (the "current" client). This fails when:
+- Multiple clients are attached to the session (e.g., shared session, or user has the session open in both VS Code and a regular terminal)
+- A session was created outside VS Code and then attached from VS Code
+
+### Correct approach: enumerate ALL clients for the current session
+
+```python
+# Get current session ID
+session_id = subprocess.run(["tmux", "display-message", "-p", "#{session_id}"], ...).stdout.strip()
+
+# List ALL clients for this session
+client_pids = subprocess.run(
+    ["tmux", "list-clients", "-t", session_id, "-F", "#{client_pid}"], ...
+).stdout.strip().splitlines()
+
+# Check each client's environment
+for pid_str in client_pids:
+    val = _ipc_from_pid(int(pid_str))
+    if val and os.path.exists(val):
+        return val  # found VSCODE_IPC_HOOK_CLI in one of the VS Code clients ✓
+```
+
+`list-clients -t <session_id>` scopes to the current session only, so we don't accidentally pick up a `VSCODE_IPC_HOOK_CLI` from a completely different VS Code window on another session.
+
+### Detection order in `_find_vscode_ipc_hook()` (when TERM_PROGRAM=tmux)
+
+1. `tmux show-environment VSCODE_IPC_HOOK_CLI` — cheap, works if user set `update-environment`
+2. `tmux list-clients -t <session_id> -F '#{client_pid}'` → `ps ewwww` each — robust, handles all cases
+
+### What `--diagnose` should show when working
+
+```json
+"detection": {
+  "in_vscode_terminal": true,
+  "vscode_ipc_hook_recovered": "/var/folders/.../vscode-ipc-xxx.sock"
+}
+```
+
+If `vscode_ipc_hook_recovered` is `null` despite being in VS Code+tmux, the strategies above both failed. Check:
+- Is the tmux session detached (no clients attached)?
+- Is `ps ewwww -p <client_pid>` working on this OS? (Some Linux distros restrict it)
+- Is the IPC socket path valid (does the `.sock` file exist)?
+
+### Red flags for tmux detection
+
+- "I fixed it with `#{client_pid}`" → only works with one client; use `list-clients` instead
+- "I fixed it with `show-environment`" → only works if user customised `update-environment`; both strategies needed
+- "It works for me but not for the user" → check if they have multiple clients or a session created before VS Code
+
+
+
+- "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.5.1/.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.5.1/.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.5.1/.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.5.1}/.github/workflows/python-publish.yml

@@ -20,9 +20,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.x"
 
@@ -33,7 +33,7 @@ jobs:
           python -m build
 
       - name: Upload distributions
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: release-dists
           path: dist/
@@ -59,7 +59,7 @@ jobs:
 
     steps:
       - name: Retrieve release distributions
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: release-dists
           path: dist/

{arrayview-0.3.0 → arrayview-0.5.1}/.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