@pmndrs/klipp 0.0.0-stage → 0.14.0

package/dist/input-sources/touch.d.ts

@@ -0,0 +1,47 @@
+import { type Vec2 } from 'math';
+import { type InteractiveArea } from './isInsideInteractiveArea.js';
+export type FingerCount = 'one' | 'two' | 'three';
+/** Up to three fingers: their movement per finger count, and two-finger pinch and twist, summed per frame. */
+export type TouchState = {
+    /** Fingers down, up to three. */
+    fingers: number;
+    /** Movement this frame of the fingers' center, by how many were down at the time, in pixels. */
+    readonly drag: Record<FingerCount, Vec2>;
+    /** Two-finger pinch this frame, as the change in `ln(scale)`. Spreading is positive. */
+    pinchDelta: number;
+    /** Two-finger rotation this frame, in radians. */
+    twistDelta: number;
+    /** Only touches that start inside this normalized region count. */
+    interactiveArea: InteractiveArea | null;
+    /** Each two-finger gesture keeps only the stronger of pinch and twist. */
+    lockTouchAxis: boolean;
+    /** Internal. */
+    pending: TouchPending;
+};
+type Finger = {
+    id: number;
+    x: number;
+    y: number;
+};
+type TouchPending = {
+    drag: Record<FingerCount, Vec2>;
+    pinchDelta: number;
+    twistDelta: number;
+    /** The first `count` are down, in the order they touched. */
+    slots: [Finger, Finger, Finger];
+    count: number;
+    /** Two-finger gesture, measured from when the current pair formed. */
+    distance: number;
+    angle: number;
+    startDistance: number;
+    twistTotal: number;
+    axisLock: 'pinch' | 'twist' | null;
+};
+/** Which of pinch and twist a two-finger gesture mostly is so far, or `null` while it is even. */
+export declare function dominantGesture(scaleFraction: number, twistDegrees: number): 'pinch' | 'twist' | null;
+export declare const create: () => TouchState;
+/** Listens to `element`'s touches. Returns a function that stops. */
+export declare function connect(state: TouchState, element: HTMLElement, onInput?: () => void): () => void;
+/** Starts a new frame: the input gathered since the last call becomes this frame's. */
+export declare function update(state: TouchState): void;
+export {};

package/dist/input-sources/touch.js

@@ -0,0 +1,173 @@
+import { isInsideInteractiveArea } from "./isInsideInteractiveArea.js";
+import { suppressNativeGestures } from "./suppressNativeGestures.js";
+import { deltaAngle, radiansToDegrees } from "math";
+//#region src/input-sources/touch.ts
+/** How many degrees of twist weigh as much as doubling the pinch distance, when choosing one. */
+var SCALE_ANGLE_RATIO_INTENT_DEG = 30;
+/** Which of pinch and twist a two-finger gesture mostly is so far, or `null` while it is even. */
+function dominantGesture(scaleFraction, twistDegrees) {
+	const intent = Math.abs(scaleFraction) * SCALE_ANGLE_RATIO_INTENT_DEG - Math.abs(twistDegrees);
+	return intent < 0 ? "twist" : intent > 0 ? "pinch" : null;
+}
+var create = () => ({
+	fingers: 0,
+	drag: {
+		one: [0, 0],
+		two: [0, 0],
+		three: [0, 0]
+	},
+	pinchDelta: 0,
+	twistDelta: 0,
+	interactiveArea: null,
+	lockTouchAxis: false,
+	pending: {
+		drag: {
+			one: [0, 0],
+			two: [0, 0],
+			three: [0, 0]
+		},
+		pinchDelta: 0,
+		twistDelta: 0,
+		slots: [
+			{
+				id: 0,
+				x: 0,
+				y: 0
+			},
+			{
+				id: 0,
+				x: 0,
+				y: 0
+			},
+			{
+				id: 0,
+				x: 0,
+				y: 0
+			}
+		],
+		count: 0,
+		distance: 0,
+		angle: 0,
+		startDistance: 0,
+		twistTotal: 0,
+		axisLock: null
+	}
+});
+function indexOf(pending, id) {
+	for (let i = 0; i < pending.count; i++) if (pending.slots[i].id === id) return i;
+	return -1;
+}
+/** Starts a fresh two-finger gesture from where the first two fingers are now. */
+function resetPair(pending) {
+	if (pending.count < 2) return;
+	const [a, b] = pending.slots;
+	pending.distance = Math.hypot(b.x - a.x, b.y - a.y);
+	pending.angle = Math.atan2(b.y - a.y, b.x - a.x);
+	pending.startDistance = pending.distance;
+	pending.twistTotal = 0;
+	pending.axisLock = null;
+}
+function moveCenter(drag, count, moving, x, y) {
+	drag[0] += (x - moving.x) / count;
+	drag[1] += (y - moving.y) / count;
+	moving.x = x;
+	moving.y = y;
+}
+function movePair(state, moving, x, y) {
+	const pending = state.pending;
+	moveCenter(pending.drag.two, 2, moving, x, y);
+	const [a, b] = pending.slots;
+	const distance = Math.hypot(b.x - a.x, b.y - a.y);
+	const pinchStep = distance > 0 && pending.distance > 0 ? Math.log(distance / pending.distance) : 0;
+	pending.distance = distance;
+	const angle = Math.atan2(b.y - a.y, b.x - a.x);
+	const twistStep = deltaAngle(pending.angle, angle);
+	pending.angle = angle;
+	pending.twistTotal += twistStep;
+	if (state.lockTouchAxis && !pending.axisLock) pending.axisLock = dominantGesture(distance / pending.startDistance - 1, radiansToDegrees(pending.twistTotal));
+	if (pending.axisLock !== "twist") pending.pinchDelta += pinchStep;
+	if (pending.axisLock !== "pinch") pending.twistDelta += twistStep;
+}
+/** Listens to `element`'s touches. Returns a function that stops. */
+function connect(state, element, onInput) {
+	const pending = state.pending;
+	const onPointerDown = (event) => {
+		if (event.pointerType !== "touch") return;
+		if (!isInsideInteractiveArea(element, state.interactiveArea, event.clientX, event.clientY)) return;
+		if (pending.count === 3 || indexOf(pending, event.pointerId) !== -1) return;
+		const finger = pending.slots[pending.count++];
+		finger.id = event.pointerId;
+		finger.x = event.clientX;
+		finger.y = event.clientY;
+		if (pending.count === 2) resetPair(pending);
+		try {
+			element.setPointerCapture(event.pointerId);
+		} catch {}
+		onInput?.();
+	};
+	const onPointerMove = (event) => {
+		if (event.pointerType !== "touch") return;
+		const index = indexOf(pending, event.pointerId);
+		if (index === -1) return;
+		const moving = pending.slots[index];
+		if (pending.count === 3) moveCenter(pending.drag.three, 3, moving, event.clientX, event.clientY);
+		else if (pending.count === 2) movePair(state, moving, event.clientX, event.clientY);
+		else moveCenter(pending.drag.one, 1, moving, event.clientX, event.clientY);
+		onInput?.();
+	};
+	const onPointerUp = (event) => {
+		if (event.pointerType !== "touch") return;
+		const index = indexOf(pending, event.pointerId);
+		if (index === -1) return;
+		const lifted = pending.slots[index];
+		for (let i = index; i < pending.count - 1; i++) pending.slots[i] = pending.slots[i + 1];
+		pending.slots[--pending.count] = lifted;
+		resetPair(pending);
+		onInput?.();
+	};
+	const liftAll = () => {
+		pending.count = 0;
+	};
+	const onVisibilityChange = () => {
+		if (document.hidden) liftAll();
+	};
+	const restoreStyles = suppressNativeGestures(element);
+	element.addEventListener("pointerdown", onPointerDown);
+	element.addEventListener("pointermove", onPointerMove);
+	element.addEventListener("pointerup", onPointerUp);
+	element.addEventListener("pointercancel", onPointerUp);
+	element.addEventListener("lostpointercapture", onPointerUp);
+	document.addEventListener("visibilitychange", onVisibilityChange);
+	window.addEventListener("blur", liftAll);
+	return () => {
+		restoreStyles();
+		element.removeEventListener("pointerdown", onPointerDown);
+		element.removeEventListener("pointermove", onPointerMove);
+		element.removeEventListener("pointerup", onPointerUp);
+		element.removeEventListener("pointercancel", onPointerUp);
+		element.removeEventListener("lostpointercapture", onPointerUp);
+		document.removeEventListener("visibilitychange", onVisibilityChange);
+		window.removeEventListener("blur", liftAll);
+		liftAll();
+	};
+}
+var copyAndZero = (out, source) => {
+	out[0] = source[0];
+	out[1] = source[1];
+	source[0] = 0;
+	source[1] = 0;
+};
+/** Starts a new frame: the input gathered since the last call becomes this frame's. */
+function update(state) {
+	const pending = state.pending;
+	state.fingers = pending.count;
+	copyAndZero(state.drag.one, pending.drag.one);
+	copyAndZero(state.drag.two, pending.drag.two);
+	copyAndZero(state.drag.three, pending.drag.three);
+	state.pinchDelta = pending.pinchDelta;
+	state.twistDelta = pending.twistDelta;
+	pending.pinchDelta = 0;
+	pending.twistDelta = 0;
+}
+//#endregion
+export { connect, create, dominantGesture, update };

package/dist/input-sources/wheel.d.ts

@@ -0,0 +1,28 @@
+import { type InteractiveArea } from './isInsideInteractiveArea.js';
+/** Wheel and trackpad scrolling, in pixels, summed per frame. */
+export type WheelState = {
+    /** Scroll since the last `update`. */
+    deltaX: number;
+    deltaY: number;
+    /** Trackpad pinch since the last `update`, as the change in `ln(scale)`. Spreading is positive. */
+    pinchDelta: number;
+    /** Only scrolls that start inside this normalized region count. */
+    interactiveArea: InteractiveArea | null;
+    /** Keep the page from scrolling under the element. */
+    preventPageScroll: boolean;
+    /** Keep a trackpad pinch from zooming the page. */
+    preventPageZoom: boolean;
+    /** Pixels per line, for wheels that report lines. */
+    pixelsPerLine: number;
+    /** Pixels per page, for wheels that report pages. */
+    pixelsPerPage: number;
+    /** Internal. */
+    pendingX: number;
+    pendingY: number;
+    pendingPinch: number;
+};
+export declare const create: () => WheelState;
+/** Listens to `element`'s wheel. Returns a function that stops. */
+export declare function connect(state: WheelState, element: HTMLElement, onInput?: () => void): () => void;
+/** Starts a new frame: the scroll gathered since the last call becomes this frame's. */
+export declare function update(state: WheelState): void;

package/dist/input-sources/wheel.js

@@ -0,0 +1,44 @@
+import { isInsideInteractiveArea } from "./isInsideInteractiveArea.js";
+//#region src/input-sources/wheel.ts
+var create = () => ({
+	deltaX: 0,
+	deltaY: 0,
+	pinchDelta: 0,
+	interactiveArea: null,
+	preventPageScroll: true,
+	preventPageZoom: true,
+	pixelsPerLine: 33,
+	pixelsPerPage: 800,
+	pendingX: 0,
+	pendingY: 0,
+	pendingPinch: 0
+});
+var pixelsPerUnit = (state, deltaMode) => deltaMode === WheelEvent.DOM_DELTA_LINE ? state.pixelsPerLine : deltaMode === WheelEvent.DOM_DELTA_PAGE ? state.pixelsPerPage : 1;
+/** Listens to `element`'s wheel. Returns a function that stops. */
+function connect(state, element, onInput) {
+	const onWheel = (event) => {
+		if (!isInsideInteractiveArea(element, state.interactiveArea, event.clientX, event.clientY)) return;
+		if (event.ctrlKey ? state.preventPageZoom : state.preventPageScroll) event.preventDefault();
+		const scale = pixelsPerUnit(state, event.deltaMode);
+		if (event.ctrlKey) state.pendingPinch -= event.deltaY * scale / 100;
+		else if (event.shiftKey && event.deltaX === 0) state.pendingX += event.deltaY * scale;
+		else {
+			state.pendingX += event.deltaX * scale;
+			state.pendingY += event.deltaY * scale;
+		}
+		onInput?.();
+	};
+	element.addEventListener("wheel", onWheel, { passive: false });
+	return () => element.removeEventListener("wheel", onWheel);
+}
+/** Starts a new frame: the scroll gathered since the last call becomes this frame's. */
+function update(state) {
+	state.deltaX = state.pendingX;
+	state.deltaY = state.pendingY;
+	state.pinchDelta = state.pendingPinch;
+	state.pendingX = 0;
+	state.pendingY = 0;
+	state.pendingPinch = 0;
+}
+//#endregion
+export { connect, create, update };

package/dist/react/CameraFrustumHelper.d.ts

@@ -0,0 +1,13 @@
+import { type Ref } from 'react';
+import { type CameraHelper, type ColorRepresentation } from 'three';
+export type CameraFrustumHelperProps = {
+    /** Single color for the whole helper. */
+    color?: ColorRepresentation;
+    /** Maximum distance drawn for the frustum. */
+    maxDistance?: number;
+    /** Whether to hide the helper while its camera is live. */
+    hideWhenLive?: boolean;
+    ref?: Ref<CameraHelper>;
+};
+/** Debug helper that draws the current virtual camera frustum. */
+export declare function CameraFrustumHelper({ color, maxDistance, hideWhenLive, ref, }?: CameraFrustumHelperProps): import("react").JSX.Element | null;

package/dist/react/CameraFrustumHelper.js

@@ -0,0 +1,32 @@
+import { CameraFrustumHelperThree } from "../three/CameraFrustumHelperThree.js";
+import { useIsLiveVirtualCamera, useVirtualCamera } from "./VirtualCameraContext.js";
+import { Color } from "three";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useImperativeHandle, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/CameraFrustumHelper.tsx
+/** Debug helper that draws the current virtual camera frustum. */
+function CameraFrustumHelper({ color, maxDistance = 1, hideWhenLive = true, ref } = {}) {
+	const { state } = useVirtualCamera();
+	const isLive = useIsLiveVirtualCamera();
+	const size = useThree((s) => s.size);
+	const [helper] = useState(() => new CameraFrustumHelperThree(maxDistance));
+	const [scratchColor] = useState(() => new Color());
+	helper.maxDistance = maxDistance;
+	useImperativeHandle(ref, () => helper, [helper]);
+	useEffect(() => () => helper.dispose(), [helper]);
+	useEffect(() => {
+		if (color === void 0) return;
+		scratchColor.set(color);
+		helper.setColors(scratchColor, scratchColor, scratchColor, scratchColor, scratchColor);
+	}, [
+		helper,
+		scratchColor,
+		color
+	]);
+	useFrame(() => helper.sync(state, size.width / size.height));
+	if (hideWhenLive && isLive) return null;
+	return /* @__PURE__ */ jsx("primitive", { object: helper });
+}
+//#endregion
+export { CameraFrustumHelper };

package/dist/react/DebugZoneOverlay.d.ts

@@ -0,0 +1,7 @@
+import { type DebugZone } from '../dom/DebugOverlay.js';
+export type { DebugZone };
+/** Renders debug zones and an optional crosshair while this camera is the active one. */
+export declare function DebugZoneOverlay({ zones, crosshair }: {
+    zones: DebugZone[];
+    crosshair?: [number, number];
+}): null;

package/dist/react/DebugZoneOverlay.js

@@ -0,0 +1,23 @@
+import { useIsActiveVirtualCamera } from "./VirtualCameraContext.js";
+import { DebugOverlay } from "../dom/DebugOverlay.js";
+import { useThree } from "@react-three/fiber";
+import { useEffect, useState } from "react";
+//#region src/react/DebugZoneOverlay.tsx
+/** Renders debug zones and an optional crosshair while this camera is the active one. */
+function DebugZoneOverlay({ zones, crosshair }) {
+	const isActive = useIsActiveVirtualCamera();
+	const container = useThree((state) => state.gl.domElement.parentElement);
+	const [overlay] = useState(() => new DebugOverlay());
+	useEffect(() => {
+		if (!container) return;
+		overlay.connect(container);
+		return overlay.disconnect;
+	}, [container, overlay]);
+	useEffect(() => {
+		if (isActive) overlay.render(zones, crosshair);
+		else overlay.render([]);
+	});
+	return null;
+}
+//#endregion
+export { DebugZoneOverlay };

package/dist/react/Klipp.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from 'react';
+import type { Camera } from 'three';
+import type { KlippOptions } from '../core/Klipp.js';
+import { type KlippMode } from '../three/KlippThree.js';
+import { type CameraTransitionEventProps } from './useCameraTransitionEvent.js';
+export type { KlippMode };
+export type KlippProps = Pick<KlippOptions, 'defaultBlend' | 'customBlends'> & {
+    children?: ReactNode;
+    camera?: Camera;
+    /** See `KlippMode`. */
+    mode?: KlippMode;
+};
+/** Provides the camera driver and writes its output to the active camera. */
+export declare function Klipp({ children, defaultBlend, customBlends, camera: cameraProp, mode }: KlippProps): import("react").JSX.Element;
+export declare namespace Klipp {
+    export { KlippEvents as Events };
+}
+export type KlippEventsProps = CameraTransitionEventProps;
+/** Listen to transitions from every camera in the nearest `<Klipp>`. */
+export declare function KlippEvents({ onActivated, onDeactivated, onBlendCreated, onBlendFinished, onCut }: KlippEventsProps): null;

package/dist/react/Klipp.js

@@ -0,0 +1,47 @@
+import { KlippThree } from "../three/KlippThree.js";
+import { KlippContext, useKlipp } from "./KlippContext.js";
+import { useCameraTransitionEvent } from "./useCameraTransitionEvent.js";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/Klipp.tsx
+/** Bound `dt` under `frameloop="demand"` so an idle gap does not jump the blend forward in one frame. */
+var DEMAND_MODE_MAX_DELTA = 1 / 30;
+/** Provides the camera driver and writes its output to the active camera. */
+function Klipp({ children, defaultBlend, customBlends, camera: cameraProp, mode = "enabled" }) {
+	const defaultCamera = useThree((state) => state.camera);
+	const size = useThree((state) => state.size);
+	const invalidate = useThree((state) => state.invalidate);
+	const camera = cameraProp ?? defaultCamera;
+	const [klipp] = useState(() => new KlippThree(camera, {
+		defaultBlend,
+		customBlends
+	}));
+	klipp.camera = camera;
+	klipp.mode = mode;
+	klipp.setSize(size.width, size.height);
+	useEffect(() => klipp.setDefaultBlend(defaultBlend), [klipp, defaultBlend]);
+	useEffect(() => klipp.setCustomBlends(customBlends), [klipp, customBlends]);
+	useEffect(() => invalidate(), [mode, invalidate]);
+	useFrame((state, rawDelta) => {
+		const delta = state.frameloop === "demand" ? Math.min(rawDelta, DEMAND_MODE_MAX_DELTA) : rawDelta;
+		if (klipp.update(delta)) state.invalidate();
+	});
+	return /* @__PURE__ */ jsx(KlippContext.Provider, {
+		value: klipp,
+		children
+	});
+}
+/** Listen to transitions from every camera in the nearest `<Klipp>`. */
+function KlippEvents({ onActivated, onDeactivated, onBlendCreated, onBlendFinished, onCut }) {
+	const klipp = useKlipp();
+	useCameraTransitionEvent(klipp, "activated", onActivated);
+	useCameraTransitionEvent(klipp, "deactivated", onDeactivated);
+	useCameraTransitionEvent(klipp, "blendCreated", onBlendCreated);
+	useCameraTransitionEvent(klipp, "blendFinished", onBlendFinished);
+	useCameraTransitionEvent(klipp, "cut", onCut);
+	return null;
+}
+Klipp.Events = KlippEvents;
+//#endregion
+export { Klipp, KlippEvents };

package/dist/react/KlippContext.d.ts

@@ -0,0 +1,5 @@
+import type { KlippThree } from '../three/KlippThree.js';
+export type { FrameUpdate } from '../three/KlippThree.js';
+export declare const KlippContext: import("react").Context<KlippThree | null>;
+/** The nearest `<Klipp>`'s `KlippThree`, which picks the camera and knows about every one. */
+export declare function useKlipp(): KlippThree;

package/dist/react/KlippContext.js

@@ -0,0 +1,11 @@
+import { createContext, use } from "react";
+//#region src/react/KlippContext.ts
+var KlippContext = createContext(null);
+/** The nearest `<Klipp>`'s `KlippThree`, which picks the camera and knows about every one. */
+function useKlipp() {
+	const value = use(KlippContext);
+	if (!value) throw new Error("useKlipp must be used within a <Klipp> provider.");
+	return value;
+}
+//#endregion
+export { KlippContext, useKlipp };

package/dist/react/VirtualCamera.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode, type Ref } from 'react';
+import { BlendHints } from '../core/blend/BlendHints.js';
+import type { StandbyUpdate } from '../core/VirtualCamera.js';
+import { VirtualCameraThree } from '../three/VirtualCameraThree.js';
+import { type CameraTransitionEventProps } from './useCameraTransitionEvent.js';
+import { type InitialCameraState } from './VirtualCameraContext.js';
+export type VirtualCameraProps = {
+    name: string;
+    priority: number;
+    /** Whether this camera participates in arbitration and updates. */
+    active?: boolean;
+    /** Blend hints for transitions involving this camera. */
+    hints?: BlendHints;
+    /** Initial pose applied once when the camera mounts. */
+    initialState?: InitialCameraState;
+    /** How this camera updates while another one is on screen. */
+    standbyUpdate?: StandbyUpdate;
+    children?: ReactNode;
+    ref?: Ref<VirtualCameraThree>;
+};
+/** Registers a virtual camera with the nearest `<Klipp>`. */
+export declare function VirtualCamera({ name, priority, active, hints, initialState, standbyUpdate, children, ref, }: VirtualCameraProps): import("react").JSX.Element;
+export declare namespace VirtualCamera {
+    export { VirtualCameraEvents as Events };
+}
+export type VirtualCameraEventsProps = CameraTransitionEventProps;
+/** Listen to transition events from the nearest virtual camera. */
+export declare function VirtualCameraEvents({ onActivated, onDeactivated, onBlendCreated, onBlendFinished, onCut, }: VirtualCameraEventsProps): null;

package/dist/react/VirtualCamera.js

@@ -0,0 +1,81 @@
+import { BlendHints } from "../core/blend/BlendHints.js";
+import { VirtualCameraThree } from "../three/VirtualCameraThree.js";
+import { VirtualCameraActiveContext, VirtualCameraContext, VirtualCameraLiveContext, useVirtualCamera } from "./VirtualCameraContext.js";
+import { useKlipp } from "./KlippContext.js";
+import { useCameraTransitionEvent } from "./useCameraTransitionEvent.js";
+import { useThree } from "@react-three/fiber";
+import { useEffect, useImperativeHandle, useState, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/VirtualCamera.tsx
+/** Registers a virtual camera with the nearest `<Klipp>`. */
+function VirtualCamera({ name, priority, active = true, hints = BlendHints.none, initialState, standbyUpdate = "roundRobin", children, ref }) {
+	const klipp = useKlipp();
+	const invalidate = useThree((state) => state.invalidate);
+	const [camera] = useState(() => new VirtualCameraThree(name, {
+		priority,
+		active,
+		hints,
+		initialState
+	}));
+	camera.standbyUpdate = standbyUpdate;
+	useImperativeHandle(ref, () => camera, [camera]);
+	useEffect(() => {
+		camera.name = name;
+	}, [camera, name]);
+	useEffect(() => {
+		camera.priority = priority;
+		if (camera.active) invalidate();
+	}, [
+		camera,
+		priority,
+		invalidate
+	]);
+	useEffect(() => {
+		camera.hints = hints;
+	}, [camera, hints]);
+	useEffect(() => {
+		camera.active = active;
+		invalidate();
+	}, [
+		camera,
+		active,
+		invalidate
+	]);
+	useEffect(() => {
+		const remove = klipp.add(camera);
+		invalidate();
+		return () => {
+			remove();
+			invalidate();
+		};
+	}, [
+		klipp,
+		camera,
+		invalidate
+	]);
+	const isActive = useSyncExternalStore(klipp.subscribeActiveId, () => active && klipp.isActive(name));
+	const isLive = useSyncExternalStore(klipp.subscribeLiveId, () => active && klipp.isLive(name));
+	return /* @__PURE__ */ jsx(VirtualCameraContext.Provider, {
+		value: camera,
+		children: /* @__PURE__ */ jsx(VirtualCameraActiveContext.Provider, {
+			value: isActive,
+			children: /* @__PURE__ */ jsx(VirtualCameraLiveContext.Provider, {
+				value: isLive,
+				children
+			})
+		})
+	});
+}
+/** Listen to transition events from the nearest virtual camera. */
+function VirtualCameraEvents({ onActivated, onDeactivated, onBlendCreated, onBlendFinished, onCut }) {
+	const camera = useVirtualCamera();
+	useCameraTransitionEvent(camera, "activated", onActivated);
+	useCameraTransitionEvent(camera, "deactivated", onDeactivated);
+	useCameraTransitionEvent(camera, "blendCreated", onBlendCreated);
+	useCameraTransitionEvent(camera, "blendFinished", onBlendFinished);
+	useCameraTransitionEvent(camera, "cut", onCut);
+	return null;
+}
+VirtualCamera.Events = VirtualCameraEvents;
+//#endregion
+export { VirtualCamera, VirtualCameraEvents };

package/dist/react/VirtualCameraContext.d.ts

@@ -0,0 +1,11 @@
+import type { VirtualCameraThree } from '../three/VirtualCameraThree.js';
+export type { InitialCameraState } from '../three/VirtualCameraThree.js';
+export declare const VirtualCameraContext: import("react").Context<VirtualCameraThree | null>;
+export declare const VirtualCameraActiveContext: import("react").Context<boolean>;
+export declare const VirtualCameraLiveContext: import("react").Context<boolean>;
+/** The nearest `<VirtualCamera>`'s `VirtualCameraThree`, with its `state` and pieces. */
+export declare function useVirtualCamera(): VirtualCameraThree;
+/** Whether the nearest virtual camera currently wins priority. */
+export declare function useIsActiveVirtualCamera(): boolean;
+/** Whether the nearest virtual camera currently contributes to output. */
+export declare function useIsLiveVirtualCamera(): boolean;

package/dist/react/VirtualCameraContext.js

@@ -0,0 +1,21 @@
+import { createContext, use } from "react";
+//#region src/react/VirtualCameraContext.ts
+var VirtualCameraContext = createContext(null);
+var VirtualCameraActiveContext = createContext(false);
+var VirtualCameraLiveContext = createContext(false);
+/** The nearest `<VirtualCamera>`'s `VirtualCameraThree`, with its `state` and pieces. */
+function useVirtualCamera() {
+	const value = use(VirtualCameraContext);
+	if (!value) throw new Error("useVirtualCamera must be used within a <VirtualCamera>.");
+	return value;
+}
+/** Whether the nearest virtual camera currently wins priority. */
+function useIsActiveVirtualCamera() {
+	return use(VirtualCameraActiveContext);
+}
+/** Whether the nearest virtual camera currently contributes to output. */
+function useIsLiveVirtualCamera() {
+	return use(VirtualCameraLiveContext);
+}
+//#endregion
+export { VirtualCameraActiveContext, VirtualCameraContext, VirtualCameraLiveContext, useIsActiveVirtualCamera, useIsLiveVirtualCamera, useVirtualCamera };

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

@@ -0,0 +1,11 @@
+import { HardLookAt } from './HardLookAt.js';
+import { PanTilt } from './PanTilt.js';
+import { RotateWithFollowTarget } from './RotateWithFollowTarget.js';
+import { RotationComposer } from './RotationComposer.js';
+/** Aim components control a `<VirtualCamera>`'s rotation. Use at most one per camera. */
+export declare const Aim: {
+    HardLookAt: typeof HardLookAt;
+    RotateWithFollowTarget: typeof RotateWithFollowTarget;
+    RotationComposer: typeof RotationComposer;
+    PanTilt: typeof PanTilt;
+};

package/dist/react/aim/Aim.js

@@ -0,0 +1,14 @@
+import { HardLookAt } from "./HardLookAt.js";
+import { PanTilt } from "./PanTilt.js";
+import { RotateWithFollowTarget } from "./RotateWithFollowTarget.js";
+import { RotationComposer } from "./RotationComposer.js";
+//#region src/react/aim/Aim.ts
+/** Aim components control a `<VirtualCamera>`'s rotation. Use at most one per camera. */
+var Aim = {
+	HardLookAt,
+	RotateWithFollowTarget,
+	RotationComposer,
+	PanTilt
+};
+//#endregion
+export { Aim };

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

@@ -0,0 +1,10 @@
+import { type Ref } from 'react';
+import { HardLookAtAimThree } from '../../three/aim/HardLookAtAimThree.js';
+import type { Target } from '../../three/resolve/Target.js';
+export type HardLookAtProps = {
+    /** Target to look at. Unresolved targets are ignored. */
+    target?: Target;
+    ref?: Ref<HardLookAtAimThree>;
+};
+/** Thin wrapper around `HardLookAtAimThree`. */
+export declare function HardLookAt({ target, ref }: HardLookAtProps): null;

package/dist/react/aim/HardLookAt.js

@@ -0,0 +1,15 @@
+import { HardLookAtAimThree } from "../../three/aim/HardLookAtAimThree.js";
+import { useVirtualCamera } from "../VirtualCameraContext.js";
+import { useEffect, useImperativeHandle, useState } from "react";
+//#region src/react/aim/HardLookAt.tsx
+/** Thin wrapper around `HardLookAtAimThree`. */
+function HardLookAt({ target, ref }) {
+	const camera = useVirtualCamera();
+	const [aim] = useState(() => new HardLookAtAimThree(target));
+	aim.target = target;
+	useImperativeHandle(ref, () => aim, [aim]);
+	useEffect(() => camera.setAim(aim), [camera, aim]);
+	return null;
+}
+//#endregion
+export { HardLookAt };