solid-drift 0.2.0 → 0.8.0

package/dist/ai.d.ts

@@ -0,0 +1,207 @@
+/**
+ * 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 { type Accessor } from "solid-js";
+import { type Easing, type EasingName } from "./easing.js";
+import { type KineticTypeFrom } from "./motion.js";
+type MaybeElement = () => Element | null | undefined;
+export type StreamRevealStatus = "idle" | "streaming" | "done";
+export interface StreamRevealOptions {
+    /** Split into "chars" or "words". Default "chars". */
+    unit?: "chars" | "words";
+    /** Flush the batch queue on this cadence, in ms. Default 120. */
+    batchMs?: number;
+    /** Flush early when the queue grows past this many chars. Default 24. */
+    maxBatch?: number;
+    /** Entrance duration per unit, in ms. Default 450. */
+    duration?: number;
+    /** Milliseconds between unit starts. Default 30. */
+    stagger?: number;
+    /** Starting transform/opacity/blur for each unit. */
+    from?: KineticTypeFrom;
+    /** Easing for each unit's entrance. Default "easeOutExpo". */
+    easing?: Easing | EasingName;
+}
+export interface StreamRevealControls {
+    /** Append raw stream tokens; they are batched internally. */
+    push: (chunk: string) => void;
+    /** Flush remaining units and settle. */
+    complete: () => void;
+    /** Clear the text and return to idle. */
+    reset: () => void;
+    /** Reactive status: "idle" | "streaming" | "done". */
+    status: Accessor<StreamRevealStatus>;
+    /** Chars waiting in the batch queue. */
+    pending: Accessor<number>;
+}
+/**
+ * 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 declare function createStreamReveal(ref: MaybeElement, options?: StreamRevealOptions): StreamRevealControls;
+/** Lifecycle states of a conversational agent turn. */
+export type AgentState = "idle" | "thinking" | "streaming" | "tool-call" | "done" | "error";
+/** One legal state change. */
+export interface AgentStateTransition {
+    from: AgentState;
+    to: AgentState;
+}
+export interface AgentStateOptions {
+    /** Starting state. Default "idle". */
+    initial?: AgentState;
+    /** Legal transitions. Omit to allow every transition. */
+    allowed?: AgentStateTransition[];
+    /** Called after entering a state, with the previous state. */
+    onEnter?: (state: AgentState, prev: AgentState) => void;
+    /** Called before leaving a state, with the next state. */
+    onExit?: (state: AgentState, next: AgentState) => void;
+}
+export interface AgentStateControls {
+    /** Current state. */
+    state: Accessor<AgentState>;
+    /** Previous state. */
+    prev: Accessor<AgentState>;
+    /** Move to the next state. Illegal transitions are ignored. */
+    set: (next: AgentState) => void;
+    /** Return to the initial state. */
+    reset: () => void;
+    /** Convenience for class bindings: `agent.is("thinking")`. */
+    is: (s: AgentState) => boolean;
+}
+/**
+ * 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 declare function createAgentState(options?: AgentStateOptions): AgentStateControls;
+/** Primitives a drift spec can choreograph. */
+export type DriftSpecPrimitive = "kineticType" | "camera" | "colorShift" | "transition" | "beat" | "streamReveal";
+/** One choreographed step. */
+export interface DriftSpecStep {
+    /** Which primitive renders this step. */
+    primitive: DriftSpecPrimitive;
+    /**
+     * Key into the refs record given to `createSpecPlayer`. Required
+     * for primitives that render into an element ("kineticType" and
+     * "streamReveal").
+     */
+    target?: string;
+    /**
+     * Primitive options. Validated against each primitive's minimal
+     * shape. "camera" reads `keyframes`, "colorShift" reads `stops`,
+     * "streamReveal" reads `text` here.
+     */
+    options?: Record<string, unknown>;
+    /** Step budget in milliseconds, for timed players. */
+    duration?: number;
+}
+/** A deterministic motion choreography, usually generated as JSON. */
+export interface DriftSpec {
+    version: 1;
+    scenes: DriftSpecStep[];
+}
+/**
+ * Thrown by `parseDriftSpec`. `path` pinpoints the invalid value
+ * (for example "scenes[2].options.duration") so a generator can
+ * repair the spec without guessing.
+ */
+export declare class DriftSpecError extends Error {
+    /** Dot/bracket path to the invalid value, "" for the root. */
+    path: string;
+    constructor(path: string, message: string);
+}
+/**
+ * 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 declare function parseDriftSpec(input: unknown): DriftSpec;
+export type SpecPlayerStatus = "idle" | "running" | "done";
+export interface SpecPlayerControls {
+    /** Play every scene in order. Resolves after the last scene. */
+    play: () => Promise<void>;
+    /** Stop mid-spec. The play() promise resolves. */
+    stop: () => void;
+    /** Reactive status: "idle" | "running" | "done". */
+    status: Accessor<SpecPlayerStatus>;
+    /** Current scene index, or -1 before the first play(). */
+    scene: Accessor<number>;
+}
+/**
+ * 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 declare function createSpecPlayer(spec: DriftSpec, refs: Record<string, MaybeElement>): SpecPlayerControls;
+export {};