@expofp/renderer 3.2.5 → 3.27.1

package/README.md

@@ -0,0 +1,111 @@
+# @expofp/renderer
+
+Interactive floor plan renderer built on [react-three-fiber](https://r3f.docs.pmnd.rs/).
+
+## Architecture
+
+- **`Renderer`** (`src/Renderer.tsx`) — the public entry: mounts the R3F
+  `Canvas` and the scene (`controls/`, `lighting/`, `batch/`). Pass `debug` to
+  enable the debug overlay.
+- **Scene topics** live in their own folders (`batch/`, `controls/`,
+  `lighting/`, …); add new rendering features as sibling topic folders.
+- **`debug/`** — the debug overlay (lil-gui panel + stats-gl overlay), loaded
+  through a single dynamic `import()` in `Renderer`. Everything under `debug/`
+  (and its heavier deps, lil-gui + stats-gl) is code-split into one lazily
+  loaded chunk that is **never fetched when `debug` is off**. Add new debug
+  pieces to `debug/index.tsx` so they ride along in the same chunk.
+
+## Navigation
+
+`RendererProps` carries two different kinds of thing:
+
+- **Camera limits** — `minZoom` / `maxZoom` / `minPitch` / `maxPitch`, declared as
+  `CameraProps` in `src/space/Camera.tsx`. They constrain the camera itself, so
+  they hold for a programmatic move as much as for a dragged one. `Camera` writes
+  them and defaults them, beside the clipping planes derived from the same
+  numbers; `maxPitch` both defaults to and is capped at `MAX_PITCH` (degrees, in
+  `clipping.ts`), the angle every depth calculation in the renderer is sized
+  against.
+- **`controls`** — what a _user_ may do. Each handler takes `false`, `true` or
+  omitted for its defaults, or an options object.
+
+```tsx
+<Renderer
+  scene={scene}
+  minZoom={0.1}
+  maxZoom={100}
+  minPitch={0}
+  maxPitch={85}
+  controls={{
+    pan: { inertia: { durationMs: 600 } },
+    zoom: true,
+    roll: { threshold: 25 },
+    pitch: false,
+  }}
+/>
+```
+
+Pan and zoom default on; **roll and pitch default on only in a development
+build**, so this package's Storybook and dev server have them and a production
+plan does not until a caller asks. An explicit value always wins.
+
+Each handler is a component under `src/controls/handlers/`, mirroring the
+imperative renderer's `ui/handlers/`, and owns its own config type and defaults.
+Mounting is enabling: a handler claims its mouse and touch actions on mount and
+gives them back on unmount, and the controls are built with every action switched
+off. To add a gesture, write a sibling component and a field on `ControlsConfig`.
+
+`Camera` writes the limits in two effects — the pitch limits, and the framing
+(distance limits, far plane, and the dolly that preserves zoom across a resize),
+which is one transaction because the dolly must follow the limits.
+
+The controls are reached two ways and no other: `useCameraControls()` reads
+them, and `useControlsEffect(effect)` runs an effect against them once they
+exist, handing them over as an argument. The React Compiler rejects assigning to
+a _field_ of a hook's return value — a method call on it, or passing it to a
+function that does the assigning, is fine — so a component with a field to write
+either routes it through a helper or uses `useControlsEffect`. Two-finger
+gestures come off `useGesture(type, handler)`.
+
+## Adding GUI controls from a component
+
+`debug/gui-context.ts` exposes `useGui()`. It returns the active lil-gui
+instance, or `null` when the overlay is disabled or still loading — so guard on a
+non-null value. `useGui` is imported from the tiny `gui-context` module (a
+type-only lil-gui import), so consuming it does **not** pull lil-gui into the
+main chunk.
+
+```tsx
+function MyThing() {
+  const gui = useGui();
+  useEffect(() => {
+    if (!gui) return;
+    const folder = gui.addFolder('My thing');
+    folder.add(/* … */);
+    return () => folder.destroy();
+  }, [gui]);
+  // …
+}
+```
+
+## Recommended extensions
+
+Two browser extensions make what the renderer draws inspectable:
+
+- **[Three.js DevTools](https://chromewebstore.google.com/detail/threejs-devtools/jechbjkglifdaldbdbigibihfaclnkbo)**
+  adds a DevTools tab showing the live scene tree — the quickest way to see how
+  Defs translate into three.js objects. Hovering a mesh there highlights its
+  geometry on the plan.
+- **[SpectorJS](https://spector.babylonjs.com/)** lists every WebGL draw call of
+  a captured frame, with the intermediate canvas state between them. It takes a
+  little coaxing: tick **Show offscreen canvas(es)** to see the canvases React
+  renders (this works inconsistently — closing and reopening the extension a
+  couple of times usually gets there), pick the canvas from the **Choose
+  canvas…** dropdown by matching its dimensions, then press the red **Record**
+  button. In debug mode the capture opens immediately, because the scene
+  re-renders every frame; without it you have to trigger a frame first, most
+  easily by panning or zooming slightly.
+
+## Running unit tests
+
+Run `nx test @expofp/renderer` to execute the unit tests via [Vitest](https://vitest.dev/).

package/dist/Renderer.d.ts

@@ -0,0 +1,88 @@
+import { type Box } from '@expofp/geometry';
+import { type HTMLAttributes, type ReactNode, type Ref } from 'react';
+import { type ControlsConfig } from './controls';
+import { type ExternalCanvasProps } from './external/ExternalCanvas';
+import { type CameraProps } from './space/Camera';
+import { type SceneDef } from './types/defs';
+import { type PointerMissedEventData } from './types/events';
+export { type ExternalCanvasProps } from './external/ExternalCanvas';
+/**
+ * Props for {@link Renderer}. One surface for both mounts: the external trio rides along optional
+ * (the partial of {@link ExternalCanvasProps}, the way the camera limits ride along from
+ * {@link CameraProps}), and **`gl` arriving is what selects external mode** — exactly as it
+ * selected the imperative renderer's. With `gl` set, everything canvas- and camera-shaped is
+ * ignored: the host owns the canvas, the view and the frames, so the DOM attributes, `ref`,
+ * the camera limits, `controls` and `visibleRect` have nothing to configure.
+ */
+export interface RendererProps extends HTMLAttributes<HTMLDivElement>, CameraProps, Partial<ExternalCanvasProps> {
+    /** Ref to the underlying WebGL canvas element. Internal mode — the external canvas is the host's. */
+    ref?: Ref<HTMLCanvasElement>;
+    /**
+     * When `true`, enables the debug UI overlay — in both modes; the GUI, the readout panels and the
+     * frame stats attach to the document beside whichever canvas is drawing. The one figure external
+     * mode cannot always show is GPU memory: it needs the context created *after* the debug chunk has
+     * instrumented context creation, which a host arranges by awaiting `prepareDebug()` before
+     * building its map. Without that the memory panel shows and stays empty — visibly wrong rather
+     * than silently absent.
+     */
+    debug?: boolean;
+    /** The scene to render. */
+    scene: SceneDef;
+    /**
+     * Components rendered inside the canvas, under the scene's space and camera. This is where a
+     * caller puts anything that has to reach the renderer from within — camera commands, event
+     * bridges — since those hooks only work below a mounted canvas.
+     */
+    children?: ReactNode;
+    /**
+     * Soft cap, in megabytes, on the GPU memory the image atlases may consume. When the atlases would
+     * exceed it, every image source is downscaled by one shared linear factor — preserving their
+     * relative sizes, with no priority — until they fit. Canvas sources are counted at full size but
+     * never scaled (their pixels are the caller's), so a limit smaller than the canvases alone need is
+     * simply not met. May be changed at runtime: the resizable atlases re-derive their textures live,
+     * with no repack. Omitted (or `0`) means no cap, and the budget stands down entirely.
+     */
+    memoryLimit?: number;
+    /**
+     * Called for a click that reached no layer handler — empty background, or a def in a layer that
+     * declares none, since such a layer is never picked. The event reports where the click landed on
+     * the plan, which a click on nothing otherwise could not tell you.
+     *
+     * Clicks that *do* reach a layer go to that layer's `onClick` instead, so a caller that wants every
+     * click regardless (say, to publish plan coordinates) wires the same function in both places.
+     */
+    onPointerMissed?: (event: PointerMissedEventData) => void;
+    /**
+     * What the user may do with the plan by mouse and touch — pan, zoom, roll, pitch.
+     *
+     * The other half of navigation from the limits this extends {@link CameraProps} for: a caller
+     * switches a gesture off without changing where the camera may go, and constrains the camera
+     * without taking a gesture away.
+     */
+    controls?: ControlsConfig;
+    /**
+     * The part of the canvas the plan should be framed inside, in css pixels from its top-left
+     * corner — for a host whose own header, sheet or panel covers the rest.
+     *
+     * **The plan is still drawn across the whole canvas**: nothing is clipped, and the strips behind
+     * that UI show more of the plan than they would otherwise rather than being cropped away. What
+     * changes is where the viewbox lands, which is guaranteed to be inside this rect.
+     *
+     * Distinct from `zoomTo`'s `within`, which is about a single command's framing and moves nothing.
+     * Ignored for a scene that carries a `staticTransform`, where the host places the plan itself.
+     */
+    visibleRect?: Box;
+}
+/**
+ * R3F floorplan renderer. Composes **one** scene tree — space, camera, layers, debug overlay, the
+ * caller's children — and mounts it on one of two canvases: its own (an R3F `<Canvas>`, wrapped in
+ * the debug loader) or a host's, when the host's `gl` arrives and {@link ExternalCanvas} adopts its
+ * canvas, camera and frame loop instead. The tree is the same in both; what external mode drops is
+ * exactly what the host owns — the managed camera, the controls, the `visibleRect` framing — and
+ * the tree simply mounts none of them there.
+ * @param props - Renderer props; in internal mode, keys other than the renderer's own pass through
+ *   to the underlying canvas.
+ * @returns The rendered canvas and scene.
+ */
+export declare function Renderer(props: RendererProps): ReactNode;
+//# sourceMappingURL=Renderer.d.ts.map

package/dist/Renderer.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { StrictMode, Suspense } from 'react';
+import { Controls } from './controls';
+import { CanvasWithDebug, DebugOverlay } from './debug';
+import { PointerMissed } from './events/PointerMissed';
+import { ExternalCanvas } from './external/ExternalCanvas';
+import { Scene } from './space/Scene';
+import { createLogger } from './utils/logging';
+const logger = createLogger('renderer');
+/**
+ * R3F floorplan renderer. Composes **one** scene tree — space, camera, layers, debug overlay, the
+ * caller's children — and mounts it on one of two canvases: its own (an R3F `<Canvas>`, wrapped in
+ * the debug loader) or a host's, when the host's `gl` arrives and {@link ExternalCanvas} adopts its
+ * canvas, camera and frame loop instead. The tree is the same in both; what external mode drops is
+ * exactly what the host owns — the managed camera, the controls, the `visibleRect` framing — and
+ * the tree simply mounts none of them there.
+ * @param props - Renderer props; in internal mode, keys other than the renderer's own pass through
+ *   to the underlying canvas.
+ * @returns The rendered canvas and scene.
+ */
+export function Renderer(props) {
+    // Every prop of the renderer's own is pulled out here rather than read off `props` below, so none
+    // of them ride along in `canvasProps` and land on the canvas's wrapper element as unknown DOM
+    // attributes — which is what React warns about, and the reason every member of `CameraProps` has
+    // to be named here as well as reassembled below. They are passed on untouched: what an omitted
+    // one means is `Camera`'s to say, and it is the only place that says it.
+    const { debug, scene, memoryLimit, minZoom, maxZoom, minPitch, maxPitch, bounds, smoothTime, controls, visibleRect, onPointerMissed, gl, requestFrame, onFrame, children, ...canvasProps } = props;
+    const cameraProps = { minZoom, maxZoom, minPitch, maxPitch, bounds, smoothTime };
+    const external = gl !== undefined;
+    // The one tree, whichever canvas it lands on. The mount decides nothing about it; the tree
+    // leaves out what external mode has no object for — the controls here, the camera inside Scene.
+    const tree = (_jsx(DebugOverlay, { enabled: debug, children: _jsxs(Scene, { sceneDef: scene, external: external, memoryLimit: memoryLimit, visibleRect: visibleRect, ...cameraProps, children: [!external && _jsx(Controls, { config: controls }), _jsx(PointerMissed, { onPointerMissed: onPointerMissed }), children] }) }));
+    // The host's context arriving is what selects external mode. The mount swap is an element-type
+    // change, so flipping modes at runtime remounts — like `debug`, both are fixed for a renderer's
+    // lifetime in practice.
+    if (gl) {
+        if (!requestFrame || !onFrame) {
+            logger.error('external mode needs requestFrame and onFrame alongside gl; nothing will render');
+            return null;
+        }
+        // No StrictMode here: ExternalCanvas wraps the tree it renders into the foreign root itself,
+        // and its own bootstrap effect must run once per context, not be double-invoked into churn.
+        return (_jsx(ExternalCanvas, { gl: gl, requestFrame: requestFrame, onFrame: onFrame, children: tree }));
+    }
+    return (_jsx(StrictMode, { children: _jsx(Suspense, { fallback: null, children: _jsx(CanvasWithDebug, { ...canvasProps, debugEnabled: debug, 
+                // Tonemapping off: plan colors are authored values, not scene-referred light.
+                flat: true, 
+                // three leaves the stencil buffer off by default. Line layers need one: it is how they keep
+                // translucent lines from darkening where they overlap (see `LineMaterial`), and without the
+                // buffer the stencil settings silently do nothing. In the MapLibre embed the context is the
+                // map's own, which already has one.
+                gl: { stencil: true }, frameloop: debug ? 'always' : 'demand', resize: { debounce: 50 }, children: tree }) }) }));
+}

package/dist/controls/CameraControls.d.ts

@@ -0,0 +1,102 @@
+import { type NonFunctionKeys } from '@react-three/fiber/dist/declarations/src/core/utils';
+import { MapControls as CameraControlsImpl, type SmoothTimeOption } from 'camera-controls';
+import { type Ref } from 'react';
+import { type OrthographicCamera, type PerspectiveCamera } from 'three';
+/**
+ * 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;
+/**
+ * How far the plan is turned from north: clockwise, in radians, in `[0, 2π)`.
+ *
+ * The camera holds an azimuth, which runs the other way and over any range the user has spun it
+ * through. Every reader of "which way is the plan facing" wants this instead, so the negation and
+ * the wrap live here once rather than at each of them — the same getter the imperative renderer put
+ * on its controller.
+ * @param controls - The scene's controls.
+ * @returns The bearing in radians.
+ */
+export declare function bearing(controls: CameraControlsImpl): number;
+/**
+ * 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;
+/** Props for {@link CameraControls}: camera-controls element props plus lifecycle callbacks. */
+export type CameraControlsProps = Partial<Omit<Pick<CameraControlsImpl, NonFunctionKeys<CameraControlsImpl>>, 'smoothTime' | 'controlSmoothTime'>> & {
+    /** Ref to hold the camera-controls instance */
+    ref?: Ref<CameraControlsImpl>;
+    /** Camera to control; defaults to R3F's default camera. */
+    camera?: PerspectiveCamera | OrthographicCamera;
+    /** Element input listeners attach to; defaults to the R3F event target. */
+    domElement?: HTMLElement;
+    /** When set, registers these as R3F's default controls (`state.controls`). */
+    makeDefault?: boolean;
+    /** Called when a user control interaction begins. */
+    onControlStart?: (e?: {
+        type: 'controlstart';
+    }) => void;
+    /** Called on each frame of a control interaction. */
+    onControl?: (e?: {
+        type: 'control';
+    }) => void;
+    /** Called when a user control interaction ends. */
+    onControlEnd?: (e?: {
+        type: 'controlend';
+    }) => void;
+    /** Called when a programmatic camera transition starts. */
+    onTransitionStart?: (e?: {
+        type: 'transitionstart';
+    }) => void;
+    /** Called whenever the camera updates. */
+    onUpdate?: (e?: {
+        type: 'update';
+    }) => void;
+    /** Called when the controls wake (begin needing frame updates). */
+    onWake?: (e?: {
+        type: 'wake';
+    }) => void;
+    /** Called when the camera comes to rest. */
+    onRest?: (e?: {
+        type: 'rest';
+    }) => void;
+    /** Called when the controls sleep (stop needing frame updates). */
+    onSleep?: (e?: {
+        type: 'sleep';
+    }) => void;
+    /** Whether to keep R3F pointer events enabled during control interaction. */
+    events?: boolean;
+    /** When set, drops render resolution (`performance.regress`) during interaction. */
+    regress?: boolean;
+    /** Approximate time in seconds to reach the target. A smaller value will reach the target faster. */
+    smoothTime?: SmoothTimeOption;
+    /** The smoothTime used while the user is actively controlling the camera */
+    controlSmoothTime?: SmoothTimeOption;
+};
+/**
+ * R3F wrapper around the `camera-controls` library. Builds a controls instance
+ * for the active camera, wires its events to R3F's invalidate/regress loop and
+ * the optional callbacks, optionally makes it the default controls, and
+ * publishes the live camera state (position, target, spherical, clipping planes)
+ * to the debug panel as it changes.
+ * @param props - Controls configuration and event callbacks.
+ * @returns The controls instance as an R3F `<primitive>`.
+ */
+export declare function CameraControls(props: CameraControlsProps): import("react").JSX.Element;
+export { CameraControlsImpl };
+//# sourceMappingURL=CameraControls.d.ts.map

package/dist/controls/CameraControls.js

@@ -0,0 +1,239 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { radToDeg } from '@expofp/geometry';
+import { extend, useFrame, useThree } from '@react-three/fiber';
+import { MapControls as CameraControlsImpl } from 'camera-controls';
+import { useEffect, useState } from 'react';
+import { Box3, MathUtils, Matrix4, Quaternion, Raycaster, Sphere, Spherical, Vector2, Vector3, Vector4, } from 'three';
+import { useDebugPanel } from '../debug/debug-context';
+import { euclideanModulo } from '../utils/math';
+/**
+ * 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;
+}
+/**
+ * How far the plan is turned from north: clockwise, in radians, in `[0, 2π)`.
+ *
+ * The camera holds an azimuth, which runs the other way and over any range the user has spun it
+ * through. Every reader of "which way is the plan facing" wants this instead, so the negation and
+ * the wrap live here once rather than at each of them — the same getter the imperative renderer put
+ * on its controller.
+ * @param controls - The scene's controls.
+ * @returns The bearing in radians.
+ */
+export function bearing(controls) {
+    return euclideanModulo(-controls.azimuthAngle, 2 * Math.PI);
+}
+/**
+ * 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]);
+}
+// Install the subset of THREE that camera-controls uses and register it with
+// R3F, once at module load — before any controls are constructed during render,
+// so the `new CameraControlsImpl(...)` below never runs uninstalled. Importing
+// only the classes it needs keeps the bundle tree-shakeable.
+// See https://github.com/yomotsu/camera-controls#important
+const subsetOfThree = {
+    Box3,
+    MathUtils: { clamp: MathUtils.clamp },
+    Matrix4,
+    Quaternion,
+    Raycaster,
+    Sphere,
+    Spherical,
+    Vector2,
+    Vector3,
+    Vector4,
+};
+CameraControlsImpl.install({ THREE: subsetOfThree });
+extend({ CameraControlsImpl });
+/**
+ * R3F wrapper around the `camera-controls` library. Builds a controls instance
+ * for the active camera, wires its events to R3F's invalidate/regress loop and
+ * the optional callbacks, optionally makes it the default controls, and
+ * publishes the live camera state (position, target, spherical, clipping planes)
+ * to the debug panel as it changes.
+ * @param props - Controls configuration and event callbacks.
+ * @returns The controls instance as an R3F `<primitive>`.
+ */
+export function CameraControls(props) {
+    const { ref, camera, domElement, makeDefault, onControlStart, onControl, onControlEnd, onTransitionStart, onUpdate, onWake, onRest, onSleep, regress, ...restProps } = props;
+    const defaultCamera = useThree((state) => state.camera);
+    const gl = useThree((state) => state.gl);
+    const invalidate = useThree((state) => state.invalidate);
+    const set = useThree((state) => state.set);
+    const get = useThree((state) => state.get);
+    const performance = useThree((state) => state.performance);
+    const setDebugPanel = useDebugPanel();
+    const explCamera = camera ?? defaultCamera;
+    // The canvas itself, not `state.events.connected`. R3F connects its pointer events to the canvas
+    // unless a caller names an `eventSource`, which this renderer never does — and `connected` is
+    // `false` until it has, so consulting it only adds a window where there is no element to attach
+    // to. A caller wanting a different one passes `domElement`.
+    const explDomElement = domElement ?? gl.domElement;
+    // Hold the instance in state, not a memo: React Fast Refresh treats every
+    // dependency list as changed when a module is edited, so `useMemo` (and the
+    // React Compiler's memo cache) would hand back a fresh instance on each save,
+    // snapping the camera back to its default target. State survives a refresh, so
+    // the instance is rebuilt only when the camera it drives actually changes.
+    const [controls, setControls] = useState(() => createControls(explCamera));
+    const [controlsCamera, setControlsCamera] = useState(explCamera);
+    if (controlsCamera !== explCamera) {
+        setControlsCamera(explCamera);
+        setControls((controls) => Object.assign(controls, { camera: explCamera }));
+    }
+    useFrame((_state, delta) => {
+        const updated = controls.update(delta);
+        if (updated || gl.info.render.frame == 0) {
+            const position = explCamera.position.toArray().map((value) => +value.toFixed(2));
+            const target = controls
+                .getTarget(_target)
+                .toArray()
+                .map((value) => +value.toFixed(2));
+            const { theta, phi, radius } = controls.getSpherical(_spherical);
+            const spherical = [radToDeg(theta), radToDeg(phi), radius].map((value) => +value.toFixed(2));
+            const clippingPlanes = [explCamera.near, explCamera.far].map((value) => +value.toFixed(2));
+            setDebugPanel('camera', { position, target, spherical, clippingPlanes });
+        }
+    }, -1);
+    useEffect(() => {
+        controls.connect(explDomElement);
+        // Android WebViews send no pointercancel for a system gesture — the back-navigation swipe — so
+        // a control interaction the user has already left would go on animating. touchcancel is what
+        // they do send, and dropping the interaction on it is what the imperative renderer did.
+        const cancel = () => controls.cancel();
+        explDomElement.addEventListener('touchcancel', cancel);
+        return () => {
+            explDomElement.removeEventListener('touchcancel', cancel);
+            controls.disconnect();
+        };
+    }, [explDomElement, controls]);
+    useEffect(() => {
+        function invalidateAndRegress() {
+            invalidate();
+            if (regress)
+                performance.regress();
+        }
+        const handleControlStart = (e) => {
+            invalidateAndRegress();
+            onControlStart?.(e);
+        };
+        const handleControl = (e) => {
+            invalidateAndRegress();
+            onControl?.(e);
+        };
+        const handleControlEnd = (e) => {
+            onControlEnd?.(e);
+        };
+        const handleTransitionStart = (e) => {
+            invalidateAndRegress();
+            onTransitionStart?.(e);
+        };
+        const handleUpdate = (e) => {
+            invalidateAndRegress();
+            onUpdate?.(e);
+        };
+        const handleWake = (e) => {
+            invalidateAndRegress();
+            onWake?.(e);
+        };
+        const handleRest = (e) => {
+            onRest?.(e);
+        };
+        const handleSleep = (e) => {
+            onSleep?.(e);
+        };
+        controls.addEventListener('controlstart', handleControlStart);
+        controls.addEventListener('control', handleControl);
+        controls.addEventListener('controlend', handleControlEnd);
+        controls.addEventListener('transitionstart', handleTransitionStart);
+        controls.addEventListener('update', handleUpdate);
+        controls.addEventListener('wake', handleWake);
+        controls.addEventListener('rest', handleRest);
+        controls.addEventListener('sleep', handleSleep);
+        return () => {
+            controls.removeEventListener('controlstart', handleControlStart);
+            controls.removeEventListener('control', handleControl);
+            controls.removeEventListener('controlend', handleControlEnd);
+            controls.removeEventListener('transitionstart', handleTransitionStart);
+            controls.removeEventListener('update', handleUpdate);
+            controls.removeEventListener('wake', handleWake);
+            controls.removeEventListener('rest', handleRest);
+            controls.removeEventListener('sleep', handleSleep);
+        };
+    }, [
+        controls,
+        invalidate,
+        regress,
+        performance,
+        onControlStart,
+        onControl,
+        onControlEnd,
+        onTransitionStart,
+        onUpdate,
+        onWake,
+        onRest,
+        onSleep,
+    ]);
+    useEffect(() => {
+        if (makeDefault) {
+            const old = get().controls;
+            set({ controls: controls });
+            return () => set({ controls: old });
+        }
+        return;
+    }, [makeDefault, controls, set, get]);
+    return _jsx("primitive", { ref: ref, object: controls, ...restProps });
+}
+/**
+ * Builds a controls instance with every mouse and touch action switched off.
+ *
+ * **The handler components own the actions**, each setting its own on mount and clearing it on
+ * unmount, so the library's defaults — orbit on the left button, truck on the right, dolly on the
+ * middle and the wheel — would be a second author writing the same fields. Zeroed here at
+ * construction rather than through a prop or an effect, both of which run *after* a handler's:
+ * R3F re-applies a prop whenever its identity changes, and a parent's effect runs after its
+ * children's, so either would undo whatever had just been set.
+ *
+ * This is where the imperative renderer did it too, in its `CameraController` constructor.
+ * @param camera - The camera the controls drive.
+ * @returns The controls, inert until a handler claims an action.
+ */
+function createControls(camera) {
+    const controls = new CameraControlsImpl(camera);
+    const { NONE } = CameraControlsImpl.ACTION;
+    controls.mouseButtons = { left: NONE, middle: NONE, right: NONE, wheel: NONE };
+    controls.touches = { one: NONE, two: NONE, three: NONE };
+    return controls;
+}
+export { CameraControlsImpl };
+const _target = new Vector3();
+const _spherical = new Spherical();