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

package/src/realtime/bridge.ts

@@ -1,121 +1,126 @@
-/**
- * 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();
+/**
+ * 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 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/cross-bundle.ts

@@ -1,29 +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;
-}
+/**
+ * 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

@@ -1,48 +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();
-  }
-}
+/**
+ * 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

@@ -1,65 +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;
-}
+/**
+ * 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

@@ -1,33 +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);
-  }
-});
+/**
+ * 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);
+  }
+});