@pmndrs/klipp 0.0.0-stage → 0.14.0

package/dist/react/aim/PanTilt.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode, type Ref } from 'react';
+import type { DampingConstant } from '../../core/damping/damping.js';
+import type { InputAxisRecentering } from '../../core/input/axis.js';
+import { PanTiltAimThree } from '../../three/aim/PanTiltAimThree.js';
+import type { Target } from '../../three/resolve/Target.js';
+export type PanTiltProps = {
+    /** Rotation frame `pan`/`tilt` compose on top of.
+     * `null`/`undefined`/omitted is world (`referenceUp`-aware) */
+    target?: Target;
+    /** Applied to both `pan.damping` and `tilt.damping`. */
+    damping?: DampingConstant;
+    /** Applied to both `pan.maxSpeed` and `tilt.maxSpeed` - caps how fast `damping` can close the gap, in degrees/sec. */
+    maxSpeed?: number;
+    /** `pan.autoNormalize`. Only applies while `panWrap` is `true`. */
+    autoNormalize?: boolean;
+    /** `pan.wrap` - loops at `panRange`'s edges or hard-clamps them. */
+    panWrap?: boolean;
+    /** `tilt.wrap` - see `panWrap`. */
+    tiltWrap?: boolean;
+    /** `pan.range` - its edges wrap or clamp depending on `panWrap`. */
+    panRange?: [number, number];
+    /** `tilt.range` - its edges wrap or clamp depending on `tiltWrap`. */
+    tiltRange?: [number, number];
+    /** Applied to both `pan.recentering` and `tilt.recentering`. */
+    recentering?: InputAxisRecentering;
+    ref?: Ref<PanTiltAimThree>;
+    /** Nested `<InputController>` picks up `pan`/`tilt` automatically without an explicit `target`. */
+    children?: ReactNode;
+};
+/** Thin wrapper around `PanTiltAimThree`. */
+export declare function PanTilt({ target, damping, maxSpeed, autoNormalize, panWrap, tiltWrap, panRange, tiltRange, recentering, ref, children, }: PanTiltProps): import("react").JSX.Element;

package/dist/react/aim/PanTilt.js

@@ -0,0 +1,38 @@
+import { PanTiltAimThree } from "../../three/aim/PanTiltAimThree.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { InputAxisOwnerContext } from "../input/InputAxisOwnerContext.js";
+import { useEffect, useImperativeHandle, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/aim/PanTilt.tsx
+var defaultPanRange = [-180, 180];
+var defaultTiltRange = [-90, 90];
+var defaultRecentering = {
+	enabled: false,
+	wait: 1,
+	time: 1
+};
+/** Thin wrapper around `PanTiltAimThree`. */
+function PanTilt({ target, damping = 0, maxSpeed = Infinity, autoNormalize = false, panWrap = true, tiltWrap = false, panRange = defaultPanRange, tiltRange = defaultTiltRange, recentering = defaultRecentering, ref, children }) {
+	const camera = useVirtualCamera();
+	const [aim] = useState(() => new PanTiltAimThree());
+	aim.target = target;
+	aim.pan.damping = damping;
+	aim.pan.maxSpeed = maxSpeed;
+	aim.pan.autoNormalize = autoNormalize;
+	aim.pan.wrap = panWrap;
+	aim.pan.range = panRange;
+	aim.pan.recentering = recentering;
+	aim.tilt.damping = damping;
+	aim.tilt.maxSpeed = maxSpeed;
+	aim.tilt.wrap = tiltWrap;
+	aim.tilt.range = tiltRange;
+	aim.tilt.recentering = recentering;
+	useImperativeHandle(ref, () => aim, [aim]);
+	useEffect(() => camera.setAim(aim), [camera, aim]);
+	return /* @__PURE__ */ jsx(InputAxisOwnerContext.Provider, {
+		value: aim,
+		children
+	});
+}
+//#endregion
+export { PanTilt };

package/dist/react/aim/RotateWithFollowTarget.d.ts

@@ -0,0 +1,10 @@
+import { type Ref } from 'react';
+import { RotateWithFollowTargetAimThree, type RotateWithFollowTargetOptions } from '../../three/aim/RotateWithFollowTargetAimThree.js';
+import type { Target } from '../../three/resolve/Target.js';
+export type RotateWithFollowTargetProps = RotateWithFollowTargetOptions & {
+    /** Target rotation to copy. Unresolved targets are ignored. */
+    target?: Target;
+    ref?: Ref<RotateWithFollowTargetAimThree>;
+};
+/** Thin wrapper around `RotateWithFollowTargetAimThree`. */
+export declare function RotateWithFollowTarget({ target, ref, ...settings }: RotateWithFollowTargetProps): null;

package/dist/react/aim/RotateWithFollowTarget.js

@@ -0,0 +1,18 @@
+import { createParams } from "../../core/aim/rotateWithFollowTarget.js";
+import { RotateWithFollowTargetAimThree } from "../../three/aim/RotateWithFollowTargetAimThree.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { useEffect, useImperativeHandle, useState } from "react";
+//#region src/react/aim/RotateWithFollowTarget.tsx
+/** Thin wrapper around `RotateWithFollowTargetAimThree`. */
+function RotateWithFollowTarget({ target, ref, ...settings }) {
+	const camera = useVirtualCamera();
+	const params = createParams(settings);
+	const [aim] = useState(() => new RotateWithFollowTargetAimThree(target, params));
+	aim.target = target;
+	Object.assign(aim, params);
+	useImperativeHandle(ref, () => aim, [aim]);
+	useEffect(() => camera.setAim(aim), [camera, aim]);
+	return null;
+}
+//#endregion
+export { RotateWithFollowTarget };

package/dist/react/aim/RotationComposer.d.ts

@@ -0,0 +1,12 @@
+import { type Ref } from 'react';
+import { RotationComposerAimThree, type RotationComposerThreeOptions } from '../../three/aim/RotationComposerAimThree.js';
+import type { Target } from '../../three/resolve/Target.js';
+export type RotationComposerProps = Omit<RotationComposerThreeOptions, 'aspect'> & {
+    /** Target to compose at `screenPosition`. Unresolved targets are ignored. */
+    target?: Target;
+    /** Draws the `deadZone` and `hardLimit` overlays. */
+    debug?: boolean;
+    ref?: Ref<RotationComposerAimThree>;
+};
+/** Keeps a target within a chosen screen region by rotating the camera. */
+export declare function RotationComposer({ target, targetOffset, debug, ref, ...settings }: RotationComposerProps): import("react").JSX.Element | null;

package/dist/react/aim/RotationComposer.js

@@ -0,0 +1,34 @@
+import { createParams } from "../../core/aim/rotationComposer.js";
+import { composer } from "../../core/debug/debugZones.js";
+import { resolveVec3 } from "../../three/resolve/resolveVector3.js";
+import { RotationComposerAimThree } from "../../three/aim/RotationComposerAimThree.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { DebugZoneOverlay } from "../DebugZoneOverlay.js";
+import { useThree } from "@react-three/fiber";
+import { useEffect, useImperativeHandle, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/aim/RotationComposer.tsx
+/** Keeps a target within a chosen screen region by rotating the camera. */
+function RotationComposer({ target, targetOffset, debug = false, ref, ...settings }) {
+	const camera = useVirtualCamera();
+	const aspect = useThree((state) => state.viewport.aspect);
+	const { targetOffset: defaultTargetOffset, ...params } = createParams({
+		...settings,
+		aspect
+	});
+	const [aim] = useState(() => new RotationComposerAimThree(target, params));
+	aim.target = target;
+	Object.assign(aim, params);
+	resolveVec3(aim.targetOffset, targetOffset ?? defaultTargetOffset);
+	aim.radius = settings.radius;
+	aim.size = settings.size;
+	useImperativeHandle(ref, () => aim, [aim]);
+	useEffect(() => camera.setAim(aim), [camera, aim]);
+	if (!debug) return null;
+	return /* @__PURE__ */ jsx(DebugZoneOverlay, {
+		zones: composer(aim.screenPosition, aim.deadZone, aim.hardLimit),
+		crosshair: aim.screenPosition
+	});
+}
+//#endregion
+export { RotationComposer };

package/dist/react/body/Body.d.ts

@@ -0,0 +1,11 @@
+import { Follow } from './Follow.js';
+import { HardLockToTarget } from './HardLockToTarget.js';
+import { OrbitFollow } from './OrbitFollow.js';
+import { PositionComposer } from './PositionComposer.js';
+/** Body components control a `<VirtualCamera>`'s position. Use at most one per camera. */
+export declare const Body: {
+    HardLockToTarget: typeof HardLockToTarget;
+    Follow: typeof Follow;
+    PositionComposer: typeof PositionComposer;
+    OrbitFollow: typeof OrbitFollow;
+};

package/dist/react/body/Body.js

@@ -0,0 +1,14 @@
+import { Follow } from "./Follow.js";
+import { HardLockToTarget } from "./HardLockToTarget.js";
+import { OrbitFollow } from "./OrbitFollow.js";
+import { PositionComposer } from "./PositionComposer.js";
+//#region src/react/body/Body.ts
+/** Body components control a `<VirtualCamera>`'s position. Use at most one per camera. */
+var Body = {
+	HardLockToTarget,
+	Follow,
+	PositionComposer,
+	OrbitFollow
+};
+//#endregion
+export { Body };

package/dist/react/body/CameraControls.d.ts

@@ -0,0 +1,50 @@
+import type { ThreeElement, Vector3 as Vector3Like } from '@react-three/fiber';
+import CameraControlsImpl, { EventDispatcher } from 'camera-controls';
+import { type Ref } from 'react';
+import { CameraControlsBodyThree } from '../../three/body/CameraControlsBodyThree.js';
+import type { Target } from '../../three/resolve/Target.js';
+type Overwrite<T, U> = Omit<T, keyof U> & U;
+export type CameraControlsProps = Omit<Overwrite<ThreeElement<typeof CameraControlsImpl>, {
+    /** Target for orbiting and dollying. Omit for free camera controls. */
+    target?: Target;
+    /** World-space starting position, applied at construction regardless of `target`'s state. */
+    initialPosition?: Vector3Like;
+    /** `camera-controls`' own transition-easing argument for every call this makes. */
+    enableTransition?: boolean;
+    /** Custom `CameraControlsImpl` subclass to instantiate instead of the base class. */
+    impl?: typeof CameraControlsImpl;
+    /** Wait for an in-progress blend into this camera before listening to input. */
+    waitForBlend?: boolean;
+    /** Registers this instance as r3f's `state.controls` while it accepts input. */
+    makeDefault?: boolean;
+    ref?: Ref<CameraControlsBodyThree>;
+    /** Also lowers r3f's render quality while dragging/transitioning. */
+    regress?: boolean;
+    onControlStart?: (event: {
+        type: 'controlstart';
+    }) => void;
+    onControl?: (event: {
+        type: 'control';
+    }) => void;
+    onControlEnd?: (event: {
+        type: 'controlend';
+    }) => void;
+    onTransitionStart?: (event: {
+        type: 'transitionstart';
+    }) => void;
+    onUpdate?: (event: {
+        type: 'update';
+    }) => void;
+    onWake?: (event: {
+        type: 'wake';
+    }) => void;
+    onRest?: (event: {
+        type: 'rest';
+    }) => void;
+    onSleep?: (event: {
+        type: 'sleep';
+    }) => void;
+}>, 'args' | keyof EventDispatcher>;
+/** Connects `camera-controls` to the active virtual camera. */
+export declare function CameraControls({ target, initialPosition, enableTransition, impl, waitForBlend, makeDefault, ref, regress, onControlStart, onControl, onControlEnd, onTransitionStart, onUpdate, onWake, onRest, onSleep, ...controlsProps }: CameraControlsProps): import("react").JSX.Element;
+export {};

package/dist/react/body/CameraControls.js

@@ -0,0 +1,106 @@
+import { resolveVector3 } from "../../three/resolve/resolveVector3.js";
+import { CameraControlsBodyThree } from "../../three/body/CameraControlsBodyThree.js";
+import { useIsActiveVirtualCamera, useIsLiveVirtualCamera, useVirtualCamera } from "../VirtualCameraContext.js";
+import { Vector3 } from "three";
+import CameraControls from "camera-controls";
+import { useThree } from "@react-three/fiber";
+import { useEffect, useEffectEvent, useImperativeHandle, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/body/CameraControls.tsx
+/** Connects `camera-controls` to the active virtual camera. */
+function CameraControls$1({ target, initialPosition, enableTransition = false, impl = CameraControls, waitForBlend = true, makeDefault = false, ref, regress = false, onControlStart, onControl, onControlEnd, onTransitionStart, onUpdate, onWake, onRest, onSleep, ...controlsProps }) {
+	const camera = useVirtualCamera();
+	const isActive = useIsActiveVirtualCamera();
+	const isLive = useIsLiveVirtualCamera();
+	const shouldConnect = isActive && (waitForBlend ? isLive : true);
+	const aspect = useThree((state) => state.viewport.aspect);
+	const domElement = useThree((state) => state.gl.domElement);
+	const invalidate = useThree((state) => state.invalidate);
+	const performance = useThree((state) => state.performance);
+	const set = useThree((state) => state.set);
+	const get = useThree((state) => state.get);
+	const [body] = useState(() => new CameraControlsBodyThree(target, {
+		aspect,
+		initialPosition: initialPosition ? resolveVector3(new Vector3(), initialPosition) : null,
+		impl,
+		enableTransition
+	}));
+	body.target = target;
+	body.aspect = aspect;
+	body.enableTransition = enableTransition;
+	useImperativeHandle(ref, () => body, [body]);
+	useEffect(() => camera.setBody(body), [camera, body]);
+	useEffect(() => {
+		if (!makeDefault || !shouldConnect) return;
+		const previous = get().controls;
+		set({ controls: body.controls });
+		return () => set({ controls: previous });
+	}, [
+		makeDefault,
+		shouldConnect,
+		body,
+		set,
+		get
+	]);
+	const invalidateAndRegress = useEffectEvent(() => {
+		invalidate();
+		if (regress) performance.regress();
+	});
+	const handleControlStart = useEffectEvent((e) => {
+		invalidateAndRegress();
+		onControlStart?.(e);
+	});
+	const handleControl = useEffectEvent((e) => {
+		invalidateAndRegress();
+		onControl?.(e);
+	});
+	const handleControlEnd = useEffectEvent((e) => onControlEnd?.(e));
+	const handleTransitionStart = useEffectEvent((e) => {
+		invalidateAndRegress();
+		onTransitionStart?.(e);
+	});
+	const handleUpdate = useEffectEvent((e) => {
+		invalidateAndRegress();
+		onUpdate?.(e);
+	});
+	const handleWake = useEffectEvent((e) => {
+		invalidateAndRegress();
+		onWake?.(e);
+	});
+	const handleRest = useEffectEvent((e) => onRest?.(e));
+	const handleSleep = useEffectEvent((e) => onSleep?.(e));
+	useEffect(() => {
+		if (!shouldConnect) return;
+		body.controls.connect(domElement);
+		body.controls.addEventListener("controlstart", handleControlStart);
+		body.controls.addEventListener("control", handleControl);
+		body.controls.addEventListener("controlend", handleControlEnd);
+		body.controls.addEventListener("transitionstart", handleTransitionStart);
+		body.controls.addEventListener("update", handleUpdate);
+		body.controls.addEventListener("wake", handleWake);
+		body.controls.addEventListener("rest", handleRest);
+		body.controls.addEventListener("sleep", handleSleep);
+		if (domElement.ownerDocument.pointerLockElement === domElement) body.controls.lockPointer();
+		return () => {
+			body.controls.disconnect();
+			body.controls.removeEventListener("controlstart", handleControlStart);
+			body.controls.removeEventListener("control", handleControl);
+			body.controls.removeEventListener("controlend", handleControlEnd);
+			body.controls.removeEventListener("transitionstart", handleTransitionStart);
+			body.controls.removeEventListener("update", handleUpdate);
+			body.controls.removeEventListener("wake", handleWake);
+			body.controls.removeEventListener("rest", handleRest);
+			body.controls.removeEventListener("sleep", handleSleep);
+		};
+	}, [
+		body,
+		domElement,
+		shouldConnect
+	]);
+	return /* @__PURE__ */ jsx("primitive", {
+		object: body.controls,
+		...controlsProps
+	});
+}
+//#endregion
+export { CameraControls$1 as CameraControls };

package/dist/react/body/Follow.d.ts

@@ -0,0 +1,10 @@
+import { type Ref } from 'react';
+import { FollowBodyThree, type FollowThreeOptions } from '../../three/body/FollowBodyThree.js';
+import type { Target } from '../../three/resolve/Target.js';
+export type FollowProps = FollowThreeOptions & {
+    /** Target to follow. Unresolved targets are ignored. */
+    target?: Target;
+    ref?: Ref<FollowBodyThree>;
+};
+/** Follows a target with a configurable offset and rotation frame. */
+export declare function Follow({ target, offset, ref, ...settings }: FollowProps): null;

package/dist/react/body/Follow.js

@@ -0,0 +1,20 @@
+import { createParams } from "../../core/body/follow.js";
+import { resolveVec3 } from "../../three/resolve/resolveVector3.js";
+import { FollowBodyThree } from "../../three/body/FollowBodyThree.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { useEffect, useImperativeHandle, useState } from "react";
+//#region src/react/body/Follow.tsx
+/** Follows a target with a configurable offset and rotation frame. */
+function Follow({ target, offset, ref, ...settings }) {
+	const camera = useVirtualCamera();
+	const { offset: defaultOffset, ...params } = createParams(settings);
+	const [body] = useState(() => new FollowBodyThree(target, params));
+	body.target = target;
+	Object.assign(body, params);
+	resolveVec3(body.offset, offset ?? defaultOffset);
+	useImperativeHandle(ref, () => body, [body]);
+	useEffect(() => camera.setBody(body), [camera, body]);
+	return null;
+}
+//#endregion
+export { Follow };

package/dist/react/body/HardLockToTarget.d.ts

@@ -0,0 +1,10 @@
+import { type Ref } from 'react';
+import { HardLockToTargetBodyThree, type HardLockToTargetOptions } from '../../three/body/HardLockToTargetBodyThree.js';
+import type { Target } from '../../three/resolve/Target.js';
+export type HardLockToTargetProps = HardLockToTargetOptions & {
+    /** Target position to follow. Unresolved targets are ignored. */
+    target?: Target;
+    ref?: Ref<HardLockToTargetBodyThree>;
+};
+/** Simple body that locks the camera to a target position, optionally with damping. */
+export declare function HardLockToTarget({ target, ref, ...settings }: HardLockToTargetProps): null;

package/dist/react/body/HardLockToTarget.js

@@ -0,0 +1,18 @@
+import { createParams } from "../../core/body/hardLockToTarget.js";
+import { HardLockToTargetBodyThree } from "../../three/body/HardLockToTargetBodyThree.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { useEffect, useImperativeHandle, useState } from "react";
+//#region src/react/body/HardLockToTarget.tsx
+/** Simple body that locks the camera to a target position, optionally with damping. */
+function HardLockToTarget({ target, ref, ...settings }) {
+	const camera = useVirtualCamera();
+	const params = createParams(settings);
+	const [body] = useState(() => new HardLockToTargetBodyThree(target, params));
+	body.target = target;
+	Object.assign(body, params);
+	useImperativeHandle(ref, () => body, [body]);
+	useEffect(() => camera.setBody(body), [camera, body]);
+	return null;
+}
+//#endregion
+export { HardLockToTarget };

package/dist/react/body/OrbitFollow.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode, type Ref } from 'react';
+import type { InputAxisParams } from '../../core/input/axis.js';
+import { OrbitFollowBodyThree, type OrbitFollowThreeOptions } from '../../three/body/OrbitFollowBodyThree.js';
+import type { Target } from '../../three/resolve/Target.js';
+/** Settings of one orbit axis. It starts at `center`, then input drives its value. */
+export type OrbitFollowAxisSettings = Partial<Omit<InputAxisParams, 'value'>>;
+export type OrbitFollowProps = OrbitFollowThreeOptions & {
+    /** Target to orbit. Unresolved targets are ignored. */
+    target?: Target;
+    /** Angle around the target, in degrees. */
+    horizontal?: OrbitFollowAxisSettings;
+    /** Elevation above the target in degrees, or from the bottom to the top ring for `threeRing`. */
+    vertical?: OrbitFollowAxisSettings;
+    /** Natural log of the radius scale. */
+    radial?: OrbitFollowAxisSettings;
+    /** `horizontal.autoNormalize`: keeps it inside its range after each drag. */
+    autoNormalize?: boolean;
+    /** Draws the orbit in the scene. */
+    debug?: boolean;
+    ref?: Ref<OrbitFollowBodyThree>;
+    /** Nested `<InputController>` picks up `horizontal`/`vertical`/`radial` without an explicit `target`. */
+    children?: ReactNode;
+};
+/** Orbits a target, driven by the `horizontal`, `vertical` and `radial` axes. */
+export declare function OrbitFollow({ target, targetOffset, horizontal, vertical, radial, autoNormalize, debug, ref, children, ...settings }: OrbitFollowProps): import("react").JSX.Element;

package/dist/react/body/OrbitFollow.js

@@ -0,0 +1,67 @@
+import { withDefaults } from "../../core/params.js";
+import { createParams } from "../../core/input/axis.js";
+import { createAxisSettings, createParams as createParams$1 } from "../../core/body/orbitFollow.js";
+import { resolveVec3 } from "../../three/resolve/resolveVector3.js";
+import { OrbitFollowBodyThree } from "../../three/body/OrbitFollowBodyThree.js";
+import { OrbitFollowHelperThree } from "../../three/body/OrbitFollowHelperThree.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { InputAxisOwnerContext } from "../input/InputAxisOwnerContext.js";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useImperativeHandle, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/body/OrbitFollow.tsx
+function applyAxis(axis, defaults, settings) {
+	const params = withDefaults(createParams(defaults), settings);
+	params.value = axis.value;
+	Object.assign(axis, params);
+}
+function applyAxes(body, { horizontal, vertical, radial, autoNormalize }) {
+	const defaults = createAxisSettings();
+	defaults.horizontal.autoNormalize = autoNormalize;
+	applyAxis(body.horizontal, defaults.horizontal, horizontal);
+	applyAxis(body.vertical, defaults.vertical, vertical);
+	applyAxis(body.radial, defaults.radial, radial);
+}
+/** Orbits a target, driven by the `horizontal`, `vertical` and `radial` axes. */
+function OrbitFollow({ target, targetOffset, horizontal, vertical, radial, autoNormalize = false, debug = false, ref, children, ...settings }) {
+	const camera = useVirtualCamera();
+	const { targetOffset: defaultTargetOffset, ...params } = createParams$1(settings);
+	const [body] = useState(() => {
+		const created = new OrbitFollowBodyThree(target, params);
+		applyAxes(created, {
+			horizontal,
+			vertical,
+			radial,
+			autoNormalize
+		});
+		for (const axis of [
+			created.horizontal,
+			created.vertical,
+			created.radial
+		]) axis.setValue(axis.center);
+		return created;
+	});
+	body.target = target;
+	Object.assign(body, params);
+	resolveVec3(body.targetOffset, targetOffset ?? defaultTargetOffset);
+	applyAxes(body, {
+		horizontal,
+		vertical,
+		radial,
+		autoNormalize
+	});
+	useImperativeHandle(ref, () => body, [body]);
+	useEffect(() => camera.setBody(body), [camera, body]);
+	return /* @__PURE__ */ jsxs(InputAxisOwnerContext.Provider, {
+		value: body,
+		children: [children, debug && /* @__PURE__ */ jsx(OrbitDebug, { body })]
+	});
+}
+function OrbitDebug({ body }) {
+	const [helper] = useState(() => new OrbitFollowHelperThree());
+	useEffect(() => () => helper.dispose(), [helper]);
+	useFrame(() => helper.sync(body));
+	return /* @__PURE__ */ jsx("primitive", { object: helper });
+}
+//#endregion
+export { OrbitFollow };

package/dist/react/body/PositionComposer.d.ts

@@ -0,0 +1,12 @@
+import { type Ref } from 'react';
+import { PositionComposerBodyThree, type PositionComposerThreeOptions } from '../../three/body/PositionComposerBodyThree.js';
+import type { Target } from '../../three/resolve/Target.js';
+export type PositionComposerProps = Omit<PositionComposerThreeOptions, 'aspect'> & {
+    /** Target to compose around. Unresolved targets are ignored. */
+    target?: Target;
+    /** Draws the `deadZone` and `hardLimit` overlays. */
+    debug?: boolean;
+    ref?: Ref<PositionComposerBodyThree>;
+};
+/** Positions the camera around a target while maintaining screen composition. */
+export declare function PositionComposer({ target, debug, ref, ...settings }: PositionComposerProps): import("react").JSX.Element | null;

package/dist/react/body/PositionComposer.js

@@ -0,0 +1,32 @@
+import { createParams } from "../../core/body/positionComposer.js";
+import { composer } from "../../core/debug/debugZones.js";
+import { PositionComposerBodyThree } from "../../three/body/PositionComposerBodyThree.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { DebugZoneOverlay } from "../DebugZoneOverlay.js";
+import { useThree } from "@react-three/fiber";
+import { useEffect, useImperativeHandle, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/body/PositionComposer.tsx
+/** Positions the camera around a target while maintaining screen composition. */
+function PositionComposer({ target, debug = false, ref, ...settings }) {
+	const camera = useVirtualCamera();
+	const aspect = useThree((state) => state.viewport.aspect);
+	const params = createParams({
+		...settings,
+		aspect
+	});
+	const [body] = useState(() => new PositionComposerBodyThree(target, params));
+	body.target = target;
+	Object.assign(body, params);
+	body.radius = settings.radius;
+	body.size = settings.size;
+	useImperativeHandle(ref, () => body, [body]);
+	useEffect(() => camera.setBody(body), [camera, body]);
+	if (!debug) return null;
+	return /* @__PURE__ */ jsx(DebugZoneOverlay, {
+		zones: composer(body.screenPosition, body.deadZone, body.hardLimit),
+		crosshair: body.screenPosition
+	});
+}
+//#endregion
+export { PositionComposer };

package/dist/react/body/camera-controls.d.ts

@@ -0,0 +1,2 @@
+export { CameraControls, type CameraControlsProps } from './CameraControls.js';
+export { CameraControlsBodyThree } from '../../three/body/CameraControlsBodyThree.js';

package/dist/react/body/camera-controls.js

@@ -0,0 +1,3 @@
+import { CameraControlsBodyThree } from "../../three/body/CameraControlsBodyThree.js";
+import { CameraControls } from "./CameraControls.js";
+export { CameraControls, CameraControlsBodyThree };

package/dist/react/extension/Extension.d.ts

@@ -0,0 +1,7 @@
+import { GroupFraming } from './GroupFraming.js';
+import { Lens } from './Lens.js';
+/** Extensions run after Body/Aim and before Noise; multiple extensions can be registered. */
+export declare const Extension: {
+    GroupFraming: typeof GroupFraming;
+    Lens: typeof Lens;
+};

package/dist/react/extension/Extension.js

@@ -0,0 +1,10 @@
+import { GroupFraming } from "./GroupFraming.js";
+import { Lens } from "./Lens.js";
+//#region src/react/extension/Extension.ts
+/** Extensions run after Body/Aim and before Noise; multiple extensions can be registered. */
+var Extension = {
+	GroupFraming,
+	Lens
+};
+//#endregion
+export { Extension };

package/dist/react/extension/GroupFraming.d.ts

@@ -0,0 +1,14 @@
+import { type Ref } from 'react';
+import { GroupFramingExtensionThree, type GroupFramingOptions } from '../../three/extension/GroupFramingExtensionThree.js';
+import { type TargetGroupMember, type TargetGroupPositionMode } from '../../three/extension/TargetGroup.js';
+export type GroupFramingProps = Omit<GroupFramingOptions, 'viewportWidth' | 'viewportHeight'> & {
+    /** Targets to keep in frame. */
+    members: TargetGroupMember[];
+    /** Strategy used to compute the group's position. */
+    positionMode?: TargetGroupPositionMode;
+    /** Draws the padding boundary while this camera is live. */
+    debug?: boolean;
+    ref?: Ref<GroupFramingExtensionThree>;
+};
+/** Keeps a target group framed within the camera. */
+export declare function GroupFraming({ members, positionMode, debug, ref, ...settings }: GroupFramingProps): import("react").JSX.Element | null;

package/dist/react/extension/GroupFraming.js

@@ -0,0 +1,52 @@
+import { createParams } from "../../core/extension/groupFraming.js";
+import { groupFramingPaddingBox } from "../../core/debug/debugZones.js";
+import { TargetGroup } from "../../three/extension/TargetGroup.js";
+import { GroupFramingExtensionThree } from "../../three/extension/GroupFramingExtensionThree.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { DebugZoneOverlay } from "../DebugZoneOverlay.js";
+import { Vector3 } from "three";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useImperativeHandle, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/extension/GroupFraming.tsx
+var scratchGroupPosition = new Vector3();
+var scratchCameraPosition = new Vector3();
+/** Minimum visible change for the debug overlay. */
+var DEBUG_BOX_EPSILON = .002;
+/** Keeps a target group framed within the camera. */
+function GroupFraming({ members, positionMode = "groupCenter", debug = false, ref, ...settings }) {
+	const camera = useVirtualCamera();
+	const cameraState = camera.state;
+	const size = useThree((state) => state.size);
+	const params = createParams({
+		...settings,
+		viewportWidth: size.width,
+		viewportHeight: size.height
+	});
+	const [group] = useState(() => new TargetGroup(members, positionMode));
+	const [extension] = useState(() => new GroupFramingExtensionThree(group, params));
+	group.members = members;
+	group.positionMode = positionMode;
+	Object.assign(extension, params);
+	useImperativeHandle(ref, () => extension, [extension]);
+	useEffect(() => camera.addExtension(extension), [camera, extension]);
+	const [paddingBox, setPaddingBox] = useState(null);
+	useFrame(() => {
+		if (!debug) return;
+		if (group.computeBounds(scratchGroupPosition) <= 0) {
+			setPaddingBox((previous) => previous === null ? previous : null);
+			return;
+		}
+		const distance = scratchCameraPosition.fromArray(cameraState.position).distanceTo(scratchGroupPosition);
+		const next = groupFramingPaddingBox([0, 0], cameraState.fov, size.width / size.height, distance, extension.padding, extension.framingMode);
+		setPaddingBox((previous) => previous && Math.abs(previous[0] - next[0]) < DEBUG_BOX_EPSILON && Math.abs(previous[1] - next[1]) < DEBUG_BOX_EPSILON ? previous : next);
+	});
+	if (!debug || !paddingBox) return null;
+	return /* @__PURE__ */ jsx(DebugZoneOverlay, { zones: [{
+		screenPosition: extension.screenPosition,
+		size: paddingBox,
+		className: "klipp-debug-groupframing"
+	}] });
+}
+//#endregion
+export { GroupFraming };

package/dist/react/extension/Lens.d.ts

@@ -0,0 +1,7 @@
+import { type Ref } from 'react';
+import { LensExtension, type LensOptions } from '../../core/extension/LensExtension.js';
+export type LensProps = LensOptions & {
+    ref?: Ref<LensExtension>;
+};
+/** Animates the camera lens without forcing a React re-render. */
+export declare function Lens({ ref, ...settings }: LensProps): null;