joinstick 0.0.0-stage → 0.1.0

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>. */
+  qr(n: number): string;
+  /** The URL inside the QR. Show it as text under the QR. */
+  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>;

package/public/host.js

@@ -0,0 +1,195 @@
+// Joinstick host SDK: create a room, show one QR per player slot, poll input.
+// Plain ESM, no dependencies. Types: host.d.ts. Protocol: PROTOCOL.md.
+import { link } from './link.js';
+
+const STORE_KEY = 'joinstick:host';
+
+function storage() {
+  try {
+    return globalThis.sessionStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function host({ slots = 2, layout, server } = {}) {
+  const base = (server ?? new URL('..', import.meta.url).href).replace(/\/+$/, '');
+  const store = storage();
+  let saved = null;
+  try {
+    saved = JSON.parse(store?.getItem(STORE_KEY) ?? 'null');
+  } catch {}
+  // A stored room is resumed only by the same server and slot count.
+  if (saved?.server !== base || saved?.slots !== slots) saved = null;
+
+  let code = saved?.room ?? null;
+  let hostToken = saved?.hostToken ?? null;
+  let joinBase = base;
+  let buttonIds = [];
+  let status = 'connecting';
+  let ready = false;
+  let resumedOnce = false;
+  const listeners = {};
+  const padState = {};
+  const state = Array.from({ length: slots }, () => ({ connected: false, name: '', x: 0, y: 0, buttons: {}, pressed: {}, baseline: true }));
+
+  function emit(ev, arg) {
+    for (const fn of listeners[ev] ?? []) {
+      try {
+        fn(arg);
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+
+  function setStatus(s) {
+    if (s !== status) emit('status', (status = s));
+  }
+
+  function at(n) {
+    if (!Number.isInteger(n) || n < 1 || n > slots) throw new RangeError(`slot must be an integer 1-${slots} (slots are 1-based)`);
+    return state[n - 1];
+  }
+
+  function neutral(s) {
+    s.x = 0;
+    s.y = 0;
+    s.buttons = Object.fromEntries(buttonIds.map((id) => [id, false]));
+    s.pressed = {};
+    s.baseline = true; // the next input sets held state without "pressed" edges
+  }
+
+  function leave(n, reason) {
+    const s = state[n - 1];
+    neutral(s);
+    if (!s.connected) return;
+    s.connected = false;
+    emit('leave', { slot: n, reason });
+  }
+
+  function join(n, name, rejoin) {
+    const s = state[n - 1];
+    neutral(s);
+    s.connected = true;
+    s.name = name;
+    emit('join', { slot: n, name, rejoin });
+  }
+
+  return new Promise((resolve, reject) => {
+    const conn = link(base.replace(/^http/, 'ws') + '/joinstick/ws', {
+      // The first create of this host() call resets pad state: a reloaded game
+      // starts from scratch, while in-session reconnects keep it.
+      open: () => conn.send({ t: 'create', v: 1, slots, layout, room: code, hostToken, resetPads: !resumedOnce }),
+      down() {
+        for (let n = 1; n <= slots; n++) leave(n, 'disconnected');
+        if (!ready) return fail(new Error(`Cannot reach the Joinstick server at ${base}`));
+        setStatus('reconnecting');
+        conn.retry();
+      },
+      message(m) {
+        try {
+          handle(m);
+        } catch (err) {
+          if (!ready) return fail(err);
+          console.error(err);
+        }
+      },
+    });
+
+    function handle(m) {
+      if (m.t === 'created') {
+        resumedOnce = true;
+        code = m.room;
+        hostToken = m.hostToken;
+        joinBase = m.joinBase;
+        buttonIds = m.layout.buttons.map((b) => b.id);
+        try {
+          store?.setItem(STORE_KEY, JSON.stringify({ server: base, slots, room: code, hostToken }));
+        } catch {}
+        conn.up();
+        for (const s of state) neutral(s);
+        for (const s of m.slots) if (s.connected) join(s.slot, s.name, true);
+        // The server forgets pad state if it restarted; send ours again.
+        for (const [n, patch] of Object.entries(padState)) conn.send({ t: 'pad', slot: Number(n), patch });
+        setStatus('connected');
+        if (!ready) resolve(room);
+        ready = true;
+      } else if (m.t === 'join') {
+        join(m.slot, m.name, m.rejoin);
+      } else if (m.t === 'leave') {
+        leave(m.slot, m.reason);
+      } else if (m.t === 'input') {
+        const s = state[m.slot - 1];
+        if (!s) return;
+        const buttons = {};
+        for (const id of buttonIds) buttons[id] = Object.hasOwn(m.b, id) && m.b[id] === true;
+        if (!s.baseline) for (const id of buttonIds) if (buttons[id] && !s.buttons[id]) s.pressed[id] = true;
+        s.baseline = false;
+        s.x = m.x;
+        s.y = m.y;
+        s.buttons = buttons;
+      } else if (m.t === 'message') {
+        emit('message', { slot: m.slot, data: m.data });
+      } else if (m.t === 'error') {
+        if (!ready) return fail(Object.assign(new Error(`Joinstick: ${m.code}${m.message ? ` (${m.message})` : ''}`), { code: m.code }));
+        emit('error', { code: m.code, message: m.message });
+        if (m.code === 'replaced') return close(); // another tab took this room
+        if (!listeners.error?.size) console.warn('joinstick:', m.code, m.message ?? '');
+      }
+    }
+
+    function fail(err) {
+      close();
+      reject(err);
+    }
+
+    function close() {
+      conn.stop(1000);
+      for (let n = 1; n <= slots; n++) leave(n, 'disconnected');
+      setStatus('closed');
+    }
+
+    const room = {
+      get code() {
+        return code;
+      },
+      get slots() {
+        return slots;
+      },
+      get status() {
+        return status;
+      },
+      input(n) {
+        const s = at(n);
+        const out = { x: s.x, y: s.y, buttons: { ...s.buttons }, pressed: s.pressed };
+        s.pressed = {};
+        return out;
+      },
+      connected: (n) => at(n).connected,
+      qr: (n) => at(n) && `${base}/joinstick/qr.svg?room=${code}&slot=${n}`,
+      joinUrl: (n) => at(n) && `${joinBase}/j/${code}/${n}`,
+      pad(n, patch) {
+        at(n);
+        const { vibrate, ...keep } = patch;
+        padState[n] = { ...padState[n], ...keep };
+        conn.send({ t: 'pad', slot: n, patch });
+      },
+      kick: (n) => at(n) && conn.send({ t: 'kick', slot: n }),
+      send: (n, data) => at(n) && conn.send({ t: 'send', slot: n, data }),
+      broadcast: (data) => conn.send({ t: 'send', slot: null, data }),
+      on(ev, fn) {
+        (listeners[ev] ??= new Set()).add(fn);
+        return () => listeners[ev].delete(fn);
+      },
+      close() {
+        try {
+          store?.removeItem(STORE_KEY);
+        } catch {}
+        close();
+      },
+    };
+
+    conn.connect();
+  });
+}

package/public/link.js

@@ -0,0 +1,73 @@
+// Shared WebSocket plumbing for host.js and client.js:
+// JSON messages, ping/pong, a silence watchdog and reconnect backoff.
+
+const SILENCE = 5000;
+
+export function link(url, { open, message, down }) {
+  let ws = null;
+  let lastMsg = 0;
+  let attempts = 0;
+  let retryTimer;
+  let stopped = false;
+
+  function connect() {
+    clearTimeout(retryTimer);
+    detach(); // never two sockets at once
+    lastMsg = Date.now();
+    ws = new WebSocket(url);
+    ws.onopen = open;
+    ws.onmessage = (e) => {
+      lastMsg = Date.now();
+      let m;
+      try {
+        m = JSON.parse(e.data);
+      } catch {
+        return;
+      }
+      if (m.t === 'ping') send({ t: 'pong' });
+      else message(m);
+    };
+    // Some runtimes (Node 22) fire 'error' without 'close' on a refused connection.
+    ws.onclose = ws.onerror = () => drop();
+  }
+
+  function detach(code) {
+    if (!ws) return false;
+    ws.onopen = ws.onmessage = ws.onclose = ws.onerror = null;
+    try {
+      ws.close(code);
+    } catch {}
+    ws = null;
+    return true;
+  }
+
+  // Close the socket right away (a dead connection can take long to report
+  // 'close') and tell the owner it is down. Also cancels a pending retry.
+  function drop(code) {
+    clearTimeout(retryTimer);
+    if (detach(code) && !stopped) down();
+  }
+
+  function send(m) {
+    if (ws?.readyState === 1) ws.send(JSON.stringify(m));
+  }
+
+  const watchdog = setInterval(() => {
+    if (ws && Date.now() - lastMsg > SILENCE) drop();
+  }, 1000);
+  watchdog.unref?.();
+
+  return {
+    send,
+    connect,
+    drop,
+    up: () => (attempts = 0),
+    retry: () => (retryTimer = setTimeout(connect, Math.min(5000, 250 * 2 ** attempts++))),
+    stop(code) {
+      stopped = true;
+      clearInterval(watchdog);
+      clearTimeout(retryTimer);
+      drop(code);
+    },
+  };
+}