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

package/src/__tests__/malformed-buffer-data-uri.integration.test.ts

@@ -0,0 +1,140 @@
+import {
+  ImporterRegistry,
+  type ImportRunnerFs,
+  type RunImportMeta,
+  runImport,
+} from '@forgeax/engine-import';
+import type { ImportContext } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { extractImageBytes } from '../extract-image-bytes.js';
+import { gltfImporter } from '../gltf-importer.js';
+import { parseGltfForImporter } from '../parse-gltf.js';
+
+const SOURCE = 'malformed-buffer.gltf';
+const MESH_GUID = '019f0000-0000-7000-8000-000000000088';
+
+const meta: RunImportMeta = {
+  importer: 'gltf',
+  source: SOURCE,
+  subAssets: [{ guid: MESH_GUID, sourceIndex: 0, sourceKey: 'mesh', kind: 'mesh' }],
+};
+
+function dataUri(bytes: Uint8Array): string {
+  return `data:application/octet-stream;base64,${btoa(
+    Array.from(bytes, (byte) => String.fromCharCode(byte)).join(''),
+  )}`;
+}
+
+function sourceBytes(bufferUri: string): Uint8Array {
+  return new TextEncoder().encode(
+    JSON.stringify({
+      asset: { version: '2.0' },
+      buffers: [{ uri: bufferUri, byteLength: 36 }],
+      bufferViews: [{ buffer: 0, byteOffset: 0, byteLength: 36 }],
+      accessors: [{ bufferView: 0, componentType: 5126, count: 3, type: 'VEC3' }],
+      meshes: [{ primitives: [{ attributes: { POSITION: 0 } }] }],
+      nodes: [],
+      scenes: [],
+    }),
+  );
+}
+
+function sourceFs(initialSource: Uint8Array): {
+  readonly fs: ImportRunnerFs;
+  setSource(source: Uint8Array): void;
+} {
+  let source = initialSource;
+  return {
+    fs: {
+      readSource: async (sourcePath) =>
+        sourcePath === SOURCE
+          ? { ok: true as const, value: source }
+          : { ok: false as const, error: new Error(`unexpected source path ${sourcePath}`) },
+    },
+    setSource(nextSource) {
+      source = nextSource;
+    },
+  };
+}
+
+describe('malformed glTF buffer data URI recovery', () => {
+  it('returns structured refusal, then retries the same registry and GUIDs exactly', async () => {
+    const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+    const validSource = sourceBytes(dataUri(new Uint8Array(positions.buffer)));
+    const malformedSource = sourceBytes('data:application/octet-stream;base64,%%%%');
+    const source = sourceFs(malformedSource);
+    const registry = new ImporterRegistry();
+    registry.register(gltfImporter);
+
+    const parsed = await parseGltfForImporter(
+      JSON.parse(new TextDecoder().decode(malformedSource)) as object,
+      async () => new ArrayBuffer(0),
+      SOURCE,
+    );
+    expect(parsed.ok).toBe(false);
+    if (!parsed.ok) expect(parsed.error.code).toBe('source-validation-failed');
+
+    const failed = await runImport(meta, registry, source.fs);
+    expect(failed.ok).toBe(false);
+    expect(failed).not.toHaveProperty('value');
+    if (!failed.ok) {
+      expect(failed.error.code).toBe('source-validation-failed');
+      expect(failed.error.detail).toMatchObject({
+        diagnostics: [
+          expect.objectContaining({
+            code: 'gltf-buffer-data-uri-invalid',
+            sourcePath: SOURCE,
+          }),
+        ],
+      });
+    }
+
+    source.setSource(validSource);
+    const repaired = await runImport(meta, registry, source.fs);
+    expect(repaired.ok).toBe(true);
+    if (!repaired.ok || 'skipped' in repaired.value)
+      throw new Error('repaired import must publish a Pack');
+    expect(repaired.value.pack.assets).toHaveLength(1);
+    expect(repaired.value.cookProducts).toHaveLength(1);
+
+    const retried = await runImport(meta, registry, source.fs);
+    expect(retried.ok).toBe(true);
+    if (!retried.ok || 'skipped' in retried.value)
+      throw new Error('same-registry retry must publish a Pack');
+    expect(retried.value.pack).toEqual(repaired.value.pack);
+    expect(retried.value.cookProducts).toEqual(repaired.value.cookProducts);
+    expect(registry.registeredImporters()).toEqual(['gltf']);
+  });
+
+  it('turns a malformed bufferView image data URI into an extraction failure', async () => {
+    const source = new TextEncoder().encode(
+      JSON.stringify({
+        asset: { version: '2.0' },
+        buffers: [{ uri: 'data:application/octet-stream;base64,%%%%', byteLength: 4 }],
+        bufferViews: [{ buffer: 0, byteOffset: 0, byteLength: 4 }],
+        images: [{ bufferView: 0, mimeType: 'image/png' }],
+      }),
+    );
+    const context: ImportContext = {
+      source: 'image-buffer.gltf',
+      readSource: async () => ({ ok: true as const, value: source }),
+      readSibling: async () => ({ ok: true as const, value: new Uint8Array() }),
+      decodeImage: async () => {
+        throw new Error('decodeImage should not run for a failed extraction');
+      },
+      subAssets: [],
+      importSettings: {},
+    };
+
+    const result = await extractImageBytes(source, context.source, context);
+
+    expect(result.extracted.size).toBe(0);
+    expect(result.failures).toEqual([
+      {
+        imageIndex: 0,
+        source: 'bufferView',
+        reason: expect.stringContaining('buffer 0 data URI base64 decode failed'),
+      },
+    ]);
+  });
+});

package/src/__tests__/material-missing-uv.unit.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { validateMaterialUvSets } from '../bridge.js';
+import type { GltfMaterialIr } from '../parse-gltf.js';
+
+describe('glTF material UV validation', () => {
+  it('returns structured failure without a material product when a requested set is absent', () => {
+    const result = validateMaterialUvSets(
+      {
+        name: 'MissingUvMaterial',
+        baseColorFactor: [1, 1, 1, 1],
+        metallicFactor: 1,
+        roughnessFactor: 1,
+        baseColorTexture: { texture: 0, texCoord: 2 },
+      } as unknown as GltfMaterialIr,
+      'primitive-3',
+      [0, 1],
+    );
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('gltf-material-uv-set-missing');
+    expect(result.error.detail).toEqual({
+      material: 'MissingUvMaterial',
+      primitive: 'primitive-3',
+      slot: 'baseColorTexture',
+      requestedSet: 2,
+      availableSets: [0, 1],
+    });
+  });
+});

package/src/__tests__/material-pack-refs.integration.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { materialRefsForPack } from '../gltf-importer.js';
+import type { GltfDoc, GltfMaterialIr } from '../parse-gltf.js';
+
+describe('glTF material Pack refs', () => {
+  it('emits texture and sampler dependencies for every material slot', () => {
+    const material = {
+      name: 'PackMaterial',
+      baseColorFactor: [1, 1, 1, 1],
+      metallicFactor: 1,
+      roughnessFactor: 1,
+      baseColorTexture: { texture: 0, sampler: 0 },
+      metallicRoughnessTexture: { texture: 1, sampler: 1 },
+      normalTexture: { texture: 2, sampler: 2 },
+      occlusionTexture: { texture: 3, sampler: 3 },
+      emissiveTexture: { texture: 4, sampler: 4 },
+    } as unknown as GltfMaterialIr;
+    const doc = {
+      textures: [
+        { source: 0, sampler: 0 },
+        { source: 1, sampler: 1 },
+        { source: 2, sampler: 2 },
+        { source: 3, sampler: 3 },
+        { source: 4, sampler: 4 },
+      ],
+    } as unknown as GltfDoc;
+    const refs = materialRefsForPack(
+      material,
+      doc,
+      new Map([
+        [0, 'texture-0'],
+        [1, 'texture-1'],
+        [2, 'texture-2'],
+        [3, 'texture-3'],
+        [4, 'texture-4'],
+      ]),
+      new Map([
+        [0, 'sampler-0'],
+        [1, 'sampler-1'],
+        [2, 'sampler-2'],
+        [3, 'sampler-3'],
+        [4, 'sampler-4'],
+      ]),
+    );
+    expect(refs.map((ref) => ref.guid)).toEqual([
+      'texture-0',
+      'sampler-0',
+      'texture-1',
+      'sampler-1',
+      'texture-2',
+      'sampler-2',
+      'texture-3',
+      'sampler-3',
+      'texture-4',
+      'sampler-4',
+    ]);
+  });
+});

package/src/__tests__/material-per-slot-ir.unit.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import { parseGltf } from '../parse-gltf.js';
+
+const noopLoader = async (_uri: string) => new ArrayBuffer(0);
+
+describe('glTF per-slot material IR', () => {
+  it('keeps texture, sampler, coordinates, transform, and slot scalars independent', async () => {
+    const result = await parseGltf(
+      {
+        asset: { version: '2.0' },
+        textures: [
+          { source: 0, sampler: 0 },
+          { source: 1, sampler: 1 },
+          { source: 2, sampler: 2 },
+          { source: 3, sampler: 3 },
+          { source: 4, sampler: 4 },
+        ],
+        materials: [
+          {
+            pbrMetallicRoughness: {
+              baseColorTexture: {
+                index: 0,
+                texCoord: 1,
+                extensions: {
+                  KHR_texture_transform: {
+                    offset: [0.1, 0.2],
+                    rotation: 0.3,
+                    scale: [1.1, 1.2],
+                  },
+                },
+              },
+              metallicRoughnessTexture: { index: 1, texCoord: 2 },
+            },
+            normalTexture: {
+              index: 2,
+              texCoord: 3,
+              scale: 0.7,
+              extensions: {
+                KHR_texture_transform: {
+                  offset: [0.4, 0.5],
+                  rotation: 0.6,
+                  scale: [1.4, 1.5],
+                },
+              },
+            },
+            occlusionTexture: { index: 3, texCoord: 4, strength: 0.8 },
+            emissiveTexture: { index: 4, texCoord: 5 },
+          },
+        ],
+      },
+      noopLoader,
+      '/per-slot.gltf',
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const material = result.value.materials[0] as unknown as Record<string, unknown>;
+    expect(material.baseColorTexture).toEqual({
+      texture: 0,
+      sampler: 0,
+      texCoord: 1,
+      transform: { offset: [0.1, 0.2], rotation: 0.3, scale: [1.1, 1.2] },
+    });
+    expect(material.metallicRoughnessTexture).toEqual({
+      texture: 1,
+      sampler: 1,
+      texCoord: 2,
+    });
+    expect(material.normalTexture).toEqual({
+      texture: 2,
+      sampler: 2,
+      texCoord: 3,
+      transform: { offset: [0.4, 0.5], rotation: 0.6, scale: [1.4, 1.5] },
+      scale: 0.7,
+    });
+    expect(material.occlusionTexture).toEqual({
+      texture: 3,
+      sampler: 3,
+      texCoord: 4,
+      strength: 0.8,
+    });
+    expect(material.emissiveTexture).toEqual({
+      texture: 4,
+      sampler: 4,
+      texCoord: 5,
+    });
+    expect(material.coordinatesSet).toBeUndefined();
+  });
+});

package/src/__tests__/material-texture-transform.unit.test.ts

@@ -0,0 +1,105 @@
+import type { Handle } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { toMaterialAsset } from '../bridge.js';
+import { parseGltf } from '../parse-gltf.js';
+
+const noopLoader = async (_uri: string) => new ArrayBuffer(0);
+
+describe('glTF KHR_texture_transform per-slot parsing', () => {
+  it('keeps transform and texCoord override attached to each texture slot', async () => {
+    const result = await parseGltf(
+      {
+        asset: { version: '2.0' },
+        extensionsRequired: ['KHR_texture_transform'],
+        extensionsUsed: ['KHR_texture_transform'],
+        textures: [
+          { source: 0, sampler: 0 },
+          { source: 1, sampler: 1 },
+        ],
+        materials: [
+          {
+            pbrMetallicRoughness: {
+              baseColorTexture: {
+                index: 0,
+                texCoord: 0,
+                extensions: {
+                  KHR_texture_transform: {
+                    texCoord: 6,
+                    offset: [0.25, 0.5],
+                    rotation: 0.75,
+                    scale: [2, 3],
+                  },
+                },
+              },
+              metallicRoughnessTexture: {
+                index: 1,
+                texCoord: 1,
+                extensions: {
+                  KHR_texture_transform: {
+                    texCoord: 7,
+                    offset: [-0.25, -0.5],
+                    rotation: -0.75,
+                    scale: [4, 5],
+                  },
+                },
+              },
+            },
+          },
+        ],
+      },
+      noopLoader,
+      '/texture-transform.gltf',
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const material = result.value.materials[0] as unknown as Record<
+      string,
+      { texCoord?: number; transform?: Record<string, unknown> } | undefined
+    >;
+    if (
+      material.baseColorTexture === undefined ||
+      material.metallicRoughnessTexture === undefined
+    ) {
+      throw new Error('expected textured material slots');
+    }
+    expect(material.baseColorTexture.texCoord).toBe(6);
+    expect(material.baseColorTexture.transform).toEqual({
+      offset: [0.25, 0.5],
+      rotation: 0.75,
+      scale: [2, 3],
+    });
+    expect(material.metallicRoughnessTexture.texCoord).toBe(7);
+    expect(material.metallicRoughnessTexture.transform).toEqual({
+      offset: [-0.25, -0.5],
+      rotation: -0.75,
+      scale: [4, 5],
+    });
+
+    const materialIr = result.value.materials[0];
+    expect(materialIr).toBeDefined();
+    if (materialIr === undefined) return;
+    const projected = toMaterialAsset(materialIr, {
+      textureHandles: new Map([
+        [0, 100],
+        [1, 101],
+      ]) as unknown as ReadonlyMap<number, Handle<'TextureAsset', 'shared'>>,
+    });
+    expect(projected.values).toMatchObject({
+      baseColorTexture: {
+        texture: 100,
+        coordinates: {
+          set: 6,
+          transform: { offset: [0.25, 0.5], rotation: 0.75, scale: [2, 3] },
+        },
+      },
+      metallicRoughnessTexture: {
+        texture: 101,
+        coordinates: {
+          set: 7,
+          transform: { offset: [-0.25, -0.5], rotation: -0.75, scale: [4, 5] },
+        },
+      },
+    });
+  });
+});

package/src/__tests__/material-unused-uv.unit.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { parseGltf } from '../parse-gltf.js';
+
+const noopLoader = async (_uri: string) => new ArrayBuffer(0);
+
+const positionBytes = new Float32Array([0, 0, 0]);
+const uvBytes = new Float32Array([0, 0]);
+const positionBase64 = Buffer.from(positionBytes.buffer).toString('base64');
+const uvBase64 = Buffer.from(uvBytes.buffer).toString('base64');
+
+describe('glTF unused UV sets', () => {
+  it('preserves mesh UV sets that no material slot consumes', async () => {
+    const result = await parseGltf(
+      {
+        asset: { version: '2.0' },
+        meshes: [{ primitives: [{ attributes: { POSITION: 0, TEXCOORD_0: 1, TEXCOORD_3: 2 } }] }],
+        buffers: [
+          { uri: `data:application/octet-stream;base64,${positionBase64}`, byteLength: 12 },
+          { uri: `data:application/octet-stream;base64,${uvBase64}`, byteLength: 8 },
+          { uri: `data:application/octet-stream;base64,${uvBase64}`, byteLength: 8 },
+        ],
+        bufferViews: [
+          { buffer: 0, byteOffset: 0, byteLength: 12 },
+          { buffer: 1, byteOffset: 0, byteLength: 8 },
+          { buffer: 2, byteOffset: 0, byteLength: 8 },
+        ],
+        accessors: [
+          { bufferView: 0, componentType: 5126, count: 1, type: 'VEC3' },
+          { bufferView: 1, componentType: 5126, count: 1, type: 'VEC2' },
+          { bufferView: 2, componentType: 5126, count: 1, type: 'VEC2' },
+        ],
+        materials: [{ pbrMetallicRoughness: { baseColorFactor: [1, 1, 1, 1] } }],
+      },
+      noopLoader,
+      '/unused-uv.gltf',
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.meshes[0]?.texcoord3).toBeInstanceOf(Float32Array);
+    expect(
+      (result.value.materials[0] as unknown as Record<string, unknown>).coordinatesSet,
+    ).toBeUndefined();
+  });
+});

package/src/__tests__/meshopt-decode.unit.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+import { projectMeshoptBufferViews } from '../meshopt-decode.js';
+
+function compressedView(overrides: Record<string, unknown> = {}) {
+  return {
+    buffer: 0,
+    byteOffset: 0,
+    byteLength: 8,
+    extensions: {
+      EXT_meshopt_compression: {
+        buffer: 1,
+        byteOffset: 2,
+        byteLength: 4,
+        byteStride: 4,
+        count: 2,
+        mode: 'ATTRIBUTES' as const,
+        ...overrides,
+      },
+    },
+  };
+}
+
+describe('EXT_meshopt_compression projection', () => {
+  it('decodes the declared compressed range and replaces the view exactly once', async () => {
+    const source = new Uint8Array([9, 9, 1, 2, 3, 4, 9]);
+    const calls: Array<{ source: Uint8Array; count: number; stride: number }> = [];
+    const result = await projectMeshoptBufferViews(
+      [compressedView()],
+      [new Uint8Array(8), source],
+      ['EXT_meshopt_compression'],
+      {
+        decode(input) {
+          calls.push(input);
+          return new Uint8Array(input.count * input.stride);
+        },
+      },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.source).toEqual(new Uint8Array([1, 2, 3, 4]));
+    if (result.ok) {
+      expect(result.value.decodedCount).toBe(1);
+      expect(result.value.bufferViews[0]).toMatchObject({
+        buffer: 2,
+        byteOffset: 0,
+        byteLength: 8,
+      });
+      expect(result.value.bufferViews[0]).not.toHaveProperty('extensions');
+      expect(result.value.buffers[2]).toHaveLength(8);
+    }
+  });
+
+  it('preserves an optional core fallback without touching compressed bytes', async () => {
+    const result = await projectMeshoptBufferViews(
+      [compressedView()],
+      [new Uint8Array(8), new Uint8Array([1, 2, 3, 4])],
+      [],
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.decodedCount).toBe(0);
+      expect(result.value.bufferViews[0]?.buffer).toBe(0);
+    }
+  });
+
+  it('supports triangle and index streams through the same capability seam', async () => {
+    const modes = ['TRIANGLES', 'INDICES'] as const;
+    const seen: string[] = [];
+    for (const mode of modes) {
+      const result = await projectMeshoptBufferViews(
+        [compressedView({ mode, byteStride: 2, count: 6 })],
+        [new Uint8Array(12), new Uint8Array(8)],
+        ['EXT_meshopt_compression'],
+        {
+          decode(input) {
+            seen.push(`${input.mode}:${input.filter}`);
+            return new Uint8Array(input.count * input.stride);
+          },
+        },
+      );
+      expect(result.ok).toBe(true);
+    }
+    expect(seen).toEqual(['TRIANGLES:NONE', 'INDICES:NONE']);
+  });
+});

package/src/__tests__/meshopt-falsifier.unit.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest';
+import type { MeshoptBufferViewJson } from '../meshopt-decode.js';
+import { projectMeshoptBufferViews } from '../meshopt-decode.js';
+
+function view(extension: Record<string, unknown>, coreByteLength = 0) {
+  return [
+    {
+      buffer: 0,
+      byteLength: coreByteLength,
+      extensions: { EXT_meshopt_compression: extension },
+    },
+  ] as unknown as MeshoptBufferViewJson[];
+}
+
+const baseExtension = {
+  buffer: 1,
+  byteOffset: 0,
+  byteLength: 4,
+  byteStride: 4,
+  count: 2,
+  mode: 'ATTRIBUTES',
+};
+
+describe('EXT_meshopt_compression falsifiers', () => {
+  it('fails closed when required compressed data has no decoder', async () => {
+    const result = await projectMeshoptBufferViews(
+      view(baseExtension),
+      [new Uint8Array(0), new Uint8Array(4)],
+      ['EXT_meshopt_compression'],
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok && result.error.code === 'gltf-meshopt-decoder-required') {
+      expect(result.error.code).toBe('gltf-meshopt-decoder-required');
+      expect(result.error.detail.actual).toBe('required');
+      expect(result.error.detail.hasCoreFallback).toBe(false);
+    }
+  });
+
+  it('rejects an out-of-range compressed payload before invoking the decoder', async () => {
+    let called = false;
+    const result = await projectMeshoptBufferViews(
+      view({ ...baseExtension, byteOffset: 3, byteLength: 4 }),
+      [new Uint8Array(0), new Uint8Array(4)],
+      ['EXT_meshopt_compression'],
+      {
+        decode() {
+          called = true;
+          return new Uint8Array(8);
+        },
+      },
+    );
+
+    expect(result.ok).toBe(false);
+    expect(called).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('gltf-meshopt-decode-failed');
+  });
+
+  it('rejects invalid mode/filter/count/stride declarations', async () => {
+    const invalidCases = [
+      { mode: 'NOT_A_MODE' },
+      { filter: 'NOT_A_FILTER' },
+      { count: 0 },
+      { byteStride: 0 },
+    ];
+    for (const mutation of invalidCases) {
+      const result = await projectMeshoptBufferViews(
+        view({ ...baseExtension, ...mutation }),
+        [new Uint8Array(0), new Uint8Array(4)],
+        ['EXT_meshopt_compression'],
+        { decode: () => new Uint8Array(8) },
+      );
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.code).toBe('gltf-meshopt-decode-failed');
+    }
+  });
+
+  it('rejects a decoder result whose byte length disagrees with count times stride', async () => {
+    const result = await projectMeshoptBufferViews(
+      view(baseExtension),
+      [new Uint8Array(0), new Uint8Array(4)],
+      ['EXT_meshopt_compression'],
+      { decode: () => new Uint8Array(7) },
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok && result.error.code === 'gltf-meshopt-decode-failed') {
+      expect(result.error.code).toBe('gltf-meshopt-decode-failed');
+      expect(result.error.detail.actual).toContain('expected=8');
+    }
+  });
+});