@diffenderfer-games/hub 0.0.0-stage → 2.0.0-next.0

package/src/realtime/social-types.ts

@@ -0,0 +1,78 @@
+/**
+ * Friends, presence and notification shapes as games see them through
+ * `hub.social`, `hub.presence` and `hub.notify`.
+ */
+import type { ChatMode, FriendEntry, Invite, Party, Presence, PresenceInput } from '@diffenderfer-games/hub-contract';
+
+/** Online counts as a game sees them. */
+export interface SocialCounts {
+  /** Everyone online on the site. */
+  online: number;
+  /** Players in the current game (0 on the catalog page). */
+  inGame: number;
+  /** My friends currently online. */
+  friendsOnline: number;
+}
+
+/** Events `hub.social.on` delivers, name → payload. */
+export interface SocialEvents {
+  /** The friends list changed. */
+  friends: FriendEntry[];
+  /** A friend's presence changed (`null` when they went offline). */
+  presence: { userId: number; p: Presence | null };
+  /** The online counts changed. */
+  counts: SocialCounts;
+  /** An invite arrived. */
+  invite: Invite;
+  /** My party changed (`null` when I left it). */
+  party: Party | null;
+}
+
+/** Who to open a player card for. */
+export type PlayerRef = { userId: number } | { username: string };
+
+/** Options for the invite picker. */
+export interface OpenInviteOptions {
+  /** Preselect this friend. */
+  userId?: number;
+  /** The game mode to invite to. */
+  mode?: string;
+}
+
+/** `hub.presence`: what you're doing, shown to friends (privacy is automatic). */
+export interface HubPresenceApi {
+  /** Report an activity, e.g. `{ kind: 'playing', detail: 'Level 3' }`. Coalesced; safe to call often. */
+  set(presence: PresenceInput): void;
+  /** Back to "in the menu". */
+  clear(): void;
+}
+
+/** `hub.social`: friends and the hub's social dialogs. */
+export interface HubSocialApi {
+  /** Open a player card (add friend, message, invite, block, report). */
+  openPlayer(ref: PlayerRef): void;
+  /** Open the hub menu on the Friends section. */
+  openFriends(): void;
+  /** Open the chat with a friend. */
+  openChat(userId: number): void;
+  /** Open the invite picker (current game by default). */
+  openInvite(options?: OpenInviteOptions): void;
+  /** Open the game-suggestion form and board. */
+  openSuggest(): void;
+  /** Open notification settings, optionally focused on a game's lobby bell. */
+  openNotify(options?: { game?: string }): void;
+  /** Friends with live presence. Rejects with `OfflineError` without the runtime. */
+  friends(): Promise<FriendEntry[]>;
+  /** Live counts; all zero until the runtime is up. */
+  counts(): SocialCounts;
+  /** The effective chat mode (with these players); `'off'` until the runtime is up. */
+  chatMode(userIds?: number[]): ChatMode;
+  /** Subscribe to social events; works before the runtime loads. Returns the unsubscribe function. */
+  on<Name extends keyof SocialEvents>(event: Name, listener: (payload: SocialEvents[Name]) => void): () => void;
+}
+
+/** `hub.notify`: toast behaviour during intense play. */
+export interface HubNotifyApi {
+  /** Quiet: toasts collapse into the menu badge; invites still show as a small pill. */
+  setQuiet(isQuiet: boolean): void;
+}

package/src/realtime/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Every public realtime type in one place: the realtime API the social
+ * runtime implements, the shapes `hub.social`, `hub.mp`, `hub.rooms` and
+ * `hub.race` use, and the contract entities they carry. Types only.
+ */
+export type {
+  Audience,
+  ChatMode,
+  Conversation,
+  Counts,
+  ErrorBody,
+  FriendEntry,
+  Invite,
+  JoinInfo,
+  Launch,
+  LaunchTicket,
+  Message,
+  MessagesPage,
+  NotifyChange,
+  NotifyPrefs,
+  Party,
+  PlayerCard,
+  PlayerLite,
+  Presence,
+  PresenceInput,
+  PresenceKind,
+  RaceOutcome,
+  RaceParams,
+  RaceRecord,
+  RaceResult,
+  RaceState,
+  RaceStats,
+  RaceStatValue,
+  Racer,
+  RacerResult,
+  RacerState,
+  RecentPlayer,
+  Relation,
+  ReportInput,
+  ReportKind,
+  ReportReason,
+  RoomInfo,
+  SocialConfig,
+  SocialMe,
+  Suggestion,
+  SuggestionStatus,
+} from '@diffenderfer-games/hub-contract';
+export type * from './wire-types';
+export type * from './social-types';
+export type * from './multiplayer-types';
+export type * from './room-types';
+export type * from './race-types';
+export type { RealtimeApi } from './runtime-api';

package/src/realtime/wire-types.ts

@@ -0,0 +1,72 @@
+/**
+ * The `/_ws` wire shapes the realtime runtime and the forwarders share,
+ * derived from the hub contract so they can never drift from what the server
+ * sends. Types only: nothing here costs a byte at runtime.
+ */
+import type {
+  EventData,
+  events,
+  OpAck,
+  ops,
+  InviteCreated as InviteCreatedSchema,
+  RaceHistory as RaceHistorySchema,
+  RaceResultPlayer as RaceResultPlayerSchema,
+  RaceRecordPlayer as RaceRecordPlayerSchema,
+  RoomSeat as RoomSeatSchema,
+} from '@diffenderfer-games/hub-contract';
+
+/** The parsed (output) type of a contract schema, without importing zod. */
+export type SchemaOutput<Schema> = Schema extends { readonly _zod: { readonly output: infer Output } } ? Output : never;
+
+/** Every server event, name → payload (the contract's `events`). */
+export type ServerEvents = { [Name in keyof typeof events]: EventData<(typeof events)[Name]> };
+
+/** The `hello` ack: everything the Friends drawer needs in one round-trip. */
+export type Snapshot = OpAck<(typeof ops)['hello']>;
+
+/** A generic server notice rendered as a toast (`ev:notice`). */
+export type Notice = ServerEvents['notice'];
+
+/** A seat in a hub room. */
+export type RoomSeat = SchemaOutput<typeof RoomSeatSchema>;
+
+/** One racer's line in a decided race. */
+export type RaceResultPlayer = SchemaOutput<typeof RaceResultPlayerSchema>;
+
+/** A racer in a history record. Suspended opponents are `hidden` (id 0, no name). */
+export type RaceRecordPlayer = SchemaOutput<typeof RaceRecordPlayerSchema>;
+
+/** A page of the player's races, newest first (`GET /race/history`). */
+export type RaceHistory = SchemaOutput<typeof RaceHistorySchema>;
+
+/** `POST /mp/invites`: the invite plus the inviter's own launch. */
+export type InviteCreated = SchemaOutput<typeof InviteCreatedSchema>;
+
+/** A live status line from another racer (`ev:race.status`); `at` is ms since the go on the server clock. */
+export type RaceStatusEvent = ServerEvents['race.status'];
+
+/** A relayed game message (`ev:room.msg`). */
+export type RoomMessage = ServerEvents['room.msg'];
+
+/** A shared-state change (`ev:room.state`); patches are shallow-merged unless `replace`. */
+export type RoomStateChange = ServerEvents['room.state'];
+
+/** A moderated room chat line (`ev:room.chat`). */
+export type RoomChatLine = ServerEvents['room.chat'];
+
+/**
+ * What a rejected realtime call throws. The runtime is another bundle, so its
+ * errors are re-created as the game's own `HubError` classes by the forwarders.
+ */
+export interface RealtimeErrorShape extends Error {
+  /** HTTP status (REST), absent for transport and socket errors. */
+  status?: number;
+  /** The machine-readable code from the error body. */
+  code?: string;
+  /** Why content was rejected. */
+  reason?: string;
+  /** A player-facing hint. */
+  hint?: string;
+  /** How long to wait before retrying, when rate limited. */
+  retryAfterMs?: number;
+}

package/src/rooms.ts

@@ -0,0 +1,10 @@
+/**
+ * `@diffenderfer-games/hub/rooms`: the hub relay rooms forwarder (`hub.rooms`),
+ * for games that want only this namespace.
+ *
+ * @packageDocumentation
+ */
+export { roomsForwarder as rooms } from './realtime/rooms-forwarder';
+export type * from './realtime/room-types';
+export type { RoomChatLine, RoomMessage, RoomSeat, RoomStateChange } from './realtime/wire-types';
+export type { RoomInfo } from '@diffenderfer-games/hub-contract';

package/src/social.ts

@@ -0,0 +1,18 @@
+/**
+ * `@diffenderfer-games/hub/social`: the social forwarders (`hub.social`,
+ * `hub.presence`, `hub.notify`), and every realtime type: the API the hub's
+ * social runtime implements and the shapes it carries.
+ *
+ * @packageDocumentation
+ */
+export { notifyForwarder as notify, presenceForwarder as presence, socialForwarder as social } from './realtime/social-forwarder';
+export { linkRealtimeToHub } from './realtime/hub-link';
+export type { RealtimeHubLink } from './realtime/hub-link';
+export { findRealtimeApi, isRealtimeApi } from './realtime/page-runtime';
+export {
+  REALTIME_FAILED_EVENT,
+  REALTIME_FEATURE_VERSION,
+  REALTIME_READY_EVENT,
+  REALTIME_SINGLETON_API,
+} from './realtime/runtime-api';
+export type * from './realtime/types';

package/src/types.ts

@@ -0,0 +1,13 @@
+/**
+ * `@diffenderfer-games/hub/types`: a type-only re-export of every contract
+ * type a game may use (request and reply shapes, entities, error bodies and
+ * codes, socket ops and events, the `game.*` manifest), so a game can name a
+ * hub type without depending on the contract package itself. Importing it
+ * adds nothing to a bundle.
+ *
+ * The client's own types (`User`, `Save<T>`, `HubStatus`, ...) come from the
+ * main entry.
+ *
+ * @packageDocumentation
+ */
+export type * from '@diffenderfer-games/hub-contract';

package/src/uistack/page-stack.ts

@@ -0,0 +1,45 @@
+/**
+ * The overlay stack is one per page, on `window.__HUB_UI__`, because several
+ * bundles share it: the host's `/_hub/hub.js`, a game's bundled client and
+ * the social runtime. It has its own handover rule (older than plan §4.4's
+ * registry, and kept for v1 copies): a newer implementation replaces an older
+ * one only while it is idle, adopting its listeners, so open entries are
+ * never orphaned.
+ */
+import { hasMethods, readField } from '../realtime/cross-bundle';
+import type { UiStack } from './types';
+import { UI_STACK_VERSION, UiStackImpl } from './ui-stack';
+
+declare global {
+  interface Window {
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_UI__?: unknown;
+  }
+}
+
+/** Whether `candidate` is some bundle's overlay stack. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the stack may come from another bundle
+export function isUiStack(candidate: unknown): candidate is UiStack {
+  return typeof readField(candidate, 'version') === 'number' && hasMethods(candidate, ['push', 'on']);
+}
+
+let pagelessStack: UiStack | null = null;
+
+/**
+ * The page-wide overlay stack, created on first use. Outside a browser a
+ * module-local instance is returned.
+ */
+export function getUiStack(): UiStack {
+  if (typeof window === 'undefined') {
+    pagelessStack ??= new UiStackImpl();
+    return pagelessStack;
+  }
+  const existing = window.__HUB_UI__;
+  if (isUiStack(existing) && (existing.version >= UI_STACK_VERSION || existing.isOpen)) {
+    return existing;
+  }
+  const handoff = isUiStack(existing) && hasMethods(existing, ['handoff']) ? existing.handoff() : undefined;
+  const stack = new UiStackImpl(handoff);
+  window.__HUB_UI__ = stack;
+  return stack;
+}

package/src/uistack/play-suspension.ts

@@ -0,0 +1,82 @@
+/**
+ * While hub UI covers the game, its `play` input group is held disabled (so a
+ * paddle doesn't move while the player types), even for games that ignore
+ * the overlay events. The game's own enable/disable calls for `play` are
+ * recorded instead of applied, and the last one wins on release, so a game
+ * that pauses itself on `open` stays paused afterwards.
+ */
+import { hasMethods } from '../realtime/cross-bundle';
+
+/** The input group the stack suspends. */
+export const PLAY_GROUP = 'play';
+
+/** The slice of the page's input system the stack needs (any bundle's). */
+export interface GroupSwitch {
+  /** Whether a group is on. */
+  isEnabled(group: string): boolean;
+  /** Turn a group on. */
+  enable(group: string): void;
+  /** Turn a group off. */
+  disable(group: string): void;
+}
+
+/** Whether `candidate` can switch input groups. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the page's input system may come from another bundle
+export function isGroupSwitch(candidate: unknown): candidate is GroupSwitch {
+  return hasMethods(candidate, ['isEnabled', 'enable', 'disable']);
+}
+
+/** The intercepted method names. */
+const SWITCH_METHODS = ['enable', 'disable'] as const;
+
+/** Holds `play` disabled for one overlay visit. */
+export class PlaySuspension {
+  private readonly input: GroupSwitch;
+  private shouldPlayAfter: boolean;
+  /** The own-property descriptors replaced (`undefined` = the method lived on the prototype). */
+  private readonly savedMethods: Record<(typeof SWITCH_METHODS)[number], PropertyDescriptor | undefined>;
+
+  constructor(input: GroupSwitch) {
+    this.input = input;
+    this.shouldPlayAfter = input.isEnabled(PLAY_GROUP);
+    if (this.shouldPlayAfter) {
+      input.disable(PLAY_GROUP);
+    }
+    this.savedMethods = {
+      enable: Object.getOwnPropertyDescriptor(input, 'enable'),
+      disable: Object.getOwnPropertyDescriptor(input, 'disable'),
+    };
+    const enableGroup = input.enable.bind(input);
+    const disableGroup = input.disable.bind(input);
+    // Own-property overrides shadow the real methods until release().
+    input.enable = (group: string): void => {
+      if (group === PLAY_GROUP) {
+        this.shouldPlayAfter = true;
+      } else {
+        enableGroup(group);
+      }
+    };
+    input.disable = (group: string): void => {
+      if (group === PLAY_GROUP) {
+        this.shouldPlayAfter = false;
+      } else {
+        disableGroup(group);
+      }
+    };
+  }
+
+  /** Remove the interception and apply the state the game last asked for. */
+  release(): void {
+    for (const method of SWITCH_METHODS) {
+      const saved = this.savedMethods[method];
+      if (saved === undefined) {
+        Reflect.deleteProperty(this.input, method);
+      } else {
+        Object.defineProperty(this.input, method, saved);
+      }
+    }
+    if (this.shouldPlayAfter) {
+      this.input.enable(PLAY_GROUP);
+    }
+  }
+}

package/src/uistack/types.ts

@@ -0,0 +1,76 @@
+/**
+ * The overlay stack's public shapes: "is the player looking at hub UI right
+ * now?" (`hub.overlay`, docs/multiplayer.md §5.7).
+ */
+
+/** Why the overlay opened, so a game can word its pause screen. */
+export type OverlayReason = 'menu' | 'chat' | 'dialog' | 'keyboard' | 'invite' | 'notify';
+
+/** An overlay edge. */
+export type OverlayEdge = 'open' | 'close';
+
+/** Payload of `open` and `close` (and of the `hub:overlay-open` / `hub:overlay-close` window events). */
+export interface OverlayEvent {
+  /** The reason of the entry that opened (for `open`) or closed last (for `close`). */
+  reason: OverlayReason;
+  /**
+   * False during a live online match (`hub.mp.setBusy(true)`): the game must
+   * keep simulating, so it should not pause.
+   */
+  canPause: boolean;
+}
+
+/** Options for {@link UiStack.autoPause}. */
+export interface AutoPauseOptions {
+  /** Pause exactly the way the game's own pause does. */
+  pause(): void;
+  /** Resume play. Only called when `resumeOnClose` is true. */
+  resume?(): void;
+  /**
+   * Resume automatically when the hub UI closes. Default false: action games
+   * should show their pause screen so the player resumes deliberately;
+   * turn-based and idle games may pass true.
+   */
+  resumeOnClose?: boolean;
+}
+
+/** A listener for overlay edges. */
+export type OverlayListener = (event: OverlayEvent) => void;
+
+/** What an older, idle stack hands to a newer one replacing it. */
+export interface UiStackHandoff {
+  /** Its listeners, by edge. */
+  listeners: { open: OverlayListener[]; close: OverlayListener[] };
+  /** Its pause permission. */
+  canPause: boolean;
+}
+
+/**
+ * The page-wide overlay stack. Every piece of hub UI that covers the game
+ * (the menu drawer, a dialog, the chat sheet…) pushes an entry while it shows
+ * and pops it when it goes away; the game sees one `open` / `close` pair for
+ * the whole visit, however the UI nests.
+ */
+export interface UiStack {
+  /** Implementation version; a newer bundle replaces an older, idle instance. */
+  readonly version: number;
+  /** Register a covering piece of UI. Returns its idempotent `pop()`. */
+  push(reason: OverlayReason): () => void;
+  /** True while any hub UI covers the game. */
+  readonly isOpen: boolean;
+  /** Number of open entries (nesting depth). */
+  readonly depth: number;
+  /** Whether the game may pause right now (false during an online match). */
+  readonly canPause: boolean;
+  /** Subscribe to an edge. Returns the unsubscribe function. */
+  on(edge: OverlayEdge, listener: OverlayListener): () => void;
+  /**
+   * One-line adoption for games: pause on open (unless `canPause` is false),
+   * optionally resume on close. Returns a function that detaches it.
+   */
+  autoPause(options: AutoPauseOptions): () => void;
+  /** Driven by `hub.mp.setBusy`: false while a live match can't pause. */
+  setCanPause(canPause: boolean): void;
+  /** Hand listeners to a newer version replacing this (idle) instance. */
+  handoff(): UiStackHandoff;
+}

package/src/uistack/ui-stack.ts

@@ -0,0 +1,144 @@
+/**
+ * The overlay stack implementation: two edges (`open` when depth goes
+ * 0 → 1, `close` when it returns to 0) mirrored as window events, the
+ * `autoPause` helper, and the `play` suspension.
+ */
+import { LEGACY_GLOBAL_NAMES } from '../globals';
+import { isGroupSwitch, PlaySuspension } from './play-suspension';
+import type { AutoPauseOptions, OverlayEdge, OverlayEvent, OverlayListener, OverlayReason, UiStack, UiStackHandoff } from './types';
+
+/** Bump when the UiStack contract gains behaviour; idle older instances are replaced. */
+export const UI_STACK_VERSION = 1;
+
+/** One open entry (its identity is what `pop` removes). */
+interface StackEntry {
+  readonly reason: OverlayReason;
+}
+
+/** The page-wide overlay stack (see {@link UiStack}). */
+export class UiStackImpl implements UiStack {
+  readonly version = UI_STACK_VERSION;
+  private readonly entries: StackEntry[] = [];
+  private readonly listeners: Record<OverlayEdge, Set<OverlayListener>> = { open: new Set(), close: new Set() };
+  private isPausable = true;
+  private suspension: PlaySuspension | null = null;
+
+  constructor(handoff?: UiStackHandoff) {
+    if (handoff === undefined) {
+      return;
+    }
+    handoff.listeners.open.forEach((listener) => this.listeners.open.add(listener));
+    handoff.listeners.close.forEach((listener) => this.listeners.close.add(listener));
+    this.isPausable = handoff.canPause;
+  }
+
+  get isOpen(): boolean {
+    return this.entries.length > 0;
+  }
+
+  get depth(): number {
+    return this.entries.length;
+  }
+
+  get canPause(): boolean {
+    return this.isPausable;
+  }
+
+  push(reason: OverlayReason): () => void {
+    const entry: StackEntry = { reason };
+    this.entries.push(entry);
+    if (this.entries.length === 1) {
+      this.suspendPlay();
+      this.emit('open', { reason, canPause: this.isPausable });
+    }
+    let wasPopped = false;
+    return () => {
+      if (wasPopped) {
+        return;
+      }
+      wasPopped = true;
+      const index = this.entries.indexOf(entry);
+      if (index < 0) {
+        return;
+      }
+      this.entries.splice(index, 1);
+      if (this.entries.length === 0) {
+        // Listeners run before `play` is restored, so a game that pauses in its close handler is honoured.
+        this.emit('close', { reason, canPause: this.isPausable });
+        this.suspension?.release();
+        this.suspension = null;
+      }
+    };
+  }
+
+  on(edge: OverlayEdge, listener: OverlayListener): () => void {
+    this.listeners[edge].add(listener);
+    return () => {
+      this.listeners[edge].delete(listener);
+    };
+  }
+
+  autoPause(options: AutoPauseOptions): () => void {
+    let wasPausedByUs = false;
+    const pauseOnOpen = (event: OverlayEvent): void => {
+      if (!event.canPause) {
+        return;
+      }
+      wasPausedByUs = true;
+      options.pause();
+    };
+    const resumeOnClose = (): void => {
+      if (wasPausedByUs && options.resumeOnClose === true) {
+        options.resume?.();
+      }
+      wasPausedByUs = false;
+    };
+    const stopOpen = this.on('open', pauseOnOpen);
+    const stopClose = this.on('close', resumeOnClose);
+    // Registered while hub UI is already up: pause now, as if it just opened.
+    const firstEntry = this.entries[0];
+    if (firstEntry !== undefined) {
+      pauseOnOpen({ reason: firstEntry.reason, canPause: this.isPausable });
+    }
+    return () => {
+      stopOpen();
+      stopClose();
+    };
+  }
+
+  setCanPause(canPause: boolean): void {
+    this.isPausable = canPause;
+  }
+
+  handoff(): UiStackHandoff {
+    const handoff: UiStackHandoff = {
+      listeners: { open: [...this.listeners.open], close: [...this.listeners.close] },
+      canPause: this.isPausable,
+    };
+    this.listeners.open.clear();
+    this.listeners.close.clear();
+    return handoff;
+  }
+
+  private suspendPlay(): void {
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: the page input system may be another bundle's
+    const input: unknown = typeof window === 'undefined' ? undefined : window[LEGACY_GLOBAL_NAMES.input];
+    if (this.suspension === null && isGroupSwitch(input)) {
+      this.suspension = new PlaySuspension(input);
+    }
+  }
+
+  private emit(edge: OverlayEdge, event: OverlayEvent): void {
+    for (const listener of [...this.listeners[edge]]) {
+      try {
+        listener(event);
+      } catch (error) {
+        // eslint-disable-next-line no-console -- a game's listener failing must not break the hub UI; surface it
+        console.error('[hub] overlay listener failed', error);
+      }
+    }
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent(`hub:overlay-${edge}`, { detail: event }));
+    }
+  }
+}