solid-drift 0.7.1 → 0.9.0

package/README.md

@@ -345,6 +345,43 @@ const { rotateX, rotateY } = createTilt(() => card, { maxAngle: 12 })
 
 Returns `{ rotateX, rotateY }`: spring-smoothed tilt in degrees. SSR-safe and reduced-motion safe: both return constant `0` accessors.
 
+### `createDrag(ref, options?)`
+
+Pointer drag with spring physics, constraints, and momentum. The gesture workhorse: draggable cards, sliders, bottom-sheet handles, sortable rows. While the pointer is down the element tracks it 1:1; on release it glides with inertia and springs into its constraints, stretching elastically past the edges while dragged. Set `touch-action: none` on the draggable element so touch drags do not fight the page scroll. For the physics-toy flavor (exponential friction plus bouncing off walls), see `createFling` instead.
+
+```tsx
+import { createDrag } from "solid-drift"
+
+let card!: HTMLDivElement
+const { x, y, status } = createDrag(() => card, {
+  constraints: { left: 0, right: 300, top: 0, bottom: 0 },
+  elastic: 0.4,
+})
+<div
+  ref={card}
+  style={{
+    transform: `translate(${x()}px, ${y()}px)`,
+    "touch-action": "none",
+    cursor: status() === "dragging" ? "grabbing" : "grab",
+  }}
+>
+  Drag me
+</div>
+```
+
+| Option        | Default                          | Description                                                        |
+| ------------- | -------------------------------- | ------------------------------------------------------------------ |
+| `axis`        | `"both"`                         | `"x"`, `"y"`, or `"both"`                                          |
+| `constraints` | none                             | Bounds in px relative to the drag origin; release settles inside    |
+| `elastic`     | `0.35`                           | Overshoot past constraints while dragging, 0 (hard stop) to 1      |
+| `momentum`    | `true`                           | Glide with inertia after release                                   |
+| `inertia`     | `0.2`                            | Seconds of release velocity projected into the settle target       |
+| `spring`      | `{ stiffness: 300, damping: 32 }` | Spring physics for the settle after release                       |
+| `onDragStart` | none                             | Called when the pointer grabs the element                           |
+| `onDragEnd`   | none                             | Called on release with `{ x, y, velocityX, velocityY }` (px/s)      |
+
+Returns `{ x, y, status }`: the drag offset in pixels and `status` (`"idle"`, `"dragging"`, `"settling"`). SSR-safe: everything rests at 0. Under reduced motion the drag still tracks the pointer (direct manipulation is not animation) but release snaps instantly to the constrained target with no glide.
+
 ### `createTrail(source, options?)`
 
 A signal that replays another signal's past: it returns the value the source had `delay` milliseconds ago, interpolated between samples. Chain trails off one source for follower effects (a cursor with a comet tail, cascading highlights), or trail a scroll progress for a delayed echo of the page. The trail catches up and parks exactly on the latest value when the source rests. The follow loop runs only while the trail is behind.
@@ -723,6 +760,8 @@ onMount(() => kinetic.play());
 
 Returns `{ play, stop, replay, status }`. `play()` resolves when the last unit arrives. Under reduced motion every unit jumps to its final state, so the text is fully readable.
 
+`from` also accepts `variance` (0 to 1, default 0) and `seed`. Each unit jitters `y`, `blur`, `scale`, and `rotate` around the `from` values by up to `variance`, so a headline feels hand-set instead of mechanical. The jitter uses a seeded PRNG, so the same `seed` renders the exact same layout on every run (stable across SSR and replays). `variance: 0` keeps the classic uniform behavior.
+
 ### `createScenePlayer(scenes)`
 
 Scene orchestrator for showreels and launch films: an ordered list of scenes, each with a `duration` and `onEnter`/`onExit` hooks. `scene()` tells your view which scene is live; the hooks trigger each scene's choreography (a `createKineticType`, a camera move, a color shift).
@@ -803,7 +842,203 @@ const off = beat.onBeat((b) => {
 beat.start();
 ```
 
-Returns `{ beat, bar, phase, onBeat, start, stop, status }`. `onBeat` returns an unsubscribe function. Beats are timing, not motion, so the clock keeps ticking under reduced motion (your callbacks decide what that means visually).
+Returns `{ beat, bar, beatsPerBar, phase, onBeat, start, stop, status }`. `onBeat` returns an unsubscribe function. Beats are timing, not motion, so the clock keeps ticking under reduced motion (your callbacks decide what that means visually).
+
+### `createShowreel(scenes)`
+
+A guided showreel recipe on top of `createScenePlayer`: scenes carry a `kind` label (`"title"`, `"camera"`, `"color"`, `"cut"`, `"custom"`) so the reel reads like a shot list. It returns the full scene player controls, so `play`, `pause`, `next`, `prev`, and `goTo` all work unchanged.
+
+```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() },
+  { kind: "cut", duration: 400, onEnter: () => wipe.play() },
+]);
+await reel.play(); // resolves after the last scene
+```
+
+Showreel recipe: combine `createKineticType` (title cards), `createCamera` (dolly moves), `createColorShift` (finale grade), `createTransition` (match cuts), `createBeat` (rhythm), and `createShowreel` (the shot list). Under reduced motion `play()` jumps straight to the last scene.
+
+### `createBeatCuts(beat, player, options?)`
+
+Beat-synced scene cuts: advances the player every N beats through the beat clock's `onBeat`. The default interval is the beat clock's `beatsPerBar`, so a cut lands on every downbeat. Returns a cleanup function that unsubscribes the cut listener.
+
+```ts
+const beat = createBeat({ bpm: 128, beatsPerBar: 4 });
+const stopCuts = createBeatCuts(beat, player); // cut every bar
+// const stopCuts = createBeatCuts(beat, player, { every: 8 }); // every 2 bars
+beat.start();
+await player.play();
+stopCuts();
+```
+
+Cuts only fire while the player is running, so pausing the reel pauses the cuts too. Beat timing is not motion, so cuts keep firing under reduced motion (pair with a reduced-motion-safe `onEnter` if the cut itself animates).
+
+### `createStreamReveal(ref, options?)`
+
+Streaming text for chat and agent UIs: push characters as they arrive and each batch reveals with the kinetic treatment (rise, deblur, settle). Batches flush on a short cadence, or early when the queue grows past `maxBatch`, so fast streams never fall behind.
+
+```tsx
+let out!: HTMLDivElement;
+const stream = createStreamReveal(() => out, { batchMs: 120, maxBatch: 24 });
+const res = await fetch("/chat", { method: "POST", body: q });
+const reader = res.body!.getReader();
+const decoder = new TextDecoder();
+for (;;) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  stream.push(decoder.decode(value, { stream: true }));
+}
+await stream.complete(); // flush the tail, then done
+<div ref={out} aria-live="polite" />
+```
+
+Returns `{ push, complete, reset, status, pending }`. `status()` is `"idle"`, `"streaming"`, or `"done"`; `pending()` counts queued characters. Under reduced motion pushed text appears immediately with no per-unit animation; on the server `push` is a no-op and `status()` is `"done"`.
+
+### `createAgentState(options?)`
+
+A tiny state machine for agent UIs: `idle`, `thinking`, `streaming`, `tool`, `done`, `error`, with legal-transition gating and enter/exit hooks. Pure signals, no DOM, so it works on the server and in tests.
+
+```ts
+const agent = createAgentState({
+  allowed: [
+    { from: "idle", to: "thinking" },
+    { from: "thinking", to: "streaming" },
+    { from: "streaming", to: "tool-call" },
+    { from: "tool-call", to: "streaming" },
+    { from: "streaming", to: "done" },
+  ],
+  onEnter: (s) => console.log("agent:", s),
+});
+agent.set("thinking");
+agent.state(); // "thinking"
+agent.prev(); // "idle"
+```
+
+Agent UI recipe: `thinking` pairs with `createWobble` on typing dots, `streaming` drives `createStreamReveal`, `tool-call` overlays a `createTransition`, and `done`/`error` tint a status pill with `createColorShift`. Returns `{ state, prev, set, reset, is }`. Illegal moves are ignored. State is logic, not motion, so it behaves identically under reduced motion.
+
+### `parseDriftSpec(input)`
+
+Validates a DriftSpec, the JSON motion spec a coding agent can generate: `{ version: 1, scenes: [{ primitive, target?, options?, duration? }] }`. Supported primitives: `kineticType`, `streamReveal`, `camera`, `colorShift`, `transition`, `beat`. Throws a `DriftSpecError` naming the exact path (`scenes[0].options.duration`) on the first problem.
+
+```ts
+import { parseDriftSpec } from "solid-drift";
+
+const spec = parseDriftSpec({
+  version: 1,
+  scenes: [
+    {
+      primitive: "kineticType",
+      target: "title",
+      options: { duration: 600, stagger: 40, from: { y: 40, variance: 0.5, seed: 7 } },
+    },
+    {
+      primitive: "colorShift",
+      options: {
+        stops: [
+          { at: 0, color: "#0a1220" },
+          { at: 1, color: "#d9a441" },
+        ],
+        duration: 1200,
+      },
+      duration: 1200, // step budget: move on even if the shift is still running
+    },
+  ],
+});
+```
+
+Prompt hint for generating specs: "Return ONLY a JSON DriftSpec: `{ version: 1, scenes: [...] }`. Each scene is `{ primitive, target?, options?, duration? }`. `primitive` is one of kineticType, streamReveal, camera, colorShift, transition, beat. `target` is a key into the refs map I provide. `options` match that primitive's options exactly. Keep scenes short; put a `duration` budget on any scene that should not block." Validation is pure and runs anywhere, including the server.
+
+### `createSpecPlayer(spec, refs)`
+
+Plays a validated DriftSpec: each scene runs its primitive against the matching ref from the `refs` map (`{ title: () => el }`), then the player advances. A scene `duration` acts as a budget, so a long ambient loop never stalls the reel.
+
+```ts
+const player = createSpecPlayer(spec, { title: () => titleEl });
+await player.play(); // scenes in order, ends "done"
+player.stop(); // halt mid-reel; the play() promise resolves
+```
+
+Returns `{ scene, status, play, stop }`. `scene()` is the live scene index (-1 before the first play). Under reduced motion `play()` applies every scene's final state instantly and ends `"done"`.
+
+### `createTxLifecycle(options?)`
+
+Transaction lifecycle for onchain UI, with zero wallet dependencies: feed it wagmi/viem-style state through an accessor (the adapter pattern) and it maps that to `idle`, `signing`, `pending`, `confirming`, `success`, `failed`. `progress()` springs between 0, 0.25, 0.5, 0.75, 1 so progress rings glide instead of jumping.
+
+```ts
+// Adapter: your wagmi/viem state in, tx state out.
+const [chain] = createSignal({ status: "idle" as const, confirmations: 0 });
+const tx = createTxLifecycle({
+  source: () => ({
+    status: chain().status, // "idle" | "pending" | "success" | "error"
+    confirmations: chain().confirmations,
+  }),
+  requiredConfirmations: 2,
+  onEnter: (s) => console.log("tx:", s),
+});
+tx.set("signing"); // manual: the moment the wallet prompt opens
+```
+
+Standard mapping: `set("signing")` when the wallet prompt opens, source `pending` (hash received) maps to `"pending"`, confirmations reaching the threshold promote to `"confirming"`, source `success`/`error` map to `"success"`/`"failed"`. Omit `source` for a fully manual lifecycle. Returns `{ state, set, reset, progress }`. On the server it stays `"idle"` with `progress()` 0; under reduced motion state changes apply instantly and `progress()` jumps to its target.
+
+### `createTicker(source, ref, options?)`
+
+A price ticker with rolling digits: each digit rolls vertically on change, the whole figure flashes green/red on up/down moves, and rapid source updates batch into one render per frame. `display()` always holds the formatted string, so SSR and tests read the price without DOM.
+
+```tsx
+const [price] = createSignal(64218.5);
+const ticker = createTicker(price, () => priceEl, {
+  decimals: 2,
+  locale: "en-US",
+  upColor: "#16a34a",
+  downColor: "#dc2626",
+  flashMs: 600,
+});
+<div>
+  <span ref={priceEl} aria-label={`Price ${ticker.display()}`} />
+</div>
+```
+
+Returns `{ display, direction }`. `direction()` is `"up"`, `"down"`, or `"flat"`. Formatting uses `Intl.NumberFormat` with the given locale. Under reduced motion the text swaps instantly with no rolling digits and no color flash; on the server only `display()` and `direction()` work.
+
+### `createMintReveal(ref, options?)`
+
+An NFT mint reveal: an anticipation shake winds up, the card flips on rotateY, `onFlip` fires at the midpoint (edge-on, so the face swap is invisible), and squash-and-stretch sells the landing. `reset()` returns the card to idle.
+
+```tsx
+let card!: HTMLDivElement;
+const reveal = createMintReveal(() => card, {
+  shakeDuration: 500,
+  flipDuration: 700,
+  squash: true,
+  onFlip: () => setFace("revealed"), // swap the artwork mid-flip
+});
+<button onClick={() => reveal.play()}>Reveal</button>
+<div ref={card} style={{ "transform-style": "preserve-3d" }} />
+```
+
+Returns `{ play, reset, status }`. `status()` walks `"idle"`, `"anticipating"`, `"flipping"`, `"revealed"`. Under reduced motion (and on the server) `play()` applies the revealed state immediately and still calls `onFlip`.
+
+### `createConnectButton(ref, options?)`
+
+Wallet connect button micro-interactions: magnetic pull toward the pointer, a press scale, an animated check overlay for copy-address feedback, and a chain pulse ring. Pointer handling is global (presses that start inside still count if released outside), and everything cleans up on unmount.
+
+```tsx
+let btn!: HTMLButtonElement;
+const connect = createConnectButton(() => btn, { strength: 0.35 });
+<button
+  ref={btn}
+  onClick={() => {
+    navigator.clipboard.writeText(address);
+    connect.copyTick(); // check overlay pops, then fades
+  }}
+>
+  {address}
+</button>
+```
+
+Returns `{ copyTick, chainPulse, status }`. `status()` is `"idle"`, `"ticking"` (check visible), or `"pulsing"` (ring expanding). Call `chainPulse()` after a successful connection or network switch. Under reduced motion there is no magnetic pull or scale; `copyTick()` and `chainPulse()` still show their overlays statically.
 
 ### Easings
 

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 {};