@woosh/meep-engine 3.1.0 → 3.2.0

package/src/engine/input/ecs/ism/InputMapSystem.js

@@ -1,976 +1,976 @@
-import { assert } from "../../../../core/assert.js";
-import { BitSet } from "../../../../core/binary/BitSet.js";
-import { System } from "../../../ecs/System.js";
-import { InputActionEvent } from "./InputActionEvent.js";
-import { InputMap } from "./map/InputMap.js";
-import { CompiledCoordinate, CompiledTrigger, InputMapProgram } from "./InputMapProgram.js";
-import { InputOcclusion } from "./InputOcclusion.js";
-import { InputSourceTable } from "./InputSourceTable.js";
-
-/**
- * Sentinel for an evaluation point that no switch caused - a tick, or a hold maturing.
- * @readonly
- * @type {number}
- */
-const NO_SOURCE = -1;
-
-/**
- * Subscription record for one interned switch. One per switch rather than a closure per event, so the edge
- * path allocates nothing.
- */
-class SwitchSubscription {
-    /**
-     * @param {InputMapSystem} system
-     * @param {number} index
-     * @param {InputDeviceSwitch} deviceSwitch
-     */
-    constructor(system, index, deviceSwitch) {
-        this.system = system;
-        this.index = index;
-        this.deviceSwitch = deviceSwitch;
-    }
-
-    down() {
-        this.system.handleEdge(this.index, true);
-    }
-
-    up() {
-        this.system.handleEdge(this.index, false);
-    }
-}
-
-/**
- * Drives {@link InputMap} components.
- *
- * EAGER: an edge is evaluated and dispatched inside the device signal that produced it. There is no input
- * buffer and no added frame of latency, which also means consumer code runs inside a DOM event handler - see
- * the deferral rules on {@link link} and {@link handleEdge}.
- *
- * {@link update} dispatches no edge-driven action. It services only what changes without an edge: hold
- * maturity, sequence windows, delta-coordinate reset, and suppression recomputation. Time is advanced there
- * and nowhere else, so it is SIMULATION time - windows do not run while the game is paused, and they stretch
- * under slow motion. That is also what makes every timing behaviour testable without a clock.
- *
- * @example
- *   new InputMapSystem([
- *       new KeyboardInputDeviceAdapter(engine.devices.keyboard),
- *       new PointerInputDeviceAdapter(engine.devices.pointer),
- *       new GamepadInputDeviceAdapter(engine.devices.gamepad)
- *   ])
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class InputMapSystem extends System {
-
-    dependencies = [InputMap];
-
-    /**
-     * @type {Map<string, InputDeviceAdapter>}
-     */
-    #adapters = new Map();
-
-    /**
-     * @type {InputSourceTable}
-     */
-    #table = new InputSourceTable();
-
-    /**
-     * Interned indices of switches currently down. Updated before dispatch, so it is exact at the moment a
-     * handler runs.
-     * @type {BitSet}
-     */
-    #held = new BitSet();
-
-    /**
-     * @type {SwitchSubscription[]}
-     */
-    #subscriptions = [];
-
-    /**
-     * How many linked programs reference each interned switch. A switch drops to zero when the last map
-     * using it unlinks, and its subscription goes with it - which matters beyond tidiness, because
-     * {@link KeyboardDevice} suppresses a browser default for any key whose down signal has handlers. A leaked
-     * subscription means a key stays swallowed long after the map that bound it is gone.
-     * @type {number[]}
-     */
-    #references = [];
-
-    /**
-     * @type {Map<number, InputMapProgram>}
-     */
-    #programs = new Map();
-
-    /**
-     * Programs by descending {@link InputMap#order}, ties oldest-linked first.
-     * @type {InputMapProgram[]}
-     */
-    #ordered = [];
-
-    /**
-     * @type {BitSet}
-     */
-    #consumed = new BitSet();
-
-    /**
-     * Indices set in {@link #consumed}, so it can be cleared without scanning.
-     * @type {number[]}
-     */
-    #consumedList = [];
-
-    /**
-     * @type {number}
-     */
-    #time = 0;
-
-    /**
-     * @type {boolean}
-     */
-    #dispatching = false;
-
-    /**
-     * Work requested while a walk was in progress. Applied once the walk finishes, so a handler that removes
-     * its own entity, rebinds its own map, or provokes a nested edge cannot corrupt the walk.
-     * @type {function[]}
-     */
-    #deferred = [];
-
-    /**
-     * @type {InputActionEvent}
-     */
-    #event = new InputActionEvent();
-
-    /**
-     * @param {InputDeviceAdapter[]} adapters
-     */
-    constructor(adapters = []) {
-        super();
-
-        for (let i = 0; i < adapters.length; i++) {
-            this.registerDevice(adapters[i]);
-        }
-    }
-
-    /**
-     * May be called after maps are linked; every linked map is recompiled, so bindings on a device that was
-     * missing become live.
-     *
-     * @param {InputDeviceAdapter} adapter
-     */
-    registerDevice(adapter) {
-        assert.defined(adapter, 'adapter');
-        assert.isString(adapter.id, 'adapter.id');
-
-        if (this.#dispatching) {
-            // recompiling mid-walk would swap the programs out from under it
-            this.#deferred.push(() => this.registerDevice(adapter));
-
-            return;
-        }
-
-        const replaced = this.#adapters.get(adapter.id);
-
-        if (replaced !== undefined) {
-            replaced.shutdown();
-        }
-
-        this.#adapters.set(adapter.id, adapter);
-
-        adapter.startup();
-
-        if (this.#programs.size > 0) {
-            this.#recompileAll();
-        }
-    }
-
-    /**
-     * @param {EntityManager} entityManager
-     */
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-    }
-
-    async shutdown() {
-        for (let i = 0; i < this.#subscriptions.length; i++) {
-            const subscription = this.#subscriptions[i];
-
-            if (subscription !== undefined) {
-                subscription.deviceSwitch.down.remove(subscription.down, subscription);
-                subscription.deviceSwitch.up.remove(subscription.up, subscription);
-            }
-        }
-
-        this.#subscriptions = [];
-
-        for (const adapter of this.#adapters.values()) {
-            adapter.shutdown();
-        }
-    }
-
-    /**
-     * @param {InputMap} map
-     * @param {number} entity
-     */
-    link(map, entity) {
-        if (this.#dispatching) {
-            this.#deferred.push(() => this.link(map, entity));
-
-            return;
-        }
-
-        /*
-        One InputMap instance backs one entity. The component holds a single compiled program, so a second
-        entity sharing the instance would hijack it and unlinking either would leave the other reading as
-        inactive while it still dispatched. Build a second map rather than sharing one.
-         */
-        assert.notOk(this.#isLinked(map), 'InputMap instance is already linked to another entity');
-
-        const program = this.#compile(map, entity);
-
-        this.#programs.set(entity, program);
-
-        map.attachProgram(program);
-
-        this.#reorder();
-    }
-
-    /**
-     * @param {InputMap} map
-     * @returns {boolean}
-     */
-    #isLinked(map) {
-        for (const program of this.#programs.values()) {
-            if (program.map === map) {
-                return true;
-            }
-        }
-
-        return false;
-    }
-
-    /**
-     * @param {InputMap} map
-     * @param {number} entity
-     */
-    unlink(map, entity) {
-        if (this.#dispatching) {
-            this.#deferred.push(() => this.unlink(map, entity));
-
-            return;
-        }
-
-        const program = this.#programs.get(entity);
-
-        this.#programs.delete(entity);
-
-        map.attachProgram(null);
-
-        if (program !== undefined) {
-            this.#release(program);
-        }
-
-        this.#reorder();
-    }
-
-    /**
-     * Give back a program's claim on the switches it referenced, unsubscribing any that no live program
-     * still uses. Interned indices are never recycled - only the subscription goes - so a later relink of
-     * the same binding lands on the same index and any recording stays readable.
-     *
-     * @param {InputMapProgram} program
-     */
-    #release(program) {
-        const indices = program.referencedIndices;
-
-        for (let i = 0; i < indices.length; i++) {
-            const index = indices[i];
-
-            const remaining = (this.#references[index] || 0) - 1;
-
-            this.#references[index] = remaining;
-
-            if (remaining > 0) {
-                continue;
-            }
-
-            const subscription = this.#subscriptions[index];
-
-            if (subscription === undefined) {
-                continue;
-            }
-
-            subscription.deviceSwitch.down.remove(subscription.down, subscription);
-            subscription.deviceSwitch.up.remove(subscription.up, subscription);
-
-            this.#subscriptions[index] = undefined;
-
-            /*
-            Forget the state along with the subscription. A key released while nothing was observing it would
-            otherwise stay set, and the next map to bind it would read it as held with nothing pressed - and
-            would swallow the first real press, having no rising edge to see.
-             */
-            this.#held.set(index, false);
-        }
-    }
-
-    /**
-     * Advance time and service everything that changes without a device edge.
-     *
-     * @param {number} timeDelta seconds
-     */
-    update(timeDelta) {
-        this.#time += timeDelta;
-
-        this.#recompileChanged();
-
-        /*
-        Latch first. Relative channels accumulate between frames, so this publishes what arrived since the
-        previous frame and starts a fresh window - clearing them instead, or latching afterwards, would report
-        an empty frame to everything that reads during it.
-         */
-        for (const adapter of this.#adapters.values()) {
-            adapter.latchDeltas();
-        }
-
-        this.#evaluate(NO_SOURCE, timeDelta);
-    }
-
-    /**
-     * Invoked by a switch subscription. Public because the subscription objects call it; not part of the
-     * consumer-facing surface.
-     *
-     * @param {number} index interned switch index
-     * @param {boolean} isDown
-     */
-    handleEdge(index, isDown) {
-        if (this.#dispatching) {
-            /*
-            A nested edge - a handler that polled a gamepad, scripted an input, or dispatched a DOM event
-            synchronously. Evaluating inline would clobber the shared event object under the outer handler,
-            so both the state change AND its evaluation are queued.
-
-            The state change has to travel with it. Applying `#held` now and evaluating later loses the
-            transition entirely when a handler issues a press and a release together - the deferred walk
-            re-reads live state and sees nothing changed, so a scripted tap fires nothing at all.
-             */
-            this.#deferred.push(() => {
-                this.#held.set(index, isDown);
-
-                this.#evaluate(index, 0);
-            });
-
-            return;
-        }
-
-        this.#held.set(index, isDown);
-
-        this.#evaluate(index, 0);
-    }
-
-    /**
-     * @param {number} sourceIndex the switch that changed, or NO_SOURCE
-     * @param {number} timeDelta
-     */
-    #evaluate(sourceIndex, timeDelta) {
-        this.#dispatching = true;
-
-        try {
-            this.#clearConsumed();
-
-            const held = this.#held;
-            const time = this.#time;
-            const ordered = this.#ordered;
-
-            for (let p = 0; p < ordered.length; p++) {
-                const program = ordered[p];
-
-                if (program.suppressed) {
-                    continue;
-                }
-
-                const stateful = program.stateful;
-
-                for (let i = 0; i < stateful.length; i++) {
-                    stateful[i].evaluate(held, time, timeDelta);
-                }
-
-                const candidates = sourceIndex === NO_SOURCE
-                    ? program.timedCandidates
-                    : program.candidatesByIndex[sourceIndex];
-
-                if (candidates === undefined) {
-                    continue;
-                }
-
-                this.#walk(program, candidates, held, time, sourceIndex);
-            }
-        } finally {
-            this.#dispatching = false;
-
-            /*
-            In the `finally`, not after it, because a handler that throws must not strand the work it queued.
-            The exception propagates out of the walk and is swallowed further up by `Signal`, so a drain
-            placed after this block simply never runs - and a map linked from a throwing handler would stay
-            dead, with no subsequent edge to notice, because it is the deferred link that would have
-            subscribed to its switches in the first place.
-
-            The recompile is here for a narrower reason: a handler may have rebound its own map, which is the
-            rebinding-capture flow, and design 2.3 promises that lands at the end of the current edge rather
-            than at the next tick.
-             */
-            this.#drainDeferred();
-
-            this.#recompileChanged();
-        }
-    }
-
-    /**
-     * @param {InputMapProgram} program
-     * @param {CompiledTrigger[]} candidates
-     * @param {BitSet} held
-     * @param {number} time
-     */
-    #walk(program, candidates, held, time, sourceIndex) {
-        /*
-        Specificity arbitration is a property of the map, not of its occlusion: Ctrl+Z must beat a bare Z in
-        a `Pass` map too. So a fired trigger always consumes, and occlusion decides only whether that
-        consumption is still standing when the next program down is walked.
-         */
-        const mark = this.#consumedList.length;
-
-        for (let i = 0; i < candidates.length; i++) {
-            const entry = candidates[i];
-
-            const trigger = entry.trigger;
-
-            const now = trigger.test(held);
-            const was = trigger.satisfied;
-
-            /*
-            `satisfied` is updated even when the trigger is consumed. Consumption gates DISPATCH, not
-            evaluation: skipping the update leaves a stale edge behind, and the next time the trigger really
-            does rise it looks like it never fell. Concretely, 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.
-             */
-            trigger.satisfied = now;
-
-            if (!now || was) {
-                continue;
-            }
-
-            if (this.#anyConsumed(entry.indices)) {
-                continue;
-            }
-
-            this.#dispatch(program, entry, time, sourceIndex);
-
-            this.#consume(entry.indices);
-        }
-
-        if (program.occlusion === InputOcclusion.Pass) {
-            this.#releaseConsumed(mark);
-        }
-    }
-
-    /**
-     * @param {InputMapProgram} program
-     * @param {CompiledTrigger} entry
-     * @param {number} time
-     */
-    #dispatch(program, entry, time, sourceIndex) {
-        const event = this.#event;
-
-        event.action = entry.action;
-        event.time = time;
-        event.value.set(0, 0, 0);
-
-        /*
-        The switch whose edge completed the trigger, which is the question a consumer asks ("which mouse
-        button was it"). Falls back to the trigger's first source for an evaluation point no switch caused -
-        a hold maturing, or a window expiring on the tick.
-         */
-        const index = sourceIndex !== NO_SOURCE ? sourceIndex : entry.indices[0];
-
-        if (index !== undefined) {
-            const source = this.#table.get(index);
-
-            event.source.device = source.device;
-            event.source.code = source.code;
-        }
-
-        this.entityManager.dataset.sendEvent(program.entity, entry.action, event);
-    }
-
-    /**
-     * @param {number[]} indices
-     * @returns {boolean}
-     */
-    #anyConsumed(indices) {
-        for (let i = 0; i < indices.length; i++) {
-            if (this.#consumed.get(indices[i])) {
-                return true;
-            }
-        }
-
-        return false;
-    }
-
-    /**
-     * @param {number[]} indices
-     */
-    #consume(indices) {
-        for (let i = 0; i < indices.length; i++) {
-            const index = indices[i];
-
-            if (!this.#consumed.get(index)) {
-                this.#consumed.set(index, true);
-
-                this.#consumedList.push(index);
-            }
-        }
-    }
-
-    /**
-     * Undo every consumption recorded after `mark`, used to make a `Pass` map's arbitration local to itself.
-     * @param {number} mark
-     */
-    #releaseConsumed(mark) {
-        const list = this.#consumedList;
-
-        while (list.length > mark) {
-            this.#consumed.set(list.pop(), false);
-        }
-    }
-
-    #clearConsumed() {
-        const list = this.#consumedList;
-
-        for (let i = 0; i < list.length; i++) {
-            this.#consumed.set(list[i], false);
-        }
-
-        list.length = 0;
-    }
-
-    /**
-     * Run queued work, taking each item off the queue BEFORE running it.
-     *
-     * Taking one at a time rather than swapping the whole array out is what keeps a throwing item from
-     * discarding the rest: the exception propagates, so the failure stays visible, and whatever had not run
-     * yet is still queued for the next evaluation point.
-     */
-    #drainDeferred() {
-        const deferred = this.#deferred;
-
-        while (deferred.length > 0) {
-            const pending = deferred.shift();
-
-            pending();
-        }
-    }
-
-    /**
-     * Turn an authored {@link InputMap} into its executable form: cascade resolved, triggers cloned so no two
-     * bindings share evaluation state, sources interned, candidate lists sorted by specificity.
-     *
-     * @param {InputMap} map
-     * @param {number} entity
-     * @returns {InputMapProgram}
-     */
-    #compile(map, entity) {
-        const program = new InputMapProgram();
-
-        program.entity = entity;
-        program.map = map;
-        program.revision = map.revision;
-        program.order = map.order;
-        program.occlusion = map.occlusion;
-        program.held = this.#held;
-
-        const triggerActions = new Map();
-        const coordinateActions = new Map();
-
-        /*
-        Cascade: the HIGHEST layer that mentions an action supplies all of it. Walking top down and keeping
-        the first mention is what lets a user keymap layer replace a default rather than add to it.
-         */
-        const layers = map.layers;
-
-        for (let i = layers.length - 1; i >= 0; i--) {
-            const layer = layers[i];
-
-            for (let b = 0; b < layer.bindings.length; b++) {
-                const binding = layer.bindings[b];
-
-                if (!triggerActions.has(binding.action) && !coordinateActions.has(binding.action)) {
-                    triggerActions.set(binding.action, binding.triggers);
-                }
-            }
-
-            for (let c = 0; c < layer.coordinates.length; c++) {
-                const binding = layer.coordinates[c];
-
-                if (!triggerActions.has(binding.action) && !coordinateActions.has(binding.action)) {
-                    coordinateActions.set(binding.action, binding.channels);
-                }
-            }
-        }
-
-        for (const [action, triggers] of triggerActions) {
-            for (let i = 0; i < triggers.length; i++) {
-                const entry = new CompiledTrigger();
-
-                entry.action = action;
-                entry.trigger = triggers[i].clone();
-                entry.trigger.resolve(this.#table);
-                entry.indices = this.#indicesOf(entry.trigger);
-
-                entry.trigger.collectStateful(program.stateful);
-
-                program.triggers.push(entry);
-            }
-        }
-
-        for (const [action, channels] of coordinateActions) {
-            const entry = new CompiledCoordinate();
-
-            entry.action = action;
-            entry.channels = channels.map(c => {
-                const clone = c.clone();
-
-                clone.resolve(this.#table, this.#adapters);
-                clone.collectStateful(program.stateful);
-
-                return clone;
-            });
-            entry.dimensions = channels[0].dimensions;
-
-            program.coordinates.push(entry);
-        }
-
-        this.#buildCandidates(program);
-
-        const referenced = [];
-
-        /**
-         * @param {number[]} indices
-         */
-        function claim(indices) {
-            for (let k = 0; k < indices.length; k++) {
-                if (referenced.indexOf(indices[k]) === -1) {
-                    referenced.push(indices[k]);
-                }
-            }
-        }
-
-        for (let i = 0; i < program.triggers.length; i++) {
-            claim(program.triggers[i].indices);
-        }
-
-        /*
-        Coordinate channels reference switches as much as triggers do - a WASD pan channel is four of them -
-        and leaving them out of the count is wrong in both directions. A coordinate-only map would release
-        nothing and leak its subscriptions, and a trigger map unlinking would drop a switch to zero and
-        unsubscribe it while a coordinate map was still reading it, freezing that map's axis mid-hold.
-         */
-        for (let i = 0; i < program.coordinates.length; i++) {
-            const channels = program.coordinates[i].channels;
-
-            for (let c = 0; c < channels.length; c++) {
-                claim(this.#indicesOf(channels[c]));
-            }
-        }
-
-        program.referencedIndices = referenced;
-
-        for (let i = 0; i < referenced.length; i++) {
-            const index = referenced[i];
-
-            this.#references[index] = (this.#references[index] || 0) + 1;
-        }
-
-        this.#subscribeAll();
-
-        for (let i = 0; i < program.triggers.length; i++) {
-            program.triggers[i].trigger.reset(this.#held, this.#time);
-        }
-
-        return program;
-    }
-
-    /**
-     * Intern everything a trigger or channel references, and hand back the deduplicated indices.
-     *
-     * @param {InputTrigger|InputCoordinateChannel} owner
-     * @returns {number[]}
-     */
-    #indicesOf(owner) {
-        const sources = [];
-
-        owner.collectSources(sources);
-
-        const result = [];
-
-        for (let i = 0; i < sources.length; i++) {
-            const index = this.#table.intern(sources[i]);
-
-            if (result.indexOf(index) === -1) {
-                result.push(index);
-            }
-        }
-
-        return result;
-    }
-
-    /**
-     * @param {InputMapProgram} program
-     */
-    #buildCandidates(program) {
-        const timed = [];
-
-        for (let i = 0; i < program.triggers.length; i++) {
-            const entry = program.triggers[i];
-
-            if (this.#isTimed(entry.trigger)) {
-                timed.push(entry);
-            }
-        }
-
-        sortBySpecificity(timed);
-
-        program.timedCandidates = timed;
-
-        const byIndex = [];
-
-        for (let i = 0; i < program.triggers.length; i++) {
-            const entry = program.triggers[i];
-
-            for (let k = 0; k < entry.indices.length; k++) {
-                const index = entry.indices[k];
-
-                let list = byIndex[index];
-
-                if (list === undefined) {
-                    list = [];
-
-                    byIndex[index] = list;
-                }
-
-                if (list.indexOf(entry) === -1) {
-                    list.push(entry);
-                }
-            }
-        }
-
-        /*
-        A timed trigger must be reconsidered at every evaluation point, including edges on switches it does
-        not reference - otherwise a sequence that completed would keep reading as satisfied and never rise
-        again.
-         */
-        for (let index = 0; index < byIndex.length; index++) {
-            const list = byIndex[index];
-
-            if (list === undefined) {
-                continue;
-            }
-
-            for (let i = 0; i < timed.length; i++) {
-                if (list.indexOf(timed[i]) === -1) {
-                    list.push(timed[i]);
-                }
-            }
-
-            sortBySpecificity(list);
-        }
-
-        program.candidatesByIndex = byIndex;
-    }
-
-    /**
-     * @param {InputTrigger} trigger
-     * @returns {boolean}
-     */
-    #isTimed(trigger) {
-        const stateful = [];
-
-        trigger.collectStateful(stateful);
-
-        return stateful.length > 0;
-    }
-
-    /**
-     * Subscribe to every interned switch not already subscribed. Idempotent, so it is safe after any compile.
-     */
-    #subscribeAll() {
-        const table = this.#table;
-
-        for (let index = 0; index < table.size; index++) {
-            if (this.#subscriptions[index] !== undefined) {
-                continue;
-            }
-
-            const source = table.get(index);
-
-            const adapter = this.#adapters.get(source.device);
-
-            if (adapter === undefined) {
-                // device not registered: inert until registerDevice brings it to life
-                continue;
-            }
-
-            const deviceSwitch = adapter.getSwitch(source.code);
-
-            const subscription = new SwitchSubscription(this, index, deviceSwitch);
-
-            deviceSwitch.down.add(subscription.down, subscription);
-            deviceSwitch.up.add(subscription.up, subscription);
-
-            this.#subscriptions[index] = subscription;
-
-            if (deviceSwitch.is_down) {
-                this.#held.set(index, true);
-            }
-        }
-    }
-
-    /**
-     * Pick up structural edits made to a linked map since it was compiled. An edit made from inside a
-     * handler is already deferred (see {@link link}); this covers edits made from anywhere else.
-     */
-    #recompileChanged() {
-        const stale = [];
-
-        let arbitration = false;
-
-        for (const program of this.#programs.values()) {
-            const map = program.map;
-
-            if (map.revision !== program.revision) {
-                stale.push(program);
-            }
-
-            if (map.order !== program.order || map.occlusion !== program.occlusion) {
-                /*
-                Cheaper than a recompile and much more common: someone raised a dialog's order, or switched a
-                map to BlockAll. Only the arbitration snapshot is stale, so re-sort rather than rebuild.
-                 */
-                program.order = map.order;
-                program.occlusion = map.occlusion;
-
-                arbitration = true;
-            }
-        }
-
-        if (stale.length > 0) {
-            this.#recompile(stale);
-        } else if (arbitration) {
-            this.#reorder();
-        }
-    }
-
-    #recompileAll() {
-        const previous = [];
-
-        for (const program of this.#programs.values()) {
-            previous.push(program);
-        }
-
-        this.#recompile(previous);
-    }
-
-    /**
-     * Rebuild exactly the listed programs.
-     *
-     * Scoped rather than global on purpose: a compile discards the matcher state of everything it rebuilds,
-     * so recompiling every map because one of them was edited would reset every other map's half-matched
-     * sequences and half-matured holds. With several contexts live at once - which is the normal case - that
-     * is a player losing an input they were part way through for a reason nowhere near them.
-     *
-     * @param {InputMapProgram[]} programs
-     */
-    #recompile(programs) {
-        for (let i = 0; i < programs.length; i++) {
-            this.#release(programs[i]);
-        }
-
-        for (let i = 0; i < programs.length; i++) {
-            const program = this.#compile(programs[i].map, programs[i].entity);
-
-            this.#programs.set(program.entity, program);
-
-            program.map.attachProgram(program);
-        }
-
-        this.#reorder();
-    }
-
-    /**
-     * Sort programs by descending order and recompute suppression. Ties keep link order, so arbitration is
-     * deterministic even when two maps pick the same number.
-     */
-    #reorder() {
-        const ordered = [];
-
-        for (const program of this.#programs.values()) {
-            ordered.push(program);
-        }
-
-        ordered.sort((a, b) => b.order - a.order);
-
-        this.#ordered = ordered;
-
-        let blocked = false;
-
-        for (let i = 0; i < ordered.length; i++) {
-            const program = ordered[i];
-
-            const was = program.suppressed;
-
-            program.suppressed = blocked;
-
-            if (was && !blocked) {
-                /*
-                Coming back from under a modal. Everything resumes against current reality rather than
-                against whatever was true when the modal opened, so a half-matched sequence does not get to
-                complete on one further step.
-                 */
-                for (let t = 0; t < program.triggers.length; t++) {
-                    program.triggers[t].trigger.reset(this.#held, this.#time);
-                }
-            }
-
-            if (program.occlusion === InputOcclusion.BlockAll) {
-                blocked = true;
-            }
-        }
-    }
-}
-
-/**
- * Specificity order: more sequence steps first, then wider chords, then declaration order. Total, so a
- * result never depends on which binding happened to be written first.
- *
- * @param {CompiledTrigger[]} entries
- */
-function sortBySpecificity(entries) {
-    for (let i = 0; i < entries.length; i++) {
-        entries[i].declarationOrder = i;
-    }
-
-    entries.sort((a, b) => {
-        const steps = b.trigger.stepCount - a.trigger.stepCount;
-
-        if (steps !== 0) {
-            return steps;
-        }
-
-        const width = b.trigger.width - a.trigger.width;
-
-        if (width !== 0) {
-            return width;
-        }
-
-        return a.declarationOrder - b.declarationOrder;
-    });
-}
+import { assert } from "../../../../core/assert.js";
+import { BitSet } from "../../../../core/binary/BitSet.js";
+import { System } from "../../../ecs/System.js";
+import { InputActionEvent } from "./InputActionEvent.js";
+import { InputMap } from "./map/InputMap.js";
+import { CompiledCoordinate, CompiledTrigger, InputMapProgram } from "./InputMapProgram.js";
+import { InputOcclusion } from "./InputOcclusion.js";
+import { InputSourceTable } from "./InputSourceTable.js";
+
+/**
+ * Sentinel for an evaluation point that no switch caused - a tick, or a hold maturing.
+ * @readonly
+ * @type {number}
+ */
+const NO_SOURCE = -1;
+
+/**
+ * Subscription record for one interned switch. One per switch rather than a closure per event, so the edge
+ * path allocates nothing.
+ */
+class SwitchSubscription {
+    /**
+     * @param {InputMapSystem} system
+     * @param {number} index
+     * @param {InputDeviceSwitch} deviceSwitch
+     */
+    constructor(system, index, deviceSwitch) {
+        this.system = system;
+        this.index = index;
+        this.deviceSwitch = deviceSwitch;
+    }
+
+    down() {
+        this.system.handleEdge(this.index, true);
+    }
+
+    up() {
+        this.system.handleEdge(this.index, false);
+    }
+}
+
+/**
+ * Drives {@link InputMap} components.
+ *
+ * EAGER: an edge is evaluated and dispatched inside the device signal that produced it. There is no input
+ * buffer and no added frame of latency, which also means consumer code runs inside a DOM event handler - see
+ * the deferral rules on {@link link} and {@link handleEdge}.
+ *
+ * {@link update} dispatches no edge-driven action. It services only what changes without an edge: hold
+ * maturity, sequence windows, delta-coordinate reset, and suppression recomputation. Time is advanced there
+ * and nowhere else, so it is SIMULATION time - windows do not run while the game is paused, and they stretch
+ * under slow motion. That is also what makes every timing behaviour testable without a clock.
+ *
+ * @example
+ *   new InputMapSystem([
+ *       new KeyboardInputDeviceAdapter(engine.devices.keyboard),
+ *       new PointerInputDeviceAdapter(engine.devices.pointer),
+ *       new GamepadInputDeviceAdapter(engine.devices.gamepad)
+ *   ])
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class InputMapSystem extends System {
+
+    dependencies = [InputMap];
+
+    /**
+     * @type {Map<string, InputDeviceAdapter>}
+     */
+    #adapters = new Map();
+
+    /**
+     * @type {InputSourceTable}
+     */
+    #table = new InputSourceTable();
+
+    /**
+     * Interned indices of switches currently down. Updated before dispatch, so it is exact at the moment a
+     * handler runs.
+     * @type {BitSet}
+     */
+    #held = new BitSet();
+
+    /**
+     * @type {SwitchSubscription[]}
+     */
+    #subscriptions = [];
+
+    /**
+     * How many linked programs reference each interned switch. A switch drops to zero when the last map
+     * using it unlinks, and its subscription goes with it - which matters beyond tidiness, because
+     * {@link KeyboardDevice} suppresses a browser default for any key whose down signal has handlers. A leaked
+     * subscription means a key stays swallowed long after the map that bound it is gone.
+     * @type {number[]}
+     */
+    #references = [];
+
+    /**
+     * @type {Map<number, InputMapProgram>}
+     */
+    #programs = new Map();
+
+    /**
+     * Programs by descending {@link InputMap#order}, ties oldest-linked first.
+     * @type {InputMapProgram[]}
+     */
+    #ordered = [];
+
+    /**
+     * @type {BitSet}
+     */
+    #consumed = new BitSet();
+
+    /**
+     * Indices set in {@link #consumed}, so it can be cleared without scanning.
+     * @type {number[]}
+     */
+    #consumedList = [];
+
+    /**
+     * @type {number}
+     */
+    #time = 0;
+
+    /**
+     * @type {boolean}
+     */
+    #dispatching = false;
+
+    /**
+     * Work requested while a walk was in progress. Applied once the walk finishes, so a handler that removes
+     * its own entity, rebinds its own map, or provokes a nested edge cannot corrupt the walk.
+     * @type {function[]}
+     */
+    #deferred = [];
+
+    /**
+     * @type {InputActionEvent}
+     */
+    #event = new InputActionEvent();
+
+    /**
+     * @param {InputDeviceAdapter[]} adapters
+     */
+    constructor(adapters = []) {
+        super();
+
+        for (let i = 0; i < adapters.length; i++) {
+            this.registerDevice(adapters[i]);
+        }
+    }
+
+    /**
+     * May be called after maps are linked; every linked map is recompiled, so bindings on a device that was
+     * missing become live.
+     *
+     * @param {InputDeviceAdapter} adapter
+     */
+    registerDevice(adapter) {
+        assert.defined(adapter, 'adapter');
+        assert.isString(adapter.id, 'adapter.id');
+
+        if (this.#dispatching) {
+            // recompiling mid-walk would swap the programs out from under it
+            this.#deferred.push(() => this.registerDevice(adapter));
+
+            return;
+        }
+
+        const replaced = this.#adapters.get(adapter.id);
+
+        if (replaced !== undefined) {
+            replaced.shutdown();
+        }
+
+        this.#adapters.set(adapter.id, adapter);
+
+        adapter.startup();
+
+        if (this.#programs.size > 0) {
+            this.#recompileAll();
+        }
+    }
+
+    /**
+     * @param {EntityManager} entityManager
+     */
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+    }
+
+    async shutdown() {
+        for (let i = 0; i < this.#subscriptions.length; i++) {
+            const subscription = this.#subscriptions[i];
+
+            if (subscription !== undefined) {
+                subscription.deviceSwitch.down.remove(subscription.down, subscription);
+                subscription.deviceSwitch.up.remove(subscription.up, subscription);
+            }
+        }
+
+        this.#subscriptions = [];
+
+        for (const adapter of this.#adapters.values()) {
+            adapter.shutdown();
+        }
+    }
+
+    /**
+     * @param {InputMap} map
+     * @param {number} entity
+     */
+    link(map, entity) {
+        if (this.#dispatching) {
+            this.#deferred.push(() => this.link(map, entity));
+
+            return;
+        }
+
+        /*
+        One InputMap instance backs one entity. The component holds a single compiled program, so a second
+        entity sharing the instance would hijack it and unlinking either would leave the other reading as
+        inactive while it still dispatched. Build a second map rather than sharing one.
+         */
+        assert.notOk(this.#isLinked(map), 'InputMap instance is already linked to another entity');
+
+        const program = this.#compile(map, entity);
+
+        this.#programs.set(entity, program);
+
+        map.attachProgram(program);
+
+        this.#reorder();
+    }
+
+    /**
+     * @param {InputMap} map
+     * @returns {boolean}
+     */
+    #isLinked(map) {
+        for (const program of this.#programs.values()) {
+            if (program.map === map) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * @param {InputMap} map
+     * @param {number} entity
+     */
+    unlink(map, entity) {
+        if (this.#dispatching) {
+            this.#deferred.push(() => this.unlink(map, entity));
+
+            return;
+        }
+
+        const program = this.#programs.get(entity);
+
+        this.#programs.delete(entity);
+
+        map.attachProgram(null);
+
+        if (program !== undefined) {
+            this.#release(program);
+        }
+
+        this.#reorder();
+    }
+
+    /**
+     * Give back a program's claim on the switches it referenced, unsubscribing any that no live program
+     * still uses. Interned indices are never recycled - only the subscription goes - so a later relink of
+     * the same binding lands on the same index and any recording stays readable.
+     *
+     * @param {InputMapProgram} program
+     */
+    #release(program) {
+        const indices = program.referencedIndices;
+
+        for (let i = 0; i < indices.length; i++) {
+            const index = indices[i];
+
+            const remaining = (this.#references[index] || 0) - 1;
+
+            this.#references[index] = remaining;
+
+            if (remaining > 0) {
+                continue;
+            }
+
+            const subscription = this.#subscriptions[index];
+
+            if (subscription === undefined) {
+                continue;
+            }
+
+            subscription.deviceSwitch.down.remove(subscription.down, subscription);
+            subscription.deviceSwitch.up.remove(subscription.up, subscription);
+
+            this.#subscriptions[index] = undefined;
+
+            /*
+            Forget the state along with the subscription. A key released while nothing was observing it would
+            otherwise stay set, and the next map to bind it would read it as held with nothing pressed - and
+            would swallow the first real press, having no rising edge to see.
+             */
+            this.#held.set(index, false);
+        }
+    }
+
+    /**
+     * Advance time and service everything that changes without a device edge.
+     *
+     * @param {number} timeDelta seconds
+     */
+    update(timeDelta) {
+        this.#time += timeDelta;
+
+        this.#recompileChanged();
+
+        /*
+        Latch first. Relative channels accumulate between frames, so this publishes what arrived since the
+        previous frame and starts a fresh window - clearing them instead, or latching afterwards, would report
+        an empty frame to everything that reads during it.
+         */
+        for (const adapter of this.#adapters.values()) {
+            adapter.latchDeltas();
+        }
+
+        this.#evaluate(NO_SOURCE, timeDelta);
+    }
+
+    /**
+     * Invoked by a switch subscription. Public because the subscription objects call it; not part of the
+     * consumer-facing surface.
+     *
+     * @param {number} index interned switch index
+     * @param {boolean} isDown
+     */
+    handleEdge(index, isDown) {
+        if (this.#dispatching) {
+            /*
+            A nested edge - a handler that polled a gamepad, scripted an input, or dispatched a DOM event
+            synchronously. Evaluating inline would clobber the shared event object under the outer handler,
+            so both the state change AND its evaluation are queued.
+
+            The state change has to travel with it. Applying `#held` now and evaluating later loses the
+            transition entirely when a handler issues a press and a release together - the deferred walk
+            re-reads live state and sees nothing changed, so a scripted tap fires nothing at all.
+             */
+            this.#deferred.push(() => {
+                this.#held.set(index, isDown);
+
+                this.#evaluate(index, 0);
+            });
+
+            return;
+        }
+
+        this.#held.set(index, isDown);
+
+        this.#evaluate(index, 0);
+    }
+
+    /**
+     * @param {number} sourceIndex the switch that changed, or NO_SOURCE
+     * @param {number} timeDelta
+     */
+    #evaluate(sourceIndex, timeDelta) {
+        this.#dispatching = true;
+
+        try {
+            this.#clearConsumed();
+
+            const held = this.#held;
+            const time = this.#time;
+            const ordered = this.#ordered;
+
+            for (let p = 0; p < ordered.length; p++) {
+                const program = ordered[p];
+
+                if (program.suppressed) {
+                    continue;
+                }
+
+                const stateful = program.stateful;
+
+                for (let i = 0; i < stateful.length; i++) {
+                    stateful[i].evaluate(held, time, timeDelta);
+                }
+
+                const candidates = sourceIndex === NO_SOURCE
+                    ? program.timedCandidates
+                    : program.candidatesByIndex[sourceIndex];
+
+                if (candidates === undefined) {
+                    continue;
+                }
+
+                this.#walk(program, candidates, held, time, sourceIndex);
+            }
+        } finally {
+            this.#dispatching = false;
+
+            /*
+            In the `finally`, not after it, because a handler that throws must not strand the work it queued.
+            The exception propagates out of the walk and is swallowed further up by `Signal`, so a drain
+            placed after this block simply never runs - and a map linked from a throwing handler would stay
+            dead, with no subsequent edge to notice, because it is the deferred link that would have
+            subscribed to its switches in the first place.
+
+            The recompile is here for a narrower reason: a handler may have rebound its own map, which is the
+            rebinding-capture flow, and design 2.3 promises that lands at the end of the current edge rather
+            than at the next tick.
+             */
+            this.#drainDeferred();
+
+            this.#recompileChanged();
+        }
+    }
+
+    /**
+     * @param {InputMapProgram} program
+     * @param {CompiledTrigger[]} candidates
+     * @param {BitSet} held
+     * @param {number} time
+     */
+    #walk(program, candidates, held, time, sourceIndex) {
+        /*
+        Specificity arbitration is a property of the map, not of its occlusion: Ctrl+Z must beat a bare Z in
+        a `Pass` map too. So a fired trigger always consumes, and occlusion decides only whether that
+        consumption is still standing when the next program down is walked.
+         */
+        const mark = this.#consumedList.length;
+
+        for (let i = 0; i < candidates.length; i++) {
+            const entry = candidates[i];
+
+            const trigger = entry.trigger;
+
+            const now = trigger.test(held);
+            const was = trigger.satisfied;
+
+            /*
+            `satisfied` is updated even when the trigger is consumed. Consumption gates DISPATCH, not
+            evaluation: skipping the update leaves a stale edge behind, and the next time the trigger really
+            does rise it looks like it never fell. Concretely, 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.
+             */
+            trigger.satisfied = now;
+
+            if (!now || was) {
+                continue;
+            }
+
+            if (this.#anyConsumed(entry.indices)) {
+                continue;
+            }
+
+            this.#dispatch(program, entry, time, sourceIndex);
+
+            this.#consume(entry.indices);
+        }
+
+        if (program.occlusion === InputOcclusion.Pass) {
+            this.#releaseConsumed(mark);
+        }
+    }
+
+    /**
+     * @param {InputMapProgram} program
+     * @param {CompiledTrigger} entry
+     * @param {number} time
+     */
+    #dispatch(program, entry, time, sourceIndex) {
+        const event = this.#event;
+
+        event.action = entry.action;
+        event.time = time;
+        event.value.set(0, 0, 0);
+
+        /*
+        The switch whose edge completed the trigger, which is the question a consumer asks ("which mouse
+        button was it"). Falls back to the trigger's first source for an evaluation point no switch caused -
+        a hold maturing, or a window expiring on the tick.
+         */
+        const index = sourceIndex !== NO_SOURCE ? sourceIndex : entry.indices[0];
+
+        if (index !== undefined) {
+            const source = this.#table.get(index);
+
+            event.source.device = source.device;
+            event.source.code = source.code;
+        }
+
+        this.entityManager.dataset.sendEvent(program.entity, entry.action, event);
+    }
+
+    /**
+     * @param {number[]} indices
+     * @returns {boolean}
+     */
+    #anyConsumed(indices) {
+        for (let i = 0; i < indices.length; i++) {
+            if (this.#consumed.get(indices[i])) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * @param {number[]} indices
+     */
+    #consume(indices) {
+        for (let i = 0; i < indices.length; i++) {
+            const index = indices[i];
+
+            if (!this.#consumed.get(index)) {
+                this.#consumed.set(index, true);
+
+                this.#consumedList.push(index);
+            }
+        }
+    }
+
+    /**
+     * Undo every consumption recorded after `mark`, used to make a `Pass` map's arbitration local to itself.
+     * @param {number} mark
+     */
+    #releaseConsumed(mark) {
+        const list = this.#consumedList;
+
+        while (list.length > mark) {
+            this.#consumed.set(list.pop(), false);
+        }
+    }
+
+    #clearConsumed() {
+        const list = this.#consumedList;
+
+        for (let i = 0; i < list.length; i++) {
+            this.#consumed.set(list[i], false);
+        }
+
+        list.length = 0;
+    }
+
+    /**
+     * Run queued work, taking each item off the queue BEFORE running it.
+     *
+     * Taking one at a time rather than swapping the whole array out is what keeps a throwing item from
+     * discarding the rest: the exception propagates, so the failure stays visible, and whatever had not run
+     * yet is still queued for the next evaluation point.
+     */
+    #drainDeferred() {
+        const deferred = this.#deferred;
+
+        while (deferred.length > 0) {
+            const pending = deferred.shift();
+
+            pending();
+        }
+    }
+
+    /**
+     * Turn an authored {@link InputMap} into its executable form: cascade resolved, triggers cloned so no two
+     * bindings share evaluation state, sources interned, candidate lists sorted by specificity.
+     *
+     * @param {InputMap} map
+     * @param {number} entity
+     * @returns {InputMapProgram}
+     */
+    #compile(map, entity) {
+        const program = new InputMapProgram();
+
+        program.entity = entity;
+        program.map = map;
+        program.revision = map.revision;
+        program.order = map.order;
+        program.occlusion = map.occlusion;
+        program.held = this.#held;
+
+        const triggerActions = new Map();
+        const coordinateActions = new Map();
+
+        /*
+        Cascade: the HIGHEST layer that mentions an action supplies all of it. Walking top down and keeping
+        the first mention is what lets a user keymap layer replace a default rather than add to it.
+         */
+        const layers = map.layers;
+
+        for (let i = layers.length - 1; i >= 0; i--) {
+            const layer = layers[i];
+
+            for (let b = 0; b < layer.bindings.length; b++) {
+                const binding = layer.bindings[b];
+
+                if (!triggerActions.has(binding.action) && !coordinateActions.has(binding.action)) {
+                    triggerActions.set(binding.action, binding.triggers);
+                }
+            }
+
+            for (let c = 0; c < layer.coordinates.length; c++) {
+                const binding = layer.coordinates[c];
+
+                if (!triggerActions.has(binding.action) && !coordinateActions.has(binding.action)) {
+                    coordinateActions.set(binding.action, binding.channels);
+                }
+            }
+        }
+
+        for (const [action, triggers] of triggerActions) {
+            for (let i = 0; i < triggers.length; i++) {
+                const entry = new CompiledTrigger();
+
+                entry.action = action;
+                entry.trigger = triggers[i].clone();
+                entry.trigger.resolve(this.#table);
+                entry.indices = this.#indicesOf(entry.trigger);
+
+                entry.trigger.collectStateful(program.stateful);
+
+                program.triggers.push(entry);
+            }
+        }
+
+        for (const [action, channels] of coordinateActions) {
+            const entry = new CompiledCoordinate();
+
+            entry.action = action;
+            entry.channels = channels.map(c => {
+                const clone = c.clone();
+
+                clone.resolve(this.#table, this.#adapters);
+                clone.collectStateful(program.stateful);
+
+                return clone;
+            });
+            entry.dimensions = channels[0].dimensions;
+
+            program.coordinates.push(entry);
+        }
+
+        this.#buildCandidates(program);
+
+        const referenced = [];
+
+        /**
+         * @param {number[]} indices
+         */
+        function claim(indices) {
+            for (let k = 0; k < indices.length; k++) {
+                if (referenced.indexOf(indices[k]) === -1) {
+                    referenced.push(indices[k]);
+                }
+            }
+        }
+
+        for (let i = 0; i < program.triggers.length; i++) {
+            claim(program.triggers[i].indices);
+        }
+
+        /*
+        Coordinate channels reference switches as much as triggers do - a WASD pan channel is four of them -
+        and leaving them out of the count is wrong in both directions. A coordinate-only map would release
+        nothing and leak its subscriptions, and a trigger map unlinking would drop a switch to zero and
+        unsubscribe it while a coordinate map was still reading it, freezing that map's axis mid-hold.
+         */
+        for (let i = 0; i < program.coordinates.length; i++) {
+            const channels = program.coordinates[i].channels;
+
+            for (let c = 0; c < channels.length; c++) {
+                claim(this.#indicesOf(channels[c]));
+            }
+        }
+
+        program.referencedIndices = referenced;
+
+        for (let i = 0; i < referenced.length; i++) {
+            const index = referenced[i];
+
+            this.#references[index] = (this.#references[index] || 0) + 1;
+        }
+
+        this.#subscribeAll();
+
+        for (let i = 0; i < program.triggers.length; i++) {
+            program.triggers[i].trigger.reset(this.#held, this.#time);
+        }
+
+        return program;
+    }
+
+    /**
+     * Intern everything a trigger or channel references, and hand back the deduplicated indices.
+     *
+     * @param {InputTrigger|InputCoordinateChannel} owner
+     * @returns {number[]}
+     */
+    #indicesOf(owner) {
+        const sources = [];
+
+        owner.collectSources(sources);
+
+        const result = [];
+
+        for (let i = 0; i < sources.length; i++) {
+            const index = this.#table.intern(sources[i]);
+
+            if (result.indexOf(index) === -1) {
+                result.push(index);
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * @param {InputMapProgram} program
+     */
+    #buildCandidates(program) {
+        const timed = [];
+
+        for (let i = 0; i < program.triggers.length; i++) {
+            const entry = program.triggers[i];
+
+            if (this.#isTimed(entry.trigger)) {
+                timed.push(entry);
+            }
+        }
+
+        sortBySpecificity(timed);
+
+        program.timedCandidates = timed;
+
+        const byIndex = [];
+
+        for (let i = 0; i < program.triggers.length; i++) {
+            const entry = program.triggers[i];
+
+            for (let k = 0; k < entry.indices.length; k++) {
+                const index = entry.indices[k];
+
+                let list = byIndex[index];
+
+                if (list === undefined) {
+                    list = [];
+
+                    byIndex[index] = list;
+                }
+
+                if (list.indexOf(entry) === -1) {
+                    list.push(entry);
+                }
+            }
+        }
+
+        /*
+        A timed trigger must be reconsidered at every evaluation point, including edges on switches it does
+        not reference - otherwise a sequence that completed would keep reading as satisfied and never rise
+        again.
+         */
+        for (let index = 0; index < byIndex.length; index++) {
+            const list = byIndex[index];
+
+            if (list === undefined) {
+                continue;
+            }
+
+            for (let i = 0; i < timed.length; i++) {
+                if (list.indexOf(timed[i]) === -1) {
+                    list.push(timed[i]);
+                }
+            }
+
+            sortBySpecificity(list);
+        }
+
+        program.candidatesByIndex = byIndex;
+    }
+
+    /**
+     * @param {InputTrigger} trigger
+     * @returns {boolean}
+     */
+    #isTimed(trigger) {
+        const stateful = [];
+
+        trigger.collectStateful(stateful);
+
+        return stateful.length > 0;
+    }
+
+    /**
+     * Subscribe to every interned switch not already subscribed. Idempotent, so it is safe after any compile.
+     */
+    #subscribeAll() {
+        const table = this.#table;
+
+        for (let index = 0; index < table.size; index++) {
+            if (this.#subscriptions[index] !== undefined) {
+                continue;
+            }
+
+            const source = table.get(index);
+
+            const adapter = this.#adapters.get(source.device);
+
+            if (adapter === undefined) {
+                // device not registered: inert until registerDevice brings it to life
+                continue;
+            }
+
+            const deviceSwitch = adapter.getSwitch(source.code);
+
+            const subscription = new SwitchSubscription(this, index, deviceSwitch);
+
+            deviceSwitch.down.add(subscription.down, subscription);
+            deviceSwitch.up.add(subscription.up, subscription);
+
+            this.#subscriptions[index] = subscription;
+
+            if (deviceSwitch.is_down) {
+                this.#held.set(index, true);
+            }
+        }
+    }
+
+    /**
+     * Pick up structural edits made to a linked map since it was compiled. An edit made from inside a
+     * handler is already deferred (see {@link link}); this covers edits made from anywhere else.
+     */
+    #recompileChanged() {
+        const stale = [];
+
+        let arbitration = false;
+
+        for (const program of this.#programs.values()) {
+            const map = program.map;
+
+            if (map.revision !== program.revision) {
+                stale.push(program);
+            }
+
+            if (map.order !== program.order || map.occlusion !== program.occlusion) {
+                /*
+                Cheaper than a recompile and much more common: someone raised a dialog's order, or switched a
+                map to BlockAll. Only the arbitration snapshot is stale, so re-sort rather than rebuild.
+                 */
+                program.order = map.order;
+                program.occlusion = map.occlusion;
+
+                arbitration = true;
+            }
+        }
+
+        if (stale.length > 0) {
+            this.#recompile(stale);
+        } else if (arbitration) {
+            this.#reorder();
+        }
+    }
+
+    #recompileAll() {
+        const previous = [];
+
+        for (const program of this.#programs.values()) {
+            previous.push(program);
+        }
+
+        this.#recompile(previous);
+    }
+
+    /**
+     * Rebuild exactly the listed programs.
+     *
+     * Scoped rather than global on purpose: a compile discards the matcher state of everything it rebuilds,
+     * so recompiling every map because one of them was edited would reset every other map's half-matched
+     * sequences and half-matured holds. With several contexts live at once - which is the normal case - that
+     * is a player losing an input they were part way through for a reason nowhere near them.
+     *
+     * @param {InputMapProgram[]} programs
+     */
+    #recompile(programs) {
+        for (let i = 0; i < programs.length; i++) {
+            this.#release(programs[i]);
+        }
+
+        for (let i = 0; i < programs.length; i++) {
+            const program = this.#compile(programs[i].map, programs[i].entity);
+
+            this.#programs.set(program.entity, program);
+
+            program.map.attachProgram(program);
+        }
+
+        this.#reorder();
+    }
+
+    /**
+     * Sort programs by descending order and recompute suppression. Ties keep link order, so arbitration is
+     * deterministic even when two maps pick the same number.
+     */
+    #reorder() {
+        const ordered = [];
+
+        for (const program of this.#programs.values()) {
+            ordered.push(program);
+        }
+
+        ordered.sort((a, b) => b.order - a.order);
+
+        this.#ordered = ordered;
+
+        let blocked = false;
+
+        for (let i = 0; i < ordered.length; i++) {
+            const program = ordered[i];
+
+            const was = program.suppressed;
+
+            program.suppressed = blocked;
+
+            if (was && !blocked) {
+                /*
+                Coming back from under a modal. Everything resumes against current reality rather than
+                against whatever was true when the modal opened, so a half-matched sequence does not get to
+                complete on one further step.
+                 */
+                for (let t = 0; t < program.triggers.length; t++) {
+                    program.triggers[t].trigger.reset(this.#held, this.#time);
+                }
+            }
+
+            if (program.occlusion === InputOcclusion.BlockAll) {
+                blocked = true;
+            }
+        }
+    }
+}
+
+/**
+ * Specificity order: more sequence steps first, then wider chords, then declaration order. Total, so a
+ * result never depends on which binding happened to be written first.
+ *
+ * @param {CompiledTrigger[]} entries
+ */
+function sortBySpecificity(entries) {
+    for (let i = 0; i < entries.length; i++) {
+        entries[i].declarationOrder = i;
+    }
+
+    entries.sort((a, b) => {
+        const steps = b.trigger.stepCount - a.trigger.stepCount;
+
+        if (steps !== 0) {
+            return steps;
+        }
+
+        const width = b.trigger.width - a.trigger.width;
+
+        if (width !== 0) {
+            return width;
+        }
+
+        return a.declarationOrder - b.declarationOrder;
+    });
+}