tabminal 2.0.11 → 2.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tabminal",
-  "version": "2.0.11",
+  "version": "2.0.13",
   "description": "A modern, persistent web terminal with multi-tab support and real-time system monitoring.",
   "type": "module",
   "bin": {
@@ -43,7 +43,9 @@
     "node-pty": "^1.1.0",
     "openai": "^6.32.0",
     "utilitas": "^2001.1.135",
-    "ws": "^8.19.0"
+    "ws": "^8.19.0",
+    "xterm-addon-serialize": "^0.11.0",
+    "xterm-headless": "^5.3.0"
   },
   "repository": {
     "type": "git",

package/public/app.js

@@ -977,8 +977,13 @@ class Session {
         this.layoutState = {
             editorFlex: '2 1 0%'
         };
+        this.wrapperElement = null;
+        this._createTerminals();
 
-        // Preview Terminal (Always create instance to maintain logic consistency)
+        this.connect();
+    }
+
+    _createTerminals() {
         this.previewTerm = new Terminal({
             disableStdin: true,
             cursorBlink: false,
@@ -986,17 +991,18 @@ class Session {
             fontSize: 10,
             rows: this.rows,
             cols: this.cols,
-            theme: { background: '#002b36', foreground: '#839496', cursor: 'transparent', selectionBackground: 'transparent' }
+            theme: {
+                background: '#002b36',
+                foreground: '#839496',
+                cursor: 'transparent',
+                selectionBackground: 'transparent'
+            }
         });
-        
-        // Only load CanvasAddon on Desktop to save GPU memory
+
         if (window.innerWidth >= 768) {
             this.previewTerm.loadAddon(new CanvasAddon());
         }
-        
-        this.wrapperElement = null;
 
-        // Main Terminal
         this.mainTerm = new Terminal({
             allowTransparency: true,
             convertEol: true,
@@ -1005,7 +1011,13 @@ class Session {
             fontSize: IS_MOBILE ? 14 : 12,
             rows: this.rows,
             cols: this.cols,
-            theme: { background: '#002b36', foreground: '#839496', cursor: '#93a1a1', cursorAccent: '#002b36', selectionBackground: '#073642' }
+            theme: {
+                background: '#002b36',
+                foreground: '#839496',
+                cursor: '#93a1a1',
+                cursorAccent: '#002b36',
+                selectionBackground: '#073642'
+            }
         });
         this.mainFitAddon = new FitAddon();
         this.mainLinksAddon = new WebLinksAddon();
@@ -1015,21 +1027,54 @@ class Session {
         this.mainTerm.loadAddon(this.searchAddon);
         this.mainTerm.loadAddon(new CanvasAddon());
 
-        // Event Listeners
-        this.mainTerm.onData(data => {
+        this.mainTerm.onData((data) => {
             if (this.isRestoring) return;
             this.send({ type: 'input', data });
         });
 
-        this.mainTerm.onResize(size => {
+        this.mainTerm.onResize((size) => {
             this.previewTerm.resize(size.cols, size.rows);
             this.updatePreviewScale();
-            
+
             const pending = getPendingSession(this.key);
             pending.resize = { cols: size.cols, rows: size.rows };
         });
+    }
 
-        this.connect();
+    recreateTerminals() {
+        const wasActive = state.activeSessionKey === this.key;
+        const previewWrapper = this.wrapperElement;
+
+        try {
+            this.previewTerm?.dispose();
+        } catch (e) {
+            if (!e.message?.includes('onRequestRedraw')) {
+                console.warn('Error disposing preview terminal:', e);
+            }
+        }
+
+        try {
+            this.mainTerm?.dispose();
+        } catch (e) {
+            if (!e.message?.includes('onRequestRedraw')) {
+                console.warn('Error disposing main terminal:', e);
+            }
+        }
+
+        this._createTerminals();
+
+        if (previewWrapper && window.innerWidth >= 768) {
+            previewWrapper.innerHTML = '';
+            this.previewTerm.open(previewWrapper);
+            this.updatePreviewScale();
+        }
+
+        if (wasActive && terminalEl) {
+            terminalEl.innerHTML = '';
+            this.mainTerm.open(terminalEl);
+            this.mainFitAddon.fit();
+            this.mainTerm.focus();
+        }
     }
 
     update(data) {
@@ -1187,15 +1232,19 @@ class Session {
     handleMessage(message) {
         switch (message.type) {
             case 'snapshot':
-                if (this.previewTerm) this.previewTerm.reset();
-                this.mainTerm.reset();
-                this.history = message.data || '';
                 this.isRestoring = true;
-                if (this.previewTerm) this.previewTerm.write(this.history);
-                this.mainTerm.write(this.history, () => { this.isRestoring = false; });
+                this.recreateTerminals();
+                if (this.previewTerm) this.previewTerm.write(message.data || '');
+                this.mainTerm.write(message.data || '', () => {
+                    this.isRestoring = false;
+                    if (state.activeSessionKey === this.key) {
+                        this.mainFitAddon.fit();
+                        this.mainTerm.focus();
+                        this.reportResize();
+                    }
+                });
                 break;
             case 'output':
-                this.history += message.data;
                 this.writeToTerminals(message.data);
                 break;
             case 'meta':

package/shell/tabminal-bashrc

@@ -0,0 +1,17 @@
+if [[ -n "${TABMINAL_SHELL_TOOLS_PATH:-}" ]]; then
+    export PATH="${TABMINAL_SHELL_TOOLS_PATH}:$PATH"
+fi
+
+if [[ -f ~/.bashrc ]]; then
+    source ~/.bashrc
+fi
+
+if [[ -n "${TABMINAL_SHELL_TOOLS_PATH:-}" ]]; then
+    export PATH="${TABMINAL_SHELL_TOOLS_PATH}:$PATH"
+fi
+
+if [[ -n "${TABMINAL_HOOKS_PATH:-}" ]] && [[ -f "$TABMINAL_HOOKS_PATH" ]]; then
+    source "$TABMINAL_HOOKS_PATH"
+fi
+
+TABMINAL_SHELL_READY=1

package/shell/tabminal-hooks.bash

@@ -0,0 +1,78 @@
+if [[ -z "${TABMINAL_SESSION_ID:-}" ]]; then
+    return 0
+fi
+
+if [[ -n "${TABMINAL_BASH_HOOKS_LOADED:-}" ]]; then
+    return 0
+fi
+
+TABMINAL_BASH_HOOKS_LOADED=1
+
+_tabminal_bash_preexec() {
+    if [[ "${BASH_COMMAND:-}" == *"_tabminal_"* ]]; then
+        return
+    fi
+    if [[ "${BASH_COMMAND:-}" == "${PROMPT_COMMAND:-}" ]]; then
+        return
+    fi
+    _tabminal_last_command="$BASH_COMMAND"
+}
+
+_tabminal_bash_postexec() {
+    local exit_code="$?"
+    if [[ -n "${_tabminal_last_command:-}" ]]; then
+        local command_b64
+        command_b64=$(
+            echo -n "$_tabminal_last_command" | base64 | tr -d '\n'
+        )
+        printf '\x1b]1337;ExitCode=%s;CommandB64=%s\x07' \
+            "$exit_code" "$command_b64"
+        _tabminal_last_command=''
+    fi
+}
+
+_tabminal_apply_prompt_marker() {
+    local marker=$'\[\e]1337;TabminalPrompt\a\]'
+    if [[ "${PS1:-}" != *'TabminalPrompt'* ]]; then
+        PS1="${PS1}${marker}"
+    fi
+}
+
+_tabminal_prompt_contains() {
+    local needle="$1"
+    local current="${PROMPT_COMMAND:-}"
+    [[ "$current" == *"$needle"* ]]
+}
+
+_tabminal_install_prompt_command() {
+    if ! _tabminal_prompt_contains '_tabminal_bash_postexec'; then
+        if [[ -n "${PROMPT_COMMAND:-}" ]]; then
+            printf -v PROMPT_COMMAND '_tabminal_bash_postexec; %s' \
+                "$PROMPT_COMMAND"
+        else
+            PROMPT_COMMAND='_tabminal_bash_postexec'
+        fi
+    fi
+
+    if ! _tabminal_prompt_contains '_tabminal_apply_prompt_marker'; then
+        if [[ -n "${PROMPT_COMMAND:-}" ]]; then
+            PROMPT_COMMAND="${PROMPT_COMMAND}; _tabminal_apply_prompt_marker"
+        else
+            PROMPT_COMMAND='_tabminal_apply_prompt_marker'
+        fi
+    fi
+}
+
+_tabminal_install_tmux_wrapper() {
+    if ! command -v tmux >/dev/null 2>&1; then
+        return 0
+    fi
+
+    tmux() {
+        command tmux -u "$@"
+    }
+}
+
+trap '_tabminal_bash_preexec' DEBUG
+_tabminal_install_prompt_command
+_tabminal_install_tmux_wrapper

package/src/persistence.mjs

@@ -7,6 +7,7 @@ const BASE_DIR = path.join(HOME_DIR, '.tabminal');
 const SESSIONS_DIR = path.join(BASE_DIR, 'sessions');
 const MEMORY_FILE = path.join(BASE_DIR, 'memory.json');
 const CLUSTER_FILE = path.join(BASE_DIR, 'cluster.json');
+const getSessionSnapshotPath = (id) => path.join(SESSIONS_DIR, `${id}.snapshot`);
 
 // Ensure directories exist
 const init = async () => {
@@ -45,6 +46,7 @@ export const saveSession = async (id, data) => {
 export const deleteSession = async (id) => {
     const jsonPath = path.join(SESSIONS_DIR, `${id}.json`);
     const logPath = path.join(SESSIONS_DIR, `${id}.log`);
+    const snapshotPath = getSessionSnapshotPath(id);
     
     try {
         await fs.unlink(jsonPath);
@@ -57,6 +59,12 @@ export const deleteSession = async (id) => {
     } catch (e) {
         if (e.code !== 'ENOENT') console.error(`[Persistence] Failed to delete session log ${id}:`, e);
     }
+
+    try {
+        await fs.unlink(snapshotPath);
+    } catch (e) {
+        if (e.code !== 'ENOENT') console.error(`[Persistence] Failed to delete session snapshot ${id}:`, e);
+    }
 };
 
 export const loadSessions = async () => {
@@ -197,6 +205,16 @@ export const appendSessionLog = async (id, chunk) => {
     }
 };
 
+export const saveSessionSnapshot = async (id, snapshot) => {
+    await init();
+    const filePath = getSessionSnapshotPath(id);
+    try {
+        await fs.writeFile(filePath, snapshot, 'utf8');
+    } catch (e) {
+        console.error(`[Persistence] Failed to save snapshot for ${id}:`, e);
+    }
+};
+
 export const loadSessionLog = async (id, limit = 1024 * 1024) => {
     const filePath = path.join(SESSIONS_DIR, `${id}.log`);
     try {
@@ -218,3 +236,19 @@ export const loadSessionLog = async (id, limit = 1024 * 1024) => {
         return '';
     }
 };
+
+export const loadSessionSnapshot = async (id) => {
+    const filePath = getSessionSnapshotPath(id);
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    } catch (e) {
+        if (e.code !== 'ENOENT') {
+            console.error(
+                `[Persistence] Failed to load snapshot for ${id}:`,
+                e
+            );
+        }
+    }
+
+    return loadSessionLog(id);
+};

package/src/terminal-manager.mjs

@@ -37,9 +37,29 @@ const initialRows = Number.parseInt(
     10
 ) || 30;
 
+function buildBashBootstrap({
+    env,
+    shell,
+    shellToolsPath,
+    sessionId
+}) {
+    const hookPath = path.join(shellToolsPath, 'tabminal-hooks.bash');
+    const rcfilePath = path.join(shellToolsPath, 'tabminal-bashrc');
+
+    env.TABMINAL_SESSION_ID = sessionId;
+    env.TABMINAL_SHELL_TOOLS_PATH = shellToolsPath;
+    env.TABMINAL_HOOKS_PATH = hookPath;
+
+    return {
+        shell,
+        args: ['--rcfile', rcfilePath, '-i']
+    };
+}
+
 export class TerminalManager {
     constructor() {
         this.sessions = new Map();
+        this.snapshotPersistTimers = new Map();
         this.lastCols = initialCols;
         this.lastRows = initialRows;
         this.disposing = false;
@@ -66,55 +86,25 @@ export class TerminalManager {
             ? `${shellToolsPath}${pathDelimiter}${existingPath}`
             : shellToolsPath;
 
+        let spawnShell = shell;
         let args = [];
-        let initFilePath = null;
         let initDirPath = null;
 
         try {
             const shellName = path.basename(shell);
             if (shellName === 'bash') {
-                initFilePath = path.join(os.tmpdir(), `tabminal-init-${id}.bashrc`);
-                const bashScript = `
-export PATH="${shellToolsPath}:$PATH"
-[ -f ~/.bashrc ] && source ~/.bashrc
-export PATH="${shellToolsPath}:$PATH"
-
-_tabminal_bash_preexec() {
-  # Prevent capturing any of our own internal or setup commands.
-  if [[ "$BASH_COMMAND" == *"_tabminal_"* || "$BASH_COMMAND" == "$PROMPT_COMMAND" ]]; then
-    return
-  fi
-  _tabminal_last_command="$BASH_COMMAND"
-}
-trap '_tabminal_bash_preexec' DEBUG
-
-_tabminal_bash_postexec() {
-  local EC="$?"
-  if [[ -n "$_tabminal_last_command" ]]; then
-    local CMD=$(echo -n "$_tabminal_last_command" | base64 | tr -d '\\n')
-    printf "\\x1b]1337;ExitCode=%s;CommandB64=%s\\x07" "$EC" "$CMD"
-    _tabminal_last_command="" # Reset after use
-  fi
-}
-_tabminal_apply_prompt_marker() {
-  local marker=$'\\[\\e]1337;TabminalPrompt\\a\\]'
-  if [[ "$PS1" != *"TabminalPrompt"* ]]; then
-    PS1="$PS1$marker"
-  fi
-}
-if [[ -n "$PROMPT_COMMAND" ]]; then
-  printf -v PROMPT_COMMAND "_tabminal_bash_postexec; %s; _tabminal_apply_prompt_marker" "$PROMPT_COMMAND"
-else
-  PROMPT_COMMAND="_tabminal_bash_postexec; _tabminal_apply_prompt_marker"
-fi
-export PROMPT_COMMAND
-`;
-                fs.writeFileSync(initFilePath, bashScript);
-                args = ['--rcfile', initFilePath, '-i'];
+                const bootstrap = buildBashBootstrap({
+                    env,
+                    shell,
+                    shellToolsPath,
+                    sessionId: id
+                });
+                spawnShell = bootstrap.shell;
+                args = bootstrap.args;
             } else if (shellName === 'zsh') {
                 initDirPath = path.join(os.tmpdir(), `tabminal-zsh-${id}`);
                 fs.mkdirSync(initDirPath, { recursive: true });
-                initFilePath = path.join(initDirPath, '.zshrc');
+                const initFilePath = path.join(initDirPath, '.zshrc');
 
                 const zshScript = `
 unset ZDOTDIR
@@ -165,10 +155,11 @@ precmd_functions+=(_tabminal_zsh_apply_prompt_marker)
             if (process.platform !== 'win32') {
                 ptyOptions.encoding = 'utf8';
             }
-            ptyProcess = pty.spawn(shell, args, ptyOptions);
+            ptyProcess = pty.spawn(spawnShell, args, ptyOptions);
         } catch (err) {
             const spawnInfo = {
-                shell,
+                shell: spawnShell,
+                requestedShell: shell,
                 args,
                 cwd: initialCwd,
                 cols,
@@ -202,8 +193,10 @@ precmd_functions+=(_tabminal_zsh_apply_prompt_marker)
         });
 
         if (restoredData) {
-            persistence.loadSessionLog(id).then(log => {
-                if (log) session.history = log;
+            persistence.loadSessionSnapshot(id).then(async (snapshot) => {
+                if (!snapshot) return;
+                await session.restoreSnapshot(snapshot);
+                this.scheduleSnapshotPersist(id);
             });
         }
 
@@ -214,7 +207,6 @@ precmd_functions+=(_tabminal_zsh_apply_prompt_marker)
             this.removeSession(id);
             // Cleanup temp files
             try {
-                if (initFilePath && fs.existsSync(initFilePath)) fs.unlinkSync(initFilePath);
                 if (initDirPath && fs.existsSync(initDirPath)) fs.rmSync(initDirPath, { recursive: true, force: true });
             } catch { /* ignore cleanup errors */ }
         });
@@ -249,8 +241,25 @@ precmd_functions+=(_tabminal_zsh_apply_prompt_marker)
         }
     }
 
-    appendLog(id, chunk) {
-        persistence.appendSessionLog(id, chunk);
+    scheduleSnapshotPersist(id) {
+        const session = this.sessions.get(id);
+        if (!session) return;
+
+        const existing = this.snapshotPersistTimers.get(id);
+        if (existing) {
+            clearTimeout(existing);
+        }
+
+        const timer = setTimeout(async () => {
+            this.snapshotPersistTimers.delete(id);
+            const currentSession = this.sessions.get(id);
+            if (!currentSession) return;
+
+            const snapshot = await currentSession.serializeSnapshot();
+            await persistence.saveSessionSnapshot(id, snapshot);
+        }, 250);
+
+        this.snapshotPersistTimers.set(id, timer);
     }
 
     getSession(id) {
@@ -274,6 +283,11 @@ precmd_functions+=(_tabminal_zsh_apply_prompt_marker)
     removeSession(id) {
         const session = this.sessions.get(id);
         if (session) {
+            const timer = this.snapshotPersistTimers.get(id);
+            if (timer) {
+                clearTimeout(timer);
+                this.snapshotPersistTimers.delete(id);
+            }
             session.dispose();
             this.sessions.delete(id);
             persistence.deleteSession(id);
@@ -300,6 +314,10 @@ precmd_functions+=(_tabminal_zsh_apply_prompt_marker)
     dispose() {
         debugLog('[Manager] Disposing all sessions.');
         this.disposing = true;
+        for (const timer of this.snapshotPersistTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.snapshotPersistTimers.clear();
         for (const session of this.sessions.values()) {
             try {
                 if (process.platform === 'win32') {

package/src/terminal-session.mjs

@@ -6,10 +6,15 @@ import { alan } from 'utilitas';
 import { config } from './config.mjs';
 
 const execAsync = promisify(exec);
+const {
+    HeadlessTerminal,
+    SerializeAddon
+} = await loadHeadlessXtermPackages();
 const WS_STATE_OPEN = 1;
 const DEFAULT_HISTORY_LIMIT = 512 * 1024; // chars
 const OSC_SEQUENCE_REGEX =
     /\u001b\]1337;(ExitCode=(\d+);CommandB64=([a-zA-Z0-9+/=]+)|TabminalPrompt)\u0007/g;
+const EXTRA_PRIVATE_MODE_REGEX = /\u001b\[\?(1005|1006|1015)([hl])/g;
 const CSI_SEQUENCE_REGEX = /\u001b\[[0-9;?]*[ -\/]*[@-~]/g;
 const OSC_STRIP_REGEX = /\u001b\][\s\S]*?(?:\u0007|\u001b\\)/g;
 const DCS_SEQUENCE_REGEX = /\u001bP[\s\S]*?(?:\u0007|\u001b\\)/g;
@@ -20,11 +25,71 @@ const TITLE_POLL_INTERVAL_MS = 3000;
 
 const IGNORED_COMMANDS = [
     'export PROMPT_COMMAND',
-    '__bash_prompt'
+    '__bash_prompt',
+    'TABMINAL_SHELL_READY=1'
 ];
 
 const PROMPT_PREFIX = "You are now operating as an AI terminal assistant. Your name is `Tabminal`. You will assist users in resolving terminal or coding issues and answering other inquiries. When troubleshooting terminal errors, you will be provided with the execution history to understand the context. However, please focus primarily on the most recent runtime errors and the user's latest questions. Keep your answers concise and accurate. Resolve the issue clearly and provide the reasoning while avoiding lengthy elaborations. Most user terminal variable keys are normal under typical circumstances and do not need to be treated as security risks.\n\n";
 
+async function loadHeadlessXtermPackages() {
+    const hadNavigator = Object.prototype.hasOwnProperty.call(
+        globalThis,
+        'navigator'
+    );
+    const navigatorDescriptor = hadNavigator
+        ? Object.getOwnPropertyDescriptor(globalThis, 'navigator')
+        : null;
+
+    if (hadNavigator) {
+        delete globalThis.navigator;
+    }
+
+    try {
+        const headlessPackage = await import('xterm-headless');
+        const serializePackage = await import('xterm-addon-serialize');
+        const { Terminal } = headlessPackage.default ?? headlessPackage;
+        const { SerializeAddon } = serializePackage.default ?? serializePackage;
+        return {
+            HeadlessTerminal: Terminal,
+            SerializeAddon
+        };
+    } finally {
+        if (hadNavigator && navigatorDescriptor) {
+            Object.defineProperty(
+                globalThis,
+                'navigator',
+                navigatorDescriptor
+            );
+        }
+    }
+}
+
+function splitTrailingPartialSequence(chunk) {
+    if (!chunk) {
+        return { complete: '', partial: '' };
+    }
+
+    const oscStart = chunk.lastIndexOf('\u001b]1337;');
+    if (oscStart >= 0) {
+        const oscTail = chunk.slice(oscStart);
+        if (!oscTail.includes('\u0007')) {
+            return {
+                complete: chunk.slice(0, oscStart),
+                partial: oscTail
+            };
+        }
+    }
+
+    return { complete: chunk, partial: '' };
+}
+
+function estimateSnapshotScrollback(cols, rows, historyLimit) {
+    const safeCols = Math.max(1, cols || 80);
+    const safeRows = Math.max(24, rows || 24);
+    const estimatedRows = Math.ceil(historyLimit / safeCols);
+    return Math.max(safeRows, Math.min(50000, estimatedRows));
+}
+
 export class TerminalSession {
     constructor(pty, options = {}) {
         this.pty = pty;
@@ -49,12 +114,35 @@ export class TerminalSession {
         this.historyLimit = Math.max(1, options.historyLimit ?? DEFAULT_HISTORY_LIMIT);
         this.history = '';
         this.clients = new Set();
+        this.pendingClients = new Map();
         this.closed = false;
         this.pollingInterval = null;
         this.captureBuffer = '';
         this.captureStartedAt = null;
         this.lastExecution = null;
         this.skipNextShellLog = false;
+        this.partialSequenceBuffer = '';
+        this.snapshotScrollback = estimateSnapshotScrollback(
+            this.pty.cols,
+            this.pty.rows,
+            this.historyLimit
+        );
+        this.snapshotTerminal = new HeadlessTerminal({
+            cols: this.pty.cols,
+            rows: this.pty.rows,
+            scrollback: this.snapshotScrollback,
+            allowProposedApi: true,
+            convertEol: true,
+            logLevel: 'off'
+        });
+        this.snapshotSerializeAddon = new SerializeAddon();
+        this.snapshotTerminal.loadAddon(this.snapshotSerializeAddon);
+        this.snapshotWritePromise = Promise.resolve();
+        this.extraPrivateModes = {
+            1005: false,
+            1006: false,
+            1015: false
+        };
 
         this.ansiParser = new AnsiParser({
             inst_o: (s) => {
@@ -83,10 +171,13 @@ export class TerminalSession {
             if (this.suppressPtyOutput) return;
 
             if (typeof chunk !== 'string') chunk = chunk.toString('utf8');
-
-            if (this.manager) {
-                this.manager.appendLog(this.id, chunk);
+            if (this.partialSequenceBuffer) {
+                chunk = this.partialSequenceBuffer + chunk;
+                this.partialSequenceBuffer = '';
             }
+            const split = splitTrailingPartialSequence(chunk);
+            chunk = split.complete;
+            this.partialSequenceBuffer = split.partial;
 
             let cleaned = '';
             let lastIndex = 0;
@@ -120,8 +211,12 @@ export class TerminalSession {
 
             if (!cleaned) return;
 
+            this._appendSnapshotData(cleaned);
             this._appendHistory(cleaned);
             this.ansiParser.parse(cleaned);
+            if (this.manager?.scheduleSnapshotPersist) {
+                this.manager.scheduleSnapshotPersist(this.id);
+            }
             this._broadcast({ type: 'output', data: cleaned });
         };
 
@@ -244,36 +339,57 @@ export class TerminalSession {
 
     attach(ws) {
         if (!ws) throw new Error('WebSocket instance required');
-        this.clients.add(ws);
-        ws.once('close', () => this.clients.delete(ws));
+        this.pendingClients.set(ws, []);
+        ws.once('close', () => {
+            this.clients.delete(ws);
+            this.pendingClients.delete(ws);
+        });
         ws.on('message', (raw) => this._routeIncoming(raw, ws));
         ws.on('error', () => ws.close());
 
-        this._send(ws, { type: 'snapshot', data: this.history });
-        this._send(ws, { type: 'meta', title: this.title, cwd: this.cwd, env: this.env, cols: this.pty.cols, rows: this.pty.rows });
-        if (this.closed) {
-            this._send(ws, { type: 'status', status: 'terminated' });
-        } else {
-            this._send(ws, { type: 'status', status: 'ready' });
-        }
+        void this._sendInitialState(ws);
     }
 
     dispose() {
         this.stopTitlePolling();
         this.clients.clear();
+        this.pendingClients.clear();
         this.dataSubscription?.dispose?.();
         this.exitSubscription?.dispose?.();
+        this.snapshotTerminal?.dispose?.();
     }
 
     resize(cols, rows) {
         if (this.closed) return;
         this.pty.resize(cols, rows);
+        this._queueSnapshotMutation(() => {
+            this.snapshotTerminal.resize(cols, rows);
+        });
+        if (this.manager?.scheduleSnapshotPersist) {
+            this.manager.scheduleSnapshotPersist(this.id);
+        }
         this._broadcast({ type: 'meta', title: this.title, cwd: this.cwd, env: this.env, cols, rows });
         if (this.manager && this.manager.saveSessionState) {
             this.manager.saveSessionState(this);
         }
     }
 
+    async restoreSnapshot(snapshot) {
+        if (typeof snapshot !== 'string' || !snapshot) return;
+        this.history = snapshot;
+        this._appendSnapshotData(snapshot);
+        await this.snapshotWritePromise;
+    }
+
+    async serializeSnapshot() {
+        await this.snapshotWritePromise;
+        let snapshot = this.snapshotSerializeAddon.serialize({
+            scrollback: this.snapshotScrollback
+        });
+        snapshot += this._serializeExtraPrivateModes();
+        return snapshot;
+    }
+
     _routeIncoming(raw, ws) {
         let payload;
         try {
@@ -892,6 +1008,9 @@ export class TerminalSession {
         for (const client of this.clients) {
             this._send(client, message, data);
         }
+        for (const pending of this.pendingClients.values()) {
+            pending.push(data);
+        }
     }
 
     _send(ws, message, preEncoded) {
@@ -901,12 +1020,82 @@ export class TerminalSession {
 
     _writeToLogAndBroadcast(text) {
         if (!text) return;
-        if (this.manager) {
-            this.manager.appendLog(this.id, text);
-        }
+        this._appendSnapshotData(text);
         this._appendHistory(text);
+        if (this.manager?.scheduleSnapshotPersist) {
+            this.manager.scheduleSnapshotPersist(this.id);
+        }
         this._broadcast({ type: 'output', data: text });
     }
+
+    _queueSnapshotMutation(mutate) {
+        const next = this.snapshotWritePromise.then(() => mutate());
+        this.snapshotWritePromise = next.catch(() => {});
+        return next;
+    }
+
+    _appendSnapshotData(text) {
+        if (!text) return;
+        this._trackExtraPrivateModes(text);
+        this._queueSnapshotMutation(() => new Promise((resolve) => {
+            this.snapshotTerminal.write(text, resolve);
+        }));
+    }
+
+    _trackExtraPrivateModes(text) {
+        EXTRA_PRIVATE_MODE_REGEX.lastIndex = 0;
+        let match;
+        while ((match = EXTRA_PRIVATE_MODE_REGEX.exec(text)) !== null) {
+            this.extraPrivateModes[match[1]] = match[2] === 'h';
+        }
+    }
+
+    _serializeExtraPrivateModes() {
+        let output = '';
+        for (const mode of ['1005', '1006', '1015']) {
+            if (this.extraPrivateModes[mode]) {
+                output += `\u001b[?${mode}h`;
+            }
+        }
+        return output;
+    }
+
+    async _sendInitialState(ws) {
+        const pending = this.pendingClients.get(ws);
+        if (!pending) return;
+
+        await this._queueSnapshotMutation(() => undefined);
+        if (ws.readyState !== WS_STATE_OPEN) {
+            this.pendingClients.delete(ws);
+            return;
+        }
+
+        const snapshot = await this.serializeSnapshot();
+        this._send(ws, { type: 'snapshot', data: snapshot });
+        this._send(ws, {
+            type: 'meta',
+            title: this.title,
+            cwd: this.cwd,
+            env: this.env,
+            cols: this.pty.cols,
+            rows: this.pty.rows
+        });
+        if (this.closed) {
+            this._send(ws, { type: 'status', status: 'terminated' });
+        } else {
+            this._send(ws, { type: 'status', status: 'ready' });
+        }
+
+        for (const payload of pending) {
+            if (ws.readyState !== WS_STATE_OPEN) break;
+            ws.send(payload);
+        }
+
+        this.pendingClients.delete(ws);
+        if (ws.readyState === WS_STATE_OPEN) {
+            this.clients.add(ws);
+        }
+    }
 }
 
 function clampDimension(value) {