feat(visualize): backend-aware tab layout (PQQA-only vs PA-only)

The Visualize page used to advertise 11 shared tabs plus 6 PA-extra
tabs. On a PA run, 7 of the 11 shared tabs (Schedule, Parallel
population, Solution-space PCA, Diversity, Loss spectrogram, Ridgeline,
Replica fate) all rendered a single "No population snapshots recorded
for this run." card because they depend on the ``PopulationTracker``
that only PQQA produces, polluting the tab bar. Symmetrically, a PQQA
run already hid the 6 PA-only tabs but its PA-flavoured narrative was
absent from the Visualize layout.

This patch splits the tabs into three groups and renders only the
universal + backend-matching ones:
- Universal (both): Solution, Dynamics, Best trajectory, Family tree
  (which is already backend-aware internally — Muller plot for PA,
  hierarchical-clustering dendrogram for PQQA).
- PQQA-only: Schedule, Parallel population, Solution-space PCA,
  Diversity, Loss spectrogram, Ridgeline, Replica fate (all depend on
  PopulationTracker).
- PA-only: PA ESS / β, PA Free energy, PA Equilibrium pop., PA
  Thermodynamics, PA Lineage vs energy, PA Ancestry Sankey.

The 7 existing ``with tab_X: ...`` rendering blocks are kept
structurally intact via a ``_discard_tab_writes()`` context manager
that creates a ``st.empty()`` placeholder, catches every write inside
its ``container()``, and calls ``placeholder.empty()`` on ``__exit__``
so the DOM carries no trace of the absorbed output. Zero reindentation
needed — ``_tab_or_noop(key)`` returns the real tab handle when the
key is in this run's layout, and a noop discard context otherwise.

Verification:
- ``test_visualize_page_renders_pa_result`` now also asserts the 7
  PQQA-only tab labels are ABSENT from the PA tab bar.
- ``test_visualize_pqqa_family_tree_renders_dendrogram`` now also
  asserts the 6 PA-only tab labels are ABSENT from the PQQA tab bar
  and that the 7 PQQA-only tabs ARE present.
- ``tasks/test/check_visualize_leakage.py`` drives both backends
  end-to-end and scans ``at.info / at.markdown / at.caption`` for
  telltale phrases ("No population snapshots recorded" / "Lineage vs
  energy" / ...) that would indicate a leak. Confirmed clean in both
  directions.
- 23 GUI AppTests + 320 unit tests pass.

Author: Yuma Ichikawa

app/pages/2_Visualize.py

@@ -88,51 +88,121 @@ class PAResult:  # type: ignore[no-redef]
 #   * PQQA → hierarchical-clustering dendrogram + per-clade energy evolution
 # That answers the user request to have a tree-style view that *adapts*
 # to the selected backend rather than hiding behind a "PA-only" label.
-base_tabs = [
-    "Solution",
-    "Dynamics",
-    "Best trajectory",
-    "Schedule",
-    "Parallel population",
-    "Solution-space PCA",
-    "Diversity",
-    "Loss spectrogram",
-    "Ridgeline",
-    "Replica fate",
-    "Family tree",
+# ---------------------------------------------------------------------------
+# Backend-aware tab layout.
+#
+# PQQA runs carry a ``PopulationTracker`` (per-epoch replica snapshots, used
+# by Population / PCA / Diversity / Spectrogram / Ridgeline / Replica-fate)
+# plus a PQQA-only ``history["bg"]`` schedule; PA runs carry a genealogy,
+# ESS / log-Z history, and equilibrium samples instead. Rendering both
+# sets on every run pollutes the UI with "No population snapshots
+# recorded" cards under PA and empty "PA: ..." tabs under PQQA. Show only
+# the tabs that apply to whichever backend produced ``result``.
+#
+# Layout:
+#   * Universal (both backends): Solution, Dynamics, Best trajectory,
+#     Family tree (tab_tree renders a backend-aware dendrogram / Muller
+#     plot internally).
+#   * PQQA-only: Schedule, Parallel population, Solution-space PCA,
+#     Diversity, Loss spectrogram, Ridgeline, Replica fate.
+#   * PA-only: PA ESS / β, PA Free energy, PA Equilibrium pop., PA
+#     Thermodynamics, PA Lineage vs energy, PA Ancestry Sankey.
+# ---------------------------------------------------------------------------
+_UNIVERSAL_TAB_KEYS: list[str] = ["sol", "hist", "best"]
+_PQQA_TAB_KEYS: list[str] = ["sched", "pop", "pca", "div", "spec", "ridge", "fate"]
+_PA_TAB_KEYS: list[str] = [
+    "pa_ess",
+    "pa_fe",
+    "pa_eq",
+    "pa_thermo",
+    "pa_lineage",
+    "pa_sankey",
 ]
-pa_extra_tabs = [
-    "PA: ESS / β",
-    "PA: Free energy",
-    "PA: Equilibrium pop.",
-    "PA: Thermodynamics",
-    "PA: Lineage vs energy",
-    "PA: Ancestry Sankey",
-]
-all_tabs = base_tabs + (pa_extra_tabs if is_pa else [])
-_tabs = st.tabs(all_tabs)
-(
-    tab_sol,
-    tab_hist,
-    tab_best,
-    tab_sched,
-    tab_pop,
-    tab_pca,
-    tab_div,
-    tab_spec,
-    tab_ridge,
-    tab_fate,
-    tab_tree,
-) = _tabs[:11]
+# ``tree`` is universal too but we put it at the end of each backend's layout
+# to keep the narrative flow "what → how → why → lineage".
+_TREE_TAB_KEY: str = "tree"
+
+_TAB_LABELS: dict[str, str] = {
+    "sol": "Solution",
+    "hist": "Dynamics",
+    "best": "Best trajectory",
+    "sched": "Schedule",
+    "pop": "Parallel population",
+    "pca": "Solution-space PCA",
+    "div": "Diversity",
+    "spec": "Loss spectrogram",
+    "ridge": "Ridgeline",
+    "fate": "Replica fate",
+    "tree": "Family tree",
+    "pa_ess": "PA: ESS / β",
+    "pa_fe": "PA: Free energy",
+    "pa_eq": "PA: Equilibrium pop.",
+    "pa_thermo": "PA: Thermodynamics",
+    "pa_lineage": "PA: Lineage vs energy",
+    "pa_sankey": "PA: Ancestry Sankey",
+}
+
 if is_pa:
-    (
-        tab_pa_ess,
-        tab_pa_fe,
-        tab_pa_eq,
-        tab_pa_thermo,
-        tab_pa_lineage,
-        tab_pa_sankey,
-    ) = _tabs[11:17]
+    _ordered_keys = _UNIVERSAL_TAB_KEYS + _PA_TAB_KEYS + [_TREE_TAB_KEY]
+else:
+    _ordered_keys = _UNIVERSAL_TAB_KEYS + _PQQA_TAB_KEYS + [_TREE_TAB_KEY]
+
+_tabs = st.tabs([_TAB_LABELS[k] for k in _ordered_keys])
+_tab_by_key: dict[str, "st.delta_generator.DeltaGenerator"] = dict(
+    zip(_ordered_keys, _tabs, strict=True)
+)
+
+
+@contextlib.contextmanager
+def _discard_tab_writes():
+    """Context manager that absorbs every Streamlit call into a placeholder
+    that is emptied on exit.
+
+    Used as a stand-in for tabs that are not part of the current backend's
+    layout (e.g. ``Schedule`` / ``Parallel population`` for a PA run) so
+    the existing ``with tab_X: ...`` rendering blocks below don't need to
+    be reindented or rewritten — they simply emit into a container that is
+    cleared the instant the ``with`` exits, leaving no trace in the page.
+    The ``st.tabs([...])`` label list already omits these tabs, so the
+    tab bar never advertises them either.
+    """
+    placeholder = st.empty()
+    try:
+        with placeholder.container():
+            yield
+    finally:
+        placeholder.empty()
+
+
+def _tab_or_noop(key: str):
+    """Return the real tab DG for ``key`` if it exists in this run's
+    layout, otherwise a write-absorbing noop context. Invariant: every
+    ``with tab_X:`` block in the rest of this page must go through this
+    accessor so it never receives ``None``.
+    """
+    real = _tab_by_key.get(key)
+    if real is not None:
+        return real
+    return _discard_tab_writes()
+
+
+tab_sol = _tab_or_noop("sol")
+tab_hist = _tab_or_noop("hist")
+tab_best = _tab_or_noop("best")
+tab_sched = _tab_or_noop("sched")
+tab_pop = _tab_or_noop("pop")
+tab_pca = _tab_or_noop("pca")
+tab_div = _tab_or_noop("div")
+tab_spec = _tab_or_noop("spec")
+tab_ridge = _tab_or_noop("ridge")
+tab_fate = _tab_or_noop("fate")
+tab_tree = _tab_or_noop("tree")
+tab_pa_ess = _tab_or_noop("pa_ess")
+tab_pa_fe = _tab_or_noop("pa_fe")
+tab_pa_eq = _tab_or_noop("pa_eq")
+tab_pa_thermo = _tab_or_noop("pa_thermo")
+tab_pa_lineage = _tab_or_noop("pa_lineage")
+tab_pa_sankey = _tab_or_noop("pa_sankey")
 
 
 def _retheme(fig):

tests/test_gui_apptest.py

@@ -228,6 +228,24 @@ def test_visualize_page_renders_pa_result():
         assert extra_tab in tab_labels, (
             f"PA-specific visualize tab {extra_tab!r} missing; got {tab_labels!r}"
         )
+    # Backend-aware layout contract: PQQA-only tabs (driven by the
+    # ``PopulationTracker`` that PA never produces) MUST NOT appear on a
+    # PA run. The user explicitly asked for this — otherwise the tab bar
+    # advertises six tabs that all just say "No population snapshots
+    # recorded for this run." and clutter the UI.
+    for pqqa_only_tab in (
+        "Schedule",
+        "Parallel population",
+        "Solution-space PCA",
+        "Diversity",
+        "Loss spectrogram",
+        "Ridgeline",
+        "Replica fate",
+    ):
+        assert pqqa_only_tab not in tab_labels, (
+            f"PQQA-only tab {pqqa_only_tab!r} must be hidden on a PA "
+            f"run; got tabs = {tab_labels!r}"
+        )
 
 
 def test_visualize_pqqa_family_tree_renders_dendrogram(tmp_path):
@@ -270,6 +288,36 @@ def test_visualize_pqqa_family_tree_renders_dendrogram(tmp_path):
     assert "Family tree" in tab_labels, (
         f"Family tree tab must be present for PQQA results; got {tab_labels!r}"
     )
+    # Backend-aware contract (mirror of the PA-run test): PA-only tabs
+    # MUST NOT appear on a PQQA run. Otherwise we advertise six empty
+    # tabs ("no free-energy history" / "no genealogy" etc).
+    for pa_only_tab in (
+        "PA: ESS / β",
+        "PA: Free energy",
+        "PA: Equilibrium pop.",
+        "PA: Thermodynamics",
+        "PA: Lineage vs energy",
+        "PA: Ancestry Sankey",
+    ):
+        assert pa_only_tab not in tab_labels, (
+            f"PA-only tab {pa_only_tab!r} must be hidden on a PQQA "
+            f"run; got tabs = {tab_labels!r}"
+        )
+    # PQQA-only tabs (what the Visualize page is designed around when
+    # the run came from ``qqa.anneal``) must still be present.
+    for pqqa_tab in (
+        "Schedule",
+        "Parallel population",
+        "Solution-space PCA",
+        "Diversity",
+        "Loss spectrogram",
+        "Ridgeline",
+        "Replica fate",
+    ):
+        assert pqqa_tab in tab_labels, (
+            f"PQQA tab {pqqa_tab!r} must be present on a PQQA run; "
+            f"got {tab_labels!r}"
+        )
 
 
 def test_solve_page_pa_backend_smoke_run():