@diffenderfer-games/hub 2.0.0-next.5 → 2.0.0-next.7

package/src/daily/types.ts

@@ -3,12 +3,14 @@
  * answers (typed from the contract's daily endpoints).
  */
 import type { dailyEndpoints, Json } from '@diffenderfer-games/hub-contract';
+import type { GamePayload } from '../core/game-data';
+import type { SavedEntry } from '../core/saved/saved-types';
 import type { SchemaOutput } from '../realtime/wire-types';
 
 /** The response type of a daily endpoint. */
 type DailyResponse<Name extends keyof typeof dailyEndpoints> = SchemaOutput<(typeof dailyEndpoints)[Name]['cfg']['response']>;
 
-/** This game's daily window and the player's completions (`GET /games/:slug/daily`). */
+/** This game's daily window, the player's completions and days in progress (`GET /games/:slug/daily`). */
 export type DailyStatus = DailyResponse<'getGameDailyChallenges'>;
 
 /** Every daily game and the global standings (`GET /daily`). */
@@ -17,7 +19,7 @@ export type DailyAll = DailyResponse<'listDailyChallengesForAllGames'>;
 /** One game's row in {@link DailyAll}. */
 export type DailyGameStatus = DailyAll['games'][number];
 
-/** The answer to starting a day: its seed and the signed token to present on completion. */
+/** The answer to starting (or resuming) a day: its seed, the signed token to present on completion, and its saved game. */
 export type DailyStartResponse = DailyResponse<'startDailyChallenge'>;
 
 /** The answer to completing a day: the player's new completion count and rank. */
@@ -25,26 +27,49 @@ export type DailyCompleteResponse = DailyResponse<'completeDailyChallenge'>;
 
 /** The challenge a game's `play` receives: set up and start exactly this day (derive the level from `seed`). */
 export interface DailyChallenge {
-  /** The day, `YYYY-MM-DD`. */
+  /** The day, `YYYY-MM-DD` (a UTC day key). */
   day: string;
   /** Deterministic per game and day. */
   seed: number;
-  /** The signed token `complete` presents. */
+  /** The signed token `complete` presents (empty for a day started offline: it is fetched when the hub is back). */
   token: string;
-  /** The player already completed this day (a replay). */
+  /** The player already completed this day (a replay for fun: nothing is saved or recorded). */
   alreadyCompleted?: boolean;
+  /** The day's saved game; `null` for a replay of a completed day. */
+  instanceId: string | null;
+  /**
+   * The state last saved for this day (`hub.daily.save`, or `hub.resume.save`
+   * during the daily), or `null` when the day starts fresh. A game that
+   * saves restores from it: `if (challenge.saved) startFrom(challenge.saved)`.
+   */
+  saved: GamePayload | null;
+  /** The game's state version of `saved` (0 when none). */
+  savedVersion: number;
+  /** The day was already in progress and was picked up again. */
+  resumed?: boolean;
 }
 
 /** What `hub.daily.define` takes. */
 export interface DailyDefinition {
-  /** Start this challenge now. */
+  /** Start this challenge now (restore `challenge.saved` when it has one). */
   play: (challenge: DailyChallenge) => void;
 }
 
 /** Metadata a game records with a completion (`{ score, difficulty, timeMs, … }`). */
 export type DailyCompletionMeta = Record<string, Json>;
 
-/** What the daily system needs from the hub client: the REST calls and its window events. */
+/** A daily state save (the same shape as `hub.resume.save`). */
+export interface DailySaveInput {
+  /** Everything needed to rebuild the day's run (up to 512 KB as JSON). */
+  readonly state: GamePayload;
+  /** A short line ("34 cards left") and an optional 0 to 1 fraction. */
+  readonly progress: { readonly label: string; readonly fraction?: number | null };
+  readonly title?: string | null;
+  /** The game's state version (default 0). */
+  readonly version?: number;
+}
+
+/** What the daily system needs from the hub client: the REST calls, the device copy and its window events. */
 export interface DailyHost {
   /** This page's game slug. */
   readonly slug: string | null;
@@ -52,17 +77,29 @@ export interface DailyHost {
   status(): Promise<DailyStatus>;
   /** `GET /daily`. */
   all(): Promise<DailyAll>;
-  /** `POST /games/:slug/daily/:day/start`. */
+  /** Start (or pick up) a day: `POST /games/:slug/daily/:day/start`, or a device-only start while offline. */
   start(day: string): Promise<DailyStartResponse>;
+  /** Pick a day in progress up again by its saved game's id. */
+  resume(instanceId: string): Promise<DailyStartResponse>;
   /** `POST /games/:slug/daily/:day/complete`; `null` when it was queued offline, to replay when the hub is back. */
   complete(day: string, token: string, meta: DailyCompletionMeta): Promise<DailyCompleteResponse | null>;
+  /** Keep the day's state on the device at once and send it soon (works offline); `false` when it can't be stored. */
+  save(challenge: DailyChallenge, input: DailySaveInput): boolean;
+  /** Send a waiting save now. */
+  flush(): Promise<void>;
+  /** Give the day up: discard its saved game (works offline). */
+  discard(challenge: DailyChallenge): Promise<void>;
+  /** This game's days in progress (the saved games of kind daily). */
+  inProgress(): Promise<SavedEntry[]>;
   /** Fire a `hub:*` window event (the menu listens). */
   emit(name: string, detail: DailyEventDetail): void;
 }
 
 /** The detail of the `hub:daily-*` window events. */
 export type DailyEventDetail =
-  | { day: string; seed: number; alreadyCompleted: boolean }
+  | { day: string; seed: number; alreadyCompleted: boolean; resumed?: boolean }
   | { day: string; count: number; rank: number | null; meta: DailyCompletionMeta }
   | { day: string; queued: true; meta: DailyCompletionMeta }
+  | { day: string; paused: true }
+  | { day: string; discarded: true }
   | { day: string; error: string };

package/src/doctor/hub-version-fetch.ts

@@ -1,43 +1,43 @@
-/**
- * Reading the hub's `GET /_api/version` for `hub-doctor`, with a timeout so a
- * hung or unreachable hub fails a game's CI quickly instead of stalling it.
- */
-import { HubVersion } from '@diffenderfer-games/hub-contract';
-
-/** How long the doctor waits for the hub by default, ms. */
-export const DEFAULT_HUB_TIMEOUT_MS = 10_000;
-
-/** The hub could not be asked: down, slow, or answering with an error. */
-export interface HubUnreachable {
-  /** The URL that was asked. */
-  readonly unreachableUrl: string;
-  /** Why, for the message (`timed out after 10000 ms`, `HTTP 502`, a network error). */
-  readonly reason: string;
-}
-
-/** Whether a version lookup failed. */
-export function isHubUnreachable(lookup: HubVersion | null | HubUnreachable): lookup is HubUnreachable {
-  return lookup !== null && 'unreachableUrl' in lookup;
-}
-
-/**
- * The hub's version: `null` for a hub from before versioning (404), a
- * {@link HubUnreachable} when it can't be read within `timeoutMs`.
- */
-export async function fetchHubVersion(hubUrl: string, timeoutMs: number = DEFAULT_HUB_TIMEOUT_MS): Promise<HubVersion | null | HubUnreachable> {
-  const url = new URL('/_api/version', hubUrl).toString();
-  try {
-    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
-    if (response.status === 404) {
-      return null;
-    }
-    if (!response.ok) {
-      return { unreachableUrl: url, reason: `HTTP ${String(response.status)}` };
-    }
-    return HubVersion.parse(await response.json());
-  } catch (failure) {
-    const isTimeout = failure instanceof Error && (failure.name === 'TimeoutError' || failure.name === 'AbortError');
-    const reason = isTimeout ? `timed out after ${String(timeoutMs)} ms` : failure instanceof Error ? failure.message : String(failure);
-    return { unreachableUrl: url, reason };
-  }
-}
+/**
+ * Reading the hub's `GET /_api/version` for `hub-doctor`, with a timeout so a
+ * hung or unreachable hub fails a game's CI quickly instead of stalling it.
+ */
+import { HubVersion } from '@diffenderfer-games/hub-contract';
+
+/** How long the doctor waits for the hub by default, ms. */
+export const DEFAULT_HUB_TIMEOUT_MS = 10_000;
+
+/** The hub could not be asked: down, slow, or answering with an error. */
+export interface HubUnreachable {
+  /** The URL that was asked. */
+  readonly unreachableUrl: string;
+  /** Why, for the message (`timed out after 10000 ms`, `HTTP 502`, a network error). */
+  readonly reason: string;
+}
+
+/** Whether a version lookup failed. */
+export function isHubUnreachable(lookup: HubVersion | null | HubUnreachable): lookup is HubUnreachable {
+  return lookup !== null && 'unreachableUrl' in lookup;
+}
+
+/**
+ * The hub's version: `null` for a hub from before versioning (404), a
+ * {@link HubUnreachable} when it can't be read within `timeoutMs`.
+ */
+export async function fetchHubVersion(hubUrl: string, timeoutMs: number = DEFAULT_HUB_TIMEOUT_MS): Promise<HubVersion | null | HubUnreachable> {
+  const url = new URL('/_api/version', hubUrl).toString();
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      return { unreachableUrl: url, reason: `HTTP ${String(response.status)}` };
+    }
+    return HubVersion.parse(await response.json());
+  } catch (failure) {
+    const isTimeout = failure instanceof Error && (failure.name === 'TimeoutError' || failure.name === 'AbortError');
+    const reason = isTimeout ? `timed out after ${String(timeoutMs)} ms` : failure instanceof Error ? failure.message : String(failure);
+    return { unreachableUrl: url, reason };
+  }
+}

package/src/index.ts

@@ -17,7 +17,7 @@
  * queue their own operations with `hub.offline` (docs: "Offline and replay").
  *
  * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
- * `hub.daily`, `hub.resume`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
+ * `hub.daily`, `hub.resume`, `hub.saved`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
  * its own entry (`@diffenderfer-games/hub/input`, ...) for games that want
  * only that part.
  *
@@ -38,7 +38,16 @@ export type { AuthResponse, ProfileUpdate, StatResult } from './core/hub-progres
 export type { GrantBundle, TradeBundle, TradeId, TradeListOptions, TradeNoteOptions } from './core/hub-economy';
 export type { HubMenuControl } from './core/menu-control';
 export { HubResume, RESUME_DEBOUNCE_MS, RESUME_MAX_STATE_BYTES } from './core/resume/hub-resume';
+export { HubAvatar, type AvatarHost, type AvatarModule } from './core/avatar/hub-avatar';
+export type { AvatarChange, AvatarRef, DesignerResult, OpenDesignerOptions, RuntimeAvatarApi } from './core/avatar/avatar-types';
+export type { CarriesLook } from './core/avatar/avatar-ref';
 export type { ResumeBlocker, ResumeEntry, ResumeLoadOptions, ResumeProgress, ResumeRun, ResumeSaveInput } from './core/resume/resume-types';
+export { HubSaved, SAVED_CHANGE_QUIET_MS, type SavedChangeListener, type SavedOpenDetail, type SavedOpenHandler } from './core/saved/hub-saved';
+export { SAVED_CHANGE_EVENT, SAVED_KIND_PARAM, SAVED_OPEN_EVENT, SAVED_OPEN_PARAM, savedGameUrl } from './core/saved/saved-open';
+export type * from './core/saved/saved-types';
+export { HubTurns, TURN_LINK_PARAM, type TurnCreateOptions } from './core/turns/hub-turns';
+export { TURN_CHAT_EVENT, TURN_EVENT, TURN_POLL_MS, TURN_RESYNC_EVENT, TurnGame, type TurnGameEvents, type TurnMoveEvent, type TurnOutcome } from './core/turns/turn-game';
+export type { OpenTurnGame, TurnChatLine, TurnDeadline, TurnGameView } from '@diffenderfer-games/hub-contract';
 export type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
 export { OfflineApi } from './core/offline/offline-api';
 export { OUTBOX_FULL_CODE, type OfflineEventDetails, type OfflineEventName, type OfflineListener, type OfflineOp } from './core/offline/outbox';

package/src/input/input-system.ts

@@ -18,7 +18,7 @@ import type { ModalityTracker } from './modality';
 import { parseLegacyControls } from './legacy-controls';
 import type { LegacyControls } from './legacy-controls';
 import { Navigator } from './navigator';
-import type { NavigatorContext } from './navigator';
+import type { AutoNavigateTarget, NavigatorContext } from './navigator';
 import { feedDeviceState, OnScreenControls } from './on-screen-controls';
 import type { PageInputControl } from './page-control';
 import { describeBinding, PlayerRemaps } from './player-remaps';
@@ -286,6 +286,15 @@ export class InputSystem implements ControlsPanelHost, PageInputControl {
     this.navigator.setAutoNavigate(Navigator.queryFor(selector), options?.back ?? null);
   }
 
+  /**
+   * The game's current `autoNavigate` target (its query and back action), or
+   * `null`. Hub UI that takes the gamepad for a while (a dialog) reads it,
+   * and gives it back with `autoNavigate(target.query, { back })` when done.
+   */
+  autoNavigateTarget(): AutoNavigateTarget | null {
+    return this.navigator.autoNavigateTarget();
+  }
+
   /** Stop navigating the game's own menu. */
   clearAutoNavigate(): void {
     this.navigator.clearAutoNavigate(this.controls.existingOverlay);

package/src/input/navigator.ts

@@ -40,6 +40,12 @@ function visibleMatches(selector: string): HTMLElement[] {
   return [...document.querySelectorAll<HTMLElement>(selector)].filter((element) => element.getClientRects().length > 0);
 }
 
+/** What `autoNavigate` was last given: the targets' query and the back action. */
+export interface AutoNavigateTarget {
+  readonly query: () => NavTarget[];
+  readonly back: (() => void) | null;
+}
+
 /** A navigable group with its highlight state. */
 interface GroupNavigation {
   readonly definition: NavigableDef;
@@ -81,6 +87,11 @@ export class Navigator {
     this.autoNavigateState = null;
   }
 
+  /** The current auto-navigate target and back action, or `null` when none is set. */
+  autoNavigateTarget(): AutoNavigateTarget | null {
+    return this.autoNavigateQuery === null ? null : { query: this.autoNavigateQuery, back: this.autoNavigateBack };
+  }
+
   /** Make a CSS selector's visible matches the auto-navigate targets. */
   static queryFor(selector: string | (() => NavTarget[])): () => NavTarget[] {
     return typeof selector === 'string' ? () => visibleMatches(selector) : selector;

package/src/input.ts

@@ -15,6 +15,7 @@ export type { InputModality } from './input/modality';
 export { isPageInputControl } from './input/page-control';
 export type { PageInputControl } from './input/page-control';
 export type * from './input/types';
+export type { AutoNavigateTarget } from './input/navigator';
 export { Overlay } from './overlay/overlay';
 export { layoutControls } from './overlay/layout';
 export type { LayoutOptions } from './overlay/layout';

package/src/overlay/overlay.ts

@@ -123,9 +123,15 @@ export class Overlay implements NavHighlighter {
     }
   }
 
-  /** Game insets (px) auto-placed controls keep clear of, e.g. a top HUD bar. Merged with earlier calls. */
+  /**
+   * Game insets (px) auto-placed controls keep clear of, e.g. a top HUD bar.
+   * Merged with earlier calls. Also published on the page as
+   * `--hub-inset-top` (and right, bottom, left), so the hub's toasts sit
+   * below a top HUD too.
+   */
   setInsets(insets: Partial<Insets>): void {
     this.gameInsets = { ...this.gameInsets, ...insets };
+    publishInsets(this.gameInsets);
     this.layout();
   }
 
@@ -208,3 +214,21 @@ export class Overlay implements NavHighlighter {
     return { top: pixels(style.paddingTop), right: pixels(style.paddingRight), bottom: pixels(style.paddingBottom), left: pixels(style.paddingLeft) };
   }
 }
+
+/** Every inset side. */
+const INSET_SIDES: readonly (keyof Insets)[] = ['top', 'right', 'bottom', 'left'];
+
+/** The page-wide CSS variables other hub UI (the runtime's toasts) keeps clear of. */
+function publishInsets(insets: Partial<Insets>): void {
+  if (typeof document === 'undefined') {
+    return;
+  }
+  for (const side of INSET_SIDES) {
+    const px = insets[side];
+    if (px === undefined) {
+      document.documentElement.style.removeProperty(`--hub-inset-${side}`);
+    } else {
+      document.documentElement.style.setProperty(`--hub-inset-${side}`, `${String(Math.max(0, Math.round(px)))}px`);
+    }
+  }
+}

package/src/realtime/runtime-api.ts

@@ -3,6 +3,7 @@
  * the page, and that `hub.presence`, `hub.social`, `hub.mp`, `hub.rooms`,
  * `hub.notify` and `hub.race` forward to.
  */
+import type { RuntimeAvatarApi } from '../core/avatar/avatar-types';
 import type { HubMpApi, InviteLinkMethods } from './multiplayer-types';
 import type { HubRaceApi } from './race-types';
 import type { HubRoomsApi, RoomReclaimMethods } from './room-types';
@@ -11,10 +12,10 @@ import type { HubNotifyApi, HubPresenceApi, HubSocialApi, PlayOnlineMethods } fr
 /**
  * The realtime feature version the runtime reports in {@link RealtimeApi.version}.
  * 2 added races; 3 added invite links and taking back a held seat; 4 added
- * "Play online" (tournaments). A client feature-detects newer additions with
- * it (or by the optional method).
+ * "Play online" (tournaments); 5 added avatars (the designer and `ev:avatar`).
+ * A client feature-detects newer additions with it (or by the optional method).
  */
-export const REALTIME_FEATURE_VERSION = 4;
+export const REALTIME_FEATURE_VERSION = 5;
 
 /** `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>;
@@ -35,6 +36,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';
 
@@ -57,4 +66,6 @@ export interface RealtimeApi {
   notify: HubNotifyApi;
   /** Races (feature version 2 and later). */
   race?: HubRaceApi;
+  /** Avatars: the designer and live changes (feature version 5 and later). */
+  avatar?: RuntimeAvatarApi;
 }

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,182 @@
+/**
+ * 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;
+ * - 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` (when the rules have it) is 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;
+ * - 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';
+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;
+  /**
+   * 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;
+  /** 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;
+}
+
+/** 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);
+}
+
+/** 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; trace: string } {
+  const rng = createTurnRng(turnRngStateFromSeed(seed));
+  const marker = `MARKER-${String(seed)}-`;
+  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, `${marker}${String(seat)}`);
+    }
+  }
+  const maxMoves = options.maxMoves ?? 2000;
+  const trace: string[] = [];
+  const checkViews = (events: readonly Event[]): void => {
+    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 (let owner = 0; owner < seats; owner++) {
+        if (owner !== viewer && options.plant !== undefined && seen.includes(`${marker}${String(owner)}`)) {
+          fail(`seat ${String(viewer)} can see seat ${String(owner)}'s secret (seed ${String(seed)})`);
+        }
+      }
+    }
+    if (options.plant !== undefined && JSON.stringify(rules.view(state, null)).includes(marker)) {
+      fail(`the public view shows a seat's secret (seed ${String(seed)})`);
+    }
+  };
+  checkViews([]);
+  for (let moves = 0; moves < maxMoves; moves++) {
+    if (rules.outcome(state) !== null) {
+      return { moves, trace: trace.join('|') };
+    }
+    const toAct = rules.toAct(state);
+    const seat = toAct[0];
+    if (seat === undefined) {
+      fail(`toAct is empty but there is no outcome yet (seed ${String(seed)}, move ${String(moves)})`);
+    }
+    const move = pickMove(rules, options, state, seat, rng);
+    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(`${options.randomMove === undefined ? 'autoMove' : 'randomMove'} 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(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;
+  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);
+    }
+  }
+  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 };
+}

package/src/turns.ts

@@ -0,0 +1,13 @@
+/**
+ * `@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.
+ *
+ * @packageDocumentation
+ */
+export { createTurnRng, defineTurnRules, turnRngStateFromSeed } from '@diffenderfer-games/hub-contract';
+export type { TurnApplyResult, TurnOutcome, TurnProgress, TurnRng, TurnRngState, TurnRules, TurnSetupContext } from '@diffenderfer-games/hub-contract';
+export { checkTurnRules, type TurnRulesCheckOptions, type TurnRulesReport } from './turns-kit/check-rules';