@woosh/meep-engine 3.60.3 → 3.60.5

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

@@ -1,627 +0,0 @@
-# ISM — implementation plan
-
-Companion to [`ISM_DESIGN.md`](ISM_DESIGN.md). The design says *what* is built and why; this says *in what
-order*, *how it is proved*, and *what happens to the systems it replaces*.
-
----
-
-## 0. Definition of done
-
-1. **DONE** — `InputMap` + `InputMapSystem` are registered in `makeMirEngineConfig` and carry real bindings
-   in the game.
-2. **DONE** — `Input` and `InputSystem` are `@deprecated` in JSDoc, with every consumer migrated (§5.4).
-3. **HALF** — `InputController` / `InputControllerSystem` carry the JSDoc note narrowing them to pointer
-   gestures and DOM-gated pointer buttons. Their **keyboard** bindings have NOT moved yet (§5.5).
-   Pointer-button bindings stay wherever an `event.target` gate or a position payload is involved — design
-   §6.3 makes those untranslatable, and §5.5's table marks each one.
-4. **NOT STARTED** — `KeyboardCameraController` is to be deleted, and it has two consumers, not one (§5.3).
-   **`EditorKeyMap` is not** deleted — see §5.1; retiring it needs a design addition this program does not
-   contain.
-5. **DONE** — `npm test` from `H:/git/moh` is green: 1968 files, 12,635 tests.
-
-Out of scope, per design §1.1 and design §13.4: pointer gestures, and the trigger DSL.
-
----
-
-## 0.5 Status
-
-Updated as phases land, so this document says what is true rather than what was intended.
-
-| Phase | State | Notes |
-|---|---|---|
-| P1 value types and trigger algebra | **landed** | all nine trigger classes, `InputSourceTable`, `InputMap`/`InputLayer`/`InputBinding`/`InputCoordinateBinding` |
-| P2 devices and adapters | **landed** | four adapters; `ManualInputDevice`. No jsdom adapter spec yet — the hardware adapters are unexercised outside a browser |
-| P3 eager edge path | **landed** | dispatch, cascade, `BlockMatched`, `isActive`, re-entrancy deferral |
-| P4 sequences and holds | **landed** | 11 behavioural specs incl. the charge input |
-| P5 coordinates | **partial** | `Switches` and device channels, priority resolution, the latch. `InputCoordinateCompose` not built; pointer `move`/`wheel` untested outside a browser |
-| P6 directions | **not started** | `InputDirection` enum exists; `InputTriggerDirection` does not |
-| P7 `BlockAll` suppression | **landed** | 12 specs incl. un-suppression re-entry |
-| P8 serialization and recording | **not started** | `InputMap.serializable` is deliberately `false`; `InputMapSerializationAdapter` and `InputRecorder` are designed, not built |
-| P9 consumer migration | **partial** | registered in `makeMirEngineConfig`; all five `Input` consumers migrated and `Input`/`InputSystem` deprecated. `InputController`'s keyboard bindings have not moved |
-| P10 DSL | **not started** | deferred by design |
-
-222 specs over the input package; 859 with `ecs` included.
-
-**Verified in a browser** — `prototypeInputMap.js`, loaded with
-`?entry=/src/mir-engine/meep/src/engine/input/ecs/ism/prototypeInputMap.js`, boots a real engine through
-`EngineHarness`, registers the three hardware adapters, and drives real DOM `KeyboardEvent`/`PointerEvent`/
-`WheelEvent`s at the element the engine mounts its devices on. Ten checks, all passing, covering what no node
-spec can reach:
-
-* a real keydown dispatching through the real `KeyboardDevice`;
-* browser-default suppression following the bound key set — a bound key is prevented, an unbound one is not,
-  and unlinking the map stops the suppression;
-* chord arbitration, a pointer button, and a sequence completing across real key events;
-* a switch-composed coordinate read from real keys;
-* **the per-frame latch on a relative channel**, which has no vehicle at all in node: three wheel events
-  between frames read 0 before the tick, 3 after it, 3 again for a second reader in the same frame, and 0 on
-  the next — checked with the raw numbers, not just a boolean;
-* a `BlockAll` map zeroing a lower map's coordinate read, and the read returning to 1 once the modal closes.
-
-The last two were checked against a negative control - without the modal the same read is 1, so the check is
-not vacuous. No console errors during the run.
-
-### Round two — reinvention audit
-
-The sponsor asked whether the subsystem re-implements anything meep already provides. Findings, with what
-was done:
-
-| Hand-rolled | meep already has | Outcome |
-|---|---|---|
-| `((r * 31) ^ h) \| 0` at 13 sites, plus `Math.round(x * 1000)` for floats | [`hash_mix2`](../../../../core/math/hash/hash_mix2.js), [`computeHashFloat`](../../../../core/primitives/numbers/computeHashFloat.js) | **Replaced.** `hash_mix2` exists precisely to stop this drift — its own docblock says the spelling is unified there "so the truncation cannot be forgotten". A third spelling was invented in a codebase that had already unified two. |
-| Plain arrays for layers, bindings, triggers, channels | [`List`](../../../../core/collection/list/List.js) | **Kept, now documented** — amendment 6 below. The deviation was undocumented, and its substitute for `List`'s change signals is where the `popLayer` defect lived. |
-| `InputSourceTable`'s nested `Map<string, Map<number, number>>` | [`HashMap`](../../../../core/collection/map/HashMap.js), keyed on `hash()`/`equals()` | **Kept.** The aggregate — dense first-seen index, reverse lookup, indices never recycled so recordings stay readable — has no core equivalent. Worth knowing that nothing in production calls `InputSource.hash()` as a result. |
-| `SwitchSubscription` + reference counting | [`SignalBinding`](../../../../core/events/signal/SignalBinding.js) | **Kept, justified.** The record *is* the allocation-free dispatch context; `SignalBinding` could only replace the add/remove pair, at two more objects per switch, and nothing in core does subscription refcounting. |
-| The `#deferred` closure queue | `core/process/task/*` | **Kept.** Task machinery is long-running cooperative scheduling — wrong shape for "apply this at the end of the current edge". |
-| The sequence matcher, rather than [`SimpleStateMachine`](../../../../core/fsm/simple/SimpleStateMachine.js) | — | **Kept, and the reasoning in design §5.6 verified.** One argument was missed and strengthens it: `advance()` needs a per-state selector registered on the description, which the rising-edge matcher does not fit at all. |
-| `CODE_TO_NAME` reverse-enum table | `objectKeyByValue` | **Kept.** Precomputed O(1) against a per-subscribe linear scan, for four lines. |
-
-Reused rather than reinvented, for balance: `InputDeviceSwitch`, `BitSet`, `Signal` context dispatch,
-`assert.*` including `assert.enum`, `computeStringHash`, `Vector1/2/3`, `gamepad_write_dpad_vector`,
-`GamepadDevice.main`, and the module-static scratch convention.
-
-### Defects found by review, and closed
-
-All six were reproduced by the adversarial review of the implementation, and all six now have a regression
-spec. Recorded because the reasoning is worth keeping, not because anything is outstanding.
-
-1. **Recompiling one map rebuilt every map**, discarding all their matcher state — so with several contexts
-   live, a `bind()` anywhere reset everyone's half-matched sequences. Recompilation is now scoped to the maps
-   whose revision actually changed.
-2. **Nested edges coalesced.** `handleEdge` applied the state change eagerly but deferred the evaluation,
-   which then re-read live state — so a press and release issued from inside an action handler cancelled out
-   and fired nothing. That is the scripted-input case `ManualInputDevice` exists to serve. The state change
-   now travels with its deferred evaluation.
-3. **A throwing handler stranded its queued work.** The exception propagates out of the walk and is swallowed
-   further up by `Signal`, so a drain placed after the `try/finally` never ran. A map linked from such a
-   handler stayed dead permanently, because the deferred link was itself what would have subscribed to its
-   switches — there was no later edge to recover on. The drain now lives inside the `finally`.
-4. **A mid-dispatch `bind()` landed a tick late** rather than at the end of the current edge. Recompilation is
-   now checked in the same `finally`.
-5. **One `InputMap` on two entities** silently broke reads — the second link hijacked the single program slot,
-   and unlinking either nulled it. Asserted at link, with the reasoning on the assert.
-6. **`registerDevice` was not deferral-guarded**, so calling it from a handler recompiled mid-walk. Now
-   deferred like `link` and `unlink`.
-
----
-
-## 1. Testability is a design constraint, not a phase
-
-meep's position is black-box only — no call counts, no private-path assertions, no mocks, no spies. That is not
-something to bolt on at the end: it dictates three structural decisions, taken here rather than discovered
-later.
-
-### 1.1 The driving seam is a real device, not a test double
-
-Every test needs to make a key go down. The obvious route — construct `KeyboardDevice` and dispatch synthetic
-DOM `KeyboardEvent`s — drags jsdom into every spec and tests the browser rather than the ISM.
-
-Instead, **`ManualInputDevice` ships as production code**: a device whose switches and coordinates are driven
-by method call rather than by hardware.
-
-```js
-export class ManualInputDevice {
-    /** @type {InputDeviceSwitch[]} */
-    switches = [];
-    /** @param {number} code @returns {InputDeviceSwitch} */
-    getSwitch(code) { }
-    /** @param {number} code @param {...number} components */
-    setCoordinate(code, ...components) { }
-}
-```
-
-It is not test scaffolding. It is the device behind three real features the design already names: **replay**
-(design §2.5 — a recorded trace is fed back through a `ManualInputDevice`), **scripted demos and tutorials**,
-and **AI- or network-driven input**. Tests use it because it is the real thing, which is exactly the property
-that makes them black-box.
-
-Its switches are real `InputDeviceSwitch` instances, so the ISM cannot tell it from `KeyboardDevice`, and the
-edge-detection and idempotence semantics under test are the production ones.
-
-Consequence for coverage: the three hardware adapters (`Keyboard`, `Pointer`, `Gamepad`) are thin — they map a
-code to a switch the device already owns. Their specs are small and jsdom-scoped (`@vitest-environment jsdom`,
-as `GamepadDevice.spec.js` already does); everything about *binding semantics* is tested through
-`ManualInputDevice` in plain node.
-
-### 1.2 Time is advanced by `update(dt)`, never read from a clock
-
-Sequence windows and hold durations need a clock. If the system calls `performance.now()`, no spec can test a
-timeout without faking time — which is a mock by another name.
-
-**`InputMapSystem` owns `#time`, advanced only by `update(dt)`.** Edges arriving between ticks are stamped with
-the current `#time`, so every edge in a frame shares a timestamp. A spec drives time by calling
-`system.update(0.1)`, with no clock anywhere.
-
-Three consequences, stated because they are real:
-
-* **Window resolution is one frame.** No window in the design is sub-frame — the tightest is a
-  fighting-game 0.15 s, or 9 frames at 60 Hz — so nothing is lost.
-* **Windows are in simulation time, not real time.** `EntityManager` passes the ticker's scaled delta, so at
-  0.25× speed a 0.2 s window lasts 0.8 s of wall clock, and a paused game freezes all windows. This
-  **contradicts design §4.4**, which specified real time; §7 records the amendment and the argument. Slow
-  motion stretching a reaction window is defensible; a testable system is not negotiable.
-* **`InputActionEvent.time` is simulation time since system startup**, and the recorder (P8) records `dt`
-  per frame, which is what makes replay exact.
-
-### 1.3 Everything observable is already observable
-
-No spec needs to reach inside. The full observation surface is the design's public one:
-
-| To observe | Use |
-|---|---|
-| an action fired | a real listener on a real `EntityComponentDataset` pushing names into an array |
-| level state | `map.isActive(action)` |
-| analog state | `map.axis2(v, action)` / `map.coordinate(...)` |
-| occlusion | the two above, on a lower map |
-| serialization | a real `BinaryBuffer`, round-tripped, then replayed against a recorded trace |
-
-A listener that appends to an array is a plain function, not a spy: nothing asserts *how many times* the ISM
-called anything, only which actions came out and in what order. Where existing specs in this package reach for
-`vi.fn()` (`GamepadDevice.spec.js`), these do not.
-
-### 1.4 What is deliberately not asserted
-
-No spec inspects `InputMapProgram`, the intern table, `#held`, matcher slots, or trigger `satisfied` flags. If
-a behaviour cannot be reached through §1.3's surface, either it does not matter or the surface is wrong —
-both of which are answers, and neither is "add a white-box assertion".
-
----
-
-## 2. File layout
-
-New code lives under `engine/input/ecs/ism/`, except three enums that are facts about devices and belong with
-them.
-
-```
-engine/input/devices/
-  mouse/MouseButtons.js                     new enum, MouseEvent.button ordinals
-  PointerCoordinates.js                     new enum: position, move, wheel
-  gamepad/GamepadCoordinates.js             new enum: left_stick, right_stick, dpad
-  ManualInputDevice.js                      section 1.1 - programmatically driven device
-
-engine/input/ecs/ism/
-  InputBinding.js                           EXISTING, old {path,event}. Untouched until 5.3.
-
-  InputSource.js                            {device, code}
-  InputCoordinateSource.js                  {device, code, dimensions, kind}
-  InputCoordinateKind.js                    Absolute | Delta | Normalized
-  InputDirection.js                         8 octants
-  InputOcclusion.js                         Pass | BlockMatched | BlockAll
-  InputActionEvent.js
-
-  device/
-    InputDeviceAdapter.js                   base
-    KeyboardInputDeviceAdapter.js
-    PointerInputDeviceAdapter.js
-    GamepadInputDeviceAdapter.js
-    ManualInputDeviceAdapter.js
-
-  trigger/
-    InputTrigger.js                         base: test(held), collectSources(out), satisfied
-    InputTriggerType.js
-    InputTriggerSwitch.js                   leaf over one InputSource
-    InputTriggerKey.js                      typed constructor
-    InputTriggerMouseButton.js              typed constructor
-    InputTriggerGamepadButton.js            typed constructor
-    InputTriggerDirection.js                leaf over a coordinate channel
-    InputTriggerChord.js                    AND
-    InputTriggerRelease.js                  NOT
-    InputTriggerHold.js                     child held for >= duration
-    InputTriggerSequence.js                 ordered steps + window
-
-  coordinate/
-    InputCoordinateChannel.js               base: read(result, offset), dimensions, collectSources
-    InputCoordinateChannelType.js
-    InputCoordinateGamepad.js
-    InputCoordinatePointer.js
-    InputCoordinateSwitches.js
-    InputCoordinateCompose.js
-
-  map/
-    InputMap.js                             the component
-    InputLayer.js
-    InputBinding.js                         NEW {action, triggers} - the collision, resolved by directory
-    InputCoordinateBinding.js               {action, channels}
-
-  InputMapSystem.js
-  InputMapProgram.js                        compiled form, internal
-  InputMapSerializationAdapter.js
-  InputRecorder.js
-```
-
-Placing the new `InputBinding` under `map/` resolves design section 14.2's filename collision outright: the old
-`ism/InputBinding.js` keeps its path and its importer (`components/Input.js`) until 5.3 deletes both.
-
-**No `.d.ts` files.** JSDoc only, per the package's standing position.
-
----
-
-## 3. Phases
-
-Each phase lands with its specs green before the next starts. Phase numbers match design section 14.
-
-### P1 — Value types and the trigger algebra
-
-`InputSource`, `InputCoordinateSource`, the enums, `InputTrigger` and the nine trigger classes, `InputMap` /
-`InputLayer` / `InputBinding` / `InputCoordinateBinding`.
-
-Triggers are pure here: `test(held)` takes a `BitSet` of interned indices, and interning belongs to the program
-(P3). To keep P1 testable alone, `collectSources` yields `InputSource` values and each leaf carries an `index`
-the program fills in — so a P1 spec builds a `BitSet` by hand and calls `test`. That is not white-box:
-`test(held)` is the published interface (design 4.1).
-
-**Gate — `trigger.spec.js`, `InputMap.spec.js`:**
-* `equals` / `hash` agree with structural equality on every trigger type, including nested.
-* `Chord.test` is AND; `Release.test` is NOT; both over held-sets built by hand.
-* `collectSources` returns every leaf source of a nested tree, deduplicated.
-* Layer cascade: `bind` on layer 0, `pushLayer().bind` on the same action; the resolved table has the top's
-  triggers and not the base's. Two triggers in one layer both survive.
-* `unbind` on a top layer removes an inherited binding.
-* Binding one action as both a trigger action and a coordinate action is rejected.
-
-### P2 — Devices and adapters
-
-The three enums, `ManualInputDevice`, `InputDeviceAdapter` and the four adapters.
-
-**Gate — `InputDeviceAdapter.spec.js` (node), `adapters.dom.spec.js` (jsdom):**
-* Totality: for every code in `KeyCodes` / `MouseButtons` / `GamepadButtons`, `getSwitch` returns a switch with
-  no hardware present, and it reads up.
-* `GamepadInputDeviceAdapter` over a `GamepadDevice` with nothing connected resolves every standard button.
-* `ManualInputDevice` switches are real: press is idempotent, release after press fires once, `is_down` tracks.
-* Coordinate dimensions: pointer `wheel` is 3, `position` is 2, gamepad sticks are 2.
-
-### P3 — The system: the eager edge path
-
-`InputMapSystem`, `InputMapProgram`, interning, compile, cascade resolution, `BlockMatched`, ECS dispatch,
-`isActive`. Switch / chord / release triggers only.
-
-**Gate — `InputMapSystem.spec.js`:**
-* An action fires **before any `update()` is called** — the latency requirement, as an executable test.
-* Press and release inside one frame both fire; two presses dispatch in press order.
-* `Ctrl` then `Z` fires only `undo`; `Z` then `Ctrl` fires both, in that order — design 4.6's stated
-  condition, tested in both directions so the asymmetry is pinned rather than accidental.
-* `Release(Chord(a,b))` does not fire on the first edge touching `a` — the `satisfied` initialisation.
-* A map linked while a key is already held does not fire that key's press trigger.
-* A listener that removes its own entity, and one that rebinds its own map, both leave the walk intact and the
-  next edge behaving.
-* `BlockMatched` above blocks a shared switch below and leaves an unrelated one alone.
-* `unlink` with a key held leaves nothing active and dispatches nothing further.
-
-### P4 — Sequences and holds
-
-`InputTriggerSequence`, `InputTriggerHold`, matcher slots, synthetic maturity edges, window refresh and expiry.
-
-**Gate — `InputTriggerSequence.spec.js`, `InputTriggerHold.spec.js`:**
-* One long press of `A` does not satisfy both steps of `[A, A]`.
-* `[A,A,B]` fires on `A A A B`.
-* Holding `A` and tapping `B` twice fires `[A,B]` **once** — the post-fire re-entry.
-* A window expiry with the first step's key still held does not spuriously advance — the stale-snapshot bug.
-* `Ctrl+Shift+A > B` fires whether or not the modifiers are released first.
-* The window refreshes while the previous step still holds and expires only after it stops.
-* A hold matures on the tick that crosses its duration, not before; releasing early cancels it.
-* Charge — `[Hold(left, 2.0), right]` — fires after a 10 s hold, and expires on a return to neutral.
-
-### P5 — Coordinates
-
-The channel classes, priority resolution, `Delta` accumulation and frame reset, the read accessors.
-
-**Gate — `InputCoordinate.spec.js`:**
-* `Switches` composes a 2-D channel from four switch triggers; both directions held reads zero.
-* A 3-D channel round-trips all three components.
-* Priority: an action bound to a gamepad stick and a switch channel reads the stick while deflected and the
-  switches at rest.
-* `Delta` accumulates across two edges within a frame and reads zero after the tick.
-
-### P6 — Directions
-
-`InputTriggerDirection`: threshold, hysteresis, exclusivity, release-before-press transition order.
-
-**Gate — `InputTriggerDirection.spec.js`:**
-* Exactly one of the eight directions is active for any deflected coordinate; none below threshold.
-* A transition releases the old direction before pressing the new one — observable as the ordering of two
-  actions bound to those two directions.
-* `down, down-right, right` over a coordinate fires a quarter-circle sequence; **the same sequence over raw
-  d-pad buttons does not** — the exclusivity claim, tested in both directions, because it is the one
-  load-bearing assumption in design 5.4 the other cases would not catch.
-* Hysteresis: a coordinate oscillating inside the band does not chatter.
-
-### P7 — `BlockAll` suppression
-
-Static per-map `suppressed`, recomputed on map-set / `order` / `occlusion` change; un-suppression re-entry.
-
-**Gate — `InputOcclusion.spec.js`:**
-* A `BlockAll` map above zeroes a lower map's `axis2` **and** `isActive`, not only its dispatch — the defect
-  design revision 2 shipped.
-* A `BlockMatched` map above does **not** zero them.
-* A modal-consumed keystroke does not advance a lower map's sequence.
-* Un-suppressing re-enters sequences at 0: one half-matched before suppression does not complete on a single
-  further step afterwards.
-* Suppression follows `order` changes made after link.
-
-### P8 — Serialization and recording
-
-`InputMapSerializationAdapter`, `InputRecorder`.
-
-**Gate — `InputMapSerializationAdapter.spec.js`:**
-* Round-trip of a map with every trigger type nested at least two deep, both binding kinds, three layers and
-  two devices; `equals` holds.
-* `order = 1000` survives — the `int16` fix.
-* A recorded trace replayed through a `ManualInputDevice` against the deserialized map produces the same
-  dispatch sequence as the original. This is the end-to-end determinism gate, and the reason
-  `ManualInputDevice` is production code rather than a fixture.
-
----
-
-## 4. Deprecation
-
-**Applied.** JSDoc only — no runtime warnings, no shims, no behaviour change.
-
-| Target | Marking |
-|---|---|
-| [`Input`](../components/Input.js) | `@deprecated` — use `InputMap` |
-| [`InputSystem`](../systems/InputSystem.js) | `@deprecated` — use `InputMapSystem` |
-| [`ism/InputBinding.js`](InputBinding.js) | `@deprecated` — internal to `Input` |
-| [`InputController`](../components/InputController.js) | **Not** `@deprecated`. A JSDoc note narrowing it: pointer gestures only; keyboard and mouse-button bindings belong in `InputMap`. |
-| [`InputControllerSystem`](../systems/InputControllerSystem.js) | Same note. Its existing `Prefer to use InputSystem instead` line is wrong once `InputSystem` is deprecated and is replaced. |
-| [`components/InputBinding.js`](../components/InputBinding.js) | Unchanged — still `InputController`'s record. |
-
-`InputController` is deliberately **not** deprecated: it still owns every gesture binding (design section 1.1),
-and marking a class deprecated while it remains the only way to do something is a lie that the next reader
-has to disprove.
-
-Deletion of `Input` / `InputSystem` / `ism/InputBinding.js` is **not** in this program. Nothing consumes them
-any more, so nothing blocks it technically — they stay because an unreferenced export is public surface in
-this package, and removing one is a separate decision from replacing it.
-
----
-
-## 5. Consumer migration
-
-> Rewritten after the adversarial review. Several claims in the first draft did not survive contact with the
-> source; section 8 lists what changed and why.
-
-### 5.1 `EditorKeyMap` — BLOCKED, and not by a small thing
-
-The first draft claimed the editor's focus gate was "preserved by construction". **It is inverted.**
-
-Today `EditorKeyMap.attach()` listens on **`window`** (`EditorKeyMap.js:71`) and gates every handler with
-`isViewFocused` (`:12-31`), which passes when the game view is a descendant of `document.activeElement`. So
-hotkeys work with focus on `body`, and are suppressed while focus is in an editor text field.
-
-The ISM would instead see keys through the engine's `KeyboardDevice`, mounted on `this.viewStack.el`
-(`Engine.js:367`) — and `Editor.js:563` pushes **the entire editor GUI into that same view stack**. Two
-failures follow, in opposite directions:
-
-* Every editor panel, tree and **text input is inside the listening element**, so a keydown typed into a field
-  reaches the device. `x` would delete the selected entities. Worse, `KeyboardDevice.js:112-118` calls
-  `preventDefault()` for any bound key that has handlers, so typing `x` into a field would not even insert the
-  character.
-* With focus on `body` — page load, or after a click that blurs — events target `body` and never reach a
-  listener on a descendant, so every editor hotkey would be dead until the canvas is clicked.
-
-The ISM has no DOM awareness to express the old gate (design 6.3), so this is **unplanned design work, not a
-verification step**. Options, none free:
-
-1. A second `KeyboardDevice` mounted on `gameView.el` with its own adapter under a distinct device id,
-   driving only the editor and tool maps. Approximates today's gate; costs a device id in the binding format
-   and a second `preventDefault` surface.
-2. A focus predicate on `InputMap`, evaluated before dispatch. Cheap, but puts a DOM concept into a component
-   the design deliberately keeps DOM-free.
-3. Leave `EditorKeyMap` alone.
-
-**This program takes option 3.** The editor migration is deferred to its own change, where 1 or 2 can be
-designed properly. `EditorKeyMap` is therefore not deleted, and the definition of done says so.
-
-### 5.2 Game input under the editor — a lever the ISM does not have
-
-`Editor.js:528` disables `InputControllerSystem` on attach, so no game binding fires while editing. That lever
-does not reach the ISM: `disableSystem` gates `update()`, and ISM dispatch is signal-driven and never passes
-through `update()`.
-
-So the moment 5.5 moves the strategy hotkeys, `i` would open the game inventory while the editor is open,
-`space` would recentre the game camera, and WASD would pan it.
-
-**The editor's own map must be `InputOcclusion.BlockAll`**, not the default. Tool maps sit above it and are
-unaffected; everything below goes inert, which is what `disableSystem` did. Worth stating loudly, because the
-design's own section 11 editor example uses the default.
-
-### 5.3 `KeyboardCameraController` — deleted, two consumers not one
-
-Replaced by a coordinate binding plus a `Script`. Call sites:
-
-| Consumer | Note |
-|---|---|
-| `StrategyInteractionController.js:581` | the game's use |
-| `EngineHarness.js:29,340` | **engine package**, constructed whenever `cameraController: true`, the default. Missed by the first draft; deleting the file without this is an import-time break for every browser harness. |
-
-Two details the first draft got wrong:
-
-* **Eight keys, not four.** `registerToggle` binds arrows *and* WASD (`:64-67`). The design's section 11
-  example binds only `a/d/w/s` and silently drops arrow-key panning.
-* **`'user-input'` goes to the camera entity**, not the map's. It is sent on `cameraController.entity`
-  (`:54`), and its consumers are `WaitForEventBehavior`s targeting `activeCamera.entity`
-  (`CameraFocusEntityStoryActionProcessor.js:44`) — the interrupt-camera-focus-on-input mechanic. An
-  `InputMap` action dispatches on the map's own entity, so the map must be built **on the camera entity**, or
-  the event re-forwarded explicitly. Getting this wrong stops keyboard pan cancelling story camera focus, and
-  the surviving pointer path would keep working and mask it.
-
-### 5.4 `Input` / `InputSystem` consumers — DONE
-
-Five, all of which moved:
-
-| File | Binding | Move |
-|---|---|---|
-| `OverlayPageGUI.js:233` | `keyboard/keys/escape/down` | direct, but see the arbitration note |
-| `CombatInteractionController.js:27,63` | `keyboard/keys/p/down`, `escape/down` | direct |
-| `StoryManager.js:422` | `keyboard/keys/space/down` | direct |
-| `StoryManager.js:421` | `pointer/on/tap` | **stays** on a small `InputController` — a tap is a gesture (fires on release, gated on 10 px and 1 s, `PointerDevice.js:20-40`), and translating it to a button press would advance dialogue on press and fire at the start of every drag |
-| `test/testAnimationGraph.js`, `test/testTalentPunisher.js` | keyboard | direct |
-
-**Escape arbitration, as it turned out.** `StrategyInteractionController`'s `escape` (`:512-517`) is an
-`InputController` binding, not an `Input` one, so it did **not** move in this slice — and the two systems do
-not see each other, so both still fire exactly as before. The conflict is real but deferred: it arrives when
-the scene moves. `OverlayPageGUI`'s map is already `order = 10` against the scene's implicit `0`, so the page
-that is open wins the key when that day comes.
-
-Once these move, nothing consumes `Input`. It is still **deprecated rather than deleted**, and the reason is
-the standing library policy — unreferenced exports are public surface — not a holdout. The first draft claimed
-a holdout that its own resolution had already removed.
-
-### 5.5 `InputController` keyboard bindings
-
-Keyboard moves; gestures and DOM-gated buttons stay.
-
-| File | Moves to `InputMap` | Stays on `InputController` |
-|---|---|---|
-| `StrategyInteractionController.js` | keyboard pan (5.3), command keys — several are `/up` bindings (`:556-561`), i.e. `InputTriggerRelease` | `drag*`, `move`, `wheel`, `pinch*`, `tap`, **and `pointer/on/down` (`:295-352`)** |
-| `makeOrbitalCameraController.js` | — | `tap`, `down`, `drag`, `wheel` — stays entirely |
-| `CombatInteractionStateMachine.js` | **nothing** — the file has no keyboard bindings; `:123-277` are all pointer. Combat's `p` and `escape` live in `CombatInteractionController.js`, covered by 5.4 | `pointer/on/*` with their `event.target === graphics.domElement` gate |
-| `RadialContextMenu.js` | — | `move`, `up` — stays entirely |
-| `DevelopmentOptions.js:189` | — | `pointer/on/tap` — stays |
-| `editor/tools/v2/prototypeTransformControls.js` | `keyboard/keys/{w,e,r}/down` | — |
-| `prototype_first_person_controller.js` | WASD to one coordinate; space/shift/c become `isActive` reads | `pointer/on/move` |
-| `enableEditor.js:74` | `num_lock` toggle, direct device subscription — case by case | — |
-
-`priority` becomes `order`; `exclusive` becomes `InputOcclusion.BlockMatched`. Both translations are vacuous
-in practice: no shipping code sets either.
-
-### 5.6 Registration
-
-* `makeMirEngineConfig.js` gains `new InputMapSystem([...adapters])`. The **component type registers
-  implicitly** — `addSystem` calls `registerManyComponentTypes(system.referenced_components)`
-  (`EntityManager.js:659`) — so no explicit component registration is needed.
-* The serialization adapter does **not** go here. `EngineConfiguration` has no adapter facility; engine
-  components register in `populateEngineSerializationRegistry.js`, which the game funnels through via
-  `GameBinarySerializationRegistry.js:53`. Only relevant once `InputMap.serializable` is turned on.
-* `EngineHarness.js` has no default system list — its config callback starts empty and `InputControllerSystem`
-  is added lazily (`:441-443`). The ISM follows the same shape.
-
-**Every `InputMap` built by a controller carries `SerializationMetadata.Transient`**, as its `InputController`
-predecessors already do (`StrategyInteractionController.js:575`, `KeyboardCameraController.js:107`). This was
-belt-and-braces while the old components were `serializable = false`; it becomes load-bearing the moment
-`InputMap` serializes — see the JSDoc on `InputMap.serializable`.
-
----
-
-## 6. Risks
-
-| | Risk | Mitigation |
-|---|---|---|
-| 1 | **Game input stays live under the editor** (5.2). Silent, and only visible as the game reacting while someone edits. | Editor map is `BlockAll`; a manual check with the editor open before the strategy hotkeys land. |
-| 2 | **`'user-input'` reach** (5.3). Regression is masked by the surviving pointer path. | Bind on the camera entity; check story camera focus is still interruptible by keyboard pan. |
-| 3 | **Escape arbitration** (5.4). Two handlers become one. | Explicit orders, stated above. |
-| 4 | **A parallel session is working on graphics.** | Every commit stages explicit paths. No `git add -A`, no `git add .`. |
-| 5 | **Three-repo submodule landing** (`moh` to `mir-engine` to `meep`). | Commit bottom-up: `meep`, then `mir-engine`, then `moh`. |
-| 6 | **Simulation-time windows** (1.2). A hold or sequence inside a PAUSE MENU can never mature, because the ticker is paused — and the pause menu is the design's own modal example. | Menus use plain presses. If a menu ever needs a hold, that is the trigger to reconsider 7.1. |
-| 7 | **Behaviour preservation in P9 has no automated gate.** "Existing specs stay green" proves nothing: none of the migrated behaviours has a spec. | Named manual checks per consumer, listed with the migration rather than assumed. |
-
----
-
-## 7. Amendments to the design
-
-1. **Sequence and hold timing is simulation time, advanced by `update(dt)`** — not real time stamped at edge
-   arrival (design 4.4). Testability (1.2): a real-time clock cannot be driven from a spec without faking it.
-   Consequences: one-frame window resolution, windows stretch under slow motion and freeze while paused
-   (risk 6).
-2. **`ManualInputDevice` is production code** (1.1) — the design's "network-driven replay source" is now a
-   named, shipped class.
-3. **The new `InputBinding` lives at `ism/map/InputBinding.js`** (2), resolving design 14.2's collision.
-4. **Relative coordinate channels LATCH rather than reset.** Design 3.3/9.2 said the reset is "ordered early
-   in the frame, so sibling systems read a completed sum". That is backwards: device events arrive *between*
-   frames, so zeroing at the top of a frame destroys exactly what that frame should report. The adapter
-   accumulates into one buffer and publishes into another once per frame (`latchDeltas`), which also makes the
-   value independent of system execution order — every reader in a frame sees the same number.
-5. **Evaluation state does not live on authored triggers.** Design 4.1 put `satisfied` on the trigger.
-   Authored triggers are routinely shared between bindings (the design's own section 11 editor example reuses
-   one `ctrl` across five chords), so the compiler takes a `clone()` per binding and state lives there.
-6. **Authored collections are plain arrays, not `List`.** Design §9.1 sketched them as
-   [`List`](../../../../core/collection/list/List.js), which is the codebase convention and which the old
-   `Input` component used. They are arrays because nothing reads them on the edge path — the compiled program
-   does — so `List`'s indirection buys nothing there, and its `equals`/`hash`/`toBinaryBuffer` are not needed
-   while `InputMap.serializable` is false. **The cost is real and was paid once already:** `List` carries
-   `on.added`/`on.removed`, and the hand-rolled substitute for that (revision counters) is where the
-   `popLayer` defect lived. Revisit when serialization lands, where `List`'s binary methods would earn their
-   place.
-
-7. **Consumption gates dispatch, not evaluation.** A consumed trigger still updates `satisfied`. Skipping it
-   leaves a stale edge: a map binding both a key and that key's release loses the release, because the press
-   was consumed by the key binding and the release trigger never saw its own value change. Found by the P3
-   gate, which is what the gate is for.
-
----
-
-## 8. What the adversarial review changed
-
-The first draft was reviewed against the source. Everything below was verified before being changed.
-
-### Blocked, and rescoped
-
-* **`EditorKeyMap` is no longer deleted** (5.1). The claim that the focus gate was "preserved by construction"
-  was inverted: the editor GUI lives inside the element the engine's `KeyboardDevice` listens on, so migrating
-  would make `x` delete entities while typing in a panel, and `preventDefault` would swallow the keystroke.
-  Retiring it needs a design addition this program does not contain.
-* **Game input under the editor** (5.2) has no ISM equivalent of `disableSystem`, because ISM dispatch never
-  passes through `update()`. The editor map must be `BlockAll`.
-* **Definition of done items 3 and 4** contradicted the plan's own tables: pointer-button bindings do not all
-  move, and `EditorKeyMap` does not go. Both reworded.
-
-### Facts corrected
-
-* `EngineHarness.js:29,340` is a second consumer of `KeyboardCameraController` (5.3). Deleting it without this
-  is an import-time break for every browser harness.
-* `KeyboardCameraController` binds **eight** keys, not four (5.3).
-* `'user-input'` is sent on the **camera** entity, not the map's, and feeds story camera-focus interruption
-  (5.3).
-* `CombatInteractionStateMachine.js` has **no keyboard bindings** (5.5). The first draft's row named work with
-  no referent.
-* `StrategyInteractionController.js:295-352` binds `pointer/on/down`, which appeared in neither column (5.5).
-* `DevelopmentOptions.js:189` is a shipping `InputController` consumer that was missing from the inventory.
-* The serialization adapter registers in `populateEngineSerializationRegistry.js`, not `makeMirEngineConfig`
-  (5.6). `EngineConfiguration` has no adapter facility.
-* `EngineHarness` has no default system list to add to (5.6), and no spec boots an engine — so the claim that
-  registering there gives specs the system was wrong twice over.
-* The `Input` "holdout" did not exist: the draft's own resolution moved every consumer off it (5.4). The right
-  reason not to delete is the library policy on public surface.
-
-### Defects fixed in the implementation
-
-* **Delta channels latch rather than reset** (7.4) — the original ordering would have reported an empty frame
-  to every reader.
-* **Evaluation state moved off authored triggers** (7.5) — sharing a trigger between bindings would have made
-  them interfere.
-* **Consumption gates dispatch, not evaluation** (7.6) — found by the P3 gate.
-* **`InputMap.serializable` stays `false`** until the adapter lands *and* the Transient discipline is audited.
-  A controller-built map that serialized would load as a ghost, win the order tie, and consume the switches
-  its live twin binds — silent input death, one more ghost per save cycle.
-
-### Gates added
-
-* Design case 20 (a map naming an unregistered device links and stays inert) and case 21 (`registerDevice`
-  after link makes inert bindings live) were dropped from every gate; both move into P3, whose machinery they
-  need. Case 21 exercises live recompile and `satisfied` re-initialisation.
-* P1's cascade items move to P3, where they are observable as *which action fires* rather than by inspecting
-  compiler output.
-* The "reject binding one action as both kinds" item is dropped: it is an `assert.*`, which is stripped in
-  production, and this codebase does not test that asserts throw.
-* Occlusion over direction-derived switches has no gate in either document. Added to P6.
-* P7 necessarily edits code landed in P3, P4 and P5. Stated, so those phases are not treated as frozen.