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

.env.example

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

.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

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...
+    },
+  },
+])
+```

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()
+  })
+})

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 }

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()
+  })
+})

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()
+  }
+}

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()
+  })
+})

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 },
+    },
+  },
+])

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>

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"
+  }
+}

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,
+  },
+})

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()
+      })
+    })
+  })
+})

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>
+  )
+}

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)
+    })
+  })
+})

src/api/client.ts

@@ -0,0 +1,84 @@
+import type { CasesResponse, SegmentResponse } from '../types'
+
+function getApiBase(): string {
+  const url = import.meta.env.VITE_API_URL
+
+  // In production, VITE_API_URL must be set - fail fast with clear error
+  if (import.meta.env.PROD && !url) {
+    throw new Error(
+      'VITE_API_URL environment variable is required in production. ' +
+        'Set it to the backend API URL (e.g., https://your-app.hf.space).'
+    )
+  }
+
+  // In development, fall back to localhost
+  return url || 'http://localhost:7860'
+}
+
+const API_BASE = getApiBase()
+
+export class ApiError extends Error {
+  status: number
+  detail?: string
+
+  constructor(message: string, status: number, detail?: string) {
+    super(message)
+    this.name = 'ApiError'
+    this.status = status
+    this.detail = detail
+  }
+}
+
+class ApiClient {
+  private baseUrl: string
+
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl
+  }
+
+  async getCases(signal?: AbortSignal): Promise<CasesResponse> {
+    const response = await fetch(`${this.baseUrl}/api/cases`, { signal })
+
+    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,
+    signal?: AbortSignal
+  ): 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,
+      }),
+      signal,
+    })
+
+    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)

src/api/index.ts

@@ -0,0 +1 @@
+export { apiClient, ApiError } from './client'

src/components/CaseSelector.tsx

@@ -0,0 +1,73 @@
+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 abortController = new AbortController()
+
+    const fetchCases = async () => {
+      try {
+        const data = await apiClient.getCases(abortController.signal)
+        setCases(data.cases)
+      } catch (err) {
+        // Ignore abort errors - component unmounted
+        if (err instanceof Error && err.name === 'AbortError') return
+
+        const message = err instanceof Error ? err.message : 'Unknown error'
+        setError(`Failed to load cases: ${message}`)
+      } finally {
+        if (!abortController.signal.aborted) {
+          setIsLoading(false)
+        }
+      }
+    }
+
+    fetchCases()
+
+    return () => abortController.abort()
+  }, [])
+
+  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>
+  )
+}

src/components/Layout.tsx

@@ -0,0 +1,21 @@
+import type { 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/MetricsPanel.tsx

@@ -0,0 +1,45 @@
+import type { Metrics } from '../types'
+
+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/components/NiiVueViewer.tsx

@@ -0,0 +1,108 @@
+import { useRef, useEffect, useState } from 'react'
+import { Niivue } from '@niivue/niivue'
+
+interface NiiVueViewerProps {
+  backgroundUrl: string
+  overlayUrl?: string
+  onError?: (error: string) => void
+}
+
+export function NiiVueViewer({ backgroundUrl, overlayUrl, onError }: NiiVueViewerProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const nvRef = useRef<Niivue | null>(null)
+  const onErrorRef = useRef(onError)
+  const [loadError, setLoadError] = useState<string | null>(null)
+
+  // Keep onError ref current without triggering effect re-runs
+  useEffect(() => {
+    onErrorRef.current = onError
+  })
+
+  // Effect 1: Mount/unmount - instantiate and cleanup NiiVue ONCE
+  useEffect(() => {
+    if (!canvasRef.current) return
+
+    const 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
+
+    // Cleanup on unmount ONLY - CRITICAL: Release WebGL context
+    // Browsers limit WebGL contexts (~16 in Chrome). Without cleanup,
+    // navigating between cases will exhaust contexts and break the viewer.
+    return () => {
+      // Capture gl BEFORE cleanup (cleanup may null internal state)
+      const gl = nv.gl
+      try {
+        // NiiVue's cleanup() releases event listeners and observers
+        // See: https://niivue.github.io/niivue/devdocs/classes/Niivue.html#cleanup
+        nv.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
+    }
+  }, [])
+
+  // Effect 2: URL changes - reload volumes on existing NiiVue instance
+  // Uses isCurrent flag to ignore stale loads when URLs change rapidly
+  useEffect(() => {
+    const nv = nvRef.current
+    if (!nv) return
+
+    let isCurrent = true
+
+    // Clear previous error before new load (valid pattern for async operations)
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setLoadError(null)
+
+    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 with error handling - ignore stale results
+    nv.loadVolumes(volumes).catch((err: unknown) => {
+      if (!isCurrent) return // Ignore errors from stale loads
+      const message = err instanceof Error ? err.message : 'Failed to load volume'
+      setLoadError(message)
+      onErrorRef.current?.(message)
+    })
+
+    // Cleanup: mark this effect instance as stale
+    return () => {
+      isCurrent = false
+    }
+  }, [backgroundUrl, overlayUrl])
+
+  return (
+    <div className="bg-gray-900 rounded-lg p-2">
+      <canvas ref={canvasRef} className="w-full h-[500px] rounded" />
+      {loadError && (
+        <div className="mt-2 p-2 bg-red-900/50 rounded text-red-300 text-sm">
+          Failed to load volume: {loadError}
+        </div>
+      )}
+      <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/__tests__/CaseSelector.test.tsx

@@ -0,0 +1,112 @@
+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')
+  })
+})

src/components/__tests__/Layout.test.tsx

@@ -0,0 +1,43 @@
+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')
+  })
+})

src/components/__tests__/MetricsPanel.test.tsx

@@ -0,0 +1,67 @@
+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')
+  })
+})

src/components/__tests__/NiiVueViewer.test.tsx

@@ -0,0 +1,160 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { NiiVueViewer } from '../NiiVueViewer'
+
+// Store mock function references so tests can verify calls
+const mockLoadVolumes = vi.fn().mockResolvedValue(undefined)
+const mockCleanup = vi.fn()
+const mockAttachToCanvas = vi.fn()
+const mockLoseContext = vi.fn()
+
+// Mock the NiiVue module since it requires actual WebGL
+vi.mock('@niivue/niivue', () => ({
+  Niivue: class MockNiivue {
+    attachToCanvas = mockAttachToCanvas
+    loadVolumes = mockLoadVolumes
+    setSliceType = vi.fn()
+    cleanup = mockCleanup
+    gl = {
+      getExtension: vi.fn(() => ({ loseContext: mockLoseContext })),
+    }
+    opts = {}
+  },
+}))
+
+describe('NiiVueViewer', () => {
+  const defaultProps = {
+    backgroundUrl: 'http://localhost:7860/files/dwi.nii.gz',
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  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('attaches NiiVue to canvas on mount', () => {
+    render(<NiiVueViewer {...defaultProps} />)
+
+    expect(mockAttachToCanvas).toHaveBeenCalled()
+    // Verify it was called with a canvas element
+    const arg = mockAttachToCanvas.mock.calls[0][0]
+    expect(arg).toBeInstanceOf(HTMLCanvasElement)
+  })
+
+  it('loads background volume on mount', () => {
+    render(<NiiVueViewer {...defaultProps} />)
+
+    expect(mockLoadVolumes).toHaveBeenCalledWith([
+      { url: defaultProps.backgroundUrl, colormap: 'gray', opacity: 1 },
+    ])
+  })
+
+  it('loads both background and overlay when overlayUrl provided', () => {
+    const overlayUrl = 'http://localhost:7860/files/prediction.nii.gz'
+
+    render(
+      <NiiVueViewer
+        {...defaultProps}
+        overlayUrl={overlayUrl}
+      />
+    )
+
+    expect(mockLoadVolumes).toHaveBeenCalledWith([
+      { url: defaultProps.backgroundUrl, colormap: 'gray', opacity: 1 },
+      { url: overlayUrl, colormap: 'red', opacity: 0.5 },
+    ])
+  })
+
+  it('calls cleanup on unmount', () => {
+    const { unmount } = render(<NiiVueViewer {...defaultProps} />)
+
+    unmount()
+
+    expect(mockCleanup).toHaveBeenCalled()
+    expect(mockLoseContext).toHaveBeenCalled()
+  })
+
+  it('sets canvas dimensions', () => {
+    render(<NiiVueViewer {...defaultProps} />)
+
+    const canvas = document.querySelector('canvas')
+    expect(canvas).toHaveClass('w-full', 'h-[500px]')
+  })
+
+  it('displays error when volume loading fails', async () => {
+    const errorMessage = 'Network error loading volume'
+    mockLoadVolumes.mockRejectedValueOnce(new Error(errorMessage))
+
+    render(<NiiVueViewer {...defaultProps} />)
+
+    // Wait for error to be displayed
+    const errorElement = await screen.findByText(/failed to load volume/i)
+    expect(errorElement).toBeInTheDocument()
+    expect(errorElement).toHaveTextContent(errorMessage)
+  })
+
+  it('calls onError callback when volume loading fails', async () => {
+    const errorMessage = 'Network error'
+    const onError = vi.fn()
+    mockLoadVolumes.mockRejectedValueOnce(new Error(errorMessage))
+
+    render(<NiiVueViewer {...defaultProps} onError={onError} />)
+
+    // Wait for error callback to be invoked
+    await vi.waitFor(() => {
+      expect(onError).toHaveBeenCalledWith(errorMessage)
+    })
+  })
+
+  it('ignores errors from stale loads after URL change', async () => {
+    const onError = vi.fn()
+    // First load succeeds, second load fails slowly
+    let rejectSecondLoad: (error: Error) => void
+    mockLoadVolumes
+      .mockResolvedValueOnce(undefined)
+      .mockImplementationOnce(() => new Promise((_, reject) => {
+        rejectSecondLoad = reject
+      }))
+
+    const { rerender } = render(
+      <NiiVueViewer backgroundUrl="http://localhost/first.nii.gz" onError={onError} />
+    )
+
+    // Change URL - starts second load
+    rerender(
+      <NiiVueViewer backgroundUrl="http://localhost/second.nii.gz" onError={onError} />
+    )
+
+    // Change URL again - makes second load stale
+    rerender(
+      <NiiVueViewer backgroundUrl="http://localhost/third.nii.gz" onError={onError} />
+    )
+
+    // Now reject the second load (stale)
+    rejectSecondLoad!(new Error('Stale load error'))
+
+    // Wait a tick and verify onError was NOT called with stale error
+    await vi.waitFor(() => {
+      expect(onError).not.toHaveBeenCalledWith('Stale load error')
+    })
+  })
+})

src/components/index.ts

@@ -0,0 +1,4 @@
+export { Layout } from './Layout'
+export { MetricsPanel } from './MetricsPanel'
+export { CaseSelector } from './CaseSelector'
+export { NiiVueViewer } from './NiiVueViewer'

src/hooks/__tests__/useSegmentation.test.tsx

@@ -0,0 +1,96 @@
+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)
+  })
+})

src/hooks/index.ts

@@ -0,0 +1 @@
+export { useSegmentation } from './useSegmentation'

src/hooks/useSegmentation.ts

@@ -0,0 +1,63 @@
+import { useState, useCallback, useRef } 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)
+
+  // Track the current request to prevent race conditions
+  // Each new request gets a unique token; only the latest request's results are applied
+  const currentRequestRef = useRef<number>(0)
+  const abortControllerRef = useRef<AbortController | null>(null)
+
+  const runSegmentation = useCallback(async (caseId: string, fastMode = true) => {
+    // Cancel any in-flight request
+    abortControllerRef.current?.abort()
+    const abortController = new AbortController()
+    abortControllerRef.current = abortController
+
+    // Increment request token to track this request
+    const requestToken = ++currentRequestRef.current
+
+    setIsLoading(true)
+    setError(null)
+
+    try {
+      const data = await apiClient.runSegmentation(caseId, fastMode, abortController.signal)
+
+      // Only apply results if this is still the current request
+      // Prevents stale responses from overwriting newer results
+      if (requestToken !== currentRequestRef.current) return
+
+      setResult({
+        dwiUrl: data.dwiUrl,
+        predictionUrl: data.predictionUrl,
+        metrics: {
+          caseId: data.caseId,
+          diceScore: data.diceScore,
+          volumeMl: data.volumeMl,
+          elapsedSeconds: data.elapsedSeconds,
+        },
+      })
+    } catch (err) {
+      // Ignore abort errors - user intentionally cancelled
+      if (err instanceof Error && err.name === 'AbortError') return
+
+      // Only apply error if this is still the current request
+      if (requestToken !== currentRequestRef.current) return
+
+      const message = err instanceof Error ? err.message : 'Unknown error'
+      setError(message)
+      setResult(null)
+    } finally {
+      // Only clear loading if this is still the current request
+      if (requestToken === currentRequestRef.current) {
+        setIsLoading(false)
+      }
+    }
+  }, [])
+
+  return { result, isLoading, error, runSegmentation }
+}

src/index.css

@@ -0,0 +1 @@
+@import "tailwindcss";

src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

src/mocks/handlers.ts

@@ -0,0 +1,52 @@
+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 })
+  }),
+}

src/mocks/server.ts

@@ -0,0 +1,4 @@
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)

src/test/fixtures.ts

@@ -0,0 +1,22 @@
+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,
+  },
+}

src/test/setup.ts

@@ -0,0 +1,151 @@
+import '@testing-library/jest-dom/vitest'
+import { cleanup } from '@testing-library/react'
+import { afterEach, beforeAll, afterAll, vi } 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() {}
+}
+
+// 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),
+}
+
+// Override getContext to return WebGL mock - uses type assertion for test mocking
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+;(HTMLCanvasElement.prototype as any).getContext = function (
+  contextType: string
+): RenderingContext | null {
+  if (contextType === 'webgl2' || contextType === 'webgl') {
+    return {
+      ...mockWebGL2Context,
+      canvas: this,
+    } as unknown as WebGL2RenderingContext
+  }
+  return null
+}

src/types/index.ts

@@ -0,0 +1,25 @@
+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
+}

tsconfig.app.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"],
+  "exclude": ["src/test", "src/mocks", "src/**/*.test.tsx", "src/**/*.test.ts"]
+}

tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" },
+    { "path": "./tsconfig.test.json" }
+  ]
+}

tsconfig.node.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts", "vitest.config.ts"]
+}

tsconfig.test.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.test.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client", "vitest/globals", "@testing-library/jest-dom", "node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src/test", "src/mocks", "src/**/*.test.tsx", "src/**/*.test.ts"]
+}

vite.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  build: {
+    outDir: 'dist',
+  },
+})

vitest.config.ts

@@ -0,0 +1,33 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import viteConfig from './vite.config'
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    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',
+          'src/vite-env.d.ts',
+        ],
+        thresholds: {
+          statements: 80,
+          branches: 75,
+          functions: 80,
+          lines: 80,
+        },
+      },
+    },
+  })
+)