@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/input/clock.js

@@ -0,0 +1,49 @@
+/**
+ * The clock gestures and look are timed on (ws/input-8). By default that is `performance.now()`
+ * (wall time). A game with a fixed step passes one `createTickClock()` to both and advances it
+ * from the step, so long-presses, double taps, look acceleration and `Look.onTap` run on game
+ * time, and a recording replays the same gestures on the same tick indices however far apart
+ * the replay's ticks are in wall time.
+ */
+/** `performance.now()` (or `Date.now()` where there is no `performance`): the default clock. */
+export const wallClock = {
+    now: () => (typeof performance !== 'undefined' ? performance.now() : Date.now()),
+};
+/**
+ * A game-time clock for gestures and look. Call `advance(stepMs)` from the fixed step, before
+ * `input.update()`, and pass the same clock to `createGestures({ clock })` and
+ * `createLook({ clock })` so the two share one time base. `start` is the first reading
+ * (default 0).
+ *
+ * ```ts
+ * const clock = createTickClock();
+ * const input = new Input(bindings, {
+ *   gestures: createGestures({ clock }),
+ *   look: createLook({ clock }),
+ * });
+ * // GameLoop `update(dt)`, in fixed steps of `dt` seconds:
+ * clock.advance(dt * 1000);
+ * input.update();
+ * ```
+ */
+export function createTickClock(start = 0) {
+    let t = Number.isFinite(start) ? start : 0;
+    return {
+        now: () => t,
+        advance(ms) {
+            if (ms > 0 && Number.isFinite(ms))
+                t += ms;
+        },
+    };
+}
+/**
+ * The clock options gestures and look accept resolved to one clock and its bound `now`:
+ * `clock` wins over the older `now` function, and with neither it is `wallClock`.
+ */
+export function resolveClock(clock, now) {
+    if (clock)
+        return { clock, now: () => clock.now() };
+    if (now)
+        return { clock: { now }, now };
+    return { clock: wallClock, now: wallClock.now };
+}

package/dist/input/follow.d.ts

@@ -0,0 +1,133 @@
+import type { Camera } from '../render/camera.js';
+import type { Look } from './look.js';
+import type { Vec3 } from './rays.js';
+/** The part of `Camera` a `Follow` drives: it only ever calls `lookAt`. */
+export type FollowCamera = Pick<Camera, 'lookAt'>;
+/** `'third'`: orbit behind the target. `'first'`: through its eyes, same yaw and pitch. */
+export type FollowMode = 'first' | 'third';
+/** What the camera follows. The game owns the object and moves it; `Follow` reads it each frame. */
+export interface FollowSubject {
+    /** The target's feet (or centre), world units. `eyeHeight` is added for the pivot. */
+    position: ArrayLike<number>;
+    /**
+     * The target's facing, radians (same convention as `yaw`: 0 is -z, positive turns right).
+     * With `realign` set, the orbit eases back to it while nobody is looking around.
+     */
+    yaw?: number;
+}
+/**
+ * The game's line-of-sight test (the engine has no world). `from` is the pivot, `to` the camera
+ * position the orbit wants. Return true and write the first obstacle point into `outHit` to pull
+ * the camera in to `outHit` minus `margin`; return false for a clear line.
+ */
+export type FollowObstacle = (from: Vec3, to: Vec3, outHit: Vec3) => boolean;
+export interface FollowOptions {
+    /** Orbit radius wanted, world units. Default 4. */
+    distance?: number;
+    /** `zoom()` floor. Default 1. */
+    minDistance?: number;
+    /** `zoom()` ceiling. Default 12. */
+    maxDistance?: number;
+    /** Over-the-shoulder offset of the pivot, camera right and up, world units. Default `[0, 0]`. */
+    shoulder?: readonly [number, number];
+    /** Pitch floor, radians (negative looks down; the orbit rises above the target). Default -1.2. */
+    pitchMin?: number;
+    /** Pitch ceiling, radians. Default 1.2. */
+    pitchMax?: number;
+    /**
+     * Time constant, seconds, of the pivot's approach to the target and of the distance's recovery
+     * after an obstacle (it snaps in, eases out). 0 follows exactly. Default 0.12.
+     */
+    smoothing?: number;
+    /** Height of the pivot (and the first-person eye) above `target.position`. Default 1.6. */
+    eyeHeight?: number;
+    /** World units one `zoom(1)` step changes `distance` by. Default 0.5. */
+    zoomStep?: number;
+    /** Line-of-sight test from the pivot to the wanted camera position. Default none. */
+    obstacle?: FollowObstacle;
+    /** Pull-back from an obstacle point along the line to the pivot, world units. Default 0.2. */
+    margin?: number;
+    /**
+     * Time constant, seconds, of the orbit yaw easing back to `target.yaw` while the look input
+     * is still. 0 (default) never realigns.
+     */
+    realign?: number;
+    /** Starting orbit yaw, radians. Default 0 (behind a target facing -z). */
+    yaw?: number;
+    /** Starting pitch, radians. Default -0.35 (a little above, looking down). */
+    pitch?: number;
+    /** Starting mode. Default `'third'`. */
+    mode?: FollowMode;
+}
+/**
+ * A third-person camera that follows a target, orbits from the same `look` deltas `Look` reports,
+ * swings in on obstacles the game reports, and becomes a first-person camera with one
+ * assignment (`mode = 'first'`). Each `update(dt)` reads the linked `Look` (or the yaw and pitch
+ * the game set), places the eye and calls `camera.lookAt`. Nothing allocates per frame.
+ *
+ * Conventions match `Look` and the look harness: yaw 0 looks down -z and positive yaw turns
+ * right; positive pitch looks up (so in third person the camera sinks below the pivot; negative
+ * pitch raises it). The pivot is `target.position + (0, eyeHeight, 0)` shifted by `shoulder`
+ * along the camera's right and up; the eye sits `distance` behind it along the view direction.
+ *
+ * ```ts
+ * const follow = new Follow(camera, { distance: 5, shoulder: [0.6, 0], obstacle: world.raycast });
+ * follow.target = player;              // { position: Float32Array(3), yaw }
+ * follow.setLook(look);
+ * // each tick, after input.update():
+ * follow.update(dt);                   // the look's zoom axis (wheel, pinch, pad) steps distance
+ * if (input.pressed('view')) follow.mode = follow.mode === 'third' ? 'first' : 'third';
+ * ```
+ */
+export declare class Follow {
+    /** What to follow. Until set, the pivot is at the origin. */
+    target: FollowSubject | null;
+    /** Orbit yaw, radians (0 is -z, positive turns right). The `Look` adds to it. */
+    yaw: number;
+    /** View pitch, radians, clamped to `pitchMin..pitchMax` each update. */
+    pitch: number;
+    /** Orbit radius wanted; `currentDistance` is what an obstacle left of it. `zoom()` steps it. */
+    distance: number;
+    mode: FollowMode;
+    minDistance: number;
+    maxDistance: number;
+    pitchMin: number;
+    pitchMax: number;
+    smoothing: number;
+    eyeHeight: number;
+    zoomStep: number;
+    margin: number;
+    realign: number;
+    obstacle: FollowObstacle | null;
+    /** Shoulder offset (camera right, up). Mutate in place. */
+    readonly shoulder: [number, number];
+    /** The eye placed by the last `update`, world units. Read-only. */
+    readonly position: Vec3;
+    /** The smoothed pivot the camera orbits (and looks at) as of the last `update`. Read-only. */
+    readonly pivot: Vec3;
+    /** The unit view direction of the last `update`. Read-only. */
+    readonly forward: Vec3;
+    /** The orbit radius the last `update` used: `distance`, shortened by an obstacle. */
+    currentDistance: number;
+    private readonly camera;
+    private look;
+    private pivotSet;
+    private readonly wanted;
+    private readonly hit;
+    private readonly aim;
+    constructor(camera: FollowCamera, opts?: FollowOptions);
+    /** Read yaw and pitch deltas and the zoom axis from this `Look` each update (`null` stops reading). */
+    setLook(look: Look | null): void;
+    /**
+     * Step `distance` by `steps × zoomStep` (positive zooms out), clamped to min..max. A linked
+     * `Look` calls it through `update` with its `zoom` axis negated; games call it for extra keys.
+     */
+    zoom(steps: number): void;
+    /** Forget the smoothed pivot so the next `update` snaps to the target (teleports, scene changes). */
+    snap(): void;
+    /**
+     * Advance one frame: apply the look deltas, clamp the pitch, follow the target, test the line
+     * of sight and aim the camera. `dt` in seconds.
+     */
+    update(dt: number): void;
+}

package/dist/input/follow.js

@@ -0,0 +1,218 @@
+/** Longest `dt` one `update` integrates over, seconds. */
+const MAX_DT = 0.1;
+/**
+ * A third-person camera that follows a target, orbits from the same `look` deltas `Look` reports,
+ * swings in on obstacles the game reports, and becomes a first-person camera with one
+ * assignment (`mode = 'first'`). Each `update(dt)` reads the linked `Look` (or the yaw and pitch
+ * the game set), places the eye and calls `camera.lookAt`. Nothing allocates per frame.
+ *
+ * Conventions match `Look` and the look harness: yaw 0 looks down -z and positive yaw turns
+ * right; positive pitch looks up (so in third person the camera sinks below the pivot; negative
+ * pitch raises it). The pivot is `target.position + (0, eyeHeight, 0)` shifted by `shoulder`
+ * along the camera's right and up; the eye sits `distance` behind it along the view direction.
+ *
+ * ```ts
+ * const follow = new Follow(camera, { distance: 5, shoulder: [0.6, 0], obstacle: world.raycast });
+ * follow.target = player;              // { position: Float32Array(3), yaw }
+ * follow.setLook(look);
+ * // each tick, after input.update():
+ * follow.update(dt);                   // the look's zoom axis (wheel, pinch, pad) steps distance
+ * if (input.pressed('view')) follow.mode = follow.mode === 'third' ? 'first' : 'third';
+ * ```
+ */
+export class Follow {
+    /** What to follow. Until set, the pivot is at the origin. */
+    target = null;
+    /** Orbit yaw, radians (0 is -z, positive turns right). The `Look` adds to it. */
+    yaw;
+    /** View pitch, radians, clamped to `pitchMin..pitchMax` each update. */
+    pitch;
+    /** Orbit radius wanted; `currentDistance` is what an obstacle left of it. `zoom()` steps it. */
+    distance;
+    mode;
+    minDistance;
+    maxDistance;
+    pitchMin;
+    pitchMax;
+    smoothing;
+    eyeHeight;
+    zoomStep;
+    margin;
+    realign;
+    obstacle;
+    /** Shoulder offset (camera right, up). Mutate in place. */
+    shoulder;
+    /** The eye placed by the last `update`, world units. Read-only. */
+    position = [0, 0, 0];
+    /** The smoothed pivot the camera orbits (and looks at) as of the last `update`. Read-only. */
+    pivot = [0, 0, 0];
+    /** The unit view direction of the last `update`. Read-only. */
+    forward = [0, 0, -1];
+    /** The orbit radius the last `update` used: `distance`, shortened by an obstacle. */
+    currentDistance;
+    camera;
+    look = null;
+    pivotSet = false;
+    wanted = [0, 0, 0];
+    hit = [0, 0, 0];
+    aim = [0, 0, 0];
+    constructor(camera, opts = {}) {
+        this.camera = camera;
+        this.distance = opts.distance ?? 4;
+        this.minDistance = opts.minDistance ?? 1;
+        this.maxDistance = opts.maxDistance ?? 12;
+        this.shoulder = [opts.shoulder?.[0] ?? 0, opts.shoulder?.[1] ?? 0];
+        this.pitchMin = opts.pitchMin ?? -1.2;
+        this.pitchMax = opts.pitchMax ?? 1.2;
+        this.smoothing = opts.smoothing ?? 0.12;
+        this.eyeHeight = opts.eyeHeight ?? 1.6;
+        this.zoomStep = opts.zoomStep ?? 0.5;
+        this.obstacle = opts.obstacle ?? null;
+        this.margin = opts.margin ?? 0.2;
+        this.realign = opts.realign ?? 0;
+        this.yaw = opts.yaw ?? 0;
+        this.pitch = opts.pitch ?? -0.35;
+        this.mode = opts.mode ?? 'third';
+        this.currentDistance = this.distance;
+    }
+    /** Read yaw and pitch deltas and the zoom axis from this `Look` each update (`null` stops reading). */
+    setLook(look) {
+        this.look = look;
+    }
+    /**
+     * Step `distance` by `steps × zoomStep` (positive zooms out), clamped to min..max. A linked
+     * `Look` calls it through `update` with its `zoom` axis negated; games call it for extra keys.
+     */
+    zoom(steps) {
+        this.distance = clamp(this.distance + steps * this.zoomStep, this.minDistance, this.maxDistance);
+    }
+    /** Forget the smoothed pivot so the next `update` snaps to the target (teleports, scene changes). */
+    snap() {
+        this.pivotSet = false;
+        this.currentDistance = this.distance;
+    }
+    /**
+     * Advance one frame: apply the look deltas, clamp the pitch, follow the target, test the line
+     * of sight and aim the camera. `dt` in seconds.
+     */
+    update(dt) {
+        const step = Math.min(MAX_DT, Math.max(0, dt));
+        const look = this.look;
+        let turned = false;
+        if (look) {
+            const dx = look.look.dx;
+            const dy = look.look.dy;
+            this.yaw += dx;
+            this.pitch += dy;
+            turned = dx !== 0 || dy !== 0;
+            // `Look.zoom` > 0 is closer; `zoom(steps)` > 0 is farther.
+            if (look.zoom !== 0)
+                this.zoom(0 - look.zoom);
+        }
+        this.pitch = clamp(this.pitch, this.pitchMin, this.pitchMax);
+        this.distance = clamp(this.distance, this.minDistance, this.maxDistance);
+        const t = this.target;
+        const tp = t?.position;
+        const tx = tp ? tp[0] : 0;
+        const ty = (tp ? tp[1] : 0) + this.eyeHeight;
+        const tz = tp ? tp[2] : 0;
+        if (this.realign > 0 && !turned && t && t.yaw !== undefined) {
+            this.yaw += angleDelta(this.yaw, t.yaw) * ease(step, this.realign);
+        }
+        const sy = Math.sin(this.yaw);
+        const cy = Math.cos(this.yaw);
+        const sp = Math.sin(this.pitch);
+        const cp = Math.cos(this.pitch);
+        const f = this.forward;
+        f[0] = sy * cp;
+        f[1] = sp;
+        f[2] = -cy * cp;
+        const eye = this.position;
+        const pivot = this.pivot;
+        const aim = this.aim;
+        if (this.mode === 'first') {
+            // Head-mounted: no lag, no shoulder; the pivot sits on the eye.
+            eye[0] = pivot[0] = tx;
+            eye[1] = pivot[1] = ty;
+            eye[2] = pivot[2] = tz;
+            this.pivotSet = true;
+            this.currentDistance = 0;
+            aim[0] = eye[0] + f[0];
+            aim[1] = eye[1] + f[1];
+            aim[2] = eye[2] + f[2];
+            this.camera.lookAt(eye, aim);
+            return;
+        }
+        // Camera right (yaw only) and up (perpendicular to forward in the yaw plane).
+        const rx = cy;
+        const rz = sy;
+        const ux = -sy * sp;
+        const uy = cp;
+        const uz = cy * sp;
+        const sh = this.shoulder;
+        const px = tx + rx * sh[0] + ux * sh[1];
+        const py = ty + uy * sh[1];
+        const pz = tz + rz * sh[0] + uz * sh[1];
+        if (this.pivotSet && this.smoothing > 0) {
+            const k = ease(step, this.smoothing);
+            pivot[0] += (px - pivot[0]) * k;
+            pivot[1] += (py - pivot[1]) * k;
+            pivot[2] += (pz - pivot[2]) * k;
+        }
+        else {
+            pivot[0] = px;
+            pivot[1] = py;
+            pivot[2] = pz;
+            this.pivotSet = true;
+        }
+        const wanted = this.wanted;
+        const d = this.distance;
+        wanted[0] = pivot[0] - f[0] * d;
+        wanted[1] = pivot[1] - f[1] * d;
+        wanted[2] = pivot[2] - f[2] * d;
+        let allowed = d;
+        const ob = this.obstacle;
+        if (ob) {
+            const hit = this.hit;
+            if (ob(pivot, wanted, hit)) {
+                const hd = Math.hypot(hit[0] - pivot[0], hit[1] - pivot[1], hit[2] - pivot[2]);
+                allowed = Math.max(0, Math.min(d, hd - this.margin));
+            }
+        }
+        // Snap in on an obstacle; ease back out when the line clears.
+        let cur = this.currentDistance;
+        if (allowed < cur || this.smoothing <= 0)
+            cur = allowed;
+        else
+            cur += (allowed - cur) * ease(step, this.smoothing);
+        this.currentDistance = cur;
+        eye[0] = pivot[0] - f[0] * cur;
+        eye[1] = pivot[1] - f[1] * cur;
+        eye[2] = pivot[2] - f[2] * cur;
+        if (cur > 0) {
+            this.camera.lookAt(eye, pivot);
+        }
+        else {
+            aim[0] = eye[0] + f[0];
+            aim[1] = eye[1] + f[1];
+            aim[2] = eye[2] + f[2];
+            this.camera.lookAt(eye, aim);
+        }
+    }
+}
+function clamp(v, lo, hi) {
+    return Math.min(hi, Math.max(lo, v));
+}
+/** The fraction of the gap to close this step for an exponential approach with time constant `tau`. */
+function ease(dt, tau) {
+    return tau > 0 ? 1 - Math.exp(-dt / tau) : 1;
+}
+/** Shortest signed turn from `from` to `to`, radians in -π..π. */
+function angleDelta(from, to) {
+    let d = (to - from) % (2 * Math.PI);
+    if (d > Math.PI)
+        d -= 2 * Math.PI;
+    else if (d < -Math.PI)
+        d += 2 * Math.PI;
+    return d;
+}

package/dist/input/gestures.d.ts

@@ -0,0 +1,281 @@
+import { type InputClock } from './clock.js';
+import { type Aim, type MagnifyOptions } from './magnify.js';
+import { type PointerDispatcher } from './pointer-dispatch.js';
+import type { GestureKind, PointerTransform } from './types.js';
+/** Device of the pointer that made a gesture. */
+export type GestureDevice = 'mouse' | 'touch' | 'pen';
+/** Phases of a continuous gesture (pan, drag, pinch). */
+export type GesturePhase = 'start' | 'move' | 'end' | 'cancel';
+/** A point in game space (through the `PointerTransform`). */
+export interface GesturePoint {
+    /** Game space. When the transform returns `null` (letterbox bars) this holds the last inside position. */
+    x: number;
+    y: number;
+    /** False when the transform returned `null` for this point. */
+    inside: boolean;
+}
+/** `tap`, `doubleTap` and `longPress`: one point, reported on one tick. */
+export interface TapGesture extends GesturePoint {
+    device: GestureDevice;
+}
+/** `pan`: one pointer moved past the threshold. Two or more pointers pinch and never pan. */
+export interface PanGesture extends GesturePoint {
+    phase: GesturePhase;
+    /** Movement since the previous report, game space. Every `dx` of one pan sums to its total travel from the down point. */
+    dx: number;
+    dy: number;
+    /** Pointers in the pan: always 1 (a second pointer cancels the pan and starts a pinch). */
+    pointers: 1;
+    device: GestureDevice;
+}
+/** `drag`: one pointer moved past the threshold. Like a one-pointer pan, with the origin. */
+export interface DragGesture extends GesturePoint {
+    phase: GesturePhase;
+    /** Where the pointer went down, game space. */
+    origin: GesturePoint;
+    dx: number;
+    dy: number;
+    device: GestureDevice;
+}
+/** `pinch`: two pointers. `x`/`y` is their centre. */
+export interface PinchGesture extends GesturePoint {
+    phase: GesturePhase;
+    /** Distance between the pointers now / at the start (1 = unchanged). */
+    scale: number;
+    /** Change since the previous report (multiply a zoom by it). */
+    delta: number;
+}
+/**
+ * An `onGesture` listener: called once, synchronously, each time the recogniser decides something,
+ * before any tick reports it. `g` is the report that the tick fields will carry (a `TapGesture`,
+ * `PanGesture`, `DragGesture` or `PinchGesture`, narrowed by `kind`). Discrete kinds (`tap`,
+ * `doubleTap`, `longPress`) come with phase `'end'`.
+ */
+export type GestureListener = (kind: GestureKind, phase: GesturePhase, g: GesturePoint) => void;
+export interface GestureOptions {
+    /**
+     * CSS px a pointer may move and still be a tap or long-press. Past it the press is a pan and a
+     * drag. Default 10.
+     */
+    panThreshold?: number;
+    /** Ms a pointer must stay down (and within `panThreshold`) for a long-press. Default 450. */
+    longPressMs?: number;
+    /** Most ms from the end of one tap to the start of the next for a double tap. Default 300. */
+    doubleTapMs?: number;
+    /** Most CSS px between the two taps of a double tap. Default 24. */
+    doubleTapDistance?: number;
+    /** While true no gesture is reported (see `Gestures`). An `Input` that links this replaces it with its own. */
+    blocked?: () => boolean;
+    /**
+     * Clock in ms. Default `performance.now()`. Tests pass a fake one. Attached DOM events are
+     * timed by their `timeStamp`, moved onto this clock by their age (`eventTime`); the long-press
+     * timer in `update()` reads this clock. The older spelling of `clock`; `clock` wins.
+     */
+    now?: () => number;
+    /**
+     * The clock gestures are timed on (ws/input-8), e.g. a `createTickClock()` the game advances
+     * from its fixed step and shares with `Look`. Default `performance.now()`.
+     */
+    clock?: InputClock;
+    /**
+     * Loupe and snap for small touch targets (see `magnify.ts`): while one touch pointer is down
+     * each tick reports `aim`, and below `below` CSS px of pitch a loupe shows the aim point.
+     */
+    magnify?: MagnifyOptions;
+    /**
+     * `'prefer'` (ws/input-3): a pointer whose cumulative travel passes a quarter of `panThreshold`
+     * is a pan candidate and can no longer long-press, however long the next frame takes; if it
+     * lifts before crossing the threshold it is a tap (within `longPressMs`) or nothing. Default:
+     * a still-enough pointer long-presses when its time is up, even after a little travel.
+     */
+    pan?: 'prefer';
+    /**
+     * Called once per press, synchronously, when its pointer's travel passes a quarter of
+     * `panThreshold` (in either `pan` mode), with the pointer id and the travel so far. An
+     * observer for games that want to cancel their own long-press affordance early.
+     */
+    onPanCandidate?: (pointer: number, travel: number) => void;
+}
+export interface GestureAttachOptions {
+    /** Element that receives pointer events (the canvas, or the element wrapping it). */
+    pointerTarget: HTMLElement;
+    /** Set `touch-action: none` on the target so touch drags don't scroll or zoom. Default true. */
+    disableTouchScroll?: boolean;
+    /**
+     * The pointer dispatcher to consume from (ws/input-4) instead of listening on the target
+     * directly. `Input.attach` passes its own; without one the gestures build a private dispatcher.
+     */
+    dispatcher?: PointerDispatcher;
+}
+/**
+ * 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 declare class Gestures {
+    /** This tick's gestures, or `null`. */
+    tap: TapGesture | null;
+    doubleTap: TapGesture | null;
+    longPress: TapGesture | null;
+    pan: PanGesture | null;
+    drag: DragGesture | null;
+    pinch: PinchGesture | null;
+    /** This tick's aim while one touch pointer is down (with the `magnify` option), or `null`. */
+    aim: Aim | null;
+    blocked: () => boolean;
+    readonly panThreshold: number;
+    readonly longPressMs: number;
+    readonly doubleTapMs: number;
+    readonly doubleTapDistance: number;
+    /** `GestureOptions.pan`: `'prefer'` keeps a pan candidate from long-pressing. */
+    readonly panMode: 'prefer' | null;
+    /**
+     * 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: ((id: number, device: GestureDevice) => boolean) | 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.
+     */
+    readonly now: () => number;
+    /** The clock (`GestureOptions.clock`, or one wrapping `now`, or the wall clock). */
+    readonly clock: InputClock;
+    private readonly onPanCandidate;
+    private transform;
+    private session;
+    /** Last tap, for double taps: client position and end time. */
+    private lastTap;
+    private lastInside;
+    /** Taps; `double` marks the second tap of a double tap (reported on the same tick). */
+    private readonly taps;
+    private readonly longPresses;
+    private readonly pans;
+    private readonly drags;
+    private readonly pinches;
+    /** Continuous gestures reported as started and not yet ended, with their last report. */
+    private readonly running;
+    /** The session whose long-press has been reported, while its pointer stays down. */
+    private longPressSession;
+    private detachFn;
+    private magnify;
+    private loupe;
+    /** The aim at the moment the finger lifted, reported (with `ended`) on the next tick. */
+    private endedAim;
+    /** `onGesture` listeners, called at recognition time. */
+    private readonly listeners;
+    constructor(opts?: GestureOptions);
+    /** Turn magnify on (or off with `null`) after construction. */
+    setMagnify(opts: MagnifyOptions | null): void;
+    /** The loupe element, once one has been shown (for styling and tests). */
+    get loupeElement(): HTMLElement | null;
+    /** Install the client → game-space mapping. `null` = identity (relative to the target when attached). */
+    setPointerTransform(fn: PointerTransform | null): void;
+    /**
+     * 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: GestureListener): () => void;
+    private emit;
+    /**
+     * 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: GestureKind): boolean;
+    /** True when `kind` was reported fresh this tick: a new tap, double tap, long-press or `start`. */
+    fired(kind: GestureKind): boolean;
+    /** Advance one tick: fire due long-presses and publish one report per kind. */
+    update(): void;
+    /**
+     * 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.
+     */
+    private updateAim;
+    /** The aim of touch contact `c` (`null` for mouse and pen, or while `when()` is false). */
+    private aimOf;
+    /** The `cancel` report for a running `kind` (blocked), or `null`. */
+    private cancelled;
+    /**
+     * 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.
+     */
+    private publish;
+    private clearQueues;
+    pointerDown(id: number, clientX: number, clientY: number, device?: GestureDevice, time?: number): void;
+    pointerMove(id: number, clientX: number, clientY: number, time?: number): void;
+    pointerUp(id: number, clientX?: number, clientY?: number, time?: number): void;
+    /** The browser took the pointer (system gesture, palm rejection): drop the press. */
+    pointerCancel(id: number): void;
+    /** Drop every pointer (focus loss, tab hidden). A started pan, drag or pinch is cancelled. */
+    cancelAll(): void;
+    private cancelSession;
+    private checkLongPress;
+    /** True when `c` may no longer long-press: a pan candidate under `pan: 'prefer'`. */
+    private preferPan;
+    private longPressOf;
+    private emitTap;
+    private pushMove;
+    /** Queues one pan and one drag report and tells the listeners. */
+    private pushPan;
+    private pushPinch;
+    /** Ends (or cancels) a one-pointer pan and drag, if one is running in `s`. */
+    private endOnePointer;
+    /** Two pointers: only the pinch moves. Their centre moving is not a pan (pinch wins). */
+    private moveTwo;
+    private endTwo;
+    private map;
+    /**
+     * 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: GestureAttachOptions): void;
+    /** The private dispatcher a standalone `attach` built, or `null` (shared or detached). */
+    private ownDispatcher;
+    /**
+     * 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.
+     */
+    private readonly consumer;
+    detach(): void;
+    /** Detach and remove the loupe element. */
+    destroy(): void;
+}
+/** `new Gestures(opts)`: gestures, on `opts.clock` when given (ws/input-8). */
+export declare function createGestures(opts?: GestureOptions): Gestures;