fix(docs): update technical debt documentation and add root cause analysis for NiiVue loading issue

- Revised the TECHNICAL_DEBT.md to reflect the current status of the NiiVue/WebGL integration, marking it as a P0 BLOCKER due to issues on HuggingFace Spaces.
- Added detailed sections outlining the critical issue with NiiVue not loading, including root causes and proposed solutions.
- Introduced new specifications for the Gradio Custom Component approach to resolve the loading issue, emphasizing the need for a structured solution.
- Documented the findings from the recent audits and analyses, providing a clear path forward for developers addressing the integration challenges.

These updates aim to enhance clarity and provide actionable insights for future development efforts.

docs/TECHNICAL_DEBT.md

@@ -1,21 +1,55 @@
 # Technical Debt and Known Issues
 
-> **Last Audit**: December 2025 (Revision 5)
+> **Last Audit**: December 2025 (Revision 6)
 > **Auditor**: Claude Code + External Senior Review
-> **Status**: Ironclad / Production-Ready (Google DeepMind level)
+> **Status**: P0 BLOCKER - NiiVue/WebGL integration broken on HF Spaces
 
 ## Summary
 
-Full architectural review completed. All critical and major technical debt items have been **resolved** via TDD.
+**CRITICAL ISSUE**: The NiiVue 3D viewer does not work on HuggingFace Spaces due to Gradio architecture limitations. See Issue #24.
 
 | Severity | Count | Description | Status |
 |----------|-------|-------------|--------|
+| **P0 (Critical)** | 1 | NiiVue/WebGL on HF Spaces | **BLOCKED** |
 | P2 (Medium) | 0 | Temp dir leak, silent empty dataset, brittle git dep | **All Fixed** |
 | P3 (Low) | 0 | SSRF vector, float64 memory, base64 overhead | **All Fixed** |
 | P3 (Low) | 1 | Type ignores | **Acceptable** |
 
 ---
 
+## P0 BLOCKER: NiiVue/WebGL on HuggingFace Spaces (Issue #24)
+
+### Problem
+
+The Interactive 3D Viewer (NiiVue) causes the entire HF Spaces app to hang on "Loading..." forever.
+
+### Root Cause
+
+**Gradio does not natively support custom WebGL content.** All hack attempts have **FAILED** (confirmed Dec 10, 2025):
+
+| Attempt | Date | Result |
+|---------|------|--------|
+| CDN import in js_on_load | Dec 9 | FAILED - CSP blocked |
+| Vendored + import() in js_on_load | Dec 9 | FAILED - Blocks Svelte hydration |
+| head_paths with loader HTML | Dec 9 | FAILED - Same issue |
+| head= with inline import() | Dec 10 | **FAILED** - Confirmed DOA |
+
+Gradio maintainers explicitly closed Issues #4511 (NIfTI support) and #7649 (WebGL canvas) as "not planned", recommending Custom Components instead.
+
+**There is no gr.HTML hack that works. The only path forward is a Gradio Custom Component.**
+
+### Solution
+
+Build a **Gradio Custom Component** that properly wraps NiiVue using Svelte.
+
+See: `docs/specs/28-gradio-custom-component-niivue.md`
+
+### Workaround (Current)
+
+The "Static Report" tab (Matplotlib 2D slices) works correctly. Only the "Interactive 3D" tab is broken.
+
+---
+
 ## Resolved Issues (Fixed in `fix/technical-debt`)
 
 ### ✅ P2: Silent Empty Dataset on Missing Data Directory
@@ -58,4 +92,6 @@ See: `docs/specs/19-perf-base64-to-file-urls.md`
 
 ## Conclusion
 
-The codebase has been hardened to a high standard of quality ("Ironclad"). All failure modes identified in the audit are now covered by regression tests and fixed in the implementation.
+The codebase is **production-ready for all features EXCEPT the Interactive 3D Viewer (NiiVue)**. All other technical debt items are resolved.
+
+**Next step:** Implement Gradio Custom Component per spec #28 to fix the P0 blocker.

docs/specs/{GRADIO_WEBGL_ANALYSIS.md → 24-bug-gradio-webgl-analysis.md}

@@ -1,7 +1,23 @@
-# Gradio + WebGL/NiiVue Analysis
+# Bug #24: Gradio + WebGL/NiiVue Root Cause Analysis
 
 **Date:** 2025-12-10
-**Context:** Understanding why NiiVue (WebGL) doesn't work in Gradio on HF Spaces
+**Status:** ALL HACKS FAILED - Custom Component Required
+**Issue:** HF Spaces stuck on "Loading..." forever
+**Root Cause:** Gradio does not natively support custom WebGL content
+**Solution:** Build Gradio Custom Component (see spec #28)
+
+---
+
+## CONFIRMED: All gr.HTML Hacks Have Failed
+
+| Attempt | Date | Result |
+|---------|------|--------|
+| CDN import in js_on_load | Dec 9 | FAILED - CSP blocks external imports |
+| Vendored + dynamic import() in js_on_load | Dec 9 | FAILED - Blocks Svelte hydration |
+| head_paths with loader HTML | Dec 9 | FAILED - Same hydration issue |
+| head= with inline import() | Dec 10 | **FAILED** - Confirmed DOA |
+
+**There is no hack that works.** The only path forward is spec #28 (Gradio Custom Component).
 
 ---
 

docs/specs/28-gradio-custom-component-niivue.md

@@ -1,7 +1,7 @@
 # Spec #28: Gradio Custom Component for NiiVue
 
 **Date:** 2025-12-10
-**Status:** PROPOSED
+**Status:** REQUIRED - All gr.HTML hacks have failed (confirmed Dec 10)
 **Blocks:** Issue #24 (HF Spaces "Loading..." forever)
 **Effort:** Medium (2-3 days)
 **Success Probability:** 90%
@@ -10,7 +10,7 @@
 
 ## Executive Summary
 
-**The current `gr.HTML` + JavaScript approach will not work reliably.**
+**All `gr.HTML` + JavaScript approaches have FAILED. This is the only path forward.**
 
 Gradio maintainers have explicitly closed both:
 - [Issue #4511](https://github.com/gradio-app/gradio/issues/4511) - NIfTI/medical imaging support → "Not planned"
@@ -301,8 +301,8 @@ viewer = NiiVueViewer(label="Interactive 3D Viewer")
 
 ### Alternative 1: Keep Hacking gr.HTML
 - **Effort:** Low
-- **Success probability:** 30%
-- **Why rejected:** We've tried 5+ approaches, all failed. Gradio architecture doesn't support this.
+- **Success probability:** 0% (CONFIRMED FAILED)
+- **Why rejected:** We tried 6 approaches over 2 days. ALL failed. This is not a viable path.
 
 ### Alternative 2: Static HTML Space (No Gradio)
 - **Effort:** High (rebuild entire UI)

docs/specs/29-codebase-status-audit.md

@@ -0,0 +1,272 @@
+# Spec #29: Codebase Status Audit (Issue #24 NiiVue/WebGL)
+
+**Date:** 2025-12-10
+**Status:** ALL HACKS CONFIRMED FAILED (Dec 10, 2025)
+**Purpose:** Top-down analysis of current frontend/NiiVue implementation state after multiple hotfix attempts
+
+---
+
+## Executive Summary: All gr.HTML Hacks Have Failed
+
+After 6 iterations of attempted hotfixes for Issue #24 (HF Spaces "Loading..." forever), **every approach has failed**:
+
+| Attempt | Result |
+|---------|--------|
+| CDN import | FAILED - CSP blocked |
+| Vendored + js_on_load import() | FAILED - Blocks hydration |
+| head_paths | FAILED - Same issue |
+| head= with import() | **FAILED** - Confirmed Dec 10 |
+
+**The codebase contains dead code from all these failed attempts.** The correct solution is Gradio Custom Component (spec #28).
+
+---
+
+## Current Frontend Architecture
+
+### File Inventory
+
+| File | Purpose | Lines | Status |
+|------|---------|-------|--------|
+| `ui/viewer.py` | NiiVue HTML/JS generation | 643 | **BLOATED** - contains 5 approaches |
+| `ui/app.py` | Main Gradio app | 313 | Clean |
+| `ui/components.py` | UI components | 94 | Clean |
+| `app.py` (root) | Local dev entry | 61 | Clean |
+| `ui/assets/niivue.js` | Vendored NiiVue v0.65.0 | 2.9MB | **NECESSARY** |
+
+### What's in `viewer.py` Right Now
+
+| Component | Lines | Status | Notes |
+|-----------|-------|--------|-------|
+| `NIIVUE_VERSION` | 30 | OK | Version tracking |
+| `_ASSET_DIR`, `_NIIVUE_JS_PATH` | 31-32 | OK | Path constants |
+| `NIIVUE_JS_URL` | 36 | **UNUSED** | Computed but not actually used |
+| Module-level logging | 39-42 | **SLOP** | 4 log statements at import time |
+| `get_niivue_head_html()` | 45-77 | **PROBLEMATIC** | Still uses `await import()` |
+| `get_niivue_loader_path()` | 80-109 | **DEPRECATED** | Marked deprecated but still exists |
+| `nifti_to_gradio_url()` | 112-142 | OK | Issue #19 fix, working |
+| `get_slice_at_max_lesion()` | 145-187 | OK | Matplotlib helper |
+| `render_3panel_view()` | 190-281 | OK | Matplotlib 3-panel |
+| `render_slice_comparison()` | 284-380 | OK | Matplotlib comparison |
+| `create_niivue_html()` | 383-434 | OK | HTML generation |
+| `NIIVUE_ON_LOAD_JS` | 449-538 | **MOSTLY OK** | No import(), uses window.Niivue |
+| `NIIVUE_UPDATE_JS` | 546-642 | **MOSTLY OK** | No import(), uses window.Niivue |
+
+---
+
+## The Core Problem: `get_niivue_head_html()` Still Uses `import()`
+
+The current "fix" in `get_niivue_head_html()` does this:
+
+```javascript
+// viewer.py:63-76
+<script type="module">
+    try {
+        const niivueUrl = '{NIIVUE_JS_URL}';
+        console.log('[NiiVue Loader] Attempting to load from:', niivueUrl);
+        const { Niivue } = await import(niivueUrl);  // <-- SAME BROKEN PATTERN!
+        window.Niivue = Niivue;
+        console.log('[NiiVue Loader] Successfully loaded');
+    } catch (error) {
+        console.error('[NiiVue Loader] FAILED to load:', error);
+        window.NIIVUE_LOAD_ERROR = error.message;
+    }
+</script>
+```
+
+**This is the EXACT same `await import()` pattern that breaks on HF Spaces.**
+
+The only difference from our previous attempts:
+- Before: `await import()` in `js_on_load`
+- Now: `await import()` in `head=` script
+
+**Why this might not matter:** The A/B test proved that `js_on_load` with async code breaks Gradio. Moving the `import()` to `head=` might help, but it's still executing async code that could fail silently and leave `window.Niivue` undefined.
+
+---
+
+## What's Necessary vs What's Slop
+
+### NECESSARY (Keep)
+
+| Item | Why |
+|------|-----|
+| `ui/assets/niivue.js` | HF Spaces CSP blocks CDN imports |
+| `gr.set_static_paths()` | Required for Gradio 6.x file serving |
+| `nifti_to_gradio_url()` | Issue #19 fix, working |
+| `create_niivue_html()` | Generates viewer HTML |
+| `NIIVUE_ON_LOAD_JS` | Initializes viewer (doesn't import) |
+| `NIIVUE_UPDATE_JS` | Re-initializes after updates |
+| Matplotlib functions | Working 2D fallback |
+| `allowed_paths` in launch() | Runtime file access |
+
+### SLOP (Should Remove/Refactor)
+
+| Item | Why It's Slop |
+|------|---------------|
+| `NIIVUE_JS_URL` module-level computation | Computed but unused in production |
+| Module-level logging (lines 39-42) | Noisy startup logs, not useful |
+| `get_niivue_loader_path()` | Deprecated, generates file we don't need |
+| `get_niivue_head_html()` with import() | Still uses broken pattern |
+| Multiple diagnostic docs | Overlapping, contradictory, stale |
+
+### UNCERTAIN (Depends on head= fix working)
+
+| Item | Status |
+|------|--------|
+| `head=get_niivue_head_html()` in launch() | **30% chance this works** |
+
+---
+
+## Documentation Status
+
+### docs/specs/ Files
+
+| File | Status | Issue |
+|------|--------|-------|
+| `00-context.md` | **ACCURATE** | None |
+| `28-gradio-custom-component-niivue.md` | **ACCURATE** | Just written |
+| `AUDIT_JS_LOADING_ISSUES.md` | **OUTDATED** | Says `set_static_paths` is blocker, but we've moved past that |
+| `DIAGNOSTIC_HF_LOADING.md` | **OUTDATED** | Lists hypotheses we've since disproven |
+| `ROOT_CAUSE_ANALYSIS.md` | **PARTIALLY OUTDATED** | Says "IN PROGRESS", discusses head= as solution |
+| `GRADIO_WEBGL_ANALYSIS.md` | **ACCURATE** | Core analysis, identifies real problem |
+
+### docs/TECHNICAL_DEBT.md
+
+| Status | Issue |
+|--------|-------|
+| **OUTDATED** | Claims "Ironclad/Production-Ready" but doesn't mention P0 NiiVue/WebGL blocker |
+
+---
+
+## Recommended Cleanup Actions
+
+### Immediate (If head= fix fails)
+
+1. **Delete deprecated code:**
+   - Remove `get_niivue_loader_path()`
+   - Remove module-level logging
+   - Clean up `NIIVUE_JS_URL` if unused
+
+2. **Archive old diagnostic docs:**
+   - Move `AUDIT_JS_LOADING_ISSUES.md` to `archive/`
+   - Move `DIAGNOSTIC_HF_LOADING.md` to `archive/`
+   - Update `ROOT_CAUSE_ANALYSIS.md` status
+
+3. **Update TECHNICAL_DEBT.md:**
+   - Add P0 section for NiiVue/WebGL blocker
+   - Link to spec #28 (Custom Component)
+
+### Long-term (After decision on path forward)
+
+1. **If Custom Component route:**
+   - Remove all `head=` NiiVue loading code
+   - Remove `get_niivue_head_html()`
+   - Simplify `viewer.py` to just Matplotlib functions
+   - NiiVue loading becomes the component's responsibility
+
+2. **If 2D fallback route:**
+   - Remove entire NiiVue integration
+   - Remove `ui/assets/niivue.js` (2.9MB)
+   - Remove `NIIVUE_ON_LOAD_JS`, `NIIVUE_UPDATE_JS`
+   - Keep only Matplotlib rendering
+
+---
+
+## Honest Assessment
+
+### What We've Tried (6+ iterations)
+
+1. **CDN import** → Blocked by CSP
+2. **Vendored + dynamic import in js_on_load** → Blocks Svelte hydration
+3. **head_paths with loader HTML** → Complex, didn't work
+4. **head= with inline import()** → Current state, **probably won't work**
+5. **Various set_static_paths/allowed_paths combos** → File serving works, JS loading doesn't
+
+### The Pattern
+
+Every attempt has been a variation of:
+> "Load NiiVue via some JavaScript mechanism within Gradio"
+
+Every attempt has failed because:
+> **Gradio was not designed for custom WebGL content**
+
+### The Correct Solution
+
+**Stop fighting Gradio's architecture. Use a Gradio Custom Component.**
+
+This is:
+- What Gradio maintainers recommend (Issues #4511, #7649)
+- How existing WebGL components work (gradio-litmodel3d)
+- 90% success probability vs 30% for more hacks
+
+See spec #28 for implementation details.
+
+---
+
+## Current Entry Point Flow
+
+```
+HF Spaces Docker
+    ↓
+CMD ["python", "-m", "stroke_deepisles_demo.ui.app"]
+    ↓
+ui/app.py __main__ block
+    ↓
+gr.set_static_paths([_ASSETS_DIR])  # Enable file serving
+    ↓
+get_demo()  # Creates Blocks with js_on_load components
+    ↓
+demo.launch(
+    head=get_niivue_head_html(),    # <-- Injects <script type="module"> with import()
+    allowed_paths=[_ASSETS_DIR],
+)
+    ↓
+Browser loads page
+    ↓
+<head> script runs: await import('/gradio_api/file=.../niivue.js')
+    ↓
+[UNCERTAIN] Does import() succeed? Does it block Svelte?
+    ↓
+If yes: window.Niivue is set, js_on_load works
+If no: window.Niivue undefined, viewer shows error
+```
+
+---
+
+## Files Modified During Issue #24 Debug
+
+| File | Changes | Commits |
+|------|---------|---------|
+| `viewer.py` | ~6 rewrites of JS loading approach | Multiple |
+| `ui/app.py` | Added head=, set_static_paths | Multiple |
+| `app.py` | Same as ui/app.py | Multiple |
+| `ui/assets/niivue.js` | Added vendored library | 1 |
+| `.gitignore` | Added niivue-loader.html | 1 |
+| `.pre-commit-config.yaml` | Exclude assets/ from large file check | 1 |
+
+---
+
+## Conclusion
+
+**The codebase is messy but not unfixable.** The mess comes from iterating through multiple failed approaches without cleaning up between attempts.
+
+**The real issue is architectural:** Gradio + custom WebGL = unsupported pattern.
+
+**Next steps:**
+1. Test if current `head=` approach works on HF Spaces (low confidence)
+2. If it fails, implement Gradio Custom Component (spec #28)
+3. Clean up cruft regardless of which path we take
+
+---
+
+## Appendix: How to Verify Current State
+
+```bash
+# Check if NiiVue file serving works
+curl -I "https://[space-url]/gradio_api/file=/home/user/demo/src/stroke_deepisles_demo/ui/assets/niivue.js"
+# Should return 200 OK with application/javascript
+
+# Check browser console for:
+# - "[NiiVue Loader] Attempting to load from: ..."
+# - "[NiiVue Loader] Successfully loaded" OR "[NiiVue Loader] FAILED"
+# - Any errors during Gradio initialization
+```