Fix Gradio 6.x compatibility for HF Spaces

- Move theme/css from gr.Blocks() to launch() per Gradio 6 API
- Set ssr_mode=False to prevent localhost-access crash on HF Spaces
- Add 11 Gradio 6 compatibility tests

app.py

@@ -85,7 +85,7 @@ gene_choices = sorted(DATA["protein"]["gene_id"].tolist())
 # ===========================================================
 # Build UI
 # ===========================================================
-demo, C = build_app(line_choices, contig_choices, gene_choices)
+demo, C, _theme, _css = build_app(line_choices, contig_choices, gene_choices)
 
 # ===========================================================
 # Wire callbacks
@@ -292,4 +292,6 @@ with demo:
 # Launch
 # ===========================================================
 if __name__ == "__main__":
-    demo.launch()
+    # Gradio 6.x moved theme/css from Blocks() to launch().
+    # ssr_mode=False prevents the SSR localhost-access crash on HF Spaces.
+    demo.launch(ssr_mode=False, theme=_theme, css=_css)

tests/test_gradio6_compat.py

@@ -0,0 +1,169 @@
+"""Tests for Gradio 6.x compatibility.
+
+Verifies that the app conforms to Gradio 6 API conventions:
+ - theme and css are NOT passed to gr.Blocks() constructor
+ - build_app() returns (demo, components, theme, css)
+ - theme is a valid gr.themes.Base instance
+ - css is a non-empty string
+ - demo.launch() would receive ssr_mode, theme, css kwargs
+"""
+
+import sys
+import warnings
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+# Ensure project root is in path
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import gradio as gr
+from ui.layout import build_app
+from ui.theme import build_theme, CUSTOM_CSS
+
+
+class TestBuildAppSignature:
+    """Verify build_app() returns the Gradio-6-compatible tuple."""
+
+    def test_returns_four_values(self):
+        """build_app() must return (demo, components, theme, css)."""
+        result = build_app(["line_a", "line_b"], ["contig_0"], ["g00001"])
+        assert len(result) == 4, (
+            f"Expected build_app() to return 4 values, got {len(result)}"
+        )
+
+    def test_demo_is_blocks(self):
+        """First return value is a gr.Blocks instance."""
+        demo, _, _, _ = build_app(["line_a"], ["contig_0"], ["g00001"])
+        assert isinstance(demo, gr.Blocks)
+
+    def test_components_is_dict(self):
+        """Second return value is a dict of UI components."""
+        _, components, _, _ = build_app(["line_a"], ["contig_0"], ["g00001"])
+        assert isinstance(components, dict)
+        assert len(components) > 0
+
+    def test_theme_is_gradio_theme(self):
+        """Third return value is a Gradio theme object."""
+        _, _, theme, _ = build_app(["line_a"], ["contig_0"], ["g00001"])
+        assert isinstance(theme, gr.themes.Base)
+
+    def test_css_is_nonempty_string(self):
+        """Fourth return value is a non-empty CSS string."""
+        _, _, _, css = build_app(["line_a"], ["contig_0"], ["g00001"])
+        assert isinstance(css, str)
+        assert len(css) > 0
+
+
+class TestThemeAndCSS:
+    """Verify theme and CSS are valid objects."""
+
+    def test_build_theme_returns_base(self):
+        """build_theme() returns a gr.themes.Base instance."""
+        theme = build_theme()
+        assert isinstance(theme, gr.themes.Base)
+
+    def test_custom_css_contains_expected_classes(self):
+        """CUSTOM_CSS contains key class names used in the app."""
+        for cls in [
+            ".progress-tracker",
+            ".metric-card",
+            ".gene-badge-core",
+            ".backpack-chip",
+        ]:
+            assert cls in CUSTOM_CSS, f"Expected '{cls}' in CUSTOM_CSS"
+
+
+class TestBlocksConstructor:
+    """Verify gr.Blocks() is NOT called with theme or css kwargs."""
+
+    def test_blocks_no_theme_or_css_kwarg(self):
+        """gr.Blocks() should only receive title, not theme/css."""
+        original_init = gr.Blocks.__init__
+
+        captured_kwargs = {}
+
+        def spy_init(self, *args, **kwargs):
+            captured_kwargs.update(kwargs)
+            return original_init(self, *args, **kwargs)
+
+        with patch.object(gr.Blocks, "__init__", spy_init):
+            build_app(["line_a"], ["contig_0"], ["g00001"])
+
+        assert "theme" not in captured_kwargs, (
+            "theme should not be passed to gr.Blocks() in Gradio 6.x -- "
+            "pass it to launch() instead"
+        )
+        assert "css" not in captured_kwargs, (
+            "css should not be passed to gr.Blocks() in Gradio 6.x -- "
+            "pass it to launch() instead"
+        )
+
+
+class TestNoDeprecationWarnings:
+    """Verify build_app() does not emit Gradio deprecation warnings."""
+
+    def test_no_gradio_warnings(self):
+        """build_app() should not trigger Gradio 6.x deprecation warnings."""
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            build_app(["line_a"], ["contig_0"], ["g00001"])
+
+        gradio_warnings = [
+            w for w in caught
+            if "gradio" in str(w.category).lower()
+            or "gradio" in str(w.message).lower()
+            or "moved" in str(w.message).lower()
+        ]
+        assert len(gradio_warnings) == 0, (
+            f"Unexpected Gradio warnings: "
+            f"{[str(w.message) for w in gradio_warnings]}"
+        )
+
+
+class TestComponentsPresent:
+    """Verify that build_app() returns all expected component keys."""
+
+    def test_required_component_keys(self):
+        """Essential UI components are present in the returned dict."""
+        _, components, _, _ = build_app(
+            ["line_a", "line_b"], ["contig_0"], ["g00001"]
+        )
+
+        required_keys = [
+            "state", "tabs", "data_health_html",
+            # Quest 0
+            "q0_tab", "q0_globe_plot", "q0_line_dropdown",
+            "q0_country_dropdown", "q0_start_btn",
+            # Quest 1
+            "q1_tab", "q1_umap_plot", "q1_color_radio",
+            # Quest 2
+            "q2_tab", "q2_donut_plot", "q2_treasure_table",
+            # Quest 3
+            "q3_tab", "q3_heatmap_plot", "q3_contig_dropdown",
+            # Quest 4
+            "q4_tab", "q4_gene_dropdown",
+            # Final
+            "final_generate_btn", "final_report_md",
+        ]
+        for key in required_keys:
+            assert key in components, f"Missing component key: {key}"
+
+
+class TestSSRModeDisabled:
+    """Verify ssr_mode=False is passed at launch time."""
+
+    def test_launch_kwargs_in_app_module(self):
+        """app.py should pass ssr_mode=False, theme, and css to launch()."""
+        app_path = Path(__file__).resolve().parent.parent / "app.py"
+        source = app_path.read_text()
+
+        assert "ssr_mode=False" in source, (
+            "app.py must pass ssr_mode=False to demo.launch() "
+            "to prevent SSR localhost crash on HF Spaces"
+        )
+        assert "theme=" in source and "css=" in source, (
+            "app.py must pass theme= and css= to demo.launch() "
+            "for Gradio 6.x compatibility"
+        )

ui/layout.py

@@ -16,11 +16,16 @@ def build_app(line_choices: list[str], contig_choices: list[str],
               gene_choices: list[str]) -> tuple:
     """
     Build the full Gradio Blocks app.
-    Returns (demo, components_dict) where components_dict maps all UI elements.
+
+    Returns (demo, components_dict, theme, css) where:
+      - demo is the gr.Blocks instance
+      - components_dict maps all UI elements
+      - theme is the Gradio theme object (pass to launch() for Gradio >= 6.0)
+      - css is the custom CSS string (pass to launch() for Gradio >= 6.0)
     """
     theme = build_theme()
 
-    with gr.Blocks(theme=theme, css=CUSTOM_CSS, title="Pigeon Pea Pangenome Atlas") as demo:
+    with gr.Blocks(title="Pigeon Pea Pangenome Atlas") as demo:
         # State
         state = gr.State(value=None)
 
@@ -67,7 +72,7 @@ def build_app(line_choices: list[str], contig_choices: list[str],
         **{f"gc_{k}": v for k, v in gc.items()},
     }
 
-    return demo, components
+    return demo, components, theme, CUSTOM_CSS
 
 
 def _build_progress_html(active_quest: int) -> str:

ui/theme.py

@@ -7,7 +7,7 @@ Exports
 -------
 get_theme()   – returns the configured ``gr.themes.Base`` instance.
 build_theme() – alias kept for backward compatibility.
-CUSTOM_CSS    – CSS string injected into ``gr.Blocks(css=...)``.
+CUSTOM_CSS    – CSS string passed to ``demo.launch(css=...)`` (Gradio 6.x).
 """
 
 import gradio as gr