@pmndrs/klipp 0.0.0-stage → 0.14.0

package/dist/core/input/inputMapping.d.ts

@@ -0,0 +1,46 @@
+import type { InputAxisData } from './axis.js';
+import type { ConsumedInput } from './consumedInput.js';
+export type InputAxisPair = {
+    x: InputAxisData;
+    y: InputAxisData;
+};
+/** Inverts both axes or configures them independently. */
+export type InputInvert = boolean | {
+    x?: boolean;
+    y?: boolean;
+};
+export type InputSourceMapping = {
+    axes: InputAxisPair;
+    /** Multiplies the raw delta before it reaches the axes. */
+    gain?: number;
+    /** Whether either axis is inverted. */
+    invert?: InputInvert;
+};
+/** One input feeding one axis. */
+export type InputAxisMapping = {
+    axis: InputAxisData;
+    /** Multiplies the raw delta before it reaches the axis. */
+    gain?: number;
+    invert?: boolean;
+};
+/** Which axes each input drives. Leave a source out, or set it to `null`, to ignore it. */
+export type InputControllerConfig = {
+    /** Dragging with each mouse button held. */
+    mouseButtons?: {
+        left?: InputSourceMapping | null;
+        right?: InputSourceMapping | null;
+        middle?: InputSourceMapping | null;
+    };
+    /** Dragging with one, two or three fingers. */
+    touches?: {
+        one?: InputSourceMapping | null;
+        two?: InputSourceMapping | null;
+        three?: InputSourceMapping | null;
+    };
+    /** Vertical wheel scrolling, in pixels. Scrolling up is positive, like spreading a pinch. */
+    wheel?: InputAxisMapping | null;
+    /** Pinch with two fingers or on a trackpad, as the change in `ln(scale)`. Spreading is positive. */
+    pinch?: InputAxisMapping | null;
+};
+/** Feeds every configured source's shaped delta and hold state into its axes. */
+export declare function feedAxes(config: InputControllerConfig, input: ConsumedInput, enabled: boolean): void;

package/dist/core/input/inputMapping.js

@@ -0,0 +1,55 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { applyDelta } from "./axis.js";
+//#region src/core/input/inputMapping.ts
+var inputMapping_exports = /* @__PURE__ */ __exportAll({ feedAxes: () => feedAxes });
+var isInverted = (invert, axis) => invert === true || typeof invert === "object" && !!invert[axis];
+function applySource(mapping, dx, dy) {
+	if (!mapping || dx === 0 && dy === 0) return;
+	const gain = mapping.gain ?? 1;
+	applyDelta(mapping.axes.x, dx * gain * (isInverted(mapping.invert, "x") ? -1 : 1));
+	applyDelta(mapping.axes.y, dy * gain * (isInverted(mapping.invert, "y") ? -1 : 1));
+}
+function applyAxis(mapping, delta) {
+	if (!mapping || delta === 0) return;
+	applyDelta(mapping.axis, delta * (mapping.gain ?? 1) * (mapping.invert ? -1 : 1));
+}
+function resetHeld(mapping) {
+	if (!mapping) return;
+	mapping.axes.x.held = false;
+	mapping.axes.y.held = false;
+}
+function applyHeld(mapping, held) {
+	if (!mapping || !held) return;
+	mapping.axes.x.held = true;
+	mapping.axes.y.held = true;
+}
+/** Feeds every configured source's shaped delta and hold state into its axes. */
+function feedAxes(config, input, enabled) {
+	const { mouseButtons, touches } = config;
+	resetHeld(mouseButtons?.left);
+	resetHeld(mouseButtons?.right);
+	resetHeld(mouseButtons?.middle);
+	resetHeld(touches?.one);
+	resetHeld(touches?.two);
+	resetHeld(touches?.three);
+	if (config.pinch) config.pinch.axis.held = false;
+	if (!enabled) return;
+	applySource(mouseButtons?.left, input.leftDx, input.leftDy);
+	applySource(mouseButtons?.right, input.rightDx, input.rightDy);
+	applySource(mouseButtons?.middle, input.middleDx, input.middleDy);
+	applySource(touches?.one, input.touchOneDx, input.touchOneDy);
+	applySource(touches?.two, input.touchTwoDx, input.touchTwoDy);
+	applySource(touches?.three, input.touchThreeDx, input.touchThreeDy);
+	applySource(mouseButtons?.left, input.lockedDx, input.lockedDy);
+	applyHeld(mouseButtons?.left, input.leftHeld);
+	applyHeld(mouseButtons?.right, input.rightHeld);
+	applyHeld(mouseButtons?.middle, input.middleHeld);
+	applyHeld(touches?.one, input.touchOneHeld);
+	applyHeld(touches?.two, input.touchTwoHeld);
+	applyHeld(touches?.three, input.touchThreeHeld);
+	applyAxis(config.wheel, -input.wheelDeltaY);
+	applyAxis(config.pinch, input.pinchDelta);
+	if (config.pinch && input.touchTwoHeld) config.pinch.axis.held = true;
+}
+//#endregion
+export { feedAxes, inputMapping_exports };

package/dist/core/input/shortestWrappedDelta.d.ts

@@ -0,0 +1,2 @@
+/** Shortest signed distance from `value` to `target` within a wrapped range. */
+export declare function shortestWrappedDelta(value: number, target: number, range: [number, number]): number;

package/dist/core/input/shortestWrappedDelta.js

@@ -0,0 +1,11 @@
+//#region src/core/input/shortestWrappedDelta.ts
+/** Shortest signed distance from `value` to `target` within a wrapped range. */
+function shortestWrappedDelta(value, target, range) {
+	const span = range[1] - range[0];
+	let delta = (target - value) % span;
+	if (delta > span / 2) delta -= span;
+	if (delta < -span / 2) delta += span;
+	return delta;
+}
+//#endregion
+export { shortestWrappedDelta };

package/dist/core/internal.d.ts

@@ -0,0 +1,16 @@
+/** Connect a camera to a `Klipp`, or disconnect it with `null`. */
+export declare const attachTo: unique symbol;
+/** Register a raw state in a `Klipp`'s arbitration. Returns a function that unregisters it. */
+export declare const register: unique symbol;
+export declare const setPriority: unique symbol;
+export declare const setHints: unique symbol;
+/** Advance a `Klipp`'s arbitration and blend, without running any camera. */
+export declare const advance: unique symbol;
+/** Warn when another camera in a `Klipp` already has this camera's name. */
+export declare const checkName: unique symbol;
+/** Pass the viewport size on to a camera's pieces. */
+export declare const prepare: unique symbol;
+/** Run a camera's pieces for one frame. */
+export declare const run: unique symbol;
+/** Skip a camera this frame, keeping the time for its next run. */
+export declare const skip: unique symbol;

package/dist/core/internal.js

@@ -0,0 +1,19 @@
+//#region src/core/internal.ts
+/** Connect a camera to a `Klipp`, or disconnect it with `null`. */
+var attachTo = Symbol("attachTo");
+/** Register a raw state in a `Klipp`'s arbitration. Returns a function that unregisters it. */
+var register = Symbol("register");
+var setPriority = Symbol("setPriority");
+var setHints = Symbol("setHints");
+/** Advance a `Klipp`'s arbitration and blend, without running any camera. */
+var advance = Symbol("advance");
+/** Warn when another camera in a `Klipp` already has this camera's name. */
+var checkName = Symbol("checkName");
+/** Pass the viewport size on to a camera's pieces. */
+var prepare = Symbol("prepare");
+/** Run a camera's pieces for one frame. */
+var run = Symbol("run");
+/** Skip a camera this frame, keeping the time for its next run. */
+var skip = Symbol("skip");
+//#endregion
+export { advance, attachTo, checkName, prepare, register, run, setHints, setPriority, skip };

package/dist/core/klippState.d.ts

@@ -0,0 +1,78 @@
+import type { CameraState } from './CameraState.js';
+import type { BlendState } from './blend/blend.js';
+import type { BlendDefinition, CustomBlend } from './blend/BlendDefinition.js';
+import { BlendHints } from './blend/BlendHints.js';
+export type VirtualCameraConfig = {
+    id: string;
+    priority: number;
+    /** Mutable live state read by the core. */
+    state: CameraState;
+    /** Blend hints for transitions involving this camera. */
+    hints?: BlendHints;
+};
+export type KlippCamera = VirtualCameraConfig & {
+    activatedAt: number;
+};
+/** Transition events emitted by the core and virtual camera controllers. */
+export type CameraTransitionEventMap = {
+    /** A camera became the active candidate. */
+    activated: {
+        incoming: string;
+        outgoing: string | null;
+    };
+    /** A camera stopped contributing to output. */
+    deactivated: {
+        outgoing: string;
+    };
+    /** A blend transition started. */
+    blendCreated: {
+        incoming: string;
+        outgoing: string | null;
+    };
+    /** A blend transition finished. */
+    blendFinished: {
+        liveId: string;
+    };
+    /** An instant transition occurred. */
+    cut: {
+        incoming: string;
+        outgoing: string | null;
+    };
+};
+/** Transition events plus `activeIdChanged` / `liveIdChanged`, in the order they happened. */
+export type KlippEvent = {
+    [K in keyof CameraTransitionEventMap]: {
+        type: K;
+    } & CameraTransitionEventMap[K];
+}[keyof CameraTransitionEventMap] | {
+    type: 'activeIdChanged';
+} | {
+    type: 'liveIdChanged';
+};
+export type KlippParams = {
+    /** Used when no `customBlends` entry matches a from→to transition. */
+    defaultBlend: BlendDefinition;
+    customBlends: CustomBlend[];
+};
+export type KlippState = {
+    cameras: Map<string, KlippCamera>;
+    /** Highest-priority camera, the one the output is heading to. */
+    activeId: string | null;
+    activationCounter: number;
+    blend: BlendState<string>;
+    customBlendFromId: string | null;
+    customBlendFromHints: BlendHints;
+    /** Events since the last drain. The caller empties it. */
+    events: KlippEvent[];
+};
+export declare const create: () => KlippState;
+/** Register a camera and return its record, needed to unregister it. */
+export declare function register(state: KlippState, config: VirtualCameraConfig): KlippCamera;
+/** Unregister `camera`, unless its id has since been taken by a newer registration. */
+export declare function unregister(state: KlippState, camera: KlippCamera): void;
+/** Change a camera's priority without restarting the current blend. */
+export declare function setPriority(state: KlippState, id: string, priority: number): void;
+/** Change a camera's blend hints in place. */
+export declare function setHints(state: KlippState, id: string, hints: BlendHints): void;
+/** Head for the active camera, advance the blend and return the reusable output state. */
+export declare function tick(state: KlippState, params: KlippParams, dt: number): CameraState;

package/dist/core/klippState.js

@@ -0,0 +1,124 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { BlendHints } from "./blend/BlendHints.js";
+import { create as create$1, forget, resolveDefinition, setTarget, targetId, tick as tick$1 } from "./blend/blend.js";
+//#region src/core/klippState.ts
+var klippState_exports = /* @__PURE__ */ __exportAll({
+	create: () => create,
+	register: () => register,
+	setHints: () => setHints,
+	setPriority: () => setPriority,
+	tick: () => tick,
+	unregister: () => unregister
+});
+var create = () => ({
+	cameras: /* @__PURE__ */ new Map(),
+	activeId: null,
+	activationCounter: 0,
+	blend: create$1(),
+	customBlendFromId: null,
+	customBlendFromHints: BlendHints.none,
+	events: []
+});
+function recompute(state) {
+	let winner = null;
+	for (const camera of state.cameras.values()) if (!winner || camera.priority > winner.priority || camera.priority === winner.priority && camera.activatedAt > winner.activatedAt) winner = camera;
+	const newActiveId = winner?.id ?? null;
+	if (newActiveId === state.activeId) return;
+	const outgoing = state.activeId;
+	state.activeId = newActiveId;
+	state.events.push({ type: "activeIdChanged" });
+	if (newActiveId !== null) state.events.push({
+		type: "activated",
+		incoming: newActiveId,
+		outgoing
+	});
+}
+function reportLiveIdChange(state, previousLiveId) {
+	if (state.blend.liveId === previousLiveId) return;
+	state.events.push({ type: "liveIdChanged" });
+	if (previousLiveId !== null) state.events.push({
+		type: "deactivated",
+		outgoing: previousLiveId
+	});
+}
+/** Register a camera and return its record, needed to unregister it. */
+function register(state, config) {
+	const camera = {
+		...config,
+		activatedAt: ++state.activationCounter
+	};
+	state.cameras.set(config.id, camera);
+	recompute(state);
+	return camera;
+}
+/** Unregister `camera`, unless its id has since been taken by a newer registration. */
+function unregister(state, camera) {
+	if (state.cameras.get(camera.id) !== camera) return;
+	state.cameras.delete(camera.id);
+	const previousLiveId = state.blend.liveId;
+	forget(state.blend, camera.id);
+	reportLiveIdChange(state, previousLiveId);
+	recompute(state);
+}
+/** Change a camera's priority without restarting the current blend. */
+function setPriority(state, id, priority) {
+	const camera = state.cameras.get(id);
+	if (!camera) return;
+	camera.priority = priority;
+	recompute(state);
+}
+/** Change a camera's blend hints in place. */
+function setHints(state, id, hints) {
+	const camera = state.cameras.get(id);
+	if (camera) camera.hints = hints;
+	if (id === state.customBlendFromId) state.customBlendFromHints = hints;
+}
+/** Start a transition to `incoming`. Returns `true` when it resolved to an instant cut. */
+function retarget(state, params, incoming) {
+	const definition = resolveDefinition(params.customBlends, state.customBlendFromId, incoming, params.defaultBlend);
+	const incomingCamera = state.cameras.get(incoming);
+	const toHints = incomingCamera.hints ?? BlendHints.none;
+	const fromHints = (state.customBlendFromId !== null ? state.cameras.get(state.customBlendFromId) : void 0)?.hints ?? state.customBlendFromHints;
+	const outgoing = targetId(state.blend);
+	const isFirstEver = !state.blend.hasEverActivated;
+	setTarget(state.blend, incoming, incomingCamera.state, definition, fromHints | toHints);
+	state.customBlendFromId = incoming;
+	state.customBlendFromHints = toHints;
+	if (isFirstEver) {
+		state.events.push({
+			type: "cut",
+			incoming,
+			outgoing: null
+		});
+		return false;
+	}
+	state.events.push({
+		type: "blendCreated",
+		incoming,
+		outgoing
+	});
+	if ("damping" in definition || definition.time > 0) return false;
+	state.events.push({
+		type: "cut",
+		incoming,
+		outgoing
+	});
+	return true;
+}
+/** Head for the active camera, advance the blend and return the reusable output state. */
+function tick(state, params, dt) {
+	const blendState = state.blend;
+	const previousLiveId = blendState.liveId;
+	const justCreatedCut = state.activeId !== null && state.activeId !== targetId(blendState) && retarget(state, params, state.activeId);
+	const wasBlending = blendState.transition.active;
+	const targetId$1 = targetId(blendState);
+	const result = tick$1(blendState, dt, targetId$1 !== null ? state.cameras.get(targetId$1).state : null);
+	if (wasBlending && !blendState.transition.active && !justCreatedCut) state.events.push({
+		type: "blendFinished",
+		liveId: blendState.liveId
+	});
+	reportLiveIdChange(state, previousLiveId);
+	return result;
+}
+//#endregion
+export { create, klippState_exports, register, setHints, setPriority, tick, unregister };

package/dist/core/noise/BasicMultiChannelPerlinNoise.d.ts

@@ -0,0 +1,21 @@
+import type { Vec3 } from 'math';
+import type { CameraState } from '../CameraState.js';
+import type { DampingConstant } from '../damping/damping.js';
+import type { PerlinNoiseParams, PerlinNoiseState } from './perlinNoise.js';
+export type PerlinNoiseOptions = Partial<PerlinNoiseParams> & {
+    /** Seed for the six independent Perlin channels. Random when omitted. */
+    seed?: number;
+};
+/** Adds Perlin position and rotation noise to a camera state. */
+export declare class BasicMultiChannelPerlinNoise implements PerlinNoiseParams {
+    positionAmplitude: Vec3;
+    positionFrequency: Vec3;
+    rotationAmplitude: Vec3;
+    rotationFrequency: Vec3;
+    amplitudeGain: number;
+    frequencyGain: number;
+    amplitudeDamping: DampingConstant;
+    readonly state: PerlinNoiseState;
+    constructor(options?: PerlinNoiseOptions);
+    update: (out: CameraState, dt: number, justActivated: boolean) => void;
+}

package/dist/core/noise/BasicMultiChannelPerlinNoise.js

@@ -0,0 +1,13 @@
+import { createParams, createState, update } from "./perlinNoise.js";
+//#region src/core/noise/BasicMultiChannelPerlinNoise.ts
+/** Adds Perlin position and rotation noise to a camera state. */
+var BasicMultiChannelPerlinNoise = class {
+	state;
+	constructor(options) {
+		Object.assign(this, createParams(options));
+		this.state = createState(options?.seed ?? Math.random() * 1e4, this.amplitudeGain);
+	}
+	update = (out, dt, justActivated) => update(out, this.state, this, dt, justActivated);
+};
+//#endregion
+export { BasicMultiChannelPerlinNoise };

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

@@ -0,0 +1,3 @@
+export { BasicMultiChannelPerlinNoise, type PerlinNoiseOptions } from './BasicMultiChannelPerlinNoise.js';
+export * as perlinNoise from './perlinNoise.js';
+export type { PerlinNoiseParams, PerlinNoiseState } from './perlinNoise.js';

package/dist/core/noise/perlinNoise.d.ts

@@ -0,0 +1,36 @@
+import { type Vec3 } from 'math';
+import { perlin2d } from 'math/noise';
+import type { CameraState } from '../CameraState.js';
+import type { DamperState, DampingConstant } from '../damping/damping.js';
+type Generator = ReturnType<typeof perlin2d.create>;
+/** Three position and three rotation noise channels. */
+type Channels = [Generator, Generator, Generator, Generator, Generator, Generator];
+export type PerlinNoiseParams = {
+    /** Per-axis positional shake amplitude in camera-local space. */
+    positionAmplitude: Vec3;
+    /** Per-axis oscillation speed for position noise. */
+    positionFrequency: Vec3;
+    /** Per-axis rotational shake amplitude in degrees. */
+    rotationAmplitude: Vec3;
+    /** Per-axis oscillation speed for rotation noise. */
+    rotationFrequency: Vec3;
+    /** Multiplies every amplitude at once. */
+    amplitudeGain: number;
+    /** Multiplies every channel's frequency. */
+    frequencyGain: number;
+    /** Response time for changes to `amplitudeGain`. */
+    amplitudeDamping: DampingConstant;
+};
+/** Every setting from `settings`, or its default. */
+export declare const createParams: (settings?: Partial<PerlinNoiseParams>) => PerlinNoiseParams;
+export type PerlinNoiseState = {
+    channels: Channels;
+    amplitudeGainDamper: DamperState;
+    effectiveAmplitudeGain: number;
+    positionPhase: Vec3;
+    rotationPhase: Vec3;
+};
+export declare const createState: (seed: number, amplitudeGain?: number) => PerlinNoiseState;
+/** Adds Perlin position and rotation noise to `out`, in camera-local space. */
+export declare function update(out: CameraState, state: PerlinNoiseState, params: PerlinNoiseParams, dt: number, justActivated: boolean): void;
+export {};

package/dist/core/noise/perlinNoise.js

@@ -0,0 +1,110 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { createState as createState$1, damp, reset } from "../damping/damping.js";
+import { withDefaults } from "../params.js";
+import { degreesToRadians, quat, vec3 } from "math";
+import { perlin2d } from "math/noise";
+//#region src/core/noise/perlinNoise.ts
+var perlinNoise_exports = /* @__PURE__ */ __exportAll({
+	createParams: () => createParams,
+	createState: () => createState,
+	update: () => update
+});
+/** Every setting from `settings`, or its default. */
+var createParams = (settings) => withDefaults({
+	positionAmplitude: [
+		0,
+		0,
+		0
+	],
+	positionFrequency: [
+		1,
+		1,
+		1
+	],
+	rotationAmplitude: [
+		0,
+		0,
+		0
+	],
+	rotationFrequency: [
+		1,
+		1,
+		1
+	],
+	amplitudeGain: 1,
+	frequencyGain: 1,
+	amplitudeDamping: 0
+}, settings);
+var createState = (seed, amplitudeGain = 1) => ({
+	channels: [
+		perlin2d.create(seed),
+		perlin2d.create(seed + 1),
+		perlin2d.create(seed + 2),
+		perlin2d.create(seed + 3),
+		perlin2d.create(seed + 4),
+		perlin2d.create(seed + 5)
+	],
+	amplitudeGainDamper: createState$1(),
+	effectiveAmplitudeGain: amplitudeGain,
+	positionPhase: [
+		0,
+		0,
+		0
+	],
+	rotationPhase: [
+		0,
+		0,
+		0
+	]
+});
+var sampleY = .5;
+var scratchOffset = [
+	0,
+	0,
+	0
+];
+var scratchEuler = [
+	0,
+	0,
+	0,
+	"xyz"
+];
+var scratchRotation = [
+	0,
+	0,
+	0,
+	1
+];
+/** Adds Perlin position and rotation noise to `out`, in camera-local space. */
+function update(out, state, params, dt, justActivated) {
+	const { channels, positionPhase, rotationPhase } = state;
+	const frequencyStep = dt * params.frequencyGain;
+	positionPhase[0] += frequencyStep * params.positionFrequency[0];
+	positionPhase[1] += frequencyStep * params.positionFrequency[1];
+	positionPhase[2] += frequencyStep * params.positionFrequency[2];
+	rotationPhase[0] += frequencyStep * params.rotationFrequency[0];
+	rotationPhase[1] += frequencyStep * params.rotationFrequency[1];
+	rotationPhase[2] += frequencyStep * params.rotationFrequency[2];
+	if (justActivated) reset(state.amplitudeGainDamper);
+	if (typeof params.amplitudeDamping === "number" && params.amplitudeDamping <= 0) state.effectiveAmplitudeGain = params.amplitudeGain;
+	else {
+		state.amplitudeGainDamper.value = state.effectiveAmplitudeGain;
+		state.effectiveAmplitudeGain = damp(state.amplitudeGainDamper, params.amplitudeGain, params.amplitudeDamping, dt).value;
+	}
+	const gain = state.effectiveAmplitudeGain;
+	const { positionAmplitude, rotationAmplitude } = params;
+	if (positionAmplitude[0] !== 0 || positionAmplitude[1] !== 0 || positionAmplitude[2] !== 0) {
+		vec3.set(scratchOffset, perlin2d.sample(channels[0], positionPhase[0], sampleY) * positionAmplitude[0], perlin2d.sample(channels[1], positionPhase[1], sampleY) * positionAmplitude[1], perlin2d.sample(channels[2], positionPhase[2], sampleY) * positionAmplitude[2]);
+		vec3.scale(scratchOffset, scratchOffset, gain);
+		vec3.transformQuat(scratchOffset, scratchOffset, out.quaternion);
+		vec3.add(out.position, out.position, scratchOffset);
+	}
+	if (rotationAmplitude[0] !== 0 || rotationAmplitude[1] !== 0 || rotationAmplitude[2] !== 0) {
+		scratchEuler[0] = degreesToRadians(perlin2d.sample(channels[3], rotationPhase[0], sampleY) * rotationAmplitude[0]) * gain;
+		scratchEuler[1] = degreesToRadians(perlin2d.sample(channels[4], rotationPhase[1], sampleY) * rotationAmplitude[1]) * gain;
+		scratchEuler[2] = degreesToRadians(perlin2d.sample(channels[5], rotationPhase[2], sampleY) * rotationAmplitude[2]) * gain;
+		quat.multiply(out.quaternion, out.quaternion, quat.fromEuler(scratchRotation, scratchEuler));
+	}
+}
+//#endregion
+export { createParams, createState, perlinNoise_exports, update };

package/dist/core/params.d.ts

@@ -0,0 +1,2 @@
+/** Fills `defaults` with every value of `settings` that isn't `undefined`, and returns it. */
+export declare function withDefaults<T extends object>(defaults: T, settings: Partial<T> | undefined): T;

package/dist/core/params.js

@@ -0,0 +1,12 @@
+//#region src/core/params.ts
+/** Fills `defaults` with every value of `settings` that isn't `undefined`, and returns it. */
+function withDefaults(defaults, settings) {
+	if (!settings) return defaults;
+	for (const key in defaults) {
+		const value = settings[key];
+		if (value !== void 0) defaults[key] = value;
+	}
+	return defaults;
+}
+//#endregion
+export { withDefaults };

package/dist/dom/DebugOverlay.d.ts

@@ -0,0 +1,11 @@
+import type { DebugZone } from '../core/debug/debugZones.js';
+export type { DebugZone };
+/** Draws framing zones and a crosshair as DOM elements over a canvas container. */
+export declare class DebugOverlay {
+    private root;
+    /** Attaches the overlay to `container`, usually the canvas's parent. Disconnects the old one first. */
+    connect: (container: HTMLElement) => void;
+    disconnect: () => void;
+    /** Replaces what is drawn. Pass no zones and no crosshair to clear it. */
+    render: (zones: readonly DebugZone[], crosshair?: [number, number]) => void;
+}

package/dist/dom/DebugOverlay.js

@@ -0,0 +1,96 @@
+//#region src/dom/DebugOverlay.ts
+var STYLESHEET_ID = "klipp-debug-zone-overlay-styles";
+/** Inject default overlay styles once. */
+function ensureStylesInjected() {
+	if (document.getElementById(STYLESHEET_ID)) return;
+	const style = document.createElement("style");
+	style.id = STYLESHEET_ID;
+	style.textContent = `
+    .klipp-debug-deadzone {
+      box-sizing: border-box;
+      border: 2px solid #33cc33;
+      box-shadow: 0 0 0 100vmax color-mix(in srgb, #33cc33 5%, transparent);
+    }
+    .klipp-debug-hardlimit {
+      box-sizing: border-box;
+      border: 2px solid #cc3333;
+      box-shadow: 0 0 0 100vmax color-mix(in srgb, #cc3333 5%, transparent);
+    }
+    .klipp-debug-groupframing {
+      box-sizing: border-box;
+      border: 2px solid #3399cc;
+      box-shadow: 0 0 0 100vmax color-mix(in srgb, #3399cc 5%, transparent);
+    }
+    .klipp-debug-crosshair { background: #ffcc00; }
+  `;
+	document.head.appendChild(style);
+}
+/** Convert normalized screen coordinates to CSS percentages. */
+function ndcToPercent(ndc, invertY) {
+	return ((invertY ? -ndc : ndc) + 1) * 50;
+}
+function appendLine(root, styles) {
+	const line = document.createElement("div");
+	line.className = "klipp-debug-crosshair";
+	line.style.position = "absolute";
+	Object.assign(line.style, styles);
+	root.appendChild(line);
+}
+/** Draws framing zones and a crosshair as DOM elements over a canvas container. */
+var DebugOverlay = class {
+	root = null;
+	/** Attaches the overlay to `container`, usually the canvas's parent. Disconnects the old one first. */
+	connect = (container) => {
+		this.disconnect();
+		ensureStylesInjected();
+		const root = document.createElement("div");
+		root.style.position = "absolute";
+		root.style.inset = "0";
+		root.style.pointerEvents = "none";
+		root.style.overflow = "hidden";
+		container.appendChild(root);
+		this.root = root;
+	};
+	disconnect = () => {
+		this.root?.remove();
+		this.root = null;
+	};
+	/** Replaces what is drawn. Pass no zones and no crosshair to clear it. */
+	render = (zones, crosshair) => {
+		const root = this.root;
+		if (!root) return;
+		root.replaceChildren();
+		for (const zone of zones) {
+			const halfWidth = zone.size[0] / 2;
+			const halfHeight = zone.size[1] / 2;
+			const left = ndcToPercent(zone.screenPosition[0] - halfWidth, false);
+			const right = ndcToPercent(zone.screenPosition[0] + halfWidth, false);
+			const top = ndcToPercent(zone.screenPosition[1] + halfHeight, true);
+			const bottom = ndcToPercent(zone.screenPosition[1] - halfHeight, true);
+			const box = document.createElement("div");
+			box.className = zone.className;
+			box.style.position = "absolute";
+			box.style.left = `${left}%`;
+			box.style.top = `${top}%`;
+			box.style.width = `${right - left}%`;
+			box.style.height = `${bottom - top}%`;
+			root.appendChild(box);
+		}
+		if (crosshair) {
+			appendLine(root, {
+				left: `${ndcToPercent(crosshair[0], false)}%`,
+				top: "0",
+				bottom: "0",
+				width: "1px"
+			});
+			appendLine(root, {
+				top: `${ndcToPercent(crosshair[1], true)}%`,
+				left: "0",
+				right: "0",
+				height: "1px"
+			});
+		}
+	};
+};
+//#endregion
+export { DebugOverlay };