@realnation/builder-shared-sdk 2.5.0 → 2.6.0

package/dist/gamepad/session.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The wheel session: one poller, one device, one set of subscribers.
+ *
+ * The host owns exactly one of these and passes a lifecycle-stripped facade to
+ * modules, mirroring how the runner owns the Runtime connection. A federated
+ * remote must never create its own: subpath imports are bundled per remote, so
+ * every remote that called `createGamepad()` would get its own poller reading
+ * the same device, and every device profile would be frozen into whichever SDK
+ * version that remote was built against.
+ */
+import type { ControlName } from './controls.js';
+import type { GamepadProfile, ProfileLookup } from './profiles.js';
+import type { ControlEvent, Thresholds } from './signals.js';
+import type { GamepadSource } from './source.js';
+export type Unsubscribe = () => void;
+/**
+ * `waiting` means the API is there but no supported wheel is: a kiosk whose
+ * wheel is unplugged, or a phone. It is a normal resting state, not an error.
+ */
+export type GamepadState = 'idle' | 'waiting' | 'ready' | 'lost';
+export type GamepadMissReason = 'NO_API' | 'NO_DEVICE' | 'UNKNOWN_DEVICE';
+export interface GamepadStatus {
+    ok: boolean;
+    reason?: GamepadMissReason;
+    /** The device that was seen, even when it was rejected. */
+    deviceId?: string;
+    profileId?: string;
+    profileName?: string;
+}
+export interface AxesUpdate {
+    /** -1 full left, 1 full right. */
+    steering: number;
+    throttle: number;
+    brake: number;
+    clutch: number;
+}
+export interface CreateGamepadOptions {
+    source?: 'live' | 'mock' | GamepadSource;
+    profiles?: readonly GamepadProfile[];
+    /** Overrides the profile's thresholds. Mainly for the tuning lab. */
+    thresholds?: Partial<Thresholds>;
+    /** How long `connect()` waits for a device to appear. */
+    waitMs?: number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+export declare class GamepadSession {
+    private readonly source;
+    private readonly profiles;
+    private readonly thresholdOverrides?;
+    private readonly waitMs;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly controlHandlers;
+    private readonly anyHandlers;
+    private readonly axesHandlers;
+    private readonly stateHandlers;
+    private signals;
+    private reading;
+    private profile;
+    private thresholds;
+    private currentState;
+    private lastLookup;
+    private closed;
+    private polling;
+    constructor(options?: CreateGamepadOptions);
+    get state(): GamepadState;
+    /** The matched profile, or null while no supported device is connected. */
+    get activeProfile(): GamepadProfile | null;
+    /**
+     * Looks for a supported wheel and starts polling if one is there.
+     *
+     * Resolving with `ok: false` is not fatal: the session keeps polling and
+     * flips to `ready` the moment a supported wheel shows up, which is what lets
+     * a player plug one in mid-session. The status is what the permission gate
+     * shows the operator.
+     *
+     * Chrome only exposes gamepads after a user gesture on the page, so calling
+     * this straight after load can legitimately report NO_DEVICE; the gate's
+     * button press is that gesture.
+     */
+    connect(): Promise<GamepadStatus>;
+    /**
+     * Adopts a profile and the thresholds that come with it.
+     *
+     * Shared by the connect-time probe and the frame loop so that a caller
+     * reading `activeProfile` straight after a successful `connect()` sees the
+     * device, rather than null until the first animation frame lands.
+     */
+    private adoptProfile;
+    /** One-shot look at what is connected right now. */
+    private probe;
+    private startPolling;
+    private onFrame;
+    private readControls;
+    private flushReleases;
+    private emitEvents;
+    private emitAxes;
+    private setState;
+    readonly controls: {
+        /** Subscribes to one control. Returns the unsubscribe function. */
+        on: (control: ControlName, handler: (event: ControlEvent) => void) => Unsubscribe;
+        /** Every control. The runner's key bridge is the intended consumer. */
+        onAny: (handler: (event: ControlEvent) => void) => Unsubscribe;
+        /** Whether a control is down right now. */
+        isPressed: (control: ControlName) => boolean;
+    };
+    readonly axes: {
+        /**
+         * Per-frame analog readings, for games that steer proportionally.
+         *
+         * Do not bind this into a reactive template: it fires on every animation
+         * frame. Canvas games should read it and draw (same caution as the
+         * runtime SDK's player facade).
+         */
+        onUpdate: (handler: (update: AxesUpdate) => void) => Unsubscribe;
+        current: () => AxesUpdate;
+    };
+    onStateChange(handler: (state: GamepadState) => void): Unsubscribe;
+    /** The device seen last, matched or not. For operator-facing messages. */
+    get device(): ProfileLookup | null;
+    /**
+     * Releases anything held and stops polling, without ending the session.
+     *
+     * The host calls this when the page is hidden or loses focus: animation
+     * frames stop there anyway, so a press held across the boundary would never
+     * see its release.
+     */
+    suspend(): void;
+    /** Resumes after `suspend()`. */
+    resume(): void;
+    /** Ends the session. Host-only: the facade handed to modules hides it. */
+    close(): void;
+    /** Alias for `close()`, matching the runtime SDK's shape. */
+    dispose(): void;
+}
+export declare function createGamepad(options?: CreateGamepadOptions): GamepadSession;
+/** English text for a failed connect, for the permission gate to show. */
+export declare function explainGamepadMiss(status: GamepadStatus): string;
+//# sourceMappingURL=session.d.ts.map

package/dist/gamepad/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/gamepad/session.ts"],"names":[],"mappings":"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"}

package/dist/gamepad/session.js

@@ -0,0 +1,305 @@
+import { BUTTON_CONTROLS } from './controls.js';
+import { decodeHat, readBinding } from './normalize.js';
+import { PROFILES, axisBinding, buttonBinding, selectDevice } from './profiles.js';
+import { EMPTY_SIGNAL_STATE, emptyReading, releaseAll, resolveThresholds, stepSignals } from './signals.js';
+import { LiveGamepadSource, MockGamepadSource } from './source.js';
+function buildSource(option) {
+    if (!option || option === 'live')
+        return new LiveGamepadSource();
+    if (option === 'mock')
+        return new MockGamepadSource();
+    return option;
+}
+export class GamepadSession {
+    source;
+    profiles;
+    thresholdOverrides;
+    waitMs;
+    setTimer;
+    clearTimer;
+    controlHandlers = new Map();
+    anyHandlers = new Set();
+    axesHandlers = new Set();
+    stateHandlers = new Set();
+    signals = EMPTY_SIGNAL_STATE;
+    reading = emptyReading();
+    profile = null;
+    thresholds = resolveThresholds();
+    currentState = 'idle';
+    lastLookup = null;
+    closed = false;
+    polling = false;
+    constructor(options = {}) {
+        this.source = buildSource(options.source);
+        this.profiles = options.profiles ?? PROFILES;
+        this.thresholdOverrides = options.thresholds;
+        this.waitMs = options.waitMs ?? 0;
+        this.setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = options.clearTimer ?? ((h) => clearTimeout(h));
+    }
+    get state() {
+        return this.currentState;
+    }
+    /** The matched profile, or null while no supported device is connected. */
+    get activeProfile() {
+        return this.profile;
+    }
+    /**
+     * Looks for a supported wheel and starts polling if one is there.
+     *
+     * Resolving with `ok: false` is not fatal: the session keeps polling and
+     * flips to `ready` the moment a supported wheel shows up, which is what lets
+     * a player plug one in mid-session. The status is what the permission gate
+     * shows the operator.
+     *
+     * Chrome only exposes gamepads after a user gesture on the page, so calling
+     * this straight after load can legitimately report NO_DEVICE; the gate's
+     * button press is that gesture.
+     */
+    async connect() {
+        if (this.closed)
+            throw new Error('This gamepad session is closed.');
+        if (!this.source.supported)
+            return { ok: false, reason: 'NO_API' };
+        this.startPolling();
+        const immediate = this.probe();
+        if (immediate.ok || this.waitMs <= 0)
+            return immediate;
+        return new Promise((resolve) => {
+            const deadline = this.waitMs;
+            const started = Date.now();
+            const poll = () => {
+                if (this.closed)
+                    return resolve({ ok: false, reason: 'NO_DEVICE' });
+                const status = this.probe();
+                if (status.ok || Date.now() - started >= deadline)
+                    return resolve(status);
+                this.setTimer(poll, 120);
+            };
+            this.setTimer(poll, 120);
+        });
+    }
+    /**
+     * Adopts a profile and the thresholds that come with it.
+     *
+     * Shared by the connect-time probe and the frame loop so that a caller
+     * reading `activeProfile` straight after a successful `connect()` sees the
+     * device, rather than null until the first animation frame lands.
+     */
+    adoptProfile(profile) {
+        if (profile === this.profile)
+            return;
+        this.profile = profile;
+        this.thresholds = resolveThresholds({ ...profile.thresholds, ...this.thresholdOverrides });
+    }
+    /** One-shot look at what is connected right now. */
+    probe() {
+        const found = selectDevice(this.source.read(), this.profiles);
+        if (!found)
+            return { ok: false, reason: 'NO_DEVICE' };
+        this.lastLookup = found.lookup;
+        if (!found.lookup.profile) {
+            return { ok: false, reason: 'UNKNOWN_DEVICE', deviceId: found.lookup.deviceId };
+        }
+        this.adoptProfile(found.lookup.profile);
+        return {
+            ok: true,
+            deviceId: found.lookup.deviceId,
+            profileId: found.lookup.profile.id,
+            profileName: found.lookup.profile.name,
+        };
+    }
+    startPolling() {
+        if (this.polling || this.closed)
+            return;
+        this.polling = true;
+        this.setState('waiting');
+        this.source.start((pads) => this.onFrame(pads));
+    }
+    onFrame(pads) {
+        if (this.closed)
+            return;
+        const found = selectDevice(pads, this.profiles);
+        const profile = found?.lookup.profile ?? null;
+        this.lastLookup = found?.lookup ?? null;
+        if (!profile || !found) {
+            // The wheel went away mid-press. Release first, then report: a module in
+            // hold mode must see the release, and it must arrive before 'lost'.
+            if (this.profile)
+                this.emitEvents(this.flushReleases());
+            this.profile = null;
+            this.reading = emptyReading();
+            this.setState(this.currentState === 'ready' ? 'lost' : 'waiting');
+            return;
+        }
+        this.adoptProfile(profile);
+        this.setState('ready');
+        this.reading = this.readControls(found.pad, profile);
+        const { state, events } = stepSignals(this.signals, this.reading, this.thresholds);
+        this.signals = state;
+        this.emitAxes();
+        this.emitEvents(events);
+    }
+    readControls(pad, profile) {
+        const axisValue = (control) => {
+            const binding = axisBinding(profile, control);
+            return binding ? readBinding(binding, pad) : 0;
+        };
+        const buttons = {};
+        // 十字键先解码：它来自一根轴，四个方向是算出来的，不是四个键。
+        // 放在按键循环之前，万一某个型号两种都有，显式的按键映射优先。
+        if (profile.dpad) {
+            const hat = decodeHat(pad.axes[profile.dpad.index] ?? NaN, profile.dpad.released);
+            buttons['dpad-up'] = hat.up ? 1 : 0;
+            buttons['dpad-right'] = hat.right ? 1 : 0;
+            buttons['dpad-down'] = hat.down ? 1 : 0;
+            buttons['dpad-left'] = hat.left ? 1 : 0;
+        }
+        for (const control of BUTTON_CONTROLS) {
+            const binding = buttonBinding(profile, control);
+            if (binding)
+                buttons[control] = readBinding(binding, pad);
+        }
+        return {
+            steering: readBinding(profile.steering, pad),
+            throttle: axisValue('throttle'),
+            brake: axisValue('brake'),
+            clutch: axisValue('clutch'),
+            buttons,
+        };
+    }
+    flushReleases() {
+        const { state, events } = releaseAll(this.signals);
+        this.signals = state;
+        return events;
+    }
+    emitEvents(events) {
+        for (const event of events) {
+            for (const handler of this.anyHandlers)
+                handler(event);
+            const handlers = this.controlHandlers.get(event.control);
+            if (handlers)
+                for (const handler of handlers)
+                    handler(event);
+        }
+    }
+    emitAxes() {
+        if (!this.axesHandlers.size)
+            return;
+        const update = {
+            steering: this.reading.steering,
+            throttle: this.reading.throttle,
+            brake: this.reading.brake,
+            clutch: this.reading.clutch,
+        };
+        for (const handler of this.axesHandlers)
+            handler(update);
+    }
+    setState(state) {
+        if (this.currentState === state)
+            return;
+        this.currentState = state;
+        for (const handler of this.stateHandlers)
+            handler(state);
+    }
+    controls = {
+        /** Subscribes to one control. Returns the unsubscribe function. */
+        on: (control, handler) => {
+            let handlers = this.controlHandlers.get(control);
+            if (!handlers) {
+                handlers = new Set();
+                this.controlHandlers.set(control, handlers);
+            }
+            handlers.add(handler);
+            return () => handlers?.delete(handler);
+        },
+        /** Every control. The runner's key bridge is the intended consumer. */
+        onAny: (handler) => {
+            this.anyHandlers.add(handler);
+            return () => this.anyHandlers.delete(handler);
+        },
+        /** Whether a control is down right now. */
+        isPressed: (control) => this.signals[control] === true,
+    };
+    axes = {
+        /**
+         * Per-frame analog readings, for games that steer proportionally.
+         *
+         * Do not bind this into a reactive template: it fires on every animation
+         * frame. Canvas games should read it and draw (same caution as the
+         * runtime SDK's player facade).
+         */
+        onUpdate: (handler) => {
+            this.axesHandlers.add(handler);
+            return () => this.axesHandlers.delete(handler);
+        },
+        current: () => ({
+            steering: this.reading.steering,
+            throttle: this.reading.throttle,
+            brake: this.reading.brake,
+            clutch: this.reading.clutch,
+        }),
+    };
+    onStateChange(handler) {
+        this.stateHandlers.add(handler);
+        return () => this.stateHandlers.delete(handler);
+    }
+    /** The device seen last, matched or not. For operator-facing messages. */
+    get device() {
+        return this.lastLookup;
+    }
+    /**
+     * Releases anything held and stops polling, without ending the session.
+     *
+     * The host calls this when the page is hidden or loses focus: animation
+     * frames stop there anyway, so a press held across the boundary would never
+     * see its release.
+     */
+    suspend() {
+        if (!this.polling)
+            return;
+        this.emitEvents(this.flushReleases());
+        this.source.stop();
+        this.polling = false;
+        this.setState('waiting');
+    }
+    /** Resumes after `suspend()`. */
+    resume() {
+        if (this.closed || this.polling)
+            return;
+        this.startPolling();
+    }
+    /** Ends the session. Host-only: the facade handed to modules hides it. */
+    close() {
+        if (this.closed)
+            return;
+        this.emitEvents(this.flushReleases());
+        this.source.stop();
+        this.polling = false;
+        this.closed = true;
+        this.setState('idle');
+        this.controlHandlers.clear();
+        this.anyHandlers.clear();
+        this.axesHandlers.clear();
+        this.stateHandlers.clear();
+    }
+    /** Alias for `close()`, matching the runtime SDK's shape. */
+    dispose() {
+        this.close();
+    }
+}
+export function createGamepad(options = {}) {
+    return new GamepadSession(options);
+}
+/** English text for a failed connect, for the permission gate to show. */
+export function explainGamepadMiss(status) {
+    switch (status.reason) {
+        case 'NO_API':
+            return 'This browser cannot read game controllers. Use Chrome or Edge on the kiosk.';
+        case 'UNKNOWN_DEVICE':
+            return `This controller model is not supported yet${status.deviceId ? ` (${status.deviceId})` : ''}. Send this model name to the team to have it added.`;
+        case 'NO_DEVICE':
+        default:
+            return 'No racing wheel was found. Connect the wheel, then press any button on it.';
+    }
+}

package/dist/gamepad/signals.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Turning continuous readings into press and release.
+ *
+ * A wheel reports how far it is turned; the platform's existing physical-input
+ * contract only knows "pressed" and "released". This is where the two meet.
+ *
+ * Two lines, not one. A single threshold would chatter: a wheel resting near
+ * it, or a foot resting on a pedal, would fire press and release many times a
+ * second. Crossing the press line fires once; nothing more happens until the
+ * reading falls back inside the release line (PF 2026-09-20: one press per
+ * turn, no auto-repeat, matching Lane Runner's one-press-one-lane ruling).
+ *
+ * Pure: a snapshot in, the next snapshot and the events to emit out. The
+ * session owns the polling; this file can be reasoned about and tested on its
+ * own.
+ */
+import type { ControlName } from './controls.js';
+export interface Thresholds {
+    /** Fraction of full lock at which steering counts as turned. */
+    steeringPress: number;
+    steeringRelease: number;
+    /** Fraction of pedal travel at which a pedal counts as pressed. */
+    pedalPress: number;
+    pedalRelease: number;
+    buttonPress: number;
+    buttonRelease: number;
+}
+/**
+ * Starting values, to be tuned against the real wheel before release.
+ *
+ * Steering sits high so a hand resting slightly off centre does not steer;
+ * pedals sit low because timing games score the instant of the press, and a
+ * pedal that only registers when floored feels late. A profile may override
+ * any of these: a 900-degree wheel needs a much lower steering line than a
+ * 270-degree one to feel the same.
+ */
+export declare const DEFAULT_THRESHOLDS: Thresholds;
+export declare function resolveThresholds(overrides?: Partial<Thresholds>): Thresholds;
+/** Normalised readings for one frame. Steering is -1..1, everything else 0..1. */
+export interface ControlReading {
+    steering: number;
+    throttle: number;
+    brake: number;
+    clutch: number;
+    /** Per-role button readings, 0..1. Roles the device lacks are absent. */
+    buttons: Partial<Record<ControlName, number>>;
+}
+export interface ControlEvent {
+    control: ControlName;
+    pressed: boolean;
+}
+/** Which controls are currently down. The whole of the state machine's memory. */
+export type SignalState = Readonly<Partial<Record<ControlName, boolean>>>;
+export declare const EMPTY_SIGNAL_STATE: SignalState;
+export declare function emptyReading(): ControlReading;
+/**
+ * Advances the state machine by one frame.
+ *
+ * Only controls that changed produce events, so a held pedal emits exactly one
+ * press however long it is held. That is what keeps the runner's `e.repeat`
+ * contract intact for the timing games.
+ */
+export declare function stepSignals(previous: SignalState, reading: ControlReading, thresholds?: Thresholds): {
+    state: SignalState;
+    events: ControlEvent[];
+};
+/**
+ * Releases everything currently held.
+ *
+ * Called whenever polling is about to stop or the device goes away: a page
+ * hidden mid-corner stops its animation frames, and a press with no matching
+ * release leaves hold-style modules (Video Player) stuck playing forever.
+ */
+export declare function releaseAll(previous: SignalState): {
+    state: SignalState;
+    events: ControlEvent[];
+};
+//# sourceMappingURL=signals.d.ts.map

package/dist/gamepad/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../../src/gamepad/signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,eAAe,CAAC;AAG9D,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,UAOhC,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAE7E;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AAE1E,eAAO,MAAM,kBAAkB,EAAE,WAAgB,CAAC;AAElD,wBAAgB,YAAY,IAAI,cAAc,CAE7C;AAqDD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,cAAc,EACvB,UAAU,GAAE,UAA+B,GAC1C;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,YAAY,EAAE,CAAA;CAAE,CAmBhD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,YAAY,EAAE,CAAA;CAAE,CAMhG"}

package/dist/gamepad/signals.js

@@ -0,0 +1,112 @@
+import { AXIS_CONTROLS, BUTTON_CONTROLS } from './controls.js';
+/**
+ * Starting values, to be tuned against the real wheel before release.
+ *
+ * Steering sits high so a hand resting slightly off centre does not steer;
+ * pedals sit low because timing games score the instant of the press, and a
+ * pedal that only registers when floored feels late. A profile may override
+ * any of these: a 900-degree wheel needs a much lower steering line than a
+ * 270-degree one to feel the same.
+ */
+export const DEFAULT_THRESHOLDS = {
+    steeringPress: 0.35,
+    steeringRelease: 0.2,
+    pedalPress: 0.25,
+    pedalRelease: 0.12,
+    buttonPress: 0.5,
+    buttonRelease: 0.4,
+};
+export function resolveThresholds(overrides) {
+    return { ...DEFAULT_THRESHOLDS, ...overrides };
+}
+export const EMPTY_SIGNAL_STATE = {};
+export function emptyReading() {
+    return { steering: 0, throttle: 0, brake: 0, clutch: 0, buttons: {} };
+}
+function pedalReading(reading, control) {
+    switch (control) {
+        case 'throttle':
+            return reading.throttle;
+        case 'brake':
+            return reading.brake;
+        case 'clutch':
+            return reading.clutch;
+        default:
+            return 0;
+    }
+}
+/**
+ * How far one control is engaged, 0..1.
+ *
+ * The two steering directions read off the same signed axis, each seeing only
+ * its own side. That is what makes them mutually exclusive for free: turning
+ * left drives `wheel-right` to zero, which releases it.
+ */
+function engagement(reading, control) {
+    switch (control) {
+        case 'wheel-left':
+            return Math.max(0, -reading.steering);
+        case 'wheel-right':
+            return Math.max(0, reading.steering);
+        case 'throttle':
+        case 'brake':
+        case 'clutch':
+            return pedalReading(reading, control);
+        default:
+            return reading.buttons[control] ?? 0;
+    }
+}
+function linesFor(control, thresholds) {
+    switch (control) {
+        case 'wheel-left':
+        case 'wheel-right':
+            return [thresholds.steeringPress, thresholds.steeringRelease];
+        case 'throttle':
+        case 'brake':
+        case 'clutch':
+            return [thresholds.pedalPress, thresholds.pedalRelease];
+        default:
+            return [thresholds.buttonPress, thresholds.buttonRelease];
+    }
+}
+const ALL_CONTROLS = [...AXIS_CONTROLS, ...BUTTON_CONTROLS];
+/**
+ * Advances the state machine by one frame.
+ *
+ * Only controls that changed produce events, so a held pedal emits exactly one
+ * press however long it is held. That is what keeps the runner's `e.repeat`
+ * contract intact for the timing games.
+ */
+export function stepSignals(previous, reading, thresholds = DEFAULT_THRESHOLDS) {
+    const next = { ...previous };
+    const events = [];
+    for (const control of ALL_CONTROLS) {
+        const [press, release] = linesFor(control, thresholds);
+        const value = engagement(reading, control);
+        const wasDown = previous[control] === true;
+        if (!wasDown && value >= press) {
+            next[control] = true;
+            events.push({ control, pressed: true });
+        }
+        else if (wasDown && value <= release) {
+            next[control] = false;
+            events.push({ control, pressed: false });
+        }
+    }
+    return { state: next, events };
+}
+/**
+ * Releases everything currently held.
+ *
+ * Called whenever polling is about to stop or the device goes away: a page
+ * hidden mid-corner stops its animation frames, and a press with no matching
+ * release leaves hold-style modules (Video Player) stuck playing forever.
+ */
+export function releaseAll(previous) {
+    const events = [];
+    for (const control of ALL_CONTROLS) {
+        if (previous[control] === true)
+            events.push({ control, pressed: false });
+    }
+    return { state: EMPTY_SIGNAL_STATE, events };
+}