@pmndrs/klipp 0.0.0-stage → 0.14.0

package/dist/three/camera.js

@@ -0,0 +1,39 @@
+import { vec3 } from "math";
+//#region src/three/camera.ts
+/** Read a perspective camera's transform and lens into `out`. */
+function copyCameraStateFromCamera(out, camera) {
+	camera.position.toArray(out.position);
+	camera.quaternion.toArray(out.quaternion);
+	out.fov = camera.fov;
+	out.near = camera.near;
+	out.far = camera.far;
+	out.viewOffset[0] = camera.view?.enabled ? -camera.view.offsetX / (camera.view.fullWidth / 2) : 0;
+	out.viewOffset[1] = camera.view?.enabled ? camera.view.offsetY / (camera.view.fullHeight / 2) : 0;
+	out.hasTarget = false;
+	out.hasLookAtTarget = false;
+	vec3.set(out.referenceUp, 0, 1, 0);
+	return out;
+}
+/** Write a camera state's position and rotation to a camera. */
+function writeCameraTransform(camera, state) {
+	camera.position.fromArray(state.position);
+	camera.quaternion.fromArray(state.quaternion);
+}
+/** Write a camera state's lens and view offset to a perspective camera. */
+function writeCameraLens(camera, state, viewportWidth, viewportHeight) {
+	camera.fov = state.fov;
+	camera.near = state.near;
+	camera.far = state.far;
+	if (state.viewOffset[0] !== 0 || state.viewOffset[1] !== 0) {
+		const offsetX = -state.viewOffset[0] * (viewportWidth / 2);
+		const offsetY = state.viewOffset[1] * (viewportHeight / 2);
+		camera.setViewOffset(viewportWidth, viewportHeight, offsetX, offsetY, viewportWidth, viewportHeight);
+	} else camera.clearViewOffset();
+}
+/** Apply a camera state to a perspective camera. */
+function applyCameraState(camera, state, viewportWidth, viewportHeight) {
+	writeCameraTransform(camera, state);
+	writeCameraLens(camera, state, viewportWidth, viewportHeight);
+}
+//#endregion
+export { applyCameraState, copyCameraStateFromCamera, writeCameraLens, writeCameraTransform };

package/dist/three/damping/Predictor.d.ts

@@ -0,0 +1,12 @@
+import type { Vector3 } from 'three';
+import * as predictor from '../../core/damping/predictor.js';
+/** Stateful wrapper over the predictor functions for three.js vectors. */
+export declare class Predictor {
+    readonly state: predictor.PredictorState;
+    /** Add a position sample and update the tracked velocity. */
+    addPosition(position: Vector3, dt: number, smoothing: number): void;
+    /** Write the predicted offset `time` seconds ahead into `out`. */
+    predictPositionDelta(out: Vector3, time: number): Vector3;
+    /** Clear the tracked velocity and position history. */
+    reset(): void;
+}

package/dist/three/damping/Predictor.js

@@ -0,0 +1,30 @@
+import { addPosition, create, predictDelta, reset } from "../../core/damping/predictor.js";
+//#region src/three/damping/Predictor.ts
+var scratchPosition = [
+	0,
+	0,
+	0
+];
+var scratchDelta = [
+	0,
+	0,
+	0
+];
+/** Stateful wrapper over the predictor functions for three.js vectors. */
+var Predictor = class {
+	state = create();
+	/** Add a position sample and update the tracked velocity. */
+	addPosition(position, dt, smoothing) {
+		addPosition(this.state, position.toArray(scratchPosition), dt, smoothing);
+	}
+	/** Write the predicted offset `time` seconds ahead into `out`. */
+	predictPositionDelta(out, time) {
+		return out.fromArray(predictDelta(scratchDelta, this.state, time));
+	}
+	/** Clear the tracked velocity and position history. */
+	reset() {
+		reset(this.state);
+	}
+};
+//#endregion
+export { Predictor };

package/dist/three/damping/QuaternionDamper.d.ts

@@ -0,0 +1,10 @@
+import type { Quaternion } from 'three';
+import * as damping from '../../core/damping/damping.js';
+import type { DampingConstant } from '../../core/damping/damping.js';
+/** Stateful wrapper over `dampQuaternion` for three.js quaternions. */
+export declare class QuaternionDamper {
+    readonly state: damping.DamperState;
+    update(out: Quaternion, target: Quaternion, dampingTime: DampingConstant, dt: number, maxSpeed?: number): Quaternion;
+    /** Reset the underlying angle spring. */
+    reset(): void;
+}

package/dist/three/damping/QuaternionDamper.js

@@ -0,0 +1,28 @@
+import { createState, dampQuaternion, reset } from "../../core/damping/damping.js";
+//#region src/three/damping/QuaternionDamper.ts
+var scratchOut = [
+	0,
+	0,
+	0,
+	1
+];
+var scratchTarget = [
+	0,
+	0,
+	0,
+	1
+];
+/** Stateful wrapper over `dampQuaternion` for three.js quaternions. */
+var QuaternionDamper = class {
+	state = createState();
+	update(out, target, dampingTime, dt, maxSpeed = Infinity) {
+		dampQuaternion(this.state, out.toArray(scratchOut), target.toArray(scratchTarget), dampingTime, dt, maxSpeed);
+		return out.fromArray(scratchOut);
+	}
+	/** Reset the underlying angle spring. */
+	reset() {
+		reset(this.state);
+	}
+};
+//#endregion
+export { QuaternionDamper };

package/dist/three/damping/Vector3Damper.d.ts

@@ -0,0 +1,10 @@
+import type { Vector3 } from 'three';
+import * as damping from '../../core/damping/damping.js';
+import type { DampingConstant } from '../../core/damping/damping.js';
+/** Stateful wrapper over `dampVector3` for three.js vectors. */
+export declare class Vector3Damper {
+    readonly state: damping.Vector3DamperState;
+    update(out: Vector3, target: Vector3, dampingTime: DampingConstant, dt: number, maxSpeed?: number): Vector3;
+    /** Reset all three component dampers. */
+    reset(): void;
+}

package/dist/three/damping/Vector3Damper.js

@@ -0,0 +1,26 @@
+import { createVector3State, dampVector3, resetVector3 } from "../../core/damping/damping.js";
+//#region src/three/damping/Vector3Damper.ts
+var scratchOut = [
+	0,
+	0,
+	0
+];
+var scratchTarget = [
+	0,
+	0,
+	0
+];
+/** Stateful wrapper over `dampVector3` for three.js vectors. */
+var Vector3Damper = class {
+	state = createVector3State();
+	update(out, target, dampingTime, dt, maxSpeed = Infinity) {
+		dampVector3(this.state, out.toArray(scratchOut), target.toArray(scratchTarget), dampingTime, dt, maxSpeed);
+		return out.fromArray(scratchOut);
+	}
+	/** Reset all three component dampers. */
+	reset() {
+		resetVector3(this.state);
+	}
+};
+//#endregion
+export { Vector3Damper };

package/dist/three/extension/GroupFramingExtensionThree.d.ts

@@ -0,0 +1,13 @@
+import type { GroupFramingFitMode, GroupFramingMode, GroupMember } from '../../core/extension/groupFraming.js';
+import { GroupFramingExtension, type GroupFramingOptions } from '../../core/extension/GroupFramingExtension.js';
+import type { TargetGroup } from './TargetGroup.js';
+export type { GroupFramingFitMode, GroupFramingMode, GroupFramingOptions };
+/** Keeps a `TargetGroup` of `Object3D`s, refs and points inside the camera frame. */
+export declare class GroupFramingExtensionThree extends GroupFramingExtension {
+    group: TargetGroup;
+    private forceSizeRecalculation;
+    constructor(group: TargetGroup, options?: GroupFramingOptions);
+    /** Re-measure member sizes on the next update. */
+    recalculateSize(): void;
+    protected readMembers(): readonly GroupMember[];
+}

package/dist/three/extension/GroupFramingExtensionThree.js

@@ -0,0 +1,23 @@
+import { GroupFramingExtension } from "../../core/extension/GroupFramingExtension.js";
+//#region src/three/extension/GroupFramingExtensionThree.ts
+/** Keeps a `TargetGroup` of `Object3D`s, refs and points inside the camera frame. */
+var GroupFramingExtensionThree = class extends GroupFramingExtension {
+	group;
+	forceSizeRecalculation = false;
+	constructor(group, options) {
+		super([], group.positionMode, options);
+		this.group = group;
+	}
+	/** Re-measure member sizes on the next update. */
+	recalculateSize() {
+		this.forceSizeRecalculation = true;
+	}
+	readMembers() {
+		this.positionMode = this.group.positionMode;
+		const members = this.group.resolveMembers(this.forceSizeRecalculation);
+		this.forceSizeRecalculation = false;
+		return members;
+	}
+};
+//#endregion
+export { GroupFramingExtensionThree };

package/dist/three/extension/TargetGroup.d.ts

@@ -0,0 +1,32 @@
+import { Vector3 } from 'three';
+import type { GroupMember, GroupPositionMode } from '../../core/extension/groupFraming.js';
+import type { Vector3Like } from '../resolve/resolveVector3.js';
+import { type Target } from '../resolve/Target.js';
+import type { TargetSlot } from '../resolve/TargetRegistry.js';
+export type TargetGroupMember = {
+    target: Target;
+    /** Position weight used by `groupAverage`. */
+    weight?: number;
+    /** Bounding-sphere radius. Ignored when `size` is set. */
+    radius?: number;
+    /** Bounding-box dimensions. Takes priority over `radius`. */
+    size?: Vector3Like;
+};
+/** Strategy used to compute the group's position. */
+export type TargetGroupPositionMode = GroupPositionMode;
+/** Combines multiple targets into one position and bound. */
+export declare class TargetGroup {
+    members: TargetGroupMember[];
+    positionMode: TargetGroupPositionMode;
+    /** Registry slots by member target; members without one are resolved directly. */
+    memberSlots: ReadonlyMap<Target, TargetSlot>;
+    private readonly resolved;
+    constructor(members?: TargetGroupMember[], positionMode?: TargetGroupPositionMode);
+    slotOf: (member: TargetGroupMember) => TargetSlot | null;
+    /** Resolve a member's dimensions. */
+    resolveMemberSize: (outSize: Vector3, member: TargetGroupMember, dynamicSize?: boolean) => boolean;
+    /** Resolve every member's position and extent for this frame, as plain data for the core. */
+    resolveMembers: (dynamicSize?: boolean) => readonly GroupMember[];
+    /** Write the group position and return a conservative enclosing radius. */
+    computeBounds: (outPosition: Vector3, dynamicSize?: boolean) => number;
+}

package/dist/three/extension/TargetGroup.js

@@ -0,0 +1,53 @@
+import { computeBounds, createMember } from "../../core/extension/groupFraming.js";
+import { resolveTargetPosition, resolveTargetSize } from "../resolve/Target.js";
+import { readTargetExtent } from "../readTargetExtent.js";
+import { Vector3 } from "three";
+//#region src/three/extension/TargetGroup.ts
+var scratchPosition = new Vector3();
+var scratchCenter = [
+	0,
+	0,
+	0
+];
+var noSlots = /* @__PURE__ */ new Map();
+/** Combines multiple targets into one position and bound. */
+var TargetGroup = class {
+	members;
+	positionMode;
+	/** Registry slots by member target; members without one are resolved directly. */
+	memberSlots = noSlots;
+	resolved = [];
+	constructor(members = [], positionMode = "groupCenter") {
+		this.members = members;
+		this.positionMode = positionMode;
+	}
+	slotOf = (member) => this.memberSlots.get(member.target) ?? null;
+	/** Resolve a member's dimensions. */
+	resolveMemberSize = (outSize, member, dynamicSize = false) => resolveTargetSize(outSize, member.target, member.size, member.radius, dynamicSize, this.slotOf(member));
+	/** Resolve every member's position and extent for this frame, as plain data for the core. */
+	resolveMembers = (dynamicSize = false) => {
+		const count = this.members.length;
+		while (this.resolved.length < count) this.resolved.push(createMember());
+		this.resolved.length = count;
+		for (let i = 0; i < count; i++) {
+			const member = this.members[i];
+			const out = this.resolved[i];
+			const slot = this.slotOf(member);
+			out.weight = member.weight ?? 1;
+			out.resolved = resolveTargetPosition(scratchPosition, member.target, slot);
+			if (!out.resolved) continue;
+			scratchPosition.toArray(out.position);
+			readTargetExtent(out.extent, member.target, member.size, member.radius, dynamicSize, slot);
+		}
+		return this.resolved;
+	};
+	/** Write the group position and return a conservative enclosing radius. */
+	computeBounds = (outPosition, dynamicSize = false) => {
+		const radius = computeBounds(scratchCenter, this.resolveMembers(dynamicSize), this.positionMode);
+		if (radius < 0) return 0;
+		outPosition.fromArray(scratchCenter);
+		return radius;
+	};
+};
+//#endregion
+export { TargetGroup };

package/dist/three/index.d.ts

@@ -0,0 +1,24 @@
+export { applyCameraState, copyCameraStateFromCamera, writeCameraLens, writeCameraTransform } from './camera.js';
+export { CameraFrustumHelperThree } from './CameraFrustumHelperThree.js';
+export { KlippThree, type FrameUpdate, type KlippMode, type KlippThreeOptions } from './KlippThree.js';
+export { readTargetExtent } from './readTargetExtent.js';
+export { readTargetPose, readTargetRotation } from './readTargetPose.js';
+export { isVector3Like, resolveVec3, resolveVector3, type Vector3Like } from './resolve/resolveVector3.js';
+export { resolveTargetPosition, resolveTargetRotation, resolveTargetSize, type RefLike, type Target, } from './resolve/Target.js';
+export { TargetRegistry, type RegisteredTarget, type TargetSlot } from './resolve/TargetRegistry.js';
+export { VirtualCameraThree, type CameraPiece, type InitialCameraState, type VirtualCameraThreeOptions, } from './VirtualCameraThree.js';
+export { Predictor } from './damping/Predictor.js';
+export { QuaternionDamper } from './damping/QuaternionDamper.js';
+export { Vector3Damper } from './damping/Vector3Damper.js';
+export { FollowBodyThree, type FollowThreeOptions } from './body/FollowBodyThree.js';
+export { HardLockToTargetBodyThree, type HardLockToTargetOptions } from './body/HardLockToTargetBodyThree.js';
+export { OrbitFollowBodyThree, type OrbitFollowThreeOptions } from './body/OrbitFollowBodyThree.js';
+export { OrbitFollowHelperThree } from './body/OrbitFollowHelperThree.js';
+export { PositionComposerBodyThree, type PositionComposerThreeOptions } from './body/PositionComposerBodyThree.js';
+export { HardLookAtAimThree } from './aim/HardLookAtAimThree.js';
+export { PanTiltAimThree } from './aim/PanTiltAimThree.js';
+export { RotateWithFollowTargetAimThree, type RotateWithFollowTargetOptions, } from './aim/RotateWithFollowTargetAimThree.js';
+export { RotationComposerAimThree, type RotationComposerThreeOptions } from './aim/RotationComposerAimThree.js';
+export { GroupFramingExtensionThree, type GroupFramingFitMode, type GroupFramingMode, type GroupFramingOptions, } from './extension/GroupFramingExtensionThree.js';
+export { TargetGroup, type TargetGroupMember, type TargetGroupPositionMode } from './extension/TargetGroup.js';
+export { BasicMultiChannelPerlinNoiseThree, type PerlinNoiseThreeOptions, } from './noise/BasicMultiChannelPerlinNoiseThree.js';

package/dist/three/index.js

@@ -0,0 +1,25 @@
+import { applyCameraState, copyCameraStateFromCamera, writeCameraLens, writeCameraTransform } from "./camera.js";
+import { CameraFrustumHelperThree } from "./CameraFrustumHelperThree.js";
+import { isVector3Like, resolveVec3, resolveVector3 } from "./resolve/resolveVector3.js";
+import { resolveTargetPosition, resolveTargetRotation, resolveTargetSize } from "./resolve/Target.js";
+import { readTargetExtent } from "./readTargetExtent.js";
+import { TargetGroup } from "./extension/TargetGroup.js";
+import { VirtualCameraThree } from "./VirtualCameraThree.js";
+import { TargetRegistry } from "./resolve/TargetRegistry.js";
+import { KlippThree } from "./KlippThree.js";
+import { readTargetPose, readTargetRotation } from "./readTargetPose.js";
+import { Predictor } from "./damping/Predictor.js";
+import { QuaternionDamper } from "./damping/QuaternionDamper.js";
+import { Vector3Damper } from "./damping/Vector3Damper.js";
+import { FollowBodyThree } from "./body/FollowBodyThree.js";
+import { HardLockToTargetBodyThree } from "./body/HardLockToTargetBodyThree.js";
+import { OrbitFollowBodyThree } from "./body/OrbitFollowBodyThree.js";
+import { OrbitFollowHelperThree } from "./body/OrbitFollowHelperThree.js";
+import { PositionComposerBodyThree } from "./body/PositionComposerBodyThree.js";
+import { HardLookAtAimThree } from "./aim/HardLookAtAimThree.js";
+import { PanTiltAimThree } from "./aim/PanTiltAimThree.js";
+import { RotateWithFollowTargetAimThree } from "./aim/RotateWithFollowTargetAimThree.js";
+import { RotationComposerAimThree } from "./aim/RotationComposerAimThree.js";
+import { GroupFramingExtensionThree } from "./extension/GroupFramingExtensionThree.js";
+import { BasicMultiChannelPerlinNoiseThree } from "./noise/BasicMultiChannelPerlinNoiseThree.js";
+export { BasicMultiChannelPerlinNoiseThree, CameraFrustumHelperThree, FollowBodyThree, GroupFramingExtensionThree, HardLockToTargetBodyThree, HardLookAtAimThree, KlippThree, OrbitFollowBodyThree, OrbitFollowHelperThree, PanTiltAimThree, PositionComposerBodyThree, Predictor, QuaternionDamper, RotateWithFollowTargetAimThree, RotationComposerAimThree, TargetGroup, TargetRegistry, Vector3Damper, VirtualCameraThree, applyCameraState, copyCameraStateFromCamera, isVector3Like, readTargetExtent, readTargetPose, readTargetRotation, resolveTargetPosition, resolveTargetRotation, resolveTargetSize, resolveVec3, resolveVector3, writeCameraLens, writeCameraTransform };

package/dist/three/noise/BasicMultiChannelPerlinNoiseThree.d.ts

@@ -0,0 +1,16 @@
+import { BasicMultiChannelPerlinNoise, type PerlinNoiseOptions as PerlinNoiseCoreOptions } from '../../core/noise/BasicMultiChannelPerlinNoise.js';
+import { type Vector3Like } from '../resolve/resolveVector3.js';
+export type PerlinNoiseThreeOptions = Omit<PerlinNoiseCoreOptions, 'positionAmplitude' | 'positionFrequency' | 'rotationAmplitude' | 'rotationFrequency'> & {
+    /** Per-axis positional shake amplitude in camera-local space. */
+    positionAmplitude?: Vector3Like;
+    /** Per-axis oscillation speed for position noise. */
+    positionFrequency?: Vector3Like;
+    /** Per-axis rotational shake amplitude in degrees. */
+    rotationAmplitude?: Vector3Like;
+    /** Per-axis oscillation speed for rotation noise. */
+    rotationFrequency?: Vector3Like;
+};
+/** `BasicMultiChannelPerlinNoise` taking three.js vectors in its options. */
+export declare class BasicMultiChannelPerlinNoiseThree extends BasicMultiChannelPerlinNoise {
+    constructor({ positionAmplitude, positionFrequency, rotationAmplitude, rotationFrequency, ...options }?: PerlinNoiseThreeOptions);
+}

package/dist/three/noise/BasicMultiChannelPerlinNoiseThree.js

@@ -0,0 +1,17 @@
+import { BasicMultiChannelPerlinNoise } from "../../core/noise/BasicMultiChannelPerlinNoise.js";
+import { optionalVec3 } from "../resolve/resolveVector3.js";
+//#region src/three/noise/BasicMultiChannelPerlinNoiseThree.ts
+/** `BasicMultiChannelPerlinNoise` taking three.js vectors in its options. */
+var BasicMultiChannelPerlinNoiseThree = class extends BasicMultiChannelPerlinNoise {
+	constructor({ positionAmplitude, positionFrequency, rotationAmplitude, rotationFrequency, ...options } = {}) {
+		super({
+			...options,
+			positionAmplitude: optionalVec3(positionAmplitude),
+			positionFrequency: optionalVec3(positionFrequency),
+			rotationAmplitude: optionalVec3(rotationAmplitude),
+			rotationFrequency: optionalVec3(rotationFrequency)
+		});
+	}
+};
+//#endregion
+export { BasicMultiChannelPerlinNoiseThree };

package/dist/three/readTargetExtent.d.ts

@@ -0,0 +1,9 @@
+import type { TargetExtent } from '../core/TargetExtent.js';
+import type { Vector3Like } from './resolve/resolveVector3.js';
+import { type Target } from './resolve/Target.js';
+import type { TargetSlot } from './resolve/TargetRegistry.js';
+/**
+ * Resolve how far a target reaches: an explicit `size`, else `radius`, else its geometry's bounds.
+ * `dynamicSize` re-measures geometry instead of using the cached bounding box.
+ */
+export declare function readTargetExtent(out: TargetExtent, target: Target, size: Vector3Like | undefined, radius: number | undefined, dynamicSize: boolean, slot: TargetSlot | null): TargetExtent;

package/dist/three/readTargetExtent.js

@@ -0,0 +1,25 @@
+import { resolveTargetRotation, resolveTargetSize } from "./resolve/Target.js";
+import { Quaternion, Vector3 } from "three";
+//#region src/three/readTargetExtent.ts
+var scratchSize = new Vector3();
+var scratchRotation = new Quaternion();
+/**
+* Resolve how far a target reaches: an explicit `size`, else `radius`, else its geometry's bounds.
+* `dynamicSize` re-measures geometry instead of using the cached bounding box.
+*/
+function readTargetExtent(out, target, size, radius, dynamicSize, slot) {
+	out.hasSize = false;
+	if (radius !== void 0 && !size) {
+		out.radius = radius;
+		return out;
+	}
+	out.radius = 0;
+	if (!resolveTargetSize(scratchSize, target, size, radius, dynamicSize, slot)) return out;
+	out.hasSize = true;
+	scratchSize.toArray(out.size);
+	if (resolveTargetRotation(scratchRotation, target, slot)) scratchRotation.toArray(out.rotation);
+	else scratchRotation.identity().toArray(out.rotation);
+	return out;
+}
+//#endregion
+export { readTargetExtent };

package/dist/three/readTargetPose.d.ts

@@ -0,0 +1,8 @@
+import type { Quat } from 'math';
+import type { TargetPose } from '../core/TargetPose.js';
+import { type Target } from './resolve/Target.js';
+import type { TargetSlot } from './resolve/TargetRegistry.js';
+/** Read a target's world pose into `out`, from `slot` when it is fresh. Returns false when unresolved. */
+export declare function readTargetPose(out: TargetPose, target: Target, slot: TargetSlot | null, withRotation: boolean): boolean;
+/** Read only a target's world rotation into `out`. Returns false for fixed points and unresolved targets. */
+export declare function readTargetRotation(out: Quat, target: Target, slot: TargetSlot | null): boolean;

package/dist/three/readTargetPose.js

@@ -0,0 +1,21 @@
+import { resolveTargetPosition, resolveTargetRotation } from "./resolve/Target.js";
+import { Quaternion, Vector3 } from "three";
+//#region src/three/readTargetPose.ts
+var scratchPosition = new Vector3();
+var scratchRotation = new Quaternion();
+/** Read a target's world pose into `out`, from `slot` when it is fresh. Returns false when unresolved. */
+function readTargetPose(out, target, slot, withRotation) {
+	if (!resolveTargetPosition(scratchPosition, target, slot)) return false;
+	scratchPosition.toArray(out.position);
+	out.hasRotation = withRotation && resolveTargetRotation(scratchRotation, target, slot);
+	if (out.hasRotation) scratchRotation.toArray(out.rotation);
+	return true;
+}
+/** Read only a target's world rotation into `out`. Returns false for fixed points and unresolved targets. */
+function readTargetRotation(out, target, slot) {
+	if (!resolveTargetRotation(scratchRotation, target, slot)) return false;
+	scratchRotation.toArray(out);
+	return true;
+}
+//#endregion
+export { readTargetPose, readTargetRotation };

package/dist/three/resolve/Target.d.ts

@@ -0,0 +1,17 @@
+import { Quaternion, Vector3, type Object3D } from 'three';
+import { type Vector3Like } from './resolveVector3.js';
+import type { TargetSlot } from './TargetRegistry.js';
+/** A React-style ref, without depending on React. */
+export type RefLike<T> = {
+    current: T;
+};
+/** A fixed point, live object, or ref to a target object. */
+export type Target = Object3D | RefLike<Object3D | null> | Vector3Like | null | undefined;
+/** Resolve a target to its live object, if it has one. */
+export declare function resolveTargetObject3D(target: Target): Object3D | null;
+/** Resolve target dimensions, using explicit size, radius, or geometry bounds. */
+export declare function resolveTargetSize(outSize: Vector3, target: Target, size?: Vector3Like, radius?: number, dynamicSize?: boolean, slot?: TargetSlot | null): boolean;
+/** Resolve a target to a world position, from `slot` when it holds this frame's value. */
+export declare function resolveTargetPosition(out: Vector3, target: Target, slot?: TargetSlot | null): boolean;
+/** Resolve a target to a world rotation. Fixed points return `false`. */
+export declare function resolveTargetRotation(out: Quaternion, target: Target, slot?: TargetSlot | null): boolean;

package/dist/three/resolve/Target.js

@@ -0,0 +1,62 @@
+import { isVector3Like, resolveVector3 } from "./resolveVector3.js";
+import { Vector3 } from "three";
+//#region src/three/resolve/Target.ts
+/** Resolve a target to its live object, if it has one. */
+function resolveTargetObject3D(target) {
+	if (target == null || isVector3Like(target)) return null;
+	return ("current" in target ? target.current : target) ?? null;
+}
+var scratchWorldScale = new Vector3();
+/** Identify geometry-bearing three.js objects. */
+function isGeometryObject(object) {
+	const o = object;
+	return o.isMesh === true || o.isLine === true || o.isPoints === true;
+}
+/** Resolve target dimensions, using explicit size, radius, or geometry bounds. */
+function resolveTargetSize(outSize, target, size, radius, dynamicSize = false, slot) {
+	if (size) {
+		resolveVector3(outSize, size);
+		return true;
+	}
+	if (radius !== void 0) return false;
+	const object = resolveTargetObject3D(target);
+	if (!object || !isGeometryObject(object)) return false;
+	if (dynamicSize || !object.geometry.boundingBox) object.geometry.computeBoundingBox();
+	if (!object.geometry.boundingBox) return false;
+	object.geometry.boundingBox.getSize(outSize);
+	if (slot?.valid) scratchWorldScale.fromArray(slot.scale);
+	else object.getWorldScale(scratchWorldScale);
+	outSize.multiply(scratchWorldScale);
+	return true;
+}
+/** Resolve a target to a world position, from `slot` when it holds this frame's value. */
+function resolveTargetPosition(out, target, slot) {
+	if (slot?.valid) {
+		out.fromArray(slot.position);
+		return true;
+	}
+	if (target == null) return false;
+	if (isVector3Like(target)) {
+		resolveVector3(out, target);
+		return true;
+	}
+	const object = "current" in target ? target.current : target;
+	if (!object) return false;
+	object.getWorldPosition(out);
+	return true;
+}
+/** Resolve a target to a world rotation. Fixed points return `false`. */
+function resolveTargetRotation(out, target, slot) {
+	if (slot?.valid) {
+		out.fromArray(slot.rotation);
+		return true;
+	}
+	if (target == null) return false;
+	if (isVector3Like(target)) return false;
+	const object = "current" in target ? target.current : target;
+	if (!object) return false;
+	object.getWorldQuaternion(out);
+	return true;
+}
+//#endregion
+export { resolveTargetObject3D, resolveTargetPosition, resolveTargetRotation, resolveTargetSize };

package/dist/three/resolve/TargetRegistry.d.ts

@@ -0,0 +1,27 @@
+import type { Quat, Vec3 } from 'math';
+import { type Object3D } from 'three';
+import type { RefLike } from './Target.js';
+/** A target whose world transform comes from the scene graph. */
+export type RegisteredTarget = Object3D | RefLike<Object3D | null>;
+/** A target's world transform for the current frame. `valid` is false while a ref is empty. */
+export type TargetSlot = {
+    position: Vec3;
+    rotation: Quat;
+    scale: Vec3;
+    valid: boolean;
+};
+/**
+ * Resolves each registered target once per frame, however many stages and cameras read it.
+ * Two different refs to the same object get two slots.
+ */
+export declare class TargetRegistry {
+    private readonly entries;
+    private readonly byTarget;
+    /** Register a reader of `target` and return its slot. The same target shares one slot. */
+    acquire(target: RegisteredTarget): TargetSlot;
+    /** Unregister a reader. Unused entries are dropped on the next `refresh()`, so a re-`acquire` keeps the slot. */
+    release(target: RegisteredTarget): void;
+    has(target: RegisteredTarget): boolean;
+    /** Read every registered target's world transform. Call once per frame, before any stage runs. */
+    refresh(): void;
+}

package/dist/three/resolve/TargetRegistry.js

@@ -0,0 +1,78 @@
+import { Quaternion, Vector3 } from "three";
+//#region src/three/resolve/TargetRegistry.ts
+var scratchPosition = new Vector3();
+var scratchRotation = new Quaternion();
+var scratchScale = new Vector3();
+/**
+* Resolves each registered target once per frame, however many stages and cameras read it.
+* Two different refs to the same object get two slots.
+*/
+var TargetRegistry = class {
+	entries = [];
+	byTarget = /* @__PURE__ */ new Map();
+	/** Register a reader of `target` and return its slot. The same target shares one slot. */
+	acquire(target) {
+		let entry = this.byTarget.get(target);
+		if (!entry) {
+			entry = {
+				target,
+				count: 0,
+				slot: {
+					position: [
+						0,
+						0,
+						0
+					],
+					rotation: [
+						0,
+						0,
+						0,
+						1
+					],
+					scale: [
+						1,
+						1,
+						1
+					],
+					valid: false
+				}
+			};
+			this.byTarget.set(target, entry);
+			this.entries.push(entry);
+		}
+		entry.count++;
+		return entry.slot;
+	}
+	/** Unregister a reader. Unused entries are dropped on the next `refresh()`, so a re-`acquire` keeps the slot. */
+	release(target) {
+		const entry = this.byTarget.get(target);
+		if (entry && entry.count > 0) entry.count--;
+	}
+	has(target) {
+		return this.byTarget.has(target);
+	}
+	/** Read every registered target's world transform. Call once per frame, before any stage runs. */
+	refresh() {
+		let kept = 0;
+		for (let i = 0; i < this.entries.length; i++) {
+			const entry = this.entries[i];
+			if (entry.count === 0) {
+				this.byTarget.delete(entry.target);
+				continue;
+			}
+			this.entries[kept++] = entry;
+			const object = "current" in entry.target ? entry.target.current : entry.target;
+			const slot = entry.slot;
+			slot.valid = object != null;
+			if (!object) continue;
+			object.updateWorldMatrix(true, false);
+			object.matrixWorld.decompose(scratchPosition, scratchRotation, scratchScale);
+			scratchPosition.toArray(slot.position);
+			scratchRotation.toArray(slot.rotation);
+			scratchScale.toArray(slot.scale);
+		}
+		this.entries.length = kept;
+	}
+};
+//#endregion
+export { TargetRegistry };

package/dist/three/resolve/resolveVector3.d.ts

@@ -0,0 +1,12 @@
+import { type Vec3 } from 'math';
+import { Vector3 } from 'three';
+/** A vector as a `Vector3`, an `[x, y, z?]` tuple or one number for all axes (same shape as r3f's `Vector3` prop). */
+export type Vector3Like = Vector3 | readonly [x: number, y: number, z?: number] | number;
+/** Whether a value matches r3f's `Vector3` prop shorthand. */
+export declare function isVector3Like(value: unknown): value is Vector3Like;
+/** Resolve a r3f vector shorthand into `out`. */
+export declare function resolveVector3(out: Vector3, value: Vector3Like): Vector3;
+/** A new tuple from a vector shorthand, or `undefined` to keep a setting's default. */
+export declare function optionalVec3(value: Vector3Like | undefined): Vec3 | undefined;
+/** Resolve a r3f vector shorthand into the tuple `out`. */
+export declare function resolveVec3(out: Vec3, value: Vector3Like): Vec3;