solid-drift 0.7.1 → 0.8.0

package/dist/ai.js

@@ -0,0 +1,570 @@
+/**
+ * Streaming-text and agent-state family: motion primitives for
+ * conversational interfaces.
+ *
+ * Token streams arrive in bursts, so `createStreamReveal` batches them
+ * into a readable cadence before animating each unit's entrance.
+ * `createAgentState` is a pure-signal state machine for agent
+ * status, kept free of motion so each state can pair with any
+ * primitive. `parseDriftSpec` and `createSpecPlayer` let generated
+ * JSON choreography be validated and rendered deterministically.
+ *
+ * All primitives are signal-native, SSR-safe, dependency-free, and
+ * define sensible static behavior under `prefers-reduced-motion`.
+ */
+import { createSignal, onCleanup, } from "solid-js";
+import { animate } from "./animate.js";
+import { resolveEasing } from "./easing.js";
+import { now, schedule } from "./engine.js";
+import { createBeat, createCamera, createColorShift, createKineticType, createTransition, } from "./motion.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+import { appendUnits } from "./text.js";
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/** Round to 2 decimals for style values. */
+function fmt(v) {
+    return String(Math.round(v * 100) / 100);
+}
+/**
+ * Smooth irregular token cadence into readable animated text.
+ *
+ * Stream tokens arrive in bursts, a flood, then silence. `push()`
+ * only appends to an internal queue; one rAF task flushes the queue
+ * on a steady cadence (or early when it overflows) and drives every
+ * unit's entrance, so a 40-token burst reads as a calm typed line
+ * instead of a flicker.
+ *
+ * SSR-safe: `push` is a no-op on the server, `status()` is "done",
+ * and the host renders the full text statically. Under reduced motion
+ * batching and entrances are skipped: text appears as it is pushed.
+ *
+ * ```tsx
+ * let out!: HTMLDivElement
+ * const stream = createStreamReveal(() => out, { unit: "chars" })
+ * const reader = response.body.getReader()
+ * onMount(async () => {
+ *   for (;;) {
+ *     const { done, value } = await reader.read()
+ *     if (done) break
+ *     stream.push(decoder.decode(value))
+ *   }
+ *   stream.complete()
+ * })
+ * <div ref={out} aria-live="polite" />
+ * ```
+ */
+export function createStreamReveal(ref, options = {}) {
+    const { unit = "chars", batchMs = 120, maxBatch = 24, duration = 450, stagger = 30, easing: easingOpt = "easeOutExpo", } = options;
+    const from = {
+        y: options.from?.y ?? 28,
+        blur: options.from?.blur ?? 10,
+        scale: options.from?.scale ?? 0.85,
+        opacity: options.from?.opacity ?? 0,
+        rotate: options.from?.rotate ?? 0,
+    };
+    const easing = resolveEasing(easingOpt);
+    const server = typeof window === "undefined";
+    const [status, setStatus] = createSignal(server ? "done" : "idle");
+    const [pending, setPending] = createSignal(0);
+    let queue = "";
+    let units = [];
+    let unitIndex = 0;
+    let cancel = null;
+    let lastFlush = 0;
+    let settling = false;
+    const applyEntrance = (el, e) => {
+        const t = 1 - e;
+        el.style.transform =
+            `translateY(${fmt(from.y * t)}px) scale(${fmt(from.scale + (1 - from.scale) * e)}) rotate(${fmt(from.rotate * t)}deg)`;
+        const blur = from.blur * t;
+        el.style.filter = blur > 0.05 ? `blur(${fmt(blur)}px)` : "none";
+        el.style.opacity = fmt(from.opacity + (1 - from.opacity) * e);
+    };
+    const flush = (t) => {
+        const el = ref();
+        if (!el || queue.length === 0) {
+            queue = "";
+            setPending(0);
+            return;
+        }
+        const batch = queue;
+        queue = "";
+        setPending(0);
+        for (const span of appendUnits(el, batch, unit)) {
+            units.push({ el: span, startAt: t + unitIndex * stagger });
+            unitIndex++;
+        }
+    };
+    const tick = (t) => {
+        if (queue.length > 0 &&
+            (queue.length >= maxBatch || t - lastFlush >= batchMs)) {
+            flush(t);
+            lastFlush = t;
+        }
+        let alive = false;
+        units = units.filter((u) => {
+            const local = clamp01((t - u.startAt) / duration);
+            applyEntrance(u.el, easing(local));
+            if (local < 1)
+                alive = true;
+            return local < 1;
+        });
+        if (queue.length > 0)
+            alive = true;
+        if (!alive) {
+            cancel = null;
+            if (settling) {
+                settling = false;
+                setStatus("done");
+            }
+        }
+        return alive;
+    };
+    const ensureLoop = () => {
+        if (cancel || server)
+            return;
+        lastFlush = now();
+        cancel = schedule(tick);
+    };
+    const push = (chunk) => {
+        if (server || chunk.length === 0)
+            return;
+        if (prefersReducedMotion()) {
+            // Accessibility: skip batching and entrances, show text at once.
+            const el = ref();
+            if (el) {
+                for (const span of appendUnits(el, chunk, unit)) {
+                    void span;
+                }
+            }
+            setPending(0);
+            setStatus("streaming");
+            return;
+        }
+        queue += chunk;
+        setPending(queue.length);
+        setStatus("streaming");
+        ensureLoop();
+    };
+    const complete = () => {
+        if (server) {
+            setStatus("done");
+            return;
+        }
+        if (prefersReducedMotion()) {
+            queue = "";
+            setPending(0);
+            setStatus("done");
+            return;
+        }
+        flush(now());
+        if (units.length === 0 && queue.length === 0) {
+            setStatus("done");
+            return;
+        }
+        settling = true;
+        ensureLoop();
+    };
+    const reset = () => {
+        cancel?.();
+        cancel = null;
+        queue = "";
+        units = [];
+        unitIndex = 0;
+        settling = false;
+        setPending(0);
+        if (!server) {
+            const el = ref();
+            el?.removeAttribute?.("aria-label");
+            if (el)
+                el.textContent = "";
+            setStatus("idle");
+        }
+    };
+    onCleanup(() => {
+        cancel?.();
+        cancel = null;
+    });
+    return { push, complete, reset, status, pending };
+}
+/**
+ * A pure-signal state machine for agent UI.
+ *
+ * Motion is deliberately not built in: pair each state with a recipe
+ * instead, so the machine stays transparent, testable, and SSR-safe.
+ * A typical pairing is `createWobble` on typing dots while "thinking",
+ * `createStreamReveal` while "streaming", `createTransition` for the
+ * "tool-call" overlay, and `createColorShift` on the status pill for
+ * "done"/"error". Each of those degrades on its own under reduced
+ * motion.
+ *
+ * SSR-safe by construction: signals only, no DOM, no clock.
+ *
+ * ```ts
+ * const agent = createAgentState()
+ * agent.set("thinking")
+ * agent.state() // "thinking"
+ * agent.is("streaming") // false
+ * ```
+ */
+export function createAgentState(options = {}) {
+    const { initial = "idle", allowed, onEnter, onExit } = options;
+    const [state, setState] = createSignal(initial);
+    const [prev, setPrev] = createSignal(initial);
+    const legal = (from, to) => {
+        if (!allowed)
+            return true;
+        return allowed.some((t) => t.from === from && t.to === to);
+    };
+    const move = (next) => {
+        const current = state();
+        if (next === current || !legal(current, next))
+            return;
+        onExit?.(current, next);
+        setPrev(current);
+        setState(next);
+        onEnter?.(next, current);
+    };
+    const reset = () => {
+        move(initial);
+    };
+    return {
+        state,
+        prev,
+        set: move,
+        reset,
+        is: (s) => state() === s,
+    };
+}
+/**
+ * Thrown by `parseDriftSpec`. `path` pinpoints the invalid value
+ * (for example "scenes[2].options.duration") so a generator can
+ * repair the spec without guessing.
+ */
+export class DriftSpecError extends Error {
+    constructor(path, message) {
+        super(path
+            ? `Invalid drift spec at "${path}": ${message}`
+            : `Invalid drift spec: ${message}`);
+        this.name = "DriftSpecError";
+        this.path = path;
+    }
+}
+const PRIMITIVES = [
+    "kineticType",
+    "camera",
+    "colorShift",
+    "transition",
+    "beat",
+    "streamReveal",
+];
+/** Primitives that render into an element and need a target key. */
+const DOM_PRIMITIVES = [
+    "kineticType",
+    "streamReveal",
+];
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function assertPositiveNumber(value, path) {
+    if (typeof value !== "number" || !(value > 0)) {
+        throw new DriftSpecError(path, "expected a positive number");
+    }
+}
+function checkOptions(primitive, options, base) {
+    const at = (key) => `${base}.options.${key}`;
+    switch (primitive) {
+        case "kineticType":
+            if (options.duration !== undefined) {
+                assertPositiveNumber(options.duration, at("duration"));
+            }
+            if (options.stagger !== undefined) {
+                assertPositiveNumber(options.stagger, at("stagger"));
+            }
+            break;
+        case "camera":
+            if (options.keyframes !== undefined &&
+                !Array.isArray(options.keyframes)) {
+                throw new DriftSpecError(at("keyframes"), "expected an array");
+            }
+            break;
+        case "colorShift":
+            if (options.stops !== undefined && !Array.isArray(options.stops)) {
+                throw new DriftSpecError(at("stops"), "expected an array");
+            }
+            if (options.duration !== undefined) {
+                assertPositiveNumber(options.duration, at("duration"));
+            }
+            break;
+        case "transition":
+            if (options.type !== undefined &&
+                !["cut", "fade", "slide", "wipe"].includes(options.type)) {
+                throw new DriftSpecError(at("type"), 'expected one of "cut", "fade", "slide", "wipe"');
+            }
+            if (options.duration !== undefined) {
+                assertPositiveNumber(options.duration, at("duration"));
+            }
+            break;
+        case "beat":
+            if (options.bpm !== undefined) {
+                assertPositiveNumber(options.bpm, at("bpm"));
+            }
+            break;
+        case "streamReveal":
+            if (options.text !== undefined && typeof options.text !== "string") {
+                throw new DriftSpecError(at("text"), "expected a string");
+            }
+            break;
+    }
+}
+/**
+ * Validate unknown input against the DriftSpec schema and return the
+ * typed spec. Throws `DriftSpecError` with a precise `path` on the
+ * first invalid value.
+ *
+ * Pure validation, no DOM: safe to run on the server.
+ *
+ * ```ts
+ * const spec = parseDriftSpec(JSON.parse(raw))
+ * const player = createSpecPlayer(spec, { title: () => titleEl })
+ * await player.play()
+ * ```
+ */
+export function parseDriftSpec(input) {
+    if (!isRecord(input)) {
+        throw new DriftSpecError("", "expected an object");
+    }
+    if (input.version !== 1) {
+        throw new DriftSpecError("version", "expected 1");
+    }
+    if (!Array.isArray(input.scenes) || input.scenes.length === 0) {
+        throw new DriftSpecError("scenes", "expected a non-empty array");
+    }
+    const scenes = input.scenes.map((raw, i) => {
+        const base = `scenes[${i}]`;
+        if (!isRecord(raw)) {
+            throw new DriftSpecError(base, "expected an object");
+        }
+        if (typeof raw.primitive !== "string" ||
+            !PRIMITIVES.includes(raw.primitive)) {
+            throw new DriftSpecError(`${base}.primitive`, `expected one of ${PRIMITIVES.join(", ")}`);
+        }
+        const primitive = raw.primitive;
+        let target;
+        if (raw.target !== undefined) {
+            if (typeof raw.target !== "string" || raw.target.length === 0) {
+                throw new DriftSpecError(`${base}.target`, "expected a non-empty string key");
+            }
+            target = raw.target;
+        }
+        else if (DOM_PRIMITIVES.includes(primitive)) {
+            throw new DriftSpecError(`${base}.target`, `"${primitive}" needs a target key into the refs record`);
+        }
+        let specOptions;
+        if (raw.options !== undefined) {
+            if (!isRecord(raw.options)) {
+                throw new DriftSpecError(`${base}.options`, "expected an object");
+            }
+            specOptions = raw.options;
+            checkOptions(primitive, specOptions, base);
+        }
+        let duration;
+        if (raw.duration !== undefined) {
+            assertPositiveNumber(raw.duration, `${base}.duration`);
+            duration = raw.duration;
+        }
+        return { primitive, target, options: specOptions, duration };
+    });
+    return { version: 1, scenes };
+}
+const noopHandle = () => ({
+    promise: Promise.resolve(),
+    stop: () => { },
+});
+/** Resolve when `isDone()` turns true, on the shared clock. */
+function whenDone(isDone) {
+    let cancel = null;
+    let resolveFn;
+    const promise = new Promise((resolve) => {
+        resolveFn = resolve;
+        if (isDone()) {
+            resolve();
+            return;
+        }
+        cancel = schedule(() => {
+            if (isDone()) {
+                resolve();
+                return false;
+            }
+            return true;
+        });
+    });
+    return {
+        promise,
+        stop: () => {
+            cancel?.();
+            cancel = null;
+            resolveFn();
+        },
+    };
+}
+const stepPlayers = {
+    kineticType: (target, options) => {
+        const c = createKineticType(target ?? (() => null), options);
+        return { promise: c.play(), stop: c.stop };
+    },
+    streamReveal: (target, options) => {
+        const c = createStreamReveal(target ?? (() => null), options);
+        const text = typeof options.text === "string" ? options.text : "";
+        c.push(text);
+        c.complete();
+        return whenDone(() => c.status() === "done");
+    },
+    camera: (target, options, budget) => {
+        const el = target?.();
+        const keyframes = options.keyframes ?? [];
+        if (!el || keyframes.length === 0)
+            return noopHandle();
+        const [p, setP] = createSignal(0);
+        const cam = createCamera(keyframes, { progress: p });
+        const ctl = animate(0, 1, {
+            duration: Math.max(budget ?? 1200, 1),
+            easing: "linear",
+            onUpdate: (v) => {
+                setP(v);
+                el.style.transform = cam();
+            },
+        });
+        return { promise: ctl.finished, stop: ctl.stop };
+    },
+    colorShift: (target, options, budget) => {
+        const el = target?.();
+        const stops = options.stops ?? [];
+        if (!el || stops.length === 0)
+            return noopHandle();
+        const c = createColorShift(stops, {
+            ...options,
+            duration: Math.max(budget ?? 1200, 1),
+        });
+        const playPromise = c.play();
+        const apply = schedule(() => {
+            el.style.color = c.color();
+            return c.status() === "running";
+        });
+        const settle = () => {
+            apply();
+            el.style.color = c.color();
+        };
+        return {
+            promise: playPromise.then(settle),
+            stop: () => {
+                c.stop();
+                settle();
+            },
+        };
+    },
+    transition: (_target, options) => {
+        const c = createTransition(options);
+        return { promise: c.play(), stop: c.stop };
+    },
+    beat: (_target, options, budget) => {
+        const c = createBeat(options);
+        c.start();
+        const timer = animate(0, 1, { duration: Math.max(budget ?? 2000, 1) });
+        const stopAll = () => {
+            timer.stop();
+            c.stop();
+        };
+        return { promise: timer.finished.then(() => c.stop()), stop: stopAll };
+    },
+};
+/**
+ * Render a validated DriftSpec: each scene's primitive plays in
+ * order against the element refs the host supplies. `duration` on a
+ * step caps that step's budget.
+ *
+ * SSR-safe: `play()` is a no-op on the server. Under reduced motion
+ * `play()` jumps straight to the last scene (the clean final frame),
+ * matching `createScenePlayer`.
+ *
+ * ```ts
+ * const player = createSpecPlayer(spec, {
+ *   title: () => titleEl,
+ *   body: () => bodyEl,
+ * })
+ * player.scene() // 0, 1, ... as the spec plays
+ * await player.play()
+ * ```
+ */
+export function createSpecPlayer(spec, refs) {
+    const [status, setStatus] = createSignal("idle");
+    const [scene, setScene] = createSignal(-1);
+    let currentStop = null;
+    let resolvePlay = null;
+    let stopped = false;
+    const runStep = async (step) => {
+        const target = step.target === undefined ? undefined : refs[step.target];
+        const handle = stepPlayers[step.primitive](target, step.options ?? {}, step.duration);
+        currentStop = handle.stop;
+        if (step.duration === undefined) {
+            await handle.promise;
+        }
+        else {
+            // The duration is a budget: the step ends when the primitive
+            // finishes or the budget runs out, whichever comes first.
+            const timer = animate(0, 1, { duration: Math.max(step.duration, 0.001) });
+            const stopStep = currentStop;
+            currentStop = () => {
+                stopStep();
+                timer.stop();
+            };
+            await Promise.race([handle.promise, timer.finished]);
+            timer.stop();
+        }
+        currentStop = null;
+    };
+    const play = () => {
+        if (spec.scenes.length === 0) {
+            setScene(-1);
+            setStatus("done");
+            return Promise.resolve();
+        }
+        if (prefersReducedMotion() || typeof window === "undefined") {
+            setScene(spec.scenes.length - 1);
+            setStatus("done");
+            return Promise.resolve();
+        }
+        // A superseded play() must not leave its caller hanging.
+        resolvePlay?.();
+        resolvePlay = null;
+        stopped = false;
+        setStatus("running");
+        return new Promise((resolve) => {
+            resolvePlay = resolve;
+            void (async () => {
+                for (let i = 0; i < spec.scenes.length; i++) {
+                    if (stopped)
+                        break;
+                    setScene(i);
+                    await runStep(spec.scenes[i]);
+                }
+                currentStop = null;
+                const done = resolvePlay;
+                resolvePlay = null;
+                setStatus(stopped ? "idle" : "done");
+                done?.();
+            })();
+        });
+    };
+    const stop = () => {
+        if (status() !== "running")
+            return;
+        stopped = true;
+        currentStop?.();
+        currentStop = null;
+        // The async loop observes `stopped`, breaks, and resolves play().
+    };
+    onCleanup(stop);
+    return { play, stop, status, scene };
+}

package/dist/index.d.ts

@@ -24,5 +24,9 @@ export { createSquashStretch, type SquashStretchOptions, type SquashStretchResul
 export { createGravity, type GravityOptions, type GravityResult, createPendulum, type PendulumOptions, type PendulumResult, createFling, type FlingOptions, type FlingResult, } from "./physics.js";
 export { createFontSwap, type FontSwapOptions, type FontSwapResult, createTyping, type TypingOptions, type TypingResult, createTextPhysics, type TextPhysicsOptions, type TextPhysicsResult, createTextTunnel, type TextTunnelOptions, type TextTunnelResult, createTextCutout, type TextCutoutOptions, createTextGradient, type TextGradientOptions, createTextScramble, type TextScrambleOptions, type TextScrambleResult, createTextWave, type TextWaveOptions, } from "./typography.js";
 export { easings, cubicBezier, linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeOutExpo, easeOutBack, easeInBack, easeInOutBack, easeOutElastic, easeOutBounce, resolveEasing, type Easing, type EasingName, } from "./easing.js";
-export { createKineticType, createScenePlayer, createCamera, createColorShift, createTransition, createBeat, } from "./motion.js";
-export type { KineticTypeFrom, KineticTypeOptions, KineticTypeStatus, KineticTypeControls, MotionScene, ScenePlayerStatus, ScenePlayerControls, CameraKeyframe, CameraOptions, ColorShiftOptions, ColorShiftStatus, ColorShiftControls, TransitionType, TransitionDirection, TransitionOptions, TransitionLayerStyle, TransitionStatus, TransitionControls, BeatOptions, BeatStatus, BeatControls, } from "./motion.js";
+export { createKineticType, createScenePlayer, createShowreel, createCamera, createColorShift, createTransition, createBeat, createBeatCuts, } from "./motion.js";
+export type { KineticTypeFrom, KineticTypeOptions, KineticTypeStatus, KineticTypeControls, MotionScene, ScenePlayerStatus, ScenePlayerControls, ShowreelScene, ShowreelSceneKind, CameraKeyframe, CameraOptions, ColorShiftOptions, ColorShiftStatus, ColorShiftControls, TransitionType, TransitionDirection, TransitionOptions, TransitionLayerStyle, TransitionStatus, TransitionControls, BeatOptions, BeatStatus, BeatControls, BeatCutOptions, } from "./motion.js";
+export { createStreamReveal, createAgentState, parseDriftSpec, createSpecPlayer, DriftSpecError, } from "./ai.js";
+export type { StreamRevealStatus, StreamRevealOptions, StreamRevealControls, AgentState, AgentStateTransition, AgentStateOptions, AgentStateControls, DriftSpecPrimitive, DriftSpecStep, DriftSpec, SpecPlayerStatus, SpecPlayerControls, } from "./ai.js";
+export { createTxLifecycle, createTicker, createMintReveal, createConnectButton, } from "./web3.js";
+export type { TxState, TxStatusInput, TxLifecycleOptions, TxLifecycleControls, TickerOptions, TickerControls, MintRevealStatus, MintRevealOptions, MintRevealControls, ConnectButtonOptions, ConnectButtonStatus, ConnectButtonControls, } from "./web3.js";

package/dist/index.js

@@ -24,4 +24,6 @@ export { createSquashStretch, createFollowThrough, createAnticipation, createWob
 export { createGravity, createPendulum, createFling, } from "./physics.js";
 export { createFontSwap, createTyping, createTextPhysics, createTextTunnel, createTextCutout, createTextGradient, createTextScramble, createTextWave, } from "./typography.js";
 export { easings, cubicBezier, linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeOutExpo, easeOutBack, easeInBack, easeInOutBack, easeOutElastic, easeOutBounce, resolveEasing, } from "./easing.js";
-export { createKineticType, createScenePlayer, createCamera, createColorShift, createTransition, createBeat, } from "./motion.js";
+export { createKineticType, createScenePlayer, createShowreel, createCamera, createColorShift, createTransition, createBeat, createBeatCuts, } from "./motion.js";
+export { createStreamReveal, createAgentState, parseDriftSpec, createSpecPlayer, DriftSpecError, } from "./ai.js";
+export { createTxLifecycle, createTicker, createMintReveal, createConnectButton, } from "./web3.js";

package/dist/motion.d.ts

@@ -25,6 +25,18 @@ export interface KineticTypeFrom {
     opacity?: number;
     /** Rotation in degrees where each unit starts. Default 0. */
     rotate?: number;
+    /**
+     * Per-unit jitter around the `from` values, 0 to 1. Default 0.
+     * At 0 every unit shares the exact `from` state; above 0 each unit
+     * gets a seeded random offset so the entrance feels hand-set
+     * instead of mechanical.
+     */
+    variance?: number;
+    /**
+     * Seed for the per-unit jitter. Same seed renders the same jitter
+     * on every run. Default 0.
+     */
+    seed?: number;
 }
 export interface KineticTypeOptions {
     /** Split into "chars" or "words". Default "chars". */
@@ -55,7 +67,8 @@ export interface KineticTypeControls {
  *
  * One master clock drives every unit, so a headline with 40 characters
  * costs a single rAF task, not 40 timers. Units animate through the
- * same `from` state with per-unit easing.
+ * same `from` state with per-unit easing; set `from.variance` above 0
+ * for seeded per-unit jitter around those values.
  *
  * SSR-safe: no-op on the server. Under reduced motion every unit jumps
  * to its final state when `play()` runs, so the text is fully readable.
@@ -293,6 +306,8 @@ export interface BeatControls {
     bar: Accessor<number>;
     /** Fractional position within the current beat, 0 to 1. */
     phase: Accessor<number>;
+    /** Beats per bar, from the options. Used as the default cut interval. */
+    beatsPerBar: number;
     /**
      * Register a callback fired on every beat with the beat index.
      * Returns an unsubscribe function.
@@ -324,4 +339,66 @@ export interface BeatControls {
  * ```
  */
 export declare function createBeat(options?: BeatOptions): BeatControls;
+/** Named role of a showreel scene, for readability. */
+export type ShowreelSceneKind = "title" | "camera" | "color" | "cut" | "custom";
+/**
+ * One scene in a guided showreel: a `MotionScene` with an optional
+ * named kind describing what the scene does.
+ */
+export interface ShowreelScene extends MotionScene {
+    /**
+     * Named kind for readability: "title" for kinetic-type title cards,
+     * "camera" for camera-move scenes, "color" for color-shift scenes,
+     * "cut" for transition handoffs, "custom" for anything else.
+     * Informational only; it does not change playback.
+     */
+    kind?: ShowreelSceneKind;
+}
+/**
+ * Guided showreel recipe: a thin typed wrapper over
+ * `createScenePlayer` for showreels and launch films. Scenes carry a
+ * named `kind` so the reel reads like a shot list, and each scene's
+ * `onEnter` wires one of the motion-graphics primitives
+ * (`createKineticType`, `createCamera`, `createColorShift`,
+ * `createTransition`, `createBeat`).
+ *
+ * Same controls, status values, and reduced-motion behavior as
+ * `createScenePlayer`: `play()` jumps to the final frame under reduced
+ * motion or on the server.
+ *
+ * ```ts
+ * const reel = createShowreel([
+ *   { kind: "title", duration: 1200, onEnter: () => titleCard.play() },
+ *   { kind: "camera", duration: 2000, onEnter: () => dolly.play() },
+ *   { kind: "color", duration: 1500, onEnter: () => finale.play() },
+ * ])
+ * beatCuts = createBeatCuts(beat, reel, { every: 8 })
+ * await reel.play()
+ * ```
+ */
+export declare function createShowreel(scenes: ShowreelScene[]): ScenePlayerControls;
+export interface BeatCutOptions {
+    /**
+     * Cut every N beats. Default: the beat clock's `beatsPerBar`, so a
+     * cut lands on every downbeat.
+     */
+    every?: number;
+}
+/**
+ * Beat-synced scene cuts: advance the player every N beats through
+ * the beat clock's `onBeat`. Returns a cleanup function that
+ * unsubscribes the cut listener.
+ *
+ * Cuts only fire while the player is running, so pausing the reel
+ * pauses the cuts too.
+ *
+ * ```ts
+ * const beat = createBeat({ bpm: 128, beatsPerBar: 4 })
+ * const stopCuts = createBeatCuts(beat, player) // cut every bar
+ * beat.start()
+ * await player.play()
+ * stopCuts()
+ * ```
+ */
+export declare function createBeatCuts(beat: BeatControls, player: Pick<ScenePlayerControls, "next" | "status">, options?: BeatCutOptions): () => void;
 export {};