solid-drift 0.7.1 → 0.9.0

package/dist/gesture.js

@@ -0,0 +1,207 @@
+import { createEffect, createSignal, onCleanup, untrack, } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+const zero = () => 0;
+const idle = () => "idle";
+/**
+ * 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.
+ *
+ * This is the framer-motion `drag` vocabulary rebuilt signal-native:
+ * `axis` locks direction, `constraints` bounds the travel, `elastic`
+ * controls the overshoot, and `momentum` toggles the release glide.
+ * For the physics-toy flavor (friction plus bouncing off walls), see
+ * `createFling` instead.
+ *
+ * Set `touch-action: none` on the draggable element so touch drags do
+ * not fight the page scroll.
+ *
+ * SSR-safe and reduced-motion aware: on the server 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.
+ *
+ * ```tsx
+ * 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>
+ * ```
+ */
+export function createDrag(ref, options = {}) {
+    if (typeof window === "undefined") {
+        return { x: zero, y: zero, status: idle };
+    }
+    const { axis = "both", constraints, elastic = 0.35, momentum = true, inertia = 0.2, spring = {}, onDragStart, onDragEnd, } = options;
+    const [x, setX] = createSignal(0);
+    const [y, setY] = createSignal(0);
+    const [status, setStatus] = createSignal("idle");
+    let cancelSettle = null;
+    const clampAxis = (value, min, max) => {
+        if (min !== undefined && value < min)
+            return min;
+        if (max !== undefined && value > max)
+            return max;
+        return value;
+    };
+    /** Elastic resistance past the constraints while dragging. */
+    const applyConstraints = (px, py) => {
+        if (!constraints)
+            return [px, py];
+        const { left, top, right, bottom } = constraints;
+        let ox = px;
+        let oy = py;
+        if (left !== undefined && ox < left)
+            ox = left + (ox - left) * elastic;
+        if (right !== undefined && ox > right)
+            ox = right + (ox - right) * elastic;
+        if (top !== undefined && oy < top)
+            oy = top + (oy - top) * elastic;
+        if (bottom !== undefined && oy > bottom)
+            oy = bottom + (oy - bottom) * elastic;
+        return [ox, oy];
+    };
+    const hardClamp = (px, py) => {
+        if (!constraints)
+            return [px, py];
+        const { left, top, right, bottom } = constraints;
+        return [clampAxis(px, left, right), clampAxis(py, top, bottom)];
+    };
+    const stopSettle = () => {
+        cancelSettle?.();
+        cancelSettle = null;
+    };
+    /** Spring glide toward the target, seeded with the release velocity. */
+    const settleTo = (tx, ty, vx0, vy0) => {
+        const { stiffness = 300, damping = 32 } = spring;
+        let cx = untrack(x);
+        let cy = untrack(y);
+        let vx = vx0;
+        let vy = vy0;
+        let last = now();
+        setStatus("settling");
+        stopSettle();
+        const task = (t) => {
+            const dt = Math.min(Math.max((t - last) / 1000, 0), 0.064);
+            last = t;
+            // Semi-implicit Euler toward the target, same integrator as createSpring.
+            vx += (-stiffness * (cx - tx) - damping * vx) * dt;
+            vy += (-stiffness * (cy - ty) - damping * vy) * dt;
+            cx += vx * dt;
+            cy += vy * dt;
+            setX(cx);
+            setY(cy);
+            const settled = Math.hypot(cx - tx, cy - ty) < 0.5 && Math.hypot(vx, vy) < 20;
+            if (settled) {
+                setX(tx);
+                setY(ty);
+                setStatus("idle");
+                cancelSettle = null;
+                return false;
+            }
+            return true;
+        };
+        cancelSettle = schedule(task);
+    };
+    const onDown = (event) => {
+        if (event.isPrimary === false)
+            return;
+        const el = ref();
+        if (!el)
+            return;
+        stopSettle();
+        const startPX = event.clientX;
+        const startPY = event.clientY;
+        const startX = untrack(x);
+        const startY = untrack(y);
+        const samples = [
+            [now(), startX, startY],
+        ];
+        setStatus("dragging");
+        onDragStart?.();
+        const move = (ev) => {
+            if (ev.isPrimary === false)
+                return;
+            let nx = startX + (ev.clientX - startPX);
+            let ny = startY + (ev.clientY - startPY);
+            if (axis === "x")
+                ny = startY;
+            if (axis === "y")
+                nx = startX;
+            [nx, ny] = applyConstraints(nx, ny);
+            setX(nx);
+            setY(ny);
+            samples.push([now(), nx, ny]);
+            if (samples.length > 8)
+                samples.shift();
+        };
+        const up = () => {
+            window.removeEventListener("pointermove", move);
+            window.removeEventListener("pointerup", up);
+            window.removeEventListener("pointercancel", up);
+            // Release velocity from the last ~120ms of the drag.
+            const t = now();
+            let oi = 0;
+            while (oi < samples.length - 1 && t - samples[oi][0] > 120)
+                oi++;
+            const [ot, ox, oy] = samples[oi];
+            const [lt, lx, ly] = samples[samples.length - 1];
+            const dt = Math.max(lt - ot, 1) / 1000;
+            const velocityX = ((lx - ox) / dt) * (axis === "y" ? 0 : 1);
+            const velocityY = ((ly - oy) / dt) * (axis === "x" ? 0 : 1);
+            const releaseX = untrack(x);
+            const releaseY = untrack(y);
+            onDragEnd?.({ x: releaseX, y: releaseY, velocityX, velocityY });
+            if (prefersReducedMotion()) {
+                // Direct manipulation still works, but the release snaps
+                // instantly to the constrained target: no glide, no spring.
+                const [cx, cy] = hardClamp(releaseX, releaseY);
+                setX(cx);
+                setY(cy);
+                setStatus("idle");
+                return;
+            }
+            // Project the release velocity forward, then spring to the
+            // clamped target. Overshoot past the constraints snaps back
+            // elastically because the target sits on the edge.
+            let tx = releaseX;
+            let ty = releaseY;
+            if (momentum) {
+                tx += velocityX * inertia;
+                ty += velocityY * inertia;
+            }
+            [tx, ty] = hardClamp(tx, ty);
+            const vx0 = momentum ? velocityX : 0;
+            const vy0 = momentum ? velocityY : 0;
+            settleTo(tx, ty, vx0, vy0);
+        };
+        window.addEventListener("pointermove", move, { passive: true });
+        window.addEventListener("pointerup", up);
+        window.addEventListener("pointercancel", up);
+    };
+    // Late-bound refs (Solid assigns `ref` after mount) still get the grab.
+    createEffect(() => {
+        const el = ref();
+        if (!el)
+            return;
+        el.addEventListener("pointerdown", onDown);
+        onCleanup(() => el.removeEventListener("pointerdown", onDown));
+    });
+    onCleanup(() => stopSettle());
+    return { x, y, status };
+}

package/dist/index.d.ts

@@ -24,5 +24,10 @@ 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 { createDrag, type DragStatus, type DragAxis, type DragConstraints, type DragEndInfo, type DragOptions, type DragControls, } from "./gesture.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,7 @@ 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 { createDrag, } from "./gesture.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 {};

package/dist/motion.js

@@ -16,53 +16,7 @@ import { parseColorStops, sampleColorStops, } from "./color.js";
 import { resolveEasing } from "./easing.js";
 import { now, schedule } from "./engine.js";
 import { prefersReducedMotion } from "./reduced-motion.js";
-function ownerDoc(el) {
-    const od = el
-        .ownerDocument;
-    if (od)
-        return od ?? undefined;
-    return typeof document !== "undefined" ? document : undefined;
-}
-/**
- * Split an element's text into per-unit inline-block spans so each
- * letter (or word) can be transformed independently. The original text
- * is preserved as an aria-label for screen readers.
- */
-function splitUnits(el, unit) {
-    const doc = ownerDoc(el);
-    if (!doc)
-        return [];
-    const text = el.textContent ?? "";
-    el.textContent = "";
-    el.setAttribute("aria-label", text);
-    const spans = [];
-    const push = (content) => {
-        const s = doc.createElement("span");
-        s.textContent = content;
-        s.setAttribute("aria-hidden", "true");
-        s.style.display = "inline-block";
-        s.style.willChange = "transform, opacity, filter";
-        el.appendChild(s);
-        spans.push(s);
-    };
-    if (unit === "words") {
-        for (const word of text.split(/(\s+)/)) {
-            if (word.length === 0)
-                continue;
-            if (/^\s+$/.test(word)) {
-                el.appendChild(doc.createTextNode(word));
-            }
-            else {
-                push(word);
-            }
-        }
-    }
-    else {
-        for (const ch of text)
-            push(ch === " " ? " " : ch);
-    }
-    return spans;
-}
+import { mulberry32, splitUnits } from "./text.js";
 function clamp01(v) {
     return v < 0 ? 0 : v > 1 ? 1 : v;
 }
@@ -88,7 +42,8 @@ function applyKineticStyle(el, e, from) {
  *
  * 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.
@@ -113,10 +68,13 @@ export function createKineticType(ref, options = {}) {
         scale: options.from?.scale ?? 0.85,
         opacity: options.from?.opacity ?? 0,
         rotate: options.from?.rotate ?? 0,
+        variance: options.from?.variance ?? 0,
+        seed: options.from?.seed ?? 0,
     };
     const easing = resolveEasing(easingOpt);
     const [status, setStatus] = createSignal("idle");
     let units = [];
+    let unitFrom = [];
     let controls = null;
     let runToken = 0;
     const play = () => {
@@ -124,6 +82,7 @@ export function createKineticType(ref, options = {}) {
         controls?.stop();
         controls = null;
         units = [];
+        unitFrom = [];
         if (typeof window !== "undefined") {
             const el = ref();
             if (el)
@@ -133,6 +92,29 @@ export function createKineticType(ref, options = {}) {
             setStatus("done");
             return Promise.resolve();
         }
+        // Seeded per-unit jitter around the `from` values. Deterministic
+        // for a given seed, so the same headline renders the same way on
+        // every run. Variance 0 keeps the exact legacy behavior.
+        const variance = clamp01(from.variance);
+        if (variance > 0) {
+            const rand = mulberry32(from.seed);
+            unitFrom = units.map(() => ({
+                y: from.y + variance * (rand() * 2 - 1) * 20,
+                blur: Math.max(0, from.blur + variance * (rand() * 2 - 1) * 8),
+                scale: from.scale + variance * (rand() * 2 - 1) * 0.15,
+                opacity: from.opacity,
+                rotate: from.rotate + variance * (rand() * 2 - 1) * 12,
+            }));
+        }
+        else {
+            unitFrom = units.map(() => ({
+                y: from.y,
+                blur: from.blur,
+                scale: from.scale,
+                opacity: from.opacity,
+                rotate: from.rotate,
+            }));
+        }
         setStatus("running");
         const total = duration + stagger * (units.length - 1);
         return new Promise((resolve) => {
@@ -146,7 +128,7 @@ export function createKineticType(ref, options = {}) {
                 onUpdate: (elapsed) => {
                     for (let i = 0; i < units.length; i++) {
                         const local = clamp01((elapsed - i * stagger) / duration);
-                        applyKineticStyle(units[i], easing(local), from);
+                        applyKineticStyle(units[i], easing(local), unitFrom[i]);
                     }
                 },
                 onComplete: () => {
@@ -716,6 +698,7 @@ export function createBeat(options = {}) {
         beat,
         bar,
         phase,
+        beatsPerBar: perBar,
         onBeat: (cb) => {
             listeners.add(cb);
             return () => {
@@ -727,3 +710,52 @@ export function createBeat(options = {}) {
         status,
     };
 }
+/**
+ * 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 function createShowreel(scenes) {
+    return createScenePlayer(scenes);
+}
+/**
+ * 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 function createBeatCuts(beat, player, options = {}) {
+    const every = Math.max(1, Math.floor(options.every ?? beat.beatsPerBar));
+    return beat.onBeat((b) => {
+        if (b % every === 0 && player.status() === "running") {
+            player.next();
+        }
+    });
+}

package/dist/text.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Internal text utilities shared by the motion-graphics primitives.
+ *
+ * Not part of the public API: family modules import from here, but
+ * nothing in this file is re-exported from the package index.
+ */
+/** Document owning the element, with an SSR-safe fallback. */
+export declare function ownerDoc(el: Element): Document | undefined;
+/**
+ * Split an element's text into per-unit inline-block spans so each
+ * letter (or word) can be transformed independently. The original text
+ * is preserved as an aria-label for screen readers. Any previous
+ * content is replaced.
+ */
+export declare function splitUnits(el: Element, unit: "chars" | "words"): HTMLElement[];
+/**
+ * Append per-unit inline-block spans for `text` to the element's
+ * existing content, without clearing it. Used by streaming text, where
+ * each flushed batch adds new units while earlier units keep playing.
+ */
+export declare function appendUnits(el: Element, text: string, unit: "chars" | "words"): HTMLElement[];
+/**
+ * Deterministic pseudo-random generator (mulberry32). Used for
+ * per-unit variance so seeded jitter renders identically on every
+ * run, which keeps tests stable and output reproducible.
+ */
+export declare function mulberry32(seed: number): () => number;

package/dist/text.js

@@ -0,0 +1,84 @@
+/**
+ * Internal text utilities shared by the motion-graphics primitives.
+ *
+ * Not part of the public API: family modules import from here, but
+ * nothing in this file is re-exported from the package index.
+ */
+/** Document owning the element, with an SSR-safe fallback. */
+export function ownerDoc(el) {
+    const od = el
+        .ownerDocument;
+    if (od)
+        return od ?? undefined;
+    return typeof document !== "undefined" ? document : undefined;
+}
+function pushUnit(doc, parent, content) {
+    const s = doc.createElement("span");
+    s.textContent = content;
+    s.setAttribute("aria-hidden", "true");
+    s.style.display = "inline-block";
+    s.style.willChange = "transform, opacity, filter";
+    parent.appendChild(s);
+    return s;
+}
+function appendTokens(doc, parent, text, unit) {
+    const spans = [];
+    if (unit === "words") {
+        for (const word of text.split(/(\s+)/)) {
+            if (word.length === 0)
+                continue;
+            if (/^\s+$/.test(word)) {
+                parent.appendChild(doc.createTextNode(word));
+            }
+            else {
+                spans.push(pushUnit(doc, parent, word));
+            }
+        }
+    }
+    else {
+        for (const ch of text)
+            spans.push(pushUnit(doc, parent, ch === " " ? " " : ch));
+    }
+    return spans;
+}
+/**
+ * Split an element's text into per-unit inline-block spans so each
+ * letter (or word) can be transformed independently. The original text
+ * is preserved as an aria-label for screen readers. Any previous
+ * content is replaced.
+ */
+export function splitUnits(el, unit) {
+    const doc = ownerDoc(el);
+    if (!doc)
+        return [];
+    const text = el.textContent ?? "";
+    el.textContent = "";
+    el.setAttribute("aria-label", text);
+    return appendTokens(doc, el, text, unit);
+}
+/**
+ * Append per-unit inline-block spans for `text` to the element's
+ * existing content, without clearing it. Used by streaming text, where
+ * each flushed batch adds new units while earlier units keep playing.
+ */
+export function appendUnits(el, text, unit) {
+    const doc = ownerDoc(el);
+    if (!doc)
+        return [];
+    return appendTokens(doc, el, text, unit);
+}
+/**
+ * Deterministic pseudo-random generator (mulberry32). Used for
+ * per-unit variance so seeded jitter renders identically on every
+ * run, which keeps tests stable and output reproducible.
+ */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}