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

package/src/input/page-control.ts

@@ -1,43 +1,43 @@
-/**
- * The small, stable slice of the input system that other bundles on the page
- * use (plan §4.4): the host menu (attach itself, `game.controls`, the
- * Controls button), the social runtime's dialogs (navigate them), the
- * overlay stack (suspend `play`), and a handover between two client copies.
- * Every client version keeps these methods.
- */
-import { hasMethods } from '../realtime/cross-bundle';
-import type { MenuBridge, NavTarget } from './types';
-
-/** The cross-bundle input surface. */
-export interface PageInputControl {
-  /** Whether the game declared its inputs. */
-  readonly isDefined: boolean;
-  /** The host menu attaches itself. */
-  attachMenu(bridge: MenuBridge | null): void;
-  /** The host menu passes `game.controls`. */
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page, parsed by the implementation
-  setLegacyControls(controls: unknown): void;
-  /** The menu's Controls button. */
-  openControls(): void;
-  /** 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;
-  /** Make elements gamepad-navigable (the runtime's dialogs). */
-  autoNavigate(selector: string | (() => NavTarget[]), options?: { back?: () => void }): void;
-  /** Stop navigating them. */
-  clearAutoNavigate(): void;
-  /** Stop driving the page and hand over to `owner`. Absent on v1 copies. */
-  yieldPageTo?(owner: PageInputControl): void;
-}
-
-/** The methods every input system on the page has, v1 copies included. */
-const PAGE_INPUT_METHODS = ['attachMenu', 'setLegacyControls', 'openControls', 'isEnabled', 'enable', 'disable', 'autoNavigate', 'clearAutoNavigate', 'define', 'value'] as const;
-
-/** Whether `candidate` is some bundle's input system. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
-export function isPageInputControl(candidate: unknown): candidate is PageInputControl {
-  return hasMethods(candidate, PAGE_INPUT_METHODS);
-}
+/**
+ * The small, stable slice of the input system that other bundles on the page
+ * use (plan §4.4): the host menu (attach itself, `game.controls`, the
+ * Controls button), the social runtime's dialogs (navigate them), the
+ * overlay stack (suspend `play`), and a handover between two client copies.
+ * Every client version keeps these methods.
+ */
+import { hasMethods } from '../realtime/cross-bundle';
+import type { MenuBridge, NavTarget } from './types';
+
+/** The cross-bundle input surface. */
+export interface PageInputControl {
+  /** Whether the game declared its inputs. */
+  readonly isDefined: boolean;
+  /** The host menu attaches itself. */
+  attachMenu(bridge: MenuBridge | null): void;
+  /** The host menu passes `game.controls`. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page, parsed by the implementation
+  setLegacyControls(controls: unknown): void;
+  /** The menu's Controls button. */
+  openControls(): void;
+  /** 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;
+  /** Make elements gamepad-navigable (the runtime's dialogs). */
+  autoNavigate(selector: string | (() => NavTarget[]), options?: { back?: () => void }): void;
+  /** Stop navigating them. */
+  clearAutoNavigate(): void;
+  /** Stop driving the page and hand over to `owner`. Absent on v1 copies. */
+  yieldPageTo?(owner: PageInputControl): void;
+}
+
+/** The methods every input system on the page has, v1 copies included. */
+const PAGE_INPUT_METHODS = ['attachMenu', 'setLegacyControls', 'openControls', 'isEnabled', 'enable', 'disable', 'autoNavigate', 'clearAutoNavigate', 'define', 'value'] as const;
+
+/** Whether `candidate` is some bundle's input system. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
+export function isPageInputControl(candidate: unknown): candidate is PageInputControl {
+  return hasMethods(candidate, PAGE_INPUT_METHODS);
+}

package/src/input/page-input.ts

@@ -1,193 +1,193 @@
-/**
- * The page's one input system (plan §4.4). The game's copy of the client owns
- * the page because the game defines the controls; the host menu reaches it
- * through the stable {@link PageInputControl} slice. Remaps persist to
- * localStorage (offline-safe) and, through the core client, to a reserved
- * cloud save slot.
- */
-import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
-import { claimSingleton, LEGACY_GLOBAL_NAMES } from '../globals';
-import { hasMethods, isObject, readField } from '../realtime/cross-bundle';
-import { InputSystem } from './input-system';
-import { isPageInputControl } from './page-control';
-import type { PageInputControl } from './page-control';
-import type { InputDef, InputHost, InputOverrides, VirtualOverride } from './types';
-
-/** The cross-bundle shape number of the `input` singleton. Bump only on an incompatible change. */
-export const INPUT_SINGLETON_API = 1;
-
-/** The public methods of every input system, v1 copies included. */
-const INPUT_SYSTEM_METHODS = [
-  'define', 'enable', 'disable', 'isEnabled', 'value', 'get', 'down', 'up', 'pressed', 'axis', 'vector', 'on',
-  'setVirtualHtml', 'showVirtual', 'setInsets', 'autoNavigate', 'clearAutoNavigate', 'attachMenu', 'setLegacyControls',
-  'openControls', 'rebind', 'setVirtual',
-] as const;
-
-/** Whether `candidate` is some bundle's input system (v1 copies included). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
-export function isInputSystem(candidate: unknown): candidate is InputSystem {
-  return hasMethods(candidate, INPUT_SYSTEM_METHODS);
-}
-
-/** How the core client connects the input system to its game. */
-export interface InputOptions {
-  /** This page's game slug (default: `window.__HUB__.slug`). */
-  slug?: string | null;
-  /** Mirror remaps to the cloud (the core client writes the `__controls` save slot). */
-  saveToCloud?: (overrides: InputOverrides) => void;
-}
-
-/** A finite number, or `undefined`. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
-function finiteNumber(candidate: unknown): number | undefined {
-  return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : undefined;
-}
-
-/** A saved rebind: the keys or gamepad button the player chose. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
-function parseBinding(saved: unknown): Partial<InputDef> {
-  const binding: Partial<InputDef> = {};
-  const keys = readField(saved, 'keys');
-  if (Array.isArray(keys) && keys.every((key) => typeof key === 'string')) {
-    binding.keys = keys.filter((key): key is string => typeof key === 'string');
-  }
-  const button = finiteNumber(readField(readField(saved, 'gamepad'), 'button'));
-  if (button !== undefined) {
-    binding.gamepad = { button };
-  }
-  return binding;
-}
-
-/** A saved dragged spot. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
-function parseVirtualOverride(saved: unknown): VirtualOverride {
-  const spot: VirtualOverride = {};
-  const left = finiteNumber(readField(saved, 'x'));
-  const top = finiteNumber(readField(saved, 'y'));
-  if (left !== undefined) {
-    spot.x = left;
-  }
-  if (top !== undefined) {
-    spot.y = top;
-  }
-  return spot;
-}
-
-/** Entries of a saved record, parsed. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
-function parseRecord<Parsed>(saved: unknown, parseEntry: (entry: unknown) => Parsed): Record<string, Parsed> | undefined {
-  if (!isObject(saved)) {
-    return undefined;
-  }
-  return Object.fromEntries(Object.entries(saved).map(([key, entry]) => [key, parseEntry(entry)]));
-}
-
-/** Saved overrides from JSON, keeping only well-formed fields. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON read back from localStorage
-export function parseInputOverrides(saved: unknown): InputOverrides {
-  const overrides: InputOverrides = {};
-  const bindings = parseRecord(readField(saved, 'bindings'), parseBinding);
-  const virtual = parseRecord(readField(saved, 'virtual'), parseVirtualOverride);
-  const showVirtual = readField(saved, 'showVirtual');
-  if (bindings !== undefined) {
-    overrides.bindings = bindings;
-  }
-  if (virtual !== undefined) {
-    overrides.virtual = virtual;
-  }
-  if (typeof showVirtual === 'boolean') {
-    overrides.showVirtual = showVirtual;
-  }
-  return overrides;
-}
-
-/** A field of the host's injected `window.__HUB__`. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the host page's injected config, checked by the caller
-function injectedField(key: string): unknown {
-  return typeof window === 'undefined' ? undefined : readField(readField(window, '__HUB__'), key);
-}
-
-/** The slug the host injected, or `null`. */
-function injectedSlug(): string | null {
-  const slug = injectedField('slug');
-  return typeof slug === 'string' ? slug : null;
-}
-
-/** A new input system, starting from the host's injected `game.controls` (the menu may pass them again later). */
-function createInputSystem(options: InputOptions, isPageOwner: boolean): InputSystem {
-  const system = new InputSystem(createInputHost(options), { isPageOwner, claimPage: registerAsPageInput });
-  system.setLegacyControls(injectedField('controls') ?? null);
-  return system;
-}
-
-/** Persistence for remaps: localStorage under `hub:<slug>:input`, mirrored to the cloud when given. */
-function createInputHost(options: InputOptions): InputHost {
-  const slug = options.slug === undefined ? injectedSlug() : options.slug;
-  const storageKey = `hub:${slug ?? 'null'}:input`;
-  return {
-    slug,
-    loadOverrides() {
-      try {
-        const saved = localStorage.getItem(storageKey);
-        if (saved === null) {
-          return null;
-        }
-        // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON from localStorage, parsed straight away
-        const parsed: unknown = JSON.parse(saved);
-        return parseInputOverrides(parsed);
-      } catch {
-        return null;
-      }
-    },
-    saveOverrides(overrides) {
-      try {
-        localStorage.setItem(storageKey, JSON.stringify(overrides));
-      } catch {
-        // Storage full or blocked: the cloud copy still saves.
-      }
-      if (slug !== null) {
-        options.saveToCloud?.(overrides);
-      }
-    },
-  };
-}
-
-/** Make `system` the page's registered input system; returns the one it replaces. */
-function registerAsPageInput(system: InputSystem): PageInputControl | null {
-  const registry = window.__DG__ ?? {};
-  window.__DG__ = registry;
-  const previous = registry.input?.instance ?? window[LEGACY_GLOBAL_NAMES.input];
-  registry.input = { version: HUB_CLIENT_VERSION, api: INPUT_SINGLETON_API, instance: system };
-  window[LEGACY_GLOBAL_NAMES.input] = system;
-  return previous !== system && isPageInputControl(previous) ? previous : null;
-}
-
-/** Whether another bundle registered an input system with a different shape number. */
-function hasMismatchedPageInput(): boolean {
-  const registered = typeof window === 'undefined' ? undefined : window.__DG__?.input;
-  return registered !== undefined && registered.api !== INPUT_SINGLETON_API && isInputSystem(registered.instance);
-}
-
-let claimedInput: InputSystem | null = null;
-
-/**
- * The page-wide input system, created on first use. `options` connect it to
- * the core client (its slug, the cloud save); the first call's options win.
- * When another client copy with a different shape owns the page, this copy
- * gets a private instance that takes the page over once its game defines
- * inputs.
- */
-export function getInput(options: InputOptions = {}): InputSystem {
-  if (claimedInput !== null) {
-    return claimedInput;
-  }
-  const isPrivate = hasMismatchedPageInput();
-  claimedInput = claimSingleton({
-    name: 'input',
-    version: HUB_CLIENT_VERSION,
-    api: INPUT_SINGLETON_API,
-    create: () => createInputSystem(options, !isPrivate),
-    isInstance: isInputSystem,
-  });
-  return claimedInput;
-}
+/**
+ * The page's one input system (plan §4.4). The game's copy of the client owns
+ * the page because the game defines the controls; the host menu reaches it
+ * through the stable {@link PageInputControl} slice. Remaps persist to
+ * localStorage (offline-safe) and, through the core client, to a reserved
+ * cloud save slot.
+ */
+import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
+import { claimSingleton, LEGACY_GLOBAL_NAMES } from '../globals';
+import { hasMethods, isObject, readField } from '../realtime/cross-bundle';
+import { InputSystem } from './input-system';
+import { isPageInputControl } from './page-control';
+import type { PageInputControl } from './page-control';
+import type { InputDef, InputHost, InputOverrides, VirtualOverride } from './types';
+
+/** The cross-bundle shape number of the `input` singleton. Bump only on an incompatible change. */
+export const INPUT_SINGLETON_API = 1;
+
+/** The public methods of every input system, v1 copies included. */
+const INPUT_SYSTEM_METHODS = [
+  'define', 'enable', 'disable', 'isEnabled', 'value', 'get', 'down', 'up', 'pressed', 'axis', 'vector', 'on',
+  'setVirtualHtml', 'showVirtual', 'setInsets', 'autoNavigate', 'clearAutoNavigate', 'attachMenu', 'setLegacyControls',
+  'openControls', 'rebind', 'setVirtual',
+] as const;
+
+/** Whether `candidate` is some bundle's input system (v1 copies included). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
+export function isInputSystem(candidate: unknown): candidate is InputSystem {
+  return hasMethods(candidate, INPUT_SYSTEM_METHODS);
+}
+
+/** How the core client connects the input system to its game. */
+export interface InputOptions {
+  /** This page's game slug (default: `window.__HUB__.slug`). */
+  slug?: string | null;
+  /** Mirror remaps to the cloud (the core client writes the `__controls` save slot). */
+  saveToCloud?: (overrides: InputOverrides) => void;
+}
+
+/** A finite number, or `undefined`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
+function finiteNumber(candidate: unknown): number | undefined {
+  return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : undefined;
+}
+
+/** A saved rebind: the keys or gamepad button the player chose. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
+function parseBinding(saved: unknown): Partial<InputDef> {
+  const binding: Partial<InputDef> = {};
+  const keys = readField(saved, 'keys');
+  if (Array.isArray(keys) && keys.every((key) => typeof key === 'string')) {
+    binding.keys = keys.filter((key): key is string => typeof key === 'string');
+  }
+  const button = finiteNumber(readField(readField(saved, 'gamepad'), 'button'));
+  if (button !== undefined) {
+    binding.gamepad = { button };
+  }
+  return binding;
+}
+
+/** A saved dragged spot. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
+function parseVirtualOverride(saved: unknown): VirtualOverride {
+  const spot: VirtualOverride = {};
+  const left = finiteNumber(readField(saved, 'x'));
+  const top = finiteNumber(readField(saved, 'y'));
+  if (left !== undefined) {
+    spot.x = left;
+  }
+  if (top !== undefined) {
+    spot.y = top;
+  }
+  return spot;
+}
+
+/** Entries of a saved record, parsed. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
+function parseRecord<Parsed>(saved: unknown, parseEntry: (entry: unknown) => Parsed): Record<string, Parsed> | undefined {
+  if (!isObject(saved)) {
+    return undefined;
+  }
+  return Object.fromEntries(Object.entries(saved).map(([key, entry]) => [key, parseEntry(entry)]));
+}
+
+/** Saved overrides from JSON, keeping only well-formed fields. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON read back from localStorage
+export function parseInputOverrides(saved: unknown): InputOverrides {
+  const overrides: InputOverrides = {};
+  const bindings = parseRecord(readField(saved, 'bindings'), parseBinding);
+  const virtual = parseRecord(readField(saved, 'virtual'), parseVirtualOverride);
+  const showVirtual = readField(saved, 'showVirtual');
+  if (bindings !== undefined) {
+    overrides.bindings = bindings;
+  }
+  if (virtual !== undefined) {
+    overrides.virtual = virtual;
+  }
+  if (typeof showVirtual === 'boolean') {
+    overrides.showVirtual = showVirtual;
+  }
+  return overrides;
+}
+
+/** A field of the host's injected `window.__HUB__`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the host page's injected config, checked by the caller
+function injectedField(key: string): unknown {
+  return typeof window === 'undefined' ? undefined : readField(readField(window, '__HUB__'), key);
+}
+
+/** The slug the host injected, or `null`. */
+function injectedSlug(): string | null {
+  const slug = injectedField('slug');
+  return typeof slug === 'string' ? slug : null;
+}
+
+/** A new input system, starting from the host's injected `game.controls` (the menu may pass them again later). */
+function createInputSystem(options: InputOptions, isPageOwner: boolean): InputSystem {
+  const system = new InputSystem(createInputHost(options), { isPageOwner, claimPage: registerAsPageInput });
+  system.setLegacyControls(injectedField('controls') ?? null);
+  return system;
+}
+
+/** Persistence for remaps: localStorage under `hub:<slug>:input`, mirrored to the cloud when given. */
+function createInputHost(options: InputOptions): InputHost {
+  const slug = options.slug === undefined ? injectedSlug() : options.slug;
+  const storageKey = `hub:${slug ?? 'null'}:input`;
+  return {
+    slug,
+    loadOverrides() {
+      try {
+        const saved = localStorage.getItem(storageKey);
+        if (saved === null) {
+          return null;
+        }
+        // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON from localStorage, parsed straight away
+        const parsed: unknown = JSON.parse(saved);
+        return parseInputOverrides(parsed);
+      } catch {
+        return null;
+      }
+    },
+    saveOverrides(overrides) {
+      try {
+        localStorage.setItem(storageKey, JSON.stringify(overrides));
+      } catch {
+        // Storage full or blocked: the cloud copy still saves.
+      }
+      if (slug !== null) {
+        options.saveToCloud?.(overrides);
+      }
+    },
+  };
+}
+
+/** Make `system` the page's registered input system; returns the one it replaces. */
+function registerAsPageInput(system: InputSystem): PageInputControl | null {
+  const registry = window.__DG__ ?? {};
+  window.__DG__ = registry;
+  const previous = registry.input?.instance ?? window[LEGACY_GLOBAL_NAMES.input];
+  registry.input = { version: HUB_CLIENT_VERSION, api: INPUT_SINGLETON_API, instance: system };
+  window[LEGACY_GLOBAL_NAMES.input] = system;
+  return previous !== system && isPageInputControl(previous) ? previous : null;
+}
+
+/** Whether another bundle registered an input system with a different shape number. */
+function hasMismatchedPageInput(): boolean {
+  const registered = typeof window === 'undefined' ? undefined : window.__DG__?.input;
+  return registered !== undefined && registered.api !== INPUT_SINGLETON_API && isInputSystem(registered.instance);
+}
+
+let claimedInput: InputSystem | null = null;
+
+/**
+ * The page-wide input system, created on first use. `options` connect it to
+ * the core client (its slug, the cloud save); the first call's options win.
+ * When another client copy with a different shape owns the page, this copy
+ * gets a private instance that takes the page over once its game defines
+ * inputs.
+ */
+export function getInput(options: InputOptions = {}): InputSystem {
+  if (claimedInput !== null) {
+    return claimedInput;
+  }
+  const isPrivate = hasMismatchedPageInput();
+  claimedInput = claimSingleton({
+    name: 'input',
+    version: HUB_CLIENT_VERSION,
+    api: INPUT_SINGLETON_API,
+    create: () => createInputSystem(options, !isPrivate),
+    isInstance: isInputSystem,
+  });
+  return claimedInput;
+}

package/src/input/player-remaps.ts

@@ -1,77 +1,77 @@
-/**
- * The player's remaps and on-screen control customisations for one game,
- * persisted through the input host after every change.
- */
-import type { InputDef, InputHost, InputOverrides, VirtualOverride } from './types';
-
-/** A readable label of an input's binding (`w/ArrowUp · Pad 0`). */
-export function describeBinding(definition: InputDef | undefined): string {
-  const parts: string[] = [];
-  if (definition?.keys !== undefined && definition.keys.length > 0) {
-    parts.push(definition.keys.join('/'));
-  }
-  if (definition?.gamepad?.button !== undefined) {
-    parts.push(`Pad ${String(definition.gamepad.button)}`);
-  }
-  if (definition?.gamepad?.axis !== undefined) {
-    parts.push(`Axis ${String(definition.gamepad.axis[0])}${definition.gamepad.axis[1]}`);
-  }
-  return parts.length > 0 ? parts.join(' · ') : '—';
-}
-
-/** The player's overrides, saved on every change. */
-export class PlayerRemaps {
-  private readonly host: InputHost;
-  private saved: InputOverrides;
-
-  constructor(host: InputHost) {
-    this.host = host;
-    this.saved = host.loadOverrides() ?? {};
-  }
-
-  /** The overrides as they stand. */
-  get overrides(): InputOverrides {
-    return this.saved;
-  }
-
-  /** A declared input with the player's rebind applied. */
-  withBinding(name: string, declared: InputDef): InputDef {
-    return { ...declared, ...this.saved.bindings?.[name] };
-  }
-
-  /** Rebind an input. */
-  rebind(inputName: string, patch: Partial<InputDef>): void {
-    const bindings = this.saved.bindings ?? {};
-    bindings[inputName] = { ...bindings[inputName], ...patch };
-    this.saved.bindings = bindings;
-    this.persist();
-  }
-
-  /** Move or restyle an on-screen control. */
-  customiseControl(id: string, patch: VirtualOverride): void {
-    const virtual = this.saved.virtual ?? {};
-    virtual[id] = { ...virtual[id], ...patch };
-    this.saved.virtual = virtual;
-    this.persist();
-  }
-
-  /** Record the player's show/hide choice. */
-  setShowVirtual(isVisible: boolean): void {
-    this.saved.showVirtual = isVisible;
-    this.persist();
-  }
-
-  /** Forget everything. */
-  reset(): void {
-    this.saved = {};
-    this.persist();
-  }
-
-  private persist(): void {
-    try {
-      this.host.saveOverrides(this.saved);
-    } catch {
-      // Storage can be full or blocked; remaps still apply for this visit.
-    }
-  }
-}
+/**
+ * The player's remaps and on-screen control customisations for one game,
+ * persisted through the input host after every change.
+ */
+import type { InputDef, InputHost, InputOverrides, VirtualOverride } from './types';
+
+/** A readable label of an input's binding (`w/ArrowUp · Pad 0`). */
+export function describeBinding(definition: InputDef | undefined): string {
+  const parts: string[] = [];
+  if (definition?.keys !== undefined && definition.keys.length > 0) {
+    parts.push(definition.keys.join('/'));
+  }
+  if (definition?.gamepad?.button !== undefined) {
+    parts.push(`Pad ${String(definition.gamepad.button)}`);
+  }
+  if (definition?.gamepad?.axis !== undefined) {
+    parts.push(`Axis ${String(definition.gamepad.axis[0])}${definition.gamepad.axis[1]}`);
+  }
+  return parts.length > 0 ? parts.join(' · ') : '—';
+}
+
+/** The player's overrides, saved on every change. */
+export class PlayerRemaps {
+  private readonly host: InputHost;
+  private saved: InputOverrides;
+
+  constructor(host: InputHost) {
+    this.host = host;
+    this.saved = host.loadOverrides() ?? {};
+  }
+
+  /** The overrides as they stand. */
+  get overrides(): InputOverrides {
+    return this.saved;
+  }
+
+  /** A declared input with the player's rebind applied. */
+  withBinding(name: string, declared: InputDef): InputDef {
+    return { ...declared, ...this.saved.bindings?.[name] };
+  }
+
+  /** Rebind an input. */
+  rebind(inputName: string, patch: Partial<InputDef>): void {
+    const bindings = this.saved.bindings ?? {};
+    bindings[inputName] = { ...bindings[inputName], ...patch };
+    this.saved.bindings = bindings;
+    this.persist();
+  }
+
+  /** Move or restyle an on-screen control. */
+  customiseControl(id: string, patch: VirtualOverride): void {
+    const virtual = this.saved.virtual ?? {};
+    virtual[id] = { ...virtual[id], ...patch };
+    this.saved.virtual = virtual;
+    this.persist();
+  }
+
+  /** Record the player's show/hide choice. */
+  setShowVirtual(isVisible: boolean): void {
+    this.saved.showVirtual = isVisible;
+    this.persist();
+  }
+
+  /** Forget everything. */
+  reset(): void {
+    this.saved = {};
+    this.persist();
+  }
+
+  private persist(): void {
+    try {
+      this.host.saveOverrides(this.saved);
+    } catch {
+      // Storage can be full or blocked; remaps still apply for this visit.
+    }
+  }
+}