@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/libraries/asset-browser/src/software-thumbnails.js

@@ -0,0 +1,940 @@
+// ============================================================================
+// SoftwareThumbnailRenderer — native counterpart to ThumbnailRenderer.
+//
+// The browser path rasterizes turntable thumbnails with a WebGL2
+// OffscreenCanvas in a worker. Native has no WebGL2, so this
+// renderer rasterizes the same models on the CPU: positions + flat normals
+// through a lookAt+perspective transform into a z-buffered Uint8Array, then
+// putImageData into an OffscreenCanvas whose 2D context is the NativeCanvas2D
+// shim. The scene composites it identically: ctx.drawImage(canvasElement).
+//
+// Shading mirrors THUMB_VS/THUMB_FS: two-sided lambert fill + subtle rim.
+//
+// `loadBytes` (optional) replaces fetch() for URI → bytes resolution, e.g.
+// reading absolute filesystem paths through a game's `downdraft` bridge on
+// native.
+// ============================================================================
+import { declaredCompanionUri, defaultCharacterMeshIndices, loadModel, PoseSampler, resolveImportSettings } from "@downdraft/engine/libraries/models";
+import { createLogger } from "@downdraft/engine/util/logger";
+const log = createLogger("info");
+function computeFlatNormals(positions, indices, out) {
+    const normals = out ?? new Float32Array(positions.length);
+    normals.fill(0);
+    for (let i = 0; i < indices.length; i += 3) {
+        const a = indices[i] * 3, b = indices[i + 1] * 3, c = indices[i + 2] * 3;
+        const ux = positions[b] - positions[a];
+        const uy = positions[b + 1] - positions[a + 1];
+        const uz = positions[b + 2] - positions[a + 2];
+        const vx = positions[c] - positions[a];
+        const vy = positions[c + 1] - positions[a + 1];
+        const vz = positions[c + 2] - positions[a + 2];
+        let nx = uy * vz - uz * vy;
+        let ny = uz * vx - ux * vz;
+        let nz = ux * vy - uy * vx;
+        const nl = Math.hypot(nx, ny, nz) || 1;
+        nx /= nl;
+        ny /= nl;
+        nz /= nl;
+        [a, b, c].forEach((j) => {
+            normals[j] += nx;
+            normals[j + 1] += ny;
+            normals[j + 2] += nz;
+        });
+    }
+    for (let i = 0; i < normals.length; i += 3) {
+        const nl = Math.hypot(normals[i], normals[i + 1], normals[i + 2]) || 1;
+        normals[i] /= nl;
+        normals[i + 1] /= nl;
+        normals[i + 2] /= nl;
+    }
+    return normals;
+}
+export class SoftwareThumbnailRenderer {
+    canvas;
+    ctx;
+    size;
+    pixels;
+    depth;
+    loadBytes;
+    resolveTexture;
+    /** LRU cache: contentId → SoftModel. */
+    cache = new Map();
+    loading = new Set();
+    maxCache = 512;
+    // Scratch transform buffers (reused per renderThumb call).
+    sx;
+    sy;
+    sz;
+    snx;
+    sny;
+    snz;
+    constructor(size = 192, opts) {
+        this.size = size;
+        this.canvas = new OffscreenCanvas(size, size);
+        this.ctx = this.canvas.getContext("2d");
+        this.pixels = new Uint8ClampedArray(size * size * 4);
+        this.depth = new Float32Array(size * size);
+        this.loadBytes = opts?.loadBytes ?? (async (uri) => {
+            const resp = await fetch(uri);
+            if (!resp.ok)
+                throw new Error(`HTTP ${resp.status}`);
+            return resp.arrayBuffer();
+        });
+        this.resolveTexture = opts?.resolveTexture ?? null;
+        const INIT_VERTS = 1 << 16;
+        this.sx = new Float32Array(INIT_VERTS);
+        this.sy = new Float32Array(INIT_VERTS);
+        this.sz = new Float32Array(INIT_VERTS);
+        this.snx = new Float32Array(INIT_VERTS);
+        this.sny = new Float32Array(INIT_VERTS);
+        this.snz = new Float32Array(INIT_VERTS);
+    }
+    /** Grow the transform scratch buffers to fit `vcount` vertices. Called once
+     *  per renderThumb — arrays double in place so a single oversized model
+     *  doesn't wedge every subsequent card into the cube fallback. */
+    ensureScratch(vcount) {
+        if (vcount <= this.sx.length)
+            return;
+        let cap = this.sx.length;
+        while (cap < vcount)
+            cap <<= 1;
+        this.sx = new Float32Array(cap);
+        this.sy = new Float32Array(cap);
+        this.sz = new Float32Array(cap);
+        this.snx = new Float32Array(cap);
+        this.sny = new Float32Array(cap);
+        this.snz = new Float32Array(cap);
+    }
+    get canvasElement() { return this.canvas; }
+    has(contentId) {
+        return this.cache.has(contentId) || this.loading.has(contentId);
+    }
+    async loadModelThumb(modelUri, contentId) {
+        if (this.cache.has(contentId) || this.loading.has(contentId))
+            return;
+        this.loading.add(contentId);
+        try {
+            const buffer = await this.loadBytes(modelUri);
+            const filename = modelUri.split("/").pop() ?? "model.glb";
+            // Companion files — .mtl for OBJ (carries material colors + texture
+            // URIs) and .bin for text .gltf. Resolved through the same sibling
+            // mechanism as textures so filesystem-backed libraries work natively.
+            const ext = filename.split(".").pop()?.toLowerCase();
+            let mtl = null, bin = null;
+            if (this.resolveTexture) {
+                const stem = filename.replace(/\.[^.]+$/, "");
+                const declared = declaredCompanionUri(buffer, ext ?? "");
+                if (ext === "obj") {
+                    mtl = (declared ? await this.resolveTexture(modelUri, decodeURIComponent(declared)) : null)
+                        ?? await this.resolveTexture(modelUri, `${stem}.mtl`);
+                }
+                else if (ext === "gltf") {
+                    bin = (declared ? await this.resolveTexture(modelUri, decodeURIComponent(declared)) : null)
+                        ?? await this.resolveTexture(modelUri, `${stem}.bin`);
+                }
+            }
+            const model = await loadModel(buffer, filename, mtl, bin, {
+                // Apply the same sidecar import settings (.ddmeta.json/.meta/.import)
+                // the game's loader uses — thumbnails should match what Load shows.
+                // The resolver's relative URIs route through the sibling-resolution
+                // callback, wrapped in a minimal Response shim.
+                sidecarResolver: this.resolveTexture
+                    ? (_name, md) => resolveImportSettings({
+                        modelPath: filename,
+                        modelData: md,
+                        fetchFn: async (uri) => {
+                            const bytes = await this.resolveTexture(modelUri, decodeURIComponent(uri));
+                            if (!bytes) {
+                                return { ok: false, status: 404, text: async () => "", arrayBuffer: async () => new ArrayBuffer(0) };
+                            }
+                            return {
+                                ok: true, status: 200,
+                                text: async () => new TextDecoder().decode(bytes),
+                                arrayBuffer: async () => bytes,
+                            };
+                        },
+                    })
+                    : undefined,
+            });
+            this.uploadModel(contentId, model, modelUri);
+            // Texture decodes run async — wait for them so the first rendered frame
+            // already has its materials (the worker snapshots PNGs immediately).
+            await this.cache.get(contentId)?.texReady;
+        }
+        catch (err) {
+            log.warn("software-thumbnail-renderer", `Failed to load ${contentId} (${modelUri}): ${err}`);
+            this.loadBuiltinCube(contentId);
+        }
+        finally {
+            this.loading.delete(contentId);
+        }
+    }
+    loadBuiltinCube(contentId) {
+        if (this.cache.has(contentId))
+            return;
+        const positions = new Float32Array([
+            -0.5, -0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, -0.5, 0.5, -0.5,
+            -0.5, -0.5, 0.5, 0.5, -0.5, 0.5, 0.5, 0.5, 0.5, -0.5, 0.5, 0.5,
+        ]);
+        const indices = new Uint16Array([
+            0, 1, 2, 0, 2, 3, 4, 6, 5, 4, 7, 6,
+            0, 3, 7, 0, 7, 4, 1, 5, 6, 1, 6, 2,
+            3, 2, 6, 3, 6, 7, 0, 4, 5, 0, 5, 1,
+        ]);
+        this.uploadGeometry(contentId, positions, indices, { center: [0, 0, 0], radius: Math.sqrt(3) / 2 });
+    }
+    loadBuiltinSphere(contentId) {
+        if (this.cache.has(contentId))
+            return;
+        const lat = 12, lon = 16;
+        const positions = [];
+        const indices = [];
+        for (let i = 0; i <= lat; i++) {
+            const theta = (i / lat) * Math.PI;
+            const st = Math.sin(theta), ct = Math.cos(theta);
+            for (let j = 0; j <= lon; j++) {
+                const phi = (j / lon) * 2 * Math.PI;
+                positions.push(st * Math.cos(phi) * 0.5, ct * 0.5, st * Math.sin(phi) * 0.5);
+            }
+        }
+        for (let i = 0; i < lat; i++) {
+            for (let j = 0; j < lon; j++) {
+                const a = i * (lon + 1) + j, b = a + lon + 1;
+                indices.push(a, b, a + 1, b, b + 1, a + 1);
+            }
+        }
+        this.uploadGeometry(contentId, new Float32Array(positions), new Uint16Array(indices), { center: [0, 0, 0], radius: 0.5 });
+    }
+    /**
+     * Upload an already-parsed model — used when the game's own loader applies
+     * accessory/variant filtering that raw loadModel() skips (unfiltered
+     * player FBXs draw every variant superimposed).
+     */
+    uploadModelData(contentId, model) {
+        this.uploadModel(contentId, model);
+    }
+    uploadModel(contentId, model, modelUri) {
+        // Rigged character packs ship every outfit/body variant as its own mesh
+        // node (ash_torso, ash_torso.001…); drawing all of them superimposes
+        // hundreds of overlapping parts. Keep the first variant per name-prefix
+        // group — the same default outfit the model viewer loads with.
+        const sel = defaultCharacterMeshIndices(model);
+        const meshes = sel ? model.meshes.filter((_, i) => sel.has(i)) : model.meshes;
+        if (!meshes || meshes.length === 0) {
+            // Mesh-less files aren't necessarily empty — animation-only exports
+            // (e.g. Mixamo `Character@Action.fbx`) carry a synthesized skeleton the
+            // loader builds from the node tree. Show the bones, not a cube.
+            if (model.skin && model.skin.bones.length > 0) {
+                this.uploadSkeletonModel(contentId, model);
+                if (!this.cache.get(contentId)?.anim) {
+                    // No usable skeleton after all — fall through to the cube.
+                    this.loadBuiltinCube(contentId);
+                }
+                return;
+            }
+            this.loadBuiltinCube(contentId);
+            return;
+        }
+        let totalVerts = 0, totalIdx = 0;
+        meshes.forEach((m) => { totalVerts += m.vertexCount; totalIdx += m.indexCount; });
+        const positions = new Float32Array(totalVerts * 3);
+        const is32 = totalVerts > 65535;
+        const indices = is32 ? new Uint32Array(totalIdx) : new Uint16Array(totalIdx);
+        const multiMat = (model.materials?.length ?? 0) > 1
+            || meshes.some((m) => (m.materialIndex ?? 0) > 0);
+        const triMat = multiMat ? new Uint16Array(totalIdx / 3) : null;
+        const anyUvs = meshes.some((m) => !!m.uvs);
+        const anyCols = meshes.some((m) => !!m.colors);
+        const anySkin = meshes.some((m) => !!m.joints && !!m.weights);
+        const uvs = anyUvs ? new Float32Array(totalVerts * 2) : null;
+        const vcols = anyCols ? new Float32Array(totalVerts * 3).fill(1) : null;
+        const joints = anySkin ? new Uint32Array(totalVerts * 4) : null;
+        const weights = anySkin ? new Float32Array(totalVerts * 4) : null;
+        let vOff = 0, iOff = 0, vBase = 0;
+        meshes.forEach((m) => {
+            const stride = m.vertices.length / m.vertexCount;
+            for (let v = 0; v < m.vertexCount; v++) {
+                positions[vOff + v * 3] = m.vertices[v * stride];
+                positions[vOff + v * 3 + 1] = m.vertices[v * stride + 1];
+                positions[vOff + v * 3 + 2] = m.vertices[v * stride + 2];
+            }
+            if (uvs) {
+                if (m.uvs)
+                    uvs.set(m.uvs.subarray(0, m.vertexCount * 2), vOff / 3 * 2);
+                // missing uvs leave (0,0) — samples the texture's corner; acceptable
+            }
+            if (vcols && m.colors) {
+                const cstride = m.colors.length / m.vertexCount;
+                for (let v = 0; v < m.vertexCount; v++) {
+                    vcols[vOff + v * 3] = m.colors[v * cstride];
+                    vcols[vOff + v * 3 + 1] = m.colors[v * cstride + 1];
+                    vcols[vOff + v * 3 + 2] = m.colors[v * cstride + 2];
+                }
+            }
+            if (joints && weights) {
+                // Bone indices are into the shared skeleton — no vBase rebase.
+                // Rigid (unskinned) vertices keep all-zero weights → bind pose.
+                if (m.joints && m.weights) {
+                    for (let v = 0; v < m.vertexCount; v++) {
+                        const j4 = v * 4, o4 = vOff / 3 * 4 + j4;
+                        joints[o4] = m.joints[j4];
+                        joints[o4 + 1] = m.joints[j4 + 1];
+                        joints[o4 + 2] = m.joints[j4 + 2];
+                        joints[o4 + 3] = m.joints[j4 + 3];
+                        weights[o4] = m.weights[j4];
+                        weights[o4 + 1] = m.weights[j4 + 1];
+                        weights[o4 + 2] = m.weights[j4 + 2];
+                        weights[o4 + 3] = m.weights[j4 + 3];
+                    }
+                }
+            }
+            vOff += m.vertexCount * 3;
+            const src = m.indices;
+            const mi = m.materialIndex ?? 0;
+            for (let i = 0; i < m.indexCount; i++)
+                indices[iOff + i] = src[i] + vBase;
+            if (triMat)
+                triMat.fill(mi, iOff / 3, (iOff + m.indexCount) / 3);
+            iOff += m.indexCount;
+            vBase += m.vertexCount;
+        });
+        let center = [0, 0, 0];
+        let radius = 0.5;
+        // model.bounds covers every variant — when a part selection trimmed the
+        // mesh list, recompute framing from the merged vertices instead.
+        if (model.bounds && !sel) {
+            const b = model.bounds;
+            center = [(b.min[0] + b.max[0]) / 2, (b.min[1] + b.max[1]) / 2, (b.min[2] + b.max[2]) / 2];
+            radius = Math.max(Math.hypot(b.max[0] - center[0], b.max[1] - center[1], b.max[2] - center[2]), Math.hypot(b.min[0] - center[0], b.min[1] - center[1], b.min[2] - center[2]));
+        }
+        else {
+            let min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+            for (let i = 0; i < positions.length; i += 3) {
+                for (let k = 0; k < 3; k++) {
+                    if (positions[i + k] < min[k])
+                        min[k] = positions[i + k];
+                    if (positions[i + k] > max[k])
+                        max[k] = positions[i + k];
+                }
+            }
+            center = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];
+            radius = Math.max(Math.hypot(max[0] - center[0], max[1] - center[1], max[2] - center[2]), Math.hypot(min[0] - center[0], min[1] - center[1], min[2] - center[2]));
+        }
+        if (radius <= 0)
+            radius = 0.5;
+        // Materials: per-mesh baseColor/emissive + async texture decode.
+        const decodes = [];
+        const mats = (model.materials ?? []).map((mat) => {
+            const sm = {
+                baseColor: [mat.baseColor[0], mat.baseColor[1], mat.baseColor[2]],
+                emissive: mat.emissiveColor ? [...mat.emissiveColor] : [0, 0, 0],
+                tex: null,
+                texPending: !!(mat.textureData || mat.textureUri),
+                texOffset: mat.textureTransform?.offset ?? [0, 0],
+                texScale: mat.textureTransform?.scale ?? [1, 1],
+            };
+            if (sm.texPending) {
+                decodes.push(this.decodeMaterialTexture(mat.textureData, mat.textureUri, modelUri)
+                    .then((tex) => { sm.tex = tex; sm.texPending = false; })
+                    .catch(() => { sm.texPending = false; }));
+            }
+            return sm;
+        });
+        if (mats.length === 0) {
+            mats.push({
+                baseColor: [0.78, 0.82, 0.88], emissive: [0, 0, 0],
+                tex: null, texPending: false, texOffset: [0, 0], texScale: [1, 1],
+            });
+        }
+        const normals = computeFlatNormals(positions, indices);
+        if (this.cache.size >= this.maxCache) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(contentId, {
+            positions, indices, normals, uvs, vcols, triMat, mats,
+            joints, weights, skeletonOnly: false,
+            anim: this.buildAnim(contentId, model),
+            texReady: Promise.all(decodes).then(() => { }),
+            center, radius,
+        });
+    }
+    /**
+     * Animation-only model (no meshes): synthesize a bone-octahedron thumbnail
+     * source. Bounds come from the skeleton's bind world positions; per-frame
+     * geometry is generated by poseSkeleton() during renderThumb.
+     */
+    uploadSkeletonModel(contentId, model) {
+        const anim = this.buildAnim(contentId, model);
+        if (!anim)
+            return; // caller falls back to the cube
+        let center = [0, 0, 0];
+        let radius = 0.5;
+        {
+            // Bind-pose bone world positions define the framing.
+            anim.sampler.sample(null);
+            const T = anim.sampler.normalizationMatrix;
+            const world = anim.sampler.getBoneWorldMatrices();
+            let min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+            for (let i = 0; i < world.length; i++) {
+                const w = world[i];
+                let px = w[12], py = w[13], pz = w[14];
+                if (T) {
+                    const nx = T[0] * px + T[4] * py + T[8] * pz + T[12];
+                    const ny = T[1] * px + T[5] * py + T[9] * pz + T[13];
+                    const nz = T[2] * px + T[6] * py + T[10] * pz + T[14];
+                    px = nx;
+                    py = ny;
+                    pz = nz;
+                }
+                for (let k = 0; k < 3; k++) {
+                    const v = k === 0 ? px : k === 1 ? py : pz;
+                    if (v < min[k])
+                        min[k] = v;
+                    if (v > max[k])
+                        max[k] = v;
+                }
+            }
+            if (min[0] !== Infinity) {
+                center = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];
+                radius = Math.max(Math.hypot(max[0] - center[0], max[1] - center[1], max[2] - center[2]), Math.hypot(min[0] - center[0], min[1] - center[1], min[2] - center[2]), 0.05);
+            }
+        }
+        if (this.cache.size >= this.maxCache) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(contentId, {
+            positions: new Float32Array(0), indices: new Uint16Array(0),
+            normals: new Float32Array(0),
+            uvs: null, vcols: null, triMat: null,
+            mats: [{ baseColor: [0.52, 0.8, 0.97], emissive: [0, 0, 0], tex: null, texPending: false, texOffset: [0, 0], texScale: [1, 1] }],
+            joints: null, weights: null,
+            skeletonOnly: true, anim, texReady: Promise.resolve(), center, radius,
+        });
+    }
+    /**
+     * Build the animation state for a model — a PoseSampler over its skin.
+     * Returns null when the model has no usable skeleton.
+     */
+    buildAnim(contentId, model) {
+        const skin = model.skin;
+        if (!skin || skin.bones.length === 0)
+            return null;
+        try {
+            const sampler = new PoseSampler(skin, model.animations ?? []);
+            const clipIndex = sampler.firstClipIndex();
+            const duration = clipIndex >= 0 ? sampler.clips[clipIndex].duration : 0;
+            return {
+                sampler, clipIndex, duration,
+                // Grown lazily at first posed render.
+                posedPos: new Float32Array(0),
+                posedNrm: new Float32Array(0),
+                skelIndices: null, bonePos: null,
+            };
+        }
+        catch (err) {
+            log.warn("software-thumbnail-renderer", `Pose sampler failed for ${contentId}: ${err}`);
+            return null;
+        }
+    }
+    /** Duration of the model's preview animation in seconds (0 = static).
+     *  Reports 0 when the clip can't affect the rendered geometry — mesh
+     *  models without skinning data render identically at every time. */
+    thumbDuration(contentId) {
+        const m = this.cache.get(contentId);
+        if (!m?.anim)
+            return 0;
+        if (!m.skeletonOnly && (!m.joints || !m.weights))
+            return 0;
+        return m.anim.duration;
+    }
+    /**
+     * CPU linear-blend skinning: posed = Σ wᵢ · (skinMatrix[jᵢ] · bind).
+     * Vertices with all-zero weights (rigid meshes sharing a skinned model)
+     * keep their bind position. Writes anim.posedPos + anim.posedNrm.
+     */
+    skinVertices(m) {
+        const anim = m.anim;
+        const mats = anim.sampler.skinMatrices; // already normalization-conjugated
+        const pos = m.positions;
+        if (anim.posedPos.length < pos.length) {
+            anim.posedPos = new Float32Array(pos.length);
+            anim.posedNrm = new Float32Array(pos.length);
+        }
+        const out = anim.posedPos;
+        const joints = m.joints;
+        const weights = m.weights;
+        const vcount = pos.length / 3;
+        for (let v = 0; v < vcount; v++) {
+            const i3 = v * 3, i4 = v * 4;
+            const x = pos[i3], y = pos[i3 + 1], z = pos[i3 + 2];
+            let ax = 0, ay = 0, az = 0, sum = 0;
+            for (let k = 0; k < 4; k++) {
+                const wk = weights[i4 + k];
+                if (wk <= 0)
+                    continue;
+                const M = joints[i4 + k] * 16;
+                ax += wk * (mats[M] * x + mats[M + 4] * y + mats[M + 8] * z + mats[M + 12]);
+                ay += wk * (mats[M + 1] * x + mats[M + 5] * y + mats[M + 9] * z + mats[M + 13]);
+                az += wk * (mats[M + 2] * x + mats[M + 6] * y + mats[M + 10] * z + mats[M + 14]);
+                sum += wk;
+            }
+            if (sum > 1e-6) {
+                const s = 1 / sum;
+                out[i3] = ax * s;
+                out[i3 + 1] = ay * s;
+                out[i3 + 2] = az * s;
+            }
+            else {
+                out[i3] = x;
+                out[i3 + 1] = y;
+                out[i3 + 2] = z;
+            }
+        }
+        computeFlatNormals(out, m.indices, anim.posedNrm);
+    }
+    /**
+     * Generate bone-octahedron geometry for a skeleton-only model at the pose
+     * currently sampled in m.anim.sampler. Bone world positions (source space)
+     * are mapped through the normalization matrix into vertex space. Each bone
+     * is a tapered 8-triangle octahedron from its parent's joint to its own;
+     * roots and zero-length segments get a small joint marker instead.
+     */
+    poseSkeleton(m) {
+        const anim = m.anim;
+        const sampler = anim.sampler;
+        const bones = sampler.skeleton.data.bones;
+        const world = sampler.getBoneWorldMatrices();
+        const T = sampler.normalizationMatrix;
+        const n = bones.length;
+        if (!anim.bonePos || anim.bonePos.length < n * 3)
+            anim.bonePos = new Float32Array(n * 3);
+        const bp = anim.bonePos;
+        for (let i = 0; i < n; i++) {
+            const w = world[i];
+            let x = w[12], y = w[13], z = w[14];
+            if (T) {
+                const nx = T[0] * x + T[4] * y + T[8] * z + T[12];
+                const ny = T[1] * x + T[5] * y + T[9] * z + T[13];
+                const nz = T[2] * x + T[6] * y + T[10] * z + T[14];
+                x = nx;
+                y = ny;
+                z = nz;
+            }
+            bp[i * 3] = x;
+            bp[i * 3 + 1] = y;
+            bp[i * 3 + 2] = z;
+        }
+        // Topology is constant per skeleton — 6 verts / 8 tris per bone.
+        if (!anim.skelIndices) {
+            const idx = new Uint32Array(n * 24);
+            for (let b = 0; b < n; b++) {
+                const vb = b * 6, ib = b * 24;
+                for (let k = 0; k < 4; k++) {
+                    idx[ib + k * 3] = vb;
+                    idx[ib + k * 3 + 1] = vb + 1 + k;
+                    idx[ib + k * 3 + 2] = vb + 1 + ((k + 1) % 4);
+                    idx[ib + 12 + k * 3] = vb + 5;
+                    idx[ib + 12 + k * 3 + 1] = vb + 1 + ((k + 1) % 4);
+                    idx[ib + 12 + k * 3 + 2] = vb + 1 + k;
+                }
+            }
+            anim.skelIndices = idx;
+        }
+        if (anim.posedPos.length < n * 18) {
+            anim.posedPos = new Float32Array(n * 18);
+            anim.posedNrm = new Float32Array(n * 18);
+        }
+        const posed = anim.posedPos;
+        const dotR = Math.max(0.02 * m.radius, 1e-4);
+        for (let b = 0; b < n; b++) {
+            const vb = b * 18;
+            const hx = bp[b * 3], hy = bp[b * 3 + 1], hz = bp[b * 3 + 2];
+            const p = bones[b].parentIndex;
+            let ux = 0, uy = 1, uz = 0, len = 0, tx = hx, ty = hy, tz = hz;
+            if (p >= 0) {
+                tx = bp[p * 3];
+                ty = bp[p * 3 + 1];
+                tz = bp[p * 3 + 2];
+                ux = hx - tx;
+                uy = hy - ty;
+                uz = hz - tz;
+                len = Math.hypot(ux, uy, uz);
+            }
+            if (p < 0 || len < m.radius * 0.005) {
+                // Root or degenerate segment → small octahedron joint marker.
+                const r = dotR;
+                posed[vb] = hx;
+                posed[vb + 1] = hy - r;
+                posed[vb + 2] = hz;
+                posed[vb + 3] = hx + r;
+                posed[vb + 4] = hy;
+                posed[vb + 5] = hz;
+                posed[vb + 6] = hx;
+                posed[vb + 7] = hy;
+                posed[vb + 8] = hz + r;
+                posed[vb + 9] = hx - r;
+                posed[vb + 10] = hy;
+                posed[vb + 11] = hz;
+                posed[vb + 12] = hx;
+                posed[vb + 13] = hy;
+                posed[vb + 14] = hz - r;
+                posed[vb + 15] = hx;
+                posed[vb + 16] = hy + r;
+                posed[vb + 17] = hz;
+                continue;
+            }
+            ux /= len;
+            uy /= len;
+            uz /= len;
+            // Orthonormal frame around the bone axis: v1 = normalize(u × a) where
+            // a = +Y unless the bone runs near-vertical (then a = +X).
+            let v1x, v1y, v1z;
+            if (Math.abs(uy) < 0.9) {
+                v1x = -uz;
+                v1y = 0;
+                v1z = ux;
+            }
+            else {
+                v1x = 0;
+                v1y = uz;
+                v1z = -uy;
+            }
+            const v1l = Math.hypot(v1x, v1y, v1z) || 1;
+            v1x /= v1l;
+            v1y /= v1l;
+            v1z /= v1l;
+            const v2x = uy * v1z - uz * v1y;
+            const v2y = uz * v1x - ux * v1z;
+            const v2z = ux * v1y - uy * v1x;
+            const r = len * 0.09;
+            const cx = tx + ux * len * 0.18, cy = ty + uy * len * 0.18, cz = tz + uz * len * 0.18;
+            // tail, ring ×4, head
+            posed[vb] = tx;
+            posed[vb + 1] = ty;
+            posed[vb + 2] = tz;
+            posed[vb + 3] = cx + v1x * r;
+            posed[vb + 4] = cy + v1y * r;
+            posed[vb + 5] = cz + v1z * r;
+            posed[vb + 6] = cx + v2x * r;
+            posed[vb + 7] = cy + v2y * r;
+            posed[vb + 8] = cz + v2z * r;
+            posed[vb + 9] = cx - v1x * r;
+            posed[vb + 10] = cy - v1y * r;
+            posed[vb + 11] = cz - v1z * r;
+            posed[vb + 12] = cx - v2x * r;
+            posed[vb + 13] = cy - v2y * r;
+            posed[vb + 14] = cz - v2z * r;
+            posed[vb + 15] = hx;
+            posed[vb + 16] = hy;
+            posed[vb + 17] = hz;
+        }
+        computeFlatNormals(posed, anim.skelIndices, anim.posedNrm);
+        return { pos: posed, nrm: anim.posedNrm, idx: anim.skelIndices };
+    }
+    /** Decode embedded bytes or a resolved external URI into an RGBA tex map.
+     *  Downscales to <=256px — thumbnails sample at 96px, no need for more. */
+    async decodeMaterialTexture(textureData, textureUri, modelUri) {
+        let bytes = textureData ?? null;
+        if (!bytes && textureUri && !textureUri.startsWith("data:") && modelUri && this.resolveTexture) {
+            bytes = await this.resolveTexture(modelUri, decodeURIComponent(textureUri));
+            // Basename fallback — FBX URIs frequently carry stale absolute paths.
+            if (!bytes) {
+                const base = decodeURIComponent(textureUri).split("/").pop() ?? "";
+                if (base)
+                    bytes = await this.resolveTexture(modelUri, base);
+            }
+        }
+        if (!bytes || bytes.byteLength <= 4)
+            return null;
+        try {
+            const bmp = await createImageBitmap(bytes);
+            const anyBmp = bmp;
+            const MAX_TEX = 256;
+            const scale = Math.min(1, MAX_TEX / Math.max(bmp.width, bmp.height));
+            const w = Math.max(1, Math.round(bmp.width * scale));
+            const h = Math.max(1, Math.round(bmp.height * scale));
+            // Native fast path — raw pixels, no canvas readback.
+            if (scale >= 1 && typeof anyBmp.getPixelData === "function") {
+                return { w, h, data: anyBmp.getPixelData() };
+            }
+            const c = new OffscreenCanvas(w, h);
+            const cx = c.getContext("2d");
+            cx.drawImage(bmp, 0, 0, w, h);
+            const id = cx.getImageData(0, 0, w, h);
+            try {
+                bmp.close?.();
+            }
+            catch { }
+            return { w, h, data: id.data };
+        }
+        catch {
+            return null;
+        }
+    }
+    uploadGeometry(contentId, positions, indices, bounds, baseColor = [0.78, 0.82, 0.88]) {
+        const normals = computeFlatNormals(positions, indices);
+        if (this.cache.size >= this.maxCache) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(contentId, {
+            positions, indices, normals,
+            uvs: null, vcols: null, triMat: null,
+            mats: [{
+                    baseColor, emissive: [0, 0, 0], tex: null, texPending: false,
+                    texOffset: [0, 0], texScale: [1, 1],
+                }],
+            joints: null, weights: null, skeletonOnly: false, anim: null,
+            texReady: Promise.resolve(),
+            center: bounds.center, radius: bounds.radius,
+        });
+    }
+    /**
+     * Rasterize one turntable frame for contentId into the canvas.
+     * `time` (seconds) samples the model's first embedded clip — skinned meshes
+     * are CPU-skinned per frame and skeleton-only models (animation-only files)
+     * draw their bones. Omit it for a static bind-pose frame.
+     * Returns false when the model isn't loaded yet.
+     */
+    renderThumb(contentId, angle, time) {
+        const m = this.cache.get(contentId);
+        if (!m)
+            return false;
+        const size = this.size;
+        const px = this.pixels;
+        const depth = this.depth;
+        // Pick the geometry to draw: bind-pose mesh, CPU-skinned mesh at `time`,
+        // or generated bone octahedra for skeleton-only models.
+        let positions = m.positions;
+        let normals = m.normals;
+        let indices = m.indices;
+        let uvs = m.uvs, vcols = m.vcols, triMat = m.triMat;
+        if (m.anim) {
+            if (m.skeletonOnly) {
+                // Bones are the content — pose even for a static frame.
+                m.anim.sampler.sample(m.anim.clipIndex >= 0 ? m.anim.clipIndex : null, time ?? 0);
+                const g = this.poseSkeleton(m);
+                positions = g.pos;
+                normals = g.nrm;
+                indices = g.idx;
+                uvs = null;
+                vcols = null;
+                triMat = null;
+            }
+            else if (time !== undefined && m.joints && m.weights && m.anim.clipIndex >= 0) {
+                m.anim.sampler.sample(m.anim.clipIndex, time);
+                this.skinVertices(m);
+                positions = m.anim.posedPos;
+                normals = m.anim.posedNrm;
+            }
+        }
+        // Clear to the same bg the WebGL version uses: rgba(0.16, 0.17, 0.22, 1).
+        for (let i = 0; i < px.length; i += 4) {
+            px[i] = 41;
+            px[i + 1] = 43;
+            px[i + 2] = 56;
+            px[i + 3] = 255;
+        }
+        depth.fill(Infinity);
+        // Camera: fixed position looking at the model center (matches renderThumb).
+        const radius = Math.max(m.radius, 0.1);
+        const dist = radius * 3.0;
+        const ex = m.center[0];
+        const ey = m.center[1] + m.radius * 0.4;
+        const ez = m.center[2] + dist;
+        const near = dist * 0.01;
+        const far = dist * 10;
+        // View basis (lookAt: eye→center, up +Y)
+        let zx = ex - m.center[0], zy = ey - m.center[1], zz = ez - m.center[2];
+        let zl = Math.hypot(zx, zy, zz) || 1;
+        zx /= zl;
+        zy /= zl;
+        zz /= zl;
+        // x = normalize(up × z) = normalize(zz, 0, -zx); y = z × x
+        let xx = zz, xy = 0, xz = -zx;
+        const xl = Math.hypot(xx, xy, xz) || 1;
+        xx /= xl;
+        xy /= xl;
+        xz /= xl;
+        const yx = zy * xz - zz * xy, yy = zz * xx - zx * xz, yz = zx * xy - zy * xx;
+        const f = 1 / Math.tan((45 * Math.PI / 180) / 2);
+        const nf = 1 / (near - far);
+        const rotC = Math.cos(angle), rotS = Math.sin(angle);
+        const vcount = positions.length / 3;
+        this.ensureScratch(vcount);
+        const sx = this.sx, sy = this.sy, sz = this.sz;
+        const snx = this.snx, sny = this.sny, snz = this.snz;
+        const cx = m.center[0], cy = m.center[1], cz = m.center[2];
+        for (let v = 0; v < vcount; v++) {
+            const i3 = v * 3;
+            // model = rotY(angle): rotate around the model's bounding-sphere center
+            // so off-center models still rotate in place.
+            const lx = positions[i3] - cx, ly = positions[i3 + 1] - cy, lz = positions[i3 + 2] - cz;
+            const mx = rotC * lx - rotS * lz + cx;
+            const my = ly + cy;
+            const mz = rotS * lx + rotC * lz + cz;
+            // view = lookAt(eye, center): v' = (x·(p-e), y·(p-e), z·(p-e))
+            const dx = mx - ex, dy = my - ey, dz = mz - ez;
+            const vx = xx * dx + xy * dy + xz * dz;
+            const vy = yx * dx + yy * dy + yz * dz;
+            const vz = zx * dx + zy * dy + zz * dz; // negative in front of camera
+            // perspective projection → NDC → screen
+            const w = -vz;
+            if (w > 0.0001) {
+                const ndcX = (f * vx) / w; // aspect = 1
+                const ndcY = (f * vy) / w;
+                const ndcZ = ((far + near) * nf * vz + 2 * far * near * nf) / w;
+                sx[v] = (ndcX * 0.5 + 0.5) * size;
+                sy[v] = (0.5 - ndcY * 0.5) * size; // NDC y-up → screen y-down
+                sz[v] = ndcZ;
+            }
+            else {
+                sx[v] = NaN; // clipped — any tri touching this vertex is skipped
+            }
+            // rotate the normal by the model rotation (view-space lighting isn't
+            // needed — the shader lights in model space relative to camera fwd).
+            const nx = normals[i3], ny = normals[i3 + 1], nz = normals[i3 + 2];
+            snx[v] = rotC * nx - rotS * nz;
+            sny[v] = ny;
+            snz[v] = rotS * nx + rotC * nz;
+        }
+        // Lighting: hemisphere ambient (brighter from above) + key + weak fill.
+        // Per-pixel interpolated normals → smooth shading instead of flat facets.
+        const kl = Math.hypot(0.55, 0.75, 0.65);
+        const Kx = 0.55 / kl, Ky = 0.75 / kl, Kz = 0.65 / kl;
+        const fl2 = Math.hypot(-0.5, 0.1, 0.55);
+        const Fx = -0.5 / fl2, Fy = 0.1 / fl2, Fz = 0.55 / fl2;
+        const mats = m.mats;
+        for (let t = 0; t < indices.length; t += 3) {
+            const a = indices[t], b = indices[t + 1], c = indices[t + 2];
+            const ax = sx[a], ay = sy[a], az = sz[a];
+            const bx = sx[b], by = sy[b], bz = sz[b];
+            const cx2 = sx[c], cy2 = sy[c], cz2 = sz[c];
+            if (Number.isNaN(ax) || Number.isNaN(bx) || Number.isNaN(cx2))
+                continue;
+            // Depth clip: WebGL clips at ndc z in [-1,1]; approximate by dropping
+            // tris entirely behind the near plane.
+            if (az < -1 && bz < -1 && cz2 < -1)
+                continue;
+            if (az > 1 && bz > 1 && cz2 > 1)
+                continue;
+            // Two-sided: flip shading normal by screen-space winding (same signal
+            // the GLSL uses via gl_FrontFacing). Screen y is flipped vs NDC, so a
+            // front-facing (CCW in NDC) tri has negative signed area here — keep
+            // its authored normal; only back faces get flipped toward the camera.
+            const winding = (bx - ax) * (cy2 - ay) - (cx2 - ax) * (by - ay);
+            const nSign = winding < 0 ? 1 : -1;
+            const mat = mats[triMat ? triMat[t / 3] : 0] ?? mats[0];
+            const br = mat.baseColor[0], bg = mat.baseColor[1], bb = mat.baseColor[2];
+            const er = mat.emissive[0], eg = mat.emissive[1], eb = mat.emissive[2];
+            const tex = mat.tex;
+            const to0 = mat.texOffset[0], to1 = mat.texOffset[1];
+            const ts0 = mat.texScale[0], ts1 = mat.texScale[1];
+            const useTex = !!(tex && uvs);
+            // Per-vertex shading inputs.
+            const nax = snx[a] * nSign, nay = sny[a] * nSign, naz = snz[a] * nSign;
+            const nbx = snx[b] * nSign, nby = sny[b] * nSign, nbz = snz[b] * nSign;
+            const ncx = snx[c] * nSign, ncy = sny[c] * nSign, ncz = snz[c] * nSign;
+            const ua = uvs ? uvs[a * 2] * ts0 + to0 : 0, va = uvs ? uvs[a * 2 + 1] * ts1 + to1 : 0;
+            const ub = uvs ? uvs[b * 2] * ts0 + to0 : 0, vb = uvs ? uvs[b * 2 + 1] * ts1 + to1 : 0;
+            const uc = uvs ? uvs[c * 2] * ts0 + to0 : 0, vc = uvs ? uvs[c * 2 + 1] * ts1 + to1 : 0;
+            const cra = vcols ? vcols[a * 3] : 1, cga = vcols ? vcols[a * 3 + 1] : 1, cba = vcols ? vcols[a * 3 + 2] : 1;
+            const crb = vcols ? vcols[b * 3] : 1, cgb = vcols ? vcols[b * 3 + 1] : 1, cbb = vcols ? vcols[b * 3 + 2] : 1;
+            const crc = vcols ? vcols[c * 3] : 1, cgc = vcols ? vcols[c * 3 + 1] : 1, cbc = vcols ? vcols[c * 3 + 2] : 1;
+            const tw = tex?.w ?? 0, th = tex?.h ?? 0, td = tex?.data;
+            // Rasterize: bounding box + edge functions, z-interpolated.
+            const minX = Math.max(0, Math.floor(Math.min(ax, bx, cx2)));
+            const maxX = Math.min(size - 1, Math.ceil(Math.max(ax, bx, cx2)));
+            const minY = Math.max(0, Math.floor(Math.min(ay, by, cy2)));
+            const maxY = Math.min(size - 1, Math.ceil(Math.max(ay, by, cy2)));
+            const area = (bx - ax) * (cy2 - ay) - (cx2 - ax) * (by - ay);
+            if (area === 0)
+                continue;
+            const invArea = 1 / area;
+            for (let y = minY; y <= maxY; y++) {
+                const py = y + 0.5;
+                for (let x = minX; x <= maxX; x++) {
+                    const pxx = x + 0.5;
+                    const w0 = ((bx - pxx) * (cy2 - py) - (cx2 - pxx) * (by - py)) * invArea;
+                    const w1 = ((cx2 - pxx) * (ay - py) - (ax - pxx) * (cy2 - py)) * invArea;
+                    const w2 = 1 - w0 - w1;
+                    if (w0 < 0 || w1 < 0 || w2 < 0)
+                        continue;
+                    const z = w0 * az + w1 * bz + w2 * cz2;
+                    const di = y * size + x;
+                    if (z >= depth[di])
+                        continue;
+                    depth[di] = z;
+                    // Interpolated normal → per-pixel lighting.
+                    let nx = w0 * nax + w1 * nbx + w2 * ncx;
+                    let ny = w0 * nay + w1 * nby + w2 * ncy;
+                    let nz = w0 * naz + w1 * nbz + w2 * ncz;
+                    const nl = Math.hypot(nx, ny, nz) || 1;
+                    nx /= nl;
+                    ny /= nl;
+                    nz /= nl;
+                    const key = nx * Kx + ny * Ky + nz * Kz;
+                    const fill = nx * Fx + ny * Fy + nz * Fz;
+                    const hemi = ny * 0.5 + 0.5;
+                    const light = 0.30 + 0.30 * hemi + (key > 0 ? key * 0.62 : 0) + (fill > 0 ? fill * 0.16 : 0);
+                    // Albedo: material baseColor × vertex color × texture.
+                    let ar = br, ag = bg, ab = bb;
+                    if (vcols) {
+                        ar *= w0 * cra + w1 * crb + w2 * crc;
+                        ag *= w0 * cga + w1 * cgb + w2 * cgc;
+                        ab *= w0 * cba + w1 * cbb + w2 * cbc;
+                    }
+                    if (useTex && td) {
+                        let u = w0 * ua + w1 * ub + w2 * uc;
+                        let v = w0 * va + w1 * vb + w2 * vc;
+                        u -= Math.floor(u);
+                        v -= Math.floor(v);
+                        // Bilinear sample.
+                        const fu = u * tw - 0.5, fv = v * th - 0.5;
+                        let x0 = Math.floor(fu), y0 = Math.floor(fv);
+                        const fx = fu - x0, fy = fv - y0;
+                        x0 = ((x0 % tw) + tw) % tw;
+                        y0 = ((y0 % th) + th) % th;
+                        const x1 = (x0 + 1) % tw, y1 = (y0 + 1) % th;
+                        const p00 = (y0 * tw + x0) * 4, p10 = (y0 * tw + x1) * 4;
+                        const p01 = (y1 * tw + x0) * 4, p11 = (y1 * tw + x1) * 4;
+                        const wA = (1 - fx) * (1 - fy), wB = fx * (1 - fy);
+                        const wC = (1 - fx) * fy, wD = fx * fy;
+                        const inv255 = 1 / 255;
+                        ar *= (td[p00] * wA + td[p10] * wB + td[p01] * wC + td[p11] * wD) * inv255;
+                        ag *= (td[p00 + 1] * wA + td[p10 + 1] * wB + td[p01 + 1] * wC + td[p11 + 1] * wD) * inv255;
+                        ab *= (td[p00 + 2] * wA + td[p10 + 2] * wB + td[p01 + 2] * wC + td[p11 + 2] * wD) * inv255;
+                    }
+                    const ndz = nz > 0 ? nz : 0;
+                    const rimT = 1 - ndz;
+                    const rim = rimT * rimT * 0.10;
+                    const pi = di * 4;
+                    px[pi] = Math.min(255, (ar * light + er + rim) * 255) | 0;
+                    px[pi + 1] = Math.min(255, (ag * light + eg + rim) * 255) | 0;
+                    px[pi + 2] = Math.min(255, (ab * light + eb + rim) * 255) | 0;
+                    px[pi + 3] = 255;
+                }
+            }
+        }
+        this.ctx.putImageData({ data: this.pixels, width: this.size, height: this.size }, 0, 0);
+        return true;
+    }
+    renderPlaceholder() {
+        for (let i = 0; i < this.pixels.length; i += 4) {
+            this.pixels[i] = 41;
+            this.pixels[i + 1] = 43;
+            this.pixels[i + 2] = 56;
+            this.pixels[i + 3] = 255;
+        }
+        this.ctx.putImageData({ data: this.pixels, width: this.size, height: this.size }, 0, 0);
+    }
+    dispose() {
+        this.cache.clear();
+        this.loading.clear();
+    }
+}