joinstick 0.1.0 → 0.2.0

package/AGENTS.md

@@ -1,9 +1,9 @@
 # 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:
+**host**) shows a QR code; each player scans it and their phone becomes a
+controller in the first free slot (per-slot QR codes exist too). 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
@@ -25,7 +25,7 @@ something else (see "Game served elsewhere" below).
 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
+showQr(room.qr(), room.joinUrl()); // <img src=qr> + the URL as text; each phone gets the first free slot (room.qr(n): a fixed slot)
 
 function tick() {
   for (let n = 1; n <= room.slots; n++) {
@@ -185,8 +185,8 @@ 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.qr(n?)               // URL of an SVG QR code for <img src>; no n: first free slot
+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)
@@ -218,7 +218,7 @@ new tab resumes the same room and the original tab gets an `error` event with
 ## 8. CLI and embedding
 
 ```
-joinstick [--port 3000] [--static ./dir] [--public-url URL]
+joinstick [--port 3000] [--static ./dir] [--public-url URL] [--client-ip-header NAME]
 ```
 
 | Flag | Env | Purpose |
@@ -226,6 +226,7 @@ joinstick [--port 3000] [--static ./dir] [--public-url URL]
 | `--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. |
+| `--client-ip-header <name>` | `CLIENT_IP_HEADER` | Behind a reverse proxy: the header it sets to the visitor's address (`fly-client-ip`, `x-real-ip`; first value used). The 20-rooms and failed-join limits per address then use it. Never set it without a proxy that overwrites the header: clients can fake it. `attach()` option: `clientIpHeader`. |
 
 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
@@ -254,8 +255,8 @@ 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`.
+`/joinstick/client.js` (CORS `*`); pad page `/j`, `/j/ROOM` (first free slot) and `/j/ROOM/SLOT`; QR
+`/joinstick/qr.svg?room=&slot=` (existing rooms only, slot optional); `/llms.txt`.
 
 ### Game served elsewhere (Vite, another port)
 

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project are documented here. The format follows
 [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.
 
+## [Unreleased]
+
+## [0.2.0] - 2026-10-16
+
+### Added
+
+- One QR for everyone: `room.qr()` and `room.joinUrl()` without a slot give a
+  link that puts each phone in the first free slot (`/j/ROOM`);
+  `/joinstick/qr.svg` accepts a missing `slot`.
+- `examples/paint-party`: a party game for 1-8 phones.
+- `--client-ip-header <name>` (`CLIENT_IP_HEADER`, `attach()` option
+  `clientIpHeader`): behind a reverse proxy, the per-address room cap and
+  failed-join limit use the header the proxy sets instead of the proxy's
+  address. Off by default, since clients can send the header themselves.
+
+### Changed
+
+- The player number on the pad's join form is optional; blank takes the first
+  free slot.
+- The pad's top bar is tinted and underlined in the pad color, so players can
+  match their phone to the screen at a glance.
+
+### Fixed
+
+- `--static` redirects a directory requested without its trailing slash
+  (`/demo/game` -> `/demo/game/`, query kept) instead of answering 404.
+
 ## [0.1.0] - 2026-10-04
 
 First public release.
@@ -32,4 +59,6 @@ First public release.
 - JSON/WebSocket protocol v1 (PROTOCOL.md), AGENTS.md for coding agents,
   TypeScript declarations, Dockerfile.
 
+[Unreleased]: https://github.com/raprav/joinstick/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/raprav/joinstick/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/raprav/joinstick/releases/tag/v0.1.0

package/PROTOCOL.md

@@ -100,8 +100,10 @@ The pad gets fatal `kicked`; the host gets `leave` with reason `kicked`.
 {"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.
+Pads join at `${joinBase}/j/${room}/${slot}`, or at `${joinBase}/j/${room}` to
+get the first free slot. The QR for a slot is
+`/joinstick/qr.svg?room=KQZX&slot=1` on the Joinstick server; without `slot`
+it encodes the slot-less link.
 
 ### `join`
 

package/README.md

@@ -10,7 +10,12 @@ for local multiplayer and party games on a laptop or TV.
 [![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>
+<p align="center"><a href="https://joinstick.fly.dev/demo/paint-party"><img src="https://raw.githubusercontent.com/raprav/joinstick/main/docs/hero.png" alt="Left: Paint Party on a TV mid-round, four paint blobs covering the floor and one QR code in the corner that every player scans. Right: a phone held sideways showing player 1's orange pad with a d-pad and BOMB and DASH buttons." width="800"></a></p>
+
+**[Live demo: Paint Party](https://joinstick.fly.dev/demo/paint-party)**. Open it on a big screen and scan the QR
+with phones: one QR for everyone, drop in or out anytime, 1-8 players, haptics
+on Android. Its source is a single file in
+[`examples/paint-party`](examples/paint-party) that uses only the public SDK.
 
 ## Quick start
 
@@ -23,7 +28,7 @@ Save this as `my-game/index.html`:
 <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
+  document.getElementById('qr').src = room.qr();  // every player 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
@@ -42,6 +47,10 @@ 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).
+[`examples/paint-party`](examples/paint-party) is a party game for 1-8 phones
+that join and leave at any time through one QR code
+([play it live](https://joinstick.fly.dev/demo/paint-party): open it on a big
+screen, then scan the QR with phones).
 
 ### Using a bundler or your own dev server
 
@@ -73,8 +82,9 @@ needs HTTPS too (see Self-hosting).
                                 └──────────────────┘
 ```
 
-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
+The game creates a room (`KQZX`) with up to 8 player slots. One QR code opens
+`/j/KQZX` on any phone, which takes the first free slot (`/j/KQZX/<slot>` asks
+for a specific one). 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.
@@ -130,7 +140,7 @@ a button, tap another). Full schema in [AGENTS.md](AGENTS.md#5-layout).
 |---|---|
 | `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.qr(n?)`, `room.joinUrl(n?)` | QR image URL and plain join link for player `n`. Without `n`: one link for everyone, each phone gets the first free slot. |
 | `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. |
@@ -149,7 +159,7 @@ phones): [AGENTS.md](AGENTS.md).
 ## CLI
 
 ```
-joinstick [--port 3000] [--static ./dir] [--public-url URL] [--version]
+joinstick [--port 3000] [--static ./dir] [--public-url URL] [--client-ip-header NAME] [--version]
 ```
 
 | Flag | Env | |
@@ -157,6 +167,7 @@ joinstick [--port 3000] [--static ./dir] [--public-url URL] [--version]
 | `--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. |
+| `--client-ip-header <name>` | `CLIENT_IP_HEADER` | Header a reverse proxy sets to the visitor's address (`fly-client-ip`, `x-real-ip`). The per-address limits use it instead of the proxy's address. Only set it behind a proxy that overwrites the header. |
 | `-v`, `--version` | | Print the version. |
 
 ## Self-hosting
@@ -168,7 +179,9 @@ joinstick [--port 3000] [--static ./dir] [--public-url URL] [--version]
   `/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):
+  together unless you pass `--client-ip-header` with a header your proxy
+  overwrites with the visitor's address (Fly.io: `fly-client-ip`).
+  With Caddy (which passes WebSockets through by default):
 
   ```
   your.domain {

package/llms.txt

@@ -1,19 +1,19 @@
 # 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.
+> 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).
+`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(n)}> and the text room.joinUrl(n) for n = 1..room.slots
+// 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
@@ -56,7 +56,7 @@ A locked/backgrounded phone leaves immediately and rejoins its slot when back (j
 
 ## 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().
+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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "joinstick",
-  "version": "0.1.0",
+  "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": {

package/public/host.d.ts

@@ -90,10 +90,10 @@ export interface Room {
   /** 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;
+  /** 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;

package/public/host.js

@@ -52,6 +52,11 @@ export function host({ slots = 2, layout, server } = {}) {
     return state[n - 1];
   }
 
+  // '/n' or '&slot=n' for a valid slot; no n: the phone gets the first free slot.
+  function slotPart(n, prefix) {
+    return n === undefined ? '' : (at(n), `${prefix}${n}`);
+  }
+
   function neutral(s) {
     s.x = 0;
     s.y = 0;
@@ -167,8 +172,8 @@ export function host({ slots = 2, layout, server } = {}) {
         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}`,
+      qr: (n) => `${base}/joinstick/qr.svg?room=${code}${slotPart(n, '&slot=')}`,
+      joinUrl: (n) => `${joinBase}/j/${code}${slotPart(n, '/')}`,
       pad(n, patch) {
         at(n);
         const { vibrate, ...keep } = patch;

package/public/pad.css

@@ -61,7 +61,9 @@ body { position: fixed; inset: 0; }
   align-items: center;
   gap: 10px;
   padding: 8px 16px 8px 24px;
-  border-bottom: 1px solid var(--line);
+  border-bottom: 4px solid var(--accent); /* the player's color, visible from across the room */
+  background: var(--panel);
+  background: color-mix(in srgb, var(--accent) 22%, var(--bg));
 }
 .side { display: flex; align-items: center; gap: 10px; min-width: 0; }
 .side.end { justify-content: flex-end; }

package/public/pad.html

@@ -48,8 +48,8 @@
   <label>Room code
     <input name="room" maxlength="4" autocomplete="off" autocapitalize="characters" autocorrect="off" spellcheck="false" required pattern="[A-Za-z]{4}" placeholder="KQZX">
   </label>
-  <label>Player number
-    <input name="slot" type="number" inputmode="numeric" min="1" max="8" value="1" required>
+  <label>Player number (optional)
+    <input name="slot" type="number" inputmode="numeric" min="1" max="8" placeholder="Any free">
   </label>
   <button class="primary">Join</button>
 </form>

package/public/pad.js

@@ -30,7 +30,7 @@ function showError(err, room, slot) {
   $('pad').hidden = true;
   const free = err.free ?? [];
   const messages = {
-    'slot-taken': [`Player ${slot} is taken`, free.length ? 'Pick a free spot:' : 'The game is full.', free.map((n) => [`Player ${n}`, go(`/j/${room}/${n}`)])],
+    'slot-taken': [slot ? `Player ${slot} is taken` : 'No free spot', free.length ? 'Pick a free spot:' : 'The game is full.', free.map((n) => [`Player ${n}`, go(`/j/${room}/${n}`)])],
     'room-not-found': ['Room not found', `There is no game with code ${room}. Check the code on the game screen.`, [['Enter another code', go('/j')]]],
     'bad-slot': ['No such player', `Room ${room} has no player ${slot}.`, [['Take a free spot', go(`/j/${room}`)]]],
     kicked: ['You were removed', 'The game disconnected this controller.', [['Join again', reload]]],
@@ -52,7 +52,8 @@ function showForm() {
   form.hidden = false;
   form.onsubmit = (e) => {
     e.preventDefault();
-    location.assign(`/j/${form.room.value.trim().toUpperCase()}/${form.slot.value}`);
+    const slot = form.slot.value; // blank: the first free slot
+    location.assign(`/j/${form.room.value.trim().toUpperCase()}${slot ? `/${slot}` : ''}`);
   };
 }
 

package/src/cli.js

@@ -15,6 +15,10 @@ Options:
   --public-url <url>  Base URL phones should open, e.g. https://abc.trycloudflare.com
                       (default: $PUBLIC_URL, else the address the game page was
                       opened with, else the detected LAN address)
+  --client-ip-header <name>
+                      Header your reverse proxy sets to the visitor's address,
+                      e.g. fly-client-ip or x-real-ip (default: $CLIENT_IP_HEADER).
+                      Only behind a proxy that sets it: clients can fake it.
   -v, --version       Print the version
   -h, --help          Show this help
 `;
@@ -26,6 +30,7 @@ try {
       port: { type: 'string' },
       static: { type: 'string' },
       'public-url': { type: 'string' },
+      'client-ip-header': { type: 'string' },
       help: { type: 'boolean', short: 'h' },
       version: { type: 'boolean', short: 'v' },
     },
@@ -46,7 +51,8 @@ if (args.help) {
 const port = Number(args.port ?? process.env.PORT ?? 3000);
 const publicUrl = args['public-url'] ?? process.env.PUBLIC_URL;
 const server = http.createServer();
-attach(server, { static: args.static, publicUrl });
+const clientIpHeader = args['client-ip-header'] ?? process.env.CLIENT_IP_HEADER;
+attach(server, { static: args.static, publicUrl, clientIpHeader });
 
 server.on('error', (err) => {
   console.error(err.code === 'EADDRINUSE' ? `Port ${port} is already in use. Try --port ${port + 1}` : err.message);

package/src/server.d.ts

@@ -7,6 +7,12 @@ export interface AttachOptions {
   publicUrl?: string;
   /** How long a room waits for its game page to come back before closing, in ms. Default 60000. */
   hostGraceMs?: number;
+  /**
+   * Header a trusted reverse proxy sets to the visitor's address, e.g. 'fly-client-ip' or
+   * 'x-real-ip'. The per-address limits use it (first value) instead of the socket address.
+   * Only set it behind a proxy that overwrites the header: clients can send it themselves.
+   */
+  clientIpHeader?: string;
 }
 
 /**

package/src/server.js

@@ -157,13 +157,14 @@ function fatal(ws, code) {
  * Existing 'request' listeners keep working for every other path.
  *
  * @param {import('node:http').Server} server
- * @param {{ static?: string, publicUrl?: string, hostGraceMs?: number }} [opts]
+ * @param {{ static?: string, publicUrl?: string, hostGraceMs?: number, clientIpHeader?: string }} [opts]
  * @returns {{ close(): void }}
  */
 export function attach(server, opts = {}) {
   const publicUrl = opts.publicUrl?.replace(/\/+$/, '');
   const staticDir = opts.static && path.resolve(opts.static);
   const hostGrace = opts.hostGraceMs ?? 60_000;
+  const ipHeader = opts.clientIpHeader?.toLowerCase();
   const rooms = new Map();
   const failedJoins = new Map(); // ip -> { count, since }
   // Right after a (re)start, phones of recreated rooms retry their joins
@@ -172,6 +173,10 @@ export function attach(server, opts = {}) {
   let closed = false;
   const wss = new WebSocketServer({ noServer: true, maxPayload: 8 * 1024 });
 
+  // The visitor's address for the per-IP limits. Behind a proxy, the header it sets;
+  // only when configured, because anyone can send that header straight to us.
+  const clientIp = (req) => (ipHeader && String(req.headers[ipHeader] ?? '').split(',')[0].trim()) || req.socket.remoteAddress;
+
   function joinBase(req) {
     if (publicUrl) return publicUrl;
     const proto = req.socket.encrypted ? 'https' : 'http';
@@ -216,7 +221,7 @@ export function attach(server, opts = {}) {
     const wanted = typeof m.room === 'string' ? m.room.toUpperCase() : '';
     let room = rooms.get(wanted);
 
-    const ip = req.socket.remoteAddress;
+    const ip = ws.ip;
     let resumed = false;
     if (room && room.hostToken === m.hostToken && room.slots.length === n) {
       // Resume: same room, same pads. Pads get a fresh 'joined' when the
@@ -234,7 +239,7 @@ export function attach(server, opts = {}) {
       }
     } else {
       if (rooms.size >= MAX_ROOMS) return fatal(ws, 'server-full');
-      // ponytail: per-IP cap only; behind a tunnel every host shares one IP.
+      // ponytail: per-IP cap only; behind a tunnel without clientIpHeader every host shares one IP.
       if ([...rooms.values()].filter((r) => r.ip === ip).length >= MAX_ROOMS_PER_IP) return fatal(ws, 'server-full');
       // Recreate (e.g. after a server restart) keeps the code so pads can rejoin.
       const recreate = !room && CODE.test(wanted) && HOST_TOKEN.test(m.hostToken ?? '');
@@ -262,8 +267,8 @@ export function attach(server, opts = {}) {
     const now = Date.now();
     let recent = failedJoins.get(ws.ip);
     if (!recent || now - recent.since >= FAILED_WINDOW) recent = { count: 0, since: now };
-    // ponytail: keyed by socket address, so behind a proxy or tunnel one guesser
-    // locks every remote phone out for a minute; key on a trusted header if that matters.
+    // Keyed by client address: behind a proxy without clientIpHeader, one guesser
+    // locks every remote phone out for a minute.
     if (recent.count >= MAX_FAILED_JOINS_PER_IP) return fatal(ws, 'rate-limited');
     const fail = (code, extra) => {
       send(ws, { t: 'error', code, ...extra });
@@ -350,7 +355,7 @@ export function attach(server, opts = {}) {
   wss.on('connection', (ws, req) => {
     ws.seen = Date.now();
     ws.failedJoins = 0;
-    ws.ip = req.socket.remoteAddress;
+    ws.ip = clientIp(req);
     ws.on('message', (raw, isBinary) => {
       ws.seen = Date.now();
       let m;
@@ -411,10 +416,10 @@ export function attach(server, opts = {}) {
     return true;
   }
 
-  async function serveStatic(req, res, pathname) {
+  async function serveStatic(req, res, url) {
     let rel;
     try {
-      rel = decodeURIComponent(pathname);
+      rel = decodeURIComponent(url.pathname);
     } catch {
       return false;
     }
@@ -422,6 +427,12 @@ export function attach(server, opts = {}) {
     let file = path.resolve(staticDir, '.' + rel);
     if (file !== staticDir && !file.startsWith(staticDir + path.sep)) return false;
     if (rel.endsWith('/')) file = path.join(file, 'index.html');
+    else if ((await stat(path.join(file, 'index.html')).catch(() => null))?.isFile()) {
+      // A directory without its slash: /demo/game -> /demo/game/. A relative Location keeps
+      // a path like //host from turning into a redirect to another site.
+      res.writeHead(301, { location: `./${url.pathname.split('/').pop()}/${url.search}` }).end();
+      return true;
+    }
     return serveFile(req, res, file);
   }
 
@@ -442,13 +453,14 @@ export function attach(server, opts = {}) {
     if (p === '/llms.txt') return serveFile(req, res, path.join(ROOT, 'llms.txt'), cors);
     if (p === '/joinstick/qr.svg') {
       const room = rooms.get((url.searchParams.get('room') ?? '').toUpperCase());
-      const slot = Number(url.searchParams.get('slot'));
-      if (!room || !Number.isInteger(slot) || slot < 1 || slot > room.slots.length) return false;
+      const slot = url.searchParams.get('slot'); // no slot: the link gives the first free one
+      const n = Number(slot);
+      if (!room || (slot !== null && (!Number.isInteger(n) || n < 1 || n > room.slots.length))) return false;
       res.writeHead(200, { 'content-type': 'image/svg+xml', 'cache-control': 'no-store', ...cors });
-      res.end(renderSVG(`${room.joinBase}/j/${room.code}/${slot}`, { border: 2 }));
+      res.end(renderSVG(`${room.joinBase}/j/${room.code}${slot === null ? '' : `/${n}`}`, { border: 2 }));
       return true;
     }
-    if (staticDir) return serveStatic(req, res, p);
+    if (staticDir) return serveStatic(req, res, url);
     return false;
   }