@expofp/renderer 3.31.3 → 3.31.4

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

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

package/dist/controls/handlers/Roll.js

@@ -3,8 +3,9 @@ import { useThree } from '@react-three/fiber';
 import { useState } from 'react';
 import { Matrix4, Vector2, Vector3 } from 'three';
 import { useSpace } from '../../space/Space';
-import { CameraControlsImpl, useCameraControls, useControlsEffect } from '../CameraControls';
+import { CameraControlsAction } from '../CameraControls';
 import { canvasPoint, useGesture } from '../gestures';
+import { useCameraControls, useControlsEffect } from '../hooks';
 /**
  * Rolling: a right-drag, and a two-finger twist.
  *
@@ -30,9 +31,9 @@ export function Roll(props) {
     const space = useSpace();
     const [gesture] = useState(() => new RollGesture());
     useControlsEffect((controls) => {
-        controls.mouseButtons.right |= ACTION.ROTATE_AZIMUTH;
+        controls.mouseButtons.right |= CameraControlsAction.ROTATE_AZIMUTH;
         return () => {
-            controls.mouseButtons.right &= ~ACTION.ROTATE_AZIMUTH;
+            controls.mouseButtons.right &= ~CameraControlsAction.ROTATE_AZIMUTH;
         };
     });
     // Each of these is cached by the React Compiler against what it captures, so `useGesture`
@@ -56,7 +57,7 @@ export function Roll(props) {
  * how far they have turned, where the pivot lands — is worth testing without a canvas around it.
  * {@link Roll} is the React half: when to subscribe, and what the scene currently holds.
  */
-export class RollGesture {
+class RollGesture {
     isRolling = false;
     startVector;
     minDiameter = 0;
@@ -172,10 +173,9 @@ export class RollGesture {
  * @param threshold - The distance along the circumference, in pixels.
  * @returns The angle in degrees; infinite while the fingers are together, so nothing turns.
  */
-export function rollThresholdDegrees(minDiameter, threshold) {
+function rollThresholdDegrees(minDiameter, threshold) {
     return (threshold / (Math.PI * minDiameter)) * 360;
 }
-const ACTION = CameraControlsImpl.ACTION;
 /** The smallest turn worth applying, in radians — below this the twist is recognizer noise. */
 const MIN_ROLL_STEP = 0.001;
 /** How far a two-finger twist must travel before it turns the plan, in pixels of circumference. */

package/dist/controls/handlers/Zoom.js

@@ -1,4 +1,5 @@
-import { CameraControlsImpl, useControlsEffect } from '../CameraControls';
+import { CameraControlsAction } from '../CameraControls';
+import { useControlsEffect } from '../hooks';
 /**
  * Zooming: the wheel, and a two-finger pinch.
  *
@@ -14,13 +15,12 @@ import { CameraControlsImpl, useControlsEffect } from '../CameraControls';
  */
 export function Zoom() {
     useControlsEffect((controls) => {
-        controls.mouseButtons.wheel = ACTION.DOLLY;
-        controls.touches.two = ACTION.TOUCH_DOLLY_SCREEN_PAN;
+        controls.mouseButtons.wheel = CameraControlsAction.DOLLY;
+        controls.touches.two = CameraControlsAction.TOUCH_DOLLY_SCREEN_PAN;
         return () => {
-            controls.mouseButtons.wheel = ACTION.NONE;
-            controls.touches.two = ACTION.NONE;
+            controls.mouseButtons.wheel = CameraControlsAction.NONE;
+            controls.touches.two = CameraControlsAction.NONE;
         };
     });
     return null;
 }
-const ACTION = CameraControlsImpl.ACTION;

package/dist/controls/hooks.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Every hook a component reaches the camera through, and the state they read.
+ *
+ * Beside `CameraControls.tsx` rather than in it, because Fast Refresh swaps a module in place only
+ * when every value it exports is a component. A hook exported next to one sends that module, and
+ * everything importing it, through a full page reload instead.
+ *
+ * The dependency runs one way, from here into `camera-api.ts`. That file holds the commands and the
+ * arithmetic behind them and imports nothing back, which is what lets `useCameraAPI` sit here with
+ * the rest.
+ */
+import { Point } from '@expofp/geometry';
+import { type CameraAPI } from './camera-api';
+import { type CameraControlsImpl } from './CameraControls';
+/**
+ * The scene's camera controls, once {@link Controls} has mounted them.
+ *
+ * For **reading** them, and for handing them to something else that does the writing — a gesture
+ * class, a measurement, a helper taking them as an argument. What the React Compiler rejects is
+ * assigning to a *field* of a hook's return value, which is a build error rather than a bug; a
+ * method call on it, or passing it along, is fine. A component with a write it cannot route through
+ * a function uses {@link useControlsEffect}, which hands the controls over as an argument.
+ * @returns The controls, or `undefined` until they mount.
+ */
+export declare function useCameraControls(): CameraControlsImpl | undefined;
+/**
+ * Runs an effect against the scene's camera controls, for as long as the component is mounted.
+ *
+ * The controls arrive as an argument rather than from a hook, which is what lets the effect write to
+ * them; and the "wait for them to mount" subscription lives here rather than in every caller, so a
+ * component that claims a mouse action is three lines and says only what it claims. Together with
+ * {@link useCameraControls} that is the whole surface — read them, or write to them in an effect.
+ *
+ * Re-runs when the controls change and whenever `effect` does, which — the React Compiler caching
+ * the closure against what it captures — is whenever the component's own inputs move.
+ * @param effect - What to do with the controls; may return a cleanup, as any effect may.
+ */
+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.
+ */
+export declare function useCameraMoveStart(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. */
+    center: Point;
+    /** How far in it is zoomed, as a factor: `1` frames the whole viewbox. */
+    zoom: number;
+    /** Which way the plan is turned, in degrees clockwise from north, in `[0, 360)`. */
+    roll: number;
+    /** How far the plan is tilted away from face-on, in degrees. */
+    pitch: number;
+    /**
+     * How much of the plan one device pixel spans, in plan units — the factor anything sized in
+     * pixels is laid out against, and the quantity the imperative renderer published as `ptScale`.
+     */
+    pixelSize: number;
+}
+/**
+ * Reads where the camera is.
+ *
+ * A **getter**, not a value: nothing here belongs in render output — a component that re-rendered
+ * whenever the camera moved would re-render on every frame of every pan — and every caller wants it
+ * at a moment of its own choosing, in an event handler, an effect, or a snapshot a host asked for.
+ * That is the same reading discipline `Space` documents, for the same reason.
+ *
+ * The five numbers come from four different places, which is why this exists at all rather than
+ * being arithmetic a caller could do: the target from the controls and the plan it lands on from the
+ * space, the zoom factor from the camera's handle, and the pixel size from the re-layout registry —
+ * which is what the plan's own labels are sized against, so a caller measuring against anything else
+ * would disagree with what is drawn.
+ *
+ * Outside a mounted scene, or in the frames before the controls publish themselves, it reports the
+ * camera at rest: the middle of the plan, framed whole, facing north.
+ *
+ * As with {@link useCameraAPI}, the reader is **new on every render** and this module memoizes
+ * nothing; a consumer that needs a settled identity holds it in a ref.
+ * @returns A function that reads the current state.
+ */
+export declare function useCameraState(): () => CameraState;
+/**
+ * The scene's camera commands.
+ *
+ * A hook rather than a ref handed out from above, and that is the point: it only resolves inside a
+ * component mounted under `<Renderer>`, and R3F mounts those only once the canvas and its context
+ * exist — so "the camera cannot be driven before the scene is ready" is enforced by where the code
+ * can live rather than by a null check every caller has to remember. A host that needs to drive the
+ * camera from outside React publishes this object from an effect, which is exactly when it is safe.
+ *
+ * Before the controls mount every command is a no-op that resolves at once, which is the same frame
+ * or two the hook's own consumers spend waiting for their effects.
+ *
+ * **The returned object is new on every render, deliberately.** This module is not memoized by hand
+ * — the React Compiler is scoped to `.tsx` under `src/` (see `vitest.config.mts`), and reaching for
+ * `useMemo` here would put a cache in the library that every consumer then has to trust. A consumer
+ * that cannot re-subscribe cheaply should hold this in a ref rather than in a dependency list; that
+ * way the decision, and its cost, sit with the code that knows how often it renders.
+ * @returns The commands.
+ */
+export declare function useCameraAPI(): CameraAPI;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/controls/hooks.js

@@ -0,0 +1,167 @@
+/**
+ * Every hook a component reaches the camera through, and the state they read.
+ *
+ * Beside `CameraControls.tsx` rather than in it, because Fast Refresh swaps a module in place only
+ * when every value it exports is a component. A hook exported next to one sends that module, and
+ * everything importing it, through a full page reload instead.
+ *
+ * The dependency runs one way, from here into `camera-api.ts`. That file holds the commands and the
+ * arithmetic behind them and imports nothing back, which is what lets `useCameraAPI` sit here with
+ * the rest.
+ */
+import { Point, radToDeg } from '@expofp/geometry';
+import { useThree } from '@react-three/fiber';
+import { use, useEffect } from 'react';
+import { Vector3 } from 'three';
+import { LayoutTargetsContext } from '../events/layout-targets';
+import { useCamera } from '../space/camera-handle';
+import { useCanvasSize } from '../space/canvas-size';
+import { useSpace } from '../space/Space';
+import { bearing, CameraCommands } from './camera-api';
+/**
+ * The scene's camera controls, once {@link Controls} has mounted them.
+ *
+ * For **reading** them, and for handing them to something else that does the writing — a gesture
+ * class, a measurement, a helper taking them as an argument. What the React Compiler rejects is
+ * assigning to a *field* of a hook's return value, which is a build error rather than a bug; a
+ * method call on it, or passing it along, is fine. A component with a write it cannot route through
+ * a function uses {@link useControlsEffect}, which hands the controls over as an argument.
+ * @returns The controls, or `undefined` until they mount.
+ */
+export function useCameraControls() {
+    return useThree((state) => state.controls) ?? undefined;
+}
+/**
+ * Runs an effect against the scene's camera controls, for as long as the component is mounted.
+ *
+ * The controls arrive as an argument rather than from a hook, which is what lets the effect write to
+ * them; and the "wait for them to mount" subscription lives here rather than in every caller, so a
+ * component that claims a mouse action is three lines and says only what it claims. Together with
+ * {@link useCameraControls} that is the whole surface — read them, or write to them in an effect.
+ *
+ * Re-runs when the controls change and whenever `effect` does, which — the React Compiler caching
+ * the closure against what it captures — is whenever the component's own inputs move.
+ * @param effect - What to do with the controls; may return a cleanup, as any effect may.
+ */
+export function useControlsEffect(effect) {
+    const get = useThree((state) => state.get);
+    // A subscription, so this re-runs once the controls have mounted. Deliberately not the value the
+    // effect uses: that is read fresh from the store below.
+    const mounted = useThree((state) => state.controls);
+    useEffect(() => {
+        const controls = get().controls;
+        if (!controls)
+            return undefined;
+        return effect(controls) ?? undefined;
+    }, [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.
+ */
+export function useCameraMoveStart(handler) {
+    useControlsEffect((controls) => {
+        controls.addEventListener('transitionstart', handler);
+        return () => controls.removeEventListener('transitionstart', handler);
+    });
+}
+/**
+ * Reads where the camera is.
+ *
+ * A **getter**, not a value: nothing here belongs in render output — a component that re-rendered
+ * whenever the camera moved would re-render on every frame of every pan — and every caller wants it
+ * at a moment of its own choosing, in an event handler, an effect, or a snapshot a host asked for.
+ * That is the same reading discipline `Space` documents, for the same reason.
+ *
+ * The five numbers come from four different places, which is why this exists at all rather than
+ * being arithmetic a caller could do: the target from the controls and the plan it lands on from the
+ * space, the zoom factor from the camera's handle, and the pixel size from the re-layout registry —
+ * which is what the plan's own labels are sized against, so a caller measuring against anything else
+ * would disagree with what is drawn.
+ *
+ * Outside a mounted scene, or in the frames before the controls publish themselves, it reports the
+ * camera at rest: the middle of the plan, framed whole, facing north.
+ *
+ * As with {@link useCameraAPI}, the reader is **new on every render** and this module memoizes
+ * nothing; a consumer that needs a settled identity holds it in a ref.
+ * @returns A function that reads the current state.
+ */
+export function useCameraState() {
+    const controls = useCameraControls();
+    const camera = useCamera();
+    const space = useSpace();
+    const targets = use(LayoutTargetsContext);
+    return () => readCameraState({ controls, camera, space, targets });
+}
+/**
+ * Reads the camera, from whatever the scene holds at the moment of asking.
+ * @param context - What the scene holds.
+ * @returns Where the camera is.
+ */
+function readCameraState(context) {
+    const { controls, camera, space, targets } = context;
+    const pixelSize = targets?.pixelSize ?? 1;
+    // A fresh centre every time: a caller that keeps the point it was handed must never find it
+    // moved under them.
+    if (!controls)
+        return { ...atRest(), pixelSize };
+    controls.getTarget(_target);
+    return {
+        center: space.worldToPlan(_target, new Point()),
+        zoom: camera?.zoomFactor ?? 1,
+        roll: radToDeg(bearing(controls)),
+        pitch: radToDeg(controls.polarAngle),
+        pixelSize,
+    };
+}
+/**
+ * The camera as it stands before anything has moved it, which is what a read outside a mounted
+ * scene reports: the middle of the plan, framed whole, facing north.
+ * @returns The state.
+ */
+function atRest() {
+    return { center: new Point(), zoom: 1, roll: 0, pitch: 0, pixelSize: 1 };
+}
+const _target = new Vector3();
+/**
+ * The scene's camera commands.
+ *
+ * A hook rather than a ref handed out from above, and that is the point: it only resolves inside a
+ * component mounted under `<Renderer>`, and R3F mounts those only once the canvas and its context
+ * exist — so "the camera cannot be driven before the scene is ready" is enforced by where the code
+ * can live rather than by a null check every caller has to remember. A host that needs to drive the
+ * camera from outside React publishes this object from an effect, which is exactly when it is safe.
+ *
+ * Before the controls mount every command is a no-op that resolves at once, which is the same frame
+ * or two the hook's own consumers spend waiting for their effects.
+ *
+ * **The returned object is new on every render, deliberately.** This module is not memoized by hand
+ * — the React Compiler is scoped to `.tsx` under `src/` (see `vitest.config.mts`), and reaching for
+ * `useMemo` here would put a cache in the library that every consumer then has to trust. A consumer
+ * that cannot re-subscribe cheaply should hold this in a ref rather than in a dependency list; that
+ * way the decision, and its cost, sit with the code that knows how often it renders.
+ * @returns The commands.
+ */
+export function useCameraAPI() {
+    const get = useThree((state) => state.get);
+    const controls = useCameraControls();
+    const camera = useCamera();
+    const space = useSpace();
+    const { width, height, dpr } = useCanvasSize();
+    return new CameraCommands({
+        controls,
+        camera,
+        space,
+        view: () => get().camera.view,
+        width,
+        height,
+        dpr,
+    });
+}

package/dist/controls/index.d.ts

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

package/dist/controls/index.js

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

package/dist/debug/debug-chunk.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one debug chunk, and the two ways into it.
+ *
+ * Beside `index.tsx` rather than in it, because Fast Refresh swaps a module in place only when every
+ * value it exports is a component. `prepareDebug` is this package's public API and cannot stop being
+ * exported, so it moves instead.
+ */
+/**
+ * Imports the debug chunk, memoized so `use()` sees a stable promise and it is fetched once.
+ *
+ * Shared by every consumer: the internal mount's context-patch gate, the overlay in both mounts'
+ * trees, and {@link prepareDebug}.
+ * @returns The import promise, the same one each call.
+ */
+export declare function loadDebugChunk(): Promise<unknown>;
+/**
+ * Loads the debug chunk ahead of time — for a host that creates its own WebGL context.
+ *
+ * The chunk's evaluation is what instruments context creation for the GPU-memory panel
+ * (webgl-memory patches `getContext` as it loads), so a context created before it exists can never
+ * report memory figures. The renderer's own mount orders this itself; a MapLibre host does it by
+ * awaiting this before constructing the map, when debug is on. Idempotent, and the only eager cost
+ * is the call: the debug code still lives in its own lazy chunk.
+ */
+export declare function prepareDebug(): Promise<void>;
+//# sourceMappingURL=debug-chunk.d.ts.map

package/dist/debug/debug-chunk.js

@@ -0,0 +1,32 @@
+/**
+ * The one debug chunk, and the two ways into it.
+ *
+ * Beside `index.tsx` rather than in it, because Fast Refresh swaps a module in place only when every
+ * value it exports is a component. `prepareDebug` is this package's public API and cannot stop being
+ * exported, so it moves instead.
+ */
+/**
+ * Imports the debug chunk, memoized so `use()` sees a stable promise and it is fetched once.
+ *
+ * Shared by every consumer: the internal mount's context-patch gate, the overlay in both mounts'
+ * trees, and {@link prepareDebug}.
+ * @returns The import promise, the same one each call.
+ */
+export function loadDebugChunk() {
+    debugChunk ??= import('./components/DebugTools');
+    return debugChunk;
+}
+/**
+ * Loads the debug chunk ahead of time — for a host that creates its own WebGL context.
+ *
+ * The chunk's evaluation is what instruments context creation for the GPU-memory panel
+ * (webgl-memory patches `getContext` as it loads), so a context created before it exists can never
+ * report memory figures. The renderer's own mount orders this itself; a MapLibre host does it by
+ * awaiting this before constructing the map, when debug is on. Idempotent, and the only eager cost
+ * is the call: the debug code still lives in its own lazy chunk.
+ */
+export async function prepareDebug() {
+    await loadDebugChunk();
+}
+/** The memoized import, set by the first {@link loadDebugChunk} call. */
+let debugChunk;

package/dist/debug/index.d.ts

@@ -1,15 +1,5 @@
 import { type CanvasProps } from '@react-three/fiber';
 import { type ReactNode } from 'react';
-/**
- * Loads the debug chunk ahead of time — for a host that creates its own WebGL context.
- *
- * The chunk's evaluation is what instruments context creation for the GPU-memory panel
- * (webgl-memory patches `getContext` as it loads), so a context created before it exists can never
- * report memory figures. The renderer's own mount orders this itself; a MapLibre host does it by
- * awaiting this before constructing the map, when debug is on. Idempotent, and the only eager cost
- * is the call: the debug code still lives in its own lazy chunk.
- */
-export declare function prepareDebug(): Promise<void>;
 /** Props for {@link CanvasWithDebug}: the Canvas props plus the debug toggle. */
 export interface CanvasWithDebugProps extends CanvasProps {
     /** When falsy, the Canvas mounts untouched and no debug code is loaded. */