@typeonce/ritmo-browser 0.10.0 → 0.12.0

package/src/Touch.ts

@@ -28,8 +28,9 @@
  *
  * @example
  * ```ts
- * const touch = Touch.track(canvas, window, ({ width, height }) => ({
- *   stick: { region: { left: 0, top: 0, width: width / 2, height }, radius: 60 },
+ * const touch = Touch.actions(canvas, window, ({ width, height }) => ({
+ *   // `vector` names the action the stick drives, so it merges into `Controls`.
+ *   stick: { region: { left: 0, top: 0, width: width / 2, height }, radius: 60, vector: "move" },
  *   buttons: {
  *     attack: { center: { x: width - 90, y: height - 90 }, radius: 55, aimRadius: 80 },
  *     dash: { center: { x: width - 200, y: height - 60 }, radius: 36 }
@@ -37,15 +38,18 @@
  * }))
  *
  * // Once per update:
- * const { stick, buttons } = touch.snapshot()
- * move(stick.vector)
- * if (buttons.attack.released && !buttons.attack.cancelled) fire(buttons.attack.aim)
+ * const { vectors, actions } = touch.snapshot()
+ * move(vectors.move)
+ * if (actions.attack.released && !actions.attack.cancelled) fire(actions.attack.aim)
  * ```
  *
  * For tests and headless runs, `scripted(...)` plays a timeline of stick
  * vectors, presses, drags, and releases.
  */
-import type { ActionState } from "./Keyboard.ts"
+import type * as System from "@typeonce/ritmo/System"
+import { anyUsed } from "./internal/used.ts"
+import type { ActionState } from "./internal/state.ts"
+import type { Vector } from "./internal/vectors.ts"
 
 /** A position in CSS pixels relative to the element's top-left corner. */
 export interface Position {
@@ -53,12 +57,7 @@ export interface Position {
   readonly y: number
 }
 
-/** A direction and strength, with length at most 1. `y` grows down the screen. */
-export interface Vector {
-  readonly x: number
-  readonly y: number
-}
-
+/** A rectangle in CSS pixels relative to the element's top-left corner. */
 export interface Rect {
   readonly left: number
   readonly top: number
@@ -66,15 +65,19 @@ export interface Rect {
   readonly height: number
 }
 
-export interface StickZone {
+/** The floating stick of a {@link Layout}. */
+export interface StickZone<V extends string = never> {
   /** Where a touch starts the stick. The stick is centered where the thumb lands. */
   readonly region: Rect
   /** Drag distance in CSS pixels for full tilt. */
   readonly radius: number
   /** Fraction of `radius` that reads as zero. Defaults to 0.15. */
   readonly deadZone?: number
+  /** The vector action the stick drives (`"move"`), reported in the snapshot's `vectors`. */
+  readonly vector?: V
 }
 
+/** A round on-screen button of a {@link Layout}; it reports the action named like its key. */
 export interface ButtonZone {
   readonly center: Position
   /** Touch radius in CSS pixels. */
@@ -85,13 +88,18 @@ export interface ButtonZone {
   readonly aimDeadZone?: number
 }
 
+/** The swipe area of a {@link Layout}. */
 export interface SwipeZone {
   /** Where a touch that is not on a button or the stick starts a swipe. */
   readonly region: Rect
 }
 
-export interface Layout<B extends string> {
-  readonly stick: StickZone
+/**
+ * The touch controls, returned by the layout function {@link actions} calls
+ * with the element's size. The button names are fixed by the first layout.
+ */
+export interface Layout<B extends string, V extends string = never> {
+  readonly stick: StickZone<V>
   readonly buttons: { readonly [K in B]: ButtonZone }
   /** Optional: fingers here report their movement, for turning or looking around. */
   readonly swipe?: SwipeZone
@@ -103,6 +111,7 @@ export interface Size {
   readonly height: number
 }
 
+/** The stick's state in a snapshot. */
 export interface Stick {
   /** Whether a thumb is on the stick. */
   readonly active: boolean
@@ -110,6 +119,7 @@ export interface Stick {
   readonly vector: Vector
 }
 
+/** One button's state: its action's edges, plus the drag aim and whether the release was cancelled. */
 export interface ButtonState extends ActionState {
   /**
    * The drag from the button's center as a fraction of `aimRadius` (length at
@@ -121,6 +131,7 @@ export interface ButtonState extends ActionState {
   readonly cancelled: boolean
 }
 
+/** The swipe area's state in a snapshot. */
 export interface Swipe {
   /** Whether a finger is on the swipe area. */
   readonly active: boolean
@@ -128,27 +139,57 @@ export interface Swipe {
   readonly delta: Vector
 }
 
-export interface Snapshot<B extends string> {
+/**
+ * The controls' state. Each button is an action named like it, and the
+ * stick drives the vector action its layout names, so the snapshot has the
+ * same core as the other devices' (`actions`, `vectors`, and `used`) and
+ * `Controls` can merge it.
+ */
+export interface Snapshot<B extends string, V extends string = never> {
   readonly stick: Stick
-  readonly buttons: { readonly [K in B]: ButtonState }
+  readonly actions: { readonly [K in B]: ButtonState }
+  /** The vector action the stick drives, when the layout names one: the stick's vector. */
+  readonly vectors: { readonly [K in V]: Vector }
   readonly swipe: Swipe
-  /** Whether any tracked touch has been seen, for switching controls on. */
-  readonly touched: boolean
+  /**
+   * A button was pressed in this window or is held, or a finger is on the
+   * stick or the swipe area: the player is using the touch controls.
+   */
+  readonly used: boolean
 }
 
+const snapshotOf = <B extends string, V extends string>(
+  vector: V | undefined,
+  stick: Stick,
+  actions: { readonly [K in B]: ButtonState },
+  swipe: Swipe
+): Snapshot<B, V> => ({
+  stick,
+  actions,
+  vectors: (vector === undefined ? {} : { [vector]: stick.vector }) as { readonly [K in V]: Vector },
+  swipe,
+  used: stick.active || swipe.active || anyUsed(actions)
+})
+
 /** Live control positions for drawing, in CSS pixels. Reading it consumes nothing. */
-export interface View<B extends string> {
-  readonly layout: Layout<B>
+export interface View<B extends string, V extends string = never> {
+  readonly layout: Layout<B, V>
   /** Where the stick was centered and where the thumb is, while it is held. */
   readonly stick: { readonly origin: Position; readonly knob: Position } | null
   readonly buttons: { readonly [K in B]: { readonly held: boolean; readonly aim: Vector | null } }
 }
 
-export interface Touch<B extends string> {
+/**
+ * Touch controls, built with {@link actions} (live) or {@link scripted}.
+ * Capture them with `InputCapture.system(...)`, or merge them with
+ * `Controls` (through `lacking(...)` for actions with no on-screen
+ * control). There is no `rebind`: the layout is the binding.
+ */
+export interface Actions<B extends string, V extends string = never> extends System.Consumes<"snapshot"> {
   /** Returns the controls' state and starts a new press/release window. */
-  snapshot(): Snapshot<B>
+  snapshot(): Snapshot<B, V>
   /** The live state for drawing. */
-  view(): View<B>
+  view(): View<B, V>
   /** Removes the event listeners and restores the element's `touch-action`. */
   dispose(): void
 }
@@ -177,7 +218,8 @@ export interface BlurHost {
   removeEventListener(type: "blur", listener: () => void): void
 }
 
-export interface TrackOptions {
+/** Options for {@link actions}. */
+export interface ActionsOptions {
   /** `PointerEvent.pointerType`s that drive the controls. Defaults to `["touch"]`. */
   readonly pointerTypes?: ReadonlyArray<string>
 }
@@ -186,13 +228,25 @@ const zero: Vector = { x: 0, y: 0 }
 
 const released = (): ButtonState => ({ held: false, pressed: false, released: false, aim: null, cancelled: false })
 
-/** A snapshot with nothing held, for initializing an input resource before the first capture. */
-export const idle = <const B extends string>(buttons: ReadonlyArray<B>): Snapshot<B> => ({
-  stick: { active: false, vector: zero },
-  buttons: Object.fromEntries(buttons.map((button) => [button, released()])) as { readonly [K in B]: ButtonState },
-  swipe: { active: false, delta: zero },
-  touched: false
-})
+/** The names a layout's controls report, for {@link idle} and {@link scripted}. */
+export interface Names<B extends string, V extends string = never> {
+  readonly buttons: ReadonlyArray<B>
+  /** The vector action the stick drives, as the layout's `stick.vector`. */
+  readonly vector?: V
+}
+
+/**
+ * A snapshot with nothing held, for initializing an input resource before
+ * the first capture: pass the layout's button names and stick vector, as
+ * `Touch.idle({ buttons: ["attack", "dash"], vector: "move" })`.
+ */
+export const idle = <const B extends string, const V extends string = never>(names: Names<B, V>): Snapshot<B, V> =>
+  snapshotOf<B, V>(
+    names.vector,
+    { active: false, vector: zero },
+    Object.fromEntries(names.buttons.map((button) => [button, released()])) as { readonly [K in B]: ButtonState },
+    { active: false, delta: zero }
+  )
 
 /** `offset / radius`, clamped to length 1, with the inner `deadZone` fraction mapped to zero. */
 const tilt = (offset: Position, radius: number, deadZone: number): Vector => {
@@ -261,14 +315,15 @@ const lift = (track: ButtonTrack, cancelled: boolean): void => {
  * Starts tracking touches over `target` with the controls `layout` returns
  * for the element's current size (it is read again on every new touch, so a
  * resize takes effect at the next touch). `blurHost` (usually `window`)
- * cancels held controls when the page loses focus.
+ * cancels held controls when the page loses focus. Use `Pointer.actions`
+ * for mouse and pen input.
  */
-export const track = <const B extends string>(
+export const actions = <const B extends string, const V extends string = never>(
   target: TouchTarget,
   blurHost: BlurHost,
-  layout: (size: Size) => Layout<B>,
-  options: TrackOptions = {}
-): Touch<B> => {
+  layout: (size: Size) => Layout<B, V>,
+  options: ActionsOptions = {}
+): Actions<B, V> => {
   const pointerTypes = options.pointerTypes ?? ["touch"]
   const sizeOf = (): Size => {
     const rect = target.getBoundingClientRect()
@@ -277,7 +332,6 @@ export const track = <const B extends string>(
   let current = layout(sizeOf())
   const names = Object.keys(current.buttons) as Array<B>
   const buttons = makeButtonTracks(names)
-  let touched = false
   let stick: { readonly pointerId: number; readonly origin: Position; knob: Position } | undefined
   /** Which button each finger holds. */
   const fingers = new Map<number, B>()
@@ -298,7 +352,6 @@ export const track = <const B extends string>(
     // A pointer id that comes down again without an up in between (the up
     // was lost) releases what it held first, as a cancel.
     end(event, true)
-    touched = true
     current = layout(sizeOf())
     const at = locate(event)
     for (const name of names) {
@@ -382,12 +435,12 @@ export const track = <const B extends string>(
 
   return {
     snapshot() {
-      const snapshot: Snapshot<B> = {
-        stick: stickState(),
-        buttons: Object.fromEntries(names.map((name) => [name, buttonSnapshot(buttons.get(name)!)])) as { readonly [K in B]: ButtonState },
-        swipe: { active: swipe !== undefined, delta: swiped },
-        touched
-      }
+      const snapshot = snapshotOf<B, V>(
+        current.stick.vector,
+        stickState(),
+        Object.fromEntries(names.map((name) => [name, buttonSnapshot(buttons.get(name)!)])) as { readonly [K in B]: ButtonState },
+        { active: swipe !== undefined, delta: swiped }
+      )
       for (const button of buttons.values()) startWindow(button)
       swiped = zero
       return snapshot
@@ -407,7 +460,7 @@ export const track = <const B extends string>(
         buttons: Object.fromEntries(names.map((name) => {
           const button = buttons.get(name)!
           return [name, { held: button.held, aim: button.held ? button.aim : null }]
-        })) as View<B>["buttons"]
+        })) as View<B, V>["buttons"]
       }
     },
     dispose() {
@@ -445,17 +498,18 @@ export interface TimelineEntry<B extends string> {
 export type Timeline<B extends string> = ReadonlyArray<TimelineEntry<B>>
 
 /** Touch controls driven by a timeline instead of an element. */
-export interface Scripted<B extends string> extends Touch<B> {
+export interface Scripted<B extends string, V extends string = never> extends Actions<B, V> {
   /** Number of snapshots taken so far, which is the next frame index. */
   readonly frames: () => number
 }
 
 /**
- * Plays `timeline` over controls named `buttons`: before the snapshot at index
- * `frame`, every entry for that frame is applied. Vectors longer than 1 are
- * clamped. Scripted controls report `touched` from the first entry on.
+ * Plays `timeline` over controls with `names` (the buttons, and the vector
+ * action the stick drives): before the snapshot at index `frame`, every
+ * entry for that frame is applied. Vectors longer than 1 are clamped.
  */
-export const scripted = <const B extends string>(buttons: ReadonlyArray<B>, timeline: Timeline<NoInfer<B>>): Scripted<B> => {
+export const scripted = <const B extends string, const V extends string = never>(names: Names<B, V>, timeline: Timeline<NoInfer<B>>): Scripted<B, V> => {
+  const buttons = names.buttons
   const byFrame = new Map<number, Array<TimelineEntry<B>>>()
   for (const entry of timeline) {
     const entries = byFrame.get(entry.frame)
@@ -468,10 +522,9 @@ export const scripted = <const B extends string>(buttons: ReadonlyArray<B>, time
   }
   const tracks = makeButtonTracks(buttons)
   let stick: Vector | null = null
-  let touched = false
   let frame = 0
-  const layout: Layout<B> = {
-    stick: { region: { left: 0, top: 0, width: 0, height: 0 }, radius: 1 },
+  const layout: Layout<B, V> = {
+    stick: { region: { left: 0, top: 0, width: 0, height: 0 }, radius: 1, ...(names.vector === undefined ? {} : { vector: names.vector }) },
     buttons: Object.fromEntries(buttons.map((button) => [button, { center: zero, radius: 0 }])) as Layout<B>["buttons"]
   }
   return {
@@ -479,7 +532,6 @@ export const scripted = <const B extends string>(buttons: ReadonlyArray<B>, time
       for (const track of tracks.values()) startWindow(track)
       const swipe = { active: false, x: 0, y: 0 }
       for (const entry of byFrame.get(frame) ?? []) {
-        touched = true
         if (entry.swipe !== undefined) {
           swipe.active = true
           swipe.x += entry.swipe.x
@@ -495,12 +547,12 @@ export const scripted = <const B extends string>(buttons: ReadonlyArray<B>, time
         for (const name of entry.cancel ?? []) lift(tracks.get(name)!, true)
       }
       frame += 1
-      return {
-        stick: { active: stick !== null, vector: stick ?? zero },
-        buttons: Object.fromEntries(buttons.map((name) => [name, buttonSnapshot(tracks.get(name)!)])) as { readonly [K in B]: ButtonState },
-        swipe: { active: swipe.active, delta: { x: swipe.x, y: swipe.y } },
-        touched
-      }
+      return snapshotOf<B, V>(
+        names.vector,
+        { active: stick !== null, vector: stick ?? zero },
+        Object.fromEntries(buttons.map((name) => [name, buttonSnapshot(tracks.get(name)!)])) as { readonly [K in B]: ButtonState },
+        { active: swipe.active, delta: { x: swipe.x, y: swipe.y } }
+      )
     },
     view() {
       return {

package/src/index.ts

@@ -1,9 +1,18 @@
-/** Browser host integrations kept outside the renderer-agnostic ECS core. */
+/**
+ * Browser host integrations kept outside the renderer-agnostic ECS core:
+ * animation-frame timing (`BrowserTickSource`, `BrowserHostClock`), input
+ * devices bound to actions (`Keyboard`, `Gamepad`, `Pointer`, `Touch`),
+ * merging and local multiplayer (`Controls`), and the system that copies
+ * input into a resource (`InputCapture`).
+ */
 export * as BrowserHostClock from "./BrowserHostClock.ts"
 export * as BrowserTickSource from "./BrowserTickSource.ts"
+export * as Controls from "./Controls.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"
 export * as Touch from "./Touch.ts"
 
+/** The package's tag, `"browser"`. */
 export const packageTag = "browser" as const

package/src/internal/buttons.ts

@@ -0,0 +1,222 @@
+import * as Result from "@typeonce/ritmo/Result"
+
+import type { ActionState } from "./state.ts"
+import { directionName, directions, isVectorBinding, zero } from "./vectors.ts"
+import type { Direction, Vector } from "./vectors.ts"
+
+const idleState: ActionState = { held: false, pressed: false, released: false }
+
+/** Action name to the buttons that trigger it, for a device with named buttons. */
+type ButtonBindings<Button extends string> = Readonly<Record<string, readonly [Button, ...Array<Button>]>>
+
+/**
+ * The held buttons, the bound actions, and the edges since the previous
+ * take, shared by devices with named buttons (`Gamepad`, `Pointer`) and by
+ * their live and scripted forms, so all of them build snapshots the same way.
+ */
+export const buttonTracker = <Button extends string, B extends ButtonBindings<Button>>(
+  buttonNames: ReadonlyArray<Button>,
+  initial: B
+) => {
+  // Fixed at creation: a rebind swaps buttons, never the actions.
+  const names = Object.keys(initial) as Array<keyof B & string>
+  let bindings: Readonly<Record<keyof B, ReadonlyArray<Button>>> = initial
+  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>()
+  /**
+   * 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,
+    upAll() {
+      for (const button of [...held]) up(button)
+    },
+    rebind(next: Readonly<Record<keyof B, ReadonlyArray<Button>>>) {
+      const before = names.filter(isHeld)
+      bindings = next
+      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)
+    },
+    /** The buttons and actions since the previous take; starts a new press/release window. */
+    take(): { readonly actions: Record<keyof B, ActionState>; readonly buttons: Record<Button, ActionState> } {
+      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 isDown = isHeld(name)
+        actions[name] = { held: isDown, pressed: pressedActions.has(name), released: releasedActions.has(name) && !isDown }
+      }
+      pressed.clear()
+      released.clear()
+      pressedActions.clear()
+      releasedActions.clear()
+      return { actions, buttons }
+    }
+  }
+}
+
+/** Every button idle, by name. */
+export const idleButtons = <Button extends string>(buttonNames: ReadonlyArray<Button>): Record<Button, ActionState> => {
+  const buttons = {} as Record<Button, ActionState>
+  for (const name of buttonNames) buttons[name] = idleState
+  return buttons
+}
+
+/** Every button action of `bindings` idle (vector actions are in {@link idleVectors}). */
+export const idleActions = <B extends object>(bindings: B): Record<keyof B, ActionState> => {
+  const actions = {} as Record<keyof B, ActionState>
+  for (const [name, entry] of Object.entries(bindings)) if (!isVectorBinding(entry)) actions[name as keyof B] = idleState
+  return actions
+}
+
+/** Every vector action of `bindings` at rest. */
+export const idleVectors = (bindings: object): Record<string, Vector> => {
+  const vectors: Record<string, Vector> = {}
+  for (const [name, entry] of Object.entries(bindings)) if (isVectorBinding(entry)) vectors[name] = zero
+  return vectors
+}
+
+/** A vector binding's digital part: buttons for the four directions, or none. */
+interface DigitalVector<Button extends string> {
+  readonly _tag: "Vector"
+  readonly up?: ReadonlyArray<Button>
+  readonly down?: ReadonlyArray<Button>
+  readonly left?: ReadonlyArray<Button>
+  readonly right?: ReadonlyArray<Button>
+}
+
+/**
+ * Each action's buttons for the button tracker, with the digital part of
+ * every vector action split into its four directions (`move.up`, ...).
+ */
+export const flattenButtons = <Button extends string>(bindings: object): Record<string, readonly [Button, ...Array<Button>]> => {
+  const flat: Record<string, readonly [Button, ...Array<Button>]> = {}
+  for (const [name, entry] of Object.entries(bindings)) {
+    if (isVectorBinding(entry)) {
+      const vector = entry as DigitalVector<Button>
+      // All four, empty when unbound (a stick-only vector), so the tracker's
+      // names stay the same whichever way a rebind binds the vector.
+      for (const direction of directions) {
+        flat[directionName(name, direction)] = (vector[direction] ?? []) as unknown as readonly [Button, ...Array<Button>]
+      }
+    } else flat[name] = entry as readonly [Button, ...Array<Button>]
+  }
+  return flat
+}
+
+/** Splits taken flat actions into the button actions of `bindings`, and whether each vector direction is held. */
+export const splitActions = (
+  bindings: object,
+  taken: Readonly<Record<string, ActionState>>
+): { readonly actions: Record<string, ActionState>; readonly held: (vector: string, direction: Direction) => boolean } => {
+  const actions: Record<string, ActionState> = {}
+  for (const [name, entry] of Object.entries(bindings)) if (!isVectorBinding(entry)) actions[name] = taken[name]!
+  return { actions, held: (vector, direction) => taken[directionName(vector, direction)]?.held === true }
+}
+
+/** Why loaded data is not a rebinding; the devices export it under their own name. */
+export interface InvalidRebinding {
+  readonly _tag: "InvalidRebinding"
+  readonly path: string
+  readonly message: string
+}
+
+/**
+ * Validates `data` as new buttons for exactly the actions of `bindings`:
+ * an object with the same action names, each a non-empty array of button
+ * names.
+ */
+export const parseButtonRebinding = <Button extends string>(
+  buttonNames: ReadonlyArray<Button>,
+  bindings: object,
+  data: unknown,
+  sticks: ReadonlyArray<string> = []
+): Result.Result<Readonly<Record<string, unknown>>, 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 known: ReadonlySet<string> = new Set(buttonNames)
+  const buttonsAt = (value: unknown, path: string): Result.Result<ReadonlyArray<Button>, InvalidRebinding> => {
+    if (!Array.isArray(value) || value.length === 0) return invalid(path, "expected a non-empty array of button names")
+    for (let offset = 0; offset < value.length; offset++) {
+      if (!known.has(value[offset])) return invalid(`${path}[${offset}]`, `expected one of ${buttonNames.join(", ")}`)
+    }
+    return Result.success([...value])
+  }
+  const rebinding: Record<string, unknown> = {}
+  for (const name of names) {
+    const value = fields[name]
+    if (isVectorBinding((bindings as Readonly<Record<string, unknown>>)[name])) {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return invalid(name, "expected { stick } and/or { up, down, left, right } buttons for a vector action")
+      }
+      const parts = value as Readonly<Record<string, unknown>>
+      const vector: Record<string, unknown> = { _tag: "Vector" }
+      if (parts["stick"] !== undefined) {
+        if (typeof parts["stick"] !== "string" || !sticks.includes(parts["stick"])) return invalid(`${name}.stick`, `expected one of ${sticks.join(", ")}`)
+        vector["stick"] = parts["stick"]
+      }
+      const given = directions.filter((direction) => parts[direction] !== undefined)
+      if (given.length > 0) {
+        for (const direction of directions) {
+          const buttons = buttonsAt(parts[direction], `${name}.${direction}`)
+          if (!buttons.ok) return buttons
+          vector[direction] = buttons.value
+        }
+      } else if (vector["stick"] === undefined) return invalid(name, "expected a stick or buttons for up, down, left, and right")
+      rebinding[name] = vector
+      continue
+    }
+    const buttons = buttonsAt(value, name)
+    if (!buttons.ok) return buttons
+    rebinding[name] = buttons.value
+  }
+  return Result.success(rebinding)
+}

package/src/internal/introspect.ts

@@ -0,0 +1,23 @@
+/**
+ * The keys a keyboard device binds now, as they read in a lint (`" "`,
+ * `KeyW`): what a player pool compares to report two players sharing a key.
+ * Live and scripted keyboards implement it.
+ */
+export const boundKeys = Symbol("ritmo-browser/boundKeys")
+
+export interface ReportsBoundKeys {
+  readonly [boundKeys]?: () => ReadonlyArray<string>
+}
+
+/** Every source a device was handed to (a merge, a pool), to report a device used twice. */
+const owners = new WeakMap<object, Array<string>>()
+
+/** Records that `owner` takes the snapshots of `device`. */
+export const claim = (device: object, owner: string): void => {
+  const list = owners.get(device)
+  if (list === undefined) owners.set(device, [owner])
+  else list.push(owner)
+}
+
+/** The sources that take the snapshots of `device`. */
+export const ownersOf = (device: object): ReadonlyArray<string> => owners.get(device) ?? []

package/src/internal/state.ts

@@ -0,0 +1,12 @@
+/**
+ * One button action's state in a snapshot, the same on every device
+ * (`Keyboard`, `Gamepad`, `Pointer`, `Touch`) and in `Controls`.
+ */
+export interface ActionState {
+  /** At least one bound key or button is down now. */
+  readonly held: boolean
+  /** A bound key or button went down since the previous snapshot, even if already released. */
+  readonly pressed: boolean
+  /** A bound key or button went up since the previous snapshot and none is held now. */
+  readonly released: boolean
+}

package/src/internal/used.ts

@@ -0,0 +1,14 @@
+import type { ActionState } from "./state.ts"
+
+/**
+ * Whether any action in a snapshot was pressed or is held: the `used` of a
+ * device's snapshot. Releases do not count, since a blur or a disconnect
+ * releases everything without the player touching the device.
+ */
+export const anyUsed = (actions: Readonly<Record<string, ActionState>>): boolean => {
+  for (const name in actions) {
+    const state = actions[name]!
+    if (state.held || state.pressed) return true
+  }
+  return false
+}