feat(frontend): React + Vite + NiiVue frontend (replaces Gradio) (#32)

## Summary
React + Vite + NiiVue frontend replacing Gradio

### Key Changes
- React 19 + Vite 7 + TypeScript strict mode
- NiiVue 0.65.0 for medical image visualization
- 58 unit tests (Vitest) + 8 E2E tests (Playwright)
- 78%+ branch coverage
- CI pipeline with lint, typecheck, test, build jobs

### CodeRabbit Review Fixes
- Split NiiVue into two effects (mount vs URL changes)
- Add AbortController + request token to useSegmentation
- Add isCurrent cleanup flag to NiiVueViewer
- Remove test-only types from tsconfig.app.json
- Update spec docs with correct versions

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ on:
       run_integration:
         description: 'Run integration tests (requires HuggingFace download)'
         required: false
-        default: 'false'
+        default: false
         type: boolean
 
 jobs:
@@ -106,3 +106,112 @@ jobs:
         run: uv run pytest -m integration --timeout=600
         env:
           HF_HOME: /tmp/hf_cache
+
+  # Frontend Jobs
+  frontend-lint:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npm run lint
+
+  frontend-typecheck:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npx tsc --noEmit
+
+  frontend-test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npm run test:coverage
+
+      - uses: codecov/codecov-action@v4
+        with:
+          files: frontend/coverage/coverage-final.json
+          flags: frontend
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  frontend-e2e:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+
+      - run: npm run test:e2e
+
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: frontend/playwright-report/
+          retention-days: 7
+
+  frontend-build:
+    runs-on: ubuntu-latest
+    needs: [frontend-lint, frontend-typecheck, frontend-test]
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npm run build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: frontend-dist
+          path: frontend/dist/
+          retention-days: 7

docs/specs/00-context.md

@@ -1,214 +0,0 @@
-# context: stroke-deepisles-demo
-
-> **Disclaimer**: This software is for research and demonstration purposes only. Not for clinical use.
-
-## overview
-
-This document explains **why** we're building `stroke-deepisles-demo` and the architectural context that informs our design decisions.
-
-## the problem we're solving
-
-We want to demonstrate an end-to-end neuroimaging inference pipeline:
-
-```
-CURRENT (Phase 1A):
-    Local NIfTI files (extracted from ISLES24-MR-Lite ZIPs)
-            ↓
-        File-based loader (parse BIDS filenames)
-            ↓
-        DeepISLES Docker (stroke segmentation)
-            ↓
-        NiiVue visualization (Gradio Space)
-
-FUTURE (Phase 1C-D):
-    HuggingFace Hub (properly uploaded dataset)
-            ↓
-        Tobias's datasets fork (BIDS loader + Nifti feature)
-            ↓
-        DeepISLES Docker (stroke segmentation)
-            ↓
-        NiiVue visualization (Gradio Space)
-```
-
-This showcases that:
-1. Neuroimaging data can be loaded from local BIDS-named files (NOW)
-2. Neuroimaging data can be consumed from HF Hub with proper BIDS/NIfTI support (FUTURE)
-3. Clinical-grade models can run via Docker as black boxes
-4. Results can be visualized interactively in a browser
-
-## critical discovery (2025-12-04)
-
-**The original ISLES24-MR-Lite dataset is NOT properly uploaded to HuggingFace.**
-
-It's just raw ZIP files dumped on HF, not a proper Dataset with parquet/Arrow format. This means `load_dataset()` fails. See `data/discovery/isles24_schema_report.txt` for full details.
-
-**Workaround**: We extracted the ZIPs locally to `data/isles24/` (git-ignored) and will implement a file-based loader first. Later, we'll re-upload properly and verify full HF consumption.
-
-## why we need tobias's datasets fork
-
-As of December 2025, the official `huggingface/datasets` library has **partial** NIfTI support but lacks critical features for neuroimaging workflows.
-
-### what's merged upstream
-
-| PR | Author | Status | Description |
-|----|--------|--------|-------------|
-| [#7874](https://github.com/huggingface/datasets/pull/7874) | CloseChoice (Tobias) | Merged Nov 21 | NIfTI visualization support |
-| [#7878](https://github.com/huggingface/datasets/pull/7878) | CloseChoice (Tobias) | Merged Nov 27 | Replace papaya with NiiVue |
-
-### what's NOT merged (and why we need the fork)
-
-| PR | Author | Status | Description |
-|----|--------|--------|-------------|
-| [#7886](https://github.com/huggingface/datasets/pull/7886) | The-Obstacle-Is-The-Way | Open | **BIDS dataset loader** - `load_dataset('bids', ...)` |
-| [#7887](https://github.com/huggingface/datasets/pull/7887) | The-Obstacle-Is-The-Way | Open | **NIfTI lazy loading fix** - use `dataobj` not `get_fdata()` |
-| [#7892](https://github.com/huggingface/datasets/pull/7892) | CloseChoice (Tobias) | Open | **NIfTI encoding for lazy upload** - fixes Arrow serialization |
-
-The fork branch bundles all these features:
-```
-https://github.com/CloseChoice/datasets/tree/feat/bids-loader-streaming-upload-fix
-```
-
-We pin to this branch until upstream merges the PRs.
-
-## key components
-
-### 1. data source: ISLES24-MR-Lite
-
-- **HF Dataset**: [YongchengYAO/ISLES24-MR-Lite](https://huggingface.co/datasets/YongchengYAO/ISLES24-MR-Lite) (**BROKEN** - raw ZIPs, not proper dataset)
-- **Local extracted**: `data/isles24/` (git-ignored)
-- **Content**: 149 acute stroke MRI cases with DWI, ADC, and manual infarct masks
-- **Origin**: Subset of ISLES 2024 challenge data
-- **Why suitable**: DeepISLES was trained on ISLES 2022, so ISLES24 is an **external** test set (no data leakage)
-
-**File structure** (after extraction):
-```
-data/isles24/
-├── Images-DWI/sub-stroke{XXXX}_ses-02_dwi.nii.gz        # 149 files
-├── Images-ADC/sub-stroke{XXXX}_ses-02_adc.nii.gz        # 149 files
-└── Masks/sub-stroke{XXXX}_ses-02_lesion-msk.nii.gz      # 149 files
-```
-
-**Schema reference**: `data/discovery/isles24_schema_report.txt`
-
-### 2. model: DeepISLES
-
-- **Paper**: Nature Communications 2025 - "DeepISLES: A clinically validated ischemic stroke segmentation model"
-- **GitHub**: [ezequieldlrosa/DeepIsles](https://github.com/ezequieldlrosa/DeepIsles)
-- **Docker**: `isleschallenge/deepisles`
-- **Inputs**: DWI + ADC (required), FLAIR (required for ensemble, optional for fast mode)
-- **Output**: 3D binary lesion mask (NIfTI)
-- **Mode**: `fast=True` runs **SEALS only** (the ISLES'22 challenge winner)
-
-#### Why we use `fast=True` (SEALS-only mode)
-
-DeepISLES is an ensemble of 3 models from the ISLES'22 challenge:
-
-| Model | Based On | Inputs Required | Notes |
-|-------|----------|-----------------|-------|
-| **SEALS** | nnUNet | DWI + ADC | 🏆 **ISLES'22 Winner** - runs in `--fast` mode |
-| NVAUTO | MONAI Auto3dseg | DWI + ADC + FLAIR | Requires FLAIR |
-| SWAN | FACTORIZER | DWI + ADC + FLAIR | Requires FLAIR |
-
-**Key insight**: ISLES24-MR-Lite contains only DWI + ADC (no FLAIR). Therefore:
-- `--fast True` → Runs SEALS only → **Perfect match** for our dataset
-- `--fast False` → Would try to run all 3 models → NVAUTO/SWAN would fail without FLAIR
-
-This is **not a downgrade**. SEALS won the ISLES'22 challenge and is state-of-the-art for stroke lesion segmentation using DWI+ADC alone.
-
-#### Scientific validity: External validation with zero data leakage
-
-| Dataset | Year | Used For |
-|---------|------|----------|
-| **ISLES 2022** | 2022 | SEALS training data (250 cases) |
-| **ISLES 2024** | 2024 | Our test data (149 cases from MR-Lite) |
-
-- Different patient cohorts (2 years apart, different hospitals)
-- SEALS has **never seen** ISLES24 patients
-- We have ground truth masks → can validate predictions
-- This constitutes a legitimate **external validation study**
-
-### 3. visualization: NiiVue
-
-- **Library**: [niivue/niivue](https://github.com/niivue/niivue)
-- **Type**: WebGL2-based neuroimaging viewer
-- **Formats**: Native NIfTI support, overlays, multiplanar views
-- **Integration**: Via Gradio custom HTML component or iframe
-
-### 4. UI framework: Gradio 5
-
-- **Version**: Gradio 5.x (latest as of Dec 2025)
-- **Features**: SSR for fast loading, improved components, WebRTC support
-- **Deployment**: Hugging Face Spaces
-
-## architecture diagram
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     stroke-deepisles-demo                        │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐       │
-│  │  data/       │    │  inference/  │    │  ui/         │       │
-│  │              │    │              │    │              │       │
-│  │  - loader    │───▶│  - docker    │───▶│  - gradio    │       │
-│  │  - adapter   │    │  - wrapper   │    │  - niivue    │       │
-│  │  - staging   │    │  - pipeline  │    │  - viewer    │       │
-│  └──────────────┘    └──────────────┘    └──────────────┘       │
-│         │                   │                   │                │
-│         ▼                   ▼                   ▼                │
-│  ┌──────────────────────────────────────────────────────┐       │
-│  │                    core/                              │       │
-│  │  - config (pydantic-settings)                        │       │
-│  │  - types (dataclasses, TypedDicts)                   │       │
-│  │  - exceptions                                         │       │
-│  └──────────────────────────────────────────────────────┘       │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-         │                    │                    │
-         ▼                    ▼                    ▼
-   ┌──────────┐        ┌──────────┐         ┌──────────┐
-   │ HF Hub   │        │ Docker   │         │ Browser  │
-   │ datasets │        │ Engine   │         │ WebGL2   │
-   └──────────┘        └──────────┘         └──────────┘
-```
-
-## design principles
-
-1. **Vertical slices**: Each phase delivers runnable functionality
-2. **TDD**: Tests written before implementation
-3. **Type safety**: Full type hints, mypy/pyright strict mode
-4. **Separation of concerns**: Data, inference, and UI are independent modules
-5. **Docker as black box**: We don't reimplement DeepISLES, we call it
-6. **Graceful degradation**: Mock Docker for tests, fallback viewers if NiiVue fails
-
-## reference repositories
-
-These are cloned locally (without git linkages) for reference:
-
-| Directory | Source | Purpose |
-|-----------|--------|---------|
-| `_reference_repos/datasets-tobias-bids-fork/` | CloseChoice/datasets@feat/bids-loader-streaming-upload-fix | BIDS loader + NIfTI lazy loading |
-| `_reference_repos/arc-aphasia-bids/` | The-Obstacle-Is-The-Way/arc-aphasia-bids | BIDS upload patterns (reference only) |
-| `_reference_repos/DeepIsles/` | ezequieldlrosa/DeepIsles | DeepISLES CLI interface reference |
-| `_reference_repos/bids-neuroimaging-space/` | [TobiasPitters/bids-neuroimaging](https://huggingface.co/spaces/TobiasPitters/bids-neuroimaging) | **Working NiiVue + FastAPI implementation** |
-
-### key reference: tobias's bids-neuroimaging space
-
-This is the most important reference for Phase 4 (UI). It demonstrates:
-
-1. **NiiVue working in HF Spaces** - Proof that WebGL2 viewer works in production
-2. **FastAPI + raw HTML approach** - Clean, no Gradio overhead for viewer
-3. **Base64 data URLs for NIfTI** - `data:application/octet-stream;base64,{b64}`
-4. **NiiVue CDN loading** - `https://unpkg.com/@niivue/niivue@0.57.0/dist/index.js`
-5. **Multiplanar + 3D rendering** - `setSliceType(sliceTypeMultiplanar)` + `setMultiplanarLayout(2)`
-
-Key file: `main.py` (~485 lines) - complete working implementation.
-
-## sources
-
-- [uv project configuration](https://docs.astral.sh/uv/concepts/projects/config/)
-- [Python packaging guide - pyproject.toml](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/)
-- [Real Python - Managing projects with uv](https://realpython.com/python-uv/)
-- [Gradio 5 announcement](https://huggingface.co/blog/gradio-5)
-- [NiiVue GitHub](https://github.com/niivue/niivue)
-- [Gradio custom HTML components](https://www.gradio.app/guides/custom_HTML_components)

docs/specs/24-bug-gradio-webgl-analysis.md

@@ -1,156 +0,0 @@
-# Bug #24: Gradio + WebGL/NiiVue Root Cause Analysis
-
-**Date:** 2025-12-10
-**Status:** ALL `gr.HTML` HACKS FAILED - Custom Component Required
-**Issue:** HF Spaces stuck on "Loading..." forever
-**Root Cause:** The `gr.HTML` + `js_on_load` + async `import()` pattern blocks Svelte hydration
-**Note:** Gradio CAN do WebGL via Custom Components (proven by gradio-litmodel3d)
-**Solution:** Build Gradio Custom Component (see spec #28)
-
----
-
-## CONFIRMED: All gr.HTML Hacks Have Failed
-
-| Attempt | Date | Result |
-|---------|------|--------|
-| CDN import in js_on_load | Dec 9 | FAILED - CSP blocks external imports |
-| Vendored + dynamic import() in js_on_load | Dec 9 | FAILED - Blocks Svelte hydration |
-| head_paths with loader HTML | Dec 9 | FAILED - Same hydration issue |
-| head= with inline import() | Dec 10 | **FAILED** - Confirmed DOA |
-
-**There is no hack that works.** The only path forward is spec #28 (Gradio Custom Component).
-
----
-
-## Why Are We Using Gradio?
-
-**What Gradio provides:**
-- Quick ML demo UIs with Python only (no frontend code needed)
-- Built-in components: file upload, sliders, dropdowns, image display
-- Easy deployment to HuggingFace Spaces
-- Handles backend/frontend communication automatically
-
-**What Gradio does NOT provide:**
-- Native support for NIfTI/DICOM medical imaging (closed as "not planned" - [Issue #4511](https://github.com/gradio-app/gradio/issues/4511))
-- Native WebGL canvas component (closed as "not planned" - [Issue #7649](https://github.com/gradio-app/gradio/issues/7649))
-- Clean way to embed custom WebGL libraries like NiiVue
-
----
-
-## The Root Cause: We're Fighting `gr.HTML`, Not Gradio
-
-### What We're Trying To Do
-Embed NiiVue (a WebGL2 library) into `gr.HTML` using JavaScript.
-
-### Why `gr.HTML` + JavaScript Doesn't Work
-1. **`gr.HTML` strips `<script>` tags** - Security feature
-2. **`js_on_load` with async `import()` blocks Svelte hydration** - **PROVEN** by A/B test
-3. **Our A/B test confirmed**: Disabling `js_on_load` makes the app load perfectly
-4. **`head=` parameter with `import()`** - Same hydration blocking issue
-
-### Gradio CAN Do WebGL
-**Important clarification:** Gradio supports WebGL via Custom Components. `gradio-litmodel3d` proves this.
-
-The issue is specifically the `gr.HTML` + `js_on_load` + `import()` pattern, NOT Gradio itself.
-
-### Gradio's Official Stance
-From Gradio maintainer Abubakar Abid on Issues #4511 and #7649:
-> "We are not planning to include this in the core Gradio library."
-> "We've now made it possible for Gradio users to create their own custom components."
-
-**The official answer is: Create a Gradio Custom Component.**
-
----
-
-## The Four Options (Ranked by Effort)
-
-### Option 1: Keep Hacking `gr.HTML` (Current Approach)
-- **Effort:** Low
-- **Success probability:** 30%
-- **What we're trying:** `head=`, `demo.load(_js=...)`, `gr.Blocks(js=...)`
-- **Problem:** Fighting Gradio's architecture
-
-### Option 2: Create a Gradio Custom Component
-- **Effort:** Medium (2-3 days)
-- **Success probability:** 90%
-- **What it is:** A proper Svelte + Python component that wraps NiiVue
-- **Why it works:** This is the official Gradio way to add WebGL
-- **Resources:**
-  - [Custom Components Guide](https://www.gradio.app/guides/custom-components-in-five-minutes)
-  - [gradio-litmodel3d](https://pypi.org/project/gradio-litmodel3d/) - Example WebGL custom component
-  - [Custom Components Gallery](https://www.gradio.app/custom-components/gallery)
-
-### Option 3: Static HTML Space (No Gradio)
-- **Effort:** High (rebuild entire UI)
-- **Success probability:** 99%
-- **What it is:** Pure HTML/CSS/JS app on HF Spaces
-- **Why it works:** WebGL works perfectly (Unity, Three.js examples exist)
-- **Downside:** Lose Gradio's nice features (file upload UX, etc.)
-
-### Option 4: 2D Slice Fallback (Remove NiiVue Entirely)
-- **Effort:** Low
-- **Success probability:** 100%
-- **What it is:** Use Matplotlib 2D slices instead of 3D WebGL viewer
-- **Why it works:** Already works (Static Report tab)
-- **Downside:** No interactive 3D visualization
-
----
-
-## Comparison: Custom Component vs Static HTML
-
-| Aspect | Custom Component | Static HTML |
-|--------|------------------|-------------|
-| Keep Gradio features | Yes | No |
-| File upload UX | Built-in | Must build |
-| Sliders/dropdowns | Built-in | Must build |
-| HF Spaces deployment | Works | Works |
-| Development time | 2-3 days | 3-5 days |
-| Maintainability | Better (Gradio handles updates) | Worse (all custom) |
-
----
-
-## Recommendation
-
-**If current PR #28 fails:**
-
-1. **First try:** `demo.load(_js=...)` approach (1 hour)
-2. **If that fails:** Create a Gradio Custom Component for NiiVue (2-3 days)
-3. **Nuclear option:** Static HTML Space or remove 3D viewer entirely
-
-**The Custom Component approach is the "correct" solution** - it's what Gradio maintainers recommend for WebGL content. We've been trying to hack around Gradio instead of working with it.
-
----
-
-## Existing Work We Can Reference
-
-1. **[gradio-litmodel3d](https://pypi.org/project/gradio-litmodel3d/)** - WebGL Model3D with HDR support
-2. **[Unet-nifti-gradio](https://github.com/benjaminirving/Unet-nifti-gradio)** - NIfTI + Gradio integration
-3. **[papaya-image-viewer-gradio](https://github.com/gradio-app/gradio/issues/4511)** - Medical imaging viewer mentioned in Issue #4511
-4. **[NiiVue docs](https://niivue.com/docs/)** - Official NiiVue integration guide
-
----
-
-## Answer: "What Does Gradio Unblock?"
-
-**Gradio unblocks:**
-- UI/UX components (dropdowns, sliders, file upload, etc.)
-- Backend/frontend communication
-- Easy HF Spaces deployment
-- Python-only development (no JS required for basic apps)
-
-**Gradio does NOT unblock:**
-- Custom WebGL content (you need a Custom Component)
-- Medical imaging formats (NIfTI, DICOM)
-- Advanced JavaScript integrations
-
-**If we go Static HTML:** Yes, we'd have to write all the HTML/CSS/JS ourselves, including file upload handling, UI layout, etc. That's what Gradio provides "for free."
-
----
-
-## Sources
-
-- [HF Forum: Gradio HTML with JS](https://discuss.huggingface.co/t/gradio-html-component-with-javascript-code-dont-work/37316)
-- [Gradio Issue #4511: 3D Medical Images](https://github.com/gradio-app/gradio/issues/4511)
-- [Gradio Issue #7649: WebGL Canvas](https://github.com/gradio-app/gradio/issues/7649)
-- [Gradio Custom Components Guide](https://www.gradio.app/guides/custom-components-in-five-minutes)
-- [HF Unity WebGL Template](https://github.com/huggingface/Unity-WebGL-template-for-Hugging-Face-Spaces)

docs/specs/28-gradio-custom-component-niivue.md

@@ -1,702 +0,0 @@
-# Spec #28: Gradio Custom Component for NiiVue
-
-**Date:** 2025-12-10
-**Status:** REQUIRED - All gr.HTML hacks have failed (confirmed Dec 10)
-**Blocks:** Issue #24 (HF Spaces "Loading..." forever)
-**Effort:** Medium (2-3 days + 0.5-1 day buffer for HF Spaces quirks)
-**Success Probability:** 90%
-**Audited:** AUDIT_REPORT_2025_12_10.md - GO recommendation
-
----
-
-## Executive Summary
-
-**All `gr.HTML` + JavaScript approaches have FAILED. This is the only path forward.**
-
-Gradio maintainers have explicitly closed both:
-- [Issue #4511](https://github.com/gradio-app/gradio/issues/4511) - NIfTI/medical imaging support → "Not planned"
-- [Issue #7649](https://github.com/gradio-app/gradio/issues/7649) - WebGL canvas component → "Not planned"
-
-Their official answer: **"Create a Gradio Custom Component."**
-
-This spec documents what we need to build to properly integrate NiiVue (WebGL2 medical imaging viewer) into our Gradio app.
-
----
-
-## Why Current Approach Fails
-
-### What We've Tried
-
-| Attempt | Why It Failed |
-|---------|---------------|
-| CDN import in js_on_load | HF Spaces CSP blocks external imports |
-| Vendored NiiVue + dynamic import() | import() in js_on_load blocks Svelte hydration |
-| head= parameter | Still uses ES module import, same problem |
-| head_paths= parameter | Same as above |
-| gr.set_static_paths() | File serving works, but JS loading mechanism broken |
-
-### Root Cause
-
-**We're fighting `gr.HTML`'s limitations, not Gradio itself.** Gradio CAN do WebGL (proven by `gradio-litmodel3d`), but NOT via `gr.HTML`:
-
-1. `gr.HTML` strips `<script>` tags (security)
-2. `js_on_load` runs during component mount - **async `import()` blocks Svelte hydration**
-3. Our A/B test proved: disabling `js_on_load` makes the app load perfectly
-
-**The `gr.HTML` + `js_on_load` + `import()` pattern is the blocker.** Custom Components solve this by using Svelte's proper `onMount` lifecycle.
-
----
-
-## The Solution: Gradio Custom Component
-
-### What Is a Gradio Custom Component?
-
-A Custom Component is a proper Svelte + Python component that integrates with Gradio's architecture:
-
-```
-gradio-niivue-viewer/
-├── frontend/
-│   ├── Index.svelte      # Svelte component (renders NiiVue)
-│   ├── package.json      # Frontend deps (including niivue)
-│   └── ...
-├── backend/
-│   └── gradio_niivue_viewer/
-│       └── __init__.py   # Python component class
-├── pyproject.toml        # Package definition
-└── demo/
-    └── app.py            # Example usage
-```
-
-### Why This Works
-
-1. **Svelte-native**: Component integrates with Gradio's lifecycle properly
-2. **Official pattern**: Gradio maintainers recommend this for WebGL
-3. **Isolated loading**: NiiVue loads within the component, not globally
-4. **Proper error handling**: Failures don't block app initialization
-5. **Reusable**: Can publish to PyPI for others to use
-
----
-
-## Prerequisites
-
-### Build Tooling Requirements
-
-| Tool | Version | Purpose |
-|------|---------|---------|
-| Node.js | >= 18.x | Required by `gradio cc build` |
-| npm | >= 9.x | Package management for Svelte frontend |
-| Python | >= 3.10 | Backend component |
-| Gradio | >= 5.0 | Custom component framework |
-
-Verify installation:
-```bash
-node --version  # v18.x or higher
-npm --version   # 9.x or higher
-gradio --version  # 5.x or higher
-```
-
-### Packaging Plan
-
-**Location:** Monorepo subdirectory at `packages/gradio-niivue-viewer/`
-
-This approach:
-- Keeps component close to main app for easy iteration
-- Allows `pip install -e packages/gradio-niivue-viewer` for local development
-- No PyPI publishing required initially (can add later)
-
----
-
-## Value Schema
-
-The component uses Gradio's file serving URLs (not base64) per Issue #19 optimization:
-
-```typescript
-// Frontend (Svelte)
-interface NiiVueViewerValue {
-  background_url: string | null;  // e.g., "/gradio_api/file=/tmp/.../dwi.nii.gz"
-  overlay_url: string | null;     // e.g., "/gradio_api/file=/tmp/.../mask.nii.gz"
-}
-```
-
-```python
-# Backend (Python)
-class NiiVueViewerData(GradioModel):
-    background_url: str | None = None  # Gradio file URL
-    overlay_url: str | None = None     # Gradio file URL
-```
-
-**Critical:** URLs must use `/gradio_api/file=` format, NOT base64. This reduces payload from ~65MB to <1KB.
-
----
-
-## Technical Approach
-
-### Phase 1: Scaffold Component (1 hour)
-
-Use Gradio's CLI to create the component:
-
-```bash
-# From repository root
-mkdir -p packages
-cd packages
-
-gradio cc create NiiVueViewer \
-  --template Image \
-  --overwrite
-```
-
-This creates the basic structure with Svelte frontend and Python backend.
-
-### Phase 2: Implement Svelte Frontend (4-6 hours)
-
-#### 2a. Install NiiVue dependency
-
-```bash
-cd packages/gradio-niivue-viewer/frontend
-npm install @niivue/niivue@0.65.0 --save-exact
-```
-
-This pins the exact version `0.65.0` to match our tested vendored copy.
-
-#### 2b. Verify package.json
-
-```json
-{
-  "name": "gradio-niivue-viewer",
-  "version": "0.1.0",
-  "dependencies": {
-    "@niivue/niivue": "0.65.0"
-  }
-}
-```
-
-#### 2c. Modify `frontend/Index.svelte`:
-
-```svelte
-<script lang="ts">
-  import { onMount, onDestroy } from 'svelte';
-  import { Niivue } from '@niivue/niivue';
-
-  // Value schema: Gradio file URLs (not base64)
-  export let value: {
-    background_url: string | null;
-    overlay_url: string | null;
-  } | null = null;
-
-  let container: HTMLDivElement;
-  let canvas: HTMLCanvasElement;
-  let nv: Niivue | null = null;
-  let error: string | null = null;
-  let loading: boolean = true;
-
-  // WebGL2 capability check
-  function checkWebGL2(): boolean {
-    const testCanvas = document.createElement('canvas');
-    const gl = testCanvas.getContext('webgl2');
-    return gl !== null;
-  }
-
-  onMount(async () => {
-    // Check WebGL2 support first
-    if (!checkWebGL2()) {
-      error = 'WebGL2 is not supported in this browser. Please use Chrome, Firefox, or Edge.';
-      loading = false;
-      return;
-    }
-
-    try {
-      nv = new Niivue({
-        backColor: [0, 0, 0, 1],
-        show3Dcrosshair: true,
-        logging: false,
-      });
-      await nv.attachToCanvas(canvas);
-
-      // Handle WebGL context loss
-      canvas.addEventListener('webglcontextlost', handleContextLost);
-      canvas.addEventListener('webglcontextrestored', handleContextRestored);
-
-      await loadVolumes();
-      loading = false;
-    } catch (e) {
-      error = `Failed to initialize viewer: ${e instanceof Error ? e.message : 'Unknown error'}`;
-      loading = false;
-    }
-  });
-
-  onDestroy(() => {
-    if (canvas) {
-      canvas.removeEventListener('webglcontextlost', handleContextLost);
-      canvas.removeEventListener('webglcontextrestored', handleContextRestored);
-    }
-    if (nv) nv.dispose();
-  });
-
-  function handleContextLost(event: Event) {
-    event.preventDefault();
-    error = 'WebGL context lost. Please refresh the page.';
-  }
-
-  function handleContextRestored() {
-    error = null;
-    if (nv && value) loadVolumes();
-  }
-
-  async function loadVolumes() {
-    if (!nv) return;
-
-    // Handle null/cleared value: clear the viewer
-    if (!value || (!value.background_url && !value.overlay_url)) {
-      try {
-        // Clear all loaded volumes
-        while (nv.volumes.length > 0) {
-          nv.removeVolumeByIndex(0);
-        }
-        nv.drawScene();
-      } catch (e) {
-        console.warn('Failed to clear volumes:', e);
-      }
-      return;
-    }
-
-    try {
-      loading = true;
-      error = null;
-
-      const volumes = [];
-      if (value.background_url) {
-        volumes.push({ url: value.background_url, name: 'background.nii.gz' });
-      }
-      if (value.overlay_url) {
-        volumes.push({
-          url: value.overlay_url,
-          name: 'overlay.nii.gz',
-          colorMap: 'red',
-          opacity: 0.5,
-        });
-      }
-
-      if (volumes.length > 0) {
-        await nv.loadVolumes(volumes);
-        // Configure view after loading
-        nv.setSliceType(nv.sliceTypeMultiplanar);
-        nv.setRenderAzimuthElevation(120, 10);
-        nv.drawScene();
-      }
-
-      loading = false;
-    } catch (e) {
-      error = `Failed to load volumes: ${e instanceof Error ? e.message : 'Unknown error'}`;
-      loading = false;
-    }
-  }
-
-  // Reactive: reload when value changes (including null to clear)
-  $: if (nv && !loading) loadVolumes();
-</script>
-
-<div bind:this={container} class="niivue-container">
-  {#if error}
-    <div class="error-message">{error}</div>
-  {:else if loading}
-    <div class="loading-message">Loading viewer...</div>
-  {/if}
-  <canvas bind:this={canvas} class:hidden={!!error}></canvas>
-</div>
-
-<style>
-  .niivue-container {
-    width: 100%;
-    height: 500px;
-    background: #000;
-    position: relative;
-    border-radius: 8px;
-    overflow: hidden;
-  }
-  canvas {
-    width: 100%;
-    height: 100%;
-  }
-  canvas.hidden {
-    display: none;
-  }
-  .error-message {
-    position: absolute;
-    top: 50%;
-    left: 50%;
-    transform: translate(-50%, -50%);
-    color: #f66;
-    text-align: center;
-    padding: 20px;
-    max-width: 80%;
-  }
-  .loading-message {
-    position: absolute;
-    top: 50%;
-    left: 50%;
-    transform: translate(-50%, -50%);
-    color: #888;
-    text-align: center;
-  }
-</style>
-```
-
-**Key improvements from audit feedback:**
-- WebGL2 capability check before initialization
-- WebGL context loss/restore handlers
-- Proper error UI states
-- Loading state management
-- Reactive update when value changes
-
-### Phase 3: Implement Python Backend (2-3 hours)
-
-```python
-# backend/gradio_niivue_viewer/__init__.py
-from __future__ import annotations
-from typing import Any
-from gradio.components.base import Component
-from gradio.data_classes import FileData, GradioModel
-
-class NiiVueViewerData(GradioModel):
-    background_url: str | None = None
-    overlay_url: str | None = None
-
-class NiiVueViewer(Component):
-    """WebGL NIfTI viewer using NiiVue."""
-
-    data_model = NiiVueViewerData
-
-    def __init__(
-        self,
-        value: NiiVueViewerData | None = None,
-        *,
-        label: str | None = None,
-        height: int = 500,
-        **kwargs,
-    ):
-        self.height = height
-        super().__init__(value=value, label=label, **kwargs)
-
-    def preprocess(self, payload: NiiVueViewerData | None) -> dict[str, Any] | None:
-        if payload is None:
-            return None
-        return {
-            "background_url": payload.background_url,
-            "overlay_url": payload.overlay_url,
-        }
-
-    def postprocess(self, value: dict[str, Any] | None) -> NiiVueViewerData | None:
-        if value is None:
-            return None
-        return NiiVueViewerData(
-            background_url=value.get("background_url"),
-            overlay_url=value.get("overlay_url"),
-        )
-```
-
-### Phase 4: Build and Test (2-3 hours)
-
-```bash
-# Build the component
-cd gradio-niivue-viewer
-gradio cc build
-
-# Install locally
-pip install -e .
-
-# Test in demo app
-python demo/app.py
-```
-
-### Phase 5: Integrate into stroke-deepisles-demo (1-2 hours)
-
-Replace `gr.HTML` with the custom component:
-
-```python
-# Before (broken)
-from stroke_deepisles_demo.ui.viewer import create_niivue_html
-viewer = gr.HTML(value="", elem_id="niivue-viewer")
-# ... then set viewer.value = create_niivue_html(...)
-
-# After (working)
-from gradio_niivue_viewer import NiiVueViewer
-viewer = NiiVueViewer(label="Interactive 3D Viewer")
-# ... then set viewer.value = {"background_url": dwi_url, "overlay_url": mask_url}
-```
-
-### Phase 6: HF Spaces Deployment (CRITICAL)
-
-**This phase is essential.** HF Spaces runs `pip install` only - it does NOT run `npm` or `gradio cc build`.
-
-#### 6a. Commit build artifacts to git
-
-```bash
-cd packages/gradio-niivue-viewer
-
-# Build the component (generates frontend/dist/ or templates/)
-gradio cc build
-
-# Force-add build artifacts (they may be gitignored by default)
-git add -f gradio_niivue_viewer/templates/
-# Or wherever the build output lands - check with:
-# find . -name "*.js" -path "*/dist/*" -o -name "*.css" -path "*/dist/*"
-
-git commit -m "chore: add compiled frontend assets for HF Spaces deployment"
-```
-
-**Why:** HF Spaces won't run npm/node build steps. The compiled JS/CSS must be in the repo.
-
-#### 6b. Update requirements.txt
-
-Add the local component to the main `requirements.txt`:
-
-```text
-# requirements.txt
-gradio>=5.0
-# ... other deps ...
-
-# Local custom component (editable install)
--e ./packages/gradio-niivue-viewer
-```
-
-**Alternative:** If the component is at repo root:
-```text
--e .
-```
-
-#### 6c. Verify .gitignore doesn't exclude build artifacts
-
-Check that `packages/gradio-niivue-viewer/.gitignore` doesn't exclude:
-- `gradio_niivue_viewer/templates/`
-- `frontend/dist/`
-- Any compiled `.js` or `.css` files needed at runtime
-
-If they're excluded, either:
-1. Remove those lines from `.gitignore`, OR
-2. Use `git add -f` to force-add them
-
-#### 6d. Test deployment flow
-
-```bash
-# Simulate what HF Spaces does
-pip install -r requirements.txt
-python -m stroke_deepisles_demo.ui.app
-
-# Should work WITHOUT running gradio cc build
-```
-
----
-
-## Existing References
-
-### Working WebGL Custom Components
-
-1. **[gradio-litmodel3d](https://pypi.org/project/gradio-litmodel3d/)**
-   - WebGL Model3D viewer with HDR lighting
-   - Source: https://github.com/gradio-app/gradio/tree/main/demo/model3d_component
-   - Proof that WebGL works in Custom Components
-
-2. **[gradio-molecule3d](https://pypi.org/project/gradio-molecule3d/)**
-   - 3D molecule viewer
-   - Uses Three.js (WebGL)
-
-### Gradio Documentation
-
-- [Custom Components in 5 Minutes](https://www.gradio.app/guides/custom-components-in-five-minutes)
-- [Gradio Components Documentation](https://www.gradio.app/docs/gradio/components)
-- [Custom Component Gallery](https://www.gradio.app/custom-components/gallery)
-
-### NiiVue Resources
-
-- [NiiVue GitHub](https://github.com/niivue/niivue)
-- [NiiVue npm](https://www.npmjs.com/package/@niivue/niivue)
-- [NiiVue Examples](https://niivue.com/docs/)
-
----
-
-## Acceptance Criteria
-
-### Must Have (MVP)
-
-- [ ] Component loads NIfTI volumes from Gradio file URLs
-- [ ] Component displays background image (DWI)
-- [ ] Component displays overlay mask (segmentation) with colormap
-- [ ] Component works on HuggingFace Spaces
-- [ ] No "Loading..." hang - failures are graceful
-- [ ] All existing tests pass
-
-### Nice to Have (Future)
-
-- [ ] Crosshair controls
-- [ ] Slice orientation toggle (axial/coronal/sagittal)
-- [ ] Opacity slider for overlay
-- [ ] Pan/zoom/rotate controls
-- [ ] Screenshot/export functionality
-- [ ] Publish to PyPI for community use
-
----
-
-## Risk Assessment
-
-| Risk | Mitigation |
-|------|------------|
-| Svelte/TypeScript learning curve | Follow gradio-litmodel3d example closely |
-| NiiVue WebGL2 browser support | Explicit WebGL2 check in Svelte + graceful error UI |
-| Build system complexity | Use gradio cc tooling, don't customize |
-| HF Spaces static file serving | Component bundles NiiVue, no external deps |
-| **Build artifacts not in git** | Phase 6a: Force-add compiled assets with `git add -f` |
-| **requirements.txt missing component** | Phase 6b: Add `-e ./packages/gradio-niivue-viewer` |
-
----
-
-## Alternatives Considered
-
-### Alternative 1: Keep Hacking gr.HTML
-- **Effort:** Low
-- **Success probability:** 0% (CONFIRMED FAILED)
-- **Why rejected:** We tried 6 approaches over 2 days. ALL failed. This is not a viable path.
-
-### Alternative 2: Static HTML Space (No Gradio)
-- **Effort:** High (rebuild entire UI)
-- **Success probability:** 99%
-- **Why rejected:** Lose Gradio's file upload, dropdowns, layout features. Too much work.
-
-### Alternative 3: Remove 3D Viewer (2D Only)
-- **Effort:** Low
-- **Success probability:** 100%
-- **Why rejected:** Loses key feature. Static Report tab already works, but 3D is valuable.
-
----
-
-## Decision
-
-**Proceed with Gradio Custom Component approach.**
-
-This is the official Gradio-recommended solution. It's more work than hacking `gr.HTML`, but it's the architecturally correct approach with 90% success probability vs 30%.
-
----
-
-## Testing Matrix
-
-### Level 1: Local Build Verification
-
-```bash
-cd packages/gradio-niivue-viewer
-
-# Build component
-gradio cc build
-
-# Install locally
-pip install -e .
-
-# Run demo app
-python demo/app.py
-# → Verify: App loads, no console errors, viewer renders
-```
-
-**Pass criteria:**
-- [ ] `gradio cc build` completes without errors
-- [ ] Demo app launches at localhost:7860
-- [ ] No JavaScript console errors
-- [ ] Canvas renders (black background visible)
-
-### Level 2: Volume Loading Test
-
-```python
-# demo/app.py
-import gradio as gr
-from gradio_niivue_viewer import NiiVueViewer
-
-def load_sample():
-    # Use a known good NIfTI file
-    return {
-        "background_url": "/gradio_api/file=/path/to/sample.nii.gz",
-        "overlay_url": None
-    }
-
-with gr.Blocks() as demo:
-    viewer = NiiVueViewer()
-    btn = gr.Button("Load Sample")
-    btn.click(load_sample, outputs=viewer)
-
-demo.launch()
-```
-
-**Pass criteria:**
-- [ ] NIfTI file loads without errors
-- [ ] Multiplanar view displays correctly
-- [ ] Overlay mask renders with red colormap (when provided)
-
-### Level 3: HF Spaces Dry Run
-
-Deploy to a **private/throwaway Space** before production:
-
-```bash
-# Create test space
-huggingface-cli repo create test-niivue-viewer --type space --private
-
-# Push and test
-git push hf-test main
-```
-
-**Pass criteria:**
-- [ ] Space shows "Running" (not stuck on "Loading...")
-- [ ] Viewer initializes (no hydration deadlock)
-- [ ] Volume loading works via Gradio file serving
-- [ ] WebGL2 error shown gracefully if unsupported
-
-### Level 4: Integration Test
-
-Replace `gr.HTML` in stroke-deepisles-demo:
-
-```python
-# src/stroke_deepisles_demo/ui/components.py
-from gradio_niivue_viewer import NiiVueViewer
-
-def create_results_display():
-    # ...
-    niivue_viewer = NiiVueViewer(label="Interactive 3D Viewer")
-    # ...
-```
-
-**Pass criteria:**
-- [ ] Existing 136 tests still pass
-- [ ] Segmentation pipeline works end-to-end
-- [ ] Viewer displays DWI + mask overlay
-- [ ] No "Loading..." hang on HF Spaces
-
----
-
-## Next Steps
-
-1. [x] Senior review of this spec (AUDIT_REPORT_2025_12_10.md)
-2. [x] Red team review - all gaps addressed (build artifacts, npm install, null handling)
-3. [ ] Create `packages/gradio-niivue-viewer/` subdirectory
-4. [ ] Scaffold component with `gradio cc create`
-5. [ ] Install NiiVue: `cd frontend && npm install @niivue/niivue@0.65.0`
-6. [ ] Implement Svelte frontend (with WebGL2 checks + null value handling)
-7. [ ] Implement Python backend
-8. [ ] Level 1 test: Local build verification
-9. [ ] Level 2 test: Volume loading
-10. [ ] Level 3 test: HF Spaces dry run
-11. [ ] Level 4 test: Integration
-12. [ ] **CRITICAL**: Commit build artifacts to git
-13. [ ] **CRITICAL**: Update requirements.txt with `-e ./packages/gradio-niivue-viewer`
-14. [ ] (Optional) Publish to PyPI
-
----
-
-## Appendix: Why WebGL + `gr.HTML` Doesn't Work
-
-From the ROOT_CAUSE_ANALYSIS.md and GRADIO_WEBGL_ANALYSIS.md research:
-
-1. **Gradio CAN do WebGL** - proven by `gradio-litmodel3d` custom component
-2. **But NOT via `gr.HTML`** - the `js_on_load` + `import()` pattern blocks Svelte hydration
-3. **Our A/B test proved it** - disabling `js_on_load` makes the app load perfectly
-4. **Gradio closed NIfTI support** (Issue #4511) - "Not planned for core"
-5. **Gradio closed WebGL canvas** (Issue #7649) - "Not planned for core"
-6. **gr.HTML strips script tags** - Security feature, can't bypass
-7. **HF Spaces CSP blocks external CDNs** - Must vendor or bundle dependencies
-8. **Gradio maintainer recommendation**: Custom Components
-
-The pattern is clear: **The `gr.HTML` + `js_on_load` + async `import()` pattern is fundamentally broken.** The Custom Component is the officially supported path for WebGL content.

docs/specs/29-codebase-status-audit.md

@@ -1,276 +0,0 @@
-# Spec #29: Codebase Status Audit (Issue #24 NiiVue/WebGL)
-
-**Date:** 2025-12-10
-**Status:** ALL `gr.HTML` HACKS CONFIRMED FAILED (Dec 10, 2025)
-**Purpose:** Top-down analysis of current frontend/NiiVue implementation state after multiple hotfix attempts
-
----
-
-## Executive Summary: The `gr.HTML` + `js_on_load` + `import()` Pattern is Broken
-
-After 6 iterations of attempted hotfixes for Issue #24 (HF Spaces "Loading..." forever), **every `gr.HTML`-based approach has failed**:
-
-| Attempt | Result |
-|---------|--------|
-| CDN import | FAILED - CSP blocked |
-| Vendored + js_on_load import() | FAILED - Blocks Svelte hydration |
-| head_paths | FAILED - Same hydration issue |
-| head= with import() | **FAILED** - Confirmed Dec 10 |
-
-**Root Cause (PROVEN):** Async `import()` inside `js_on_load` blocks Gradio's Svelte hydration. Our A/B test confirmed: disabling `js_on_load` makes the app load.
-
-**Clarification:** Gradio CAN do WebGL via Custom Components (`gradio-litmodel3d` proves this). The issue is the `gr.HTML` approach, not Gradio itself.
-
-**The correct solution is Gradio Custom Component (spec #28).**
-
----
-
-## Current Frontend Architecture
-
-### File Inventory
-
-| File | Purpose | Lines | Status |
-|------|---------|-------|--------|
-| `ui/viewer.py` | NiiVue HTML/JS generation | 643 | **BLOATED** - contains 5 approaches |
-| `ui/app.py` | Main Gradio app | 313 | Clean |
-| `ui/components.py` | UI components | 94 | Clean |
-| `app.py` (root) | Local dev entry | 61 | Clean |
-| `ui/assets/niivue.js` | Vendored NiiVue v0.65.0 | 2.9MB | **NECESSARY** |
-
-### What's in `viewer.py` Right Now
-
-| Component | Lines | Status | Notes |
-|-----------|-------|--------|-------|
-| `NIIVUE_VERSION` | 30 | OK | Version tracking |
-| `_ASSET_DIR`, `_NIIVUE_JS_PATH` | 31-32 | OK | Path constants |
-| `NIIVUE_JS_URL` | 36 | **UNUSED** | Computed but not actually used |
-| Module-level logging | 39-42 | **SLOP** | 4 log statements at import time |
-| `get_niivue_head_html()` | 45-77 | **PROBLEMATIC** | Still uses `await import()` |
-| `get_niivue_loader_path()` | 80-109 | **DEPRECATED** | Marked deprecated but still exists |
-| `nifti_to_gradio_url()` | 112-142 | OK | Issue #19 fix, working |
-| `get_slice_at_max_lesion()` | 145-187 | OK | Matplotlib helper |
-| `render_3panel_view()` | 190-281 | OK | Matplotlib 3-panel |
-| `render_slice_comparison()` | 284-380 | OK | Matplotlib comparison |
-| `create_niivue_html()` | 383-434 | OK | HTML generation |
-| `NIIVUE_ON_LOAD_JS` | 449-538 | **MOSTLY OK** | No import(), uses window.Niivue |
-| `NIIVUE_UPDATE_JS` | 546-642 | **MOSTLY OK** | No import(), uses window.Niivue |
-
----
-
-## The Core Problem: `get_niivue_head_html()` Still Uses `import()`
-
-The current "fix" in `get_niivue_head_html()` does this:
-
-```javascript
-// viewer.py:63-76
-<script type="module">
-    try {
-        const niivueUrl = '{NIIVUE_JS_URL}';
-        console.log('[NiiVue Loader] Attempting to load from:', niivueUrl);
-        const { Niivue } = await import(niivueUrl);  // <-- SAME BROKEN PATTERN!
-        window.Niivue = Niivue;
-        console.log('[NiiVue Loader] Successfully loaded');
-    } catch (error) {
-        console.error('[NiiVue Loader] FAILED to load:', error);
-        window.NIIVUE_LOAD_ERROR = error.message;
-    }
-</script>
-```
-
-**This is the EXACT same `await import()` pattern that breaks on HF Spaces.**
-
-The only difference from our previous attempts:
-- Before: `await import()` in `js_on_load`
-- Now: `await import()` in `head=` script
-
-**Why this might not matter:** The A/B test proved that `js_on_load` with async code breaks Gradio. Moving the `import()` to `head=` might help, but it's still executing async code that could fail silently and leave `window.Niivue` undefined.
-
----
-
-## What's Necessary vs What's Slop
-
-### NECESSARY (Keep)
-
-| Item | Why |
-|------|-----|
-| `ui/assets/niivue.js` | HF Spaces CSP blocks CDN imports |
-| `gr.set_static_paths()` | Required for Gradio 6.x file serving |
-| `nifti_to_gradio_url()` | Issue #19 fix, working |
-| `create_niivue_html()` | Generates viewer HTML |
-| `NIIVUE_ON_LOAD_JS` | Initializes viewer (doesn't import) |
-| `NIIVUE_UPDATE_JS` | Re-initializes after updates |
-| Matplotlib functions | Working 2D fallback |
-| `allowed_paths` in launch() | Runtime file access |
-
-### SLOP (Should Remove/Refactor)
-
-| Item | Why It's Slop |
-|------|---------------|
-| `NIIVUE_JS_URL` module-level computation | Computed but unused in production |
-| Module-level logging (lines 39-42) | Noisy startup logs, not useful |
-| `get_niivue_loader_path()` | Deprecated, generates file we don't need |
-| `get_niivue_head_html()` with import() | Still uses broken pattern |
-| Multiple diagnostic docs | Overlapping, contradictory, stale |
-
-### UNCERTAIN (Depends on head= fix working)
-
-| Item | Status |
-|------|--------|
-| `head=get_niivue_head_html()` in launch() | **30% chance this works** |
-
----
-
-## Documentation Status
-
-### docs/specs/ Files
-
-| File | Status | Issue |
-|------|--------|-------|
-| `00-context.md` | **ACCURATE** | None |
-| `28-gradio-custom-component-niivue.md` | **ACCURATE** | Just written |
-| `AUDIT_JS_LOADING_ISSUES.md` | **OUTDATED** | Says `set_static_paths` is blocker, but we've moved past that |
-| `DIAGNOSTIC_HF_LOADING.md` | **OUTDATED** | Lists hypotheses we've since disproven |
-| `ROOT_CAUSE_ANALYSIS.md` | **PARTIALLY OUTDATED** | Says "IN PROGRESS", discusses head= as solution |
-| `GRADIO_WEBGL_ANALYSIS.md` | **ACCURATE** | Core analysis, identifies real problem |
-
-### docs/TECHNICAL_DEBT.md
-
-| Status | Issue |
-|--------|-------|
-| **OUTDATED** | Claims "Ironclad/Production-Ready" but doesn't mention P0 NiiVue/WebGL blocker |
-
----
-
-## Recommended Cleanup Actions
-
-### Immediate (If head= fix fails)
-
-1. **Delete deprecated code:**
-   - Remove `get_niivue_loader_path()`
-   - Remove module-level logging
-   - Clean up `NIIVUE_JS_URL` if unused
-
-2. **Archive old diagnostic docs:**
-   - Move `AUDIT_JS_LOADING_ISSUES.md` to `archive/`
-   - Move `DIAGNOSTIC_HF_LOADING.md` to `archive/`
-   - Update `ROOT_CAUSE_ANALYSIS.md` status
-
-3. **Update TECHNICAL_DEBT.md:**
-   - Add P0 section for NiiVue/WebGL blocker
-   - Link to spec #28 (Custom Component)
-
-### Long-term (After decision on path forward)
-
-1. **If Custom Component route:**
-   - Remove all `head=` NiiVue loading code
-   - Remove `get_niivue_head_html()`
-   - Simplify `viewer.py` to just Matplotlib functions
-   - NiiVue loading becomes the component's responsibility
-
-2. **If 2D fallback route:**
-   - Remove entire NiiVue integration
-   - Remove `ui/assets/niivue.js` (2.9MB)
-   - Remove `NIIVUE_ON_LOAD_JS`, `NIIVUE_UPDATE_JS`
-   - Keep only Matplotlib rendering
-
----
-
-## Honest Assessment
-
-### What We've Tried (6+ iterations)
-
-1. **CDN import** → Blocked by CSP
-2. **Vendored + dynamic import in js_on_load** → Blocks Svelte hydration
-3. **head_paths with loader HTML** → Complex, didn't work
-4. **head= with inline import()** → Current state, **probably won't work**
-5. **Various set_static_paths/allowed_paths combos** → File serving works, JS loading doesn't
-
-### The Pattern
-
-Every attempt has been a variation of:
-> "Load NiiVue via some JavaScript mechanism within Gradio"
-
-Every attempt has failed because:
-> **Gradio was not designed for custom WebGL content**
-
-### The Correct Solution
-
-**Stop fighting Gradio's architecture. Use a Gradio Custom Component.**
-
-This is:
-- What Gradio maintainers recommend (Issues #4511, #7649)
-- How existing WebGL components work (gradio-litmodel3d)
-- 90% success probability vs 30% for more hacks
-
-See spec #28 for implementation details.
-
----
-
-## Current Entry Point Flow
-
-```
-HF Spaces Docker
-    ↓
-CMD ["python", "-m", "stroke_deepisles_demo.ui.app"]
-    ↓
-ui/app.py __main__ block
-    ↓
-gr.set_static_paths([_ASSETS_DIR])  # Enable file serving
-    ↓
-get_demo()  # Creates Blocks with js_on_load components
-    ↓
-demo.launch(
-    head=get_niivue_head_html(),    # <-- Injects <script type="module"> with import()
-    allowed_paths=[_ASSETS_DIR],
-)
-    ↓
-Browser loads page
-    ↓
-<head> script runs: await import('/gradio_api/file=.../niivue.js')
-    ↓
-[UNCERTAIN] Does import() succeed? Does it block Svelte?
-    ↓
-If yes: window.Niivue is set, js_on_load works
-If no: window.Niivue undefined, viewer shows error
-```
-
----
-
-## Files Modified During Issue #24 Debug
-
-| File | Changes | Commits |
-|------|---------|---------|
-| `viewer.py` | ~6 rewrites of JS loading approach | Multiple |
-| `ui/app.py` | Added head=, set_static_paths | Multiple |
-| `app.py` | Same as ui/app.py | Multiple |
-| `ui/assets/niivue.js` | Added vendored library | 1 |
-| `.gitignore` | Added niivue-loader.html | 1 |
-| `.pre-commit-config.yaml` | Exclude assets/ from large file check | 1 |
-
----
-
-## Conclusion
-
-**The codebase is messy but not unfixable.** The mess comes from iterating through multiple failed approaches without cleaning up between attempts.
-
-**The real issue is architectural:** Gradio + custom WebGL = unsupported pattern.
-
-**Next steps:**
-1. Test if current `head=` approach works on HF Spaces (low confidence)
-2. If it fails, implement Gradio Custom Component (spec #28)
-3. Clean up cruft regardless of which path we take
-
----
-
-## Appendix: How to Verify Current State
-
-```bash
-# Check if NiiVue file serving works
-curl -I "https://[space-url]/gradio_api/file=/home/user/demo/src/stroke_deepisles_demo/ui/assets/niivue.js"
-# Should return 200 OK with application/javascript
-
-# Check browser console for:
-# - "[NiiVue Loader] Attempting to load from: ..."
-# - "[NiiVue Loader] Successfully loaded" OR "[NiiVue Loader] FAILED"
-# - Any errors during Gradio initialization
-```

docs/specs/30-bug-hf-spaces-build-packages-dir.md

@@ -1,116 +0,0 @@
-# Spec #30: HF Spaces Build Error - Missing packages/ Directory
-
-## Status: 🔴 P0 BLOCKER
-
-## Issue
-HuggingFace Spaces Docker build fails with:
-```
-ERROR: Invalid requirement: './packages/niivueviewer': Expected package name at the start of dependency specifier
-    ./packages/niivueviewer
-    ^ (from line 28 of requirements.txt)
-Hint: It looks like a path. File './packages/niivueviewer' does not exist.
-```
-
-## Root Cause Analysis
-
-### Timeline
-1. PR #29 added `gradio_niivueviewer` custom component in `packages/niivueviewer/`
-2. Added `./packages/niivueviewer` to `requirements.txt` line 28 for local installs
-3. Dockerfile copies `requirements.txt` but NOT `packages/` directory
-4. `pip install -r requirements.txt` fails because path doesn't exist
-
-### Architecture Gap
-```
-Local Development:
-  requirements.txt → ./packages/niivueviewer → ✅ EXISTS
-
-HF Spaces Docker:
-  COPY requirements.txt → Container
-  pip install -r requirements.txt
-  → ./packages/niivueviewer → ❌ NOT COPIED
-```
-
-## Solution Options
-
-### Option A: Copy packages/ in Dockerfile (Recommended)
-Add `COPY --chown=1000:1000 packages/ /home/user/demo/packages/` before pip install.
-
-**Pros:**
-- Simple fix
-- Preserves local development workflow
-- Editable install works correctly
-
-**Cons:**
-- Adds ~1.3MB to Docker image (compiled JS bundle)
-
-### Option B: Build wheel and include in Docker
-Pre-build wheel, copy to container, install from wheel file.
-
-**Pros:**
-- More "production" approach
-
-**Cons:**
-- More complex build process
-- Need to manage wheel artifacts
-
-### Option C: Separate requirements files
-Create `requirements-docker.txt` without local path dependencies.
-
-**Pros:**
-- Clear separation of concerns
-
-**Cons:**
-- Duplicate maintenance
-- Easy to drift out of sync
-
-## Recommended Fix
-
-**Option A** - Simple, maintainable, aligns with how local development works.
-
-### Implementation
-
-```dockerfile
-# BEFORE pip install, add:
-COPY --chown=1000:1000 packages/ /home/user/demo/packages/
-```
-
-### Full Dockerfile Change
-
-```dockerfile
-# Copy requirements first for better layer caching
-COPY --chown=1000:1000 requirements.txt /home/user/demo/requirements.txt
-
-# Copy custom component packages (required for pip install)
-COPY --chown=1000:1000 packages/ /home/user/demo/packages/
-
-# Install Python dependencies into SYSTEM Python
-RUN pip install --no-cache-dir -r requirements.txt
-```
-
-## Test Plan
-
-### Level 1: Local Docker Build
-```bash
-docker build -t stroke-demo-test .
-docker run -p 7860:7860 stroke-demo-test
-```
-
-### Level 2: HF Spaces Deploy
-Push to HF Spaces, verify build succeeds and app loads.
-
-### Level 3: Functional Test
-- Upload NIfTI files
-- Run segmentation
-- Verify NiiVue 3D viewer renders volumes
-
-## Files to Modify
-- `Dockerfile` - Add COPY for packages/ directory
-
-## Risk Assessment
-- **Low risk** - Additive change, doesn't modify existing code
-- **Reversible** - Can easily remove if issues arise
-
-## Acceptance Criteria
-- [ ] HF Spaces build succeeds
-- [ ] App loads without "Loading..." hang
-- [ ] NiiVue viewer displays volumes correctly

docs/specs/AUDIT_REPORT_2025_12_10.md

@@ -1,52 +0,0 @@
-# Audit Report: Issue #24 Root Cause & Custom Component Proposal
-
-**Date:** December 10, 2025
-**Auditor:** Gemini (Senior CLI Agent)
-**Review Scope:** Spec #28, Root Cause Analysis, Codebase Status
-
-## 1. Executive Summary
-
-**Recommendation: GO** - Proceed immediately with Spec #28 (Gradio Custom Component).
-
-My audit confirms your root cause analysis is accurate and your proposed solution is the correct, architecturally supported path. The "hacks" involving `gr.HTML` and `js_on_load` are fundamentally incompatible with Gradio's Svelte-based hydration lifecycle, especially when involving asynchronous module loading (`import()`). Continued attempts to patch `gr.HTML` will likely result in further fragility or failure.
-
-## 2. Validation of Root Cause Analysis
-
-| Claim | Verdict | Evidence/Rationale |
-|-------|---------|--------------------|
-| **Gradio lacks native WebGL/NIfTI in core** | **CONFIRMED** | Issues #4511 and #7649 closed as "not planned" for core. BUT `gradio-litmodel3d` proves WebGL works via Custom Components. |
-| **`gr.HTML` + `import()` breaks hydration** | **CONFIRMED** | `js_on_load` runs during the critical hydration phase. Async operations or unhandled Promise rejections here can hang the entire Gradio app ("Loading..." forever). |
-| **HF Spaces CSP blocks CDNs** | **CONFIRMED** | HF Spaces enforces strict CSP. While `custom_http_headers` *can* relax this, it doesn't solve the hydration/execution context issue. |
-| **`gr.HTML` strips `<script>`** | **CONFIRMED** | Standard security behavior. The `head=` workaround puts scripts in the global scope, polluting the window object and risking race conditions, which you effectively identified. |
-
-**Key Insight:** The "Loading..." hang isn't just a network error; it's a frontend application state deadlock. Your move to a Custom Component moves the NiiVue initialization into a self-contained Svelte `onMount` lifecycle method, which is the correct place for side effects like WebGL context creation.
-
-## 3. Evaluation of Proposed Solution (Spec #28)
-
-The proposed architecture for `gradio_niivue_viewer` is sound and follows best practices.
-
-*   **Architecture:** Python Backend (data passing) + Svelte Frontend (NiiVue rendering) is the standard pattern.
-*   **Reference:** `gradio-litmodel3d` is an excellent precedent. It proves WebGL contexts can be managed within a custom component.
-*   **Data Passing:** Reusing the "File URL" optimization (Issue #19) is critical. Passing 65MB+ base64 strings to a custom component would degrade performance; passing `/gradio_api/file=` URLs is efficient.
-
-**Refinements for Implementation:**
-*   **Build Tooling:** Ensure you have `node` and `npm` available in your environment, as `gradio cc build` requires them.
-*   **Type Safety:** The Svelte code in your spec uses TypeScript (`<script lang="ts">`). Ensure your `tsconfig.json` (generated by `gradio cc`) is configured to handle `niivue` types if available, or add a declaration file.
-*   **Fallbacks:** In your Svelte component, explicitly handle the case where WebGL2 context is lost or unavailable, providing a user-friendly error message within the component div, rather than crashing the whole app.
-
-## 4. Alternative Approaches Audit
-
-You correctly dismissed the alternatives:
-*   **CSP Header Config:** You *could* edit `README.md` to allow external CDNs (`custom_http_headers`), but this only fixes the *loading* of the script, not the *hydration blocking* caused by `js_on_load`. It's a partial fix that leads to the same deadlock.
-*   **Static HTML Space:** Too high effort. Losing Gradio's file/state management would require rewriting the entire backend API.
-
-## 5. Risk Assessment
-
-*   **Component Publishing:** You don't strictly *need* to publish to PyPI to use it. You can install it locally (`pip install -e .`) within your repo, which is faster for iteration.
-*   **NiiVue Version:** Ensure the custom component's `package.json` pins the exact version of NiiVue you've been testing with (`0.65.0` or newer) to avoid regressions.
-
-## 6. Conclusion
-
-Your analysis effectively ruled out "easy" hacks. The investment of 2-3 days for a Custom Component is justified and necessary to unblock Feature #24.
-
-**Next Action:** Initialize the custom component immediately.

docs/specs/NIIVUE-GRADIO-POSTMORTEM.md

@@ -0,0 +1,408 @@
+# NiiVue + Gradio Integration: POSTMORTEM
+
+**Date:** 2025-12-10
+**Status:** ABANDONED
+**Time Spent:** 2+ days
+**Result:** IMPOSSIBLE with current Gradio architecture
+
+---
+
+## Executive Summary
+
+We attempted to integrate NiiVue (a WebGL-based neuroimaging viewer) into a Gradio application deployed on HuggingFace Spaces. After exhaustive investigation across 10+ approaches, we conclusively determined that **Gradio is fundamentally incompatible with NiiVue or any JavaScript library requiring reliable execution**.
+
+---
+
+## Stack Versions
+
+| Component | Version |
+|-----------|---------|
+| Python | 3.12 |
+| Gradio | >=6.0.0,<7.0.0 |
+| NiiVue | 0.65.0 (vendored) |
+| Svelte (custom component) | ^5.43.4 |
+| @gradio/preview | 0.15.1 |
+| HuggingFace Spaces | Docker SDK |
+
+---
+
+## The Problem
+
+We needed to display NiiVue inside a Gradio app on HF Spaces. NiiVue requires JavaScript execution to initialize WebGL and render volumes.
+
+**Gradio does not reliably support JavaScript execution in HTML components.**
+
+---
+
+## All Approaches Tried
+
+### 1. gr.HTML with Inline `<script>` Tags
+
+**What we did:** Put `<script type="module">` inside gr.HTML value
+
+**Result:** FAILED
+
+**Why:** Browsers do not execute `<script>` tags inserted via innerHTML. This is a browser security feature, not a bug. Gradio uses innerHTML to update gr.HTML components.
+
+**Source:** [HuggingFace Forum](https://discuss.huggingface.co/t/gradio-html-component-with-javascript-code-dont-work/37316)
+
+---
+
+### 2. js_on_load Parameter with Dynamic import()
+
+**What we did:** Used `gr.HTML(js_on_load=...)` with async IIFE containing `await import('niivue')`
+
+**Result:** FAILED
+
+**Why:** The async `import()` blocks Gradio's Svelte hydration process. The entire UI freezes on "Loading..." forever.
+
+**Evidence:** A/B test confirmed - disabling js_on_load made the app load perfectly. All other features (DeepISLES pipeline, Matplotlib, Metrics) worked.
+
+**Technical Detail:** `js_on_load` only runs ONCE when the component first mounts. When `gr.HTML` value updates (after segmentation), js_on_load does NOT re-run. The HTML updates but JavaScript initialization never happens again.
+
+**Source:** [Gradio Custom HTML Components Guide](https://www.gradio.app/guides/custom_HTML_components) - "Event listeners attached in js_on_load are only attached once when the component is first rendered."
+
+---
+
+### 3. .then(fn=None, js=...) Pattern
+
+**What we did:** Tried using `.then(fn=None, js=NIIVUE_UPDATE_JS)` on event handlers
+
+**Result:** FAILED
+
+**Why:** The `js` parameter in event handlers has a completely different context than `js_on_load`:
+- `js_on_load` has access to `element` (the DOM element)
+- `js` on event handlers only receives input/output VALUES, not DOM elements
+- Must use `document.querySelector()` instead of `element.querySelector()`
+- The async import() still blocked hydration
+
+**Source:** [GitHub Issue #6729](https://github.com/gradio-app/gradio/issues/6729) - `js` without `fn` only executes if `fn` is explicitly set to `None`
+
+---
+
+### 4. head= Parameter on gr.Blocks() (Gradio 5 Syntax)
+
+**What we did:** `gr.Blocks(head='<script>...</script>')`
+
+**Result:** FAILED
+
+**Why:** This is Gradio 5 syntax. In Gradio 6, `head=`, `js=`, `css=` moved from `gr.Blocks()` to `launch()`.
+
+**Source:** [Gradio 6 Migration Guide](https://www.gradio.app/main/guides/gradio-6-migration-guide)
+
+---
+
+### 5. head= Parameter on launch() with import()
+
+**What we did:** `demo.launch(head='<script type="module">await import(...)</script>')`
+
+**Result:** FAILED
+
+**Why:** Same problem as #2 - async import() still blocks hydration even when in `<head>`.
+
+**Additional Issue:** [GitHub Issue #10250](https://github.com/gradio-app/gradio/issues/10250) documents that JavaScript in `head` param has non-deterministic execution - "would sometimes execute only after extended waiting periods (5+ minutes), or occasionally not at all."
+
+---
+
+### 6. head_paths= Parameter
+
+**What we did:** Used `head_paths=['path/to/niivue-loader.html']`
+
+**Result:** FAILED
+
+**Why:** Multiple issues:
+- Files weren't served correctly without `gr.set_static_paths()`
+- [GitHub Issue #11649](https://github.com/gradio-app/gradio/issues/11649) - head= with file paths causes 404
+- Even when files served correctly, the async import() pattern still blocked hydration
+
+---
+
+### 7. Vendored NiiVue (Local File)
+
+**What we did:** Downloaded niivue.js (2.9MB) locally to bypass CDN/CSP issues
+
+**Result:** PARTIALLY WORKED (file served) but FAILED (still blocks hydration)
+
+**Why:** The file serving worked via `allowed_paths` and `gr.set_static_paths()`, but the async import() pattern still blocked Svelte hydration.
+
+**Secondary Issue:** Base64 payload risk - encoding DWI (~30MB) + ADC (~18MB) as base64 would create ~65MB payloads, risking browser memory issues and Gradio payload limits.
+
+---
+
+### 8. Head Script + MutationObserver Pattern
+
+**What we did:** Load NiiVue via `launch(head=...)` globally, then use MutationObserver to watch for DOM changes and trigger initialization
+
+**Result:** FAILED
+
+**Why:** The head script still uses `await import()` which blocks hydration. Even if NiiVue loads globally as `window.Niivue`, the async pattern during page load still freezes the UI.
+
+**What it should have done:** MutationObserver watches for `data-*` attribute changes on gr.HTML elements, then calls `initNiiVue()`. But the initial import never completes due to hydration blocking.
+
+---
+
+### 9. Custom Svelte Component (packages/niivueviewer/)
+
+**What we did:** Built a full Gradio custom component:
+- Svelte 5 frontend with NiiVue bundled via npm (`@niivue/niivue@0.65.0`)
+- Python backend component class
+- StatusTracker for loading states
+- Templates compiled via `gradio cc build`
+
+**Result:** FAILED - Froze entire UI
+
+**Issues encountered:**
+
+| Issue | Description | Fix Applied | Still Broken |
+|-------|-------------|-------------|--------------|
+| Missing `gradio` prop | StatusTracker requires `gradio.i18n` for translations | PR #31 added it | Yes |
+| Missing packages/ in Docker | Dockerfile didn't copy `packages/` directory | PR #30 added COPY | Yes |
+| style.css 404 | [Issue #7026](https://github.com/gradio-app/gradio/issues/7026) - causes loading hang | N/A | Yes |
+| CJS/ESM conflicts | [Issue #6087](https://github.com/gradio-app/gradio/issues/6087) - dev server stuck | N/A | Yes |
+| Templates undefined | [Issue #9879](https://github.com/gradio-app/gradio/issues/9879) | N/A | Yes |
+
+**Time spent:** ~1 day on this approach alone
+
+**Root cause unresolved:** Even after adding `gradio` prop and shipping templates, UI still completely frozen. The exact failure mode remains unknown.
+
+**Gradio team's stance on custom components:**
+- [Issue #12074](https://github.com/gradio-app/gradio/issues/12074) - Proposed `gr.Custom` class because custom components are "too complex"
+- Custom components have multiple fragile failure modes that make them riskier than simpler approaches
+
+---
+
+### 10. gradio-iframe Package
+
+**What we did:** Attempted to use `gradio-iframe` package to isolate NiiVue in an iframe
+
+**Result:** FAILED - Incompatible with Gradio 6
+
+**Why:** `gradio-iframe` version 0.0.10 (Jan 2024) is the latest. Installing it forces Gradio downgrade from 6.x to 4.x. Package is effectively abandoned.
+
+**Source:** [PyPI gradio-iframe](https://pypi.org/project/gradio-iframe/)
+
+---
+
+### 11. Inline iframe via gr.HTML (NOT TESTED)
+
+**What we planned:** Use `gr.HTML('<iframe src="..."></iframe>')` with standalone viewer HTML
+
+**Result:** PLANNED BUT NOT EXECUTED
+
+**Why we stopped:** After 2+ days of failures, we stopped here because:
+- No definitive evidence it works on HF Spaces
+- CSP may still block JavaScript in iframes
+- 50/50 chance of working - yet another gamble
+
+**This remains the only untested approach** that might theoretically work.
+
+---
+
+## Root Causes
+
+### 1. Gradio's innerHTML Security Model
+
+Gradio uses innerHTML to update component values. Browsers intentionally do not execute `<script>` tags inserted via innerHTML. This is a security feature, not a bug.
+
+**Implication:** Any approach that relies on Gradio updating HTML content cannot include executable JavaScript.
+
+### 2. Svelte Hydration Blocking
+
+Any async JavaScript execution during Gradio's component mounting phase can block Svelte hydration, causing the entire UI to freeze.
+
+**Specifically:** `<script type="module">` with `import()` statements - even deferred - can interfere with Svelte's initialization timing in unpredictable ways.
+
+### 3. HuggingFace Spaces CSP
+
+HF Spaces has Content Security Policy headers that block external CDN imports:
+- `script-src 'self' 'unsafe-inline' 'unsafe-eval'` (estimated)
+- External domains like unpkg.com are blocked
+- CSP headers are NOT customizable per HF documentation
+
+**Source:** [HF Spaces Config Reference](https://huggingface.co/docs/hub/spaces-config-reference)
+
+### 4. js_on_load Only Runs Once
+
+Gradio's `js_on_load` executes only when the component first mounts, not when the value updates. This breaks any approach that needs to reinitialize JavaScript after data changes.
+
+### 5. Module Script Timing Race Condition
+
+`<script type="module">` is deferred by default. It executes AFTER HTML parsing but the timing relative to Svelte component mounting is unpredictable. `window.Niivue` may be undefined when `js_on_load` tries to access it.
+
+### 6. Two Entry Points with Path Mismatch Risk
+
+Root `app.py` vs `src/.../ui/app.py` compute asset paths differently:
+- Root: `Path(__file__).parent / "src" / "..." / "assets"`
+- Module: `Path(__file__).parent / "assets"`
+
+Docker uses `python -m stroke_deepisles_demo.ui.app`, so only the module path matters, but this caused confusion during debugging.
+
+### 7. Gradio's Design Philosophy
+
+Gradio is designed for simple input/output ML demos, not complex WebGL applications with their own JavaScript lifecycle. The Gradio maintainers explicitly closed requests for WebGL/NIfTI support:
+
+| Issue | Request | Response |
+|-------|---------|----------|
+| [#4511](https://github.com/gradio-app/gradio/issues/4511) | NIfTI/3D medical image support | "Not planned" - told to build custom component |
+| [#7649](https://github.com/gradio-app/gradio/issues/7649) | WebGL Canvas component | "Not planned" - "too niche" |
+
+---
+
+## GitHub Issues Referenced
+
+### WebGL/3D Related
+
+| Issue | Description | Status |
+|-------|-------------|--------|
+| [#4511](https://github.com/gradio-app/gradio/issues/4511) | 3D medical image support | Closed - "use custom component" |
+| [#7649](https://github.com/gradio-app/gradio/issues/7649) | WebGL Canvas component | Closed - "too niche" |
+| [#5765](https://github.com/gradio-app/gradio/issues/5765) | Model3D rendered see-through | WebGL error |
+| [#7632](https://github.com/gradio-app/gradio/issues/7632) | Model3D collapsed in tabs | Open |
+| [#7485](https://github.com/gradio-app/gradio/issues/7485) | Model3D not working when embedded | Open |
+
+### Custom Component Related
+
+| Issue | Description | Impact |
+|-------|-------------|--------|
+| [#7026](https://github.com/gradio-app/gradio/issues/7026) | style.css 404 causes hang | Loading forever |
+| [#6087](https://github.com/gradio-app/gradio/issues/6087) | CJS imports break dev server | Dev stuck |
+| [#9879](https://github.com/gradio-app/gradio/issues/9879) | Templates undefined | Component fails |
+| [#12074](https://github.com/gradio-app/gradio/issues/12074) | Custom components too complex | Proposed gr.Custom |
+
+### JavaScript Loading Related
+
+| Issue | Description | Status |
+|-------|-------------|--------|
+| [#11649](https://github.com/gradio-app/gradio/issues/11649) | head= with files causes 404 | Closed - use head_paths |
+| [#10250](https://github.com/gradio-app/gradio/issues/10250) | head JS execution non-deterministic | Open |
+| [#6426](https://github.com/gradio-app/gradio/issues/6426) | head argument bugs | Fixed in PR #6639 |
+| [#6729](https://github.com/gradio-app/gradio/issues/6729) | js without fn requires explicit None | Closed |
+
+### HF Spaces SSE/Queue Related
+
+| Issue | Description | Impact |
+|-------|-------------|--------|
+| [#5974](https://github.com/gradio-app/gradio/issues/5974) | Stuck in processing with queue | Loading forever |
+| [#4279](https://github.com/gradio-app/gradio/issues/4279) | Stuck on Loading with new Gradio | Loading forever |
+| [#4332](https://github.com/gradio-app/gradio/issues/4332) | Loading stuck in non-internet env | SSE connection issues |
+
+---
+
+## What Actually Works on HF Spaces
+
+**Proof from 2025-12-11 HF Spaces test** (after removing custom component):
+
+| Component | Status |
+|-----------|--------|
+| Gradio UI | ✅ WORKS - App loads, no freeze |
+| Dropdown | ✅ WORKS - Case selector shows 149 cases |
+| Buttons | ✅ WORKS - "Run Segmentation" triggers pipeline |
+| DeepISLES Pipeline | ✅ WORKS - Runs in ~38 seconds |
+| Matplotlib Plots | ✅ WORKS - Static Report renders correctly |
+| Metrics JSON | ✅ WORKS - Displays dice_score, volume_ml |
+| File Downloads | ✅ WORKS - Prediction NIfTI downloadable |
+| NiiVue Viewer | ❌ BROKEN - Shows placeholder, script never executes |
+
+**This proves:** The custom Svelte component WAS the cause of the UI freeze. Everything else in the stack works perfectly.
+
+---
+
+## Reference Implementation
+
+The only working NiiVue + HF Spaces example:
+- [TobiasPitters/bids-neuroimaging](https://huggingface.co/spaces/TobiasPitters/bids-neuroimaging)
+- **Does NOT use Gradio** - uses FastAPI with raw HTML
+- Scripts execute because they're in the actual HTML document, not injected via innerHTML
+- Uses NiiVue 0.57.0
+
+---
+
+## Viable Paths Forward
+
+### Option 1: Remove NiiVue (IMPLEMENTED)
+
+Keep 2D Matplotlib visualizations only. This is what we shipped.
+
+**Pros:** Works reliably, no JavaScript complexity
+**Cons:** No 3D interactivity
+
+### Option 2: Abandon Gradio
+
+Rewrite with FastAPI + raw HTML, like the reference implementation.
+
+**Pros:** Full control over JavaScript execution
+**Cons:** Lose all Gradio benefits (state, components, themes, HF integration)
+
+### Option 3: Inline iframe (UNTESTED)
+
+Use `gr.HTML('<iframe src="..."></iframe>')` with standalone viewer HTML.
+
+**Pros:** Might work - iframes are isolated
+**Cons:** Untested, CSP may still block, communication is complex
+
+### Option 4: Wait for Gradio gr.Custom
+
+[Issue #12074](https://github.com/gradio-app/gradio/issues/12074) proposes simpler custom components.
+
+**Pros:** Might solve our issues
+**Cons:** No timeline, may never happen
+
+---
+
+## Lessons Learned
+
+1. **Gradio is not a general-purpose web framework** - It's designed for simple ML demos, not complex WebGL applications
+
+2. **JavaScript execution in Gradio is fundamentally broken** - innerHTML security model prevents script execution
+
+3. **js_on_load has severe limitations** - Only runs once, async IIFEs can block hydration, no access to `element` in .then(js=) handlers
+
+4. **"Workarounds" don't work** - js_on_load, head=, head_paths=, MutationObserver, custom components - all fail
+
+5. **Custom components are fragile** - Multiple failure modes (templates, i18n props, build artifacts) make them risky
+
+6. **Community packages may be abandoned** - gradio-iframe hasn't been updated for Gradio 6
+
+7. **Read the closed issues first** - Gradio maintainers already said "not planned" for WebGL
+
+8. **Use `data-*` attributes for state** - gr.HTML re-renders completely on update, so data attributes are the only reliable way to pass information to JavaScript
+
+9. **Two entry points = confusion** - Root app.py vs module app.py compute paths differently, causing debugging overhead
+
+10. **The only untested path is inline iframe** - If we ever revisit this, start there
+
+---
+
+## Final Status
+
+**NiiVue integration: ABANDONED**
+
+The app works on HF Spaces with 2D Matplotlib visualizations. The 3D NiiVue viewer is not possible with Gradio.
+
+If 3D visualization is required in the future:
+1. Try inline iframe approach first (untested)
+2. If that fails, Gradio must be replaced entirely with FastAPI + raw HTML
+
+---
+
+## Archive Note
+
+This postmortem consolidates all findings from the following archived specs:
+- `00-context.md` - Project context
+- `10-bug-niivue-viewer-black-screen.md` - Initial black screen investigation
+- `11-bug-niivue-js-on-load-not-rerunning.md` - js_on_load limitations
+- `19-perf-base64-to-file-urls.md` - Base64 payload optimization
+- `24-bug-hf-spaces-loading-forever.md` - CSP and hydration analysis
+- `24-bug-gradio-webgl-analysis.md` - WebGL analysis
+- `28-gradio-custom-component-niivue.md` - Custom component attempt
+- `29-codebase-status-audit.md` - Code audit
+- `30-bug-hf-spaces-build-packages-dir.md` - Docker build fix
+- `32-bug-hf-spaces-ui-frozen-audit.md` - UI freeze investigation
+- `33-definitive-niivue-gradio-integration.md` - Integration research
+- `34-COMPREHENSIVE-NIIVUE-GRADIO-AUDIT.md` - Final comprehensive audit
+- `35-FINAL-ATTEMPT-GRADIO-IFRAME.md` - gradio-iframe attempt (not executed)
+- `AUDIT_JS_LOADING_ISSUES.md` - JavaScript loading audit
+- `DIAGNOSTIC_HF_LOADING.md` - HF loading diagnostics
+- `ROOT_CAUSE_ANALYSIS.md` - Root cause analysis
+
+The archive can be deleted now that this postmortem is complete.

docs/specs/archive/01-phase-0-repo-bootstrap.md

@@ -1,438 +0,0 @@
-# phase 0: repo bootstrap
-
-## purpose
-
-Set up the foundational project structure with 2025 Python best practices. At the end of this phase, we have a working skeleton that can be installed, linted, type-checked, and tested (even if tests are empty).
-
-## deliverables
-
-- [ ] `pyproject.toml` with uv + hatchling backend
-- [ ] `src/stroke_deepisles_demo/` package structure
-- [ ] `tests/` directory with pytest configuration
-- [ ] Development tooling: ruff, mypy, pre-commit
-- [ ] Basic `README.md` with clinical disclaimer
-- [ ] `.gitignore` updates if needed
-
-## repo structure
-
-```
-stroke-deepisles-demo/
-├── pyproject.toml              # Project metadata, deps, tool config
-├── uv.lock                     # Locked dependencies (auto-generated)
-├── .python-version             # Python version (3.12)
-├── README.md                   # Project overview + disclaimer
-├── .gitignore                  # Standard Python ignores
-├── .pre-commit-config.yaml     # Pre-commit hooks
-│
-├── src/
-│   └── stroke_deepisles_demo/
-│       ├── __init__.py         # Package version, exports
-│       ├── py.typed            # PEP 561 marker
-│       │
-│       ├── core/               # Shared utilities
-│       │   ├── __init__.py
-│       │   ├── config.py       # Pydantic settings (stub)
-│       │   ├── types.py        # Shared type definitions (stub)
-│       │   └── exceptions.py   # Custom exceptions (stub)
-│       │
-│       ├── data/               # Data loading (stub)
-│       │   └── __init__.py
-│       │
-│       ├── inference/          # DeepISLES integration (stub)
-│       │   └── __init__.py
-│       │
-│       └── ui/                 # Gradio app (stub)
-│           └── __init__.py
-│
-├── tests/
-│   ├── __init__.py
-│   ├── conftest.py             # Shared fixtures
-│   └── test_package.py         # Smoke test: package imports
-│
-└── docs/
-    └── specs/                  # These spec documents
-        ├── 00-context.md
-        ├── 01-phase-0-repo-bootstrap.md
-        └── ...
-```
-
-## pyproject.toml specification
-
-```toml
-[project]
-name = "stroke-deepisles-demo"
-version = "0.1.0"
-description = "Demo: HF datasets + DeepISLES stroke segmentation + Gradio visualization"
-readme = "README.md"
-license = { text = "MIT" }
-requires-python = ">=3.11"
-authors = [
-    { name = "Your Name", email = "you@example.com" }
-]
-classifiers = [
-    "Development Status :: 3 - Alpha",
-    "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Topic :: Scientific/Engineering :: Medical Science Apps.",
-]
-keywords = ["stroke", "neuroimaging", "segmentation", "BIDS", "NIfTI", "deep-learning"]
-
-dependencies = [
-    # Core - pinned to Tobias's fork for BIDS + NIfTI lazy loading
-    "datasets @ git+https://github.com/CloseChoice/datasets.git@feat/bids-loader-streaming-upload-fix",
-    "huggingface-hub>=0.25.0",
-
-    # NIfTI handling
-    "nibabel>=5.2.0",
-    "numpy>=1.26.0",
-
-    # Configuration
-    "pydantic>=2.5.0",
-    "pydantic-settings>=2.1.0",
-
-    # UI (Gradio 5.x)
-    "gradio>=5.0.0",
-]
-
-[dependency-groups]
-dev = [
-    "pytest>=8.0.0",
-    "pytest-cov>=4.1.0",
-    "pytest-mock>=3.12.0",
-    "mypy>=1.8.0",
-    "ruff>=0.8.0",
-    "pre-commit>=3.6.0",
-    # Type stubs
-    "types-requests",
-]
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/stroke_deepisles_demo"]
-
-[tool.uv]
-dev-dependencies = [
-    "pytest>=8.0.0",
-    "pytest-cov>=4.1.0",
-    "pytest-mock>=3.12.0",
-    "mypy>=1.8.0",
-    "ruff>=0.8.0",
-    "pre-commit>=3.6.0",
-]
-
-# ─────────────────────────────────────────────────────────────────
-# Tool configurations
-# ─────────────────────────────────────────────────────────────────
-
-[tool.ruff]
-target-version = "py311"
-line-length = 100
-src = ["src", "tests"]
-
-[tool.ruff.lint]
-select = [
-    "E",      # pycodestyle errors
-    "W",      # pycodestyle warnings
-    "F",      # pyflakes
-    "I",      # isort
-    "B",      # flake8-bugbear
-    "C4",     # flake8-comprehensions
-    "UP",     # pyupgrade
-    "ARG",    # flake8-unused-arguments
-    "SIM",    # flake8-simplify
-    "TCH",    # flake8-type-checking
-    "PTH",    # flake8-use-pathlib
-    "RUF",    # ruff-specific
-]
-ignore = [
-    "E501",   # line too long (handled by formatter)
-]
-
-[tool.ruff.lint.isort]
-known-first-party = ["stroke_deepisles_demo"]
-
-[tool.mypy]
-python_version = "3.11"
-strict = true
-warn_return_any = true
-warn_unused_ignores = true
-disallow_untyped_defs = true
-plugins = ["pydantic.mypy"]
-
-[[tool.mypy.overrides]]
-module = [
-    "nibabel.*",
-    "gradio.*",
-    "datasets.*",
-    "niivue.*",
-]
-ignore_missing_imports = true
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-python_files = ["test_*.py"]
-python_functions = ["test_*"]
-addopts = [
-    "-v",
-    "--tb=short",
-    "--strict-markers",
-]
-markers = [
-    "integration: marks tests requiring external resources (Docker, network)",
-    "slow: marks tests that take >10s to run",
-]
-filterwarnings = [
-    "ignore::DeprecationWarning",
-]
-
-[tool.coverage.run]
-source = ["src/stroke_deepisles_demo"]
-branch = true
-
-[tool.coverage.report]
-exclude_lines = [
-    "pragma: no cover",
-    "if TYPE_CHECKING:",
-    "raise NotImplementedError",
-]
-```
-
-## module stubs
-
-### `src/stroke_deepisles_demo/__init__.py`
-
-```python
-"""stroke-deepisles-demo: HF datasets + DeepISLES + Gradio visualization."""
-
-__version__ = "0.1.0"
-
-__all__ = ["__version__"]
-```
-
-### `src/stroke_deepisles_demo/core/config.py`
-
-```python
-"""Application configuration using pydantic-settings."""
-
-from __future__ import annotations
-
-from pydantic_settings import BaseSettings
-
-
-class Settings(BaseSettings):
-    """Application settings loaded from environment variables."""
-
-    # HuggingFace
-    hf_dataset_id: str = "YongchengYAO/ISLES24-MR-Lite"
-    hf_cache_dir: str | None = None
-
-    # DeepISLES
-    deepisles_docker_image: str = "isleschallenge/deepisles"
-    deepisles_fast_mode: bool = True  # SEALS-only (ISLES'22 winner, no FLAIR needed)
-
-    # Paths
-    temp_dir: str | None = None
-
-    class Config:
-        env_prefix = "STROKE_DEMO_"
-        env_file = ".env"
-
-
-settings = Settings()
-```
-
-### `src/stroke_deepisles_demo/core/types.py`
-
-```python
-"""Shared type definitions."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import TypedDict
-
-
-class CaseFiles(TypedDict):
-    """Paths to NIfTI files for a single case."""
-
-    dwi: Path
-    adc: Path
-    flair: Path | None
-    ground_truth: Path | None
-
-
-@dataclass(frozen=True)
-class InferenceResult:
-    """Result of running DeepISLES on a case."""
-
-    case_id: str
-    input_files: CaseFiles
-    prediction_mask: Path
-    elapsed_seconds: float
-```
-
-### `src/stroke_deepisles_demo/core/exceptions.py`
-
-```python
-"""Custom exceptions for stroke-deepisles-demo."""
-
-from __future__ import annotations
-
-
-class StrokeDemoError(Exception):
-    """Base exception for stroke-deepisles-demo."""
-
-
-class DataLoadError(StrokeDemoError):
-    """Failed to load data from HuggingFace Hub."""
-
-
-class DockerNotAvailableError(StrokeDemoError):
-    """Docker is not installed or not running."""
-
-
-class DeepISLESError(StrokeDemoError):
-    """DeepISLES inference failed."""
-
-
-class MissingInputError(StrokeDemoError):
-    """Required input files are missing."""
-```
-
-## pre-commit configuration
-
-### `.pre-commit-config.yaml`
-
-```yaml
-repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.0
-    hooks:
-      - id: ruff
-        args: [--fix]
-      - id: ruff-format
-
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.8.0
-    hooks:
-      - id: mypy
-        additional_dependencies:
-          - pydantic>=2.5.0
-          - pydantic-settings>=2.1.0
-        args: [--config-file=pyproject.toml]
-
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
-    hooks:
-      - id: trailing-whitespace
-      - id: end-of-file-fixer
-      - id: check-yaml
-      - id: check-added-large-files
-        args: [--maxkb=1000]
-```
-
-## tdd plan
-
-### tests to write first
-
-1. **`tests/test_package.py`** - Smoke test that package imports work
-
-```python
-"""Smoke tests for package structure."""
-
-from __future__ import annotations
-
-
-def test_package_imports() -> None:
-    """Verify the package can be imported."""
-    import stroke_deepisles_demo
-
-    assert stroke_deepisles_demo.__version__ == "0.1.0"
-
-
-def test_core_modules_import() -> None:
-    """Verify core modules can be imported without side effects."""
-    from stroke_deepisles_demo.core import config, exceptions, types
-
-    assert config.settings is not None
-    assert types.CaseFiles is not None
-    assert exceptions.StrokeDemoError is not None
-
-
-def test_subpackages_exist() -> None:
-    """Verify subpackage structure exists."""
-    from stroke_deepisles_demo import data, inference, ui
-
-    # These are stubs, just verify they exist
-    assert data is not None
-    assert inference is not None
-    assert ui is not None
-```
-
-### what to mock
-
-- Nothing needed for Phase 0 - these are pure import tests
-
-### what to test for real
-
-- Package imports
-- Module structure
-- Type definitions load correctly
-- Pydantic settings initialize with defaults
-
-## "done" criteria
-
-Phase 0 is complete when:
-
-1. `uv sync` succeeds and creates virtual environment
-2. `uv run pytest` passes all smoke tests
-3. `uv run ruff check .` reports no errors
-4. `uv run ruff format --check .` reports no changes needed
-5. `uv run mypy src/` passes with no errors
-6. `uv run pre-commit run --all-files` passes
-7. Package can be imported: `uv run python -c "import stroke_deepisles_demo"`
-
-## commands cheatsheet
-
-```bash
-# Initialize (if starting fresh)
-uv init --package stroke-deepisles-demo
-
-# Install dependencies
-uv sync
-
-# Run tests
-uv run pytest
-
-# Run tests with coverage
-uv run pytest --cov
-
-# Lint
-uv run ruff check .
-
-# Format
-uv run ruff format .
-
-# Type check
-uv run mypy src/
-
-# Install pre-commit hooks
-uv run pre-commit install
-
-# Run all pre-commit hooks
-uv run pre-commit run --all-files
-```
-
-## notes
-
-- We use `hatchling` as the build backend (current uv default, stable)
-- `uv_build` is newer but `hatchling` is battle-tested
-- The `datasets` dependency is pinned to Tobias's fork via git URL
-- Gradio 5.x for latest features (SSR, improved components)
-- Python 3.11+ for modern typing features (`X | None` syntax)

docs/specs/archive/02-phase-1-data-access.md

@@ -1,415 +0,0 @@
-# phase 1: data access layer
-
-## purpose
-
-Implement a data loading layer that provides typed access to ISLES24 neuroimaging cases. This phase is split into sub-phases due to a critical discovery: the upstream dataset is not properly formatted for HuggingFace consumption.
-
-## critical discovery (2025-12-04)
-
-**`YongchengYAO/ISLES24-MR-Lite` is NOT a proper HuggingFace Dataset.**
-
-| What we expected | What actually exists |
-|------------------|---------------------|
-| `load_dataset()` returns Dataset with columns | `load_dataset()` FAILS with "no data" |
-| Columns: `dwi`, `adc`, `mask`, `participant_id` | No columns - just raw ZIP files |
-| Parquet/Arrow format | Three ZIP archives dumped on HF |
-
-**Evidence**: `data/discovery/isles24_schema_report.txt`
-
-This means the demo must be built in phases:
-1. **Phase 1A**: Local file loader (works NOW with extracted data)
-2. **Phase 1B**: Test Tobias's `Nifti()` feature on local files (proves loading works)
-3. **Phase 1C**: Upload properly to HuggingFace (future - proves production pipeline)
-4. **Phase 1D**: Consume via Tobias's fork (future - proves full round-trip)
-
----
-
-## phase 1a: local file loader (CURRENT PRIORITY)
-
-### data location
-
-```
-data/isles24/                       # Git-ignored
-├── Images-DWI/                     # 149 files
-│   └── sub-stroke{XXXX}_ses-02_dwi.nii.gz
-├── Images-ADC/                     # 149 files
-│   └── sub-stroke{XXXX}_ses-02_adc.nii.gz
-└── Masks/                          # 149 files
-    └── sub-stroke{XXXX}_ses-02_lesion-msk.nii.gz
-```
-
-### file naming convention (BIDS-like)
-
-| Component | Pattern | Example |
-|-----------|---------|---------|
-| Subject ID | `sub-stroke{XXXX}` | `sub-stroke0005` |
-| Session | `ses-02` | Always "02" in this dataset |
-| Modality | `dwi`, `adc`, `lesion-msk` | - |
-| Extension | `.nii.gz` | Compressed NIfTI |
-
-**Subject ID regex**: `sub-stroke(\d{4})_ses-02_.*\.nii\.gz`
-
-**Note**: Subject IDs have gaps (e.g., 0018 missing). Range is 0001-0189, total 149 cases.
-
-### deliverables
-
-- [ ] `src/stroke_deepisles_demo/data/loader.py` - Rewrite with local mode
-- [ ] `src/stroke_deepisles_demo/data/adapter.py` - Rewrite for file-based access
-- [ ] `src/stroke_deepisles_demo/data/staging.py` - Already correct, no changes
-- [ ] Unit tests with synthetic fixtures
-- [ ] Integration test with actual extracted data
-
-### interfaces
-
-#### `data/loader.py`
-
-```python
-"""Load ISLES24 data from local directory or HuggingFace Hub."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from stroke_deepisles_demo.data.adapter import LocalDataset
-
-
-@dataclass
-class DatasetInfo:
-    """Metadata about the dataset."""
-
-    source: str  # "local" or HF dataset ID
-    num_cases: int
-    modalities: list[str]
-    has_ground_truth: bool
-
-
-def load_isles_dataset(
-    source: str | Path = "data/isles24",
-    *,
-    local_mode: bool = True,  # Default to local for now
-) -> LocalDataset:
-    """
-    Load ISLES24 dataset.
-
-    Args:
-        source: Local directory path or HuggingFace dataset ID
-        local_mode: If True, treat source as local directory
-
-    Returns:
-        Dataset-like object providing case access
-
-    Raises:
-        DataLoadError: If data cannot be loaded
-    """
-    if local_mode or isinstance(source, Path):
-        return _load_from_local_directory(Path(source))
-    # Future: return _load_from_huggingface(source)
-    raise NotImplementedError("HuggingFace mode not yet implemented")
-
-
-def _load_from_local_directory(data_dir: Path) -> LocalDataset:
-    """
-    Load cases from extracted local files.
-
-    Expects structure:
-        data_dir/
-        ├── Images-DWI/sub-stroke{XXXX}_ses-02_dwi.nii.gz
-        ├── Images-ADC/sub-stroke{XXXX}_ses-02_adc.nii.gz
-        └── Masks/sub-stroke{XXXX}_ses-02_lesion-msk.nii.gz
-    """
-    ...
-```
-
-#### `data/adapter.py`
-
-```python
-"""Provide typed access to ISLES24 cases."""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Iterator
-
-from stroke_deepisles_demo.core.types import CaseFiles
-
-
-@dataclass
-class LocalDataset:
-    """File-based dataset for local ISLES24 data."""
-
-    data_dir: Path
-    cases: dict[str, CaseFiles]  # subject_id -> files
-
-    def __len__(self) -> int:
-        return len(self.cases)
-
-    def __iter__(self) -> Iterator[str]:
-        return iter(self.cases.keys())
-
-    def list_case_ids(self) -> list[str]:
-        """Return sorted list of subject IDs."""
-        return sorted(self.cases.keys())
-
-    def get_case(self, case_id: str | int) -> CaseFiles:
-        """Get files for a case by ID or index."""
-        if isinstance(case_id, int):
-            case_id = self.list_case_ids()[case_id]
-        return self.cases[case_id]
-
-
-# Subject ID extraction
-SUBJECT_PATTERN = re.compile(r"sub-(stroke\d{4})_ses-\d+_.*\.nii\.gz")
-
-
-def parse_subject_id(filename: str) -> str | None:
-    """Extract subject ID from BIDS filename."""
-    match = SUBJECT_PATTERN.match(filename)
-    return f"sub-{match.group(1)}" if match else None
-
-
-def build_local_dataset(data_dir: Path) -> LocalDataset:
-    """
-    Scan directory and build case mapping.
-
-    Matches DWI + ADC + Mask files by subject ID.
-    """
-    dwi_dir = data_dir / "Images-DWI"
-    adc_dir = data_dir / "Images-ADC"
-    mask_dir = data_dir / "Masks"
-
-    cases: dict[str, CaseFiles] = {}
-
-    # Scan DWI files to get subject IDs
-    for dwi_file in dwi_dir.glob("*.nii.gz"):
-        subject_id = parse_subject_id(dwi_file.name)
-        if not subject_id:
-            continue
-
-        # Find matching ADC and Mask
-        adc_file = adc_dir / dwi_file.name.replace("_dwi.", "_adc.")
-        mask_file = mask_dir / dwi_file.name.replace("_dwi.", "_lesion-msk.")
-
-        if not adc_file.exists():
-            continue  # Skip incomplete cases
-
-        cases[subject_id] = CaseFiles(
-            dwi=dwi_file,
-            adc=adc_file,
-            ground_truth=mask_file if mask_file.exists() else None,
-        )
-
-    return LocalDataset(data_dir=data_dir, cases=cases)
-```
-
-### synthetic fixture structure
-
-Unit tests MUST use fixtures that replicate the **exact** directory structure. Add to `tests/conftest.py`:
-
-```python
-@pytest.fixture
-def synthetic_isles_dir(temp_dir: Path) -> Path:
-    """
-    Create synthetic ISLES24-like directory structure.
-
-    Structure:
-        temp_dir/
-        ├── Images-DWI/
-        │   ├── sub-stroke0001_ses-02_dwi.nii.gz
-        │   └── sub-stroke0002_ses-02_dwi.nii.gz
-        ├── Images-ADC/
-        │   ├── sub-stroke0001_ses-02_adc.nii.gz
-        │   └── sub-stroke0002_ses-02_adc.nii.gz
-        └── Masks/
-            ├── sub-stroke0001_ses-02_lesion-msk.nii.gz
-            └── sub-stroke0002_ses-02_lesion-msk.nii.gz
-    """
-    dwi_dir = temp_dir / "Images-DWI"
-    adc_dir = temp_dir / "Images-ADC"
-    mask_dir = temp_dir / "Masks"
-
-    dwi_dir.mkdir()
-    adc_dir.mkdir()
-    mask_dir.mkdir()
-
-    for subject_num in [1, 2]:
-        subject_id = f"sub-stroke{subject_num:04d}"
-
-        # Create DWI
-        dwi_data = np.random.rand(10, 10, 5).astype(np.float32)
-        dwi_img = nib.Nifti1Image(dwi_data, affine=np.eye(4))
-        nib.save(dwi_img, dwi_dir / f"{subject_id}_ses-02_dwi.nii.gz")
-
-        # Create ADC
-        adc_data = np.random.rand(10, 10, 5).astype(np.float32) * 2000
-        adc_img = nib.Nifti1Image(adc_data, affine=np.eye(4))
-        nib.save(adc_img, adc_dir / f"{subject_id}_ses-02_adc.nii.gz")
-
-        # Create Mask
-        mask_data = (np.random.rand(10, 10, 5) > 0.9).astype(np.uint8)
-        mask_img = nib.Nifti1Image(mask_data, affine=np.eye(4))
-        nib.save(mask_img, mask_dir / f"{subject_id}_ses-02_lesion-msk.nii.gz")
-
-    return temp_dir
-```
-
-### tdd plan
-
-```python
-# tests/data/test_loader.py
-
-def test_load_from_local_returns_local_dataset(synthetic_isles_dir):
-    """Local mode returns LocalDataset."""
-    ...
-
-def test_load_from_local_finds_all_cases(synthetic_isles_dir):
-    """Finds all cases in synthetic structure."""
-    ...
-
-# tests/data/test_adapter.py
-
-def test_parse_subject_id_extracts_correctly():
-    """Extracts subject ID from BIDS filename."""
-    assert parse_subject_id("sub-stroke0005_ses-02_dwi.nii.gz") == "sub-stroke0005"
-
-def test_build_local_dataset_matches_files(synthetic_isles_dir):
-    """Matches DWI, ADC, Mask by subject ID."""
-    ...
-
-def test_get_case_returns_case_files(synthetic_isles_dir):
-    """get_case returns CaseFiles with correct paths."""
-    ...
-```
-
-### done criteria (phase 1a)
-
-- [ ] `uv run pytest tests/data/ -v` passes
-- [ ] Can load all 149 cases from `data/isles24/`
-- [ ] `list_case_ids()` returns 149 subject IDs
-- [ ] `get_case("sub-stroke0005")` returns valid CaseFiles
-- [ ] Type checking passes: `uv run mypy src/stroke_deepisles_demo/data/`
-
----
-
-## phase 1b: test tobias's nifti feature (NEXT)
-
-### purpose
-
-Verify that Tobias's `Nifti()` feature type from the datasets fork can correctly load/parse NIfTI files. This proves the **loading** part of the consumption pipeline works, even though the **download** part is broken.
-
-### approach
-
-```python
-# Test script to verify Nifti() feature works on local files
-from datasets import Features, Value
-from datasets.features import Nifti  # From Tobias's fork
-
-# Create a simple dataset from local files
-features = Features({
-    "subject_id": Value("string"),
-    "dwi": Nifti(),
-    "adc": Nifti(),
-    "mask": Nifti(),
-})
-
-# Load a single case and verify Nifti() decodes correctly
-```
-
-### done criteria (phase 1b)
-
-- [ ] Tobias's `Nifti()` feature loads local `.nii.gz` files
-- [ ] Decoded NIfTI has correct shape/dtype
-- [ ] Can access voxel data via nibabel-like interface
-
----
-
-## phase 1c: proper huggingface upload (FUTURE)
-
-### purpose
-
-Re-upload ISLES24 data to HuggingFace **properly** using the arc-aphasia-bids approach. This proves the **production** pipeline works.
-
-### approach
-
-1. Use BIDS loader from Tobias's fork
-2. Create proper parquet schema with columns:
-   - `subject`: string
-   - `session`: string
-   - `dwi`: Nifti()
-   - `adc`: Nifti()
-   - `mask`: Nifti()
-3. Upload to new HuggingFace repo (e.g., `The-Obstacle-Is-The-Way/ISLES24-BIDS`)
-
-### done criteria (phase 1c)
-
-- [ ] Dataset uploaded to HuggingFace with proper schema
-- [ ] HuggingFace dataset viewer shows data correctly
-- [ ] `load_dataset("new-repo-id")` returns Dataset with expected columns
-
----
-
-## phase 1d: consumption verification (FUTURE)
-
-### purpose
-
-Verify the full round-trip: Download from HuggingFace using Tobias's fork.
-
-### approach
-
-```python
-from datasets import load_dataset
-
-# This should work after Phase 1C
-ds = load_dataset("The-Obstacle-Is-The-Way/ISLES24-BIDS")
-case = ds["train"][0]
-print(case["dwi"].shape)  # Should work!
-```
-
-### new adapter function
-
-When Phase 1D is implemented, `adapter.py` will need a new function alongside `build_local_dataset`:
-
-```python
-def adapt_hf_case(hf_row: dict) -> CaseFiles:
-    """
-    Adapt a HuggingFace Dataset row to CaseFiles.
-
-    Args:
-        hf_row: Row from load_dataset() with columns:
-            - dwi: Nifti feature (nibabel-like object)
-            - adc: Nifti feature
-            - mask: Nifti feature
-            - subject: str
-
-    Returns:
-        CaseFiles with materialized paths or nibabel objects
-    """
-    # Implementation depends on how Nifti() feature exposes data
-    # May need to write to temp files or pass nibabel objects directly
-    ...
-```
-
-This maintains the same `CaseFiles` contract for downstream phases regardless of data source.
-
-### done criteria (phase 1d)
-
-- [ ] `load_dataset()` works on properly uploaded dataset
-- [ ] `adapt_hf_case()` function converts HF rows to CaseFiles
-- [ ] Full demo runs with HuggingFace consumption (not just local files)
-- [ ] Documents the pitfall for future projects
-
----
-
-## dependencies
-
-No new dependencies needed beyond Phase 0.
-
-## notes
-
-- The original `adapter.py` assumed HF Dataset with columns - COMPLETELY WRONG
-- The original `loader.py` called `load_dataset()` directly - FAILS on this dataset
-- `staging.py` is still correct - it just needs `CaseFiles` with paths

docs/specs/archive/03-phase-2-deepisles-docker.md

@@ -1,884 +0,0 @@
-# phase 2: deepisles docker integration
-
-## purpose
-
-Create a Python wrapper that calls the DeepISLES Docker image as a black box. At the end of this phase, we can run stroke lesion segmentation on a folder of NIfTI files and get back the predicted mask.
-
-## deliverables
-
-- [ ] `src/stroke_deepisles_demo/inference/docker.py` - Docker execution wrapper
-- [ ] `src/stroke_deepisles_demo/inference/deepisles.py` - DeepISLES-specific CLI interface
-- [ ] Unit tests with subprocess mocking
-- [ ] Integration test (marked, requires Docker)
-
-## vertical slice outcome
-
-After this phase, you can run:
-
-```python
-from stroke_deepisles_demo.inference import run_deepisles_on_folder
-
-# input_dir contains: dwi.nii.gz, adc.nii.gz
-result = run_deepisles_on_folder(
-    input_dir=Path("/path/to/staged/case"),
-    fast=True,
-)
-print(f"Prediction mask: {result.prediction_path}")
-print(f"Elapsed: {result.elapsed_seconds:.1f}s")
-```
-
-## module structure
-
-```
-src/stroke_deepisles_demo/inference/
-├── __init__.py          # Public API exports
-├── docker.py            # Generic Docker execution utilities
-└── deepisles.py         # DeepISLES-specific wrapper
-```
-
-## deepisles cli reference
-
-From the [DeepIsles repository](https://github.com/ezequieldlrosa/DeepIsles), the Docker interface expects:
-
-```bash
-docker run --rm \
-    -v /path/to/input:/input \
-    -v /path/to/output:/output \
-    --gpus all \
-    isleschallenge/deepisles \
-    --dwi_file_name dwi.nii.gz \
-    --adc_file_name adc.nii.gz \
-    [--flair_file_name flair.nii.gz] \
-    --fast True  # Single model mode, faster
-```
-
-**Expected input files:**
-- `dwi.nii.gz` (required) - Diffusion-weighted imaging
-- `adc.nii.gz` (required) - Apparent diffusion coefficient
-- `flair.nii.gz` (optional) - Required for full ensemble, not needed for fast mode
-
-**Output:**
-- `results/` directory containing the lesion mask
-
-### Why `--fast True` (SEALS-only mode)
-
-DeepISLES contains 3 models from the ISLES'22 challenge:
-
-| Model | Inputs | Notes |
-|-------|--------|-------|
-| **SEALS** (nnUNet) | DWI + ADC | 🏆 ISLES'22 Winner - runs with `--fast True` |
-| NVAUTO (MONAI) | DWI + ADC + FLAIR | Requires FLAIR |
-| SWAN (FACTORIZER) | DWI + ADC + FLAIR | Requires FLAIR |
-
-**We default to `fast=True` because:**
-1. ISLES24-MR-Lite only has DWI + ADC (no FLAIR)
-2. SEALS alone is the challenge-winning algorithm
-3. Running the full ensemble without FLAIR would fail for 2/3 models
-
-This is not a compromise—SEALS is state-of-the-art for DWI+ADC stroke segmentation.
-
-## interfaces and types
-
-### `inference/docker.py`
-
-```python
-"""Docker execution utilities."""
-
-from __future__ import annotations
-
-import subprocess
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Sequence
-
-from stroke_deepisles_demo.core.exceptions import DockerNotAvailableError
-
-
-@dataclass(frozen=True)
-class DockerRunResult:
-    """Result of a Docker container run."""
-
-    exit_code: int
-    stdout: str
-    stderr: str
-    elapsed_seconds: float
-
-
-def check_docker_available() -> bool:
-    """
-    Check if Docker is installed and the daemon is running.
-
-    Returns:
-        True if Docker is available, False otherwise
-    """
-    ...
-
-
-def ensure_docker_available() -> None:
-    """
-    Ensure Docker is available, raising if not.
-
-    Raises:
-        DockerNotAvailableError: If Docker is not installed or not running
-    """
-    ...
-
-
-def pull_image_if_missing(image: str, *, timeout: float = 600) -> bool:
-    """
-    Pull a Docker image if not present locally.
-
-    Args:
-        image: Docker image name (e.g., "isleschallenge/deepisles")
-        timeout: Maximum seconds to wait for pull
-
-    Returns:
-        True if image was pulled, False if already present
-    """
-    ...
-
-
-def run_container(
-    image: str,
-    *,
-    command: Sequence[str] | None = None,
-    volumes: dict[Path, str] | None = None,  # host_path -> container_path
-    environment: dict[str, str] | None = None,
-    gpu: bool = False,
-    remove: bool = True,
-    timeout: float | None = None,
-) -> DockerRunResult:
-    """
-    Run a Docker container and wait for completion.
-
-    Args:
-        image: Docker image name
-        command: Command to run in container
-        volumes: Volume mounts (host path -> container path)
-        environment: Environment variables
-        gpu: If True, pass --gpus all
-        remove: If True, remove container after exit (--rm)
-        timeout: Maximum seconds to wait (None = no timeout)
-
-    Returns:
-        DockerRunResult with exit code, stdout, stderr, elapsed time
-
-    Raises:
-        DockerNotAvailableError: If Docker is not available
-        subprocess.TimeoutExpired: If timeout exceeded
-    """
-    ...
-
-
-def build_docker_command(
-    image: str,
-    *,
-    command: Sequence[str] | None = None,
-    volumes: dict[Path, str] | None = None,
-    environment: dict[str, str] | None = None,
-    gpu: bool = False,
-    remove: bool = True,
-) -> list[str]:
-    """
-    Build the docker run command without executing.
-
-    Useful for logging/debugging.
-
-    Returns:
-        List of command arguments for subprocess
-    """
-    ...
-```
-
-### `inference/deepisles.py`
-
-```python
-"""DeepISLES stroke segmentation wrapper."""
-
-from __future__ import annotations
-
-import time
-from dataclasses import dataclass
-from pathlib import Path
-
-from stroke_deepisles_demo.core.config import settings
-from stroke_deepisles_demo.core.exceptions import DeepISLESError, MissingInputError
-from stroke_deepisles_demo.inference.docker import (
-    DockerRunResult,
-    ensure_docker_available,
-    run_container,
-)
-
-
-@dataclass(frozen=True)
-class DeepISLESResult:
-    """Result of DeepISLES inference."""
-
-    prediction_path: Path
-    docker_result: DockerRunResult
-    elapsed_seconds: float
-
-
-def validate_input_folder(input_dir: Path) -> tuple[Path, Path, Path | None]:
-    """
-    Validate that input folder contains required files.
-
-    Args:
-        input_dir: Directory to validate
-
-    Returns:
-        Tuple of (dwi_path, adc_path, flair_path_or_none)
-
-    Raises:
-        MissingInputError: If required files are missing
-    """
-    ...
-
-
-def run_deepisles_on_folder(
-    input_dir: Path,
-    *,
-    output_dir: Path | None = None,
-    fast: bool = True,
-    gpu: bool = True,
-    timeout: float | None = 1800,  # 30 minutes default
-) -> DeepISLESResult:
-    """
-    Run DeepISLES stroke segmentation on a folder of NIfTI files.
-
-    Args:
-        input_dir: Directory containing dwi.nii.gz, adc.nii.gz, [flair.nii.gz]
-        output_dir: Where to write results (default: input_dir/results)
-        fast: If True, use single-model mode (faster, slightly less accurate)
-        gpu: If True, use GPU acceleration
-        timeout: Maximum seconds to wait for inference
-
-    Returns:
-        DeepISLESResult with path to prediction mask
-
-    Raises:
-        DockerNotAvailableError: If Docker is not available
-        MissingInputError: If required input files are missing
-        DeepISLESError: If inference fails (non-zero exit, missing output)
-
-    Example:
-        >>> result = run_deepisles_on_folder(Path("/data/case001"), fast=True)
-        >>> print(result.prediction_path)
-        /data/case001/results/prediction.nii.gz
-    """
-    ...
-
-
-def find_prediction_mask(output_dir: Path) -> Path:
-    """
-    Find the prediction mask in DeepISLES output directory.
-
-    DeepISLES outputs may have varying names depending on version.
-    This function finds the most likely prediction file.
-
-    Args:
-        output_dir: DeepISLES output directory
-
-    Returns:
-        Path to the prediction mask NIfTI file
-
-    Raises:
-        DeepISLESError: If no prediction mask found
-    """
-    ...
-
-
-# Constants
-DEEPISLES_IMAGE = "isleschallenge/deepisles"
-EXPECTED_INPUT_FILES = ["dwi.nii.gz", "adc.nii.gz"]
-OPTIONAL_INPUT_FILES = ["flair.nii.gz"]
-```
-
-### `inference/__init__.py` (public API)
-
-```python
-"""Inference module for stroke-deepisles-demo."""
-
-from stroke_deepisles_demo.inference.deepisles import (
-    DEEPISLES_IMAGE,
-    DeepISLESResult,
-    run_deepisles_on_folder,
-    validate_input_folder,
-)
-from stroke_deepisles_demo.inference.docker import (
-    DockerRunResult,
-    build_docker_command,
-    check_docker_available,
-    ensure_docker_available,
-    run_container,
-)
-
-__all__ = [
-    # DeepISLES
-    "run_deepisles_on_folder",
-    "validate_input_folder",
-    "DeepISLESResult",
-    "DEEPISLES_IMAGE",
-    # Docker utilities
-    "check_docker_available",
-    "ensure_docker_available",
-    "run_container",
-    "build_docker_command",
-    "DockerRunResult",
-]
-```
-
-## tdd plan
-
-### test file structure
-
-```
-tests/
-├── inference/
-│   ├── __init__.py
-│   ├── test_docker.py       # Tests for Docker utilities
-│   └── test_deepisles.py    # Tests for DeepISLES wrapper
-```
-
-### tests to write first (TDD order)
-
-#### 1. `tests/inference/test_docker.py`
-
-```python
-"""Tests for Docker utilities."""
-
-from __future__ import annotations
-
-import subprocess
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from stroke_deepisles_demo.core.exceptions import DockerNotAvailableError
-from stroke_deepisles_demo.inference.docker import (
-    build_docker_command,
-    check_docker_available,
-    ensure_docker_available,
-    run_container,
-)
-
-
-class TestCheckDockerAvailable:
-    """Tests for check_docker_available."""
-
-    def test_returns_true_when_docker_responds(self) -> None:
-        """Returns True when 'docker info' succeeds."""
-        with patch("subprocess.run") as mock_run:
-            mock_run.return_value = MagicMock(returncode=0)
-
-            result = check_docker_available()
-
-            assert result is True
-
-    def test_returns_false_when_docker_not_found(self) -> None:
-        """Returns False when docker command not found."""
-        with patch("subprocess.run") as mock_run:
-            mock_run.side_effect = FileNotFoundError()
-
-            result = check_docker_available()
-
-            assert result is False
-
-    def test_returns_false_when_daemon_not_running(self) -> None:
-        """Returns False when docker daemon not running."""
-        with patch("subprocess.run") as mock_run:
-            mock_run.return_value = MagicMock(returncode=1)
-
-            result = check_docker_available()
-
-            assert result is False
-
-
-class TestEnsureDockerAvailable:
-    """Tests for ensure_docker_available."""
-
-    def test_raises_when_docker_not_available(self) -> None:
-        """Raises DockerNotAvailableError when Docker not available."""
-        with patch(
-            "stroke_deepisles_demo.inference.docker.check_docker_available",
-            return_value=False,
-        ):
-            with pytest.raises(DockerNotAvailableError):
-                ensure_docker_available()
-
-    def test_no_error_when_docker_available(self) -> None:
-        """No exception when Docker is available."""
-        with patch(
-            "stroke_deepisles_demo.inference.docker.check_docker_available",
-            return_value=True,
-        ):
-            ensure_docker_available()  # Should not raise
-
-
-class TestBuildDockerCommand:
-    """Tests for build_docker_command."""
-
-    def test_basic_command(self) -> None:
-        """Builds basic docker run command."""
-        cmd = build_docker_command("myimage:latest")
-
-        assert cmd[0] == "docker"
-        assert "run" in cmd
-        assert "myimage:latest" in cmd
-
-    def test_includes_rm_flag(self) -> None:
-        """Includes --rm when remove=True."""
-        cmd = build_docker_command("myimage", remove=True)
-
-        assert "--rm" in cmd
-
-    def test_excludes_rm_flag(self) -> None:
-        """Excludes --rm when remove=False."""
-        cmd = build_docker_command("myimage", remove=False)
-
-        assert "--rm" not in cmd
-
-    def test_includes_gpu_flag(self) -> None:
-        """Includes --gpus all when gpu=True."""
-        cmd = build_docker_command("myimage", gpu=True)
-
-        assert "--gpus" in cmd
-        gpu_index = cmd.index("--gpus")
-        assert cmd[gpu_index + 1] == "all"
-
-    def test_volume_mounts(self, temp_dir: Path) -> None:
-        """Includes volume mounts."""
-        volumes = {temp_dir: "/data"}
-        cmd = build_docker_command("myimage", volumes=volumes)
-
-        assert "-v" in cmd
-        # Find the volume argument
-        v_index = cmd.index("-v")
-        assert f"{temp_dir}:/data" in cmd[v_index + 1]
-
-    def test_custom_command(self) -> None:
-        """Appends custom command arguments."""
-        cmd = build_docker_command(
-            "myimage", command=["--input", "/data", "--fast", "True"]
-        )
-
-        assert "--input" in cmd
-        assert "--fast" in cmd
-
-
-class TestRunContainer:
-    """Tests for run_container."""
-
-    def test_calls_subprocess_with_built_command(self) -> None:
-        """Calls subprocess.run with built command."""
-        with patch("subprocess.run") as mock_run:
-            mock_run.return_value = MagicMock(
-                returncode=0, stdout="output", stderr=""
-            )
-            with patch(
-                "stroke_deepisles_demo.inference.docker.ensure_docker_available"
-            ):
-                run_container("myimage")
-
-            mock_run.assert_called_once()
-
-    def test_returns_result_with_exit_code(self) -> None:
-        """Returns DockerRunResult with correct exit code."""
-        with patch("subprocess.run") as mock_run:
-            mock_run.return_value = MagicMock(
-                returncode=42, stdout="out", stderr="err"
-            )
-            with patch(
-                "stroke_deepisles_demo.inference.docker.ensure_docker_available"
-            ):
-                result = run_container("myimage")
-
-            assert result.exit_code == 42
-
-    def test_captures_stdout_stderr(self) -> None:
-        """Captures stdout and stderr from container."""
-        with patch("subprocess.run") as mock_run:
-            mock_run.return_value = MagicMock(
-                returncode=0, stdout="hello", stderr="warning"
-            )
-            with patch(
-                "stroke_deepisles_demo.inference.docker.ensure_docker_available"
-            ):
-                result = run_container("myimage")
-
-            assert result.stdout == "hello"
-            assert result.stderr == "warning"
-
-    def test_respects_timeout(self) -> None:
-        """Passes timeout to subprocess."""
-        with patch("subprocess.run") as mock_run:
-            mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
-            with patch(
-                "stroke_deepisles_demo.inference.docker.ensure_docker_available"
-            ):
-                run_container("myimage", timeout=60.0)
-
-            call_kwargs = mock_run.call_args.kwargs
-            assert call_kwargs.get("timeout") == 60.0
-
-
-@pytest.mark.integration
-class TestDockerIntegration:
-    """Integration tests requiring real Docker."""
-
-    def test_docker_actually_available(self) -> None:
-        """Docker is actually available on this system."""
-        # This test only runs with -m integration
-        assert check_docker_available() is True
-
-    def test_can_run_hello_world(self) -> None:
-        """Can run docker hello-world container."""
-        result = run_container("hello-world", timeout=60.0)
-
-        assert result.exit_code == 0
-        assert "Hello from Docker!" in result.stdout
-```
-
-#### 2. `tests/inference/test_deepisles.py`
-
-```python
-"""Tests for DeepISLES wrapper."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from stroke_deepisles_demo.core.exceptions import DeepISLESError, MissingInputError
-from stroke_deepisles_demo.inference.deepisles import (
-    DeepISLESResult,
-    find_prediction_mask,
-    run_deepisles_on_folder,
-    validate_input_folder,
-)
-
-
-class TestValidateInputFolder:
-    """Tests for validate_input_folder."""
-
-    def test_succeeds_with_required_files(self, temp_dir: Path) -> None:
-        """Returns paths when required files exist."""
-        (temp_dir / "dwi.nii.gz").touch()
-        (temp_dir / "adc.nii.gz").touch()
-
-        dwi, adc, flair = validate_input_folder(temp_dir)
-
-        assert dwi == temp_dir / "dwi.nii.gz"
-        assert adc == temp_dir / "adc.nii.gz"
-        assert flair is None
-
-    def test_includes_flair_when_present(self, temp_dir: Path) -> None:
-        """Returns FLAIR path when present."""
-        (temp_dir / "dwi.nii.gz").touch()
-        (temp_dir / "adc.nii.gz").touch()
-        (temp_dir / "flair.nii.gz").touch()
-
-        dwi, adc, flair = validate_input_folder(temp_dir)
-
-        assert flair == temp_dir / "flair.nii.gz"
-
-    def test_raises_when_dwi_missing(self, temp_dir: Path) -> None:
-        """Raises MissingInputError when DWI is missing."""
-        (temp_dir / "adc.nii.gz").touch()
-
-        with pytest.raises(MissingInputError, match="dwi"):
-            validate_input_folder(temp_dir)
-
-    def test_raises_when_adc_missing(self, temp_dir: Path) -> None:
-        """Raises MissingInputError when ADC is missing."""
-        (temp_dir / "dwi.nii.gz").touch()
-
-        with pytest.raises(MissingInputError, match="adc"):
-            validate_input_folder(temp_dir)
-
-
-class TestFindPredictionMask:
-    """Tests for find_prediction_mask."""
-
-    def test_finds_prediction_file(self, temp_dir: Path) -> None:
-        """Finds prediction.nii.gz in output directory."""
-        results_dir = temp_dir / "results"
-        results_dir.mkdir()
-        pred_file = results_dir / "prediction.nii.gz"
-        pred_file.touch()
-
-        result = find_prediction_mask(temp_dir)
-
-        assert result == pred_file
-
-    def test_raises_when_no_prediction(self, temp_dir: Path) -> None:
-        """Raises DeepISLESError when no prediction found."""
-        results_dir = temp_dir / "results"
-        results_dir.mkdir()
-
-        with pytest.raises(DeepISLESError, match="prediction"):
-            find_prediction_mask(temp_dir)
-
-
-class TestRunDeepIslesOnFolder:
-    """Tests for run_deepisles_on_folder."""
-
-    @pytest.fixture
-    def valid_input_dir(self, temp_dir: Path) -> Path:
-        """Create a valid input directory with required files."""
-        (temp_dir / "dwi.nii.gz").touch()
-        (temp_dir / "adc.nii.gz").touch()
-        return temp_dir
-
-    def test_validates_input_files(self, temp_dir: Path) -> None:
-        """Validates input files before running Docker."""
-        # Missing required files
-        with pytest.raises(MissingInputError):
-            run_deepisles_on_folder(temp_dir)
-
-    def test_calls_docker_with_correct_image(self, valid_input_dir: Path) -> None:
-        """Calls Docker with DeepISLES image."""
-        with patch(
-            "stroke_deepisles_demo.inference.deepisles.run_container"
-        ) as mock_run:
-            mock_run.return_value = MagicMock(exit_code=0, stdout="", stderr="")
-            # Also mock finding the prediction
-            with patch(
-                "stroke_deepisles_demo.inference.deepisles.find_prediction_mask"
-            ) as mock_find:
-                mock_find.return_value = valid_input_dir / "results" / "pred.nii.gz"
-
-                run_deepisles_on_folder(valid_input_dir)
-
-            # Check image name
-            call_args = mock_run.call_args
-            assert "isleschallenge/deepisles" in str(call_args)
-
-    def test_passes_fast_flag(self, valid_input_dir: Path) -> None:
-        """Passes --fast True when fast=True."""
-        with patch(
-            "stroke_deepisles_demo.inference.deepisles.run_container"
-        ) as mock_run:
-            mock_run.return_value = MagicMock(exit_code=0, stdout="", stderr="")
-            with patch(
-                "stroke_deepisles_demo.inference.deepisles.find_prediction_mask"
-            ) as mock_find:
-                mock_find.return_value = valid_input_dir / "results" / "pred.nii.gz"
-
-                run_deepisles_on_folder(valid_input_dir, fast=True)
-
-            # Check --fast in command
-            call_kwargs = mock_run.call_args.kwargs
-            command = call_kwargs.get("command", [])
-            assert "--fast" in command
-
-    def test_raises_on_docker_failure(self, valid_input_dir: Path) -> None:
-        """Raises DeepISLESError when Docker returns non-zero."""
-        with patch(
-            "stroke_deepisles_demo.inference.deepisles.run_container"
-        ) as mock_run:
-            mock_run.return_value = MagicMock(
-                exit_code=1, stdout="", stderr="Segmentation fault"
-            )
-
-            with pytest.raises(DeepISLESError, match="failed"):
-                run_deepisles_on_folder(valid_input_dir)
-
-    def test_returns_result_with_prediction_path(self, valid_input_dir: Path) -> None:
-        """Returns DeepISLESResult with prediction path."""
-        with patch(
-            "stroke_deepisles_demo.inference.deepisles.run_container"
-        ) as mock_run:
-            mock_run.return_value = MagicMock(exit_code=0, stdout="", stderr="")
-            with patch(
-                "stroke_deepisles_demo.inference.deepisles.find_prediction_mask"
-            ) as mock_find:
-                expected_path = valid_input_dir / "results" / "prediction.nii.gz"
-                mock_find.return_value = expected_path
-
-                result = run_deepisles_on_folder(valid_input_dir)
-
-            assert isinstance(result, DeepISLESResult)
-            assert result.prediction_path == expected_path
-
-
-@pytest.mark.integration
-@pytest.mark.slow
-class TestDeepIslesIntegration:
-    """Integration tests requiring real Docker and DeepISLES image."""
-
-    def test_real_inference(self, synthetic_case_files) -> None:
-        """Run actual DeepISLES inference on synthetic data."""
-        # This test requires:
-        # 1. Docker available
-        # 2. isleschallenge/deepisles image pulled
-        # 3. GPU (optional but recommended)
-        #
-        # Run with: pytest -m "integration and slow"
-
-        from stroke_deepisles_demo.data.staging import stage_case_for_deepisles
-
-        # Stage the synthetic files
-        staged = stage_case_for_deepisles(
-            synthetic_case_files,
-            Path("/tmp/deepisles_test"),
-        )
-
-        # Run inference
-        result = run_deepisles_on_folder(
-            staged.input_dir,
-            fast=True,
-            gpu=False,  # Might not have GPU in CI
-            timeout=600,
-        )
-
-        # Verify output exists
-        assert result.prediction_path.exists()
-```
-
-### what to mock
-
-- `subprocess.run` - Mock for all unit tests
-- `check_docker_available` - Mock to control Docker availability
-- `run_container` - Mock in DeepISLES tests to avoid Docker
-- File system for prediction finding - Use temp directories
-
-### what to test for real
-
-- Command building (no subprocess needed)
-- Input validation (real file system with temp dirs)
-- Integration test: actual Docker hello-world
-- Integration test: actual DeepISLES inference (marked `slow`)
-
-## "done" criteria
-
-Phase 2 is complete when:
-
-1. All unit tests pass: `uv run pytest tests/inference/ -v`
-2. Can build Docker commands correctly
-3. Can validate input folders
-4. Unit tests don't require Docker (all mocked)
-5. Integration test passes with Docker: `uv run pytest -m integration tests/inference/`
-6. Type checking passes: `uv run mypy src/stroke_deepisles_demo/inference/`
-7. Code coverage for inference module > 80%
-
-## implementation notes
-
-- Check DeepISLES repo for exact output file names/structure
-- Consider `--gpus all` vs `--gpus '"device=0"'` for GPU selection
-- Timeout should be generous (30+ minutes) for full ensemble mode
-- Log Docker stdout/stderr for debugging
-- Consider streaming Docker output for long-running inference
-
-### critical: docker file permissions (linux)
-
-**Reviewer feedback (valid)**: Docker containers run as root by default on Linux. Output files written to mounted volumes will be owned by root:root. The Python process running as a normal user will fail to read or delete these files.
-
-**Solution**: Pass `--user` flag to match host user:
-
-```python
-def build_docker_command(
-    image: str,
-    *,
-    volumes: dict[Path, str] | None = None,
-    gpu: bool = False,
-    remove: bool = True,
-    match_user: bool = True,  # NEW: default True on Linux
-) -> list[str]:
-    """Build docker run command."""
-    cmd = ["docker", "run"]
-
-    if remove:
-        cmd.append("--rm")
-
-    if gpu:
-        cmd.extend(["--gpus", "all"])
-
-    # Match host user to avoid permission issues
-    if match_user and sys.platform != "darwin":  # Not needed on macOS
-        import os
-        uid = os.getuid()
-        gid = os.getgid()
-        cmd.extend(["--user", f"{uid}:{gid}"])
-
-    if volumes:
-        for host_path, container_path in volumes.items():
-            cmd.extend(["-v", f"{host_path}:{container_path}"])
-
-    cmd.append(image)
-    return cmd
-```
-
-### critical: gpu availability check
-
-**Reviewer feedback (valid)**: We check for Docker daemon but not NVIDIA Container Runtime. A user might have Docker but lack GPU passthrough setup.
-
-**Solution**: Add GPU-specific availability check:
-
-```python
-def check_nvidia_docker_available() -> bool:
-    """
-    Check if NVIDIA Container Runtime is available for GPU support.
-
-    Returns:
-        True if nvidia-docker/nvidia-container-toolkit is configured
-    """
-    try:
-        result = subprocess.run(
-            ["docker", "run", "--rm", "--gpus", "all", "nvidia/cuda:11.0-base", "nvidia-smi"],
-            capture_output=True,
-            timeout=30,
-        )
-        return result.returncode == 0
-    except (subprocess.TimeoutExpired, FileNotFoundError):
-        return False
-
-
-def ensure_gpu_available_if_requested(gpu: bool) -> None:
-    """
-    Verify GPU is available if requested, or warn user.
-
-    Raises:
-        DockerGPUNotAvailableError: If GPU requested but not available
-    """
-    if gpu and not check_nvidia_docker_available():
-        raise DockerGPUNotAvailableError(
-            "GPU requested but NVIDIA Container Runtime not available. "
-            "Either install nvidia-container-toolkit or set gpu=False."
-        )
-```
-
-Add to exceptions:
-
-```python
-class DockerGPUNotAvailableError(StrokeDemoError):
-    """GPU requested but NVIDIA Container Runtime not available."""
-```
-
-### nifti orientation (medium risk)
-
-**Reviewer feedback (noted)**: DeepISLES may expect specific anatomical orientation (e.g., RAS). BIDS data might be in different orientations.
-
-**Mitigation**: DeepISLES is trained on ISLES challenge data which follows standard conventions. If issues arise, add orientation checking in staging:
-
-```python
-def check_nifti_orientation(nifti_path: Path) -> str:
-    """Check NIfTI orientation code (e.g., 'RAS', 'LPS')."""
-    import nibabel as nib
-    img = nib.load(nifti_path)
-    return nib.aff2axcodes(img.affine)
-
-def conform_to_ras(nifti_path: Path, output_path: Path) -> Path:
-    """Reorient NIfTI to RAS if needed."""
-    import nibabel as nib
-    img = nib.load(nifti_path)
-    # nibabel can reorient - implement if needed
-    ...
-```
-
-## dependencies to add
-
-None - all covered in Phase 0.

docs/specs/archive/04-phase-3-pipeline.md

@@ -1,705 +0,0 @@
-# phase 3: end-to-end pipeline (no ui)
-
-## purpose
-
-Tie together Phase 1 (data loading) and Phase 2 (DeepISLES inference) into a cohesive pipeline. At the end of this phase, we can run stroke segmentation on any case from ISLES24-MR-Lite with a single function call.
-
-## deliverables
-
-- [ ] `src/stroke_deepisles_demo/pipeline.py` - Main orchestration
-- [ ] `src/stroke_deepisles_demo/metrics.py` - Optional Dice computation
-- [ ] CLI entry point for testing
-- [ ] Unit tests with full mocking
-- [ ] Integration test for complete flow
-
-## vertical slice outcome
-
-After this phase, you can run:
-
-```python
-from stroke_deepisles_demo.pipeline import run_pipeline_on_case
-
-# Run segmentation on a specific case
-result = run_pipeline_on_case("sub-001")
-
-print(f"Input DWI: {result.input_files.dwi}")
-print(f"Input ADC: {result.input_files.adc}")
-print(f"Prediction: {result.prediction_mask}")
-print(f"Ground truth: {result.ground_truth}")
-print(f"Dice score: {result.dice_score:.3f}")  # if computed
-```
-
-Or via CLI:
-
-```bash
-uv run stroke-demo run --case sub-001 --fast
-uv run stroke-demo run --index 0 --output ./results
-uv run stroke-demo list  # List all available cases
-```
-
-## module structure
-
-```
-src/stroke_deepisles_demo/
-├── pipeline.py          # Main orchestration
-├── metrics.py           # Dice score computation
-└── cli.py               # CLI entry point (optional)
-```
-
-## interfaces and types
-
-### `pipeline.py`
-
-```python
-"""End-to-end pipeline orchestration."""
-
-from __future__ import annotations
-
-import tempfile
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Mapping
-
-from stroke_deepisles_demo.core.config import settings
-from stroke_deepisles_demo.core.types import CaseFiles, InferenceResult
-from stroke_deepisles_demo.data import CaseAdapter, load_isles_dataset, stage_case_for_deepisles
-from stroke_deepisles_demo.inference import run_deepisles_on_folder
-
-
-@dataclass(frozen=True)
-class PipelineResult:
-    """Complete result of running the pipeline on a case."""
-
-    case_id: str
-    input_files: CaseFiles
-    staged_dir: Path
-    prediction_mask: Path
-    ground_truth: Path | None
-    dice_score: float | None  # None if ground truth unavailable or not computed
-    elapsed_seconds: float
-
-
-def run_pipeline_on_case(
-    case_id: str | int,
-    *,
-    dataset_id: str | None = None,
-    output_dir: Path | None = None,
-    fast: bool = True,
-    gpu: bool = True,
-    compute_dice: bool = True,
-    cleanup_staging: bool = False,
-) -> PipelineResult:
-    """
-    Run the complete segmentation pipeline on a single case.
-
-    This function:
-    1. Loads the case from HuggingFace Hub (or cache)
-    2. Stages NIfTI files with DeepISLES-expected naming
-    3. Runs DeepISLES Docker container
-    4. Optionally computes Dice score against ground truth
-    5. Returns all paths and metrics
-
-    Args:
-        case_id: Case identifier (string) or index (int)
-        dataset_id: HF dataset ID (default from settings)
-        output_dir: Directory for results (default: temp dir)
-        fast: Use SEALS-only mode (ISLES'22 winner, DWI+ADC only, no FLAIR needed)
-        gpu: Use GPU acceleration
-        compute_dice: Compute Dice score if ground truth available
-        cleanup_staging: Remove staging directory after inference
-
-    Returns:
-        PipelineResult with all paths and optional metrics
-
-    Raises:
-        DataLoadError: If case cannot be loaded
-        MissingInputError: If required files missing
-        DeepISLESError: If inference fails
-
-    Example:
-        >>> result = run_pipeline_on_case("sub-001", fast=True)
-        >>> print(f"Dice: {result.dice_score:.3f}")
-    """
-    ...
-
-
-def run_pipeline_on_batch(
-    case_ids: list[str | int],
-    *,
-    max_workers: int = 1,
-    **kwargs,
-) -> list[PipelineResult]:
-    """
-    Run pipeline on multiple cases.
-
-    Note: Parallel execution requires multiple GPUs or sequential mode.
-
-    Args:
-        case_ids: List of case identifiers or indices
-        max_workers: Number of parallel workers (default 1 for sequential)
-        **kwargs: Passed to run_pipeline_on_case
-
-    Returns:
-        List of PipelineResult, one per case
-    """
-    ...
-
-
-def get_pipeline_summary(results: list[PipelineResult]) -> PipelineSummary:
-    """
-    Compute summary statistics from multiple pipeline results.
-
-    Returns:
-        Summary with mean Dice, success rate, etc.
-    """
-    ...
-
-
-@dataclass(frozen=True)
-class PipelineSummary:
-    """Summary statistics from multiple pipeline runs."""
-
-    num_cases: int
-    num_successful: int
-    num_failed: int
-    mean_dice: float | None
-    std_dice: float | None
-    min_dice: float | None
-    max_dice: float | None
-    mean_elapsed_seconds: float
-
-
-# Internal helper
-def _load_or_get_adapter(
-    dataset_id: str | None = None,
-    cache: dict | None = None,
-) -> CaseAdapter:
-    """Load dataset and return adapter, using cache if available."""
-    ...
-```
-
-### `metrics.py`
-
-```python
-"""Metrics for evaluating segmentation quality."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import nibabel as nib
-import numpy as np
-from numpy.typing import NDArray
-
-
-def compute_dice(
-    prediction: Path | NDArray[np.float64],
-    ground_truth: Path | NDArray[np.float64],
-    *,
-    threshold: float = 0.5,
-) -> float:
-    """
-    Compute Dice similarity coefficient between prediction and ground truth.
-
-    Dice = 2 * |P ∩ G| / (|P| + |G|)
-
-    Args:
-        prediction: Path to NIfTI file or numpy array
-        ground_truth: Path to NIfTI file or numpy array
-        threshold: Threshold for binarization (if needed)
-
-    Returns:
-        Dice coefficient in [0, 1]
-
-    Raises:
-        ValueError: If shapes don't match
-    """
-    ...
-
-
-def compute_volume_ml(
-    mask: Path | NDArray[np.float64],
-    voxel_size_mm: tuple[float, float, float] | None = None,
-) -> float:
-    """
-    Compute lesion volume in milliliters.
-
-    Args:
-        mask: Path to NIfTI file or numpy array
-        voxel_size_mm: Voxel dimensions in mm (read from NIfTI if None)
-
-    Returns:
-        Volume in milliliters (mL)
-    """
-    ...
-
-
-def load_nifti_as_array(path: Path) -> tuple[NDArray[np.float64], tuple[float, ...]]:
-    """
-    Load NIfTI file and return data array with voxel dimensions.
-
-    Returns:
-        Tuple of (data_array, voxel_sizes_mm)
-    """
-    ...
-```
-
-### `cli.py` (optional)
-
-```python
-"""Command-line interface for stroke-deepisles-demo."""
-
-from __future__ import annotations
-
-import argparse
-import sys
-from pathlib import Path
-
-
-def main(argv: list[str] | None = None) -> int:
-    """Main CLI entry point."""
-    parser = argparse.ArgumentParser(
-        prog="stroke-demo",
-        description="Run DeepISLES stroke segmentation on HF datasets",
-    )
-    subparsers = parser.add_subparsers(dest="command", required=True)
-
-    # List command
-    list_parser = subparsers.add_parser("list", help="List available cases")
-    list_parser.add_argument(
-        "--dataset", default=None, help="HF dataset ID"
-    )
-
-    # Run command
-    run_parser = subparsers.add_parser("run", help="Run segmentation")
-    run_parser.add_argument(
-        "--case", type=str, help="Case ID (e.g., sub-001)"
-    )
-    run_parser.add_argument(
-        "--index", type=int, help="Case index (alternative to --case)"
-    )
-    run_parser.add_argument(
-        "--output", type=Path, default=None, help="Output directory"
-    )
-    run_parser.add_argument(
-        "--fast", action="store_true", default=True, help="Use fast mode"
-    )
-    run_parser.add_argument(
-        "--no-gpu", action="store_true", help="Disable GPU"
-    )
-
-    args = parser.parse_args(argv)
-
-    if args.command == "list":
-        return cmd_list(args)
-    elif args.command == "run":
-        return cmd_run(args)
-
-    return 0
-
-
-def cmd_list(args: argparse.Namespace) -> int:
-    """Handle 'list' command."""
-    ...
-
-
-def cmd_run(args: argparse.Namespace) -> int:
-    """Handle 'run' command."""
-    ...
-
-
-if __name__ == "__main__":
-    sys.exit(main())
-```
-
-### pyproject.toml addition for CLI
-
-```toml
-[project.scripts]
-stroke-demo = "stroke_deepisles_demo.cli:main"
-```
-
-## tdd plan
-
-### test file structure
-
-```
-tests/
-├── test_pipeline.py         # Pipeline orchestration tests
-├── test_metrics.py          # Metrics computation tests
-└── test_cli.py              # CLI tests (optional)
-```
-
-### tests to write first (TDD order)
-
-#### 1. `tests/test_metrics.py` - Pure functions, no mocks needed
-
-```python
-"""Tests for metrics module."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import nibabel as nib
-import numpy as np
-import pytest
-
-from stroke_deepisles_demo.metrics import (
-    compute_dice,
-    compute_volume_ml,
-    load_nifti_as_array,
-)
-
-
-class TestComputeDice:
-    """Tests for compute_dice."""
-
-    def test_identical_masks_return_one(self) -> None:
-        """Dice of identical masks is 1.0."""
-        mask = np.array([[[1, 1, 0], [0, 1, 0], [0, 0, 1]]])
-
-        dice = compute_dice(mask, mask)
-
-        assert dice == 1.0
-
-    def test_no_overlap_returns_zero(self) -> None:
-        """Dice of non-overlapping masks is 0.0."""
-        pred = np.array([[[1, 1, 0], [0, 0, 0], [0, 0, 0]]])
-        gt = np.array([[[0, 0, 0], [0, 0, 0], [0, 0, 1]]])
-
-        dice = compute_dice(pred, gt)
-
-        assert dice == 0.0
-
-    def test_partial_overlap(self) -> None:
-        """Dice with partial overlap is between 0 and 1."""
-        pred = np.array([[[1, 1, 0], [0, 0, 0], [0, 0, 0]]])
-        gt = np.array([[[1, 0, 0], [0, 0, 0], [0, 0, 0]]])
-
-        dice = compute_dice(pred, gt)
-
-        # Overlap: 1, Pred: 2, GT: 1 -> Dice = 2*1 / (2+1) = 0.667
-        assert 0.6 < dice < 0.7
-
-    def test_empty_masks_return_one(self) -> None:
-        """Dice of two empty masks is 1.0 (both agree on nothing)."""
-        empty = np.zeros((10, 10, 10))
-
-        dice = compute_dice(empty, empty)
-
-        assert dice == 1.0
-
-    def test_accepts_file_paths(self, temp_dir: Path) -> None:
-        """Can compute Dice from NIfTI file paths."""
-        mask = np.array([[[1, 1, 0], [0, 1, 0], [0, 0, 1]]]).astype(np.float32)
-        img = nib.Nifti1Image(mask, np.eye(4))
-
-        pred_path = temp_dir / "pred.nii.gz"
-        gt_path = temp_dir / "gt.nii.gz"
-        nib.save(img, pred_path)
-        nib.save(img, gt_path)
-
-        dice = compute_dice(pred_path, gt_path)
-
-        assert dice == 1.0
-
-    def test_shape_mismatch_raises(self) -> None:
-        """Raises ValueError if shapes don't match."""
-        pred = np.zeros((10, 10, 10))
-        gt = np.zeros((10, 10, 5))
-
-        with pytest.raises(ValueError, match="shape"):
-            compute_dice(pred, gt)
-
-
-class TestComputeVolumeMl:
-    """Tests for compute_volume_ml."""
-
-    def test_computes_volume_from_voxel_size(self) -> None:
-        """Volume computed correctly from voxel dimensions."""
-        # 10x10x10 = 1000 voxels of size 1mm^3 each = 1000mm^3 = 1mL
-        mask = np.ones((10, 10, 10))
-
-        volume = compute_volume_ml(mask, voxel_size_mm=(1.0, 1.0, 1.0))
-
-        assert volume == pytest.approx(1.0, rel=0.01)
-
-    def test_reads_voxel_size_from_nifti(self, temp_dir: Path) -> None:
-        """Reads voxel size from NIfTI header."""
-        mask = np.ones((10, 10, 10)).astype(np.float32)
-        # Affine with 2mm voxels
-        affine = np.diag([2.0, 2.0, 2.0, 1.0])
-        img = nib.Nifti1Image(mask, affine)
-
-        path = temp_dir / "mask.nii.gz"
-        nib.save(img, path)
-
-        # 1000 voxels * 8mm^3 = 8000mm^3 = 8mL
-        volume = compute_volume_ml(path)
-
-        assert volume == pytest.approx(8.0, rel=0.01)
-
-
-class TestLoadNiftiAsArray:
-    """Tests for load_nifti_as_array."""
-
-    def test_returns_array_and_voxel_sizes(self, temp_dir: Path) -> None:
-        """Returns data array and voxel dimensions."""
-        data = np.random.rand(10, 10, 10).astype(np.float32)
-        affine = np.diag([1.5, 1.5, 2.0, 1.0])
-        img = nib.Nifti1Image(data, affine)
-
-        path = temp_dir / "test.nii.gz"
-        nib.save(img, path)
-
-        arr, voxels = load_nifti_as_array(path)
-
-        assert arr.shape == (10, 10, 10)
-        assert voxels == pytest.approx((1.5, 1.5, 2.0), rel=0.01)
-```
-
-#### 2. `tests/test_pipeline.py` - Full orchestration with mocks
-
-```python
-"""Tests for pipeline orchestration."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from stroke_deepisles_demo.core.types import CaseFiles
-from stroke_deepisles_demo.pipeline import (
-    PipelineResult,
-    PipelineSummary,
-    get_pipeline_summary,
-    run_pipeline_on_case,
-)
-
-
-class TestRunPipelineOnCase:
-    """Tests for run_pipeline_on_case."""
-
-    @pytest.fixture
-    def mock_dependencies(self, temp_dir: Path):
-        """Mock all external dependencies."""
-        with patch(
-            "stroke_deepisles_demo.pipeline.load_isles_dataset"
-        ) as mock_load, patch(
-            "stroke_deepisles_demo.pipeline.CaseAdapter"
-        ) as mock_adapter_cls, patch(
-            "stroke_deepisles_demo.pipeline.stage_case_for_deepisles"
-        ) as mock_stage, patch(
-            "stroke_deepisles_demo.pipeline.run_deepisles_on_folder"
-        ) as mock_inference, patch(
-            "stroke_deepisles_demo.pipeline.compute_dice"
-        ) as mock_dice:
-            # Configure mocks
-            mock_adapter = MagicMock()
-            mock_adapter.get_case.return_value = CaseFiles(
-                dwi=temp_dir / "dwi.nii.gz",
-                adc=temp_dir / "adc.nii.gz",
-                flair=None,
-                ground_truth=temp_dir / "gt.nii.gz",
-            )
-            mock_adapter_cls.return_value = mock_adapter
-
-            mock_stage.return_value = MagicMock(
-                input_dir=temp_dir / "staged",
-                dwi_path=temp_dir / "staged" / "dwi.nii.gz",
-                adc_path=temp_dir / "staged" / "adc.nii.gz",
-                flair_path=None,
-            )
-
-            mock_inference.return_value = MagicMock(
-                prediction_path=temp_dir / "results" / "pred.nii.gz",
-                elapsed_seconds=10.5,
-            )
-
-            mock_dice.return_value = 0.85
-
-            yield {
-                "load": mock_load,
-                "adapter_cls": mock_adapter_cls,
-                "adapter": mock_adapter,
-                "stage": mock_stage,
-                "inference": mock_inference,
-                "dice": mock_dice,
-            }
-
-    def test_returns_pipeline_result(self, mock_dependencies, temp_dir) -> None:
-        """Returns PipelineResult with expected fields."""
-        result = run_pipeline_on_case("sub-001")
-
-        assert isinstance(result, PipelineResult)
-        assert result.case_id == "sub-001"
-
-    def test_loads_case_from_adapter(self, mock_dependencies, temp_dir) -> None:
-        """Loads case using CaseAdapter."""
-        run_pipeline_on_case("sub-001")
-
-        mock_dependencies["adapter"].get_case.assert_called_once_with("sub-001")
-
-    def test_stages_files_for_deepisles(self, mock_dependencies, temp_dir) -> None:
-        """Stages files with correct naming."""
-        run_pipeline_on_case("sub-001")
-
-        mock_dependencies["stage"].assert_called_once()
-
-    def test_runs_deepisles_inference(self, mock_dependencies, temp_dir) -> None:
-        """Runs DeepISLES on staged directory."""
-        run_pipeline_on_case("sub-001", fast=True, gpu=False)
-
-        mock_dependencies["inference"].assert_called_once()
-        call_kwargs = mock_dependencies["inference"].call_args.kwargs
-        assert call_kwargs.get("fast") is True
-        assert call_kwargs.get("gpu") is False
-
-    def test_computes_dice_when_ground_truth_available(
-        self, mock_dependencies, temp_dir
-    ) -> None:
-        """Computes Dice score when ground truth is available."""
-        result = run_pipeline_on_case("sub-001", compute_dice=True)
-
-        mock_dependencies["dice"].assert_called_once()
-        assert result.dice_score == 0.85
-
-    def test_skips_dice_when_disabled(self, mock_dependencies, temp_dir) -> None:
-        """Skips Dice computation when compute_dice=False."""
-        result = run_pipeline_on_case("sub-001", compute_dice=False)
-
-        mock_dependencies["dice"].assert_not_called()
-        assert result.dice_score is None
-
-    def test_handles_missing_ground_truth(self, mock_dependencies, temp_dir) -> None:
-        """Handles cases without ground truth gracefully."""
-        # Modify mock to return no ground truth
-        mock_dependencies["adapter"].get_case.return_value = CaseFiles(
-            dwi=temp_dir / "dwi.nii.gz",
-            adc=temp_dir / "adc.nii.gz",
-            flair=None,
-            ground_truth=None,
-        )
-
-        result = run_pipeline_on_case("sub-001", compute_dice=True)
-
-        assert result.dice_score is None
-        assert result.ground_truth is None
-
-    def test_accepts_integer_index(self, mock_dependencies, temp_dir) -> None:
-        """Accepts integer index as case identifier."""
-        mock_dependencies["adapter"].get_case_by_index.return_value = (
-            "sub-001",
-            CaseFiles(
-                dwi=temp_dir / "dwi.nii.gz",
-                adc=temp_dir / "adc.nii.gz",
-                flair=None,
-                ground_truth=None,
-            ),
-        )
-
-        result = run_pipeline_on_case(0)
-
-        assert result.case_id == "sub-001"
-
-
-class TestGetPipelineSummary:
-    """Tests for get_pipeline_summary."""
-
-    def test_computes_mean_dice(self) -> None:
-        """Computes mean Dice from results."""
-        results = [
-            MagicMock(dice_score=0.8, elapsed_seconds=10),
-            MagicMock(dice_score=0.9, elapsed_seconds=12),
-            MagicMock(dice_score=0.7, elapsed_seconds=8),
-        ]
-
-        summary = get_pipeline_summary(results)
-
-        assert summary.mean_dice == pytest.approx(0.8, rel=0.01)
-
-    def test_handles_none_dice_scores(self) -> None:
-        """Handles results with None Dice scores."""
-        results = [
-            MagicMock(dice_score=0.8, elapsed_seconds=10),
-            MagicMock(dice_score=None, elapsed_seconds=12),
-            MagicMock(dice_score=0.7, elapsed_seconds=8),
-        ]
-
-        summary = get_pipeline_summary(results)
-
-        # Mean of 0.8 and 0.7 only
-        assert summary.mean_dice == pytest.approx(0.75, rel=0.01)
-
-    def test_counts_successful_and_failed(self) -> None:
-        """Counts successful and failed runs."""
-        results = [
-            MagicMock(dice_score=0.8, elapsed_seconds=10),
-            MagicMock(dice_score=None, elapsed_seconds=0),  # Failed
-        ]
-
-        summary = get_pipeline_summary(results)
-
-        assert summary.num_cases == 2
-        assert summary.num_successful == 1
-        assert summary.num_failed == 1
-
-
-@pytest.mark.integration
-class TestPipelineIntegration:
-    """Integration tests for full pipeline."""
-
-    @pytest.mark.slow
-    def test_run_on_real_case(self) -> None:
-        """Run pipeline on actual ISLES24-MR-Lite case."""
-        # Requires: network, Docker, DeepISLES image
-        # Run with: pytest -m "integration and slow"
-
-        result = run_pipeline_on_case(
-            0,  # First case
-            fast=True,
-            gpu=False,
-            compute_dice=True,
-        )
-
-        assert result.prediction_mask.exists()
-        assert 0 <= result.dice_score <= 1
-```
-
-### what to mock
-
-- `load_isles_dataset` - Avoid network calls
-- `CaseAdapter` - Return synthetic CaseFiles
-- `stage_case_for_deepisles` - Return mock staged paths
-- `run_deepisles_on_folder` - Avoid Docker
-- `compute_dice` - Return fixed value for deterministic tests
-
-### what to test for real
-
-- Dice computation (pure NumPy)
-- Volume computation (pure NumPy + nibabel)
-- NIfTI loading
-- Integration: full pipeline on real data
-
-## "done" criteria
-
-Phase 3 is complete when:
-
-1. All unit tests pass: `uv run pytest tests/test_pipeline.py tests/test_metrics.py -v`
-2. Dice computation is correct for known test cases
-3. Pipeline orchestrates all components correctly
-4. CLI works: `uv run stroke-demo list` and `uv run stroke-demo run --index 0`
-5. Integration test passes: `uv run pytest -m "integration and slow"`
-6. Type checking passes: `uv run mypy src/stroke_deepisles_demo/pipeline.py src/stroke_deepisles_demo/metrics.py`
-7. Code coverage for pipeline module > 80%
-
-## implementation notes
-
-- Use dataclasses for results (immutable, typed)
-- Consider caching the loaded dataset in module-level variable
-- Dice should handle edge cases (empty masks, shape mismatches)
-- CLI is optional but useful for manual testing
-- Batch processing is sequential by default (GPU constraint)

docs/specs/archive/05-phase-4-gradio-ui.md

@@ -1,778 +0,0 @@
-# phase 4: gradio / spaces app
-
-## purpose
-
-Build a minimal but clean Gradio 5 app that allows interactive case selection, segmentation, and visualization. At the end of this phase, we have a deployable Hugging Face Space.
-
-## deliverables
-
-- [ ] `src/stroke_deepisles_demo/ui/app.py` - Main Gradio application
-- [ ] `src/stroke_deepisles_demo/ui/viewer.py` - NiiVue integration
-- [ ] `src/stroke_deepisles_demo/ui/components.py` - Reusable UI components
-- [ ] `app.py` at repo root - HF Spaces entry point
-- [ ] Unit tests for UI logic (not Gradio itself)
-- [ ] Smoke test for app import
-
-## vertical slice outcome
-
-After this phase, you can run locally:
-
-```bash
-uv run gradio src/stroke_deepisles_demo/ui/app.py
-# or
-uv run python -m stroke_deepisles_demo.ui.app
-```
-
-And deploy to Hugging Face Spaces with the standard Gradio SDK.
-
-## module structure
-
-```
-src/stroke_deepisles_demo/ui/
-├── __init__.py          # Public API
-├── app.py               # Main Gradio application
-├── viewer.py            # NiiVue integration
-└── components.py        # Reusable UI components
-
-# Root level for HF Spaces
-app.py                   # Entry point: from stroke_deepisles_demo.ui.app import demo
-```
-
-## gradio 5 considerations
-
-Based on [Gradio 5 documentation](https://huggingface.co/blog/gradio-5):
-
-- Server-side rendering (SSR) for fast initial load
-- Improved components (Buttons, Tabs, Sliders)
-- WebRTC support for real-time streaming
-- New built-in themes
-
-Key patterns:
-```python
-import gradio as gr
-
-# Gradio 5 app pattern
-with gr.Blocks(theme=gr.themes.Soft()) as demo:
-    gr.Markdown("# Title")
-    with gr.Row():
-        with gr.Column():
-            # Inputs
-            ...
-        with gr.Column():
-            # Outputs
-            ...
-
-demo.launch()
-```
-
-## niivue integration strategy
-
-[NiiVue](https://github.com/niivue/niivue) is a WebGL2-based neuroimaging viewer.
-
-### proven implementation: tobias's bids-neuroimaging space
-
-**Reference**: [TobiasPitters/bids-neuroimaging](https://huggingface.co/spaces/TobiasPitters/bids-neuroimaging) - A working HF Space with NiiVue multiplanar + 3D rendering.
-
-Key patterns from Tobias's implementation:
-
-1. **FastAPI + raw HTML** (not Gradio) - Cleaner for single-page viewer
-2. **NiiVue via unpkg CDN**: `https://unpkg.com/@niivue/niivue@0.57.0/dist/index.js`
-3. **Base64 data URLs** for NIfTI data (no file serving needed):
-   ```python
-   import base64
-   nifti_bytes = nifti_image.to_bytes()
-   nifti_b64 = base64.b64encode(nifti_bytes).decode("utf-8")
-   data_url = f"data:application/octet-stream;base64,{nifti_b64}"
-   ```
-4. **NiiVue configuration for multiplanar + 3D**:
-   ```javascript
-   nv.setSliceType(nv.sliceTypeMultiplanar);
-   nv.setMultiplanarLayout(2);  // 2x2 grid with 3D render
-   nv.opts.show3Dcrosshair = true;
-   ```
-
-### implementation approach: gradio + direct base64 injection
-
-For our demo, we use:
-- **Gradio** for case selection dropdown and "Run Segmentation" button
-- **Direct Base64 data URLs** injected into HTML (no separate API endpoints)
-- **NiiVue via `gr.HTML`** for interactive 3D visualization
-
-This gives us:
-- Gradio's nice UI components for inputs
-- Proven NiiVue rendering pattern from Tobias's implementation
-- No iframe complexity, no proxy issues in HF Spaces
-
-### concrete implementation
-
-```python
-import base64
-from pathlib import Path
-import nibabel as nib
-
-def nifti_to_data_url(nifti_path: Path) -> str:
-    """Convert NIfTI file to base64 data URL for NiiVue."""
-    img = nib.load(nifti_path)
-    nifti_bytes = img.to_bytes()
-    nifti_b64 = base64.b64encode(nifti_bytes).decode("utf-8")
-    return f"data:application/octet-stream;base64,{nifti_b64}"
-
-def create_niivue_viewer_html(
-    volume_data_url: str,
-    mask_data_url: str | None = None,
-    height: int = 600,
-) -> str:
-    """Create NiiVue HTML viewer with optional mask overlay."""
-    mask_loading = ""
-    if mask_data_url:
-        mask_loading = f"""
-            volumes.push({{
-                url: '{mask_data_url}',
-                colorMap: 'red',
-                opacity: 0.5
-            }});
-        """
-
-    return f"""
-    <div style="width:100%; height:{height}px; background:#000; border-radius:8px;">
-        <canvas id="niivue-canvas" style="width:100%; height:100%;"></canvas>
-    </div>
-    <script type="module">
-        const niivueModule = await import('https://unpkg.com/@niivue/niivue@0.57.0/dist/index.js');
-        const Niivue = niivueModule.Niivue;
-
-        const nv = new Niivue({{
-            logging: false,
-            show3Dcrosshair: true,
-            textHeight: 0.04
-        }});
-
-        await nv.attachTo('niivue-canvas');
-
-        const volumes = [{{
-            url: '{volume_data_url}',
-            name: 'dwi.nii.gz'
-        }}];
-        {mask_loading}
-
-        await nv.loadVolumes(volumes);
-
-        // Multiplanar + 3D view
-        nv.setSliceType(nv.sliceTypeMultiplanar);
-        if (nv.setMultiplanarLayout) {{
-            nv.setMultiplanarLayout(2);
-        }}
-        nv.opts.show3Dcrosshair = true;
-        nv.setRenderAzimuthElevation(120, 10);
-        nv.drawScene();
-    </script>
-    """
-```
-
-## interfaces and types
-
-### `ui/app.py`
-
-```python
-"""Main Gradio application for stroke-deepisles-demo."""
-
-from __future__ import annotations
-
-import gradio as gr
-
-from stroke_deepisles_demo.pipeline import run_pipeline_on_case
-from stroke_deepisles_demo.ui.components import create_case_selector, create_results_display
-from stroke_deepisles_demo.ui.viewer import render_comparison_view
-
-
-def create_app() -> gr.Blocks:
-    """
-    Create the Gradio application.
-
-    Returns:
-        Configured gr.Blocks application
-    """
-    with gr.Blocks(
-        title="Stroke Lesion Segmentation Demo",
-        theme=gr.themes.Soft(),
-    ) as demo:
-        # Header
-        gr.Markdown("""
-        # Stroke Lesion Segmentation Demo
-
-        This demo runs [DeepISLES](https://github.com/ezequieldlrosa/DeepIsles)
-        stroke segmentation on cases from
-        [ISLES24-MR-Lite](https://huggingface.co/datasets/YongchengYAO/ISLES24-MR-Lite).
-
-        > **Disclaimer**: This is for research/demonstration only. Not for clinical use.
-        """)
-
-        with gr.Row():
-            # Left column: Controls
-            with gr.Column(scale=1):
-                case_selector = create_case_selector()
-                run_btn = gr.Button("Run Segmentation", variant="primary")
-                status = gr.Textbox(label="Status", interactive=False)
-
-            # Right column: Results
-            with gr.Column(scale=2):
-                results_display = create_results_display()
-
-        # Event handlers
-        run_btn.click(
-            fn=run_segmentation,
-            inputs=[case_selector],
-            outputs=[results_display, status],
-        )
-
-    return demo
-
-
-def run_segmentation(case_id: str) -> tuple[dict, str]:
-    """
-    Run segmentation and return results for display.
-
-    Args:
-        case_id: Selected case identifier
-
-    Returns:
-        Tuple of (results_dict, status_message)
-    """
-    ...
-
-
-# Module-level app instance for Gradio CLI
-demo = create_app()
-
-if __name__ == "__main__":
-    demo.launch()
-```
-
-### `ui/viewer.py`
-
-```python
-"""Neuroimaging visualization for Gradio."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-import numpy as np
-
-if TYPE_CHECKING:
-    from matplotlib.figure import Figure
-    from numpy.typing import NDArray
-
-
-def render_slice_comparison(
-    dwi_path: Path,
-    prediction_path: Path,
-    ground_truth_path: Path | None = None,
-    *,
-    slice_idx: int | None = None,
-    orientation: str = "axial",
-) -> Figure:
-    """
-    Render side-by-side comparison of DWI, prediction, and ground truth.
-
-    Args:
-        dwi_path: Path to DWI NIfTI
-        prediction_path: Path to predicted mask NIfTI
-        ground_truth_path: Optional path to ground truth mask
-        slice_idx: Slice index (default: middle slice)
-        orientation: One of "axial", "coronal", "sagittal"
-
-    Returns:
-        Matplotlib figure with comparison view
-    """
-    ...
-
-
-def render_3panel_view(
-    nifti_path: Path,
-    mask_path: Path | None = None,
-    *,
-    mask_alpha: float = 0.5,
-    mask_color: str = "red",
-) -> Figure:
-    """
-    Render axial/coronal/sagittal slices with optional mask overlay.
-
-    Args:
-        nifti_path: Path to base NIfTI volume
-        mask_path: Optional path to mask for overlay
-        mask_alpha: Transparency of mask overlay
-        mask_color: Color for mask overlay
-
-    Returns:
-        Matplotlib figure with 3-panel view
-    """
-    ...
-
-
-def create_niivue_html(
-    volume_url: str,
-    mask_url: str | None = None,
-    *,
-    height: int = 400,
-) -> str:
-    """
-    Create HTML/JS for NiiVue viewer.
-
-    Args:
-        volume_url: URL to volume NIfTI file
-        mask_url: Optional URL to mask NIfTI file
-        height: Viewer height in pixels
-
-    Returns:
-        HTML string with embedded NiiVue viewer
-    """
-    template = f"""
-    <div id="gl" style="width:100%; height:{height}px;"></div>
-    <script type="module">
-        const niivueModule = await import('https://unpkg.com/@niivue/niivue@0.57.0/dist/index.js');
-        const Niivue = niivueModule.Niivue;
-        const nv = new Niivue({{ show3Dcrosshair: true }});
-        nv.attachToCanvas(document.getElementById('gl'));
-        const volumes = [{{ url: '{volume_url}' }}];
-        {'volumes.push({ url: "' + mask_url + '", colorMap: "red", opacity: 0.5 });' if mask_url else ''}
-        await nv.loadVolumes(volumes);
-    </script>
-    """
-    return template
-
-
-def get_slice_at_max_lesion(
-    mask_path: Path,
-    orientation: str = "axial",
-) -> int:
-    """
-    Find slice index with maximum lesion area.
-
-    Useful for displaying the most informative slice.
-
-    Args:
-        mask_path: Path to lesion mask NIfTI
-        orientation: Slice orientation
-
-    Returns:
-        Slice index with maximum lesion area
-    """
-    ...
-```
-
-### `ui/components.py`
-
-```python
-"""Reusable UI components."""
-
-from __future__ import annotations
-
-import gradio as gr
-
-from stroke_deepisles_demo.data import list_case_ids
-
-
-def create_case_selector() -> gr.Dropdown:
-    """
-    Create a dropdown for selecting cases.
-
-    Returns:
-        Configured gr.Dropdown component
-    """
-    try:
-        case_ids = list_case_ids()
-    except Exception:
-        case_ids = ["Error loading cases"]
-
-    return gr.Dropdown(
-        choices=case_ids,
-        value=case_ids[0] if case_ids else None,
-        label="Select Case",
-        info="Choose a case from ISLES24-MR-Lite",
-    )
-
-
-def create_results_display() -> dict[str, gr.components.Component]:
-    """
-    Create results display components.
-
-    Returns:
-        Dictionary of component name -> gr.Component
-    """
-    with gr.Group():
-        viewer = gr.Image(label="Segmentation Result", type="filepath")
-        metrics = gr.JSON(label="Metrics")
-        download = gr.File(label="Download Prediction")
-
-    return {
-        "viewer": viewer,
-        "metrics": metrics,
-        "download": download,
-    }
-
-
-def create_settings_accordion() -> dict[str, gr.components.Component]:
-    """
-    Create expandable settings section.
-
-    Returns:
-        Dictionary of setting name -> gr.Component
-    """
-    with gr.Accordion("Advanced Settings", open=False):
-        fast_mode = gr.Checkbox(
-            value=True,
-            label="Fast Mode (SEALS)",
-            info="Run SEALS only (ISLES'22 winner, requires DWI+ADC). Disable for full ensemble (requires FLAIR).",
-        )
-        show_ground_truth = gr.Checkbox(
-            value=True,
-            label="Show Ground Truth",
-            info="Display ground truth mask if available",
-        )
-
-    return {
-        "fast_mode": fast_mode,
-        "show_ground_truth": show_ground_truth,
-    }
-```
-
-### Root `app.py` for HF Spaces
-
-```python
-"""Entry point for Hugging Face Spaces deployment."""
-
-from stroke_deepisles_demo.ui.app import demo
-
-if __name__ == "__main__":
-    demo.launch()
-```
-
-## hugging face spaces configuration
-
-### `README.md` header for Spaces
-
-```yaml
----
-title: Stroke DeepISLES Demo
-emoji: 🧠
-colorFrom: blue
-colorTo: purple
-sdk: gradio
-sdk_version: 5.0.0
-app_file: app.py
-pinned: false
-license: mit
----
-```
-
-### `requirements.txt` for Spaces
-
-```
-# Note: HF Spaces uses requirements.txt, not pyproject.toml
-git+https://github.com/CloseChoice/datasets.git@feat/bids-loader-streaming-upload-fix
-huggingface-hub>=0.25.0
-nibabel>=5.2.0
-numpy>=1.26.0
-pydantic>=2.5.0
-pydantic-settings>=2.1.0
-gradio>=5.0.0
-matplotlib>=3.8.0
-```
-
-## tdd plan
-
-### test file structure
-
-```
-tests/
-├── ui/
-│   ├── __init__.py
-│   ├── test_viewer.py       # Tests for visualization
-│   ├── test_components.py   # Tests for UI components
-│   └── test_app.py          # Smoke tests for app
-```
-
-### tests to write first (TDD order)
-
-#### 1. `tests/ui/test_viewer.py` - Pure visualization functions
-
-```python
-"""Tests for viewer module."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import matplotlib
-import matplotlib.pyplot as plt
-import numpy as np
-import pytest
-
-matplotlib.use("Agg")  # Non-interactive backend for tests
-
-from stroke_deepisles_demo.ui.viewer import (
-    create_niivue_html,
-    get_slice_at_max_lesion,
-    render_3panel_view,
-    render_slice_comparison,
-)
-
-
-class TestRender3PanelView:
-    """Tests for render_3panel_view."""
-
-    def test_returns_matplotlib_figure(self, synthetic_nifti_3d: Path) -> None:
-        """Returns a matplotlib Figure object."""
-        fig = render_3panel_view(synthetic_nifti_3d)
-
-        assert isinstance(fig, plt.Figure)
-        plt.close(fig)
-
-    def test_has_three_axes(self, synthetic_nifti_3d: Path) -> None:
-        """Figure has 3 subplots (axial, coronal, sagittal)."""
-        fig = render_3panel_view(synthetic_nifti_3d)
-
-        assert len(fig.axes) == 3
-        plt.close(fig)
-
-    def test_overlay_mask_when_provided(
-        self, synthetic_nifti_3d: Path, temp_dir: Path
-    ) -> None:
-        """Overlays mask when mask_path provided."""
-        # Create a simple mask
-        import nibabel as nib
-
-        mask_data = np.zeros((10, 10, 10), dtype=np.uint8)
-        mask_data[4:6, 4:6, 4:6] = 1
-        mask_img = nib.Nifti1Image(mask_data, np.eye(4))
-        mask_path = temp_dir / "mask.nii.gz"
-        nib.save(mask_img, mask_path)
-
-        fig = render_3panel_view(synthetic_nifti_3d, mask_path=mask_path)
-
-        # Should not raise
-        assert fig is not None
-        plt.close(fig)
-
-
-class TestRenderSliceComparison:
-    """Tests for render_slice_comparison."""
-
-    def test_comparison_without_ground_truth(
-        self, synthetic_nifti_3d: Path
-    ) -> None:
-        """Works when ground truth is None."""
-        fig = render_slice_comparison(
-            synthetic_nifti_3d,
-            synthetic_nifti_3d,  # Use same as prediction for test
-            ground_truth_path=None,
-        )
-
-        assert isinstance(fig, plt.Figure)
-        plt.close(fig)
-
-    def test_comparison_with_ground_truth(
-        self, synthetic_nifti_3d: Path
-    ) -> None:
-        """Works when ground truth is provided."""
-        fig = render_slice_comparison(
-            synthetic_nifti_3d,
-            synthetic_nifti_3d,
-            ground_truth_path=synthetic_nifti_3d,
-        )
-
-        assert isinstance(fig, plt.Figure)
-        plt.close(fig)
-
-
-class TestGetSliceAtMaxLesion:
-    """Tests for get_slice_at_max_lesion."""
-
-    def test_finds_slice_with_lesion(self, temp_dir: Path) -> None:
-        """Returns slice index where lesion is largest."""
-        import nibabel as nib
-
-        # Create mask with lesion at slice 7
-        mask_data = np.zeros((10, 10, 10), dtype=np.uint8)
-        mask_data[:, :, 7] = 1  # Full slice 7 is lesion
-
-        mask_img = nib.Nifti1Image(mask_data, np.eye(4))
-        mask_path = temp_dir / "mask.nii.gz"
-        nib.save(mask_img, mask_path)
-
-        slice_idx = get_slice_at_max_lesion(mask_path, orientation="axial")
-
-        assert slice_idx == 7
-
-    def test_returns_middle_for_empty_mask(self, temp_dir: Path) -> None:
-        """Returns middle slice when mask is empty."""
-        import nibabel as nib
-
-        mask_data = np.zeros((10, 10, 20), dtype=np.uint8)
-        mask_img = nib.Nifti1Image(mask_data, np.eye(4))
-        mask_path = temp_dir / "mask.nii.gz"
-        nib.save(mask_img, mask_path)
-
-        slice_idx = get_slice_at_max_lesion(mask_path, orientation="axial")
-
-        assert slice_idx == 10  # Middle of 20
-
-
-class TestCreateNiivueHtml:
-    """Tests for create_niivue_html."""
-
-    def test_includes_volume_url(self) -> None:
-        """Generated HTML includes the volume URL."""
-        html = create_niivue_html("http://example.com/brain.nii.gz")
-
-        assert "http://example.com/brain.nii.gz" in html
-
-    def test_includes_mask_when_provided(self) -> None:
-        """Generated HTML includes mask URL when provided."""
-        html = create_niivue_html(
-            "http://example.com/brain.nii.gz",
-            mask_url="http://example.com/mask.nii.gz",
-        )
-
-        assert "http://example.com/mask.nii.gz" in html
-
-    def test_sets_height(self) -> None:
-        """Generated HTML respects height parameter."""
-        html = create_niivue_html(
-            "http://example.com/brain.nii.gz",
-            height=600,
-        )
-
-        assert "height:600px" in html
-```
-
-#### 2. `tests/ui/test_app.py` - Smoke tests
-
-```python
-"""Smoke tests for Gradio app."""
-
-from __future__ import annotations
-
-
-def test_app_module_imports() -> None:
-    """App module imports without side effects."""
-    # This should not launch the app or make network calls
-    from stroke_deepisles_demo.ui import app
-
-    assert hasattr(app, "create_app")
-    assert hasattr(app, "demo")
-
-
-def test_create_app_returns_blocks() -> None:
-    """create_app returns a gr.Blocks instance."""
-    import gradio as gr
-
-    from stroke_deepisles_demo.ui.app import create_app
-
-    app = create_app()
-
-    assert isinstance(app, gr.Blocks)
-
-
-def test_viewer_module_imports() -> None:
-    """Viewer module imports without errors."""
-    from stroke_deepisles_demo.ui import viewer
-
-    assert hasattr(viewer, "render_3panel_view")
-    assert hasattr(viewer, "create_niivue_html")
-
-
-def test_components_module_imports() -> None:
-    """Components module imports without errors."""
-    from stroke_deepisles_demo.ui import components
-
-    assert hasattr(components, "create_case_selector")
-    assert hasattr(components, "create_results_display")
-```
-
-### what to mock
-
-- `list_case_ids()` in components - Avoid network during import
-- Any data loading in app initialization
-
-### what to test for real
-
-- Matplotlib figure generation
-- NiiVue HTML string generation
-- Slice finding algorithms
-- Module imports (no network side effects)
-
-## "done" criteria
-
-Phase 4 is complete when:
-
-1. All unit tests pass: `uv run pytest tests/ui/ -v`
-2. App launches locally: `uv run python -m stroke_deepisles_demo.ui.app`
-3. Can select a case, click "Run", see visualization
-4. Visualization shows DWI with predicted mask overlay
-5. Metrics (Dice score) displayed
-6. Type checking passes: `uv run mypy src/stroke_deepisles_demo/ui/`
-7. Ready for HF Spaces deployment (README header, requirements.txt)
-
-## implementation notes
-
-- **NiiVue is primary** - Proven working in Tobias's Space, not "fragile"
-- **Base64 data URLs** - Avoids file serving complexity, works in all environments
-- **Lazy initialization** - Do NOT call `list_case_ids()` at module import time (causes network calls)
-- **Test on HF Spaces early** - Verify WebGL works in their environment
-- **Keep UI simple** - This is a demo, not a full application
-- **Cache case list** - Avoid repeated HF Hub calls
-
-### avoiding import-time side effects
-
-The reviewer correctly noted that `demo = create_app()` at module level triggers network calls. Fix:
-
-```python
-# BAD - triggers network call on import
-demo = create_app()
-
-# GOOD - lazy initialization
-_demo: gr.Blocks | None = None
-
-def get_demo() -> gr.Blocks:
-    global _demo
-    if _demo is None:
-        _demo = create_app()
-    return _demo
-
-# For Gradio CLI compatibility
-demo = None  # Set lazily
-
-if __name__ == "__main__":
-    get_demo().launch()
-```
-
-Or use a factory pattern in the root `app.py`:
-
-```python
-# app.py (HF Spaces entry point)
-from stroke_deepisles_demo.ui.app import create_app
-
-demo = create_app()  # Only called when this file is executed
-
-if __name__ == "__main__":
-    demo.launch()
-```
-
-## dependencies to add
-
-```toml
-# Add to pyproject.toml dependencies
-"matplotlib>=3.8.0",  # For static slice rendering in viewer.py
-```
-
-## reference implementation
-
-Clone Tobias's working Space for reference:
-```
-_reference_repos/bids-neuroimaging-space/
-```
-
-Key file: `main.py` - Complete NiiVue + FastAPI implementation.

docs/specs/archive/06-phase-5-polish.md

@@ -1,667 +0,0 @@
-# phase 5: polish, observability, and docs
-
-## purpose
-
-Add production-quality polish: structured logging, environment-driven configuration, comprehensive documentation, and CI readiness. At the end of this phase, the codebase is maintainable, debuggable, and ready for others to contribute.
-
-## deliverables
-
-- [ ] Structured logging throughout all modules
-- [ ] Environment-driven configuration via pydantic-settings
-- [ ] Developer documentation (CONTRIBUTING.md, architecture)
-- [ ] API documentation (docstrings, optional Sphinx/mkdocs)
-- [ ] CI configuration (GitHub Actions)
-- [ ] Final cleanup and code review checklist
-
-## logging strategy
-
-### centralized logging setup
-
-```python
-# src/stroke_deepisles_demo/core/logging.py
-
-"""Centralized logging configuration."""
-
-from __future__ import annotations
-
-import logging
-import sys
-from typing import Literal
-
-LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
-
-
-def setup_logging(
-    level: LogLevel = "INFO",
-    *,
-    format_style: Literal["simple", "detailed", "json"] = "simple",
-) -> None:
-    """
-    Configure logging for the application.
-
-    Args:
-        level: Minimum log level
-        format_style: Output format style
-
-    Example:
-        >>> setup_logging("DEBUG", format_style="detailed")
-    """
-    formats = {
-        "simple": "%(levelname)s: %(message)s",
-        "detailed": "%(asctime)s | %(name)s | %(levelname)s | %(message)s",
-        "json": '{"time": "%(asctime)s", "name": "%(name)s", "level": "%(levelname)s", "message": "%(message)s"}',
-    }
-
-    logging.basicConfig(
-        level=getattr(logging, level),
-        format=formats[format_style],
-        stream=sys.stderr,
-        force=True,
-    )
-
-    # Reduce noise from libraries
-    logging.getLogger("urllib3").setLevel(logging.WARNING)
-    logging.getLogger("httpx").setLevel(logging.WARNING)
-    logging.getLogger("datasets").setLevel(logging.WARNING)
-
-
-def get_logger(name: str) -> logging.Logger:
-    """
-    Get a logger for a module.
-
-    Args:
-        name: Logger name (typically __name__)
-
-    Returns:
-        Configured logger instance
-    """
-    return logging.getLogger(f"stroke_demo.{name}")
-```
-
-### logging usage pattern
-
-```python
-# In each module
-from stroke_deepisles_demo.core.logging import get_logger
-
-logger = get_logger(__name__)
-
-
-def run_deepisles_on_folder(input_dir: Path, *, fast: bool = True) -> DeepISLESResult:
-    logger.info("Starting DeepISLES inference", extra={"input_dir": str(input_dir), "fast": fast})
-
-    try:
-        result = _run_docker(...)
-        logger.info("Inference complete", extra={"elapsed": result.elapsed_seconds})
-        return result
-    except Exception as e:
-        logger.error("Inference failed", extra={"error": str(e)}, exc_info=True)
-        raise
-```
-
-## enhanced configuration
-
-### `src/stroke_deepisles_demo/core/config.py`
-
-```python
-"""Application configuration using pydantic-settings."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Literal
-
-from pydantic import Field, field_validator
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-
-class Settings(BaseSettings):
-    """
-    Application settings loaded from environment variables.
-
-    All settings can be overridden via environment variables with
-    the STROKE_DEMO_ prefix.
-
-    Example:
-        export STROKE_DEMO_LOG_LEVEL=DEBUG
-        export STROKE_DEMO_HF_DATASET_ID=my/dataset
-    """
-
-    model_config = SettingsConfigDict(
-        env_prefix="STROKE_DEMO_",
-        env_file=".env",
-        env_file_encoding="utf-8",
-        extra="ignore",
-    )
-
-    # Logging
-    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
-    log_format: Literal["simple", "detailed", "json"] = "simple"
-
-    # HuggingFace
-    hf_dataset_id: str = "YongchengYAO/ISLES24-MR-Lite"
-    hf_cache_dir: Path | None = None
-    hf_token: str | None = Field(default=None, repr=False)  # Hidden from logs
-
-    # DeepISLES
-    deepisles_docker_image: str = "isleschallenge/deepisles"
-    deepisles_fast_mode: bool = True  # SEALS-only (ISLES'22 winner, no FLAIR needed)
-    deepisles_timeout_seconds: int = 1800  # 30 minutes
-    deepisles_use_gpu: bool = True
-
-    # Paths
-    temp_dir: Path | None = None
-    results_dir: Path = Path("./results")
-
-    # UI
-    gradio_server_name: str = "0.0.0.0"
-    gradio_server_port: int = 7860
-    gradio_share: bool = False
-
-    @field_validator("results_dir", mode="before")
-    @classmethod
-    def ensure_results_dir_exists(cls, v: Path | str) -> Path:
-        """Create results directory if it doesn't exist."""
-        path = Path(v)
-        path.mkdir(parents=True, exist_ok=True)
-        return path
-
-
-# Global settings instance
-settings = Settings()
-
-
-def get_settings() -> Settings:
-    """Get the current settings instance."""
-    return settings
-
-
-def reload_settings() -> Settings:
-    """Reload settings from environment (useful for testing)."""
-    global settings
-    settings = Settings()
-    return settings
-```
-
-## documentation structure
-
-```
-docs/
-├── specs/                  # Design specs (these documents)
-│   ├── 00-context.md
-│   ├── 01-phase-0-repo-bootstrap.md
-│   ├── ...
-│   └── 06-phase-5-polish.md
-│
-├── guides/                 # User guides
-│   ├── quickstart.md       # Getting started
-│   ├── configuration.md    # Environment variables
-│   └── deployment.md       # HF Spaces deployment
-│
-└── reference/              # API reference (auto-generated)
-    └── api.md
-
-# Root level
-README.md                   # Project overview
-CONTRIBUTING.md             # Contribution guidelines
-CHANGELOG.md                # Version history
-```
-
-### `CONTRIBUTING.md`
-
-```markdown
-# Contributing to stroke-deepisles-demo
-
-Thank you for your interest in contributing!
-
-## Development Setup
-
-1. **Clone the repository**
-   ```bash
-   git clone https://github.com/The-Obstacle-Is-The-Way/stroke-deepisles-demo.git
-   cd stroke-deepisles-demo
-   ```
-
-2. **Install uv** (if not already installed)
-   ```bash
-   curl -LsSf https://astral.sh/uv/install.sh | sh
-   ```
-
-3. **Install dependencies**
-   ```bash
-   uv sync
-   ```
-
-4. **Install pre-commit hooks**
-   ```bash
-   uv run pre-commit install
-   ```
-
-## Running Tests
-
-```bash
-# All tests (excluding integration)
-uv run pytest
-
-# With coverage
-uv run pytest --cov
-
-# Integration tests (requires Docker)
-uv run pytest -m integration
-
-# Slow tests (requires Docker + DeepISLES image)
-uv run pytest -m "integration and slow"
-```
-
-## Code Quality
-
-```bash
-# Lint
-uv run ruff check .
-
-# Format
-uv run ruff format .
-
-# Type check
-uv run mypy src/
-```
-
-## Project Structure
-
-```
-src/stroke_deepisles_demo/
-├── core/           # Shared utilities (config, types, exceptions)
-├── data/           # HF dataset loading and case management
-├── inference/      # DeepISLES Docker integration
-├── ui/             # Gradio application
-├── pipeline.py     # End-to-end orchestration
-└── metrics.py      # Evaluation metrics
-```
-
-## Pull Request Process
-
-1. Create a feature branch from `main`
-2. Write tests for new functionality
-3. Ensure all tests pass and code quality checks pass
-4. Update documentation if needed
-5. Submit PR with clear description
-
-## Code Style
-
-- Type hints on all functions
-- Docstrings in Google style
-- Keep functions focused and small
-- Prefer explicit over implicit
-```
-
-### `docs/guides/quickstart.md`
-
-```markdown
-# Quickstart
-
-Get started with stroke-deepisles-demo in 5 minutes.
-
-## Prerequisites
-
-- Python 3.11+
-- Docker (for DeepISLES inference)
-- ~10GB disk space (for Docker image and datasets)
-
-## Installation
-
-```bash
-# Clone
-git clone https://github.com/The-Obstacle-Is-The-Way/stroke-deepisles-demo.git
-cd stroke-deepisles-demo
-
-# Install
-uv sync
-```
-
-## Pull DeepISLES Docker Image
-
-```bash
-docker pull isleschallenge/deepisles
-```
-
-## Run Locally
-
-### Option 1: Gradio UI
-
-```bash
-uv run python -m stroke_deepisles_demo.ui.app
-# Open http://localhost:7860
-```
-
-### Option 2: CLI
-
-```bash
-# List available cases
-uv run stroke-demo list
-
-# Run on a specific case
-uv run stroke-demo run --case sub-001 --fast
-```
-
-### Option 3: Python API
-
-```python
-from stroke_deepisles_demo.pipeline import run_pipeline_on_case
-
-result = run_pipeline_on_case("sub-001", fast=True)
-print(f"Dice score: {result.dice_score:.3f}")
-print(f"Prediction: {result.prediction_mask}")
-```
-
-## Configuration
-
-Set environment variables or create a `.env` file:
-
-```bash
-# .env
-STROKE_DEMO_LOG_LEVEL=DEBUG
-STROKE_DEMO_DEEPISLES_USE_GPU=false  # If no GPU available
-```
-
-See [Configuration Guide](configuration.md) for all options.
-```
-
-### `docs/guides/configuration.md`
-
-```markdown
-# Configuration
-
-All settings can be configured via environment variables.
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `STROKE_DEMO_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
-| `STROKE_DEMO_LOG_FORMAT` | `simple` | Log format (simple, detailed, json) |
-| `STROKE_DEMO_HF_DATASET_ID` | `YongchengYAO/ISLES24-MR-Lite` | HuggingFace dataset ID |
-| `STROKE_DEMO_HF_CACHE_DIR` | `None` | Custom HF cache directory |
-| `STROKE_DEMO_HF_TOKEN` | `None` | HuggingFace API token (for private datasets) |
-| `STROKE_DEMO_DEEPISLES_DOCKER_IMAGE` | `isleschallenge/deepisles` | DeepISLES Docker image |
-| `STROKE_DEMO_DEEPISLES_FAST_MODE` | `true` | Use single-model mode |
-| `STROKE_DEMO_DEEPISLES_TIMEOUT_SECONDS` | `1800` | Inference timeout |
-| `STROKE_DEMO_DEEPISLES_USE_GPU` | `true` | Use GPU acceleration |
-| `STROKE_DEMO_RESULTS_DIR` | `./results` | Directory for output files |
-
-## Using .env File
-
-Create a `.env` file in the project root:
-
-```bash
-STROKE_DEMO_LOG_LEVEL=DEBUG
-STROKE_DEMO_DEEPISLES_USE_GPU=false
-STROKE_DEMO_RESULTS_DIR=/data/results
-```
-
-## Programmatic Configuration
-
-```python
-from stroke_deepisles_demo.core.config import settings, reload_settings
-import os
-
-# Check current settings
-print(settings.log_level)
-
-# Override via environment
-os.environ["STROKE_DEMO_LOG_LEVEL"] = "DEBUG"
-reload_settings()
-print(settings.log_level)  # DEBUG
-```
-```
-
-## ci configuration
-
-### `.github/workflows/ci.yml`
-
-```yaml
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-
-      - name: Set up Python
-        run: uv python install 3.12
-
-      - name: Install dependencies
-        run: uv sync
-
-      - name: Lint with ruff
-        run: uv run ruff check .
-
-      - name: Check formatting
-        run: uv run ruff format --check .
-
-  typecheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-
-      - name: Set up Python
-        run: uv python install 3.12
-
-      - name: Install dependencies
-        run: uv sync
-
-      - name: Type check with mypy
-        run: uv run mypy src/
-
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-
-      - name: Set up Python
-        run: uv python install 3.12
-
-      - name: Install dependencies
-        run: uv sync
-
-      - name: Run tests
-        run: uv run pytest --cov --cov-report=xml
-
-      - name: Upload coverage
-        uses: codecov/codecov-action@v4
-        with:
-          files: ./coverage.xml
-
-  integration:
-    runs-on: ubuntu-latest
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-
-      - name: Set up Python
-        run: uv python install 3.12
-
-      - name: Install dependencies
-        run: uv sync
-
-      - name: Run integration tests
-        run: uv run pytest -m integration --timeout=600
-```
-
-## final code review checklist
-
-### code quality
-- [ ] All functions have type hints
-- [ ] All public functions have docstrings
-- [ ] No unused imports or variables
-- [ ] No hardcoded paths or secrets
-- [ ] Error messages are helpful
-
-### testing
-- [ ] Unit test coverage > 80%
-- [ ] Edge cases covered
-- [ ] Integration tests for critical paths
-- [ ] Tests are deterministic (no flakiness)
-
-### documentation
-- [ ] README is clear and accurate
-- [ ] CONTRIBUTING.md is complete
-- [ ] All configuration options documented
-- [ ] Example usage in docstrings
-
-### security
-- [ ] No secrets in code
-- [ ] HF_TOKEN is optional and hidden from logs
-- [ ] Docker commands are properly escaped
-- [ ] No arbitrary code execution vulnerabilities
-
-### production readiness
-- [ ] Logging is consistent and useful
-- [ ] Errors are handled gracefully
-- [ ] Configuration is environment-driven
-- [ ] CI passes on all checks
-
-## tdd plan
-
-### tests for logging
-
-```python
-"""Tests for logging configuration."""
-
-from __future__ import annotations
-
-import logging
-
-from stroke_deepisles_demo.core.logging import get_logger, setup_logging
-
-
-class TestSetupLogging:
-    """Tests for setup_logging."""
-
-    def test_sets_log_level(self) -> None:
-        """Sets the root logger level."""
-        setup_logging("DEBUG")
-        assert logging.getLogger().level == logging.DEBUG
-
-    def test_format_styles(self) -> None:
-        """Different format styles work."""
-        for style in ["simple", "detailed", "json"]:
-            setup_logging("INFO", format_style=style)
-            # Should not raise
-
-
-class TestGetLogger:
-    """Tests for get_logger."""
-
-    def test_returns_namespaced_logger(self) -> None:
-        """Returns logger with stroke_demo prefix."""
-        logger = get_logger("my_module")
-        assert logger.name == "stroke_demo.my_module"
-```
-
-### tests for configuration
-
-```python
-"""Tests for configuration."""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-import pytest
-
-from stroke_deepisles_demo.core.config import Settings, reload_settings
-
-
-class TestSettings:
-    """Tests for Settings."""
-
-    def test_default_values(self) -> None:
-        """Has sensible defaults."""
-        settings = Settings()
-        assert settings.log_level == "INFO"
-        assert settings.hf_dataset_id == "YongchengYAO/ISLES24-MR-Lite"
-
-    def test_env_override(self, monkeypatch) -> None:
-        """Environment variables override defaults."""
-        monkeypatch.setenv("STROKE_DEMO_LOG_LEVEL", "DEBUG")
-        settings = Settings()
-        assert settings.log_level == "DEBUG"
-
-    def test_hf_token_hidden_from_repr(self) -> None:
-        """HF token is not visible in repr."""
-        settings = Settings(hf_token="secret123")
-        assert "secret123" not in repr(settings)
-
-    def test_results_dir_created(self, tmp_path: Path) -> None:
-        """Results directory is created if it doesn't exist."""
-        new_dir = tmp_path / "new_results"
-        settings = Settings(results_dir=new_dir)
-        assert new_dir.exists()
-```
-
-## "done" criteria
-
-Phase 5 is complete when:
-
-1. Structured logging is in place throughout
-2. All settings are configurable via environment
-3. README.md and CONTRIBUTING.md are complete
-4. Developer guides are written
-5. CI workflow passes on GitHub Actions
-6. Code coverage > 80% overall
-7. All code review checklist items pass
-8. Repository is ready for others to contribute
-
-## final deliverables
-
-At the end of all phases, the repository contains:
-
-```
-stroke-deepisles-demo/
-├── .github/
-│   └── workflows/
-│       └── ci.yml
-├── docs/
-│   ├── specs/
-│   ├── guides/
-│   └── reference/
-├── src/
-│   └── stroke_deepisles_demo/
-│       ├── core/
-│       ├── data/
-│       ├── inference/
-│       ├── ui/
-│       ├── pipeline.py
-│       ├── metrics.py
-│       └── cli.py
-├── tests/
-├── pyproject.toml
-├── uv.lock
-├── README.md
-├── CONTRIBUTING.md
-├── CHANGELOG.md
-├── .pre-commit-config.yaml
-├── .gitignore
-├── .env.example
-└── app.py                  # HF Spaces entry point
-```

docs/specs/archive/07-hf-spaces-deployment.md

@@ -1,969 +0,0 @@
-# spec: hugging face spaces + gradio deployment
-
-> **Version**: December 2025
-> **Status**: APPROVED - Ready for Implementation
-> **Last Updated**: 2025-12-05
-> **Verified**: Cold start claims, pause/restart behavior, ZeroGPU limitations
-
-## important: gradio 6 is now available
-
-As of December 2025, **Gradio 6.0.2** is the latest stable release. Our `pyproject.toml` currently specifies `gradio>=5.0.0`, which will install Gradio 6.x.
-
-**Key breaking changes affecting our codebase:**
-
-| Change | Impact | Our Code |
-|--------|--------|----------|
-| `theme`, `css`, `js` moved from `Blocks()` to `launch()` | HIGH | `app.py:111` uses `gr.Blocks()`, `app.py:170` passes theme to `launch()` - **OK** |
-| `gr.HTML` padding default `True` → `False` | LOW | No visual impact expected |
-| Chatbot tuple format removed | NONE | We don't use Chatbot |
-| `show_api` → `footer_links` | LOW | We don't customize this |
-
-**Recommendation**: Pin to `gradio>=6.0.0,<7.0.0` for stability, or test with latest and update as needed.
-
-**Migration guide**: [Gradio 6 Migration Guide](https://www.gradio.app/main/guides/gradio-6-migration-guide)
-
----
-
-## purpose
-
-This spec documents the requirements, constraints, and best practices for deploying the `stroke-deepisles-demo` Gradio application to Hugging Face Spaces. It identifies potential friction points between our current implementation and HF Spaces constraints, providing concrete guidance before deployment.
-
-## executive summary
-
-### critical friction points identified
-
-| Issue | Severity | Current State | Fix Required |
-|-------|----------|---------------|--------------|
-| **NVIDIA GPU required** | HIGH | DeepISLES needs CUDA | Use Docker SDK + GPU on HF Spaces |
-| **JavaScript in `gr.HTML`** | HIGH | `<script type="module">` in viewer.py | May not execute; needs `js=` param pattern |
-| **Git dependency in pyproject.toml** | MEDIUM | `datasets @ git+https://...` | Needs `requirements.txt` with git URL |
-| **Large NIfTI files as base64** | MEDIUM | Full file loaded to memory | Should be fine with GPU tier RAM |
-| **NiiVue version** | LOW | Currently 0.57.0 in viewer.py | Update to **0.65.0** (latest) |
-
-### deployment strategy
-
-> **Important**: DeepISLES requires NVIDIA GPU with CUDA. There is no CPU-only or Apple Silicon option. "Demo mode" with pre-computed results was rejected as it defeats the purpose of a real inference demo.
-
-### Primary: Local NVIDIA GPU
-- Develop and test locally with your NVIDIA GPU
-- Free, unlimited, real inference
-- Works on Windows/Linux with NVIDIA GPU (GTX 1080+, RTX series)
-
-### Showcase: HF Spaces Docker SDK + GPU (On-Demand)
-- Use `sdk: docker` with GPU hardware
-- **Spin up** when demoing, **pause** when done
-- Cost: ~$0.20-$0.40 per 30-60 min demo session
-- Billing stops when paused ($0 while inactive)
-
----
-
-## critical: cold start reality
-
-> ⚠️ **OPERATIONAL MANDATE**: Always run `api.restart_space()` **20-30 minutes** before a scheduled demo. Verify the Space is "Running" before sharing your screen.
-
-### verified cold start times (december 2025)
-
-| Phase | Time | Source |
-|-------|------|--------|
-| HF Infrastructure boot | ~2 minutes | [HF Forums](https://discuss.huggingface.co/t/slow-space-cold-boot/72154) |
-| Docker image provision | 5-20 minutes | Large images (CUDA + nnU-Net ~15-20GB) |
-| Application startup | 1-5 minutes | Gradio + model loading |
-| **Total (best case)** | **8-12 minutes** | Normal conditions |
-| **Total (worst case)** | **30-60+ minutes** | Resource contention, Feb 2025 T4 issues |
-
-**Sources**: [T4 startup 45+ min issue (Feb 2025)](https://discuss.huggingface.co/t/staring-up-t4-instances-is-taking-45-minutes/139567), [Cold boot discussion](https://discuss.huggingface.co/t/slow-space-cold-boot/72154)
-
-### why cold start is unavoidable
-
-From HF Staff (forum moderator):
-> "avoiding a cold start here is not possible"
-
-The ~2-minute infrastructure delay is inherent to HF Spaces architecture. Docker GPU Spaces add additional time for image provisioning and GPU allocation.
-
-### deployment risks (edge cases)
-
-| Risk | Frequency | Mitigation |
-|------|-----------|------------|
-| Space stuck in "Starting" | Rare | Factory rebuild, contact HF support |
-| Space stuck in "Paused" | Rare | Wait + retry, contact HF support |
-| Build timeout (30-45 min limit) | Possible | Optimize Dockerfile, cache layers |
-| GPU unavailable (resource contention) | Rare | Try again later, different hardware tier |
-
-**Sources**: [Space stuck at Starting (Nov 2025)](https://discuss.huggingface.co/t/hf-space-stuck-at-starting/170911), [Space stuck in Paused (Oct 2025)](https://discuss.huggingface.co/t/space-stuck-in-paused/169467)
-
-### pre-demo warm-up procedure
-
-```bash
-# 20-30 minutes before your demo:
-
-# 1. Restart the Space
-python -c "
-from huggingface_hub import HfApi
-api = HfApi()
-api.restart_space('YOUR_USERNAME/stroke-deepisles-demo')
-print('Space restart initiated...')
-"
-
-# 2. Monitor status (check every 2 min)
-python -c "
-from huggingface_hub import HfApi
-api = HfApi()
-info = api.space_info('YOUR_USERNAME/stroke-deepisles-demo')
-print(f'Status: {info.runtime.stage}')  # Should be 'RUNNING'
-"
-
-# 3. Only proceed when status = RUNNING
-```
-
-### contingency plan if cold start fails
-
-1. **Space stuck in "Starting" > 30 min**:
-   - Try "Factory rebuild" from Space Settings
-   - If still stuck, contact HF support via [Discord](https://discord.gg/hugging-face-879548962464493619)
-
-2. **Demo starts before Space is ready**:
-   - Show local demo on your NVIDIA GPU machine instead
-   - "Let me show you on my development machine while the cloud version warms up"
-
-3. **GPU unavailable error**:
-   - Try `a10g-small` instead of `t4-small` (different GPU pool)
-   - Wait 15 minutes and retry
-
----
-
-## zerogpu: why it doesn't work for us
-
-ZeroGPU offers free, dynamic GPU allocation on H200 GPUs. However:
-
-| Requirement | ZeroGPU | Our Need |
-|-------------|---------|----------|
-| SDK Support | Gradio SDK only | Docker SDK (for DeepISLES container) |
-| Docker containers | ❌ NOT supported | ✅ Required |
-| Custom CUDA environment | ❌ NOT supported | ✅ Required (nnU-Net) |
-
-**Source**: [ZeroGPU Documentation](https://huggingface.co/docs/hub/en/spaces-zerogpu), [Community request for Docker support](https://huggingface.co/spaces/zero-gpu-explorers/README/discussions/27)
-
-**Verdict**: ZeroGPU is incompatible with DeepISLES. We must use Docker SDK + paid GPU hardware.
-
----
-
-## hugging face spaces constraints
-
-### sdk options
-
-| SDK | Use Case | Docker Access | GPU Support |
-|-----|----------|---------------|-------------|
-| `gradio` | Standard Gradio apps | **NO** | Via hardware upgrade |
-| `docker` | Custom containers | **YES** | Via hardware upgrade |
-| `static` | HTML/JS only | **NO** | N/A |
-
-**Key insight**: The Gradio SDK **cannot run Docker containers**. Our pipeline requires the DeepISLES Docker image, creating a fundamental incompatibility.
-
-### hardware tiers
-
-| Tier | vCPU | RAM | Cost | GPU |
-|------|------|-----|------|-----|
-| cpu-basic (free) | 2 | 16GB | $0 | None |
-| cpu-upgrade | 8 | 32GB | $0.03/hr | None |
-| t4-small | 4 | 15GB | $0.40/hr | T4 (16GB) |
-| t4-medium | 8 | 30GB | $0.60/hr | T4 (16GB) |
-| a10g-small | 4 | 15GB | $1.05/hr | A10G (24GB) |
-| a10g-large | 12 | 46GB | $3.15/hr | A10G (24GB) |
-
-**Source**: [Hugging Face Spaces GPU Upgrades](https://huggingface.co/docs/hub/spaces)
-
-### storage limits
-
-| Type | Limit | Behavior |
-|------|-------|----------|
-| Ephemeral (root fs) | 50GB | Lost on restart |
-| Persistent (`/data`) | 20GB-1TB | Paid tiers ($5-$100/mo) |
-| Build cache | Varies | Can cause "storage limit exceeded" |
-
-**Best practice**: Set `HF_HOME=/data/.huggingface` to cache models in persistent storage.
-
-> ⚠️ **Important**: `HF_HOME` must be set in the Space's **Settings → Repository secrets** UI, not just in code. Environment variables set only in Python code won't persist across container restarts.
-
-**Source**: [Spaces Persistent Storage](https://huggingface.co/docs/hub/en/spaces-storage)
-
-### build limits
-
-| Limit | Value | Notes |
-|-------|-------|-------|
-| Build timeout | 30-45 minutes | Large dependencies may fail |
-| Build cache | Part of 50GB ephemeral | Can cause "storage limit exceeded" |
-| Startup timeout | 30 minutes (default) | Configurable via `startup_duration_timeout` |
-| Idle sleep | 48 hours | Free Spaces sleep after inactivity |
-
-**Warning**: Heavy scientific stacks (PyTorch, large C extensions) may hit build timeout. Monitor build logs closely.
-
----
-
-## gradio 6 constraints (december 2025)
-
-> **Note**: Gradio 6.0 was released in late November 2025. Our codebase was written for Gradio 5.x but is largely compatible.
-
-### key breaking changes from gradio 5 → 6
-
-| Change | Gradio 5.x | Gradio 6.x | Our Status |
-|--------|------------|------------|------------|
-| Theme/CSS/JS placement | `gr.Blocks(theme=..., css=..., js=...)` | `demo.launch(theme=..., css=..., js=...)` | ✅ Already correct in `app.py:170` |
-| HTML padding default | `padding=True` | `padding=False` | ⚠️ Minor visual change |
-| Chatbot message format | Tuple `[["user", "bot"]]` | Dict `{"role": ..., "content": ...}` | N/A - Not used |
-| `show_api` parameter | `show_api=True/False` | `footer_links=["api", "gradio", "settings"]` | N/A - Not customized |
-| Event `api_name=False` | `api_name=False` | `api_visibility="private"` | N/A - Not used |
-
-### new in gradio 6
-
-1. **Custom Web Components**: Write custom components in pure HTML/JS inline in Python via `gradio cc`
-2. **Vibe Mode**: `gradio --vibe app.py` for AI-assisted app editing
-3. **Performance**: Significantly lighter and faster
-4. **Security**: Trail of Bits audit improvements carried forward
-5. **Server-Side Rendering (SSR)**: Faster initial loads, better SEO
-
-> ⚠️ **SSR Consideration**: With SSR enabled, JavaScript that references `window` or `document` may fail during server-side render. Ensure NiiVue initialization checks `typeof window !== 'undefined'` before accessing browser APIs.
-
-### javascript execution in `gr.HTML`
-
-**CRITICAL ISSUE**: The `gr.HTML` component does **not** execute JavaScript in `<script>` tags in the standard way.
-
-#### current implementation (viewer.py:262-324)
-
-```python
-def create_niivue_html(...) -> str:
-    return f"""
-    <div style="width:100%; height:{height}px; ...">
-        <canvas id="niivue-canvas" style="width:100%; height:100%;"></canvas>
-    </div>
-    <script type="module">
-        const niivueModule = await import('https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js');
-        // ... NiiVue initialization
-    </script>
-    """
-```
-
-#### the problem
-
-From the [Gradio documentation](https://www.gradio.app/guides/custom-CSS-and-JS) and [HF Forums](https://discuss.huggingface.co/t/gradio-html-component-with-javascript-code-dont-work/37316):
-
-> "The `gr.HTML` component doesn't support loading scripts via traditional `<script>` tags. This prevents JavaScript functions from being accessible to inline event handlers."
-
-#### recommended fix
-
-Use `gr.Blocks(js=...)` or `demo.load(_js=...)` to inject JavaScript:
-
-```python
-NIIVUE_INIT_JS = """
-async () => {
-    // Wait for NiiVue module to load
-    const niivueModule = await import('https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js');
-    globalThis.Niivue = niivueModule.Niivue;
-}
-"""
-
-def create_app() -> gr.Blocks:
-    with gr.Blocks(js=NIIVUE_INIT_JS) as demo:
-        # ... components
-
-    return demo
-```
-
-Then in the HTML component, reference the global:
-
-```python
-def create_niivue_html(volume_url: str, ...) -> str:
-    return f"""
-    <div id="niivue-container-{uuid}" style="...">
-        <canvas id="niivue-canvas-{uuid}"></canvas>
-    </div>
-    <script>
-        (async function() {{
-            if (typeof globalThis.Niivue === 'undefined') {{
-                console.error('NiiVue not loaded');
-                return;
-            }}
-            const nv = new globalThis.Niivue({{...}});
-            await nv.attachTo('niivue-canvas-{uuid}');
-            // ...
-        }})();
-    </script>
-    """
-```
-
-**Note**: Even this may not work reliably. Testing on HF Spaces is required.
-
-#### alternative: gradio custom components (`gradio cc`)
-
-For production deployments, Gradio 6 supports first-class **Custom Components** via the `gradio cc` CLI. This is the recommended "production" solution (vs. the `js=` hack for MVP).
-
-```bash
-# Create a NiiVue custom component
-gradio cc create NiiVueViewer --template HTML
-
-# Development server with hot reload
-gradio cc dev
-
-# Build for distribution
-gradio cc build
-
-# Publish to PyPI and HF Spaces
-gradio cc publish
-```
-
-**Pros**:
-- First-class support, proper state management
-- No hacky string interpolation
-- Reusable across projects
-
-**Cons**:
-- Requires Node.js build step
-- Higher complexity than `js=` parameter
-- Overkill for MVP
-
-**Source**: [Custom Components In Five Minutes](https://www.gradio.app/guides/custom-components-in-five-minutes)
-
-#### alternative: `gradio-iframe` component
-
-The [`gradio-iframe`](https://pypi.org/project/gradio-iframe/) package (v0.0.10) provides an iframe component that may execute JavaScript more reliably:
-
-```python
-from gradio_iframe import iFrame
-
-viewer = iFrame(
-    value="<html>...NiiVue code...</html>",
-    label="NiiVue Viewer"
-)
-```
-
-**Warning**: This is experimental and "not fully tested" per the maintainer. Use with caution.
-
-### css restrictions
-
-Custom CSS should use `elem_id` and `elem_classes` rather than query selectors:
-
-> "The use of query selectors in custom JS and CSS is not guaranteed to work across Gradio versions as the Gradio HTML DOM may change."
-
-**Source**: [Custom CSS and JS Guide](https://www.gradio.app/guides/custom-CSS-and-JS)
-
-### security (gradio 5 audit, inherited by v6)
-
-The Trail of Bits security audit was performed on **Gradio 5.0**. All fixes are inherited by Gradio 6.x:
-
-- **CVE-2024-47872**: XSS via HTML/JS/SVG file uploads (fixed in 5.0.0)
-- File type restrictions enforced server-side
-- Our app uses `gradio>=6.0.0` - we're covered
-
-> **Note**: There was no separate Gradio 6 audit. The security improvements from Gradio 5 persist in v6.
-
-**Source**: [A Security Review of Gradio 5](https://huggingface.co/blog/gradio-5-security)
-
----
-
-## readme.md yaml configuration
-
-### required fields for gradio spaces
-
-```yaml
----
-title: Stroke DeepISLES Demo
-emoji: 🧠
-colorFrom: blue
-colorTo: purple
-sdk: gradio
-sdk_version: "6.0.2"  # Latest stable as of Dec 2025
-python_version: "3.11"
-app_file: app.py
-pinned: false
-license: mit
-short_description: "Ischemic stroke lesion segmentation using DeepISLES"
-
-# Optional but recommended
-models:
-  - isleschallenge/deepisles  # If we reference it
-datasets:
-  - YongchengYAO/ISLES24-MR-Lite
-tags:
-  - medical-imaging
-  - stroke
-  - segmentation
-  - neuroimaging
-  - niivue
-
-# For CPU-only demo mode
-suggested_hardware: cpu-basic
-
-# If we need cross-origin isolation (e.g., SharedArrayBuffer)
-# custom_headers:
-#   cross-origin-embedder-policy: require-corp
-#   cross-origin-opener-policy: same-origin
----
-```
-
-### configuration reference
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `sdk` | string | `gradio`, `docker`, or `static` |
-| `sdk_version` | string | Gradio version (e.g., "5.0.0") |
-| `python_version` | string | Python version (e.g., "3.11") |
-| `app_file` | string | Entry point (default: `app.py`) |
-| `suggested_hardware` | string | Hardware for duplicators |
-| `disable_embedding` | bool | Prevent iframe embedding |
-| `custom_headers` | dict | COEP/COOP/CORP headers |
-
-**Source**: [Spaces Configuration Reference](https://huggingface.co/docs/hub/en/spaces-config-reference)
-
----
-
-## dependencies
-
-### requirements.txt for hf spaces
-
-HF Spaces uses `requirements.txt`, not `pyproject.toml` for dependency installation.
-
-```text
-# requirements.txt for HF Spaces
-
-# Core - Tobias's fork with BIDS + NIfTI lazy loading
-git+https://github.com/CloseChoice/datasets.git@feat/bids-loader-streaming-upload-fix
-
-# HuggingFace
-huggingface-hub>=0.25.0
-
-# NIfTI handling
-nibabel>=5.2.0
-numpy>=1.26.0
-
-# Configuration
-pydantic>=2.5.0
-pydantic-settings>=2.1.0
-
-# UI - Gradio 6.x (latest stable as of Dec 2025)
-gradio>=6.0.0,<7.0.0
-matplotlib>=3.8.0
-
-# Networking
-requests>=2.0.0
-```
-
-### potential issues
-
-1. **Git dependencies**: HF Spaces supports `git+https://...` in requirements.txt
-2. **C extensions**: nibabel/numpy compile fine on HF Spaces
-3. **Size**: No bloated dependencies (no PyTorch required for demo mode)
-
----
-
-## deployment paths
-
-### hardware requirements
-
-| Component | Requirement | Notes |
-|-----------|-------------|-------|
-| GPU | NVIDIA with CUDA 11.3+ | **Mandatory** - no CPU/MPS fallback |
-| VRAM | 4GB minimum, 12GB+ recommended | For parallel processing |
-| Docker | Docker + nvidia-container-toolkit | Required for DeepISLES |
-| Python | 3.8+ (3.11 recommended) | Per project config |
-
-> ⚠️ **Apple Silicon (M1/M2/M3) is NOT supported.** DeepISLES requires NVIDIA CUDA.
-
-### path 1: local nvidia gpu (primary development)
-
-For day-to-day development and testing on your own NVIDIA GPU machine.
-
-```bash
-# 1. Ensure Docker + nvidia-container-toolkit installed
-docker run --rm --gpus all nvidia/cuda:11.3-base nvidia-smi
-
-# 2. Pull DeepISLES image
-docker pull isleschallenge/deepisles
-
-# 3. Run the app
-uv run python -m stroke_deepisles_demo.ui.app
-```
-
-**Pros**:
-- Free (you own the hardware)
-- Fast iteration
-- No network dependency
-
-**Cons**:
-- Requires NVIDIA GPU hardware
-
-### path 2: hf spaces docker sdk + gpu (on-demand demos)
-
-For showcasing to others. Spin up when needed, pause when done.
-
-#### dockerfile for hf spaces
-
-```dockerfile
-# Dockerfile for HF Spaces
-# CRITICAL: DeepISLES code lives at /app/src/ in the base image.
-# We install our demo at /home/user/demo to avoid overwriting DeepISLES.
-FROM isleschallenge/deepisles:latest
-
-# HF Spaces runs containers with user ID 1000
-RUN useradd -m -u 1000 user 2>/dev/null || true
-
-# IMPORTANT: Use /home/user/demo for our app, NOT /app
-WORKDIR /home/user/demo
-
-# Add our application
-COPY --chown=1000:1000 requirements.txt /home/user/demo/requirements.txt
-RUN pip install --no-cache-dir -r requirements.txt
-
-COPY --chown=1000:1000 pyproject.toml /home/user/demo/pyproject.toml
-COPY --chown=1000:1000 src/ /home/user/demo/src/
-COPY --chown=1000:1000 app.py /home/user/demo/app.py
-RUN pip install --no-cache-dir --no-deps -e .
-
-# Environment variables for HF Spaces + direct invocation
-ENV HF_SPACES=1
-ENV DEEPISLES_DIRECT_INVOCATION=1
-ENV DEEPISLES_PATH=/app
-
-USER user
-EXPOSE 7860
-ENTRYPOINT []
-CMD ["python", "-m", "stroke_deepisles_demo.ui.app"]
-```
-
-#### readme.md configuration
-
-```yaml
----
-title: Stroke DeepISLES Demo
-emoji: 🧠
-colorFrom: blue
-colorTo: purple
-sdk: docker
-app_port: 7860
-suggested_hardware: t4-small
-pinned: false
-license: mit
----
-```
-
-#### cost management: pause/restart api
-
-```python
-from huggingface_hub import HfApi
-
-api = HfApi()
-SPACE_ID = "your-username/stroke-deepisles-demo"
-
-# PAUSE - stops billing immediately
-api.pause_space(SPACE_ID)
-
-# RESTART - spin up for demo
-api.restart_space(SPACE_ID)
-
-# AUTO-SLEEP after 30 min inactivity
-api.set_space_sleep_time(SPACE_ID, sleep_time=1800)
-```
-
-#### billing breakdown
-
-| State | Billed? | How to Enter |
-|-------|---------|--------------|
-| Running | ✅ $0.40/hr (T4) | `restart_space()` or visitor wakes it |
-| Sleeping | ❌ $0 | Auto after `sleep_time` inactivity |
-| Paused | ❌ $0 | `pause_space()` - only owner can restart |
-
-**Typical demo session**: 30-60 minutes = **$0.20-$0.40**
-
-**Monthly cost if paused**: **$0.00**
-
----
-
-## niivue integration analysis
-
-### current implementation
-
-Our viewer uses NiiVue loaded from unpkg CDN with base64 data URLs:
-
-```python
-# viewer.py:289-324
-return f"""
-<div style="width:100%; height:{height}px; ...">
-    <canvas id="niivue-canvas" style="width:100%; height:100%;"></canvas>
-</div>
-<script type="module">
-    const niivueModule = await import('https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js');
-    const Niivue = niivueModule.Niivue;
-    // ...
-    await nv.loadVolumes(volumes);
-</script>
-"""
-```
-
-### potential issues
-
-1. **Script execution**: `<script type="module">` may not execute in `gr.HTML`
-2. **Canvas element IDs**: Hardcoded `id="niivue-canvas"` will conflict if multiple viewers
-3. **CSP headers**: External CDN might be blocked by Content Security Policy
-4. **Memory**: Base64 NIfTI files loaded entirely into browser memory
-
-### recommended fixes
-
-```python
-import uuid
-
-def create_niivue_html(volume_url: str, mask_url: str | None = None, *, height: int = 400) -> str:
-    """Create HTML/JS for NiiVue viewer with unique IDs."""
-    canvas_id = f"niivue-canvas-{uuid.uuid4().hex[:8]}"
-
-    # ... rest of implementation with unique canvas_id
-```
-
-### webgl compatibility
-
-NiiVue requires WebGL2. Most modern browsers support it, but:
-
-- HF Spaces renders in iframes
-- Some iframe security policies restrict WebGL
-- Cross-origin isolation may be needed for SharedArrayBuffer
-
-**Test required**: Verify NiiVue WebGL works in HF Spaces iframe environment.
-
----
-
-## memory and performance
-
-### memory considerations
-
-| Resource | Size | Concern |
-|----------|------|---------|
-| DWI NIfTI (ISLES24-MR-Lite) | ~2-5 MB | Low |
-| Base64 encoded | ~3-7 MB | ~1.33x overhead |
-| Multiple volumes in browser | ~15-20 MB | Moderate |
-| Matplotlib figures | ~1-5 MB | Low |
-| Free tier RAM | 16 GB | Sufficient |
-
-### optimization strategies
-
-1. **Lazy loading**: Don't load all cases at startup
-2. **Cleanup**: Clear matplotlib figures after rendering
-3. **Pagination**: Limit case dropdown to reasonable number
-4. **Compression**: NIfTI files are already gzipped
-
----
-
-## testing checklist
-
-Before deploying to HF Spaces, verify:
-
-### local testing
-
-- [ ] `uv run python app.py` launches without errors
-- [ ] Case dropdown populates
-- [ ] NiiVue viewer renders (in browser, not headless)
-- [ ] Matplotlib plots display correctly
-- [ ] No import-time side effects (network calls)
-
-### hf spaces testing
-
-- [ ] Create private Space first
-- [ ] Verify dependencies install
-- [ ] Check JavaScript execution in `gr.HTML`
-- [ ] Test NiiVue WebGL rendering
-- [ ] Monitor memory usage
-- [ ] Test on mobile browsers (if applicable)
-
-### known issues to monitor
-
-1. **Startup timeout**: Default is 30 minutes, may need adjustment
-2. **Sleep behavior**: Free Spaces sleep after 48h of inactivity
-3. **Build cache**: May cause "storage limit exceeded"
-
----
-
-## deployment procedure
-
-### step 1: verify local nvidia gpu setup
-
-```bash
-# Verify NVIDIA driver and Docker GPU support
-docker run --rm --gpus all nvidia/cuda:11.3-base nvidia-smi
-
-# Pull DeepISLES image
-docker pull isleschallenge/deepisles
-
-# Test local inference
-uv run stroke-demo run --case sub-stroke0001
-```
-
-### step 2: create dockerfile for hf spaces
-
-```dockerfile
-# Dockerfile
-# CRITICAL: DeepISLES code lives at /app/src/ in the base image.
-# We install our demo at /home/user/demo to avoid overwriting DeepISLES.
-FROM isleschallenge/deepisles:latest
-
-# HF Spaces runs containers with user ID 1000
-RUN useradd -m -u 1000 user 2>/dev/null || true
-
-# IMPORTANT: Use /home/user/demo for our app, NOT /app
-WORKDIR /home/user/demo
-
-# Install additional dependencies
-COPY --chown=1000:1000 requirements.txt /home/user/demo/requirements.txt
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Copy application code
-COPY --chown=1000:1000 pyproject.toml /home/user/demo/pyproject.toml
-COPY --chown=1000:1000 src/ /home/user/demo/src/
-COPY --chown=1000:1000 app.py /home/user/demo/app.py
-RUN pip install --no-cache-dir --no-deps -e .
-
-# Environment variables for HF Spaces + direct invocation
-ENV HF_SPACES=1
-ENV DEEPISLES_DIRECT_INVOCATION=1
-ENV DEEPISLES_PATH=/app
-
-USER user
-EXPOSE 7860
-ENTRYPOINT []
-CMD ["python", "-m", "stroke_deepisles_demo.ui.app"]
-```
-
-### step 3: create requirements.txt
-
-```bash
-cat > requirements.txt << 'EOF'
-git+https://github.com/CloseChoice/datasets.git@feat/bids-loader-streaming-upload-fix
-huggingface-hub>=0.25.0
-nibabel>=5.2.0
-numpy>=1.26.0
-pydantic>=2.5.0
-pydantic-settings>=2.1.0
-gradio>=6.0.0,<7.0.0
-matplotlib>=3.8.0
-requests>=2.0.0
-EOF
-```
-
-### step 4: update readme.md for docker sdk
-
-```yaml
----
-title: Stroke DeepISLES Demo
-emoji: 🧠
-colorFrom: blue
-colorTo: purple
-sdk: docker
-app_port: 7860
-suggested_hardware: t4-small
-pinned: false
-license: mit
----
-```
-
-### step 5: deploy to private space
-
-```bash
-# Create Docker Space with GPU
-huggingface-cli repo create stroke-deepisles-demo --type space --sdk docker
-
-# Push code
-git remote add space https://huggingface.co/spaces/YOUR_USERNAME/stroke-deepisles-demo
-git push space main
-```
-
-### step 6: configure cost management
-
-```python
-from huggingface_hub import HfApi
-
-api = HfApi()
-SPACE_ID = "YOUR_USERNAME/stroke-deepisles-demo"
-
-# Set auto-sleep after 30 min of inactivity
-api.set_space_sleep_time(SPACE_ID, sleep_time=1800)
-
-# After demo: pause to stop all billing
-api.pause_space(SPACE_ID)
-
-# Before next demo: restart
-api.restart_space(SPACE_ID)
-```
-
-### step 7: monitor and iterate
-
-- Check build logs (Docker builds can take 10-20 min)
-- Test inference end-to-end
-- Verify NiiVue visualization works
-- Pause Space when done testing
-
----
-
-## decision matrix
-
-| Approach | Real Inference | Cost | Complexity | Use Case |
-|----------|----------------|------|------------|----------|
-| Local NVIDIA GPU | ✅ | $0 | Low | **Primary development** |
-| HF Spaces Docker + GPU (on-demand) | ✅ | ~$0.40/demo | Medium | **Showcasing to others** |
-| ~~Demo Mode (pre-computed)~~ | ❌ Fake | $0 | Low | ~~Rejected - defeats purpose~~ |
-| ~~HF Spaces Gradio SDK (free)~~ | ❌ No Docker | $0 | Low | ~~Cannot run DeepISLES~~ |
-| ~~ZeroGPU (free H200)~~ | ❌ No Docker | $0 | Low | ~~Only supports Gradio SDK~~ |
-
----
-
-## sources
-
-### official documentation
-- [Gradio Spaces](https://huggingface.co/docs/hub/en/spaces-sdks-gradio)
-- [Gradio 6 Migration Guide](https://www.gradio.app/main/guides/gradio-6-migration-guide)
-- [Custom CSS and JS](https://www.gradio.app/guides/custom-CSS-and-JS)
-- [Custom Components In Five Minutes](https://www.gradio.app/guides/custom-components-in-five-minutes)
-- [Spaces Configuration Reference](https://huggingface.co/docs/hub/en/spaces-config-reference)
-- [Spaces Persistent Storage](https://huggingface.co/docs/hub/en/spaces-storage)
-- [Manage Spaces - HF Hub](https://huggingface.co/docs/huggingface_hub/main/en/guides/manage-spaces)
-- [A Security Review of Gradio 5](https://huggingface.co/blog/gradio-5-security)
-- [Trail of Bits Gradio Audit](https://blog.trailofbits.com/2024/10/10/auditing-gradio-5-hugging-faces-ml-gui-framework/)
-- [Docker Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker)
-- [ZeroGPU Documentation](https://huggingface.co/docs/hub/en/spaces-zerogpu)
-
-### forum discussions (cold start verification)
-- [Slow Space Cold Boot](https://discuss.huggingface.co/t/slow-space-cold-boot/72154) - 2 min baseline confirmed
-- [T4 startup taking 45+ minutes](https://discuss.huggingface.co/t/staring-up-t4-instances-is-taking-45-minutes/139567) - Feb 2025 resource issues
-- [Space stuck at Starting](https://discuss.huggingface.co/t/hf-space-stuck-at-starting/170911) - Nov 2025 edge case
-- [Space stuck in Paused](https://discuss.huggingface.co/t/space-stuck-in-paused/169467) - Oct 2025 edge case
-- [ZeroGPU Docker request](https://huggingface.co/spaces/zero-gpu-explorers/README/discussions/27) - Community asking for Docker support
-- [Gradio HTML component with javascript code don't work](https://discuss.huggingface.co/t/gradio-html-component-with-javascript-code-dont-work/37316)
-
-### packages
-- [NiiVue npm package](https://www.npmjs.com/package/@niivue/niivue) - v0.65.0 (latest as of Dec 2025)
-- [gradio-iframe PyPI](https://pypi.org/project/gradio-iframe/) - v0.0.10 (experimental)
-- [DeepISLES Docker Hub](https://hub.docker.com/r/isleschallenge/deepisles)
-
----
-
-## appendix: friction points summary
-
-### high priority (must fix before deployment)
-
-1. **JavaScript execution in `gr.HTML`**
-   - Current: `<script type="module">` embedded in HTML string
-   - Risk: May not execute at all
-   - Fix: Use `gr.Blocks(js=...)` or `demo.load(_js=...)`
-   - Testing: Required on actual HF Spaces environment
-
-2. **Docker + GPU requirement**
-   - Current: Pipeline requires `isleschallenge/deepisles` container with NVIDIA GPU
-   - Risk: Gradio SDK cannot run Docker; Apple Silicon not supported
-   - Fix: Use Docker SDK with GPU hardware (on-demand billing)
-
-### medium priority (should fix)
-
-3. **Unique canvas IDs**
-   - Current: Hardcoded `id="niivue-canvas"`
-   - Risk: Multiple viewers would conflict
-   - Fix: Generate unique IDs with UUID
-
-4. **Git dependency in requirements**
-   - Current: `datasets @ git+https://...` in pyproject.toml
-   - Risk: HF Spaces uses requirements.txt
-   - Fix: Create requirements.txt with git URL
-
-### low priority (nice to have)
-
-5. **Memory optimization**
-   - Current: Full NIfTI files in base64
-   - Risk: Could hit memory limits on complex cases
-   - Fix: Implement streaming or pagination
-
-6. **CDN reliability**
-   - Current: NiiVue from unpkg.com
-   - Risk: CDN downtime affects app
-   - Fix: Consider bundling or alternative CDN
-
----
-
-## appendix: operational runbook
-
-### daily operations
-
-**After development session:**
-```bash
-# Always pause to stop billing
-python -c "
-from huggingface_hub import HfApi
-api = HfApi()
-api.pause_space('YOUR_USERNAME/stroke-deepisles-demo')
-print('Space paused - billing stopped')
-"
-```
-
-**Before scheduled demo:**
-```bash
-# T-30 minutes: Start warm-up
-python -c "
-from huggingface_hub import HfApi
-api = HfApi()
-api.restart_space('YOUR_USERNAME/stroke-deepisles-demo')
-print('Warming up... check status in 5 min')
-"
-
-# T-25, T-20, T-15, T-10, T-5 minutes: Check status
-python -c "
-from huggingface_hub import HfApi
-api = HfApi()
-info = api.space_info('YOUR_USERNAME/stroke-deepisles-demo')
-print(f'Status: {info.runtime.stage}')
-# BUILDING -> Wait
-# RUNNING_BUILDING -> Almost ready
-# RUNNING -> Ready to demo!
-"
-```
-
-**After demo:**
-```bash
-# Immediately pause to stop billing
-python -c "
-from huggingface_hub import HfApi
-api = HfApi()
-api.pause_space('YOUR_USERNAME/stroke-deepisles-demo')
-print('Demo complete - billing stopped')
-"
-```
-
-### troubleshooting
-
-| Symptom | Diagnosis | Resolution |
-|---------|-----------|------------|
-| Status stuck on "BUILDING" > 45 min | Build timeout | Check build logs, optimize Dockerfile |
-| Status stuck on "STARTING" > 30 min | Resource issue | Factory rebuild, or try different hardware |
-| Status stuck on "PAUSED" after restart | API issue | Wait 5 min, retry, or use UI |
-| "Scheduling failure" error | GPU unavailable | Try later or different hardware tier |
-| "Storage limit exceeded" | Build cache full | Clear cache, reduce image layers |
-
-### cost tracking
-
-```bash
-# Check current month's usage
-# Visit: https://huggingface.co/settings/billing
-
-# Estimate cost per demo:
-# T4-small: $0.40/hr × 0.5 hr = $0.20 per 30-min demo
-# T4-medium: $0.60/hr × 0.5 hr = $0.30 per 30-min demo
-# A10G-small: $1.05/hr × 0.5 hr = $0.53 per 30-min demo
-```
-
----
-
-## next steps
-
-> **Status**: Spec APPROVED - Ready for implementation
-
-1. ~~Senior Review: Get approval on this spec~~ ✅ **APPROVED**
-2. **Local Testing**: Verify full pipeline on local NVIDIA GPU machine
-3. **Fix JavaScript Pattern**: Refactor NiiVue initialization for `gr.HTML`
-4. **Create Dockerfile**: Build HF Spaces Docker image based on DeepISLES
-5. **Create requirements.txt**: Generate from pyproject.toml
-6. **Deploy to Private Space**: Test Docker SDK + GPU on HF Spaces
-7. **Configure Auto-Sleep**: Set `sleep_time=1800` (30 min) to minimize costs
-8. **Pre-Demo Test**: Practice warm-up procedure (20-30 min cold start)
-9. **Demo & Pause**: Show to stakeholders, then `pause_space()` to stop billing
-10. **Public Release**: Make Space public when stable (keep paused when not demoing)

docs/specs/archive/08-bug-hf-spaces-dataset-loop.md

@@ -1,239 +0,0 @@
-# Bug Spec: HuggingFace Spaces Dataset Loading Issues
-
-**Status:** Root Causes Identified → Comprehensive Fix Ready
-**Priority:** P0 (Blocks deployment)
-**Branch:** `fix/pipeline-resource-leak`
-**Date:** 2025-12-08
-**Updated:** 2025-12-08
-
-## Executive Summary
-
-Two distinct bugs prevent the HuggingFace Spaces deployment from working:
-
-| Bug | Symptom | Root Cause | Impact | Fix |
-|-----|---------|------------|--------|-----|
-| **#1** | Dropdown never populates | PyArrow streaming bug | App hangs at startup | Pre-computed case IDs |
-| **#2** | OOM on case selection | `load_dataset()` downloads 99GB | App crashes on first use | HfFileSystem + pyarrow |
-
-Both bugs stem from fundamental incompatibilities between the `datasets` library and our 99GB parquet dataset on resource-constrained HF Spaces hardware.
-
----
-
-## Bug #1: Streaming Iteration Hang
-
-### Summary
-
-The dropdown never populates because `load_dataset(..., streaming=True)` hangs indefinitely on parquet datasets. This is a **known PyArrow bug**, not a HuggingFace datasets bug.
-
-### The Bug Chain
-
-1. **Our code** calls `load_dataset("hugging-science/isles24-stroke", streaming=True)`
-2. **HF datasets** internally uses `ParquetFileFragment.to_batches()` for streaming
-3. **PyArrow** hangs when iterating batches from parquet with partial consumption
-4. **Result:** Script hangs forever, never returns case IDs
-
-### Upstream Issues
-
-- **PyArrow Issue:** [apache/arrow#45214](https://github.com/apache/arrow/issues/45214) - Root cause
-- **HF Datasets Issue:** [huggingface/datasets#7467](https://github.com/huggingface/datasets/issues/7467) - HF tracking
-- **Status:** Open, no fix ETA
-- **Maintainer:** @lhoestq (HF datasets core dev) correctly escalated to PyArrow team
-
-### Minimal Reproduction (Pure PyArrow, no HF)
-
-```python
-import pyarrow.dataset as ds
-
-file = "test-00000-of-00003.parquet"
-with open(file, "rb") as f:
-    parquet_fragment = ds.ParquetFileFormat().make_fragment(f)
-    for record_batch in parquet_fragment.to_batches():
-        print(len(record_batch))
-        break  # ← Partial consumption causes hang
-# Script hangs here forever
-```
-
-This proves the bug is in **PyArrow's C++ layer**, not HuggingFace datasets.
-
-### Fix: Pre-computed Case ID List
-
-**Why this is professional, not hacky:**
-
-1. **ISLES24 is a static challenge dataset** - case IDs will never change
-2. **Industry standard** - many production ML systems pre-define dataset indices
-3. **Zero startup latency** - dropdown populates instantly
-4. **No network dependency** - works offline for dropdown population
-5. **Bypasses upstream bug** - doesn't depend on PyArrow fix timeline
-
----
-
-## Bug #2: Full Dataset OOM on Case Access
-
-### Summary
-
-Even after fixing Bug #1, the application would crash immediately upon selecting a case. The current `get_case()` implementation calls:
-
-```python
-# adapter.py:213
-self._hf_dataset = load_dataset(self.dataset_id, split="train")
-```
-
-This attempts to download the **entire 99GB dataset** into memory, which OOMs on HF Spaces.
-
-### Why This Wasn't Caught
-
-The bug document initially focused on the dropdown hang (Bug #1). Bug #2 would only manifest after Bug #1 was fixed and a user actually selected a case.
-
-### Investigation Results
-
-| Approach | Result | Time | Memory |
-|----------|--------|------|--------|
-| `load_dataset(..., streaming=True)` | **HANGS** | ∞ | N/A |
-| `load_dataset(...)` (full download) | **OOMs** | ~10 min | 99GB+ |
-| `HfFileSystem` + `pyarrow` (single file) | **WORKS** | 1.7s | ~50MB |
-
-### Dataset Structure Discovery
-
-Critical finding: Each case is stored in a **separate parquet file**:
-
-- **149 parquet files** named `train-00000-of-00149.parquet` through `train-00148-of-00149.parquet`
-- **Each file = one case** (~600-700MB raw data per case)
-- **Schema:** `subject_id`, `dwi`, `adc`, `lesion_mask` (NIfTI bytes stored as binary)
-
-This means we can **directly access individual cases** without loading the full dataset!
-
-### Fix: Direct Parquet Access via HfFileSystem
-
-```python
-from huggingface_hub import HfFileSystem
-import pyarrow.parquet as pq
-
-fs = HfFileSystem()
-fpath = f"datasets/{dataset_id}/data/train-{idx:05d}-of-00149.parquet"
-
-with fs.open(fpath, 'rb') as f:
-    pf = pq.ParquetFile(f)
-    table = pf.read(columns=['subject_id', 'dwi', 'adc', 'lesion_mask'])
-    # Extract ~50MB for one case in ~2 seconds
-```
-
-**Benefits:**
-- Downloads only the single case needed (~50MB vs 99GB)
-- Completes in 1.7 seconds (vs hanging or OOM)
-- No dependency on `datasets` library for data access
-- Bypasses both PyArrow streaming bug and memory constraints
-
----
-
-## Comprehensive Fix Implementation
-
-### 1. Create `constants.py` with case ID → file index mapping
-
-```python
-# src/stroke_deepisles_demo/data/constants.py
-
-# Pre-computed case IDs for ISLES24 dataset (static challenge dataset)
-# Extracted via HfFileSystem enumeration on 2025-12-08
-ISLES24_CASE_IDS: tuple[str, ...] = (
-    "sub-stroke0001", "sub-stroke0002", ..., "sub-stroke0189"
-)
-
-# Mapping from case ID to parquet file index (0-indexed)
-ISLES24_CASE_INDEX: dict[str, int] = {
-    case_id: idx for idx, case_id in enumerate(ISLES24_CASE_IDS)
-}
-```
-
-### 2. Rewrite `HuggingFaceDataset.get_case()` to use HfFileSystem
-
-Replace `load_dataset()` call with direct parquet access:
-
-```python
-def get_case(self, case_id: str | int) -> CaseFiles:
-    from huggingface_hub import HfFileSystem
-    import pyarrow.parquet as pq
-
-    idx = self._case_index[case_id]
-    fpath = f"datasets/{self.dataset_id}/data/train-{idx:05d}-of-00149.parquet"
-
-    fs = HfFileSystem()
-    with fs.open(fpath, 'rb') as f:
-        table = pq.ParquetFile(f).read(columns=['dwi', 'adc', 'lesion_mask'])
-        # Extract bytes and write to temp files...
-```
-
-### 3. Remove all `load_dataset()` calls from HuggingFace path
-
-The `datasets` library is completely bypassed for the HuggingFace workflow.
-
----
-
-## All 149 Case IDs (Extracted via HfFileSystem)
-
-```
-sub-stroke0001, sub-stroke0002, sub-stroke0003, sub-stroke0004, sub-stroke0005,
-sub-stroke0006, sub-stroke0007, sub-stroke0008, sub-stroke0009, sub-stroke0010,
-sub-stroke0011, sub-stroke0012, sub-stroke0013, sub-stroke0014, sub-stroke0015,
-sub-stroke0016, sub-stroke0017, sub-stroke0019, sub-stroke0020, sub-stroke0021,
-sub-stroke0022, sub-stroke0025, sub-stroke0026, sub-stroke0027, sub-stroke0028,
-sub-stroke0030, sub-stroke0033, sub-stroke0036, sub-stroke0037, sub-stroke0038,
-sub-stroke0040, sub-stroke0043, sub-stroke0045, sub-stroke0047, sub-stroke0048,
-sub-stroke0049, sub-stroke0052, sub-stroke0053, sub-stroke0054, sub-stroke0055,
-sub-stroke0057, sub-stroke0062, sub-stroke0066, sub-stroke0068, sub-stroke0070,
-sub-stroke0071, sub-stroke0073, sub-stroke0074, sub-stroke0075, sub-stroke0076,
-sub-stroke0077, sub-stroke0078, sub-stroke0079, sub-stroke0080, sub-stroke0081,
-sub-stroke0082, sub-stroke0083, sub-stroke0084, sub-stroke0085, sub-stroke0086,
-sub-stroke0087, sub-stroke0088, sub-stroke0089, sub-stroke0090, sub-stroke0091,
-sub-stroke0092, sub-stroke0093, sub-stroke0094, sub-stroke0095, sub-stroke0096,
-sub-stroke0097, sub-stroke0098, sub-stroke0099, sub-stroke0100, sub-stroke0101,
-sub-stroke0102, sub-stroke0103, sub-stroke0104, sub-stroke0105, sub-stroke0106,
-sub-stroke0107, sub-stroke0108, sub-stroke0109, sub-stroke0110, sub-stroke0111,
-sub-stroke0112, sub-stroke0113, sub-stroke0114, sub-stroke0115, sub-stroke0116,
-sub-stroke0117, sub-stroke0118, sub-stroke0119, sub-stroke0133, sub-stroke0134,
-sub-stroke0135, sub-stroke0136, sub-stroke0137, sub-stroke0138, sub-stroke0139,
-sub-stroke0140, sub-stroke0141, sub-stroke0142, sub-stroke0143, sub-stroke0144,
-sub-stroke0145, sub-stroke0146, sub-stroke0147, sub-stroke0148, sub-stroke0149,
-sub-stroke0150, sub-stroke0151, sub-stroke0152, sub-stroke0153, sub-stroke0154,
-sub-stroke0155, sub-stroke0156, sub-stroke0157, sub-stroke0158, sub-stroke0159,
-sub-stroke0161, sub-stroke0162, sub-stroke0163, sub-stroke0164, sub-stroke0165,
-sub-stroke0166, sub-stroke0167, sub-stroke0168, sub-stroke0169, sub-stroke0170,
-sub-stroke0171, sub-stroke0172, sub-stroke0173, sub-stroke0174, sub-stroke0175,
-sub-stroke0176, sub-stroke0177, sub-stroke0178, sub-stroke0179, sub-stroke0180,
-sub-stroke0181, sub-stroke0182, sub-stroke0183, sub-stroke0184, sub-stroke0185,
-sub-stroke0186, sub-stroke0187, sub-stroke0188, sub-stroke0189
-```
-
----
-
-## Environment
-
-- **Space:** `VibecoderMcSwaggins/stroke-deepisles-demo`
-- **Hardware:** T4-small GPU (limited memory)
-- **Dataset:** `hugging-science/isles24-stroke` (149 parquet files, ~99GB total)
-- **Dependencies:**
-  - `datasets @ git+https://github.com/CloseChoice/datasets.git@c1c15aa...` (fork with Nifti support)
-  - `pyarrow` (inherited, contains Bug #1)
-  - `huggingface_hub` (used for Bug #2 fix)
-
----
-
-## References
-
-- [PyArrow Issue #45214](https://github.com/apache/arrow/issues/45214) - Bug #1 root cause
-- [PyArrow Issue #43604](https://github.com/apache/arrow/issues/43604) - Related hang issue
-- [HF Datasets Issue #7467](https://github.com/huggingface/datasets/issues/7467) - HF tracking issue
-- [HF Datasets Issue #7357](https://github.com/huggingface/datasets/issues/7357) - Original report
-
----
-
-## Checklist
-
-1. [x] Identify Bug #1 root cause (PyArrow streaming hang)
-2. [x] Identify Bug #2 root cause (OOM on full download)
-3. [x] Extract all 149 case IDs via HfFileSystem
-4. [x] Validate direct parquet access works (1.7s per case)
-5. [x] Implement pre-computed case ID list (`constants.py`)
-6. [x] Rewrite `get_case()` to use HfFileSystem + pyarrow
-7. [x] Update tests
-8. [ ] Test on HF Spaces
-9. [ ] Monitor PyArrow issue for upstream fix

docs/specs/archive/09-bug-deepisles-not-installed-hf-spaces.md

@@ -1,92 +0,0 @@
-# Bug Spec: DeepISLES Path Conflict in Docker Build
-
-**Status:** Root Cause Found → Fix Ready
-**Priority:** P0 (Blocks inference)
-**Branch:** `fix/deepisles-docker-path`
-**Date:** 2025-12-08
-
-## Executive Summary
-
-Our Dockerfile was **overwriting DeepISLES modules** by copying our app to `/app/src/`, which is where the base image stores DeepISLES code. The fix is to install our app at `/home/user/demo` instead.
-
-## Root Cause
-
-The `isleschallenge/deepisles:latest` Docker image has this structure:
-```text
-/app/
-├── main.py
-├── requirements.txt
-├── src/                    ← DeepISLES Python modules
-│   └── isles22_ensemble.py
-└── weights/                ← Model weights (~GB)
-```
-
-Our original Dockerfile:
-```dockerfile
-FROM isleschallenge/deepisles:latest
-WORKDIR /app
-COPY src/ /app/src/         ← OVERWRITES DeepISLES modules!
-```
-
-This replaced `/app/src/isles22_ensemble.py` (DeepISLES) with `/app/src/stroke_deepisles_demo/` (our app).
-
-## The Fix
-
-1. **Changed app directory** from `/app` to `/home/user/demo`
-2. **Added `DEEPISLES_PATH=/app`** environment variable
-3. **Updated `direct.py`** to check `DEEPISLES_PATH` first
-
-### Dockerfile Changes
-```dockerfile
-# Before: WORKDIR /app
-# After:
-WORKDIR /home/user/demo
-
-# Before: COPY src/ /app/src/
-# After:
-COPY src/ /home/user/demo/src/
-
-# New:
-ENV DEEPISLES_PATH=/app
-```
-
-### direct.py Changes
-```python
-def _get_deepisles_search_paths() -> list[str]:
-    paths = []
-    # Check environment variable first (set in Dockerfile)
-    env_path = os.environ.get("DEEPISLES_PATH")
-    if env_path:
-        paths.append(env_path)
-    # Add common installation locations
-    paths.extend(["/app", "/DeepIsles", ...])
-    return paths
-```
-
-## Investigation Process
-
-1. Pulled `isleschallenge/deepisles:latest` locally
-2. Inspected WORKDIR: `/app`
-3. Listed `/app` contents: found `src/`, `weights/`, `main.py`
-4. Realized our `COPY src/ /app/src/` was overwriting DeepISLES
-
-## Files Changed
-
-- `Dockerfile` - Use `/home/user/demo`, add `DEEPISLES_PATH`
-- `src/stroke_deepisles_demo/inference/direct.py` - Dynamic search paths
-
-## Testing
-
-- All 125 unit tests pass
-- Need to test on HF Spaces to verify inference works
-
-## References
-
-- [DeepISLES GitHub](https://github.com/ezequieldlrosa/DeepIsles)
-- [Docker Hub Image](https://hub.docker.com/r/isleschallenge/deepisles)
-- [HuggingFace Docker Spaces](https://huggingface.co/docs/hub/en/spaces-sdks-docker)
-
-## Sources
-
-- [Docker Blog: Build ML Apps with HuggingFace](https://www.docker.com/blog/build-machine-learning-apps-with-hugging-faces-docker-spaces/)
-- [HuggingFace Docker Spaces Docs](https://huggingface.co/docs/hub/en/spaces-sdks-docker)

docs/specs/archive/10-bug-niivue-viewer-black-screen.md

@@ -1,418 +0,0 @@
-# Bug #10: NiiVue 3D Viewer Renders Black Screen on HF Spaces
-
-## Status: PARTIALLY FIXED → See Bug #11
-
-**Date:** 2025-12-09
-**Branch:** `fix/niivue-js-on-load` (merged), now `fix/niivue-js-rerun`
-**Discovered:** After fixing Bug #9 (DeepISLES subprocess bridge)
-
-### Fix Applied (2025-12-09) - PARTIAL
-
-Implemented `js_on_load` approach (Solution 1 from this spec):
-
-1. **`viewer.py`**: Removed `<script>` tags, added `NIIVUE_JS_ON_LOAD` constant
-2. **`components.py`**: Added `js_on_load=NIIVUE_JS_ON_LOAD` to gr.HTML
-3. **All 130 tests pass locally**
-
-The HTML now uses `data-*` attributes to pass volume URLs, and JavaScript
-executes via `js_on_load` instead of inline `<script>` tags.
-
-### Continued in Bug #11
-
-After HF Spaces deployment, we discovered that `js_on_load` **only runs once
-on component mount**, not on value updates. This means the NiiVue viewer
-initializes correctly on page load, but when `run_segmentation()` updates
-the gr.HTML value with new data-* attributes, the JS doesn't re-execute.
-
-**See [Bug #11](./11-bug-niivue-js-on-load-not-rerunning.md) for the complete
-analysis and the verified fix using `.then(fn=None, js=...)`.**
-
----
-
-## TL;DR - ROOT CAUSE
-
-**Gradio's `gr.HTML` component does NOT execute `<script>` tags (including `type="module"`).**
-
-Our code embeds NiiVue initialization JavaScript inside `<script type="module">` tags within the HTML value. Gradio intentionally ignores these for security reasons. The canvas renders but NiiVue never initializes → black screen.
-
----
-
-## Symptom
-
-After successful DeepISLES inference on HF Spaces, the NiiVue 3D viewer component (top-right panel) renders as a completely black rectangle. No brain scan or mask overlay is visible.
-
-**What IS working:**
-- DeepISLES inference completes successfully (~32 seconds)
-- Slice Comparison (matplotlib 2D view) renders correctly
-- Metrics JSON displays correctly
-- Download button provides the prediction mask
-- Ground truth overlay in Slice Comparison works
-
-**What is NOT working:**
-- NiiVue WebGL 3D viewer shows black screen
-- No error message displayed in the viewer area
-- No visible WebGL error fallback message
-
-**What SHOULD appear:**
-- Multi-planar view (axial/coronal/sagittal slices)
-- Optional 3D volume rendering
-- Interactive crosshairs for navigation
-- DWI volume as grayscale background
-- Prediction mask as semi-transparent red overlay
-
----
-
-## Root Cause Analysis
-
-### Evidence Chain
-
-1. **[HuggingFace Forum](https://discuss.huggingface.co/t/gradio-html-component-with-javascript-code-dont-work/37316)**:
-   > "You can't load scripts via `gr.HTML`"
-
-2. **[Gradio Official Docs](https://www.gradio.app/docs/gradio/html)**:
-   > "Only static HTML is rendered (e.g., no JavaScript). To render JavaScript, use the `js` or `head` parameters"
-
-3. **[Gradio 6 Migration Guide](https://www.gradio.app/main/guides/gradio-6-migration-guide)**:
-   > The `js` and `head` parameters moved from `gr.Blocks()` to `launch()` in Gradio 6
-
-4. **[GitHub Issue #10250](https://github.com/gradio-app/gradio/issues/10250)**:
-   > Known issue with JavaScript in `head` param not executing reliably
-
-### Our Code (BROKEN)
-
-```python
-# viewer.py:324-385 - Returns HTML with embedded script tags
-def create_niivue_html(volume_url, mask_url, height=400) -> str:
-    return f"""
-    <div id="{container_id}" style="...">
-        <canvas id="{canvas_id}" style="..."></canvas>
-    </div>
-    <script type="module">
-        // THIS ENTIRE BLOCK IS IGNORED BY GRADIO!
-        (async function() {{
-            const niivueModule = await import('{NIIVUE_CDN_URL}');
-            const Niivue = niivueModule.Niivue;
-            const nv = new Niivue({{...}});
-            await nv.attachToCanvas(document.getElementById('{canvas_id}'));
-            await nv.loadVolumes([{{ url: {volume_url_js} }}]);
-            // ... more initialization
-        }})();
-    </script>
-    """
-
-# components.py:42 - Basic HTML component without js_on_load
-niivue_viewer = gr.HTML(label="Interactive 3D Viewer")  # No js_on_load!
-```
-
-### Why It Fails
-
-1. `gr.HTML` receives our HTML string as `value`
-2. Gradio renders the `<div>` and `<canvas>` elements (static HTML)
-3. Gradio **strips or ignores** the `<script>` tags for security
-4. NiiVue JavaScript never executes
-5. Canvas remains empty → black screen
-6. Our try/catch error handling never runs (script doesn't execute at all)
-
----
-
-## Secondary Issues
-
-### Issue 1: Base64 Payload Size (~65MB)
-
-Even if JavaScript executed, we're passing massive base64-encoded NIfTI data:
-
-| File | Raw Size | Base64 Size |
-|------|----------|-------------|
-| DWI | 30.1 MB | ~40 MB |
-| ADC | 17.7 MB | ~24 MB |
-| **Total** | ~48 MB | **~65 MB** |
-
-This could cause:
-- Browser memory issues
-- Gradio payload limits
-- Slow/failed rendering
-
-### Issue 2: Gradio 6 Breaking Changes
-
-Our code uses Gradio 5.x patterns. In Gradio 6.x:
-- `js`, `head`, `head_paths` moved from `gr.Blocks()` to `launch()`
-- `padding` default changed from `True` to `False`
-- `js_on_load` is now the proper way for component-level JavaScript
-
-### Issue 3: No Error Visibility
-
-Our JavaScript has try/catch that should display errors in the container, but since the script never executes, the error handling never runs. The canvas just stays black with no feedback to the user.
-
----
-
-## Code Locations
-
-| File | Lines | Description |
-|------|-------|-------------|
-| `src/stroke_deepisles_demo/ui/viewer.py` | 277-385 | `create_niivue_html()` - generates broken HTML |
-| `src/stroke_deepisles_demo/ui/viewer.py` | 34-51 | `nifti_to_data_url()` - base64 encoding |
-| `src/stroke_deepisles_demo/ui/app.py` | 101-117 | NiiVue HTML generation in `run_segmentation()` |
-| `src/stroke_deepisles_demo/ui/components.py` | 41-42 | `gr.HTML` component creation (missing js_on_load) |
-
----
-
-## External Validation (2025-12-09)
-
-An external agent review claimed `js_on_load` does not exist. **This claim was REFUTED.**
-
-### Verification Results
-
-| Claim | Status | Evidence |
-|-------|--------|----------|
-| "gr.HTML does NOT have js_on_load parameter" | ❌ **REFUTED** | [Gradio Docs](https://www.gradio.app/docs/gradio/html) show `js_on_load` with default value |
-| "js_on_load was added in PR #12098" | ✅ Confirmed | Part of "gr.HTML custom components" feature |
-| "Base64 payload (~65MB) is a risk" | ✅ Confirmed | Valid concern, should use file URLs |
-| "CSP headers may block CDN" | ⚠️ Possible | HF Spaces typically allows unpkg.com, but worth testing |
-
-### Validated `js_on_load` Signature
-
-```python
-js_on_load: str | None = "element.addEventListener('click', function() { trigger('click') });"
-```
-
-**Available in js_on_load context:**
-- `element` - The HTML DOM element
-- `trigger(event_name)` - Fire Gradio events
-- `props` - Access component props including `props.value`
-
-**Untested (needs verification):**
-- Async/await patterns
-- Dynamic `import()` for CDN modules
-- Error propagation to Gradio
-
----
-
-## Proposed Solutions (Ranked)
-
-### Solution 1: Use `js_on_load` Parameter (Recommended)
-
-Gradio 6's `gr.HTML` supports `js_on_load` for component-level JavaScript (added in PR #12098):
-
-```python
-def create_niivue_component(volume_url, mask_url, height=400):
-    container_id = f"nv-{uuid.uuid4().hex[:8]}"
-
-    html_content = f'<div id="{container_id}" style="height:{height}px;background:#000;"><canvas></canvas></div>'
-
-    js_code = f"""
-        (async () => {{
-            try {{
-                const {{ Niivue }} = await import('https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js');
-                const nv = new Niivue({{ logging: false, backColor: [0,0,0,1] }});
-                await nv.attachToCanvas(element.querySelector('canvas'));
-                await nv.loadVolumes([{{ url: {json.dumps(volume_url)} }}]);
-                nv.setSliceType(nv.sliceTypeMultiplanar);
-            }} catch (e) {{
-                element.innerHTML = '<div style="color:#fff;padding:20px;">Error: ' + e.message + '</div>';
-            }}
-        }})();
-    """
-
-    return gr.HTML(
-        value=html_content,
-        js_on_load=js_code,
-        label="Interactive 3D Viewer"
-    )
-```
-
-**Pros:** Native Gradio 6 approach, component-scoped
-**Cons:** May have issues with dynamic import in js_on_load context
-
-### Solution 2: Use `head` Parameter in `launch()`
-
-Load NiiVue globally via the `head` parameter:
-
-```python
-# app.py
-NIIVUE_HEAD = '''
-<script type="module">
-    import { Niivue } from 'https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js';
-    window.Niivue = Niivue;
-</script>
-'''
-
-demo.launch(
-    head=NIIVUE_HEAD,
-    server_name="0.0.0.0",
-    server_port=7860
-)
-```
-
-**Pros:** Loads library once, available globally
-**Cons:** GitHub Issue #10250 reports unreliable execution
-
-### Solution 3: Server-Side File Serving
-
-Instead of base64 data URLs, serve NIfTI files via Gradio's file system:
-
-```python
-# Use Gradio's file URL instead of data URLs
-from gradio import FileData
-file_data = FileData(path=str(dwi_path))
-# Pass file_data.url to NiiVue instead of base64
-```
-
-**Pros:** Avoids 65MB payload, better memory efficiency
-**Cons:** Requires refactoring data flow, CORS considerations
-
-### Solution 4: Custom Gradio Component
-
-Build a proper `gradio_niivue` package:
-
-```bash
-gradio cc create NiiVue --template HTML
-# Implement Svelte frontend with NiiVue
-# Publish to PyPI
-```
-
-**Pros:** Most robust, reusable, proper architecture
-**Cons:** Significant development effort
-
-### Solution 5: Enhanced 2D Fallback (Simplest)
-
-Remove NiiVue entirely, enhance matplotlib visualization:
-
-```python
-def create_results_display():
-    with gr.Group():
-        # Remove: niivue_viewer = gr.HTML(...)
-
-        # Enhanced 2D visualization
-        slice_plot = gr.Plot(label="Multi-View Comparison")
-        slice_slider = gr.Slider(label="Slice", minimum=0, maximum=100)
-
-        # Add orthogonal views
-        with gr.Row():
-            axial_plot = gr.Plot(label="Axial")
-            coronal_plot = gr.Plot(label="Coronal")
-            sagittal_plot = gr.Plot(label="Sagittal")
-```
-
-**Pros:** Eliminates WebGL complexity, works reliably
-**Cons:** Loses 3D interactivity, less impressive demo
-
----
-
-## Investigation Steps
-
-### Step 0: Test Async/Await in js_on_load (CRITICAL)
-Before implementing Solution 1, verify async works:
-```python
-import gradio as gr
-
-with gr.Blocks() as demo:
-    html = gr.HTML(
-        value="<div>Testing async...</div>",
-        js_on_load="""
-            (async () => {
-                element.innerText = 'Async started...';
-                await new Promise(r => setTimeout(r, 1000));
-                element.innerText = 'Async works!';
-                element.style.background = 'green';
-            })();
-        """
-    )
-
-demo.launch()
-```
-
-If this shows "Async works!" with green background after 1 second, async is supported.
-
-### Step 1: Verify js_on_load Works (Basic)
-Create minimal test:
-```python
-import gradio as gr
-
-with gr.Blocks() as demo:
-    html = gr.HTML(
-        value="<div id='test'>Loading...</div>",
-        js_on_load="element.style.background='green'; element.innerText='JS Works!';"
-    )
-
-demo.launch()
-```
-
-### Step 2: Test Dynamic Import in js_on_load
-```python
-js_on_load="""
-    (async () => {
-        const mod = await import('https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js');
-        console.log('NiiVue loaded:', mod);
-        element.innerText = 'Import succeeded!';
-    })();
-"""
-```
-
-### Step 3: Check Browser Console
-1. Open HF Spaces demo
-2. Open DevTools (F12) → Console
-3. Look for errors related to:
-   - Module loading failures
-   - WebGL context issues
-   - CORS errors
-   - Memory errors
-
-### Step 4: Test with Smaller Files
-Create downsampled test NIfTI (~1MB) to isolate size vs JS issues.
-
----
-
-## Related Issues
-
-- **Bug #9**: DeepISLES modules not found (FIXED - subprocess bridge)
-- **Bug #8**: HF Spaces streaming hang (FIXED)
-- **Technical Debt**: NiiVue memory overhead (P2)
-- **[Gradio #4511](https://github.com/gradio-app/gradio/issues/4511)**: 3D medical image support request (closed, not planned)
-- **[Gradio #10250](https://github.com/gradio-app/gradio/issues/10250)**: JS in head param issues (open)
-
----
-
-## Priority Assessment
-
-**Severity:** P2 (Medium)
-- Core inference pipeline works correctly
-- 2D visualization provides adequate fallback
-- No data loss or security impact
-- Demo is functional for evaluation purposes
-
-**Impact:**
-- Less impressive without 3D viewer
-- Users can still evaluate predictions via 2D slices
-- Download functionality unaffected
-
-**Recommendation:**
-1. First, validate inference accuracy across multiple cases
-2. Then attempt Solution 1 (js_on_load) as quick fix
-3. If that fails, implement Solution 5 (enhanced 2D) for reliability
-4. Consider Solution 4 (custom component) for future enhancement
-
----
-
-## References
-
-- [Gradio HTML Docs](https://www.gradio.app/docs/gradio/html)
-- [Gradio Custom HTML Components Guide](https://www.gradio.app/guides/custom_HTML_components)
-- [Gradio 6 Migration Guide](https://www.gradio.app/main/guides/gradio-6-migration-guide)
-- [HuggingFace Forum: JS doesn't work in gr.HTML](https://discuss.huggingface.co/t/gradio-html-component-with-javascript-code-dont-work/37316)
-- [GitHub Issue #10250: JS in head param](https://github.com/gradio-app/gradio/issues/10250)
-- [GitHub Issue #4511: 3D Medical Images](https://github.com/gradio-app/gradio/issues/4511)
-- [NiiVue GitHub](https://github.com/niivue/niivue)
-- [ipyniivue (Jupyter Widget)](https://github.com/niivue/ipyniivue)
-- [Gradio 6 Announcement](https://alternativeto.net/news/2025/11/gradio-6-released-with-faster-performance-for-creating-machine-learning-apps-in-python/)
-
----
-
-## Appendix: HF Spaces Logs
-
-```text
-INFO: Running segmentation for sub-stroke0002
-INFO: Case sub-stroke0002 ready: DWI=20.9MB, ADC=12.6MB
-INFO: DeepISLES subprocess completed in 30.88s
-```
-
-Note: No JavaScript errors visible in server logs (client-side only).

docs/specs/archive/11-bug-niivue-js-on-load-not-rerunning.md

@@ -1,484 +0,0 @@
-# Bug #11: NiiVue js_on_load Doesn't Re-run on Value Update
-
-## Status: FIXED
-
-**Date:** 2025-12-09
-**Branch:** `fix/niivue-js-rerun`
-**Fixed By:** Implementing `.then(fn=None, js=NIIVUE_UPDATE_JS)` pattern with correct `document.querySelector` context.
-**Related:** Bug #10 (Fixed)
-
----
-
-## TL;DR - ROOT CAUSE
-
-**Gradio's `js_on_load` only runs ONCE when the component first mounts.**
-
-When we update the `gr.HTML` value with new content (after segmentation), the `js_on_load` code does NOT re-execute. The HTML updates, but the JavaScript initialization never runs.
-
----
-
-## Symptom
-
-After successful DeepISLES inference on HF Spaces:
-- Viewer shows "Loading viewer..." (initial HTML state)
-- Status never changes to "Checking WebGL2..." or "Loading NiiVue..."
-- No error message displayed
-- No brain scan visible
-
-**What IS working:**
-- DeepISLES inference completes (~36 seconds)
-- Slice Comparison (matplotlib 2D view) renders correctly
-- Metrics JSON displays correctly
-- Download button provides the prediction mask
-- Initial HTML renders with data-* attributes
-
-**What is NOT working:**
-- js_on_load JavaScript doesn't re-run when value updates
-- NiiVue never initializes after segmentation
-
----
-
-## Evidence
-
-### Gradio Documentation
-
-From [Custom HTML Components Guide](https://www.gradio.app/guides/custom_HTML_components):
-
-> "Event listeners attached in `js_on_load` are only attached **once** when the component is first rendered. If your component creates new elements dynamically that need event listeners, attach the event listener to a parent element..."
-
-### Observed Behavior
-
-1. Page loads → js_on_load runs → No volumeUrl → Shows "Waiting for segmentation..."
-2. User clicks "Run Segmentation"
-3. DeepISLES runs successfully
-4. `run_segmentation()` returns new HTML with data-volume-url attribute
-5. gr.HTML value updates with new HTML
-6. **js_on_load does NOT re-run** ← THE BUG
-7. Viewer shows "Loading viewer..." (static HTML, no JS executed)
-
-### Server Logs (Working)
-
-```text
-INFO: Running segmentation for sub-stroke0001
-INFO: DeepISLES subprocess completed in 35.73s
-```
-
-Inference works. The problem is client-side JavaScript execution.
-
----
-
-## Code Flow Analysis
-
-### Current Implementation (BROKEN)
-
-```python
-# components.py - js_on_load set once at component creation
-niivue_viewer = gr.HTML(
-    label="Interactive 3D Viewer",
-    js_on_load=NIIVUE_ON_LOAD_JS,  # Runs ONCE on mount
-)
-
-# app.py - returns new HTML value after segmentation
-def run_segmentation(...):
-    # ... inference ...
-    niivue_html = create_niivue_html(dwi_url, mask_url)
-    return niivue_html, ...  # Value updates, but js_on_load doesn't re-run
-```
-
-### Why It Fails
-
-1. Component mounts → js_on_load runs (no data yet)
-2. Value updates → HTML re-renders, js_on_load SKIPPED
-3. New HTML has data-* attributes but no JS execution
-
----
-
-## Proposed Solutions (Ranked)
-
-### Solution 1: Use `js` Parameter on Event Handler (Recommended)
-
-Gradio allows running JavaScript after an event completes:
-
-```python
-run_btn.click(
-    fn=run_segmentation,
-    inputs=[...],
-    outputs=[results["niivue_viewer"], ...],
-).then(
-    fn=None,  # MUST be explicit!
-    js=NIIVUE_UPDATE_JS,  # ⚠️ CANNOT reuse NIIVUE_ON_LOAD_JS - different context!
-)
-```
-
-**Pros:** Native Gradio pattern, runs after each update
-**Cons:** Requires separate JS constant (see "Different JS Context" section below)
-
-**⚠️ CRITICAL:** The `js` param does NOT have access to `element`. You must use
-`document.querySelector()` instead. See the corrected JavaScript in the
-"Recommended Implementation" section.
-
-### Solution 2: MutationObserver in js_on_load
-
-Watch for DOM changes and re-initialize. This approach IS valid because
-`js_on_load` has access to `element`:
-
-```javascript
-// In js_on_load - 'element' IS available here
-const initNiiVue = async () => {
-    const container = element.querySelector('.niivue-viewer') || element;
-    const volumeUrl = container.dataset.volumeUrl;
-    if (!volumeUrl) return;
-    // ... NiiVue initialization code ...
-};
-
-// Watch for attribute changes (when Python updates data-volume-url)
-const observer = new MutationObserver((mutations) => {
-    for (const mutation of mutations) {
-        if (mutation.type === 'attributes' &&
-            mutation.attributeName.startsWith('data-')) {
-            initNiiVue();
-            break;
-        }
-    }
-});
-
-// Observe the element for attribute changes
-observer.observe(element, {
-    attributes: true,
-    subtree: true,
-    attributeFilter: ['data-volume-url', 'data-mask-url']
-});
-
-// Initial check
-initNiiVue();
-```
-
-**Pros:** Self-contained in js_on_load, no separate event wiring needed
-**Cons:** More complex, relies on Gradio updating DOM attributes (may not work
-if Gradio replaces the entire element instead of updating attributes)
-
-### Solution 3: Use gradio-iframe Component
-
-The `gradio-iframe` package allows JavaScript to execute normally:
-
-```python
-from gradio_iframe import iFrame
-
-niivue_viewer = iFrame(
-    value=create_niivue_html_with_script(...),  # Scripts execute in iframe
-)
-```
-
-**Pros:** Scripts execute normally inside iframe
-**Cons:** Additional dependency, iframe quirks
-
-### Solution 4: Embed JS in HTML via data: URL iframe
-
-Self-contained iframe with script:
-
-```python
-def create_niivue_html(...):
-    html_with_script = f'''<script>...</script><canvas>...</canvas>'''
-    encoded = base64.b64encode(html_with_script.encode()).decode()
-    return f'<iframe src="data:text/html;base64,{encoded}"></iframe>'
-```
-
-**Pros:** No external dependency, scripts execute
-**Cons:** Complex, potential CSP issues
-
-### Solution 5: Custom Gradio Component
-
-Build a proper `gradio_niivue` Svelte component:
-
-```bash
-gradio cc create NiiVue --template HTML
-```
-
-**Pros:** Most robust, proper lifecycle hooks
-**Cons:** Significant development effort
-
----
-
-## Investigation Steps
-
-### Step 1: Test Solution 1 (js param on .then())
-
-```python
-run_btn.click(
-    fn=run_segmentation,
-    inputs=[...],
-    outputs=[...],
-).then(
-    fn=None,
-    js="console.log('then JS ran'); console.log(document.querySelector('.niivue-viewer'));"
-)
-```
-
-Verify:
-- Does `js` run after value update?
-- Does it have access to the updated DOM?
-
-### Step 2: Test Solution 2 (MutationObserver)
-
-Add observer to js_on_load and check if it triggers on value change.
-
-### Step 3: Check Browser Console
-
-Open DevTools and look for:
-- JavaScript errors
-- Console logs from js_on_load
-- Network requests to NiiVue CDN
-
----
-
-## Temporary Workaround
-
-The 2D Slice Comparison view works correctly and provides adequate visualization for evaluation purposes while we fix the 3D viewer.
-
----
-
-## Priority Assessment
-
-**Severity:** P1 (High)
-- 3D viewer is a key feature for the demo
-- The fix we deployed doesn't fully work
-- Blocks demo usability for 3D visualization
-
-**Impact:**
-- Users see "Loading viewer..." indefinitely
-- 2D fallback still works
-- Demo is partially functional
-
----
-
-## Deep Web Research (2025-12-09)
-
-### Relationship Between Bug #10 and Bug #11
-
-**They are the SAME underlying issue with two symptoms:**
-
-1. **Bug #10**: Gradio strips `<script>` tags from gr.HTML for XSS security
-2. **Bug #11**: Gradio's `js_on_load` only runs once on component mount
-
-Both stem from Gradio's design decision to limit JavaScript execution in HTML components for security reasons.
-
-### Verified Gradio Behavior (from official docs)
-
-#### js_on_load Limitation (CONFIRMED)
-
-From [Gradio Custom HTML Components](https://www.gradio.app/guides/custom_HTML_components):
-
-> "Event listeners attached in `js_on_load` are **only attached once** when the component is first rendered."
-
-#### Solution 1 VALIDATED: `.then(fn=None, js=...)`
-
-From [Gradio Custom CSS and JS](https://www.gradio.app/guides/custom-CSS-and-JS):
-
-> "You can pass both a JavaScript function and a Python function (in which case the JavaScript function is run first) or **only Javascript (and set the Python `fn` to `None`)**."
-
-**Critical Implementation Detail** from [GitHub Issue #6729](https://github.com/gradio-app/gradio/issues/6729):
-
-> "`js` without `fn` is executed only if `fn` is **explicitly** set to `None`"
-
-```python
-# WORKS
-b1.click(js=js, fn=None)
-
-# DOES NOT WORK
-b2.click(js=js)  # fn defaults to something, not None
-```
-
-#### js Parameter Signature
-
-From [Gradio HTML Docs](https://www.gradio.app/docs/gradio/html):
-
-> "The `js` parameter is an optional frontend js method to run before running 'fn'. Input arguments for js method are values of 'inputs' and 'outputs', return should be a list of values for output components."
-
-### Alternative Solutions Research
-
-#### gradio-iframe Package
-
-From [PyPI gradio-iframe](https://pypi.org/project/gradio-iframe/):
-
-- Version: 0.0.10 (Jan 2024)
-- **JavaScript executes normally inside iframe**
-- Known issues: Height doesn't always adjust, not fully responsive
-- Status: Alpha, possibly abandoned (no updates in 12 months)
-- **Risk:** May not be compatible with Gradio 6.x
-
-#### MutationObserver Pattern
-
-From [MDN MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver):
-
-MutationObserver can watch for DOM changes and trigger re-initialization:
-
-```javascript
-const observer = new MutationObserver((mutations) => {
-    mutations.forEach((mutation) => {
-        if (mutation.type === 'attributes' &&
-            mutation.attributeName === 'data-volume-url') {
-            initNiiVue();
-        }
-    });
-});
-observer.observe(element, { attributes: true, attributeFilter: ['data-volume-url'] });
-```
-
-**Caveat from Gradio docs:**
-
-> "Warning: The use of query selectors in custom JS and CSS is not guaranteed to work across Gradio versions that bind to Gradio's own HTML elements as the Gradio HTML DOM may change."
-
-#### ipyniivue (Jupyter Widget)
-
-From [GitHub ipyniivue](https://github.com/niivue/ipyniivue):
-
-- Built on anywidget framework
-- Designed for Jupyter, not Gradio
-- No direct Gradio integration exists
-
-### Recommended Implementation
-
-Based on research, **Solution 1 (`.then(fn=None, js=...)`) is the correct fix**.
-
-#### Step 1: Create a NEW JavaScript constant for event handlers
-
-We **CANNOT** reuse `NIIVUE_ON_LOAD_JS` because it uses `element` which is not
-available in the event handler context. We need a new constant:
-
-```python
-# viewer.py - NEW constant for event handler context
-NIIVUE_UPDATE_JS = f"""
-(async () => {{
-    // ⚠️ NO 'element' available - must use document.querySelector()
-    const container = document.querySelector('.niivue-viewer');
-    if (!container) {{
-        console.error('NiiVue container not found');
-        return;
-    }}
-
-    const canvas = container.querySelector('canvas');
-    const status = container.querySelector('.niivue-status');
-
-    // Get URLs from data attributes
-    const volumeUrl = container.dataset.volumeUrl;
-    const maskUrl = container.dataset.maskUrl;
-
-    // Skip if no volume URL
-    if (!volumeUrl) {{
-        console.log('No volume URL yet');
-        return;
-    }}
-
-    try {{
-        if (status) status.innerText = 'Loading NiiVue...';
-
-        const {{ Niivue }} = await import('{NIIVUE_CDN_URL}');
-        const nv = new Niivue({{
-            logging: false,
-            show3Dcrosshair: true,
-            backColor: [0, 0, 0, 1]
-        }});
-
-        await nv.attachToCanvas(canvas);
-        if (status) status.style.display = 'none';
-
-        const volumes = [{{ url: volumeUrl, name: 'input.nii.gz' }}];
-        if (maskUrl) {{
-            volumes.push({{ url: maskUrl, colorMap: 'red', opacity: 0.5 }});
-        }}
-
-        await nv.loadVolumes(volumes);
-        nv.setSliceType(nv.sliceTypeMultiplanar);
-        nv.drawScene();
-
-        console.log('NiiVue initialized via .then()');
-    }} catch (error) {{
-        console.error('NiiVue init error:', error);
-        if (container) {{
-            const errorDiv = document.createElement('div');
-            errorDiv.style.cssText = 'color:#f66;padding:20px;text-align:center;';
-            errorDiv.textContent = 'Error: ' + error.message;
-            container.innerHTML = '';
-            container.appendChild(errorDiv);
-        }}
-    }}
-}})();
-"""
-```
-
-#### Step 2: Wire up the event handler in app.py
-
-```python
-# app.py
-from stroke_deepisles_demo.ui.viewer import NIIVUE_UPDATE_JS
-
-run_btn.click(
-    fn=run_segmentation,
-    inputs=[case_selector, settings["fast_mode"], settings["show_ground_truth"]],
-    outputs=[results["niivue_viewer"], results["slice_plot"], results["metrics"],
-             results["download"], status],
-).then(
-    fn=None,  # MUST be explicit per GitHub Issue #6729!
-    js=NIIVUE_UPDATE_JS,
-)
-```
-
-**Why this works:**
-1. Python `run_segmentation()` updates gr.HTML value with new data-* attributes
-2. `.then()` chains after the click handler completes
-3. `fn=None` tells Gradio to skip Python, run JS only
-4. `js=NIIVUE_UPDATE_JS` runs our initialization code
-5. JS uses `document.querySelector()` to find the updated DOM
-
-### ⚠️ CRITICAL: Different JS Context (VERIFIED)
-
-The `js` parameter on event handlers has a **completely different context** than `js_on_load`:
-
-| Context | `js_on_load` | `js` on event handler |
-|---------|--------------|----------------------|
-| `element` | ✅ Available | ❌ **NOT available** |
-| `props` | ✅ Available | ❌ **NOT available** |
-| `trigger()` | ✅ Available | ❌ **NOT available** |
-| Arguments | None | Receives input/output **values** |
-
-From [Gradio Custom CSS and JS](https://www.gradio.app/guides/custom-CSS-and-JS):
-
-> "Input arguments for js method are **values of 'inputs' and 'outputs'**"
-
-Example from Gradio docs:
-```python
-reverse_btn.click(
-    None, [subject, verb, object], output2,
-    js="(s, v, o) => o + ' ' + v + ' ' + s"  # Receives VALUES, not DOM elements
-)
-```
-
-**This is why we need TWO separate JavaScript constants:**
-- `NIIVUE_ON_LOAD_JS` - Uses `element.querySelector()` (for initial mount)
-- `NIIVUE_UPDATE_JS` - Uses `document.querySelector()` (for .then() handler)
-
-### Risk Assessment: Is This Fixable?
-
-| Approach | Feasibility | Risk Level | Notes |
-|----------|-------------|------------|-------|
-| `.then(fn=None, js=...)` | ✅ High | Low | Native Gradio, documented |
-| MutationObserver | ✅ High | Medium | Complex, DOM stability warning |
-| gradio-iframe | ⚠️ Medium | High | Abandoned, Gradio 6 compat unknown |
-| data: URL iframe | ⚠️ Medium | Medium | CSP issues possible |
-| Custom component | ✅ High | Low | Most work, most robust |
-
-**Verdict: YES, this is fixable.** Solution 1 should work based on verified documentation.
-
----
-
-## References
-
-- [Gradio Custom HTML Components](https://www.gradio.app/guides/custom_HTML_components) - js_on_load limitation
-- [Gradio Custom CSS and JS](https://www.gradio.app/guides/custom-CSS-and-JS) - js parameter docs
-- [Gradio Event Listeners](https://www.gradio.app/docs/gradio/blocks#events) - .then() method
-- [GitHub Issue #6729](https://github.com/gradio-app/gradio/issues/6729) - fn=None requirement
-- [gradio-iframe PyPI](https://pypi.org/project/gradio-iframe/) - Alternative approach
-- [ipyniivue GitHub](https://github.com/niivue/ipyniivue) - Jupyter widget (not Gradio)
-- [MDN MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) - DOM watching
-- [Bug #10 Spec](./10-bug-niivue-viewer-black-screen.md) - Previous fix attempt
-- [Issue #19](https://github.com/The-Obstacle-Is-The-Way/stroke-deepisles-demo/issues/19) - Base64 optimization (related)

docs/specs/archive/19-perf-base64-to-file-urls.md

@@ -1,244 +0,0 @@
-# Issue #19: Replace Base64 Data URLs with File URLs for NiiVue Viewer
-
-## Status: RESOLVED ✅
-
-**Date:** 2025-12-09
-**Resolved:** 2025-12-09
-**Priority:** P3 (Performance optimization)
-**GitHub Issue:** https://github.com/The-Obstacle-Is-The-Way/stroke-deepisles-demo/issues/19
-**Related:** Bug #10, Bug #11 (both FIXED)
-
----
-
-## TL;DR
-
-Replace base64-encoded data URLs (~65MB payloads) with Gradio's file serving for
-NiiVue volumes. The viewer works correctly now, but large payloads may cause
-slow loading or memory issues.
-
----
-
-## Problem
-
-The NiiVue 3D viewer currently uses base64-encoded data URLs to pass NIfTI
-volumes to the browser:
-
-```python
-# Current implementation in viewer.py
-def nifti_to_data_url(nifti_path: Path) -> str:
-    """Convert NIfTI file to base64 data URL."""
-    data = nifti_path.read_bytes()
-    b64 = base64.b64encode(data).decode("ascii")
-    return f"data:application/octet-stream;base64,{b64}"
-```
-
-### Payload Size Analysis
-
-| File | Raw Size | Base64 Size |
-|------|----------|-------------|
-| DWI | 30.1 MB | ~40 MB |
-| ADC | 17.7 MB | ~24 MB |
-| **Total** | ~48 MB | **~65 MB** |
-
-### Potential Issues
-
-1. **Browser memory pressure** - Large base64 strings in DOM
-2. **Slow loading times** - 65MB transferred per segmentation
-3. **Gradio payload limits** - May hit internal limits on large responses
-4. **Mobile/low-bandwidth issues** - Poor UX on slower connections
-
----
-
-## Proposed Solution
-
-Use Gradio's built-in file serving instead of base64 data URLs.
-
-### Option A: Use `gr.File` component (Recommended)
-
-Gradio automatically serves files and provides URLs:
-
-```python
-from gradio import FileData
-
-def nifti_to_file_url(nifti_path: Path) -> str:
-    """Get Gradio file URL for NIfTI file."""
-    file_data = FileData(path=str(nifti_path))
-    return file_data.url  # Returns /file=... URL served by Gradio
-```
-
-### Option B: Use Gradio's file caching
-
-```python
-import gradio as gr
-
-# Gradio caches files and provides URLs
-cached_path = gr.utils.get_upload_folder() / nifti_path.name
-shutil.copy(nifti_path, cached_path)
-file_url = f"/file={cached_path}"
-```
-
----
-
-## Files to Modify
-
-| File | Changes |
-|------|---------|
-| `src/stroke_deepisles_demo/ui/viewer.py` | Replace `nifti_to_data_url()` with file URL function |
-| `src/stroke_deepisles_demo/ui/app.py` | Update `run_segmentation()` to use file URLs |
-
----
-
-## Implementation Steps
-
-### Step 1: Research Gradio File Serving
-
-Verify how Gradio serves files and what URL format NiiVue expects:
-
-```python
-# Test script
-import gradio as gr
-from gradio import FileData
-
-file_data = FileData(path="/path/to/test.nii.gz")
-print(f"URL: {file_data.url}")
-print(f"Type: {type(file_data.url)}")
-```
-
-### Step 2: Update `nifti_to_data_url()` → `nifti_to_file_url()`
-
-```python
-# viewer.py
-def nifti_to_file_url(nifti_path: Path) -> str:
-    """Get Gradio-served file URL for NIfTI file.
-
-    Args:
-        nifti_path: Path to NIfTI file
-
-    Returns:
-        URL string that Gradio will serve (e.g., /file=...)
-    """
-    from gradio import FileData
-    file_data = FileData(path=str(nifti_path))
-    return file_data.url
-```
-
-### Step 3: Update `app.py` to Use File URLs
-
-```python
-# app.py - run_segmentation()
-# Replace:
-dwi_url = nifti_to_data_url(dwi_path)
-mask_url = nifti_to_data_url(result.prediction_mask)
-
-# With:
-dwi_url = nifti_to_file_url(dwi_path)
-mask_url = nifti_to_file_url(result.prediction_mask)
-```
-
-### Step 4: Test NiiVue with File URLs
-
-Verify NiiVue can load from Gradio's file URLs:
-- Check CORS headers
-- Verify Content-Type header
-- Test with different browsers
-
-### Step 5: Cleanup
-
-Remove or deprecate `nifti_to_data_url()` if no longer needed.
-
----
-
-## Testing Checklist
-
-- [x] NiiVue loads DWI volume from file URL
-- [x] NiiVue loads prediction mask overlay from file URL
-- [x] No CORS errors in browser console (same-origin requests)
-- [x] Loading time improved (no base64 encoding overhead)
-- [x] Memory usage reduced (streaming vs. DOM strings)
-- [x] Works on HF Spaces deployment (uses tempfile.gettempdir())
-- [x] All existing tests pass (134 tests)
-
----
-
-## Implementation Details
-
-### Final Implementation (2025-12-09)
-
-The solution uses Gradio's built-in file serving at `/gradio_api/file=<path>`:
-
-**`viewer.py` - New function:**
-```python
-def nifti_to_gradio_url(nifti_path: Path) -> str:
-    """Get Gradio file URL for a NIfTI file."""
-    abs_path = nifti_path.resolve()
-    return f"/gradio_api/file={abs_path}"
-```
-
-**`app.py` - Updated usage:**
-```python
-dwi_url = nifti_to_gradio_url(dwi_path)
-mask_url = nifti_to_gradio_url(result.prediction_mask)
-```
-
-### Why This Works
-
-1. **Gradio allows temp files by default**: Files in `tempfile.gettempdir()` are
-   automatically accessible via the `/gradio_api/file=` endpoint.
-
-2. **Pipeline results are in temp dir**: `run_pipeline_on_case()` creates results
-   in `tempfile.mkdtemp()`, which is under `tempfile.gettempdir()`.
-
-3. **NiiVue supports HTTP URLs**: The `loadVolumes()` method can fetch from any
-   HTTP/HTTPS URL, including relative URLs served by Gradio.
-
-4. **Same-origin requests**: Since NiiVue's JavaScript runs in the browser and
-   requests files from the same Gradio server, there are no CORS issues.
-
-### Tests Added
-
-```python
-class TestNiftiToGradioUrl:
-    def test_returns_gradio_api_format(self, synthetic_nifti_3d: Path) -> None:
-        url = nifti_to_gradio_url(synthetic_nifti_3d)
-        assert url.startswith("/gradio_api/file=")
-
-    def test_uses_absolute_path(self, synthetic_nifti_3d: Path) -> None:
-        url = nifti_to_gradio_url(synthetic_nifti_3d)
-        path_part = url.replace("/gradio_api/file=", "")
-        assert path_part.startswith("/")
-
-    def test_no_base64_encoding(self, synthetic_nifti_3d: Path) -> None:
-        url = nifti_to_gradio_url(synthetic_nifti_3d)
-        assert not url.startswith("data:")
-        assert ";base64," not in url
-```
-
----
-
-## Risks and Mitigations
-
-| Risk | Mitigation |
-|------|------------|
-| CORS issues | Gradio should handle CORS for its own file serving |
-| NiiVue URL format | Test that NiiVue accepts relative URLs |
-| File cleanup | Gradio handles temp file cleanup automatically |
-| Security | Gradio's file serving is sandboxed to allowed paths |
-
----
-
-## Acceptance Criteria
-
-1. NiiVue viewer loads volumes from file URLs (not base64)
-2. No regression in viewer functionality
-3. Measurable improvement in loading time or memory usage
-4. All 130+ tests pass
-5. Works on HF Spaces
-
----
-
-## References
-
-- [Gradio FileData API](https://www.gradio.app/docs/gradio/filedata)
-- [Gradio File Serving](https://www.gradio.app/guides/file-access)
-- [NiiVue Loading Volumes](https://niivue.github.io/niivue/features/loading.volumes.html)
-- [Bug #10 - Secondary Issue 1](./10-bug-niivue-viewer-black-screen.md)

docs/specs/archive/23-slice-comparison-overlay-bug.md

@@ -1,287 +0,0 @@
-# Bug Investigation: Slice Comparison Prediction Overlay Not Visible
-
-**Issue**: Prediction overlay is invisible in slice comparison while ground truth overlay is visible
-
-**Date**: 2025-12-09
-**Branch**: `debug/slice-comparison-prediction-overlay`
-
----
-
-## Observed Behavior
-
-In the Gradio UI "Slice Comparison" tab:
-- **DWI Input** (left panel): Shows grayscale brain scan ✓
-- **Prediction** (middle panel): Shows grayscale brain scan **without any visible overlay** ✗
-- **Ground Truth** (right panel): Shows grayscale brain scan **with green overlay** ✓
-
-## Expected Behavior
-
-The Prediction panel should show a **red overlay** on the predicted lesion area, similar to how Ground Truth shows a green overlay.
-
----
-
-## Code Analysis
-
-### Visualization Code (`viewer.py:261-268`)
-
-```python
-# Prediction panel
-axes[1].imshow(d_slice, cmap="gray")
-axes[1].imshow(
-    np.ma.masked_where(p_slice == 0, p_slice),
-    cmap="Reds",
-    alpha=0.5,
-    vmin=0,
-    vmax=1,
-)
-```
-
-### Ground Truth Code (`viewer.py:273-280`)
-
-```python
-# Ground Truth panel
-axes[2].imshow(d_slice, cmap="gray")
-axes[2].imshow(
-    np.ma.masked_where(g_slice == 0, g_slice),
-    cmap="Greens",
-    alpha=0.5,
-    vmin=0,
-    vmax=1,
-)
-```
-
-The code is **structurally identical**. The only difference is:
-- Prediction: `cmap="Reds"`
-- Ground Truth: `cmap="Greens"`
-
----
-
-## Hypothesis
-
-### Primary Hypothesis: Probability vs Binary Mask Values
-
-| Mask Type | Typical Values | Colormap Rendering | Visibility |
-|-----------|----------------|-------------------|------------|
-| Ground Truth | Binary (0 or 1) | 1.0 → **Dark Green** | High ✓ |
-| Prediction | Probabilities (0.0-0.3) | 0.1 → **Nearly White** | None ✗ |
-
-**Why this matters:**
-
-1. Matplotlib's **"Reds" colormap** goes from white (0) → red (1)
-2. With `vmin=0, vmax=1`:
-   - A value of `0.05` maps to 5% of the colormap = nearly white
-   - A value of `1.0` maps to 100% of the colormap = red
-3. With `alpha=0.5` over a grayscale background, nearly-white overlays are **invisible**
-
-**Evidence:**
-- DeepISLES SEALS model may output probability maps, not binary masks
-- The `compute_dice` function in `metrics.py` applies a `threshold=0.5` to binarize predictions
-- The visualization does **not** apply any thresholding before display
-
-### Alternative Hypotheses
-
-1. **Empty slice**: Prediction mask is all zeros at the selected slice (unlikely given the slice selection logic uses `get_slice_at_max_lesion(prediction_path)`)
-
-2. **Data type issue**: Float comparison `p_slice == 0` may fail for float32 arrays (unlikely - works for ground truth)
-
-3. **File path mismatch**: Wrong file being loaded as prediction (need to verify)
-
----
-
-## Diagnostic Steps
-
-### 1. Check Prediction Mask Values
-
-```python
-import nibabel as nib
-import numpy as np
-
-# Load a prediction mask from a recent run
-pred = nib.load("/path/to/prediction.nii.gz").get_fdata()
-print(f"Shape: {pred.shape}")
-print(f"Dtype: {pred.dtype}")
-print(f"Min: {pred.min()}, Max: {pred.max()}")
-print(f"Unique values: {np.unique(pred)[:20]}")  # First 20 unique values
-print(f"Non-zero count: {np.count_nonzero(pred)}")
-print(f"Values > 0.5: {np.count_nonzero(pred > 0.5)}")
-```
-
-### 2. Check Ground Truth Mask Values
-
-```python
-gt = nib.load("/path/to/ground_truth.nii.gz").get_fdata()
-print(f"Shape: {gt.shape}")
-print(f"Dtype: {gt.dtype}")
-print(f"Min: {gt.min()}, Max: {gt.max()}")
-print(f"Unique values: {np.unique(gt)}")
-```
-
-### 3. Visual Comparison
-
-```python
-# Plot histogram of values
-import matplotlib.pyplot as plt
-fig, axes = plt.subplots(1, 2)
-axes[0].hist(pred[pred > 0].flatten(), bins=50)
-axes[0].set_title("Prediction non-zero values")
-axes[1].hist(gt[gt > 0].flatten(), bins=50)
-axes[1].set_title("Ground Truth non-zero values")
-plt.savefig("mask_histograms.png")
-```
-
----
-
-## Proposed Fix
-
-### Option A: Binarize Prediction Before Display (Recommended)
-
-```python
-# In render_slice_comparison, before creating overlay:
-p_slice_binary = (p_slice > 0.5).astype(float)
-
-axes[1].imshow(
-    np.ma.masked_where(p_slice_binary == 0, p_slice_binary),
-    cmap="Reds",
-    alpha=0.5,
-    vmin=0,
-    vmax=1,
-)
-```
-
-**Pros:**
-- Consistent with how `compute_dice` treats predictions
-- Clear visualization of model decision boundary
-- Matches clinical interpretation (lesion vs not-lesion)
-
-**Cons:**
-- Loses probability information in visualization
-
-### Option B: Dynamic Normalization
-
-```python
-# Normalize to actual value range instead of fixed 0-1
-p_max = p_slice.max() if p_slice.max() > 0 else 1.0
-axes[1].imshow(
-    np.ma.masked_where(p_slice == 0, p_slice),
-    cmap="Reds",
-    alpha=0.5,
-    vmin=0,
-    vmax=p_max,
-)
-```
-
-**Pros:**
-- Shows probability information
-- Works regardless of value range
-
-**Cons:**
-- Inconsistent intensity across cases
-- Low-confidence predictions still appear bright (misleading)
-
-### Option C: Threshold-Based Masking
-
-```python
-# Only show values above a threshold
-threshold = 0.5
-axes[1].imshow(
-    np.ma.masked_where(p_slice < threshold, p_slice),
-    cmap="Reds",
-    alpha=0.5,
-    vmin=threshold,
-    vmax=1.0,
-)
-```
-
-**Pros:**
-- Only shows confident predictions
-- Good dynamic range for visible values
-
-**Cons:**
-- May hide uncertain but potentially relevant areas
-
----
-
-## Recommendation
-
-**Implement Option A (Binarize)** because:
-
-1. It matches the clinical use case (segmentation → binary decision)
-2. It's consistent with `compute_dice` threshold behavior
-3. It provides clear, interpretable visualization
-4. The raw probability map can still be viewed in NiiVue if needed
-
----
-
-## Dependencies
-
-| Package | Version | Relevant |
-|---------|---------|----------|
-| gradio | >=6.0.0 | Unlikely cause (renders matplotlib figure correctly) |
-| matplotlib | >=3.8.0 | Colormap behavior is standard |
-| numpy | >=1.26.0,<2.0.0 | Float comparison works correctly |
-| nibabel | >=5.2.0 | Loads data correctly |
-
----
-
-## Resolution
-
-**Status**: FIXED (2025-12-09)
-**Branch**: `debug/slice-comparison-prediction-overlay`
-
-### Changes Made
-
-**Primary Fix (Issue #23):**
-
-1. **`viewer.py:270-275`**: Added binarization of prediction mask in `render_slice_comparison`:
-   ```python
-   # Binarize prediction at threshold 0.5 for visible overlay (Issue #23)
-   p_slice_binary = (p_slice > 0.5).astype(float)
-   ```
-
-2. **`viewer.py:156-164`**: Added binarization in `render_3panel_view` for consistency
-
-3. **`tests/conftest.py`**: Added `synthetic_probability_mask` and `synthetic_binary_mask` fixtures
-
-4. **`tests/ui/test_viewer.py`**: Added `TestRenderSliceComparisonProbabilityMask` test class
-
-**Additional Fixes (Found During Audit):**
-
-5. **Race Condition (P2)**: Replaced global `_previous_results_dir` with `gr.State` for per-session thread-safe cleanup tracking
-
-6. **Inconsistent Threshold in compute_volume_ml**: Added `threshold=0.5` parameter for consistent binarization
-
-7. **render_3panel_view Wired Into UI**:
-   - Added `gr.Tabs` layout with "Interactive 3D" and "Static Report" tabs
-   - `render_3panel_view` now displayed in "Static Report" alongside slice comparison
-   - Provides WebGL2 fallback via static matplotlib figures
-
-8. **Thread-Safe Matplotlib**: Refactored from `pyplot` API to Object-Oriented API (`Figure()`) for multi-user safety
-
-### Verification
-
-- All 136 tests pass
-- Lint (ruff) passes
-- Type check (mypy) passes
-
-## Files Modified
-
-| File | Changes |
-|------|---------|
-| `src/stroke_deepisles_demo/ui/viewer.py` | OO matplotlib API, binarization in both render functions |
-| `src/stroke_deepisles_demo/ui/app.py` | gr.State, render_3panel_view integration, volume_ml |
-| `src/stroke_deepisles_demo/ui/components.py` | Tabs layout (Interactive 3D / Static Report) |
-| `src/stroke_deepisles_demo/metrics.py` | threshold parameter for compute_volume_ml |
-| `tests/conftest.py` | New probability/binary mask fixtures |
-| `tests/ui/test_viewer.py` | Probability mask tests |
-| `tests/ui/test_app.py` | Updated for new return signature |
-
-## Next Steps
-
-1. [x] Run diagnostic script to confirm hypothesis
-2. [x] Implement fix (Option A - binarize)
-3. [x] Add test case for probability-valued masks
-4. [x] Wire render_3panel_view into UI with tabs
-5. [x] Fix race condition with gr.State
-6. [x] Make matplotlib thread-safe with OO API
-7. [ ] Verify fix in local Gradio app (manual testing recommended)
-8. [ ] Create PR and merge to main

docs/specs/archive/24-bug-hf-spaces-loading-forever.md

@@ -1,254 +0,0 @@
-# Bug #24: HuggingFace Space Stuck on "Loading..." (P0)
-
-**Date:** 2025-12-09
-**Status:** FIXED
-**Branch:** `debug/hf-spaces-loading-forever`
-**Space:** https://huggingface.co/spaces/VibecoderMcSwaggins/stroke-deepisles-demo
-
----
-
-## Symptom
-
-The HuggingFace Space shows:
-- **Status badge:** "Running on T4" (green) ✓
-- **App panel:** Stuck on "Loading..." indefinitely ✗
-
-The Docker container has started successfully (hence "Running on T4"), but the Gradio frontend never receives a response from the backend.
-
----
-
-## What We Know
-
-### Local Testing: Works Fine
-```python
-# All pass in ~1.3 seconds
-from stroke_deepisles_demo.ui.app import create_app
-demo = create_app()  # Returns gr.Blocks successfully
-```
-
-### Code on HF Space
-The Space is synced with `main` branch (commit `10a72ea`), NOT the PR #23 branch.
-- `js_on_load` parameter was already added in commit `bc1d8e8`
-- Server binds to `0.0.0.0:7860` (correct for Docker)
-- Dataset loading uses pre-computed case IDs (no network calls on startup)
-
-### Configuration Verified
-| Setting | Value | Status |
-|---------|-------|--------|
-| `sdk` | `docker` | ✓ Correct |
-| `app_port` | `7860` | ✓ Correct |
-| `server_name` | `0.0.0.0` | ✓ Correct |
-| `server_port` | `7860` | ✓ Correct |
-| Gradio version | `>=6.0.0,<7.0.0` | ✓ Correct |
-
----
-
-## Hypotheses
-
-### H1: Python Startup Crash (Silent)
-The Python app may be crashing during startup but HF Spaces still shows "Running on T4" because the container process is alive (perhaps a shell wrapper).
-
-**Check:** Look at HF Spaces logs for Python tracebacks.
-
-### H2: Gradio Server Not Binding
-The Gradio server may be failing to bind or timing out before accepting connections.
-
-**Check:** Look for "Running on local URL" in logs.
-
-### H3: HF Spaces Platform Issue
-HuggingFace Spaces may have a platform-wide issue affecting Docker SDK spaces.
-
-**Check:** https://status.huggingface.co/ and HF Forums.
-
-### H4: Memory/Resource Exhaustion
-The T4 instance may be running out of memory during startup.
-
-**Check:** Look for OOM errors in logs.
-
-### H5: Dependencies Installation Failure
-The `git+https://github.com/CloseChoice/datasets.git@...` dependency may fail to install.
-
-**Check:** Build logs for pip install errors.
-
----
-
-## Diagnostic Steps
-
-### 1. Check HF Spaces Logs
-Go to the Space → Settings → Logs and look for:
-- Python tracebacks
-- "Running on local URL: http://0.0.0.0:7860"
-- Memory errors
-- Dependency installation errors
-
-### 2. Factory Rebuild
-Settings → Factory rebuild to force a clean Docker build.
-
-### 3. Check HF Status
-Visit https://status.huggingface.co/ for platform outages.
-
-### 4. Test Minimal Dockerfile
-Create a minimal test Space with just Gradio to isolate the issue:
-
-```dockerfile
-FROM python:3.11-slim
-RUN pip install gradio
-COPY <<EOF app.py
-import gradio as gr
-demo = gr.Interface(fn=lambda x: x, inputs="text", outputs="text")
-demo.launch(server_name="0.0.0.0", server_port=7860)
-EOF
-CMD ["python", "app.py"]
-```
-
----
-
-## Related Issues
-
-- [HF Forum: Space stuck at Starting](https://discuss.huggingface.co/t/hf-space-stuck-at-starting/170911) (Nov 2025)
-- [HF Forum: Dockerized app stuck at Building](https://discuss.huggingface.co/t/dockerized-gradio-app-stuck-at-building-despite-clean-logs/65558)
-- [HF Forum: How to debug Spaces](https://discuss.huggingface.co/t/how-to-debug-spaces-on-hf-co/13191)
-- [Gradio Issue #11401: Errors accessing spaces](https://github.com/gradio-app/gradio/issues/11401) (June 2025)
-
----
-
-## Questions for User
-
-1. **When did the Space last work correctly?** (Before which commit/PR?)
-2. **What do the HF Spaces logs show?** (Settings → Logs)
-3. **Has a factory rebuild been attempted?**
-4. **Is HF Spaces having any platform issues today?**
-
----
-
-## Next Steps
-
-1. [ ] User to check HF Spaces logs
-2. [ ] User to attempt factory rebuild
-3. [ ] Check if issue is platform-wide (HF status page)
-4. [ ] If needed, create minimal reproduction Space
-5. [ ] If dependency issue, consider vendoring the datasets fork
-
----
-
-## Resolution
-
-**Status:** FIXED (2025-12-09)
-
-### Root Cause
-
-**Content Security Policy (CSP) blocking external CDN imports.**
-
-The NiiVue library was being loaded via dynamic ES module import from unpkg.com CDN:
-```javascript
-const { Niivue } = await import('https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js');
-```
-
-HuggingFace Spaces enforces strict CSP headers that block external script imports. The import would either:
-1. Be silently blocked by CSP
-2. Hang indefinitely waiting for a response that never comes
-
-This caused the Gradio frontend to remain stuck on "Loading..." even though the Python backend was running correctly.
-
-**Evidence:**
-- HF Spaces logs showed `Running on local URL: http://0.0.0.0:7860` (server healthy)
-- No Python tracebacks (no backend crash)
-- `list_case_ids()` uses pre-computed constants (no network blocking)
-- Classic symptom of client-side JS execution failure
-
-### Fix Applied
-
-**Vendored the NiiVue library locally** instead of relying on external CDN:
-
-1. **Downloaded NiiVue to local assets:**
-   - `src/stroke_deepisles_demo/ui/assets/niivue.js` (2.9MB)
-
-2. **Updated `viewer.py` to use local path:**
-   ```python
-   _ASSET_DIR = Path(__file__).parent / "assets"
-   _NIIVUE_JS_PATH = _ASSET_DIR / "niivue.js"
-   NIIVUE_JS_URL = f"/gradio_api/file={_NIIVUE_JS_PATH.resolve()}"
-   ```
-
-3. **Added `allowed_paths` to `demo.launch()`:**
-   ```python
-   assets_dir = Path(__file__).parent / "assets"
-   demo.launch(
-       # ...
-       allowed_paths=[str(assets_dir)],
-   )
-   ```
-
-### Files Modified
-
-| File | Changes |
-|------|---------|
-| `src/stroke_deepisles_demo/ui/assets/niivue.js` | NEW - Vendored NiiVue v0.65.0 |
-| `src/stroke_deepisles_demo/ui/viewer.py` | Use local path instead of CDN |
-| `src/stroke_deepisles_demo/ui/app.py` | Add `allowed_paths` to launch() |
-| `app.py` | Add `allowed_paths` to launch() |
-| `.pre-commit-config.yaml` | Exclude assets/ from hooks |
-
-### Verification
-
-- All 136 tests pass
-- Ruff lint passes
-- Mypy type check passes
-- Local Gradio app loads correctly
-
-### Why This Is The Professional Solution
-
-1. **Self-contained:** No external dependencies at runtime
-2. **Reliable:** Immune to CDN outages or rate limits
-3. **Security-compliant:** Respects HF Spaces CSP policy
-4. **Reproducible:** Same NiiVue version always loaded
-5. **Standard practice:** Vendoring is the recommended approach for HF Spaces
-
----
-
-## Update: Vendoring Alone Did Not Fix It (2025-12-09)
-
-### New Finding
-
-Vendoring NiiVue locally bypassed CSP but **the app still wouldn't load**.
-
-**Diagnostic test:** Disabled `js_on_load` parameter entirely.
-
-**Result:** App loads perfectly! Everything works EXCEPT Interactive 3D viewer.
-
-### Real Root Cause
-
-**`gr.HTML(js_on_load=...)` with dynamic ES module `import()` blocks Gradio frontend initialization on HF Spaces.**
-
-The issue is NOT the vendored file location - it's HOW we load the JavaScript:
-
-```javascript
-// This approach BREAKS the entire Gradio app on HF Spaces:
-const { Niivue } = await import('/gradio_api/file=...');
-```
-
-When this fails (silently), it prevents the Gradio frontend from completing initialization, causing the eternal "Loading..." screen.
-
-### Evidence
-
-With `js_on_load` disabled:
-- ✅ Gradio app loads
-- ✅ Case selector works
-- ✅ DeepISLES segmentation runs (38.66s)
-- ✅ Static Report (Matplotlib) renders correctly
-- ✅ Metrics JSON displays
-- ✅ Download works
-- ❌ Interactive 3D shows "Loading viewer..." (expected - JS disabled)
-
-### Correct Approach
-
-Use `gr.Blocks(head=...)` to load NiiVue as a `<script>` tag instead of dynamic `import()`:
-
-```python
-with gr.Blocks(
-    head='<script src="/gradio_api/file=.../niivue.js"></script>'
-) as demo:
-    ...
-```
-
-Or use the global `js` parameter on `gr.Blocks` to define initialization code that runs after the script loads.

docs/specs/archive/AUDIT_JS_LOADING_ISSUES.md

@@ -1,935 +0,0 @@
-# Comprehensive Audit: JavaScript Loading Issues on HuggingFace Spaces
-
-**Created:** 2025-12-09
-**Status:** P0 - Critical
-**Issue:** HF Spaces stuck on "Loading..." forever despite "Running on T4"
-
----
-
-## Executive Summary
-
-The NiiVue 3D viewer fails to load on HuggingFace Spaces due to a combination of JavaScript loading issues, timing race conditions, and architectural problems. This document catalogs EVERY potential issue found in the codebase.
-
----
-
-## ROOT CAUSES IDENTIFIED
-
-### 1. Module Script Timing Race Condition (CRITICAL)
-
-**Location:** `src/stroke_deepisles_demo/ui/viewer.py:64-68`
-
-```python
-loader_content = f"""...
-<script type="module">
-    import {{ Niivue }} from '{NIIVUE_JS_URL}';
-    window.Niivue = Niivue;
-    console.log('[NiiVue Loader] Loaded globally:', typeof window.Niivue);
-</script>
-"""
-```
-
-**Problem:** `<script type="module">` is **deferred by default**. It executes AFTER HTML parsing completes, but `js_on_load` may run BEFORE the module finishes loading.
-
-**Impact:** `window.Niivue` is `undefined` when `NIIVUE_ON_LOAD_JS` tries to access it.
-
----
-
-### 2. Dynamic Path Resolution at Import Time
-
-**Location:** `src/stroke_deepisles_demo/ui/viewer.py:32-36`
-
-```python
-_ASSET_DIR = Path(__file__).parent / "assets"
-_NIIVUE_JS_PATH = _ASSET_DIR / "niivue.js"
-NIIVUE_JS_URL = f"/gradio_api/file={_NIIVUE_JS_PATH.resolve()}"
-```
-
-**Problem:** `NIIVUE_JS_URL` is computed at **module import time** with `.resolve()`. This creates an absolute path like:
-- Local: `/Users/ray/Desktop/.../assets/niivue.js`
-- HF Spaces: `/home/user/demo/src/.../assets/niivue.js`
-
-**Risk:** If the path is wrong or the file is not accessible, the module import fails silently.
-
----
-
-### 3. Two Entry Points with Different Configurations
-
-**Location:** Root `app.py` vs `src/stroke_deepisles_demo/ui/app.py`
-
-**Dockerfile uses:**
-```dockerfile
-CMD ["python", "-m", "stroke_deepisles_demo.ui.app"]
-```
-
-This runs `src/stroke_deepisles_demo/ui/app.py` as `__main__`, NOT root `app.py`.
-
-**Both files configure `head_paths` and `allowed_paths` in their `if __name__ == "__main__":` blocks:**
-
-Root `app.py:35-49`:
-```python
-assets_dir = Path(__file__).parent / "src" / "stroke_deepisles_demo" / "ui" / "assets"
-```
-
-`src/.../ui/app.py:278-292`:
-```python
-assets_dir = Path(__file__).parent / "assets"
-```
-
-**Risk:** Different path calculations, potential mismatch.
-
----
-
-### 4. Async IIFE in js_on_load
-
-**Location:** `src/stroke_deepisles_demo/ui/viewer.py:441-526` and `viewer.py:535-625`
-
-```javascript
-NIIVUE_ON_LOAD_JS = """
-(async () => {
-    // ... async code ...
-})();
-"""
-```
-
-**Problem:** Gradio's `js_on_load` mechanism may not properly handle async IIFEs. If the function throws before completing, Gradio's frontend initialization may hang.
-
----
-
-### 5. Error Message Inconsistency / Stale Comments
-
-**Location:** `src/stroke_deepisles_demo/ui/viewer.py:437-440`
-
-```python
-# IMPORTANT: This code uses window.Niivue which must be loaded via
-# gr.Blocks(head=get_niivue_head_script()). Do NOT use dynamic import()
-```
-
-**But we actually use `head_paths`!** Comment is stale.
-
-**Location:** `src/stroke_deepisles_demo/ui/viewer.py:473`
-```javascript
-throw new Error('NiiVue not loaded. Ensure head script is included via gr.Blocks(head=...)');
-```
-
-**Wrong!** Should reference `head_paths`, not `head`.
-
----
-
-### 6. Deprecated Function Still Present
-
-**Location:** `src/stroke_deepisles_demo/ui/viewer.py:95-109`
-
-```python
-def get_niivue_head_script() -> str:
-    """
-    DEPRECATED: Use get_niivue_loader_path() with head_paths instead.
-    """
-```
-
-**Risk:** Could be accidentally used, causing confusion.
-
----
-
-### 7. Test Script Uses CDN (Outdated Pattern)
-
-**Location:** `scripts/test_js_on_load.py:38` and `scripts/test_js_on_load.py:76`
-
-```javascript
-const mod = await import('https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js');
-```
-
-**Problem:** This is the EXACT pattern that was blocked by HF Spaces CSP! The test script uses the old CDN approach.
-
----
-
-### 8. niivue-loader.html Generated at Runtime
-
-**Location:** `src/stroke_deepisles_demo/ui/viewer.py:39-91`
-
-```python
-def get_niivue_loader_path() -> Path:
-    loader_path = _ASSET_DIR / "niivue-loader.html"
-    # ... generates file at runtime ...
-```
-
-**Gitignored at:** `.gitignore:219`
-```text
-src/stroke_deepisles_demo/ui/assets/niivue-loader.html
-```
-
-**Risk:**
-- File must be generated before `launch()` is called
-- Write permissions required on HF Spaces
-- If generation fails, `head_paths` has invalid file
-
----
-
-## ALL JAVASCRIPT CODE LOCATIONS
-
-### Production Code
-
-| File | Line | Type | Content |
-|------|------|------|---------|
-| `viewer.py` | 64-68 | ES Module | `import { Niivue } from '...'` in loader HTML |
-| `viewer.py` | 105-109 | ES Module | Deprecated `get_niivue_head_script()` |
-| `viewer.py` | 441-526 | js_on_load | `NIIVUE_ON_LOAD_JS` - async IIFE |
-| `viewer.py` | 535-625 | .then(js=) | `NIIVUE_UPDATE_JS` - async IIFE |
-| `components.py` | 49 | js_on_load | `js_on_load=NIIVUE_ON_LOAD_JS` |
-| `ui/app.py` | 250 | .then(js=) | `js=NIIVUE_UPDATE_JS` |
-
-### Test/Development Code
-
-| File | Line | Type | Content |
-|------|------|------|---------|
-| `test_js_on_load.py` | 38 | Dynamic Import | CDN import (unpkg.com) - **BLOCKED BY CSP** |
-| `test_js_on_load.py` | 76 | Dynamic Import | CDN import (unpkg.com) - **BLOCKED BY CSP** |
-
----
-
-## ALL EXTERNAL URLs
-
-### In Production Code
-
-| File | Line | URL | Status |
-|------|------|-----|--------|
-| `viewer.py` | 36 | `/gradio_api/file=...` | Internal (OK) |
-
-### In Documentation (Historical)
-
-| File | URL | Status |
-|------|-----|--------|
-| `docs/specs/00-context.md:202` | `https://unpkg.com/@niivue/niivue@0.57.0/dist/index.js` | **BLOCKED BY CSP** |
-| `docs/specs/07-hf-spaces-deployment.md:239` | `https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js` | **BLOCKED BY CSP** |
-| `docs/specs/07-hf-spaces-deployment.md:259` | `https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js` | **BLOCKED BY CSP** |
-| `docs/specs/07-hf-spaces-deployment.md:592` | `https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js` | **BLOCKED BY CSP** |
-
----
-
-## ALL head_paths / allowed_paths CONFIGURATIONS
-
-| File | Line | Configuration |
-|------|------|---------------|
-| `app.py` | 48-49 | `allowed_paths=[str(assets_dir)], head_paths=[str(niivue_loader)]` |
-| `ui/app.py` | 291-292 | `allowed_paths=[str(assets_dir)], head_paths=[str(niivue_loader)]` |
-
----
-
-## ALL async/await PATTERNS IN JAVASCRIPT
-
-| File | Line | Pattern | Risk |
-|------|------|---------|------|
-| `viewer.py` | 442 | `(async () => { ... })();` | Unhandled rejection may hang Gradio |
-| `viewer.py` | 536 | `(async () => { ... })();` | Unhandled rejection may hang Gradio |
-| `test_js_on_load.py` | 24 | `(async () => { ... })();` | Test-only |
-| `test_js_on_load.py` | 35 | `(async () => { ... })();` | Test-only |
-| `test_js_on_load.py` | 61 | `(async () => { ... })();` | Test-only |
-
----
-
-## POTENTIAL CSP VIOLATIONS
-
-### HuggingFace Spaces CSP Headers (Suspected)
-
-```text
-Content-Security-Policy:
-  script-src 'self' 'unsafe-inline' 'unsafe-eval';
-  connect-src 'self' ...;
-```
-
-### Code That May Violate CSP
-
-1. **Dynamic ES Module Import** - `<script type="module">` with `import()` from local file
-   - Should be OK if file is same-origin
-   - May fail if path resolution is wrong
-
-2. **External CDN (Historical)** - `import('https://unpkg.com/...')`
-   - **BLOCKED** by `script-src` not including unpkg.com
-
----
-
-## TIMING DIAGRAM: What SHOULD Happen
-
-```text
-1. Gradio loads HTML page
-2. <head> includes niivue-loader.html via head_paths
-3. Module script in loader imports niivue.js
-4. window.Niivue is set globally
-5. gr.HTML component mounts
-6. js_on_load runs, accesses window.Niivue
-7. NiiVue initializes
-```
-
-## TIMING DIAGRAM: What MAY Be Happening
-
-```text
-1. Gradio loads HTML page
-2. <head> includes niivue-loader.html via head_paths
-3. Module script DEFERRED (not executed yet)
-4. gr.HTML component mounts
-5. js_on_load runs, window.Niivue is UNDEFINED
-6. Error thrown: "NiiVue not loaded"
-7. Gradio hangs waiting for component
-```
-
----
-
-## RECOMMENDED FIXES (Priority Order)
-
-### P0: Verify head_paths is Actually Working
-
-Add diagnostic logging:
-```python
-print(f"[DEBUG] niivue_loader path: {niivue_loader}")
-print(f"[DEBUG] File exists: {Path(niivue_loader).exists()}")
-print(f"[DEBUG] File contents: {Path(niivue_loader).read_text()[:200]}")
-```
-
-### P1: Add Module Load Waiting
-
-Change NIIVUE_ON_LOAD_JS to wait for window.Niivue:
-```javascript
-(async () => {
-    // Wait for NiiVue to be available (max 5 seconds)
-    for (let i = 0; i < 50 && !window.Niivue; i++) {
-        await new Promise(r => setTimeout(r, 100));
-    }
-    if (!window.Niivue) {
-        throw new Error('NiiVue failed to load after 5 seconds');
-    }
-    // ... rest of initialization
-})();
-```
-
-### P2: Use Non-Module Script Tag
-
-Instead of `<script type="module">`, use regular script:
-```html
-<script>
-    // UMD build instead of ESM
-</script>
-```
-
-### P3: Bundle NiiVue into a Single IIFE
-
-Create a self-contained bundle that doesn't need ES module import.
-
----
-
-## FILES TO AUDIT BEFORE ANY FIX
-
-1. `src/stroke_deepisles_demo/ui/viewer.py` - All JS constants
-2. `src/stroke_deepisles_demo/ui/components.py` - js_on_load usage
-3. `src/stroke_deepisles_demo/ui/app.py` - .then(js=) usage, launch config
-4. `app.py` - launch config
-5. `.gitignore` - niivue-loader.html entry
-6. `Dockerfile` - CMD entry point
-
----
-
-## VERSION HISTORY
-
-| Date | Change | Result |
-|------|--------|--------|
-| Pre-bc1d8e8 | Inline `<script>` tags | Black screen (scripts stripped) |
-| bc1d8e8 | js_on_load + CDN import | Loading forever (CSP blocked CDN) |
-| 1973147 | Vendored niivue.js | Loading forever (still using import()) |
-| 08c3363 | head_paths approach | Loading forever (timing race?) |
-
----
-
----
-
-## RESEARCH FINDINGS FROM WEB
-
-### Source 1: GitHub Issue #11649 - head_paths is Official Solution
-
-**URL:** https://github.com/gradio-app/gradio/issues/11649
-
-**Finding:** Gradio maintainer @dawoodkhan82 explicitly recommended `head_paths`:
-> "use the `head_paths` param where you can pass a path or list of paths to html files, and in that file you can include your `<script>`"
-
-**Confirmation:** "I just tested, and this works on my end."
-
-**Implication:** Our approach using `head_paths` is correct according to Gradio maintainers.
-
----
-
-### Source 2: GitHub Issue #10250 - head Parameter JS Execution Non-Deterministic
-
-**URL:** https://github.com/gradio-app/gradio/issues/10250
-
-**Finding:** JavaScript in `head` parameter has non-deterministic execution:
-> "JavaScript would sometimes execute only after extended waiting periods (5+ minutes), or occasionally not at all."
-
-**Root Cause:** Timing issues between Gradio's frontend initialization and script loading.
-
-**Implication:** Even if `head_paths` works, the timing may be unpredictable.
-
----
-
-### Source 3: ES Module Script Timing
-
-**URLs:**
-- https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script
-- https://gist.github.com/jakub-g/385ee6b41085303a53ad92c7c8afd7a6
-
-**Finding:** Module scripts execute BEFORE DOMContentLoaded:
-> "The DOMContentLoaded event fires when the HTML document has been completely parsed, and all deferred scripts (`<script defer src="…">` and `<script type="module">`) have downloaded and executed."
-
-**Key Points:**
-- Module scripts are deferred by default
-- They execute AFTER HTML parsing but BEFORE DOMContentLoaded
-- Regular inline scripts execute immediately
-
-**Implication:** In theory, `window.Niivue` should be set BEFORE Gradio's frontend fully initializes. BUT Gradio may initialize components differently.
-
----
-
-### Source 4: Gradio js_on_load Parameter
-
-**URL:** https://www.gradio.app/docs/gradio/html
-
-**Finding:** `js_on_load` executes "when the component is loaded."
-
-**Available Variables:**
-- `element` - the HTML element of the component
-- `trigger` - function to trigger events
-- `props` - component properties
-
-**Default:** `"element.addEventListener('click', function() { trigger('click') });"`
-
-**Implication:** js_on_load runs during Svelte component mounting, which may be AFTER or BEFORE module scripts complete.
-
----
-
-### Source 5: Gradio Frontend Architecture
-
-**URL:** https://www.gradio.app/guides/frontend
-
-**Finding:** Gradio frontend is built with Svelte 5 and SvelteKit. Components use Svelte's `onMount` lifecycle.
-
-**Svelte onMount Timing:**
-> "The onMount function schedules a callback to run as soon as the component has been mounted to the DOM."
-
-**Implication:** js_on_load likely runs during `onMount`, which is AFTER the component renders to DOM. Module scripts in `<head>` should have already executed by then... BUT there may be framework-specific timing issues.
-
----
-
-### Source 6: HuggingFace Spaces CSP
-
-**URL:** https://huggingface.co/docs/hub/spaces-config-reference
-
-**Finding:** HF Spaces only allows these custom headers:
-- `cross-origin-embedder-policy`
-- `cross-origin-opener-policy`
-- `cross-origin-resource-policy`
-
-**Content-Security-Policy is NOT customizable.**
-
-**Implication:** We cannot modify CSP. We must work within HF Spaces' default CSP.
-
----
-
-### Source 7: HF Spaces Perpetual Loading
-
-**URL:** https://discuss.huggingface.co/t/issue-with-perpetual-loading-on-the-space/35684
-
-**Finding:** Browser cache can cause perpetual loading even when Space is running correctly.
-
-**Solution:** Clear browser cache.
-
-**Implication:** Some "Loading..." issues may be client-side, not server-side.
-
----
-
-### Source 8: Gradio Custom JS Documentation
-
-**URL:** https://www.gradio.app/guides/custom-CSS-and-JS
-
-**Key Differences:**
-
-| Parameter | Location | Timing | Purpose |
-|-----------|----------|--------|---------|
-| `js` in launch() | Page body | Page load | Interactive logic |
-| `head` in launch() | `<head>` | Document init | Setup/analytics |
-| `head_paths` | `<head>` | Document init | External files |
-| `js_on_load` | Component | Component mount | Per-component |
-
-**Warning from docs:**
-> "Query selectors in custom JS and CSS are _not_ guaranteed to work across Gradio versions"
-
----
-
-## REVISED THEORY: Why It's Still Breaking
-
-Based on research, here's the likely sequence:
-
-1. **Browser requests page from HF Spaces**
-2. **Gradio server returns HTML with `<head>` contents from `head_paths`**
-3. **Browser parses HTML, encounters `<script type="module">` in `<head>`**
-4. **Module script is DEFERRED** (won't block parsing)
-5. **Gradio's Svelte frontend initializes**
-6. **gr.HTML component mounts → `js_on_load` runs**
-7. **`js_on_load` tries to access `window.Niivue`**
-8. **If module hasn't finished loading → `window.Niivue` is undefined**
-9. **Error is thrown or code hangs**
-
-The issue is that Gradio's Svelte components may mount BEFORE all deferred scripts complete, even though DOMContentLoaded waits for them.
-
----
-
-## ALTERNATIVE THEORIES
-
-### Theory A: head_paths File Not Being Served
-
-The `niivue-loader.html` file might not be accessible via Gradio's file serving on HF Spaces.
-
-**Test:** Check browser Network tab for 404 on niivue-loader.html or niivue.js
-
-### Theory B: allowed_paths Not Working
-
-The `allowed_paths` parameter might not be properly allowing access to the assets directory on HF Spaces.
-
-**Test:** Try serving a simple text file via /gradio_api/file=
-
-### Theory C: Path Resolution Mismatch
-
-The absolute path in `NIIVUE_JS_URL` might be wrong for the HF Spaces Docker environment.
-
-**Expected path:** `/home/user/demo/src/stroke_deepisles_demo/ui/assets/niivue.js`
-
-**Test:** Log the actual path and verify it exists
-
-### Theory D: Svelte Hydration Issue
-
-Gradio's Svelte frontend might be having hydration issues that prevent proper initialization.
-
-**Symptom:** Page shows "Loading..." but no JavaScript errors in console
-
-### Theory E: Uncaught Promise Rejection
-
-The async IIFE in js_on_load might be throwing an uncaught error that Gradio doesn't handle gracefully.
-
-**Test:** Wrap entire js_on_load in try-catch with console.error
-
----
-
-## COMPREHENSIVE FIX STRATEGY
-
-### Step 1: Add Polling for window.Niivue
-
-Don't assume window.Niivue exists. Poll for it:
-
-```javascript
-async function waitForNiivue(timeout = 10000) {
-    const start = Date.now();
-    while (!window.Niivue && Date.now() - start < timeout) {
-        await new Promise(r => setTimeout(r, 100));
-    }
-    return window.Niivue;
-}
-```
-
-### Step 2: Add Comprehensive Error Handling
-
-Catch all errors and display them visually:
-
-```javascript
-try {
-    const Niivue = await waitForNiivue();
-    if (!Niivue) {
-        element.innerHTML = '<div style="color:red;">NiiVue failed to load after 10s</div>';
-        return;
-    }
-    // ... rest of code
-} catch (e) {
-    console.error('NiiVue error:', e);
-    element.innerHTML = '<div style="color:red;">Error: ' + e.message + '</div>';
-}
-```
-
-### Step 3: Add Diagnostic Logging
-
-Log everything to console for debugging:
-
-```javascript
-console.log('[NiiVue] js_on_load started');
-console.log('[NiiVue] window.Niivue:', typeof window.Niivue);
-console.log('[NiiVue] element:', element);
-console.log('[NiiVue] volumeUrl:', volumeUrl);
-```
-
-### Step 4: Consider Alternative Loading Method
-
-If module script timing is fundamentally broken, use the `js` parameter in launch() to load NiiVue:
-
-```python
-NIIVUE_LOADER_JS = """
-(async () => {
-    const script = document.createElement('script');
-    script.type = 'module';
-    script.textContent = `import { Niivue } from '/gradio_api/file=...'; window.Niivue = Niivue;`;
-    document.head.appendChild(script);
-})();
-"""
-
-demo.launch(js=NIIVUE_LOADER_JS, ...)
-```
-
----
-
-## CONCLUSION
-
-The root cause is likely a **timing race condition** where `js_on_load` executes before the ES module in `head_paths` finishes loading.
-
-**Secondary issues:**
-- Stale comments referencing wrong parameters
-- Deprecated functions still in codebase
-- Test scripts using blocked CDN patterns
-- No error visibility when things fail
-
-**Research confirms:**
-1. `head_paths` IS the correct approach (GitHub #11649)
-2. BUT `head` parameter JS execution can be non-deterministic (GitHub #10250)
-3. Module scripts SHOULD execute before component mount
-4. Gradio's Svelte frontend may have its own timing quirks
-
-**Next step:** Add diagnostic logging AND polling for window.Niivue to handle timing uncertainty.
-
----
-
-## CRITICAL FINDING: THE UPSTREAM BLOCKER
-
-### The Real Root Cause: `allowed_paths` Bug in Gradio 5.x+
-
-**Source:** https://github.com/gradio-app/gradio/issues/11649
-
-**Finding:** `allowed_paths` has known bugs in Gradio 5.x and 6.x:
-> "Starting from Gradio 5.x, files are not accessible anymore via the `/file=` path even if they are in a subfolder of the project root."
-
-**Our Setup:**
-- Gradio version: `>=6.0.0,<7.0.0`
-- We use: `allowed_paths=[str(assets_dir)]`
-- We do NOT use: `gr.set_static_paths()`
-
-**The Bug:**
-- We tell Gradio to allow serving from `assets/` directory
-- niivue-loader.html contains: `import { Niivue } from '/gradio_api/file=.../niivue.js'`
-- The `/gradio_api/file=...` URL returns **404 NOT FOUND** due to the Gradio bug
-- Module import fails silently
-- `window.Niivue` is never set
-- `js_on_load` tries to use `window.Niivue` → undefined → error
-- Gradio frontend hangs
-
-### The Fix: Use `gr.set_static_paths()`
-
-**Source:** https://www.gradio.app/docs/gradio/set_static_paths
-
-**Key Requirements:**
-1. Call `gr.set_static_paths()` BEFORE creating Blocks
-2. Pass the assets directory path
-3. Files become accessible at `/gradio_api/file=<path>`
-
-**Example:**
-```python
-import gradio as gr
-from pathlib import Path
-
-# MUST be called BEFORE creating Blocks!
-assets_dir = Path(__file__).parent / "src" / "stroke_deepisles_demo" / "ui" / "assets"
-gr.set_static_paths(paths=[str(assets_dir)])
-
-# Now create the demo
-demo = create_app()
-
-demo.launch(
-    # allowed_paths may still be needed for runtime files
-    allowed_paths=[str(assets_dir)],
-    head_paths=[str(niivue_loader)],
-)
-```
-
----
-
-## COMPREHENSIVE FIX LIST
-
-### Fix 1: Add `gr.set_static_paths()` (CRITICAL - UPSTREAM BLOCKER)
-
-**Files to modify:**
-- `app.py` (root entry point)
-- `src/stroke_deepisles_demo/ui/app.py` (module entry point)
-
-**Change:**
-```python
-# At module level, BEFORE any demo creation
-import gradio as gr
-from pathlib import Path
-
-_ASSETS_DIR = Path(__file__).parent / "assets"  # Adjust path per file
-gr.set_static_paths(paths=[str(_ASSETS_DIR)])
-```
-
-### Fix 2: Add Polling for window.Niivue (DEFENSIVE)
-
-**File:** `src/stroke_deepisles_demo/ui/viewer.py`
-
-**Change:** Modify NIIVUE_ON_LOAD_JS and NIIVUE_UPDATE_JS to poll for window.Niivue
-
-### Fix 3: Update Stale Comments (CLEANUP)
-
-**File:** `src/stroke_deepisles_demo/ui/viewer.py:437-440`
-
-**Change:** Update comments to reference `head_paths` and `set_static_paths`
-
-### Fix 4: Update Error Messages (CLEANUP)
-
-**File:** `src/stroke_deepisles_demo/ui/viewer.py:473, 571`
-
-**Change:** Update error messages to be more helpful
-
-### Fix 5: Remove Deprecated Function (CLEANUP)
-
-**File:** `src/stroke_deepisles_demo/ui/viewer.py:95-109`
-
-**Change:** Remove `get_niivue_head_script()` or mark it more clearly
-
-### Fix 6: Update Test Script (CLEANUP)
-
-**File:** `scripts/test_js_on_load.py:38, 76`
-
-**Change:** Update to use local vendored NiiVue instead of CDN
-
----
-
-## FINAL DIAGNOSIS
-
-**One upstream blocker:** Missing `gr.set_static_paths()` call
-
-**Why:** Gradio 6.x has a known bug where `allowed_paths` doesn't properly enable file serving. The official workaround is `gr.set_static_paths()`.
-
-**Chain of failure:**
-```text
-Missing gr.set_static_paths()
-    ↓
-/gradio_api/file=.../niivue.js returns 404
-    ↓
-ES module import in niivue-loader.html fails
-    ↓
-window.Niivue is never set
-    ↓
-js_on_load checks window.Niivue → undefined
-    ↓
-Error thrown or NiiVue never initializes
-    ↓
-Gradio frontend may hang on "Loading..."
-```
-
-**Secondary issues** (should be fixed but not blocking):
-- Stale comments
-- Deprecated functions
-- Test scripts using CDN
-- No error visibility
-
-**Vendoring niivue.js WAS necessary** because:
-1. CDN imports are blocked by HF Spaces CSP
-2. Local files need to be served via Gradio's file serving
-3. `gr.set_static_paths()` enables this
-
----
-
-## VERIFICATION STEPS AFTER FIX
-
-1. Run locally: `python -m stroke_deepisles_demo.ui.app`
-2. Open browser DevTools → Network tab
-3. Check that `/gradio_api/file=.../niivue.js` returns 200 (not 404)
-4. Check console for "[NiiVue Loader] Loaded globally: function"
-5. Run segmentation and verify 3D viewer works
-6. Deploy to HF Spaces and repeat verification
-
----
-
-## DEEP AUDIT COMPLETE - FINAL SUMMARY
-
-**Audit Date:** 2025-12-09
-**Auditor:** Claude (Opus 4.5)
-**Status:** COMPLETE - All issues identified
-
-### DEFINITIVE LIST OF ALL ISSUES
-
-| # | Severity | File | Line(s) | Issue | Fix Required |
-|---|----------|------|---------|-------|--------------|
-| 1 | **CRITICAL** | `ui/app.py` | 284 | Missing `gr.set_static_paths()` before Blocks creation | Add call before `get_demo()` |
-| 2 | **CRITICAL** | `app.py` | 26 | Missing `gr.set_static_paths()` before Blocks creation | Add call before `get_demo()` |
-| 3 | HIGH | `viewer.py` | 437-440 | Stale comment says `gr.Blocks(head=...)` | Update to reference `head_paths` and `set_static_paths` |
-| 4 | HIGH | `viewer.py` | 473 | Wrong error message: "gr.Blocks(head=...)" | Update to reference `head_paths` |
-| 5 | MEDIUM | `viewer.py` | 530-533 | Stale comment says `head=` | Update to reference `head_paths` |
-| 6 | MEDIUM | `viewer.py` | 95-109 | Deprecated `get_niivue_head_script()` still exists | Remove or clearly mark |
-| 7 | LOW | `test_js_on_load.py` | 38, 76 | Uses CDN imports (blocked by CSP) | Update to use local NiiVue |
-
-### CONFIRMED NON-ISSUES
-
-These were investigated and confirmed NOT to be problems:
-
-| Item | Status | Reason |
-|------|--------|--------|
-| `niivue.js` vendoring | ✅ CORRECT | CDN is blocked by HF Spaces CSP |
-| `head_paths` approach | ✅ CORRECT | Official Gradio recommendation |
-| `js_on_load` usage | ✅ CORRECT | Proper way for component-level JS |
-| Path calculation in `ui/app.py` | ✅ CORRECT | Docker uses this entry point |
-| `niivue-loader.html` gitignored | ✅ CORRECT | Generated at runtime with env-specific path |
-| `allowed_paths` in launch() | ✅ CORRECT | Still needed for runtime files |
-
-### ROOT CAUSE CHAIN
-
-```text
-[UPSTREAM BLOCKER]
-Both entry points call get_demo() BEFORE gr.set_static_paths()
-    ↓
-Gradio 6.x bug: allowed_paths alone doesn't enable file serving
-    ↓
-/gradio_api/file=.../niivue.js returns 404
-    ↓
-<script type="module"> import fails silently
-    ↓
-window.Niivue is never set
-    ↓
-js_on_load throws "NiiVue not loaded" error
-    ↓
-Gradio frontend hangs on "Loading..."
-```
-
-### SEARCH PATTERNS USED
-
-All search patterns used to find issues:
-
-- `gradio_api|file=|allowed_paths|head_paths|set_static_paths|js_on_load`
-- `import\s*\(|from\s+['"]https?://`
-- `unpkg|jsdelivr|cdnjs|cdn\.|esm\.sh`
-- `window\.|document\.|<script|<link|<style`
-- `async|await|Promise|setTimeout`
-- `throw|Error\(|error|catch|try`
-- `https?://[^'\"\s]+`
-- `Path\(__file__|__file__`
-- `\.resolve\(\)|\.absolute\(\)`
-
-### CONFIDENCE LEVEL
-
-**100% confidence** that all JavaScript loading issues have been identified.
-
-The fix for Issue #1 and #2 (`gr.set_static_paths()`) is the **only upstream blocker**. All other issues are cleanup/hardening.
-
----
-
-## WEB-VERIFIED FIXES (December 2025)
-
-### Fix #1 & #2: `gr.set_static_paths()` - VERIFIED CORRECT
-
-**Source:** [Gradio set_static_paths Documentation](https://www.gradio.app/docs/gradio/set_static_paths)
-
-**Official Documentation Confirms:**
-- "Calling this function will set the static paths for all gradio applications defined in the same interpreter session"
-- Must be called **BEFORE** creating Blocks
-- Files become network-accessible via `/gradio_api/file=<path>`
-- Files are "served directly from the file system instead of being copied"
-
-**Correct Implementation:**
-```python
-import gradio as gr
-from pathlib import Path
-
-# MUST be called BEFORE get_demo() or create_app()
-_ASSETS_DIR = Path(__file__).parent / "assets"
-gr.set_static_paths(paths=[str(_ASSETS_DIR)])
-
-# Now create the demo
-demo = get_demo()
-demo.launch(...)
-```
-
----
-
-### `head_paths` Approach - VERIFIED CORRECT
-
-**Source:** [GitHub Issue #11649](https://github.com/gradio-app/gradio/issues/11649)
-
-**Gradio Maintainer @dawoodkhan82 explicitly recommended:**
-> "use the `head_paths` param where you can pass a path or list of paths to html files, and in that file you can include your `<script>`"
-
-**Issue Status:** Closed as resolved on August 25, 2025
-
-**Our Approach:** We're using `head_paths` correctly in `launch()`.
-
----
-
-### ES Module Load Order - VERIFIED
-
-**Source:** [MDN DOMContentLoaded](https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event)
-
-**Official MDN Documentation:**
-> "The DOMContentLoaded event fires when the HTML document has been completely parsed, and all deferred scripts (`<script defer src="…">` and `<script type="module">`) have downloaded and executed."
-
-**Source:** [MDN JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
-
-**Module Scope:**
-> "Module-defined variables are scoped to the module unless explicitly attached to the global object."
-
-**Our Approach:** We correctly use `window.Niivue = Niivue;` to expose globally.
-
-**Conclusion:** If `set_static_paths()` enables file serving, ES modules SHOULD execute before `js_on_load`. Polling is DEFENSIVE but may not be strictly necessary.
-
----
-
-### Gradio 6 Migration - VERIFIED COMPATIBLE
-
-**Source:** [Gradio 6 Migration Guide](https://www.gradio.app/main/guides/gradio-6-migration-guide)
-
-**Key Changes in Gradio 6:**
-- `theme`, `css`, `css_paths`, `js`, `head`, `head_paths` moved from `gr.Blocks()` to `launch()`
-- "Gradio 6.1.0 was uploaded on December 9, 2025"
-- "Only Gradio 6 will receive ongoing support"
-
-**Our Code:** Already uses `launch()` for these parameters - CORRECT.
-
----
-
-### `js_on_load` Parameter - VERIFIED EXISTS
-
-**Source:** [Gradio HTML Component Docs](https://www.gradio.app/docs/gradio/html)
-
-**Available Variables:**
-- `element` - References the HTML element
-- `trigger` - Function for dispatching events
-- `props` - Object for modifying values
-
-**Note:** Documentation does NOT explicitly address async/await patterns. Our async IIFE may work but is not officially documented.
-
----
-
-## FINAL VERIFIED FIX STRATEGY
-
-| Fix | Approach | Source | Confidence |
-|-----|----------|--------|------------|
-| #1-2: `set_static_paths()` | Call BEFORE `get_demo()` | [Gradio Docs](https://www.gradio.app/docs/gradio/set_static_paths) | ✅ 100% |
-| `head_paths` usage | Already correct | [GitHub #11649](https://github.com/gradio-app/gradio/issues/11649) | ✅ 100% |
-| Polling for Niivue | DEFENSIVE only | [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event) | ⚠️ Optional |
-| Stale comments | Cleanup | N/A | ✅ Do it |
-| Deprecated function | Remove | N/A | ✅ Do it |
-| Test script CDN | Update | N/A | ✅ Do it |
-
----
-
-## WHY `allowed_paths` ALONE DOESN'T WORK
-
-Based on [GitHub Issue #11649](https://github.com/gradio-app/gradio/issues/11649) and [Gradio File Access Guide](https://www.gradio.app/guides/file-access):
-
-**`allowed_paths`** (in `launch()`):
-- Controls security permissions for file access
-- Does NOT enable static file serving by itself
-- May require files to be copied to Gradio cache first
-
-**`gr.set_static_paths()`** (function call):
-- Enables direct file serving without caching
-- Files served with `Content-Disposition: inline`
-- Files become accessible at `/gradio_api/file=<path>`
-
-**The Bug:** In Gradio 5.x/6.x, using `allowed_paths` alone does not properly enable `/gradio_api/file=` serving for arbitrary paths. The `set_static_paths()` function is required.

docs/specs/archive/DIAGNOSTIC_HF_LOADING.md

@@ -1,228 +0,0 @@
-# Diagnostic: HuggingFace Spaces "Loading..." Forever Bug
-
-**Date**: 2025-12-10
-**Status**: UNRESOLVED - App stuck on "Loading..." despite backend running
-**Symptom**: HF Spaces shows "Running on T4", logs show successful startup, but UI never renders
-
-## Observed Behavior
-
-```
-===== Application Startup at 2025-12-10 02:10:47 =====
-* Running on local URL:  http://0.0.0.0:7860
-```
-
-- Backend Python starts successfully
-- Gradio server binds to `0.0.0.0:7860` (correct for Docker)
-- Frontend shows Gradio "Loading..." spinner indefinitely
-- No error messages in container logs
-
----
-
-## Research Findings
-
-### 1. Known Gradio Issues with Custom JavaScript
-
-#### Issue #11649: Custom JS via `head` fails with 404
-**Source**: [GitHub Issue #11649](https://github.com/gradio-app/gradio/issues/11649)
-
-Users report custom JavaScript files failing to load even with `allowed_paths` configured.
-
-**Solution found**: Use `head_paths` parameter instead of `head`:
-```python
-with gr.Blocks(head_paths=["custom.html"]) as demo:
-```
-
-Alternative URL format that works: `/gradio_api/file=static/custom.js` instead of `/file/static/custom.js`
-
-#### Issue #10250: JavaScript in `head` param not executing
-**Source**: [GitHub Issue #10250](https://github.com/gradio-app/gradio/issues/10250)
-
-JavaScript occasionally executes after extended delays (5-10+ minutes) or not at all.
-
-**Key insight**: `gr.HTML()` components intentionally do NOT execute JavaScript for security. Only `head` parameter supports JS execution.
-
-#### Issue #6426: gr.Blocks head argument not working
-**Source**: [GitHub Issue #6426](https://github.com/gradio-app/gradio/issues/6426)
-
-Two critical bugs:
-1. Only the FIRST script tag from `head` is applied
-2. Script tags are injected AFTER page loads, preventing execution
-
-**Fixed in PR #6639** - but may require specific Gradio version.
-
-### 2. ES Module Script Behavior
-
-**Source**: [ES Modules Explainer](https://gist.github.com/jakub-g/385ee6b41085303a53ad92c7c8afd7a6)
-
-Key facts about `<script type="module">`:
-- **Always deferred by default** - does NOT block HTML parsing
-- **No way to make it blocking** - even without async/defer
-- If import fails, script silently fails but shouldn't block page
-
-**Implication**: Our NiiVue loader (`<script type="module">`) should NOT be blocking Gradio's rendering. The issue is elsewhere.
-
-### 3. HuggingFace Spaces Known Issues
-
-#### Origin Mismatch Bug (Issue #10893)
-**Source**: [HF Forum Thread](https://discuss.huggingface.co/t/gradio-space-javascript-not-executing-fields-not-populating-persistent-syntaxerror-in-browser-console/163689)
-
-Gradio's `postMessage` calls fail due to origin mismatch between `https://huggingface.co` and the actual Space URL. This can prevent JavaScript execution entirely.
-
-#### Docker "Running" But "Loading..." Forever
-**Source**: [HF Forum Thread](https://discuss.huggingface.co/t/space-stuck-in-building-despite-gradio-welcome-port/36890)
-
-Common causes:
-- Binding to `127.0.0.1` instead of `0.0.0.0` (**we already fixed this**)
-- Incorrect port configuration (**we use 7860**)
-- Private Space authentication issues (**our Space is public**)
-
-#### Interface Not Showing Despite Running
-**Source**: [HF Forum Thread](https://discuss.huggingface.co/t/bug-free-gradio-interface-not-loading-on-hfs/25102)
-
-Assigning Interface to a variable before launching can cause this:
-```python
-# WRONG
-iface = gr.Interface(...).launch()
-
-# RIGHT
-gr.Interface(...).launch()
-```
-
-**Our code**: We use `get_demo().launch()` which SHOULD be correct.
-
-### 4. Gradio set_static_paths Requirements
-
-**Source**: [Gradio Docs](https://www.gradio.app/docs/gradio/set_static_paths)
-
-- Must be called BEFORE creating Blocks
-- Affects ALL Gradio apps in the same interpreter session
-- Exposes entire directories to network (security consideration)
-
-**Our code**: We call `gr.set_static_paths()` at module level before imports. ✅
-
-### 5. Browser Cache Issues
-
-**Source**: [HF Forum Thread](https://discuss.huggingface.co/t/issue-with-perpetual-loading-on-the-space/35684)
-
-Some "Loading..." issues resolved by clearing browser cache. Works in one browser but not another.
-
-**Unlikely cause**: This is a fresh deployment, not a cache issue.
-
----
-
-## Our Current Implementation
-
-### JavaScript Loading Flow
-
-1. `app.py` (root entry point for HF Spaces Docker):
-   - Calls `gr.set_static_paths(paths=[str(_ASSETS_DIR)])` before imports
-   - Imports `get_demo()` and `get_niivue_loader_path()`
-   - Launches with `head_paths=[str(niivue_loader)]`
-
-2. `ui/app.py` (also calls set_static_paths):
-   - Module-level `gr.set_static_paths()` before imports
-   - Creates demo with `js_on_load=NIIVUE_ON_LOAD_JS` on gr.HTML component
-
-3. `viewer.py`:
-   - Generates `niivue-loader.html` at runtime with absolute path
-   - Content: `<script type="module">import { Niivue } from '/gradio_api/file=...'</script>`
-
-### Files Involved
-
-| File | Purpose | Status |
-|------|---------|--------|
-| `app.py` (root) | HF Spaces entry point | Uses head_paths ✅ |
-| `src/.../ui/app.py` | Main UI module | Uses js_on_load ✅ |
-| `src/.../ui/viewer.py` | NiiVue loader generation | Generates at runtime ✅ |
-| `src/.../ui/components.py` | UI components | Uses NIIVUE_ON_LOAD_JS ✅ |
-| `src/.../ui/assets/niivue.js` | Vendored NiiVue library | 2.9MB, tracked ✅ |
-| `src/.../ui/assets/niivue-loader.html` | Generated loader | gitignored ✅ |
-
-### Dockerfile CMD
-
-```dockerfile
-CMD ["python", "-m", "stroke_deepisles_demo.ui.app"]
-```
-
-This runs `ui/app.py` as `__main__`, which should execute our launch() with head_paths.
-
----
-
-## Hypotheses
-
-### H1: `js_on_load` Breaking Gradio Initialization
-
-**Theory**: The `js_on_load` parameter on `gr.HTML` might be executing before Gradio fully initializes, causing a crash.
-
-**Evidence**: Our code has `js_on_load=NIIVUE_ON_LOAD_JS` which is a complex async IIFE.
-
-**Test**: Remove `js_on_load` parameter and see if app loads.
-
-### H2: `head_paths` Not Being Applied on HF Spaces
-
-**Theory**: The `head_paths` parameter might not be reaching the frontend on HF Spaces due to Docker networking or Gradio configuration.
-
-**Evidence**: Issue #11649 shows head-related parameters have bugs.
-
-**Test**: Check browser Network tab for niivue.js 404 or missing script.
-
-### H3: demo.load() Blocking Initial Render
-
-**Theory**: The `demo.load(initialize_case_selector, ...)` call might be blocking the initial UI render.
-
-**Evidence**: `initialize_case_selector()` calls `list_case_ids()` which loads HuggingFace dataset.
-
-**Test**: Remove demo.load() and see if app loads.
-
-### H4: Double set_static_paths Causing Conflict
-
-**Theory**: Both `app.py` (root) and `ui/app.py` call `gr.set_static_paths()`. This might cause conflicts.
-
-**Evidence**: Gradio docs say "affects ALL Gradio apps in same interpreter session".
-
-**Test**: Remove one of the set_static_paths calls.
-
-### H5: Module Import Order Issue
-
-**Theory**: The order of imports and set_static_paths calls might matter on HF Spaces but not locally.
-
-**Evidence**: We have `noqa: E402` comments indicating non-standard import order.
-
-**Test**: Trace exact import order and when set_static_paths is effective.
-
-### H6: Path Resolution Different in Docker
-
-**Theory**: `Path(__file__).resolve()` might resolve to different paths in Docker vs local.
-
-**Evidence**: We use absolute paths for NIIVUE_JS_URL computed at import time.
-
-**Test**: Log the actual paths being computed in Docker.
-
----
-
-## Diagnostic Steps to Try
-
-1. **Minimal Test**: Create a branch that removes ALL custom JS and test if basic Gradio loads
-2. **Log Paths**: Add logging to show exactly what paths are computed in Docker
-3. **Browser DevTools**: Check Network tab and Console for errors (if accessible)
-4. **Gradio Version**: Verify we're using a version with all relevant fixes
-5. **HF Spaces Logs**: Check full container logs for any Python errors not shown in UI
-
----
-
-## Related Documentation
-
-- [AUDIT_JS_LOADING_ISSUES.md](./AUDIT_JS_LOADING_ISSUES.md) - Previous audit of JavaScript loading issues
-- [docs/specs/24-bug-hf-spaces-loading-forever.md](./docs/specs/24-bug-hf-spaces-loading-forever.md) - Original bug specification
-
----
-
-## External Resources
-
-- [Gradio Custom CSS and JS Guide](https://www.gradio.app/guides/custom-CSS-and-JS)
-- [Gradio File Access Guide](https://www.gradio.app/guides/file-access)
-- [Gradio set_static_paths Docs](https://www.gradio.app/docs/gradio/set_static_paths)
-- [Gradio Issue #11649](https://github.com/gradio-app/gradio/issues/11649) - head_paths solution
-- [Gradio Issue #10250](https://github.com/gradio-app/gradio/issues/10250) - head JS not executing
-- [Gradio Issue #6426](https://github.com/gradio-app/gradio/issues/6426) - head argument bugs
-- [HF Spaces Docker Guide](https://huggingface.co/docs/hub/spaces-sdks-docker)

docs/specs/archive/ROOT_CAUSE_ANALYSIS.md

@@ -1,230 +0,0 @@
-# Root Cause Analysis: HF Spaces "Loading..." Forever (Issue #24)
-
-**Date:** 2025-12-10
-**Status:** IN PROGRESS
-**Branch:** `debug/niivue-head-script-loading`
-
----
-
-## Executive Summary
-
-The HuggingFace Spaces app hangs on "Loading..." indefinitely because **dynamic ES module `import()` inside `gr.HTML(js_on_load=...)` blocks Gradio's Svelte frontend from hydrating**.
-
-This was proven empirically in our own A/B test documented in `docs/specs/24-bug-hf-spaces-loading-forever.md`:
-
-> **Diagnostic test:** Disabled `js_on_load` parameter entirely.
-> **Result:** App loads perfectly! Everything works EXCEPT Interactive 3D viewer.
-
----
-
-## First Principles Analysis
-
-### How Gradio Renders
-
-1. Server sends initial HTML with loading spinner
-2. Gradio's Svelte app downloads and hydrates
-3. Components mount, including `gr.HTML`
-4. `js_on_load` executes during component mount
-5. Loading spinner clears when hydration completes
-
-### Why Dynamic Import Blocks Hydration
-
-The current `js_on_load` code does this (viewer.py:497):
-
-```javascript
-const module = await import(niivueUrl);  // <-- BLOCKS HYDRATION
-window.Niivue = module.Niivue;
-```
-
-**Problem:** If this `import()` hangs (CSP issues, network issues, MIME type issues, etc.), the async IIFE never resolves, and Svelte's mount lifecycle stalls. HF Spaces silently blocks or delays these imports.
-
-### Why `head=` Works
-
-The `head=` parameter injects content into `<head>` BEFORE Gradio hydrates:
-
-```html
-<head>
-  <!-- Injected by head= -->
-  <script type="module">
-    const { Niivue } = await import('/gradio_api/file=.../niivue.js');
-    window.Niivue = Niivue;
-  </script>
-</head>
-```
-
-**Key insight:** Even if this script fails, Gradio still loads because:
-1. Script tags in `<head>` don't block Svelte hydration
-2. They run BEFORE Gradio components mount
-3. Failure just means `window.Niivue` is undefined (graceful degradation)
-
-Then `js_on_load` simply USES `window.Niivue` (no imports):
-
-```javascript
-// No import() - just use what's already loaded
-const Niivue = window.Niivue;
-if (!Niivue) {
-  // Show error message, don't block
-}
-```
-
----
-
-## Evidence-Based Conclusions
-
-| Claim | Evidence | Validated |
-|-------|----------|-----------|
-| Dynamic `import()` in `js_on_load` blocks HF Spaces | A/B test: disabling `js_on_load` makes app load | **YES** |
-| Vendored NiiVue file is served correctly | Local testing shows 200 response | **YES** |
-| `gr.set_static_paths()` is called correctly | Called before any Blocks in both entry points | **YES** |
-| `allowed_paths` is configured correctly | Both entry points pass `allowed_paths` | **YES** |
-| `demo.load()` doesn't block initial render | Gradio docs confirm load runs post-hydration | **YES** |
-
----
-
-## The Fix
-
-### Before (Broken)
-
-```python
-# viewer.py - NIIVUE_ON_LOAD_JS
-const module = await import(niivueUrl);  # Dynamic import in js_on_load
-window.Niivue = module.Niivue;
-```
-
-```python
-# ui/app.py - No head= parameter, relying on js_on_load to load NiiVue
-demo.launch(...)  # No head= parameter
-```
-
-### After (Fixed)
-
-```python
-# ui/app.py - Load NiiVue via head= BEFORE Gradio hydrates
-from stroke_deepisles_demo.ui.viewer import get_niivue_head_html
-
-get_demo().launch(
-    head=get_niivue_head_html(),  # Inject NiiVue loader into <head>
-    ...
-)
-```
-
-```python
-# viewer.py - NIIVUE_ON_LOAD_JS just USES window.Niivue (no import)
-const Niivue = window.Niivue;
-if (!Niivue) {
-    // Graceful error - don't block Gradio
-    container.innerHTML = 'NiiVue failed to load...';
-    return;
-}
-```
-
----
-
-## Why Previous Attempts Failed
-
-### Attempt 1: CDN Import
-**Failed because:** HF Spaces CSP blocks external CDN imports
-
-### Attempt 2: Vendor NiiVue + Dynamic Import in js_on_load
-**Failed because:** Dynamic `import()` in js_on_load still blocks Svelte hydration, even for local files
-
-### Attempt 3: Remove head= and make js_on_load self-sufficient
-**Failed because:** This approach doubled down on the broken pattern (dynamic import in js_on_load)
-
-### This Fix: head= for loading + js_on_load for init only
-**Should work because:** Matches the architecture documented in spec 24 and proven by the A/B test
-
----
-
-## Test Strategy
-
-1. **Local sanity:** Run with fix, verify app loads and NiiVue works
-2. **A/B comparison:** Compare behavior with/without `head=` parameter
-3. **HF Spaces deployment:** Push to hf-personal remote and verify
-4. **Console inspection:** Check for `[NiiVue Loader]` logs in browser console
-
----
-
-## Files to Modify
-
-| File | Change |
-|------|--------|
-| `src/stroke_deepisles_demo/ui/viewer.py` | Remove `import()` from js_on_load, use `window.Niivue` directly |
-| `src/stroke_deepisles_demo/ui/app.py` | Add `head=get_niivue_head_html()` to launch() |
-| `app.py` | Same as above for local dev |
-
----
-
-## Update (2025-12-10): Web Research Findings
-
-### Critical Discovery: The Issue is Gradio, NOT HuggingFace Spaces
-
-**Web search confirmed:**
-- HF Spaces DOES support JavaScript, WebGL, ES modules
-- Working examples: Unity WebGL, Three.js games, Gaussian Splat Viewer
-- The issue is specifically **Gradio's handling of custom JavaScript**
-
-**Sources:**
-- [HF Unity WebGL Template](https://github.com/huggingface/Unity-WebGL-template-for-Hugging-Face-Spaces)
-- [WebGL Gaussian Splat Viewer on HF](https://huggingface.co/spaces/cakewalk/splat)
-- [HF Forum: Gradio HTML with JS doesn't work](https://discuss.huggingface.co/t/gradio-html-component-with-javascript-code-dont-work/37316)
-
-### Known Gradio Limitations
-
-1. **`gr.HTML()` cannot load `<script>` tags** - They're stripped for security
-2. **postMessage origin mismatch bug** (Gradio Issue #10893) - Causes SyntaxError
-3. **`js_on_load` with dynamic `import()`** - Can block Svelte hydration
-
-### Alternative Approaches NOT YET TRIED
-
-#### Option 1: `demo.load(_js=...)` with globalThis
-
-```python
-scripts = """
-async () => {
-    const script = document.createElement("script");
-    script.src = "/gradio_api/file=.../niivue.js";
-    script.type = "module";
-    document.head.appendChild(script);
-    await new Promise(resolve => script.onload = resolve);
-    globalThis.Niivue = window.Niivue;
-}
-"""
-demo.load(None, None, None, _js=scripts)
-```
-
-Source: [HF Forum workaround](https://discuss.huggingface.co/t/gradio-html-component-with-javascript-code-dont-work/37316)
-
-#### Option 2: `gr.Blocks(js=...)` parameter
-
-```python
-with gr.Blocks(js="() => { /* load NiiVue */ }") as demo:
-    ...
-```
-
-Source: [Gradio Custom CSS/JS Guide](https://www.gradio.app/guides/custom-CSS-and-JS)
-
-#### Option 3: Static HTML Space (Nuclear Option)
-
-If all Gradio approaches fail, create a **Static HTML Space** with pure JS/HTML/CSS.
-NiiVue would definitely work since WebGL examples exist on HF Spaces.
-
-Would require rebuilding the UI without Gradio.
-
-### Decision Tree
-
-```
-PR #28 (head= approach) works? ──YES──> Done!
-        │
-        NO
-        ↓
-Try demo.load(_js=...) works? ──YES──> Done!
-        │
-        NO
-        ↓
-Try gr.Blocks(js=...) works? ──YES──> Done!
-        │
-        NO
-        ↓
-Static HTML Space (rebuild UI without Gradio)
-```

docs/specs/archive/data-discovery.md

@@ -1,66 +0,0 @@
-# data discovery & verification protocol
-
-## purpose
-To establish a rigorous, reproducible process for exploring, verifying, and documenting external data sources (Hugging Face Datasets, BIDS repos, etc.) before integrating them into the production codebase. This prevents "schema guessing" and ensures strict typing aligns with reality.
-
-## principles
-1.  **No Assumptions**: Never assume column names, file formats, or data types. Verify them programmatically.
-2.  **Isolation**: Discovery scripts and their outputs must be isolated from production code and source control.
-3.  **Reproducibility**: The discovery process must be scriptable and reproducible, not a series of manual CLI commands.
-
-## standard locations
-
-### scripts
-All discovery logic resides in:
-```
-scripts/discovery/
-├── __init__.py
-├── inspect_hf_dataset.py   # e.g., Generic HF inspector
-├── verify_bids_layout.py   # e.g., BIDS validator
-└── ...
-```
-
-### data & artifacts
-All downloaded samples, temporary outputs, and schema reports reside in:
-```
-data/
-├── isles24/             # Extracted ISLES24 data (IGNORED)
-└── discovery/           # Schema reports, samples (IGNORED)
-```
-
-## discovery workflow
-
-### 1. implementation
-Write a focused script in `scripts/discovery/` that:
-- Connects to the data source (e.g., HF Hub).
-- Fetches *metadata* or a *minimal sample* (streaming mode preferred).
-- Prints/Logs:
-    - Feature keys (column names).
-    - Data types (Arrow types, Python types).
-    - Non-null counts (if feasible).
-    - A sample row structure.
-
-### 2. execution
-Run the script from the project root:
-```bash
-uv run scripts/discovery/inspect_hf_dataset.py > data/discovery/schema_report.txt
-```
-
-### 3. verification
-Manually review `data/discovery/schema_report.txt`.
-- **Check**: Do column names match `CaseAdapter` expectations?
-- **Check**: Are file paths strings or objects?
-- **Check**: Are required fields (DWI, ADC) actually present?
-
-### 4. remediation
-If the report contradicts the code/specs:
-1.  Update the spec (`docs/specs/`) to reflect reality.
-2.  Update the code (`src/.../adapter.py`) to handle the actual schema.
-3.  Add a regression test if the edge case is complex.
-
-## git configuration
-Ensure `.gitignore` includes:
-```gitignore
-data/isles24/
-data/discovery/
-```

docs/specs/frontend/36-frontend-without-gradio-hf-spaces.md

@@ -0,0 +1,1102 @@
+# Spec 36: React Frontend + FastAPI Backend for HuggingFace Spaces
+
+**Status**: APPROVED PLAN
+**Date**: 2025-12-11
+**Goal**: Replace Gradio with React frontend for NiiVue, FastAPI backend for DeepISLES
+
+---
+
+## Security Note: CVE-2025-55182 Does NOT Affect This App
+
+**CVE-2025-55182 (React2Shell)** is a critical RCE vulnerability disclosed December 3, 2025.
+
+| What | Status |
+|------|--------|
+| **React 19.x with RSC** | VULNERABLE if using Server Components |
+| **React 19.x client-only** | SAFE - no Server Components = no vulnerability |
+| **React 18.x** | NOT AFFECTED - no Server Components |
+
+**We use React 19.2.0** which is **safe for our use case** because:
+- CVE-2025-55182 only affects React Server Components (RSC)
+- Our app is **client-only** (Static Space = no server-side rendering)
+- We do not use React Server Components
+- The vulnerability requires SSR/RSC to be exploitable
+
+Sources:
+- [React Security Advisory](https://react.dev/blog/2025/12/03/critical-security-vulnerability-in-react-server-components)
+- [Wiz Analysis](https://www.wiz.io/blog/critical-vulnerability-in-react-cve-2025-55182)
+
+---
+
+## The Stack
+
+| Component | Technology | Version | Purpose |
+|-----------|------------|---------|---------|
+| **Frontend Framework** | React | 19.2.0 | UI components (client-only, see security note) |
+| **Type Safety** | TypeScript | 5.9.3 | Type checking |
+| **Build Tool** | Vite | 7.2.4 | Fast builds, HMR |
+| **CSS Framework** | Tailwind CSS | 4.1.17 | Utility-first styling |
+| **3D Viewer** | @niivue/niivue | 0.65.0 | WebGL2 NIfTI viewer |
+| **Testing** | Vitest + Playwright | 4.0.15 / 1.57.0 | Unit, integration, E2E tests |
+| **Backend Framework** | FastAPI | 0.124.2 | Python REST API |
+| **ML Pipeline** | DeepISLES | existing | Stroke segmentation |
+
+---
+
+## Architecture: Two HuggingFace Spaces
+
+You **need both** because:
+- **Static Space** = JavaScript only (React, NiiVue) - cannot run Python
+- **Docker Space** = Python runtime (FastAPI, DeepISLES, PyTorch)
+
+```
+┌─────────────────────────────────────┐
+│  HuggingFace Static Space           │
+│  stroke-viewer-frontend             │
+│                                     │
+│  React 19 + TypeScript + Tailwind   │
+│  @niivue/niivue for 3D viewing      │
+│                                     │
+│  Serves: index.html, JS, CSS        │
+│  Always on, never sleeps            │
+└──────────────┬──────────────────────┘
+               │ HTTPS API calls
+               ▼
+┌─────────────────────────────────────┐
+│  HuggingFace Docker Space           │
+│  stroke-viewer-api                  │
+│                                     │
+│  FastAPI + DeepISLES + PyTorch      │
+│                                     │
+│  Endpoints:                         │
+│  - GET  /api/cases                  │
+│  - POST /api/segment                │
+│  - GET  /api/files/{path}           │
+│                                     │
+│  Sleeps after 48h inactivity        │
+└─────────────────────────────────────┘
+```
+
+---
+
+## Project Structure
+
+```
+stroke-viewer/
+├── frontend/                    # Static Space
+│   ├── src/
+│   │   ├── components/
+│   │   │   ├── NiiVueViewer.tsx
+│   │   │   ├── CaseSelector.tsx
+│   │   │   ├── MetricsPanel.tsx
+│   │   │   └── Layout.tsx
+│   │   ├── hooks/
+│   │   │   └── useSegmentation.ts
+│   │   ├── api/
+│   │   │   └── client.ts
+│   │   ├── types/
+│   │   │   └── index.ts
+│   │   ├── App.tsx
+│   │   ├── main.tsx
+│   │   └── index.css
+│   ├── public/
+│   ├── index.html
+│   ├── vite.config.ts
+│   ├── tsconfig.json
+│   ├── package.json
+│   └── README.md                # HF Spaces YAML config
+│
+├── backend/                     # Docker Space
+│   ├── api/
+│   │   ├── __init__.py
+│   │   ├── main.py              # FastAPI app
+│   │   ├── routes.py            # API endpoints
+│   │   └── schemas.py           # Pydantic models
+│   ├── Dockerfile
+│   ├── requirements.txt
+│   └── README.md                # HF Spaces YAML config
+│
+└── README.md                    # Project overview
+```
+
+---
+
+## Frontend Implementation
+
+### package.json
+
+```json
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test"
+  },
+  "dependencies": {
+    "@niivue/niivue": "^0.65.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.57.0",
+    "@tailwindcss/vite": "^4.1.17",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@vitest/coverage-v8": "^4.0.15",
+    "eslint": "^9.39.1",
+    "tailwindcss": "^4.1.17",
+    "typescript": "~5.9.3",
+    "vite": "^7.2.4",
+    "vitest": "^4.0.15"
+  }
+}
+```
+
+**Why these versions:**
+- `react` / `react-dom` **19.2.0**: Latest React 19 - client-only so CVE-2025-55182 doesn't apply
+- `@niivue/niivue` **0.65.0**: Latest stable (Dec 2025)
+- `vite` **7.2.4**: Latest stable v7
+- `vitest` **4.0.15**: Fast unit testing with React Testing Library
+- `@playwright/test` **1.57.0**: E2E browser testing
+- `tailwindcss` **4.1.17**: Latest stable v4
+- `typescript` **5.9.3**: Latest stable
+- ESLint included for code quality in CI
+
+### vite.config.ts
+
+```typescript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  build: {
+    outDir: 'dist',
+  },
+})
+```
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}
+```
+
+### src/index.css
+
+```css
+@import "tailwindcss";
+```
+
+### src/main.tsx
+
+```tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+import './index.css'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)
+```
+
+### src/App.tsx
+
+```tsx
+import { useState } from 'react'
+import { Layout } from './components/Layout'
+import { CaseSelector } from './components/CaseSelector'
+import { NiiVueViewer } from './components/NiiVueViewer'
+import { MetricsPanel } from './components/MetricsPanel'
+import { useSegmentation } from './hooks/useSegmentation'
+
+export default function App() {
+  const [selectedCase, setSelectedCase] = useState<string | null>(null)
+  const { result, isLoading, error, runSegmentation } = useSegmentation()
+
+  const handleRunSegmentation = async () => {
+    if (selectedCase) {
+      await runSegmentation(selectedCase)
+    }
+  }
+
+  return (
+    <Layout>
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+        {/* Left Panel: Controls */}
+        <div className="space-y-4">
+          <CaseSelector
+            selectedCase={selectedCase}
+            onSelectCase={setSelectedCase}
+          />
+          <button
+            onClick={handleRunSegmentation}
+            disabled={!selectedCase || isLoading}
+            className="w-full bg-blue-600 hover:bg-blue-700 disabled:bg-gray-400
+                       text-white font-medium py-3 px-4 rounded-lg transition"
+          >
+            {isLoading ? 'Processing...' : 'Run Segmentation'}
+          </button>
+          {error && (
+            <div className="bg-red-100 text-red-700 p-3 rounded-lg">
+              {error}
+            </div>
+          )}
+          {result && <MetricsPanel metrics={result.metrics} />}
+        </div>
+
+        {/* Right Panel: Viewer */}
+        <div className="lg:col-span-2">
+          {result ? (
+            <NiiVueViewer
+              backgroundUrl={result.dwiUrl}
+              overlayUrl={result.predictionUrl}
+            />
+          ) : (
+            <div className="bg-gray-900 rounded-lg h-[500px] flex items-center justify-center">
+              <p className="text-gray-400">
+                Select a case and run segmentation to view results
+              </p>
+            </div>
+          )}
+        </div>
+      </div>
+    </Layout>
+  )
+}
+```
+
+### src/components/Layout.tsx
+
+```tsx
+import { ReactNode } from 'react'
+
+interface LayoutProps {
+  children: ReactNode
+}
+
+export function Layout({ children }: LayoutProps) {
+  return (
+    <div className="min-h-screen bg-gray-950 text-white">
+      <header className="border-b border-gray-800 py-4">
+        <div className="container mx-auto px-4">
+          <h1 className="text-2xl font-bold">Stroke Lesion Segmentation</h1>
+          <p className="text-gray-400 text-sm mt-1">
+            DeepISLES segmentation on ISLES24 dataset
+          </p>
+        </div>
+      </header>
+      <main className="container mx-auto px-4 py-6">
+        {children}
+      </main>
+    </div>
+  )
+}
+```
+
+### src/components/NiiVueViewer.tsx
+
+```tsx
+import { useRef, useEffect } from 'react'
+import { Niivue } from '@niivue/niivue'
+
+interface NiiVueViewerProps {
+  backgroundUrl: string
+  overlayUrl?: string
+}
+
+export function NiiVueViewer({ backgroundUrl, overlayUrl }: NiiVueViewerProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const nvRef = useRef<Niivue | null>(null)
+
+  useEffect(() => {
+    if (!canvasRef.current) return
+
+    // Only instantiate NiiVue once; reuse for volume reloads
+    let nv = nvRef.current
+    if (!nv) {
+      nv = new Niivue({
+        backColor: [0.05, 0.05, 0.05, 1],
+        show3Dcrosshair: true,
+        crosshairColor: [1, 0, 0, 0.5],
+      })
+      nv.attachToCanvas(canvasRef.current)
+      nvRef.current = nv
+    }
+
+    // Build volumes array - always reload when URLs change
+    const volumes: Array<{ url: string; colormap: string; opacity: number }> = [
+      { url: backgroundUrl, colormap: 'gray', opacity: 1 },
+    ]
+
+    if (overlayUrl) {
+      volumes.push({
+        url: overlayUrl,
+        colormap: 'red',
+        opacity: 0.5,
+      })
+    }
+
+    // Load volumes (async but we don't await - just fire off)
+    void nv.loadVolumes(volumes)
+
+    // Cleanup on unmount - CRITICAL: Release WebGL context
+    // Browsers limit WebGL contexts (~16 in Chrome). Without cleanup,
+    // navigating between results will exhaust contexts and break the viewer.
+    return () => {
+      if (nvRef.current) {
+        // Capture gl BEFORE cleanup (cleanup may null internal state)
+        const gl = nvRef.current.gl
+        try {
+          // NiiVue's cleanup() releases event listeners and observers
+          // See: https://niivue.github.io/niivue/devdocs/classes/Niivue.html#cleanup
+          nvRef.current.cleanup()
+          // Force WebGL context loss to free GPU memory immediately
+          if (gl) {
+            const ext = gl.getExtension('WEBGL_lose_context')
+            ext?.loseContext()
+          }
+        } catch {
+          // Ignore cleanup errors
+        }
+        nvRef.current = null
+      }
+    }
+  }, [backgroundUrl, overlayUrl])
+
+  return (
+    <div className="bg-gray-900 rounded-lg p-2">
+      <canvas
+        ref={canvasRef}
+        className="w-full h-[500px] rounded"
+      />
+      <div className="flex gap-4 mt-2 text-xs text-gray-400">
+        <span>Scroll: Navigate slices</span>
+        <span>Drag: Adjust contrast</span>
+        <span>Right-click: Pan</span>
+      </div>
+    </div>
+  )
+}
+```
+
+### src/components/CaseSelector.tsx
+
+```tsx
+import { useEffect, useState } from 'react'
+import { apiClient } from '../api/client'
+
+interface CaseSelectorProps {
+  selectedCase: string | null
+  onSelectCase: (caseId: string) => void
+}
+
+export function CaseSelector({ selectedCase, onSelectCase }: CaseSelectorProps) {
+  const [cases, setCases] = useState<string[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    const fetchCases = async () => {
+      try {
+        const data = await apiClient.getCases()
+        setCases(data.cases)
+      } catch (err) {
+        setError('Failed to load cases')
+        console.error(err)
+      } finally {
+        setLoading(false)
+      }
+    }
+    fetchCases()
+  }, [])
+
+  if (loading) {
+    return (
+      <div className="bg-gray-800 rounded-lg p-4">
+        <p className="text-gray-400">Loading cases...</p>
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className="bg-red-900 rounded-lg p-4">
+        <p className="text-red-300">{error}</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="bg-gray-800 rounded-lg p-4">
+      <label className="block text-sm font-medium mb-2">
+        Select Case
+      </label>
+      <select
+        value={selectedCase || ''}
+        onChange={(e) => onSelectCase(e.target.value)}
+        className="w-full bg-gray-700 border border-gray-600 rounded-lg px-3 py-2
+                   text-white focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+      >
+        <option value="">Choose a case...</option>
+        {cases.map((caseId) => (
+          <option key={caseId} value={caseId}>
+            {caseId}
+          </option>
+        ))}
+      </select>
+    </div>
+  )
+}
+```
+
+### src/components/MetricsPanel.tsx
+
+```tsx
+interface Metrics {
+  caseId: string
+  diceScore: number | null
+  volumeMl: number | null
+  elapsedSeconds: number
+}
+
+interface MetricsPanelProps {
+  metrics: Metrics
+}
+
+export function MetricsPanel({ metrics }: MetricsPanelProps) {
+  return (
+    <div className="bg-gray-800 rounded-lg p-4 space-y-3">
+      <h3 className="font-medium text-lg">Results</h3>
+
+      <div className="grid grid-cols-2 gap-3 text-sm">
+        <div>
+          <span className="text-gray-400">Case:</span>
+          <span className="ml-2 font-mono">{metrics.caseId}</span>
+        </div>
+
+        {metrics.diceScore !== null && (
+          <div>
+            <span className="text-gray-400">Dice Score:</span>
+            <span className="ml-2 font-mono text-green-400">
+              {metrics.diceScore.toFixed(3)}
+            </span>
+          </div>
+        )}
+
+        {metrics.volumeMl !== null && (
+          <div>
+            <span className="text-gray-400">Volume:</span>
+            <span className="ml-2 font-mono">{metrics.volumeMl.toFixed(2)} mL</span>
+          </div>
+        )}
+
+        <div>
+          <span className="text-gray-400">Time:</span>
+          <span className="ml-2 font-mono">{metrics.elapsedSeconds.toFixed(1)}s</span>
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+### src/api/client.ts
+
+```typescript
+// API base URL - configure via environment variable
+const API_BASE = import.meta.env.VITE_API_URL || 'https://your-backend.hf.space'
+
+interface CasesResponse {
+  cases: string[]
+}
+
+interface SegmentResponse {
+  caseId: string
+  diceScore: number | null
+  volumeMl: number | null
+  elapsedSeconds: number
+  dwiUrl: string
+  predictionUrl: string
+}
+
+class ApiClient {
+  private baseUrl: string
+
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl
+  }
+
+  async getCases(): Promise<CasesResponse> {
+    const response = await fetch(`${this.baseUrl}/api/cases`)
+    if (!response.ok) {
+      throw new Error(`Failed to fetch cases: ${response.statusText}`)
+    }
+    return response.json()
+  }
+
+  async runSegmentation(caseId: string, fastMode = true): Promise<SegmentResponse> {
+    const response = await fetch(`${this.baseUrl}/api/segment`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        case_id: caseId,
+        fast_mode: fastMode,
+      }),
+    })
+    if (!response.ok) {
+      throw new Error(`Segmentation failed: ${response.statusText}`)
+    }
+    return response.json()
+  }
+}
+
+export const apiClient = new ApiClient(API_BASE)
+```
+
+### src/hooks/useSegmentation.ts
+
+```typescript
+import { useState, useCallback } from 'react'
+import { apiClient } from '../api/client'
+
+interface SegmentationResult {
+  dwiUrl: string
+  predictionUrl: string
+  metrics: {
+    caseId: string
+    diceScore: number | null
+    volumeMl: number | null
+    elapsedSeconds: number
+  }
+}
+
+export function useSegmentation() {
+  const [result, setResult] = useState<SegmentationResult | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const runSegmentation = useCallback(async (caseId: string) => {
+    setIsLoading(true)
+    setError(null)
+
+    try {
+      const data = await apiClient.runSegmentation(caseId)
+      setResult({
+        dwiUrl: data.dwiUrl,
+        predictionUrl: data.predictionUrl,
+        metrics: {
+          caseId: data.caseId,
+          diceScore: data.diceScore,
+          volumeMl: data.volumeMl,
+          elapsedSeconds: data.elapsedSeconds,
+        },
+      })
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Unknown error')
+      setResult(null)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [])
+
+  return { result, isLoading, error, runSegmentation }
+}
+```
+
+### src/types/index.ts
+
+```typescript
+export interface Case {
+  id: string
+  name: string
+}
+
+export interface Metrics {
+  caseId: string
+  diceScore: number | null
+  volumeMl: number | null
+  elapsedSeconds: number
+}
+
+export interface SegmentationResult {
+  dwiUrl: string
+  predictionUrl: string
+  metrics: Metrics
+}
+```
+
+### index.html
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Stroke Lesion Segmentation</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+### frontend/README.md (HuggingFace Spaces Config)
+
+```markdown
+---
+title: Stroke Lesion Viewer
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
+sdk: static
+app_file: dist/index.html
+app_build_command: npm run build
+# CRITICAL: Vite 6 requires Node.js >= 20. HF Spaces defaults to Node 18.
+# Without this, the build will fail or produce warnings.
+nodejs_version: "20"
+pinned: false
+---
+
+# Stroke Lesion Segmentation Viewer
+
+Interactive 3D viewer for stroke lesion segmentation results using NiiVue.
+
+Built with React, TypeScript, Tailwind CSS, and Vite.
+```
+
+---
+
+## Backend Implementation
+
+### requirements.txt
+
+```
+fastapi==0.124.2
+uvicorn[standard]==0.34.0
+pydantic==2.10.4
+python-multipart>=0.0.18
+
+# Existing project dependencies
+stroke-deepisles-demo @ file:.
+```
+
+**Why these exact versions (Dec 2025):**
+- `fastapi` **0.124.2**: Latest stable (Dec 10, 2025)
+- `uvicorn[standard]` **0.34.0**: Latest stable
+- `pydantic` **2.10.4**: Latest stable
+- `python-multipart` **>=0.0.18**: Required by FastAPI 0.124.x
+
+### backend/api/main.py
+
+```python
+"""FastAPI backend for stroke segmentation."""
+
+import os
+import re
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from api.routes import router
+
+app = FastAPI(
+    title="Stroke Segmentation API",
+    description="DeepISLES stroke lesion segmentation",
+    version="1.0.0",
+)
+
+# CORS for frontend - HF Spaces use dashed hostnames: {org}--{space}.hf.space
+# Also supports PR previews: pr-{n}--{org}--{space}.hf.space
+FRONTEND_ORIGIN = os.environ.get("FRONTEND_ORIGIN", "")
+CORS_ORIGINS = [
+    "http://localhost:5173",  # Local Vite dev server
+    "http://localhost:3000",  # Alternative local port
+]
+if FRONTEND_ORIGIN:
+    CORS_ORIGINS.append(FRONTEND_ORIGIN)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=CORS_ORIGINS,
+    # Regex matches HuggingFace Spaces origins:
+    # - Production: https://{org}--stroke-viewer-frontend.hf.space
+    # - PR preview: https://{org}--stroke-viewer-frontend--pr-{N}.hf.space
+    # - Branch:     https://{org}--stroke-viewer-frontend--{branch}.hf.space
+    # Pattern: anything--stroke-viewer-frontend, optionally followed by --anything
+    allow_origin_regex=r"https://.*--stroke-viewer-frontend(--.*)?\.hf\.space",
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# API routes
+app.include_router(router, prefix="/api")
+
+# Serve NIfTI files from results directory
+# Files are stored as /tmp/stroke-results/{run_id}/{case_id}/{filename}
+app.mount("/files", StaticFiles(directory="/tmp/stroke-results"), name="files")
+
+
+@app.get("/")
+async def root():
+    return {"status": "healthy", "service": "stroke-segmentation-api"}
+```
+
+### backend/api/routes.py
+
+```python
+"""API route handlers."""
+
+import os
+import uuid
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Request
+from api.schemas import SegmentRequest, SegmentResponse, CasesResponse
+
+from stroke_deepisles_demo.data import list_case_ids
+from stroke_deepisles_demo.pipeline import run_pipeline_on_case
+from stroke_deepisles_demo.metrics import compute_volume_ml
+
+router = APIRouter()
+
+# Base directory for results (must match StaticFiles mount in main.py)
+RESULTS_BASE = Path("/tmp/stroke-results")
+
+
+def get_backend_base_url(request: Request) -> str:
+    """Get the backend's public URL for building absolute file URLs.
+
+    Priority:
+    1. BACKEND_PUBLIC_URL env var (for production HF Spaces)
+    2. Request's base URL (for local development)
+    """
+    env_url = os.environ.get("BACKEND_PUBLIC_URL", "").rstrip("/")
+    if env_url:
+        return env_url
+    # Fall back to request origin (works for local dev)
+    return str(request.base_url).rstrip("/")
+
+
+@router.get("/cases", response_model=CasesResponse)
+async def get_cases():
+    """List available cases from dataset."""
+    try:
+        cases = list_case_ids()
+        return CasesResponse(cases=cases)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/segment", response_model=SegmentResponse)
+async def run_segmentation(request: Request, body: SegmentRequest):
+    """Run DeepISLES segmentation on a case."""
+    try:
+        # Generate unique run ID to avoid conflicts between concurrent requests
+        run_id = str(uuid.uuid4())[:8]
+        output_dir = RESULTS_BASE / run_id
+
+        result = run_pipeline_on_case(
+            body.case_id,
+            output_dir=output_dir,
+            fast=body.fast_mode,
+            compute_dice=True,
+            cleanup_staging=True,
+        )
+
+        # Compute volume
+        volume_ml = None
+        try:
+            volume_ml = round(compute_volume_ml(result.prediction_mask, threshold=0.5), 2)
+        except Exception:
+            pass
+
+        # Build ABSOLUTE file URLs for cross-origin NiiVue loading
+        # Files are at: /tmp/stroke-results/{run_id}/{case_id}/{filename}
+        # Served at: /files/{run_id}/{case_id}/{filename}
+        backend_url = get_backend_base_url(request)
+        dwi_filename = result.input_files["dwi"].name
+        pred_filename = result.prediction_mask.name
+
+        # URL path: /files/{run_id}/{case_id}/{filename}
+        file_path_prefix = f"/files/{run_id}/{result.case_id}"
+
+        return SegmentResponse(
+            caseId=result.case_id,
+            diceScore=result.dice_score,
+            volumeMl=volume_ml,
+            elapsedSeconds=round(result.elapsed_seconds, 2),
+            dwiUrl=f"{backend_url}{file_path_prefix}/{dwi_filename}",
+            predictionUrl=f"{backend_url}{file_path_prefix}/{pred_filename}",
+        )
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+```
+
+### backend/api/schemas.py
+
+```python
+"""Pydantic schemas for API."""
+
+from pydantic import BaseModel
+
+
+class CasesResponse(BaseModel):
+    cases: list[str]
+
+
+class SegmentRequest(BaseModel):
+    case_id: str
+    fast_mode: bool = True
+
+
+class SegmentResponse(BaseModel):
+    caseId: str
+    diceScore: float | None
+    volumeMl: float | None
+    elapsedSeconds: float
+    dwiUrl: str
+    predictionUrl: str
+```
+
+### backend/Dockerfile
+
+```dockerfile
+# CRITICAL: Must use isleschallenge/deepisles base image
+# This image contains:
+# - PyTorch with CUDA support
+# - Pre-installed DeepISLES model weights (~18GB)
+# - All medical imaging dependencies (nibabel, nnunet, etc.)
+#
+# Using python:3.11-slim would require manually downloading weights
+# and reinstalling all CUDA/PyTorch dependencies - not feasible.
+FROM isleschallenge/deepisles:latest
+
+WORKDIR /app
+
+# Copy the ENTIRE project (stroke-deepisles-demo package)
+# This is required because requirements.txt references "stroke-deepisles-demo @ file:."
+COPY pyproject.toml .
+COPY src/ src/
+COPY README.md .
+
+# Copy API code
+COPY backend/api/ api/
+COPY backend/requirements.txt .
+
+# Install API dependencies (FastAPI, uvicorn) + local package
+# Note: Base image already has torch, nibabel, etc.
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Create results directory (used by StaticFiles mount)
+RUN mkdir -p /tmp/stroke-results
+
+# Environment variables for HuggingFace Spaces
+ENV HF_SPACES=1
+ENV DEEPISLES_DIRECT_INVOCATION=1
+
+# Expose port (HF Spaces expects 7860)
+EXPOSE 7860
+
+# Run FastAPI
+CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "7860"]
+```
+
+**CRITICAL: GPU Required**
+
+DeepISLES requires GPU acceleration. HuggingFace Spaces FREE tier (`cpu-basic`) will NOT work.
+
+| Tier | GPU | Will Work? |
+|------|-----|------------|
+| `cpu-basic` (free) | None | ❌ No |
+| `t4-small` | NVIDIA T4 (16GB) | ✅ Yes |
+| `t4-medium` | NVIDIA T4 (16GB) | ✅ Yes |
+| `a10g-small` | NVIDIA A10G (24GB) | ✅ Yes |
+
+When creating the HF Space, select **T4-small** or higher.
+
+**Note:** The Dockerfile copies the full project because `requirements.txt` has:
+```
+stroke-deepisles-demo @ file:.
+```
+This PEP 508 local path reference requires the package source to be present.
+
+### backend/README.md (HuggingFace Spaces Config)
+
+```markdown
+---
+title: Stroke Segmentation API
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Stroke Segmentation API
+
+FastAPI backend running DeepISLES stroke lesion segmentation.
+
+## Endpoints
+
+- `GET /api/cases` - List available cases
+- `POST /api/segment` - Run segmentation
+- `GET /files/{filename}` - Download result files
+```
+
+---
+
+## Setup Commands
+
+### Frontend (Local Development)
+
+```bash
+# Create project
+npm create vite@latest stroke-viewer-frontend -- --template react-ts
+cd stroke-viewer-frontend
+
+# Install dependencies
+npm install @niivue/niivue
+npm install -D tailwindcss @tailwindcss/vite
+
+# Copy the files from this spec into src/
+
+# Run dev server
+npm run dev
+# Opens http://localhost:5173
+```
+
+### Backend (Local Development)
+
+```bash
+cd backend
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run server
+uvicorn api.main:app --reload --port 7860
+# Opens http://localhost:7860
+```
+
+### Deploy to HuggingFace
+
+```bash
+# Frontend (Static Space)
+cd frontend
+huggingface-cli repo create stroke-viewer-frontend --type space --space-sdk static
+huggingface-cli upload stroke-viewer-frontend ./dist . --repo-type space
+
+# Backend (Docker Space)
+cd backend
+huggingface-cli repo create stroke-viewer-api --type space --space-sdk docker
+huggingface-cli upload stroke-viewer-api . . --repo-type space
+```
+
+---
+
+## Environment Variables
+
+### Frontend (.env)
+
+```env
+VITE_API_URL=https://your-username-stroke-viewer-api.hf.space
+```
+
+### Backend
+
+No additional env vars needed - uses existing stroke-deepisles-demo configuration.
+
+---
+
+## Key Differences from Gradio
+
+| What | Gradio (broken) | This Stack |
+|------|-----------------|------------|
+| NiiVue JavaScript | Blocked by innerHTML | Full execution ✓ |
+| WebGL2 context | Frozen during hydration | Works normally ✓ |
+| Bundle size | ~2MB Gradio overhead | ~200KB total |
+| Cold start | Python + Gradio init | Instant (static) |
+| Customization | Limited to Gradio components | Full React control |
+
+---
+
+## Next Steps
+
+1. Create `frontend/` directory with files from this spec
+2. Create `backend/` directory with files from this spec
+3. Test locally: `npm run dev` + `uvicorn api.main:app`
+4. Create HuggingFace Spaces (one Static, one Docker)
+5. Deploy and test
+
+---
+
+## Dependencies Summary (Verified Dec 11, 2025)
+
+**Frontend (npm) - PINNED VERSIONS:**
+| Package | Version | Notes |
+|---------|---------|-------|
+| react | 18.3.1 | NOT React 19 (CVE-2025-55182) |
+| react-dom | 18.3.1 | Must match react version |
+| @niivue/niivue | 0.65.0 | Latest stable |
+| typescript | 5.6.3 | Latest 5.6.x |
+| vite | 6.0.5 | Stable v6 (not v7/v8 beta) |
+| tailwindcss | 4.1.7 | Latest v4 |
+| @tailwindcss/vite | 4.1.7 | Must match tailwindcss |
+| @vitejs/plugin-react | 4.3.4 | Latest stable |
+
+**Backend (pip) - PINNED VERSIONS:**
+| Package | Version | Notes |
+|---------|---------|-------|
+| fastapi | 0.124.2 | Latest (Dec 10, 2025) |
+| uvicorn[standard] | 0.34.0 | Latest stable |
+| pydantic | 2.10.4 | Latest stable |
+| python-multipart | >=0.0.18 | Required by FastAPI |
+
+**Node.js:** >= 20.0.0 (required for Vite 6)
+**Python:** >= 3.11 (recommended for FastAPI)

docs/specs/frontend/37-0-project-setup.md

@@ -0,0 +1,307 @@
+# Spec 37.0: Frontend Project Setup
+
+**Status**: READY FOR IMPLEMENTATION
+**Phase**: 0 of 5
+**Depends On**: Spec 36 (Stack Definition)
+**Goal**: Scaffold Vite + React + TypeScript project with testing infrastructure
+
+---
+
+## Deliverables
+
+By the end of this phase, you will have:
+
+1. Working Vite dev server (`npm run dev`)
+2. TypeScript compilation passing (`npx tsc --noEmit`)
+3. Vitest running with a smoke test (`npm test`)
+4. Tailwind CSS working
+5. MSW configured for API mocking
+
+---
+
+## Step 1: Create Vite Project
+
+```bash
+cd /Users/ray/Desktop/CLARITY-DIGITAL-TWIN/stroke-deepisles-demo
+npm create vite@latest frontend -- --template react-ts
+cd frontend
+```
+
+---
+
+## Step 2: Install Dependencies
+
+```bash
+# Core dependencies
+npm install @niivue/niivue@0.65.0
+
+# Dev dependencies - Testing
+npm install -D vitest@2.1.8 @vitest/coverage-v8@2.1.8 @vitest/ui@2.1.8
+npm install -D @testing-library/react@16.3.0 @testing-library/jest-dom@6.6.3 @testing-library/user-event@14.5.2
+npm install -D jsdom@25.0.1 msw@2.7.0
+
+# Dev dependencies - Styling
+npm install -D tailwindcss@4.1.7 @tailwindcss/vite@4.1.7
+```
+
+---
+
+## Step 3: Configure package.json Scripts
+
+Replace scripts section:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage"
+  }
+}
+```
+
+---
+
+## Step 4: Configure Vite + Vitest
+
+Replace `vite.config.ts`:
+
+```typescript
+/// <reference types="vitest" />
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  build: {
+    outDir: 'dist',
+  },
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    exclude: ['node_modules', 'e2e'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: [
+        'src/**/*.test.{ts,tsx}',
+        'src/test/**',
+        'src/mocks/**',
+        'src/main.tsx',
+      ],
+    },
+  },
+})
+```
+
+---
+
+## Step 5: Configure TypeScript
+
+Replace `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "types": ["vitest/globals", "@testing-library/jest-dom"]
+  },
+  "include": ["src"]
+}
+```
+
+---
+
+## Step 6: Configure Tailwind CSS
+
+Replace `src/index.css`:
+
+```css
+@import "tailwindcss";
+```
+
+---
+
+## Step 7: Create Test Setup
+
+Create `src/test/setup.ts`:
+
+```typescript
+import '@testing-library/jest-dom/vitest'
+import { cleanup } from '@testing-library/react'
+import { afterEach, beforeAll, afterAll } from 'vitest'
+import { server } from '../mocks/server'
+
+// Establish API mocking before all tests
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
+
+// Clean up after each test
+afterEach(() => {
+  cleanup()
+  server.resetHandlers()
+})
+
+// Clean up after all tests
+afterAll(() => server.close())
+
+// Mock ResizeObserver (needed for some UI components)
+global.ResizeObserver = class ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+```
+
+---
+
+## Step 8: Create MSW Mocks
+
+Create `src/mocks/handlers.ts`:
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+const API_BASE = import.meta.env.VITE_API_URL || 'http://localhost:7860'
+
+export const handlers = [
+  // GET /api/cases - List available cases
+  http.get(`${API_BASE}/api/cases`, () => {
+    return HttpResponse.json({
+      cases: ['sub-stroke0001', 'sub-stroke0002', 'sub-stroke0003'],
+    })
+  }),
+
+  // POST /api/segment - Run segmentation
+  http.post(`${API_BASE}/api/segment`, async ({ request }) => {
+    const body = (await request.json()) as { case_id: string; fast_mode?: boolean }
+    return HttpResponse.json({
+      caseId: body.case_id,
+      diceScore: 0.847,
+      volumeMl: 15.32,
+      elapsedSeconds: body.fast_mode === false ? 45.0 : 12.5,
+      dwiUrl: `${API_BASE}/files/dwi.nii.gz`,
+      predictionUrl: `${API_BASE}/files/prediction.nii.gz`,
+    })
+  }),
+]
+```
+
+Create `src/mocks/server.ts`:
+
+```typescript
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)
+```
+
+---
+
+## Step 9: Create Smoke Test
+
+Create `src/App.test.tsx`:
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import App from './App'
+
+describe('App', () => {
+  it('renders without crashing', () => {
+    render(<App />)
+    // This will pass with default Vite template
+    expect(document.body).toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Step 10: Create Environment File
+
+Create `.env`:
+
+```env
+VITE_API_URL=http://localhost:7860
+```
+
+Create `.env.example`:
+
+```env
+VITE_API_URL=http://localhost:7860
+```
+
+---
+
+## Verification Checklist
+
+Run these commands to verify setup:
+
+```bash
+# 1. TypeScript compiles
+npx tsc --noEmit
+# Expected: No errors
+
+# 2. Dev server starts
+npm run dev
+# Expected: Server at http://localhost:5173
+
+# 3. Tests pass
+npm test
+# Expected: 1 test passing
+
+# 4. Build works
+npm run build
+# Expected: dist/ folder created
+```
+
+---
+
+## File Structure After This Phase
+
+```
+frontend/
+├── src/
+│   ├── mocks/
+│   │   ├── handlers.ts
+│   │   └── server.ts
+│   ├── test/
+│   │   └── setup.ts
+│   ├── App.tsx
+│   ├── App.test.tsx
+│   ├── main.tsx
+│   └── index.css
+├── .env
+├── .env.example
+├── index.html
+├── package.json
+├── tsconfig.json
+└── vite.config.ts
+```
+
+---
+
+## Next Phase
+
+Once verification passes, proceed to **Spec 37.1: Foundation Components**

docs/specs/frontend/37-1-foundation-components.md

@@ -0,0 +1,331 @@
+# Spec 37.1: Foundation Components
+
+**Status**: READY FOR IMPLEMENTATION
+**Phase**: 1 of 5
+**Depends On**: Spec 37.0 (Project Setup)
+**Goal**: TDD implementation of Layout and MetricsPanel components
+
+---
+
+## Deliverables
+
+By the end of this phase, you will have:
+
+1. `Layout` component with header and main content area
+2. `MetricsPanel` component displaying segmentation results
+3. 100% test coverage for both components
+4. Visual verification in browser
+
+---
+
+## Component 1: Layout
+
+### Test First
+
+Create `src/components/__tests__/Layout.test.tsx`:
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { Layout } from '../Layout'
+
+describe('Layout', () => {
+  it('renders header with title', () => {
+    render(<Layout>Content</Layout>)
+
+    expect(
+      screen.getByRole('heading', { name: /stroke lesion segmentation/i })
+    ).toBeInTheDocument()
+  })
+
+  it('renders subtitle', () => {
+    render(<Layout>Content</Layout>)
+
+    expect(screen.getByText(/deepisles segmentation/i)).toBeInTheDocument()
+  })
+
+  it('renders children in main area', () => {
+    render(
+      <Layout>
+        <div data-testid="child">Test Child</div>
+      </Layout>
+    )
+
+    expect(screen.getByTestId('child')).toBeInTheDocument()
+  })
+
+  it('has accessible landmark structure', () => {
+    render(<Layout>Content</Layout>)
+
+    expect(screen.getByRole('banner')).toBeInTheDocument()
+    expect(screen.getByRole('main')).toBeInTheDocument()
+  })
+
+  it('applies dark theme styling', () => {
+    render(<Layout>Content</Layout>)
+
+    const container = screen.getByRole('banner').parentElement
+    expect(container).toHaveClass('bg-gray-950')
+  })
+})
+```
+
+### Implementation
+
+Create `src/components/Layout.tsx`:
+
+```typescript
+import { ReactNode } from 'react'
+
+interface LayoutProps {
+  children: ReactNode
+}
+
+export function Layout({ children }: LayoutProps) {
+  return (
+    <div className="min-h-screen bg-gray-950 text-white">
+      <header className="border-b border-gray-800 py-4">
+        <div className="container mx-auto px-4">
+          <h1 className="text-2xl font-bold">Stroke Lesion Segmentation</h1>
+          <p className="text-gray-400 text-sm mt-1">
+            DeepISLES segmentation on ISLES24 dataset
+          </p>
+        </div>
+      </header>
+      <main className="container mx-auto px-4 py-6">{children}</main>
+    </div>
+  )
+}
+```
+
+### Verify
+
+```bash
+npm test -- Layout
+# Expected: 5 tests passing
+```
+
+---
+
+## Component 2: MetricsPanel
+
+### Test First
+
+Create `src/components/__tests__/MetricsPanel.test.tsx`:
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { MetricsPanel } from '../MetricsPanel'
+
+describe('MetricsPanel', () => {
+  const defaultMetrics = {
+    caseId: 'sub-stroke0001',
+    diceScore: 0.847,
+    volumeMl: 15.32,
+    elapsedSeconds: 12.5,
+  }
+
+  it('renders results heading', () => {
+    render(<MetricsPanel metrics={defaultMetrics} />)
+
+    expect(
+      screen.getByRole('heading', { name: /results/i })
+    ).toBeInTheDocument()
+  })
+
+  it('displays case ID', () => {
+    render(<MetricsPanel metrics={defaultMetrics} />)
+
+    expect(screen.getByText('sub-stroke0001')).toBeInTheDocument()
+  })
+
+  it('displays dice score with 3 decimal places', () => {
+    render(<MetricsPanel metrics={defaultMetrics} />)
+
+    expect(screen.getByText('0.847')).toBeInTheDocument()
+  })
+
+  it('displays volume in mL with 2 decimal places', () => {
+    render(<MetricsPanel metrics={defaultMetrics} />)
+
+    expect(screen.getByText('15.32 mL')).toBeInTheDocument()
+  })
+
+  it('displays elapsed time with 1 decimal place', () => {
+    render(<MetricsPanel metrics={defaultMetrics} />)
+
+    expect(screen.getByText('12.5s')).toBeInTheDocument()
+  })
+
+  it('hides dice score row when null', () => {
+    render(
+      <MetricsPanel metrics={{ ...defaultMetrics, diceScore: null }} />
+    )
+
+    expect(screen.queryByText(/dice score/i)).not.toBeInTheDocument()
+  })
+
+  it('hides volume row when null', () => {
+    render(
+      <MetricsPanel metrics={{ ...defaultMetrics, volumeMl: null }} />
+    )
+
+    expect(screen.queryByText(/volume/i)).not.toBeInTheDocument()
+  })
+
+  it('applies card styling', () => {
+    render(<MetricsPanel metrics={defaultMetrics} />)
+
+    const panel = screen.getByRole('heading', { name: /results/i }).parentElement
+    expect(panel).toHaveClass('bg-gray-800', 'rounded-lg')
+  })
+})
+```
+
+### Implementation
+
+Create `src/components/MetricsPanel.tsx`:
+
+```typescript
+interface Metrics {
+  caseId: string
+  diceScore: number | null
+  volumeMl: number | null
+  elapsedSeconds: number
+}
+
+interface MetricsPanelProps {
+  metrics: Metrics
+}
+
+export function MetricsPanel({ metrics }: MetricsPanelProps) {
+  return (
+    <div className="bg-gray-800 rounded-lg p-4 space-y-3">
+      <h3 className="font-medium text-lg">Results</h3>
+
+      <div className="grid grid-cols-2 gap-3 text-sm">
+        <div>
+          <span className="text-gray-400">Case:</span>
+          <span className="ml-2 font-mono">{metrics.caseId}</span>
+        </div>
+
+        {metrics.diceScore !== null && (
+          <div>
+            <span className="text-gray-400">Dice Score:</span>
+            <span className="ml-2 font-mono text-green-400">
+              {metrics.diceScore.toFixed(3)}
+            </span>
+          </div>
+        )}
+
+        {metrics.volumeMl !== null && (
+          <div>
+            <span className="text-gray-400">Volume:</span>
+            <span className="ml-2 font-mono">
+              {metrics.volumeMl.toFixed(2)} mL
+            </span>
+          </div>
+        )}
+
+        <div>
+          <span className="text-gray-400">Time:</span>
+          <span className="ml-2 font-mono">
+            {metrics.elapsedSeconds.toFixed(1)}s
+          </span>
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+### Verify
+
+```bash
+npm test -- MetricsPanel
+# Expected: 8 tests passing
+```
+
+---
+
+## Create Index Export
+
+Create `src/components/index.ts`:
+
+```typescript
+export { Layout } from './Layout'
+export { MetricsPanel } from './MetricsPanel'
+```
+
+---
+
+## Visual Verification
+
+Update `src/App.tsx` to see components:
+
+```typescript
+import { Layout } from './components/Layout'
+import { MetricsPanel } from './components/MetricsPanel'
+
+const mockMetrics = {
+  caseId: 'sub-stroke0001',
+  diceScore: 0.847,
+  volumeMl: 15.32,
+  elapsedSeconds: 12.5,
+}
+
+function App() {
+  return (
+    <Layout>
+      <div className="max-w-md">
+        <MetricsPanel metrics={mockMetrics} />
+      </div>
+    </Layout>
+  )
+}
+
+export default App
+```
+
+Run dev server and verify visually:
+
+```bash
+npm run dev
+# Open http://localhost:5173
+```
+
+---
+
+## Verification Checklist
+
+- [ ] `npm test` - All 13+ tests pass
+- [ ] `npm run dev` - Components render correctly
+- [ ] Header shows "Stroke Lesion Segmentation"
+- [ ] MetricsPanel shows all metrics with correct formatting
+- [ ] Dark theme applies correctly
+
+---
+
+## File Structure After This Phase
+
+```
+frontend/src/
+├── components/
+│   ├── __tests__/
+│   │   ├── Layout.test.tsx
+│   │   └── MetricsPanel.test.tsx
+│   ├── Layout.tsx
+│   ├── MetricsPanel.tsx
+│   └── index.ts
+├── mocks/
+├── test/
+├── App.tsx (updated)
+└── ...
+```
+
+---
+
+## Next Phase
+
+Once verification passes, proceed to **Spec 37.2: API Layer**

docs/specs/frontend/37-2-api-layer.md

@@ -0,0 +1,523 @@
+# Spec 37.2: API Layer
+
+**Status**: READY FOR IMPLEMENTATION
+**Phase**: 2 of 5
+**Depends On**: Spec 37.1 (Foundation Components)
+**Goal**: TDD implementation of API client and useSegmentation hook
+
+---
+
+## Deliverables
+
+By the end of this phase, you will have:
+
+1. Type definitions for API responses
+2. `apiClient` with `getCases()` and `runSegmentation()` methods
+3. `useSegmentation` React hook for state management
+4. MSW handlers for all API endpoints
+5. Error handling tests
+
+---
+
+## Step 1: Type Definitions
+
+Create `src/types/index.ts`:
+
+```typescript
+export interface Metrics {
+  caseId: string
+  diceScore: number | null
+  volumeMl: number | null
+  elapsedSeconds: number
+}
+
+export interface SegmentationResult {
+  dwiUrl: string
+  predictionUrl: string
+  metrics: Metrics
+}
+
+export interface CasesResponse {
+  cases: string[]
+}
+
+export interface SegmentResponse {
+  caseId: string
+  diceScore: number | null
+  volumeMl: number | null
+  elapsedSeconds: number
+  dwiUrl: string
+  predictionUrl: string
+}
+```
+
+---
+
+## Step 2: Test Fixtures
+
+Create `src/test/fixtures.ts`:
+
+```typescript
+import type { SegmentationResult, CasesResponse } from '../types'
+
+export const mockCases: string[] = [
+  'sub-stroke0001',
+  'sub-stroke0002',
+  'sub-stroke0003',
+]
+
+export const mockCasesResponse: CasesResponse = {
+  cases: mockCases,
+}
+
+export const mockSegmentationResult: SegmentationResult = {
+  dwiUrl: 'http://localhost:7860/files/dwi.nii.gz',
+  predictionUrl: 'http://localhost:7860/files/prediction.nii.gz',
+  metrics: {
+    caseId: 'sub-stroke0001',
+    diceScore: 0.847,
+    volumeMl: 15.32,
+    elapsedSeconds: 12.5,
+  },
+}
+```
+
+---
+
+## Step 3: Enhanced MSW Handlers
+
+Update `src/mocks/handlers.ts`:
+
+```typescript
+import { http, HttpResponse, delay } from 'msw'
+
+const API_BASE = import.meta.env.VITE_API_URL || 'http://localhost:7860'
+
+export const handlers = [
+  http.get(`${API_BASE}/api/cases`, async () => {
+    await delay(100)
+    return HttpResponse.json({
+      cases: ['sub-stroke0001', 'sub-stroke0002', 'sub-stroke0003'],
+    })
+  }),
+
+  http.post(`${API_BASE}/api/segment`, async ({ request }) => {
+    const body = (await request.json()) as { case_id: string; fast_mode?: boolean }
+    await delay(200)
+    return HttpResponse.json({
+      caseId: body.case_id,
+      diceScore: 0.847,
+      volumeMl: 15.32,
+      // Reflect fast_mode in response - slower when fast_mode=false
+      elapsedSeconds: body.fast_mode === false ? 45.0 : 12.5,
+      dwiUrl: `${API_BASE}/files/dwi.nii.gz`,
+      predictionUrl: `${API_BASE}/files/prediction.nii.gz`,
+    })
+  }),
+]
+
+// Error handlers for testing error states
+export const errorHandlers = {
+  casesServerError: http.get(`${API_BASE}/api/cases`, () => {
+    return HttpResponse.json(
+      { detail: 'Internal server error' },
+      { status: 500 }
+    )
+  }),
+
+  casesNetworkError: http.get(`${API_BASE}/api/cases`, () => {
+    return HttpResponse.error()
+  }),
+
+  segmentServerError: http.post(`${API_BASE}/api/segment`, () => {
+    return HttpResponse.json(
+      { detail: 'Segmentation failed: out of memory' },
+      { status: 500 }
+    )
+  }),
+
+  segmentTimeout: http.post(`${API_BASE}/api/segment`, async () => {
+    await delay(30000)
+    return HttpResponse.json({ detail: 'Timeout' }, { status: 504 })
+  }),
+}
+```
+
+---
+
+## Step 4: API Client
+
+### Test First
+
+Create `src/api/__tests__/client.test.ts`:
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { server } from '../../mocks/server'
+import { errorHandlers } from '../../mocks/handlers'
+import { apiClient } from '../client'
+
+describe('apiClient', () => {
+  describe('getCases', () => {
+    it('returns list of case IDs', async () => {
+      const result = await apiClient.getCases()
+
+      expect(result.cases).toHaveLength(3)
+      expect(result.cases).toContain('sub-stroke0001')
+    })
+
+    it('throws ApiError on server error', async () => {
+      server.use(errorHandlers.casesServerError)
+
+      await expect(apiClient.getCases()).rejects.toThrow(/failed to fetch cases/i)
+    })
+
+    it('throws ApiError on network error', async () => {
+      server.use(errorHandlers.casesNetworkError)
+
+      await expect(apiClient.getCases()).rejects.toThrow()
+    })
+  })
+
+  describe('runSegmentation', () => {
+    it('returns segmentation result', async () => {
+      const result = await apiClient.runSegmentation('sub-stroke0001')
+
+      expect(result.caseId).toBe('sub-stroke0001')
+      expect(result.diceScore).toBe(0.847)
+      expect(result.volumeMl).toBe(15.32)
+      expect(result.dwiUrl).toContain('dwi.nii.gz')
+      expect(result.predictionUrl).toContain('prediction.nii.gz')
+    })
+
+    it('sends fast_mode parameter', async () => {
+      const result = await apiClient.runSegmentation('sub-stroke0001', false)
+
+      expect(result).toBeDefined()
+    })
+
+    it('defaults fast_mode to true', async () => {
+      const result = await apiClient.runSegmentation('sub-stroke0001')
+
+      expect(result).toBeDefined()
+    })
+
+    it('throws ApiError on server error', async () => {
+      server.use(errorHandlers.segmentServerError)
+
+      await expect(
+        apiClient.runSegmentation('sub-stroke0001')
+      ).rejects.toThrow(/segmentation failed/i)
+    })
+  })
+})
+```
+
+### Implementation
+
+Create `src/api/client.ts`:
+
+```typescript
+import type { CasesResponse, SegmentResponse } from '../types'
+
+const API_BASE = import.meta.env.VITE_API_URL || 'http://localhost:7860'
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public detail?: string
+  ) {
+    super(message)
+    this.name = 'ApiError'
+  }
+}
+
+class ApiClient {
+  private baseUrl: string
+
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl
+  }
+
+  async getCases(): Promise<CasesResponse> {
+    const response = await fetch(`${this.baseUrl}/api/cases`)
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}))
+      throw new ApiError(
+        `Failed to fetch cases: ${response.statusText}`,
+        response.status,
+        error.detail
+      )
+    }
+
+    return response.json()
+  }
+
+  async runSegmentation(
+    caseId: string,
+    fastMode: boolean = true
+  ): Promise<SegmentResponse> {
+    const response = await fetch(`${this.baseUrl}/api/segment`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        case_id: caseId,
+        fast_mode: fastMode,
+      }),
+    })
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}))
+      throw new ApiError(
+        `Segmentation failed: ${error.detail || response.statusText}`,
+        response.status,
+        error.detail
+      )
+    }
+
+    return response.json()
+  }
+}
+
+export const apiClient = new ApiClient(API_BASE)
+```
+
+### Verify
+
+```bash
+npm test -- client
+# Expected: 7 tests passing
+```
+
+---
+
+## Step 5: useSegmentation Hook
+
+### Test First
+
+Create `src/hooks/__tests__/useSegmentation.test.tsx`:
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { renderHook, waitFor, act } from '@testing-library/react'
+import { server } from '../../mocks/server'
+import { errorHandlers } from '../../mocks/handlers'
+import { useSegmentation } from '../useSegmentation'
+
+describe('useSegmentation', () => {
+  it('starts with null result and not loading', () => {
+    const { result } = renderHook(() => useSegmentation())
+
+    expect(result.current.result).toBeNull()
+    expect(result.current.isLoading).toBe(false)
+    expect(result.current.error).toBeNull()
+  })
+
+  it('sets loading state during segmentation', async () => {
+    const { result } = renderHook(() => useSegmentation())
+
+    act(() => {
+      result.current.runSegmentation('sub-stroke0001')
+    })
+
+    expect(result.current.isLoading).toBe(true)
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false)
+    })
+  })
+
+  it('returns result on success', async () => {
+    const { result } = renderHook(() => useSegmentation())
+
+    await act(async () => {
+      await result.current.runSegmentation('sub-stroke0001')
+    })
+
+    expect(result.current.result).not.toBeNull()
+    expect(result.current.result?.metrics.caseId).toBe('sub-stroke0001')
+    expect(result.current.result?.metrics.diceScore).toBe(0.847)
+    expect(result.current.result?.dwiUrl).toContain('dwi.nii.gz')
+  })
+
+  it('sets error on failure', async () => {
+    server.use(errorHandlers.segmentServerError)
+
+    const { result } = renderHook(() => useSegmentation())
+
+    await act(async () => {
+      await result.current.runSegmentation('sub-stroke0001')
+    })
+
+    expect(result.current.error).toMatch(/segmentation failed/i)
+    expect(result.current.result).toBeNull()
+  })
+
+  it('clears previous error on new request', async () => {
+    server.use(errorHandlers.segmentServerError)
+    const { result } = renderHook(() => useSegmentation())
+
+    // First request fails
+    await act(async () => {
+      await result.current.runSegmentation('sub-stroke0001')
+    })
+    expect(result.current.error).not.toBeNull()
+
+    // Reset to success handler
+    server.resetHandlers()
+
+    // Second request succeeds
+    await act(async () => {
+      await result.current.runSegmentation('sub-stroke0001')
+    })
+
+    expect(result.current.error).toBeNull()
+    expect(result.current.result).not.toBeNull()
+  })
+
+  it('clears previous result on new request', async () => {
+    const { result } = renderHook(() => useSegmentation())
+
+    // First request
+    await act(async () => {
+      await result.current.runSegmentation('sub-stroke0001')
+    })
+    expect(result.current.result).not.toBeNull()
+
+    // Start second request - result should clear while loading
+    act(() => {
+      result.current.runSegmentation('sub-stroke0002')
+    })
+
+    // While loading, previous result is still available
+    // (or you could clear it - depends on UX preference)
+    expect(result.current.isLoading).toBe(true)
+  })
+})
+```
+
+### Implementation
+
+Create `src/hooks/useSegmentation.ts`:
+
+```typescript
+import { useState, useCallback } from 'react'
+import { apiClient } from '../api/client'
+import type { SegmentationResult } from '../types'
+
+export function useSegmentation() {
+  const [result, setResult] = useState<SegmentationResult | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const runSegmentation = useCallback(async (caseId: string, fastMode = true) => {
+    setIsLoading(true)
+    setError(null)
+
+    try {
+      const data = await apiClient.runSegmentation(caseId, fastMode)
+
+      setResult({
+        dwiUrl: data.dwiUrl,
+        predictionUrl: data.predictionUrl,
+        metrics: {
+          caseId: data.caseId,
+          diceScore: data.diceScore,
+          volumeMl: data.volumeMl,
+          elapsedSeconds: data.elapsedSeconds,
+        },
+      })
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Unknown error'
+      setError(message)
+      setResult(null)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [])
+
+  return { result, isLoading, error, runSegmentation }
+}
+```
+
+### Verify
+
+```bash
+npm test -- useSegmentation
+# Expected: 6 tests passing
+```
+
+---
+
+## Step 6: Create Index Export
+
+Create `src/hooks/index.ts`:
+
+```typescript
+export { useSegmentation } from './useSegmentation'
+```
+
+Create `src/api/index.ts`:
+
+```typescript
+export { apiClient, ApiError } from './client'
+```
+
+---
+
+## Verification Checklist
+
+```bash
+# Run all tests
+npm test
+
+# Expected output:
+# - client.test.ts: 7 tests passing
+# - useSegmentation.test.tsx: 6 tests passing
+# Total: ~25+ tests passing
+```
+
+- [ ] API client handles success responses
+- [ ] API client handles error responses
+- [ ] Hook manages loading state correctly
+- [ ] Hook manages error state correctly
+- [ ] Hook transforms API response to SegmentationResult
+
+---
+
+## File Structure After This Phase
+
+```
+frontend/src/
+├── api/
+│   ├── __tests__/
+│   │   └── client.test.ts
+│   ├── client.ts
+│   └── index.ts
+├── hooks/
+│   ├── __tests__/
+│   │   └── useSegmentation.test.tsx
+│   ├── useSegmentation.ts
+│   └── index.ts
+├── types/
+│   └── index.ts
+├── test/
+│   ├── setup.ts
+│   └── fixtures.ts
+├── mocks/
+│   ├── handlers.ts (updated)
+│   └── server.ts
+├── components/
+│   └── ...
+└── ...
+```
+
+---
+
+## Next Phase
+
+Once verification passes, proceed to **Spec 37.3: Interactive Components**

docs/specs/frontend/37-3-interactive-components.md

@@ -0,0 +1,681 @@
+# Spec 37.3: Interactive Components
+
+**Status**: READY FOR IMPLEMENTATION
+**Phase**: 3 of 5
+**Depends On**: Spec 37.2 (API Layer)
+**Goal**: TDD implementation of CaseSelector and NiiVueViewer components
+
+---
+
+## Deliverables
+
+By the end of this phase, you will have:
+
+1. `CaseSelector` dropdown that fetches and displays cases
+2. `NiiVueViewer` component for 3D medical image viewing
+3. Loading and error states for both components
+4. WebGL mocking for NiiVue tests
+
+---
+
+## Component 1: CaseSelector
+
+### Test First
+
+Create `src/components/__tests__/CaseSelector.test.tsx`:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { server } from '../../mocks/server'
+import { errorHandlers } from '../../mocks/handlers'
+import { CaseSelector } from '../CaseSelector'
+
+describe('CaseSelector', () => {
+  const mockOnSelectCase = vi.fn()
+
+  beforeEach(() => {
+    mockOnSelectCase.mockClear()
+  })
+
+  it('shows loading state initially', () => {
+    render(
+      <CaseSelector selectedCase={null} onSelectCase={mockOnSelectCase} />
+    )
+
+    expect(screen.getByText(/loading/i)).toBeInTheDocument()
+  })
+
+  it('renders select after loading', async () => {
+    render(
+      <CaseSelector selectedCase={null} onSelectCase={mockOnSelectCase} />
+    )
+
+    await waitFor(() => {
+      expect(screen.getByRole('combobox')).toBeInTheDocument()
+    })
+  })
+
+  it('displays all cases as options', async () => {
+    render(
+      <CaseSelector selectedCase={null} onSelectCase={mockOnSelectCase} />
+    )
+
+    await waitFor(() => {
+      expect(screen.getByRole('combobox')).toBeInTheDocument()
+    })
+
+    expect(screen.getByRole('option', { name: /sub-stroke0001/i })).toBeInTheDocument()
+    expect(screen.getByRole('option', { name: /sub-stroke0002/i })).toBeInTheDocument()
+    expect(screen.getByRole('option', { name: /sub-stroke0003/i })).toBeInTheDocument()
+  })
+
+  it('has placeholder option', async () => {
+    render(
+      <CaseSelector selectedCase={null} onSelectCase={mockOnSelectCase} />
+    )
+
+    await waitFor(() => {
+      expect(screen.getByRole('combobox')).toBeInTheDocument()
+    })
+
+    expect(screen.getByRole('option', { name: /choose a case/i })).toBeInTheDocument()
+  })
+
+  it('calls onSelectCase when case selected', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <CaseSelector selectedCase={null} onSelectCase={mockOnSelectCase} />
+    )
+
+    await waitFor(() => {
+      expect(screen.getByRole('combobox')).toBeInTheDocument()
+    })
+
+    await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+
+    expect(mockOnSelectCase).toHaveBeenCalledWith('sub-stroke0001')
+  })
+
+  it('shows selected case value', async () => {
+    render(
+      <CaseSelector
+        selectedCase="sub-stroke0002"
+        onSelectCase={mockOnSelectCase}
+      />
+    )
+
+    await waitFor(() => {
+      expect(screen.getByRole('combobox')).toHaveValue('sub-stroke0002')
+    })
+  })
+
+  it('shows error state on API failure', async () => {
+    server.use(errorHandlers.casesServerError)
+
+    render(
+      <CaseSelector selectedCase={null} onSelectCase={mockOnSelectCase} />
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText(/failed to load/i)).toBeInTheDocument()
+    })
+  })
+
+  it('applies correct styling', async () => {
+    render(
+      <CaseSelector selectedCase={null} onSelectCase={mockOnSelectCase} />
+    )
+
+    await waitFor(() => {
+      expect(screen.getByRole('combobox')).toBeInTheDocument()
+    })
+
+    const container = screen.getByRole('combobox').closest('div')
+    expect(container).toHaveClass('bg-gray-800')
+  })
+})
+```
+
+### Implementation
+
+Create `src/components/CaseSelector.tsx`:
+
+```typescript
+import { useEffect, useState } from 'react'
+import { apiClient } from '../api/client'
+
+interface CaseSelectorProps {
+  selectedCase: string | null
+  onSelectCase: (caseId: string) => void
+}
+
+export function CaseSelector({ selectedCase, onSelectCase }: CaseSelectorProps) {
+  const [cases, setCases] = useState<string[]>([])
+  const [isLoading, setIsLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    const fetchCases = async () => {
+      try {
+        const data = await apiClient.getCases()
+        setCases(data.cases)
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error'
+        setError(`Failed to load cases: ${message}`)
+      } finally {
+        setIsLoading(false)
+      }
+    }
+
+    fetchCases()
+  }, [])
+
+  if (isLoading) {
+    return (
+      <div className="bg-gray-800 rounded-lg p-4">
+        <p className="text-gray-400">Loading cases...</p>
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className="bg-red-900/50 rounded-lg p-4">
+        <p className="text-red-300">{error}</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="bg-gray-800 rounded-lg p-4">
+      <label className="block text-sm font-medium mb-2">Select Case</label>
+      <select
+        value={selectedCase || ''}
+        onChange={(e) => onSelectCase(e.target.value)}
+        className="w-full bg-gray-700 border border-gray-600 rounded-lg px-3 py-2
+                   text-white focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+      >
+        <option value="">Choose a case...</option>
+        {cases.map((caseId) => (
+          <option key={caseId} value={caseId}>
+            {caseId}
+          </option>
+        ))}
+      </select>
+    </div>
+  )
+}
+```
+
+### Verify
+
+```bash
+npm test -- CaseSelector
+# Expected: 9 tests passing
+```
+
+---
+
+## Component 2: NiiVueViewer
+
+### WebGL Mock Setup
+
+Update `src/test/setup.ts` to add WebGL mocking:
+
+```typescript
+import '@testing-library/jest-dom/vitest'
+import { cleanup } from '@testing-library/react'
+import { afterEach, beforeAll, afterAll, vi } from 'vitest'
+import { server } from '../mocks/server'
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
+
+afterEach(() => {
+  cleanup()
+  server.resetHandlers()
+})
+
+afterAll(() => server.close())
+
+// Mock ResizeObserver
+global.ResizeObserver = class ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+// Mock WebGL2 context for NiiVue
+// NiiVue requires specific extensions for float textures (overlays)
+// See: https://github.com/niivue/niivue#browser-requirements
+const mockExtensions: Record<string, object> = {
+  // Required for float textures (overlay rendering)
+  EXT_color_buffer_float: {},
+  OES_texture_float_linear: {},
+  // Required for WebGL context management
+  WEBGL_lose_context: {
+    loseContext: vi.fn(),
+    restoreContext: vi.fn(),
+  },
+  // Optional but commonly requested
+  EXT_texture_filter_anisotropic: {
+    TEXTURE_MAX_ANISOTROPY_EXT: 0x84fe,
+    MAX_TEXTURE_MAX_ANISOTROPY_EXT: 0x84ff,
+  },
+  WEBGL_debug_renderer_info: {
+    UNMASKED_VENDOR_WEBGL: 0x9245,
+    UNMASKED_RENDERER_WEBGL: 0x9246,
+  },
+}
+
+const mockWebGL2Context = {
+  canvas: null as HTMLCanvasElement | null,
+  drawingBufferWidth: 640,
+  drawingBufferHeight: 480,
+  createShader: vi.fn(() => ({})),
+  shaderSource: vi.fn(),
+  compileShader: vi.fn(),
+  getShaderParameter: vi.fn(() => true),
+  getShaderInfoLog: vi.fn(() => ''),
+  createProgram: vi.fn(() => ({})),
+  attachShader: vi.fn(),
+  linkProgram: vi.fn(),
+  getProgramParameter: vi.fn(() => true),
+  getProgramInfoLog: vi.fn(() => ''),
+  useProgram: vi.fn(),
+  getAttribLocation: vi.fn(() => 0),
+  getUniformLocation: vi.fn(() => ({})),
+  createBuffer: vi.fn(() => ({})),
+  bindBuffer: vi.fn(),
+  bufferData: vi.fn(),
+  enableVertexAttribArray: vi.fn(),
+  vertexAttribPointer: vi.fn(),
+  createTexture: vi.fn(() => ({})),
+  bindTexture: vi.fn(),
+  texParameteri: vi.fn(),
+  texParameterf: vi.fn(),
+  texImage2D: vi.fn(),
+  texImage3D: vi.fn(),
+  texStorage2D: vi.fn(),
+  texStorage3D: vi.fn(),
+  texSubImage2D: vi.fn(),
+  texSubImage3D: vi.fn(),
+  activeTexture: vi.fn(),
+  generateMipmap: vi.fn(),
+  uniform1i: vi.fn(),
+  uniform1f: vi.fn(),
+  uniform2f: vi.fn(),
+  uniform2fv: vi.fn(),
+  uniform3f: vi.fn(),
+  uniform3fv: vi.fn(),
+  uniform4f: vi.fn(),
+  uniform4fv: vi.fn(),
+  uniformMatrix4fv: vi.fn(),
+  viewport: vi.fn(),
+  scissor: vi.fn(),
+  clear: vi.fn(),
+  clearColor: vi.fn(),
+  clearDepth: vi.fn(),
+  enable: vi.fn(),
+  disable: vi.fn(),
+  blendFunc: vi.fn(),
+  blendFuncSeparate: vi.fn(),
+  depthFunc: vi.fn(),
+  depthMask: vi.fn(),
+  cullFace: vi.fn(),
+  drawArrays: vi.fn(),
+  drawElements: vi.fn(),
+  // CRITICAL: Return stub extensions for NiiVue float texture support
+  getExtension: vi.fn((name: string) => mockExtensions[name] || null),
+  getParameter: vi.fn((pname: number) => {
+    // Return reasonable defaults for common parameter queries
+    if (pname === 0x0d33) return 16384 // MAX_TEXTURE_SIZE
+    if (pname === 0x8073) return 2048 // MAX_3D_TEXTURE_SIZE
+    if (pname === 0x851c) return 16 // MAX_TEXTURE_IMAGE_UNITS
+    return 0
+  }),
+  getSupportedExtensions: vi.fn(() => Object.keys(mockExtensions)),
+  pixelStorei: vi.fn(),
+  readPixels: vi.fn(),
+  createFramebuffer: vi.fn(() => ({})),
+  bindFramebuffer: vi.fn(),
+  framebufferTexture2D: vi.fn(),
+  checkFramebufferStatus: vi.fn(() => 36053), // FRAMEBUFFER_COMPLETE
+  createRenderbuffer: vi.fn(() => ({})),
+  bindRenderbuffer: vi.fn(),
+  renderbufferStorage: vi.fn(),
+  framebufferRenderbuffer: vi.fn(),
+  deleteTexture: vi.fn(),
+  deleteBuffer: vi.fn(),
+  deleteProgram: vi.fn(),
+  deleteShader: vi.fn(),
+  deleteFramebuffer: vi.fn(),
+  deleteRenderbuffer: vi.fn(),
+  createVertexArray: vi.fn(() => ({})),
+  bindVertexArray: vi.fn(),
+  deleteVertexArray: vi.fn(),
+  flush: vi.fn(),
+  finish: vi.fn(),
+  isContextLost: vi.fn(() => false),
+}
+
+HTMLCanvasElement.prototype.getContext = function (
+  contextType: string
+): RenderingContext | null {
+  if (contextType === 'webgl2' || contextType === 'webgl') {
+    return {
+      ...mockWebGL2Context,
+      canvas: this,
+    } as unknown as WebGL2RenderingContext
+  }
+  return null
+}
+```
+
+### Test First
+
+Create `src/components/__tests__/NiiVueViewer.test.tsx`:
+
+```typescript
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import { NiiVueViewer } from '../NiiVueViewer'
+
+// Mock the NiiVue module since it requires actual WebGL
+vi.mock('@niivue/niivue', () => ({
+  Niivue: vi.fn().mockImplementation(() => ({
+    attachToCanvas: vi.fn(),
+    loadVolumes: vi.fn().mockResolvedValue(undefined),
+    setSliceType: vi.fn(),
+    cleanup: vi.fn(), // NiiVue's cleanup() releases event listeners/observers
+    gl: {
+      getExtension: vi.fn(() => ({ loseContext: vi.fn() })),
+    },
+    opts: {},
+  })),
+}))
+
+describe('NiiVueViewer', () => {
+  const defaultProps = {
+    backgroundUrl: 'http://localhost:7860/files/dwi.nii.gz',
+  }
+
+  it('renders canvas element', () => {
+    render(<NiiVueViewer {...defaultProps} />)
+
+    expect(document.querySelector('canvas')).toBeInTheDocument()
+  })
+
+  it('renders container with correct styling', () => {
+    render(<NiiVueViewer {...defaultProps} />)
+
+    const container = document.querySelector('canvas')?.parentElement
+    expect(container).toHaveClass('bg-gray-900')
+  })
+
+  it('renders help text for controls', () => {
+    render(<NiiVueViewer {...defaultProps} />)
+
+    expect(screen.getByText(/scroll/i)).toBeInTheDocument()
+    expect(screen.getByText(/drag/i)).toBeInTheDocument()
+  })
+
+  it('initializes NiiVue with background volume', async () => {
+    const { Niivue } = await import('@niivue/niivue')
+
+    render(<NiiVueViewer {...defaultProps} />)
+
+    expect(Niivue).toHaveBeenCalled()
+  })
+
+  it('loads overlay when provided', async () => {
+    const { Niivue } = await import('@niivue/niivue')
+    const mockInstance = {
+      attachToCanvas: vi.fn(),
+      loadVolumes: vi.fn().mockResolvedValue(undefined),
+      cleanup: vi.fn(),
+      gl: { getExtension: vi.fn(() => ({ loseContext: vi.fn() })) },
+      opts: {},
+    }
+    ;(Niivue as unknown as ReturnType<typeof vi.fn>).mockImplementation(
+      () => mockInstance
+    )
+
+    render(
+      <NiiVueViewer
+        {...defaultProps}
+        overlayUrl="http://localhost:7860/files/prediction.nii.gz"
+      />
+    )
+
+    // Wait for useEffect to run
+    await waitFor(() => {
+      expect(mockInstance.loadVolumes).toHaveBeenCalled()
+    })
+
+    const loadVolumesCall = mockInstance.loadVolumes.mock.calls[0][0]
+    expect(loadVolumesCall).toHaveLength(2)
+    expect(loadVolumesCall[1].url).toContain('prediction.nii.gz')
+  })
+
+  it('sets canvas dimensions', () => {
+    render(<NiiVueViewer {...defaultProps} />)
+
+    const canvas = document.querySelector('canvas')
+    expect(canvas).toHaveClass('w-full', 'h-[500px]')
+  })
+})
+```
+
+### Implementation
+
+Create `src/components/NiiVueViewer.tsx`:
+
+```typescript
+import { useRef, useEffect } from 'react'
+import { Niivue } from '@niivue/niivue'
+
+interface NiiVueViewerProps {
+  backgroundUrl: string
+  overlayUrl?: string
+}
+
+export function NiiVueViewer({ backgroundUrl, overlayUrl }: NiiVueViewerProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const nvRef = useRef<Niivue | null>(null)
+
+  useEffect(() => {
+    if (!canvasRef.current) return
+
+    // Only instantiate NiiVue once; reuse for volume reloads
+    let nv = nvRef.current
+    if (!nv) {
+      nv = new Niivue({
+        backColor: [0.05, 0.05, 0.05, 1],
+        show3Dcrosshair: true,
+        crosshairColor: [1, 0, 0, 0.5],
+      })
+      nv.attachToCanvas(canvasRef.current)
+      nvRef.current = nv
+    }
+
+    // Build volumes array - always reload when URLs change
+    const volumes: Array<{ url: string; colormap: string; opacity: number }> = [
+      { url: backgroundUrl, colormap: 'gray', opacity: 1 },
+    ]
+
+    if (overlayUrl) {
+      volumes.push({
+        url: overlayUrl,
+        colormap: 'red',
+        opacity: 0.5,
+      })
+    }
+
+    // Load volumes (async but we don't await - just fire off)
+    void nv.loadVolumes(volumes)
+
+    // Cleanup on unmount - CRITICAL: Release WebGL context
+    // Browsers limit WebGL contexts (~16 in Chrome). Without cleanup,
+    // navigating between results will exhaust contexts and break the viewer.
+    return () => {
+      if (nvRef.current) {
+        // Capture gl BEFORE cleanup (cleanup may null internal state)
+        const gl = nvRef.current.gl
+        try {
+          // NiiVue's cleanup() releases event listeners and observers
+          // See: https://niivue.github.io/niivue/devdocs/classes/Niivue.html#cleanup
+          nvRef.current.cleanup()
+          // Force WebGL context loss to free GPU memory immediately
+          if (gl) {
+            const ext = gl.getExtension('WEBGL_lose_context')
+            ext?.loseContext()
+          }
+        } catch {
+          // Ignore cleanup errors
+        }
+        nvRef.current = null
+      }
+    }
+  }, [backgroundUrl, overlayUrl])
+
+  return (
+    <div className="bg-gray-900 rounded-lg p-2">
+      <canvas ref={canvasRef} className="w-full h-[500px] rounded" />
+      <div className="flex gap-4 mt-2 text-xs text-gray-400">
+        <span>Scroll: Navigate slices</span>
+        <span>Drag: Adjust contrast</span>
+        <span>Right-click: Pan</span>
+      </div>
+    </div>
+  )
+}
+```
+
+### Verify
+
+```bash
+npm test -- NiiVueViewer
+# Expected: 6 tests passing
+```
+
+---
+
+## Update Component Index
+
+Update `src/components/index.ts`:
+
+```typescript
+export { Layout } from './Layout'
+export { MetricsPanel } from './MetricsPanel'
+export { CaseSelector } from './CaseSelector'
+export { NiiVueViewer } from './NiiVueViewer'
+```
+
+---
+
+## Visual Verification
+
+Update `src/App.tsx` to preview all components:
+
+```typescript
+import { useState } from 'react'
+import { Layout } from './components/Layout'
+import { CaseSelector } from './components/CaseSelector'
+import { MetricsPanel } from './components/MetricsPanel'
+import { NiiVueViewer } from './components/NiiVueViewer'
+
+const mockMetrics = {
+  caseId: 'sub-stroke0001',
+  diceScore: 0.847,
+  volumeMl: 15.32,
+  elapsedSeconds: 12.5,
+}
+
+// Demo NIfTI file from NiiVue examples
+const DEMO_NIFTI = 'https://niivue.github.io/niivue-demo-images/mni152.nii.gz'
+
+function App() {
+  const [selectedCase, setSelectedCase] = useState<string | null>(null)
+
+  return (
+    <Layout>
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+        <div className="space-y-4">
+          <CaseSelector
+            selectedCase={selectedCase}
+            onSelectCase={setSelectedCase}
+          />
+          <MetricsPanel metrics={mockMetrics} />
+        </div>
+        <div className="lg:col-span-2">
+          <NiiVueViewer backgroundUrl={DEMO_NIFTI} />
+        </div>
+      </div>
+    </Layout>
+  )
+}
+
+export default App
+```
+
+```bash
+npm run dev
+# Open http://localhost:5173
+# Verify:
+# - CaseSelector loads and shows cases
+# - NiiVue viewer renders 3D brain
+# - MetricsPanel displays correctly
+```
+
+---
+
+## Verification Checklist
+
+```bash
+npm test
+# Expected: ~35+ tests passing
+```
+
+- [ ] CaseSelector shows loading state
+- [ ] CaseSelector fetches and displays cases
+- [ ] CaseSelector calls onSelectCase on selection
+- [ ] CaseSelector shows error state on API failure
+- [ ] NiiVueViewer renders canvas
+- [ ] NiiVueViewer initializes NiiVue instance
+- [ ] NiiVueViewer loads overlay when provided
+- [ ] Visual: All components render correctly in browser
+
+---
+
+## File Structure After This Phase
+
+```text
+frontend/src/
+├── components/
+│   ├── __tests__/
+│   │   ├── Layout.test.tsx
+│   │   ├── MetricsPanel.test.tsx
+│   │   ├── CaseSelector.test.tsx
+│   │   └── NiiVueViewer.test.tsx
+│   ├── Layout.tsx
+│   ├── MetricsPanel.tsx
+│   ├── CaseSelector.tsx
+│   ├── NiiVueViewer.tsx
+│   └── index.ts
+├── api/
+├── hooks/
+├── types/
+├── test/
+│   └── setup.ts (updated with WebGL mocks)
+├── mocks/
+└── App.tsx (updated)
+```
+
+---
+
+## Next Phase
+
+Once verification passes, proceed to **Spec 37.4: App Integration**

docs/specs/frontend/37-4-app-integration.md

@@ -0,0 +1,461 @@
+# Spec 37.4: App Integration
+
+**Status**: READY FOR IMPLEMENTATION
+**Phase**: 4 of 5
+**Depends On**: Spec 37.3 (Interactive Components)
+**Goal**: Wire all components together into a working application
+
+---
+
+## Deliverables
+
+By the end of this phase, you will have:
+
+1. Complete `App.tsx` with full user flow
+2. Integration tests for the complete workflow
+3. Error handling for all states
+4. Working end-to-end flow (with mocked API)
+
+---
+
+## Step 1: App Integration Tests
+
+Create `src/App.test.tsx`:
+
+```typescript
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { server } from './mocks/server'
+import { errorHandlers } from './mocks/handlers'
+import App from './App'
+
+describe('App Integration', () => {
+  describe('Initial Render', () => {
+    it('renders main heading', () => {
+      render(<App />)
+
+      expect(
+        screen.getByRole('heading', { name: /stroke lesion segmentation/i })
+      ).toBeInTheDocument()
+    })
+
+    it('renders case selector', async () => {
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+    })
+
+    it('renders run button', () => {
+      render(<App />)
+
+      expect(
+        screen.getByRole('button', { name: /run segmentation/i })
+      ).toBeInTheDocument()
+    })
+
+    it('shows placeholder viewer message', () => {
+      render(<App />)
+
+      expect(
+        screen.getByText(/select a case and run segmentation/i)
+      ).toBeInTheDocument()
+    })
+  })
+
+  describe('Run Button State', () => {
+    it('disables run button when no case selected', async () => {
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      expect(
+        screen.getByRole('button', { name: /run segmentation/i })
+      ).toBeDisabled()
+    })
+
+    it('enables run button when case selected', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+
+      expect(
+        screen.getByRole('button', { name: /run segmentation/i })
+      ).toBeEnabled()
+    })
+  })
+
+  describe('Segmentation Flow', () => {
+    it('shows processing state when running', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      expect(screen.getByText(/processing/i)).toBeInTheDocument()
+    })
+
+    it('displays metrics after successful segmentation', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByText('0.847')).toBeInTheDocument()
+      })
+
+      expect(screen.getByText('15.32 mL')).toBeInTheDocument()
+      expect(screen.getByText(/12\.5s/)).toBeInTheDocument()
+    })
+
+    it('displays viewer after successful segmentation', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(document.querySelector('canvas')).toBeInTheDocument()
+      })
+    })
+
+    it('hides placeholder after successful segmentation', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByText('0.847')).toBeInTheDocument()
+      })
+
+      expect(
+        screen.queryByText(/select a case and run segmentation/i)
+      ).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Error Handling', () => {
+    it('shows error when segmentation fails', async () => {
+      server.use(errorHandlers.segmentServerError)
+      const user = userEvent.setup()
+
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByRole('alert')).toBeInTheDocument()
+      })
+
+      expect(screen.getByText(/segmentation failed/i)).toBeInTheDocument()
+    })
+
+    it('allows retry after error', async () => {
+      server.use(errorHandlers.segmentServerError)
+      const user = userEvent.setup()
+
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByRole('alert')).toBeInTheDocument()
+      })
+
+      // Reset to success handler
+      server.resetHandlers()
+
+      // Retry
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByText('0.847')).toBeInTheDocument()
+      })
+
+      expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Multiple Runs', () => {
+    it('allows running segmentation on different cases', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      // First case
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByText('sub-stroke0001')).toBeInTheDocument()
+      })
+
+      // Second case
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0002')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByText('sub-stroke0002')).toBeInTheDocument()
+      })
+    })
+  })
+})
+```
+
+---
+
+## Step 2: App Implementation
+
+Replace `src/App.tsx`:
+
+```typescript
+import { useState } from 'react'
+import { Layout } from './components/Layout'
+import { CaseSelector } from './components/CaseSelector'
+import { NiiVueViewer } from './components/NiiVueViewer'
+import { MetricsPanel } from './components/MetricsPanel'
+import { useSegmentation } from './hooks/useSegmentation'
+
+export default function App() {
+  const [selectedCase, setSelectedCase] = useState<string | null>(null)
+  const { result, isLoading, error, runSegmentation } = useSegmentation()
+
+  const handleRunSegmentation = async () => {
+    if (selectedCase) {
+      await runSegmentation(selectedCase)
+    }
+  }
+
+  return (
+    <Layout>
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+        {/* Left Panel: Controls */}
+        <div className="space-y-4">
+          <CaseSelector
+            selectedCase={selectedCase}
+            onSelectCase={setSelectedCase}
+          />
+
+          <button
+            onClick={handleRunSegmentation}
+            disabled={!selectedCase || isLoading}
+            className="w-full bg-blue-600 hover:bg-blue-700 disabled:bg-gray-600
+                       disabled:cursor-not-allowed text-white font-medium
+                       py-3 px-4 rounded-lg transition-colors"
+          >
+            {isLoading ? 'Processing...' : 'Run Segmentation'}
+          </button>
+
+          {error && (
+            <div role="alert" className="bg-red-900/50 text-red-300 p-3 rounded-lg">
+              {error}
+            </div>
+          )}
+
+          {result && <MetricsPanel metrics={result.metrics} />}
+        </div>
+
+        {/* Right Panel: Viewer */}
+        <div className="lg:col-span-2">
+          {result ? (
+            <NiiVueViewer
+              backgroundUrl={result.dwiUrl}
+              overlayUrl={result.predictionUrl}
+            />
+          ) : (
+            <div className="bg-gray-900 rounded-lg h-[500px] flex items-center justify-center">
+              <p className="text-gray-400">
+                Select a case and run segmentation to view results
+              </p>
+            </div>
+          )}
+        </div>
+      </div>
+    </Layout>
+  )
+}
+```
+
+---
+
+## Step 3: Run Tests
+
+```bash
+npm test
+# Expected: ~45+ tests passing
+```
+
+---
+
+## Step 4: Visual Verification
+
+```bash
+npm run dev
+# Open http://localhost:5173
+```
+
+**Manual Test Checklist:**
+
+1. [ ] Page loads with header
+2. [ ] Case selector shows "Loading cases..."
+3. [ ] Case selector populates with 3 cases
+4. [ ] Run button is disabled initially
+5. [ ] Selecting a case enables run button
+6. [ ] Clicking run shows "Processing..."
+7. [ ] After completion, metrics panel appears
+8. [ ] After completion, viewer shows (with demo image)
+9. [ ] Selecting different case and running updates results
+
+---
+
+## Step 5: Test Custom Render Utility (Optional Enhancement)
+
+Create `src/test/test-utils.tsx`:
+
+```typescript
+import type { ReactElement, ReactNode } from 'react'
+import { render, RenderOptions } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+// Wrapper for any providers (Router, Theme, etc.)
+function AllTheProviders({ children }: { children: ReactNode }) {
+  return <>{children}</>
+}
+
+function customRender(
+  ui: ReactElement,
+  options?: Omit<RenderOptions, 'wrapper'>
+) {
+  return {
+    user: userEvent.setup(),
+    ...render(ui, { wrapper: AllTheProviders, ...options }),
+  }
+}
+
+// Re-export everything
+export * from '@testing-library/react'
+export { customRender as render }
+```
+
+Update tests to use custom render (optional):
+
+```typescript
+import { render, screen, waitFor } from '../test/test-utils'
+// Now `render` returns `{ user, ...result }`
+```
+
+---
+
+## Verification Checklist
+
+```bash
+# All tests pass
+npm test
+# Expected: ~45+ tests passing
+
+# Build succeeds
+npm run build
+# Expected: dist/ folder created
+
+# No TypeScript errors
+npx tsc --noEmit
+# Expected: No errors
+```
+
+- [ ] All integration tests pass
+- [ ] Full flow works in browser
+- [ ] Error states display correctly
+- [ ] Loading states display correctly
+- [ ] Results update on new runs
+
+---
+
+## File Structure After This Phase
+
+```
+frontend/src/
+├── components/
+│   ├── __tests__/
+│   │   ├── Layout.test.tsx
+│   │   ├── MetricsPanel.test.tsx
+│   │   ├── CaseSelector.test.tsx
+│   │   └── NiiVueViewer.test.tsx
+│   ├── Layout.tsx
+│   ├── MetricsPanel.tsx
+│   ├── CaseSelector.tsx
+│   ├── NiiVueViewer.tsx
+│   └── index.ts
+├── api/
+│   ├── __tests__/
+│   │   └── client.test.ts
+│   ├── client.ts
+│   └── index.ts
+├── hooks/
+│   ├── __tests__/
+│   │   └── useSegmentation.test.tsx
+│   ├── useSegmentation.ts
+│   └── index.ts
+├── types/
+│   └── index.ts
+├── test/
+│   ├── setup.ts
+│   ├── fixtures.ts
+│   └── test-utils.tsx
+├── mocks/
+│   ├── handlers.ts
+│   └── server.ts
+├── App.tsx
+├── App.test.tsx
+├── main.tsx
+└── index.css
+```
+
+---
+
+## Next Phase
+
+Once verification passes, proceed to **Spec 37.5: E2E Tests & CI/CD**

docs/specs/frontend/37-5-e2e-and-ci.md

@@ -0,0 +1,607 @@
+# Spec 37.5: E2E Tests & CI/CD
+
+**Status**: READY FOR IMPLEMENTATION
+**Phase**: 5 of 5
+**Depends On**: Spec 37.4 (App Integration)
+**Goal**: End-to-end tests with Playwright and GitHub Actions CI pipeline
+
+---
+
+## Deliverables
+
+By the end of this phase, you will have:
+
+1. Playwright E2E tests for critical user flows
+2. Page Object Models for maintainable tests
+3. GitHub Actions workflow for CI
+4. Coverage reporting integration
+
+---
+
+## Step 1: Install Playwright
+
+```bash
+cd frontend
+npm install -D @playwright/test@1.49.1
+npx playwright install
+```
+
+---
+
+## Step 2: Playwright Configuration
+
+Create `playwright.config.ts`:
+
+```typescript
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { open: 'never' }],
+    ['list'],
+    ...(process.env.CI ? [['github' as const]] : []),
+  ],
+  use: {
+    baseURL: 'http://localhost:5173',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    // Uncomment for cross-browser testing:
+    // {
+    //   name: 'firefox',
+    //   use: { ...devices['Desktop Firefox'] },
+    // },
+    // {
+    //   name: 'webkit',
+    //   use: { ...devices['Desktop Safari'] },
+    // },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+})
+```
+
+---
+
+## Step 3: Update package.json Scripts
+
+Add to `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:debug": "playwright test --debug"
+  }
+}
+```
+
+---
+
+## Step 4: Page Object Model
+
+Create `e2e/pages/HomePage.ts`:
+
+```typescript
+import { type Page, type Locator, expect } from '@playwright/test'
+
+export class HomePage {
+  readonly page: Page
+  readonly heading: Locator
+  readonly caseSelector: Locator
+  readonly runButton: Locator
+  readonly processingText: Locator
+  readonly metricsPanel: Locator
+  readonly diceScore: Locator
+  readonly viewer: Locator
+  readonly placeholderText: Locator
+  readonly errorAlert: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.heading = page.getByRole('heading', {
+      name: /stroke lesion segmentation/i,
+    })
+    this.caseSelector = page.getByRole('combobox')
+    this.runButton = page.getByRole('button', { name: /run segmentation/i })
+    this.processingText = page.getByText(/processing/i)
+    this.metricsPanel = page.getByRole('heading', { name: /results/i })
+    this.diceScore = page.getByText(/0\.\d{3}/)
+    this.viewer = page.locator('canvas')
+    this.placeholderText = page.getByText(/select a case and run segmentation/i)
+    this.errorAlert = page.getByRole('alert')
+  }
+
+  async goto() {
+    await this.page.goto('/')
+    await expect(this.heading).toBeVisible()
+  }
+
+  async waitForCasesToLoad() {
+    await expect(this.caseSelector).toBeEnabled({ timeout: 10000 })
+  }
+
+  async selectCase(caseId: string) {
+    await this.caseSelector.selectOption(caseId)
+  }
+
+  async runSegmentation() {
+    await this.runButton.click()
+  }
+
+  async waitForResults() {
+    await expect(this.metricsPanel).toBeVisible({ timeout: 30000 })
+  }
+
+  async expectViewerVisible() {
+    await expect(this.viewer).toBeVisible()
+  }
+
+  async expectPlaceholderVisible() {
+    await expect(this.placeholderText).toBeVisible()
+  }
+
+  async expectErrorVisible() {
+    await expect(this.errorAlert).toBeVisible()
+  }
+}
+```
+
+---
+
+## Step 5: Global API Mocking Fixture
+
+**CRITICAL:** E2E tests run against `npm run dev` which has no backend.
+Without API mocking, tests will hang or fail on API calls.
+
+Create `e2e/fixtures.ts` - Global mock for all API calls:
+
+```typescript
+import { test as base, expect } from '@playwright/test'
+
+// API response mocks matching MSW handlers
+const MOCK_CASES = ['sub-stroke0001', 'sub-stroke0002', 'sub-stroke0003']
+const MOCK_SEGMENT_RESPONSE = {
+  caseId: 'sub-stroke0001',
+  diceScore: 0.847,
+  volumeMl: 15.32,
+  elapsedSeconds: 12.5,
+  // Use a real public NIfTI for visual testing (NiiVue demo image)
+  dwiUrl: 'https://niivue.github.io/niivue-demo-images/mni152.nii.gz',
+  predictionUrl: 'https://niivue.github.io/niivue-demo-images/mni152.nii.gz',
+}
+
+// Extend base test to include API mocking
+export const test = base.extend({
+  // Auto-mock API routes for every test
+  page: async ({ page }, use) => {
+    // Mock GET /api/cases
+    await page.route('**/api/cases', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ cases: MOCK_CASES }),
+      })
+    })
+
+    // Mock POST /api/segment - return different caseId based on request
+    await page.route('**/api/segment', async (route) => {
+      const request = route.request()
+      const body = JSON.parse(request.postData() || '{}')
+
+      // Simulate network delay
+      await new Promise((r) => setTimeout(r, 200))
+
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          ...MOCK_SEGMENT_RESPONSE,
+          caseId: body.case_id || 'sub-stroke0001',
+        }),
+      })
+    })
+
+    await use(page)
+  },
+})
+
+export { expect }
+```
+
+---
+
+## Step 6: E2E Tests
+
+Create `e2e/home.spec.ts`:
+
+```typescript
+import { test, expect } from './fixtures'
+import { HomePage } from './pages/HomePage'
+
+test.describe('Home Page', () => {
+  test('displays main heading', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+
+    await expect(homePage.heading).toBeVisible()
+  })
+
+  test('loads case selector with options', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+    await homePage.waitForCasesToLoad()
+
+    // Verify selector has options
+    const options = await homePage.caseSelector.locator('option').count()
+    expect(options).toBeGreaterThan(1) // placeholder + cases
+  })
+
+  test('shows placeholder viewer initially', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+
+    await homePage.expectPlaceholderVisible()
+  })
+
+  test('run button disabled without case selected', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+    await homePage.waitForCasesToLoad()
+
+    await expect(homePage.runButton).toBeDisabled()
+  })
+})
+```
+
+Create `e2e/segmentation-flow.spec.ts`:
+
+```typescript
+import { test, expect } from './fixtures'
+import { HomePage } from './pages/HomePage'
+
+test.describe('Segmentation Flow', () => {
+  test('complete segmentation workflow', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+    await homePage.waitForCasesToLoad()
+
+    // Select a case
+    await homePage.selectCase('sub-stroke0001')
+    await expect(homePage.runButton).toBeEnabled()
+
+    // Run segmentation
+    await homePage.runSegmentation()
+
+    // Verify processing state
+    await expect(homePage.processingText).toBeVisible()
+
+    // Wait for results
+    await homePage.waitForResults()
+
+    // Verify results displayed
+    await expect(homePage.diceScore).toBeVisible()
+    await homePage.expectViewerVisible()
+
+    // Placeholder should be gone
+    await expect(homePage.placeholderText).not.toBeVisible()
+  })
+
+  test('can run multiple segmentations', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+    await homePage.waitForCasesToLoad()
+
+    // First run
+    await homePage.selectCase('sub-stroke0001')
+    await homePage.runSegmentation()
+    await homePage.waitForResults()
+
+    // Second run with different case
+    await homePage.selectCase('sub-stroke0002')
+    await homePage.runSegmentation()
+    await homePage.waitForResults()
+
+    // Results should still be visible
+    await expect(homePage.metricsPanel).toBeVisible()
+  })
+})
+```
+
+Create `e2e/error-handling.spec.ts`:
+
+```typescript
+import { test as base, expect } from '@playwright/test'
+import { HomePage } from './pages/HomePage'
+
+// Error tests need to override the default mocks, so use base test
+const test = base
+
+test.describe('Error Handling', () => {
+  test('shows error when API fails', async ({ page }) => {
+    // Mock cases API (needed for page to load)
+    await page.route('**/api/cases', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ cases: ['sub-stroke0001'] }),
+      })
+    })
+
+    // Mock segment API to return error
+    await page.route('**/api/segment', (route) => {
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({ detail: 'Segmentation failed' }),
+      })
+    })
+
+    const homePage = new HomePage(page)
+    await homePage.goto()
+    await homePage.waitForCasesToLoad()
+
+    await homePage.selectCase('sub-stroke0001')
+    await homePage.runSegmentation()
+
+    await homePage.expectErrorVisible()
+    await expect(homePage.errorAlert).toContainText(/failed/i)
+  })
+
+  test('shows error when cases fail to load', async ({ page }) => {
+    // Mock cases API to return error
+    await page.route('**/api/cases', (route) => {
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({ detail: 'Server error' }),
+      })
+    })
+
+    const homePage = new HomePage(page)
+    await homePage.goto()
+
+    // Case selector should show error state
+    await expect(page.getByText(/failed to load/i)).toBeVisible()
+  })
+})
+```
+
+---
+
+## Step 7: GitHub Actions CI Workflow
+
+Create `.github/workflows/frontend-ci.yml`:
+
+```yaml
+name: Frontend CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'frontend/**'
+      - '.github/workflows/frontend-ci.yml'
+  pull_request:
+    paths:
+      - 'frontend/**'
+
+defaults:
+  run:
+    working-directory: frontend
+
+jobs:
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npx tsc --noEmit
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npm run test:coverage
+
+      - uses: codecov/codecov-action@v4
+        with:
+          files: frontend/coverage/coverage-final.json
+          flags: frontend
+          fail_ci_if_error: false
+
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+
+      - run: npm run test:e2e
+
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: frontend/playwright-report/
+          retention-days: 7
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [typecheck, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npm run build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: frontend-dist
+          path: frontend/dist/
+          retention-days: 7
+```
+
+---
+
+## Step 8: Add Coverage Thresholds
+
+Update `vite.config.ts` coverage section:
+
+```typescript
+coverage: {
+  provider: 'v8',
+  reporter: ['text', 'json', 'html'],
+  include: ['src/**/*.{ts,tsx}'],
+  exclude: [
+    'src/**/*.test.{ts,tsx}',
+    'src/test/**',
+    'src/mocks/**',
+    'src/main.tsx',
+    'src/vite-env.d.ts',
+  ],
+  thresholds: {
+    statements: 80,
+    branches: 75,
+    functions: 80,
+    lines: 80,
+  },
+},
+```
+
+---
+
+## Step 9: Run All Tests
+
+```bash
+# Unit & Integration tests
+npm test
+# Expected: ~45+ tests passing
+
+# E2E tests
+npm run test:e2e
+# Expected: 7 tests passing
+
+# Coverage report
+npm run test:coverage
+# Expected: >80% coverage
+```
+
+---
+
+## Verification Checklist
+
+- [ ] `npm test` - All unit/integration tests pass
+- [ ] `npm run test:coverage` - Coverage meets thresholds
+- [ ] `npm run test:e2e` - All E2E tests pass
+- [ ] `npm run build` - Production build succeeds
+- [ ] CI workflow runs successfully (push to branch)
+
+---
+
+## File Structure After This Phase
+
+```
+frontend/
+├── e2e/
+│   ├── pages/
+│   │   └── HomePage.ts
+│   ├── fixtures.ts              # <-- NEW: Global API mocking
+│   ├── home.spec.ts
+│   ├── segmentation-flow.spec.ts
+│   └── error-handling.spec.ts
+├── src/
+│   ├── components/
+│   ├── api/
+│   ├── hooks/
+│   ├── types/
+│   ├── test/
+│   ├── mocks/
+│   ├── App.tsx
+│   ├── App.test.tsx
+│   └── ...
+├── .github/
+│   └── workflows/
+│       └── frontend-ci.yml
+├── playwright.config.ts
+├── vite.config.ts
+├── package.json
+└── ...
+```
+
+---
+
+## Summary: Complete Testing Stack
+
+| Layer | Tool | Test Count | Purpose |
+|-------|------|------------|---------|
+| Unit | Vitest + RTL | ~35 | Component isolation |
+| Integration | Vitest + MSW | ~15 | API + hooks |
+| E2E | Playwright | ~7 | Full user flows |
+| **Total** | | **~57** | |
+
+---
+
+## Next Steps After All Phases Complete
+
+1. **Deploy Frontend**: Push to HuggingFace Static Space
+2. **Connect to Backend**: Update `VITE_API_URL` to real backend
+3. **Test Against Real API**: Run E2E tests with real backend
+4. **Monitor**: Set up error tracking (optional)
+
+---
+
+## Congratulations!
+
+You now have a fully tested React frontend with:
+
+- Type-safe TypeScript code
+- Comprehensive unit tests
+- API mocking with MSW
+- End-to-end browser tests
+- Automated CI/CD pipeline
+- 80%+ code coverage

frontend/.env.example

@@ -0,0 +1 @@
+VITE_API_URL=http://localhost:7860

frontend/.gitignore

@@ -0,0 +1,29 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Test output
+coverage
+playwright-report
+test-results

frontend/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

frontend/e2e/error-handling.spec.ts

@@ -0,0 +1,54 @@
+import { test as base, expect } from '@playwright/test'
+import { HomePage } from './pages/HomePage'
+
+// Error tests need to override the default mocks, so use base test
+const test = base
+
+test.describe('Error Handling', () => {
+  test('shows error when API fails', async ({ page }) => {
+    // Mock cases API (needed for page to load)
+    await page.route('**/api/cases', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ cases: ['sub-stroke0001'] }),
+      })
+    })
+
+    // Mock segment API to return error
+    await page.route('**/api/segment', (route) => {
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({ detail: 'Segmentation failed' }),
+      })
+    })
+
+    const homePage = new HomePage(page)
+    await homePage.goto()
+    await homePage.waitForCasesToLoad()
+
+    await homePage.selectCase('sub-stroke0001')
+    await homePage.runSegmentation()
+
+    await homePage.expectErrorVisible()
+    await expect(homePage.errorAlert).toContainText(/failed/i)
+  })
+
+  test('shows error when cases fail to load', async ({ page }) => {
+    // Mock cases API to return error
+    await page.route('**/api/cases', (route) => {
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({ detail: 'Server error' }),
+      })
+    })
+
+    const homePage = new HomePage(page)
+    await homePage.goto()
+
+    // Case selector should show error state
+    await expect(page.getByText(/failed to load/i)).toBeVisible()
+  })
+})

frontend/e2e/fixtures.ts

@@ -0,0 +1,50 @@
+import { test as base, expect } from '@playwright/test'
+
+// API response mocks matching MSW handlers
+const MOCK_CASES = ['sub-stroke0001', 'sub-stroke0002', 'sub-stroke0003']
+const MOCK_SEGMENT_RESPONSE = {
+  caseId: 'sub-stroke0001',
+  diceScore: 0.847,
+  volumeMl: 15.32,
+  elapsedSeconds: 12.5,
+  // Use real public NIfTI for visual testing (NiiVue demo image)
+  dwiUrl: 'https://niivue.github.io/niivue-demo-images/mni152.nii.gz',
+  predictionUrl: 'https://niivue.github.io/niivue-demo-images/mni152.nii.gz',
+}
+
+// Extend base test to include API mocking
+export const test = base.extend({
+  // Auto-mock API routes for every test
+  page: async ({ page }, use) => {
+    // Mock GET /api/cases
+    await page.route('**/api/cases', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ cases: MOCK_CASES }),
+      })
+    })
+
+    // Mock POST /api/segment - return different caseId based on request
+    await page.route('**/api/segment', async (route) => {
+      const request = route.request()
+      const body = JSON.parse(request.postData() || '{}') as { case_id?: string }
+
+      // Simulate network delay
+      await new Promise((r) => setTimeout(r, 200))
+
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          ...MOCK_SEGMENT_RESPONSE,
+          caseId: body.case_id || 'sub-stroke0001',
+        }),
+      })
+    })
+
+    await use(page)
+  },
+})
+
+export { expect }

frontend/e2e/home.spec.ts

@@ -0,0 +1,36 @@
+import { test, expect } from './fixtures'
+import { HomePage } from './pages/HomePage'
+
+test.describe('Home Page', () => {
+  test('displays main heading', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+
+    await expect(homePage.heading).toBeVisible()
+  })
+
+  test('loads case selector with options', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+    await homePage.waitForCasesToLoad()
+
+    // Verify selector has options
+    const options = await homePage.caseSelector.locator('option').count()
+    expect(options).toBeGreaterThan(1) // placeholder + cases
+  })
+
+  test('shows placeholder viewer initially', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+
+    await homePage.expectPlaceholderVisible()
+  })
+
+  test('run button disabled without case selected', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+    await homePage.waitForCasesToLoad()
+
+    await expect(homePage.runButton).toBeDisabled()
+  })
+})

frontend/e2e/pages/HomePage.ts

@@ -0,0 +1,62 @@
+import { type Page, type Locator, expect } from '@playwright/test'
+
+export class HomePage {
+  readonly page: Page
+  readonly heading: Locator
+  readonly caseSelector: Locator
+  readonly runButton: Locator
+  readonly processingText: Locator
+  readonly metricsPanel: Locator
+  readonly diceScore: Locator
+  readonly viewer: Locator
+  readonly placeholderText: Locator
+  readonly errorAlert: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.heading = page.getByRole('heading', {
+      name: /stroke lesion segmentation/i,
+    })
+    this.caseSelector = page.getByRole('combobox')
+    this.runButton = page.getByRole('button', { name: /run segmentation/i })
+    this.processingText = page.getByText(/processing/i)
+    this.metricsPanel = page.getByRole('heading', { name: /results/i })
+    this.diceScore = page.getByText(/0\.\d{3}/)
+    this.viewer = page.locator('canvas')
+    this.placeholderText = page.getByText(/select a case and run segmentation/i)
+    this.errorAlert = page.getByRole('alert')
+  }
+
+  async goto() {
+    await this.page.goto('/')
+    await expect(this.heading).toBeVisible()
+  }
+
+  async waitForCasesToLoad() {
+    await expect(this.caseSelector).toBeEnabled({ timeout: 10000 })
+  }
+
+  async selectCase(caseId: string) {
+    await this.caseSelector.selectOption(caseId)
+  }
+
+  async runSegmentation() {
+    await this.runButton.click()
+  }
+
+  async waitForResults() {
+    await expect(this.metricsPanel).toBeVisible({ timeout: 30000 })
+  }
+
+  async expectViewerVisible() {
+    await expect(this.viewer).toBeVisible()
+  }
+
+  async expectPlaceholderVisible() {
+    await expect(this.placeholderText).toBeVisible()
+  }
+
+  async expectErrorVisible() {
+    await expect(this.errorAlert).toBeVisible()
+  }
+}

frontend/e2e/segmentation-flow.spec.ts

@@ -0,0 +1,49 @@
+import { test, expect } from './fixtures'
+import { HomePage } from './pages/HomePage'
+
+test.describe('Segmentation Flow', () => {
+  test('complete segmentation workflow', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+    await homePage.waitForCasesToLoad()
+
+    // Select a case
+    await homePage.selectCase('sub-stroke0001')
+    await expect(homePage.runButton).toBeEnabled()
+
+    // Run segmentation
+    await homePage.runSegmentation()
+
+    // Verify processing state
+    await expect(homePage.processingText).toBeVisible()
+
+    // Wait for results
+    await homePage.waitForResults()
+
+    // Verify results displayed
+    await expect(homePage.diceScore).toBeVisible()
+    await homePage.expectViewerVisible()
+
+    // Placeholder should be gone
+    await expect(homePage.placeholderText).not.toBeVisible()
+  })
+
+  test('can run multiple segmentations', async ({ page }) => {
+    const homePage = new HomePage(page)
+    await homePage.goto()
+    await homePage.waitForCasesToLoad()
+
+    // First run
+    await homePage.selectCase('sub-stroke0001')
+    await homePage.runSegmentation()
+    await homePage.waitForResults()
+
+    // Second run with different case
+    await homePage.selectCase('sub-stroke0002')
+    await homePage.runSegmentation()
+    await homePage.waitForResults()
+
+    // Results should still be visible
+    await expect(homePage.metricsPanel).toBeVisible()
+  })
+})

frontend/eslint.config.js

@@ -0,0 +1,33 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist', 'coverage']),
+  // Main source files - full React rules
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+  // E2E tests - Playwright, not React (disable react-hooks rules)
+  {
+    files: ['e2e/**/*.{ts,tsx}'],
+    extends: [js.configs.recommended, tseslint.configs.recommended],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: { ...globals.browser, ...globals.node },
+    },
+  },
+])

frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Stroke Lesion Segmentation</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:debug": "playwright test --debug"
+  },
+  "dependencies": {
+    "@niivue/niivue": "^0.65.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@playwright/test": "^1.57.0",
+    "@tailwindcss/vite": "^4.1.17",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/ui": "^4.0.15",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "jsdom": "^25.0.1",
+    "msw": "^2.7.0",
+    "tailwindcss": "^4.1.17",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4",
+    "vitest": "^4.0.15"
+  }
+}

frontend/playwright.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { open: 'never' }],
+    ['list'],
+    ...(process.env.CI ? [['github' as const]] : []),
+  ],
+  use: {
+    baseURL: 'http://localhost:5173',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+})

frontend/src/App.test.tsx

@@ -0,0 +1,240 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { server } from './mocks/server'
+import { errorHandlers } from './mocks/handlers'
+import App from './App'
+
+// Mock NiiVue to avoid WebGL in tests
+vi.mock('@niivue/niivue', () => ({
+  Niivue: class MockNiivue {
+    attachToCanvas = vi.fn()
+    loadVolumes = vi.fn().mockResolvedValue(undefined)
+    cleanup = vi.fn()
+    gl = {
+      getExtension: vi.fn(() => ({ loseContext: vi.fn() })),
+    }
+    opts = {}
+  },
+}))
+
+describe('App Integration', () => {
+  describe('Initial Render', () => {
+    it('renders main heading', () => {
+      render(<App />)
+
+      expect(
+        screen.getByRole('heading', { name: /stroke lesion segmentation/i })
+      ).toBeInTheDocument()
+    })
+
+    it('renders case selector', async () => {
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+    })
+
+    it('renders run button', () => {
+      render(<App />)
+
+      expect(
+        screen.getByRole('button', { name: /run segmentation/i })
+      ).toBeInTheDocument()
+    })
+
+    it('shows placeholder viewer message', () => {
+      render(<App />)
+
+      expect(
+        screen.getByText(/select a case and run segmentation/i)
+      ).toBeInTheDocument()
+    })
+  })
+
+  describe('Run Button State', () => {
+    it('disables run button when no case selected', async () => {
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      expect(
+        screen.getByRole('button', { name: /run segmentation/i })
+      ).toBeDisabled()
+    })
+
+    it('enables run button when case selected', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+
+      expect(
+        screen.getByRole('button', { name: /run segmentation/i })
+      ).toBeEnabled()
+    })
+  })
+
+  describe('Segmentation Flow', () => {
+    it('shows processing state when running', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      expect(screen.getByText(/processing/i)).toBeInTheDocument()
+    })
+
+    it('displays metrics after successful segmentation', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByText('0.847')).toBeInTheDocument()
+      })
+
+      expect(screen.getByText('15.32 mL')).toBeInTheDocument()
+      expect(screen.getByText(/12\.5s/)).toBeInTheDocument()
+    })
+
+    it('displays viewer after successful segmentation', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(document.querySelector('canvas')).toBeInTheDocument()
+      })
+    })
+
+    it('hides placeholder after successful segmentation', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByText('0.847')).toBeInTheDocument()
+      })
+
+      expect(
+        screen.queryByText(/select a case and run segmentation/i)
+      ).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Error Handling', () => {
+    it('shows error when segmentation fails', async () => {
+      server.use(errorHandlers.segmentServerError)
+      const user = userEvent.setup()
+
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByRole('alert')).toBeInTheDocument()
+      })
+
+      expect(screen.getByText(/segmentation failed/i)).toBeInTheDocument()
+    })
+
+    it('allows retry after error', async () => {
+      server.use(errorHandlers.segmentServerError)
+      const user = userEvent.setup()
+
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByRole('alert')).toBeInTheDocument()
+      })
+
+      // Reset to success handler
+      server.resetHandlers()
+
+      // Retry
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByText('0.847')).toBeInTheDocument()
+      })
+
+      expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Multiple Runs', () => {
+    it('allows running segmentation on different cases', async () => {
+      const user = userEvent.setup()
+      render(<App />)
+
+      await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument()
+      })
+
+      // First case
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0001')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      // Wait for first segmentation to complete
+      await waitFor(() => {
+        expect(screen.getByText('sub-stroke0001')).toBeInTheDocument()
+      })
+
+      // Wait for button to be ready again (not "Processing...")
+      await waitFor(() => {
+        expect(screen.getByRole('button', { name: /run segmentation/i })).toBeInTheDocument()
+      })
+
+      // Second case
+      await user.selectOptions(screen.getByRole('combobox'), 'sub-stroke0002')
+      await user.click(screen.getByRole('button', { name: /run segmentation/i }))
+
+      await waitFor(() => {
+        expect(screen.getByText('sub-stroke0002')).toBeInTheDocument()
+      })
+    })
+  })
+})

frontend/src/App.tsx

@@ -0,0 +1,65 @@
+import { useState } from 'react'
+import { Layout } from './components/Layout'
+import { CaseSelector } from './components/CaseSelector'
+import { NiiVueViewer } from './components/NiiVueViewer'
+import { MetricsPanel } from './components/MetricsPanel'
+import { useSegmentation } from './hooks/useSegmentation'
+
+export default function App() {
+  const [selectedCase, setSelectedCase] = useState<string | null>(null)
+  const { result, isLoading, error, runSegmentation } = useSegmentation()
+
+  const handleRunSegmentation = async () => {
+    if (selectedCase) {
+      await runSegmentation(selectedCase)
+    }
+  }
+
+  return (
+    <Layout>
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+        {/* Left Panel: Controls */}
+        <div className="space-y-4">
+          <CaseSelector
+            selectedCase={selectedCase}
+            onSelectCase={setSelectedCase}
+          />
+
+          <button
+            onClick={handleRunSegmentation}
+            disabled={!selectedCase || isLoading}
+            className="w-full bg-blue-600 hover:bg-blue-700 disabled:bg-gray-600
+                       disabled:cursor-not-allowed text-white font-medium
+                       py-3 px-4 rounded-lg transition-colors"
+          >
+            {isLoading ? 'Processing...' : 'Run Segmentation'}
+          </button>
+
+          {error && (
+            <div role="alert" className="bg-red-900/50 text-red-300 p-3 rounded-lg">
+              {error}
+            </div>
+          )}
+
+          {result && <MetricsPanel metrics={result.metrics} />}
+        </div>
+
+        {/* Right Panel: Viewer */}
+        <div className="lg:col-span-2">
+          {result ? (
+            <NiiVueViewer
+              backgroundUrl={result.dwiUrl}
+              overlayUrl={result.predictionUrl}
+            />
+          ) : (
+            <div className="bg-gray-900 rounded-lg h-[500px] flex items-center justify-center">
+              <p className="text-gray-400">
+                Select a case and run segmentation to view results
+              </p>
+            </div>
+          )}
+        </div>
+      </div>
+    </Layout>
+  )
+}

frontend/src/api/__tests__/client.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest'
+import { server } from '../../mocks/server'
+import { errorHandlers } from '../../mocks/handlers'
+import { apiClient } from '../client'
+
+describe('apiClient', () => {
+  describe('getCases', () => {
+    it('returns list of case IDs', async () => {
+      const result = await apiClient.getCases()
+
+      expect(result.cases).toHaveLength(3)
+      expect(result.cases).toContain('sub-stroke0001')
+    })
+
+    it('throws ApiError on server error', async () => {
+      server.use(errorHandlers.casesServerError)
+
+      await expect(apiClient.getCases()).rejects.toThrow(/failed to fetch cases/i)
+    })
+
+    it('throws ApiError on network error', async () => {
+      server.use(errorHandlers.casesNetworkError)
+
+      await expect(apiClient.getCases()).rejects.toThrow()
+    })
+  })
+
+  describe('runSegmentation', () => {
+    it('returns segmentation result', async () => {
+      const result = await apiClient.runSegmentation('sub-stroke0001')
+
+      expect(result.caseId).toBe('sub-stroke0001')
+      expect(result.diceScore).toBe(0.847)
+      expect(result.volumeMl).toBe(15.32)
+      expect(result.dwiUrl).toContain('dwi.nii.gz')
+      expect(result.predictionUrl).toContain('prediction.nii.gz')
+    })
+
+    it('sends fast_mode=false parameter (slower processing)', async () => {
+      const result = await apiClient.runSegmentation('sub-stroke0001', false)
+
+      // Mock returns 45.0s when fast_mode=false
+      expect(result.elapsedSeconds).toBe(45.0)
+    })
+
+    it('defaults fast_mode to true (faster processing)', async () => {
+      const result = await apiClient.runSegmentation('sub-stroke0001')
+
+      // Mock returns 12.5s when fast_mode=true (the default)
+      expect(result.elapsedSeconds).toBe(12.5)
+    })
+
+    it('throws ApiError on server error', async () => {
+      server.use(errorHandlers.segmentServerError)
+
+      await expect(
+        apiClient.runSegmentation('sub-stroke0001')
+      ).rejects.toThrow(/segmentation failed/i)
+    })
+  })
+})