docs/specs/11-bug-niivue-js-on-load-not-rerunning.md

Bug #11: NiiVue js_on_load Doesn't Re-run on Value Update

Status: FIXED

Date: 2025-12-09 Branch: fix/niivue-js-rerun Fixed By: Implementing .then(fn=None, js=NIIVUE_UPDATE_JS) pattern with correct document.querySelector context. Related: Bug #10 (Fixed)

---

TL;DR - ROOT CAUSE

Gradio's js_on_load only runs ONCE when the component first mounts.

When we update the gr.HTML value with new content (after segmentation), the js_on_load code does NOT re-execute. The HTML updates, but the JavaScript initialization never runs.

---

Symptom

After successful DeepISLES inference on HF Spaces:

• Viewer shows "Loading viewer..." (initial HTML state)
• Status never changes to "Checking WebGL2..." or "Loading NiiVue..."
• No error message displayed
• No brain scan visible

What IS working:

• DeepISLES inference completes (~36 seconds)
• Slice Comparison (matplotlib 2D view) renders correctly
• Metrics JSON displays correctly
• Download button provides the prediction mask
• Initial HTML renders with data-* attributes

What is NOT working:

• js_on_load JavaScript doesn't re-run when value updates
• NiiVue never initializes after segmentation

---

Evidence

Gradio Documentation

From Custom HTML Components Guide:

"Event listeners attached in js_on_load are only attached once when the component is first rendered. If your component creates new elements dynamically that need event listeners, attach the event listener to a parent element..."

Observed Behavior

1. Page loads → js_on_load runs → No volumeUrl → Shows "Waiting for segmentation..."
2. User clicks "Run Segmentation"
3. DeepISLES runs successfully
4. run_segmentation() returns new HTML with data-volume-url attribute
5. gr.HTML value updates with new HTML
6. js_on_load does NOT re-run ← THE BUG
7. Viewer shows "Loading viewer..." (static HTML, no JS executed)

Server Logs (Working)

INFO: Running segmentation for sub-stroke0001
INFO: DeepISLES subprocess completed in 35.73s

Inference works. The problem is client-side JavaScript execution.

---

Code Flow Analysis

Current Implementation (BROKEN)

# components.py - js_on_load set once at component creation
niivue_viewer = gr.HTML(
    label="Interactive 3D Viewer",
    js_on_load=NIIVUE_ON_LOAD_JS,  # Runs ONCE on mount
)

# app.py - returns new HTML value after segmentation
def run_segmentation(...):
    # ... inference ...
    niivue_html = create_niivue_html(dwi_url, mask_url)
    return niivue_html, ...  # Value updates, but js_on_load doesn't re-run

Why It Fails

1. Component mounts → js_on_load runs (no data yet)
2. Value updates → HTML re-renders, js_on_load SKIPPED
3. New HTML has data-* attributes but no JS execution

---

Proposed Solutions (Ranked)

Solution 1: Use js Parameter on Event Handler (Recommended)

Gradio allows running JavaScript after an event completes:

run_btn.click(
    fn=run_segmentation,
    inputs=[...],
    outputs=[results["niivue_viewer"], ...],
).then(
    fn=None,  # MUST be explicit!
    js=NIIVUE_UPDATE_JS,  # ⚠️ CANNOT reuse NIIVUE_ON_LOAD_JS - different context!
)

Pros: Native Gradio pattern, runs after each update Cons: Requires separate JS constant (see "Different JS Context" section below)

⚠️ CRITICAL: The js param does NOT have access to element. You must use document.querySelector() instead. See the corrected JavaScript in the "Recommended Implementation" section.

Solution 2: MutationObserver in js_on_load

Watch for DOM changes and re-initialize. This approach IS valid because js_on_load has access to element:

// In js_on_load - 'element' IS available here
const initNiiVue = async () => {
    const container = element.querySelector('.niivue-viewer') || element;
    const volumeUrl = container.dataset.volumeUrl;
    if (!volumeUrl) return;
    // ... NiiVue initialization code ...
};

// Watch for attribute changes (when Python updates data-volume-url)
const observer = new MutationObserver((mutations) => {
    for (const mutation of mutations) {
        if (mutation.type === 'attributes' &&
            mutation.attributeName.startsWith('data-')) {
            initNiiVue();
            break;
        }
    }
});

// Observe the element for attribute changes
observer.observe(element, {
    attributes: true,
    subtree: true,
    attributeFilter: ['data-volume-url', 'data-mask-url']
});

// Initial check
initNiiVue();

Pros: Self-contained in js_on_load, no separate event wiring needed Cons: More complex, relies on Gradio updating DOM attributes (may not work if Gradio replaces the entire element instead of updating attributes)

Solution 3: Use gradio-iframe Component

The gradio-iframe package allows JavaScript to execute normally:

from gradio_iframe import iFrame

niivue_viewer = iFrame(
    value=create_niivue_html_with_script(...),  # Scripts execute in iframe
)

Pros: Scripts execute normally inside iframe Cons: Additional dependency, iframe quirks

Solution 4: Embed JS in HTML via data: URL iframe

Self-contained iframe with script:

def create_niivue_html(...):
    html_with_script = f'''<script>...</script><canvas>...</canvas>'''
    encoded = base64.b64encode(html_with_script.encode()).decode()
    return f'<iframe src="data:text/html;base64,{encoded}"></iframe>'

Pros: No external dependency, scripts execute Cons: Complex, potential CSP issues

Solution 5: Custom Gradio Component

Build a proper gradio_niivue Svelte component:

gradio cc create NiiVue --template HTML

Pros: Most robust, proper lifecycle hooks Cons: Significant development effort

---

Investigation Steps

Step 1: Test Solution 1 (js param on .then())

run_btn.click(
    fn=run_segmentation,
    inputs=[...],
    outputs=[...],
).then(
    fn=None,
    js="console.log('then JS ran'); console.log(document.querySelector('.niivue-viewer'));"
)

Verify:

• Does js run after value update?
• Does it have access to the updated DOM?

Step 2: Test Solution 2 (MutationObserver)

Add observer to js_on_load and check if it triggers on value change.

Step 3: Check Browser Console

Open DevTools and look for:

• JavaScript errors
• Console logs from js_on_load
• Network requests to NiiVue CDN

---

Temporary Workaround

The 2D Slice Comparison view works correctly and provides adequate visualization for evaluation purposes while we fix the 3D viewer.

---

Priority Assessment

Severity: P1 (High)

• 3D viewer is a key feature for the demo
• The fix we deployed doesn't fully work
• Blocks demo usability for 3D visualization

Impact:

• Users see "Loading viewer..." indefinitely
• 2D fallback still works
• Demo is partially functional

---

Deep Web Research (2025-12-09)

Relationship Between Bug #10 and Bug #11

They are the SAME underlying issue with two symptoms:

1. Bug #10: Gradio strips <script> tags from gr.HTML for XSS security
2. Bug #11: Gradio's js_on_load only runs once on component mount

Both stem from Gradio's design decision to limit JavaScript execution in HTML components for security reasons.

Verified Gradio Behavior (from official docs)

js_on_load Limitation (CONFIRMED)

From Gradio Custom HTML Components:

"Event listeners attached in js_on_load are only attached once when the component is first rendered."

Solution 1 VALIDATED: .then(fn=None, js=...)

From Gradio Custom CSS and JS:

"You can pass both a JavaScript function and a Python function (in which case the JavaScript function is run first) or only Javascript (and set the Python fn to None)."

Critical Implementation Detail from GitHub Issue #6729:

"js without fn is executed only if fn is explicitly set to None"

# WORKS
b1.click(js=js, fn=None)

# DOES NOT WORK
b2.click(js=js)  # fn defaults to something, not None

js Parameter Signature

From Gradio HTML Docs:

"The js parameter is an optional frontend js method to run before running 'fn'. Input arguments for js method are values of 'inputs' and 'outputs', return should be a list of values for output components."

Alternative Solutions Research

gradio-iframe Package

From PyPI gradio-iframe:

• Version: 0.0.10 (Jan 2024)
• JavaScript executes normally inside iframe
• Known issues: Height doesn't always adjust, not fully responsive
• Status: Alpha, possibly abandoned (no updates in 12 months)
• Risk: May not be compatible with Gradio 6.x

MutationObserver Pattern

From MDN MutationObserver:

MutationObserver can watch for DOM changes and trigger re-initialization:

const observer = new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
        if (mutation.type === 'attributes' &&
            mutation.attributeName === 'data-volume-url') {
            initNiiVue();
        }
    });
});
observer.observe(element, { attributes: true, attributeFilter: ['data-volume-url'] });

Caveat from Gradio docs:

"Warning: The use of query selectors in custom JS and CSS is not guaranteed to work across Gradio versions that bind to Gradio's own HTML elements as the Gradio HTML DOM may change."

ipyniivue (Jupyter Widget)

From GitHub ipyniivue:

• Built on anywidget framework
• Designed for Jupyter, not Gradio
• No direct Gradio integration exists

Recommended Implementation

Based on research, Solution 1 (.then(fn=None, js=...)) is the correct fix.

Step 1: Create a NEW JavaScript constant for event handlers

We CANNOT reuse NIIVUE_ON_LOAD_JS because it uses element which is not available in the event handler context. We need a new constant:

# viewer.py - NEW constant for event handler context
NIIVUE_UPDATE_JS = f"""
(async () => {{
    // ⚠️ NO 'element' available - must use document.querySelector()
    const container = document.querySelector('.niivue-viewer');
    if (!container) {{
        console.error('NiiVue container not found');
        return;
    }}

    const canvas = container.querySelector('canvas');
    const status = container.querySelector('.niivue-status');

    // Get URLs from data attributes
    const volumeUrl = container.dataset.volumeUrl;
    const maskUrl = container.dataset.maskUrl;

    // Skip if no volume URL
    if (!volumeUrl) {{
        console.log('No volume URL yet');
        return;
    }}

    try {{
        if (status) status.innerText = 'Loading NiiVue...';

        const {{ Niivue }} = await import('{NIIVUE_CDN_URL}');
        const nv = new Niivue({{
            logging: false,
            show3Dcrosshair: true,
            backColor: [0, 0, 0, 1]
        }});

        await nv.attachToCanvas(canvas);
        if (status) status.style.display = 'none';

        const volumes = [{{ url: volumeUrl, name: 'input.nii.gz' }}];
        if (maskUrl) {{
            volumes.push({{ url: maskUrl, colorMap: 'red', opacity: 0.5 }});
        }}

        await nv.loadVolumes(volumes);
        nv.setSliceType(nv.sliceTypeMultiplanar);
        nv.drawScene();

        console.log('NiiVue initialized via .then()');
    }} catch (error) {{
        console.error('NiiVue init error:', error);
        if (container) {{
            const errorDiv = document.createElement('div');
            errorDiv.style.cssText = 'color:#f66;padding:20px;text-align:center;';
            errorDiv.textContent = 'Error: ' + error.message;
            container.innerHTML = '';
            container.appendChild(errorDiv);
        }}
    }}
}})();
"""

Step 2: Wire up the event handler in app.py

# app.py
from stroke_deepisles_demo.ui.viewer import NIIVUE_UPDATE_JS

run_btn.click(
    fn=run_segmentation,
    inputs=[case_selector, settings["fast_mode"], settings["show_ground_truth"]],
    outputs=[results["niivue_viewer"], results["slice_plot"], results["metrics"],
             results["download"], status],
).then(
    fn=None,  # MUST be explicit per GitHub Issue #6729!
    js=NIIVUE_UPDATE_JS,
)

Why this works:

1. Python run_segmentation() updates gr.HTML value with new data-* attributes
2. .then() chains after the click handler completes
3. fn=None tells Gradio to skip Python, run JS only
4. js=NIIVUE_UPDATE_JS runs our initialization code
5. JS uses document.querySelector() to find the updated DOM

⚠️ CRITICAL: Different JS Context (VERIFIED)

The js parameter on event handlers has a completely different context than js_on_load:

Context	js_on_load	js on event handler
element	✅ Available	❌ NOT available
props	✅ Available	❌ NOT available
trigger()	✅ Available	❌ NOT available
Arguments	None	Receives input/output values

From Gradio Custom CSS and JS:

"Input arguments for js method are values of 'inputs' and 'outputs'"

Example from Gradio docs:

reverse_btn.click(
    None, [subject, verb, object], output2,
    js="(s, v, o) => o + ' ' + v + ' ' + s"  # Receives VALUES, not DOM elements
)

This is why we need TWO separate JavaScript constants:

• NIIVUE_ON_LOAD_JS - Uses element.querySelector() (for initial mount)
• NIIVUE_UPDATE_JS - Uses document.querySelector() (for .then() handler)

Risk Assessment: Is This Fixable?

Approach	Feasibility	Risk Level	Notes
.then(fn=None, js=...)	✅ High	Low	Native Gradio, documented
MutationObserver	✅ High	Medium	Complex, DOM stability warning
gradio-iframe	⚠️ Medium	High	Abandoned, Gradio 6 compat unknown
data: URL iframe	⚠️ Medium	Medium	CSP issues possible
Custom component	✅ High	Low	Most work, most robust

Verdict: YES, this is fixable. Solution 1 should work based on verified documentation.

---

References

• Gradio Custom HTML Components - js_on_load limitation
• Gradio Custom CSS and JS - js parameter docs
• Gradio Event Listeners - .then() method
• GitHub Issue #6729 - fn=None requirement
• gradio-iframe PyPI - Alternative approach
• ipyniivue GitHub - Jupyter widget (not Gradio)
• MDN MutationObserver - DOM watching
• Bug #10 Spec - Previous fix attempt
• Issue #19 - Base64 optimization (related)