fix(ui): use js_on_load for NiiVue viewer instead of script tags (#20)

* docs: add bug spec for NiiVue 3D viewer black screen (P2)

Document the NiiVue WebGL viewer rendering black on HF Spaces.
Core inference and 2D visualization work correctly.

Hypotheses:
1. Base64 data URL size (~65MB) exceeding limits
2. CDN accessibility issues
3. WebGL2 context limitations
4. Gradio HTML script execution

Proposed solutions ranked by complexity.
See: docs/specs/10-bug-niivue-viewer-black-screen.md

* docs: comprehensive root cause analysis for NiiVue black screen

ROOT CAUSE CONFIRMED: gr.HTML does not execute <script> tags.
Gradio intentionally ignores embedded JavaScript for security.

Key findings:
- js_on_load parameter is the correct Gradio 6 approach
- Base64 payload (~65MB) is a secondary concern
- Gradio 6 moved js/head params from Blocks() to launch()

Added 5 ranked solutions with code examples.
References: Gradio docs, HF forums, GitHub issues.

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

* docs: add external validation results to NiiVue bug spec

Agent claimed js_on_load doesn't exist - REFUTED by Gradio docs.
Parameter exists with default value, added in PR #12098.

Validated findings:
- js_on_load IS valid in Gradio 6.x gr.HTML
- Base64 payload concern is legitimate (use file URLs)
- CSP headers may need testing on HF Spaces

Added Step 0 to test async/await in js_on_load before implementing fix.

* fix(ui): use js_on_load for NiiVue viewer instead of script tags

ROOT CAUSE: Gradio's gr.HTML strips <script> tags for XSS security.
Our NiiVue initialization code was embedded in <script type="module">
tags, which Gradio ignored → black screen.

FIX: Use Gradio's js_on_load parameter instead:
- viewer.py: Removed script tags, added NIIVUE_JS_ON_LOAD constant
- HTML now uses data-* attributes for volume URLs
- JavaScript reads URLs from element.dataset
- components.py: Added js_on_load=NIIVUE_JS_ON_LOAD to gr.HTML
- Added test script for js_on_load validation

All 130 tests pass.

Fixes: #10 NiiVue 3D viewer black screen on HF Spaces
See: docs/specs/10-bug-niivue-viewer-black-screen.md

* fix: address CodeRabbit review feedback

- viewer.py: Use textContent instead of innerHTML to prevent XSS
- test_js_on_load.py: Add null coalescing for props.value
- docs: Add language identifier to code block

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

@@ -0,0 +1,408 @@
+# Bug #10: NiiVue 3D Viewer Renders Black Screen on HF Spaces
+
+## Status: FIXED (pending HF Spaces verification)
+
+**Date:** 2025-12-09
+**Branch:** `fix/niivue-js-on-load`
+**Discovered:** After fixing Bug #9 (DeepISLES subprocess bridge)
+
+### Fix Applied (2025-12-09)
+
+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.
+
+---
+
+## 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).

scripts/test_js_on_load.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python
+"""Test script to verify js_on_load + async + dynamic import works in Gradio.
+
+This tests the core mechanism needed to fix the NiiVue black screen bug.
+
+Run:
+    uv run python scripts/test_js_on_load.py
+
+Then open http://localhost:7860 and check if the tests pass.
+"""
+
+import gradio as gr
+
+# Test 1: Basic js_on_load execution
+TEST1_HTML = '<div id="test1" style="padding:20px;background:#333;color:#fff;margin:10px;border-radius:8px;">Test 1: Waiting...</div>'
+TEST1_JS = """
+    element.innerText = 'Test 1: PASS - js_on_load executed!';
+    element.style.background = '#228B22';
+"""
+
+# Test 2: Async IIFE pattern
+TEST2_HTML = '<div id="test2" style="padding:20px;background:#333;color:#fff;margin:10px;border-radius:8px;">Test 2: Waiting...</div>'
+TEST2_JS = """
+    (async () => {
+        element.innerText = 'Test 2: Async started...';
+        await new Promise(r => setTimeout(r, 500));
+        element.innerText = 'Test 2: PASS - Async/await works!';
+        element.style.background = '#228B22';
+    })();
+"""
+
+# Test 3: Dynamic import from CDN
+TEST3_HTML = '<div id="test3" style="padding:20px;background:#333;color:#fff;margin:10px;border-radius:8px;">Test 3: Waiting...</div>'
+TEST3_JS = """
+    (async () => {
+        element.innerText = 'Test 3: Loading NiiVue from CDN...';
+        try {
+            const mod = await import('https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js');
+            if (mod.Niivue) {
+                element.innerText = 'Test 3: PASS - NiiVue loaded! Niivue class available.';
+                element.style.background = '#228B22';
+            } else {
+                element.innerText = 'Test 3: PARTIAL - Module loaded but no Niivue class';
+                element.style.background = '#FFA500';
+            }
+        } catch(e) {
+            element.innerText = 'Test 3: FAIL - ' + e.message;
+            element.style.background = '#DC143C';
+        }
+    })();
+"""
+
+# Test 4: Canvas + WebGL2 check
+TEST4_HTML = """
+<div id="test4-container" style="padding:20px;background:#333;color:#fff;margin:10px;border-radius:8px;">
+    <div id="test4-status">Test 4: Waiting...</div>
+    <canvas id="test4-canvas" style="width:200px;height:100px;background:#000;margin-top:10px;"></canvas>
+</div>
+"""
+TEST4_JS = """
+    (async () => {
+        const status = element.querySelector('#test4-status');
+        const canvas = element.querySelector('#test4-canvas');
+
+        status.innerText = 'Test 4: Checking WebGL2...';
+
+        const gl = canvas.getContext('webgl2');
+        if (!gl) {
+            status.innerText = 'Test 4: FAIL - WebGL2 not supported';
+            element.style.background = '#DC143C';
+            return;
+        }
+
+        status.innerText = 'Test 4: Loading NiiVue...';
+        try {
+            const { Niivue } = await import('https://unpkg.com/@niivue/niivue@0.65.0/dist/index.js');
+            const nv = new Niivue({ logging: false, backColor: [0.2, 0.2, 0.3, 1] });
+            await nv.attachToCanvas(canvas);
+            nv.drawScene();
+
+            status.innerText = 'Test 4: PASS - NiiVue attached to canvas!';
+            status.style.color = '#90EE90';
+        } catch(e) {
+            status.innerText = 'Test 4: FAIL - ' + e.message;
+            element.style.background = '#DC143C';
+        }
+    })();
+"""
+
+# Test 5: Full integration with props.value
+TEST5_HTML = """
+<div id="test5-container" style="padding:20px;background:#333;color:#fff;margin:10px;border-radius:8px;">
+    <div id="test5-status">Test 5: Waiting...</div>
+    <div id="test5-value" style="font-family:monospace;font-size:12px;margin-top:10px;"></div>
+</div>
+"""
+TEST5_JS = """
+    const status = element.querySelector('#test5-status');
+    const valueDiv = element.querySelector('#test5-value');
+
+    // Check if we can access props
+    if (typeof props !== 'undefined') {
+        status.innerText = 'Test 5: PASS - props object accessible!';
+        status.style.color = '#90EE90';
+        valueDiv.innerText = 'props.value = ' + JSON.stringify(props.value ?? null).substring(0, 100) + '...';
+    } else {
+        status.innerText = 'Test 5: FAIL - props not defined';
+        element.style.background = '#DC143C';
+    }
+"""
+
+
+with gr.Blocks(title="js_on_load Test Suite") as demo:
+    gr.Markdown("""
+    # NiiVue js_on_load Test Suite
+
+    Testing if `js_on_load` supports the patterns we need for NiiVue:
+
+    1. **Basic execution** - Does js_on_load run at all?
+    2. **Async IIFE** - Does `(async () => { await ... })()` work?
+    3. **Dynamic import** - Can we `await import()` from CDN?
+    4. **Canvas + NiiVue** - Can we attach NiiVue to a canvas?
+    5. **Props access** - Can we read `props.value`?
+
+    All tests should show green "PASS" if our fix will work.
+    """)
+
+    with gr.Row():
+        with gr.Column():
+            gr.HTML(value=TEST1_HTML, js_on_load=TEST1_JS)
+            gr.HTML(value=TEST2_HTML, js_on_load=TEST2_JS)
+            gr.HTML(value=TEST3_HTML, js_on_load=TEST3_JS)
+
+        with gr.Column():
+            gr.HTML(value=TEST4_HTML, js_on_load=TEST4_JS)
+            gr.HTML(value=TEST5_HTML, js_on_load=TEST5_JS)
+
+    gr.Markdown("""
+    ---
+    **If all tests pass:** We can implement the `js_on_load` fix for NiiVue viewer.
+
+    **If tests fail:** We'll need alternative approaches (gradio-iframe or enhanced 2D).
+    """)
+
+
+if __name__ == "__main__":
+    print("Starting js_on_load test server...")
+    print("Open http://localhost:7860 to see test results")
+    demo.launch(server_port=7860)

src/stroke_deepisles_demo/ui/components.py

@@ -6,6 +6,7 @@ import gradio as gr
 
 from stroke_deepisles_demo.core.config import get_settings
 from stroke_deepisles_demo.core.logging import get_logger
+from stroke_deepisles_demo.ui.viewer import NIIVUE_JS_ON_LOAD
 
 logger = get_logger(__name__)
 
@@ -38,8 +39,14 @@ def create_results_display() -> dict[str, gr.components.Component]:
     """
     # Using gr.Group to group them visually
     with gr.Group():
-        # NiiVue visualization uses HTML
-        niivue_viewer = gr.HTML(label="Interactive 3D Viewer")
+        # NiiVue visualization uses HTML with js_on_load for JavaScript execution
+        # Note: Gradio strips <script> tags from HTML value for security,
+        # so we must use js_on_load to run our NiiVue initialization code.
+        # The HTML value contains data-* attributes with volume URLs.
+        niivue_viewer = gr.HTML(
+            label="Interactive 3D Viewer",
+            js_on_load=NIIVUE_JS_ON_LOAD,
+        )
 
         # Slice comparisons (Matplotlib)
         slice_plot = gr.Plot(label="Slice Comparison")

src/stroke_deepisles_demo/ui/viewer.py

@@ -281,11 +281,14 @@ def create_niivue_html(
     height: int = 400,
 ) -> str:
     """
-    Create HTML/JS for NiiVue viewer.
+    Create HTML for NiiVue viewer (static content only).
 
-    This function generates an HTML snippet with embedded JavaScript for
-    NiiVue WebGL-based neuroimaging visualization. Each invocation creates
-    a unique canvas ID to avoid conflicts when multiple viewers are rendered.
+    This function generates an HTML snippet with data attributes containing
+    volume URLs. The actual NiiVue initialization is handled by js_on_load
+    in the gr.HTML component (see NIIVUE_JS_ON_LOAD).
+
+    IMPORTANT: Gradio's gr.HTML strips <script> tags for security.
+    JavaScript must be passed via the js_on_load parameter instead.
 
     Args:
         volume_url: Data URL or URL to volume NIfTI file
@@ -293,93 +296,117 @@ def create_niivue_html(
         height: Viewer height in pixels
 
     Returns:
-        HTML string with embedded NiiVue viewer
+        HTML string with data attributes for NiiVue viewer
 
     Note:
-        The JavaScript uses dynamic import() which works in modern browsers
-        and Gradio's HTML component. Each viewer gets a unique ID to support
-        multiple simultaneous viewers.
+        The volume URLs are stored in data-* attributes and read by
+        the js_on_load JavaScript code. This pattern works because
+        js_on_load has access to the 'element' variable.
     """
     # Generate unique ID for this viewer instance
     viewer_id = uuid.uuid4().hex[:8]
-    canvas_id = f"niivue-canvas-{viewer_id}"
-    container_id = f"niivue-container-{viewer_id}"
-
-    # Safely serialize URLs for JavaScript (prevents XSS)
-    volume_url_js = json.dumps(volume_url)
-
-    # Build mask volume configuration if provided
-    mask_js = ""
-    if mask_url:
-        mask_url_js = json.dumps(mask_url)
-        mask_js = f"""
-                volumes.push({{
-                    url: {mask_url_js},
-                    colorMap: 'red',
-                    opacity: 0.5
-                }});"""
-
-    # JavaScript that initializes NiiVue
-    # Using an IIFE pattern that works better in Gradio's HTML component
-    return f"""
-    <div id="{container_id}" style="width:100%; height:{height}px; background:#000; border-radius:8px; position:relative;">
-        <canvas id="{canvas_id}" style="width:100%; height:100%;"></canvas>
+
+    # Safely encode URLs for HTML data attributes
+    # Using json.dumps ensures proper escaping
+    volume_attr = f"data-volume-url={json.dumps(volume_url)}"
+    mask_attr = f"data-mask-url={json.dumps(mask_url)}" if mask_url else 'data-mask-url=""'
+
+    return f"""<div
+    id="niivue-container-{viewer_id}"
+    class="niivue-viewer"
+    {volume_attr}
+    {mask_attr}
+    style="width:100%; height:{height}px; background:#000; border-radius:8px; position:relative;"
+>
+    <canvas style="width:100%; height:100%;"></canvas>
+    <div class="niivue-status" style="position:absolute;top:50%;left:50%;transform:translate(-50%,-50%);color:#666;">
+        Loading viewer...
     </div>
-    <script type="module">
-        // NiiVue initialization for viewer {viewer_id}
-        (async function() {{
-            try {{
-                // Check if browser supports WebGL2
-                const testCanvas = document.createElement('canvas');
-                const gl = testCanvas.getContext('webgl2');
-                if (!gl) {{
-                    document.getElementById('{container_id}').innerHTML =
-                        '<div style="color:#fff;padding:20px;text-align:center;">' +
-                        'WebGL2 not supported. Please use a modern browser.</div>';
-                    return;
-                }}
-
-                // Dynamically import NiiVue
-                const niivueModule = await import('{NIIVUE_CDN_URL}');
-                const Niivue = niivueModule.Niivue;
-
-                // Initialize NiiVue with options
-                const nv = new Niivue({{
-                    logging: false,
-                    show3Dcrosshair: true,
-                    textHeight: 0.04,
-                    backColor: [0, 0, 0, 1],
-                    crosshairColor: [0.2, 0.8, 0.2, 1]
-                }});
-
-                // Attach to canvas
-                await nv.attachToCanvas(document.getElementById('{canvas_id}'));
-
-                // Prepare volumes
-                const volumes = [{{
-                    url: {volume_url_js},
-                    name: 'input.nii.gz'
-                }}];{mask_js}
-
-                // Load volumes
-                await nv.loadVolumes(volumes);
-
-                // Configure view: multiplanar + 3D
-                nv.setSliceType(nv.sliceTypeMultiplanar);
-                if (typeof nv.setMultiplanarLayout === 'function') {{
-                    nv.setMultiplanarLayout(2);
-                }}
-                nv.opts.show3Dcrosshair = true;
-                nv.setRenderAzimuthElevation(120, 10);
-                nv.drawScene();
-
-                console.log('NiiVue viewer {viewer_id} initialized successfully');
-            }} catch (error) {{
-                console.error('NiiVue initialization error:', error);
-                document.getElementById('{container_id}').innerHTML =
-                    '<div style="color:#fff;padding:20px;text-align:center;">' +
-                    'Error loading viewer: ' + error.message + '</div>';
-            }}
-        }})();
-    </script>
-    """
+</div>"""
+
+
+# JavaScript code for js_on_load parameter
+# This runs when the gr.HTML component loads/updates
+# Variables available: element, props, trigger
+NIIVUE_JS_ON_LOAD = f"""
+(async () => {{
+    const container = element.querySelector('.niivue-viewer') || element;
+    const canvas = element.querySelector('canvas');
+    const status = element.querySelector('.niivue-status');
+
+    // Get URLs from data attributes
+    const volumeUrl = container.dataset.volumeUrl;
+    const maskUrl = container.dataset.maskUrl;
+
+    // Skip if no volume URL (initial empty state)
+    if (!volumeUrl) {{
+        if (status) status.innerText = 'Waiting for segmentation...';
+        return;
+    }}
+
+    try {{
+        if (status) status.innerText = 'Checking WebGL2...';
+
+        // Check WebGL2 support
+        const gl = canvas.getContext('webgl2');
+        if (!gl) {{
+            container.innerHTML = '<div style="color:#fff;padding:20px;text-align:center;">WebGL2 not supported. Please use a modern browser.</div>';
+            return;
+        }}
+
+        if (status) status.innerText = 'Loading NiiVue...';
+
+        // Dynamically import NiiVue from CDN
+        const {{ Niivue }} = await import('{NIIVUE_CDN_URL}');
+
+        // Initialize NiiVue
+        const nv = new Niivue({{
+            logging: false,
+            show3Dcrosshair: true,
+            textHeight: 0.04,
+            backColor: [0, 0, 0, 1],
+            crosshairColor: [0.2, 0.8, 0.2, 1]
+        }});
+
+        // Attach to canvas
+        await nv.attachToCanvas(canvas);
+
+        // Hide status message
+        if (status) status.style.display = 'none';
+
+        // Prepare volumes
+        const volumes = [{{ url: volumeUrl, name: 'input.nii.gz' }}];
+
+        if (maskUrl) {{
+            volumes.push({{
+                url: maskUrl,
+                colorMap: 'red',
+                opacity: 0.5
+            }});
+        }}
+
+        // Load volumes
+        await nv.loadVolumes(volumes);
+
+        // Configure view: multiplanar + 3D
+        nv.setSliceType(nv.sliceTypeMultiplanar);
+        if (typeof nv.setMultiplanarLayout === 'function') {{
+            nv.setMultiplanarLayout(2);
+        }}
+        nv.opts.show3Dcrosshair = true;
+        nv.setRenderAzimuthElevation(120, 10);
+        nv.drawScene();
+
+        console.log('NiiVue viewer initialized successfully');
+
+    }} catch (error) {{
+        console.error('NiiVue initialization error:', error);
+        // Use textContent instead of innerHTML to prevent XSS
+        const errorDiv = document.createElement('div');
+        errorDiv.style.cssText = 'color:#f66;padding:20px;text-align:center;';
+        errorDiv.textContent = 'Error loading viewer: ' + error.message;
+        container.innerHTML = '';
+        container.appendChild(errorDiv);
+    }}
+}})();
+"""