Merge pull request 'Read and triage unread updates inside mobile My Work' (#152) from timmy/151-mobile-update-reader into main

2026-08-07 00:36:31 +00:00 · 2026-08-07 00:36:31 +00:00 · 62ebabb132
commit 62ebabb132
parent 5b864c028e f7073e1393
7 changed files with 628 additions and 8 deletions
--- a/frontend/index.html
+++ b/frontend/index.html
@ -66,6 +66,7 @@ textarea { resize: vertical; min-height: 120px; }
 .my-work-card:hover { border-color:var(--accent); }
 .my-work-card-title { display:block; margin:5px 0; font-weight:650; }
 .mark-update-read { min-height:44px; width:100%; }
+.read-update { min-height:44px; width:100%; }
 .load-more-notifications { min-height:44px; width:100%; margin-top:10px; }
 .load-more-notifications[hidden] { display:none; }
 .my-work-bulk { position:sticky; bottom:0; z-index:4; margin:10px -4px -12px; padding:10px 4px; padding-bottom:calc(10px + env(safe-area-inset-bottom)); background:rgba(11,21,38,.98); border-top:1px solid #2a496e; }
@ -102,6 +103,15 @@ textarea { resize: vertical; min-height: 120px; }
 .review-diff-note, .review-diff-empty { display:block; padding:8px; color:#fcd34d; white-space:normal; }
 .review-action { min-height:44px; }
 .review-retry { min-height:44px; margin-top:10px; }
+.update-sheet { position:fixed; inset:0; z-index:55; display:none; justify-content:flex-end; background:rgba(5,12,21,.72); backdrop-filter:blur(4px); }
+.update-sheet.open { display:flex; }
+.update-sheet-panel { width:min(560px,100%); height:100%; overflow:auto; padding:18px; background:#0b1526; border-left:1px solid #2a496e; }
+.update-sheet-header { display:flex; align-items:center; justify-content:space-between; gap:10px; }
+.update-sheet-content { overflow-wrap:anywhere; white-space:pre-wrap; }
+.update-sheet-actions { position:sticky; bottom:0; z-index:3; display:grid; gap:8px; margin-top:14px; padding:10px 4px; padding-bottom:calc(10px + env(safe-area-inset-bottom)); background:rgba(11,21,38,.98); border-top:1px solid #2a496e; }
+.update-sheet-actions button, .update-sheet-actions a { min-height:44px; display:flex; align-items:center; justify-content:center; }
+.update-sheet-actions a { border:1px solid #60a5fa; border-radius:10px; font-weight:700; }
+.update-retry { min-height:44px; width:100%; margin-top:10px; }
@media (max-width: 600px) {
  header { align-items:flex-start; }
  .my-work { margin:0; }
@ -109,6 +119,7 @@ textarea { resize: vertical; min-height: 120px; }
  .work-filters { width:100%; }
  .work-filter { flex:1 1 calc(50% - 8px); }
  .review-sheet-panel { width:100%; border-left:0; padding:14px; }
+  .update-sheet-panel { width:100%; border-left:0; padding:14px; }
 }
 .obi { width:14px; height:14px; background: url('data:image/svg+xml;utf8,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22><rect width=%2224%22 height=%2224%22 rx=%226%22 fill=%22%230b1526%22/><circle cx=%2212%22 cy=%2212%22 r=%226%22 fill=%22%2360a5fa%22/></svg>') center/contain no-repeat; display:inline-block; }
 .footer { padding: 12px; text-align: center; color:#4e6b8a; font-size:12px; }
@ -235,6 +246,35 @@ textarea { resize: vertical; min-height: 120px; }
  </div>
 </div>

+<div class="update-sheet" id="update-sheet" role="dialog" aria-modal="true" aria-labelledby="update-sheet-title">
+  <section class="update-sheet-panel">
+    <div class="update-sheet-header">
+      <div>
+        <div class="small" id="update-sheet-key"></div>
+        <h3 id="update-sheet-title">Unread update</h3>
+      </div>
+      <button id="keep-update-unread" type="button">Keep unread</button>
+    </div>
+    <div id="update-sheet-status" class="small" aria-live="polite">Choose an update.</div>
+    <button class="update-retry" id="retry-update-load" type="button" hidden>Retry loading update</button>
+    <div class="row">
+      <span class="pill" id="update-subject-type">Update</span>
+      <span class="pill" id="update-subject-state"></span>
+    </div>
+    <h2>Latest comment</h2>
+    <div class="small" id="update-comment-meta"></div>
+    <p class="update-sheet-content" id="update-comment-body"></p>
+    <details>
+      <summary><h2>Subject context</h2></summary>
+      <p class="update-sheet-content muted" id="update-subject-body"></p>
+    </details>
+    <div class="update-sheet-actions">
+      <button id="mark-update-read-next" type="button">Mark read &amp; next</button>
+      <a id="open-update-gitea" href="#" target="_blank" rel="noopener noreferrer">Open in Gitea</a>
+    </div>
+  </section>
+</div>
+
 <div class="review-sheet" id="review-sheet" role="dialog" aria-modal="true" aria-labelledby="review-sheet-title">
  <section class="review-sheet-panel">
    <div class="review-sheet-header">
@ -327,6 +367,8 @@ textarea { resize: vertical; min-height: 120px; }
  let hasContextSnapshot = false;
  let selectedReview = null;
  let reviewTrigger = null;
+  let selectedUpdate = null;
+  let updateTrigger = null;
  let progress = null;
  let draft = null;
  let reviewFiles = [];
@ -382,6 +424,15 @@ textarea { resize: vertical; min-height: 120px; }
    return payload;
  }

+  async function fetchNotificationDetail(notificationId) {
+    const response = await fetch('api/v1/notifications/' + encodeURIComponent(notificationId), {
+      headers: { Accept: 'application/json' },
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok) throw new Error(payload.error || 'Loading the update failed.');
+    return payload;
+  }
+
  const notificationAcknowledger = createNotificationAcknowledger({
    markRead: markNotificationRead,
    onItems: items => {
@ -417,6 +468,51 @@ textarea { resize: vertical; min-height: 120px; }
    },
    onStatus: message => { qs('#my-work-action-status').textContent = message; },
  });
+  const notificationReader = createNotificationReader({
+    load: fetchNotificationDetail,
+    markRead: markNotificationRead,
+    onOpen: item => {
+      selectedUpdate = item;
+      qs('#update-sheet').classList.add('open');
+      qs('#update-sheet-key').textContent = item.key || '';
+      qs('#update-sheet-title').textContent = item.title || 'Unread update';
+      qs('#update-comment-meta').textContent = '';
+      qs('#update-comment-body').textContent = '';
+      qs('#update-subject-body').textContent = '';
+      qs('#update-subject-type').textContent = item.subject_type || 'Update';
+      qs('#update-subject-state').textContent = item.state || '';
+      qs('#open-update-gitea').href = item.url || '#';
+      qs('#retry-update-load').hidden = true;
+      qs('#keep-update-unread').focus();
+    },
+    onDetail: detail => {
+      const comment = detail.latest_comment || {};
+      qs('#update-sheet-title').textContent = detail.title || 'Unread update';
+      qs('#update-subject-type').textContent = detail.subject_type || 'Update';
+      qs('#update-subject-state').textContent = detail.state || '';
+      qs('#update-comment-meta').textContent = comment.author ?
+        comment.author + (comment.created_at ? ' · ' + fmt(comment.created_at) : '') :
+        (comment.created_at ? fmt(comment.created_at) : 'No comment author reported');
+      qs('#update-comment-body').textContent = comment.body || 'No comment body was provided.';
+      qs('#update-subject-body').textContent = detail.subject_body || 'No subject context was provided.';
+      qs('#open-update-gitea').href = detail.url || selectedUpdate?.url || '#';
+      qs('#retry-update-load').hidden = true;
+    },
+    onItems: items => {
+      const readId = selectedUpdate?.notification_id;
+      lastMyWork = items;
+      if (Number.isInteger(readId)) {
+        lastNotifications = lastNotifications.filter(item => item.id !== readId);
+      }
+      refreshMyWorkView();
+    },
+    onStatus: message => {
+      qs('#update-sheet-status').textContent = message;
+      qs('#retry-update-load').hidden = !message.startsWith('Could not load update.');
+      if (message === 'Inbox cleared.') qs('#my-work-action-status').textContent = message;
+    },
+    onClose: () => closeUpdateSheet(false),
+  });

  function renderContextSnapshot(data) {
    liveMode = true;
@ -481,6 +577,7 @@ textarea { resize: vertical; min-height: 120px; }
  function renderMyWork() {
    const visible = filterMyWork(lastMyWork, selectedWorkFilter);
    qs('#my-work-list').innerHTML = visible.length ? visible.map(item => {
+      const index = lastMyWork.findIndex(candidate => candidate.key === item.key && candidate.kind === item.kind);
      const contents =
      '<span class="small">' + escapeHtml(item.key) + ' · ' + escapeHtml(item.kind === 'pull' ? 'PR' : (item.kind === 'update' ? 'Update' : 'Issue')) + '</span>' +
      '<span class="my-work-card-title">' + escapeHtml(item.title) + '</span>' +
@ -489,15 +586,24 @@ textarea { resize: vertical; min-height: 120px; }
      (item.updated_at ? '<span class="small"> · Updated ' + escapeHtml(fmt(item.updated_at)) + '</span>' : '');
      const markRead = item.has_update && Number.isInteger(item.notification_id) ?
        '<button class="mark-update-read" data-notification-id="' + item.notification_id + '">Mark read</button>' : '';
+      const readUpdate = item.has_update && Number.isInteger(item.notification_id) ?
+        '<button class="read-update" data-update-index="' + index + '">Read update</button>' : '';
      if (item.is_review) {
-        const index = lastMyWork.findIndex(candidate => candidate.key === item.key && candidate.kind === item.kind);
-        return '<article class="my-work-card"><button class="my-work-card-main review-trigger" data-review-index="' + index + '">' + contents + '</button>' + markRead + '</article>';
+        return '<article class="my-work-card"><button class="my-work-card-main review-trigger" data-review-index="' + index + '">' + contents + '</button>' + readUpdate + markRead + '</article>';
      }
-      return '<article class="my-work-card"><a class="my-work-card-main" href="' + escAttr(item.url) + '" target="_blank" rel="noopener noreferrer">' + contents + '</a>' + markRead + '</article>';
+      return '<article class="my-work-card"><a class="my-work-card-main" href="' + escAttr(item.url) + '" target="_blank" rel="noopener noreferrer">' + contents + '</a>' + readUpdate + markRead + '</article>';
    }).join('') : '<div class="muted">No ' + (selectedWorkFilter === 'review' ? 'reviews' : (selectedWorkFilter === 'update' ? 'unread updates' : (selectedWorkFilter === 'all' ? 'work' : selectedWorkFilter + ' items'))) + '.</div>';
    document.querySelectorAll('[data-review-index]').forEach(button => {
      button.addEventListener('click', () => openReviewSheet(lastMyWork[Number(button.dataset.reviewIndex)], button));
    });
+    document.querySelectorAll('[data-update-index]').forEach(button => {
+      button.addEventListener('click', () => {
+        const item = lastMyWork[Number(button.dataset.updateIndex)];
+        if (!item) return;
+        updateTrigger = button;
+        notificationReader.open(item, lastMyWork);
+      });
+    });
    document.querySelectorAll('[data-notification-id]').forEach(button => {
      button.addEventListener('click', async () => {
        const notificationId = Number(button.dataset.notificationId);
@ -652,6 +758,13 @@ textarea { resize: vertical; min-height: 120px; }
    if (reviewTrigger?.isConnected) reviewTrigger.focus();
  }

+  function closeUpdateSheet(restoreTrigger = true) {
+    qs('#update-sheet').classList.remove('open');
+    selectedUpdate = null;
+    if (restoreTrigger && updateTrigger?.isConnected) updateTrigger.focus();
+    else qs('[data-work-filter="update"]')?.focus();
+  }
+
  function markMyWorkStale() {
    qs('#my-work').setAttribute('data-stale', 'true');
    qs('#my-work-status').textContent = lastMyWork.length ?
@ -793,6 +906,18 @@ textarea { resize: vertical; min-height: 120px; }
  qs('#cmd-input').addEventListener('input', (e) => renderCommands(e.target.value));
  document.addEventListener('keydown', (e) => { if ((e.metaKey||e.ctrlKey) && e.key==='k') { e.preventDefault(); qs('#cmd-palette').classList.toggle('open'); if(qs('#cmd-palette').classList.contains('open')){ qs('#cmd-input').focus(); renderCommands(''); } } });
  qs('#close-whiteboard').addEventListener('click', () => closeModal('whiteboard-modal'));
+  qs('#keep-update-unread').addEventListener('click', () => closeUpdateSheet(true));
+  qs('#retry-update-load').addEventListener('click', () => {
+    if (selectedUpdate) notificationReader.open(selectedUpdate, lastMyWork);
+  });
+  qs('#mark-update-read-next').addEventListener('click', async () => {
+    qs('#mark-update-read-next').disabled = true;
+    try {
+      await notificationReader.markReadAndNext(lastMyWork);
+    } finally {
+      qs('#mark-update-read-next').disabled = false;
+    }
+  });
  qs('#close-review-sheet').addEventListener('click', closeReviewSheet);
  qs('#retry-review-load').addEventListener('click', () => {
    if (selectedReview) openReviewSheet(selectedReview, reviewTrigger);
--- a/frontend/my-work.js
+++ b/frontend/my-work.js
@ -169,6 +169,63 @@ function createNotificationPager({ load, onNotifications, onPagination, onStatus
  };
 }

+function createNotificationReader({ load, markRead, onOpen, onDetail, onItems, onStatus, onClose }) {
+  let selected = null;
+  let loadVersion = 0;
+  let marking = false;
+
+  async function open(item) {
+    selected = item;
+    const version = ++loadVersion;
+    onOpen(item);
+    onStatus('Loading update…');
+    try {
+      const detail = await load(item.notification_id);
+      if (selected !== item || version !== loadVersion) return false;
+      onDetail(detail);
+      onStatus('Update ready.');
+      return true;
+    } catch (_error) {
+      if (selected === item && version === loadVersion) {
+        onStatus('Could not load update. Retry or open it in Gitea.');
+      }
+      return false;
+    }
+  }
+
+  return {
+    open,
+    async markReadAndNext(items) {
+      if (!selected || marking) return false;
+      const current = selected;
+      marking = true;
+      onStatus('Marking update read…');
+      try {
+        await markRead(current.notification_id);
+        const updated = acknowledgeNotification(items, current.notification_id);
+        onItems(updated);
+        const currentIndex = items.indexOf(current);
+        const remaining = items.slice(currentIndex + 1).concat(items.slice(0, currentIndex));
+        const next = remaining.find(item =>
+          item && item.has_update && Number.isInteger(item.notification_id)
+        );
+        if (next) await open(next);
+        else {
+          selected = null;
+          onClose();
+          onStatus('Inbox cleared.');
+        }
+        return { items: updated, next: next || null };
+      } catch (_error) {
+        onStatus('Could not mark update read. Retry.');
+        return false;
+      } finally {
+        marking = false;
+      }
+    },
+  };
+}
+
 function filterMyWork(items, selectedFilter) {
  if (selectedFilter === 'all') return items;
  if (selectedFilter === 'review') return items.filter((item) => item.is_review);
@ -205,5 +262,6 @@ if (typeof module !== 'undefined' && module.exports) {
  buildMyWork.notificationIds = notificationIds;
  buildMyWork.createBulkNotificationAcknowledger = createBulkNotificationAcknowledger;
  buildMyWork.createNotificationPager = createNotificationPager;
+  buildMyWork.createNotificationReader = createNotificationReader;
  module.exports = buildMyWork;
 }
--- a/src/gitea_proxy.py
+++ b/src/gitea_proxy.py
@ -211,6 +211,74 @@ async def mark_notification_read(thread_id: int) -> None:
    response.raise_for_status()


+def _gitea_api_path(value: Any) -> str:
+    if not isinstance(value, str):
+        return ""
+    parsed = urlsplit(value)
+    configured = urlsplit(GITEA_URL)
+    prefix = "/api/v1/"
+    if (
+        parsed.scheme not in {"http", "https"}
+        or parsed.netloc != configured.netloc
+        or not parsed.path.startswith(prefix)
+    ):
+        return ""
+    return parsed.path[len(prefix):] + (("?" + parsed.query) if parsed.query else "")
+
+
+async def notification_detail(thread_id: int) -> dict:
+    thread = await fetch(f"notifications/threads/{thread_id}")
+    if not isinstance(thread, dict):
+        raise ValueError("Gitea notification thread response was not an object")
+    repository_value = thread.get("repository")
+    repository = repository_value if isinstance(repository_value, dict) else {}
+    subject_value = thread.get("subject")
+    subject = subject_value if isinstance(subject_value, dict) else {}
+    subject_path = _gitea_api_path(subject.get("url"))
+    comment_path = _gitea_api_path(subject.get("latest_comment_url"))
+    subject_detail = await fetch(subject_path) if subject_path else {}
+    comment = await fetch(comment_path) if comment_path else {}
+    subject_detail = subject_detail if isinstance(subject_detail, dict) else {}
+    comment = comment if isinstance(comment, dict) else {}
+    user_value = comment.get("user")
+    user = user_value if isinstance(user_value, dict) else {}
+    subject_url = _safe_web_url(subject.get("html_url"))
+    latest_url = _safe_web_url(comment.get("html_url")) or _safe_web_url(
+        subject.get("latest_comment_html_url")
+    )
+    return {
+        "id": thread_id,
+        "repository": repository.get("full_name", "")
+        if isinstance(repository.get("full_name"), str)
+        else "",
+        "title": subject.get("title", "")
+        if isinstance(subject.get("title"), str)
+        else "",
+        "subject_type": subject.get("type", "Update")
+        if isinstance(subject.get("type"), str)
+        else "Update",
+        "state": subject.get("state", "")
+        if isinstance(subject.get("state"), str)
+        else "",
+        "url": latest_url or subject_url,
+        "subject_body": subject_detail.get("body", "")
+        if isinstance(subject_detail.get("body"), str)
+        else "",
+        "latest_comment": {
+            "author": user.get("login", "")
+            if isinstance(user.get("login"), str)
+            else "",
+            "body": comment.get("body", "")
+            if isinstance(comment.get("body"), str)
+            else "",
+            "created_at": comment.get("created_at", "")
+            if isinstance(comment.get("created_at"), str)
+            else "",
+            "url": latest_url,
+        },
+    }
+
+
 async def pull_requests() -> list[dict]:
    assigned, review_requested = await asyncio.gather(
        fetch("repos/issues/search?state=open&assigned=true&type=pulls&limit=50"),
--- a/src/main.py
+++ b/src/main.py
@ -17,6 +17,7 @@ from src.gitea_proxy import (
    is_requested_review,
    issues,
    mark_notification_read,
+    notification_detail,
    notifications,
    pull_requests,
    pull_review_detail,
@ -54,6 +55,7 @@ READINESS_TIMEOUT_SECONDS = 5.0
 REVIEW_DETAIL_TIMEOUT_SECONDS = 5.0
 NOTIFICATION_MUTATION_TIMEOUT_SECONDS = 5.0
 NOTIFICATION_PAGE_TIMEOUT_SECONDS = 5.0
+NOTIFICATION_DETAIL_TIMEOUT_SECONDS = 5.0
 BULK_NOTIFICATION_CONCURRENCY = 5
 BULK_NOTIFICATION_DEADLINE_SECONDS = 6.0
 LIVE_SNAPSHOT_FRESHNESS_SECONDS = 8.0
@ -140,13 +142,10 @@ app.include_router(frontend_router)
@app.middleware("http")
 async def prevent_live_api_caching(request, call_next):
    response = await call_next(request)
-    if request.url.path in {"/api/v1/context", "/api/v1/events", "/api/v1/live", "/api/v1/notifications"} or (
+    if request.url.path in {"/api/v1/context", "/api/v1/events", "/api/v1/live"} or (
        request.url.path.startswith("/api/v1/repos/")
        and request.url.path.endswith("/review")
-    ) or (
-        request.url.path.startswith("/api/v1/notifications/")
-        and request.url.path.endswith("/read")
-    ):
+    ) or request.url.path.startswith("/api/v1/notifications"):
        response.headers["Cache-Control"] = "no-store"
    return response

@ -581,6 +580,30 @@ async def notification_page(page: int = Query(default=1, ge=1)) -> JSONResponse:
    return JSONResponse(result)


+@app.get("/api/v1/notifications/{thread_id}")
+async def notification_thread_detail(
+    thread_id: int = PathParam(gt=0),
+) -> JSONResponse:
+    try:
+        result = await asyncio.wait_for(
+            notification_detail(thread_id),
+            timeout=NOTIFICATION_DETAIL_TIMEOUT_SECONDS,
+        )
+    except TimeoutError:
+        return JSONResponse(
+            {"error": "Loading the update timed out. Please retry."},
+            status_code=503,
+            headers={"Retry-After": "1"},
+        )
+    except Exception:
+        return JSONResponse(
+            {"error": "The update is temporarily unavailable. Please retry."},
+            status_code=503,
+            headers={"Retry-After": "1"},
+        )
+    return JSONResponse(result)
+
+
@app.patch("/api/v1/notifications/{thread_id}/read")
 async def read_notification(thread_id: int = PathParam(gt=0)) -> JSONResponse:
    try:
--- a/tests/test_gitea_notifications.py
+++ b/tests/test_gitea_notifications.py
@ -110,3 +110,93 @@ async def test_unread_notifications_are_normalized_for_mobile_handoff():
 async def test_notification_collection_rejects_non_list_payload():
    with pytest.raises(ValueError, match="notification response was not a list"):
        gitea_proxy._normalize_notifications({"message": "unexpected"})
+
+
+@pytest.mark.anyio
+async def test_notification_detail_loads_subject_and_latest_comment_for_inbox_reader():
+    requests = []
+
+    def upstream(request):
+        requests.append(str(request.url))
+        if request.url.path.endswith("/notifications/threads/42"):
+            return httpx.Response(200, json={
+                "id": 42,
+                "repository": {"full_name": "stackchain/api"},
+                "subject": {
+                    "title": "Retry failed deploy",
+                    "type": "Issue",
+                    "state": "open",
+                    "url": "http://127.0.0.1:3000/api/v1/repos/stackchain/api/issues/7",
+                    "latest_comment_url": "http://127.0.0.1:3000/api/v1/repos/stackchain/api/issues/comments/9",
+                    "html_url": "https://forge.example/stackchain/api/issues/7",
+                    "latest_comment_html_url": "https://forge.example/stackchain/api/issues/7#issuecomment-9",
+                },
+            })
+        if request.url.path.endswith("/issues/7"):
+            return httpx.Response(200, json={"body": "Deploy fails after **three** retries."})
+        if request.url.path.endswith("/issues/comments/9"):
+            return httpx.Response(200, json={
+                "body": "Logs point to the worker timeout.",
+                "created_at": "2026-08-06T12:30:00Z",
+                "user": {"login": "alexander"},
+                "html_url": "https://forge.example/stackchain/api/issues/7#issuecomment-9",
+            })
+        return httpx.Response(404)
+
+    gitea_proxy.start_client(transport=httpx.MockTransport(upstream))
+    try:
+        result = await gitea_proxy.notification_detail(42)
+    finally:
+        await gitea_proxy.stop_client()
+
+    assert requests == [
+        "http://127.0.0.1:3000/api/v1/notifications/threads/42",
+        "http://127.0.0.1:3000/api/v1/repos/stackchain/api/issues/7",
+        "http://127.0.0.1:3000/api/v1/repos/stackchain/api/issues/comments/9",
+    ]
+    assert result == {
+        "id": 42,
+        "repository": "stackchain/api",
+        "title": "Retry failed deploy",
+        "subject_type": "Issue",
+        "state": "open",
+        "url": "https://forge.example/stackchain/api/issues/7#issuecomment-9",
+        "subject_body": "Deploy fails after **three** retries.",
+        "latest_comment": {
+            "author": "alexander",
+            "body": "Logs point to the worker timeout.",
+            "created_at": "2026-08-06T12:30:00Z",
+            "url": "https://forge.example/stackchain/api/issues/7#issuecomment-9",
+        },
+    }
+
+
+@pytest.mark.anyio
+async def test_notification_detail_never_follows_foreign_api_urls():
+    requests = []
+
+    def upstream(request):
+        requests.append(str(request.url))
+        return httpx.Response(200, json={
+            "id": 42,
+            "repository": {"full_name": "stackchain/api"},
+            "subject": {
+                "title": "Suspicious update",
+                "url": "https://evil.example/api/v1/user",
+                "latest_comment_url": "https://evil.example/api/v1/admin/users",
+                "html_url": "javascript:alert(1)",
+            },
+        })
+
+    gitea_proxy.start_client(transport=httpx.MockTransport(upstream))
+    try:
+        result = await gitea_proxy.notification_detail(42)
+    finally:
+        await gitea_proxy.stop_client()
+
+    assert requests == [
+        "http://127.0.0.1:3000/api/v1/notifications/threads/42"
+    ]
+    assert result["url"] == ""
+    assert result["subject_body"] == ""
+    assert result["latest_comment"]["body"] == ""
--- a/tests/test_my_work.py
+++ b/tests/test_my_work.py
@ -384,6 +384,165 @@ pager.loadMore([{{id:1}}]).then(result =>
    }


+def test_notification_reader_marks_current_read_and_opens_next_update():
+    script = f"""
+const buildMyWork = require({json.dumps(str(MY_WORK))});
+const original = [
+  {{kind:'update', key:'repo#1', notification_id:42, has_update:true, title:'First'}},
+  {{kind:'issue', key:'repo#2', notification_id:43, has_update:true, title:'Second'}},
+];
+const loaded = [];
+const opened = [];
+const details = [];
+const states = [];
+const statuses = [];
+const closed = [];
+const reader = buildMyWork.createNotificationReader({{
+  load: async id => {{ loaded.push(id); return {{id, latest_comment:{{body:'Comment ' + id}}}}; }},
+  markRead: async id => id,
+  onOpen: item => opened.push(item.notification_id),
+  onDetail: detail => details.push(detail.id),
+  onItems: items => states.push(items),
+  onStatus: status => statuses.push(status),
+  onClose: () => closed.push(true),
+}});
+reader.open(original[0], original).then(() =>
+  reader.markReadAndNext(original).then(result =>
+    process.stdout.write(JSON.stringify({{loaded, opened, details, states, statuses, closed, result}}))
+  )
+);
+"""
+    result = subprocess.run(
+        ["node", "-e", script], check=True, capture_output=True, text=True
+    )
+    output = json.loads(result.stdout)
+
+    assert output["loaded"] == [42, 43]
+    assert output["opened"] == [42, 43]
+    assert output["details"] == [42, 43]
+    assert output["states"] == [[
+        {"kind": "issue", "key": "repo#2", "notification_id": 43,
+         "has_update": True, "title": "Second"},
+    ]]
+    assert output["statuses"] == [
+        "Loading update…", "Update ready.", "Marking update read…",
+        "Loading update…", "Update ready.",
+    ]
+    assert output["closed"] == []
+    assert output["result"]["next"]["notification_id"] == 43
+
+
+def test_notification_reader_keeps_current_update_retryable_when_detail_load_fails():
+    script = f"""
+const buildMyWork = require({json.dumps(str(MY_WORK))});
+const item = {{kind:'update', notification_id:42, has_update:true}};
+const events = [];
+const reader = buildMyWork.createNotificationReader({{
+  load: async () => {{ throw new Error('offline'); }},
+  markRead: async () => {{}}, onOpen: () => events.push('open'),
+  onDetail: () => events.push('detail'), onItems: () => events.push('items'),
+  onStatus: status => events.push(status), onClose: () => events.push('close'),
+}});
+reader.open(item, [item]).then(result =>
+  process.stdout.write(JSON.stringify({{result, events}}))
+);
+"""
+    result = subprocess.run(
+        ["node", "-e", script], check=True, capture_output=True, text=True
+    )
+
+    assert json.loads(result.stdout) == {
+        "result": False,
+        "events": [
+            "open", "Loading update…",
+            "Could not load update. Retry or open it in Gitea.",
+        ],
+    }
+
+
+def test_notification_reader_does_not_advance_or_remove_item_when_mark_read_fails():
+    script = f"""
+const buildMyWork = require({json.dumps(str(MY_WORK))});
+const item = {{kind:'update', notification_id:42, has_update:true}};
+const events = [];
+const reader = buildMyWork.createNotificationReader({{
+  load: async id => ({{id}}), markRead: async () => {{ throw new Error('offline'); }},
+  onOpen: () => events.push('open'), onDetail: () => events.push('detail'),
+  onItems: () => events.push('items'), onStatus: status => events.push(status),
+  onClose: () => events.push('close'),
+}});
+reader.open(item, [item]).then(() =>
+  reader.markReadAndNext([item]).then(result =>
+    process.stdout.write(JSON.stringify({{result, events}}))
+  )
+);
+"""
+    result = subprocess.run(
+        ["node", "-e", script], check=True, capture_output=True, text=True
+    )
+
+    assert json.loads(result.stdout) == {
+        "result": False,
+        "events": [
+            "open", "Loading update…", "detail", "Update ready.",
+            "Marking update read…", "Could not mark update read. Retry.",
+        ],
+    }
+
+
+def test_notification_reader_wraps_to_an_earlier_visible_unread_update():
+    script = f"""
+const buildMyWork = require({json.dumps(str(MY_WORK))});
+const items = [
+  {{kind:'update', notification_id:42, has_update:true}},
+  {{kind:'update', notification_id:43, has_update:true}},
+];
+const opened = [];
+const reader = buildMyWork.createNotificationReader({{
+  load: async id => ({{id}}), markRead: async () => {{}},
+  onOpen: item => opened.push(item.notification_id), onDetail: () => {{}},
+  onItems: () => {{}}, onStatus: () => {{}}, onClose: () => {{}},
+}});
+reader.open(items[1], items).then(() => reader.markReadAndNext(items)).then(result =>
+  process.stdout.write(JSON.stringify({{opened, next:result.next.notification_id}}))
+);
+"""
+    result = subprocess.run(
+        ["node", "-e", script], check=True, capture_output=True, text=True
+    )
+
+    assert json.loads(result.stdout) == {"opened": [43, 42], "next": 42}
+
+
+def test_notification_reader_closes_and_announces_when_final_update_is_cleared():
+    script = f"""
+const buildMyWork = require({json.dumps(str(MY_WORK))});
+const item = {{kind:'update', notification_id:42, has_update:true}};
+const events = [];
+const reader = buildMyWork.createNotificationReader({{
+  load: async id => ({{id}}), markRead: async () => {{}},
+  onOpen: () => {{}}, onDetail: () => {{}}, onItems: items => events.push(['items', items]),
+  onStatus: status => events.push(['status', status]), onClose: () => events.push(['close']),
+}});
+reader.open(item, [item]).then(() => {{
+  events.length = 0;
+  return reader.markReadAndNext([item]);
+}}).then(result => process.stdout.write(JSON.stringify({{result, events}})));
+"""
+    result = subprocess.run(
+        ["node", "-e", script], check=True, capture_output=True, text=True
+    )
+    output = json.loads(result.stdout)
+
+    assert output["result"] == {"items": [], "next": None}
+    assert output["events"] == [
+        ["status", "Marking update read…"],
+        ["items", []],
+        ["close"],
+        ["status", "Inbox cleared."],
+    ]
+
+
@pytest.mark.anyio
 async def test_mobile_dashboard_puts_filterable_my_work_before_auxiliary_panels():
    html = await dashboard()
@ -416,6 +575,27 @@ async def test_unread_cards_offer_accessible_mobile_mark_read_without_nested_act
    assert '<a class="my-work-card"' not in html


+@pytest.mark.anyio
+async def test_mobile_update_reader_is_in_app_safe_area_aware_and_actionable():
+    html = await dashboard()
+
+    assert 'id="update-sheet"' in html and 'aria-modal="true"' in html
+    assert 'class="read-update"' in html
+    assert 'id="keep-update-unread"' in html
+    assert 'id="mark-update-read-next"' in html
+    assert 'id="retry-update-load"' in html
+    assert 'id="update-comment-body"' in html
+    assert 'id="update-subject-body"' in html
+    assert 'id="open-update-gitea"' in html
+    assert '.update-sheet-panel { width:min(560px,100%);' in html
+    assert '.update-sheet-content { overflow-wrap:anywhere;' in html
+    assert 'padding-bottom:calc(10px + env(safe-area-inset-bottom));' in html
+    assert '.update-sheet-actions button, .update-sheet-actions a { min-height:44px;' in html
+    assert "createNotificationReader" in html
+    assert "api/v1/notifications/" in html
+    assert "notificationReader.markReadAndNext(lastMyWork)" in html
+
+
@pytest.mark.anyio
 async def test_updates_view_offers_confirmed_sticky_mobile_bulk_acknowledgement():
    html = await dashboard()
--- a/tests/test_notification_detail.py
+++ b/tests/test_notification_detail.py
@ -0,0 +1,76 @@
+import asyncio
+
+import httpx
+import pytest
+
+from src import main
+
+
+@pytest.mark.anyio
+async def test_notification_detail_api_is_bounded_and_never_cacheable(monkeypatch):
+    calls = []
+
+    async def detail(thread_id):
+        calls.append(thread_id)
+        return {
+            "id": thread_id,
+            "repository": "stackchain/api",
+            "title": "Retry failed deploy",
+            "subject_type": "Issue",
+            "state": "open",
+            "url": "https://forge.example/stackchain/api/issues/7#issuecomment-9",
+            "subject_body": "Deploy fails after three retries.",
+            "latest_comment": {
+                "author": "alexander",
+                "body": "Logs point to the worker timeout.",
+                "created_at": "2026-08-06T12:30:00Z",
+                "url": "https://forge.example/stackchain/api/issues/7#issuecomment-9",
+            },
+        }
+
+    monkeypatch.setattr(main, "notification_detail", detail, raising=False)
+    transport = httpx.ASGITransport(app=main.app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/api/v1/notifications/42")
+        invalid = await client.get("/api/v1/notifications/0")
+
+    assert response.status_code == 200
+    assert response.json()["latest_comment"]["author"] == "alexander"
+    assert response.headers["cache-control"] == "no-store"
+    assert invalid.status_code == 422
+    assert calls == [42]
+
+
+@pytest.mark.anyio
+async def test_notification_detail_timeout_is_sanitized_and_retryable(monkeypatch):
+    async def detail(_thread_id):
+        await asyncio.sleep(0.05)
+
+    monkeypatch.setattr(main, "notification_detail", detail)
+    monkeypatch.setattr(main, "NOTIFICATION_DETAIL_TIMEOUT_SECONDS", 0.01)
+    transport = httpx.ASGITransport(app=main.app, raise_app_exceptions=False)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/api/v1/notifications/42")
+
+    assert response.status_code == 503
+    assert response.json() == {"error": "Loading the update timed out. Please retry."}
+    assert response.headers["retry-after"] == "1"
+    assert response.headers["cache-control"] == "no-store"
+
+
+@pytest.mark.anyio
+async def test_notification_detail_upstream_failure_does_not_leak_exception(monkeypatch):
+    async def detail(_thread_id):
+        raise httpx.HTTPError("token=secret upstream exploded")
+
+    monkeypatch.setattr(main, "notification_detail", detail)
+    transport = httpx.ASGITransport(app=main.app, raise_app_exceptions=False)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/api/v1/notifications/42")
+
+    assert response.status_code == 503
+    assert response.json() == {
+        "error": "The update is temporarily unavailable. Please retry."
+    }
+    assert "secret" not in response.text
+    assert response.headers["retry-after"] == "1"