ai-or-die 0.1.86 → 0.1.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.86",
+  "version": "0.1.87",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {

package/src/public/app.js

@@ -284,6 +284,15 @@ class ClaudeCodeWebInterface {
         
         // Check if there are existing sessions
         console.log('[Init] Checking sessions, tabs.size:', this.sessionTabManager.tabs.size);
+        // Clean up cached snapshots for sessions that no longer exist (deleted
+        // while away). Deferred so the IndexedDB hydrate has completed; reads the
+        // live tab set AT prune time (not now) so a tab created during the delay
+        // isn't mistaken for an orphan. Best-effort; LRU bounds growth regardless.
+        setTimeout(() => {
+            try {
+                this.snapshotCache?.pruneOrphans(Array.from(this.sessionTabManager.tabs.keys()));
+            } catch (_) { /* best-effort */ }
+        }, 3000);
         if (this.sessionTabManager.tabs.size > 0) {
             console.log('[Init] Found sessions, switching to first tab...');
             // Sessions exist - switch to the last-active one (persisted across
@@ -671,6 +680,30 @@ class ClaudeCodeWebInterface {
 
         this.terminal.open(document.getElementById('terminal'));
 
+        // Faithful per-tab snapshot cache for instant tab-switch repaint.
+        // Guarded: if the serialize addon or the cache class failed to load
+        // (e.g. CDN blocked), snapshotCache stays null and every call site is
+        // ?.-guarded, degrading cleanly to server-only repaint (today's path).
+        this.snapshotCache = null;
+        if (typeof SerializeAddon !== 'undefined' && typeof TerminalSnapshotCache !== 'undefined') {
+            try {
+                this._serializeAddon = new SerializeAddon.SerializeAddon();
+                this.terminal.loadAddon(this._serializeAddon);
+                const snapLines = parseInt((this.loadSettings() || {}).tabSnapshotLines, 10);
+                this.snapshotCache = new TerminalSnapshotCache({
+                    terminal: this.terminal,
+                    serializeAddon: this._serializeAddon,
+                    maxLines: Number.isFinite(snapLines) ? snapLines : 500,
+                });
+                // Fire-and-forget: in-memory tier works immediately; the disk
+                // hydrate (for reload-restore) completes asynchronously.
+                this.snapshotCache.init();
+            } catch (e) {
+                this.snapshotCache = null;
+                try { console.warn('[snapshot-cache] init failed:', e && e.message); } catch (_) {}
+            }
+        }
+
         // WebGL renderer: 3-10x faster than DOM (0.7ms vs 5-10ms per frame)
         this._loadGpuRenderer();
 
@@ -2327,6 +2360,16 @@ class ClaudeCodeWebInterface {
         }
     }
 
+    // True iff the shared terminal is stably displaying this session — no switch
+    // in flight, and the active tab, the joined session, and `sid` all agree.
+    // Capturing a snapshot is only correctly attributed when this holds.
+    _terminalStablyShowsSession(sid) {
+        if (!sid || this.pendingJoinSessionId) return false;
+        if (this.currentClaudeSessionId !== sid) return false;
+        if (this.sessionTabManager && this.sessionTabManager.activeTabId !== sid) return false;
+        return true;
+    }
+
     handleBinaryOutput(data) {
         const chunk = new Uint8Array(data);
 
@@ -2349,6 +2392,20 @@ class ClaudeCodeWebInterface {
             if (this._planDetectTimer) clearTimeout(this._planDetectTimer);
             this._planDetectTimer = setTimeout(() => this._flushPlanDetection(), 100);
         }
+
+        // 4. Keep the active tab's snapshot fresh after output settles (never
+        // per frame). Debounced so a burst captures once when it quiets. Only
+        // captures while the terminal STABLY shows this session (no switch in
+        // flight; active tab + joined session agree), so a switch can never
+        // store one tab's screen under another tab's id.
+        if (this.snapshotCache && this._terminalStablyShowsSession(this.currentClaudeSessionId)) {
+            const sid = this.currentClaudeSessionId;
+            if (this._snapCaptureTimer) clearTimeout(this._snapCaptureTimer);
+            this._snapCaptureTimer = setTimeout(() => {
+                this._snapCaptureTimer = null;
+                if (this._terminalStablyShowsSession(sid)) this.snapshotCache?.capture(sid);
+            }, 400);
+        }
     }
 
     // Concatenate all queued chunks and write to terminal once per animation frame
@@ -2529,21 +2586,60 @@ class ClaudeCodeWebInterface {
                     this.pendingJoinSessionId = null;
                 }
                 
-                // Repaint: prefer the rendered snapshot (clean last screen) so a
-                // refresh doesn't blank or show broken control sequences; fall
-                // back to raw outputBuffer replay when there's no snapshot.
-                if (message.renderedSnapshot) {
-                    this.terminal.clear();
-                    this.terminal.write(message.renderedSnapshot.replace(/\n/g, '\r\n'));
-                } else if (message.outputBuffer && message.outputBuffer.length > 0) {
-                    this.terminal.clear();
-                    message.outputBuffer.forEach(data => {
-                        // Filter out focus tracking sequences (^[[I and ^[[O)
-                        const filteredData = data.replace(/\x1b\[\[?[IO]/g, '');
-                        this.terminal.write(filteredData);
-                    });
+                // Repaint on (re)join — but only if this join is still the tab
+                // the user has selected. A rapid A→B→C switch can deliver a stale
+                // join (in EITHER arrival order); repainting it would paint the
+                // wrong tab. activeTabId is the user's selection and is immune to
+                // the join ordering/timeout races that make pendingJoinSessionId
+                // unreliable here.
+                const targetTabId = this.sessionTabManager ? this.sessionTabManager.activeTabId : message.sessionId;
+                const isStaleJoin = targetTabId && targetTabId !== message.sessionId;
+                if (!isStaleJoin) {
+                    // For a LIVE session, replay the raw outputBuffer (real ANSI +
+                    // cursor codes) so the agent's live TUI redraw aligns. The
+                    // server's renderedSnapshot is rendered PLAIN TEXT (no cursor/
+                    // SGR/scroll-region state); writing it under a live TUI leaves
+                    // the cursor on the wrong row and the next redraw collides
+                    // with stale content (the #131 regression). So the plain-text
+                    // snapshot is used ONLY for non-live (exited/idle) sessions.
+                    // See join-repaint.js for the decision matrix.
+                    const replayBuffer = () => {
+                        this.terminal.clear();
+                        message.outputBuffer.forEach(data => {
+                            // Filter out focus tracking sequences (^[[I and ^[[O)
+                            this.terminal.write(data.replace(/\x1b\[\[?[IO]/g, ''));
+                        });
+                    };
+                    const action = chooseJoinRepaint(message);
+                    // Did the instant cache paint already show THIS session for
+                    // this switch? If so, a 'clear' verdict (the server has nothing
+                    // to replay) must NOT blank the good cached view.
+                    const cacheAlreadyPainted = this._cachePaintedForSession === message.sessionId;
+                    if (action === 'buffer') {
+                        replayBuffer();
+                    } else if (action === 'snapshot') {
+                        this.terminal.clear();
+                        this.terminal.write(message.renderedSnapshot.replace(/\n/g, '\r\n'));
+                    } else if (!cacheAlreadyPainted) {
+                        // Empty-state guard: clear so a cold join never leaves the
+                        // previous tab's content lingering on the shared terminal.
+                        this.terminal.clear();
+                    }
+
+                    // Refresh the cache from the authoritative repaint, but only
+                    // AFTER xterm has drained the writes above. terminal.write('',
+                    // cb) fires its callback once all prior writes are parsed — a
+                    // reliable drain barrier (a single rAF is not). Guard against a
+                    // re-switch landing before the drain completes.
+                    if (this.snapshotCache && message.sessionId && action !== 'clear') {
+                        const sid = message.sessionId;
+                        this.terminal.write('', () => {
+                            if (this._terminalStablyShowsSession(sid)) this.snapshotCache?.capture(sid);
+                        });
+                    }
+                    this._cachePaintedForSession = null;
                 }
-                
+
                 // Show appropriate UI based on session state
                 console.log('[session_joined] Checking if should show overlay. Active:', message.active, 'toolStartPending:', !!this._toolStartPending);
                 if (this._toolStartPending) {
@@ -2579,7 +2675,17 @@ class ClaudeCodeWebInterface {
                 this.currentClaudeSessionId = null;
                 this.currentClaudeSessionName = null;
                 this.updateSessionButton('Sessions');
-                this.terminal.clear();
+                // During a tab switch the server emits session_left (for the
+                // outgoing session) immediately before session_joined (for the
+                // incoming one). Skip the clear ONLY when we already painted the
+                // incoming tab from cache — clearing would wipe that instant
+                // repaint. If there was NO cache paint, the shared terminal is
+                // still showing the OUTGOING session, so we MUST clear it;
+                // otherwise its content lingers into the incoming tab
+                // (cross-session bleed). session_joined repaints authoritatively.
+                if (!this._cachePaintedForSession) {
+                    this.terminal.clear();
+                }
                 
                 // Update tab status
                 if (this.sessionTabManager && message.sessionId) {
@@ -4035,6 +4141,8 @@ class ClaudeCodeWebInterface {
         if (cursorBlink) cursorBlink.checked = settings.cursorBlink ?? true;
         const scrollback = document.getElementById('scrollback');
         if (scrollback) scrollback.value = String(settings.scrollback || 1000);
+        const tabSnapshotLines = document.getElementById('tabSnapshotLines');
+        if (tabSnapshotLines) tabSnapshotLines.value = String(settings.tabSnapshotLines ?? 500);
         const terminalPadding = document.getElementById('terminalPadding');
         if (terminalPadding) terminalPadding.value = String(settings.terminalPadding ?? 8);
         const terminalPaddingValue = document.getElementById('terminalPaddingValue');
@@ -4375,7 +4483,8 @@ class ClaudeCodeWebInterface {
             notifSound: true,
             notifVolume: 30,
             notifDesktop: true,
-            enableSessionStickyNotes: true
+            enableSessionStickyNotes: true,
+            tabSnapshotLines: 500
         };
     }
 
@@ -4417,7 +4526,8 @@ class ClaudeCodeWebInterface {
             notifSound: document.getElementById('notifSound')?.checked ?? true,
             notifVolume: parseInt(document.getElementById('notifVolume')?.value || '30'),
             notifDesktop: document.getElementById('notifDesktop')?.checked ?? true,
-            enableSessionStickyNotes: document.getElementById('enableSessionStickyNotes')?.checked ?? true
+            enableSessionStickyNotes: document.getElementById('enableSessionStickyNotes')?.checked ?? true,
+            tabSnapshotLines: parseInt(document.getElementById('tabSnapshotLines')?.value || '500', 10)
         };
 
         try {
@@ -4466,6 +4576,11 @@ class ClaudeCodeWebInterface {
         this.terminal.options.cursorBlink = settings.cursorBlink ?? true;
         if (settings.scrollback) this.terminal.options.scrollback = settings.scrollback;
 
+        // Push the instant-snapshot line cap to the cache (0 disables capture+paint).
+        if (this.snapshotCache && settings.tabSnapshotLines !== undefined) {
+            this.snapshotCache.setMaxLines(settings.tabSnapshotLines);
+        }
+
         // Apply terminal padding
         const terminalEl = document.getElementById('terminal');
         if (terminalEl) {
@@ -5460,11 +5575,15 @@ class ClaudeCodeWebInterface {
             
             // Set a timeout in case the response never comes
             setTimeout(() => {
-                if (this.pendingJoinResolve) {
+                // Only clear if THIS join is still the pending one. A newer
+                // joinSession() may have replaced it; nulling the newer join's
+                // pending state would corrupt the cache/repaint guards that rely
+                // on it. resolve() is idempotent, so always settle this promise.
+                if (this.pendingJoinResolve === resolve) {
                     this.pendingJoinResolve = null;
                     this.pendingJoinSessionId = null;
-                    resolve(); // Resolve anyway after timeout
                 }
+                resolve(); // Resolve anyway after timeout
             }, 2000);
         });
     }

package/src/public/index.html

@@ -101,6 +101,7 @@
     <script src="https://unpkg.com/xterm-addon-unicode11@0.6.0/lib/xterm-addon-unicode11.js"></script>
     <script src="https://unpkg.com/xterm-addon-webgl@0.16.0/lib/xterm-addon-webgl.js"></script>
     <script src="https://unpkg.com/xterm-addon-canvas@0.5.0/lib/xterm-addon-canvas.js"></script>
+    <script src="https://unpkg.com/xterm-addon-serialize@0.11.0/lib/xterm-addon-serialize.js"></script>
     <link rel="stylesheet" href="https://unpkg.com/xterm@5.3.0/css/xterm.css" />
     <!-- Monaco editor is loaded lazily on first file preview/editor open via
          file-viewer-monaco.js (see ADR-0016). Preconnect above warms the
@@ -461,6 +462,15 @@
                                         <option value="50000">50,000 lines</option>
                                     </select>
                                 </div>
+                                <div class="setting-group">
+                                    <label for="tabSnapshotLines">Instant tab snapshot</label>
+                                    <select id="tabSnapshotLines">
+                                        <option value="0">Off</option>
+                                        <option value="200">200 lines</option>
+                                        <option value="500">500 lines</option>
+                                        <option value="2000">2,000 lines</option>
+                                    </select>
+                                </div>
                                 <div class="setting-group">
                                     <label for="terminalPadding">Padding</label>
                                     <span class="range-field">
@@ -844,6 +854,8 @@
     <script src="command-palette.js"></script>
     <script src="extra-keys.js"></script>
     <script src="input-overlay.js"></script>
+    <script src="join-repaint.js"></script>
+    <script src="terminal-snapshot-cache.js"></script>
     <script src="app.js"></script>
     <ninja-keys class="dark" id="commandPalette" hideBreadcrumbs></ninja-keys>
     

package/src/public/join-repaint.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * chooseJoinRepaint — decide how to repaint the shared terminal on (re)join.
+ *
+ * This is the crux of the #131 fix. The server may send a `renderedSnapshot`
+ * (rendered PLAIN TEXT via translateToString — no cursor/SGR/scroll state) and
+ * the raw `outputBuffer` (the real ANSI byte chunks). Writing the plain-text
+ * snapshot under a LIVE agent TUI leaves the cursor on the wrong row and the
+ * next incremental redraw collides with stale content (the garble regression).
+ *
+ * Rules:
+ *   - LIVE session (active): replay the raw outputBuffer (real ANSI) so the
+ *     live TUI redraw aligns. NEVER the plain-text snapshot. → 'buffer'
+ *     (or 'clear' when the buffer is empty — a brand-new just-started session).
+ *   - NON-live session (exited/idle): the plain-text snapshot is safe (nothing
+ *     redraws on top) and fixes blank-on-refresh (#131's legitimate goal). →
+ *     'snapshot', falling back to 'buffer' then 'clear'.
+ *
+ * Returns one of: 'buffer' | 'snapshot' | 'clear'.
+ */
+(function (global) {
+  function chooseJoinRepaint(message) {
+    const hasBuffer = !!(message && message.outputBuffer && message.outputBuffer.length > 0);
+    const hasSnapshot = !!(message && message.renderedSnapshot);
+    if (message && message.active) {
+      return hasBuffer ? 'buffer' : 'clear';
+    }
+    if (hasSnapshot) return 'snapshot';
+    if (hasBuffer) return 'buffer';
+    return 'clear';
+  }
+
+  global.chooseJoinRepaint = chooseJoinRepaint;
+  if (typeof module !== 'undefined' && module.exports) module.exports = { chooseJoinRepaint };
+})(typeof window !== 'undefined' ? window : globalThis);

package/src/public/session-manager.js

@@ -725,6 +725,24 @@ class SessionTabManager {
 
         const { skipHistoryUpdate = false } = options;
 
+        // Cancel any pending capture-on-settle: the shared terminal is about to
+        // repaint to the incoming tab, so a stale timer must not serialize it
+        // under the outgoing tab's id.
+        if (this.claudeInterface._snapCaptureTimer) {
+            clearTimeout(this.claudeInterface._snapCaptureTimer);
+            this.claudeInterface._snapCaptureTimer = null;
+        }
+
+        // Snapshot the OUTGOING tab's rendered screen so a later switch back can
+        // repaint it instantly — but only when no switch is already in flight,
+        // since otherwise the shared terminal may be showing a tab other than
+        // activeTabId and we'd cache the wrong content under previousTabId.
+        const previousTabId = this.activeTabId;
+        if (previousTabId && previousTabId !== sessionId &&
+            !this.claudeInterface.pendingJoinSessionId) {
+            this.claudeInterface.snapshotCache?.capture(previousTabId);
+        }
+
         // Remove active class from all tabs
         this.tabs.forEach(t => {
             t.classList.remove('active');
@@ -759,6 +777,20 @@ class SessionTabManager {
         this.updateOverflowMenu();
 
         // If tile view is enabled, tabs target the active pane (VS Code-style)
+        // Instant paint from the cache (faithful serialize snapshot) BEFORE the
+        // join round-trip, so the switch shows the target tab's last view
+        // immediately instead of lingering the previous tab's content. Record
+        // that we painted so session_joined's reconcile won't blank it on a
+        // 'clear' verdict (see app.js). session_joined repaints authoritatively.
+        const cachePainted = this.claudeInterface.snapshotCache?.paintCached(sessionId);
+        this.claudeInterface._cachePaintedForSession = cachePainted ? sessionId : null;
+        // When we painted the incoming tab from cache, drop any output frames
+        // still queued from the OUTGOING session so they can't flush on top of
+        // the instant repaint. They belong to the previous session, whose
+        // server-side buffer replays them on its next visit.
+        if (cachePainted && Array.isArray(this.claudeInterface._pendingWrites)) {
+            this.claudeInterface._pendingWrites.length = 0;
+        }
         await this.claudeInterface.joinSession(sessionId);
         this.updateHeaderInfo(sessionId);
 
@@ -846,6 +878,7 @@ class SessionTabManager {
         tab.remove();
         this.tabs.delete(sessionId);
         this.activeSessions.delete(sessionId);
+        this.claudeInterface.snapshotCache?.evict(sessionId);
         this.tabOrder = orderedIds.filter(id => id !== sessionId);
         this.removeFromHistory(sessionId);
 

package/src/public/terminal-snapshot-cache.js

@@ -0,0 +1,295 @@
+'use strict';
+
+/**
+ * TerminalSnapshotCache — instant, faithful per-tab terminal repaint.
+ *
+ * Problem it solves: there is ONE shared xterm terminal for all tabs. On tab
+ * switch the terminal is repainted only by the server round-trip
+ * (join_session -> session_joined), so until that lands the previous tab's
+ * content lingers. This cache paints the target tab's last rendered view
+ * INSTANTLY from a client-side snapshot, decoupled from the round-trip; the
+ * server reply then reconciles authoritatively.
+ *
+ * Fidelity: snapshots are produced by xterm's serialize addon, which emits the
+ * already-rendered buffer with absolute SGR + a final cursor-positioning
+ * sequence. Writing that into a freshly-cleared terminal reproduces the screen
+ * faithfully (cursor + colors), unlike a plain-text dump.
+ *
+ * Tiers:
+ *   - Tier 1 (in-memory Map): authoritative for the instant paint, synchronous.
+ *   - Tier 2 (IndexedDB): survives a page reload. Throttled writes, LRU-bounded.
+ *
+ * Robustness: every IndexedDB call is guarded; on any failure the cache runs
+ * MEMORY-ONLY (instant in-session switching still works, only reload-restore is
+ * lost) and never throws into the caller's switch/render path. Setting
+ * maxLines to 0 disables capture + paint entirely (a pure pass-through).
+ */
+(function (global) {
+  const DB_NAME = 'cc-terminal-cache';
+  const DB_VERSION = 1;
+  const STORE = 'snapshots';
+  const PER_RECORD_CAP_BYTES = 256 * 1024; // skip persisting anything larger (keep in memory only)
+  const TOTAL_BUDGET_BYTES = 6 * 1024 * 1024; // LRU-evict oldest beyond this
+  const PERSIST_DEBOUNCE_MS = 1000;
+
+  const byteLen = (s) => {
+    try { return (typeof TextEncoder !== 'undefined') ? new TextEncoder().encode(s).length : (s ? s.length : 0); }
+    catch (_) { return s ? s.length : 0; }
+  };
+
+  class TerminalSnapshotCache {
+    constructor({ terminal, serializeAddon, maxLines = 500 } = {}) {
+      this.terminal = terminal;
+      this.serializeAddon = serializeAddon || null;
+      this.maxLines = Number.isFinite(maxLines) ? maxLines : 500;
+      this._mem = new Map(); // sessionId -> { text, cols, updatedAt, bytes }
+      this._lastPainted = null; // last text written via paintCached/reconcile
+      this._db = null;
+      this._persistDisabled = false;
+      this._dirty = new Set();
+      this._persistTimer = null;
+      this._ready = false;
+    }
+
+    /** Open IndexedDB and hydrate the in-memory map. Never throws. */
+    async init() {
+      if (this._ready) return;
+      this._ready = true;
+      if (typeof indexedDB === 'undefined') { this._persistDisabled = true; return; }
+      try {
+        this._db = await this._openDb();
+        await this._hydrateFromDisk();
+        // Persist any snapshots captured before the DB finished opening — their
+        // _schedulePersist() no-opped while _db was still null.
+        if (this._dirty.size > 0) this._schedulePersist();
+      } catch (err) {
+        // Private mode / blocked / corrupt — degrade to memory-only.
+        this._persistDisabled = true;
+        this._db = null;
+        try { console.warn('[snapshot-cache] persistence disabled (memory-only):', err && err.message); } catch (_) {}
+      }
+    }
+
+    _openDb() {
+      return new Promise((resolve, reject) => {
+        let req;
+        try { req = indexedDB.open(DB_NAME, DB_VERSION); }
+        catch (e) { reject(e); return; }
+        req.onupgradeneeded = () => {
+          const db = req.result;
+          if (!db.objectStoreNames.contains(STORE)) {
+            db.createObjectStore(STORE, { keyPath: 'sessionId' });
+          }
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error || new Error('indexedDB open failed'));
+        req.onblocked = () => reject(new Error('indexedDB blocked'));
+      });
+    }
+
+    async _hydrateFromDisk() {
+      if (!this._db) return;
+      const records = await this._txAll();
+      for (const r of records) {
+        if (r && r.sessionId && typeof r.text === 'string') {
+          // Don't let a stale persisted record overwrite a fresher in-memory
+          // snapshot that was captured before this async hydrate completed.
+          const existing = this._mem.get(r.sessionId);
+          if (existing && (existing.updatedAt || 0) >= (r.updatedAt || 0)) continue;
+          this._mem.set(r.sessionId, {
+            text: r.text,
+            cols: r.cols || 0,
+            updatedAt: r.updatedAt || 0,
+            bytes: r.bytes || byteLen(r.text),
+          });
+        }
+      }
+    }
+
+    _txAll() {
+      return new Promise((resolve, reject) => {
+        try {
+          const tx = this._db.transaction(STORE, 'readonly');
+          const req = tx.objectStore(STORE).getAll();
+          req.onsuccess = () => resolve(req.result || []);
+          req.onerror = () => reject(req.error || new Error('getAll failed'));
+        } catch (e) { reject(e); }
+      });
+    }
+
+    setMaxLines(n) {
+      const v = parseInt(n, 10);
+      if (Number.isFinite(v) && v >= 0) this.maxLines = v;
+    }
+
+    /** True if there is a cached snapshot for this session. */
+    has(sessionId) {
+      return !!sessionId && this._mem.has(sessionId);
+    }
+
+    /**
+     * Serialize the CURRENT terminal screen and store it under sessionId.
+     * Call this for the tab that is currently shown (active/outgoing), never
+     * per output frame — only when the screen has settled or on switch-away.
+     */
+    capture(sessionId) {
+      if (!sessionId || this.maxLines <= 0 || !this.serializeAddon || !this.terminal) return;
+      let text;
+      try {
+        text = this.serializeAddon.serialize({ scrollback: this.maxLines });
+      } catch (err) {
+        try { console.warn('[snapshot-cache] serialize failed:', err && err.message); } catch (_) {}
+        return;
+      }
+      if (typeof text !== 'string' || text.length === 0) return;
+      const bytes = byteLen(text);
+      this._mem.set(sessionId, {
+        text,
+        cols: (this.terminal.cols | 0) || 0,
+        updatedAt: this._now(),
+        bytes,
+      });
+      // Bound the in-memory tier in EVERY mode. The persist path's eviction is
+      // skipped when persistence is disabled or the DB isn't open yet, so
+      // memory-only / private-mode would otherwise grow unbounded.
+      this._evictLruOverBudget();
+      this._dirty.add(sessionId);
+      this._schedulePersist();
+    }
+
+    /**
+     * Instantly repaint the terminal from the cached snapshot for sessionId.
+     * Returns true if it painted, false if there was no entry (caller then
+     * relies on the server repaint). maxLines === 0 disables (returns false).
+     */
+    paintCached(sessionId) {
+      if (!sessionId || this.maxLines <= 0 || !this.terminal) return false;
+      const entry = this._mem.get(sessionId);
+      if (!entry || !entry.text) return false;
+      try {
+        this.terminal.clear();
+        this.terminal.write(entry.text);
+        this._lastPainted = entry.text;
+        return true;
+      } catch (err) {
+        try { console.warn('[snapshot-cache] paint failed:', err && err.message); } catch (_) {}
+        return false;
+      }
+    }
+
+    /** Drop the cached snapshot for a deleted session (memory + disk). */
+    evict(sessionId) {
+      if (!sessionId) return;
+      this._mem.delete(sessionId);
+      this._dirty.delete(sessionId);
+      this._deleteFromDisk(sessionId);
+    }
+
+    /** Remove cached snapshots for sessions that no longer exist. */
+    pruneOrphans(liveIds) {
+      let live;
+      try { live = new Set(liveIds || []); } catch (_) { return; }
+      for (const id of Array.from(this._mem.keys())) {
+        if (!live.has(id)) this.evict(id);
+      }
+    }
+
+    // ---- persistence internals (all guarded; never throw to callers) ----
+
+    _now() {
+      // Date.now() is fine in the browser; only the workflow sandbox forbids it.
+      try { return Date.now(); } catch (_) { return 0; }
+    }
+
+    _schedulePersist() {
+      if (this._persistDisabled || !this._db) return;
+      if (this._persistTimer) return;
+      this._persistTimer = setTimeout(() => {
+        this._persistTimer = null;
+        this._persistNow();
+      }, PERSIST_DEBOUNCE_MS);
+    }
+
+    async _persistNow() {
+      if (this._persistDisabled || !this._db) { this._dirty.clear(); return; }
+      // Enforce the total byte budget by evicting oldest entries first.
+      this._evictLruOverBudget();
+      const ids = Array.from(this._dirty);
+      this._dirty.clear();
+      for (const id of ids) {
+        const entry = this._mem.get(id);
+        if (!entry) { this._deleteFromDisk(id); continue; }
+        // Too large to persist: keep it in memory, but drop any stale on-disk
+        // copy so a reload doesn't hydrate an older snapshot for this session.
+        if (entry.bytes > PER_RECORD_CAP_BYTES) { this._deleteFromDisk(id); continue; }
+        try { await this._putOnDisk(id, entry); }
+        catch (err) {
+          // Quota exceeded: evict half by age, retry once, then disable persistence.
+          if (err && (err.name === 'QuotaExceededError' || /quota/i.test(err.message || ''))) {
+            this._evictLruHalf();
+            try { await this._putOnDisk(id, this._mem.get(id)); }
+            catch (_) { this._persistDisabled = true; }
+          } else {
+            try { console.warn('[snapshot-cache] persist failed:', err && err.message); } catch (_) {}
+          }
+        }
+      }
+    }
+
+    _evictLruOverBudget() {
+      let total = 0;
+      for (const e of this._mem.values()) total += e.bytes || 0;
+      if (total <= TOTAL_BUDGET_BYTES) return;
+      const byAge = Array.from(this._mem.entries()).sort((a, b) => a[1].updatedAt - b[1].updatedAt);
+      for (const [id, e] of byAge) {
+        if (total <= TOTAL_BUDGET_BYTES) break;
+        total -= e.bytes || 0;
+        this._mem.delete(id);
+        this._dirty.delete(id);
+        this._deleteFromDisk(id);
+      }
+    }
+
+    _evictLruHalf() {
+      const byAge = Array.from(this._mem.entries()).sort((a, b) => a[1].updatedAt - b[1].updatedAt);
+      const drop = Math.ceil(byAge.length / 2);
+      for (let i = 0; i < drop; i++) {
+        const id = byAge[i][0];
+        this._mem.delete(id);
+        this._dirty.delete(id);
+        this._deleteFromDisk(id);
+      }
+    }
+
+    _putOnDisk(sessionId, entry) {
+      return new Promise((resolve, reject) => {
+        if (!this._db || !entry) { resolve(); return; }
+        try {
+          const tx = this._db.transaction(STORE, 'readwrite');
+          tx.objectStore(STORE).put({
+            sessionId,
+            text: entry.text,
+            cols: entry.cols,
+            updatedAt: entry.updatedAt,
+            bytes: entry.bytes,
+          });
+          tx.oncomplete = () => resolve();
+          tx.onerror = () => reject(tx.error || new Error('put failed'));
+          tx.onabort = () => reject(tx.error || new Error('put aborted'));
+        } catch (e) { reject(e); }
+      });
+    }
+
+    _deleteFromDisk(sessionId) {
+      if (this._persistDisabled || !this._db) return;
+      try {
+        const tx = this._db.transaction(STORE, 'readwrite');
+        tx.objectStore(STORE).delete(sessionId);
+      } catch (_) { /* best-effort */ }
+    }
+  }
+
+  global.TerminalSnapshotCache = TerminalSnapshotCache;
+  // CommonJS export for unit tests (Node/mocha) — harmless in the browser.
+  if (typeof module !== 'undefined' && module.exports) module.exports = TerminalSnapshotCache;
+})(typeof window !== 'undefined' ? window : globalThis);