handmux 0.19.0 → 0.20.0

package/public/index.html

@@ -48,8 +48,8 @@
       @keyframes bootDot { 0%,100% { opacity: .22; transform: translateY(0); } 40% { opacity: 1; transform: translateY(-3px); } }
       @media (prefers-reduced-motion: reduce) { .boot-glow, .boot-dots i { animation: none; opacity: .8; } }
     </style>
-    <script type="module" crossorigin src="/assets/index-CIlbBw_U.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-erQcVC-q.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" crossorigin href="/assets/index-erQcVC-q.css"></noscript>
+    <script type="module" crossorigin src="/assets/index-DkaDRYCU.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DCZuq0nO.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" crossorigin href="/assets/index-DCZuq0nO.css"></noscript>
   </head>
   <body>
     <div id="boot-splash" aria-hidden="true">

package/src/captureBackground.js

@@ -0,0 +1,93 @@
+const CSI = /\x1b\[([0-9;]*)m/g;
+const ANSI = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\))/g;
+
+function backgroundAfter(line, initial) {
+  let background = initial;
+  const sgr = new RegExp(CSI.source, 'g');
+  let match = sgr.exec(line);
+  while (match) {
+    const params = match[1] === '' ? [0] : match[1].split(';').map(Number);
+    for (let i = 0; i < params.length; i += 1) {
+      const value = params[i];
+      if (value === 0 || value === 49) background = false;
+      else if ((value >= 40 && value <= 47) || (value >= 100 && value <= 107)) background = true;
+      else if (value === 38 || value === 48) {
+        const isBackground = value === 48;
+        if (params[i + 1] === 5) {
+          i += 2;
+          if (isBackground) background = true;
+        } else if (params[i + 1] === 2) {
+          i += 4;
+          if (isBackground) background = true;
+        }
+      }
+    }
+    match = sgr.exec(line);
+  }
+  return background;
+}
+
+function paintsBackground(line) {
+  let background = false;
+  let offset = 0;
+  const sgr = new RegExp(CSI.source, 'g');
+  let match = sgr.exec(line);
+  while (match) {
+    if (background && match.index > offset) return true;
+    background = backgroundAfter(match[0], background);
+    offset = sgr.lastIndex;
+    match = sgr.exec(line);
+  }
+  return background && offset < line.length;
+}
+
+const isBlank = (line) => line.replace(ANSI, '').trim() === '';
+
+// `capture-pane -e -N` compresses SGR state across newlines. A default blank row after a shaded
+// row (Claude) and a genuinely shaded padding row (Codex) therefore look identical in the combined
+// capture. Capturing just that row makes tmux emit the row's real starting attributes. Only those
+// ambiguous rows need the extra read; ordinary rows keep the single fast combined capture.
+export function ambiguousBackgroundRows(lines) {
+  const indexes = [];
+  let background = false;
+  let inBlankRun = false;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const ambiguous = background && isBlank(line);
+    // One row resolves the whole trailing run: default closes it before the first LF; shaded is the
+    // one real padding row the client preserves and seals before clearing any additional blanks.
+    if (ambiguous && !inBlankRun) indexes.push(index);
+    inBlankRun = ambiguous;
+    background = backgroundAfter(line, background);
+  }
+  return indexes;
+}
+
+export async function restoreBlankRowBackgrounds(lines, historyLines, readRow) {
+  const restored = [...lines];
+  const indexes = ambiguousBackgroundRows(lines);
+  await Promise.all(indexes.map(async (index) => {
+    const row = index - historyLines;
+    const exact = await readRow(row);
+    // A separately-captured default row has no background SGR. Explicitly close the combined
+    // stream's inherited background before replaying it. A real padding row starts with its own
+    // background SGR and is preserved verbatim.
+    restored[index] = paintsBackground(exact) ? exact : `\x1b[49m${exact}`;
+  }));
+  return restored;
+}
+
+export async function restoreCaptureBackgrounds(capture, paneHeight, readRow) {
+  const trailingNewline = capture.endsWith('\n');
+  const body = trailingNewline ? capture.slice(0, -1) : capture;
+  const lines = body.split('\n');
+  const historyLines = Math.max(0, lines.length - paneHeight);
+  const restored = await restoreBlankRowBackgrounds(lines, historyLines, async (row) => {
+    const exact = await readRow(row);
+    return exact.endsWith('\n') ? exact.slice(0, -1) : exact;
+  });
+  return {
+    ansi: restored.join('\n') + (trailingNewline ? '\n' : ''),
+    historyLines,
+  };
+}

package/src/cli/i18n/en.js

@@ -285,7 +285,7 @@ export default {
   'setup.sshReady': '✓ passwordless SSH already set up',
   'setup.sshSetup': "→ setting up passwordless SSH to {host} (you'll enter the password once) …",
   'setup.sshHelp1': 'Server side (one-time): point a reverse proxy at the forwarded loopback port.',
-  'setup.sshHelpNginx': '  nginx:  proxy_pass http://127.0.0.1:{port};  (add client_max_body_size 60m; proxy_read_timeout 90s;)',
+  'setup.sshHelpNginx': '  nginx:  proxy_pass http://127.0.0.1:{port};  also set proxy_http_version 1.1, the Upgrade/Connection WebSocket headers, client_max_body_size 60m, and proxy_read_timeout 90s;',
   'setup.sshHelpCaddy': '  caddy:  {url} {  reverse_proxy 127.0.0.1:{port}  }',
   'setup.previewAbout': 'Open a development service running on this machine by port from your phone. Static directory preview still works without this setting.',
   'setup.previewRoute': 'Enter only the preview domain (for example, preview.example.com). handmux uses <project-name>.preview.example.com; route *.preview.example.com to the handmux gateway.',

package/src/cli/i18n/zh.js

@@ -284,7 +284,7 @@ export default {
   'setup.sshReady': '✓ 免密 SSH 已配置好',
   'setup.sshSetup': '→ 正在配置到 {host} 的免密 SSH(你需要输入一次密码)…',
   'setup.sshHelp1': '服务端(一次性):把反向代理指向被转发的 loopback 端口。',
-  'setup.sshHelpNginx': '  nginx:  proxy_pass http://127.0.0.1:{port};  (加上 client_max_body_size 60m; proxy_read_timeout 90s;)',
+  'setup.sshHelpNginx': '  nginx:  proxy_pass http://127.0.0.1:{port};  并设置 proxy_http_version 1.1、Upgrade/Connection WebSocket 头、client_max_body_size 60m、proxy_read_timeout 90s;',
   'setup.sshHelpCaddy': '  caddy:  {url} {  reverse_proxy 127.0.0.1:{port}  }',
   'setup.previewAbout': '用于在手机上按端口打开本机正在运行的开发服务；不配置时，静态目录预览仍可使用。',
   'setup.previewRoute': '只填预览域名（如 preview.example.com）。handmux 会使用 <项目名>.preview.example.com；请将 *.preview.example.com 路由到 handmux 网关。',

package/src/routes/terminal.js

@@ -6,6 +6,7 @@ import { gzipSync } from 'node:zlib';
 import { isPaneId, isWindowId } from '../tmux/commands.js';
 import { capTrailingBlankRows } from '../trimCapture.js';
 import { isAllowedKey } from '../keyNames.js';
+import { restoreCaptureBackgrounds } from '../captureBackground.js';
 
 export { isAllowedKey } from '../keyNames.js';
 
@@ -46,13 +47,28 @@ export function terminalRoutes({ commands }) {
       // pane as exactly its visible screen (lines=0) and skip the blank-trim. A normal pane still pulls
       // `lines` of scrollback and caps the empty grid below the cursor (fresh shell = "prompt + a wall of
       // blank rows") so the phone's bottom-anchored render shows content, not blank. See trimCapture.js.
-      const raw = await commands.capturePane(req.query.pane, altScreen ? 0 : lines);
+      const captured = await commands.capturePane(req.query.pane, altScreen ? 0 : lines);
+      const restored = typeof commands.capturePaneRow === 'function'
+        ? await restoreCaptureBackgrounds(
+          captured,
+          height,
+          (row) => commands.capturePaneRow(req.query.pane, row),
+        )
+        : {
+          ansi: captured,
+          historyLines: Math.max(
+            0,
+            (captured.endsWith('\n') ? captured.slice(0, -1) : captured).split('\n').length - height,
+          ),
+        };
+      const raw = restored.ansi;
       const ansi = altScreen ? raw : capTrailingBlankRows(raw);
       // The cursor's row counted from the BOTTOM of the (trimmed) capture. The live screen is the
       // capture's last `height` rows, so the cursor sits `height-1-cursorY` rows above the bottom —
       // less however many trailing blank rows capTrailingBlankRows dropped (all of them below the
       // cursor). The client re-places xterm's cursor this many rows up from the seed's last row.
       const rowsOf = (s) => (s.endsWith('\n') ? s.slice(0, -1) : s).split('\n').length;
+      const historyLines = altScreen ? 0 : restored.historyLines;
       const cur = {
         row: Math.max(0, (height - 1 - cursorY) - (rowsOf(raw) - rowsOf(ansi))),
         col: cursorX, vis: cursorVisible,
@@ -67,7 +83,9 @@ export function terminalRoutes({ commands }) {
         .update(`${width}x${height}\n${cur.col},${cursorY},${cur.vis ? 1 : 0}\n${altScreen ? 1 : 0}${mouseAware ? 'm' : ''}\n${ansi}`)
         .digest('hex').slice(0, 16);
       if (req.query.since === hash) return res.status(204).end();
-      const json = JSON.stringify({ ansi, width, height, hash, cur, alt: altScreen, mouseAware });
+      const json = JSON.stringify({
+        ansi, width, height, historyLines, hash, cur, alt: altScreen, mouseAware,
+      });
       res.set('Content-Type', 'application/json');
       res.set('Vary', 'Accept-Encoding'); // both 200 branches vary on encoding (correct for any caching proxy)
       // Capture text is mostly SGR codes + spaces — gzip crushes it ~10x. (204s are empty, never gzipped.)

package/src/server.js

@@ -24,6 +24,7 @@ import { createEnvironmentProvider } from './workspace/environment.js';
 import { createWorkspaceLock } from './workspace/lock.js';
 import { createGracefulShutdown, createWorkspaceBackground } from './workspace/checkpointer.js';
 import { createWorkspaceRuntime } from './workspace/runtime.js';
+import { createTerminalStream } from './terminalStream.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 
@@ -151,10 +152,17 @@ app.get('*', (req, res, next) => {
 const server = app.listen(cfg.port, cfg.host, () => {
   console.log(`[handmux] listening on http://${cfg.host}:${cfg.port} (serving ${staticDir})`);
 });
-// WebSocket/HMR for dynamic previews: route raw Upgrade by Host to the right loopback port.
-server.on('upgrade', preview.onUpgrade);
+const terminalStream = createTerminalStream({ token, commands });
+// The terminal stream owns one exact path. Every other Upgrade keeps using the existing
+// dynamic-preview router unchanged.
+server.on('upgrade', (req, socket, head) => {
+  if (!terminalStream.onUpgrade(req, socket, head)) preview.onUpgrade(req, socket, head);
+});
 
 const shutdown = createGracefulShutdown({ events, workspace, server });
-const handleSignal = () => { shutdown().catch(() => {}); };
+const handleSignal = () => {
+  terminalStream.close();
+  shutdown().catch(() => {});
+};
 process.on('SIGINT', handleSignal);
 process.on('SIGTERM', handleSignal);

package/src/terminalStream.js

@@ -0,0 +1,388 @@
+import { spawn } from 'node:child_process';
+import { WebSocketServer } from 'ws';
+import { tokenEquals } from './auth.js';
+import { isPaneId } from './tmux/commands.js';
+import { restoreCaptureBackgrounds } from './captureBackground.js';
+
+const MAX_BUFFERED_BYTES = 1024 * 1024;
+const MAX_CLIENT_MESSAGE_BYTES = 16 * 1024;
+const START_TIMEOUT_MS = 5000;
+const SUBSCRIBE_TIMEOUT_MS = 5000;
+const HEARTBEAT_MS = 30000;
+const INITIAL_HISTORY_LINES = 100;
+const PANE_INFO = '"#{pane_width}\\t#{pane_height}\\t#{cursor_x}\\t#{cursor_y}\\t#{cursor_flag}\\t#{alternate_on}\\t#{mouse_any_flag}\\t#{mouse_sgr_flag}"';
+
+export function echoTerminalProbe(ws, message) {
+  if (message?.type !== 'probe' || !Number.isSafeInteger(message.id) || message.id < 0) return false;
+  if (ws.readyState === 1) ws.send(JSON.stringify({ type: 'probe', id: message.id }));
+  return true;
+}
+
+export function startSubscribeDeadline(ws, timeoutMs = SUBSCRIBE_TIMEOUT_MS) {
+  const timer = setTimeout(() => {
+    if (ws.readyState < 2) ws.close(4001, 'authentication timeout');
+  }, timeoutMs);
+  timer.unref?.();
+  return () => clearTimeout(timer);
+}
+
+function parsePaneInfo(infoLines) {
+  const values = Buffer.concat(infoLines).toString('utf8').split('\t').map(Number);
+  if (!values.every(Number.isFinite) || values.length !== 8 || values[0] < 1 || values[1] < 1) {
+    throw new Error('invalid tmux pane info');
+  }
+  return values;
+}
+
+export function decodeControlData(data) {
+  const bytes = [];
+  for (let i = 0; i < data.length;) {
+    if (data[i] === 0x5c && data[i + 1] === 0x5c) {
+      bytes.push(0x5c);
+      i += 2;
+      continue;
+    }
+    if (data[i] === 0x5c && i + 3 < data.length) {
+      const a = data[i + 1];
+      const b = data[i + 2];
+      const c = data[i + 3];
+      if (a >= 0x30 && a <= 0x37 && b >= 0x30 && b <= 0x37 && c >= 0x30 && c <= 0x37) {
+        bytes.push(((a - 0x30) << 6) | ((b - 0x30) << 3) | (c - 0x30));
+        i += 4;
+        continue;
+      }
+    }
+    bytes.push(data[i]);
+    i += 1;
+  }
+  return Buffer.from(bytes);
+}
+
+export class PaneControlStream {
+  constructor({ ws, pane, session, spawnControl = spawn }) {
+    this.ws = ws;
+    this.pane = pane;
+    this.buffer = Buffer.alloc(0);
+    this.waiters = [];
+    this.response = null;
+    this.phase = 'attach';
+    this.wantLive = true;
+    this.pendingOutput = [];
+    this.pendingOutputBytes = 0;
+    this.resyncing = null;
+    this.attached = new Promise((resolve, reject) => {
+      this.resolveAttached = resolve;
+      this.rejectAttached = reject;
+    });
+    this.startTimer = setTimeout(
+      () => this.rejectAttached(new Error('tmux control mode attach timed out')),
+      START_TIMEOUT_MS,
+    );
+    this.child = spawnControl('tmux', ['-C', 'attach-session', '-t', session], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    this.child.stdout.on('data', (chunk) => this.onChunk(chunk));
+    this.child.stderr.on('data', (chunk) => { this.lastError = chunk.toString('utf8'); });
+    this.child.on('error', (error) => this.fail(error));
+    this.child.on('exit', (code) => {
+      if (this.phase !== 'closed') this.fail(new Error(this.lastError || `tmux control mode exited (${code})`));
+    });
+  }
+
+  onChunk(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    for (;;) {
+      const newline = this.buffer.indexOf(0x0a);
+      if (newline < 0) break;
+      const line = this.buffer.subarray(0, newline);
+      this.buffer = this.buffer.subarray(newline + 1);
+      this.onLine(line.at(-1) === 0x0d ? line.subarray(0, -1) : line);
+    }
+  }
+
+  onLine(line) {
+    if (line.subarray(0, 8).toString('ascii') === '%output ') {
+      const split = line.indexOf(0x20, 8);
+      if (split < 0 || line.subarray(8, split).toString('ascii') !== this.pane) return;
+      const output = decodeControlData(line.subarray(split + 1));
+      if (this.phase === 'buffer') {
+        if (this.pendingOutputBytes + output.length > MAX_BUFFERED_BYTES) {
+          this.wantLive = false;
+          this.phase = 'paused';
+          this.pendingOutput = [];
+          this.pendingOutputBytes = 0;
+          if (this.ws.readyState < 2) this.ws.close(1013, 'stream fell behind');
+        } else {
+          this.pendingOutput.push(output);
+          this.pendingOutputBytes += output.length;
+        }
+      }
+      else if (this.phase === 'live') this.sendOutput(output);
+      return;
+    }
+    if (line.subarray(0, 7).toString('ascii') === '%begin ') {
+      this.response = { lines: [], waiter: this.waiters.shift() ?? null };
+      return;
+    }
+    const end = line.subarray(0, 5).toString('ascii') === '%end ';
+    const error = line.subarray(0, 7).toString('ascii') === '%error ';
+    if (end || error) {
+      const response = this.response;
+      this.response = null;
+      if (response?.waiter) {
+        if (error) {
+          response.waiter.reject(new Error(Buffer.concat(response.lines).toString('utf8')));
+        } else {
+          try {
+            // Run the boundary callback synchronously, before onChunk can consume any notification
+            // following this %end in the same stdout chunk. Resync uses this to publish ready before
+            // later %output, so an older cursor snapshot can never overwrite newer streamed movement.
+            response.waiter.onEnd?.(response.lines);
+            response.waiter.resolve(response.lines);
+          } catch (callbackError) {
+            response.waiter.reject(callbackError);
+          }
+        }
+      }
+      return;
+    }
+    if (this.response) {
+      this.response.lines.push(Buffer.from(line));
+      return;
+    }
+    if (line.subarray(0, 17).toString('ascii') === '%session-changed ') {
+      clearTimeout(this.startTimer);
+      this.resolveAttached();
+    }
+  }
+
+  request(command, onEnd) {
+    return new Promise((resolve, reject) => {
+      if (this.phase === 'closed') {
+        reject(new Error('tmux control stream closed'));
+        return;
+      }
+      this.waiters.push({ resolve, reject, onEnd });
+      this.child.stdin.write(`${command}\n`);
+    });
+  }
+
+  sendOutput(output) {
+    if (this.ws.readyState !== 1) return;
+    if (this.ws.bufferedAmount > MAX_BUFFERED_BYTES) {
+      this.ws.close(1013, 'stream fell behind');
+      return;
+    }
+    this.ws.send(output, { binary: true });
+  }
+
+  sendJson(message) {
+    if (this.ws.readyState !== 1) return false;
+    if (this.ws.bufferedAmount > MAX_BUFFERED_BYTES) {
+      this.ws.close(1013, 'stream fell behind');
+      return false;
+    }
+    this.ws.send(JSON.stringify(message));
+    return true;
+  }
+
+  async start() {
+    await this.attached;
+    await this.resync();
+  }
+
+  pause() {
+    if (this.phase !== 'closed') {
+      this.wantLive = false;
+      this.phase = 'paused';
+      this.pendingOutput = [];
+      this.pendingOutputBytes = 0;
+    }
+  }
+
+  resync() {
+    this.wantLive = true;
+    if (this.resyncing) return this.resyncing;
+    this.resyncing = this.runResync().finally(() => { this.resyncing = null; });
+    return this.resyncing;
+  }
+
+  async runResync() {
+    await this.attached;
+    this.phase = 'capture';
+    this.pendingOutput = [];
+    this.pendingOutputBytes = 0;
+    const captureLines = await this.request(
+      `capture-pane -p -e -N -S -${INITIAL_HISTORY_LINES} -t ${this.pane}`,
+      () => { this.phase = this.wantLive ? 'buffer' : 'paused'; },
+    );
+    const preliminaryInfo = await this.request(
+      `display-message -p -t ${this.pane} ${PANE_INFO}`,
+    );
+    const [, height, , , , alternateOn] = parsePaneInfo(preliminaryInfo);
+    if (!this.wantLive || this.phase === 'closed') {
+      this.pendingOutput = [];
+      this.pendingOutputBytes = 0;
+      if (this.phase !== 'closed') this.phase = 'paused';
+      return;
+    }
+    const sourceLines = alternateOn === 1 ? captureLines.slice(-height) : captureLines;
+    const captured = Buffer.concat(sourceLines.flatMap((line) => [line, Buffer.from('\n')]))
+      .toString('utf8');
+    const restored = await restoreCaptureBackgrounds(captured, height, async (row) => {
+      const exact = await this.request(
+        `capture-pane -p -e -N -S ${row} -E ${row} -t ${this.pane}`,
+      );
+      return `${Buffer.concat(exact).toString('utf8')}\n`;
+    });
+    const restoredLines = restored.ansi.endsWith('\n')
+      ? restored.ansi.slice(0, -1).split('\n').map((line) => Buffer.from(line))
+      : restored.ansi.split('\n').map((line) => Buffer.from(line));
+    // Re-read size/cursor after the targeted row checks. Output produced while those checks ran is
+    // buffered; the synchronous onEnd handoff below publishes seed → buffered output → fresh cursor
+    // before any later %output from the same control chunk can overtake it.
+    await this.request(
+      `display-message -p -t ${this.pane} ${PANE_INFO}`,
+      (infoLines) => this.finishResync(restoredLines, infoLines),
+    );
+  }
+
+  finishResync(captureLines, infoLines) {
+    const [width, height, cursorX, cursorY, cursorFlag, alternateOn, mouseAny, mouseSgr] =
+      parsePaneInfo(infoLines);
+    if (!this.wantLive || this.phase === 'closed') {
+      this.pendingOutput = [];
+      this.pendingOutputBytes = 0;
+      if (this.phase !== 'closed') this.phase = 'paused';
+      return;
+    }
+    // Alternate-screen apps have no history of their own. tmux's -S capture may prepend the main
+    // screen's scrollback, so keep only the alternate screen's real grid there.
+    const visibleCapture = alternateOn === 1 ? captureLines.slice(-height) : captureLines;
+    const historyLines = Math.max(0, visibleCapture.length - height);
+    const ansi = Buffer.concat(visibleCapture.flatMap((line) => [line, Buffer.from('\n')])).toString('utf8');
+    if (!this.sendJson({
+      type: 'seed',
+      ansi,
+      width,
+      height,
+      historyLines,
+      alt: alternateOn === 1,
+      mouseAware: mouseAny === 1,
+      mouseSgr: mouseSgr === 1,
+    })) return;
+    for (const output of this.pendingOutput) this.sendOutput(output);
+    if (!this.sendJson({
+      type: 'ready',
+      cur: { row: height - 1 - cursorY, col: cursorX, vis: cursorFlag === 1 },
+    })) return;
+    this.pendingOutput = [];
+    this.pendingOutputBytes = 0;
+    this.phase = this.wantLive ? 'live' : 'paused';
+  }
+
+  fail(error) {
+    clearTimeout(this.startTimer);
+    this.rejectAttached(error);
+    this.response?.waiter?.reject(error);
+    this.response = null;
+    for (const waiter of this.waiters.splice(0)) waiter.reject(error);
+    if (this.ws.readyState < 2) this.ws.close(1011, 'tmux stream failed');
+  }
+
+  close() {
+    clearTimeout(this.startTimer);
+    this.phase = 'closed';
+    this.wantLive = false;
+    const error = new Error('tmux control stream closed');
+    this.response?.waiter?.reject(error);
+    this.response = null;
+    for (const waiter of this.waiters.splice(0)) waiter.reject(error);
+    this.pendingOutput = [];
+    this.pendingOutputBytes = 0;
+    try { this.child.kill(); } catch { /* already gone */ }
+  }
+}
+
+export function createTerminalStream({ token, commands, spawnControl } = {}) {
+  const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_CLIENT_MESSAGE_BYTES });
+  const streams = new Set();
+  const heartbeat = setInterval(() => {
+    for (const ws of wss.clients) {
+      if (ws.readyState !== 1) continue;
+      if (ws.isAlive === false) {
+        ws.terminate();
+        continue;
+      }
+      ws.isAlive = false;
+      ws.ping();
+    }
+  }, HEARTBEAT_MS);
+  heartbeat.unref?.();
+
+  wss.on('connection', (ws) => {
+    ws.isAlive = true;
+    ws.on('pong', () => { ws.isAlive = true; });
+    const cancelSubscribeDeadline = startSubscribeDeadline(ws);
+    let authenticating = false;
+    let stream = null;
+    ws.on('message', async (raw, binary) => {
+      if (binary) return;
+      let message;
+      try { message = JSON.parse(raw.toString()); } catch { ws.close(1003, 'bad message'); return; }
+      if (stream) {
+        if (echoTerminalProbe(ws, message)) return;
+        if (message.type === 'pause') stream.pause();
+        else if (message.type === 'resync') {
+          try { await stream.resync(); } catch {
+            if (ws.readyState < 2) ws.close(1011, 'stream resync failed');
+          }
+        }
+        return;
+      }
+      if (authenticating) return;
+      if (message.type !== 'subscribe'
+        || !tokenEquals(message.token ?? '', token)
+        || !isPaneId(message.pane)) {
+        ws.close(4001, 'unauthorized');
+        return;
+      }
+      authenticating = true;
+      cancelSubscribeDeadline();
+      try {
+        const session = await commands.paneSession(message.pane);
+        if (ws.readyState !== 1) return;
+        stream = new PaneControlStream({ ws, pane: message.pane, session, spawnControl });
+        streams.add(stream);
+        await stream.start();
+      } catch {
+        if (ws.readyState < 2) ws.close(1011, 'stream setup failed');
+      }
+    });
+    ws.on('close', () => {
+      cancelSubscribeDeadline();
+      if (stream) {
+        stream.close();
+        streams.delete(stream);
+      }
+    });
+  });
+
+  const onUpgrade = (req, socket, head) => {
+    let pathname;
+    try { pathname = new URL(req.url, 'http://handmux.local').pathname; } catch { return false; }
+    if (pathname !== '/api/terminal-stream') return false;
+    wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
+    return true;
+  };
+
+  const close = () => {
+    clearInterval(heartbeat);
+    for (const stream of streams) stream.close();
+    streams.clear();
+    for (const ws of wss.clients) ws.close(1001, 'server shutting down');
+    wss.close();
+  };
+
+  return { onUpgrade, close };
+}

package/src/tmux/commands.js

@@ -94,6 +94,16 @@ export async function capturePane(paneId, linesBack) {
   return runTmux(['capture-pane', '-p', '-e', '-N', '-S', String(-Math.abs(linesBack)), '-t', paneId]);
 }
 
+// A single row capture re-emits that row's real starting attributes. The combined capture above
+// intentionally compresses SGR state across newlines, which makes an inherited background ambiguous.
+export async function capturePaneRow(paneId, row) {
+  return runTmux([
+    'capture-pane', '-p', '-e', '-N',
+    '-S', String(row), '-E', String(row),
+    '-t', paneId,
+  ]);
+}
+
 // Plain visible-screen capture — NO SGR escapes (unlike capturePane's `-e`), so the text parses cleanly.
 // Used to scrape a pending prompt/menu off the screen (see pendingPrompt.js).
 export async function capturePlain(paneId) {
@@ -153,6 +163,13 @@ export async function paneLocation(paneId) {
   return { session, window: windowId, windowName };
 }
 
+export async function paneSession(paneId) {
+  const out = await runTmux(['display-message', '-p', '-t', paneId, '#{session_id}']);
+  const id = out.trim();
+  if (!isSessionId(id)) throw new Error('pane session not found');
+  return id;
+}
+
 // Exit tmux copy/scroll mode if the pane is currently in it. Called before any user input so
 // text and keys reach the shell instead of being swallowed by tmux's mode key-bindings.
 export async function exitCopyModeIfActive(paneId) {

package/src/trimCapture.js

@@ -8,9 +8,9 @@
 // bottom. We apply this BEFORE hashing/sending, so the change-hash, the transferred body, and the
 // client's render + at-bottom logic all key off the same trimmed capture.
 //
-// A row counts as blank only if it has no glyph AND no SGR escape — a shaded/full-width padding row
-// (e.g. Claude Code's grey message bar) carries \x1b and is NEVER trimmed here; that stays for the
-// client's trimTrailingShadow (and such boxes are never the very bottom of the pane anyway).
+// A row counts as blank only if it has no glyph AND no SGR escape. captureBackground normalizes
+// ambiguous blank rows before this step, so genuinely shaded padding carries its explicit SGR while
+// a default-background blank may be trimmed normally.
 export const MAX_TRAILING_BLANK = 3;
 
 const isBlank = (row) => row === '' || (/^[ \t]*$/.test(row) && !row.includes('\x1b'));