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

package/src/manifest/labels.ts

@@ -0,0 +1,99 @@
+/**
+ * `game.labels`: what kind of game it is, from one fixed vocabulary, so the
+ * catalog can filter by them. Labels are grouped (genre, look, where it
+ * plays, how many play); a game lists every label that fits.
+ *
+ * Authoring is lenient: an unknown label is a warning (`hub-doctor`, the
+ * host's boot log), never an error, and the catalog ignores it.
+ */
+import { z } from 'zod';
+
+/** The vocabulary, by group. */
+export const GAME_LABEL_GROUPS = {
+  /** What kind of game. */
+  genre: ['cards', 'board', 'puzzle', 'arcade', 'platformer', 'real-time-strategy', 'physics', 'typing', 'word', 'sports', 'racing'],
+  /** How it looks. */
+  form: ['2d', '3d'],
+  /** Where it plays: `phone` (touch controls), `controller` (gamepad support), `desktop` (keyboard or mouse only). */
+  platform: ['phone', 'controller', 'desktop'],
+  /** How many play. */
+  play: ['multiplayer', 'single-player'],
+} as const;
+
+/** A label group's key. */
+export type GameLabelGroup = keyof typeof GAME_LABEL_GROUPS;
+
+/** The groups in display order. */
+export const GAME_LABEL_GROUP_ORDER: readonly GameLabelGroup[] = ['genre', 'form', 'platform', 'play'];
+
+/** Every label, in display order (group by group). */
+export const GAME_LABELS = [
+  ...GAME_LABEL_GROUPS.genre, ...GAME_LABEL_GROUPS.form, ...GAME_LABEL_GROUPS.platform, ...GAME_LABEL_GROUPS.play,
+] as const;
+
+/** One known label. */
+export const GameLabel = z.enum(GAME_LABELS);
+
+/** One known label. */
+export type GameLabel = z.infer<typeof GameLabel>;
+
+/** Each label's display name. */
+export const GAME_LABEL_TITLES: Readonly<Record<GameLabel, string>> = {
+  cards: 'Cards',
+  board: 'Board',
+  puzzle: 'Puzzle',
+  arcade: 'Arcade',
+  platformer: 'Platformer',
+  'real-time-strategy': 'Real-time strategy',
+  physics: 'Physics',
+  typing: 'Typing',
+  word: 'Word',
+  sports: 'Sports',
+  racing: 'Racing',
+  '2d': '2D',
+  '3d': '3D',
+  phone: 'Phone',
+  controller: 'Controller',
+  desktop: 'Desktop only',
+  multiplayer: 'Multiplayer',
+  'single-player': 'Single player',
+};
+
+/** Each group's display name. */
+export const GAME_LABEL_GROUP_TITLES: Readonly<Record<GameLabelGroup, string>> = {
+  genre: 'Genre',
+  form: 'Look',
+  platform: 'Plays on',
+  play: 'Players',
+};
+
+/** Whether `text` is a known label. */
+export function isGameLabel(text: string): text is GameLabel {
+  return GameLabel.safeParse(text).success;
+}
+
+/** The group a label belongs to. */
+export function groupOfLabel(label: GameLabel): GameLabelGroup {
+  return GAME_LABEL_GROUP_ORDER.find((group) => GAME_LABEL_GROUPS[group].some((member) => member === label)) ?? 'genre';
+}
+
+/**
+ * `game.labels` as written: short strings. Unknown ones parse (they are a
+ * warning, see {@link splitGameLabels}).
+ */
+export const GameLabels = z.array(z.string().trim().min(1).max(40)).max(24);
+
+/** Known labels (trimmed, lower-cased, de-duplicated, in vocabulary order) and the unknown ones as written. */
+export function splitGameLabels(written: readonly string[]): { readonly labels: GameLabel[]; readonly unknown: string[] } {
+  const known = new Set<GameLabel>();
+  const unknown: string[] = [];
+  for (const text of written) {
+    const candidate = text.trim().toLowerCase();
+    if (isGameLabel(candidate)) {
+      known.add(candidate);
+    } else {
+      unknown.push(text);
+    }
+  }
+  return { labels: GAME_LABELS.filter((label) => known.has(label)), unknown };
+}

package/src/manifest/multiplayer.ts

@@ -50,6 +50,14 @@ export const GameMultiplayer = z.strictObject({
   spectate: z.boolean().default(false),
   /** Offer quick match. Default `false`. */
   quickMatch: z.boolean().default(false),
+  /**
+   * Tournaments can be played in this game (docs/multiplayer.md §15). Default
+   * `false`. The game must play a 1v1 match from a `host`/`guest` launch that
+   * carries `launch.tournament`, and report its winner: hub rooms end with
+   * `room.end({ winnerId })`, own-server games post results with
+   * `tournament`. Race games need no flag: their races are the matches.
+   */
+  tournaments: z.boolean().default(false),
   /** Modes players can be invited into (at most 16, unique keys). */
   modes: z.array(MultiplayerMode).max(MANIFEST_LIMITS.modesMax).refine(hasUniqueKeys, 'mode keys must be unique').default([]),
   /**

package/src/realtime/events/multiplayer.ts

@@ -1,8 +1,9 @@
-/** Socket events for invites, parties, hub rooms and races. */
+/** Socket events for invites, parties, hub rooms, races and tournaments. */
 import type { EventDef } from '../define';
 import { partyEvents } from './parties';
 import { raceEvents } from './races';
 import { roomEvents } from './rooms';
+import { tournamentEvents } from './tournaments';
 
 /** The multiplayer events, by event name. */
-export const multiplayerEvents = { ...partyEvents, ...roomEvents, ...raceEvents } satisfies Record<string, EventDef>;
+export const multiplayerEvents = { ...partyEvents, ...roomEvents, ...raceEvents, ...tournamentEvents } satisfies Record<string, EventDef>;

package/src/realtime/events/rooms.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { Json, UserId } from '../../common';
 import { ChatLineEvent } from '../../api/mp/chat';
 import { OpaqueId } from '../../api/mp/parties';
-import { RoomClosedReason, RoomInfo, RoomMessage, RoomState, SeatGoneReason } from '../../api/mp/rooms';
+import { RoomClosedReason, RoomInfo, RoomMessage, RoomState, SeatChange, SeatGoneReason } from '../../api/mp/rooms';
 import { event, type EventDef } from '../define';
 
 /** The room events, by event name. */
@@ -39,10 +39,14 @@ export const roomEvents = {
   }),
   'room.closed': event({
     d: z.object({ reason: RoomClosedReason }),
-    doc: 'The room is gone for this tab (emptied, ended, host left, moved, another tab took the seat, removed).',
+    doc: 'The room is gone for this tab (emptied, ended, moved, another tab took the seat, removed). `host_left` is no longer sent: the host role passes on.',
   }),
   'room.abandoned': event({
     d: z.object({ userId: UserId, reason: SeatGoneReason }),
     doc: 'A player left mid-game (or their reconnect grace ran out); the game decides what that means.',
   }),
+  'room.seat': event({
+    d: SeatChange,
+    doc: 'A seat went away (held for the grace period), came back (reclaimed) or is gone. The game hands an away seat to its computer player and gives it back on `back`.',
+  }),
 } satisfies Record<string, EventDef>;

package/src/realtime/events/social.ts

@@ -12,8 +12,8 @@ import { FriendChange } from '../../api/social/people';
 import { Counts, Presence } from '../../api/social/presence';
 import { event, type EventDef } from '../define';
 
-/** What kind of thing a notice is about. `renamed`: an admin changed your username. */
-export const NoticeKind = z.enum(['dm', 'friend_request', 'friend_online', 'lobby_open', 'invite', 'suggestion', 'renamed']);
+/** What kind of thing a notice is about. `renamed`: an admin changed your username; `tournament`: a match is ready, a start is near, a forfeit warning. */
+export const NoticeKind = z.enum(['dm', 'friend_request', 'friend_online', 'lobby_open', 'invite', 'suggestion', 'renamed', 'tournament']);
 
 /** A notice kind. */
 export type NoticeKind = z.infer<typeof NoticeKind>;

package/src/realtime/events/tournaments.ts

@@ -0,0 +1,12 @@
+/** Tournament events (batch-2026-10 R15). */
+import { z } from 'zod';
+import { TournamentSummary } from '../../api/tournaments/shapes';
+import { event, type EventDef } from '../define';
+
+/** The tournament events, by event name. */
+export const tournamentEvents = {
+  tournament: event({
+    d: z.object({ tournament: TournamentSummary }),
+    doc: 'A tournament you are in, follow, created or were invited to changed (sign-ups, the start, a match ready or decided, the end).',
+  }),
+} satisfies Record<string, EventDef>;

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,