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

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;

package/src/realtime/room-types.ts

@@ -1,125 +1,151 @@
-/**
- * Hub relay rooms as games see them through `hub.rooms`: realtime
- * multiplayer for static games, relayed (never refereed) by the hub.
- */
-import type { Json, RoomInfo } from '@diffenderfer-games/hub-contract';
-import type { RoomChatLine, RoomMessage } from './wire-types';
-
-/** The shared room state (a JSON object, at most 32 KB). */
-export type RoomState = Record<string, Json>;
-
-/** Options for `hub.rooms.create`. `game` defaults to the current slug. */
-export interface RoomCreateOptions {
-  /** The game slug (default: this page's game). */
-  game?: string;
-  /** The game mode. */
-  mode?: string;
-  /** Listed in `hub.rooms.list` (default false). */
-  public?: boolean;
-  /** Seats. */
-  maxPlayers?: number;
-  /** `host` (default): guests' unaddressed sends reach the host only. `relay`: everyone hears every send. */
-  model?: 'host' | 'relay';
-  /** Seat this party in the room. */
-  partyId?: string;
-}
-
-/** Options for joining a room or race. */
-export interface JoinOptions {
-  /** Watch instead of taking a seat (if the game allows spectators). */
-  spectate?: boolean;
-}
-
-/** Events a {@link HubRoom} emits, name → payload. */
-export interface RoomEvents {
-  /** The room changed: roster, ready flags, phase, host. */
-  room: RoomInfo;
-  /** A relayed game message. */
-  msg: RoomMessage;
-  /** The shared state after a change. */
-  state: RoomState;
-  /** A moderated chat line. */
-  chat: RoomChatLine;
-  /** The host removed me. */
-  kicked: { roomId: string };
-  /**
-   * The room is gone for this tab. `reason`: empty, ended, host_left,
-   * other_tab, moved, removed, or `gone` (client-side: the seat couldn't be
-   * reclaimed after a reconnect, e.g. the host restarted).
-   */
-  closed: { reason: string };
-  /** The host ended the match (phase → `ended`); `results` is what it passed to `end()`. Fires once. */
-  ended: { room: RoomInfo; results?: Json };
-  /** A player left mid-game (or their reconnect grace ran out). */
-  abandoned: { userId: number; reason?: string };
-}
-
-/** Who I am in a room. */
-export interface RoomSelf {
-  /** My user id. */
-  userId: number;
-  /** I host the room. */
-  host: boolean;
-  /** I'm watching, not seated. */
-  spectator: boolean;
-}
-
-/** Options for {@link HubRoom.send}. */
-export interface RoomSendOptions {
-  /** Send to this seat only. */
-  to?: number;
-}
-
-/** Options for {@link HubRoom.setState}. */
-export interface RoomStateOptions {
-  /** Replace the whole state instead of shallow-merging the patch. */
-  replace?: boolean;
-}
-
-/** A live hub relay room, as games see it. */
-export interface HubRoom {
-  /** The room as last reported. */
-  readonly info: RoomInfo;
-  /** The shared room state (at most 32 KB). */
-  readonly state: RoomState;
-  /** Who I am in this room. */
-  readonly me: RoomSelf;
-  /** Subscribe to a room event. Returns the unsubscribe function. */
-  on<Name extends keyof RoomEvents>(event: Name, listener: (payload: RoomEvents[Name]) => void): () => void;
-  /** Mark my seat ready (or not). */
-  ready(isReady: boolean): Promise<void>;
-  /** Set my seat's small game data (team, colour…), at most 2 KB. */
-  seat(seatData: Json): Promise<void>;
-  /** Host: start the match. */
-  start(): Promise<void>;
-  /** Relay a game message. */
-  send(message: Json, options?: RoomSendOptions): Promise<void>;
-  /** Change the shared state. */
-  setState(patch: RoomState, options?: RoomStateOptions): Promise<void>;
-  /** Free-text chat; resolves with the delivered (maybe softened) text, rejects with a content rejection. */
-  chat(text: string): Promise<string>;
-  /** Send a quick-chat phrase. */
-  quick(phraseId: string): Promise<void>;
-  /** Host: remove a player. */
-  kick(userId: number): Promise<void>;
-  /** Leave the room. */
-  leave(): Promise<void>;
-  /** Host: end the match, with optional results for everyone. */
-  end(results?: Json): Promise<void>;
-}
-
-/** Options for `hub.rooms.list`. */
-export interface RoomListOptions {
-  /** Only rooms in this mode. */
-  mode?: string;
-}
-
-/** `hub.rooms`: hub relay rooms (static games, no server). */
-export interface HubRoomsApi {
-  /** Create a room and take its first seat. */
-  create(options?: RoomCreateOptions): Promise<HubRoom>;
-  /** Join a room by its 5-character code or its id. */
-  join(codeOrId: string, options?: JoinOptions): Promise<HubRoom>;
-  /** Public rooms in the lobby phase for this game. */
-  list(options?: RoomListOptions): Promise<RoomInfo[]>;
-}
+/**
+ * Hub relay rooms as games see them through `hub.rooms`: realtime
+ * multiplayer for static games, relayed (never refereed) by the hub.
+ */
+import type { Json, RoomInfo } from '@diffenderfer-games/hub-contract';
+import type { RoomChatLine, RoomMessage, RoomSeat, RoomSeatChange } from './wire-types';
+
+/** The shared room state (a JSON object, at most 32 KB). */
+export type RoomState = Record<string, Json>;
+
+/** Options for `hub.rooms.create`. `game` defaults to the current slug. */
+export interface RoomCreateOptions {
+  /** The game slug (default: this page's game). */
+  game?: string;
+  /** The game mode. */
+  mode?: string;
+  /** Listed in `hub.rooms.list` (default false). */
+  public?: boolean;
+  /** Seats. */
+  maxPlayers?: number;
+  /** `host` (default): guests' unaddressed sends reach the host only. `relay`: everyone hears every send. */
+  model?: 'host' | 'relay';
+  /**
+   * When the host role moves on mid-game: `grace` (default) once the host's
+   * seat is freed (left, or 3 minutes away), so a host holding hidden state
+   * can come back; `drop` as soon as the host drops, for games whose truth is
+   * all in `setState`.
+   */
+  hostMigration?: 'grace' | 'drop';
+  /** Seat this party in the room. */
+  partyId?: string;
+}
+
+/** Options for joining a room or race. */
+export interface JoinOptions {
+  /** Watch instead of taking a seat (if the game allows spectators). */
+  spectate?: boolean;
+}
+
+/** Events a {@link HubRoom} emits, name → payload. */
+export interface RoomEvents {
+  /** The room changed: roster, ready flags, phase, host. */
+  room: RoomInfo;
+  /** A relayed game message. */
+  msg: RoomMessage;
+  /** The shared state after a change. */
+  state: RoomState;
+  /** A moderated chat line. */
+  chat: RoomChatLine;
+  /** The host removed me. */
+  kicked: { roomId: string };
+  /**
+   * The room is gone for this tab. `reason`: empty, ended, host_left,
+   * other_tab, moved, removed, or `gone` (client-side: the seat couldn't be
+   * reclaimed after a reconnect, e.g. the host restarted).
+   */
+  closed: { reason: string };
+  /** The host ended the match (phase → `ended`); `results` is what it passed to `end()`. Fires once. */
+  ended: { room: RoomInfo; results?: Json };
+  /** A player left mid-game (or their reconnect grace ran out). */
+  abandoned: { userId: number; reason?: string };
+  /**
+   * A seat changed: `away` (dropped; held until `graceEndsAt`, so hand it to
+   * your computer player), `back` (reclaimed: give control back) or `gone`
+   * (freed: left, kicked or the grace ran out). The game never ends on its
+   * own because of this; `info.hostId` may have moved to another player.
+   */
+  seat: RoomSeatChange;
+}
+
+/** Who I am in a room. */
+export interface RoomSelf {
+  /** My user id. */
+  userId: number;
+  /** I host the room. */
+  host: boolean;
+  /** I'm watching, not seated. */
+  spectator: boolean;
+}
+
+/** Options for {@link HubRoom.send}. */
+export interface RoomSendOptions {
+  /** Send to this seat only. */
+  to?: number;
+}
+
+/** Options for {@link HubRoom.setState}. */
+export interface RoomStateOptions {
+  /** Replace the whole state instead of shallow-merging the patch. */
+  replace?: boolean;
+}
+
+/** A live hub relay room, as games see it. */
+export interface HubRoom {
+  /** The room as last reported. */
+  readonly info: RoomInfo;
+  /** The shared room state (at most 32 KB). */
+  readonly state: RoomState;
+  /** Who I am in this room. */
+  readonly me: RoomSelf;
+  /** The seats as last reported; `connected: false` while a seat is away. */
+  seats(): RoomSeat[];
+  /** Subscribe to a room event. Returns the unsubscribe function. */
+  on<Name extends keyof RoomEvents>(event: Name, listener: (payload: RoomEvents[Name]) => void): () => void;
+  /** Mark my seat ready (or not). */
+  ready(isReady: boolean): Promise<void>;
+  /** Set my seat's small game data (team, colour…), at most 2 KB. */
+  seat(seatData: Json): Promise<void>;
+  /** Host: start the match. */
+  start(): Promise<void>;
+  /** Relay a game message. */
+  send(message: Json, options?: RoomSendOptions): Promise<void>;
+  /** Change the shared state. */
+  setState(patch: RoomState, options?: RoomStateOptions): Promise<void>;
+  /** Free-text chat; resolves with the delivered (maybe softened) text, rejects with a content rejection. */
+  chat(text: string): Promise<string>;
+  /** Send a quick-chat phrase. */
+  quick(phraseId: string): Promise<void>;
+  /** Host: remove a player. */
+  kick(userId: number): Promise<void>;
+  /** Leave the room. */
+  leave(): Promise<void>;
+  /** Host: end the match, with optional results for everyone. */
+  end(results?: Json): Promise<void>;
+}
+
+/** Options for `hub.rooms.list`. */
+export interface RoomListOptions {
+  /** Only rooms in this mode. */
+  mode?: string;
+}
+
+/** What feature version 3 added to `hub.rooms`. */
+export interface RoomReclaimMethods {
+  /**
+   * Take back the seat I still hold in this game (after a reload, from
+   * another tab): the room, or `null` when I hold none. The hub also does
+   * this on its own at boot, as a `join` launch with `via: 'rejoin'`.
+   */
+  reclaim(): Promise<HubRoom | null>;
+}
+
+/** `hub.rooms`: hub relay rooms (static games, no server). */
+export interface HubRoomsApi extends RoomReclaimMethods {
+  /** Create a room and take its first seat. */
+  create(options?: RoomCreateOptions): Promise<HubRoom>;
+  /** Join a room by its 5-character code or its id. */
+  join(codeOrId: string, options?: JoinOptions): Promise<HubRoom>;
+  /** Public rooms in the lobby phase for this game. */
+  list(options?: RoomListOptions): Promise<RoomInfo[]>;
+}