3d-spinner 0.9.2 → 0.9.4

package/dist/animations/ghost-train.js

@@ -0,0 +1,247 @@
+import { animationLabelOpacity, mountAnimationLabel, } from "../animation-label.js";
+import { Little3dEngine, cube, cross, dot, normalize, subtract, } from "../engines/little-3d-engine/little-3d-engine.js";
+import { squareMotion } from "../motion/square.js";
+import { easeOutBack } from "../engines/little-tween-engine/core/tweens.js";
+const MAX_CARS = 50; // one car per 2% of progress
+const CAMERA_Z = 3;
+const FOV = (55 * Math.PI) / 180;
+const HALF_HEIGHT = Math.tan(FOV / 2) * CAMERA_Z;
+const RUN_GAP_MS = 130; // spacing between cars in path-time; 49 gaps stay under one lap
+const POP_MS = 320; // a new car pops into existence over this long
+const SAMPLE_MS = 8; // heading sample step
+const TURN_RATE = (0.4 * Math.PI) / 180; // max heading change per millisecond (smooth cornering)
+// Blast-off: the whole convoy funnels through the lead car's exit point and
+// follows the exact same escape path. A time-warp accelerates every car's
+// path-time after exit so all of them clear the view within MAX_OUTRO_MS.
+const MAX_OUTRO_MS = 4000;
+const WARP_ACCEL = 1000; // extra path-milliseconds accrued, = 0.5 * WARP_ACCEL * seconds^2
+const TRAIL_OUTRO_MS = 1200; // how long the lead keeps shedding stars into the outro
+const TRANSPARENCY = { mode: "two-sided", opacity: 0.275 };
+const CAR_COLORS = ["#bae6fd", "#7dd3fc", "#38bdf8", "#0ea5e9", "#a5f3fc", "#e0f2fe"];
+const WORLD_UP = { x: 0, y: 1, z: 0 };
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+/** Orientation (engine Euler) that points the car's local +X along `forward`, kept upright. */
+function orientationFor(forward) {
+    const fwd = normalize(forward);
+    let right = cross(fwd, WORLD_UP);
+    if (Math.hypot(right.x, right.y, right.z) < 1e-4)
+        right = { x: 0, y: 0, z: 1 };
+    right = normalize(right);
+    const up = cross(right, fwd);
+    const w = normalize(cross(fwd, up));
+    return {
+        x: Math.atan2(cross(w, fwd).z, w.z),
+        y: Math.asin(Math.max(-1, Math.min(1, -fwd.z))),
+        z: Math.atan2(fwd.y, fwd.x),
+    };
+}
+/** Rotate unit vector `from` toward `to` by at most `maxRad`, for a rate-limited turn. */
+function rotateToward(from, to, maxRad) {
+    const a = normalize(from);
+    const b = normalize(to);
+    const d = Math.max(-1, Math.min(1, dot(a, b)));
+    const angle = Math.acos(d);
+    if (angle <= maxRad || angle < 1e-4)
+        return b;
+    const sin = Math.sin(angle);
+    if (sin < 1e-4)
+        return b; // (near-)opposite: snap rather than spin unpredictably
+    const t = maxRad / angle;
+    const w1 = Math.sin((1 - t) * angle) / sin;
+    const w2 = Math.sin(t * angle) / sin;
+    return normalize({ x: a.x * w1 + b.x * w2, y: a.y * w1 + b.y * w2, z: a.z * w1 + b.z * w2 });
+}
+/**
+ * A progress story: a translucent train of ice cubes runs laps around a tilted
+ * square track, cars turning smoothly through the corners as if seen from above.
+ * Every 2% of progress attaches one more car, popping it into existence at the
+ * tail. At 100% the lead car keeps going in its current direction of travel and
+ * every following car funnels through that same exit point along the exact same
+ * path, the convoy accelerating clear of the view within four seconds. Car
+ * count follows the
+ * reported progress, so scrubbing in either direction stays smooth.
+ * {@link trailEmitter} exposes the lead car to a particle layer for the star trail.
+ */
+export class GhostTrainAnimation {
+    constructor(options = {}) {
+        this.cars = [];
+        this.appear = new Array(MAX_CARS).fill(0);
+        this.headings = new Array(MAX_CARS).fill(undefined);
+        this.aspect = 16 / 9;
+        this.enterAt = Infinity;
+        this.outroAt = Infinity;
+        this.carsAtOutro = 0;
+        this.exitPathTime = 0; // lead car's path-time at blast-off (the escape switch point)
+        this.exitPoint = { x: 0, y: 0, z: 0 };
+        this.exitDir = { x: 1, y: 0, z: 0 }; // shared escape direction, outward from the track
+        this.exitSpeed = 0.001; // path-units per path-millisecond at the switch (keeps speed continuous)
+        this.lastNow = 0;
+        this.finished = false;
+        this.motion = options.motion ?? squareMotion({ size: 1.7, periodMs: 6800, tilt: 0.5 });
+        this.size = options.size ?? 0.15;
+        this.backend = options.backend;
+        this.labelContent = options.label;
+        this.fadeLabel = options.fadeLabel ?? true;
+    }
+    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 },
+        });
+        const mesh = cube(1, CAR_COLORS);
+        for (let i = 0; i < MAX_CARS; i++) {
+            this.cars.push(engine.add(mesh, { scale: 0, transparency: { ...TRANSPARENCY } }));
+        }
+        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.outroAt !== Infinity || this.enterAt === Infinity)
+            return;
+        this.outroAt = now;
+        this.carsAtOutro = this.appear.filter((a) => a > 0.5).length;
+        this.exitPathTime = now - this.enterAt;
+        const from = this.motion.positionAt(this.exitPathTime);
+        const velocity = subtract(this.motion.positionAt(this.exitPathTime + 1), this.motion.positionAt(this.exitPathTime - 1));
+        const speed = Math.hypot(velocity.x, velocity.y, velocity.z);
+        this.exitPoint = from;
+        if (speed > 1e-6)
+            this.exitSpeed = speed / 2;
+        // The lead car keeps going in its current direction of travel; every car
+        // funnels through the exit point and follows that same straight path out.
+        this.exitDir = speed > 1e-6 ? normalize(velocity) : { x: 1, y: 0, z: 0 };
+    }
+    isFinished() {
+        return this.finished;
+    }
+    /** Milliseconds the lead car keeps moving into the outro; feed a trail layer's `outroMs`. */
+    get outroDurationMs() {
+        return TRAIL_OUTRO_MS;
+    }
+    /**
+     * A {@link MotionController} following the lead car's actual position, through
+     * laps and the accelerating escape. Feed it to a particle layer's `emitter`
+     * so the star trail stays behind the train.
+     */
+    trailEmitter() {
+        return {
+            positionAt: (t) => this.enterAt === Infinity
+                ? this.motion.positionAt(t)
+                : this.pathPosition(t - this.enterAt + this.warp(t)),
+        };
+    }
+    render(now, frame) {
+        if (!this.engine || !this.label)
+            return;
+        for (const car of this.cars)
+            car.transform.scale = 0;
+        if (this.enterAt === Infinity) {
+            this.engine.render();
+            return;
+        }
+        const dt = this.lastNow === 0 ? 16 : Math.min(50, now - this.lastNow);
+        this.lastNow = now;
+        // One car per 2%; round so the fiftieth attaches ~99% and has a beat to pop
+        // before the 100% blast-off (mirrors the rocket-launch count).
+        const want = this.outroAt !== Infinity
+            ? this.carsAtOutro
+            : Math.min(MAX_CARS, Math.round(frame.progress * MAX_CARS));
+        const halfWidth = HALF_HEIGHT * this.aspect;
+        const warp = this.warp(now);
+        let anyOnScreen = false;
+        for (let k = 0; k < MAX_CARS; k++) {
+            const target = k < want ? 1 : 0;
+            this.appear[k] = clamp01(this.appear[k] + Math.sign(target - this.appear[k]) * (dt / POP_MS));
+            if (this.appear[k] <= 0) {
+                this.headings[k] = undefined;
+                continue;
+            }
+            const p = now - this.enterAt - k * RUN_GAP_MS + warp;
+            const position = this.pathPosition(p);
+            if (Math.abs(position.x) > halfWidth + this.size || Math.abs(position.y) > HALF_HEIGHT + this.size) {
+                continue; // off-screen: leave it hidden
+            }
+            const ahead = subtract(this.pathPosition(p + SAMPLE_MS), position);
+            const targetDir = Math.hypot(ahead.x, ahead.y, ahead.z) > 1e-5
+                ? ahead
+                : this.headings[k] ?? { x: 1, y: 0, z: 0 };
+            this.headings[k] = this.headings[k]
+                ? rotateToward(this.headings[k], targetDir, TURN_RATE * dt)
+                : normalize(targetDir);
+            const orientation = orientationFor(this.headings[k]);
+            const transform = this.cars[k].transform;
+            transform.position.x = position.x;
+            transform.position.y = position.y;
+            transform.position.z = position.z;
+            transform.rotation.x = orientation.x;
+            transform.rotation.y = orientation.y;
+            transform.rotation.z = orientation.z;
+            transform.scale = this.size * easeOutBack(this.appear[k]);
+            anyOnScreen = true;
+        }
+        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, POP_MS, this.outroAt, TRAIL_OUTRO_MS));
+        }
+        if (this.outroAt !== Infinity && now > this.outroAt + 300 &&
+            (!anyOnScreen || now >= this.outroAt + MAX_OUTRO_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.cars.length = 0;
+    }
+    /** Extra path-time every car has accelerated forward by, `now` ms into the outro. */
+    warp(now) {
+        if (this.outroAt === Infinity)
+            return 0;
+        const seconds = (now - this.outroAt) / 1000;
+        return 0.5 * WARP_ACCEL * seconds * seconds;
+    }
+    /**
+     * The single trajectory every car rides, sampled at path-time `p`: the track
+     * up to the exit switch point, then a straight escape outward. Because the
+     * switch point and direction are shared, all cars follow the exact same path.
+     */
+    pathPosition(p) {
+        if (this.outroAt === Infinity || p <= this.exitPathTime) {
+            return this.motion.positionAt(p);
+        }
+        const distance = this.exitSpeed * (p - this.exitPathTime);
+        return {
+            x: this.exitPoint.x + this.exitDir.x * distance,
+            y: this.exitPoint.y + this.exitDir.y * distance,
+            z: this.exitPoint.z + this.exitDir.z * distance,
+        };
+    }
+}

package/dist/animations/grid-assembly.d.ts

@@ -0,0 +1,70 @@
+import type { AnimationFrame, AnimationLabel, SpinnerAnimation } from "../animation.js";
+import { type Backend, type Mesh } from "../engines/little-3d-engine/little-3d-engine.js";
+export interface GridAssemblyOptions {
+    /** Meshes (or factories) cycled across the 25 shapes. Defaults to a mixed primitive set. */
+    meshes?: Array<Mesh | (() => Mesh)>;
+    /** Uniform shape size in scene units. Default `0.34`. */
+    size?: number;
+    /** Gap between neighboring grid cells in scene units. Default `0.12`. */
+    gap?: number;
+    /** Milliseconds for one full orbit revolution. Default `9000`. */
+    orbitPeriodMs?: number;
+    /** Milliseconds one shape takes to travel between the orbit and its grid cell. Default `800`. */
+    dockMs?: number;
+    /** Rendering backend. Default `"canvas2d"`. */
+    backend?: Backend;
+    /** Overlay label shown in indeterminate mode (progress mode shows a percentage). */
+    label?: AnimationLabel;
+    /** Fade the label with the story's beginning and end. Default `true`. */
+    fadeLabel?: boolean;
+}
+/**
+ * A progress story in three acts: 25 pastel dark-blue cubes fly in and circle
+ * just inside the view edge, completing the full ring before any of them move;
+ * once the circle is complete they leave the orbit one by one as progress climbs
+ * and dock into a 5x5 grid at the center (docked cubes idle with a staggered
+ * spin every two seconds); at completion the finished grid holds for a second,
+ * then the cubes dive into the center a little staggered, shrinking away and
+ * vanishing 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 declare class GridAssemblyAnimation implements SpinnerAnimation {
+    private engine?;
+    private label?;
+    private observer?;
+    private readonly handles;
+    private readonly blends;
+    private readonly dockedAt;
+    private readonly tumbleX;
+    private readonly tumbleY;
+    private readonly collapseDelay;
+    private readonly popStarted;
+    private maxCollapseDelay;
+    private readonly fades;
+    private readonly slots;
+    private readonly meshes;
+    private readonly size;
+    private readonly orbitPeriodMs;
+    private readonly dockMs;
+    private readonly backend?;
+    private readonly labelContent?;
+    private readonly fadeLabel;
+    private aspect;
+    private enterAt;
+    private exitAt;
+    private allDockedAt;
+    private collapseAt;
+    private captured?;
+    private lastNow;
+    private finished;
+    constructor(options?: GridAssemblyOptions);
+    mount(target: HTMLElement): void;
+    enter(now: number): void;
+    exit(now: number): void;
+    isFinished(): boolean;
+    render(now: number, frame: AnimationFrame): void;
+    destroy(): void;
+    private updateBlends;
+    private renderStory;
+    private renderCollapse;
+}

package/dist/animations/grid-assembly.js

@@ -0,0 +1,282 @@
+import { animationLabelOpacity, mountAnimationLabel, } from "../animation-label.js";
+import { Little3dEngine, cube, } 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;
+// The orbit ring is fully formed once the last-staggered shape finishes flying in.
+const INTRO_DONE_MS = (COUNT - 1) * INTRO_STAGGER_MS + INTRO_MS;
+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 COLLAPSE_SPREAD_MS = 500; // shapes leave a little staggered, not all at once
+const POP_MS = 170;
+const LABEL_FADE_MS = 600;
+// Every shape is the same pastel dark-blue cube; the six face tints give it depth.
+const CUBE_COLORS = ["#8397c6", "#7186b8", "#6176a8", "#93a6cf", "#556a9c", "#7a8fc0"];
+const DEFAULT_MESHES = [() => cube(1, CUBE_COLORS)];
+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 pastel dark-blue cubes fly in and circle
+ * just inside the view edge, completing the full ring before any of them move;
+ * once the circle is complete they leave the orbit one by one as progress climbs
+ * and dock into a 5x5 grid at the center (docked cubes idle with a staggered
+ * spin every two seconds); at completion the finished grid holds for a second,
+ * then the cubes dive into the center a little staggered, shrinking away and
+ * vanishing 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.collapseDelay = [];
+        this.popStarted = new Array(COUNT).fill(false);
+        this.maxCollapseDelay = 0;
+        this.fades = [];
+        this.slots = [];
+        this.aspect = 16 / 9;
+        this.enterAt = Infinity;
+        this.exitAt = Infinity;
+        this.allDockedAt = Infinity;
+        this.collapseAt = Infinity;
+        this.lastNow = 0;
+        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);
+            this.collapseDelay.push(hash01(i, 7) * COLLAPSE_SPREAD_MS);
+        }
+        this.maxCollapseDelay = Math.max(...this.collapseDelay);
+    }
+    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 + this.maxCollapseDelay + 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;
+        // Hold every shape on the orbit until the ring is fully formed: no shape
+        // starts diving to its grid cell before the circle is complete.
+        const ringComplete = now - this.enterAt >= INTRO_DONE_MS;
+        const want = !ringComplete
+            ? 0
+            : 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 }));
+        }
+        // Each shape dives and pops on its own small delay, so the grid empties a
+        // little staggered instead of all at once.
+        for (let i = 0; i < COUNT; i++) {
+            const transform = this.handles[i].transform;
+            const from = this.captured[i];
+            const local = now - this.collapseAt - this.collapseDelay[i];
+            if (local <= 0) {
+                transform.position.x = from.x;
+                transform.position.y = from.y;
+                transform.position.z = from.z;
+                transform.scale = this.size;
+                continue;
+            }
+            const pull = easeInCubic(clamp01(local / COLLAPSE_MS));
+            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 (local >= COLLAPSE_MS) {
+                if (!this.popStarted[i]) {
+                    this.popStarted[i] = true;
+                    this.handles[i].transparency = this.fades[i];
+                }
+                const v = clamp01((local - COLLAPSE_MS) / POP_MS);
+                this.fades[i].opacity = 1 - v;
+                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;