@expofp/renderer 0.0.0-experimental.cf063fc

package/README.md

@@ -0,0 +1,145 @@
+# @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/).
+
+## Limits of the published package
+
+**`dist` is not supported outside this repository. It does not even resolve.**
+`dist/objects/images/worker/client.js` holds
+`import AtlasWorker from './atlas-worker?worker&inline'`, and `dist/index.js`
+reaches that file. The `?worker&inline` specifier is a Vite instruction, so
+only Vite can answer it. Any other consumer — a different bundler, plain Node,
+a browser loading the files as they are — fails to resolve the import and stops
+there. Nothing in the package loads, so there is no smaller part of it to fall
+back on.
+
+This package has no bundler. Its `build` target is plain `tsc`, so `dist` is
+file-per-module TypeScript output and nothing else runs over it. `tsc` copies
+the specifier through unchanged, which is where the broken import comes from.
+The same absence of a bundler means the React Compiler never runs on `dist`
+either, so the components there ship unoptimized.
+
+Nothing in this repository is affected, because nothing in this repository
+consumes `dist`. The renderer is compiled from its own source instead.
+Floorplan's browser build reaches `src` through the `@expofp/source` condition
+in `vite.config.mts`, so Vite answers the specifier and inlines the worker
+script into the bundle; floorplan also applies its own React Compiler pass.
+This package's own unit tests and Storybook import `src` by relative path, so
+Vite answers the specifier for them too: the Storybook run starts the real
+worker, and the unit tests drive the protocol against a fake one. Wayfinding
+imports types only, which are erased at emit. The offline CLI copies
+floorplan's browser bundle rather than importing anything.
+
+To lift the limit, give this package a Vite library build in the shape
+floorplan already uses. Keep `build` (tsc) for the types. Add `build-browser`
+(Vite) for the bundle. Put a `browser` condition in the exports map, above
+`import`. That answers the worker specifier and runs the React Compiler, so
+both problems above go with it.

package/dist/Renderer.d.ts

@@ -0,0 +1,102 @@
+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 LightingProps } from './objects/lighting';
+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 scene's lighting, and the darkening that rides with it: the rig's contrast and three
+     * colors, and a `shadow` object holding the shade both darkening terms blend toward and each
+     * term's own numbers. See {@link LightingProps}.
+     *
+     * Every value is optional and every omitted one keeps the design's own default, so a caller sets
+     * the one number a plan needs and nothing else. Where the key light points is not here: that is
+     * the design's decision, and the debug GUI keeps it.
+     *
+     * Changing a value moves a mounted scene with no remount and no shader recompile. It lands on a
+     * uniform or on a field the frame reads, and asks for a redraw.
+     */
+    lighting?: LightingProps;
+    /**
+     * 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,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { StrictMode, Suspense, useEffect, useRef, } 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, lighting, visibleRect, onPointerMissed, gl, requestFrame, onFrame, children, ...canvasProps } = props;
+    const cameraProps = { minZoom, maxZoom, minPitch, maxPitch, bounds, smoothTime };
+    const external = gl !== undefined;
+    // The context this mount created, released here rather than left to R3F. `<Canvas>`'s teardown
+    // (`unmountComponentAtNode`) defers `forceContextLoss()` behind a 500 ms `setTimeout`, inside a
+    // `try` that disconnects events first — so a host that unmounts the renderer holds a full
+    // viewport of GPU memory for half a second after it thought the surface was gone, and holds it
+    // forever if anything ahead of the loss in that block throws. An SDK `destroy()` that returns
+    // while the plan still owns a WebGL2 context is the same bug on a timer, and a plan swap pays it
+    // as a real transient: the incoming plan's context is created while the outgoing one still
+    // holds its own. R3F's deferred pass still runs afterwards and is unharmed — its remaining work
+    // (`renderLists.dispose()`, `dispose(scene)`) is no-ops on a lost context.
+    //
+    // Safe as a plain unmount effect only because `<StrictMode>` starts *below* here, wrapping the
+    // canvas rather than this component: nothing simulates a remount at this level, so the cleanup
+    // runs when the renderer is actually going away. External mode never fills the ref — the host
+    // owns that context, and `ExternalCanvas` neuters `forceContextLoss` for the same reason.
+    const rendererRef = useRef(undefined);
+    useEffect(() => {
+        return () => {
+            rendererRef.current?.forceContextLoss();
+            rendererRef.current = 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, lighting: lighting, 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, 
+                // No `dpr`: R3F's default caps the buffer at 2x, and that is a performance choice rather
+                // than a size one. Every pixel-authored size is derived from CSS units and the pixel size
+                // the renderer publishes (also CSS), so a 3x canvas rasterized by a caller still draws at
+                // the size it asked for while the buffer stays at 2x. A 3x buffer is 2.25 times the area
+                // of a 2x one, on exactly the devices that can least afford it.
+                debugEnabled: debug, 
+                // R3F force-writes ACES filmic tone mapping onto a fresh renderer unless `flat` is set,
+                // which lands it on three's own default, `NoToneMapping`, instead. This renderer does not
+                // tone map: `Lighting` keeps the rig's light sum in range by construction, rather than
+                // compressing an unbounded one back into range afterward.
+                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 }, 
+                // three reads a program's info log straight after linking it, and that read blocks until
+                // the driver has finished linking. Left to itself the driver links in the background,
+                // because `KHR_parallel_shader_compile` is there, so the check is the whole of what makes
+                // a compile synchronous: 17 programs cost 64 ms of main thread on a large scene, in
+                // blocks of up to 12 ms, and they land in the frames where the layers are still mounting.
+                // Debug keeps the check, because a broken shader has to report itself somewhere.
+                //
+                // The root state is also this mount's one handle on the renderer, which the unmount
+                // effect above needs to release its context.
+                onCreated: (state) => {
+                    state.gl.debug.checkShaderErrors = debug ?? false;
+                    rendererRef.current = state.gl;
+                }, frameloop: debug ? 'always' : 'demand', resize: { debounce: 50 }, children: tree }) }) }));
+}

package/dist/controls/CameraControls.d.ts

@@ -0,0 +1,108 @@
+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';
+/** 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;
+/**
+ * The controls class, under the name the rest of this package calls it by.
+ *
+ * A **type** and not a value: the only code that needs the class itself is right here, and a type
+ * survives an import cycle where a class would not — so a handler this module's own parent loads
+ * can name it freely. Everything else the library offers arrives through
+ * {@link CameraControlsAction}.
+ */
+export { type CameraControlsImpl };
+/**
+ * The mouse and touch actions a handler claims, from the library's own enum.
+ *
+ * Beside the component rather than in a module of its own: a constant is the one thing Fast Refresh
+ * tolerates next to a component, and this one never changes.
+ */
+export declare const CameraControlsAction: Readonly<{
+    readonly NONE: 0;
+    readonly ROTATE_AZIMUTH: 1;
+    readonly ROTATE_POLAR: 2;
+    readonly ROTATE: number;
+    readonly TRUCK: 4;
+    readonly SCREEN_PAN: 8;
+    readonly OFFSET: 16;
+    readonly DOLLY: 32;
+    readonly ZOOM: 64;
+    readonly TOUCH_ROTATE_AZIMUTH: 128;
+    readonly TOUCH_ROTATE_POLAR: 256;
+    readonly TOUCH_ROTATE: number;
+    readonly TOUCH_TRUCK: 512;
+    readonly TOUCH_SCREEN_PAN: 1024;
+    readonly TOUCH_OFFSET: 2048;
+    readonly TOUCH_DOLLY: 4096;
+    readonly TOUCH_ZOOM: 8192;
+    readonly TOUCH_DOLLY_TRUCK: number;
+    readonly TOUCH_DOLLY_SCREEN_PAN: number;
+    readonly TOUCH_DOLLY_OFFSET: number;
+    readonly TOUCH_DOLLY_ROTATE: number;
+    readonly TOUCH_ZOOM_TRUCK: number;
+    readonly TOUCH_ZOOM_OFFSET: number;
+    readonly TOUCH_ZOOM_SCREEN_PAN: number;
+    readonly TOUCH_ZOOM_ROTATE: number;
+}>;
+//# sourceMappingURL=CameraControls.d.ts.map

package/dist/controls/CameraControls.js

@@ -0,0 +1,203 @@
+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';
+// 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(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
+                .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 } = CameraControlsAction;
+    controls.mouseButtons = { left: NONE, middle: NONE, right: NONE, wheel: NONE };
+    controls.touches = { one: NONE, two: NONE, three: NONE };
+    return controls;
+}
+/**
+ * The mouse and touch actions a handler claims, from the library's own enum.
+ *
+ * Beside the component rather than in a module of its own: a constant is the one thing Fast Refresh
+ * 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();