fix(ui): use head_paths for NiiVue loading on HF Spaces (#24) (#25)

* chore: DIAGNOSTIC - disable js_on_load to test HF Spaces loading

* fix(ui): use head_paths for NiiVue loading on HF Spaces (#24)

Root cause: gr.HTML(js_on_load=...) with dynamic ES module import()
breaks Gradio frontend initialization on HuggingFace Spaces, causing
the app to hang on "Loading..." indefinitely.

Fix: Use the official Gradio-recommended head_paths approach:
1. Generate niivue-loader.html at runtime with correct absolute path
2. Load via demo.launch(head_paths=[...]) instead of head=
3. NiiVue exposed globally as window.Niivue
4. js_on_load and event handlers access window.Niivue (no import())

This follows the solution recommended by Gradio maintainers in
GitHub issue #11649 for loading custom JavaScript reliably.

Files changed:
- viewer.py: Add get_niivue_loader_path(), convert JS to regular strings
- app.py: Use head_paths instead of head parameter
- ui/app.py: Use head_paths, re-enable NIIVUE_UPDATE_JS handler
- components.py: Re-enable js_on_load=NIIVUE_ON_LOAD_JS
- assets/niivue-loader.html: Auto-generated loader (gitignored runtime)

All 136 tests pass. Lint and type checks clean.

* fix: gitignore niivue-loader.html (generated at runtime with env-specific path)

* fix: add logging and error handling to get_niivue_loader_path (CodeRabbit)

.gitignore

@@ -215,3 +215,5 @@ data/scratch/
 
 # macOS
 .DS_Store
+# Auto-generated at runtime (path is environment-specific)
+src/stroke_deepisles_demo/ui/assets/niivue-loader.html

app.py

@@ -16,6 +16,7 @@ import gradio as gr
 from stroke_deepisles_demo.core.config import get_settings
 from stroke_deepisles_demo.core.logging import setup_logging
 from stroke_deepisles_demo.ui.app import get_demo
+from stroke_deepisles_demo.ui.viewer import get_niivue_loader_path
 
 # Initialize logging
 settings = get_settings()
@@ -35,6 +36,9 @@ if __name__ == "__main__":
     # Assets are located in src/stroke_deepisles_demo/ui/assets
     assets_dir = Path(__file__).parent / "src" / "stroke_deepisles_demo" / "ui" / "assets"
 
+    # Generate the NiiVue loader HTML file (creates if needed)
+    niivue_loader = get_niivue_loader_path()
+
     demo.launch(
         server_name=settings.gradio_server_name,
         server_port=settings.gradio_server_port,
@@ -42,4 +46,5 @@ if __name__ == "__main__":
         theme=gr.themes.Soft(),
         css="footer {visibility: hidden}",
         allowed_paths=[str(assets_dir)],
+        head_paths=[str(niivue_loader)],  # Official Gradio approach (Issue #11649)
     )

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

@@ -203,3 +203,52 @@ This caused the Gradio frontend to remain stuck on "Loading..." even though the
 3. **Security-compliant:** Respects HF Spaces CSP policy
 4. **Reproducible:** Same NiiVue version always loaded
 5. **Standard practice:** Vendoring is the recommended approach for HF Spaces
+
+---
+
+## Update: Vendoring Alone Did Not Fix It (2025-12-09)
+
+### New Finding
+
+Vendoring NiiVue locally bypassed CSP but **the app still wouldn't load**.
+
+**Diagnostic test:** Disabled `js_on_load` parameter entirely.
+
+**Result:** App loads perfectly! Everything works EXCEPT Interactive 3D viewer.
+
+### Real Root Cause
+
+**`gr.HTML(js_on_load=...)` with dynamic ES module `import()` blocks Gradio frontend initialization on HF Spaces.**
+
+The issue is NOT the vendored file location - it's HOW we load the JavaScript:
+
+```javascript
+// This approach BREAKS the entire Gradio app on HF Spaces:
+const { Niivue } = await import('/gradio_api/file=...');
+```
+
+When this fails (silently), it prevents the Gradio frontend from completing initialization, causing the eternal "Loading..." screen.
+
+### Evidence
+
+With `js_on_load` disabled:
+- ✅ Gradio app loads
+- ✅ Case selector works
+- ✅ DeepISLES segmentation runs (38.66s)
+- ✅ Static Report (Matplotlib) renders correctly
+- ✅ Metrics JSON displays
+- ✅ Download works
+- ❌ Interactive 3D shows "Loading viewer..." (expected - JS disabled)
+
+### Correct Approach
+
+Use `gr.Blocks(head=...)` to load NiiVue as a `<script>` tag instead of dynamic `import()`:
+
+```python
+with gr.Blocks(
+    head='<script src="/gradio_api/file=.../niivue.js"></script>'
+) as demo:
+    ...
+```
+
+Or use the global `js` parameter on `gr.Blocks` to define initialization code that runs after the script loads.

src/stroke_deepisles_demo/ui/app.py

@@ -21,6 +21,7 @@ from stroke_deepisles_demo.ui.components import (
 from stroke_deepisles_demo.ui.viewer import (
     NIIVUE_UPDATE_JS,
     create_niivue_html,
+    get_niivue_loader_path,
     nifti_to_gradio_url,
     render_3panel_view,
     render_slice_comparison,
@@ -245,7 +246,7 @@ def create_app() -> gr.Blocks:
                 previous_results_state,  # Update state with new results_dir
             ],
         ).then(
-            fn=None,  # Explicitly None to run JS only
+            fn=None,  # JS-only handler to re-initialize NiiVue after HTML update
             js=NIIVUE_UPDATE_JS,
         )
 
@@ -277,6 +278,9 @@ if __name__ == "__main__":
     # Allow access to local assets (e.g., niivue.js)
     assets_dir = Path(__file__).parent / "assets"
 
+    # Generate the NiiVue loader HTML file (creates if needed)
+    niivue_loader = get_niivue_loader_path()
+
     get_demo().launch(
         server_name=settings.gradio_server_name,
         server_port=settings.gradio_server_port,
@@ -285,4 +289,5 @@ if __name__ == "__main__":
         css="footer {visibility: hidden}",
         show_error=True,  # Show full Python tracebacks in UI for debugging
         allowed_paths=[str(assets_dir)],
+        head_paths=[str(niivue_loader)],  # Official Gradio approach (Issue #11649)
     )

src/stroke_deepisles_demo/ui/components.py

@@ -41,10 +41,9 @@ def create_results_display() -> dict[str, gr.components.Component]:
     with gr.Group():
         with gr.Tabs():
             with gr.Tab("Interactive 3D"):
-                # 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 3D viewer - uses js_on_load to initialize after HTML renders
+                # The NiiVue library is loaded globally via head_paths (see app.py)
+                # This handler accesses window.Niivue set by the loader script
                 niivue_viewer = gr.HTML(
                     label="Interactive 3D Viewer",
                     js_on_load=NIIVUE_ON_LOAD_JS,

src/stroke_deepisles_demo/ui/viewer.py

@@ -19,8 +19,11 @@ from pathlib import Path
 import numpy as np
 from matplotlib.figure import Figure
 
+from stroke_deepisles_demo.core.logging import get_logger
 from stroke_deepisles_demo.metrics import load_nifti_as_array
 
+logger = get_logger(__name__)
+
 # NiiVue version - updated to latest stable (Dec 2025)
 # Switched to local vendoring to avoid CSP issues on HuggingFace Spaces (Issue #24)
 # The file is located in src/stroke_deepisles_demo/ui/assets/niivue.js
@@ -33,6 +36,79 @@ _NIIVUE_JS_PATH = _ASSET_DIR / "niivue.js"
 NIIVUE_JS_URL = f"/gradio_api/file={_NIIVUE_JS_PATH.resolve()}"
 
 
+def get_niivue_loader_path() -> Path:
+    """
+    Get path to the NiiVue loader HTML file, creating it if needed.
+
+    This function generates an HTML file that loads NiiVue as a global.
+    Using head_paths with a file is the official Gradio-recommended approach
+    for loading custom JavaScript (see GitHub issue #11649).
+
+    The HTML file is generated at runtime because the niivue.js path
+    is dynamic (depends on installation location).
+
+    Returns:
+        Path to the niivue-loader.html file
+
+    Note:
+        The returned path must be included in allowed_paths during launch().
+    """
+    loader_path = _ASSET_DIR / "niivue-loader.html"
+
+    # Generate the loader HTML with the correct absolute path
+    loader_content = f"""<!--
+    NiiVue Loader for Gradio (auto-generated)
+    Loads NiiVue library and exposes it globally for js_on_load handlers.
+    See: docs/specs/24-bug-hf-spaces-loading-forever.md
+-->
+<script type="module">
+    import {{ Niivue }} from '{NIIVUE_JS_URL}';
+    window.Niivue = Niivue;
+    console.log('[NiiVue Loader] Loaded globally:', typeof window.Niivue);
+</script>
+"""
+
+    # Write/update the loader file (idempotent)
+    # This ensures the path is always correct for the current installation
+    try:
+        # Check if file exists and has correct content
+        if loader_path.exists():
+            existing_content = loader_path.read_text()
+            if existing_content == loader_content:
+                return loader_path
+
+        loader_path.write_text(loader_content)
+        logger.debug("Generated NiiVue loader at %s", loader_path)
+    except OSError as e:
+        # If we can't write (e.g., read-only filesystem), the file should
+        # already exist from the build process
+        logger.warning("Could not write loader file at %s: %s", loader_path, e)
+        if not loader_path.exists():
+            raise RuntimeError(
+                f"NiiVue loader file not found and cannot be created: {loader_path}"
+            ) from e
+
+    return loader_path
+
+
+# Legacy function for backward compatibility
+def get_niivue_head_script() -> str:
+    """
+    Get HTML script tag for loading NiiVue in Gradio's head.
+
+    DEPRECATED: Use get_niivue_loader_path() with head_paths instead.
+    This function is kept for backward compatibility only.
+
+    Returns:
+        HTML string with script tag
+    """
+    return f"""<script type="module">
+    import {{ Niivue }} from '{NIIVUE_JS_URL}';
+    window.Niivue = Niivue;
+    console.log('NiiVue loaded globally:', typeof window.Niivue);
+</script>"""
+
+
 def nifti_to_gradio_url(nifti_path: Path) -> str:
     """
     Get Gradio file URL for a NIfTI file.
@@ -358,8 +434,12 @@ def create_niivue_html(
 # JavaScript code for js_on_load parameter
 # This runs when the gr.HTML component FIRST loads (mounts)
 # Variables available: element, props, trigger
-NIIVUE_ON_LOAD_JS = f"""
-(async () => {{
+#
+# IMPORTANT: This code uses window.Niivue which must be loaded via
+# gr.Blocks(head=get_niivue_head_script()). Do NOT use dynamic import()
+# as it breaks Gradio on HF Spaces.
+NIIVUE_ON_LOAD_JS = """
+(async () => {
     const container = element.querySelector('.niivue-viewer') || element;
     const canvas = element.querySelector('canvas');
     const status = element.querySelector('.niivue-status');
@@ -369,34 +449,38 @@ NIIVUE_ON_LOAD_JS = f"""
     const maskUrl = container.dataset.maskUrl;
 
     // Skip if no volume URL (initial empty state)
-    if (!volumeUrl) {{
+    if (!volumeUrl) {
         if (status) status.innerText = 'Waiting for segmentation...';
         return;
-    }}
+    }
 
-    try {{
+    try {
         if (status) status.innerText = 'Checking WebGL2...';
 
         // Check WebGL2 support
         const gl = canvas.getContext('webgl2');
-        if (!gl) {{
+        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 local asset (vendored)
-        const {{ Niivue }} = await import('{NIIVUE_JS_URL}');
+        // Use globally loaded NiiVue (from head script)
+        // Do NOT use dynamic import() - it breaks Gradio on HF Spaces
+        const Niivue = window.Niivue;
+        if (!Niivue) {
+            throw new Error('NiiVue not loaded. Ensure head script is included via gr.Blocks(head=...)');
+        }
 
         // Initialize NiiVue
-        const nv = new 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);
@@ -405,31 +489,31 @@ NIIVUE_ON_LOAD_JS = f"""
         if (status) status.style.display = 'none';
 
         // Prepare volumes
-        const volumes = [{{ url: volumeUrl, name: 'input.nii.gz' }}];
+        const volumes = [{ url: volumeUrl, name: 'input.nii.gz' }];
 
-        if (maskUrl) {{
-            volumes.push({{
+        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') {{
+        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) {{
+    } catch (error) {
         console.error('NiiVue initialization error:', error);
         // Use textContent instead of innerHTML to prevent XSS
         const errorDiv = document.createElement('div');
@@ -437,22 +521,26 @@ NIIVUE_ON_LOAD_JS = f"""
         errorDiv.textContent = 'Error loading viewer: ' + error.message;
         container.innerHTML = '';
         container.appendChild(errorDiv);
-    }}
-}})();
+    }
+})();
 """
 
 # JavaScript code for event handlers (e.g. .then(js=...))
 # This runs after Python updates the HTML value.
 # ⚠️ CRITICAL: 'element' is NOT available here! Must use document.querySelector
-NIIVUE_UPDATE_JS = f"""
-(async () => {{
+#
+# IMPORTANT: This code uses window.Niivue which must be loaded via
+# head_paths with niivue-loader.html. Do NOT use dynamic import()
+# as it breaks Gradio on HF Spaces.
+NIIVUE_UPDATE_JS = """
+(async () => {
     // We must find the container globally since 'element' is not available in event handlers
     const container = document.querySelector('.niivue-viewer');
 
-    if (!container) {{
+    if (!container) {
         console.error('NiiVue container not found');
         return;
-    }}
+    }
 
     const canvas = container.querySelector('canvas');
     const status = container.querySelector('.niivue-status');
@@ -462,31 +550,35 @@ NIIVUE_UPDATE_JS = f"""
     const maskUrl = container.dataset.maskUrl;
 
     // Skip if no volume URL
-    if (!volumeUrl) {{
+    if (!volumeUrl) {
         return;
-    }}
+    }
 
-    try {{
+    try {
         if (status) status.innerText = 'Reloading NiiVue...';
 
         // Check WebGL2 support
         const gl = canvas.getContext('webgl2');
-        if (!gl) {{
+        if (!gl) {
             container.innerHTML = '<div style="color:#fff;padding:20px;text-align:center;">WebGL2 not supported. Please use a modern browser.</div>';
             return;
-        }}
+        }
 
-        // Dynamically import NiiVue from local asset (vendored)
-        const {{ Niivue }} = await import('{NIIVUE_JS_URL}');
+        // Use globally loaded NiiVue (from head script)
+        // Do NOT use dynamic import() - it breaks Gradio on HF Spaces
+        const Niivue = window.Niivue;
+        if (!Niivue) {
+            throw new Error('NiiVue not loaded. Ensure head_paths includes niivue-loader.html');
+        }
 
         // Initialize NiiVue
-        const nv = new 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);
@@ -495,39 +587,39 @@ NIIVUE_UPDATE_JS = f"""
         if (status) status.style.display = 'none';
 
         // Prepare volumes
-        const volumes = [{{ url: volumeUrl, name: 'input.nii.gz' }}];
+        const volumes = [{ url: volumeUrl, name: 'input.nii.gz' }];
 
-        if (maskUrl) {{
-            volumes.push({{
+        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') {{
+        if (typeof nv.setMultiplanarLayout === 'function') {
             nv.setMultiplanarLayout(2);
-        }}
+        }
         nv.opts.show3Dcrosshair = true;
         nv.setRenderAzimuthElevation(120, 10);
         nv.drawScene();
 
         console.log('NiiVue viewer re-initialized successfully via event handler');
 
-    }} catch (error) {{
+    } catch (error) {
         console.error('NiiVue re-initialization error:', error);
         const errorDiv = document.createElement('div');
         errorDiv.style.cssText = 'color:#f66;padding:20px;text-align:center;';
         errorDiv.textContent = 'Error reloading viewer: ' + error.message;
-        if (container) {{
+        if (container) {
             container.innerHTML = '';
             container.appendChild(errorDiv);
-        }}
-    }}
-}})();
+        }
+    }
+})();
 """