@woosh/meep-engine 2.170.0 → 3.0.1

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

@@ -0,0 +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).