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

package/src/uistack/page-stack.ts

@@ -1,45 +1,45 @@
-/**
- * The overlay stack is one per page, on `window.__HUB_UI__`, because several
- * bundles share it: the host's `/_hub/hub.js`, a game's bundled client and
- * the social runtime. It has its own handover rule (older than plan §4.4's
- * registry, and kept for v1 copies): a newer implementation replaces an older
- * one only while it is idle, adopting its listeners, so open entries are
- * never orphaned.
- */
-import { hasMethods, readField } from '../realtime/cross-bundle';
-import type { UiStack } from './types';
-import { UI_STACK_VERSION, UiStackImpl } from './ui-stack';
-
-declare global {
-  interface Window {
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
-    __HUB_UI__?: unknown;
-  }
-}
-
-/** Whether `candidate` is some bundle's overlay stack. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the stack may come from another bundle
-export function isUiStack(candidate: unknown): candidate is UiStack {
-  return typeof readField(candidate, 'version') === 'number' && hasMethods(candidate, ['push', 'on']);
-}
-
-let pagelessStack: UiStack | null = null;
-
-/**
- * The page-wide overlay stack, created on first use. Outside a browser a
- * module-local instance is returned.
- */
-export function getUiStack(): UiStack {
-  if (typeof window === 'undefined') {
-    pagelessStack ??= new UiStackImpl();
-    return pagelessStack;
-  }
-  const existing = window.__HUB_UI__;
-  if (isUiStack(existing) && (existing.version >= UI_STACK_VERSION || existing.isOpen)) {
-    return existing;
-  }
-  const handoff = isUiStack(existing) && hasMethods(existing, ['handoff']) ? existing.handoff() : undefined;
-  const stack = new UiStackImpl(handoff);
-  window.__HUB_UI__ = stack;
-  return stack;
-}
+/**
+ * The overlay stack is one per page, on `window.__HUB_UI__`, because several
+ * bundles share it: the host's `/_hub/hub.js`, a game's bundled client and
+ * the social runtime. It has its own handover rule (older than plan §4.4's
+ * registry, and kept for v1 copies): a newer implementation replaces an older
+ * one only while it is idle, adopting its listeners, so open entries are
+ * never orphaned.
+ */
+import { hasMethods, readField } from '../realtime/cross-bundle';
+import type { UiStack } from './types';
+import { UI_STACK_VERSION, UiStackImpl } from './ui-stack';
+
+declare global {
+  interface Window {
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_UI__?: unknown;
+  }
+}
+
+/** Whether `candidate` is some bundle's overlay stack. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the stack may come from another bundle
+export function isUiStack(candidate: unknown): candidate is UiStack {
+  return typeof readField(candidate, 'version') === 'number' && hasMethods(candidate, ['push', 'on']);
+}
+
+let pagelessStack: UiStack | null = null;
+
+/**
+ * The page-wide overlay stack, created on first use. Outside a browser a
+ * module-local instance is returned.
+ */
+export function getUiStack(): UiStack {
+  if (typeof window === 'undefined') {
+    pagelessStack ??= new UiStackImpl();
+    return pagelessStack;
+  }
+  const existing = window.__HUB_UI__;
+  if (isUiStack(existing) && (existing.version >= UI_STACK_VERSION || existing.isOpen)) {
+    return existing;
+  }
+  const handoff = isUiStack(existing) && hasMethods(existing, ['handoff']) ? existing.handoff() : undefined;
+  const stack = new UiStackImpl(handoff);
+  window.__HUB_UI__ = stack;
+  return stack;
+}

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;
+}