@forgeax/engine-gltf 0.1.2

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@forgeax/engine-gltf",
+  "version": "0.1.2",
+  "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 typed assets.load(guid, sceneAssetKind) and World scene ownership.",
+  "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.1.2",
+    "@forgeax/engine-geometry": "0.1.2",
+    "@forgeax/engine-import": "0.1.2",
+    "@forgeax/engine-math": "0.1.2",
+    "@forgeax/engine-pack": "0.1.2",
+    "@forgeax/engine-scene": "0.1.2",
+    "@forgeax/engine-types": "0.1.2",
+    "@webgpu/types": "^0.1.71",
+    "meshoptimizer": "^0.20.0"
+  },
+  "devDependencies": {
+    "@forgeax/engine-assets-runtime": "0.1.2",
+    "@forgeax/engine-ecs": "0.1.2",
+    "@forgeax/engine-geometry": "0.1.2",
+    "@forgeax/engine-picking": "0.1.2",
+    "@forgeax/engine-render": "0.1.2",
+    "@forgeax/engine-runtime": "0.1.2",
+    "@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__/asset-runtime-fixture.ts

@@ -0,0 +1,278 @@
+import { createHash } from 'node:crypto';
+import {
+  type AssetRegistry,
+  createAssetRegistry,
+  createCatalogSource,
+} from '@forgeax/engine-assets-runtime';
+import { meshAssetDecoder, meshAssetKind } from '@forgeax/engine-geometry';
+import { type DdcPack, normaliseForPack } from '@forgeax/engine-import';
+import type {
+  AssetDecoder,
+  AssetKind,
+  AssetLoadError,
+  MeshAsset,
+  MorphTarget,
+  Result,
+  VertexAttributeMap,
+} from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+
+const SCOPE_ID = 'gltf-test-scope';
+const GENERATION = 1;
+const PACK_DIGEST = `sha256:${'1'.repeat(64)}`;
+const OUTPUT_SET_DIGEST = `sha256:${'2'.repeat(64)}`;
+const OUTPUT_DIGEST = `sha256:${'3'.repeat(64)}`;
+const ATTRIBUTE_KEYS = [
+  'position',
+  'normal',
+  'uv',
+  'tangent',
+  'skinIndex',
+  'skinWeight',
+  'uv1',
+  'uv2',
+  'uv3',
+  'uv4',
+  'uv5',
+  'uv6',
+  'uv7',
+] as const;
+
+type FixtureAsset = DdcPack['assets'][number];
+
+export interface AssetRuntimeFixtureOptions {
+  readonly packageUrl?: string;
+  readonly artifactOverrides?: ReadonlyMap<string, Uint8Array>;
+}
+
+function sha256(bytes: Uint8Array): string {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function row(asset: FixtureAsset, packageUrl: string) {
+  const sourcePath = `fixtures/${asset.guid}`;
+  return {
+    guid: asset.guid,
+    packageUrl,
+    kind: asset.kind,
+    sourcePath,
+    revision: { rootId: 'gltf-fixture', digest: 'sha256:catalog', observedAt: 1 },
+    publication: {
+      schemaVersion: 'asset-publication/1' as const,
+      sourcePath,
+      sourceRevision: 'gltf-fixture-source',
+      generation: GENERATION,
+      digest: PACK_DIGEST,
+      outputSetDigest: OUTPUT_SET_DIGEST,
+      outputs: [
+        {
+          guid: asset.guid,
+          sourceKey: asset.sourceKey ?? asset.guid,
+          kind: asset.kind,
+          digest: OUTPUT_DIGEST,
+          refs: asset.refs,
+        },
+      ],
+      receipt: {
+        schemaVersion: 'asset-publication-receipt/1' as const,
+        sourcePath,
+        sourceRevision: 'gltf-fixture-source',
+        inputFingerprint: 'gltf-fixture-input',
+        outputDigest: OUTPUT_DIGEST,
+        outputSetDigest: OUTPUT_SET_DIGEST,
+        externalEvidence: [],
+      },
+      externalEvidence: [],
+    },
+  };
+}
+
+function floatArray(value: unknown): Float32Array | undefined {
+  if (value instanceof Float32Array) return value;
+  if (value instanceof ArrayBuffer) return new Float32Array(value);
+  if (ArrayBuffer.isView(value))
+    return new Float32Array(Array.from(value as unknown as ArrayLike<number>));
+  if (Array.isArray(value)) return new Float32Array(value as number[]);
+  return undefined;
+}
+
+function indexArray(value: unknown): Uint16Array | Uint32Array | undefined {
+  if (value instanceof Uint16Array || value instanceof Uint32Array) return value;
+  if (ArrayBuffer.isView(value) || Array.isArray(value)) {
+    const values = Array.from(value as unknown as ArrayLike<number>);
+    return values.some((entry) => entry > 0xffff)
+      ? new Uint32Array(values)
+      : new Uint16Array(values);
+  }
+  return undefined;
+}
+
+function integerAttribute(value: unknown): Uint16Array | undefined {
+  if (value instanceof Uint16Array) return value;
+  if (Array.isArray(value) || ArrayBuffer.isView(value)) {
+    return new Uint16Array(Array.from(value as unknown as ArrayLike<number>));
+  }
+  return undefined;
+}
+
+function morphTarget(value: unknown): MorphTarget | undefined {
+  if (value === null || typeof value !== 'object') return undefined;
+  const source = value as Record<string, unknown>;
+  const position = floatArray(source.position);
+  const normal = floatArray(source.normal);
+  const tangent = floatArray(source.tangent);
+  return {
+    ...(position === undefined ? {} : { position }),
+    ...(normal === undefined ? {} : { normal }),
+    ...(tangent === undefined ? {} : { tangent }),
+  };
+}
+
+function meshPayload(value: unknown): MeshAsset | undefined {
+  if (value === null || typeof value !== 'object') return undefined;
+  const source = value as Record<string, unknown>;
+  const vertices = floatArray(source.vertices);
+  const rawAttributes = source.attributes;
+  const rawSubmeshes = source.submeshes;
+  const rawMaterialSlots = source.materialSlots;
+  if (
+    source.kind !== 'mesh' ||
+    vertices === undefined ||
+    rawAttributes === null ||
+    typeof rawAttributes !== 'object' ||
+    !Array.isArray(rawSubmeshes) ||
+    !Array.isArray(rawMaterialSlots)
+  ) {
+    return undefined;
+  }
+  const attributes: VertexAttributeMap = {};
+  const sourceAttributes = rawAttributes as Record<string, unknown>;
+  for (const key of ATTRIBUTE_KEYS) {
+    const raw = sourceAttributes[key];
+    if (raw === undefined) continue;
+    const converted = key === 'skinIndex' ? integerAttribute(raw) : floatArray(raw);
+    if (converted !== undefined) attributes[key] = converted;
+  }
+  const indices = indexArray(source.indices);
+  const aabb = floatArray(source.aabb);
+  const morphWeights = floatArray(source.morphWeights);
+  const morphTargets = Array.isArray(source.morphTargets)
+    ? source.morphTargets.flatMap((target) => {
+        const converted = morphTarget(target);
+        return converted === undefined ? [] : [converted];
+      })
+    : undefined;
+  return {
+    kind: 'mesh',
+    vertices,
+    ...(indices === undefined ? {} : { indices }),
+    attributes,
+    ...(aabb === undefined ? {} : { aabb }),
+    submeshes: rawSubmeshes as MeshAsset['submeshes'],
+    materialSlots: rawMaterialSlots as MeshAsset['materialSlots'],
+    ...(morphTargets === undefined ? {} : { morphTargets }),
+    ...(morphWeights === undefined ? {} : { morphWeights }),
+  };
+}
+
+export const normalizedMeshAssetDecoder: AssetDecoder<MeshAsset> = {
+  async decode(input): Promise<Result<MeshAsset, AssetLoadError>> {
+    const body = input.envelope.artifacts.body;
+    if (body !== undefined) {
+      const bytes = await input.artifacts.read(body);
+      if (!bytes.ok) return bytes;
+    }
+    const payload = meshPayload(input.envelope.payload);
+    if (payload === undefined) {
+      return err({
+        code: 'asset-package-invalid',
+        expected: 'a JSON-safe mesh payload that can be owned by Geometry',
+        hint: 'recook the mesh payload with typed vertex and attribute fields',
+        detail: { guid: input.envelope.guid, reason: 'mesh payload normalization failed' },
+      });
+    }
+    return meshAssetDecoder.decode({
+      ...input,
+      envelope: { ...input.envelope, payload },
+    });
+  },
+};
+
+export function installMeshDecoder(assets: AssetRegistry) {
+  return assets.installDecoder(meshAssetKind, normalizedMeshAssetDecoder);
+}
+
+export function installPassthroughDecoder(assets: AssetRegistry, kind: string) {
+  const token: AssetKind<Record<string, unknown>, string> = {
+    kind,
+  } as AssetKind<Record<string, unknown>, string>;
+  return assets.installDecoder(token, {
+    async decode({ envelope }) {
+      return ok(envelope.payload);
+    },
+  });
+}
+
+export function createAssetRuntimeFixture(
+  sourceAssets: readonly FixtureAsset[],
+  options: AssetRuntimeFixtureOptions = {},
+): AssetRegistry {
+  const packageUrl = options.packageUrl ?? 'https://assets.test/gltf-fixture.pack.json';
+  const artifactBytes = new Map<string, Uint8Array>();
+  const runtimeAssets = sourceAssets.map((asset) => {
+    const artifacts = Object.fromEntries(
+      Object.entries(asset.artifacts).map(([key, body]) => {
+        const path = `${asset.guid}/${key}.bin`;
+        const url = new URL(path, packageUrl).toString();
+        artifactBytes.set(
+          url,
+          options.artifactOverrides?.get(`${asset.guid}:${key}`) ?? body.bytes,
+        );
+        return [
+          key,
+          {
+            path,
+            mediaType: body.mediaType,
+            contentEncoding: 'identity' as const,
+            byteLength: body.bytes.byteLength,
+            integrity: { algorithm: 'sha256' as const, digest: sha256(body.bytes) },
+            ...(body.assetCodec === undefined ? {} : { assetCodec: body.assetCodec }),
+          },
+        ];
+      }),
+    );
+    return {
+      guid: asset.guid,
+      kind: asset.kind,
+      ...(asset.name === undefined ? {} : { name: asset.name }),
+      payload: normaliseForPack(asset.payload) as Record<string, unknown>,
+      refs: asset.refs,
+      artifacts,
+    };
+  });
+  const pack = {
+    schemaVersion: '2.0.0' as const,
+    kind: 'internal-text-package' as const,
+    scopeId: SCOPE_ID,
+    generation: GENERATION,
+    digest: PACK_DIGEST,
+    outputSetDigest: OUTPUT_SET_DIGEST,
+    assets: runtimeAssets,
+  };
+  const fetcher: typeof globalThis.fetch = async (input) => {
+    const url = String(input);
+    if (url === packageUrl) return new Response(JSON.stringify(pack));
+    const bytes = artifactBytes.get(url);
+    return bytes === undefined
+      ? new Response('not found', { status: 404 })
+      : new Response(bytes as unknown as BodyInit);
+  };
+  return createAssetRegistry({
+    catalog: createCatalogSource({
+      entries: sourceAssets.map((asset) => row(asset, packageUrl)),
+    }),
+    fetcher,
+    scopeId: SCOPE_ID,
+    generation: GENERATION,
+  });
+}

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' });
+  });
+});