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

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@forgeax/engine-gltf",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Runtime glTF 2.0 importer (Tier-B subset: scenes + nodes + meshes (POSITION + INDICES) + UnlitMaterial.baseColor + Camera.perspective). Pure-function pipeline parseGlb / parseGltf / toAssetPack consumed by build-time CLI (forgeax-engine-remote-gltf import) writing <source>.meta.json (external-asset-package; assetType=gltf) for runtime loadByGuid<SceneAsset>.",
+  "bin": {
+    "forgeax-engine-remote-gltf": "./dist/cli-gltf.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./node": {
+      "types": "./dist/node-file-entry.d.ts",
+      "import": "./dist/node-file-entry.mjs"
+    },
+    "./importer": {
+      "types": "./dist/importer-entry.d.ts",
+      "import": "./dist/importer-entry.mjs"
+    },
+    "./cli-gltf": {
+      "types": "./dist/cli-gltf.d.ts",
+      "node": "./dist/cli-gltf.mjs",
+      "default": null
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-animation": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-geometry": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-import": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-math": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-pack": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-scene": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79",
+    "@webgpu/types": "^0.1.71",
+    "meshoptimizer": "^0.20.0"
+  },
+  "devDependencies": {
+    "@forgeax/engine-assets-runtime": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-picking": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-render": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-runtime": "0.0.0-dev.8d955ade1c79",
+    "@types/node": "^20.14.0"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip",
+        "expected": 5865,
+        "baseline": {
+          "source": ".forgeax-harness/forgeax-loop/feat-20260515-gltf-loader-via-asset-system/plan-strategy.md#R3",
+          "threshold": 102400
+        }
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "build-time importer pure-function pipeline; no runtime canvas. fps reported by hello-gltf app (M5)."
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "Tier-B importer is one-shot build-time work (not a hot path); bench focus stays on @forgeax/engine-math."
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no per-package binary gate; runtime parsing is consumed by @forgeax/engine-runtime + cli-gltf only, no separate enforcement scope."
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package."
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/animation-target-errors.unit.test.ts

@@ -0,0 +1,51 @@
+import { deriveAnimationTargetId } from '@forgeax/engine-animation/target-id';
+import { describe, expect, it } from 'vitest';
+import { gltfErr } from '../errors';
+import { buildNodeParentMap, resolveNamedNodePath } from '../node-path';
+
+describe('glTF animation target paths', () => {
+  const nodes = [
+    { name: 'Root', children: [1] },
+    { name: 'Hip', children: [] },
+  ] as const;
+
+  it('derives a stable full-path ID from a source node index', () => {
+    const parents = buildNodeParentMap(nodes);
+    const path = resolveNamedNodePath(nodes, parents, 1);
+    expect(path.ok).toBe(true);
+    if (!path.ok) return;
+    expect(path.value).toEqual(['Root', 'Hip']);
+    expect(deriveAnimationTargetId(path.value)).toBe('a95da0ec669189f98273e8f86d8ad9f2');
+  });
+
+  it('uses one stable code with a reason discriminator', () => {
+    const error = gltfErr('gltf-animation-target-invalid', {
+      reason: 'name-missing',
+      animationIndex: 0,
+      channelIndex: 1,
+      nodeIndex: 1,
+    });
+    expect(error.code).toBe('gltf-animation-target-invalid');
+    expect(error.detail.reason).toBe('name-missing');
+    expect(error.hint.length).toBeGreaterThan(0);
+  });
+
+  it('rejects cyclic node ancestry instead of looping', () => {
+    const cyclicNodes = [
+      { name: 'A', children: [1] },
+      { name: 'B', children: [0] },
+    ] as const;
+    const path = resolveNamedNodePath(cyclicNodes, buildNodeParentMap(cyclicNodes), 0);
+
+    expect(path).toEqual({
+      ok: false,
+      reason: 'hierarchy-cycle',
+      nodeIndex: 0,
+    });
+  });
+
+  it('does not reject unnamed nodes that are not animation targets', () => {
+    const parents = buildNodeParentMap([{ children: [] }]);
+    expect(parents.size).toBe(0);
+  });
+});

package/src/__tests__/bridge-material-samplers.unit.test.ts

@@ -0,0 +1,67 @@
+import type { Handle } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { toMaterialAsset } from '../bridge.js';
+import type { GltfMaterialIr } from '../parse-gltf.js';
+
+describe('glTF material sampler mapping', () => {
+  it('maps BLEND to straight-alpha state without depth writes', () => {
+    const asset = toMaterialAsset({
+      baseColorFactor: [1, 1, 1, 0.4],
+      metallicFactor: 0,
+      roughnessFactor: 1,
+      alphaMode: 'BLEND',
+    } as unknown as GltfMaterialIr);
+    const state = asset.passes?.[0]?.renderState as {
+      blend?: {
+        color?: { srcFactor?: string; dstFactor?: string };
+        alpha?: { srcFactor?: string; dstFactor?: string };
+      };
+      depthWriteEnabled?: boolean;
+      queue?: number;
+    };
+
+    expect(state.queue).toBe(3000);
+    expect(state.depthWriteEnabled).toBe(false);
+    expect(state.blend).toMatchObject({
+      color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha' },
+      alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+    });
+  });
+
+  it('maps each texture slot to its own sampler GUID', () => {
+    const asset = toMaterialAsset(
+      {
+        baseColorFactor: [1, 1, 1, 1],
+        metallicFactor: 1,
+        roughnessFactor: 1,
+        baseColorTexture: { texture: 0, sampler: 10 },
+        metallicRoughnessTexture: { texture: 1, sampler: 11 },
+        normalTexture: { texture: 2, sampler: 12 },
+        occlusionTexture: { texture: 3, sampler: 13 },
+        emissiveTexture: { texture: 4, sampler: 14 },
+      } as unknown as GltfMaterialIr,
+      {
+        textureHandles: new Map([
+          [0, 100],
+          [1, 101],
+          [2, 102],
+          [3, 103],
+          [4, 104],
+        ]) as unknown as ReadonlyMap<number, Handle<'TextureAsset', 'shared'>>,
+        samplerHandles: new Map([
+          [10, 200],
+          [11, 201],
+          [12, 202],
+          [13, 203],
+          [14, 204],
+        ]) as unknown as ReadonlyMap<number, Handle<'SamplerAsset', 'shared'>>,
+      },
+    );
+    const values = asset.values as Record<string, { sampler?: unknown }>;
+    expect(values.baseColorTexture?.sampler).toBe(200);
+    expect(values.metallicRoughnessTexture?.sampler).toBe(201);
+    expect(values.normalTexture?.sampler).toBe(202);
+    expect(values.occlusionTexture?.sampler).toBe(203);
+    expect(values.emissiveTexture?.sampler).toBe(204);
+  });
+});

package/src/__tests__/bridge-material-values.unit.test.ts

@@ -0,0 +1,106 @@
+import type { Handle } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { toMaterialAsset } from '../bridge.js';
+import type { GltfMaterialIr } from '../parse-gltf.js';
+
+describe('glTF material bridge values', () => {
+  it('preserves all four base-color channels for factor and texture composition', () => {
+    const factor = [0.5, 0.75, 0.25, 0.4] as const;
+    const material = toMaterialAsset({
+      baseColorFactor: factor,
+      metallicFactor: 0.5,
+      roughnessFactor: 0.7,
+      baseColorTexture: { texture: 0 },
+    } as unknown as GltfMaterialIr);
+
+    expect(material.values).toMatchObject({ baseColor: factor });
+    expect(material.values).not.toHaveProperty('baseColorAlpha');
+    expect(material.values).not.toHaveProperty('textureAlphaFactor');
+  });
+
+  it.each([
+    ['default', undefined, 0.5],
+    ['explicit', 0.73, 0.73],
+    ['zero', 0, 0],
+    ['one', 1, 1],
+  ] as const)('projects MASK %s cutoff into the material contract', (_name, authored, expected) => {
+    const material = toMaterialAsset({
+      baseColorFactor: [1, 1, 1, 0.5],
+      metallicFactor: 0,
+      roughnessFactor: 1,
+      alphaMode: 'MASK',
+      ...(authored === undefined ? {} : { alphaCutoff: authored }),
+    } as unknown as GltfMaterialIr);
+
+    expect(material.values?.alphaCutoff).toBe(expected);
+  });
+
+  it('projects five structured texture slots into standard-root values', () => {
+    const material = toMaterialAsset(
+      {
+        baseColorFactor: [0.8, 0.2, 0.1, 1],
+        metallicFactor: 0.5,
+        roughnessFactor: 0.7,
+        baseColorTexture: { texture: 0, sampler: 10, texCoord: 1 },
+        metallicRoughnessTexture: { texture: 1, sampler: 11, texCoord: 2 },
+        normalTexture: { texture: 2, sampler: 12, texCoord: 3, scale: 0.6 },
+        occlusionTexture: { texture: 3, sampler: 13, texCoord: 4, strength: 0.8 },
+        emissiveTexture: { texture: 4, sampler: 14, texCoord: 5 },
+      } as unknown as GltfMaterialIr,
+      {
+        textureHandles: new Map([
+          [0, 100],
+          [1, 101],
+          [2, 102],
+          [3, 103],
+          [4, 104],
+        ]) as unknown as ReadonlyMap<number, Handle<'TextureAsset', 'shared'>>,
+        samplerHandles: new Map([
+          [10, 200],
+          [11, 201],
+          [12, 202],
+          [13, 203],
+          [14, 204],
+        ]) as unknown as ReadonlyMap<number, Handle<'SamplerAsset', 'shared'>>,
+      },
+    );
+
+    expect(material.passes?.[0]?.program.module).toBe('forgeax::default-standard-pbr');
+    expect(material.colorSpace).toBe('linear');
+    expect(material.values).toMatchObject({
+      baseColor: [0.8, 0.2, 0.1, 1],
+      metallic: 0.5,
+      roughness: 0.7,
+      baseColorTexture: { texture: 100, sampler: 200, coordinates: { set: 1 } },
+      metallicRoughnessTexture: { texture: 101, sampler: 201, coordinates: { set: 2 } },
+      normalTexture: { texture: 102, sampler: 202, coordinates: { set: 3 }, normalScale: 0.6 },
+      occlusionTexture: {
+        texture: 103,
+        sampler: 203,
+        coordinates: { set: 4 },
+        occlusionStrength: 0.8,
+      },
+      emissiveTexture: { texture: 104, sampler: 204, coordinates: { set: 5 } },
+    });
+  });
+
+  it('keeps identity texture authoring compact', () => {
+    const material = toMaterialAsset(
+      {
+        baseColorTexture: { texture: 0 },
+        metallicFactor: 0.5,
+        roughnessFactor: 0.5,
+      } as unknown as GltfMaterialIr,
+      {
+        textureHandles: new Map([[0, 100]]) as unknown as ReadonlyMap<
+          number,
+          Handle<'TextureAsset', 'shared'>
+        >,
+        samplerHandles: new Map(),
+      },
+    );
+
+    expect(material.values?.baseColorTexture).toEqual({ texture: 100 });
+    expect(material.values?.baseColorTexture).not.toHaveProperty('coordinates');
+  });
+});

package/src/__tests__/bridge-mixed-color.unit.test.ts

@@ -0,0 +1,100 @@
+import type { MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { meshIrToMeshAsset as bridgeMeshIrToMeshAsset } from '../bridge.js';
+import type { GltfMeshIr } from '../parse-gltf.js';
+import { unwrapMeshAsset as meshIrToMeshAsset } from './bridge-test-helpers.js';
+
+type ColorMeshIr = GltfMeshIr & { readonly colors0?: Float32Array };
+
+function primitive(vertexCount: number, colors0?: Float32Array): ColorMeshIr {
+  const positions = new Float32Array(vertexCount * 3);
+  for (let vertex = 0; vertex < vertexCount; vertex++) {
+    positions[vertex * 3 + 0] = vertex;
+  }
+  return {
+    positions,
+    indices: new Uint16Array(vertexCount === 3 ? [0, 1, 2] : [0, 1, 2, 0, 2, 3]),
+    materialIndex: 0,
+    meshIndex: 0,
+    ...(colors0 === undefined ? {} : { colors0 }),
+  };
+}
+
+function color(asset: MeshAsset): Float32Array | undefined {
+  return asset.attributes.color as Float32Array | undefined;
+}
+
+describe('glTF bridge COLOR_0 mixed primitive contract', () => {
+  it('takes the attributes union and fills absent primitive vertices with white', () => {
+    const colored = primitive(3, new Float32Array([1, 0.5, 0, 1, 0, 1, 0.5, 1, 0.25, 0, 1, 1]));
+    const plain = primitive(3);
+    const asset = meshIrToMeshAsset([colored, plain]);
+    expect(color(asset)).toEqual(
+      new Float32Array([
+        1, 0.5, 0, 1, 0, 1, 0.5, 1, 0.25, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
+      ]),
+    );
+  });
+
+  it.each([
+    ['all colored', [primitive(3, new Float32Array(12)), primitive(4, new Float32Array(16))]],
+    ['all plain', [primitive(3), primitive(4)]],
+    [
+      'skin and UV combination',
+      [
+        {
+          ...primitive(3, new Float32Array(12)),
+          joints0: new Uint16Array(12),
+          weights0: new Float32Array(12),
+          texcoord0: new Float32Array(6),
+          texcoord1: new Float32Array(6),
+        },
+      ],
+    ],
+  ] as const)('uses one canonical packer for %s', (_name, prims) => {
+    const asset = meshIrToMeshAsset(prims);
+    const attributes = asset.attributes as Record<string, unknown>;
+    expect(attributes.position).toBeInstanceOf(Float32Array);
+    expect(attributes.color === undefined || attributes.color instanceof Float32Array).toBe(true);
+  });
+
+  it('keeps a missing color stream unallocated for a plain mesh', () => {
+    const asset = meshIrToMeshAsset([primitive(3)]);
+    expect(color(asset)).toBeUndefined();
+  });
+
+  it('returns closed, typed bridge failures before publishing malformed meshes', () => {
+    const empty = bridgeMeshIrToMeshAsset([]);
+    expect(empty.ok).toBe(false);
+    if (!empty.ok) expect(empty.error.detail).toEqual({ reason: 'empty-input', primitiveCount: 0 });
+
+    const morphMismatch = bridgeMeshIrToMeshAsset([
+      { ...primitive(3), morphTargets: [] },
+      { ...primitive(3), morphTargets: [{ position: new Float32Array(9) }] },
+    ]);
+    expect(morphMismatch.ok).toBe(false);
+    if (!morphMismatch.ok)
+      expect(morphMismatch.error.detail).toMatchObject({
+        reason: 'morph-count-mismatch',
+        expectedTargetCount: 0,
+        actualTargetCount: 1,
+      });
+
+    const colorMismatch = bridgeMeshIrToMeshAsset([primitive(3, new Float32Array(4))]);
+    expect(colorMismatch.ok).toBe(false);
+    if (!colorMismatch.ok)
+      expect(colorMismatch.error.detail).toMatchObject({
+        reason: 'color-cardinality',
+        semantic: 'COLOR_0',
+        expectedLength: 12,
+        actualLength: 4,
+      });
+
+    const layoutMismatch = bridgeMeshIrToMeshAsset([
+      { ...primitive(3), positions: new Float32Array(4) },
+    ]);
+    expect(layoutMismatch.ok).toBe(false);
+    if (!layoutMismatch.ok)
+      expect(layoutMismatch.error.detail).toMatchObject({ reason: 'layout-invalid' });
+  });
+});

package/src/__tests__/bridge-sampler-required.test-d.ts

@@ -0,0 +1,59 @@
+// bridge-sampler-required.test-d.ts - type-level assertions for
+// toMaterialAsset (pass-based, feat-20260526-material-asset-multipass-renderstate M4 / w31).
+//
+// toMaterialAsset no longer takes a shadingModel parameter; it accepts
+// GltfMaterialIr + optional MaterialBridgeContext and returns MaterialAsset.
+
+import type { Handle } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import type { MaterialBridgeContext } from '../bridge.js';
+import { toMaterialAsset } from '../bridge.js';
+import type { GltfMaterialIr } from '../parse-gltf.js';
+
+const matIr: GltfMaterialIr = {
+  name: 'test-material',
+  baseColorFactor: [1, 1, 1, 1],
+  metallicFactor: 0,
+  roughnessFactor: 0.5,
+};
+
+const textureHandles = new Map<number, Handle<'TextureAsset', 'shared'>>();
+const samplerHandles = new Map<number, Handle<'SamplerAsset', 'shared'>>();
+
+describe('toMaterialAsset — pass-based type-level', () => {
+  it('positive: with undefined ctx compiles', () => {
+    const result = toMaterialAsset(matIr, undefined);
+    expectTypeOf(result).toMatchTypeOf<ReturnType<typeof toMaterialAsset>>();
+  });
+
+  it('positive: without ctx compiles', () => {
+    const result = toMaterialAsset(matIr);
+    expectTypeOf(result).toMatchTypeOf<ReturnType<typeof toMaterialAsset>>();
+  });
+
+  it('positive: with both textureHandles and samplerHandles compiles', () => {
+    const result = toMaterialAsset(matIr, {
+      textureHandles,
+      samplerHandles,
+    });
+    expectTypeOf(result).toMatchTypeOf<ReturnType<typeof toMaterialAsset>>();
+  });
+
+  it('positive: with textureHandles only compiles', () => {
+    const result = toMaterialAsset(matIr, { textureHandles });
+    expectTypeOf(result).toMatchTypeOf<ReturnType<typeof toMaterialAsset>>();
+  });
+
+  it('type-level: MaterialBridgeContext has optional samplerHandles', () => {
+    const ctx: MaterialBridgeContext = { textureHandles };
+    expectTypeOf(ctx).toMatchTypeOf<MaterialBridgeContext>();
+  });
+
+  it('type-level: toMaterialAsset is callable as a function', () => {
+    expectTypeOf(toMaterialAsset).toBeCallableWith(matIr);
+    expectTypeOf(toMaterialAsset).toBeCallableWith(matIr, {
+      textureHandles,
+      samplerHandles,
+    });
+  });
+});

package/src/__tests__/bridge-skin-shader-route.unit.test.ts

@@ -0,0 +1,42 @@
+// bridge-skin-shader-route.unit.test.ts (feat-20260611 M4 / w17-a).
+//
+// Covers cooker-side auto-route: toMaterialAsset emits
+// `forgeax::pbr-skin` when MaterialBridgeContext.skinned === true,
+// falls back to `forgeax::default-standard-pbr` otherwise. The
+// gltf-importer is the only call site that has the per-mesh skin
+// presence info; routing here keeps shader choice content-driven
+// without exposing a runtime auto-resolve (Q4) — the runtime
+// SkinMaterialMismatchError fail-fast in render-system-extract is
+// the reverse-direction safety net for misauthored content.
+
+import { describe, expect, it } from 'vitest';
+import { toMaterialAsset } from '../bridge.js';
+import type { GltfMaterialIr } from '../parse-gltf.js';
+
+function makeMatIr(): GltfMaterialIr {
+  return {
+    baseColorFactor: [1, 1, 1, 1] as const,
+    metallicFactor: 0.0,
+    roughnessFactor: 1.0,
+  };
+}
+
+describe('toMaterialAsset shader routing (w17-a)', () => {
+  it('skinned: true -> passes[0].shader === forgeax::pbr-skin', () => {
+    const mat = makeMatIr();
+    const asset = toMaterialAsset(mat, { skinned: true });
+    expect(asset.passes?.[0]?.program.module).toBe('forgeax::pbr-skin');
+  });
+
+  it('skinned: false -> passes[0].shader === forgeax::default-standard-pbr', () => {
+    const mat = makeMatIr();
+    const asset = toMaterialAsset(mat, { skinned: false });
+    expect(asset.passes?.[0]?.program.module).toBe('forgeax::default-standard-pbr');
+  });
+
+  it('no flag (back-compat) -> passes[0].shader === forgeax::default-standard-pbr', () => {
+    const mat = makeMatIr();
+    const asset = toMaterialAsset(mat);
+    expect(asset.passes?.[0]?.program.module).toBe('forgeax::default-standard-pbr');
+  });
+});

package/src/__tests__/bridge-skin-stride.unit.test.ts

@@ -0,0 +1,115 @@
+// bridge-skin-stride.unit.test.ts (feat-20260611 M2 / w9 + w10).
+//
+// Covers AC-08: meshIrToMeshAsset per-MeshAsset stride decision.
+// - w9: skinned + unskinned primitives sharing one glTF mesh both walk the
+//   18-float stride; unskinned primitive's skin slots are zero-filled.
+// - w10: a single unskinned primitive stays on the legacy 12-float stride
+//   (OOS-9 / AC-04 — learn-render unskinned demos must not regress).
+
+import { describe, expect, it } from 'vitest';
+import type { GltfMeshIr } from '../parse-gltf.js';
+import { unwrapMeshAsset as meshIrToMeshAsset } from './bridge-test-helpers.js';
+
+function makeUnskinnedPrim(meshIndex: number, vertexCount: number): GltfMeshIr {
+  return {
+    meshIndex,
+    materialIndex: null,
+    positions: new Float32Array(vertexCount * 3),
+    indices: new Uint16Array(Array.from({ length: vertexCount }, (_, i) => i)),
+  };
+}
+
+function makeSkinnedPrim(meshIndex: number, vertexCount: number): GltfMeshIr {
+  const joints0 = new Uint16Array(vertexCount * 4);
+  const weights0 = new Float32Array(vertexCount * 4);
+  for (let v = 0; v < vertexCount; v++) {
+    joints0[v * 4 + 0] = v;
+    joints0[v * 4 + 1] = v + 1;
+    joints0[v * 4 + 2] = v + 2;
+    joints0[v * 4 + 3] = v + 3;
+    weights0[v * 4 + 0] = 0.4;
+    weights0[v * 4 + 1] = 0.3;
+    weights0[v * 4 + 2] = 0.2;
+    weights0[v * 4 + 3] = 0.1;
+  }
+  return {
+    meshIndex,
+    materialIndex: null,
+    positions: new Float32Array(vertexCount * 3),
+    indices: new Uint16Array(Array.from({ length: vertexCount }, (_, i) => i)),
+    joints0,
+    weights0,
+  };
+}
+
+describe('meshIrToMeshAsset stride decision (AC-08)', () => {
+  it('skinned + unskinned primitives co-located -> 18F unified, unskinned skin slots zero-filled', () => {
+    const skinned = makeSkinnedPrim(0, 3);
+    const unskinned = makeUnskinnedPrim(0, 2);
+    const asset = meshIrToMeshAsset([skinned, unskinned]);
+
+    const totalVerts = 3 + 2;
+    expect(asset.vertices.length / 18).toBe(totalVerts);
+    expect(asset.attributes.skinIndex).toBeInstanceOf(Uint16Array);
+    expect(asset.attributes.skinWeight).toBeInstanceOf(Float32Array);
+
+    const stride = 18;
+    // Layout per deriveVertexBufferLayout (72-byte stride):
+    //   pos[0..2] norm[3..5] uv[6..7] tangent[8..11]
+    //   skinIndex (uint16x4) at float[12..13] (8 bytes)
+    //   skinWeight (float32x4) at float[14..17] (16 bytes)
+    const interleavedU16 = new Uint16Array(asset.vertices.buffer);
+    for (let v = 0; v < 3; v++) {
+      const u16Base = (v * stride + 12) * 2;
+      expect(interleavedU16[u16Base + 0]).toBe(v);
+      expect(interleavedU16[u16Base + 1]).toBe(v + 1);
+      expect(interleavedU16[u16Base + 2]).toBe(v + 2);
+      expect(interleavedU16[u16Base + 3]).toBe(v + 3);
+      expect(asset.vertices[v * stride + 14]).toBeCloseTo(0.4, 5);
+      expect(asset.vertices[v * stride + 15]).toBeCloseTo(0.3, 5);
+      expect(asset.vertices[v * stride + 16]).toBeCloseTo(0.2, 5);
+      expect(asset.vertices[v * stride + 17]).toBeCloseTo(0.1, 5);
+    }
+    // Unskinned primitive (vertex 3..4) skin slots must be all zero.
+    for (let v = 3; v < totalVerts; v++) {
+      const u16Base = (v * stride + 12) * 2;
+      expect(interleavedU16[u16Base + 0]).toBe(0);
+      expect(interleavedU16[u16Base + 1]).toBe(0);
+      expect(interleavedU16[u16Base + 2]).toBe(0);
+      expect(interleavedU16[u16Base + 3]).toBe(0);
+      expect(asset.vertices[v * stride + 14]).toBe(0);
+      expect(asset.vertices[v * stride + 15]).toBe(0);
+      expect(asset.vertices[v * stride + 16]).toBe(0);
+      expect(asset.vertices[v * stride + 17]).toBe(0);
+    }
+  });
+});
+
+describe('meshIrToMeshAsset pure-unskinned path (AC-04 / AC-08 / OOS-9)', () => {
+  it('all primitives unskinned -> 12F stride preserved, no skinIndex/skinWeight in attributes', () => {
+    const unskinned = makeUnskinnedPrim(0, 4);
+    const asset = meshIrToMeshAsset([unskinned]);
+
+    expect(asset.vertices.length / 12).toBe(4);
+    expect(asset.attributes.skinIndex).toBeUndefined();
+    expect(asset.attributes.skinWeight).toBeUndefined();
+    // Position / normal / uv / tangent attributes still populated.
+    expect(asset.attributes.position).toBeInstanceOf(Float32Array);
+    expect(asset.attributes.normal).toBeInstanceOf(Float32Array);
+    expect(asset.attributes.uv).toBeInstanceOf(Float32Array);
+    expect(asset.attributes.tangent).toBeInstanceOf(Float32Array);
+  });
+});
+
+describe('glTF bridge uses geometry-owned packing', () => {
+  it('does not own a parallel 12F/18F stride or uv count calculation', () => {
+    const asset = meshIrToMeshAsset([makeUnskinnedPrim(0, 4)]);
+    expect(asset.vertices.length / 12).toBe(4);
+    expect(asset.attributes.position).toBeInstanceOf(Float32Array);
+  });
+
+  it('keeps no-color producer output free of a synthetic color stream', () => {
+    const asset = meshIrToMeshAsset([makeUnskinnedPrim(0, 4)]);
+    expect(asset.attributes.color).toBeUndefined();
+  });
+});

package/src/__tests__/bridge-test-helpers.ts

@@ -0,0 +1,9 @@
+import type { MeshAsset } from '@forgeax/engine-types';
+import { meshIrToMeshAsset } from '../bridge.js';
+
+/** Test-only unwrap for fixtures whose validity is the subject under test. */
+export function unwrapMeshAsset(...args: Parameters<typeof meshIrToMeshAsset>): MeshAsset {
+  const result = meshIrToMeshAsset(...args);
+  if (!result.ok) throw result.error;
+  return result.value;
+}