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

package/src/realtime/ops/hello.ts

@@ -1,40 +1,40 @@
-/**
- * `hello`: the first op on every socket (multiplayer-impl.md §4.5). It marks
- * the tab live for events and presence and answers with the snapshot a
- * client needs to draw the Friends drawer, invites and any room it still holds.
- */
-import { z } from 'zod';
-import { UnreadSummary } from '../../api/messages';
-import { MultiplayerSnapshot } from '../../api/mp/snapshot';
-import { SocialConfig } from '../../api/social/config';
-import { FriendEntry, FriendRequests, SocialMe } from '../../api/social/people';
-import { Counts } from '../../api/social/presence';
-import { op } from '../define';
-
-/** `hello` input. Anything unrecognised is ignored rather than rejected. */
-export const HelloInput = z.object({
-  /** The game this tab is in, or `null` on the home page. Unknown slugs count as `null`. */
-  slug: z.string().nullable().optional(),
-  /** A per-tab id (`[A-Za-z0-9_-]{1,64}`); other values are ignored. */
-  tab: z.string().optional(),
-  /** The document is visible (default `true`). */
-  visible: z.boolean().optional(),
-  /** The client package version that opened the socket (`2.3.0`); v1 vendored copies send none. */
-  client: z.string().optional(),
-});
-
-/** The `hello` snapshot. Guests get no friends and empty request lists. */
-export const HelloSnapshot = z.object({
-  me: SocialMe,
-  config: SocialConfig,
-  counts: Counts,
-  friends: z.array(FriendEntry),
-  requests: FriendRequests,
-  unread: UnreadSummary,
-  ...MultiplayerSnapshot.shape,
-});
-
-/** The `hello` op (allowed before `hello`, obviously). */
-export const helloOps = {
-  hello: op({ d: HelloInput, ack: HelloSnapshot, errors: [], doc: 'Start the session on this socket; answers with the snapshot.' }),
-};
+/**
+ * `hello`: the first op on every socket (multiplayer-impl.md §4.5). It marks
+ * the tab live for events and presence and answers with the snapshot a
+ * client needs to draw the Friends drawer, invites and any room it still holds.
+ */
+import { z } from 'zod';
+import { UnreadSummary } from '../../api/messages';
+import { MultiplayerSnapshot } from '../../api/mp/snapshot';
+import { SocialConfig } from '../../api/social/config';
+import { FriendEntry, FriendRequests, SocialMe } from '../../api/social/people';
+import { Counts } from '../../api/social/presence';
+import { op } from '../define';
+
+/** `hello` input. Anything unrecognised is ignored rather than rejected. */
+export const HelloInput = z.object({
+  /** The game this tab is in, or `null` on the home page. Unknown slugs count as `null`. */
+  slug: z.string().nullable().optional(),
+  /** A per-tab id (`[A-Za-z0-9_-]{1,64}`); other values are ignored. */
+  tab: z.string().optional(),
+  /** The document is visible (default `true`). */
+  visible: z.boolean().optional(),
+  /** The client package version that opened the socket (`2.3.0`); v1 vendored copies send none. */
+  client: z.string().optional(),
+});
+
+/** The `hello` snapshot. Guests get no friends and empty request lists. */
+export const HelloSnapshot = z.object({
+  me: SocialMe,
+  config: SocialConfig,
+  counts: Counts,
+  friends: z.array(FriendEntry),
+  requests: FriendRequests,
+  unread: UnreadSummary,
+  ...MultiplayerSnapshot.shape,
+});
+
+/** The `hello` op (allowed before `hello`, obviously). */
+export const helloOps = {
+  hello: op({ d: HelloInput, ack: HelloSnapshot, errors: [], doc: 'Start the session on this socket; answers with the snapshot.' }),
+};

package/src/realtime/ops/multiplayer.ts

@@ -1,8 +1,8 @@
-/** Socket ops for invites, parties, hub rooms and races. */
-import type { OpDef } from '../define';
-import { partyOps } from './parties';
-import { raceOps } from './races';
-import { roomOps } from './rooms';
-
-/** The multiplayer ops, by op name. */
-export const multiplayerOps = { ...partyOps, ...roomOps, ...raceOps } satisfies Record<string, OpDef>;
+/** Socket ops for invites, parties, hub rooms and races. */
+import type { OpDef } from '../define';
+import { partyOps } from './parties';
+import { raceOps } from './races';
+import { roomOps } from './rooms';
+
+/** The multiplayer ops, by op name. */
+export const multiplayerOps = { ...partyOps, ...roomOps, ...raceOps } satisfies Record<string, OpDef>;

package/src/realtime/ops/parties.ts

@@ -1,13 +1,13 @@
-/** The party socket op: party chat. Invites and party membership are REST (`/mp/*`). */
-import { CHAT_ERRORS, ChatLine, ChatSend } from '../../api/mp/chat';
-import { op, type OpDef } from '../define';
-
-/** The party ops, by op name. */
-export const partyOps = {
-  'party.chat': op({
-    d: ChatSend,
-    ack: ChatLine,
-    errors: ['party_gone', ...CHAT_ERRORS],
-    doc: "Chat to your party: free text only when every member is a mutual friend, quick-chat otherwise.",
-  }),
-} satisfies Record<string, OpDef>;
+/** The party socket op: party chat. Invites and party membership are REST (`/mp/*`). */
+import { CHAT_ERRORS, ChatLine, ChatSend } from '../../api/mp/chat';
+import { op, type OpDef } from '../define';
+
+/** The party ops, by op name. */
+export const partyOps = {
+  'party.chat': op({
+    d: ChatSend,
+    ack: ChatLine,
+    errors: ['party_gone', ...CHAT_ERRORS],
+    doc: "Chat to your party: free text only when every member is a mutual friend, quick-chat otherwise.",
+  }),
+} satisfies Record<string, OpDef>;

package/src/realtime/ops/races.ts

@@ -1,99 +1,99 @@
-/**
- * Race ops (docs/plans/race.md §4). A race is a hub room with a referee: the
- * countdown starts when every seat is filled, the seed is revealed with it,
- * and the first valid finish wins. Reports come from browsers, so the hub
- * measures time itself and enforces what it can (`minMs`, one result each).
- */
-import { z } from 'zod';
-import { Slug } from '../../common';
-import { OpaqueId } from '../../api/mp/parties';
-import { RaceParams, RaceProgress, RaceResult, RaceStats } from '../../api/mp/races';
-import { RoomInfo, RoomTarget } from '../../api/mp/rooms';
-import { op, type OpDef } from '../define';
-import { EmptyAck, NoInput } from './empty';
-
-/** A racer's report (status, finish, lose): stats (`null` means none) and optional 0..1 progress. */
-const RaceReport = z.object({
-  stats: RaceStats.nullish(),
-  progress: RaceProgress.nullish(),
-});
-
-/** The refusal a malformed report gets (old wording). */
-const BAD_STATS = { code: 'bad_stats', error: 'Race stats must be numbers, true/false or #rrggbb colours.' } as const;
-
-/** A race room ack. */
-const RoomAck = z.object({ room: RoomInfo });
-
-/** The race ops, by op name. */
-export const raceOps = {
-  'race.create': op({
-    d: z.object({
-      game: Slug,
-      /** The creator's choices; undeclared keys and values fall back to the defaults. */
-      params: RaceParams.optional(),
-      /** Shown in Open races and can alert followers (default true). */
-      public: z.boolean().optional(),
-      /** Seats, within the game's `race.players` (default its min). */
-      maxPlayers: z.number().optional(),
-      /** The caller's party: when they lead it, its join info becomes `{ room: code }`. */
-      partyId: OpaqueId.optional(),
-    }),
-    ack: RoomAck,
-    errors: ['not_race', 'too_many_rooms'],
-    doc: 'Open a race room with the caller seated; the countdown starts once every seat is filled.',
-  }),
-  'race.join': op({
-    d: RoomTarget,
-    ack: RoomAck,
-    errors: ['room_not_found', 'banned', 'in_progress', 'room_full', 'not_multiplayer', 'not_supported'],
-    doc: 'Join (or watch) a race room, like `room.join` but only for races.',
-  }),
-  'race.list': op({
-    d: z.object({ game: Slug }),
-    ack: z.object({ rooms: z.array(RoomInfo) }),
-    errors: [],
-    doc: 'Public races waiting for racers (at most 50), minus rooms with blocked players.',
-  }),
-  'race.start': op({
-    d: NoInput,
-    ack: EmptyAck,
-    errors: ['not_in_race', 'not_host', 'in_progress', 'not_ready'],
-    doc: 'Creator: start the countdown early once the minimum racers are in.',
-  }),
-  'race.status': op({
-    d: RaceReport,
-    ack: EmptyAck,
-    errors: ['not_in_race', 'not_started', 'race_over', 'rate_limited', 'bad_stats'],
-    invalid: BAD_STATS,
-    doc: 'Live status for the race HUD. Numbers, booleans and #rrggbb only: never text.',
-  }),
-  'race.finish': op({
-    d: RaceReport,
-    ack: z.object({ result: RaceResult }),
-    errors: ['not_in_race', 'not_started', 'race_over', 'too_fast', 'bad_stats'],
-    invalid: BAD_STATS,
-    doc: 'Report a finish with final stats; the first valid finish wins the race.',
-  }),
-  'race.lose': op({
-    d: RaceReport,
-    ack: EmptyAck,
-    errors: ['not_in_race', 'not_started', 'race_over', 'bad_stats'],
-    invalid: BAD_STATS,
-    doc: 'Game over for this racer (out of lives, stuck…); the last racer left wins.',
-  }),
-  'race.forfeit': op({
-    d: NoInput,
-    ack: EmptyAck,
-    errors: ['not_in_race', 'race_over'],
-    doc: 'Give up (leaving the room mid-race counts the same).',
-  }),
-  'race.rematch': op({
-    d: z.object({
-      /** Creator only: params for the next round. */
-      params: RaceParams.optional(),
-    }),
-    ack: EmptyAck,
-    errors: ['not_in_race', 'in_progress'],
-    doc: 'Ask for another round; it starts when every seated racer has asked.',
-  }),
-} satisfies Record<string, OpDef>;
+/**
+ * Race ops (docs/plans/race.md §4). A race is a hub room with a referee: the
+ * countdown starts when every seat is filled, the seed is revealed with it,
+ * and the first valid finish wins. Reports come from browsers, so the hub
+ * measures time itself and enforces what it can (`minMs`, one result each).
+ */
+import { z } from 'zod';
+import { Slug } from '../../common';
+import { OpaqueId } from '../../api/mp/parties';
+import { RaceParams, RaceProgress, RaceResult, RaceStats } from '../../api/mp/races';
+import { RoomInfo, RoomTarget } from '../../api/mp/rooms';
+import { op, type OpDef } from '../define';
+import { EmptyAck, NoInput } from './empty';
+
+/** A racer's report (status, finish, lose): stats (`null` means none) and optional 0..1 progress. */
+const RaceReport = z.object({
+  stats: RaceStats.nullish(),
+  progress: RaceProgress.nullish(),
+});
+
+/** The refusal a malformed report gets (old wording). */
+const BAD_STATS = { code: 'bad_stats', error: 'Race stats must be numbers, true/false or #rrggbb colours.' } as const;
+
+/** A race room ack. */
+const RoomAck = z.object({ room: RoomInfo });
+
+/** The race ops, by op name. */
+export const raceOps = {
+  'race.create': op({
+    d: z.object({
+      game: Slug,
+      /** The creator's choices; undeclared keys and values fall back to the defaults. */
+      params: RaceParams.optional(),
+      /** Shown in Open races and can alert followers (default true). */
+      public: z.boolean().optional(),
+      /** Seats, within the game's `race.players` (default its min). */
+      maxPlayers: z.number().optional(),
+      /** The caller's party: when they lead it, its join info becomes `{ room: code }`. */
+      partyId: OpaqueId.optional(),
+    }),
+    ack: RoomAck,
+    errors: ['not_race', 'too_many_rooms'],
+    doc: 'Open a race room with the caller seated; the countdown starts once every seat is filled.',
+  }),
+  'race.join': op({
+    d: RoomTarget,
+    ack: RoomAck,
+    errors: ['room_not_found', 'banned', 'in_progress', 'room_full', 'not_multiplayer', 'not_supported'],
+    doc: 'Join (or watch) a race room, like `room.join` but only for races.',
+  }),
+  'race.list': op({
+    d: z.object({ game: Slug }),
+    ack: z.object({ rooms: z.array(RoomInfo) }),
+    errors: [],
+    doc: 'Public races waiting for racers (at most 50), minus rooms with blocked players.',
+  }),
+  'race.start': op({
+    d: NoInput,
+    ack: EmptyAck,
+    errors: ['not_in_race', 'not_host', 'in_progress', 'not_ready'],
+    doc: 'Creator: start the countdown early once the minimum racers are in.',
+  }),
+  'race.status': op({
+    d: RaceReport,
+    ack: EmptyAck,
+    errors: ['not_in_race', 'not_started', 'race_over', 'rate_limited', 'bad_stats'],
+    invalid: BAD_STATS,
+    doc: 'Live status for the race HUD. Numbers, booleans and #rrggbb only: never text.',
+  }),
+  'race.finish': op({
+    d: RaceReport,
+    ack: z.object({ result: RaceResult }),
+    errors: ['not_in_race', 'not_started', 'race_over', 'too_fast', 'bad_stats'],
+    invalid: BAD_STATS,
+    doc: 'Report a finish with final stats; the first valid finish wins the race.',
+  }),
+  'race.lose': op({
+    d: RaceReport,
+    ack: EmptyAck,
+    errors: ['not_in_race', 'not_started', 'race_over', 'bad_stats'],
+    invalid: BAD_STATS,
+    doc: 'Game over for this racer (out of lives, stuck…); the last racer left wins.',
+  }),
+  'race.forfeit': op({
+    d: NoInput,
+    ack: EmptyAck,
+    errors: ['not_in_race', 'race_over'],
+    doc: 'Give up (leaving the room mid-race counts the same).',
+  }),
+  'race.rematch': op({
+    d: z.object({
+      /** Creator only: params for the next round. */
+      params: RaceParams.optional(),
+    }),
+    ack: EmptyAck,
+    errors: ['not_in_race', 'in_progress'],
+    doc: 'Ask for another round; it starts when every seated racer has asked.',
+  }),
+} satisfies Record<string, OpDef>;

package/src/realtime/ops/rooms.ts

@@ -8,13 +8,21 @@ import { z } from 'zod';
 import { Json, Slug, UserId } from '../../common';
 import { CHAT_ERRORS, ChatLine, ChatSend } from '../../api/mp/chat';
 import { GameMode, OpaqueId } from '../../api/mp/parties';
-import { RoomInfo, RoomMessage, RoomModel, RoomState, RoomTarget } from '../../api/mp/rooms';
+import { HostMigration, RoomInfo, RoomMessage, RoomModel, RoomState, RoomTarget } from '../../api/mp/rooms';
 import { op, type OpDef } from '../define';
 import { EmptyAck, NoInput } from './empty';
 
 /** A per-room sequence number ack (`room.send`, `room.state`). */
 const SeqAck = z.object({ seq: z.number().int().positive() });
 
+/** A join's ack: the room, its state and the history this member may replay. */
+const RoomJoinAck = z.object({
+  room: RoomInfo,
+  state: RoomState,
+  /** Recent messages this member may see, oldest first. */
+  history: z.array(RoomMessage),
+});
+
 /** The room ops, by op name. */
 export const roomOps = {
   'room.create': op({
@@ -27,6 +35,8 @@ export const roomOps = {
       /** Seats; clamped to the game's max (and 8). Defaults to the max. */
       maxPlayers: z.number().optional(),
       model: RoomModel.optional(),
+      /** When the host role moves on mid-game (default `grace`). */
+      hostMigration: HostMigration.optional(),
       /** The caller's party: when they lead it, its join info becomes `{ room: code }`. */
       partyId: OpaqueId.optional(),
     }),
@@ -36,15 +46,19 @@ export const roomOps = {
   }),
   'room.join': op({
     d: RoomTarget,
-    ack: z.object({
-      room: RoomInfo,
-      state: RoomState,
-      /** Recent messages this member may see, oldest first. */
-      history: z.array(RoomMessage),
-    }),
+    ack: RoomJoinAck,
     errors: ['room_not_found', 'banned', 'in_progress', 'room_full', 'not_multiplayer', 'not_supported'],
     doc: 'Take a seat (lobby only), reclaim your own seat (any phase, any tab), or watch.',
   }),
+  'room.reclaim': op({
+    d: z.object({ game: Slug }),
+    ack: z.object({
+      /** The seat I still hold in this game, now reclaimed by this tab; `null` when there is none. */
+      held: RoomJoinAck.nullable(),
+    }),
+    errors: [],
+    doc: 'Take back the seat I still hold in this game (after a reload or from another tab); the room hears `room.seat` `back`.',
+  }),
   'room.leave': op({
     d: NoInput,
     ack: EmptyAck,
@@ -88,7 +102,7 @@ export const roomOps = {
       replace: z.boolean().optional(),
     }),
     ack: SeqAck,
-    errors: ['not_in_room', 'race_room', 'not_host', 'bad_patch', 'too_large'],
+    errors: ['not_in_room', 'race_room', 'not_host', 'bad_patch', 'too_large'],
     invalid: { code: 'bad_patch', error: 'patch must be an object.' },
     doc: 'Update the shared state (host only in the host model), at most 32 KB.',
   }),

package/src/realtime/ops/social.ts

@@ -1,58 +1,58 @@
-/**
- * Socket ops for presence, visibility, typing and the heartbeat
- * (multiplayer-impl.md §4.3). `hello` is declared with the snapshot.
- */
-import { z } from 'zod';
-import { Millis, UserId } from '../../common';
-import { PresenceInput } from '../../api/social/presence';
-import { op, type OpDef } from '../define';
-import { EmptyAck, NoInput } from './empty';
-
-/**
- * `visibility` input: the tab's document visibility and idle state. Input
- * that isn't an object counts as `{}` (visible, not idle); a field that isn't a
- * boolean takes its default.
- */
-export const VisibilityInput = z.object({
-  /** The document is visible (default `true`). */
-  visible: z.boolean().optional().catch(undefined),
-  /** The player has been idle (default `false`). Hidden or idle tabs count as `away`. */
-  idle: z.boolean().optional().catch(undefined),
-}).catch({});
-
-/** The social ops, by op name. */
-export const socialOps = {
-  presence: op({
-    d: PresenceInput,
-    ack: EmptyAck,
-    errors: ['rate_limited'],
-    doc: "Report this tab's activity. Rate-limited per user; a rejected `detail` is dropped silently.",
-  }),
-  visibility: op({
-    d: VisibilityInput,
-    ack: EmptyAck,
-    errors: [],
-    doc: "Report this tab's visibility and idle state (hidden or idle tabs count as `away`).",
-  }),
-  typing: op({
-    d: z.object({
-      /**
-       * The friend you're typing to. Anything that isn't a friend's id is a
-       * silent no-op; a value that isn't a user id at all parses as `0` (no one).
-       */
-      to: UserId.catch(0),
-    }),
-    ack: EmptyAck,
-    errors: [],
-    doc: 'Tell a friend you are typing (`ev:typing`), at most once per 2 s per pair.',
-  }),
-  ping: op({
-    d: NoInput,
-    ack: z.object({
-      /** The server clock (epoch ms). */
-      t: Millis,
-    }),
-    errors: [],
-    doc: 'Heartbeat and clock check; allowed before `hello`.',
-  }),
-} satisfies Record<string, OpDef>;
+/**
+ * Socket ops for presence, visibility, typing and the heartbeat
+ * (multiplayer-impl.md §4.3). `hello` is declared with the snapshot.
+ */
+import { z } from 'zod';
+import { Millis, UserId } from '../../common';
+import { PresenceInput } from '../../api/social/presence';
+import { op, type OpDef } from '../define';
+import { EmptyAck, NoInput } from './empty';
+
+/**
+ * `visibility` input: the tab's document visibility and idle state. Input
+ * that isn't an object counts as `{}` (visible, not idle); a field that isn't a
+ * boolean takes its default.
+ */
+export const VisibilityInput = z.object({
+  /** The document is visible (default `true`). */
+  visible: z.boolean().optional().catch(undefined),
+  /** The player has been idle (default `false`). Hidden or idle tabs count as `away`. */
+  idle: z.boolean().optional().catch(undefined),
+}).catch({});
+
+/** The social ops, by op name. */
+export const socialOps = {
+  presence: op({
+    d: PresenceInput,
+    ack: EmptyAck,
+    errors: ['rate_limited'],
+    doc: "Report this tab's activity. Rate-limited per user; a rejected `detail` is dropped silently.",
+  }),
+  visibility: op({
+    d: VisibilityInput,
+    ack: EmptyAck,
+    errors: [],
+    doc: "Report this tab's visibility and idle state (hidden or idle tabs count as `away`).",
+  }),
+  typing: op({
+    d: z.object({
+      /**
+       * The friend you're typing to. Anything that isn't a friend's id is a
+       * silent no-op; a value that isn't a user id at all parses as `0` (no one).
+       */
+      to: UserId.catch(0),
+    }),
+    ack: EmptyAck,
+    errors: [],
+    doc: 'Tell a friend you are typing (`ev:typing`), at most once per 2 s per pair.',
+  }),
+  ping: op({
+    d: NoInput,
+    ack: z.object({
+      /** The server clock (epoch ms). */
+      t: Millis,
+    }),
+    errors: [],
+    doc: 'Heartbeat and clock check; allowed before `hello`.',
+  }),
+} satisfies Record<string, OpDef>;