v0.4.0 — multiplayer Phases 0 and 1: seat and player split apart, turn state per player, the page behind a Session, and eight seat/player mix-ups fixed with tests that fail without them

src/web/session.ts

@@ -0,0 +1,172 @@
+/**
+ * The boundary between the page and the game.
+ *
+ * The page draws a `Frame` and offers a `Menu`, and submits intents. It does not care whether the
+ * rules are being applied a function call away or across a network — which is the whole point:
+ *
+ *   - `LocalSession` runs the engine in this browser. Solitaire, exactly as it has always worked,
+ *     with no server involved at any point.
+ *   - `RemoteSession` (not built yet — see `docs/architecture/multiplayer.md` Phase 2) will hold no
+ *     authoritative state at all. It cannot: it has neither the deck order nor the other players'
+ *     hands, and if it did the game would be cheatable.
+ *
+ * So this interface is deliberately the SMALLER of the two — everything a remote client could
+ * possibly offer, and nothing that only a local one can do. What a local session can do beyond it is
+ * declared in `capabilities`, and the page hides those controls rather than calling them and failing.
+ */
+
+import type { Intent } from '../engine/intents.ts';
+import type { Frame } from '../sim/view.ts';
+import type { GameConfig, PlayerIndex } from '../engine/state.ts';
+import type { Game, Menu, Save } from './game.ts';
+import {
+  actionMenu,
+  currentActor,
+  fromSave,
+  handPlayable,
+  newGame,
+  overHandLimit,
+  submit,
+  toSave,
+  undo,
+  view,
+} from './game.ts';
+
+/**
+ * What this session can do beyond the common interface.
+ *
+ * None of these survive a server. Undo would have to un-see what other players have already seen;
+ * a local save is meaningless when the server is the store; and dealing a new game is the lobby's
+ * job. The page reads these rather than assuming, so the same code drives both.
+ */
+export type Capabilities = {
+  undo: boolean;
+  saveLocal: boolean;
+  newGame: boolean;
+};
+
+export type Session = {
+  /** The board as this seat sees it. */
+  view(): Frame;
+  /** What this seat may do right now. */
+  menu(): Menu;
+  /** Which seat this client is playing. */
+  seat(): PlayerIndex;
+  /** Whose turn it is, or null when the game is over or waiting on nothing. */
+  actor(): PlayerIndex | null;
+  /** True when the hand is over §6.2's limit and the turn cannot be ended. */
+  overHandLimit(): boolean;
+  /** Which cards in hand are playable right now, in hand order. */
+  handPlayable(): boolean[];
+  /**
+   * Propose an action. Resolves false if the rules refused it.
+   *
+   * Async because a remote session must be, even though the local one answers immediately — a page
+   * written against a synchronous `submit` would have to be rewritten for the server.
+   */
+  submit(intent: Intent): Promise<boolean>;
+  /** Called whenever something changed and the page should redraw. Returns an unsubscribe. */
+  subscribe(fn: () => void): () => void;
+  capabilities: Capabilities;
+
+  /**
+   * WHAT JUST HAPPENED — three transient signals the page uses to draw a moment rather than a state.
+   *
+   * They are separate from `view()` because two of them are CONSUMED: a Stage flash and a sound play
+   * once and are then gone, whereas the Frame can be rebuilt any number of times per render. Putting
+   * them on the Frame would mean re-flashing on every redraw.
+   *
+   * A remote session fills these from the server's pushes rather than from a local event log; the
+   * page cannot tell the difference. Whether they eventually ride on the Frame as animation hints is
+   * a Phase 2 question (`docs/architecture/multiplayer.md` D3).
+   */
+  /** The narrated history, newest last. */
+  lines(): { text: string; tone: string }[];
+  /** Sounds earned since the last call. Draining. */
+  takeCues(): string[];
+  /** The timetable slot the last 1D12 filled, once. Draining. */
+  takeScheduled(): number | null;
+  /** The card most recently drawn into this seat's hand. Persists until another draw replaces it. */
+  justDrawn(): string | null;
+};
+
+/**
+ * Everything a LOCAL session can additionally do. Kept off `Session` so that reaching for one of
+ * these in shared page code is a type error rather than a runtime surprise against a server.
+ */
+export type LocalSession = Session & {
+  readonly game: Game;
+  seed(): number;
+  save(): Save;
+  /** How many intents have been submitted — what the Undo button counts down. */
+  steps(): number;
+  /** Steps back one intent by replaying the history without it. Returns false at the start. */
+  undo(): boolean;
+  restore(save: Save): void;
+};
+
+/**
+ * A session that owns the engine in this process.
+ *
+ * `Game` is mutated in place by `submit`, so the wrapper keeps a mutable reference rather than
+ * copying — `undo` and `restore` replace the whole game, which is why `game` is a getter.
+ */
+export function createLocalSession(seed: number, config?: GameConfig): LocalSession {
+  let game: Game = config ? newGame(seed, config) : newGame(seed);
+  const listeners = new Set<() => void>();
+  const changed = (): void => {
+    for (const fn of [...listeners]) fn();
+  };
+
+  return {
+    get game() {
+      return game;
+    },
+    view: () => view(game),
+    menu: () => actionMenu(game),
+    seat: () => 0,
+    actor: () => currentActor(game),
+    overHandLimit: () => overHandLimit(game),
+    handPlayable: () => handPlayable(game),
+    submit: async (intent: Intent) => {
+      const ok = submit(game, intent);
+      if (ok) changed();
+      return ok;
+    },
+    subscribe(fn: () => void) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    capabilities: { undo: true, saveLocal: true, newGame: true },
+
+    lines: () => game.log,
+    takeCues: () => game.cues.splice(0, game.cues.length),
+    takeScheduled: () => {
+      const slot = game.scheduled;
+      game.scheduled = null;
+      return slot;
+    },
+    justDrawn: () => game.justDrawn,
+
+    seed: () => game.seed,
+    save: () => toSave(game),
+    steps: () => game.history.length,
+    undo() {
+      const back = undo(game);
+      if (!back) return false;
+      game = back;
+      // The rebuilt game replays its own history, so every cue and draw in it is old news.
+      back.cues.length = 0;
+      back.scheduled = null;
+      back.justDrawn = null;
+      changed();
+      return true;
+    },
+    restore(save: Save) {
+      game = fromSave(save);
+      // Restoring replays the whole history and re-records every draw; none of it is news.
+      game.justDrawn = null;
+      changed();
+    },
+  };
+}