joinstick 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,270 @@
-# Temporary Holding Version
+# Joinstick
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Use phones as gamepads for browser games.** The game shows a QR code, each
+player scans it, and their phone becomes a controller. No accounts, no app
+install: one small self-hosted Node server and a few lines in your game. Made
+for local multiplayer and party games on a laptop or TV.
+
+[![npm](https://img.shields.io/npm/v/joinstick)](https://www.npmjs.com/package/joinstick)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![node >= 22](https://img.shields.io/badge/node-%3E%3D22-339933)](package.json)
+[![CI](https://github.com/raprav/joinstick/actions/workflows/ci.yml/badge.svg)](https://github.com/raprav/joinstick/actions/workflows/ci.yml)
+
+<p align="center"><img src="https://raw.githubusercontent.com/raprav/joinstick/main/docs/hero.png" alt="Left: the example game on a laptop, showing a room code, two moving squares and a QR code per player. Right: a phone held sideways showing the Joinstick pad with a d-pad and two buttons." width="800"></p>
+
+## Quick start
+
+Save this as `my-game/index.html`:
+
+```html
+<!doctype html>
+<meta charset="utf-8">
+<img id="qr" width="240">
+<script type="module">
+  import { host } from '/joinstick/host.js';
+  const room = await host({ slots: 2 });          // default pad: d-pad + A, B
+  document.getElementById('qr').src = room.qr(1); // player 1 scans this
+  (function frame() {
+    const p1 = room.input(1);                     // { x, y, buttons, pressed }, never undefined
+    if (p1.pressed.a) console.log('jump!');       // x, y in [-1, 1]; pressed = went down since last read
+    requestAnimationFrame(frame);
+  })();
+</script>
+```
+
+Then run (Node 22 or newer):
+
+```sh
+npx joinstick --static ./my-game
+```
+
+Open `http://localhost:3000` on the computer, scan the QR with a phone on the
+same Wi-Fi, and press A. Embedding in your own Node server or using
+TypeScript: `npm i joinstick`. A complete example game is in
+[`examples/basic`](examples/basic).
+
+### Using a bundler or your own dev server
+
+Run Joinstick on its own port next to your dev server (Vite, webpack...) and
+tell the SDK where it is:
+
+```sh
+npm i joinstick
+npx joinstick                 # Joinstick alone on :3000
+```
+
+```js
+import { host } from 'joinstick/host'; // typed
+
+const room = await host({ slots: 2, server: `http://${location.hostname}:3000` });
+```
+
+QR codes then point at that server. If your dev server uses HTTPS, Joinstick
+needs HTTPS too (see Self-hosting).
+
+## How it works
+
+```
+  laptop / TV                     Joinstick server                 phones
+ ┌─────────────┐   WebSocket    ┌──────────────────┐  WebSocket   ┌──────────┐
+ │ your game   │ ◄────────────► │ rooms, relay,    │ ◄──────────► │ pad page │
+ │ + host.js   │  input, joins  │ QR codes, pad    │  pad state   │ /j/KQZX/1│
+ └─────────────┘                │ page, SDKs       │              └──────────┘
+                                └──────────────────┘
+```
+
+The game creates a room (`KQZX`) with up to 8 player slots. Each slot has a QR
+code that opens `/j/KQZX/<slot>` on a phone. The phone sends its controller
+state on every change; your game reads `room.input(n)` once per frame. All
+traffic goes through your server; nothing leaves your network unless you put
+it on the internet.
+
+## Features
+
+- **Zero install for players**: a QR code (or `http://<laptop-ip>:3000/j` and
+  a 4-letter code) opens the controller in the phone's browser.
+- **Small and self-hosted**: one Node process, two runtime dependencies
+  (`ws`, `uqr`), plain ES modules in the browser, no build step.
+- **Reconnects automatically**: phones that lock or drop Wi-Fi leave and rejoin
+  their own slot; game page reloads and server restarts keep the room code.
+  Your game gets `join`/`leave` events to pause and resume.
+- **Configurable pad**: d-pad plus up to 8 buttons with labels, colors and
+  sizes; the game can retitle, recolor, highlight or disable buttons live.
+- **Landscape by default**: held upright, the pad shows rotated, so it works
+  with the phone's rotation lock on (on Android Chrome the first tap also
+  tries fullscreen and an orientation lock).
+- **Haptics**: a short tick on every press (Android; best effort on iOS 18+,
+  see the FAQ), plus game-driven vibration on Android.
+- **Bring your own controller**: the pad is just one client of a documented
+  JSON/WebSocket protocol; `client.js` lets you build your own or drive pads
+  from tests.
+
+## Pad layouts
+
+```js
+await host({
+  slots: 2,
+  layout: {
+    arrangement: 'arc',               // 'grid' (default) | 'diamond' | 'arc'
+    buttons: [
+      { id: 'punch', label: 'PUNCH' }, // in 'arc' the first button is the big one
+      { id: 'kick', label: 'KICK' },
+      { id: 'ult', label: 'ULT', size: 'large' },
+      { id: 'block', label: 'BLOCK', size: 'wide' },   // a bar to rest a thumb on
+      { id: 'start', label: 'START', system: true },   // a pill in the top bar
+    ],
+  },
+});
+```
+
+<p align="center"><img src="https://raw.githubusercontent.com/raprav/joinstick/main/docs/layouts.png" alt="Four pad screenshots: grid, diamond, arc, and arc with a wide BLOCK bar. Each has a d-pad on the left and a START pill in the top bar." width="800"></p>
+
+Also: `stick: 'none'` (buttons only), `orientation: 'landscape' | 'portrait' |
+'any'`, `haptics: false`, per-button `color` and `haptic` (ms). Taps between
+buttons go to the nearest one, and several fingers work at once (move, hold
+a button, tap another). Full schema in [AGENTS.md](AGENTS.md#5-layout).
+
+## API in one screen
+
+| Game side (`/joinstick/host.js`) | |
+|---|---|
+| `host({ slots, layout, server })` | Create (or after a reload, resume) a room. `server` is the Joinstick URL when the game is served elsewhere. |
+| `room.input(n)` | `{ x, y, buttons, pressed }` for player `n`. Read it every frame. |
+| `room.qr(n)`, `room.joinUrl(n)` | QR image URL and plain join link for player `n`. |
+| `room.connected(n)`, `room.on('join' \| 'leave', fn)` | Who is here; pause when someone drops. |
+| `room.pad(n, { title, color, highlight, disabled, vibrate })` | Change what a phone shows. |
+| `room.send(n, data)`, `room.broadcast(data)`, `room.on('message', fn)` | Custom messages both ways. |
+| `room.kick(n)`, `room.close()` | Remove a player; end the room. |
+| `room.on('status' \| 'error', fn)` | Connection to the server (`connected`, `reconnecting`...) and fatal errors. |
+
+| Server side (`import { attach } from 'joinstick'`) | |
+|---|---|
+| `attach(httpServer, { static, publicUrl })` | Add Joinstick to your own Node HTTP server. |
+
+Types: [`host.d.ts`](public/host.d.ts), [`client.d.ts`](public/client.d.ts),
+[`server.d.ts`](src/server.d.ts). Wire protocol: [PROTOCOL.md](PROTOCOL.md).
+Everything else (input contract, pausing, error codes, testing without
+phones): [AGENTS.md](AGENTS.md).
+
+## CLI
+
+```
+joinstick [--port 3000] [--static ./dir] [--public-url URL] [--version]
+```
+
+| Flag | Env | |
+|---|---|---|
+| `--port` | `PORT` | Port to listen on. Default 3000. |
+| `--static <dir>` | | Also serve your game from this directory. |
+| `--public-url <url>` | `PUBLIC_URL` | Origin that QR codes and join links use (no path). Default: the host the game page connected with, unless it is `localhost`/loopback; then the detected LAN address. |
+| `-v`, `--version` | | Print the version. |
+
+## Self-hosting
+
+- **LAN (the usual case)**: run it on the laptop that shows the game. Phones
+  on the same Wi-Fi open the printed "Phones join at" URL. Plain HTTP is fine.
+- **Behind a reverse proxy with TLS**: proxy everything (or at least `/j`,
+  `/joinstick/`) to Joinstick, let the proxy pass WebSocket upgrades on
+  `/joinstick/ws`, and start Joinstick with `--public-url https://your.domain`
+  so QR codes point at the public address. Behind a proxy every game shares
+  the proxy's IP address, so the 20-rooms-per-IP cap applies to all of them
+  together. With Caddy (which passes WebSockets through by default):
+
+  ```
+  your.domain {
+    reverse_proxy localhost:3000
+  }
+  ```
+
+- **Docker**: the repo has a small [Dockerfile](Dockerfile) (non-root,
+  Node 22 Alpine; it is not in the npm package). Inside a container the LAN
+  address cannot be detected, so pass `--public-url`. From a clone of the repo:
+
+  ```sh
+  docker build -t joinstick .
+  docker run --rm -p 3000:3000 -v "$PWD/my-game:/site:ro" joinstick \
+    --static /site --public-url http://<your-lan-ip>:3000
+  ```
+
+## Remote play
+
+What works today: put the server on a public URL (a tunnel such as
+`cloudflared tunnel --url http://localhost:3000`, or a reverse proxy) and pass
+that URL as `--public-url`. Remote phones then join like local ones.
+
+What it does not do: Joinstick only carries controller input. Remote players
+still need to see the game (screen sharing, a video call). Input is relayed
+through your server, not peer to peer, so each remote player adds their
+network delay to the server.
+
+Security on a public URL, plainly:
+
+- The room code is the only credential. Codes are 4 letters from 20
+  consonants, so 160,000 possible codes. Anyone who guesses a live code can
+  take a **free** slot (a taken slot also needs that phone's secret token).
+- Guessing is slowed down: after 20 failed joins in a minute, an address is
+  refused for the rest of that minute (not counted in the first minute after
+  the server starts, while phones rejoin). Behind a tunnel or proxy every phone
+  shares the proxy's address, so a guesser also delays real players by up to
+  a minute.
+- The server does not check the `Origin` header: any web page that knows the
+  server's address can open a connection to it, like any other client.
+
+Fine for playing with friends; not for anything secret.
+
+## For AI coding agents
+
+Point your agent at [AGENTS.md](AGENTS.md): integration checklist, full API,
+input contract, pitfalls, and how to test with scripted pads instead of
+phones. A running server also serves a condensed version at `/llms.txt`.
+
+## FAQ
+
+**The phone can't connect.** It must reach the laptop: same Wi-Fi, and allow
+Node through the firewall prompt on first run (macOS/Windows). Guest, hotel
+and office networks often isolate devices; use a phone hotspot or a tunnel.
+If the printed "Phones join at" URL doesn't open on the phone, nothing else will.
+
+**Do players need the same Wi-Fi?** For local play, yes (or any network where
+the phone can reach the server). For remote play, see above.
+
+**Does vibration work on iPhone?** Partly. Android gets tap feedback and
+game-driven vibration. iOS Safari has no vibration API; on iOS 18+ the pad
+plays the system's single haptic tick on presses as a best effort (length is
+ignored, game-driven vibration does nothing). Older iOS and desktops: none.
+
+**How much latency?** Input is sent the moment it changes, with no polling or
+batching. On a LAN the delay is about one Wi-Fi hop from the phone to the
+laptop. The server's own relay is small: measured on loopback (pad socket to
+server to game socket, same machine, 500 inputs) the median was 0.06 ms. We
+have not published phone-to-screen numbers.
+
+**Which browsers?**
+
+| | Chrome / Android | Safari / iOS | Firefox | Samsung Internet |
+|---|---|---|---|---|
+| Phone pad | 87 | 14.5 | 79 | 14 |
+| Game page (`host.js`) | 93 | 15.4 | 92 | 17 |
+
+Derived, not tested on each version: these are the first versions that
+support the newest feature each side needs, looked up in MDN's
+[browser-compat-data](https://github.com/mdn/browser-compat-data) 8.1.4. Pad:
+CSS `inset` (Chrome 87, iOS 14.5), `??=` (Firefox 79), plus Pointer Events,
+ES modules and WebSocket. Game page: `Object.hasOwn` in `host.js`; the
+Quick start snippet also uses top-level `await` (Chrome 89, Safari 15,
+Firefox 89). Newer browsers additionally get `color-mix()` colors (Chrome 111,
+Safari 16.2, Firefox 113); older ones show plainer colors. The iOS haptic tick
+needs iOS 18.
+
+**Limits?** 8 players per room, 8 buttons per pad, 1000 rooms per server
+(20 per IP address), 8 KB per message. A room closes 60 s after the game page
+goes away.
+
+**HTTPS game page?** A page served over HTTPS cannot open a plain `ws://`
+connection. Serve the game with `--static`, or put both behind HTTPS.
+
+## License
+
+[MIT](LICENSE) © 2026 Rafa Prats. Third-party notices:
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+QR Code is a registered trademark of DENSO WAVE INCORPORATED.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,66 @@
+# Third-party notices
+
+Joinstick's own code is MIT licensed, © 2026 Rafa Prats (see [LICENSE](LICENSE)).
+Every file in `src/` and `public/` is original to this project.
+
+Joinstick does not bundle third-party code. It depends on the npm packages
+below, which npm installs next to it (the Docker image includes them). Both
+are MIT licensed; their notices follow.
+
+QR Code is a registered trademark of DENSO WAVE INCORPORATED.
+
+## ws
+
+https://github.com/websockets/ws (MIT)
+
+```
+Copyright (c) 2011 Einar Otto Stangvik <einaros@gmail.com>
+Copyright (c) 2013 Arnout Kazemier and contributors
+Copyright (c) 2016 Luigi Pinca and contributors
+
+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.
+```
+
+## uqr
+
+https://github.com/unjs/uqr (MIT; based on the QR Code generator library by Project Nayuki)
+
+```
+MIT License
+
+Copyright (c) Project Nayuki
+Copyright (c) 2023 Anthony Fu <https://github.com/antfu>
+
+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/llms.txt

@@ -0,0 +1,102 @@
+# Joinstick
+
+> Turn phones into gamepads for browser games. The game page (host) shows one QR code per player slot; scanning it opens a controller page on the phone. Self-hosted Node server (`npx joinstick`), plain ESM browser SDKs, JSON over WebSocket.
+
+Full guide: AGENTS.md. Wire format: PROTOCOL.md. Types: /joinstick/host.d.ts, /joinstick/client.d.ts (all in the npm package and at https://github.com/raprav/joinstick).
+
+## Run
+
+`npx joinstick --static ./my-game` serves the game and Joinstick on http://localhost:3000 (or `npm i joinstick`, then `npx joinstick`). Node 22+. Phones must be on the same Wi-Fi. Flags: `--port` (PORT, default 3000), `--static <dir>`, `--public-url <url>` (PUBLIC_URL; base URL phones open, an origin without a path, for tunnels/Docker/proxies).
+
+## Integrate
+
+```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' }] } });
+// show <img src={room.qr(n)}> and the text room.joinUrl(n) for n = 1..room.slots
+function tick() {
+  for (let n = 1; n <= room.slots; n++) {
+    const { x, y, buttons, pressed } = room.input(n); // once per frame per slot
+  }
+  requestAnimationFrame(tick);
+}
+tick();
+```
+
+If host.js is bundled or the game is served from another origin: `import { host } from 'joinstick/host'` (package installed from git or a checkout) and pass `server: 'http://<host>:3000'`.
+
+## Input contract
+
+- Slots are 1-based. `room.input(0)` throws RangeError.
+- `room.input(n)` is never undefined: `{ x, y, buttons, pressed }`. Neutral when the slot is empty and after leave. After a join or game reload, input already held shows in x/y/buttons but never in pressed.
+- `x`: -1 left .. 1 right. `y`: -1 up .. 1 down. The d-pad gives -1/0/1 (8-way; up needs the thumb clearly above horizontal).
+- `buttons`: held state of every layout button. Use for movement, block, charge.
+- `pressed`: buttons that went down since the previous `input(n)` call, latched and cleared on read. Use for attacks, jumps, confirm. Never use held state to trigger one-shot actions.
+- No input events: polling is the only way to read input.
+- Keep calling input(n) every frame while paused (ignore the result), or presses made during the pause fire on resume.
+
+## Pause recipe
+
+```js
+const paused = ![1, 2].every((n) => room.connected(n)); // every frame: simplest and always right
+room.on('leave', ({ slot, reason }) => pause(slot));     // reason: left | disconnected | timeout | kicked
+room.on('join', ({ slot, name, rejoin }) => maybeResume());
+```
+
+A locked/backgrounded phone leaves immediately and rejoins its slot when back (join with rejoin: true). Game page reload: host() resumes the same room; pads already connected are visible via connected(n) when host() resolves and get NO join event, so check connected(n) at start; held input is restored; every pad's state (title/color/highlight/disabled) is reset. Host Wi-Fi blip: leave (disconnected) for all, then join with rejoin: true. Server restart: same room code; phones rejoin with rejoin: false. A stored room is only resumed with the same slots count. A duplicated browser tab takes over the room: the original gets room.on('error') with code 'replaced' and status 'closed'.
+
+## Layout
+
+`{ stick: 'dpad' | 'none', orientation?: 'landscape' (default) | 'portrait' | 'any', arrangement?: 'grid' (default) | 'diamond' | 'arc', haptics?: true, buttons: [{ id, label?, color?, size?: 'large' | 'wide', haptic?: ms 0-100, system?: true }] }`, max 8 buttons (system ones included). id `/^[A-Za-z0-9_-]{1,16}$/` unique, not an Object.prototype name (constructor, toString...); label ≤ 8 chars; color `/^#[0-9a-f]{3,8}$/i`. Default: d-pad + a, b. Invalid layout → host() rejects with code 'bad-message'.
+- orientation 'landscape': a phone held upright shows the pad rotated 90° (works with the rotation lock on); Android Chrome also goes fullscreen and locks the orientation on the first tap.
+- arrangement: 'diamond' = first 4 buttons as face buttons (bottom, left, right, top), the rest beside them; 'arc' = first button big under the right thumb, the rest fanned around it.
+- size 'wide': a long bar under the other buttons (good for a held action like block).
+- system: true renders a small pill in the pad's top bar (START/MENU); it reports in input(n).buttons/pressed like any other button.
+- haptics: local tap feedback on press and d-pad direction change (Android: vibrate; iOS 18+: best-effort system tick; desktop: none). layout.haptics false turns it off; per-button haptic sets ms (0 = off).
+
+## Host API
+
+room.code, room.slots, room.status ('connecting'|'connected'|'reconnecting'|'closed'), room.input(n), room.connected(n), room.qr(n), room.joinUrl(n), room.pad(n, { title?, color?, highlight?: ids (glow and make the phone vibrate briefly (Android only); disabled wins over highlight), disabled?: ids, vibrate?: ms }), room.kick(n), room.send(n, data), room.broadcast(data), room.on('join'|'leave'|'message'|'status'|'error', fn) → unsubscribe, room.close().
+
+## Client API (custom controllers, remote players)
+
+```js
+import { join } from '/joinstick/client.js';
+const pad = await join({ room: 'KQZX', slot: 1, name: 'Ana' }); // slot omitted = first free
+pad.setInput({ x, y, buttons: { a: true } }); pad.send(data); pad.on('message'|'pad'|'error'|'status', fn); pad.leave();
+```
+
+## Error codes
+
+room-not-found, slot-taken (with free: [slots]), bad-slot, bad-message (with message), replaced, kicked, room-closed (host gone 60 s), version, server-full (1000 rooms, or 20 from one address), rate-limited (20 failed joins from one address in a minute); client-only: unreachable.
+
+## Pitfalls
+
+- First run: allow Node through the OS firewall prompt.
+- Guest/hotel Wi-Fi with client isolation blocks phones: use a hotspot or a tunnel.
+- Plain HTTP: no wake lock, no iOS fullscreen. Host-driven vibrate (room.pad vibrate/highlight) works only on Android.
+- An HTTPS game page cannot reach a ws:// LAN server (mixed content): serve the game with --static or put both behind HTTPS.
+- Docker breaks LAN IP detection: use --public-url.
+- Remote play: `cloudflared tunnel --url http://localhost:3000`, then start Joinstick with `--public-url https://<name>.trycloudflare.com`. 4-letter room codes are guessable on a public URL; there is no other authentication.
+- --static refuses dotfiles and has no HTTP Range support (Safari video/audio needs Range: serve media elsewhere).
+- Embedding with attach(server): call it after registering your own 'request' listeners.
+- A pad in a background browser tab leaves its slot (lock-screen behavior).
+
+## Testing without phones
+
+In the game tab's console (or a Node 22+ script importing joinstick/public/client.js with `server: 'http://localhost:3000'`):
+
+```js
+const { join } = await import('/joinstick/client.js');
+const pad = await join({ room: room.code, slot: 1 });
+pad.setInput({ x: 1 });                         // hold right
+pad.setInput({ x: 1, buttons: { a: true } });   // press A
+pad.setInput({ x: 1, buttons: { a: false } });  // release: input(1).pressed.a seen once
+pad.leave();                                    // game should pause
+```
+
+## Don't
+
+- Don't use innerHTML with player names or network data; use textContent.
+- Don't read held state for one-shot actions; use pressed.
+- Don't call input(n) twice per frame for the same slot.

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "joinstick",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Use phones as gamepads for HTML5 browser games: scan a QR, play. Self-hosted and open source, no accounts, no app install.",
+  "license": "MIT",
+  "author": {
+    "name": "Rafa Prats",
+    "url": "https://github.com/raprav"
+  },
+  "homepage": "https://github.com/raprav/joinstick#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raprav/joinstick.git"
+  },
+  "bugs": {
+    "url": "https://github.com/raprav/joinstick/issues"
+  },
+  "keywords": [
+    "gamepad",
+    "controller",
+    "phone-controller",
+    "mobile-controller",
+    "phone-gamepad",
+    "virtual-gamepad",
+    "touch-controls",
+    "local-multiplayer",
+    "multiplayer",
+    "party-game",
+    "couch-coop",
+    "smartphone-controller",
+    "game-controller",
+    "qr",
+    "qr-code",
+    "websocket",
+    "html5",
+    "html5-game",
+    "browser-game",
+    "self-hosted"
+  ],
+  "type": "module",
+  "main": "src/server.js",
+  "types": "src/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/server.d.ts",
+      "default": "./src/server.js"
+    },
+    "./host": {
+      "types": "./public/host.d.ts",
+      "default": "./public/host.js"
+    },
+    "./client": {
+      "types": "./public/client.d.ts",
+      "default": "./public/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "joinstick": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "public",
+    "llms.txt",
+    "AGENTS.md",
+    "PROTOCOL.md",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "uqr": "^0.1.3",
+    "ws": "^8.22.0"
+  }
+}

package/public/client.d.ts

@@ -0,0 +1,88 @@
+import type { Layout } from './host.js';
+
+export type { Layout } from './host.js';
+
+export interface PadState {
+  title?: string;
+  color?: string;
+  highlight?: string[];
+  disabled?: string[];
+}
+
+export interface PadPatch extends PadState {
+  vibrate?: number;
+}
+
+export type ErrorCode =
+  | 'room-not-found'
+  | 'slot-taken'
+  | 'bad-slot'
+  | 'bad-message'
+  | 'replaced'
+  | 'kicked'
+  | 'room-closed'
+  | 'version'
+  | 'rate-limited'
+  | 'unreachable';
+
+export interface JoinError {
+  code: ErrorCode;
+  message?: string;
+  /** With 'slot-taken': the slots that are free right now. */
+  free?: number[];
+}
+
+export type Status = 'connecting' | 'connected' | 'reconnecting' | 'closed';
+
+export interface PadInput {
+  /** -1 (left) .. 1 (right). */
+  x?: number;
+  /** -1 (up) .. 1 (down). */
+  y?: number;
+  /** Full held state, e.g. { a: true, b: false }. */
+  buttons?: Record<string, boolean>;
+}
+
+export interface PadEvents {
+  /** Data sent by the host with room.send() or room.broadcast(). */
+  message: [data: unknown];
+  /** The host changed this pad. `state` is the merged state, `patch` what changed (may include vibrate). */
+  pad: [state: PadState, patch: PadPatch];
+  /** Fatal error after joining (kicked, room-closed, replaced, slot-taken on rejoin...). The pad is closed. */
+  error: [error: JoinError];
+  status: [status: Status];
+}
+
+export interface JoinOptions {
+  /** Room code, case-insensitive. */
+  room: string;
+  /** 1-based slot. Omit to take the first free one. */
+  slot?: number;
+  /** Player name shown to the host, at most 20 chars. */
+  name?: string;
+  /** Joinstick server URL. Default: where client.js was loaded from. */
+  server?: string;
+}
+
+export interface Pad {
+  readonly room: string;
+  readonly slot: number;
+  /** Layout chosen by the host. Render labels with textContent only. */
+  readonly layout: Layout & Required<Pick<Layout, 'stick' | 'buttons'>>;
+  readonly state: PadState;
+  readonly status: Status;
+  /** Send the full current state. Cheap to call often: unchanged state is not resent. */
+  setInput(input: PadInput): void;
+  /** Send any JSON value to the host (arrives as room.on('message')). */
+  send(data: unknown): void;
+  on<E extends keyof PadEvents>(event: E, fn: (...args: PadEvents[E]) => void): () => void;
+  /** Leave the slot for good (no auto-rejoin). The host sees reason 'left'. */
+  leave(): void;
+}
+
+/**
+ * Join a room. Reconnects and rejoins the same slot by itself (network blips,
+ * phone locked, server restart). Rejects with an Error carrying a JoinError's
+ * fields (`code`, `free`) if the first join fails.
+ */
+export function join(options: JoinOptions): Promise<Pad>;