@pmndrs/klipp 0.0.0-stage → 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Łukasz Kwas AKA Kvvasu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# Klipp 📹
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Version](https://badgen.net/npm/v/@pmndrs/klipp)](https://www.npmjs.com/package/@pmndrs/klipp)
+[![Examples](https://img.shields.io/static/v1?message=Examples&style=flat&colorA=000000&colorB=000000&label=&logo=threedotjs&logoColor=ffffff)](https://pmndrs.github.io/klipp/examples/)
+[![Docs](https://img.shields.io/static/v1?message=Docs&style=flat&colorA=000000&colorB=000000&label=&logo=googledocs&logoColor=ffffff)](https://pmndrs.github.io/klipp/docs/)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A camera toolkit for the web, inspired by Unity Cinemachine. Describe the shots you want, and klipp picks the right one and blends between them.
+
+The core runs anywhere, with no renderer or framework attached. Integrations are thin layers on top: three.js and React Three Fiber today, with more to come, like TresJS.
+
+```bash
+npm install @pmndrs/klipp
+```
+
+⚠️ Early-stage, experimental - the API may change.
+
+## Core
+
+```ts
+import { Klipp, FollowBody, HardLookAtAim, targetPose } from '@pmndrs/klipp';
+
+const klipp = new Klipp();
+const player = targetPose.create(); // keep player.position up to date
+
+const follow = klipp.addCamera('follow', { priority: 10 });
+follow.body = new FollowBody(player, { offset: [0, 3, 8], damping: 0.5 });
+follow.aim = new HardLookAtAim(player);
+
+// every frame
+klipp.update(dt);
+engineCamera.setPosition(klipp.shot.position);
+engineCamera.setRotation(klipp.shot.quaternion);
+```
+
+## React Three Fiber
+
+```tsx
+import { Klipp, VirtualCamera, Body, Aim } from '@pmndrs/klipp/react';
+
+<Klipp>
+  <VirtualCamera name="follow" priority={10}>
+    <Body.Follow target={playerRef} offset={[0, 3, 8]} damping={0.5} />
+    <Aim.HardLookAt target={playerRef} />
+  </VirtualCamera>
+
+  <VirtualCamera name="cutscene" priority={20} active={isCutscene}>
+    <Body.HardLockToTarget target={[10, 2, 0]} />
+    <Aim.HardLookAt target={playerRef} />
+  </VirtualCamera>
+</Klipp>;
+```
+
+## What's inside
+
+- **Virtual cameras** with priorities, and **blending** between them.
+- **Body** and **Aim**: follow, frame or look at targets, or let the user orbit and look around.
+- **Extension**, **Noise** and **Impulse**: group framing, lens, and camera shake.
+- **Debugging**: framing zones and camera frustums.
+
+## Packages
+
+| Entry point           | For                                                          |
+| --------------------- | ------------------------------------------------------------ |
+| `@pmndrs/klipp`       | The core, built on [`math`](https://github.com/pmndrs/math). |
+| `@pmndrs/klipp/three` | three.js classes, ending in `Three`.                         |
+| `@pmndrs/klipp/react` | React Three Fiber components.                                |
+| `@pmndrs/klipp/dom`   | Mouse, touch and wheel input, and debug overlays.            |
+
+## Links
+
+- [Documentation](https://pmndrs.github.io/klipp/docs/)
+- [Examples](https://pmndrs.github.io/klipp/examples/)

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/core/CameraState.d.ts

@@ -0,0 +1,32 @@
+import { type Quat, type Vec3 } from 'math';
+/** A reusable snapshot of camera transform, lens, targets, and view offset. */
+export type CameraState = {
+    position: Vec3;
+    quaternion: Quat;
+    fov: number;
+    near: number;
+    far: number;
+    /** Normalized frustum offset; `0` is centered. */
+    viewOffset: [number, number];
+    /** Body tracking position, valid when `hasTarget` is true. */
+    target: Vec3;
+    hasTarget: boolean;
+    /** Aim look-at position, valid when `hasLookAtTarget` is true. */
+    lookAtTarget: Vec3;
+    hasLookAtTarget: boolean;
+    /** Up direction used by look-at rotation. */
+    referenceUp: Vec3;
+    /** World rotation the Body turned the camera by this frame, which damped Aims follow without damping. */
+    rotationDampingBypass: Quat;
+};
+/** Create a camera state. */
+export declare function create(): CameraState;
+/** Copy `source` into `out` without replacing nested objects. */
+export declare function copy(out: CameraState, source: CameraState): CameraState;
+/** Merge defined fields from `partial` into `out`. */
+export declare function merge(out: CameraState, partial: Partial<CameraState>): CameraState;
+/** Whether `a` and `b` have the same position and rotation. */
+export declare const transformEquals: (a: CameraState, b: CameraState) => boolean;
+/** Whether `a` and `b` have the same lens, view offset included. */
+export declare const lensEquals: (a: CameraState, b: CameraState) => boolean;
+export { lerp } from './blend/lerpCameraState.js';

package/dist/core/CameraState.js

@@ -0,0 +1,97 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { lerp as lerp$1 } from "./blend/lerpCameraState.js";
+import { vec3, vec4 } from "math";
+//#region src/core/CameraState.ts
+var CameraState_exports = /* @__PURE__ */ __exportAll({
+	copy: () => copy,
+	create: () => create,
+	lensEquals: () => lensEquals,
+	lerp: () => lerp$1,
+	merge: () => merge,
+	transformEquals: () => transformEquals
+});
+/** Create a camera state. */
+function create() {
+	return {
+		position: [
+			0,
+			0,
+			0
+		],
+		quaternion: [
+			0,
+			0,
+			0,
+			1
+		],
+		fov: 50,
+		near: .1,
+		far: 1e3,
+		viewOffset: [0, 0],
+		target: [
+			0,
+			0,
+			0
+		],
+		hasTarget: false,
+		lookAtTarget: [
+			0,
+			0,
+			0
+		],
+		hasLookAtTarget: false,
+		referenceUp: [
+			0,
+			1,
+			0
+		],
+		rotationDampingBypass: [
+			0,
+			0,
+			0,
+			1
+		]
+	};
+}
+/** Copy `source` into `out` without replacing nested objects. */
+function copy(out, source) {
+	vec3.copy(out.position, source.position);
+	vec4.copy(out.quaternion, source.quaternion);
+	out.fov = source.fov;
+	out.near = source.near;
+	out.far = source.far;
+	out.viewOffset[0] = source.viewOffset[0];
+	out.viewOffset[1] = source.viewOffset[1];
+	vec3.copy(out.target, source.target);
+	out.hasTarget = source.hasTarget;
+	vec3.copy(out.lookAtTarget, source.lookAtTarget);
+	out.hasLookAtTarget = source.hasLookAtTarget;
+	vec3.copy(out.referenceUp, source.referenceUp);
+	vec4.copy(out.rotationDampingBypass, source.rotationDampingBypass);
+	return out;
+}
+/** Merge defined fields from `partial` into `out`. */
+function merge(out, partial) {
+	if (partial.position) vec3.copy(out.position, partial.position);
+	if (partial.quaternion) vec4.copy(out.quaternion, partial.quaternion);
+	if (partial.fov !== void 0) out.fov = partial.fov;
+	if (partial.near !== void 0) out.near = partial.near;
+	if (partial.far !== void 0) out.far = partial.far;
+	if (partial.viewOffset) {
+		out.viewOffset[0] = partial.viewOffset[0];
+		out.viewOffset[1] = partial.viewOffset[1];
+	}
+	if (partial.target) vec3.copy(out.target, partial.target);
+	if (partial.hasTarget !== void 0) out.hasTarget = partial.hasTarget;
+	if (partial.lookAtTarget) vec3.copy(out.lookAtTarget, partial.lookAtTarget);
+	if (partial.hasLookAtTarget !== void 0) out.hasLookAtTarget = partial.hasLookAtTarget;
+	if (partial.referenceUp) vec3.copy(out.referenceUp, partial.referenceUp);
+	if (partial.rotationDampingBypass) vec4.copy(out.rotationDampingBypass, partial.rotationDampingBypass);
+	return out;
+}
+/** Whether `a` and `b` have the same position and rotation. */
+var transformEquals = (a, b) => vec3.exactEquals(a.position, b.position) && vec4.exactEquals(a.quaternion, b.quaternion);
+/** Whether `a` and `b` have the same lens, view offset included. */
+var lensEquals = (a, b) => a.fov === b.fov && a.near === b.near && a.far === b.far && a.viewOffset[0] === b.viewOffset[0] && a.viewOffset[1] === b.viewOffset[1];
+//#endregion
+export { CameraState_exports, copy, create, lensEquals, lerp$1 as lerp, merge, transformEquals };

package/dist/core/EventDispatcher.d.ts

@@ -0,0 +1,18 @@
+/** An event as listeners receive it: its data plus `type` and the dispatching `target`. */
+export type DispatchedEvent<TData, TType extends string, TTarget> = TData & {
+    readonly type: TType;
+    readonly target: TTarget;
+};
+export type EventListener<TData, TType extends string, TTarget> = (event: DispatchedEvent<TData, TType, TTarget>) => void;
+type EventType<TEventMap> = Extract<keyof TEventMap, string>;
+/** Typed event dispatcher with the same semantics as three.js `EventDispatcher`. */
+export declare class EventDispatcher<TEventMap extends {} = {}> {
+    private readonly listeners;
+    addEventListener<T extends EventType<TEventMap>>(type: T, listener: EventListener<TEventMap[T], T, this>): void;
+    hasEventListener<T extends EventType<TEventMap>>(type: T, listener: EventListener<TEventMap[T], T, this>): boolean;
+    removeEventListener<T extends EventType<TEventMap>>(type: T, listener: EventListener<TEventMap[T], T, this>): void;
+    dispatchEvent<T extends EventType<TEventMap>>(event: {
+        type: T;
+    } & TEventMap[T]): void;
+}
+export {};

package/dist/core/EventDispatcher.js

@@ -0,0 +1,28 @@
+//#region src/core/EventDispatcher.ts
+/** Typed event dispatcher with the same semantics as three.js `EventDispatcher`. */
+var EventDispatcher = class {
+	listeners = /* @__PURE__ */ new Map();
+	addEventListener(type, listener) {
+		const array = this.listeners.get(type) ?? [];
+		if (!array.includes(listener)) this.listeners.set(type, [...array, listener]);
+	}
+	hasEventListener(type, listener) {
+		return this.listeners.get(type)?.includes(listener) ?? false;
+	}
+	removeEventListener(type, listener) {
+		const array = this.listeners.get(type);
+		if (!array?.includes(listener)) return;
+		const remaining = array.filter((l) => l !== listener);
+		this.listeners.set(type, remaining);
+	}
+	dispatchEvent(event) {
+		const array = this.listeners.get(event.type);
+		if (!array) return;
+		const dispatched = event;
+		dispatched.target = this;
+		for (const listener of array) listener.call(this, dispatched);
+		dispatched.target = null;
+	}
+};
+//#endregion
+export { EventDispatcher };

package/dist/core/Klipp.d.ts

@@ -0,0 +1,109 @@
+import * as klippState from './klippState.js';
+import type { CameraState } from './CameraState.js';
+import { EventDispatcher } from './EventDispatcher.js';
+import { advance, checkName, register, setHints, setPriority } from './internal.js';
+import type { CameraTransitionEventMap, VirtualCameraConfig } from './klippState.js';
+import { VirtualCamera, type VirtualCameraOptions } from './VirtualCamera.js';
+import { type BlendDefinition, type CustomBlend } from './blend/BlendDefinition.js';
+import type { BlendHints } from './blend/BlendHints.js';
+export type { CameraTransitionEventMap, VirtualCameraConfig };
+/** `'enabled'` writes the output, `'standby'` keeps every camera updating without writing, `'disabled'` stops. */
+export type KlippMode = 'enabled' | 'standby' | 'disabled';
+/** Per-frame work that runs before the cameras, like input. Return `true` while it is still moving. */
+export type FrameUpdate = (dt: number) => boolean | void;
+export type KlippOptions = {
+    /** Used when no `customBlends` entry matches a from→to transition. */
+    defaultBlend?: BlendDefinition;
+    customBlends?: CustomBlend[];
+    mode?: KlippMode;
+    /** The pose and lens new virtual cameras start from. */
+    initialCameraState?: CameraState;
+};
+/** Runs virtual cameras, picks the winner by priority and blends between shots. */
+export declare class Klipp extends EventDispatcher<CameraTransitionEventMap> {
+    readonly state: klippState.KlippState;
+    /** The pose and lens new virtual cameras start from. */
+    readonly initialCameraState: CameraState;
+    protected readonly cameras: Set<VirtualCamera>;
+    private readonly updates;
+    private readonly previousResult;
+    private settled;
+    private _width;
+    private _height;
+    private readonly params;
+    private readonly activeIdListeners;
+    private readonly liveIdListeners;
+    private draining;
+    private roundRobinTurn;
+    private _mode;
+    constructor(options?: KlippOptions);
+    get mode(): KlippMode;
+    /** Switching back to `'enabled'` writes the next shot even if it did not change, to take the camera back. */
+    set mode(mode: KlippMode);
+    setDefaultBlend(defaultBlend?: BlendDefinition): void;
+    setCustomBlends(customBlends?: CustomBlend[]): void;
+    get activeCameraId(): string | null;
+    isActive(id: string): boolean;
+    /** Subscribe to active camera changes. */
+    subscribeActiveId: (listener: () => void) => (() => void);
+    /** The last shot `update` wrote. Read it after `update` to put it on your camera. */
+    get shot(): CameraState;
+    /** The active camera's raw state. */
+    get activeState(): CameraState | null;
+    /** Camera currently settled in the output. */
+    get liveCameraId(): string | null;
+    isLive(id: string): boolean;
+    /** Subscribe to live camera changes. */
+    subscribeLiveId: (listener: () => void) => (() => void);
+    get isBlending(): boolean;
+    /** Destination of the active blend, or the live camera when settled. */
+    get blendTargetId(): string | null;
+    /** Whether the core has produced a real camera output. */
+    get hasEverActivated(): boolean;
+    /** Register a camera and return an unregister callback. */
+    [register](config: VirtualCameraConfig): () => void;
+    /** Update a candidate priority without restarting the current blend. */
+    [setPriority](id: string, priority: number): void;
+    /** Update candidate hints in place. */
+    [setHints](id: string, hints: BlendHints): void;
+    /** Viewport width in pixels, `0` until `setSize`. */
+    get width(): number;
+    /** Viewport height in pixels, `0` until `setSize`. */
+    get height(): number;
+    /** Set the viewport size in pixels. Pieces that frame by screen size get it whenever they update. */
+    setSize(width: number, height: number): void;
+    /** Create a virtual camera and add it. */
+    addCamera(name: string, options?: VirtualCameraOptions): VirtualCamera;
+    /** Add a virtual camera, moving it from any other `Klipp`. Returns a function that removes it. */
+    add(camera: VirtualCamera): () => void;
+    /** Remove a virtual camera. It leaves the arbitration, and the shot blends to the next winner. */
+    remove(camera: VirtualCamera): void;
+    [checkName](camera: VirtualCamera): void;
+    /**
+     * Call `start` while `camera` is on screen, and the function it returns once it leaves, for example to connect
+     * input. With `waitForBlend`, on screen begins once the blend into it has finished. Returns a function that stops.
+     */
+    whileOnScreen(camera: VirtualCamera, start: () => () => void, { waitForBlend }?: {
+        waitForBlend?: boolean | undefined;
+    }): () => void;
+    /** Run `update` every frame before the cameras. Returns a function that stops it. */
+    registerUpdate(update: FrameUpdate): () => void;
+    /**
+     * Advance one frame: run every camera, pick and blend the shot, and `write` it when it changed.
+     * Returns `true` while something is still moving, so on-demand rendering knows to request another frame.
+     */
+    update(dt: number): boolean;
+    /**
+     * Prepare and run the camera the shot heads to, and the others as their `standbyUpdate` says.
+     * Returns `true` while one moves.
+     */
+    private runCameras;
+    /** Runs at the start of every frame, before any camera. Layers override it to read their targets. */
+    protected prepareFrame(): void;
+    /** Called with the output whenever it changed. Layers override it to write their camera. */
+    protected write(_result: CameraState, _transformChanged: boolean, _lensChanged: boolean): void;
+    /** Advance the blend and return the reusable output state. */
+    [advance](dt: number): CameraState;
+    /** Notify subscribers and listeners of buffered events, including ones raised while notifying. */
+    private drainEvents;
+}

package/dist/core/Klipp.js

@@ -0,0 +1,253 @@
+import { EventDispatcher } from "./EventDispatcher.js";
+import { copy, create, lensEquals, transformEquals } from "./CameraState.js";
+import { targetId } from "./blend/blend.js";
+import { create as create$1, register, setHints, setPriority, tick, unregister } from "./klippState.js";
+import { advance, attachTo, checkName, prepare, register as register$1, run, setHints as setHints$1, setPriority as setPriority$1, skip } from "./internal.js";
+import { VirtualCamera } from "./VirtualCamera.js";
+import { DEFAULT_BLEND } from "./blend/BlendDefinition.js";
+//#region src/core/Klipp.ts
+/** Runs virtual cameras, picks the winner by priority and blends between shots. */
+var Klipp = class extends EventDispatcher {
+	state = create$1();
+	/** The pose and lens new virtual cameras start from. */
+	initialCameraState;
+	cameras = /* @__PURE__ */ new Set();
+	updates = /* @__PURE__ */ new Set();
+	previousResult = create();
+	settled = false;
+	_width = 0;
+	_height = 0;
+	params;
+	activeIdListeners = /* @__PURE__ */ new Set();
+	liveIdListeners = /* @__PURE__ */ new Set();
+	draining = false;
+	roundRobinTurn = 0;
+	_mode = "enabled";
+	constructor(options = {}) {
+		super();
+		this.mode = options.mode ?? "enabled";
+		this.initialCameraState = options.initialCameraState ?? create();
+		this.params = {
+			defaultBlend: options.defaultBlend ?? DEFAULT_BLEND,
+			customBlends: options.customBlends ?? []
+		};
+	}
+	get mode() {
+		return this._mode;
+	}
+	/** Switching back to `'enabled'` writes the next shot even if it did not change, to take the camera back. */
+	set mode(mode) {
+		if (mode === "enabled" && this._mode !== "enabled") this.settled = false;
+		this._mode = mode;
+	}
+	setDefaultBlend(defaultBlend) {
+		this.params.defaultBlend = defaultBlend ?? DEFAULT_BLEND;
+	}
+	setCustomBlends(customBlends) {
+		this.params.customBlends = customBlends ?? [];
+	}
+	get activeCameraId() {
+		return this.state.activeId;
+	}
+	isActive(id) {
+		return this.state.activeId === id;
+	}
+	/** Subscribe to active camera changes. */
+	subscribeActiveId = (listener) => {
+		this.activeIdListeners.add(listener);
+		return () => this.activeIdListeners.delete(listener);
+	};
+	/** The last shot `update` wrote. Read it after `update` to put it on your camera. */
+	get shot() {
+		return this.previousResult;
+	}
+	/** The active camera's raw state. */
+	get activeState() {
+		return this.state.activeId !== null ? this.state.cameras.get(this.state.activeId).state : null;
+	}
+	/** Camera currently settled in the output. */
+	get liveCameraId() {
+		return this.state.blend.liveId;
+	}
+	isLive(id) {
+		return this.state.blend.liveId === id;
+	}
+	/** Subscribe to live camera changes. */
+	subscribeLiveId = (listener) => {
+		this.liveIdListeners.add(listener);
+		return () => this.liveIdListeners.delete(listener);
+	};
+	get isBlending() {
+		return this.state.blend.transition.active;
+	}
+	/** Destination of the active blend, or the live camera when settled. */
+	get blendTargetId() {
+		return targetId(this.state.blend);
+	}
+	/** Whether the core has produced a real camera output. */
+	get hasEverActivated() {
+		return this.state.blend.hasEverActivated;
+	}
+	/** Register a camera and return an unregister callback. */
+	[register$1](config) {
+		const camera = register(this.state, config);
+		this.drainEvents();
+		return () => {
+			unregister(this.state, camera);
+			this.drainEvents();
+		};
+	}
+	/** Update a candidate priority without restarting the current blend. */
+	[setPriority$1](id, priority) {
+		setPriority(this.state, id, priority);
+		this.drainEvents();
+	}
+	/** Update candidate hints in place. */
+	[setHints$1](id, hints) {
+		setHints(this.state, id, hints);
+	}
+	/** Viewport width in pixels, `0` until `setSize`. */
+	get width() {
+		return this._width;
+	}
+	/** Viewport height in pixels, `0` until `setSize`. */
+	get height() {
+		return this._height;
+	}
+	/** Set the viewport size in pixels. Pieces that frame by screen size get it whenever they update. */
+	setSize(width, height) {
+		this._width = width;
+		this._height = height;
+	}
+	/** Create a virtual camera and add it. */
+	addCamera(name, options) {
+		const camera = new VirtualCamera(name, options);
+		this.add(camera);
+		return camera;
+	}
+	/** Add a virtual camera, moving it from any other `Klipp`. Returns a function that removes it. */
+	add(camera) {
+		if (camera.klipp !== this) {
+			camera.klipp?.remove(camera);
+			this[checkName](camera);
+			this.cameras.add(camera);
+			camera[attachTo](this);
+		}
+		return () => this.remove(camera);
+	}
+	/** Remove a virtual camera. It leaves the arbitration, and the shot blends to the next winner. */
+	remove(camera) {
+		if (!this.cameras.delete(camera)) return;
+		camera[attachTo](null);
+	}
+	[checkName](camera) {
+		for (const other of this.cameras) if (other !== camera && other.name === camera.name) {
+			console.warn(`Two virtual cameras are named "${camera.name}". Names must be unique: blends and events use them.`);
+			return;
+		}
+	}
+	/**
+	* Call `start` while `camera` is on screen, and the function it returns once it leaves, for example to connect
+	* input. With `waitForBlend`, on screen begins once the blend into it has finished. Returns a function that stops.
+	*/
+	whileOnScreen(camera, start, { waitForBlend = true } = {}) {
+		let stop = null;
+		const check = () => {
+			const onScreen = this.isActive(camera.name) && (!waitForBlend || this.isLive(camera.name));
+			if (onScreen && !stop) stop = start();
+			else if (!onScreen && stop) {
+				stop();
+				stop = null;
+			}
+		};
+		const offActive = this.subscribeActiveId(check);
+		const offLive = this.subscribeLiveId(check);
+		check();
+		return () => {
+			offActive();
+			offLive();
+			stop?.();
+			stop = null;
+		};
+	}
+	/** Run `update` every frame before the cameras. Returns a function that stops it. */
+	registerUpdate(update) {
+		this.updates.add(update);
+		return () => this.updates.delete(update);
+	}
+	/**
+	* Advance one frame: run every camera, pick and blend the shot, and `write` it when it changed.
+	* Returns `true` while something is still moving, so on-demand rendering knows to request another frame.
+	*/
+	update(dt) {
+		if (this.mode === "disabled") return false;
+		this.prepareFrame();
+		let stillInFlight = false;
+		for (const update of this.updates) if (update(dt) === true) stillInFlight = true;
+		if (this.runCameras(dt)) stillInFlight = true;
+		const result = this[advance](dt);
+		if (this.mode === "standby") return stillInFlight || this.isBlending;
+		if (!this.hasEverActivated) return stillInFlight;
+		const previous = this.previousResult;
+		const transformChanged = !this.settled || !transformEquals(result, previous);
+		const lensChanged = !this.settled || !lensEquals(result, previous);
+		if (!transformChanged && !lensChanged) return stillInFlight;
+		copy(previous, result);
+		this.settled = true;
+		this.write(result, transformChanged, lensChanged);
+		return true;
+	}
+	/**
+	* Prepare and run the camera the shot heads to, and the others as their `standbyUpdate` says.
+	* Returns `true` while one moves.
+	*/
+	runCameras(dt) {
+		const activeId = this.state.activeId;
+		let roundRobinCount = 0;
+		for (const camera of this.cameras) if (camera.active && camera.name !== activeId && camera.standbyUpdate === "roundRobin") roundRobinCount++;
+		const turn = roundRobinCount > 0 ? this.roundRobinTurn++ % roundRobinCount : -1;
+		let stillInFlight = false;
+		let roundRobinIndex = 0;
+		for (const camera of this.cameras) {
+			if (!camera.active) continue;
+			if (camera.name !== activeId && (camera.standbyUpdate === "never" || camera.standbyUpdate === "roundRobin" && roundRobinIndex++ !== turn)) {
+				camera[skip](dt);
+				continue;
+			}
+			camera[prepare](this._width, this._height);
+			if (camera[run](dt)) stillInFlight = true;
+		}
+		return stillInFlight;
+	}
+	/** Runs at the start of every frame, before any camera. Layers override it to read their targets. */
+	prepareFrame() {}
+	/** Called with the output whenever it changed. Layers override it to write their camera. */
+	write(_result, _transformChanged, _lensChanged) {}
+	/** Advance the blend and return the reusable output state. */
+	[advance](dt) {
+		const result = tick(this.state, this.params, dt);
+		this.drainEvents();
+		return result;
+	}
+	/** Notify subscribers and listeners of buffered events, including ones raised while notifying. */
+	drainEvents() {
+		if (this.draining) return;
+		this.draining = true;
+		const events = this.state.events;
+		let i = 0;
+		try {
+			for (; i < events.length; i++) {
+				const event = events[i];
+				if (event.type === "activeIdChanged") for (const listener of this.activeIdListeners) listener();
+				else if (event.type === "liveIdChanged") for (const listener of this.liveIdListeners) listener();
+				else this.dispatchEvent(event);
+			}
+		} finally {
+			if (i >= events.length) events.length = 0;
+			else events.splice(0, i + 1);
+			this.draining = false;
+		}
+	}
+};
+//#endregion
+export { Klipp };

package/dist/core/TargetExtent.d.ts

@@ -0,0 +1,11 @@
+import { type Quat, type Vec3 } from 'math';
+/** How far a target reaches: a sphere of `radius`, or (when `hasSize`) a box of `size` with its world `rotation`. */
+export type TargetExtent = {
+    radius: number;
+    size: Vec3;
+    rotation: Quat;
+    hasSize: boolean;
+};
+export declare const create: () => TargetExtent;
+/** Half-extents of `extent` along two world axes. */
+export declare function project(out: [number, number], extent: TargetExtent, axisA: Vec3, axisB: Vec3): [number, number];