@typeonce/ritmo-browser 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @typeonce/ritmo-browser
 
+## 0.11.0
+
+### Minor Changes
+
+- 778301a: **Draining a service is declared, checked at compile time, and observed at run time.**
+
+  - **`System.Consumes<"snapshot">`** marks the methods of a service type that drain it. A system that declares the service with `Game.System.service` sees those methods as a compile error naming the fix (`snapshot() drains Game/Controls: declare it with Game.System.consumeService, or read the resource its capture writes`); `Game.System.consumeService` calls them. Its other methods stay available through `service` (a settings screen can still `rebind`).
+  - Every input source is marked: `Keyboard.Actions`, `Keyboard.Presses`, `Gamepad.Actions`, `Gamepad.Pads`, `Touch.Actions`, `Pointer.Actions`, `Controls.Device`, `Controls.Controls`, `Controls.Pool`, and `InputCapture.Source`. **Breaking:** a system that called `snapshot()` through `Game.System.service` no longer compiles; read the resource `InputCapture.system` writes instead (or, for a system that must drain the source itself, declare it with `Game.System.consumeService`).
+  - `Game.System.service` returns `ServiceRead<D, false>` and `consumeService` returns `ServiceRead<D, true>`.
+  - The `service-consumed-twice` lint also reports what a debug runtime saw: a consumed service whose consumers ran at more than one placement in the session, in unnamed schedules too (`Game/Drain (schedule#2, step 0, unnamed)`). Named schedules are reported once, by the static lint.
+
+- 866bcff: **`Controls` merges several input devices into one source, every device snapshot shares one shape, and capturing input is checked at compile time and by `describe()`.**
+
+  - **`Controls.actions({ buttons: [...] })`** declares the game's actions once. Its `merge({ keyboard, gamepad, touch })` builds one input source: an action is `held` while any device holds it, `pressed` when any device pressed it, and `released` when a device released it and none holds it now (the same rules as one device with all the bindings). Each device binds every declared action; a device that cannot is passed as `lacking(device, ["pause"])`, which must name exactly the actions it lacks (autocomplete offers them). A device binding an undeclared action, a device missing an action, and an action no device binds do not compile.
+  - The merged snapshot has `actions`, `vectors`, `available` (whether the last used device binds each action, so a game can offer a lacking action another way), `devices` (each device's own snapshot, keyed by the merge names: sticks, triggers, touch aim), and `lastUsed` (`null` until a device is used). The merged source exposes `rebind.<device>` for devices that can rebind, and `dispose()`. `idle({ keyboard: Keyboard.idle(...), ... })` initializes the input resource. Reading an action on a device that lacks it does not compile.
+  - **Breaking: `Keyboard.Snapshot` is `{ actions, vectors, used }`.** Read `input.actions.jump.pressed` instead of `input.jump.pressed`. Hand-written timelines and bindings are unchanged.
+  - **Breaking: `Touch.Snapshot` renames `buttons` to `actions`** (each still a `ButtonState` with `aim` and `cancelled`) **and replaces `touched` with `used`.** Read `input.actions.fire` instead of `input.buttons.fire`. `Layout.buttons` and `View.buttons` are unchanged.
+  - Every device snapshot (`Keyboard`, `Gamepad`, `Pointer`, `Touch`) has `used`: something pressed in this window or held, or a stick or swipe in use. Releases do not count, so a blur or a disconnect does not change `lastUsed`.
+  - **`Game.System.consumeService(Service)`** declares a service a system drains on each run (an input source's `snapshot()`, a message queue); it is the only way to call the draining methods (see `System.Consumes`). `describe()` warns with the new `service-consumed-twice` lint when a consumed service has more than one placement, for example the same input captured in a fixed and a render schedule, where each capture sees only the presses since the other ran. `SystemDescription.consumes` lists them.
+  - **Breaking: `InputCapture.system` keeps its declared access**: it consumes the source and writes the resource, so a `Game.System.thisTick` reader of the resource placed before the capture no longer compiles (the error names both systems and the fix: place the reader after the capture), and capturing one source twice is reported by `describe()`. The exported `InputCapture.CaptureSystem` type is removed: let the system's type be inferred.
+  - **`Debug.serviceLints`** lets a service value add findings to `describe()` lints, reported as `service-lint` with the service as subject; `Controls` uses it to list every device that lacks an action.
+
+- deaed5a: **`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, 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.
+  - **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() {}`.
+
+- 57430bb: **Local multiplayer: players join slots by pressing a button on any pooled device.**
+
+  - **`Controls.players(Actions, { slots, join, leave })`** declares the players: the slots (the most at once, in join order), the button action that joins (or `"any"` for any button), and the one that leaves while joining is open. A misspelled or vector action, no slot, a slot named `joining`, and a button action named `any` (it would read as `join: "any"`) do not compile.
+  - **`pool(devices)`** on the declared players builds one input source from devices nobody holds yet. Pressing join on one gives it the first free slot; that snapshot reports `event: "joined"` with the player's input idle, so the press does nothing else (joining with the jump button does not jump). One device holds one slot; slots keep their names when another empties, and the next player fills the gap. Each pooled device binds every action (or is passed through `lacking`), and the join action always.
+  - The snapshot has every slot by name (`input.p2`): `joined`, `device` (what it joined with), `connected`, `event` (`"joined"`, `"left"`, or `null`), and the player's `actions`, `vectors`, and `available`, idle while the slot is empty. A device's own snapshot is behind a check of `device` (`if (input.p2.device === "pads") input.p2.devices.pads.left`). The declared players' `idle(...)` initializes the resource.
+  - Systems call `setJoining(open)` (closed at the start: open it on a join screen, or once for drop-in play), `seat(slot, device)` (a player in from the start, or picked on a menu: a pool name, or `{ pads: index }` for one pad; returns `{ ok: false, reason }` when the slot or device is taken), `leave(slot)` (a pause menu), and `rebind.<device>` through a plain service. Leaving by button works only while joining is open; otherwise `leave` is an ordinary action.
+  - **`Gamepad.pads(host, bindings, max)`** reads every pad on its own, for a pool: each pad joins as its own player. An unplugged pad keeps its slot (`connected: false`) and returns to it when it comes back; two pads of one model share an id, so they are told apart by their place in the pad list. `Gamepad.scriptedPads(bindings, timelines)` drives one timeline per pad in tests.
+  - `describe()` lints two keyboard devices that bind the same key, a device taken by two sources (a merge and a pool), and joining never opened.
+
+- 97e39c5: **`Pointer` binds actions like `Keyboard` and `Gamepad` and merges into `Controls`, and `Controls.group` makes devices used together count as one.**
+
+  - **Breaking: `Pointer.track(target, blurHost, options?)` is `Pointer.actions(target, blurHost, bindings, options?)`.** Bindings map actions to buttons (`{ fire: ["primary"] }`); a misspelled button or an empty list does not compile. Pass `{}` for position and raw buttons only. The `Pointer.Pointer` type is `Pointer.Actions<B>` and `TrackOptions` is `ActionsOptions`.
+  - **Breaking: the snapshot is `{ actions, vectors, buttons, position, movement, wheel, over, locked, used }`.** Read `input.buttons.primary` (or a bound action) instead of `input.primary`. `used` is a press, a hold, or movement over the element; releases do not count. `movement`, `wheel`, and `locked` come with the wheel and the pointer lock.
+  - **The `back` and `forward` side buttons** (`PointerEvent.button` 3 and 4) are reported and bindable. `Pointer.buttonNames` and `Pointer.isButton` list and check them.
+  - `rebind(...)` swaps the buttons of the same actions; `Pointer.parseRebinding(bindings, data)` validates saved ones.
+  - **Breaking: `Pointer.idle(bindings, position?)` and `Pointer.scripted(bindings, timeline, start?)`** take the bindings first. Timelines still name buttons, so a replay follows the bindings as live play does.
+  - **`actions.group({ keyboard, mouse })`** groups devices into one merge entry: it binds what its devices bind between them, and `lastUsed` and `available` follow it as a whole, so walking with the keyboard while aiming with the mouse stays on one device. Grouped devices keep their own names in `devices`, `rebind`, and `idle`; `lastUsed` names the group. Pass the group to `lacking(...)` for actions none of its devices binds. A group of fewer than two devices, a `lacking` device or a group inside a group, a device binding an undeclared action, and a name used twice across devices and groups do not compile.
+
+- bb371d4: **`Pointer` reads the wheel and the pointer lock, and `Touch.track` is `Touch.actions`, so every device is built the same way.**
+
+  - **The wheel**, read two ways for two jobs. `wheel` is how far it scrolled since the previous snapshot, in CSS pixels (lines and pages are converted), for zoom. The `wheelUp`, `wheelDown`, `wheelLeft`, and `wheelRight` buttons pulse (pressed and released in one window) once per `Pointer.wheelStep` (100 px, one notch), so a stepping action binds them (`nextWeapon: ["wheelDown"]`) and merges with a gamepad bumper in `Controls`. The page does not scroll over the element unless `preventScroll: false`. `PointerTarget` gains the `wheel` listener.
+  - **Mouse look:** `movement` is the raw motion since the previous snapshot (`movementX`/`movementY`), locked or not. With `lock: document`, a click on the element locks the pointer (the browser grants a lock only inside a click, so the module asks in its own listener); that click is not reported as a press. `locked` turns `false` when the player leaves with Escape, which releases what was held. `used` also counts motion and scrolling.
+  - Timelines record and replay `wheel`, `movement`, and `locked`. Their `press`/`release` take `Pointer.PhysicalButton`s; wheel pulses come from `wheel`.
+  - **Breaking: `Touch.track(target, blurHost, layout, options?)` is `Touch.actions(...)`, the `Touch.Touch<B>` type is `Touch.Actions<B>`, and `Touch.TrackOptions` is `Touch.ActionsOptions`,** matching `Keyboard.actions`, `Gamepad.actions`, and `Pointer.actions`. Arguments and behavior are unchanged.
+
+- b3b16fd: **Movement is one vector action: declared once, bound per device, merged by `Controls`, and checked like every other action.**
+
+  - **`Controls.actions({ buttons: [...], vectors: [...] })`** declares both kinds. A button action is pressed and held (jump); a vector action is a direction with length at most 1, `y` growing down (move). A name declared as both kinds does not compile. The declared names are listed in the set's `buttons` and `vectors`.
+  - **`Keyboard.vector({ up, down, left, right })`** binds a vector to keys: opposite keys cancel and a diagonal has length 1. **`Gamepad.vector({ stick, up, down, left, right })`** binds it to a stick, the d-pad, or both (the longer wins). **A `Touch` layout's `stick.vector`** names the vector the stick drives. Every device snapshot has `vectors`; read `input.vectors.move` (`Pointer`'s is empty: it reports `position` and `movement`).
+  - `Controls` merges a vector as the longest any device reports, so devices never add up past 1 or cancel each other. Vectors work with `lacking`, `available`, `idle`, and `lastUsed` (a vector in use counts as use). Binding a vector action as a button (or the reverse), missing a vector, and reading `actions.move` or `vectors.jump` do not compile, each with an error naming the fix.
+  - `rebind` and `parseRebinding` take vector bindings (`Gamepad` can swap sticks).
+  - Keyboard timelines name a vector by direction, `press: ["move.right"]`; `parseTimeline` validates it. Button actions are named as before.
+  - **Breaking: `Touch.idle` and `Touch.scripted` take the names as an object**, `{ buttons, vector? }` (`vector` as the layout's `stick.vector`):
+
+    ```diff
+    -Touch.idle(["fire"])
+    -Touch.scripted(["fire"], timeline)
+    +Touch.idle({ buttons: ["fire"] })
+    +Touch.scripted({ buttons: ["fire"] }, timeline)
+    ```
+
+  - Directions that step one tile at a time (a grid game reading taps) stay button actions.
+
+### Patch Changes
+
+- e46f284: **Documentation pass over every public module.** Every export has JSDoc saying what it is for and which neighbouring API to use instead; examples that no longer compiled (`Session.make` without `hostClock`, `Replay.session`, the `Pointer` rebind) are fixed; `Debug.Lint` lists every lint code the runtime emits. The `stale-target` lint's fix now names `queries.x.getHandle(handle)`.
+- Updated dependencies [778301a]
+- Updated dependencies [866bcff]
+- Updated dependencies [e46f284]
+  - @typeonce/ritmo@0.11.0
+
 ## 0.10.0
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,11 @@
 # `@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:
+
+- `BrowserTickSource`: animation frames as a tick source for the core fixed-step loop.
+- Devices, each built with `X.actions(...)` from its host and bindings (a layout for `Touch`) and reporting a snapshot of `actions`, `vectors`, and `used`: `Keyboard` (keys by character or physical key), `Gamepad` (standard-mapping button names, sticks, and triggers), `Pointer` (mouse and pen buttons, position, wheel, pointer lock), and `Touch` (on-screen controls with a floating stick and drag-to-aim buttons). Keyboard, gamepad, and pointer bindings are rebindable at runtime for a controls settings screen (validate saved ones with `parseRebinding`); every device has scripted timelines for tests, and keyboard, gamepad, and pointer also record them for replays.
+- `Controls`: the game's actions declared once, as buttons and vectors (movement with length at most 1, from keys, d-pad, stick, or touch stick), and the devices merged into one input source; devices used together (keyboard and mouse) are grouped as one. `Controls.players` and `Gamepad.pads`: local multiplayer, where players join a slot by pressing a button on any pooled device, every pad on its own.
+- `InputCapture`: the system that drains an input source once per update into a resource. Systems read that resource; a system that calls `snapshot()` itself declares the source with `Game.System.consumeService`.
 
 ```sh
 pnpm add @typeonce/ritmo-browser @typeonce/ritmo

package/dist/Controls.d.ts

@@ -0,0 +1,495 @@
+/**
+ * One input source merged from several devices, so gameplay reads each
+ * action once whatever the player uses.
+ *
+ * Declare the game's actions once with `Controls.actions({ buttons: [...] })`, bind them
+ * on every device (`Keyboard.actions`, `Gamepad.actions`, `Pointer.actions`,
+ * `Touch.actions`), and merge the devices with the declaration's `merge`.
+ * Merged devices
+ * behave like one device with all their bindings: an action is `held` while
+ * any device holds it, `pressed` when any device pressed it, and `released`
+ * when a device released it and none holds it now. A vector action (movement)
+ * is the longest direction any device reports, so a stick and keys never add
+ * up past length 1 or cancel each other. Device-specific data
+ * (sticks, triggers, touch aim) stays in `devices`, under the names given to
+ * `merge`; `lastUsed` names the device the player used last, for button
+ * prompts.
+ *
+ * Devices the player uses together (keyboard and mouse) go in one
+ * `group(...)`: the group is one entry of the merge, so walking with the
+ * keyboard while aiming with the mouse keeps `lastUsed` on the group, and
+ * `available` follows what the group binds between its devices. Grouped
+ * devices keep their own names in `devices` and `rebind`.
+ *
+ * Every entry binds every action. A device that cannot (a touch layout
+ * without a pause button) is passed as `actions.lacking(device, [...])`,
+ * which names exactly the actions it lacks. Reading a lacking action on that
+ * device does not compile; `available` reports whether the last used device
+ * has each action, and `describe()` lists every gap as a `service-lint`.
+ *
+ * Capture the merged source with `InputCapture.system(...)` and build the
+ * devices inside the `merge(...)` call, so nothing else takes their
+ * snapshots. A game with one device captures that device directly instead.
+ *
+ * A merge is one player on every device. For local multiplayer, where each
+ * device belongs to the player who joined with it, declare
+ * `Controls.players(Actions, { slots, join, leave })` and capture its
+ * `pool(...)` instead.
+ *
+ * @module Controls
+ * @docGroup browser
+ *
+ * @example
+ * ```ts
+ * const Actions = Controls.actions({ buttons: ["jump", "pause"], vectors: ["move"] })
+ *
+ * const keyBindings = {
+ *   move: Keyboard.vector({ up: ["ArrowUp", "w"], down: ["ArrowDown", "s"], left: ["ArrowLeft", "a"], right: ["ArrowRight", "d"] }),
+ *   jump: [" "],
+ *   pause: ["Escape"]
+ * } as const
+ * const padBindings = {
+ *   move: Gamepad.vector({ stick: "left", up: ["dpadUp"], down: ["dpadDown"], left: ["dpadLeft"], right: ["dpadRight"] }),
+ *   jump: ["south"],
+ *   pause: ["start"]
+ * } as const
+ *
+ * // One function builds the controls, for the browser and for tests.
+ * export const makeControls = (devices: {
+ *   readonly keyboard: Keyboard.Actions<typeof keyBindings>
+ *   readonly gamepad: Gamepad.Actions<typeof padBindings>
+ * }) => Actions.merge(devices)
+ *
+ * const ControlsInput = Descriptor.Service<ReturnType<typeof makeControls>>()("Game/Controls")
+ * const Input = Descriptor.TransientResource<InputCapture.SnapshotOf<typeof ControlsInput>>()("Game/Input")
+ * const CaptureInput = InputCapture.system(Game, { name: "Game/CaptureInput", source: ControlsInput, resource: Input })
+ *
+ * const runtime = Game.Runtime.make({
+ *   services: Game.Runtime.services(Game.Runtime.service(ControlsInput, makeControls({
+ *     keyboard: Keyboard.actions(window, keyBindings),
+ *     gamepad: Gamepad.actions(window, padBindings)
+ *   }))),
+ *   resources: { Input: Actions.idle({ keyboard: Keyboard.idle(keyBindings), gamepad: Gamepad.idle(padBindings) }) }
+ * }).value
+ *
+ * // In a system:
+ * const input = resources.input.get()
+ * walk(input.vectors.move) // length at most 1: keys, d-pad, or stick
+ * if (input.actions.jump.pressed) jump()
+ * const prompt = input.lastUsed === "gamepad" ? "Ⓐ" : "Space"
+ * ```
+ */
+import type * as System from "@typeonce/ritmo/System";
+import type { ActionState } from "./Keyboard.ts";
+import type { Vector } from "./internal/vectors.ts";
+export type { Vector };
+/**
+ * The part of a device's snapshot `Controls` merges: every button action's
+ * state, every vector action's direction, and whether the player used the
+ * device in this window.
+ */
+export interface DeviceSnapshot<A extends string, V extends string = never> {
+    readonly actions: {
+        readonly [K in A]: ActionState;
+    };
+    readonly vectors: {
+        readonly [K in V]: Vector;
+    };
+    readonly used: boolean;
+}
+/** A device `Controls` can merge: `Keyboard.actions`, `Gamepad.actions`, `Pointer.actions`, `Touch.actions`, or their scripted forms. */
+export interface Device<A extends string = string, V extends string = string> extends System.Consumes<"snapshot"> {
+    snapshot(): DeviceSnapshot<A, V>;
+    dispose(): void;
+}
+/**
+ * Devices the player uses together as one (keyboard and mouse), built with
+ * {@link ActionSet.group}. The group is one entry of the merge: it binds
+ * what its devices bind between them, and `lastUsed` and `available` follow
+ * it as a whole. Its devices keep their own names in `devices` and `rebind`.
+ */
+export interface Group<Members> {
+    readonly _tag: "Group";
+    readonly members: Members;
+}
+/**
+ * Every pad on its own, for a player pool: `Gamepad.pads(...)`. Each pad
+ * joins as its own player.
+ */
+export interface Pads {
+    readonly _tag: "Pads";
+    readonly max: number;
+    snapshot(): ReadonlyArray<DeviceSnapshot<string, string> & {
+        readonly id: string | null;
+        readonly connected: boolean;
+    }>;
+    dispose(): void;
+}
+/** A device passed with the actions it lacks; build it with {@link ActionSet.lacking}. */
+export interface Lacking<D extends Unit | Pads, Missing extends string> {
+    readonly _tag: "Lacking";
+    readonly device: D;
+    readonly lacking: ReadonlyArray<Missing>;
+}
+/** One entry of a merge before `lacking`: a device or a group of devices. */
+type Unit = Device | Group<Readonly<Record<string, Device>>>;
+type Entry = Unit | Lacking<Unit, string>;
+/** One entry of a player pool: a device, or every pad, maybe with the actions it lacks. */
+type PoolEntry = Device | Pads | Lacking<Device | Pads, string>;
+/** The button actions a device, or the devices of a group, bind. */
+type ActionsOf<D> = D extends Group<infer M> ? {
+    [K in keyof M]: ActionsOf<M[K]>;
+}[keyof M] : D extends {
+    readonly _tag: "Pads";
+    snapshot(): ReadonlyArray<{
+        readonly actions: infer Actions;
+    }>;
+} ? keyof Actions & string : D extends {
+    snapshot(): {
+        readonly actions: infer Actions;
+    };
+} ? keyof Actions & string : never;
+/** The vector actions a device, or the devices of a group, bind. */
+type VectorsOf<D> = D extends Group<infer M> ? {
+    [K in keyof M]: VectorsOf<M[K]>;
+}[keyof M] : D extends {
+    readonly _tag: "Pads";
+    snapshot(): ReadonlyArray<{
+        readonly vectors: infer Vectors;
+    }>;
+} ? keyof Vectors & string : D extends {
+    snapshot(): {
+        readonly vectors: infer Vectors;
+    };
+} ? keyof Vectors & string : never;
+/** Every action a device binds, of either kind. */
+type BoundOf<D> = ActionsOf<D> | VectorsOf<D>;
+/**
+ * Why a device's bindings do not fit the declared buttons `A` and vectors
+ * `V` (an action of the wrong kind, or one not declared), or `never`.
+ */
+type KindIssue<A extends string, V extends string, Name extends string, D> = [ActionsOf<D> & V] extends [never] ? [VectorsOf<D> & A] extends [never] ? [Exclude<BoundOf<D>, A | V>] extends [never] ? never : `${Name} binds ${Exclude<BoundOf<D>, A | V>}, which is not one of the actions` : `${Name} binds ${VectorsOf<D> & A} as a vector, but it is a button action: bind it to keys or buttons` : `${Name} binds ${ActionsOf<D> & V} as a button, but it is a vector action: bind it with vector(...)`;
+type DeviceOf<E> = E extends Lacking<infer D, string> ? D : E;
+type SnapshotOf<D> = D extends {
+    snapshot(): infer S;
+} ? S : never;
+/** The devices one merge entry contributes, by name: a group's members, or the device under the entry's name. */
+type MembersOf<K, U> = U extends Group<infer M> ? M : {
+    readonly [P in K & string]: U;
+};
+/** Every device name of a merge, with groups flattened. */
+type DeviceNames<R> = {
+    [K in keyof R]: keyof MembersOf<K, DeviceOf<R[K]>>;
+}[keyof R] & string;
+/** The device a merge names `N`, wherever it is. */
+type DeviceNamed<R, N> = {
+    [K in keyof R]: MembersOf<K, DeviceOf<R[K]>> extends infer M ? N extends keyof M ? M[N] : never : never;
+}[keyof R];
+/** Each device's full snapshot, by device name (group members under their own names). */
+type DevicesOf<R> = {
+    readonly [N in DeviceNames<R>]: SnapshotOf<DeviceNamed<R, N>>;
+};
+/** The `rebind` of each merged device that has one, by device name. */
+type RebindOf<R> = {
+    readonly [N in DeviceNames<R> as DeviceNamed<R, N> extends {
+        readonly rebind: unknown;
+    } ? N : never]: DeviceNamed<R, N> extends {
+        readonly rebind: infer Rebind;
+    } ? Rebind : never;
+};
+/** The names one entry takes: its own, and its members' for a group. */
+type NamesOf<K, U> = U extends Group<infer M> ? K | keyof M : K;
+/** A device or group name the merge uses twice. */
+type Repeated<R> = {
+    [K in keyof R]: (NamesOf<K, DeviceOf<R[K]>> & {
+        [J in Exclude<keyof R, K>]: NamesOf<J, DeviceOf<R[J]>>;
+    }[Exclude<keyof R, K>]) | (DeviceOf<R[K]> extends Group<infer M> ? K & keyof M : never);
+}[keyof R] & string;
+/** Rejects a merge that uses a name twice: `devices`, `rebind`, and `lastUsed` need one meaning per name. */
+type UniqueNames<R> = [Repeated<R>] extends [never] ? unknown : `the name ${Repeated<R>} is used twice: give every device and group its own name`;
+/** A group member when it is a plain device binding only declared actions, otherwise an error naming the fix. */
+type CheckMember<A extends string, V extends string, Name extends string, D> = D extends Lacking<Unit, string> ? "lacking applies to the whole group: pass lacking(group(...), [...])" : D extends Group<unknown> ? "groups do not nest: list every device in one group" : [KindIssue<A, V, Name, D>] extends [never] ? D : KindIssue<A, V, Name, D>;
+/** Rejects a group of fewer than two devices. */
+type TwoOrMore<M> = [keyof M] extends [never] ? "a group needs at least two devices" : {
+    [K in keyof M]: [Exclude<keyof M, K>] extends [never] ? K : never;
+}[keyof M] extends infer Alone extends string ? [Alone] extends [never] ? unknown : `a group needs at least two devices: pass ${Alone} to merge directly` : unknown;
+/** The entry when it covers exactly the declared actions, otherwise an error naming the device and the fix. */
+type CheckEntry<A extends string, V extends string, Name extends string, E> = E extends Lacking<infer D, infer Missing> ? [KindIssue<A, V, Name, D>] extends [never] ? [Exclude<A | V, BoundOf<D> | Missing>] extends [never] ? E : `${Name} has no action ${Exclude<A | V, BoundOf<D> | Missing>}: bind it on ${Name}, or list it in its lacking(...)` : KindIssue<A, V, Name, D> : [KindIssue<A, V, Name, E>] extends [never] ? [Exclude<A | V, BoundOf<E>>] extends [never] ? E : `${Name} has no action ${Exclude<A | V, BoundOf<E>>}: bind it on ${Name}, or pass lacking(${Name}, [...]) from the action set` : KindIssue<A, V, Name, E>;
+/** The actions some merged device binds. */
+type BoundBy<R> = {
+    [K in keyof R]: BoundOf<DeviceOf<R[K]>>;
+}[keyof R];
+/** Rejects a merge where no device binds an action. */
+type EveryActionBound<A extends string, R> = [Exclude<A, BoundBy<R>>] extends [never] ? unknown : `no device binds ${Exclude<A, BoundBy<R>>}: bind it on one device, or remove it from Controls.actions`;
+/**
+ * The merged input. `actions` merges every device; `devices` holds each
+ * device's own snapshot under the name it was merged under.
+ */
+export interface Snapshot<A extends string, V extends string, Devices, Used extends string = keyof Devices & string> {
+    readonly actions: {
+        readonly [K in A]: ActionState;
+    };
+    /**
+     * Each vector action (movement) as a direction with length at most 1, `y`
+     * growing down: the longest any device reports, so devices never add up
+     * past 1 or cancel each other.
+     */
+    readonly vectors: {
+        readonly [K in V]: Vector;
+    };
+    /**
+     * Whether the last used device binds each action: `false` for the actions
+     * it was merged as lacking, so the game can offer them another way (an
+     * on-screen pause button). Every action is available before any device is
+     * used.
+     */
+    readonly available: {
+        readonly [K in A | V]: boolean;
+    };
+    readonly devices: Devices;
+    /**
+     * The device (or group) that reported input most recently, or `null`
+     * before any did. When several report input in one window it stays on the
+     * current one if it is among them, otherwise it takes the first in merge
+     * order.
+     */
+    readonly lastUsed: Used | null;
+}
+/** The merged source, for `InputCapture.system(...)`. */
+export interface Controls<A extends string, V extends string, R> extends System.Consumes<"snapshot"> {
+    /** Takes every device's snapshot, starting a new press window on each, and merges them. */
+    snapshot(): Snapshot<A, V, DevicesOf<R>, keyof R & string>;
+    /** Each merged device's `rebind`, for a settings screen; devices without one (touch) are not listed. */
+    readonly rebind: RebindOf<R>;
+    /** Disposes every merged device. */
+    dispose(): void;
+}
+/**
+ * The game's actions, declared once. Every merge, gap, and idle snapshot is
+ * built from it, so action names are checked against one list.
+ */
+export interface ActionSet<A extends string, V extends string = never> {
+    /** The declared button actions, in order, for listing them on a settings screen. */
+    readonly buttons: ReadonlyArray<A>;
+    /** The declared vector actions, in order. */
+    readonly vectors: ReadonlyArray<V>;
+    /**
+     * Marks the actions `device` cannot report, for {@link merge}. List
+     * exactly the declared actions it does not bind: autocomplete offers them,
+     * and a missing or extra name does not compile.
+     */
+    lacking<D extends Unit | Pads, const Missing extends ReadonlyArray<Exclude<A | V, BoundOf<D>>>>(device: D & ([
+        KindIssue<A, V, "This device", D>
+    ] extends [never] ? [Exclude<A | V, BoundOf<D>>] extends [never] ? "This device binds every action: pass it to merge without lacking" : unknown : KindIssue<A, V, "This device", D>), lacking: Missing & ([Exclude<A | V, BoundOf<D> | Missing[number]>] extends [never] ? unknown : `This device also lacks ${Exclude<A | V, BoundOf<D> | Missing[number]>}: bind it, or list it here`)): Lacking<D, Missing[number]>;
+    /**
+     * Groups devices the player uses together (keyboard and mouse), for
+     * {@link merge}: the group binds what its devices bind between them, and
+     * `lastUsed` and `available` follow it as a whole, so walking with the
+     * keyboard while aiming with the mouse is one device in use. A group needs
+     * two or more plain devices, each binding only declared actions; pass the
+     * group to {@link lacking} for the actions none of them binds.
+     */
+    group<const M extends Readonly<Record<string, Entry | Group<unknown>>>>(members: {
+        readonly [K in keyof M]: CheckMember<A, V, K & string, M[K]>;
+    } & TwoOrMore<M>): Group<M>;
+    /**
+     * Merges `devices` into one source. Each entry (a device or a
+     * {@link group}) binds every declared action, or is passed through
+     * {@link lacking}; every action is bound by at least one device. Entry
+     * names key `lastUsed`; device names (a group's members under their own)
+     * key `devices` and `rebind`.
+     */
+    merge<const R extends Readonly<Record<string, Entry>>>(devices: {
+        readonly [K in keyof R]: CheckEntry<A, V, K & string, R[K]>;
+    } & EveryActionBound<A | V, R> & UniqueNames<R>): Controls<A, V, R>;
+    /**
+     * A merged snapshot with nothing held and no device used yet, for
+     * initializing the input resource: pass each device's idle snapshot
+     * (`Keyboard.idle(...)`, ...) under its device name.
+     */
+    idle<const Devices extends Readonly<Record<string, DeviceSnapshot<string, string>>>>(devices: Devices): Snapshot<A, V, Devices, never>;
+}
+/** Rejects a name declared both as a button and as a vector. */
+type DistinctKinds<A extends string, V extends string> = [A & V] extends [never] ? unknown : `${A & V} is declared as both a button and a vector action: give it one kind`;
+/**
+ * Declares the game's actions: `buttons` (pressed and held: jump, pause)
+ * and `vectors` (a direction with length at most 1: move), each bound on
+ * every device. Build the merged source with the returned set's `merge`.
+ *
+ * @example
+ * ```ts
+ * const Actions = Controls.actions({ buttons: ["jump", "pause"], vectors: ["move"] })
+ * ```
+ */
+export declare const actions: <const Buttons extends readonly [string, ...Array<string>], const Vectors extends ReadonlyArray<string> = readonly []>(names: {
+    readonly buttons: Buttons;
+    readonly vectors?: Vectors;
+} & DistinctKinds<Buttons[number], Vectors[number]>) => ActionSet<Buttons[number], Vectors[number]>;
+/** A slot's input without the device: what every player snapshot has, joined or not. */
+export interface SlotInput<A extends string, V extends string> {
+    readonly actions: {
+        readonly [K in A]: ActionState;
+    };
+    readonly vectors: {
+        readonly [K in V]: Vector;
+    };
+    /** Whether the slot's device binds each action: every one while the slot is empty. */
+    readonly available: {
+        readonly [K in A | V]: boolean;
+    };
+}
+/** A slot nobody holds: its input is idle. */
+export interface EmptySlot<A extends string, V extends string> extends SlotInput<A, V> {
+    readonly joined: false;
+    readonly device: null;
+    readonly connected: false;
+    /** `"left"` in the snapshot right after its player left, otherwise `null`. */
+    readonly event: "left" | null;
+    readonly devices: {
+        readonly [K in never]: never;
+    };
+}
+/** A slot held by a player, by the device they joined with. Check `device` to read that device's own snapshot. */
+export type JoinedSlot<A extends string, V extends string, Devices> = {
+    readonly [D in keyof Devices & string]: SlotInput<A, V> & {
+        readonly joined: true;
+        readonly device: D;
+        /** `false` while the player's pad is unplugged: the slot is kept, and the same pad coming back returns to it. */
+        readonly connected: boolean;
+        /** `"joined"` in the snapshot where the player joined (their input is idle there, so the press that joins does nothing else), otherwise `null`. */
+        readonly event: "joined" | null;
+        readonly devices: {
+            readonly [P in D]: Devices[D];
+        };
+    };
+}[keyof Devices & string];
+/** One player slot: empty, or held through one of the pool's devices. */
+export type Slot<A extends string, V extends string, Devices> = EmptySlot<A, V> | JoinedSlot<A, V, Devices>;
+/** Every slot by name, and whether joining is open. */
+export type PlayersSnapshot<A extends string, V extends string, S extends string, Devices> = {
+    readonly joining: boolean;
+} & {
+    readonly [K in S]: Slot<A, V, Devices>;
+};
+/** What one pool entry hands a player: a pad's snapshot for `Gamepad.pads`, the device's otherwise. */
+type UnitSnapshotOf<D> = D extends {
+    readonly _tag: "Pads";
+    snapshot(): ReadonlyArray<infer S>;
+} ? S : SnapshotOf<D>;
+type PoolDevicesOf<R> = {
+    readonly [K in keyof R]: UnitSnapshotOf<DeviceOf<R[K]>>;
+};
+/** The entry when it fits the actions and binds the join action, otherwise an error naming the fix. */
+type CheckPoolEntry<A extends string, V extends string, J extends string, Name extends string, E> = E extends Lacking<infer _D, infer Missing> ? [Missing & J] extends [never] ? CheckEntry<A, V, Name, E> : `${Name} lacks ${Missing & J}: every pooled device binds ${J}, or no one can join with it` : CheckEntry<A, V, Name, E>;
+/**
+ * A pooled device to seat a player on: its pool name, or `{ [name]: index }`
+ * for one pad of a `Gamepad.pads` entry (its place in the pad list, from 0).
+ */
+export type SeatDevice<R> = {
+    readonly [K in keyof R & string]: DeviceOf<R[K]> extends Pads ? never : K;
+}[keyof R & string] | {
+    readonly [K in keyof R & string]: DeviceOf<R[K]> extends Pads ? {
+        readonly [P in K]: number;
+    } : never;
+}[keyof R & string];
+/**
+ * Whether {@link Pool.seat} seated the player: `slot-taken` when someone
+ * holds the slot, `device-taken` when another slot holds the device, and
+ * `no-such-pad` when the index is not a place in the pad list.
+ */
+export type SeatResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: "slot-taken" | "device-taken" | "no-such-pad";
+};
+/** The pooled input source, for `InputCapture.system(...)`; systems call the rest through a plain service. */
+export interface Pool<A extends string, V extends string, S extends string, R> extends System.Consumes<"snapshot"> {
+    /** Takes every device's snapshot, applies joins, leaves, and reconnects, and reports every slot. */
+    snapshot(): PlayersSnapshot<A, V, S, PoolDevicesOf<R>>;
+    /** Opens or closes joining: open on a join screen or for drop-in play, closed during a round. Closed at the start. */
+    setJoining(open: boolean): void;
+    /**
+     * Gives `slot` to `device` without a press, joining or not: a player who
+     * is in from the start (call it from a setup system), or one picked on a
+     * menu. The next snapshot reports `event: "joined"`, as a join does. A
+     * pad not plugged in yet holds the slot with `connected: false`.
+     */
+    seat(slot: S, device: SeatDevice<R>): SeatResult;
+    /** Frees a slot (a pause menu's "Leave", "Continue without P2"); its device goes back to the pool. */
+    leave(slot: S): void;
+    /** Each pooled device's `rebind`, by its pool name (`Gamepad.pads` rebinds every pad). */
+    readonly rebind: {
+        readonly [K in keyof R as DeviceOf<R[K]> extends {
+            readonly rebind: unknown;
+        } ? K : never]: DeviceOf<R[K]> extends {
+            readonly rebind: infer Rebind;
+        } ? Rebind : never;
+    };
+    /** Disposes every pooled device. */
+    dispose(): void;
+}
+/** The players of a local multiplayer game, declared once. */
+export interface PlayerSet<A extends string, V extends string, S extends string, J extends string> {
+    /** The slots, in join order. */
+    readonly slots: ReadonlyArray<S>;
+    /**
+     * Pools `devices`: none belongs to a player until someone presses join on
+     * it. Each binds every action (or is passed through `lacking`), and the
+     * join action always: `Gamepad.pads(...)` lets every pad join on its own,
+     * and two `Keyboard.actions` over different keys are two keyboard players.
+     */
+    pool<const R extends Readonly<Record<string, PoolEntry>>>(devices: {
+        readonly [K in keyof R]: CheckPoolEntry<A, V, J, K & string, R[K]>;
+    }): Pool<A, V, S, R>;
+    /**
+     * Every slot empty and joining closed, for initializing the input
+     * resource: pass each device's idle snapshot (`Keyboard.idle(...)`,
+     * `Gamepad.idle(...)` for pads) under its pool name.
+     */
+    idle<const Devices extends Readonly<Record<string, DeviceSnapshot<string, string>>>>(devices: Devices): PlayersSnapshot<A, V, S, Devices>;
+}
+/** Rejects a slot named like the snapshot's own field. */
+type SlotNames<S extends string> = [S & "joining"] extends [never] ? unknown : "joining is the snapshot's own field: name the slot something else";
+/** Rejects a button action named like `join: "any"`, which would read as any button. */
+type NoAnyAction<A extends string> = [A & "any"] extends [never] ? unknown : "an action named any reads as join: \"any\" (any button): rename the action";
+/**
+ * Declares the players of a local multiplayer game over `actions`: the
+ * `slots` (the most players at once, in join order), the button action
+ * that joins (`"any"` for any button action but `leave`, or any vector
+ * moved), and the optional one that leaves while joining is open. Build the
+ * input source with the returned set's `pool`. For one player on several
+ * devices, use the action set's `merge` instead.
+ *
+ * Pressing join on a device nobody holds gives it the first free slot; that
+ * snapshot reports `event: "joined"` with the player's input idle, so the
+ * press does nothing else. A slot keeps its name when another empties. A
+ * pad that disconnects keeps its slot (`connected: false`) and returns to
+ * it when it comes back (two pads of one model share an id, so they are
+ * told apart by their place in the pad list: each returns to the slot
+ * holding that place). Leaving by button works only while joining is
+ * open; otherwise `leave` is an ordinary action (a pause menu), and
+ * `pool.leave(slot)` frees the slot. `pool.seat(slot, device)` puts a
+ * player in without a press: one who is in from the start.
+ *
+ * @example
+ * ```ts
+ * const Players = Controls.players(Actions, { slots: ["p1", "p2"], join: "join", leave: "back" })
+ * const makePlayers = (devices: {
+ *   readonly left: Keyboard.Actions<typeof leftKeys>
+ *   readonly right: Keyboard.Actions<typeof rightKeys>
+ *   readonly pads: Gamepad.Pads<typeof padBindings>
+ * }) => Players.pool(devices)
+ *
+ * // In a system:
+ * const input = resources.input.get()
+ * if (input.p2.event === "joined") spawnSecondPlayer()
+ * const move = input.p2.vectors.move
+ * ```
+ */
+export declare const players: <A extends string, V extends string, const S extends readonly [string, ...Array<string>], const J extends A | "any", const L extends A = never>(actions: ActionSet<A, V> & NoAnyAction<A>, options: {
+    readonly slots: S & SlotNames<S[number]>;
+    readonly join: J;
+    readonly leave?: L;
+}) => PlayerSet<A, V, S[number], Exclude<J, "any">>;
+//# sourceMappingURL=Controls.d.ts.map