@diffenderfer-games/hub 0.0.0-stage → 2.0.0-next.1

package/dist/shared/input.d.ts

@@ -0,0 +1,730 @@
+//#region src/input/types.d.ts
+/**
+ * The input system's public shapes (`hub.input`, docs/hub.md "Input system").
+ * A game declares named inputs that each read as 0..1 and maps each to
+ * keyboard, mouse, touch and gamepad sources.
+ */
+/** The device the player is using right now. */
+type InputSource = 'keyboard' | 'mouse' | 'gamepad' | 'touch';
+/** A direction or half of an axis. */
+type AxisSide = '+' | '-';
+/** How the mouse drives an input. */
+interface MouseMapping {
+  /** Held while this mouse button is down. */
+  button?: number;
+  /** 1 for one frame on a double-click. */
+  dblclick?: boolean;
+  /** The pointer's position from screen centre on this axis maps to 0..1 on one side. */
+  centerAxis?: 'x' | 'y';
+  /** Which side of centre fills 0..1 (default `+`). */
+  centerSide?: AxisSide;
+  /** Relative movement on this axis, scaled by `moveScale`. */
+  moveAxis?: 'x' | 'y';
+  /** Which direction of movement counts (default `+`). */
+  moveSign?: AxisSide;
+  /** Movement scale (default 0.1). */
+  moveScale?: number;
+  /** Wheel delta in this direction (decays). */
+  wheel?: AxisSide;
+}
+/** How a gamepad drives an input. */
+interface GamepadMapping {
+  /** A standard-gamepad button index (0/1, or a 0..1 trigger). */
+  button?: number;
+  /** An axis index and which half: `+` positive, `-` negative, `±` absolute value. */
+  axis?: [number, AxisSide | '±'];
+}
+/** How touch and the on-screen controls drive an input. */
+interface TouchMapping {
+  /** The id of a virtual button that drives this input. */
+  button?: string;
+  /** The id of a virtual joystick. */
+  stick?: string;
+  /** Which half or axis of that stick. */
+  axis?: 'x+' | 'x-' | 'y+' | 'y-' | 'x' | 'y';
+  /** 1 for one frame on a tap anywhere on a tap control. */
+  tap?: boolean;
+  /** The last touch's position from screen centre on this axis maps to 0..1 on one side. */
+  centerAxis?: 'x' | 'y';
+  /** Which side of centre fills 0..1 (default `+`). */
+  centerSide?: AxisSide;
+}
+/** One named input and its sources. */
+interface InputDef {
+  /** `KeyboardEvent.key` values (case-insensitive). */
+  keys?: string[];
+  /** Mouse source (counts while the mouse is the active pointer). */
+  mouse?: MouseMapping;
+  /** Gamepad source (counts while a gamepad is the active pointer). */
+  gamepad?: GamepadMapping;
+  /** Touch and on-screen control source. */
+  touch?: TouchMapping;
+}
+/**
+ * A named axis. Each of `x` and `y` is a `[negative, positive]` pair of input
+ * names (read as -1..1), or one input name read directly.
+ */
+interface AxisDef {
+  /** The horizontal axis. */
+  x?: string | [string, string];
+  /** The vertical axis. */
+  y?: string | [string, string];
+}
+/** Where an on-screen control sits. */
+type Anchor = 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
+/** The kinds of on-screen control. */
+type VirtualControlType = 'button' | 'joystick' | 'dpad' | 'tap';
+/** Pixel distances from the viewport edges. */
+interface EdgeOffsets {
+  /** From the left edge. */
+  left?: number;
+  /** From the right edge. */
+  right?: number;
+  /** From the top edge. */
+  top?: number;
+  /** From the bottom edge. */
+  bottom?: number;
+}
+/** The inputs a dpad or button drives. */
+interface VirtualInputs {
+  /** Up. */
+  up?: string;
+  /** Down. */
+  down?: string;
+  /** Left. */
+  left?: string;
+  /** Right. */
+  right?: string;
+  /** A press. */
+  press?: string;
+}
+/** An on-screen touch control. */
+interface VirtualDef {
+  /** Its id (inputs reference it from `touch.button` or `touch.stick`). */
+  id: string;
+  /** What it is. */
+  type: VirtualControlType;
+  /** Its anchor for the automatic layout. */
+  place: Anchor;
+  /**
+   * An explicit pixel position from the viewport edges; bypasses the automatic
+   * layout for this control (e.g. pin a pause button just above a stick).
+   */
+  pos?: EdgeOffsets;
+  /**
+   * Nudge an auto-placed control away from its anchor's edges, in px: `x`
+   * moves it inward from the left/right edge, `y` away from the top/bottom
+   * edge. For a band every control should avoid, use `hub.input.setInsets`.
+   */
+  offset?: {
+    x?: number;
+    y?: number;
+  };
+  /** Diameter in px (or the width when `width`/`height` are given). */
+  size?: number;
+  /** Width in px; overrides `size` for non-square controls. */
+  width?: number;
+  /** Height in px; overrides `size` for non-square controls. */
+  height?: number;
+  /** Default circle for sticks, round for buttons. */
+  shape?: 'round' | 'circle' | 'square' | 'pill';
+  /** A stick's travel: `both` (default), or single-axis `x` / `y`. */
+  axis?: 'x' | 'y' | 'both';
+  /** 0..1. */
+  opacity?: number;
+  /** Accent colour (border, knob, pressed fill). */
+  color?: string;
+  /** Resting background colour. */
+  bg?: string;
+  /** Label text colour. */
+  text?: string;
+  /** Text on a button. */
+  label?: string;
+  /** Raw HTML inside a button. */
+  html?: string;
+  /** For a dpad or button: the inputs it drives. Joysticks drive the inputs that reference them. */
+  inputs?: VirtualInputs;
+}
+/** A screen rectangle in px. */
+interface Rect {
+  /** Left. */
+  x: number;
+  /** Top. */
+  y: number;
+  /** Width. */
+  width: number;
+  /** Height. */
+  height: number;
+}
+/** What a navigable element is, for `act`. */
+type NavElementKind = 'button' | 'text' | 'range' | 'custom';
+/** A navigable element that isn't (only) a DOM node, e.g. a canvas-drawn button. */
+interface NavElement {
+  /** Its id, echoed in focus/blur/act events. */
+  id?: string;
+  /** What it is (`text` opens the on-screen keyboard on act). */
+  kind?: NavElementKind;
+  /** A DOM element: bounds, click and focus come from it. */
+  el?: HTMLElement;
+  /** Its bounds, for elements without `el`. */
+  getBounds?: () => Rect;
+  /** Called when it gains the highlight. */
+  onFocus?: () => void;
+  /** Called when it loses the highlight. */
+  onBlur?: () => void;
+  /** Called when the player activates it. */
+  onAct?: () => void;
+}
+/** What a navigable group's element list may hold. */
+type NavTarget = HTMLElement | NavElement;
+/** Makes a group's UI navigable by gamepad and keys. */
+interface NavigableDef {
+  /** Input that steps to the previous element. */
+  prev?: string;
+  /** Input that steps to the next element. */
+  next?: string;
+  /** Input that moves up spatially. */
+  up?: string;
+  /** Input that moves down spatially. */
+  down?: string;
+  /** Input that activates the highlighted element. */
+  act: string;
+  /** The elements, re-queried after every interaction (the DOM can change). */
+  elements: () => NavTarget[];
+  /** Wrap around at the ends (default true). */
+  wrap?: boolean;
+}
+/** A named group of inputs, enabled and disabled together. */
+interface GroupDef {
+  /** The inputs, by name. */
+  inputs: Record<string, InputDef>;
+  /** Named axes over the inputs. */
+  axes?: Record<string, AxisDef>;
+  /** On-screen controls shown while the group is enabled. */
+  virtual?: VirtualDef[];
+  /** Makes the group's UI navigable. */
+  navigable?: NavigableDef;
+  /** Start enabled (default false; call `enable()` yourself). */
+  enabled?: boolean;
+}
+/** What `hub.input.define` takes. */
+interface InputConfig {
+  /** The groups, by name. */
+  groups: Record<string, GroupDef>;
+}
+/** One input's reading this frame. */
+interface InputReading {
+  /** 0..1. */
+  value: number;
+  /** Same as `value`. */
+  raw: number;
+  /** It crossed 0.5 upward this frame. */
+  isDown: boolean;
+  /** It crossed 0.5 downward this frame. */
+  isUp: boolean;
+}
+/** A 2D reading, clamped to the unit circle. */
+interface Vector {
+  /** -1..1. */
+  x: number;
+  /** -1..1. */
+  y: number;
+  /** 0..1. */
+  mag: number;
+}
+/** A player-dragged spot: the control's top-left corner as % of the viewport. */
+interface DraggedSpot {
+  /** % of the viewport width. */
+  x?: number;
+  /** % of the viewport height. */
+  y?: number;
+}
+/** A player's changes to a virtual control. */
+type VirtualOverride = Partial<VirtualDef> & DraggedSpot;
+/** The player's remaps and control customisations, persisted per game. */
+interface InputOverrides {
+  /** Rebound inputs, by input name. */
+  bindings?: Record<string, Partial<InputDef>>;
+  /** Moved or restyled on-screen controls, by control id. */
+  virtual?: Record<string, VirtualOverride>;
+  /** The player's show/hide choice for the on-screen controls. */
+  showVirtual?: boolean;
+}
+/** The hub menu, as the input system drives it (toggle on Select, gamepad navigation inside). */
+interface MenuBridge {
+  /** Open or close the menu; returns whether it is now open. */
+  toggle: () => boolean;
+  /** Whether the menu is open. */
+  isOpen: () => boolean;
+  /** Close the menu. */
+  close: () => void;
+  /** The menu's shadow root (its focusables are navigated). */
+  root: ShadowRoot | null;
+}
+/** A navigation focus or act event. */
+interface NavFocusEvent {
+  /** The element's id, if it has one. */
+  id?: string | undefined;
+  /** The DOM element, if any. */
+  el?: HTMLElement | undefined;
+  /** What it is. */
+  kind?: NavElementKind | undefined;
+  /** Its index in the list. */
+  index: number;
+}
+/** A navigation blur event. */
+interface NavBlurEvent {
+  /** The element's id, if it has one. */
+  id?: string | undefined;
+  /** Its index in the list. */
+  index: number;
+}
+/** Events `hub.input.on` delivers, name → payload. */
+interface InputEvents {
+  /** An element gained the highlight. */
+  focus: NavFocusEvent;
+  /** An element lost the highlight. */
+  blur: NavBlurEvent;
+  /** The player activated an element. */
+  act: NavFocusEvent;
+  /** The active device changed. */
+  sourcechange: InputSource;
+  /** Reserved. */
+  navigate: NavFocusEvent;
+}
+/** Where the input system persists the player's remaps. */
+interface InputHost {
+  /** This page's game slug. */
+  readonly slug: string | null;
+  /** The saved overrides, or `null`. */
+  loadOverrides(): InputOverrides | null;
+  /** Save overrides (locally, and to the cloud when signed in). */
+  saveOverrides(overrides: InputOverrides): void;
+}
+//#endregion
+//#region src/overlay/controls-panel.d.ts
+/** What the Controls screen drives (the input system). */
+interface ControlsPanelHost {
+  /** The player's show/hide state of the on-screen controls. */
+  readonly showingVirtual: boolean;
+  /** Show or hide the on-screen controls (persisted). */
+  showVirtual(isVisible: boolean): void;
+  /** Force the controls visible while editing the layout. */
+  setVirtualEditing(isEditing: boolean): void;
+  /** Rebind an input (persisted). */
+  rebind(inputName: string, patch: Partial<InputDef>): void;
+  /** Forget every remap. */
+  resetControls(): void;
+  /** A readable label of an input's current binding. */
+  bindingLabel(inputName: string): string;
+}
+//#endregion
+//#region src/input/page-control.d.ts
+/** The cross-bundle input surface. */
+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`. */
+  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;
+}
+/** Whether `candidate` is some bundle's input system. */
+declare function isPageInputControl(candidate: unknown): candidate is PageInputControl;
+//#endregion
+//#region src/input/input-system.d.ts
+/** Options for the input system. */
+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 page's input system. */
+declare class InputSystem implements ControlsPanelHost, PageInputControl {
+  private readonly host;
+  private readonly options;
+  private config;
+  private readonly remaps;
+  private readonly registry;
+  private readonly devices;
+  private readonly controls;
+  private readonly navigator;
+  private readonly repeats;
+  private readonly presses;
+  private readonly events;
+  private menu;
+  private legacyControls;
+  private legacyControlsSource;
+  private activeSource;
+  private isPageOwner;
+  private pageOwner;
+  constructor(host: InputHost, options?: InputSystemOptions);
+  /** Whether this page counts as a touch device. */
+  get touchDevice(): boolean;
+  /** Declare the game's inputs (replacing any earlier declaration). The game owns input from now on. */
+  define(config: InputConfig): void;
+  /** True once the game has declared its inputs. */
+  get isDefined(): boolean;
+  /** Turn a group on. Held keys don't fire a phantom `down` (the pause key held as play resumes). */
+  enable(group: string): void;
+  /** Turn a group off (its inputs read 0). */
+  disable(group: string): void;
+  /** Whether a group is on. */
+  isEnabled(group: string): boolean;
+  /** An input's value, 0..1. */
+  value(name: string): number;
+  /** An input's full reading this frame. */
+  get(name: string): InputReading;
+  /** Whether an input went down this frame. */
+  down(name: string): boolean;
+  /** Whether an input came up this frame. */
+  up(name: string): boolean;
+  /** Whether an input is held (≥ 0.5). */
+  pressed(name: string): boolean;
+  /** A named axis, or an ad-hoc `axis(negative, positive)` pair, as -1..1. */
+  axis(name: string, positive?: string): number;
+  /** A named axis pair as a vector clamped to the unit circle. */
+  vector(name: string): Vector;
+  /** The device the player is using right now. */
+  get source(): InputSource;
+  /** Subscribe to an input event. Returns the unsubscribe function. */
+  on<Name extends keyof InputEvents>(event: Name, listener: (payload: InputEvents[Name]) => void): () => void;
+  /** Update a button's content at runtime (e.g. an SVG reflecting game state). */
+  setVirtualHtml(id: string, html: string): void;
+  /** The player's show/hide choice for the on-screen controls (persisted). */
+  showVirtual(isVisible: boolean): void;
+  /** Flip the player's show/hide choice. */
+  toggleVirtual(): void;
+  /** Force the controls visible for layout editing, without changing the player's choice. */
+  setVirtualEditing(isEditing: boolean): void;
+  /** This game's default visibility (the player's choice still wins); `null` = shown on touch devices without a pad. */
+  setVirtualDefault(isVisible: boolean | null): void;
+  /**
+   * 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;
+  /** What the "Show on-screen controls" toggle reflects. */
+  get showingVirtual(): boolean;
+  /** Rebind an input (persisted). */
+  rebind(inputName: string, patch: Partial<InputDef>): void;
+  /** Move or restyle an on-screen control (persisted). */
+  setVirtual(id: string, patch: VirtualOverride): void;
+  /** Open (or close) the Controls screen. */
+  openControls(): void;
+  /** Forget every remap and customisation. */
+  resetControls(): void;
+  /** A readable label of an input's current binding. */
+  bindingLabel(inputName: string): string;
+  /** Called by the injected menu: Select toggles it and a gamepad navigates it. */
+  attachMenu(bridge: MenuBridge | null): void;
+  /** Called by the injected menu with `game.controls`, for the zero-config fallback. */
+  setLegacyControls(controls: unknown): void;
+  /**
+   * 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;
+  /** Stop navigating the game's own menu. */
+  clearAutoNavigate(): void;
+  /**
+   * 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;
+  private buildControls;
+  private setSource;
+  private navigatorContext;
+  private tick;
+  /** One frame as the page owner: the menu toggle and navigation, inputs, the zero-config fallback. */
+  private driveFrame;
+}
+//#endregion
+//#region src/input/page-input.d.ts
+/** The cross-bundle shape number of the `input` singleton. Bump only on an incompatible change. */
+declare const INPUT_SINGLETON_API = 1;
+/** Whether `candidate` is some bundle's input system (v1 copies included). */
+declare function isInputSystem(candidate: unknown): candidate is InputSystem;
+/** How the core client connects the input system to its game. */
+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;
+}
+/** Saved overrides from JSON, keeping only well-formed fields. */
+declare function parseInputOverrides(saved: unknown): InputOverrides;
+/**
+ * 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.
+ */
+declare function getInput(options?: InputOptions): InputSystem;
+//#endregion
+//#region src/input/nav-state.d.ts
+/** What a navigable list draws with (the overlay). */
+interface NavHighlighter {
+  /** Ring the highlighted element. */
+  showHighlight(bounds: Rect): void;
+  /** Remove the ring. */
+  hideHighlight(): void;
+  /** Open the on-screen keyboard for a text field. */
+  openKeyboard(target: HTMLInputElement | HTMLTextAreaElement | null): void;
+}
+//#endregion
+//#region src/overlay/layout-geometry.d.ts
+/** A placed control: top-left corner and size, in viewport px. */
+interface LayoutBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+/** One control as the layout engine sees it (its rendered px size). */
+interface LayoutItem {
+  /** The control id. */
+  id: string;
+  /** Its type. */
+  type: VirtualDef['type'];
+  /** Its anchor. */
+  place: Anchor;
+  /** Rendered width. */
+  w: number;
+  /** Rendered height. */
+  h: number;
+  /** An explicit position from the edges. */
+  pos?: VirtualDef['pos'] | undefined;
+  /** A nudge away from the anchor's edges. */
+  offset?: VirtualDef['offset'] | undefined;
+  /** The player's dragged spot: the control's top-left corner as % of the viewport. */
+  override?: {
+    x: number;
+    y: number;
+  } | undefined;
+}
+/** Px insets from each viewport edge. */
+interface Insets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+/** The rendered size of a control: buttons and taps draw a 2px border outside their declared size; sticks draw theirs inside. */
+declare function controlSize(definition: Pick<VirtualDef, 'type' | 'size' | 'width' | 'height'>): {
+  w: number;
+  h: number;
+};
+/** Do two boxes overlap (or come closer than `padding` px)? */
+declare function boxesTouch(first: LayoutBox, second: LayoutBox, padding?: number): boolean;
+//#endregion
+//#region src/overlay/virtual-controls.d.ts
+/** What a control reports. */
+interface VirtualControlCallbacks {
+  /** A button went down. */
+  onButtonDown(id: string): void;
+  /** A button came up. */
+  onButtonUp(id: string): void;
+  /** A stick moved (-1..1 per axis; 0, 0 on release). */
+  onStick(id: string, outX: number, outY: number): void;
+  /** A tap region was tapped. */
+  onTap(): void;
+  /** The player dropped a dragged control: its top-left corner as % of the viewport. */
+  onDragged(id: string, spot: {
+    x: number;
+    y: number;
+  }): void;
+}
+//#endregion
+//#region src/overlay/overlay.d.ts
+/** The overlay (one per input system). */
+declare class Overlay implements NavHighlighter {
+  private readonly shadowHost;
+  private readonly root;
+  private readonly controlsLayer;
+  private readonly ring;
+  private readonly keyboard;
+  private readonly controlsPanel;
+  private controls;
+  private controlScope;
+  private overrides;
+  private gameInsets;
+  private raceHudBands;
+  private safeAreaProbe;
+  constructor();
+  /** (Re)build every on-screen control from the config and the player's overrides. */
+  build(config: InputConfig, overrides: InputOverrides, callbacks: VirtualControlCallbacks): void;
+  /** Replace a button or tap control's content at runtime. Listeners live on the wrapper, so they survive. */
+  setControlHtml(id: string, html: string): void;
+  /** Show controls of the enabled groups (or of every group, with `null`, while editing). */
+  setVirtualVisible(isVisible: boolean, enabledGroups: ReadonlySet<string> | null): void;
+  /** Game insets (px) auto-placed controls keep clear of, e.g. a top HUD bar. Merged with earlier calls. */
+  setInsets(insets: Partial<Insets>): void;
+  /** Re-place every control for the current viewport, keeping the player's dragged spots. */
+  layout(): void;
+  /** Ring the highlighted element. */
+  showHighlight(bounds: Rect): void;
+  /** Remove the ring. */
+  hideHighlight(): void;
+  /** Open the on-screen keyboard for a text field. */
+  openKeyboard(target: HTMLInputElement | HTMLTextAreaElement | null): void;
+  /** Whether the on-screen keyboard is showing. */
+  get isKeyboardOpen(): boolean;
+  /** Open (or close) the Controls screen. */
+  toggleControls(config: InputConfig | null, host: ControlsPanelHost): void;
+  /** Per-frame work: gamepad navigation of the keyboard. */
+  afterFrame(): void;
+  /** The device safe-area insets (notch, home bar), via a probe element. */
+  private readSafeArea;
+}
+//#endregion
+//#region src/overlay/layout.d.ts
+/** Layout options. */
+interface LayoutOptions {
+  /** Game insets (a HUD bar…): auto-placed controls keep clear of them. */
+  insets?: Partial<Insets>;
+  /** Device safe area (notch, home bar): every control stays inside it. */
+  safe?: Partial<Insets>;
+  /** Distance from the edges for auto-placed controls (default 22). */
+  margin?: number;
+  /** Space between auto-placed controls (default 14). */
+  gap?: number;
+}
+/**
+ * Place every control for a `viewportWidth` × `viewportHeight` viewport and
+ * return each control's box.
+ *
+ * 1. A game `pos` is honoured as given. A player-dragged control keeps its
+ *    spot (as % of the viewport, re-clamped inside the safe area), nudged to
+ *    the nearest free spot if it would land on (or within `gap` of) a stick.
+ * 2. Sticks sit in their anchor's corner, side by side inward.
+ * 3. Buttons cluster beside their corner's sticks, stacked in columns. If any
+ *    cluster doesn't fit, every corner cluster that has sticks moves into rows
+ *    above (below, for top corners) its sticks, first-declared button
+ *    innermost. Any button that still collides moves to the nearest free spot.
+ */
+declare function layoutControls(items: readonly LayoutItem[], viewportWidth: number, viewportHeight: number, options?: LayoutOptions): Record<string, LayoutBox>;
+//#endregion
+//#region src/uistack/types.d.ts
+/**
+ * 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. */
+type OverlayReason = 'menu' | 'chat' | 'dialog' | 'keyboard' | 'invite' | 'notify';
+/** An overlay edge. */
+type OverlayEdge = 'open' | 'close';
+/** Payload of `open` and `close` (and of the `hub:overlay-open` / `hub:overlay-close` window events). */
+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}. */
+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. */
+type OverlayListener = (event: OverlayEvent) => void;
+/** What an older, idle stack hands to a newer one replacing it. */
+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.
+ */
+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;
+}
+//#endregion
+//#region src/uistack/page-stack.d.ts
+declare global {
+  interface Window {
+    __HUB_UI__?: unknown;
+  }
+}
+/** Whether `candidate` is some bundle's overlay stack. */
+declare function isUiStack(candidate: unknown): candidate is UiStack;
+/**
+ * The page-wide overlay stack, created on first use. Outside a browser a
+ * module-local instance is returned.
+ */
+declare function getUiStack(): UiStack;
+//#endregion
+//#region src/uistack/ui-stack.d.ts
+/** Bump when the UiStack contract gains behaviour; idle older instances are replaced. */
+declare const UI_STACK_VERSION = 1;
+//#endregion
+export { VirtualControlType as $, AxisSide as A, InputReading as B, parseInputOverrides as C, isPageInputControl as D, PageInputControl as E, InputConfig as F, NavElement as G, MenuBridge as H, InputDef as I, NavTarget as J, NavElementKind as K, InputEvents as L, EdgeOffsets as M, GamepadMapping as N, Anchor as O, GroupDef as P, Vector as Q, InputHost as R, isInputSystem as S, InputSystemOptions as T, MouseMapping as U, InputSource as V, NavBlurEvent as W, Rect as X, NavigableDef as Y, TouchMapping as Z, boxesTouch as _, OverlayEdge as a, InputOptions as b, OverlayReason as c, LayoutOptions as d, VirtualDef as et, layoutControls as f, LayoutItem as g, LayoutBox as h, AutoPauseOptions as i, DraggedSpot as j, AxisDef as k, UiStack as l, Insets as m, getUiStack as n, VirtualOverride as nt, OverlayEvent as o, Overlay as p, NavFocusEvent as q, isUiStack as r, OverlayListener as s, UI_STACK_VERSION as t, VirtualInputs as tt, UiStackHandoff as u, controlSize as v, InputSystem as w, getInput as x, INPUT_SINGLETON_API as y, InputOverrides as z };
+//# sourceMappingURL=input.d.ts.map