joinstick 0.0.0-stage → 0.2.0

package/llms.txt

@@ -0,0 +1,102 @@
+# Joinstick
+
+> Turn phones into gamepads for browser games. The game page (host) shows one QR code for everyone (or one per slot); scanning it opens a controller page on the phone in the first free slot. 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), `--client-ip-header <name>` (CLIENT_IP_HEADER; behind a trusted proxy, the header with the visitor's address for the per-address limits).
+
+## 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()}> and the text room.joinUrl(): each phone that scans it gets the first free slot (room.qr(n) for a fixed slot)
+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?) (no n: first free slot), 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.2.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>;

package/public/client.js

@@ -0,0 +1,182 @@
+// Joinstick client SDK: join a room as a player from a phone (or any browser).
+// The default pad page is built on this. Types: client.d.ts. Protocol: PROTOCOL.md.
+import { link } from './link.js';
+
+const REJOIN_WINDOW = 60_000;
+const FATAL = new Set(['room-not-found', 'slot-taken', 'bad-slot', 'replaced', 'kicked', 'room-closed', 'version', 'rate-limited']);
+const memory = new Map();
+
+function storage() {
+  if (typeof window === 'undefined') return null;
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function getItem(key) {
+  try {
+    return storage()?.getItem(key) ?? memory.get(key) ?? null;
+  } catch {
+    return memory.get(key) ?? null;
+  }
+}
+
+function setItem(key, value) {
+  memory.set(key, value);
+  try {
+    storage()?.setItem(key, value);
+  } catch {}
+}
+
+// crypto.randomUUID() is missing on plain-HTTP LAN origins; getRandomValues is not.
+function newToken() {
+  return Array.from(crypto.getRandomValues(new Uint8Array(16)), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+const NEUTRAL = { t: 'input', x: 0, y: 0, b: {} };
+
+export function join({ room: roomCode, slot, name, server } = {}) {
+  const base = (server ?? new URL('..', import.meta.url).href).replace(/\/+$/, '');
+  const room = String(roomCode ?? '').trim().toUpperCase();
+  let token = (slot && getItem(`joinstick:${room}:${slot}`)) || newToken();
+  let layout = null;
+  let padState = {};
+  let status = 'connecting';
+  let ready = false;
+  let closed = false;
+  let hidden = false;
+  let lostAt = 0;
+  let input = NEUTRAL;
+  let lastSent = '';
+  const listeners = {};
+
+  function emit(ev, ...args) {
+    for (const fn of listeners[ev] ?? []) {
+      try {
+        fn(...args);
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+
+  function setStatus(s) {
+    if (s !== status) emit('status', (status = s));
+  }
+
+  function sendInput(force) {
+    const s = JSON.stringify(input);
+    if (s === lastSent && !force) return;
+    lastSent = s;
+    conn.send(input);
+  }
+
+  let resolveJoin, rejectJoin;
+  const joined = new Promise((res, rej) => ((resolveJoin = res), (rejectJoin = rej)));
+
+  const conn = link(base.replace(/^http/, 'ws') + '/joinstick/ws', {
+    open: () => conn.send({ t: 'join', v: 1, room, slot, token, name }),
+    down() {
+      if (!ready) return end({ code: 'unreachable', message: `Cannot reach the Joinstick server at ${base}` });
+      lostAt ||= Date.now();
+      setStatus('reconnecting');
+      if (!hidden) conn.retry();
+    },
+    message(m) {
+      if (m.t === 'joined') {
+        slot = m.slot;
+        layout = m.layout;
+        padState = { ...m.pad };
+        setItem(`joinstick:${room}:${slot}`, token);
+        conn.up();
+        lostAt = 0;
+        // Always send the current state first: the host treats it as the
+        // baseline, so a button held through a rejoin is not a new press.
+        sendInput(true);
+        if (!ready) resolveJoin(pad);
+        ready = true;
+        emit('pad', padState, {});
+        setStatus('connected');
+      } else if (m.t === 'pad') {
+        const { vibrate, ...keep } = m.patch;
+        padState = { ...padState, ...keep };
+        emit('pad', padState, m.patch);
+      } else if (m.t === 'message') {
+        emit('message', m.data);
+      } else if (m.t === 'error') {
+        // After a server restart the host needs a moment to recreate the room.
+        if (m.code === 'room-not-found' && ready && Date.now() - lostAt < REJOIN_WINDOW) return conn.drop();
+        if (FATAL.has(m.code)) return end(m);
+        console.warn('joinstick:', m.code, m.message ?? '');
+      }
+    },
+  });
+
+  function end(err) {
+    if (closed) return;
+    closed = true;
+    conn.stop(1000);
+    setStatus('closed');
+    if (!ready) return rejectJoin(Object.assign(new Error(`Joinstick: ${err.code}`), err));
+    emit('error', err);
+  }
+
+  // A locked or backgrounded phone leaves at once (the game can pause) and
+  // rejoins the same slot when it comes back.
+  function suspend() {
+    if (!ready || closed || hidden) return;
+    hidden = true;
+    input = NEUTRAL;
+    conn.drop(4001);
+  }
+
+  function resume() {
+    if (!hidden || closed) return;
+    hidden = false;
+    conn.connect();
+  }
+
+  if (typeof document !== 'undefined') {
+    document.addEventListener('visibilitychange', () => (document.hidden ? suspend() : resume()));
+    addEventListener('pagehide', suspend);
+    addEventListener('pageshow', resume);
+  }
+
+  const pad = {
+    get room() {
+      return room;
+    },
+    get slot() {
+      return slot;
+    },
+    get layout() {
+      return layout;
+    },
+    get state() {
+      return padState;
+    },
+    get status() {
+      return status;
+    },
+    setInput({ x = 0, y = 0, buttons = {} } = {}) {
+      input = { t: 'input', x, y, b: buttons };
+      sendInput();
+    },
+    send: (data) => conn.send({ t: 'msg', data }),
+    on(ev, fn) {
+      (listeners[ev] ??= new Set()).add(fn);
+      return () => listeners[ev].delete(fn);
+    },
+    leave() {
+      if (closed) return;
+      closed = true;
+      conn.stop(1000);
+      setStatus('closed');
+    },
+  };
+
+  conn.connect();
+  return joined;
+}

package/public/host.d.ts

@@ -0,0 +1,116 @@
+/** Controller layout rendered by the default pad page. Validated by the server. */
+export interface Layout {
+  /** 'dpad' (default) shows an 8-way d-pad on the left; 'none' hides it. */
+  stick?: 'dpad' | 'none';
+  /** At most 8 buttons, system buttons included. */
+  buttons?: Button[];
+  /**
+   * 'landscape' (default): a phone held upright shows the pad rotated, so the
+   * player turns it sideways (works with the rotation lock on). 'portrait'
+   * does the opposite; 'any' follows the phone.
+   */
+  orientation?: 'landscape' | 'portrait' | 'any';
+  /**
+   * How the pad places the gameplay buttons. 'grid' (default): rows and columns.
+   * 'diamond': the first four as face buttons (bottom, left, right, top), the
+   * rest beside them. 'arc': the first button big under the thumb, the rest
+   * fanned around it.
+   */
+  arrangement?: 'grid' | 'diamond' | 'arc';
+  /** Short local vibration on every press and d-pad direction change. Default true. */
+  haptics?: boolean;
+}
+
+export interface Button {
+  /** Key in `input(n).buttons`. Must match /^[A-Za-z0-9_-]{1,16}$/, be unique and not be an Object.prototype name (e.g. 'constructor'). */
+  id: string;
+  /** Text on the button, at most 8 chars. Defaults to the id. */
+  label?: string;
+  /** Hex color, /^#[0-9a-f]{3,8}$/i. */
+  color?: string;
+  /** 'large': a bigger round button. 'wide': a long bar under the other buttons (good for a held action). */
+  size?: 'large' | 'wide';
+  /** Tap feedback length in ms (0-100, 0 = none). Default 10. */
+  haptic?: number;
+  /** A small pill in the pad's top bar (START, MENU...), away from the thumbs. Reports like any other button. */
+  system?: boolean;
+}
+
+/** Change what one pad shows. Every field is optional; omitted fields keep their value. */
+export interface PadPatch {
+  /** Shown in the pad header, at most 20 chars. '' clears it. */
+  title?: string;
+  /** Accent color of the pad (hex). */
+  color?: string;
+  /** Button ids that glow and make the phone vibrate briefly (Android only). Disabled wins over highlight. [] clears. */
+  highlight?: string[];
+  /** Button ids that cannot be pressed. [] clears. */
+  disabled?: string[];
+  /** Vibrate the phone for this many ms (0-2000). One-shot, Android only. */
+  vibrate?: number;
+}
+
+export interface Input {
+  /** -1 (left) .. 1 (right). The d-pad gives -1, 0 or 1. */
+  x: number;
+  /** -1 (up) .. 1 (down). The d-pad gives -1, 0 or 1. */
+  y: number;
+  /** Held state of every layout button. Use for movement/charging, not one-shot actions. */
+  buttons: Record<string, boolean>;
+  /** Buttons that went down since the previous input(n) call. Latched and cleared on read: use for attacks, jumps, menu selects. */
+  pressed: Record<string, true>;
+}
+
+export type LeaveReason = 'left' | 'disconnected' | 'timeout' | 'kicked';
+export type Status = 'connecting' | 'connected' | 'reconnecting' | 'closed';
+
+export interface HostEvents {
+  join: { slot: number; name: string; rejoin: boolean };
+  leave: { slot: number; reason: LeaveReason };
+  message: { slot: number; data: unknown };
+  status: Status;
+  /** Server errors after host() resolved. 'replaced' (another tab resumed this room, e.g. a duplicated tab) also closes this room object. */
+  error: { code: string; message?: string };
+}
+
+export interface HostOptions {
+  /** Number of player slots, 1-8. Default 2. */
+  slots?: number;
+  /** Default: d-pad plus buttons 'a' and 'b'. */
+  layout?: Layout;
+  /** Joinstick server URL, e.g. 'http://localhost:3000'. Default: where host.js was loaded from. Required when you bundle this file. */
+  server?: string;
+}
+
+export interface Room {
+  /** 4-letter room code, e.g. 'KQZX'. */
+  readonly code: string;
+  readonly slots: number;
+  readonly status: Status;
+  /** Current input of slot n (1-based). Never undefined: neutral when the slot is empty. Clears `pressed`. Throws RangeError for a bad slot. */
+  input(n: number): Input;
+  connected(n: number): boolean;
+  /** URL of an SVG QR code that opens the pad for slot n. Use as <img src>. Without n, every phone that scans it gets the first free slot. */
+  qr(n?: number): string;
+  /** The URL inside the QR. Show it as text under the QR. Without n: the first-free-slot link. */
+  joinUrl(n?: number): string;
+  pad(n: number, patch: PadPatch): void;
+  /** Disconnect the phone in slot n; the slot becomes free. */
+  kick(n: number): void;
+  /** Send any JSON value to the phone in slot n. */
+  send(n: number, data: unknown): void;
+  broadcast(data: unknown): void;
+  /** Returns a function that removes the listener. */
+  on<E extends keyof HostEvents>(event: E, fn: (arg: HostEvents[E]) => void): () => void;
+  /** Disconnect and forget the room (the server drops it 60 s later). */
+  close(): void;
+}
+
+/**
+ * Create a room, or resume the one stored in sessionStorage (same server and
+ * slot count) after a page reload. Resuming resets every pad's state (title,
+ * color, highlight, disabled). Pads already connected are visible through
+ * connected(n) when this resolves; no 'join' event is emitted for them.
+ * Rejects if the server is unreachable or refuses the options.
+ */
+export function host(options?: HostOptions): Promise<Room>;