hop2 0.11.0 → 0.11.2

package/demo/capture/mcp-client.mjs

@@ -0,0 +1,61 @@
+// Minimal stdio MCP client for driving mcp/hop-mcp.js from rig scripts
+// (spawn-aurora.mjs, dispatch-task.mjs).
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { REPO_ROOT } from "./capture-env.mjs";
+
+export function startMcp(clientName) {
+  const mcp = spawn(process.execPath, [path.join(REPO_ROOT, "mcp", "hop-mcp.js")], {
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  mcp.stderr.on("data", () => {});
+  let nextId = 1;
+  const pending = new Map();
+  let buf = "";
+  mcp.stdout.on("data", (chunk) => {
+    buf += chunk.toString();
+    let i;
+    while ((i = buf.indexOf("\n")) !== -1) {
+      const line = buf.slice(0, i).trim();
+      buf = buf.slice(i + 1);
+      if (!line) continue;
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id && pending.has(msg.id)) {
+          pending.get(msg.id)(msg);
+          pending.delete(msg.id);
+        }
+      } catch {}
+    }
+  });
+  const rpc = (method, params, timeoutMs = 240000) =>
+    new Promise((resolve, reject) => {
+      const id = nextId++;
+      pending.set(id, resolve);
+      mcp.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+      setTimeout(() => {
+        if (pending.has(id)) {
+          pending.delete(id);
+          reject(new Error(`rpc timeout: ${method}`));
+        }
+      }, timeoutMs);
+    });
+  const callTool = async (name, args, timeoutMs = 240000) => {
+    const res = await rpc("tools/call", { name, arguments: args }, timeoutMs);
+    const text = res.result?.content?.[0]?.text ?? "";
+    let parsed = null;
+    try {
+      parsed = JSON.parse(text);
+    } catch {}
+    return { isError: res.result?.isError === true, text, parsed };
+  };
+  const init = async () => {
+    await rpc("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: clientName, version: "0" }
+    });
+    mcp.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");
+  };
+  return { rpc, callTool, init, kill: () => mcp.kill() };
+}

package/demo/capture/native-css.mjs

@@ -0,0 +1,49 @@
+// CSS injected at document-start for the 02b "native local terminal" clip:
+// hide ALL web chrome (topbar, drawer/controls, footer, FAB, banners, toasts)
+// and make the terminal frame fill the whole viewport. The .terminal-scroll
+// padding (16px) is kept so text has a natural terminal margin.
+export const NATIVE_TERMINAL_CSS = `
+  .topbar, .controls, .terminal-footer, .drawer-toggle, .drawer-overlay,
+  .drawer-close, .connection-banner, .terminal-toast, .terminal-find {
+    display: none !important;
+  }
+  .app { padding: 0 !important; }
+  .session {
+    display: block !important;
+    padding: 0 !important;
+    gap: 0 !important;
+  }
+  .terminal { display: flex !important; }
+  .terminal-frame {
+    height: 100vh !important;
+    min-height: 100vh !important;
+    border: none !important;
+    border-radius: 0 !important;
+    box-shadow: none !important;
+    animation: none !important;
+  }
+  .terminal-scroll { scrollbar-width: none !important; }
+  .terminal-scroll::-webkit-scrollbar { display: none !important; }
+`;
+
+// Playwright addInitScript source that installs the style at document-start
+// (before first paint), so no chrome ever flashes into a recorded frame.
+export const NATIVE_CSS_INIT = `(() => {
+  const CSS = ${JSON.stringify(NATIVE_TERMINAL_CSS)};
+  let done = false;
+  const add = () => {
+    if (done) return;
+    const root = document.head || document.documentElement;
+    if (!root) return;
+    done = true;
+    const st = document.createElement("style");
+    st.textContent = CSS;
+    root.appendChild(st);
+  };
+  add();
+  if (!done) {
+    new MutationObserver((m, mo) => { add(); if (done) mo.disconnect(); })
+      .observe(document, { childList: true, subtree: true });
+    document.addEventListener("DOMContentLoaded", add);
+  }
+})();`;

package/demo/capture/setup-04.mjs

@@ -0,0 +1,67 @@
+// Recreate the four sanitized demo sessions for the 04-phone-switcher clip,
+// PHONE-FIT. Every PTY is created at 46x40 AND re-claimed via REST resize
+// after the last write, so the API client is the latest typer and its size
+// wins the election (same trick the capture driver uses for clip 03). No
+// 140-col content ever exists, so the phone view cannot pan/crop the left
+// text edge.
+//
+// Aurora2 runs a scripted agent-lookalike ticker (tools/agent.sh) — NOT a
+// real agent — because clip 04 only shows preview cards plus a brief
+// terminal shot.
+import {
+  getHopState, ensureTerminal, execTerminal, resizeTerminal, sleep
+} from "../hop-demo-lib.mjs";
+import {
+  WORKSPACE, sanitizedShell, WIPE, saveTerminals, seedDemoTree
+} from "./capture-env.mjs";
+
+const state = getHopState();
+seedDemoTree();
+
+const COLS = 46, ROWS = 40;
+
+const defs = [
+  { name: "Lyra2",    after: ["ls -1"] },
+  { name: "Aurora2",  after: ["sh ../tools/agent.sh"] },
+  { name: "Nebula2",  after: ["sh ../tools/build.sh"] },
+  { name: "Polaris2", after: ["sh ../tools/metrics.sh"] }
+];
+
+const out = {};
+for (const def of defs) {
+  const t = await ensureTerminal(state, { name: def.name, cwd: WORKSPACE, cols: COLS, rows: ROWS });
+  await resizeTerminal(state, t.id, COLS, ROWS);
+  await sleep(1400);                      // let the real zsh prompt appear
+  await execTerminal(state, t.id, sanitizedShell("demo@hop $ "));
+  await sleep(900);
+  await execTerminal(state, t.id, WIPE);  // wipe screen + scrollback (removes real prompt)
+  await sleep(500);
+  for (const cmd of def.after) {
+    await execTerminal(state, t.id, cmd);
+    await sleep(700);
+  }
+  // Re-claim the size election AFTER the last write on this terminal.
+  await resizeTerminal(state, t.id, COLS, ROWS);
+  out[def.name] = { terminalId: t.id, sessionName: t.sessionName || def.name };
+  console.log(`ready: ${def.name} -> ${t.id}`);
+}
+saveTerminals(out);
+
+// Sanity: every demo PTY must report phone-fit width, and no preview line may
+// exceed COLS characters.
+await sleep(2500);
+const sess = await fetch(`${state.localUrl}/api/sessions`, {
+  headers: { Authorization: `Bearer ${state.sessionSecret}` }
+}).then((r) => r.json());
+for (const def of defs) {
+  const s = (sess.sessions || []).find((x) => x.name === def.name);
+  console.log(`${def.name}: cols=${s?.cols} rows=${s?.rows} live=${s?.live}`);
+  const p = await fetch(
+    `${state.localUrl}/api/sessions/preview?name=${encodeURIComponent(def.name)}`,
+    { headers: { Authorization: `Bearer ${state.sessionSecret}` } }
+  ).then((r) => r.json()).catch(() => ({}));
+  const maxw = Math.max(0, ...String(p.text || "").split("\n").map((l) => l.length));
+  console.log(`${def.name}: preview max line width = ${maxw}`);
+  if (maxw > COLS) throw new Error(`ABORT: ${def.name} preview wider than ${COLS} cols`);
+}
+console.log("done");

package/demo/capture/setup-sessions.mjs

@@ -0,0 +1,40 @@
+// Create the sanitized demo shell sessions: Lyra2, Nebula2, Polaris2. The
+// "2"-suffixed internal names keep them clear of any real session or stale
+// alias; the capture driver's DOM rewriter displays them as Lyra/Nebula/
+// Polaris. Each gets a deterministic clean bash (env -i) and a scrollback
+// wipe, then Nebula2/Polaris2 start endless colorful tickers so switcher
+// cards look live. Run spawn-aurora.mjs afterwards for the agent session.
+import {
+  getHopState, ensureTerminal, execTerminal, resizeTerminal, sleep
+} from "../hop-demo-lib.mjs";
+import {
+  WORKSPACE, sanitizedShell, WIPE, loadTerminals, saveTerminals, seedDemoTree
+} from "./capture-env.mjs";
+
+const state = getHopState();
+seedDemoTree();
+
+const defs = [
+  { name: "Lyra2",    after: ["ls -1"] },
+  { name: "Nebula2",  after: ["sh ../tools/build.sh"] },
+  { name: "Polaris2", after: ["sh ../tools/metrics.sh"] }
+];
+
+const out = loadTerminals({ required: false });
+for (const def of defs) {
+  const t = await ensureTerminal(state, { name: def.name, cwd: WORKSPACE, cols: 140, rows: 40 });
+  await resizeTerminal(state, t.id, 140, 40);
+  await sleep(1200);                      // let the real zsh prompt appear
+  await execTerminal(state, t.id, sanitizedShell());
+  await sleep(900);
+  await execTerminal(state, t.id, WIPE);  // wipe screen + scrollback (removes real prompt)
+  await sleep(500);
+  for (const cmd of def.after) {
+    await execTerminal(state, t.id, cmd);
+    await sleep(700);
+  }
+  out[def.name] = { terminalId: t.id, sessionName: t.sessionName || def.name };
+  console.log(`ready: ${def.name} -> ${t.id}`);
+}
+saveTerminals(out);
+console.log("done");

package/demo/capture/spawn-aurora.mjs

@@ -0,0 +1,53 @@
+// Spawn a real coding agent in session Aurora2 (displayed as "Aurora") via
+// the Hop MCP server. Wipes scrollback before launch so no real shell prompt
+// survives, accepts a trust prompt if one appears, checks the agent is on
+// screen, and stores terminal info for later dispatch.
+//
+// The agent command defaults to `claude`; override with HOP_CAPTURE_AGENT.
+import { startMcp } from "./mcp-client.mjs";
+import {
+  AGENT_CMD, WORKSPACE, loadTerminals, saveTerminals, seedDemoTree
+} from "./capture-env.mjs";
+
+seedDemoTree();
+const mcp = startMcp("video-capture");
+
+try {
+  await mcp.init();
+
+  const res = await mcp.callTool("hopx_spawn_agent", {
+    name: "Aurora2",
+    cwd: WORKSPACE,
+    agent: "custom",
+    command: `clear; printf '\\033[3J'; ${AGENT_CMD}`,
+    ready_timeout_ms: 120000,
+    cols: 140, rows: 40
+  }, 240000);
+  if (res.isError || !res.parsed?.terminal_id) {
+    console.error("SPAWN FAIL: " + res.text.slice(0, 500));
+    process.exit(1);
+  }
+  const terminalId = res.parsed.terminal_id;
+  console.log(`spawned terminal_id=${terminalId} ready=${res.parsed.ready}`);
+
+  // Screen check: trust prompt? agent visible?
+  const agentToken = AGENT_CMD.split(/\s+/)[0].toLowerCase();
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const ui = await mcp.callTool("hop_read_terminal", { terminal_id: terminalId, mode: "ui" }, 30000);
+    const screen = JSON.stringify(ui.parsed?.ui?.lines || ui.text || "").toLowerCase();
+    if (screen.includes("do you trust") || screen.includes("trust the files")) {
+      console.log("trust prompt detected -> accepting");
+      await mcp.callTool("hop_write_terminal", { terminal_id: terminalId, data: "\r" }, 20000);
+      await new Promise((r) => setTimeout(r, 4000));
+      continue;
+    }
+    console.log(`agent-on-screen=${screen.includes(agentToken)}`);
+    console.log("screen sample: " + screen.slice(0, 400));
+    break;
+  }
+  const info = loadTerminals({ required: false });
+  info.Aurora2 = { terminalId, sessionName: res.parsed.sessionName || "Aurora2" };
+  saveTerminals(info);
+} finally {
+  mcp.kill();
+}

package/demo/capture/tools/agent.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+# Demo agent-lookalike ticker — endless, sanitized, phone-width (<=44 cols).
+# NOT a real agent: scripted output that reads like one for preview cards.
+C="\033[36m"; G="\033[32m"; M="\033[35m"; D="\033[2m"; B="\033[1m"; R="\033[0m"
+O="\033[38;5;208m"
+printf "${O}✻${R} ${B}agent${R} ${D}· workspace tour${R}\n\n"
+printf "${D}>${R} walk the repo and draft a refactor plan\n\n"
+i=0
+while true; do
+  i=$((i+1))
+  case $((i % 16)) in
+    0)  printf "${G}●${R} Read ${D}README.md${R}\n";;
+    1)  printf "  ${D}⎿  38 lines${R}\n";;
+    2)  printf "\n${C}✻ Thinking…${R}\n\n";;
+    3)  printf "  The server keeps one room per\n";;
+    4)  printf "  session; presence rides the same\n";;
+    5)  printf "  socket as terminal frames.\n\n";;
+    6)  printf "${G}●${R} Read ${D}server/rooms.ts${R}\n";;
+    7)  printf "  ${D}⎿  112 lines${R}\n";;
+    8)  printf "  Rooms elect a size owner — the\n";;
+    9)  printf "  latest typer wins, so phones\n";;
+    10) printf "  never fight the desktop.\n\n";;
+    11) printf "${G}●${R} Grep ${D}\"presence\" · 9 matches${R}\n";;
+    12) printf "  Next: split usePresence into\n";;
+    13) printf "  transport + view-model layers,\n";;
+    14) printf "  then add reconnect backoff.\n\n";;
+    15) printf "${M}◐${R} ${D}streaming…${R}\n";;
+  esac
+  sleep 0.8
+done

package/demo/capture/tools/build.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+# Demo build/test ticker — endless, colorful, sanitized.
+G="\033[32m"; Y="\033[33m"; C="\033[36m"; D="\033[2m"; B="\033[1m"; R="\033[0m"
+i=0
+printf "${B}vite build ${D}(watch mode)${R}\n\n"
+while true; do
+  i=$((i+1))
+  ts=$(date +%H:%M:%S)
+  case $((i % 6)) in
+    0) printf "${D}${ts}${R} ${C}transform${R} src/components/RoomView.tsx\n";;
+    1) printf "${D}${ts}${R} ${C}transform${R} src/hooks/usePresence.ts\n";;
+    2) printf "${D}${ts}${R} ${G}✓${R} 128 modules transformed in $((180 + i % 140))ms\n";;
+    3) printf "${D}${ts}${R} ${G}✓${R} dist/assets/index.js  ${D}142.5 kB │ gzip: 45.9 kB${R}\n";;
+    4) printf "${D}${ts}${R} ${Y}hmr update${R} /src/styles.css\n";;
+    5) printf "${D}${ts}${R} ${G}✓${R} tests: 47 passed ${D}(bells 12, election 9, switcher 26)${R}\n";;
+  esac
+  sleep 1
+done

package/demo/capture/tools/metrics.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+# Demo deploy/metrics ticker — endless, sanitized.
+G="\033[32m"; Y="\033[33m"; M="\033[35m"; D="\033[2m"; B="\033[1m"; R="\033[0m"
+i=0
+printf "${B}edge-deploy ${D}watching production${R}\n\n"
+while true; do
+  i=$((i+1))
+  ts=$(date +%H:%M:%S)
+  case $((i % 5)) in
+    0) printf "${D}${ts}${R} ${M}render${R} p50=$((18 + i % 9))ms p99=$((61 + i % 22))ms\n";;
+    1) printf "${D}${ts}${R} ${G}healthy${R} 12/12 instances ${D}us-east, eu-west, ap-south${R}\n";;
+    2) printf "${D}${ts}${R} ${G}✓${R} cdn cache hit $((92 + i % 6)).$((i % 10))%%\n";;
+    3) printf "${D}${ts}${R} ${Y}queue${R} depth=$((i % 4)) ${D}drained in $((3 + i % 5))s${R}\n";;
+    4) printf "${D}${ts}${R} ${G}✓${R} rollout wave $((1 + i % 4))/4 complete\n";;
+  esac
+  sleep 1
+done

package/docs/hero-overview.svg

@@ -0,0 +1,119 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="980" height="640" viewBox="0 0 980 640" role="img" aria-label="One hop runtime, three surfaces: a browser window, an MCP agent panel, and a CLI window all attached to the same live terminal session named claude. A legend explains web sharing, MCP-native agent control, and the CLI client.">
+  <defs>
+    <linearGradient id="canvas" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#16171c"/>
+      <stop offset="1" stop-color="#101116"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="160%">
+      <feDropShadow dx="0" dy="6" stdDeviation="14" flood-color="#000000" flood-opacity="0.45"/>
+    </filter>
+    <clipPath id="winBrowser"><rect x="40" y="78" width="460" height="296" rx="10"/></clipPath>
+    <clipPath id="winMcp"><rect x="540" y="78" width="400" height="186" rx="10"/></clipPath>
+    <clipPath id="winCli"><rect x="540" y="292" width="400" height="182" rx="10"/></clipPath>
+  </defs>
+
+  <!-- canvas -->
+  <rect x="0.5" y="0.5" width="979" height="639" rx="18" fill="url(#canvas)" stroke="#272831"/>
+
+  <!-- kicker -->
+  <text x="490" y="44" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="12.5" letter-spacing="0.14em" fill="#8d909b">ONE RUNTIME — THE SAME LIVE SESSION IN THE BROWSER, THE TERMINAL, AND UNDER AGENT CONTROL</text>
+
+  <!-- ═══════════ ① browser window (web client, light theme) ═══════════ -->
+  <g filter="url(#shadow)">
+    <rect x="40" y="78" width="460" height="296" rx="10" fill="#ffffff" stroke="#d4d5db"/>
+  </g>
+  <g clip-path="url(#winBrowser)" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="11.5">
+    <!-- browser chrome -->
+    <rect x="40" y="78" width="460" height="30" fill="#e9eaef"/>
+    <circle cx="60" cy="93" r="5" fill="#ff5f57"/>
+    <circle cx="76" cy="93" r="5" fill="#febc2e"/>
+    <circle cx="92" cy="93" r="5" fill="#28c840"/>
+    <rect x="130" y="85" width="300" height="16" rx="8" fill="#ffffff" stroke="#d4d5db"/>
+    <text x="280" y="96.5" text-anchor="middle" fill="#6e6e73" font-size="10">https://hop.example.com/s/claude/</text>
+    <!-- web topbar -->
+    <rect x="40" y="108" width="460" height="32" fill="#f2f2f7"/>
+    <rect x="54" y="115" width="18" height="18" rx="5" fill="#7c3aed"/>
+    <text x="63" y="128" text-anchor="middle" font-size="10">🐰</text>
+    <text x="80" y="127.5" fill="#1d1d1f" font-weight="700" font-size="11">Hay</text>
+    <rect x="306" y="113" width="84" height="22" rx="11" fill="#ffffff" stroke="#dcdce3"/>
+    <text x="318" y="127.5" font-size="10"><tspan fill="#1a7f37">●</tspan><tspan fill="#1d1d1f" font-weight="600"> alice</tspan></text>
+    <rect x="396" y="113" width="92" height="22" rx="11" fill="#ffffff" stroke="#7c3aed"/>
+    <text x="406" y="127.5" font-size="10"><tspan fill="#7c3aed">●</tspan><tspan fill="#1d1d1f" font-weight="600"> claude</tspan><tspan fill="#6e6e73"> ai</tspan></text>
+    <!-- terminal body -->
+    <text x="58" y="166"><tspan fill="#6e6e73">$</tspan><tspan fill="#1d1d1f"> npm test</tspan></text>
+    <text x="58" y="188"><tspan fill="#1a7f37">✓</tspan><tspan fill="#1d1d1f"> 20 tests passed</tspan><tspan fill="#6e6e73"> (1.2s)</tspan></text>
+    <text x="58" y="218"><tspan fill="#6e6e73">$</tspan><tspan fill="#1d1d1f"> claude</tspan></text>
+    <text x="58" y="240"><tspan fill="#7c3aed">✻</tspan><tspan fill="#1d1d1f"> Refactoring rooms.ts…</tspan></text>
+    <text x="58" y="262" fill="#6e6e73">  ⎿ Updated packages/shared/protocol.ts</text>
+    <text x="58" y="292"><tspan fill="#6e6e73">&gt;</tspan></text>
+    <rect x="72" y="281" width="7" height="13" fill="#7c3aed" opacity="0.85"/>
+    <!-- web status bar -->
+    <rect x="40" y="344" width="460" height="30" fill="#e9e9ed"/>
+    <rect x="48" y="349" width="62" height="20" rx="5" fill="#7c3aed"/>
+    <text x="79" y="363" text-anchor="middle" fill="#ffffff" font-weight="700" font-size="10.5">claude</text>
+    <text x="118" y="363" fill="#6e6e73" font-size="10.5">~/code/hop2</text>
+    <text x="492" y="363" text-anchor="end" font-size="10.5"><tspan fill="#6e6e73">⌘F find · 2 viewers </tspan><tspan fill="#1a7f37">●</tspan></text>
+  </g>
+
+  <!-- ═══════════ ② MCP agent panel ═══════════ -->
+  <g filter="url(#shadow)">
+    <rect x="540" y="78" width="400" height="186" rx="10" fill="#111116" stroke="#2c2c31"/>
+  </g>
+  <g clip-path="url(#winMcp)" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="11">
+    <rect x="540" y="78" width="400" height="28" fill="#1a1a1f"/>
+    <text x="556" y="96.5" fill="#93939b" font-size="10.5">Claude Code — MCP client</text>
+    <rect x="848" y="84" width="78" height="17" rx="8.5" fill="none" stroke="#a78bfa"/>
+    <text x="887" y="96" text-anchor="middle" fill="#a78bfa" font-size="9.5">hop-mcp</text>
+    <text x="556" y="126"><tspan fill="#e6e6e9">▸ hop_create_terminal</tspan><tspan fill="#93939b"> { name: "claude" }</tspan></text>
+    <text x="556" y="144"><tspan fill="#3fb950">  ✓</tspan><tspan fill="#93939b"> { id: "t_4f21", sessionName: "claude" }</tspan></text>
+    <text x="556" y="172"><tspan fill="#e6e6e9">▸ hopx_exec</tspan><tspan fill="#93939b"> { command: "npm test" }</tspan></text>
+    <text x="556" y="190"><tspan fill="#3fb950">  ✓</tspan><tspan fill="#93939b"> exit_code 0 · "20 tests passed"</tspan></text>
+    <text x="556" y="218"><tspan fill="#e6e6e9">▸ hop_wait_terminal</tspan><tspan fill="#93939b"> { until_agent_done: true }</tspan></text>
+    <text x="556" y="236"><tspan fill="#d29922">  ⧗</tspan><tspan fill="#93939b"> waiting — agent turn in progress…</tspan></text>
+  </g>
+
+  <!-- ═══════════ ③ CLI window (dark theme) ═══════════ -->
+  <g filter="url(#shadow)">
+    <rect x="540" y="292" width="400" height="182" rx="10" fill="#17181d" stroke="#2e3038"/>
+  </g>
+  <g clip-path="url(#winCli)" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="11">
+    <rect x="540" y="292" width="400" height="26" fill="#1f2026"/>
+    <circle cx="558" cy="305" r="4.5" fill="#ff5f57"/>
+    <circle cx="573" cy="305" r="4.5" fill="#febc2e"/>
+    <circle cx="588" cy="305" r="4.5" fill="#28c840"/>
+    <text x="740" y="309" text-anchor="middle" fill="#8d909b" font-size="10" font-family="-apple-system, 'Segoe UI', sans-serif">hop attach claude</text>
+    <text x="556" y="342"><tspan fill="#3fb950">●</tspan><tspan fill="#93939b"> Attached to 'claude' (3 participants)</tspan></text>
+    <text x="556" y="368"><tspan fill="#93939b">&gt;</tspan></text>
+    <rect x="570" y="357" width="7" height="13" fill="#a78bfa" opacity="0.85"/>
+    <!-- status bar -->
+    <rect x="540" y="408" width="400" height="22" fill="#2a2a2e"/>
+    <rect x="540" y="408" width="58" height="22" fill="#a78bfa"/>
+    <text x="569" y="423" text-anchor="middle" fill="#1d1d1f" font-weight="700" font-size="10.5">claude</text>
+    <text x="606" y="423" fill="#93939b" font-size="10.5">~/code/hop2</text>
+    <text x="930" y="423" text-anchor="end" font-size="10.5"><tspan fill="#93939b">peers: alice, claude* · </tspan><tspan fill="#3fb950">●</tspan></text>
+    <!-- hint bar -->
+    <rect x="540" y="430" width="400" height="22" fill="#232327"/>
+    <text x="552" y="445" font-size="10.5"><tspan fill="#e6e6e9">⌃G </tspan><tspan fill="#93939b">detach · </tspan><tspan fill="#e6e6e9">⌥F </tspan><tspan fill="#93939b">find · </tspan><tspan fill="#e6e6e9">⌥C </tspan><tspan fill="#93939b">control · </tspan><tspan fill="#e6e6e9">⌥0 </tspan><tspan fill="#93939b">live</tspan></text>
+  </g>
+
+  <!-- numbered badges -->
+  <g font-family="-apple-system, 'Segoe UI', sans-serif" font-size="11" font-weight="bold" text-anchor="middle">
+    <circle cx="40" cy="94" r="9" fill="#8b6ef0"/><text x="40" y="98" fill="#ffffff">1</text>
+    <circle cx="540" cy="94" r="9" fill="#8b6ef0"/><text x="540" y="98" fill="#ffffff">2</text>
+    <circle cx="540" cy="308" r="9" fill="#8b6ef0"/><text x="540" y="312" fill="#ffffff">3</text>
+  </g>
+
+  <!-- legend -->
+  <g font-family="-apple-system, 'Segoe UI', sans-serif">
+    <g font-size="11" font-weight="bold" text-anchor="middle" fill="#ffffff">
+      <circle cx="60" cy="516" r="8" fill="#8b6ef0"/><text x="60" y="520">1</text>
+      <circle cx="60" cy="556" r="8" fill="#8b6ef0"/><text x="60" y="560">2</text>
+      <circle cx="60" cy="596" r="8" fill="#8b6ef0"/><text x="60" y="600">3</text>
+    </g>
+    <g font-size="13.5" fill="#e8e9ee">
+      <text x="78" y="521"><tspan font-weight="600">Share in the browser</tspan><tspan fill="#9a9da8"> — tunneled anywhere, with presence, typing markers, and take/release control.</tspan></text>
+      <text x="78" y="561"><tspan font-weight="600">MCP-native agents</tspan><tspan fill="#9a9da8"> — Claude Code, Codex &amp; friends create, drive, and read the same sessions.</tspan></text>
+      <text x="78" y="601"><tspan font-weight="600">Attach from any terminal</tspan><tspan fill="#9a9da8"> — detach freely; sessions persist on the hop runtime.</tspan></text>
+    </g>
+  </g>
+</svg>

package/docs/hero.svg

@@ -0,0 +1,118 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="980" height="600" viewBox="0 0 980 600" role="img" aria-label="Annotated screenshot of the hop terminal: a dark-themed terminal window with a session chip, live state dot, scroll indicator and keycap hints, next to a light-themed window showing adaptive themes and scrollback search; a legend explains each numbered feature.">
+  <defs>
+    <linearGradient id="canvas" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#16171c"/>
+      <stop offset="1" stop-color="#101116"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="160%">
+      <feDropShadow dx="0" dy="6" stdDeviation="14" flood-color="#000000" flood-opacity="0.45"/>
+    </filter>
+    <clipPath id="winDark"><rect x="48" y="48" width="580" height="300" rx="10"/></clipPath>
+    <clipPath id="winLight"><rect x="664" y="96" width="276" height="136" rx="8"/></clipPath>
+  </defs>
+
+  <!-- canvas -->
+  <rect x="0.5" y="0.5" width="979" height="599" rx="18" fill="url(#canvas)" stroke="#272831"/>
+
+  <!-- ======================= dark terminal window ======================= -->
+  <g filter="url(#shadow)">
+    <rect x="48" y="48" width="580" height="300" rx="10" fill="#17181d" stroke="#2e3038"/>
+  </g>
+  <g clip-path="url(#winDark)" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13">
+    <!-- chrome -->
+    <rect x="48" y="48" width="580" height="32" fill="#1f2026"/>
+    <circle cx="70" cy="64" r="5.5" fill="#ff5f57"/>
+    <circle cx="88" cy="64" r="5.5" fill="#febc2e"/>
+    <circle cx="106" cy="64" r="5.5" fill="#28c840"/>
+    <text x="338" y="68.5" text-anchor="middle" fill="#8d909b" font-size="12" font-family="-apple-system, 'Segoe UI', sans-serif">hop attach claude — dark</text>
+
+    <!-- body -->
+    <text x="64" y="106"><tspan fill="#93939b">$</tspan><tspan fill="#e6e6e9"> hop attach claude</tspan></text>
+    <text x="64" y="128"><tspan fill="#3fb950">●</tspan><tspan fill="#93939b"> Attached to 'claude' (2 participants)</tspan></text>
+    <text x="64" y="172"><tspan fill="#a78bfa">✻</tspan><tspan fill="#e6e6e9"> Refactoring rooms.ts…</tspan></text>
+    <text x="64" y="194" fill="#93939b">  ⎿ Updated packages/shared/protocol.ts</text>
+    <text x="64" y="216" fill="#93939b">  ⎿ Ran vitest — 20 tests passed</text>
+    <text x="64" y="260"><tspan fill="#3fb950">✓</tspan><tspan fill="#e6e6e9"> Done. Anything else?</tspan></text>
+    <text x="64" y="282"><tspan fill="#93939b">&gt;</tspan><tspan fill="#e6e6e9"> </tspan></text>
+    <rect x="80" y="271" width="8" height="14" fill="#a78bfa" opacity="0.85"/>
+
+    <!-- status bar -->
+    <rect x="48" y="300" width="580" height="24" fill="#2a2a2e"/>
+    <rect x="48" y="300" width="66" height="24" fill="#a78bfa"/>
+    <text x="81" y="316.5" text-anchor="middle" fill="#1d1d1f" font-weight="bold">claude</text>
+    <text x="122" y="316.5" fill="#93939b">~/code/hop2</text>
+    <text x="612" y="316.5" text-anchor="end"><tspan fill="#e6e6e9">scroll 142/520 · ⌥0 live</tspan><tspan fill="#93939b"> · peers: alice* · </tspan><tspan fill="#3fb950">●</tspan></text>
+
+    <!-- hint bar -->
+    <rect x="48" y="324" width="580" height="24" fill="#232327"/>
+    <text x="60" y="340.5"><tspan fill="#e6e6e9">⌃G </tspan><tspan fill="#93939b">detach · </tspan><tspan fill="#e6e6e9">⌃Q </tspan><tspan fill="#93939b">kill · </tspan><tspan fill="#e6e6e9">⌥←→↑↓ </tspan><tspan fill="#93939b">pan · </tspan><tspan fill="#e6e6e9">⌥0 </tspan><tspan fill="#93939b">live · </tspan><tspan fill="#e6e6e9">⌥F </tspan><tspan fill="#93939b">find · </tspan><tspan fill="#e6e6e9">⌥C </tspan><tspan fill="#93939b">control</tspan></text>
+  </g>
+
+  <!-- ======================= light terminal window ======================= -->
+  <g filter="url(#shadow)">
+    <rect x="664" y="96" width="276" height="136" rx="8" fill="#ffffff" stroke="#d4d5db"/>
+  </g>
+  <g clip-path="url(#winLight)" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="11">
+    <rect x="664" y="96" width="276" height="26" fill="#e9eaef"/>
+    <circle cx="681" cy="109" r="4.5" fill="#ff5f57"/>
+    <circle cx="696" cy="109" r="4.5" fill="#febc2e"/>
+    <circle cx="711" cy="109" r="4.5" fill="#28c840"/>
+    <text x="812" y="113" text-anchor="middle" fill="#7a7d88" font-size="10.5" font-family="-apple-system, 'Segoe UI', sans-serif">hop — light</text>
+
+    <text x="676" y="140"><tspan fill="#6e6e73">$</tspan><tspan fill="#1d1d1f"> npm run build</tspan></text>
+    <text x="676" y="158"><tspan fill="#1a7f37">✓</tspan><tspan fill="#1d1d1f"> built in 0.6s</tspan></text>
+
+    <!-- status bar -->
+    <rect x="664" y="166" width="276" height="22" fill="#e9e9ed"/>
+    <rect x="664" y="166" width="48" height="22" fill="#7c3aed"/>
+    <text x="688" y="181" text-anchor="middle" fill="#ffffff" font-weight="bold">build</text>
+    <text x="718" y="181" fill="#6e6e73">~/code</text>
+    <text x="928" y="181" text-anchor="end"><tspan fill="#b45309">reconnecting · ●</tspan></text>
+
+    <!-- hint bar : search -->
+    <rect x="664" y="188" width="276" height="22" fill="#f2f2f7"/>
+    <text x="676" y="203"><tspan fill="#7c3aed">/error</tspan><tspan fill="#1d1d1f">  3/17</tspan><tspan fill="#6e6e73"> · ↓ next · ↑ prev · Esc</tspan></text>
+
+    <!-- toast strip -->
+    <rect x="664" y="210" width="276" height="22" fill="#f2f2f7"/>
+    <text x="676" y="225"><tspan fill="#1a7f37">✓ </tspan><tspan fill="#1d1d1f">Sent 12 line(s) to clipboard</tspan></text>
+  </g>
+
+  <!-- ======================= numbered badges ======================= -->
+  <g font-family="-apple-system, 'Segoe UI', sans-serif" font-size="11" font-weight="bold" text-anchor="middle">
+    <circle cx="44" cy="312" r="9" fill="#8b6ef0"/><text x="44" y="316" fill="#ffffff">1</text>
+    <circle cx="632" cy="312" r="9" fill="#8b6ef0"/><text x="632" y="316" fill="#ffffff">2</text>
+    <circle cx="466" cy="296" r="9" fill="#8b6ef0"/><text x="466" y="300" fill="#ffffff">3</text>
+    <circle cx="300" cy="352" r="9" fill="#8b6ef0"/><text x="300" y="356" fill="#ffffff">4</text>
+    <circle cx="662" cy="109" r="9" fill="#8b6ef0"/><text x="662" y="113" fill="#ffffff">5</text>
+    <circle cx="942" cy="199" r="9" fill="#8b6ef0"/><text x="942" y="203" fill="#ffffff">6</text>
+  </g>
+
+  <!-- ======================= legend ======================= -->
+  <g font-family="-apple-system, 'Segoe UI', sans-serif">
+    <g font-size="11" font-weight="bold" text-anchor="middle" fill="#ffffff">
+      <circle cx="60" cy="416" r="8" fill="#8b6ef0"/><text x="60" y="420">1</text>
+      <circle cx="60" cy="472" r="8" fill="#8b6ef0"/><text x="60" y="476">2</text>
+      <circle cx="60" cy="528" r="8" fill="#8b6ef0"/><text x="60" y="532">3</text>
+      <circle cx="524" cy="416" r="8" fill="#8b6ef0"/><text x="524" y="420">4</text>
+      <circle cx="524" cy="472" r="8" fill="#8b6ef0"/><text x="524" y="476">5</text>
+      <circle cx="524" cy="528" r="8" fill="#8b6ef0"/><text x="524" y="532">6</text>
+    </g>
+    <g font-size="13.5" font-weight="600" fill="#e8e9ee">
+      <text x="78" y="421">Session chip</text>
+      <text x="78" y="477">Live state dot</text>
+      <text x="78" y="533">Scroll indicator</text>
+      <text x="542" y="421">Keycap hints</text>
+      <text x="542" y="477">Adaptive themes</text>
+      <text x="542" y="533">Search &amp; toasts</text>
+    </g>
+    <g font-size="12.5" fill="#9a9da8">
+      <text x="78" y="440">The room name, pinned flush-left as an accent pill.</text>
+      <text x="78" y="496">Green connected · amber reconnecting · red dropped · purple locked.</text>
+      <text x="78" y="552">Your place in scrollback — ⌥0 snaps back to live output.</text>
+      <text x="542" y="440">Keys bright, labels dim; ⌃G detach / ⌃Q kill never truncate away.</text>
+      <text x="542" y="496">Light/dark detected from your terminal (OSC 11), or --theme.</text>
+      <text x="542" y="552">⌥F search with live match counts; ✓ / ! toasts for feedback.</text>
+    </g>
+  </g>
+</svg>