fix(ui): vendor NiiVue library to bypass HF Spaces CSP (#24) (#24)

* fix(ui): vendor NiiVue library to bypass HF Spaces CSP (#24)

Root cause: HuggingFace Spaces CSP blocks external CDN imports.
The dynamic import from unpkg.com caused the Gradio frontend to hang
on "Loading..." indefinitely while the Python backend ran correctly.

Fix: Vendor NiiVue v0.65.0 locally instead of CDN:
- Add src/stroke_deepisles_demo/ui/assets/niivue.js (2.9MB)
- Update viewer.py to use /gradio_api/file= for local serving
- Add allowed_paths to demo.launch() in both entry points
- Exclude assets/ from pre-commit large file check

All 136 tests pass. Lint and type checks clean.

* docs: add pre-commit-config to files modified table (CodeRabbit)

.pre-commit-config.yaml

@@ -19,7 +19,11 @@ repos:
     rev: v6.0.0
     hooks:
       - id: trailing-whitespace
+        exclude: ^src/stroke_deepisles_demo/ui/assets/
       - id: end-of-file-fixer
+        exclude: ^src/stroke_deepisles_demo/ui/assets/
       - id: check-yaml
       - id: check-added-large-files
         args: [--maxkb=1000]
+        # Exclude vendored assets (NiiVue library ~2.9MB)
+        exclude: ^src/stroke_deepisles_demo/ui/assets/

app.py

@@ -9,6 +9,8 @@ See:
     - https://huggingface.co/docs/hub/spaces-sdks-docker
 """
 
+from pathlib import Path
+
 import gradio as gr
 
 from stroke_deepisles_demo.core.config import get_settings
@@ -28,10 +30,16 @@ if __name__ == "__main__":
     # - server_port: 7860 is HF Spaces default
     # - theme: Gradio 6 uses launch() for theme
     # - css: Hide footer for cleaner look
+
+    # Allow access to local assets (e.g., niivue.js)
+    # Assets are located in src/stroke_deepisles_demo/ui/assets
+    assets_dir = Path(__file__).parent / "src" / "stroke_deepisles_demo" / "ui" / "assets"
+
     demo.launch(
         server_name=settings.gradio_server_name,
         server_port=settings.gradio_server_port,
         share=settings.gradio_share,
         theme=gr.themes.Soft(),
         css="footer {visibility: hidden}",
+        allowed_paths=[str(assets_dir)],
     )

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

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

src/stroke_deepisles_demo/ui/app.py

@@ -274,6 +274,9 @@ if __name__ == "__main__":
     settings = get_settings()
     setup_logging(settings.log_level, format_style=settings.log_format)
 
+    # Allow access to local assets (e.g., niivue.js)
+    assets_dir = Path(__file__).parent / "assets"
+
     get_demo().launch(
         server_name=settings.gradio_server_name,
         server_port=settings.gradio_server_port,
@@ -281,4 +284,5 @@ if __name__ == "__main__":
         theme=gr.themes.Soft(),
         css="footer {visibility: hidden}",
         show_error=True,  # Show full Python tracebacks in UI for debugging
+        allowed_paths=[str(assets_dir)],
     )

src/stroke_deepisles_demo/ui/viewer.py

@@ -14,20 +14,23 @@ from __future__ import annotations
 
 import json
 import uuid
-from typing import TYPE_CHECKING
+from pathlib import Path
 
 import numpy as np
 from matplotlib.figure import Figure
 
 from stroke_deepisles_demo.metrics import load_nifti_as_array
 
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
 # 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
 NIIVUE_VERSION = "0.65.0"
-NIIVUE_CDN_URL = f"https://unpkg.com/@niivue/niivue@{NIIVUE_VERSION}/dist/index.js"
+_ASSET_DIR = Path(__file__).parent / "assets"
+_NIIVUE_JS_PATH = _ASSET_DIR / "niivue.js"
+
+# Ensure absolute path for Gradio serving
+# NOTE: This path must be added to allowed_paths in demo.launch()
+NIIVUE_JS_URL = f"/gradio_api/file={_NIIVUE_JS_PATH.resolve()}"
 
 
 def nifti_to_gradio_url(nifti_path: Path) -> str:
@@ -383,8 +386,8 @@ NIIVUE_ON_LOAD_JS = f"""
 
         if (status) status.innerText = 'Loading NiiVue...';
 
-        // Dynamically import NiiVue from CDN
-        const {{ Niivue }} = await import('{NIIVUE_CDN_URL}');
+        // Dynamically import NiiVue from local asset (vendored)
+        const {{ Niivue }} = await import('{NIIVUE_JS_URL}');
 
         // Initialize NiiVue
         const nv = new Niivue({{
@@ -473,8 +476,8 @@ NIIVUE_UPDATE_JS = f"""
             return;
         }}
 
-        // Dynamically import NiiVue from CDN
-        const {{ Niivue }} = await import('{NIIVUE_CDN_URL}');
+        // Dynamically import NiiVue from local asset (vendored)
+        const {{ Niivue }} = await import('{NIIVUE_JS_URL}');
 
         // Initialize NiiVue
         const nv = new Niivue({{