@claudecollab/cli 0.1.0

package/packages/cli/src/relay-client.js

@@ -0,0 +1,271 @@
+// The host-side relay client — the host brain's one outbound connection to the
+// relay (spec §architecture: "one outbound connection"). It is the mirror image
+// of packages/relay/server.js's host channel: an ssh2 client that authenticates
+// as username 'host', opens a no-pty shell, and speaks the JSON-lines protocol
+// from packages/shared over that channel.
+//
+// Everything product-shaped stays in the CLI (bin/claude-share.js); this module
+// only frames messages and surfaces relay events as callbacks. It deliberately
+// knows nothing about drafts, roles, or the band.
+//
+//   host→relay: hello / reclaim / admit / deny / screen / to / drop / end / state
+//   relay→host: room / gone / knock / joined / left / key / resize / pointer / ui
+//
+// The host's ssh key is a stable identity: its fingerprint gates room reclaim on
+// the relay (spec §failure-behavior), so callers pass a persistent privateKey.
+
+import ssh2 from 'ssh2';
+import { createHash } from 'node:crypto';
+import { TYPES, encode, validate, Decoder } from '../../shared/protocol.js';
+
+const { Client, utils } = ssh2;
+
+/**
+ * Parse a relay location into { host, port }. Accepts `ssh://host:port`,
+ * `ssh://host` (port defaults to 22), and a bare `host:port`. Undefined/empty
+ * falls back to the localhost dev relay.
+ * @param {string} [url]
+ * @returns {{host:string, port:number}}
+ */
+export function parseRelayUrl(url) {
+  if (!url) return { host: '127.0.0.1', port: 2222 };
+  let s = String(url).trim();
+  if (!s.includes('://')) s = 'ssh://' + s;
+  let u;
+  try {
+    u = new URL(s);
+  } catch {
+    return { host: '127.0.0.1', port: 2222 };
+  }
+  return { host: u.hostname || '127.0.0.1', port: u.port ? Number(u.port) : 22 };
+}
+
+// Coerce screen/to payloads (Buffer or string) to the base64 the protocol wants.
+const toB64 = (data) => (Buffer.isBuffer(data) ? data : Buffer.from(String(data), 'utf8')).toString('base64');
+
+/**
+ * The opening protocol move for a (re)connection once it is ready: ask for a fresh
+ * room when we hold none, or RECLAIM the room we already own after a drop (spec
+ * §failure-behavior: "reconnect with the same key restores identity + role; relay
+ * holds the code 10 min"). bin/claude-share.js calls this each time a relay
+ * connection becomes ready, so an initial connect says hello and every reconnect
+ * reclaims — the piece the CLI was missing.
+ * @param {string|null|undefined} heldRoom the room code we currently hold, if any
+ * @returns {{t:'hello'} | {t:'reclaim', code:string}}
+ */
+export function openingMove(heldRoom) {
+  return heldRoom ? { t: 'reclaim', code: heldRoom } : { t: 'hello' };
+}
+
+/**
+ * Connect to the relay as the host and return an event/command handle.
+ *
+ * @param {object} opts
+ * @param {string} [opts.url]                relay location (default localhost:2222)
+ * @param {string|Buffer} [opts.privateKey]  host ssh private key (stable identity;
+ *                                            an ephemeral one is generated if omitted)
+ * @param {number} [opts.keepaliveInterval]  ssh keepalive ms (default 20s)
+ * @param {string} [opts.secret]             room-creation credential; rides every hello()
+ *                                            (a relay with ROOM_SECRET set requires it)
+ * @param {string} [opts.roomPass]           optional join password for the room this host
+ *                                            creates — the relay challenges every guest
+ *                                            with it before their knock is delivered
+ * @param {(fp:string)=>boolean} [opts.verifyHostKey]  called with the relay's SHA256:…
+ *                                            key fingerprint during the handshake; return
+ *                                            false to abort (impersonation defense).
+ *                                            Omitted = accept any key (dev/loopback).
+ * @returns {{
+ *   ready: Promise<void>,
+ *   onRoom, onGone, onRefused, onKnock, onJoin, onLeave, onKey, onResize, onPointer, onUi, onClose, onError,
+ *   hello():void, reclaim(code):void,
+ *   admit(id):void, deny(id):void,
+ *   sendScreen(data):void, sendTo(id,data):void, sendState(data):void,
+ *   drop(id,ban):void, end():void, close():void
+ * }}
+ */
+export function connectRelay(opts = {}) {
+  const { url, keepaliveInterval = 20000, secret, roomPass, verifyHostKey } = opts;
+  const { host, port } = parseRelayUrl(url);
+  // A stable key lets the host reclaim its room after a drop; if the caller has
+  // none we still connect (relay rejects `none` auth) with a throwaway key —
+  // reclaim just won't work across restarts, which is fine for a one-off run.
+  const privateKey = opts.privateKey ?? utils.generateKeyPairSync('ed25519').private;
+
+  const client = new Client();
+  const dec = new Decoder();
+
+  // One callback set per event; on*() returns an unsubscribe fn.
+  const sets = {
+    room: new Set(),
+    gone: new Set(),
+    refused: new Set(),
+    knock: new Set(),
+    join: new Set(),
+    leave: new Set(),
+    key: new Set(),
+    resize: new Set(),
+    pointer: new Set(),
+    ui: new Set(),
+    close: new Set(),
+    error: new Set(),
+  };
+  const on = (set) => (cb) => {
+    set.add(cb);
+    return () => set.delete(cb);
+  };
+  const emit = (name, ...args) => {
+    for (const cb of sets[name]) {
+      try {
+        cb(...args);
+      } catch {
+        /* a listener throwing must not desync the wire loop */
+      }
+    }
+  };
+
+  let stream = null;
+  let closed = false;
+
+  const send = (obj) => {
+    if (closed || !stream) return;
+    try {
+      stream.write(encode(obj));
+    } catch {
+      /* channel already gone */
+    }
+  };
+
+  // Route one decoded relay→host message to its callback set. Drop anything that
+  // fails validation (spec: fail closed — the host never acts on a malformed line).
+  const route = (msg) => {
+    if (!validate(msg)) return;
+    switch (msg.t) {
+      case TYPES.ROOM:
+        // webUrl: the relay's PUBLIC browser base (a deployed relay behind TLS) —
+        // links must print https://domain/room, not http://ssh-host:webPort/room.
+        return emit('room', msg.code, msg.webUrl);
+      case TYPES.GONE:
+        return emit('gone', msg.code);
+      case TYPES.REFUSED:
+        // The relay rejected our HELLO (reason 'secret' = bad/missing room
+        // credential). Not transient — the caller should stop, not reconnect.
+        return emit('refused', msg.reason);
+      case TYPES.KNOCK:
+        return emit('knock', { id: msg.id, name: msg.name, fp: msg.fp, seen: msg.seen });
+      case TYPES.JOINED:
+        return emit('join', msg.id);
+      case TYPES.LEFT:
+        return emit('leave', msg.id);
+      case TYPES.KEY:
+        return emit('key', { id: msg.id, data: Buffer.from(msg.data, 'base64') });
+      case TYPES.RESIZE:
+        return emit('resize', { id: msg.id, cols: msg.cols, rows: msg.rows });
+      // Browser-view inputs, labeled by the relay with the sending guest's id.
+      case TYPES.POINTER:
+        return emit('pointer', { id: msg.id, x: msg.x, y: msg.y });
+      case TYPES.UI:
+        return emit('ui', { id: msg.id, action: msg.action });
+      // host→relay types (hello/admit/screen/state/…) never arrive here; ignore.
+      default:
+        return;
+    }
+  };
+
+  let settled = false;
+  const ready = new Promise((resolve, reject) => {
+    client.on('error', (err) => {
+      if (!settled) {
+        settled = true;
+        reject(err);
+      }
+      emit('error', err);
+    });
+    client.on('close', () => {
+      closed = true;
+      emit('close');
+    });
+    client.on('ready', () => {
+      // No pty — the host channel is a pure byte pipe for the protocol (mirrors
+      // the relay, which routes by username 'host', not by whether a pty exists).
+      client.shell(false, (err, s) => {
+        if (err) {
+          if (!settled) {
+            settled = true;
+            reject(err);
+          }
+          return;
+        }
+        stream = s;
+        s.on('data', (chunk) => {
+          for (const msg of dec.push(chunk)) route(msg);
+        });
+        s.on('close', () => {
+          closed = true;
+          emit('close');
+        });
+        settled = true;
+        resolve();
+      });
+    });
+    const connectOpts = { host, port, username: 'host', privateKey, keepaliveInterval };
+    if (verifyHostKey) {
+      // ssh2 hands the raw public-key blob to hostVerifier during the handshake;
+      // we reduce it to the standard SHA256:… fingerprint (same derivation the
+      // relay uses) so callers compare one printable string. Returning false
+      // aborts the connection before any bytes of ours reach an impersonator.
+      connectOpts.hostVerifier = (keyBlob) => {
+        const fp = 'SHA256:' + createHash('sha256').update(keyBlob).digest('base64').replace(/=+$/, '');
+        try {
+          return verifyHostKey(fp) === true;
+        } catch {
+          return false; // a throwing verifier must fail closed, not connect
+        }
+      };
+    }
+    client.connect(connectOpts);
+  });
+  // Nobody may await ready (fire-and-forget wiring); don't crash on a rejection.
+  ready.catch(() => {});
+
+  return {
+    ready,
+
+    onRoom: on(sets.room), // (code)                       room granted (create or reclaim)
+    onGone: on(sets.gone), // (code)                       reclaim refused (expired / wrong key)
+    onRefused: on(sets.refused), // (reason)               hello rejected ('secret'); don't reconnect
+    onKnock: on(sets.knock), // ({id,name,fp,seen})        a guest is knocking
+    onJoin: on(sets.join), // (id)                         a guest was admitted
+    onLeave: on(sets.leave), // (id)                       a guest disconnected
+    onKey: on(sets.key), // ({id, data:Buffer})            guest keystrokes, labeled
+    onResize: on(sets.resize), // ({id, cols, rows})       guest terminal size
+    onPointer: on(sets.pointer), // ({id, x, y})           browser cursor move (normalized)
+    onUi: on(sets.ui), // ({id, action})                   browser button command, labeled
+    onClose: on(sets.close), // ()                         the control channel closed
+    onError: on(sets.error), // (err)                      ssh transport error
+
+    hello: () => send({ t: TYPES.HELLO, want: 'room', ...(secret ? { secret } : {}), ...(roomPass ? { pass: roomPass } : {}) }),
+    reclaim: (code) => send({ t: TYPES.RECLAIM, code }),
+    admit: (id) => send({ t: TYPES.ADMIT, id }),
+    deny: (id) => send({ t: TYPES.DENY, id }),
+    sendScreen: (data) => send({ t: TYPES.SCREEN, data: toB64(data) }),
+    sendTo: (id, data) => send({ t: TYPES.TO, id, data: toB64(data) }),
+    sendState: (data) => send({ t: TYPES.STATE, data }),
+    drop: (id, ban = false) => send({ t: TYPES.DROP, id, ban: !!ban }),
+    end: () => send({ t: TYPES.END }),
+
+    /** Tear down the transport without ending the room (e.g. on host crash). */
+    close: () => {
+      closed = true;
+      try {
+        stream?.end();
+      } catch {
+        /* already closed */
+      }
+      try {
+        client.end();
+      } catch {
+        /* already closed */
+      }
+    },
+  };
+}

package/packages/cli/src/renderer.js

@@ -0,0 +1,230 @@
+// The band renderer — the SINGLE status line painted under Claude's full-screen TUI.
+//
+// Post-dogfood verdict (design v2): the host terminal is the engine room — plain,
+// native Claude, exactly as solo. The multiplayer band is dead; the browser is the
+// one multiplayer surface for everyone, host included. All the terminal shows is one
+// status line, pinned to the very bottom row:
+//
+//   ─ <room> · <n> people · <claude-state> · <room URL> ─
+//
+// Claude runs in a PTY one row shorter than the real terminal (see pty.js), so its
+// absolute cursor addressing can never touch that bottom row. paint() draws only the
+// band row(s): it saves the cursor (DECSC), positions + clears each row, writes the
+// status line on the last one, and restores the cursor (DECRC) — the tmux status-bar
+// technique. paint() is a pure function of state (same state in, same ANSI out), so
+// it stays golden-file testable.
+
+// ── ANSI vocabulary ───────────────────────────────────────────────────────────
+const SAVE = '\x1b7'; // DECSC — save cursor position
+const RESTORE = '\x1b8'; // DECRC — restore cursor position
+const CLEAR_LINE = '\x1b[2K'; // erase entire line
+const RESET = '\x1b[0m';
+const ORANGE = '\x1b[38;5;214m'; // status line (matches spike band)
+const posLine = (row) => `\x1b[${row};1H`; // move to column 1 of `row`
+
+// Role → status-line glyph (spec §roles: viewer 👁, prompter ✎, host ★).
+// Still exported for the join context card (brain/card.js) and event toasts.
+export const ROLE_GLYPH = Object.freeze({
+  host: '★',
+  prompter: '✎',
+  viewer: '👁',
+});
+
+// ── display-width helpers ─────────────────────────────────────────────────────
+// A terminal cannot count JS UTF-16 code units; it counts cells. These helpers
+// let us truncate the status line so it can never wrap into Claude's rows. Width
+// follows the wcwidth convention: combining marks 0, East-Asian-wide + emoji 2,
+// ambiguous 1. Load-bearing for the "no overflow" invariant, not cosmetics.
+
+const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[78]/g;
+
+/** Remove CSI/OSC/DECSC-DECRC escape sequences (they occupy zero cells). */
+export function stripAnsi(str) {
+  return String(str).replace(ANSI_RE, '');
+}
+
+const inRanges = (cp, ranges) => {
+  for (const [lo, hi] of ranges) if (cp >= lo && cp <= hi) return true;
+  return false;
+};
+
+const ZERO_WIDTH = [
+  [0x0300, 0x036f], // combining diacritical marks
+  [0x0483, 0x0489],
+  [0x0591, 0x05bd],
+  [0x200b, 0x200f], // zero-width space/joiner + bidi marks
+  [0x202a, 0x202e],
+  [0x2060, 0x2064],
+  [0xfe00, 0xfe0f], // variation selectors
+  [0xfe20, 0xfe2f], // combining half marks
+];
+
+const WIDE = [
+  [0x1100, 0x115f], // Hangul Jamo
+  [0x2329, 0x232a],
+  [0x2e80, 0x303e], // CJK radicals … punctuation
+  [0x3041, 0x33ff],
+  [0x3400, 0x4dbf],
+  [0x4e00, 0x9fff], // CJK unified ideographs
+  [0xa000, 0xa4cf],
+  [0xac00, 0xd7a3], // Hangul syllables
+  [0xf900, 0xfaff], // CJK compatibility ideographs
+  [0xfe30, 0xfe4f], // CJK compatibility forms
+  [0xff00, 0xff60], // fullwidth forms
+  [0xffe0, 0xffe6],
+  [0x1f000, 0x1faff], // emoji & pictographs
+  [0x20000, 0x3fffd], // CJK extension planes
+];
+
+function cellWidth(cp) {
+  if (inRanges(cp, ZERO_WIDTH)) return 0;
+  return inRanges(cp, WIDE) ? 2 : 1;
+}
+
+/** Visible column width of a string, ignoring ANSI escapes. */
+export function stringWidth(str) {
+  let w = 0;
+  for (const ch of stripAnsi(str)) w += cellWidth(ch.codePointAt(0));
+  return w;
+}
+
+/**
+ * Truncate PLAIN text (no embedded ANSI) to at most `max` visible cells, never
+ * splitting a wide character across the boundary.
+ */
+export function truncateToWidth(str, max) {
+  if (max <= 0) return '';
+  let w = 0;
+  let out = '';
+  for (const ch of String(str)) {
+    const cw = cellWidth(ch.codePointAt(0));
+    if (w + cw > max) break;
+    out += ch;
+    w += cw;
+  }
+  return out;
+}
+
+/**
+ * Truncate to `max` cells like {@link truncateToWidth}, but when the text actually
+ * doesn't fit, end it in a single-cell ellipsis so a trimmed toast reads as clipped
+ * prose ("copy the invite…") instead of a raw mid-word cut (finding 5).
+ */
+export function ellipsize(str, max) {
+  if (max <= 0) return '';
+  const s = String(str);
+  if (stringWidth(s) <= max) return s; // fits whole — no ellipsis
+  if (max === 1) return '…';
+  return truncateToWidth(s, max - 1) + '…';
+}
+
+// ── the status line ─────────────────────────────────────────────────────────────
+
+const color = (sgr, plain, width) => (width <= 0 ? '' : sgr + truncateToWidth(plain, width) + RESET);
+
+const SEP = ' · ';
+const FRAME_L = '─ ';
+const FRAME_R = ' ─';
+
+/**
+ * The one and only band line: `─ <room> · <n> people · <claude-state> · <room URL> ─`.
+ * Missing pieces are simply dropped (no room URL when solo, no count when unknown);
+ * the whole line is width-clamped so it can never wrap into Claude's rows. Transient
+ * messages (toasts, pause, event notices) are folded into the claude-state slot by
+ * the caller — the band is one line and never grows.
+ *
+ * The URL is load-bearing: on the host's terminal it is the ONLY place the host-tab
+ * URL (with its token) is shown, and clipboard copy is best-effort/optional. Clamping
+ * the whole line truncated the URL — the last slot — into uselessness on common widths
+ * (100 cols cut it to "…8787/humble-s"; the 80-col floor left almost nothing). So the
+ * URL is packed FIRST at full width and never truncated; room, people and claude-state
+ * then fill what remains (that priority), the last one trimmed and the rest dropped —
+ * the URL always survives the clamp. Only an absurdly narrow terminal (< URL width)
+ * trims the URL, where the never-wrap-into-Claude invariant has to win.
+ *
+ * @param {object} state
+ * @param {string|null} [state.room]        room code (null ⇒ "claudecollab")
+ * @param {number} [state.people]           participant count
+ * @param {string} [state.claudeState]      Claude's state / a folded-in toast
+ * @param {string|null} [state.url]         the room URL to print (null when solo)
+ * @param {number} [width=80]               column budget
+ * @returns {string} colored, width-clamped line
+ */
+export function statusLine(state = {}, width = 80) {
+  const room = state.room || 'claudecollab';
+  const url = state.url ? String(state.url) : null;
+  const n = state.people;
+  const people = Number.isFinite(n) ? `${n} ${n === 1 ? 'person' : 'people'}` : null;
+  const claudeState = state.claudeState ? String(state.claudeState) : null;
+
+  const sepW = stringWidth(SEP);
+  const inner = width - stringWidth(FRAME_L) - stringWidth(FRAME_R);
+  if (inner <= 0) return color(ORANGE, truncateToWidth(`${FRAME_L}${room}`, width), width);
+
+  // Reading order for display vs keep-priority for the clamp (URL highest).
+  const display = [
+    { key: 'room', text: room },
+    { key: 'people', text: people },
+    { key: 'claude', text: claudeState },
+    { key: 'url', text: url },
+  ].filter((s) => s.text != null);
+  const priority = ['url', 'room', 'people', 'claude'];
+
+  const chosen = new Map(); // key -> text (whole, or truncated for the last that fits)
+  let used = 0; // inner columns consumed
+  for (const key of priority) {
+    const slot = display.find((s) => s.key === key);
+    if (!slot) continue;
+    const sep = chosen.size > 0 ? sepW : 0;
+    const w = stringWidth(slot.text);
+    if (used + sep + w <= inner) {
+      chosen.set(key, slot.text);
+      used += sep + w;
+      continue;
+    }
+    // Doesn't fit whole. The URL is kept even here (truncated only if it can't fit
+    // alone); every other slot is trimmed into what's left, then packing stops.
+    if (key === 'url') {
+      // A URL trimmed with an ellipsis reads as a broken link, so hard-cut it (this
+      // only happens far below the 80-col floor; see the doc comment above).
+      chosen.set(key, truncateToWidth(slot.text, inner - used - sep));
+    } else {
+      const budget = inner - used - sep;
+      // room/people/claude (toasts land here) ellipsize so a trim never cuts mid-word.
+      if (budget >= 1) chosen.set(key, ellipsize(slot.text, budget));
+    }
+    break;
+  }
+
+  const parts = display.filter((s) => chosen.has(s.key)).map((s) => chosen.get(s.key));
+  return color(ORANGE, `${FRAME_L}${parts.join(SEP)}${FRAME_R}`, width);
+}
+
+/**
+ * Render the band as a single ANSI string, positioned at the bottom `bandRows` rows
+ * of a `cols`×`rows` terminal. The status line sits on the band's LAST row (the
+ * terminal's very bottom); any rows above it in the band are cleared blank. The
+ * cursor is saved before and restored after so Claude's own cursor is never
+ * disturbed. In practice bandRows is 1 (the band is permanently one line).
+ *
+ * @param {object} state       see {@link statusLine} plus:
+ * @param {number} [state.cols=80]     real (clamped) terminal columns
+ * @param {number} [state.rows=24]     real (clamped) terminal rows
+ * @param {number} [state.bandRows=1]  reserved bottom rows
+ * @returns {string} ANSI for the band only (empty string if bandRows <= 0)
+ */
+export function paint(state = {}) {
+  const cols = state.cols ?? 80;
+  const rows = state.rows ?? 24;
+  const bandRows = state.bandRows ?? 1;
+  if (bandRows <= 0) return '';
+
+  const top = Math.max(1, rows - bandRows + 1);
+  let out = SAVE;
+  for (let i = 0; i < bandRows; i++) {
+    const content = i === bandRows - 1 ? statusLine(state, cols) : '';
+    out += posLine(top + i) + CLEAR_LINE + content;
+  }
+  out += RESTORE;
+  return out;
+}

package/packages/cli/src/screen-snapshot.js

@@ -0,0 +1,139 @@
+// A rolling snapshot of the child's current screen, so a guest admitted mid-session
+// sees the LIVE screen immediately — not blank space until the next frame (spec
+// §renderer: "there is exactly one live screen, mirrored to everyone"; dogfood
+// finding: a guest admitted while Claude was idle saw the context card, then nothing).
+//
+// We deliberately don't emulate a terminal (deps are ssh2 + node-pty only). Instead
+// we retain the bytes the child has emitted SINCE it last cleared the screen:
+//
+//   • an alternate-screen TUI (Claude v2) enters `?1049h`, then repaints with
+//     absolute cursor positioning — replaying the bytes since that enter/last clear
+//     reconstructs the current screen for a fresh attacher;
+//   • a line app (`cat`) never clears, so the buffer is simply the echoed content.
+//
+// A byte cap bounds memory; on overflow we keep the tail (the most recent, most
+// relevant paint). The host replays get() to a joiner right after the context card.
+
+// Sequences that wipe the whole screen (so earlier bytes no longer matter):
+//   \x1b[2J  clear entire screen      \x1b[3J  clear screen + scrollback
+//   \x1bc    full reset (RIS)         \x1b[?1049h  enter alternate screen
+const CLEAR_RE = /\x1b\[2J|\x1b\[3J|\x1bc|\x1b\[\?1049h/g;
+
+// A synchronized-update frame ends here (Claude v2). We trim the memory cap at a
+// frame boundary when we can, so a joiner's replay never starts mid-repaint.
+const SU_END = '\x1b[?2026l';
+
+// Cursor visibility (DECTCEM) is a STICKY mode set once on a state change, not
+// re-asserted per frame — so the establishing ?25h often lives in a frame the
+// clear-reset or cap-trim has already dropped, and a joiner replaying the window
+// resolves to cursor-hidden while everyone who watched live shows it. We track the
+// effective state across ALL pushed bytes and re-assert it at the end of get().
+const CURSOR_SHOW = '\x1b[?25h';
+const CURSOR_HIDE = '\x1b[?25l';
+
+// A COMPLETE escape sequence: CSI (ESC [ … final), OSC (ESC ] … BEL/ST), or a
+// 2-byte ESC form (ESC 7 / ESC 8). Used to find spans so a cut never lands in the
+// middle of one, and to decide whether a trailing ESC… is finished (finding 2).
+const ESC_SEQ = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[78]/g;
+const ESC_SEQ_AT_START = /^(?:\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[78])/;
+
+// The smallest index >= min at which slicing leaves a CLEAN start — never inside an
+// escape sequence, so a joiner's terminal never renders a fragment (";246m…") as
+// literal text. If min sits inside a sequence we jump to that sequence's end; in
+// plain text any index is safe, so min itself is returned.
+function safeStart(buf, min) {
+  if (min <= 0) return 0;
+  ESC_SEQ.lastIndex = 0;
+  let m;
+  while ((m = ESC_SEQ.exec(buf)) !== null) {
+    const start = m.index;
+    const end = start + m[0].length;
+    if (end <= min) continue; // span entirely before min → irrelevant
+    if (start >= min) return min; // min is in clean text before the next span
+    return end; // min is inside this span → jump past it
+  }
+  return min; // no span covers min → plain text
+}
+
+// Drop a DANGLING trailing escape (a "\x1b[38;5" with no final byte, or a bare ESC)
+// so the replay never ends mid-sequence and eat the live frames that follow it. A
+// completed sequence — even with trailing text — is kept whole.
+function dropTrailingPartial(s) {
+  const esc = s.lastIndexOf('\x1b');
+  if (esc === -1) return s; // no escape at all
+  if (ESC_SEQ_AT_START.test(s.slice(esc))) return s; // last ESC starts a complete seq
+  return s.slice(0, esc); // dangling partial → cut it off
+}
+
+export class ScreenSnapshot {
+  #buf = '';
+  #cap;
+  #cursorShown = true; // terminals start with a visible cursor
+
+  /** @param {{cap?:number}} [opts] max bytes retained (default 256 KiB) */
+  constructor({ cap = 1 << 18 } = {}) {
+    this.#cap = Math.max(1, cap | 0);
+  }
+
+  /** Absorb one chunk of child output (a frame or partial frame). */
+  push(chunk) {
+    if (!chunk) return;
+    const prevLen = this.#buf.length;
+    this.#buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+
+    // Track effective cursor visibility over the appended bytes. Scan a window
+    // reaching a few bytes back so a sequence split across chunks still counts.
+    const win = this.#buf.slice(Math.max(0, prevLen - 8));
+    const show = win.lastIndexOf(CURSOR_SHOW);
+    const hide = win.lastIndexOf(CURSOR_HIDE);
+    if (show !== -1 || hide !== -1) this.#cursorShown = show > hide;
+
+    // Drop everything before the last full-screen clear / alt-screen enter: the
+    // screen was wiped there, so nothing prior is visible any more. The cut lands ON
+    // the clear escape, so the retained buffer starts at a clean boundary.
+    CLEAR_RE.lastIndex = 0;
+    let last = -1;
+    let m;
+    while ((m = CLEAR_RE.exec(this.#buf))) last = m.index;
+    if (last > 0) this.#buf = this.#buf.slice(last);
+
+    this.#trim();
+  }
+
+  // Bound memory to the cap, cutting only at a CLEAN boundary — never mid escape
+  // sequence (finding 2). Prefer a frame boundary (right after an SU_END): the
+  // smallest such cut whose tail fits the cap, dropping whole older frames. When no
+  // frame boundary fits (a line app with no markers), fall back to the smallest
+  // escape-safe index so the retained tail can never begin inside a sequence.
+  #trim() {
+    if (this.#buf.length <= this.#cap) return;
+    const target = this.#buf.length - this.#cap;
+    let cut = -1;
+    let idx = this.#buf.indexOf(SU_END);
+    while (idx !== -1) {
+      const after = idx + SU_END.length;
+      if (this.#buf.length - after <= this.#cap) {
+        cut = after;
+        break;
+      }
+      idx = this.#buf.indexOf(SU_END, after);
+    }
+    if (cut === -1) cut = safeStart(this.#buf, target);
+    this.#buf = this.#buf.slice(cut);
+  }
+
+  /** The bytes to replay so an attacher sees the current screen (may be ''). */
+  get() {
+    const out = dropTrailingPartial(this.#buf);
+    if (!out) return out;
+    // Re-assert the effective cursor visibility: the sticky ?25h/?25l that set it
+    // may have been trimmed out of the window above (a joiner during a busy spell
+    // otherwise lands cursor-hidden while the host's terminal shows it).
+    return out + (this.#cursorShown ? CURSOR_SHOW : CURSOR_HIDE);
+  }
+
+  /** Bytes currently retained. */
+  get size() {
+    return this.#buf.length;
+  }
+}