@instruktlabs/kiln 1.2.2 → 1.2.3

package/lib/views/camera.js

@@ -1,6 +1,9 @@
 import { Vector3, Matrix4, Euler, Group } from 'three';
 import { collectTriangles, compositingOrder, measureBounds, orbitDir } from "./raster.js";
 import { resolveBackdrop } from "./background.js";
+import { cloneReviewScene } from "./scene-copy.js";
+import { visibleNormalSign } from "./face-policy.js";
+import { prepareTriangleCoverage } from "./triangle-coverage.js";
 const vec = (a) => new Vector3(...a);
 const tuple = (v) => [v.x || 0, v.y || 0, v.z || 0];
 /** Common near-misses for camera keys, named in the unknown-key error. */
@@ -301,7 +304,11 @@ export function resolveAssetCamera(root, shot = {}) {
             const padding = request.padding ?? 1.2;
             const fit = cameraFromBounds(bounds, tuple(direction), padding, tuple(up), measureBounds(root));
             if (request.projection === 'orthographic')
-                camera = { ...fit, near: request.near ?? fit.near, far: request.far ?? fit.far };
+                camera = {
+                    ...fit,
+                    near: request.near ?? fit.near,
+                    far: request.far ?? fit.far,
+                };
             else {
                 const fov = finite(request.fovDeg ?? 50, 'fovDeg');
                 if (fov <= 0 || fov >= 180)
@@ -375,9 +382,9 @@ export async function withCameraVisibility(root, shot, run) {
  * A derivative GLB
  * serialized from a scene with hidden nodes (authored, or isolated by
  * {@link withCameraVisibility}) would ship them to the GPU. Every node with
- * `visible = false` leaves with its subtree, which is what three draws. Returns the root
- * itself when nothing is hidden, else a pruned clone; the caller's scene is never mutated and
- * restores `.visible` itself.
+ * `visible = false` removes drawing from its subtree. Required skeleton ancestors remain
+ * as transforms without drawing payloads. Returns the root itself when nothing is hidden,
+ * else an independent pruned hierarchy/skeleton; the caller restores `.visible` itself.
  */
 export function withoutHiddenMeshes(root) {
     if (root.visible === false) {
@@ -394,15 +401,7 @@ export function withoutHiddenMeshes(root) {
     });
     if (!any)
         return root;
-    const copy = root.clone(true);
-    const drop = [];
-    copy.traverse((node) => {
-        if (hidden(node))
-            drop.push(node);
-    });
-    for (const node of drop)
-        node.removeFromParent();
-    return copy;
+    return cloneReviewScene(root, { omitHidden: true });
 }
 /** Flat geometry renderer with exact orthographic/perspective projection and near/far clipping. */
 export function rasterizeCamera(root, input, size = 384, backfaceCull = true, backdrop) {
@@ -415,6 +414,7 @@ export function rasterizeCamera(root, input, size = 384, backfaceCull = true, ba
     for (let i = 0; i < size * size; i++)
         out.set(bg, i * 3);
     const depth = new Float64Array(size * size).fill(Infinity);
+    const weights = new Float64Array(3);
     const clip = (points, plane, near) => {
         const result = [];
         for (let i = 0; i < points.length; i++) {
@@ -422,8 +422,13 @@ export function rasterizeCamera(root, input, size = 384, backfaceCull = true, ba
             const insideA = near ? a.z >= plane : a.z <= plane, insideB = near ? b.z >= plane : b.z <= plane;
             if (insideA)
                 result.push(a);
-            if (insideA !== insideB)
-                result.push(a.clone().lerp(b, (plane - a.z) / (b.z - a.z)));
+            if (insideA !== insideB) {
+                // Shared intersections must round identically for either edge direction.
+                const low = a.z < b.z ? a : b, high = a.z < b.z ? b : a;
+                const intersection = low.clone().lerp(high, (plane - low.z) / (high.z - low.z));
+                intersection.z = plane;
+                result.push(intersection);
+            }
         }
         return result;
     };
@@ -438,14 +443,14 @@ export function rasterizeCamera(root, input, size = 384, backfaceCull = true, ba
             .clone()
             .sub(world[0])
             .cross(world[2].clone().sub(world[0]))
-            .normalize();
-        if (backfaceCull &&
-            !tri.doubleSided &&
-            normal.dot(camera.projection === 'perspective' ? position.clone().sub(world[0]) : z) <= 0)
+            .normalize()
+            .multiplyScalar(tri.windingParity);
+        const normalSign = visibleNormalSign(normal.dot(camera.projection === 'perspective' ? position.clone().sub(world[0]) : z), tri.side, backfaceCull);
+        if (normalSign === 0)
             continue;
         if (tri.alpha <= 0)
             continue;
-        const light = Math.min(1, 0.25 + 1.1 * Math.max(0, normal.dot(key)));
+        const light = Math.min(1, 0.25 + 1.1 * Math.max(0, normal.dot(key) * normalSign));
         const color = tri.color.map((c) => Math.round(srgb(c * light) * 255));
         let polygon = world.map((p) => {
             const d = p.clone().sub(position);
@@ -464,17 +469,16 @@ export function rasterizeCamera(root, input, size = 384, backfaceCull = true, ba
                 ];
             });
             const [a, b, c] = screen;
-            const area = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
-            if (Math.abs(area) < 1e-9)
+            const triangle = prepareTriangleCoverage(a[0], a[1], b[0], b[1], c[0], c[1], size);
+            if (!triangle)
                 continue;
-            for (let py = Math.max(0, Math.floor(Math.min(...screen.map((s) => s[1])))); py <= Math.min(size - 1, Math.ceil(Math.max(...screen.map((s) => s[1])))); py++)
-                for (let px = Math.max(0, Math.floor(Math.min(...screen.map((s) => s[0])))); px <= Math.min(size - 1, Math.ceil(Math.max(...screen.map((s) => s[0])))); px++) {
-                    const w0 = ((b[0] - a[0]) * (py + 0.5 - a[1]) - (b[1] - a[1]) * (px + 0.5 - a[0])) / area, w1 = ((c[0] - b[0]) * (py + 0.5 - b[1]) - (c[1] - b[1]) * (px + 0.5 - b[0])) / area, w2 = 1 - w0 - w1;
-                    if (w0 < 0 || w1 < 0 || w2 < 0)
+            for (let py = triangle.minY; py <= triangle.maxY; py++)
+                for (let px = triangle.minX; px <= triangle.maxX; px++) {
+                    if (!triangle.sample(px + 0.5, py + 0.5, weights))
                         continue;
                     const d = camera.projection === 'perspective'
-                        ? 1 / (w1 / p[0].z + w2 / p[1].z + w0 / p[2].z)
-                        : w1 * p[0].z + w2 * p[1].z + w0 * p[2].z;
+                        ? 1 / (weights[0] / p[0].z + weights[1] / p[1].z + weights[2] / p[2].z)
+                        : weights[0] * p[0].z + weights[1] * p[1].z + weights[2] * p[2].z;
                     const index = py * size + px;
                     if (d >= depth[index])
                         continue;

package/lib/views/face-policy.d.ts

@@ -0,0 +1,9 @@
+/** Standard material sides, kept numeric for cross-realm and flat GLB inputs. */
+export type SurfaceSide = 0 | 1 | 2;
+/** Match Three's affine front-face convention; a singular transform does not flip.
+ * Collapsed triangles are discarded by rasterization. No inverse is needed. */
+export declare function worldWindingParity(m: ArrayLike<number>): 1 | -1;
+/** Facing uses deformed triangle winding corrected for the mesh world transform.
+ * Zero means culled; +/-1 orients the visible flat lighting normal. Disabling
+ * culling is a diagnostic two-sided override, matching GPU review derivatives. */
+export declare function visibleNormalSign(facing: number, side: SurfaceSide, cull: boolean): -1 | 0 | 1;

package/lib/views/face-policy.js

@@ -0,0 +1,16 @@
+/** Match Three's affine front-face convention; a singular transform does not flip.
+ * Collapsed triangles are discarded by rasterization. No inverse is needed. */
+export function worldWindingParity(m) {
+    const determinant = m[0] * (m[5] * m[10] - m[9] * m[6]) -
+        m[4] * (m[1] * m[10] - m[9] * m[2]) +
+        m[8] * (m[1] * m[6] - m[5] * m[2]);
+    return determinant < 0 ? -1 : 1;
+}
+/** Facing uses deformed triangle winding corrected for the mesh world transform.
+ * Zero means culled; +/-1 orients the visible flat lighting normal. Disabling
+ * culling is a diagnostic two-sided override, matching GPU review derivatives. */
+export function visibleNormalSign(facing, side, cull) {
+    if (cull && ((side === 0 && facing <= 0) || (side === 1 && facing >= 0)))
+        return 0;
+    return facing < 0 ? -1 : 1;
+}

package/lib/views/glb.js

@@ -1,11 +1,14 @@
 /** GLB-native input adapter for the deterministic CPU geometry-flat renderer. */
 import { useCubicSpline } from "../animation-cubic.js";
+import { gltfTextureBindingKey, restoreGltfTextureBinding } from "../gltf-texture-binding.js";
+import { isCubicSplineTrack } from "../animation-spline.js";
 import { createGltfIO } from "../gltf-io.js";
 import { listLodChainNodes } from "../lod-export.js";
 import { isHiddenGltfNode } from "../metrics.js";
 import { registerReviewLodChains } from "./lod.js";
+import { atlasDocumentTable, expandAtlasBinding, restoreAtlasTextureProvenance, validateAtlasDocumentProvenance, } from "../atlas-provenance.js";
 import { Primitive, } from '@gltf-transform/core';
-import { BufferAttribute, BufferGeometry, Group, Matrix4, Mesh, MeshStandardMaterial, NoColorSpace, SRGBColorSpace, Texture, AnimationClip, QuaternionKeyframeTrack, VectorKeyframeTrack, Quaternion, Vector3, InterpolateDiscrete, InterpolateLinear, } from 'three';
+import { BufferAttribute, BufferGeometry, Group, Matrix4, Mesh, Bone, SkinnedMesh, Skeleton, MeshStandardMaterial, NoColorSpace, SRGBColorSpace, Texture, AnimationClip, QuaternionKeyframeTrack, NumberKeyframeTrack, PropertyBinding, VectorKeyframeTrack, Quaternion, Vector3, InterpolateDiscrete, InterpolateLinear, } from 'three';
 export const GLB_GEOMETRY_FLAT_REASON = {
     TEXTURE_SAMPLING_UNSUPPORTED: 'GLB_FLAT_TEXTURE_SAMPLING_UNSUPPORTED',
     KTX2_SAMPLING_UNSUPPORTED: 'GLB_FLAT_KTX2_SAMPLING_UNSUPPORTED',
@@ -91,10 +94,18 @@ function reviewClipsFromExtras(extras) {
                 throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', 'Invalid animation review track.');
             }
             const property = track.name.slice(track.name.lastIndexOf('.') + 1);
-            const Track = property === 'quaternion' ? QuaternionKeyframeTrack : VectorKeyframeTrack;
+            const morph = /^morphTargetInfluences(?:\[[^\]]+\])?$/.test(property);
+            const Track = morph
+                ? NumberKeyframeTrack
+                : property === 'quaternion'
+                    ? QuaternionKeyframeTrack
+                    : VectorKeyframeTrack;
             if (track.interpolation === 'CUBICSPLINE') {
+                const tuple = morph ? track.values.length / track.times.length : cubicTuple(property);
                 if (track.times.length < 2 ||
-                    track.values.length !== track.times.length * cubicTuple(property)) {
+                    track.values.length !== track.times.length * tuple ||
+                    !Number.isInteger(tuple / 3) ||
+                    tuple < 3) {
                     throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', 'Invalid animation review track.');
                 }
                 return useCubicSpline(new Track(track.name, track.times, track.values));
@@ -182,7 +193,7 @@ function flatMaterial(material) {
             ?.getEmissiveStrength() ?? 1,
     };
 }
-function preserveTexture(source, usage, cache) {
+function preserveTexture(source, usage, cache, info, atlas) {
     if (!source)
         return null;
     const encoded = source.getImage();
@@ -194,14 +205,21 @@ function preserveTexture(source, usage, cache) {
         byUsage = new Map();
         cache.set(source, byUsage);
     }
-    const existing = byUsage.get(usage);
+    const reference = info?.getExtras()['kilnAtlasReference'];
+    const cacheKey = `${usage}:${gltfTextureBindingKey(info)}`;
+    const existing = byUsage.get(cacheKey);
     if (existing)
         return existing;
     const texture = new Texture();
     texture.name = source.getName();
     texture.colorSpace = usage === 'color' ? SRGBColorSpace : NoColorSpace;
     texture.userData.encoded = { mime, bytes: Uint8Array.from(encoded) };
-    byUsage.set(usage, texture);
+    texture.flipY = false;
+    if (info)
+        restoreGltfTextureBinding(texture, info);
+    if (reference && info && atlas)
+        restoreAtlasTextureProvenance(texture, info, atlas);
+    byUsage.set(cacheKey, texture);
     return texture;
 }
 function noteMaterialTextures(material, reasons) {
@@ -257,6 +275,7 @@ export async function loadGlbGeometryFlatScene(bytes) {
     catch (error) {
         throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', `Could not parse final GLB bytes: ${error instanceof Error ? error.message : String(error)}`);
     }
+    await validateAtlasDocumentProvenance(document);
     const scene = document.getRoot().getDefaultScene() ?? document.getRoot().listScenes()[0];
     if (!scene)
         throw new GlbGeometryFlatError('GLB_FLAT_NO_SCENE', 'Final GLB has no scene.');
@@ -274,18 +293,24 @@ export async function loadGlbGeometryFlatScene(bytes) {
     };
     for (const child of scene.listChildren())
         visit(child);
+    // Skinning needs the joint hierarchy and inverse bind matrices. Keep the
+    // historical flat adapter for rigid scenes, but share the review loader for
+    // a posed derivative instead of silently rasterizing its bind-pose positions.
+    if ([...sceneNodes].some((node) => node.getSkin() ||
+        node
+            .getMesh()
+            ?.listPrimitives()
+            .some((p) => p.listTargets().length))) {
+        await validateAtlasDocumentProvenance(document);
+        return reviewSceneFromDocument(document);
+    }
     for (const node of sceneNodes) {
         const mesh = node.getMesh();
         if (!mesh)
             continue;
-        if (node.getSkin())
-            reasons.add(GLB_GEOMETRY_FLAT_REASON.SKIN_DEFORMATION_UNSUPPORTED);
         const instances = instanceMatrices(node);
         instanceCount += instances.count;
         for (const primitive of mesh.listPrimitives()) {
-            if (primitive.listTargets().length > 0) {
-                reasons.add(GLB_GEOMETRY_FLAT_REASON.MORPH_TARGETS_UNSUPPORTED);
-            }
             const positionAccessor = primitive.getAttribute('POSITION');
             if (positionAccessor?.getElementSize() !== 3)
                 continue;
@@ -370,6 +395,10 @@ export async function loadGlbReviewScene(bytes) {
     catch {
         throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', 'Could not parse final GLB bytes.');
     }
+    await validateAtlasDocumentProvenance(document);
+    return reviewSceneFromDocument(document);
+}
+function reviewSceneFromDocument(document) {
     const sourceScene = document.getRoot().getDefaultScene() ?? document.getRoot().listScenes()[0];
     if (!sourceScene)
         throw new GlbGeometryFlatError('GLB_FLAT_NO_SCENE', 'Final GLB has no scene.');
@@ -377,14 +406,35 @@ export async function loadGlbReviewScene(bytes) {
     const root = new Group();
     root.name = sourceScene.getName() || 'Scene';
     const nodeMap = new Map();
+    const atlas = atlasDocumentTable(document);
     const textureCache = new Map();
+    const morphMeshes = new Map();
+    // Morph primitives need unique, binding-safe names: the historical ':primitive'
+    // suffix is a namespace separator to Three.PropertyBinding. Parent names stay intact.
+    const usedNames = new Set(document
+        .getRoot()
+        .listNodes()
+        .map((node) => node.getName()));
+    const nodeIds = new Map(document
+        .getRoot()
+        .listNodes()
+        .map((node, index) => [node, index]));
+    let morphValues = 0;
+    const morphError = (detail) => {
+        throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', `Invalid morph review data: ${detail}`);
+    };
+    const joints = new Set(document
+        .getRoot()
+        .listSkins()
+        .flatMap((skin) => skin.listJoints()));
+    const pendingSkins = [];
     let meshCount = 0;
     let instanceCount = 0;
     const buildNode = (source) => {
         const existing = nodeMap.get(source);
         if (existing)
             return existing;
-        const target = new Group();
+        const target = joints.has(source) ? new Bone() : new Group();
         target.name = source.getName();
         target.position.fromArray(source.getTranslation());
         target.quaternion.fromArray(source.getRotation());
@@ -396,14 +446,27 @@ export async function loadGlbReviewScene(bytes) {
         nodeMap.set(source, target);
         const sourceMesh = source.getMesh();
         if (sourceMesh) {
+            const targetCount = sourceMesh.listPrimitives()[0]?.listTargets().length ?? 0;
+            if (sourceMesh.listPrimitives().some((p) => p.listTargets().length !== targetCount))
+                morphError('primitives must have equal target counts.');
+            const nodeWeights = source.getWeights(), meshWeights = sourceMesh.getWeights();
+            for (const weights of [nodeWeights, meshWeights])
+                if (weights.length && (weights.length !== targetCount || !weights.every(Number.isFinite)))
+                    morphError('default weight count or values.');
+            const weights = nodeWeights.length
+                ? nodeWeights
+                : meshWeights.length
+                    ? meshWeights
+                    : Array(targetCount).fill(0);
+            // glTF Transform decodes extras.targetNames into PrimitiveTarget names.
+            const targetNames = sourceMesh
+                .listPrimitives()[0]
+                ?.listTargets()
+                .map((target, index) => target.getName() || String(index)) ?? [];
             target.userData.kilnGlbMeshNode = true;
-            if (source.getSkin())
-                reasons.add(GLB_GEOMETRY_FLAT_REASON.SKIN_DEFORMATION_UNSUPPORTED);
             const matrices = localInstanceMatrices(source);
             instanceCount += matrices.length;
             for (const [primitiveIndex, primitive] of sourceMesh.listPrimitives().entries()) {
-                if (primitive.listTargets().length)
-                    reasons.add(GLB_GEOMETRY_FLAT_REASON.MORPH_TARGETS_UNSUPPORTED);
                 const position = primitive.getAttribute('POSITION');
                 if (position?.getElementSize() !== 3)
                     continue;
@@ -416,6 +479,9 @@ export async function loadGlbReviewScene(bytes) {
                 noteMaterialTextures(material, reasons);
                 const flat = flatMaterial(material);
                 const geometry = new BufferGeometry();
+                const atlasBinding = primitive.getExtras()['kilnAtlasBinding'];
+                if (atlasBinding !== undefined && atlas)
+                    geometry.userData.kilnAtlasBinding = expandAtlasBinding(atlasBinding, atlas);
                 geometry.setAttribute('position', new BufferAttribute(Float32Array.from(decodedAccessor(position)), 3));
                 const normal = primitive.getAttribute('NORMAL');
                 if (normal) {
@@ -430,6 +496,59 @@ export async function loadGlbReviewScene(bytes) {
                     geometry.setAttribute('tangent', new BufferAttribute(Float32Array.from(decodedAccessor(tangent)), 4));
                 }
                 geometry.setIndex(new BufferAttribute(indices, 1));
+                if (targetCount) {
+                    const targets = primitive.listTargets();
+                    for (const target of targets)
+                        for (const semantic of target.listSemantics()) {
+                            const attribute = target.getAttribute(semantic);
+                            if (!primitive.getAttribute(semantic) ||
+                                attribute.getCount() !== position.getCount() ||
+                                ((semantic === 'POSITION' || semantic === 'NORMAL' || semantic === 'TANGENT') &&
+                                    attribute.getElementSize() !== 3))
+                                morphError(`target attribute ${semantic} does not match the base primitive.`);
+                            if (semantic !== 'POSITION' && semantic !== 'NORMAL')
+                                reasons.add(GLB_GEOMETRY_FLAT_REASON.MORPH_TARGETS_UNSUPPORTED);
+                        }
+                    const semantics = targets.some((target) => target.getAttribute('NORMAL'))
+                        ? ['POSITION', 'NORMAL']
+                        : ['POSITION'];
+                    // Bound zero-filled missing attributes as well as decoded ones: a tiny
+                    // file with many omitted deltas must not expand without limit.
+                    morphValues += targetCount * position.getCount() * 3 * semantics.length;
+                    if (morphValues > 16_777_216)
+                        morphError('expanded morph attributes exceed the 64 MiB review budget.');
+                    geometry.morphTargetsRelative = true;
+                    for (const semantic of semantics) {
+                        const attributes = targets.map((target) => {
+                            const attribute = target.getAttribute(semantic);
+                            const values = attribute
+                                ? Float32Array.from(decodedAccessor(attribute))
+                                : new Float32Array(position.getCount() * 3);
+                            if (!values.every(Number.isFinite))
+                                morphError(`nonfinite ${semantic} displacement.`);
+                            return new BufferAttribute(values, 3);
+                        });
+                        if (semantic === 'POSITION')
+                            geometry.morphAttributes.position = attributes;
+                        else
+                            geometry.morphAttributes.normal = attributes;
+                    }
+                }
+                if (source.getSkin()) {
+                    const skinIndices = primitive.getAttribute('JOINTS_0');
+                    const skinWeights = primitive.getAttribute('WEIGHTS_0');
+                    if (!skinIndices ||
+                        !skinWeights ||
+                        skinIndices.getElementSize() !== 4 ||
+                        skinWeights.getElementSize() !== 4 ||
+                        skinIndices.getCount() !== position.getCount() ||
+                        skinWeights.getCount() !== position.getCount())
+                        throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', `Invalid skin attributes on ${source.getName()}.`);
+                    if (primitive.getAttribute('JOINTS_1') || primitive.getAttribute('WEIGHTS_1'))
+                        throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', `Skin review supports four influences per vertex; ${source.getName()} has additional joint/weight sets.`);
+                    geometry.setAttribute('skinIndex', new BufferAttribute(Uint16Array.from(decodedAccessor(skinIndices)), 4));
+                    geometry.setAttribute('skinWeight', new BufferAttribute(Float32Array.from(decodedAccessor(skinWeights)), 4));
+                }
                 const threeMaterial = new MeshStandardMaterial({
                     opacity: flat.opacity,
                     transparent: flat.alphaMode === 'BLEND',
@@ -443,22 +562,41 @@ export async function loadGlbReviewScene(bytes) {
                 threeMaterial.emissiveIntensity = flat.emissiveIntensity;
                 if (material) {
                     threeMaterial.userData = { ...material.getExtras() };
-                    threeMaterial.map = preserveTexture(material.getBaseColorTexture(), 'color', textureCache);
-                    threeMaterial.normalMap = preserveTexture(material.getNormalTexture(), 'data', textureCache);
+                    threeMaterial.map = preserveTexture(material.getBaseColorTexture(), 'color', textureCache, material.getBaseColorTextureInfo(), atlas);
+                    threeMaterial.normalMap = preserveTexture(material.getNormalTexture(), 'data', textureCache, material.getNormalTextureInfo(), atlas);
                     threeMaterial.normalScale.setScalar(material.getNormalScale());
-                    const metallicRoughness = preserveTexture(material.getMetallicRoughnessTexture(), 'data', textureCache);
+                    const metallicRoughness = preserveTexture(material.getMetallicRoughnessTexture(), 'data', textureCache, material.getMetallicRoughnessTextureInfo(), atlas);
                     threeMaterial.metalnessMap = metallicRoughness;
                     threeMaterial.roughnessMap = metallicRoughness;
-                    threeMaterial.emissiveMap = preserveTexture(material.getEmissiveTexture(), 'color', textureCache);
-                    threeMaterial.aoMap = preserveTexture(material.getOcclusionTexture(), 'data', textureCache);
+                    threeMaterial.emissiveMap = preserveTexture(material.getEmissiveTexture(), 'color', textureCache, material.getEmissiveTextureInfo(), atlas);
+                    threeMaterial.aoMap = preserveTexture(material.getOcclusionTexture(), 'data', textureCache, material.getOcclusionTextureInfo(), atlas);
                     threeMaterial.aoMapIntensity = material.getOcclusionStrength();
                 }
                 for (const [index, matrix] of matrices.entries()) {
-                    const mesh = new Mesh(geometry, threeMaterial);
+                    const mesh = source.getSkin()
+                        ? new SkinnedMesh(geometry, threeMaterial)
+                        : new Mesh(geometry, threeMaterial);
+                    if (mesh instanceof SkinnedMesh)
+                        pendingSkins.push({ source, mesh });
                     // A deduplicated mesh resource can serve many distinctly named nodes.
                     // QA repair hints must identify this owning node, not the shared resource.
                     const baseName = source.getName() || sourceMesh.getName() || 'Mesh';
                     mesh.name = `${baseName}:primitive-${primitiveIndex}${matrices.length === 1 ? '' : `:instance-${index}`}`;
+                    if (targetCount) {
+                        let bindingName = `${PropertyBinding.sanitizeNodeName(baseName)}_morph_${nodeIds.get(source)}_${primitiveIndex}_${index}`;
+                        while (usedNames.has(bindingName))
+                            bindingName += '_';
+                        usedNames.add(bindingName);
+                        mesh.name = bindingName;
+                        mesh.morphTargetInfluences = [...weights];
+                        if (Array.isArray(targetNames) &&
+                            targetNames.length === targetCount &&
+                            targetNames.every((name) => typeof name === 'string'))
+                            mesh.morphTargetDictionary = Object.fromEntries(targetNames.map((name, index) => [name, index]));
+                        const siblings = morphMeshes.get(source) ?? [];
+                        siblings.push(mesh);
+                        morphMeshes.set(source, siblings);
+                    }
                     mesh.matrixAutoUpdate = false;
                     mesh.matrix.copy(matrix);
                     target.add(mesh);
@@ -484,6 +622,28 @@ export async function loadGlbReviewScene(bytes) {
         base: nodeMap.get(base),
         levels: lower.some((level) => nodeMap.has(level)) ? [] : lower.map(buildNode),
     })));
+    for (const { source, mesh } of pendingSkins) {
+        const skin = source.getSkin();
+        const bones = skin.listJoints().map((joint) => nodeMap.get(joint));
+        const inverse = skin.getInverseBindMatrices();
+        if (!bones.length ||
+            bones.some((bone) => !(bone instanceof Bone)) ||
+            (inverse && (inverse.getElementSize() !== 16 || inverse.getCount() < bones.length)))
+            throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', `Invalid or unavailable skin joints/bind matrices on ${source.getName()}.`);
+        const indices = mesh.geometry.getAttribute('skinIndex');
+        const weights = mesh.geometry.getAttribute('skinWeight');
+        for (let i = 0; i < indices.array.length; i++)
+            if (indices.array[i] >= bones.length ||
+                !Number.isFinite(weights.array[i]) ||
+                weights.array[i] < 0)
+                throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', `Invalid skin joint index or weight on ${source.getName()}.`);
+        const matrices = bones.map((_, index) => new Matrix4().fromArray(inverse ? inverse.getElement(index, []) : new Matrix4().elements));
+        // glTF's inverse bind already maps mesh-local positions into joint space.
+        // Identity bindMatrix and AttachedBindMode cancel the mesh world transform,
+        // matching GLTFLoader even under translated/scaled mesh ancestors.
+        mesh.bind(new Skeleton(bones, matrices), new Matrix4());
+    }
+    root.updateMatrixWorld(true);
     const nativeClips = document
         .getRoot()
         .listAnimations()
@@ -494,7 +654,7 @@ export async function loadGlbReviewScene(bytes) {
         const input = sampler?.getInput()?.getArray();
         const output = sampler?.getOutput()?.getArray();
         const property = path === 'translation' ? 'position' : path === 'rotation' ? 'quaternion' : path;
-        if (!node || !property || property === 'weights' || !input || !output)
+        if (!node || !property || !input || !output)
             return [];
         const interpolation = sampler.getInterpolation();
         if (interpolation !== 'STEP' &&
@@ -502,6 +662,25 @@ export async function loadGlbReviewScene(bytes) {
             interpolation !== 'CUBICSPLINE') {
             throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', `Animation review does not support ${interpolation} interpolation; use LINEAR, STEP or CUBICSPLINE.`);
         }
+        if (property === 'weights') {
+            const targets = morphMeshes.get(node);
+            if (!targets?.length)
+                return [];
+            const width = targets[0].morphTargetInfluences.length;
+            const values = decodedAccessor(sampler.getOutput());
+            if (input.length < 1 ||
+                input.length > REVIEW_CLIP_LIMITS.samplesPerTrack ||
+                values.length > REVIEW_CLIP_LIMITS.valuesPerTrack ||
+                values.length !==
+                    input.length * width * (interpolation === 'CUBICSPLINE' ? 3 : 1) ||
+                !Array.from(input).every((v, i) => Number.isFinite(v) && v >= 0 && (i === 0 || v > input[i - 1])) ||
+                !Array.from(values).every(Number.isFinite))
+                morphError('animation weight sampler width or values.');
+            return targets.map((mesh) => {
+                const track = new NumberKeyframeTrack(`${mesh.name}.morphTargetInfluences`, input, values, interpolation === 'STEP' ? InterpolateDiscrete : InterpolateLinear);
+                return interpolation === 'CUBICSPLINE' ? useCubicSpline(track) : track;
+            });
+        }
         const Track = path === 'rotation' ? QuaternionKeyframeTrack : VectorKeyframeTrack;
         if (interpolation === 'CUBICSPLINE') {
             if (input.length < 2 || output.length !== input.length * cubicTuple(property)) {
@@ -513,7 +692,22 @@ export async function loadGlbReviewScene(bytes) {
             new Track(`${node.getName()}.${property}`, input, output, interpolation === 'STEP' ? InterpolateDiscrete : InterpolateLinear),
         ];
     })), animation.getExtras().kilnLoopIntent));
-    const clips = reviewClipsFromExtras(sourceScene.getExtras()) ?? nativeClips;
+    const extrasClips = reviewClipsFromExtras(sourceScene.getExtras());
+    if (extrasClips)
+        for (const clip of extrasClips)
+            clip.tracks = clip.tracks.flatMap((track) => {
+                const dot = track.name.lastIndexOf('.'), property = track.name.slice(dot + 1);
+                if (!/^morphTargetInfluences(?:\[[^\]]+\])?$/.test(property))
+                    return [track];
+                const sources = [...morphMeshes.keys()].filter((node) => node.getName() === track.name.slice(0, dot));
+                if (sources.length !== 1)
+                    return [track]; // Preserve unresolved/ambiguous author evidence.
+                return morphMeshes.get(sources[0]).map((mesh) => {
+                    const copy = new NumberKeyframeTrack(`${mesh.name}.${property}`, track.times, track.values, track.getInterpolation());
+                    return isCubicSplineTrack(track) ? useCubicSpline(copy) : copy;
+                });
+            });
+    const clips = extrasClips ?? nativeClips;
     return {
         root,
         clips,

package/lib/views/pose.d.ts

@@ -1,6 +1,9 @@
 /** Minimal duck-typed view of a Three.js node we pose. */
 interface DuckNode {
     name?: string;
+    uuid?: string;
+    morphTargetInfluences?: number[];
+    morphTargetDictionary?: Record<string, number>;
     position?: {
         set(x: number, y: number, z: number): void;
     };
@@ -31,7 +34,7 @@ export interface DuckClip {
         kilnLoopIntent?: unknown;
     };
 }
-type Prop = 'position' | 'quaternion' | 'scale';
+type Prop = 'position' | 'quaternion' | 'scale' | 'morphTargetInfluences';
 interface PreparedTrack {
     nodeName: string;
     prop: Prop;
@@ -40,6 +43,9 @@ interface PreparedTrack {
     /** One value of `stride` per key; a CUBICSPLINE key is [in-tangent, value, out-tangent]. */
     values: number[];
     interpolation: 'LINEAR' | 'STEP' | 'CUBICSPLINE';
+    /** Original spelling retained for unresolved-track evidence. */
+    sourceName?: string;
+    morphIndex?: number;
 }
 /** A clip prepared for repeated time-sampling: parsed tracks + a derived duration. */
 export interface PreparedClip {