@driftengine/core 3.61.0

package/dist/input/inputHarness.d.ts

@@ -0,0 +1,42 @@
+import { type GamepadAxis, type GamepadButton } from './gamepadMapping.ts';
+export declare function fakeBrowser(id?: string): {
+    target: HTMLElement;
+    /**
+     * How many times the poll asked the browser for pads.
+     *
+     * The number the once-a-frame rule is asserted on: `getGamepads` allocates an array and the
+     * objects behind it, so a read that called it again would multiply that by however many
+     * buttons a frame looks at.
+     */
+    calls: {
+        getGamepads: number;
+    };
+    /** Every effect the poll's pad was asked to play, in order, with the parameters it was given. */
+    effects: {
+        type: string;
+        params: Record<string, number>;
+    }[];
+    /** How many times the actuator was reset, which is what stopping a rumble does. */
+    readonly resets: number;
+    /**
+     * Whether this pad carries an actuator, and whether that actuator carries `reset`.
+     *
+     * Both are real states a browser produces: a keyboard-shaped pad has no actuator at all, and an
+     * older Chromium's actuator has `playEffect` without `reset`.
+     */
+    rumbleSupport(present: boolean, options?: {
+        reset?: boolean;
+        fail?: boolean;
+    }): void;
+    connect(nextId?: string, nextMapping?: string): void;
+    disconnect(): void;
+    press(button: GamepadButton): void;
+    release(button: GamepadButton): void;
+    axis(axis: GamepadAxis, value: number): void;
+    /** Press a key, as the window would deliver it. `target` is nothing a game is typing into. */
+    keyDown(code: string): void;
+    keyUp(code: string): void;
+    /** Run exactly one animation frame, which is what a poll rides on. */
+    frame(): void;
+    restore(): void;
+};

package/dist/input/inputHarness.js

@@ -0,0 +1,193 @@
+import { AXIS_INDEX, BUTTON_INDEX, } from './gamepadMapping.js';
+export function fakeBrowser(id = 'Xbox 360 Controller (XInput STANDARD GAMEPAD)') {
+    const buttons = Array.from({ length: 17 }, () => ({ pressed: false, value: 0 }));
+    const axes = [0, 0, 0, 0];
+    let connected = false;
+    let mapping = 'standard';
+    let padId = id;
+    /**
+     * A fresh array every call, and fresh button objects behind it — **because the real one does
+     * that too**, and the poll's whole design rests on it. A harness that handed back the same array
+     * would let a renderer read it many times a frame and never show the cost.
+     */
+    const calls = { getGamepads: 0 };
+    /**
+     * The rumble half, recorded rather than felt.
+     *
+     * **A haptic effect has no observable result in a test**, which is exactly why the surface answers
+     * a boolean rather than nothing: what can be asserted is whether the platform took the call and
+     * what it was handed. So the effects are recorded here and the tests read them.
+     *
+     * `hasActuator` is a switch rather than a fixture, because the capability under test is largely
+     * the *refusal*: most pads on most browsers cannot rumble, and a settings screen has to know.
+     */
+    const effects = [];
+    let resets = 0;
+    let hasActuator = true;
+    let hasReset = true;
+    let failEffect = false;
+    const actuator = {
+        playEffect: (type, params) => {
+            effects.push({ type, params: { ...params } });
+            return failEffect
+                ? Promise.reject(new Error('the pad went away'))
+                : Promise.resolve('complete');
+        },
+        reset: () => {
+            resets += 1;
+            return Promise.resolve('complete');
+        },
+    };
+    const getGamepads = () => {
+        calls.getGamepads += 1;
+        if (!connected)
+            return [null];
+        return [
+            {
+                id: padId,
+                index: 0,
+                mapping,
+                connected: true,
+                buttons: buttons.map((b) => ({ pressed: b.pressed, value: b.value })),
+                axes: axes.slice(),
+                vibrationActuator: hasActuator
+                    ? hasReset
+                        ? actuator
+                        : { playEffect: actuator.playEffect }
+                    : null,
+            },
+        ];
+    };
+    const frameCallbacks = [];
+    let nextFrameHandle = 1;
+    const target = {
+        addEventListener: () => { },
+        removeEventListener: () => { },
+        requestPointerLock: () => undefined,
+        getBoundingClientRect: () => ({ left: 0, top: 0, width: 640, height: 480 }),
+    };
+    const globals = globalThis;
+    const had = {};
+    const install = (name, value) => {
+        had[name] = { present: name in globals, value: globals[name] };
+        /* `defineProperty` rather than assignment: `navigator` is a getter on the Node global and
+           assigning to it is silently ignored, which would leave the poll reading the real one. */
+        Object.defineProperty(globals, name, { value, configurable: true, writable: true });
+    };
+    /** Window listeners this harness can fire, so a key is a statement rather than a real event. */
+    const windowListeners = new Map();
+    install('window', {
+        matchMedia: () => ({ matches: false }),
+        addEventListener: (type, fn) => {
+            const existing = windowListeners.get(type);
+            if (existing === undefined)
+                windowListeners.set(type, [fn]);
+            else
+                existing.push(fn);
+        },
+        removeEventListener: (type, fn) => {
+            const existing = windowListeners.get(type);
+            if (existing === undefined)
+                return;
+            const at = existing.indexOf(fn);
+            if (at >= 0)
+                existing.splice(at, 1);
+        },
+    });
+    install('document', {
+        addEventListener: () => { },
+        removeEventListener: () => { },
+        pointerLockElement: null,
+        visibilityState: 'visible',
+    });
+    install('navigator', { getGamepads });
+    install('requestAnimationFrame', (fn) => {
+        frameCallbacks.push(fn);
+        return nextFrameHandle++;
+    });
+    install('cancelAnimationFrame', () => { });
+    const indexOfButton = (button) => BUTTON_INDEX[button];
+    return {
+        target,
+        /**
+         * How many times the poll asked the browser for pads.
+         *
+         * The number the once-a-frame rule is asserted on: `getGamepads` allocates an array and the
+         * objects behind it, so a read that called it again would multiply that by however many
+         * buttons a frame looks at.
+         */
+        calls,
+        /** Every effect the poll's pad was asked to play, in order, with the parameters it was given. */
+        effects,
+        /** How many times the actuator was reset, which is what stopping a rumble does. */
+        get resets() {
+            return resets;
+        },
+        /**
+         * Whether this pad carries an actuator, and whether that actuator carries `reset`.
+         *
+         * Both are real states a browser produces: a keyboard-shaped pad has no actuator at all, and an
+         * older Chromium's actuator has `playEffect` without `reset`.
+         */
+        rumbleSupport(present, options = {}) {
+            hasActuator = present;
+            hasReset = options.reset ?? true;
+            failEffect = options.fail ?? false;
+        },
+        connect(nextId = padId, nextMapping = 'standard') {
+            padId = nextId;
+            mapping = nextMapping;
+            connected = true;
+        },
+        disconnect() {
+            connected = false;
+        },
+        press(button) {
+            const at = buttons[indexOfButton(button)];
+            if (at !== undefined) {
+                at.pressed = true;
+                at.value = 1;
+            }
+        },
+        release(button) {
+            const at = buttons[indexOfButton(button)];
+            if (at !== undefined) {
+                at.pressed = false;
+                at.value = 0;
+            }
+        },
+        axis(axis, value) {
+            axes[AXIS_INDEX[axis]] = value;
+        },
+        /** Press a key, as the window would deliver it. `target` is nothing a game is typing into. */
+        keyDown(code) {
+            for (const fn of windowListeners.get('keydown') ?? []) {
+                fn({ code, repeat: false, target: null, preventDefault: () => { } });
+            }
+        },
+        keyUp(code) {
+            for (const fn of windowListeners.get('keyup') ?? [])
+                fn({ code });
+        },
+        /** Run exactly one animation frame, which is what a poll rides on. */
+        frame() {
+            const pending = frameCallbacks.splice(0, frameCallbacks.length);
+            for (const fn of pending)
+                fn(0);
+        },
+        restore() {
+            for (const [name, before] of Object.entries(had)) {
+                if (before.present) {
+                    Object.defineProperty(globals, name, {
+                        value: before.value,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
+                else {
+                    delete globals[name];
+                }
+            }
+        },
+    };
+}

package/dist/input/rightGesture.d.ts

@@ -0,0 +1,57 @@
+/**
+ * What a drag on the look zone turns out to be.
+ *
+ * Separated from `TouchControls` because it is the one part of touch handling
+ * with a right answer that can be checked without a device: everything else is
+ * DOM plumbing, but this is a classification, and getting it wrong silently
+ * removes a control rather than breaking one visibly.
+ */
+export type RightGesture = 'pending' | 'look' | 'secondary';
+export interface RightGestureOptions {
+    /** Travel before a drag is classified at all, pixels. */
+    gestureMovePx: number;
+    /** A flick has to finish inside this to count as one, milliseconds. */
+    swipeMaxMs: number;
+    /** Vertical travel over horizontal required to read as a deliberate flick. */
+    swipeDominance: number;
+}
+/**
+ * Classify a drag from its travel and duration.
+ *
+ * The bias is deliberate and one-way: **when in doubt, it is a look.** Looking
+ * is continuous and constant, the secondary flick is occasional, and the two
+ * failure modes are not equal — a missed flick costs one slide, while a look
+ * wrongly eaten costs the camera for the whole gesture, which is felt as the
+ * controls being broken rather than as a missed input.
+ *
+ * That asymmetry is exactly what went wrong: any quick downward drag was read
+ * as a flick, so trying to look *down* quickly did not move the camera at all.
+ * Looking left and right stayed fine, because no gesture competes for it.
+ */
+export declare function classifyRightGesture(dx: number, dy: number, elapsedMs: number, options: RightGestureOptions): RightGesture;
+/**
+ * Whether a released touch was a tap, and therefore fires the primary.
+ *
+ * Stated as its own rule because getting it wrong is how the primary went
+ * missing. The press used to be queued only for a touch still *unresolved* at
+ * release — but a motionless touch is promoted to the held form after
+ * `holdResolveMs`, which the caller runs on a frame clock, so every tap longer
+ * than that resolve was discarded. On a phone that is most of them: a
+ * comfortable tap is 80 to 150 ms against a 90 ms resolve, which is exactly the
+ * shape of *"sometimes the jump is missed."*
+ *
+ * So a tap is defined by what it *did*, not by which state it happened to be
+ * parked in: it stayed inside `gestureMovePx` of where it landed and it was
+ * short. A touch that travelled further has already been read as a look or a
+ * flick and did its work there; firing a press on its release as well would put
+ * a jump on the end of every camera drag, which is the complaint this scheme
+ * was built to fix.
+ *
+ * `travelPx` is the *greatest* distance reached from the start, not the
+ * distance at release: a thumb that swings out and returns is not a tap, and
+ * measuring only the final point cannot tell the two apart.
+ */
+export declare function isTapRelease(travelPx: number, durationMs: number, options: {
+    gestureMovePx: number;
+    tapMaxMs: number;
+}): boolean;

package/dist/input/rightGesture.js

@@ -0,0 +1,49 @@
+/**
+ * Classify a drag from its travel and duration.
+ *
+ * The bias is deliberate and one-way: **when in doubt, it is a look.** Looking
+ * is continuous and constant, the secondary flick is occasional, and the two
+ * failure modes are not equal — a missed flick costs one slide, while a look
+ * wrongly eaten costs the camera for the whole gesture, which is felt as the
+ * controls being broken rather than as a missed input.
+ *
+ * That asymmetry is exactly what went wrong: any quick downward drag was read
+ * as a flick, so trying to look *down* quickly did not move the camera at all.
+ * Looking left and right stayed fine, because no gesture competes for it.
+ */
+export function classifyRightGesture(dx, dy, elapsedMs, options) {
+    if (Math.hypot(dx, dy) < options.gestureMovePx)
+        return 'pending';
+    const quick = elapsedMs < options.swipeMaxMs;
+    // Downward only, and steeply so: dy is positive toward the bottom of the
+    // screen, and a flick that is merely mostly-down is far likelier to be
+    // somebody looking at the ground.
+    if (quick && dy > 0 && dy > options.swipeDominance * Math.abs(dx))
+        return 'secondary';
+    return 'look';
+}
+/**
+ * Whether a released touch was a tap, and therefore fires the primary.
+ *
+ * Stated as its own rule because getting it wrong is how the primary went
+ * missing. The press used to be queued only for a touch still *unresolved* at
+ * release — but a motionless touch is promoted to the held form after
+ * `holdResolveMs`, which the caller runs on a frame clock, so every tap longer
+ * than that resolve was discarded. On a phone that is most of them: a
+ * comfortable tap is 80 to 150 ms against a 90 ms resolve, which is exactly the
+ * shape of *"sometimes the jump is missed."*
+ *
+ * So a tap is defined by what it *did*, not by which state it happened to be
+ * parked in: it stayed inside `gestureMovePx` of where it landed and it was
+ * short. A touch that travelled further has already been read as a look or a
+ * flick and did its work there; firing a press on its release as well would put
+ * a jump on the end of every camera drag, which is the complaint this scheme
+ * was built to fix.
+ *
+ * `travelPx` is the *greatest* distance reached from the start, not the
+ * distance at release: a thumb that swings out and returns is not a tap, and
+ * measuring only the final point cannot tell the two apart.
+ */
+export function isTapRelease(travelPx, durationMs, options) {
+    return travelPx <= options.gestureMovePx && durationMs < options.tapMaxMs;
+}

package/dist/input/rumble.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Driving a controller's motors, and saying so when the platform cannot.
+ *
+ * **The refusal is half the capability.** Most pads on most browsers have no actuator at all, and a
+ * settings screen that offers a rumble slider a player's hardware ignores is worse than one that
+ * greys it out. So every verb here answers a boolean — the same rule the host seam keeps for a
+ * window mode a shell cannot enter — rather than accepting the call and doing nothing quietly.
+ *
+ * **The engine takes durations and magnitudes, and nothing else.** A magnitude is a fraction of a
+ * motor and a duration is milliseconds; what a rumble *means* is the consumer's. There is no
+ * pattern language, no named effect and no curve, because every one of those would be a decision
+ * about what a game does with the hardware.
+ *
+ * ## What this reaches, and what it does not
+ *
+ * `GamepadHapticActuator.playEffect('dual-rumble', …)` and nothing else. Two motors of different
+ * masses, which is what a standard pad has: `strong` is the low-frequency one and `weak` the
+ * high-frequency one.
+ *
+ * **`hapticActuators[].pulse` is not used, on purpose.** It is a non-standard surface with a
+ * different model — one magnitude where this has two — so serving it would mean either dropping
+ * the weak motor or averaging the pair, and both are a silent lie about what the caller asked for.
+ * A platform with only `pulse` answers `false` and is greyed out, which is true rather than
+ * convenient. **What would make that wrong** is a measurement on a browser a consumer actually
+ * ships to where `pulse` exists and `vibrationActuator` does not.
+ *
+ * **Trigger rumble is not reached either.** `'trigger-rumble'` drives two more motors that only
+ * some pads have, so it needs its own capability answer beside `canRumble` rather than riding this
+ * one; it is a row of its own the day somebody wants it.
+ */
+/**
+ * The actuator, named here so this file does not depend on lib.dom's version of it.
+ *
+ * `reset` is optional because an older Chromium ships `playEffect` without it, and a pad that can
+ * play an effect can always be stopped by a zero one — which is what `stopRumble` falls back to.
+ */
+export interface RawHapticActuator {
+    playEffect(type: string, params: Readonly<Record<string, number>>): Promise<string>;
+    reset?(): Promise<string>;
+}
+/**
+ * The specification's ceiling on one effect, in milliseconds.
+ *
+ * Clamped here rather than left to the platform, because a longer request is not an error the
+ * caller can see: the promise resolves with a word nobody reads, and browsers differ on whether
+ * they clamp it or drop it. A caller wanting a longer rumble re-issues, which it has to anyway —
+ * any effect can be preempted by the next one.
+ */
+export declare const MAX_RUMBLE_MS = 5000;
+/**
+ * Play one dual-rumble effect. Answers whether the platform took it.
+ *
+ * `false` means the caller should stop offering the control, and it is answered for three separate
+ * states that are one thing to a player: no actuator, an actuator this browser cannot drive, and a
+ * duration there is nothing to play for.
+ *
+ * A rejection is swallowed and reported through `onFailure`, once per pad. `playEffect` rejects
+ * when the pad goes away mid-effect, which is a thing a player does with a cable; an unhandled
+ * rejection is a stack trace nobody can act on, and silence leaves a player whose pad stopped
+ * rumbling with nothing to read. **This never throws**, because it is reachable from a frame.
+ */
+export declare function playRumble(actuator: RawHapticActuator | null, durationMs: number, strong: number, weak: number, onFailure: () => void): boolean;
+/**
+ * Stop whatever is playing. Answers whether the platform took it.
+ *
+ * `reset` where the actuator has one, and a zero effect where it does not — a zero-magnitude,
+ * zero-duration effect preempts the one in flight, which is the same result by the specification's
+ * own rule about preemption. Answering `false` for a missing `reset` would grey out a control the
+ * hardware can honour.
+ */
+export declare function stopRumble(actuator: RawHapticActuator | null, onFailure: () => void): boolean;

package/dist/input/rumble.js

@@ -0,0 +1,119 @@
+/**
+ * Driving a controller's motors, and saying so when the platform cannot.
+ *
+ * **The refusal is half the capability.** Most pads on most browsers have no actuator at all, and a
+ * settings screen that offers a rumble slider a player's hardware ignores is worse than one that
+ * greys it out. So every verb here answers a boolean — the same rule the host seam keeps for a
+ * window mode a shell cannot enter — rather than accepting the call and doing nothing quietly.
+ *
+ * **The engine takes durations and magnitudes, and nothing else.** A magnitude is a fraction of a
+ * motor and a duration is milliseconds; what a rumble *means* is the consumer's. There is no
+ * pattern language, no named effect and no curve, because every one of those would be a decision
+ * about what a game does with the hardware.
+ *
+ * ## What this reaches, and what it does not
+ *
+ * `GamepadHapticActuator.playEffect('dual-rumble', …)` and nothing else. Two motors of different
+ * masses, which is what a standard pad has: `strong` is the low-frequency one and `weak` the
+ * high-frequency one.
+ *
+ * **`hapticActuators[].pulse` is not used, on purpose.** It is a non-standard surface with a
+ * different model — one magnitude where this has two — so serving it would mean either dropping
+ * the weak motor or averaging the pair, and both are a silent lie about what the caller asked for.
+ * A platform with only `pulse` answers `false` and is greyed out, which is true rather than
+ * convenient. **What would make that wrong** is a measurement on a browser a consumer actually
+ * ships to where `pulse` exists and `vibrationActuator` does not.
+ *
+ * **Trigger rumble is not reached either.** `'trigger-rumble'` drives two more motors that only
+ * some pads have, so it needs its own capability answer beside `canRumble` rather than riding this
+ * one; it is a row of its own the day somebody wants it.
+ */
+/**
+ * The specification's ceiling on one effect, in milliseconds.
+ *
+ * Clamped here rather than left to the platform, because a longer request is not an error the
+ * caller can see: the promise resolves with a word nobody reads, and browsers differ on whether
+ * they clamp it or drop it. A caller wanting a longer rumble re-issues, which it has to anyway —
+ * any effect can be preempted by the next one.
+ */
+export const MAX_RUMBLE_MS = 5000;
+/**
+ * The parameters, claimed once.
+ *
+ * `playEffect` converts this to a dictionary synchronously at the call, so one object rewritten in
+ * place is safe and is what the hot-path rule asks for even though a rumble is an event rather
+ * than a frame.
+ */
+const params = {
+    duration: 0,
+    startDelay: 0,
+    strongMagnitude: 0,
+    weakMagnitude: 0,
+};
+function clamp01(value) {
+    if (!(value > 0))
+        return 0;
+    return value > 1 ? 1 : value;
+}
+/**
+ * Play one dual-rumble effect. Answers whether the platform took it.
+ *
+ * `false` means the caller should stop offering the control, and it is answered for three separate
+ * states that are one thing to a player: no actuator, an actuator this browser cannot drive, and a
+ * duration there is nothing to play for.
+ *
+ * A rejection is swallowed and reported through `onFailure`, once per pad. `playEffect` rejects
+ * when the pad goes away mid-effect, which is a thing a player does with a cable; an unhandled
+ * rejection is a stack trace nobody can act on, and silence leaves a player whose pad stopped
+ * rumbling with nothing to read. **This never throws**, because it is reachable from a frame.
+ */
+export function playRumble(actuator, durationMs, strong, weak, onFailure) {
+    if (actuator === null || typeof actuator.playEffect !== 'function')
+        return false;
+    if (!(durationMs > 0))
+        return false;
+    params.duration = durationMs > MAX_RUMBLE_MS ? MAX_RUMBLE_MS : durationMs;
+    params.strongMagnitude = clamp01(strong);
+    params.weakMagnitude = clamp01(weak);
+    return dispatch(actuator, onFailure);
+}
+/**
+ * Stop whatever is playing. Answers whether the platform took it.
+ *
+ * `reset` where the actuator has one, and a zero effect where it does not — a zero-magnitude,
+ * zero-duration effect preempts the one in flight, which is the same result by the specification's
+ * own rule about preemption. Answering `false` for a missing `reset` would grey out a control the
+ * hardware can honour.
+ */
+export function stopRumble(actuator, onFailure) {
+    if (actuator === null || typeof actuator.playEffect !== 'function')
+        return false;
+    if (typeof actuator.reset === 'function') {
+        swallow(actuator.reset(), onFailure);
+        return true;
+    }
+    params.duration = 0;
+    params.strongMagnitude = 0;
+    params.weakMagnitude = 0;
+    return dispatch(actuator, onFailure);
+}
+function dispatch(actuator, onFailure) {
+    /*
+     * The call itself is guarded, not only its promise. A browser that rejects the *arguments* throws
+     * synchronously rather than rejecting, and this is reachable from a frame — where the house rule
+     * is that nothing throws.
+     */
+    try {
+        swallow(actuator.playEffect('dual-rumble', params), onFailure);
+    }
+    catch {
+        onFailure();
+        return false;
+    }
+    return true;
+}
+function swallow(result, onFailure) {
+    if (result === undefined || typeof result.then !== 'function')
+        return;
+    void result.then(undefined, onFailure);
+}

package/dist/input/touchControls.d.ts

@@ -0,0 +1,138 @@
+/** Configurable two-zone mobile controls over raw touch input. */
+import { InputSource } from './input.ts';
+export interface TouchControlsOptions {
+    /**
+     * The two nodes the stick is *drawn* with, when a caller wants one drawn.
+     *
+     * **Optional, and that is a correction rather than a convenience.** These were positional
+     * arguments and read as dependencies — a consumer who could not reach the page concluded the
+     * class needed two elements to work, and constructed two `div`s it never appended anywhere so
+     * the input maths would run. It does not need them: they are an *output channel*, written to and
+     * never read. Every touch comes from `input.target`, and every number this class reports is
+     * computed without either node.
+     *
+     * So absent means the stick has no visible representation and the controls work exactly as they
+     * did, which is what a consumer drawing its own HUD, drawing none, or forbidden the page wants.
+     * `stickBase` takes `hidden` and a position; `stickNub` takes a transform.
+     */
+    stickBase?: HTMLElement;
+    stickNub?: HTMLElement;
+    /** Fraction of the input surface assigned to the dynamic stick. */
+    splitRatio?: number;
+    stickRadiusPx?: number;
+    stickDeadzone?: number;
+    gestureMovePx?: number;
+    holdResolveMs?: number;
+    /**
+     * How long a touch may last and still fire the primary on release.
+     *
+     * The press fires on release, so this duration *is* the action's input
+     * latency, and a caller whose action has a grace window of its own — a
+     * platformer's coyote time — wants the two sized against each other. Set it
+     * past that window and a tap begun at the edge of a drop resolves after the
+     * body is unjumpably in the air.
+     */
+    tapMaxMs?: number;
+    /**
+     * Whether holding the second zone still also *fires* the primary, or only holds it.
+     *
+     * The default is only-holds, and it is the fix for a real complaint from phone
+     * testing: a still thumb kept firing the primary action, so there was no way to hold
+     * position and look. A thumb placed down and held is what looking around
+     * *starts* with, so resolving it into a press fires the action every time somebody
+     * lines up a camera move. There is no threshold that separates "still thumb" from
+     * "about to look", because they are the same input.
+     *
+     * A tap still fires on release, which is where the intent actually is; and the hold
+     * still reports `primaryHeld`, so a caller whose action has a held form — a glide, a
+     * charge — keeps it. Only the *edge* from a motionless press is gone.
+     *
+     * The promotion is not a verdict, and reading it as one is what later ate the tap:
+     * a touch promoted to the hold and released quickly is still a tap, because the
+     * player's thumb did the thing a tap is. See `isTapRelease`.
+     */
+    fireOnHold?: boolean;
+    swipeMaxMs?: number;
+    /** Vertical travel divided by horizontal travel required for a swipe. */
+    swipeDominance?: number;
+}
+/**
+ * A reusable mobile scheme: dynamic stick on the first zone; look plus a
+ * primary tap/hold and secondary downward swipe on the second. The class
+ * reports generic control state. A game decides whether those signals mean
+ * jump, fire, crouch, slide, or anything else.
+ */
+export declare class TouchControls {
+    moveX: number;
+    moveY: number;
+    primaryHeld: boolean;
+    secondaryHeld: boolean;
+    onFirstTouch: (() => void) | null;
+    private primaryQueued;
+    private lookDx;
+    private lookDy;
+    private leftId;
+    private rightId;
+    private rightMode;
+    private rightLastX;
+    private rightLastY;
+    /** Greatest distance the owning touch has reached from where it landed. */
+    private rightTravel;
+    private rightStart;
+    private firstTouchSeen;
+    private readonly extraIds;
+    private readonly extraTravel;
+    private readonly extraSliding;
+    /** Whether the owning touch is the one holding the secondary. */
+    private ownerSliding;
+    private readonly stickBase;
+    private readonly stickNub;
+    private readonly surface;
+    private readonly splitRatio;
+    private readonly stickRadiusPx;
+    private readonly stickDeadzone;
+    private readonly gestureMovePx;
+    private readonly holdResolveMs;
+    private readonly tapMaxMs;
+    private readonly fireOnHold;
+    private readonly swipeMaxMs;
+    private readonly swipeDominance;
+    private readonly unsubscribe;
+    /**
+     * Take the input surface, and optionally the two nodes the stick is drawn with.
+     *
+     * **Two forms, and the older one is kept working rather than deprecated.** It was
+     * `(input, stickBase, stickNub, options)`, which put an output channel where a reader expects a
+     * dependency — a consumer forbidden the page read the signature, concluded the class could not be
+     * used without two `HTMLElement`s, and built two it threw away. The options form says what is
+     * true: the elements are how the stick is *drawn*, and drawing it is optional.
+     *
+     * `new TouchControls(input)` is a working control scheme with no visible stick.
+     */
+    constructor(input: InputSource, options?: TouchControlsOptions);
+    constructor(input: InputSource, stickBase: HTMLElement, stickNub: HTMLElement, options?: TouchControlsOptions);
+    /** Resolve a still second-zone touch into the generic primary hold. */
+    tick(nowMs: number): void;
+    /** Consume the primary edge exactly once. */
+    consumePrimaryPress(): boolean;
+    /** Drain accumulated second-zone look motion into a caller-owned object. */
+    consumeLook(out: {
+        dx: number;
+        dy: number;
+    }): void;
+    dispose(): void;
+    private onStart;
+    private onMove;
+    private onEnd;
+    private claimExtra;
+    private extraSlot;
+    private moveExtra;
+    private endExtra;
+    /** The secondary is held while *any* touch in the zone is holding it. */
+    private refreshSecondary;
+    private classify;
+    private isTap;
+    private showStick;
+    private updateStick;
+    private validateOptions;
+}