From 475d848ec45f38bb219f756450d107008f53c0ff Mon Sep 17 00:00:00 2001
From: Willi Budzinski <w.budzinski@telekom.de>
Date: Thu, 18 Jun 2026 21:39:08 +0200
Subject: [PATCH 1/3] fix(viewer): preserve dashboard scroll and show api
 errors

---
 .../plan.md                                   | 173 ++++++++++++++++++
 .../todo.md                                   |  81 ++++++++
 src/viewer/index.html                         | 114 +++++++++++-
 test/helpers/viewer-sandbox.ts                | 111 +++++++++--
 test/viewer-session-id.test.ts                | 109 +++++++++++
 5 files changed, 570 insertions(+), 18 deletions(-)
 create mode 100644 docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/plan.md
 create mode 100644 docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md

diff --git a/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/plan.md b/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/plan.md
new file mode 100644
index 00000000..78343bb5
--- /dev/null
+++ b/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/plan.md
@@ -0,0 +1,173 @@
+# Issue 507 Viewer Dashboard Errors Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Preserve dashboard scroll position during refreshes and show safe user-visible API error notifications in the viewer.
+
+**Architecture:** Keep the fix inside the existing single-file viewer script. Add a small toast host/renderer beside the existing auth prompt patterns, add client-side timeout handling inside `api()`, and wrap dashboard refresh rendering with scroll capture/restore on the dashboard scroll container.
+
+**Tech Stack:** TypeScript tests with Vitest, VM-executed browser script from `src/viewer/index.html`, DOM stubs in `test/helpers/viewer-sandbox.ts`, browser JavaScript in the viewer template.
+
+---
+
+## Files
+
+- Modify: `src/viewer/index.html`
+- Modify: `test/helpers/viewer-sandbox.ts`
+- Modify: `test/viewer-session-id.test.ts`
+- Update: `docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md`
+
+## Task 1: Red Tests For Viewer API Error Toasts
+
+**Files:**
+- Modify: `test/helpers/viewer-sandbox.ts`
+- Modify: `test/viewer-session-id.test.ts`
+
+- [ ] **Step 1: Extend the sandbox enough to observe abort timeouts and toast DOM**
+
+Add mock element fields used by the viewer code: `scrollTop`, `scrollHeight`, `clientHeight`, `appendChild`, `remove`, `children`, and a minimal `AbortController`/`AbortSignal.timeout` surface if needed by tests.
+
+- [ ] **Step 2: Write failing HTTP error toast test**
+
+Add a test that sets `sandbox.fetch` to return `{ ok: false, status: 503 }`, calls `sandbox.apiGet("memories?<img src=x onerror=alert(1)>")`, and asserts a toast host contains escaped path/status text and no raw `<img`.
+
+- [ ] **Step 3: Write failing network failure toast test**
+
+Add a test that makes `sandbox.fetch` reject with `new Error("<script>offline</script>")`, calls `sandbox.apiGet("health")`, and asserts visible escaped text in the toast host with no raw `<script>`.
+
+- [ ] **Step 4: Write failing timeout toast test**
+
+Add a test using a never-settling `sandbox.fetch`, run pending timers, and assert `apiGet("health")` resolves to `null` and the toast host reports a timeout.
+
+- [ ] **Step 5: Run red tests**
+
+Run:
+
+```bash
+corepack pnpm exec vitest run test/viewer-session-id.test.ts
+```
+
+Expected before implementation: new toast tests fail because there is no toast host/notification and no browser-side timeout.
+
+## Task 2: Red Tests For Dashboard Scroll Preservation
+
+**Files:**
+- Modify: `test/helpers/viewer-sandbox.ts`
+- Modify: `test/viewer-session-id.test.ts`
+
+- [ ] **Step 1: Write failing direct refresh scroll test**
+
+Set `view-dashboard.scrollTop = 240`, provide successful dashboard API responses, call `sandbox.refreshDashboard()`, and assert `scrollTop` remains `240` after render.
+
+- [ ] **Step 2: Write failing debounced refresh scroll test**
+
+Set `state.activeTab = "dashboard"`, `view-dashboard.scrollTop = 180`, trigger `sandbox.scheduleDashboardRefresh()`, flush timers, await the load, and assert `scrollTop` remains `180`.
+
+- [ ] **Step 3: Run red tests**
+
+Run:
+
+```bash
+corepack pnpm exec vitest run test/viewer-session-id.test.ts
+```
+
+Expected before implementation: new scroll tests fail because `loadDashboard()` writes a loading state and render output without scroll restoration.
+
+## Task 3: Minimal Viewer Implementation
+
+**Files:**
+- Modify: `src/viewer/index.html`
+
+- [ ] **Step 1: Add toast CSS and host**
+
+Add a bottom-right fixed toast container near existing top-level viewer markup. Style toasts with compact, accessible, non-card UI that fits existing viewer colors.
+
+- [ ] **Step 2: Add safe toast helpers**
+
+Add `showToast(title, message)` that creates DOM nodes and assigns text via `textContent`; do not concatenate untrusted text into `innerHTML`.
+
+- [ ] **Step 3: Add browser-side API timeout**
+
+Inside `api()`, create an `AbortController`, pass its signal to `fetch`, clear the timer in `finally`, and return `null` on timeout/failure. Do not override caller-provided headers. Preserve auth prompt behavior for 401.
+
+- [ ] **Step 4: Surface API failures**
+
+For non-OK responses, network failures, and timeouts, call `showToast()` with method/path/status-safe text. Do not include raw response bodies. Hide auth prompt only after successful responses as today.
+
+- [ ] **Step 5: Preserve dashboard scroll**
+
+Capture `#view-dashboard.scrollTop` before refresh rendering. Restore it after loading and after `renderDashboard()` if the active tab is still dashboard. Apply this through both direct `refreshDashboard()` and debounced `scheduleDashboardRefresh()` because both converge on `loadDashboardOnce()`.
+
+## Task 4: Green Verification And Cleanup
+
+**Files:**
+- Modify: `docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md`
+
+- [ ] **Step 1: Run targeted viewer tests**
+
+Run:
+
+```bash
+corepack pnpm exec vitest run test/viewer-session-id.test.ts test/viewer-security.test.ts test/viewer-graph-cooldown.test.ts
+```
+
+Expected after implementation: pass.
+
+- [ ] **Step 2: Run repo-native checks**
+
+Run:
+
+```bash
+corepack pnpm test
+corepack pnpm run build
+corepack pnpm run lint
+```
+
+Expected: pass, or record any unrelated/pre-existing failure with evidence.
+
+- [ ] **Step 3: Run required security gates**
+
+Run:
+
+```bash
+semgrep scan --config p/default --error --metrics=off .
+gitleaks protect --staged --redact
+```
+
+Expected: pass. `gitleaks protect` runs after staging task-owned files.
+
+- [ ] **Step 4: Update task record**
+
+Update matrix statuses with command evidence, caveats, and residual risks.
+
+## Task 5: GitHub PR Flow Closeout
+
+**Files:**
+- No code edits expected beyond task record if verification evidence changes.
+
+- [ ] **Step 1: Commit task-owned changes**
+
+Stage only task-owned files and commit with a scoped Conventional Commit message.
+
+- [ ] **Step 2: Push branch to origin**
+
+Push `issue/507-viewer-dashboard-errors` to `origin`.
+
+- [ ] **Step 3: Create PR against `main`**
+
+Use `gh pr create --repo wbugitlab1/agentmemory --base main --head issue/507-viewer-dashboard-errors`.
+
+- [ ] **Step 4: Wait for CI and merge**
+
+Wait for PR checks. If checks pass, merge into `origin/main` using repository defaults. If checks fail, fix task-owned failures or record blocker.
+
+- [ ] **Step 5: Verify issue/thread closeout**
+
+Verify Issue #507 is closed or linked by the merged PR. Archive the delegated Codex thread with the thread-management tool.
+
+## Self-Review
+
+- Spec coverage: Issue #507 scroll preservation, API error display, timeout behavior, and regression coverage are mapped to tests and implementation tasks.
+- Placeholder scan: No `TBD` or open implementation placeholders remain.
+- Type consistency: Viewer VM tests refer only to existing sandbox pattern names or browser globals that Task 1 adds.
+- Scope: Single viewer surface; no schema, auth, REST endpoint, dependency, or external service changes.
diff --git a/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md b/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md
new file mode 100644
index 00000000..dae115b0
--- /dev/null
+++ b/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md
@@ -0,0 +1,81 @@
+# Issue 507 Viewer Dashboard Errors
+
+## Scope
+
+- Repository: `/Users/A1538552/.codex/worktrees/dea7/agentmemory`
+- Branch: `issue/507-viewer-dashboard-errors`
+- Base: `origin/main` at `a029b7e117db99c65201ee3d9abb6bb93ff2e173`
+- GitHub issue: `wbugitlab1/agentmemory#507`
+- Spec path: none; source of truth is the current user delegation, Issue #507 body, and this task record.
+
+## Sprint Contract
+
+**Goal:** Preserve dashboard scroll position across refreshes and surface viewer API failures to users with safe, escaped toast notifications.
+
+**Scope:** Viewer browser code in `src/viewer/index.html`, viewer VM sandbox support in `test/helpers/viewer-sandbox.ts`, and focused viewer tests.
+
+**Non-goals:** No REST endpoint changes, no auth changes, no new dependencies, no new external services, no persistence/schema changes, and no upstream `rohitg00/agentmemory` writes.
+
+**Acceptance criteria:**
+
+- Manual dashboard refresh preserves `#view-dashboard.scrollTop`.
+- Debounced dashboard refreshes used by polling and WebSocket events preserve `#view-dashboard.scrollTop`.
+- API HTTP errors, network failures, and request timeouts produce visible bottom-right viewer notifications.
+- Error notification content is text-escaped and does not render raw HTML from paths, HTTP bodies, or exception messages.
+- Existing dashboard endpoint error banner remains intact for partial dashboard loads.
+
+**Intended verification:**
+
+- `corepack pnpm exec vitest run test/viewer-session-id.test.ts test/viewer-security.test.ts test/viewer-graph-cooldown.test.ts`
+- `corepack pnpm test`
+- `corepack pnpm run build`
+- `corepack pnpm run lint`
+- `semgrep scan --config p/default --error --metrics=off .`
+- After staging: `gitleaks protect --staged --redact`
+
+**Known boundaries:**
+
+- Current-turn user instruction authorizes push, PR creation, merge, issue/thread closeout for task-owned changes.
+- Remote writes must target `origin` (`wbugitlab1/agentmemory`) only.
+- Do not read or mutate token-bearing package-manager config.
+- If dependency setup is required because `node_modules` is missing, use `corepack pnpm install --frozen-lockfile --ignore-scripts` without manifest/lockfile changes.
+
+**Stop conditions:**
+
+- Any required check reports a real finding that cannot be fixed in scope.
+- Remote target is not `wbugitlab1/agentmemory`.
+- CI fails with an unclear or out-of-scope failure.
+- A required security gate is unavailable or nonzero and cannot be resolved without current-turn user acceptance.
+
+## Feature / Verification Matrix
+
+| Change | Verification method | Status | Evidence |
+| --- | --- | --- | --- |
+| Preserve dashboard scroll on direct refresh | Failing then passing VM test in `test/viewer-session-id.test.ts` | pass | Red: `corepack pnpm exec vitest run test/viewer-session-id.test.ts` failed with `scrollTop` 0 vs expected 240. Green: same command passed 14/14. |
+| Preserve dashboard scroll on debounced refresh path | Failing then passing VM test using `scheduleDashboardRefresh()`/timer flush | pass | Red: same focused run failed with `scrollTop` 0 vs expected 180. Green: same command passed 14/14. |
+| Show API HTTP error toast | Failing then passing VM test around `apiGet()` | pass | Red: focused run failed because toast HTML was empty. Green: focused run passed 14/14. |
+| Show API network failure toast | Failing then passing VM test around rejected `fetch` | pass | Red: focused run failed because toast HTML was empty. Green: focused run passed 14/14. |
+| Show API timeout toast | Failing then passing VM test around abort timeout | pass | Red: focused run returned `{ unexpectedlyCompletedWithoutTimeout: true }`. Green: focused run passed 14/14. |
+| Escape toast content | Failing then passing VM test with hostile path/error text | pass | Green focused tests assert no raw `<img` or `<script>` appears in toast HTML. |
+| Existing dashboard endpoint banner preserved | Existing targeted viewer test suite | pass | `corepack pnpm exec vitest run test/viewer-session-id.test.ts test/viewer-security.test.ts test/viewer-graph-cooldown.test.ts` passed 40/40. |
+
+## Subagent Ledger
+
+| Workstream | Scope | Edits allowed | Expected output | Result | Residual risk |
+| --- | --- | --- | --- | --- | --- |
+| Explorer `019edc33-9e31-70d1-a3da-4e7c4e416b1d` | Read-only validation of Issue #507 against `HEAD == origin/main` | No | Evidence on scroll preservation, API error visibility, dashboard banner coverage, DOM escaping | Completed: issue valid. Dashboard banner partially covers endpoint-group failures, but scroll preservation and general API toasts/timeouts are missing. All refresh sources converge through dashboard content replacement. Fix must use textContent or `esc()` for untrusted text. | Source inspection inferred scroll loss; browser/runtime verification remains useful after implementation. |
+
+## Progress
+
+- 2026-06-18: Confirmed branch, remote, clean worktree, and issue validity.
+- 2026-06-18: Recorded current Sprint Contract, matrix, and subagent result.
+- 2026-06-18: Added Red tests for API HTTP/network/timeout toasts and dashboard scroll preservation; confirmed focused failures before implementation.
+- 2026-06-18: Implemented safe viewer toasts, browser-side API timeout, and dashboard scroll capture/restore.
+- 2026-06-18: Verification before base merge:
+  - `corepack pnpm exec vitest run test/viewer-session-id.test.ts` passed 14 tests.
+  - `corepack pnpm exec vitest run test/viewer-session-id.test.ts test/viewer-security.test.ts test/viewer-graph-cooldown.test.ts` passed 40 tests.
+  - `corepack pnpm test` passed 198 files / 2772 tests.
+  - `corepack pnpm run build` exited 0 with existing tsdown plugin timing and dynamic-import warnings.
+  - `corepack pnpm run lint` exited 0.
+  - `semgrep scan --config p/default --error --metrics=off .` completed with 0 findings.
+  - `git diff --check` exited 0.
diff --git a/src/viewer/index.html b/src/viewer/index.html
index 040ed66f..8cbe3cc8 100644
--- a/src/viewer/index.html
+++ b/src/viewer/index.html
@@ -250,6 +250,41 @@
       letter-spacing: 0.08em;
       margin-bottom: 4px;
     }
+    .viewer-toasts {
+      position: fixed;
+      right: 18px;
+      bottom: 18px;
+      z-index: 40;
+      display: flex;
+      flex-direction: column;
+      gap: 8px;
+      width: min(360px, calc(100vw - 36px));
+      pointer-events: none;
+    }
+    .viewer-toast {
+      border: 1px solid var(--accent);
+      border-left-width: 3px;
+      background: var(--bg);
+      color: var(--ink);
+      padding: 11px 13px;
+      box-shadow: 0 10px 28px rgba(0,0,0,0.14);
+      font-family: var(--font-ui);
+      pointer-events: auto;
+    }
+    .viewer-toast-title {
+      color: var(--accent);
+      font-size: 11px;
+      font-weight: 700;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      margin-bottom: 4px;
+    }
+    .viewer-toast-message {
+      color: var(--ink-muted);
+      font-size: 12px;
+      line-height: 1.4;
+      overflow-wrap: anywhere;
+    }
 
     .card {
       background: var(--bg);
@@ -1074,6 +1109,7 @@ <h1>agentmemory</h1>
 
   <div id="flag-banners" class="flag-banners"></div>
   <div id="viewer-auth" class="viewer-auth"></div>
+  <div id="viewer-toasts" class="viewer-toasts" aria-live="polite" aria-atomic="true"></div>
 
   <div id="view-dashboard" class="view active"></div>
   <div id="view-graph" class="view"></div>
@@ -1448,7 +1484,48 @@ <h1>agentmemory</h1>
       host.innerHTML = '';
     }
 
+    var VIEWER_API_TIMEOUT_MS = 10000;
+    var VIEWER_TOAST_LIMIT = 4;
+    var VIEWER_TOAST_TTL_MS = 8000;
+
+    function showToast(title, message) {
+      var host = document.getElementById('viewer-toasts');
+      if (!host) return;
+      var toast = document.createElement('div');
+      toast.className = 'viewer-toast';
+      toast.setAttribute('role', 'status');
+      var titleEl = document.createElement('div');
+      titleEl.className = 'viewer-toast-title';
+      titleEl.textContent = String(title || 'Notice');
+      var messageEl = document.createElement('div');
+      messageEl.className = 'viewer-toast-message';
+      messageEl.textContent = String(message || '');
+      toast.appendChild(titleEl);
+      toast.appendChild(messageEl);
+      host.appendChild(toast);
+      while (host.children && host.children.length > VIEWER_TOAST_LIMIT) {
+        host.removeChild(host.children[0]);
+      }
+      setTimeout(function() {
+        if (toast.parentNode) toast.remove();
+      }, VIEWER_TOAST_TTL_MS);
+    }
+
+    function apiErrorMessage(method, path, detail) {
+      return method + ' /agentmemory/' + path + ': ' + detail;
+    }
+
+    function errorDetail(err) {
+      if (!err) return 'request failed';
+      if (err.message) return err.message;
+      return String(err);
+    }
+
     async function api(path, opts) {
+      var fetchOpts;
+      var timeoutId = null;
+      var didTimeout = false;
+      var method = (opts && opts.method) || 'GET';
       try {
         var url = REST + '/agentmemory/' + path;
         var headers = Object.assign({ 'Cache-Control': 'no-cache' }, (opts && opts.headers) || {});
@@ -1456,18 +1533,34 @@ <h1>agentmemory</h1>
         if (viewerToken && !headers.Authorization && !headers.authorization) {
           headers.Authorization = 'Bearer ' + viewerToken;
         }
-        var fetchOpts = Object.assign({}, opts || {}, { headers: headers });
+        fetchOpts = Object.assign({}, opts || {}, { headers: headers });
+        if (typeof AbortController !== 'undefined') {
+          var controller = new AbortController();
+          timeoutId = setTimeout(function() {
+            didTimeout = true;
+            controller.abort();
+          }, VIEWER_API_TIMEOUT_MS);
+          fetchOpts.signal = controller.signal;
+        }
         var res = await fetch(url, fetchOpts);
         if (!res.ok) {
           if (res.status === 401) showViewerAuthPrompt();
+          else showToast('API request failed', apiErrorMessage(method, path, 'HTTP ' + res.status));
           console.warn('[viewer] API ' + (fetchOpts.method || 'GET') + ' ' + path + ' returned ' + res.status);
           return null;
         }
         hideViewerAuthPrompt();
         return await res.json();
       } catch (err) {
+        if (didTimeout || (err && err.name === 'AbortError')) {
+          showToast('API request timed out', apiErrorMessage(method, path, 'exceeded ' + Math.round(VIEWER_API_TIMEOUT_MS / 1000) + 's'));
+        } else {
+          showToast('API request failed', apiErrorMessage(method, path, errorDetail(err)));
+        }
         console.warn('[viewer] API error on ' + path + ':', err);
         return null;
+      } finally {
+        if (timeoutId) clearTimeout(timeoutId);
       }
     }
     async function apiGet(path) { return api(path); }
@@ -1552,9 +1645,24 @@ <h1>agentmemory</h1>
       }
     }
 
+    function captureDashboardScroll() {
+      var el = document.getElementById('view-dashboard');
+      if (!el) return null;
+      return { el: el, top: el.scrollTop || 0 };
+    }
+
+    function restoreDashboardScroll(snapshot) {
+      if (!snapshot || !snapshot.el) return;
+      snapshot.el.scrollTop = snapshot.top;
+    }
+
     async function loadDashboard() {
       var el = document.getElementById('view-dashboard');
-      el.innerHTML = '<div class="loading">' + t('loading.dashboard') + '</div>';
+      var scrollSnapshot = captureDashboardScroll();
+      if (!el.innerHTML) {
+        el.innerHTML = '<div class="loading">' + t('loading.dashboard') + '</div>';
+        restoreDashboardScroll(scrollSnapshot);
+      }
       try {
         var dashboardEndpointRequests = [
           { label: 'health', path: 'health' },
@@ -1590,6 +1698,7 @@ <h1>agentmemory</h1>
         state.dashboard.failedEndpoints = failedDashboardEndpoints;
         state.dashboard.loaded = true;
         renderDashboard();
+        restoreDashboardScroll(scrollSnapshot);
       } catch (err) {
         // Without this catch, any uncaught error in the await Promise.all
         // or the renderDashboard call leaves the dashboard stuck on
@@ -1606,6 +1715,7 @@ <h1>agentmemory</h1>
           '<br><br><span style="font-size:12px;color:var(--ink-muted);">' +
           t('dashboard.failed_help') +
           '</span></div>';
+        restoreDashboardScroll(scrollSnapshot);
       }
     }
 
diff --git a/test/helpers/viewer-sandbox.ts b/test/helpers/viewer-sandbox.ts
index 1900ee8f..73c5ff87 100644
--- a/test/helpers/viewer-sandbox.ts
+++ b/test/helpers/viewer-sandbox.ts
@@ -24,26 +24,91 @@ export function loadViewerSandbox() {
     const attributes = new Map<string, string>();
     const classes = new Set<string>();
     const listeners = new Map<string, Array<(event?: unknown) => void>>();
-    return {
+    let html = "";
+    let text = "";
+    const childNodes: any[] = [];
+    const element: Record<string, any> = {
       id,
-      innerHTML: "",
-      textContent: "",
       value: "",
       checked: false,
       dataset: {},
       style: {},
       listeners,
+      parentNode: null,
+      scrollTop: 0,
+      scrollHeight: 1000,
+      clientHeight: 400,
+      className: "",
+      role: "",
+      ariaLive: "",
+      get children() {
+        return childNodes;
+      },
+      set innerHTML(value: unknown) {
+        html = String(value ?? "");
+        text = "";
+        childNodes.splice(0, childNodes.length);
+        element.scrollTop = 0;
+      },
+      get innerHTML() {
+        if (childNodes.length > 0) {
+          return childNodes.map((child) => child.outerHTML ?? child.innerHTML ?? "").join("");
+        }
+        return html;
+      },
+      set textContent(value: unknown) {
+        text = String(value ?? "");
+        html = htmlEscape(text);
+        childNodes.splice(0, childNodes.length);
+      },
+      get textContent() {
+        return text;
+      },
+      get outerHTML() {
+        const classAttr = element.className ? ` class="${htmlEscape(element.className)}"` : "";
+        const roleAttr = element.role ? ` role="${htmlEscape(element.role)}"` : "";
+        return `<div${classAttr}${roleAttr}>${element.innerHTML}</div>`;
+      },
       classList: {
-        add: (name: string) => classes.add(name),
-        remove: (name: string) => classes.delete(name),
+        add: (name: string) => {
+          classes.add(name);
+          element.className = Array.from(classes).join(" ");
+        },
+        remove: (name: string) => {
+          classes.delete(name);
+          element.className = Array.from(classes).join(" ");
+        },
         contains: (name: string) => classes.has(name),
         toggle: (name: string, force?: boolean) => {
           const enabled = force ?? !classes.has(name);
           if (enabled) classes.add(name);
           else classes.delete(name);
+          element.className = Array.from(classes).join(" ");
           return enabled;
         },
       },
+      appendChild: (child: any) => {
+        child.parentNode = element;
+        childNodes.push(child);
+        return child;
+      },
+      removeChild: (child: any) => {
+        const idx = childNodes.indexOf(child);
+        if (idx >= 0) childNodes.splice(idx, 1);
+        child.parentNode = null;
+        return child;
+      },
+      replaceChildren: (...children: any[]) => {
+        childNodes.splice(0, childNodes.length);
+        children.forEach((child) => element.appendChild(child));
+        html = "";
+        text = "";
+      },
+      remove: () => {
+        if (element.parentNode && typeof element.parentNode.removeChild === "function") {
+          element.parentNode.removeChild(element);
+        }
+      },
       addEventListener: (type: string, handler: (event?: unknown) => void) => {
         const current = listeners.get(type) || [];
         current.push(handler);
@@ -58,6 +123,7 @@ export function loadViewerSandbox() {
       },
       querySelectorAll: () => [],
     };
+    return element;
   };
   const getElement = (id: string) => {
     if (!elements.has(id)) elements.set(id, createMockElement(id));
@@ -110,22 +176,34 @@ export function loadViewerSandbox() {
 
   const document = {
     documentElement: { dataset: {} },
-    createElement: () => {
-      let text = "";
-      return {
-        set textContent(value: unknown) {
-          text = String(value ?? "");
-        },
-        get innerHTML() {
-          return htmlEscape(text);
-        },
-      };
-    },
+    createElement: () => createMockElement(),
     getElementById: getElement,
     querySelectorAll,
     addEventListener: () => {},
   };
 
+  class MockAbortSignal {
+    aborted = false;
+    private listeners: Array<() => void> = [];
+
+    addEventListener(type: string, listener: () => void) {
+      if (type === "abort") this.listeners.push(listener);
+    }
+
+    abort() {
+      if (this.aborted) return;
+      this.aborted = true;
+      this.listeners.forEach((listener) => listener());
+    }
+  }
+
+  class MockAbortController {
+    signal = new MockAbortSignal();
+    abort() {
+      this.signal.abort();
+    }
+  }
+
   const sandbox: Record<string, any> = {
     console: { log: () => {}, warn: () => {}, error: () => {} },
     document,
@@ -157,6 +235,7 @@ export function loadViewerSandbox() {
       };
     })(),
     fetch: async () => ({ ok: true, json: async () => ({}) }),
+    AbortController: MockAbortController,
     WebSocket: function WebSocket() {},
     navigator: { userAgent: "vitest" },
     Element: function Element() {},
diff --git a/test/viewer-session-id.test.ts b/test/viewer-session-id.test.ts
index a15405df..43774172 100644
--- a/test/viewer-session-id.test.ts
+++ b/test/viewer-session-id.test.ts
@@ -2,6 +2,31 @@ import { describe, expect, it } from "vitest";
 import { renderViewerDocument } from "../src/viewer/document.js";
 import { loadViewerSandbox } from "./helpers/viewer-sandbox.js";
 
+const dashboardResponses: Record<string, unknown> = {
+  health: { status: "healthy", health: {} },
+  sessions: { sessions: [{ id: "ses_dashboard_ok", status: "active", observationCount: 2, startedAt: "2026-06-18T08:00:00.000Z" }] },
+  "memories?latest=true&limit=500": { memories: [] },
+  "graph/stats": { nodes: 1, edges: 0 },
+  "audit?limit=5": { entries: [] },
+  semantic: { facts: [] },
+  procedural: { procedures: [] },
+  relations: { relations: [] },
+  lessons: { lessons: [] },
+  crystals: { crystals: [] },
+  insights: { insights: [] },
+};
+
+function installDashboardFetch(sandbox: Record<string, any>) {
+  sandbox.fetch = async (url: string) => {
+    const requestUrl = new URL(url);
+    const path = requestUrl.pathname.replace("/agentmemory/", "") + requestUrl.search;
+    return {
+      ok: true,
+      json: async () => dashboardResponses[path] ?? {},
+    };
+  };
+}
+
 describe("viewer session rendering", () => {
   it("attaches the saved viewer bearer to API calls", async () => {
     const { sandbox } = loadViewerSandbox();
@@ -32,6 +57,61 @@ describe("viewer session rendering", () => {
     expect(prompt.innerHTML).not.toContain("/data/.hmac");
   });
 
+  it("shows escaped toast details for API HTTP errors", async () => {
+    const { sandbox, getElement } = loadViewerSandbox();
+    sandbox.fetch = async () => ({ ok: false, status: 503, json: async () => ({}) });
+
+    const result = await sandbox.apiGet("memories?<img src=x onerror=alert(1)>");
+
+    const toastHtml = getElement("viewer-toasts").innerHTML;
+    expect(result).toBeNull();
+    expect(toastHtml).toContain("API request failed");
+    expect(toastHtml).toContain("503");
+    expect(toastHtml).toContain("memories?&lt;img src=x onerror=alert(1)&gt;");
+    expect(toastHtml).not.toContain("<img src=x");
+  });
+
+  it("shows escaped toast details for API network failures", async () => {
+    const { sandbox, getElement } = loadViewerSandbox();
+    sandbox.fetch = async () => {
+      throw new Error("<script>offline</script>");
+    };
+
+    const result = await sandbox.apiGet("health");
+
+    const toastHtml = getElement("viewer-toasts").innerHTML;
+    expect(result).toBeNull();
+    expect(toastHtml).toContain("API request failed");
+    expect(toastHtml).toContain("health");
+    expect(toastHtml).toContain("&lt;script&gt;offline&lt;/script&gt;");
+    expect(toastHtml).not.toContain("<script>offline</script>");
+  });
+
+  it("shows a timeout toast when API requests exceed the viewer timeout", async () => {
+    const { sandbox, getElement, flushTimers } = loadViewerSandbox();
+    sandbox.fetch = async (_url: string, opts?: { signal?: { addEventListener?: (type: string, listener: () => void) => void } }) => {
+      if (!opts?.signal?.addEventListener) {
+        return { ok: true, json: async () => ({ unexpectedlyCompletedWithoutTimeout: true }) };
+      }
+      return new Promise((_resolve, reject) => {
+        opts.signal?.addEventListener?.("abort", () => {
+          const err = new Error("aborted");
+          err.name = "AbortError";
+          reject(err);
+        });
+      });
+    };
+
+    const resultPromise = sandbox.apiGet("health");
+    flushTimers();
+    const result = await resultPromise;
+
+    const toastHtml = getElement("viewer-toasts").innerHTML;
+    expect(result).toBeNull();
+    expect(toastHtml).toContain("API request timed out");
+    expect(toastHtml).toContain("health");
+  });
+
   it("shows an explicit dashboard error banner when endpoint groups fail", async () => {
     const { sandbox, getElement } = loadViewerSandbox();
     const responses: Record<string, unknown> = {
@@ -79,6 +159,35 @@ describe("viewer session rendering", () => {
     expect(dashboard).toContain("ses_dash");
   });
 
+  it("preserves dashboard scroll position during manual refresh", async () => {
+    const { sandbox, getElement } = loadViewerSandbox();
+    installDashboardFetch(sandbox);
+    const dashboard = getElement("view-dashboard");
+    await sandbox.loadDashboard();
+    dashboard.scrollTop = 240;
+
+    await sandbox.refreshDashboard();
+
+    expect(dashboard.innerHTML).toContain("Recent Sessions");
+    expect(dashboard.scrollTop).toBe(240);
+  });
+
+  it("preserves dashboard scroll position during debounced websocket or polling refresh", async () => {
+    const { sandbox, getElement, flushTimers } = loadViewerSandbox();
+    installDashboardFetch(sandbox);
+    sandbox.state.activeTab = "dashboard";
+    const dashboard = getElement("view-dashboard");
+    await sandbox.loadDashboard();
+    dashboard.scrollTop = 180;
+
+    sandbox.scheduleDashboardRefresh();
+    flushTimers();
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(dashboard.innerHTML).toContain("Recent Sessions");
+    expect(dashboard.scrollTop).toBe(180);
+  });
+
   it("does not throw when dashboard sessions are missing ids", () => {
     const { sandbox, getElement } = loadViewerSandbox();
     sandbox.state.dashboard = {

From eb4e1bddc2a13b536cf361c88cf39f89b5b60c52 Mon Sep 17 00:00:00 2001
From: Willi Budzinski <w.budzinski@telekom.de>
Date: Thu, 18 Jun 2026 21:42:49 +0200
Subject: [PATCH 2/3] docs: record issue 507 verification

---
 .../2026-06-18-issue-507-viewer-dashboard-errors/todo.md   | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md b/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md
index dae115b0..1cd5a19d 100644
--- a/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md
+++ b/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md
@@ -79,3 +79,10 @@
   - `corepack pnpm run lint` exited 0.
   - `semgrep scan --config p/default --error --metrics=off .` completed with 0 findings.
   - `git diff --check` exited 0.
+- 2026-06-18: Merged `origin/main` (`ee72dba7`) into `issue/507-viewer-dashboard-errors` with no conflicts.
+- 2026-06-18: Post-merge verification:
+  - `corepack pnpm exec vitest run test/viewer-session-id.test.ts test/viewer-security.test.ts test/viewer-graph-cooldown.test.ts test/viewer-token-savings.test.ts` passed 4 files / 41 tests.
+  - `corepack pnpm test` passed 199 files / 2773 tests.
+  - `corepack pnpm run build` exited 0 with existing tsdown plugin timing and dynamic-import warnings.
+  - `corepack pnpm run lint` exited 0.
+  - `semgrep scan --config p/default --error --metrics=off .` completed with 0 findings.

From f62aea40c3647c77be3c558821f47e8762a368c1 Mon Sep 17 00:00:00 2001
From: Willi Budzinski <w.budzinski@telekom.de>
Date: Thu, 18 Jun 2026 21:46:17 +0200
Subject: [PATCH 3/3] docs: record issue 507 final verification

---
 .../2026-06-18-issue-507-viewer-dashboard-errors/todo.md   | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md b/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md
index 1cd5a19d..a8eaef8b 100644
--- a/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md
+++ b/docs/todos/2026-06-18-issue-507-viewer-dashboard-errors/todo.md
@@ -86,3 +86,10 @@
   - `corepack pnpm run build` exited 0 with existing tsdown plugin timing and dynamic-import warnings.
   - `corepack pnpm run lint` exited 0.
   - `semgrep scan --config p/default --error --metrics=off .` completed with 0 findings.
+- 2026-06-18: Branch protection reported the PR branch behind `origin/main`; merged latest `origin/main` again with no conflicts.
+- 2026-06-18: Final local verification after second base merge:
+  - `corepack pnpm exec vitest run test/viewer-session-id.test.ts test/viewer-security.test.ts test/viewer-graph-cooldown.test.ts test/viewer-token-savings.test.ts` passed 4 files / 41 tests.
+  - `corepack pnpm test` passed 199 files / 2773 tests.
+  - `corepack pnpm run lint` exited 0.
+  - `semgrep scan --config p/default --error --metrics=off .` completed with 0 findings.
+  - `corepack pnpm run build` exited 0 with existing tsdown plugin timing and dynamic-import warnings.