termbeam 1.10.3 → 1.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termbeam",
-  "version": "1.10.3",
+  "version": "1.11.1",
   "description": "Beam your terminal to any device — mobile-optimized web terminal with multi-session support",
   "main": "src/server.js",
   "bin": {
@@ -47,7 +47,7 @@
     "url": "https://github.com/dorlugasigal/TermBeam/issues"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "files": [
     "bin/",

package/public/index.html

@@ -197,6 +197,45 @@
         border: 1px solid rgba(128, 128, 128, 0.3);
       }
 
+      .update-banner {
+        margin: 12px 16px 0;
+        padding: 10px 14px;
+        background: var(--surface);
+        border: 1px solid var(--accent);
+        border-radius: 10px;
+        display: none;
+        align-items: center;
+        gap: 10px;
+        font-size: 13px;
+        color: var(--text);
+      }
+      .update-banner.visible {
+        display: flex;
+      }
+      .update-banner-text {
+        flex: 1;
+      }
+      .update-banner-text code {
+        font-size: 12px;
+        background: var(--border);
+        padding: 2px 6px;
+        border-radius: 4px;
+        word-break: break-all;
+      }
+      .update-banner-dismiss {
+        background: none;
+        border: none;
+        color: var(--text-dim);
+        cursor: pointer;
+        font-size: 18px;
+        line-height: 1;
+        padding: 0 2px;
+        flex-shrink: 0;
+      }
+      .update-banner-dismiss:hover {
+        color: var(--text);
+      }
+
       .sessions-list {
         padding: 16px;
         padding-bottom: calc(80px + env(safe-area-inset-bottom, 0px));
@@ -730,7 +769,8 @@
     <div class="header">
       <h1>📡 Term<span>Beam</span></h1>
       <p>
-        Beam your terminal to any device · <span id="version" style="color: var(--accent)"></span>
+        Beam your terminal to any device ·
+        <span id="version" style="color: var(--accent)"></span>
       </p>
       <button class="header-btn" id="share-btn" style="right: 96px; top: 16px" title="Share link">
         <svg
@@ -833,6 +873,23 @@
       </div>
     </div>
 
+    <div class="update-banner" id="update-banner">
+      <div class="update-banner-text">
+        <strong>Update available:</strong> <span id="update-versions"></span><br />
+        <span id="update-command-text"
+          >Run: <code id="update-command">npm install -g termbeam@latest</code></span
+        >
+      </div>
+      <button
+        class="update-banner-dismiss"
+        id="update-dismiss"
+        title="Dismiss"
+        aria-label="Dismiss update notification"
+      >
+        &times;
+      </button>
+    </div>
+
     <div class="sessions-list" id="sessions-list"></div>
     <button class="new-session" id="new-session-btn">+ New Session</button>
 
@@ -981,6 +1038,36 @@
       const listEl = document.getElementById('sessions-list');
       const modal = document.getElementById('modal');
 
+      // Update notification
+      (async function checkUpdate() {
+        if (sessionStorage.getItem('update-dismissed')) return;
+        try {
+          const res = await fetch('/api/update-check');
+          if (!res.ok) return;
+          const info = await res.json();
+          if (info.updateAvailable && info.latest) {
+            const banner = document.getElementById('update-banner');
+            document.getElementById('update-versions').textContent =
+              'v' + info.current + ' \u2192 v' + info.latest;
+            if (info.command) {
+              const cmdEl = document.getElementById('update-command');
+              cmdEl.textContent = info.command;
+              if (info.method === 'npx') {
+                document.getElementById('update-command-text').textContent = 'Next time, run: ';
+                document.getElementById('update-command-text').appendChild(cmdEl);
+              }
+            }
+            banner.classList.add('visible');
+          }
+        } catch {
+          // Silent — update check is non-critical
+        }
+      })();
+      document.getElementById('update-dismiss').addEventListener('click', () => {
+        document.getElementById('update-banner').classList.remove('visible');
+        sessionStorage.setItem('update-dismissed', '1');
+      });
+
       function getActivityLabel(ts) {
         if (!ts) return '';
         const diff = (Date.now() - ts) / 1000;

package/public/sw.js

@@ -1,4 +1,4 @@
-const CACHE_NAME = 'termbeam-v5';
+const CACHE_NAME = 'termbeam-v7';
 const SHELL_URLS = ['/', '/terminal'];
 
 self.addEventListener('install', (event) => {

package/public/terminal.html

@@ -2293,6 +2293,7 @@
     <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/lib/addon-fit.min.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-web-links@0.11.0/lib/addon-web-links.min.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-search@0.15.0/lib/addon-search.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-canvas@0.7.0/lib/addon-canvas.min.js"></script>
     <script src="/js/shared.js"></script>
     <script src="/js/themes.js"></script>
     <script src="/js/terminal-themes.js"></script>
@@ -2376,6 +2377,9 @@
       const terminalsWrapper = document.getElementById('terminals-wrapper');
 
       // ===== Font Loading (non-blocking) =====
+      // Hook for font-load refit (set inside init, called by font loader)
+      let onFontReady = null;
+
       const nerdFont = new FontFace(
         'NerdFont',
         "url('https://cdn.jsdelivr.net/gh/ryanoasis/nerd-fonts@v3.4.0/patched-fonts/JetBrainsMono/Ligatures/Regular/JetBrainsMonoNerdFont-Regular.ttf')",
@@ -2387,6 +2391,10 @@
         })
         .catch(() => {
           console.warn('Nerd Font failed to load, using fallback');
+        })
+        .finally(() => {
+          // Refit all terminals once font metrics are stable
+          if (onFontReady) onFontReady();
         });
 
       // Start immediately — don't wait for font
@@ -2497,9 +2505,8 @@
 
         if (startId) activateSession(startId);
         else {
-          sessionNameEl.textContent = 'No sessions';
-          statusText.textContent = '';
-          document.getElementById('stop-btn').style.display = 'none';
+          window.location.replace('/');
+          return;
         }
 
         renderTabs();
@@ -2512,6 +2519,7 @@
         setupPreviewModal();
         loadShellsForModal();
         startPolling();
+        setTimeout(requestWakeLock, 0);
 
         // Pinch-to-zoom
         (function setupPinchZoom() {
@@ -2578,9 +2586,22 @@
             }
           }
         }
+        onFontReady = doResize;
         window.addEventListener('resize', doResize);
         screen.orientation?.addEventListener('change', () => setTimeout(doResize, 150));
 
+        // ResizeObserver — catches container size changes that don't trigger window resize
+        if (typeof ResizeObserver !== 'undefined') {
+          let resizeTimer = null;
+          new ResizeObserver(() => {
+            clearTimeout(resizeTimer);
+            resizeTimer = setTimeout(doResize, 100);
+          }).observe(terminalsWrapper);
+        }
+
+        // Refit after all fonts finish loading (catches bold variant, system fonts)
+        document.fonts.ready.then(() => doResize());
+
         // Mobile soft keyboard
         if (window.visualViewport) {
           const keyBar = document.getElementById('key-bar');
@@ -2640,24 +2661,70 @@
           );
         }
 
-        // Scroll to bottom when returning from idle / tab switch
+        // Wake Lock — helps keep mobile browser tab alive
+        let wakeLock = null;
+
+        async function requestWakeLock() {
+          if (!('wakeLock' in navigator)) return;
+          try {
+            wakeLock = await navigator.wakeLock.request('screen');
+            wakeLock.addEventListener('release', () => {
+              wakeLock = null;
+            });
+          } catch {
+            // Wake Lock request failed (e.g. low battery, not visible)
+          }
+        }
+
+        function releaseWakeLock() {
+          if (wakeLock) {
+            wakeLock.release().catch(() => {});
+            wakeLock = null;
+          }
+        }
+
+        // Reconnect & refit when returning from idle / tab switch
         document.addEventListener('visibilitychange', () => {
-          if (!document.hidden && activeId) {
-            clearUnreadIndicator();
-            const ms = managed.get(activeId);
-            if (ms) {
-              ms.term.scrollToBottom();
-              ms.fitAddon.fit();
-              sendResize(ms);
-            }
-            if (splitMode && splitSecondId) {
-              const ms2 = managed.get(splitSecondId);
-              if (ms2) {
-                ms2.term.scrollToBottom();
-                ms2.fitAddon.fit();
-                sendResize(ms2);
+          if (!document.hidden) {
+            if (activeId) {
+              clearUnreadIndicator();
+              const ms = managed.get(activeId);
+              if (ms) {
+                // Reconnect immediately if WebSocket died in background
+                if (!ms.exited && (!ms.ws || ms.ws.readyState !== WebSocket.OPEN)) {
+                  if (ms.reconnectTimer) {
+                    clearTimeout(ms.reconnectTimer);
+                    ms.reconnectTimer = null;
+                  }
+                  ms.reconnectDelay = 3000;
+                  connectSession(ms);
+                } else {
+                  ms.term.scrollToBottom();
+                  ms.fitAddon.fit();
+                  sendResize(ms);
+                }
+              }
+              if (splitMode && splitSecondId) {
+                const ms2 = managed.get(splitSecondId);
+                if (ms2) {
+                  if (!ms2.exited && (!ms2.ws || ms2.ws.readyState !== WebSocket.OPEN)) {
+                    if (ms2.reconnectTimer) {
+                      clearTimeout(ms2.reconnectTimer);
+                      ms2.reconnectTimer = null;
+                    }
+                    ms2.reconnectDelay = 3000;
+                    connectSession(ms2);
+                  } else {
+                    ms2.term.scrollToBottom();
+                    ms2.fitAddon.fit();
+                    sendResize(ms2);
+                  }
+                }
               }
             }
+            requestWakeLock();
+          } else {
+            releaseWakeLock();
           }
         });
 
@@ -2709,7 +2776,7 @@
           fontWeight: 'normal',
           fontWeightBold: 'bold',
           letterSpacing: 0,
-          lineHeight: 1.1,
+          lineHeight: 1.0,
           theme: TERM_THEMES[getTheme()] || darkTermTheme,
           allowProposedApi: true,
           scrollback: 10000,
@@ -2729,6 +2796,17 @@
         terminalsWrapper.appendChild(container);
         term.open(container);
 
+        // Canvas renderer — sharper text and more accurate selection.
+        // Skip in automated browsers (navigator.webdriver) where canvas
+        // rendering makes .xterm-rows inaccessible to DOM text queries.
+        if (window.CanvasAddon && !navigator.webdriver) {
+          try {
+            term.loadAddon(new window.CanvasAddon.CanvasAddon());
+          } catch {
+            // Fall back to DOM renderer
+          }
+        }
+
         // Scroll-to-bottom button
         const scrollBtn = document.createElement('button');
         scrollBtn.className = 'scroll-bottom-btn';
@@ -2740,17 +2818,28 @@
         });
         container.appendChild(scrollBtn);
 
-        // Write coalescer — batch rapid term.write() calls into one per frame
-        // so ANSI cursor-up/down pairs within a frame are processed atomically
+        // Write coalescer — batch rapid term.write() calls to reduce flicker.
+        // Single RAF for interactive typing (low latency). During bursts
+        // (>512 bytes buffered, e.g. Ctrl+O expand), waits one extra frame
+        // so cursor-movement sequences arrive as one atomic write.
         let writeBuf = '';
         let writeRaf = null;
+        function flushWrite() {
+          writeRaf = null;
+          if (writeBuf) {
+            term.write(writeBuf);
+            writeBuf = '';
+          }
+        }
         function coalescedWrite(data) {
           writeBuf += data;
           if (!writeRaf) {
             writeRaf = requestAnimationFrame(() => {
-              term.write(writeBuf);
-              writeBuf = '';
-              writeRaf = null;
+              if (writeBuf.length > 512) {
+                writeRaf = requestAnimationFrame(flushWrite);
+              } else {
+                flushWrite();
+              }
             });
           }
         }
@@ -3043,6 +3132,9 @@
           if (ms.id === activeId) {
             statusDot.className = '';
             statusText.textContent = 'Disconnected';
+            reconnectOverlay.querySelector('.msg').textContent =
+              'Disconnected. Attempting to reconnect\u2026';
+            reconnectOverlay.classList.add('visible');
           }
           if (!ms.exited) {
             ms.reconnectTimer = setTimeout(() => {
@@ -3139,11 +3231,8 @@
           const remaining = [...managed.keys()];
           if (remaining.length > 0) activateSession(remaining[0]);
           else {
-            activeId = null;
-            sessionNameEl.textContent = 'No sessions';
-            statusText.textContent = '';
-            statusDot.className = '';
-            document.getElementById('stop-btn').style.display = 'none';
+            window.location.replace('/');
+            return;
           }
         }
         renderTabs();
@@ -4232,12 +4321,8 @@
                   const remaining = [...managed.keys()];
                   if (remaining.length > 0) activateSession(remaining[0]);
                   else {
-                    activeId = null;
-                    sessionNameEl.textContent = 'No sessions';
-                    statusText.textContent = '';
-                    statusDot.className = '';
-                    document.getElementById('stop-btn').style.display = 'none';
-                    reconnectOverlay.classList.remove('visible');
+                    window.location.replace('/');
+                    return;
                   }
                 }
               }
@@ -4553,7 +4638,7 @@
               box.innerHTML =
                 '<div style="font-size:24px;margin-bottom:8px;">⚡</div>' +
                 '<div style="font-size:16px;font-weight:600;color:var(--text);margin-bottom:4px;">TermBeam</div>' +
-                '<div style="font-size:13px;color:var(--text-secondary);margin-bottom:16px;">' +
+                '<div style="font-size:13px;color:var(--text-secondary);margin-bottom:12px;">' +
                 esc(ver) +
                 '</div>' +
                 '<div style="font-size:12px;color:var(--text-secondary);margin-bottom:16px;">Terminal in your browser, optimized for mobile.</div>' +
@@ -4561,7 +4646,74 @@
                 '<a href="https://github.com/dorlugasigal/TermBeam" target="_blank" rel="noopener" style="color:var(--accent);font-size:12px;text-decoration:none;">GitHub</a>' +
                 '<a href="https://dorlugasigal.github.io/TermBeam/" target="_blank" rel="noopener" style="color:var(--accent);font-size:12px;text-decoration:none;">Docs</a>' +
                 '<a href="https://termbeam.pages.dev" target="_blank" rel="noopener" style="color:var(--accent);font-size:12px;text-decoration:none;">Website</a>' +
-                '</div>';
+                '</div>' +
+                '<div id="about-update-area" style="margin-bottom:12px;"></div>';
+              const updateArea = box.querySelector('#about-update-area');
+              const updateBtn = document.createElement('button');
+              updateBtn.textContent = 'Check for updates';
+              updateBtn.style.cssText =
+                'padding:6px 16px;border-radius:6px;border:1px solid var(--border);background:transparent;color:var(--text-secondary);font-size:12px;cursor:pointer;';
+              updateBtn.onclick = async () => {
+                updateBtn.textContent = 'Checking...';
+                updateBtn.disabled = true;
+                updateBtn.style.cursor = 'default';
+                try {
+                  const res = await fetch('/api/update-check?force=true');
+                  if (!res.ok) throw new Error();
+                  const info = await res.json();
+                  if (info.updateAvailable && info.latest) {
+                    const cmd = info.command || 'npm install -g termbeam@latest';
+                    updateArea.innerHTML = '';
+                    const status = document.createElement('div');
+                    status.style.cssText = 'font-size:12px;color:var(--accent);margin-bottom:8px;';
+                    status.textContent = 'v' + info.latest + ' available';
+                    updateArea.appendChild(status);
+                    const cmdRow = document.createElement('div');
+                    cmdRow.style.cssText =
+                      'display:flex;align-items:center;justify-content:center;gap:6px;';
+                    const cmdText = document.createElement('code');
+                    cmdText.textContent = cmd;
+                    cmdText.style.cssText =
+                      'font-size:11px;color:var(--accent);background:var(--bg);padding:4px 8px;border-radius:4px;border:1px solid var(--border);';
+                    const copyBtn = document.createElement('button');
+                    copyBtn.textContent = 'Copy';
+                    copyBtn.style.cssText =
+                      'padding:4px 10px;border-radius:4px;border:1px solid var(--accent);background:transparent;color:var(--accent);font-size:11px;cursor:pointer;';
+                    copyBtn.onclick = () => {
+                      const onSuccess = () => {
+                        copyBtn.textContent = 'Copied!';
+                        setTimeout(() => {
+                          copyBtn.textContent = 'Copy';
+                        }, 2000);
+                      };
+                      if (navigator.clipboard && navigator.clipboard.writeText) {
+                        navigator.clipboard
+                          .writeText(cmd)
+                          .then(onSuccess)
+                          .catch(() => {
+                            copyFallback(cmd);
+                            onSuccess();
+                          });
+                      } else {
+                        copyFallback(cmd);
+                        onSuccess();
+                      }
+                    };
+                    cmdRow.appendChild(cmdText);
+                    cmdRow.appendChild(copyBtn);
+                    updateArea.appendChild(cmdRow);
+                  } else {
+                    updateBtn.textContent = 'Up to date';
+                    updateBtn.style.color = '#4ec9b0';
+                    updateBtn.style.borderColor = '#4ec9b0';
+                  }
+                } catch {
+                  updateBtn.textContent = 'Check failed — try again';
+                  updateBtn.disabled = false;
+                  updateBtn.style.cursor = 'pointer';
+                }
+              };
+              updateArea.appendChild(updateBtn);
               const btn = document.createElement('button');
               btn.textContent = 'Close';
               btn.style.cssText =

package/src/routes.js

@@ -87,6 +87,29 @@ function setupRoutes(app, { auth, sessions, config, state }) {
     res.json({ version: getVersion() });
   });
 
+  // Update check API
+  app.get('/api/update-check', apiRateLimit, auth.middleware, async (req, res) => {
+    const { checkForUpdate, detectInstallMethod } = require('./update-check');
+    const force = req.query.force === 'true';
+
+    try {
+      const info = await checkForUpdate({ currentVersion: config.version, force });
+      const installInfo = detectInstallMethod();
+      state.updateInfo = { ...info, ...installInfo };
+      res.json(state.updateInfo);
+    } catch {
+      const installInfo = detectInstallMethod();
+      const fallback = {
+        current: config.version,
+        latest: null,
+        updateAvailable: false,
+        ...installInfo,
+      };
+      state.updateInfo = fallback;
+      res.json(fallback);
+    }
+  });
+
   // Share token auto-login middleware: validates ?ott= param, sets session cookie, redirects to clean URL
   function autoLogin(req, res, next) {
     const { ott } = req.query;

package/src/server.js

@@ -16,6 +16,7 @@ const { setupWebSocket } = require('./websocket');
 const { startTunnel, cleanupTunnel, findDevtunnel } = require('./tunnel');
 const { createPreviewProxy } = require('./preview');
 const { writeConnectionConfig, removeConnectionConfig } = require('./resume');
+const { checkForUpdate, detectInstallMethod } = require('./update-check');
 
 // --- Helpers ---
 function getLocalIP() {
@@ -73,7 +74,7 @@ function createTermBeamServer(overrides = {}) {
   const server = http.createServer(app);
   const wss = new WebSocketServer({ server, path: '/ws', maxPayload: 1 * 1024 * 1024 });
 
-  const state = { shareBaseUrl: null };
+  const state = { shareBaseUrl: null, updateInfo: null };
   app.use('/preview', auth.middleware, createPreviewProxy());
   setupRoutes(app, { auth, sessions, config, state });
   setupWebSocket(wss, { auth, sessions });
@@ -273,6 +274,41 @@ function createTermBeamServer(overrides = {}) {
         );
         console.log('');
 
+        // Non-blocking update check — runs after banner, never delays startup.
+        // Skip under the Node test runner and CI to avoid network requests in tests.
+        // Accept any version containing a semver-like pattern (including dev builds).
+        const versionParts = config.version.match(/(\d{1,10})\.(\d{1,10})\.(\d{1,10})/);
+        if (
+          versionParts &&
+          !process.env.NODE_TEST_CONTEXT &&
+          !process.env.CI &&
+          !process.argv.includes('--test')
+        ) {
+          const installInfo = detectInstallMethod();
+          checkForUpdate({ currentVersion: config.version })
+            .then((info) => {
+              state.updateInfo = { ...info, ...installInfo };
+              if (info.updateAvailable) {
+                const yl = '\x1b[33m';
+                const gn2 = '\x1b[38;5;114m';
+                const dm = '\x1b[2m';
+                console.log('');
+                console.log(
+                  `  ${yl}Update available:${rs} ${dm}${info.current}${rs} → ${gn2}${info.latest}${rs}`,
+                );
+                if (installInfo.method === 'npx') {
+                  console.log(`  Next time, run: ${gn2}npx termbeam@latest${rs}`);
+                } else {
+                  console.log(`  Run: ${gn2}${installInfo.command}${rs}`);
+                }
+                console.log('');
+              }
+            })
+            .catch(() => {
+              // Silent failure — update check is non-critical
+            });
+        }
+
         resolve({ url: `http://localhost:${actualPort}`, defaultId });
       });
     });

package/src/sessions.js

@@ -144,9 +144,15 @@ class SessionManager {
     ptyProcess.onData((data) => {
       session.lastActivity = Date.now();
       session.scrollbackBuf += data;
-      // Cap scrollback at ~200KB
-      if (session.scrollbackBuf.length > 200000) {
-        session.scrollbackBuf = session.scrollbackBuf.slice(-100000);
+      // High/low water scrollback cap: trim to 500k chars when buffer exceeds 1,000,000 chars
+      if (session.scrollbackBuf.length > 1000000) {
+        let buf = session.scrollbackBuf.slice(-500000);
+        // Advance to first newline to avoid starting mid-line
+        const nlIdx = buf.indexOf('\n');
+        if (nlIdx > 0 && nlIdx < 200) {
+          buf = buf.slice(nlIdx + 1);
+        }
+        session.scrollbackBuf = buf;
       }
       for (const ws of session.clients) {
         if (ws.readyState === 1) ws.send(JSON.stringify({ type: 'output', data }));

package/src/update-check.js

@@ -0,0 +1,240 @@
+const https = require('https');
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const PACKAGE_NAME = 'termbeam';
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const REQUEST_TIMEOUT_MS = 5000;
+const MAX_RESPONSE_SIZE = 100 * 1024; // 100 KB — real npm responses are ~3-4 KB
+
+function getCacheFilePath() {
+  const configDir = process.env.TERMBEAM_CONFIG_DIR || path.join(os.homedir(), '.termbeam');
+  return path.join(configDir, 'update-check.json');
+}
+
+function readCache() {
+  try {
+    const data = JSON.parse(fs.readFileSync(getCacheFilePath(), 'utf8'));
+    if (data && typeof data.latest === 'string' && typeof data.checkedAt === 'number') {
+      return data;
+    }
+  } catch {
+    // Cache missing or corrupt — will re-fetch
+  }
+  return null;
+}
+
+function writeCache(latest) {
+  try {
+    const cacheFile = getCacheFilePath();
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    fs.writeFileSync(cacheFile, JSON.stringify({ latest, checkedAt: Date.now() }) + '\n', {
+      mode: 0o600,
+    });
+  } catch {
+    // Non-critical — next check will just re-fetch
+  }
+}
+
+/**
+ * Normalize a version string into a [major, minor, patch] numeric tuple.
+ * Strips leading "v", drops prerelease/build metadata.
+ * Returns null if the version cannot be safely parsed.
+ */
+function normalizeVersion(version) {
+  if (typeof version !== 'string') return null;
+  let v = version.trim();
+  if (!v) return null;
+  if (v[0] === 'v' || v[0] === 'V') v = v.slice(1);
+
+  // Drop build metadata (+foo) and prerelease tags (-beta.1)
+  const plusIdx = v.indexOf('+');
+  if (plusIdx !== -1) v = v.slice(0, plusIdx);
+  const dashIdx = v.indexOf('-');
+  if (dashIdx !== -1) v = v.slice(0, dashIdx);
+  if (!v) return null;
+
+  const parts = v.split('.');
+  if (parts.length === 0 || parts.length > 3) return null;
+
+  const nums = [];
+  for (const part of parts) {
+    if (!/^\d+$/.test(part)) return null;
+    nums.push(Number(part));
+  }
+  while (nums.length < 3) nums.push(0);
+  return nums;
+}
+
+/**
+ * Compare two semver version strings (e.g. "1.10.2" vs "1.11.0").
+ * Returns true if `latest` is newer than `current`.
+ * Returns false if either version cannot be parsed.
+ */
+function isNewerVersion(current, latest) {
+  const cur = normalizeVersion(current);
+  const lat = normalizeVersion(latest);
+  if (!cur || !lat) return false;
+  for (let i = 0; i < 3; i++) {
+    if (lat[i] > cur[i]) return true;
+    if (lat[i] < cur[i]) return false;
+  }
+  return false;
+}
+
+/**
+ * Strip ANSI escape sequences and control characters from a string.
+ * Prevents terminal injection if the registry returns malicious data.
+ */
+function sanitizeVersion(v) {
+  if (typeof v !== 'string') return '';
+  return (
+    v
+      // CSI sequences: ESC [ ... command
+      .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '')
+      // OSC sequences: ESC ] ... BEL or ESC ] ... ESC \
+      .replace(/\x1b\][^\x1b\x07]*(?:\x07|\x1b\\)/g, '')
+      // DCS, SOS, PM, APC: ESC P/X/^/_ ... ESC \
+      .replace(/\x1b[PX^_][\s\S]*?\x1b\\/g, '')
+      // Single-character ESC sequences
+      .replace(/\x1b[@-Z\\-_]/g, '')
+      // Remaining C0 and C1 control characters
+      .replace(/[\x00-\x1f\x7f-\x9f]/g, '')
+  );
+}
+
+/**
+ * Fetch the latest version from the npm registry.
+ * Returns the version string or null on failure.
+ * @param {string} [registryUrl] - Override the registry URL (for testing).
+ */
+function fetchLatestVersion(registryUrl) {
+  const url = registryUrl || REGISTRY_URL;
+  const client = url.startsWith('https') ? https : http;
+  return new Promise((resolve) => {
+    const req = client.get(url, { timeout: REQUEST_TIMEOUT_MS }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        resolve(null);
+        return;
+      }
+      let body = '';
+      let aborted = false;
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        if (aborted) return;
+        body += chunk;
+        if (body.length > MAX_RESPONSE_SIZE) {
+          aborted = true;
+          req.destroy();
+          resolve(null);
+        }
+      });
+      res.on('end', () => {
+        if (aborted) return;
+        try {
+          const data = JSON.parse(body);
+          const version = data.version;
+          if (!version || typeof version !== 'string') {
+            resolve(null);
+            return;
+          }
+          if (!/^\d+\.\d+\.\d+$/.test(version)) {
+            resolve(null);
+            return;
+          }
+          resolve(sanitizeVersion(version));
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    // Unref so a pending update check can't delay process exit
+    req.on('socket', (socket) => socket.unref());
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+/**
+ * Check for available updates.
+ * @param {object} options
+ * @param {string} options.currentVersion - The current version (e.g. "1.10.2")
+ * @param {boolean} [options.force=false] - Bypass cache and fetch fresh data
+ * @returns {Promise<{current: string, latest: string|null, updateAvailable: boolean}>}
+ */
+async function checkForUpdate({ currentVersion, force = false } = {}) {
+  if (!currentVersion) {
+    return { current: 'unknown', latest: null, updateAvailable: false };
+  }
+
+  // Check cache first (unless forced)
+  if (!force) {
+    const cache = readCache();
+    if (cache && Date.now() - cache.checkedAt < CACHE_TTL_MS) {
+      const cachedLatest = typeof cache.latest === 'string' ? sanitizeVersion(cache.latest) : null;
+      if (cachedLatest && /^\d+\.\d+\.\d+$/.test(cachedLatest)) {
+        return {
+          current: currentVersion,
+          latest: cachedLatest,
+          updateAvailable: isNewerVersion(currentVersion, cachedLatest),
+        };
+      }
+    }
+  }
+
+  // Fetch from registry
+  const latest = await module.exports.fetchLatestVersion();
+  if (!latest) {
+    return { current: currentVersion, latest: null, updateAvailable: false };
+  }
+
+  // Cache the result
+  writeCache(latest);
+
+  return {
+    current: currentVersion,
+    latest,
+    updateAvailable: isNewerVersion(currentVersion, latest),
+  };
+}
+
+/**
+ * Detect how TermBeam was installed and return the appropriate update command.
+ * @returns {{ method: string, command: string }}
+ */
+function detectInstallMethod() {
+  // npx / npm exec — npm sets npm_command=exec
+  if (process.env.npm_command === 'exec') {
+    return { method: 'npx', command: 'npx termbeam@latest' };
+  }
+
+  // Detect package manager from npm_execpath (set during npm/yarn/pnpm lifecycle)
+  const execPath = process.env.npm_execpath || '';
+  if (execPath.includes('yarn')) {
+    return { method: 'yarn', command: 'yarn global add termbeam@latest' };
+  }
+  if (execPath.includes('pnpm')) {
+    return { method: 'pnpm', command: 'pnpm add -g termbeam@latest' };
+  }
+
+  // Default: npm global install
+  return { method: 'npm', command: 'npm install -g termbeam@latest' };
+}
+
+module.exports = {
+  checkForUpdate,
+  isNewerVersion,
+  normalizeVersion,
+  fetchLatestVersion,
+  readCache,
+  writeCache,
+  sanitizeVersion,
+  detectInstallMethod,
+};

package/src/version.js

@@ -10,17 +10,35 @@ function getVersion() {
     return base;
   }
 
-  // Running from source — try git describe for a dev version
+  // Running from source — git tags are the version source of truth.
+  // This avoids drift between package.json and tagged releases.
   try {
     const gitDesc = execSync('git describe --tags --always --dirty', {
       cwd: path.join(__dirname, '..'),
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
     }).trim();
-    // If we have a tag like v1.0.0, and we're exactly on it, return base
-    if (gitDesc === `v${base}`) return base;
-    // Otherwise return dev version
-    return `${base}-dev (${gitDesc})`;
+
+    const tagMatch = gitDesc.match(/^v(\d+\.\d+\.\d+)(?:-(\d+)-g([0-9a-f]+))?(-dirty)?$/);
+    if (tagMatch) {
+      const gitVersion = tagMatch[1];
+      const commits = tagMatch[2];
+      const hash = tagMatch[3];
+      const dirty = tagMatch[4];
+
+      // Exactly on a clean tag — return the tag version
+      if (!commits && !dirty) return gitVersion;
+
+      // Build a combined semver-style dev string
+      let ver = `${gitVersion}-dev`;
+      if (commits) ver += `.${commits}`;
+      const meta = [hash ? `g${hash}` : null, dirty ? 'dirty' : null].filter(Boolean).join('.');
+      if (meta) ver += `+${meta}`;
+      return ver;
+    }
+
+    // No semver tag found (e.g. bare commit hash) — fall back to package.json
+    return `${base}-dev+${gitDesc}`;
   } catch {
     return `${base}-dev`;
   }

package/src/websocket.js

@@ -1,14 +1,37 @@
 const log = require('./logger');
 
+const ACTIVE_THRESHOLD = 60000; // 60 seconds
+
+// OSC color query/response sequences (OSC 4/10/11/12) cause garbled output
+// on replay: color queries trigger xterm.js to generate responses that echo
+// through the PTY as visible text, accumulating on each refresh.
+const OSC_COLOR_RE = /\x1b\](?:4;\d+|10|11|12);[^\x07\x1b]*(?:\x07|\x1b\\)/g;
+function sanitizeForReplay(buf) {
+  return buf.replace(OSC_COLOR_RE, '');
+}
+
 function recalcPtySize(session) {
-  let minCols = Infinity;
-  let minRows = Infinity;
+  const now = Date.now();
+  let activeCols = Infinity;
+  let activeRows = Infinity;
+  let allCols = Infinity;
+  let allRows = Infinity;
+  let hasActive = false;
+
   for (const client of session.clients) {
-    if (client._dims) {
-      minCols = Math.min(minCols, client._dims.cols);
-      minRows = Math.min(minRows, client._dims.rows);
+    if (!client._dims) continue;
+    allCols = Math.min(allCols, client._dims.cols);
+    allRows = Math.min(allRows, client._dims.rows);
+    if (client._lastActivity && now - client._lastActivity < ACTIVE_THRESHOLD) {
+      activeCols = Math.min(activeCols, client._dims.cols);
+      activeRows = Math.min(activeRows, client._dims.rows);
+      hasActive = true;
     }
   }
+
+  const minCols = hasActive ? activeCols : allCols;
+  const minRows = hasActive ? activeRows : allRows;
+
   if (minCols === Infinity || minRows === Infinity) return;
   if (minCols === session._lastCols && minRows === session._lastRows) return;
   session._lastCols = minCols;
@@ -39,6 +62,11 @@ function setupWebSocket(wss, { auth, sessions }) {
       }
     }
 
+    const pingInterval = setInterval(() => {
+      if (ws.readyState === 1) ws.ping();
+    }, 30000);
+    if (typeof pingInterval.unref === 'function') pingInterval.unref();
+
     let authenticated = !auth.password;
     let attached = null;
 
@@ -95,6 +123,7 @@ function setupWebSocket(wss, { auth, sessions }) {
             log.warn(`WS: attach failed — session ${msg.sessionId} not found`);
             return;
           }
+          ws._lastActivity = Date.now();
           attached = session;
           // First client: defer adding to session.clients until after the
           // first resize so we can decide whether the PTY needs resizing.
@@ -104,7 +133,9 @@ function setupWebSocket(wss, { auth, sessions }) {
           } else {
             session.clients.add(ws);
             if (session.scrollbackBuf.length > 0) {
-              ws.send(JSON.stringify({ type: 'output', data: session.scrollbackBuf }));
+              ws.send(
+                JSON.stringify({ type: 'output', data: sanitizeForReplay(session.scrollbackBuf) }),
+              );
             }
           }
           ws.send(JSON.stringify({ type: 'attached', sessionId: msg.sessionId }));
@@ -115,12 +146,14 @@ function setupWebSocket(wss, { auth, sessions }) {
         if (!attached) return;
 
         if (msg.type === 'input') {
+          ws._lastActivity = Date.now();
           attached.pty.write(msg.data);
         } else if (msg.type === 'resize') {
           const cols = Math.floor(msg.cols);
           const rows = Math.floor(msg.rows);
           if (cols > 0 && cols <= 500 && rows > 0 && rows <= 200) {
             ws._dims = { cols, rows };
+            ws._lastActivity = Date.now();
             if (ws._pendingResize) {
               ws._pendingResize = false;
               // Only discard scrollback and send SIGWINCH if the PTY was
@@ -136,7 +169,12 @@ function setupWebSocket(wss, { auth, sessions }) {
               } else {
                 attached.clients.add(ws);
                 if (attached.scrollbackBuf.length > 0) {
-                  ws.send(JSON.stringify({ type: 'output', data: attached.scrollbackBuf }));
+                  ws.send(
+                    JSON.stringify({
+                      type: 'output',
+                      data: sanitizeForReplay(attached.scrollbackBuf),
+                    }),
+                  );
                 }
               }
             } else {
@@ -150,6 +188,7 @@ function setupWebSocket(wss, { auth, sessions }) {
     });
 
     ws.on('close', () => {
+      clearInterval(pingInterval);
       if (attached) {
         attached.clients.delete(ws);
         recalcPtySize(attached);
@@ -159,4 +198,4 @@ function setupWebSocket(wss, { auth, sessions }) {
   });
 }
 
-module.exports = { setupWebSocket };
+module.exports = { setupWebSocket, ACTIVE_THRESHOLD, sanitizeForReplay };