3d-spinner 0.9.0

package/dist/animations/spin.d.ts

@@ -0,0 +1,44 @@
+import type { AnimationFrame, SpinnerAnimation } from "../animation.js";
+import { type Backend, type Mesh } from "../engines/little-3d-engine/little-3d-engine.js";
+import { type ProgressAnimationOptions } from "../progress-animation.js";
+export interface SpinAnimationOptions {
+    /** Shape to spin: a mesh, or a factory that returns one. Default: a cube. */
+    shape?: Mesh | (() => Mesh);
+    /** Face color(s): one color for every face, or an array applied per face. */
+    color?: string | string[];
+    /** Rotation speed around the X axis, in radians per millisecond. Default `0.0007`. */
+    spinX?: number;
+    /** Rotation speed around the Y axis, in radians per millisecond. Default `0.0011`. */
+    spinY?: number;
+    /** Rendering backend. Default `"canvas2d"`. */
+    backend?: Backend;
+    /**
+     * Enable the start/end pop and progress-driven scale, with an optional overlay
+     * label. Omit to spin at constant size with no progress reaction.
+     */
+    progressAnimation?: ProgressAnimationOptions;
+}
+/**
+ * A spinning, flat-lit 3D shape (a cube by default). With `progressAnimation`
+ * set it pops in/out and its scale tracks progress, with an optional label;
+ * otherwise it just spins at a constant size.
+ */
+export declare class SpinAnimation implements SpinnerAnimation {
+    private engine?;
+    private handle?;
+    private label?;
+    private readonly mesh;
+    private readonly spinX;
+    private readonly spinY;
+    private readonly backend?;
+    private readonly progress?;
+    private exited;
+    constructor(options?: SpinAnimationOptions);
+    mount(target: HTMLElement): void;
+    enter(now: number): void;
+    exit(now: number): void;
+    isFinished(): boolean;
+    render(now: number, frame: AnimationFrame): void;
+    destroy(): void;
+    private applyLabel;
+}

package/dist/animations/spin.js

@@ -0,0 +1,108 @@
+import { Little3dEngine, cube, } from "../engines/little-3d-engine/little-3d-engine.js";
+import { ProgressAnimation, } from "../progress-animation.js";
+const LABEL_STYLE = [
+    "position:absolute",
+    "inset:0",
+    "display:flex",
+    "align-items:center",
+    "justify-content:center",
+    "pointer-events:none",
+    "font:600 1.1rem/1.2 system-ui,sans-serif",
+    "letter-spacing:0.06em",
+    "text-transform:lowercase",
+    "color:rgba(255,255,255,0.65)",
+    "z-index:1",
+].join(";");
+function resolveMesh(shape) {
+    if (!shape)
+        return cube();
+    return typeof shape === "function" ? shape() : shape;
+}
+function applyColor(mesh, color) {
+    if (color === undefined || (Array.isArray(color) && color.length === 0))
+        return mesh;
+    const pick = Array.isArray(color) ? (i) => color[i % color.length] : () => color;
+    return { vertices: mesh.vertices, faces: mesh.faces.map((f, i) => ({ ...f, color: pick(i) })) };
+}
+/**
+ * A spinning, flat-lit 3D shape (a cube by default). With `progressAnimation`
+ * set it pops in/out and its scale tracks progress, with an optional label;
+ * otherwise it just spins at a constant size.
+ */
+export class SpinAnimation {
+    constructor(options = {}) {
+        this.exited = false;
+        this.mesh = applyColor(resolveMesh(options.shape), options.color);
+        this.spinX = options.spinX ?? 0.0007;
+        this.spinY = options.spinY ?? 0.0011;
+        this.backend = options.backend;
+        this.progress = options.progressAnimation
+            ? new ProgressAnimation(options.progressAnimation)
+            : undefined;
+    }
+    mount(target) {
+        target.style.position = "relative";
+        const engine = new Little3dEngine({
+            backend: this.backend,
+            camera: { position: { x: 0, y: 0, z: 2.8 } },
+        });
+        this.handle = engine.add(this.mesh);
+        this.engine = engine;
+        engine.mount(target).catch((error) => {
+            target.textContent = error instanceof Error ? error.message : String(error);
+        });
+        if (this.progress) {
+            const label = document.createElement("div");
+            label.style.cssText = LABEL_STYLE;
+            label.setAttribute("aria-hidden", "true");
+            label.hidden = true;
+            target.appendChild(label);
+            this.label = label;
+        }
+    }
+    enter(now) {
+        this.progress?.enter(now);
+    }
+    exit(now) {
+        this.exited = true;
+        this.progress?.exit(now);
+    }
+    isFinished() {
+        return this.progress ? this.progress.isFinished() : this.exited;
+    }
+    render(now, frame) {
+        if (!this.engine || !this.handle)
+            return;
+        const rotation = this.handle.transform.rotation;
+        rotation.x = now * this.spinX;
+        rotation.y = now * this.spinY;
+        if (this.progress) {
+            const visual = this.progress.update(now, frame.progress, frame.targetProgress);
+            this.handle.transform.scale = visual.hidden ? 0 : visual.scale;
+            this.applyLabel(visual);
+        }
+        else {
+            this.handle.transform.scale = 1;
+        }
+        this.engine.render();
+    }
+    destroy() {
+        this.label?.remove();
+        this.label = undefined;
+        this.engine?.destroy();
+        this.engine = undefined;
+        this.handle = undefined;
+    }
+    applyLabel(visual) {
+        if (!this.label)
+            return;
+        if (visual.hidden || visual.text == null) {
+            this.label.hidden = true;
+            this.label.textContent = "";
+            return;
+        }
+        this.label.hidden = false;
+        this.label.textContent = visual.text;
+        this.label.style.opacity = String(visual.textOpacity);
+    }
+}

package/dist/engines/little-3d-engine/core/camera.d.ts

@@ -0,0 +1,26 @@
+import { type Mat4, type Vec3 } from "./math.js";
+/** Camera configuration. */
+export interface CameraOptions {
+    /** Eye position. Default `{ x: 0, y: 0, z: 4 }` (looking toward -Z). */
+    position: Vec3;
+    /** Vertical field of view in radians. Default `~0.96` (55 degrees). */
+    fov: number;
+    /** Near clip distance. Default `0.1`. */
+    near: number;
+    /** Far clip distance. Default `100`. */
+    far: number;
+}
+/** A perspective camera looking down the -Z axis from its `position`. */
+export declare class Camera {
+    readonly options: CameraOptions;
+    constructor(options?: Partial<CameraOptions>);
+    /** Transform a world-space point into view (camera) space. */
+    toView(p: Vec3): Vec3;
+    /** Combined view-projection matrix for the given viewport aspect ratio. */
+    viewProjection(aspect: number): Mat4;
+    /** Convert a normalized device coordinate (-1..1) to a pixel position. */
+    toScreen(ndc: Vec3, width: number, height: number): {
+        x: number;
+        y: number;
+    };
+}

package/dist/engines/little-3d-engine/core/camera.js

@@ -0,0 +1,32 @@
+import { multiply, perspective, transformAffine, translation, } from "./math.js";
+const DEFAULTS = {
+    position: { x: 0, y: 0, z: 4 },
+    fov: (55 * Math.PI) / 180,
+    near: 0.1,
+    far: 100,
+};
+/** A perspective camera looking down the -Z axis from its `position`. */
+export class Camera {
+    constructor(options) {
+        this.options = { ...DEFAULTS, ...options };
+    }
+    /** Transform a world-space point into view (camera) space. */
+    toView(p) {
+        const { position } = this.options;
+        return transformAffine(translation(-position.x, -position.y, -position.z), p);
+    }
+    /** Combined view-projection matrix for the given viewport aspect ratio. */
+    viewProjection(aspect) {
+        const { position, fov, near, far } = this.options;
+        const view = translation(-position.x, -position.y, -position.z);
+        const projection = perspective(fov, aspect, near, far);
+        return multiply(projection, view);
+    }
+    /** Convert a normalized device coordinate (-1..1) to a pixel position. */
+    toScreen(ndc, width, height) {
+        return {
+            x: (ndc.x * 0.5 + 0.5) * width,
+            y: (1 - (ndc.y * 0.5 + 0.5)) * height,
+        };
+    }
+}

package/dist/engines/little-3d-engine/core/geometry.d.ts

@@ -0,0 +1,27 @@
+import { type Vec3 } from "./math.js";
+import type { Mesh } from "./mesh.js";
+/** Parse a CSS hex color (`#rgb` or `#rrggbb`) into 0..255 channels. */
+export declare function parseColor(color: string): [number, number, number];
+/** Flat triangle soup ready for GPU upload: 3 floats per vertex per array. */
+export interface TriangleData {
+    positions: Float32Array;
+    normals: Float32Array;
+    colors: Float32Array;
+    /** Number of vertices (positions.length / 3). */
+    count: number;
+}
+/**
+ * Triangulate a mesh into a non-indexed soup where every vertex carries its
+ * face's normal and color. This is what GPU backends upload to render flat
+ * shading without per-primitive state.
+ */
+export declare function expandToTriangles(mesh: Mesh): TriangleData;
+/**
+ * Build a sphere by subdividing a triangular seed polyhedron and projecting
+ * every vertex onto the sphere. `detail` 1 keeps the seed; each extra level
+ * splits every triangle into four. Used by the icosphere and octa-sphere.
+ *
+ * @param seedVertices Seed polyhedron vertices (any radius; they are normalized).
+ * @param seedFaces Seed triangles, wound CCW as seen from outside.
+ */
+export declare function sphereFromTriangles(seedVertices: Vec3[], seedFaces: number[][], size: number, detail: number, colors: string[]): Mesh;

package/dist/engines/little-3d-engine/core/geometry.js

@@ -0,0 +1,87 @@
+import { cross, normalize, scale, subtract } from "./math.js";
+/** Parse a CSS hex color (`#rgb` or `#rrggbb`) into 0..255 channels. */
+export function parseColor(color) {
+    const hex = color.trim().replace("#", "");
+    const full = hex.length === 3
+        ? hex
+            .split("")
+            .map((c) => c + c)
+            .join("")
+        : hex;
+    const n = parseInt(full, 16);
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+/**
+ * Triangulate a mesh into a non-indexed soup where every vertex carries its
+ * face's normal and color. This is what GPU backends upload to render flat
+ * shading without per-primitive state.
+ */
+export function expandToTriangles(mesh) {
+    let triangles = 0;
+    for (const face of mesh.faces)
+        triangles += Math.max(0, face.indices.length - 2);
+    const positions = new Float32Array(triangles * 9);
+    const normals = new Float32Array(triangles * 9);
+    const colors = new Float32Array(triangles * 9);
+    let o = 0;
+    for (const face of mesh.faces) {
+        const v0 = mesh.vertices[face.indices[0]];
+        const v1 = mesh.vertices[face.indices[1]];
+        const v2 = mesh.vertices[face.indices[2]];
+        const normal = normalize(cross(subtract(v1, v0), subtract(v2, v0)));
+        const [r, g, b] = parseColor(face.color);
+        const cr = r / 255;
+        const cg = g / 255;
+        const cb = b / 255;
+        for (let k = 1; k < face.indices.length - 1; k++) {
+            const tri = [face.indices[0], face.indices[k], face.indices[k + 1]];
+            for (const index of tri) {
+                const v = mesh.vertices[index];
+                positions[o] = v.x;
+                positions[o + 1] = v.y;
+                positions[o + 2] = v.z;
+                normals[o] = normal.x;
+                normals[o + 1] = normal.y;
+                normals[o + 2] = normal.z;
+                colors[o] = cr;
+                colors[o + 1] = cg;
+                colors[o + 2] = cb;
+                o += 3;
+            }
+        }
+    }
+    return { positions, normals, colors, count: positions.length / 3 };
+}
+function midpoint(a, b) {
+    return { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2, z: (a.z + b.z) / 2 };
+}
+/**
+ * Build a sphere by subdividing a triangular seed polyhedron and projecting
+ * every vertex onto the sphere. `detail` 1 keeps the seed; each extra level
+ * splits every triangle into four. Used by the icosphere and octa-sphere.
+ *
+ * @param seedVertices Seed polyhedron vertices (any radius; they are normalized).
+ * @param seedFaces Seed triangles, wound CCW as seen from outside.
+ */
+export function sphereFromTriangles(seedVertices, seedFaces, size, detail, colors) {
+    const radius = size / 2;
+    let triangles = seedFaces.map((f) => f.map((i) => normalize(seedVertices[i])));
+    const levels = Math.max(0, Math.floor(detail) - 1);
+    for (let level = 0; level < levels; level++) {
+        const next = [];
+        for (const [a, b, c] of triangles) {
+            const ab = normalize(midpoint(a, b));
+            const bc = normalize(midpoint(b, c));
+            const ca = normalize(midpoint(c, a));
+            next.push([a, ab, ca], [b, bc, ab], [c, ca, bc], [ab, bc, ca]);
+        }
+        triangles = next;
+    }
+    const vertices = [];
+    const faces = triangles.map((tri, i) => {
+        const base = vertices.length;
+        vertices.push(scale(tri[0], radius), scale(tri[1], radius), scale(tri[2], radius));
+        return { indices: [base, base + 1, base + 2], color: colors[i % colors.length] };
+    });
+    return { vertices, faces };
+}

package/dist/engines/little-3d-engine/core/light.d.ts

@@ -0,0 +1,31 @@
+import { type Vec3 } from "./math.js";
+/** Directional light configuration. */
+export interface LightOptions {
+    /** Direction the light travels. Default points down-forward into the scene. */
+    direction: Vec3;
+    /** Direct light strength `0..1`. Default `0.85`. */
+    intensity: number;
+    /** Base illumination on unlit faces `0..1`. Default `0.25`. */
+    ambient: number;
+}
+/** Resolved light values passed to a renderer each frame. */
+export interface LightParams {
+    /** Unit vector pointing toward the light. */
+    toLight: Vec3;
+    intensity: number;
+    ambient: number;
+}
+/**
+ * Flat-shade a face: brighten its base `color` by how directly its `normal`
+ * faces the light, floored at the ambient level. Returns an `rgb(...)` string.
+ */
+export declare function shadeColor(normal: Vec3, color: string, light: LightParams): string;
+/** A single directional light with an ambient term, used for flat shading. */
+export declare class Light {
+    readonly options: LightOptions;
+    /** Resolved values for renderers. */
+    readonly params: LightParams;
+    constructor(options?: Partial<LightOptions>);
+    /** Convenience wrapper around {@link shadeColor} using this light. */
+    shade(normal: Vec3, color: string): string;
+}

package/dist/engines/little-3d-engine/core/light.js

@@ -0,0 +1,35 @@
+import { dot, normalize, scale } from "./math.js";
+import { parseColor } from "./geometry.js";
+const DEFAULTS = {
+    direction: { x: -0.4, y: -0.7, z: -0.6 },
+    intensity: 0.85,
+    ambient: 0.25,
+};
+function clamp01(value) {
+    return Math.min(1, Math.max(0, value));
+}
+/**
+ * Flat-shade a face: brighten its base `color` by how directly its `normal`
+ * faces the light, floored at the ambient level. Returns an `rgb(...)` string.
+ */
+export function shadeColor(normal, color, light) {
+    const lambert = Math.max(0, dot(normal, light.toLight));
+    const brightness = clamp01(light.ambient + light.intensity * lambert);
+    const [r, g, b] = parseColor(color);
+    return `rgb(${Math.round(r * brightness)}, ${Math.round(g * brightness)}, ${Math.round(b * brightness)})`;
+}
+/** A single directional light with an ambient term, used for flat shading. */
+export class Light {
+    constructor(options) {
+        this.options = { ...DEFAULTS, ...options };
+        this.params = {
+            toLight: normalize(scale(this.options.direction, -1)),
+            intensity: this.options.intensity,
+            ambient: this.options.ambient,
+        };
+    }
+    /** Convenience wrapper around {@link shadeColor} using this light. */
+    shade(normal, color) {
+        return shadeColor(normal, color, this.params);
+    }
+}

package/dist/engines/little-3d-engine/core/math.d.ts

@@ -0,0 +1,50 @@
+/** A point or direction in 3D space. */
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Create a {@link Vec3}. */
+export declare function vec3(x: number, y: number, z: number): Vec3;
+/** Subtract `b` from `a` (`a - b`). */
+export declare function subtract(a: Vec3, b: Vec3): Vec3;
+/** Cross product `a x b` (a vector perpendicular to both). */
+export declare function cross(a: Vec3, b: Vec3): Vec3;
+/** Dot product `a . b`. */
+export declare function dot(a: Vec3, b: Vec3): number;
+/** Scale a vector by a scalar. */
+export declare function scale(v: Vec3, s: number): Vec3;
+/** Return a unit-length copy of `v` (zero vector is returned unchanged). */
+export declare function normalize(v: Vec3): Vec3;
+/**
+ * A 4x4 matrix in column-major order (16 numbers), suitable for chaining
+ * model, view, and projection transforms.
+ */
+export type Mat4 = number[];
+/** The 4x4 identity matrix. */
+export declare function identity(): Mat4;
+/** Multiply two matrices (`a * b`); applies `b` first, then `a`. */
+export declare function multiply(a: Mat4, b: Mat4): Mat4;
+/** Translation matrix. */
+export declare function translation(x: number, y: number, z: number): Mat4;
+/** Uniform scale matrix. */
+export declare function scaleMatrix(s: number): Mat4;
+/** Rotation matrix about the X axis (radians). */
+export declare function rotationX(rad: number): Mat4;
+/** Rotation matrix about the Y axis (radians). */
+export declare function rotationY(rad: number): Mat4;
+/** Rotation matrix about the Z axis (radians). */
+export declare function rotationZ(rad: number): Mat4;
+/**
+ * Perspective projection matrix.
+ *
+ * @param fovY Vertical field of view in radians.
+ * @param aspect Viewport width divided by height.
+ * @param near Near clip distance.
+ * @param far Far clip distance.
+ */
+export declare function perspective(fovY: number, aspect: number, near: number, far: number): Mat4;
+/** Transform a point by a matrix, applying the perspective divide. */
+export declare function transformPoint(m: Mat4, p: Vec3): Vec3;
+/** Transform a point by a matrix without the perspective divide. */
+export declare function transformAffine(m: Mat4, p: Vec3): Vec3;

package/dist/engines/little-3d-engine/core/math.js

@@ -0,0 +1,109 @@
+/** Create a {@link Vec3}. */
+export function vec3(x, y, z) {
+    return { x, y, z };
+}
+/** Subtract `b` from `a` (`a - b`). */
+export function subtract(a, b) {
+    return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
+}
+/** Cross product `a x b` (a vector perpendicular to both). */
+export function cross(a, b) {
+    return {
+        x: a.y * b.z - a.z * b.y,
+        y: a.z * b.x - a.x * b.z,
+        z: a.x * b.y - a.y * b.x,
+    };
+}
+/** Dot product `a . b`. */
+export function dot(a, b) {
+    return a.x * b.x + a.y * b.y + a.z * b.z;
+}
+/** Scale a vector by a scalar. */
+export function scale(v, s) {
+    return { x: v.x * s, y: v.y * s, z: v.z * s };
+}
+/** Return a unit-length copy of `v` (zero vector is returned unchanged). */
+export function normalize(v) {
+    const length = Math.hypot(v.x, v.y, v.z);
+    if (length === 0)
+        return { x: 0, y: 0, z: 0 };
+    return { x: v.x / length, y: v.y / length, z: v.z / length };
+}
+/** The 4x4 identity matrix. */
+export function identity() {
+    return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+}
+/** Multiply two matrices (`a * b`); applies `b` first, then `a`. */
+export function multiply(a, b) {
+    const out = new Array(16);
+    for (let col = 0; col < 4; col++) {
+        for (let row = 0; row < 4; row++) {
+            let sum = 0;
+            for (let k = 0; k < 4; k++) {
+                sum += a[k * 4 + row] * b[col * 4 + k];
+            }
+            out[col * 4 + row] = sum;
+        }
+    }
+    return out;
+}
+/** Translation matrix. */
+export function translation(x, y, z) {
+    return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, y, z, 1];
+}
+/** Uniform scale matrix. */
+export function scaleMatrix(s) {
+    return [s, 0, 0, 0, 0, s, 0, 0, 0, 0, s, 0, 0, 0, 0, 1];
+}
+/** Rotation matrix about the X axis (radians). */
+export function rotationX(rad) {
+    const c = Math.cos(rad);
+    const s = Math.sin(rad);
+    return [1, 0, 0, 0, 0, c, s, 0, 0, -s, c, 0, 0, 0, 0, 1];
+}
+/** Rotation matrix about the Y axis (radians). */
+export function rotationY(rad) {
+    const c = Math.cos(rad);
+    const s = Math.sin(rad);
+    return [c, 0, -s, 0, 0, 1, 0, 0, s, 0, c, 0, 0, 0, 0, 1];
+}
+/** Rotation matrix about the Z axis (radians). */
+export function rotationZ(rad) {
+    const c = Math.cos(rad);
+    const s = Math.sin(rad);
+    return [c, s, 0, 0, -s, c, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+}
+/**
+ * Perspective projection matrix.
+ *
+ * @param fovY Vertical field of view in radians.
+ * @param aspect Viewport width divided by height.
+ * @param near Near clip distance.
+ * @param far Far clip distance.
+ */
+export function perspective(fovY, aspect, near, far) {
+    const f = 1 / Math.tan(fovY / 2);
+    const nf = 1 / (near - far);
+    return [
+        f / aspect, 0, 0, 0,
+        0, f, 0, 0,
+        0, 0, (far + near) * nf, -1,
+        0, 0, 2 * far * near * nf, 0,
+    ];
+}
+/** Transform a point by a matrix, applying the perspective divide. */
+export function transformPoint(m, p) {
+    const x = m[0] * p.x + m[4] * p.y + m[8] * p.z + m[12];
+    const y = m[1] * p.x + m[5] * p.y + m[9] * p.z + m[13];
+    const z = m[2] * p.x + m[6] * p.y + m[10] * p.z + m[14];
+    const w = m[3] * p.x + m[7] * p.y + m[11] * p.z + m[15] || 1;
+    return { x: x / w, y: y / w, z: z / w };
+}
+/** Transform a point by a matrix without the perspective divide. */
+export function transformAffine(m, p) {
+    return {
+        x: m[0] * p.x + m[4] * p.y + m[8] * p.z + m[12],
+        y: m[1] * p.x + m[5] * p.y + m[9] * p.z + m[13],
+        z: m[2] * p.x + m[6] * p.y + m[10] * p.z + m[14],
+    };
+}

package/dist/engines/little-3d-engine/core/mesh.d.ts

@@ -0,0 +1,22 @@
+import type { Vec3 } from "./math.js";
+/** A single flat polygon: indices into the mesh `vertices` plus a base color. */
+export interface Face {
+    /** Vertex indices, wound counter-clockwise when viewed from outside. */
+    indices: number[];
+    /** Base CSS color, for example `"#3b82f6"`. Shading is applied on top of it. */
+    color: string;
+}
+/** Geometry: a list of vertices and the colored faces that connect them. */
+export interface Mesh {
+    vertices: Vec3[];
+    faces: Face[];
+}
+/** Position and orientation (Euler radians) applied to a mesh when rendered. */
+export interface Transform {
+    position: Vec3;
+    rotation: Vec3;
+    /** Uniform scale multiplier. Default `1`. */
+    scale: number;
+}
+/** Create a {@link Transform} with sensible defaults (origin, no rotation). */
+export declare function transform(init?: Partial<Transform>): Transform;

package/dist/engines/little-3d-engine/core/mesh.js

@@ -0,0 +1,8 @@
+/** Create a {@link Transform} with sensible defaults (origin, no rotation). */
+export function transform(init) {
+    return {
+        position: init?.position ?? { x: 0, y: 0, z: 0 },
+        rotation: init?.rotation ?? { x: 0, y: 0, z: 0 },
+        scale: init?.scale ?? 1,
+    };
+}

package/dist/engines/little-3d-engine/little-3d-engine.d.ts

@@ -0,0 +1,75 @@
+import { type CameraOptions } from "./core/camera.js";
+import { type LightOptions } from "./core/light.js";
+import { type Mesh, type Transform } from "./core/mesh.js";
+import { type Backend } from "./renderer.js";
+/** Options for {@link Little3dEngine}. */
+export interface Little3dEngineOptions {
+    /** Rendering backend. Loaded on demand. Default `"canvas2d"`. */
+    backend?: Backend;
+    camera?: Partial<CameraOptions>;
+    light?: Partial<LightOptions>;
+    /** Solid background color; omit for a transparent canvas (overlay use). */
+    background?: string;
+}
+/** A live mesh in the scene. Mutate `transform` to move or rotate it. */
+export interface MeshHandle {
+    readonly mesh: Mesh;
+    readonly transform: Transform;
+    /** Remove this mesh from the scene. */
+    remove(): void;
+}
+/**
+ * A minimal software/hardware 3D engine. It projects colored meshes with flat
+ * directional lighting through a swappable {@link Backend} renderer. Mount it
+ * into any element to render in a component, or into a transparent positioned
+ * element to overlay a page.
+ */
+export declare class Little3dEngine {
+    private readonly camera;
+    private readonly light;
+    private readonly backend;
+    private readonly background?;
+    private readonly scene;
+    private canvas?;
+    private observer?;
+    private renderer?;
+    private cssWidth;
+    private cssHeight;
+    private ready;
+    private generation;
+    private rafId;
+    private running;
+    constructor(options?: Little3dEngineOptions);
+    /**
+     * Create the canvas inside `target`, load the selected backend, and start
+     * tracking size. Resolves once the renderer is ready; rejects if the backend
+     * is unavailable. Drawing is a no-op until it resolves.
+     */
+    mount(target: HTMLElement): Promise<void>;
+    /** Add a mesh to the scene and return a handle for animating it. */
+    add(mesh: Mesh, init?: Partial<Transform>): MeshHandle;
+    private resize;
+    /** Draw a single frame from the current scene state. */
+    render(): void;
+    /** Start an internal animation loop that calls {@link render} each frame. */
+    start(): void;
+    /** Stop the internal animation loop started by {@link start}. */
+    stop(): void;
+    /** Stop animating, release the renderer, and remove the canvas. */
+    destroy(): void;
+}
+export { Camera, type CameraOptions } from "./core/camera.js";
+export { Light, type LightOptions, type LightParams } from "./core/light.js";
+export { cube } from "./shapes/cube.js";
+export { tetrahedron } from "./shapes/tetrahedron.js";
+export { octahedron } from "./shapes/octahedron.js";
+export { pyramid } from "./shapes/pyramid.js";
+export { uvSphere } from "./shapes/uv-sphere.js";
+export { icosphere } from "./shapes/icosphere.js";
+export { octaSphere } from "./shapes/octa-sphere.js";
+export { cubeSphere } from "./shapes/cube-sphere.js";
+export { expandToTriangles } from "./core/geometry.js";
+export type { Mesh, Face, Transform } from "./core/mesh.js";
+export { transform } from "./core/mesh.js";
+export type { Backend, Renderer, RenderFrame, RenderItem, RendererOptions } from "./renderer.js";
+export { type Vec3, vec3, subtract, cross, dot, scale, normalize, } from "./core/math.js";