fix(chat): keep in-flight answers alive across in-app view switches

Root cause (owner repro, verified in a real browser 2026-09-06): the
five navbar views (Chat, RAG, Sources, Tuning, History) were separate
HTML documents, so a navbar click was a REAL cross-document navigation
— the chat page unloaded, the in-flight SSE fetch was aborted, and the
phase-48 teardown (app/api/chat.py `finally`, "chat: turn cancelled")
stopped the model. Observed: send question -> click RAG mid-stream ->
click Chat -> the answer never finished: no `query_log` row, and on
return a dangling question with no brain record (the pre-token pagehide
partial persist skips because `acc` is empty).

Phase-48 LOCKED-DECISION REFINEMENT (owner-confirmed 2026-09-06,
flagged per AGENTS.md rule 3, not silently deviated): "real navigation
cancels the fetch" now means LEAVING THE APP — tab close,
external/other-document navigation, the Stop button. In-app navbar
switches are client-side view switches and no longer cancel.

Fix — Option A (SPA shell), chosen over B (Service Worker owns the
stream) and C (server-side turn registry + resume):
- frontend/index.html is the shell: ONE `<main id="main">` holds the
  five `<section class="view">` blocks; hidden views carry BOTH
  `hidden` and `inert` (WCAG — no focus/keyboard traversal). The
  shared header, the single `doc-modal-*` skeleton, and the
  `#app-version` footer each exist exactly once; the per-view copies
  from the four folded pages are dropped.
- New frontend/assets/router.js (vanilla module — no framework, no
  bundler, No-CDN rule intact): lazy-imports a view module on FIRST
  show only (mount-once, hide-forever — the chat view's in-flight SSE
  reader persists across switches; that persistence IS the fix);
  intercepts same-shell navbar links with preventDefault +
  history.pushState (never a document load); handles popstate; single
  writer of `.nav-link` active state (is-active + aria-current),
  document.title, and the per-view meta description (values carried
  over from the old pages' heads, brand-resolved at write time).
- Each folded page's JS becomes `export async function mount(root)` —
  root-scoped queries; `initSharedHeader()` dropped (the header boots
  once in the shell via the chat module; the admin flag comes from the
  same cached `fetchIsAdmin()` promise — zero extra requests).
- app/main.py: a small list-driven route factory serves the shell for
  /tuning.html, /sources.html, /git-sources.html, /history.html —
  registered AFTER the API routers and BEFORE the static catch-all
  (routes-first). The phase-33 caching middleware applies no-cache +
  `?v=` rewriting unchanged; app/core/caching.py needed NO change
  (the view paths did not change — pinned by the integration tests).
- The four old view .html files are DELETED (one source of truth);
  deep links to the old URLs keep working (the router picks the view
  from the pathname); `/?chat=<id>` is unaffected; the Containerfile
  bundles router.js (inlining the lazy view modules) and drops the
  folded page files.
- app/schemas.py: HistoryTurn.text cap 4000 -> 32000 — the shell
  keeps long saved answers in the chat, and the old cap (stricter than
  the 24_000-char total history budget) 422-rejected any second turn
  in such a chat (found by the phase-42 E2E suite on the shell).

Boundaries: login.html, shared.html, doc-edit.html, document.html
REMAIN separate documents (flow pages, not navbar tabs); a mid-stream
navigation to doc-edit/document.html still cancels per phase 48
(follow-up candidate, out of scope). The SSE API is unchanged. Real
departures still cancel the turn — phase 48 intact (pinned by
tests/e2e/test_stop_generation.py, unchanged, and by the new suite's
real-departure control).

Tests:
- Phase-20 suite REWRITTEN to the new semantics
  (tests/e2e/test_sources_midstream_bug.py): a navbar switch no longer
  cancels — the stream survives the switch and the FULL answer
  settles; the pagehide partial persist REMAINS for real departures
  (the partial's exact shape — first streamed chunk prefix, no done
  metadata — is still pinned there).
- NEW story suite tests/e2e/test_nav_switch_keeps_stream.py (mock
  LLM): the owner repro (send -> RAG mid-stream -> Chat: window
  sentinel survives = same document, FULL answer, exactly one brain
  turn in bor.chat.v1, exactly one settled query_log row, auto-saved
  row matches) + the same mid-stream switch against the other three
  views + the real-departure-still-cancels control + the no-switch
  baseline.
- tests/unit/test_frontend_router.py: source-level pins of the router
  invariants (click interceptor targets ONLY same-shell view paths,
  pushState-only switches, mount-once guard, hidden+inert pair,
  single-writer active state/title); shell-route integration tests
  (each folded path serves the shell with no-cache + `?v=` body; a
  non-view path still 404s); the file-reading unit pins re-pointed at
  the shell (the four view files are gone — the shell is the source
  of truth).

Verification (this commit): full suite green — 1565 unit+integration
tests, app/ coverage 99% (>90% floor); ruff + pyright clean; the
phase's E2E suites green in isolation (house protocol, AGENTS.md rule
9). Owner repro verified in a real browser against the real LLM
(dev server :8010, headful Chromium): "tell me about everquest" ->
RAG mid-stream -> Chat — the answer completed with one brain bubble
and no error banner, `query_log` gained exactly one settled row
(deflected=True: the dev KB holds no EverQuest docs — the settle, not
the topic, is the proof), zero "chat: turn cancelled" lines for that
turn; the control (real navigation to /shared.html mid-stream) still
cancelled (no settled row, the cancel line logged, the partial
persisted on return). Screenshots: .agents/screenshots/76_manual_*.

Phase 76 (76_spa_nav_shell) complete — moved to
.agents/phases/complete/.
This commit is contained in:
2026-09-06 06:31:31 -04:00
parent 7e567bddf3
commit ffa919b8bf
78 changed files with 5548 additions and 3244 deletions
+168 -90
View File
@@ -1,8 +1,14 @@
"""Unit: the phase-50 task-04 History-page contract.
"""Unit: the phase-50 task-04 History contract.
The browser behavior itself is E2E-gated by the story suite (task 05);
like the other frontend-adjacent unit files, this module pins the
JS/CSS/HTML markers the History page depends on, so a silent
Phase 76 (task 03): the History view is a view of the shell —
``frontend/history.html`` is deleted, its content lives in the shell's
``#view-history`` section, and ``history.js`` is a ``mount(root)`` view
module the router lazy-imports. This module pins the JS/CSS/HTML
markers the view depends on accordingly (the JS pins against
``history.js`` — brace-balanced slices, since phase 76 task 03 the
functions live inside ``mount(root)`` — the HTML pins against the
shell, scoped to the view where view-scoped); the browser behavior
itself is E2E-gated by the story suite (task 05), and a silent
regression is caught without a browser:
* the anonymous no-fetch gate (the gate in, the table out, and the
@@ -14,19 +20,21 @@ regression is caught without a browser:
(owner-locked 2026-08-29: no native confirm dialog on this page);
* the ``/?chat=<id>`` Open-link href shape (TODO.md L5 — "return to
that history with a click");
* ``#nav-history`` on ALL SEVEN pages (the phase-34 one-bar contract)
+ ``header.js``'s reveal-for-admin block;
* ``#nav-history`` on ALL surviving pages (the phase-34 one-bar
contract — phase 76: the four folded navbar-view files are gone
(tasks 01–03), so the page list is the shell + the surviving
documents) + ``header.js``'s reveal-for-admin block;
* the full-width table CSS (AGENTS.md rule 5) + the confirm pair +
the empty-state row;
* the Stale column (phase 53, task 04): the READ-ONLY marker cell in
``makeRow`` (the rose ``.stale-pill`` from the row's ``stale`` flag
+ the em-dash fallback, the ``<td>`` aria-label in BOTH states —
WCAG 2.1 AA, conveyed without the visual), the ``Stale`` ``<th>``
between Updated and Share in ``history.html``, and the ``.stale-pill``
rose-family CSS in ``styles.css``.
between Updated and Share in the shell's History view, and the
``.stale-pill`` rose-family CSS in ``styles.css``.
The Containerfile stage-1 coverage (history.html copied, history.js
bundled) is pinned dynamically by
The Containerfile stage-1 coverage (the shell copied, the view modules
bundled into the router) is pinned dynamically by
``tests/integration/test_containerfile_assets.py`` — a page or module
missing from stage 1 fails there.
"""
@@ -39,27 +47,25 @@ FRONTEND = Path(__file__).resolve().parents[2] / "frontend"
ASSETS = FRONTEND / "assets"
INDEX_HTML = FRONTEND / "index.html"
SOURCES_HTML = FRONTEND / "sources.html"
GIT_SOURCES_HTML = FRONTEND / "git-sources.html"
TUNING_HTML = FRONTEND / "tuning.html"
DOCUMENT_HTML = FRONTEND / "document.html"
LOGIN_HTML = FRONTEND / "login.html"
HISTORY_HTML = FRONTEND / "history.html"
SHARED_HTML = FRONTEND / "shared.html" # phase 51: the anonymous shared page
HISTORY_JS = ASSETS / "history.js"
HEADER_JS = ASSETS / "header.js"
STYLES_CSS = ASSETS / "styles.css"
#: The phase-34 one-bar contract + the History page + the shared
#: page: EIGHT pages.
#: The phase-34 one-bar contract + the shared page.
#: Phase 76 (task 01): the post-shell set — TUNING_HTML dropped (the
#: Tuning view is folded into the shell; its file is deleted).
#: Phase 76 (task 02): SOURCES_HTML + GIT_SOURCES_HTML dropped (both
#: views folded into the shell; both files deleted).
#: Phase 76 (task 03): HISTORY_HTML dropped (the History view is
#: folded into the shell; its file is deleted) — the shell + the
#: surviving documents.
ALL_PAGES = (
INDEX_HTML,
SOURCES_HTML,
GIT_SOURCES_HTML,
TUNING_HTML,
DOCUMENT_HTML,
LOGIN_HTML,
HISTORY_HTML,
SHARED_HTML,
)
@@ -77,11 +83,41 @@ def _css() -> str:
return _text(STYLES_CSS)
def _shell() -> str:
return _text(INDEX_HTML)
def _view(html: str) -> str:
"""The shell's History view section — from the #view-history open
tag to the container main's close (the view is the shell's LAST
view section, so the slice ends at the first ``</main>`` after
it)."""
start = html.find('<section class="view" id="view-history"')
assert start != -1, "the #view-history section must be in the shell"
end = html.find("</main>", start)
assert end != -1, "the container main must close after the view"
return html[start:end]
def _fn(js: str, name: str) -> str:
"""The source of a top-level ``function <name>(...)`` (to its close)."""
start = js.find(f"function {name}(")
assert start != -1, f"{name}() must exist in history.js"
return js[start : js.find("\n}\n", start) + 4]
"""The source of the first ``function <name>`` in history.js (brace
balanced — since phase 76 task 03 the functions live inside
mount(root), so the closing brace is indented, not line-leading;
the house pin pattern from tests/unit/test_frontend_sync_upload.py).
"""
fn = js.find(f"function {name}")
assert fn != -1, f"{name} must be defined in history.js"
open_idx = js.find("{", fn)
depth = 0
for i in range(open_idx, len(js)):
c = js[i]
if c == "{":
depth += 1
elif c == "}":
depth -= 1
if depth == 0:
return js[fn : i + 1]
raise AssertionError(f"unbalanced braces in {name}")
def _nav_history_tag(html: str) -> str:
@@ -90,14 +126,18 @@ def _nav_history_tag(html: str) -> str:
return tag.group(0)
# ---------- the #nav-history link: all seven pages ----------
# ---------- the #nav-history link: all surviving pages ----------
def test_nav_history_present_on_all_seven_pages() -> None:
def test_nav_history_present_on_all_surviving_pages() -> None:
"""The phase-34 one-bar contract extended by phase 50: the admin-only
History link SHIPS hidden (revealed by header.js for admin) on every
page, after the Tuning link, pointing at /history.html. The page's
own link is the active one (is-active + aria-current)."""
standalone page (the shell carries it once for its views — phase 76),
after the Tuning link, pointing at /history.html. NO page's link is
statically stamped active: in the shell the router is the SINGLE
WRITER of the active state (client-side, per view — the old
history.html page-level stamp is gone with the file), and the
surviving documents keep their pre-shell no-stamp state."""
for html in ALL_PAGES:
text = _text(html)
tag = _nav_history_tag(text)
@@ -107,29 +147,26 @@ def test_nav_history_present_on_all_seven_pages() -> None:
assert text.find('id="nav-tuning"') < text.find('id="nav-history"'), (
f"{html.name}: #nav-history must follow #nav-tuning"
)
# The history page is the only one whose link is active.
for html in ALL_PAGES:
tag = _nav_history_tag(_text(html))
if html.name == "history.html":
assert 'class="nav-link is-active"' in tag
assert 'aria-current="page"' in tag
else:
assert "is-active" not in tag, (
f"{html.name}: no nav link is current there"
)
assert "is-active" not in tag, (
f"{html.name}: no statically-current nav link (in the shell the "
"active state is the router's single-writer job)"
)
assert 'aria-current="page"' not in tag
def test_nav_history_count_is_exactly_eight_pages() -> None:
def test_nav_history_count_is_exactly_four_pages() -> None:
"""The pin counting occurrences across ``frontend/*.html`` — exactly
one ``id="nav-history"`` per page, eight pages (phase 51: + the
shared page), no duplicates and no extra page that forgot (or
added twice)."""
one ``id="nav-history"`` per page, FOUR pages (phase 51: + the shared
page; phase 76: the four folded navbar-view files are gone — task 01
− Tuning, task 02 − RAG + Sources, task 03 − History — the shell's
ONE link covers all its views), no duplicates and no extra page
that forgot (or added twice)."""
total = 0
for html in sorted(FRONTEND.glob("*.html")):
count = html.read_text(encoding="utf-8").count('id="nav-history"')
assert count in (0, 1), f"{html.name}: #nav-history appears {count} times"
total += count
assert total == 8, f"expected #nav-history on 8 pages, found {total}"
assert total == 4, f"expected #nav-history on 4 pages, found {total}"
def test_header_js_reveals_nav_history_for_admin() -> None:
@@ -145,41 +182,56 @@ def test_header_js_reveals_nav_history_for_admin() -> None:
assert "navHistory.hidden = !admin" in body
# ---------- history.html: the page scaffold ----------
# ---------- the shell's History view: the scaffold ----------
def test_history_page_scaffold_and_landmarks() -> None:
"""The standard page scaffold (AGENTS.md rule 5): skip link, the
shared header, the steering panel + announcer (phase 34 — ships on
every page), the page-head, the gate (ship-hidden), the
role="status" live region, and the table inside the
.table-wrap card. Footer with the version span (the index.html
shape)."""
html = _text(HISTORY_HTML)
def test_history_view_scaffold_and_landmarks() -> None:
"""The shell's History view (formerly history.html — phase 76 task
03): the shell's standard landmarks (skip link, the shared header,
the steering panel + announcer — the shell's ONE header-owned pair,
the view's copies dropped with the move) + the view section
(hidden AND inert + focusable — the WCAG pair, AGENTS.md rule 5),
the page-head, the gate (ship-hidden), the role="status" live
region, the table inside the .table-wrap card, and the shell's ONE
footer with the version span (the history page's footer copy is
dropped — no duplicate #app-version)."""
html = _shell()
assert '<a class="skip-link" href="#main">' in html
assert 'class="app-header"' in html
assert 'nav class="app-nav" id="app-nav" aria-label="Primary"' in html
tag = re.search(r'<section[^>]*id="steering-panel"[^>]*>', html)
assert tag and "hidden" in tag.group(0), "the steering panel ships hidden"
assert re.search(r'<p[^>]*id="steering-announcer"[^>]*role="status"[^>]*>', html)
assert "<main id=\"main\" class=\"app-main\" tabindex=\"-1\">" in html
assert '<h1>Saved chats</h1>' in html
assert html.count('id="steering-panel"') == 1, (
"the shell carries its ONE steering panel (the view's copy is dropped)"
)
assert html.count('id="steering-announcer"') == 1
assert html.count('<main id="main" class="app-main" tabindex="-1">') == 1
# The view section: hidden AND inert (the WCAG pair) + focusable.
view = re.search(r'<section[^>]*id="view-history"[^>]*>', html)
assert view, "the #view-history section must be in the shell"
view_tag = view.group(0)
assert "hidden" in view_tag and "inert" in view_tag, (
"the folded view ships hidden AND inert"
)
assert 'tabindex="-1"' in view_tag, "the target view is focusable"
body = _view(html)
assert '<h1>Saved chats</h1>' in body
# The anonymous gate — the #sources-gate pattern, ship-hidden.
gate = re.search(r'<section[^>]*id="history-gate"[^>]*>', html)
gate = re.search(r'<section[^>]*id="history-gate"[^>]*>', body)
assert gate and "hidden" in gate.group(0), "#history-gate must ship hidden"
assert 'href="/login.html?next=/history.html"' in html, (
"the gate's Sign in returns to the History page (no-JS fallback)"
assert 'href="/login.html?next=/history.html"' in body, (
"the gate's Sign in returns to the History view (no-JS fallback)"
)
# The action-feedback live region.
assert re.search(r'<span[^>]*id="history-status"[^>]*role="status"[^>]*>', html)
assert re.search(r'<span[^>]*id="history-status"[^>]*role="status"[^>]*>', body)
# The table wrapper: the .table-wrap card (scrollable) with its
# own id, a labeled region, focusable.
wrap = re.search(r'<div[^>]*class="table-wrap history-table-wrap"[^>]*>', html)
wrap = re.search(r'<div[^>]*class="table-wrap history-table-wrap"[^>]*>', body)
assert wrap, "the table must live in the .table-wrap card"
assert 'id="history-table-wrap"' in wrap.group(0)
assert 'role="region"' in wrap.group(0) and 'tabindex="0"' in wrap.group(0)
# Footer with the version span.
# The shell keeps its ONE footer with the version span (the history
# page's footer copy is dropped — no duplicate #app-version).
assert 'class="footer-version" id="app-version"' in html
assert html.count('id="app-version"') == 1
def test_history_table_skeleton() -> None:
@@ -187,8 +239,9 @@ def test_history_table_skeleton() -> None:
Title | Messages | Updated | Stale (phase 53) | Share (phase 51) |
Actions (the Actions header text is visually-hidden — the row
buttons carry their own aria-labels) — and the empty-state row
(ship-hidden, the exact copy)."""
html = _text(HISTORY_HTML)
(ship-hidden, the exact copy). Phase 76 (task 03): scoped to the
shell's History view section."""
html = _view(_shell())
assert '<table class="history-table">' in html
for col in ('<th scope="col">Title</th>', '<th scope="col">Messages</th>',
'<th scope="col">Updated</th>', '<th scope="col">Stale</th>',
@@ -224,16 +277,22 @@ def test_history_table_skeleton() -> None:
) in html
def test_history_page_scripts_and_no_cdn() -> None:
"""Script load order (the house pattern): brand.js classic FIRST,
the history.js module second, NO direct header.js <script> tag
(single-evaluation design — history.js imports it relatively).
No-CDN rule (AGENTS.md rule 6): no external script/link tags."""
html = _text(HISTORY_HTML)
def test_shell_scripts_and_no_cdn() -> None:
"""Shell script load order (the house pattern): brand.js classic
FIRST, the app.js (chat) + router.js modules, NO direct history.js
<script> tag (single-evaluation design — the router lazy-imports
the view module on first show; in the image the Containerfile's
esbuild stage inlines it into the router bundle). history.js keeps
its relative shared-header import (it uses the cached whoami
promise). No-CDN rule (AGENTS.md rule 6): no external
script/link tags."""
html = _shell()
srcs = re.findall(r'<script[^>]*src="([^"]+)"', html)
assert srcs == ["assets/brand.js", "/assets/history.js"], (
f"history.html must load brand.js (classic, first) + the history.js "
f"module, got {srcs}"
assert srcs[0] == "assets/brand.js", "brand.js (classic) must load first"
assert "/assets/app.js" in srcs, "the shell loads the chat module"
assert "/assets/router.js" in srcs, "the shell loads the router module"
assert [s for s in srcs if "history.js" in s] == [], (
"no direct history.js tag — the router lazy-imports the view module"
)
js = _js()
assert 'from "./header.js"' in js, (
@@ -249,12 +308,17 @@ def test_history_page_scripts_and_no_cdn() -> None:
def test_anonymous_boot_makes_no_chats_request() -> None:
"""The whoami gate in the boot IIFE: ``initSharedHeader()`` first
(shared-header contract), then the anonymous branch hides the
table, shows the gate, and RETURNS — no ``/api/chats`` request on
the wire (the router 403s anonymous; the story E2E pins the
request log). Only the admin path reaches ``loadChats()``. The
single ``fetch("/api/chats")`` in the file lives in loadChats."""
"""The whoami gate in ``mount(root)`` (phase 76 task 03 — the shell
view module form): the view module does NOT boot the shared header
(the shell's header boots exactly once, via the chat module
(app.js) at shell boot — no call site, and the import carries ONLY
the cached whoami promise), so the anonymous branch gates on
``fetchIsAdmin()`` alone (the SAME cached /api/whoami request —
zero extra), hides the table, shows the gate, and RETURNS — no
``/api/chats`` request on the wire (the router 403s anonymous; the
story E2E pins the request log). Only the admin path reaches
``loadChats()``. The single ``fetch("/api/chats")`` in the file
lives in loadChats."""
js = _js()
assert js.count('fetch("/api/chats")') == 1, (
"exactly ONE list fetch — the anonymous path must never add one"
@@ -262,19 +326,33 @@ def test_anonymous_boot_makes_no_chats_request() -> None:
load = _fn(js, "loadChats")
assert 'fetch("/api/chats")' in load, "the list fetch lives in loadChats"
boot = js[js.find("(async () => {"):]
assert boot, "the boot IIFE must exist"
assert "await initSharedHeader()" in boot
gate_i = boot.find("if (!(await fetchIsAdmin()))")
assert gate_i != -1, "the whoami gate must run in boot"
# Phase 76 (task 03): the view module never boots the shell's
# header — no CALL to the header boot (a docstring may name it;
# a call may not) and no initSharedHeader in the import — the
# shell's header boots via the chat module (app.js) at shell boot.
assert "await initSharedHeader()" not in js, (
"the view must not re-boot the shell's header"
)
import_lines = [line for line in js.splitlines() if line.strip().startswith("import")]
assert all("initSharedHeader" not in line for line in import_lines), (
"the view must not import the header boot — the shell's header boots "
"via the chat module (app.js) at shell boot"
)
assert 'import { fetchIsAdmin } from "./header.js";' in js, (
"the view imports ONLY the shared cached whoami promise"
)
mount_i = js.find("export async function mount(root)")
assert mount_i != -1, "mount(root) must be the module's entry"
gate_i = js.find("if (!(await fetchIsAdmin()))")
assert gate_i > mount_i, "the whoami gate must run in mount"
# The anonymous branch: gate in, table out, then a bare return —
# and NO fetch call anywhere inside it.
branch = boot[gate_i : boot.find("return;", gate_i)]
branch = js[gate_i : js.find("return;", gate_i)]
assert "fetch(" not in branch, "the anonymous branch must not fetch anything"
assert "tableWrap.hidden = true" in branch
assert "gateEl.hidden = false" in branch
# The admin path: the gate hides, then the list loads.
after = boot[boot.find("return;", gate_i):]
after = js[js.find("return;", gate_i):]
assert "gateEl.hidden = true" in after
assert "loadChats();" in after
@@ -346,9 +424,9 @@ def test_two_step_delete_confirm_pair() -> None:
yes_swap = fn.find("cell.replaceChildren(label, yes, no)")
assert fn.find("yes.focus()", yes_swap) > 0, "focus moves to Yes after the swap"
# No (and the restore helper) bring the Delete button back, focused.
restore_start = fn.find("function restoreDelete")
restore_end = fn.find("\n }", restore_start)
restore = fn[restore_start:restore_end]
# (Brace-balanced — since phase 76 task 03 the helper lives inside
# mount(root), so a line-leading-brace slice would not find it.)
restore = _fn(js, "restoreDelete")
assert "cell.replaceChildren(del)" in restore
assert "del.focus()" in restore
assert 'no.addEventListener("click", restoreDelete)' in fn