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

package/src/input/input-events.ts

@@ -0,0 +1,32 @@
+/**
+ * The input system's events (`hub.input.on`): typed listeners per event,
+ * isolated so one failing listener can't stop the frame loop.
+ */
+import type { InputEvents } from './types';
+
+/** Listeners by event name. */
+export class InputEventHub {
+  private readonly listeners: { [Name in keyof InputEvents]: Set<(payload: InputEvents[Name]) => void> } = {
+    focus: new Set(), blur: new Set(), act: new Set(), sourcechange: new Set(), navigate: new Set(),
+  };
+
+  /** Subscribe. Returns the unsubscribe function. */
+  on<Name extends keyof InputEvents>(event: Name, listener: (payload: InputEvents[Name]) => void): () => void {
+    const registered = this.listeners[event];
+    registered.add(listener);
+    return () => {
+      registered.delete(listener);
+    };
+  }
+
+  /** Deliver an event to every listener. */
+  emit<Name extends keyof InputEvents>(event: Name, payload: InputEvents[Name]): void {
+    for (const listener of [...this.listeners[event]]) {
+      try {
+        listener(payload);
+      } catch {
+        // A game's listener failing must not stop the frame loop.
+      }
+    }
+  }
+}

package/src/input/input-registry.ts

@@ -0,0 +1,164 @@
+/**
+ * The declared inputs, groups and axes, and their readings: each input's raw
+ * value this frame and last frame, from which edges, axes and vectors follow.
+ */
+import type { DeviceState } from './device-state';
+import { clampUnit, readRawValue } from './source-values';
+import type { AxisDef, InputConfig, InputDef, InputReading, InputSource, Vector } from './types';
+
+/** One input's live state. */
+interface LiveInput {
+  definition: InputDef;
+  readonly group: string;
+  raw: number;
+  previous: number;
+}
+
+/** Inputs cross this to count as pressed. */
+const PRESS_THRESHOLD = 0.5;
+
+/** One side of an axis definition as -1..1. */
+function readAxisSide(side: AxisDef['x'], valueOf: (name: string) => number): number {
+  if (side === undefined) {
+    return 0;
+  }
+  if (typeof side === 'string') {
+    return valueOf(side);
+  }
+  return clampUnit(valueOf(side[1])) - clampUnit(valueOf(side[0]));
+}
+
+/** The declared inputs and their readings. */
+export class InputRegistry {
+  private readonly inputs = new Map<string, LiveInput>();
+  private readonly enabledGroups = new Map<string, boolean>();
+  private readonly axes = new Map<string, AxisDef>();
+
+  /** Replace the declared inputs. Groups keep an enabled state set before; new ones start as declared. */
+  declare(config: InputConfig, bindingOf: (name: string, declared: InputDef) => InputDef): void {
+    this.inputs.clear();
+    this.axes.clear();
+    for (const [group, groupDefinition] of Object.entries(config.groups)) {
+      if (!this.enabledGroups.has(group)) {
+        this.enabledGroups.set(group, groupDefinition.enabled ?? false);
+      }
+      for (const [name, definition] of Object.entries(groupDefinition.inputs)) {
+        this.inputs.set(name, { definition: bindingOf(name, definition), group, raw: 0, previous: 0 });
+      }
+      for (const [name, axis] of Object.entries(groupDefinition.axes ?? {})) {
+        this.axes.set(name, axis);
+      }
+    }
+  }
+
+  /** The group an input belongs to. */
+  groupOf(name: string): string | undefined {
+    return this.inputs.get(name)?.group;
+  }
+
+  /** Replace one input's sources (after a rebind). */
+  redefine(name: string, definition: InputDef): void {
+    const input = this.inputs.get(name);
+    if (input !== undefined) {
+      input.definition = definition;
+    }
+  }
+
+  /** Turn a group on or off. On: held sources don't fire a phantom `down`. Off: its inputs read 0. */
+  setGroupEnabled(group: string, isEnabled: boolean, devices: DeviceState, source: InputSource): void {
+    this.enabledGroups.set(group, isEnabled);
+    for (const input of this.inputs.values()) {
+      if (input.group !== group) {
+        continue;
+      }
+      input.raw = isEnabled ? readRawValue(devices, input.definition, source) : 0;
+      if (isEnabled) {
+        input.previous = input.raw;
+      }
+    }
+  }
+
+  /** Whether a group is on. */
+  isEnabled(group: string): boolean {
+    return this.enabledGroups.get(group) === true;
+  }
+
+  /** The groups that are on. */
+  enabledGroupNames(): Set<string> {
+    return new Set([...this.enabledGroups].filter(([, isOn]) => isOn).map(([group]) => group));
+  }
+
+  /** Take this frame's readings (inputs of disabled groups read 0). */
+  sample(devices: DeviceState, source: InputSource): void {
+    for (const input of this.inputs.values()) {
+      input.previous = input.raw;
+      input.raw = this.isEnabled(input.group) ? readRawValue(devices, input.definition, source) : 0;
+    }
+  }
+
+  /** Every input reads 0 this frame (the hub menu is open). */
+  silence(): void {
+    for (const input of this.inputs.values()) {
+      input.previous = input.raw;
+      input.raw = 0;
+    }
+  }
+
+  /** An input's value, 0..1. */
+  value(name: string): number {
+    return this.inputs.get(name)?.raw ?? 0;
+  }
+
+  /** Whether an input crossed the press threshold upward this frame. */
+  wentDown(name: string): boolean {
+    const input = this.inputs.get(name);
+    return input !== undefined && input.previous < PRESS_THRESHOLD && input.raw >= PRESS_THRESHOLD;
+  }
+
+  /** Whether an input crossed the press threshold downward this frame. */
+  wentUp(name: string): boolean {
+    const input = this.inputs.get(name);
+    return input !== undefined && input.previous >= PRESS_THRESHOLD && input.raw < PRESS_THRESHOLD;
+  }
+
+  /** Whether an input is held. */
+  isPressed(name: string): boolean {
+    return this.value(name) >= PRESS_THRESHOLD;
+  }
+
+  /** An input's full reading. */
+  reading(name: string): InputReading {
+    const raw = this.value(name);
+    return { value: raw, raw, isDown: this.wentDown(name), isUp: this.wentUp(name) };
+  }
+
+  /** A named axis (or an ad-hoc negative/positive pair) as -1..1. */
+  axis(name: string, positive?: string): number {
+    if (positive !== undefined) {
+      return clampUnit(this.value(positive)) - clampUnit(this.value(name));
+    }
+    const axis = this.axes.get(name);
+    return axis === undefined ? this.value(name) : readAxisSide(axis.x, (input) => this.value(input));
+  }
+
+  /** A named axis pair as a vector clamped to the unit circle. */
+  vector(name: string): Vector {
+    const axis = this.axes.get(name);
+    if (axis === undefined) {
+      return { x: 0, y: 0, mag: 0 };
+    }
+    let horizontal = readAxisSide(axis.x, (input) => this.value(input));
+    let vertical = readAxisSide(axis.y, (input) => this.value(input));
+    const magnitude = Math.hypot(horizontal, vertical);
+    if (magnitude > 1) {
+      horizontal /= magnitude;
+      vertical /= magnitude;
+    }
+    return { x: horizontal, y: vertical, mag: Math.min(magnitude, 1) };
+  }
+
+  /** An input's current sources (for the binding label). */
+  definitionOf(name: string): InputDef | undefined {
+    return this.inputs.get(name)?.definition;
+  }
+}

package/src/input/input-system.ts

@@ -0,0 +1,393 @@
+/**
+ * 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);
+  }
+}

package/src/input/legacy-controls.ts

@@ -0,0 +1,64 @@
+/**
+ * `game.controls` (`window.__HUB__.controls`): the gamepad-to-keyboard map a
+ * zero-config game declares. It comes from the page, so it is read field by
+ * field; anything malformed falls back to the defaults.
+ */
+import { isObject, readField } from '../realtime/cross-bundle';
+
+/** One player's resolved map: a `KeyboardEvent.code` per direction and per button index. */
+export interface ResolvedControlMap {
+  up: string;
+  down: string;
+  left: string;
+  right: string;
+  buttons: Map<number, string>;
+}
+
+/** The parsed `game.controls`: one map per player (pads past the end use the first). */
+export type LegacyControls = readonly ResolvedControlMap[];
+
+/** The defaults: arrows, A=Space, B=Enter, X=Z, Y=X, Select=Escape, Start=Enter. */
+const DEFAULT_BUTTONS: ReadonlyArray<readonly [number, string]> = [[0, 'Space'], [1, 'Enter'], [2, 'KeyZ'], [3, 'KeyX'], [9, 'Enter'], [8, 'Escape']];
+
+/** A text field of the map, or the default. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page
+function textOr(map: unknown, key: string, fallback: string): string {
+  const field = readField(map, key);
+  return typeof field === 'string' && field !== '' ? field : fallback;
+}
+
+/** One player's map over the defaults. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page
+function resolveMap(map: unknown): ResolvedControlMap {
+  const buttons = new Map<number, string>(DEFAULT_BUTTONS);
+  const declared = readField(map, 'buttons');
+  if (isObject(declared)) {
+    for (const [index, code] of Object.entries(declared)) {
+      if (typeof code === 'string' && code !== '' && /^\d+$/.test(index)) {
+        buttons.set(Number(index), code);
+      }
+    }
+  }
+  return {
+    up: textOr(map, 'up', 'ArrowUp'),
+    down: textOr(map, 'down', 'ArrowDown'),
+    left: textOr(map, 'left', 'ArrowLeft'),
+    right: textOr(map, 'right', 'ArrowRight'),
+    buttons,
+  };
+}
+
+/** Parse `game.controls` (a shared map, or per-player maps in `players`). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page
+export function parseLegacyControls(raw: unknown): LegacyControls {
+  const players = readField(raw, 'players');
+  if (Array.isArray(players) && players.length > 0) {
+    return players.map(resolveMap);
+  }
+  return [resolveMap(raw)];
+}
+
+/** The map for the pad at `padIndex`. */
+export function controlMapFor(controls: LegacyControls, padIndex: number): ResolvedControlMap {
+  return controls[padIndex] ?? controls[0] ?? resolveMap(null);
+}