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

package/src/realtime/multiplayer-types.ts

@@ -1,52 +1,52 @@
-/**
- * The multiplayer lifecycle as games see it through `hub.mp`: invites,
- * launches, the leave guard and own-server tickets.
- */
-import type { Invite, JoinInfo, Launch, Party } from '@diffenderfer-games/hub-contract';
-
-/** `hub.mp.onJoinInfo` payload: the party leader published where to connect. */
-export interface JoinInfoEvent {
-  /** The party it is for. */
-  partyId: string;
-  /** Opaque connection details (a room code, a server address…). */
-  info: JoinInfo;
-}
-
-/** What `hub.mp.invite` resolves with. */
-export interface InviteResult {
-  /** The invite as sent. */
-  invite: Invite;
-}
-
-/** Options for `hub.mp.invite`. */
-export interface InviteOptions {
-  /** The game mode to invite to. */
-  mode?: string;
-}
-
-/** Options for `hub.mp.setBusy`. */
-export interface BusyOptions {
-  /** What the leave-confirmation calls the match ("a duel"). */
-  label?: string;
-}
-
-/** `hub.mp`: the multiplayer lifecycle (docs/multiplayer.md §7). */
-export interface HubMpApi {
-  /** Invite, join and watch arrivals. Call at boot; launches that arrived earlier are buffered. */
-  onLaunch(listener: (launch: Launch) => void): () => void;
-  /** The party leader published join info (e.g. a room code). */
-  onJoinInfo(listener: (event: JoinInfoEvent) => void): () => void;
-  /** Invite a friend to this game. Rejects with `HubError` or `OfflineError`. */
-  invite(userId: number, options?: InviteOptions): Promise<InviteResult>;
-  /**
-   * A live match is in progress: the hub confirms before navigating away and
-   * overlay events carry `canPause: false`.
-   */
-  setBusy(isBusy: boolean, options?: BusyOptions): void;
-  /** A 60-second identity ticket for your own game server. */
-  ticket(): Promise<string>;
-  /** Host side, own-server games: tell the party where to connect. */
-  setJoinInfo(partyId: string, joinInfo: JoinInfo): Promise<void>;
-  /** My current party, or `null` (also `null` until the runtime is up). */
-  party(): Party | null;
-}
+/**
+ * The multiplayer lifecycle as games see it through `hub.mp`: invites,
+ * launches, the leave guard and own-server tickets.
+ */
+import type { Invite, JoinInfo, Launch, Party } from '@diffenderfer-games/hub-contract';
+
+/** `hub.mp.onJoinInfo` payload: the party leader published where to connect. */
+export interface JoinInfoEvent {
+  /** The party it is for. */
+  partyId: string;
+  /** Opaque connection details (a room code, a server address…). */
+  info: JoinInfo;
+}
+
+/** What `hub.mp.invite` resolves with. */
+export interface InviteResult {
+  /** The invite as sent. */
+  invite: Invite;
+}
+
+/** Options for `hub.mp.invite`. */
+export interface InviteOptions {
+  /** The game mode to invite to. */
+  mode?: string;
+}
+
+/** Options for `hub.mp.setBusy`. */
+export interface BusyOptions {
+  /** What the leave-confirmation calls the match ("a duel"). */
+  label?: string;
+}
+
+/** `hub.mp`: the multiplayer lifecycle (docs/multiplayer.md §7). */
+export interface HubMpApi {
+  /** Invite, join and watch arrivals. Call at boot; launches that arrived earlier are buffered. */
+  onLaunch(listener: (launch: Launch) => void): () => void;
+  /** The party leader published join info (e.g. a room code). */
+  onJoinInfo(listener: (event: JoinInfoEvent) => void): () => void;
+  /** Invite a friend to this game. Rejects with `HubError` or `OfflineError`. */
+  invite(userId: number, options?: InviteOptions): Promise<InviteResult>;
+  /**
+   * A live match is in progress: the hub confirms before navigating away and
+   * overlay events carry `canPause: false`.
+   */
+  setBusy(isBusy: boolean, options?: BusyOptions): void;
+  /** A 60-second identity ticket for your own game server. */
+  ticket(): Promise<string>;
+  /** Host side, own-server games: tell the party where to connect. */
+  setJoinInfo(partyId: string, joinInfo: JoinInfo): Promise<void>;
+  /** My current party, or `null` (also `null` until the runtime is up). */
+  party(): Party | null;
+}

package/src/realtime/page-runtime.ts

@@ -1,60 +1,60 @@
-/**
- * Finding the social runtime's realtime API on the page. The runtime owns the
- * `rt` singleton (plan §4.4): it registers on `window.__DG__.rt`, and older
- * runtimes only set the v1 name `window.__HUB_RT__`.
- */
-import { LEGACY_GLOBAL_NAMES } from '../globals';
-import { hasMethods, isObject, readField } from './cross-bundle';
-import type { RealtimeApi } from './runtime-api';
-import { REALTIME_SINGLETON_API } from './runtime-api';
-
-/** Whether `candidate` looks like a {@link RealtimeApi} (any bundle's). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the runtime is another bundle
-export function isRealtimeApi(candidate: unknown): candidate is RealtimeApi {
-  return typeof readField(candidate, 'version') === 'number'
-    && hasMethods(readField(candidate, 'presence'), ['set', 'clear'])
-    && hasMethods(readField(candidate, 'social'), ['openPlayer', 'friends', 'counts', 'chatMode', 'on'])
-    && hasMethods(readField(candidate, 'mp'), ['onLaunch', 'onJoinInfo', 'invite', 'setBusy', 'party'])
-    && hasMethods(readField(candidate, 'rooms'), ['create', 'join', 'list'])
-    && hasMethods(readField(candidate, 'notify'), ['setQuiet']);
-}
-
-let hasWarnedAboutApi = false;
-
-/** Warn once when the runtime registered a different shape number than this client knows. */
-function warnOnApiMismatch(registeredApi: number): void {
-  if (registeredApi === REALTIME_SINGLETON_API || hasWarnedAboutApi) {
-    return;
-  }
-  hasWarnedAboutApi = true;
-  // eslint-disable-next-line no-console -- the plan's one-time warning to the game developer, with the fix
-  console.warn(`[hub] this page's social runtime speaks realtime api ${String(registeredApi)}, this client api ${String(REALTIME_SINGLETON_API)}. Fix: npm update @diffenderfer-games/hub`);
-}
-
-/** The page's realtime API if the runtime has loaded, else `null`. */
-export function findRealtimeApi(): RealtimeApi | null {
-  if (typeof window === 'undefined') {
-    return null;
-  }
-  const registered = window.__DG__?.rt;
-  if (registered !== undefined && isRealtimeApi(registered.instance)) {
-    warnOnApiMismatch(registered.api);
-    return registered.instance;
-  }
-  const legacy = window[LEGACY_GLOBAL_NAMES.rt];
-  return isRealtimeApi(legacy) ? legacy : null;
-}
-
-/** Whether the hub injected this page (`window.__HUB__`); without it the runtime can never arrive. */
-export function isHubInjectedPage(): boolean {
-  return typeof window !== 'undefined' && isObject(readField(window, '__HUB__'));
-}
-
-/** Why the social runtime failed to load on this page (set by the menu), or `''`. */
-export function readRuntimeFailure(): string {
-  if (typeof window === 'undefined') {
-    return '';
-  }
-  const failure = readField(window, '__HUB_RT_ERROR__');
-  return typeof failure === 'string' ? failure.slice(0, 120) : '';
-}
+/**
+ * Finding the social runtime's realtime API on the page. The runtime owns the
+ * `rt` singleton (plan §4.4): it registers on `window.__DG__.rt`, and older
+ * runtimes only set the v1 name `window.__HUB_RT__`.
+ */
+import { LEGACY_GLOBAL_NAMES } from '../globals';
+import { hasMethods, isObject, readField } from './cross-bundle';
+import type { RealtimeApi } from './runtime-api';
+import { REALTIME_SINGLETON_API } from './runtime-api';
+
+/** Whether `candidate` looks like a {@link RealtimeApi} (any bundle's). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the runtime is another bundle
+export function isRealtimeApi(candidate: unknown): candidate is RealtimeApi {
+  return typeof readField(candidate, 'version') === 'number'
+    && hasMethods(readField(candidate, 'presence'), ['set', 'clear'])
+    && hasMethods(readField(candidate, 'social'), ['openPlayer', 'friends', 'counts', 'chatMode', 'on'])
+    && hasMethods(readField(candidate, 'mp'), ['onLaunch', 'onJoinInfo', 'invite', 'setBusy', 'party'])
+    && hasMethods(readField(candidate, 'rooms'), ['create', 'join', 'list'])
+    && hasMethods(readField(candidate, 'notify'), ['setQuiet']);
+}
+
+let hasWarnedAboutApi = false;
+
+/** Warn once when the runtime registered a different shape number than this client knows. */
+function warnOnApiMismatch(registeredApi: number): void {
+  if (registeredApi === REALTIME_SINGLETON_API || hasWarnedAboutApi) {
+    return;
+  }
+  hasWarnedAboutApi = true;
+  // eslint-disable-next-line no-console -- the plan's one-time warning to the game developer, with the fix
+  console.warn(`[hub] this page's social runtime speaks realtime api ${String(registeredApi)}, this client api ${String(REALTIME_SINGLETON_API)}. Fix: npm update @diffenderfer-games/hub`);
+}
+
+/** The page's realtime API if the runtime has loaded, else `null`. */
+export function findRealtimeApi(): RealtimeApi | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+  const registered = window.__DG__?.rt;
+  if (registered !== undefined && isRealtimeApi(registered.instance)) {
+    warnOnApiMismatch(registered.api);
+    return registered.instance;
+  }
+  const legacy = window[LEGACY_GLOBAL_NAMES.rt];
+  return isRealtimeApi(legacy) ? legacy : null;
+}
+
+/** Whether the hub injected this page (`window.__HUB__`); without it the runtime can never arrive. */
+export function isHubInjectedPage(): boolean {
+  return typeof window !== 'undefined' && isObject(readField(window, '__HUB__'));
+}
+
+/** Why the social runtime failed to load on this page (set by the menu), or `''`. */
+export function readRuntimeFailure(): string {
+  if (typeof window === 'undefined') {
+    return '';
+  }
+  const failure = readField(window, '__HUB_RT_ERROR__');
+  return typeof failure === 'string' ? failure.slice(0, 120) : '';
+}

package/src/realtime/race-forwarder.ts

@@ -1,59 +1,59 @@
-/**
- * `hub.race`: races, forwarded to the social runtime. An old cached runtime
- * (feature version 1) has no races, which reads as "not available" rather
- * than a crash.
- */
-import { pageBridge } from './bridge';
-import { hubLink } from './hub-link';
-import type { HubRaceApi, RaceDefinition } from './race-types';
-import type { RealtimeApi } from './runtime-api';
-import { createRuntimeOpener } from './runtime-opener';
-
-const openWithRuntime = createRuntimeOpener(pageBridge);
-
-let raceDefinition: RaceDefinition | null = null;
-pageBridge.onReady((realtime) => {
-  if (raceDefinition !== null) {
-    realtime.race?.define(raceDefinition);
-  }
-});
-
-/** The runtime's race section, or an `OfflineError` for a runtime too old to race. */
-function requireRaces(realtime: RealtimeApi): HubRaceApi {
-  if (realtime.race === undefined) {
-    throw hubLink().createOfflineError('Races need the latest hub — reload the page.');
-  }
-  return realtime.race;
-}
-
-/** `hub.race`: races. */
-export const raceForwarder: HubRaceApi = {
-  define(definition) {
-    raceDefinition = definition;
-    pageBridge.current()?.race?.define(definition);
-  },
-  create: (options) => pageBridge.call((realtime) => requireRaces(realtime).create(options)),
-  join: (code, options) => pageBridge.call((realtime) => requireRaces(realtime).join(code, options)),
-  list: () => pageBridge.call((realtime) => requireRaces(realtime).list()),
-  browse: () => {
-    openWithRuntime((realtime) => {
-      realtime.race?.browse();
-    });
-  },
-  openHistory: (options) => {
-    openWithRuntime((realtime) => {
-      realtime.race?.openHistory(options);
-    });
-  },
-  history: (query) => pageBridge.call((realtime) => requireRaces(realtime).history(query)),
-  status: (stats, progress) => {
-    pageBridge.current()?.race?.status(stats, progress);
-  },
-  finish: (stats) => pageBridge.call((realtime) => requireRaces(realtime).finish(stats)),
-  lose: (stats) => pageBridge.call((realtime) => requireRaces(realtime).lose(stats)),
-  forfeit: () => pageBridge.call((realtime) => requireRaces(realtime).forfeit()),
-  leave: () => pageBridge.call((realtime) => requireRaces(realtime).leave()),
-  rematch: (params) => pageBridge.call((realtime) => requireRaces(realtime).rematch(params)),
-  current: () => pageBridge.current()?.race?.current() ?? null,
-  on: (event, listener) => pageBridge.subscribe((realtime) => realtime.race?.on(event, listener) ?? (() => undefined)),
-};
+/**
+ * `hub.race`: races, forwarded to the social runtime. An old cached runtime
+ * (feature version 1) has no races, which reads as "not available" rather
+ * than a crash.
+ */
+import { pageBridge } from './bridge';
+import { hubLink } from './hub-link';
+import type { HubRaceApi, RaceDefinition } from './race-types';
+import type { RealtimeApi } from './runtime-api';
+import { createRuntimeOpener } from './runtime-opener';
+
+const openWithRuntime = createRuntimeOpener(pageBridge);
+
+let raceDefinition: RaceDefinition | null = null;
+pageBridge.onReady((realtime) => {
+  if (raceDefinition !== null) {
+    realtime.race?.define(raceDefinition);
+  }
+});
+
+/** The runtime's race section, or an `OfflineError` for a runtime too old to race. */
+function requireRaces(realtime: RealtimeApi): HubRaceApi {
+  if (realtime.race === undefined) {
+    throw hubLink().createOfflineError('Races need the latest hub — reload the page.');
+  }
+  return realtime.race;
+}
+
+/** `hub.race`: races. */
+export const raceForwarder: HubRaceApi = {
+  define(definition) {
+    raceDefinition = definition;
+    pageBridge.current()?.race?.define(definition);
+  },
+  create: (options) => pageBridge.call((realtime) => requireRaces(realtime).create(options)),
+  join: (code, options) => pageBridge.call((realtime) => requireRaces(realtime).join(code, options)),
+  list: () => pageBridge.call((realtime) => requireRaces(realtime).list()),
+  browse: () => {
+    openWithRuntime((realtime) => {
+      realtime.race?.browse();
+    });
+  },
+  openHistory: (options) => {
+    openWithRuntime((realtime) => {
+      realtime.race?.openHistory(options);
+    });
+  },
+  history: (query) => pageBridge.call((realtime) => requireRaces(realtime).history(query)),
+  status: (stats, progress) => {
+    pageBridge.current()?.race?.status(stats, progress);
+  },
+  finish: (stats) => pageBridge.call((realtime) => requireRaces(realtime).finish(stats)),
+  lose: (stats) => pageBridge.call((realtime) => requireRaces(realtime).lose(stats)),
+  forfeit: () => pageBridge.call((realtime) => requireRaces(realtime).forfeit()),
+  leave: () => pageBridge.call((realtime) => requireRaces(realtime).leave()),
+  rematch: (params) => pageBridge.call((realtime) => requireRaces(realtime).rematch(params)),
+  current: () => pageBridge.current()?.race?.current() ?? null,
+  on: (event, listener) => pageBridge.subscribe((realtime) => realtime.race?.on(event, listener) ?? (() => undefined)),
+};

package/src/realtime/race-types.ts

@@ -1,132 +1,132 @@
-/**
- * Races as games see them through `hub.race` (docs/plans/race.md): a hub
- * room with a referee. Everyone gets the same puzzle (shared seed and
- * params), live status, and the first valid finish wins.
- */
-import type { RaceParams, RaceResult, RaceStats, RoomInfo } from '@diffenderfer-games/hub-contract';
-import type { RaceHistory, RaceStatusEvent } from './wire-types';
-import type { JoinOptions } from './room-types';
-
-/** What a race game's `start` receives: build the puzzle from `seed` and `params`. */
-export interface RaceStart {
-  /** The race room. */
-  roomId: string;
-  /** 1 for the first race in the room, +1 per rematch. */
-  round: number;
-  /** The shared seed, revealed at the countdown. */
-  seed: number;
-  /** The creator's choices. */
-  params: RaceParams;
-  /** The go, on THIS page's clock (`Date.now()` ms). The hub draws the 3-2-1. */
-  startAt: number;
-  /** Racer user ids. */
-  players: number[];
-  /** Watching: don't let a spectator play. */
-  spectator: boolean;
-  /** A re-join after a reload or reconnect (the race was already running). */
-  resumed: boolean;
-}
-
-/** Options for `hub.race.create`. */
-export interface RaceCreateOptions {
-  /** The race params (defaults from the manifest). */
-  params?: RaceParams;
-  /** Public (default true): shows in Open races and can alert friends who follow the game. */
-  public?: boolean;
-  /** Seats (default the manifest's minimum). The race starts when they're all filled. */
-  maxPlayers?: number;
-  /** Race this party. */
-  partyId?: string;
-}
-
-/** Where the hub's race HUD sits. */
-export type RaceHudPlace = 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-
-/** `hub.race.define`: how the hub drives a race game. */
-export interface RaceDefinition {
-  /** The countdown began: build the puzzle from `seed` and `params` now and let the player move at `startAt`. */
-  start(race: RaceStart): void;
-  /** The race was decided (stop input; the hub shows the result card). */
-  end?(result: RaceResult): void;
-  /** The player left the race screen (Done, cancelled, the room closed): go back to your menu. */
-  exit?(): void;
-  /** The hub's live race HUD (default on, top). `false` if you draw your own from `hub.race.on('status')`. */
-  hud?: false | { place?: RaceHudPlace };
-}
-
-/** Events `hub.race.on` delivers, name → payload. */
-export interface RaceEvents {
-  /** The race room changed (roster, phase, statuses folded in). */
-  room: RoomInfo;
-  /** The countdown began. */
-  start: RaceStart;
-  /** Another racer's live status. */
-  status: RaceStatusEvent;
-  /** The race was decided. */
-  result: RaceResult;
-  /** The race room is gone for this page (left, closed, kicked). */
-  closed: { reason: string };
-}
-
-/** Filters for the race history. */
-export interface RaceHistoryQuery {
-  /** A game slug (default: every game). */
-  game?: string;
-  /** Only races with this player. */
-  with?: number;
-  /** Only races older than this race id (paging). */
-  before?: number;
-  /** Page size, 1 to 50. */
-  limit?: number;
-}
-
-/** Options for `hub.race.openHistory`. */
-export interface RaceHistoryViewOptions {
-  /** This game (default), another slug, or `null` for every game. */
-  game?: string | null;
-  /** Only races with this player. */
-  with?: number;
-}
-
-/**
- * `hub.race`: races (docs/multiplayer.md "Races"). Declare `game.race` in
- * package.json, call `define` at boot, put a Race button on your menu that
- * calls `create({ params })` (or `browse()`), and report `status`, `finish`
- * and `lose`. The hub does the matching, the waiting card, invites, the
- * countdown, the live HUD, the referee, the result card and the history.
- */
-export interface HubRaceApi {
-  /** Register how the hub starts and ends your race. Call once at boot (works before the runtime loads). */
-  define(definition: RaceDefinition): void;
-  /** Create a race (you're seated; the hub shows the waiting card). Rejects with `HubError` or `OfflineError`. */
-  create(options?: RaceCreateOptions): Promise<RoomInfo>;
-  /** Join a race by its 5-character code (or watch: `{ spectate: true }`). */
-  join(code: string, options?: JoinOptions): Promise<RoomInfo>;
-  /** Public races in this game waiting for racers. */
-  list(): Promise<RoomInfo[]>;
-  /** Open the hub's "Open races" sheet (join one, or type a code). */
-  browse(): void;
-  /** Open the hub's race history (this game by default). */
-  openHistory(options?: RaceHistoryViewOptions): void;
-  /** The signed-in player's races. */
-  history(query?: RaceHistoryQuery): Promise<RaceHistory>;
-  /** Live stats for the HUD (and optional 0..1 progress). Throttled and coalesced: call it on every change. */
-  status(stats: RaceStats, progress?: number): void;
-  /** I finished: resolves with the result if I won, `null` if someone was first. */
-  finish(stats?: RaceStats): Promise<RaceResult | null>;
-  /** I'm out (game over, no lives): the others race on, the last one in wins. */
-  lose(stats?: RaceStats): Promise<void>;
-  /** Give up. */
-  forfeit(): Promise<void>;
-  /** Leave the race room (a forfeit if it's running). */
-  leave(): Promise<void>;
-  /** Ask for another round after a race. */
-  rematch(params?: RaceParams): Promise<void>;
-  /** The race room this page is in (its `RoomInfo` has `race`), or `null`. */
-  current(): RoomInfo | null;
-  /** Subscribe to race events; works before the runtime loads. Returns the unsubscribe function. */
-  on<Name extends keyof RaceEvents>(event: Name, listener: (payload: RaceEvents[Name]) => void): () => void;
-}
-
-/** What the runtime's `race` section implements (the same surface `hub.race` forwards). */
-export type RaceRuntimeApi = HubRaceApi;
+/**
+ * Races as games see them through `hub.race` (docs/plans/race.md): a hub
+ * room with a referee. Everyone gets the same puzzle (shared seed and
+ * params), live status, and the first valid finish wins.
+ */
+import type { RaceParams, RaceResult, RaceStats, RoomInfo } from '@diffenderfer-games/hub-contract';
+import type { RaceHistory, RaceStatusEvent } from './wire-types';
+import type { JoinOptions } from './room-types';
+
+/** What a race game's `start` receives: build the puzzle from `seed` and `params`. */
+export interface RaceStart {
+  /** The race room. */
+  roomId: string;
+  /** 1 for the first race in the room, +1 per rematch. */
+  round: number;
+  /** The shared seed, revealed at the countdown. */
+  seed: number;
+  /** The creator's choices. */
+  params: RaceParams;
+  /** The go, on THIS page's clock (`Date.now()` ms). The hub draws the 3-2-1. */
+  startAt: number;
+  /** Racer user ids. */
+  players: number[];
+  /** Watching: don't let a spectator play. */
+  spectator: boolean;
+  /** A re-join after a reload or reconnect (the race was already running). */
+  resumed: boolean;
+}
+
+/** Options for `hub.race.create`. */
+export interface RaceCreateOptions {
+  /** The race params (defaults from the manifest). */
+  params?: RaceParams;
+  /** Public (default true): shows in Open races and can alert friends who follow the game. */
+  public?: boolean;
+  /** Seats (default the manifest's minimum). The race starts when they're all filled. */
+  maxPlayers?: number;
+  /** Race this party. */
+  partyId?: string;
+}
+
+/** Where the hub's race HUD sits. */
+export type RaceHudPlace = 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+/** `hub.race.define`: how the hub drives a race game. */
+export interface RaceDefinition {
+  /** The countdown began: build the puzzle from `seed` and `params` now and let the player move at `startAt`. */
+  start(race: RaceStart): void;
+  /** The race was decided (stop input; the hub shows the result card). */
+  end?(result: RaceResult): void;
+  /** The player left the race screen (Done, cancelled, the room closed): go back to your menu. */
+  exit?(): void;
+  /** The hub's live race HUD (default on, top). `false` if you draw your own from `hub.race.on('status')`. */
+  hud?: false | { place?: RaceHudPlace };
+}
+
+/** Events `hub.race.on` delivers, name → payload. */
+export interface RaceEvents {
+  /** The race room changed (roster, phase, statuses folded in). */
+  room: RoomInfo;
+  /** The countdown began. */
+  start: RaceStart;
+  /** Another racer's live status. */
+  status: RaceStatusEvent;
+  /** The race was decided. */
+  result: RaceResult;
+  /** The race room is gone for this page (left, closed, kicked). */
+  closed: { reason: string };
+}
+
+/** Filters for the race history. */
+export interface RaceHistoryQuery {
+  /** A game slug (default: every game). */
+  game?: string;
+  /** Only races with this player. */
+  with?: number;
+  /** Only races older than this race id (paging). */
+  before?: number;
+  /** Page size, 1 to 50. */
+  limit?: number;
+}
+
+/** Options for `hub.race.openHistory`. */
+export interface RaceHistoryViewOptions {
+  /** This game (default), another slug, or `null` for every game. */
+  game?: string | null;
+  /** Only races with this player. */
+  with?: number;
+}
+
+/**
+ * `hub.race`: races (docs/multiplayer.md "Races"). Declare `game.race` in
+ * package.json, call `define` at boot, put a Race button on your menu that
+ * calls `create({ params })` (or `browse()`), and report `status`, `finish`
+ * and `lose`. The hub does the matching, the waiting card, invites, the
+ * countdown, the live HUD, the referee, the result card and the history.
+ */
+export interface HubRaceApi {
+  /** Register how the hub starts and ends your race. Call once at boot (works before the runtime loads). */
+  define(definition: RaceDefinition): void;
+  /** Create a race (you're seated; the hub shows the waiting card). Rejects with `HubError` or `OfflineError`. */
+  create(options?: RaceCreateOptions): Promise<RoomInfo>;
+  /** Join a race by its 5-character code (or watch: `{ spectate: true }`). */
+  join(code: string, options?: JoinOptions): Promise<RoomInfo>;
+  /** Public races in this game waiting for racers. */
+  list(): Promise<RoomInfo[]>;
+  /** Open the hub's "Open races" sheet (join one, or type a code). */
+  browse(): void;
+  /** Open the hub's race history (this game by default). */
+  openHistory(options?: RaceHistoryViewOptions): void;
+  /** The signed-in player's races. */
+  history(query?: RaceHistoryQuery): Promise<RaceHistory>;
+  /** Live stats for the HUD (and optional 0..1 progress). Throttled and coalesced: call it on every change. */
+  status(stats: RaceStats, progress?: number): void;
+  /** I finished: resolves with the result if I won, `null` if someone was first. */
+  finish(stats?: RaceStats): Promise<RaceResult | null>;
+  /** I'm out (game over, no lives): the others race on, the last one in wins. */
+  lose(stats?: RaceStats): Promise<void>;
+  /** Give up. */
+  forfeit(): Promise<void>;
+  /** Leave the race room (a forfeit if it's running). */
+  leave(): Promise<void>;
+  /** Ask for another round after a race. */
+  rematch(params?: RaceParams): Promise<void>;
+  /** The race room this page is in (its `RoomInfo` has `race`), or `null`. */
+  current(): RoomInfo | null;
+  /** Subscribe to race events; works before the runtime loads. Returns the unsubscribe function. */
+  on<Name extends keyof RaceEvents>(event: Name, listener: (payload: RaceEvents[Name]) => void): () => void;
+}
+
+/** What the runtime's `race` section implements (the same surface `hub.race` forwards). */
+export type RaceRuntimeApi = HubRaceApi;