fix(ui): make the raw-result accordion legible without touching the payload

A full-panel `pdac_msk_2024` query rendered a ~300,000-pixel page: 21,187 lines
of JSON in an accordion that grows with its content. The payload is not the
problem and is deliberately NOT trimmed — `samples_profiled` is the ID set the
orchestrator derives wild-type from (`per_sample_contract`), and `per_sample` /
`provenance` are the per-sample answer. Dropping either is the bug that reported
every gene as "no variation in alteration status".

So the split is display-side only. The machine endpoints still call `_as_json`
and emit the payload byte for byte (verified live over `gradio_client`: 3 x 2,336
IDs, still lists, no display key). The UI gets three tiers over the same object:

- a summary table, gene x modality, each cell carrying the percentage AND the
fraction it came from. Absent cells NAME the absence ("not on DNA panel",
"not in cohort", "not curated") — never blank, never padded to 0%, and NRG1
still shows its 6 SV events while its mutation/CNV cells stay refused.
- `_ui_json`: the same object with bulk scalar collections replaced by a counted
sentinel of a different shape, so an abridged block cannot be misread as data.
21,187 -> 1,658 lines. Small payloads (denial, refusal, error) pass through
verbatim, so the denial-visibility guarantee is untouched.
- a download of the COMPLETE payload, so nothing is withheld, only deferred.
Grounded results only — a BYOD upload is never written to disk (ADR-0003).

Height is now capped in CSS, not by `gr.Code(max_lines=...)`: gradio 6.18
ignores that here — measured in the browser, the box still rendered 23,323px
tall with it set. Measured after: page 2,818px with the accordion OPEN, and it
no longer tracks cohort size at all.

The clearing frame blanks the two new slots as it does the charts — a stale
download link is the worst version of that bug, since the file leaves the page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

gradio_ui.py

@@ -29,6 +29,7 @@ from __future__ import annotations
 import json
 import os
 import sys
+import tempfile
 import time
 from pathlib import Path
 
@@ -114,6 +115,125 @@ def _as_json(result) -> str:
     return json.dumps(result, indent=2, default=str)
 
 
+# --------------------------------------------------------------------------- #
+# Result presentation — summary first, abridged JSON, full payload on request
+# --------------------------------------------------------------------------- #
+# A full-panel `pdac_msk_2024` answer serializes to 21,187 lines / ~800 kB, which rendered the
+# "Raw result (JSON)" accordion as a ~300,000-pixel page: opening it lost the reader the charts,
+# the caution box and the scrollbar in one click (found in the 2026-08-05 signed-in
+# click-through). The size is not an accident and is NOT fixable by trimming the payload:
+#
+#   * `samples_profiled` is 3 x 2,336 IDs = 7,008 lines. It exists so a MACHINE caller can
+#     reconstruct wild-type from the sparse `per_sample` (`deploy/orchestrator_registration.yaml`,
+#     `per_sample_contract`). Dropping it is what previously made the orchestrator's join report
+#     every gene as "no variation in alteration status".
+#   * `per_sample` + `provenance` are another ~13,200 lines — KRAS alone is altered in ~90% of
+#     2,336 samples. That is the actual answer, per sample, and is equally load-bearing.
+#
+# So the payload is right and the RENDERING was wrong. The split below is therefore strictly
+# display-side: the machine endpoints keep calling `_as_json` and emit the payload byte for byte,
+# while the UI gets three tiers over the same object — a summary table (what a non-coding
+# scientist actually reads), an abridged JSON preview (structure, inspectable at a glance), and a
+# download of the COMPLETE payload (nothing is withheld, only deferred).
+_ABRIDGE_MIN_ITEMS = 8   # collections at or below this render in full — small blocks stay readable
+_ABRIDGE_PREVIEW = 3     # how many entries a sentinel shows, so the shape stays visible
+
+_ABRIDGE_NOTE = (
+    "This is an ABRIDGED view for on-screen reading: long sample-ID lists and per-sample maps "
+    "are replaced by a sentinel giving their exact size and first few entries. Nothing has been "
+    "removed from the answer itself — use “Download full result (JSON)” above for the complete "
+    "payload, which is also exactly what the machine endpoint returns."
+)
+
+
+def _is_bulk(items) -> bool:
+    """True for a big collection of SCALARS — the shape worth replacing with a sentinel.
+
+    Nested collections are left alone deliberately: `genes` has 36 entries but each is a block a
+    reader needs, whereas `samples_profiled["mutation"]` is 2,336 interchangeable IDs. Size alone
+    is the wrong test; size plus flatness is the one that only ever hits bulk data.
+    """
+    items = list(items)
+    return len(items) > _ABRIDGE_MIN_ITEMS and not any(isinstance(v, (dict, list)) for v in items)
+
+
+def _abridge(value):
+    """Recursively replace oversized collections with a self-describing sentinel.
+
+    The sentinel is deliberately a DIFFERENT SHAPE from what it replaces (a dict where a list
+    was), so an abridged block can never be mistaken for the real one — a truncated list that
+    still looks like a list is how a reader ends up believing a cohort has 8 profiled samples.
+    Every sentinel states the true count, which is the analytically load-bearing part: the size
+    of `samples_profiled[modality]` IS the denominator, and it is also carried in `n_profiled`.
+    """
+    if isinstance(value, dict):
+        if _is_bulk(value.values()):
+            return {
+                "__abridged__": f"{len(value)} entries — shown in full in the downloaded JSON",
+                "n_entries": len(value),
+                "first": dict(list(value.items())[:_ABRIDGE_PREVIEW]),
+            }
+        return {k: _abridge(v) for k, v in value.items()}
+    if isinstance(value, list):
+        if _is_bulk(value):
+            return {
+                "__abridged__": f"{len(value)} items — shown in full in the downloaded JSON",
+                "n_items": len(value),
+                "first": value[:_ABRIDGE_PREVIEW],
+            }
+        return [_abridge(v) for v in value]
+    return value
+
+
+def _ui_json(result) -> str:
+    """The accordion's JSON: the same object, abridged for display only.
+
+    Small payloads (a denial, a refusal, a BYOD summary, a `route: orchestrator` result) pass
+    through untouched — every collection in them is under the threshold — so the denial-visibility
+    and error-shape guarantees the tests pin are unaffected.
+    """
+    if not isinstance(result, dict):
+        return _as_json(result)
+    abridged = _abridge(result)
+    if abridged == result:  # nothing was large enough to touch — show it verbatim
+        return _as_json(result)
+    return _as_json({"__display__": _ABRIDGE_NOTE, **abridged})
+
+
+# Full-payload downloads. Written under the system temp dir, pruned to the most recent few, and
+# only ever used for GROUNDED registered-cohort results — a BYOD upload is never written to disk
+# (ADR-0003: "never persisted"), which is why the BYOD tab has no download button.
+_DOWNLOAD_DIR = Path(tempfile.gettempdir()) / "pdac-genomics-agent-results"
+_DOWNLOAD_KEEP = 20
+
+
+def _full_result_file(result, stem: str):
+    """Write the COMPLETE payload to a temp file and return a DownloadButton update.
+
+    The abridged accordion is only honest if the unabridged thing is one click away; without
+    this, "abridged for display" would be indistinguishable from data we quietly dropped.
+    """
+    try:
+        _DOWNLOAD_DIR.mkdir(parents=True, exist_ok=True)
+        existing = sorted(_DOWNLOAD_DIR.glob("*.json"), key=lambda p: p.stat().st_mtime)
+        for stale in existing[: max(0, len(existing) - _DOWNLOAD_KEEP + 1)]:
+            stale.unlink(missing_ok=True)
+        handle, path = tempfile.mkstemp(prefix=f"{stem}-", suffix=".json", dir=_DOWNLOAD_DIR)
+        with os.fdopen(handle, "w", encoding="utf-8") as fh:
+            fh.write(_as_json(result))
+    except OSError:
+        # A download we cannot write is not a reason to lose the answer — the summary table,
+        # the charts and the abridged JSON all still render.
+        return gr.update(visible=False)
+    return gr.update(value=path, visible=True)
+
+
+def _safe_source_stem(result) -> str:
+    source = result.get("source") if isinstance(result, dict) else None
+    text = str(source or "result").replace(":", "-")
+    return "".join(c if c.isalnum() or c in "-_" else "-" for c in text)[:60] or "result"
+
+
 # --------------------------------------------------------------------------- #
 # Plots
 # --------------------------------------------------------------------------- #
@@ -215,6 +335,83 @@ def _frequency_plots(result):
     return updates
 
 
+# --------------------------------------------------------------------------- #
+# Summary table — the top tier of the disclosure
+# --------------------------------------------------------------------------- #
+# One row per requested gene, one column per modality, each cell carrying the frequency AND the
+# fraction it came from. It is the answer a reader wants before any of the per-sample detail,
+# and it is what makes the abridged JSON acceptable: the numbers are on the page, not inside a
+# collapsed accordion.
+#
+# An absent cell is NEVER blank and never zero. Padding every gene to three modalities is the
+# specific bug this repo has already fixed twice (it reports NRG1 as 0% mutated on a cohort that
+# never sequenced it), so each empty cell instead SAYS which kind of absence it is — and the four
+# kinds are genuinely different things:
+_CELL_NOT_ON_PANEL = "not on DNA panel"      # cohort never interrogated the gene for this modality
+_CELL_NO_MODALITY = "not in cohort"          # the whole cohort lacks the modality (per-study gate)
+_CELL_NOT_CURATED = "not curated"            # our snapshot's gap, fixed by re-curating
+_SUMMARY_GENE_COL = "gene"
+_SUMMARY_NOTE_COL = "coverage"
+
+
+def _summary_cell(entry: dict, modality: str, modalities_available: dict) -> str:
+    block = entry.get(modality)
+    if isinstance(block, dict) and "frequency" in block:
+        pct = round(block["frequency"] * 100, 1)
+        return f"{pct}%  ({block['n_altered']} / {block['n_profiled']})"
+    if entry.get("curated") is False:
+        return _CELL_NOT_CURATED
+    if not modalities_available.get(modality):
+        return _CELL_NO_MODALITY
+    if entry.get("assayed") is False:
+        return _CELL_NOT_ON_PANEL
+    return _CELL_NO_MODALITY
+
+
+def _coverage_note(entry: dict) -> str:
+    """A SHORT reason for a gated row — the payload keeps the full wording.
+
+    The tool's own `note` runs to three sentences, which is right in the JSON and wrong in a
+    table cell: one long note makes every row as tall as the longest, and 36 of them reproduce
+    the scrolling problem this change exists to remove. The distinctions are preserved, only
+    compressed — and the full text is one click away in the downloaded payload.
+    """
+    if entry.get("curated") is False:
+        return "absent from our curated snapshot — re-curation fixes it"
+    if entry.get("assayed") is False:
+        if isinstance(entry.get("sv"), dict):
+            # The modality-scoped gate (ADR-0008): off the DNA panel, but the fusion assay
+            # covers it, so the SV cell legitimately carries a number while the others do not.
+            return "off the DNA panel — fusion assay covers it, so SV only"
+        return "never sequenced in this cohort — not a zero"
+    return ""
+
+
+def _summary_frame(result) -> pd.DataFrame | None:
+    """Gene x modality frequency table, with every absence named rather than left blank."""
+    genes = result.get("genes") if isinstance(result, dict) else None
+    if not genes:
+        return None
+    available = result.get("modalities_available") or {}
+    rows = []
+    for gene, entry in genes.items():
+        if not isinstance(entry, dict):
+            continue
+        row = {_SUMMARY_GENE_COL: gene}
+        for modality in _MODALITY_ORDER:
+            row[_MODALITY_LABELS[modality]] = _summary_cell(entry, modality, available)
+        row[_SUMMARY_NOTE_COL] = _coverage_note(entry)
+        rows.append(row)
+    return pd.DataFrame(rows) if rows else None
+
+
+def _summary_table(result):
+    frame = _summary_frame(result)
+    if frame is None or frame.empty:
+        return gr.update(value=None, visible=False)
+    return gr.update(value=frame, visible=True)
+
+
 def _subtype_frame(result) -> pd.DataFrame | None:
     """Tidy (gene, subtype, % altered) frame from a `variant_by_subtype` result."""
     if not isinstance(result, dict) or not result.get("join_available"):
@@ -672,6 +869,11 @@ def _ui_variant_status(source, genes, profile: gr.OAuthProfile | None = None):
     warning (found on prod, 2026-08-05). Clearing first means the worst intermediate state a
     reader can catch is an EMPTY chart, which claims nothing, rather than a stale one, which
     claims something false. The cost is one extra frame; the alternative is a wrong answer.
+
+    Output order is (caution, summary table, three charts, download, JSON). The JSON stays LAST:
+    the gating tests read the answer as `outputs[-1]` and every slot between the caution and it
+    as "must show nothing on a denial", which the two new slots satisfy by returning a
+    hidden-visibility update on the denied path exactly as the charts do.
     """
     username = _username(profile)
     src = registered_source(source)
@@ -679,12 +881,30 @@ def _ui_variant_status(source, genes, profile: gr.OAuthProfile | None = None):
     if not allowed:
         record_run("variant_status", username=username, source=src, status="denied")
         _, js = _denied_json(denial)
-        yield (_denial_caution_md(denial), *_CLEAR_PLOTS, js)
+        yield (
+            _denial_caution_md(denial),
+            gr.update(value=None, visible=False),
+            *_CLEAR_PLOTS,
+            gr.update(visible=False),
+            js,
+        )
         return
-    yield (gr.update(), *_CLEAR_PLOTS, gr.update())
+    # The clearing frame blanks the summary table and the download file for the same reason it
+    # blanks the charts: leaving the previous cohort's numbers on screen under the new cohort's
+    # caution is a wrong answer, and a stale download link is the worst version of it — the file
+    # would leave the page and be read later with no indication which query produced it. Values
+    # only, never visibility (see `_CLEAR_PLOTS`).
+    yield (gr.update(), gr.update(value=None), *_CLEAR_PLOTS, gr.update(value=None), gr.update())
     result = _safe_result(lambda: _query_variant_status(list(genes) or list(PANEL), source))
     record_run("variant_status", username=username, source=src, result=result)
-    yield (_status_caution_md(result), *_frequency_plots(result), _as_json(result))
+    yield (
+        _status_caution_md(result),
+        _summary_table(result),
+        *_frequency_plots(result),
+        _full_result_file(result, _safe_source_stem(result)),
+        # Abridged for the screen only — the button above serves the payload in full.
+        _ui_json(result),
+    )
 
 
 def _ui_variant_by_subtype(
@@ -816,7 +1036,22 @@ def _byod_caution_md(result):
 # --------------------------------------------------------------------------- #
 # App
 # --------------------------------------------------------------------------- #
-with gr.Blocks(title="PDAC Genomics Agent") as demo:
+# The height cap on the raw-JSON box, in CSS rather than in `gr.Code(max_lines=...)`.
+#
+# `max_lines` is NOT honoured by gradio 6.18's CodeMirror editor — measured in the browser, a
+# full-panel `pdac_msk_2024` answer still rendered a 23,323-pixel-tall box with `max_lines=25`
+# set, i.e. the box grows with the content exactly as before. The parameter is kept below as a
+# declaration of intent, but THIS is what enforces it. Without a cap the page height tracks the
+# payload, which is the whole bug: abridgement alone took the page from ~300,000px to ~25,000px,
+# and only this makes it constant.
+_CSS = """
+#vs-raw-json .cm-editor, #vs-raw-json .cm-scroller {
+    max-height: 460px;
+    overflow: auto;
+}
+"""
+
+with gr.Blocks(title="PDAC Genomics Agent", css=_CSS) as demo:
     gr.Markdown(
         "# PDAC Genomics Agent\n"
         "Somatic **mutation**, **copy-number** and **structural-variant (fusion)** status over a "
@@ -855,16 +1090,44 @@ with gr.Blocks(title="PDAC Genomics Agent") as demo:
             )
         vs_button = gr.Button("Query variant status", variant="primary")
         vs_caution = gr.Markdown(visible=False)
+        # Progressive disclosure, widest first: summary table -> charts -> full payload on
+        # request -> abridged JSON. The table is deliberately ABOVE the charts — it carries the
+        # fractions the bars are drawn from, and it is the only tier that can say "not on DNA
+        # panel" rather than drawing nothing.
+        vs_summary = gr.Dataframe(
+            label="Alteration frequency by gene (cell = % altered, and the fraction it came from)",
+            interactive=False,
+            wrap=True,
+            # Bounded height: 36 panel genes scroll INSIDE the table rather than lengthening the
+            # page. The whole point of this change is that page height stops tracking data size.
+            max_height=420,
+            visible=False,
+        )
         # One chart per modality — see `_frequency_plots`. Never a single stacked chart: the
         # modalities have different denominators and overlapping membership, so a stack is not
         # a quantity. Each starts hidden and is shown only when the answer contains it.
         vs_plots = [gr.BarPlot(visible=False) for _ in _MODALITY_ORDER]
-        with gr.Accordion("Raw result (JSON)", open=False):
-            vs_json = gr.Code(label="Result", language="json")
+        # The complete, unabridged payload — byte for byte what the machine endpoint returns.
+        # It sits OUTSIDE the accordion, above it, so the abridged preview can never be mistaken
+        # for the whole answer.
+        vs_download = gr.DownloadButton("Download full result (JSON)", visible=False)
+        with gr.Accordion("Raw result (JSON — abridged preview)", open=False):
+            gr.Markdown(
+                "Long sample-ID lists and per-sample maps are shown as a sentinel giving their "
+                "exact size and first few entries, so this stays readable: a full-panel query on "
+                "a 2,336-sample cohort is ~21,000 lines of JSON. **Nothing is withheld** — use "
+                "*Download full result (JSON)* above for the complete payload."
+            )
+            # Height is bounded by `_CSS` via this elem_id, NOT by `max_lines` — see the note on
+            # `_CSS`, which gradio 6.18 ignores here. Between them: the abridgement keeps what
+            # you scroll through comprehensible, and the cap keeps the PAGE finite.
+            vs_json = gr.Code(
+                label="Result", language="json", lines=20, max_lines=25, elem_id="vs-raw-json"
+            )
         vs_button.click(
             _ui_variant_status,
             inputs=[vs_source, vs_genes],
-            outputs=[vs_caution, *vs_plots, vs_json],
+            outputs=[vs_caution, vs_summary, *vs_plots, vs_download, vs_json],
             api_name=False,
         )
 

tests/test_plot_and_caveat_rendering.py

@@ -186,11 +186,23 @@ def test_variant_status_handler_clears_the_plot_before_answering():
     assert len(frames) == 2, "expected a clearing frame followed by the answer"
     clearing, answer = frames
 
-    # The clearing frame blanks each chart's VALUE and leaves visibility alone. Hiding here
+    # The clearing frame blanks each result slot's VALUE and leaves visibility alone. Hiding here
     # instead made every query a hide→show flip, and the third chart lost that race about half
     # the time — it stayed unmounted ("null does not exist" in the browser), so a cohort WITH
     # structural variants rendered as mutation+CNV only, reading as "no fusions here".
-    assert all(u is None for u in clearing[1:-1]), "clearing frame must blank, not hide"
+    #
+    # Two spellings of "blanked", because the slots are no longer all charts: a chart clears to a
+    # bare `None`, while the summary table and the full-result download clear with an explicit
+    # `gr.update(value=None)`. The invariant is the same for all of them and is what this asserts
+    # — carry no value, and say nothing about visibility. The download slot matters most here: a
+    # stale file link would leave the page entirely and be opened later with nothing to say which
+    # query produced it.
+    for slot in clearing[1:-1]:
+        if slot is None:
+            continue
+        assert isinstance(slot, dict), f"unexpected clearing-frame slot: {slot!r}"
+        assert slot.get("value") is None, "clearing frame must carry no value"
+        assert "visible" not in slot, "clearing frame must blank, not hide"
     assert any(getattr(u, "value", None) is not None for u in answer[1:-1])
 
 

tests/test_raw_result_legibility.py

@@ -0,0 +1,173 @@
+"""The "Raw result (JSON)" accordion must stay readable — WITHOUT trimming the payload.
+
+A full-panel `pdac_msk_2024` answer is ~21,000 lines / ~800 kB, and rendering it verbatim
+produced a roughly 300,000-pixel page (found in the 2026-08-05 signed-in click-through). The
+size is load-bearing, not waste:
+
+  * `samples_profiled` is the per-modality profiled universe as an ID SET, and the ONLY way a
+    machine caller can reconstruct wild-type from the sparse `per_sample`
+    (`deploy/orchestrator_registration.yaml`, `per_sample_contract`). Dropping it is what made
+    the orchestrator's join report every gene as "no variation in alteration status".
+  * `per_sample` / `provenance` are the per-sample answer itself.
+
+So this is a RENDERING split, and these tests pin both halves of it: the machine endpoint still
+emits the payload in full, and the UI's view is abridged, bounded, and self-describing. A change
+that fixes the page by shortening the payload fails here.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+import gradio_ui
+from src.tools.query_variant_status import query_variant_status
+
+# The widest answer this deployment can produce: full panel over the largest cohort.
+BIG_SOURCE = "cbioportal:pdac_msk_2024"
+
+
+@pytest.fixture(scope="module")
+def big_result():
+    return query_variant_status([], BIG_SOURCE)
+
+
+# --------------------------------------------------------------------------- #
+# The payload contract is untouched
+# --------------------------------------------------------------------------- #
+def test_full_payload_keeps_every_profiled_sample_id(big_result):
+    """`samples_profiled` stays a complete ID list — the orchestrator derives WT from it."""
+    for modality, ids in big_result["samples_profiled"].items():
+        assert isinstance(ids, list)
+        assert len(ids) == big_result["n_profiled"][modality]
+        assert all(isinstance(i, str) for i in ids)
+
+
+def test_machine_json_is_the_unabridged_payload(big_result):
+    """`_as_json` — what every `gr.api` endpoint returns — carries the payload verbatim."""
+    body = json.loads(gradio_ui._as_json(big_result))
+    assert body == json.loads(json.dumps(big_result, default=str))
+    assert len(body["samples_profiled"]["mutation"]) == 2336
+
+
+# --------------------------------------------------------------------------- #
+# The UI view is abridged, bounded, and honest about it
+# --------------------------------------------------------------------------- #
+def test_ui_json_is_dramatically_smaller_than_the_payload(big_result):
+    full = gradio_ui._as_json(big_result).splitlines()
+    ui = gradio_ui._ui_json(big_result).splitlines()
+    assert len(full) > 20_000, "fixture no longer reproduces the size that caused the bug"
+    # Bounded by the PANEL (36 genes x 3 modalities), not by the cohort (2,336 samples) — that
+    # decoupling is the actual fix. The page can no longer grow with cohort size.
+    assert len(ui) < 2_500
+    assert len(ui) < len(full) / 8
+
+
+def test_ui_json_replaces_big_collections_with_a_counted_sentinel(big_result):
+    """An abridged block states its TRUE size and is shaped so it cannot be misread as the data."""
+    body = json.loads(gradio_ui._ui_json(big_result))
+
+    profiled = body["samples_profiled"]["mutation"]
+    assert isinstance(profiled, dict), "a truncated list would still look like a list"
+    assert profiled["n_items"] == 2336 == big_result["n_profiled"]["mutation"]
+    assert len(profiled["first"]) == gradio_ui._ABRIDGE_PREVIEW
+
+    per_sample = body["genes"]["KRAS"]["mutation"]["per_sample"]
+    assert per_sample["n_entries"] == len(big_result["genes"]["KRAS"]["mutation"]["per_sample"])
+
+
+def test_ui_json_says_it_is_abridged_and_where_the_full_thing_is(big_result):
+    body = json.loads(gradio_ui._ui_json(big_result))
+    note = body["__display__"]
+    assert "ABRIDGED" in note
+    assert "Download full result" in note
+
+
+def test_frequencies_and_denominators_survive_abridgement(big_result):
+    """Only collections are abridged. Every NUMBER a reader might act on is untouched."""
+    body = json.loads(gradio_ui._ui_json(big_result))
+    for gene, entry in big_result["genes"].items():
+        for modality in ("mutation", "cnv", "sv"):
+            block = entry.get(modality)
+            if not isinstance(block, dict) or "frequency" not in block:
+                continue
+            shown = body["genes"][gene][modality]
+            assert shown["frequency"] == block["frequency"]
+            assert shown["n_altered"] == block["n_altered"]
+            assert shown["n_profiled"] == block["n_profiled"]
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        {"status": "denied", "reason": "Please sign in."},
+        {"status": "refused", "reason": "non_human_species", "message": "not human"},
+        {"status": "error", "reason": "RuntimeError: cBioPortal is down"},
+        {"source": "cbioportal:paad_tcga", "n_samples": 3, "genes": {}},
+    ],
+)
+def test_small_payloads_pass_through_verbatim(payload):
+    """A denial/refusal/error is never rewritten — the visibility guarantees rest on its shape."""
+    assert json.loads(gradio_ui._ui_json(payload)) == payload
+
+
+# --------------------------------------------------------------------------- #
+# The summary table — the tier a non-coding scientist actually reads
+# --------------------------------------------------------------------------- #
+def test_summary_table_has_one_row_per_requested_gene(big_result):
+    frame = gradio_ui._summary_frame(big_result)
+    assert len(frame) == len(big_result["genes"])
+    assert list(frame["gene"]) == list(big_result["genes"])
+
+
+def test_summary_table_never_pads_an_unassayed_gene_to_zero(big_result):
+    """The regression this repo has already fixed twice: a gene nobody sequenced is not 0%.
+
+    ELAVL1 is off `pdac_msk_2024`'s DNA panel and has no fusion events, so every one of its
+    cells must NAME the absence rather than show a percentage.
+    """
+    frame = gradio_ui._summary_frame(big_result)
+    row = frame[frame["gene"] == "ELAVL1"].iloc[0]
+    for modality in gradio_ui._MODALITY_ORDER:
+        cell = row[gradio_ui._MODALITY_LABELS[modality]]
+        assert "%" not in cell
+        assert cell == gradio_ui._CELL_NOT_ON_PANEL
+    assert "not a zero" in row[gradio_ui._SUMMARY_NOTE_COL]
+
+
+def test_summary_table_honours_the_modality_scoped_gate(big_result):
+    """NRG1 (ADR-0008): off the DNA panel, but 6 real somatic rearrangements — SV shows,
+    mutation and CNV do not."""
+    frame = gradio_ui._summary_frame(big_result)
+    row = frame[frame["gene"] == "NRG1"].iloc[0]
+    assert row[gradio_ui._MODALITY_LABELS["mutation"]] == gradio_ui._CELL_NOT_ON_PANEL
+    assert row[gradio_ui._MODALITY_LABELS["cnv"]] == gradio_ui._CELL_NOT_ON_PANEL
+    sv = row[gradio_ui._MODALITY_LABELS["sv"]]
+    assert "%" in sv and "6 / 2336" in sv
+    assert "SV only" in row[gradio_ui._SUMMARY_NOTE_COL]
+
+
+def test_summary_cell_states_the_fraction_not_just_the_percentage(big_result):
+    """"93.7%" alone hides the denominator, and the denominator is the thing people get wrong."""
+    frame = gradio_ui._summary_frame(big_result)
+    kras = frame[frame["gene"] == "KRAS"].iloc[0][gradio_ui._MODALITY_LABELS["mutation"]]
+    assert "93.7%" in kras
+    assert "2188 / 2336" in kras
+
+
+def test_summary_table_hidden_when_there_is_nothing_to_show():
+    for empty in ({"genes": {}}, {"status": "denied"}, None):
+        assert gradio_ui._summary_table(empty)["visible"] is False
+
+
+# --------------------------------------------------------------------------- #
+# The download — the abridgement is only honest if the full thing is one click away
+# --------------------------------------------------------------------------- #
+def test_download_file_holds_the_complete_payload(big_result):
+    update = gradio_ui._full_result_file(big_result, gradio_ui._safe_source_stem(big_result))
+    assert update["visible"] is True
+    with open(update["value"], encoding="utf-8") as fh:
+        written = json.load(fh)
+    assert written == json.loads(json.dumps(big_result, default=str))
+    assert len(written["samples_profiled"]["cnv"]) == 2336