@expofp/renderer 3.2.5 → 3.27.0

package/dist/controls/handlers/Pitch.js

@@ -0,0 +1,191 @@
+import { degToRad } from '@expofp/geometry';
+import { useState } from 'react';
+import { Vector2 } from 'three';
+import { CameraControlsImpl, useCameraControls, useControlsEffect } from '../CameraControls';
+import { canvasPoint, useGesture } from '../gestures';
+/**
+ * Pitching: a right-drag, and two fingers dragged vertically together.
+ *
+ * The right-drag is camera-controls' own polar rotation. The vertical drag is not, and the hard
+ * part is not applying it but telling it apart from the pinch and the twist that share two fingers.
+ * That judgement lives in {@link beginsVertically}, and until it is settled the gesture does
+ * nothing.
+ *
+ * The pitch **limits** are not here. They constrain the camera whether or not this handler is
+ * mounted — the imperative renderer applied them from its pitch handler's constructor for exactly
+ * that reason — so they are `Camera`'s, alongside the zoom bounds and the clipping planes derived
+ * from both.
+ *
+ * Mounting is enabling. The mouse action shares a field with `Roll`, so it is set and cleared with
+ * `|=` and `&= ~`, which are idempotent where an exclusive-or would not be.
+ * @returns Nothing; this renders no scene node.
+ */
+export function Pitch() {
+    // Read, not written: the gesture below takes the controls as an argument and does the writing.
+    const controls = useCameraControls();
+    const [gesture] = useState(() => new PitchGesture());
+    useControlsEffect((controls) => {
+        controls.mouseButtons.right |= ACTION.ROTATE_POLAR;
+        return () => {
+            controls.mouseButtons.right &= ~ACTION.ROTATE_POLAR;
+            // Unmounting mid-gesture would otherwise leave the two-finger action switched off for
+            // whichever handler owns it.
+            gesture.end(controls);
+        };
+    });
+    // Each of these is cached by the React Compiler against what it captures, so `useGesture`
+    // re-subscribes only when one of those actually moves — in practice, never.
+    const onPitchStart = (event) => gesture.start(event);
+    const onPitch = (event) => {
+        if (controls)
+            gesture.move(event, controls);
+    };
+    const onPitchEnd = () => gesture.end(controls);
+    useGesture('pitchstart', onPitchStart);
+    useGesture('pitch', onPitch);
+    useGesture('pitchend', onPitchEnd);
+    return null;
+}
+/**
+ * Two fingers dragged vertically together, tilting the plan.
+ *
+ * A class rather than fields on the component, for two reasons that agree: the React Compiler
+ * refuses a direct write to anything `useState` returned, and the gesture's arbitration is worth
+ * testing without a canvas around it. {@link Pitch} is the React half.
+ */
+export class PitchGesture {
+    verdict = {};
+    lastPoints;
+    prevTwoFingerAction;
+    p0 = new Vector2();
+    p1 = new Vector2();
+    /**
+     * Remembers where the fingers started, and rules the gesture out when they are stacked one above
+     * the other — from there a vertical drag is indistinguishable from a pinch.
+     * @param event - The gesture event that began the drag.
+     */
+    start(event) {
+        const pointers = byPointerId(event);
+        if (pointers.length !== 2)
+            return;
+        this.p0.copy(canvasPoint(pointers[0]));
+        this.p1.copy(canvasPoint(pointers[1]));
+        this.lastPoints = [new Vector2().copy(this.p0), new Vector2().copy(this.p1)];
+        if (isVertical(this.p0.sub(this.p1)))
+            this.verdict.isValid = false;
+    }
+    /**
+     * Tilts the plan by how far the fingers moved down the screen, once the gesture has been judged
+     * a pitch.
+     * @param event - The gesture event carrying the drag so far.
+     * @param controls - The controls to tilt.
+     */
+    move(event, controls) {
+        const lastPoints = this.lastPoints;
+        if (!lastPoints)
+            return;
+        const pointers = byPointerId(event);
+        if (pointers.length !== 2)
+            return;
+        // From here on `p0` and `p1` are movements rather than positions.
+        this.p0.copy(canvasPoint(pointers[0])).sub(lastPoints[0]);
+        this.p1.copy(canvasPoint(pointers[1])).sub(lastPoints[1]);
+        if (!beginsVertically(this.p0, this.p1, event.timeStamp, this.verdict))
+            return;
+        // The pinch would otherwise dolly the plan while it is being tilted. Captured rather than
+        // assumed, so whatever the zoom handler put there is what comes back at the end of the gesture.
+        if (this.prevTwoFingerAction === undefined) {
+            this.prevTwoFingerAction = controls.touches.two;
+            controls.touches.two = ACTION.NONE;
+        }
+        lastPoints[0].add(this.p0);
+        lastPoints[1].add(this.p1);
+        const yDeltaAverage = (this.p0.y + this.p1.y) / 2;
+        const deltaAngle = degToRad(yDeltaAverage * DEGREES_PER_PIXEL);
+        void controls.rotatePolarTo(controls.polarAngle + deltaAngle, false);
+    }
+    /**
+     * Puts back the two-finger action this suppressed, if it suppressed one, and forgets the gesture.
+     *
+     * Nothing is restored when the captured action was already `NONE`: there was nothing to suppress,
+     * and writing it back would claim a field this handler does not own.
+     * @param controls - The controls to restore, if they are still there.
+     */
+    end(controls) {
+        if (controls && this.prevTwoFingerAction)
+            controls.touches.two = this.prevTwoFingerAction;
+        this.prevTwoFingerAction = undefined;
+        this.verdict = {};
+        this.lastPoints = undefined;
+    }
+}
+/**
+ * Whether a two-finger gesture is a pitch, judged from how the fingers first moved.
+ *
+ * Judged once and then held: the verdict is returned unchanged as soon as it has one, so a drag
+ * that started as a pitch stays one even if the fingers wander, and one that did not can never
+ * become one. A `false` verdict is what makes a pinch or a twist stay a pinch or a twist.
+ *
+ * The two fingers rarely start moving on the same frame, so one moving alone is not by itself a
+ * verdict — the other is given {@link ALLOWED_SINGLE_TOUCH_TIME} to follow, and only when it fails
+ * to is the gesture ruled out.
+ * @param a - How far the first finger moved since the last event.
+ * @param b - How far the second finger moved since the last event.
+ * @param timeStamp - When this event happened, in milliseconds.
+ * @param verdict - How far the judgement has got; updated in place.
+ * @returns Whether this is a pitch — `false` both for "not a pitch" and for "not yet decided", the
+ *   two cases a caller treats alike by doing nothing.
+ */
+export function beginsVertically(a, b, timeStamp, verdict) {
+    verdict.isValid = judge(a, b, timeStamp, verdict);
+    return verdict.isValid === true;
+}
+/**
+ * Whether a movement is more down-the-screen than across it.
+ * @param vector - The movement to judge.
+ * @returns Whether it is vertical.
+ */
+export function isVertical(vector) {
+    return Math.abs(vector.y) > Math.abs(vector.x);
+}
+/**
+ * The judgement itself, which unlike {@link beginsVertically} distinguishes "not a pitch" from
+ * "the fingers have not said yet".
+ * @param a - How far the first finger moved since the last event.
+ * @param b - How far the second finger moved since the last event.
+ * @param timeStamp - When this event happened, in milliseconds.
+ * @param verdict - How far the judgement has got; its `firstMove` is set when one finger moves alone.
+ * @returns Whether this is a pitch, or `undefined` while the fingers have not said.
+ */
+function judge(a, b, timeStamp, verdict) {
+    if (verdict.isValid !== undefined)
+        return verdict.isValid;
+    const movedA = a.length() >= MOVE_THRESHOLD_PX;
+    const movedB = b.length() >= MOVE_THRESHOLD_PX;
+    // Neither finger has moved a meaningful amount; wait.
+    if (!movedA && !movedB)
+        return undefined;
+    // One finger has moved and the other has not. Wait a moment for the second, then give up.
+    if (!movedA || !movedB) {
+        verdict.firstMove ??= timeStamp;
+        return timeStamp - verdict.firstMove < ALLOWED_SINGLE_TOUCH_TIME ? undefined : false;
+    }
+    const sameDirection = a.y > 0 === b.y > 0;
+    return isVertical(a) && isVertical(b) && sameDirection;
+}
+/**
+ * The gesture's pointers in a stable order, so "the first finger" means the same finger from one
+ * event to the next and its movement can be diffed.
+ * @param event - The gesture event.
+ * @returns The pointers ordered by id — a copy, so the recognizer's own array is left alone.
+ */
+function byPointerId(event) {
+    return event.pointers.slice().sort((a, b) => a.pointerId - b.pointerId);
+}
+const ACTION = CameraControlsImpl.ACTION;
+/** How far the plan tilts per pixel the fingers travel down the screen, in degrees. */
+const DEGREES_PER_PIXEL = -0.5;
+/** How far a finger must travel before it counts as having moved, in pixels. */
+const MOVE_THRESHOLD_PX = 2;
+/** How long the second finger has to join the first before the gesture is ruled out, in milliseconds. */
+const ALLOWED_SINGLE_TOUCH_TIME = 100;

package/dist/controls/handlers/Roll.d.ts

@@ -0,0 +1,103 @@
+import { type MjolnirGestureEvent } from 'mjolnir.js';
+import { type GestureContext } from '../gestures';
+/** Options for the roll handler, which are also its props. */
+export interface RollConfig {
+    /**
+     * How far two fingers must twist before the plan starts turning, in pixels along the
+     * circumference of the circle they describe; defaults to `25`.
+     *
+     * Measured along the circumference rather than in degrees — the Mapbox rule — so the same
+     * threshold asks for a wide turn when the fingers are close together and a slight one when they
+     * are far apart, which is what stops a pinch from turning the plan by accident.
+     */
+    threshold?: number;
+}
+/**
+ * Rolling: a right-drag, and a two-finger twist.
+ *
+ * The right-drag is camera-controls' own azimuth rotation. The twist is not — it turns the plan
+ * about **the point between the fingers** rather than about whatever the camera is looking at,
+ * which is what makes two fingers feel like they are holding the plan itself. camera-controls can
+ * only orbit its target, so the twist is recognized off the canvas's gesture manager and applied
+ * by {@link RollGesture}.
+ *
+ * Mounting is enabling. The mouse action is a bit of a shared field — `Pitch` owns the other one —
+ * so it is set and cleared with `|=` and `&= ~` rather than assigned. Both are idempotent, which an
+ * exclusive-or (the imperative renderer's) is not: `StrictMode` re-running an effect would flip a
+ * bit back on.
+ * @param props - How far a twist must travel before it turns the plan.
+ * @returns Nothing; this renders no scene node.
+ */
+export declare function Roll(props: RollConfig): null;
+/**
+ * A two-finger twist, turning the plan about the point between the fingers.
+ *
+ * A class rather than fields on the component, for two reasons that agree: the React Compiler
+ * refuses a direct write to anything `useState` returned, and this half — where the fingers are,
+ * how far they have turned, where the pivot lands — is worth testing without a canvas around it.
+ * {@link Roll} is the React half: when to subscribe, and what the scene currently holds.
+ */
+export declare class RollGesture {
+    private isRolling;
+    private startVector?;
+    private minDiameter;
+    private prevAngle;
+    private vector;
+    private p0;
+    private p1;
+    private pivotPlan;
+    private pivotWorld;
+    private targetWorld;
+    private cameraPosition;
+    private cameraForward;
+    private rotation;
+    /**
+     * Remembers where the fingers started, which the twist is measured against.
+     * @param event - The gesture event that began the twist.
+     */
+    start(event: MjolnirGestureEvent): void;
+    /**
+     * Turns the plan by however far the fingers have twisted since the last event, once the gesture
+     * has passed its threshold.
+     * @param event - The gesture event carrying the twist so far.
+     * @param threshold - How far a twist must travel before it takes, in pixels of circumference.
+     * @param context - What the scene currently holds.
+     */
+    move(event: MjolnirGestureEvent, threshold: number, context: GestureContext): void;
+    /** Forgets the gesture, so the next twist measures its threshold afresh. */
+    end(): void;
+    /**
+     * Whether the twist so far is still inside its threshold, narrowing the remembered diameter as it
+     * goes.
+     *
+     * The narrowest the fingers have been is what the threshold is sized against, rather than where
+     * they are now, so pinching in and out during a twist does not make it progressively touchier.
+     * @param threshold - The distance along the circumference, in pixels.
+     * @returns Whether the plan should stay put.
+     */
+    private belowThreshold;
+    /**
+     * Puts the pivot under the point between the fingers, and reads the camera's stance around it.
+     *
+     * The pivot is found on the plan and converted back out to the world, rather than crossed with
+     * the world's own `z = 0` plane. The two agree under the viewbox fit; only this one stays right
+     * for a host that placed the plan itself, at a tilt or off the world origin.
+     * @param center - The point between the fingers, in css pixels from the canvas's top-left corner.
+     * @param context - What the scene currently holds.
+     * @returns Whether a pivot was found — a camera looking along the plan never meets it.
+     */
+    private setPivot;
+}
+/**
+ * How far a twist must turn before it takes, in degrees, for fingers this far apart.
+ *
+ * The threshold is a distance along the circumference of the circle the fingers describe — the
+ * Mapbox rule — so the angle it works out to is wide when the fingers are close together and narrow
+ * when they are far apart. That is what keeps a pinch from turning the plan by accident while
+ * leaving a deliberate two-handed twist responsive.
+ * @param minDiameter - The narrowest the fingers have been during the gesture, in pixels.
+ * @param threshold - The distance along the circumference, in pixels.
+ * @returns The angle in degrees; infinite while the fingers are together, so nothing turns.
+ */
+export declare function rollThresholdDegrees(minDiameter: number, threshold: number): number;
+//# sourceMappingURL=Roll.d.ts.map

package/dist/controls/handlers/Roll.js

@@ -0,0 +1,182 @@
+import { degToRad, Point, radToDeg } from '@expofp/geometry';
+import { useThree } from '@react-three/fiber';
+import { useState } from 'react';
+import { Matrix4, Vector2, Vector3 } from 'three';
+import { useSpace } from '../../space/Space';
+import { CameraControlsImpl, useCameraControls, useControlsEffect } from '../CameraControls';
+import { canvasPoint, useGesture } from '../gestures';
+/**
+ * Rolling: a right-drag, and a two-finger twist.
+ *
+ * The right-drag is camera-controls' own azimuth rotation. The twist is not — it turns the plan
+ * about **the point between the fingers** rather than about whatever the camera is looking at,
+ * which is what makes two fingers feel like they are holding the plan itself. camera-controls can
+ * only orbit its target, so the twist is recognized off the canvas's gesture manager and applied
+ * by {@link RollGesture}.
+ *
+ * Mounting is enabling. The mouse action is a bit of a shared field — `Pitch` owns the other one —
+ * so it is set and cleared with `|=` and `&= ~` rather than assigned. Both are idempotent, which an
+ * exclusive-or (the imperative renderer's) is not: `StrictMode` re-running an effect would flip a
+ * bit back on.
+ * @param props - How far a twist must travel before it turns the plan.
+ * @returns Nothing; this renders no scene node.
+ */
+export function Roll(props) {
+    const threshold = props.threshold ?? DEFAULT_THRESHOLD;
+    const get = useThree((state) => state.get);
+    // Read, not written: the gesture below takes the controls as an argument and does the writing, so
+    // nothing here ever assigns to them — which is the line the React Compiler draws.
+    const controls = useCameraControls();
+    const space = useSpace();
+    const [gesture] = useState(() => new RollGesture());
+    useControlsEffect((controls) => {
+        controls.mouseButtons.right |= ACTION.ROTATE_AZIMUTH;
+        return () => {
+            controls.mouseButtons.right &= ~ACTION.ROTATE_AZIMUTH;
+        };
+    });
+    // Each of these is cached by the React Compiler against what it captures, so `useGesture`
+    // re-subscribes only when one of those actually moves — in practice, never.
+    const onRotateStart = (event) => gesture.start(event);
+    const onRotate = (event) => {
+        if (controls)
+            gesture.move(event, threshold, { controls, camera: get().camera, space });
+    };
+    const onRotateEnd = () => gesture.end();
+    useGesture('rotatestart', onRotateStart);
+    useGesture('rotate', onRotate);
+    useGesture('rotateend', onRotateEnd);
+    return null;
+}
+/**
+ * A two-finger twist, turning the plan about the point between the fingers.
+ *
+ * A class rather than fields on the component, for two reasons that agree: the React Compiler
+ * refuses a direct write to anything `useState` returned, and this half — where the fingers are,
+ * how far they have turned, where the pivot lands — is worth testing without a canvas around it.
+ * {@link Roll} is the React half: when to subscribe, and what the scene currently holds.
+ */
+export class RollGesture {
+    isRolling = false;
+    startVector;
+    minDiameter = 0;
+    prevAngle = 0;
+    vector = new Vector2();
+    p0 = new Vector2();
+    p1 = new Vector2();
+    pivotPlan = new Point();
+    pivotWorld = new Vector3();
+    targetWorld = new Vector3();
+    cameraPosition = new Vector3();
+    cameraForward = new Vector3();
+    rotation = new Matrix4();
+    /**
+     * Remembers where the fingers started, which the twist is measured against.
+     * @param event - The gesture event that began the twist.
+     */
+    start(event) {
+        const { pointers } = event;
+        this.p0.copy(canvasPoint(pointers[0]));
+        this.p1.copy(canvasPoint(pointers[1]));
+        this.startVector = new Vector2().copy(this.p0).sub(this.p1);
+        this.minDiameter = this.startVector.length();
+    }
+    /**
+     * Turns the plan by however far the fingers have twisted since the last event, once the gesture
+     * has passed its threshold.
+     * @param event - The gesture event carrying the twist so far.
+     * @param threshold - How far a twist must travel before it takes, in pixels of circumference.
+     * @param context - What the scene currently holds.
+     */
+    move(event, threshold, context) {
+        const { controls } = context;
+        const { pointers } = event;
+        if (!this.isRolling) {
+            if (pointers.length !== 2)
+                return;
+            this.p0.copy(canvasPoint(pointers[0]));
+            this.p1.copy(canvasPoint(pointers[1]));
+            this.vector.copy(this.p0).sub(this.p1);
+            if (this.belowThreshold(threshold))
+                return;
+            this.isRolling = true;
+            this.prevAngle = event.rotation;
+        }
+        // Negated: the recognizer measures the twist clockwise on screen, and the azimuth it drives
+        // grows the other way.
+        const deltaAngle = -degToRad(event.rotation - this.prevAngle);
+        this.prevAngle = event.rotation;
+        if (Math.abs(deltaAngle) < MIN_ROLL_STEP)
+            return;
+        // mjolnir measures the midpoint from the target's own padding edge, as `canvasPoint` does.
+        if (!this.setPivot(event.offsetCenter, context))
+            return;
+        // The plan's own up axis is world z, so turning the plan is a rotation about it.
+        this.rotation.makeRotationZ(deltaAngle);
+        this.cameraPosition.sub(this.pivotWorld).applyMatrix4(this.rotation).add(this.pivotWorld);
+        this.cameraForward.applyMatrix4(this.rotation);
+        this.targetWorld.copy(this.cameraPosition).add(this.cameraForward);
+        void controls.setLookAt(this.cameraPosition.x, this.cameraPosition.y, this.cameraPosition.z, this.targetWorld.x, this.targetWorld.y, this.targetWorld.z, false);
+    }
+    /** Forgets the gesture, so the next twist measures its threshold afresh. */
+    end() {
+        this.isRolling = false;
+        this.startVector = undefined;
+        this.minDiameter = 0;
+    }
+    /**
+     * Whether the twist so far is still inside its threshold, narrowing the remembered diameter as it
+     * goes.
+     *
+     * The narrowest the fingers have been is what the threshold is sized against, rather than where
+     * they are now, so pinching in and out during a twist does not make it progressively touchier.
+     * @param threshold - The distance along the circumference, in pixels.
+     * @returns Whether the plan should stay put.
+     */
+    belowThreshold(threshold) {
+        this.minDiameter = Math.min(this.minDiameter, this.vector.length());
+        const startVector = this.startVector;
+        if (!startVector)
+            return false;
+        return (radToDeg(this.vector.angleTo(startVector)) < rollThresholdDegrees(this.minDiameter, threshold));
+    }
+    /**
+     * Puts the pivot under the point between the fingers, and reads the camera's stance around it.
+     *
+     * The pivot is found on the plan and converted back out to the world, rather than crossed with
+     * the world's own `z = 0` plane. The two agree under the viewbox fit; only this one stays right
+     * for a host that placed the plan itself, at a tilt or off the world origin.
+     * @param center - The point between the fingers, in css pixels from the canvas's top-left corner.
+     * @param context - What the scene currently holds.
+     * @returns Whether a pivot was found — a camera looking along the plan never meets it.
+     */
+    setPivot(center, context) {
+        const { controls, camera, space } = context;
+        if (!space.canvasToPlan(center, camera, this.pivotPlan))
+            return false;
+        space.planToWorld(this.pivotPlan, this.pivotWorld);
+        controls.getPosition(this.cameraPosition);
+        controls.getTarget(this.targetWorld);
+        this.cameraForward.copy(this.targetWorld).sub(this.cameraPosition);
+        return true;
+    }
+}
+/**
+ * How far a twist must turn before it takes, in degrees, for fingers this far apart.
+ *
+ * The threshold is a distance along the circumference of the circle the fingers describe — the
+ * Mapbox rule — so the angle it works out to is wide when the fingers are close together and narrow
+ * when they are far apart. That is what keeps a pinch from turning the plan by accident while
+ * leaving a deliberate two-handed twist responsive.
+ * @param minDiameter - The narrowest the fingers have been during the gesture, in pixels.
+ * @param threshold - The distance along the circumference, in pixels.
+ * @returns The angle in degrees; infinite while the fingers are together, so nothing turns.
+ */
+export function rollThresholdDegrees(minDiameter, threshold) {
+    return (threshold / (Math.PI * minDiameter)) * 360;
+}
+const ACTION = CameraControlsImpl.ACTION;
+/** The smallest turn worth applying, in radians — below this the twist is recognizer noise. */
+const MIN_ROLL_STEP = 0.001;
+/** How far a two-finger twist must travel before it turns the plan, in pixels of circumference. */
+const DEFAULT_THRESHOLD = 25;

package/dist/controls/handlers/Zoom.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Zooming: the wheel, and a two-finger pinch.
+ *
+ * Nothing here beyond the actions — camera-controls recognizes both gestures itself, and `Controls`
+ * has already told it to dolly toward the cursor rather than the centre. The two-finger action pans
+ * as well as pinches, which is what makes a pinch feel like it holds the plan under the fingers;
+ * the twist half of a two-finger gesture is `Roll`'s, and comes off the gesture recognizer rather
+ * than from here, so the two never contend for `touches.two`.
+ *
+ * Mounting is enabling. The actions are set when this mounts and returned to `NONE` when it
+ * unmounts, which is the whole of what the imperative renderer's `enable()` / `disable()` did.
+ * @returns Nothing; this renders no scene node.
+ */
+export declare function Zoom(): null;
+//# sourceMappingURL=Zoom.d.ts.map

package/dist/controls/handlers/Zoom.js

@@ -0,0 +1,26 @@
+import { CameraControlsImpl, useControlsEffect } from '../CameraControls';
+/**
+ * Zooming: the wheel, and a two-finger pinch.
+ *
+ * Nothing here beyond the actions — camera-controls recognizes both gestures itself, and `Controls`
+ * has already told it to dolly toward the cursor rather than the centre. The two-finger action pans
+ * as well as pinches, which is what makes a pinch feel like it holds the plan under the fingers;
+ * the twist half of a two-finger gesture is `Roll`'s, and comes off the gesture recognizer rather
+ * than from here, so the two never contend for `touches.two`.
+ *
+ * Mounting is enabling. The actions are set when this mounts and returned to `NONE` when it
+ * unmounts, which is the whole of what the imperative renderer's `enable()` / `disable()` did.
+ * @returns Nothing; this renders no scene node.
+ */
+export function Zoom() {
+    useControlsEffect((controls) => {
+        controls.mouseButtons.wheel = ACTION.DOLLY;
+        controls.touches.two = ACTION.TOUCH_DOLLY_SCREEN_PAN;
+        return () => {
+            controls.mouseButtons.wheel = ACTION.NONE;
+            controls.touches.two = ACTION.NONE;
+        };
+    });
+    return null;
+}
+const ACTION = CameraControlsImpl.ACTION;

package/dist/controls/index.d.ts

@@ -0,0 +1,56 @@
+import { type ReactNode } from 'react';
+import { type PanConfig } from './handlers/Pan';
+import { type RollConfig } from './handlers/Roll';
+export { type CameraAPI, type CameraAxes, CameraCommands, type TransitionOptions, useCameraAPI, type ZoomToOptions, } from './camera-api';
+export { useCameraMoveStart } from './camera-move';
+export { type CameraState, useCameraState } from './camera-state';
+export { bearing, CameraControls, CameraControlsImpl, useCameraControls, useControlsEffect, } from './CameraControls';
+export type { InertiaConfig } from './handlers/Inertia';
+export type { PanConfig } from './handlers/Pan';
+export type { RollConfig } from './handlers/Roll';
+/**
+ * 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. */
+    zoom?: boolean;
+    /** 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=index.d.ts.map

package/dist/controls/index.js

@@ -0,0 +1,58 @@
+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';
+export { CameraCommands, useCameraAPI, } from './camera-api';
+export { useCameraMoveStart } from './camera-move';
+export { useCameraState } from './camera-state';
+export { bearing, CameraControls, CameraControlsImpl, useCameraControls, useControlsEffect, } from './CameraControls';
+/**
+ * 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, {}), 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;