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

package/src/overlay/virtual-controls.ts

@@ -0,0 +1,262 @@
+/**
+ * Building one on-screen control (button, tap region, joystick or dpad) and
+ * wiring its touch and mouse handling, plus drag-to-move while the player
+ * edits the layout.
+ */
+import type { VirtualDef } from '../input/types';
+import { placeAt, requireElement } from './dom';
+import { declaredSize, isStickType } from './layout-geometry';
+import type { ListenerScope } from './listener-scope';
+import { ACCENT_COLOR } from './styles';
+
+/** What a control reports. */
+export interface VirtualControlCallbacks {
+  /** A button went down. */
+  onButtonDown(id: string): void;
+  /** A button came up. */
+  onButtonUp(id: string): void;
+  /** A stick moved (-1..1 per axis; 0, 0 on release). */
+  onStick(id: string, outX: number, outY: number): void;
+  /** A tap region was tapped. */
+  onTap(): void;
+  /** The player dropped a dragged control: its top-left corner as % of the viewport. */
+  onDragged(id: string, spot: { x: number; y: number }): void;
+}
+
+/** What controls need from the overlay. */
+export interface VirtualControlEnvironment {
+  readonly callbacks: VirtualControlCallbacks;
+  /** Window listeners, removed when the controls are rebuilt. */
+  readonly scope: ListenerScope;
+  /** Whether the player is editing the layout (controls drag instead of acting). */
+  isEditing(): boolean;
+}
+
+/** A dpad snaps past this deflection. */
+const DPAD_THRESHOLD = 0.4;
+
+const RADIUS_BY_SHAPE = { circle: '50%', pill: '999px', square: '0', round: '16px' } as const;
+
+/** The first touch of a touch event. */
+function firstTouch(event: TouchEvent): Touch | undefined {
+  return event.changedTouches[0];
+}
+
+function bindButton(id: string, element: HTMLElement, environment: VirtualControlEnvironment): void {
+  const { callbacks } = environment;
+  const isTapRegion = element.classList.contains('vc-transparent');
+  const press = (event: Event): void => {
+    if (environment.isEditing()) {
+      return;
+    }
+    event.preventDefault();
+    element.classList.add('pressed');
+    callbacks.onButtonDown(id);
+    if (isTapRegion) {
+      callbacks.onTap();
+    }
+  };
+  const release = (event: Event): void => {
+    event.preventDefault();
+    element.classList.remove('pressed');
+    callbacks.onButtonUp(id);
+  };
+  element.addEventListener('touchstart', press, { passive: false });
+  element.addEventListener('touchend', release, { passive: false });
+  element.addEventListener('touchcancel', release, { passive: false });
+  element.addEventListener('mousedown', press);
+  environment.scope.listenWindow('mouseup', release);
+}
+
+function bindStick(id: string, wrapper: HTMLElement, knob: HTMLElement, definition: VirtualDef, environment: VirtualControlEnvironment): void {
+  const isDpad = definition.type === 'dpad';
+  const axisMode = definition.axis ?? 'both';
+  const { callbacks } = environment;
+  let activeTouchId = -1;
+  let centreX = 0;
+  let centreY = 0;
+  let travelX = 1;
+  let travelY = 1;
+  const measure = (): void => {
+    const bounds = wrapper.getBoundingClientRect();
+    centreX = bounds.left + bounds.width / 2;
+    centreY = bounds.top + bounds.height / 2;
+    const knobRadius = knob.getBoundingClientRect().width / 2 || Math.min(bounds.width, bounds.height) * 0.25;
+    travelX = Math.max(1, bounds.width / 2 - knobRadius);
+    travelY = Math.max(1, bounds.height / 2 - knobRadius);
+  };
+  const moveTo = (pointerX: number, pointerY: number): void => {
+    let dx = axisMode === 'y' ? 0 : pointerX - centreX;
+    let dy = axisMode === 'x' ? 0 : pointerY - centreY;
+    if (axisMode === 'both') {
+      const limit = Math.min(travelX, travelY);
+      const distance = Math.hypot(dx, dy);
+      if (distance > limit) {
+        dx = (dx * limit) / distance;
+        dy = (dy * limit) / distance;
+      }
+    } else {
+      dx = Math.max(-travelX, Math.min(travelX, dx));
+      dy = Math.max(-travelY, Math.min(travelY, dy));
+    }
+    let outX = dx / travelX;
+    let outY = dy / travelY;
+    if (isDpad) {
+      outX = Math.abs(outX) > DPAD_THRESHOLD ? Math.sign(outX) : 0;
+      outY = Math.abs(outY) > DPAD_THRESHOLD ? Math.sign(outY) : 0;
+    }
+    knob.style.transform = `translate(${String(dx)}px, ${String(dy)}px)`;
+    callbacks.onStick(id, outX, outY);
+  };
+  const release = (): void => {
+    activeTouchId = -1;
+    knob.style.transform = 'translate(0,0)';
+    callbacks.onStick(id, 0, 0);
+  };
+  wrapper.addEventListener('touchstart', (event) => {
+    const touch = firstTouch(event);
+    if (environment.isEditing() || touch === undefined) {
+      return;
+    }
+    event.preventDefault();
+    measure();
+    activeTouchId = touch.identifier;
+    moveTo(touch.clientX, touch.clientY);
+  }, { passive: false });
+  wrapper.addEventListener('touchmove', (event) => {
+    event.preventDefault();
+    for (const touch of event.changedTouches) {
+      if (touch.identifier === activeTouchId) {
+        moveTo(touch.clientX, touch.clientY);
+      }
+    }
+  }, { passive: false });
+  wrapper.addEventListener('touchend', release, { passive: false });
+  wrapper.addEventListener('touchcancel', release, { passive: false });
+  // Mouse drag (desktop testing).
+  let isMouseHeld = false;
+  wrapper.addEventListener('mousedown', (event) => {
+    if (environment.isEditing()) {
+      return;
+    }
+    measure();
+    isMouseHeld = true;
+    moveTo(event.clientX, event.clientY);
+  });
+  environment.scope.listenWindow('mousemove', (event) => {
+    if (isMouseHeld) {
+      moveTo(event.clientX, event.clientY);
+    }
+  });
+  environment.scope.listenWindow('mouseup', () => {
+    if (isMouseHeld) {
+      isMouseHeld = false;
+      release();
+    }
+  });
+}
+
+/** Drag-to-move while editing: the control keeps its grab point under the finger and stays fully on-screen. */
+function bindEditDrag(id: string, element: HTMLElement, environment: VirtualControlEnvironment): void {
+  let isDragging = false;
+  let grabX = 0;
+  let grabY = 0;
+  let droppedSpot: { x: number; y: number } | null = null;
+  const start = (pointerX: number, pointerY: number): void => {
+    if (!environment.isEditing()) {
+      return;
+    }
+    isDragging = true;
+    const bounds = element.getBoundingClientRect();
+    grabX = pointerX - bounds.left;
+    grabY = pointerY - bounds.top;
+    droppedSpot = null;
+  };
+  const move = (pointerX: number, pointerY: number): void => {
+    if (!isDragging) {
+      return;
+    }
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+    const left = Math.max(0, Math.min(viewportWidth - element.offsetWidth, pointerX - grabX));
+    const top = Math.max(0, Math.min(viewportHeight - element.offsetHeight, pointerY - grabY));
+    placeAt(element, left, top);
+    droppedSpot = { x: (left / viewportWidth) * 100, y: (top / viewportHeight) * 100 };
+  };
+  const end = (): void => {
+    if (!isDragging) {
+      return;
+    }
+    isDragging = false;
+    if (droppedSpot !== null) {
+      environment.callbacks.onDragged(id, droppedSpot);
+    }
+  };
+  element.addEventListener('mousedown', (event) => {
+    start(event.clientX, event.clientY);
+  });
+  element.addEventListener('touchstart', (event) => {
+    const touch = firstTouch(event);
+    if (touch !== undefined) {
+      start(touch.clientX, touch.clientY);
+    }
+  }, { passive: true });
+  environment.scope.listenWindow('mousemove', (event) => {
+    move(event.clientX, event.clientY);
+  });
+  environment.scope.listenWindow('touchmove', (event) => {
+    const touch = firstTouch(event);
+    if (isDragging && touch !== undefined) {
+      move(touch.clientX, touch.clientY);
+    }
+  });
+  environment.scope.listenWindow('mouseup', end);
+  environment.scope.listenWindow('touchend', end);
+}
+
+/** Build one on-screen control element, wired up. */
+export function createVirtualControl(definition: VirtualDef, environment: VirtualControlEnvironment): HTMLElement {
+  const isStick = isStickType(definition.type);
+  const { w: width, h: height } = declaredSize(definition);
+  const wrapper = document.createElement('div');
+  wrapper.className = `vc vc-${definition.type}`;
+  wrapper.dataset['controlId'] = definition.id;
+  // The v1 expando tests and tools read the control id from.
+  Reflect.set(wrapper, '__id', definition.id);
+  wrapper.style.width = `${String(width)}px`;
+  wrapper.style.height = `${String(height)}px`;
+  if (definition.opacity !== undefined) {
+    wrapper.style.opacity = String(definition.opacity);
+  }
+  wrapper.style.setProperty('--vc-color', definition.color ?? ACCENT_COLOR);
+  if (definition.bg !== undefined) {
+    wrapper.style.setProperty('--vc-bg', definition.bg);
+  }
+  if (definition.text !== undefined) {
+    wrapper.style.color = definition.text;
+  }
+  const radius = RADIUS_BY_SHAPE[definition.shape ?? (isStick ? 'circle' : 'round')];
+  wrapper.style.borderRadius = radius;
+  if (isStick) {
+    wrapper.innerHTML = '<div class="base"></div><div class="knob"></div>';
+    requireElement(wrapper, '.base', HTMLElement).style.borderRadius = radius;
+    // The knob stays a circle sized to the short edge (a wide pill stick gets a
+    // round knob that slides). Single-axis sticks get a knob that mostly fills
+    // the short edge; 2D sticks a smaller one with room to travel.
+    const knob = requireElement(wrapper, '.knob', HTMLElement);
+    const isSingleAxis = definition.axis === 'x' || definition.axis === 'y';
+    const knobDiameter = Math.round(Math.min(width, height) * (isSingleAxis ? 0.92 : 0.5));
+    knob.style.width = `${String(knobDiameter)}px`;
+    knob.style.height = `${String(knobDiameter)}px`;
+    bindStick(definition.id, wrapper, knob, definition, environment);
+  } else {
+    // The game's own markup (an SVG icon, an entity in a label), inserted as given.
+    wrapper.innerHTML = definition.html ?? `<span>${definition.label ?? ''}</span>`;
+    if (definition.type === 'tap') {
+      wrapper.classList.add('vc-transparent');
+    }
+    bindButton(definition.id, wrapper, environment);
+  }
+  bindEditDrag(definition.id, wrapper, environment);
+  return wrapper;
+}

package/src/race.ts

@@ -0,0 +1,10 @@
+/**
+ * `@diffenderfer-games/hub/race`: the race forwarder (`hub.race`), for games
+ * that want only this namespace.
+ *
+ * @packageDocumentation
+ */
+export { raceForwarder as race } from './realtime/race-forwarder';
+export type * from './realtime/race-types';
+export type { RaceHistory, RaceRecordPlayer, RaceResultPlayer, RaceStatusEvent } from './realtime/wire-types';
+export type { RaceOutcome, RaceParams, RaceRecord, RaceResult, RaceState, RaceStats, RaceStatValue, Racer, RacerResult, RacerState, RoomInfo } from '@diffenderfer-games/hub-contract';

package/src/realtime/bridge.ts

@@ -0,0 +1,121 @@
+/**
+ * The bridge from the forwarders to the social runtime, which the menu loads
+ * after the page (and which may never load). The forwarders stay thin so a
+ * game's bundled copy never goes stale:
+ *
+ * - listeners are kept here and attached whenever the runtime appears;
+ * - "latest state" calls are remembered and replayed when it appears;
+ * - calls that return data wait up to {@link RUNTIME_WAIT_MS}, then reject
+ *   with `OfflineError`;
+ * - with no `window.__HUB__` (a page the hub didn't inject) waits end at once.
+ */
+import { hubLink } from './hub-link';
+import { findRealtimeApi, isHubInjectedPage } from './page-runtime';
+import type { RealtimeApi } from './runtime-api';
+import { REALTIME_READY_EVENT } from './runtime-api';
+
+/** How long data and UI calls wait for the social runtime before giving up. */
+export const RUNTIME_WAIT_MS = 15_000;
+
+/** Something to run with the runtime once it exists. */
+type RuntimeCallback = (realtime: RealtimeApi) => void;
+
+/** Resolves the runtime's realtime API, waiting for it to load when necessary. */
+export class RealtimeBridge {
+  private pendingCallbacks: RuntimeCallback[] = [];
+
+  constructor() {
+    if (typeof window !== 'undefined') {
+      window.addEventListener(REALTIME_READY_EVENT, () => {
+        this.runPendingCallbacks();
+      });
+    }
+  }
+
+  /** The runtime's API if it has loaded. */
+  current(): RealtimeApi | null {
+    return findRealtimeApi();
+  }
+
+  /** Run `callback` as soon as the runtime exists (now, or whenever it loads). */
+  onReady(callback: RuntimeCallback): void {
+    const realtime = this.current();
+    if (realtime === null) {
+      this.pendingCallbacks.push(callback);
+    } else {
+      callback(realtime);
+    }
+  }
+
+  /** The runtime, waiting up to {@link RUNTIME_WAIT_MS}; rejects with `OfflineError`. */
+  whenReady(): Promise<RealtimeApi> {
+    const realtime = this.current();
+    if (realtime !== null) {
+      return Promise.resolve(realtime);
+    }
+    if (!isHubInjectedPage()) {
+      return Promise.reject(hubLink().createOfflineError('Online features are not available on this page.'));
+    }
+    return new Promise((resolve, reject) => {
+      const resolveWhenReady: RuntimeCallback = (loaded) => {
+        clearTimeout(timer);
+        resolve(loaded);
+      };
+      const timer = setTimeout(() => {
+        this.pendingCallbacks = this.pendingCallbacks.filter((callback) => callback !== resolveWhenReady);
+        reject(hubLink().createOfflineError('Online features did not load.'));
+      }, RUNTIME_WAIT_MS);
+      this.pendingCallbacks.push(resolveWhenReady);
+    });
+  }
+
+  /** Attach a listener now or on load; the returned function detaches it. */
+  subscribe(attach: (realtime: RealtimeApi) => () => void): () => void {
+    let detach: (() => void) | null = null;
+    let isCancelled = false;
+    this.onReady((realtime) => {
+      if (!isCancelled) {
+        detach = attach(realtime);
+      }
+    });
+    return () => {
+      isCancelled = true;
+      detach?.();
+    };
+  }
+
+  /** Call the runtime (waiting for it) and re-create its errors as the core client's classes. */
+  async call<Result>(request: (realtime: RealtimeApi) => Promise<Result>): Promise<Result> {
+    const realtime = await this.whenReady();
+    return rethrowAsHubError(request(realtime));
+  }
+
+  private runPendingCallbacks(): void {
+    const realtime = this.current();
+    if (realtime === null) {
+      return;
+    }
+    const callbacks = this.pendingCallbacks;
+    this.pendingCallbacks = [];
+    for (const callback of callbacks) {
+      try {
+        callback(realtime);
+      } catch (error) {
+        // eslint-disable-next-line no-console -- one runtime callback failing must not stop the others; surface it
+        console.error('[hub] social runtime callback failed', error);
+      }
+    }
+  }
+}
+
+/** The same promise, with rejections re-created as the core client's error classes. */
+export async function rethrowAsHubError<Result>(pending: Promise<Result>): Promise<Result> {
+  try {
+    return await pending;
+  } catch (error) {
+    throw hubLink().toHubError(error);
+  }
+}
+
+/** The page's one bridge (per client bundle). */
+export const pageBridge = new RealtimeBridge();

package/src/realtime/cross-bundle.ts

@@ -0,0 +1,29 @@
+/**
+ * Checks for objects another bundle put on the page (a game's copy of the
+ * client, the host's `/_hub/hub.js`, the social runtime, a v1 vendored copy).
+ * Their classes are not ours, so they are recognised by shape.
+ */
+
+/** A function of any arity, as seen from outside. */
+type AnyMethod = (...args: never[]) => void;
+
+/** Whether `candidate` is a non-null object. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: an object from another bundle on the page
+export function isObject(candidate: unknown): candidate is object {
+  return typeof candidate === 'object' && candidate !== null;
+}
+
+/** Whether `candidate` is an object with a function under every one of `names`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: an object from another bundle on the page
+export function hasMethods<Name extends string>(candidate: unknown, names: readonly Name[]): candidate is Record<Name, AnyMethod> {
+  if (!isObject(candidate)) {
+    return false;
+  }
+  return names.every((name) => name in candidate && typeof Reflect.get(candidate, name) === 'function');
+}
+
+/** The value under `key` on another bundle's object, or `undefined`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: reads a field of another bundle's object, checked by the caller
+export function readField(candidate: unknown, key: string): unknown {
+  return isObject(candidate) ? Reflect.get(candidate, key) : undefined;
+}

package/src/realtime/fallback-notice.ts

@@ -0,0 +1,48 @@
+/**
+ * A minimal top-centre notice for when the social runtime (which owns the
+ * real toasts) isn't available: plain DOM with inline styles in the hub
+ * palette, one at a time.
+ */
+import { pageBody } from '../overlay/dom';
+
+const NOTICE_ELEMENT_ID = 'hub-fallback-notice';
+const NOTICE_STYLE = 'position:fixed;top:12px;left:50%;transform:translateX(-50%);z-index:2147483647;'
+  + 'max-width:min(92vw,420px);padding:10px 14px;border-radius:10px;font:13px/1.4 "Space Mono",ui-monospace,monospace;'
+  + 'background:#11141c;color:#e8e6df;border:1px solid #2a3142;box-shadow:0 8px 24px rgba(0,0,0,.5);pointer-events:none;';
+
+let hideTimer: ReturnType<typeof setTimeout> | null = null;
+
+/** Show `text`; it hides itself after `visibleMs` (0 = until replaced or hidden). */
+export function showFallbackNotice(text: string, visibleMs = 0): void {
+  if (typeof document === 'undefined') {
+    return;
+  }
+  const body = pageBody();
+  if (body === null) {
+    return;
+  }
+  let notice = document.getElementById(NOTICE_ELEMENT_ID);
+  if (notice === null) {
+    notice = document.createElement('div');
+    notice.id = NOTICE_ELEMENT_ID;
+    notice.setAttribute('role', 'status');
+    notice.style.cssText = NOTICE_STYLE;
+    body.appendChild(notice);
+  }
+  notice.textContent = text;
+  if (hideTimer !== null) {
+    clearTimeout(hideTimer);
+  }
+  hideTimer = visibleMs > 0 ? setTimeout(hideFallbackNotice, visibleMs) : null;
+}
+
+/** Remove the notice. */
+export function hideFallbackNotice(): void {
+  if (hideTimer !== null) {
+    clearTimeout(hideTimer);
+    hideTimer = null;
+  }
+  if (typeof document !== 'undefined') {
+    document.getElementById(NOTICE_ELEMENT_ID)?.remove();
+  }
+}

package/src/realtime/hub-link.ts

@@ -0,0 +1,65 @@
+/**
+ * What the forwarders need from the core client: its error classes (so a
+ * runtime rejection is an `instanceof HubError` in the game) and the direct
+ * own-server ticket request. The core client links itself at load with
+ * {@link linkRealtimeToHub}; until then plain errors with the same fields are
+ * used, so a forwarder imported on its own still works.
+ */
+import { readField } from './cross-bundle';
+import type { RealtimeErrorShape } from './wire-types';
+
+/** The core client's side of the link. */
+export interface RealtimeHubLink {
+  /** Re-create an error from the runtime (another bundle) as this client's `HubError` family. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: a rejection from another bundle
+  toHubError(error: unknown): Error;
+  /** This client's `OfflineError` with a message. */
+  createOfflineError(message: string): Error;
+  /** A 60-second identity ticket for this game's own server (`POST /mp/ticket`), straight from the hub. */
+  getGameServerTicket(): Promise<string>;
+}
+
+/** Copy the error-body fields of another bundle's error onto a plain `Error`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a rejection from another bundle
+function copyAsPlainError(error: unknown): RealtimeErrorShape {
+  if (error instanceof Error) {
+    return error;
+  }
+  const message = readField(error, 'message');
+  const copy: RealtimeErrorShape = new Error(typeof message === 'string' ? message : String(error));
+  for (const key of ['status', 'retryAfterMs'] as const) {
+    const field = readField(error, key);
+    if (typeof field === 'number') {
+      copy[key] = field;
+    }
+  }
+  for (const key of ['code', 'reason', 'hint'] as const) {
+    const field = readField(error, key);
+    if (typeof field === 'string') {
+      copy[key] = field;
+    }
+  }
+  return copy;
+}
+
+const standaloneLink: RealtimeHubLink = {
+  toHubError: copyAsPlainError,
+  createOfflineError(message) {
+    const offline: RealtimeErrorShape = new Error(message);
+    offline.code = 'offline';
+    return offline;
+  },
+  getGameServerTicket: () => Promise.reject(new Error('Hub: import @diffenderfer-games/hub to request game-server tickets.')),
+};
+
+let currentLink: RealtimeHubLink = standaloneLink;
+
+/** Called once by the core client so forwarder errors use its classes and tickets use its REST client. */
+export function linkRealtimeToHub(link: RealtimeHubLink): void {
+  currentLink = link;
+}
+
+/** The link in effect. */
+export function hubLink(): RealtimeHubLink {
+  return currentLink;
+}

package/src/realtime/latest-state.ts

@@ -0,0 +1,33 @@
+/**
+ * The "latest state" calls (presence, the busy flag, quiet mode): only the
+ * last value matters, so each is remembered and replayed, in that order,
+ * when the social runtime loads.
+ */
+import type { PresenceInput } from '@diffenderfer-games/hub-contract';
+import { pageBridge } from './bridge';
+import type { BusyOptions } from './multiplayer-types';
+
+/** The busy flag as last set. */
+interface BusyState {
+  readonly isBusy: boolean;
+  readonly options: BusyOptions;
+}
+
+/** The latest state calls, as last made on this page. */
+export const latestState: { presence: PresenceInput | null; busy: BusyState | null; isQuiet: boolean | null } = {
+  presence: null,
+  busy: null,
+  isQuiet: null,
+};
+
+pageBridge.onReady((realtime) => {
+  if (latestState.presence !== null) {
+    realtime.presence.set(latestState.presence);
+  }
+  if (latestState.busy !== null) {
+    realtime.mp.setBusy(latestState.busy.isBusy, latestState.busy.options);
+  }
+  if (latestState.isQuiet !== null) {
+    realtime.notify.setQuiet(latestState.isQuiet);
+  }
+});

package/src/realtime/multiplayer-forwarder.ts

@@ -0,0 +1,28 @@
+/**
+ * `hub.mp`: invites, launches, the leave guard and own-server tickets,
+ * forwarded to the social runtime.
+ */
+import { getUiStack } from '../uistack/page-stack';
+import { pageBridge } from './bridge';
+import { hubLink } from './hub-link';
+import { latestState } from './latest-state';
+import type { HubMpApi } from './multiplayer-types';
+
+/** `hub.mp`: the multiplayer lifecycle. */
+export const multiplayerForwarder: HubMpApi = {
+  onLaunch: (listener) => pageBridge.subscribe((realtime) => realtime.mp.onLaunch(listener)),
+  onJoinInfo: (listener) => pageBridge.subscribe((realtime) => realtime.mp.onJoinInfo(listener)),
+  invite: (userId, options) => pageBridge.call((realtime) => realtime.mp.invite(userId, options)),
+  setBusy(isBusy, options) {
+    const busyOptions = options?.label === undefined ? {} : { label: options.label };
+    latestState.busy = { isBusy, options: busyOptions };
+    // The overlay stack is local, so "can't pause" works even without the runtime.
+    getUiStack().setCanPause(!isBusy);
+    pageBridge.current()?.mp.setBusy(isBusy, busyOptions);
+  },
+  // A direct request, not a runtime call: "Play online" must not depend on the
+  // social runtime having loaded (an old cached menu may never load it).
+  ticket: () => hubLink().getGameServerTicket(),
+  setJoinInfo: (partyId, joinInfo) => pageBridge.call((realtime) => realtime.mp.setJoinInfo(partyId, joinInfo)),
+  party: () => pageBridge.current()?.mp.party() ?? null,
+};

package/src/realtime/multiplayer-types.ts

@@ -0,0 +1,52 @@
+/**
+ * The multiplayer lifecycle as games see it through `hub.mp`: invites,
+ * launches, the leave guard and own-server tickets.
+ */
+import type { Invite, JoinInfo, Launch, Party } from '@diffenderfer-games/hub-contract';
+
+/** `hub.mp.onJoinInfo` payload: the party leader published where to connect. */
+export interface JoinInfoEvent {
+  /** The party it is for. */
+  partyId: string;
+  /** Opaque connection details (a room code, a server address…). */
+  info: JoinInfo;
+}
+
+/** What `hub.mp.invite` resolves with. */
+export interface InviteResult {
+  /** The invite as sent. */
+  invite: Invite;
+}
+
+/** Options for `hub.mp.invite`. */
+export interface InviteOptions {
+  /** The game mode to invite to. */
+  mode?: string;
+}
+
+/** Options for `hub.mp.setBusy`. */
+export interface BusyOptions {
+  /** What the leave-confirmation calls the match ("a duel"). */
+  label?: string;
+}
+
+/** `hub.mp`: the multiplayer lifecycle (docs/multiplayer.md §7). */
+export interface HubMpApi {
+  /** Invite, join and watch arrivals. Call at boot; launches that arrived earlier are buffered. */
+  onLaunch(listener: (launch: Launch) => void): () => void;
+  /** The party leader published join info (e.g. a room code). */
+  onJoinInfo(listener: (event: JoinInfoEvent) => void): () => void;
+  /** Invite a friend to this game. Rejects with `HubError` or `OfflineError`. */
+  invite(userId: number, options?: InviteOptions): Promise<InviteResult>;
+  /**
+   * A live match is in progress: the hub confirms before navigating away and
+   * overlay events carry `canPause: false`.
+   */
+  setBusy(isBusy: boolean, options?: BusyOptions): void;
+  /** A 60-second identity ticket for your own game server. */
+  ticket(): Promise<string>;
+  /** Host side, own-server games: tell the party where to connect. */
+  setJoinInfo(partyId: string, joinInfo: JoinInfo): Promise<void>;
+  /** My current party, or `null` (also `null` until the runtime is up). */
+  party(): Party | null;
+}