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

package/src/__tests__/cli-gltf.integration.test.ts

@@ -0,0 +1,122 @@
+// packages/gltf/src/__tests__/cli-gltf.integration.test.ts
+//
+// Integration test: run `forgeax-engine-remote-gltf import` against real
+// glTF files and verify the written .meta.json sidecar contains texture
+// sub-assets (feat-20260608 M6 w29 AC-18).
+//
+// Uses the BoxTextured fixture from forgeax-engine-assets.
+
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { runCliGltf } from '../cli-gltf.js';
+
+interface CapturedIO {
+  stdout: string[];
+  stderr: string[];
+}
+
+function makeIO(): CapturedIO {
+  return { stdout: [], stderr: [] };
+}
+
+function ctxFor(io: CapturedIO) {
+  return {
+    stdoutWrite: (line: string): void => {
+      io.stdout.push(line);
+    },
+    stderrWrite: (line: string): void => {
+      io.stderr.push(line);
+    },
+  };
+}
+
+describe('cli-gltf integration (AC-18)', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'gltf-cli-int-'));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('produces texture sub-assets in .meta.json for BoxTextured.gltf (external-uri)', async () => {
+    const assetsDir = join(
+      dirname(fileURLToPath(import.meta.url)),
+      '../../../../../forgeax-engine-assets/khronos-gltf-samples',
+    );
+    const gltfDir = join(assetsDir, 'BoxTextured', 'glTF');
+    const sourcePath = join(gltfDir, 'BoxTextured.gltf');
+
+    // Verify the fixture exists.
+    let fileStats: { isFile(): boolean } | undefined;
+    try {
+      fileStats = await stat(sourcePath);
+    } catch {
+      // Fixture not available; skip the test.
+      return;
+    }
+    expect(fileStats.isFile()).toBe(true);
+
+    // Symlink the fixture into a temp dir so the sidecar is written there.
+    const dest = join(tempDir, 'BoxTextured.gltf');
+    await writeFile(dest, await readFile(sourcePath));
+    // Also copy sibling .bin and .png files needed for parseGltf.
+    for (const siblingName of ['BoxTextured.bin', 'CesiumLogoFlat.png']) {
+      const src = join(gltfDir, siblingName);
+      try {
+        await stat(src);
+        await writeFile(join(tempDir, siblingName), await readFile(src));
+      } catch {
+        // Skip if missing.
+      }
+    }
+
+    const io = makeIO();
+    const code = await runCliGltf(['import', dest], ctxFor(io));
+    expect(code).toBe(0);
+
+    const metaPath = `${dest}.meta.json`;
+    const metaRaw = await readFile(metaPath, 'utf-8');
+    const meta = JSON.parse(metaRaw) as { subAssets?: Array<{ kind: string }> };
+    expect(meta.subAssets).toBeDefined();
+
+    const kinds = meta.subAssets?.map((s) => s.kind) ?? [];
+    expect(kinds).toContain('texture');
+  });
+
+  it('produces texture sub-assets in .meta.json for BoxTextured.glb (bufferView)', async () => {
+    const assetsDir = join(
+      dirname(fileURLToPath(import.meta.url)),
+      '../../../../../forgeax-engine-assets/khronos-gltf-samples',
+    );
+    const sourcePath = join(assetsDir, 'BoxTextured', 'BoxTextured.glb');
+
+    let fileStatsForGlb: { isFile(): boolean } | undefined;
+    try {
+      fileStatsForGlb = await stat(sourcePath);
+    } catch {
+      return;
+    }
+    expect(fileStatsForGlb.isFile()).toBe(true);
+
+    const destGlb = join(tempDir, 'BoxTextured.glb');
+    await writeFile(destGlb, await readFile(sourcePath));
+
+    const io = makeIO();
+    const code = await runCliGltf(['import', destGlb], ctxFor(io));
+    expect(code).toBe(0);
+
+    const metaPath = `${destGlb}.meta.json`;
+    const metaRaw = await readFile(metaPath, 'utf-8');
+    const meta = JSON.parse(metaRaw) as { subAssets?: Array<{ kind: string }> };
+    expect(meta.subAssets).toBeDefined();
+
+    const kinds = meta.subAssets?.map((s) => s.kind) ?? [];
+    expect(kinds).toContain('texture');
+  });
+});

package/src/__tests__/color-0-accessor.unit.test.ts

@@ -0,0 +1,174 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { decodeColorAccessor } from '../accessor/decode-color.js';
+import { dataUriBase64Payload, decodeBase64 } from '../data-uri.js';
+
+type Fixture = {
+  readonly buffers: readonly { readonly uri: string; readonly byteLength: number }[];
+  readonly bufferViews: readonly {
+    readonly buffer: number;
+    readonly byteLength: number;
+    readonly byteOffset?: number;
+    readonly byteStride?: number;
+  }[];
+  readonly accessors: readonly {
+    readonly bufferView: number;
+    readonly byteOffset?: number;
+    readonly componentType: number;
+    readonly count: number;
+    readonly normalized?: boolean;
+    readonly type: string;
+    readonly sparse?: unknown;
+  }[];
+};
+
+type ColorError = {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly semantic: string;
+    readonly accessorIndex: number;
+    readonly reason: string;
+  };
+};
+
+function readFixture(name: string): Fixture {
+  const url = new URL(`./fixtures/color-0/${name}.gltf`, import.meta.url);
+  return JSON.parse(readFileSync(url, 'utf8')) as Fixture;
+}
+
+function inputFor(name: string, accessorIndex = 0) {
+  const fixture = readFixture(name);
+  const accessor = fixture.accessors[accessorIndex];
+  if (accessor === undefined) throw new Error(`missing fixture accessor ${accessorIndex}`);
+  const view = fixture.bufferViews[accessor.bufferView ?? -1];
+  if (view === undefined) throw new Error(`missing fixture bufferView ${accessor.bufferView}`);
+  const source = fixture.buffers[view.buffer];
+  if (source === undefined) throw new Error(`missing fixture buffer ${view.buffer}`);
+  const payload = dataUriBase64Payload(source.uri);
+  if (payload === undefined) throw new Error('fixture buffer must be a base64 data URI');
+  return {
+    accessorIndex,
+    accessor,
+    bufferView: view,
+    buffer: decodeBase64(payload),
+    semantic: 'COLOR_0' as const,
+    bufferIndex: view.buffer,
+  };
+}
+
+function expectColorError(result: unknown, code: string, reason: string, accessorIndex: number) {
+  expect(result).toMatchObject({ ok: false });
+  if (typeof result !== 'object' || result === null || !('ok' in result) || result.ok) {
+    throw new Error('expected a structured color error');
+  }
+  const error = (result as unknown as { readonly error: ColorError }).error;
+  expect(error.code).toBe(code);
+  expect(error.expected).toEqual(expect.any(String));
+  expect(error.hint).toEqual(expect.any(String));
+  expect(error.detail).toMatchObject({ semantic: 'COLOR_0', accessorIndex, reason });
+}
+
+describe('COLOR_0 accessor support matrix', () => {
+  function expectFloat32Values(actual: Float32Array, expected: readonly number[]) {
+    expect(actual).toHaveLength(expected.length);
+    expected.forEach((value, index) => {
+      expect(actual[index]).toBeCloseTo(value, 6);
+    });
+  }
+
+  it('decodes VEC3 FLOAT and supplies alpha=1, including endpoint and midpoint values', () => {
+    const result = decodeColorAccessor(inputFor('float-vec3', 1));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(Array.from(result.value)).toEqual([0, 0.5, 1, 1, 1, 0.25, 0, 1]);
+  });
+
+  it('decodes normalized UBYTE VEC4 to linear RGBA endpoints and midpoint', () => {
+    const result = decodeColorAccessor(inputFor('normalized-ubyte'));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expectFloat32Values(result.value, [0, 128 / 255, 1, 64 / 255, 1, 32 / 255, 128 / 255, 1]);
+  });
+
+  it('decodes normalized USHORT VEC4 without sRGB conversion', () => {
+    const result = decodeColorAccessor(inputFor('normalized-ushort'));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expectFloat32Values(result.value, [
+      0,
+      32768 / 65535,
+      1,
+      16384 / 65535,
+      1,
+      8192 / 65535,
+      49152 / 65535,
+      1,
+    ]);
+  });
+
+  it('walks each element of a valid interleaved byteStride', () => {
+    const result = decodeColorAccessor(inputFor('interleaved-vec3'));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(Array.from(result.value)).toEqual([0, 0.25, 1, 1, 1, 0.5, 0, 1]);
+  });
+
+  it.each([
+    ['component', { componentType: 5120 }],
+    ['type', { type: 'VEC2' }],
+    ['normalized', { normalized: false }],
+  ] as const)('classifies unsupported %s as unsupported, not absent', (reason, patch) => {
+    const base = inputFor('float-vec3', 1);
+    const result = decodeColorAccessor({ ...base, accessor: { ...base.accessor, ...patch } });
+    expectColorError(result, 'gltf-color-accessor-unsupported', reason, 1);
+  });
+
+  it.each([
+    ['count', { count: 0 }],
+    ['bounds', { byteOffset: 20 }],
+    ['range', { byteOffset: 0 }],
+  ] as const)('classifies malformed %s with accessor context', (reason, patch) => {
+    const base = inputFor('float-vec3', 1);
+    const accessor = { ...base.accessor, ...patch };
+    if (reason === 'range') {
+      const bytes = base.buffer.slice();
+      new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).setFloat32(24, 2, true);
+      const result = decodeColorAccessor({ ...base, accessor, buffer: bytes });
+      expectColorError(result, 'gltf-color-accessor-malformed', reason, 1);
+      return;
+    }
+    const result = decodeColorAccessor({ ...base, accessor });
+    expectColorError(result, 'gltf-color-accessor-malformed', reason, 1);
+  });
+
+  it('rejects non-finite FLOAT values as malformed rather than publishing partial data', () => {
+    const base = inputFor('float-vec3', 1);
+    const bytes = base.buffer.slice();
+    new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).setFloat32(24, Number.NaN, true);
+    const result = decodeColorAccessor({ ...base, buffer: bytes });
+    expectColorError(result, 'gltf-color-accessor-malformed', 'finite', 1);
+  });
+
+  it('rejects a bad buffer reference as malformed', () => {
+    const base = inputFor('float-vec3', 1);
+    const result = decodeColorAccessor({
+      ...base,
+      bufferView: { ...base.bufferView, buffer: 4 },
+    });
+    expectColorError(result, 'gltf-color-accessor-malformed', 'reference', 1);
+  });
+
+  it('reports sparse and morph COLOR_0 as deferred unsupported', () => {
+    const base = inputFor('float-vec3', 1);
+    const sparse = decodeColorAccessor({
+      ...base,
+      accessor: { ...base.accessor, sparse: { count: 1 } },
+    });
+    expectColorError(sparse, 'gltf-color-accessor-unsupported', 'sparse', 1);
+
+    const morph = decodeColorAccessor(base, { morph: true });
+    expectColorError(morph, 'gltf-color-accessor-unsupported', 'morph', 1);
+  });
+});

package/src/__tests__/data-uri-surface.unit.test.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { Base64DecodeError, dataUriBase64Payload, decodeBase64 } from '../data-uri.js';
+
+const ownerSource = readFileSync(new URL('../data-uri.ts', import.meta.url), 'utf8');
+const parseSource = readFileSync(new URL('../parse-gltf.ts', import.meta.url), 'utf8');
+const extractSource = readFileSync(new URL('../extract-image-bytes.ts', import.meta.url), 'utf8');
+
+describe('data URI helper surface', () => {
+  it('owns matching, payload preservation, and browser-safe decoding', () => {
+    const payload = dataUriBase64Payload('data:application/octet-stream;base64,AAE=');
+
+    expect(payload).toBe('AAE=');
+    expect(dataUriBase64Payload('https://example.com/mesh.bin')).toBeUndefined();
+    expect(dataUriBase64Payload('data:application/octet-stream;base64,')).toBe('');
+    expect([...decodeBase64(payload ?? '')]).toEqual([0, 1]);
+    expect(() => decodeBase64('%%%%')).toThrow(Base64DecodeError);
+    expect(ownerSource.match(/const DATA_URI_BASE64_RE =/g)).toHaveLength(1);
+    expect(parseSource).not.toMatch(/const DATA_URI_BASE64_RE =/);
+    expect(extractSource).not.toMatch(/const DATA_URI_BASE64_RE =/);
+    expect(parseSource).not.toMatch(/function decodeBase64/);
+    expect(extractSource).not.toMatch(/function decodeBase64/);
+    expect(parseSource).toMatch(/dataUriBase64Payload/);
+    expect(extractSource).toMatch(/dataUriBase64Payload/);
+  });
+});

package/src/__tests__/extension-admission.unit.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { checkExtensions } from '../check-extensions.js';
+
+describe('glTF required extension admission', () => {
+  it('keeps unknown required extensions fail-closed', () => {
+    const result = checkExtensions({
+      extensionsRequired: ['KHR_forgeax_unknown'],
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('gltf-extension-unsupported');
+    if (result.error.code !== 'gltf-extension-unsupported') return;
+    expect(result.error.detail).toEqual({
+      extension: 'KHR_forgeax_unknown',
+      source: 'extensionsRequired',
+    });
+  });
+});

package/src/__tests__/fixtures/color-0/float-vec3.gltf

@@ -0,0 +1,13 @@
+{
+  "asset": { "version": "2.0" },
+  "buffers": [{ "byteLength": 48, "uri": "data:application/octet-stream;base64,AAAAAAAAAAAAAAAAAACAPwAAAAAAAAAAAAAAAAAAAD8AAIA/AACAPwAAgD4AAAAA" }],
+  "bufferViews": [
+    { "buffer": 0, "byteOffset": 0, "byteLength": 24 },
+    { "buffer": 0, "byteOffset": 24, "byteLength": 24 }
+  ],
+  "accessors": [
+    { "bufferView": 0, "componentType": 5126, "count": 2, "type": "VEC3" },
+    { "bufferView": 1, "componentType": 5126, "count": 2, "type": "VEC3" }
+  ],
+  "meshes": [{ "primitives": [{ "attributes": { "POSITION": 0, "COLOR_0": 1 } }] }]
+}

package/src/__tests__/fixtures/color-0/interleaved-vec3.gltf

@@ -0,0 +1,6 @@
+{
+  "asset": { "version": "2.0" },
+  "buffers": [{ "byteLength": 32, "uri": "data:application/octet-stream;base64,AAAAAAAAgD4AAIA/AAAAAAAAgD8AAAA/AAAAAAAAAAA=" }],
+  "bufferViews": [{ "buffer": 0, "byteLength": 32, "byteStride": 16 }],
+  "accessors": [{ "bufferView": 0, "componentType": 5126, "count": 2, "type": "VEC3" }]
+}

package/src/__tests__/fixtures/color-0/normalized-ubyte.gltf

@@ -0,0 +1,6 @@
+{
+  "asset": { "version": "2.0" },
+  "buffers": [{ "byteLength": 8, "uri": "data:application/octet-stream;base64,AID/QP8ggP8=" }],
+  "bufferViews": [{ "buffer": 0, "byteLength": 8 }],
+  "accessors": [{ "bufferView": 0, "componentType": 5121, "normalized": true, "count": 2, "type": "VEC4" }]
+}

package/src/__tests__/fixtures/color-0/normalized-ushort.gltf

@@ -0,0 +1,6 @@
+{
+  "asset": { "version": "2.0" },
+  "buffers": [{ "byteLength": 16, "uri": "data:application/octet-stream;base64,AAAAgP//AED//wAgAMD//w==" }],
+  "bufferViews": [{ "buffer": 0, "byteLength": 16 }],
+  "accessors": [{ "bufferView": 0, "componentType": 5123, "normalized": true, "count": 2, "type": "VEC4" }]
+}

package/src/__tests__/gltf-error-derived-views.test-d.ts

@@ -0,0 +1,152 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import {
+  type GltfAccessorTypeMismatchDetail,
+  type GltfAnimationCubicsplineUnsupportedDetail,
+  type GltfAnimationTargetInvalidDetail,
+  type GltfBufferOutOfBoundsDetail,
+  type GltfColorAccessorMalformedDetail,
+  type GltfColorAccessorUnsupportedDetail,
+  type GltfError,
+  type GltfErrorCode,
+  type GltfErrorDetail,
+  type GltfExtensionUnsupportedDetail,
+  type GltfImageExtractFailedDetail,
+  type GltfImageMimeUnsupportedDetail,
+  type GltfInstancingCountMismatchDetail,
+  type GltfMalformedHeaderDetail,
+  type GltfMeshBridgeInvalidDetail,
+  type GltfMeshoptDecodeFailedDetail,
+  type GltfMeshoptDecoderRequiredDetail,
+  type GltfMetaMissingDetail,
+  type GltfMorphInvalidDetail,
+  type GltfMorphUnsupportedDetail,
+  type GltfSkinAttrAsymmetricDetail,
+  type GltfSkinJointCountExceededDetail,
+  type GltfSkinJointNameMissingDetail,
+  type GltfTextureLoadFailedDetail,
+  type GltfVersionUnsupportedDetail,
+  gltfErr,
+} from '../errors.js';
+
+type ExpectedDetails = {
+  readonly 'gltf-malformed-header': GltfMalformedHeaderDetail;
+  readonly 'gltf-version-unsupported': GltfVersionUnsupportedDetail;
+  readonly 'gltf-buffer-out-of-bounds': GltfBufferOutOfBoundsDetail;
+  readonly 'gltf-extension-unsupported': GltfExtensionUnsupportedDetail;
+  readonly 'gltf-accessor-type-mismatch': GltfAccessorTypeMismatchDetail;
+  readonly 'gltf-texture-load-failed': GltfTextureLoadFailedDetail;
+  readonly 'gltf-meta-missing': GltfMetaMissingDetail;
+  readonly 'gltf-instancing-count-mismatch': GltfInstancingCountMismatchDetail;
+  readonly 'gltf-image-mime-unsupported': GltfImageMimeUnsupportedDetail;
+  readonly 'gltf-skin-joint-count-exceeded': GltfSkinJointCountExceededDetail;
+  readonly 'gltf-animation-cubicspline-unsupported': GltfAnimationCubicsplineUnsupportedDetail;
+  readonly 'gltf-morph-unsupported': GltfMorphUnsupportedDetail;
+  readonly 'gltf-skin-joint-name-missing': GltfSkinJointNameMissingDetail;
+  readonly 'gltf-image-extract-failed': GltfImageExtractFailedDetail;
+  readonly 'gltf-skin-attr-asymmetric': GltfSkinAttrAsymmetricDetail;
+  readonly 'gltf-animation-target-invalid': GltfAnimationTargetInvalidDetail;
+  readonly 'gltf-meshopt-decoder-required': GltfMeshoptDecoderRequiredDetail;
+  readonly 'gltf-meshopt-decode-failed': GltfMeshoptDecodeFailedDetail;
+  readonly 'gltf-morph-invalid': GltfMorphInvalidDetail;
+  readonly 'gltf-color-accessor-unsupported': GltfColorAccessorUnsupportedDetail;
+  readonly 'gltf-color-accessor-malformed': GltfColorAccessorMalformedDetail;
+  readonly 'gltf-mesh-bridge-invalid': GltfMeshBridgeInvalidDetail;
+};
+
+type ExpectedCodes = keyof ExpectedDetails;
+type ExpectedError = {
+  readonly [C in ExpectedCodes]: {
+    readonly code: C;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: ExpectedDetails[C];
+  };
+}[ExpectedCodes];
+
+function exhaustive(error: GltfError): string {
+  switch (error.code) {
+    case 'gltf-malformed-header':
+      return `${error.detail.filePath}:${error.detail.byteOffset}`;
+    case 'gltf-version-unsupported':
+      return error.detail.actualVersion;
+    case 'gltf-buffer-out-of-bounds':
+      return `${error.detail.accessor}:${error.detail.bufferIndex}`;
+    case 'gltf-extension-unsupported':
+      return error.detail.extension;
+    case 'gltf-accessor-type-mismatch':
+      return error.detail.reason;
+    case 'gltf-texture-load-failed':
+      return error.detail.uri;
+    case 'gltf-meta-missing':
+      return error.detail.expectedMetaPath;
+    case 'gltf-instancing-count-mismatch':
+      return error.detail.accessor;
+    case 'gltf-image-mime-unsupported':
+      return error.detail.mimeType;
+    case 'gltf-skin-joint-count-exceeded':
+      return `${error.detail.skinIndex}:${error.detail.maxJoints}`;
+    case 'gltf-animation-cubicspline-unsupported':
+      return `${error.detail.animationIndex}:${error.detail.samplerIndex}`;
+    case 'gltf-morph-unsupported':
+      return `${error.detail.animationIndex}:${error.detail.channelIndex}`;
+    case 'gltf-skin-joint-name-missing':
+      return error.detail.reason;
+    case 'gltf-image-extract-failed':
+      return error.detail.source;
+    case 'gltf-skin-attr-asymmetric':
+      return `${error.detail.meshIndex}:${error.detail.primitiveIndex}`;
+    case 'gltf-animation-target-invalid':
+      return error.detail.reason;
+    case 'gltf-meshopt-decoder-required':
+      return `${error.detail.bufferView}:${error.detail.actual}`;
+    case 'gltf-meshopt-decode-failed':
+      return `${error.detail.bufferView}:${error.detail.mode}`;
+    case 'gltf-morph-invalid':
+      return `${error.detail.meshIndex}:${error.detail.primitiveIndex}:${error.detail.reason}`;
+    case 'gltf-color-accessor-unsupported':
+      return `${error.detail.semantic}:${error.detail.accessorIndex}:${error.detail.reason}`;
+    case 'gltf-color-accessor-malformed':
+      return `${error.detail.semantic}:${error.detail.accessorIndex}:${error.detail.reason}`;
+    case 'gltf-mesh-bridge-invalid':
+      return error.detail.reason;
+  }
+  return error;
+}
+
+describe('GltfError derived public views', () => {
+  it('keeps the exact twenty-two-code vocabulary and correlated union', () => {
+    expectTypeOf<GltfErrorCode>().toEqualTypeOf<ExpectedCodes>();
+    expectTypeOf<GltfError>().toEqualTypeOf<ExpectedError>();
+    expectTypeOf<GltfErrorCode>().toEqualTypeOf<GltfError['code']>();
+    expectTypeOf<GltfErrorDetail>().toEqualTypeOf<GltfError['detail']>();
+  });
+
+  it('rejects unknown codes and mismatched code/detail pairs', () => {
+    // @ts-expect-error unknown literals are outside the closed code view
+    const invalidCode: GltfErrorCode = 'gltf-not-a-real-error';
+    void invalidCode;
+
+    // @ts-expect-error the detail must match the selected code
+    gltfErr('gltf-malformed-header', { uri: 'textures/wrong.png' });
+  });
+
+  it('preserves gltfErr inference for a selected correlated variant', () => {
+    const error = gltfErr('gltf-version-unsupported', {
+      filePath: 'model.gltf',
+      actualVersion: '1.0',
+    });
+    expectTypeOf(error).toEqualTypeOf<
+      Extract<GltfError, { readonly code: 'gltf-version-unsupported' }>
+    >();
+    expectTypeOf(error.detail).toEqualTypeOf<GltfVersionUnsupportedDetail>();
+  });
+
+  it('supports exhaustive narrowing across every derived variant', () => {
+    expectTypeOf(exhaustive).toBeCallableWith({
+      code: 'gltf-meta-missing',
+      expected: 'sidecar',
+      hint: 'import it',
+      detail: { filePath: 'model.gltf', expectedMetaPath: 'model.gltf.meta.json' },
+    });
+  });
+});

package/src/__tests__/gltf-error-migration.test.ts

@@ -0,0 +1,147 @@
+// gltf-error-migration.test.ts - M1 grep gate for GltfErrorCode migration.
+//
+// TDD red-green: written BEFORE migration (t6/t7/t8). Three grep assertions
+// guard the DIP boundary: types must have zero gltf- literals, types must
+// have zero GltfError* exports, and gltf/errors.ts must have >=1 GltfError*
+// export. These are RED on first run (types still has GltfError*); they go
+// GREEN after t6/t7/t8 complete the migration.
+//
+// Anchors:
+// - requirements AC-28 (types grep GltfError = 0 hits)
+// - requirements AC-27 (DIP three grep gates)
+// - plan-strategy section 5.3 (DIP grep gate AC-27/AC-28)
+// - charter P3 (explicit failure: grep gate fails-fast on drift)
+
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const REPO_ROOT = resolve(import.meta.dirname ?? '.', '..', '..', '..', '..');
+const TYPES_INDEX = resolve(REPO_ROOT, 'packages', 'types', 'src', 'index.ts');
+const GLTF_ERRORS = resolve(REPO_ROOT, 'packages', 'gltf', 'src', 'errors.ts');
+
+function grepCount(pattern: string, file: string): number {
+  try {
+    const out = execFileSync('rg', ['--count', '--regexp', pattern, file], { encoding: 'utf-8' });
+    return Number.parseInt(out.trim(), 10);
+  } catch (cause: unknown) {
+    if ((cause as { status?: number }).status === 1) return 0;
+    if ((cause as NodeJS.ErrnoException).code === 'ENOENT') {
+      try {
+        const out = execFileSync('grep', ['-E', '-c', pattern, file], { encoding: 'utf-8' });
+        return Number.parseInt(out.trim(), 10);
+      } catch (fallbackCause: unknown) {
+        if ((fallbackCause as { status?: number }).status === 1) return 0;
+        throw fallbackCause;
+      }
+    }
+    throw cause;
+  }
+}
+
+function grepCountImportGltfErrorFromTypes(): number {
+  try {
+    // Search tracked source paths so coverage runs do not recursively walk
+    // generated or ignored trees on a busy CI runner. The migration contract
+    // is about repository source, which is exactly the tracked worktree set.
+    const out = execFileSync(
+      'git',
+      [
+        'grep',
+        '--no-color',
+        '-E',
+        '-l',
+        '-e',
+        'import.*GltfError.*from.*@forgeax/engine-types',
+        '--',
+        'packages',
+        'apps',
+        ':(exclude)packages/gltf/src/__tests__/gltf-error-migration.test.ts',
+      ],
+      { encoding: 'utf-8' },
+    );
+    return out.trim().split('\n').filter(Boolean).length;
+  } catch (cause: unknown) {
+    if ((cause as { status?: number }).status === 1) return 0;
+    if ((cause as NodeJS.ErrnoException).code === 'ENOENT') {
+      try {
+        const out = execFileSync(
+          'rg',
+          [
+            '--files-with-matches',
+            '--glob',
+            '*.ts',
+            '--glob',
+            '!**/node_modules/**',
+            '--glob',
+            '!**/dist/**',
+            '--glob',
+            '!**/gltf-error-migration.test.ts',
+            '--regexp',
+            'import.*GltfError.*from.*@forgeax/engine-types',
+            resolve(REPO_ROOT, 'packages'),
+            resolve(REPO_ROOT, 'apps'),
+          ],
+          { encoding: 'utf-8' },
+        );
+        return out.trim().split('\n').filter(Boolean).length;
+      } catch (fallbackCause: unknown) {
+        if ((fallbackCause as { status?: number }).status === 1) return 0;
+        if ((fallbackCause as NodeJS.ErrnoException).code === 'ENOENT') {
+          try {
+            const out = execFileSync(
+              'grep',
+              [
+                '-R',
+                '-l',
+                '-E',
+                '--include=*.ts',
+                '--exclude-dir=node_modules',
+                '--exclude-dir=dist',
+                'import.*GltfError.*from.*@forgeax/engine-types',
+                resolve(REPO_ROOT, 'packages'),
+                resolve(REPO_ROOT, 'apps'),
+              ],
+              { encoding: 'utf-8' },
+            );
+            return out
+              .trim()
+              .split('\n')
+              .filter(
+                (file) =>
+                  file &&
+                  !file.endsWith('/packages/gltf/src/__tests__/gltf-error-migration.test.ts'),
+              ).length;
+          } catch (grepCause: unknown) {
+            if ((grepCause as { status?: number }).status === 1) return 0;
+            throw grepCause;
+          }
+        }
+        throw fallbackCause;
+      }
+    }
+    throw cause;
+  }
+}
+
+describe('M1 GltfErrorCode migration grep gate (AC-28)', () => {
+  it("(a) types/src/index.ts contains zero 'gltf-' string literals", () => {
+    const count = grepCount("'gltf-", TYPES_INDEX);
+    expect(count).toBe(0);
+  });
+
+  it('(b) types/src/index.ts contains zero export type GltfError* exports', () => {
+    const count = grepCount('export type GltfError', TYPES_INDEX);
+    expect(count).toBe(0);
+  });
+
+  it('(c) gltf/errors.ts contains >=1 export type GltfError* exports', () => {
+    const count = grepCount('export type GltfError', GLTF_ERRORS);
+    expect(count).toBeGreaterThanOrEqual(1);
+  });
+
+  it('(d) zero import GltfError from @forgeax/engine-types in all packages/apps', () => {
+    const count = grepCountImportGltfErrorFromTypes();
+    expect(count).toBe(0);
+  });
+});