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

package/src/realtime/page-runtime.ts

@@ -0,0 +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) : '';
+}

package/src/realtime/race-forwarder.ts

@@ -0,0 +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)),
+};

package/src/realtime/race-types.ts

@@ -0,0 +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;

package/src/realtime/room-types.ts

@@ -0,0 +1,125 @@
+/**
+ * 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[]>;
+}

package/src/realtime/rooms-forwarder.ts

@@ -0,0 +1,79 @@
+/**
+ * `hub.rooms`: hub relay rooms, forwarded to the social runtime. Each room is
+ * wrapped so its rejections use the core client's error classes.
+ */
+import type { Json, RoomInfo } from '@diffenderfer-games/hub-contract';
+import { pageBridge, rethrowAsHubError } from './bridge';
+import type { HubRoom, HubRoomsApi, RoomEvents, RoomSelf, RoomSendOptions, RoomState, RoomStateOptions } from './room-types';
+
+/** A runtime room whose rejections are re-created as the core client's errors. */
+class ForwardedRoom implements HubRoom {
+  private readonly room: HubRoom;
+
+  constructor(room: HubRoom) {
+    this.room = room;
+  }
+
+  get info(): RoomInfo {
+    return this.room.info;
+  }
+
+  get state(): RoomState {
+    return this.room.state;
+  }
+
+  get me(): RoomSelf {
+    return this.room.me;
+  }
+
+  on<Name extends keyof RoomEvents>(event: Name, listener: (payload: RoomEvents[Name]) => void): () => void {
+    return this.room.on(event, listener);
+  }
+
+  ready(isReady: boolean): Promise<void> {
+    return rethrowAsHubError(this.room.ready(isReady));
+  }
+
+  seat(seatData: Json): Promise<void> {
+    return rethrowAsHubError(this.room.seat(seatData));
+  }
+
+  start(): Promise<void> {
+    return rethrowAsHubError(this.room.start());
+  }
+
+  send(message: Json, options?: RoomSendOptions): Promise<void> {
+    return rethrowAsHubError(this.room.send(message, options));
+  }
+
+  setState(patch: RoomState, options?: RoomStateOptions): Promise<void> {
+    return rethrowAsHubError(this.room.setState(patch, options));
+  }
+
+  chat(text: string): Promise<string> {
+    return rethrowAsHubError(this.room.chat(text));
+  }
+
+  quick(phraseId: string): Promise<void> {
+    return rethrowAsHubError(this.room.quick(phraseId));
+  }
+
+  kick(userId: number): Promise<void> {
+    return rethrowAsHubError(this.room.kick(userId));
+  }
+
+  leave(): Promise<void> {
+    return rethrowAsHubError(this.room.leave());
+  }
+
+  end(results?: Json): Promise<void> {
+    return rethrowAsHubError(this.room.end(results));
+  }
+}
+
+/** `hub.rooms`: hub relay rooms. */
+export const roomsForwarder: HubRoomsApi = {
+  create: (options) => pageBridge.call(async (realtime) => new ForwardedRoom(await realtime.rooms.create(options))),
+  join: (codeOrId, options) => pageBridge.call(async (realtime) => new ForwardedRoom(await realtime.rooms.join(codeOrId, options))),
+  list: (options) => pageBridge.call((realtime) => realtime.rooms.list(options)),
+};

package/src/realtime/runtime-api.ts

@@ -0,0 +1,49 @@
+/**
+ * The realtime API the hub's social runtime (`/_hub/social.js`) installs on
+ * the page, and that `hub.presence`, `hub.social`, `hub.mp`, `hub.rooms`,
+ * `hub.notify` and `hub.race` forward to.
+ */
+import type { HubMpApi } from './multiplayer-types';
+import type { HubRaceApi } from './race-types';
+import type { HubRoomsApi } from './room-types';
+import type { HubNotifyApi, HubPresenceApi, HubSocialApi } from './social-types';
+
+/**
+ * The realtime feature version the runtime reports in {@link RealtimeApi.version}.
+ * 2 added races; a client feature-detects newer additions with it.
+ */
+export const REALTIME_FEATURE_VERSION = 2;
+
+/**
+ * The cross-bundle shape number of the `rt` page singleton (plan §4.4). The
+ * runtime registers with it through `claimSingleton`; bump it only when the
+ * shape of {@link RealtimeApi} changes incompatibly.
+ */
+export const REALTIME_SINGLETON_API = 1;
+
+/** The window event the runtime fires once it has installed itself. */
+export const REALTIME_READY_EVENT = 'hub:rt-ready';
+
+/** The window event the menu fires when the runtime failed to load (its reason is on `window.__HUB_RT_ERROR__`). */
+export const REALTIME_FAILED_EVENT = 'hub:rt-failed';
+
+/**
+ * Installed by the social runtime as the page's `rt` singleton (and the v1
+ * alias `window.__HUB_RT__`).
+ */
+export interface RealtimeApi {
+  /** The runtime's feature version (see {@link REALTIME_FEATURE_VERSION}). */
+  readonly version: number;
+  /** Presence reporting. */
+  presence: HubPresenceApi;
+  /** Friends and the social dialogs. */
+  social: HubSocialApi;
+  /** Invites, launches, the leave guard and tickets. */
+  mp: HubMpApi;
+  /** Hub relay rooms. */
+  rooms: HubRoomsApi;
+  /** Toast behaviour. */
+  notify: HubNotifyApi;
+  /** Races (feature version 2 and later). */
+  race?: HubRaceApi;
+}

package/src/realtime/runtime-opener.ts

@@ -0,0 +1,61 @@
+/**
+ * Opening the runtime's UI (a player card, the friends drawer, the race
+ * sheet) from a game button. A tap must never look dead: if the runtime isn't
+ * there within a moment the player is told it is loading, and if it never
+ * arrives, how to recover.
+ */
+import type { RealtimeBridge } from './bridge';
+import { hideFallbackNotice, showFallbackNotice } from './fallback-notice';
+import { readRuntimeFailure } from './page-runtime';
+import type { RealtimeApi } from './runtime-api';
+import { REALTIME_FAILED_EVENT } from './runtime-api';
+
+/** How long before "still loading" shows. */
+const SLOW_NOTICE_MS = 1500;
+/** How long the failure notice stays up. */
+const FAILURE_NOTICE_MS = 8000;
+
+/** Tell the player the social runtime failed, with the reason the menu recorded. */
+function showRuntimeFailure(): void {
+  const reason = readRuntimeFailure();
+  showFallbackNotice(`Friends couldn't load${reason === '' ? '' : ` (${reason})`}. Reload the page to try again.`, FAILURE_NOTICE_MS);
+}
+
+/** Make an opener: runs a UI call on the runtime once it is up, with the loading and failure notices. */
+export function createRuntimeOpener(bridge: RealtimeBridge): (openUi: (realtime: RealtimeApi) => void) => void {
+  return (openUi) => {
+    const loaded = bridge.current();
+    if (loaded !== null) {
+      openUi(loaded);
+      return;
+    }
+    // The menu already knows the runtime failed.
+    if (readRuntimeFailure() !== '') {
+      showRuntimeFailure();
+      return;
+    }
+    const slowTimer = setTimeout(() => {
+      showFallbackNotice('Friends are still loading…');
+    }, SLOW_NOTICE_MS);
+    let isSettled = false;
+    const onFailed = (): void => {
+      if (!isSettled) {
+        isSettled = true;
+        clearTimeout(slowTimer);
+        showRuntimeFailure();
+      }
+    };
+    if (typeof window !== 'undefined') {
+      window.addEventListener(REALTIME_FAILED_EVENT, onFailed, { once: true });
+    }
+    bridge.whenReady().then((realtime) => {
+      if (isSettled) {
+        return;
+      }
+      isSettled = true;
+      clearTimeout(slowTimer);
+      hideFallbackNotice();
+      openUi(realtime);
+    }, onFailed);
+  };
+}

package/src/realtime/social-forwarder.ts

@@ -0,0 +1,72 @@
+/**
+ * `hub.presence`, `hub.social` and `hub.notify`: thin forwarders to the
+ * social runtime. Presence and quiet mode are "latest state" calls,
+ * remembered and replayed when the runtime loads.
+ */
+import { pageBridge } from './bridge';
+import { latestState } from './latest-state';
+import { createRuntimeOpener } from './runtime-opener';
+import type { HubNotifyApi, HubPresenceApi, HubSocialApi, SocialCounts } from './social-types';
+
+const openWithRuntime = createRuntimeOpener(pageBridge);
+
+/** Counts before the runtime is up. */
+const NO_COUNTS: SocialCounts = { online: 0, inGame: 0, friendsOnline: 0 };
+
+/** `hub.presence`: what you're doing, shown to friends. */
+export const presenceForwarder: HubPresenceApi = {
+  set(presence) {
+    latestState.presence = { ...presence };
+    pageBridge.current()?.presence.set(latestState.presence);
+  },
+  clear() {
+    latestState.presence = { kind: 'menu' };
+    pageBridge.current()?.presence.clear();
+  },
+};
+
+/** `hub.notify`: toast behaviour. */
+export const notifyForwarder: HubNotifyApi = {
+  setQuiet(isQuiet) {
+    latestState.isQuiet = isQuiet;
+    pageBridge.current()?.notify.setQuiet(isQuiet);
+  },
+};
+
+/** `hub.social`: friends and the hub's social dialogs. */
+export const socialForwarder: HubSocialApi = {
+  openPlayer: (ref) => {
+    openWithRuntime((realtime) => {
+      realtime.social.openPlayer(ref);
+    });
+  },
+  openFriends: () => {
+    openWithRuntime((realtime) => {
+      realtime.social.openFriends();
+    });
+  },
+  openChat: (userId) => {
+    openWithRuntime((realtime) => {
+      realtime.social.openChat(userId);
+    });
+  },
+  openInvite: (options) => {
+    openWithRuntime((realtime) => {
+      realtime.social.openInvite(options);
+    });
+  },
+  openSuggest: () => {
+    openWithRuntime((realtime) => {
+      realtime.social.openSuggest();
+    });
+  },
+  openNotify: (options) => {
+    openWithRuntime((realtime) => {
+      realtime.social.openNotify(options);
+    });
+  },
+  friends: () => pageBridge.call((realtime) => realtime.social.friends()),
+  counts: () => pageBridge.current()?.social.counts() ?? { ...NO_COUNTS },
+  chatMode: (userIds) => pageBridge.current()?.social.chatMode(userIds) ?? 'off',
+  on: (event, listener) => pageBridge.subscribe((realtime) => realtime.social.on(event, listener)),
+};