fix(ui): simplify NiiVue loading, add diagnostic logging (#24)

Root cause analysis from external agent suggests the "Loading..." hang
is caused by JavaScript failing to load due to path resolution issues
or silent errors.

Changes based on external agent feedback:

1. **Use `head` param instead of `head_paths`**
- Eliminates file I/O that could fail on HF Spaces
- Inline script injection is simpler and more reliable

2. **Add diagnostic logging at startup**
- Log asset directory paths at module load time
- Log whether assets exist for debugging HF Spaces issues

3. **Improve error handling in NiiVue loader**
- Add try/catch around ES module import
- Store errors in window.NIIVUE_LOAD_ERROR for debugging
- Update js_on_load to check for loader errors

4. **Clean up root app.py**
- Clarify it's NOT used by HF Spaces Docker (CMD uses ui/app.py)
- Update to use same `head` approach as ui/app.py

5. **Add DIAGNOSTIC_HF_LOADING.md**
- Documents all research and hypotheses
- Lists external agent's analysis and recommendations

All 136 tests pass. Lint and type checks clean.

DIAGNOSTIC_HF_LOADING.md

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

app.py

@@ -1,12 +1,9 @@
-"""Entry point for Hugging Face Spaces deployment.
+"""Alternative entry point for local development.
 
-This module provides the entry point for deploying the stroke-deepisles-demo
-application to Hugging Face Spaces. It handles environment detection and
-configures Gradio appropriately for the deployment environment.
+NOTE: HuggingFace Spaces Docker deployment uses `python -m stroke_deepisles_demo.ui.app`
+(see Dockerfile CMD). This file is for local development convenience only.
 
-See:
-    - docs/specs/07-hf-spaces-deployment.md
-    - https://huggingface.co/docs/hub/spaces-sdks-docker
+For HF Spaces deployment, see: src/stroke_deepisles_demo/ui/app.py
 """
 
 from pathlib import Path
@@ -14,15 +11,16 @@ from pathlib import Path
 import gradio as gr
 
 # CRITICAL: Allow direct file serving for local assets (niivue.js)
-# This fixes the P0 "Loading..." bug on HF Spaces (Issue #11649)
 # Must be called BEFORE creating any Blocks
 _ASSETS_DIR = Path(__file__).parent / "src" / "stroke_deepisles_demo" / "ui" / "assets"
 gr.set_static_paths(paths=[str(_ASSETS_DIR)])
 
 from stroke_deepisles_demo.core.config import get_settings  # noqa: E402
-from stroke_deepisles_demo.core.logging import setup_logging  # noqa: E402
+from stroke_deepisles_demo.core.logging import get_logger, setup_logging  # noqa: E402
 from stroke_deepisles_demo.ui.app import get_demo  # noqa: E402
-from stroke_deepisles_demo.ui.viewer import get_niivue_loader_path  # noqa: E402
+from stroke_deepisles_demo.ui.viewer import get_niivue_head_html  # noqa: E402
+
+logger = get_logger(__name__)
 
 # Initialize logging
 settings = get_settings()
@@ -32,14 +30,15 @@ setup_logging(settings.log_level, format_style=settings.log_format)
 demo = get_demo()
 
 if __name__ == "__main__":
-    # Launch configuration
-    # - server_name: 0.0.0.0 required for HF Spaces (Docker)
-    # - server_port: 7860 is HF Spaces default
-    # - theme: Gradio 6 uses launch() for theme
-    # - css: Hide footer for cleaner look
+    # Log startup info for debugging
+    logger.info("=" * 60)
+    logger.info("STARTUP: stroke-deepisles-demo (root app.py)")
+    logger.info("Assets directory: %s", _ASSETS_DIR.resolve())
+    logger.info("Assets exists: %s", _ASSETS_DIR.exists())
+    logger.info("=" * 60)
 
-    # Generate the NiiVue loader HTML file (creates if needed)
-    niivue_loader = get_niivue_loader_path()
+    # Get the NiiVue loader HTML (inline script, no file I/O needed)
+    niivue_head = get_niivue_head_html()
 
     demo.launch(
         server_name=settings.gradio_server_name,
@@ -48,5 +47,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)
+        head=niivue_head,  # Inject NiiVue loader directly
     )

src/stroke_deepisles_demo/ui/app.py

@@ -27,7 +27,7 @@ from stroke_deepisles_demo.ui.components import (  # noqa: E402
 from stroke_deepisles_demo.ui.viewer import (  # noqa: E402
     NIIVUE_UPDATE_JS,
     create_niivue_html,
-    get_niivue_loader_path,
+    get_niivue_head_html,
     nifti_to_gradio_url,
     render_3panel_view,
     render_slice_comparison,
@@ -281,8 +281,16 @@ if __name__ == "__main__":
     settings = get_settings()
     setup_logging(settings.log_level, format_style=settings.log_format)
 
-    # Generate the NiiVue loader HTML file (creates if needed)
-    niivue_loader = get_niivue_loader_path()
+    # Log startup info for debugging HF Spaces issues
+    logger.info("=" * 60)
+    logger.info("STARTUP: stroke-deepisles-demo")
+    logger.info("Assets directory: %s", _ASSETS_DIR.resolve())
+    logger.info("Assets exists: %s", _ASSETS_DIR.exists())
+    logger.info("=" * 60)
+
+    # Get the NiiVue loader HTML (inline script, no file I/O needed)
+    # Using `head` param directly is simpler than `head_paths` with file generation
+    niivue_head = get_niivue_head_html()
 
     get_demo().launch(
         server_name=settings.gradio_server_name,
@@ -292,5 +300,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)
+        head=niivue_head,  # Inject NiiVue loader directly (simpler than head_paths)
     )

src/stroke_deepisles_demo/ui/viewer.py

@@ -32,46 +32,66 @@ _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()
+# NOTE: This path must be added to allowed_paths AND set_static_paths in demo.launch()
 NIIVUE_JS_URL = f"/gradio_api/file={_NIIVUE_JS_PATH.resolve()}"
 
+# Log the computed paths at module load time for debugging HF Spaces issues
+logger.info("NiiVue assets directory: %s", _ASSET_DIR.resolve())
+logger.info("NiiVue JS path: %s", _NIIVUE_JS_PATH.resolve())
+logger.info("NiiVue JS URL: %s", NIIVUE_JS_URL)
+logger.info("NiiVue JS exists: %s", _NIIVUE_JS_PATH.exists())
 
-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).
+def get_niivue_head_html() -> str:
+    """
+    Get HTML content to inject into page <head> for NiiVue loading.
 
-    The HTML file is generated at runtime because the niivue.js path
-    is dynamic (depends on installation location).
+    This returns an inline script that loads NiiVue as a global variable.
+    Using the `head` parameter directly (instead of `head_paths` with a file)
+    is simpler and avoids file I/O issues on HF Spaces.
 
     Returns:
-        Path to the niivue-loader.html file
+        HTML string containing the NiiVue loader script
 
     Note:
-        The returned path must be included in allowed_paths during launch().
+        The niivue.js path must be registered with gr.set_static_paths()
+        and included in allowed_paths during launch().
     """
-    loader_path = _ASSET_DIR / "niivue-loader.html"
+    # Log for debugging path resolution issues on HF Spaces
+    logger.info("Generating NiiVue head HTML with URL: %s", NIIVUE_JS_URL)
 
-    # 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
--->
+    return f"""<!-- NiiVue Loader: Exposes window.Niivue for js_on_load handlers -->
 <script type="module">
-    import {{ Niivue }} from '{NIIVUE_JS_URL}';
-    window.Niivue = Niivue;
-    console.log('[NiiVue Loader] Loaded globally:', typeof window.Niivue);
+    try {{
+        const niivueUrl = '{NIIVUE_JS_URL}';
+        console.log('[NiiVue Loader] Attempting to load from:', niivueUrl);
+        const {{ Niivue }} = await import(niivueUrl);
+        window.Niivue = Niivue;
+        console.log('[NiiVue Loader] Successfully loaded, window.Niivue:', typeof window.Niivue);
+    }} catch (error) {{
+        console.error('[NiiVue Loader] FAILED to load:', error);
+        // Surface the error visibly so we can debug on HF Spaces
+        window.NIIVUE_LOAD_ERROR = error.message;
+    }}
 </script>
 """
 
-    # Write/update the loader file (idempotent)
-    # This ensures the path is always correct for the current installation
+
+def get_niivue_loader_path() -> Path:
+    """
+    DEPRECATED: Use get_niivue_head_html() with the `head` parameter instead.
+
+    Get path to the NiiVue loader HTML file, creating it if needed.
+    This file-based approach is kept for backwards compatibility but
+    the direct `head` parameter approach is preferred.
+
+    Returns:
+        Path to the niivue-loader.html file
+    """
+    loader_path = _ASSET_DIR / "niivue-loader.html"
+    loader_content = get_niivue_head_html()
+
     try:
-        # Check if file exists and has correct content
         if loader_path.exists():
             existing_content = loader_path.read_text()
             if existing_content == loader_content:
@@ -80,8 +100,6 @@ def get_niivue_loader_path() -> 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(
@@ -457,6 +475,10 @@ NIIVUE_ON_LOAD_JS = """
         const waitForNiivue = async () => {
             for (let i = 0; i < 50; i++) {
                 if (window.Niivue) return window.Niivue;
+                // Check if loader script failed (error stored in global)
+                if (window.NIIVUE_LOAD_ERROR) {
+                    throw new Error('NiiVue loader failed: ' + window.NIIVUE_LOAD_ERROR);
+                }
                 await new Promise(r => setTimeout(r, 100));
             }
             return null;
@@ -464,7 +486,9 @@ NIIVUE_ON_LOAD_JS = """
 
         const Niivue = await waitForNiivue();
         if (!Niivue) {
-            throw new Error('NiiVue not loaded after 5s. Ensure head_paths includes niivue-loader.html and gr.set_static_paths is called.');
+            // Provide diagnostic info about what might be wrong
+            const loadErr = window.NIIVUE_LOAD_ERROR || 'unknown';
+            throw new Error('NiiVue not loaded after 5s. Check browser console for errors. Load error: ' + loadErr);
         }
 
         // Initialize NiiVue
@@ -567,6 +591,10 @@ NIIVUE_UPDATE_JS = """
         const waitForNiivue = async () => {
             for (let i = 0; i < 50; i++) {
                 if (window.Niivue) return window.Niivue;
+                // Check if loader script failed (error stored in global)
+                if (window.NIIVUE_LOAD_ERROR) {
+                    throw new Error('NiiVue loader failed: ' + window.NIIVUE_LOAD_ERROR);
+                }
                 await new Promise(r => setTimeout(r, 100));
             }
             return null;
@@ -574,7 +602,9 @@ NIIVUE_UPDATE_JS = """
 
         const Niivue = await waitForNiivue();
         if (!Niivue) {
-            throw new Error('NiiVue not loaded after 5s. Ensure head_paths includes niivue-loader.html and gr.set_static_paths is called.');
+            // Provide diagnostic info about what might be wrong
+            const loadErr = window.NIIVUE_LOAD_ERROR || 'unknown';
+            throw new Error('NiiVue not loaded after 5s. Check browser console for errors. Load error: ' + loadErr);
         }
 
         // Initialize NiiVue