@expofp/renderer 3.36.0 → 3.37.1

package/dist/controls/CameraControls.js

@@ -60,7 +60,7 @@ export function CameraControls(props) {
         setControls((controls) => Object.assign(controls, { camera: explCamera }));
     }
     useFrame((_state, delta) => {
-        const updated = controls.update(delta);
+        const updated = controls.update(Math.min(delta, MAX_FRAME_DELTA));
         if (updated || gl.info.render.frame == 0) {
             const position = explCamera.position.toArray().map((value) => +value.toFixed(2));
             const target = controls
@@ -190,5 +190,14 @@ function createControls(camera) {
  * tolerates next to a component, and this one never changes.
  */
 export const CameraControlsAction = CameraControlsImpl.ACTION;
+/**
+ * The longest step, in seconds, one frame may advance the controls' easing by.
+ *
+ * Under a demand frameloop the first frame after an idle spell carries the whole spell as its
+ * delta, and camera-controls does not clamp it: a move started by that frame would reach its
+ * target in one step. A ceiling rather than a fixed step, so a device drawing at 30 fps still
+ * eases in real time and only the idle gap is cut short.
+ */
+const MAX_FRAME_DELTA = 1 / 30;
 const _target = new Vector3();
 const _spherical = new Spherical();

package/dist/controls/hooks.d.ts

@@ -37,17 +37,43 @@ export declare function useCameraControls(): CameraControlsImpl | undefined;
  */
 export declare function useControlsEffect(effect: (controls: CameraControlsImpl) => (() => void) | void): void;
 /**
- * Runs a handler when a camera movement begins — a gesture and a command alike, one call per
- * movement rather than one per frame. The event the imperative renderer published as
- * `navigation:change`, under a name that says what happened.
- *
- * A camera-level event rather than the controls themselves, so a caller resetting an idle timer or
- * dismissing an overlay never learns which library drives the camera. For as long as the component
- * is mounted; where the camera *is* once it settles is `useCameraState`'s business.
- * @param handler - Called as each movement starts. Re-subscribed when its identity changes, so pass
- *   a stable function — under the React Compiler an inline closure over stable values is one.
+ * Runs a handler once the camera has come to rest after moving — one call per movement rather than
+ * one per frame, whether a gesture or a command drove it. The event the imperative renderer
+ * published as `navigation:change`, under a name that says what happened.
+ *
+ * At rest and not at the start, so a caller that reads the camera back reads where the movement
+ * actually ended: the framing a kiosk saves, or the rect an overlay measures itself against. Every
+ * movement is reported because the one that moved the camera is not always the one that cares — the
+ * zoom buttons reach the camera through the store, and the screen recording the framing never sees
+ * that command.
+ *
+ * `sleep` rather than `rest`, which the library recommends for "the camera has stopped": `rest` is
+ * dispatched from the damping tail, and a pan here has none to dispatch from ({@link Controls}
+ * zeroes the control smoothing for truck and rotate), so a drag can finish without ever resting.
+ * `sleep` is dispatched for every movement, a jump included.
+ *
+ * A camera-level event rather than the controls themselves, so a caller recording where the plan was
+ * left never learns which library drives the camera. For as long as the component is mounted; where
+ * the camera *is* once it settles is `useCameraState`'s business.
+ * @param handler - Called once each movement has come to rest. Re-subscribed when its identity
+ *   changes, so pass a stable function — under the React Compiler an inline closure over stable
+ *   values is one.
+ */
+export declare function useCameraMoveEnd(handler: () => void): void;
+/**
+ * Runs a handler while the user is moving the camera by hand — a drag, a pinch and a wheel tick
+ * alike, as each one reaches the camera.
+ *
+ * The user's own movement and nothing else, which is what an idle timer wants: a kiosk that treated
+ * a command as activity would have the idle reset's own camera restore re-arm the timer it had just
+ * fired, and would never return home. Deliberately not bracketed by the gesture's start and end —
+ * the controls report neither for the wheel, since scrolling arrives in intermittent ticks with no
+ * way to tell a last one from a pause.
+ * @param handler - Called as each movement of the user's reaches the camera, which may be once per
+ *   frame for as long as a drag lasts. Re-subscribed when its identity changes, so pass a stable
+ *   function — under the React Compiler an inline closure over stable values is one.
  */
-export declare function useCameraMoveStart(handler: () => void): void;
+export declare function useCameraGesture(handler: () => void): void;
 /** Where the camera is, at the moment it was asked. */
 export interface CameraState {
     /** The point on the plan it is looking at, in plan units. */

package/dist/controls/hooks.js

@@ -56,20 +56,51 @@ export function useControlsEffect(effect) {
     }, [effect, get, mounted]);
 }
 /**
- * Runs a handler when a camera movement begins — a gesture and a command alike, one call per
- * movement rather than one per frame. The event the imperative renderer published as
- * `navigation:change`, under a name that says what happened.
- *
- * A camera-level event rather than the controls themselves, so a caller resetting an idle timer or
- * dismissing an overlay never learns which library drives the camera. For as long as the component
- * is mounted; where the camera *is* once it settles is `useCameraState`'s business.
- * @param handler - Called as each movement starts. Re-subscribed when its identity changes, so pass
- *   a stable function — under the React Compiler an inline closure over stable values is one.
+ * Runs a handler once the camera has come to rest after moving — one call per movement rather than
+ * one per frame, whether a gesture or a command drove it. The event the imperative renderer
+ * published as `navigation:change`, under a name that says what happened.
+ *
+ * At rest and not at the start, so a caller that reads the camera back reads where the movement
+ * actually ended: the framing a kiosk saves, or the rect an overlay measures itself against. Every
+ * movement is reported because the one that moved the camera is not always the one that cares — the
+ * zoom buttons reach the camera through the store, and the screen recording the framing never sees
+ * that command.
+ *
+ * `sleep` rather than `rest`, which the library recommends for "the camera has stopped": `rest` is
+ * dispatched from the damping tail, and a pan here has none to dispatch from ({@link Controls}
+ * zeroes the control smoothing for truck and rotate), so a drag can finish without ever resting.
+ * `sleep` is dispatched for every movement, a jump included.
+ *
+ * A camera-level event rather than the controls themselves, so a caller recording where the plan was
+ * left never learns which library drives the camera. For as long as the component is mounted; where
+ * the camera *is* once it settles is `useCameraState`'s business.
+ * @param handler - Called once each movement has come to rest. Re-subscribed when its identity
+ *   changes, so pass a stable function — under the React Compiler an inline closure over stable
+ *   values is one.
+ */
+export function useCameraMoveEnd(handler) {
+    useControlsEffect((controls) => {
+        controls.addEventListener('sleep', handler);
+        return () => controls.removeEventListener('sleep', handler);
+    });
+}
+/**
+ * Runs a handler while the user is moving the camera by hand — a drag, a pinch and a wheel tick
+ * alike, as each one reaches the camera.
+ *
+ * The user's own movement and nothing else, which is what an idle timer wants: a kiosk that treated
+ * a command as activity would have the idle reset's own camera restore re-arm the timer it had just
+ * fired, and would never return home. Deliberately not bracketed by the gesture's start and end —
+ * the controls report neither for the wheel, since scrolling arrives in intermittent ticks with no
+ * way to tell a last one from a pause.
+ * @param handler - Called as each movement of the user's reaches the camera, which may be once per
+ *   frame for as long as a drag lasts. Re-subscribed when its identity changes, so pass a stable
+ *   function — under the React Compiler an inline closure over stable values is one.
  */
-export function useCameraMoveStart(handler) {
+export function useCameraGesture(handler) {
     useControlsEffect((controls) => {
-        controls.addEventListener('transitionstart', handler);
-        return () => controls.removeEventListener('transitionstart', handler);
+        controls.addEventListener('control', handler);
+        return () => controls.removeEventListener('control', handler);
     });
 }
 /**

package/dist/controls/index.d.ts

@@ -4,5 +4,5 @@ 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 CameraState, useCameraAPI, useCameraControls, useCameraMoveStart, useCameraState, useControlsEffect, } from './hooks';
+export { type CameraState, useCameraAPI, useCameraControls, useCameraGesture, useCameraMoveEnd, useCameraState, useControlsEffect, } from './hooks';
 //# sourceMappingURL=index.d.ts.map

package/dist/controls/index.js

@@ -4,4 +4,4 @@
 export { bearing, CameraCommands, } from './camera-api';
 export { CameraControls, CameraControlsAction } from './CameraControls';
 export { Controls } from './Controls';
-export { useCameraAPI, useCameraControls, useCameraMoveStart, useCameraState, useControlsEffect, } from './hooks';
+export { useCameraAPI, useCameraControls, useCameraGesture, useCameraMoveEnd, useCameraState, useControlsEffect, } from './hooks';

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, useCameraMoveStart, 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 ZoomToOptions, } from './controls';
 export { prepareDebug } from './debug/debug-chunk';
 export { useDebugPanel } from './debug/debug-context';
 export { type LightingProps, type ShadowProps } from './objects/lighting';

package/dist/index.js

@@ -1,7 +1,7 @@
-// The camera's public surface: commands, a state reader, and the movement event. Deliberately not
-// `useControlsEffect` or the controls themselves — those hand out `camera-controls`, which is this
-// renderer's internals.
-export { useCameraAPI, useCameraMoveStart, useCameraState, } from './controls';
+// The camera's public surface: commands, a state reader, and the two movement events — the user's
+// own hand on the camera, and any movement coming to rest. Deliberately not `useControlsEffect` or
+// the controls themselves — those hand out `camera-controls`, which is this renderer's internals.
+export { useCameraAPI, useCameraGesture, useCameraMoveEnd, useCameraState, } from './controls';
 // The debug chunk's preload, for an external host that must create its context instrumented.
 export { prepareDebug } from './debug/debug-chunk';
 // Publishing a host's own values into the debug panel.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/renderer",
-  "version": "3.36.0",
+  "version": "3.37.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/expofp/efp-app.git",
@@ -42,7 +42,7 @@
     "troika-three-text": "^0.52.5",
     "tslib": "^2.3.0",
     "webgl-memory": "^1.1.3",
-    "@expofp/geometry": "3.36.0"
+    "@expofp/geometry": "3.37.1"
   },
   "devDependencies": {
     "@react-three/test-renderer": "^9.1.0",