@diffenderfer-games/hub 2.0.0-next.1 → 2.0.0-next.10

package/src/realtime/rooms-forwarder.ts

@@ -1,10 +1,21 @@
 /**
  * `hub.rooms`: hub relay rooms, forwarded to the social runtime. Each room is
- * wrapped so its rejections use the core client's error classes.
+ * wrapped so its rejections use the core client's error classes, and the
+ * page's open rooms are tracked (`isInHubRoom`), so `hub.resume` can refuse
+ * to save an online run.
  */
 import type { Json, RoomInfo } from '@diffenderfer-games/hub-contract';
-import { pageBridge, rethrowAsHubError } from './bridge';
+import { outdatedRuntime, pageBridge, rethrowAsHubError } from './bridge';
 import type { HubRoom, HubRoomsApi, RoomEvents, RoomSelf, RoomSendOptions, RoomState, RoomStateOptions } from './room-types';
+import type { RoomSeat } from './wire-types';
+
+/** The rooms this page is in (created, joined or reclaimed, and not yet left or closed). */
+const openRooms = new Set<HubRoom>();
+
+/** Whether this page is in a hub room right now. */
+export function isInHubRoom(): boolean {
+  return openRooms.size > 0;
+}
 
 /** A runtime room whose rejections are re-created as the core client's errors. */
 class ForwardedRoom implements HubRoom {
@@ -12,6 +23,8 @@ class ForwardedRoom implements HubRoom {
 
   constructor(room: HubRoom) {
     this.room = room;
+    openRooms.add(room);
+    room.on('closed', () => { openRooms.delete(room); });
   }
 
   get info(): RoomInfo {
@@ -26,6 +39,10 @@ class ForwardedRoom implements HubRoom {
     return this.room.me;
   }
 
+  seats(): RoomSeat[] {
+    return this.room.info.seats;
+  }
+
   on<Name extends keyof RoomEvents>(event: Name, listener: (payload: RoomEvents[Name]) => void): () => void {
     return this.room.on(event, listener);
   }
@@ -63,6 +80,7 @@ class ForwardedRoom implements HubRoom {
   }
 
   leave(): Promise<void> {
+    openRooms.delete(this.room);
     return rethrowAsHubError(this.room.leave());
   }
 
@@ -76,4 +94,11 @@ export const roomsForwarder: HubRoomsApi = {
   create: (options) => pageBridge.call(async (realtime) => new ForwardedRoom(await realtime.rooms.create(options))),
   join: (codeOrId, options) => pageBridge.call(async (realtime) => new ForwardedRoom(await realtime.rooms.join(codeOrId, options))),
   list: (options) => pageBridge.call((realtime) => realtime.rooms.list(options)),
+  reclaim: () => pageBridge.call(async (realtime) => {
+    if (realtime.rooms.reclaim === undefined) {
+      throw outdatedRuntime('Taking back a seat');
+    }
+    const held = await realtime.rooms.reclaim();
+    return held === null ? null : new ForwardedRoom(held);
+  }),
 };

package/src/realtime/runtime-api.ts

@@ -3,16 +3,29 @@
  * the page, and that `hub.presence`, `hub.social`, `hub.mp`, `hub.rooms`,
  * `hub.notify` and `hub.race` forward to.
  */
-import type { HubMpApi } from './multiplayer-types';
+import type { RuntimeAvatarApi } from '../core/avatar/avatar-types';
+import type { HubMpApi, InviteLinkMethods } from './multiplayer-types';
 import type { HubRaceApi } from './race-types';
-import type { HubRoomsApi } from './room-types';
-import type { HubNotifyApi, HubPresenceApi, HubSocialApi } from './social-types';
+import type { HubRoomsApi, RoomReclaimMethods } from './room-types';
+import type { HubNotifyApi, HubPresenceApi, HubSocialApi, PlayOnlineMethods } from './social-types';
+import type { RuntimeWorldApi } from './world-types';
 
 /**
  * The realtime feature version the runtime reports in {@link RealtimeApi.version}.
- * 2 added races; a client feature-detects newer additions with it.
+ * 2 added races; 3 added invite links and taking back a held seat; 4 added
+ * "Play online" (tournaments); 5 added avatars (the designer and `ev:avatar`); 6 added the world (`world`).
+ * A client feature-detects newer additions with it (or by the optional method).
  */
-export const REALTIME_FEATURE_VERSION = 2;
+export const REALTIME_FEATURE_VERSION = 6;
+
+/** `hub.social` as a runtime installs it: version 4's `openPlayOnline` is missing on older runtimes. */
+export type RuntimeSocialApi = Omit<HubSocialApi, keyof PlayOnlineMethods> & Partial<PlayOnlineMethods>;
+
+/** `hub.mp` as a runtime installs it: version 3's invite-link methods are missing on older runtimes. */
+export type RuntimeMpApi = Omit<HubMpApi, keyof InviteLinkMethods> & Partial<InviteLinkMethods>;
+
+/** `hub.rooms` as a runtime installs it: version 3's `reclaim` is missing on older runtimes. */
+export type RuntimeRoomsApi = Omit<HubRoomsApi, keyof RoomReclaimMethods> & Partial<RoomReclaimMethods>;
 
 /**
  * The cross-bundle shape number of the `rt` page singleton (plan §4.4). The
@@ -24,6 +37,14 @@ export const REALTIME_SINGLETON_API = 1;
 /** The window event the runtime fires once it has installed itself. */
 export const REALTIME_READY_EVENT = 'hub:rt-ready';
 
+/**
+ * The window event the runtime fires each time its socket says hello (it
+ * connected, or connected again after a drop), with `{ user: { id, look } }`
+ * from the hello snapshot. `hub.avatar` and `hub.userId()` follow it; changes
+ * sent while the socket was down are fetched again.
+ */
+export const SESSION_EVENT = 'hub:session';
+
 /** The window event the menu fires when the runtime failed to load (its reason is on `window.__HUB_RT_ERROR__`). */
 export const REALTIME_FAILED_EVENT = 'hub:rt-failed';
 
@@ -37,13 +58,17 @@ export interface RealtimeApi {
   /** Presence reporting. */
   presence: HubPresenceApi;
   /** Friends and the social dialogs. */
-  social: HubSocialApi;
+  social: RuntimeSocialApi;
   /** Invites, launches, the leave guard and tickets. */
-  mp: HubMpApi;
+  mp: RuntimeMpApi;
   /** Hub relay rooms. */
-  rooms: HubRoomsApi;
+  rooms: RuntimeRoomsApi;
   /** Toast behaviour. */
   notify: HubNotifyApi;
   /** Races (feature version 2 and later). */
   race?: HubRaceApi;
+  /** Avatars: the designer and live changes (feature version 5 and later). */
+  avatar?: RuntimeAvatarApi;
+  /** The world's ops and events (feature version 6 and later). */
+  world?: RuntimeWorldApi;
 }

package/src/realtime/social-forwarder.ts

@@ -65,6 +65,11 @@ export const socialForwarder: HubSocialApi = {
       realtime.social.openNotify(options);
     });
   },
+  openPlayOnline: () => {
+    openWithRuntime((realtime) => {
+      realtime.social.openPlayOnline?.();
+    });
+  },
   friends: () => pageBridge.call((realtime) => realtime.social.friends()),
   counts: () => pageBridge.current()?.social.counts() ?? { ...NO_COUNTS },
   chatMode: (userIds) => pageBridge.current()?.social.chatMode(userIds) ?? 'off',

package/src/realtime/social-types.ts

@@ -61,6 +61,11 @@ export interface HubSocialApi {
   openSuggest(): void;
   /** Open notification settings, optionally focused on a game's lobby bell. */
   openNotify(options?: { game?: string }): void;
+  /**
+   * Open "Play online": games waiting for a player, invites, tournaments and
+   * the quick 1v1 (feature version 4; a no-op on older runtimes).
+   */
+  openPlayOnline(): void;
   /** Friends with live presence. Rejects with `OfflineError` without the runtime. */
   friends(): Promise<FriendEntry[]>;
   /** Live counts; all zero until the runtime is up. */
@@ -71,6 +76,9 @@ export interface HubSocialApi {
   on<Name extends keyof SocialEvents>(event: Name, listener: (payload: SocialEvents[Name]) => void): () => void;
 }
 
+/** What feature version 4 added to `hub.social`. */
+export type PlayOnlineMethods = Pick<HubSocialApi, 'openPlayOnline'>;
+
 /** `hub.notify`: toast behaviour during intense play. */
 export interface HubNotifyApi {
   /** Quiet: toasts collapse into the menu badge; invites still show as a small pill. */

package/src/realtime/types.ts

@@ -51,3 +51,4 @@ export type * from './multiplayer-types';
 export type * from './room-types';
 export type * from './race-types';
 export type { RealtimeApi } from './runtime-api';
+export type { RuntimeWorldApi, WorldEventName, WorldOpName } from './world-types';

package/src/realtime/wire-types.ts

@@ -9,6 +9,7 @@ import type {
   OpAck,
   ops,
   InviteCreated as InviteCreatedSchema,
+  InviteLink as InviteLinkSchema,
   RaceHistory as RaceHistorySchema,
   RaceResultPlayer as RaceResultPlayerSchema,
   RaceRecordPlayer as RaceRecordPlayerSchema,
@@ -51,6 +52,12 @@ export type RoomMessage = ServerEvents['room.msg'];
 /** A shared-state change (`ev:room.state`); patches are shallow-merged unless `replace`. */
 export type RoomStateChange = ServerEvents['room.state'];
 
+/** A seat went away, came back or is gone (`ev:room.seat`). */
+export type RoomSeatChange = ServerEvents['room.seat'];
+
+/** A shareable invite link into a room (`POST /mp/links`). */
+export type InviteLink = SchemaOutput<typeof InviteLinkSchema>;
+
 /** A moderated room chat line (`ev:room.chat`). */
 export type RoomChatLine = ServerEvents['room.chat'];
 

package/src/realtime/world-types.ts

@@ -0,0 +1,20 @@
+/**
+ * The world over the runtime's socket (docs/plans/world.md §8.3): the
+ * `world.*` ops and events, typed from the contract. The hub's world client
+ * calls it; games don't need it.
+ */
+import type { EventData, EventName, events, OpAck, OpInput, OpName, ops } from '@diffenderfer-games/hub-contract';
+
+/** A `world.*` op name. */
+export type WorldOpName = Extract<OpName, `world.${string}`>;
+
+/** A `world.*` event name. */
+export type WorldEventName = Extract<EventName, `world.${string}`>;
+
+/** `rt.world` (realtime feature version 6 and later). */
+export interface RuntimeWorldApi {
+  /** Send a world op on the page's socket; rejects with the hub's refusal. */
+  op<Name extends WorldOpName>(name: Name, input: OpInput<(typeof ops)[Name]>): Promise<OpAck<(typeof ops)[Name]>>;
+  /** Hear a world event; returns the unsubscribe. */
+  on<Name extends WorldEventName>(name: Name, listener: (payload: EventData<(typeof events)[Name]>) => void): () => void;
+}

package/src/rooms.ts

@@ -6,5 +6,5 @@
  */
 export { roomsForwarder as rooms } from './realtime/rooms-forwarder';
 export type * from './realtime/room-types';
-export type { RoomChatLine, RoomMessage, RoomSeat, RoomStateChange } from './realtime/wire-types';
+export type { RoomChatLine, RoomMessage, RoomSeat, RoomSeatChange, RoomStateChange } from './realtime/wire-types';
 export type { RoomInfo } from '@diffenderfer-games/hub-contract';

package/src/social.ts

@@ -14,5 +14,6 @@ export {
   REALTIME_FEATURE_VERSION,
   REALTIME_READY_EVENT,
   REALTIME_SINGLETON_API,
+  SESSION_EVENT,
 } from './realtime/runtime-api';
 export type * from './realtime/types';

package/src/turns-kit/check-rules.ts

@@ -0,0 +1,281 @@
+/**
+ * The rules conformance kit (docs/multiplayer.md "Turn games: testing"):
+ * `checkTurnRules(rules, options)` plays many seeded games through a rules
+ * module the way the hub does and throws on the first broken promise:
+ *
+ * - every game reaches an outcome within `maxMoves`, and `toAct` is never
+ *   empty before it; every seat in `toAct` gets to move (not only the
+ *   first), and so do the seats in `mayAct` (out of turn: a jump-in, a
+ *   catch) whose `autoReact` (or `options.reactMove`) has a move;
+ * - `toAct` and `mayAct` only name seats that exist;
+ * - the state survives a JSON round trip after every move, and the same seed
+ *   plays the same game (no `Math.random`, no hidden globals);
+ * - `autoMove` and `autoReact` (when the rules have them) are always legal;
+ * - no seat's `view` or `eventView` shows another seat's secrets: markers
+ *   planted with `options.plant` never appear in anyone else's view until
+ *   the rules reveal them (`options.revealed`: a card played face up);
+ * - with `options.shuffleHidden` (the "twin table"): shuffling everything a
+ *   seat may not see never changes that seat's view;
+ * - stored fixtures from older versions `migrate` to a state that views;
+ * - views, events and moves stay within the hub's size caps.
+ *
+ * It needs no hub: run it in a game's own unit tests (vitest, node:test).
+ */
+import { createTurnRng, turnRngStateFromSeed, type TurnRng, type TurnRules } from '@diffenderfer-games/hub-contract/turns-rules';
+import { parseJsonText } from '../core/storage/json-guards';
+
+/** The hub's caps. */
+const STATE_MAX_BYTES = 64 * 1024;
+const MOVE_MAX_BYTES = 2 * 1024;
+
+/** How to check a rules module. */
+export interface TurnRulesCheckOptions<State, Move, Options = never> {
+  /** Seat counts to play (default: 2). */
+  readonly seats?: readonly number[];
+  /** Games per seat count (default: 25). */
+  readonly games?: number;
+  /** A game that runs longer than this many moves fails (default: 2000). */
+  readonly maxMoves?: number;
+  /** Options and mode to set games up with. */
+  readonly setupOptions?: Options;
+  readonly mode?: string | null;
+  /** A legal move for `seat` (default: the rules' own `autoMove`). At least one of the two is needed. */
+  readonly randomMove?: (state: State, seat: number, rng: TurnRng) => Move;
+  /** A legal out-of-turn move for `seat` while it is in `mayAct`, or `null` to pass (default: the rules' own `autoReact`). */
+  readonly reactMove?: (state: State, seat: number, rng: TurnRng) => Move | null;
+  /**
+   * Put `marker` somewhere only `seat` may see (a card in their hand, their
+   * secret goal) and return the state; the kit then checks no other seat's
+   * view or events ever contain it. Leave it out for a game with no hidden
+   * information.
+   */
+  readonly plant?: (state: State, seat: number, marker: string) => State;
+  /**
+   * Whether a planted `marker` is now public by the rules (the card was
+   * played or discarded face up, a secret was shown at the end): from then
+   * on the kit stops checking it in that game, so a card that is rightly
+   * revealed isn't a leak. Leave it out when planted markers never become
+   * public.
+   */
+  readonly revealed?: (state: State, marker: string) => boolean;
+  /**
+   * The "twin table": a copy of `state` with everything `seat` may not see
+   * shuffled or redealt (the deck's order, the other hands' cards, keeping
+   * their counts), drawing from `rng`. After every move the kit checks
+   * that each seat's `view` of the twin is exactly its view of the real
+   * state: a view that changes depends on something that seat must not
+   * know. Catches leaks `plant` can't (a count, an order, a derived hint).
+   */
+  readonly shuffleHidden?: (state: State, seat: number, rng: TurnRng) => State;
+  /** States saved by older rules versions, which `migrate` must bring up to date. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: states stored by older rules versions
+  readonly fixtures?: readonly { readonly version: number; readonly state: unknown }[];
+}
+
+/** What the kit played. */
+export interface TurnRulesReport {
+  readonly games: number;
+  readonly moves: number;
+  readonly longestGame: number;
+  /** Moves made out of turn (by a seat in `mayAct`, not `toAct`). */
+  readonly outOfTurn: number;
+}
+
+/** The UTF-8 bytes of a JSON text. */
+function bytesOf(json: string): number {
+  return new TextEncoder().encode(json).length;
+}
+
+/** Throw a kit failure. */
+function fail(message: string): never {
+  throw new Error(`checkTurnRules: ${message}`);
+}
+
+/** A JSON copy (what the hub stores and reads back). */
+function roundTrip<T>(value: T): T {
+  const copy = parseJsonText(JSON.stringify(value));
+  if (copy === null && value !== null) {
+    fail('a state or move is not JSON');
+  }
+  return isGamesOwn(copy, value) ? copy : fail('a state or move is not JSON');
+}
+
+/** Always true: JSON a game's rules made is read back as the game's own type (the game vouches for it, as `toGameData` does). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the game's own JSON, round-tripped
+function isGamesOwn<T>(_value: unknown, _like: T): _value is T {
+  return true;
+}
+
+/** A move for `seat`: the check's own chooser, else the rules' autoMove. */
+function pickMove<State, Move, View, Event, Options>(rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options>, state: State, seat: number, rng: TurnRng): Move {
+  if (options.randomMove !== undefined) {
+    return options.randomMove(state, seat, rng);
+  }
+  if (rules.autoMove === undefined) {
+    return fail('the rules have no autoMove: pass options.randomMove');
+  }
+  return rules.autoMove(state, seat, rng);
+}
+
+/** An out-of-turn move for `seat`: the check's own chooser, else the rules' autoReact, else none. */
+function pickReaction<State, Move, View, Event, Options>(rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options>, state: State, seat: number, rng: TurnRng): Move | null {
+  if (options.reactMove !== undefined) {
+    return options.reactMove(state, seat, rng);
+  }
+  return rules.autoReact?.(state, seat, rng) ?? null;
+}
+
+/** Fail unless every seat in `list` exists. */
+function checkSeats(list: readonly number[], seats: number, what: string, seed: number): void {
+  if (list.some((seat) => !Number.isInteger(seat) || seat < 0 || seat >= seats)) {
+    fail(`${what} named a seat that doesn't exist: [${list.join(', ')}] (seed ${String(seed)})`);
+  }
+}
+
+/**
+ * The next move of a game: half the time a seat in `mayAct` that has an
+ * out-of-turn move, else a seat in `toAct` (any of them, not only the
+ * first). The kit's own `pick` RNG chooses, so the game's RNG sees only
+ * the rules' own draws.
+ */
+function nextMove<State, Move, View, Event, Options>(
+  rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options>, state: State, toAct: readonly number[], rng: TurnRng, pick: TurnRng,
+): { seat: number; move: Move; by: string } | null {
+  const optional = (rules.mayAct?.(state) ?? []).filter((seat) => !toAct.includes(seat));
+  if (optional.length > 0 && pick.int(2) === 0) {
+    const seat = pick.pick(optional);
+    const move = pickReaction(rules, options, state, seat, rng);
+    if (move !== null) {
+      return { seat, move, by: options.reactMove === undefined ? 'autoReact' : 'reactMove' };
+    }
+  }
+  const seat = toAct.length === 0 ? undefined : pick.pick(toAct);
+  return seat === undefined ? null : { seat, move: pickMove(rules, options, state, seat, rng), by: options.randomMove === undefined ? 'autoMove' : 'randomMove' };
+}
+
+/** Play one seeded game; answers its moves and a trace for the determinism check. */
+function playGame<State, Move, View, Event, Options>(
+  rules: TurnRules<State, Move, View, Event, Options>, seats: number, seed: number, options: TurnRulesCheckOptions<State, Move, Options>,
+): { moves: number; outOfTurn: number; trace: string } {
+  const rng = createTurnRng(turnRngStateFromSeed(seed));
+  const pick = createTurnRng(turnRngStateFromSeed(seed ^ 0x5bd1e995));
+  const twinRng = createTurnRng(turnRngStateFromSeed(seed ^ 0x27d4eb2f));
+  const marker = `MARKER-${String(seed)}-`;
+  const markerOf = (owner: number): string => `${marker}${String(owner)}`;
+  let state = rules.setup({ seats, options: options.setupOptions ?? null, mode: options.mode ?? null, rng });
+  if (options.plant !== undefined) {
+    for (let seat = 0; seat < seats; seat++) {
+      state = options.plant(state, seat, markerOf(seat));
+    }
+  }
+  const maxMoves = options.maxMoves ?? 2000;
+  const trace: string[] = [];
+  let outOfTurn = 0;
+  /** The twin table: each seat's view is the same after what it can't see is shuffled. */
+  const checkTwin = (): void => {
+    if (options.shuffleHidden === undefined) {
+      return;
+    }
+    for (let viewer = 0; viewer < seats; viewer++) {
+      const real = JSON.stringify(rules.view(state, viewer));
+      const twin = JSON.stringify(rules.view(roundTrip(options.shuffleHidden(roundTrip(state), viewer, twinRng)), viewer));
+      if (twin !== real) {
+        fail(`seat ${String(viewer)}'s view changed when what it can't see was shuffled: it shows something hidden (seed ${String(seed)})`);
+      }
+    }
+  };
+  /** The seats whose planted marker is still secret (the rules haven't revealed it). */
+  const secret = new Set(options.plant === undefined ? [] : Array.from({ length: seats }, (_, seat) => seat));
+  const checkViews = (events: readonly Event[]): void => {
+    for (const owner of secret) {
+      if (options.revealed?.(state, markerOf(owner)) === true) {
+        secret.delete(owner);
+      }
+    }
+    for (let viewer = 0; viewer < seats; viewer++) {
+      const seen = JSON.stringify(rules.view(state, viewer)) + JSON.stringify(events.map((event) => rules.eventView?.(event, viewer) ?? null));
+      for (const owner of secret) {
+        if (owner !== viewer && seen.includes(markerOf(owner))) {
+          fail(`seat ${String(viewer)} can see seat ${String(owner)}'s secret (seed ${String(seed)})`);
+        }
+      }
+    }
+    const shown = JSON.stringify(rules.view(state, null));
+    for (const owner of secret) {
+      if (shown.includes(markerOf(owner))) {
+        fail(`the public view shows seat ${String(owner)}'s secret (seed ${String(seed)})`);
+      }
+    }
+    checkTwin();
+  };
+  checkViews([]);
+  for (let moves = 0; moves < maxMoves; moves++) {
+    if (rules.outcome(state) !== null) {
+      return { moves, outOfTurn, trace: trace.join('|') };
+    }
+    const toAct = rules.toAct(state);
+    checkSeats(toAct, seats, 'toAct', seed);
+    checkSeats(rules.mayAct?.(state) ?? [], seats, 'mayAct', seed);
+    if (toAct.length === 0) {
+      fail(`toAct is empty but there is no outcome yet (seed ${String(seed)}, move ${String(moves)})`);
+    }
+    const next = nextMove(rules, options, state, toAct, rng, pick);
+    if (next === null) {
+      return fail(`no seat could move (seed ${String(seed)}, move ${String(moves)})`);
+    }
+    const { seat, move } = next;
+    outOfTurn += toAct.includes(seat) ? 0 : 1;
+    if (bytesOf(JSON.stringify(move)) > MOVE_MAX_BYTES) {
+      fail(`a move is over ${String(MOVE_MAX_BYTES)} bytes`);
+    }
+    const result = rules.apply(roundTrip(state), seat, roundTrip(move), rng);
+    if ('error' in result) {
+      fail(`${next.by} made an illegal move for seat ${String(seat)}: ${result.error} (seed ${String(seed)}, move ${String(moves)})`);
+    }
+    state = roundTrip(result.state);
+    if (bytesOf(JSON.stringify(state)) > STATE_MAX_BYTES) {
+      fail(`the state is over ${String(STATE_MAX_BYTES)} bytes`);
+    }
+    checkViews(result.events ?? []);
+    rules.progress(state, seat);
+    trace.push(`${String(seat)}:${JSON.stringify(move)}`);
+  }
+  return fail(`a game did not end within ${String(maxMoves)} moves (seed ${String(seed)})`);
+}
+
+/** Check a rules module (see the file comment); throws on the first failure. */
+export function checkTurnRules<State, Move, View, Event, Options>(
+  rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options> = {},
+): TurnRulesReport {
+  if (!Number.isInteger(rules.version) || rules.version < 0) {
+    fail('rules.version must be a whole number');
+  }
+  let games = 0;
+  let moves = 0;
+  let longestGame = 0;
+  let outOfTurn = 0;
+  for (const seats of options.seats ?? [2]) {
+    for (let game = 0; game < (options.games ?? 25); game++) {
+      const seed = seats * 100_003 + game;
+      const played = playGame(rules, seats, seed, options);
+      if (playGame(rules, seats, seed, options).trace !== played.trace) {
+        fail(`the same seed played a different game (seed ${String(seed)}): use the rng you are given, never Math.random`);
+      }
+      games += 1;
+      moves += played.moves;
+      longestGame = Math.max(longestGame, played.moves);
+      outOfTurn += played.outOfTurn;
+    }
+  }
+  for (const fixture of options.fixtures ?? []) {
+    if (fixture.version < rules.version) {
+      if (rules.migrate === undefined) {
+        fail(`a version ${String(fixture.version)} fixture needs rules.migrate`);
+      }
+      const migrated = rules.migrate(roundTrip(fixture.state), fixture.version);
+      rules.view(migrated, null);
+      rules.toAct(migrated);
+    }
+  }
+  return { games, moves, longestGame, outOfTurn };
+}

package/src/turns-rules.ts

@@ -0,0 +1,12 @@
+/**
+ * `@diffenderfer-games/hub/turns-rules`: what an online turn game's rules
+ * module imports (docs/multiplayer.md §16): `defineTurnRules` to type the
+ * rules object, the rules contract's types, and the seeded RNG the hub
+ * hands the rules. Nothing else comes with it (no zod, no client), so a
+ * rules bundle that imports it stays a few KB. The conformance kit for
+ * tests is `@diffenderfer-games/hub/turns`.
+ *
+ * @packageDocumentation
+ */
+export { createTurnRng, defineTurnRules, turnRngStateFromSeed } from '@diffenderfer-games/hub-contract/turns-rules';
+export type { TurnApplyResult, TurnOutcome, TurnProgress, TurnRng, TurnRngState, TurnRules, TurnSetupContext } from '@diffenderfer-games/hub-contract/turns-rules';

package/src/turns.ts

@@ -0,0 +1,14 @@
+/**
+ * `@diffenderfer-games/hub/turns`: writing and testing an online turn
+ * game's rules module (docs/multiplayer.md "Turn games"). The types of the
+ * rules contract, `defineTurnRules` to type a rules object, the seeded RNG
+ * the hub hands the rules (to replay a game in tests), and the conformance
+ * kit, `checkTurnRules`, for the game's own CI. The page-side API is
+ * `hub.turns` on the main entry. A rules module itself imports
+ * `@diffenderfer-games/hub/turns-rules` (the same `defineTurnRules` and
+ * types, nothing else), so its bundle stays a few KB.
+ *
+ * @packageDocumentation
+ */
+export * from './turns-rules';
+export { checkTurnRules, type TurnRulesCheckOptions, type TurnRulesReport } from './turns-kit/check-rules';