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

package/src/input/input-system.ts

@@ -1,393 +1,406 @@
-/**
- * The generic input system (`hub.input`): desktop, touch and gamepad. A game
- * declares named inputs that each read as 0..1, grouped so they can be
- * enabled together, and reads them every frame. The system handles edges,
- * axes and vectors, device arbitration (last used wins; the keyboard is
- * always on), on-screen controls, navigable UI, an on-screen keyboard,
- * player remapping, and a zero-config fallback for games that never define
- * inputs.
- */
-import type { ControlsPanelHost } from '../overlay/controls-panel';
-import { DeviceState } from './device-state';
-import { RepeatingEdges, RisingEdges } from './edges';
-import { isAnyPadButtonPressed, PAD_BUTTON } from './gamepad';
-import { InputEventHub } from './input-events';
-import { InputRegistry } from './input-registry';
-import { parseLegacyControls } from './legacy-controls';
-import type { LegacyControls } from './legacy-controls';
-import { Navigator } from './navigator';
-import type { NavigatorContext } from './navigator';
-import { feedDeviceState, OnScreenControls } from './on-screen-controls';
-import type { PageInputControl } from './page-control';
-import { describeBinding, PlayerRemaps } from './player-remaps';
-import type {
-  InputConfig, InputDef, InputEvents, InputHost, InputReading, InputSource, MenuBridge, NavTarget, Vector, VirtualOverride,
-} from './types';
-import { runZeroConfigFrame } from './zero-config';
-
-/** Options for the input system. */
-export interface InputSystemOptions {
-  /** Start as the page's input owner (default true). A private instance takes over when its game defines inputs. */
-  isPageOwner?: boolean;
-  /** Make this instance the page's registered input system (when a private instance takes over); returns the one replaced. */
-  claimPage?: (system: InputSystem) => PageInputControl | null;
-}
-
-/** The window flag that tells every copy's zero-config fallback to stand down. */
-const INPUT_ACTIVE_FLAG = '__HUB_INPUT_ACTIVE__';
-
-/** The page's input system. */
-export class InputSystem implements ControlsPanelHost, PageInputControl {
-  private readonly host: InputHost;
-  private readonly options: InputSystemOptions;
-  private config: InputConfig | null = null;
-  private readonly remaps: PlayerRemaps;
-  private readonly registry = new InputRegistry();
-  private readonly devices = new DeviceState();
-  private readonly controls = new OnScreenControls(() => this.registry.enabledGroupNames());
-  private readonly navigator = new Navigator();
-  private readonly repeats = new RepeatingEdges();
-  private readonly presses = new RisingEdges();
-  private readonly events = new InputEventHub();
-  private menu: MenuBridge | null = null;
-  private legacyControls: LegacyControls = parseLegacyControls(null);
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page as given, kept for a handover
-  private legacyControlsSource: unknown = null;
-  private activeSource: InputSource = 'keyboard';
-  private isPageOwner: boolean;
-  private pageOwner: PageInputControl | null = null;
-
-  constructor(host: InputHost, options: InputSystemOptions = {}) {
-    this.host = host;
-    this.options = options;
-    this.isPageOwner = options.isPageOwner ?? true;
-    this.remaps = new PlayerRemaps(host);
-    this.controls.playerChoice = this.remaps.overrides.showVirtual ?? null;
-    this.devices.listen({
-      onMouseActivity: () => {
-        this.setSource('mouse');
-      },
-      onGamepadConnection: (isConnected) => {
-        this.controls.isGamepadConnected ||= isConnected;
-        this.controls.sync();
-      },
-      shouldCancelScrollKeys: () => this.config !== null,
-    });
-    if (typeof requestAnimationFrame === 'function') {
-      requestAnimationFrame(() => {
-        this.tick();
-      });
-    }
-  }
-
-  /** Whether this page counts as a touch device. */
-  get touchDevice(): boolean {
-    return this.controls.isTouchDevice;
-  }
-
-  /** Declare the game's inputs (replacing any earlier declaration). The game owns input from now on. */
-  define(config: InputConfig): void {
-    if (!this.isPageOwner) {
-      const previous = this.options.claimPage?.(this) ?? null;
-      this.isPageOwner = true;
-      previous?.yieldPageTo?.(this);
-    }
-    this.config = config;
-    this.registry.declare(config, (name, declared) => this.remaps.withBinding(name, declared));
-    this.navigator.clearGroups();
-    for (const [group, groupDefinition] of Object.entries(config.groups)) {
-      if (groupDefinition.navigable !== undefined) {
-        this.navigator.addGroup(group, groupDefinition.navigable);
-      }
-    }
-    this.buildControls();
-    Reflect.set(window, INPUT_ACTIVE_FLAG, true);
-  }
-
-  /** True once the game has declared its inputs. */
-  get isDefined(): boolean {
-    return this.pageOwner?.isDefined ?? this.config !== null;
-  }
-
-  /** Turn a group on. Held keys don't fire a phantom `down` (the pause key held as play resumes). */
-  enable(group: string): void {
-    this.registry.setGroupEnabled(group, true, this.devices, this.activeSource);
-    this.controls.sync();
-    this.navigator.refreshGroup(group, this.navigatorContext());
-  }
-
-  /** Turn a group off (its inputs read 0). */
-  disable(group: string): void {
-    this.registry.setGroupEnabled(group, false, this.devices, this.activeSource);
-    this.controls.sync();
-    this.navigator.blurGroup(group, this.controls.existingOverlay);
-  }
-
-  /** Whether a group is on. */
-  isEnabled(group: string): boolean {
-    return this.registry.isEnabled(group);
-  }
-
-  /** An input's value, 0..1. */
-  value(name: string): number {
-    return this.registry.value(name);
-  }
-
-  /** An input's full reading this frame. */
-  get(name: string): InputReading {
-    return this.registry.reading(name);
-  }
-
-  /** Whether an input went down this frame. */
-  down(name: string): boolean {
-    return this.registry.wentDown(name);
-  }
-
-  /** Whether an input came up this frame. */
-  up(name: string): boolean {
-    return this.registry.wentUp(name);
-  }
-
-  /** Whether an input is held (≥ 0.5). */
-  pressed(name: string): boolean {
-    return this.registry.isPressed(name);
-  }
-
-  /** A named axis, or an ad-hoc `axis(negative, positive)` pair, as -1..1. */
-  axis(name: string, positive?: string): number {
-    return this.registry.axis(name, positive);
-  }
-
-  /** A named axis pair as a vector clamped to the unit circle. */
-  vector(name: string): Vector {
-    return this.registry.vector(name);
-  }
-
-  /** The device the player is using right now. */
-  get source(): InputSource {
-    return this.activeSource;
-  }
-
-  /** Subscribe to an input event. Returns the unsubscribe function. */
-  on<Name extends keyof InputEvents>(event: Name, listener: (payload: InputEvents[Name]) => void): () => void {
-    return this.events.on(event, listener);
-  }
-
-  /** Update a button's content at runtime (e.g. an SVG reflecting game state). */
-  setVirtualHtml(id: string, html: string): void {
-    this.controls.existingOverlay?.setControlHtml(id, html);
-  }
-
-  /** The player's show/hide choice for the on-screen controls (persisted). */
-  showVirtual(isVisible: boolean): void {
-    this.controls.playerChoice = isVisible;
-    this.remaps.setShowVirtual(isVisible);
-    this.controls.sync();
-  }
-
-  /** Flip the player's show/hide choice. */
-  toggleVirtual(): void {
-    this.showVirtual(!this.showingVirtual);
-  }
-
-  /** Force the controls visible for layout editing, without changing the player's choice. */
-  setVirtualEditing(isEditing: boolean): void {
-    this.controls.setEditing(isEditing);
-  }
-
-  /** This game's default visibility (the player's choice still wins); `null` = shown on touch devices without a pad. */
-  setVirtualDefault(isVisible: boolean | null): void {
-    this.controls.setGameDefault(isVisible);
-  }
-
-  /**
-   * Keep auto-placed controls clear of a band along a screen edge, e.g. your
-   * top HUD: `setInsets({ top: hud.getBoundingClientRect().bottom })`. Px from
-   * each edge, merged with earlier calls (0 clears one edge). Dragged controls
-   * and explicit `pos` ignore it.
-   */
-  setInsets(insets: { top?: number; right?: number; bottom?: number; left?: number }): void {
-    this.controls.overlay().setInsets(insets);
-  }
-
-  /** What the "Show on-screen controls" toggle reflects. */
-  get showingVirtual(): boolean {
-    return this.controls.isShowing;
-  }
-
-  /** Rebind an input (persisted). */
-  rebind(inputName: string, patch: Partial<InputDef>): void {
-    this.remaps.rebind(inputName, patch);
-    const declared = this.config?.groups[this.registry.groupOf(inputName) ?? '']?.inputs[inputName];
-    if (declared !== undefined) {
-      this.registry.redefine(inputName, this.remaps.withBinding(inputName, declared));
-    }
-  }
-
-  /** Move or restyle an on-screen control (persisted). */
-  setVirtual(id: string, patch: VirtualOverride): void {
-    this.remaps.customiseControl(id, patch);
-    this.buildControls();
-  }
-
-  /** Open (or close) the Controls screen. */
-  openControls(): void {
-    if (this.pageOwner === null) {
-      this.controls.overlay().toggleControls(this.config, this);
-    } else {
-      this.pageOwner.openControls();
-    }
-  }
-
-  /** Forget every remap and customisation. */
-  resetControls(): void {
-    this.remaps.reset();
-    this.controls.playerChoice = null;
-    if (this.config !== null) {
-      this.define(this.config);
-    }
-  }
-
-  /** A readable label of an input's current binding. */
-  bindingLabel(inputName: string): string {
-    return describeBinding(this.registry.definitionOf(inputName));
-  }
-
-  /** Called by the injected menu: Select toggles it and a gamepad navigates it. */
-  attachMenu(bridge: MenuBridge | null): void {
-    if (this.pageOwner === null) {
-      this.menu = bridge;
-    } else {
-      this.pageOwner.attachMenu(bridge);
-    }
-  }
-
-  /** Called by the injected menu with `game.controls`, for the zero-config fallback. */
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from window.__HUB__, parsed straight away
-  setLegacyControls(controls: unknown): void {
-    if (this.pageOwner === null) {
-      this.legacyControlsSource = controls;
-      this.legacyControls = parseLegacyControls(controls);
-    } else {
-      this.pageOwner.setLegacyControls(controls);
-    }
-  }
-
-  /**
-   * Make a game's own on-screen menu gamepad-navigable: a CSS selector (or a
-   * function returning elements). While any match is visible and a gamepad is
-   * in use, the stick moves a highlight, A clicks, B calls `options.back`.
-   * Re-queried every frame, so call it once.
-   */
-  autoNavigate(selector: string | (() => NavTarget[]), options?: { back?: () => void }): void {
-    this.navigator.setAutoNavigate(Navigator.queryFor(selector), options?.back ?? null);
-  }
-
-  /** Stop navigating the game's own menu. */
-  clearAutoNavigate(): void {
-    this.navigator.clearAutoNavigate(this.controls.existingOverlay);
-  }
-
-  /**
-   * Stop driving the page because another copy's game owns it (plan §4.4):
-   * hand the menu and `game.controls` to `owner`, and forward the menu's calls to it.
-   */
-  yieldPageTo(owner: PageInputControl): void {
-    this.isPageOwner = false;
-    this.pageOwner = owner;
-    owner.attachMenu(this.menu);
-    owner.setLegacyControls(this.legacyControlsSource);
-    this.menu = null;
-  }
-
-  private buildControls(): void {
-    if (this.config === null) {
-      return;
-    }
-    const callbacks = feedDeviceState(this.devices, {
-      onTouch: () => {
-        this.setSource('touch');
-      },
-      onDragged: (id, spot) => {
-        this.setVirtual(id, spot);
-      },
-    });
-    this.controls.build(this.config, this.remaps.overrides, callbacks);
-  }
-
-  private setSource(source: InputSource): void {
-    if (source === this.activeSource) {
-      return;
-    }
-    this.activeSource = source;
-    this.events.emit('sourcechange', source);
-    this.controls.sync();
-  }
-
-  private navigatorContext(): NavigatorContext {
-    return {
-      gamepads: this.devices.gamepads,
-      repeats: this.repeats,
-      presses: this.presses,
-      listeners: {
-        onFocus: (event) => {
-          this.events.emit('focus', event);
-        },
-        onBlur: (event) => {
-          this.events.emit('blur', event);
-        },
-        onAct: (event) => {
-          this.events.emit('act', event);
-        },
-      },
-      highlighter: () => this.controls.overlay(),
-      isPressed: (name) => this.registry.isPressed(name),
-      wentDown: (name) => this.registry.wentDown(name),
-    };
-  }
-
-  private tick(): void {
-    this.devices.frame += 1;
-    const { isConnected, hasActivity } = this.devices.pollGamepads();
-    this.controls.isGamepadConnected = isConnected;
-    if (hasActivity) {
-      this.setSource('gamepad');
-    }
-    if (this.isPageOwner) {
-      this.driveFrame();
-    } else {
-      this.registry.sample(this.devices, this.activeSource);
-    }
-    this.devices.decay();
-    this.controls.existingOverlay?.afterFrame();
-    requestAnimationFrame(() => {
-      this.tick();
-    });
-  }
-
-  /** One frame as the page owner: the menu toggle and navigation, inputs, the zero-config fallback. */
-  private driveFrame(): void {
-    const context = this.navigatorContext();
-    const overlay = this.controls.existingOverlay;
-    const isGamepadActive = this.activeSource === 'gamepad';
-    const menu = this.menu;
-    // Select toggles the hub menu from anywhere.
-    if (menu !== null && this.presses.rose('select', isAnyPadButtonPressed(this.devices.gamepads, PAD_BUTTON.SELECT))) {
-      menu.toggle();
-    }
-    if (menu?.isOpen() === true) {
-      // The menu takes over input: the game's inputs read 0 while it is open.
-      this.registry.silence();
-      this.navigator.driveMenu(menu, isGamepadActive, context, overlay);
-      return;
-    }
-    this.navigator.leaveMenu(overlay);
-    if (this.config !== null) {
-      this.registry.sample(this.devices, this.activeSource);
-      this.navigator.driveGroups((group) => this.registry.isEnabled(group), context);
-    } else if (Reflect.get(window, INPUT_ACTIVE_FLAG) !== true) {
-      runZeroConfigFrame({ gamepads: this.devices.gamepads, slug: this.host.slug, controls: this.legacyControls, navEdges: this.repeats });
-    }
-    this.navigator.driveAutoNavigate(isGamepadActive, context, overlay);
-  }
-}
+/**
+ * The generic input system (`hub.input`): desktop, touch and gamepad. A game
+ * declares named inputs that each read as 0..1, grouped so they can be
+ * enabled together, and reads them every frame. The system handles edges,
+ * axes and vectors, device arbitration (last used wins; the keyboard is
+ * always on), on-screen controls, navigable UI, an on-screen keyboard,
+ * player remapping, and a zero-config fallback for games that never define
+ * inputs.
+ */
+import type { ControlsPanelHost } from '../overlay/controls-panel';
+import { DeviceState } from './device-state';
+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 { AutoNavigateTarget, NavigatorContext } from './navigator';
+import { feedDeviceState, OnScreenControls } from './on-screen-controls';
+import type { PageInputControl } from './page-control';
+import { describeBinding, PlayerRemaps } from './player-remaps';
+import type {
+  InputConfig, InputDef, InputEvents, InputHost, InputReading, InputSource, MenuBridge, NavTarget, Vector, VirtualOverride,
+} from './types';
+import { runZeroConfigFrame } from './zero-config';
+
+/** Options for the input system. */
+export interface InputSystemOptions {
+  /** Start as the page's input owner (default true). A private instance takes over when its game defines inputs. */
+  isPageOwner?: boolean;
+  /** Make this instance the page's registered input system (when a private instance takes over); returns the one replaced. */
+  claimPage?: (system: InputSystem) => PageInputControl | null;
+}
+
+/** The window flag that tells every copy's zero-config fallback to stand down. */
+const INPUT_ACTIVE_FLAG = '__HUB_INPUT_ACTIVE__';
+
+/** The page's input system. */
+export class InputSystem implements ControlsPanelHost, PageInputControl {
+  private readonly host: InputHost;
+  private readonly options: InputSystemOptions;
+  private config: InputConfig | null = null;
+  private readonly remaps: PlayerRemaps;
+  private readonly registry = new InputRegistry();
+  private readonly devices = new DeviceState();
+  private readonly controls = new OnScreenControls(() => this.registry.enabledGroupNames());
+  private readonly navigator = new Navigator();
+  private readonly repeats = new RepeatingEdges();
+  private readonly presses = new RisingEdges();
+  private readonly events = new InputEventHub();
+  private menu: MenuBridge | null = null;
+  private legacyControls: LegacyControls = parseLegacyControls(null);
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page as given, kept for a handover
+  private legacyControlsSource: unknown = null;
+  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;
+    this.options = options;
+    this.isPageOwner = options.isPageOwner ?? true;
+    this.remaps = new PlayerRemaps(host);
+    this.controls.playerChoice = this.remaps.overrides.showVirtual ?? null;
+    this.devices.listen({
+      onMouseActivity: () => {
+        this.setSource('mouse');
+      },
+      onGamepadConnection: (isConnected) => {
+        this.controls.isGamepadConnected ||= isConnected;
+        this.controls.sync();
+      },
+      shouldCancelScrollKeys: () => this.config !== null,
+    });
+    if (typeof requestAnimationFrame === 'function') {
+      requestAnimationFrame(() => {
+        this.tick();
+      });
+    }
+  }
+
+  /** Whether this page counts as a touch device. */
+  get touchDevice(): boolean {
+    return this.controls.isTouchDevice;
+  }
+
+  /** Declare the game's inputs (replacing any earlier declaration). The game owns input from now on. */
+  define(config: InputConfig): void {
+    if (!this.isPageOwner) {
+      const previous = this.options.claimPage?.(this) ?? null;
+      this.isPageOwner = true;
+      previous?.yieldPageTo?.(this);
+    }
+    this.config = config;
+    this.registry.declare(config, (name, declared) => this.remaps.withBinding(name, declared));
+    this.navigator.clearGroups();
+    for (const [group, groupDefinition] of Object.entries(config.groups)) {
+      if (groupDefinition.navigable !== undefined) {
+        this.navigator.addGroup(group, groupDefinition.navigable);
+      }
+    }
+    this.buildControls();
+    Reflect.set(window, INPUT_ACTIVE_FLAG, true);
+  }
+
+  /** True once the game has declared its inputs. */
+  get isDefined(): boolean {
+    return this.pageOwner?.isDefined ?? this.config !== null;
+  }
+
+  /** Turn a group on. Held keys don't fire a phantom `down` (the pause key held as play resumes). */
+  enable(group: string): void {
+    this.registry.setGroupEnabled(group, true, this.devices, this.activeSource);
+    this.controls.sync();
+    this.navigator.refreshGroup(group, this.navigatorContext());
+  }
+
+  /** Turn a group off (its inputs read 0). */
+  disable(group: string): void {
+    this.registry.setGroupEnabled(group, false, this.devices, this.activeSource);
+    this.controls.sync();
+    this.navigator.blurGroup(group, this.controls.existingOverlay);
+  }
+
+  /** Whether a group is on. */
+  isEnabled(group: string): boolean {
+    return this.registry.isEnabled(group);
+  }
+
+  /** An input's value, 0..1. */
+  value(name: string): number {
+    return this.registry.value(name);
+  }
+
+  /** An input's full reading this frame. */
+  get(name: string): InputReading {
+    return this.registry.reading(name);
+  }
+
+  /** Whether an input went down this frame. */
+  down(name: string): boolean {
+    return this.registry.wentDown(name);
+  }
+
+  /** Whether an input came up this frame. */
+  up(name: string): boolean {
+    return this.registry.wentUp(name);
+  }
+
+  /** Whether an input is held (≥ 0.5). */
+  pressed(name: string): boolean {
+    return this.registry.isPressed(name);
+  }
+
+  /** A named axis, or an ad-hoc `axis(negative, positive)` pair, as -1..1. */
+  axis(name: string, positive?: string): number {
+    return this.registry.axis(name, positive);
+  }
+
+  /** A named axis pair as a vector clamped to the unit circle. */
+  vector(name: string): Vector {
+    return this.registry.vector(name);
+  }
+
+  /** The device the player is using right now. */
+  get source(): InputSource {
+    return this.activeSource;
+  }
+
+  /** Subscribe to an input event. Returns the unsubscribe function. */
+  on<Name extends keyof InputEvents>(event: Name, listener: (payload: InputEvents[Name]) => void): () => void {
+    return this.events.on(event, listener);
+  }
+
+  /** Update a button's content at runtime (e.g. an SVG reflecting game state). */
+  setVirtualHtml(id: string, html: string): void {
+    this.controls.existingOverlay?.setControlHtml(id, html);
+  }
+
+  /** The player's show/hide choice for the on-screen controls (persisted). */
+  showVirtual(isVisible: boolean): void {
+    this.controls.playerChoice = isVisible;
+    this.remaps.setShowVirtual(isVisible);
+    this.controls.sync();
+  }
+
+  /** Flip the player's show/hide choice. */
+  toggleVirtual(): void {
+    this.showVirtual(!this.showingVirtual);
+  }
+
+  /** Force the controls visible for layout editing, without changing the player's choice. */
+  setVirtualEditing(isEditing: boolean): void {
+    this.controls.setEditing(isEditing);
+  }
+
+  /** This game's default visibility (the player's choice still wins); `null` = shown on touch devices without a pad. */
+  setVirtualDefault(isVisible: boolean | null): void {
+    this.controls.setGameDefault(isVisible);
+  }
+
+  /**
+   * Keep auto-placed controls clear of a band along a screen edge, e.g. your
+   * top HUD: `setInsets({ top: hud.getBoundingClientRect().bottom })`. Px from
+   * each edge, merged with earlier calls (0 clears one edge). Dragged controls
+   * and explicit `pos` ignore it.
+   */
+  setInsets(insets: { top?: number; right?: number; bottom?: number; left?: number }): void {
+    this.controls.overlay().setInsets(insets);
+  }
+
+  /** What the "Show on-screen controls" toggle reflects. */
+  get showingVirtual(): boolean {
+    return this.controls.isShowing;
+  }
+
+  /** Rebind an input (persisted). */
+  rebind(inputName: string, patch: Partial<InputDef>): void {
+    this.remaps.rebind(inputName, patch);
+    const declared = this.config?.groups[this.registry.groupOf(inputName) ?? '']?.inputs[inputName];
+    if (declared !== undefined) {
+      this.registry.redefine(inputName, this.remaps.withBinding(inputName, declared));
+    }
+  }
+
+  /** Move or restyle an on-screen control (persisted). */
+  setVirtual(id: string, patch: VirtualOverride): void {
+    this.remaps.customiseControl(id, patch);
+    this.buildControls();
+  }
+
+  /** Open (or close) the Controls screen. */
+  openControls(): void {
+    if (this.pageOwner === null) {
+      this.controls.overlay().toggleControls(this.config, this);
+    } else {
+      this.pageOwner.openControls();
+    }
+  }
+
+  /** Forget every remap and customisation. */
+  resetControls(): void {
+    this.remaps.reset();
+    this.controls.playerChoice = null;
+    if (this.config !== null) {
+      this.define(this.config);
+    }
+  }
+
+  /** A readable label of an input's current binding. */
+  bindingLabel(inputName: string): string {
+    return describeBinding(this.registry.definitionOf(inputName));
+  }
+
+  /** Called by the injected menu: Select toggles it and a gamepad navigates it. */
+  attachMenu(bridge: MenuBridge | null): void {
+    if (this.pageOwner === null) {
+      this.menu = bridge;
+    } else {
+      this.pageOwner.attachMenu(bridge);
+    }
+  }
+
+  /** Called by the injected menu with `game.controls`, for the zero-config fallback. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from window.__HUB__, parsed straight away
+  setLegacyControls(controls: unknown): void {
+    if (this.pageOwner === null) {
+      this.legacyControlsSource = controls;
+      this.legacyControls = parseLegacyControls(controls);
+    } else {
+      this.pageOwner.setLegacyControls(controls);
+    }
+  }
+
+  /**
+   * Make a game's own on-screen menu gamepad-navigable: a CSS selector (or a
+   * function returning elements). While any match is visible and a gamepad is
+   * in use, the stick moves a highlight, A clicks, B calls `options.back`.
+   * Re-queried every frame, so call it once.
+   */
+  autoNavigate(selector: string | (() => NavTarget[]), options?: { back?: () => void }): void {
+    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);
+  }
+
+  /**
+   * Stop driving the page because another copy's game owns it (plan §4.4):
+   * hand the menu and `game.controls` to `owner`, and forward the menu's calls to it.
+   */
+  yieldPageTo(owner: PageInputControl): void {
+    this.isPageOwner = false;
+    this.pageOwner = owner;
+    owner.attachMenu(this.menu);
+    owner.setLegacyControls(this.legacyControlsSource);
+    this.menu = null;
+  }
+
+  private buildControls(): void {
+    if (this.config === null) {
+      return;
+    }
+    const callbacks = feedDeviceState(this.devices, {
+      onTouch: () => {
+        this.setSource('touch');
+      },
+      onDragged: (id, spot) => {
+        this.setVirtual(id, spot);
+      },
+    });
+    this.controls.build(this.config, this.remaps.overrides, callbacks);
+  }
+
+  private setSource(source: InputSource): void {
+    if (source === this.activeSource) {
+      return;
+    }
+    this.activeSource = source;
+    this.events.emit('sourcechange', source);
+    this.controls.sync();
+  }
+
+  private navigatorContext(): NavigatorContext {
+    return {
+      gamepads: this.devices.gamepads,
+      repeats: this.repeats,
+      presses: this.presses,
+      listeners: {
+        onFocus: (event) => {
+          this.events.emit('focus', event);
+        },
+        onBlur: (event) => {
+          this.events.emit('blur', event);
+        },
+        onAct: (event) => {
+          this.events.emit('act', event);
+        },
+      },
+      highlighter: () => this.controls.overlay(),
+      isPressed: (name) => this.registry.isPressed(name),
+      wentDown: (name) => this.registry.wentDown(name),
+    };
+  }
+
+  private tick(): void {
+    this.devices.frame += 1;
+    const { isConnected, hasActivity } = this.devices.pollGamepads();
+    this.controls.isGamepadConnected = isConnected;
+    if (hasActivity) {
+      this.setSource('gamepad');
+      this.modality?.set('keys');
+    }
+    if (this.isPageOwner) {
+      this.driveFrame();
+    } else {
+      this.registry.sample(this.devices, this.activeSource);
+    }
+    this.devices.decay();
+    this.controls.existingOverlay?.afterFrame();
+    requestAnimationFrame(() => {
+      this.tick();
+    });
+  }
+
+  /** One frame as the page owner: the menu toggle and navigation, inputs, the zero-config fallback. */
+  private driveFrame(): void {
+    const context = this.navigatorContext();
+    const overlay = this.controls.existingOverlay;
+    const isGamepadActive = this.activeSource === 'gamepad';
+    const menu = this.menu;
+    // Select toggles the hub menu from anywhere.
+    if (menu !== null && this.presses.rose('select', isAnyPadButtonPressed(this.devices.gamepads, PAD_BUTTON.SELECT))) {
+      menu.toggle();
+    }
+    if (menu?.isOpen() === true) {
+      // The menu takes over input: the game's inputs read 0 while it is open.
+      this.registry.silence();
+      this.navigator.driveMenu(menu, isGamepadActive, context, overlay);
+      return;
+    }
+    this.navigator.leaveMenu(overlay);
+    if (this.config !== null) {
+      this.registry.sample(this.devices, this.activeSource);
+      this.navigator.driveGroups((group) => this.registry.isEnabled(group), context);
+    } else if (Reflect.get(window, INPUT_ACTIVE_FLAG) !== true) {
+      runZeroConfigFrame({ gamepads: this.devices.gamepads, slug: this.host.slug, controls: this.legacyControls, navEdges: this.repeats });
+    }
+    this.navigator.driveAutoNavigate(isGamepadActive, context, overlay);
+  }
+}