Code-first video & image, rendered natively on WebGPU.
import { attachInlineSignal, resolveSignalArg } from "./inline-signals.js";
import type {
AnimatableProp,
AnimationTrack,
EaseRef,
LayerAnimationSpec,
SignalClock,
TrackSource,
} from "./schema.js";
/** Common 3D Euler rotation aliases accepted alongside `rotateX` / `rotateY` / `rotateZ`. */
export type AnimatablePropAlias = "rotationX" | "rotationY" | "rotationZ";
export type CanonicalAnimatableProp<
P extends AnimatableProp | AnimatablePropAlias,
> = P extends "rotationX"
? "rotateX"
: P extends "rotationY"
? "rotateY"
: P extends "rotationZ"
? "rotateZ"
: P;
const PROP_ALIASES: Record<AnimatablePropAlias, AnimatableProp> = {
rotationX: "rotateX",
rotationY: "rotateY",
rotationZ: "rotateZ",
};
export function normalizeAnimatableProp(
prop: AnimatableProp | AnimatablePropAlias,
): AnimatableProp {
return (
(PROP_ALIASES as Record<string, AnimatableProp | undefined>)[prop] ??
(prop as AnimatableProp)
);
}
/**
* One keyframe as a tuple: `[frame, value]` or `[frame, value, ease]`. The
* ease shapes the motion arriving at this keyframe from the one before.
*/
export type KeyframeTuple = readonly [
frame: number,
value: number | string | boolean,
ease?: string | EaseRef,
];
export interface FromToOptions {
from?: number;
to?: number;
start?: number;
end?: number;
fromFrame?: number;
toFrame?: number;
durationFrames?: number;
ease?: string | EaseRef;
repeat?: number;
yoyo?: boolean;
}
export interface TrackKeyOptions {
repeat?: number;
yoyo?: boolean;
durationFrames?: number;
}
export interface Tilt3DOptions {
from?: {
rotateX?: number;
rotateY?: number;
rotateZ?: number;
translateZ?: number;
perspective?: number;
};
to: {
rotateX?: number;
rotateY?: number;
rotateZ?: number;
translateZ?: number;
perspective?: number;
};
start?: number;
end?: number;
fromFrame?: number;
toFrame?: number;
ease?: string | EaseRef;
}
export interface SignalTrackOptions {
multiplier?: number;
offset?: number;
smoothing?: number;
channel?: string;
mode?: "continuous" | "accumulate";
threshold?: number;
debounceFrames?: number;
/**
* `"composition"` (default) samples the signal at the composition frame,
* as audio analysis and shared signals need. `"layer"` samples it at the
* layer's own frame, counted from its start like keyframes: for motion
* authored per scene, which then plays right inside `Layer.sequence`.
*/
clock?: SignalClock;
}
export interface ColorSignalOptions {
colorA: string;
colorB: string;
/** Scales the signal before it picks a color (e.g. `1 / 900` for a speed in px/s). Default 1. */
multiplier?: number;
/** Added after `multiplier`. Default 0. */
offset?: number;
colorMode?: "interpolate" | "hueRotate" | "threshold";
threshold?: number;
smoothing?: number;
}
export interface WiggleOptions {
frequency?: number;
amplitude?: number;
octaves?: number;
seed?: number;
}
export interface SpringOptions {
damping?: number;
stiffness?: number;
mass?: number;
}
export interface PathLike3D {
getPointAt(u: number): {
position: [number, number, number];
tangent?: [number, number, number];
};
getFrameAt?(u: number): {
position: [number, number, number];
tangent: [number, number, number];
normal?: [number, number, number];
binormal?: [number, number, number];
rotation?: [number, number, number];
};
totalLength?: number;
}
export interface FollowPathOptions {
fromDistance?: number;
toDistance?: number;
fromProgress?: number;
toProgress?: number;
start?: number;
end?: number;
fromFrame?: number;
toFrame?: number;
autoOrient?: boolean;
banking?: number;
pitchOffset?: number;
yawOffset?: number;
rollOffset?: number;
samples?: number;
ease?: string | EaseRef;
}
export interface CameraFollowPathOptions {
fromProgress?: number;
toProgress?: number;
start?: number;
end?: number;
fromFrame?: number;
toFrame?: number;
mode?: "orientAlongPath" | "lookAtTarget" | "leadTarget";
target?: [number, number, number];
lookAhead?: number;
samples?: number;
ease?: string | EaseRef;
}
const isKeyframeTrack = (t: AnimationTrack) =>
!t.source || t.source.type === "keyframe";
/**
* Merges keyframe tracks that animate the same prop into one sorted track,
* the later key winning on a shared frame. Procedural tracks (signal,
* wiggle, spring…) pass through untouched.
*/
export function mergeAnimationTracks(
tracks: readonly AnimationTrack[],
): AnimationTrack[] {
const out: AnimationTrack[] = [];
const byProp = new Map<string, AnimationTrack>();
for (const t of tracks) {
if (!isKeyframeTrack(t)) {
out.push(t);
continue;
}
const existing = byProp.get(t.prop);
if (!existing) {
const copy = { ...t, keyframes: [...(t.keyframes ?? [])] };
byProp.set(t.prop, copy);
out.push(copy);
continue;
}
const frames = new Map(existing.keyframes.map((k) => [k.frame, k]));
for (const k of t.keyframes ?? []) frames.set(k.frame, k);
existing.keyframes = [...frames.values()].sort((a, b) => a.frame - b.frame);
}
return out;
}
function evaluateEasingProgress(
ease: string | EaseRef | undefined,
t: number,
): number {
if (!ease) return t;
const ref = parseEase(ease);
if (!ref || ref.name === "none") return t;
const { name, dir, params } = ref;
const s = Math.max(0, Math.min(1, t));
const applyDir = (fn: (x: number) => number): number => {
if (dir === "in") return fn(s);
if (dir === "out") return 1 - fn(1 - s);
return s < 0.5 ? fn(s * 2) / 2 : 1 - fn((1 - s) * 2) / 2;
};
switch (name) {
case "power1":
return applyDir((x) => x * x);
case "power2":
return applyDir((x) => x * x * x);
case "power3":
return applyDir((x) => x * x * x * x);
case "sine":
return applyDir((x) => 1 - Math.cos((x * Math.PI) / 2));
case "circ":
return applyDir((x) => 1 - Math.sqrt(Math.max(0, 1 - x * x)));
case "expo":
return applyDir((x) => (x === 0 ? 0 : 2 ** (10 * (x - 1))));
case "back": {
const c1 = params?.[0] ?? 1.70158;
const c3 = c1 + 1;
return applyDir((x) => c3 * x * x * x - c1 * x * x);
}
case "bounce": {
const bounceOut = (x: number): number => {
const n1 = 7.5625;
const d1 = 2.75;
if (x < 1 / d1) return n1 * x * x;
if (x < 2 / d1) {
const x2 = x - 1.5 / d1;
return n1 * x2 * x2 + 0.75;
}
if (x < 2.5 / d1) {
const x2 = x - 2.25 / d1;
return n1 * x2 * x2 + 0.9375;
}
const x2 = x - 2.625 / d1;
return n1 * x2 * x2 + 0.984375;
};
if (dir === "out") return bounceOut(s);
if (dir === "in") return 1 - bounceOut(1 - s);
return s < 0.5
? (1 - bounceOut(1 - 2 * s)) / 2
: (1 + bounceOut(2 * s - 1)) / 2;
}
default:
return s;
}
}
function parseEase(ease?: string | EaseRef): EaseRef | undefined {
if (!ease) return undefined;
if (typeof ease === "object" && "name" in ease && "dir" in ease) return ease;
if (typeof ease === "string") {
const trimmed = ease.trim();
const match = trimmed.match(
/^([a-zA-Z0-9]+)(?:\.([a-zA-Z]+))?(?:\(([^)]+)\))?$/,
);
if (match) {
const rawName = match[1].toLowerCase();
const name = (rawName === "linear" ? "none" : rawName) as EaseRef["name"];
const rawDir = (match[2] || "out").toLowerCase();
let dir: EaseRef["dir"] = "out";
if (rawDir === "in") dir = "in";
else if (rawDir === "out") dir = "out";
else if (rawDir === "inout") dir = "inOut";
let params: number[] | undefined;
if (match[3]) {
params = match[3]
.split(",")
.map((s) => Number.parseFloat(s.trim()))
.filter((n) => !Number.isNaN(n));
}
return { name, dir, ...(params && params.length > 0 ? { params } : {}) };
}
const dotIdx = trimmed.indexOf(".");
if (dotIdx === -1) {
const raw = trimmed.toLowerCase();
const name = (raw === "linear" ? "none" : raw) as EaseRef["name"];
return { name, dir: "out" };
}
const rawName = trimmed.slice(0, dotIdx).toLowerCase();
const name = (rawName === "linear" ? "none" : rawName) as EaseRef["name"];
const rawDir = trimmed.slice(dotIdx + 1).toLowerCase();
let dir: EaseRef["dir"] = "out";
if (rawDir === "in") dir = "in";
else if (rawDir === "out") dir = "out";
else if (rawDir === "inout") dir = "inOut";
return { name, dir };
}
return undefined;
}
/**
* Fluent builder and runtime representation for layer animations.
* Supports chainable keyframes, reactive signal binding, Perlin wiggles, and springs.
*/
export class LayerAnimation<TProp extends AnimatableProp = AnimatableProp>
implements LayerAnimationSpec<TProp>
{
public tracks: AnimationTrack<TProp>[] = [];
/** Hold each value for this many frames (see {@link LayerAnimation.stepped}). */
public frameStep?: number;
public defaultRepeat?: number;
public defaultYoyo?: boolean;
constructor(tracks: AnimationTrack<TProp>[] = []) {
this.tracks = [...tracks];
}
public static create<
P extends AnimatableProp = AnimatableProp,
>(): LayerAnimation<P> {
return new LayerAnimation<P>();
}
public static stepped<P extends AnimatableProp = AnimatableProp>(
frames = 2,
): LayerAnimation<P> {
return new LayerAnimation<P>().stepped(frames);
}
/** See {@link LayerAnimation.stepped}. */
public stepped(frames = 2): this {
this.frameStep = Math.max(1, Math.min(24, Math.round(frames)));
return this;
}
public static fromTo<
P extends AnimatableProp | AnimatablePropAlias = AnimatableProp,
>(
prop: P,
fromValue: number | string | boolean,
toValue: number | string | boolean,
options: FromToOptions = {},
): LayerAnimation<CanonicalAnimatableProp<P>> {
return new LayerAnimation<CanonicalAnimatableProp<P>>().fromTo(
prop,
fromValue,
toValue,
options,
);
}
/** A track from a list of `[frame, value, ease?]` keyframes; see {@link LayerAnimation.keys}. */
public static keys<
P extends AnimatableProp | AnimatablePropAlias = AnimatableProp,
>(
prop: P,
keyframes: readonly KeyframeTuple[],
options?: TrackKeyOptions,
): LayerAnimation<CanonicalAnimatableProp<P>> {
return new LayerAnimation<CanonicalAnimatableProp<P>>().keys(
prop,
keyframes,
options,
);
}
public static signal<
P extends AnimatableProp | AnimatablePropAlias = AnimatableProp,
>(
prop: P,
signalOrHandleId: unknown,
options: SignalTrackOptions = {},
): LayerAnimation<CanonicalAnimatableProp<P>> {
return new LayerAnimation<CanonicalAnimatableProp<P>>().signal(
prop,
signalOrHandleId,
options,
);
}
public static colorSignal<
P extends AnimatableProp | AnimatablePropAlias = AnimatableProp,
>(
prop: P,
signalOrHandleId: unknown,
options: ColorSignalOptions,
): LayerAnimation<CanonicalAnimatableProp<P>> {
return new LayerAnimation<CanonicalAnimatableProp<P>>().colorSignal(
prop,
signalOrHandleId,
options,
);
}
public static kineticSweep(
fromOffset = -1,
toOffset = 1,
startFrame = 0,
endFrame = 24,
ease: string | EaseRef = "power2.out",
): LayerAnimation {
return new LayerAnimation().kineticSweep(
fromOffset,
toOffset,
startFrame,
endFrame,
ease,
);
}
public static typewriter(
startFrame = 0,
endFrame = 30,
ease: string | EaseRef = "linear",
): LayerAnimation {
return new LayerAnimation().typewriter(startFrame, endFrame, ease);
}
public static letterSpacing(
fromSpacing: number,
toSpacing: number,
startFrame = 0,
endFrame = 24,
ease: string | EaseRef = "power2.out",
): LayerAnimation {
return new LayerAnimation().letterSpacing(
fromSpacing,
toSpacing,
startFrame,
endFrame,
ease,
);
}
public static wiggle(
prop: AnimatableProp | AnimatablePropAlias,
options: WiggleOptions = {},
): LayerAnimation {
return new LayerAnimation().wiggle(prop, options);
}
public static spring(
prop: AnimatableProp | AnimatablePropAlias,
options: SpringOptions = {},
): LayerAnimation {
return new LayerAnimation().spring(prop, options);
}
public static firstMargin(
fromMargin: number,
toMargin: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().firstMargin(fromMargin, toMargin, options);
}
public static strokeWidth(
fromWidth: number,
toWidth: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo(
"strokeWidth",
fromWidth,
toWidth,
options,
);
}
public static rotateX(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo("rotateX", fromAngle, toAngle, options);
}
public static rotateY(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo("rotateY", fromAngle, toAngle, options);
}
public static rotateZ(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo("rotateZ", fromAngle, toAngle, options);
}
public static rotationX(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo("rotateX", fromAngle, toAngle, options);
}
public static rotationY(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo("rotateY", fromAngle, toAngle, options);
}
public static rotationZ(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo("rotateZ", fromAngle, toAngle, options);
}
public static rotation(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo("rotation", fromAngle, toAngle, options);
}
public static scale(
fromScale: number,
toScale: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo("scale", fromScale, toScale, options);
}
public static scaleX(
fromScale: number,
toScale: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo("scaleX", fromScale, toScale, options);
}
public static scaleY(
fromScale: number,
toScale: number,
options: FromToOptions = {},
): LayerAnimation {
return new LayerAnimation().fromTo("scaleY", fromScale, toScale, options);
}
public addTrack(track: AnimationTrack<TProp>): this {
this.tracks.push(track);
return this;
}
/**
* Configures repeat count on all tracks, or on a specific prop's track:
* - `-1`: loops indefinitely.
* - `N`: repeats N times after the initial iteration (total N + 1 iterations).
*/
public repeat(count = -1, prop?: AnimatableProp | AnimatablePropAlias): this {
const canonical = prop ? normalizeAnimatableProp(prop) : undefined;
this.defaultRepeat = count;
for (const track of this.tracks) {
if (!canonical || track.prop === canonical) {
track.repeat = count;
}
}
return this;
}
/**
* Enables or disables yoyo (alternate playback direction on each repeat iteration).
*/
public yoyo(
enable = true,
prop?: AnimatableProp | AnimatablePropAlias,
): this {
const canonical = prop ? normalizeAnimatableProp(prop) : undefined;
this.defaultYoyo = enable;
for (const track of this.tracks) {
if (!canonical || track.prop === canonical) {
track.yoyo = enable;
}
}
return this;
}
/**
* Shorthand to loop keyframed animation continuously (infinite repeat).
* If `options.yoyo` is true, oscillates back and forth.
*/
public loop(
options: { yoyo?: boolean } = {},
prop?: AnimatableProp | AnimatablePropAlias,
): this {
this.repeat(-1, prop);
if (options.yoyo) {
this.yoyo(true, prop);
}
return this;
}
/**
* Creates a keyframed track animating from fromValue to toValue.
*/
public fromTo(
rawProp: AnimatableProp | AnimatablePropAlias,
fromValue: number | string | boolean,
toValue: number | string | boolean,
options: FromToOptions = {},
): this {
const prop = normalizeAnimatableProp(rawProp);
const start = options.from ?? options.start ?? options.fromFrame ?? 0;
const end =
options.to ??
options.end ??
options.toFrame ??
(options.durationFrames !== undefined
? start + options.durationFrames
: start + 24);
const ease = parseEase(options.ease);
let track = this.tracks.find(
(t) => t.prop === prop && (!t.source || t.source.type === "keyframe"),
);
if (!track) {
const newTrack: AnimationTrack<TProp> = {
id: `${prop}_fromTo_${this.tracks.length}`,
prop: prop as TProp,
keyframes: [],
...(this.defaultRepeat !== undefined && { repeat: this.defaultRepeat }),
...(this.defaultYoyo !== undefined && { yoyo: this.defaultYoyo }),
};
this.tracks.push(newTrack);
track = newTrack;
}
if (options.repeat !== undefined) track.repeat = options.repeat;
if (options.yoyo !== undefined) track.yoyo = options.yoyo;
if (options.durationFrames !== undefined)
track.durationFrames = options.durationFrames;
const id = track.id;
// If this is the initial keyframe on the track and start > 0, hold fromValue from frame 0
// so that the layer does not flash its un-animated base value before the animation starts.
if (track.keyframes.length === 0 && start > 0) {
track.keyframes.push({
id: `${id}_k0`,
frame: 0,
value: fromValue,
});
}
// Anchor the start of this transition
if (
track.keyframes.length === 0 ||
track.keyframes[track.keyframes.length - 1].frame < start
) {
track.keyframes.push({
id: `${id}_k_${start}`,
frame: start,
value: fromValue,
});
}
// Destination keyframe at end with easing
track.keyframes.push({
id: `${id}_k_${end}`,
frame: end,
value: toValue,
...(ease && { ease }),
});
track.keyframes.sort((a, b) => a.frame - b.frame);
return this;
}
/**
* Appends a keyframe to an existing track for prop, or creates a new track.
*/
public keyframe(
rawProp: AnimatableProp | AnimatablePropAlias,
frame: number,
value: number | string | boolean,
ease?: string | EaseRef,
): this {
const prop = normalizeAnimatableProp(rawProp);
let track = this.tracks.find(
(t) => t.prop === prop && (!t.source || t.source.type === "keyframe"),
);
if (!track) {
const newTrack: AnimationTrack<TProp> = {
id: `${prop}_track_${this.tracks.length}`,
prop: prop as TProp,
keyframes: [],
...(this.defaultRepeat !== undefined && { repeat: this.defaultRepeat }),
...(this.defaultYoyo !== undefined && { yoyo: this.defaultYoyo }),
};
this.tracks.push(newTrack);
track = newTrack;
}
const parsedEase = parseEase(ease);
const kf = {
id: `k_${track.keyframes.length}_f${frame}`,
frame,
value,
...(parsedEase && { ease: parsedEase }),
};
// A key on an occupied frame replaces it (later wins), so behaviours
// can be layered in any order without tripping duplicate-frame errors.
const at = track.keyframes.findIndex((k) => k.frame === frame);
if (at >= 0) track.keyframes[at] = kf;
else track.keyframes.push(kf);
track.keyframes.sort((a, b) => a.frame - b.frame);
return this;
}
/**
* Adds several keyframes to prop's track at once:
* `.keys("scale", [[0, 0], [12, 1.1, "back.out"], [20, 1]])`.
* Frames are rounded to whole frames, so beat math can be passed straight in.
*/
public keys(
rawProp: AnimatableProp | AnimatablePropAlias,
keyframes: readonly KeyframeTuple[],
options?: TrackKeyOptions,
): this {
const prop = normalizeAnimatableProp(rawProp);
for (const [frame, value, ease] of keyframes) {
this.keyframe(prop, Math.round(frame), value, ease);
}
if (options) {
const track = this.tracks.find(
(t) => t.prop === prop && (!t.source || t.source.type === "keyframe"),
);
if (track) {
if (options.repeat !== undefined) track.repeat = options.repeat;
if (options.yoyo !== undefined) track.yoyo = options.yoyo;
if (options.durationFrames !== undefined)
track.durationFrames = options.durationFrames;
}
}
return this;
}
/**
* Animates opacity from 0 to 1 between startFrame and endFrame.
*/
public fadeIn(
startFrame = 0,
endFrame = 20,
ease: string | EaseRef = "power2.out",
): this {
return this.fromTo("opacity", 0, 1, {
from: startFrame,
to: endFrame,
ease,
});
}
/**
* Animates opacity from 1 to 0 between startFrame and endFrame.
*/
public fadeOut(
startFrame: number,
endFrame: number,
ease: string | EaseRef = "power2.in",
): this {
return this.fromTo("opacity", 1, 0, {
from: startFrame,
to: endFrame,
ease,
});
}
/**
* Slides in Y coordinate from fromY to toY.
*/
public slideInY(
fromY: number,
toY: number,
startFrame = 0,
endFrame = 24,
ease: string | EaseRef = "power2.out",
): this {
return this.fromTo("y", fromY, toY, {
from: startFrame,
to: endFrame,
ease,
});
}
/**
* Slides in X coordinate from fromX to toX.
*/
public slideInX(
fromX: number,
toX: number,
startFrame = 0,
endFrame = 24,
ease: string | EaseRef = "power2.out",
): this {
return this.fromTo("x", fromX, toX, {
from: startFrame,
to: endFrame,
ease,
});
}
/**
* Sweeps kinetic typography animator offset from fromOffset to toOffset.
* Cascades per-glyph or per-word transforms across the text.
*/
public kineticSweep(
fromOffset = -1,
toOffset = 1,
startFrame = 0,
endFrame = 24,
ease: string | EaseRef = "power2.out",
): this {
return this.fromTo("offset", fromOffset, toOffset, {
from: startFrame,
to: endFrame,
ease,
});
}
/**
* Progressive character write-on / typewriter text reveal.
*/
public typewriter(
startFrame = 0,
endFrame = 30,
ease: string | EaseRef = "linear",
): this {
return this.fromTo("text", 0, 1, {
from: startFrame,
to: endFrame,
ease,
});
}
/**
* Animates letter-spacing (tracking expansion or compression).
*/
public letterSpacing(
fromSpacing: number,
toSpacing: number,
startFrame = 0,
endFrame = 24,
ease: string | EaseRef = "power2.out",
): this {
return this.fromTo("letterSpacing", fromSpacing, toSpacing, {
from: startFrame,
to: endFrame,
ease,
});
}
/**
* Animates text position along a path via First Margin.
*/
public firstMargin(
fromMargin: number,
toMargin: number,
options: FromToOptions = {},
): this {
return this.fromTo("firstMargin", fromMargin, toMargin, options);
}
/**
* Animates Last Margin spatial limit along a path.
*/
public lastMargin(
fromMargin: number,
toMargin: number,
options: FromToOptions = {},
): this {
return this.fromTo("lastMargin", fromMargin, toMargin, options);
}
/**
* Animates baseline shift perpendicular to curve tangent.
*/
public baselineShift(
fromShift: number,
toShift: number,
options: FromToOptions = {},
): this {
return this.fromTo("baselineShift", fromShift, toShift, options);
}
/**
* Animate rotateX from fromAngle to toAngle.
*/
public rotateX(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): this {
return this.fromTo("rotateX", fromAngle, toAngle, options);
}
/**
* Animate rotateY from fromAngle to toAngle.
*/
public rotateY(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): this {
return this.fromTo("rotateY", fromAngle, toAngle, options);
}
/**
* Animate rotateZ from fromAngle to toAngle.
*/
public rotateZ(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): this {
return this.fromTo("rotateZ", fromAngle, toAngle, options);
}
/** Alias for {@link rotateX}. */
public rotationX(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): this {
return this.fromTo("rotateX", fromAngle, toAngle, options);
}
/** Alias for {@link rotateY}. */
public rotationY(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): this {
return this.fromTo("rotateY", fromAngle, toAngle, options);
}
/** Alias for {@link rotateZ}. */
public rotationZ(
fromAngle: number,
toAngle: number,
options: FromToOptions = {},
): this {
return this.fromTo("rotateZ", fromAngle, toAngle, options);
}
/**
* Animate scale along the X axis.
*/
public scaleX(
fromScale: number,
toScale: number,
options: FromToOptions = {},
): this {
return this.fromTo("scaleX", fromScale, toScale, options);
}
/**
* Animate scale along the Y axis.
*/
public scaleY(
fromScale: number,
toScale: number,
options: FromToOptions = {},
): this {
return this.fromTo("scaleY", fromScale, toScale, options);
}
/**
* Animate uniform scale.
*/
public scale(
fromScale: number,
toScale: number,
options: FromToOptions = {},
): this {
return this.fromTo("scale", fromScale, toScale, options);
}
/**
* Animate perspective camera distance in pixels.
*/
public perspective(
fromDist: number,
toDist: number,
options: FromToOptions = {},
): this {
return this.fromTo("perspective", fromDist, toDist, options);
}
/**
* Animate depth translation (translateZ) in pixels.
*/
public translateZ(
fromZ: number,
toZ: number,
options: FromToOptions = {},
): this {
return this.fromTo("translateZ", fromZ, toZ, options);
}
/**
* Composite helper to tilt a container across multiple 3D axes simultaneously.
*/
public tilt3D(options: Tilt3DOptions): this {
const start = options.start ?? options.fromFrame;
const end = options.end ?? options.toFrame;
const ease = options.ease;
const from = options.from ?? {};
const to = options.to;
const props = [
"rotateX",
"rotateY",
"rotateZ",
"translateZ",
"perspective",
] as const;
for (const prop of props) {
const toVal = to[prop];
if (toVal !== undefined) {
const fromVal = from[prop] ?? 0;
this.fromTo(prop, fromVal, toVal, {
from: start,
to: end,
fromFrame: start,
toFrame: end,
ease,
});
}
}
return this;
}
/**
* Binds an animatable property to a reactive continuous Signal (e.g. LFO, speech energy, audio pitch).
*
* `signalOrHandleId` is either a signal object (`Signal.fromArray`,
* `Signal.builder`, an audio channel …) — carried on the track and
* registered with the program automatically — or the name of a signal
* registered with `comp.addSignal(name, signal)`.
*/
public signal(
rawProp: AnimatableProp | AnimatablePropAlias,
signalOrHandleId: unknown,
options: SignalTrackOptions = {},
): this {
const prop = normalizeAnimatableProp(rawProp);
const { handleId, inline } = resolveSignalArg(signalOrHandleId);
const id = `${prop}_sig_${handleId}_${this.tracks.length}`;
const source: TrackSource = {
type: "signal",
inputHandleId: handleId,
multiplier: options.multiplier ?? 1.0,
offset: options.offset ?? 0.0,
smoothingWindowFrames: options.smoothing ?? 0,
signalMode: options.mode ?? "continuous",
threshold: options.threshold ?? 0.15,
accumulateThreshold: options.threshold ?? 0.15,
debounceFrames: options.debounceFrames ?? 2,
channel: options.channel ?? "primary",
...(options.clock && { clock: options.clock }),
};
if (inline) attachInlineSignal(source, inline);
this.tracks.push({
id,
prop: prop as TProp,
source,
keyframes: [],
});
return this;
}
/**
* Modulates color interpolation based on an active signal (object or
* registered name, as in {@link LayerAnimation.signal}).
*/
public colorSignal(
rawProp: AnimatableProp | AnimatablePropAlias,
signalOrHandleId: unknown,
options: ColorSignalOptions,
): this {
const prop = normalizeAnimatableProp(rawProp);
const { handleId, inline } = resolveSignalArg(signalOrHandleId);
const id = `${prop}_colorSig_${handleId}_${this.tracks.length}`;
const source: TrackSource = {
type: "signal",
inputHandleId: handleId,
multiplier: options.multiplier ?? 1.0,
offset: options.offset ?? 0.0,
smoothingWindowFrames: options.smoothing ?? 0,
colorMode: options.colorMode ?? "interpolate",
colorA: options.colorA,
colorB: options.colorB,
colorThreshold: options.threshold,
channel: "primary",
};
if (inline) attachInlineSignal(source, inline);
this.tracks.push({
id,
prop: prop as TProp,
source,
keyframes: [],
});
return this;
}
/**
* Adds organic Perlin noise wiggling to a property.
*/
public wiggle(
rawProp: AnimatableProp | AnimatablePropAlias,
options: WiggleOptions = {},
): this {
const prop = normalizeAnimatableProp(rawProp);
const id = `${prop}_wiggle_${this.tracks.length}`;
const source: TrackSource = {
type: "wiggle",
frequency: options.frequency ?? 2.0,
amplitude: options.amplitude ?? 20.0,
octaves: options.octaves ?? 1,
seed: options.seed ?? 1234,
};
this.tracks.push({
id,
prop: prop as TProp,
source,
keyframes: [],
});
return this;
}
/**
* Adds physical harmonic spring overshoot behavior to a property transition.
*/
public spring(
rawProp: AnimatableProp | AnimatablePropAlias,
options: SpringOptions = {},
): this {
const prop = normalizeAnimatableProp(rawProp);
const id = `${prop}_spring_${this.tracks.length}`;
const source: TrackSource = {
type: "springOvershoot",
damping: options.damping ?? 12,
stiffness: options.stiffness ?? 180,
mass: options.mass ?? 1,
};
this.tracks.push({
id,
prop: prop as TProp,
source,
keyframes: [],
});
return this;
}
/**
* Follows a 2D or 3D path with constant arc-length velocity, automatic orientation,
* banking into turns, and optional easing.
*/
public followPath(path: PathLike3D, options: FollowPathOptions = {}): this {
const startFrame = options.start ?? options.fromFrame ?? 0;
const endFrame = options.end ?? options.toFrame ?? 60;
const duration = Math.max(1, endFrame - startFrame);
const sampleCount =
options.samples ?? Math.max(8, Math.min(60, Math.round(duration / 2)));
const totalLen = path.totalLength ?? 1;
let fromProg = options.fromProgress ?? 0;
let toProg = options.toProgress ?? 1;
if (options.fromDistance !== undefined && totalLen > 0) {
fromProg = options.fromDistance / totalLen;
}
if (options.toDistance !== undefined && totalLen > 0) {
toProg = options.toDistance / totalLen;
}
const autoOrient = options.autoOrient ?? true;
const banking = options.banking ?? 0;
const pitchOffset = options.pitchOffset ?? 0;
const yawOffset = options.yawOffset ?? 0;
const rollOffset = options.rollOffset ?? 0;
let hasZ = false;
let hasRx = false;
let hasRy = false;
const samples: Array<{
f: number;
x: number;
y: number;
z: number;
rx: number;
ry: number;
rz: number;
}> = [];
for (let i = 0; i <= sampleCount; i++) {
const t = i / sampleCount;
const easedT = evaluateEasingProgress(options.ease, t);
const u = fromProg + easedT * (toProg - fromProg);
const f = Math.round(startFrame + t * duration);
let pos: [number, number, number] = [0, 0, 0];
let tan: [number, number, number] = [1, 0, 0];
let rot: [number, number, number] = [0, 0, 0];
if (typeof path.getFrameAt === "function") {
const frameData = path.getFrameAt(u);
pos = frameData.position;
tan = frameData.tangent;
rot = frameData.rotation ?? [0, 0, 0];
} else {
const pt = path.getPointAt(u);
pos = pt.position;
if (pt.tangent) tan = pt.tangent;
const pitch =
Math.asin(Math.max(-1, Math.min(1, -tan[1]))) * (180 / Math.PI);
const yaw = Math.atan2(tan[0], tan[2]) * (180 / Math.PI);
const roll = Math.atan2(tan[1], tan[0]) * (180 / Math.PI);
rot = [pitch, yaw, roll];
}
const rx = rot[0] + pitchOffset;
const ry = rot[1] + yawOffset;
let rz =
(Math.abs(tan[2]) < 1e-4
? Math.atan2(tan[1], tan[0]) * (180 / Math.PI)
: rot[2]) + rollOffset;
if (banking !== 0) {
const uAhead = Math.min(1, u + 0.02);
const uBehind = Math.max(0, u - 0.02);
const ptAhead = path.getPointAt(uAhead);
const ptBehind = path.getPointAt(uBehind);
const tAhead = ptAhead.tangent ?? [1, 0, 0];
const tBehind = ptBehind.tangent ?? [1, 0, 0];
const yawAhead = Math.atan2(tAhead[0], tAhead[2]);
const yawBehind = Math.atan2(tBehind[0], tBehind[2]);
const dYaw = yawAhead - yawBehind;
rz -= dYaw * banking * 57.2958;
}
if (Math.abs(pos[2]) > 1e-4) hasZ = true;
if (Math.abs(rx) > 1e-4) hasRx = true;
if (Math.abs(ry) > 1e-4) hasRy = true;
samples.push({ f, x: pos[0], y: pos[1], z: pos[2], rx, ry, rz });
}
for (const s of samples) {
this.keyframe("x", s.f, s.x);
this.keyframe("y", s.f, s.y);
if (hasZ) {
this.keyframe("z", s.f, s.z);
}
if (autoOrient) {
this.keyframe("rotateZ", s.f, s.rz);
if (hasRx) this.keyframe("rotateX", s.f, s.rx);
if (hasRy) this.keyframe("rotateY", s.f, s.ry);
}
}
return this;
}
/**
* Attaches this animation to a target LayoutNode and returns the node.
*/
public applyTo<T extends { animation?: LayerAnimationSpec }>(node: T): T {
node.animation = this.toSpec() as unknown as LayerAnimationSpec;
return node;
}
/**
* Folds other animations into this one. Keyframe tracks on the same prop
* merge into one track (a later key wins on a shared frame), so separate
* behaviours — an entrance, presses, a wave — can be authored apart:
* `LayerAnimation.merge(rainIn, presses, wave)`.
*/
public merge(
...others: Array<LayerAnimation | { tracks: AnimationTrack[] }>
): this {
this.tracks = mergeAnimationTracks([
...this.tracks,
...others.flatMap((o) => o.tracks),
]) as unknown as AnimationTrack<TProp>[];
return this;
}
public static merge<P extends AnimatableProp = AnimatableProp>(
...anims: Array<LayerAnimation<P> | { tracks: AnimationTrack<P>[] }>
): LayerAnimation<P> {
const result = new LayerAnimation<P>();
result.tracks = mergeAnimationTracks(
anims.flatMap((o) => o.tracks),
) as unknown as AnimationTrack<P>[];
return result;
}
/**
* Returns the validated LayerAnimation specification object.
*/
public toSpec(): LayerAnimationSpec<TProp> {
return {
tracks: this.tracks,
...(this.frameStep !== undefined && { frameStep: this.frameStep }),
};
}
public toJSON(): LayerAnimationSpec<TProp> {
return this.toSpec();
}
}
export interface DollyOptions {
fromDistance: number;
toDistance: number;
start?: number;
end?: number;
fromFrame?: number;
toFrame?: number;
ease?: string;
}
export interface OrbitOptions {
radius?: { from?: number; to: number };
azimuth?: { from?: number; to: number };
elevation?: { from?: number; to: number };
start?: number;
end?: number;
fromFrame?: number;
toFrame?: number;
ease?: string;
}
export interface RackFocusOptions {
fromDistance: number;
toDistance: number;
fromFStop?: number;
toFStop?: number;
start?: number;
end?: number;
fromFrame?: number;
toFrame?: number;
ease?: string;
}
export interface HandheldOptions {
translationAmplitude: number;
rotationAmplitude: number;
start?: number;
end?: number;
fromFrame?: number;
toFrame?: number;
}
export class CameraAnimation extends LayerAnimation {
public static camera(): CameraAnimation {
return new CameraAnimation();
}
public dolly(
fromDistanceOrOptions: number | DollyOptions,
toDistance?: number,
options: FromToOptions = {},
): this {
if (typeof fromDistanceOrOptions === "object") {
const opts = fromDistanceOrOptions;
const start = opts.start ?? opts.fromFrame ?? 0;
const end = opts.end ?? opts.toFrame ?? 0;
return this.fromTo("cameraZ", opts.fromDistance, opts.toDistance, {
from: start,
to: end,
ease: opts.ease,
});
}
return this.fromTo(
"cameraZ",
fromDistanceOrOptions,
toDistance ?? fromDistanceOrOptions,
options,
);
}
public orbit(options: OrbitOptions): this {
const start = options.start ?? options.fromFrame ?? 0;
const end = options.end ?? options.toFrame ?? 0;
if (options.azimuth) {
this.fromTo(
"orbitAzimuth",
options.azimuth.from ?? 0,
options.azimuth.to,
{
from: start,
to: end,
ease: options.ease,
},
);
}
if (options.elevation) {
this.fromTo(
"orbitElevation",
options.elevation.from ?? 0,
options.elevation.to,
{
from: start,
to: end,
ease: options.ease,
},
);
}
if (options.radius) {
this.fromTo(
"orbitRadius",
options.radius.from ?? 1500,
options.radius.to,
{
from: start,
to: end,
ease: options.ease,
},
);
}
return this;
}
public truck(fromX: number, toX: number, options: FromToOptions = {}): this {
return this.fromTo("cameraX", fromX, toX, options);
}
public pedestal(
fromY: number,
toY: number,
options: FromToOptions = {},
): this {
return this.fromTo("cameraY", fromY, toY, options);
}
public pan(
fromAngleDeg: number,
toAngleDeg: number,
options: FromToOptions = {},
): this {
return this.fromTo("cameraYaw", fromAngleDeg, toAngleDeg, options);
}
public tilt(
fromAngleDeg: number,
toAngleDeg: number,
options: FromToOptions = {},
): this {
return this.fromTo("cameraPitch", fromAngleDeg, toAngleDeg, options);
}
public roll(
fromAngleDeg: number,
toAngleDeg: number,
options: FromToOptions = {},
): this {
return this.fromTo("cameraRoll", fromAngleDeg, toAngleDeg, options);
}
public rackFocus(options: RackFocusOptions): this {
const start = options.start ?? options.fromFrame ?? 0;
const end = options.end ?? options.toFrame ?? 0;
this.fromTo("focusDistance", options.fromDistance, options.toDistance, {
from: start,
to: end,
ease: options.ease ?? "power2.inOut",
});
if (options.toFStop !== undefined) {
this.fromTo("fStop", options.fromFStop ?? 2.8, options.toFStop, {
from: start,
to: end,
ease: options.ease ?? "power2.inOut",
});
}
return this;
}
public handheld(options: HandheldOptions): this {
const start = options.start ?? options.fromFrame ?? 0;
const end = options.end ?? options.toFrame ?? 0;
this.fromTo("shakeTranslation", 0, options.translationAmplitude, {
from: start,
to: end,
});
this.fromTo("shakeRotation", 0, options.rotationAmplitude, {
from: start,
to: end,
});
return this;
}
/**
* Animates camera eye and lookAt target along a 3D path with constant velocity,
* leading target look-ahead, or path tangent orientation.
*/
public followPath3D(
path: PathLike3D,
options: CameraFollowPathOptions = {},
): this {
const startFrame = options.start ?? options.fromFrame ?? 0;
const endFrame = options.end ?? options.toFrame ?? 60;
const duration = Math.max(1, endFrame - startFrame);
const sampleCount =
options.samples ?? Math.max(8, Math.min(60, Math.round(duration / 2)));
const mode =
options.mode ?? (options.target ? "lookAtTarget" : "leadTarget");
const fromProg = options.fromProgress ?? 0;
const toProg = options.toProgress ?? 1;
const lookAhead = options.lookAhead ?? 0.05;
for (let i = 0; i <= sampleCount; i++) {
const t = i / sampleCount;
const easedT = evaluateEasingProgress(options.ease, t);
const u = fromProg + easedT * (toProg - fromProg);
const f = Math.round(startFrame + t * duration);
let pos: [number, number, number] = [0, 0, 0];
let rot: [number, number, number] = [0, 0, 0];
if (typeof path.getFrameAt === "function") {
const frameData = path.getFrameAt(u);
pos = frameData.position;
rot = frameData.rotation ?? [0, 0, 0];
} else {
const pt = path.getPointAt(u);
pos = pt.position;
}
this.keyframe("cameraX", f, pos[0]);
this.keyframe("cameraY", f, pos[1]);
this.keyframe("cameraZ", f, pos[2]);
if (mode === "lookAtTarget") {
const tgt = options.target ?? [pos[0], pos[1], 0];
this.keyframe("targetX", f, tgt[0]);
this.keyframe("targetY", f, tgt[1]);
this.keyframe("targetZ", f, tgt[2]);
} else if (mode === "leadTarget") {
const leadU = Math.min(1, u + lookAhead);
const leadPt = path.getPointAt(leadU);
this.keyframe("targetX", f, leadPt.position[0]);
this.keyframe("targetY", f, leadPt.position[1]);
this.keyframe("targetZ", f, leadPt.position[2]);
} else if (mode === "orientAlongPath") {
this.keyframe("cameraPitch", f, rot[0]);
this.keyframe("cameraYaw", f, rot[1]);
this.keyframe("cameraRoll", f, rot[2]);
}
}
return this;
}
}