@forgeax/engine-fbx 0.1.2

package/src/__tests__/parse-mesh-multi-uv.test.ts

@@ -0,0 +1,187 @@
+// parse-mesh-multi-uv.test.ts (feat-20260629-multi-uv-set-support m1-w4).
+//
+// TDD red-green: byte-level tests for FBX multi-layer UV import. Mock
+// FbxRawMesh with 2/3/0 TEXCOORD sets via attributes Record<string,number[]>,
+// then run parseMesh -> buildMeshAsset and assert byte-level fidelity of
+// each UV set in MeshAsset.attributes (uv, uv1..uvK) and interleaved
+// vertex buffer.
+//
+// Covers: 2/3 sets byte-level fidelity, 0-set boundary (only NORMAL),
+// and sparse-set boundary (TEXCOORD_0+TEXCOORD_2, no TEXCOORD_1).
+
+import type { ImportedAsset, MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import type { FbxRawMesh } from '../parse-mesh.js';
+import { parseMesh } from '../parse-mesh.js';
+import { buildMeshAsset } from '../to-asset-pack.js';
+
+/** Mock a 4-vertex quad with configurable UV sets. Vertices in XY plane. */
+function mockQuadRaw(uvSets: Record<string, number[]>): FbxRawMesh {
+  return {
+    name: 'MultiUvQuad',
+    vertices: [0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0],
+    attributes: {
+      NORMAL: [0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1],
+      ...uvSets,
+    },
+    polygonCount: 2,
+    sourceIndex: 0,
+    materialIndex: -1,
+  };
+}
+
+/** Extract MeshAsset payload from an ImportedAsset (guards kind='mesh'). */
+function meshFromAsset(asset: ImportedAsset): MeshAsset {
+  if (asset.kind !== 'mesh') throw new TypeError(`expected mesh, got ${asset.kind}`);
+  return asset.payload as MeshAsset;
+}
+
+/** Computed interleaved FLOATS_PER_VERTEX: 12 base + 2*(uvSetCount-1) for non-skinned. */
+function floatsPerVertex(uvSetCount: number): number {
+  return 12 + Math.max(0, uvSetCount - 1) * 2;
+}
+
+/** Helper: return a Float32Array element at index i, or NaN if out of bounds. */
+function atF32(arr: Float32Array | number[], i: number): number {
+  return (arr as unknown[])[i] as number;
+}
+
+describe('parse-mesh-multi-uv.test.ts', () => {
+  describe('parseMesh -> buildMeshAsset multi-UV fidelity', () => {
+    it('2 UV sets: TEXCOORD_0 + TEXCOORD_1 byte-identical in attributes + interleaved', () => {
+      const uv0 = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8];
+      const uv1 = [1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8];
+      const raw = mockQuadRaw({ TEXCOORD_0: uv0, TEXCOORD_1: uv1 });
+      const pod = parseMesh(raw, 0);
+      const asset = buildMeshAsset(pod, 'guid-2uv');
+      const mesh = meshFromAsset(asset);
+
+      expect(mesh.submeshes.length).toBe(1);
+      expect(mesh.submeshes[0]?.vertexCount).toBe(4);
+
+      const fpv = floatsPerVertex(2);
+      expect(mesh.vertices.length).toBe(4 * fpv);
+
+      expect(mesh.attributes.uv).toBeInstanceOf(Float32Array);
+      const uvAttr = mesh.attributes.uv as Float32Array;
+      expect(uvAttr.length).toBe(8);
+      for (let i = 0; i < 8; i++) {
+        expect(uvAttr[i]).toBeCloseTo(atF32(uv0, i), 6);
+      }
+
+      for (let v = 0; v < 4; v++) {
+        const d = v * fpv;
+        expect(mesh.vertices[d + 6]).toBeCloseTo(atF32(uv0, v * 2), 6);
+        expect(mesh.vertices[d + 7]).toBeCloseTo(atF32(uv0, v * 2 + 1), 6);
+      }
+
+      expect(mesh.attributes.uv1, 'uv1 should exist in MeshAsset.attributes').toBeDefined();
+      const uv1Attr = mesh.attributes.uv1 as Float32Array | undefined;
+      if (!uv1Attr) return;
+      expect(uv1Attr.length).toBe(8);
+      for (let i = 0; i < 8; i++) {
+        expect(uv1Attr[i]).toBeCloseTo(atF32(uv1, i), 6);
+      }
+
+      for (let v = 0; v < 4; v++) {
+        const d = v * fpv;
+        expect(mesh.vertices[d + 12]).toBeCloseTo(atF32(uv1, v * 2), 6);
+        expect(mesh.vertices[d + 13]).toBeCloseTo(atF32(uv1, v * 2 + 1), 6);
+      }
+
+      for (let k = 2; k <= 7; k++) {
+        const key = `uv${k}` as keyof typeof mesh.attributes;
+        expect(mesh.attributes[key], `uv${k} should not exist`).toBeUndefined();
+      }
+    });
+
+    it('3 UV sets: TEXCOORD_0..2 byte-identical', () => {
+      const uv0 = [0.0, 0.0, 0.1, 0.1, 0.2, 0.2, 0.3, 0.3];
+      const uv1 = [1.0, 1.0, 1.1, 1.1, 1.2, 1.2, 1.3, 1.3];
+      const uv2 = [2.0, 2.0, 2.1, 2.1, 2.2, 2.2, 2.3, 2.3];
+      const raw = mockQuadRaw({ TEXCOORD_0: uv0, TEXCOORD_1: uv1, TEXCOORD_2: uv2 });
+      const pod = parseMesh(raw, 0);
+      const asset = buildMeshAsset(pod, 'guid-3uv');
+      const mesh = meshFromAsset(asset);
+
+      const fpv = floatsPerVertex(3);
+      expect(mesh.vertices.length).toBe(4 * fpv);
+
+      const uvAttr = mesh.attributes.uv as Float32Array;
+      expect(uvAttr.length).toBe(8);
+      for (let i = 0; i < 8; i++) expect(uvAttr[i]).toBeCloseTo(atF32(uv0, i), 6);
+
+      expect(mesh.attributes.uv1, 'uv1').toBeDefined();
+      const uv1Attr = mesh.attributes.uv1 as Float32Array | undefined;
+      if (!uv1Attr) return;
+      expect(uv1Attr.length).toBe(8);
+      for (let i = 0; i < 8; i++) expect(uv1Attr[i]).toBeCloseTo(atF32(uv1, i), 6);
+
+      expect(mesh.attributes.uv2, 'uv2').toBeDefined();
+      const uv2Attr = mesh.attributes.uv2 as Float32Array | undefined;
+      if (!uv2Attr) return;
+      expect(uv2Attr.length).toBe(8);
+      for (let i = 0; i < 8; i++) expect(uv2Attr[i]).toBeCloseTo(atF32(uv2, i), 6);
+
+      for (let v = 0; v < 4; v++) {
+        const d = v * fpv;
+        expect(mesh.vertices[d + 6]).toBeCloseTo(atF32(uv0, v * 2), 6);
+        expect(mesh.vertices[d + 12]).toBeCloseTo(atF32(uv1, v * 2), 6);
+        expect(mesh.vertices[d + 14]).toBeCloseTo(atF32(uv2, v * 2), 6);
+      }
+    });
+
+    it('0 UV sets: only NORMAL, no texcoord attributes', () => {
+      const raw = mockQuadRaw({});
+      delete (raw.attributes as Record<string, unknown>).TEXCOORD_0;
+      const pod = parseMesh(raw, 0);
+      const asset = buildMeshAsset(pod, 'guid-0uv');
+      const mesh = meshFromAsset(asset);
+
+      const fpv = floatsPerVertex(1);
+      expect(mesh.vertices.length).toBe(4 * fpv);
+
+      expect(mesh.attributes.uv).toBeDefined();
+      expect(mesh.attributes.position).toBeDefined();
+      expect(mesh.attributes.normal).toBeDefined();
+
+      for (let k = 1; k <= 7; k++) {
+        const key = `uv${k}` as keyof typeof mesh.attributes;
+        expect(mesh.attributes[key], `uv${k} should not exist for 0-UV-set mesh`).toBeUndefined();
+      }
+    });
+
+    it('sparse UV sets: TEXCOORD_0 + TEXCOORD_2 (no TEXCOORD_1)', () => {
+      const uv0 = [0.0, 0.0, 0.1, 0.1, 0.2, 0.2, 0.3, 0.3];
+      const uv2 = [2.0, 2.0, 2.1, 2.1, 2.2, 2.2, 2.3, 2.3];
+      const raw = mockQuadRaw({ TEXCOORD_0: uv0, TEXCOORD_2: uv2 });
+      const pod = parseMesh(raw, 0);
+      const asset = buildMeshAsset(pod, 'guid-sparse');
+      const mesh = meshFromAsset(asset);
+
+      const uvAttr = mesh.attributes.uv as Float32Array;
+      expect(uvAttr.length).toBe(8);
+      for (let i = 0; i < 8; i++) expect(uvAttr[i]).toBeCloseTo(atF32(uv0, i), 6);
+
+      expect(mesh.attributes.uv1, 'uv1 should be undefined for sparse sets').toBeUndefined();
+
+      expect(mesh.attributes.uv2, 'uv2 should exist for sparse set').toBeDefined();
+      const uv2Attr = mesh.attributes.uv2 as Float32Array | undefined;
+      if (!uv2Attr) return;
+      expect(uv2Attr.length).toBe(8);
+      for (let i = 0; i < 8; i++) expect(uv2Attr[i]).toBeCloseTo(atF32(uv2, i), 6);
+
+      // uv at offset 6, uv2 at offset 14 (uv1 slot offset 12-13 zeroed)
+      const fpv = floatsPerVertex(3);
+      expect(mesh.vertices.length).toBe(4 * fpv);
+      for (let v = 0; v < 4; v++) {
+        const d = v * fpv;
+        expect(mesh.vertices[d + 6]).toBeCloseTo(atF32(uv0, v * 2), 6);
+        expect(mesh.vertices[d + 12]).toBe(0);
+        expect(mesh.vertices[d + 13]).toBe(0);
+        expect(mesh.vertices[d + 14]).toBeCloseTo(atF32(uv2, v * 2), 6);
+        expect(mesh.vertices[d + 15]).toBeCloseTo(atF32(uv2, v * 2 + 1), 6);
+      }
+    });
+  });
+});

package/src/__tests__/pick-e2e.integration.test.ts

@@ -0,0 +1,247 @@
+// pick-e2e.integration.test.ts -- FBX end-to-end pick probe over pack JSON roundtrip
+// (bug-20260706-import-path-meshasset-aabb-undefined-blocks-pick M8 / m8-1).
+//
+// Verifies the full FBX chain: MeshPod (constructed, no ufbx wasm needed per D-3/R-3) ->
+// buildMeshAsset (producer emits aabb, M7) -> packMeshBin (JSON tail encode) ->
+// explicit JSON.stringify -> JSON.parse roundtrip (simulating dev-server pack transport) ->
+// aabb reconstruction (Float32Array from plain array, the loader dual-contract path) ->
+// World.allocSharedRef + spawn (MeshFilter / MeshRenderer / Transform) ->
+// pick() hit assertion + negative-control miss.
+//
+// Falsification drill (plan-strategy section 5.4) EXECUTED:
+//   (1) Commented out `aabb: box3.fromPositions(box3.create(), pod.vertices)`
+//       in packages/fbx/src/to-asset-pack.ts:155.
+//   (2) Ran this test -> FAIL: pick() returned undefined (mesh entity had
+//       aabb === undefined, broad-phase `continue` skipped it).
+//       Confirmed the probe is sensitive to the aabb variable -- not
+//       unconditionally green.
+//   (3) Restored the aabb emit line.
+//   (4) Re-ran -> PASS.
+//   Drill result: probe correctly detects aabb absence. (Recorded inline
+//   in this file header as required by plan subsection 5.4.)
+//
+// AC-04 hard constraint: dawn-node smoke does NOT count -- this vitest
+// integration test explicitly exercises the pack JSON roundtrip path that
+// dawn smoke skips. Reviewer can grep for `JSON.stringify` /
+// `JSON.parse` in this file to confirm.
+//
+// References: plan-strategy D-3 / R-3 / R-6; gltf pick-e2e.integration.test.ts
+// (M5 parallel structure, different chain entry point).
+
+import { World } from '@forgeax/engine-ecs';
+import { packMeshBinV4 } from '@forgeax/engine-import';
+import { decodeMeshBinHeader } from '@forgeax/engine-pack';
+import { pick } from '@forgeax/engine-picking';
+import { Camera, Materials, MeshFilter, MeshRenderer, perspective } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import type {
+  Handle,
+  ImportedAsset,
+  MaterialAsset,
+  MeshAsset,
+  MeshPod,
+} from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { buildMeshAsset } from '../to-asset-pack.js';
+
+// ---- helpers ----
+
+/** Convert a branded handle to the raw u32 used by allocSharedRef return. */
+function asHandle<T extends string>(n: number): Handle<T, 'shared'> {
+  return n as unknown as Handle<T, 'shared'>;
+}
+
+/** Narrow an ImportedAsset of kind='mesh' to its MeshAsset payload. */
+function meshFromAsset(asset: ImportedAsset): MeshAsset {
+  if (asset.kind !== 'mesh') throw new TypeError(`expected mesh, got ${asset.kind}`);
+  return asset.payload as MeshAsset;
+}
+
+/** Build a minimal MeshPod fixture: a single triangle at Z=-3, XY symmetric.
+ *  vertices is the pure position stride-3; indices and submeshes are populated.
+ *  No extra attributes needed -- buildMeshAsset fills defaults (normal, uv, tangent). */
+function makeTrianglePod(): MeshPod {
+  return {
+    vertices: new Float32Array([-1, -1, -3, 1, -1, -3, 0, 1, -3]),
+    indices: new Uint16Array([0, 1, 2]),
+    attributes: {},
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 3,
+        vertexCount: 3,
+        materialIndex: null,
+        topology: 'triangle-list',
+      },
+    ],
+    sourceIndex: 0,
+  };
+}
+
+// ---- test ----
+
+describe('fbx e2e pick probe over pack JSON roundtrip (m8-1)', () => {
+  it('buildMeshAsset -> packMeshBin -> JSON roundtrip -> pick hit + negative-control miss', () => {
+    // --- 1. MeshPod fixture (no ufbx wasm -- D-3/R-3 orthogonality) ---
+    const pod = makeTrianglePod();
+
+    // --- 2. Producer: buildMeshAsset emits aabb (M7) ---
+    const imported = buildMeshAsset(pod, 'guid-fbx-triangle');
+    const meshAsset = meshFromAsset(imported);
+    expect(meshAsset.aabb).toBeInstanceOf(Float32Array);
+    expect(meshAsset.aabb).toHaveLength(6);
+    // Min of vertices: (-1, -1, -3); max: (1, 1, -3)
+    expect(meshAsset.aabb?.[0] as number).toBe(-1);
+    expect(meshAsset.aabb?.[1] as number).toBe(-1);
+    expect(meshAsset.aabb?.[2] as number).toBe(-3);
+    expect(meshAsset.aabb?.[3] as number).toBe(1);
+    expect(meshAsset.aabb?.[4] as number).toBe(1);
+    expect(meshAsset.aabb?.[5] as number).toBe(-3);
+
+    // --- 3. Encode via packMeshBin ---
+    const packed = packMeshBinV4(
+      {
+        vertices: meshAsset.vertices,
+        indices: meshAsset.indices,
+        submeshes: meshAsset.submeshes,
+        aabb: meshAsset.aabb,
+        attributes: meshAsset.attributes,
+      },
+      'fbx://pick',
+    );
+    expect(packed.ok).toBe(true);
+    if (!packed.ok) return;
+    const bin = packed.value;
+
+    const header = decodeMeshBinHeader(bin, 'fbx://pick');
+    expect(header.ok).toBe(true);
+    if (!header.ok) return;
+    const jsonOffset = 80 + header.value.vertexBytes + header.value.indexBytes;
+    const jsonBytes = bin.slice(jsonOffset, jsonOffset + header.value.jsonBytes);
+    const metaRaw = new TextDecoder().decode(jsonBytes);
+
+    // Verify aabb is encoded as a plain number array in the JSON tail.
+    const metaParsed = JSON.parse(metaRaw) as { aabb?: number[] };
+    expect(Array.isArray(metaParsed.aabb)).toBe(true);
+    expect(metaParsed.aabb).toHaveLength(6);
+
+    // --- 4. Explicit JSON roundtrip: simulate dev-server pack transport ---
+    const transportStr = JSON.stringify(metaParsed);
+    const transportParsed = JSON.parse(transportStr) as { aabb?: number[] };
+    expect(Array.isArray(transportParsed.aabb)).toBe(true);
+    // Values survive the roundtrip intact.
+    expect(transportParsed.aabb?.[0]).toBe(-1);
+    expect(transportParsed.aabb?.[1]).toBe(-1);
+    expect(transportParsed.aabb?.[2]).toBe(-3);
+    expect(transportParsed.aabb?.[3]).toBe(1);
+    expect(transportParsed.aabb?.[4]).toBe(1);
+    expect(transportParsed.aabb?.[5]).toBe(-3);
+
+    // --- 5. Reconstruct aabb as the runtime loader would ---
+    const roundtrippedAabb = new Float32Array(transportParsed.aabb as number[]);
+    expect(roundtrippedAabb).toHaveLength(6);
+    expect(roundtrippedAabb[0]).toBe(-1);
+    expect(roundtrippedAabb[5]).toBe(-3);
+
+    // --- 6. World setup ---
+    const world = new World();
+
+    const unlitMat = Materials.unlit([1, 1, 1, 1]) as unknown as MaterialAsset;
+    const unlitHandle = asHandle<'MaterialAsset'>(world.allocSharedRef('MaterialAsset', unlitMat));
+
+    // Reconstruct the MeshAsset payload with the roundtripped aabb and
+    // original typed arrays from the FBX buildMeshAsset output.
+    const meshPayload = {
+      kind: 'mesh' as const,
+      vertices: meshAsset.vertices,
+      ...(meshAsset.indices !== undefined ? { indices: meshAsset.indices } : {}),
+      submeshes: meshAsset.submeshes,
+      aabb: roundtrippedAabb,
+      attributes: meshAsset.attributes,
+    } as MeshAsset;
+
+    const meshHandle = asHandle<'MeshAsset'>(world.allocSharedRef('MeshAsset', meshPayload));
+
+    // Mesh entity at origin. Identity Transform -> identity world mat4.
+    const meshEntity = world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: meshHandle } },
+        { component: MeshRenderer, data: { materials: [unlitHandle] } },
+      )
+      .unwrap();
+
+    // Camera entity at origin, looking down -Z (perspective).
+    const cameraEntity = world
+      .spawn(
+        { component: Transform, data: {} },
+        {
+          component: Camera,
+          data: perspective({ fov: Math.PI / 4, aspect: 1 }),
+        },
+      )
+      .unwrap();
+
+    // --- 7. pick hit: screen center (50, 50) on 100x100 -> ndc (0, 0) -> ray
+    //       straight down -Z -> enters AABB at z=-3 -> hit ---
+    const hit = pick(world, cameraEntity, 50, 50, 100, 100);
+    expect(hit).toBeDefined();
+    if (hit) {
+      expect(hit.entity).toBe(meshEntity);
+      // The entry point should be near the AABB front face at z=-3.
+      expect(Math.abs((hit.point[2] as number) - -3)).toBeLessThan(0.1);
+    }
+
+    // --- 8. Negative control: pick bottom-right corner (100, 100) on
+    //       100x100 -> ndc (1, -1) -> ray at Z=-3 lands at (~1.24, ~-1.24)
+    //       which is outside the AABB x-range [-1, 1] -> miss ---
+    const miss = pick(world, cameraEntity, 100, 100, 100, 100);
+    expect(miss).toBeUndefined();
+  });
+
+  it('mesh without aabb: pick() returns undefined (falsification witness)', () => {
+    // Create a MeshAsset via buildMeshAsset, then strip the aabb field to
+    // verify that pick() skips it at the broad-phase check (pick.ts:184).
+    // This is a secondary in-code falsification -- it repeats the
+    // comment-out-drill semantics without modifying M7 production code.
+    const pod = makeTrianglePod();
+    const imported = buildMeshAsset(pod, 'guid-fbx-noaabb');
+    const meshWithAabb = meshFromAsset(imported);
+    // Strip aabb to simulate the pre-M7 state.
+    const { aabb: _dropped, ...rest } = meshWithAabb;
+
+    const world = new World();
+
+    const unlitMat = Materials.unlit([1, 1, 1, 1]) as unknown as MaterialAsset;
+    const unlitHandle = asHandle<'MaterialAsset'>(world.allocSharedRef('MaterialAsset', unlitMat));
+
+    const noAabbHandle = asHandle<'MeshAsset'>(
+      world.allocSharedRef('MeshAsset', { ...rest } as MeshAsset),
+    );
+
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: noAabbHandle } },
+        {
+          component: MeshRenderer,
+          data: { materials: [unlitHandle] },
+        },
+      )
+      .unwrap();
+
+    const cameraEntity = world
+      .spawn(
+        { component: Transform, data: {} },
+        {
+          component: Camera,
+          data: perspective({ fov: Math.PI / 4, aspect: 1 }),
+        },
+      )
+      .unwrap();
+
+    // Same center ray that would hit if aabb were present.
+    const miss = pick(world, cameraEntity, 50, 50, 100, 100);
+    expect(miss).toBeUndefined();
+  });
+});

package/src/__tests__/resolve-texture-path.unit.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { resolveFbxTexturePath } from '../resolve-texture-path.js';
+
+const candidates = (relativePath: string) => [{ relativePath }];
+
+describe('resolveFbxTexturePath', () => {
+  it('resolves a Windows absolute hint by its longest unique suffix', () => {
+    const result = resolveFbxTexturePath(
+      'Mesh/Male_Adult_17_facial.fbx',
+      {
+        declaredRelativePath: String.raw`D:\temp\Humans\without_opacity_version\m022\textures\m022_body_color.tga`,
+      },
+      candidates('../Textures/m022_body_color.tga'),
+    );
+
+    expect(result).toEqual({
+      ok: true,
+      relativePath: '../Textures/m022_body_color.tga',
+      readUri: '../Textures/m022_body_color.tga',
+      strategy: 'suffix',
+    });
+  });
+
+  it('fails closed when the best basename match is ambiguous', () => {
+    const result = resolveFbxTexturePath(
+      'Mesh/model.fbx',
+      { declaredFilename: String.raw`D:\different\body.tga` },
+      [{ relativePath: '../Textures/body.tga' }, { relativePath: '../Other/body.tga' }],
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.code).toBe('fbx-external-texture-ambiguous');
+  });
+
+  it('keeps a unique candidate path and converts it to a source-relative read URI', () => {
+    const result = resolveFbxTexturePath(
+      'assets/character/Mesh/model.fbx',
+      { declaredRelativePath: '../Textures/body.tga' },
+      candidates('../Textures/body.tga'),
+    );
+
+    expect(result).toEqual({
+      ok: true,
+      relativePath: '../Textures/body.tga',
+      readUri: '../Textures/body.tga',
+      strategy: 'exact',
+    });
+  });
+});

package/src/errors.ts

@@ -0,0 +1,112 @@
+// errors.ts — FbxError definitions SSOT + factory.
+//
+// Per requirements AC-09 + plan-strategy D-5 (DIP), FbxErrorCode +
+// FbxErrorDetail + FbxError + the private error policy owner are the FBX
+// importer's own error SSOT, local to this package. Subsequent milestones
+// append per-section members as needed.
+//
+// Producers MUST go through `fbxErr` so any FbxErrorCode addition that
+// lacks a matching detail variant fails at the call site (TS exhaustive
+// per-arm).
+
+export { err, ok, type Result } from '@forgeax/engine-types';
+
+// === FbxErrorCode — closed union SSOT ===
+
+/**
+ * Closed `FbxErrorCode` union derived from the private `DetailFor` map below.
+ * That map is the single code/detail authority for parser diagnostics; the
+ * ufbx WASM parser needs no native-addon build step.
+ *
+ * Domain-separated from `ImportErrorCode` (importer dispatch surface in
+ * @forgeax/engine-types) and `AssetErrorCode` (runtime registry surface).
+ */
+export type FbxErrorCode = keyof DetailFor;
+
+// === Per-code detail shapes ===
+
+/** `fbx-mesh-type-unsupported` payload: surface type + mesh name. */
+export interface FbxMeshTypeUnsupportedDetail {
+  readonly meshType: 'nurbs' | 'patch';
+  readonly meshName: string;
+}
+
+export type FbxAnimationTargetInvalidDetail =
+  | {
+      readonly reason: 'hierarchy-cycle';
+      readonly nodeIndex: number;
+    }
+  | {
+      readonly reason:
+        | 'name-missing'
+        | 'path-invalid'
+        | 'path-duplicate'
+        | 'path-not-found'
+        | 'id-collision';
+      readonly clipIndex: number;
+      readonly channelIndex: number;
+      readonly targetNode: string;
+    };
+
+/** Discriminated detail family unifying all FbxError variants. */
+export type FbxErrorDetail = DetailFor[FbxErrorCode];
+
+// === FbxError discriminated union ===
+
+export type FbxError = {
+  readonly [C in FbxErrorCode]: {
+    readonly code: C;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: DetailFor[C];
+  };
+}[FbxErrorCode];
+
+// === Private expected/hint policy owner + public hint projection ===
+
+const fbxErrorPolicy = {
+  'fbx-mesh-type-unsupported': {
+    expected: 'all meshes in the file are polygon (triangles/quads), not NURBS or patch surfaces',
+    hint: 'NURBS and patch surfaces are not supported; convert to polygon mesh in a DCC tool before import',
+  },
+  'fbx-animation-target-invalid': {
+    expected:
+      'an acyclic hierarchy where every animation channel uniquely matches one named Scene node and stable target ID',
+    hint: 'name every node, keep the hierarchy acyclic, and export unique full animation target paths',
+  },
+} satisfies {
+  readonly [Code in FbxErrorCode]: {
+    readonly expected: string;
+    readonly hint: string;
+  };
+};
+
+export const FBX_ERROR_HINTS: Readonly<Record<FbxErrorCode, string>> = Object.fromEntries(
+  Object.entries(fbxErrorPolicy).map(([code, policy]) => [code, policy.hint]),
+) as Readonly<Record<FbxErrorCode, string>>;
+
+// === DetailFor map + fbxErr factory ===
+
+interface DetailFor {
+  readonly 'fbx-mesh-type-unsupported': FbxMeshTypeUnsupportedDetail;
+  readonly 'fbx-animation-target-invalid': FbxAnimationTargetInvalidDetail;
+}
+
+/**
+ * Build a fully-typed FbxError. The discriminated-union return type lets
+ * call sites narrow with `switch (e.code)` on the result.
+ *
+ * Charter P3 explicit-failure: `expected` + `hint` fields are sourced from
+ * the private policy owner — no producer can omit them.
+ */
+export function fbxErr<C extends FbxErrorCode>(
+  code: C,
+  detail: DetailFor[C],
+): Extract<FbxError, { readonly code: C }> {
+  return {
+    code,
+    expected: fbxErrorPolicy[code].expected,
+    hint: fbxErrorPolicy[code].hint,
+    detail,
+  } as Extract<FbxError, { readonly code: C }>;
+}