joinstick 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,373 @@
+# Joinstick for coding agents
+
+Joinstick turns phones into gamepads for browser games. The game page (the
+**host**) shows one QR code per player slot; a player scans it and the phone
+becomes a controller. Read this file before integrating; it is the whole
+contract. Wire format: [PROTOCOL.md](PROTOCOL.md). Types:
+[`public/host.d.ts`](public/host.d.ts), [`public/client.d.ts`](public/client.d.ts).
+
+## 1. Run the server
+
+Node 22+:
+
+```sh
+npx joinstick --static ./my-game   # serves the game AND Joinstick on :3000
+# or add it to your project: npm i joinstick, then npx joinstick --static ./my-game
+```
+
+Open `http://localhost:3000/` on the computer. Phones must be on the same
+Wi-Fi. Without `--static`, Joinstick runs alone and your game is served by
+something else (see "Game served elsewhere" below).
+
+## 2. Integrate (copy-paste)
+
+```js
+import { host } from '/joinstick/host.js';
+
+const room = await host({ slots: 2, layout: { stick: 'dpad', buttons: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }] } });
+for (let n = 1; n <= room.slots; n++) showQr(n, room.qr(n), room.joinUrl(n)); // <img src=qr> + the URL as text
+
+function tick() {
+  for (let n = 1; n <= room.slots; n++) {
+    const { x, y, buttons, pressed } = room.input(n); // poll once per frame per slot
+    // move with x/y (and held buttons); trigger one-shot actions with pressed.a
+  }
+  requestAnimationFrame(tick);
+}
+tick();
+```
+
+Slots are **1-based** everywhere. `room.input(0)` throws `RangeError`.
+
+## 3. Pause when a player is missing
+
+The simplest correct recipe is to check every frame:
+
+```js
+const everyone = () => [1, 2].every((n) => room.connected(n));
+// in your frame loop:
+const paused = !everyone();
+```
+
+With events, also check once at start, because pads that were already
+connected when `host()` resolved do not get a `join` event (see below):
+
+```js
+room.on('leave', ({ slot, reason }) => pause(`Waiting for player ${slot}`));
+room.on('join', () => { if (everyone()) resume(); });
+if (!everyone()) pause('Waiting for players');
+```
+
+`leave` fires immediately when a phone is locked, backgrounded, loses Wi-Fi,
+holds "Leave", or is kicked. The same phone rejoins the same slot by itself
+when it comes back; a new person can also scan that slot's QR.
+
+Exact ordering in each reconnect case:
+
+| Case | What the game sees |
+|---|---|
+| Game page reloaded (same tab) | `host()` resumes the room. Pads already connected show as `connected(n) === true` **when `host()` resolves**; no `join` event for them. Pads that arrive later get `join`. Held input is restored. |
+| Host loses the server briefly (Wi-Fi blip) | `leave` (reason `'disconnected'`) for every connected slot, then `join` with `rejoin: true` for each once back. |
+| Server restarted | `leave` (`'disconnected'`) for every slot; the host recreates the same code; each phone rejoins with a `join` whose `rejoin` is **false** (the server forgot the tokens). |
+| Phone locked / Wi-Fi lost, then back | `leave` (`'disconnected'`), later `join` with `rejoin: true`. |
+
+## 4. Input contract
+
+`room.input(n)` returns `{ x, y, buttons, pressed }` and is **never undefined**.
+
+| Field | Meaning |
+|---|---|
+| `x` | -1 left .. 1 right. The d-pad gives -1, 0 or 1. |
+| `y` | -1 **up** .. 1 down (screen convention, like the Gamepad API). |
+| `buttons` | Held state of every layout button: `{ a: false, b: true }`. |
+| `pressed` | Buttons that went down since your previous `input(n)` call: `{ b: true }`. Latched and **cleared on read**, so a tap shorter than one frame is never lost and never counted twice. |
+
+- Use `pressed` for one-shot actions (attack, jump, confirm, pause). **Never
+  use held state (`buttons`) to trigger attacks**: you would fire every frame
+  or miss fast taps.
+- Use `buttons` for things that last while held (block, run, charge).
+- Neutral (`x = y = 0`, all buttons false, `pressed` empty) when the slot is
+  empty and right after `leave`. After a `join` or a game reload, a direction
+  or button the player is already holding shows in `x`/`y`/`buttons` but never
+  in `pressed`.
+- Read `input(n)` exactly once per frame per slot; a second read in the same
+  frame has an empty `pressed`.
+- The d-pad is 8-way. Up and the up-diagonals need the thumb clearly above
+  horizontal (30° or more), so a resting thumb does not jump by accident.
+- There is no input event; polling is the only way to read input.
+- **Keep calling `input(n)` every frame while paused** and ignore the result.
+  Otherwise presses made during the pause are still latched and fire the
+  moment you resume.
+
+## 5. Layout
+
+Passed to `host({ layout })`. Validated by the server; an invalid layout
+makes `host()` reject with `code: 'bad-message'` and a message saying why.
+
+```js
+{
+  stick: 'dpad',                    // 'dpad' (default) or 'none'
+  orientation: 'landscape',         // 'landscape' (default), 'portrait' or 'any'
+  arrangement: 'grid',              // 'grid' (default), 'diamond' or 'arc'
+  haptics: true,                    // tap feedback on the phone (default true)
+  buttons: [                        // 0-8 buttons; default: [{id:'a'},{id:'b'}]
+    { id: 'punch', label: 'P', color: '#e5484d' },
+    { id: 'kick',  label: 'K', haptic: 20 },
+    { id: 'super', label: 'SUPER', size: 'large' },
+    { id: 'block', label: 'BLOCK', size: 'wide' },
+    { id: 'start', label: 'START', system: true },
+  ],
+}
+```
+
+- `id`: `/^[A-Za-z0-9_-]{1,16}$/`, unique, and not an `Object.prototype`
+  name (`constructor`, `toString`, `__proto__`...). It is the key in `buttons`/`pressed`.
+- `label`: ≤ 8 chars (defaults to the id); the pad shrinks long labels to fit
+  the round button, so short labels read best. `color`: `/^#[0-9a-f]{3,8}$/i`.
+- `size`: `'large'` (bigger round button), `'wide'` (a long bar under the
+  others, easy to find blind and rest a thumb on: good for a held action) or omitted.
+- `system: true`: a small pill in the middle of the pad's top bar, away from
+  the thumbs (START, MENU, PAUSE). It reports in `buttons`/`pressed` like any
+  other button. The 8-button limit counts it.
+- `orientation`: with `'landscape'` (the default) a phone held upright shows
+  the pad rotated 90°, so the player turns the phone sideways; it works even
+  with the rotation lock on, and the d-pad ends up under the left thumb. On
+  Android Chrome the first tap also goes fullscreen and locks landscape.
+  `'portrait'` is the mirror case; `'any'` follows the phone.
+- `arrangement` (gameplay buttons only; order matters):
+  - `'grid'`: rows and columns, in order.
+  - `'diamond'`: buttons 1-4 as face buttons (bottom, left, right, top), the
+    rest in a column beside them.
+  - `'arc'`: button 1 is big and sits where the right thumb rests; the rest
+    fan out around it (left, then over the top). Put the most used action first.
+- Taps between buttons go to the nearest one: there are no dead gaps.
+
+**Haptics.** The pad gives a short tick on every button press and d-pad
+direction change (`haptics: false` turns it off; `haptic: ms` per button,
+0 = none). What actually works:
+
+| Phone | Tap feedback | `room.pad(n, { vibrate })` and highlight buzz |
+|---|---|---|
+| Android Chrome/Firefox | yes (`navigator.vibrate`) | yes |
+| iOS 18+ Safari | best effort: one fixed system tick per tap, via a hidden switch control; length is ignored | no |
+| iOS ≤ 17, desktop | no (fails silently) | no |
+
+## 6. Change a pad while playing
+
+```js
+room.pad(1, { title: 'Ryu', color: '#e5484d' });  // header text (≤ 20 chars) and accent color
+room.pad(1, { highlight: ['a'] });                 // glow and make the phone vibrate briefly (Android only)
+room.pad(1, { disabled: ['super'] });              // greyed out, cannot be pressed
+room.pad(1, { vibrate: 200 });                     // one-shot, ms (0-2000), Android only
+room.pad(1, { highlight: [], disabled: [] });      // clear
+```
+
+Patches merge; the server remembers the last state per slot and re-sends it
+when a phone (re)joins. A button that is both highlighted and disabled is
+shown disabled, without glow (disabled wins).
+
+A **game page reload** (any new `host()` call that resumes the room) resets
+every pad to the default state, because the game starts from scratch. In-session
+reconnects (Wi-Fi blips, server restarts) keep the pad state. Pads still
+connected after a reload get no `join` event, so set their state at start too:
+
+```js
+const greet = (slot) => room.pad(slot, { title: `Player ${slot}` });
+room.on('join', ({ slot }) => greet(slot));
+for (let n = 1; n <= room.slots; n++) if (room.connected(n)) greet(n);
+```
+
+## 7. Full host API
+
+```ts
+const room = await host({ slots?: 1-8 = 2, layout?, server?: string });
+room.code                 // 'KQZX' (4 consonants)
+room.slots; room.status   // 'connecting' | 'connected' | 'reconnecting' | 'closed'
+room.input(n)             // see section 4
+room.connected(n)         // boolean
+room.qr(n)                // URL of an SVG QR code for <img src>
+room.joinUrl(n)           // the URL inside the QR: show it as text too
+room.pad(n, patch)        // section 6
+room.kick(n)              // disconnect that phone; it gets a "removed" screen
+room.send(n, data)        // any JSON to one phone (custom controllers)
+room.broadcast(data)      // any JSON to every phone
+room.on(event, fn)        // returns an unsubscribe function
+room.close()              // leave and forget the room (refresh keeps it otherwise)
+```
+
+Events: `join {slot, name, rejoin}`, `leave {slot, reason}` where reason is
+`'left' | 'disconnected' | 'timeout' | 'kicked'`, `message {slot, data}`,
+`status` (string), `error {code, message}` (server errors after `host()`
+resolved).
+
+`host()` rejects with an `Error` whose `code` is `'bad-message'` (invalid
+options), `'server-full'` or `'version'`, or with "Cannot reach the Joinstick
+server" when nothing answers. It never hangs on an error.
+
+A page refresh or a server restart is transparent: the room code and hostToken
+are kept in `sessionStorage`, the host reconnects with backoff and recreates
+the same code, and phones rejoin. QR codes stay valid. A stored room is only
+resumed with the same server URL and the same `slots`; otherwise `host()`
+creates a new room.
+
+**Duplicated tabs:** Chrome's "Duplicate tab" copies `sessionStorage`, so the
+new tab resumes the same room and the original tab gets an `error` event with
+`code: 'replaced'`, then `status: 'closed'` (it stops reconnecting). Show a
+"this game is open in another tab" message on that event.
+
+## 8. CLI and embedding
+
+```
+joinstick [--port 3000] [--static ./dir] [--public-url URL]
+```
+
+| Flag | Env | Purpose |
+|---|---|---|
+| `--port` | `PORT` | Port (default 3000). |
+| `--static <dir>` | | Serve your game from the same server (recommended). |
+| `--public-url <url>` | `PUBLIC_URL` | Base URL phones should open (tunnels, Docker, reverse proxies). Must be an origin like `https://abc.example.com`, without a path: Joinstick's routes live at the root. |
+
+The join URL base is chosen as: `--public-url`, else the `Host` header the
+game used if it is not loopback, else the detected LAN IPv4 (192.168.x
+preferred; Docker/VPN/virtual interfaces skipped). All candidates are printed
+at startup.
+
+`--static` refuses dotfiles (`.env`, `.git/...`) and reads each file whole,
+without HTTP Range support: fine for game assets, but Safari needs Range
+requests to play `<video>`/`<audio>`, so serve media elsewhere if you need it.
+
+Embed in an existing Node server instead of using the CLI:
+
+```js
+import http from 'node:http';
+import { attach } from 'joinstick';
+const server = http.createServer(app); // your handler keeps every other path
+attach(server, { static: './dist', publicUrl: process.env.PUBLIC_URL });
+server.listen(3000);
+```
+
+Call `attach()` after every other `'request'` listener is registered: it wraps
+the listeners that exist at that moment, and later ones would also answer
+Joinstick's routes.
+
+Append `?name=Ana` to a join URL to give the player a name (shown to the host
+in the `join` event).
+
+Routes: WebSocket `/joinstick/ws`; SDKs `/joinstick/host.js`,
+`/joinstick/client.js` (CORS `*`); pad page `/j` and `/j/ROOM/SLOT`; QR
+`/joinstick/qr.svg?room=&slot=` (existing rooms only); `/llms.txt`.
+
+### Game served elsewhere (Vite, another port)
+
+```js
+import { host } from 'joinstick/host'; // npm i joinstick (types included)
+const room = await host({ slots: 2, server: `http://${location.hostname}:3000` });
+```
+
+Pass `server` whenever host.js is bundled; by default it connects to the
+origin it was loaded from. Or import it at runtime from
+`http://localhost:3000/joinstick/host.js` (CORS is open).
+
+## 9. Custom controllers and remote play
+
+`/joinstick/client.js` is what the default pad page is built on. Use it for a
+custom phone UI or a remote client:
+
+```js
+import { join } from '/joinstick/client.js';
+const pad = await join({ room: 'KQZX', slot: 1, name: 'Ana' }); // slot omitted = first free
+pad.setInput({ x: 0, y: -1, buttons: { a: true } }); // full state on every change
+pad.send({ chat: 'gg' });                            // host gets room.on('message')
+pad.on('message', (data) => {});                     // from room.send / broadcast
+pad.on('pad', (state, patch) => {});                 // title/color/highlight/disabled/vibrate
+pad.on('error', (err) => {});                        // kicked, room-closed, replaced...
+pad.on('status', (s) => {});
+pad.leave();
+```
+
+`join()` rejects with `err.code` in `room-not-found`, `slot-taken` (with
+`err.free`, the free slots), `bad-slot`, `version`, `unreachable`. Tokens are
+kept in `localStorage` (`joinstick:ROOM:SLOT`) so the same browser rejoins the
+same slot.
+
+Remote players over the internet:
+
+```sh
+cloudflared tunnel --url http://localhost:3000     # prints https://xyz.trycloudflare.com
+node joinstick/src/cli.js --static ./my-game --public-url https://xyz.trycloudflare.com
+```
+
+QR codes and `joinUrl()` then point at the tunnel; phones use `wss://` automatically.
+
+Room codes are 4 letters (160,000 combinations), so on a public URL anyone
+patient can guess one and take a free slot. That is fine for playing with
+friends; there is no authentication beyond the code. The server caps rooms at
+1000 in total and 20 per client address (behind a tunnel all hosts share one
+address).
+
+## 10. Error codes
+
+| Code | Meaning |
+|---|---|
+| `room-not-found` | No room with that code (typo, or the host is gone). |
+| `slot-taken` | Another phone holds that slot. Comes with `free: [..]`. |
+| `bad-slot` | Slot is not an integer in 1..slots. |
+| `bad-message` | Malformed or invalid message; `message` says why. Not fatal. |
+| `replaced` | The same player (or host) connected again elsewhere; this connection is closed. |
+| `kicked` | The host called `room.kick(n)`. |
+| `room-closed` | The host was gone for 60 s; the room was deleted. |
+| `version` | Protocol version mismatch. |
+| `server-full` | 1000 rooms already exist, or this address already created 20. |
+| `rate-limited` | 20 failed joins from this address in a minute (code guessing); wait a minute. |
+| `unreachable` | Client SDK only: the server could not be reached. |
+
+## 11. Pitfalls
+
+- **First run on macOS/Windows** shows a firewall prompt for Node. Allow it, or
+  phones cannot connect.
+- **Guest / hotel / office Wi-Fi** often isolates clients (AP isolation):
+  phones cannot reach the laptop. Use a phone hotspot or `--public-url` with a tunnel.
+- **Plain HTTP on a LAN** works, but phones get no wake lock and no fullscreen
+  on iOS. Host-driven `vibrate` only works on Android (see Haptics in section 5).
+- **Mixed content:** a game page served over HTTPS cannot open `ws://` to a LAN
+  server. Serve the game with `--static`, or put both behind HTTPS (tunnel +
+  `--public-url`).
+- **Docker** breaks LAN IP detection (you get the container IP). Pass
+  `--public-url http://<host-lan-ip>:3000`.
+- Check the printed "Phones join at" URL: if it is not reachable from a phone,
+  nothing else will be.
+- A pad in a **background tab** leaves its slot (that is the lock-screen
+  behavior). When testing with pads in the browser, keep them in the visible
+  game tab or a separate window, or use a Node script (next section).
+
+## 12. Testing without phones
+
+Drive pads from code with the client SDK; it is how you verify an
+integration end to end. In the game tab's DevTools console (the room code is
+`room.code`; use the full `http://localhost:3000/joinstick/client.js` URL if
+the game is served from another origin):
+
+```js
+const { join } = await import('/joinstick/client.js');
+const pad = await join({ room: 'KQZX', slot: 1 });
+pad.setInput({ x: 1 });                                  // hold right
+pad.setInput({ x: 1, buttons: { a: true } });            // press A...
+pad.setInput({ x: 1, buttons: { a: false } });           // ...and release: pressed.a once
+pad.leave();                                             // the game should pause
+```
+
+Or from a Node 22+ script next to the checkout (`node pads.mjs KQZX`):
+
+```js
+import { join } from './joinstick/public/client.js';
+const pad = await join({ server: 'http://localhost:3000', room: process.argv[2], slot: 2 });
+setInterval(() => pad.setInput({ x: Math.sign(Math.random() - 0.5) }), 500);
+```
+
+## 13. Don't
+
+- Don't use `innerHTML` with player names, messages or anything from the
+  network. Use `textContent`.
+- Don't trigger one-shot actions from held state; use `pressed`.
+- Don't call `input(n)` more than once per frame per slot (it consumes `pressed`).
+- Don't assume a slot is connected; check `room.connected(n)` or listen to `leave`.

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the version
+is 0.x, a minor release may change the API; the changelog says how.
+
+## [0.1.0] - 2026-10-04
+
+First public release.
+
+### Added
+
+- `joinstick` CLI: one Node server for rooms, the phone pad page at `/j`, the
+  browser SDKs at `/joinstick/*`, QR codes and `/llms.txt`; `--static` serves
+  your game on the same port, `--public-url` sets the address in QR codes.
+- `attach(server, opts)` to embed Joinstick in an existing Node HTTP server.
+- Game SDK (`host.js`): rooms with up to 8 slots, per-frame `input(n)` with
+  held `buttons` and one-shot `pressed`, join/leave events, QR and join
+  URLs, live pad changes (title, color, highlight, disabled, vibrate),
+  messages both ways.
+- Phone SDK (`client.js`) for custom controllers and scripted test pads.
+- Pad page: d-pad and up to 8 buttons; `grid`, `diamond` and `arc`
+  arrangements; `large` and `wide` buttons; `system` buttons (START/MENU) in
+  the top bar; landscape by default with CSS rotation when the phone is held
+  upright; tap haptics (Android, best effort on iOS 18+); multi-touch.
+- Reconnection: phones that lock or drop Wi-Fi rejoin their slot; game page
+  reloads and server restarts keep the room code (AGENTS.md has the details).
+- Room safety: 20 failed joins per minute per client address, then
+  `rate-limited`; per-address room cap; 4-letter room codes.
+- `--version` flag.
+- JSON/WebSocket protocol v1 (PROTOCOL.md), AGENTS.md for coding agents,
+  TypeScript declarations, Dockerfile.
+
+[0.1.0]: https://github.com/raprav/joinstick/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafa Prats
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,236 @@
+# Joinstick protocol, version 1
+
+Plain JSON text frames over one WebSocket at `/joinstick/ws`. Every message is
+an object with a string field `t`. You only need this to write a client in
+another language; browser code should use `host.js` / `client.js`.
+
+```
+ host (game)                    server                     pad (phone)
+   | create ------------------->  |                            |
+   | <------------------ created  |                            |
+   |                              | <---------------------- join
+   | <--------------------- join  | joined ------------------> |
+   | <-------------------- input  | <--------------------- input
+   | pad / send / kick ---------> | pad / message / error ---> |
+   | <------------------- leave   |          (socket closed)   |
+```
+
+A connection is a host or a pad, decided by its first message (`create` or
+`join`). Anything else first gets `bad-message`.
+
+## Common rules
+
+- Max frame size 8 KB; bigger frames close the socket with code 1009.
+- Unknown or malformed messages get `{t:'error', code:'bad-message', message}`
+  and are otherwise ignored.
+- Slots are 1-based integers. Room codes are 4 letters from
+  `BCDFGHJKLMNPQRSTVWXZ`, case-insensitive (the server upper-cases them).
+- Fatal errors are sent as `{t:'error', code}` and then the server closes the
+  socket with code 4000 and the error code as reason.
+
+## Liveness
+
+The server sends `{t:'ping'}` every 2 s to every socket. Clients answer
+`{t:'pong'}`. Any message counts as activity. The server drops a socket after
+5 s of silence; clients should drop and reconnect after 5 s without any
+message from the server.
+
+## Host → server
+
+### `create`
+
+```json
+{"t":"create","v":1,"slots":2,"layout":{"stick":"dpad","buttons":[{"id":"a","label":"A"}]},"room":"KQZX","hostToken":"…","resetPads":true}
+```
+
+| Field | |
+|---|---|
+| `v` | Must be `1`, else fatal `version`. |
+| `slots` | 1-8, default 2. |
+| `layout` | Optional. `stick`: `'dpad'` (default) or `'none'`. `orientation`: `'landscape'`, `'portrait'` or `'any'`. `arrangement`: `'grid'`, `'diamond'` or `'arc'`. `haptics`: boolean. `buttons`: ≤ 8 of `{id, label?, color?, size?, haptic?, system?}`; `id` `/^[A-Za-z0-9_-]{1,16}$/`, unique, not an `Object.prototype` name; `label` ≤ 8 chars (default id), `color` `/^#[0-9a-f]{3,8}$/i`, `size` `'large'` or `'wide'`, `haptic` integer ms 0-100, `system` boolean. Optional fields are echoed only when given; the pad applies the defaults (landscape, grid, haptics on, 10 ms). Default: d-pad + buttons `a`, `b`. |
+| `room`, `hostToken` | Optional, to resume. |
+| `resetPads` | Optional. `true` on resume clears every slot's pad state (the game was reloaded). The host SDK sends it on the first `create` of each `host()` call. |
+
+Resume-or-recreate:
+
+- `room` exists, `hostToken` matches and `slots` is the same → **resume** the
+  same room and pads. A previous host connection gets fatal `replaced`. If the
+  layout changed or `resetPads` is true, connected pads receive a fresh
+  `joined`. Right after `created`, the server sends the last `input` of every
+  connected pad, so held state survives the reload.
+- `room` does not exist, `room` is a valid code and `hostToken` is 32 hex
+  chars → **recreate** the room with that code and token (server restart case).
+- Otherwise → a new room with a new code and token.
+
+More than 1000 rooms, or 20 rooms created from the same client address →
+fatal `server-full`.
+
+### `pad`
+
+```json
+{"t":"pad","slot":1,"patch":{"title":"Ryu","color":"#e5484d","highlight":["a"],"disabled":["b"],"vibrate":200}}
+```
+
+All patch fields optional: `title` (string, trimmed to 20 chars), `color` (hex),
+`highlight` / `disabled` (arrays of ≤ 8 button ids), `vibrate` (integer
+0-2000 ms). The server merges the patch into that slot's pad state (everything
+but `vibrate`), keeps it while the room lives, and forwards the patch to the
+pad.
+
+### `send`
+
+```json
+{"t":"send","slot":1,"data":{"any":"json"}}
+{"t":"send","slot":null,"data":"to every pad"}
+```
+
+### `kick`
+
+```json
+{"t":"kick","slot":1}
+```
+
+The pad gets fatal `kicked`; the host gets `leave` with reason `kicked`.
+
+## Server → host
+
+### `created`
+
+```json
+{"t":"created","room":"KQZX","hostToken":"9f…32 hex","joinBase":"http://192.168.1.20:3000","layout":{…validated…},"slots":[{"slot":1,"connected":false,"name":""}]}
+```
+
+Pads join at `${joinBase}/j/${room}/${slot}`. The QR for a slot is
+`/joinstick/qr.svg?room=KQZX&slot=1` on the Joinstick server.
+
+### `join`
+
+```json
+{"t":"join","slot":1,"name":"Ana","rejoin":false}
+```
+
+`rejoin` is true when the token is the same as the slot's previous occupant
+(same phone coming back, or taking over from another tab).
+
+### `leave`
+
+```json
+{"t":"leave","slot":1,"reason":"left"}
+```
+
+`reason`: `left` (pad closed with code 1000), `disconnected` (any other
+close, including a locked phone), `timeout` (no pong for 5 s), `kicked`.
+
+### `input`
+
+```json
+{"t":"input","slot":1,"x":-1,"y":0,"b":{"a":true,"b":false}}
+```
+
+Full state, forwarded as sent by the pad (x, y clamped to [-1, 1]). The first
+`input` after a `join` (or after `created` on resume) is the slot's baseline:
+buttons already down in it are held, not new presses. The client SDK always
+sends one right after `joined`.
+
+### `message`
+
+```json
+{"t":"message","slot":1,"data":{"any":"json"}}
+```
+
+## Pad → server
+
+### `join`
+
+```json
+{"t":"join","v":1,"room":"KQZX","slot":1,"token":"32 hex chars","name":"Ana"}
+```
+
+| Field | |
+|---|---|
+| `v` | Must be `1`, else fatal `version`. |
+| `room` | Case-insensitive. Unknown → `room-not-found`. |
+| `slot` | Optional. Omitted/null → the slot this token held before, else the first free one. Not 1..slots → `bad-slot`. |
+| `token` | `/^[A-Za-z0-9_-]{16,64}$/`, generated and stored by the client. Identifies the phone. |
+| `name` | Optional, control chars stripped, trimmed to 20 chars. |
+
+The first join and a rejoin are the same message. Outcomes:
+
+- Slot empty → taken.
+- Slot occupied by the **same token** → the new connection wins; the old one
+  gets fatal `replaced`.
+- Slot occupied by **another token** → `{t:'error', code:'slot-taken', free:[2,3]}`.
+
+After 5 failed joins on one socket the server closes it. After 20 failed
+joins from one client address within a minute, every further `join` from
+that address gets fatal `rate-limited` until the minute is over. Failures in
+the first minute after the server starts are not counted: phones are still
+waiting for their game to recreate its room.
+
+### `input`
+
+```json
+{"t":"input","x":0,"y":-1,"b":{"a":true}}
+```
+
+Full state on every change. `x`, `y` are finite numbers (clamped to [-1, 1];
+`y` = -1 is up). `b` maps ≤ 16 button ids to booleans (`Object.prototype`
+names are refused). While the host is away it is not forwarded, but the
+server keeps the latest one per slot for the host's resume. Send your current
+state right after every `joined`.
+
+### `msg`
+
+```json
+{"t":"msg","data":{"any":"json"}}
+```
+
+Delivered to the host as `message` with the pad's slot.
+
+## Server → pad
+
+### `joined`
+
+```json
+{"t":"joined","room":"KQZX","slot":1,"layout":{…},"pad":{"title":"Ryu","color":"#e5484d"}}
+```
+
+`pad` is the slot's current pad state. Sent again (same shape) when the host
+resumes with a different layout or with `resetPads`.
+
+### `pad`
+
+```json
+{"t":"pad","patch":{"highlight":["a"],"vibrate":200}}
+```
+
+### `message`
+
+```json
+{"t":"message","data":{"any":"json"}}
+```
+
+## Errors
+
+| Code | Fatal | When |
+|---|---|---|
+| `room-not-found` | no | `join` with an unknown room. |
+| `slot-taken` | no | Slot held by another token. Includes `free`. |
+| `bad-slot` | no | Slot is not an integer in 1..slots. |
+| `bad-message` | no | Invalid JSON, shape or values. Includes `message`. |
+| `replaced` | yes | Same host token or pad token connected again. |
+| `kicked` | yes | Host kicked this pad. |
+| `room-closed` | yes | Host gone for 60 s; room deleted. |
+| `version` | yes | `v` is not 1. |
+| `server-full` | yes | Room limit reached (1000 total, 20 per client address). |
+| `rate-limited` | yes | 20 failed joins from this client address in the last minute. |
+
+"Fatal" means the server closes the socket right after the error. Failed
+joins (the non-fatal join errors) count toward the 5-failure limit.
+
+## Host disconnects
+
+When the host socket closes, the room stays for 60 s. Pads stay connected
+(their input is dropped). A host that sends `create` with the same `room` and
+`hostToken` within that time resumes it; otherwise every pad gets
+`room-closed` and the room is deleted.