v0.5.1 — multiplayer Phase 4: lobby, sessions, reconnection

A real server existed since v0.5.0 but nobody could reach it without a hand-built ?seat=&secret=
URL. This is what makes it a game you can actually create or join.

The server now hosts more than one game: src/server/lobby.ts (new) is pure logic — creating,
joining, bot seats, host transfer, starting — same split session.ts already draws for a running
game. persistence.ts gained one directory per gameId plus a top-level index so index.ts resumes
every saved game on boot. /api/stream and /api/intent now authenticate by session token instead of
?seat=&secret= — the token alone proves identity (lobby-and-sessions.md §1), so the join secret's
job ends at the lobby door.

Bots fill empty seats at Lobby.Start only, never take over a disconnected human (D8): session.ts
gained driveBots(), playing developerBot forward through consecutive bot seats after every accepted
intent. Disconnect keeps the seat and says so — Push gained an optional presence field, built
entirely by http.ts and never routed through the engine, since a disconnect is transport news, not
a GameEvent. Host rights pass to the earliest-joined remaining player if the host drops before
start.

Client: src/web/lobby.ts adds create/join forms and a live seating screen; localStorage replaces
?seat= for reconnecting straight back into a game already joined. A Multiplayer button sits beside
New game; the New Game dialog itself is untouched.

Found only by the live smoke test, not by typechecking: /api/intent read its token from the JSON
body while the client sends it in the query string (matching /api/stream) — every intent failed
"no such game" until caught by curl-level verification.

Doc fix: multiplayer.md's D18 said the player cap was 6; lobby-and-sessions.md §2 says 2-4 with the
reasoning and the test coverage to back it. The two had drifted apart. D18 now reads 2-4.

Not verified: an actual browser walking through the lobby screens — none available in this
environment, same limitation Phase 2's RemoteSession shipped under. 656 tests, 0 failures.

tools/jitsi-harness/ deliberately left untracked — unrelated side-project work, not part of this
release.

src/web/main.ts

@@ -25,9 +25,18 @@ import type { NewGameOptions } from './game.ts';
 import type { LocalSession, Session } from './session.ts';
 import { createLocalSession, createRemoteSession } from './session.ts';
 import type { PlayerIndex } from '../engine/state.ts';
+import { runLobby } from './lobby.ts';
+import type { LobbyReady } from './lobby.ts';
 
 const SAVE_KEY = 'station-master.save.v1';
 const SETTINGS_KEY = 'station-master.settings.v1';
+/**
+ * The multiplayer session — `lobby-and-sessions.md` §1's token, plus the `gameId`/`seat` a fresh
+ * `createRemoteSession` needs without waiting on a push to learn its own seat. Separate from
+ * `SAVE_KEY`: a solitaire save is the seed plus intents and is meant to be portable between
+ * browsers; this is a credential for THIS origin's server and must never be treated as one.
+ */
+const REMOTE_KEY = 'station-master.remote.v1';
 /** Preset board zoom levels — a fraction applied to the rendered SVG's own pixel dimensions. */
 const ZOOM_LEVELS = [0.75, 1, 1.25, 1.5] as const;
 
@@ -298,27 +307,58 @@ function rulesToUrl(rules: HouseRules, options: NewGameOptions, seed: string): s
   return `?${params}`;
 }
 
+function loadRemote(): LobbyReady | null {
+  try {
+    const raw = localStorage.getItem(REMOTE_KEY);
+    return raw ? (JSON.parse(raw) as LobbyReady) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Toggles the two mutually-exclusive top-level screens `play.html` defines — `#lobby` (Phase 4)
+ * and `#gameui` (the board, whether local or remote). Both start `hidden` in the markup so neither
+ * ever flashes before `start()` decides which one this load actually needs. */
+function showScreen(which: 'lobby' | 'gameui'): void {
+  document.getElementById('lobby')!.hidden = which !== 'lobby';
+  document.getElementById('gameui')!.hidden = which !== 'gameui';
+}
+
 /**
- * `?seat=` PRESENT means multiplayer (D4 — one bundle, runtime switch). The seed, house rules and
- * URL-carried save/restore logic below are all solitaire concepts: a remote game's rules come from
- * whatever the server was configured with, not from this browser's URL or `localStorage`.
+ * The one place a `RemoteSession` gets built — from a fresh `Lobby.Start` push (`lobby.ts`'s
+ * `runLobby` callback) or from a `{token, gameId, seat}` already sitting in `localStorage` from an
+ * earlier visit. Either way the token is what makes reconnection work (`lobby-and-sessions.md` §1),
+ * so it is always written back here before anything else happens.
+ */
+function beginRemote(ready: LobbyReady): void {
+  localStorage.setItem(REMOTE_KEY, JSON.stringify(ready));
+  showScreen('gameui');
+  session = createRemoteSession(ready.token, ready.seat);
+  applyCapabilities();
+  // A LocalSession has data the instant it is constructed; a RemoteSession does not — its first
+  // real Frame only exists once the SSE connection's first push arrives, so the first render waits
+  // for `subscribe`'s callback rather than firing immediately (`session.ts`'s own doc comment on
+  // `createRemoteSession` explains why `view()` would otherwise throw).
+  session.subscribe(render);
+}
+
+/**
+ * NO `?seat=` SHORTCUT ANY MORE. A remote game is reached by creating or joining one through
+ * `#lobby` (`lobby.ts`), which is what hands out the token `beginRemote` needs — hand-editing a URL
+ * cannot produce one. `start()`'s job is only to decide which of three screens this load is: back
+ * into a remembered multiplayer game, straight into solitaire (the zero-friction default, D11 — the
+ * common case and the only one a bare page load has ever needed a decision for), or the lobby.
  */
 function start(): void {
   const params = new URLSearchParams(location.search);
-  const seatParam = params.get('seat');
 
-  if (seatParam !== null) {
-    const seat = Number(seatParam) as PlayerIndex;
-    session = createRemoteSession(seat, params.get('secret') ?? '');
-    applyCapabilities();
-    // A LocalSession has data the instant it is constructed; a RemoteSession does not — its first
-    // real Frame only exists once the SSE connection's first push arrives, so the first render waits
-    // for `subscribe`'s callback rather than firing immediately (`session.ts`'s own doc comment on
-    // `createRemoteSession` explains why `view()` would otherwise throw).
-    session.subscribe(render);
+  const remembered = loadRemote();
+  if (remembered) {
+    beginRemote(remembered);
     return;
   }
 
+  showScreen('gameui');
   const requested = params.get('seed');
   // A seed in the URL makes a game shareable and reproducible: same link, same deal.
   const seed = requested !== null ? Number(requested) || 1 : Math.floor(Math.random() * 1e9);
@@ -354,6 +394,23 @@ function applyCapabilities(): void {
   hide('undo', c.undo);
   hide('savefile', c.saveLocal);
   hide('newgame', c.newGame);
+  // Creating or joining ANOTHER multiplayer game from inside a running one is not a thing this
+  // page offers — same reasoning as `newgame`, and the same capability answers both.
+  hide('multiplayer', c.newGame);
+}
+
+/**
+ * `lobby-and-sessions.md` §5 — names every currently-DISCONNECTED other seat, so a stalled table
+ * has a reason on screen instead of silence. Always empty for a `LocalSession` (`presence()` never
+ * has anything to report), and empty again the moment everyone reports back in — `#presence:empty`
+ * collapses the banner rather than leaving a reassuring "all connected" line nobody needs to read.
+ */
+function renderPresence(f: Frame): void {
+  const away = session
+    .presence()
+    .filter((p) => !p.connected)
+    .map((p) => f.players.find((pl) => pl.index === p.seat)?.name ?? `Seat ${p.seat}`);
+  $('presence').textContent = away.length === 0 ? '' : `⚠ waiting on ${away.join(', ')} — disconnected`;
 }
 
 function render(): void {
@@ -379,6 +436,7 @@ function render(): void {
   }
 
   renderTurnChart(f);
+  renderPresence(f);
   $('revenue').textContent = String(f.revenue);
   /**
    * THE OBJECTIVE, WITHOUT THE COMMENTARY.
@@ -1180,6 +1238,20 @@ if (saveBtn) saveBtn.onclick = downloadSave;
  * Navigating rather than re-rendering, so a stale `?seed=` in the URL goes too — leaving it would
  * deal the same game again and look like the button had done nothing.
  */
+const multiplayerBtn = document.getElementById('multiplayer');
+if (multiplayerBtn) {
+  multiplayerBtn.onclick = () => {
+    // Hidden whenever `session` cannot deal (`applyCapabilities`), but repeated here for the same
+    // reason `newBtn`'s handler repeats its own guard: the click handler outlives any one session.
+    if (!isLocal(session)) return;
+    const f = session.view();
+    const started = f.status === 'active' && (f.day > 1 || f.stage > 1);
+    if (started && !confirm(`Leave this game (seed ${session.seed()}, Day ${f.day}) for multiplayer?`)) return;
+    showScreen('lobby');
+    runLobby(beginRemote);
+  };
+}
+
 const newBtn = document.getElementById('newgame');
 const dlg = document.getElementById('newgamedlg') as HTMLDialogElement | null;
 if (newBtn && dlg) {