@forgeax/engine-gltf 0.0.0-dev.8d955ade1c79

package/src/__tests__/meshopt-mode-filter-owner.test-d.ts

@@ -0,0 +1,79 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type {
+  GLTF_MESHOPT_FILTERS,
+  GLTF_MESHOPT_MODES,
+  GltfMeshoptDecodeFailedDetail,
+  GltfMeshoptFilter,
+  GltfMeshoptMode,
+} from '../errors.js';
+import type {
+  GltfBufferViewDecodeCapability,
+  MeshoptCompressionJson,
+  MeshoptFilter,
+  MeshoptMode,
+} from '../meshopt-decode.js';
+
+const errorsSource = readFileSync(new URL('../errors.ts', import.meta.url), 'utf8');
+const meshoptSource = readFileSync(new URL('../meshopt-decode.ts', import.meta.url), 'utf8');
+
+type DecodedMode = Parameters<GltfBufferViewDecodeCapability['decode']>[0]['mode'];
+type DecodedFilter = Parameters<GltfBufferViewDecodeCapability['decode']>[0]['filter'];
+
+describe('glTF Meshopt mode/filter owner', () => {
+  it('keeps tuple order and derives every Meshopt vocabulary projection', () => {
+    expectTypeOf<typeof GLTF_MESHOPT_MODES>().toEqualTypeOf<
+      readonly ['ATTRIBUTES', 'TRIANGLES', 'INDICES']
+    >();
+    expectTypeOf<typeof GLTF_MESHOPT_FILTERS>().toEqualTypeOf<
+      readonly ['NONE', 'OCTAHEDRAL', 'QUATERNION', 'EXPONENTIAL']
+    >();
+
+    expectTypeOf<GltfMeshoptMode>().toEqualTypeOf<(typeof GLTF_MESHOPT_MODES)[number]>();
+    expectTypeOf<(typeof GLTF_MESHOPT_MODES)[number]>().toEqualTypeOf<GltfMeshoptMode>();
+    expectTypeOf<GltfMeshoptFilter>().toEqualTypeOf<(typeof GLTF_MESHOPT_FILTERS)[number]>();
+    expectTypeOf<(typeof GLTF_MESHOPT_FILTERS)[number]>().toEqualTypeOf<GltfMeshoptFilter>();
+
+    expectTypeOf<MeshoptMode>().toEqualTypeOf<GltfMeshoptMode>();
+    expectTypeOf<GltfMeshoptMode>().toEqualTypeOf<MeshoptMode>();
+    expectTypeOf<MeshoptFilter>().toEqualTypeOf<GltfMeshoptFilter>();
+    expectTypeOf<GltfMeshoptFilter>().toEqualTypeOf<MeshoptFilter>();
+    expectTypeOf<MeshoptCompressionJson['mode']>().toEqualTypeOf<MeshoptMode>();
+    expectTypeOf<MeshoptCompressionJson['filter']>().toEqualTypeOf<MeshoptFilter | undefined>();
+    expectTypeOf<DecodedMode>().toEqualTypeOf<MeshoptMode>();
+    expectTypeOf<DecodedFilter>().toEqualTypeOf<MeshoptFilter>();
+    expectTypeOf<GltfMeshoptDecodeFailedDetail['mode']>().toEqualTypeOf<MeshoptMode>();
+    expectTypeOf<GltfMeshoptDecodeFailedDetail['filter']>().toEqualTypeOf<MeshoptFilter>();
+  });
+
+  it('keeps the owner declarations and tuple-driven validation single-sourced', () => {
+    expect(errorsSource).toContain(
+      'export type GltfMeshoptMode = (typeof GLTF_MESHOPT_MODES)[number];',
+    );
+    expect(errorsSource).toContain(
+      'export type GltfMeshoptFilter = (typeof GLTF_MESHOPT_FILTERS)[number];',
+    );
+    expect(errorsSource).toContain('readonly mode: GltfMeshoptMode;');
+    expect(errorsSource).toContain('readonly filter: GltfMeshoptFilter;');
+    expect(meshoptSource).toContain('export type MeshoptMode = GltfMeshoptMode;');
+    expect(meshoptSource).toContain('export type MeshoptFilter = GltfMeshoptFilter;');
+    expect(meshoptSource).toContain(
+      'return GLTF_MESHOPT_MODES.some((candidate) => candidate === mode);',
+    );
+    expect(meshoptSource).toContain(
+      'return GLTF_MESHOPT_FILTERS.some((candidate) => candidate === filter);',
+    );
+    expect(meshoptSource).not.toContain(
+      "export type MeshoptMode = 'ATTRIBUTES' | 'TRIANGLES' | 'INDICES';",
+    );
+    expect(meshoptSource).not.toContain(
+      "export type MeshoptFilter = 'NONE' | 'OCTAHEDRAL' | 'QUATERNION' | 'EXPONENTIAL';",
+    );
+    expect(errorsSource).not.toContain("readonly mode: 'ATTRIBUTES' | 'TRIANGLES' | 'INDICES';");
+    expect(errorsSource).not.toContain(
+      "readonly filter: 'NONE' | 'OCTAHEDRAL' | 'QUATERNION' | 'EXPONENTIAL';",
+    );
+  });
+});

package/src/__tests__/meshopt-real-matrix.integration.test.ts

@@ -0,0 +1,370 @@
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { Asset, ImportContext, ImportedAsset } from '@forgeax/engine-types';
+import { MeshoptDecoder, MeshoptEncoder } from 'meshoptimizer';
+import { describe, expect, it } from 'vitest';
+import { createGltfImporter } from '../gltf-importer.js';
+import { parseGlb } from '../parse-gltf.js';
+import { unwrapMeshAsset as meshIrToMeshAsset } from './bridge-test-helpers.js';
+
+function bytesOf(view: ArrayBufferView): Uint8Array {
+  return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+}
+
+function pad4(bytes: Uint8Array, fill: number): Uint8Array {
+  const padded = new Uint8Array((bytes.byteLength + 3) & ~3);
+  padded.fill(fill);
+  padded.set(bytes);
+  return padded;
+}
+
+function makeGlb(json: Record<string, unknown>, binary: Uint8Array): ArrayBuffer {
+  const jsonBytes = pad4(new TextEncoder().encode(JSON.stringify(json)), 0x20);
+  const binBytes = pad4(binary, 0);
+  const totalLength = 12 + 8 + jsonBytes.byteLength + 8 + binBytes.byteLength;
+  const glb = new Uint8Array(totalLength);
+  const view = new DataView(glb.buffer);
+  view.setUint32(0, 0x46546c67, true);
+  view.setUint32(4, 2, true);
+  view.setUint32(8, totalLength, true);
+  view.setUint32(12, jsonBytes.byteLength, true);
+  view.setUint32(16, 0x4e4f534a, true);
+  glb.set(jsonBytes, 20);
+  const binHeader = 20 + jsonBytes.byteLength;
+  view.setUint32(binHeader, binBytes.byteLength, true);
+  view.setUint32(binHeader + 4, 0x004e4942, true);
+  glb.set(binBytes, binHeader + 8);
+  return glb.buffer;
+}
+
+function compressedGlb(): ArrayBuffer {
+  const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+  const indices = new Uint16Array([0, 1, 2]);
+  const positionBytes = MeshoptEncoder.encodeGltfBuffer(
+    bytesOf(positions),
+    positions.length / 3,
+    12,
+    'ATTRIBUTES',
+  );
+  const indexBytes = MeshoptEncoder.encodeGltfBuffer(
+    bytesOf(indices),
+    indices.length,
+    2,
+    'TRIANGLES',
+  );
+  const indexOffset = positionBytes.byteLength;
+  const binary = new Uint8Array(indexOffset + indexBytes.byteLength);
+  binary.set(positionBytes, 0);
+  binary.set(indexBytes, indexOffset);
+  return makeGlb(
+    {
+      asset: { version: '2.0' },
+      extensionsUsed: ['EXT_meshopt_compression'],
+      extensionsRequired: ['EXT_meshopt_compression'],
+      buffers: [{ byteLength: binary.byteLength }],
+      bufferViews: [
+        {
+          buffer: 0,
+          byteLength: 0,
+          extensions: {
+            EXT_meshopt_compression: {
+              buffer: 0,
+              byteOffset: 0,
+              byteLength: positionBytes.byteLength,
+              byteStride: 12,
+              count: 3,
+              mode: 'ATTRIBUTES',
+            },
+          },
+        },
+        {
+          buffer: 0,
+          byteLength: 0,
+          extensions: {
+            EXT_meshopt_compression: {
+              buffer: 0,
+              byteOffset: indexOffset,
+              byteLength: indexBytes.byteLength,
+              byteStride: 2,
+              count: 3,
+              mode: 'TRIANGLES',
+            },
+          },
+        },
+      ],
+      accessors: [
+        { bufferView: 0, componentType: 5126, count: 3, type: 'VEC3' },
+        { bufferView: 1, componentType: 5123, count: 3, type: 'SCALAR' },
+      ],
+      meshes: [
+        {
+          primitives: [{ attributes: { POSITION: 0 }, indices: 1 }],
+        },
+      ],
+    },
+    binary,
+  );
+}
+
+describe('real EXT_meshopt_compression glTF matrix', () => {
+  function decoder() {
+    return {
+      decode({
+        source,
+        count,
+        stride,
+        mode,
+        filter,
+      }: {
+        source: Uint8Array;
+        count: number;
+        stride: number;
+        mode: 'ATTRIBUTES' | 'TRIANGLES' | 'INDICES';
+        filter: 'NONE' | 'OCTAHEDRAL' | 'QUATERNION' | 'EXPONENTIAL';
+      }) {
+        const target = new Uint8Array(count * stride);
+        MeshoptDecoder.decodeGltfBuffer(target, count, stride, source, mode, filter);
+        return target;
+      },
+    };
+  }
+
+  it('decodes compressed ATTRIBUTES and TRIANGLES streams before bridge projection', async () => {
+    await MeshoptEncoder.ready;
+    await MeshoptDecoder.ready;
+    const result = await parseGlb(compressedGlb(), 'meshopt-real.glb', { meshopt: decoder() });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.meshes).toHaveLength(1);
+    expect(Array.from(result.value.meshes[0]?.positions ?? [])).toEqual([
+      0, 0, 0, 1, 0, 0, 0, 1, 0,
+    ]);
+    expect(Array.from(result.value.meshes[0]?.indices ?? [])).toEqual([0, 1, 2]);
+
+    const mesh = meshIrToMeshAsset(result.value.meshes);
+    expect([
+      mesh.vertices[0],
+      mesh.vertices[1],
+      mesh.vertices[2],
+      mesh.vertices[12],
+      mesh.vertices[13],
+      mesh.vertices[14],
+      mesh.vertices[24],
+      mesh.vertices[25],
+      mesh.vertices[26],
+    ]).toEqual([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+    expect(Array.from(mesh.indices ?? [])).toEqual([0, 1, 2]);
+  });
+
+  it('routes the same compressed source through the build-time importer capability', async () => {
+    await MeshoptEncoder.ready;
+    await MeshoptDecoder.ready;
+    const bytes = new Uint8Array(compressedGlb());
+    const context: ImportContext = {
+      source: 'meshopt-real.glb',
+      readSource: async () => ({ ok: true as const, value: bytes }),
+      readSibling: async () => {
+        throw new Error('the compressed fixture has no sibling buffers');
+      },
+      decodeImage: async () => {
+        throw new Error('the compressed fixture has no images');
+      },
+      subAssets: [
+        {
+          guid: '019f0000-0000-7000-8000-000000000201',
+          sourceIndex: 0,
+          kind: 'mesh',
+        },
+      ],
+      importSettings: {},
+    };
+    const result = await createGltfImporter(decoder()).import(context);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const mesh = result.value.assets.find((asset: { kind: string }) => asset.kind === 'mesh');
+    expect(mesh?.guid).toBe('019f0000-0000-7000-8000-000000000201');
+    expect(mesh?.payload.indices).toEqual(new Uint16Array([0, 1, 2]));
+  });
+
+  it('loads the imported compressed artifact through Pack, Catalog, and loadByGuid', async () => {
+    await MeshoptEncoder.ready;
+    await MeshoptDecoder.ready;
+    const guid = '019f0000-0000-7000-8000-000000000202';
+    const sourceBytes = new Uint8Array(compressedGlb());
+    const context: ImportContext = {
+      source: 'meshopt-pack.glb',
+      readSource: async () => ({ ok: true as const, value: sourceBytes }),
+      readSibling: async () => {
+        throw new Error('the compressed fixture has no sibling buffers');
+      },
+      decodeImage: async () => {
+        throw new Error('the compressed fixture has no images');
+      },
+      subAssets: [{ guid, sourceIndex: 0, kind: 'mesh' }],
+      importSettings: {},
+    };
+    const imported = await createGltfImporter(decoder()).import(context);
+    expect(imported.ok).toBe(true);
+    if (!imported.ok) return;
+    const mesh = imported.value.assets.find((asset: ImportedAsset) => asset.guid === guid);
+    expect(mesh?.kind).toBe('mesh');
+    if (mesh?.kind !== 'mesh') return;
+    const meshPayload = mesh.payload as Extract<Asset, { kind: 'mesh' }>;
+    const body = mesh.artifacts.body;
+    expect(body?.bytes.byteLength).toBeGreaterThan(0);
+    if (body === undefined) return;
+
+    const packIndexUrl = '/meshopt-pack-index.json';
+    const packageUrl = '/ddc/meshopt-pack.pack.json';
+    const originalFetch = globalThis.fetch;
+    const registry = new AssetRegistry({} as never);
+    registry.configurePackIndex(packIndexUrl);
+    globalThis.fetch = ((input: string) => {
+      const url = typeof input === 'string' ? input : String(input);
+      if (url === packIndexUrl) {
+        return Promise.resolve({
+          ok: true,
+          json: async () => [{ guid, packageUrl, kind: 'mesh' }],
+        });
+      }
+      if (url === packageUrl) {
+        const pack = {
+          schemaVersion: '2.0.0',
+          kind: 'internal-text-package',
+          assets: [
+            {
+              guid,
+              kind: 'mesh',
+              payload: meshPayload,
+              refs: [],
+              artifacts: {
+                body: {
+                  path: 'mesh.bin',
+                  mediaType: body.mediaType,
+                  byteLength: body.bytes.byteLength,
+                  assetCodec: body.assetCodec,
+                },
+              },
+            },
+          ],
+        };
+        return Promise.resolve({
+          ok: true,
+          json: async () => JSON.parse(JSON.stringify(pack)),
+        });
+      }
+      return Promise.resolve({
+        ok: true,
+        arrayBuffer: async () =>
+          body.bytes.buffer.slice(
+            body.bytes.byteOffset,
+            body.bytes.byteOffset + body.bytes.byteLength,
+          ),
+      });
+    }) as unknown as typeof globalThis.fetch;
+
+    try {
+      const loaded = await registry.loadByGuid(registry.parseGuid(guid));
+      expect(loaded.ok).toBe(true);
+      if (!loaded.ok) return;
+      const payload = loaded.value as { vertices: Float32Array; indices?: Uint16Array };
+      expect([
+        payload.vertices[0],
+        payload.vertices[1],
+        payload.vertices[2],
+        payload.vertices[12],
+        payload.vertices[13],
+        payload.vertices[14],
+        payload.vertices[24],
+        payload.vertices[25],
+        payload.vertices[26],
+      ]).toEqual([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+      expect(Array.from(payload.indices ?? [])).toEqual([0, 1, 2]);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('rejects a damaged compressed artifact after importer success', async () => {
+    await MeshoptEncoder.ready;
+    await MeshoptDecoder.ready;
+    const guid = '019f0000-0000-7000-8000-000000000203';
+    const sourceBytes = new Uint8Array(compressedGlb());
+    const context: ImportContext = {
+      source: 'meshopt-damaged.glb',
+      readSource: async () => ({ ok: true as const, value: sourceBytes }),
+      readSibling: async () => {
+        throw new Error('the compressed fixture has no sibling buffers');
+      },
+      decodeImage: async () => {
+        throw new Error('the compressed fixture has no images');
+      },
+      subAssets: [{ guid, sourceIndex: 0, kind: 'mesh' }],
+      importSettings: {},
+    };
+    const imported = await createGltfImporter(decoder()).import(context);
+    expect(imported.ok).toBe(true);
+    if (!imported.ok) return;
+    const mesh = imported.value.assets.find((asset: ImportedAsset) => asset.guid === guid);
+    if (mesh?.kind !== 'mesh' || mesh.artifacts.body === undefined) return;
+    const meshPayload = mesh.payload as Extract<Asset, { kind: 'mesh' }>;
+    const damaged = new Uint8Array(mesh.artifacts.body.bytes);
+    const lastByte = damaged.length - 1;
+    damaged[lastByte] = (damaged[lastByte] ?? 0) ^ 0xff;
+    const registry = new AssetRegistry({} as never);
+    const packIndexUrl = '/meshopt-damaged-index.json';
+    const packageUrl = '/ddc/meshopt-damaged.pack.json';
+    registry.configurePackIndex(packIndexUrl);
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = ((input: string) => {
+      const url = typeof input === 'string' ? input : String(input);
+      if (url === packIndexUrl)
+        return Promise.resolve({
+          ok: true,
+          json: async () => [{ guid, packageUrl, kind: 'mesh' }],
+        });
+      if (url === packageUrl)
+        return Promise.resolve({
+          ok: true,
+          json: async () => ({
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              {
+                guid,
+                kind: 'mesh',
+                payload: meshPayload,
+                refs: [],
+                artifacts: {
+                  body: {
+                    path: 'mesh.bin',
+                    mediaType: mesh.artifacts.body?.mediaType,
+                    byteLength: damaged.byteLength,
+                    assetCodec: mesh.artifacts.body?.assetCodec,
+                  },
+                },
+              },
+            ],
+          }),
+        });
+      return Promise.resolve({
+        ok: true,
+        arrayBuffer: async () =>
+          damaged.buffer.slice(damaged.byteOffset, damaged.byteOffset + damaged.byteLength),
+      });
+    }) as unknown as typeof globalThis.fetch;
+    try {
+      const loaded = await registry.loadByGuid(registry.parseGuid(guid));
+      expect(loaded.ok).toBe(false);
+      if (loaded.ok) return;
+      expect([
+        'asset-parse-failed',
+        'asset-artifact-integrity-mismatch',
+        'mesh-bin-contract-violation',
+      ]).toContain(loaded.error.code);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});

package/src/__tests__/morph-import.integration.test.ts

@@ -0,0 +1,115 @@
+import { readFile } from 'node:fs/promises';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { ImporterRegistry, type RunImportMeta, runImport } from '@forgeax/engine-import';
+import type { AnimationClip, MeshAsset, SceneAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { gltfImporter } from '../gltf-importer.js';
+
+const MESH_GUID = '11111111-1111-4111-8111-111111111111';
+const MATERIAL_GUID = '22222222-2222-4222-8222-222222222222';
+const SCENE_GUID = '33333333-3333-4333-8333-333333333333';
+const ANIMATION_GUID = '44444444-4444-4444-8444-444444444444';
+
+const sourceUrl = new URL(
+  '../../../../apps/hello/format-tier1/fixtures/animated-morph-cube.gltf',
+  import.meta.url,
+);
+
+function meta(): RunImportMeta {
+  return {
+    importer: 'gltf',
+    source: 'apps/hello/format-tier1/fixtures/animated-morph-cube.gltf',
+    subAssets: [
+      { guid: MESH_GUID, sourceIndex: 0, sourceKey: 'gltf:mesh:Cube', kind: 'mesh' },
+      {
+        guid: MATERIAL_GUID,
+        sourceIndex: 0,
+        sourceKey: 'gltf:material:Material',
+        kind: 'material',
+      },
+      { guid: SCENE_GUID, sourceIndex: 0, sourceKey: 'gltf:scene:default', kind: 'scene' },
+      {
+        guid: ANIMATION_GUID,
+        sourceIndex: 0,
+        sourceKey: 'gltf:animation:Square',
+        kind: 'animation-clip',
+      },
+    ],
+  };
+}
+
+async function importFixture() {
+  const bytes = new Uint8Array(await readFile(sourceUrl));
+  const registry = new ImporterRegistry();
+  registry.register(gltfImporter);
+  const fs = { readSource: async () => ({ ok: true as const, value: bytes }) };
+  const result = await runImport(meta(), registry, fs);
+  if (!result.ok) throw new Error(`glTF import failed: ${JSON.stringify(result.error)}`);
+  if ('skipped' in result.value) throw new Error('expected glTF DDC pack');
+  return result.value.pack;
+}
+
+describe('real glTF morph import through Pack and AssetRegistry', () => {
+  it('preserves two targets and two animation keyframes through loadByGuid', async () => {
+    const pack = await importFixture();
+    const meshEntry = pack.assets.find((asset) => asset.guid === MESH_GUID);
+    const sceneEntry = pack.assets.find((asset) => asset.guid === SCENE_GUID);
+    const animationEntry = pack.assets.find((asset) => asset.guid === ANIMATION_GUID);
+    expect(meshEntry?.kind).toBe('mesh');
+    expect(sceneEntry?.kind).toBe('scene');
+    expect(animationEntry?.kind).toBe('animation-clip');
+
+    const meshPayload = meshEntry?.payload as {
+      readonly vertices: number[];
+      readonly morphTargets?: readonly { readonly position?: number[] }[];
+      readonly morphWeights?: number[];
+    };
+    expect(meshPayload.morphTargets).toHaveLength(2);
+    expect(meshPayload.morphTargets?.every((target) => target.position?.length === 24 * 3)).toBe(
+      true,
+    );
+    expect(meshPayload.morphTargets?.[0]?.position?.some((value) => value !== 0)).toBe(true);
+    expect(meshPayload.morphTargets?.[1]?.position?.some((value) => value !== 0)).toBe(true);
+    expect(meshPayload.morphWeights).toEqual([0, 0]);
+
+    const animationPayload = animationEntry?.payload as {
+      readonly channels: readonly {
+        readonly property: string;
+        readonly sampler: { readonly input: readonly number[]; readonly output: readonly number[] };
+      }[];
+    };
+    expect(animationPayload.channels).toHaveLength(1);
+    expect(animationPayload.channels[0]?.property).toBe('weights');
+    expect(animationPayload.channels[0]?.sampler.input).toEqual([0, 1]);
+    expect(animationPayload.channels[0]?.sampler.output).toEqual([0, 0.75, 0.25, 0]);
+
+    const runtime = new AssetRegistry({} as never);
+    const parsedMesh = runtime.parseAssetPayload('mesh', meshEntry?.payload ?? {});
+    const parsedAnimation = runtime.parseAssetPayload(
+      'animation-clip',
+      animationEntry?.payload ?? {},
+    );
+    expect(parsedMesh).toMatchObject({ kind: 'mesh', morphWeights: new Float32Array([0, 0]) });
+    expect(parsedAnimation).toMatchObject({ kind: 'animation-clip' });
+    expect(runtime.catalog(MESH_GUID, parsedMesh as never).ok).toBe(true);
+    expect(runtime.catalog(SCENE_GUID, sceneEntry?.payload as never).ok).toBe(true);
+    expect(runtime.catalog(ANIMATION_GUID, parsedAnimation as never).ok).toBe(true);
+
+    const loadedMesh = await runtime.loadByGuid<MeshAsset>(runtime.parseGuid(MESH_GUID));
+    const loadedScene = await runtime.loadByGuid<SceneAsset>(runtime.parseGuid(SCENE_GUID));
+    const loadedAnimation = await runtime.loadByGuid<AnimationClip>(
+      runtime.parseGuid(ANIMATION_GUID),
+    );
+    expect(loadedMesh.ok).toBe(true);
+    expect(loadedScene.ok).toBe(true);
+    expect(loadedAnimation.ok).toBe(true);
+    if (!loadedMesh.ok || !loadedScene.ok || !loadedAnimation.ok) return;
+    expect(Array.from(loadedMesh.value.morphWeights ?? [])).toEqual([0, 0]);
+    const sceneEntity = loadedScene.value.entities[0];
+    expect(sceneEntity?.components.MorphWeights?.weights).toEqual([0, 0]);
+    expect(loadedAnimation.value.channels[0]?.property).toBe('weights');
+    expect(Array.from(loadedAnimation.value.channels[0]?.sampler.output ?? [])).toEqual([
+      0, 0.75, 0.25, 0,
+    ]);
+  });
+});

package/src/__tests__/morph-import.unit.test.ts

@@ -0,0 +1,62 @@
+import { Buffer } from 'node:buffer';
+import { describe, expect, it } from 'vitest';
+import { parseGltf } from '../parse-gltf.js';
+import { unwrapMeshAsset as meshIrToMeshAsset } from './bridge-test-helpers.js';
+
+function documentWithMorph(targetAccessor: number | object = 1) {
+  const values = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1.25, 0, 0, 0, 1, 0]);
+  const uri = `data:application/octet-stream;base64,${Buffer.from(values.buffer).toString('base64')}`;
+  return {
+    asset: { version: '2.0' },
+    buffers: [{ uri, byteLength: values.byteLength }],
+    bufferViews: [
+      { buffer: 0, byteOffset: 0, byteLength: 36 },
+      { buffer: 0, byteOffset: 36, byteLength: 36 },
+    ],
+    accessors: [
+      { bufferView: 0, componentType: 5126, count: 3, type: 'VEC3' },
+      { bufferView: 1, componentType: 5126, count: 3, type: 'VEC3' },
+    ],
+    meshes: [
+      {
+        weights: [0.25],
+        primitives: [{ attributes: { POSITION: 0 }, targets: [{ POSITION: targetAccessor }] }],
+      },
+    ],
+    nodes: [{ mesh: 0 }],
+    scenes: [{ nodes: [0] }],
+    scene: 0,
+  };
+}
+
+describe('glTF morph target import', () => {
+  it('projects additive POSITION deltas and default weights into MeshAsset', async () => {
+    const parsed = await parseGltf(
+      documentWithMorph(),
+      async () => new ArrayBuffer(0),
+      'morph.gltf',
+    );
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    const first = parsed.value.meshes[0];
+    expect(first).toBeDefined();
+    if (first === undefined) return;
+    const mesh = meshIrToMeshAsset([first]);
+    const morphMesh = mesh as typeof mesh & {
+      readonly morphTargets?: readonly { readonly position?: Float32Array }[];
+      readonly morphWeights?: Float32Array;
+    };
+    expect(morphMesh.morphTargets?.[0]?.position?.[3]).toBeCloseTo(1.25);
+    expect(Array.from(morphMesh.morphWeights ?? [])).toEqual([0.25]);
+  });
+
+  it('returns a structured morph error for a missing target accessor', async () => {
+    const parsed = await parseGltf(
+      documentWithMorph(99),
+      async () => new ArrayBuffer(0),
+      'morph.gltf',
+    );
+    expect(parsed.ok).toBe(false);
+    if (!parsed.ok) expect(parsed.error.code).toBe('gltf-morph-invalid');
+  });
+});