@expofp/renderer 3.40.2 → 3.41.0

package/dist/controls/Controls.d.ts

@@ -1,6 +1,7 @@
 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.
  *
@@ -18,8 +19,11 @@ import { type RollConfig } from './handlers/Roll';
 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;
+    /**
+     * 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. */

package/dist/controls/Controls.js

@@ -34,7 +34,7 @@ export function Controls(props) {
         // 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, {})] }));
+    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.

package/dist/controls/gestures.d.ts

@@ -30,9 +30,10 @@ export interface GestureContext {
  * **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.
+ * 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` and `Pitch` want one on the same canvas, and two would
+ * 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

package/dist/controls/gestures.js

@@ -1,5 +1,5 @@
 import { useThree } from '@react-three/fiber';
-import { EventManager, Pan, Rotate } from 'mjolnir.js';
+import { EventManager, Pan, Rotate, Tap } from 'mjolnir.js';
 import { useEffect } from 'react';
 /**
  * Subscribes to one of the canvas's gestures for as long as the component is mounted.
@@ -7,9 +7,10 @@ import { useEffect } from 'react';
  * **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.
+ * 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` and `Pitch` want one on the same canvas, and two would
+ * 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
@@ -46,7 +47,15 @@ export function acquireGestureManager(element) {
         return held.manager;
     }
     const manager = new EventManager(element, {
-        recognizers: [Rotate, [Pan, { event: 'pitch', pointers: 2 }, 'rotate']],
+        recognizers: [
+            Rotate,
+            [Pan, { event: 'pitch', pointers: 2 }, 'rotate'],
+            // A mouse's pointer events feed the recognizer as a finger's do, so one double tap is both
+            // the double-click and the double-tap. MapLibre's tap tolerances rather than the
+            // recognizer's own: a finger's second tap rarely lands within 10px of its first, and with
+            // the default `posThreshold` a real double tap on a phone was never recognized.
+            [Tap, { event: 'doubletap', taps: 2, interval: 500, time: 500, posThreshold: 30 }],
+        ],
     });
     managers.set(element, { manager, refs: 1 });
     return manager;

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

@@ -0,0 +1,23 @@
+/** Props for {@link DoubleTapZoom}. */
+export interface DoubleTapZoomProps {
+    /** What a double tap multiplies the zoom factor by. */
+    factor: number;
+}
+/**
+ * A double-click or double-tap: zooms by `factor` about the point under the pointer, which keeps
+ * its place on the canvas throughout.
+ *
+ * Mounted by `Zoom`, and only when a double-click is meant to zoom. One double tap is both the
+ * double-click and the double-tap: the gesture recognizer reads a mouse's pointer events as it
+ * reads a finger's.
+ *
+ * Run as a user transition, so it eases the way a wheel tick does — by `controlSmoothTime`, with the
+ * target on the dolly's clock — and reports itself as the user's hand.
+ *
+ * A component of its own rather than a branch inside `Zoom`, because subscribing is a hook and a
+ * hook cannot be switched off conditionally — mounting this is what switches it on.
+ * @param props - The zoom factor to multiply by.
+ * @returns Nothing; this renders no scene node.
+ */
+export declare function DoubleTapZoom(props: DoubleTapZoomProps): null;
+//# sourceMappingURL=DoubleTapZoom.d.ts.map

package/dist/controls/handlers/DoubleTapZoom.js

@@ -0,0 +1,82 @@
+import { useThree } from '@react-three/fiber';
+import { Spherical, Vector3 } from 'three';
+import { useSpace, } from '../../space/Space';
+import { clamp } from '../../utils/math';
+import { useGesture } from '../gestures';
+import { useCameraControls } from '../hooks';
+/**
+ * A double-click or double-tap: zooms by `factor` about the point under the pointer, which keeps
+ * its place on the canvas throughout.
+ *
+ * Mounted by `Zoom`, and only when a double-click is meant to zoom. One double tap is both the
+ * double-click and the double-tap: the gesture recognizer reads a mouse's pointer events as it
+ * reads a finger's.
+ *
+ * Run as a user transition, so it eases the way a wheel tick does — by `controlSmoothTime`, with the
+ * target on the dolly's clock — and reports itself as the user's hand.
+ *
+ * A component of its own rather than a branch inside `Zoom`, because subscribing is a hook and a
+ * hook cannot be switched off conditionally — mounting this is what switches it on.
+ * @param props - The zoom factor to multiply by.
+ * @returns Nothing; this renders no scene node.
+ */
+export function DoubleTapZoom(props) {
+    const { factor } = props;
+    const get = useThree((state) => state.get);
+    const invalidate = useThree((state) => state.invalidate);
+    const space = useSpace();
+    // Read, not written: `userTransition` takes the move as a callback, which does the writing.
+    const controls = useCameraControls();
+    const onDoubleTap = (event) => {
+        if (!controls)
+            return;
+        // mjolnir measures the tap from the target's own padding edge, as `canvasPoint` does.
+        const around = space.canvasToPlan(event.offsetCenter, get().camera);
+        if (!around)
+            return;
+        void controls.userTransition(() => zoomAbout(controls, space, factor, around));
+        // The move happens outside a React commit, so a demand frame loop has to be asked for a frame.
+        invalidate();
+    };
+    useGesture('doubletap', onDoubleTap);
+    return null;
+}
+/**
+ * Zooms by a factor about a point on the plan, which keeps its place on the canvas.
+ *
+ * Scaling the whole camera about the point, orientation untouched, is what leaves the point where
+ * it was: the target slides toward it in the proportion the distance shrinks. Exact under a visible
+ * rect too, whose offset rides in the projection this leaves alone. It holds **during** the ease
+ * only inside a user transition, which puts the target on the dolly's clock.
+ *
+ * **Scaled from where the camera is now, sized from where it is heading.** A double tap often lands
+ * while the last one is still easing. The point under the finger is found through the camera as it
+ * is drawn, so it is the camera's current stance that has to be scaled about it — that keeps the
+ * point under the finger from here on. The zoom is sized from the distance the camera is heading
+ * to, so a second double tap zooms a full step past the first rather than a step past wherever the
+ * first had got to, as successive wheel notches do. The clamped distance sets the proportion, so a
+ * zoom stopped short by the camera's limits does not slide the target as far as the one asked for.
+ * @param controls - The controls to move.
+ * @param space - The scene's space.
+ * @param factor - What to multiply the zoom factor by.
+ * @param around - The point to zoom about, in plan units.
+ * @returns When the move has settled.
+ */
+function zoomAbout(controls, space, factor, around) {
+    const from = controls.distance;
+    // The zoom factor is inversely proportional to the distance.
+    const to = clamp(controls.getSpherical(_spherical, true).radius / factor, controls.minDistance, controls.maxDistance);
+    const pivot = space.planToWorld(around, _pivot);
+    const target = controls
+        .getTarget(_target, false)
+        .sub(pivot)
+        .multiplyScalar(to / from)
+        .add(pivot);
+    return Promise.all([
+        controls.moveTo(target.x, target.y, target.z, true),
+        controls.dollyTo(to, true),
+    ]);
+}
+const _pivot = new Vector3();
+const _target = new Vector3();
+const _spherical = new Spherical();

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

@@ -1,21 +1,21 @@
 /**
- * How the glide a pan leaves behind is measured, and how it slows.
+ * How the glide a motion leaves behind is measured, and how it slows.
  *
- * The speed is taken from where the camera's target actually traveled over the last stretch of the
- * drag, so these are all expressed against that: world units and milliseconds.
+ * The speed is taken from the motion's own samples over the last stretch of the interaction, so
+ * the threshold is in the motion's units per millisecond: css pixels for a pan.
  */
 export interface InertiaConfig {
     /**
-     * How far back the drag is sampled to measure its speed, in milliseconds; defaults to `50`. The
-     * oldest sample at least this old is the one differenced against, so a flick that ended in a
-     * stall glides at the stall's speed rather than the flick's.
+     * How far back the interaction is sampled to measure its speed, in milliseconds; defaults to
+     * `50`. The oldest sample at least this old is the one differenced against, so a flick that ended
+     * in a stall glides at the stall's speed rather than the flick's.
      */
     minSampleMs?: number;
     /** How long the glide lasts, in milliseconds; defaults to `1000`. */
     durationMs?: number;
     /**
-     * The speed below which a lifted pointer leaves no glide at all, in world units per millisecond;
-     * defaults to `0.08`.
+     * The speed below which a lifted pointer leaves no glide at all, in the motion's units per
+     * millisecond; defaults to `0.08`, sized for a pan in css pixels.
      */
     speedThreshold?: number;
     /**
@@ -27,19 +27,34 @@ export interface InertiaConfig {
      */
     ease?: (t: number) => number;
 }
+/** Props for {@link Inertia}: the motion it carries on, and how. */
+export interface InertiaProps extends InertiaConfig {
+    /**
+     * How far the motion moved since the last call, or `undefined` when this step of the interaction
+     * was not one of its own. Called on every `control` event the controls report, so it measures the
+     * motion directly rather than inferring it from where the camera went.
+     */
+    sample: () => readonly number[] | undefined;
+    /**
+     * Moves the camera by one step of the glide, in the same units as the samples.
+     * @returns Whether it moved; `false` ends the glide.
+     */
+    apply: (step: readonly number[]) => boolean;
+}
 /**
- * The glide a lifted pointer leaves behind.
+ * The glide a lifted pointer leaves behind, for one kind of motion.
  *
- * Mounted by {@link Pan}, and only when a pan is meant to keep moving. It watches the controls'
- * own interaction events to learn how fast the plan was traveling when the pointer left, then eases
- * that speed away over the following second.
+ * MapLibre's shape: each kind of motion measures itself while the user drives it, and when the
+ * interaction ends it glides on at the speed it ended with — rather than one glide reading the
+ * camera after the fact, where a pan, a pinch's slide toward the fingers and a twist's turn about
+ * them all arrive mixed into the same target. Generic over the motion: the caller says how to
+ * sample it and how to apply a step of it, and this owns the timing.
  *
  * Runs its frame callback **ahead of the controls' own** (see {@link INERTIA_PRIORITY}), so the
- * target it moves is the one that frame draws rather than the next — a frame tighter than the
- * imperative renderer, which updated the controller before its handlers. It asks for the next frame
+ * camera it moves is the one that frame draws rather than the next. It asks for the next frame
  * itself, which is what keeps a glide alive under the on-demand loop.
- * @param props - How the glide is measured and how it slows.
+ * @param props - What the glide carries on, and how it is measured and slows.
  * @returns Nothing; this renders no scene node.
  */
-export declare function Inertia(props: InertiaConfig): null;
+export declare function Inertia(props: InertiaProps): null;
 //# sourceMappingURL=Inertia.d.ts.map

package/dist/controls/handlers/Inertia.js

@@ -1,19 +1,19 @@
 import { useFrame, useThree } from '@react-three/fiber';
 import { useEffect, useState } from 'react';
-import { Vector3 } from 'three';
 import { useControlsEffect } from '../hooks';
 /**
- * The glide a lifted pointer leaves behind.
+ * The glide a lifted pointer leaves behind, for one kind of motion.
  *
- * Mounted by {@link Pan}, and only when a pan is meant to keep moving. It watches the controls'
- * own interaction events to learn how fast the plan was traveling when the pointer left, then eases
- * that speed away over the following second.
+ * MapLibre's shape: each kind of motion measures itself while the user drives it, and when the
+ * interaction ends it glides on at the speed it ended with — rather than one glide reading the
+ * camera after the fact, where a pan, a pinch's slide toward the fingers and a twist's turn about
+ * them all arrive mixed into the same target. Generic over the motion: the caller says how to
+ * sample it and how to apply a step of it, and this owns the timing.
  *
  * Runs its frame callback **ahead of the controls' own** (see {@link INERTIA_PRIORITY}), so the
- * target it moves is the one that frame draws rather than the next — a frame tighter than the
- * imperative renderer, which updated the controller before its handlers. It asks for the next frame
+ * camera it moves is the one that frame draws rather than the next. It asks for the next frame
  * itself, which is what keeps a glide alive under the on-demand loop.
- * @param props - How the glide is measured and how it slows.
+ * @param props - What the glide carries on, and how it is measured and slows.
  * @returns Nothing; this renders no scene node.
  */
 export function Inertia(props) {
@@ -21,13 +21,15 @@ export function Inertia(props) {
     const durationMs = props.durationMs ?? DEFAULT_DURATION_MS;
     const speedThreshold = props.speedThreshold ?? DEFAULT_SPEED_THRESHOLD;
     const ease = props.ease ?? easeInertia;
+    const { sample, apply } = props;
     const invalidate = useThree((state) => state.invalidate);
-    const [inertia] = useState(() => new InertiaController({ minSampleMs, durationMs, speedThreshold, ease }));
-    // Assignments only, so a caller passing an inline `ease` re-syncs four fields and disturbs
-    // nothing else — in particular it never re-subscribes, which is why this is its own effect.
+    const [inertia] = useState(() => new InertiaController({ minSampleMs, durationMs, speedThreshold, ease }, sample, apply));
+    // Assignments only, so a caller passing an inline `ease` or a fresh `sample` re-syncs fields and
+    // disturbs nothing else — in particular it never re-subscribes, which is why this is its own
+    // effect.
     useEffect(() => {
-        inertia.configure({ minSampleMs, durationMs, speedThreshold, ease });
-    }, [inertia, minSampleMs, durationMs, speedThreshold, ease]);
+        inertia.configure({ minSampleMs, durationMs, speedThreshold, ease }, sample, apply);
+    }, [inertia, minSampleMs, durationMs, speedThreshold, ease, sample, apply]);
     useControlsEffect((controls) => {
         inertia.connect(controls);
         return () => inertia.disconnect();
@@ -48,59 +50,65 @@ function easeInertia(t) {
     return Math.pow(2, 10 * (t - 1));
 }
 /**
- * Carries a pan on after the pointer lifts.
+ * Carries a motion on after the pointer lifts.
  *
- * Framework-free on purpose: everything here is arithmetic over the camera's target and a list of
+ * Framework-free on purpose: everything here is arithmetic over a running total and a list of
  * timestamps, which is the half worth testing without a canvas around it. {@link Inertia} is the
  * React half — when to connect, when to configure, when to step.
  *
- * **The speed comes from where the target actually went**, not from the pointer. Every interaction
- * frame records the target; when the pointer lifts, the oldest sample at least `minSampleMs` old is
- * diffed against the current target. A flick that ended in a stall therefore glides at the
- * stall's speed, because the samples covering the stall are the recent ones.
+ * **The speed comes from the motion's own samples.** Each `control` event adds the motion's delta
+ * to a running total and records it; when the pointer lifts, the oldest record at least
+ * `minSampleMs` old is diffed against the total. A flick that ended in a stall therefore glides at
+ * the stall's speed, because the records covering the stall are the recent ones. A step the motion
+ * sat out adds nothing, so an interaction it never took part in glides nowhere.
  */
 class InertiaController {
     minSampleMs;
     durationMs;
     speedThreshold;
     ease;
+    sample;
+    apply;
     controls;
-    samples = [];
-    target = new Vector3();
-    delta = new Vector3();
-    velocity = new Vector3();
+    total = [];
+    records = [];
+    velocity = [];
+    step = [];
     active = false;
     elapsedMs = 0;
     prevFactor = 1;
     /**
-     * Takes every value rather than defaulting any: what an omitted option means is `resolveControls`'s
+     * Takes every value rather than defaulting any: what an omitted option means is {@link Inertia}'s
      * to answer, and answering it twice is how the two drift apart.
      * @param options - How the glide is measured and how it slows.
+     * @param sample - How far the motion moved since the last call.
+     * @param apply - Moves the camera by one step of the glide.
      */
-    constructor(options) {
+    constructor(options, sample, apply) {
         this.minSampleMs = options.minSampleMs;
         this.durationMs = options.durationMs;
         this.speedThreshold = options.speedThreshold;
         this.ease = options.ease;
+        this.sample = sample;
+        this.apply = apply;
     }
     /**
-     * Sets how the glide is measured and how it slows. Every field is optional, so a partial update
-     * leaves the rest as it was.
-     * @param options - The values to change.
+     * Sets the motion, and how the glide is measured and slows.
+     * @param options - How the glide is measured and how it slows.
+     * @param sample - How far the motion moved since the last call.
+     * @param apply - Moves the camera by one step of the glide.
      */
-    configure(options) {
-        if (options.minSampleMs !== undefined)
-            this.minSampleMs = options.minSampleMs;
-        if (options.durationMs !== undefined)
-            this.durationMs = options.durationMs;
-        if (options.speedThreshold !== undefined)
-            this.speedThreshold = options.speedThreshold;
-        if (options.ease !== undefined)
-            this.ease = options.ease;
+    configure(options, sample, apply) {
+        this.minSampleMs = options.minSampleMs;
+        this.durationMs = options.durationMs;
+        this.speedThreshold = options.speedThreshold;
+        this.ease = options.ease;
+        this.sample = sample;
+        this.apply = apply;
     }
     /**
      * Starts watching a controls instance for the interactions a glide follows.
-     * @param controls - The controls to watch and to move.
+     * @param controls - The controls to watch.
      */
     connect(controls) {
         if (this.controls)
@@ -116,7 +124,7 @@ class InertiaController {
         if (!controls)
             return;
         this.active = false;
-        this.samples.length = 0;
+        this.records.length = 0;
         controls.removeEventListener('controlstart', this.onControlStart);
         controls.removeEventListener('control', this.onControl);
         controls.removeEventListener('controlend', this.onControlEnd);
@@ -132,8 +140,7 @@ class InertiaController {
      * @returns Whether the camera moved, and so whether another frame is wanted.
      */
     update(delta) {
-        const controls = this.controls;
-        if (!this.active || !controls)
+        if (!this.active)
             return false;
         const deltaMs = delta * 1000;
         this.elapsedMs += deltaMs;
@@ -141,54 +148,54 @@ class InertiaController {
         const factor = this.ease(1 - t); // 1 -> 0
         const avgFactor = (factor + this.prevFactor) * 0.5;
         this.prevFactor = factor;
-        // The current target rather than the one being eased toward: a glide is a chain of immediate
-        // moves, so the two agree — asking for the end value would compound with any transition the
-        // controls happen to be running.
-        controls.getTarget(this.target, false);
-        this.delta.copy(this.velocity).multiplyScalar(avgFactor * deltaMs);
-        this.target.add(this.delta);
-        // Only the target is moved: camera-controls carries the camera along with it, which is why the
-        // imperative renderer's parallel arithmetic on the camera position was never read back.
-        void controls.moveTo(this.target.x, this.target.y, this.target.z, false);
+        for (let i = 0; i < this.velocity.length; i++) {
+            this.step[i] = this.velocity[i] * avgFactor * deltaMs;
+        }
+        if (!this.apply(this.step)) {
+            this.active = false;
+            return false;
+        }
         if (factor <= REST_FACTOR || t >= 1)
             this.active = false;
         return true;
     }
     onControlStart = () => {
         this.active = false;
-        this.samples.length = 0;
+        this.records.length = 0;
+        this.total.fill(0);
     };
     onControl = () => {
-        const controls = this.controls;
-        if (!controls)
-            return;
+        const delta = this.sample();
         const now = performance.now();
-        controls.getTarget(this.target, false);
-        this.samples.push({ t: now, target: this.target.clone() });
+        if (delta) {
+            for (let i = 0; i < delta.length; i++)
+                this.total[i] = (this.total[i] ?? 0) + delta[i];
+        }
+        this.records.push({ t: now, total: this.total.slice() });
         const cutoff = now - SAMPLE_WINDOW_MS;
-        while (this.samples.length && this.samples[0].t < cutoff)
-            this.samples.shift();
+        while (this.records.length && this.records[0].t < cutoff)
+            this.records.shift();
     };
     onControlEnd = () => {
-        const controls = this.controls;
-        if (!controls)
-            return;
         const now = performance.now();
         const oldest = now - this.minSampleMs;
-        for (let i = this.samples.length - 1; i >= 0; i--) {
-            const sample = this.samples[i];
-            // The first sample old enough to measure against — or the oldest there is, when the whole
-            // drag was shorter than the sampling window.
-            if (sample.t >= oldest && i !== 0)
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const record = this.records[i];
+            // The first record old enough to measure against — or the oldest there is, when the whole
+            // interaction was shorter than the sampling window.
+            if (record.t >= oldest && i !== 0)
                 continue;
-            const dt = now - sample.t;
+            const dt = now - record.t;
             if (dt <= 0)
                 return;
-            controls.getTarget(this.target, false);
-            this.velocity.subVectors(this.target, sample.target).divideScalar(dt);
-            // A pan never changes elevation, and a glide must not introduce one.
-            this.velocity.z = 0;
-            if (this.velocity.length() <= this.speedThreshold)
+            let speedSquared = 0;
+            this.velocity.length = this.total.length;
+            this.step.length = this.total.length;
+            for (let axis = 0; axis < this.total.length; axis++) {
+                this.velocity[axis] = (this.total[axis] - (record.total[axis] ?? 0)) / dt;
+                speedSquared += this.velocity[axis] * this.velocity[axis];
+            }
+            if (Math.sqrt(speedSquared) <= this.speedThreshold)
                 return;
             this.elapsedMs = 0;
             this.prevFactor = 1;
@@ -203,13 +210,13 @@ class InertiaController {
  * Negative on both counts, so neither takes over rendering from R3F — a positive priority would.
  */
 const INERTIA_PRIORITY = -2;
-/** How much of a drag is kept to measure its speed from, in milliseconds. */
+/** How much of an interaction is kept to measure its speed from, in milliseconds. */
 const SAMPLE_WINDOW_MS = 300;
 /** The easing factor below which what is left of a glide is not worth another frame. */
 const REST_FACTOR = 0.02;
-/** How far back a drag is sampled to measure the speed it should glide at, in milliseconds. */
+/** How far back an interaction is sampled to measure the speed it should glide at, in milliseconds. */
 const DEFAULT_SAMPLE_MS = 50;
 /** How long a glide lasts, in milliseconds. */
 const DEFAULT_DURATION_MS = 1000;
-/** The speed below which a lifted pointer leaves no glide, in world units per millisecond. */
+/** The speed below which a lifted pointer leaves no glide, in the motion's units per millisecond. */
 const DEFAULT_SPEED_THRESHOLD = 0.08;

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

@@ -12,7 +12,7 @@ export interface PanConfig {
  * 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 Inertia}, which is the one piece of
+ * 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.

package/dist/controls/handlers/Pan.js

@@ -1,6 +1,12 @@
 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 { useControlsEffect } from '../hooks';
+import { canvasPoint } from '../gestures';
+import { useCameraControls, useControlsEffect } from '../hooks';
 import { Inertia } from './Inertia';
 /**
  * Panning: a left-drag, and a one-finger drag.
@@ -9,7 +15,7 @@ import { Inertia } from './Inertia';
  * 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 Inertia}, which is the one piece of
+ * 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.
@@ -28,5 +34,179 @@ export function Pan(props) {
     });
     if (inertia === false)
         return null;
-    return _jsx(Inertia, { ...(inertia === true ? {} : inertia) });
+    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.js

@@ -98,21 +98,30 @@ class PitchGesture {
         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, and forgets the gesture.
+     * 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, if they are still there.
+     * @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;

package/dist/controls/handlers/Roll.js

@@ -34,6 +34,8 @@ export function Roll(props) {
         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`
@@ -43,7 +45,7 @@ export function Roll(props) {
         if (controls)
             gesture.move(event, threshold, { controls, camera: get().camera, space });
     };
-    const onRotateEnd = () => gesture.end();
+    const onRotateEnd = () => gesture.end(controls);
     useGesture('rotatestart', onRotateStart);
     useGesture('rotate', onRotate);
     useGesture('rotateend', onRotateEnd);
@@ -102,6 +104,9 @@ class RollGesture {
                 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.
@@ -118,9 +123,18 @@ class RollGesture {
         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. */
-    end() {
+    /**
+     * 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;

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

@@ -1,15 +1,28 @@
+import { type ReactNode } from 'react';
+/** Options for the zoom handler, which are also its props. */
+export interface ZoomConfig {
+    /**
+     * What a double-click or a double-tap multiplies the zoom factor by, zooming toward the point
+     * under the pointer and keeping it there. Off when left out.
+     */
+    dblclick?: number;
+}
 /**
- * Zooming: the wheel, and a two-finger pinch.
+ * Zooming: the wheel, a two-finger pinch, and — when asked for — a double-click or double-tap.
  *
- * 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`.
+ * Nothing here beyond the actions for the first two — 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`.
+ *
+ * The double-click is not camera-controls' either, so it comes off the gesture recognizer, which
+ * reads a mouse and a finger alike: see {@link DoubleTapZoom}.
  *
  * 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.
+ * @param props - Whether a double-click zooms, and by how much.
+ * @returns The double-click zoom, when there is one.
  */
-export declare function Zoom(): null;
+export declare function Zoom(props: ZoomConfig): ReactNode;
 //# sourceMappingURL=Zoom.d.ts.map

package/dist/controls/handlers/Zoom.js

@@ -1,19 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { CameraControlsAction } from '../CameraControls';
 import { useControlsEffect } from '../hooks';
+import { DoubleTapZoom } from './DoubleTapZoom';
 /**
- * Zooming: the wheel, and a two-finger pinch.
+ * Zooming: the wheel, a two-finger pinch, and — when asked for — a double-click or double-tap.
  *
- * 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`.
+ * Nothing here beyond the actions for the first two — 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`.
+ *
+ * The double-click is not camera-controls' either, so it comes off the gesture recognizer, which
+ * reads a mouse and a finger alike: see {@link DoubleTapZoom}.
  *
  * 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.
+ * @param props - Whether a double-click zooms, and by how much.
+ * @returns The double-click zoom, when there is one.
  */
-export function Zoom() {
+export function Zoom(props) {
     useControlsEffect((controls) => {
         controls.mouseButtons.wheel = CameraControlsAction.DOLLY;
         controls.touches.two = CameraControlsAction.TOUCH_DOLLY_SCREEN_PAN;
@@ -22,5 +28,7 @@ export function Zoom() {
             controls.touches.two = CameraControlsAction.NONE;
         };
     });
-    return null;
+    if (props.dblclick === undefined)
+        return null;
+    return _jsx(DoubleTapZoom, { factor: props.dblclick });
 }

package/dist/controls/index.d.ts

@@ -4,5 +4,6 @@ export { Controls, type ControlsConfig, type ControlsProps } from './Controls';
 export type { InertiaConfig } from './handlers/Inertia';
 export type { PanConfig } from './handlers/Pan';
 export type { RollConfig } from './handlers/Roll';
+export type { ZoomConfig } from './handlers/Zoom';
 export { type CameraState, useCameraAPI, useCameraControls, useCameraGesture, useCameraMoveEnd, useCameraState, useControlsEffect, } from './hooks';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type CameraAPI, type CameraAxes, type CameraState, type ControlsConfig, type InertiaConfig, type PanConfig, type RollConfig, type TransitionOptions, useCameraAPI, useCameraGesture, useCameraMoveEnd, useCameraState, type ZoomToOptions, } from './controls';
+export { type CameraAPI, type CameraAxes, type CameraState, type ControlsConfig, type InertiaConfig, type PanConfig, type RollConfig, type TransitionOptions, useCameraAPI, useCameraGesture, useCameraMoveEnd, useCameraState, type ZoomConfig, type ZoomToOptions, } from './controls';
 export { prepareDebug } from './debug/debug-chunk';
 export { useDebugPanel } from './debug/debug-context';
 export { type LightingProps, type ShadowProps } from './objects/lighting';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/renderer",
-  "version": "3.40.2",
+  "version": "3.41.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/expofp/efp-app.git",
@@ -32,7 +32,7 @@
   ],
   "dependencies": {
     "@react-three/fiber": "^9.6.1",
-    "camera-controls": "github:expofp/camera-controls#v3.1.3-expofp.5",
+    "camera-controls": "github:expofp/camera-controls#v3.1.3-expofp.7",
     "colord": "^2.9.3",
     "lil-gui": "^0.21.0",
     "maxrects-packer": "^2.7.3",
@@ -42,7 +42,7 @@
     "troika-three-text": "^0.52.5",
     "tslib": "^2.3.0",
     "webgl-memory": "^1.1.3",
-    "@expofp/geometry": "3.40.2"
+    "@expofp/geometry": "3.41.0"
   },
   "devDependencies": {
     "@react-three/test-renderer": "^9.1.0",