@anvpx/motion-scenes 0.0.0-stage → 0.1.1

package/dist/registry.js

@@ -0,0 +1,68 @@
+import { bugScene } from "./scenes/bug/index.js";
+import { bulletsScene } from "./scenes/bullets/index.js";
+import { calloutScene } from "./scenes/callout/index.js";
+import { captionScene } from "./scenes/caption/index.js";
+import { chapterScene } from "./scenes/chapter/index.js";
+import { chartScene } from "./scenes/chart/index.js";
+import { codeScene } from "./scenes/code/index.js";
+import { compareScene } from "./scenes/compare/index.js";
+import { countdownScene } from "./scenes/countdown/index.js";
+import { flowScene } from "./scenes/flow/index.js";
+import { heroScene } from "./scenes/hero/index.js";
+import { iconGridScene } from "./scenes/icon-grid/index.js";
+import { kineticScene } from "./scenes/kinetic/index.js";
+import { kpiGridScene } from "./scenes/kpi-grid/index.js";
+import { lowerThirdScene } from "./scenes/lower-third/index.js";
+import { mediaFrameScene } from "./scenes/media-frame/index.js";
+import { outroScene } from "./scenes/outro/index.js";
+import { posterScene } from "./scenes/poster/index.js";
+import { progressScene } from "./scenes/progress/index.js";
+import { quoteScene } from "./scenes/quote/index.js";
+import { scene3dScene } from "./scenes/scene3d/index.js";
+import { statScene } from "./scenes/stat/index.js";
+import { stepsScene } from "./scenes/steps/index.js";
+import { stickerScene } from "./scenes/sticker/index.js";
+import { tableScene } from "./scenes/table/index.js";
+import { timelineScene } from "./scenes/timeline/index.js";
+import { titleScene } from "./scenes/title/index.js";
+import { waveformScene } from "./scenes/waveform/index.js";
+/** The single list of scenes: adding a scene is one import and one entry here. */
+const plugins = [
+    titleScene,
+    heroScene,
+    posterScene,
+    bulletsScene,
+    statScene,
+    flowScene,
+    outroScene,
+    lowerThirdScene,
+    bugScene,
+    progressScene,
+    countdownScene,
+    chapterScene,
+    captionScene,
+    compareScene,
+    calloutScene,
+    quoteScene,
+    iconGridScene,
+    stepsScene,
+    timelineScene,
+    mediaFrameScene,
+    kineticScene,
+    codeScene,
+    kpiGridScene,
+    chartScene,
+    tableScene,
+    scene3dScene,
+    stickerScene,
+    waveformScene,
+];
+export const sceneRegistry = new Map(plugins.map((plugin) => [plugin.type, plugin]));
+export const sceneTypes = [...sceneRegistry.keys()];
+export const getScene = (type) => {
+    const plugin = sceneRegistry.get(type);
+    if (!plugin) {
+        throw new Error(`unknown scene type "${type}"; use one of: ${sceneTypes.join("|")}`);
+    }
+    return plugin;
+};

package/dist/runtime/compose.d.ts

@@ -0,0 +1,21 @@
+export { clamp01, ease } from "./easing.js";
+/**
+ * Normalized interval in seconds. A zero duration is an instantaneous cut;
+ * negative durations are invalid. No prior samples or DOM state are read.
+ * @param {number} time
+ * @param {number} start
+ * @param {number} duration
+ */
+export declare const progress: (time: number, start: number, duration: number) => number;
+/** Numeric interpolation; amount may overshoot for spring or anticipation.
+ * @param {number} from
+ * @param {number} to
+ * @param {number} amount
+ */
+export declare const interpolate: (from: number, to: number, amount: number) => number;
+/** Start time for an item. A negative step expresses a reversed order.
+ * @param {number} index non-negative integer
+ * @param {number} step seconds between items
+ * @param {number} [start=0] first item's time
+ */
+export declare const stagger: (index: number, step: number, start?: number) => number;

package/dist/runtime/compose.js

@@ -0,0 +1,43 @@
+// @ts-check
+// Style-neutral authoring helpers. Every sample depends only on its inputs.
+export { clamp01, ease } from "./easing.js";
+/** @param {number[]} values */
+const finite = (...values) => {
+    if (!values.every(Number.isFinite))
+        throw new RangeError("composition inputs must be finite");
+};
+/**
+ * Normalized interval in seconds. A zero duration is an instantaneous cut;
+ * negative durations are invalid. No prior samples or DOM state are read.
+ * @param {number} time
+ * @param {number} start
+ * @param {number} duration
+ */
+export const progress = (time, start, duration) => {
+    finite(time, start, duration);
+    if (duration < 0)
+        throw new RangeError("duration must be non-negative");
+    if (duration === 0)
+        return time < start ? 0 : 1;
+    return Math.max(0, Math.min(1, (time - start) / duration));
+};
+/** Numeric interpolation; amount may overshoot for spring or anticipation.
+ * @param {number} from
+ * @param {number} to
+ * @param {number} amount
+ */
+export const interpolate = (from, to, amount) => {
+    finite(from, to, amount);
+    return from + (to - from) * amount;
+};
+/** Start time for an item. A negative step expresses a reversed order.
+ * @param {number} index non-negative integer
+ * @param {number} step seconds between items
+ * @param {number} [start=0] first item's time
+ */
+export const stagger = (index, step, start = 0) => {
+    if (!Number.isInteger(index) || index < 0)
+        throw new RangeError("index must be a non-negative integer");
+    finite(step, start);
+    return start + index * step;
+};

package/dist/runtime/easing.d.ts

@@ -0,0 +1,14 @@
+export type EaseFn = (t: number) => number;
+/** @typedef {(t: number) => number} EaseFn */
+/** Clamp to [0, 1]; non-finite input maps to 0.
+ * @param {number} t
+ * @returns {number}
+ */
+export declare const clamp01: (t: number) => number;
+export declare const EASE_NAMES: string[];
+/**
+ * @param {string} name one of EASE_NAMES
+ * @param {number} t progress, clamped to [0, 1]
+ * @returns {number}
+ */
+export declare const ease: (name: string, t: number) => number;

package/dist/runtime/easing.js

@@ -0,0 +1,45 @@
+// @ts-check
+// Pure easing functions: no DOM, no clock, no state.
+/** @typedef {(t: number) => number} EaseFn */
+/** Clamp to [0, 1]; non-finite input maps to 0.
+ * @param {number} t
+ * @returns {number}
+ */
+export const clamp01 = (t) => (t > 0 ? Math.min(t, 1) : 0);
+/** Normalised settle time of the closed-form spring response. */
+const SPRING_SPAN = 1;
+/**
+ * Closed-form underdamped spring step response, rescaled so f(1) = 1 exactly.
+ * @param {number} damping damping ratio, 0 < damping < 1
+ * @param {number} omega natural frequency over the normalised span
+ * @returns {EaseFn}
+ */
+const spring = (damping, omega) => {
+    const decay = damping * omega;
+    const damped = omega * Math.sqrt(1 - damping * damping);
+    /** @param {number} x */
+    const step = (x) => 1 - Math.exp(-decay * x) * (Math.cos(damped * x) + (decay / damped) * Math.sin(damped * x));
+    const settled = step(SPRING_SPAN);
+    return (t) => step(t * SPRING_SPAN) / settled;
+};
+/** @type {Readonly<Record<string, EaseFn>>} */
+const EASINGS = {
+    linear: (t) => t,
+    in: (t) => t * t * t,
+    out: (t) => 1 - (1 - t) ** 3,
+    "in-out": (t) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2),
+    "spring-soft": spring(0.85, 9),
+    "spring-snappy": spring(0.6, 14),
+};
+export const EASE_NAMES = Object.keys(EASINGS);
+/**
+ * @param {string} name one of EASE_NAMES
+ * @param {number} t progress, clamped to [0, 1]
+ * @returns {number}
+ */
+export const ease = (name, t) => {
+    const fn = EASINGS[name];
+    if (!fn)
+        throw new Error(`unknown ease "${name}"; use one of: ${EASE_NAMES.join("|")}`);
+    return fn(clamp01(t));
+};

package/dist/runtime/mount.d.ts

@@ -0,0 +1,50 @@
+export type SceneConfig = {
+    ease?: string;
+    move?: string;
+    focus?: string;
+};
+export type RuntimeContext = {
+    fps?: number;
+    duration?: number;
+};
+export type Plan = import("./timeline.js").Plan;
+export type Runtime = {
+    seek(t: number): void;
+    dispose(): void;
+    ready: Promise<void>;
+};
+export type CreateScene = (root: HTMLElement, config: SceneConfig, ctx: RuntimeContext) => Runtime;
+export type Counter = {
+    el: HTMLElement;
+    text: string;
+    track: import("./timeline.js").Track;
+};
+export type Item = {
+    el: HTMLElement | SVGElement;
+    kind: string;
+    keys: string;
+    track: import("./timeline.js").Track;
+};
+/**
+ * Mounts every [data-anim] element of a scene fragment on one entrance timeline.
+ * @param {HTMLElement} root
+ * @param {SceneConfig} config
+ * @param {RuntimeContext} ctx
+ * @param {Plan} plan
+ * @returns {Runtime}
+ */
+export declare const mountTimeline: (root: HTMLElement, config: SceneConfig, ctx: RuntimeContext, plan: Plan) => Runtime;
+/**
+ * An overlay: the entrance timeline plus an eased fade of the whole layer in and out of its
+ * time span. `hooks.update(t)` draws scene-specific state; `hooks.reset()` undoes it on dispose.
+ * @param {HTMLElement} root
+ * @param {SceneConfig} config
+ * @param {RuntimeContext} ctx
+ * @param {Plan} plan
+ * @param {{ update?: (t: number) => void, reset?: () => void }} [hooks]
+ * @returns {Runtime}
+ */
+export declare const mountOverlay: (root: HTMLElement, config: SceneConfig, ctx: RuntimeContext, plan: Plan, hooks?: {
+    update?: (t: number) => void;
+    reset?: () => void;
+}) => Runtime;

package/dist/runtime/mount.js

@@ -0,0 +1,153 @@
+// @ts-check
+// Thin DOM layer: seek(t) writes styles as a pure function of t.
+import { cameraScale, countScale, countText, countTrack, dimOpacity, driftOf, entranceState, entranceTrack, overlayEnvelope, sample, } from "./timeline.js";
+/** @typedef {{ ease?: string, move?: string, focus?: string }} SceneConfig */
+/** @typedef {{ fps?: number, duration?: number }} RuntimeContext */
+/** @typedef {import("./timeline.js").Plan} Plan */
+/** @typedef {{ seek(t: number): void, dispose(): void, ready: Promise<void> }} Runtime */
+/** @typedef {(root: HTMLElement, config: SceneConfig, ctx: RuntimeContext) => Runtime} CreateScene */
+/** @typedef {{ el: HTMLElement, text: string, track: import("./timeline.js").Track }} Counter */
+/** @typedef {{ el: HTMLElement | SVGElement, kind: string, keys: string, track: import("./timeline.js").Track }} Item */
+const DEFAULT_FPS = 30;
+/**
+ * Config and ctx win over the data-* attributes the emitter put on the root.
+ * @param {HTMLElement} root
+ * @param {SceneConfig} config
+ * @param {RuntimeContext} ctx
+ */
+const readSettings = (root, config, ctx) => ({
+    ease: config.ease ?? root.dataset.ease ?? "out",
+    move: config.move ?? root.dataset.move ?? "static",
+    focus: config.focus ?? root.dataset.focus ?? "",
+    fps: ctx.fps ?? Number(root.dataset.fps ?? DEFAULT_FPS),
+    duration: ctx.duration ?? Number(root.dataset.duration ?? 0),
+});
+/**
+ * @param {HTMLElement} root
+ * @param {ReturnType<typeof readSettings>} settings
+ * @param {Plan} plan
+ * @returns {Item[]}
+ */
+const collectItems = (root, settings, plan) => Array.from(root.querySelectorAll("[data-anim]"), (node) => {
+    const el = /** @type {HTMLElement | SVGElement} */ (node);
+    const step = Number(el.dataset.step ?? 0);
+    return {
+        el,
+        kind: el.dataset.anim ?? "rise",
+        keys: el.dataset.focusKey ?? "",
+        track: entranceTrack(step, plan, settings.fps, settings.ease),
+    };
+});
+/**
+ * @param {Item} item
+ * @param {number} t
+ * @param {string} focus
+ * @param {number} rise
+ */
+const applyItem = (item, t, focus, rise) => {
+    const state = entranceState(item.kind, sample(item.track, t), rise);
+    item.el.style.opacity = String(state.opacity * dimOpacity(focus, item.keys));
+    if (item.kind === "rise")
+        item.el.style.transform = `translateY(${state.y}px)`;
+    if (item.kind === "draw")
+        item.el.style.strokeDashoffset = String(state.dash);
+    if (item.kind === "grow")
+        item.el.style.transform = `scaleX(${state.scale})`;
+};
+/** @param {Item} item */
+const clearItem = (item) => {
+    for (const name of ["opacity", "transform", "stroke-dashoffset"]) {
+        item.el.style.removeProperty(name);
+    }
+};
+/**
+ * Elements whose text counts up to the number they carry in data-count.
+ * @param {HTMLElement} root
+ * @param {ReturnType<typeof readSettings>} settings
+ * @param {Plan} plan
+ * @returns {Counter[]}
+ */
+const collectCounters = (root, settings, plan) => Array.from(root.querySelectorAll("[data-count]"), (node) => {
+    const el = /** @type {HTMLElement} */ (node);
+    const step = Number(el.dataset.step ?? 0);
+    return {
+        el,
+        text: el.dataset.count ?? "",
+        track: countTrack(step, plan, settings.fps, settings.ease, settings.duration),
+    };
+});
+/**
+ * @param {Counter} counter
+ * @param {number} t
+ */
+const applyCounter = (counter, t) => {
+    const progress = sample(counter.track, t);
+    counter.el.textContent = countText(counter.text, progress);
+    counter.el.style.transform = `scale(${countScale(progress)})`;
+};
+/**
+ * @param {HTMLElement} root
+ * @returns {Promise<void>}
+ */
+const fontsReady = (root) => root.ownerDocument.fonts?.ready.then(() => undefined) ?? Promise.resolve();
+/**
+ * Mounts every [data-anim] element of a scene fragment on one entrance timeline.
+ * @param {HTMLElement} root
+ * @param {SceneConfig} config
+ * @param {RuntimeContext} ctx
+ * @param {Plan} plan
+ * @returns {Runtime}
+ */
+export const mountTimeline = (root, config, ctx, plan) => {
+    const settings = readSettings(root, config, ctx);
+    const items = collectItems(root, settings, plan);
+    const counters = collectCounters(root, settings, plan);
+    /** @param {number} t */
+    const seek = (t) => {
+        for (const item of items)
+            applyItem(item, t, settings.focus, plan.rise);
+        for (const counter of counters)
+            applyCounter(counter, t);
+        root.style.setProperty("--drift", String(driftOf(t)));
+        root.style.transform = `scale(${cameraScale(settings.move, t, settings.duration)})`;
+    };
+    const dispose = () => {
+        for (const item of items)
+            clearItem(item);
+        for (const counter of counters) {
+            counter.el.textContent = counter.text;
+            counter.el.style.removeProperty("transform");
+        }
+        root.style.removeProperty("transform");
+        root.style.removeProperty("--drift");
+    };
+    seek(0);
+    return { seek, dispose, ready: fontsReady(root) };
+};
+/**
+ * An overlay: the entrance timeline plus an eased fade of the whole layer in and out of its
+ * time span. `hooks.update(t)` draws scene-specific state; `hooks.reset()` undoes it on dispose.
+ * @param {HTMLElement} root
+ * @param {SceneConfig} config
+ * @param {RuntimeContext} ctx
+ * @param {Plan} plan
+ * @param {{ update?: (t: number) => void, reset?: () => void }} [hooks]
+ * @returns {Runtime}
+ */
+export const mountOverlay = (root, config, ctx, plan, hooks = {}) => {
+    const settings = readSettings(root, config, ctx);
+    const inner = mountTimeline(root, config, ctx, plan);
+    /** @param {number} t */
+    const seek = (t) => {
+        inner.seek(t);
+        root.style.opacity = String(overlayEnvelope(t, settings.duration, settings.ease));
+        hooks.update?.(t);
+    };
+    const dispose = () => {
+        inner.dispose();
+        root.style.removeProperty("opacity");
+        hooks.reset?.();
+    };
+    seek(0);
+    return { seek, dispose, ready: inner.ready };
+};

package/dist/runtime/timeline.d.ts

@@ -0,0 +1,147 @@
+export type Track = {
+    from: number;
+    to: number;
+    start: number;
+    end: number;
+    ease: string;
+};
+export type Plan = {
+    baseDelay: number;
+    staggerFrames: number;
+    rise: number;
+};
+export type EntranceState = {
+    opacity: number;
+    y: number;
+    dash: number;
+    scale: number;
+};
+/** @typedef {{ from: number, to: number, start: number, end: number, ease: string }} Track */
+/** @typedef {{ baseDelay: number, staggerFrames: number, rise: number }} Plan */
+/** @typedef {{ opacity: number, y: number, dash: number, scale: number }} EntranceState */
+export declare const ENTRANCE_SECONDS = 0.6;
+export declare const MIN_STAGGER_FRAMES = 3;
+export declare const MAX_STAGGER_FRAMES = 6;
+export declare const COUNT_SECONDS = 1.4;
+/** Share of the scene a count-up may take, and its ceiling in seconds. */
+export declare const COUNT_SHARE = 0.25;
+export declare const MAX_COUNT_SECONDS = 3;
+/** Opacity of a "rise" element at progress 0, so no scene opens on a blank frame. */
+export declare const RISE_FLOOR = 0.45;
+/** Size of a counting number at progress 0, relative to its final size. */
+export declare const COUNT_SCALE_FROM = 0.7;
+/** Fade-in and fade-out length of an overlay window, in seconds. */
+export declare const ENVELOPE_SECONDS = 0.4;
+/** Extra size of a countdown number at the start of each step. */
+export declare const PULSE_SCALE = 0.25;
+/**
+ * Value of a single-segment track at time t (seconds).
+ * @param {Track} track
+ * @param {number} t
+ * @returns {number}
+ */
+export declare const sample: (track: Track, t: number) => number;
+/**
+ * Stagger between consecutive steps, in seconds, from a frame count.
+ * @param {number} frames 3-6
+ * @param {number} fps
+ * @returns {number}
+ */
+export declare const staggerSeconds: (frames: number, fps: number) => number;
+/**
+ * Progress track (0 -> 1) of the entrance of step `step`.
+ * @param {number} step
+ * @param {Plan} plan
+ * @param {number} fps
+ * @param {string} easing
+ * @returns {Track}
+ */
+export declare const entranceTrack: (step: number, plan: Plan, fps: number, easing: string) => Track;
+/**
+ * Visual state of an element kind at entrance progress p.
+ * @param {string} kind rise | fade | draw | grow
+ * @param {number} p progress; may overshoot for springs
+ * @param {number} rise rise distance in px
+ * @returns {EntranceState}
+ */
+export declare const entranceState: (kind: string, p: number, rise: number) => EntranceState;
+/**
+ * Count-up length: COUNT_SECONDS, stretched to a quarter of a long scene (max MAX_COUNT_SECONDS).
+ * @param {number} duration scene seconds; 0 or unknown keeps COUNT_SECONDS
+ * @returns {number}
+ */
+export declare const countSeconds: (duration: number) => number;
+/**
+ * Track of a count-up that starts with the entrance of `step`.
+ * @param {number} step
+ * @param {Plan} plan
+ * @param {number} fps
+ * @param {string} easing
+ * @param {number} [duration] scene seconds
+ * @returns {Track}
+ */
+export declare const countTrack: (step: number, plan: Plan, fps: number, easing: string, duration?: number) => Track;
+/**
+ * Scale of a counting number at count progress p: grows from COUNT_SCALE_FROM to 1.
+ * @param {number} p
+ * @returns {number}
+ */
+export declare const countScale: (p: number) => number;
+/**
+ * The first number of `text` scaled to progress p, keeping prefix, suffix, decimals and
+ * thousands separators; p >= 1 and text without one leading number return `text` verbatim.
+ * @param {string} text
+ * @param {number} p
+ * @returns {string}
+ */
+export declare const countText: (text: string, p: number) => string;
+/**
+ * Slow background drift in [-1, 1]: one cycle every ~18 s.
+ * @param {number} t seconds
+ * @returns {number}
+ */
+export declare const driftOf: (t: number) => number;
+/**
+ * Root scale of the supported camera moves; other moves are applied by the build.
+ * @param {string} move
+ * @param {number} t
+ * @param {number} duration
+ * @returns {number}
+ */
+export declare const cameraScale: (move: string, t: number, duration: number) => number;
+/**
+ * Opacity multiplier of `focus`: elements outside the focus dim.
+ * @param {string} focus focused key; empty means no focus
+ * @param {string} keys space-separated keys of the element; empty means never dim
+ * @returns {number}
+ */
+export declare const dimOpacity: (focus: string, keys: string) => number;
+/**
+ * Opacity of an overlay at local time t: eased fade in, hold, eased fade out.
+ * @param {number} t seconds from the start of the overlay window
+ * @param {number} duration window length in seconds
+ * @param {string} easing
+ * @returns {number}
+ */
+export declare const overlayEnvelope: (t: number, duration: number, easing: string) => number;
+/**
+ * Countdown value and pulse scale at local time t: one equal step per integer from -> to.
+ * @param {number} t
+ * @param {number} duration
+ * @param {number} from
+ * @param {number} to
+ * @returns {{ value: number, scale: number }}
+ */
+export declare const countdownState: (t: number, duration: number, from: number, to: number) => {
+    value: number;
+    scale: number;
+};
+/**
+ * Linear value from -> to across the duration (progress bars).
+ * @param {number} t
+ * @param {number} duration
+ * @param {number} from
+ * @param {number} to
+ * @returns {number}
+ */
+export declare const spanProgress: (t: number, duration: number, from: number, to: number) => number;