// gamepadShim.ts — Mega 4: the W3C Gamepad API shim. Every JOINED seat appears inside the GAME FRAME
// as a standard `Gamepad` (`navigator.getGamepads()` + `gamepadconnected` / `gamepaddisconnected`),
// so any web game that already supports gamepads works on the couch unchanged.
//
// STANDALONE (like shortplay-sdk.ts / shortplay-players.ts): imports only the frozen players contract
// types. It runs INSIDE the sandboxed game frame; the SDK constructs it when the parent says the game
// opted in (manifest `inputs` ∋ `gamepad`, and NOT `managesPlayers` — those games use `onInput`).
//
// ── Mapping (W3C "standard" layout) ─────────────────────────────────────────────────────────────
//   phone retro pad : A=0 B=1 Select=8 Start=9 d-pad up/down/left/right=12/13/14/15; left stick
//                     axes[0..1] (twin-stick adds axes[2..3]). Sent as `button` / `axes` on the event
//                     (Mega 2 writes them); when ABSENT we map `dpadDirection` / `token` / `code`.
//   TV remote seat  : OK(select)=0 Back(Escape/Backspace)=1 arrows=12..15.
//   Seat index      : P1→0 … P4→3. The index IS the slot, so it is stable across a drop + rejoin.
//
// ── Drop ────────────────────────────────────────────────────────────────────────────────────────
// A seat leaving `joined` (held or empty) first RELEASES every pressed button + zeroes the axes
// (the cancel), THEN fires `gamepaddisconnected` — so a game never sees a disconnected pad still
// holding a button. The seat's index is reserved while held; rejoin re-fires `gamepadconnected`.
//
// ── Timing (the jitter buffer) ──────────────────────────────────────────────────────────────────
// Each edge carries the DEVICE clock `t` (+ `heldMs` on release). Wi-Fi jitter (30-100 ms per edge)
// lives in arrival time, never in `t`. We replay every edge at `t + minOffset + jitterBufferMs`,
// where minOffset = min(arrival - t) seen for that seat (the best-case path), so the down→up spacing
// is the phone's, shifted by a constant. An edge that still arrives later than its slot (jitter >
// buffer) applies at once, and a RELEASE is additionally held to `pressApplied + max(heldMs | end.t -
// start.t, GAMEPAD_MIN_PRESS_MS)` so a late press can never shorten the press: a 150 ms tap stays 150 ms.
//   LATENCY COST: a constant `jitterBufferMs` (default 100 ms) added to every press/release vs the
//   best-case network path. It absorbs up to that much per-edge jitter. A frame with no device clock
//   (an older controller) is applied on arrival, unbuffered. Slow clock drift between devices is not
//   modelled (a min-offset tracker self-corrects toward the lowest-delay path only).

//
// ── SELF-CONTAINED (Mega 6) — a HARD REQUIREMENT, same as controllerInputDispatch.ts ───────────
// This module is consumed TWO ways:
//   (1) imported normally by the child SDK (shortplay-sdk.ts);
//   (2) `.toString()`'d into the literal inline <script> the games-worker injects into EVERY served
//       uploaded-game HTML document (games-worker/src/inputShim.ts) — so a plain web game that only
//       calls `navigator.getGamepads()` gets the seats WITHOUT bundling this SDK.
// Path (2) means `createGamepadShim` and `isGamepadPlayersMessage` must resolve using ONLY their
// own parameters, their own LOCAL declarations and JS/DOM builtins — never a module-level
// `const` / `import` / helper. Every constant and helper they need is therefore declared INSIDE the
// function body (a free variable is a `ReferenceError` the moment the extracted source runs with no
// module scope). The exported `GAMEPAD_*` constants below are the PUBLIC mirror of those locals;
// tests/games-sdk/gamepadShim.test.ts pins the two together and executes the extracted source.
// Type-only imports are fine (erased); a VALUE import is not.
//
// ── ONE shim per window (the double-wiring guard) ───────────────────────────────────────────────
// A game that bundles the SDK AND is served by the games-worker has both consumers in one document.
// `createGamepadShim` is idempotent per window through the shared marker `window.__spGamepadShim`:
// the first call installs, every later call returns that SAME instance (its options are ignored), so
// there is one set of pads and one `gamepadconnected` per seat whoever asked first. (Who FEEDS it is
// decided separately by `window.__spInputOwner` — see shortplay-sdk.ts / inputShim.ts.)
//
// ── Pad `id` by device kind + layout (AMENDMENT-2 item 9) ───────────────────────────────────────
// Every pad keeps the FULL standard shape (17 buttons / 4 axes), so a game cannot tell a remote from
// a phone pad by a missing button. It tells by the id PREFIX (the index already names the seat):
//   `ShortPlay Remote (STANDARD GAMEPAD Vendor: 5350 Product: 0003)`           the TV remote
//   `ShortPlay Phone Retro Pad (STANDARD GAMEPAD Vendor: 5350 Product: 0001)`  phone/tablet, `retro`
//   `ShortPlay Phone Twin Stick (STANDARD GAMEPAD Vendor: 5350 Product: 0002)` phone/tablet, `twin-stick`
//   `ShortPlay Controller (STANDARD GAMEPAD Vendor: 5350 Product: 0000)`       anything else / unknown
// The kind comes from two OPTIONAL additive fields on each `players` seat (`device`, `layout`); when
// they are absent the id is the fallback, and the FIRST slotted input that carries `layout`
// (`retro` / `twin-stick`) may upgrade a fallback id. An id change is a RECONNECT: the seat reads
// released, fires `gamepaddisconnected`, then `gamepadconnected` with the SAME index and the new id.
// An unchanged snapshot fires nothing.
//
// ── Native (wired) pads — ONE rule: seats OR native, never both ─────────────────────────────────
// While ANY seat is joined, `getGamepads()` returns EXACTLY the four seat entries (index = seat).
// With NO seat joined it returns the native list untouched (a wired-pad game on a desk is unchanged).
// Why not "append native pads after the seats": a native Gamepad keeps its own `.index` (0..3), so a
// game that keys players by `pad.index` would see a wired pad — or an Android TV remote that
// enumerates as a gamepad — land on the SAME index as seat P1, and its idle state would overwrite
// P1's press every frame. The either/or rule cannot double (or clobber) a player.
// TRADE-OFF: a wired pad is not readable while a seat is joined. Native `gamepadconnected` events
// are not suppressed (the game's own listeners are attached before any shim could intercept them).
// The native `getGamepads` is always called inside try/catch: in a cross-origin frame WITHOUT the
// `gamepad` Permissions-Policy it throws SecurityError, and the seats must survive that.

import type { PlayerSlotId } from './shortplay-players';

/** The default jitter-buffer depth in ms (= the constant latency cost per press). */
export const GAMEPAD_JITTER_BUFFER_MS = 100;

/** A press is visible for at least this long (ms) so a rAF-polling game (16.7 ms frames) sees even a
 *  0 ms step; a longer device press is replayed at its true length. */
export const GAMEPAD_MIN_PRESS_MS = 50;

/** W3C standard-mapping button indices the shim emits. */
export const GAMEPAD_BUTTON = {
  A: 0,
  B: 1,
  Select: 8,
  Start: 9,
  Up: 12,
  Down: 13,
  Left: 14,
  Right: 15,
} as const;

/** The subset of a relayed input the shim reads (a `SlotInputEvent` / `GameInputMessage`). */
export interface GamepadShimInput {
  slot?: PlayerSlotId | null;
  token: string;
  phase: 'start' | 'move' | 'end' | 'cancel';
  t?: number;
  heldMs?: number;
  dpadDirection?: string;
  code?: string;
  button?: number;
  axes?: number[];
  /** The controller layout the sender is on (Mega 2 stamps it on input). Secondary id signal only. */
  layout?: string;
}

export interface GamepadShimSeat {
  slot: PlayerSlotId;
  state: 'empty' | 'joined' | 'held';
  /** OPTIONAL (additive): 'phone' | 'tablet' | 'remote'. Unknown/absent -> the fallback pad id. */
  device?: string | null;
  /** OPTIONAL (additive): 'touch' | 'touch+dpad' | 'retro' | 'twin-stick'. */
  layout?: string | null;
}

export interface GamepadShimOptions {
  win?: Window;
  /** Jitter-buffer depth (ms). Default {@link GAMEPAD_JITTER_BUFFER_MS}. */
  jitterBufferMs?: number;
  /** Test seams (default to the window's own). */
  now?: () => number;
  setTimeout?: (fn: () => void, ms: number) => unknown;
  clearTimeout?: (handle: unknown) => void;
}

export interface GamepadShim {
  /** Feed the current seat table; fires connected/disconnected on edges. */
  setSeats(seats: readonly GamepadShimSeat[]): void;
  /** Feed one relayed input. Returns true when the shim CONSUMED it (the caller must then NOT also
   *  inject a synthetic key/pointer event for it); false = not ours, fall through. */
  handleInput(msg: GamepadShimInput): boolean;
  /** Restore `navigator.getGamepads` and drop every timer. */
  dispose(): void;
}

interface PadButton {
  pressed: boolean;
  touched: boolean;
  value: number;
}

interface ShimPad {
  id: string;
  index: number;
  connected: boolean;
  mapping: 'standard';
  timestamp: number;
  buttons: PadButton[];
  axes: number[];
  vibrationActuator: null;
  hapticActuators: never[];
}

type Op =
  | { kind: 'button'; index: number; down: boolean }
  | { kind: 'axes'; axes: number[]; zero: boolean }
  | { kind: 'releaseAll' };

interface Queued {
  at: number;
  ops: Op[];
  /** Corrected device time for `pad.timestamp` (null = use apply time). */
  stamp: number | null;
}

interface Seat {
  slot: PlayerSlotId;
  pad: ShimPad;
  connected: boolean;
  /** min(arrival - t) — the best-case path offset between the device clock and this frame's clock. */
  minOff: number | null;
  queue: Queued[];
  timer: unknown;
  lastAt: number;
  /** per button: scheduled apply time + device t of the latest press edge (for the release clamp). */
  pressAt: Map<number, number>;
  pressT: Map<number, number>;
  /** The seat's device kind + layout from the latest snapshot (undefined/null = not told). */
  device: unknown;
  layout: unknown;
  /** `layout` learned from the first slotted input that carried one (only used when the snapshot is silent). */
  inputLayout: string | null;
  /** LATCH: buttons that went down and have not yet been RETURNED pressed by a `getGamepads()` call. */
  unobserved: Set<number>;
  /** LATCH: releases owed to a button that was still unobserved when its release came due. */
  deferred: Set<number>;
  /** Fallback timer so a game that stops polling cannot leave a deferred release stuck forever. */
  flushTimer: unknown;
}

/** The envelope + seat table of a parent→game `players` message that switches the shim ON. */
export interface GamepadPlayersMessage {
  sp: 1;
  nonce: string;
  type: 'players';
  gamepad: true;
  players: GamepadShimSeat[];
}

/**
 * SELF-CONTAINED predicate (see module header) — true iff `x` is a well-formed parent→game `players`
 * message with `gamepad === true`. FAILS CLOSED on anything else. Mirrors, field for field, what the
 * SDK accepts on the same wire (`isPlayersSnapshot` in ./shortplay-players + the sp/nonce/type
 * envelope of src/runtime/protocol.ts's `isGamePlayersMessage`) — pinned by a parity test — so the
 * SDK and the injected script agree on every message. The caller still owns the nonce comparison.
 */
export function isGamepadPlayersMessage(x: unknown): x is GamepadPlayersMessage {
  if (typeof x !== 'object' || x === null) return false;
  const rec = x as Record<string, unknown>;
  if (rec.sp !== 1) return false;
  if (typeof rec.nonce !== 'string' || rec.nonce.length === 0 || rec.nonce.length > 128) return false;
  if (rec.type !== 'players') return false;
  if (rec.gamepad !== true) return false;
  const slots = ['P1', 'P2', 'P3', 'P4'];
  if (!Array.isArray(rec.players) || rec.players.length !== slots.length) return false;
  for (let i = 0; i < slots.length; i++) {
    const p = rec.players[i] as Record<string, unknown> | null;
    if (typeof p !== 'object' || p === null) return false;
    if (p.slot !== slots[i]) return false;
    if (p.state !== 'empty' && p.state !== 'joined' && p.state !== 'held') return false;
    if (p.heldUntil !== null && (typeof p.heldUntil !== 'number' || !isFinite(p.heldUntil))) return false;
  }
  const lobby = rec.lobby as Record<string, unknown> | null;
  if (typeof lobby !== 'object' || lobby === null) return false;
  const strings = ['qrSvg', 'code'];
  for (let i = 0; i < strings.length; i++) {
    const v = lobby[strings[i] as string];
    // 65536 === PLAYERS_STRING_MAX in ./shortplay-players (inlined: self-contained).
    if (v !== null && (typeof v !== 'string' || v.length > 65536)) return false;
  }
  return typeof lobby.locked === 'boolean';
}

/**
 * SELF-CONTAINED factory (see module header): everything it needs is declared in its own body.
 * IDEMPOTENT per window via `window.__spGamepadShim` — a second call returns the first instance.
 */
export function createGamepadShim(options: GamepadShimOptions = {}): GamepadShim {
  const win = options.win ?? (globalThis as unknown as Window);
  // The double-wiring guard: whichever consumer (SDK or the games-worker inject) installs first
  // wins; the other gets the same instance back, so pads + connect events exist exactly once.
  const holder = win as unknown as { __spGamepadShim?: GamepadShim };
  if (holder.__spGamepadShim) return holder.__spGamepadShim;

  // ---- constants: LOCAL on purpose (self-contained; mirrored by the exported GAMEPAD_*) --------
  const JITTER_BUFFER_MS = 100; // === GAMEPAD_JITTER_BUFFER_MS
  const MIN_PRESS_MS = 50; // === GAMEPAD_MIN_PRESS_MS
  const BUTTON_COUNT = 17;
  const AXES_COUNT = 4;
  const SLOT_IDS: readonly PlayerSlotId[] = ['P1', 'P2', 'P3', 'P4']; // === shortplay-players' slot ids
  // W3C standard mapping (=== GAMEPAD_BUTTON): A=0 B=1 Up/Down/Left/Right=12/13/14/15.
  const DPAD_BUTTON: Record<string, number> = { up: 12, down: 13, left: 14, right: 15, select: 0 };
  const KEY_BUTTON: Record<string, number> = {
    ArrowUp: 12,
    ArrowDown: 13,
    ArrowLeft: 14,
    ArrowRight: 15,
    Enter: 0,
    Space: 0,
    Escape: 1,
    Backspace: 1,
    GoBack: 1,
  };

  /** The pad id for a seat's device kind + layout (see header). Games match on the PREFIX. */
  function padId(device: unknown, layout: unknown): string {
    if (device === 'remote') return 'ShortPlay Remote (STANDARD GAMEPAD Vendor: 5350 Product: 0003)';
    const handheld = device === 'phone' || device === 'tablet' || device === undefined || device === null;
    if (handheld && layout === 'retro') return 'ShortPlay Phone Retro Pad (STANDARD GAMEPAD Vendor: 5350 Product: 0001)';
    if (handheld && layout === 'twin-stick') return 'ShortPlay Phone Twin Stick (STANDARD GAMEPAD Vendor: 5350 Product: 0002)';
    return 'ShortPlay Controller (STANDARD GAMEPAD Vendor: 5350 Product: 0000)';
  }

  function makePad(index: number): ShimPad {
    return {
      id: padId(undefined, undefined),
      index,
      connected: false,
      mapping: 'standard',
      timestamp: 0,
      buttons: Array.from({ length: BUTTON_COUNT }, () => ({ pressed: false, touched: false, value: 0 })),
      axes: new Array<number>(AXES_COUNT).fill(0),
      vibrationActuator: null,
      hapticActuators: [],
    };
  }

  /** Map one input to ops, or null when this shim does not own the event (falls through). */
  function mapInput(msg: GamepadShimInput): Op[] | null {
    const down = msg.phase === 'start';
    const ops: Op[] = [];
    if (typeof msg.button === 'number') {
      if (msg.phase !== 'move') ops.push({ kind: 'button', index: msg.button, down });
    } else if (msg.axes === undefined) {
      if (msg.token === 'gamepad') return msg.phase === 'cancel' ? [{ kind: 'releaseAll' }] : [];
      let index: number | undefined;
      // Pointer-shaped tokens (tap/hold/drag/...) are NOT a pad's — they fall through to the synthetic path.
      if (msg.token !== 'dpad' && msg.token !== 'remote' && msg.token !== 'keyboard') return null;
      if (msg.token === 'dpad' || msg.token === 'remote') {
        if (msg.dpadDirection) index = DPAD_BUTTON[msg.dpadDirection];
        else if (msg.code) index = KEY_BUTTON[msg.code];
      } else if (msg.token === 'keyboard') {
        if (msg.code) index = KEY_BUTTON[msg.code];
        else if (msg.dpadDirection) index = DPAD_BUTTON[msg.dpadDirection];
      }
      if (index === undefined) {
        // The relay's drop-`cancel` is keyed by TOKEN only (no direction/button): release everything
        // for that seat. Any other unmapped gamepad-class event is consumed as a no-op (never a key).
        if (msg.phase === 'cancel') return [{ kind: 'releaseAll' }];
        return msg.token === 'dpad' || msg.token === 'remote' ? [] : null;
      }
      if (msg.phase !== 'move') ops.push({ kind: 'button', index, down });
    }
    if (msg.axes !== undefined) {
      ops.push({ kind: 'axes', axes: msg.axes.slice(0, AXES_COUNT), zero: msg.phase === 'end' || msg.phase === 'cancel' });
    }
    // A `move` on a mapped button (no axes) is consumed as a no-op (the button is already held).
    return ops;
  }

  const D = options.jitterBufferMs ?? JITTER_BUFFER_MS;
  const now = options.now ?? (() => (win.performance ?? performance).now());
  const setT = options.setTimeout ?? ((fn: () => void, ms: number) => win.setTimeout(fn, ms));
  const clearT = options.clearTimeout ?? ((h: unknown) => win.clearTimeout(h as number));

  const seats = new Map<PlayerSlotId, Seat>();
  SLOT_IDS.forEach((slot, i) => {
    seats.set(slot, {
      slot,
      pad: makePad(i),
      connected: false,
      minOff: null,
      queue: [],
      timer: null,
      lastAt: 0,
      pressAt: new Map(),
      pressT: new Map(),
      device: undefined,
      layout: undefined,
      inputLayout: null,
      unobserved: new Set(),
      deferred: new Set(),
      flushTimer: null,
    });
  });

  // ---- navigator.getGamepads patch ----------------------------------------------------------
  const nav = win.navigator as unknown as Record<string, unknown>;
  const hadOwn = Object.prototype.hasOwnProperty.call(nav, 'getGamepads');
  const original = nav.getGamepads as (() => (Gamepad | null)[]) | undefined;
  const patched = (): (Gamepad | null)[] => {
    let anySeat = false;
    const out: (Gamepad | null)[] = SLOT_IDS.map((slot) => {
      const seat = seats.get(slot)!;
      if (seat.connected) anySeat = true;
      if (!seat.connected) return null;
      // LATCH: a release owed to a press an EARLIER poll already saw takes effect now (before this read).
      flushDeferred(seat);
      return seat.pad as unknown as Gamepad;
    });
    // LATCH: every button this poll RETURNS pressed is now observed; a release owed to it is applied by
    // the next poll / pump (never inside this one: the game is about to read the pad we return).
    for (const slot of SLOT_IDS) {
      const seat = seats.get(slot)!;
      if (!seat.connected || seat.unobserved.size === 0) continue;
      seat.pad.buttons.forEach((b, i) => {
        if (b.pressed) seat.unobserved.delete(i);
      });
      if (seat.deferred.size > 0 && seat.flushTimer === null) {
        seat.flushTimer = setT(() => {
          seat.flushTimer = null;
          flushDeferred(seat);
        }, MIN_PRESS_MS);
      }
    }
    // While ANY seat is joined the seats ARE the pad list (see header "Native (wired) pads").
    if (anySeat) return out;
    // No seat joined: the game sees exactly what it would without the shim.
    try {
      const native = original?.call(win.navigator);
      if (native) return native;
    } catch {
      /* SecurityError (no `gamepad` Permissions-Policy in this frame) must never reach the game */
    }
    return out;
  };
  Object.defineProperty(win.navigator, 'getGamepads', { value: patched, configurable: true, writable: true });

  function fire(type: 'gamepadconnected' | 'gamepaddisconnected', pad: ShimPad): void {
    // A real GamepadEvent rejects a non-native Gamepad, so a plain Event carries `.gamepad`.
    const EventCtor = (win as unknown as { Event?: typeof Event }).Event ?? Event;
    const evt = new EventCtor(type);
    Object.defineProperty(evt, 'gamepad', { value: pad });
    win.dispatchEvent(evt);
  }

  function releaseAll(seat: Seat, stamp: number): void {
    seat.unobserved.clear();
    seat.deferred.clear();
    for (const b of seat.pad.buttons) {
      b.pressed = false;
      b.touched = false;
      b.value = 0;
    }
    seat.pad.axes.fill(0);
    seat.pad.timestamp = Math.max(seat.pad.timestamp, stamp);
  }

  /** Apply releases that were owed to presses a poll has since observed. */
  function flushDeferred(seat: Seat): void {
    if (seat.deferred.size === 0) return;
    for (const i of Array.from(seat.deferred)) {
      if (seat.unobserved.has(i)) continue;
      seat.deferred.delete(i);
      const b = seat.pad.buttons[i];
      if (!b) continue;
      b.pressed = false;
      b.touched = false;
      b.value = 0;
    }
  }

  function applyOps(seat: Seat, q: Queued): void {
    for (const op of q.ops) {
      if (op.kind === 'releaseAll') {
        releaseAll(seat, q.at);
      } else if (op.kind === 'button') {
        const b = seat.pad.buttons[op.index];
        if (!b) continue;
        if (!op.down && seat.unobserved.has(op.index)) {
          // LATCH: no poll has returned this press yet -> keep it down until one does.
          seat.deferred.add(op.index);
          continue;
        }
        if (op.down) {
          seat.deferred.delete(op.index);
          seat.unobserved.add(op.index);
        }
        b.pressed = op.down;
        b.touched = op.down;
        b.value = op.down ? 1 : 0;
      } else if (op.zero) {
        for (let i = 0; i < AXES_COUNT; i++) seat.pad.axes[i] = 0;
      } else {
        for (let i = 0; i < AXES_COUNT; i++) seat.pad.axes[i] = op.axes[i] ?? 0;
      }
    }
    seat.pad.timestamp = Math.max(seat.pad.timestamp, q.stamp ?? q.at);
  }

  function pump(seat: Seat): void {
    seat.timer = null;
    flushDeferred(seat);
    const t = now();
    while (seat.queue.length > 0 && seat.queue[0]!.at <= t) {
      applyOps(seat, seat.queue.shift()!);
    }
    arm(seat);
  }

  function arm(seat: Seat): void {
    if (seat.timer !== null || seat.queue.length === 0) return;
    seat.timer = setT(() => pump(seat), Math.max(0, seat.queue[0]!.at - now()));
  }

  function clearSeatQueue(seat: Seat): void {
    if (seat.timer !== null) clearT(seat.timer);
    seat.timer = null;
    if (seat.flushTimer !== null) clearT(seat.flushTimer);
    seat.flushTimer = null;
    // LEAVING EXCEPTION to the latch: connect/disconnect/dispose discard owed releases + observation
    // state, and `disconnect` then releaseAll()s at once, so a leaving seat never leaves a stuck button.
    seat.unobserved.clear();
    seat.deferred.clear();
    seat.queue.length = 0;
    seat.pressAt.clear();
    seat.pressT.clear();
    seat.minOff = null;
    seat.lastAt = 0;
  }

  function connect(seat: Seat): void {
    if (seat.connected) return;
    clearSeatQueue(seat);
    seat.connected = true;
    seat.pad.connected = true;
    seat.pad.timestamp = now();
    fire('gamepadconnected', seat.pad);
  }

  function disconnect(seat: Seat): void {
    if (!seat.connected) return;
    // (1) the cancel: every pressed button reads RELEASED, queued edges are discarded ...
    clearSeatQueue(seat);
    releaseAll(seat, now());
    // (2) ... THEN the disconnect (the index stays reserved for this slot).
    seat.connected = false;
    seat.pad.connected = false;
    fire('gamepaddisconnected', seat.pad);
  }

  const shim: GamepadShim = {
    setSeats(list: readonly GamepadShimSeat[]): void {
      for (const s of list) {
        const seat = seats.get(s.slot);
        if (!seat) continue;
        seat.device = s.device;
        seat.layout = s.layout;
        if (s.state === 'empty') seat.inputLayout = null; // the seat was freed: forget its last device
        if (s.state !== 'joined') {
          disconnect(seat);
          continue;
        }
        // The id is read at connect, so a changed id is a RECONNECT (released, disconnected, connected);
        // an unchanged one fires nothing (`connect` is a no-op on a connected seat).
        const id = padId(seat.device, seat.layout ?? seat.inputLayout);
        if (seat.connected && seat.pad.id !== id) disconnect(seat);
        seat.pad.id = id;
        connect(seat);
      }
    },

    handleInput(msg: GamepadShimInput): boolean {
      if (!msg.slot) return false; // no seat -> not a gamepad's
      const seat = seats.get(msg.slot);
      if (!seat) return false;
      // Secondary id signal: the snapshot said nothing about this seat's layout and this is the first
      // slotted input that does -> upgrade the FALLBACK id (a reconnect), then handle the input.
      if (
        seat.connected &&
        (seat.layout === undefined || seat.layout === null) &&
        seat.inputLayout === null &&
        (msg.layout === 'retro' || msg.layout === 'twin-stick')
      ) {
        seat.inputLayout = msg.layout;
        const id = padId(seat.device, msg.layout);
        if (id !== seat.pad.id) {
          disconnect(seat);
          seat.pad.id = id;
          connect(seat);
        }
      }
      const ops = mapInput(msg);
      if (!ops) return false; // unmapped for a pad -> let the synthetic path have it
      if (!seat.connected) return true; // consumed (no double input) but the seat isn't joined
      if (ops.length === 0) return true;

      const arrival = now();
      const hasClock = typeof msg.t === 'number';
      let at = arrival;
      let stamp: number | null = null;
      if (hasClock) {
        const t = msg.t as number;
        const off = arrival - t;
        seat.minOff = seat.minOff === null ? off : Math.min(seat.minOff, off);
        at = t + seat.minOff + D;
        stamp = t + seat.minOff;
      }
      // Release clamp: a late press must never shorten the press (see header).
      for (const op of ops) {
        if (op.kind !== 'button' || op.down) continue;
        if (msg.phase === 'cancel') continue;
        const pressAt = seat.pressAt.get(op.index);
        const pressT = seat.pressT.get(op.index);
        const dur = msg.heldMs ?? (hasClock && pressT !== undefined ? (msg.t as number) - pressT : 0);
        // MIN_PRESS_MS: a 0 ms step (the phone d-pad's click = start+end at one `t`) would apply down
        // and up in the same tick and a rAF-polling game would never see it pressed.
        if (pressAt !== undefined) at = Math.max(at, pressAt + Math.max(dur, MIN_PRESS_MS));
      }
      at = Math.max(at, seat.lastAt); // FIFO per seat
      seat.lastAt = at;
      for (const op of ops) {
        if (op.kind === 'releaseAll') {
          seat.pressAt.clear();
          seat.pressT.clear();
          continue;
        }
        if (op.kind !== 'button') continue;
        if (op.down) {
          seat.pressAt.set(op.index, at);
          if (hasClock) seat.pressT.set(op.index, msg.t as number);
        } else {
          seat.pressAt.delete(op.index);
          seat.pressT.delete(op.index);
        }
      }

      const q: Queued = { at, ops, stamp };
      if (at <= arrival && seat.queue.length === 0) {
        applyOps(seat, q);
        return true;
      }
      seat.queue.push(q);
      arm(seat);
      return true;
    },

    dispose(): void {
      for (const seat of seats.values()) clearSeatQueue(seat);
      if (hadOwn) {
        Object.defineProperty(win.navigator, 'getGamepads', { value: original, configurable: true, writable: true });
      } else {
        delete nav.getGamepads;
      }
      if (holder.__spGamepadShim === shim) delete holder.__spGamepadShim;
    },
  };
  holder.__spGamepadShim = shim;
  return shim;
}