@expofp/renderer 3.2.4 → 3.27.0

package/dist/controls/camera-api.d.ts

@@ -0,0 +1,206 @@
+import { type Box } from '@expofp/geometry';
+import { type CameraHandle } from '../space/camera-handle';
+import { type PlanPointLike, type Space } from '../space/Space';
+import { type CameraControlsImpl } from './CameraControls';
+import { type ViewOffset } from './zoom-to';
+/** How a camera move should be made. */
+export interface TransitionOptions {
+    /** Jump rather than ease; defaults to easing. How long an eased move takes is `smoothTime`. */
+    immediate?: boolean;
+}
+/** How {@link CameraAPI.zoomTo} should frame its target. */
+export interface ZoomToOptions extends TransitionOptions {
+    /**
+     * Fraction of the region left as margin on each side; defaults to none. `0.25` spends half the
+     * region on margin, which is what the imperative renderer asked for around a single booth.
+     */
+    padding?: number;
+    /** The closest the fit may bring the plan, as a zoom factor. The camera's `maxZoom` still caps it. */
+    maxZoom?: number;
+    /**
+     * The part of the canvas to frame the target inside, in css pixels from its top-left corner;
+     * defaults to the whole canvas.
+     *
+     * **Framing only.** Nothing is rendered differently for it and the plan does not move when one
+     * appears — which is what makes it the right place for a panel that covers part of the canvas,
+     * as opposed to `visibleRect`, which is where the plan is *drawn*.
+     */
+    within?: Box;
+}
+/** Which axes {@link CameraAPI.reset} returns to their starting values. */
+export interface CameraAxes {
+    /** Look at the middle of the plan again. */
+    pan?: boolean;
+    /** Frame the whole viewbox again — zoom factor `1`. */
+    zoom?: boolean;
+    /** Face north again. */
+    roll?: boolean;
+    /** Look straight down again, as far as `minPitch` allows. */
+    pitch?: boolean;
+}
+/**
+ * Moving the camera: what a host asks the plan to do, as opposed to what a *user* may do with it,
+ * which is `ControlsConfig`.
+ *
+ * Every move is held to the camera's own limits — `minZoom`, `maxZoom`, `minPitch`, `maxPitch`,
+ * `bounds` — and to nothing else. In particular it does **not** matter which gestures are mounted:
+ * a plan with roll switched off still rolls when its host asks it to, because a limit on where the
+ * camera may go and a decision about what a finger may do are different questions. That is the one
+ * place this departs from the imperative renderer, whose `resetCamera` skipped any axis whose
+ * handler happened to be disabled.
+ *
+ * Every method resolves when the move has settled, so a caller can sequence them; an `immediate`
+ * move resolves at once.
+ */
+export interface CameraAPI {
+    /**
+     * Frames a box of the plan.
+     * @param target - The box, in plan units.
+     * @param options - How to frame it.
+     * @returns When the move has settled.
+     */
+    zoomTo(target: Box, options?: ZoomToOptions): Promise<void>;
+    /**
+     * Zooms by a factor of where it already is — `1.5` closer, `0.66` further out.
+     * @param factor - What to multiply the zoom factor by.
+     * @param options - How to make the move.
+     * @returns When the move has settled.
+     */
+    zoomBy(factor: number, options?: TransitionOptions): Promise<void>;
+    /**
+     * Looks at a point on the plan.
+     * @param point - Where to look, in plan units. A `z` is ignored: the camera looks at the floor
+     *   beneath an elevated point, not at the point itself.
+     * @param options - How to make the move.
+     * @returns When the move has settled.
+     */
+    panTo(point: PlanPointLike, options?: TransitionOptions): Promise<void>;
+    /**
+     * Slides the view across the plan.
+     * @param offset - How far to slide, in plan units.
+     * @param options - How to make the move.
+     * @returns When the move has settled.
+     */
+    panBy(offset: PlanPointLike, options?: TransitionOptions): Promise<void>;
+    /**
+     * Turns the plan to face a heading, by whichever way round is shorter.
+     * @param degrees - The heading, clockwise from north.
+     * @param options - How to make the move.
+     * @returns When the move has settled.
+     */
+    rollTo(degrees: number, options?: TransitionOptions): Promise<void>;
+    /**
+     * Turns the plan further.
+     * @param degrees - How far to turn it, clockwise.
+     * @param options - How to make the move.
+     * @returns When the move has settled.
+     */
+    rollBy(degrees: number, options?: TransitionOptions): Promise<void>;
+    /**
+     * Tilts the plan to an angle away from face-on, held inside the pitch limits.
+     * @param degrees - The angle; `0` looks straight down.
+     * @param options - How to make the move.
+     * @returns When the move has settled.
+     */
+    pitchTo(degrees: number, options?: TransitionOptions): Promise<void>;
+    /**
+     * Tilts the plan further, held inside the pitch limits.
+     * @param degrees - How much further to tilt it.
+     * @param options - How to make the move.
+     * @returns When the move has settled.
+     */
+    pitchBy(degrees: number, options?: TransitionOptions): Promise<void>;
+    /**
+     * Returns the named axes to where they started; all four when none are named.
+     * @param axes - Which axes to reset.
+     * @param options - How to make the move.
+     * @returns When every reset has settled.
+     */
+    reset(axes?: CameraAxes, options?: TransitionOptions): Promise<void>;
+}
+/**
+ * What {@link CameraCommands} needs from the scene it drives.
+ *
+ * Handed over whole rather than reached for, so the class stays free of React and can be exercised
+ * against a bare camera. Nothing here is the camera three draws through: the one thing ever wanted
+ * from it is its view offset, which arrives as {@link CameraContext.view} — naming both a `camera`
+ * and a way to reach three's camera would be two different objects under one word.
+ */
+interface CameraContext {
+    /** The controls every command drives, once they have mounted. */
+    controls: CameraControlsImpl | undefined;
+    /** The camera's zoom handle, once it is published. */
+    camera: CameraHandle | undefined;
+    /**
+     * What a visible rect put on the projection, read at the moment of asking.
+     *
+     * A function and not a value, because it is written by an effect after this context was built —
+     * a scene with a visible rect spends its first render without one — and three mutates the object
+     * in place rather than replacing it, so nothing short of a fresh read is reliably current.
+     */
+    view: () => ViewOffset;
+    /** The scene's space, which takes plan coordinates into world ones. */
+    space: Space;
+    /** The canvas width in css pixels. */
+    width: number;
+    /** Its height. */
+    height: number;
+    /** Device pixels per css pixel. */
+    dpr: number;
+}
+/**
+ * The scene's camera commands.
+ *
+ * A hook rather than a ref handed out from above, and that is the point: it only resolves inside a
+ * component mounted under `<Renderer>`, and R3F mounts those only once the canvas and its context
+ * exist — so "the camera cannot be driven before the scene is ready" is enforced by where the code
+ * can live rather than by a null check every caller has to remember. A host that needs to drive the
+ * camera from outside React publishes this object from an effect, which is exactly when it is safe.
+ *
+ * Before the controls mount every command is a no-op that resolves at once, which is the same frame
+ * or two the hook's own consumers spend waiting for their effects.
+ *
+ * **The returned object is new on every render, deliberately.** This module is not memoized by hand
+ * — the React Compiler is scoped to `.tsx` under `src/` (see `vitest.config.mts`), and reaching for
+ * `useMemo` here would put a cache in the library that every consumer then has to trust. A consumer
+ * that cannot re-subscribe cheaply should hold this in a ref rather than in a dependency list; that
+ * way the decision, and its cost, sit with the code that knows how often it renders.
+ * @returns The commands.
+ */
+export declare function useCameraAPI(): CameraAPI;
+/**
+ * The camera commands, over whatever the scene currently holds.
+ *
+ * A class rather than an object literal because it is the renderer's published surface: the methods
+ * document themselves in one place, and a caller reading `CameraAPI` in an editor lands here. It is
+ * built fresh whenever its context moves rather than mutated in place, so nothing here is state and
+ * every method reads the scene as it stood when the component last rendered — bar the camera's own
+ * position and heading, which are read from the controls at the moment of asking.
+ */
+export declare class CameraCommands implements CameraAPI {
+    private readonly context;
+    /**
+     * @param context - What the scene holds; the instance is rebuilt whenever it moves.
+     */
+    constructor(context: CameraContext);
+    /** @inheritdoc */
+    zoomTo(target: Box, options?: ZoomToOptions): Promise<void>;
+    /** @inheritdoc */
+    zoomBy(factor: number, options?: TransitionOptions): Promise<void>;
+    /** @inheritdoc */
+    panTo(point: PlanPointLike, options?: TransitionOptions): Promise<void>;
+    /** @inheritdoc */
+    panBy(offset: PlanPointLike, options?: TransitionOptions): Promise<void>;
+    /** @inheritdoc */
+    rollTo(degrees: number, options?: TransitionOptions): Promise<void>;
+    /** @inheritdoc */
+    rollBy(degrees: number, options?: TransitionOptions): Promise<void>;
+    /** @inheritdoc */
+    pitchTo(degrees: number, options?: TransitionOptions): Promise<void>;
+    /** @inheritdoc */
+    pitchBy(degrees: number, options?: TransitionOptions): Promise<void>;
+    /** @inheritdoc */
+    reset(axes?: CameraAxes, options?: TransitionOptions): Promise<void>;
+}
+export {};
+//# sourceMappingURL=camera-api.d.ts.map

package/dist/controls/camera-api.js

@@ -0,0 +1,181 @@
+import { angleDiff, degToRad } from '@expofp/geometry';
+import { useThree } from '@react-three/fiber';
+import { Vector3 } from 'three';
+import { useCamera } from '../space/camera-handle';
+import { useCanvasSize } from '../space/canvas-size';
+import { useSpace } from '../space/Space';
+import { bearing, useCameraControls } from './CameraControls';
+import { fitBox, framingRegion } from './zoom-to';
+/**
+ * The scene's camera commands.
+ *
+ * A hook rather than a ref handed out from above, and that is the point: it only resolves inside a
+ * component mounted under `<Renderer>`, and R3F mounts those only once the canvas and its context
+ * exist — so "the camera cannot be driven before the scene is ready" is enforced by where the code
+ * can live rather than by a null check every caller has to remember. A host that needs to drive the
+ * camera from outside React publishes this object from an effect, which is exactly when it is safe.
+ *
+ * Before the controls mount every command is a no-op that resolves at once, which is the same frame
+ * or two the hook's own consumers spend waiting for their effects.
+ *
+ * **The returned object is new on every render, deliberately.** This module is not memoized by hand
+ * — the React Compiler is scoped to `.tsx` under `src/` (see `vitest.config.mts`), and reaching for
+ * `useMemo` here would put a cache in the library that every consumer then has to trust. A consumer
+ * that cannot re-subscribe cheaply should hold this in a ref rather than in a dependency list; that
+ * way the decision, and its cost, sit with the code that knows how often it renders.
+ * @returns The commands.
+ */
+export function useCameraAPI() {
+    const get = useThree((state) => state.get);
+    const controls = useCameraControls();
+    const camera = useCamera();
+    const space = useSpace();
+    const { width, height, dpr } = useCanvasSize();
+    return new CameraCommands({
+        controls,
+        camera,
+        space,
+        view: () => get().camera.view,
+        width,
+        height,
+        dpr,
+    });
+}
+/**
+ * The camera commands, over whatever the scene currently holds.
+ *
+ * A class rather than an object literal because it is the renderer's published surface: the methods
+ * document themselves in one place, and a caller reading `CameraAPI` in an editor lands here. It is
+ * built fresh whenever its context moves rather than mutated in place, so nothing here is state and
+ * every method reads the scene as it stood when the component last rendered — bar the camera's own
+ * position and heading, which are read from the controls at the moment of asking.
+ */
+export class CameraCommands {
+    context;
+    /**
+     * @param context - What the scene holds; the instance is rebuilt whenever it moves.
+     */
+    constructor(context) {
+        this.context = context;
+    }
+    /** @inheritdoc */
+    async zoomTo(target, options) {
+        const { controls, camera, space, view, width, height, dpr } = this.context;
+        if (!controls || !camera)
+            return;
+        const fit = fitBox({
+            target,
+            space,
+            bearing: bearing(controls),
+            region: framingRegion(options?.within, width, height, dpr, view()),
+            padding: options?.padding,
+            maxZoom: options?.maxZoom,
+        });
+        if (!fit)
+            return;
+        const transition = !options?.immediate;
+        await Promise.all([
+            controls.moveTo(fit.center.x, fit.center.y, 0, transition),
+            controls.dollyTo(camera.zoomFactorToDistance(fit.zoom), transition),
+        ]);
+    }
+    /** @inheritdoc */
+    zoomBy(factor, options) {
+        const { controls, camera } = this.context;
+        if (!controls || !camera)
+            return RESOLVED;
+        return controls.dollyTo(camera.zoomFactorToDistance(camera.zoomFactor * factor), !options?.immediate);
+    }
+    /** @inheritdoc */
+    panTo(point, options) {
+        const { controls, space } = this.context;
+        if (!controls)
+            return RESOLVED;
+        const world = toWorld(space, point);
+        return controls.moveTo(world.x, world.y, world.z, !options?.immediate);
+    }
+    /** @inheritdoc */
+    panBy(offset, options) {
+        const { controls, space } = this.context;
+        if (!controls)
+            return RESOLVED;
+        // Two conversions rather than one, because a plan offset is a direction and the fit carries a
+        // translation: only the difference between two converted points is free of it.
+        const origin = toWorld(space, ORIGIN, _origin);
+        const shifted = toWorld(space, offset);
+        const current = controls.getTarget(_current);
+        return controls.moveTo(current.x + shifted.x - origin.x, current.y + shifted.y - origin.y, current.z + shifted.z - origin.z, !options?.immediate);
+    }
+    /** @inheritdoc */
+    rollTo(degrees, options) {
+        const { controls } = this.context;
+        if (!controls)
+            return RESOLVED;
+        // Whichever way round is shorter, which is what keeps a turn from 350° to 10° going the long
+        // way about.
+        const delta = angleDiff(-degToRad(degrees), controls.azimuthAngle);
+        return controls.rotateAzimuthTo(controls.azimuthAngle + delta, !options?.immediate);
+    }
+    /** @inheritdoc */
+    rollBy(degrees, options) {
+        const { controls } = this.context;
+        if (!controls)
+            return RESOLVED;
+        return controls.rotateAzimuthTo(controls.azimuthAngle - degToRad(degrees), !options?.immediate);
+    }
+    /** @inheritdoc */
+    pitchTo(degrees, options) {
+        const { controls } = this.context;
+        if (!controls)
+            return RESOLVED;
+        // Held inside the pitch limits by the controls themselves, which is where those limits live.
+        return controls.rotatePolarTo(degToRad(degrees), !options?.immediate);
+    }
+    /** @inheritdoc */
+    pitchBy(degrees, options) {
+        const { controls } = this.context;
+        if (!controls)
+            return RESOLVED;
+        return controls.rotatePolarTo(controls.polarAngle + degToRad(degrees), !options?.immediate);
+    }
+    /** @inheritdoc */
+    async reset(axes = ALL_AXES, options) {
+        const { controls, camera } = this.context;
+        if (!controls || !camera)
+            return;
+        const transition = !options?.immediate;
+        const moves = [];
+        // Every target is the camera's own, which is why there is no registry of what to ask: the
+        // viewbox fit puts the plan's middle on the world origin, zoom factor 1 frames it, north is
+        // azimuth zero, and how flat the plan may lie is `minPitch`.
+        if (axes.pan)
+            moves.push(controls.moveTo(0, 0, 0, transition));
+        if (axes.zoom)
+            moves.push(controls.dollyTo(camera.zoomFactorToDistance(1), transition));
+        // Normalized first, so a plan turned several times over unwinds to the nearest north rather
+        // than spinning back through every turn it was given.
+        if (axes.roll)
+            moves.push(controls.normalizeRotations().rotateAzimuthTo(0, transition));
+        if (axes.pitch)
+            moves.push(controls.rotatePolarTo(controls.minPolarAngle, transition));
+        await Promise.all(moves);
+    }
+}
+/**
+ * Takes a point on the plan into world coordinates.
+ * @param space - The scene's space.
+ * @param point - The point, in plan units.
+ * @param out - Where to write the result.
+ * @returns The world point.
+ */
+function toWorld(space, point, out = _target) {
+    return space.planToWorld({ x: point.x, y: point.y, z: 0 }, out);
+}
+/** Every axis, which is what {@link CameraAPI.reset} resets when a caller names none. */
+const ALL_AXES = { pan: true, zoom: true, roll: true, pitch: true };
+/** What a command hands back before the controls have mounted and there is nothing to move. */
+const RESOLVED = Promise.resolve();
+const ORIGIN = { x: 0, y: 0 };
+const _target = new Vector3();
+const _origin = new Vector3();
+const _current = new Vector3();

package/dist/controls/camera-move.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Runs a handler when a camera movement begins — a gesture and a command alike, one call per
+ * movement rather than one per frame. The event the imperative renderer published as
+ * `navigation:change`, under a name that says what happened.
+ *
+ * A camera-level event rather than the controls themselves, so a caller resetting an idle timer or
+ * dismissing an overlay never learns which library drives the camera. For as long as the component
+ * is mounted; where the camera *is* once it settles is `useCameraState`'s business.
+ * @param handler - Called as each movement starts. Re-subscribed when its identity changes, so pass
+ *   a stable function — under the React Compiler an inline closure over stable values is one.
+ */
+export declare function useCameraMoveStart(handler: () => void): void;
+//# sourceMappingURL=camera-move.d.ts.map

package/dist/controls/camera-move.js

@@ -0,0 +1,18 @@
+import { useControlsEffect } from './CameraControls';
+/**
+ * Runs a handler when a camera movement begins — a gesture and a command alike, one call per
+ * movement rather than one per frame. The event the imperative renderer published as
+ * `navigation:change`, under a name that says what happened.
+ *
+ * A camera-level event rather than the controls themselves, so a caller resetting an idle timer or
+ * dismissing an overlay never learns which library drives the camera. For as long as the component
+ * is mounted; where the camera *is* once it settles is `useCameraState`'s business.
+ * @param handler - Called as each movement starts. Re-subscribed when its identity changes, so pass
+ *   a stable function — under the React Compiler an inline closure over stable values is one.
+ */
+export function useCameraMoveStart(handler) {
+    useControlsEffect((controls) => {
+        controls.addEventListener('transitionstart', handler);
+        return () => controls.removeEventListener('transitionstart', handler);
+    });
+}

package/dist/controls/camera-state.d.ts

@@ -0,0 +1,40 @@
+import { Point } from '@expofp/geometry';
+/** Where the camera is, at the moment it was asked. */
+export interface CameraState {
+    /** The point on the plan it is looking at, in plan units. */
+    center: Point;
+    /** How far in it is zoomed, as a factor: `1` frames the whole viewbox. */
+    zoom: number;
+    /** Which way the plan is turned, in degrees clockwise from north, in `[0, 360)`. */
+    roll: number;
+    /** How far the plan is tilted away from face-on, in degrees. */
+    pitch: number;
+    /**
+     * How much of the plan one device pixel spans, in plan units — the factor anything sized in
+     * pixels is laid out against, and the quantity the imperative renderer published as `ptScale`.
+     */
+    pixelSize: number;
+}
+/**
+ * Reads where the camera is.
+ *
+ * A **getter**, not a value: nothing here belongs in render output — a component that re-rendered
+ * whenever the camera moved would re-render on every frame of every pan — and every caller wants it
+ * at a moment of its own choosing, in an event handler, an effect, or a snapshot a host asked for.
+ * That is the same reading discipline `Space` documents, for the same reason.
+ *
+ * The five numbers come from four different places, which is why this exists at all rather than
+ * being arithmetic a caller could do: the target from the controls and the plan it lands on from the
+ * space, the zoom factor from the camera's handle, and the pixel size from the re-layout registry —
+ * which is what the plan's own labels are sized against, so a caller measuring against anything else
+ * would disagree with what is drawn.
+ *
+ * Outside a mounted scene, or in the frames before the controls publish themselves, it reports the
+ * camera at rest: the middle of the plan, framed whole, facing north.
+ *
+ * As with {@link useCameraAPI}, the reader is **new on every render** and this module memoizes
+ * nothing; a consumer that needs a settled identity holds it in a ref.
+ * @returns A function that reads the current state.
+ */
+export declare function useCameraState(): () => CameraState;
+//# sourceMappingURL=camera-state.d.ts.map

package/dist/controls/camera-state.js

@@ -0,0 +1,65 @@
+import { Point, radToDeg } from '@expofp/geometry';
+import { use } from 'react';
+import { Vector3 } from 'three';
+import { LayoutTargetsContext } from '../events/layout-targets';
+import { useCamera } from '../space/camera-handle';
+import { useSpace } from '../space/Space';
+import { bearing, useCameraControls } from './CameraControls';
+/**
+ * Reads where the camera is.
+ *
+ * A **getter**, not a value: nothing here belongs in render output — a component that re-rendered
+ * whenever the camera moved would re-render on every frame of every pan — and every caller wants it
+ * at a moment of its own choosing, in an event handler, an effect, or a snapshot a host asked for.
+ * That is the same reading discipline `Space` documents, for the same reason.
+ *
+ * The five numbers come from four different places, which is why this exists at all rather than
+ * being arithmetic a caller could do: the target from the controls and the plan it lands on from the
+ * space, the zoom factor from the camera's handle, and the pixel size from the re-layout registry —
+ * which is what the plan's own labels are sized against, so a caller measuring against anything else
+ * would disagree with what is drawn.
+ *
+ * Outside a mounted scene, or in the frames before the controls publish themselves, it reports the
+ * camera at rest: the middle of the plan, framed whole, facing north.
+ *
+ * As with {@link useCameraAPI}, the reader is **new on every render** and this module memoizes
+ * nothing; a consumer that needs a settled identity holds it in a ref.
+ * @returns A function that reads the current state.
+ */
+export function useCameraState() {
+    const controls = useCameraControls();
+    const camera = useCamera();
+    const space = useSpace();
+    const targets = use(LayoutTargetsContext);
+    return () => readCameraState({ controls, camera, space, targets });
+}
+/**
+ * Reads the camera, from whatever the scene holds at the moment of asking.
+ * @param context - What the scene holds.
+ * @returns Where the camera is.
+ */
+function readCameraState(context) {
+    const { controls, camera, space, targets } = context;
+    const pixelSize = targets?.pixelSize ?? 1;
+    // A fresh centre every time: a caller that keeps the point it was handed must never find it
+    // moved under them.
+    if (!controls)
+        return { ...atRest(), pixelSize };
+    controls.getTarget(_target);
+    return {
+        center: space.worldToPlan(_target, new Point()),
+        zoom: camera?.zoomFactor ?? 1,
+        roll: radToDeg(bearing(controls)),
+        pitch: radToDeg(controls.polarAngle),
+        pixelSize,
+    };
+}
+/**
+ * The camera as it stands before anything has moved it, which is what a read outside a mounted
+ * scene reports: the middle of the plan, framed whole, facing north.
+ * @returns The state.
+ */
+function atRest() {
+    return { center: new Point(), zoom: 1, roll: 0, pitch: 0, pixelSize: 1 };
+}
+const _target = new Vector3();

package/dist/controls/gestures.d.ts

@@ -0,0 +1,70 @@
+import { EventManager, type MjolnirGestureEvent } from 'mjolnir.js';
+import { type Camera } from 'three';
+import { type CanvasPointLike, type Space } from '../space/Space';
+import { type CameraControlsImpl } from './CameraControls';
+/**
+ * The canvas's multi-pointer gesture recognizer.
+ *
+ * Aliased so a reader is never left wondering which `EventManager` is meant: R3F has one of its own
+ * — the pointer-event dispatcher behind `state.events` — and the two meet in this file.
+ */
+export type GestureManager = EventManager;
+/**
+ * What a gesture needs from the scene at the moment it fires.
+ *
+ * Handed in on every event rather than held by the gesture, because all three may be swapped out
+ * under a mounted handler — R3F replaces the camera, the controls publish themselves a commit
+ * later — and a gesture that captured them once would go on driving the old ones.
+ */
+export interface GestureContext {
+    /** The controls the gesture moves. */
+    controls: CameraControlsImpl;
+    /** The camera the canvas is drawn through, which canvas positions are cast from. */
+    camera: Camera;
+    /** The scene's space, which canvas positions are resolved on the plan through. */
+    space: Space;
+}
+/**
+ * Subscribes to one of the canvas's gestures for as long as the component is mounted.
+ *
+ * **Two fingers are why any of this exists.** camera-controls recognizes a pinch and an orbit, but
+ * neither of the two-finger gestures the plan needs: a twist that turns the plan about the point
+ * between the fingers, and a vertical drag that tilts it. Both come off `mjolnir.js`, whose
+ * recognizer configuration is the imperative renderer's verbatim.
+ *
+ * The recognizer itself is shared: `Roll` and `Pitch` want one on the same canvas, and two would
+ * mean two sets of pointer listeners racing over the same fingers. It is built on the first
+ * subscription and torn down with the last, since it attaches its listeners in its constructor and
+ * offers no disconnect. Every recognizer stays dormant until something subscribes to its event, so
+ * mounting `Roll` is literally what turns `rotate` on.
+ * @param type - The gesture event to listen for, e.g. `rotatestart`.
+ * @param handler - What to run when it fires. Re-subscribes whenever its identity changes, so build
+ *   it where the React Compiler can cache it against what it captures.
+ */
+export declare function useGesture(type: string, handler: (event: MjolnirGestureEvent) => void): void;
+/**
+ * Takes out a share in the canvas's recognizer, building it if this is the first.
+ *
+ * The plumbing behind {@link useGesture}, which is what a component uses; exported so the sharing
+ * and the teardown can be pinned by a spec. Every call must be paired with a release.
+ * @param element - The element to recognize on.
+ * @returns The manager.
+ */
+export declare function acquireGestureManager(element: HTMLElement): GestureManager;
+/**
+ * Gives back a share taken out by {@link acquireGestureManager}, tearing the recognizer down once
+ * the last one is returned.
+ * @param element - The element it was acquired for.
+ */
+export declare function releaseGestureManager(element: HTMLElement): void;
+/**
+ * Where one of a gesture's pointers sits on the canvas, in css pixels from its top-left corner.
+ *
+ * The one place a DOM event crosses into {@link CanvasPointLike}, which is why the assertion is
+ * written here rather than at each handler: `offsetX`/`offsetY` are canvas coordinates by
+ * definition, being measured from the target's own padding edge.
+ * @param event - One of the pointer events a gesture carries.
+ * @returns The point on the canvas.
+ */
+export declare function canvasPoint(event: MouseEvent): CanvasPointLike;
+//# sourceMappingURL=gestures.d.ts.map