arrayview 0.13.0__tar.gz → 0.15.0__tar.gz

{arrayview-0.13.0 → arrayview-0.15.0}/.claude/skills/ui-consistency-audit/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: ui-consistency-audit
-description: Use when implementing or modifying any visual feature, layout, keyboard shortcut, or mode-specific behavior in arrayview. Proactively identifies all affected mode combinations before coding, prescribes per-mode behavior, checks for UI clashes, and runs a Playwright-based visual audit after implementation. Absorbs and replaces the modes-consistency skill.
+description: Use when the user explicitly requests a full visual audit, when validating UI work for a release, or when diagnosing a cross-mode visual regression in arrayview. Proactively identifies all affected mode combinations, prescribes per-mode behavior, checks for UI clashes, and runs a Playwright-based visual audit after implementation. Absorbs and replaces the modes-consistency skill.
 ---
 
 # ArrayView UI Consistency Audit
 
 ## Rule
 
-Every visual change must be verified across **all applicable mode × array-count combinations** before it ships. This skill has two phases: a **proactive phase** (before coding) that plans the cross-mode behavior, and a **reactive phase** (after coding) that runs an automated visual audit.
+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.13.0 → arrayview-0.15.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 the user explicitly asks to sync UI docs/help/test coverage, or when preparing a UI change for release. 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.
+This is the release/explicit-sync checklist for UI work. Do not invoke it by default for every UI edit during development. Use it when the user explicitly asks for the full sync, or when preparing a UI change for release.
+
+`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
 
@@ -17,7 +19,7 @@ Every UI change to arrayview MUST be reflected in `tests/visual_smoke.py`, the h
 - Layout changes (canvas sizing, colorbar position, overlays)
 - New overlay, dialog, or panel
 
-## Steps (mandatory, in order)
+## Steps (when this checklist is invoked)
 
 1. **Update coverage table** at the top of `visual_smoke.py`
    - If shortcut is now testable: change `✗` to `✓ NN` with scenario number
@@ -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.15.0/.github/copilot-instructions.md

@@ -0,0 +1,39 @@
+---
+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: [YYYY-MM-DD]
+---
+
+# [Project Name]
+
+## What This Is
+<!-- One sentence. What does this project do?
+     Length: 1 sentence maximum.
+     Not a tagline — a factual description of what the software does.
+     Example: "A REST API for managing inventory across multiple warehouse locations." -->
+
+## Non-Negotiables
+<!-- Hard rules the agent must never violate. Not preferences — rules.
+     These are the things that, if broken, cause real damage to the codebase.
+     Length: 3-7 items maximum. More than 7 means the list has not been prioritised.
+     Example:
+     - Never write database queries outside of the repository layer
+     - Never commit secrets or API keys
+     - Always handle errors explicitly — no silent failures -->
+
+## Commands
+<!-- The exact commands needed to work on this project.
+     Include: run dev server, run tests, run linter, build.
+     Use the actual commands from this codebase — not placeholders.
+     Example:
+     - Dev: `npm run dev`
+     - Test: `npm test`
+     - Lint: `npm run lint`
+     - Build: `npm run build` -->
+
+## After Every Task
+After completing any task: update `.mex/ROUTER.md` project state and any `.mex/` files that are now out of date. If no pattern existed for the task you just completed, create one in `.mex/patterns/`.
+
+## Navigation
+At the start of every session, read `.mex/ROUTER.md` before doing anything else.
+For full project context, patterns, and task guidance — everything is there.

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

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

arrayview-0.15.0/.ignore

@@ -0,0 +1 @@
+.worktrees/

arrayview-0.15.0/.mex/AGENTS.md

@@ -0,0 +1,9 @@
+---
+name: agents
+description: Lightweight pointer to ROUTER.md for task routing.
+last_updated: 2026-04-14
+---
+
+# arrayview
+
+Use `.mex/ROUTER.md` only when you need project state, routing, or a matching task pattern.

arrayview-0.15.0/.mex/ROUTER.md

@@ -0,0 +1,86 @@
+---
+name: router
+description: Navigation hub for task routing, project state, and behavioral guidance. Start here, then load the minimum extra context needed for the task.
+edges:
+  - target: context/project-state.md
+    condition: when the task depends on what is currently shipped, in progress, or recently changed
+  - 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: context/frontend.md
+    condition: when working on _viewer.html — modes, reconcilers, command registry, View Component System
+  - target: context/render-pipeline.md
+    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-15
+---
+
+# arrayview — Router
+
+## 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).
+
+## Non-Negotiables
+- Never split `_viewer.html` — entire frontend is one self-contained file, no build step
+- All heavy imports (numpy, matplotlib, nibabel, FastAPI, uvicorn) must be lazy — CLI fast path stays near-zero cost
+- New rendering features must be consistent across all six invocation environments
+- Global state lives in `_session.py` only — `SESSIONS`, `SERVER_LOOP`, `VIEWER_SOCKETS` 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 <file>`
+- Build: `uv build`
+
+## Context Budget
+
+1. Start with this file plus **at most one pattern and one context file**.
+2. Treat frontmatter `edges` as **optional suggestions**, not a preload list.
+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.
+
+## Current Project State
+
+Load `context/project-state.md` only when you need active-workstream or recent-shipping detail.
+
+## Routing Table
+
+| Task type | Load |
+|-----------|------|
+| Checking current shipped / in-progress status | `context/project-state.md` |
+| Understanding system architecture | `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) | `context/frontend.md` + `patterns/frontend-change.md` |
+| Render pipeline, colormaps, caching | `context/render-pipeline.md` |
+| Adding a new file format | `patterns/add-file-format.md` |
+| Adding a server route / WebSocket endpoint | `patterns/add-server-endpoint.md` |
+| Visual bugs / render artifacts | `patterns/debug-render.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.
+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`.
+5. **DEBUG** — If verification fails, check `patterns/INDEX.md` for one debug pattern, fix, then re-run VERIFY.
+6. **GROW** — After completing the task: create/update patterns, update stale context files, and update `context/project-state.md` if significant.
+
+## After Completing a Task
+
+- [ ] Update `context/project-state.md` if shipped or in-progress status changed
+- [ ] Update any stale `.mex/context/` or `.mex/patterns/` files touched by the task
+- [ ] If this revealed a repeatable workflow, add or update a pattern in `.mex/patterns/`

arrayview-0.15.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.md`** — interactive drift check + targeted or full resync
+- **`mex watch`** — auto drift score after every commit

arrayview-0.15.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.15.0/.mex/context/architecture.md

@@ -0,0 +1,90 @@
+---
+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"
+  - "data flow"
+  - "display routing"
+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: context/frontend.md
+    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-15
+---
+
+# Architecture
+
+## System Overview
+
+```
+CLI / Python API (view() or uvx arrayview <file>)
+   └─ _launcher.py  →  FastAPI server (_server.py, uvicorn)   [network mode]
+                    →  _stdio_server.py                        [VS Code direct webview]
+
+Server (either mode)
+   ├─ _session.py   Session objects, global state, render thread, caches
+   ├─ _render.py    extract_slice → apply_complex_mode → render_rgba → PNG pipeline
+   └─ _io.py        load_data() — npy/npz/nii/zarr/h5/mat/tif/pt routing
+
+Browser (_viewer.html — single self-contained HTML+JS+CSS file)
+   ├─ WebSocket /ws/{sid}   binary PNG slices from server
+   ├─ GET /meta/{sid}       session metadata on first load
+   └─ Canvas + UI           colorbars, eggs, dynamic islands, mode transitions
+```
+
+A `view()` call creates a `Session`, starts the FastAPI server if not running,
+registers the session via HTTP POST `/load`, then opens a display for the detected
+environment (Jupyter inline, VS Code SimpleBrowser or direct webview, native
+pywebview, or system browser).
+
+## Key Components
+
+- **`_launcher.py`** — CLI parser, `view()` API, `ViewHandle`, server lifecycle, SSH relay, file watching. Heavy imports (`_session`, `_render`, `_io`, uvicorn) are all lazy to keep the CLI fast path near-zero cost.
+- **`_server.py`** — FastAPI app with all REST and WebSocket routes (`/meta/{sid}`, `/load`, `/slice`, `/ws/{sid}`, `/seg/*`, `/reload`, etc.). Dispatches render work to the render thread via `_render()` from `_session.py`.
+- **`_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()`).
+- **`_io.py`** — All file-format loading behind `load_data(filepath)`. Lazy nibabel import for NIfTI. Handles `.npy`, `.npz`, `.nii/.nii.gz`, `.zarr`, `.zarr.zip`, `.pt/.pth`, `.h5/.hdf5`, `.tif/.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, SimpleBrowser and direct webview opening.
+- **`_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 (~15 600 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`.
+
+## Display Routing
+
+| Environment | Default display | Server mode |
+|---|---|---|
+| Jupyter | Inline iframe | network |
+| VS Code local | Simple Browser | network |
+| VS Code tunnel | Direct webview (stdio) | stdio |
+| Julia | System browser | network |
+| CLI / Python script | Native pywebview | network |
+| SSH terminal | VS Code ext via TCP relay (prints URL on failure) | network |
+
+Detection logic: `_platform.py`. Display opening: `_launcher.py` + `_vscode.py`.
+
+## External Dependencies
+
+- **FastAPI + uvicorn** — async HTTP/WebSocket server, lazy-imported in `_launcher.py`. Never call uvicorn directly — use the `_uvicorn()` accessor.
+- **nibabel** — NIfTI file loading. Lazy-imported in `_io.py` via `_nib()`. Only loaded for `.nii` / `.nii.gz`.
+- **numpy** — Core array type throughout. The only non-lazy import in the render path.
+- **matplotlib** — Colormap LUT generation only. Lazy, initialized once by `_init_luts()` in `_render.py`.
+- **qmricolors** — Registers the `lipari` and `navia` colormaps. Git dependency (`oscarvanderheide/qmricolors`).
+- **zarr** — Lazy chunk access for `.zarr` / `.zarr.zip`. Chunk presets via `zarr_chunk_preset()` in `_session.py`.
+- **pywebview** — Native OS window. Lazy, only started when `_can_native_window()` is true.
+
+## What Does NOT Exist Here
+
+- No persistent storage — sessions are in-memory only; nothing is written to disk by the server.
+- No authentication or multi-user access control — server binds to localhost.
+- No build step for the frontend — `_viewer.html` is a single static file served from package resources.
+- No background job queue — heavy ops run in the render thread or prefetch pool, both owned by `_session.py`.
+- No nnInteractive server — `_segmentation.py` is a pure HTTP client to a separately running nnInteractive process.