3d-spinner 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RuneL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# 3d-spinner
+
+[![tests](https://img.shields.io/github/actions/workflow/status/runelaang/3d-spinner/ci.yml?label=tests&logo=github)](https://github.com/runelaang/3d-spinner/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/3d-spinner?logo=npm)](https://www.npmjs.com/package/3d-spinner)
+[![license](https://img.shields.io/github/license/runelaang/3d-spinner)](LICENSE)
+
+A zero-dependency 3D spinner, loader, and progress indicator for the browser. It renders to a
+canvas and ships as ES modules split across separate import paths, so a consumer loads only the
+animation, motion path, and rendering backend they actually use - nothing else is pulled in.
+
+## Install
+
+```sh
+npm install 3d-spinner
+```
+
+## Quick start
+
+A spinner is a renderer (the `animation`) plus a mode. The simplest case is an indeterminate
+spinner that runs until you stop it:
+
+```js
+import { createSpinner } from "3d-spinner";
+import { SpinAnimation } from "3d-spinner/animations/spin";
+
+const spinner = createSpinner(document.getElementById("app"), {
+  type: "indeterminate",
+  animation: new SpinAnimation(),
+});
+
+// When the work is done:
+spinner.stop();    // play the outro, then stop (leaves the element in place)
+spinner.destroy(); // stop now and remove the element
+```
+
+## Reporting progress
+
+Drop the `type` (it defaults to `"progress"`) and report progress yourself as work completes.
+Give `SpinAnimation` a `progressAnimation` to make it pop in, scale with progress, and show a
+label:
+
+```js
+import { createSpinner } from "3d-spinner";
+import { SpinAnimation } from "3d-spinner/animations/spin";
+
+const spinner = createSpinner(document.getElementById("app"), {
+  animation: new SpinAnimation({ progressAnimation: {} }),
+});
+
+spinner.setProgress(0.4); // smoothly advances toward 40%
+spinner.setProgress(1);   // reaching 1 plays the outro
+```
+
+## Choosing a shape
+
+`SpinAnimation` spins a cube by default. Pass any built-in shape, or your own mesh:
+
+```js
+import { SpinAnimation } from "3d-spinner/animations/spin";
+import { tetrahedron } from "3d-spinner/engines/little-3d-engine";
+
+new SpinAnimation({ shape: tetrahedron(), color: "#3b82f6" });
+```
+
+Shapes exported from `3d-spinner/engines/little-3d-engine` include `cube`, `tetrahedron`,
+`octahedron`, `pyramid`, and several spheres (`uvSphere`, `icosphere`, `octaSphere`,
+`cubeSphere`).
+
+## How it fits together
+
+A spinner is assembled from a few independent pieces, so you can swap one without touching the
+others:
+
+- **`createSpinner`** mounts the spinner into an element and runs a single animation loop.
+- **Spinner type** decides how progress is driven. `progress` is determinate - you report a value
+  from 0 to 1 with `setProgress`. `indeterminate` is self-driving - it loops a synthetic progress
+  on a timer until you `stop()`. Any animation works with either type.
+- **Animation** is the visual that plays (a spinning shape, a moving object). Each one lives at its
+  own import path, so you load only the animation you use.
+- **Intro and outro** are the entrance and exit. The loop plays the intro once when the spinner
+  starts and the outro when it finishes - progress reaching 1, or `stop()`. `destroy()` skips the
+  outro and removes the element immediately.
+- **Motion controller** (for `ObjectMotionAnimation`) is a small, separate object that decides
+  *how* a thing moves - a circle, square, figure-8, or wander. Swap the controller to change the
+  path without changing the animation.
+- **Transition** (for `ObjectMotionAnimation`) is the optional intro/outro effect - grow or shrink
+  in place, or fly in and out along the path.
+- **The 3D engine** is the renderer underneath: a small, dependency-free engine that draws shapes
+  and meshes to a canvas, with swappable Canvas 2D, WebGL, and WebGPU backends.
+
+## Animations
+
+Each animation is imported from its own subpath, so you only pull in the one you use.
+
+| Import | Class | Description |
+| --- | --- | --- |
+| `3d-spinner/animations/spin` | `SpinAnimation` | A spinning 3D shape, a cube by default. |
+| `3d-spinner/animations/object-motion` | `ObjectMotionAnimation` | A mesh that follows a motion path, with an intro/outro you choose. |
+
+`ObjectMotionAnimation` takes a motion controller from `3d-spinner/motion` (`circleMotion`,
+`squareMotion`, `figureEightMotion`, `wanderMotion`) and optional entrance/exit transitions from
+`3d-spinner/motion/transitions` (`grow`, `shrink`, `enterFromObjectDirection`,
+`leaveInObjectDirection`) - for example a figure-8 path with a fly-in and fly-out.
+
+## API
+
+### `createSpinner(target, options)`
+
+Mounts a spinner inside `target` (an `HTMLElement`) and returns a `Spinner`. The options depend
+on the mode.
+
+**Progress** (the default, `type: "progress"`):
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `animation` | `SpinnerAnimation` | The renderer to play. Required. |
+| `progress` | `number` | Initial progress `0..1`. A value above 0 plays the intro immediately. |
+| `timeout` | `number` | Auto-complete after this many milliseconds. |
+| `until` | `Date` | Auto-complete at this time. If both are set, the earlier wins. |
+
+**Indeterminate** (`type: "indeterminate"`):
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `animation` | `SpinnerAnimation` | The renderer to play. Required. |
+| `loop` | `"bounce" \| "restart"` | `"bounce"` ramps 0 to 1 and back; `"restart"` repeats 0 to 1. Default `"bounce"`. |
+| `periodMs` | `number` | Milliseconds for one sweep. Must be finite and greater than zero. Default `2000`. |
+
+### `Spinner`
+
+| Method | Description |
+| --- | --- |
+| `setProgress(target)` | Advance progress toward `target` (`0..1`). No-op for an indeterminate spinner. |
+| `stop()` | Play the outro, then stop animating. Keeps the injected element. |
+| `destroy()` | Stop immediately and remove the injected element. Safe to call more than once. |
+
+## Rendering backend
+
+By default the spinner uses a Canvas 2D software renderer, which has no dependencies and runs
+anywhere a canvas does. The engine can also render through WebGL or WebGPU; pass `backend` to
+any of the 3D animations to switch. Backends are loaded on demand, so the code for the ones you
+do not use is never fetched.
+
+```js
+new SpinAnimation({ backend: "webgl" }); // "canvas2d" (default), "webgl", or "webgpu"
+```
+
+## The engine
+
+The renderer is a small, self-contained 3D engine, exported on its own in case you want it
+directly:
+
+- `3d-spinner/engines/little-3d-engine` - the engine (`Little3dEngine`), shapes, and math.
+- `3d-spinner/engines/little-3d-engine/loaders/obj` - a minimal OBJ loader (`parseObj`).
+- `3d-spinner/engines/little-tween-engine` - a standalone tween and easing engine
+  (`LittleTweenEngine`).
+
+Each has no dependencies of its own.
+
+## Module format
+
+ES modules only, for the browser. Use a bundler or native `<script type="module">`; the engine
+draws to a canvas, so there is no server-side rendering. ES modules do not load over `file://`,
+so serve the page over HTTP rather than opening the file directly.
+
+## Development
+
+```sh
+npm install
+npm run build   # compile src/ to dist/ (ESM + type declarations)
+npm test        # build, then run the unit tests
+npm run dev     # serve this folder; open /examples/index.html
+```
+
+## License
+
+MIT (c) RuneL

package/dist/animation.d.ts

@@ -0,0 +1,28 @@
+/** Per-frame state handed to a {@link SpinnerAnimation}. */
+export interface AnimationFrame {
+    /**
+     * Progress in the range 0..1. Lerped from the caller's target for a
+     * `progress` spinner; a synthetic looping value for an `indeterminate` one.
+     */
+    readonly progress: number;
+    /** Lerp destination for `progress` (equals `progress` for an indeterminate spinner). */
+    readonly targetProgress: number;
+    /** True when the spinner is indeterminate (progress is a synthetic loop). */
+    readonly indeterminate: boolean;
+}
+/**
+ * A reusable visual: a cube spin, a flying plane, a progress bar. The animation
+ * owns its intro/loop/outro visuals but does not decide *when* to play them -
+ * the spinner runner triggers {@link enter} and {@link exit}.
+ */
+export interface SpinnerAnimation {
+    mount(target: HTMLElement): void;
+    /** Play the intro once. Calls after the first are ignored. */
+    enter(now: number): void;
+    /** Begin the outro. {@link isFinished} becomes true once it completes. */
+    exit(now: number): void;
+    render(now: number, frame: AnimationFrame): void;
+    /** True once the outro has finished and the spinner can be torn down. */
+    isFinished(): boolean;
+    destroy(): void;
+}

package/dist/animation.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,96 @@
+import type { AnimationFrame, SpinnerAnimation } from "../animation.js";
+import { type Backend, type Mesh } from "../engines/little-3d-engine/little-3d-engine.js";
+import type { MotionController } from "../motion/controller.js";
+import { type ObjectMotionTransitionConfig } from "../motion/transitions.js";
+/** Which local axis the object's nose points down, used to correct a model that moves backwards or sideways. */
+export type Facing = "+x" | "-x" | "+y" | "-y" | "+z" | "-z";
+/** Trailing copies that chase the lead object in single file. */
+export interface ObjectMotionTail {
+    /** Number of trailing copies. */
+    count: number;
+    /** Time each copy lags the one ahead of it, in milliseconds. */
+    gapMs: number;
+}
+/** Extra local-space orientation on top of path following. */
+export interface ObjectMotionRotation {
+    /** Fixed local-space Euler offset, radians. */
+    x?: number;
+    y?: number;
+    z?: number;
+    /** Continuous spin around local X/Y/Z, radians per millisecond. */
+    spinX?: number;
+    spinY?: number;
+    spinZ?: number;
+}
+export interface ObjectMotionOptions {
+    /** Object mesh (an OBJ import or an engine primitive), or a factory returning one. */
+    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"`. */
+    color?: string;
+    /** Rendering backend. Default `"canvas2d"`. */
+    backend?: Backend;
+    /** Uniform object size after centering. Default `1`. */
+    size?: number;
+    /** The object's nose axis. Set this to correct a model that moves backwards or sideways. Default `"+x"`. */
+    facing?: Facing;
+    /** Additional local-space rotation on top of path orientation. */
+    rotation?: ObjectMotionRotation;
+    /** Intro transition. Defaults to `grow()`. */
+    intro?: ObjectMotionTransitionConfig;
+    /** Outro transition. Defaults to `shrink()`. */
+    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;
+}
+/** Centers a mesh at the origin and uniformly scales it to fit within `targetSize`. */
+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
+ * primitives); `facing` corrects a model that points the wrong way, and
+ * `rotation` adds local spin or tilt on top of path following.
+ */
+export declare class ObjectMotionAnimation implements SpinnerAnimation {
+    private engine?;
+    private label?;
+    private readonly handles;
+    private readonly banks;
+    private readonly headings;
+    private readonly mesh;
+    private readonly motion;
+    private readonly backend?;
+    private readonly labelText?;
+    private readonly tailCount;
+    private readonly tailGap;
+    private readonly intro;
+    private readonly outro;
+    private readonly rotationOffset;
+    private readonly rotationSpin;
+    private readonly hasExtraRotation;
+    private started;
+    private finished;
+    private introStart;
+    private outroStart;
+    private outroPosition;
+    private outroVelocity;
+    private outroDirection;
+    constructor(options: ObjectMotionOptions);
+    mount(target: HTMLElement): void;
+    enter(now: number): void;
+    exit(now: number): void;
+    isFinished(): boolean;
+    render(now: number, frame: AnimationFrame): void;
+    destroy(): void;
+    private aheadAt;
+    private positionAt;
+    private sampleAt;
+    private transitionSample;
+    private transitionInput;
+    private applyTransitionOutput;
+}

package/dist/animations/object-motion.js

@@ -0,0 +1,339 @@
+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(";");
+const WORLD_UP = { x: 0, y: 1, z: 0 };
+const DEFAULT_INTRO_MS = 2100;
+const DEFAULT_OUTRO_MS = 2100;
+const BANK_GAIN = 26;
+const BANK_LIMIT = 0.7;
+const BANK_SMOOTH = 0.12;
+const SAMPLE_MS = 8;
+// Rotation (proper, winding-preserving) that maps each `facing` axis onto +X.
+const FACE_FORWARD = {
+    "+x": (v) => v,
+    "-x": (v) => ({ x: -v.x, y: v.y, z: -v.z }),
+    "+z": (v) => ({ x: v.z, y: v.y, z: -v.x }),
+    "-z": (v) => ({ x: -v.z, y: v.y, z: v.x }),
+    "+y": (v) => ({ x: v.y, y: -v.x, z: v.z }),
+    "-y": (v) => ({ x: -v.y, y: v.x, z: v.z }),
+};
+function add(a, b) {
+    return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+}
+function resolveMesh(mesh) {
+    return typeof mesh === "function" ? mesh() : mesh;
+}
+function applyColor(mesh, color) {
+    return { vertices: mesh.vertices, faces: mesh.faces.map((face) => ({ ...face, color })) };
+}
+function faceForward(mesh, facing) {
+    if (facing === "+x")
+        return mesh;
+    const turn = FACE_FORWARD[facing];
+    return { vertices: mesh.vertices.map(turn), faces: mesh.faces };
+}
+/** Centers a mesh at the origin and uniformly scales it to fit within `targetSize`. */
+export function centerAndScaleMesh(mesh, targetSize) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (const vertex of mesh.vertices) {
+        minX = Math.min(minX, vertex.x);
+        minY = Math.min(minY, vertex.y);
+        minZ = Math.min(minZ, vertex.z);
+        maxX = Math.max(maxX, vertex.x);
+        maxY = Math.max(maxY, vertex.y);
+        maxZ = Math.max(maxZ, vertex.z);
+    }
+    const centerX = (minX + maxX) / 2;
+    const centerY = (minY + maxY) / 2;
+    const centerZ = (minZ + maxZ) / 2;
+    const extent = Math.max(maxX - minX, maxY - minY, maxZ - minZ) || 1;
+    const factor = targetSize / extent;
+    return {
+        vertices: mesh.vertices.map((vertex) => ({
+            x: (vertex.x - centerX) * factor,
+            y: (vertex.y - centerY) * factor,
+            z: (vertex.z - centerZ) * factor,
+        })),
+        faces: mesh.faces,
+    };
+}
+/**
+ * Orientation (engine Euler, Rz*Ry*Rx) that points the nose (+X) along
+ * `forward` and keeps `up` upright, rolled by `bank` radians about the nose.
+ */
+function orientationFor(forward, bank) {
+    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 levelUp = cross(right, fwd);
+    const up = add(scale(levelUp, Math.cos(bank)), scale(right, Math.sin(bank)));
+    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),
+    };
+}
+/** Engine rotation matrix from Euler angles (Rz * Ry * Rx). */
+function rotationMatrix(x, y, z) {
+    return multiply(rotationZ(z), multiply(rotationY(y), rotationX(x)));
+}
+/** Inverse of {@link rotationMatrix} for the engine's Rz * Ry * Rx order. */
+function eulerFromRotationMatrix(matrix) {
+    const sy = Math.hypot(matrix[0], matrix[1]);
+    if (sy > 1e-6) {
+        return {
+            x: Math.atan2(matrix[9], matrix[10]),
+            y: Math.asin(Math.max(-1, Math.min(1, -matrix[8]))),
+            z: Math.atan2(matrix[4], matrix[0]),
+        };
+    }
+    return {
+        x: Math.atan2(-matrix[6], matrix[5]),
+        y: Math.asin(Math.max(-1, Math.min(1, -matrix[8]))),
+        z: 0,
+    };
+}
+/** Compose path orientation with a local-space offset/spin rotation. */
+function combineLocalRotation(path, extra) {
+    return eulerFromRotationMatrix(multiply(rotationMatrix(path.x, path.y, path.z), rotationMatrix(extra.x, extra.y, extra.z)));
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function motionVectorAt(motion, t) {
+    return scale(subtract(motion.positionAt(t + 1), motion.positionAt(t - 1)), 0.5);
+}
+function resolveDirection(velocity, fallback) {
+    return Math.hypot(velocity.x, velocity.y, velocity.z) > 1e-6 ? normalize(velocity) : fallback;
+}
+function resolveTransition(config, fallback, durationMs) {
+    if (!config)
+        return { transition: fallback, durationMs };
+    if (typeof config === "function")
+        return { transition: config, durationMs };
+    return { transition: config.transition, durationMs: Math.max(0, config.durationMs ?? 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
+ * primitives); `facing` corrects a model that points the wrong way, and
+ * `rotation` adds local spin or tilt on top of path following.
+ */
+export class ObjectMotionAnimation {
+    constructor(options) {
+        this.handles = [];
+        this.banks = [];
+        this.headings = [];
+        this.started = false;
+        this.finished = false;
+        this.introStart = 0;
+        this.outroStart = Infinity;
+        this.outroPosition = { x: 0, y: 0, z: 0 };
+        this.outroVelocity = { x: 0, y: 0, z: 0 };
+        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.motion = options.motion;
+        this.backend = options.backend;
+        this.labelText = options.label;
+        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);
+        const rotation = options.rotation;
+        this.rotationOffset = { x: rotation?.x ?? 0, y: rotation?.y ?? 0, z: rotation?.z ?? 0 };
+        this.rotationSpin = {
+            x: rotation?.spinX ?? 0,
+            y: rotation?.spinY ?? 0,
+            z: rotation?.spinZ ?? 0,
+        };
+        this.hasExtraRotation =
+            this.rotationOffset.x !== 0 ||
+                this.rotationOffset.y !== 0 ||
+                this.rotationOffset.z !== 0 ||
+                this.rotationSpin.x !== 0 ||
+                this.rotationSpin.y !== 0 ||
+                this.rotationSpin.z !== 0;
+    }
+    mount(target) {
+        target.style.position = "relative";
+        const engine = new Little3dEngine({
+            backend: this.backend,
+            camera: { position: { x: 0, y: 0, z: 3 } },
+        });
+        for (let i = 0; i <= this.tailCount; i++) {
+            this.handles.push(engine.add(this.mesh));
+            this.banks.push(0);
+            this.headings.push({ x: 1, y: 0, z: 0 });
+        }
+        this.engine = engine;
+        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;
+    }
+    enter(now) {
+        if (this.started)
+            return;
+        this.started = true;
+        this.introStart = now;
+    }
+    exit(now) {
+        if (!this.started || this.outroStart !== Infinity)
+            return;
+        this.outroPosition = this.motion.positionAt(now);
+        this.outroVelocity = motionVectorAt(this.motion, now);
+        this.outroDirection = resolveDirection(this.outroVelocity, this.headings[0]);
+        this.outroStart = now;
+    }
+    isFinished() {
+        return this.finished;
+    }
+    render(now, frame) {
+        if (!this.engine || !this.label)
+            return;
+        if (this.outroStart !== Infinity && now >= this.outroStart + this.outro.durationMs + this.tailCount * this.tailGap) {
+            this.finished = true;
+        }
+        for (let k = 0; k < this.handles.length; k++) {
+            const transform = this.handles[k].transform;
+            const t = now - k * this.tailGap;
+            const sample = this.sampleAt(t);
+            if (!sample) {
+                transform.scale = 0;
+                continue;
+            }
+            transform.scale = sample.size;
+            let euler = sample.orientation;
+            if (!euler) {
+                const heading = subtract(this.positionAt(t + SAMPLE_MS) ?? sample.position, sample.position);
+                if (Math.hypot(heading.x, heading.y, heading.z) > 1e-5) {
+                    this.headings[k] = normalize(heading);
+                }
+                const ahead = this.aheadAt(t) ?? this.headings[k];
+                const targetBank = Math.max(-BANK_LIMIT, Math.min(BANK_LIMIT, cross(this.headings[k], ahead).y * BANK_GAIN));
+                this.banks[k] += (targetBank - this.banks[k]) * BANK_SMOOTH;
+                euler = orientationFor(this.headings[k], this.banks[k]);
+            }
+            if (this.hasExtraRotation) {
+                euler = combineLocalRotation(euler, {
+                    x: this.rotationOffset.x + this.rotationSpin.x * t,
+                    y: this.rotationOffset.y + this.rotationSpin.y * t,
+                    z: this.rotationOffset.z + this.rotationSpin.z * t,
+                });
+            }
+            transform.position.x = sample.position.x;
+            transform.position.y = sample.position.y;
+            transform.position.z = sample.position.z;
+            transform.rotation.x = euler.x;
+            transform.rotation.y = euler.y;
+            transform.rotation.z = euler.z;
+        }
+        this.label.textContent = frame.indeterminate
+            ? (this.labelText ?? "")
+            : `${Math.round(frame.progress * 100)}%`;
+        this.engine.render();
+    }
+    destroy() {
+        this.label?.remove();
+        this.label = undefined;
+        this.engine?.destroy();
+        this.engine = undefined;
+        this.handles.length = 0;
+    }
+    aheadAt(t) {
+        const next = this.positionAt(t + SAMPLE_MS);
+        const afterNext = this.positionAt(t + 2 * SAMPLE_MS);
+        if (!next || !afterNext)
+            return undefined;
+        const ahead = subtract(afterNext, next);
+        if (Math.hypot(ahead.x, ahead.y, ahead.z) <= 1e-5)
+            return undefined;
+        return normalize(ahead);
+    }
+    positionAt(t) {
+        return this.sampleAt(t)?.position;
+    }
+    sampleAt(t) {
+        if (!this.started || t < this.introStart)
+            return undefined;
+        if (t < this.introStart + this.intro.durationMs) {
+            return this.transitionSample("intro", t, this.intro, this.introStart);
+        }
+        if (this.outroStart !== Infinity) {
+            if (t > this.outroStart + this.outro.durationMs)
+                return undefined;
+            if (t >= this.outroStart)
+                return this.transitionSample("outro", t, this.outro, this.outroStart);
+        }
+        return { position: this.motion.positionAt(t), size: 1 };
+    }
+    transitionSample(phase, t, transition, start) {
+        const elapsedMs = Math.max(0, t - start);
+        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);
+    }
+    transitionInput(phase, delta, elapsedMs, durationMs, start) {
+        if (phase === "intro") {
+            const handoff = start + durationMs;
+            const velocity = motionVectorAt(this.motion, handoff);
+            return {
+                delta,
+                position: this.motion.positionAt(handoff),
+                direction: resolveDirection(velocity, { x: 1, y: 0, z: 0 }),
+                velocity,
+                size: 1,
+                durationMs,
+                elapsedMs,
+                phase,
+            };
+        }
+        return {
+            delta,
+            position: this.outroPosition,
+            direction: this.outroDirection,
+            velocity: this.outroVelocity,
+            size: 1,
+            durationMs,
+            elapsedMs,
+            phase,
+        };
+    }
+    applyTransitionOutput(input, output) {
+        return {
+            position: output.position ?? input.position,
+            size: output.size ?? input.size ?? 1,
+            orientation: output.orientation,
+        };
+    }
+}