app: live bare spinner under the answer during the freshness check (#103)

* app: keep the answer on screen with a live verifying spinner during the freshness check

Review feedback on the SWR flow: while the post-answer freshness check ran,
the user saw a bare answer with no sign anything was happening, and a
correction (when it came) appeared out of nowhere. Now the answer stays fully
visible the whole time with a small animated line UNDER it — 'Checking these
docs are still current…' — updated in place through the same Gradio stream
(no page refresh, never a blank screen). A clean check simply removes the
line; on drift the line switches to 'The docs changed — updating this
answer…' while the regeneration runs, then the corrected answer swaps in with
the note. Thread exceptions are logged and always fall back to clearing the
spinner and keeping the shown answer.

227 tests pass (added: the answer remains in every verifying frame, and the
spinner line is gone from the final value).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LX1gm8fuzK2ZeEWi3Zar1b

* app: bare spinner under the answer — just the wheel, no words

Per feedback: the verifying/updating line under the answer now shows only the
animated wheel, no explanatory text. The final ↻ note still explains a
correction after the fact.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LX1gm8fuzK2ZeEWi3Zar1b

---------

Co-authored-by: Claude <noreply@anthropic.com>

app/main.py

@@ -190,13 +190,18 @@ def respond(question: str, request: gr.Request = None):
     reads as "working", not "frozen" — then yields the finished markdown.
 
     After the answer is shown, a stale-while-revalidate pass re-checks the
-    CITED pages against the live docs (index/freshness.py): the stored copies
-    self-heal on drift, and if the grounding text really changed the answer is
-    regenerated from the fresh content and swapped in with a note. The user
-    already has an answer during all of this, and any freshness failure leaves
-    it untouched. The first yield is the static THINKING_NOTE (immediate
-    paint); gradio_client.predict returns the LAST yielded value, so the smoke
-    test still gets a real answer.
+    CITED pages against the live docs (index/freshness.py). The answer stays
+    fully visible the whole time, with a bare spinner (just the wheel, no
+    words) under it while the check runs — the user reads while we verify —
+    and everything swaps in place (Gradio streams the same output component;
+    no page refresh). Clean check → the spinner simply disappears. Drift → the
+    stored copies self-heal, and the answer is regenerated from the fresh
+    content and swapped in with the ↻ note (the spinner keeps turning during
+    the regeneration). Any freshness failure clears the spinner and leaves the
+    shown answer untouched.
+    The first yield is the static THINKING_NOTE (immediate paint);
+    gradio_client.predict returns the LAST yielded value, so the smoke test
+    still gets a real answer.
     """
     yield THINKING_NOTE
 
@@ -221,26 +226,60 @@ def respond(question: str, request: gr.Request = None):
             time.monotonic() - started < _DRAFTING_AFTER
         ) else "Drafting your answer"
         yield f"{next(frames)} {stage}…"
-    yield result.get("md", ERROR_NOTE)
+    md = result.get("md", ERROR_NOTE)
+    yield md
 
     # ---- stale-while-revalidate: the answer is already on screen ----------
+    answer = result.get("answer")
+    if answer is None or not answer.citations:
+        return
     try:
-        answer = result.get("answer")
-        if answer is None or not answer.citations:
-            return
         from index import freshness
 
         if not freshness.enabled():
             return
-        drifted = freshness.refresh_pages([c.url for c in answer.citations])
-        if not drifted:
+
+        def run_below(target):
+            """Run `target` on a thread; while it runs, keep the ANSWER on
+            screen with a bare spinner under it — just the wheel, no words
+            (in-place updates: never a blank screen, never a page refresh)."""
+            thread = threading.Thread(target=target, daemon=True)
+            thread.start()
+            while True:
+                thread.join(timeout=THINKING_TICK)
+                if not thread.is_alive():
+                    return
+                yield f"{md}\n\n<sub>{next(frames)}</sub>"
+
+        check: dict = {}
+
+        def verify():
+            try:
+                check["drifted"] = freshness.refresh_pages([c.url for c in answer.citations])
+            except Exception as exc:  # noqa: BLE001 — a thread exception must not vanish
+                print(f"[app] freshness check failed: {type(exc).__name__}: {exc}", flush=True)
+
+        yield from run_below(verify)
+        if not check.get("drifted"):
+            yield md  # clean (or check failed): just clear the spinner line
             return
+
         # the text the answer was grounded in changed → answer again from the
         # just-refreshed content and swap it in, flagged so the user knows why
-        print(f"[app] cited docs drifted ({len(drifted)}); regenerating", flush=True)
-        yield render(answer_routed(question)) + FRESHNESS_NOTE
+        print("[app] cited docs drifted; regenerating", flush=True)
+        redo: dict = {}
+
+        def regenerate():
+            try:
+                redo["md"] = render(answer_routed(question)) + FRESHNESS_NOTE
+            except Exception as exc:  # noqa: BLE001 — keep the original answer instead
+                print(f"[app] regeneration failed: {type(exc).__name__}: {exc}", flush=True)
+
+        yield from run_below(regenerate)
+        yield redo.get("md", md)  # a failed regeneration keeps the original
     except Exception as exc:  # noqa: BLE001 — never disturb the shown answer
         print(f"[app] freshness pass skipped: {type(exc).__name__}: {exc}", flush=True)
+        yield md  # clear any spinner line that was showing
 
 
 def build_ui():

tests/app/test_render.py

@@ -102,8 +102,37 @@ def test_respond_regenerates_when_the_cited_docs_drifted(monkeypatch):
 def test_respond_freshness_is_silent_when_nothing_drifted(monkeypatch):
     monkeypatch.setattr("app.main.answer_routed", lambda q, **k: _cited_answer("the answer"))
     monkeypatch.setattr("index.freshness.refresh_pages", lambda urls: set())
+    from app.main import THINKING_SPINNER
+
     chunks = list(respond("how do I use SGD?"))
     assert "the answer" in chunks[-1] and "regenerated" not in chunks[-1]
+    # the spinner under the answer is cleared once the check finishes
+    assert all(frame not in chunks[-1] for frame in THINKING_SPINNER)
+
+
+def test_respond_keeps_the_answer_visible_while_verifying(monkeypatch):
+    # while the freshness check runs, the user must keep READING the answer —
+    # under it just a bare spinner (the wheel, no words), updated in place
+    import time
+
+    from app.main import THINKING_SPINNER
+
+    monkeypatch.setattr("app.main.THINKING_TICK", 0.02)
+    monkeypatch.setattr("app.main.answer_routed", lambda q, **k: _cited_answer("the answer"))
+
+    def slow_check(urls):
+        time.sleep(0.15)  # several ticks → several verifying frames
+        return set()
+
+    monkeypatch.setattr("index.freshness.refresh_pages", slow_check)
+    chunks = list(respond("how do I use SGD?"))
+    verifying = [
+        c for c in chunks if "the answer" in c and any(f in c for f in THINKING_SPINNER)
+    ]
+    assert verifying  # the check was visible: answer + wheel together
+    # the wheel is BARE — no explanatory text rides along with it
+    assert all(c.endswith("</sub>") and "…" not in c.split("<sub>")[1] for c in verifying)
+    assert all(f not in chunks[-1] for f in THINKING_SPINNER)  # gone when done
 
 
 def test_respond_freshness_failure_never_disturbs_the_answer(monkeypatch):