@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/controls/handlers/Pan.js

@@ -0,0 +1,212 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Point } from '@expofp/geometry';
+import { useThree } from '@react-three/fiber';
+import { useEffect, useState } from 'react';
+import { Vector3 } from 'three';
+import { useSpace, } from '../../space/Space';
+import { CameraControlsAction } from '../CameraControls';
+import { canvasPoint } from '../gestures';
+import { useCameraControls, useControlsEffect } from '../hooks';
+import { Inertia } from './Inertia';
+/**
+ * Panning: a left-drag, and a one-finger drag.
+ *
+ * Screen-pan rather than truck, so the plan tracks the pointer at any pitch instead of sliding
+ * along the camera's own axes — the imperative renderer's choice, and what makes a tilted plan drag
+ * the way a map does.
+ *
+ * Owns the glide a lifted pointer leaves by rendering {@link PanInertia}, which is the one piece of
+ * panning camera-controls does not do itself.
+ *
+ * Mounting is enabling: the actions are set on mount and returned to `NONE` on unmount.
+ * @param props - Whether a pan glides, and how.
+ * @returns The glide, when there is one.
+ */
+export function Pan(props) {
+    const inertia = props.inertia ?? true;
+    useControlsEffect((controls) => {
+        controls.mouseButtons.left = CameraControlsAction.SCREEN_PAN;
+        controls.touches.one = CameraControlsAction.TOUCH_SCREEN_PAN;
+        return () => {
+            controls.mouseButtons.left = CameraControlsAction.NONE;
+            controls.touches.one = CameraControlsAction.NONE;
+        };
+    });
+    if (inertia === false)
+        return null;
+    return _jsx(PanInertia, { ...(inertia === true ? {} : inertia) });
+}
+/**
+ * The glide a pan leaves behind: {@link Inertia}, fed the pan itself.
+ *
+ * **Measured from the pointers, not from the camera.** Every step of a drag that pans — by mouse,
+ * by one finger, or by two fingers pinching and panning at once — samples how far the pointers'
+ * centroid moved, in css pixels. That is the pan camera-controls applies on the same step, and
+ * nothing else: a pinch spreads the fingers about their centroid, and a twist turns them about it,
+ * so neither moves it, and neither leaks into the glide. A step whose action has no pan in it — a
+ * right-drag turn, or a tilt, which switches the two-finger action off — samples nothing.
+ *
+ * Applied the same way round: each step of the glide moves the plan so that the point under the
+ * last centroid travels the step's pixels, which glides a tilted or turned plan the way the drag
+ * moved it.
+ *
+ * A component of its own rather than a branch inside {@link Pan}, because its hooks cannot be
+ * switched off conditionally — mounting this is what switches the glide on.
+ * @param props - How the glide is measured and how it slows.
+ * @returns The glide.
+ */
+function PanInertia(props) {
+    const canvas = useThree((state) => state.gl.domElement);
+    const get = useThree((state) => state.get);
+    const space = useSpace();
+    // Read, not written: `panBy` takes the controls as an argument and does the writing.
+    const controls = useCameraControls();
+    const [pointers] = useState(() => new PointerCentroid());
+    useEffect(() => {
+        pointers.connect(canvas);
+        return () => pointers.disconnect();
+    }, [pointers, canvas]);
+    const sample = () => {
+        // Always taken, so a step that sat the pan out does not leave its movement for the next one.
+        const delta = pointers.sample();
+        return controls && (controls.currentAction & PAN) !== 0 ? delta : undefined;
+    };
+    const apply = (step) => controls !== undefined && panBy(controls, space, get().camera, pointers.anchor, step);
+    return _jsx(Inertia, { ...props, sample: sample, apply: apply });
+}
+/**
+ * Where the pointers are, and how far their centroid has moved since the last sample.
+ *
+ * Measured the way MapLibre's touch pan measures it: as the average movement of the pointers that
+ * were down at both samples. A finger that lands or lifts between two samples therefore adds no
+ * jump of its own, where the raw centroid would leap halfway to it.
+ */
+class PointerCentroid {
+    /** Where the pointers' centroid was at the last sample, in css pixels from the canvas's corner. */
+    anchor = new Point();
+    element;
+    positions = new Map();
+    last = new Map();
+    delta = [0, 0];
+    /**
+     * Starts tracking the pointers that land on an element. Moves and lifts are heard on its
+     * document, as camera-controls hears them, so a mouse dragged off the canvas is still followed.
+     * @param element - The element pointers land on.
+     */
+    connect(element) {
+        if (this.element)
+            this.disconnect();
+        this.element = element;
+        const document = element.ownerDocument;
+        element.addEventListener('pointerdown', this.onDown);
+        document.addEventListener('pointermove', this.onMove);
+        document.addEventListener('pointerup', this.onUp);
+        document.addEventListener('pointercancel', this.onUp);
+    }
+    /** Stops tracking, and forgets every pointer. */
+    disconnect() {
+        const element = this.element;
+        if (!element)
+            return;
+        const document = element.ownerDocument;
+        element.removeEventListener('pointerdown', this.onDown);
+        document.removeEventListener('pointermove', this.onMove);
+        document.removeEventListener('pointerup', this.onUp);
+        document.removeEventListener('pointercancel', this.onUp);
+        this.positions.clear();
+        this.last.clear();
+        this.element = undefined;
+    }
+    /**
+     * How far the centroid moved since the last call, and where it is now.
+     * @returns The movement in css pixels, as `[x, y]`; reused between calls.
+     */
+    sample() {
+        let dx = 0;
+        let dy = 0;
+        let moved = 0;
+        let cx = 0;
+        let cy = 0;
+        for (const [id, position] of this.positions) {
+            cx += position.x;
+            cy += position.y;
+            const last = this.last.get(id);
+            if (!last)
+                continue;
+            dx += position.x - last.x;
+            dy += position.y - last.y;
+            last.x = position.x;
+            last.y = position.y;
+            moved++;
+        }
+        if (this.positions.size)
+            this.anchor.set(cx / this.positions.size, cy / this.positions.size, 0);
+        this.delta[0] = moved ? dx / moved : 0;
+        this.delta[1] = moved ? dy / moved : 0;
+        return this.delta;
+    }
+    /**
+     * A pointer landing on the canvas, whose `offsetX` is measured from the canvas itself. Its later
+     * moves are heard on the document and may target any element, so their own `offsetX` is not the
+     * canvas's — they are placed by how far they moved in client pixels from where this one landed.
+     * @param event - The pointer landing.
+     */
+    onDown = (event) => {
+        const { x, y } = canvasPoint(event);
+        this.positions.set(event.pointerId, {
+            x,
+            y,
+            toCanvasX: x - event.clientX,
+            toCanvasY: y - event.clientY,
+        });
+        this.last.set(event.pointerId, { x, y });
+    };
+    onMove = (event) => {
+        const position = this.positions.get(event.pointerId);
+        if (!position)
+            return;
+        position.x = event.clientX + position.toCanvasX;
+        position.y = event.clientY + position.toCanvasY;
+    };
+    onUp = (event) => {
+        this.positions.delete(event.pointerId);
+        this.last.delete(event.pointerId);
+    };
+}
+/**
+ * Pans the plan by a step in css pixels: the point under `anchor` moves to `anchor + step`.
+ *
+ * Both points are found on the plan through the camera and taken out to the world, and the target
+ * moves by their difference — so a tilted plan, whose pixels cover more ground toward the horizon,
+ * glides as far as the drag would have carried it there.
+ * @param controls - The controls to move.
+ * @param space - The scene's space.
+ * @param camera - The camera the canvas is drawn through.
+ * @param anchor - Where the step starts, in css pixels from the canvas's top-left corner.
+ * @param step - How far to move, in css pixels, as `[x, y]`.
+ * @returns Whether it moved; a step off the plan, toward the horizon, does not.
+ */
+function panBy(controls, space, camera, anchor, step) {
+    const from = space.canvasToPlan(anchor, camera, _fromPlan);
+    const to = space.canvasToPlan({ x: anchor.x + step[0], y: anchor.y + step[1] }, camera, _toPlan);
+    if (!from || !to)
+        return false;
+    space.planToWorld(from, _fromWorld);
+    space.planToWorld(to, _toWorld);
+    const target = controls.getTarget(_target, false).add(_fromWorld).sub(_toWorld);
+    void controls.moveTo(target.x, target.y, target.z, false);
+    return true;
+}
+/**
+ * The controls' pan bits. A two-finger pinch that pans as it dollies carries one too, and its pan
+ * is sampled like any other: the centroid measures the pan alone.
+ */
+const PAN = CameraControlsAction.TRUCK |
+    CameraControlsAction.SCREEN_PAN |
+    CameraControlsAction.TOUCH_TRUCK |
+    CameraControlsAction.TOUCH_SCREEN_PAN;
+const _fromPlan = new Point();
+const _toPlan = new Point();
+const _fromWorld = new Vector3();
+const _toWorld = new Vector3();
+const _target = new Vector3();

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

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function Pitch(): null;
+//# sourceMappingURL=Pitch.d.ts.map

package/dist/controls/handlers/Pitch.js

@@ -0,0 +1,200 @@
+import { degToRad } from '@expofp/geometry';
+import { useState } from 'react';
+import { Vector2 } from 'three';
+import { CameraControlsAction } from '../CameraControls';
+import { canvasPoint, useGesture } from '../gestures';
+import { useCameraControls, useControlsEffect } from '../hooks';
+/**
+ * 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 |= CameraControlsAction.ROTATE_POLAR;
+        return () => {
+            controls.mouseButtons.right &= ~CameraControlsAction.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.
+ */
+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 = CameraControlsAction.NONE;
+            // Bracketed from the moment the drag is judged a tilt, which is also the moment it first
+            // moves the camera.
+            controls.dispatchEvent({ type: 'controlstart' });
+        }
+        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);
+        // The tilt moves the camera through a public setter, which the controls count as a command
+        // rather than the user's hand; reporting it is what tells an idle timer the user is here.
+        controls.dispatchEvent({ type: 'control' });
+    }
+    /**
+     * Puts back the two-finger action this suppressed, if it suppressed one, closes the
+     * `controlstart` the tilt opened, 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 and report to, if they are still there.
+     */
+    end(controls) {
+        if (this.prevTwoFingerAction !== undefined)
+            controls?.dispatchEvent({ type: 'controlend' });
+        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.
+ */
+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.
+ */
+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);
+}
+/** 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,30 @@
+/** 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;
+//# sourceMappingURL=Roll.d.ts.map

package/dist/controls/handlers/Roll.js

@@ -0,0 +1,196 @@
+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 { CameraControlsAction } from '../CameraControls';
+import { canvasPoint, useGesture } from '../gestures';
+import { useCameraControls, useControlsEffect } from '../hooks';
+/**
+ * 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 |= CameraControlsAction.ROTATE_AZIMUTH;
+        return () => {
+            controls.mouseButtons.right &= ~CameraControlsAction.ROTATE_AZIMUTH;
+            // Unmounting mid-twist would otherwise leave a `controlstart` without its `controlend`.
+            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 onRotateStart = (event) => gesture.start(event);
+    const onRotate = (event) => {
+        if (controls)
+            gesture.move(event, threshold, { controls, camera: get().camera, space });
+    };
+    const onRotateEnd = () => gesture.end(controls);
+    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.
+ */
+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;
+            // Bracketed from the moment the plan starts turning, not from the touch: a twist still inside
+            // its threshold has not moved the camera, and may yet turn out to be a pinch.
+            controls.dispatchEvent({ type: 'controlstart' });
+        }
+        // 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);
+        // The twist moves the camera through the public setters, which the controls count as a command
+        // rather than the user's hand; reporting it is what tells an idle timer the user is here.
+        controls.dispatchEvent({ type: 'control' });
+    }
+    /**
+     * Forgets the gesture, so the next twist measures its threshold afresh, and closes the
+     * `controlstart` the twist opened, if it got far enough to open one.
+     * @param controls - The controls to report to, if they are still there.
+     */
+    end(controls) {
+        if (this.isRolling)
+            controls?.dispatchEvent({ type: 'controlend' });
+        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.
+ */
+function rollThresholdDegrees(minDiameter, threshold) {
+    return (threshold / (Math.PI * minDiameter)) * 360;
+}
+/** 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;