@pmndrs/klipp 0.0.0-stage → 0.14.0

package/dist/core/extension/groupFraming.js

@@ -0,0 +1,271 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { createState as createState$1, damp, reset } from "../damping/damping.js";
+import { create } from "../TargetExtent.js";
+import { withDefaults } from "../params.js";
+import { clamp, degreesToRadians, vec3 } from "math";
+//#region src/core/extension/groupFraming.ts
+var groupFraming_exports = /* @__PURE__ */ __exportAll({
+	computeBounds: () => computeBounds,
+	createMember: () => createMember,
+	createParams: () => createParams,
+	createState: () => createState,
+	horizontalHalfFov: () => horizontalHalfFov,
+	update: () => update
+});
+var createMember = () => ({
+	position: [
+		0,
+		0,
+		0
+	],
+	extent: create(),
+	weight: 1,
+	resolved: true
+});
+/** Every setting from `settings`, or its default. */
+var createParams = (settings) => withDefaults({
+	padding: 0,
+	viewportWidth: 1,
+	viewportHeight: 1,
+	damping: 0,
+	maxSpeed: Infinity,
+	screenPosition: [0, 0],
+	fitMode: "ceiling",
+	minDistance: 0,
+	maxDistance: Infinity,
+	framingMode: "horizontalAndVertical"
+}, settings);
+var createState = () => ({
+	distanceDamper: createState$1(),
+	screenPositionXDamper: createState$1(),
+	screenPositionYDamper: createState$1(),
+	currentDistance: 0,
+	currentScreenPosition: [0, 0]
+});
+var scratchMin = [
+	0,
+	0,
+	0
+];
+var scratchMax = [
+	0,
+	0,
+	0
+];
+var scratchAccumulator = [
+	0,
+	0,
+	0
+];
+var scratchGroupPosition = [
+	0,
+	0,
+	0
+];
+var scratchRight = [
+	0,
+	0,
+	0
+];
+var scratchUp = [
+	0,
+	0,
+	0
+];
+var scratchForward = [
+	0,
+	0,
+	0
+];
+var scratchOffset = [
+	0,
+	0,
+	0
+];
+var scratchAxisX = [
+	0,
+	0,
+	0
+];
+var scratchAxisY = [
+	0,
+	0,
+	0
+];
+var scratchAxisZ = [
+	0,
+	0,
+	0
+];
+var scratchBackward = [
+	0,
+	0,
+	0
+];
+var rightAxis = [
+	1,
+	0,
+	0
+];
+var upAxis = [
+	0,
+	1,
+	0
+];
+var forwardAxis = [
+	0,
+	0,
+	-1
+];
+var backwardAxis = [
+	0,
+	0,
+	1
+];
+var CORNER_SIGNS = [-1, 1];
+/** A member's enclosing radius: a box's half-diagonal, otherwise its sphere radius. */
+var fallbackRadius = (member) => member.extent.hasSize ? vec3.length(member.extent.size) / 2 : member.extent.radius;
+function computeCenterPosition(out, members) {
+	let any = false;
+	for (const member of members) {
+		if (!member.resolved) continue;
+		const radius = fallbackRadius(member);
+		const p = member.position;
+		if (!any) {
+			vec3.subtractScalar(scratchMin, p, radius);
+			vec3.addScalar(scratchMax, p, radius);
+			any = true;
+			continue;
+		}
+		scratchMin[0] = Math.min(scratchMin[0], p[0] - radius);
+		scratchMin[1] = Math.min(scratchMin[1], p[1] - radius);
+		scratchMin[2] = Math.min(scratchMin[2], p[2] - radius);
+		scratchMax[0] = Math.max(scratchMax[0], p[0] + radius);
+		scratchMax[1] = Math.max(scratchMax[1], p[1] + radius);
+		scratchMax[2] = Math.max(scratchMax[2], p[2] + radius);
+	}
+	if (!any) return false;
+	vec3.scale(out, vec3.add(out, scratchMin, scratchMax), .5);
+	return true;
+}
+function computeAveragePosition(out, members) {
+	let totalWeight = 0;
+	vec3.set(scratchAccumulator, 0, 0, 0);
+	for (const member of members) {
+		if (member.weight <= 0 || !member.resolved) continue;
+		vec3.scaleAndAdd(scratchAccumulator, scratchAccumulator, member.position, member.weight);
+		totalWeight += member.weight;
+	}
+	if (totalWeight <= 0) return false;
+	vec3.scale(out, scratchAccumulator, 1 / totalWeight);
+	return true;
+}
+/**
+* Writes the group position to `outPosition` and returns a conservative enclosing radius, or -1 (leaving
+* `outPosition` untouched) when no member is resolved.
+*/
+function computeBounds(outPosition, members, mode) {
+	if (!(mode === "groupAverage" ? computeAveragePosition(outPosition, members) : computeCenterPosition(outPosition, members))) return -1;
+	let radius = 0;
+	for (const member of members) {
+		if (!member.resolved) continue;
+		const reach = vec3.distance(member.position, outPosition) + fallbackRadius(member);
+		if (reach > radius) radius = reach;
+	}
+	return radius;
+}
+/** Half the horizontal field of view, in radians, for a vertical half-FOV and aspect ratio. */
+var horizontalHalfFov = (verticalHalfFov, aspect) => Math.atan(Math.tan(verticalHalfFov) * aspect);
+/**
+* Keeps the group inside the frame by moving `out` along its own view axis and easing `viewOffset` to
+* `screenPosition`. Returns true while still moving.
+*/
+function update(out, state, params, members, positionMode, dt, justActivated) {
+	if (justActivated) {
+		reset(state.distanceDamper);
+		reset(state.screenPositionXDamper);
+		reset(state.screenPositionYDamper);
+	}
+	const boundsRadius = computeBounds(scratchGroupPosition, members, positionMode);
+	if (boundsRadius < 0 || boundsRadius === 0 && params.padding <= 0) return false;
+	const verticalHalfFov = degreesToRadians(out.fov) / 2;
+	const horizontalHalf = horizontalHalfFov(verticalHalfFov, params.viewportWidth / params.viewportHeight);
+	vec3.transformQuat(scratchRight, rightAxis, out.quaternion);
+	vec3.transformQuat(scratchUp, upAxis, out.quaternion);
+	vec3.transformQuat(scratchForward, forwardAxis, out.quaternion);
+	const includeVertical = params.framingMode !== "horizontal";
+	const includeHorizontal = params.framingMode !== "vertical";
+	const padding = Math.max(0, params.padding);
+	const tanVertical = Math.tan(verticalHalfFov);
+	const tanHorizontal = Math.tan(horizontalHalf);
+	const sinVertical = Math.sin(verticalHalfFov);
+	const sinHorizontal = Math.sin(horizontalHalf);
+	const cosVertical = Math.cos(verticalHalfFov);
+	const cosHorizontal = Math.cos(horizontalHalf);
+	let requiredDistance = 0;
+	for (const member of members) {
+		if (!member.resolved) continue;
+		vec3.subtract(scratchOffset, member.position, scratchGroupPosition);
+		const offsetUp = vec3.dot(scratchOffset, scratchUp);
+		const offsetRight = vec3.dot(scratchOffset, scratchRight);
+		const offsetForward = vec3.dot(scratchOffset, scratchForward);
+		const { extent } = member;
+		if (extent.hasSize) {
+			const { size, rotation } = extent;
+			vec3.transformQuat(scratchAxisX, vec3.set(scratchAxisX, size[0] * .5, 0, 0), rotation);
+			vec3.transformQuat(scratchAxisY, vec3.set(scratchAxisY, 0, size[1] * .5, 0), rotation);
+			vec3.transformQuat(scratchAxisZ, vec3.set(scratchAxisZ, 0, 0, size[2] * .5), rotation);
+			const axisXUp = vec3.dot(scratchAxisX, scratchUp);
+			const axisYUp = vec3.dot(scratchAxisY, scratchUp);
+			const axisZUp = vec3.dot(scratchAxisZ, scratchUp);
+			const axisXRight = vec3.dot(scratchAxisX, scratchRight);
+			const axisYRight = vec3.dot(scratchAxisY, scratchRight);
+			const axisZRight = vec3.dot(scratchAxisZ, scratchRight);
+			const axisXForward = vec3.dot(scratchAxisX, scratchForward);
+			const axisYForward = vec3.dot(scratchAxisY, scratchForward);
+			const axisZForward = vec3.dot(scratchAxisZ, scratchForward);
+			for (const sx of CORNER_SIGNS) for (const sy of CORNER_SIGNS) for (const sz of CORNER_SIGNS) {
+				const cornerUp = offsetUp + sx * axisXUp + sy * axisYUp + sz * axisZUp;
+				const cornerRight = offsetRight + sx * axisXRight + sy * axisYRight + sz * axisZRight;
+				const cornerForward = offsetForward + sx * axisXForward + sy * axisYForward + sz * axisZForward;
+				if (includeVertical) requiredDistance = Math.max(requiredDistance, (Math.abs(cornerUp) + padding) / tanVertical - cornerForward);
+				if (includeHorizontal) requiredDistance = Math.max(requiredDistance, (Math.abs(cornerRight) + padding) / tanHorizontal - cornerForward);
+			}
+		} else {
+			const effectiveRadius = extent.radius + padding;
+			if (includeVertical) {
+				const vertical = (effectiveRadius + Math.abs(offsetUp) * cosVertical) / sinVertical - offsetForward;
+				requiredDistance = Math.max(requiredDistance, vertical);
+			}
+			if (includeHorizontal) {
+				const horizontal = (effectiveRadius + Math.abs(offsetRight) * cosHorizontal) / sinHorizontal - offsetForward;
+				requiredDistance = Math.max(requiredDistance, horizontal);
+			}
+		}
+	}
+	const clampedRequiredDistance = clamp(requiredDistance, params.minDistance, params.maxDistance);
+	const distance = params.fitMode === "rigid" ? clampedRequiredDistance : Math.max(vec3.distance(out.position, scratchGroupPosition), clampedRequiredDistance);
+	const instant = typeof params.damping === "number" && params.damping <= 0;
+	if (instant) state.currentDistance = distance;
+	else {
+		state.distanceDamper.value = state.currentDistance;
+		state.currentDistance = damp(state.distanceDamper, distance, params.damping, dt, params.maxSpeed).value;
+	}
+	vec3.transformQuat(scratchBackward, backwardAxis, out.quaternion);
+	vec3.scaleAndAdd(out.position, scratchGroupPosition, scratchBackward, state.currentDistance);
+	const current = state.currentScreenPosition;
+	if (instant) {
+		current[0] = params.screenPosition[0];
+		current[1] = params.screenPosition[1];
+	} else {
+		state.screenPositionXDamper.value = current[0];
+		current[0] = damp(state.screenPositionXDamper, params.screenPosition[0], params.damping, dt).value;
+		state.screenPositionYDamper.value = current[1];
+		current[1] = damp(state.screenPositionYDamper, params.screenPosition[1], params.damping, dt).value;
+	}
+	out.viewOffset[0] = current[0];
+	out.viewOffset[1] = current[1];
+	return state.currentDistance !== distance || current[0] !== params.screenPosition[0] || current[1] !== params.screenPosition[1];
+}
+//#endregion
+export { computeBounds, createMember, createParams, createState, groupFraming_exports, horizontalHalfFov, update };

package/dist/core/extension/index.d.ts

@@ -0,0 +1,6 @@
+export { LensExtension, type LensOptions } from './LensExtension.js';
+export * as lens from './lens.js';
+export type { LensParams, LensState } from './lens.js';
+export { GroupFramingExtension, type GroupFramingOptions } from './GroupFramingExtension.js';
+export * as groupFraming from './groupFraming.js';
+export type { GroupMember, GroupPositionMode, GroupFramingParams, GroupFramingState, GroupFramingFitMode, GroupFramingMode, } from './groupFraming.js';

package/dist/core/extension/lens.d.ts

@@ -0,0 +1,35 @@
+import type { CameraState } from '../CameraState.js';
+import type { DamperState, DampingConstant } from '../damping/damping.js';
+export type LensParams = {
+    /** Overrides the camera's field of view, in degrees. `undefined` leaves the current value untouched. */
+    fov?: number;
+    /** Overrides the near clip plane. `undefined` leaves the current value untouched. */
+    near?: number;
+    /** Overrides the far clip plane. `undefined` leaves the current value untouched. */
+    far?: number;
+    /** Spring response time to `fov` as it changes. `0` is instant. */
+    fovDamping: DampingConstant;
+    /** Spring response time to `near` as it changes. `0` is instant. */
+    nearDamping: DampingConstant;
+    /** Spring response time to `far` as it changes. `0` is instant. */
+    farDamping: DampingConstant;
+    /** Caps how fast `fovDamping` can close the gap, in degrees/sec. `Infinity` means no cap. */
+    fovMaxSpeed: number;
+    /** Caps how fast `nearDamping` can close the gap, in world units/sec. `Infinity` means no cap. */
+    nearMaxSpeed: number;
+    /** Caps how fast `farDamping` can close the gap, in world units/sec. `Infinity` means no cap. */
+    farMaxSpeed: number;
+};
+/** Every setting from `settings`, or its default. */
+export declare const createParams: (settings?: Partial<LensParams>) => LensParams;
+export type LensState = {
+    fovDamper: DamperState;
+    nearDamper: DamperState;
+    farDamper: DamperState;
+    currentFov: number;
+    currentNear: number;
+    currentFar: number;
+};
+export declare const createState: () => LensState;
+/** Overrides the lens fields that are set in `params`, each with its own damping. Returns true while still moving. */
+export declare function update(out: CameraState, state: LensState, params: LensParams, dt: number, justActivated: boolean): boolean;

package/dist/core/extension/lens.js

@@ -0,0 +1,57 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { createState as createState$1, damp, reset } from "../damping/damping.js";
+import { withDefaults } from "../params.js";
+//#region src/core/extension/lens.ts
+var lens_exports = /* @__PURE__ */ __exportAll({
+	createParams: () => createParams,
+	createState: () => createState,
+	update: () => update
+});
+/** Every setting from `settings`, or its default. */
+var createParams = (settings) => withDefaults({
+	fov: void 0,
+	near: void 0,
+	far: void 0,
+	fovDamping: 0,
+	nearDamping: 0,
+	farDamping: 0,
+	fovMaxSpeed: Infinity,
+	nearMaxSpeed: Infinity,
+	farMaxSpeed: Infinity
+}, settings);
+var createState = () => ({
+	fovDamper: createState$1(),
+	nearDamper: createState$1(),
+	farDamper: createState$1(),
+	currentFov: 0,
+	currentNear: 0,
+	currentFar: 0
+});
+function dampLensField(damper, current, target, dampingTime, dt, maxSpeed) {
+	if (typeof dampingTime === "number" && dampingTime <= 0) return target;
+	damper.value = current;
+	return damp(damper, target, dampingTime, dt, maxSpeed).value;
+}
+/** Overrides the lens fields that are set in `params`, each with its own damping. Returns true while still moving. */
+function update(out, state, params, dt, justActivated) {
+	if (justActivated) {
+		reset(state.fovDamper);
+		reset(state.nearDamper);
+		reset(state.farDamper);
+	}
+	if (params.fov !== void 0) {
+		state.currentFov = dampLensField(state.fovDamper, state.currentFov, params.fov, params.fovDamping, dt, params.fovMaxSpeed);
+		out.fov = state.currentFov;
+	}
+	if (params.near !== void 0) {
+		state.currentNear = dampLensField(state.nearDamper, state.currentNear, params.near, params.nearDamping, dt, params.nearMaxSpeed);
+		out.near = state.currentNear;
+	}
+	if (params.far !== void 0) {
+		state.currentFar = dampLensField(state.farDamper, state.currentFar, params.far, params.farDamping, dt, params.farMaxSpeed);
+		out.far = state.currentFar;
+	}
+	return params.fov !== void 0 && state.currentFov !== params.fov || params.near !== void 0 && state.currentNear !== params.near || params.far !== void 0 && state.currentFar !== params.far;
+}
+//#endregion
+export { createParams, createState, lens_exports, update };

package/dist/core/groups/ClearShot.d.ts

@@ -0,0 +1,32 @@
+import type { CameraState } from '../CameraState.js';
+import type { BlendDefinition } from '../blend/BlendDefinition.js';
+import * as clearShotState from './clearShotState.js';
+import type { ClearShotCandidate, ShotQualityEvaluator } from './clearShotState.js';
+export type ClearShotOptions = {
+    evaluator: ShotQualityEvaluator;
+    defaultBlend?: BlendDefinition;
+    /** Seconds a new best candidate must stay the best, uninterrupted, before it's actually committed to. */
+    activateAfter?: number;
+    /** Seconds the live camera must stay live before yielding to another candidate on quality alone.
+     *  Gates internal switches only - an external, higher-priority camera preempting the whole `ClearShot`
+     *  from outside isn't modeled here, this class can't see that. */
+    minDuration?: number;
+    /** Pick randomly among exactly-tied (quality AND priority) candidates instead of list order. */
+    randomizeChoice?: boolean;
+    random?: () => number;
+};
+/**
+ * Picks the child with the best shot quality - `priority` only breaks quality ties.
+ * `activateAfter` debounces the pick (a new best must hold that title continuously before it's committed,
+ * anti-flicker); `minDuration` then protects the committed camera from being swapped out again too soon.
+ */
+export declare class ClearShot {
+    readonly state: clearShotState.ClearShotState;
+    private readonly params;
+    constructor(candidates: ClearShotCandidate[], options: ClearShotOptions);
+    get liveCameraId(): string | null;
+    get isBlending(): boolean;
+    /** The candidate currently being debounced toward (`activateAfter`), before it's committed to. */
+    get pendingCameraId(): string | null;
+    tick(dt: number): CameraState;
+}

package/dist/core/groups/MixingCamera.d.ts

@@ -0,0 +1,20 @@
+import type { CameraState } from '../CameraState.js';
+import { type MixingCameraSlot } from './mixCameraStates.js';
+/**
+ * Continuous N-way cross-fade of up to 8 fixed slots, weighted by `weight / sum(weights)` - unlike
+ * `Klipp`/`Sequencer`, there's no winner and no time-driven curve; the caller drives the mix by
+ * mutating `weight` directly (e.g. an authored slider blend between two cameras).
+ *
+ * Position/lens average in a plain weighted sum. Quaternions have no closed-form weighted average, so
+ * they're combined incrementally: start from the first contributing camera, then `slerp` each next one
+ * in by its share of the weight accumulated so far - exact for 2 cameras, a standard approximation for
+ * more.
+ */
+export declare class MixingCamera {
+    private readonly slots;
+    private readonly output;
+    constructor(slots: MixingCameraSlot[]);
+    /** Recomputes the weighted mix from the slots' current weights and returns it - same scratch instance
+     *  every call. If every weight is zero (or negative), returns the previous output unchanged. */
+    tick(): CameraState;
+}

package/dist/core/groups/Sequencer.d.ts

@@ -0,0 +1,24 @@
+import type { CameraState } from '../CameraState.js';
+import type { BlendDefinition } from '../blend/BlendDefinition.js';
+import * as sequencerState from './sequencerState.js';
+import type { SequencerInstruction } from './sequencerState.js';
+export type SequencerOptions = {
+    defaultBlend?: BlendDefinition;
+    /** Wrap to the first instruction after the last one's hold elapses, instead of holding forever. */
+    loop?: boolean;
+};
+/**
+ * Steps through a fixed list of camera instructions in order, holding each for its own duration before
+ * blending to the next. Holds the last instruction forever once reached, unless `loop`.
+ */
+export declare class Sequencer {
+    readonly state: sequencerState.SequencerState;
+    private readonly params;
+    constructor(instructions: SequencerInstruction[], options?: SequencerOptions);
+    /** The settled instruction; during a blend, still the one being left. `0` before the first tick. */
+    get currentIndex(): number;
+    get currentCameraId(): string;
+    get isBlending(): boolean;
+    /** Advances by `dt` and returns the composited `CameraState` - same scratch instance every call. */
+    tick(dt: number): CameraState;
+}

package/dist/core/groups/StateDrivenCamera.d.ts

@@ -0,0 +1,26 @@
+import type { CameraState } from '../CameraState.js';
+import type { BlendDefinition } from '../blend/BlendDefinition.js';
+import * as stateDrivenState from './stateDrivenState.js';
+import type { StateDrivenCandidate } from './stateDrivenState.js';
+export type StateDrivenCameraOptions = {
+    defaultBlend?: BlendDefinition;
+};
+/**
+ * Maps an externally-driven state (`setState()`, e.g. mirroring an animator's current state) to a child
+ * camera. Several candidates can target the same state - then the highest `priority` wins, and on a
+ * priority tie the FIRST one in the candidate list wins - deliberately simpler than `Klipp`'s
+ * "most recently activated" tie-break, since there's no activation order here, just a fixed list.
+ *
+ * If the current state matches no candidate, holds whatever was live before (nothing to switch to).
+ */
+export declare class StateDrivenCamera {
+    readonly state: stateDrivenState.StateDrivenState;
+    private readonly params;
+    constructor(candidates: StateDrivenCandidate[], options?: StateDrivenCameraOptions);
+    setState(state: string): void;
+    get currentState(): string | null;
+    get liveCameraId(): string | null;
+    get isBlending(): boolean;
+    /** Advances any in-progress blend by `dt` and returns the composited `CameraState` - same scratch instance every call. */
+    tick(dt: number): CameraState;
+}

package/dist/core/groups/clearShotState.d.ts

@@ -0,0 +1,32 @@
+import type { CameraState } from '../CameraState.js';
+import type { BlendState } from '../blend/blend.js';
+import type { BlendDefinition } from '../blend/BlendDefinition.js';
+export type ClearShotCandidate = {
+    cameraId: string;
+    /** Live reference - read fresh every `tick()`. */
+    state: CameraState;
+    priority: number;
+};
+/** Scores a candidate's shot quality - higher wins. No built-in scorer yet (a real one needs scene/
+ *  collider access, e.g. a future Deoccluder-based evaluator) - this is just the plug point. */
+export type ShotQualityEvaluator = (candidate: ClearShotCandidate) => number;
+export type ClearShotParams = {
+    candidates: readonly ClearShotCandidate[];
+    evaluator: ShotQualityEvaluator;
+    defaultBlend: BlendDefinition;
+    activateAfter: number;
+    minDuration: number;
+    randomizeChoice: boolean;
+    random: () => number;
+};
+export type ClearShotState = {
+    /** Seconds since the last commit (initial swap or mid-blend retarget). */
+    liveElapsed: number;
+    /** The candidate being debounced toward (`activateAfter`), before it is committed to. */
+    pendingId: string | null;
+    pendingElapsed: number;
+    blend: BlendState<string>;
+};
+export declare const create: () => ClearShotState;
+/** Re-evaluates the candidates, advances any blend by `dt` and returns the output. */
+export declare function tick(state: ClearShotState, params: ClearShotParams, dt: number): CameraState;

package/dist/core/groups/index.d.ts

@@ -0,0 +1,11 @@
+export { Sequencer, type SequencerOptions } from './Sequencer.js';
+export * as sequencerState from './sequencerState.js';
+export type { SequencerInstruction, SequencerParams, SequencerState } from './sequencerState.js';
+export { MixingCamera } from './MixingCamera.js';
+export type { MixingCameraSlot } from './mixCameraStates.js';
+export { StateDrivenCamera, type StateDrivenCameraOptions } from './StateDrivenCamera.js';
+export * as stateDrivenState from './stateDrivenState.js';
+export type { StateDrivenCandidate, StateDrivenParams, StateDrivenState } from './stateDrivenState.js';
+export { ClearShot, type ClearShotOptions } from './ClearShot.js';
+export * as clearShotState from './clearShotState.js';
+export type { ClearShotCandidate, ShotQualityEvaluator, ClearShotParams, ClearShotState } from './clearShotState.js';

package/dist/core/groups/mixCameraStates.d.ts

@@ -0,0 +1,13 @@
+import type { CameraState } from '../CameraState.js';
+export type MixingCameraSlot = {
+    cameraId: string;
+    /** Live reference - read fresh every `tick()`. */
+    state: CameraState;
+    /** Mutable - this camera's contribution is `weight / sum(weights)`. Zero/negative = no contribution. */
+    weight: number;
+};
+/**
+ * Writes the weighted mix of `slots` into `out`, weighted by `weight / sum(weights)`. If every weight is
+ * zero (or negative), `out` is left unchanged.
+ */
+export declare function mix(out: CameraState, slots: readonly MixingCameraSlot[]): CameraState;

package/dist/core/groups/sequencerState.d.ts

@@ -0,0 +1,26 @@
+import type { CameraState } from '../CameraState.js';
+import type { BlendState } from '../blend/blend.js';
+import type { BlendDefinition } from '../blend/BlendDefinition.js';
+export type SequencerInstruction = {
+    cameraId: string;
+    /** Live reference - `Sequencer` reads it directly. */
+    state: CameraState;
+    /** Seconds to hold this camera before advancing. Ignored on the last instruction unless `loop`. */
+    hold: number;
+    /** Transition into the NEXT instruction. Falls back to `defaultBlend` if omitted. */
+    blend?: BlendDefinition;
+};
+export type SequencerParams = {
+    instructions: readonly SequencerInstruction[];
+    defaultBlend: BlendDefinition;
+    loop: boolean;
+};
+export type SequencerState = {
+    holdElapsed: number;
+    blend: BlendState<number>;
+};
+export declare const create: () => SequencerState;
+/** The settled instruction; during a blend, still the one being left. `0` before the first tick. */
+export declare const index: (state: SequencerState) => number;
+/** Advances the sequence by `dt` and returns the composited output. */
+export declare function tick(state: SequencerState, params: SequencerParams, dt: number): CameraState;

package/dist/core/groups/stateDrivenState.d.ts

@@ -0,0 +1,28 @@
+import type { CameraState } from '../CameraState.js';
+import type { BlendState } from '../blend/blend.js';
+import type { BlendDefinition } from '../blend/BlendDefinition.js';
+export type StateDrivenCandidate = {
+    cameraId: string;
+    /** Live reference - read fresh every `tick()`. */
+    state: CameraState;
+    priority: number;
+    /** Which driving state (`setState()`) this candidate applies to. */
+    forState: string;
+};
+export type StateDrivenParams = {
+    candidates: readonly StateDrivenCandidate[];
+    defaultBlend: BlendDefinition;
+};
+export type StateDrivenState = {
+    drivingState: string | null;
+    winnerId: string | null;
+    blend: BlendState<string>;
+};
+export declare const create: () => StateDrivenState;
+/** Select the camera for `drivingState`: highest priority, first in the list on a tie. */
+export declare function setDrivingState(state: StateDrivenState, params: StateDrivenParams, drivingState: string): void;
+/**
+ * Advances any blend toward the selected camera and returns the output. Before any matching state has
+ * been set, this is the untouched default `CameraState`.
+ */
+export declare function tick(state: StateDrivenState, params: StateDrivenParams, dt: number): CameraState;

package/dist/core/impulse/ImpulseField.d.ts

@@ -0,0 +1,15 @@
+import type { Vec3 } from 'math';
+import * as impulses from './impulses.js';
+import type { GenerateImpulseOptions, ImpulseClockSeconds } from './impulses.js';
+/** Stores one-shot impulses and samples their combined effect at a world position. */
+export declare class ImpulseField {
+    readonly state: impulses.ImpulseFieldState;
+    /** Register a new impulse event. */
+    generate(options: GenerateImpulseOptions, now?: ImpulseClockSeconds): void;
+    /** Write the summed offset into `outPositionOffset` and return its current strength. */
+    sampleAt(outPositionOffset: Vec3, samplePosition: Vec3, channelMask?: number, gain?: number, now?: ImpulseClockSeconds): number;
+    /** Whether any event remains within its lifetime. */
+    get hasEvents(): boolean;
+}
+/** Shared impulse field. Create another instance for an isolated event stream. */
+export declare const impulseField: ImpulseField;

package/dist/core/impulse/ImpulseField.js

@@ -0,0 +1,22 @@
+import { createFieldState, generate, now, sample } from "./impulses.js";
+//#region src/core/impulse/ImpulseField.ts
+/** Stores one-shot impulses and samples their combined effect at a world position. */
+var ImpulseField = class {
+	state = createFieldState();
+	/** Register a new impulse event. */
+	generate(options, now$2 = now()) {
+		generate(this.state, options, now$2);
+	}
+	/** Write the summed offset into `outPositionOffset` and return its current strength. */
+	sampleAt(outPositionOffset, samplePosition, channelMask = 1, gain = 1, now$1 = now()) {
+		return sample(outPositionOffset, this.state, samplePosition, channelMask, gain, now$1);
+	}
+	/** Whether any event remains within its lifetime. */
+	get hasEvents() {
+		return this.state.events.length > 0;
+	}
+};
+/** Shared impulse field. Create another instance for an isolated event stream. */
+var impulseField = new ImpulseField();
+//#endregion
+export { ImpulseField, impulseField };

package/dist/core/impulse/ImpulseListenerNoise.d.ts

@@ -0,0 +1,19 @@
+import type { CameraState } from '../CameraState.js';
+import type { BasicMultiChannelPerlinNoise } from '../noise/BasicMultiChannelPerlinNoise.js';
+import type { ImpulseField } from './ImpulseField.js';
+import type { ImpulseListenerParams } from './impulseListener.js';
+export type ImpulseListenerOptions = Partial<ImpulseListenerParams> & {
+    /** Perlin shake driven by the impulse strength. */
+    shake?: BasicMultiChannelPerlinNoise;
+};
+/** Applies impulse offsets and optional strength-driven Perlin shake. */
+export declare class ImpulseListenerNoise implements ImpulseListenerParams {
+    field: ImpulseField;
+    channelMask: number;
+    gain: number;
+    cameraSpace: boolean;
+    shake?: BasicMultiChannelPerlinNoise;
+    constructor(options?: ImpulseListenerOptions);
+    /** Apply the current impulse effect and report whether events remain active. */
+    update: (out: CameraState, dt: number, justActivated: boolean, now?: number) => boolean;
+}