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

package/src/turns-kit/check-rules.ts

@@ -0,0 +1,281 @@
+/**
+ * The rules conformance kit (docs/multiplayer.md "Turn games: testing"):
+ * `checkTurnRules(rules, options)` plays many seeded games through a rules
+ * module the way the hub does and throws on the first broken promise:
+ *
+ * - every game reaches an outcome within `maxMoves`, and `toAct` is never
+ *   empty before it; every seat in `toAct` gets to move (not only the
+ *   first), and so do the seats in `mayAct` (out of turn: a jump-in, a
+ *   catch) whose `autoReact` (or `options.reactMove`) has a move;
+ * - `toAct` and `mayAct` only name seats that exist;
+ * - the state survives a JSON round trip after every move, and the same seed
+ *   plays the same game (no `Math.random`, no hidden globals);
+ * - `autoMove` and `autoReact` (when the rules have them) are always legal;
+ * - no seat's `view` or `eventView` shows another seat's secrets: markers
+ *   planted with `options.plant` never appear in anyone else's view until
+ *   the rules reveal them (`options.revealed`: a card played face up);
+ * - with `options.shuffleHidden` (the "twin table"): shuffling everything a
+ *   seat may not see never changes that seat's view;
+ * - stored fixtures from older versions `migrate` to a state that views;
+ * - views, events and moves stay within the hub's size caps.
+ *
+ * It needs no hub: run it in a game's own unit tests (vitest, node:test).
+ */
+import { createTurnRng, turnRngStateFromSeed, type TurnRng, type TurnRules } from '@diffenderfer-games/hub-contract/turns-rules';
+import { parseJsonText } from '../core/storage/json-guards';
+
+/** The hub's caps. */
+const STATE_MAX_BYTES = 64 * 1024;
+const MOVE_MAX_BYTES = 2 * 1024;
+
+/** How to check a rules module. */
+export interface TurnRulesCheckOptions<State, Move, Options = never> {
+  /** Seat counts to play (default: 2). */
+  readonly seats?: readonly number[];
+  /** Games per seat count (default: 25). */
+  readonly games?: number;
+  /** A game that runs longer than this many moves fails (default: 2000). */
+  readonly maxMoves?: number;
+  /** Options and mode to set games up with. */
+  readonly setupOptions?: Options;
+  readonly mode?: string | null;
+  /** A legal move for `seat` (default: the rules' own `autoMove`). At least one of the two is needed. */
+  readonly randomMove?: (state: State, seat: number, rng: TurnRng) => Move;
+  /** A legal out-of-turn move for `seat` while it is in `mayAct`, or `null` to pass (default: the rules' own `autoReact`). */
+  readonly reactMove?: (state: State, seat: number, rng: TurnRng) => Move | null;
+  /**
+   * Put `marker` somewhere only `seat` may see (a card in their hand, their
+   * secret goal) and return the state; the kit then checks no other seat's
+   * view or events ever contain it. Leave it out for a game with no hidden
+   * information.
+   */
+  readonly plant?: (state: State, seat: number, marker: string) => State;
+  /**
+   * Whether a planted `marker` is now public by the rules (the card was
+   * played or discarded face up, a secret was shown at the end): from then
+   * on the kit stops checking it in that game, so a card that is rightly
+   * revealed isn't a leak. Leave it out when planted markers never become
+   * public.
+   */
+  readonly revealed?: (state: State, marker: string) => boolean;
+  /**
+   * The "twin table": a copy of `state` with everything `seat` may not see
+   * shuffled or redealt (the deck's order, the other hands' cards, keeping
+   * their counts), drawing from `rng`. After every move the kit checks
+   * that each seat's `view` of the twin is exactly its view of the real
+   * state: a view that changes depends on something that seat must not
+   * know. Catches leaks `plant` can't (a count, an order, a derived hint).
+   */
+  readonly shuffleHidden?: (state: State, seat: number, rng: TurnRng) => State;
+  /** States saved by older rules versions, which `migrate` must bring up to date. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: states stored by older rules versions
+  readonly fixtures?: readonly { readonly version: number; readonly state: unknown }[];
+}
+
+/** What the kit played. */
+export interface TurnRulesReport {
+  readonly games: number;
+  readonly moves: number;
+  readonly longestGame: number;
+  /** Moves made out of turn (by a seat in `mayAct`, not `toAct`). */
+  readonly outOfTurn: number;
+}
+
+/** The UTF-8 bytes of a JSON text. */
+function bytesOf(json: string): number {
+  return new TextEncoder().encode(json).length;
+}
+
+/** Throw a kit failure. */
+function fail(message: string): never {
+  throw new Error(`checkTurnRules: ${message}`);
+}
+
+/** A JSON copy (what the hub stores and reads back). */
+function roundTrip<T>(value: T): T {
+  const copy = parseJsonText(JSON.stringify(value));
+  if (copy === null && value !== null) {
+    fail('a state or move is not JSON');
+  }
+  return isGamesOwn(copy, value) ? copy : fail('a state or move is not JSON');
+}
+
+/** Always true: JSON a game's rules made is read back as the game's own type (the game vouches for it, as `toGameData` does). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the game's own JSON, round-tripped
+function isGamesOwn<T>(_value: unknown, _like: T): _value is T {
+  return true;
+}
+
+/** A move for `seat`: the check's own chooser, else the rules' autoMove. */
+function pickMove<State, Move, View, Event, Options>(rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options>, state: State, seat: number, rng: TurnRng): Move {
+  if (options.randomMove !== undefined) {
+    return options.randomMove(state, seat, rng);
+  }
+  if (rules.autoMove === undefined) {
+    return fail('the rules have no autoMove: pass options.randomMove');
+  }
+  return rules.autoMove(state, seat, rng);
+}
+
+/** An out-of-turn move for `seat`: the check's own chooser, else the rules' autoReact, else none. */
+function pickReaction<State, Move, View, Event, Options>(rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options>, state: State, seat: number, rng: TurnRng): Move | null {
+  if (options.reactMove !== undefined) {
+    return options.reactMove(state, seat, rng);
+  }
+  return rules.autoReact?.(state, seat, rng) ?? null;
+}
+
+/** Fail unless every seat in `list` exists. */
+function checkSeats(list: readonly number[], seats: number, what: string, seed: number): void {
+  if (list.some((seat) => !Number.isInteger(seat) || seat < 0 || seat >= seats)) {
+    fail(`${what} named a seat that doesn't exist: [${list.join(', ')}] (seed ${String(seed)})`);
+  }
+}
+
+/**
+ * The next move of a game: half the time a seat in `mayAct` that has an
+ * out-of-turn move, else a seat in `toAct` (any of them, not only the
+ * first). The kit's own `pick` RNG chooses, so the game's RNG sees only
+ * the rules' own draws.
+ */
+function nextMove<State, Move, View, Event, Options>(
+  rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options>, state: State, toAct: readonly number[], rng: TurnRng, pick: TurnRng,
+): { seat: number; move: Move; by: string } | null {
+  const optional = (rules.mayAct?.(state) ?? []).filter((seat) => !toAct.includes(seat));
+  if (optional.length > 0 && pick.int(2) === 0) {
+    const seat = pick.pick(optional);
+    const move = pickReaction(rules, options, state, seat, rng);
+    if (move !== null) {
+      return { seat, move, by: options.reactMove === undefined ? 'autoReact' : 'reactMove' };
+    }
+  }
+  const seat = toAct.length === 0 ? undefined : pick.pick(toAct);
+  return seat === undefined ? null : { seat, move: pickMove(rules, options, state, seat, rng), by: options.randomMove === undefined ? 'autoMove' : 'randomMove' };
+}
+
+/** Play one seeded game; answers its moves and a trace for the determinism check. */
+function playGame<State, Move, View, Event, Options>(
+  rules: TurnRules<State, Move, View, Event, Options>, seats: number, seed: number, options: TurnRulesCheckOptions<State, Move, Options>,
+): { moves: number; outOfTurn: number; trace: string } {
+  const rng = createTurnRng(turnRngStateFromSeed(seed));
+  const pick = createTurnRng(turnRngStateFromSeed(seed ^ 0x5bd1e995));
+  const twinRng = createTurnRng(turnRngStateFromSeed(seed ^ 0x27d4eb2f));
+  const marker = `MARKER-${String(seed)}-`;
+  const markerOf = (owner: number): string => `${marker}${String(owner)}`;
+  let state = rules.setup({ seats, options: options.setupOptions ?? null, mode: options.mode ?? null, rng });
+  if (options.plant !== undefined) {
+    for (let seat = 0; seat < seats; seat++) {
+      state = options.plant(state, seat, markerOf(seat));
+    }
+  }
+  const maxMoves = options.maxMoves ?? 2000;
+  const trace: string[] = [];
+  let outOfTurn = 0;
+  /** The twin table: each seat's view is the same after what it can't see is shuffled. */
+  const checkTwin = (): void => {
+    if (options.shuffleHidden === undefined) {
+      return;
+    }
+    for (let viewer = 0; viewer < seats; viewer++) {
+      const real = JSON.stringify(rules.view(state, viewer));
+      const twin = JSON.stringify(rules.view(roundTrip(options.shuffleHidden(roundTrip(state), viewer, twinRng)), viewer));
+      if (twin !== real) {
+        fail(`seat ${String(viewer)}'s view changed when what it can't see was shuffled: it shows something hidden (seed ${String(seed)})`);
+      }
+    }
+  };
+  /** The seats whose planted marker is still secret (the rules haven't revealed it). */
+  const secret = new Set(options.plant === undefined ? [] : Array.from({ length: seats }, (_, seat) => seat));
+  const checkViews = (events: readonly Event[]): void => {
+    for (const owner of secret) {
+      if (options.revealed?.(state, markerOf(owner)) === true) {
+        secret.delete(owner);
+      }
+    }
+    for (let viewer = 0; viewer < seats; viewer++) {
+      const seen = JSON.stringify(rules.view(state, viewer)) + JSON.stringify(events.map((event) => rules.eventView?.(event, viewer) ?? null));
+      for (const owner of secret) {
+        if (owner !== viewer && seen.includes(markerOf(owner))) {
+          fail(`seat ${String(viewer)} can see seat ${String(owner)}'s secret (seed ${String(seed)})`);
+        }
+      }
+    }
+    const shown = JSON.stringify(rules.view(state, null));
+    for (const owner of secret) {
+      if (shown.includes(markerOf(owner))) {
+        fail(`the public view shows seat ${String(owner)}'s secret (seed ${String(seed)})`);
+      }
+    }
+    checkTwin();
+  };
+  checkViews([]);
+  for (let moves = 0; moves < maxMoves; moves++) {
+    if (rules.outcome(state) !== null) {
+      return { moves, outOfTurn, trace: trace.join('|') };
+    }
+    const toAct = rules.toAct(state);
+    checkSeats(toAct, seats, 'toAct', seed);
+    checkSeats(rules.mayAct?.(state) ?? [], seats, 'mayAct', seed);
+    if (toAct.length === 0) {
+      fail(`toAct is empty but there is no outcome yet (seed ${String(seed)}, move ${String(moves)})`);
+    }
+    const next = nextMove(rules, options, state, toAct, rng, pick);
+    if (next === null) {
+      return fail(`no seat could move (seed ${String(seed)}, move ${String(moves)})`);
+    }
+    const { seat, move } = next;
+    outOfTurn += toAct.includes(seat) ? 0 : 1;
+    if (bytesOf(JSON.stringify(move)) > MOVE_MAX_BYTES) {
+      fail(`a move is over ${String(MOVE_MAX_BYTES)} bytes`);
+    }
+    const result = rules.apply(roundTrip(state), seat, roundTrip(move), rng);
+    if ('error' in result) {
+      fail(`${next.by} made an illegal move for seat ${String(seat)}: ${result.error} (seed ${String(seed)}, move ${String(moves)})`);
+    }
+    state = roundTrip(result.state);
+    if (bytesOf(JSON.stringify(state)) > STATE_MAX_BYTES) {
+      fail(`the state is over ${String(STATE_MAX_BYTES)} bytes`);
+    }
+    checkViews(result.events ?? []);
+    rules.progress(state, seat);
+    trace.push(`${String(seat)}:${JSON.stringify(move)}`);
+  }
+  return fail(`a game did not end within ${String(maxMoves)} moves (seed ${String(seed)})`);
+}
+
+/** Check a rules module (see the file comment); throws on the first failure. */
+export function checkTurnRules<State, Move, View, Event, Options>(
+  rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options> = {},
+): TurnRulesReport {
+  if (!Number.isInteger(rules.version) || rules.version < 0) {
+    fail('rules.version must be a whole number');
+  }
+  let games = 0;
+  let moves = 0;
+  let longestGame = 0;
+  let outOfTurn = 0;
+  for (const seats of options.seats ?? [2]) {
+    for (let game = 0; game < (options.games ?? 25); game++) {
+      const seed = seats * 100_003 + game;
+      const played = playGame(rules, seats, seed, options);
+      if (playGame(rules, seats, seed, options).trace !== played.trace) {
+        fail(`the same seed played a different game (seed ${String(seed)}): use the rng you are given, never Math.random`);
+      }
+      games += 1;
+      moves += played.moves;
+      longestGame = Math.max(longestGame, played.moves);
+      outOfTurn += played.outOfTurn;
+    }
+  }
+  for (const fixture of options.fixtures ?? []) {
+    if (fixture.version < rules.version) {
+      if (rules.migrate === undefined) {
+        fail(`a version ${String(fixture.version)} fixture needs rules.migrate`);
+      }
+      const migrated = rules.migrate(roundTrip(fixture.state), fixture.version);
+      rules.view(migrated, null);
+      rules.toAct(migrated);
+    }
+  }
+  return { games, moves, longestGame, outOfTurn };
+}

package/src/turns-rules.ts

@@ -0,0 +1,12 @@
+/**
+ * `@diffenderfer-games/hub/turns-rules`: what an online turn game's rules
+ * module imports (docs/multiplayer.md §16): `defineTurnRules` to type the
+ * rules object, the rules contract's types, and the seeded RNG the hub
+ * hands the rules. Nothing else comes with it (no zod, no client), so a
+ * rules bundle that imports it stays a few KB. The conformance kit for
+ * tests is `@diffenderfer-games/hub/turns`.
+ *
+ * @packageDocumentation
+ */
+export { createTurnRng, defineTurnRules, turnRngStateFromSeed } from '@diffenderfer-games/hub-contract/turns-rules';
+export type { TurnApplyResult, TurnOutcome, TurnProgress, TurnRng, TurnRngState, TurnRules, TurnSetupContext } from '@diffenderfer-games/hub-contract/turns-rules';

package/src/turns.ts

@@ -0,0 +1,14 @@
+/**
+ * `@diffenderfer-games/hub/turns`: writing and testing an online turn
+ * game's rules module (docs/multiplayer.md "Turn games"). The types of the
+ * rules contract, `defineTurnRules` to type a rules object, the seeded RNG
+ * the hub hands the rules (to replay a game in tests), and the conformance
+ * kit, `checkTurnRules`, for the game's own CI. The page-side API is
+ * `hub.turns` on the main entry. A rules module itself imports
+ * `@diffenderfer-games/hub/turns-rules` (the same `defineTurnRules` and
+ * types, nothing else), so its bundle stays a few KB.
+ *
+ * @packageDocumentation
+ */
+export * from './turns-rules';
+export { checkTurnRules, type TurnRulesCheckOptions, type TurnRulesReport } from './turns-kit/check-rules';

package/src/types.ts

@@ -1,13 +1,13 @@
-/**
- * `@diffenderfer-games/hub/types`: a type-only re-export of every contract
- * type a game may use (request and reply shapes, entities, error bodies and
- * codes, socket ops and events, the `game.*` manifest), so a game can name a
- * hub type without depending on the contract package itself. Importing it
- * adds nothing to a bundle.
- *
- * The client's own types (`User`, `Save<T>`, `HubStatus`, ...) come from the
- * main entry.
- *
- * @packageDocumentation
- */
-export type * from '@diffenderfer-games/hub-contract';
+/**
+ * `@diffenderfer-games/hub/types`: a type-only re-export of every contract
+ * type a game may use (request and reply shapes, entities, error bodies and
+ * codes, socket ops and events, the `game.*` manifest), so a game can name a
+ * hub type without depending on the contract package itself. Importing it
+ * adds nothing to a bundle.
+ *
+ * The client's own types (`User`, `Save<T>`, `HubStatus`, ...) come from the
+ * main entry.
+ *
+ * @packageDocumentation
+ */
+export type * from '@diffenderfer-games/hub-contract';

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