@woosh/meep-engine 3.0.2 → 3.2.0

package/src/engine/input/ecs/ism/ISM_DESIGN.md

@@ -1,1523 +1,1523 @@
-# Input System Mapping — design
-
-A binding layer for keyboard, pointer buttons and gamepad, replacing `Input`/`InputSystem`, the keyboard half
-of `InputController`/`InputControllerSystem`, `EditorKeyMap` and `Tool.handleKeyboardEvent`.
-
-Status: **design, not yet implemented.** The only file in this directory today is
-[`InputBinding.js`](InputBinding.js) (the `{path, event}` record used by
-[`Input`](../components/Input.js)); it is superseded by §4.
-
-> **Revision 3.** Rewritten after an adversarial review of revision 2 found three defects that made it
-> unimplementable, and several false claims about the existing codebase. What changed, and why, is in §17.
-> The three that matter: the sequence matcher's reset paths were broken (§5); occlusion could not reach polled
-> reads, so a modal dialog could not stop a camera (§8); and coordinate bindings had no home in either the
-> component or the wire format (§9.1, §10). Two scope decisions were taken at the same time: **pointer
-> gestures are out of scope** (§1.1), and **`SimpleStateMachine` is not used** (§5.6).
-
----
-
-## 0. Summary
-
-Two decisions carry the design.
-
-> **1. Every input this system binds is either a switch or a coordinate.** `InputDeviceSwitch` already exists
-> and is already what keyboard keys, pointer buttons and gamepad buttons *are*. A coordinate is an
-> N-dimensional analog channel — stick deflection, wheel ticks, pointer position.
->
-> **2. Every trigger is a predicate over (held switches + its own state), and a binding fires on that
-> predicate's rising edge** — evaluated the instant an edge arrives, never on a frame boundary.
-
-| Requirement | Falls out of |
-|---|---|
-| Combinations (chords) | A chord is the AND of its children's predicates |
-| Sequences | A sequence is a predicate over a small linear matcher, advanced per edge (§5) |
-| Cross-device combos | A chord cannot tell which device a child came from — there is nothing to make work |
-| Arbitrary devices | A device is anything that hands out switches and coordinates (§3) |
-| Layers, top wins | Cascade over an action table, compiled once per change, like CSS (§7) |
-| Serializable bindings | A binding is `(trigger, action name)`; both halves are plain data (§6.1, §10) |
-| No added latency | Evaluation is eager on the edge; the tick services only time (§2) |
-
-Two defects in the current systems that this fixes on the way past:
-
-1. **Binding resolution can throw.** `resolvePath` throws on an unresolvable path
-   ([`resolvePathByArray.js:47`](../../../../core/json/resolvePathByArray.js)), which is why a gamepad binding
-   is a load-order landmine (see [`GAMEPAD_API_PROPOSAL.md §3`](../../GAMEPAD_API_PROPOSAL.md)). Source
-   resolution here is total.
-2. **Nothing can express a combination.** `Ctrl+Z` is not expressible as a path, which is why
-   [`EditorKeyMap`](../../../../../editor/EditorKeyMap.js) exists as a parallel, unserializable, unrebindable
-   input system made of `if (event.ctrlKey)`.
-
----
-
-## 1. Scope
-
-### 1.1 Pointer gestures are out of scope
-
-`PointerDevice` synthesizes gestures on top of its buttons — `tap`, `drag`, `dragStart`, `dragEnd`, `move`,
-`wheel`, `pinch`, `pinchStart`, `pinchEnd` — and those are **not** modelled here. They are stateful
-constructions with their own parameters (`tap` fires on *release*, gated on ≤ 10 px of travel and ≤ 1 s;
-`PointerDevice.js:20-40`), not switches, and folding them into the trigger algebra is a separate piece of work.
-
-This is a deliberate limit with a measurable cost. Of the pointer bindings in shipping consumers:
-
-| `down`/`up` | `tap` | `drag`/`dragStart`/`dragEnd` | `move` | `wheel` | `pinch`/`pinchStart` |
-|---|---|---|---|---|---|
-| 6 | 4 | 4 | 2 | 2 | 2 |
-
-Only the first column is expressible. **Consumers bound to gestures stay on `InputController`**, which is
-therefore *reduced*, not retired, by this program (§14). Chief among them:
-`StrategyInteractionController` (17 bindings, including both pinch bindings),
-`makeOrbitalCameraController` (tap + down + drag + wheel), and `RadialContextMenu`.
-
-### 1.2 What is replaced
-
-| Mechanism | Disposition | Why |
-|---|---|---|
-| [`Input`](../components/Input.js) + [`InputSystem`](../systems/InputSystem.js) | **Retired** (one holdout, §14) | Magic string paths; one source per binding; no combinations; `resolvePath` throws; `serializable = false` |
-| [`EditorKeyMap`](../../../../../editor/EditorKeyMap.js) | **Retired** | Exists only because chords are inexpressible above; hard-coded, unrebindable, undiscoverable |
-| `Tool.handleKeyboardEvent` | **Retired** | An unconditional forward to the active tool, with no gating |
-| [`KeyboardCameraController`](../controllers/KeyboardCameraController.js) | **Retired** | 16 `bind()` calls maintaining a `controls` struct — a 2-D coordinate written by hand (§3.3) |
-| [`InputController`](../components/InputController.js) + [`InputControllerSystem`](../systems/InputControllerSystem.js) | **Reduced** | Keyboard and button bindings move; gesture bindings stay (§1.1) |
-| Direct `engine.devices.*.on.*.add(...)` in gameplay code | **Case by case** | Not bindable, not rebindable, not occludable; but gesture subscriptions have nowhere to go yet |
-
-**Not in scope at all:** direct device reads in `prototype*.js` / `test*.js` harnesses. Those are internal
-tools, and polling `pad.buttons[GamepadButtons.a].is_down` remains the blessed path for anything that does not
-want a binding layer. The ISM sits *above* the devices; it does not close them off.
-
----
-
-## 2. Evaluation: eager on edges, ticked only for time
-
-There is **no input buffer and no added frame of latency.** An edge is evaluated and dispatched inside the
-device signal that produced it.
-
-```
- InputDeviceSwitch.down / .up            (keyboard/pointer: DOM event. gamepad: poll.)
-            |
-            v
- ISM edge handler  --- synchronous, no queue ---------------------------------
-            |
-            |  1.  stamp arrival time
-            |  2.  update #held : BitSet
-            |  3.  append to the recorder, if one is attached          (§2.4)
-            |  4.  walk maps by `order` descending, skipping suppressed maps (§8):
-            |          for each candidate trigger touching this switch,
-            |          in specificity order (§4.6):
-            |              was := trigger.satisfied
-            |              now := trigger.test(#held)
-            |              trigger.satisfied := now
-            |              if (now && !was)  consume, dispatch
-            |  5.  apply changes deferred during dispatch              (§2.3)
-            v
- dataset.sendEvent(entity, action, event)   -- consumer runs here, this instant
-```
-
-`#held` is exact at dispatch time by construction, because dispatch *is* the edge. No replay, no
-reconstruction.
-
-### 2.1 The tick services time, and only time
-
-`System.update(dt)` dispatches no edge-driven action. It services the four things that change without an edge:
-
-1. **`InputTriggerHold` maturity.** A hold for 0.5 s becomes true 0.5 s after its child did, which no edge
-   announces. When it matures it emits a **synthetic edge** into the same walk as step 4 above, carrying the
-   hold's own `collectSources()` set so consumption (§8) has something to match against. Latency is bounded by
-   the frame, which is inherent: nothing observes time more finely than the loop observing time.
-2. **Sequence step windows** (§5.2) — both the refresh while a previous step still holds, and the expiry.
-3. **`Delta` coordinate reset** (§3.3).
-4. **Suppression recompute** when the linked map set, `order` or `occlusion` changed during the frame (§8).
-
-A trigger built only from switches and chords is untouched by `update`.
-
-### 2.2 Polled devices are bounded by their own poll rate
-
-`GamepadDevice` polls once per animation frame and drives its switches from the result
-(`GamepadDevice.js:370-407`), so gamepad edges cannot be finer-grained than that — a Gamepad API property, not
-one this design imposes. `GamepadDevice.poll()` is callable manually, so a consumer driving a fixed-rate loop
-can raise its own resolution. Keyboard and pointer edges are DOM-driven and carry no such floor.
-
-### 2.3 The re-entrancy contract
-
-Consumer code runs inside a DOM event handler. Four cases, each with a stated rule:
-
-* **Structural change** — a handler adds or removes an entity, and therefore an `InputMap`. Queued, applied at
-  step 5, after the current edge finishes.
-* **Binding edits on a linked map** — a handler calls `bind()` / `pushLayer()`, which §9.3 says triggers a
-  recompile. The recompile is queued with structural changes and applied at step 5; the walk always runs to
-  completion against the program it started with. This path is not exotic: it is the rebinding-capture flow.
-* **Nested edges** — a handler calls `GamepadDevice.poll()` (blessed in §2.2) or synchronously dispatches a DOM
-  event (`element.click()`, `.focus()`), re-entering the walk. **Rejected**: a re-entrant edge is queued and
-  replayed at step 5 rather than processed inline, because processing it inline would mutate `#held` under the
-  outer walk and clobber the shared `InputActionEvent` (§6.3) before the outer handler finished reading it.
-* **A handler that throws** — it throws. `#held` and the recorder are updated *before* dispatch (steps 2–3), so
-  ISM state stays consistent and the failure is visible, per the codebase's position on not swallowing errors.
-
-*(For contrast, `InputControllerSystem` carries a `deferred` array for the first case that **nothing ever
-populates** — `add()` registers directly under a `//TODO handle case where binding is added mid-dispatch`
-(`InputControllerSystem.js:119-121`). The hazard is real and currently unhandled, not handled badly.)*
-
-### 2.4 Ordering, and what it costs
-
-Action effects land wherever in the frame the edge arrived, so two actions in one frame are ordered by
-arrival, not by system order. That is the direct consequence of wanting zero latency, and §4.6 and §5.5 record
-the two places it is observable.
-
-### 2.5 Recording and replay
-
-An optional recorder captures, per frame: the frame's `dt`, every switch edge as
-`(source_index, is_down, time)`, and a sample of every **coordinate channel** any linked map references.
-Coordinates must be recorded because they are read by polling, not driven by edges — without them,
-`InputActionEvent.value` and every `axis*` read diverge on replay. `dt` must be recorded because hold maturity
-and window expiry are evaluated on the tick, so a different frame cadence produces different fire times.
-
-Replay injects recorded edges at their recorded positions within each recorded frame and drives the same eager
-path. Interned `source_index` values are stable only within one link generation, so the recorder writes the
-source table alongside and remaps on load.
-
-The recorder is an observer, not the mechanism — attach it for a determinism run or a bug report, leave it off
-otherwise.
-
-### 2.6 `preventDefault`, and its granularity
-
-[`KeyboardDevice`](../../devices/KeyboardDevice.js) calls `event.preventDefault()` when the pressed key's
-`down` signal *has handlers* (`KeyboardDevice.js:112-118`). Since the ISM subscribes to precisely the keys some
-live binding references, browser-default suppression tracks the bound key set automatically.
-
-**Granularity is per key, not per chord**, and this is worth knowing before it surprises someone: binding only
-`Ctrl+S` subscribes `s`'s `down` signal, so a *bare* `S` keydown is also `preventDefault`ed anywhere the device
-element sees it. This is inherited behaviour, not new — `InputController` binding `keyboard/keys/s/down` does
-the same — but chords make it newly reachable. Changing it means changing `KeyboardDevice`, which is out of
-scope here.
-
----
-
-## 3. Devices, switches and coordinates
-
-### 3.1 The adapter
-
-```js
-/**
- * Adapts a concrete input device to the ISM.
- *
- * Resolution must be TOTAL: an adapter answers for every code it declares, whether or not hardware is
- * present. Absent hardware reads as "up" and as zero, never as undefined, and never throws. This is the
- * property `resolvePath` lacked.
- */
-export class InputDeviceAdapter {
-    /** Stable identifier, written into serialized bindings. ASCII, lower_snake_case. @type {string} */
-    id = "";
-
-    /** @param {number} code @returns {InputDeviceSwitch} */
-    getSwitch(code) { }
-
-    /** @param {number[]|Float64Array} result @param {number} offset @param {number} code */
-    readCoordinate(result, offset, code) { }
-
-    /** Begin/stop observing the device. Adapters with nothing to subscribe to leave these alone. */
-    startup() { }
-    shutdown() { }
-
-    /** Publish this frame's relative-channel totals and start a new window. See the latch rule in §3.3. */
-    latchDeltas() { }
-}
-```
-
-A channel's *dimensionality* is not asked of the adapter. It is a static property of the channel code, known
-to the typed constructors (§3.3), so a binding on an unregistered device still knows its own shape.
-
-| Adapter | `id` | Switch codes | Coordinate codes |
-|---|---|---|---|
-| `KeyboardInputDeviceAdapter` | `"keyboard"` | [`KeyCodes`](../../devices/KeyCodes.js) | — |
-| `PointerInputDeviceAdapter` | `"pointer"` | `MouseButtons` | `PointerCoordinates` |
-| `GamepadInputDeviceAdapter` | `"gamepad"` | [`GamepadButtons`](../../devices/gamepad/GamepadButtons.js) | `GamepadCoordinates` |
-
-Three enums are new, and each needs a stability note because their values become `uint16` codes on disk:
-
-* **`MouseButtons`** — `left: 0, middle: 1, right: 2, back: 3, forward: 4`. These are
-  **`MouseEvent.button` ordinals**, matching how `PointerDevice.buttons[]` is indexed
-  (`PointerDevice.js:300-318`: `mouseButtonLeft` is `[0]`, `mouseButtonMiddle` is `[1]`, `mouseButtonRight` is
-  `[2]`). They are deliberately **not** the `MouseEvent.buttons` *bitmask* order, which is left/right/middle —
-  taking that order would index `buttons[1]` for a right-click and fire every right-click binding on the
-  middle button, into saved data.
-* **`PointerCoordinates`** — `position`, `move`, `wheel`.
-* **`GamepadCoordinates`** — `left_stick`, `right_stick`, `dpad`.
-
-Values are append-only once shipped, like `KeyCodes` and `GamepadButtons` before them.
-
-A fourth device — MIDI pedal, wheel, eye tracker, a network-driven replay source — is an adapter and a
-registration call. Nothing in the trigger, layer, cascade or serialization layers changes, because none of them
-can tell devices apart.
-
-The gamepad adapter binds `GamepadDevice.main`, the persistent handle: it exists before any hardware does,
-survives disconnection, and rebinds to the oldest connected pad on a swap (`GamepadDevice.js:110, 306-344`). A
-serialized gamepad binding therefore resolves at load time and keeps working across a hot-swap — the defect
-`GAMEPAD_API_PROPOSAL.md §3` identified and could not fix from the device side alone.
-
-**A device that is not registered** is not an error. A map naming an unregistered `id` links successfully and
-its bindings on that device are inert — the same contract as connected-but-absent hardware, so a saved map
-never fails to load because a peripheral is missing. `registerDevice()` may be called after maps are linked; it
-recompiles every linked map (§9.3), at which point those bindings become live.
-
-### 3.2 Switch sources
-
-```js
-export class InputSource {
-    device = "";                    // InputDeviceAdapter#id
-    code = 0;
-}
-```
-
-One flat value type with `equals`/`hash`/`toBinaryBuffer`/`fromBinaryBuffer`, deliberately *not* a
-`KeySource`/`GamepadButtonSource`/… hierarchy: a chord over `{keyboard:ctrl, pointer:0}` needs no polymorphic
-dispatch, serialization is `(device_index: Uint8, code: Uint16)` against a per-map device table (§10) with no
-type tags, and interning to an integer (§9.3) is a two-field hash after which the hot path never touches the
-object again. The typing that matters to an author lives on the *trigger* constructors (§4.2).
-
-### 3.3 Coordinates — analog channels of arbitrary dimensionality
-
-An analog channel is not a scalar axis. `WheelEvent` carries `deltaX`, `deltaY` and `deltaZ`, and
-[`PointerDevice`](../../devices/PointerDevice.js) surfaces all three (`PointerDevice.js:398-404`). A 1-D axis
-abstraction would have to either drop `deltaZ` or invent three channels for one control.
-
-*(Precisely: `PointerDevice` reports `sign(event.deltaX/Y/Z)`, so components are -1, 0 or 1 and scroll
-magnitude is discarded at the device. A `Delta` wheel channel therefore accumulates **tick counts**, not
-distance. That is the device's existing behaviour; the ISM reports what it is given.)*
-
-```js
-export class InputCoordinateSource {
-    device = "";
-    code = 0;
-    /** Component count. 2 for a stick or pointer position, 3 for a wheel. @type {number} */
-    dimensions = 1;
-    /** @type {InputCoordinateKind} */
-    kind = InputCoordinateKind.Normalized;
-}
-
-export const InputCoordinateKind = {
-    /** A position in some space. Read at any time, no accumulation. Pointer position. */
-    Absolute: 0,
-    /** A change. Accumulates within a frame, zeroed at the frame boundary. Wheel. */
-    Delta: 1,
-    /** Deflection, each component in [-1, 1]. Stick, d-pad. */
-    Normalized: 2
-};
-```
-
-`kind` is the verb — what the numbers *mean*. `Delta` is the one with behaviour attached, and it is why the
-tick exists at all: two wheel events in one frame must sum.
-
-**The `Delta` visibility rule, stated exactly.** A relative channel **latches**; it is not cleared. The
-adapter accumulates arriving events into one buffer, and once per frame `update` publishes that buffer into a
-second one and starts a fresh accumulation window. Readers see the published value.
-
-Latching rather than clearing is load-bearing, and the obvious alternative is wrong. Device events arrive
-*between* frames, so an adapter that zeroed its accumulator at the top of a frame would destroy exactly the
-events that frame exists to report. Latching also makes the value **independent of system execution order**:
-every reader in a frame sees the same number whether it runs before or after the ISM, which is what the
-"same value for every reader" guarantee actually requires.
-
-An **eager handler** reading a `Delta` channel mid-frame sees the value published for the frame in progress —
-the same one the tick-time readers will see — not a running total of events that have arrived since. Those
-belong to the next frame.
-
-**Reading.** The general accessor writes into an indexable numeric buffer; common dimensionalities get typed
-conveniences over the engine's vector types:
-
-```js
-map.coordinate(result, offset, 'look');   // Float64Array | number[] - any dimensionality
-map.axis1(v1, 'throttle');                // Vector1
-map.axis2(v2, 'move');                    // Vector2
-map.axis3(v3, 'wheel');                   // Vector3
-```
-
-Result-first argument order follows the engine's `f(result, ...)` convention.
-
-**Channels.** A coordinate action is driven by a channel, and the consumer cannot tell which kind:
-
-```js
-InputCoordinateGamepad.from(GamepadCoordinates.left_stick)   // hardware channel
-InputCoordinatePointer.from(PointerCoordinates.wheel)        // hardware channel, 3-D
-InputCoordinateSwitches.from([                               // N-D from 2N switch triggers
-    InputTriggerKey.from('a'), InputTriggerKey.from('d'),    //   x: negative, positive
-    InputTriggerKey.from('w'), InputTriggerKey.from('s')     //   y: negative, positive
-])
-InputCoordinateCompose.from(x_channel, y_channel)            // stitch channels
-```
-
-`InputCoordinateSwitches` is [`KeyboardCameraController`](../controllers/KeyboardCameraController.js) as data,
-and it generalises past 2-D for free.
-
-**Shaping stays at the call site.** No dead zone, no response curve, no sensitivity inside the ISM. It returns
-the composed raw value and the consumer calls
-[`apply_radial_dead_zone`](../../analog/apply_radial_dead_zone.js). This is the position
-`GAMEPAD_API_PROPOSAL.md §1.2` argues at length; reversing it here would put the same policy back in the same
-wrong layer, one floor up.
-
-### 3.4 Derived switches: a direction is a coordinate with a threshold
-
-`InputTriggerDirection` turns a coordinate into a switch — "the stick is in the *down-right* octant". This is
-what makes motion inputs work (§5.4), and it is not bolted on for them: a d-pad is already a coordinate in this
-codebase (`gamepad_write_dpad_vector`), so one path serves stick and d-pad.
-
-The eight directional switches derived from one coordinate are **mutually exclusive by construction**, and the
-derived layer **releases the old direction before pressing the new one**, so exclusivity is never momentarily
-violated. §5.4 depends on both.
-
-Three properties an implementer must know, because none is free:
-
-* **Threshold.** Producing a boolean from a coordinate requires one by definition. This is not an exception to
-  §3.3, which forbids shaping the *analog value* handed to a consumer. Constructor argument, defaulted.
-* **Sampling.** Octant transitions are observed only as often as the channel updates. On a gamepad that is the
-  rAF poll (§2.2), so a fast quarter-circle can pass from `Down` to `Right` between two polls without ever
-  reporting `DownRight`, and a motion requiring that step silently fails. Sequences over directions are
-  reliable at hand speed, not at frame-perfect speed.
-* **Hysteresis.** A stick resting on an octant boundary chatters release/press pairs. The threshold carries an
-  angular hysteresis band, defaulted, for the same reason it carries a magnitude threshold: without it a
-  boundary rest position resets hold timers continuously.
-
----
-
-## 4. Triggers
-
-### 4.1 One interface, two methods and one field
-
-```js
-export class InputTrigger {
-    /**
-     * Is this trigger's condition currently met?
-     * Pure for leaves and combinators. `InputTriggerHold` and `InputTriggerSequence` additionally consult
-     * per-instance state, which edges and ticks maintain.
-     *
-     * @param {BitSet} held interned switch indices currently down
-     * @returns {boolean}
-     */
-    test(held) { }
-
-    /**
-     * Every switch index this trigger can be affected by. Collected once, at compile time (§9.3).
-     * @param {number[]} result
-     */
-    collectSources(result) { }
-
-    /**
-     * Last observed value of `test`, per compiled instance. A binding fires when `test` is true and this
-     * is false. Initialised at compile time to `test(held-at-compile)` - NOT to false. See §4.5.
-     * @type {boolean}
-     */
-    satisfied = false;
-}
-```
-
-**A binding fires on the rising edge of `test`.** That single rule covers press, release, hold, chord, sequence
-and direction, and it is why there is no `Started`/`Performed`/`Canceled` phase enum and no `edge` field.
-
-### 4.2 Leaf triggers — typed constructors
-
-```js
-InputTriggerKey.from('space')
-InputTriggerKey.from(KeyCodes.space)
-InputTriggerMouseButton.from(MouseButtons.left)
-InputTriggerGamepadButton.from(GamepadButtons.a)
-InputTriggerDirection.from(stick, InputDirection.DownRight)     // stick: any InputCoordinate* channel
-```
-
-Each extends `InputTriggerSwitch`, which holds one `InputSource` and whose `test` is `held.get(index)`. The
-subclasses add no fields — they are typed, validating constructors that fix the device and check the code
-against that device's enum. `InputTriggerKey.from('nonexistent')` fails at authoring time under `assert.*`,
-which is compiled out of production, so the typing is free in shipped code.
-
-Serialization round-trips the flat form, so a deserialized trigger is an `InputTriggerSwitch`, not an
-`InputTriggerKey`. Nothing needs the subclass identity at runtime — it exists for the author and the assertion.
-
-### 4.3 Combinators
-
-```js
-InputTriggerChord.from(a, b, c)          // test = AND over children
-InputTriggerRelease.from(a)              // test = NOT child.test
-InputTriggerHold.from(a, 0.5)            // test = child.test AND continuously true for >= 0.5s
-InputTriggerSequence.from(a, b, c)       // test = the matcher completed on this edge (§5)
-```
-
-Combinators take *triggers*, not sources, which is why the requirements compose:
-
-```js
-// "the chord ended"
-InputTriggerRelease.from(InputTriggerChord.from(InputTriggerKey.from('ctrl'),
-                                                InputTriggerKey.from('z')))
-
-// "hold Ctrl+Shift for half a second"
-InputTriggerHold.from(InputTriggerChord.from(InputTriggerKey.from('ctrl'),
-                                              InputTriggerKey.from('shift')), 0.5)
-
-// cross-device: nothing here knows a device is involved
-InputTriggerChord.from(InputTriggerKey.from('ctrl'),
-                       InputTriggerMouseButton.from(MouseButtons.left))
-```
-
-`InputTriggerRelease` as *negation* rather than an edge kind is what makes it compose — an edge flag on a chord
-could not express "when this chord stops holding".
-
-**One composition that does not mean what it looks like:** `InputTriggerRelease.from(sequence)`. A sequence's
-`test` is a single-edge pulse (§5.2 step 5), so negating it yields "true except on the completing edge", which
-rises on the *next* evaluated edge after every completion — an echo of the fire, not "the sequence stopped
-matching". A sequence's partial-match state is deliberately not exposed to `test`. Do not wrap a sequence in
-`Release`.
-
-### 4.4 Step timeout lives on the sequence
-
-```js
-InputTriggerSequence.from(a, b, c).withStepTimeout(0.25)
-```
-
-Default **1.0 s**, which suits editor and menu sequences whose first step is a chord the author must release
-before reaching for the next key. Fighting-game motions want 0.15–0.25 s. §5.2 defines exactly what the window
-measures, which is not what a naive reading suggests.
-
-Timing was specified here as **real time**, stamped at edge arrival, on the argument that a paused game must
-not give a chord an infinite window and a game at 0.25× speed must not quarter the player's reflexes.
-
-**Superseded.** As built it is *simulation* time, advanced by `update(dt)` and nowhere else. The reason is
-testability: a real-time clock cannot be driven from a spec without faking one, and faking it is a mock. The
-consequences are real and accepted — windows stretch under slow motion and freeze while the game is paused,
-so a hold inside a pause menu can never mature. See the implementation plan's amendments section for the full
-argument.
-
-### 4.5 `satisfied` is initialised from state, not from false
-
-At compile time each trigger instance sets `satisfied := test(held)` against the currently held switches. It is
-**not** zero-initialised, and the difference is not academic:
-`InputTriggerRelease.from(InputTriggerChord.from(ctrl, z))` has `test` true whenever the chord is *not* held —
-which is almost always. Zero-initialised, the first edge touching `ctrl` or `z` would see `now=true, was=false`
-and fire "the chord ended" before the chord ever existed.
-
-This matters on every compile, not just the first: maps link mid-dispatch (§2.3), and `registerDevice` and
-binding edits both recompile live maps while keys are held.
-
-### 4.6 Precedence within a layer
-
-Candidate triggers on one edge are ordered, and the order is total so it never depends on declaration accident:
-
-1. **Sequences first**, longer before shorter (by step count).
-2. Then by **chord width** — the number of switches that must be simultaneously held. `Hold` and `Release`
-   rank by their child's width, so `Hold(Chord(a,b), t)` ranks as width 2 and beats `Key(a)`; `Direction` ranks
-   as width 1.
-3. Then declaration order within the layer.
-
-A fired trigger consumes its switches for the remainder of the current edge (§8), so `Ctrl+Z` firing means `Z`
-does not.
-
-**The condition on that guarantee.** Consumption is scoped to one edge, so it arbitrates only triggers that
-complete on the *same* edge. `Ctrl` pressed before `Z` gives one edge (`z↓`) at which both `Ctrl+Z` and `Z` are
-satisfiable, and the chord wins. `Z` pressed **before** `Ctrl` gives two edges: `z↓` fires `Z`'s action (the
-chord is not yet satisfiable, so there is nothing to lose to), then `ctrl↓` fires `undo`. **Both fire.**
-
-This is inherent to zero-latency evaluation — suppressing the first would mean either delaying it or retracting
-a dispatched action, and both are excluded. Practically it is rarely reached, because modifier-first is how
-people type chords. Where it matters, do not bind a bare key in the same layer as a chord that contains it.
-
----
-
-## 5. Sequence semantics
-
-### 5.1 State
-
-Per sequence binding instance, three numbers, held on the **compiled clone** of the trigger (§9.3):
-
-```js
-#step             // steps matched so far, 0..N
-#stepSatisfied    // last observed value of steps[#step].test
-#window           // time the current step's window last refreshed
-```
-
-*(An earlier revision put these in typed arrays on the program, indexed by sequence-binding index. Cloning per
-binding is what the compiler does anyway — authored triggers are shared, so evaluation state cannot live on
-them — and once each binding owns a private trigger object, three fields on it are the same thing with less
-bookkeeping. Nothing allocates per evaluation either way.)*
-
-Entering a state is one operation, and **every** path into a state uses it. That is the whole of §17's most
-important correction:
-
-```js
-function enter(k, held, now) {
-    step      = k;
-    satisfied = (k < N) ? steps[k].test(held) : false;   // the entry snapshot
-    window    = now;
-}
-```
-
-### 5.2 The rule
-
-Evaluated at each edge (device or synthetic) and each tick:
-
-```
-1.  if (step > 0) {
-        if (steps[step - 1].test(held))          window := now          // previous step still holds
-        else if (now - window > step_timeout)    enter(0, held, now)     // window expired
-    }
-
-2.  cur := steps[step].test(held)
-
-3.  if (cur && !satisfied) {
-        enter(step + 1, held, now)
-        if (step === N) {
-            fire()                     // the sequence's own `test` reads true for this edge
-            enter(0, held, now)
-        }
-    } else {
-        satisfied := cur
-    }
-```
-
-Three properties do all the work:
-
-* **Advance on a rising edge, not on satisfaction.** Otherwise one long press of `A` satisfies both steps
-  of `[A, A]`.
-* **The entry snapshot, on every entry.** Advance, expiry and post-fire wrap all route through `enter`, so a
-  reset can never leave a stale `satisfied` behind. `enter` never indexes `steps[N]`.
-* **The window measures time since the previous step stopped holding**, not time since the advance. Step 1
-  refreshes `window` for as long as `steps[step-1]` is still satisfied, which is what makes charge inputs work
-  (§5.4) and is why the tick must service sequences even when no edge arrives.
-
-**A mismatch does not reset. Only window expiry resets.** A sequence is a leniency window, and the window is
-what §5.2 step 1 defines.
-
-### 5.3 Worked: `[A, A, B]` on `A↓ A↑ A↓ A↑ A↓ B↓`
-
-| edge | held | step | step-1 holds? | `cur` | `satisfied` | result |
-|---|---|---|---|---|---|---|
-| — | {} | 0 | — | — | false (compile snapshot) | |
-| `A↓` | {A} | 0 | — | true | false | **rise** → `enter(1)`, `satisfied := A.test({A}) = true` |
-| `A↑` | {} | 1 | no | false | true | `satisfied := false` |
-| `A↓` | {A} | 1 | yes → refresh | true | false | **rise** → `enter(2)`, `satisfied := B.test({A}) = false` |
-| `A↑` | {} | 2 | no | false | false | — |
-| `A↓` | {A} | 2 | yes → refresh | false | false | — |
-| `B↓` | {A,B} | 2 | yes → refresh | true | false | **rise** → `enter(3)` = N → **fire**, `enter(0)` |
-
-No failure function, no KMP: the entry snapshot alone prevents one press from satisfying two steps.
-
-**Post-fire, the case revision 2 got wrong.** `enter(0, {A,B}, now)` snapshots `satisfied := A.test({A,B}) =
-true`. So with `A` still held, tapping `B` again gives `cur = true, satisfied = true` — no rise, no fire.
-Revision 2 left `satisfied` untouched on the post-fire reset, and holding `A` while mashing `B` machine-gunned
-the action off a single `A` press.
-
-### 5.4 Worked: chords, motions and charge
-
-**`Ctrl+Shift+A > B`** — steps are triggers, and a chord is a trigger, so this is not a special case:
-
-```js
-map.bind('promote', InputTriggerSequence.from(
-    InputTriggerChord.from(InputTriggerKey.from('ctrl'),
-                           InputTriggerKey.from('shift'),
-                           InputTriggerKey.from('a')),
-    InputTriggerKey.from('b')
-));
-```
-
-`ctrl↓`, `shift↓`: chord false. `a↓`: chord rises → `enter(1)`, `satisfied := b.test({ctrl,shift,a}) = false`.
-Then `b↓` fires — **whether or not the modifiers were released first**, because leaf and chord tests are
-*subset* tests over the held set, and because holding the chord keeps refreshing the window rather than
-starting its clock.
-
-**Quarter-circle forward, `↓ ↘ →`** — this is the case that only works because directions are derived from a
-coordinate (§3.4) rather than read off raw d-pad buttons:
-
-```js
-const stick = InputCoordinateGamepad.from(GamepadCoordinates.left_stick);
-
-map.bind('hadouken', InputTriggerSequence.from(
-    InputTriggerDirection.from(stick, InputDirection.Down),
-    InputTriggerDirection.from(stick, InputDirection.DownRight),
-    InputTriggerDirection.from(stick, InputDirection.Right)
-).withStepTimeout(0.2));
-```
-
-| edge | held | step | `cur` | result |
-|---|---|---|---|---|
-| `Down↓` | {Down} | 0 | true | **rise** → `enter(1)`, `satisfied := DownRight.test({Down}) = false` |
-| `Down↑` | {} | 1 | false | — |
-| `DownRight↓` | {DownRight} | 1 | true | **rise** → `enter(2)`, `satisfied := Right.test({DownRight}) = false` |
-| `DownRight↑` | {} | 2 | false | — |
-| `Right↓` | {Right} | 2 | true | **rise** → `enter(3)` = N → **fire** |
-
-The two snapshots in the result column are the trick. With raw d-pad buttons `↓` and `→` can be held together,
-`Right.test({Down,Right})` is `true` on entry to state 2, and the motion can never complete. Exclusivity by
-construction is what removes that failure mode — which is why §12.2 tests it in both directions.
-
-**Dragon punch, `→ ↓ ↘`** — the same trace with steps permuted; each entry snapshot is false for the same
-reason. Verified also against the realistic rolled input `Right, DownRight, Down, DownRight`, where the
-intermediate `DownRight↓` at step 1 is a non-advancing mismatch (ignored, correctly) and the final one fires.
-
-**Charge, `hold ← for 2 s, then →`** — the case revision 2 published as passing and which in fact failed:
-
-```js
-InputTriggerSequence.from(
-    InputTriggerHold.from(InputTriggerDirection.from(stick, InputDirection.Left), 2.0),
-    InputTriggerDirection.from(stick, InputDirection.Right)
-)
-```
-
-At t=2.0 the hold matures, emits a synthetic edge (§2.1) and rises → `enter(1)`. The player then keeps holding
-`←`, which is what charge play *is*. Under revision 2 the window ran from the advance, so any charge longer
-than `duration + step_timeout` expired before the flick and the move was silently lost; raising the timeout
-instead produced ghost charges minutes later. Under §5.2 step 1, `steps[0].test` — the hold — is still true
-while `←` is held, so `window` is refreshed on every tick. Release `←` at t=8.0 and the window opens *there*;
-`→` within `step_timeout` fires. Return to neutral instead and the window expires normally, so there is no
-ghost.
-
-**Motion plus button, `236 + P`** — append `InputTriggerGamepadButton.from(GamepadButtons.x)` as a fourth step.
-While `→` is held, step 1 keeps refreshing the window, so the button may be pressed at leisure; it fires with
-`→` still held because button steps are subset tests.
-
-### 5.5 What this deliberately cannot do
-
-**Strict rejection.** `↓ ← →` inside the window fires the quarter-circle, because `←` neither advances nor
-resets. Arcade-grade matchers reject a direction outside the expected set. The shape of the fix is known — an
-optional rejection predicate on the sequence, resetting to 0 when it matches — and it is **deferred until a
-consumer asks**, on the position that the common case should be the only case. For every sequence in this
-codebase, and for menu, cheat-code and editor cases, leniency is the wanted behaviour.
-
-**Button buffering.** A button pressed *before* the motion step it follows poisons that step's entry snapshot
-and must be re-pressed. Genre-standard buffering is a fighting-game engine feature, not an input-mapping one.
-
-**Tap versus hold on the same switch — accepted as a cost of zero latency.** Given
-`'interact' = Key(e)` and `'loot_all' = Hold(Key(e), 0.5)`, a press-and-hold fires **both**: `'interact'` at
-`e↓`, `'loot_all'` 0.5 s later. They complete on different edges, so §4.6's per-edge consumption cannot
-arbitrate them, and no composition inside the algebra separates them either —
-`Chord(Release(e), Release(Hold(e, 0.5)))` collapses, because `hold.test` falls to false on the same `e↑` edge
-the release rises on.
-
-Discriminating them requires *withholding* the short action until the hold window has passed, which is
-precisely the frame-buffered dispatch this design exists to avoid. Paying that architectural cost — a second,
-deferred dispatch path with its own ordering and occlusion semantics — for one interaction pattern is not
-worth it. **Tap-and-hold pairs must use distinct inputs** (`E` and `Shift+E`), or accept that the hold is
-additive to the tap. Revision 2 claimed §4.6 arbitrated this; it does not.
-
-**Key autorepeat.** `KeyboardDevice` discards `event.repeat` (`KeyboardDevice.js:93-97`) and
-`InputDeviceSwitch.press()` is idempotent, so a held key produces exactly one edge. Autorepeat is not
-observable anywhere in this design, and a consumer that wants repeat behaviour — held-key menu navigation,
-`EditorKeyMap`'s current repeat-undo — must drive it from `isActive` plus its own timer. Changing this means
-changing `KeyboardDevice`, which is out of scope.
-
-### 5.6 Why `SimpleStateMachine` is not used
-
-The first revision built this on
-[`SimpleStateMachine`](../../../../core/fsm/simple/SimpleStateMachine.js) and
-[`SimpleStateMachineDescription`](../../../../core/fsm/simple/SimpleStateMachineDescription.js). It does not
-earn its place here, and the reasons are specific rather than a matter of taste:
-
-* **The graph is a path.** States `0..N` with edges `i → i+1` plus resets to `0`. There is nothing to search,
-  so `findPath` — the description's real capability — is dead weight.
-* **The self-transition is not declarable.** "Stay in the current state on a mismatch" is the common case, and
-  the edge set never contains `i → i`. It works only because the edge-existence assertion in `advance()` is
-  commented out (`SimpleStateMachine.js:238`) — a latent trap if those assertions are ever restored.
-* **Initial state is `-1`** (`SimpleStateMachine.js:16`), so every instance needs an explicit `setState(0)`.
-* **It is not the cheap object it looks like.** Each instance carries a description reference and two handler
-  arrays (`SimpleStateMachine.js:22-30`) that this design never registers into — while `satisfied` and `window`
-  have to live outside it regardless. Three typed-array slots replace all of it with no per-instance object.
-
-The requirement was to make good use of existing meep constructs. The honest reading is that this construct
-does not fit this problem: the matcher is a path, not a graph. **`SimpleStateMachineDescription` becomes the
-right tool the moment sequences branch** — alternate motions sharing a prefix, resolved by longest match —
-and that is the point at which to adopt it, not before.
-
----
-
-## 6. Actions — the bindings/behaviour seam
-
-### 6.1 The seam
-
-```
-   DATA  (serializable, no code)                |    CODE (never serialized)
-   -----------------------------                |    ----------------------
-   trigger                ---->  action name    |    action name  ---->  behaviour
-   Chord(ctrl, z)                "undo"         |    "undo"       ---->  editor.actions.undo()
-```
-
-The left side is an `InputMap` component. The right side is an ECS event listener. They meet at a string, and
-nothing else crosses. This is the same seam [`InputSystem`](../systems/InputSystem.js) already uses
-(`InputSystem.js:79`), which is why that component is the one worth keeping the shape of. It is explicitly
-*not* a string-keyed factory registry: no behaviour is constructed from the string and no class is looked up
-by it.
-
-### 6.2 One event, one level, one coordinate
-
-```js
-// discrete — fires on the trigger's rising edge, this instant, no frame delay
-ecd.addEntityEventListener(entity, 'undo', () => editor.actions.undo());
-
-// continuous — no listener, no mirrored boolean, no teardown handler
-if (map.isActive('sprint')) { ... }
-map.axis2(v, 'move');
-```
-
-Three accessors for three *questions* — "did it happen", "is it happening", "how much" — not three ways to ask
-one question. The level accessor is what deletes
-[`KeyboardCameraController`](../controllers/KeyboardCameraController.js)'s `controls` struct, the 16 `bind()`
-calls maintaining it, and the `clearControls` handler wired to `on.unlinked` that exists solely to stop the
-camera drifting after teardown. The same boilerplate is duplicated almost verbatim in
-[`prototype_first_person_controller.js`](../../../control/first-person/prototype_first_person_controller.js).
-
-Two things `isActive` is not: it is effectively always `false` for a sequence action, whose `test` is a
-single-edge pulse; and it returns `false` for every action on a **suppressed** map (§8).
-
-*(One behaviour `KeyboardCameraController` has that the coordinate does not reproduce: it sends a `'user-input'`
-entity event on every pan keydown (`KeyboardCameraController.js:54`), consumed elsewhere as an interaction
-signal. Porting it is a `map.bind('user-input', ...)` alongside the coordinate, and §14 lists it rather than
-leaving it to be discovered missing.)*
-
-### 6.3 The event payload
-
-```js
-export class InputActionEvent {
-    action = "";
-    /** Driving coordinate, or the pointer position, at the moment the trigger fired. @type {Vector3} */
-    value = new Vector3();
-    /** The switch whose edge completed the trigger. For a synthetic hold-maturity edge, the first
-     *  switch in the hold's own source set. @type {InputSource} */
-    source = new InputSource();
-    /** Arrival timestamp of the completing edge, real time, seconds since ISM start. @type {number} */
-    time = 0;
-}
-```
-
-One instance, reused across dispatches, mutated in place. Dispatch is synchronous, so a handler that reads it
-inline is correct and one that retains it is not — stated in the JSDoc, as scratch vectors are elsewhere in
-the engine. A nested edge cannot clobber it mid-read, because nested edges are queued rather than processed
-inline (§2.3).
-
-**It carries no DOM information**, and that is a real limit worth naming: consumers that today gate on
-`event.target === graphics.domElement` to tell a canvas click from a click on overlaying UI —
-`CombatInteractionStateMachine` does — have no equivalent here. UI-overlay occlusion is a DOM-tree question
-that §8's map occlusion cannot see. Those consumers are in the gesture set that stays on `InputController`
-(§1.1) for now; a DOM-aware gate is part of the deferred gesture work.
-
----
-
-## 7. Layers — a stack, addressed by index
-
-Layers solve **rebinding**: defaults, then the player's overrides, then a context-specific tweak — one
-conceptual keymap assembled from stacked sources, top wins. They are a stack, addressed by index.
-
-```js
-const map = new InputMap();
-
-map.bind('jump', InputTriggerKey.from('space'));          // layer 0, the base
-map.bind('undo', InputTriggerChord.from(InputTriggerKey.from('ctrl'),
-                                        InputTriggerKey.from('z')));
-
-const user = map.pushLayer();                             // index 1
-user.bind('jump', InputTriggerGamepadButton.from(GamepadButtons.a));   // REPLACES space
-```
-
-```js
-map.layer(i)      // InputLayer at index i, asserts existence
-map.pushLayer()   // append, return the new top
-map.popLayer()    // discard the top
-map.bind(...)     // sugar for map.layer(0).bind(...)
-```
-
-Rules, and they are CSS's:
-
-* Higher index is higher in the cascade.
-* The cascade is **per action name**, and it applies identically to trigger bindings and coordinate bindings
-  (§9.1). The highest layer binding an action supplies *all* of that action's triggers or channels; lower
-  layers' entries for it are inert.
-* To keep both, bind both **in one layer** — a binding maps one action to a *list*, exactly as
-  `font-family: a, b` lists fallbacks in one declaration:
-
-```js
-map.bind('jump', InputTriggerKey.from('space'), InputTriggerGamepadButton.from(GamepadButtons.a));
-```
-
-  Replace-versus-add is a property of *where you write it*, not a flag on `bind`. That is what lets rebinding
-  ("the user's jump wins") and multi-device ("either device jumps") both be expressible with no mode switch.
-
-* An action named in the top layer that binds it, with nothing bound, is **unbound** — how a keymap layer
-  removes an inherited binding:
-
-```js
-map.layer(1).unbind('undo');
-```
-
-* An action name is either a trigger action or a coordinate action, never both — asserted at authoring time,
-  because `isActive('move')` and `axis2(v, 'move')` would otherwise disagree about what `'move'` is.
-
-Layers carry no names. There is nothing to look up, so nothing to mistype, and serialization is one `uint16`
-count with no strings (§10).
-
----
-
-## 8. Occlusion — arbitration across entities
-
-Layers are within one map. Modality is across maps, and it is a different question: the cascade is *nominal*
-(over action names), occlusion is *physical* (over switches).
-
-```js
-export const InputOcclusion = {
-    /** Sees everything, blocks nothing. HUD overlays, debug readouts, recorders. */
-    Pass: 0,
-    /** Switches consumed by this map's fired triggers are invisible below, for that edge. The default. */
-    BlockMatched: 1,
-    /** Every map below is suppressed outright. Modal dialogs, pause menus. */
-    BlockAll: 2
-};
-```
-
-**The two values do different jobs at different scopes, and revision 2's failure to say so was a real bug.**
-
-### 8.1 `BlockMatched` — dynamic, per edge, dispatch only
-
-Per edge, the walk descends maps by `order`. A `consumed : BitSet` over interned switch indices accumulates as
-it goes; a fired trigger adds its own switches, and a trigger whose switches are already consumed does not
-dispatch.
-
-**Consumption gates dispatch, not evaluation** — and this is the correction that matters, because the obvious
-alternative is broken. Hiding a consumed edge from a lower map entirely freezes that map's triggers at their
-last observed values, and the next edge they *do* see no longer looks like a change. Concretely: an upper map
-binding `Release(k)` and a lower map binding `k`. Every release is consumed above, so the lower map never
-observes `k` going up; its press trigger fires once and is then dead forever. So lower maps keep evaluating,
-and only their dispatch is suppressed.
-
-The honest consequence, since an earlier revision of this document claimed otherwise: a modal-consumed
-keystroke **does** advance a lower map's sequence and **does** run its hold timers. Only the firing is
-withheld. `BlockAll` is what makes a lower map genuinely inert (§8.2), and that is another reason the two
-values are not degrees of the same thing.
-
-Consumption is also **unconditional within a map**. Specificity arbitration — `Ctrl+Z` beating a bare `Z`
-(§4.6) — is a property of the map, not of its occlusion, so it holds in a `Pass` map too. What occlusion
-decides is only whether that consumption is still standing when the next map down is walked.
-
-`BlockMatched` does not affect polled reads. A pause menu using it stops the combat scene's `Escape` while the
-camera keeps panning behind it — which is exactly what §8 wants of it.
-
-### 8.2 `BlockAll` — static, whole-map, dispatch *and* reads
-
-Each linked map carries a computed `suppressed : boolean` — "is there a `BlockAll` map above me". It is
-recomputed when the linked map set, any `order`, or any `occlusion` changes; not per edge.
-
-A suppressed map is **inert**: the walk skips it, so nothing dispatches; `isActive` returns `false`; coordinate
-reads return zero; sequence matchers do not advance and hold timers do not run. On un-suppression every
-sequence matcher is re-entered with `enter(0, held, now)` (§5.1), so it resumes against current reality rather
-than stale state.
-
-This is the fix for the defect revision 2 shipped. There, occlusion was a per-edge `consumed` set gating
-*firing* only, while `isActive` and the coordinate accessors are **polled** — outside any edge walk, with
-nothing connecting them. So the §11 pause menu stopped edge-driven actions while the §11 camera, which is a
-`Script` polling `map.axis2(pan, 'pan')` over WASD every tick, kept panning: precisely the drifting-world bug
-the modal value exists to prevent. Its two occlusion test cases both passed, because both tested dispatched
-actions only.
-
-### 8.3 Consequences worth stating
-
-* **Local co-op needs no fourth value.** `BlockMatched` is per switch, so player 2's pad is untouched by player
-  1's map — they never reference the same switch. `BlockAll` suppresses whole maps and is therefore wrong for
-  split-screen; that is a property of the modal hammer, not a hole in it.
-* **`order` ties are resolved by link order**, oldest first. Deterministic, and mentioned because the format
-  clamps `order` (§10) and ties are therefore reachable.
-* **Lifetime is entity lifetime.** This is already how the game scopes input:
-  `CombatInteractionStateMachine` registers an entity per FSM state and lets `link`/`unlink` turn bindings on
-  and off (`CombatInteractionStateMachine.js:113-160`). Put the `InputMap` on the entity owning the context and
-  entering or leaving the state *is* the binding lifecycle — no `enable()`/`disable()` bookkeeping, no
-  `clearControls` on teardown.
-
----
-
-## 9. The component and the system
-
-### 9.1 `InputMap`
-
-```js
-export class InputMap {
-    static typeName = "InputMap";
-    static serializable = true;
-
-    /** Index 0 is the base. @readonly @type {InputLayer[]} */
-    layers = new List();
-
-    /** Cross-entity arbitration, higher evaluates first. @type {number} */
-    order = 0;
-
-    /** @type {InputOcclusion} */
-    occlusion = InputOcclusion.BlockMatched;
-
-    // ---- authoring -----------------------------------------------------
-    bind(action, ...triggers) { }           // -> InputMap, writes to layer 0
-    bindCoordinate(action, ...channels) { } // -> InputMap, writes to layer 0
-    unbind(action) { }                      // -> InputMap, covers both kinds
-    layer(index) { }                        // -> InputLayer
-    pushLayer() { }                         // -> InputLayer
-    popLayer() { }
-
-    // ---- reading -------------------------------------------------------
-    isActive(action) { }                    // -> boolean
-    coordinate(result, offset, action) { }  // any dimensionality
-    axis1(result, action) { }               // Vector1
-    axis2(result, action) { }               // Vector2
-    axis3(result, action) { }               // Vector3
-
-    equals(other) { }
-    hash() { }
-}
-```
-
-```js
-export class InputLayer {
-    /** @readonly @type {InputBinding[]} */
-    bindings = new List();
-    /** @readonly @type {List<InputCoordinateBinding>} */
-    coordinates = new List();
-
-    bind(action, ...triggers) { }
-    bindCoordinate(action, ...channels) { }
-    unbind(action) { }
-}
-
-export class InputBinding {
-    action = "";
-    /** @readonly @type {InputTrigger[]} */
-    triggers = new List();
-}
-
-export class InputCoordinateBinding {
-    action = "";
-    /** @readonly @type {InputCoordinateChannel[]} */
-    channels = new List();
-}
-```
-
-**Coordinate bindings are a first-class list on the layer, not triggers.** Revision 2 exposed
-`bindCoordinate()` with nowhere to store the result — `InputBinding` holds triggers, and a channel is not a
-trigger — so coordinate bindings existed in the API, in the examples and in the argument for deleting
-`KeyboardCameraController`, but in neither the component nor the wire format.
-
-**Multiple channels on one action resolve by priority: the first channel with any non-zero component wins.**
-Deterministic, allocation-free, and the behaviour consumers already hand-write — `GamepadDevice`'s own
-documented example is "stick wins, else D-pad". It also avoids the alternative's arithmetic nonsense, where
-keyboard `D` plus a stick at 0.3 would sum to 1.3. All channels bound to one action must agree on
-`dimensions`; asserted at authoring time.
-
-The simple case never mentions layers, occlusion or order:
-
-```js
-const map = new InputMap();
-map.bind('jump', InputTriggerKey.from('space'));
-```
-
-### 9.2 `InputMapSystem`
-
-```js
-export class InputMapSystem extends System {
-    dependencies = [InputMap];
-
-    registerDevice(adapter) { }     // may be called after maps are linked; recompiles them (§3.1)
-
-    link(map, entity) { }           // compile (§9.3), subscribe to newly-referenced switches
-    unlink(map, entity) { }         // release; unsubscribe switches no live map references
-    update(dt) { }                  // time only: hold maturity, sequence windows, Delta reset, suppression
-
-    setRecorder(recorder) { }       // §2.5 — DESIGNED, NOT BUILT
-}
-```
-
-Construction takes adapters rather than `engine.devices`, so the system has no dependency on the shape of that
-object and is constructible in a test with nothing behind it:
-
-```js
-new InputMapSystem([
-    new KeyboardInputDeviceAdapter(devices.keyboard),
-    new PointerInputDeviceAdapter(devices.pointer),
-    new GamepadInputDeviceAdapter(devices.gamepad)
-]);
-```
-
-Each interned switch is subscribed once, with a per-switch `SourceBinding {index, system}` passed as the
-`Signal` handler's context (`Signal.js:151`), so the edge path allocates nothing and needs no closure per
-event.
-
-*(As built, the system declares no `components_used`, and does not need to: relative channels LATCH rather
-than clear (§3.3), so every reader in a frame sees the same value regardless of where the system runs in it.
-An earlier revision of this section leaned on execution order instead, which was the weaker guarantee.)*
-
-**Unlinking a map with a sequence mid-match** discards its matcher state along with the compiled program;
-there is nothing to leak and nothing to resume. Unlinking with switches held is likewise clean: `#held` is
-owned by the system, not the map, and the map's triggers are simply gone.
-
-### 9.3 Compilation: the stylesheet / computed-style split
-
-The `InputMap` component is *authored* data — layered, editable. It is not what the edge path reads. On `link`,
-on `registerDevice`, and on any structural change, the system compiles it into an internal `InputMapProgram`:
-
-* cascade resolved — one flat action table per kind, layers already collapsed;
-* switches interned to `Uint32` indices against a system-wide table;
-* per switch, the list of triggers it can affect (`collectSources`), pre-sorted into §4.6 specificity order, so
-  an edge touches only triggers that could possibly care;
-* every trigger's `satisfied` initialised from current state, not from `false` (§4.5);
-* sequence matcher state allocated as three typed-array slots per sequence binding (§5.1).
-
-The edge path then touches integers, typed arrays and `BitSet`s only. No string comparison, no `List`
-traversal, no allocation per event. Recompiles requested during dispatch are queued and applied at the end of
-the current edge (§2.3), so a walk always completes against the program it started with.
-
----
-
-## 10. Serialization
-
-```js
-export class InputMapSerializationAdapter extends BinaryClassSerializationAdapter {
-    klass = InputMap;
-    version = 0;
-
-    serialize(buffer, map) { }
-    deserialize(buffer, map) { }
-}
-```
-
-```
-InputMap
-  int16    order                  see below
-  uint8    occlusion              InputOcclusion
-  uint8    device_count
-  repeat   device_count x utf8    device table - every InputDeviceAdapter#id referenced
-  uint16   layer_count
-  repeat   layer_count x InputLayer          index 0 first; layers carry no name
-
-InputLayer
-  uint16   binding_count
-  repeat   binding_count x InputBinding
-  uint16   coordinate_binding_count
-  repeat   coordinate_binding_count x InputCoordinateBinding
-
-InputBinding
-  utf8     action
-  uint8    trigger_count
-  repeat   trigger_count x InputTrigger
-
-InputCoordinateBinding
-  utf8     action
-  uint8    channel_count
-  repeat   channel_count x InputCoordinateChannel
-
-InputTrigger
-  uint8    type                   InputTriggerType
-    Switch     : InputSource
-    Direction  : InputCoordinateChannel, uint8 direction, float32 threshold, float32 hysteresis
-    Chord      : uint8 child_count, children
-    Sequence   : uint8 child_count, children, float32 step_timeout
-    Hold       : child, float32 duration
-    Release    : child
-
-InputCoordinateChannel
-  uint8    type                   InputCoordinateChannelType
-    Device   : InputCoordinateSource
-    Switches : uint8 count, count x InputTrigger        (2 per dimension: negative, positive)
-    Compose  : uint8 count, count x InputCoordinateChannel
-
-InputSource
-  uint8    device_index           into the map's device table
-  uint16   code
-
-InputCoordinateSource
-  uint8    device_index
-  uint16   code
-  uint8    dimensions
-  uint8    kind                   InputCoordinateKind
-```
-
-Decisions, not incidentals:
-
-* **`order` is `int16`.** Revision 2 wrote it as `uint8 + 128`, range `[-128, 127]` — and its own modal example
-  used `order = 1000`, which clamped to 127 on load and could silently tie with any other high map. `int16`
-  covers the examples and leaves headroom; ties resolve by link order (§8.3).
-* **Coordinate bindings are reachable from the root.** Revision 2 defined an `InputCoordinateChannel` encoding
-  that nothing referenced, so no map containing a coordinate could round-trip.
-* **`Direction` serializes a channel, not a source.** It accepts any `InputCoordinate*` channel (§4.2), so
-  writing only an `InputCoordinateSource` made direction-over-composed-channel constructible and
-  unserializable.
-* **A device table, not a string per source.** A 40-binding keyboard map writes `"keyboard"` once rather than
-  forty times.
-* **Every string here is an identifier.** `writeUTF8String` is ASCII-only in practice and `readUTF8String` is
-  NUL-terminated by design, so this must be stated: action names and device ids are ASCII identifiers, not
-  localized text. A binding UI shows a label looked up *from* the action name; it never serializes the label.
-* **Codes come from enums, three of which are new.** `KeyCodes`, `GamepadButtons` and `GamepadAxes` are already
-  stable on-disk quantities; `MouseButtons`, `PointerCoordinates` and `GamepadCoordinates` are introduced here
-  and are append-only once shipped (§3.1). Revision 2 claimed "no new numbering to keep in sync", which was
-  false the moment it introduced them.
-* **Triggers and channels nest, so serialization recurses.** One `uint8` discriminator each, dispatched by a
-  `switch` — verbose, typed and greppable, over a string-keyed constructor table.
-
----
-
-## 11. End to end
-
-**Gameplay — camera, mixed devices:**
-
-```js
-const map = new InputMap();
-
-map.bindCoordinate('pan',
-    InputCoordinateGamepad.from(GamepadCoordinates.left_stick),   // first non-zero wins
-    InputCoordinateSwitches.from([
-        InputTriggerKey.from('a'), InputTriggerKey.from('d'),
-        InputTriggerKey.from('w'), InputTriggerKey.from('s')
-    ]));
-map.bind('user-input', InputTriggerKey.from('a'), InputTriggerKey.from('d'),
-                       InputTriggerKey.from('w'), InputTriggerKey.from('s'));
-map.bind('focus_selection', InputTriggerKey.from('f'));
-
-new Entity()
-    .add(map)
-    .add(new Script(dt => {
-        map.axis2(pan, 'pan');
-        apply_radial_dead_zone(pan, pan.x, pan.y, 0.15, 0.95);   // policy, at the call site
-        controller.pan(pan, dt);
-    }))
-    .build(ecd);
-```
-
-Both channels feed one action in one call, so the cascade replaces them as a unit; the stick wins while
-deflected and the keys take over when it rests. The `'user-input'` binding is
-`KeyboardCameraController.js:54`'s interaction signal, carried over explicitly rather than lost.
-
-**Editor — `EditorKeyMap` as data:**
-
-```js
-const ctrl = InputTriggerKey.from('ctrl');
-
-const map = new InputMap();
-map.order = 100;
-
-map.bind('undo',      InputTriggerChord.from(ctrl, InputTriggerKey.from('z')));
-map.bind('redo',      InputTriggerChord.from(ctrl, InputTriggerKey.from('y')));
-map.bind('copy',      InputTriggerChord.from(ctrl, InputTriggerKey.from('c')));
-map.bind('paste',     InputTriggerChord.from(ctrl, InputTriggerKey.from('v')));
-map.bind('save',      InputTriggerChord.from(ctrl, InputTriggerKey.from('s')));
-map.bind('duplicate', InputTriggerChord.from(InputTriggerKey.from('shift'), InputTriggerKey.from('d')));
-map.bind('delete',    InputTriggerKey.from('delete'), InputTriggerKey.from('x'));
-
-ecd.addEntityEventListener(entity, 'undo', () => editor.actions.undo());
-```
-
-`Ctrl+Z` beats the bare `Z` binding under §4.6 (modifier-first; see §4.6's stated condition), and the
-`if (event.ctrlKey)` split disappears. The bindings are serializable, so the editor gets a rebinding panel for
-free — the thing that could not exist while they were `if` statements. §14.1 lists the three `EditorKeyMap`
-behaviours that do *not* come across.
-
-**Modal — pause menu:**
-
-```js
-const map = new InputMap();
-map.order = 1000;
-map.occlusion = InputOcclusion.BlockAll;
-map.bind('resume', InputTriggerKey.from('escape'));
-```
-
-Every map below is suppressed: no dispatch, and `isActive`/`axis2` read neutral — so the camera above stops
-rather than drifting behind the dialog (§8.2).
-
-**Cross-device chords:**
-
-```js
-map.bind('precision_place', InputTriggerChord.from(InputTriggerKey.from('ctrl'),
-                                                   InputTriggerMouseButton.from(MouseButtons.left)));
-map.bind('pad_reset',       InputTriggerChord.from(InputTriggerGamepadButton.from(GamepadButtons.back),
-                                                   InputTriggerKey.from('r')));
-```
-
----
-
-## 12. Testing
-
-### 12.1 No mocks, and no DOM
-
-The seam is `InputDeviceSwitch`: a real object with `press()`/`release()`, constructible in node with nothing
-beneath it. A test adapter is a *real* adapter over *real* switches — not a mock. Eager evaluation keeps the
-tests short, because there is no tick to pump for edge-driven behaviour:
-
-```js
-const kb = new TestInputDeviceAdapter('keyboard', KeyCodes);
-const system = new InputMapSystem([kb]);
-// real EntityComponentDataset, real InputMap, real listeners
-
-kb.switch(KeyCodes.ctrl).press();
-kb.switch(KeyCodes.z).press();
-
-expect(observed).toEqual(['undo']);      // no system.update() anywhere
-```
-
-`system.update(dt)` appears only in tests for hold maturity, sequence windows, `Delta` reset and suppression —
-a precise statement of what the tick is for.
-
-*(Revision 2 justified this by claiming `InputSystem` "cannot be exercised without a focusable DOM element".
-That was overstated: focusability is `KeyboardDevice`'s requirement (`KeyboardDevice.js:61-66`), and
-`InputSystem` resolves paths against any object, so a synthetic tree of real Signals would exercise it. The
-real point is narrower and still worth making — nobody has, and `InputBinding.spec.js` asserts only that a
-constructor does not throw.)*
-
-### 12.2 What gets asserted
-
-Observable behaviour only: dispatched action names and order, `isActive` levels, coordinate values. Never which
-triggers were evaluated, never how many times a matcher ran, never internal matcher state.
-
-| | Case | Guards |
-|---|---|---|
-| 1 | An action fires before any `update()` runs | §2 eager evaluation — the requirement, as a test |
-| 2 | Press and release inside one frame both fire; two presses dispatch in press order | §2 |
-| 3 | `Ctrl` then `Z` fires only `undo`; `Z` then `Ctrl` fires both, in that order | §4.6 and its stated condition |
-| 4 | One long press of `A` does not satisfy both steps of `[A, A]` | §5.1 entry snapshot |
-| 5 | `[A,A,B]` fires on `A A A B` | §5.3 |
-| 6 | Holding `A` and tapping `B` twice fires `[A,B]` **once** | §5.3 post-fire re-entry — the revision-2 machine-gun |
-| 7 | A window expiry with the first step's key held does not spuriously advance | §5.1 — the revision-2 stale-snapshot bug |
-| 8 | `Ctrl+Shift+A > B` fires whether or not modifiers are released first | §5.4 |
-| 9 | `↓ ↘ →` over a stick coordinate fires; the same over raw d-pad *buttons* does not | §5.4 — the exclusivity claim, both directions |
-| 10 | Charge (`hold ← 2 s > →`) fires after a 10 s hold; returning to neutral instead expires it | §5.2 window refresh — the revision-2 charge failure |
-| 11 | A sequence window expires only after the previous step stops holding | §5.2 |
-| 12 | `Release(Chord(a,b))` does not fire on the first edge touching `a` | §4.5 `satisfied` initialisation |
-| 13 | A handler that removes its own entity, or rebinds its own map, does not corrupt the walk | §2.3 |
-| 14 | A `BlockAll` map zeroes a lower map's `axis2` and `isActive`, not just its dispatch | §8.2 — the revision-2 drifting camera |
-| 15 | A `BlockMatched` map does **not** stop a lower map's unrelated action or its coordinate reads | §8.1 — the converse |
-| 16 | A lower map's press binding still fires after many edges consumed above it | §8.1 — the stale-edge trap |
-| 17 | Un-suppressing a map re-enters its sequences at 0 rather than resuming stale state | §8.2 |
-| 18 | The top layer's `jump` replaces the base layer's `jump`; two triggers in one layer both fire | §7 |
-| 19 | A coordinate action bound to stick + keys reads the stick while deflected, the keys at rest | §9.1 priority |
-| 20 | A gamepad binding with no pad connected links and never fires; so does an unregistered device id | §3.1 totality |
-| 21 | `registerDevice` after link makes previously inert bindings live | §3.1, §9.3 |
-| 22 | Two wheel events in one frame sum for tick-time readers | §3.3 `Delta` |
-| 23 | A 3-D wheel coordinate round-trips all three components | §3.3 dimensionality |
-| 24 | Serialize, deserialize, replay a recorded trace, get the same dispatches | §10, §2.5 |
-
-Cases 6, 7, 10 and 14 are regressions against defects revision 2 actually contained; write them first. Case 9
-is the only claim in §5.4 that could be wrong in a way the others would not catch.
-
----
-
-## 13. The trigger DSL — planned, deferred, optional
-
-**Not implemented in this design.** Specified here so the trigger classes are shaped to accept it, and so it
-is not invented ad hoc later.
-
-### 13.1 What it is
-
-A text syntax compiling to the same `InputTrigger` objects §4 defines. It is **an additional entry point,
-never a required one**: an author can compose triggers by hand or write them as text, and the runtime cannot
-tell the results apart.
-
-```js
-import { InputTriggerDSL } from "./dsl/InputTriggerDSL.js";
-
-map.bind('promote', InputTriggerDSL.compile("keyboard:ctrl + keyboard:shift + keyboard:a > keyboard:b"));
-```
-
-### 13.2 Grammar
-
-```ebnf
-trigger    = sequence ;
-sequence   = chord , { ">" , chord } , [ "within" , NUMBER ] ;
-chord      = unary , { "+" , unary } ;
-unary      = [ "!" ] , primary ;
-primary    = atom | "(" , trigger , ")" | call ;
-call       = IDENT , "(" , [ trigger , { "," , trigger | NUMBER } ] , ")" ;
-atom       = DEVICE , ":" , BINDPOINT , [ "." , SUBPOINT ] ;
-DEVICE     = IDENT ;
-BINDPOINT  = IDENT | NUMBER ;
-SUBPOINT   = IDENT ;
-```
-
-| Form | Means | Compiles to |
-|---|---|---|
-| `keyboard:space` | a key | `InputTriggerKey` |
-| `pointer:left` | a mouse button | `InputTriggerMouseButton` |
-| `gamepad:a` | a pad button | `InputTriggerGamepadButton` |
-| `gamepad:left_stick.down` | a direction on a coordinate | `InputTriggerDirection` |
-| `a + b` | chord | `InputTriggerChord` |
-| `a > b` | sequence | `InputTriggerSequence` |
-| `!a` | release / negation | `InputTriggerRelease` |
-| `hold(a, 0.5)` | held for 0.5 s | `InputTriggerHold` |
-| `(...)` | grouping | — |
-| `... within 0.2` | step timeout | `withStepTimeout` |
-
-**Precedence, tightest first:** `!` → `+` → `>` → `within`, so
-`keyboard:ctrl + keyboard:shift + keyboard:a > keyboard:b` parses as intended with no parentheses.
-
-**Keyword collision** is resolved by the `:` — an identifier followed by `:` is a device name, so a device may
-be called `hold` without ambiguity. Worth stating because it is where small DSLs usually break.
-
-The §5.4 motion, written out:
-
-```
-gamepad:left_stick.down > gamepad:left_stick.down_right > gamepad:left_stick.right + gamepad:x within 0.2
-```
-
-### 13.3 Why it stays separate
-
-* **`ism/dsl/` is its own module**, imported by nothing in the runtime. A game that composes triggers by hand
-  never pays for a parser — it is not in the bundle.
-* **It is a compiler, not a representation.** Serialization stays binary (§10), so a DSL change can never
-  invalidate saved bindings.
-* **`InputTriggerDSL.stringify(trigger)` is the inverse**, which is what a rebinding UI wants: it shows a
-  binding in the syntax an author would type, with no second formatting path.
-
-### 13.4 Deferred until
-
-Everything in §14 phases 1–8 has landed and at least one consumer has migrated. The DSL is a convenience over a
-working system; building it first would freeze the trigger vocabulary before the vocabulary has been used.
-
----
-
-## 14. Migration
-
-The ISM lands beside the existing systems. Both keep working; neither is touched until its consumers move.
-**`InputController` and `InputControllerSystem` survive this program** — they still own every gesture binding
-(§1.1).
-
-*This table is the plan of work, not a progress report. For where each phase actually stands, read the status
-section of [`ISM_IMPLEMENTATION_PLAN.md`](ISM_IMPLEMENTATION_PLAN.md), which is kept current as phases land.*
-
-| Phase | Work | Gate |
-|---|---|---|
-| **1** | `InputSource`, `InputCoordinateSource`, the `InputTrigger*` classes, `InputMap` / `InputLayer` / `InputBinding` / `InputCoordinateBinding` | Value-object specs: `equals` / `hash` / round-trip |
-| **2** | `InputDeviceAdapter` and the three adapters; the `MouseButtons`, `PointerCoordinates`, `GamepadCoordinates` enums | Totality: every declared code resolves with no hardware, and with no adapter (§12.2 cases 20–21) |
-| **3** | `InputMapSystem`: eager edge path, `#held`, compile, switch/chord/release, cascade, `BlockMatched`, ECS dispatch, `isActive` | cases 1–3, 12, 13, 15, 18 |
-| **4** | `InputTriggerSequence` + `InputTriggerHold`; synthetic maturity edges; window refresh and expiry | cases 4–8, 10, 11, 16 |
-| **5** | Coordinates: channels, priority resolution, the `Delta` latch, read accessors | cases 19, 22, 23; retires `KeyboardCameraController` |
-| **6** | `InputTriggerDirection` over coordinates, with threshold and hysteresis | case 9 |
-| **7** | `BlockAll` suppression across dispatch and reads; un-suppression re-entry | cases 14, 17 |
-| **8** | `InputMapSerializationAdapter` + `InputRecorder` | case 24 |
-| **9** | Migrate consumers (below) | existing specs stay green |
-| **10** | `ism/dsl/` — the §13 compiler and `stringify` | round-trip: `compile(stringify(t))` equals `t` |
-
-### 14.1 Consumers
-
-1. **`EditorKeyMap`** — **blocked, not retired.** The engine's `KeyboardDevice` is mounted on
-   `viewStack.el` (`Engine.js:367`) and `Editor.js:563` pushes the entire editor GUI into that same stack, so
-   an editor map would see keys typed into panel text fields — `x` would delete the selected entities, and
-   `preventDefault` would swallow the keystroke. The ISM has no DOM awareness to express the old gate (§6.3),
-   so retiring this needs a design addition. See the implementation plan §5.1. Four behaviours would have to be
-   re-provided in any case, because none of them is in the ISM:
-   * **Focus gating.** `isViewFocused` (`EditorKeyMap.js:12-31`) suppresses all editor bindings when focus is
-     outside the game view. In the ISM this depends on which element the editor's `KeyboardDevice` is mounted
-     on. With bare-key bindings like `x` = delete, getting it wrong is destructive — verify before landing.
-   * **Autorepeat.** Holding `Ctrl+Z` currently repeat-undoes; it will not (§5.5). Decide per action whether
-     that is a loss or a fix.
-   * **`stopPropagation()`** on handled chords — currently prevents the event reaching other listeners.
-   * **The unconditional forward to the active tool** (`EditorKeyMap.js:175-180`), which `Tool.handleKeyboardEvent`
-     relies on: each tool gets its own `InputMap` on its activation entity, at a higher `order`.
-2. **`KeyboardCameraController`** — retired by §3.3, not ported. Carry the `'user-input'` event (§11).
-3. **`Input` / `InputSystem`** — **done.** All five consumers moved and both are `@deprecated`.
-   `OverlayPageGUI` (escape), `CombatInteractionController` (p, escape) and two harnesses were straight
-   translations. `StoryManager` was a split: it bound both a tap and the space bar to one action, and only
-   the space bar moved. A tap is not a button press (§1.1) — translating it would change advance-on-release
-   to advance-on-press and fire at the start of every drag — so the tap kept a small `InputController`, which
-   is the decision the earlier revision of this section left open.
-4. **`InputController` keyboard bindings** — **not started.** The keyboard subset moves; `priority` becomes
-   `order`, `exclusive` becomes `InputOcclusion.BlockMatched`. Gesture bindings stay put, which for
-   `StrategyInteractionController` means most of the file. This is where escape arbitration finally bites
-   (plan §5.4) and where `KeyboardCameraController`'s `'user-input'` entity subtlety has to be handled.
-5. **`components/InputBinding.js`** (`{path, listener, …}`) is orphaned only when `InputController` finally
-   goes, which is not in this program.
-
-### 14.2 A naming collision to plan around
-
-*(Resolved: the new record lives at `ism/map/InputBinding.js`, so the two never shared a filename and the old
-one kept its path and its importer. What follows is the problem as it stood.)*
-
-Phase 1 introduces `InputBinding` in `ism/`, and `ism/InputBinding.js` already exists as the old
-`{path, event}` record imported by [`Input.js:3`](../components/Input.js). The old file must survive until
-`Input` is retired (phase 9), so the two cannot share a filename. Land the new one as `ism/InputBinding.js`
-only after the old is deleted; until then it lives beside its siblings under a transitional name, or `Input`
-is repointed at a copy under `components/`.
-
----
-
-## 15. Explicitly not doing
-
-* **Pointer gestures** — tap, drag, move, wheel-as-gesture, pinch. §1.1, with the binding counts. Revision 2
-  claimed "nothing in the codebase binds pinch today"; that was false —
-  `StrategyInteractionController.js:437,447` binds `pinchStart` and `pinch`, and it is also the largest
-  migration target.
-* **Buffering input to a frame boundary.** §2. Revision 1 did, and it bought nothing eager evaluation does not
-  also provide.
-* **Discriminating tap from hold on one switch.** §5.5 — it requires withholding the short action, which is the
-  buffering above. Accepted as a cost.
-* **Key autorepeat.** §5.5 — not observable through `InputDeviceSwitch` at all.
-* **Keeping string paths.** `resolvePath` throws where it should resolve and cannot express two sources at once;
-  `GAMEPAD_API_PROPOSAL.md §5` says not to grow it.
-* **A trigger class per gesture pattern.** Double-tap is a two-step sequence with a short window; long-press is
-  `InputTriggerHold`.
-* **Dead zones, sensitivity or response curves on analog output.** §3.3. The direction threshold and hysteresis
-  in §3.4 are not exceptions: producing a boolean from a coordinate cannot be done without them.
-* **A `Started` / `Performed` / `Canceled` phase enum, or an `edge` field.** §4.1 — every trigger is a
-  predicate and every binding fires on its rising edge.
-* **A per-binding `consume` flag.** Occlusion is a property of a *context*, not of one binding, and a boolean
-  per binding makes behaviour depend on declaration order.
-* **Named layers.** §7 — a stack is addressed by index.
-* **Behaviour in the component.** No function references, no script names, no serialized handler ids (§6.1).
-* **DOM-target awareness in `InputActionEvent`.** §6.3 — it belongs with the deferred gesture work.
-* **Strict sequence rejection**, and **button buffering**. §5.5, both deferred with known shapes.
-* **A generic input node graph.** The trigger classes are already a small algebra; the DSL (§13) is the cheaper
-  first step over it.
-
----
-
-## 16. Resolved decisions
-
-1. **Analog channels are N-dimensional "coordinates", not axes** — §3.3. `WheelEvent` has three components and
-   `PointerDevice` surfaces all three. `kind` (`Absolute` / `Delta` / `Normalized`) carries the verb.
-2. **`order` stays author-set** — §8. A GUI-hierarchy-derived order would need no hand-picked numbers but would
-   couple input arbitration to that hierarchy.
-3. **No sensitivity in bindings** — §3.3. A rebinding UI serializes *which* channel drives an action, never how
-   twitchy it is.
-4. **Layers are an index-addressed stack, with no names** — §7.
-5. **Evaluation is eager, on the edge** — §2. No buffer, no added frame. The costs — re-entrant dispatch,
-   arrival-ordering, the §4.6 chord condition, the §5.5 tap-versus-hold limit, and the §3.3 `Delta` split
-   between eager and tick-time readers — are stated where they arise rather than hidden.
-6. **The trigger DSL is planned, specified and deferred** — §13, phase 10.
-7. **Pointer gestures are out of scope** — §1.1. `InputController` is reduced, not retired.
-8. **`SimpleStateMachine` is not used** — §5.6. The matcher is a path, not a graph; the class becomes the right
-   tool if sequences ever branch.
-
----
-
-## 17. What changed in revision 3, and why
-
-An adversarial review of revision 2 found three defects that made it unimplementable, plus a set of false
-claims about the existing codebase. Everything below was verified against source before being changed.
-
-### Defects
-
-| | Was | Now |
-|---|---|---|
-| **Sequence matcher** | Reset paths (window expiry, post-fire) did not re-establish the entry snapshot, and the advance step indexed `steps[N]`. Holding `A` and mashing `B` machine-gunned `[A,B]` off one `A` press; an expiry with the first key held spuriously advanced with no edge. | Every entry routes through `enter(k, held, now)` (§5.1), which snapshots and never indexes `steps[N]`. Cases 6 and 7. |
-| **Occlusion** | A per-edge `consumed` set gating *firing* only. `isActive` and coordinate reads are polled, so `BlockAll` could not stop them — a pause menu left the camera panning, the exact bug §8 claimed to prevent. Both occlusion tests passed anyway, testing only dispatch. | Two scopes: `BlockMatched` stays dynamic and dispatch-only; `BlockAll` sets a static per-map `suppressed` covering dispatch *and* reads (§8.2). Cases 14, 15, 17. |
-| **Coordinate bindings** | `bindCoordinate()` existed with nowhere to store its result, and §10's channel encoding was unreachable from the format root. No map with a coordinate could serialize. `bindCoordinate` was also called twice for one action in §11 with no defined meaning. | `InputCoordinateBinding` on the layer, reachable in the format, with priority resolution (§9.1). Case 19. |
-
-### Corrections
-
-* **Charge inputs failed.** The step window ran from the advance, so any charge longer than
-  `duration + step_timeout` expired before the flick. It now measures time since the previous step *stopped*
-  holding (§5.2). Case 10.
-* **`satisfied` initialisation was unspecified**, and zero-init makes `Release(Chord(a,b))` fire before the
-  chord exists. Now snapshotted at compile (§4.5). Case 12.
-* **`order` was `uint8`-biased**, range `[-128,127]`, while §11's own modal used `1000`. Now `int16` (§10).
-* **`MouseButtons` cited the wrong standard.** The `MouseEvent.buttons` *bitmask* order is left/right/middle;
-  `PointerDevice.buttons[]` is indexed by `MouseEvent.button` *ordinal*. Following the citation would have
-  fired every right-click binding on the middle button, into saved data (§3.1).
-* **`Release(sequence)` was claimed to mean "stopped matching".** It cannot — a sequence's `test` is a pulse
-  (§4.3).
-* **Specificity did not rank `Hold` / `Release` / `Direction`**, so they fell through to declaration order —
-  the accident §4.6 claims to eliminate (§4.6).
-* **Chord-vs-subset arbitration was stated unconditionally.** It holds only when the modifier arrives first
-  (§4.6). Case 3 now tests both orders.
-* **The `Delta` "same value for every reader" invariant** was a leftover from the buffered design and is false
-  under eager dispatch (§3.3).
-* **Re-entrancy covered only structural change.** Nested edges and mid-dispatch binding edits are now specified
-  (§2.3).
-* **The recorder captured only switch edges**, so no map with a coordinate or a hold could replay. It now
-  records coordinate samples and per-frame `dt` (§2.5).
-* **Unregistered devices had no defined behaviour** (§3.1).
-* **`EditorKeyMap` and `KeyboardCameraController` deletions dropped real behaviour** — focus gating,
-  autorepeat, `stopPropagation`, the tool forward, the `'user-input'` event — now inventoried (§14.1).
-* **Counts and claims:** `KeyboardCameraController` has 16 `bind()` calls, not eight; the `InputController`
-  path-string count flattered a migration that is mostly gestures (§1.1); `InputControllerSystem`'s `deferred`
-  array is dead code, not a working mitigation (§2.3); "`InputSystem` cannot be tested without a DOM element"
-  was overstated (§12.1); "no new numbering to keep in sync" was false (§10); `PointerDevice`'s wheel reports
-  `sign()`, so a `Delta` wheel channel counts ticks rather than distance (§3.3).
+# Input System Mapping — design
+
+A binding layer for keyboard, pointer buttons and gamepad, replacing `Input`/`InputSystem`, the keyboard half
+of `InputController`/`InputControllerSystem`, `EditorKeyMap` and `Tool.handleKeyboardEvent`.
+
+Status: **design, not yet implemented.** The only file in this directory today is
+[`InputBinding.js`](InputBinding.js) (the `{path, event}` record used by
+[`Input`](../components/Input.js)); it is superseded by §4.
+
+> **Revision 3.** Rewritten after an adversarial review of revision 2 found three defects that made it
+> unimplementable, and several false claims about the existing codebase. What changed, and why, is in §17.
+> The three that matter: the sequence matcher's reset paths were broken (§5); occlusion could not reach polled
+> reads, so a modal dialog could not stop a camera (§8); and coordinate bindings had no home in either the
+> component or the wire format (§9.1, §10). Two scope decisions were taken at the same time: **pointer
+> gestures are out of scope** (§1.1), and **`SimpleStateMachine` is not used** (§5.6).
+
+---
+
+## 0. Summary
+
+Two decisions carry the design.
+
+> **1. Every input this system binds is either a switch or a coordinate.** `InputDeviceSwitch` already exists
+> and is already what keyboard keys, pointer buttons and gamepad buttons *are*. A coordinate is an
+> N-dimensional analog channel — stick deflection, wheel ticks, pointer position.
+>
+> **2. Every trigger is a predicate over (held switches + its own state), and a binding fires on that
+> predicate's rising edge** — evaluated the instant an edge arrives, never on a frame boundary.
+
+| Requirement | Falls out of |
+|---|---|
+| Combinations (chords) | A chord is the AND of its children's predicates |
+| Sequences | A sequence is a predicate over a small linear matcher, advanced per edge (§5) |
+| Cross-device combos | A chord cannot tell which device a child came from — there is nothing to make work |
+| Arbitrary devices | A device is anything that hands out switches and coordinates (§3) |
+| Layers, top wins | Cascade over an action table, compiled once per change, like CSS (§7) |
+| Serializable bindings | A binding is `(trigger, action name)`; both halves are plain data (§6.1, §10) |
+| No added latency | Evaluation is eager on the edge; the tick services only time (§2) |
+
+Two defects in the current systems that this fixes on the way past:
+
+1. **Binding resolution can throw.** `resolvePath` throws on an unresolvable path
+   ([`resolvePathByArray.js:47`](../../../../core/json/resolvePathByArray.js)), which is why a gamepad binding
+   is a load-order landmine (see [`GAMEPAD_API_PROPOSAL.md §3`](../../GAMEPAD_API_PROPOSAL.md)). Source
+   resolution here is total.
+2. **Nothing can express a combination.** `Ctrl+Z` is not expressible as a path, which is why
+   [`EditorKeyMap`](../../../../../editor/EditorKeyMap.js) exists as a parallel, unserializable, unrebindable
+   input system made of `if (event.ctrlKey)`.
+
+---
+
+## 1. Scope
+
+### 1.1 Pointer gestures are out of scope
+
+`PointerDevice` synthesizes gestures on top of its buttons — `tap`, `drag`, `dragStart`, `dragEnd`, `move`,
+`wheel`, `pinch`, `pinchStart`, `pinchEnd` — and those are **not** modelled here. They are stateful
+constructions with their own parameters (`tap` fires on *release*, gated on ≤ 10 px of travel and ≤ 1 s;
+`PointerDevice.js:20-40`), not switches, and folding them into the trigger algebra is a separate piece of work.
+
+This is a deliberate limit with a measurable cost. Of the pointer bindings in shipping consumers:
+
+| `down`/`up` | `tap` | `drag`/`dragStart`/`dragEnd` | `move` | `wheel` | `pinch`/`pinchStart` |
+|---|---|---|---|---|---|
+| 6 | 4 | 4 | 2 | 2 | 2 |
+
+Only the first column is expressible. **Consumers bound to gestures stay on `InputController`**, which is
+therefore *reduced*, not retired, by this program (§14). Chief among them:
+`StrategyInteractionController` (17 bindings, including both pinch bindings),
+`makeOrbitalCameraController` (tap + down + drag + wheel), and `RadialContextMenu`.
+
+### 1.2 What is replaced
+
+| Mechanism | Disposition | Why |
+|---|---|---|
+| [`Input`](../components/Input.js) + [`InputSystem`](../systems/InputSystem.js) | **Retired** (one holdout, §14) | Magic string paths; one source per binding; no combinations; `resolvePath` throws; `serializable = false` |
+| [`EditorKeyMap`](../../../../../editor/EditorKeyMap.js) | **Retired** | Exists only because chords are inexpressible above; hard-coded, unrebindable, undiscoverable |
+| `Tool.handleKeyboardEvent` | **Retired** | An unconditional forward to the active tool, with no gating |
+| [`KeyboardCameraController`](../controllers/KeyboardCameraController.js) | **Retired** | 16 `bind()` calls maintaining a `controls` struct — a 2-D coordinate written by hand (§3.3) |
+| [`InputController`](../components/InputController.js) + [`InputControllerSystem`](../systems/InputControllerSystem.js) | **Reduced** | Keyboard and button bindings move; gesture bindings stay (§1.1) |
+| Direct `engine.devices.*.on.*.add(...)` in gameplay code | **Case by case** | Not bindable, not rebindable, not occludable; but gesture subscriptions have nowhere to go yet |
+
+**Not in scope at all:** direct device reads in `prototype*.js` / `test*.js` harnesses. Those are internal
+tools, and polling `pad.buttons[GamepadButtons.a].is_down` remains the blessed path for anything that does not
+want a binding layer. The ISM sits *above* the devices; it does not close them off.
+
+---
+
+## 2. Evaluation: eager on edges, ticked only for time
+
+There is **no input buffer and no added frame of latency.** An edge is evaluated and dispatched inside the
+device signal that produced it.
+
+```
+ InputDeviceSwitch.down / .up            (keyboard/pointer: DOM event. gamepad: poll.)
+            |
+            v
+ ISM edge handler  --- synchronous, no queue ---------------------------------
+            |
+            |  1.  stamp arrival time
+            |  2.  update #held : BitSet
+            |  3.  append to the recorder, if one is attached          (§2.4)
+            |  4.  walk maps by `order` descending, skipping suppressed maps (§8):
+            |          for each candidate trigger touching this switch,
+            |          in specificity order (§4.6):
+            |              was := trigger.satisfied
+            |              now := trigger.test(#held)
+            |              trigger.satisfied := now
+            |              if (now && !was)  consume, dispatch
+            |  5.  apply changes deferred during dispatch              (§2.3)
+            v
+ dataset.sendEvent(entity, action, event)   -- consumer runs here, this instant
+```
+
+`#held` is exact at dispatch time by construction, because dispatch *is* the edge. No replay, no
+reconstruction.
+
+### 2.1 The tick services time, and only time
+
+`System.update(dt)` dispatches no edge-driven action. It services the four things that change without an edge:
+
+1. **`InputTriggerHold` maturity.** A hold for 0.5 s becomes true 0.5 s after its child did, which no edge
+   announces. When it matures it emits a **synthetic edge** into the same walk as step 4 above, carrying the
+   hold's own `collectSources()` set so consumption (§8) has something to match against. Latency is bounded by
+   the frame, which is inherent: nothing observes time more finely than the loop observing time.
+2. **Sequence step windows** (§5.2) — both the refresh while a previous step still holds, and the expiry.
+3. **`Delta` coordinate reset** (§3.3).
+4. **Suppression recompute** when the linked map set, `order` or `occlusion` changed during the frame (§8).
+
+A trigger built only from switches and chords is untouched by `update`.
+
+### 2.2 Polled devices are bounded by their own poll rate
+
+`GamepadDevice` polls once per animation frame and drives its switches from the result
+(`GamepadDevice.js:370-407`), so gamepad edges cannot be finer-grained than that — a Gamepad API property, not
+one this design imposes. `GamepadDevice.poll()` is callable manually, so a consumer driving a fixed-rate loop
+can raise its own resolution. Keyboard and pointer edges are DOM-driven and carry no such floor.
+
+### 2.3 The re-entrancy contract
+
+Consumer code runs inside a DOM event handler. Four cases, each with a stated rule:
+
+* **Structural change** — a handler adds or removes an entity, and therefore an `InputMap`. Queued, applied at
+  step 5, after the current edge finishes.
+* **Binding edits on a linked map** — a handler calls `bind()` / `pushLayer()`, which §9.3 says triggers a
+  recompile. The recompile is queued with structural changes and applied at step 5; the walk always runs to
+  completion against the program it started with. This path is not exotic: it is the rebinding-capture flow.
+* **Nested edges** — a handler calls `GamepadDevice.poll()` (blessed in §2.2) or synchronously dispatches a DOM
+  event (`element.click()`, `.focus()`), re-entering the walk. **Rejected**: a re-entrant edge is queued and
+  replayed at step 5 rather than processed inline, because processing it inline would mutate `#held` under the
+  outer walk and clobber the shared `InputActionEvent` (§6.3) before the outer handler finished reading it.
+* **A handler that throws** — it throws. `#held` and the recorder are updated *before* dispatch (steps 2–3), so
+  ISM state stays consistent and the failure is visible, per the codebase's position on not swallowing errors.
+
+*(For contrast, `InputControllerSystem` carries a `deferred` array for the first case that **nothing ever
+populates** — `add()` registers directly under a `//TODO handle case where binding is added mid-dispatch`
+(`InputControllerSystem.js:119-121`). The hazard is real and currently unhandled, not handled badly.)*
+
+### 2.4 Ordering, and what it costs
+
+Action effects land wherever in the frame the edge arrived, so two actions in one frame are ordered by
+arrival, not by system order. That is the direct consequence of wanting zero latency, and §4.6 and §5.5 record
+the two places it is observable.
+
+### 2.5 Recording and replay
+
+An optional recorder captures, per frame: the frame's `dt`, every switch edge as
+`(source_index, is_down, time)`, and a sample of every **coordinate channel** any linked map references.
+Coordinates must be recorded because they are read by polling, not driven by edges — without them,
+`InputActionEvent.value` and every `axis*` read diverge on replay. `dt` must be recorded because hold maturity
+and window expiry are evaluated on the tick, so a different frame cadence produces different fire times.
+
+Replay injects recorded edges at their recorded positions within each recorded frame and drives the same eager
+path. Interned `source_index` values are stable only within one link generation, so the recorder writes the
+source table alongside and remaps on load.
+
+The recorder is an observer, not the mechanism — attach it for a determinism run or a bug report, leave it off
+otherwise.
+
+### 2.6 `preventDefault`, and its granularity
+
+[`KeyboardDevice`](../../devices/KeyboardDevice.js) calls `event.preventDefault()` when the pressed key's
+`down` signal *has handlers* (`KeyboardDevice.js:112-118`). Since the ISM subscribes to precisely the keys some
+live binding references, browser-default suppression tracks the bound key set automatically.
+
+**Granularity is per key, not per chord**, and this is worth knowing before it surprises someone: binding only
+`Ctrl+S` subscribes `s`'s `down` signal, so a *bare* `S` keydown is also `preventDefault`ed anywhere the device
+element sees it. This is inherited behaviour, not new — `InputController` binding `keyboard/keys/s/down` does
+the same — but chords make it newly reachable. Changing it means changing `KeyboardDevice`, which is out of
+scope here.
+
+---
+
+## 3. Devices, switches and coordinates
+
+### 3.1 The adapter
+
+```js
+/**
+ * Adapts a concrete input device to the ISM.
+ *
+ * Resolution must be TOTAL: an adapter answers for every code it declares, whether or not hardware is
+ * present. Absent hardware reads as "up" and as zero, never as undefined, and never throws. This is the
+ * property `resolvePath` lacked.
+ */
+export class InputDeviceAdapter {
+    /** Stable identifier, written into serialized bindings. ASCII, lower_snake_case. @type {string} */
+    id = "";
+
+    /** @param {number} code @returns {InputDeviceSwitch} */
+    getSwitch(code) { }
+
+    /** @param {number[]|Float64Array} result @param {number} offset @param {number} code */
+    readCoordinate(result, offset, code) { }
+
+    /** Begin/stop observing the device. Adapters with nothing to subscribe to leave these alone. */
+    startup() { }
+    shutdown() { }
+
+    /** Publish this frame's relative-channel totals and start a new window. See the latch rule in §3.3. */
+    latchDeltas() { }
+}
+```
+
+A channel's *dimensionality* is not asked of the adapter. It is a static property of the channel code, known
+to the typed constructors (§3.3), so a binding on an unregistered device still knows its own shape.
+
+| Adapter | `id` | Switch codes | Coordinate codes |
+|---|---|---|---|
+| `KeyboardInputDeviceAdapter` | `"keyboard"` | [`KeyCodes`](../../devices/KeyCodes.js) | — |
+| `PointerInputDeviceAdapter` | `"pointer"` | `MouseButtons` | `PointerCoordinates` |
+| `GamepadInputDeviceAdapter` | `"gamepad"` | [`GamepadButtons`](../../devices/gamepad/GamepadButtons.js) | `GamepadCoordinates` |
+
+Three enums are new, and each needs a stability note because their values become `uint16` codes on disk:
+
+* **`MouseButtons`** — `left: 0, middle: 1, right: 2, back: 3, forward: 4`. These are
+  **`MouseEvent.button` ordinals**, matching how `PointerDevice.buttons[]` is indexed
+  (`PointerDevice.js:300-318`: `mouseButtonLeft` is `[0]`, `mouseButtonMiddle` is `[1]`, `mouseButtonRight` is
+  `[2]`). They are deliberately **not** the `MouseEvent.buttons` *bitmask* order, which is left/right/middle —
+  taking that order would index `buttons[1]` for a right-click and fire every right-click binding on the
+  middle button, into saved data.
+* **`PointerCoordinates`** — `position`, `move`, `wheel`.
+* **`GamepadCoordinates`** — `left_stick`, `right_stick`, `dpad`.
+
+Values are append-only once shipped, like `KeyCodes` and `GamepadButtons` before them.
+
+A fourth device — MIDI pedal, wheel, eye tracker, a network-driven replay source — is an adapter and a
+registration call. Nothing in the trigger, layer, cascade or serialization layers changes, because none of them
+can tell devices apart.
+
+The gamepad adapter binds `GamepadDevice.main`, the persistent handle: it exists before any hardware does,
+survives disconnection, and rebinds to the oldest connected pad on a swap (`GamepadDevice.js:110, 306-344`). A
+serialized gamepad binding therefore resolves at load time and keeps working across a hot-swap — the defect
+`GAMEPAD_API_PROPOSAL.md §3` identified and could not fix from the device side alone.
+
+**A device that is not registered** is not an error. A map naming an unregistered `id` links successfully and
+its bindings on that device are inert — the same contract as connected-but-absent hardware, so a saved map
+never fails to load because a peripheral is missing. `registerDevice()` may be called after maps are linked; it
+recompiles every linked map (§9.3), at which point those bindings become live.
+
+### 3.2 Switch sources
+
+```js
+export class InputSource {
+    device = "";                    // InputDeviceAdapter#id
+    code = 0;
+}
+```
+
+One flat value type with `equals`/`hash`/`toBinaryBuffer`/`fromBinaryBuffer`, deliberately *not* a
+`KeySource`/`GamepadButtonSource`/… hierarchy: a chord over `{keyboard:ctrl, pointer:0}` needs no polymorphic
+dispatch, serialization is `(device_index: Uint8, code: Uint16)` against a per-map device table (§10) with no
+type tags, and interning to an integer (§9.3) is a two-field hash after which the hot path never touches the
+object again. The typing that matters to an author lives on the *trigger* constructors (§4.2).
+
+### 3.3 Coordinates — analog channels of arbitrary dimensionality
+
+An analog channel is not a scalar axis. `WheelEvent` carries `deltaX`, `deltaY` and `deltaZ`, and
+[`PointerDevice`](../../devices/PointerDevice.js) surfaces all three (`PointerDevice.js:398-404`). A 1-D axis
+abstraction would have to either drop `deltaZ` or invent three channels for one control.
+
+*(Precisely: `PointerDevice` reports `sign(event.deltaX/Y/Z)`, so components are -1, 0 or 1 and scroll
+magnitude is discarded at the device. A `Delta` wheel channel therefore accumulates **tick counts**, not
+distance. That is the device's existing behaviour; the ISM reports what it is given.)*
+
+```js
+export class InputCoordinateSource {
+    device = "";
+    code = 0;
+    /** Component count. 2 for a stick or pointer position, 3 for a wheel. @type {number} */
+    dimensions = 1;
+    /** @type {InputCoordinateKind} */
+    kind = InputCoordinateKind.Normalized;
+}
+
+export const InputCoordinateKind = {
+    /** A position in some space. Read at any time, no accumulation. Pointer position. */
+    Absolute: 0,
+    /** A change. Accumulates within a frame, zeroed at the frame boundary. Wheel. */
+    Delta: 1,
+    /** Deflection, each component in [-1, 1]. Stick, d-pad. */
+    Normalized: 2
+};
+```
+
+`kind` is the verb — what the numbers *mean*. `Delta` is the one with behaviour attached, and it is why the
+tick exists at all: two wheel events in one frame must sum.
+
+**The `Delta` visibility rule, stated exactly.** A relative channel **latches**; it is not cleared. The
+adapter accumulates arriving events into one buffer, and once per frame `update` publishes that buffer into a
+second one and starts a fresh accumulation window. Readers see the published value.
+
+Latching rather than clearing is load-bearing, and the obvious alternative is wrong. Device events arrive
+*between* frames, so an adapter that zeroed its accumulator at the top of a frame would destroy exactly the
+events that frame exists to report. Latching also makes the value **independent of system execution order**:
+every reader in a frame sees the same number whether it runs before or after the ISM, which is what the
+"same value for every reader" guarantee actually requires.
+
+An **eager handler** reading a `Delta` channel mid-frame sees the value published for the frame in progress —
+the same one the tick-time readers will see — not a running total of events that have arrived since. Those
+belong to the next frame.
+
+**Reading.** The general accessor writes into an indexable numeric buffer; common dimensionalities get typed
+conveniences over the engine's vector types:
+
+```js
+map.coordinate(result, offset, 'look');   // Float64Array | number[] - any dimensionality
+map.axis1(v1, 'throttle');                // Vector1
+map.axis2(v2, 'move');                    // Vector2
+map.axis3(v3, 'wheel');                   // Vector3
+```
+
+Result-first argument order follows the engine's `f(result, ...)` convention.
+
+**Channels.** A coordinate action is driven by a channel, and the consumer cannot tell which kind:
+
+```js
+InputCoordinateGamepad.from(GamepadCoordinates.left_stick)   // hardware channel
+InputCoordinatePointer.from(PointerCoordinates.wheel)        // hardware channel, 3-D
+InputCoordinateSwitches.from([                               // N-D from 2N switch triggers
+    InputTriggerKey.from('a'), InputTriggerKey.from('d'),    //   x: negative, positive
+    InputTriggerKey.from('w'), InputTriggerKey.from('s')     //   y: negative, positive
+])
+InputCoordinateCompose.from(x_channel, y_channel)            // stitch channels
+```
+
+`InputCoordinateSwitches` is [`KeyboardCameraController`](../controllers/KeyboardCameraController.js) as data,
+and it generalises past 2-D for free.
+
+**Shaping stays at the call site.** No dead zone, no response curve, no sensitivity inside the ISM. It returns
+the composed raw value and the consumer calls
+[`apply_radial_dead_zone`](../../analog/apply_radial_dead_zone.js). This is the position
+`GAMEPAD_API_PROPOSAL.md §1.2` argues at length; reversing it here would put the same policy back in the same
+wrong layer, one floor up.
+
+### 3.4 Derived switches: a direction is a coordinate with a threshold
+
+`InputTriggerDirection` turns a coordinate into a switch — "the stick is in the *down-right* octant". This is
+what makes motion inputs work (§5.4), and it is not bolted on for them: a d-pad is already a coordinate in this
+codebase (`gamepad_write_dpad_vector`), so one path serves stick and d-pad.
+
+The eight directional switches derived from one coordinate are **mutually exclusive by construction**, and the
+derived layer **releases the old direction before pressing the new one**, so exclusivity is never momentarily
+violated. §5.4 depends on both.
+
+Three properties an implementer must know, because none is free:
+
+* **Threshold.** Producing a boolean from a coordinate requires one by definition. This is not an exception to
+  §3.3, which forbids shaping the *analog value* handed to a consumer. Constructor argument, defaulted.
+* **Sampling.** Octant transitions are observed only as often as the channel updates. On a gamepad that is the
+  rAF poll (§2.2), so a fast quarter-circle can pass from `Down` to `Right` between two polls without ever
+  reporting `DownRight`, and a motion requiring that step silently fails. Sequences over directions are
+  reliable at hand speed, not at frame-perfect speed.
+* **Hysteresis.** A stick resting on an octant boundary chatters release/press pairs. The threshold carries an
+  angular hysteresis band, defaulted, for the same reason it carries a magnitude threshold: without it a
+  boundary rest position resets hold timers continuously.
+
+---
+
+## 4. Triggers
+
+### 4.1 One interface, two methods and one field
+
+```js
+export class InputTrigger {
+    /**
+     * Is this trigger's condition currently met?
+     * Pure for leaves and combinators. `InputTriggerHold` and `InputTriggerSequence` additionally consult
+     * per-instance state, which edges and ticks maintain.
+     *
+     * @param {BitSet} held interned switch indices currently down
+     * @returns {boolean}
+     */
+    test(held) { }
+
+    /**
+     * Every switch index this trigger can be affected by. Collected once, at compile time (§9.3).
+     * @param {number[]} result
+     */
+    collectSources(result) { }
+
+    /**
+     * Last observed value of `test`, per compiled instance. A binding fires when `test` is true and this
+     * is false. Initialised at compile time to `test(held-at-compile)` - NOT to false. See §4.5.
+     * @type {boolean}
+     */
+    satisfied = false;
+}
+```
+
+**A binding fires on the rising edge of `test`.** That single rule covers press, release, hold, chord, sequence
+and direction, and it is why there is no `Started`/`Performed`/`Canceled` phase enum and no `edge` field.
+
+### 4.2 Leaf triggers — typed constructors
+
+```js
+InputTriggerKey.from('space')
+InputTriggerKey.from(KeyCodes.space)
+InputTriggerMouseButton.from(MouseButtons.left)
+InputTriggerGamepadButton.from(GamepadButtons.a)
+InputTriggerDirection.from(stick, InputDirection.DownRight)     // stick: any InputCoordinate* channel
+```
+
+Each extends `InputTriggerSwitch`, which holds one `InputSource` and whose `test` is `held.get(index)`. The
+subclasses add no fields — they are typed, validating constructors that fix the device and check the code
+against that device's enum. `InputTriggerKey.from('nonexistent')` fails at authoring time under `assert.*`,
+which is compiled out of production, so the typing is free in shipped code.
+
+Serialization round-trips the flat form, so a deserialized trigger is an `InputTriggerSwitch`, not an
+`InputTriggerKey`. Nothing needs the subclass identity at runtime — it exists for the author and the assertion.
+
+### 4.3 Combinators
+
+```js
+InputTriggerChord.from(a, b, c)          // test = AND over children
+InputTriggerRelease.from(a)              // test = NOT child.test
+InputTriggerHold.from(a, 0.5)            // test = child.test AND continuously true for >= 0.5s
+InputTriggerSequence.from(a, b, c)       // test = the matcher completed on this edge (§5)
+```
+
+Combinators take *triggers*, not sources, which is why the requirements compose:
+
+```js
+// "the chord ended"
+InputTriggerRelease.from(InputTriggerChord.from(InputTriggerKey.from('ctrl'),
+                                                InputTriggerKey.from('z')))
+
+// "hold Ctrl+Shift for half a second"
+InputTriggerHold.from(InputTriggerChord.from(InputTriggerKey.from('ctrl'),
+                                              InputTriggerKey.from('shift')), 0.5)
+
+// cross-device: nothing here knows a device is involved
+InputTriggerChord.from(InputTriggerKey.from('ctrl'),
+                       InputTriggerMouseButton.from(MouseButtons.left))
+```
+
+`InputTriggerRelease` as *negation* rather than an edge kind is what makes it compose — an edge flag on a chord
+could not express "when this chord stops holding".
+
+**One composition that does not mean what it looks like:** `InputTriggerRelease.from(sequence)`. A sequence's
+`test` is a single-edge pulse (§5.2 step 5), so negating it yields "true except on the completing edge", which
+rises on the *next* evaluated edge after every completion — an echo of the fire, not "the sequence stopped
+matching". A sequence's partial-match state is deliberately not exposed to `test`. Do not wrap a sequence in
+`Release`.
+
+### 4.4 Step timeout lives on the sequence
+
+```js
+InputTriggerSequence.from(a, b, c).withStepTimeout(0.25)
+```
+
+Default **1.0 s**, which suits editor and menu sequences whose first step is a chord the author must release
+before reaching for the next key. Fighting-game motions want 0.15–0.25 s. §5.2 defines exactly what the window
+measures, which is not what a naive reading suggests.
+
+Timing was specified here as **real time**, stamped at edge arrival, on the argument that a paused game must
+not give a chord an infinite window and a game at 0.25× speed must not quarter the player's reflexes.
+
+**Superseded.** As built it is *simulation* time, advanced by `update(dt)` and nowhere else. The reason is
+testability: a real-time clock cannot be driven from a spec without faking one, and faking it is a mock. The
+consequences are real and accepted — windows stretch under slow motion and freeze while the game is paused,
+so a hold inside a pause menu can never mature. See the implementation plan's amendments section for the full
+argument.
+
+### 4.5 `satisfied` is initialised from state, not from false
+
+At compile time each trigger instance sets `satisfied := test(held)` against the currently held switches. It is
+**not** zero-initialised, and the difference is not academic:
+`InputTriggerRelease.from(InputTriggerChord.from(ctrl, z))` has `test` true whenever the chord is *not* held —
+which is almost always. Zero-initialised, the first edge touching `ctrl` or `z` would see `now=true, was=false`
+and fire "the chord ended" before the chord ever existed.
+
+This matters on every compile, not just the first: maps link mid-dispatch (§2.3), and `registerDevice` and
+binding edits both recompile live maps while keys are held.
+
+### 4.6 Precedence within a layer
+
+Candidate triggers on one edge are ordered, and the order is total so it never depends on declaration accident:
+
+1. **Sequences first**, longer before shorter (by step count).
+2. Then by **chord width** — the number of switches that must be simultaneously held. `Hold` and `Release`
+   rank by their child's width, so `Hold(Chord(a,b), t)` ranks as width 2 and beats `Key(a)`; `Direction` ranks
+   as width 1.
+3. Then declaration order within the layer.
+
+A fired trigger consumes its switches for the remainder of the current edge (§8), so `Ctrl+Z` firing means `Z`
+does not.
+
+**The condition on that guarantee.** Consumption is scoped to one edge, so it arbitrates only triggers that
+complete on the *same* edge. `Ctrl` pressed before `Z` gives one edge (`z↓`) at which both `Ctrl+Z` and `Z` are
+satisfiable, and the chord wins. `Z` pressed **before** `Ctrl` gives two edges: `z↓` fires `Z`'s action (the
+chord is not yet satisfiable, so there is nothing to lose to), then `ctrl↓` fires `undo`. **Both fire.**
+
+This is inherent to zero-latency evaluation — suppressing the first would mean either delaying it or retracting
+a dispatched action, and both are excluded. Practically it is rarely reached, because modifier-first is how
+people type chords. Where it matters, do not bind a bare key in the same layer as a chord that contains it.
+
+---
+
+## 5. Sequence semantics
+
+### 5.1 State
+
+Per sequence binding instance, three numbers, held on the **compiled clone** of the trigger (§9.3):
+
+```js
+#step             // steps matched so far, 0..N
+#stepSatisfied    // last observed value of steps[#step].test
+#window           // time the current step's window last refreshed
+```
+
+*(An earlier revision put these in typed arrays on the program, indexed by sequence-binding index. Cloning per
+binding is what the compiler does anyway — authored triggers are shared, so evaluation state cannot live on
+them — and once each binding owns a private trigger object, three fields on it are the same thing with less
+bookkeeping. Nothing allocates per evaluation either way.)*
+
+Entering a state is one operation, and **every** path into a state uses it. That is the whole of §17's most
+important correction:
+
+```js
+function enter(k, held, now) {
+    step      = k;
+    satisfied = (k < N) ? steps[k].test(held) : false;   // the entry snapshot
+    window    = now;
+}
+```
+
+### 5.2 The rule
+
+Evaluated at each edge (device or synthetic) and each tick:
+
+```
+1.  if (step > 0) {
+        if (steps[step - 1].test(held))          window := now          // previous step still holds
+        else if (now - window > step_timeout)    enter(0, held, now)     // window expired
+    }
+
+2.  cur := steps[step].test(held)
+
+3.  if (cur && !satisfied) {
+        enter(step + 1, held, now)
+        if (step === N) {
+            fire()                     // the sequence's own `test` reads true for this edge
+            enter(0, held, now)
+        }
+    } else {
+        satisfied := cur
+    }
+```
+
+Three properties do all the work:
+
+* **Advance on a rising edge, not on satisfaction.** Otherwise one long press of `A` satisfies both steps
+  of `[A, A]`.
+* **The entry snapshot, on every entry.** Advance, expiry and post-fire wrap all route through `enter`, so a
+  reset can never leave a stale `satisfied` behind. `enter` never indexes `steps[N]`.
+* **The window measures time since the previous step stopped holding**, not time since the advance. Step 1
+  refreshes `window` for as long as `steps[step-1]` is still satisfied, which is what makes charge inputs work
+  (§5.4) and is why the tick must service sequences even when no edge arrives.
+
+**A mismatch does not reset. Only window expiry resets.** A sequence is a leniency window, and the window is
+what §5.2 step 1 defines.
+
+### 5.3 Worked: `[A, A, B]` on `A↓ A↑ A↓ A↑ A↓ B↓`
+
+| edge | held | step | step-1 holds? | `cur` | `satisfied` | result |
+|---|---|---|---|---|---|---|
+| — | {} | 0 | — | — | false (compile snapshot) | |
+| `A↓` | {A} | 0 | — | true | false | **rise** → `enter(1)`, `satisfied := A.test({A}) = true` |
+| `A↑` | {} | 1 | no | false | true | `satisfied := false` |
+| `A↓` | {A} | 1 | yes → refresh | true | false | **rise** → `enter(2)`, `satisfied := B.test({A}) = false` |
+| `A↑` | {} | 2 | no | false | false | — |
+| `A↓` | {A} | 2 | yes → refresh | false | false | — |
+| `B↓` | {A,B} | 2 | yes → refresh | true | false | **rise** → `enter(3)` = N → **fire**, `enter(0)` |
+
+No failure function, no KMP: the entry snapshot alone prevents one press from satisfying two steps.
+
+**Post-fire, the case revision 2 got wrong.** `enter(0, {A,B}, now)` snapshots `satisfied := A.test({A,B}) =
+true`. So with `A` still held, tapping `B` again gives `cur = true, satisfied = true` — no rise, no fire.
+Revision 2 left `satisfied` untouched on the post-fire reset, and holding `A` while mashing `B` machine-gunned
+the action off a single `A` press.
+
+### 5.4 Worked: chords, motions and charge
+
+**`Ctrl+Shift+A > B`** — steps are triggers, and a chord is a trigger, so this is not a special case:
+
+```js
+map.bind('promote', InputTriggerSequence.from(
+    InputTriggerChord.from(InputTriggerKey.from('ctrl'),
+                           InputTriggerKey.from('shift'),
+                           InputTriggerKey.from('a')),
+    InputTriggerKey.from('b')
+));
+```
+
+`ctrl↓`, `shift↓`: chord false. `a↓`: chord rises → `enter(1)`, `satisfied := b.test({ctrl,shift,a}) = false`.
+Then `b↓` fires — **whether or not the modifiers were released first**, because leaf and chord tests are
+*subset* tests over the held set, and because holding the chord keeps refreshing the window rather than
+starting its clock.
+
+**Quarter-circle forward, `↓ ↘ →`** — this is the case that only works because directions are derived from a
+coordinate (§3.4) rather than read off raw d-pad buttons:
+
+```js
+const stick = InputCoordinateGamepad.from(GamepadCoordinates.left_stick);
+
+map.bind('hadouken', InputTriggerSequence.from(
+    InputTriggerDirection.from(stick, InputDirection.Down),
+    InputTriggerDirection.from(stick, InputDirection.DownRight),
+    InputTriggerDirection.from(stick, InputDirection.Right)
+).withStepTimeout(0.2));
+```
+
+| edge | held | step | `cur` | result |
+|---|---|---|---|---|
+| `Down↓` | {Down} | 0 | true | **rise** → `enter(1)`, `satisfied := DownRight.test({Down}) = false` |
+| `Down↑` | {} | 1 | false | — |
+| `DownRight↓` | {DownRight} | 1 | true | **rise** → `enter(2)`, `satisfied := Right.test({DownRight}) = false` |
+| `DownRight↑` | {} | 2 | false | — |
+| `Right↓` | {Right} | 2 | true | **rise** → `enter(3)` = N → **fire** |
+
+The two snapshots in the result column are the trick. With raw d-pad buttons `↓` and `→` can be held together,
+`Right.test({Down,Right})` is `true` on entry to state 2, and the motion can never complete. Exclusivity by
+construction is what removes that failure mode — which is why §12.2 tests it in both directions.
+
+**Dragon punch, `→ ↓ ↘`** — the same trace with steps permuted; each entry snapshot is false for the same
+reason. Verified also against the realistic rolled input `Right, DownRight, Down, DownRight`, where the
+intermediate `DownRight↓` at step 1 is a non-advancing mismatch (ignored, correctly) and the final one fires.
+
+**Charge, `hold ← for 2 s, then →`** — the case revision 2 published as passing and which in fact failed:
+
+```js
+InputTriggerSequence.from(
+    InputTriggerHold.from(InputTriggerDirection.from(stick, InputDirection.Left), 2.0),
+    InputTriggerDirection.from(stick, InputDirection.Right)
+)
+```
+
+At t=2.0 the hold matures, emits a synthetic edge (§2.1) and rises → `enter(1)`. The player then keeps holding
+`←`, which is what charge play *is*. Under revision 2 the window ran from the advance, so any charge longer
+than `duration + step_timeout` expired before the flick and the move was silently lost; raising the timeout
+instead produced ghost charges minutes later. Under §5.2 step 1, `steps[0].test` — the hold — is still true
+while `←` is held, so `window` is refreshed on every tick. Release `←` at t=8.0 and the window opens *there*;
+`→` within `step_timeout` fires. Return to neutral instead and the window expires normally, so there is no
+ghost.
+
+**Motion plus button, `236 + P`** — append `InputTriggerGamepadButton.from(GamepadButtons.x)` as a fourth step.
+While `→` is held, step 1 keeps refreshing the window, so the button may be pressed at leisure; it fires with
+`→` still held because button steps are subset tests.
+
+### 5.5 What this deliberately cannot do
+
+**Strict rejection.** `↓ ← →` inside the window fires the quarter-circle, because `←` neither advances nor
+resets. Arcade-grade matchers reject a direction outside the expected set. The shape of the fix is known — an
+optional rejection predicate on the sequence, resetting to 0 when it matches — and it is **deferred until a
+consumer asks**, on the position that the common case should be the only case. For every sequence in this
+codebase, and for menu, cheat-code and editor cases, leniency is the wanted behaviour.
+
+**Button buffering.** A button pressed *before* the motion step it follows poisons that step's entry snapshot
+and must be re-pressed. Genre-standard buffering is a fighting-game engine feature, not an input-mapping one.
+
+**Tap versus hold on the same switch — accepted as a cost of zero latency.** Given
+`'interact' = Key(e)` and `'loot_all' = Hold(Key(e), 0.5)`, a press-and-hold fires **both**: `'interact'` at
+`e↓`, `'loot_all'` 0.5 s later. They complete on different edges, so §4.6's per-edge consumption cannot
+arbitrate them, and no composition inside the algebra separates them either —
+`Chord(Release(e), Release(Hold(e, 0.5)))` collapses, because `hold.test` falls to false on the same `e↑` edge
+the release rises on.
+
+Discriminating them requires *withholding* the short action until the hold window has passed, which is
+precisely the frame-buffered dispatch this design exists to avoid. Paying that architectural cost — a second,
+deferred dispatch path with its own ordering and occlusion semantics — for one interaction pattern is not
+worth it. **Tap-and-hold pairs must use distinct inputs** (`E` and `Shift+E`), or accept that the hold is
+additive to the tap. Revision 2 claimed §4.6 arbitrated this; it does not.
+
+**Key autorepeat.** `KeyboardDevice` discards `event.repeat` (`KeyboardDevice.js:93-97`) and
+`InputDeviceSwitch.press()` is idempotent, so a held key produces exactly one edge. Autorepeat is not
+observable anywhere in this design, and a consumer that wants repeat behaviour — held-key menu navigation,
+`EditorKeyMap`'s current repeat-undo — must drive it from `isActive` plus its own timer. Changing this means
+changing `KeyboardDevice`, which is out of scope.
+
+### 5.6 Why `SimpleStateMachine` is not used
+
+The first revision built this on
+[`SimpleStateMachine`](../../../../core/fsm/simple/SimpleStateMachine.js) and
+[`SimpleStateMachineDescription`](../../../../core/fsm/simple/SimpleStateMachineDescription.js). It does not
+earn its place here, and the reasons are specific rather than a matter of taste:
+
+* **The graph is a path.** States `0..N` with edges `i → i+1` plus resets to `0`. There is nothing to search,
+  so `findPath` — the description's real capability — is dead weight.
+* **The self-transition is not declarable.** "Stay in the current state on a mismatch" is the common case, and
+  the edge set never contains `i → i`. It works only because the edge-existence assertion in `advance()` is
+  commented out (`SimpleStateMachine.js:238`) — a latent trap if those assertions are ever restored.
+* **Initial state is `-1`** (`SimpleStateMachine.js:16`), so every instance needs an explicit `setState(0)`.
+* **It is not the cheap object it looks like.** Each instance carries a description reference and two handler
+  arrays (`SimpleStateMachine.js:22-30`) that this design never registers into — while `satisfied` and `window`
+  have to live outside it regardless. Three typed-array slots replace all of it with no per-instance object.
+
+The requirement was to make good use of existing meep constructs. The honest reading is that this construct
+does not fit this problem: the matcher is a path, not a graph. **`SimpleStateMachineDescription` becomes the
+right tool the moment sequences branch** — alternate motions sharing a prefix, resolved by longest match —
+and that is the point at which to adopt it, not before.
+
+---
+
+## 6. Actions — the bindings/behaviour seam
+
+### 6.1 The seam
+
+```
+   DATA  (serializable, no code)                |    CODE (never serialized)
+   -----------------------------                |    ----------------------
+   trigger                ---->  action name    |    action name  ---->  behaviour
+   Chord(ctrl, z)                "undo"         |    "undo"       ---->  editor.actions.undo()
+```
+
+The left side is an `InputMap` component. The right side is an ECS event listener. They meet at a string, and
+nothing else crosses. This is the same seam [`InputSystem`](../systems/InputSystem.js) already uses
+(`InputSystem.js:79`), which is why that component is the one worth keeping the shape of. It is explicitly
+*not* a string-keyed factory registry: no behaviour is constructed from the string and no class is looked up
+by it.
+
+### 6.2 One event, one level, one coordinate
+
+```js
+// discrete — fires on the trigger's rising edge, this instant, no frame delay
+ecd.addEntityEventListener(entity, 'undo', () => editor.actions.undo());
+
+// continuous — no listener, no mirrored boolean, no teardown handler
+if (map.isActive('sprint')) { ... }
+map.axis2(v, 'move');
+```
+
+Three accessors for three *questions* — "did it happen", "is it happening", "how much" — not three ways to ask
+one question. The level accessor is what deletes
+[`KeyboardCameraController`](../controllers/KeyboardCameraController.js)'s `controls` struct, the 16 `bind()`
+calls maintaining it, and the `clearControls` handler wired to `on.unlinked` that exists solely to stop the
+camera drifting after teardown. The same boilerplate is duplicated almost verbatim in
+[`prototype_first_person_controller.js`](../../../control/first-person/prototype_first_person_controller.js).
+
+Two things `isActive` is not: it is effectively always `false` for a sequence action, whose `test` is a
+single-edge pulse; and it returns `false` for every action on a **suppressed** map (§8).
+
+*(One behaviour `KeyboardCameraController` has that the coordinate does not reproduce: it sends a `'user-input'`
+entity event on every pan keydown (`KeyboardCameraController.js:54`), consumed elsewhere as an interaction
+signal. Porting it is a `map.bind('user-input', ...)` alongside the coordinate, and §14 lists it rather than
+leaving it to be discovered missing.)*
+
+### 6.3 The event payload
+
+```js
+export class InputActionEvent {
+    action = "";
+    /** Driving coordinate, or the pointer position, at the moment the trigger fired. @type {Vector3} */
+    value = new Vector3();
+    /** The switch whose edge completed the trigger. For a synthetic hold-maturity edge, the first
+     *  switch in the hold's own source set. @type {InputSource} */
+    source = new InputSource();
+    /** Arrival timestamp of the completing edge, real time, seconds since ISM start. @type {number} */
+    time = 0;
+}
+```
+
+One instance, reused across dispatches, mutated in place. Dispatch is synchronous, so a handler that reads it
+inline is correct and one that retains it is not — stated in the JSDoc, as scratch vectors are elsewhere in
+the engine. A nested edge cannot clobber it mid-read, because nested edges are queued rather than processed
+inline (§2.3).
+
+**It carries no DOM information**, and that is a real limit worth naming: consumers that today gate on
+`event.target === graphics.domElement` to tell a canvas click from a click on overlaying UI —
+`CombatInteractionStateMachine` does — have no equivalent here. UI-overlay occlusion is a DOM-tree question
+that §8's map occlusion cannot see. Those consumers are in the gesture set that stays on `InputController`
+(§1.1) for now; a DOM-aware gate is part of the deferred gesture work.
+
+---
+
+## 7. Layers — a stack, addressed by index
+
+Layers solve **rebinding**: defaults, then the player's overrides, then a context-specific tweak — one
+conceptual keymap assembled from stacked sources, top wins. They are a stack, addressed by index.
+
+```js
+const map = new InputMap();
+
+map.bind('jump', InputTriggerKey.from('space'));          // layer 0, the base
+map.bind('undo', InputTriggerChord.from(InputTriggerKey.from('ctrl'),
+                                        InputTriggerKey.from('z')));
+
+const user = map.pushLayer();                             // index 1
+user.bind('jump', InputTriggerGamepadButton.from(GamepadButtons.a));   // REPLACES space
+```
+
+```js
+map.layer(i)      // InputLayer at index i, asserts existence
+map.pushLayer()   // append, return the new top
+map.popLayer()    // discard the top
+map.bind(...)     // sugar for map.layer(0).bind(...)
+```
+
+Rules, and they are CSS's:
+
+* Higher index is higher in the cascade.
+* The cascade is **per action name**, and it applies identically to trigger bindings and coordinate bindings
+  (§9.1). The highest layer binding an action supplies *all* of that action's triggers or channels; lower
+  layers' entries for it are inert.
+* To keep both, bind both **in one layer** — a binding maps one action to a *list*, exactly as
+  `font-family: a, b` lists fallbacks in one declaration:
+
+```js
+map.bind('jump', InputTriggerKey.from('space'), InputTriggerGamepadButton.from(GamepadButtons.a));
+```
+
+  Replace-versus-add is a property of *where you write it*, not a flag on `bind`. That is what lets rebinding
+  ("the user's jump wins") and multi-device ("either device jumps") both be expressible with no mode switch.
+
+* An action named in the top layer that binds it, with nothing bound, is **unbound** — how a keymap layer
+  removes an inherited binding:
+
+```js
+map.layer(1).unbind('undo');
+```
+
+* An action name is either a trigger action or a coordinate action, never both — asserted at authoring time,
+  because `isActive('move')` and `axis2(v, 'move')` would otherwise disagree about what `'move'` is.
+
+Layers carry no names. There is nothing to look up, so nothing to mistype, and serialization is one `uint16`
+count with no strings (§10).
+
+---
+
+## 8. Occlusion — arbitration across entities
+
+Layers are within one map. Modality is across maps, and it is a different question: the cascade is *nominal*
+(over action names), occlusion is *physical* (over switches).
+
+```js
+export const InputOcclusion = {
+    /** Sees everything, blocks nothing. HUD overlays, debug readouts, recorders. */
+    Pass: 0,
+    /** Switches consumed by this map's fired triggers are invisible below, for that edge. The default. */
+    BlockMatched: 1,
+    /** Every map below is suppressed outright. Modal dialogs, pause menus. */
+    BlockAll: 2
+};
+```
+
+**The two values do different jobs at different scopes, and revision 2's failure to say so was a real bug.**
+
+### 8.1 `BlockMatched` — dynamic, per edge, dispatch only
+
+Per edge, the walk descends maps by `order`. A `consumed : BitSet` over interned switch indices accumulates as
+it goes; a fired trigger adds its own switches, and a trigger whose switches are already consumed does not
+dispatch.
+
+**Consumption gates dispatch, not evaluation** — and this is the correction that matters, because the obvious
+alternative is broken. Hiding a consumed edge from a lower map entirely freezes that map's triggers at their
+last observed values, and the next edge they *do* see no longer looks like a change. Concretely: an upper map
+binding `Release(k)` and a lower map binding `k`. Every release is consumed above, so the lower map never
+observes `k` going up; its press trigger fires once and is then dead forever. So lower maps keep evaluating,
+and only their dispatch is suppressed.
+
+The honest consequence, since an earlier revision of this document claimed otherwise: a modal-consumed
+keystroke **does** advance a lower map's sequence and **does** run its hold timers. Only the firing is
+withheld. `BlockAll` is what makes a lower map genuinely inert (§8.2), and that is another reason the two
+values are not degrees of the same thing.
+
+Consumption is also **unconditional within a map**. Specificity arbitration — `Ctrl+Z` beating a bare `Z`
+(§4.6) — is a property of the map, not of its occlusion, so it holds in a `Pass` map too. What occlusion
+decides is only whether that consumption is still standing when the next map down is walked.
+
+`BlockMatched` does not affect polled reads. A pause menu using it stops the combat scene's `Escape` while the
+camera keeps panning behind it — which is exactly what §8 wants of it.
+
+### 8.2 `BlockAll` — static, whole-map, dispatch *and* reads
+
+Each linked map carries a computed `suppressed : boolean` — "is there a `BlockAll` map above me". It is
+recomputed when the linked map set, any `order`, or any `occlusion` changes; not per edge.
+
+A suppressed map is **inert**: the walk skips it, so nothing dispatches; `isActive` returns `false`; coordinate
+reads return zero; sequence matchers do not advance and hold timers do not run. On un-suppression every
+sequence matcher is re-entered with `enter(0, held, now)` (§5.1), so it resumes against current reality rather
+than stale state.
+
+This is the fix for the defect revision 2 shipped. There, occlusion was a per-edge `consumed` set gating
+*firing* only, while `isActive` and the coordinate accessors are **polled** — outside any edge walk, with
+nothing connecting them. So the §11 pause menu stopped edge-driven actions while the §11 camera, which is a
+`Script` polling `map.axis2(pan, 'pan')` over WASD every tick, kept panning: precisely the drifting-world bug
+the modal value exists to prevent. Its two occlusion test cases both passed, because both tested dispatched
+actions only.
+
+### 8.3 Consequences worth stating
+
+* **Local co-op needs no fourth value.** `BlockMatched` is per switch, so player 2's pad is untouched by player
+  1's map — they never reference the same switch. `BlockAll` suppresses whole maps and is therefore wrong for
+  split-screen; that is a property of the modal hammer, not a hole in it.
+* **`order` ties are resolved by link order**, oldest first. Deterministic, and mentioned because the format
+  clamps `order` (§10) and ties are therefore reachable.
+* **Lifetime is entity lifetime.** This is already how the game scopes input:
+  `CombatInteractionStateMachine` registers an entity per FSM state and lets `link`/`unlink` turn bindings on
+  and off (`CombatInteractionStateMachine.js:113-160`). Put the `InputMap` on the entity owning the context and
+  entering or leaving the state *is* the binding lifecycle — no `enable()`/`disable()` bookkeeping, no
+  `clearControls` on teardown.
+
+---
+
+## 9. The component and the system
+
+### 9.1 `InputMap`
+
+```js
+export class InputMap {
+    static typeName = "InputMap";
+    static serializable = true;
+
+    /** Index 0 is the base. @readonly @type {InputLayer[]} */
+    layers = new List();
+
+    /** Cross-entity arbitration, higher evaluates first. @type {number} */
+    order = 0;
+
+    /** @type {InputOcclusion} */
+    occlusion = InputOcclusion.BlockMatched;
+
+    // ---- authoring -----------------------------------------------------
+    bind(action, ...triggers) { }           // -> InputMap, writes to layer 0
+    bindCoordinate(action, ...channels) { } // -> InputMap, writes to layer 0
+    unbind(action) { }                      // -> InputMap, covers both kinds
+    layer(index) { }                        // -> InputLayer
+    pushLayer() { }                         // -> InputLayer
+    popLayer() { }
+
+    // ---- reading -------------------------------------------------------
+    isActive(action) { }                    // -> boolean
+    coordinate(result, offset, action) { }  // any dimensionality
+    axis1(result, action) { }               // Vector1
+    axis2(result, action) { }               // Vector2
+    axis3(result, action) { }               // Vector3
+
+    equals(other) { }
+    hash() { }
+}
+```
+
+```js
+export class InputLayer {
+    /** @readonly @type {InputBinding[]} */
+    bindings = new List();
+    /** @readonly @type {List<InputCoordinateBinding>} */
+    coordinates = new List();
+
+    bind(action, ...triggers) { }
+    bindCoordinate(action, ...channels) { }
+    unbind(action) { }
+}
+
+export class InputBinding {
+    action = "";
+    /** @readonly @type {InputTrigger[]} */
+    triggers = new List();
+}
+
+export class InputCoordinateBinding {
+    action = "";
+    /** @readonly @type {InputCoordinateChannel[]} */
+    channels = new List();
+}
+```
+
+**Coordinate bindings are a first-class list on the layer, not triggers.** Revision 2 exposed
+`bindCoordinate()` with nowhere to store the result — `InputBinding` holds triggers, and a channel is not a
+trigger — so coordinate bindings existed in the API, in the examples and in the argument for deleting
+`KeyboardCameraController`, but in neither the component nor the wire format.
+
+**Multiple channels on one action resolve by priority: the first channel with any non-zero component wins.**
+Deterministic, allocation-free, and the behaviour consumers already hand-write — `GamepadDevice`'s own
+documented example is "stick wins, else D-pad". It also avoids the alternative's arithmetic nonsense, where
+keyboard `D` plus a stick at 0.3 would sum to 1.3. All channels bound to one action must agree on
+`dimensions`; asserted at authoring time.
+
+The simple case never mentions layers, occlusion or order:
+
+```js
+const map = new InputMap();
+map.bind('jump', InputTriggerKey.from('space'));
+```
+
+### 9.2 `InputMapSystem`
+
+```js
+export class InputMapSystem extends System {
+    dependencies = [InputMap];
+
+    registerDevice(adapter) { }     // may be called after maps are linked; recompiles them (§3.1)
+
+    link(map, entity) { }           // compile (§9.3), subscribe to newly-referenced switches
+    unlink(map, entity) { }         // release; unsubscribe switches no live map references
+    update(dt) { }                  // time only: hold maturity, sequence windows, Delta reset, suppression
+
+    setRecorder(recorder) { }       // §2.5 — DESIGNED, NOT BUILT
+}
+```
+
+Construction takes adapters rather than `engine.devices`, so the system has no dependency on the shape of that
+object and is constructible in a test with nothing behind it:
+
+```js
+new InputMapSystem([
+    new KeyboardInputDeviceAdapter(devices.keyboard),
+    new PointerInputDeviceAdapter(devices.pointer),
+    new GamepadInputDeviceAdapter(devices.gamepad)
+]);
+```
+
+Each interned switch is subscribed once, with a per-switch `SourceBinding {index, system}` passed as the
+`Signal` handler's context (`Signal.js:151`), so the edge path allocates nothing and needs no closure per
+event.
+
+*(As built, the system declares no `components_used`, and does not need to: relative channels LATCH rather
+than clear (§3.3), so every reader in a frame sees the same value regardless of where the system runs in it.
+An earlier revision of this section leaned on execution order instead, which was the weaker guarantee.)*
+
+**Unlinking a map with a sequence mid-match** discards its matcher state along with the compiled program;
+there is nothing to leak and nothing to resume. Unlinking with switches held is likewise clean: `#held` is
+owned by the system, not the map, and the map's triggers are simply gone.
+
+### 9.3 Compilation: the stylesheet / computed-style split
+
+The `InputMap` component is *authored* data — layered, editable. It is not what the edge path reads. On `link`,
+on `registerDevice`, and on any structural change, the system compiles it into an internal `InputMapProgram`:
+
+* cascade resolved — one flat action table per kind, layers already collapsed;
+* switches interned to `Uint32` indices against a system-wide table;
+* per switch, the list of triggers it can affect (`collectSources`), pre-sorted into §4.6 specificity order, so
+  an edge touches only triggers that could possibly care;
+* every trigger's `satisfied` initialised from current state, not from `false` (§4.5);
+* sequence matcher state allocated as three typed-array slots per sequence binding (§5.1).
+
+The edge path then touches integers, typed arrays and `BitSet`s only. No string comparison, no `List`
+traversal, no allocation per event. Recompiles requested during dispatch are queued and applied at the end of
+the current edge (§2.3), so a walk always completes against the program it started with.
+
+---
+
+## 10. Serialization
+
+```js
+export class InputMapSerializationAdapter extends BinaryClassSerializationAdapter {
+    klass = InputMap;
+    version = 0;
+
+    serialize(buffer, map) { }
+    deserialize(buffer, map) { }
+}
+```
+
+```
+InputMap
+  int16    order                  see below
+  uint8    occlusion              InputOcclusion
+  uint8    device_count
+  repeat   device_count x utf8    device table - every InputDeviceAdapter#id referenced
+  uint16   layer_count
+  repeat   layer_count x InputLayer          index 0 first; layers carry no name
+
+InputLayer
+  uint16   binding_count
+  repeat   binding_count x InputBinding
+  uint16   coordinate_binding_count
+  repeat   coordinate_binding_count x InputCoordinateBinding
+
+InputBinding
+  utf8     action
+  uint8    trigger_count
+  repeat   trigger_count x InputTrigger
+
+InputCoordinateBinding
+  utf8     action
+  uint8    channel_count
+  repeat   channel_count x InputCoordinateChannel
+
+InputTrigger
+  uint8    type                   InputTriggerType
+    Switch     : InputSource
+    Direction  : InputCoordinateChannel, uint8 direction, float32 threshold, float32 hysteresis
+    Chord      : uint8 child_count, children
+    Sequence   : uint8 child_count, children, float32 step_timeout
+    Hold       : child, float32 duration
+    Release    : child
+
+InputCoordinateChannel
+  uint8    type                   InputCoordinateChannelType
+    Device   : InputCoordinateSource
+    Switches : uint8 count, count x InputTrigger        (2 per dimension: negative, positive)
+    Compose  : uint8 count, count x InputCoordinateChannel
+
+InputSource
+  uint8    device_index           into the map's device table
+  uint16   code
+
+InputCoordinateSource
+  uint8    device_index
+  uint16   code
+  uint8    dimensions
+  uint8    kind                   InputCoordinateKind
+```
+
+Decisions, not incidentals:
+
+* **`order` is `int16`.** Revision 2 wrote it as `uint8 + 128`, range `[-128, 127]` — and its own modal example
+  used `order = 1000`, which clamped to 127 on load and could silently tie with any other high map. `int16`
+  covers the examples and leaves headroom; ties resolve by link order (§8.3).
+* **Coordinate bindings are reachable from the root.** Revision 2 defined an `InputCoordinateChannel` encoding
+  that nothing referenced, so no map containing a coordinate could round-trip.
+* **`Direction` serializes a channel, not a source.** It accepts any `InputCoordinate*` channel (§4.2), so
+  writing only an `InputCoordinateSource` made direction-over-composed-channel constructible and
+  unserializable.
+* **A device table, not a string per source.** A 40-binding keyboard map writes `"keyboard"` once rather than
+  forty times.
+* **Every string here is an identifier.** `writeUTF8String` is ASCII-only in practice and `readUTF8String` is
+  NUL-terminated by design, so this must be stated: action names and device ids are ASCII identifiers, not
+  localized text. A binding UI shows a label looked up *from* the action name; it never serializes the label.
+* **Codes come from enums, three of which are new.** `KeyCodes`, `GamepadButtons` and `GamepadAxes` are already
+  stable on-disk quantities; `MouseButtons`, `PointerCoordinates` and `GamepadCoordinates` are introduced here
+  and are append-only once shipped (§3.1). Revision 2 claimed "no new numbering to keep in sync", which was
+  false the moment it introduced them.
+* **Triggers and channels nest, so serialization recurses.** One `uint8` discriminator each, dispatched by a
+  `switch` — verbose, typed and greppable, over a string-keyed constructor table.
+
+---
+
+## 11. End to end
+
+**Gameplay — camera, mixed devices:**
+
+```js
+const map = new InputMap();
+
+map.bindCoordinate('pan',
+    InputCoordinateGamepad.from(GamepadCoordinates.left_stick),   // first non-zero wins
+    InputCoordinateSwitches.from([
+        InputTriggerKey.from('a'), InputTriggerKey.from('d'),
+        InputTriggerKey.from('w'), InputTriggerKey.from('s')
+    ]));
+map.bind('user-input', InputTriggerKey.from('a'), InputTriggerKey.from('d'),
+                       InputTriggerKey.from('w'), InputTriggerKey.from('s'));
+map.bind('focus_selection', InputTriggerKey.from('f'));
+
+new Entity()
+    .add(map)
+    .add(new Script(dt => {
+        map.axis2(pan, 'pan');
+        apply_radial_dead_zone(pan, pan.x, pan.y, 0.15, 0.95);   // policy, at the call site
+        controller.pan(pan, dt);
+    }))
+    .build(ecd);
+```
+
+Both channels feed one action in one call, so the cascade replaces them as a unit; the stick wins while
+deflected and the keys take over when it rests. The `'user-input'` binding is
+`KeyboardCameraController.js:54`'s interaction signal, carried over explicitly rather than lost.
+
+**Editor — `EditorKeyMap` as data:**
+
+```js
+const ctrl = InputTriggerKey.from('ctrl');
+
+const map = new InputMap();
+map.order = 100;
+
+map.bind('undo',      InputTriggerChord.from(ctrl, InputTriggerKey.from('z')));
+map.bind('redo',      InputTriggerChord.from(ctrl, InputTriggerKey.from('y')));
+map.bind('copy',      InputTriggerChord.from(ctrl, InputTriggerKey.from('c')));
+map.bind('paste',     InputTriggerChord.from(ctrl, InputTriggerKey.from('v')));
+map.bind('save',      InputTriggerChord.from(ctrl, InputTriggerKey.from('s')));
+map.bind('duplicate', InputTriggerChord.from(InputTriggerKey.from('shift'), InputTriggerKey.from('d')));
+map.bind('delete',    InputTriggerKey.from('delete'), InputTriggerKey.from('x'));
+
+ecd.addEntityEventListener(entity, 'undo', () => editor.actions.undo());
+```
+
+`Ctrl+Z` beats the bare `Z` binding under §4.6 (modifier-first; see §4.6's stated condition), and the
+`if (event.ctrlKey)` split disappears. The bindings are serializable, so the editor gets a rebinding panel for
+free — the thing that could not exist while they were `if` statements. §14.1 lists the three `EditorKeyMap`
+behaviours that do *not* come across.
+
+**Modal — pause menu:**
+
+```js
+const map = new InputMap();
+map.order = 1000;
+map.occlusion = InputOcclusion.BlockAll;
+map.bind('resume', InputTriggerKey.from('escape'));
+```
+
+Every map below is suppressed: no dispatch, and `isActive`/`axis2` read neutral — so the camera above stops
+rather than drifting behind the dialog (§8.2).
+
+**Cross-device chords:**
+
+```js
+map.bind('precision_place', InputTriggerChord.from(InputTriggerKey.from('ctrl'),
+                                                   InputTriggerMouseButton.from(MouseButtons.left)));
+map.bind('pad_reset',       InputTriggerChord.from(InputTriggerGamepadButton.from(GamepadButtons.back),
+                                                   InputTriggerKey.from('r')));
+```
+
+---
+
+## 12. Testing
+
+### 12.1 No mocks, and no DOM
+
+The seam is `InputDeviceSwitch`: a real object with `press()`/`release()`, constructible in node with nothing
+beneath it. A test adapter is a *real* adapter over *real* switches — not a mock. Eager evaluation keeps the
+tests short, because there is no tick to pump for edge-driven behaviour:
+
+```js
+const kb = new TestInputDeviceAdapter('keyboard', KeyCodes);
+const system = new InputMapSystem([kb]);
+// real EntityComponentDataset, real InputMap, real listeners
+
+kb.switch(KeyCodes.ctrl).press();
+kb.switch(KeyCodes.z).press();
+
+expect(observed).toEqual(['undo']);      // no system.update() anywhere
+```
+
+`system.update(dt)` appears only in tests for hold maturity, sequence windows, `Delta` reset and suppression —
+a precise statement of what the tick is for.
+
+*(Revision 2 justified this by claiming `InputSystem` "cannot be exercised without a focusable DOM element".
+That was overstated: focusability is `KeyboardDevice`'s requirement (`KeyboardDevice.js:61-66`), and
+`InputSystem` resolves paths against any object, so a synthetic tree of real Signals would exercise it. The
+real point is narrower and still worth making — nobody has, and `InputBinding.spec.js` asserts only that a
+constructor does not throw.)*
+
+### 12.2 What gets asserted
+
+Observable behaviour only: dispatched action names and order, `isActive` levels, coordinate values. Never which
+triggers were evaluated, never how many times a matcher ran, never internal matcher state.
+
+| | Case | Guards |
+|---|---|---|
+| 1 | An action fires before any `update()` runs | §2 eager evaluation — the requirement, as a test |
+| 2 | Press and release inside one frame both fire; two presses dispatch in press order | §2 |
+| 3 | `Ctrl` then `Z` fires only `undo`; `Z` then `Ctrl` fires both, in that order | §4.6 and its stated condition |
+| 4 | One long press of `A` does not satisfy both steps of `[A, A]` | §5.1 entry snapshot |
+| 5 | `[A,A,B]` fires on `A A A B` | §5.3 |
+| 6 | Holding `A` and tapping `B` twice fires `[A,B]` **once** | §5.3 post-fire re-entry — the revision-2 machine-gun |
+| 7 | A window expiry with the first step's key held does not spuriously advance | §5.1 — the revision-2 stale-snapshot bug |
+| 8 | `Ctrl+Shift+A > B` fires whether or not modifiers are released first | §5.4 |
+| 9 | `↓ ↘ →` over a stick coordinate fires; the same over raw d-pad *buttons* does not | §5.4 — the exclusivity claim, both directions |
+| 10 | Charge (`hold ← 2 s > →`) fires after a 10 s hold; returning to neutral instead expires it | §5.2 window refresh — the revision-2 charge failure |
+| 11 | A sequence window expires only after the previous step stops holding | §5.2 |
+| 12 | `Release(Chord(a,b))` does not fire on the first edge touching `a` | §4.5 `satisfied` initialisation |
+| 13 | A handler that removes its own entity, or rebinds its own map, does not corrupt the walk | §2.3 |
+| 14 | A `BlockAll` map zeroes a lower map's `axis2` and `isActive`, not just its dispatch | §8.2 — the revision-2 drifting camera |
+| 15 | A `BlockMatched` map does **not** stop a lower map's unrelated action or its coordinate reads | §8.1 — the converse |
+| 16 | A lower map's press binding still fires after many edges consumed above it | §8.1 — the stale-edge trap |
+| 17 | Un-suppressing a map re-enters its sequences at 0 rather than resuming stale state | §8.2 |
+| 18 | The top layer's `jump` replaces the base layer's `jump`; two triggers in one layer both fire | §7 |
+| 19 | A coordinate action bound to stick + keys reads the stick while deflected, the keys at rest | §9.1 priority |
+| 20 | A gamepad binding with no pad connected links and never fires; so does an unregistered device id | §3.1 totality |
+| 21 | `registerDevice` after link makes previously inert bindings live | §3.1, §9.3 |
+| 22 | Two wheel events in one frame sum for tick-time readers | §3.3 `Delta` |
+| 23 | A 3-D wheel coordinate round-trips all three components | §3.3 dimensionality |
+| 24 | Serialize, deserialize, replay a recorded trace, get the same dispatches | §10, §2.5 |
+
+Cases 6, 7, 10 and 14 are regressions against defects revision 2 actually contained; write them first. Case 9
+is the only claim in §5.4 that could be wrong in a way the others would not catch.
+
+---
+
+## 13. The trigger DSL — planned, deferred, optional
+
+**Not implemented in this design.** Specified here so the trigger classes are shaped to accept it, and so it
+is not invented ad hoc later.
+
+### 13.1 What it is
+
+A text syntax compiling to the same `InputTrigger` objects §4 defines. It is **an additional entry point,
+never a required one**: an author can compose triggers by hand or write them as text, and the runtime cannot
+tell the results apart.
+
+```js
+import { InputTriggerDSL } from "./dsl/InputTriggerDSL.js";
+
+map.bind('promote', InputTriggerDSL.compile("keyboard:ctrl + keyboard:shift + keyboard:a > keyboard:b"));
+```
+
+### 13.2 Grammar
+
+```ebnf
+trigger    = sequence ;
+sequence   = chord , { ">" , chord } , [ "within" , NUMBER ] ;
+chord      = unary , { "+" , unary } ;
+unary      = [ "!" ] , primary ;
+primary    = atom | "(" , trigger , ")" | call ;
+call       = IDENT , "(" , [ trigger , { "," , trigger | NUMBER } ] , ")" ;
+atom       = DEVICE , ":" , BINDPOINT , [ "." , SUBPOINT ] ;
+DEVICE     = IDENT ;
+BINDPOINT  = IDENT | NUMBER ;
+SUBPOINT   = IDENT ;
+```
+
+| Form | Means | Compiles to |
+|---|---|---|
+| `keyboard:space` | a key | `InputTriggerKey` |
+| `pointer:left` | a mouse button | `InputTriggerMouseButton` |
+| `gamepad:a` | a pad button | `InputTriggerGamepadButton` |
+| `gamepad:left_stick.down` | a direction on a coordinate | `InputTriggerDirection` |
+| `a + b` | chord | `InputTriggerChord` |
+| `a > b` | sequence | `InputTriggerSequence` |
+| `!a` | release / negation | `InputTriggerRelease` |
+| `hold(a, 0.5)` | held for 0.5 s | `InputTriggerHold` |
+| `(...)` | grouping | — |
+| `... within 0.2` | step timeout | `withStepTimeout` |
+
+**Precedence, tightest first:** `!` → `+` → `>` → `within`, so
+`keyboard:ctrl + keyboard:shift + keyboard:a > keyboard:b` parses as intended with no parentheses.
+
+**Keyword collision** is resolved by the `:` — an identifier followed by `:` is a device name, so a device may
+be called `hold` without ambiguity. Worth stating because it is where small DSLs usually break.
+
+The §5.4 motion, written out:
+
+```
+gamepad:left_stick.down > gamepad:left_stick.down_right > gamepad:left_stick.right + gamepad:x within 0.2
+```
+
+### 13.3 Why it stays separate
+
+* **`ism/dsl/` is its own module**, imported by nothing in the runtime. A game that composes triggers by hand
+  never pays for a parser — it is not in the bundle.
+* **It is a compiler, not a representation.** Serialization stays binary (§10), so a DSL change can never
+  invalidate saved bindings.
+* **`InputTriggerDSL.stringify(trigger)` is the inverse**, which is what a rebinding UI wants: it shows a
+  binding in the syntax an author would type, with no second formatting path.
+
+### 13.4 Deferred until
+
+Everything in §14 phases 1–8 has landed and at least one consumer has migrated. The DSL is a convenience over a
+working system; building it first would freeze the trigger vocabulary before the vocabulary has been used.
+
+---
+
+## 14. Migration
+
+The ISM lands beside the existing systems. Both keep working; neither is touched until its consumers move.
+**`InputController` and `InputControllerSystem` survive this program** — they still own every gesture binding
+(§1.1).
+
+*This table is the plan of work, not a progress report. For where each phase actually stands, read the status
+section of [`ISM_IMPLEMENTATION_PLAN.md`](ISM_IMPLEMENTATION_PLAN.md), which is kept current as phases land.*
+
+| Phase | Work | Gate |
+|---|---|---|
+| **1** | `InputSource`, `InputCoordinateSource`, the `InputTrigger*` classes, `InputMap` / `InputLayer` / `InputBinding` / `InputCoordinateBinding` | Value-object specs: `equals` / `hash` / round-trip |
+| **2** | `InputDeviceAdapter` and the three adapters; the `MouseButtons`, `PointerCoordinates`, `GamepadCoordinates` enums | Totality: every declared code resolves with no hardware, and with no adapter (§12.2 cases 20–21) |
+| **3** | `InputMapSystem`: eager edge path, `#held`, compile, switch/chord/release, cascade, `BlockMatched`, ECS dispatch, `isActive` | cases 1–3, 12, 13, 15, 18 |
+| **4** | `InputTriggerSequence` + `InputTriggerHold`; synthetic maturity edges; window refresh and expiry | cases 4–8, 10, 11, 16 |
+| **5** | Coordinates: channels, priority resolution, the `Delta` latch, read accessors | cases 19, 22, 23; retires `KeyboardCameraController` |
+| **6** | `InputTriggerDirection` over coordinates, with threshold and hysteresis | case 9 |
+| **7** | `BlockAll` suppression across dispatch and reads; un-suppression re-entry | cases 14, 17 |
+| **8** | `InputMapSerializationAdapter` + `InputRecorder` | case 24 |
+| **9** | Migrate consumers (below) | existing specs stay green |
+| **10** | `ism/dsl/` — the §13 compiler and `stringify` | round-trip: `compile(stringify(t))` equals `t` |
+
+### 14.1 Consumers
+
+1. **`EditorKeyMap`** — **blocked, not retired.** The engine's `KeyboardDevice` is mounted on
+   `viewStack.el` (`Engine.js:367`) and `Editor.js:563` pushes the entire editor GUI into that same stack, so
+   an editor map would see keys typed into panel text fields — `x` would delete the selected entities, and
+   `preventDefault` would swallow the keystroke. The ISM has no DOM awareness to express the old gate (§6.3),
+   so retiring this needs a design addition. See the implementation plan §5.1. Four behaviours would have to be
+   re-provided in any case, because none of them is in the ISM:
+   * **Focus gating.** `isViewFocused` (`EditorKeyMap.js:12-31`) suppresses all editor bindings when focus is
+     outside the game view. In the ISM this depends on which element the editor's `KeyboardDevice` is mounted
+     on. With bare-key bindings like `x` = delete, getting it wrong is destructive — verify before landing.
+   * **Autorepeat.** Holding `Ctrl+Z` currently repeat-undoes; it will not (§5.5). Decide per action whether
+     that is a loss or a fix.
+   * **`stopPropagation()`** on handled chords — currently prevents the event reaching other listeners.
+   * **The unconditional forward to the active tool** (`EditorKeyMap.js:175-180`), which `Tool.handleKeyboardEvent`
+     relies on: each tool gets its own `InputMap` on its activation entity, at a higher `order`.
+2. **`KeyboardCameraController`** — retired by §3.3, not ported. Carry the `'user-input'` event (§11).
+3. **`Input` / `InputSystem`** — **done.** All five consumers moved and both are `@deprecated`.
+   `OverlayPageGUI` (escape), `CombatInteractionController` (p, escape) and two harnesses were straight
+   translations. `StoryManager` was a split: it bound both a tap and the space bar to one action, and only
+   the space bar moved. A tap is not a button press (§1.1) — translating it would change advance-on-release
+   to advance-on-press and fire at the start of every drag — so the tap kept a small `InputController`, which
+   is the decision the earlier revision of this section left open.
+4. **`InputController` keyboard bindings** — **not started.** The keyboard subset moves; `priority` becomes
+   `order`, `exclusive` becomes `InputOcclusion.BlockMatched`. Gesture bindings stay put, which for
+   `StrategyInteractionController` means most of the file. This is where escape arbitration finally bites
+   (plan §5.4) and where `KeyboardCameraController`'s `'user-input'` entity subtlety has to be handled.
+5. **`components/InputBinding.js`** (`{path, listener, …}`) is orphaned only when `InputController` finally
+   goes, which is not in this program.
+
+### 14.2 A naming collision to plan around
+
+*(Resolved: the new record lives at `ism/map/InputBinding.js`, so the two never shared a filename and the old
+one kept its path and its importer. What follows is the problem as it stood.)*
+
+Phase 1 introduces `InputBinding` in `ism/`, and `ism/InputBinding.js` already exists as the old
+`{path, event}` record imported by [`Input.js:3`](../components/Input.js). The old file must survive until
+`Input` is retired (phase 9), so the two cannot share a filename. Land the new one as `ism/InputBinding.js`
+only after the old is deleted; until then it lives beside its siblings under a transitional name, or `Input`
+is repointed at a copy under `components/`.
+
+---
+
+## 15. Explicitly not doing
+
+* **Pointer gestures** — tap, drag, move, wheel-as-gesture, pinch. §1.1, with the binding counts. Revision 2
+  claimed "nothing in the codebase binds pinch today"; that was false —
+  `StrategyInteractionController.js:437,447` binds `pinchStart` and `pinch`, and it is also the largest
+  migration target.
+* **Buffering input to a frame boundary.** §2. Revision 1 did, and it bought nothing eager evaluation does not
+  also provide.
+* **Discriminating tap from hold on one switch.** §5.5 — it requires withholding the short action, which is the
+  buffering above. Accepted as a cost.
+* **Key autorepeat.** §5.5 — not observable through `InputDeviceSwitch` at all.
+* **Keeping string paths.** `resolvePath` throws where it should resolve and cannot express two sources at once;
+  `GAMEPAD_API_PROPOSAL.md §5` says not to grow it.
+* **A trigger class per gesture pattern.** Double-tap is a two-step sequence with a short window; long-press is
+  `InputTriggerHold`.
+* **Dead zones, sensitivity or response curves on analog output.** §3.3. The direction threshold and hysteresis
+  in §3.4 are not exceptions: producing a boolean from a coordinate cannot be done without them.
+* **A `Started` / `Performed` / `Canceled` phase enum, or an `edge` field.** §4.1 — every trigger is a
+  predicate and every binding fires on its rising edge.
+* **A per-binding `consume` flag.** Occlusion is a property of a *context*, not of one binding, and a boolean
+  per binding makes behaviour depend on declaration order.
+* **Named layers.** §7 — a stack is addressed by index.
+* **Behaviour in the component.** No function references, no script names, no serialized handler ids (§6.1).
+* **DOM-target awareness in `InputActionEvent`.** §6.3 — it belongs with the deferred gesture work.
+* **Strict sequence rejection**, and **button buffering**. §5.5, both deferred with known shapes.
+* **A generic input node graph.** The trigger classes are already a small algebra; the DSL (§13) is the cheaper
+  first step over it.
+
+---
+
+## 16. Resolved decisions
+
+1. **Analog channels are N-dimensional "coordinates", not axes** — §3.3. `WheelEvent` has three components and
+   `PointerDevice` surfaces all three. `kind` (`Absolute` / `Delta` / `Normalized`) carries the verb.
+2. **`order` stays author-set** — §8. A GUI-hierarchy-derived order would need no hand-picked numbers but would
+   couple input arbitration to that hierarchy.
+3. **No sensitivity in bindings** — §3.3. A rebinding UI serializes *which* channel drives an action, never how
+   twitchy it is.
+4. **Layers are an index-addressed stack, with no names** — §7.
+5. **Evaluation is eager, on the edge** — §2. No buffer, no added frame. The costs — re-entrant dispatch,
+   arrival-ordering, the §4.6 chord condition, the §5.5 tap-versus-hold limit, and the §3.3 `Delta` split
+   between eager and tick-time readers — are stated where they arise rather than hidden.
+6. **The trigger DSL is planned, specified and deferred** — §13, phase 10.
+7. **Pointer gestures are out of scope** — §1.1. `InputController` is reduced, not retired.
+8. **`SimpleStateMachine` is not used** — §5.6. The matcher is a path, not a graph; the class becomes the right
+   tool if sequences ever branch.
+
+---
+
+## 17. What changed in revision 3, and why
+
+An adversarial review of revision 2 found three defects that made it unimplementable, plus a set of false
+claims about the existing codebase. Everything below was verified against source before being changed.
+
+### Defects
+
+| | Was | Now |
+|---|---|---|
+| **Sequence matcher** | Reset paths (window expiry, post-fire) did not re-establish the entry snapshot, and the advance step indexed `steps[N]`. Holding `A` and mashing `B` machine-gunned `[A,B]` off one `A` press; an expiry with the first key held spuriously advanced with no edge. | Every entry routes through `enter(k, held, now)` (§5.1), which snapshots and never indexes `steps[N]`. Cases 6 and 7. |
+| **Occlusion** | A per-edge `consumed` set gating *firing* only. `isActive` and coordinate reads are polled, so `BlockAll` could not stop them — a pause menu left the camera panning, the exact bug §8 claimed to prevent. Both occlusion tests passed anyway, testing only dispatch. | Two scopes: `BlockMatched` stays dynamic and dispatch-only; `BlockAll` sets a static per-map `suppressed` covering dispatch *and* reads (§8.2). Cases 14, 15, 17. |
+| **Coordinate bindings** | `bindCoordinate()` existed with nowhere to store its result, and §10's channel encoding was unreachable from the format root. No map with a coordinate could serialize. `bindCoordinate` was also called twice for one action in §11 with no defined meaning. | `InputCoordinateBinding` on the layer, reachable in the format, with priority resolution (§9.1). Case 19. |
+
+### Corrections
+
+* **Charge inputs failed.** The step window ran from the advance, so any charge longer than
+  `duration + step_timeout` expired before the flick. It now measures time since the previous step *stopped*
+  holding (§5.2). Case 10.
+* **`satisfied` initialisation was unspecified**, and zero-init makes `Release(Chord(a,b))` fire before the
+  chord exists. Now snapshotted at compile (§4.5). Case 12.
+* **`order` was `uint8`-biased**, range `[-128,127]`, while §11's own modal used `1000`. Now `int16` (§10).
+* **`MouseButtons` cited the wrong standard.** The `MouseEvent.buttons` *bitmask* order is left/right/middle;
+  `PointerDevice.buttons[]` is indexed by `MouseEvent.button` *ordinal*. Following the citation would have
+  fired every right-click binding on the middle button, into saved data (§3.1).
+* **`Release(sequence)` was claimed to mean "stopped matching".** It cannot — a sequence's `test` is a pulse
+  (§4.3).
+* **Specificity did not rank `Hold` / `Release` / `Direction`**, so they fell through to declaration order —
+  the accident §4.6 claims to eliminate (§4.6).
+* **Chord-vs-subset arbitration was stated unconditionally.** It holds only when the modifier arrives first
+  (§4.6). Case 3 now tests both orders.
+* **The `Delta` "same value for every reader" invariant** was a leftover from the buffered design and is false
+  under eager dispatch (§3.3).
+* **Re-entrancy covered only structural change.** Nested edges and mid-dispatch binding edits are now specified
+  (§2.3).
+* **The recorder captured only switch edges**, so no map with a coordinate or a hold could replay. It now
+  records coordinate samples and per-frame `dt` (§2.5).
+* **Unregistered devices had no defined behaviour** (§3.1).
+* **`EditorKeyMap` and `KeyboardCameraController` deletions dropped real behaviour** — focus gating,
+  autorepeat, `stopPropagation`, the tool forward, the `'user-input'` event — now inventoried (§14.1).
+* **Counts and claims:** `KeyboardCameraController` has 16 `bind()` calls, not eight; the `InputController`
+  path-string count flattered a migration that is mostly gestures (§1.1); `InputControllerSystem`'s `deferred`
+  array is dead code, not a working mitigation (§2.3); "`InputSystem` cannot be tested without a DOM element"
+  was overstated (§12.1); "no new numbering to keep in sync" was false (§10); `PointerDevice`'s wheel reports
+  `sign()`, so a `Delta` wheel channel counts ticks rather than distance (§3.3).