@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/input/gestures.js

@@ -0,0 +1,662 @@
+import { Loupe } from '../ui/loupe.js';
+import { resolveClock } from './clock.js';
+import { loupeClear, loupeSpot, MAGNIFY_DEFAULTS, magnifySize, } from './magnify.js';
+import { createPointerDispatcher, POINTER_PRIORITY, } from './pointer-dispatch.js';
+const DEFAULTS = {
+    panThreshold: 10,
+    longPressMs: 450,
+    doubleTapMs: 300,
+    doubleTapDistance: 24,
+};
+/** Most taps (of one kind) queued for later ticks. */
+const MAX_QUEUED = 8;
+/** Fraction of `panThreshold` past which a pointer is a pan candidate. */
+const CANDIDATE_FRACTION = 0.25;
+const CONTINUOUS = ['pan', 'drag', 'pinch'];
+/**
+ * Touch and pointer gestures: tap, double tap, long-press, pan, drag and pinch. Feed it pointer
+ * events (via `attach` or the public feed methods), call `update()` once per simulation tick,
+ * then read this tick's gestures. Thresholds are CSS px; positions are game space through the
+ * same `PointerTransform` as `Input`.
+ *
+ * ```ts
+ * const gestures = new Gestures();
+ * input.setGestures(gestures);   // shares blocked(), the transform, attach and update()
+ * // each tick, after input.update():
+ * if (gestures.tap) select(gestures.tap.x, gestures.tap.y);
+ * if (gestures.drag?.phase === 'move') moveBy(gestures.drag.dx, gestures.drag.dy);
+ * ```
+ *
+ * Or bind them as actions: `{ select: [{ gesture: 'tap' }], info: [{ gesture: 'longPress' }] }`.
+ *
+ * Rules:
+ * - A tap is a down and up that stays within `panThreshold` and ends before `longPressMs`. A
+ *   double tap also reports a tap for each of its two taps.
+ * - A long-press fires once, after `longPressMs` within the threshold; no tap follows it.
+ * - Moving past the threshold starts a pan and a drag (one pointer) for the rest of the press.
+ *   Travel is cumulative from the down point, so a slow drag crosses it too, and the threshold
+ *   is checked before the long-press timer on every move: a pointer whose travel crosses it
+ *   never long-presses, however long the frame took. A long-press that already fired stays.
+ * - A second pointer cancels the pan and drag (and any tap or long-press) and starts a pinch;
+ *   while two or more pointers are down, pan and drag report nothing (pinch wins). Lifting
+ *   either pointer ends the pinch; nothing more is reported until every pointer is up.
+ * - Discrete gestures that arrive faster than ticks are queued, one per kind per tick. Moves in
+ *   one tick are merged; `start` and `end` each get their own tick. While a pan, drag or pinch
+ *   runs, every tick reports it (a `move` with no change when nothing moved).
+ * - While `blocked()` nothing is reported, the press in progress is dropped, and a pan, drag or
+ *   pinch that had started gets one `cancel`, so the game can put things back.
+ */
+export class Gestures {
+    /** This tick's gestures, or `null`. */
+    tap = null;
+    doubleTap = null;
+    longPress = null;
+    pan = null;
+    drag = null;
+    pinch = null;
+    /** This tick's aim while one touch pointer is down (with the `magnify` option), or `null`. */
+    aim = null;
+    blocked;
+    panThreshold;
+    longPressMs;
+    doubleTapMs;
+    doubleTapDistance;
+    /** `GestureOptions.pan`: `'prefer'` keeps a pan candidate from long-pressing. */
+    panMode;
+    /**
+     * The pointer-claim hook (ws/input-3): called on every `pointerDown` with the pointer id and
+     * device; when it returns true the pointer is not a gesture (its moves and lift are ignored
+     * too). `Input.setLook` installs one so an orbit look drag never pans; a game may install its
+     * own when nothing is linked.
+     */
+    claim = null;
+    /**
+     * The clock gestures are timed on (`GestureOptions.now`). Recordings stamp pointer events on
+     * it and playbacks replay them on it (ws/input-7). `clock.now`, bound.
+     */
+    now;
+    /** The clock (`GestureOptions.clock`, or one wrapping `now`, or the wall clock). */
+    clock;
+    onPanCandidate;
+    transform = null;
+    session = null;
+    /** Last tap, for double taps: client position and end time. */
+    lastTap = null;
+    lastInside = { x: 0, y: 0, inside: false };
+    /** Taps; `double` marks the second tap of a double tap (reported on the same tick). */
+    taps = [];
+    longPresses = [];
+    pans = [];
+    drags = [];
+    pinches = [];
+    /** Continuous gestures reported as started and not yet ended, with their last report. */
+    running = new Map();
+    /** The session whose long-press has been reported, while its pointer stays down. */
+    longPressSession = null;
+    detachFn = null;
+    magnify;
+    loupe = null;
+    /** The aim at the moment the finger lifted, reported (with `ended`) on the next tick. */
+    endedAim = null;
+    /** `onGesture` listeners, called at recognition time. */
+    listeners = [];
+    constructor(opts = {}) {
+        this.panThreshold = opts.panThreshold ?? DEFAULTS.panThreshold;
+        this.longPressMs = opts.longPressMs ?? DEFAULTS.longPressMs;
+        this.doubleTapMs = opts.doubleTapMs ?? DEFAULTS.doubleTapMs;
+        this.doubleTapDistance = opts.doubleTapDistance ?? DEFAULTS.doubleTapDistance;
+        this.blocked = opts.blocked ?? (() => false);
+        const c = resolveClock(opts.clock, opts.now);
+        this.clock = c.clock;
+        this.now = c.now;
+        this.magnify = opts.magnify ?? null;
+        this.panMode = opts.pan ?? null;
+        this.onPanCandidate = opts.onPanCandidate ?? null;
+    }
+    /** Turn magnify on (or off with `null`) after construction. */
+    setMagnify(opts) {
+        this.magnify = opts;
+        this.aim = null;
+        this.loupe?.destroy();
+        this.loupe = null;
+    }
+    /** The loupe element, once one has been shown (for styling and tests). */
+    get loupeElement() {
+        return this.loupe?.el ?? null;
+    }
+    /** Install the client → game-space mapping. `null` = identity (relative to the target when attached). */
+    setPointerTransform(fn) {
+        this.transform = fn;
+        this.ownDispatcher?.setTransform(fn);
+    }
+    // ---------------------------------------------------------------- observer
+    /**
+     * Observe the gesture stream: `listener` is called synchronously each time a gesture is
+     * recognised (a tap on lift, a long-press when its time is up, a pan's `start`, every `move`,
+     * `end` or `cancel`), not once per tick. It is an observer for tests, replays and logging; the
+     * per-tick fields (`tap`, `drag`, ...) and action bindings stay the way a game reads gestures.
+     * Returns the unsubscribe function.
+     */
+    onGesture(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const i = this.listeners.indexOf(listener);
+            if (i >= 0)
+                this.listeners.splice(i, 1);
+        };
+    }
+    emit(kind, phase, g) {
+        const ls = this.listeners;
+        for (let i = 0; i < ls.length; i++)
+            ls[i]?.(kind, phase, g);
+    }
+    // ---------------------------------------------------------------- queries
+    /**
+     * True while `kind` drives an action binding: on the tick a tap or double tap is reported;
+     * from a long-press until its pointer lifts; on a pan, drag or pinch's `start` and `move` ticks.
+     */
+    active(kind) {
+        switch (kind) {
+            case 'tap':
+                return this.tap !== null;
+            case 'doubleTap':
+                return this.doubleTap !== null;
+            case 'longPress':
+                return this.longPress !== null || this.longPressSession !== null;
+            default:
+                return this.running.has(kind);
+        }
+    }
+    /** True when `kind` was reported fresh this tick: a new tap, double tap, long-press or `start`. */
+    fired(kind) {
+        switch (kind) {
+            case 'tap':
+            case 'doubleTap':
+            case 'longPress':
+                return this[kind] !== null;
+            default:
+                return this[kind]?.phase === 'start';
+        }
+    }
+    // ---------------------------------------------------------------- tick
+    /** Advance one tick: fire due long-presses and publish one report per kind. */
+    update() {
+        const t = this.now();
+        if (this.blocked()) {
+            this.clearQueues();
+            if (this.session)
+                this.session.void = true;
+            this.longPressSession = null;
+            this.tap = null;
+            this.doubleTap = null;
+            this.longPress = null;
+            // A pan, drag or pinch that had started is cancelled once; nothing else is reported.
+            this.lastTap = null;
+            this.pan = this.cancelled('pan');
+            this.drag = this.cancelled('drag');
+            this.pinch = this.cancelled('pinch');
+            if (this.pan)
+                this.emit('pan', 'cancel', this.pan);
+            if (this.drag)
+                this.emit('drag', 'cancel', this.drag);
+            if (this.pinch)
+                this.emit('pinch', 'cancel', this.pinch);
+            this.running.clear();
+            this.updateAim();
+            return;
+        }
+        this.checkLongPress(t);
+        const tap = this.taps.shift();
+        this.tap = tap?.tap ?? null;
+        this.doubleTap = tap?.double ? tap.tap : null;
+        this.longPress = this.longPresses.shift() ?? null;
+        if (this.longPress && this.session?.longPressed && !this.session.void) {
+            this.longPressSession = this.session;
+        }
+        this.pan = this.publish('pan', this.pans, mergePan, idlePan);
+        this.drag = this.publish('drag', this.drags, mergePan, idlePan);
+        this.pinch = this.publish('pinch', this.pinches, mergePinch, idlePinch);
+        this.updateAim();
+    }
+    /**
+     * This tick's aim (the `magnify` option): one touch pointer down, not blocked, `when()`. The
+     * aim point is the finger, raised by `lift` while it drags; `snap` picks the target; the
+     * loupe shows while the pitch is below `below` and the aim is over the targets.
+     */
+    updateAim() {
+        const m = this.magnify;
+        const s = this.session;
+        const c = s && !s.void && !s.multi ? s.contacts.values().next().value : null;
+        // The aim the finger lifted at comes with the drag's `end` (moves before it get their own
+        // ticks first, still aiming there).
+        let ended = this.endedAim;
+        if (ended && this.drags.length > 0)
+            ended = { ...ended, ended: false };
+        else
+            this.endedAim = null;
+        const aim = !m || this.blocked() ? null : c ? this.aimOf(m, c, s?.moving === true) : ended;
+        this.aim = aim;
+        if (!m?.source || !aim?.loupe || aim.ended) {
+            this.loupe?.hide();
+            return;
+        }
+        const size = magnifySize(m);
+        if (this.loupe && this.loupe.size !== size) {
+            this.loupe.destroy();
+            this.loupe = null;
+        }
+        this.loupe ??= new Loupe(m.source, {
+            size,
+            zoom: m.zoom ?? MAGNIFY_DEFAULTS.zoom,
+            className: m.className,
+            parent: m.parent,
+        });
+        let ring = null;
+        const t = aim.target;
+        if (t) {
+            const to = m.toClient ?? ((tx, ty) => ({ x: tx, y: ty }));
+            const a = to(t.x, t.y);
+            const b = to(t.x + t.r, t.y);
+            ring = { x: a.x, y: a.y, r: Math.abs(b.x - a.x) };
+        }
+        this.loupe.show({ focus: aim.client, at: aim.at, ring, leader: m.leader ? ring : null });
+    }
+    /** The aim of touch contact `c` (`null` for mouse and pen, or while `when()` is false). */
+    aimOf(m, c, lifted) {
+        if (c.device !== 'touch' || (m.when && !m.when()))
+            return null;
+        const lift = lifted ? (m.lift ?? MAGNIFY_DEFAULTS.lift) : 0;
+        const finger = { x: c.lastX, y: c.lastY };
+        const client = { x: c.lastX, y: c.lastY - lift };
+        const p = this.transform ? this.transform(client.x, client.y) : { x: client.x, y: client.y };
+        const inside = p !== null;
+        const x = p?.x ?? this.lastInside.x;
+        const y = p?.y ?? this.lastInside.y;
+        const target = inside && m.snap ? m.snap(x, y) : null;
+        const over = inside && (m.over ? m.over(x, y) : target !== null);
+        const size = magnifySize(m);
+        const loupe = over && m.pitch() < (m.below ?? MAGNIFY_DEFAULTS.below);
+        const win = (m.source?.ownerDocument ?? globalThis.document)?.defaultView;
+        const view = win
+            ? { width: win.innerWidth, height: win.innerHeight }
+            : { width: Number.POSITIVE_INFINITY, height: Number.POSITIVE_INFINITY };
+        const room = loupe && m.clear ? m.clear(target, { x, y }) : null;
+        const at = room
+            ? loupeClear(finger, client, size, view, room.keep, room.avoid, room.spare)
+            : loupeSpot(finger, client, size, view);
+        return { x, y, inside, client, finger, lifted, target, loupe, at, ended: false };
+    }
+    /** The `cancel` report for a running `kind` (blocked), or `null`. */
+    cancelled(kind) {
+        const last = this.running.get(kind);
+        if (!last)
+            return null;
+        return (kind === 'pinch'
+            ? { ...last, phase: 'cancel', delta: 1 }
+            : { ...last, phase: 'cancel', dx: 0, dy: 0 });
+    }
+    /**
+     * This tick's report for `kind`: the next queued event (consecutive moves merged), or, while
+     * the gesture runs with nothing new, the last report as a `move` with no change.
+     */
+    publish(kind, queue, merge, idle) {
+        let e = queue.shift();
+        if (!e) {
+            const last = this.running.get(kind);
+            return last ? idle(last) : null;
+        }
+        if (e.phase === 'move') {
+            while (queue[0]?.phase === 'move')
+                e = merge(e, queue.shift());
+        }
+        if (e.phase === 'end' || e.phase === 'cancel')
+            this.running.delete(kind);
+        else
+            this.running.set(kind, e);
+        return e;
+    }
+    clearQueues() {
+        this.taps.length = 0;
+        this.longPresses.length = 0;
+        this.pans.length = 0;
+        this.drags.length = 0;
+        this.pinches.length = 0;
+    }
+    // ---------------------------------------------------------------- low-level feed
+    // Public so tests, replays and automated playtests can drive gestures without a DOM. Positions
+    // are client coordinates (CSS px), run through the transform. `time` defaults to the clock.
+    pointerDown(id, clientX, clientY, device = 'touch', time = this.now()) {
+        if (this.claim?.(id, device))
+            return;
+        if (!this.session) {
+            if (this.blocked())
+                return;
+            this.session = {
+                contacts: new Map(),
+                moving: false,
+                multi: false,
+                void: false,
+                longPressed: false,
+                pinchStartDist: 0,
+                pinchLastDist: 0,
+                pinching: false,
+                centreLast: null,
+                last: null,
+                at: null,
+            };
+        }
+        const s = this.session;
+        if (s.contacts.has(id))
+            return;
+        const contact = {
+            id,
+            device,
+            downAt: time,
+            startX: clientX,
+            startY: clientY,
+            lastX: clientX,
+            lastY: clientY,
+            origin: this.map(clientX, clientY),
+            travel: 0,
+            candidate: false,
+        };
+        s.contacts.set(id, contact);
+        if (s.void || s.contacts.size !== 2) {
+            // A third pointer is ignored; it still has to lift before the session ends.
+            return;
+        }
+        // Second pointer: the press becomes a pinch; a running pan and drag are cancelled, and
+        // neither reports again until every pointer is up.
+        s.multi = true;
+        this.endOnePointer(s, s.contacts.values().next().value, 'cancel');
+        const [a, b] = [...s.contacts.values()];
+        s.pinchStartDist = Math.max(1, dist(a.lastX, a.lastY, b.lastX, b.lastY));
+        s.pinchLastDist = s.pinchStartDist;
+        const centre = this.map((a.lastX + b.lastX) / 2, (a.lastY + b.lastY) / 2);
+        s.centreLast = centre;
+        s.pinching = true;
+        this.pushPinch({ phase: 'start', ...centre, scale: 1, delta: 1 });
+    }
+    pointerMove(id, clientX, clientY, time = this.now()) {
+        const s = this.session;
+        const c = s?.contacts.get(id);
+        if (!s || !c || (clientX === c.lastX && clientY === c.lastY))
+            return;
+        c.travel += dist(c.lastX, c.lastY, clientX, clientY);
+        c.lastX = clientX;
+        c.lastY = clientY;
+        if (!c.candidate && c.travel > this.panThreshold * CANDIDATE_FRACTION) {
+            c.candidate = true;
+            this.onPanCandidate?.(id, c.travel);
+        }
+        if (s.void)
+            return;
+        if (s.multi) {
+            this.moveTwo(s);
+            return;
+        }
+        if (s.longPressed)
+            return;
+        if (!s.moving) {
+            // The threshold first: travel that crosses it is a pan, however late this move arrives
+            // (a long frame), and the pending long-press is dropped. Only a still pointer may long-press.
+            if (c.travel <= this.panThreshold) {
+                this.checkLongPress(time);
+                return;
+            }
+            s.moving = true;
+            s.last = c.origin;
+            const p = this.map(clientX, clientY);
+            this.pushMove(s, c, p, 'start');
+            return;
+        }
+        this.pushMove(s, c, this.map(clientX, clientY), 'move');
+    }
+    pointerUp(id, clientX, clientY, time = this.now()) {
+        const s = this.session;
+        const c = s?.contacts.get(id);
+        if (!s || !c)
+            return;
+        if (clientX !== undefined && clientY !== undefined)
+            this.pointerMove(id, clientX, clientY, time);
+        if (this.magnify && !s.void && !s.multi && !this.blocked()) {
+            const aim = this.aimOf(this.magnify, c, s.moving);
+            this.endedAim = aim ? { ...aim, ended: true } : null;
+        }
+        s.contacts.delete(id);
+        if (this.longPressSession === s)
+            this.longPressSession = null;
+        if (!s.void) {
+            if (s.multi) {
+                this.endTwo(s, 'end');
+                s.void = true;
+            }
+            else if (s.moving) {
+                this.endOnePointer(s, c, 'end');
+            }
+            else if (!s.longPressed) {
+                if (time - c.downAt >= this.longPressMs) {
+                    // Held long enough but no tick saw it (a stalled frame): still a long-press, not a tap.
+                    // A pan candidate under `pan: 'prefer'` was on its way to a pan: nothing.
+                    if (!this.preferPan(c))
+                        this.longPressOf(s, c);
+                }
+                else {
+                    this.emitTap(c, time);
+                }
+            }
+        }
+        if (s.contacts.size === 0)
+            this.session = null;
+    }
+    /** The browser took the pointer (system gesture, palm rejection): drop the press. */
+    pointerCancel(id) {
+        const s = this.session;
+        if (!s?.contacts.has(id))
+            return;
+        this.cancelSession(s);
+        s.contacts.delete(id);
+        if (s.contacts.size === 0)
+            this.session = null;
+    }
+    /** Drop every pointer (focus loss, tab hidden). A started pan, drag or pinch is cancelled. */
+    cancelAll() {
+        const s = this.session;
+        if (s)
+            this.cancelSession(s);
+        this.session = null;
+        this.longPressSession = null;
+    }
+    cancelSession(s) {
+        if (!s.void) {
+            if (s.multi)
+                this.endTwo(s, 'cancel');
+            else
+                this.endOnePointer(s, s.contacts.values().next().value, 'cancel');
+        }
+        s.void = true;
+        if (this.longPressSession === s)
+            this.longPressSession = null;
+    }
+    // ---------------------------------------------------------------- recognisers
+    checkLongPress(t) {
+        const s = this.session;
+        if (!s || s.void || s.multi || s.moving || s.longPressed)
+            return;
+        const c = s.contacts.values().next().value;
+        if (!c || t - c.downAt < this.longPressMs || this.preferPan(c))
+            return;
+        this.longPressOf(s, c);
+    }
+    /** True when `c` may no longer long-press: a pan candidate under `pan: 'prefer'`. */
+    preferPan(c) {
+        return this.panMode === 'prefer' && c.candidate;
+    }
+    longPressOf(s, c) {
+        s.longPressed = true;
+        const g = { ...c.origin, device: c.device };
+        push(this.longPresses, g);
+        this.emit('longPress', 'end', g);
+    }
+    emitTap(c, time) {
+        const prev = this.lastTap;
+        const double = prev !== null &&
+            c.downAt - prev.at <= this.doubleTapMs &&
+            dist(prev.x, prev.y, c.startX, c.startY) <= this.doubleTapDistance;
+        const tap = { ...c.origin, device: c.device };
+        push(this.taps, { tap, double });
+        this.lastTap = double ? null : { x: c.startX, y: c.startY, at: time };
+        this.emit('tap', 'end', tap);
+        if (double)
+            this.emit('doubleTap', 'end', tap);
+    }
+    pushMove(s, c, p, phase) {
+        const last = s.last ?? c.origin;
+        const dx = p.inside && last.inside ? p.x - last.x : 0;
+        const dy = p.inside && last.inside ? p.y - last.y : 0;
+        const at = p.inside ? p : { ...last, inside: false };
+        s.last = p.inside ? p : last;
+        s.at = at;
+        this.pushPan(c, phase, at, dx, dy);
+    }
+    /** Queues one pan and one drag report and tells the listeners. */
+    pushPan(c, phase, at, dx, dy) {
+        const pan = { phase, ...at, dx, dy, pointers: 1, device: c.device };
+        const drag = { phase, ...at, origin: c.origin, dx, dy, device: c.device };
+        this.pans.push(pan);
+        this.drags.push(drag);
+        this.emit('pan', phase, pan);
+        this.emit('drag', phase, drag);
+    }
+    pushPinch(e) {
+        push(this.pinches, e);
+        this.emit('pinch', e.phase, e);
+    }
+    /** Ends (or cancels) a one-pointer pan and drag, if one is running in `s`. */
+    endOnePointer(s, c, phase) {
+        if (!s.moving)
+            return;
+        s.moving = false;
+        this.pushPan(c, phase, s.at ?? c.origin, 0, 0);
+    }
+    /** Two pointers: only the pinch moves. Their centre moving is not a pan (pinch wins). */
+    moveTwo(s) {
+        const [a, b] = [...s.contacts.values()];
+        const d = Math.max(1, dist(a.lastX, a.lastY, b.lastX, b.lastY));
+        const centre = this.map((a.lastX + b.lastX) / 2, (a.lastY + b.lastY) / 2);
+        if (centre.inside)
+            s.centreLast = centre;
+        if (d === s.pinchLastDist)
+            return;
+        const delta = d / s.pinchLastDist;
+        s.pinchLastDist = d;
+        const at = centre.inside ? centre : { ...(s.centreLast ?? centre), inside: false };
+        this.pushPinch({ phase: 'move', ...at, scale: d / s.pinchStartDist, delta });
+    }
+    endTwo(s, phase) {
+        if (!s.pinching)
+            return;
+        s.pinching = false;
+        const e = {
+            phase,
+            ...(s.centreLast ?? this.lastInside),
+            scale: s.pinchLastDist / s.pinchStartDist,
+            delta: 1,
+        };
+        this.pinches.push(e);
+        this.emit('pinch', phase, e);
+    }
+    map(clientX, clientY) {
+        const p = this.transform ? this.transform(clientX, clientY) : { x: clientX, y: clientY };
+        if (p) {
+            this.lastInside = { x: p.x, y: p.y, inside: true };
+            return { x: p.x, y: p.y, inside: true };
+        }
+        return { x: this.lastInside.x, y: this.lastInside.y, inside: false };
+    }
+    // ---------------------------------------------------------------- DOM
+    /**
+     * Listen to pointer events on the target. Mouse: the primary button only. Touch and pen: up
+     * to two contacts. The target captures each pointer, so a drag off its edge keeps reporting.
+     * `Input.setGestures` calls this from `Input.attach`; call it yourself only when the gestures
+     * are used without an `Input`.
+     */
+    attach(opts) {
+        this.detach();
+        const target = opts.pointerTarget;
+        const prevTouchAction = target.style.touchAction;
+        if (opts.disableTouchScroll !== false)
+            target.style.touchAction = 'none';
+        const shared = opts.dispatcher ?? null;
+        const dispatcher = shared ?? createPointerDispatcher(target, { transform: this.transform });
+        if (!shared)
+            this.ownDispatcher = dispatcher;
+        const remove = dispatcher.add(this.consumer, POINTER_PRIORITY.gestures);
+        this.detachFn = () => {
+            remove();
+            if (!shared)
+                dispatcher.destroy();
+            this.ownDispatcher = null;
+            target.style.touchAction = prevTouchAction;
+        };
+    }
+    /** The private dispatcher a standalone `attach` built, or `null` (shared or detached). */
+    ownDispatcher = null;
+    /**
+     * The dispatcher consumer: mouse primary button only; every touch and pen contact. Each event
+     * is timed by its `timeStamp` (`eventTime`: `now() - age`), not by when it was handled, so a
+     * tap delivered after a stalled frame is still a tap; a replayed event by its recorded time.
+     */
+    consumer = {
+        pointerDown: (p) => {
+            if (p.device === 'mouse' && p.button !== 0)
+                return;
+            this.pointerDown(p.id, p.x, p.y, p.device, this.now() - p.age);
+        },
+        pointerMove: (p) => this.pointerMove(p.id, p.x, p.y, this.now() - p.age),
+        pointerUp: (p) => {
+            if (p.device === 'mouse' && p.button !== 0)
+                return;
+            this.pointerUp(p.id, p.x, p.y, this.now() - p.age);
+        },
+        pointerCancel: (p) => this.pointerCancel(p.id),
+        cancelAll: () => this.cancelAll(),
+    };
+    detach() {
+        this.detachFn?.();
+        this.detachFn = null;
+        this.cancelAll();
+        this.aim = null;
+        this.endedAim = null;
+        this.loupe?.hide();
+    }
+    /** Detach and remove the loupe element. */
+    destroy() {
+        this.detach();
+        this.loupe?.destroy();
+        this.loupe = null;
+    }
+}
+function dist(ax, ay, bx, by) {
+    return Math.hypot(bx - ax, by - ay);
+}
+function push(queue, e) {
+    if (queue.length < MAX_QUEUED)
+        queue.push(e);
+}
+function idlePan(last) {
+    return { ...last, phase: 'move', dx: 0, dy: 0 };
+}
+function idlePinch(last) {
+    return { ...last, phase: 'move', delta: 1 };
+}
+function mergePan(a, b) {
+    return { ...b, dx: a.dx + b.dx, dy: a.dy + b.dy };
+}
+function mergePinch(a, b) {
+    return { ...b, delta: a.delta * b.delta };
+}
+/** `new Gestures(opts)`: gestures, on `opts.clock` when given (ws/input-8). */
+export function createGestures(opts = {}) {
+    return new Gestures(opts);
+}

package/dist/input/glyphs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Prompt glyphs (ws/input-3): the label a game shows for a binding ("Space", "A", "Cross", "Tap"),
+ * chosen for the device the player last used. Pure tables, no DOM; `Input.glyphFor(action,
+ * device?)` picks the binding and calls `glyphForBinding`. The engine draws nothing: `kind` says
+ * which icon set a game's UI should reach for, `label` is the text.
+ */
+import type { Binding, InputDevice } from './types.js';
+/** What a glyph stands for. */
+export type GlyphKind = 'key' | 'button' | 'axis' | 'pointer' | 'gesture' | 'xr';
+/** A prompt glyph: `kind` picks the icon set, `label` is the text. */
+export interface Glyph {
+    kind: GlyphKind;
+    label: string;
+}
+/** Button naming families. `guessPadLayout(gamepad.id)` picks one; `InputOptions.padLayout` overrides. */
+export type PadLayout = 'xbox' | 'playstation' | 'nintendo' | 'generic';
+/** The pad layout for a `Gamepad.id` (vendor words and USB vendor ids), `'generic'` when unknown. */
+export declare function guessPadLayout(id: string | undefined): PadLayout;
+/** Standard-mapping pad button `index` in `layout` (`'Button 7'` past the table or for `'generic'`). */
+export declare function padButtonLabel(index: number, layout?: PadLayout): string;
+/** Standard-mapping pad axis `axis` pushed in `dir`: `'LS →'`, `'RS ↑'`, or `'Axis 4 +'` past the sticks. */
+export declare function padAxisLabel(axis: number, dir: 1 | -1): string;
+/**
+ * Display text for a `KeyboardEvent.code`: `'KeyA'` → `'A'`, `'Digit1'` → `'1'`, `'Numpad1'` →
+ * `'Num 1'`, `'F5'` → `'F5'`, arrows as arrows, modifiers without their side; unknown codes are
+ * split at their capitals (`'AudioVolumeUp'` → `'Audio Volume Up'`).
+ */
+export declare function keyLabel(code: string): string;
+/**
+ * The glyph for one binding. A chord joins its members with ` + ` and takes the first member's
+ * kind; `trigger: 'hold'` prefixes `Hold `, `'doubleTap'` prefixes `Double-tap `.
+ */
+export declare function glyphForBinding(b: Binding, layout?: PadLayout): Glyph;
+/** True when `b` is what `device` produces, so its glyph is the one to show for that device. */
+export declare function bindingMatchesDevice(b: Binding, device: InputDevice): boolean;