feat(ui): documents open in an almost-fullscreen modal instead of a new page — same-page overlay on chat + Sources, /document.html kept as the no-JS/direct-link fallback

tests/e2e/test_chat_persistence.py

@@ -158,7 +158,7 @@ def test_conversation_survives_reload(
     chip = page.locator(".msg.brain .source-chip", has_text="kubernetes.md")
     expect(chip).to_have_count(1)
     expect(chip.first).to_have_attribute("href", CHIP_HREF)
-    expect(chip.first).to_have_attribute("target", "_blank")
+    expect(chip.first).not_to_have_attribute("target")  # phase 26: modal, not a new tab
 
     # The restore is read-only: storage still holds the same two messages.
     assert [m["who"] for m in _stored_parsed(page)["messages"]] == ["user", "brain"]

tests/e2e/test_chat_rag.py

@@ -98,16 +98,16 @@ def test_on_topic_question_streams_grounded_answer(
 
     # Grounded: a kubernetes.md source chip renders under the bubble
     # (top-N docs can add more chips; the question's doc must be among them).
-    # Phase 10: chips open the document viewer in a new tab (encoded URL);
-    # phase 13 appends back=/ so the viewer's back button returns to chat.
+    # Phase 26: the chip opens the document in the SAME-PAGE modal — no new
+    # tab; the encoded href stays as the no-JS / context-menu escape hatch
+    # (phase 13's back=/ lets the viewer's back button return to chat).
     chip = page.locator(".msg.brain .source-chip", has_text="kubernetes.md")
     expect(chip).to_have_count(1)
     expect(chip.first).to_contain_text("kubernetes.md")
     expect(chip.first).to_have_attribute(
         "href", "/document.html?source=docs&path=homelab%2Fkubernetes.md&back=%2F"
     )
-    expect(chip.first).to_have_attribute("target", "_blank")
-    expect(chip.first).to_have_attribute("rel", "noopener")
+    expect(chip.first).not_to_have_attribute("target")  # phase 26: modal, not a new tab
 
     # Button recovers: enabled + "Send" (never stale).
     expect(page.locator("#send-btn")).to_be_enabled()

tests/e2e/test_document_back_navigation.py

@@ -6,21 +6,26 @@ Run in isolation (DB must be up: ``podman compose up -d db``):
 
     uv run pytest tests/e2e/test_document_back_navigation.py -v --no-cov
 
-Both entry points (chat source chips, Sources table links) open the viewer
-in a NEW tab, where there is no browser history — so the return target is
-carried in the viewer URL: chat chips append ``&back=%2F`` (resolves to
-"Chat"), Sources links omit the param (the viewer's default
-``/sources.html`` applies → "Sources"). The viewer only honors
-same-origin relative ``back`` values; everything else falls back to
-``/sources.html``.
+The viewer can be reached directly (no browser history to go back to),
+so the return target is carried in the viewer URL: chat chips append
+``&back=%2F`` (resolves to "Chat"), Sources links omit the param (the
+viewer's default ``/sources.html`` applies → "Sources"). The viewer only
+honors same-origin relative ``back`` values; everything else falls back
+to ``/sources.html``.
+
+Phase 26 adaptation: the chip/row-link LEFT click now opens the
+document in the same-page modal — no new tab is spawned. The encoded
+viewer URL survives as each link's ``href`` (the no-JS / context-menu
+"open in new tab" escape hatch), so the back contract is asserted on
+that exact href and verified by navigating to it directly.
 
 Test → story mapping (Playwright Mapping Rule):
-1. ``test_back_from_chat_returns_to_chat`` — question → source chip →
-   new tab with ``&back=%2F`` → back link href ``/`` labeled "Chat" →
-   click → the chat page.
-2. ``test_back_from_sources_returns_to_sources`` — Sources table link →
-   new tab without a ``back`` param → back link href ``/sources.html``
-   labeled "Sources" → click → the Sources page.
+1. ``test_back_from_chat_returns_to_chat`` — question → source chip href
+   (carries ``&back=%2F``) → viewer back link href ``/`` labeled "Chat"
+   → click → the chat page.
+2. ``test_back_from_sources_returns_to_sources`` — Sources table link
+   href (no ``back`` param) → back link href ``/sources.html`` labeled
+   "Sources" → click → the Sources page.
 3. ``test_malicious_back_param_is_rejected`` — absolute,
    protocol-relative, and ``javascript:`` ``back`` values all fall back
    to ``/sources.html`` (labeled "Sources", navigable).
@@ -106,30 +111,33 @@ def test_back_from_chat_returns_to_chat(
 
     chip = page.locator(".msg.brain .source-chip", has_text="kubernetes.md")
     expect(chip).to_have_count(1, timeout=30_000)
-    # Chat chips carry back=/ (encoded %2F) so the viewer knows where home is.
+    # Chat chips carry back=/ (encoded %2F) so the viewer knows where
+    # home is. Phase 26: the left click opens the same-page modal (no
+    # target=_blank); this href is what the no-JS / context-menu "open
+    # in a new tab" path reaches, so the back contract rides on it.
     expect(chip.first).to_have_attribute(
         "href", f"/document.html?source={DOC_SOURCE}&path={DOC_PATH}&back=%2F"
     )
+    expect(chip.first).not_to_have_attribute("target")  # phase 26: modal, not a new tab
 
-    with page.expect_popup() as popup_info:
-        chip.first.click()
-    viewer = popup_info.value
-    expect(viewer).to_have_url(
+    # The exact href asserted above (the no-JS / new-tab escape hatch).
+    page.goto(f"{app_url}/document.html?source={DOC_SOURCE}&path={DOC_PATH}&back=%2F")
+    expect(page).to_have_url(
         re.compile(
             re.escape(f"{app_url}/document.html?source={DOC_SOURCE}&path={DOC_PATH}&back=%2F")
         )
     )
     # The cited document actually rendered (this is the viewer, not an error).
-    expect(viewer.locator("#doc-title")).to_have_text(DOC_TITLE)
+    expect(page.locator("#doc-title")).to_have_text(DOC_TITLE)
     # Back link resolved to the chat page, labeled "Chat".
-    back = viewer.locator("#doc-back")
+    back = page.locator("#doc-back")
     expect(back).to_have_attribute("href", "/")
     expect(back).to_have_text("Chat")
 
     # Click: deterministic anchor navigation back to the chat page.
     back.click()
-    expect(viewer).to_have_url(f"{app_url}/")
-    expect(viewer.locator("#composer")).to_be_visible()
+    expect(page).to_have_url(f"{app_url}/")
+    expect(page.locator("#composer")).to_be_visible()
 
 
 # ---------------------------------------------------------------------------
@@ -148,24 +156,25 @@ def test_back_from_sources_returns_to_sources(
     link = row.locator("td:nth-child(2) a.doc-link")
     expect(link).to_have_count(1)
     # Sources links carry NO back param — the viewer's default target
-    # (/sources.html) applies.
+    # (/sources.html) applies. Phase 26: left click opens the modal;
+    # the href (no back param) is the no-JS / new-tab escape hatch.
     expect(link).to_have_attribute(
         "href", f"/document.html?source={DOC_SOURCE}&path={DOC_PATH}"
     )
+    expect(link).not_to_have_attribute("target")  # phase 26: modal, not a new tab
 
-    with page.expect_popup() as popup_info:
-        link.click()
-    viewer = popup_info.value
-    assert "back=" not in viewer.url, f"unexpected back param: {viewer.url}"
-    expect(viewer.locator("#doc-title")).to_have_text(DOC_TITLE)
+    # The exact href asserted above — no back param in the URL.
+    page.goto(f"{app_url}/document.html?source={DOC_SOURCE}&path={DOC_PATH}")
+    assert "back=" not in page.url, f"unexpected back param: {page.url}"
+    expect(page.locator("#doc-title")).to_have_text(DOC_TITLE)
     # Back link kept the default target, labeled "Sources".
-    back = viewer.locator("#doc-back")
+    back = page.locator("#doc-back")
     expect(back).to_have_attribute("href", "/sources.html")
     expect(back).to_have_text("Sources")
 
     back.click()
-    expect(viewer).to_have_url(f"{app_url}/sources.html")
-    expect(viewer.locator("#docs-table")).to_be_visible()
+    expect(page).to_have_url(f"{app_url}/sources.html")
+    expect(page.locator("#docs-table")).to_be_visible()
 
 
 # ---------------------------------------------------------------------------

tests/e2e/test_document_viewer.py

@@ -1,25 +1,32 @@
-"""Phase 10 E2E (Playwright): the clickable document viewer.
+"""Phase 26 E2E (Playwright): documents open in the almost-fullscreen
+modal — not in a new page.
 
-Story: ``.agent/user_stories/document-viewer.md``
+Story: ``.agent/user_stories/document-modal.md``
 Run in isolation (DB must be up: ``podman compose up -d db``):
 
     uv run pytest tests/e2e/test_document_viewer.py -v --no-cov
 
 Seeding reuses the real importer against ``tests/fixtures/docs/`` with the
-deterministic mock embeddings (same pattern as the earlier story suites).
+deterministic mock embeddings (same harness as the phase-10 suite — only
+the assertions changed: chips/row links now open the SAME-PAGE modal,
+no ``expect_popup``).
 
 Test → story mapping (Playwright Mapping Rule):
-1. ``test_source_chip_opens_document``       — chip → NEW TAB → viewer with
-   title + known content string + format badge.
-2. ``test_sources_row_links_to_viewer``      — Sources path link (yaml
-   fixture) → viewer with raw content in a ``pre``.
-3. ``test_markdown_renders_and_stays_xss_safe`` — md fixture containing
-   ``<script>alert(1)</script>`` renders as visible escaped text (no
-   execution).
-4. ``test_missing_doc_shows_not_found``      — unknown doc → not-found
-   state + Sources link; no console crash.
-5. ``test_viewer_theme_and_no_cdn``          — dark theme + every
-   ``script[src]`` / ``link[href]`` local or ``data:`` + a11y frame.
+1. ``test_source_chip_opens_modal`` — chat chip → modal opens in-page
+   (NO new tab, URL unchanged), title + ``.doc-md`` content + meta row.
+2. ``test_sources_row_opens_modal`` — Sources path link → modal, yaml in
+   ``<pre.doc-raw>``, mono font, URL unchanged.
+3. ``test_modal_closes_on_button_escape_and_backdrop`` — close via
+   ``#doc-modal-close``, via backdrop click, via ``Escape``.
+4. ``test_modal_focus_and_a11y`` — ``role="dialog"`` + ``aria-modal``,
+   focus inside the panel on open, close button has an ``aria-label``.
+5. ``test_modal_xss_safe`` — hostile md document opened through the modal
+   renders as escaped text; no dialog fires.
+6. ``test_standalone_page_still_works`` — the dedicated ``/document.html``
+   page keeps its phase-10 contract (title/content/badges, not-found,
+   dark theme, no-CDN, a11y frame, ≤736px md column).
+7. ``test_modal_theme_and_no_cdn`` — dark page background, the panel on
+   the Phase-08 surface colour, every asset same-origin or ``data:``.
 """
 from __future__ import annotations
 
@@ -83,60 +90,84 @@ def _reset_db(mock_port: int, seed: bool) -> ImportSummary | None:
     return _run_in_thread(_import_fixtures(mock_port))
 
 
+def _ask_for_chip(page: Page, app_url: str) -> Any:
+    """Drive one chat turn and return the kubernetes.md source chip."""
+    page.goto(app_url)
+    page.fill("#message-input", QUESTION)
+    page.click("#send-btn")
+    chip = page.locator(".msg.brain .source-chip", has_text="kubernetes.md")
+    expect(chip).to_have_count(1, timeout=30_000)
+    return chip
+
+
+def _assert_closed(page: Page) -> None:
+    """The modal is fully closed: the hidden attribute is back and the
+    overlay is gone from view."""
+    expect(page.locator("#doc-modal")).to_have_attribute("hidden", "")
+    expect(page.locator(".doc-modal")).not_to_be_visible()
+
+
 # ---------------------------------------------------------------------------
-# 1. Chat source chip → new tab → full document
+# 1. Chat source chip → SAME-PAGE modal (no new tab)
 # ---------------------------------------------------------------------------
 
 
-def test_source_chip_opens_document(
+def test_source_chip_opens_modal(
     page: Page, app_url: str, mock_llm: int, db_ready: None
 ) -> None:
     _reset_db(mock_llm, seed=True)
     page.set_default_timeout(30_000)
-    page.goto(app_url)
-
-    page.fill("#message-input", QUESTION)
-    page.click("#send-btn")
-
-    chip = page.locator(".msg.brain .source-chip", has_text="kubernetes.md")
-    expect(chip).to_have_count(1, timeout=30_000)
-    # New-tab contract: same-origin viewer URL, all query values encoded
-    # (the path's slashes come out as %2F — exactly why encoding matters),
-    # plus back=/ (phase 13) so the viewer's back button returns to chat.
+    chip = _ask_for_chip(page, app_url)
+    # The encoded viewer URL stays as the no-JS / context-menu escape
+    # hatch — but phase 26 removed target=_blank: the left click is
+    # intercepted and opens the modal in place.
     expect(chip.first).to_have_attribute(
         "href", "/document.html?source=docs&path=homelab%2Fkubernetes.md&back=%2F"
     )
-    expect(chip.first).to_have_attribute("target", "_blank")
-    expect(chip.first).to_have_attribute("rel", "noopener")
+    expect(chip.first).not_to_have_attribute("target")
 
-    with page.expect_popup() as popup_info:
-        chip.first.click()
-    viewer = popup_info.value
-    expect(viewer).to_have_url(
-        re.compile(
-            re.escape(
-                f"{app_url}/document.html?source=docs&path=homelab%2Fkubernetes.md&back=%2F"
-            )
-        )
+    before = len(page.context.pages)
+    chip.first.click()
+    # No new tab: the click must not have spawned a page.
+    assert len(page.context.pages) == before, "clicking a chip must not open a new tab"
+
+    # The almost-fullscreen modal becomes visible (hidden attribute gone).
+    expect(page.locator("#doc-modal")).not_to_have_attribute("hidden")
+    expect(page.locator(".doc-modal")).to_be_visible()
+    # "Almost-fullscreen": the panel is min(1100px, 96vw) × 92vh, centered
+    # (at a 1280px viewport the 1100px cap wins over 96vw = 1228.8px).
+    box = page.locator("#doc-modal-panel").bounding_box()
+    assert box is not None, "modal panel not rendered"
+    expected_w = min(1100, 0.96 * 1280)
+    expected_h = 0.92 * 800
+    assert abs(box["width"] - expected_w) < 2, f"panel width {box['width']} (want ~{expected_w})"
+    assert abs(box["height"] - expected_h) < 2, f"panel height {box['height']} (want ~{expected_h})"
+
+    # Same content the /document.html page renders: title, markdown in
+    # the centered .doc-md column (the modal's content target is
+    # #doc-modal-content — the modal variant of the page's #doc-content).
+    expect(page.locator("#doc-modal-title")).to_have_text("Kubernetes Homelab Cluster")
+    expect(page.locator("#doc-modal-content .doc-md")).to_have_count(1)
+    expect(page.locator("#doc-modal-content")).to_contain_text("Talos Linux on three nodes")
+    # Meta row mirrors the viewer: source · format · mono path · indexed · chunks.
+    expect(page.locator("#doc-modal-meta .doc-source-badge")).to_have_text("docs")
+    expect(page.locator("#doc-modal-meta .format-badge")).to_have_text("md")
+    expect(page.locator("#doc-modal-meta .doc-path")).to_have_text("homelab/kubernetes.md")
+    expect(page.locator("#doc-modal-meta .doc-indexed")).to_contain_text("Indexed")
+    assert re.fullmatch(
+        r"\d+ chunks?", page.locator("#doc-modal-meta .doc-chunks").inner_text()
     )
-    expect(viewer.locator("#doc-title")).to_have_text("Kubernetes Homelab Cluster")
-    # Meta row: source badge · format badge · mono path · indexed · chunks.
-    expect(viewer.locator("#doc-meta .doc-source-badge")).to_have_text("docs")
-    expect(viewer.locator("#doc-meta .format-badge")).to_have_text("md")
-    expect(viewer.locator("#doc-meta .doc-path")).to_have_text("homelab/kubernetes.md")
-    expect(viewer.locator("#doc-meta .doc-indexed")).to_contain_text("Indexed")
-    assert re.fullmatch(r"\d+ chunks?", viewer.locator("#doc-meta .doc-chunks").inner_text())
-    # Full document, rendered markdown in the centered column (not a pre).
-    expect(viewer.locator("#doc-content .doc-md")).to_have_count(1)
-    expect(viewer.locator("#doc-content")).to_contain_text("Talos Linux on three nodes")
+
+    # Still the chat page: no navigation happened.
+    assert page.url == app_url + "/", f"navigated away: {page.url}"
 
 
 # ---------------------------------------------------------------------------
-# 2. Sources table path link → viewer (yaml → raw pre)
+# 2. Sources table path link → same-page modal (yaml → raw pre)
 # ---------------------------------------------------------------------------
 
 
-def test_sources_row_links_to_viewer(
+def test_sources_row_opens_modal(
     page: Page, app_url: str, mock_llm: int, db_ready: None
 ) -> None:
     _reset_db(mock_llm, seed=True)
@@ -146,34 +177,119 @@ def test_sources_row_links_to_viewer(
     expect(row).to_have_count(1)
     link = row.locator("td:nth-child(2) a.doc-link")
     expect(link).to_have_count(1)
-    # Encoded URL: the slashes in the path value come out as %2F.
+    # Encoded URL kept as the escape hatch (slashes come out as %2F);
+    # no target=_blank any more.
     expect(link).to_have_attribute(
         "href",
         "/document.html?source=docs&path=homelab%2Fcontainer_gitlab%2Fgitlab-compose.yaml",
     )
-    expect(link).to_have_attribute("target", "_blank")
-    expect(link).to_have_attribute("rel", "noopener")
+    expect(link).not_to_have_attribute("target")
     expect(link).to_have_attribute("title", "homelab/container_gitlab/gitlab-compose.yaml")
 
-    with page.expect_popup() as popup_info:
-        link.click()
-    viewer = popup_info.value
-    expect(viewer.locator("#doc-title")).to_have_text("gitlab-compose")
-    expect(viewer.locator("#doc-meta .format-badge")).to_have_text("yaml")
+    before = len(page.context.pages)
+    link.click()
+    assert len(page.context.pages) == before, "clicking a row link must not open a new tab"
+
+    expect(page.locator(".doc-modal")).to_be_visible()
+    expect(page.locator("#doc-modal-title")).to_have_text("gitlab-compose")
+    expect(page.locator("#doc-modal-meta .format-badge")).to_have_text("yaml")
     # Non-markdown formats render as escaped monospace text in a pre.
-    pre = viewer.locator("#doc-content pre.doc-raw")
+    pre = page.locator("#doc-modal-content pre.doc-raw")
     expect(pre).to_have_count(1)
     expect(pre).to_contain_text("gitlab/gitlab-ce:17.2.1-ce.0")
     font = pre.evaluate("el => getComputedStyle(el).fontFamily")
     assert "mono" in font
 
+    # Still on the Sources page: no navigation happened.
+    assert page.url == app_url + "/sources.html", f"navigated away: {page.url}"
+
 
 # ---------------------------------------------------------------------------
-# 3. Markdown renders through the shared renderer and stays XSS-safe
+# 3. Close on button, backdrop, and Escape
 # ---------------------------------------------------------------------------
 
 
-def test_markdown_renders_and_stays_xss_safe(
+def test_modal_closes_on_button_escape_and_backdrop(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    _reset_db(mock_llm, seed=True)
+    page.set_default_timeout(30_000)
+    chip = _ask_for_chip(page, app_url)
+
+    def open_and_loaded() -> None:
+        chip.first.click()
+        expect(page.locator("#doc-modal-title")).to_have_text("Kubernetes Homelab Cluster")
+
+    # 1) The close button.
+    open_and_loaded()
+    page.click("#doc-modal-close")
+    _assert_closed(page)
+
+    # 2) The backdrop — a point outside the centered 96vw × 92vh panel
+    #    (panel starts at 4vh from the top / 2vw from the edge).
+    open_and_loaded()
+    page.locator("#doc-modal-backdrop").click(position={"x": 5, "y": 5})
+    _assert_closed(page)
+
+    # 3) Escape — the capture is document-level, so it works from any
+    #    focus position inside (or outside) the panel.
+    open_and_loaded()
+    page.keyboard.press("Escape")
+    _assert_closed(page)
+
+    # After closing, the page behind is untouched: chat is still there.
+    assert page.url == app_url + "/"
+    expect(page.locator("#composer")).to_be_visible()
+
+
+# ---------------------------------------------------------------------------
+# 4. Focus management + dialog a11y frame
+# ---------------------------------------------------------------------------
+
+
+def test_modal_focus_and_a11y(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    _reset_db(mock_llm, seed=True)
+    page.set_default_timeout(30_000)
+    chip = _ask_for_chip(page, app_url)
+
+    chip.first.click()
+    expect(page.locator("#doc-modal-title")).to_have_text("Kubernetes Homelab Cluster")
+
+    # The panel is a proper modal dialog, labelled by its title.
+    panel = page.locator("#doc-modal-panel")
+    expect(panel).to_have_attribute("role", "dialog")
+    expect(panel).to_have_attribute("aria-modal", "true")
+    expect(panel).to_have_attribute("aria-labelledby", "doc-modal-title")
+
+    # On open, focus moves into the dialog's content target.
+    focus_id = page.evaluate("() => document.activeElement && document.activeElement.id")
+    assert focus_id == "doc-modal-content", f"focus {focus_id!r} did not move into the modal"
+
+    # The close control carries an accessible name (icon-only button).
+    expect(page.locator("#doc-modal-close")).to_have_attribute("aria-label", "Close document")
+
+    # The "Full page" escape hatch is rebuilt to the same encoded viewer
+    # URL (no back param — the dedicated page's own default applies).
+    expect(page.locator("#doc-modal-open")).to_be_visible()
+    expect(page.locator("#doc-modal-open")).to_have_attribute(
+        "href", "/document.html?source=docs&path=homelab%2Fkubernetes.md"
+    )
+
+    # Closing returns focus to the triggering control.
+    page.keyboard.press("Escape")
+    _assert_closed(page)
+    focus_id = page.evaluate("() => document.activeElement && document.activeElement.className")
+    assert "source-chip" in (focus_id or ""), f"focus {focus_id!r} did not return to the chip"
+
+
+# ---------------------------------------------------------------------------
+# 5. Modal rendering stays XSS-safe (hostile md, opened via the modal)
+# ---------------------------------------------------------------------------
+
+
+def test_modal_xss_safe(
     page: Page, app_url: str, mock_llm: int, db_ready: None
 ) -> None:
     _reset_db(mock_llm, seed=True)
@@ -200,28 +316,46 @@ def test_markdown_renders_and_stays_xss_safe(
         d.dismiss()
 
     page.on("dialog", _catch_dialog)
-    page.goto(f"{app_url}/document.html?source=docs&path=notes%2Fxss-fixture.md")
 
-    expect(page.locator("#doc-title")).to_have_text("Xss Fixture")
+    # The Sources table lists every indexed document — the admin entry
+    # point into the modal for a doc the chat never cited.
+    login(page, app_url)
+    row = page.locator("#docs-tbody tr", has_text="xss-fixture.md")
+    expect(row).to_have_count(1)
+    row.locator("td:nth-child(2) a.doc-link").click()
+
+    expect(page.locator(".doc-modal")).to_be_visible()
+    expect(page.locator("#doc-modal-title")).to_have_text("Xss Fixture")
     # The tag shows up as VISIBLE, ESCAPED text — rendered, never executed.
-    expect(page.locator("#doc-content")).to_contain_text("<script>alert(1)</script>")
-    expect(page.locator("#doc-content")).to_contain_text("XSS-FIXTURE-MARKER")
-    assert page.locator("#doc-content script").count() == 0, "hostile script became live HTML"
+    expect(page.locator("#doc-modal-content")).to_contain_text("<script>alert(1)</script>")
+    expect(page.locator("#doc-modal-content")).to_contain_text("XSS-FIXTURE-MARKER")
+    assert page.locator("#doc-modal-content script").count() == 0, "hostile script became live HTML"
     assert dialogs == [], f"dialog fired — script executed: {dialogs}"
 
 
 # ---------------------------------------------------------------------------
-# 4. Missing document → designed not-found state, no console crash
+# 6. The dedicated /document.html page keeps its phase-10 contract
 # ---------------------------------------------------------------------------
 
 
-def test_missing_doc_shows_not_found(
+def test_standalone_page_still_works(
     page: Page, app_url: str, mock_llm: int, db_ready: None
 ) -> None:
     _reset_db(mock_llm, seed=True)
     errors: list[str] = []
     page.on("pageerror", lambda e: errors.append(str(e)))
 
+    # Direct link renders exactly as before (phase 10): title, meta row,
+    # markdown in the centered column.
+    page.goto(f"{app_url}/document.html?source=docs&path=homelab%2Fkubernetes.md")
+    expect(page.locator("#doc-title")).to_have_text("Kubernetes Homelab Cluster")
+    expect(page.locator("#doc-meta .doc-source-badge")).to_have_text("docs")
+    expect(page.locator("#doc-meta .format-badge")).to_have_text("md")
+    expect(page.locator("#doc-content .doc-md")).to_have_count(1)
+    expect(page.locator("#doc-content")).to_contain_text("Talos Linux on three nodes")
+
+    # Not-found state: an unknown pair AND missing params — no console
+    # crash, the designed card with the Sources link.
     page.goto(f"{app_url}/document.html?source=docs&path=definitely/not/here.md")
     expect(page.locator("#doc-title")).to_have_text("Document not found")
     card = page.locator("#doc-not-found")
@@ -229,29 +363,15 @@ def test_missing_doc_shows_not_found(
     expect(card).to_contain_text("Document not found")
     expect(card.locator("a.doc-open-sources")).to_have_attribute("href", "/sources.html")
     expect(page.locator("#doc-content")).to_be_empty()
-
-    # Missing params → the same designed state (no fetch, no crash).
     page.goto(f"{app_url}/document.html")
     expect(page.locator("#doc-not-found")).to_be_visible()
 
-    assert errors == [], f"console crashes: {errors}"
-
-
-# ---------------------------------------------------------------------------
-# 5. Dark theme + all assets local + a11y frame
-# ---------------------------------------------------------------------------
-
-
-def test_viewer_theme_and_no_cdn(page: Page, app_url: str, mock_llm: int, db_ready: None) -> None:
-    _reset_db(mock_llm, seed=True)
+    # Dark theme + all assets local + a11y frame + capped md column.
     page.goto(f"{app_url}/document.html?source=docs&path=homelab%2Fkubernetes.md")
     expect(page.locator("#doc-content .doc-md")).not_to_be_empty()
-
-    # Dark theme inherited from phase 08 (same sampling as that story).
     bg = page.evaluate("() => getComputedStyle(document.documentElement).backgroundColor")
     assert bg == "rgb(10, 14, 23)"
 
-    # No-CDN: every script/link reference is same-origin or a data: URI.
     refs = page.evaluate(
         """() => [...document.querySelectorAll("script[src], link[href]")]
             .map((el) => el.src || el.href)"""
@@ -260,8 +380,6 @@ def test_viewer_theme_and_no_cdn(page: Page, app_url: str, mock_llm: int, db_rea
     for ref in refs:
         assert ref.startswith(app_url) or ref.startswith("data:"), f"non-local: {ref}"
 
-    # A11y frame: landmarks, skip link, aria-live around the load→content
-    # swap, and focus moved to main on load.
     expect(page.locator("header.doc-header")).to_have_count(1)
     expect(page.locator("main#main")).to_have_count(1)
     expect(page.locator("footer.app-footer")).to_have_count(1)
@@ -272,3 +390,40 @@ def test_viewer_theme_and_no_cdn(page: Page, app_url: str, mock_llm: int, db_rea
     # Markdown column centered and capped at 46rem (736px at 16px root).
     box = page.locator("#doc-content .doc-md").bounding_box()
     assert box is not None and box["width"] <= 736 + 1
+
+    assert errors == [], f"console crashes: {errors}"
+
+
+# ---------------------------------------------------------------------------
+# 7. Modal theme + no CDN on the touched page
+# ---------------------------------------------------------------------------
+
+
+def test_modal_theme_and_no_cdn(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    _reset_db(mock_llm, seed=True)
+    page.set_default_timeout(30_000)
+    chip = _ask_for_chip(page, app_url)
+    chip.first.click()
+    expect(page.locator("#doc-modal-title")).to_have_text("Kubernetes Homelab Cluster")
+    expect(page.locator("#doc-modal-content .doc-md")).not_to_be_empty()
+
+    # Dark theme (phase 08): the page background is untouched, and the
+    # modal panel sits on the Phase-08 surface colour (#121a2e).
+    bg = page.evaluate("() => getComputedStyle(document.documentElement).backgroundColor")
+    assert bg == "rgb(10, 14, 23)"
+    surface = page.evaluate(
+        "() => getComputedStyle(document.querySelector('.doc-modal-panel')).backgroundColor"
+    )
+    assert surface == "rgb(18, 26, 46)", f"panel not on the Phase-08 surface: {surface}"
+
+    # No-CDN: every script/link reference on the chat page (the touched
+    # page) is same-origin or a data: URI — the modal adds no assets.
+    refs = page.evaluate(
+        """() => [...document.querySelectorAll("script[src], link[href]")]
+            .map((el) => el.src || el.href)"""
+    )
+    assert refs, "expected local asset references on the chat page"
+    for ref in refs:
+        assert ref.startswith(app_url) or ref.startswith("data:"), f"non-local: {ref}"

tests/integration/test_api.py

@@ -77,6 +77,7 @@ def test_styles_and_js_served(client) -> None:
     assert client.get("/assets/markdown.js").status_code == 200  # phase 10: shared renderer
     assert client.get("/assets/document.js").status_code == 200  # phase 10: viewer page
     assert client.get("/assets/login.js").status_code == 200  # phase 16: login page
+    assert client.get("/assets/document-modal.js").status_code == 200  # phase 26: modal module
 
 
 # Emoji code points banned from UI chrome (phase 08): the pictograph
@@ -112,6 +113,7 @@ def _find_emoji(text: str) -> list[str]:
         "/assets/markdown.js",
         "/assets/document.js",
         "/assets/login.js",  # phase 16
+        "/assets/document-modal.js",  # phase 26: the document modal module
         "/assets/styles.css",
     ],
 )

tests/unit/test_document_viewer.py

@@ -13,8 +13,11 @@ Frontend side:
   spaces/slashes) executed under node when available, plus source pins that
   run everywhere;
 * the shared-renderer extraction — ``markdown.js`` holds the renderer,
-  loaded by BOTH pages via a relative ``<script src>`` before the module
-  scripts.
+  loaded by the pages that use it via a relative ``<script src>`` before
+  the module scripts;
+* phase 26 — the shared ``renderDocument`` export in ``document.js``, the
+  import-safe page guard, the modal skeleton on chat + Sources, and the
+  modal module's close/focus/URL contract.
 """
 from __future__ import annotations
 
@@ -37,6 +40,9 @@ APP_JS = FRONTEND / "assets" / "app.js"
 SOURCES_JS = FRONTEND / "assets" / "sources.js"
 DOCUMENT_JS = FRONTEND / "assets" / "document.js"
 MARKDOWN_JS = FRONTEND / "assets" / "markdown.js"
+MODAL_JS = FRONTEND / "assets" / "document-modal.js"  # phase 26: the modal owner
+INDEX_HTML = FRONTEND / "index.html"
+SOURCES_HTML = FRONTEND / "sources.html"
 
 HAVE_NODE = shutil.which("node") is not None
 
@@ -160,30 +166,38 @@ def test_content_requires_both_params() -> None:
 
 def test_viewer_url_builder_present_in_chat_and_sources() -> None:
     """Both entry points (chat chips, Sources rows) build the same
-    encoded viewer URL and open it in a new tab with rel=noopener.
+    encoded viewer URL — kept as each link's ``href`` (no-JS /
+    context-menu escape hatch to the dedicated viewer).
 
     Phase 13: the chat builder additionally carries ``back=/`` (encoded
     %2F) so the viewer's back button returns to the chat; Sources links
-    intentionally omit the param (the viewer's /sources.html default)."""
+    intentionally omit the param (the viewer's /sources.html default).
+
+    Phase 26: the left-click no longer opens a new tab — it is
+    intercepted (preventDefault) and routed to openDocumentModal from
+    the shared modal module; no ``target="_blank"" survives on either
+    entry point."""
     for name, js in (("app.js", _read(APP_JS)), ("sources.js", _read(SOURCES_JS))):
         assert '"/document.html?source=" + encodeURIComponent(' in js, name
         assert '"&path=" + encodeURIComponent(' in js, name
+        assert 'target = "_blank"' not in js, f"{name}: phase 26 — no new tabs"
 
     app_js = _read(APP_JS)
     # Chat: 3-arg builder with back defaulting to the chat page.
     assert 'function documentUrl(source, path, back = "/")' in app_js
     assert '"&back=" + encodeURIComponent(back)' in app_js
     assert 'chip.href = documentUrl(s.source, s.path, "/")' in app_js
-    assert 'chip.target = "_blank"' in app_js
-    assert 'chip.rel = "noopener"' in app_js
+    assert 'chip.addEventListener("click"' in app_js
+    assert "e.preventDefault()" in app_js
+    assert "openDocumentModal(s.source, s.path, chip)" in app_js
 
     sources_js = _read(SOURCES_JS)
     # Sources: unchanged 2-arg builder — no back param in the URL.
     assert "function documentUrl(source, path)" in sources_js
     assert 'link.className = "doc-link"' in sources_js
     assert "link.href = documentUrl(d.source, d.path)" in sources_js
-    assert 'link.target = "_blank"' in sources_js
-    assert 'link.rel = "noopener"' in sources_js
+    assert 'link.addEventListener("click"' in sources_js
+    assert "openDocumentModal(d.source, d.path, link)" in sources_js
     # The full path stays the hover name on the ellipsized cell AND the link.
     assert "pathTd.title = d.path" in sources_js
     assert "link.title = d.path" in sources_js
@@ -269,6 +283,133 @@ def test_markdown_renderer_stays_xss_safe_and_unchanged() -> None:
     assert "<h3>Title</h3>" in html
 
 
+# ---------------------------------------------------------------------------
+# Phase 26 — shared renderDocument + the document modal wiring
+# ---------------------------------------------------------------------------
+
+
+def test_render_document_exported_and_modal_imports_it() -> None:
+    """Phase 26: document.js EXPORTS renderDocument(doc, { … }) — the
+    exact renderer the standalone page and the modal share (no drift).
+    The modal module imports it relatively, and BOTH page scripts import
+    the modal module relatively — no direct <script> tag (the header.js
+    single-evaluation design: esbuild inlines it into the page bundle,
+    one module instance per page)."""
+    doc_js = _read(DOCUMENT_JS)
+    # Task 03 signature: the page passes its #doc-title / #doc-meta /
+    # #doc-content elements under exactly these names.
+    assert "export function renderDocument(doc, { titleEl, metaEl, contentEl })" in doc_js, (
+        "document.js must export renderDocument(doc, { titleEl, metaEl, contentEl })"
+    )
+    # The standalone page renders through the SAME shared function with its
+    # own page elements (no second renderer copy).
+    assert "renderDocument(doc, { titleEl, metaEl, contentEl })" in doc_js
+    modal_js = _read(MODAL_JS)
+    assert 'from "./document.js"' in modal_js
+    assert "export function openDocumentModal(" in modal_js
+    assert "export function closeDocumentModal(" in modal_js
+    for name, js in (("app.js", _read(APP_JS)), ("sources.js", _read(SOURCES_JS))):
+        assert 'from "./document-modal.js"' in js, (
+            f"{name}: must import the modal module relatively"
+        )
+    for page in (INDEX_HTML, SOURCES_HTML):
+        text = _read(page)
+        assert not re.search(r"<script[^>]*document-modal\.js", text), (
+            f"{page.name}: no direct document-modal.js <script> tag "
+            "(single-evaluation design — the page script imports it)"
+        )
+
+
+def test_document_js_page_init_is_import_safe() -> None:
+    """Phase 26: the /document.html-specific init (back-link resolution,
+    whoami, content load) runs ONLY when #doc-title exists — the modal
+    module's `import { renderDocument } from "./document.js"` on the
+    chat/sources pages must have no side effects."""
+    js = _read(DOCUMENT_JS)
+    guard = js.find('querySelector("#doc-title")')
+    back_href = js.find("backLink.href = backTarget")
+    load_call = js.rfind("load();")
+    assert 0 < guard < back_href < load_call, (
+        "the viewer-page init must sit inside the #doc-title guard "
+        "(after it, and load() must be the guarded entry point)"
+    )
+
+
+def test_both_pages_carry_the_modal_skeleton() -> None:
+    """Phase 26: chat AND Sources ship the same modal skeleton (the
+    task-01 markup) — the a11y frame included: role=dialog +
+    aria-modal, a labelled close control, a focusable content target
+    (tabindex=-1), and a role=status announcer. Hidden by default —
+    inert until JS opens it."""
+    for page in (INDEX_HTML, SOURCES_HTML):
+        text = _read(page)
+        assert '<div class="doc-modal" id="doc-modal" hidden>' in text, page.name
+        assert 'id="doc-modal-backdrop"' in text, page.name
+        assert 'id="doc-modal-panel"' in text, page.name
+        assert 'role="dialog"' in text and 'aria-modal="true"' in text, page.name
+        assert 'id="doc-modal-title"' in text, page.name
+        assert 'id="doc-modal-meta"' in text, page.name
+        assert 'id="doc-modal-desc"' in text, page.name
+        assert 'id="doc-modal-open"' in text, page.name
+        assert re.search(r'id="doc-modal-content"[^>]*tabindex="-1"', text), page.name
+        assert re.search(
+            r'id="doc-modal-close"[^>]*aria-label="Close document"', text
+        ), page.name
+
+
+def test_sources_page_loads_markdown_before_its_module() -> None:
+    """Phase 26: the modal renders md documents on the Sources page too —
+    so sources.html loads the classic markdown.js (global renderMarkdown)
+    via a relative <script src> BEFORE its module script, exactly like
+    index.html does."""
+    html = _read(SOURCES_HTML)
+    assert re.search(r'<script src="assets/markdown\.js"></script>', html)
+    assert html.index('src="assets/markdown.js"') < html.index('type="module"'), (
+        "sources.html: markdown.js must load before the module script"
+    )
+
+
+def test_modal_close_contract_pins() -> None:
+    """Phase 26: the modal closes on the close button, on backdrop
+    click, and on Escape (captured document-level, so it works from any
+    focus position); focus returns to the triggering control
+    (best-effort); the fetch goes to the stateless content endpoint with
+    the same percent-encoding the page uses, and success renders through
+    the shared renderDocument; the "Full page" link is rebuilt on open."""
+    js = _read(MODAL_JS)
+    assert 'e.key === "Escape"' in js
+    assert 'addEventListener("keydown"' in js
+    assert "backdropEl.addEventListener(\"click\", closeDocumentModal)" in js
+    assert "closeEl.addEventListener(\"click\", closeDocumentModal)" in js
+    assert "triggerEl.focus" in js  # best-effort focus restore
+    assert '"/api/documents/content?source=" + encodeURIComponent(' in js
+    assert '"&path=" + encodeURIComponent(' in js
+    # The shared renderer (not a copy), called with the modal's own
+    # #doc-modal-title / #doc-modal-meta / #doc-modal-content elements.
+    assert "renderDocument(doc, { titleEl, metaEl, contentEl })" in js
+    assert 'openEl.href = fullPageUrl(source, path)' in js
+
+
+@pytest.mark.skipif(not HAVE_NODE, reason="node not available")
+def test_modal_url_builders_encode_like_the_page() -> None:
+    """Behavioral check (node) of the modal's own URL builders: the
+    content fetch and the "Full page" href must come out percent-encoded
+    exactly like the page's builders (slashes/spaces in real paths)."""
+    js = _read(MODAL_JS)
+    content_fn = _extract_function(js, "contentUrl")
+    full_fn = _extract_function(js, "fullPageUrl")
+    out = _run_node(
+        content_fn
+        + full_fn
+        + "\nconsole.log(contentUrl('Homelab', 'notes/my file.yaml'));\n"
+        + "console.log(fullPageUrl('H omelab', 'a/b.md'));"
+    )
+    assert out.splitlines() == [
+        "/api/documents/content?source=Homelab&path=notes%2Fmy%20file.yaml",
+        "/document.html?source=H%20omelab&path=a%2Fb.md",
+    ]
+
+
 def test_viewer_js_rendering_contracts() -> None:
     """document.js: raw formats go in via textContent (never parsed as
     HTML), markdown via the shared renderer, 404 → designed not-found