3d-spinner 0.9.2 → 0.9.3

package/dist/engines/little-3d-engine/renderers/webgl-textured.js

@@ -0,0 +1,211 @@
+import { expandToTriangles } from "../core/geometry.js";
+import { DEFAULT_ONE_SIDED_OPACITY, opacity, resolveTwoSidedOpacity, } from "../renderer.js";
+import { planarUVs } from "./textured-helpers.js";
+import { WebGLRenderer } from "./webgl.js";
+const VERTEX_SHADER = `#version 300 es
+in vec3 aPos;
+in vec2 aUV;
+in vec3 aColor;
+uniform mat4 uViewProj;
+uniform mat4 uModel;
+out vec2 vUV;
+out vec3 vColor;
+void main() {
+  vUV = aUV;
+  vColor = aColor;
+  gl_Position = uViewProj * uModel * vec4(aPos, 1.0);
+}`;
+const FRAGMENT_SHADER = `#version 300 es
+precision mediump float;
+in vec2 vUV;
+in vec3 vColor;
+uniform sampler2D uTexture;
+uniform float uOpacity;
+out vec4 fragColor;
+void main() {
+  vec4 t = texture(uTexture, vUV);
+  fragColor = vec4(t.rgb * vColor, t.a * uOpacity);
+}`;
+function compile(gl, type, source) {
+    const shader = gl.createShader(type);
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        throw new Error(`3d-spinner: shader compile failed: ${gl.getShaderInfoLog(shader)}`);
+    }
+    return shader;
+}
+function link(gl) {
+    const program = gl.createProgram();
+    gl.attachShader(program, compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER));
+    gl.attachShader(program, compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER));
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+        throw new Error(`3d-spinner: program link failed: ${gl.getProgramInfoLog(program)}`);
+    }
+    return program;
+}
+function itemOpacity(transparency) {
+    if (!transparency)
+        return 1;
+    if (transparency.mode === "two-sided")
+        return resolveTwoSidedOpacity(transparency).front;
+    return opacity(transparency.opacity, DEFAULT_ONE_SIDED_OPACITY);
+}
+/**
+ * WebGL renderer with image textures on registered meshes; unregistered
+ * meshes render exactly as in the plain WebGL backend. Made for billboard
+ * quads: UVs are a planar projection of the mesh's XY extent, textured faces
+ * render unlit with the texture tinted by the face color, and textured
+ * instances draw after the other transparent instances. Until an image URL
+ * finishes loading its mesh renders with a plain white texture.
+ *
+ * Pass it to the engine (or an animation) as a `backend` factory so the
+ * module is only fetched when used:
+ *
+ * ```js
+ * backend: async (options) => {
+ *   const { WebGLTexturedRenderer } =
+ *     await import("3d-spinner/engines/little-3d-engine/renderers/webgl-textured");
+ *   const renderer = new WebGLTexturedRenderer(options);
+ *   renderer.setTexture(mesh, "/sprite.png");
+ *   return renderer;
+ * }
+ * ```
+ */
+export class WebGLTexturedRenderer {
+    constructor(options = {}) {
+        this.sources = new Map();
+        this.textures = new Map();
+        this.buffers = new Map();
+        this.inner = new WebGLRenderer(options);
+    }
+    /** Texture every instance of `mesh` with `source`. Call any time, also before init. */
+    setTexture(mesh, source) {
+        this.sources.set(mesh, source);
+    }
+    init(canvas) {
+        this.inner.init(canvas);
+        const gl = canvas.getContext("webgl2");
+        this.gl = gl;
+        this.program = link(gl);
+        this.locations = {
+            aPos: gl.getAttribLocation(this.program, "aPos"),
+            aUV: gl.getAttribLocation(this.program, "aUV"),
+            aColor: gl.getAttribLocation(this.program, "aColor"),
+            uViewProj: gl.getUniformLocation(this.program, "uViewProj"),
+            uModel: gl.getUniformLocation(this.program, "uModel"),
+            uTexture: gl.getUniformLocation(this.program, "uTexture"),
+            uOpacity: gl.getUniformLocation(this.program, "uOpacity"),
+        };
+    }
+    resize() {
+        this.inner.resize();
+    }
+    textureFor(mesh) {
+        const cached = this.textures.get(mesh);
+        if (cached)
+            return cached;
+        const gl = this.gl;
+        const texture = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([255, 255, 255, 255]));
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        this.textures.set(mesh, texture);
+        const upload = (image) => {
+            if (!this.gl || this.textures.get(mesh) !== texture)
+                return;
+            this.gl.bindTexture(this.gl.TEXTURE_2D, texture);
+            this.gl.texImage2D(this.gl.TEXTURE_2D, 0, this.gl.RGBA, this.gl.RGBA, this.gl.UNSIGNED_BYTE, image);
+        };
+        const source = this.sources.get(mesh);
+        if (typeof source === "string") {
+            const image = new Image();
+            image.onload = () => upload(image);
+            image.src = source;
+        }
+        else {
+            upload(source);
+        }
+        return texture;
+    }
+    buffersFor(mesh) {
+        const cached = this.buffers.get(mesh);
+        if (cached)
+            return cached;
+        const gl = this.gl;
+        const loc = this.locations;
+        const data = expandToTriangles(mesh);
+        const vao = gl.createVertexArray();
+        gl.bindVertexArray(vao);
+        const attribute = (location, array, size) => {
+            if (location < 0)
+                return;
+            const buffer = gl.createBuffer();
+            gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+            gl.bufferData(gl.ARRAY_BUFFER, array, gl.STATIC_DRAW);
+            gl.enableVertexAttribArray(location);
+            gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        };
+        attribute(loc.aPos, data.positions, 3);
+        attribute(loc.aColor, data.colors, 3);
+        attribute(loc.aUV, planarUVs(mesh), 2);
+        gl.bindVertexArray(null);
+        const result = { vao, count: data.count };
+        this.buffers.set(mesh, result);
+        return result;
+    }
+    render(frame) {
+        const plain = [];
+        const textured = [];
+        for (const item of frame.items) {
+            (this.sources.has(item.mesh) ? textured : plain).push(item);
+        }
+        this.inner.render(textured.length ? { ...frame, items: plain } : frame);
+        if (!textured.length)
+            return;
+        const gl = this.gl;
+        const loc = this.locations;
+        if (!gl || !this.program || !loc)
+            return;
+        gl.useProgram(this.program);
+        gl.uniformMatrix4fv(loc.uViewProj, false, new Float32Array(frame.viewProjection));
+        gl.uniform1i(loc.uTexture, 0);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        gl.depthMask(false);
+        for (const item of textured) {
+            const buffers = this.buffersFor(item.mesh);
+            gl.bindTexture(gl.TEXTURE_2D, this.textureFor(item.mesh));
+            gl.uniformMatrix4fv(loc.uModel, false, new Float32Array(item.model));
+            gl.uniform1f(loc.uOpacity, itemOpacity(item.transparency));
+            gl.bindVertexArray(buffers.vao);
+            gl.drawArrays(gl.TRIANGLES, 0, buffers.count);
+        }
+        gl.depthMask(true);
+        gl.disable(gl.BLEND);
+        gl.bindVertexArray(null);
+    }
+    destroy() {
+        const gl = this.gl;
+        if (gl) {
+            for (const texture of this.textures.values())
+                gl.deleteTexture(texture);
+            for (const buffers of this.buffers.values())
+                gl.deleteVertexArray(buffers.vao);
+            if (this.program)
+                gl.deleteProgram(this.program);
+        }
+        this.textures.clear();
+        this.buffers.clear();
+        this.sources.clear();
+        this.gl = undefined;
+        this.program = undefined;
+        this.locations = undefined;
+        this.inner.destroy();
+    }
+}

package/dist/engines/little-3d-engine/renderers/webgpu-textured.d.ts

@@ -0,0 +1,45 @@
+import type { Mesh } from "../core/mesh.js";
+import { type RenderFrame } from "../renderer.js";
+import { type TextureSource } from "./textured-helpers.js";
+import { WebGPURenderer } from "./webgpu.js";
+export type { TextureSource } from "./textured-helpers.js";
+/**
+ * WebGPU renderer with image textures on registered meshes; unregistered
+ * meshes render exactly as in the plain WebGPU backend. Made for billboard
+ * quads: UVs are a planar projection of the mesh's XY extent, textured faces
+ * render unlit with the texture tinted by the face color, and textured
+ * instances draw after the other transparent instances. Until an image URL
+ * finishes loading its mesh renders with a plain white texture.
+ *
+ * Pass it to the engine (or an animation) as a `backend` factory so the
+ * module is only fetched when used:
+ *
+ * ```js
+ * backend: async (options) => {
+ *   const { WebGPUTexturedRenderer } =
+ *     await import("3d-spinner/engines/little-3d-engine/renderers/webgpu-textured");
+ *   const renderer = new WebGPUTexturedRenderer(options);
+ *   renderer.setTexture(mesh, "/sprite.png");
+ *   return renderer;
+ * }
+ * ```
+ */
+export declare class WebGPUTexturedRenderer extends WebGPURenderer {
+    private texturedPipeline;
+    private sampler;
+    private texturedUniforms;
+    private texturedCapacity;
+    private readonly sources;
+    private readonly textures;
+    private readonly retired;
+    private readonly texturedBuffers;
+    private readonly bindGroups;
+    /** Texture every instance of `mesh` with `source`. Call any time, also before init. */
+    setTexture(mesh: Mesh, source: TextureSource): void;
+    init(canvas: HTMLCanvasElement): Promise<void>;
+    private textureFor;
+    private buffersFor;
+    private bindGroupFor;
+    render(frame: RenderFrame): void;
+    destroy(): void;
+}

package/dist/engines/little-3d-engine/renderers/webgpu-textured.js

@@ -0,0 +1,300 @@
+import { expandToTriangles } from "../core/geometry.js";
+import { multiply } from "../core/math.js";
+import { DEFAULT_ONE_SIDED_OPACITY, opacity, resolveTwoSidedOpacity, } from "../renderer.js";
+import { planarUVs } from "./textured-helpers.js";
+import { WebGPURenderer } from "./webgpu.js";
+const WGSL = `
+struct Uniforms {
+  viewProj: mat4x4<f32>,
+  model: mat4x4<f32>,
+  params: vec4<f32>,
+};
+@group(0) @binding(0) var<uniform> u: Uniforms;
+@group(0) @binding(1) var tex: texture_2d<f32>;
+@group(0) @binding(2) var samp: sampler;
+
+struct VSOut {
+  @builtin(position) position: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+  @location(1) color: vec3<f32>,
+};
+
+@vertex
+fn vs(@location(0) pos: vec3<f32>, @location(1) uv: vec2<f32>, @location(2) color: vec3<f32>) -> VSOut {
+  var out: VSOut;
+  out.uv = uv;
+  out.color = color;
+  out.position = u.viewProj * u.model * vec4<f32>(pos, 1.0);
+  return out;
+}
+
+@fragment
+fn fs(in: VSOut) -> @location(0) vec4<f32> {
+  let t = textureSample(tex, samp, in.uv);
+  return vec4<f32>(t.rgb * in.color, t.a * u.params.x);
+}
+`;
+// Maps OpenGL clip space (z in -1..1) to WebGPU clip space (z in 0..1).
+const CLIP_Z_FIX = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0.5, 0, 0, 0, 0.5, 1];
+const UNIFORM_STRIDE = 256;
+function itemOpacity(transparency) {
+    if (!transparency)
+        return 1;
+    if (transparency.mode === "two-sided")
+        return resolveTwoSidedOpacity(transparency).front;
+    return opacity(transparency.opacity, DEFAULT_ONE_SIDED_OPACITY);
+}
+/**
+ * WebGPU renderer with image textures on registered meshes; unregistered
+ * meshes render exactly as in the plain WebGPU backend. Made for billboard
+ * quads: UVs are a planar projection of the mesh's XY extent, textured faces
+ * render unlit with the texture tinted by the face color, and textured
+ * instances draw after the other transparent instances. Until an image URL
+ * finishes loading its mesh renders with a plain white texture.
+ *
+ * Pass it to the engine (or an animation) as a `backend` factory so the
+ * module is only fetched when used:
+ *
+ * ```js
+ * backend: async (options) => {
+ *   const { WebGPUTexturedRenderer } =
+ *     await import("3d-spinner/engines/little-3d-engine/renderers/webgpu-textured");
+ *   const renderer = new WebGPUTexturedRenderer(options);
+ *   renderer.setTexture(mesh, "/sprite.png");
+ *   return renderer;
+ * }
+ * ```
+ */
+export class WebGPUTexturedRenderer extends WebGPURenderer {
+    constructor() {
+        super(...arguments);
+        this.texturedCapacity = 0;
+        this.sources = new Map();
+        this.textures = new Map();
+        this.retired = [];
+        this.texturedBuffers = new Map();
+        this.bindGroups = new Map();
+    }
+    /** Texture every instance of `mesh` with `source`. Call any time, also before init. */
+    setTexture(mesh, source) {
+        this.sources.set(mesh, source);
+    }
+    async init(canvas) {
+        await super.init(canvas);
+        const device = this.device;
+        if (!device)
+            return;
+        const format = navigator.gpu.getPreferredCanvasFormat();
+        const module = device.createShaderModule({ code: WGSL });
+        const stage = globalThis.GPUShaderStage;
+        const layout = device.createBindGroupLayout({
+            entries: [
+                {
+                    binding: 0,
+                    visibility: stage.VERTEX | stage.FRAGMENT,
+                    buffer: { type: "uniform", hasDynamicOffset: true, minBindingSize: 144 },
+                },
+                { binding: 1, visibility: stage.FRAGMENT, texture: {} },
+                { binding: 2, visibility: stage.FRAGMENT, sampler: {} },
+            ],
+        });
+        const vertexBuffer = (location, components) => ({
+            arrayStride: components * 4,
+            attributes: [{ shaderLocation: location, offset: 0, format: `float32x${components}` }],
+        });
+        this.texturedPipeline = device.createRenderPipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+            vertex: {
+                module,
+                entryPoint: "vs",
+                buffers: [vertexBuffer(0, 3), vertexBuffer(1, 2), vertexBuffer(2, 3)],
+            },
+            fragment: {
+                module,
+                entryPoint: "fs",
+                targets: [
+                    {
+                        format,
+                        blend: {
+                            color: {
+                                srcFactor: "src-alpha",
+                                dstFactor: "one-minus-src-alpha",
+                                operation: "add",
+                            },
+                            alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                        },
+                    },
+                ],
+            },
+            primitive: { topology: "triangle-list", cullMode: "back", frontFace: "ccw" },
+            depthStencil: {
+                format: "depth24plus",
+                depthWriteEnabled: false,
+                depthCompare: "less",
+            },
+        });
+        this.sampler = device.createSampler({ magFilter: "linear", minFilter: "linear" });
+    }
+    textureFor(mesh) {
+        const cached = this.textures.get(mesh);
+        if (cached)
+            return cached;
+        const device = this.device;
+        const usage = globalThis.GPUTextureUsage;
+        const white = device.createTexture({
+            size: { width: 1, height: 1 },
+            format: "rgba8unorm",
+            usage: usage.TEXTURE_BINDING | usage.COPY_DST,
+        });
+        device.queue.writeTexture({ texture: white }, new Uint8Array([255, 255, 255, 255]), {}, { width: 1, height: 1 });
+        this.textures.set(mesh, white);
+        const upload = async (source) => {
+            const image = source instanceof HTMLImageElement ? await createImageBitmap(source) : source;
+            if (this.destroyed || !this.device || this.textures.get(mesh) !== white)
+                return;
+            const width = image.width || 1;
+            const height = image.height || 1;
+            const texture = this.device.createTexture({
+                size: { width, height },
+                format: "rgba8unorm",
+                usage: usage.TEXTURE_BINDING | usage.COPY_DST | usage.RENDER_ATTACHMENT,
+            });
+            this.device.queue.copyExternalImageToTexture({ source: image }, { texture }, { width, height });
+            // The placeholder may still be referenced by an unsubmitted command
+            // buffer, so it is retired here and destroyed with the renderer.
+            this.retired.push(white);
+            this.textures.set(mesh, texture);
+            this.bindGroups.delete(mesh);
+        };
+        const source = this.sources.get(mesh);
+        if (typeof source === "string") {
+            const image = new Image();
+            image.onload = () => void upload(image);
+            image.src = source;
+        }
+        else {
+            void upload(source);
+        }
+        return this.textures.get(mesh);
+    }
+    buffersFor(mesh) {
+        const cached = this.texturedBuffers.get(mesh);
+        if (cached)
+            return cached;
+        const data = expandToTriangles(mesh);
+        const usage = globalThis.GPUBufferUsage.VERTEX | globalThis.GPUBufferUsage.COPY_DST;
+        const upload = (array) => {
+            const buffer = this.device.createBuffer({ size: array.byteLength, usage });
+            this.device.queue.writeBuffer(buffer, 0, array);
+            return buffer;
+        };
+        const result = {
+            position: upload(data.positions),
+            uv: upload(planarUVs(mesh)),
+            color: upload(data.colors),
+            count: data.count,
+        };
+        this.texturedBuffers.set(mesh, result);
+        return result;
+    }
+    bindGroupFor(mesh) {
+        const texture = this.textureFor(mesh);
+        const cached = this.bindGroups.get(mesh);
+        if (cached && cached.buffer === this.texturedUniforms && cached.texture === texture) {
+            return cached.group;
+        }
+        const group = this.device.createBindGroup({
+            layout: this.texturedPipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: this.texturedUniforms, offset: 0, size: 144 } },
+                { binding: 1, resource: texture.createView() },
+                { binding: 2, resource: this.sampler },
+            ],
+        });
+        this.bindGroups.set(mesh, { group, buffer: this.texturedUniforms, texture });
+        return group;
+    }
+    render(frame) {
+        const plain = [];
+        const textured = [];
+        for (const item of frame.items) {
+            (this.sources.has(item.mesh) ? textured : plain).push(item);
+        }
+        super.render(textured.length ? { ...frame, items: plain } : frame);
+        if (!textured.length)
+            return;
+        if (this.destroyed || !this.device || !this.context || !this.texturedPipeline)
+            return;
+        if (frame.width === 0 || frame.height === 0)
+            return;
+        this.ensureDepth();
+        if (textured.length > this.texturedCapacity || !this.texturedUniforms) {
+            this.texturedUniforms?.destroy?.();
+            this.texturedUniforms = this.device.createBuffer({
+                size: textured.length * UNIFORM_STRIDE,
+                usage: globalThis.GPUBufferUsage.UNIFORM |
+                    globalThis.GPUBufferUsage.COPY_DST,
+            });
+            this.texturedCapacity = textured.length;
+        }
+        const viewProj = multiply(CLIP_Z_FIX, frame.viewProjection);
+        textured.forEach((item, i) => {
+            const data = new Float32Array(UNIFORM_STRIDE / 4);
+            data.set(viewProj, 0);
+            data.set(item.model, 16);
+            data.set([itemOpacity(item.transparency), 0, 0, 0], 32);
+            this.device.queue.writeBuffer(this.texturedUniforms, i * UNIFORM_STRIDE, data);
+        });
+        // The base pass skips entirely when it has no items, so this pass clears
+        // the attachments in that case instead of loading them.
+        const cleared = plain.length > 0;
+        const encoder = this.device.createCommandEncoder();
+        const pass = encoder.beginRenderPass({
+            colorAttachments: [
+                {
+                    view: this.context.getCurrentTexture().createView(),
+                    clearValue: this.clearValue,
+                    loadOp: cleared ? "load" : "clear",
+                    storeOp: "store",
+                },
+            ],
+            depthStencilAttachment: {
+                view: this.depthTexture.createView(),
+                depthClearValue: 1,
+                depthLoadOp: cleared ? "load" : "clear",
+                depthStoreOp: "store",
+            },
+        });
+        pass.setPipeline(this.texturedPipeline);
+        textured.forEach((item, i) => {
+            const mesh = this.buffersFor(item.mesh);
+            pass.setBindGroup(0, this.bindGroupFor(item.mesh), [i * UNIFORM_STRIDE]);
+            pass.setVertexBuffer(0, mesh.position);
+            pass.setVertexBuffer(1, mesh.uv);
+            pass.setVertexBuffer(2, mesh.color);
+            pass.draw(mesh.count);
+        });
+        pass.end();
+        this.device.queue.submit([encoder.finish()]);
+    }
+    destroy() {
+        for (const texture of this.textures.values())
+            texture.destroy?.();
+        for (const texture of this.retired.splice(0))
+            texture.destroy?.();
+        for (const buffers of this.texturedBuffers.values()) {
+            buffers.position.destroy?.();
+            buffers.uv.destroy?.();
+            buffers.color.destroy?.();
+        }
+        this.textures.clear();
+        this.texturedBuffers.clear();
+        this.bindGroups.clear();
+        this.sources.clear();
+        this.texturedUniforms?.destroy?.();
+        this.texturedUniforms = undefined;
+        this.texturedPipeline = undefined;
+        this.sampler = undefined;
+        super.destroy();
+    }
+}

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

@@ -2,23 +2,28 @@ import { type Renderer, type RenderFrame, type RendererOptions } from "../render
 /** Hardware renderer using WebGPU: GPU transforms with a real depth buffer. */
 export declare class WebGPURenderer implements Renderer {
     private canvas?;
-    private device;
-    private context;
+    protected device: any;
+    protected context: any;
     private pipeline;
     private transparentBackPipeline;
     private transparentFrontPipeline;
     private uniformBuffer;
     private uniformCapacity;
-    private depthTexture;
+    protected depthTexture: any;
     private depthSize;
-    private destroyed;
+    protected destroyed: boolean;
     private readonly cache;
-    private readonly clearValue;
+    protected readonly clearValue: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
     private readonly alphaMode;
     constructor(options?: RendererOptions);
     init(canvas: HTMLCanvasElement): Promise<void>;
     resize(): void;
-    private ensureDepth;
+    protected ensureDepth(): void;
     private buffers;
     private ensureUniformCapacity;
     render(frame: RenderFrame): void;

package/dist/engines/little-3d-engine/shapes/complex/plane.d.ts

@@ -0,0 +1,3 @@
+import type { Mesh } from "../../core/mesh.js";
+/** Build a low-poly plane mesh pointing along the positive X axis. */
+export declare function planeMesh(colors?: string[]): Mesh;

package/dist/engines/little-3d-engine/shapes/complex/plane.js

@@ -0,0 +1,33 @@
+const DEFAULT_COLORS = ["#e0f2fe", "#7dd3fc", "#38bdf8", "#f8fafc"];
+/** Build a low-poly plane mesh pointing along the positive X axis. */
+export function planeMesh(colors = DEFAULT_COLORS) {
+    return {
+        vertices: [
+            { x: 0.9, y: 0, z: 0 },
+            { x: -0.2, y: 0, z: 0.82 },
+            { x: -0.55, y: 0, z: 0.16 },
+            { x: -0.72, y: 0, z: 0 },
+            { x: -0.55, y: 0, z: -0.16 },
+            { x: -0.2, y: 0, z: -0.82 },
+            { x: -0.08, y: 0.12, z: 0 },
+            { x: -0.08, y: -0.1, z: 0 },
+            { x: -0.52, y: 0.38, z: 0 },
+        ],
+        faces: [
+            { indices: [6, 1, 0], color: colors[0] ?? DEFAULT_COLORS[0] },
+            { indices: [6, 2, 1], color: colors[3] ?? DEFAULT_COLORS[3] },
+            { indices: [6, 3, 2], color: colors[1] ?? DEFAULT_COLORS[1] },
+            { indices: [6, 4, 3], color: colors[2] ?? DEFAULT_COLORS[2] },
+            { indices: [6, 5, 4], color: colors[3] ?? DEFAULT_COLORS[3] },
+            { indices: [6, 0, 5], color: colors[0] ?? DEFAULT_COLORS[0] },
+            { indices: [7, 0, 1], color: colors[1] ?? DEFAULT_COLORS[1] },
+            { indices: [7, 1, 2], color: colors[2] ?? DEFAULT_COLORS[2] },
+            { indices: [7, 2, 3], color: colors[1] ?? DEFAULT_COLORS[1] },
+            { indices: [7, 3, 4], color: colors[2] ?? DEFAULT_COLORS[2] },
+            { indices: [7, 4, 5], color: colors[1] ?? DEFAULT_COLORS[1] },
+            { indices: [7, 5, 0], color: colors[2] ?? DEFAULT_COLORS[2] },
+            { indices: [3, 6, 8], color: colors[0] ?? DEFAULT_COLORS[0] },
+            { indices: [3, 8, 6], color: colors[1] ?? DEFAULT_COLORS[1] },
+        ],
+    };
+}

package/dist/engines/little-3d-engine/shapes/{cube.d.ts → primitives/cube.d.ts}

@@ -1,4 +1,4 @@
-import type { Mesh } from "../core/mesh.js";
+import type { Mesh } from "../../core/mesh.js";
 /**
  * Build a cube mesh centered on the origin.
  *

package/dist/engines/little-3d-engine/shapes/{octahedron.d.ts → primitives/octahedron.d.ts}

@@ -1,4 +1,4 @@
-import type { Mesh } from "../core/mesh.js";
+import type { Mesh } from "../../core/mesh.js";
 /**
  * Build a regular octahedron mesh centered on the origin.
  *

package/dist/engines/little-3d-engine/shapes/{pyramid.d.ts → primitives/pyramid.d.ts}

@@ -1,4 +1,4 @@
-import type { Mesh } from "../core/mesh.js";
+import type { Mesh } from "../../core/mesh.js";
 /**
  * Build a square pyramid mesh centered on the origin, base down.
  *

package/dist/engines/little-3d-engine/shapes/primitives/quad.d.ts

@@ -0,0 +1,9 @@
+import type { Mesh } from "../../core/mesh.js";
+/**
+ * Build a flat square in the XY plane, facing +Z, as a single four-vertex
+ * face. Useful as a billboard when kept facing the camera.
+ *
+ * @param size Edge length. Defaults to `1`.
+ * @param colors CSS color for the face. Defaults to a built-in blue.
+ */
+export declare function quad(size?: number, colors?: string[]): Mesh;

package/dist/engines/little-3d-engine/shapes/primitives/quad.js

@@ -0,0 +1,18 @@
+const DEFAULT_COLORS = ["#3b82f6"];
+/**
+ * Build a flat square in the XY plane, facing +Z, as a single four-vertex
+ * face. Useful as a billboard when kept facing the camera.
+ *
+ * @param size Edge length. Defaults to `1`.
+ * @param colors CSS color for the face. Defaults to a built-in blue.
+ */
+export function quad(size = 1, colors = DEFAULT_COLORS) {
+    const s = size / 2;
+    const vertices = [
+        { x: -s, y: -s, z: 0 },
+        { x: s, y: -s, z: 0 },
+        { x: s, y: s, z: 0 },
+        { x: -s, y: s, z: 0 },
+    ];
+    return { vertices, faces: [{ indices: [0, 1, 2, 3], color: colors[0] }] };
+}