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

package/src/index.ts

@@ -13,10 +13,11 @@
  * {@link createHub} for others. Every call rejects with a {@link HubError}
  * when it fails, except the fire-and-forget analytics (`recordPlay`,
  * `heartbeat`, `event`). When the hub can't be reached, reads come from an
- * offline cache and writes are queued until it is back.
+ * offline cache and writes are queued in an outbox until it is back; games
+ * queue their own operations with `hub.offline` (docs: "Offline and replay").
  *
  * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
- * `hub.daily`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
+ * `hub.daily`, `hub.resume`, `hub.saved`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
  * its own entry (`@diffenderfer-games/hub/input`, ...) for games that want
  * only that part.
  *
@@ -27,6 +28,7 @@ export {
   ContentRejectedError,
   HubError,
   OfflineError,
+  SAVE_UNKNOWN_CODE,
   UNSUPPORTED_BY_HUB,
   type HubErrorCode,
   type HubErrorDetails,
@@ -35,7 +37,23 @@ export type { SyncConflict, SyncResult } from './core/connection';
 export type { AuthResponse, ProfileUpdate, StatResult } from './core/hub-progress';
 export type { GrantBundle, TradeBundle, TradeId, TradeListOptions, TradeNoteOptions } from './core/hub-economy';
 export type { HubMenuControl } from './core/menu-control';
+export { HubResume, RESUME_DEBOUNCE_MS, RESUME_MAX_STATE_BYTES } from './core/resume/hub-resume';
+export { HubAvatar, type AvatarHost, type AvatarModule } from './core/avatar/hub-avatar';
+export type { AvatarChange, AvatarRef, DesignerResult, OpenDesignerOptions, RuntimeAvatarApi } from './core/avatar/avatar-types';
+export type { CarriesLook } from './core/avatar/avatar-ref';
+export type { ResumeBlocker, ResumeEntry, ResumeLoadOptions, ResumeProgress, ResumeRun, ResumeSaveInput } from './core/resume/resume-types';
+export { HubSaved, SAVED_CHANGE_QUIET_MS, type SavedChangeListener, type SavedOpenDetail, type SavedOpenHandler } from './core/saved/hub-saved';
+export { SAVED_CHANGE_EVENT, SAVED_KIND_PARAM, SAVED_OPEN_EVENT, SAVED_OPEN_PARAM, savedGameUrl } from './core/saved/saved-open';
+export type * from './core/saved/saved-types';
+export { HubTurns, TURN_LINK_PARAM, type TurnCreateOptions } from './core/turns/hub-turns';
+export { isNewlyDue, readYourTurnBuzz, saveYourTurnBuzz, YOUR_TURN_BUZZ, YOUR_TURN_BUZZ_KEY } from './core/turns/your-turn-buzz';
+export { TURN_CHAT_EVENT, TURN_EVENT, TURN_POLL_MS, TURN_QUIET_MS, TURN_RESYNC_EVENT, TurnGame, type TurnGameEvents, type TurnGameOptions, type TurnMoveEvent, type TurnOutcome } from './core/turns/turn-game';
+export type { OpenTurnGame, TurnChatLine, TurnDeadline, TurnGameView } from '@diffenderfer-games/hub-contract';
 export type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
+export { OfflineApi } from './core/offline/offline-api';
+export { OUTBOX_FULL_CODE, type OfflineEventDetails, type OfflineEventName, type OfflineListener, type OfflineOp } from './core/offline/outbox';
+export type { OfflineHandler, OfflineKindDefinition, ReplayContext } from './core/offline/outbox-kinds';
+export { OUTBOX_MAX_CHARS, OUTBOX_MAX_ENTRIES } from './core/offline/outbox-store';
 export type { BufferedEvent } from './core/offline/events';
 export type { EndpointFields, EndpointName, EndpointReply } from './core/rest/endpoint-types';
 export { CLIENT_VERSION_HEADER } from './core/rest/rest-client';

package/src/input/focus-ring.ts

@@ -0,0 +1,13 @@
+/**
+ * The hub's focus ring: a two-tone box-shadow (a dark gap, then a light ring)
+ * that follows the element's own border-radius and shows on light and dark
+ * buttons alike. Pages tune it with CSS variables:
+ * `--hub-focus-color` (the ring), `--hub-focus-inner` (the gap),
+ * `--hub-focus-width` and `--hub-focus-gap`.
+ */
+
+const GAP = 'var(--hub-focus-gap, 2px)';
+const WIDTH = 'var(--hub-focus-width, 3px)';
+
+/** The ring as a `box-shadow` value. */
+export const FOCUS_RING_SHADOW = `0 0 0 ${GAP} var(--hub-focus-inner, rgba(13, 15, 20, 0.85)), 0 0 0 calc(${GAP} + ${WIDTH}) var(--hub-focus-color, #fff)`;

package/src/input/input-registry.ts

@@ -132,13 +132,20 @@ export class InputRegistry {
     return { value: raw, raw, isDown: this.wentDown(name), isUp: this.wentUp(name) };
   }
 
-  /** A named axis (or an ad-hoc negative/positive pair) as -1..1. */
+  /**
+   * A named axis (or an ad-hoc negative/positive pair) as -1..1: its `x`, or
+   * its `y` when it declares only `y` (a vertical one-axis control, like a
+   * paddle).
+   */
   axis(name: string, positive?: string): number {
     if (positive !== undefined) {
       return clampUnit(this.value(positive)) - clampUnit(this.value(name));
     }
     const axis = this.axes.get(name);
-    return axis === undefined ? this.value(name) : readAxisSide(axis.x, (input) => this.value(input));
+    if (axis === undefined) {
+      return this.value(name);
+    }
+    return readAxisSide(axis.x ?? axis.y, (input) => this.value(input));
   }
 
   /** A named axis pair as a vector clamped to the unit circle. */

package/src/input/input-system.ts

@@ -13,10 +13,12 @@ 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';
-import type { NavigatorContext } from './navigator';
+import type { AutoNavigateTarget, NavigatorContext } from './navigator';
 import { feedDeviceState, OnScreenControls } from './on-screen-controls';
 import type { PageInputControl } from './page-control';
 import { describeBinding, PlayerRemaps } from './player-remaps';
@@ -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;
@@ -283,6 +286,15 @@ export class InputSystem implements ControlsPanelHost, PageInputControl {
     this.navigator.setAutoNavigate(Navigator.queryFor(selector), options?.back ?? null);
   }
 
+  /**
+   * The game's current `autoNavigate` target (its query and back action), or
+   * `null`. Hub UI that takes the gamepad for a while (a dialog) reads it,
+   * and gives it back with `autoNavigate(target.query, { back })` when done.
+   */
+  autoNavigateTarget(): AutoNavigateTarget | null {
+    return this.navigator.autoNavigateTarget();
+  }
+
   /** Stop navigating the game's own menu. */
   clearAutoNavigate(): void {
     this.navigator.clearAutoNavigate(this.controls.existingOverlay);
@@ -352,6 +364,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/navigator.ts

@@ -40,6 +40,12 @@ function visibleMatches(selector: string): HTMLElement[] {
   return [...document.querySelectorAll<HTMLElement>(selector)].filter((element) => element.getClientRects().length > 0);
 }
 
+/** What `autoNavigate` was last given: the targets' query and the back action. */
+export interface AutoNavigateTarget {
+  readonly query: () => NavTarget[];
+  readonly back: (() => void) | null;
+}
+
 /** A navigable group with its highlight state. */
 interface GroupNavigation {
   readonly definition: NavigableDef;
@@ -81,6 +87,11 @@ export class Navigator {
     this.autoNavigateState = null;
   }
 
+  /** The current auto-navigate target and back action, or `null` when none is set. */
+  autoNavigateTarget(): AutoNavigateTarget | null {
+    return this.autoNavigateQuery === null ? null : { query: this.autoNavigateQuery, back: this.autoNavigateBack };
+  }
+
   /** Make a CSS selector's visible matches the auto-navigate targets. */
   static queryFor(selector: string | (() => NavTarget[])): () => NavTarget[] {
     return typeof selector === 'string' ? () => visibleMatches(selector) : selector;

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,9 +9,13 @@ 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';
+export type { AutoNavigateTarget } from './input/navigator';
 export { Overlay } from './overlay/overlay';
 export { layoutControls } from './overlay/layout';
 export type { LayoutOptions } from './overlay/layout';

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';
@@ -122,9 +123,15 @@ export class Overlay implements NavHighlighter {
     }
   }
 
-  /** Game insets (px) auto-placed controls keep clear of, e.g. a top HUD bar. Merged with earlier calls. */
+  /**
+   * Game insets (px) auto-placed controls keep clear of, e.g. a top HUD bar.
+   * Merged with earlier calls. Also published on the page as
+   * `--hub-inset-top` (and right, bottom, left), so the hub's toasts sit
+   * below a top HUD too.
+   */
   setInsets(insets: Partial<Insets>): void {
     this.gameInsets = { ...this.gameInsets, ...insets };
+    publishInsets(this.gameInsets);
     this.layout();
   }
 
@@ -160,9 +167,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`;
@@ -206,3 +214,21 @@ export class Overlay implements NavHighlighter {
     return { top: pixels(style.paddingTop), right: pixels(style.paddingRight), bottom: pixels(style.paddingBottom), left: pixels(style.paddingLeft) };
   }
 }
+
+/** Every inset side. */
+const INSET_SIDES: readonly (keyof Insets)[] = ['top', 'right', 'bottom', 'left'];
+
+/** The page-wide CSS variables other hub UI (the runtime's toasts) keeps clear of. */
+function publishInsets(insets: Partial<Insets>): void {
+  if (typeof document === 'undefined') {
+    return;
+  }
+  for (const side of INSET_SIDES) {
+    const px = insets[side];
+    if (px === undefined) {
+      document.documentElement.style.removeProperty(`--hub-inset-${side}`);
+    } else {
+      document.documentElement.style.setProperty(`--hub-inset-${side}`, `${String(Math.max(0, Math.round(px)))}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. */