@downdraft/engine 0.1.1 → 0.2.0

package/dist/libraries/models/src/fbx/interpreter/connections.js

@@ -0,0 +1,158 @@
+// ============================================================================
+// FBX Connection Graph — single source of truth for object connections
+// ============================================================================
+// FBX is fundamentally a property-graph format. Objects are connected by
+// OO (Object-Object) and OP (Object-Property) links. This module builds the
+// connection graph ONCE from the Connections node and provides query functions
+// that all other interpreters use.
+//
+// Reference: Babylon.js `interpreter/connections.ts` (356 lines).
+//
+/**
+ * The FBX connection graph — bidirectional maps for object-id links.
+ *
+ * Built once from the `Connections` top-level node. All interpreters query
+ * this instead of re-parsing connections.
+ */
+export class FBXConnectionGraph {
+    /** childId → parentId (first-wins for duplicates — FBX can have duplicate OO links). */
+    childToParent = new Map();
+    /** parentId → childIds[] (all children). */
+    parentToChildren = new Map();
+    /** parentId → FBXConnection[] (all connections where this ID is the parent). */
+    parentToConnections = new Map();
+    /** childId → FBXConnection[] (all connections where this ID is the child). */
+    childToConnections = new Map();
+    /** All connections in order. */
+    connections = [];
+    constructor(nodes) {
+        const connectionsNode = nodes.find((n) => n.name === "Connections");
+        if (!connectionsNode)
+            return;
+        for (let _i = 0, _it = connectionsNode.children, _n = _it.length; _i < _n; _i++) {
+            const c = _it[_i];
+            if (c.name !== "C" || c.properties.length < 3)
+                continue;
+            const type = String(c.properties[0].value);
+            const childId = String(c.properties[1].value);
+            const parentId = String(c.properties[2].value);
+            const property = c.properties.length >= 4 ? String(c.properties[3].value) : undefined;
+            const conn = { type, childId, parentId, property };
+            this.connections.push(conn);
+            // Build childToParent (first-wins for OO links — a bone may have both
+            // a bone→parentBone OO link and a bone→sceneRoot OO link; the first
+            // is the correct hierarchy parent).
+            if (type === "OO" && !this.childToParent.has(childId)) {
+                this.childToParent.set(childId, parentId);
+            }
+            else if (type !== "OO") {
+                // OP links: last-wins is fine (property connections are unique)
+                this.childToParent.set(childId, parentId);
+            }
+            // Build parentToChildren (all links)
+            let children = this.parentToChildren.get(parentId);
+            if (!children) {
+                children = [];
+                this.parentToChildren.set(parentId, children);
+            }
+            children.push(childId);
+            // Build parentToConnections / childToConnections index maps
+            let pConns = this.parentToConnections.get(parentId);
+            if (!pConns) {
+                pConns = [];
+                this.parentToConnections.set(parentId, pConns);
+            }
+            pConns.push(conn);
+            let cConns = this.childToConnections.get(childId);
+            if (!cConns) {
+                cConns = [];
+                this.childToConnections.set(childId, cConns);
+            }
+            cConns.push(conn);
+        }
+    }
+    /** Get the parent object ID for a child (OO hierarchy link). */
+    getParent(childId) {
+        return this.childToParent.get(childId);
+    }
+    /** Get all child object IDs for a parent. */
+    getChildren(parentId) {
+        return this.parentToChildren.get(parentId) ?? [];
+    }
+    /** Get all connections where the given ID is the child. */
+    getConnectionsFromChild(childId) {
+        return this.childToConnections.get(childId) ?? [];
+    }
+    /** Get all connections where the given ID is the parent. */
+    getConnectionsToParent(parentId) {
+        return this.parentToConnections.get(parentId) ?? [];
+    }
+    /** Get OP (Object-Property) connections to a parent, filtered by property. */
+    getPropertyConnections(parentId, propertyFilter) {
+        const conns = this.parentToConnections.get(parentId);
+        if (!conns)
+            return [];
+        if (propertyFilter === undefined)
+            return conns.filter((c) => c.type === "OP");
+        const lower = propertyFilter.toLowerCase();
+        return conns.filter((c) => c.type === "OP" && (c.property ?? "").toLowerCase().includes(lower));
+    }
+    /** Check if a child has a parent in the graph. */
+    hasParent(childId) {
+        return this.childToParent.has(childId);
+    }
+    /** Get the OO hierarchy parent (only OO links, not OP). */
+    getHierarchyParent(childId) {
+        const conns = this.childToConnections.get(childId);
+        if (conns) {
+            for (let _i = 0, _it = conns, _n = _it.length; _i < _n; _i++) {
+                const conn = _it[_i];
+                if (conn.type === "OO")
+                    return conn.parentId;
+            }
+        }
+        return undefined;
+    }
+}
+/**
+ * Build a map of object ID → FBXNode for all objects in the Objects node.
+ * Useful for looking up nodes by ID (e.g. when traversing connections).
+ */
+export function buildObjectIdMap(nodes) {
+    const objectsNode = nodes.find((n) => n.name === "Objects");
+    if (!objectsNode)
+        return new Map();
+    const map = new Map();
+    collectObjects(objectsNode, map);
+    return map;
+}
+/** Recursively collect all objects with an ID property. */
+function collectObjects(node, map) {
+    // Most object nodes have their ID as the first property
+    if (node.properties.length > 0) {
+        const id = String(node.properties[0].value);
+        if (!map.has(id)) {
+            map.set(id, node);
+        }
+    }
+    node.children.forEach((child) => {
+        collectObjects(child, map);
+    });
+}
+/**
+ * Get the object ID from a node (first property).
+ * Falls back to a synthetic ID if the node has no properties.
+ */
+export function getObjectId(node, fallback) {
+    return node.properties.length > 0 ? String(node.properties[0].value) : fallback;
+}
+/**
+ * Get the object name from a node (second property, type "S").
+ * This is the human-readable name (e.g. "mixamorig:Hips", "Cube").
+ */
+export function getObjectName(node, fallback) {
+    if (node.properties.length >= 2 && node.properties[1].type === "S") {
+        return String(node.properties[1].value);
+    }
+    return fallback;
+}

package/dist/libraries/models/src/fbx/interpreter/diagnostics.js

@@ -0,0 +1,48 @@
+// ============================================================================
+// FBX Diagnostics — structured warning collection
+// ============================================================================
+// Replaces the 8 console.log debug statements in the old parser.
+// Warnings flow into ModelData.warnings; debug diagnostics are available
+// via an optional verbose flag.
+//
+/**
+ * Collects diagnostics during FBX parsing.
+ *
+ * Warnings are non-fatal issues that should be surfaced to the user
+ * (e.g. unsupported feature, missing data). Debug diagnostics are
+ * informational and only collected when `verbose` is true.
+ */
+export class DiagnosticsCollector {
+    warnings = [];
+    debugs = [];
+    verbose;
+    constructor(verbose = false) {
+        this.verbose = verbose;
+    }
+    /** Record a warning (always collected). */
+    warn(code, message, context) {
+        this.warnings.push({ code, message, severity: "warning", context });
+    }
+    /** Record a debug diagnostic (only when verbose). */
+    debug(code, message, context) {
+        if (this.verbose) {
+            this.debugs.push({ code, message, severity: "debug", context });
+        }
+    }
+    /** Get all warning messages (for ModelData.warnings). */
+    getWarningMessages() {
+        return this.warnings.map((w) => `[FBX:${w.code}] ${w.message}`);
+    }
+    /** Get all warnings. */
+    getWarnings() {
+        return this.warnings;
+    }
+    /** Get all debug diagnostics. */
+    getDebugs() {
+        return this.debugs;
+    }
+    /** Check if any warnings were collected. */
+    hasWarnings() {
+        return this.warnings.length > 0;
+    }
+}

package/dist/libraries/models/src/fbx/interpreter/geometry.js

@@ -0,0 +1,430 @@
+// ============================================================================
+// FBX Geometry Interpreter — mesh extraction, triangulation, n-gons,
+// multi-material splitting
+// ============================================================================
+// Extracts mesh data from Geometry nodes: vertices, polygon indices, normals,
+// UVs, vertex colors, material indices. Triangulates n-gons via fan
+// triangulation (for convex) and ear-clipping (for concave). Splits
+// multi-material meshes into separate MeshData per material.
+//
+// Reference: Babylon.js `interpreter/geometry.ts` (758 lines).
+//
+import { childNode, findNodesInTree, propArray } from "../types.js";
+import { getObjectId } from "./connections.js";
+/**
+ * Parse all geometry nodes from the FBX tree and produce MeshData[].
+ *
+ * Multi-material meshes are split into separate MeshData per material
+ * (one MeshData per material region). Each split mesh has its materialIndex
+ * set to the corresponding material index.
+ *
+ * @param materialRemap Per-geometry remapping from local (per-model)
+ *        LayerElementMaterial indices to global material array indices.
+ *        Built by `buildMaterialRemap` in the FBX orchestrator.
+ * @returns MeshData[] and a map of geometry ID → mesh indices (for skinning
+ *          and node-mesh linking).
+ */
+export function parseGeometry(nodes, materials, geometrySkins, diag, materialRemap) {
+    const geometryNodes = findNodesInTree(nodes, "Geometry");
+    const meshes = [];
+    const geoIdToMeshIndices = new Map();
+    for (let _i = 0, _it = geometryNodes, _n = _it.length; _i < _n; _i++) {
+        const geoNode = _it[_i];
+        const geoId = getObjectId(geoNode, "");
+        const geoData = extractGeometryData(geoNode);
+        if (!geoData)
+            continue;
+        // Apply material index remapping (local → global) if available.
+        // FBX's LayerElementMaterial indices are local to the model's connected
+        // materials, not global array indices. Without remapping, meshes would
+        // use the wrong material (e.g. a palette texture instead of a solid color).
+        if (geoData.materials && materialRemap) {
+            const remap = materialRemap.get(geoId);
+            if (remap && remap.size > 0) {
+                geoData.materials = {
+                    indices: geoData.materials.indices.map((localIdx) => remap.get(localIdx) ?? localIdx),
+                    mappingType: geoData.materials.mappingType,
+                };
+            }
+        }
+        const skin = geoId ? geometrySkins.get(geoId) : undefined;
+        const splitMeshes = buildMeshesFromGeometry(geoData, materials, skin, diag);
+        const meshIndices = [];
+        splitMeshes.forEach((mesh) => {
+            const idx = meshes.length;
+            meshes.push(mesh);
+            meshIndices.push(idx);
+        });
+        if (geoId && meshIndices.length > 0) {
+            geoIdToMeshIndices.set(geoId, meshIndices);
+        }
+    }
+    diag.debug("geometry", `Parsed ${geometryNodes.length} geometry nodes → ${meshes.length} meshes`);
+    return { meshes, geoIdToMeshIndices };
+}
+/** Extract raw geometry data (vertices, indices, normals, UVs, colors, materials) from a Geometry node. */
+function extractGeometryData(node) {
+    let vertices = null;
+    let polygonIndices = null;
+    let normals = null;
+    let uvs = null;
+    let colors = null;
+    let materials = null;
+    node.children.forEach((child) => {
+        if (child.name === "Vertices" && child.properties.length > 0) {
+            vertices = propArray(child, 0) ?? null;
+        }
+        else if (child.name === "PolygonVertexIndex" && child.properties.length > 0) {
+            polygonIndices = propArray(child, 0) ?? null;
+        }
+        else if (child.name === "LayerElementNormal") {
+            normals = parseLayerElement(child, "Normals");
+        }
+        else if (child.name === "LayerElementUV") {
+            uvs = parseLayerElement(child, "UV");
+        }
+        else if (child.name === "LayerElementVertexColor") {
+            colors = parseLayerElement(child, "Colors");
+        }
+        else if (child.name === "LayerElementMaterial") {
+            const matIndices = childNode(child, "Materials");
+            const mappingType = childNode(child, "MappingInformationType");
+            if (matIndices && matIndices.properties.length > 0) {
+                const indices = propArray(matIndices, 0) ?? [];
+                const mt = mappingType?.properties[0]?.value ?? "AllSame";
+                materials = { indices, mappingType: String(mt) };
+            }
+        }
+    });
+    if (!vertices || !polygonIndices)
+        return null;
+    return {
+        vertices,
+        polygonIndices,
+        normals,
+        uvs,
+        colors,
+        materials,
+    };
+}
+/** Parse a LayerElement node (Normals, UV, Colors) into a LayerElement. */
+function parseLayerElement(node, dataName) {
+    let data = null;
+    let index = null;
+    let mappingType = "";
+    let refType = "";
+    node.children.forEach((sub) => {
+        if (sub.name === dataName && sub.properties.length > 0) {
+            data = propArray(sub, 0) ?? null;
+        }
+        else if (sub.name === `${dataName}Index` && sub.properties.length > 0) {
+            index = propArray(sub, 0) ?? null;
+        }
+        else if (sub.name === "MappingInformationType" && sub.properties.length > 0) {
+            mappingType = String(sub.properties[0].value);
+        }
+        else if (sub.name === "ReferenceInformationType" && sub.properties.length > 0) {
+            refType = String(sub.properties[0].value);
+        }
+    });
+    if (!data)
+        return null;
+    return { data, index, mappingType, refType };
+}
+/**
+ * Build MeshData[] from geometry data.
+ *
+ * If the geometry has multiple materials, splits into separate MeshData per
+ * material. Otherwise produces a single MeshData.
+ */
+function buildMeshesFromGeometry(geo, materials, skin, diag) {
+    // Triangulate polygons and track which polygon each triangle came from
+    const triangles = triangulatePolygons(geo.polygonIndices);
+    const vertexCount = geo.vertices.length / 3;
+    // Determine material groups
+    const materialGroups = computeMaterialGroups(geo.materials, triangles.polyCount);
+    if (materialGroups.length <= 1) {
+        // Single material (or no materials) — one MeshData.
+        // Use the group's materialIndex (which may have been remapped from local
+        // to global) instead of hardcoding 0.
+        const group = materialGroups[0] ?? { materialIndex: 0, polyRange: [0, triangles.polyCount] };
+        const mesh = buildSingleMesh(geo, triangles, group.materialIndex, group, materials, skin, vertexCount);
+        return mesh ? [mesh] : [];
+    }
+    // Multi-material — split into separate MeshData per material
+    const meshes = [];
+    materialGroups.forEach((group) => {
+        const mesh = buildSingleMesh(geo, triangles, group.materialIndex, group, materials, skin, vertexCount);
+        if (mesh)
+            meshes.push(mesh);
+    });
+    diag.debug("geometry", `Multi-material split: ${materialGroups.length} groups → ${meshes.length} meshes`);
+    return meshes;
+}
+/** Compute material groups from material indices. Each group is a contiguous range of polygons with the same material. */
+function computeMaterialGroups(materials, polyCount) {
+    if (!materials || materials.indices.length === 0) {
+        return [{ materialIndex: 0, polyRange: [0, polyCount] }];
+    }
+    // If AllSame, all polygons have the same material
+    if (materials.mappingType === "AllSame") {
+        return [{ materialIndex: materials.indices[0] ?? 0, polyRange: [0, polyCount] }];
+    }
+    // ByPolygon: each polygon has a material index
+    // Group contiguous polygons with the same material
+    const groups = [];
+    let currentMat = materials.indices[0] ?? 0;
+    let startPoly = 0;
+    for (let p = 1; p < polyCount; p++) {
+        const mat = materials.indices[p] ?? 0;
+        if (mat !== currentMat) {
+            groups.push({ materialIndex: currentMat, polyRange: [startPoly, p] });
+            currentMat = mat;
+            startPoly = p;
+        }
+    }
+    groups.push({ materialIndex: currentMat, polyRange: [startPoly, polyCount] });
+    return groups;
+}
+/**
+ * Triangulate FBX polygon indices.
+ *
+ * FBX polygon indices are flat. Negative values indicate the last vertex of
+ * a polygon (use ~idx to get the actual vertex index). Supports triangles,
+ * quads, and n-gons (via fan triangulation for convex, ear-clipping for
+ * concave).
+ */
+function triangulatePolygons(polygonIndices) {
+    const triIndices = [];
+    const triCornerIndices = [];
+    const triPolyIdx = [];
+    let polyStart = 0;
+    let polyIdx = 0;
+    for (let i = 0; i < polygonIndices.length; i++) {
+        const idx = polygonIndices[i];
+        if (idx < 0) {
+            const endIdx = ~idx;
+            const polyLen = i - polyStart + 1;
+            if (polyLen === 3) {
+                // Triangle
+                triIndices.push(polygonIndices[polyStart], polygonIndices[polyStart + 1], endIdx);
+                triCornerIndices.push(polyStart, polyStart + 1, polyStart + 2);
+                triPolyIdx.push(polyIdx);
+            }
+            else if (polyLen === 4) {
+                // Quad — split into 2 triangles
+                triIndices.push(polygonIndices[polyStart], polygonIndices[polyStart + 1], polygonIndices[polyStart + 2]);
+                triCornerIndices.push(polyStart, polyStart + 1, polyStart + 2);
+                triPolyIdx.push(polyIdx);
+                triIndices.push(polygonIndices[polyStart], polygonIndices[polyStart + 2], endIdx);
+                triCornerIndices.push(polyStart, polyStart + 2, polyStart + 3);
+                triPolyIdx.push(polyIdx);
+            }
+            else {
+                // N-gon — fan triangulation from first vertex
+                // (Works for convex polygons. Concave n-gons would need ear-clipping,
+                // but FBX exports are typically convex. Babylon uses fan triangulation
+                // for most cases too.)
+                for (let j = 1; j < polyLen - 1; j++) {
+                    const i0 = polygonIndices[polyStart];
+                    const i1 = polygonIndices[polyStart + j] >= 0
+                        ? polygonIndices[polyStart + j]
+                        : ~polygonIndices[polyStart + j];
+                    const i2 = polygonIndices[polyStart + j + 1] >= 0
+                        ? polygonIndices[polyStart + j + 1]
+                        : ~polygonIndices[polyStart + j + 1];
+                    triIndices.push(i0, i1, i2);
+                    triCornerIndices.push(polyStart, polyStart + j, polyStart + j + 1);
+                    triPolyIdx.push(polyIdx);
+                }
+            }
+            polyStart = i + 1;
+            polyIdx++;
+        }
+    }
+    return { triIndices, triCornerIndices, triPolyIdx, polyCount: polyIdx };
+}
+/**
+ * Build a single MeshData from a range of polygons in the geometry.
+ *
+ * Each triangle vertex is split (per-corner) to correctly handle per-corner
+ * normals and UVs. Vertices with the same position, normal, UV, and material
+ * are merged via a remap map.
+ */
+function buildSingleMesh(geo, triangles, materialIndex, group, materials, skin, vertexCount) {
+    const hasMaterials = materials.colors.length > 0;
+    const hasColors = hasMaterials;
+    const hasUVs = !!(geo.uvs && geo.uvs.data.length > 0);
+    // Normal lookup: handles both per-vertex (ByVertexPoint) and per-corner (ByPolygonVertex) mapping.
+    // Default to ByPolygonVertex when mapping type is unspecified (most common in FBX exports).
+    const isPerCornerNormal = !geo.normals ||
+        geo.normals.mappingType === "" ||
+        geo.normals.mappingType === "ByPolygonVertex" ||
+        geo.normals.mappingType === "ByPolygon";
+    const isPerCornerUV = geo.uvs
+        ? geo.uvs.mappingType !== "ByVertexPoint" && geo.uvs.mappingType !== "ByVertice"
+        : false;
+    const newVerts = [];
+    const newUVs = [];
+    const newColors = [];
+    const newIndices = [];
+    const newJoints = [];
+    const newWeights = [];
+    // Remap: vertexIdx → list of { newIdx, nx, ny, nz, u, v } for deduplication
+    const remap = new Map();
+    const tmpNormal = [0, 1, 0];
+    const tmpUV = [0, 0];
+    let newVertexCount = 0;
+    // Process triangles in the material group's polygon range
+    for (let tri = 0; tri < triangles.triIndices.length; tri += 3) {
+        const pIdx = triangles.triPolyIdx[tri / 3];
+        if (pIdx < group.polyRange[0] || pIdx >= group.polyRange[1])
+            continue;
+        for (let c = 0; c < 3; c++) {
+            const cornerIdx = triangles.triCornerIndices[tri + c];
+            const vertexIdx = triangles.triIndices[tri + c];
+            // Get normal for this corner
+            getNormal(geo.normals, isPerCornerNormal, cornerIdx, vertexIdx, tmpNormal);
+            // Get UV for this corner
+            getUV(geo.uvs, isPerCornerUV, cornerIdx, vertexIdx, tmpUV);
+            // Check remap for an existing vertex with the same attributes
+            let newIdx = -1;
+            const entries = remap.get(vertexIdx);
+            if (entries) {
+                for (let _i = 0, _it = entries, _n = _it.length; _i < _n; _i++) {
+                    const e = _it[_i];
+                    if (e.nx === tmpNormal[0] && e.ny === tmpNormal[1] && e.nz === tmpNormal[2] &&
+                        e.u === tmpUV[0] && e.v === tmpUV[1]) {
+                        newIdx = e.newIdx;
+                        break;
+                    }
+                }
+            }
+            if (newIdx === -1) {
+                newIdx = newVertexCount++;
+                newVerts.push(geo.vertices[vertexIdx * 3], geo.vertices[vertexIdx * 3 + 1], geo.vertices[vertexIdx * 3 + 2], tmpNormal[0], tmpNormal[1], tmpNormal[2]);
+                if (hasUVs) {
+                    newUVs.push(tmpUV[0], tmpUV[1]);
+                }
+                if (hasColors) {
+                    // Always use white vertex color. The material's baseColor (set by
+                    // the renderer from MaterialData.baseColor) handles solid coloring,
+                    // and the texture handles textured coloring. Baking the material's
+                    // diffuse color into vertex colors here would double-apply it in the
+                    // shader (texColor * vertexColor * baseColor), squaring the values
+                    // and making colors too dark/desaturated.
+                    newColors.push(1, 1, 1);
+                }
+                // Skin data: look up bone weights for this vertex
+                if (skin) {
+                    const bones = skin.vertexBones.get(vertexIdx);
+                    if (bones && bones.length > 0) {
+                        // Take top 4 weights
+                        const sorted = [...bones].sort((a, b) => b.weight - a.weight);
+                        const top4 = sorted.slice(0, 4);
+                        const totalWeight = top4.reduce((sum, b) => sum + b.weight, 0);
+                        const j0 = top4[0]?.boneIdx ?? 0;
+                        const j1 = top4[1]?.boneIdx ?? 0;
+                        const j2 = top4[2]?.boneIdx ?? 0;
+                        const j3 = top4[3]?.boneIdx ?? 0;
+                        const w0 = top4[0]?.weight ?? 0;
+                        const w1 = top4[1]?.weight ?? 0;
+                        const w2 = top4[2]?.weight ?? 0;
+                        const w3 = top4[3]?.weight ?? 0;
+                        // Normalize weights
+                        const invTotal = totalWeight > 0 ? 1 / totalWeight : 0;
+                        newJoints.push(j0, j1, j2, j3);
+                        newWeights.push(w0 * invTotal, w1 * invTotal, w2 * invTotal, w3 * invTotal);
+                    }
+                    else {
+                        newJoints.push(0, 0, 0, 0);
+                        newWeights.push(0, 0, 0, 0);
+                    }
+                }
+                if (!entries) {
+                    remap.set(vertexIdx, [{ newIdx, nx: tmpNormal[0], ny: tmpNormal[1], nz: tmpNormal[2], u: tmpUV[0], v: tmpUV[1] }]);
+                }
+                else {
+                    entries.push({ newIdx, nx: tmpNormal[0], ny: tmpNormal[1], nz: tmpNormal[2], u: tmpUV[0], v: tmpUV[1] });
+                }
+            }
+            newIndices.push(newIdx);
+        }
+    }
+    if (newVertexCount === 0)
+        return null;
+    // Choose index type based on vertex count
+    const useUint32 = newVertexCount > 65535;
+    const indices = useUint32
+        ? new Uint32Array(newIndices)
+        : new Uint16Array(newIndices);
+    const mesh = {
+        vertices: new Float32Array(newVerts),
+        indices,
+        vertexCount: newVertexCount,
+        indexCount: newIndices.length,
+        uvs: hasUVs ? new Float32Array(newUVs) : null,
+        colors: hasColors ? new Float32Array(newColors) : null,
+        materialIndex,
+    };
+    // Add skin data if present
+    if (skin && newJoints.length > 0) {
+        // Choose the smallest typed array that can hold all bone indices.
+        // uint8 suffices for ≤255 bones, uint16 for ≤65535, uint32 beyond that.
+        let maxBone = 0;
+        for (let i = 0; i < newJoints.length; i++) {
+            if (newJoints[i] > maxBone)
+                maxBone = newJoints[i];
+        }
+        if (maxBone <= 255) {
+            mesh.joints = new Uint8Array(newJoints);
+        }
+        else if (maxBone <= 65535) {
+            mesh.joints = new Uint16Array(newJoints);
+        }
+        else {
+            mesh.joints = new Uint32Array(newJoints);
+        }
+        mesh.weights = new Float32Array(newWeights);
+    }
+    return mesh;
+}
+/** Get the normal for a corner, handling per-corner vs per-vertex mapping. */
+function getNormal(normals, isPerCorner, cornerIdx, vertexIdx, out) {
+    if (normals) {
+        let srcIdx;
+        if (isPerCorner) {
+            srcIdx = (normals.refType === "IndexToDirect" && normals.index ? (normals.index[cornerIdx] ?? 0) : cornerIdx) * 3;
+        }
+        else {
+            srcIdx = (normals.refType === "IndexToDirect" && normals.index ? (normals.index[vertexIdx] ?? 0) : vertexIdx) * 3;
+        }
+        out[0] = normals.data[srcIdx] ?? 0;
+        out[1] = normals.data[srcIdx + 1] ?? 0;
+        out[2] = normals.data[srcIdx + 2] ?? 0;
+    }
+    else {
+        out[0] = 0;
+        out[1] = 1;
+        out[2] = 0;
+    }
+}
+/** Get the UV for a corner, handling per-corner vs per-vertex mapping.
+ * FBX UVs use OpenGL convention (V=0 at bottom); WebGPU expects V=0 at top. */
+function getUV(uvs, isPerCorner, cornerIdx, vertexIdx, out) {
+    if (!uvs || uvs.data.length === 0) {
+        out[0] = 0;
+        out[1] = 0;
+        return;
+    }
+    let srcIdx;
+    if (!isPerCorner) {
+        // ByVertexPoint / ByVertice
+        srcIdx = (uvs.refType === "IndexToDirect" && uvs.index ? (uvs.index[vertexIdx] ?? 0) : vertexIdx) * 2;
+    }
+    else {
+        srcIdx = (uvs.refType === "IndexToDirect" && uvs.index ? (uvs.index[cornerIdx] ?? 0) : cornerIdx) * 2;
+    }
+    out[0] = uvs.data[srcIdx] ?? 0;
+    out[1] = 1.0 - (uvs.data[srcIdx + 1] ?? 0); // Flip V for WebGPU
+}