arrayview 0.13.0__tar.gz → 0.14.0__tar.gz

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

@@ -1,13 +1,15 @@
 ---
 name: viewer-ui-checklist
-description: Use when adding keyboard shortcuts, changing layout, or making any UI change to arrayview. Ensures visual_smoke.py, help overlay, and README stay in sync.
+description: Use when adding keyboard shortcuts, changing layout, or making any UI change to arrayview. Ensures visual_smoke.py, help overlay, and docs/ stay in sync.
 ---
 
 # ArrayView UI Checklist
 
 ## Rule
 
-Every UI change to arrayview MUST be reflected in `tests/visual_smoke.py`, the help overlay, and (when user-facing) `README.md` before the task is complete.
+Every UI change to arrayview MUST be reflected in `tests/visual_smoke.py`, the help overlay, and the relevant `docs/*.md` page before the task is complete.
+
+`README.md` is intentionally minimal and stable — do **not** add per-feature shortcuts or behavior to it. User-facing docs live in `docs/` and are organized by topic (`display.md`, `viewing.md`, `comparing.md`, `loading.md`, `measurement.md`, `remote.md`, `configuration.md`).
 
 ## What counts as a UI change
 
@@ -40,8 +42,16 @@ Every UI change to arrayview MUST be reflected in `tests/visual_smoke.py`, the h
    - Include a `hint` for non-obvious shortcuts
    - Use the `docs-style` skill for formatting rules
 
-6. **Update `README.md`** if the change is user-facing (new CLI flag, new API, new mode)
+6. **Update the matching `docs/*.md` page** for any user-facing change. Pick the page by topic:
+   - `display.md` — colormaps, range, log scale, themes, masking, layout toggles
+   - `viewing.md` — navigation, zoom, slice/dim shortcuts, multiview, projections
+   - `comparing.md` — compare mode, overlay, diff, registration
+   - `loading.md` — file formats, CLI, Python/Julia/MATLAB API
+   - `measurement.md` — ROI, hover, pixel info
+   - `remote.md` — VS Code Remote, tunneling
+   - `configuration.md` — settings, env vars, persistence
    - Use the `docs-style` skill for formatting rules
+   - Do **not** touch `README.md` for per-feature changes — it's intentionally stable
 
 ## Red flags — STOP
 

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

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

arrayview-0.14.0/.mex/AGENTS.md

@@ -0,0 +1,33 @@
+---
+name: agents
+description: Always-loaded project anchor. Read this first. Contains project identity, non-negotiables, commands, and pointer to ROUTER.md for full context.
+last_updated: 2026-04-13
+---
+
+# arrayview
+
+## What This Is
+A Python package for interactively viewing multi-dimensional arrays (numpy, NIfTI, zarr, DICOM, etc.) with a FastAPI backend, a single-file HTML/JS frontend, and multi-environment display routing (Jupyter, VS Code, SSH, native window).
+
+## Non-Negotiables
+
+- Never split `_viewer.html` into separate files — the entire frontend is one self-contained file, no build step
+- All heavy imports (numpy, matplotlib, nibabel, FastAPI, uvicorn) must be lazy — CLI fast path must stay near-zero cost
+- New rendering features must be consistent across all six invocation environments (CLI, Jupyter, Julia, VS Code local, VS Code tunnel, SSH)
+- Global state lives in `_session.py` only — `SESSIONS`, `SERVER_LOOP`, `VIEWER_SOCKETS` are never redefined elsewhere
+- Render thread must remain a raw `threading.Thread` + `SimpleQueue`, not `concurrent.futures`
+
+## Commands
+
+- Test: `uv run pytest tests/`
+- Visual smoke: `uv run pytest tests/visual_smoke.py`
+- CLI: `uvx arrayview path/to/file.npy`
+- Build: `uv build`
+- Docs: `uv run mkdocs serve`
+
+## Scaffold Growth
+After every task: if no pattern exists for the task type you just completed, create one. If a pattern or context file is now out of date, update it. The scaffold grows from real work, not just setup. See the GROW step in `ROUTER.md` for details.
+
+## Navigation
+At the start of every session, read `ROUTER.md` before doing anything else.
+For full project context, patterns, and task guidance — everything is there.

arrayview-0.14.0/.mex/ROUTER.md

@@ -0,0 +1,76 @@
+---
+name: router
+description: Session bootstrap and navigation hub. Read at the start of every session before any task. Contains project state, routing table, and behavioural contract.
+edges:
+  - target: context/architecture.md
+    condition: when working on system design, integrations, or understanding how components connect
+  - target: context/stack.md
+    condition: when working with specific technologies, libraries, or making tech decisions
+  - target: context/conventions.md
+    condition: when writing new code, reviewing code, or unsure about project patterns
+  - target: context/decisions.md
+    condition: when making architectural choices or understanding why something is built a certain way
+  - target: context/setup.md
+    condition: when setting up the dev environment or running the project for the first time
+  - target: patterns/INDEX.md
+    condition: when starting a task — check the pattern index for a matching pattern file
+last_updated: 2026-04-13
+---
+
+# Session Bootstrap
+
+If you haven't already read `AGENTS.md`, read it now — it contains the project identity, non-negotiables, and commands.
+
+Then read this file fully before doing anything else in this session.
+
+## Current Project State
+
+**Working:**
+- CLI (`uvx arrayview file.npy`) and Python API (`view(arr)`) — both stable
+- All six display environments: Jupyter inline, VS Code local (Simple Browser), VS Code tunnel (stdio), Julia, native pywebview, SSH URL print
+- File formats: `.npy`, `.npz`, `.nii`/`.nii.gz`, `.zarr`, `.h5`/`.hdf5`, `.mat`, `.tif`/`.tiff`, `.pt`/`.pth`
+- Rendering pipeline: colormaps, complex modes (mag/phase/real/imag), mosaic, RGB/RGBA, projections (max/min/mean/std/sos/sum)
+- Overlays: binary mask, multi-label segmentation, float heatmap with nnInteractive integration
+- NIfTI spatial metadata display, RAS resampling
+- VS Code extension v0.14.0 — stable window ID via `EnvironmentVariableCollection`
+- Colorbar refactor: `ColorBar` JS class partially migrated (in progress)
+
+**Not yet built:**
+- Independent split view for mismatched-shape arrays (designed, shelved — see `project_independent_split_view.md` memory)
+- Smooth immersive transition during continuous trackpad zoom (deferred — see memory)
+- Admin/config UI — config is file-based (`~/.arrayview/config.toml`) only
+
+**Known issues:**
+- White flicker on macOS native window before loading animation appears (minor, tracked in `dev/TODO.md`)
+- ColorBar class refactor is partially complete — some colorbars still use legacy inline code
+
+## Routing Table
+
+Load the relevant file based on the current task. Always load `context/architecture.md` first if not already in context this session.
+
+| Task type | Load |
+|-----------|------|
+| Understanding how the system works | `context/architecture.md` |
+| Working with a specific technology | `context/stack.md` |
+| Writing or reviewing code | `context/conventions.md` |
+| Making a design decision | `context/decisions.md` |
+| Setting up or running the project | `context/setup.md` |
+| Editing `_viewer.html` (frontend) | `patterns/frontend-change.md` |
+| Adding a new file format | `patterns/add-file-format.md` |
+| VS Code display / IPC issues | `patterns/vscode-display.md` |
+| Visual bugs / render artifacts | `patterns/debug-render.md` |
+| Any specific task | Check `patterns/INDEX.md` for a matching pattern |
+
+## Behavioural Contract
+
+For every task, follow this loop:
+
+1. **CONTEXT** — Load the relevant context file(s) from the routing table above. Check `patterns/INDEX.md` for a matching pattern. If one exists, follow it. Narrate what you load: "Loading architecture context..."
+2. **BUILD** — Do the work. If a pattern exists, follow its Steps. If you are about to deviate from an established pattern, say so before writing any code — state the deviation and why.
+3. **VERIFY** — Load `context/conventions.md` and run the Verify Checklist item by item. State each item and whether the output passes. Do not summarise — enumerate explicitly.
+4. **DEBUG** — If verification fails or something breaks, check `patterns/INDEX.md` for a debug pattern. Follow it. Fix the issue and re-run VERIFY.
+5. **GROW** — After completing the task:
+   - If no pattern exists for this task type, create one in `patterns/` using the format in `patterns/README.md`. Add it to `patterns/INDEX.md`. Flag it: "Created `patterns/<name>.md` from this session."
+   - If a pattern exists but you deviated from it or discovered a new gotcha, update it with what you learned.
+   - If any `context/` file is now out of date because of this work, update it surgically — do not rewrite entire files.
+   - Update the "Current Project State" section above if the work was significant.

arrayview-0.14.0/.mex/SETUP.md

@@ -0,0 +1,228 @@
+# Setup — Populate This Scaffold
+
+This file contains the prompts to populate the scaffold. It is NOT the dev environment setup — for that, see `context/setup.md` after population.
+
+This scaffold is currently empty. Follow the steps below to populate it for your project.
+
+## Recommended: Use setup.sh
+
+```bash
+.mex/setup.sh
+```
+
+The script handles everything automatically:
+1. Detects your project state (existing codebase, fresh project, or partial)
+2. Asks which AI tool you use and copies the right config file
+3. Pre-scans your codebase with `mex init` to build a structured brief (~5-8k tokens vs ~50k from AI exploration)
+4. Builds and runs the population prompt — or prints it for manual paste
+
+If you want to populate manually instead, use the prompts below.
+
+## Detecting Your State
+
+**Existing codebase?** Follow Option A.
+**Fresh project, nothing built yet?** Follow Option B.
+**Partially built?** Follow Option A — the agent will flag empty slots it cannot fill yet.
+
+---
+
+## Option A — Existing Codebase
+
+Paste the following prompt into your agent:
+
+---
+
+**SETUP PROMPT — copy everything between the lines:**
+
+```
+You are going to populate an AI context scaffold for this project.
+The scaffold lives in the root of this repository.
+
+Read the following files in order before doing anything else:
+1. ROUTER.md — understand the scaffold structure
+2. context/architecture.md — read the annotation comments to understand what belongs there
+3. context/stack.md — same
+4. context/conventions.md — same
+5. context/decisions.md — same
+6. context/setup.md — same
+
+Then explore this codebase:
+- Read the main entry point(s)
+- Read the folder structure
+- Read 2-3 representative files from each major layer
+- Read any existing README or documentation
+
+PASS 1 — Populate knowledge files:
+
+Populate each context/ file by replacing the annotation comments
+with real content from this codebase. Follow the annotation instructions exactly.
+For each slot:
+- Use the actual names, patterns, and structures from this codebase
+- Do not use generic examples
+- Do not leave any slot empty — if you cannot determine the answer,
+  write "[TO DETERMINE]" and explain what information is needed
+- Keep length within the guidance given in each annotation
+
+Then assess: does this project have domains complex enough that cramming
+them into architecture.md would make it too long or too shallow?
+If yes, create additional domain-specific context files in context/.
+Examples: a project with a complex auth system gets context/auth.md.
+A data pipeline gets context/ingestion.md. A project with Stripe gets
+context/payments.md. Use the same YAML frontmatter format (name,
+description, triggers, edges, last_updated). Only create these for
+domains that have real depth — not for simple integrations that fit
+in a few lines of architecture.md.
+
+After populating context/ files, update ROUTER.md:
+- Fill in the Current Project State section based on what you found
+- Add rows to the routing table for any domain-specific context files you created
+
+Update AGENTS.md:
+- Fill in the project name, one-line description, non-negotiables, and commands
+
+PASS 2 — Generate starter patterns:
+
+Read patterns/README.md for the format and categories.
+
+Generate 3-5 starter patterns for the most common and most dangerous task
+types in this project. Focus on:
+- The 1-2 tasks a developer does most often (e.g., add endpoint, add component)
+- The 1-2 integrations with the most non-obvious gotchas
+- 1 debug pattern for the most common failure boundary
+
+Each pattern should be specific to this project — real file paths, real gotchas,
+real verify steps derived from the code you read in Pass 1.
+Use the format in patterns/README.md. Name descriptively (e.g., add-endpoint.md).
+
+Do NOT try to generate a pattern for every possible task type. The scaffold
+grows incrementally — the behavioural contract (step 5: GROW) will create
+new patterns from real work as the project evolves. Setup just seeds the most
+critical ones.
+
+After generating patterns, update patterns/INDEX.md with a row for each
+pattern file you created. For multi-section patterns, add one row per task
+section using anchor links (see INDEX.md annotation for format).
+
+PASS 3 — Wire the web:
+
+Re-read every file you just wrote (context/ files, pattern files, ROUTER.md).
+For each file, add or update the `edges` array in the YAML frontmatter.
+Each edge should point to another scaffold file that is meaningfully related,
+with a `condition` explaining when an agent should follow that edge.
+
+Rules for edges:
+- Every context/ file should have at least 2 edges
+- Every pattern file should have at least 1 edge (usually to the relevant context file)
+- Edges should be bidirectional where it makes sense (if A links to B, consider B linking to A)
+- Use relative paths (e.g., context/stack.md, patterns/add-endpoint.md)
+- Pattern files can edge to other patterns (e.g., debug pattern → related task pattern)
+
+Important: only write content derived from the codebase.
+Do not include system-injected text (dates, reminders, etc.)
+in any scaffold file.
+
+When done, confirm which files were populated and flag any slots
+you could not fill with confidence.
+```
+
+---
+
+## Option B — Fresh Project
+
+Paste the following prompt into your agent:
+
+---
+
+**SETUP PROMPT — copy everything between the lines:**
+
+```
+You are going to populate an AI context scaffold for a project that
+is just starting. Nothing is built yet.
+
+Read the following files in order before doing anything else:
+1. ROUTER.md — understand the scaffold structure
+2. All files in context/ — read the annotation comments in each
+
+Then ask me the following questions one section at a time.
+Wait for my answer before moving to the next section:
+
+1. What does this project do? (one sentence)
+2. What are the hard rules — things that must never happen in this codebase?
+3. What is the tech stack? (language, framework, database, key libraries)
+4. Why did you choose this stack over alternatives?
+5. How will the major pieces connect? Describe the flow of a typical request/action.
+6. What patterns do you want to enforce from day one?
+7. What are you deliberately NOT building or using?
+
+After I answer, populate the context/ files based on my answers.
+For any slot you cannot fill yet, write "[TO BE DETERMINED]" and note
+what needs to be decided before it can be filled.
+
+Then assess: based on my answers, does this project have domains complex
+enough that cramming them into architecture.md would make it too long
+or too shallow? If yes, create additional domain-specific context files
+in context/. Examples: a project with a complex auth system gets
+context/auth.md. A data pipeline gets context/ingestion.md. A project
+with Stripe gets context/payments.md. Use the same YAML frontmatter
+format (name, description, triggers, edges, last_updated). Only create
+these for domains that have real depth — not for simple integrations
+that fit in a few lines of architecture.md. For fresh projects, mark
+domain-specific unknowns with "[TO BE DETERMINED — populate after first
+implementation]".
+
+Update ROUTER.md current state to reflect that this is a new project.
+Add rows to the routing table for any domain-specific context files you created.
+Update AGENTS.md with the project name, description, non-negotiables, and commands.
+
+Read patterns/README.md for the format and categories.
+
+Generate 2-3 starter patterns for the most obvious task types you can
+anticipate for this stack. Focus on the tasks a developer will do first.
+Mark unknowns with "[VERIFY AFTER FIRST IMPLEMENTATION]".
+
+Do NOT try to anticipate every possible pattern. The scaffold grows
+incrementally — the behavioural contract (step 5: GROW) will create
+new patterns from real work as the project evolves. Setup just seeds
+the most critical ones.
+
+After generating patterns, update patterns/INDEX.md with a row for each
+pattern file you created.
+
+PASS 3 — Wire the web:
+
+Re-read every file you just wrote (context/ files, pattern files, ROUTER.md).
+For each file, add or update the `edges` array in the YAML frontmatter.
+Each edge should point to another scaffold file that is meaningfully related,
+with a `condition` explaining when an agent should follow that edge.
+
+Rules for edges:
+- Every context/ file should have at least 2 edges
+- Every pattern file should have at least 1 edge
+- Edges should be bidirectional where it makes sense
+- Use relative paths (e.g., context/stack.md, patterns/add-endpoint.md)
+
+Important: only write content derived from your answers.
+Do not include system-injected text (dates, reminders, etc.)
+in any scaffold file.
+```
+
+---
+
+## After Setup
+
+**Verify** by starting a fresh session and asking your agent:
+"Read `.mex/ROUTER.md` and tell me what you now know about this project."
+
+A well-populated scaffold should give the agent enough to:
+- Describe the architecture without looking at code
+- Name the non-negotiable conventions
+- Know which files to load for any given task type
+- Know which patterns exist for common task types
+
+## Keeping It Fresh
+
+Once the scaffold is populated, use these to keep it aligned with your codebase:
+
+- **`mex check`** — detect drift (zero tokens, zero AI)
+- **`.mex/sync.sh`** — interactive drift check + targeted or full resync
+- **`mex watch`** — auto drift score after every commit

arrayview-0.14.0/.mex/SYNC.md

@@ -0,0 +1,62 @@
+# Sync — Realign This Scaffold
+
+## Recommended: Use sync.sh
+
+```bash
+.mex/sync.sh
+```
+
+The script runs drift detection first, shows you exactly what's wrong, then offers:
+1. **Targeted sync** — AI fixes only the flagged files (fastest, cheapest)
+2. **Full resync** — AI re-reads everything and updates all scaffold files
+3. **Prompt export** — shows the prompts for manual paste
+4. **Exit** — fix it yourself
+
+## Quick Check
+
+```bash
+mex check              # full drift report
+mex check --quiet      # one-liner: "drift score 85/100 (1 error)"
+mex sync --dry-run     # preview targeted fix prompts
+```
+
+## Manual Resync
+
+If you prefer to paste a prompt manually, or don't have the CLI built:
+
+---
+
+**SYNC PROMPT — copy everything between the lines:**
+
+```
+You are going to resync the AI context scaffold for this project.
+The scaffold may be out of date — the codebase has changed since it was last populated.
+
+First, read all files in context/ to understand the current scaffold state.
+Then explore what has changed in the codebase since the scaffold was last updated.
+Check the last_updated dates in the YAML frontmatter of each file.
+
+For each context/ file:
+1. Compare the current scaffold content to the actual codebase
+2. Identify what has changed, been added, or been removed
+3. Update the file to reflect the current state
+
+Critical rules for updating:
+- Use surgical, targeted edits — NOT full file rewrites. Read the existing content,
+  identify what changed, and update only those sections.
+- PRESERVE YAML frontmatter structure. Never delete or rewrite the entire frontmatter block.
+  Edit individual fields only. The edges, triggers, name, and description fields must
+  survive every sync. If you need to update edges, add or remove individual entries —
+  do not replace the entire array.
+- In context/decisions.md: NEVER delete existing decisions.
+  If a decision has changed, mark the old entry as "Superseded by [new decision title]"
+  and add the new decision above it with today's date.
+- In all other files: update content to reflect current reality
+- Update last_updated in the YAML frontmatter of every file you change
+- After updating each file, update ROUTER.md Current Project State
+
+When done, report:
+- Which files were updated and what changed
+- Any decisions that were superseded
+- Any slots that could not be filled with confidence
+```

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

@@ -0,0 +1,89 @@
+---
+name: architecture
+description: How the major pieces of arrayview connect and flow. Load when working on system design, integrations, or understanding how components interact.
+triggers:
+  - "architecture"
+  - "system design"
+  - "how does X connect to Y"
+  - "integration"
+  - "flow"
+  - "display routing"
+  - "server mode"
+edges:
+  - target: context/stack.md
+    condition: when specific technology details are needed
+  - target: context/decisions.md
+    condition: when understanding why the architecture is structured this way
+  - target: patterns/vscode-display.md
+    condition: when working on VS Code display routing or IPC
+  - target: patterns/frontend-change.md
+    condition: when working on the frontend viewer
+last_updated: 2026-04-13
+---
+
+# Architecture
+
+## System Overview
+
+```
+CLI / Python API (arrayview file.npy  OR  view(arr))
+   ↓
+_launcher.py — detects environment, starts server, opens display
+   ├─ _platform.py    environment detection (Jupyter/VSCode/SSH/Julia/native)
+   └─ _vscode.py      VS Code extension install, signal-file IPC, browser open
+
+Server (one of two transport modes):
+   ├─ Network mode: FastAPI (_server.py) + uvicorn → HTTP/WebSocket on localhost:PORT
+   └─ Stdio mode:  _stdio_server.py → JSON+binary over stdin/stdout (VS Code tunnel)
+
+Server internals (both modes):
+   ├─ _session.py   Session objects, SESSIONS dict, render thread, prefetch, cache budgets
+   ├─ _render.py    extract_slice → apply_complex_mode → apply_colormap_rgba → PNG
+   └─ _io.py        load_data() for .npy/.npz/.nii/.zarr/.h5/.mat/.tiff/.pt
+
+Frontend:
+   └─ _viewer.html  Single ~15k-line self-contained HTML/CSS/JS file
+                    ← binary RGBA frames over WebSocket / postMessage
+                    → slice index, colormap, mode commands back to server
+```
+
+## Key Components
+
+- **`_launcher.py`** (2817 lines) — Main entry point. CLI parser, `view()` API, `ViewHandle`, server lifecycle (port detection, background thread start), SSH relay, demo arrays, file watching. Imports `_server` and `uvicorn` lazily to keep CLI fast path cheap.
+- **`_server.py`** (3258 lines) — FastAPI app. All REST endpoints (`/load`, `/reload`, `/seg/*`, `/resample_ras`, …) and WebSocket handler (`/ws/{sid}`). Reads from `Session` objects in `_session.SESSIONS`.
+- **`_viewer.html`** (~15,600 lines) — The entire frontend. CSS dark theme + JS viewer state machine in a single file. No build step. Organized by `/* ── Section ── */` comment separators. Receives binary RGBA frames, renders to Canvas.
+- **`_session.py`** — `Session` class (LRU raw/rgba/mosaic caches, preload state, vfield, spatial_meta), global state (SESSIONS dict, SERVER_LOOP, VIEWER_SOCKETS), dedicated render thread, prefetch pool.
+- **`_render.py`** — `extract_slice` → `apply_complex_mode` → `apply_colormap_rgba` → `render_rgba`. Also handles `render_mosaic`, `render_rgb_rgba`, overlay compositing. Colormap LUTs built lazily via `_init_luts()`.
+- **`_platform.py`** — Environment detection: `_in_jupyter()`, `_in_vscode_terminal()`, `_is_vscode_remote()`, `_in_vscode_tunnel()`, `_can_native_window()`, `_is_julia_env()`. Includes ancestor-process walk to recover env vars stripped by `uv run`.
+- **`_vscode.py`** — VS Code extension auto-install (VSIX bundled in package), signal-file IPC (`open-request-v0900.json`), shared-memory IPC, `EnvironmentVariableCollection` window ID (stable across uv run env stripping).
+- **`_stdio_server.py`** (791 lines) — Alternative transport for VS Code direct webview. Reads JSON requests from stdin, writes binary RGBA frames to stdout. Spawned as subprocess by the VS Code extension.
+- **`_io.py`** — `load_data(filepath)` dispatcher. Handles lazy vs eager loading per format. `.nii.gz` is always materialized (gzip not seekable). `.npy` uses `mmap_mode="r"`.
+
+## Display Routing
+
+| Environment | Display method | Server mode |
+|---|---|---|
+| Jupyter | Inline iframe | network |
+| VS Code local terminal | Simple Browser (signal-file IPC) | network |
+| VS Code tunnel (remote) | Direct webview via stdio | stdio |
+| Julia | System browser | network |
+| CLI / Python script (macOS/Win) | Native pywebview window | network |
+| SSH (no VS Code) | Prints URL; VS Code ext tries TCP relay | network |
+
+Detection lives in `_platform.py`. Opening logic in `_launcher.py` and `_vscode.py`.
+
+## External Dependencies
+
+- **FastAPI + uvicorn** — HTTP/WebSocket server. Imported lazily from `_server_mod()` in `_launcher.py` to save ~175 ms on CLI fast path (server already running).
+- **nibabel** — NIfTI loading. Lazy import inside `_io._nib()`. `.nii.gz` volumes are materialized up front; `.nii` uses mmap.
+- **matplotlib + qmricolors** — Colormap LUTs. Both deferred until first render via `_init_luts()`. `qmricolors` registers `lipari` and `navia` colormaps.
+- **pywebview** — Native window rendering on macOS/Windows/Linux. Launched in a fresh subprocess (via `_open_webview`) to avoid multiprocessing bootstrap issues from Jupyter.
+- **zarr** — Lazy array access for `.zarr` files. Used directly; no abstraction layer.
+
+## What Does NOT Exist Here
+
+- No database — all state is in-memory (`SESSIONS` dict) and dies with the process.
+- No authentication — server binds to localhost only; no access control.
+- No async rendering — render thread is a dedicated `threading.Thread` pulling from a `SimpleQueue`; deliberately not `concurrent.futures` (immune to interpreter-shutdown executor cleanup).
+- No build step for the frontend — `_viewer.html` is a single file edited directly.
+- No separate admin / management interface — `_config.py` reads `~/.arrayview/config.toml` directly.

arrayview-0.14.0/.mex/context/conventions.md

@@ -0,0 +1,89 @@
+---
+name: conventions
+description: How code is written in arrayview — naming, structure, lazy imports, and frontend organization. Load when writing new code or reviewing existing code.
+triggers:
+  - "convention"
+  - "pattern"
+  - "naming"
+  - "style"
+  - "how should I"
+  - "what's the right way"
+  - "lazy import"
+edges:
+  - target: context/architecture.md
+    condition: when a convention depends on understanding the system structure
+  - target: context/stack.md
+    condition: when the convention is library-specific
+  - target: patterns/frontend-change.md
+    condition: when writing frontend (HTML/CSS/JS) code
+last_updated: 2026-04-13
+---
+
+# Conventions
+
+## Naming
+
+- **Module files** — all private, prefixed with `_` (`_launcher.py`, `_render.py`, `_server.py`). Only `__init__.py` and `__main__.py` are public entry points.
+- **Functions** — `snake_case`, internal helpers prefixed with `_` (e.g. `_compute_vmin_vmax`, `_in_jupyter`)
+- **Constants** — `SCREAMING_SNAKE_CASE` for module-level constants (`SESSIONS`, `LUTS`, `COLORMAPS`, `HEAVY_OP_LIMIT_BYTES`)
+- **Classes** — `PascalCase` (`Session`, `ViewHandle`, `TrainingMonitor`, `_LazyMod`)
+- **Frontend section separators** — `/* ── Section Name ── */` in CSS, `// ── Section Name ──` in JS (double-dash with spaces, em-dashes)
+
+## Structure
+
+- **Lazy imports everywhere** — any import that costs >10 ms must be deferred. Pattern: module-level `_cache = None` + accessor function (see `_server_mod()`, `_uvicorn()`, `_nib()`, `_init_luts()`). The CLI fast path (server already running) must stay near-zero cost.
+- **Global state lives in `_session.py`** — `SESSIONS`, `SERVER_LOOP`, `VIEWER_SOCKETS`, `SHELL_SOCKETS`. Other modules import these by name, never redefine them.
+- **Render pipeline is pure functions** — `_render.py` exports stateless functions that take `session` + parameters. No class hierarchy.
+- **One HTML file for the entire frontend** — all CSS and JS live in `_viewer.html`. Do not split into separate files.
+- **Tests live in `tests/`** — not next to source files. Visual/browser tests use playwright and are marked `@pytest.mark.browser`.
+- **All file-format loading goes through `_io.load_data(filepath)`** — no direct format imports in `_server.py` or `_launcher.py`.
+
+## Patterns
+
+**Lazy module import pattern** (used for all heavy dependencies):
+```python
+# At module level
+_nib_mod = None
+
+def _nib():
+    global _nib_mod
+    if _nib_mod is None:
+        import nibabel
+        _nib_mod = nibabel
+    return _nib_mod
+
+# Usage: _nib().load(filepath)  — never `import nibabel` at top level
+```
+
+**Session cache pattern** (LRU via `OrderedDict`):
+```python
+key = (dim_x, dim_y, key_idx)
+if key in session.raw_cache:
+    session.raw_cache.move_to_end(key)  # LRU update
+    return session.raw_cache[key]
+# ... compute result ...
+session.raw_cache[key] = result
+session._raw_bytes += result.nbytes
+while session._raw_bytes > session.RAW_CACHE_BYTES and session.raw_cache:
+    _, v = session.raw_cache.popitem(last=False)
+    session._raw_bytes -= v.nbytes
+```
+
+**Environment detection order** (in `_platform.detect_environment()`):
+```
+jupyter → vscode → julia → ssh → terminal
+```
+Always check in this priority order. Never short-circuit.
+
+**Float rendering convention** — slices are always converted to `np.float32` before applying colormap. RGB uint8 arrays skip colormap and go directly to RGBA. Complex arrays are transformed by `apply_complex_mode()` before any colormap step.
+
+## Verify Checklist
+
+Before presenting any code change:
+- [ ] New heavy imports are lazy (wrapped in a `_mod = None` / accessor function pattern)
+- [ ] Any new `Session` field is initialized in `Session.__init__` and cleared in `reset_caches()` if it's cache-related
+- [ ] New file format support goes through `_io.load_data()` and adds the extension to `_SUPPORTED_EXTS`
+- [ ] Frontend changes are in `_viewer.html` only — no new JS/CSS files
+- [ ] New rendering functions follow the `extract_slice → apply_complex_mode → apply_colormap_rgba` pipeline order
+- [ ] Environment detection changes go in `_platform.py`, not inline in `_launcher.py` or `_vscode.py`
+- [ ] Cross-mode consistency: any new visual feature verified in all six invocation environments (see `invocation-consistency` skill)