@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/controls/Controls.d.ts

@@ -0,0 +1,53 @@
+import { type ReactNode } from 'react';
+import { type PanConfig } from './handlers/Pan';
+import { type RollConfig } from './handlers/Roll';
+import { type ZoomConfig } from './handlers/Zoom';
+/**
+ * What the user may do with the plan.
+ *
+ * Each handler takes `false` to switch it off, `true` or nothing for its defaults, and — where it
+ * has any — an options object, whose own defaults the handler applies.
+ *
+ * **Pan and zoom default on; roll and pitch default to whether this is a development build**, so
+ * the renderer's own Storybook and dev server carry them and a production plan does not until a
+ * caller asks. An explicit value always wins, so a host driving roll from a user-facing setting
+ * never has to think about the dev default.
+ *
+ * The pitch and zoom **limits** are not here: they hold whether or not the matching gesture does,
+ * which makes them the camera's — see `CameraProps`.
+ */
+export interface ControlsConfig {
+    /** Left-drag and one-finger drag to pan the plan. Defaults on. */
+    pan?: boolean | PanConfig;
+    /**
+     * Wheel and two-finger pinch to zoom, toward the cursor. Defaults on; a double-click or
+     * double-tap zooms too only when its options ask for it.
+     */
+    zoom?: boolean | ZoomConfig;
+    /** Right-drag and two-finger twist to turn the plan. Defaults to a development build. */
+    roll?: boolean | RollConfig;
+    /** Right-drag and two-finger vertical drag to tilt the plan. Defaults to a development build. */
+    pitch?: boolean;
+}
+/** Props for {@link Controls}. */
+export interface ControlsProps {
+    /** What the user may do with the plan; see {@link ControlsConfig}. */
+    config?: ControlsConfig;
+}
+/**
+ * The scene's camera controls, and the gesture handlers that drive them.
+ *
+ * Registered as R3F's default controls (`makeDefault`) so everything else reaches them through
+ * `state.controls`. Every mouse and touch action starts switched off, and each handler mounted
+ * below claims the ones it needs — so what a user can do is exactly the set of handlers standing
+ * here, and turning one off is unmounting it.
+ *
+ * **How far the camera may go is not decided here.** The zoom and pitch bounds constrain a
+ * programmatic move as much as a dragged one, so they belong to the camera; `Camera` writes them,
+ * beside the clipping planes derived from the same numbers. This component is only about what the
+ * user may do.
+ * @param props - What the user may do with the plan.
+ * @returns The controls and their handlers.
+ */
+export declare function Controls(props: ControlsProps): ReactNode;
+//# sourceMappingURL=Controls.d.ts.map

package/dist/controls/Controls.js

@@ -0,0 +1,54 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { CameraControls } from './CameraControls';
+import { Pan } from './handlers/Pan';
+import { Pitch } from './handlers/Pitch';
+import { Roll } from './handlers/Roll';
+import { Zoom } from './handlers/Zoom';
+/**
+ * The scene's camera controls, and the gesture handlers that drive them.
+ *
+ * Registered as R3F's default controls (`makeDefault`) so everything else reaches them through
+ * `state.controls`. Every mouse and touch action starts switched off, and each handler mounted
+ * below claims the ones it needs — so what a user can do is exactly the set of handlers standing
+ * here, and turning one off is unmounting it.
+ *
+ * **How far the camera may go is not decided here.** The zoom and pitch bounds constrain a
+ * programmatic move as much as a dragged one, so they belong to the camera; `Camera` writes them,
+ * beside the clipping planes derived from the same numbers. This component is only about what the
+ * user may do.
+ * @param props - What the user may do with the plan.
+ * @returns The controls and their handlers.
+ */
+export function Controls(props) {
+    const controlsRef = useRef(null);
+    const config = props.config ?? {};
+    const pan = config.pan ?? true;
+    const zoom = config.zoom ?? true;
+    const roll = config.roll ?? DEV;
+    const pitch = config.pitch ?? DEV;
+    useEffect(() => {
+        // Straight down by default. Set through `rotateTo` rather than by assigning `polarAngle`, which
+        // skips `Spherical.makeSafe` — and a polar angle of exactly zero causes trouble with roll on
+        // mobile. Nothing sets a target: the scene's fit puts the plan's centre on the world origin,
+        // which is where the controls already orbit.
+        void controlsRef.current.rotateTo(0, 0);
+    }, []);
+    return (_jsxs(_Fragment, { children: [_jsx(CameraControls, { ref: controlsRef, makeDefault: true, events: true, dollyToCursor: true, controlSmoothTime: { rotate: 0, truck: 0 } }), pan !== false && _jsx(Pan, { ...optionsOf(pan) }), zoom !== false && _jsx(Zoom, { ...optionsOf(zoom) }), roll !== false && _jsx(Roll, { ...optionsOf(roll) }), pitch !== false && _jsx(Pitch, {})] }));
+}
+/**
+ * The options a handler was configured with, if it was given any rather than a bare flag.
+ * @param config - What the caller wrote for it.
+ * @returns The options, or an empty set for a handler switched on without any.
+ */
+function optionsOf(config) {
+    return typeof config === 'object' ? config : {};
+}
+/**
+ * Whether this is a development build, which is what roll and pitch default to.
+ *
+ * Typed inline rather than through `vite/client`, matching `stories/support/screenshot.ts`: the
+ * library build compiles without those types, and the optional chain keeps a consumer whose bundler
+ * defines no `import.meta.env` from throwing on it.
+ */
+const DEV = import.meta.env?.DEV === true;

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

@@ -0,0 +1,226 @@
+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;
+    /**
+     * Asks React Three Fiber to draw another frame.
+     *
+     * A command changes the controls directly. That change happens outside a React commit. React
+     * Three Fiber cannot see it on its own. Calling this schedules the frame that shows the change,
+     * under a demand frame loop that would otherwise never draw one.
+     */
+    invalidate: () => void;
+}
+/**
+ * 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>;
+    /**
+     * Runs a move against the controls and asks for the frame that shows it.
+     *
+     * Every method above that takes {@link TransitionOptions} funnels its move through this one
+     * helper. A method that calls `controls` directly instead skips it, and looks obviously unlike
+     * its siblings.
+     *
+     * The invalidate happens before the move settles, not after, and every time, not only when the
+     * move is immediate. An eased move already triggers its own invalidate through `transitionstart`.
+     * An immediate move fires no event at all. `camera-controls` only applies an immediate move inside
+     * its own `update`, which runs from a frame that only an invalidate schedules. Invalidating after
+     * the move's promise settles would be too late to schedule that frame.
+     *
+     * A field and not a method, so it never lands on `CameraCommands.prototype`. The guard spec walks
+     * that prototype and calls everything it finds there, and an implementation detail would fail that
+     * walk for no reason.
+     * @param move - Issues the move against the controls and returns its promise.
+     * @returns The same promise `move` returned.
+     */
+    private withInvalidate;
+}
+/**
+ * How far the plan is turned from north: clockwise, in radians, in `[0, 2π)`.
+ *
+ * The camera holds an azimuth, which runs the other way and over any range the user has spun it
+ * through. Every reader of "which way is the plan facing" wants this instead, so the negation and
+ * the wrap live here once rather than at each of them — the same getter the imperative renderer put
+ * on its controller. Beside the rest of "where the camera is", which is the only question it
+ * answers.
+ * @param controls - The scene's controls.
+ * @returns The bearing in radians.
+ */
+export declare function bearing(controls: CameraControlsImpl): number;
+export {};
+//# sourceMappingURL=camera-api.d.ts.map

package/dist/controls/camera-api.js

@@ -0,0 +1,179 @@
+import { angleDiff, degToRad } from '@expofp/geometry';
+import { Vector3 } from 'three';
+import { euclideanModulo } from '../utils/math';
+import { fitBox, framingRegion } from './zoom-to';
+/**
+ * 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 this.withInvalidate(() => 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 this.withInvalidate(() => 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 this.withInvalidate(() => 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 this.withInvalidate(() => 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 this.withInvalidate(() => controls.rotateAzimuthTo(controls.azimuthAngle + delta, !options?.immediate));
+    }
+    /** @inheritdoc */
+    rollBy(degrees, options) {
+        const { controls } = this.context;
+        if (!controls)
+            return RESOLVED;
+        return this.withInvalidate(() => 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 this.withInvalidate(() => controls.rotatePolarTo(degToRad(degrees), !options?.immediate));
+    }
+    /** @inheritdoc */
+    pitchBy(degrees, options) {
+        const { controls } = this.context;
+        if (!controls)
+            return RESOLVED;
+        return this.withInvalidate(() => 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 this.withInvalidate(() => Promise.all(moves));
+    }
+    /**
+     * Runs a move against the controls and asks for the frame that shows it.
+     *
+     * Every method above that takes {@link TransitionOptions} funnels its move through this one
+     * helper. A method that calls `controls` directly instead skips it, and looks obviously unlike
+     * its siblings.
+     *
+     * The invalidate happens before the move settles, not after, and every time, not only when the
+     * move is immediate. An eased move already triggers its own invalidate through `transitionstart`.
+     * An immediate move fires no event at all. `camera-controls` only applies an immediate move inside
+     * its own `update`, which runs from a frame that only an invalidate schedules. Invalidating after
+     * the move's promise settles would be too late to schedule that frame.
+     *
+     * A field and not a method, so it never lands on `CameraCommands.prototype`. The guard spec walks
+     * that prototype and calls everything it finds there, and an implementation detail would fail that
+     * walk for no reason.
+     * @param move - Issues the move against the controls and returns its promise.
+     * @returns The same promise `move` returned.
+     */
+    withInvalidate = (move) => {
+        this.context.invalidate();
+        return move();
+    };
+}
+/**
+ * How far the plan is turned from north: clockwise, in radians, in `[0, 2π)`.
+ *
+ * The camera holds an azimuth, which runs the other way and over any range the user has spun it
+ * through. Every reader of "which way is the plan facing" wants this instead, so the negation and
+ * the wrap live here once rather than at each of them — the same getter the imperative renderer put
+ * on its controller. Beside the rest of "where the camera is", which is the only question it
+ * answers.
+ * @param controls - The scene's controls.
+ * @returns The bearing in radians.
+ */
+export function bearing(controls) {
+    return euclideanModulo(-controls.azimuthAngle, 2 * Math.PI);
+}
+/**
+ * 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/gestures.d.ts

@@ -0,0 +1,71 @@
+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 — as does the double tap that
+ * `Zoom` zooms on, which camera-controls does not recognize either.
+ *
+ * The recognizer itself is shared: `Roll`, `Pitch` and `Zoom` 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