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

package/src/uistack/play-suspension.ts

@@ -1,82 +1,82 @@
-/**
- * While hub UI covers the game, its `play` input group is held disabled (so a
- * paddle doesn't move while the player types), even for games that ignore
- * the overlay events. The game's own enable/disable calls for `play` are
- * recorded instead of applied, and the last one wins on release, so a game
- * that pauses itself on `open` stays paused afterwards.
- */
-import { hasMethods } from '../realtime/cross-bundle';
-
-/** The input group the stack suspends. */
-export const PLAY_GROUP = 'play';
-
-/** The slice of the page's input system the stack needs (any bundle's). */
-export interface GroupSwitch {
-  /** Whether a group is on. */
-  isEnabled(group: string): boolean;
-  /** Turn a group on. */
-  enable(group: string): void;
-  /** Turn a group off. */
-  disable(group: string): void;
-}
-
-/** Whether `candidate` can switch input groups. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the page's input system may come from another bundle
-export function isGroupSwitch(candidate: unknown): candidate is GroupSwitch {
-  return hasMethods(candidate, ['isEnabled', 'enable', 'disable']);
-}
-
-/** The intercepted method names. */
-const SWITCH_METHODS = ['enable', 'disable'] as const;
-
-/** Holds `play` disabled for one overlay visit. */
-export class PlaySuspension {
-  private readonly input: GroupSwitch;
-  private shouldPlayAfter: boolean;
-  /** The own-property descriptors replaced (`undefined` = the method lived on the prototype). */
-  private readonly savedMethods: Record<(typeof SWITCH_METHODS)[number], PropertyDescriptor | undefined>;
-
-  constructor(input: GroupSwitch) {
-    this.input = input;
-    this.shouldPlayAfter = input.isEnabled(PLAY_GROUP);
-    if (this.shouldPlayAfter) {
-      input.disable(PLAY_GROUP);
-    }
-    this.savedMethods = {
-      enable: Object.getOwnPropertyDescriptor(input, 'enable'),
-      disable: Object.getOwnPropertyDescriptor(input, 'disable'),
-    };
-    const enableGroup = input.enable.bind(input);
-    const disableGroup = input.disable.bind(input);
-    // Own-property overrides shadow the real methods until release().
-    input.enable = (group: string): void => {
-      if (group === PLAY_GROUP) {
-        this.shouldPlayAfter = true;
-      } else {
-        enableGroup(group);
-      }
-    };
-    input.disable = (group: string): void => {
-      if (group === PLAY_GROUP) {
-        this.shouldPlayAfter = false;
-      } else {
-        disableGroup(group);
-      }
-    };
-  }
-
-  /** Remove the interception and apply the state the game last asked for. */
-  release(): void {
-    for (const method of SWITCH_METHODS) {
-      const saved = this.savedMethods[method];
-      if (saved === undefined) {
-        Reflect.deleteProperty(this.input, method);
-      } else {
-        Object.defineProperty(this.input, method, saved);
-      }
-    }
-    if (this.shouldPlayAfter) {
-      this.input.enable(PLAY_GROUP);
-    }
-  }
-}
+/**
+ * While hub UI covers the game, its `play` input group is held disabled (so a
+ * paddle doesn't move while the player types), even for games that ignore
+ * the overlay events. The game's own enable/disable calls for `play` are
+ * recorded instead of applied, and the last one wins on release, so a game
+ * that pauses itself on `open` stays paused afterwards.
+ */
+import { hasMethods } from '../realtime/cross-bundle';
+
+/** The input group the stack suspends. */
+export const PLAY_GROUP = 'play';
+
+/** The slice of the page's input system the stack needs (any bundle's). */
+export interface GroupSwitch {
+  /** Whether a group is on. */
+  isEnabled(group: string): boolean;
+  /** Turn a group on. */
+  enable(group: string): void;
+  /** Turn a group off. */
+  disable(group: string): void;
+}
+
+/** Whether `candidate` can switch input groups. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the page's input system may come from another bundle
+export function isGroupSwitch(candidate: unknown): candidate is GroupSwitch {
+  return hasMethods(candidate, ['isEnabled', 'enable', 'disable']);
+}
+
+/** The intercepted method names. */
+const SWITCH_METHODS = ['enable', 'disable'] as const;
+
+/** Holds `play` disabled for one overlay visit. */
+export class PlaySuspension {
+  private readonly input: GroupSwitch;
+  private shouldPlayAfter: boolean;
+  /** The own-property descriptors replaced (`undefined` = the method lived on the prototype). */
+  private readonly savedMethods: Record<(typeof SWITCH_METHODS)[number], PropertyDescriptor | undefined>;
+
+  constructor(input: GroupSwitch) {
+    this.input = input;
+    this.shouldPlayAfter = input.isEnabled(PLAY_GROUP);
+    if (this.shouldPlayAfter) {
+      input.disable(PLAY_GROUP);
+    }
+    this.savedMethods = {
+      enable: Object.getOwnPropertyDescriptor(input, 'enable'),
+      disable: Object.getOwnPropertyDescriptor(input, 'disable'),
+    };
+    const enableGroup = input.enable.bind(input);
+    const disableGroup = input.disable.bind(input);
+    // Own-property overrides shadow the real methods until release().
+    input.enable = (group: string): void => {
+      if (group === PLAY_GROUP) {
+        this.shouldPlayAfter = true;
+      } else {
+        enableGroup(group);
+      }
+    };
+    input.disable = (group: string): void => {
+      if (group === PLAY_GROUP) {
+        this.shouldPlayAfter = false;
+      } else {
+        disableGroup(group);
+      }
+    };
+  }
+
+  /** Remove the interception and apply the state the game last asked for. */
+  release(): void {
+    for (const method of SWITCH_METHODS) {
+      const saved = this.savedMethods[method];
+      if (saved === undefined) {
+        Reflect.deleteProperty(this.input, method);
+      } else {
+        Object.defineProperty(this.input, method, saved);
+      }
+    }
+    if (this.shouldPlayAfter) {
+      this.input.enable(PLAY_GROUP);
+    }
+  }
+}

package/src/uistack/types.ts

@@ -1,76 +1,76 @@
-/**
- * The overlay stack's public shapes: "is the player looking at hub UI right
- * now?" (`hub.overlay`, docs/multiplayer.md §5.7).
- */
-
-/** Why the overlay opened, so a game can word its pause screen. */
-export type OverlayReason = 'menu' | 'chat' | 'dialog' | 'keyboard' | 'invite' | 'notify';
-
-/** An overlay edge. */
-export type OverlayEdge = 'open' | 'close';
-
-/** Payload of `open` and `close` (and of the `hub:overlay-open` / `hub:overlay-close` window events). */
-export interface OverlayEvent {
-  /** The reason of the entry that opened (for `open`) or closed last (for `close`). */
-  reason: OverlayReason;
-  /**
-   * False during a live online match (`hub.mp.setBusy(true)`): the game must
-   * keep simulating, so it should not pause.
-   */
-  canPause: boolean;
-}
-
-/** Options for {@link UiStack.autoPause}. */
-export interface AutoPauseOptions {
-  /** Pause exactly the way the game's own pause does. */
-  pause(): void;
-  /** Resume play. Only called when `resumeOnClose` is true. */
-  resume?(): void;
-  /**
-   * Resume automatically when the hub UI closes. Default false: action games
-   * should show their pause screen so the player resumes deliberately;
-   * turn-based and idle games may pass true.
-   */
-  resumeOnClose?: boolean;
-}
-
-/** A listener for overlay edges. */
-export type OverlayListener = (event: OverlayEvent) => void;
-
-/** What an older, idle stack hands to a newer one replacing it. */
-export interface UiStackHandoff {
-  /** Its listeners, by edge. */
-  listeners: { open: OverlayListener[]; close: OverlayListener[] };
-  /** Its pause permission. */
-  canPause: boolean;
-}
-
-/**
- * The page-wide overlay stack. Every piece of hub UI that covers the game
- * (the menu drawer, a dialog, the chat sheet…) pushes an entry while it shows
- * and pops it when it goes away; the game sees one `open` / `close` pair for
- * the whole visit, however the UI nests.
- */
-export interface UiStack {
-  /** Implementation version; a newer bundle replaces an older, idle instance. */
-  readonly version: number;
-  /** Register a covering piece of UI. Returns its idempotent `pop()`. */
-  push(reason: OverlayReason): () => void;
-  /** True while any hub UI covers the game. */
-  readonly isOpen: boolean;
-  /** Number of open entries (nesting depth). */
-  readonly depth: number;
-  /** Whether the game may pause right now (false during an online match). */
-  readonly canPause: boolean;
-  /** Subscribe to an edge. Returns the unsubscribe function. */
-  on(edge: OverlayEdge, listener: OverlayListener): () => void;
-  /**
-   * One-line adoption for games: pause on open (unless `canPause` is false),
-   * optionally resume on close. Returns a function that detaches it.
-   */
-  autoPause(options: AutoPauseOptions): () => void;
-  /** Driven by `hub.mp.setBusy`: false while a live match can't pause. */
-  setCanPause(canPause: boolean): void;
-  /** Hand listeners to a newer version replacing this (idle) instance. */
-  handoff(): UiStackHandoff;
-}
+/**
+ * The overlay stack's public shapes: "is the player looking at hub UI right
+ * now?" (`hub.overlay`, docs/multiplayer.md §5.7).
+ */
+
+/** Why the overlay opened, so a game can word its pause screen. */
+export type OverlayReason = 'menu' | 'chat' | 'dialog' | 'keyboard' | 'invite' | 'notify';
+
+/** An overlay edge. */
+export type OverlayEdge = 'open' | 'close';
+
+/** Payload of `open` and `close` (and of the `hub:overlay-open` / `hub:overlay-close` window events). */
+export interface OverlayEvent {
+  /** The reason of the entry that opened (for `open`) or closed last (for `close`). */
+  reason: OverlayReason;
+  /**
+   * False during a live online match (`hub.mp.setBusy(true)`): the game must
+   * keep simulating, so it should not pause.
+   */
+  canPause: boolean;
+}
+
+/** Options for {@link UiStack.autoPause}. */
+export interface AutoPauseOptions {
+  /** Pause exactly the way the game's own pause does. */
+  pause(): void;
+  /** Resume play. Only called when `resumeOnClose` is true. */
+  resume?(): void;
+  /**
+   * Resume automatically when the hub UI closes. Default false: action games
+   * should show their pause screen so the player resumes deliberately;
+   * turn-based and idle games may pass true.
+   */
+  resumeOnClose?: boolean;
+}
+
+/** A listener for overlay edges. */
+export type OverlayListener = (event: OverlayEvent) => void;
+
+/** What an older, idle stack hands to a newer one replacing it. */
+export interface UiStackHandoff {
+  /** Its listeners, by edge. */
+  listeners: { open: OverlayListener[]; close: OverlayListener[] };
+  /** Its pause permission. */
+  canPause: boolean;
+}
+
+/**
+ * The page-wide overlay stack. Every piece of hub UI that covers the game
+ * (the menu drawer, a dialog, the chat sheet…) pushes an entry while it shows
+ * and pops it when it goes away; the game sees one `open` / `close` pair for
+ * the whole visit, however the UI nests.
+ */
+export interface UiStack {
+  /** Implementation version; a newer bundle replaces an older, idle instance. */
+  readonly version: number;
+  /** Register a covering piece of UI. Returns its idempotent `pop()`. */
+  push(reason: OverlayReason): () => void;
+  /** True while any hub UI covers the game. */
+  readonly isOpen: boolean;
+  /** Number of open entries (nesting depth). */
+  readonly depth: number;
+  /** Whether the game may pause right now (false during an online match). */
+  readonly canPause: boolean;
+  /** Subscribe to an edge. Returns the unsubscribe function. */
+  on(edge: OverlayEdge, listener: OverlayListener): () => void;
+  /**
+   * One-line adoption for games: pause on open (unless `canPause` is false),
+   * optionally resume on close. Returns a function that detaches it.
+   */
+  autoPause(options: AutoPauseOptions): () => void;
+  /** Driven by `hub.mp.setBusy`: false while a live match can't pause. */
+  setCanPause(canPause: boolean): void;
+  /** Hand listeners to a newer version replacing this (idle) instance. */
+  handoff(): UiStackHandoff;
+}

package/src/uistack/ui-stack.ts

@@ -1,144 +1,144 @@
-/**
- * The overlay stack implementation: two edges (`open` when depth goes
- * 0 → 1, `close` when it returns to 0) mirrored as window events, the
- * `autoPause` helper, and the `play` suspension.
- */
-import { LEGACY_GLOBAL_NAMES } from '../globals';
-import { isGroupSwitch, PlaySuspension } from './play-suspension';
-import type { AutoPauseOptions, OverlayEdge, OverlayEvent, OverlayListener, OverlayReason, UiStack, UiStackHandoff } from './types';
-
-/** Bump when the UiStack contract gains behaviour; idle older instances are replaced. */
-export const UI_STACK_VERSION = 1;
-
-/** One open entry (its identity is what `pop` removes). */
-interface StackEntry {
-  readonly reason: OverlayReason;
-}
-
-/** The page-wide overlay stack (see {@link UiStack}). */
-export class UiStackImpl implements UiStack {
-  readonly version = UI_STACK_VERSION;
-  private readonly entries: StackEntry[] = [];
-  private readonly listeners: Record<OverlayEdge, Set<OverlayListener>> = { open: new Set(), close: new Set() };
-  private isPausable = true;
-  private suspension: PlaySuspension | null = null;
-
-  constructor(handoff?: UiStackHandoff) {
-    if (handoff === undefined) {
-      return;
-    }
-    handoff.listeners.open.forEach((listener) => this.listeners.open.add(listener));
-    handoff.listeners.close.forEach((listener) => this.listeners.close.add(listener));
-    this.isPausable = handoff.canPause;
-  }
-
-  get isOpen(): boolean {
-    return this.entries.length > 0;
-  }
-
-  get depth(): number {
-    return this.entries.length;
-  }
-
-  get canPause(): boolean {
-    return this.isPausable;
-  }
-
-  push(reason: OverlayReason): () => void {
-    const entry: StackEntry = { reason };
-    this.entries.push(entry);
-    if (this.entries.length === 1) {
-      this.suspendPlay();
-      this.emit('open', { reason, canPause: this.isPausable });
-    }
-    let wasPopped = false;
-    return () => {
-      if (wasPopped) {
-        return;
-      }
-      wasPopped = true;
-      const index = this.entries.indexOf(entry);
-      if (index < 0) {
-        return;
-      }
-      this.entries.splice(index, 1);
-      if (this.entries.length === 0) {
-        // Listeners run before `play` is restored, so a game that pauses in its close handler is honoured.
-        this.emit('close', { reason, canPause: this.isPausable });
-        this.suspension?.release();
-        this.suspension = null;
-      }
-    };
-  }
-
-  on(edge: OverlayEdge, listener: OverlayListener): () => void {
-    this.listeners[edge].add(listener);
-    return () => {
-      this.listeners[edge].delete(listener);
-    };
-  }
-
-  autoPause(options: AutoPauseOptions): () => void {
-    let wasPausedByUs = false;
-    const pauseOnOpen = (event: OverlayEvent): void => {
-      if (!event.canPause) {
-        return;
-      }
-      wasPausedByUs = true;
-      options.pause();
-    };
-    const resumeOnClose = (): void => {
-      if (wasPausedByUs && options.resumeOnClose === true) {
-        options.resume?.();
-      }
-      wasPausedByUs = false;
-    };
-    const stopOpen = this.on('open', pauseOnOpen);
-    const stopClose = this.on('close', resumeOnClose);
-    // Registered while hub UI is already up: pause now, as if it just opened.
-    const firstEntry = this.entries[0];
-    if (firstEntry !== undefined) {
-      pauseOnOpen({ reason: firstEntry.reason, canPause: this.isPausable });
-    }
-    return () => {
-      stopOpen();
-      stopClose();
-    };
-  }
-
-  setCanPause(canPause: boolean): void {
-    this.isPausable = canPause;
-  }
-
-  handoff(): UiStackHandoff {
-    const handoff: UiStackHandoff = {
-      listeners: { open: [...this.listeners.open], close: [...this.listeners.close] },
-      canPause: this.isPausable,
-    };
-    this.listeners.open.clear();
-    this.listeners.close.clear();
-    return handoff;
-  }
-
-  private suspendPlay(): void {
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: the page input system may be another bundle's
-    const input: unknown = typeof window === 'undefined' ? undefined : window[LEGACY_GLOBAL_NAMES.input];
-    if (this.suspension === null && isGroupSwitch(input)) {
-      this.suspension = new PlaySuspension(input);
-    }
-  }
-
-  private emit(edge: OverlayEdge, event: OverlayEvent): void {
-    for (const listener of [...this.listeners[edge]]) {
-      try {
-        listener(event);
-      } catch (error) {
-        // eslint-disable-next-line no-console -- a game's listener failing must not break the hub UI; surface it
-        console.error('[hub] overlay listener failed', error);
-      }
-    }
-    if (typeof window !== 'undefined') {
-      window.dispatchEvent(new CustomEvent(`hub:overlay-${edge}`, { detail: event }));
-    }
-  }
-}
+/**
+ * The overlay stack implementation: two edges (`open` when depth goes
+ * 0 → 1, `close` when it returns to 0) mirrored as window events, the
+ * `autoPause` helper, and the `play` suspension.
+ */
+import { LEGACY_GLOBAL_NAMES } from '../globals';
+import { isGroupSwitch, PlaySuspension } from './play-suspension';
+import type { AutoPauseOptions, OverlayEdge, OverlayEvent, OverlayListener, OverlayReason, UiStack, UiStackHandoff } from './types';
+
+/** Bump when the UiStack contract gains behaviour; idle older instances are replaced. */
+export const UI_STACK_VERSION = 1;
+
+/** One open entry (its identity is what `pop` removes). */
+interface StackEntry {
+  readonly reason: OverlayReason;
+}
+
+/** The page-wide overlay stack (see {@link UiStack}). */
+export class UiStackImpl implements UiStack {
+  readonly version = UI_STACK_VERSION;
+  private readonly entries: StackEntry[] = [];
+  private readonly listeners: Record<OverlayEdge, Set<OverlayListener>> = { open: new Set(), close: new Set() };
+  private isPausable = true;
+  private suspension: PlaySuspension | null = null;
+
+  constructor(handoff?: UiStackHandoff) {
+    if (handoff === undefined) {
+      return;
+    }
+    handoff.listeners.open.forEach((listener) => this.listeners.open.add(listener));
+    handoff.listeners.close.forEach((listener) => this.listeners.close.add(listener));
+    this.isPausable = handoff.canPause;
+  }
+
+  get isOpen(): boolean {
+    return this.entries.length > 0;
+  }
+
+  get depth(): number {
+    return this.entries.length;
+  }
+
+  get canPause(): boolean {
+    return this.isPausable;
+  }
+
+  push(reason: OverlayReason): () => void {
+    const entry: StackEntry = { reason };
+    this.entries.push(entry);
+    if (this.entries.length === 1) {
+      this.suspendPlay();
+      this.emit('open', { reason, canPause: this.isPausable });
+    }
+    let wasPopped = false;
+    return () => {
+      if (wasPopped) {
+        return;
+      }
+      wasPopped = true;
+      const index = this.entries.indexOf(entry);
+      if (index < 0) {
+        return;
+      }
+      this.entries.splice(index, 1);
+      if (this.entries.length === 0) {
+        // Listeners run before `play` is restored, so a game that pauses in its close handler is honoured.
+        this.emit('close', { reason, canPause: this.isPausable });
+        this.suspension?.release();
+        this.suspension = null;
+      }
+    };
+  }
+
+  on(edge: OverlayEdge, listener: OverlayListener): () => void {
+    this.listeners[edge].add(listener);
+    return () => {
+      this.listeners[edge].delete(listener);
+    };
+  }
+
+  autoPause(options: AutoPauseOptions): () => void {
+    let wasPausedByUs = false;
+    const pauseOnOpen = (event: OverlayEvent): void => {
+      if (!event.canPause) {
+        return;
+      }
+      wasPausedByUs = true;
+      options.pause();
+    };
+    const resumeOnClose = (): void => {
+      if (wasPausedByUs && options.resumeOnClose === true) {
+        options.resume?.();
+      }
+      wasPausedByUs = false;
+    };
+    const stopOpen = this.on('open', pauseOnOpen);
+    const stopClose = this.on('close', resumeOnClose);
+    // Registered while hub UI is already up: pause now, as if it just opened.
+    const firstEntry = this.entries[0];
+    if (firstEntry !== undefined) {
+      pauseOnOpen({ reason: firstEntry.reason, canPause: this.isPausable });
+    }
+    return () => {
+      stopOpen();
+      stopClose();
+    };
+  }
+
+  setCanPause(canPause: boolean): void {
+    this.isPausable = canPause;
+  }
+
+  handoff(): UiStackHandoff {
+    const handoff: UiStackHandoff = {
+      listeners: { open: [...this.listeners.open], close: [...this.listeners.close] },
+      canPause: this.isPausable,
+    };
+    this.listeners.open.clear();
+    this.listeners.close.clear();
+    return handoff;
+  }
+
+  private suspendPlay(): void {
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: the page input system may be another bundle's
+    const input: unknown = typeof window === 'undefined' ? undefined : window[LEGACY_GLOBAL_NAMES.input];
+    if (this.suspension === null && isGroupSwitch(input)) {
+      this.suspension = new PlaySuspension(input);
+    }
+  }
+
+  private emit(edge: OverlayEdge, event: OverlayEvent): void {
+    for (const listener of [...this.listeners[edge]]) {
+      try {
+        listener(event);
+      } catch (error) {
+        // eslint-disable-next-line no-console -- a game's listener failing must not break the hub UI; surface it
+        console.error('[hub] overlay listener failed', error);
+      }
+    }
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent(`hub:overlay-${edge}`, { detail: event }));
+    }
+  }
+}