@pmndrs/klipp 0.0.0-stage → 0.14.0

package/dist/react/extension/Lens.js

@@ -0,0 +1,31 @@
+import { createParams } from "../../core/extension/lens.js";
+import { LensExtension } from "../../core/extension/LensExtension.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { useThree } from "@react-three/fiber";
+import { useEffect, useImperativeHandle, useState } from "react";
+//#region src/react/extension/Lens.tsx
+/** Animates the camera lens without forcing a React re-render. */
+function Lens({ ref, ...settings }) {
+	const camera = useVirtualCamera();
+	const invalidate = useThree((state) => state.invalidate);
+	const params = createParams(settings);
+	const [extension] = useState(() => new LensExtension(params));
+	Object.assign(extension, params);
+	useImperativeHandle(ref, () => extension, [extension]);
+	useEffect(() => camera.addExtension(extension), [camera, extension]);
+	const { fov, near, far, fovDamping, nearDamping, farDamping } = params;
+	useEffect(() => {
+		invalidate();
+	}, [
+		fov,
+		near,
+		far,
+		fovDamping,
+		nearDamping,
+		farDamping,
+		invalidate
+	]);
+	return null;
+}
+//#endregion
+export { Lens };

package/dist/react/impulse/ImpulseListener.d.ts

@@ -0,0 +1,12 @@
+import { type Ref } from 'react';
+import { ImpulseListenerNoise, type ImpulseListenerOptions } from '../../core/impulse/ImpulseListenerNoise.js';
+import type { BasicMultiChannelPerlinProps } from '../noise/BasicMultiChannelPerlin.js';
+/** Perlin shake options driven by the current impulse strength. */
+export type ImpulseShakeProps = Omit<BasicMultiChannelPerlinProps, 'amplitudeGain' | 'ref'>;
+export type ImpulseListenerProps = Omit<ImpulseListenerOptions, 'shake'> & {
+    /** Optional Perlin shake driven by the impulse strength. */
+    shake?: ImpulseShakeProps;
+    ref?: Ref<ImpulseListenerNoise>;
+};
+/** Adds impulse-driven camera shake and kick. */
+export declare function ImpulseListener({ shake, ref, ...settings }: ImpulseListenerProps): import("react").JSX.Element | null;

package/dist/react/impulse/ImpulseListener.js

@@ -0,0 +1,33 @@
+import { createParams } from "../../core/impulse/impulseListener.js";
+import { ImpulseListenerNoise } from "../../core/impulse/ImpulseListenerNoise.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { useBasicMultiChannelPerlinNoise } from "../noise/useBasicMultiChannelPerlinNoise.js";
+import { useEffect, useImperativeHandle, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/impulse/ImpulseListener.tsx
+/** Adds impulse-driven camera shake and kick. */
+function ImpulseListener({ shake, ref, ...settings }) {
+	const camera = useVirtualCamera();
+	const params = createParams(settings);
+	const [listener] = useState(() => new ImpulseListenerNoise(params));
+	Object.assign(listener, params);
+	useImperativeHandle(ref, () => listener, [listener]);
+	useEffect(() => camera.addNoise(listener), [camera, listener]);
+	return shake ? /* @__PURE__ */ jsx(ImpulseListenerShake, {
+		listener,
+		...shake
+	}) : null;
+}
+/** Mounts the optional Perlin shake. */
+function ImpulseListenerShake({ listener, ...props }) {
+	const shakeNoise = useBasicMultiChannelPerlinNoise(props);
+	useEffect(() => {
+		listener.shake = shakeNoise;
+		return () => {
+			listener.shake = void 0;
+		};
+	}, [listener, shakeNoise]);
+	return null;
+}
+//#endregion
+export { ImpulseListener };

package/dist/react/index.d.ts

@@ -0,0 +1,24 @@
+export { CameraFrustumHelper, type CameraFrustumHelperProps } from './CameraFrustumHelper.js';
+export { Klipp, KlippEvents, type KlippEventsProps, type KlippMode, type KlippProps } from './Klipp.js';
+export { useKlipp, type FrameUpdate } from './KlippContext.js';
+export { VirtualCamera, VirtualCameraEvents, type VirtualCameraEventsProps, type VirtualCameraProps, } from './VirtualCamera.js';
+export { useIsActiveVirtualCamera, useIsLiveVirtualCamera, useVirtualCamera } from './VirtualCameraContext.js';
+export type { InputAxisOwner } from '../core/input/InputAxisOwner.js';
+export { InputAxisOwnerContext } from './input/InputAxisOwnerContext.js';
+export { InputController, type InputAxisSourceConfig, type InputControllerProps, type InputSourceConfig, } from './input/InputController.js';
+export { Body } from './body/Body.js';
+export { Follow, type FollowProps } from './body/Follow.js';
+export { HardLockToTarget, type HardLockToTargetProps } from './body/HardLockToTarget.js';
+export { OrbitFollow, type OrbitFollowAxisSettings, type OrbitFollowProps } from './body/OrbitFollow.js';
+export { PositionComposer, type PositionComposerProps } from './body/PositionComposer.js';
+export { Aim } from './aim/Aim.js';
+export { HardLookAt, type HardLookAtProps } from './aim/HardLookAt.js';
+export { PanTilt, type PanTiltProps } from './aim/PanTilt.js';
+export { RotateWithFollowTarget, type RotateWithFollowTargetProps } from './aim/RotateWithFollowTarget.js';
+export { RotationComposer, type RotationComposerProps } from './aim/RotationComposer.js';
+export { BasicMultiChannelPerlin, type BasicMultiChannelPerlinProps } from './noise/BasicMultiChannelPerlin.js';
+export { Noise } from './noise/Noise.js';
+export { ImpulseListener, type ImpulseListenerProps, type ImpulseShakeProps } from './impulse/ImpulseListener.js';
+export { Extension } from './extension/Extension.js';
+export { GroupFraming, type GroupFramingProps } from './extension/GroupFraming.js';
+export { Lens, type LensProps } from './extension/Lens.js';

package/dist/react/index.js

@@ -0,0 +1,24 @@
+import { useIsActiveVirtualCamera, useIsLiveVirtualCamera, useVirtualCamera } from "./VirtualCameraContext.js";
+import { CameraFrustumHelper } from "./CameraFrustumHelper.js";
+import { useKlipp } from "./KlippContext.js";
+import { Klipp, KlippEvents } from "./Klipp.js";
+import { VirtualCamera, VirtualCameraEvents } from "./VirtualCamera.js";
+import { InputAxisOwnerContext } from "./input/InputAxisOwnerContext.js";
+import { InputController } from "./input/InputController.js";
+import { Follow } from "./body/Follow.js";
+import { HardLockToTarget } from "./body/HardLockToTarget.js";
+import { OrbitFollow } from "./body/OrbitFollow.js";
+import { PositionComposer } from "./body/PositionComposer.js";
+import { Body } from "./body/Body.js";
+import { HardLookAt } from "./aim/HardLookAt.js";
+import { PanTilt } from "./aim/PanTilt.js";
+import { RotateWithFollowTarget } from "./aim/RotateWithFollowTarget.js";
+import { RotationComposer } from "./aim/RotationComposer.js";
+import { Aim } from "./aim/Aim.js";
+import { BasicMultiChannelPerlin } from "./noise/BasicMultiChannelPerlin.js";
+import { Noise } from "./noise/Noise.js";
+import { ImpulseListener } from "./impulse/ImpulseListener.js";
+import { GroupFraming } from "./extension/GroupFraming.js";
+import { Lens } from "./extension/Lens.js";
+import { Extension } from "./extension/Extension.js";
+export { Aim, BasicMultiChannelPerlin, Body, CameraFrustumHelper, Extension, Follow, GroupFraming, HardLockToTarget, HardLookAt, ImpulseListener, InputAxisOwnerContext, InputController, Klipp, KlippEvents, Lens, Noise, OrbitFollow, PanTilt, PositionComposer, RotateWithFollowTarget, RotationComposer, VirtualCamera, VirtualCameraEvents, useIsActiveVirtualCamera, useIsLiveVirtualCamera, useKlipp, useVirtualCamera };

package/dist/react/input/InputAxisOwnerContext.d.ts

@@ -0,0 +1,3 @@
+import type { InputAxisOwner } from '../../core/input/InputAxisOwner.js';
+/** Set by a Body/Aim/Extension around its `children`, so a nested `<InputController>` finds its `inputAxes`. */
+export declare const InputAxisOwnerContext: import("react").Context<InputAxisOwner | null>;

package/dist/react/input/InputAxisOwnerContext.js

@@ -0,0 +1,6 @@
+import { createContext } from "react";
+//#region src/react/input/InputAxisOwnerContext.ts
+/** Set by a Body/Aim/Extension around its `children`, so a nested `<InputController>` finds its `inputAxes`. */
+var InputAxisOwnerContext = createContext(null);
+//#endregion
+export { InputAxisOwnerContext };

package/dist/react/input/InputController.d.ts

@@ -0,0 +1,53 @@
+import { type Ref, type RefObject } from 'react';
+import type { InputAxisOwner } from '../../core/input/InputAxisOwner.js';
+import type { InputInvert } from '../../core/input/inputMapping.js';
+import { InputControllerDom } from '../../dom/InputControllerDom.js';
+import type { InteractiveArea } from '../../dom/InputSystem.js';
+export type InputSourceConfig = {
+    /** Axis names to drive for each source. */
+    axes: {
+        x: string;
+        y: string;
+    };
+    /** Multiplies the raw delta before it reaches the axes. */
+    gain?: number;
+    invert?: InputInvert;
+};
+export type InputAxisSourceConfig = {
+    /** Axis name to drive. */
+    axis: string;
+    /** Multiplies the raw delta before it reaches the axis. */
+    gain?: number;
+    invert?: boolean;
+};
+export type InputControllerProps = {
+    /** Axis owner to drive. Uses the nearest owner context when omitted, or else the virtual camera itself. */
+    target?: RefObject<InputAxisOwner | null>;
+    mouseButtons?: {
+        left?: InputSourceConfig | null;
+        right?: InputSourceConfig | null;
+        middle?: InputSourceConfig | null;
+    };
+    touches?: {
+        one?: InputSourceConfig | null;
+        two?: InputSourceConfig | null;
+        three?: InputSourceConfig | null;
+    };
+    /** Vertical wheel scrolling, in pixels. Scrolling up is positive, like spreading a pinch. */
+    wheel?: InputAxisSourceConfig | null;
+    /** Pinch with two fingers or on a trackpad, as the change in `ln(scale)`. Spreading is positive. */
+    pinch?: InputAxisSourceConfig | null;
+    /** Wait until this camera is live before listening to input. */
+    waitForBlend?: boolean;
+    /** Whether input reaches the axes. Unmount the component to stop listening altogether. */
+    enabled?: boolean;
+    /** Suppresses the native right-click context menu. */
+    suppressContextMenu?: boolean;
+    /** Restricts drag/wheel start to a normalized rect of the element's bounds. */
+    interactiveArea?: InteractiveArea | null;
+    /** Lock diagonal two-finger input to pinch or rotation. */
+    lockTouchAxis?: boolean;
+    ref?: Ref<InputControllerDom>;
+};
+/** Connects DOM input sources to named axes on a camera component. */
+export declare function InputController(props: InputControllerProps): null;

package/dist/react/input/InputController.js

@@ -0,0 +1,115 @@
+import { useIsActiveVirtualCamera, useIsLiveVirtualCamera, useVirtualCamera } from "../VirtualCameraContext.js";
+import { useKlipp } from "../KlippContext.js";
+import { InputAxisOwnerContext } from "./InputAxisOwnerContext.js";
+import { InputControllerDom } from "../../dom/InputControllerDom.js";
+import { useThree } from "@react-three/fiber";
+import { use, useEffect, useImperativeHandle, useState } from "react";
+//#region src/react/input/InputController.tsx
+function resolveAxis(owner, name) {
+	const axis = owner.inputAxes[name];
+	if (!axis) {
+		console.warn(`<InputController>: no axis named "${name}" on target's inputAxes.`);
+		return null;
+	}
+	return axis;
+}
+function resolveSource(owner, source) {
+	if (!source) return null;
+	const x = resolveAxis(owner, source.axes.x);
+	const y = resolveAxis(owner, source.axes.y);
+	if (!x || !y) return null;
+	return {
+		axes: {
+			x,
+			y
+		},
+		gain: source.gain,
+		invert: source.invert
+	};
+}
+function resolveAxisSource(owner, source) {
+	if (!source) return null;
+	const axis = resolveAxis(owner, source.axis);
+	return axis && {
+		axis,
+		gain: source.gain,
+		invert: source.invert
+	};
+}
+function buildConfig(owner, props) {
+	return {
+		mouseButtons: {
+			left: resolveSource(owner, props.mouseButtons?.left),
+			right: resolveSource(owner, props.mouseButtons?.right),
+			middle: resolveSource(owner, props.mouseButtons?.middle)
+		},
+		touches: {
+			one: resolveSource(owner, props.touches?.one),
+			two: resolveSource(owner, props.touches?.two),
+			three: resolveSource(owner, props.touches?.three)
+		},
+		wheel: resolveAxisSource(owner, props.wheel),
+		pinch: resolveAxisSource(owner, props.pinch)
+	};
+}
+/** Connects DOM input sources to named axes on a camera component. */
+function InputController(props) {
+	const { waitForBlend = true, enabled = true, suppressContextMenu = false, interactiveArea = null, lockTouchAxis = false, ref } = props;
+	const contextOwner = use(InputAxisOwnerContext);
+	const camera = useVirtualCamera();
+	const klipp = useKlipp();
+	const isActive = useIsActiveVirtualCamera();
+	const isLive = useIsLiveVirtualCamera();
+	const shouldConnect = isActive && (waitForBlend ? isLive : true);
+	const domElement = useThree((state) => state.gl.domElement);
+	const invalidate = useThree((state) => state.invalidate);
+	const [controller] = useState(() => new InputControllerDom({}));
+	const [binding] = useState(() => ({
+		props,
+		contextOwner,
+		owner: null,
+		axes: null,
+		stale: true
+	}));
+	useImperativeHandle(ref, () => controller, [controller]);
+	controller.enabled = enabled;
+	controller.inputSystem.suppressContextMenu = suppressContextMenu;
+	controller.inputSystem.interactiveArea = interactiveArea;
+	controller.inputSystem.lockTouchAxis = lockTouchAxis;
+	useEffect(() => {
+		binding.props = props;
+		binding.contextOwner = contextOwner;
+		binding.stale = true;
+	});
+	useEffect(() => klipp.registerUpdate(() => {
+		const owner = binding.props.target?.current ?? binding.contextOwner ?? camera;
+		if (binding.stale || owner !== binding.owner || owner.inputAxes !== binding.axes) {
+			controller.config = buildConfig(owner, binding.props);
+			binding.owner = owner;
+			binding.axes = owner.inputAxes;
+			binding.stale = false;
+		}
+		controller.update();
+	}), [
+		klipp,
+		controller,
+		binding,
+		camera
+	]);
+	useEffect(() => {
+		if (!shouldConnect) return;
+		controller.connect(domElement, () => invalidate());
+		return () => {
+			controller.disconnect();
+			invalidate();
+		};
+	}, [
+		controller,
+		domElement,
+		shouldConnect,
+		invalidate
+	]);
+	return null;
+}
+//#endregion
+export { InputController };

package/dist/react/noise/BasicMultiChannelPerlin.d.ts

@@ -0,0 +1,7 @@
+import { type Ref } from 'react';
+import type { BasicMultiChannelPerlinNoiseThree, PerlinNoiseThreeOptions } from '../../three/noise/BasicMultiChannelPerlinNoiseThree.js';
+export type BasicMultiChannelPerlinProps = PerlinNoiseThreeOptions & {
+    ref?: Ref<BasicMultiChannelPerlinNoiseThree>;
+};
+/** Adds position and rotation noise to the camera. */
+export declare function BasicMultiChannelPerlin({ ref, ...props }: BasicMultiChannelPerlinProps): null;

package/dist/react/noise/BasicMultiChannelPerlin.js

@@ -0,0 +1,14 @@
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { useBasicMultiChannelPerlinNoise } from "./useBasicMultiChannelPerlinNoise.js";
+import { useEffect, useImperativeHandle } from "react";
+//#region src/react/noise/BasicMultiChannelPerlin.tsx
+/** Adds position and rotation noise to the camera. */
+function BasicMultiChannelPerlin({ ref, ...props }) {
+	const camera = useVirtualCamera();
+	const noise = useBasicMultiChannelPerlinNoise(props);
+	useImperativeHandle(ref, () => noise, [noise]);
+	useEffect(() => camera.addNoise(noise), [camera, noise]);
+	return null;
+}
+//#endregion
+export { BasicMultiChannelPerlin };

package/dist/react/noise/Noise.d.ts

@@ -0,0 +1,5 @@
+import { BasicMultiChannelPerlin } from './BasicMultiChannelPerlin.js';
+/** Noise components add position and rotation offsets to a virtual camera. Multiple noise components can stack. */
+export declare const Noise: {
+    BasicMultiChannelPerlin: typeof BasicMultiChannelPerlin;
+};

package/dist/react/noise/Noise.js

@@ -0,0 +1,6 @@
+import { BasicMultiChannelPerlin } from "./BasicMultiChannelPerlin.js";
+//#region src/react/noise/Noise.ts
+/** Noise components add position and rotation offsets to a virtual camera. Multiple noise components can stack. */
+var Noise = { BasicMultiChannelPerlin };
+//#endregion
+export { Noise };

package/dist/react/noise/useBasicMultiChannelPerlinNoise.d.ts

@@ -0,0 +1,4 @@
+import { BasicMultiChannelPerlinNoiseThree } from '../../three/noise/BasicMultiChannelPerlinNoiseThree.js';
+import type { BasicMultiChannelPerlinProps } from './BasicMultiChannelPerlin.js';
+/** Creates and synchronizes a shared Perlin noise instance from props. */
+export declare function useBasicMultiChannelPerlinNoise({ positionAmplitude, positionFrequency, rotationAmplitude, rotationFrequency, seed, ...settings }: Omit<BasicMultiChannelPerlinProps, 'ref'>): BasicMultiChannelPerlinNoiseThree;

package/dist/react/noise/useBasicMultiChannelPerlinNoise.js

@@ -0,0 +1,21 @@
+import { createParams } from "../../core/noise/perlinNoise.js";
+import { resolveVec3 } from "../../three/resolve/resolveVector3.js";
+import { BasicMultiChannelPerlinNoiseThree } from "../../three/noise/BasicMultiChannelPerlinNoiseThree.js";
+import { useState } from "react";
+//#region src/react/noise/useBasicMultiChannelPerlinNoise.ts
+/** Creates and synchronizes a shared Perlin noise instance from props. */
+function useBasicMultiChannelPerlinNoise({ positionAmplitude, positionFrequency, rotationAmplitude, rotationFrequency, seed, ...settings }) {
+	const { positionAmplitude: defaultPositionAmplitude, positionFrequency: defaultPositionFrequency, rotationAmplitude: defaultRotationAmplitude, rotationFrequency: defaultRotationFrequency, ...params } = createParams(settings);
+	const [noise] = useState(() => new BasicMultiChannelPerlinNoiseThree({
+		...params,
+		seed
+	}));
+	Object.assign(noise, params);
+	resolveVec3(noise.positionAmplitude, positionAmplitude ?? defaultPositionAmplitude);
+	resolveVec3(noise.positionFrequency, positionFrequency ?? defaultPositionFrequency);
+	resolveVec3(noise.rotationAmplitude, rotationAmplitude ?? defaultRotationAmplitude);
+	resolveVec3(noise.rotationFrequency, rotationFrequency ?? defaultRotationFrequency);
+	return noise;
+}
+//#endregion
+export { useBasicMultiChannelPerlinNoise };

package/dist/react/useCameraTransitionEvent.d.ts

@@ -0,0 +1,12 @@
+import type { EventDispatcher } from '../core/EventDispatcher.js';
+import type { CameraTransitionEventMap } from '../core/Klipp.js';
+/** Callback props for camera transition events. */
+export type CameraTransitionEventProps = {
+    onActivated?: (event: CameraTransitionEventMap['activated']) => void;
+    onDeactivated?: (event: CameraTransitionEventMap['deactivated']) => void;
+    onBlendCreated?: (event: CameraTransitionEventMap['blendCreated']) => void;
+    onBlendFinished?: (event: CameraTransitionEventMap['blendFinished']) => void;
+    onCut?: (event: CameraTransitionEventMap['cut']) => void;
+};
+/** Subscribe to one camera transition event. */
+export declare function useCameraTransitionEvent<T extends keyof CameraTransitionEventMap>(dispatcher: EventDispatcher<CameraTransitionEventMap>, type: T, listener: ((event: CameraTransitionEventMap[T]) => void) | undefined): void;

package/dist/react/useCameraTransitionEvent.js

@@ -0,0 +1,14 @@
+import { useEffect, useEffectEvent } from "react";
+//#region src/react/useCameraTransitionEvent.ts
+/** Subscribe to one camera transition event. */
+function useCameraTransitionEvent(dispatcher, type, listener) {
+	const onEvent = useEffectEvent((event) => {
+		listener?.(event);
+	});
+	useEffect(() => {
+		dispatcher.addEventListener(type, onEvent);
+		return () => dispatcher.removeEventListener(type, onEvent);
+	}, [dispatcher, type]);
+}
+//#endregion
+export { useCameraTransitionEvent };

package/dist/three/CameraFrustumHelperThree.d.ts

@@ -0,0 +1,11 @@
+import { CameraHelper } from 'three';
+import type { CameraState } from '../core/CameraState.js';
+/** A `CameraHelper` that draws a virtual camera's frustum from its `state`. */
+export declare class CameraFrustumHelperThree extends CameraHelper {
+    /** How far the frustum is drawn. */
+    maxDistance: number;
+    private readonly lens;
+    constructor(maxDistance?: number);
+    /** Follow `state`, seen at `aspect`. Redraws only when the pose or lens changed. */
+    sync(state: CameraState, aspect: number): void;
+}

package/dist/three/CameraFrustumHelperThree.js

@@ -0,0 +1,44 @@
+import { CameraHelper, PerspectiveCamera, Quaternion, Vector3 } from "three";
+//#region src/three/CameraFrustumHelperThree.ts
+var scratchPosition = new Vector3();
+var scratchQuaternion = new Quaternion();
+/** A `CameraHelper` that draws a virtual camera's frustum from its `state`. */
+var CameraFrustumHelperThree = class extends CameraHelper {
+	/** How far the frustum is drawn. */
+	maxDistance;
+	lens = {
+		fov: NaN,
+		near: NaN,
+		far: NaN,
+		aspect: NaN
+	};
+	constructor(maxDistance = 1) {
+		super(new PerspectiveCamera());
+		this.maxDistance = maxDistance;
+	}
+	/** Follow `state`, seen at `aspect`. Redraws only when the pose or lens changed. */
+	sync(state, aspect) {
+		const camera = this.camera;
+		const far = Math.min(state.far, this.maxDistance);
+		const lens = this.lens;
+		const lensChanged = lens.fov !== state.fov || lens.near !== state.near || lens.far !== far || lens.aspect !== aspect;
+		if (lensChanged) {
+			camera.fov = lens.fov = state.fov;
+			camera.near = lens.near = state.near;
+			camera.far = lens.far = far;
+			camera.aspect = lens.aspect = aspect;
+			camera.updateProjectionMatrix();
+		}
+		scratchPosition.fromArray(state.position);
+		scratchQuaternion.fromArray(state.quaternion);
+		const transformChanged = !camera.position.equals(scratchPosition) || !camera.quaternion.equals(scratchQuaternion);
+		if (transformChanged) {
+			camera.position.copy(scratchPosition);
+			camera.quaternion.copy(scratchQuaternion);
+			camera.updateMatrixWorld(true);
+		}
+		if (lensChanged || transformChanged) this.update();
+	}
+};
+//#endregion
+export { CameraFrustumHelperThree };

package/dist/three/KlippThree.d.ts

@@ -0,0 +1,18 @@
+import type { Camera } from 'three';
+import type { CameraState } from '../core/CameraState.js';
+import { Klipp, type KlippOptions } from '../core/Klipp.js';
+import { VirtualCameraThree, type VirtualCameraThreeOptions } from './VirtualCameraThree.js';
+import { TargetRegistry } from './resolve/TargetRegistry.js';
+export type { KlippMode, FrameUpdate } from '../core/Klipp.js';
+export type KlippThreeOptions = Omit<KlippOptions, 'initialCameraState'>;
+/** `Klipp` for three.js: reads `Object3D` targets once per frame and writes the shot to a camera. */
+export declare class KlippThree extends Klipp {
+    /** Reads every target once per frame for all the pieces that follow it. */
+    readonly targets: TargetRegistry;
+    /** The camera to drive. New virtual cameras start from its pose and lens. */
+    camera: Camera;
+    constructor(camera: Camera, options?: KlippThreeOptions);
+    addCamera(name: string, options?: VirtualCameraThreeOptions): VirtualCameraThree;
+    protected prepareFrame(): void;
+    protected write(result: CameraState, transformChanged: boolean, lensChanged: boolean): void;
+}

package/dist/three/KlippThree.js

@@ -0,0 +1,50 @@
+import { create } from "../core/CameraState.js";
+import { Klipp } from "../core/Klipp.js";
+import { copyCameraStateFromCamera, writeCameraLens, writeCameraTransform } from "./camera.js";
+import { VirtualCameraThree } from "./VirtualCameraThree.js";
+import { TargetRegistry } from "./resolve/TargetRegistry.js";
+//#region src/three/KlippThree.ts
+/** `three` can load twice in monorepos; `instanceof` then fails. Use the camera's own flag instead. */
+function isPerspectiveCamera(camera) {
+	return camera.isPerspectiveCamera === true;
+}
+/** The original pose and lens per camera, so a later `KlippThree` on the same camera does not inherit stale state. */
+var pristineCameraStates = /* @__PURE__ */ new WeakMap();
+function pristineStateOf(camera) {
+	let pristine = pristineCameraStates.get(camera);
+	if (!pristine) {
+		pristine = create();
+		if (isPerspectiveCamera(camera)) copyCameraStateFromCamera(pristine, camera);
+		pristineCameraStates.set(camera, pristine);
+	}
+	return pristine;
+}
+/** `Klipp` for three.js: reads `Object3D` targets once per frame and writes the shot to a camera. */
+var KlippThree = class extends Klipp {
+	/** Reads every target once per frame for all the pieces that follow it. */
+	targets = new TargetRegistry();
+	/** The camera to drive. New virtual cameras start from its pose and lens. */
+	camera;
+	constructor(camera, options = {}) {
+		super({
+			...options,
+			initialCameraState: pristineStateOf(camera)
+		});
+		this.camera = camera;
+	}
+	addCamera(name, options) {
+		const camera = new VirtualCameraThree(name, options);
+		this.add(camera);
+		return camera;
+	}
+	prepareFrame() {
+		super.prepareFrame();
+		this.targets.refresh();
+	}
+	write(result, transformChanged, lensChanged) {
+		if (transformChanged) writeCameraTransform(this.camera, result);
+		if (lensChanged && isPerspectiveCamera(this.camera)) writeCameraLens(this.camera, result, this.width || 1, this.height || 1);
+	}
+};
+//#endregion
+export { KlippThree };

package/dist/three/VirtualCameraThree.d.ts

@@ -0,0 +1,35 @@
+import { type Quat } from 'math';
+import { Quaternion } from 'three';
+import type { CameraState } from '../core/CameraState.js';
+import { attachTo, prepare } from '../core/internal.js';
+import type { Klipp } from '../core/Klipp.js';
+import { VirtualCamera, type CameraPiece, type VirtualCameraOptions } from '../core/VirtualCamera.js';
+import { type Vector3Like } from './resolve/resolveVector3.js';
+export type { CameraPiece };
+/** A starting pose and lens, with three.js vector shorthand. */
+export type InitialCameraState = Partial<Omit<CameraState, 'position' | 'quaternion' | 'target' | 'lookAtTarget' | 'referenceUp'>> & {
+    position?: Vector3Like;
+    quaternion?: Quaternion | Quat;
+    target?: Vector3Like;
+    lookAtTarget?: Vector3Like;
+    referenceUp?: Vector3Like;
+};
+export type VirtualCameraThreeOptions = Omit<VirtualCameraOptions, 'initialState'> & {
+    /** Starting pose, applied on creation. Defaults to the real camera's pose. */
+    initialState?: InitialCameraState;
+};
+/** `VirtualCamera` for three.js: points every piece's target at its slot in the `KlippThree`'s registry. */
+export declare class VirtualCameraThree extends VirtualCamera {
+    /** The target registry of the `KlippThree` this camera is in. */
+    private registry;
+    private readonly slots;
+    private readonly groupSlots;
+    constructor(name: string, options?: VirtualCameraThreeOptions);
+    [attachTo](klipp: Klipp | null): void;
+    [prepare](width: number, height: number): void;
+    protected removePiece(piece: CameraPiece): void;
+    private releaseSlots;
+    private syncSlot;
+    private syncGroupSlots;
+    private releaseGroupSlots;
+}