@zkmake/three-cameras 0.0.0 → 0.2.0

package/dist/channels-Dp6gFE5b.js

@@ -0,0 +1,1324 @@
+import { BufferGeometry, CameraHelper, Euler, Float32BufferAttribute, Group, Line, LineBasicMaterial, Matrix4, Points, PointsMaterial, Quaternion, Vector3, Vector4 } from "three";
+//#region src/core/discover.ts
+const isCubeCamera = (object) => object.type === "CubeCamera";
+const isCamera = (object) => object.isCamera === true;
+const kindOf = (camera) => {
+	if (isCubeCamera(camera)) return "cube";
+	if (camera.isArrayCamera) return "array";
+	if (camera.isPerspectiveCamera) return "perspective";
+	if (camera.isOrthographicCamera) return "orthographic";
+	return "other";
+};
+/** Every camera under `root`, in scene order, `root` included. */
+const findCameras = (root) => {
+	const found = [];
+	const visit = (object) => {
+		if (isCubeCamera(object)) {
+			found.push(object);
+			return;
+		}
+		if (isCamera(object)) found.push(object);
+		for (const child of object.children) visit(child);
+	};
+	visit(root);
+	return found;
+};
+/** Where it sits: its ancestors' names (or types) from the root down, `scene › rig › cam`. */
+const pathOf = (object) => {
+	const path = [];
+	for (let node = object.parent; node; node = node.parent) path.unshift(node.name || node.type);
+	return path;
+};
+//#endregion
+//#region src/core/pose.ts
+/**
+* A camera's pose: where it is, which way it faces, and how it projects. Poses are what saved
+* views hold now and what keyframes will: capture one, put one back, and blend between two.
+*
+* Position and rotation are the camera's own (local, relative to its parent), so a pose put back
+* lands where it was taken even if the parent has moved since, the same way a keyframe would.
+*/
+const isPerspective = (camera) => camera.isPerspectiveCamera === true;
+const projects = (camera) => isPerspective(camera) || camera.isOrthographicCamera === true;
+const capturePose = (camera) => {
+	const { position, quaternion } = camera;
+	const pose = {
+		position: [
+			position.x,
+			position.y,
+			position.z
+		],
+		quaternion: [
+			quaternion.x,
+			quaternion.y,
+			quaternion.z,
+			quaternion.w
+		],
+		near: 0,
+		far: 0,
+		zoom: 1
+	};
+	if (projects(camera)) {
+		pose.near = camera.near;
+		pose.far = camera.far;
+		pose.zoom = camera.zoom;
+	}
+	if (isPerspective(camera)) pose.fov = camera.fov;
+	return pose;
+};
+const applyPose = (camera, pose) => {
+	camera.position.fromArray(pose.position);
+	camera.quaternion.fromArray(pose.quaternion);
+	if (projects(camera)) {
+		camera.near = pose.near;
+		camera.far = pose.far;
+		camera.zoom = pose.zoom;
+		if (isPerspective(camera) && pose.fov !== void 0) camera.fov = pose.fov;
+		camera.updateProjectionMatrix();
+	}
+};
+const lerp = (a, b, t) => a + (b - a) * t;
+const from = new Quaternion();
+const to = new Quaternion();
+const va = new Vector3();
+const vb = new Vector3();
+/** The pose `t` of the way from `a` to `b`: positions and lenses straight, rotation by slerp. */
+const blendPoses = (a, b, t) => {
+	const position = va.fromArray(a.position).lerp(vb.fromArray(b.position), t);
+	const quaternion = from.fromArray(a.quaternion).slerp(to.fromArray(b.quaternion), t);
+	const pose = {
+		position: [
+			position.x,
+			position.y,
+			position.z
+		],
+		quaternion: [
+			quaternion.x,
+			quaternion.y,
+			quaternion.z,
+			quaternion.w
+		],
+		near: lerp(a.near, b.near, t),
+		far: lerp(a.far, b.far, t),
+		zoom: lerp(a.zoom, b.zoom, t)
+	};
+	if (a.fov !== void 0 && b.fov !== void 0) pose.fov = lerp(a.fov, b.fov, t);
+	return pose;
+};
+/** Slow in, slow out: a camera move that starts and settles gently. */
+const easeInOut = (t) => t < .5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+const round = (value, digits = 4) => {
+	const text = value.toFixed(digits);
+	return text.includes(".") ? text.replace(/\.?0+$/, "") : text;
+};
+/** Three.js to recreate the pose on a camera called `name`. */
+const poseToCode = (pose, name = "camera") => {
+	const [x, y, z, w] = pose.quaternion;
+	const lines = [`${name}.position.set(${pose.position.map((value) => round(value)).join(", ")});`, `${name}.quaternion.set(${[
+		x,
+		y,
+		z,
+		w
+	].map((value) => round(value, 5)).join(", ")});`];
+	if (pose.fov !== void 0) lines.push(`${name}.fov = ${round(pose.fov, 2)};`);
+	if (pose.zoom !== 1) lines.push(`${name}.zoom = ${round(pose.zoom, 3)};`);
+	lines.push(`${name}.near = ${round(pose.near)};`, `${name}.far = ${round(pose.far)};`);
+	lines.push(`${name}.updateProjectionMatrix();`);
+	return lines.join("\n");
+};
+//#endregion
+//#region src/core/track.ts
+/**
+* A camera's track: keyframes in time, each a pose and the ease into the next. `sampleTrack` gives
+* the pose at any time: the camera travels a smooth curve through the keyed positions
+* (Catmull-Rom), turns by slerp, and its lens (fov, zoom, near, far) goes straight between keys,
+* all paced by the outgoing key's ease. Before the first key it holds the first; after the last,
+* the last.
+*
+* An ease is a preset or a custom cubic Bézier (CSS `cubic-bezier` terms: the curve from (0, 0) to
+* (1, 1) through two handles). A handle may go above 1 or below 0, for overshoot and anticipation.
+*/
+const EASES = [
+	"ease-in-out",
+	"linear",
+	"ease-in",
+	"ease-out",
+	"hold",
+	"custom"
+];
+/** The presets as Bézier handles: where a custom curve starts when a preset is reshaped. */
+const PRESET_BEZIERS = {
+	linear: [
+		.25,
+		.25,
+		.75,
+		.75
+	],
+	"ease-in": [
+		.32,
+		0,
+		.67,
+		0
+	],
+	"ease-out": [
+		.33,
+		1,
+		.68,
+		1
+	],
+	"ease-in-out": [
+		.65,
+		0,
+		.35,
+		1
+	]
+};
+const bezierAxis = (a, b, t) => {
+	const u = 1 - t;
+	return 3 * u * u * t * a + 3 * u * t * t * b + t * t * t;
+};
+const bezierSlope = (a, b, t) => {
+	const u = 1 - t;
+	return 3 * u * u * a + 6 * u * t * (b - a) + 3 * t * t * (1 - b);
+};
+/** A cubic Bézier ease: progress (y) at time share `x`, solving the curve's x for its parameter. */
+const cubicBezier = ([x1, y1, x2, y2], x) => {
+	if (x <= 0 || x >= 1) return x <= 0 ? 0 : 1;
+	let t = x;
+	for (let i = 0; i < 8; i += 1) {
+		const error = bezierAxis(x1, x2, t) - x;
+		const slope = bezierSlope(x1, x2, t);
+		if (Math.abs(error) < 1e-7) return bezierAxis(y1, y2, t);
+		if (Math.abs(slope) < 1e-6) break;
+		t -= error / slope;
+	}
+	let low = 0;
+	let high = 1;
+	t = x;
+	for (let i = 0; i < 40; i += 1) {
+		const value = bezierAxis(x1, x2, t);
+		if (Math.abs(value - x) < 1e-7) break;
+		if (value < x) low = t;
+		else high = t;
+		t = (low + high) / 2;
+	}
+	return bezierAxis(y1, y2, t);
+};
+const easeFns = {
+	linear: (t) => t,
+	"ease-in": (t) => t * t * t,
+	"ease-out": (t) => 1 - Math.pow(1 - t, 3),
+	"ease-in-out": (t) => t < .5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2,
+	hold: () => 0
+};
+/** Progress through a segment at time share `t` (0–1). A custom curve may leave 0–1 in between. */
+const applyEase = (ease, t, bezier) => {
+	const clamped = Math.min(1, Math.max(0, t));
+	if (ease === "custom") return cubicBezier(bezier ?? PRESET_BEZIERS.linear, clamped);
+	return easeFns[ease](clamped);
+};
+const sortKeys = (keys) => [...keys].sort((a, b) => a.time - b.time);
+const p0 = new Vector3();
+const p1 = new Vector3();
+const p2 = new Vector3();
+const p3 = new Vector3();
+const out = new Vector3();
+/** Uniform Catmull-Rom through p1 → p2, with p0 and p3 as the neighbours shaping the bend. */
+const catmullRom = (t) => {
+	const t2 = t * t;
+	const t3 = t2 * t;
+	return out.set(.5 * (2 * p1.x + (-p0.x + p2.x) * t + (2 * p0.x - 5 * p1.x + 4 * p2.x - p3.x) * t2 + (-p0.x + 3 * p1.x - 3 * p2.x + p3.x) * t3), .5 * (2 * p1.y + (-p0.y + p2.y) * t + (2 * p0.y - 5 * p1.y + 4 * p2.y - p3.y) * t2 + (-p0.y + 3 * p1.y - 3 * p2.y + p3.y) * t3), .5 * (2 * p1.z + (-p0.z + p2.z) * t + (2 * p0.z - 5 * p1.z + 4 * p2.z - p3.z) * t2 + (-p0.z + 3 * p1.z - 3 * p2.z + p3.z) * t3));
+};
+/** The pose at `time` on sorted `keys`, or `null` with no keys. */
+const sampleTrack = (keys, time) => {
+	const first = keys[0];
+	const last = keys.at(-1);
+	if (!first || !last) return null;
+	if (time <= first.time || keys.length === 1) return first.pose;
+	if (time >= last.time) return last.pose;
+	let index = 0;
+	while (index < keys.length - 2 && keys[index + 1].time <= time) index += 1;
+	const from = keys[index];
+	const to = keys[index + 1];
+	const span = to.time - from.time;
+	const t = applyEase(from.ease, span > 0 ? (time - from.time) / span : 1, from.bezier);
+	const pose = blendPoses(from.pose, to.pose, t);
+	if (from.ease !== "hold") {
+		const before = keys[index - 1];
+		const after = keys[index + 2];
+		p1.fromArray(from.pose.position);
+		p2.fromArray(to.pose.position);
+		if (before) p0.fromArray(before.pose.position);
+		else p0.copy(p1).multiplyScalar(2).sub(p2);
+		if (after) p3.fromArray(after.pose.position);
+		else p3.copy(p2).multiplyScalar(2).sub(p1);
+		const point = catmullRom(t);
+		pose.position = [
+			point.x,
+			point.y,
+			point.z
+		];
+	}
+	return pose;
+};
+//#endregion
+//#region src/core/lab.ts
+/**
+* `CameraLab`: the cameras a scene has and the ones drawing it. No UI; the panel drives it.
+*
+* Cameras come from two places: the scene graph, and the renderer. The camera an app renders with
+* is often not in the scene at all (R3F's default camera isn't; most vanilla apps never add
+* theirs), so the lab wraps `renderer.render` and notes every camera it's handed: that's how it
+* knows which are live, and how often each draws.
+*
+* Entries are named by the `cameras` option, else the camera's name, else its kind, numbered when
+* they repeat. A name holds for as long as the camera is listed, and saved views are kept by it.
+*
+* The same watch lets the lab act on frames: "look through" hands the renderer another camera in
+* place of the app's main one (fitted to its aspect for that frame), a move to a saved view steps
+* once per frame, and the timeline plays: each camera with keyframes is put where its track says,
+* right before the frame draws, so it wins over an app that moves the camera itself.
+*
+* Once the timeline has been played or scrubbed, tracked cameras are held to their tracks, even
+* paused. Editing one (`set`, a move to a saved view) lets it go, so the edit sticks until it's
+* keyed or the timeline moves again; `stop()` lets them all go.
+*/
+/** How long a camera's moves are kept, ms, and at most how many samples. */
+const RECORD_MS = 8e3;
+const RECORD_MAX = 900;
+/** Moved this recently counts as moving, ms. */
+const MOVING_MS = 1e3;
+/** Less than this, in its own units, isn't a move. */
+const STILL = 1e-4;
+/** How often a recorded line redraws, ms. */
+const MOTION_REDRAW_MS = 100;
+/** Path points per second of track, and the most a path gets. */
+const TRAIL_RATE = 30;
+const TRAIL_MAX = 600;
+/** Rendered this recently counts as live, ms. */
+const LIVE_MS = 500;
+/** A camera outside the scene stays listed this long after its last frame, ms. */
+const KEEP_MS = 5e3;
+/** A move to a saved view, ms. */
+const MOVE_MS = 800;
+/** A new timeline's length, s. */
+const DURATION_S = 10;
+/** Keys closer than this, s, are the same key. */
+const SAME_TIME = .001;
+const newId = () => `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+const memoryTracks = () => {
+	let data = { tracks: {} };
+	return {
+		load: () => data,
+		save: (next) => {
+			data = next;
+		}
+	};
+};
+const memoryViews = () => {
+	let views = {};
+	return {
+		load: () => views,
+		save: (next) => {
+			views = next;
+		}
+	};
+};
+const KIND_LABELS = {
+	perspective: "perspective",
+	orthographic: "orthographic",
+	array: "array",
+	cube: "cube",
+	other: "camera"
+};
+const now = () => typeof performance === "undefined" ? Date.now() : performance.now();
+const toDegrees = (radians) => radians * 180 / Math.PI;
+const toRadians = (degrees) => degrees * Math.PI / 180;
+const projectionOf = (camera, kind) => {
+	if (kind === "perspective" || kind === "array") {
+		const { near, far, zoom, fov, aspect } = camera;
+		return {
+			near,
+			far,
+			zoom,
+			fov,
+			aspect
+		};
+	}
+	if (kind === "orthographic") {
+		const { near, far, zoom, left, right, top, bottom } = camera;
+		return {
+			near,
+			far,
+			zoom,
+			left,
+			right,
+			top,
+			bottom
+		};
+	}
+	return null;
+};
+/** Ramer–Douglas–Peucker on positions: the samples where the path bends by more than `tolerance`. */
+const simplify = (samples, tolerance, maxKeys) => {
+	const keep = /* @__PURE__ */ new Set([0, samples.length - 1]);
+	const a = new Vector3();
+	const b = new Vector3();
+	const p = new Vector3();
+	const distance = (index, from, to) => {
+		a.fromArray(samples[from].position);
+		b.fromArray(samples[to].position);
+		p.fromArray(samples[index].position);
+		const span = b.clone().sub(a);
+		const length = span.lengthSq();
+		if (length === 0) return p.distanceTo(a);
+		const t = Math.min(1, Math.max(0, p.clone().sub(a).dot(span) / length));
+		return p.distanceTo(a.clone().addScaledVector(span, t));
+	};
+	const split = (from, to) => {
+		let far = -1;
+		let most = tolerance;
+		for (let i = from + 1; i < to; i += 1) {
+			const d = distance(i, from, to);
+			if (d > most) {
+				most = d;
+				far = i;
+			}
+		}
+		if (far >= 0 && keep.size < maxKeys) {
+			keep.add(far);
+			split(from, far);
+			split(far, to);
+		}
+	};
+	split(0, samples.length - 1);
+	return [...keep].sort((x, y) => x - y).map((index) => samples[index]);
+};
+var CameraLab = class {
+	options;
+	records = /* @__PURE__ */ new Map();
+	byId = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	tweens = /* @__PURE__ */ new Map();
+	store;
+	saved;
+	restoreRender = null;
+	/** Look-through: the camera shown, and the app camera it stands in for. */
+	looking = null;
+	standIn = null;
+	/** The frame being drawn: what to put back after it. */
+	fitted = null;
+	viewport = new Vector4();
+	view = null;
+	trackStore;
+	tracks;
+	state;
+	/** When the playhead last advanced, ms; `null` until the next frame after a play. */
+	lastTick = null;
+	selectedId = null;
+	notifyQueued = false;
+	disposed = false;
+	constructor(options) {
+		this.options = options;
+		this.store = options.store ?? memoryViews();
+		this.saved = { ...this.store.load() };
+		this.trackStore = options.trackStore ?? memoryTracks();
+		const loaded = this.trackStore.load();
+		this.tracks = { ...loaded.tracks };
+		this.state = {
+			time: 0,
+			duration: loaded.duration && loaded.duration > 0 ? loaded.duration : DURATION_S,
+			playing: false,
+			loop: true,
+			engaged: false
+		};
+		this.watch(options.renderer);
+		this.refresh();
+	}
+	/** Whether the lab sees frames: look-through and animated moves need a renderer. */
+	get watching() {
+		return this.restoreRender !== null;
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	/** Every camera, in scene order; ones only the renderer knows about after. */
+	entries() {
+		const time = now();
+		return [...this.byId.values()].map((item) => this.entryOf(item, time));
+	}
+	entry(id) {
+		const item = this.byId.get(id);
+		return item ? this.entryOf(item, now()) : null;
+	}
+	/** Where it is and how it projects, read now. */
+	details(id) {
+		const item = this.byId.get(id);
+		if (!item) return null;
+		const { camera } = item;
+		const position = new Vector3();
+		const quaternion = new Quaternion();
+		camera.updateWorldMatrix(true, false);
+		camera.matrixWorld.decompose(position, quaternion, new Vector3());
+		const euler = new Euler().setFromQuaternion(quaternion);
+		const own = camera.rotation;
+		return {
+			position: [
+				position.x,
+				position.y,
+				position.z
+			],
+			rotation: [
+				toDegrees(euler.x),
+				toDegrees(euler.y),
+				toDegrees(euler.z)
+			],
+			local: {
+				position: [
+					camera.position.x,
+					camera.position.y,
+					camera.position.z
+				],
+				rotation: [
+					toDegrees(own.x),
+					toDegrees(own.y),
+					toDegrees(own.z)
+				]
+			},
+			projection: projectionOf(camera, item.kind)
+		};
+	}
+	/**
+	* Change a camera: its own position or rotation, or its lens. The projection updates, and a
+	* render-on-demand loop gets a frame. An app that sets the camera every frame wins on the next.
+	*/
+	set(id, patch) {
+		const item = this.require(id);
+		const camera = item.camera;
+		if (patch.position) camera.position.set(...patch.position);
+		if (patch.rotation) {
+			const [x, y, z] = patch.rotation.map(toRadians);
+			camera.rotation.set(x, y, z);
+		}
+		if (this.projects(item)) {
+			const lens = camera;
+			if (patch.near !== void 0) lens.near = patch.near;
+			if (patch.far !== void 0) lens.far = patch.far;
+			if (patch.zoom !== void 0) lens.zoom = patch.zoom;
+			if (patch.fov !== void 0 && item.kind === "perspective") lens.fov = patch.fov;
+			lens.updateProjectionMatrix();
+		}
+		this.tweens.delete(item);
+		item.held = false;
+		this.options.invalidate?.();
+	}
+	/** The camera picked in a panel, which "add key" and the controls act on. */
+	get selected() {
+		return this.selectedId;
+	}
+	select(id) {
+		if (id !== this.selectedId && (id === null || this.byId.has(id))) {
+			this.selectedId = id;
+			this.notify();
+		}
+	}
+	/**
+	* Show the main view through `id`, or back through the app's own camera with `null`. The camera
+	* it stands in for is the app's main view: the one drawing the most of the screen (a
+	* picture-in-picture inset or a render target loses to it), most often on a tie.
+	*/
+	lookThrough(id) {
+		if (id === null || this.looking?.id === id) {
+			this.looking = null;
+			this.standIn = null;
+		} else {
+			const item = this.require(id);
+			if (!this.projects(item)) throw new Error(`three-cameras: "${id}" can't be looked through (${item.kind})`);
+			const time = now();
+			const main = [...this.records.values()].filter((other) => other !== item && isCamera(other.camera)).map((other) => ({
+				other,
+				fps: other.frames.filter((at) => time - at <= 1e3).length
+			})).filter(({ fps }) => fps > 0).sort((a, b) => b.other.area - a.other.area || b.fps - a.fps)[0];
+			if (!main) throw new Error("three-cameras: no camera is drawing, so there's no view to look through");
+			this.looking = item;
+			this.standIn = main.other.camera;
+		}
+		this.options.invalidate?.();
+		this.notify();
+	}
+	/** Save where the camera is and how it projects, as a view to go back to. */
+	saveView(id, name) {
+		const item = this.require(id);
+		if (!this.projects(item)) throw new Error(`three-cameras: "${id}" has no lens to save (${item.kind})`);
+		const list = this.saved[id] ?? [];
+		const taken = new Set(list.map((view) => view.name));
+		let label = name ?? `view ${list.length + 1}`;
+		for (let n = 2; taken.has(label); n += 1) label = `${name ?? "view"} ${n}`;
+		const view = {
+			id: `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+			name: label,
+			pose: capturePose(item.camera)
+		};
+		this.saved = {
+			...this.saved,
+			[id]: [...list, view]
+		};
+		this.store.save(this.saved);
+		this.notify();
+		return view;
+	}
+	views(id) {
+		return this.saved[id] ?? [];
+	}
+	deleteView(id, viewId) {
+		const list = this.saved[id] ?? [];
+		this.saved = {
+			...this.saved,
+			[id]: list.filter((view) => view.id !== viewId)
+		};
+		this.store.save(this.saved);
+		this.notify();
+	}
+	/**
+	* Move the camera to a saved view: eased over `duration` ms, stepped once per frame (so it needs
+	* a renderer; without one, or with `duration: 0`, it lands at once).
+	*/
+	goToView(id, viewId, { duration = MOVE_MS } = {}) {
+		const item = this.require(id);
+		const view = this.views(id).find((saved) => saved.id === viewId);
+		if (!view) throw new Error(`three-cameras: "${id}" has no saved view "${viewId}"`);
+		const camera = item.camera;
+		item.held = false;
+		if (duration <= 0 || !this.watching) {
+			this.tweens.delete(item);
+			applyPose(camera, view.pose);
+		} else this.tweens.set(item, {
+			from: capturePose(camera),
+			to: view.pose,
+			start: now(),
+			duration
+		});
+		this.options.invalidate?.();
+	}
+	timeline() {
+		return { ...this.state };
+	}
+	/** Play from the playhead (from the start if it's at the end). Needs a renderer to advance. */
+	play() {
+		if (this.state.time >= this.state.duration) this.state.time = 0;
+		this.state.playing = true;
+		this.lastTick = null;
+		this.engage();
+	}
+	pause() {
+		this.state.playing = false;
+		this.notify();
+	}
+	/** Stop and let every camera go back to the app (and to edits). The playhead stays. */
+	stop() {
+		this.state.playing = false;
+		this.state.engaged = false;
+		this.notify();
+	}
+	/** Move the playhead, and hold tracked cameras where their tracks are then. */
+	seek(time) {
+		this.state.time = Math.min(Math.max(0, time), this.state.duration);
+		this.lastTick = null;
+		this.engage();
+	}
+	setLoop(loop) {
+		this.state.loop = loop;
+		this.notify();
+	}
+	/** The timeline's length, s. Keys past it stay, and it grows to fit a key added later. */
+	setDuration(duration) {
+		if (duration > 0) {
+			this.state.duration = duration;
+			this.state.time = Math.min(this.state.time, duration);
+			this.saveTracks();
+			this.notify();
+		}
+	}
+	/** A camera's keyframes, in time order. */
+	keys(id) {
+		return this.tracks[id] ?? [];
+	}
+	/**
+	* Key the camera as it is now, at `time` (default: the playhead). A key already there is
+	* replaced, keeping its ease.
+	*/
+	addKey(id, { time, ease } = {}) {
+		const item = this.require(id);
+		if (!this.projects(item)) throw new Error(`three-cameras: "${id}" has no lens to key (${item.kind})`);
+		const at = Math.max(0, time ?? this.state.time);
+		const list = this.keys(id);
+		const existing = list.find((key) => Math.abs(key.time - at) < SAME_TIME);
+		const key = {
+			id: existing?.id ?? newId(),
+			time: at,
+			pose: capturePose(item.camera),
+			ease: ease ?? existing?.ease ?? "ease-in-out"
+		};
+		this.setTrack(id, [...list.filter((other) => other !== existing), key]);
+		if (at > this.state.duration) this.state.duration = Math.ceil(at);
+		item.held = true;
+		this.state.engaged = true;
+		this.saveTracks();
+		this.notify();
+		return key;
+	}
+	/**
+	* Change a key: move it in time, change its ease or its curve (`bezier`, which makes the ease
+	* `custom`), set its pose outright (a graph editor's drag), or re-key it from the camera as it is.
+	*/
+	updateKey(id, keyId, change) {
+		const item = this.require(id);
+		const key = this.keys(id).find((other) => other.id === keyId);
+		if (!key) throw new Error(`three-cameras: "${id}" has no key "${keyId}"`);
+		const ease = change.bezier ? "custom" : change.ease ?? key.ease;
+		const next = {
+			...key,
+			time: change.time === void 0 ? key.time : Math.max(0, change.time),
+			ease,
+			pose: change.recapture ? capturePose(item.camera) : change.pose ?? key.pose
+		};
+		if (ease === "custom") next.bezier = change.bezier ?? key.bezier ?? (key.ease === "custom" || key.ease === "hold" ? PRESET_BEZIERS.linear : PRESET_BEZIERS[key.ease]);
+		else delete next.bezier;
+		this.setTrack(id, this.keys(id).map((other) => other === key ? next : other));
+		if (change.recapture) item.held = true;
+		this.saveTracks();
+		this.options.invalidate?.();
+		this.notify();
+	}
+	deleteKey(id, keyId) {
+		this.setTrack(id, this.keys(id).filter((key) => key.id !== keyId));
+		this.saveTracks();
+		this.notify();
+	}
+	setTrack(id, keys) {
+		const next = { ...this.tracks };
+		if (keys.length > 0) next[id] = sortKeys(keys);
+		else delete next[id];
+		this.tracks = next;
+		const item = this.byId.get(id);
+		if (item) this.syncTrail(item);
+	}
+	/**
+	* Show or hide a camera's motion path in the scene, or `auto` (the default): shown while it
+	* moves or has keys, for cameras in the scene. The path is its track as a line with a dot per
+	* key; a camera without keys shows where it's been lately instead.
+	*/
+	setTrail(id, on) {
+		const item = this.require(id);
+		item.trailMode = on === "auto" ? "auto" : on ? "on" : "off";
+		this.syncTrail(item);
+		this.options.invalidate?.();
+		this.notify();
+	}
+	/** Where the camera has been lately, oldest first. */
+	motion(id) {
+		return [...this.require(id).motion];
+	}
+	/**
+	* Turn a camera's recorded moves into keys, replacing its track: a key where the path bends
+	* (within `tolerance`, in its own units), timed from the first sample, linear between. The
+	* lens is the camera's as it is now.
+	*/
+	bakeMotion(id, { tolerance = .05, maxKeys = 40 } = {}) {
+		const item = this.require(id);
+		if (!this.projects(item)) throw new Error(`three-cameras: "${id}" has no lens to key (${item.kind})`);
+		const samples = item.motion;
+		if (samples.length < 2) throw new Error(`three-cameras: "${id}" hasn't moved lately, so there's nothing to bake`);
+		const picked = simplify(samples, tolerance, maxKeys);
+		const start = samples[0].time;
+		const lens = capturePose(item.camera);
+		const keys = picked.map((sample) => ({
+			id: newId(),
+			time: Math.round((sample.time - start) / 1e3 * 1e3) / 1e3,
+			pose: {
+				...lens,
+				position: [...sample.position],
+				quaternion: [...sample.quaternion]
+			},
+			ease: "linear"
+		}));
+		this.setTrack(id, keys);
+		this.state.duration = Math.max(this.state.duration, Math.ceil(keys.at(-1).time));
+		this.saveTracks();
+		this.syncTrail(item);
+		this.notify();
+		return keys;
+	}
+	/** The main view as last drawn, or `null` before its first frame. */
+	viewTransform() {
+		return this.view ? {
+			world: this.view.world.clone(),
+			projection: this.view.projection.clone(),
+			viewport: this.view.viewport.clone()
+		} : null;
+	}
+	/** Every key dot drawn in the scene, where it is in the world. */
+	keyHandles() {
+		const handles = [];
+		for (const item of this.records.values()) {
+			const keys = this.tracks[item.id];
+			if (!item.trail || !keys) continue;
+			const parent = item.camera.parent;
+			parent?.updateWorldMatrix(true, false);
+			for (const key of keys) {
+				const position = new Vector3().fromArray(key.pose.position);
+				if (parent) position.applyMatrix4(parent.matrixWorld);
+				handles.push({
+					camera: item.id,
+					key: key.id,
+					position
+				});
+			}
+		}
+		return handles;
+	}
+	/** Move a key to a point in the world (a dragged dot): its position, in the camera's parent's space. */
+	moveKeyTo(id, keyId, world) {
+		const item = this.require(id);
+		const key = this.keys(id).find((other) => other.id === keyId);
+		if (!key) throw new Error(`three-cameras: "${id}" has no key "${keyId}"`);
+		const local = world.clone();
+		if (item.camera.parent) {
+			item.camera.parent.updateWorldMatrix(true, false);
+			item.camera.parent.worldToLocal(local);
+		}
+		this.updateKey(id, keyId, { pose: {
+			...key.pose,
+			position: [
+				local.x,
+				local.y,
+				local.z
+			]
+		} });
+	}
+	autoTrail(item, time) {
+		return this.projects(item) && this.inScene(item.camera) && ((this.tracks[item.id]?.length ?? 0) > 0 || time - item.lastMoved < MOVING_MS);
+	}
+	/** Make the path match its mode: create, draw or drop it. */
+	syncTrail(item, time = now()) {
+		const wanted = item.trailMode === "on" || item.trailMode === "auto" && this.autoTrail(item, time);
+		if (wanted && !item.trail) {
+			const trail = new Group();
+			const line = new Line(new BufferGeometry(), new LineBasicMaterial({
+				color: "#fbbf24",
+				transparent: true,
+				opacity: .9
+			}));
+			const markers = new Points(new BufferGeometry(), new PointsMaterial({
+				color: "#ffffff",
+				size: 8,
+				sizeAttenuation: false
+			}));
+			const recorded = new Line(new BufferGeometry(), new LineBasicMaterial({
+				color: "#7dd3fc",
+				transparent: true,
+				opacity: .55
+			}));
+			trail.name = `${item.id} (three-cameras path)`;
+			trail.userData.threeCameras = true;
+			trail.add(line, markers, recorded);
+			(item.camera.parent ?? this.options.scene).add(trail);
+			item.trail = trail;
+			this.drawTrail(item);
+			this.notifySoon();
+		} else if (!wanted && item.trail) {
+			this.dropTrail(item);
+			this.notifySoon();
+		} else if (item.trail) this.drawTrail(item);
+	}
+	drawTrail(item) {
+		const trail = item.trail;
+		if (!trail) return;
+		const [line, markers, recorded] = trail.children;
+		const keys = this.tracks[item.id] ?? [];
+		recorded.geometry.setAttribute("position", new Float32BufferAttribute(keys.length > 0 ? [] : item.motion.flatMap((sample) => sample.position), 3));
+		recorded.geometry.computeBoundingSphere();
+		const first = keys[0];
+		const last = keys.at(-1);
+		const path = [];
+		if (first && last) {
+			const span = last.time - first.time;
+			const count = Math.min(TRAIL_MAX, Math.max(1, Math.ceil(span * TRAIL_RATE)));
+			for (let i = 0; i <= count; i += 1) {
+				const pose = sampleTrack(keys, first.time + span * i / count);
+				if (pose) path.push(...pose.position);
+			}
+		}
+		line.geometry.setAttribute("position", new Float32BufferAttribute(path, 3));
+		line.geometry.computeBoundingSphere();
+		markers.geometry.setAttribute("position", new Float32BufferAttribute(keys.flatMap((key) => key.pose.position), 3));
+		markers.geometry.computeBoundingSphere();
+		this.options.invalidate?.();
+	}
+	dropTrail(item) {
+		if (!item.trail) return;
+		for (const child of item.trail.children) {
+			child.geometry.dispose();
+			child.material.dispose();
+		}
+		item.trail.removeFromParent();
+		item.trail = null;
+	}
+	saveTracks() {
+		this.trackStore.save({
+			duration: this.state.duration,
+			tracks: this.tracks
+		});
+	}
+	engage() {
+		this.state.engaged = true;
+		for (const item of this.records.values()) {
+			item.held = true;
+			this.tweens.delete(item);
+		}
+		this.applyTracks();
+		this.options.invalidate?.();
+		this.notify();
+	}
+	/** Every held camera with a track, to where its track is at the playhead. */
+	applyTracks() {
+		if (!this.state.engaged) return;
+		for (const item of this.records.values()) {
+			const keys = this.tracks[item.id];
+			if (item.held && keys && keys.length > 0) {
+				const pose = sampleTrack(keys, this.state.time);
+				if (pose) applyPose(item.camera, pose);
+			}
+		}
+	}
+	/** Move the playhead by the time since the last frame. */
+	advance(time) {
+		if (!this.state.playing) return;
+		const step = this.lastTick === null ? 0 : Math.min(.25, (time - this.lastTick) / 1e3);
+		this.lastTick = time;
+		this.state.time += step;
+		if (this.state.time >= this.state.duration) {
+			if (this.state.loop && this.state.duration > 0) this.state.time %= this.state.duration;
+			else {
+				this.state.time = this.state.duration;
+				this.state.playing = false;
+				this.notifySoon();
+			}
+		}
+		this.options.invalidate?.();
+	}
+	/**
+	* Look at the scene again: new cameras get entries, ones that left go (a camera outside the
+	* scene stays while it's still rendering, and a few seconds after).
+	*/
+	refresh() {
+		if (this.disposed) return;
+		const time = now();
+		const listed = /* @__PURE__ */ new Set();
+		let changed = false;
+		for (const camera of findCameras(this.options.scene)) listed.add(camera);
+		for (const info of this.options.cameras ?? []) listed.add(info.camera);
+		for (const [camera, item] of this.records) {
+			const last = item.frames.at(-1);
+			if (last !== void 0 && time - last < KEEP_MS || camera === this.standIn) listed.add(camera);
+		}
+		for (const camera of listed) if (!this.records.has(camera)) {
+			this.add(camera);
+			changed = true;
+		}
+		for (const [camera, item] of this.records) if (!listed.has(camera)) {
+			this.remove(item);
+			changed = true;
+		}
+		if (this.looking && !this.records.has(this.looking.camera)) {
+			this.looking = null;
+			this.standIn = null;
+		}
+		if (changed) this.notify();
+	}
+	/** Show or hide a camera's frustum. The helper sits in the lab's scene and follows the camera. */
+	setHelper(id, on) {
+		const item = this.require(id);
+		if (on === (item.helper !== null)) return;
+		if (on) {
+			if (!this.canHelp(item)) throw new Error(`three-cameras: "${id}" has no frustum to draw (${item.kind})`);
+			const helper = new CameraHelper(item.camera);
+			helper.name = `${id} (three-cameras helper)`;
+			helper.userData.threeCameras = true;
+			this.options.scene.add(helper);
+			item.helper = helper;
+		} else this.dropHelper(item);
+		this.options.invalidate?.();
+		this.notify();
+	}
+	dispose() {
+		this.disposed = true;
+		for (const item of this.records.values()) {
+			this.dropHelper(item);
+			this.dropTrail(item);
+		}
+		this.looking = null;
+		this.standIn = null;
+		this.state.playing = false;
+		this.tweens.clear();
+		this.restoreRender?.();
+		this.restoreRender = null;
+		this.listeners.clear();
+	}
+	watch(renderer) {
+		const target = renderer;
+		if (!target || typeof target.render !== "function") return;
+		const render = target.render;
+		const own = Object.hasOwn(target, "render");
+		const before = (camera, host) => this.beforeFrame(camera, host);
+		const after = () => this.afterFrame();
+		const watched = function(scene, camera, ...rest) {
+			const shown = before(camera, this);
+			try {
+				return render.call(this, scene, shown, ...rest);
+			} finally {
+				after();
+			}
+		};
+		target.render = watched;
+		this.restoreRender = () => {
+			if (target.render !== watched) return;
+			if (own) target.render = render;
+			else delete target.render;
+		};
+	}
+	/** Before a frame: count it, step moves, and pick the camera it's drawn with. */
+	beforeFrame(camera, host) {
+		if (this.disposed || !camera) return camera;
+		const time = now();
+		this.count(camera, time);
+		this.measure(camera, host);
+		this.record(time);
+		this.advance(time);
+		this.applyTracks();
+		this.step(time);
+		let shown = camera;
+		if (this.looking && camera === this.standIn) {
+			shown = this.looking.camera;
+			this.count(shown, time);
+			const lens = shown;
+			const view = camera;
+			if (lens.isPerspectiveCamera && view.isPerspectiveCamera && lens.aspect !== view.aspect) {
+				this.fitted = {
+					camera: lens,
+					aspect: lens.aspect
+				};
+				lens.aspect = view.aspect;
+				lens.updateProjectionMatrix();
+			}
+		}
+		for (const other of this.records.values()) if (other.helper) {
+			other.helper.visible = other.camera !== shown;
+			other.helper.update();
+		}
+		this.captureView(camera, shown);
+		return shown;
+	}
+	/** The main view's matrices, when this frame is it: the camera drawing the most of the screen. */
+	captureView(requested, shown) {
+		const item = this.records.get(requested);
+		if (!item) return;
+		let main = true;
+		for (const other of this.records.values()) if (other.area > item.area) {
+			main = false;
+			break;
+		}
+		if (!main || item.area === 0) return;
+		shown.updateWorldMatrix(true, false);
+		this.view ??= {
+			world: new Matrix4(),
+			projection: new Matrix4(),
+			viewport: new Vector4()
+		};
+		this.view.world.copy(shown.matrixWorld);
+		this.view.projection.copy(shown.projectionMatrix);
+		this.view.viewport.copy(this.viewport);
+	}
+	/**
+	* Note where cameras in the scene are, when they've moved: their recent motion, drawn for a
+	* camera without keys and bakeable into keys. A camera its track is driving isn't recorded.
+	*/
+	record(time) {
+		const driving = this.state.engaged;
+		for (const item of this.records.values()) {
+			if (!this.projects(item) || !this.inScene(item.camera)) continue;
+			const tracked = (this.tracks[item.id]?.length ?? 0) > 0;
+			if (!(driving && item.held && tracked)) {
+				const { position, quaternion } = item.camera;
+				const last = item.motion.at(-1);
+				if (!last || Math.abs(last.position[0] - position.x) > STILL || Math.abs(last.position[1] - position.y) > STILL || Math.abs(last.position[2] - position.z) > STILL || Math.abs(last.quaternion[3] - quaternion.w) > STILL) {
+					if (last) item.lastMoved = time;
+					item.motion.push({
+						time,
+						position: [
+							position.x,
+							position.y,
+							position.z
+						],
+						quaternion: [
+							quaternion.x,
+							quaternion.y,
+							quaternion.z,
+							quaternion.w
+						]
+					});
+				}
+				while (item.motion.length > RECORD_MAX || item.motion.length > 0 && time - item.motion[0].time > RECORD_MS) item.motion.shift();
+			}
+			if (item.trailMode === "auto" || item.trail) {
+				const was = item.trail !== null;
+				if (item.trail && !tracked && time - item.motionDrawn >= MOTION_REDRAW_MS) {
+					item.motionDrawn = time;
+					this.drawTrail(item);
+				}
+				if (item.trailMode === "auto" && was !== this.autoTrail(item, time)) this.syncTrail(item, time);
+			}
+		}
+	}
+	afterFrame() {
+		if (this.fitted) {
+			this.fitted.camera.aspect = this.fitted.aspect;
+			this.fitted.camera.updateProjectionMatrix();
+			this.fitted = null;
+		}
+	}
+	/** How much of the screen this frame covers, if the renderer says. */
+	measure(camera, host) {
+		const item = this.records.get(camera);
+		if (!item || typeof host?.getCurrentViewport !== "function") return;
+		const offscreen = typeof host.getRenderTarget === "function" && host.getRenderTarget() !== null;
+		const viewport = host.getCurrentViewport(this.viewport);
+		item.area = offscreen ? 0 : viewport.z * viewport.w;
+	}
+	count(camera, time) {
+		const item = this.records.get(camera);
+		if (item) {
+			item.frames.push(time);
+			while (item.frames.length > 0 && time - item.frames[0] > 1e3) item.frames.shift();
+		} else if (this.findOwner(camera) === null) {
+			this.add(camera).frames.push(time);
+			this.notifySoon();
+		}
+	}
+	/** Moves to saved views, one step per frame. */
+	step(time) {
+		if (this.tweens.size === 0) return;
+		for (const [item, tween] of this.tweens) {
+			const t = Math.min(1, (time - tween.start) / tween.duration);
+			applyPose(item.camera, blendPoses(tween.from, tween.to, easeInOut(t)));
+			if (t >= 1) this.tweens.delete(item);
+		}
+		this.options.invalidate?.();
+	}
+	/** A camera the renderer was handed that belongs to one listed, like a CubeCamera's faces. */
+	findOwner(camera) {
+		for (let node = camera.parent; node; node = node.parent) if (this.records.has(node)) return node;
+		return null;
+	}
+	canHelp(item) {
+		return this.projects(item);
+	}
+	projects(item) {
+		return item.kind === "perspective" || item.kind === "orthographic";
+	}
+	add(camera) {
+		const kind = kindOf(camera);
+		const registered = this.options.cameras?.find((info) => info.camera === camera)?.name;
+		const id = this.uniqueName(registered || camera.name || `${KIND_LABELS[kind]} camera`);
+		const item = {
+			id,
+			camera,
+			kind,
+			helper: null,
+			frames: [],
+			area: 0,
+			held: true,
+			trail: null,
+			trailMode: "auto",
+			motion: [],
+			lastMoved: Number.NEGATIVE_INFINITY,
+			motionDrawn: 0
+		};
+		this.records.set(camera, item);
+		this.byId.set(id, item);
+		return item;
+	}
+	remove(item) {
+		this.dropHelper(item);
+		this.dropTrail(item);
+		this.tweens.delete(item);
+		if (this.selectedId === item.id) this.selectedId = null;
+		this.records.delete(item.camera);
+		this.byId.delete(item.id);
+	}
+	dropHelper(item) {
+		if (item.helper) {
+			item.helper.removeFromParent();
+			item.helper.dispose();
+			item.helper = null;
+		}
+	}
+	uniqueName(base) {
+		let name = base;
+		for (let n = 2; this.byId.has(name); n += 1) name = `${base} ${n}`;
+		return name;
+	}
+	inScene(camera) {
+		let top = camera;
+		while (top.parent) top = top.parent;
+		return top === this.options.scene;
+	}
+	entryOf(item, time) {
+		const recent = item.frames.filter((at) => time - at <= 1e3);
+		const last = recent.at(-1);
+		return {
+			id: item.id,
+			kind: item.kind,
+			camera: item.camera,
+			inScene: this.inScene(item.camera),
+			live: last !== void 0 && time - last < LIVE_MS,
+			fps: recent.length,
+			helper: item.helper !== null,
+			canHelp: this.canHelp(item),
+			path: pathOf(item.camera),
+			projects: this.projects(item),
+			viewing: this.looking === item,
+			standingIn: this.looking !== null && this.standIn === item.camera,
+			views: this.saved[item.id]?.length ?? 0,
+			keys: this.tracks[item.id]?.length ?? 0,
+			trail: item.trail !== null,
+			moving: time - item.lastMoved < MOVING_MS,
+			recorded: item.motion.length > 1,
+			selected: this.selectedId === item.id
+		};
+	}
+	require(id) {
+		const item = this.byId.get(id);
+		if (!item) throw new Error(`three-cameras: no camera "${id}"`);
+		return item;
+	}
+	notifySoon() {
+		if (!this.notifyQueued) {
+			this.notifyQueued = true;
+			queueMicrotask(() => {
+				this.notifyQueued = false;
+				this.notify();
+			});
+		}
+	}
+	notify() {
+		for (const listener of this.listeners) listener();
+	}
+};
+//#endregion
+//#region src/core/channels.ts
+/**
+* A pose as separate channels, the way a graph editor shows it: position x, y, z; rotation x, y, z
+* (XYZ Euler, degrees); and the lens (fov, zoom, near, far). Read one, or write one back into a
+* pose. Rotation is stored as a quaternion, so a rotation channel goes through Euler angles on the
+* way in and out.
+*/
+const CHANNELS = [
+	"px",
+	"py",
+	"pz",
+	"rx",
+	"ry",
+	"rz",
+	"fov",
+	"zoom",
+	"near",
+	"far"
+];
+const CHANNEL_LABELS = {
+	px: "position x",
+	py: "position y",
+	pz: "position z",
+	rx: "rotation x",
+	ry: "rotation y",
+	rz: "rotation z",
+	fov: "fov",
+	zoom: "zoom",
+	near: "near",
+	far: "far"
+};
+const euler = new Euler();
+const quaternion = new Quaternion();
+const DEGREES = 180 / Math.PI;
+/** One channel's value in a pose; `undefined` for fov on an orthographic pose. */
+const readChannel = (pose, channel) => {
+	switch (channel) {
+		case "px": return pose.position[0];
+		case "py": return pose.position[1];
+		case "pz": return pose.position[2];
+		case "rx":
+		case "ry":
+		case "rz":
+			euler.setFromQuaternion(quaternion.fromArray(pose.quaternion));
+			return (channel === "rx" ? euler.x : channel === "ry" ? euler.y : euler.z) * DEGREES;
+		default: return pose[channel];
+	}
+};
+/** A copy of `pose` with one channel set. */
+const writeChannel = (pose, channel, value) => {
+	const next = {
+		...pose,
+		position: [...pose.position],
+		quaternion: [...pose.quaternion]
+	};
+	switch (channel) {
+		case "px":
+		case "py":
+		case "pz":
+			next.position[channel === "px" ? 0 : channel === "py" ? 1 : 2] = value;
+			break;
+		case "rx":
+		case "ry":
+		case "rz":
+			euler.setFromQuaternion(quaternion.fromArray(pose.quaternion));
+			euler[channel === "rx" ? "x" : channel === "ry" ? "y" : "z"] = value / DEGREES;
+			quaternion.setFromEuler(euler);
+			next.quaternion = [
+				quaternion.x,
+				quaternion.y,
+				quaternion.z,
+				quaternion.w
+			];
+			break;
+		default: next[channel] = value;
+	}
+	return next;
+};
+/**
+* A channel over time, `samples + 1` points from `start` to `end`, as the track plays it. Angles
+* are unwrapped (no jump at ±180°) so a turn reads as one curve.
+*/
+const sampleChannel = (keys, channel, start, end, samples) => {
+	const points = [];
+	let previous;
+	for (let i = 0; i <= samples; i += 1) {
+		const time = start + (end - start) * i / samples;
+		const pose = sampleTrack(keys, time);
+		let value = pose ? readChannel(pose, channel) : void 0;
+		if (value === void 0) continue;
+		if (previous !== void 0 && channel.startsWith("r")) {
+			while (value - previous > 180) value -= 360;
+			while (value - previous < -180) value += 360;
+		}
+		previous = value;
+		points.push([time, value]);
+	}
+	return points;
+};
+//#endregion
+export { pathOf as S, poseToCode as _, writeChannel as a, isCubeCamera as b, PRESET_BEZIERS as c, sampleTrack as d, sortKeys as f, easeInOut as g, capturePose as h, sampleChannel as i, applyEase as l, blendPoses as m, CHANNEL_LABELS as n, CameraLab as o, applyPose as p, readChannel as r, EASES as s, CHANNELS as t, cubicBezier as u, findCameras as v, kindOf as x, isCamera as y };
+
+//# sourceMappingURL=channels-Dp6gFE5b.js.map