@diffenderfer-games/hub 2.0.0-next.1 → 2.0.0-next.3

package/src/input/input-system.ts

@@ -13,6 +13,8 @@ import { RepeatingEdges, RisingEdges } from './edges';
 import { isAnyPadButtonPressed, PAD_BUTTON } from './gamepad';
 import { InputEventHub } from './input-events';
 import { InputRegistry } from './input-registry';
+import { trackInputModality } from './modality';
+import type { ModalityTracker } from './modality';
 import { parseLegacyControls } from './legacy-controls';
 import type { LegacyControls } from './legacy-controls';
 import { Navigator } from './navigator';
@@ -56,6 +58,7 @@ export class InputSystem implements ControlsPanelHost, PageInputControl {
   private activeSource: InputSource = 'keyboard';
   private isPageOwner: boolean;
   private pageOwner: PageInputControl | null = null;
+  private readonly modality: ModalityTracker | null = typeof document === 'undefined' ? null : trackInputModality();
 
   constructor(host: InputHost, options: InputSystemOptions = {}) {
     this.host = host;
@@ -352,6 +355,7 @@ export class InputSystem implements ControlsPanelHost, PageInputControl {
     this.controls.isGamepadConnected = isConnected;
     if (hasActivity) {
       this.setSource('gamepad');
+      this.modality?.set('keys');
     }
     if (this.isPageOwner) {
       this.driveFrame();

package/src/input/modality.ts

@@ -0,0 +1,122 @@
+/**
+ * Which kind of input the player used last, published as `data-hub-input` on
+ * `<html>` so focus styles show only to keyboard and gamepad players: a tap or
+ * click never leaves a ring behind, and touch devices show none at all. The
+ * attribute is the shared state, so every bundle's copy of the client agrees.
+ */
+import { isTypingTarget } from './device-state';
+import { FOCUS_RING_SHADOW } from './focus-ring';
+
+/** `keys`: keyboard or gamepad. `pointer`: mouse or pen. `touch`: a finger. */
+export type InputModality = 'keys' | 'pointer' | 'touch';
+
+/** The `<html>` attribute that holds the modality. */
+export const MODALITY_ATTRIBUTE = 'data-hub-input';
+
+const STYLE_ID = 'hub-focus-style';
+const MODIFIER_KEYS = new Set(['Shift', 'Control', 'Alt', 'Meta', 'AltGraph', 'CapsLock']);
+const MODALITIES: readonly InputModality[] = ['keys', 'pointer', 'touch'];
+
+/**
+ * The page focus styles: the gamepad highlight (`gp-focus`) for keyboard and
+ * gamepad players only, and no browser focus ring on buttons after a tap.
+ */
+const PAGE_FOCUS_CSS = `html[${MODALITY_ATTRIBUTE}="keys"] .gp-focus{outline:none !important;box-shadow:${FOCUS_RING_SHADOW} !important;}
+html[${MODALITY_ATTRIBUTE}="touch"] :is(button,a,summary,[role="button"],[tabindex]):focus{outline:none;}`;
+
+/** The modality a pointer event's `pointerType` implies. */
+export function modalityOfPointer(pointerType: string): InputModality {
+  return pointerType === 'touch' ? 'touch' : 'pointer';
+}
+
+/** The modality a key press implies, or `null` when it says nothing (a lone modifier, typing in a field). */
+export function modalityOfKey(key: string, isTyping: boolean): InputModality | null {
+  if (MODIFIER_KEYS.has(key)) {
+    return null;
+  }
+  // Typing (an on-screen keyboard fires keydown too) is not navigating; Tab always is.
+  return isTyping && key !== 'Tab' ? null : 'keys';
+}
+
+/** Where the modality is stored: `<html>`, or a fake in tests. */
+export interface ModalityRoot {
+  getAttribute(name: string): string | null;
+  setAttribute(name: string, value: string): void;
+}
+
+/** Reads and writes the page's modality attribute. */
+export class ModalityTracker {
+  private readonly root: ModalityRoot;
+
+  /** Start at `initial` unless another copy already set the attribute. */
+  constructor(root: ModalityRoot, initial: InputModality) {
+    this.root = root;
+    if (this.readAttribute() === null) {
+      this.set(initial);
+    }
+  }
+
+  /** The last modality used. */
+  get current(): InputModality {
+    return this.readAttribute() ?? 'pointer';
+  }
+
+  /** Whether focus should show: the last input was a keyboard or gamepad. */
+  get showsFocus(): boolean {
+    return this.current === 'keys';
+  }
+
+  /** Record the modality the player just used. */
+  set(modality: InputModality): void {
+    if (this.readAttribute() !== modality) {
+      this.root.setAttribute(MODALITY_ATTRIBUTE, modality);
+    }
+  }
+
+  /** A key went down (`isTyping`: in a text field). */
+  noteKey(key: string, isTyping: boolean): void {
+    const modality = modalityOfKey(key, isTyping);
+    if (modality !== null) {
+      this.set(modality);
+    }
+  }
+
+  /** A pointer went down. */
+  notePointer(pointerType: string): void {
+    this.set(modalityOfPointer(pointerType));
+  }
+
+  private readAttribute(): InputModality | null {
+    const value = this.root.getAttribute(MODALITY_ATTRIBUTE);
+    return MODALITIES.find((modality) => modality === value) ?? null;
+  }
+}
+
+let pageTracker: ModalityTracker | null = null;
+
+/** Track the page's modality (once per bundle) and add the focus styles (once per page). */
+export function trackInputModality(): ModalityTracker {
+  if (pageTracker !== null) {
+    return pageTracker;
+  }
+  const root = document.documentElement;
+  const isTouchDevice = typeof matchMedia === 'function' && matchMedia('(hover: none) and (pointer: coarse)').matches;
+  const isFirstCopy = root.getAttribute(MODALITY_ATTRIBUTE) === null;
+  const tracker = new ModalityTracker(root, isTouchDevice ? 'touch' : 'pointer');
+  pageTracker = tracker;
+  if (isFirstCopy) {
+    document.addEventListener('keydown', (event) => {
+      tracker.noteKey(event.key, isTypingTarget(event.target));
+    }, true);
+    document.addEventListener('pointerdown', (event) => {
+      tracker.notePointer(event.pointerType);
+    }, true);
+  }
+  if (document.getElementById(STYLE_ID) === null) {
+    const style = document.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = PAGE_FOCUS_CSS;
+    document.head.appendChild(style);
+  }
+  return tracker;
+}

package/src/input/nav-state.ts

@@ -9,8 +9,8 @@ import type { NavBlurEvent, NavElement, NavElementKind, NavFocusEvent, NavTarget
 
 /** What a navigable list draws with (the overlay). */
 export interface NavHighlighter {
-  /** Ring the highlighted element. */
-  showHighlight(bounds: Rect): void;
+  /** Ring the highlighted element, following its corner radius (a CSS `border-radius`, or empty). */
+  showHighlight(bounds: Rect, radius: string): void;
   /** Remove the ring. */
   hideHighlight(): void;
   /** Open the on-screen keyboard for a text field. */
@@ -50,6 +50,11 @@ function boundsOf(element: NavElement): Rect {
   return element.el === undefined ? { x: 0, y: 0, width: 0, height: 0 } : rectOf(element.el);
 }
 
+/** A navigable element's CSS corner radius, so the ring can follow it (empty for a non-DOM element). */
+function radiusOf(element: NavElement): string {
+  return element.el === undefined ? '' : getComputedStyle(element.el).borderRadius;
+}
+
 /** The text field a navigable element edits, if it is one. */
 function textFieldOf(element: NavElement): HTMLInputElement | HTMLTextAreaElement | null {
   return element.el instanceof HTMLInputElement || element.el instanceof HTMLTextAreaElement ? element.el : null;
@@ -148,16 +153,20 @@ export class NavState {
     this.position(highlighter);
   }
 
-  /** Move the ring to the highlighted element (or hide it). */
+  /** Move the ring to the highlighted element (or hide it), following keyboard focus (Tab) within the list. */
   position(highlighter: NavHighlighter | null): void {
     if (highlighter === null) {
       return;
     }
+    const focused = this.elements.findIndex((element) => element.el !== undefined && element.el === document.activeElement);
+    if (focused >= 0) {
+      this.index = focused;
+    }
     const current = this.elements[this.index];
     if (current === undefined) {
       highlighter.hideHighlight();
     } else {
-      highlighter.showHighlight(boundsOf(current));
+      highlighter.showHighlight(boundsOf(current), radiusOf(current));
     }
   }
 

package/src/input/zero-config.ts

@@ -14,9 +14,8 @@ import { isTypingTarget } from './device-state';
 
 /** Synthetic keys stay pressed past half deflection. */
 const SYNTH_DEADZONE = 0.5;
+/** The catalog tile highlight; its style (keyboard and gamepad players only) is in `modality.ts`. */
 const FOCUS_CLASS = 'gp-focus';
-const FOCUS_STYLE_ID = 'gp-focus-style';
-const FOCUS_CSS = '.gp-focus{outline:3px solid #ff5f3b !important;outline-offset:2px;border-radius:4px;}';
 
 /** `KeyboardEvent.code` → its `key` and legacy `keyCode`. */
 const KEY_FOR_CODE = new Map<string, readonly [string, number]>([
@@ -51,17 +50,6 @@ function dispatchKey(type: 'keydown' | 'keyup', code: string): void {
   target.dispatchEvent(event);
 }
 
-/** Add the highlight style to the page once. */
-function ensureFocusStyle(): void {
-  if (document.getElementById(FOCUS_STYLE_ID) !== null) {
-    return;
-  }
-  const style = document.createElement('style');
-  style.id = FOCUS_STYLE_ID;
-  style.textContent = FOCUS_CSS;
-  document.head.appendChild(style);
-}
-
 /** The keys each pad holds down, by pad index. */
 const heldCodes = new Map<number, Set<string>>();
 
@@ -168,7 +156,6 @@ export function runZeroConfigFrame(frame: ZeroConfigFrame): void {
   if (frame.gamepads.length === 0) {
     return;
   }
-  ensureFocusStyle();
   if (frame.slug === null) {
     navigateCatalog(frame);
   } else {

package/src/input.ts

@@ -9,6 +9,9 @@ export { InputSystem } from './input/input-system';
 export type { InputSystemOptions } from './input/input-system';
 export { getInput, INPUT_SINGLETON_API, isInputSystem, parseInputOverrides } from './input/page-input';
 export type { InputOptions } from './input/page-input';
+export { FOCUS_RING_SHADOW } from './input/focus-ring';
+export { MODALITY_ATTRIBUTE, trackInputModality } from './input/modality';
+export type { InputModality } from './input/modality';
 export { isPageInputControl } from './input/page-control';
 export type { PageInputControl } from './input/page-control';
 export type * from './input/types';

package/src/mp.ts

@@ -6,5 +6,5 @@
  */
 export { multiplayerForwarder as mp } from './realtime/multiplayer-forwarder';
 export type * from './realtime/multiplayer-types';
-export type { InviteCreated } from './realtime/wire-types';
+export type { InviteCreated, InviteLink } from './realtime/wire-types';
 export type { Invite, JoinInfo, Launch, LaunchTicket, Party } from '@diffenderfer-games/hub-contract';

package/src/overlay/overlay.ts

@@ -6,6 +6,7 @@
  */
 import type { NavHighlighter } from '../input/nav-state';
 import type { InputConfig, InputOverrides, Rect, VirtualDef } from '../input/types';
+import { trackInputModality } from '../input/modality';
 import { readField } from '../realtime/cross-bundle';
 import { ControlsPanel } from './controls-panel';
 import type { ControlsPanelHost } from './controls-panel';
@@ -160,9 +161,10 @@ export class Overlay implements NavHighlighter {
     }
   }
 
-  /** Ring the highlighted element. */
-  showHighlight(bounds: Rect): void {
-    this.ring.hidden = false;
+  /** Ring the highlighted element, for keyboard and gamepad players only (never after a tap or click). */
+  showHighlight(bounds: Rect, radius: string): void {
+    this.ring.hidden = !trackInputModality().showsFocus;
+    this.ring.style.borderRadius = radius;
     this.ring.style.left = `${String(bounds.x)}px`;
     this.ring.style.top = `${String(bounds.y)}px`;
     this.ring.style.width = `${String(bounds.width)}px`;

package/src/overlay/styles.ts

@@ -1,6 +1,7 @@
 /**
  * The overlay's styles (inside its shadow root, so games can't restyle it).
  */
+import { FOCUS_RING_SHADOW } from '../input/focus-ring';
 
 /** The hub accent colour. */
 export const ACCENT_COLOR = '#ff5f3b';
@@ -28,8 +29,8 @@ export const OVERLAY_CSS = `
 :host(.editing) .edit-bar .btn { margin: 0; }
 .safe-probe { position: fixed; left: 0; top: 0; width: 0; height: 0; visibility: hidden; pointer-events: none;
   padding: env(safe-area-inset-top, 0px) env(safe-area-inset-right, 0px) env(safe-area-inset-bottom, 0px) env(safe-area-inset-left, 0px); }
-.ring { position: fixed; pointer-events: none; z-index: 2147483200; border: 3px solid ${ACCENT_COLOR}; border-radius: 8px;
-        box-shadow: 0 0 0 2px rgba(0,0,0,.4); transition: left .08s, top .08s, width .08s, height .08s; }
+.ring { position: fixed; pointer-events: none; z-index: 2147483200; box-shadow: ${FOCUS_RING_SHADOW};
+        transition: left .08s, top .08s, width .08s, height .08s; }
 .ring[hidden] { display: none; }
 .kb { position: fixed; left: 0; right: 0; bottom: 0; z-index: 2147483400; background: #0d0f14ee; padding: 10px;
       pointer-events: auto; border-top: 1px solid #2a3142; }
@@ -38,7 +39,7 @@ export const OVERLAY_CSS = `
 .kb .k { flex: 1; min-width: 0; max-width: 64px; height: 46px; border-radius: 8px; border: 1px solid #2a3142;
          background: #11141c; color: #e8e6df; font: 16px monospace; cursor: pointer; }
 .kb .k.space { max-width: 280px; } .kb .k.wide { max-width: 90px; }
-.kb .k.kfocus { border-color: ${ACCENT_COLOR}; box-shadow: 0 0 0 2px ${ACCENT_COLOR}; }
+.kb .k.kfocus { box-shadow: ${FOCUS_RING_SHADOW}; }
 .panel { position: fixed; inset: 0; z-index: 2147483500; display: grid; place-items: center; background: rgba(0,0,0,.6); pointer-events: auto;
          font-family: 'Space Mono', ui-monospace, monospace; }
 .panel-card { background: #0d0f14; color: #e8e6df; border: 1px solid #2a3142; border-radius: 12px; padding: 18px;

package/src/realtime/bridge.ts

@@ -117,5 +117,10 @@ export async function rethrowAsHubError<Result>(pending: Promise<Result>): Promi
   }
 }
 
+/** The rejection for a feature the page's social runtime is too old to have (version 3 additions). */
+export function outdatedRuntime(feature: string): Error {
+  return hubLink().createOfflineError(`${feature} needs the newest hub. Reload the page to update.`);
+}
+
 /** The page's one bridge (per client bundle). */
 export const pageBridge = new RealtimeBridge();

package/src/realtime/multiplayer-forwarder.ts

@@ -3,7 +3,7 @@
  * forwarded to the social runtime.
  */
 import { getUiStack } from '../uistack/page-stack';
-import { pageBridge } from './bridge';
+import { outdatedRuntime, pageBridge } from './bridge';
 import { hubLink } from './hub-link';
 import { latestState } from './latest-state';
 import type { HubMpApi } from './multiplayer-types';
@@ -25,4 +25,16 @@ export const multiplayerForwarder: HubMpApi = {
   ticket: () => hubLink().getGameServerTicket(),
   setJoinInfo: (partyId, joinInfo) => pageBridge.call((realtime) => realtime.mp.setJoinInfo(partyId, joinInfo)),
   party: () => pageBridge.current()?.mp.party() ?? null,
+  inviteLink: () => pageBridge.call((realtime) => {
+    if (realtime.mp.inviteLink === undefined) {
+      throw outdatedRuntime('Invite links');
+    }
+    return realtime.mp.inviteLink();
+  }),
+  revokeInviteLink: (token) => pageBridge.call((realtime) => {
+    if (realtime.mp.revokeInviteLink === undefined) {
+      throw outdatedRuntime('Invite links');
+    }
+    return realtime.mp.revokeInviteLink(token);
+  }),
 };

package/src/realtime/multiplayer-types.ts

@@ -3,6 +3,7 @@
  * launches, the leave guard and own-server tickets.
  */
 import type { Invite, JoinInfo, Launch, Party } from '@diffenderfer-games/hub-contract';
+import type { InviteLink } from './wire-types';
 
 /** `hub.mp.onJoinInfo` payload: the party leader published where to connect. */
 export interface JoinInfoEvent {
@@ -30,8 +31,21 @@ export interface BusyOptions {
   label?: string;
 }
 
+/** What feature version 3 added to `hub.mp`: invite links. */
+export interface InviteLinkMethods {
+  /**
+   * A shareable link to the room I'm in (my live one when it exists): anyone
+   * who opens it joins while a seat is free, otherwise watches. It expires
+   * after 24 h. Claimed accounts only; rejects with `HubError`
+   * (`not_in_room`, `too_many_links`, `rate_limited`) or `OfflineError`.
+   */
+  inviteLink(): Promise<InviteLink>;
+  /** Revoke a link I made, or one into a room I host. */
+  revokeInviteLink(token: string): Promise<void>;
+}
+
 /** `hub.mp`: the multiplayer lifecycle (docs/multiplayer.md §7). */
-export interface HubMpApi {
+export interface HubMpApi extends InviteLinkMethods {
   /** 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). */

package/src/realtime/room-types.ts

@@ -3,7 +3,7 @@
  * 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';
+import type { RoomChatLine, RoomMessage, RoomSeat, RoomSeatChange } from './wire-types';
 
 /** The shared room state (a JSON object, at most 32 KB). */
 export type RoomState = Record<string, Json>;
@@ -20,6 +20,13 @@ export interface RoomCreateOptions {
   maxPlayers?: number;
   /** `host` (default): guests' unaddressed sends reach the host only. `relay`: everyone hears every send. */
   model?: 'host' | 'relay';
+  /**
+   * When the host role moves on mid-game: `grace` (default) once the host's
+   * seat is freed (left, or 3 minutes away), so a host holding hidden state
+   * can come back; `drop` as soon as the host drops, for games whose truth is
+   * all in `setState`.
+   */
+  hostMigration?: 'grace' | 'drop';
   /** Seat this party in the room. */
   partyId?: string;
 }
@@ -52,6 +59,13 @@ export interface RoomEvents {
   ended: { room: RoomInfo; results?: Json };
   /** A player left mid-game (or their reconnect grace ran out). */
   abandoned: { userId: number; reason?: string };
+  /**
+   * A seat changed: `away` (dropped; held until `graceEndsAt`, so hand it to
+   * your computer player), `back` (reclaimed: give control back) or `gone`
+   * (freed: left, kicked or the grace ran out). The game never ends on its
+   * own because of this; `info.hostId` may have moved to another player.
+   */
+  seat: RoomSeatChange;
 }
 
 /** Who I am in a room. */
@@ -84,6 +98,8 @@ export interface HubRoom {
   readonly state: RoomState;
   /** Who I am in this room. */
   readonly me: RoomSelf;
+  /** The seats as last reported; `connected: false` while a seat is away. */
+  seats(): RoomSeat[];
   /** 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). */
@@ -114,8 +130,18 @@ export interface RoomListOptions {
   mode?: string;
 }
 
+/** What feature version 3 added to `hub.rooms`. */
+export interface RoomReclaimMethods {
+  /**
+   * Take back the seat I still hold in this game (after a reload, from
+   * another tab): the room, or `null` when I hold none. The hub also does
+   * this on its own at boot, as a `join` launch with `via: 'rejoin'`.
+   */
+  reclaim(): Promise<HubRoom | null>;
+}
+
 /** `hub.rooms`: hub relay rooms (static games, no server). */
-export interface HubRoomsApi {
+export interface HubRoomsApi extends RoomReclaimMethods {
   /** Create a room and take its first seat. */
   create(options?: RoomCreateOptions): Promise<HubRoom>;
   /** Join a room by its 5-character code or its id. */

package/src/realtime/rooms-forwarder.ts

@@ -3,8 +3,9 @@
  * 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 { outdatedRuntime, pageBridge, rethrowAsHubError } from './bridge';
 import type { HubRoom, HubRoomsApi, RoomEvents, RoomSelf, RoomSendOptions, RoomState, RoomStateOptions } from './room-types';
+import type { RoomSeat } from './wire-types';
 
 /** A runtime room whose rejections are re-created as the core client's errors. */
 class ForwardedRoom implements HubRoom {
@@ -26,6 +27,10 @@ class ForwardedRoom implements HubRoom {
     return this.room.me;
   }
 
+  seats(): RoomSeat[] {
+    return this.room.info.seats;
+  }
+
   on<Name extends keyof RoomEvents>(event: Name, listener: (payload: RoomEvents[Name]) => void): () => void {
     return this.room.on(event, listener);
   }
@@ -76,4 +81,11 @@ 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)),
+  reclaim: () => pageBridge.call(async (realtime) => {
+    if (realtime.rooms.reclaim === undefined) {
+      throw outdatedRuntime('Taking back a seat');
+    }
+    const held = await realtime.rooms.reclaim();
+    return held === null ? null : new ForwardedRoom(held);
+  }),
 };

package/src/realtime/runtime-api.ts

@@ -3,16 +3,27 @@
  * 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 { HubMpApi, InviteLinkMethods } from './multiplayer-types';
 import type { HubRaceApi } from './race-types';
-import type { HubRoomsApi } from './room-types';
-import type { HubNotifyApi, HubPresenceApi, HubSocialApi } from './social-types';
+import type { HubRoomsApi, RoomReclaimMethods } from './room-types';
+import type { HubNotifyApi, HubPresenceApi, HubSocialApi, PlayOnlineMethods } 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.
+ * 2 added races; 3 added invite links and taking back a held seat; 4 added
+ * "Play online" (tournaments). A client feature-detects newer additions with
+ * it (or by the optional method).
  */
-export const REALTIME_FEATURE_VERSION = 2;
+export const REALTIME_FEATURE_VERSION = 4;
+
+/** `hub.social` as a runtime installs it: version 4's `openPlayOnline` is missing on older runtimes. */
+export type RuntimeSocialApi = Omit<HubSocialApi, keyof PlayOnlineMethods> & Partial<PlayOnlineMethods>;
+
+/** `hub.mp` as a runtime installs it: version 3's invite-link methods are missing on older runtimes. */
+export type RuntimeMpApi = Omit<HubMpApi, keyof InviteLinkMethods> & Partial<InviteLinkMethods>;
+
+/** `hub.rooms` as a runtime installs it: version 3's `reclaim` is missing on older runtimes. */
+export type RuntimeRoomsApi = Omit<HubRoomsApi, keyof RoomReclaimMethods> & Partial<RoomReclaimMethods>;
 
 /**
  * The cross-bundle shape number of the `rt` page singleton (plan §4.4). The
@@ -37,11 +48,11 @@ export interface RealtimeApi {
   /** Presence reporting. */
   presence: HubPresenceApi;
   /** Friends and the social dialogs. */
-  social: HubSocialApi;
+  social: RuntimeSocialApi;
   /** Invites, launches, the leave guard and tickets. */
-  mp: HubMpApi;
+  mp: RuntimeMpApi;
   /** Hub relay rooms. */
-  rooms: HubRoomsApi;
+  rooms: RuntimeRoomsApi;
   /** Toast behaviour. */
   notify: HubNotifyApi;
   /** Races (feature version 2 and later). */

package/src/realtime/social-forwarder.ts

@@ -65,6 +65,11 @@ export const socialForwarder: HubSocialApi = {
       realtime.social.openNotify(options);
     });
   },
+  openPlayOnline: () => {
+    openWithRuntime((realtime) => {
+      realtime.social.openPlayOnline?.();
+    });
+  },
   friends: () => pageBridge.call((realtime) => realtime.social.friends()),
   counts: () => pageBridge.current()?.social.counts() ?? { ...NO_COUNTS },
   chatMode: (userIds) => pageBridge.current()?.social.chatMode(userIds) ?? 'off',

package/src/realtime/social-types.ts

@@ -61,6 +61,11 @@ export interface HubSocialApi {
   openSuggest(): void;
   /** Open notification settings, optionally focused on a game's lobby bell. */
   openNotify(options?: { game?: string }): void;
+  /**
+   * Open "Play online": games waiting for a player, invites, tournaments and
+   * the quick 1v1 (feature version 4; a no-op on older runtimes).
+   */
+  openPlayOnline(): void;
   /** Friends with live presence. Rejects with `OfflineError` without the runtime. */
   friends(): Promise<FriendEntry[]>;
   /** Live counts; all zero until the runtime is up. */
@@ -71,6 +76,9 @@ export interface HubSocialApi {
   on<Name extends keyof SocialEvents>(event: Name, listener: (payload: SocialEvents[Name]) => void): () => void;
 }
 
+/** What feature version 4 added to `hub.social`. */
+export type PlayOnlineMethods = Pick<HubSocialApi, 'openPlayOnline'>;
+
 /** `hub.notify`: toast behaviour during intense play. */
 export interface HubNotifyApi {
   /** Quiet: toasts collapse into the menu badge; invites still show as a small pill. */

package/src/realtime/wire-types.ts

@@ -9,6 +9,7 @@ import type {
   OpAck,
   ops,
   InviteCreated as InviteCreatedSchema,
+  InviteLink as InviteLinkSchema,
   RaceHistory as RaceHistorySchema,
   RaceResultPlayer as RaceResultPlayerSchema,
   RaceRecordPlayer as RaceRecordPlayerSchema,
@@ -51,6 +52,12 @@ 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 seat went away, came back or is gone (`ev:room.seat`). */
+export type RoomSeatChange = ServerEvents['room.seat'];
+
+/** A shareable invite link into a room (`POST /mp/links`). */
+export type InviteLink = SchemaOutput<typeof InviteLinkSchema>;
+
 /** A moderated room chat line (`ev:room.chat`). */
 export type RoomChatLine = ServerEvents['room.chat'];
 

package/src/rooms.ts

@@ -6,5 +6,5 @@
  */
 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 { RoomChatLine, RoomMessage, RoomSeat, RoomSeatChange, RoomStateChange } from './realtime/wire-types';
 export type { RoomInfo } from '@diffenderfer-games/hub-contract';