From deaed5ad70e98287bc10de6f36f99d40b6b67ef9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 21 Oct 2026 23:00:18 +0000
Subject: [PATCH 1/4] Add Gamepad actions, and rebinding for keyboard and
 gamepad

Games had keyboard, pointer, and touch input but no controllers, and
bindings were fixed when the actions were made, so players could not
remap them. Gamepad follows Keyboard's shape (named actions, edges,
idle/scripted/recording/parseTimeline) and adds the sticks, triggers,
and every button by name for menus and settings screens. rebind() keeps
the action names and swaps the keys or buttons.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015qkEJzyV5DVhoLVDMmoWJh
---
 .changeset/gamepad-actions.md            |   9 +
 packages/browser/README.md               |   2 +-
 packages/browser/dtslint/Gamepad.tst.ts  |  38 ++
 packages/browser/dtslint/Keyboard.tst.ts |   8 +
 packages/browser/package.json            |   3 +-
 packages/browser/src/Gamepad.ts          | 497 +++++++++++++++++++++++
 packages/browser/src/Keyboard.ts         |  51 ++-
 packages/browser/src/index.ts            |   1 +
 packages/browser/test/Gamepad.test.ts    | 247 +++++++++++
 packages/browser/test/Keyboard.test.ts   |  41 ++
 10 files changed, 883 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/gamepad-actions.md
 create mode 100644 packages/browser/dtslint/Gamepad.tst.ts
 create mode 100644 packages/browser/src/Gamepad.ts
 create mode 100644 packages/browser/test/Gamepad.test.ts

diff --git a/.changeset/gamepad-actions.md b/.changeset/gamepad-actions.md
new file mode 100644
index 00000000..f66c886e
--- /dev/null
+++ b/.changeset/gamepad-actions.md
@@ -0,0 +1,9 @@
+---
+"@typeonce/ritmo-browser": minor
+---
+
+**`Gamepad` reads controllers as named actions, and keyboard and gamepad bindings can change at runtime.**
+
+- **`Gamepad.actions(navigator, bindings, options)`** binds actions to buttons named by the browser's standard mapping (`"south"`, `"west"`, `"rightTrigger"`, `"dpadUp"`, `"start"`...). Each snapshot has `actions` (as `Keyboard`'s), every `buttons` state by name whatever the bindings (for menu navigation and for a settings screen waiting for the button to bind), the `left` and `right` sticks with a radial dead zone (`y` grows down, as `Touch`'s stick), how far each trigger is pulled, and the followed pad's `id`. It follows the pad used last and releases everything held when that pad disconnects. Call `poll()` each animation frame so taps shorter than an update count. `Gamepad.idle`, `scripted`, `recording`, `parseTimeline`, and `isButton` match the other devices; timelines name buttons, so a replay follows the bindings.
+- **`rebind(bindings)`** on `Keyboard.actions(...)` and `Gamepad.actions(...)` binds the same actions to new keys or buttons, for players who remap their controls. An action held only through a key it lost reports `released`. Scripted keyboard actions ignore it (their timeline names actions).
+- **Breaking for hand-written sources:** `Keyboard.Actions` now requires `rebind`. An object implementing it by hand adds `rebind() {}`.
diff --git a/packages/browser/README.md b/packages/browser/README.md
index fe9968ca..1aef15fd 100644
--- a/packages/browser/README.md
+++ b/packages/browser/README.md
@@ -1,6 +1,6 @@
 # `@typeonce/ritmo-browser`
 
-Browser integrations for ritmo: animation frames as a tick source for the core fixed-step loop (`BrowserTickSource`), keyboard actions with press/release edges, bound by character or by physical key (`Keyboard`), mouse and pen position and button edges over an element (`Pointer`), on-screen touch controls with a floating stick and drag-to-aim buttons (`Touch`), scripted and recorded keyboard and pointer timelines for tests and replays, and a system that copies input into a resource (`InputCapture`).
+Browser integrations for ritmo: animation frames as a tick source for the core fixed-step loop (`BrowserTickSource`), keyboard actions with press/release edges, bound by character or by physical key (`Keyboard`), gamepad actions by standard-mapping button names plus the sticks and triggers (`Gamepad`), both rebindable at runtime for a controls settings screen, mouse and pen position and button edges over an element (`Pointer`), on-screen touch controls with a floating stick and drag-to-aim buttons (`Touch`), scripted and recorded keyboard, pointer, and gamepad timelines for tests and replays, and a system that copies input into a resource (`InputCapture`).
 
 ```sh
 pnpm add @typeonce/ritmo-browser @typeonce/ritmo
diff --git a/packages/browser/dtslint/Gamepad.tst.ts b/packages/browser/dtslint/Gamepad.tst.ts
new file mode 100644
index 00000000..e8db7962
--- /dev/null
+++ b/packages/browser/dtslint/Gamepad.tst.ts
@@ -0,0 +1,38 @@
+import { Gamepad } from "@typeonce/ritmo-browser"
+import { describe, expect, it } from "tstyche"
+
+declare const host: Gamepad.GamepadHost
+
+describe("Gamepad", () => {
+  it("types snapshot actions by the bound action names", () => {
+    const input = Gamepad.actions(host, { attack: ["west"], dash: ["south", "rightBumper"] })
+    expect(input.snapshot().actions.attack.pressed).type.toBe<boolean>()
+    expect(input.snapshot().buttons.dpadUp.held).type.toBe<boolean>()
+    expect(input.snapshot().left).type.toBe<Gamepad.Vector>()
+    // @ts-expect-error Property 'jump' does not exist
+    input.snapshot().actions.jump
+  })
+
+  it("binds only standard mapping buttons, at least one per action", () => {
+    // @ts-expect-error Type '"A"' is not assignable to type
+    Gamepad.actions(host, { attack: ["A"] })
+    // @ts-expect-error Type '[]' is not assignable to type 'readonly [
+    Gamepad.actions(host, { attack: [] })
+  })
+
+  it("rebinds the same actions only", () => {
+    const input = Gamepad.actions(host, { attack: ["west"], dash: ["south"] })
+    expect(input.rebind).type.toBeCallableWith({ attack: ["north"], dash: ["east"] })
+    expect(input.rebind).type.not.toBeCallableWith({ attack: ["north"] })
+    expect(input.rebind).type.not.toBeCallableWith({ attack: ["north"], dash: ["east"], jump: ["south"] })
+  })
+
+  it("accepts the browser's navigator as a host", () => {
+    expect<Navigator>().type.toBeAssignableTo<Gamepad.GamepadHost>()
+  })
+
+  it("narrows stored names with isButton", () => {
+    const name: unknown = "south"
+    if (Gamepad.isButton(name)) expect(name).type.toBe<Gamepad.Button>()
+  })
+})
diff --git a/packages/browser/dtslint/Keyboard.tst.ts b/packages/browser/dtslint/Keyboard.tst.ts
index 1547cbbe..33cd53c7 100644
--- a/packages/browser/dtslint/Keyboard.tst.ts
+++ b/packages/browser/dtslint/Keyboard.tst.ts
@@ -28,3 +28,11 @@ describe("Keyboard", () => {
     Keyboard.actions(host, { jump: [] })
   })
 })
+
+describe("Keyboard.rebind", () => {
+  it("rebinds the same actions only", () => {
+    const input = Keyboard.actions(host, { jump: [" "], left: ["a"] })
+    expect(input.rebind).type.toBeCallableWith({ jump: [Keyboard.code("KeyJ")], left: ["ArrowLeft"] })
+    expect(input.rebind).type.not.toBeCallableWith({ jump: ["j"] })
+  })
+})
diff --git a/packages/browser/package.json b/packages/browser/package.json
index f5cf2d45..a487ee8a 100644
--- a/packages/browser/package.json
+++ b/packages/browser/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@typeonce/ritmo-browser",
   "version": "0.10.0",
-  "description": "Browser fixed-step loop, keyboard actions, and input capture for Ritmo",
+  "description": "Browser fixed-step loop, keyboard and gamepad actions, and input capture for Ritmo",
   "author": "Sandro Maglione",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,7 @@
     "ritmo",
     "browser",
     "keyboard",
+    "gamepad",
     "game-loop"
   ],
   "type": "module",
diff --git a/packages/browser/src/Gamepad.ts b/packages/browser/src/Gamepad.ts
new file mode 100644
index 00000000..31d9c8fa
--- /dev/null
+++ b/packages/browser/src/Gamepad.ts
@@ -0,0 +1,497 @@
+/**
+ * Gamepad input as caller-named actions, plus the sticks and triggers.
+ *
+ * Games bind actions to buttons once and read one snapshot per update, as
+ * with `Keyboard`. The module owns the plumbing every game rewrites: polling
+ * (the Gamepad API has no button events), press/release edges, a radial dead
+ * zone on the sticks, following the pad that was used last when several are
+ * connected, and releasing everything held when a pad disconnects. It does
+ * not know about the ECS; `InputCapture.system(...)` copies snapshots from a
+ * service into a resource.
+ *
+ * Buttons are named by their place in the browser's standard mapping
+ * (`"south"` is A on Xbox, Cross on PlayStation, B on Nintendo), so bindings
+ * stay the same on every pad. A pad whose `mapping` is not `"standard"` is
+ * read by the same indices, which may not match its labels: let players
+ * remap (`rebind`). The snapshot also reports every `button` by name,
+ * whatever the bindings, for fixed menu navigation and for a settings screen
+ * that waits for the button to bind.
+ *
+ * Polling happens on every `snapshot()`. A press and release that both fall
+ * between two snapshots is missed unless the host also calls `poll()` more
+ * often (each animation frame, for example). Browsers expose a pad only after
+ * a button is pressed on it, and only in a secure context (HTTPS or
+ * localhost); elsewhere `navigator.getGamepads` is missing, and a game uses
+ * `scripted(bindings, [])` as an idle stand-in.
+ *
+ * @module Gamepad
+ * @docGroup browser
+ *
+ * @example
+ * ```ts
+ * const pad = Gamepad.actions(navigator, {
+ *   attack: ["west"],
+ *   dash: ["south"],
+ *   pause: ["start"]
+ * })
+ *
+ * // Each animation frame (optional), so taps shorter than an update count:
+ * pad.poll()
+ *
+ * // Once per update:
+ * const snapshot = pad.snapshot()
+ * move(snapshot.left)
+ * if (snapshot.actions.attack.pressed) attack()
+ *
+ * // In a settings screen, rebinding keeps the action names:
+ * pad.rebind({ attack: ["north"], dash: ["south"], pause: ["start"] })
+ * ```
+ *
+ * For tests, replays, and headless runs, `scripted(...)` plays a timeline of
+ * button presses, releases, and stick moves instead of polling a host, and
+ * `recording(...)` wraps live actions to capture the timeline a session
+ * produced. `parseTimeline(...)` validates a timeline loaded from JSON.
+ */
+import * as Result from "@typeonce/ritmo/Result"
+
+import type { ActionState } from "./Keyboard.ts"
+
+/**
+ * The buttons of the browser's standard mapping, in index order: face
+ * buttons by compass position, bumpers and triggers, the two small center
+ * buttons, the stick clicks, the d-pad, and the home button.
+ */
+export const buttonNames = [
+  "south",
+  "east",
+  "west",
+  "north",
+  "leftBumper",
+  "rightBumper",
+  "leftTrigger",
+  "rightTrigger",
+  "select",
+  "start",
+  "leftStick",
+  "rightStick",
+  "dpadUp",
+  "dpadDown",
+  "dpadLeft",
+  "dpadRight",
+  "home"
+] as const
+
+/** One button of the standard mapping, see {@link buttonNames}. */
+export type Button = (typeof buttonNames)[number]
+
+/**
+ * Action name to the buttons that trigger it. Every action needs at least
+ * one button.
+ */
+export type Bindings = Readonly<Record<string, readonly [Button, ...Array<Button>]>>
+
+/** New buttons for the same actions, for {@link Actions.rebind}. */
+export type Rebinding<B extends Bindings> = { readonly [Action in keyof B]: readonly [Button, ...Array<Button>] }
+
+/** One button's reading, the subset of the browser's `GamepadButton` the module reads. */
+export interface ButtonReading {
+  readonly pressed: boolean
+  readonly value: number
+}
+
+/** One pad's reading, the subset of the browser's `Gamepad` the module reads. */
+export interface PadReading {
+  readonly id: string
+  readonly index: number
+  readonly connected: boolean
+  readonly mapping: string
+  readonly buttons: ReadonlyArray<ButtonReading>
+  readonly axes: ReadonlyArray<number>
+}
+
+/** Where pads are read from, usually `navigator`. */
+export interface GamepadHost {
+  getGamepads(): ReadonlyArray<PadReading | null>
+}
+
+/** A stick's tilt with the dead zone removed: zero at rest, length 1 at full tilt. `y` grows down, as on screen. */
+export interface Vector {
+  readonly x: number
+  readonly y: number
+}
+
+export interface Snapshot<B extends Bindings> {
+  /** Every bound action's state. */
+  readonly actions: { readonly [Action in keyof B]: ActionState }
+  /** Every button's state by name, whatever the bindings. */
+  readonly buttons: { readonly [Name in Button]: ActionState }
+  readonly left: Vector
+  readonly right: Vector
+  /** How far each trigger is pulled, 0 to 1. */
+  readonly leftTrigger: number
+  readonly rightTrigger: number
+  /** Whether a pad is being followed. */
+  readonly connected: boolean
+  /** The followed pad's `id` (it names the maker, for button labels), or `null`. */
+  readonly id: string | null
+}
+
+export interface Actions<B extends Bindings> {
+  /** Returns the input state and starts a new press/release window. */
+  snapshot(): Snapshot<B>
+  /** Reads the pads now, so a press shorter than one update still counts. `snapshot()` polls too. */
+  poll(): void
+  /**
+   * Binds the same actions to new buttons, from the next snapshot. An action
+   * held only through buttons it lost reports `released`.
+   */
+  rebind(bindings: Rebinding<B>): void
+  /** Stops reading pads. */
+  dispose(): void
+}
+
+export interface ActionsOptions {
+  /** Fraction of a stick's tilt that reads as zero. Defaults to 0.15. */
+  readonly deadZone?: number
+  /** How far a trigger is pulled before it counts as held. Defaults to 0.5. */
+  readonly triggerThreshold?: number
+}
+
+const idleState: ActionState = { held: false, pressed: false, released: false }
+const zero: Vector = { x: 0, y: 0 }
+
+const idleButtons = (): Snapshot<Bindings>["buttons"] => {
+  const buttons = {} as Record<Button, ActionState>
+  for (const name of buttonNames) buttons[name] = idleState
+  return buttons
+}
+
+/**
+ * A snapshot with nothing held and no pad, for initializing an input
+ * resource before the first capture.
+ */
+export const idle = <const B extends Bindings>(bindings: B): Snapshot<B> => {
+  const actions = {} as Record<keyof B, ActionState>
+  for (const name of Object.keys(bindings) as Array<keyof B>) actions[name] = idleState
+  return { actions, buttons: idleButtons() as Snapshot<B>["buttons"], left: zero, right: zero, leftTrigger: 0, rightTrigger: 0, connected: false, id: null }
+}
+
+/** Removes the dead zone and rescales, so the stick goes from zero to full tilt smoothly. */
+const stick = (x: number, y: number, deadZone: number): Vector => {
+  const length = Math.sqrt(x * x + y * y)
+  if (length <= deadZone) return zero
+  const scaled = Math.min(1, (length - deadZone) / (1 - deadZone))
+  return { x: (x / length) * scaled, y: (y / length) * scaled }
+}
+
+/**
+ * The held buttons and the edges since the previous snapshot, shared by live
+ * and scripted actions so both build snapshots the same way.
+ */
+const tracker = <B extends Bindings>(initial: B) => {
+  let bindings: Rebinding<B> = initial
+  let names = Object.keys(initial) as Array<keyof B & string>
+  const held = new Set<Button>()
+  const pressed = new Set<Button>()
+  const released = new Set<Button>()
+  /** Actions that lost their held buttons in a rebind, reported released on the next snapshot. */
+  const droppedActions = new Set<keyof B>()
+  const isHeld = (name: keyof B & string): boolean => bindings[name]!.some((button) => held.has(button))
+  return {
+    held,
+    down(button: Button) {
+      if (held.has(button)) return
+      held.add(button)
+      pressed.add(button)
+    },
+    up(button: Button) {
+      if (held.delete(button)) released.add(button)
+    },
+    upAll() {
+      for (const button of held) released.add(button)
+      held.clear()
+    },
+    rebind(next: Rebinding<B>) {
+      const before = names.filter(isHeld)
+      bindings = next
+      names = Object.keys(next) as Array<keyof B & string>
+      for (const name of before) if (!isHeld(name)) droppedActions.add(name)
+    },
+    snapshot(analog: Pick<Snapshot<B>, "left" | "right" | "leftTrigger" | "rightTrigger" | "connected" | "id">): Snapshot<B> {
+      const buttons = {} as Record<Button, ActionState>
+      for (const name of buttonNames) {
+        const isDown = held.has(name)
+        buttons[name] = isDown || pressed.has(name) || released.has(name)
+          ? { held: isDown, pressed: pressed.has(name), released: released.has(name) && !isDown }
+          : idleState
+      }
+      const actions = {} as Record<keyof B, ActionState>
+      for (const name of names) {
+        const bound = bindings[name]!
+        const isDown = bound.some((button) => held.has(button))
+        actions[name] = {
+          held: isDown,
+          pressed: bound.some((button) => pressed.has(button)),
+          released: !isDown && (droppedActions.has(name) || bound.some((button) => released.has(button)))
+        }
+      }
+      pressed.clear()
+      released.clear()
+      droppedActions.clear()
+      return { actions, buttons, ...analog }
+    }
+  }
+}
+
+/** Whether a pad is being touched: a button down or a stick past the dead zone. */
+const inUse = (pad: PadReading, deadZone: number, triggerThreshold: number): boolean =>
+  pad.buttons.some((button, index) => isDown(button, index, triggerThreshold)) ||
+  // Only the sticks' axes: some pads report their triggers as extra axes resting at -1.
+  pad.axes.slice(0, 4).some((axis) => Math.abs(axis) > deadZone)
+
+const triggerIndices = new Set([6, 7])
+
+const isDown = (button: ButtonReading, index: number, triggerThreshold: number): boolean =>
+  triggerIndices.has(index) ? button.value >= triggerThreshold : button.pressed
+
+/** Reads the pads, treating a host that throws (a blocked permission policy) as having none. */
+const readPads = (host: GamepadHost): ReadonlyArray<PadReading | null> => {
+  try {
+    return host.getGamepads()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Starts reading pads from `host`. With several pads connected it follows
+ * the one used last; a pad that disconnects releases everything it held.
+ */
+export const actions = <const B extends Bindings>(host: GamepadHost, bindings: B, options: ActionsOptions = {}): Actions<B> => {
+  const deadZone = options.deadZone ?? 0.15
+  const triggerThreshold = options.triggerThreshold ?? 0.5
+  const state = tracker(bindings)
+  let followed: number | null = null
+  let disposed = false
+  let reading: PadReading | null = null
+
+  const poll = (): void => {
+    if (disposed) return
+    const pads = readPads(host).filter((pad): pad is PadReading => pad !== null && pad.connected)
+    const current = pads.find((pad) => pad.index === followed)
+    // Keep the followed pad while it is in use; otherwise switch to another one being used, or keep the first there is.
+    const used = current !== undefined && inUse(current, deadZone, triggerThreshold)
+      ? current
+      : pads.find((pad) => pad.index !== followed && inUse(pad, deadZone, triggerThreshold))
+    const next = used ?? current ?? pads[0]
+    if (next?.index !== followed) state.upAll()
+    followed = next?.index ?? null
+    reading = next ?? null
+    if (next === undefined) return
+    for (let index = 0; index < buttonNames.length; index++) {
+      const button = next.buttons[index]
+      const name = buttonNames[index]!
+      if (button !== undefined && isDown(button, index, triggerThreshold)) state.down(name)
+      else state.up(name)
+    }
+  }
+
+  return {
+    snapshot() {
+      poll()
+      const pad = reading
+      if (pad === null) return state.snapshot({ left: zero, right: zero, leftTrigger: 0, rightTrigger: 0, connected: false, id: null })
+      const axis = (index: number) => pad.axes[index] ?? 0
+      const trigger = (index: number) => Math.min(1, Math.max(0, pad.buttons[index]?.value ?? 0))
+      return state.snapshot({
+        left: stick(axis(0), axis(1), deadZone),
+        right: stick(axis(2), axis(3), deadZone),
+        leftTrigger: trigger(6),
+        rightTrigger: trigger(7),
+        connected: true,
+        id: pad.id
+      })
+    },
+    poll,
+    rebind: state.rebind,
+    dispose() {
+      disposed = true
+      reading = null
+      state.upAll()
+    }
+  }
+}
+
+/**
+ * Input changes applied just before one snapshot: presses first, then
+ * releases, then the sticks and triggers, which keep their value until set
+ * again. `frame` is the snapshot's index, counting from 0 at the first
+ * `snapshot()` call. A button both pressed and released in one frame is a
+ * tap shorter than a frame.
+ */
+export interface TimelineEntry {
+  readonly frame: number
+  readonly press?: ReadonlyArray<Button>
+  readonly release?: ReadonlyArray<Button>
+  readonly left?: Vector
+  readonly right?: Vector
+  readonly leftTrigger?: number
+  readonly rightTrigger?: number
+}
+
+/**
+ * Input changes by snapshot index. Plain data, so it round-trips through
+ * JSON; load it back with `parseTimeline`. It names buttons, not actions, so
+ * a replay follows the bindings as live play does.
+ */
+export type Timeline = ReadonlyArray<TimelineEntry>
+
+/** Actions driven by a timeline instead of a host. */
+export interface Scripted<B extends Bindings> extends Actions<B> {
+  /** Number of snapshots taken so far, which is the next frame index. */
+  readonly frames: () => number
+}
+
+/**
+ * Plays `timeline`: before the snapshot at index `frame`, every entry for
+ * that frame is applied. A pad counts as connected from the first entry on.
+ * Buttons stay held from their press until their release; pressing a held
+ * button is not a new press.
+ */
+export const scripted = <const B extends Bindings>(bindings: B, timeline: Timeline): Scripted<B> => {
+  const state = tracker(bindings)
+  const byFrame = new Map<number, Array<TimelineEntry>>()
+  for (const entry of timeline) {
+    const entries = byFrame.get(entry.frame)
+    if (entries) entries.push(entry)
+    else byFrame.set(entry.frame, [entry])
+  }
+  const first = timeline.reduce((earliest, entry) => Math.min(earliest, entry.frame), Number.POSITIVE_INFINITY)
+  let analog = { left: zero, right: zero, leftTrigger: 0, rightTrigger: 0 }
+  let frame = 0
+  return {
+    snapshot() {
+      for (const entry of byFrame.get(frame) ?? []) {
+        for (const button of entry.press ?? []) state.down(button)
+        for (const button of entry.release ?? []) state.up(button)
+        analog = {
+          left: entry.left ?? analog.left,
+          right: entry.right ?? analog.right,
+          leftTrigger: entry.leftTrigger ?? analog.leftTrigger,
+          rightTrigger: entry.rightTrigger ?? analog.rightTrigger
+        }
+      }
+      const connected = frame >= first
+      frame += 1
+      return state.snapshot({ ...analog, connected, id: connected ? "scripted" : null })
+    },
+    poll() {},
+    rebind: state.rebind,
+    dispose() {},
+    frames: () => frame
+  }
+}
+
+/** Live actions that also record the timeline they produce. */
+export interface Recording<B extends Bindings> extends Actions<B> {
+  /** The recorded timeline; `scripted(bindings, timeline)` replays it exactly. */
+  readonly timeline: () => Timeline
+}
+
+const sameVector = (a: Vector, b: Vector): boolean => a.x === b.x && a.y === b.y
+
+/**
+ * Wraps `actions` and records, for every snapshot, the buttons pressed and
+ * released since the previous one and the sticks and triggers that moved.
+ */
+export const recording = <B extends Bindings>(actions: Actions<B>): Recording<B> => {
+  const entries: Array<TimelineEntry> = []
+  let previous: Pick<Snapshot<B>, "left" | "right" | "leftTrigger" | "rightTrigger"> = { left: zero, right: zero, leftTrigger: 0, rightTrigger: 0 }
+  let frame = 0
+  return {
+    snapshot() {
+      const snapshot = actions.snapshot()
+      const press = buttonNames.filter((name) => snapshot.buttons[name].pressed)
+      const release = buttonNames.filter((name) => snapshot.buttons[name].released)
+      const entry: Record<string, unknown> = {
+        ...(press.length > 0 ? { press } : {}),
+        ...(release.length > 0 ? { release } : {}),
+        ...(sameVector(snapshot.left, previous.left) ? {} : { left: snapshot.left }),
+        ...(sameVector(snapshot.right, previous.right) ? {} : { right: snapshot.right }),
+        ...(snapshot.leftTrigger === previous.leftTrigger ? {} : { leftTrigger: snapshot.leftTrigger }),
+        ...(snapshot.rightTrigger === previous.rightTrigger ? {} : { rightTrigger: snapshot.rightTrigger })
+      }
+      // The first entry also marks when a pad appeared, so a replay connects on the same frame.
+      if (Object.keys(entry).length > 0 || (entries.length === 0 && snapshot.connected)) entries.push({ frame, ...entry })
+      previous = snapshot
+      frame += 1
+      return snapshot
+    },
+    poll: () => actions.poll(),
+    rebind: (bindings) => actions.rebind(bindings),
+    dispose: () => actions.dispose(),
+    timeline: () => [...entries]
+  }
+}
+
+/**
+ * Why loaded data is not a timeline. `path` points at the offending value,
+ * for example `[3].press[0]`.
+ */
+export interface InvalidTimeline {
+  readonly _tag: "InvalidTimeline"
+  readonly path: string
+  readonly message: string
+}
+
+const buttonSet: ReadonlySet<string> = new Set(buttonNames)
+
+/** Whether `name` is a button of the standard mapping, for validating stored bindings. */
+export const isButton = (name: unknown): name is Button => typeof name === "string" && buttonSet.has(name)
+
+/**
+ * Validates untrusted data, such as a parsed JSON file, as a timeline: an
+ * array of entries with a non-negative integer `frame`, optional
+ * `press`/`release` arrays of button names, optional `left`/`right` vectors
+ * of length at most 1, and optional triggers from 0 to 1.
+ */
+export const parseTimeline = (data: unknown): Result.Result<Timeline, InvalidTimeline> => {
+  const invalid = (path: string, message: string) => Result.failure<InvalidTimeline>({ _tag: "InvalidTimeline", path, message })
+  if (!Array.isArray(data)) return invalid("", "expected an array of entries")
+  const entries: Array<TimelineEntry> = []
+  for (let index = 0; index < data.length; index++) {
+    const entry: unknown = data[index]
+    const path = `[${index}]`
+    if (typeof entry !== "object" || entry === null) return invalid(path, "expected an object")
+    const fields = entry as Readonly<Record<string, unknown>>
+    const frame = fields["frame"]
+    if (typeof frame !== "number" || !Number.isInteger(frame) || frame < 0) return invalid(`${path}.frame`, "expected a non-negative integer")
+    const parsed: Record<string, unknown> = { frame }
+    for (const field of ["press", "release"] as const) {
+      const value = fields[field]
+      if (value === undefined) continue
+      if (!Array.isArray(value)) return invalid(`${path}.${field}`, "expected an array of button names")
+      for (let offset = 0; offset < value.length; offset++) {
+        if (!isButton(value[offset])) return invalid(`${path}.${field}[${offset}]`, `expected one of ${buttonNames.join(", ")}`)
+      }
+      parsed[field] = [...value]
+    }
+    for (const field of ["left", "right"] as const) {
+      const value = fields[field]
+      if (value === undefined) continue
+      const { x, y } = (typeof value === "object" && value !== null ? value : {}) as { readonly x?: unknown; readonly y?: unknown }
+      if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y) || x * x + y * y > 1 + 1e-9) {
+        return invalid(`${path}.${field}`, "expected { x, y } of length at most 1")
+      }
+      parsed[field] = { x, y }
+    }
+    for (const field of ["leftTrigger", "rightTrigger"] as const) {
+      const value = fields[field]
+      if (value === undefined) continue
+      if (typeof value !== "number" || !(value >= 0 && value <= 1)) return invalid(`${path}.${field}`, "expected a number from 0 to 1")
+      parsed[field] = value
+    }
+    entries.push(parsed as unknown as TimelineEntry)
+  }
+  return Result.success(entries)
+}
diff --git a/packages/browser/src/Keyboard.ts b/packages/browser/src/Keyboard.ts
index 89d35f9f..23d96d98 100644
--- a/packages/browser/src/Keyboard.ts
+++ b/packages/browser/src/Keyboard.ts
@@ -132,11 +132,21 @@ export type Snapshot<B extends Bindings> = {
   readonly [Action in keyof B]: ActionState
 }
 
+/** New keys for the same actions, for {@link Actions.rebind}. */
+export type Rebinding<B extends Bindings> = { readonly [Action in keyof B]: readonly [KeyBinding, ...Array<KeyBinding>] }
+
 export interface Actions<B extends Bindings> {
   /**
    * Returns every action's state and starts a new press/release window.
    */
   snapshot(): Snapshot<B>
+  /**
+   * Binds the same actions to new keys, from the next snapshot, for a
+   * settings screen where players remap controls. An action held only
+   * through keys it lost reports `released`; a key held across the rebind
+   * that is newly bound counts once it is pressed again.
+   */
+  rebind(bindings: Rebinding<B>): void
   /**
    * Removes the event listeners.
    */
@@ -175,20 +185,25 @@ const bindingToken = (binding: KeyBinding): string => typeof binding === "string
  */
 export const actions = <const B extends Bindings>(
   host: KeyboardHost,
-  bindings: B,
+  initial: B,
   options: ActionsOptions = {}
 ): Actions<B> => {
   const preventDefault = options.preventDefault ?? true
-  const names = Object.keys(bindings) as Array<keyof B & string>
+  let bindings: Rebinding<B> = initial
+  let names = Object.keys(initial) as Array<keyof B & string>
   const actionsByToken = new Map<string, Array<keyof B & string>>()
-  for (const name of names) {
-    for (const binding of bindings[name]!) {
-      const token = bindingToken(binding)
-      const bound = actionsByToken.get(token)
-      if (bound) bound.push(name)
-      else actionsByToken.set(token, [name])
+  const index = (): void => {
+    actionsByToken.clear()
+    for (const name of names) {
+      for (const binding of bindings[name]!) {
+        const token = bindingToken(binding)
+        const bound = actionsByToken.get(token)
+        if (bound) bound.push(name)
+        else actionsByToken.set(token, [name])
+      }
     }
   }
+  index()
 
   const heldTokens = new Set<string>()
   /**
@@ -227,15 +242,15 @@ export const actions = <const B extends Bindings>(
       tokens.push(codeToken(event.code))
     }
     for (const token of tokens) {
-      const bound = actionsByToken.get(token)
-      if (!bound || !heldTokens.delete(token)) continue
-      for (const name of bound) released.add(name)
+      // A key stays tracked while held even if a rebind unbound it, so its release is still seen.
+      if (!heldTokens.delete(token)) continue
+      for (const name of actionsByToken.get(token) ?? []) released.add(name)
     }
   }
 
   const onBlur = (): void => {
     for (const token of heldTokens) {
-      for (const name of actionsByToken.get(token)!) released.add(name)
+      for (const name of actionsByToken.get(token) ?? []) released.add(name)
     }
     heldTokens.clear()
     keyTokenByCode.clear()
@@ -267,6 +282,13 @@ export const actions = <const B extends Bindings>(
       released.clear()
       return snapshot
     },
+    rebind(next) {
+      const before = names.filter(isHeld)
+      bindings = next
+      names = Object.keys(next) as Array<keyof B & string>
+      index()
+      for (const name of before) if (!isHeld(name)) released.add(name)
+    },
     dispose() {
       host.removeEventListener("keydown", onKeyDown)
       host.removeEventListener("keyup", onKeyUp)
@@ -339,6 +361,8 @@ export const scripted = <const B extends Bindings>(bindings: B, timeline: Timeli
       }
       return snapshot
     },
+    // A timeline names actions, not keys, so new keys change nothing.
+    rebind() {},
     dispose() {},
     frames: () => frame
   }
@@ -379,6 +403,9 @@ export const recording = <B extends Bindings>(actions: Actions<B>): Recording<B>
       frame += 1
       return snapshot
     },
+    rebind(bindings) {
+      actions.rebind(bindings)
+    },
     dispose() {
       actions.dispose()
     },
diff --git a/packages/browser/src/index.ts b/packages/browser/src/index.ts
index 85bc2b79..2b3f754b 100644
--- a/packages/browser/src/index.ts
+++ b/packages/browser/src/index.ts
@@ -1,6 +1,7 @@
 /** Browser host integrations kept outside the renderer-agnostic ECS core. */
 export * as BrowserHostClock from "./BrowserHostClock.ts"
 export * as BrowserTickSource from "./BrowserTickSource.ts"
+export * as Gamepad from "./Gamepad.ts"
 export * as InputCapture from "./InputCapture.ts"
 export * as Keyboard from "./Keyboard.ts"
 export * as Pointer from "./Pointer.ts"
diff --git a/packages/browser/test/Gamepad.test.ts b/packages/browser/test/Gamepad.test.ts
new file mode 100644
index 00000000..acd10abd
--- /dev/null
+++ b/packages/browser/test/Gamepad.test.ts
@@ -0,0 +1,247 @@
+import { describe, expect, it } from "vitest"
+
+import { Gamepad } from "@typeonce/ritmo-browser"
+
+const released = { held: false, pressed: false, released: true }
+const idle = { held: false, pressed: false, released: false }
+
+/** A pad whose buttons and axes the test sets, read by index as the standard mapping. */
+const makePad = (index = 0, id = `pad ${index}`) => {
+  const buttons = Array.from({ length: 17 }, () => ({ pressed: false, value: 0 }))
+  const axes = [0, 0, 0, 0]
+  const pad = { id, index, connected: true, mapping: "standard", buttons, axes }
+  const at = (name: Gamepad.Button) => Gamepad.buttonNames.indexOf(name)
+  return {
+    pad,
+    down: (name: Gamepad.Button) => (buttons[at(name)] = { pressed: true, value: 1 }),
+    up: (name: Gamepad.Button) => (buttons[at(name)] = { pressed: false, value: 0 }),
+    pull: (name: "leftTrigger" | "rightTrigger", value: number) => (buttons[at(name)] = { pressed: value > 0.1, value }),
+    tilt: (stick: "left" | "right", x: number, y: number) => {
+      const first = stick === "left" ? 0 : 2
+      axes[first] = x
+      axes[first + 1] = y
+    }
+  }
+}
+
+const makeHost = (...pads: Array<ReturnType<typeof makePad>>) => {
+  const connected: Array<Gamepad.PadReading | null> = pads.map(({ pad }) => pad)
+  const host: Gamepad.GamepadHost = { getGamepads: () => connected }
+  return { host, connected }
+}
+
+const bindings = { attack: ["west"], dash: ["south", "rightBumper"], ultimate: ["rightTrigger"] } as const
+
+describe("Gamepad.actions", () => {
+  it("reports held state and press edges per snapshot", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings)
+
+    pad.down("west")
+    expect(input.snapshot().actions.attack).toEqual({ held: true, pressed: true, released: false })
+    expect(input.snapshot().actions.attack).toEqual({ held: true, pressed: false, released: false })
+    pad.up("west")
+    expect(input.snapshot().actions.attack).toEqual(released)
+    expect(input.snapshot().actions.dash).toEqual(idle)
+  })
+
+  it("holds an action while any of its buttons is down", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings)
+
+    pad.down("south")
+    pad.down("rightBumper")
+    input.snapshot()
+    pad.up("south")
+    expect(input.snapshot().actions.dash).toEqual({ held: true, pressed: false, released: false })
+    pad.up("rightBumper")
+    expect(input.snapshot().actions.dash).toEqual(released)
+  })
+
+  it("keeps a tap that starts and ends between two snapshots when polled", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings)
+
+    pad.down("west")
+    input.poll()
+    pad.up("west")
+
+    expect(input.snapshot().actions.attack).toEqual({ held: false, pressed: true, released: true })
+  })
+
+  it("reports every button by name, whatever the bindings", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings)
+
+    pad.down("dpadDown")
+    const snapshot = input.snapshot()
+    expect(snapshot.buttons.dpadDown).toEqual({ held: true, pressed: true, released: false })
+    expect(snapshot.buttons.start).toEqual(idle)
+  })
+
+  it("removes the stick dead zone and rescales the rest", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings, { deadZone: 0.2 })
+
+    pad.tilt("left", 0.1, -0.1)
+    expect(input.snapshot().left).toEqual({ x: 0, y: 0 })
+    pad.tilt("left", 0, 0.6)
+    expect(input.snapshot().left.y).toBeCloseTo(0.5)
+    pad.tilt("right", 1, 1)
+    const right = input.snapshot().right
+    expect(Math.hypot(right.x, right.y)).toBeCloseTo(1)
+  })
+
+  it("holds a trigger past the threshold and reports how far it is pulled", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings, { triggerThreshold: 0.6 })
+
+    pad.pull("rightTrigger", 0.4)
+    let snapshot = input.snapshot()
+    expect(snapshot.actions.ultimate.held).toBe(false)
+    expect(snapshot.rightTrigger).toBeCloseTo(0.4)
+    pad.pull("rightTrigger", 0.8)
+    snapshot = input.snapshot()
+    expect(snapshot.actions.ultimate).toEqual({ held: true, pressed: true, released: false })
+  })
+
+  it("reports no pad until one connects, and releases everything when it disconnects", () => {
+    const pad = makePad()
+    const { host, connected } = makeHost()
+    const input = Gamepad.actions(host, bindings)
+
+    expect(input.snapshot()).toEqual(Gamepad.idle(bindings))
+    connected.push(pad.pad)
+    pad.down("west")
+    expect(input.snapshot()).toMatchObject({ connected: true, id: "pad 0", actions: { attack: { held: true, pressed: true } } })
+    connected.length = 0
+    expect(input.snapshot()).toMatchObject({ connected: false, id: null, actions: { attack: released } })
+  })
+
+  it("follows the pad used last", () => {
+    const first = makePad(0)
+    const second = makePad(1)
+    const input = Gamepad.actions(makeHost(first, second).host, bindings)
+
+    first.down("west")
+    expect(input.snapshot().id).toBe("pad 0")
+    first.up("west")
+    second.tilt("left", 1, 0)
+    const snapshot = input.snapshot()
+    expect(snapshot.id).toBe("pad 1")
+    expect(snapshot.left.x).toBeCloseTo(1)
+    // While the followed pad is in use, another one does not take over.
+    first.down("south")
+    expect(input.snapshot().id).toBe("pad 1")
+  })
+
+  it("does not take resting trigger axes for use", () => {
+    const first = makePad(0)
+    const second = makePad(1)
+    second.pad.axes.push(-1, -1)
+    const input = Gamepad.actions(makeHost(first, second).host, bindings)
+
+    first.down("west")
+    input.snapshot()
+    first.up("west")
+    expect(input.snapshot().id).toBe("pad 0")
+  })
+
+  it("treats a host that throws as having no pads", () => {
+    const input = Gamepad.actions({ getGamepads: () => { throw new Error("blocked") } }, bindings)
+    expect(input.snapshot().connected).toBe(false)
+  })
+
+  it("rebinds actions, releasing one held only through buttons it lost", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings)
+
+    pad.down("west")
+    input.snapshot()
+    input.rebind({ attack: ["north"], dash: ["west"], ultimate: ["rightTrigger"] })
+    const snapshot = input.snapshot()
+    expect(snapshot.actions.attack).toEqual(released)
+    expect(snapshot.actions.dash).toEqual({ held: true, pressed: false, released: false })
+    pad.down("north")
+    expect(input.snapshot().actions.attack).toEqual({ held: true, pressed: true, released: false })
+  })
+
+  it("stops reading after dispose", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings)
+
+    pad.down("west")
+    input.snapshot()
+    input.dispose()
+    expect(input.snapshot().actions.attack).toEqual(released)
+    expect(input.snapshot().connected).toBe(false)
+  })
+})
+
+describe("Gamepad.scripted", () => {
+  it("plays presses, releases, and sticks by frame", () => {
+    const input = Gamepad.scripted(bindings, [
+      { frame: 1, press: ["west"], left: { x: 1, y: 0 } },
+      { frame: 2, release: ["west"] },
+      { frame: 3, press: ["south"], release: ["south"] }
+    ])
+
+    expect(input.snapshot().connected).toBe(false)
+    let snapshot = input.snapshot()
+    expect(snapshot).toMatchObject({ connected: true, left: { x: 1, y: 0 }, actions: { attack: { held: true, pressed: true } } })
+    snapshot = input.snapshot()
+    expect(snapshot.actions.attack).toEqual(released)
+    expect(snapshot.left).toEqual({ x: 1, y: 0 })
+    expect(input.snapshot().actions.dash).toEqual({ held: false, pressed: true, released: true })
+    expect(input.frames()).toBe(4)
+  })
+
+  it("follows the bindings, so a rebind changes what a replay does", () => {
+    const input = Gamepad.scripted(bindings, [{ frame: 0, press: ["north"] }])
+    input.rebind({ attack: ["north"], dash: ["south"], ultimate: ["rightTrigger"] })
+    expect(input.snapshot().actions.attack.pressed).toBe(true)
+  })
+})
+
+describe("Gamepad.recording", () => {
+  it("records a timeline that replays the same snapshots", () => {
+    const pad = makePad()
+    const live = Gamepad.recording(Gamepad.actions(makeHost(pad).host, bindings))
+    const seen: Array<Gamepad.Snapshot<typeof bindings>> = []
+
+    seen.push(live.snapshot())
+    pad.down("west")
+    pad.tilt("left", 0, 1)
+    seen.push(live.snapshot())
+    pad.up("west")
+    pad.pull("rightTrigger", 1)
+    seen.push(live.snapshot())
+
+    const parsed = Gamepad.parseTimeline(JSON.parse(JSON.stringify(live.timeline())))
+    expect(parsed.ok).toBe(true)
+    if (!parsed.ok) return
+    const replay = Gamepad.scripted(bindings, parsed.value)
+    for (const snapshot of seen) {
+      const { id: _, ...rest } = replay.snapshot()
+      const { id: __, ...expected } = snapshot
+      expect(rest).toEqual(expected)
+    }
+  })
+})
+
+describe("Gamepad.parseTimeline", () => {
+  it("names the offending value", () => {
+    expect(Gamepad.parseTimeline([{ frame: 0, press: ["jump"] }])).toMatchObject({ ok: false, error: { path: "[0].press[0]" } })
+    expect(Gamepad.parseTimeline([{ frame: -1 }])).toMatchObject({ ok: false, error: { path: "[0].frame" } })
+    expect(Gamepad.parseTimeline([{ frame: 0, left: { x: 2, y: 0 } }])).toMatchObject({ ok: false, error: { path: "[0].left" } })
+    expect(Gamepad.parseTimeline([{ frame: 0, rightTrigger: 2 }])).toMatchObject({ ok: false, error: { path: "[0].rightTrigger" } })
+    expect(Gamepad.parseTimeline({})).toMatchObject({ ok: false, error: { path: "" } })
+  })
+})
+
+describe("Gamepad.isButton", () => {
+  it("accepts standard mapping names only", () => {
+    expect(Gamepad.isButton("south")).toBe(true)
+    expect(Gamepad.isButton("A")).toBe(false)
+  })
+})
diff --git a/packages/browser/test/Keyboard.test.ts b/packages/browser/test/Keyboard.test.ts
index 2565ce0c..9ac8392c 100644
--- a/packages/browser/test/Keyboard.test.ts
+++ b/packages/browser/test/Keyboard.test.ts
@@ -195,3 +195,44 @@ describe("Keyboard physical keys", () => {
     expect(fake.prevented).toEqual(["k", " "])
   })
 })
+
+describe("Keyboard.rebind", () => {
+  it("binds the same actions to new keys from the next snapshot", () => {
+    const fake = makeHost()
+    const input = Keyboard.actions(fake.host, { jump: [" "], dash: ["Shift"] })
+
+    input.rebind({ jump: [Keyboard.code("KeyJ")], dash: [" "] })
+    fake.downCode("j", "KeyJ")
+    fake.down(" ")
+    const snapshot = input.snapshot()
+    expect(snapshot.jump).toEqual({ held: true, pressed: true, released: false })
+    expect(snapshot.dash).toEqual({ held: true, pressed: true, released: false })
+  })
+
+  it("releases an action held only through keys it lost, and still sees the old key go up", () => {
+    const fake = makeHost()
+    const input = Keyboard.actions(fake.host, { jump: [" "], crouch: ["c"] })
+
+    fake.down(" ")
+    input.snapshot()
+    input.rebind({ jump: ["w"], crouch: [" "] })
+    const snapshot = input.snapshot()
+    expect(snapshot.jump).toEqual({ held: false, pressed: false, released: true })
+    expect(snapshot.crouch).toEqual({ held: true, pressed: false, released: false })
+    fake.up(" ")
+    expect(input.snapshot().crouch).toEqual({ held: false, pressed: false, released: true })
+  })
+
+  it("keeps a recording's timeline by action, so a rebind does not change a replay", () => {
+    const fake = makeHost()
+    const bindings = { jump: [" "] } as const
+    const recorder = Keyboard.recording(Keyboard.actions(fake.host, bindings))
+
+    recorder.rebind({ jump: ["w"] })
+    fake.down("w")
+    recorder.snapshot()
+    const replay = Keyboard.scripted(bindings, recorder.timeline())
+    replay.rebind({ jump: ["x"] })
+    expect(replay.snapshot().jump.pressed).toBe(true)
+  })
+})

From c77a24f843cc65541c621ed6fbc751155fad3796 Mon Sep 17 00:00:00 2001
From: SandroMaglione <lass.maglio@gmail.com>
Date: Thu, 22 Oct 2026 19:07:15 +0900
Subject: [PATCH 2/4] Require a fresh press after rebind, capture keys, parse
 saved bindings

- rebind keeps the actions the source was made with, so a rebinding
  object with extra keys can no longer add actions at runtime.
- A key or button held across a rebind holds a newly bound action only
  after a fresh press, on both devices, so an action never turns held
  without a press.
- Timelines play an entry naming a held action or button in both press
  and release as a release then a new press, and recordings emit it, so
  a release and press inside one update replays exactly.
- Keyboard.presses(host) reports every key press for a settings screen
  waiting for the key to bind.
- Keyboard.parseRebinding and Gamepad.parseRebinding validate saved
  bindings into a Result ready for rebind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/gamepad-actions.md            |   5 +-
 packages/browser/README.md               |   2 +-
 packages/browser/dtslint/Gamepad.tst.ts  |  20 +++
 packages/browser/dtslint/Keyboard.tst.ts |  27 ++++
 packages/browser/src/Gamepad.ts          | 153 +++++++++++++++-----
 packages/browser/src/Keyboard.ts         | 175 ++++++++++++++++++++---
 packages/browser/test/Gamepad.test.ts    |  86 ++++++++++-
 packages/browser/test/Keyboard.test.ts   |  94 +++++++++++-
 8 files changed, 504 insertions(+), 58 deletions(-)

diff --git a/.changeset/gamepad-actions.md b/.changeset/gamepad-actions.md
index f66c886e..543178f0 100644
--- a/.changeset/gamepad-actions.md
+++ b/.changeset/gamepad-actions.md
@@ -5,5 +5,8 @@
 **`Gamepad` reads controllers as named actions, and keyboard and gamepad bindings can change at runtime.**
 
 - **`Gamepad.actions(navigator, bindings, options)`** binds actions to buttons named by the browser's standard mapping (`"south"`, `"west"`, `"rightTrigger"`, `"dpadUp"`, `"start"`...). Each snapshot has `actions` (as `Keyboard`'s), every `buttons` state by name whatever the bindings (for menu navigation and for a settings screen waiting for the button to bind), the `left` and `right` sticks with a radial dead zone (`y` grows down, as `Touch`'s stick), how far each trigger is pulled, and the followed pad's `id`. It follows the pad used last and releases everything held when that pad disconnects. Call `poll()` each animation frame so taps shorter than an update count. `Gamepad.idle`, `scripted`, `recording`, `parseTimeline`, and `isButton` match the other devices; timelines name buttons, so a replay follows the bindings.
-- **`rebind(bindings)`** on `Keyboard.actions(...)` and `Gamepad.actions(...)` binds the same actions to new keys or buttons, for players who remap their controls. An action held only through a key it lost reports `released`. Scripted keyboard actions ignore it (their timeline names actions).
+- **`rebind(bindings)`** on `Keyboard.actions(...)` and `Gamepad.actions(...)` binds the same actions to new keys or buttons, for players who remap their controls. An action held only through a key it lost reports `released`; a key held across the rebind holds a newly bound action only after a fresh press, so an action never turns held without a press. Scripted keyboard actions ignore it (their timeline names actions).
+- **`Keyboard.presses(window)`** reports every key that went down since the previous snapshot, bound or not, as `{ key, code }`, so a settings screen can wait for the key to bind (the gamepad equivalent is the snapshot's `buttons`).
+- **`Keyboard.parseRebinding(bindings, data)`** and **`Gamepad.parseRebinding(bindings, data)`** validate saved bindings (for example from `localStorage`) as a `Result` ready for `rebind`, with the offending `path` on failure.
+- **Timelines replay a release and press inside one update.** An action (keyboard) or button (gamepad) in both `press` and `release` of one entry is now a release then a new press when it was held, and still a tap when it was up, so `recording(...)` captures a quick double tap and the replay matches.
 - **Breaking for hand-written sources:** `Keyboard.Actions` now requires `rebind`. An object implementing it by hand adds `rebind() {}`.
diff --git a/packages/browser/README.md b/packages/browser/README.md
index 1aef15fd..967b059d 100644
--- a/packages/browser/README.md
+++ b/packages/browser/README.md
@@ -1,6 +1,6 @@
 # `@typeonce/ritmo-browser`
 
-Browser integrations for ritmo: animation frames as a tick source for the core fixed-step loop (`BrowserTickSource`), keyboard actions with press/release edges, bound by character or by physical key (`Keyboard`), gamepad actions by standard-mapping button names plus the sticks and triggers (`Gamepad`), both rebindable at runtime for a controls settings screen, mouse and pen position and button edges over an element (`Pointer`), on-screen touch controls with a floating stick and drag-to-aim buttons (`Touch`), scripted and recorded keyboard, pointer, and gamepad timelines for tests and replays, and a system that copies input into a resource (`InputCapture`).
+Browser integrations for ritmo: animation frames as a tick source for the core fixed-step loop (`BrowserTickSource`), keyboard actions with press/release edges, bound by character or by physical key (`Keyboard`), gamepad actions by standard-mapping button names plus the sticks and triggers (`Gamepad`), both rebindable at runtime for a controls settings screen (capture the key or button to bind, validate saved bindings with `parseRebinding`), mouse and pen position and button edges over an element (`Pointer`), on-screen touch controls with a floating stick and drag-to-aim buttons (`Touch`), scripted and recorded keyboard, pointer, and gamepad timelines for tests and replays, and a system that copies input into a resource (`InputCapture`).
 
 ```sh
 pnpm add @typeonce/ritmo-browser @typeonce/ritmo
diff --git a/packages/browser/dtslint/Gamepad.tst.ts b/packages/browser/dtslint/Gamepad.tst.ts
index e8db7962..6e3c842d 100644
--- a/packages/browser/dtslint/Gamepad.tst.ts
+++ b/packages/browser/dtslint/Gamepad.tst.ts
@@ -1,3 +1,4 @@
+import { Result } from "@typeonce/ritmo"
 import { Gamepad } from "@typeonce/ritmo-browser"
 import { describe, expect, it } from "tstyche"
 
@@ -36,3 +37,22 @@ describe("Gamepad", () => {
     if (Gamepad.isButton(name)) expect(name).type.toBe<Gamepad.Button>()
   })
 })
+
+describe("Gamepad.parseRebinding", () => {
+  it("parses into a rebinding for the same actions", () => {
+    const bindings = { attack: ["west"], dash: ["south"] } as const
+    expect(Gamepad.parseRebinding(bindings, null)).type.toBe<
+      Result.Result<Gamepad.Rebinding<{ readonly attack: readonly ["west"]; readonly dash: readonly ["south"] }>, Gamepad.InvalidRebinding>
+    >()
+    const parsed = Gamepad.parseRebinding(bindings, null)
+    if (parsed.ok) Gamepad.actions(host, bindings).rebind(parsed.value)
+  })
+
+  it("rejects a rebinding parsed for other actions", () => {
+    const parsed = Gamepad.parseRebinding({ attack: ["west"] }, null)
+    if (parsed.ok) {
+      // @ts-expect-error Property 'dash' is missing
+      Gamepad.actions(host, { attack: ["west"], dash: ["south"] }).rebind(parsed.value)
+    }
+  })
+})
diff --git a/packages/browser/dtslint/Keyboard.tst.ts b/packages/browser/dtslint/Keyboard.tst.ts
index 33cd53c7..e7ee212a 100644
--- a/packages/browser/dtslint/Keyboard.tst.ts
+++ b/packages/browser/dtslint/Keyboard.tst.ts
@@ -1,3 +1,4 @@
+import { Result } from "@typeonce/ritmo"
 import { Keyboard } from "@typeonce/ritmo-browser"
 import { describe, expect, it } from "tstyche"
 
@@ -36,3 +37,29 @@ describe("Keyboard.rebind", () => {
     expect(input.rebind).type.not.toBeCallableWith({ jump: ["j"] })
   })
 })
+
+describe("Keyboard.presses", () => {
+  it("returns the keys pressed since the previous snapshot", () => {
+    expect(Keyboard.presses(host).snapshot()).type.toBe<ReadonlyArray<Keyboard.KeyPress>>()
+    expect(Keyboard.presses(host).snapshot()[0]?.code).type.toBe<string | null | undefined>()
+  })
+})
+
+describe("Keyboard.parseRebinding", () => {
+  it("parses into a rebinding for the same actions", () => {
+    const bindings = { jump: [" "], left: ["a"] } as const
+    expect(Keyboard.parseRebinding(bindings, null)).type.toBe<
+      Result.Result<Keyboard.Rebinding<{ readonly jump: readonly [" "]; readonly left: readonly ["a"] }>, Keyboard.InvalidRebinding>
+    >()
+    const parsed = Keyboard.parseRebinding(bindings, null)
+    if (parsed.ok) Keyboard.actions(host, bindings).rebind(parsed.value)
+  })
+
+  it("rejects a rebinding parsed for other actions", () => {
+    const parsed = Keyboard.parseRebinding({ jump: [" "] }, null)
+    if (parsed.ok) {
+      // @ts-expect-error Property 'left' is missing
+      Keyboard.actions(host, { jump: [" "], left: ["a"] }).rebind(parsed.value)
+    }
+  })
+})
diff --git a/packages/browser/src/Gamepad.ts b/packages/browser/src/Gamepad.ts
index 31d9c8fa..2a9b053b 100644
--- a/packages/browser/src/Gamepad.ts
+++ b/packages/browser/src/Gamepad.ts
@@ -15,7 +15,8 @@
  * read by the same indices, which may not match its labels: let players
  * remap (`rebind`). The snapshot also reports every `button` by name,
  * whatever the bindings, for fixed menu navigation and for a settings screen
- * that waits for the button to bind.
+ * that waits for the button to bind; `parseRebinding(...)` validates
+ * bindings saved as JSON.
  *
  * Polling happens on every `snapshot()`. A press and release that both fall
  * between two snapshots is missed unless the host also calls `poll()` more
@@ -90,7 +91,10 @@ export type Button = (typeof buttonNames)[number]
  */
 export type Bindings = Readonly<Record<string, readonly [Button, ...Array<Button>]>>
 
-/** New buttons for the same actions, for {@link Actions.rebind}. */
+/**
+ * New buttons for the same actions, for {@link Actions.rebind}. Load saved
+ * ones with {@link parseRebinding}.
+ */
 export type Rebinding<B extends Bindings> = { readonly [Action in keyof B]: readonly [Button, ...Array<Button>] }
 
 /** One button's reading, the subset of the browser's `GamepadButton` the module reads. */
@@ -142,8 +146,13 @@ export interface Actions<B extends Bindings> {
   /** Reads the pads now, so a press shorter than one update still counts. `snapshot()` polls too. */
   poll(): void
   /**
-   * Binds the same actions to new buttons, from the next snapshot. An action
-   * held only through buttons it lost reports `released`.
+   * Binds the same actions to new buttons, from the next snapshot, for a
+   * settings screen where players remap controls (capture the button to bind
+   * from the snapshot's `buttons`). An action held only through buttons it
+   * lost reports `released`. A button held across the rebind holds a newly
+   * bound action only once it is pressed again, so an action never turns
+   * held without a press. Buttons outside the actions it was made with are
+   * ignored.
    */
   rebind(bindings: Rebinding<B>): void
   /** Stops reading pads. */
@@ -189,33 +198,62 @@ const stick = (x: number, y: number, deadZone: number): Vector => {
  * and scripted actions so both build snapshots the same way.
  */
 const tracker = <B extends Bindings>(initial: B) => {
+  // Fixed at creation: a rebind swaps buttons, never the actions.
+  const names = Object.keys(initial) as Array<keyof B & string>
   let bindings: Rebinding<B> = initial
-  let names = Object.keys(initial) as Array<keyof B & string>
+  const actionsByButton = new Map<Button, Array<keyof B & string>>()
+  const index = (): void => {
+    actionsByButton.clear()
+    for (const name of names) {
+      for (const button of bindings[name]!) {
+        const bound = actionsByButton.get(button)
+        if (bound) bound.push(name)
+        else actionsByButton.set(button, [name])
+      }
+    }
+  }
+  index()
   const held = new Set<Button>()
   const pressed = new Set<Button>()
   const released = new Set<Button>()
-  /** Actions that lost their held buttons in a rebind, reported released on the next snapshot. */
-  const droppedActions = new Set<keyof B>()
-  const isHeld = (name: keyof B & string): boolean => bindings[name]!.some((button) => held.has(button))
+  /**
+   * Each held button and the actions it holds: those bound to it when it
+   * went down that are still bound to it.
+   */
+  const holding = new Map<Button, Set<keyof B & string>>()
+  const pressedActions = new Set<keyof B>()
+  const releasedActions = new Set<keyof B>()
+  const isHeld = (name: keyof B & string): boolean => bindings[name]!.some((button) => holding.get(button)?.has(name) === true)
+  const up = (button: Button): void => {
+    if (!held.delete(button)) return
+    released.add(button)
+    for (const name of holding.get(button) ?? []) releasedActions.add(name)
+    holding.delete(button)
+  }
   return {
     held,
     down(button: Button) {
       if (held.has(button)) return
       held.add(button)
       pressed.add(button)
+      const bound = actionsByButton.get(button) ?? []
+      holding.set(button, new Set(bound))
+      for (const name of bound) pressedActions.add(name)
     },
-    up(button: Button) {
-      if (held.delete(button)) released.add(button)
-    },
+    up,
     upAll() {
-      for (const button of held) released.add(button)
-      held.clear()
+      for (const button of [...held]) up(button)
     },
     rebind(next: Rebinding<B>) {
       const before = names.filter(isHeld)
       bindings = next
-      names = Object.keys(next) as Array<keyof B & string>
-      for (const name of before) if (!isHeld(name)) droppedActions.add(name)
+      index()
+      // A held button keeps only the actions still bound to it; new ones wait for a fresh press.
+      for (const [button, actions] of holding) {
+        const bound = actionsByButton.get(button) ?? []
+        for (const name of actions) if (!bound.includes(name)) actions.delete(name)
+      }
+      for (const name of before) if (!isHeld(name)) releasedActions.add(name)
     },
     snapshot(analog: Pick<Snapshot<B>, "left" | "right" | "leftTrigger" | "rightTrigger" | "connected" | "id">): Snapshot<B> {
       const buttons = {} as Record<Button, ActionState>
@@ -227,17 +265,13 @@ const tracker = <B extends Bindings>(initial: B) => {
       }
       const actions = {} as Record<keyof B, ActionState>
       for (const name of names) {
-        const bound = bindings[name]!
-        const isDown = bound.some((button) => held.has(button))
-        actions[name] = {
-          held: isDown,
-          pressed: bound.some((button) => pressed.has(button)),
-          released: !isDown && (droppedActions.has(name) || bound.some((button) => released.has(button)))
-        }
+        const isDown = isHeld(name)
+        actions[name] = { held: isDown, pressed: pressedActions.has(name), released: releasedActions.has(name) && !isDown }
       }
       pressed.clear()
       released.clear()
-      droppedActions.clear()
+      pressedActions.clear()
+      releasedActions.clear()
       return { actions, buttons, ...analog }
     }
   }
@@ -323,11 +357,12 @@ export const actions = <const B extends Bindings>(host: GamepadHost, bindings: B
 }
 
 /**
- * Input changes applied just before one snapshot: presses first, then
- * releases, then the sticks and triggers, which keep their value until set
- * again. `frame` is the snapshot's index, counting from 0 at the first
- * `snapshot()` call. A button both pressed and released in one frame is a
- * tap shorter than a frame.
+ * Input changes applied just before one snapshot: the buttons, then the
+ * sticks and triggers, which keep their value until set again. `frame` is the
+ * snapshot's index, counting from 0 at the first `snapshot()` call. A button
+ * in both `press` and `release` changed twice within the frame: a tap
+ * shorter than a frame when it was up, a release and a new press when it was
+ * held.
  */
 export interface TimelineEntry {
   readonly frame: number
@@ -372,8 +407,16 @@ export const scripted = <const B extends Bindings>(bindings: B, timeline: Timeli
   return {
     snapshot() {
       for (const entry of byFrame.get(frame) ?? []) {
-        for (const button of entry.press ?? []) state.down(button)
-        for (const button of entry.release ?? []) state.up(button)
+        const releases = new Set(entry.release ?? [])
+        for (const button of entry.press ?? []) {
+          if (state.held.has(button) && releases.has(button)) {
+            // Released and pressed again within the frame.
+            releases.delete(button)
+            state.up(button)
+          }
+          state.down(button)
+        }
+        for (const button of releases) state.up(button)
         analog = {
           left: entry.left ?? analog.left,
           right: entry.right ?? analog.right,
@@ -406,13 +449,14 @@ const sameVector = (a: Vector, b: Vector): boolean => a.x === b.x && a.y === b.y
  */
 export const recording = <B extends Bindings>(actions: Actions<B>): Recording<B> => {
   const entries: Array<TimelineEntry> = []
-  let previous: Pick<Snapshot<B>, "left" | "right" | "leftTrigger" | "rightTrigger"> = { left: zero, right: zero, leftTrigger: 0, rightTrigger: 0 }
+  let previous: Pick<Snapshot<B>, "buttons" | "left" | "right" | "leftTrigger" | "rightTrigger"> = { buttons: idleButtons(), left: zero, right: zero, leftTrigger: 0, rightTrigger: 0 }
   let frame = 0
   return {
     snapshot() {
       const snapshot = actions.snapshot()
       const press = buttonNames.filter((name) => snapshot.buttons[name].pressed)
-      const release = buttonNames.filter((name) => snapshot.buttons[name].released)
+      // A press of a button held at the previous snapshot means it was released in between.
+      const release = buttonNames.filter((name) => snapshot.buttons[name].released || (snapshot.buttons[name].pressed && previous.buttons[name].held))
       const entry: Record<string, unknown> = {
         ...(press.length > 0 ? { press } : {}),
         ...(release.length > 0 ? { release } : {}),
@@ -495,3 +539,48 @@ export const parseTimeline = (data: unknown): Result.Result<Timeline, InvalidTim
   }
   return Result.success(entries)
 }
+
+/**
+ * Why loaded data is not a rebinding for the bindings. `path` points at the
+ * offending value, for example `attack[1]`.
+ */
+export interface InvalidRebinding {
+  readonly _tag: "InvalidRebinding"
+  readonly path: string
+  readonly message: string
+}
+
+/**
+ * Validates untrusted data, such as saved settings parsed from JSON, as new
+ * buttons for `bindings`: an object with exactly the same action names, each
+ * mapped to a non-empty array of button names. Pass the result to
+ * {@link Actions.rebind}; on failure, keep the defaults.
+ *
+ * @example
+ * ```ts
+ * const saved = Gamepad.parseRebinding(bindings, JSON.parse(stored))
+ * if (saved.ok) pad.rebind(saved.value)
+ * ```
+ */
+export const parseRebinding = <const B extends Bindings>(
+  bindings: B,
+  data: unknown
+): Result.Result<Rebinding<B>, InvalidRebinding> => {
+  const invalid = (path: string, message: string) => Result.failure<InvalidRebinding>({ _tag: "InvalidRebinding", path, message })
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return invalid("", "expected an object of action names")
+  const fields = data as Readonly<Record<string, unknown>>
+  const names = Object.keys(bindings)
+  for (const name of Object.keys(fields)) {
+    if (!names.includes(name)) return invalid(name, `unknown action, expected one of ${names.join(", ")}`)
+  }
+  const rebinding: Record<string, ReadonlyArray<Button>> = {}
+  for (const name of names) {
+    const value = fields[name]
+    if (!Array.isArray(value) || value.length === 0) return invalid(name, "expected a non-empty array of button names")
+    for (let offset = 0; offset < value.length; offset++) {
+      if (!isButton(value[offset])) return invalid(`${name}[${offset}]`, `expected one of ${buttonNames.join(", ")}`)
+    }
+    rebinding[name] = [...value]
+  }
+  return Result.success(rebinding as unknown as Rebinding<B>)
+}
diff --git a/packages/browser/src/Keyboard.ts b/packages/browser/src/Keyboard.ts
index 23d96d98..efea7e19 100644
--- a/packages/browser/src/Keyboard.ts
+++ b/packages/browser/src/Keyboard.ts
@@ -36,6 +36,11 @@
  * input.dispose()
  * ```
  *
+ * For a controls settings screen, `presses(...)` reports every key that
+ * goes down (bound or not) so the screen can wait for the key to bind,
+ * `rebind(...)` swaps the keys of the same actions, and `parseRebinding(...)`
+ * validates bindings saved as JSON.
+ *
  * For tests, replays, and headless runs, `scripted(...)` plays a timeline of
  * presses and releases instead of listening to a host, and `recording(...)`
  * wraps live actions to capture the timeline a session produced.
@@ -132,7 +137,10 @@ export type Snapshot<B extends Bindings> = {
   readonly [Action in keyof B]: ActionState
 }
 
-/** New keys for the same actions, for {@link Actions.rebind}. */
+/**
+ * New keys for the same actions, for {@link Actions.rebind}. Load saved
+ * ones with {@link parseRebinding}.
+ */
 export type Rebinding<B extends Bindings> = { readonly [Action in keyof B]: readonly [KeyBinding, ...Array<KeyBinding>] }
 
 export interface Actions<B extends Bindings> {
@@ -142,9 +150,11 @@ export interface Actions<B extends Bindings> {
   snapshot(): Snapshot<B>
   /**
    * Binds the same actions to new keys, from the next snapshot, for a
-   * settings screen where players remap controls. An action held only
-   * through keys it lost reports `released`; a key held across the rebind
-   * that is newly bound counts once it is pressed again.
+   * settings screen where players remap controls (capture the key to bind
+   * with {@link presses}). An action held only through keys it lost reports
+   * `released`. A key held across the rebind holds a newly bound action only
+   * once it is pressed again, so an action never turns held without a
+   * press. Keys outside the actions it was made with are ignored.
    */
   rebind(bindings: Rebinding<B>): void
   /**
@@ -189,8 +199,9 @@ export const actions = <const B extends Bindings>(
   options: ActionsOptions = {}
 ): Actions<B> => {
   const preventDefault = options.preventDefault ?? true
+  // Fixed at creation: a rebind swaps keys, never the actions.
+  const names = Object.keys(initial) as Array<keyof B & string>
   let bindings: Rebinding<B> = initial
-  let names = Object.keys(initial) as Array<keyof B & string>
   const actionsByToken = new Map<string, Array<keyof B & string>>()
   const index = (): void => {
     actionsByToken.clear()
@@ -205,7 +216,12 @@ export const actions = <const B extends Bindings>(
   }
   index()
 
-  const heldTokens = new Set<string>()
+  /**
+   * Each held token and the actions it holds: those bound to it when it went
+   * down that are still bound to it. A token stays here while held even if a
+   * rebind unbound it, so its release is still seen.
+   */
+  const heldTokens = new Map<string, Set<keyof B & string>>()
   /**
    * The character token each physical key produced when it went down, so its
    * release matches even if a modifier changed the character meanwhile
@@ -227,7 +243,7 @@ export const actions = <const B extends Bindings>(
       if (!bound) continue
       handled = true
       if (event.repeat || heldTokens.has(token)) continue
-      heldTokens.add(token)
+      heldTokens.set(token, new Set(bound))
       for (const name of bound) pressed.add(name)
     }
     if (handled && preventDefault) event.preventDefault()
@@ -242,15 +258,16 @@ export const actions = <const B extends Bindings>(
       tokens.push(codeToken(event.code))
     }
     for (const token of tokens) {
-      // A key stays tracked while held even if a rebind unbound it, so its release is still seen.
-      if (!heldTokens.delete(token)) continue
-      for (const name of actionsByToken.get(token) ?? []) released.add(name)
+      const holding = heldTokens.get(token)
+      if (!holding) continue
+      heldTokens.delete(token)
+      for (const name of holding) released.add(name)
     }
   }
 
   const onBlur = (): void => {
-    for (const token of heldTokens) {
-      for (const name of actionsByToken.get(token) ?? []) released.add(name)
+    for (const holding of heldTokens.values()) {
+      for (const name of holding) released.add(name)
     }
     heldTokens.clear()
     keyTokenByCode.clear()
@@ -262,7 +279,7 @@ export const actions = <const B extends Bindings>(
 
   const isHeld = (name: keyof B & string): boolean => {
     for (const binding of bindings[name]!) {
-      if (heldTokens.has(bindingToken(binding))) return true
+      if (heldTokens.get(bindingToken(binding))?.has(name)) return true
     }
     return false
   }
@@ -285,8 +302,12 @@ export const actions = <const B extends Bindings>(
     rebind(next) {
       const before = names.filter(isHeld)
       bindings = next
-      names = Object.keys(next) as Array<keyof B & string>
       index()
+      // A held key keeps only the actions still bound to it; new ones wait for a fresh press.
+      for (const [token, holding] of heldTokens) {
+        const bound = actionsByToken.get(token) ?? []
+        for (const name of holding) if (!bound.includes(name)) holding.delete(name)
+      }
       for (const name of before) if (!isHeld(name)) released.add(name)
     },
     dispose() {
@@ -297,11 +318,62 @@ export const actions = <const B extends Bindings>(
   }
 }
 
+/** One key that went down, in the two forms a {@link KeyBinding} can name it. */
+export interface KeyPress {
+  /** The character typed (`KeyboardEvent.key`), for a character binding. */
+  readonly key: string
+  /** The physical key (`KeyboardEvent.code`), for `Keyboard.code(...)`; `null` when the host gave none. */
+  readonly code: string | null
+}
+
+/** Every key press on a host, bound or not; see {@link presses}. */
+export interface Presses {
+  /** The keys that went down since the previous snapshot, in order, without auto-repeats. */
+  snapshot(): ReadonlyArray<KeyPress>
+  /** Removes the event listener. */
+  dispose(): void
+}
+
+/**
+ * Starts collecting every key press on `host`, whatever the bindings, for a
+ * settings screen that waits for the key to bind. Use {@link actions} for
+ * gameplay. It never calls `preventDefault()`.
+ *
+ * @example
+ * ```ts
+ * const presses = Keyboard.presses(window)
+ *
+ * // While the settings screen waits for the new jump key:
+ * const press = presses.snapshot()[0]
+ * if (press !== undefined) {
+ *   input.rebind({ ...current, jump: [press.code === null ? press.key : Keyboard.code(press.code)] })
+ * }
+ * ```
+ */
+export const presses = (host: KeyboardHost): Presses => {
+  let pending: Array<KeyPress> = []
+  const onKeyDown = (event: KeyEvent): void => {
+    if (event.repeat) return
+    pending.push({ key: event.key, code: event.code ?? null })
+  }
+  host.addEventListener("keydown", onKeyDown)
+  return {
+    snapshot() {
+      const snapshot = pending
+      pending = []
+      return snapshot
+    },
+    dispose() {
+      host.removeEventListener("keydown", onKeyDown)
+    }
+  }
+}
+
 /**
- * Input changes applied just before one snapshot: presses first, then
- * releases. `frame` is the snapshot's index, counting from 0 at the first
- * `snapshot()` call. An action both pressed and released in one frame is a
- * tap shorter than a frame.
+ * Input changes applied just before one snapshot. `frame` is the snapshot's
+ * index, counting from 0 at the first `snapshot()` call. An action in both
+ * `press` and `release` changed twice within the frame: a tap shorter than a
+ * frame when it was up, a release and a new press when it was held.
  */
 export interface TimelineEntry<B extends Bindings> {
   readonly frame: number
@@ -343,13 +415,21 @@ export const scripted = <const B extends Bindings>(bindings: B, timeline: Timeli
       const pressed = new Set<keyof B>()
       const released = new Set<keyof B>()
       for (const entry of byFrame.get(frame) ?? []) {
+        const releases = new Set(entry.release ?? [])
         for (const name of entry.press ?? []) {
+          if (held.has(name) && releases.has(name)) {
+            // Released and pressed again within the frame.
+            releases.delete(name)
+            released.add(name)
+            pressed.add(name)
+            continue
+          }
           // A press of a held action is not a new press, as with a live
           // keyboard's auto-repeat.
           if (!held.has(name)) pressed.add(name)
           held.add(name)
         }
-        for (const name of entry.release ?? []) {
+        for (const name of releases) {
           if (held.delete(name)) released.add(name)
         }
       }
@@ -382,17 +462,22 @@ export interface Recording<B extends Bindings> extends Actions<B> {
  */
 export const recording = <B extends Bindings>(actions: Actions<B>): Recording<B> => {
   const entries: Array<TimelineEntry<B>> = []
+  let wasHeld = new Set<keyof B & string>()
   let frame = 0
   return {
     snapshot() {
       const snapshot = actions.snapshot()
       const press: Array<keyof B & string> = []
       const release: Array<keyof B & string> = []
+      const held = new Set<keyof B & string>()
       for (const name of Object.keys(snapshot) as Array<keyof B & string>) {
         const state = snapshot[name]!
+        if (state.held) held.add(name)
         if (state.pressed) press.push(name)
-        if (state.released) release.push(name)
+        // A press of an action held at the previous snapshot means it was released in between.
+        if (state.released || (state.pressed && wasHeld.has(name))) release.push(name)
       }
+      wasHeld = held
       if (press.length > 0 || release.length > 0) {
         entries.push({
           frame,
@@ -468,3 +553,53 @@ export const parseTimeline = <const B extends Bindings>(
   }
   return Result.success(entries)
 }
+
+/**
+ * Why loaded data is not a rebinding for the bindings. `path` points at the
+ * offending value, for example `jump[1]`.
+ */
+export interface InvalidRebinding {
+  readonly _tag: "InvalidRebinding"
+  readonly path: string
+  readonly message: string
+}
+
+/**
+ * Validates untrusted data, such as saved settings parsed from JSON, as new
+ * keys for `bindings`: an object with exactly the same action names, each
+ * mapped to a non-empty array of characters or `{ code }` physical keys.
+ * Pass the result to {@link Actions.rebind}; on failure, keep the defaults.
+ *
+ * @example
+ * ```ts
+ * const saved = Keyboard.parseRebinding(bindings, JSON.parse(stored))
+ * if (saved.ok) input.rebind(saved.value)
+ * ```
+ */
+export const parseRebinding = <const B extends Bindings>(
+  bindings: B,
+  data: unknown
+): Result.Result<Rebinding<B>, InvalidRebinding> => {
+  const invalid = (path: string, message: string) => Result.failure<InvalidRebinding>({ _tag: "InvalidRebinding", path, message })
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return invalid("", "expected an object of action names")
+  const fields = data as Readonly<Record<string, unknown>>
+  const names = Object.keys(bindings)
+  for (const name of Object.keys(fields)) {
+    if (!names.includes(name)) return invalid(name, `unknown action, expected one of ${names.join(", ")}`)
+  }
+  const rebinding: Record<string, ReadonlyArray<KeyBinding>> = {}
+  for (const name of names) {
+    const value = fields[name]
+    if (!Array.isArray(value) || value.length === 0) return invalid(name, "expected a non-empty array of keys")
+    const keys: Array<KeyBinding> = []
+    for (let offset = 0; offset < value.length; offset++) {
+      const key: unknown = value[offset]
+      if (typeof key === "string" && key.length > 0) keys.push(key)
+      else if (typeof key === "object" && key !== null && typeof (key as { readonly code?: unknown }).code === "string" && (key as PhysicalKey).code.length > 0) {
+        keys.push({ code: (key as PhysicalKey).code })
+      } else return invalid(`${name}[${offset}]`, "expected a key character or { code }")
+    }
+    rebinding[name] = keys
+  }
+  return Result.success(rebinding as unknown as Rebinding<B>)
+}
diff --git a/packages/browser/test/Gamepad.test.ts b/packages/browser/test/Gamepad.test.ts
index acd10abd..1391377c 100644
--- a/packages/browser/test/Gamepad.test.ts
+++ b/packages/browser/test/Gamepad.test.ts
@@ -161,9 +161,48 @@ describe("Gamepad.actions", () => {
     input.rebind({ attack: ["north"], dash: ["west"], ultimate: ["rightTrigger"] })
     const snapshot = input.snapshot()
     expect(snapshot.actions.attack).toEqual(released)
-    expect(snapshot.actions.dash).toEqual({ held: true, pressed: false, released: false })
+    // West is still down, but dash waits for a fresh press of it.
+    expect(snapshot.actions.dash).toEqual(idle)
     pad.down("north")
     expect(input.snapshot().actions.attack).toEqual({ held: true, pressed: true, released: false })
+    pad.up("west")
+    expect(input.snapshot().actions.dash).toEqual(idle)
+    pad.down("west")
+    expect(input.snapshot().actions.dash).toEqual({ held: true, pressed: true, released: false })
+  })
+
+  it("does not hold a newly bound action through the button that was pressed to bind it", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings)
+
+    pad.down("north")
+    const waiting = input.snapshot()
+    expect(waiting.buttons.north.pressed).toBe(true)
+    input.rebind({ attack: ["north"], dash: ["south"], ultimate: ["rightTrigger"] })
+    expect(input.snapshot().actions.attack).toEqual(idle)
+    pad.up("north")
+    expect(input.snapshot().actions.attack).toEqual(idle)
+  })
+
+  it("keeps an action held through a button it kept", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings)
+
+    pad.down("south")
+    input.snapshot()
+    input.rebind({ attack: ["west"], dash: ["south"], ultimate: ["north"] })
+    expect(input.snapshot().actions.dash).toEqual({ held: true, pressed: false, released: false })
+    pad.up("south")
+    expect(input.snapshot().actions.dash).toEqual(released)
+  })
+
+  it("ignores actions a rebinding adds", () => {
+    const pad = makePad()
+    const input = Gamepad.actions(makeHost(pad).host, bindings)
+    const next = { attack: ["west"], dash: ["south"], ultimate: ["rightTrigger"], extra: ["north"] } as const
+
+    input.rebind(next)
+    expect(Object.keys(input.snapshot().actions)).toEqual(["attack", "dash", "ultimate"])
   })
 
   it("stops reading after dispose", () => {
@@ -229,6 +268,51 @@ describe("Gamepad.recording", () => {
   })
 })
 
+describe("Gamepad.recording release and press within one update", () => {
+  it("replays a button released and pressed again between two snapshots", () => {
+    const pad = makePad()
+    const live = Gamepad.recording(Gamepad.actions(makeHost(pad).host, bindings))
+    const seen: Array<Gamepad.Snapshot<typeof bindings>> = []
+
+    pad.down("west")
+    seen.push(live.snapshot())
+    pad.up("west")
+    live.poll()
+    pad.down("west")
+    live.poll()
+    seen.push(live.snapshot())
+    expect(seen[1]!.actions.attack).toEqual({ held: true, pressed: true, released: false })
+    expect(live.timeline()).toEqual([{ frame: 0, press: ["west"] }, { frame: 1, press: ["west"], release: ["west"] }])
+
+    const replay = Gamepad.scripted(bindings, live.timeline())
+    for (const snapshot of seen) expect(replay.snapshot().actions).toEqual(snapshot.actions)
+  })
+
+  it("plays a button in both lists as a tap when it was up", () => {
+    const replay = Gamepad.scripted(bindings, [{ frame: 0, press: ["west"], release: ["west"] }])
+    expect(replay.snapshot().actions.attack).toEqual({ held: false, pressed: true, released: true })
+  })
+})
+
+describe("Gamepad.parseRebinding", () => {
+  it("accepts the same actions bound to button names", () => {
+    const parsed = Gamepad.parseRebinding(bindings, JSON.parse('{"attack":["north"],"dash":["south","east"],"ultimate":["leftTrigger"]}'))
+    expect(parsed).toMatchObject({ ok: true, value: { attack: ["north"], dash: ["south", "east"], ultimate: ["leftTrigger"] } })
+  })
+
+  it("names the offending value", () => {
+    const fail = (data: unknown) => {
+      const parsed = Gamepad.parseRebinding(bindings, data)
+      return parsed.ok ? null : parsed.error.path
+    }
+    expect(fail([])).toBe("")
+    expect(fail({ attack: ["north"], dash: ["south"] })).toBe("ultimate")
+    expect(fail({ attack: ["north"], dash: ["south"], ultimate: [], })).toBe("ultimate")
+    expect(fail({ attack: ["north", "A"], dash: ["south"], ultimate: ["east"] })).toBe("attack[1]")
+    expect(fail({ attack: ["north"], dash: ["south"], ultimate: ["east"], jump: ["west"] })).toBe("jump")
+  })
+})
+
 describe("Gamepad.parseTimeline", () => {
   it("names the offending value", () => {
     expect(Gamepad.parseTimeline([{ frame: 0, press: ["jump"] }])).toMatchObject({ ok: false, error: { path: "[0].press[0]" } })
diff --git a/packages/browser/test/Keyboard.test.ts b/packages/browser/test/Keyboard.test.ts
index 9ac8392c..3795eb85 100644
--- a/packages/browser/test/Keyboard.test.ts
+++ b/packages/browser/test/Keyboard.test.ts
@@ -209,18 +209,42 @@ describe("Keyboard.rebind", () => {
     expect(snapshot.dash).toEqual({ held: true, pressed: true, released: false })
   })
 
-  it("releases an action held only through keys it lost, and still sees the old key go up", () => {
+  it("releases an action held only through keys it lost, and holds a newly bound one only after a fresh press", () => {
     const fake = makeHost()
     const input = Keyboard.actions(fake.host, { jump: [" "], crouch: ["c"] })
+    const idle = { held: false, pressed: false, released: false }
 
     fake.down(" ")
     input.snapshot()
     input.rebind({ jump: ["w"], crouch: [" "] })
     const snapshot = input.snapshot()
     expect(snapshot.jump).toEqual({ held: false, pressed: false, released: true })
-    expect(snapshot.crouch).toEqual({ held: true, pressed: false, released: false })
+    expect(snapshot.crouch).toEqual(idle)
     fake.up(" ")
-    expect(input.snapshot().crouch).toEqual({ held: false, pressed: false, released: true })
+    expect(input.snapshot().crouch).toEqual(idle)
+    fake.down(" ")
+    expect(input.snapshot().crouch).toEqual({ held: true, pressed: true, released: false })
+  })
+
+  it("keeps an action held through a key it kept", () => {
+    const fake = makeHost()
+    const input = Keyboard.actions(fake.host, { jump: [" "], crouch: ["c"] })
+
+    fake.down(" ")
+    input.snapshot()
+    input.rebind({ jump: [" ", "w"], crouch: ["x"] })
+    expect(input.snapshot().jump).toEqual({ held: true, pressed: false, released: false })
+    fake.up(" ")
+    expect(input.snapshot().jump).toEqual({ held: false, pressed: false, released: true })
+  })
+
+  it("ignores actions a rebinding adds", () => {
+    const fake = makeHost()
+    const input = Keyboard.actions(fake.host, { jump: [" "] })
+    const next = { jump: ["w"], extra: ["x"] } as const
+
+    input.rebind(next)
+    expect(Object.keys(input.snapshot())).toEqual(["jump"])
   })
 
   it("keeps a recording's timeline by action, so a rebind does not change a replay", () => {
@@ -236,3 +260,67 @@ describe("Keyboard.rebind", () => {
     expect(replay.snapshot().jump.pressed).toBe(true)
   })
 })
+
+describe("Keyboard.recording release and press within one update", () => {
+  it("replays an action released and pressed again between two snapshots", () => {
+    const fake = makeHost()
+    const bindings = { jump: [" "] } as const
+    const recorder = Keyboard.recording(Keyboard.actions(fake.host, bindings))
+    const live: Array<Keyboard.Snapshot<typeof bindings>> = []
+
+    fake.down(" ")
+    live.push(recorder.snapshot())
+    fake.up(" ")
+    fake.down(" ")
+    live.push(recorder.snapshot())
+    expect(live[1]!.jump).toEqual({ held: true, pressed: true, released: false })
+    expect(recorder.timeline()).toEqual([{ frame: 0, press: ["jump"] }, { frame: 1, press: ["jump"], release: ["jump"] }])
+
+    const replay = Keyboard.scripted(bindings, recorder.timeline())
+    expect(live.map(() => replay.snapshot())).toEqual(live)
+  })
+})
+
+describe("Keyboard.presses", () => {
+  it("collects every key press, bound or not, once per snapshot and without repeats", () => {
+    const fake = makeHost()
+    const presses = Keyboard.presses(fake.host)
+
+    fake.downCode("j", "KeyJ")
+    fake.down("j", true)
+    fake.down("Escape")
+    expect(presses.snapshot()).toEqual([{ key: "j", code: "KeyJ" }, { key: "Escape", code: null }])
+    expect(presses.snapshot()).toEqual([])
+    presses.dispose()
+    expect(fake.listenerCount()).toBe(0)
+  })
+
+  it("does not prevent the browser default", () => {
+    const fake = makeHost()
+    Keyboard.presses(fake.host)
+    fake.down(" ")
+    expect(fake.prevented).toEqual([])
+  })
+})
+
+describe("Keyboard.parseRebinding", () => {
+  const bindings = { jump: [" "], left: ["a"] } as const
+
+  it("accepts the same actions bound to characters and physical keys", () => {
+    const parsed = Keyboard.parseRebinding(bindings, JSON.parse('{"jump":[{"code":"KeyJ"}],"left":["ArrowLeft","q"]}'))
+    expect(parsed).toMatchObject({ ok: true, value: { jump: [{ code: "KeyJ" }], left: ["ArrowLeft", "q"] } })
+  })
+
+  it("names the offending value", () => {
+    const fail = (data: unknown) => {
+      const parsed = Keyboard.parseRebinding(bindings, data)
+      return parsed.ok ? null : parsed.error.path
+    }
+    expect(fail(null)).toBe("")
+    expect(fail({ jump: ["j"] })).toBe("left")
+    expect(fail({ jump: [], left: ["a"] })).toBe("jump")
+    expect(fail({ jump: ["j", { key: "k" }], left: ["a"] })).toBe("jump[1]")
+    expect(fail({ jump: [""], left: ["a"] })).toBe("jump[0]")
+    expect(fail({ jump: ["j"], left: ["a"], fly: ["f"] })).toBe("fly")
+  })
+})

From 46ea1cb4b4772e1b42e4b11d1a1775c99cc032f9 Mon Sep 17 00:00:00 2001
From: SandroMaglione <lass.maglio@gmail.com>
Date: Thu, 22 Oct 2026 19:22:27 +0900
Subject: [PATCH 3/4] Exact rebind and capture types, and read pads on
 animation frames

- rebind takes exactly the actions the source was made with: an extra
  action fails to compile even from an object not written inline, and a
  Record<string, ...> is rejected since it cannot prove its keys.
- InputCapture.system requires the resource's value type to be exactly
  the source's snapshot type, not merely assignable both ways, and the
  error names SnapshotOf as the fix.
- Gamepad.actions takes the window and reads the pads on every animation
  frame until dispose, so poll() is gone and the lifecycle matches
  Keyboard (snapshot / rebind / dispose).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/gamepad-actions.md                |  5 +-
 packages/browser/dtslint/Gamepad.tst.ts      | 24 +++++++-
 packages/browser/dtslint/InputCapture.tst.ts | 20 ++++++-
 packages/browser/dtslint/Keyboard.tst.ts     | 13 ++++
 packages/browser/src/Gamepad.ts              | 62 +++++++++++++-------
 packages/browser/src/InputCapture.ts         | 17 +++++-
 packages/browser/src/Keyboard.ts             | 12 +++-
 packages/browser/test/Gamepad.test.ts        | 56 ++++++++++++++----
 packages/browser/test/Keyboard.test.ts       |  4 +-
 9 files changed, 169 insertions(+), 44 deletions(-)

diff --git a/.changeset/gamepad-actions.md b/.changeset/gamepad-actions.md
index 543178f0..6669b2e7 100644
--- a/.changeset/gamepad-actions.md
+++ b/.changeset/gamepad-actions.md
@@ -4,9 +4,10 @@
 
 **`Gamepad` reads controllers as named actions, and keyboard and gamepad bindings can change at runtime.**
 
-- **`Gamepad.actions(navigator, bindings, options)`** binds actions to buttons named by the browser's standard mapping (`"south"`, `"west"`, `"rightTrigger"`, `"dpadUp"`, `"start"`...). Each snapshot has `actions` (as `Keyboard`'s), every `buttons` state by name whatever the bindings (for menu navigation and for a settings screen waiting for the button to bind), the `left` and `right` sticks with a radial dead zone (`y` grows down, as `Touch`'s stick), how far each trigger is pulled, and the followed pad's `id`. It follows the pad used last and releases everything held when that pad disconnects. Call `poll()` each animation frame so taps shorter than an update count. `Gamepad.idle`, `scripted`, `recording`, `parseTimeline`, and `isButton` match the other devices; timelines name buttons, so a replay follows the bindings.
-- **`rebind(bindings)`** on `Keyboard.actions(...)` and `Gamepad.actions(...)` binds the same actions to new keys or buttons, for players who remap their controls. An action held only through a key it lost reports `released`; a key held across the rebind holds a newly bound action only after a fresh press, so an action never turns held without a press. Scripted keyboard actions ignore it (their timeline names actions).
+- **`Gamepad.actions(window, bindings, options)`** binds actions to buttons named by the browser's standard mapping (`"south"`, `"west"`, `"rightTrigger"`, `"dpadUp"`, `"start"`...). Each snapshot has `actions` (as `Keyboard`'s), every `buttons` state by name whatever the bindings (for menu navigation and for a settings screen waiting for the button to bind), the `left` and `right` sticks with a radial dead zone (`y` grows down, as `Touch`'s stick), how far each trigger is pulled, and the followed pad's `id`. It follows the pad used last and releases everything held when that pad disconnects. It reads the pads on every animation frame (and on every snapshot) until `dispose()`, so taps shorter than an update count with nothing to call; the lifecycle is `snapshot` / `rebind` / `dispose`, as for `Keyboard`. `Gamepad.idle`, `scripted`, `recording`, `parseTimeline`, and `isButton` match the other devices; timelines name buttons, so a replay follows the bindings.
+- **`rebind(bindings)`** on `Keyboard.actions(...)` and `Gamepad.actions(...)` binds the same actions to new keys or buttons, for players who remap their controls. An action held only through a key it lost reports `released`; a key held across the rebind holds a newly bound action only after a fresh press, so an action never turns held without a press. It takes exactly the actions the source was made with: an extra action fails to compile with `<name> is not an action of these bindings`, even from an object not written inline. Scripted keyboard actions ignore it (their timeline names actions).
 - **`Keyboard.presses(window)`** reports every key that went down since the previous snapshot, bound or not, as `{ key, code }`, so a settings screen can wait for the key to bind (the gamepad equivalent is the snapshot's `buttons`).
 - **`Keyboard.parseRebinding(bindings, data)`** and **`Gamepad.parseRebinding(bindings, data)`** validate saved bindings (for example from `localStorage`) as a `Result` ready for `rebind`, with the offending `path` on failure.
 - **Timelines replay a release and press inside one update.** An action (keyboard) or button (gamepad) in both `press` and `release` of one entry is now a release then a new press when it was held, and still a tap when it was up, so `recording(...)` captures a quick double tap and the replay matches.
+- **Breaking: `InputCapture.system` requires the resource's value type to be exactly the source's snapshot type.** A resource that only matched both ways (for example one with an extra optional field) now fails with a message naming the fix: declare it as `Descriptor.TransientResource<InputCapture.SnapshotOf<typeof Source>>()`.
 - **Breaking for hand-written sources:** `Keyboard.Actions` now requires `rebind`. An object implementing it by hand adds `rebind() {}`.
diff --git a/packages/browser/dtslint/Gamepad.tst.ts b/packages/browser/dtslint/Gamepad.tst.ts
index 6e3c842d..5eed96be 100644
--- a/packages/browser/dtslint/Gamepad.tst.ts
+++ b/packages/browser/dtslint/Gamepad.tst.ts
@@ -28,8 +28,28 @@ describe("Gamepad", () => {
     expect(input.rebind).type.not.toBeCallableWith({ attack: ["north"], dash: ["east"], jump: ["south"] })
   })
 
-  it("accepts the browser's navigator as a host", () => {
-    expect<Navigator>().type.toBeAssignableTo<Gamepad.GamepadHost>()
+  it("rejects extra actions even from an object that is not written inline", () => {
+    const input = Gamepad.actions(host, { attack: ["west"], dash: ["south"] })
+    const next = { attack: ["north"], dash: ["east"], jump: ["south"] } as const
+    // @ts-expect-error jump is not an action of these bindings
+    input.rebind(next)
+    const wide: Record<string, readonly ["north"]> = {}
+    expect(input.rebind).type.not.toBeCallableWith(wide)
+    let current: Gamepad.Rebinding<{ readonly attack: readonly ["west"]; readonly dash: readonly ["south"] }> = { attack: ["west"], dash: ["south"] }
+    current = { ...current, attack: ["north"] }
+    expect(input.rebind).type.toBeCallableWith(current)
+    expect(Gamepad.recording(input).rebind).type.not.toBeCallableWith(next)
+  })
+
+  it("accepts the browser's window as a host", () => {
+    expect<Window>().type.toBeAssignableTo<Gamepad.GamepadHost>()
+    // @ts-expect-error is missing the following properties from type 'GamepadHost': navigator
+    Gamepad.actions(navigator, { attack: ["west"] })
+  })
+
+  it("has no poll(): the pads are read on every animation frame", () => {
+    // @ts-expect-error Property 'poll' does not exist
+    Gamepad.actions(host, { attack: ["west"] }).poll()
   })
 
   it("narrows stored names with isButton", () => {
diff --git a/packages/browser/dtslint/InputCapture.tst.ts b/packages/browser/dtslint/InputCapture.tst.ts
index 32f4342f..3db0a2a1 100644
--- a/packages/browser/dtslint/InputCapture.tst.ts
+++ b/packages/browser/dtslint/InputCapture.tst.ts
@@ -8,8 +8,12 @@ type Snapshot = Keyboard.Snapshot<typeof bindings>
 const KeyboardInput = Descriptor.Service<Keyboard.Actions<typeof bindings>>()("CaptureTypes/Keyboard")
 const Input = Descriptor.TransientResource<Snapshot>()("CaptureTypes/Input")
 const Wrong = Descriptor.Resource<{ readonly jump: boolean }>()("CaptureTypes/Wrong")
+const Fewer = Descriptor.TransientResource<Keyboard.Snapshot<{ readonly jump: readonly [" "]; readonly left: readonly ["a"] }>>()("CaptureTypes/Fewer")
+const Optional = Descriptor.TransientResource<{ readonly jump: Keyboard.ActionState; readonly left?: Keyboard.ActionState }>()("CaptureTypes/Optional")
+const Wide = Descriptor.TransientResource<unknown>()("CaptureTypes/Wide")
+const Declared = Descriptor.TransientResource<InputCapture.SnapshotOf<typeof KeyboardInput>>()("CaptureTypes/Declared")
 const Clock = Descriptor.Service<{ readonly now: () => number }>()("CaptureTypes/Clock")
-const Game = Schema.bind(Schema.fragment({ resources: { Input, Wrong } }))
+const Game = Schema.bind(Schema.fragment({ resources: { Input, Wrong, Fewer, Optional, Wide, Declared } }))
 
 describe("InputCapture", () => {
   it("requires the service and resource at tick time", () => {
@@ -45,9 +49,19 @@ describe("InputCapture", () => {
     expect(ready.tick(Game.Schedule(Capture)).ok).type.toBe<boolean>()
   })
 
-  it("rejects resources whose value is not the snapshot type", () => {
-    // @ts-expect-error Type 'ActionState' is not assignable to type 'boolean'.
+  it("rejects resources whose value is not exactly the snapshot type", () => {
+    // @ts-expect-error must be exactly the source's snapshot type
     InputCapture.system(Game, { name: "CaptureTypes/Wrong", source: KeyboardInput, resource: Wrong })
+    // @ts-expect-error must be exactly the source's snapshot type
+    InputCapture.system(Game, { name: "CaptureTypes/Fewer", source: KeyboardInput, resource: Fewer })
+    // @ts-expect-error must be exactly the source's snapshot type
+    InputCapture.system(Game, { name: "CaptureTypes/Optional", source: KeyboardInput, resource: Optional })
+    // @ts-expect-error must be exactly the source's snapshot type
+    InputCapture.system(Game, { name: "CaptureTypes/Wide", source: KeyboardInput, resource: Wide })
+  })
+
+  it("accepts a resource declared with SnapshotOf", () => {
+    expect(InputCapture.system).type.toBeCallableWith(Game, { name: "CaptureTypes/Declared", source: KeyboardInput, resource: Declared })
   })
 
   it("rejects sources without snapshot()", () => {
diff --git a/packages/browser/dtslint/Keyboard.tst.ts b/packages/browser/dtslint/Keyboard.tst.ts
index e7ee212a..6eb6a332 100644
--- a/packages/browser/dtslint/Keyboard.tst.ts
+++ b/packages/browser/dtslint/Keyboard.tst.ts
@@ -36,6 +36,19 @@ describe("Keyboard.rebind", () => {
     expect(input.rebind).type.toBeCallableWith({ jump: [Keyboard.code("KeyJ")], left: ["ArrowLeft"] })
     expect(input.rebind).type.not.toBeCallableWith({ jump: ["j"] })
   })
+
+  it("rejects extra actions even from an object that is not written inline", () => {
+    const input = Keyboard.actions(host, { jump: [" "], left: ["a"] })
+    const next = { jump: ["j"], left: ["q"], extra: ["x"] } as const
+    // @ts-expect-error extra is not an action of these bindings
+    input.rebind(next)
+    const wide: Record<string, readonly ["j"]> = {}
+    expect(input.rebind).type.not.toBeCallableWith(wide)
+    let current: Keyboard.Rebinding<{ readonly jump: readonly [" "]; readonly left: readonly ["a"] }> = { jump: [" "], left: ["a"] }
+    current = { ...current, jump: [Keyboard.code("KeyJ")] }
+    expect(input.rebind).type.toBeCallableWith(current)
+    expect(Keyboard.recording(input).rebind).type.not.toBeCallableWith(next)
+  })
 })
 
 describe("Keyboard.presses", () => {
diff --git a/packages/browser/src/Gamepad.ts b/packages/browser/src/Gamepad.ts
index 2a9b053b..723682d1 100644
--- a/packages/browser/src/Gamepad.ts
+++ b/packages/browser/src/Gamepad.ts
@@ -18,9 +18,9 @@
  * that waits for the button to bind; `parseRebinding(...)` validates
  * bindings saved as JSON.
  *
- * Polling happens on every `snapshot()`. A press and release that both fall
- * between two snapshots is missed unless the host also calls `poll()` more
- * often (each animation frame, for example). Browsers expose a pad only after
+ * The Gamepad API has no button events, so the pads are read on every
+ * animation frame and on every `snapshot()`; a tap that starts and ends
+ * between two updates still counts. Browsers expose a pad only after
  * a button is pressed on it, and only in a secure context (HTTPS or
  * localhost); elsewhere `navigator.getGamepads` is missing, and a game uses
  * `scripted(bindings, [])` as an idle stand-in.
@@ -30,15 +30,12 @@
  *
  * @example
  * ```ts
- * const pad = Gamepad.actions(navigator, {
+ * const pad = Gamepad.actions(window, {
  *   attack: ["west"],
  *   dash: ["south"],
  *   pause: ["start"]
  * })
  *
- * // Each animation frame (optional), so taps shorter than an update count:
- * pad.poll()
- *
  * // Once per update:
  * const snapshot = pad.snapshot()
  * move(snapshot.left)
@@ -55,6 +52,7 @@
  */
 import * as Result from "@typeonce/ritmo/Result"
 
+import type * as BrowserTickSource from "./BrowserTickSource.ts"
 import type { ActionState } from "./Keyboard.ts"
 
 /**
@@ -113,11 +111,19 @@ export interface PadReading {
   readonly axes: ReadonlyArray<number>
 }
 
-/** Where pads are read from, usually `navigator`. */
-export interface GamepadHost {
+/** Where pads are read from, the subset of the browser's `navigator` the module reads. */
+export interface GamepadNavigator {
   getGamepads(): ReadonlyArray<PadReading | null>
 }
 
+/**
+ * What live actions need from the window: the pads, and animation frames to
+ * read them on, since the Gamepad API has no button events.
+ */
+export interface GamepadHost extends BrowserTickSource.Host {
+  readonly navigator: GamepadNavigator
+}
+
 /** A stick's tilt with the dead zone removed: zero at rest, length 1 at full tilt. `y` grows down, as on screen. */
 export interface Vector {
   readonly x: number
@@ -140,22 +146,28 @@ export interface Snapshot<B extends Bindings> {
   readonly id: string | null
 }
 
+/**
+ * Rejects actions a rebinding names that the bindings do not have, so
+ * {@link Actions.rebind} takes exactly the actions it was made with.
+ */
+export type OnlyActionsOf<R, B extends Bindings> = {
+  readonly [Name in Exclude<keyof R, keyof B>]: `${Name & string} is not an action of these bindings`
+}
+
 export interface Actions<B extends Bindings> {
   /** Returns the input state and starts a new press/release window. */
   snapshot(): Snapshot<B>
-  /** Reads the pads now, so a press shorter than one update still counts. `snapshot()` polls too. */
-  poll(): void
   /**
    * Binds the same actions to new buttons, from the next snapshot, for a
    * settings screen where players remap controls (capture the button to bind
    * from the snapshot's `buttons`). An action held only through buttons it
    * lost reports `released`. A button held across the rebind holds a newly
    * bound action only once it is pressed again, so an action never turns
-   * held without a press. Buttons outside the actions it was made with are
-   * ignored.
+   * held without a press. It takes exactly the actions the source was made
+   * with.
    */
-  rebind(bindings: Rebinding<B>): void
-  /** Stops reading pads. */
+  rebind<const R extends Rebinding<B>>(bindings: R & OnlyActionsOf<R, B>): void
+  /** Stops reading pads and cancels the animation frame. */
   dispose(): void
 }
 
@@ -291,15 +303,16 @@ const isDown = (button: ButtonReading, index: number, triggerThreshold: number):
 /** Reads the pads, treating a host that throws (a blocked permission policy) as having none. */
 const readPads = (host: GamepadHost): ReadonlyArray<PadReading | null> => {
   try {
-    return host.getGamepads()
+    return host.navigator.getGamepads()
   } catch {
     return []
   }
 }
 
 /**
- * Starts reading pads from `host`. With several pads connected it follows
- * the one used last; a pad that disconnects releases everything it held.
+ * Starts reading pads from `host`, usually `window`, on every animation
+ * frame until `dispose()`. With several pads connected it follows the one
+ * used last; a pad that disconnects releases everything it held.
  */
 export const actions = <const B extends Bindings>(host: GamepadHost, bindings: B, options: ActionsOptions = {}): Actions<B> => {
   const deadZone = options.deadZone ?? 0.15
@@ -308,6 +321,7 @@ export const actions = <const B extends Bindings>(host: GamepadHost, bindings: B
   let followed: number | null = null
   let disposed = false
   let reading: PadReading | null = null
+  let frame = 0
 
   const poll = (): void => {
     if (disposed) return
@@ -330,6 +344,13 @@ export const actions = <const B extends Bindings>(host: GamepadHost, bindings: B
     }
   }
 
+  const onFrame = (): void => {
+    if (disposed) return
+    poll()
+    frame = host.requestAnimationFrame(onFrame)
+  }
+  frame = host.requestAnimationFrame(onFrame)
+
   return {
     snapshot() {
       poll()
@@ -346,10 +367,11 @@ export const actions = <const B extends Bindings>(host: GamepadHost, bindings: B
         id: pad.id
       })
     },
-    poll,
     rebind: state.rebind,
     dispose() {
+      if (disposed) return
       disposed = true
+      host.cancelAnimationFrame(frame)
       reading = null
       state.upAll()
     }
@@ -428,7 +450,6 @@ export const scripted = <const B extends Bindings>(bindings: B, timeline: Timeli
       frame += 1
       return state.snapshot({ ...analog, connected, id: connected ? "scripted" : null })
     },
-    poll() {},
     rebind: state.rebind,
     dispose() {},
     frames: () => frame
@@ -471,7 +492,6 @@ export const recording = <B extends Bindings>(actions: Actions<B>): Recording<B>
       frame += 1
       return snapshot
     },
-    poll: () => actions.poll(),
     rebind: (bindings) => actions.rebind(bindings),
     dispose: () => actions.dispose(),
     timeline: () => [...entries]
diff --git a/packages/browser/src/InputCapture.ts b/packages/browser/src/InputCapture.ts
index 6739400d..63370d85 100644
--- a/packages/browser/src/InputCapture.ts
+++ b/packages/browser/src/InputCapture.ts
@@ -10,7 +10,9 @@
  *
  * The source is any service with `snapshot()`: `Keyboard.actions(...)`
  * directly, or a game-specific adapter that merges several devices. The
- * resource's value type must be exactly the snapshot type.
+ * resource's value type must be exactly the snapshot type (declare it as
+ * `InputCapture.SnapshotOf<typeof Source>`): not a wider type, and not one
+ * with extra optional fields.
  *
  * Its spec is erased, so it does not count as a writer of the resource for
  * `Game.System.thisTick(...)` order checks: place it first yourself.
@@ -55,6 +57,15 @@ type ResourceDescriptor = Descriptor<"resource", string, any>
 export type SnapshotOf<Service extends ServiceDescriptor> =
   Descriptor.Value<Service> extends Source<infer Value> ? Value : never
 
+/** Whether `A` and `B` are the same type, not merely assignable both ways. */
+type Same<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false
+
+/** The resource when its value type is exactly the source's snapshot type, otherwise an error naming the fix. */
+type MatchingResource<Resource extends ResourceDescriptor, Service extends ServiceDescriptor> =
+  Same<Descriptor.Value<Resource>, SnapshotOf<Service>> extends true
+    ? Resource
+    : "The resource's value type must be exactly the source's snapshot type: declare it with InputCapture.SnapshotOf<typeof Source>"
+
 export interface Options<
   S extends Schema.Any,
   Service extends ServiceDescriptor,
@@ -66,7 +77,7 @@ export interface Options<
   /** The service to read snapshots from; its value must have `snapshot()`. */
   readonly source: Descriptor.Value<Service> extends Source<any> ? Service : "The source service must provide snapshot()"
   /** The resource to write each snapshot into; its value type must be exactly the snapshot type. */
-  readonly resource: Resource & Descriptor<"resource", string, SnapshotOf<Service>>
+  readonly resource: MatchingResource<Resource, Service>
   /**
    * Run conditions, like a system's `when`. While they fail, snapshots are
    * not taken, so presses stay in the device until capture resumes (for
@@ -95,7 +106,7 @@ export const system = <
   options: Options<S, Service, Resource, When>
 ): CaptureSystem<S, Root, Service | Resource | ConditionNeedsFromConditions<When>> =>
   Game.System(options.name, {
-    resources: { input: Game.System.writeResource(options.resource) },
+    resources: { input: Game.System.writeResource(options.resource as Resource) },
     services: { source: Game.System.service(options.source as Service) },
     when: (options.when ?? []) as ReadonlyArray<Condition<Root>>
   }, ({ resources, services }) => {
diff --git a/packages/browser/src/Keyboard.ts b/packages/browser/src/Keyboard.ts
index efea7e19..decd1ce7 100644
--- a/packages/browser/src/Keyboard.ts
+++ b/packages/browser/src/Keyboard.ts
@@ -143,6 +143,14 @@ export type Snapshot<B extends Bindings> = {
  */
 export type Rebinding<B extends Bindings> = { readonly [Action in keyof B]: readonly [KeyBinding, ...Array<KeyBinding>] }
 
+/**
+ * Rejects actions a rebinding names that the bindings do not have, so
+ * {@link Actions.rebind} takes exactly the actions it was made with.
+ */
+export type OnlyActionsOf<R, B extends Bindings> = {
+  readonly [Name in Exclude<keyof R, keyof B>]: `${Name & string} is not an action of these bindings`
+}
+
 export interface Actions<B extends Bindings> {
   /**
    * Returns every action's state and starts a new press/release window.
@@ -154,9 +162,9 @@ export interface Actions<B extends Bindings> {
    * with {@link presses}). An action held only through keys it lost reports
    * `released`. A key held across the rebind holds a newly bound action only
    * once it is pressed again, so an action never turns held without a
-   * press. Keys outside the actions it was made with are ignored.
+   * press. It takes exactly the actions the source was made with.
    */
-  rebind(bindings: Rebinding<B>): void
+  rebind<const R extends Rebinding<B>>(bindings: R & OnlyActionsOf<R, B>): void
   /**
    * Removes the event listeners.
    */
diff --git a/packages/browser/test/Gamepad.test.ts b/packages/browser/test/Gamepad.test.ts
index 1391377c..7f5c4402 100644
--- a/packages/browser/test/Gamepad.test.ts
+++ b/packages/browser/test/Gamepad.test.ts
@@ -24,10 +24,28 @@ const makePad = (index = 0, id = `pad ${index}`) => {
   }
 }
 
+/** A window whose pads the test sets and whose animation frames the test runs with `frame()`. */
 const makeHost = (...pads: Array<ReturnType<typeof makePad>>) => {
   const connected: Array<Gamepad.PadReading | null> = pads.map(({ pad }) => pad)
-  const host: Gamepad.GamepadHost = { getGamepads: () => connected }
-  return { host, connected }
+  const frames = new Map<number, (timestamp: number) => void>()
+  let next = 0
+  const host: Gamepad.GamepadHost = {
+    navigator: { getGamepads: () => connected },
+    requestAnimationFrame: (callback) => {
+      next += 1
+      frames.set(next, callback)
+      return next
+    },
+    cancelAnimationFrame: (handle) => {
+      frames.delete(handle)
+    }
+  }
+  const frame = () => {
+    const pending = [...frames.values()]
+    frames.clear()
+    for (const callback of pending) callback(0)
+  }
+  return { host, connected, frame, scheduled: () => frames.size }
 }
 
 const bindings = { attack: ["west"], dash: ["south", "rightBumper"], ultimate: ["rightTrigger"] } as const
@@ -58,12 +76,13 @@ describe("Gamepad.actions", () => {
     expect(input.snapshot().actions.dash).toEqual(released)
   })
 
-  it("keeps a tap that starts and ends between two snapshots when polled", () => {
+  it("keeps a tap that starts and ends between two snapshots, read on an animation frame", () => {
     const pad = makePad()
-    const input = Gamepad.actions(makeHost(pad).host, bindings)
+    const host = makeHost(pad)
+    const input = Gamepad.actions(host.host, bindings)
 
     pad.down("west")
-    input.poll()
+    host.frame()
     pad.up("west")
 
     expect(input.snapshot().actions.attack).toEqual({ held: false, pressed: true, released: true })
@@ -148,7 +167,8 @@ describe("Gamepad.actions", () => {
   })
 
   it("treats a host that throws as having no pads", () => {
-    const input = Gamepad.actions({ getGamepads: () => { throw new Error("blocked") } }, bindings)
+    const { host } = makeHost()
+    const input = Gamepad.actions({ ...host, navigator: { getGamepads: () => { throw new Error("blocked") } } }, bindings)
     expect(input.snapshot().connected).toBe(false)
   })
 
@@ -196,15 +216,30 @@ describe("Gamepad.actions", () => {
     expect(input.snapshot().actions.dash).toEqual(released)
   })
 
-  it("ignores actions a rebinding adds", () => {
+  it("ignores actions a rebinding adds at runtime", () => {
     const pad = makePad()
     const input = Gamepad.actions(makeHost(pad).host, bindings)
     const next = { attack: ["west"], dash: ["south"], ultimate: ["rightTrigger"], extra: ["north"] } as const
 
+    // The types reject it; the runtime ignores it too, for untyped callers.
+    // @ts-expect-error is not an action of these bindings
     input.rebind(next)
     expect(Object.keys(input.snapshot().actions)).toEqual(["attack", "dash", "ultimate"])
   })
 
+  it("reads on every animation frame until dispose, which cancels the frame", () => {
+    const pad = makePad()
+    const host = makeHost(pad)
+    const input = Gamepad.actions(host.host, bindings)
+
+    expect(host.scheduled()).toBe(1)
+    host.frame()
+    host.frame()
+    expect(host.scheduled()).toBe(1)
+    input.dispose()
+    expect(host.scheduled()).toBe(0)
+  })
+
   it("stops reading after dispose", () => {
     const pad = makePad()
     const input = Gamepad.actions(makeHost(pad).host, bindings)
@@ -271,15 +306,16 @@ describe("Gamepad.recording", () => {
 describe("Gamepad.recording release and press within one update", () => {
   it("replays a button released and pressed again between two snapshots", () => {
     const pad = makePad()
-    const live = Gamepad.recording(Gamepad.actions(makeHost(pad).host, bindings))
+    const host = makeHost(pad)
+    const live = Gamepad.recording(Gamepad.actions(host.host, bindings))
     const seen: Array<Gamepad.Snapshot<typeof bindings>> = []
 
     pad.down("west")
     seen.push(live.snapshot())
     pad.up("west")
-    live.poll()
+    host.frame()
     pad.down("west")
-    live.poll()
+    host.frame()
     seen.push(live.snapshot())
     expect(seen[1]!.actions.attack).toEqual({ held: true, pressed: true, released: false })
     expect(live.timeline()).toEqual([{ frame: 0, press: ["west"] }, { frame: 1, press: ["west"], release: ["west"] }])
diff --git a/packages/browser/test/Keyboard.test.ts b/packages/browser/test/Keyboard.test.ts
index 3795eb85..844ce3f4 100644
--- a/packages/browser/test/Keyboard.test.ts
+++ b/packages/browser/test/Keyboard.test.ts
@@ -238,11 +238,13 @@ describe("Keyboard.rebind", () => {
     expect(input.snapshot().jump).toEqual({ held: false, pressed: false, released: true })
   })
 
-  it("ignores actions a rebinding adds", () => {
+  it("ignores actions a rebinding adds at runtime", () => {
     const fake = makeHost()
     const input = Keyboard.actions(fake.host, { jump: [" "] })
     const next = { jump: ["w"], extra: ["x"] } as const
 
+    // The types reject it; the runtime ignores it too, for untyped callers.
+    // @ts-expect-error is not an action of these bindings
     input.rebind(next)
     expect(Object.keys(input.snapshot())).toEqual(["jump"])
   })

From 1b8a3c657435f19776ddc20ab25bbd4b02065798 Mon Sep 17 00:00:00 2001
From: SandroMaglione <lass.maglio@gmail.com>
Date: Thu, 22 Oct 2026 19:32:42 +0900
Subject: [PATCH 4/4] Record pad disconnects, and play the top-down integration
 with a gamepad

- Gamepad timeline entries take an optional `connected`: a disconnect
  releases every held button and zeroes the sticks and triggers, as with
  a live pad, and recordings write disconnects and reconnects, so a
  replay no longer stays connected after the pad drops.
- The top-down integration reads a gamepad next to the keyboard: a
  GamepadInput service, a PadState resource declared with
  InputCapture.SnapshotOf, its own capture system, the left stick at its
  analog length or the d-pad for walking, and south to interact, with
  headless tests for each.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/gamepad-actions.md                |  2 +-
 integration/top-down/debug.ts                |  8 ++--
 integration/top-down/math.ts                 | 23 +++++++---
 integration/top-down/runtime.ts              |  5 ++-
 integration/top-down/schedules.ts            |  4 +-
 integration/top-down/schema.ts               |  6 +++
 integration/top-down/simulation.ts           | 14 +++---
 integration/top-down/systems/index.ts        |  2 +-
 integration/top-down/systems/input.ts        | 10 ++++-
 integration/top-down/systems/interaction.ts  |  6 ++-
 integration/top-down/systems/movement.ts     |  7 +--
 integration/top-down/test/simulation.test.ts | 42 +++++++++++++++---
 integration/top-down/types.ts                | 11 ++++-
 packages/browser/src/Gamepad.ts              | 43 +++++++++++++-----
 packages/browser/test/Gamepad.test.ts        | 46 ++++++++++++++++++++
 15 files changed, 186 insertions(+), 43 deletions(-)

diff --git a/.changeset/gamepad-actions.md b/.changeset/gamepad-actions.md
index 6669b2e7..84f8e2ef 100644
--- a/.changeset/gamepad-actions.md
+++ b/.changeset/gamepad-actions.md
@@ -4,7 +4,7 @@
 
 **`Gamepad` reads controllers as named actions, and keyboard and gamepad bindings can change at runtime.**
 
-- **`Gamepad.actions(window, bindings, options)`** binds actions to buttons named by the browser's standard mapping (`"south"`, `"west"`, `"rightTrigger"`, `"dpadUp"`, `"start"`...). Each snapshot has `actions` (as `Keyboard`'s), every `buttons` state by name whatever the bindings (for menu navigation and for a settings screen waiting for the button to bind), the `left` and `right` sticks with a radial dead zone (`y` grows down, as `Touch`'s stick), how far each trigger is pulled, and the followed pad's `id`. It follows the pad used last and releases everything held when that pad disconnects. It reads the pads on every animation frame (and on every snapshot) until `dispose()`, so taps shorter than an update count with nothing to call; the lifecycle is `snapshot` / `rebind` / `dispose`, as for `Keyboard`. `Gamepad.idle`, `scripted`, `recording`, `parseTimeline`, and `isButton` match the other devices; timelines name buttons, so a replay follows the bindings.
+- **`Gamepad.actions(window, bindings, options)`** binds actions to buttons named by the browser's standard mapping (`"south"`, `"west"`, `"rightTrigger"`, `"dpadUp"`, `"start"`...). Each snapshot has `actions` (as `Keyboard`'s), every `buttons` state by name whatever the bindings (for menu navigation and for a settings screen waiting for the button to bind), the `left` and `right` sticks with a radial dead zone (`y` grows down, as `Touch`'s stick), how far each trigger is pulled, and the followed pad's `id`. It follows the pad used last and releases everything held when that pad disconnects. It reads the pads on every animation frame (and on every snapshot) until `dispose()`, so taps shorter than an update count with nothing to call; the lifecycle is `snapshot` / `rebind` / `dispose`, as for `Keyboard`. `Gamepad.idle`, `scripted`, `recording`, `parseTimeline`, and `isButton` match the other devices; timelines name buttons, so a replay follows the bindings, and an entry's `connected` records a disconnect or reconnect, so a replay drops and regains the pad on the same frames.
 - **`rebind(bindings)`** on `Keyboard.actions(...)` and `Gamepad.actions(...)` binds the same actions to new keys or buttons, for players who remap their controls. An action held only through a key it lost reports `released`; a key held across the rebind holds a newly bound action only after a fresh press, so an action never turns held without a press. It takes exactly the actions the source was made with: an extra action fails to compile with `<name> is not an action of these bindings`, even from an object not written inline. Scripted keyboard actions ignore it (their timeline names actions).
 - **`Keyboard.presses(window)`** reports every key that went down since the previous snapshot, bound or not, as `{ key, code }`, so a settings screen can wait for the key to bind (the gamepad equivalent is the snapshot's `buttons`).
 - **`Keyboard.parseRebinding(bindings, data)`** and **`Gamepad.parseRebinding(bindings, data)`** validate saved bindings (for example from `localStorage`) as a `Result` ready for `rebind`, with the offending `path` on failure.
diff --git a/integration/top-down/debug.ts b/integration/top-down/debug.ts
index b5d67f76..690d833f 100644
--- a/integration/top-down/debug.ts
+++ b/integration/top-down/debug.ts
@@ -11,14 +11,14 @@
  * the timeline, the invariants, and the questions.
  */
 import { HostClock } from "@typeonce/ritmo"
-import { Keyboard } from "@typeonce/ritmo-browser"
+import { Gamepad, Keyboard } from "@typeonce/ritmo-browser"
 import { Invariant, Session } from "@typeonce/ritmo-devtools"
 
 import { WORLD_HEIGHT, WORLD_WIDTH } from "./constants.ts"
 import { PlayerPositionQuery } from "./queries.ts"
 import { Game, Player, Position } from "./schema.ts"
 import { createTopDownSimulation } from "./simulation.ts"
-import { inputBindings } from "./types.ts"
+import { inputBindings, padBindings } from "./types.ts"
 
 // Frame 0 is the first update. Press and release are applied before that
 // frame's input capture; a press and release in one frame is a tap.
@@ -30,7 +30,9 @@ const keyboard = Keyboard.scripted(inputBindings, [
 
 // A test clock keeps every timing at 0, so the output is the same on every run.
 const hostClock = HostClock.test()
-const simulation = createTopDownSimulation({ keyboard, hostClock })
+// No controller in this run; script one the same way, by button names.
+const gamepad = Gamepad.scripted(padBindings, [])
+const simulation = createTopDownSimulation({ keyboard, gamepad, hostClock })
 if (!simulation.ok) throw new Error(simulation.error.message)
 const { runtime, setup, update } = simulation.value
 
diff --git a/integration/top-down/math.ts b/integration/top-down/math.ts
index 00cf728c..da257514 100644
--- a/integration/top-down/math.ts
+++ b/integration/top-down/math.ts
@@ -3,7 +3,8 @@ import * as InputAxis from "@typeonce/ritmo-math/InputAxis"
 import * as Scalar from "@typeonce/ritmo-math/Scalar"
 import * as Vector2Module from "@typeonce/ritmo-math/Vector2"
 import { WORLD_HEIGHT, WORLD_WIDTH } from "./constants.ts"
-import type { InputStateValue, Vector2 } from "./types.ts"
+import type { Gamepad } from "@typeonce/ritmo-browser"
+import type { InputStateValue, padBindings, Vector2 } from "./types.ts"
 
 export const clamp = (value: number, min: number, max: number): number => {
   const nextValue = Scalar.Finite.option(value)
@@ -18,13 +19,21 @@ export const clamp = (value: number, min: number, max: number): number => {
 
 export const lengthSquared = (vector: Vector2): number => Vector2Module.lengthSquared(vector)
 
-export const normalizeMovement = (input: InputStateValue): Vector2 =>
-  InputAxis.vectorFromAxes({
-    up: input.up.held,
-    down: input.down.held,
-    left: input.left.held,
-    right: input.right.held
+/**
+ * The walk direction from both devices: a tilted left stick wins and keeps
+ * its analog length (a half tilt walks at half speed); otherwise the keys
+ * and the d-pad give a unit direction.
+ */
+export const normalizeMovement = (keys: InputStateValue, pad: Gamepad.Snapshot<typeof padBindings>): Vector2 => {
+  const stick = Vector2Module.option(pad.left)
+  if (stick !== null && Vector2Module.lengthSquared(stick) > 0) return stick
+  return InputAxis.vectorFromAxes({
+    up: keys.up.held || pad.actions.up.held,
+    down: keys.down.held || pad.actions.down.held,
+    left: keys.left.held || pad.actions.left.held,
+    right: keys.right.held || pad.actions.right.held
   })
+}
 
 export const intersects = (
   firstPosition: Vector2,
diff --git a/integration/top-down/runtime.ts b/integration/top-down/runtime.ts
index 1876a5de..9ecece93 100644
--- a/integration/top-down/runtime.ts
+++ b/integration/top-down/runtime.ts
@@ -1,8 +1,8 @@
-import { Keyboard } from "@typeonce/ritmo-browser"
+import { Gamepad, Keyboard } from "@typeonce/ritmo-browser"
 
 import { pickupLayout } from "./content.ts"
 import { Facing, Game, Locomotion } from "./schema.ts"
-import { inputBindings } from "./types.ts"
+import { inputBindings, padBindings } from "./types.ts"
 import type { FrameContextValue } from "./types.ts"
 
 export const makeEmptyFocusedCollectable = () => ({
@@ -14,6 +14,7 @@ export const makeEmptyFocusedCollectable = () => ({
 export const initialResources = (frame: FrameContextValue) => ({
   DeltaTime: frame.deltaSeconds,
   InputState: Keyboard.idle(inputBindings),
+  PadState: Gamepad.idle(padBindings),
   FocusedCollectable: makeEmptyFocusedCollectable(),
   CollectedCount: 0,
   TotalCollectables: pickupLayout.length
diff --git a/integration/top-down/schedules.ts b/integration/top-down/schedules.ts
index 3fac4f12..ede03839 100644
--- a/integration/top-down/schedules.ts
+++ b/integration/top-down/schedules.ts
@@ -1,6 +1,7 @@
 import {
   CaptureFrameContextSystem,
   CaptureInputSystem,
+  CapturePadSystem,
   CollectFocusedCollectableSystem,
   MovePlayerSystem,
   PlanPlayerVelocitySystem,
@@ -17,10 +18,11 @@ export const setupWorldSchedule = Game.Schedule(
   Game.Schedule.applyDeferred()
 )
 
-/** One fixed update. It needs only the keyboard and the frame context, so it runs headless (see `simulation.ts`). */
+/** One fixed update. It needs only the keyboard, the gamepad, and the frame context, so it runs headless (see `simulation.ts`). */
 export const simulationSchedule = Game.Schedule(
   CaptureFrameContextSystem,
   CaptureInputSystem,
+  CapturePadSystem,
   PlanPlayerVelocitySystem,
   MovePlayerSystem,
   UpdateFocusedCollectableSystem,
diff --git a/integration/top-down/schema.ts b/integration/top-down/schema.ts
index 87221595..b86dd21a 100644
--- a/integration/top-down/schema.ts
+++ b/integration/top-down/schema.ts
@@ -1,9 +1,11 @@
 import { Descriptor, Entity, Schema } from "@typeonce/ritmo"
+import type { InputCapture } from "@typeonce/ritmo-browser"
 import * as Size2 from "@typeonce/ritmo-math/Size2"
 import * as Vector2 from "@typeonce/ritmo-math/Vector2"
 
 import type {
   FrameContextValue,
+  GamepadInput as GamepadInputValue,
   InputStateValue,
   KeyboardInput as KeyboardInputValue
 } from "./types.ts"
@@ -34,6 +36,9 @@ export const CollectedCount = Descriptor.Resource<number>()("TopDown/CollectedCo
 export const TotalCollectables = Descriptor.Resource<number>()("TopDown/TotalCollectables")
 
 export const KeyboardInput = Descriptor.Service<KeyboardInputValue>()("TopDown/KeyboardInput")
+export const GamepadInput = Descriptor.Service<GamepadInputValue>()("TopDown/GamepadInput")
+// Captured from the gamepad at the start of each update; its type is exactly what the source produces.
+export const PadState = Descriptor.TransientResource<InputCapture.SnapshotOf<typeof GamepadInput>>()("TopDown/PadState")
 export const FrameContext = Descriptor.Service<FrameContextValue>()("TopDown/FrameContext")
 
 export const Game = Schema.bind(
@@ -56,6 +61,7 @@ export const Game = Schema.bind(
     resources: {
       DeltaTime,
       InputState,
+      PadState,
       FocusedCollectable,
       CollectedCount,
       TotalCollectables
diff --git a/integration/top-down/simulation.ts b/integration/top-down/simulation.ts
index ece317a8..2ba85c10 100644
--- a/integration/top-down/simulation.ts
+++ b/integration/top-down/simulation.ts
@@ -1,13 +1,14 @@
 /**
  * The top-down game without a browser: the simulation schedules on a
- * runtime that needs only a keyboard and a frame context, with the debug
- * handle attached.
+ * runtime that needs only a keyboard, a gamepad, and a frame context, with
+ * the debug handle attached.
  *
  * Tests, benchmarks, and coding agents drive it directly:
  *
  * ```ts
  * const keyboard = Keyboard.scripted(inputBindings, [{ frame: 0, press: ["right"] }])
- * const simulation = createTopDownSimulation({ keyboard, hostClock: HostClock.test() })
+ * const gamepad = Gamepad.scripted(padBindings, [])
+ * const simulation = createTopDownSimulation({ keyboard, gamepad, hostClock: HostClock.test() })
  * if (simulation.ok) {
  *   simulation.value.runtime.tick(simulation.value.setup)
  *   simulation.value.runtime.tick(simulation.value.update)
@@ -19,12 +20,14 @@ import * as Result from "@typeonce/ritmo/Result"
 
 import { FIXED_STEP_SECONDS } from "./constants.ts"
 import { initialMachines, initialResources } from "./runtime.ts"
-import { FrameContext, Game, KeyboardInput } from "./schema.ts"
+import { FrameContext, Game, GamepadInput, KeyboardInput } from "./schema.ts"
 import { setupWorldSchedule, simulationSchedule } from "./schedules.ts"
-import type { FrameContextValue, KeyboardInput as KeyboardInputValue } from "./types.ts"
+import type { FrameContextValue, GamepadInput as GamepadInputValue, KeyboardInput as KeyboardInputValue } from "./types.ts"
 
 export interface TopDownSimulationOptions {
   readonly keyboard: KeyboardInputValue
+  /** `Gamepad.actions(window, padBindings)` in a browser, `Gamepad.scripted(padBindings, timeline)` headless. */
+  readonly gamepad: GamepadInputValue
   /** Times the debug traces; `HostClock.test()` keeps every timing at 0. Pass the same clock to `Session.make`. */
   readonly hostClock: HostClock.HostClock
   /** Defaults to one fixed step at 60 Hz. */
@@ -40,6 +43,7 @@ export const createTopDownSimulation = (options: TopDownSimulationOptions) => {
   const made = Game.Runtime.make({
     services: Game.Runtime.services(
       Game.Runtime.service(KeyboardInput, options.keyboard),
+      Game.Runtime.service(GamepadInput, options.gamepad),
       Game.Runtime.service(FrameContext, frame)
     ),
     resources: initialResources(frame),
diff --git a/integration/top-down/systems/index.ts b/integration/top-down/systems/index.ts
index 3facef3e..f34d0e87 100644
--- a/integration/top-down/systems/index.ts
+++ b/integration/top-down/systems/index.ts
@@ -1,5 +1,5 @@
 export { SetupWorldSystem } from "./setup.ts"
-export { CaptureFrameContextSystem, CaptureInputSystem } from "./input.ts"
+export { CaptureFrameContextSystem, CaptureInputSystem, CapturePadSystem } from "./input.ts"
 export { PlanPlayerVelocitySystem, MovePlayerSystem } from "./movement.ts"
 export { UpdateFocusedCollectableSystem, CollectFocusedCollectableSystem } from "./interaction.ts"
 export { ResolveFacingSystem, ResolveLocomotionSystem } from "./facing.ts"
diff --git a/integration/top-down/systems/input.ts b/integration/top-down/systems/input.ts
index ab9e7c7a..741d5639 100644
--- a/integration/top-down/systems/input.ts
+++ b/integration/top-down/systems/input.ts
@@ -3,8 +3,10 @@ import {
   DeltaTime,
   FrameContext,
   Game,
+  GamepadInput,
   InputState,
-  KeyboardInput
+  KeyboardInput,
+  PadState
 } from "../schema.ts"
 
 export const CaptureInputSystem = InputCapture.system(Game, {
@@ -13,6 +15,12 @@ export const CaptureInputSystem = InputCapture.system(Game, {
   resource: InputState
 })
 
+export const CapturePadSystem = InputCapture.system(Game, {
+  name: "TopDown/CapturePad",
+  source: GamepadInput,
+  resource: PadState
+})
+
 export const CaptureFrameContextSystem = Game.System(
   "TopDown/CaptureFrameContext",
   {
diff --git a/integration/top-down/systems/interaction.ts b/integration/top-down/systems/interaction.ts
index aef691ec..e6c89f99 100644
--- a/integration/top-down/systems/interaction.ts
+++ b/integration/top-down/systems/interaction.ts
@@ -5,7 +5,8 @@ import {
   Collectable,
   FocusedCollectable,
   Game,
-  InputState
+  InputState,
+  PadState
 } from "../schema.ts"
 import { makeEmptyFocusedCollectable } from "../runtime.ts"
 
@@ -64,6 +65,7 @@ export const CollectFocusedCollectableSystem = Game.System(
     },
     resources: {
       input: Game.System.readResource(InputState),
+      pad: Game.System.readResource(PadState),
       focused: Game.System.writeResource(FocusedCollectable),
       collectedCount: Game.System.writeResource(CollectedCount)
     },
@@ -71,7 +73,7 @@ export const CollectFocusedCollectableSystem = Game.System(
   },
   ({ queries, resources, commands }) =>
     {
-      if (!resources.input.get().interact.pressed) {
+      if (!resources.input.get().interact.pressed && !resources.pad.get().actions.interact.pressed) {
         return
       }
 
diff --git a/integration/top-down/systems/movement.ts b/integration/top-down/systems/movement.ts
index f5ae466e..11030eb9 100644
--- a/integration/top-down/systems/movement.ts
+++ b/integration/top-down/systems/movement.ts
@@ -3,7 +3,7 @@ import * as Vector2 from "@typeonce/ritmo-math/Vector2"
 import { PLAYER_SPEED } from "../constants.ts"
 import { normalizeMovement, resolveHorizontalMovement, resolveVerticalMovement } from "../math.ts"
 import { PlayerMovementQuery, WallCollisionQuery } from "../queries.ts"
-import { DeltaTime, Game, InputState } from "../schema.ts"
+import { DeltaTime, Game, InputState, PadState } from "../schema.ts"
 
 export const PlanPlayerVelocitySystem = Game.System(
   "TopDown/PlanPlayerVelocity",
@@ -12,7 +12,8 @@ export const PlanPlayerVelocitySystem = Game.System(
       player: PlayerMovementQuery
     },
     resources: {
-      input: Game.System.readResource(InputState)
+      input: Game.System.readResource(InputState),
+      pad: Game.System.readResource(PadState)
     }
   },
   ({ queries, resources }) =>
@@ -22,7 +23,7 @@ export const PlanPlayerVelocitySystem = Game.System(
         return
       }
 
-      const direction = normalizeMovement(resources.input.get())
+      const direction = normalizeMovement(resources.input.get(), resources.pad.get())
       player.value.data.velocity.updateRaw(() =>
         ({
           x: direction.x * PLAYER_SPEED,
diff --git a/integration/top-down/test/simulation.test.ts b/integration/top-down/test/simulation.test.ts
index d915c911..10fb36b6 100644
--- a/integration/top-down/test/simulation.test.ts
+++ b/integration/top-down/test/simulation.test.ts
@@ -1,15 +1,19 @@
 import { HostClock } from "@typeonce/ritmo"
-import { Keyboard } from "@typeonce/ritmo-browser"
+import { Gamepad, Keyboard } from "@typeonce/ritmo-browser"
 import { Session } from "@typeonce/ritmo-devtools"
 import { describe, expect, it } from "vitest"
 
 import { createTopDownSimulation } from "../simulation.ts"
 import { PlayerPositionQuery } from "../queries.ts"
 import { CollectedCount, Game } from "../schema.ts"
-import { inputBindings } from "../types.ts"
+import { inputBindings, padBindings } from "../types.ts"
 
-const start = (timeline: Keyboard.Timeline<typeof inputBindings>) => {
-  const simulation = createTopDownSimulation({ keyboard: Keyboard.scripted(inputBindings, timeline), hostClock: HostClock.test() })
+const start = (timeline: Keyboard.Timeline<typeof inputBindings>, pad: Gamepad.Timeline = []) => {
+  const simulation = createTopDownSimulation({
+    keyboard: Keyboard.scripted(inputBindings, timeline),
+    gamepad: Gamepad.scripted(padBindings, pad),
+    hostClock: HostClock.test()
+  })
   if (!simulation.ok) throw new Error(simulation.error.message)
   const { runtime, setup, update } = simulation.value
   expect(runtime.tick(setup).ok).toBe(true)
@@ -19,6 +23,9 @@ const start = (timeline: Keyboard.Timeline<typeof inputBindings>) => {
 const PlayerPosition = Game.Inspector("Test/PlayerPosition", { queries: { player: PlayerPositionQuery } }, ({ queries }) =>
   queries.player.each().map((match) => match.data.position.get()))
 
+const Collected = Game.Inspector("Test/Collected", { resources: { count: Game.System.readResource(CollectedCount) } }, ({ resources }) =>
+  resources.count.get())
+
 describe("top-down simulation", () => {
   it("runs headless and moves the player with scripted input", () => {
     const { runtime, update } = start([{ frame: 0, press: ["right"] }, { frame: 30, release: ["right"] }])
@@ -32,6 +39,31 @@ describe("top-down simulation", () => {
     })
   })
 
+  it("moves the player with the left stick, at its analog length", () => {
+    const { runtime, update } = start([], [{ frame: 0, left: { x: 0.5, y: 0 } }, { frame: 30, left: { x: 0, y: 0 } }])
+    for (let frame = 0; frame < 60; frame++) expect(runtime.tick(update).ok).toBe(true)
+    const [position] = runtime.inspect(PlayerPosition)
+    expect(position?.x).toBeCloseTo(640 + 0.5 * 280 * 30 / 60)
+    expect(position?.y).toBe(260)
+  })
+
+  it("moves the player with the d-pad like the arrow keys", () => {
+    const { runtime, update } = start([], [{ frame: 0, press: ["dpadRight"] }, { frame: 30, release: ["dpadRight"] }])
+    for (let frame = 0; frame < 60; frame++) expect(runtime.tick(update).ok).toBe(true)
+    const [position] = runtime.inspect(PlayerPosition)
+    expect(position?.x).toBeCloseTo(640 + 280 * 30 / 60)
+  })
+
+  it("collects a pickup with the south button", () => {
+    const { runtime, update } = start([], [
+      { frame: 0, press: ["dpadLeft"] },
+      { frame: 85, release: ["dpadLeft"] },
+      { frame: 88, press: ["south"], release: ["south"] }
+    ])
+    for (let frame = 0; frame < 120; frame++) expect(runtime.tick(update).ok).toBe(true)
+    expect(runtime.inspect(Collected)).toBe(1)
+  })
+
   it("describes the simulation schedules without lint warnings", () => {
     const { runtime } = start([])
     const description = runtime.debug.describe()
@@ -48,7 +80,7 @@ describe("top-down debug session", () => {
       { frame: 88, press: ["interact"], release: ["interact"] }
     ])
     const hostClock = HostClock.test()
-    const simulation = createTopDownSimulation({ keyboard, hostClock })
+    const simulation = createTopDownSimulation({ keyboard, gamepad: Gamepad.scripted(padBindings, []), hostClock })
     if (!simulation.ok) throw new Error(simulation.error.message)
     const { runtime, setup, update } = simulation.value
     const session = Session.make(runtime, { hostClock, schedules: { setup, update } })
diff --git a/integration/top-down/types.ts b/integration/top-down/types.ts
index 011f63b9..246028e4 100644
--- a/integration/top-down/types.ts
+++ b/integration/top-down/types.ts
@@ -1,4 +1,4 @@
-import type { Keyboard } from "@typeonce/ritmo-browser"
+import type { Gamepad, Keyboard } from "@typeonce/ritmo-browser"
 import type * as Vector2Value from "@typeonce/ritmo-math/Vector2"
 
 export type Vector2 = Vector2Value.Vector2
@@ -11,6 +11,15 @@ export const inputBindings = {
 } as const
 export type InputStateValue = Keyboard.Snapshot<typeof inputBindings>
 export type KeyboardInput = Keyboard.Actions<typeof inputBindings>
+/** The same actions on a controller: the d-pad walks (the left stick too, see `normalizeMovement`), south interacts. */
+export const padBindings = {
+  up: ["dpadUp"],
+  down: ["dpadDown"],
+  left: ["dpadLeft"],
+  right: ["dpadRight"],
+  interact: ["south"]
+} as const
+export type GamepadInput = Gamepad.Actions<typeof padBindings>
 /** What one fixed update needs from the host: the step length. */
 export type FrameContextValue = {
   readonly deltaSeconds: number
diff --git a/packages/browser/src/Gamepad.ts b/packages/browser/src/Gamepad.ts
index 723682d1..b77fa49b 100644
--- a/packages/browser/src/Gamepad.ts
+++ b/packages/browser/src/Gamepad.ts
@@ -380,14 +380,20 @@ export const actions = <const B extends Bindings>(host: GamepadHost, bindings: B
 
 /**
  * Input changes applied just before one snapshot: the buttons, then the
- * sticks and triggers, which keep their value until set again. `frame` is the
- * snapshot's index, counting from 0 at the first `snapshot()` call. A button
- * in both `press` and `release` changed twice within the frame: a tap
- * shorter than a frame when it was up, a release and a new press when it was
- * held.
+ * sticks and triggers, which keep their value until set again, then
+ * `connected`. `frame` is the snapshot's index, counting from 0 at the first
+ * `snapshot()` call. A button in both `press` and `release` changed twice
+ * within the frame: a tap shorter than a frame when it was up, a release and
+ * a new press when it was held.
  */
 export interface TimelineEntry {
   readonly frame: number
+  /**
+   * Connects or disconnects the pad from this frame on. The first entry
+   * connects it unless it says otherwise. A disconnect releases every held
+   * button and zeroes the sticks and triggers, as with a live pad.
+   */
+  readonly connected?: boolean
   readonly press?: ReadonlyArray<Button>
   readonly release?: ReadonlyArray<Button>
   readonly left?: Vector
@@ -411,7 +417,8 @@ export interface Scripted<B extends Bindings> extends Actions<B> {
 
 /**
  * Plays `timeline`: before the snapshot at index `frame`, every entry for
- * that frame is applied. A pad counts as connected from the first entry on.
+ * that frame is applied. A pad counts as connected from the first entry on,
+ * until an entry says `connected: false`.
  * Buttons stay held from their press until their release; pressing a held
  * button is not a new press.
  */
@@ -424,7 +431,9 @@ export const scripted = <const B extends Bindings>(bindings: B, timeline: Timeli
     else byFrame.set(entry.frame, [entry])
   }
   const first = timeline.reduce((earliest, entry) => Math.min(earliest, entry.frame), Number.POSITIVE_INFINITY)
-  let analog = { left: zero, right: zero, leftTrigger: 0, rightTrigger: 0 }
+  const resting = { left: zero, right: zero, leftTrigger: 0, rightTrigger: 0 }
+  let analog = resting
+  let connected = false
   let frame = 0
   return {
     snapshot() {
@@ -445,8 +454,12 @@ export const scripted = <const B extends Bindings>(bindings: B, timeline: Timeli
           leftTrigger: entry.leftTrigger ?? analog.leftTrigger,
           rightTrigger: entry.rightTrigger ?? analog.rightTrigger
         }
+        connected = entry.connected ?? (frame === first ? true : connected)
+        if (!connected) {
+          state.upAll()
+          analog = resting
+        }
       }
-      const connected = frame >= first
       frame += 1
       return state.snapshot({ ...analog, connected, id: connected ? "scripted" : null })
     },
@@ -470,7 +483,7 @@ const sameVector = (a: Vector, b: Vector): boolean => a.x === b.x && a.y === b.y
  */
 export const recording = <B extends Bindings>(actions: Actions<B>): Recording<B> => {
   const entries: Array<TimelineEntry> = []
-  let previous: Pick<Snapshot<B>, "buttons" | "left" | "right" | "leftTrigger" | "rightTrigger"> = { buttons: idleButtons(), left: zero, right: zero, leftTrigger: 0, rightTrigger: 0 }
+  let previous: Omit<Snapshot<B>, "actions" | "id"> = { buttons: idleButtons(), left: zero, right: zero, leftTrigger: 0, rightTrigger: 0, connected: false }
   let frame = 0
   return {
     snapshot() {
@@ -484,7 +497,9 @@ export const recording = <B extends Bindings>(actions: Actions<B>): Recording<B>
         ...(sameVector(snapshot.left, previous.left) ? {} : { left: snapshot.left }),
         ...(sameVector(snapshot.right, previous.right) ? {} : { right: snapshot.right }),
         ...(snapshot.leftTrigger === previous.leftTrigger ? {} : { leftTrigger: snapshot.leftTrigger }),
-        ...(snapshot.rightTrigger === previous.rightTrigger ? {} : { rightTrigger: snapshot.rightTrigger })
+        ...(snapshot.rightTrigger === previous.rightTrigger ? {} : { rightTrigger: snapshot.rightTrigger }),
+        // The first entry connects the pad by itself; later changes are written out.
+        ...(snapshot.connected === previous.connected || entries.length === 0 ? {} : { connected: snapshot.connected })
       }
       // The first entry also marks when a pad appeared, so a replay connects on the same frame.
       if (Object.keys(entry).length > 0 || (entries.length === 0 && snapshot.connected)) entries.push({ frame, ...entry })
@@ -517,7 +532,8 @@ export const isButton = (name: unknown): name is Button => typeof name === "stri
  * Validates untrusted data, such as a parsed JSON file, as a timeline: an
  * array of entries with a non-negative integer `frame`, optional
  * `press`/`release` arrays of button names, optional `left`/`right` vectors
- * of length at most 1, and optional triggers from 0 to 1.
+ * of length at most 1, optional triggers from 0 to 1, and an optional
+ * boolean `connected`.
  */
 export const parseTimeline = (data: unknown): Result.Result<Timeline, InvalidTimeline> => {
   const invalid = (path: string, message: string) => Result.failure<InvalidTimeline>({ _tag: "InvalidTimeline", path, message })
@@ -555,6 +571,11 @@ export const parseTimeline = (data: unknown): Result.Result<Timeline, InvalidTim
       if (typeof value !== "number" || !(value >= 0 && value <= 1)) return invalid(`${path}.${field}`, "expected a number from 0 to 1")
       parsed[field] = value
     }
+    const connected = fields["connected"]
+    if (connected !== undefined) {
+      if (typeof connected !== "boolean") return invalid(`${path}.connected`, "expected a boolean")
+      parsed["connected"] = connected
+    }
     entries.push(parsed as unknown as TimelineEntry)
   }
   return Result.success(entries)
diff --git a/packages/browser/test/Gamepad.test.ts b/packages/browser/test/Gamepad.test.ts
index 7f5c4402..2937fe59 100644
--- a/packages/browser/test/Gamepad.test.ts
+++ b/packages/browser/test/Gamepad.test.ts
@@ -330,6 +330,52 @@ describe("Gamepad.recording release and press within one update", () => {
   })
 })
 
+describe("Gamepad timelines and disconnects", () => {
+  it("records a disconnect and a reconnect, and replays them", () => {
+    const pad = makePad()
+    const host = makeHost(pad)
+    const live = Gamepad.recording(Gamepad.actions(host.host, bindings))
+    const seen: Array<Gamepad.Snapshot<typeof bindings>> = []
+
+    pad.down("west")
+    pad.tilt("left", 1, 0)
+    seen.push(live.snapshot())
+    host.connected.length = 0
+    seen.push(live.snapshot())
+    seen.push(live.snapshot())
+    host.connected.push(pad.pad)
+    seen.push(live.snapshot())
+    expect(seen.map((snapshot) => snapshot.connected)).toEqual([true, false, false, true])
+    expect(live.timeline()[1]).toMatchObject({ frame: 1, release: ["west"], connected: false })
+    expect(live.timeline()[2]).toMatchObject({ frame: 3, press: ["west"], connected: true })
+
+    const parsed = Gamepad.parseTimeline(JSON.parse(JSON.stringify(live.timeline())))
+    expect(parsed.ok).toBe(true)
+    if (!parsed.ok) return
+    const replay = Gamepad.scripted(bindings, parsed.value)
+    for (const snapshot of seen) {
+      const replayed = replay.snapshot()
+      expect(replayed.actions).toEqual(snapshot.actions)
+      expect(replayed.buttons).toEqual(snapshot.buttons)
+      expect(replayed.left).toEqual(snapshot.left)
+      expect(replayed.connected).toBe(snapshot.connected)
+    }
+  })
+
+  it("releases everything and zeroes the sticks when a scripted pad disconnects", () => {
+    const replay = Gamepad.scripted(bindings, [
+      { frame: 0, press: ["west"], left: { x: 1, y: 0 }, rightTrigger: 1 },
+      { frame: 1, connected: false }
+    ])
+    replay.snapshot()
+    expect(replay.snapshot()).toEqual({ ...Gamepad.idle(bindings), actions: { ...Gamepad.idle(bindings).actions, attack: released }, buttons: { ...Gamepad.idle(bindings).buttons, west: released } })
+  })
+
+  it("rejects a connected flag that is not a boolean", () => {
+    expect(Gamepad.parseTimeline([{ frame: 0, connected: "yes" }])).toMatchObject({ ok: false, error: { path: "[0].connected" } })
+  })
+})
+
 describe("Gamepad.parseRebinding", () => {
   it("accepts the same actions bound to button names", () => {
     const parsed = Gamepad.parseRebinding(bindings, JSON.parse('{"attack":["north"],"dash":["south","east"],"ultimate":["leftTrigger"]}'))