3d-spinner 0.9.1 → 0.9.3

package/dist/animations/grid-assembly.js

@@ -0,0 +1,268 @@
+import { animationLabelOpacity, mountAnimationLabel, } from "../animation-label.js";
+import { Little3dEngine, cube, tetrahedron, octahedron, pyramid, icosphere, } from "../engines/little-3d-engine/little-3d-engine.js";
+import { easeInCubic, easeInOutCubic, easeOutCubic, } from "../engines/little-tween-engine/core/tweens.js";
+const GRID = 5;
+const COUNT = GRID * GRID;
+const CAMERA_Z = 4;
+const FOV = (55 * Math.PI) / 180;
+const TWO_PI = Math.PI * 2;
+const INTRO_MS = 900;
+const INTRO_STAGGER_MS = 60;
+const GATE_DOCK = 0.35;
+const GATE_UNDOCK = 0.65;
+const EXIT_HURRY = 2.5;
+const SPIN_EVERY_MS = 2000;
+const SPIN_MS = 380;
+const SPIN_STAGGER_MS = 80;
+const HOLD_MS = 1000;
+const COLLAPSE_MS = 700;
+const POP_MS = 170;
+const LABEL_FADE_MS = 600;
+const DEFAULT_MESHES = [
+    () => cube(1, ["#60a5fa", "#3b82f6", "#2563eb", "#38bdf8", "#0ea5e9", "#1d4ed8"]),
+    () => tetrahedron(1, ["#f472b6", "#ec4899", "#db2777", "#f9a8d4"]),
+    () => octahedron(1, ["#34d399", "#10b981", "#059669", "#6ee7b7", "#a7f3d0", "#047857", "#4ade80", "#065f46"]),
+    () => pyramid(1, ["#fbbf24", "#f59e0b", "#d97706", "#fde68a", "#fcd34d"]),
+    () => icosphere(1, 1, ["#a78bfa", "#8b5cf6", "#7c3aed", "#c4b5fd"]),
+];
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function smooth01(value) {
+    const x = clamp01(value);
+    return x * x * (3 - 2 * x);
+}
+function resolveMesh(mesh) {
+    return typeof mesh === "function" ? mesh() : mesh;
+}
+// Shortest signed representation of an angle, so easing a tumble back to zero
+// never unwinds through full revolutions.
+function wrapAngle(angle) {
+    const wrapped = angle - TWO_PI * Math.floor(angle / TWO_PI);
+    return wrapped > Math.PI ? wrapped - TWO_PI : wrapped;
+}
+function hash01(index, salt) {
+    let h = (Math.imul(index + 1, 0x9e3779b9) ^ Math.imul(salt + 1, 0x85ebca6b)) >>> 0;
+    h = Math.imul(h ^ (h >>> 16), 0x45d9f3b);
+    h ^= h >>> 16;
+    return (h >>> 0) / 4294967296;
+}
+/**
+ * A progress story in three acts: 25 shapes fly in and circle just inside the
+ * view edge; as progress climbs they leave the orbit one by one and dock into
+ * a 5x5 grid at the center (docked shapes idle with a staggered spin every two
+ * seconds); at completion the finished grid holds for a second, then every
+ * shape dives into the center while shrinking away and vanishes with a small
+ * pop. Docking is driven by time-based blends toward per-shape targets, so a
+ * progress jump in either direction stays smooth.
+ */
+export class GridAssemblyAnimation {
+    constructor(options = {}) {
+        this.handles = [];
+        this.blends = new Array(COUNT).fill(0);
+        this.dockedAt = new Array(COUNT).fill(Infinity);
+        this.tumbleX = [];
+        this.tumbleY = [];
+        this.fades = [];
+        this.slots = [];
+        this.aspect = 16 / 9;
+        this.enterAt = Infinity;
+        this.exitAt = Infinity;
+        this.allDockedAt = Infinity;
+        this.collapseAt = Infinity;
+        this.lastNow = 0;
+        this.popFading = false;
+        this.finished = false;
+        const sources = options.meshes && options.meshes.length > 0 ? options.meshes : DEFAULT_MESHES;
+        this.meshes = sources.map(resolveMesh);
+        this.size = options.size ?? 0.34;
+        this.orbitPeriodMs = options.orbitPeriodMs ?? 9000;
+        this.dockMs = options.dockMs ?? 800;
+        this.backend = options.backend;
+        this.labelContent = options.label;
+        this.fadeLabel = options.fadeLabel ?? true;
+        const spacing = this.size + (options.gap ?? 0.12);
+        for (let i = 0; i < COUNT; i++) {
+            const row = Math.floor(i / GRID);
+            const col = i % GRID;
+            this.slots.push({ x: (col - 2) * spacing, y: (2 - row) * spacing, z: 0 });
+            this.tumbleX.push(TWO_PI * hash01(i, 2) - Math.PI);
+            this.tumbleY.push(TWO_PI * hash01(i, 4) - Math.PI);
+        }
+    }
+    mount(target) {
+        if (!target.style.position)
+            target.style.position = "relative";
+        const engine = new Little3dEngine({
+            backend: this.backend,
+            camera: { position: { x: 0, y: 0, z: CAMERA_Z }, fov: FOV },
+        });
+        for (let i = 0; i < COUNT; i++) {
+            this.fades.push({ mode: "one-sided", opacity: 1 });
+            this.handles.push(engine.add(this.meshes[i % this.meshes.length], { scale: 0 }));
+        }
+        this.engine = engine;
+        engine.mount(target).catch((error) => {
+            target.textContent = error instanceof Error ? error.message : String(error);
+        });
+        const measure = () => {
+            if (target.clientWidth > 0 && target.clientHeight > 0) {
+                this.aspect = target.clientWidth / target.clientHeight;
+            }
+        };
+        measure();
+        this.observer = new ResizeObserver(measure);
+        this.observer.observe(target);
+        this.label = mountAnimationLabel(target, this.labelContent);
+        if (this.fadeLabel)
+            this.label.setOpacity(0);
+    }
+    enter(now) {
+        if (this.enterAt === Infinity)
+            this.enterAt = now;
+    }
+    exit(now) {
+        if (this.exitAt === Infinity)
+            this.exitAt = now;
+    }
+    isFinished() {
+        return this.finished;
+    }
+    render(now, frame) {
+        if (!this.engine || !this.label)
+            return;
+        if (this.enterAt === Infinity) {
+            for (const handle of this.handles)
+                handle.transform.scale = 0;
+            this.engine.render();
+            return;
+        }
+        const dt = this.lastNow === 0 ? 16 : Math.min(50, now - this.lastNow);
+        this.lastNow = now;
+        this.updateBlends(dt, frame.progress, now);
+        if (this.exitAt !== Infinity && this.allDockedAt !== Infinity && this.collapseAt === Infinity) {
+            this.collapseAt = Math.max(this.exitAt, this.allDockedAt) + HOLD_MS;
+        }
+        if (now >= this.collapseAt)
+            this.renderCollapse(now);
+        else
+            this.renderStory(now, dt);
+        this.label.setText(frame.indeterminate
+            ? (typeof this.labelContent === "string" ? this.labelContent : "")
+            : `${Math.round(frame.progress * 100)}%`);
+        if (this.fadeLabel) {
+            this.label.setOpacity(animationLabelOpacity(now, this.enterAt, LABEL_FADE_MS, this.collapseAt, COLLAPSE_MS));
+        }
+        if (this.collapseAt !== Infinity && now >= this.collapseAt + COLLAPSE_MS + POP_MS) {
+            this.finished = true;
+        }
+        this.engine.render();
+    }
+    destroy() {
+        this.observer?.disconnect();
+        this.observer = undefined;
+        this.label?.container.remove();
+        this.label = undefined;
+        this.engine?.destroy();
+        this.engine = undefined;
+        this.handles.length = 0;
+        this.fades.length = 0;
+    }
+    updateBlends(dt, progress, now) {
+        const exiting = this.exitAt !== Infinity;
+        const want = exiting ? COUNT : Math.min(COUNT, Math.floor(progress * COUNT + 1e-9));
+        const rate = (dt / this.dockMs) * (exiting ? EXIT_HURRY : 1);
+        for (let i = 0; i < COUNT; i++) {
+            const target = i < want ? 1 : 0;
+            const blend = this.blends[i];
+            if (target > blend && (i === 0 || this.blends[i - 1] >= GATE_DOCK)) {
+                this.blends[i] = Math.min(1, blend + rate);
+            }
+            else if (target < blend && (i === COUNT - 1 || this.blends[i + 1] <= GATE_UNDOCK)) {
+                this.blends[i] = Math.max(0, blend - rate);
+            }
+            if (this.blends[i] >= 1) {
+                if (this.dockedAt[i] === Infinity)
+                    this.dockedAt[i] = now;
+            }
+            else {
+                this.dockedAt[i] = Infinity;
+            }
+        }
+        const allDocked = want === COUNT && this.blends.every((blend) => blend >= 1);
+        if (allDocked) {
+            if (this.allDockedAt === Infinity)
+                this.allDockedAt = now;
+        }
+        else if (!exiting) {
+            this.allDockedAt = Infinity;
+        }
+    }
+    renderStory(now, dt) {
+        const t = now - this.enterAt;
+        const halfHeight = Math.tan(FOV / 2) * CAMERA_Z;
+        const halfWidth = halfHeight * this.aspect;
+        const radius = Math.max(0.6, Math.min(halfWidth, halfHeight) - this.size * 0.55);
+        const spawnFactor = (Math.max(halfWidth, halfHeight) * 1.25 + this.size * 2) / radius;
+        for (let i = 0; i < COUNT; i++) {
+            const transform = this.handles[i].transform;
+            const eased = smooth01(this.blends[i]);
+            const introT = clamp01((t - i * INTRO_STAGGER_MS) / INTRO_MS);
+            const reach = 1 + (spawnFactor - 1) * (1 - easeOutCubic(introT));
+            const angle = Math.PI / 2 - (i / COUNT) * TWO_PI - (t / this.orbitPeriodMs) * TWO_PI;
+            const orbitX = Math.cos(angle) * radius * reach;
+            const orbitY = Math.sin(angle) * radius * reach;
+            const slot = this.slots[i];
+            transform.position.x = orbitX + (slot.x - orbitX) * eased;
+            transform.position.y = orbitY + (slot.y - orbitY) * eased;
+            transform.position.z = 0;
+            transform.scale = this.size;
+            // The tumble angle only advances while a shape is fully free, so easing it to
+            // zero during docking never crosses the +-pi seam and cannot visibly snap.
+            if (this.blends[i] === 0) {
+                this.tumbleX[i] = wrapAngle(this.tumbleX[i] + (0.0004 + 0.0008 * hash01(i, 1)) * dt);
+                this.tumbleY[i] = wrapAngle(this.tumbleY[i] + (0.0006 + 0.001 * hash01(i, 3)) * dt);
+            }
+            transform.rotation.z = 0;
+            if (this.blends[i] >= 1) {
+                const phase = (t + i * SPIN_STAGGER_MS) % SPIN_EVERY_MS;
+                const spinning = phase < SPIN_MS && now - phase >= this.dockedAt[i];
+                transform.rotation.x = 0;
+                transform.rotation.y = spinning ? TWO_PI * easeInOutCubic(phase / SPIN_MS) : 0;
+            }
+            else {
+                const free = 1 - eased;
+                transform.rotation.x = this.tumbleX[i] * free;
+                transform.rotation.y = this.tumbleY[i] * free;
+            }
+        }
+    }
+    renderCollapse(now) {
+        if (!this.captured) {
+            this.captured = this.handles.map((handle) => ({ ...handle.transform.position }));
+        }
+        const u = clamp01((now - this.collapseAt) / COLLAPSE_MS);
+        const pull = easeInCubic(u);
+        for (let i = 0; i < COUNT; i++) {
+            const transform = this.handles[i].transform;
+            const from = this.captured[i];
+            transform.position.x = from.x * (1 - pull);
+            transform.position.y = from.y * (1 - pull);
+            transform.position.z = from.z * (1 - pull);
+            transform.scale = this.size * (1 - 0.99 * pull);
+        }
+        if (u >= 1) {
+            if (!this.popFading) {
+                this.popFading = true;
+                for (let i = 0; i < COUNT; i++)
+                    this.handles[i].transparency = this.fades[i];
+            }
+            const v = clamp01((now - this.collapseAt - COLLAPSE_MS) / POP_MS);
+            for (let i = 0; i < COUNT; i++) {
+                this.fades[i].opacity = 1 - v;
+                this.handles[i].transform.scale =
+                    v >= 1 ? 0 : this.size * 0.01 * (1 + 1.6 * Math.sin(Math.PI * v));
+            }
+        }
+    }
+}

package/dist/animations/object-motion.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationFrame, SpinnerAnimation } from "../animation.js";
+import type { AnimationFrame, AnimationLabel, SpinnerAnimation } from "../animation.js";
 import { type Backend, type Mesh, type Transparency } from "../engines/little-3d-engine/little-3d-engine.js";
 import type { MotionController } from "../motion/controller.js";
 import { type ObjectMotionTransitionConfig } from "../motion/transitions.js";
@@ -27,7 +27,7 @@ export interface ObjectMotionOptions {
     mesh: Mesh | (() => Mesh);
     /** How the object moves: a circle, square, figure-8, wander, or any custom controller. */
     motion: MotionController;
-    /** Face color applied to every triangle. Default `"#cbd5e1"`. */
+    /** Face color applied to every triangle. Omit to retain the mesh's face colors. */
     color?: string;
     /** Rendering backend. Default `"canvas2d"`. */
     backend?: Backend;
@@ -39,14 +39,16 @@ export interface ObjectMotionOptions {
     facing?: Facing;
     /** Additional local-space rotation on top of path orientation. */
     rotation?: ObjectMotionRotation;
-    /** Intro transition. Defaults to `grow()`. */
+    /** Intro transition. Defaults to `enterFromObjectDirection()` (fly in along the path). */
     intro?: ObjectMotionTransitionConfig;
-    /** Outro transition. Defaults to `shrink()`. */
+    /** Outro transition. Defaults to `leaveInObjectDirection()` (fly out along the path). */
     outro?: ObjectMotionTransitionConfig;
     /** Trailing copies that chase the lead in single file. Omit for a single object. */
     tail?: ObjectMotionTail;
     /** Overlay label shown in indeterminate mode (no value to show). Hidden if omitted. */
-    label?: string;
+    label?: AnimationLabel;
+    /** Fade the label with the intro and outro transitions. Default `true`. */
+    fadeLabel?: boolean;
 }
 /** Centers a mesh at the origin and uniformly scales it to fit within `targetSize`. */
 export declare function centerAndScaleMesh(mesh: Mesh, targetSize: number): Mesh;
@@ -54,7 +56,7 @@ export declare function centerAndScaleMesh(mesh: Mesh, targetSize: number): Mesh
  * An object that moves along a {@link MotionController}'s path (a circle, a
  * square, a figure-8, a smooth wander, or any custom controller) with its nose
  * following the path tangent. The runner triggers the lifecycle: {@link enter}
- * pops it in, {@link exit} pops it out. Any mesh works (OBJ imports or engine
+ * flies it in along the path, {@link exit} flies it out. Any mesh works (OBJ imports or engine
  * primitives); `facing` corrects a model that points the wrong way, and
  * `rotation` adds local spin or tilt on top of path following.
  */
@@ -68,7 +70,8 @@ export declare class ObjectMotionAnimation implements SpinnerAnimation {
     private readonly motion;
     private readonly backend?;
     private readonly transparency?;
-    private readonly labelText?;
+    private readonly labelContent?;
+    private readonly fadeLabel;
     private readonly tailCount;
     private readonly tailGap;
     private readonly intro;
@@ -88,6 +91,15 @@ export declare class ObjectMotionAnimation implements SpinnerAnimation {
     enter(now: number): void;
     exit(now: number): void;
     isFinished(): boolean;
+    /** Milliseconds the fly-out takes; used to align a following particle trail's outro. */
+    get outroDurationMs(): number;
+    /**
+     * A {@link MotionController} that follows the object's *actual* position, including
+     * the intro fly-in and outro fly-out (it falls back to the raw motion path before
+     * {@link enter} and once idle). Feed it to a particle layer's `emitter` so the
+     * particles trail the object through its transitions instead of the bare path.
+     */
+    trailEmitter(): MotionController;
     render(now: number, frame: AnimationFrame): void;
     destroy(): void;
     private aheadAt;

package/dist/animations/object-motion.js

@@ -1,19 +1,7 @@
+import { animationLabelOpacity, mountAnimationLabel, } from "../animation-label.js";
 import { Little3dEngine, cross, normalize, scale, subtract, } from "../engines/little-3d-engine/little-3d-engine.js";
 import { multiply, rotationX, rotationY, rotationZ, } from "../engines/little-3d-engine/core/math.js";
-import { grow, shrink, } from "../motion/transitions.js";
-const LABEL_STYLE = [
-    "position:absolute",
-    "inset:0",
-    "display:flex",
-    "align-items:center",
-    "justify-content:center",
-    "pointer-events:none",
-    "font:700 1.6rem/1 system-ui,sans-serif",
-    "letter-spacing:0.02em",
-    "color:rgba(255,255,255,0.9)",
-    "text-shadow:0 1px 10px rgba(0,0,0,0.6)",
-    "z-index:1",
-].join(";");
+import { enterFromObjectDirection, leaveInObjectDirection, } from "../motion/transitions.js";
 const WORLD_UP = { x: 0, y: 1, z: 0 };
 const DEFAULT_INTRO_MS = 2100;
 const DEFAULT_OUTRO_MS = 2100;
@@ -37,6 +25,8 @@ function resolveMesh(mesh) {
     return typeof mesh === "function" ? mesh() : mesh;
 }
 function applyColor(mesh, color) {
+    if (color === undefined)
+        return mesh;
     return { vertices: mesh.vertices, faces: mesh.faces.map((face) => ({ ...face, color })) };
 }
 function faceForward(mesh, facing) {
@@ -138,7 +128,7 @@ function resolveTransition(config, fallback, durationMs) {
  * An object that moves along a {@link MotionController}'s path (a circle, a
  * square, a figure-8, a smooth wander, or any custom controller) with its nose
  * following the path tangent. The runner triggers the lifecycle: {@link enter}
- * pops it in, {@link exit} pops it out. Any mesh works (OBJ imports or engine
+ * flies it in along the path, {@link exit} flies it out. Any mesh works (OBJ imports or engine
  * primitives); `facing` corrects a model that points the wrong way, and
  * `rotation` adds local spin or tilt on top of path following.
  */
@@ -156,15 +146,16 @@ export class ObjectMotionAnimation {
         this.outroDirection = { x: 1, y: 0, z: 0 };
         const centered = centerAndScaleMesh(resolveMesh(options.mesh), options.size ?? 1);
         const facing = faceForward(centered, options.facing ?? "+x");
-        this.mesh = applyColor(facing, options.color ?? "#cbd5e1");
+        this.mesh = applyColor(facing, options.color);
         this.motion = options.motion;
         this.backend = options.backend;
         this.transparency = options.transparency;
-        this.labelText = options.label;
+        this.labelContent = options.label;
+        this.fadeLabel = options.fadeLabel ?? true;
         this.tailCount = Math.max(0, Math.floor(options.tail?.count ?? 0));
         this.tailGap = Math.max(0, options.tail?.gapMs ?? 0);
-        this.intro = resolveTransition(options.intro, grow(), DEFAULT_INTRO_MS);
-        this.outro = resolveTransition(options.outro, shrink(), DEFAULT_OUTRO_MS);
+        this.intro = resolveTransition(options.intro, enterFromObjectDirection(), DEFAULT_INTRO_MS);
+        this.outro = resolveTransition(options.outro, leaveInObjectDirection(), DEFAULT_OUTRO_MS);
         const rotation = options.rotation;
         this.rotationOffset = { x: rotation?.x ?? 0, y: rotation?.y ?? 0, z: rotation?.z ?? 0 };
         this.rotationSpin = {
@@ -181,7 +172,8 @@ export class ObjectMotionAnimation {
                 this.rotationSpin.z !== 0;
     }
     mount(target) {
-        target.style.position = "relative";
+        if (!target.style.position)
+            target.style.position = "relative";
         const engine = new Little3dEngine({
             backend: this.backend,
             camera: { position: { x: 0, y: 0, z: 3 } },
@@ -195,11 +187,9 @@ export class ObjectMotionAnimation {
         engine.mount(target).catch((error) => {
             target.textContent = error instanceof Error ? error.message : String(error);
         });
-        const label = document.createElement("div");
-        label.style.cssText = LABEL_STYLE;
-        label.setAttribute("role", "status");
-        target.appendChild(label);
-        this.label = label;
+        this.label = mountAnimationLabel(target, this.labelContent);
+        if (this.fadeLabel)
+            this.label.setOpacity(0);
     }
     enter(now) {
         if (this.started)
@@ -218,6 +208,19 @@ export class ObjectMotionAnimation {
     isFinished() {
         return this.finished;
     }
+    /** Milliseconds the fly-out takes; used to align a following particle trail's outro. */
+    get outroDurationMs() {
+        return this.outro.durationMs;
+    }
+    /**
+     * A {@link MotionController} that follows the object's *actual* position, including
+     * the intro fly-in and outro fly-out (it falls back to the raw motion path before
+     * {@link enter} and once idle). Feed it to a particle layer's `emitter` so the
+     * particles trail the object through its transitions instead of the bare path.
+     */
+    trailEmitter() {
+        return { positionAt: (t) => this.sampleAt(t)?.position ?? this.motion.positionAt(t) };
+    }
     render(now, frame) {
         if (!this.engine || !this.label)
             return;
@@ -258,13 +261,16 @@ export class ObjectMotionAnimation {
             transform.rotation.y = euler.y;
             transform.rotation.z = euler.z;
         }
-        this.label.textContent = frame.indeterminate
-            ? (this.labelText ?? "")
-            : `${Math.round(frame.progress * 100)}%`;
+        this.label.setText(frame.indeterminate
+            ? (typeof this.labelContent === "string" ? this.labelContent : "")
+            : `${Math.round(frame.progress * 100)}%`);
+        if (this.fadeLabel) {
+            this.label.setOpacity(animationLabelOpacity(now, this.started ? this.introStart : Infinity, this.intro.durationMs, this.outroStart, this.outro.durationMs));
+        }
         this.engine.render();
     }
     destroy() {
-        this.label?.remove();
+        this.label?.container.remove();
         this.label = undefined;
         this.engine?.destroy();
         this.engine = undefined;
@@ -302,7 +308,7 @@ export class ObjectMotionAnimation {
         const delta = transition.durationMs === 0 ? 1 : clamp01(elapsedMs / transition.durationMs);
         const input = this.transitionInput(phase, delta, elapsedMs, transition.durationMs, start);
         const output = transition.transition(input);
-        return this.applyTransitionOutput(input, output);
+        return this.applyTransitionOutput(input, output, phase, t);
     }
     transitionInput(phase, delta, elapsedMs, durationMs, start) {
         if (phase === "intro") {
@@ -330,9 +336,9 @@ export class ObjectMotionAnimation {
             phase,
         };
     }
-    applyTransitionOutput(input, output) {
+    applyTransitionOutput(input, output, phase, t) {
         return {
-            position: output.position ?? input.position,
+            position: output.position ?? (phase === "intro" ? this.motion.positionAt(t) : input.position),
             size: output.size ?? input.size ?? 1,
             orientation: output.orientation,
         };

package/dist/animations/particles.d.ts

@@ -0,0 +1,110 @@
+import type { AnimationFrame, AnimationLabel, SpinnerAnimation } from "../animation.js";
+import type { MotionController } from "../motion/controller.js";
+import { type Backend, type Vec3 } from "../engines/little-3d-engine/little-3d-engine.js";
+export interface ParticlesOptions {
+    /** Particles emitted per second. Default `20`. */
+    rate?: number;
+    /** Lifetime of one particle in milliseconds. Default `1800`. */
+    lifeMs?: number;
+    /** Particle colors, cycled across particles. Defaults to a built-in palette. */
+    colors?: string[];
+    /** Base particle size in world units, varied per particle. Default `0.16`. */
+    size?: number;
+    /** Base emission speed in world units per second, varied per particle. Default `0.6`. */
+    speed?: number;
+    /** Constant acceleration in world units per second squared. Default none. */
+    gravity?: Vec3;
+    /** Mean emission direction. Omit to emit uniformly in all directions. */
+    direction?: Vec3;
+    /** Cone half-angle around `direction` in radians. Default `0.5`. */
+    spread?: number;
+    /** Peak particle opacity `0..1`. Default `0.9`. */
+    opacity?: number;
+    /** Maximum spin around the view axis in radians per millisecond. Default `0.002`. */
+    spin?: number;
+    /** Rotate each billboard around the view axis to follow its current velocity. Default `false`. */
+    alignToMotion?: boolean;
+    /** Seed for the deterministic particle stream. Default `1`. */
+    seed?: number;
+    /** Rendering backend. Default `"canvas2d"`. */
+    backend?: Backend;
+    /** Optional moving emission origin. Each particle keeps the origin where it was emitted. */
+    emitter?: MotionController;
+    /**
+     * Milliseconds to keep emitting after {@link ParticlesAnimation.exit}. Default `0`
+     * (emission stops at exit). Give it a moving `emitter`'s outro duration so fresh
+     * particles keep trailing the emitter as it flies out, instead of freezing where
+     * the loop left off.
+     */
+    outroMs?: number;
+    /**
+     * Image applied to every particle (a URL or a drawable element), tinted by
+     * the particle color; the image's alpha shapes the particle. Renders
+     * through a textured renderer, fetched on demand: the WebGPU one when
+     * `backend` is `"webgpu"`, otherwise the WebGL one.
+     */
+    texture?: string | TexImageSource;
+    /** Overlay label shown in indeterminate mode (no value to show). Hidden if omitted. */
+    label?: AnimationLabel;
+    /** Fade the label as particles appear and drain away. Default `true`. */
+    fadeLabel?: boolean;
+}
+/** State of one live particle: where it is and how it looks. */
+export interface ParticleSample {
+    position: Vec3;
+    /** Rotation around the view axis, radians. */
+    roll: number;
+    size: number;
+    opacity: number;
+}
+/**
+ * A deterministic particle stream. Particle `index` is emitted at
+ * `index * spawnGapMs`; its whole life is a pure function of time, so the
+ * field holds no per-frame state and the same seed replays the same stream.
+ */
+export interface ParticleField {
+    /** Upper bound on simultaneously live particles; slots recycle beyond it. */
+    maxLive: number;
+    /** Milliseconds between consecutive emissions. */
+    spawnGapMs: number;
+    /** Lifetime of one particle in milliseconds. */
+    lifeMs: number;
+    /**
+     * State of particle `index` at `t` milliseconds after emission started, or
+     * `undefined` while unborn or after death.
+     */
+    sample(index: number, t: number): ParticleSample | undefined;
+}
+/** Create a {@link ParticleField} from the emission options. */
+export declare function particleField(options?: ParticlesOptions): ParticleField;
+/**
+ * A stream of camera-facing billboard particles: a burst, a fountain, drifting
+ * embers - shaped by the emission options. Particles fade in, drift under
+ * `gravity`, and fade out; the runner triggers the lifecycle: {@link enter}
+ * starts emission, {@link exit} stops it and lets the live particles die out
+ * as the outro.
+ */
+export declare class ParticlesAnimation implements SpinnerAnimation {
+    private engine?;
+    private label?;
+    private readonly handles;
+    private readonly fades;
+    private readonly field;
+    private readonly colors;
+    private readonly backend?;
+    private readonly texture?;
+    private readonly labelContent?;
+    private readonly fadeLabel;
+    private readonly emitter?;
+    private readonly outroMs;
+    private enterAt;
+    private exitAt;
+    private finished;
+    constructor(options?: ParticlesOptions);
+    mount(target: HTMLElement): void;
+    enter(now: number): void;
+    exit(now: number): void;
+    isFinished(): boolean;
+    render(now: number, frame: AnimationFrame): void;
+    destroy(): void;
+}