diff --git a/CHANGELOG.md b/CHANGELOG.md
index a15e881..1810af6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,14 @@ Notable changes to **pixelpets**. All art and sound are original/procedural (no
 
 ## [Unreleased]
 
+### iPad terminal
+- **A terminal on the iPad, pointed at the machine that has one.** `npm run ipad:lan` prints a URL; Safari on the tablet opens a real shell - `vim`, `top`, tab completion, colours - on this computer. The thing it deliberately does *not* do is control other iPad apps: iPadOS sandboxes every app and exposes no API for it, so a tool that promised that would be lying. Shortcuts is the only sanctioned cross-app path on a tablet, and only for apps publishing App Intents.
+- **Switching apps no longer kills your build.** Safari suspends a backgrounded tab, so the naive version of this loses the shell the moment you check a message. The shell now outlives its connection, and the client counts the bytes it has rendered so a reconnect asks for exactly the gap - output made while you were away is replayed, output you already read is not repeated.
+- **A shell nobody is watching gets reaped.** The cleanup was armed only by a client *disconnecting*, so a session created and then never attached to - a page that loaded and got closed, a probe - held a live shell open forever.
+- **The keys a soft keyboard does not have.** No Esc, no Tab, no Ctrl, no arrows is most of what a shell is driven with; a key bar supplies them, with a sticky Ctrl. Tapping one uses `pointerdown` rather than click, because moving focus to a button on iPadOS dismisses the keyboard mid-command.
+- **Zero dependencies to start, better with two.** It runs on plain `node`: no install, output over SSE and input over POST rather than a hand-rolled WebSocket. `npm install` inside the tool adds a real pty and vendors xterm.js locally, and it is deliberately its own package - `node-pty` is native and xterm is browser-side, so neither belongs in the Electron bundle.
+- **Loopback unless you say otherwise.** `--lan` is the only thing that opens the port. Every request needs a token, ten bad ones lock the caller out for a minute, and the `Host` header is checked so a hostname resolving to this box cannot be used to probe it. The page strips the token out of the address bar on load and authenticates its own stylesheet and script with a `SameSite=Strict` cookie the API itself refuses.
+
 ### Sound
 - **The pet stopped making noise nobody asked for.** A cursor merely *resting* on the sprite counted as petting on every frame: the gate rejected a fast cursor, but a stationary one has `velEMA` 0, and main only forwards the cursor when it moves, so the last resting position stood forever. A pointer parked on the pet - easy to do by accident, and where the cursor often ends up after a pounce - purred without end and trilled every 1.5 seconds indefinitely. The *pose* is deliberate and stays, because a hand resting on the pet should squint its eyes; the voice now settles after eight seconds of a still hand.
 - **The butterfly stopped keeping time.** The paw-swat lasted 600ms and re-armed 100ms later, so it threw a whoosh roughly every 350ms for the whole 22-30 second visit, and visits recur every 14-24 seconds - better than half of all idle time spent audibly batting. The paw now rests between swats, jittered so it reads as a cat losing interest rather than a metronome.
diff --git a/README.md b/README.md
index 345fcd7..4bbb3a8 100644
--- a/README.md
+++ b/README.md
@@ -507,6 +507,30 @@ fullscreen), clicks pass through except on the cat, the typing reaction works
 after granting Accessibility, the cat rests on the Dock edge (not the menu
 bar), the tray menu works in the menu bar, and login launch works.
 
+## Drive it from an iPad
+
+```
+npm run ipad:lan
+```
+
+That prints a URL. Open it in Safari on the iPad and you have a real terminal - `vim`,
+`top`, tab completion, colours - on **this** machine. Share → Add to Home Screen gives
+it an icon and a full-screen window.
+
+The honest limitation first, because it is the reason the tool works this way: nothing
+running on an iPad can control other iPad apps. iPadOS sandboxes every app, Apple
+exposes no API for cross-app control, and no terminal on the App Store gets around it -
+Shortcuts is the only sanctioned path, and only for apps that publish App Intents. So
+this puts the shell on the computer, where a shell is worth having, and lets the iPad be
+the screen and the keyboard.
+
+It is built for a tablet: a key bar supplies the Esc, Tab, Ctrl and arrows the soft
+keyboard lacks, and because Safari suspends a backgrounded tab, the shell outlives the
+connection and replays exactly the output you missed when you come back.
+
+It is a shell running as you, over plain HTTP. Fine on your own Wi-Fi, not fine anywhere
+else - see [`tools/ipad-terminal/`](tools/ipad-terminal/) for the full notes.
+
 ## How it works
 
 - The cat is one role-coded sprite (outline, coat, markings, white, patch, eye,
@@ -565,6 +589,7 @@ pixelpets/
   tests/                   # node:test suites, no Electron and no GPU required
   scripts/                 # the vm harness, icon and demo generators, notify.js,
                            #  install-hook.js, the boot check
+  tools/ipad-terminal/     # browser terminal for this machine, driven from an iPad
   integrations/            # ready-made agent hook configs (5 agents)
   assets/                  # generated icons, showcase, hero + gallery clips
   site/                    # the browser demo deployed to Vercel
diff --git a/package.json b/package.json
index 5e05ec7..cd64e88 100644
--- a/package.json
+++ b/package.json
@@ -26,6 +26,8 @@
     "test": "node --test",
     "lint": "eslint . --cache --cache-location node_modules/.cache/eslint/",
     "hook": "node scripts/install-hook.js",
+    "ipad": "node tools/ipad-terminal/server.js",
+    "ipad:lan": "node tools/ipad-terminal/server.js --lan",
     "test:boot": "node scripts/bootcheck.js",
     "demo": "node scripts/make-demo-gif.js mp4",
     "demo:hero": "node scripts/make-demo-gif.js hero mp4",
diff --git a/tests/ipad-terminal.test.js b/tests/ipad-terminal.test.js
new file mode 100644
index 0000000..02d448e
--- /dev/null
+++ b/tests/ipad-terminal.test.js
@@ -0,0 +1,196 @@
+// The iPad terminal's job is to survive a tablet: Safari suspends the tab the moment
+// you switch apps, and the shell on the other end must not die with it, lose the output
+// it produced while you were away, or re-print what you already read. These drive the
+// real server over real HTTP against a real shell - no mocks, so a pass means bytes
+// actually made the round trip.
+const test = require('node:test');
+const assert = require('node:assert');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const srv = require('../tools/ipad-terminal/server.js');
+const SERVER = path.join(__dirname, '..', 'tools', 'ipad-terminal', 'server.js');
+const WIN = process.platform === 'win32';
+
+test('--lan is the one flag that opens the port to the network', () => {
+  assert.equal(srv.parseArgs([]).host, '127.0.0.1');
+  assert.equal(srv.parseArgs(['--lan']).host, '0.0.0.0');
+  // An explicit --host wins, so --lan can't silently widen a deliberate bind.
+  assert.equal(srv.parseArgs(['--lan', '--host=192.168.1.5']).host, '192.168.1.5');
+  assert.equal(srv.parseArgs(['--port=9000']).port, 9000);
+  assert.equal(srv.parseArgs(['--idle=30']).idle, 30);
+  assert.deepEqual(srv.parseArgs(['--allow-host=a.ts.net', '--allow-host=b']).allowHost, ['a.ts.net', 'b']);
+  assert.equal(srv.parseArgs(['--nope']).bad, '--nope');
+});
+
+test('the Host check lets the iPad in and keeps rebound DNS names out', () => {
+  const ok = (host) => srv.hostOk({ headers: { host } });
+  assert.ok(ok('192.168.1.5:7681'), 'the LAN IP the iPad actually dials');
+  assert.ok(ok('127.0.0.1:7681'));
+  assert.ok(ok('localhost:7681'));
+  assert.ok(ok('johnsons-mac.local:7681'), 'Bonjour name a Mac answers to');
+  assert.ok(ok('[::1]:7681'));
+  // A name that resolves to this box is exactly the DNS-rebinding shape.
+  assert.ok(!ok('evil.example.com:7681'));
+  assert.ok(!ok(''));
+});
+
+test('scrollback keeps its offsets straight as it evicts', () => {
+  const sess = { chunks: [], bytes: 0, base: 0, offset: 0, clients: new Set() };
+  const chunk = Buffer.alloc(64 * 1024, 'x');
+  for (let i = 0; i < 6; i += 1) srv.pushOut(sess, chunk);
+
+  const total = 6 * chunk.length;
+  assert.equal(sess.offset, total, 'offset counts every byte ever written');
+  assert.ok(sess.bytes <= srv.SCROLLBACK, 'the buffer stays capped');
+  assert.ok(sess.base > 0, 'the oldest output was dropped');
+  assert.equal(sess.base + sess.bytes, sess.offset, 'base and length still meet the head');
+
+  // Replaying from the head is a no-op: a client that is caught up gets nothing.
+  let sent = '';
+  srv.replay(sess, { write: (s) => { sent += s; } }, sess.offset);
+  assert.equal(sent, '', 'a caught-up reconnect replays nothing');
+
+  // Replaying from mid-buffer returns exactly the bytes past that point.
+  const from = sess.base + 1000;
+  let frame = '';
+  srv.replay(sess, { write: (s) => { frame += s; } }, from);
+  const payload = Buffer.from(frame.replace(/^event: out\ndata: /, '').trim(), 'base64');
+  assert.equal(payload.length, sess.offset - from, 'replay length matches the gap exactly');
+});
+
+// ---- end to end, against a real shell over real HTTP
+
+const TOKEN = 'test-token-for-the-suite';
+
+async function withServer(fn) {
+  const port = 7900 + Math.floor(Math.random() * 90);
+  const proc = spawn(process.execPath, [SERVER, `--port=${port}`, `--token=${TOKEN}`, '--idle=2'], { stdio: 'pipe' });
+  const base = `http://127.0.0.1:${port}`;
+  try {
+    await waitFor(async () => (await fetch(`${base}/?t=${TOKEN}`)).ok);
+    await fn(base);
+  } finally {
+    proc.kill();
+  }
+}
+
+async function waitFor(check, tries = 60) {
+  for (let i = 0; i < tries; i += 1) {
+    try { if (await check()) return; } catch { /* not up yet */ }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw new Error('server never came up');
+}
+
+const auth = { 'x-term-token': TOKEN };
+
+// Node's fetch silently drops a Host header, so the DNS-rebinding guard needs a raw
+// request to be exercised at all.
+function statusWithHost(base, host) {
+  const url = new URL(`${base}/?t=${TOKEN}`);
+  return new Promise((resolve, reject) => {
+    const req = require('node:http').request(
+      { host: url.hostname, port: url.port, path: url.pathname + url.search, headers: { host } },
+      (res) => { res.resume(); resolve(res.statusCode); });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+// The browser client, in miniature: read SSE frames, decode the base64 payloads, and
+// keep an exact count of rendered bytes so a reconnect can ask for precisely the gap.
+async function readStream(base, id, from, ms) {
+  const stop = new AbortController();
+  const timer = setTimeout(() => stop.abort(), ms);
+  const res = await fetch(`${base}/api/stream?id=${id}&from=${from}`, { headers: auth, signal: stop.signal });
+  assert.ok(res.ok, `stream returned ${res.status}`);
+  const reader = res.body.getReader();
+  const dec = new TextDecoder();
+  let buf = '';
+  let text = '';
+  let rendered = from;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      let cut;
+      while ((cut = buf.indexOf('\n\n')) !== -1) {
+        const frame = buf.slice(0, cut);
+        buf = buf.slice(cut + 2);
+        if (!frame.startsWith('event: out')) continue;
+        const bytes = Buffer.from(frame.slice(frame.indexOf('data: ') + 6), 'base64');
+        rendered += bytes.length;
+        text += bytes.toString('utf8');
+      }
+    }
+  } catch { /* aborted on purpose */ }
+  clearTimeout(timer);
+  return { text, rendered };
+}
+
+const type = (base, id, s) => fetch(`${base}/api/input?id=${id}`, { method: 'POST', headers: auth, body: s });
+
+test('an unauthenticated request never reaches a shell', { skip: WIN && 'posix shell' }, async () => {
+  await withServer(async (base) => {
+    assert.equal((await fetch(`${base}/`)).status, 401);
+    assert.equal((await fetch(`${base}/?t=wrong`)).status, 401);
+    // A token of the wrong length must be rejected, not throw inside the comparison.
+    assert.equal((await fetch(`${base}/?t=${'a'.repeat(200)}`)).status, 401);
+    assert.equal((await fetch(`${base}/api/session`, { method: 'POST' })).status, 401);
+    // fetch() refuses to set Host, so this one goes out over a raw request.
+    assert.equal(await statusWithHost(base, 'evil.example.com'), 421);
+    assert.equal(await statusWithHost(base, '127.0.0.1'), 200, 'the address the iPad dials still works');
+  });
+});
+
+test('a backgrounded iPad loses no output and re-reads none', { skip: WIN && 'posix shell' }, async () => {
+  await withServer(async (base) => {
+    const res = await fetch(`${base}/api/session`, {
+      method: 'POST', headers: { ...auth, 'content-type': 'application/json' },
+      body: JSON.stringify({ cols: 80, rows: 24 }),
+    });
+    const { id, mode } = await res.json();
+    assert.ok(id);
+
+    // Connection one: run something, then let the socket drop mid-session.
+    await type(base, id, 'echo BEFORE-DROP\n');
+    const first = await readStream(base, id, 0, 1200);
+    assert.match(first.text, /BEFORE-DROP/);
+
+    // Safari is suspended here. The shell keeps working and keeps producing output.
+    await type(base, id, 'echo WHILE-AWAY\n');
+    await new Promise((r) => setTimeout(r, 600));
+
+    // Connection two asks for exactly what it has not rendered.
+    await type(base, id, 'echo AFTER-RECONNECT\n');
+    const second = await readStream(base, id, first.rendered, 1200);
+    assert.match(second.text, /WHILE-AWAY/, 'output produced while away was replayed');
+    assert.match(second.text, /AFTER-RECONNECT/, 'the session is live again');
+    assert.ok(!second.text.includes('BEFORE-DROP'), 'already-rendered output was not repeated');
+    if (mode === 'pty') assert.equal((await fetch(`${base}/api/resize?id=${id}&cols=120&rows=40`, { method: 'POST', headers: auth })).status, 204);
+  });
+});
+
+test('a shell nobody is watching is reaped, not left running', { skip: WIN && 'posix shell' }, async () => {
+  await withServer(async (base) => {
+    const res = await fetch(`${base}/api/session`, {
+      method: 'POST', headers: { ...auth, 'content-type': 'application/json' },
+      body: JSON.stringify({ cols: 80, rows: 24 }),
+    });
+    const { id } = await res.json();
+    // --idle=2 above: still there right after the drop, gone once the window passes.
+    assert.equal((await type(base, id, '')).status, 204);
+    await new Promise((r) => setTimeout(r, 3500));
+    assert.equal((await type(base, id, 'echo late\n')).status, 404);
+  });
+});
+
+test('a bogus session id is a 404, not a crash', { skip: WIN && 'posix shell' }, async () => {
+  await withServer(async (base) => {
+    assert.equal((await fetch(`${base}/api/input?id=nope`, { method: 'POST', headers: auth, body: 'x' })).status, 404);
+    assert.equal((await fetch(`${base}/api/stream?id=nope`, { headers: auth })).status, 404);
+    assert.equal((await fetch(`${base}/nope`, { headers: auth })).status, 404);
+  });
+});
diff --git a/tools/ipad-terminal/README.md b/tools/ipad-terminal/README.md
new file mode 100644
index 0000000..424d65d
--- /dev/null
+++ b/tools/ipad-terminal/README.md
@@ -0,0 +1,112 @@
+# ipad-terminal
+
+A terminal for **this machine**, driven from an iPad.
+
+```
+npm run ipad:lan          # from the repo root
+```
+
+It prints a URL. Open it in Safari on the iPad. You get a real shell.
+
+---
+
+## What this is not
+
+It is worth being blunt about the limit, because it is the whole reason this tool is
+shaped the way it is.
+
+**Nothing running on an iPad can control other iPad apps.** iPadOS sandboxes every app:
+it cannot read another app's data, send it input, or drive its UI. Apple exposes no API
+for it, and no terminal - this one or any on the App Store - can get around that. The
+only sanctioned cross-app automation on an iPad is the **Shortcuts** app, and it only
+reaches apps that publish App Intents.
+
+So this does the thing that *is* possible: it puts a shell on the computer where a shell
+is worth having, and lets the iPad be the screen and the keyboard.
+
+## Running it
+
+| | |
+|---|---|
+| `npm run ipad` | loopback only - this machine, for a smoke test |
+| `npm run ipad:lan` | bound to `0.0.0.0`, so the iPad can reach it over your Wi-Fi |
+
+Options: `--port=N` (default 7681), `--token=STR`, `--shell=PATH`, `--idle=SECONDS`,
+`--allow-host=NAME`, `--help`.
+
+A fresh random token is generated each run and baked into the printed URL. The page
+strips it out of the address bar as soon as it loads, so it is not sitting in a
+screenshot or a synced tab, and hands the tab a `SameSite=Strict` cookie for its own
+stylesheet and script - the API itself never accepts that cookie.
+
+On the iPad, **Share → Add to Home Screen** gives it an icon and a full-screen window
+with no Safari chrome.
+
+## Two modes
+
+Run `npm install` in this directory to get the good one.
+
+**Full tty** (with `node-pty` installed) - a real pty. `vim`, `top`, tab completion,
+job control, Ctrl-C, colours, the works. The terminal's size is pushed to the shell, so
+`tput cols` is honest.
+
+**Line mode** (nothing installed) - the shell is spawned over pipes, so there is no tty.
+The browser does the line editing and ships whole lines. Commands run and output comes
+back; interactive full-screen programs do not work. This exists so the tool starts with
+plain `node` on a fresh clone.
+
+`npm install` here also vendors xterm.js locally. Without it the page pulls xterm from
+jsdelivr with a pinned integrity hash - fine on a normal network, but install it if you
+want the thing to work with no internet at all.
+
+## Surviving an iPad
+
+Safari suspends a backgrounded tab, which would ordinarily mean switching apps kills
+whatever you were running. Two things prevent that:
+
+- The shell outlives the connection by `--idle` seconds (default 120). Coming back
+  inside that window resumes the *same* shell, not a new one.
+- The client counts the bytes it has rendered and asks for exactly the gap on reconnect,
+  so output produced while you were away is replayed and output you already read is not.
+
+`tests/ipad-terminal.test.js` drives that path against a real shell over real HTTP.
+
+## Long-running jobs
+
+The shell outlives a dropped connection by `--idle` seconds and no longer. That is the
+right behaviour for a terminal, and the wrong behaviour for a six-hour training run: put
+the iPad down, and two minutes later the reaper kills the shell and the job goes with it.
+
+So start anything long inside `tmux` (or `screen`):
+
+```
+tmux new -s train        # then run the job
+# detach with ctrl-b d, close the iPad, come back later:
+tmux attach -t train
+```
+
+A tmux session is not a child of the shell, so it survives the reaper, a Wi-Fi drop, and
+restarting this server. Verified: a bare background job is killed with its shell once the
+idle window passes; the same job inside tmux is untouched.
+
+`--idle=86400` also works and is worse - it leaves an abandoned shell alive for a day.
+
+## The key bar
+
+The iPad soft keyboard has no Esc, no Tab, no Ctrl and no arrows, which is most of what
+a shell is driven with. The row along the bottom puts them back. `ctrl` is sticky: tap
+it, then the next letter becomes a control code.
+
+## Security
+
+This is a shell running as you. Take it as seriously as that sounds.
+
+- The token is required on every request; ten bad ones and the caller is locked out for
+  a minute.
+- The `Host` header is checked, so a hostname that resolves to this box cannot be used
+  to probe the port.
+- `--lan` is the only thing that opens it to the network, and it is never the default.
+- It is plain HTTP. That is fine on your own Wi-Fi and **not** fine anywhere else - to
+  reach it from outside, put it behind a tunnel that terminates TLS (Tailscale,
+  Cloudflare Tunnel, `ssh -L`) rather than forwarding a port on your router.
+- Stop it with Ctrl-C when you are done. It is not a service; do not leave it running.
diff --git a/tools/ipad-terminal/package-lock.json b/tools/ipad-terminal/package-lock.json
new file mode 100644
index 0000000..5506c2a
--- /dev/null
+++ b/tools/ipad-terminal/package-lock.json
@@ -0,0 +1,53 @@
+{
+  "name": "pixelpets-ipad-terminal",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "pixelpets-ipad-terminal",
+      "version": "1.0.0",
+      "license": "MIT",
+      "optionalDependencies": {
+        "@xterm/addon-fit": "^0.10.0",
+        "@xterm/xterm": "^5.5.0",
+        "node-pty": "^1.0.0"
+      }
+    },
+    "node_modules/@xterm/addon-fit": {
+      "version": "0.10.0",
+      "resolved": "https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.10.0.tgz",
+      "integrity": "sha512-UFYkDm4HUahf2lnEyHvio51TNGiLK66mqP2JoATy7hRZeXaGMRDr00JiSF7m63vR5WKATF605yEggJKsw0JpMQ==",
+      "license": "MIT",
+      "optional": true,
+      "peerDependencies": {
+        "@xterm/xterm": "^5.0.0"
+      }
+    },
+    "node_modules/@xterm/xterm": {
+      "version": "5.5.0",
+      "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-5.5.0.tgz",
+      "integrity": "sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/node-addon-api": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+      "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/node-pty": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.1.0.tgz",
+      "integrity": "sha512-20JqtutY6JPXTUnL0ij1uad7Qe1baT46lyolh2sSENDd4sTzKZ4nmAFkeAARDKwmlLjPx6XKRlwRUxwjOy+lUg==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "node-addon-api": "^7.1.0"
+      }
+    }
+  }
+}
diff --git a/tools/ipad-terminal/package.json b/tools/ipad-terminal/package.json
new file mode 100644
index 0000000..cb6d487
--- /dev/null
+++ b/tools/ipad-terminal/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "pixelpets-ipad-terminal",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Browser terminal for this machine, driven from an iPad",
+  "license": "MIT",
+  "scripts": {
+    "start": "node server.js",
+    "lan": "node server.js --lan"
+  },
+  "//": "Deliberately a package of its own, not part of the app. node-pty is a native module and xterm is browser-side - neither belongs in the Electron bundle, and hoisting them into the root manifest would ship both to every installer. Everything here is optional: with nothing installed the server still runs in line mode and loads xterm from a CDN.",
+  "optionalDependencies": {
+    "node-pty": "^1.0.0",
+    "@xterm/xterm": "^5.5.0",
+    "@xterm/addon-fit": "^0.10.0"
+  }
+}
diff --git a/tools/ipad-terminal/public/index.html b/tools/ipad-terminal/public/index.html
new file mode 100644
index 0000000..b284d07
--- /dev/null
+++ b/tools/ipad-terminal/public/index.html
@@ -0,0 +1,409 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<!-- viewport-fit=cover so the key bar can sit in the home-indicator inset rather than
+     above it; no user scaling because pinch-zoom on a terminal only ever loses your place. -->
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover">
+<meta name="apple-mobile-web-app-capable" content="yes">
+<meta name="mobile-web-app-capable" content="yes">
+<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+<meta name="apple-mobile-web-app-title" content="pixelpets">
+<meta name="color-scheme" content="dark">
+<link rel="icon" href="/icon.png">
+<link rel="apple-touch-icon" href="/icon.png">
+<title>pixelpets terminal</title>
+<style>
+  :root {
+    --bg: #14161c; --chrome: #1c1f28; --line: #2b2f3b;
+    --ink: #d7dbe6; --dim: #7c869c; --accent: #ffb454; --bad: #ff6b6b; --ok: #7ee787;
+    --key: #262b36; --keydown: #3a4150;
+  }
+  * { box-sizing: border-box; -webkit-tap-highlight-color: transparent; }
+  html, body {
+    margin: 0; height: 100%; overflow: hidden; background: var(--bg); color: var(--ink);
+    font: 13px/1.4 ui-sans-serif, -apple-system, system-ui, sans-serif;
+    -webkit-text-size-adjust: 100%; overscroll-behavior: none;
+  }
+  #app { display: flex; flex-direction: column; height: 100%; }
+
+  header {
+    flex: none; display: flex; align-items: center; gap: 10px;
+    padding: max(6px, env(safe-area-inset-top)) 12px 6px;
+    background: var(--chrome); border-bottom: 1px solid var(--line);
+  }
+  #title { font-weight: 600; letter-spacing: .02em; }
+  #title span { color: var(--dim); font-weight: 400; }
+  #status { margin-left: auto; display: flex; align-items: center; gap: 6px; color: var(--dim); }
+  #dot { width: 8px; height: 8px; border-radius: 50%; background: var(--dim); }
+  #dot.live { background: var(--ok); }
+  #dot.lost { background: var(--bad); }
+  header button {
+    font: inherit; color: var(--ink); background: var(--key); border: 1px solid var(--line);
+    border-radius: 6px; padding: 3px 9px; min-width: 30px;
+  }
+
+  #term { flex: 1; min-height: 0; padding: 4px 2px 0 6px; }
+  .xterm .xterm-viewport { overscroll-behavior: contain; }
+
+  /* The soft keyboard has no Esc, no Tab, no Ctrl and no arrows, which is most of
+     what a shell is driven with. This row puts them back within thumb reach. */
+  #keys {
+    flex: none; display: flex; gap: 5px; padding: 6px 8px calc(6px + env(safe-area-inset-bottom));
+    background: var(--chrome); border-top: 1px solid var(--line);
+    overflow-x: auto; scrollbar-width: none;
+  }
+  #keys::-webkit-scrollbar { display: none; }
+  #keys button {
+    flex: none; min-width: 42px; height: 36px; padding: 0 10px;
+    font: 13px/1 ui-monospace, SFMono-Regular, Menlo, monospace;
+    color: var(--ink); background: var(--key); border: 1px solid var(--line);
+    border-radius: 7px; touch-action: manipulation;
+  }
+  #keys button:active { background: var(--keydown); }
+  #keys button.armed { background: var(--accent); border-color: var(--accent); color: #14161c; }
+
+  #splash {
+    position: fixed; inset: 0; display: flex; align-items: center; justify-content: center;
+    flex-direction: column; gap: 12px; background: var(--bg); text-align: center; padding: 24px;
+  }
+  #splash.gone { display: none; }
+  #splash p { color: var(--dim); max-width: 34ch; margin: 0; }
+  #splash button {
+    font: inherit; color: #14161c; background: var(--accent); border: 0;
+    border-radius: 8px; padding: 10px 18px; font-weight: 600;
+  }
+</style>
+</head>
+<body>
+<div id="app">
+  <header>
+    <div id="title">pixelpets <span id="where"></span></div>
+    <div id="status"><span id="dot"></span><span id="state">starting</span></div>
+    <button id="smaller" aria-label="smaller text">A-</button>
+    <button id="bigger" aria-label="bigger text">A+</button>
+  </header>
+  <div id="term"></div>
+  <div id="keys"></div>
+</div>
+<div id="splash"><p id="splash-msg">loading terminal…</p><button id="splash-go" hidden>retry</button></div>
+
+<script>
+// Filled in by the server: "local" once you have run `npm install` beside the tool,
+// "cdn" on a fresh checkout so the first run needs nothing installed.
+const VENDOR_MODE = '__VENDOR__';
+const CDN = 'https://cdn.jsdelivr.net/npm/';
+const ASSETS = {
+  css: { local: '/vendor/xterm.css', cdn: CDN + '@xterm/xterm@5.5.0/css/xterm.css',
+    sri: 'sha384-8Xk9wy/gzEDUKrXtrmCFa2bBuK3BpjpDuL/p0SeKQX19Khl/M+lHOgD/CyYf7efP' },
+  core: { local: '/vendor/xterm.js', cdn: CDN + '@xterm/xterm@5.5.0/lib/xterm.js',
+    sri: 'sha384-M169f14mRZOXm3hD/v2Ti0ThIT/RnAQagXA9nlE15yHAtrW19gdePJh/HaTzUOe/' },
+  fit: { local: '/vendor/addon-fit.js', cdn: CDN + '@xterm/addon-fit@0.10.0/lib/addon-fit.js',
+    sri: 'sha384-iF+jqbuti4XlB64clWgFWYEscb+UnSRv3VgVikGYZu+otNFnSHr7y7NcKfBnGizn' },
+};
+
+// The token arrives in the URL because that is the only thing you can reasonably type
+// (or scan) on a tablet. Keep it in memory and strip it from the address bar, so it is
+// not sitting in a screenshot, a shared tab, or Safari's history sync.
+const TOKEN = new URLSearchParams(location.search).get('t') || '';
+history.replaceState(null, '', location.pathname);
+
+const $ = (id) => document.getElementById(id);
+const splash = $('splash'), splashMsg = $('splash-msg'), splashGo = $('splash-go');
+
+function fail(msg, retry) {
+  splash.classList.remove('gone');
+  splashMsg.textContent = msg;
+  splashGo.hidden = !retry;
+  splashGo.onclick = retry || null;
+}
+
+function loadAsset(kind, key) {
+  return new Promise((resolve, reject) => {
+    const a = ASSETS[key];
+    const local = VENDOR_MODE === 'local';
+    const el = document.createElement(kind === 'css' ? 'link' : 'script');
+    if (kind === 'css') { el.rel = 'stylesheet'; el.href = local ? a.local : a.cdn; }
+    else { el.src = local ? a.local : a.cdn; }
+    if (!local) { el.integrity = a.sri; el.crossOrigin = 'anonymous'; }
+    el.onload = resolve;
+    el.onerror = () => reject(new Error(key));
+    document.head.appendChild(el);
+  });
+}
+
+async function boot() {
+  if (!TOKEN) return fail('No token in the URL. Re-open the exact link the server printed.');
+  try {
+    await loadAsset('css', 'css');
+    await loadAsset('js', 'core');
+    await loadAsset('js', 'fit');
+  } catch {
+    return fail(VENDOR_MODE === 'local'
+      ? 'Could not load the terminal files from this machine.'
+      : 'Could not reach the CDN for xterm.js. Run `npm install` in tools/ipad-terminal on the computer and reload - then it is served locally and needs no internet.',
+      () => location.reload());
+  }
+  start();
+}
+
+function start() {
+  const term = new Terminal({
+    cursorBlink: true,
+    fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+    fontSize: Number(localStorage.getItem('pp.fontSize')) || 14,
+    scrollback: 5000,
+    macOptionIsMeta: true,
+    theme: {
+      background: '#14161c', foreground: '#d7dbe6', cursor: '#ffb454',
+      selectionBackground: '#3a4150', black: '#14161c', brightBlack: '#7c869c',
+    },
+  });
+  const fit = new FitAddon.FitAddon();
+  term.loadAddon(fit);
+  term.open($('term'));
+
+  const state = { id: null, mode: 'pty', rendered: 0, abort: null, backoff: 500, closed: false };
+  const enc = new TextEncoder();
+
+  const setState = (text, cls) => { $('state').textContent = text; $('dot').className = cls || ''; };
+
+  const api = (path, init) => fetch(path, {
+    ...init,
+    headers: { 'x-term-token': TOKEN, ...(init && init.headers) },
+  });
+
+  // ---- sizing. The soft keyboard does not resize the window on iPadOS, it just
+  // covers it, so trust visualViewport for the real usable height instead.
+  function relayout() {
+    const vv = window.visualViewport;
+    if (vv) $('app').style.height = vv.height + 'px';
+    try { fit.fit(); } catch { /* not measurable yet */ }
+    if (state.id && state.mode === 'pty') {
+      api(`/api/resize?id=${state.id}&cols=${term.cols}&rows=${term.rows}`, { method: 'POST' }).catch(() => {});
+    }
+  }
+  const relayoutSoon = () => setTimeout(relayout, 60);
+  window.addEventListener('resize', relayoutSoon);
+  window.addEventListener('orientationchange', relayoutSoon);
+  if (window.visualViewport) {
+    visualViewport.addEventListener('resize', relayoutSoon);
+    visualViewport.addEventListener('scroll', relayoutSoon);
+  }
+
+  // Same pointerdown trick as the key bar: a plain click would move focus to the
+  // button, and on iPadOS losing terminal focus drops the soft keyboard entirely.
+  for (const [id, step] of [['bigger', 1], ['smaller', -1]]) {
+    $(id).addEventListener('pointerdown', (e) => {
+      e.preventDefault();
+      setFont(term.options.fontSize + step);
+      term.focus();
+    });
+  }
+  function setFont(n) {
+    const size = Math.max(9, Math.min(24, n));
+    term.options.fontSize = size;
+    localStorage.setItem('pp.fontSize', String(size));
+    relayout();
+  }
+
+  // ---- upstream. One POST per keystroke would be a round trip per character; a
+  // 12ms coalescing window turns a burst of typing (or a paste) into a single write
+  // without being long enough to feel like lag.
+  let pending = [];
+  let flushTimer = null;
+  function send(data) {
+    pending.push(typeof data === 'string' ? enc.encode(data) : data);
+    if (flushTimer) return;
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      const parts = pending; pending = [];
+      let size = 0;
+      for (const p of parts) size += p.length;
+      const body = new Uint8Array(size);
+      let at = 0;
+      for (const p of parts) { body.set(p, at); at += p.length; }
+      api(`/api/input?id=${state.id}`, {
+        method: 'POST', body, headers: { 'content-type': 'application/octet-stream' },
+      }).catch(() => {});
+    }, 12);
+  }
+
+  // ---- line mode. Without node-pty there is no tty, so nothing echoes what you type
+  // and nothing handles backspace. The browser plays terminal instead: edit here, ship
+  // whole lines to the shell.
+  const line = { buf: '', prompt: '\x1b[38;5;215m$\x1b[0m ' };
+  function lineKey(data) {
+    for (const ch of data) {
+      if (ch === '\r' || ch === '\n') {
+        term.write('\r\n');
+        send(line.buf + '\n');
+        line.buf = '';
+      } else if (ch === '\x7f' || ch === '\b') {
+        if (line.buf) { line.buf = line.buf.slice(0, -1); term.write('\b \b'); }
+      } else if (ch === '\x03') {
+        term.write('^C\r\n');
+        line.buf = '';
+        api(`/api/signal?id=${state.id}`, { method: 'POST' }).catch(() => {});
+        term.write(line.prompt);
+      } else if (ch >= ' ') {
+        line.buf += ch;
+        term.write(ch);
+      }
+    }
+  }
+
+  // ---- sticky Ctrl for the key bar: arm it, then the next letter from the soft
+  // keyboard becomes a control code, the way a real Ctrl chord would.
+  let ctrlArmed = null;
+  term.onData((data) => {
+    if (ctrlArmed) {
+      const btn = ctrlArmed; ctrlArmed = null; btn.classList.remove('armed');
+      if (data.length === 1) {
+        const c = data.toUpperCase().charCodeAt(0);
+        if (c >= 64 && c < 128) data = String.fromCharCode(c & 31);
+      }
+    }
+    if (state.mode === 'line') lineKey(data); else send(data);
+  });
+  term.onBinary((data) => send(Uint8Array.from(data, (c) => c.charCodeAt(0) & 255)));
+
+  const KEYS = [
+    ['esc', '\x1b'], ['tab', '\t'], ['ctrl', 'CTRL'],
+    ['↑', '\x1b[A'], ['↓', '\x1b[B'], ['←', '\x1b[D'], ['→', '\x1b[C'],
+    ['^C', '\x03'], ['^D', '\x04'], ['^Z', '\x1a'], ['^L', '\x0c'],
+    ['|', '|'], ['~', '~'], ['/', '/'], ['-', '-'], ['`', '`'], ['$', '$'],
+  ];
+  for (const [label, code] of KEYS) {
+    const b = document.createElement('button');
+    b.textContent = label;
+    b.type = 'button';
+    // pointerdown, not click: it fires before focus moves, so the soft keyboard
+    // never dismisses itself when you reach for Esc mid-command.
+    b.addEventListener('pointerdown', (e) => {
+      e.preventDefault();
+      if (code === 'CTRL') {
+        if (ctrlArmed === b) { ctrlArmed = null; b.classList.remove('armed'); }
+        else { if (ctrlArmed) ctrlArmed.classList.remove('armed'); ctrlArmed = b; b.classList.add('armed'); }
+        return;
+      }
+      if (state.mode === 'line') lineKey(code); else send(code);
+      term.focus();
+    });
+    $('keys').appendChild(b);
+  }
+
+  // ---- downstream. fetch + a manual SSE parse rather than EventSource, because
+  // EventSource hides the status code (so a reaped session is indistinguishable from
+  // a flaky Wi-Fi drop) and would replay from a stale offset on its own reconnects.
+  function handleFrame(frame) {
+    let event = 'message', data = '';
+    for (const raw of frame.split('\n')) {
+      if (raw.startsWith(':')) continue;
+      if (raw.startsWith('event:')) event = raw.slice(6).trim();
+      else if (raw.startsWith('data:')) data += raw.slice(5).trim();
+    }
+    if (event === 'out') {
+      const bin = atob(data);
+      const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0));
+      state.rendered += bytes.length;
+      term.write(bytes);
+    } else if (event === 'hello') {
+      const info = JSON.parse(data);
+      state.mode = info.mode;
+      state.backoff = 500;
+      setState(info.mode === 'pty' ? 'connected' : 'line mode', 'live');
+      splash.classList.add('gone');
+      relayout();
+      term.focus();
+    } else if (event === 'exit') {
+      const { code } = JSON.parse(data);
+      state.closed = true;
+      setState('shell exited', 'lost');
+      term.write(`\r\n\x1b[38;5;215m[shell exited (${code})]\x1b[0m\r\n`);
+      offerRestart();
+    }
+  }
+
+  async function stream() {
+    state.abort = new AbortController();
+    let res;
+    try {
+      res = await api(`/api/stream?id=${state.id}&from=${state.rendered}`, { signal: state.abort.signal });
+    } catch {
+      return retry();
+    }
+    if (res.status === 404) { state.id = null; return newSession(); }
+    if (!res.ok) return fail(`server said ${res.status}. The token may have changed - re-open the printed link.`, () => location.reload());
+
+    const reader = res.body.getReader();
+    const dec = new TextDecoder();
+    let buf = '';
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += dec.decode(value, { stream: true });
+        let cut;
+        while ((cut = buf.indexOf('\n\n')) !== -1) {
+          handleFrame(buf.slice(0, cut));
+          buf = buf.slice(cut + 2);
+        }
+      }
+    } catch { /* dropped mid-stream */ }
+    retry();
+  }
+
+  function retry() {
+    if (state.closed) return;
+    setState('reconnecting', 'lost');
+    // Capped exponential backoff: a Wi-Fi handoff recovers on the first try, a
+    // laptop that went to sleep should not get hammered until it wakes.
+    const wait = state.backoff;
+    state.backoff = Math.min(state.backoff * 2, 8000);
+    setTimeout(stream, wait);
+  }
+
+  function offerRestart() {
+    fail('The shell exited.', async () => { state.closed = false; state.rendered = 0; term.reset(); await newSession(); });
+  }
+
+  async function newSession() {
+    setState('starting', '');
+    let info;
+    try {
+      const res = await api('/api/session', {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ cols: term.cols, rows: term.rows }),
+      });
+      if (!res.ok) throw new Error(String(res.status));
+      info = await res.json();
+    } catch (e) {
+      return fail(`Could not start a shell (${e.message}). Is the server still running?`, () => newSession());
+    }
+    state.id = info.id;
+    state.mode = info.mode;
+    state.rendered = 0;
+    state.closed = false;
+    $('where').textContent = info.host || '';
+    if (info.mode === 'line') term.write(`\x1b[38;5;215mline mode\x1b[0m - no tty, so no vim/top and no tab completion.\r\ninstall node-pty next to the tool for the real thing.\r\n\r\n${line.prompt}`);
+    stream();
+  }
+
+  // iPadOS freezes a backgrounded tab's fetch; coming back needs a nudge rather
+  // than a wait for the dead socket to time out on its own.
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState !== 'visible' || state.closed || !state.id) return;
+    state.backoff = 500;
+    if (state.abort) state.abort.abort();
+    relayoutSoon();
+  });
+
+  relayout();
+  newSession();
+}
+
+boot();
+</script>
+</body>
+</html>
diff --git a/tools/ipad-terminal/server.js b/tools/ipad-terminal/server.js
new file mode 100644
index 0000000..4c5e76c
--- /dev/null
+++ b/tools/ipad-terminal/server.js
@@ -0,0 +1,444 @@
+// A browser terminal you can drive from an iPad.
+//
+// iPadOS sandboxes every app, so nothing running *on* the tablet can reach into other
+// iPad apps. What the iPad can do is reach this machine over the network. So the shell
+// lives here - on the computer pixelpets actually runs on - and Safari is only the
+// screen and the keyboard. Point the iPad at the URL this prints and you get a real
+// terminal, on the machine where a terminal is worth having.
+//
+//   node tools/ipad-terminal/server.js         # loopback only (this machine)
+//   node tools/ipad-terminal/server.js --lan   # reachable from the iPad on your Wi-Fi
+//
+// Downstream is Server-Sent Events, upstream is POST, rather than one WebSocket: node
+// ships no WebSocket *server*, and hand-rolling RFC 6455 framing is a lot of surface
+// area for something whose whole job is shuttling a few hundred bytes per keypress
+// across a LAN. This way the tool stays dependency-free and starts with plain `node`.
+const http = require('node:http');
+const crypto = require('node:crypto');
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const PUBLIC = path.join(__dirname, 'public');
+// Enough scrollback that backgrounding Safari and coming back re-paints a full screen
+// of context instead of dropping you into a blank buffer mid-command.
+const SCROLLBACK = 256 * 1024;
+const MAX_SESSIONS = 4;
+const MAX_BODY = 64 * 1024;
+const HEARTBEAT_MS = 15000;
+
+// ---------------------------------------------------------------- options
+
+function parseArgs(argv) {
+  const opt = {
+    host: '127.0.0.1', port: 7681, lan: false, token: '',
+    shell: '', idle: 120, allowHost: [],
+  };
+  for (const arg of argv) {
+    const eq = arg.indexOf('=');
+    const key = eq === -1 ? arg : arg.slice(0, eq);
+    const val = eq === -1 ? '' : arg.slice(eq + 1);
+    switch (key) {
+      case '--lan': opt.lan = true; break;
+      case '--host': opt.host = val; break;
+      case '--port': opt.port = Number(val) || opt.port; break;
+      case '--token': opt.token = val; break;
+      case '--shell': opt.shell = val; break;
+      // Seconds a disconnected session's shell survives. iPad Safari suspends
+      // background tabs aggressively, so "you tabbed away" must not mean "your
+      // build got killed" - reconnecting inside this window resumes the same shell.
+      case '--idle': opt.idle = Number(val) || opt.idle; break;
+      // Only needed when you reach the box by a DNS name (a tunnel, an mDNS alias).
+      case '--allow-host': if (val) opt.allowHost.push(val.toLowerCase()); break;
+      case '--help': case '-h': opt.help = true; break;
+      default: if (arg.startsWith('-')) { opt.bad = arg; }
+    }
+  }
+  if (opt.lan && opt.host === '127.0.0.1') opt.host = '0.0.0.0';
+  return opt;
+}
+
+const opt = parseArgs(process.argv.slice(2));
+
+const TOKEN = opt.token || crypto.randomBytes(16).toString('hex');
+const IS_WIN = process.platform === 'win32';
+const SHELL = opt.shell || process.env.SHELL || (IS_WIN ? 'powershell.exe' : '/bin/bash');
+
+// node-pty is optional and native. With it you get a true terminal - vim, top, tab
+// completion, job control. Without it we fall back to piping a shell, which can still
+// run commands but has no tty, so the browser does the line editing instead.
+let pty = null;
+try { pty = require('node-pty'); } catch { /* line mode */ }
+const MODE = pty ? 'pty' : 'line';
+
+// ---------------------------------------------------------------- auth
+
+const TOKEN_BUF = Buffer.from(TOKEN);
+const failures = new Map(); // ip -> { count, until }
+
+const COOKIE = 'ppterm';
+
+function cookieToken(req) {
+  const jar = String(req.headers.cookie || '');
+  const hit = jar.split(';').map((c) => c.trim()).find((c) => c.startsWith(`${COOKIE}=`));
+  return hit ? decodeURIComponent(hit.slice(COOKIE.length + 1)) : '';
+}
+
+// `allowCookie` is deliberately not the default. The page and its stylesheet/script
+// tags have no way to send a header - a <script src> is a plain browser fetch - so
+// those requests authenticate by cookie. The API does not: a cookie is something a
+// hostile page could try to ride, and SameSite=Strict already blocks that, but the
+// shell endpoints should not depend on getting SameSite right in every browser.
+function tokenOk(req, url, allowCookie) {
+  const given = req.headers['x-term-token'] || url.searchParams.get('t')
+    || (allowCookie ? cookieToken(req) : '') || '';
+  const buf = Buffer.from(String(given));
+  // timingSafeEqual throws on a length mismatch, which would itself leak length,
+  // so compare a fixed-size digest of each instead of the raw bytes.
+  return crypto.timingSafeEqual(crypto.createHash('sha256').update(buf).digest(),
+    crypto.createHash('sha256').update(TOKEN_BUF).digest());
+}
+
+function throttled(ip) {
+  const rec = failures.get(ip);
+  return !!(rec && rec.until > Date.now());
+}
+
+function noteFailure(ip) {
+  const rec = failures.get(ip) || { count: 0, until: 0 };
+  rec.count += 1;
+  // A handful of fat-fingered URLs is normal; a hundred is someone walking the space.
+  if (rec.count >= 10) { rec.until = Date.now() + 60000; rec.count = 0; }
+  failures.set(ip, rec);
+}
+
+// A browser on some other site can't read our responses, but it *can* make the
+// request - and if it reaches us via a hostname that resolves to this box, the
+// request carries no token and fails anyway. The Host check exists so a rebound
+// DNS name can't be used to probe the port at all. IP literals are always fine.
+function hostOk(req) {
+  const raw = String(req.headers.host || '');
+  const name = raw.replace(/:\d+$/, '').replace(/^\[|\]$/g, '').toLowerCase();
+  if (!name) return false;
+  if (name === 'localhost' || name.endsWith('.local')) return true;
+  if (opt.allowHost.includes(name)) return true;
+  return /^[\d.]+$/.test(name) || name.includes(':');
+}
+
+// ---------------------------------------------------------------- sessions
+
+const sessions = new Map();
+
+function newSession(cols, rows) {
+  if (sessions.size >= MAX_SESSIONS) return null;
+  const id = crypto.randomBytes(9).toString('hex');
+  const sess = {
+    id, chunks: [], bytes: 0, base: 0, offset: 0,
+    clients: new Set(), reaper: null, exited: null, proc: null,
+  };
+
+  if (pty) {
+    sess.proc = pty.spawn(SHELL, [], {
+      name: 'xterm-256color',
+      cols: cols || 80,
+      rows: rows || 24,
+      cwd: process.env.HOME || process.cwd(),
+      env: { ...process.env, TERM: 'xterm-256color' },
+    });
+    sess.proc.onData((d) => pushOut(sess, Buffer.from(d, 'utf8')));
+    sess.proc.onExit(({ exitCode }) => endSession(sess, exitCode));
+  } else {
+    sess.proc = spawn(SHELL, IS_WIN ? ['-NoLogo', '-NoProfile', '-Command', '-'] : [], {
+      cwd: process.env.HOME || process.cwd(),
+      env: { ...process.env, TERM: 'dumb' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    sess.proc.stdout.on('data', (d) => pushOut(sess, d));
+    // stderr is folded into the same stream: a terminal shows one interleaved
+    // transcript, and splitting them here would only reorder the output.
+    sess.proc.stderr.on('data', (d) => pushOut(sess, d));
+    sess.proc.on('exit', (code) => endSession(sess, code == null ? -1 : code));
+    sess.proc.on('error', (err) => {
+      pushOut(sess, Buffer.from(`\r\ncould not start ${SHELL}: ${err.message}\r\n`));
+      endSession(sess, -1);
+    });
+  }
+
+  sessions.set(id, sess);
+  // Arm the reaper before anyone attaches. A session that is created and then never
+  // streamed to - a page that loaded and got closed, a probe, a client that died
+  // during the handshake - would otherwise hold a live shell open forever, since
+  // until now only a *disconnecting* client scheduled the cleanup.
+  sess.reaper = setTimeout(() => killSession(sess), opt.idle * 1000);
+  return sess;
+}
+
+function pushOut(sess, buf) {
+  if (!buf || !buf.length) return;
+  sess.chunks.push(buf);
+  sess.bytes += buf.length;
+  sess.offset += buf.length;
+  while (sess.bytes > SCROLLBACK && sess.chunks.length > 1) {
+    const dropped = sess.chunks.shift();
+    sess.bytes -= dropped.length;
+    sess.base += dropped.length;
+  }
+  const frame = `event: out\ndata: ${buf.toString('base64')}\n\n`;
+  for (const res of sess.clients) res.write(frame);
+}
+
+function endSession(sess, code) {
+  if (sess.exited !== null) return;
+  sess.exited = code;
+  const frame = `event: exit\ndata: ${JSON.stringify({ code })}\n\n`;
+  for (const res of sess.clients) { res.write(frame); res.end(); }
+  sess.clients.clear();
+  if (sess.reaper) clearTimeout(sess.reaper);
+  sessions.delete(sess.id);
+}
+
+function killSession(sess) {
+  if (sess.exited !== null) return;
+  try { sess.proc.kill(); } catch { /* already gone */ }
+  endSession(sess, -1);
+}
+
+// Replay is what makes a dropped connection a non-event. The client tells us the
+// byte offset it last rendered; we send whatever of the ring buffer sits past it.
+function replay(sess, res, from) {
+  let skip = Math.max(0, from - sess.base);
+  const out = [];
+  for (const chunk of sess.chunks) {
+    if (skip >= chunk.length) { skip -= chunk.length; continue; }
+    out.push(skip > 0 ? chunk.subarray(skip) : chunk);
+    skip = 0;
+  }
+  if (out.length) res.write(`event: out\ndata: ${Buffer.concat(out).toString('base64')}\n\n`);
+}
+
+// ---------------------------------------------------------------- http
+
+const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8' };
+
+function send(res, code, type, body, extra) {
+  res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store', ...extra });
+  res.end(body);
+}
+
+function readBody(req, cb) {
+  const parts = [];
+  let size = 0;
+  req.on('data', (d) => {
+    size += d.length;
+    if (size > MAX_BODY) { req.destroy(); return; }
+    parts.push(d);
+  });
+  req.on('end', () => cb(Buffer.concat(parts)));
+  req.on('error', () => cb(Buffer.alloc(0)));
+}
+
+// xterm.js is served from node_modules when it's installed next to this tool, and
+// from jsdelivr (integrity-pinned) otherwise, so the very first run needs no install
+// and a later `npm install` here makes the whole thing work with no internet at all.
+const VENDOR = {
+  '/vendor/xterm.css': ['@xterm/xterm', 'css/xterm.css'],
+  '/vendor/xterm.js': ['@xterm/xterm', 'lib/xterm.js'],
+  '/vendor/addon-fit.js': ['@xterm/addon-fit', 'lib/addon-fit.js'],
+};
+
+function vendorPath(key) {
+  const [pkg, rel] = VENDOR[key];
+  try { return require.resolve(`${pkg}/${rel}`, { paths: [__dirname] }); } catch { return null; }
+}
+
+const server = http.createServer((req, res) => {
+  const ip = req.socket.remoteAddress || '?';
+  const url = new URL(req.url, 'http://x');
+  const route = url.pathname;
+
+  if (!hostOk(req)) return send(res, 421, 'text/plain', 'bad Host header\n');
+  if (throttled(ip)) return send(res, 429, 'text/plain', 'too many bad tokens; wait a minute\n');
+  const isPage = route === '/' || route === '/index.html' || route.startsWith('/vendor/')
+    || route === '/icon.png' || route === '/favicon.ico';
+  if (!tokenOk(req, url, isPage)) {
+    noteFailure(ip);
+    return send(res, 401, 'text/plain', 'bad or missing token\n');
+  }
+
+  if (route === '/' || route === '/index.html') {
+    let html;
+    try { html = fs.readFileSync(path.join(PUBLIC, 'index.html')); } catch { return send(res, 500, 'text/plain', 'index.html missing\n'); }
+    const local = Object.keys(VENDOR).every((k) => vendorPath(k));
+    return send(res, 200, MIME['.html'], String(html).replace('__VENDOR__', local ? 'local' : 'cdn'), {
+      // Hands the tab a credential its <script>/<link> tags can actually present, so
+      // the token can leave the address bar without the page failing to load itself.
+      'set-cookie': `${COOKIE}=${encodeURIComponent(TOKEN)}; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400`,
+      // No frames, no referrer leaking the token to whatever we might link to.
+      'x-frame-options': 'DENY',
+      'referrer-policy': 'no-referrer',
+    });
+  }
+
+  // Add to Home Screen wants a real image, and Safari probes /favicon.ico on its own -
+  // without this both come back 401 and the home-screen tile is a page screenshot.
+  if (route === '/icon.png' || route === '/favicon.ico') {
+    const icon = path.join(__dirname, '..', '..', 'assets', 'icon-512.png');
+    if (!fs.existsSync(icon)) return send(res, 404, 'text/plain', 'no icon\n');
+    return send(res, 200, 'image/png', fs.readFileSync(icon), { 'cache-control': 'max-age=86400' });
+  }
+
+  if (VENDOR[route]) {
+    const file = vendorPath(route);
+    if (!file) return send(res, 404, 'text/plain', 'not installed locally\n');
+    return send(res, 200, MIME[path.extname(route)] || 'application/octet-stream', fs.readFileSync(file));
+  }
+
+  if (route === '/api/session' && req.method === 'POST') {
+    return readBody(req, (body) => {
+      let want = {};
+      try { want = JSON.parse(body.toString() || '{}'); } catch { /* defaults */ }
+      const sess = newSession(Number(want.cols), Number(want.rows));
+      if (!sess) return send(res, 429, 'application/json', JSON.stringify({ error: 'too many sessions' }));
+      send(res, 200, 'application/json', JSON.stringify({ id: sess.id, mode: MODE, shell: SHELL, host: os.hostname() }));
+    });
+  }
+
+  const sess = sessions.get(url.searchParams.get('id') || '');
+
+  if (route === '/api/stream') {
+    if (!sess) return send(res, 404, 'text/plain', 'no such session\n');
+    res.socket.setNoDelay(true);
+    res.socket.setKeepAlive(true);
+    res.writeHead(200, {
+      'content-type': 'text/event-stream',
+      'cache-control': 'no-store',
+      connection: 'keep-alive',
+      'x-accel-buffering': 'no',
+    });
+    if (sess.reaper) { clearTimeout(sess.reaper); sess.reaper = null; }
+    sess.clients.add(res);
+    res.write(`event: hello\ndata: ${JSON.stringify({ mode: MODE, offset: sess.offset, base: sess.base })}\n\n`);
+    replay(sess, res, Number(url.searchParams.get('from') || 0));
+    const beat = setInterval(() => res.write(': beat\n\n'), HEARTBEAT_MS);
+    const done = () => {
+      clearInterval(beat);
+      sess.clients.delete(res);
+      // Don't reap while another tab is still watching, and give a suspended
+      // Safari a window to come back before the shell dies with it.
+      if (!sess.clients.size && sess.exited === null && !sess.reaper) {
+        sess.reaper = setTimeout(() => killSession(sess), opt.idle * 1000);
+      }
+    };
+    req.on('close', done);
+    req.on('error', done);
+    return undefined;
+  }
+
+  if (route === '/api/input' && req.method === 'POST') {
+    if (!sess) return send(res, 404, 'text/plain', 'no such session\n');
+    return readBody(req, (body) => {
+      try {
+        if (pty) sess.proc.write(body.toString('utf8'));
+        else sess.proc.stdin.write(body);
+      } catch { /* raced with exit */ }
+      send(res, 204, 'text/plain', '');
+    });
+  }
+
+  if (route === '/api/resize' && req.method === 'POST') {
+    if (!sess) return send(res, 404, 'text/plain', 'no such session\n');
+    const cols = Math.max(20, Math.min(500, Number(url.searchParams.get('cols')) || 80));
+    const rows = Math.max(5, Math.min(200, Number(url.searchParams.get('rows')) || 24));
+    if (pty) { try { sess.proc.resize(cols, rows); } catch { /* raced with exit */ } }
+    return send(res, 204, 'text/plain', '');
+  }
+
+  // Line mode has no tty, so Ctrl-C can't arrive as a 0x03 byte the shell will act on.
+  if (route === '/api/signal' && req.method === 'POST') {
+    if (!sess) return send(res, 404, 'text/plain', 'no such session\n');
+    try { sess.proc.kill('SIGINT'); } catch { /* already gone */ }
+    return send(res, 204, 'text/plain', '');
+  }
+
+  if (route === '/api/bye' && req.method === 'POST') {
+    if (sess) killSession(sess);
+    return send(res, 204, 'text/plain', '');
+  }
+
+  return send(res, 404, 'text/plain', 'not found\n');
+});
+
+// ---------------------------------------------------------------- boot
+
+function lanAddresses() {
+  const out = [];
+  for (const list of Object.values(os.networkInterfaces())) {
+    for (const nic of list || []) {
+      if (nic.family === 'IPv4' && !nic.internal) out.push(nic.address);
+    }
+  }
+  return out;
+}
+
+// Requiring this file (the tests do) must not open a port or take over SIGINT;
+// only running it directly should stand a terminal up.
+if (require.main === module) {
+  if (opt.help) {
+    process.stdout.write([
+      'pixelpets ipad-terminal - a browser terminal for this machine',
+      '',
+      '  --lan              bind 0.0.0.0 so the iPad can reach it over Wi-Fi',
+      '  --host=ADDR        bind a specific address (default 127.0.0.1)',
+      '  --port=N           default 7681',
+      '  --token=STR        fixed token (default: a fresh random one each run)',
+      '  --shell=PATH       shell to run (default $SHELL, or powershell.exe on Windows)',
+      '  --idle=SECONDS     keep a disconnected shell alive this long (default 120)',
+      '  --allow-host=NAME  permit this Host header (needed only behind a named tunnel)',
+      '',
+    ].join('\n'));
+    process.exit(0);
+  }
+  if (opt.bad) {
+    console.error(`unknown option ${opt.bad} (try --help)`);
+    process.exit(2);
+  }
+
+  server.listen(opt.port, opt.host, () => {
+    const where = opt.host === '0.0.0.0' ? lanAddresses() : [opt.host];
+    const lines = [
+      '',
+      `  pixelpets terminal  -  ${MODE === 'pty' ? 'full tty' : 'line mode (install node-pty for a real tty)'}`,
+      `  shell: ${SHELL}`,
+    ];
+    // Better to say this now than to let the iPad find out: the page cannot render at
+    // all without xterm, and the fix is on this machine rather than on the tablet.
+    if (!Object.keys(VENDOR).every((k) => vendorPath(k))) {
+      lines.push('  xterm.js: from the CDN - `npm install` in tools/ipad-terminal to serve it locally');
+    }
+    lines.push('', '  open this on the iPad:');
+    for (const addr of where.length ? where : ['127.0.0.1']) {
+      lines.push(`    http://${addr}:${opt.port}/?t=${TOKEN}`);
+    }
+    if (opt.host === '0.0.0.0') {
+      lines.push('', '  reachable by anything on this network that has the token.',
+        '  it is a shell as you - stop it when you are done (ctrl-c).');
+    } else {
+      lines.push('', '  loopback only: pass --lan to let the iPad reach it.');
+    }
+    lines.push('');
+    process.stdout.write(lines.join('\n') + '\n');
+  });
+
+  const shutdown = () => {
+    for (const sess of [...sessions.values()]) killSession(sess);
+    server.close(() => process.exit(0));
+    // Nothing should take a second to close, and a wedged socket must not keep a
+    // terminal server alive after you have asked it to stop.
+    setTimeout(() => process.exit(0), 1000).unref();
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+module.exports = { parseArgs, hostOk, pushOut, replay, SCROLLBACK };