feat(ipad): a browser terminal for this machine, driven from an iPad

[JOhnsonKC201]

What does this change?

Adds tools/ipad-terminal/ — a terminal for this machine that you drive from an iPad.

npm run ipad:lan

It prints a URL. Open it in Safari on the iPad and you get a real shell — vim, top, tab completion, colours — on the computer pixelpets runs on. Share → Add to Home Screen gives it an icon and a full-screen window.

The limitation this is built around

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 gets around that — 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.

Built for a tablet specifically

• Backgrounding Safari doesn't kill your work. Safari suspends a backgrounded tab, so the naive version loses the shell the moment you check a message. The shell outlives its connection (--idle, default 120s), and the client counts the bytes it has rendered so a reconnect asks for exactly the gap — missed output replayed, already-read output not repeated.
• The keys a soft keyboard doesn't have. A key bar supplies Esc, Tab, Ctrl and arrows, with a sticky Ctrl. Taps use pointerdown rather than click, because moving focus to a button on iPadOS dismisses the keyboard mid-command.
• Layout follows visualViewport, since the soft keyboard covers the window rather than resizing it.

Shape of it

Runs on plain node with nothing installed: output over SSE, input over POST, rather than hand-rolled RFC 6455 framing for something that shuttles a few hundred bytes per keypress. npm install inside the tool adds a real pty and vendors xterm.js locally; without it the server drops to line mode and the page pulls xterm from a pinned CDN, and the boot banner says which you're getting.

It is its own package on purpose — node-pty is native and xterm is browser-side, so neither belongs in the Electron bundle. The root package.json gains only two scripts; package-lock.json is untouched.

Security

Loopback unless --lan. 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 can't probe the port. The page strips the token out of the address bar on load and authenticates its own stylesheet and script with a SameSite=Strict cookie that the API itself refuses. It's plain HTTP — fine on your own Wi-Fi, and the README says to use a TLS tunnel rather than a port forward for anything else.

Two bugs found while testing, fixed here

• A session created but never streamed to held a live shell open forever — only a disconnecting client armed the cleanup.
• The locally vendored xterm files 401'd in a real browser: a <script src> can't carry an auth header. That's what the subresource cookie is for.

Verification

Beyond the test suite, this was driven in Chromium at an iPad viewport: opened vim, typed in insert mode, hit Esc from the key bar, :wq, and cat confirmed the file; tty reports /dev/pts/0 and tput cols matches the fitted terminal; colours and CJK render; no console errors. The offline path was checked too — with the CDN blocked the page shows the "run npm install" message and a retry button rather than a blank screen.

Checklist

• npm test is green — 200 passing (193 existing + 7 new), with and without node-pty installed
• npx eslint src/ tests/ is clean (npm run lint over the whole tree is clean too)
• If this touches rendering: n/a — no sprite, palette or renderer code touched
• If this touches src/cat-sprite.js: n/a — not touched
• All art/sound in this PR is original or procedural — no art or sound added; the only third-party code is xterm.js, loaded from a pinned CDN or an opt-in local install, never vendored into the repo

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pixelcat	Ready	Preview	Aug 28, 2026 3:12am