solid-drift 0.2.0 → 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/animate.d.ts

@@ -25,8 +25,8 @@ export interface AnimationControls {
  *   duration: 500,
  *   easing: "easeOutExpo",
  *   onUpdate: (v) => el.style.opacity = String(v / 100),
- * });
- * await ctl.finished;
+ * })
+ * await ctl.finished
  * ```
  */
 export declare function animate(from: number, to: number, options?: AnimateOptions): AnimationControls;

package/dist/animate.js

@@ -9,8 +9,8 @@ import { prefersReducedMotion } from "./reduced-motion.js";
  *   duration: 500,
  *   easing: "easeOutExpo",
  *   onUpdate: (v) => el.style.opacity = String(v / 100),
- * });
- * await ctl.finished;
+ * })
+ * await ctl.finished
  * ```
  */
 export function animate(from, to, options = {}) {