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

package/src/__tests__/vertex-attribute-layout-owner.unit.test.ts

@@ -0,0 +1,181 @@
+import {
+  buildMeshAttributeMapForUvSets,
+  deriveVertexBufferLayout,
+  deriveVertexLayoutProjection,
+  deriveVertexLayoutProjectionFromMask,
+  packInterleavedVertexAttributes,
+} from '@forgeax/engine-geometry';
+import type { VertexAttributeMap } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+const makeBuffer = (): Float32Array => new Float32Array(0);
+
+function makeCompleteAttributeMap(): VertexAttributeMap {
+  return {
+    position: makeBuffer(),
+    normal: makeBuffer(),
+    uv: makeBuffer(),
+    tangent: makeBuffer(),
+    skinIndex: new Uint16Array(0).buffer,
+    skinWeight: makeBuffer(),
+    uv1: makeBuffer(),
+    uv2: makeBuffer(),
+    uv3: makeBuffer(),
+    uv4: makeBuffer(),
+    uv5: makeBuffer(),
+    uv6: makeBuffer(),
+    uv7: makeBuffer(),
+  };
+}
+
+describe('vertex attribute layout owner', () => {
+  it('derives the complete 13-key layout from the format owner', () => {
+    expect(deriveVertexBufferLayout(makeCompleteAttributeMap())).toEqual([
+      {
+        arrayStride: 128,
+        attributes: [
+          { shaderLocation: 0, offset: 0, format: 'float32x3' },
+          { shaderLocation: 1, offset: 12, format: 'float32x3' },
+          { shaderLocation: 2, offset: 24, format: 'float32x2' },
+          { shaderLocation: 3, offset: 32, format: 'float32x4' },
+          { shaderLocation: 4, offset: 48, format: 'uint16x4' },
+          { shaderLocation: 5, offset: 56, format: 'float32x4' },
+          { shaderLocation: 6, offset: 72, format: 'float32x2' },
+          { shaderLocation: 7, offset: 80, format: 'float32x2' },
+          { shaderLocation: 8, offset: 88, format: 'float32x2' },
+          { shaderLocation: 9, offset: 96, format: 'float32x2' },
+          { shaderLocation: 10, offset: 104, format: 'float32x2' },
+          { shaderLocation: 11, offset: 112, format: 'float32x2' },
+          { shaderLocation: 12, offset: 120, format: 'float32x2' },
+        ],
+      },
+    ]);
+  });
+
+  it('projects color as host location 13 without moving the existing 0..12 keys', () => {
+    const map: VertexAttributeMap = {
+      position: new Float32Array([0, 0, 0]),
+      normal: new Float32Array([0, 1, 0]),
+      uv: new Float32Array([0, 0]),
+      tangent: new Float32Array([1, 0, 0, 1]),
+      color: new Float32Array([0.25, 0.5, 0.75, 1]),
+    };
+    const projection = deriveVertexLayoutProjection(map);
+
+    expect(projection.attributes.map((entry) => entry.key)).toEqual([
+      'position',
+      'normal',
+      'uv',
+      'tangent',
+      'color',
+    ]);
+    expect(projection.attributes.find((entry) => entry.key === 'color')).toMatchObject({
+      shaderLocation: 13,
+      offset: 48,
+      format: 'float32x4',
+    });
+    expect(projection.arrayStride).toBe(64);
+    expect(projection.mask).toBe(0x200f);
+    expect(projection.digest).toBe('vlp-v1-6586e1c9');
+  });
+
+  it('keeps digest independent of attribute bytes and changes it when layout changes', () => {
+    const a: VertexAttributeMap = {
+      position: new Float32Array([0, 0, 0]),
+      normal: new Float32Array([0, 1, 0]),
+      uv: new Float32Array([0, 0]),
+      tangent: new Float32Array([1, 0, 0, 1]),
+      color: new Float32Array([1, 0, 0, 1]),
+    };
+    const b: VertexAttributeMap = { ...a, color: new Float32Array([0, 1, 0, 1]) };
+    const c: VertexAttributeMap = { ...a, uv1: new Float32Array([0, 0]) };
+
+    expect(deriveVertexLayoutProjection(a).digest).toBe(deriveVertexLayoutProjection(b).digest);
+    expect(deriveVertexLayoutProjection(a).digest).not.toBe(deriveVertexLayoutProjection(c).digest);
+  });
+
+  it('reconstructs wire masks through the same canonical projection owner', () => {
+    const color = deriveVertexLayoutProjectionFromMask(1 << 13);
+    expect(color.ok).toBe(true);
+    if (!color.ok) return;
+    expect(color.value.attributes.map((entry) => entry.key)).toEqual(['color']);
+
+    const empty = deriveVertexLayoutProjectionFromMask(0);
+    expect(empty.ok).toBe(false);
+    if (!empty.ok) expect(empty.error.detail.reason).toBe('empty');
+
+    const unknown = deriveVertexLayoutProjectionFromMask(1 << 14);
+    expect(unknown.ok).toBe(false);
+    if (!unknown.ok) expect(unknown.error.detail.reason).toBe('unknown-bits');
+  });
+
+  it('packs color/no-color using one projection and keeps no-color bytes unchanged', () => {
+    const common: VertexAttributeMap = {
+      position: new Float32Array([0, 0, 0, 1, 0, 0]),
+      normal: new Float32Array([0, 1, 0, 0, 1, 0]),
+      uv: new Float32Array([0, 0, 1, 0]),
+      tangent: new Float32Array([1, 0, 0, 1, 1, 0, 0, 1]),
+    };
+    const plain = packInterleavedVertexAttributes(common, 2);
+    const colored = packInterleavedVertexAttributes(
+      { ...common, color: new Float32Array([1, 0, 0, 1, 0, 1, 0, 1]) },
+      2,
+    );
+
+    expect(plain.ok).toBe(true);
+    expect(colored.ok).toBe(true);
+    if (!plain.ok || !colored.ok) return;
+    expect(plain.value.projection.arrayStride).toBe(48);
+    expect(colored.value.projection.arrayStride).toBe(64);
+    expect(plain.value.vertices.byteLength).toBe(96);
+    expect(colored.value.vertices.byteLength).toBe(128);
+    expect(Array.from(colored.value.vertices.slice(12, 16))).toEqual([1, 0, 0, 1]);
+    expect(Array.from(colored.value.vertices.slice(28, 32))).toEqual([0, 1, 0, 1]);
+  });
+
+  it('rejects non-RGBA, non-finite, and cardinality-mismatched color', () => {
+    expect(deriveVertexLayoutProjection({ color: new Float32Array([1, 0, 0]) }).arrayStride).toBe(
+      16,
+    );
+    const nonFinite = packInterleavedVertexAttributes(
+      { color: new Float32Array([1, Number.NaN, 0, 1]) },
+      1,
+    );
+    expect(nonFinite.ok).toBe(false);
+    if (!nonFinite.ok)
+      expect(nonFinite.error.detail).toMatchObject({ reason: 'attribute-non-finite' });
+    const mismatched = packInterleavedVertexAttributes({ color: new Float32Array(4) }, 2);
+    expect(mismatched.ok).toBe(false);
+    if (!mismatched.ok)
+      expect(mismatched.error.detail).toMatchObject({ reason: 'attribute-cardinality-mismatch' });
+    const unaligned = packInterleavedVertexAttributes(
+      { color: new ArrayBuffer(3) } as unknown as VertexAttributeMap,
+      1,
+    );
+    expect(unaligned.ok).toBe(false);
+    if (!unaligned.ok)
+      expect(unaligned.error.detail).toMatchObject({ reason: 'attribute-cardinality-mismatch' });
+  });
+
+  it('derives multi-UV keys and clamps missing shader sets to the last mesh set', () => {
+    const map = buildMeshAttributeMapForUvSets(4);
+
+    expect(Object.keys(map)).toEqual(['position', 'normal', 'uv', 'tangent', 'uv1', 'uv2', 'uv3']);
+    expect(deriveVertexBufferLayout(map, { shaderUvSetCount: 6 })).toEqual([
+      {
+        arrayStride: 72,
+        attributes: [
+          { shaderLocation: 0, offset: 0, format: 'float32x3' },
+          { shaderLocation: 1, offset: 12, format: 'float32x3' },
+          { shaderLocation: 2, offset: 24, format: 'float32x2' },
+          { shaderLocation: 3, offset: 32, format: 'float32x4' },
+          { shaderLocation: 6, offset: 48, format: 'float32x2' },
+          { shaderLocation: 7, offset: 56, format: 'float32x2' },
+          { shaderLocation: 8, offset: 64, format: 'float32x2' },
+          { shaderLocation: 9, offset: 64, format: 'float32x2' },
+          { shaderLocation: 10, offset: 64, format: 'float32x2' },
+        ],
+      },
+    ]);
+  });
+});

package/src/assets/mesh-binary.ts

@@ -0,0 +1,421 @@
+import {
+  decodeMeshBinHeader,
+  MESH_BIN_HEADER_V4_BYTES,
+  MESH_BIN_VERSION,
+  type MeshBinHeaderV4,
+} from '@forgeax/engine-pack';
+import type {
+  AssetGuid,
+  MeshAsset,
+  MeshMaterialSlot,
+  MorphTarget,
+  Submesh,
+  VertexAttributeMap,
+} from '@forgeax/engine-types';
+import { PROCEDURAL_FLOATS_PER_VERTEX } from '../box';
+import {
+  deriveVertexLayoutProjectionFromMask,
+  type VertexLayoutProjection,
+} from '../vertex-attribute-layout';
+
+interface PackedMesh {
+  readonly version: 4;
+  readonly vertices: Float32Array;
+  readonly attributes?: VertexAttributeMap;
+  readonly indices?: Uint16Array | Uint32Array;
+  readonly submeshes?: readonly Record<string, unknown>[];
+  readonly materialSlots?: readonly {
+    readonly slotName: string;
+    readonly sourceKey?: string;
+    readonly defaultMaterialRef?: number;
+  }[];
+  readonly aabb?: Float32Array;
+  readonly skinIndex?: Uint16Array;
+  readonly skinWeight?: Float32Array;
+  readonly uvSetCount: number;
+  readonly floatsPerVertex: number;
+  readonly morphTargets?: readonly MorphTarget[];
+  readonly morphWeights?: Float32Array;
+  readonly projection?: VertexLayoutProjection;
+}
+
+function parseGuid(value: string): AssetGuid | undefined {
+  const compact = value.replaceAll('-', '');
+  if (!/^[0-9a-f]{32}$/i.test(compact)) return undefined;
+  const bytes = new Uint8Array(16);
+  for (let index = 0; index < bytes.length; index += 1) {
+    const pair = compact.slice(index * 2, index * 2 + 2);
+    const parsed = Number.parseInt(pair, 16);
+    if (!Number.isInteger(parsed)) return undefined;
+    bytes[index] = parsed;
+  }
+  return bytes as AssetGuid;
+}
+
+function floatArray(value: unknown): Float32Array | undefined {
+  if (value instanceof Float32Array) return value;
+  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.length === 0 ? undefined : value;
+  }
+  if (!Array.isArray(value)) return undefined;
+  if (value.length === 0) return undefined;
+  return value.some((entry) => entry > 0xffff)
+    ? new Uint32Array(value as number[])
+    : new Uint16Array(value as number[]);
+}
+
+function integerArray(value: unknown): Uint16Array | undefined {
+  if (value instanceof Uint16Array) return value;
+  if (Array.isArray(value)) return new Uint16Array(value as number[]);
+  return undefined;
+}
+
+function morphTargets(value: unknown): readonly MorphTarget[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length === 0 || value.length > 8) return undefined;
+  const targets: MorphTarget[] = [];
+  for (const raw of value) {
+    if (raw === null || typeof raw !== 'object') return undefined;
+    const target: { position?: Float32Array; normal?: Float32Array; tangent?: Float32Array } = {};
+    for (const [key, stream] of Object.entries(raw as Record<string, unknown>)) {
+      if (key !== 'position' && key !== 'normal' && key !== 'tangent') return undefined;
+      const typed = floatArray(stream);
+      if (typed === undefined) return undefined;
+      if (key === 'position') target.position = typed;
+      else if (key === 'normal') target.normal = typed;
+      else target.tangent = typed;
+    }
+    if (Object.keys(target).length === 0) return undefined;
+    targets.push(target);
+  }
+  return targets;
+}
+
+function unpackMeshBinary(bytes: Uint8Array): PackedMesh | undefined {
+  const headerResult = decodeMeshBinHeader(bytes);
+  if (!headerResult.ok) return undefined;
+  const header: MeshBinHeaderV4 = headerResult.value;
+  const projectionResult = deriveVertexLayoutProjectionFromMask(header.mask);
+  if (!projectionResult.ok) return undefined;
+  const projection = projectionResult.value;
+  if (
+    projection.schemaVersion !== header.projectionVersion ||
+    projection.arrayStride !== header.stride ||
+    projection.digest !== header.digest
+  ) {
+    return undefined;
+  }
+  const payloadBytes = header.vertexBytes + header.indexBytes + header.jsonBytes;
+  if (MESH_BIN_HEADER_V4_BYTES + payloadBytes !== bytes.byteLength) return undefined;
+
+  let offset = MESH_BIN_HEADER_V4_BYTES;
+  const vertexBytes = bytes.subarray(offset, offset + header.vertexBytes);
+  const vertices = new Float32Array(vertexBytes.byteLength / 4);
+  new Uint8Array(vertices.buffer).set(vertexBytes);
+  offset += header.vertexBytes;
+  let indices: Uint16Array | Uint32Array | undefined;
+  if (header.indexCount > 0) {
+    const indexBytes = bytes.subarray(offset, offset + header.indexBytes);
+    if (header.indexWidth === 2) {
+      indices = new Uint16Array(header.indexCount);
+      new Uint8Array(indices.buffer).set(indexBytes);
+    } else if (header.indexWidth === 4) {
+      indices = new Uint32Array(header.indexCount);
+      new Uint8Array(indices.buffer).set(indexBytes);
+    } else {
+      return undefined;
+    }
+    offset += header.indexBytes;
+  }
+
+  let metadata: {
+    readonly submeshes?: readonly Record<string, unknown>[];
+    readonly materialSlots?: PackedMesh['materialSlots'];
+    readonly aabb?: readonly number[];
+    readonly morphTargets?: readonly Record<string, readonly number[]>[];
+    readonly morphWeights?: readonly number[];
+  };
+  try {
+    metadata = JSON.parse(
+      new TextDecoder().decode(bytes.subarray(offset, offset + header.jsonBytes)),
+    ) as typeof metadata;
+  } catch {
+    return undefined;
+  }
+  if (
+    metadata.submeshes === undefined ||
+    metadata.submeshes.length === 0 ||
+    metadata.materialSlots === undefined
+  ) {
+    return undefined;
+  }
+  const attributes: Record<string, Float32Array | Uint16Array> = {};
+  const view = new DataView(vertices.buffer);
+  for (const entry of projection.attributes) {
+    const components = entry.byteLength / (entry.format === 'uint16x4' ? 2 : 4);
+    const target =
+      entry.format === 'uint16x4'
+        ? new Uint16Array(header.vertexCount * components)
+        : new Float32Array(header.vertexCount * components);
+    for (let vertex = 0; vertex < header.vertexCount; vertex += 1) {
+      for (let component = 0; component < components; component += 1) {
+        const sourceOffset =
+          vertex * header.stride + entry.offset + component * (entry.format === 'uint16x4' ? 2 : 4);
+        if (sourceOffset + (entry.format === 'uint16x4' ? 2 : 4) > vertices.byteLength) {
+          return undefined;
+        }
+        if (target instanceof Uint16Array) {
+          target[vertex * components + component] = view.getUint16(sourceOffset, true);
+        } else {
+          const value = view.getFloat32(sourceOffset, true);
+          if (!Number.isFinite(value)) return undefined;
+          target[vertex * components + component] = value;
+        }
+      }
+    }
+    attributes[entry.key] = target;
+  }
+  const decodedMorphTargets = morphTargets(metadata.morphTargets);
+  const morphWeightValues =
+    metadata.morphWeights === undefined ? undefined : new Float32Array(metadata.morphWeights);
+  if (
+    decodedMorphTargets !== undefined &&
+    morphWeightValues !== undefined &&
+    decodedMorphTargets.length !== morphWeightValues.length
+  ) {
+    return undefined;
+  }
+  return {
+    version: MESH_BIN_VERSION,
+    vertices,
+    attributes: attributes as VertexAttributeMap,
+    projection,
+    ...(indices === undefined ? {} : { indices }),
+    submeshes: metadata.submeshes,
+    materialSlots: metadata.materialSlots,
+    ...(metadata.aabb === undefined ? {} : { aabb: new Float32Array(metadata.aabb) }),
+    // MeshAsset.vertices remains a Float32Array, so translate the wire stride
+    // (bytes) back to the legacy float-count input expected by meshFromParts.
+    floatsPerVertex: header.stride / Float32Array.BYTES_PER_ELEMENT,
+    uvSetCount: 1,
+    ...(decodedMorphTargets === undefined ? {} : { morphTargets: decodedMorphTargets }),
+    ...(morphWeightValues === undefined ? {} : { morphWeights: morphWeightValues }),
+  };
+}
+
+function materialSlotsFor(
+  raw: PackedMesh['materialSlots'],
+  submeshes: readonly Submesh[],
+  refs: readonly string[],
+): readonly MeshMaterialSlot[] {
+  if (raw === undefined)
+    return submeshes.map((_submesh, index) => ({ slotName: `LegacySlot_${index}` }));
+  return raw.map((slot, index) => {
+    const reference =
+      slot.defaultMaterialRef === undefined ? undefined : refs[slot.defaultMaterialRef];
+    const defaultMaterial = reference === undefined ? undefined : parseGuid(reference);
+    return {
+      slotName:
+        typeof slot.slotName === 'string' && slot.slotName.trim().length > 0
+          ? slot.slotName
+          : `LegacySlot_${index}`,
+      ...(typeof slot.sourceKey === 'string' ? { sourceKey: slot.sourceKey } : {}),
+      ...(defaultMaterial === undefined ? {} : { defaultMaterial }),
+    };
+  });
+}
+
+function submeshesFor(
+  raw: readonly Record<string, unknown>[] | undefined,
+  vertexCount: number,
+  indexCount: number,
+): readonly Submesh[] {
+  const values =
+    raw === undefined || raw.length === 0
+      ? [{ indexOffset: 0, indexCount, vertexCount, topology: 'triangle-list' }]
+      : raw;
+  return values.map((value, index) => ({
+    indexOffset: typeof value.indexOffset === 'number' ? value.indexOffset : 0,
+    indexCount: typeof value.indexCount === 'number' ? value.indexCount : indexCount,
+    vertexCount: typeof value.vertexCount === 'number' ? value.vertexCount : vertexCount,
+    topology:
+      value.topology === 'line-list' ||
+      value.topology === 'line-strip' ||
+      value.topology === 'point-list' ||
+      value.topology === 'triangle-strip'
+        ? value.topology
+        : 'triangle-list',
+    materialSlot: typeof value.materialSlot === 'number' ? value.materialSlot : index,
+  }));
+}
+
+function deriveAabb(vertices: Float32Array, stride: number): Float32Array | undefined {
+  if (stride < 3 || vertices.length < 3 || vertices.length % stride !== 0) return undefined;
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let minZ = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  let maxZ = Number.NEGATIVE_INFINITY;
+  for (let offset = 0; offset < vertices.length; offset += stride) {
+    const x = vertices[offset];
+    const y = vertices[offset + 1];
+    const z = vertices[offset + 2];
+    if (x === undefined || y === undefined || z === undefined) return undefined;
+    minX = Math.min(minX, x);
+    minY = Math.min(minY, y);
+    minZ = Math.min(minZ, z);
+    maxX = Math.max(maxX, x);
+    maxY = Math.max(maxY, y);
+    maxZ = Math.max(maxZ, z);
+  }
+  return Float32Array.of(minX, minY, minZ, maxX, maxY, maxZ);
+}
+
+function meshFromParts(
+  parts: {
+    readonly vertices: unknown;
+    readonly indices?: unknown;
+    readonly attributes?: unknown;
+    readonly aabb?: unknown;
+    readonly submeshes?: readonly Record<string, unknown>[];
+    readonly materialSlots?: PackedMesh['materialSlots'];
+    readonly morphTargets?: unknown;
+    readonly morphWeights?: unknown;
+    readonly floatsPerVertex?: number;
+    readonly uvSetCount?: number;
+  },
+  refs: readonly string[],
+): MeshAsset | undefined {
+  const vertices = floatArray(parts.vertices);
+  if (vertices === undefined || vertices.length === 0) return undefined;
+  const indices = indexArray(parts.indices);
+  const sourceAttributes =
+    parts.attributes !== null && typeof parts.attributes === 'object'
+      ? (parts.attributes as Record<string, unknown>)
+      : {};
+  const attributes: VertexAttributeMap = {};
+  for (const key of [
+    'position',
+    'normal',
+    'uv',
+    'tangent',
+    'uv1',
+    'uv2',
+    'uv3',
+    'uv4',
+    'uv5',
+    'uv6',
+    'uv7',
+    'color',
+  ] as const) {
+    const value = floatArray(sourceAttributes[key]);
+    if (value !== undefined) attributes[key] = value;
+  }
+  const skinIndex = integerArray(sourceAttributes.skinIndex);
+  const skinWeight = floatArray(sourceAttributes.skinWeight);
+  if (skinIndex !== undefined) attributes.skinIndex = skinIndex;
+  if (skinWeight !== undefined) attributes.skinWeight = skinWeight;
+  const stride = parts.floatsPerVertex ?? 0;
+  const vertexCount = stride > 0 ? vertices.length / stride : vertices.length;
+  const submeshes = submeshesFor(parts.submeshes, vertexCount, indices?.length ?? 0);
+  const materialSlots = materialSlotsFor(parts.materialSlots, submeshes, refs);
+  const aabb = floatArray(parts.aabb) ?? deriveAabb(vertices, stride);
+  if (aabb === undefined) return undefined;
+  const morph = morphTargets(parts.morphTargets);
+  const weights = floatArray(parts.morphWeights);
+  if (morph !== undefined && weights !== undefined && morph.length !== weights.length)
+    return undefined;
+  const uvSetCount = parts.uvSetCount ?? 1;
+  if (stride > 0 && uvSetCount > 1) {
+    const hasSkin = stride === 18 + (uvSetCount - 1) * 2;
+    const firstOffset = hasSkin ? 18 : PROCEDURAL_FLOATS_PER_VERTEX;
+    const extraUvKeys = ['uv1', 'uv2', 'uv3', 'uv4', 'uv5', 'uv6', 'uv7'] as const;
+    for (let set = 1; set < uvSetCount; set += 1) {
+      const key = extraUvKeys[set - 1];
+      if (key === undefined) return undefined;
+      const values = new Float32Array(vertexCount * 2);
+      const sourceOffset = firstOffset + (set - 1) * 2;
+      for (let vertex = 0; vertex < vertexCount; vertex += 1) {
+        const source = vertex * stride + sourceOffset;
+        values[vertex * 2] = vertices[source] ?? 0;
+        values[vertex * 2 + 1] = vertices[source + 1] ?? 0;
+      }
+      attributes[key] = values;
+    }
+  }
+  return {
+    kind: 'mesh',
+    vertices,
+    ...(indices === undefined ? {} : { indices }),
+    attributes,
+    aabb,
+    submeshes,
+    materialSlots,
+    ...(morph === undefined ? {} : { morphTargets: morph }),
+    ...(weights === undefined ? {} : { morphWeights: weights }),
+  };
+}
+
+export function decodeMeshBinary(
+  bytes: Uint8Array,
+  refs: readonly string[],
+): MeshAsset | undefined {
+  const decoded = unpackMeshBinary(bytes);
+  if (decoded === undefined) return undefined;
+  return meshFromParts(
+    {
+      vertices: decoded.vertices,
+      ...(decoded.attributes === undefined ? {} : { attributes: decoded.attributes }),
+      ...(decoded.indices === undefined ? {} : { indices: decoded.indices }),
+      ...(decoded.aabb === undefined ? {} : { aabb: decoded.aabb }),
+      ...(decoded.submeshes === undefined ? {} : { submeshes: decoded.submeshes }),
+      ...(decoded.materialSlots === undefined ? {} : { materialSlots: decoded.materialSlots }),
+      ...(decoded.morphTargets === undefined ? {} : { morphTargets: decoded.morphTargets }),
+      ...(decoded.morphWeights === undefined ? {} : { morphWeights: decoded.morphWeights }),
+      ...(decoded.skinIndex === undefined && decoded.skinWeight === undefined
+        ? {}
+        : {
+            attributes: {
+              ...(decoded.skinIndex === undefined ? {} : { skinIndex: decoded.skinIndex }),
+              ...(decoded.skinWeight === undefined ? {} : { skinWeight: decoded.skinWeight }),
+            },
+          }),
+      floatsPerVertex: decoded.floatsPerVertex,
+      uvSetCount: decoded.uvSetCount,
+    },
+    refs,
+  );
+}
+
+export function normalizeMeshPayload(
+  payload: unknown,
+  refs: readonly string[],
+): MeshAsset | undefined {
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return undefined;
+  const source = payload as Record<string, unknown>;
+  if (source.kind !== 'mesh') return undefined;
+  return meshFromParts(
+    {
+      vertices: source.vertices,
+      ...(source.indices === undefined ? {} : { indices: source.indices }),
+      ...(source.attributes === undefined ? {} : { attributes: source.attributes }),
+      ...(source.aabb === undefined ? {} : { aabb: source.aabb }),
+      submeshes: Array.isArray(source.submeshes)
+        ? (source.submeshes as Record<string, unknown>[])
+        : [],
+      ...(Array.isArray(source.materialSlots)
+        ? { materialSlots: source.materialSlots as PackedMesh['materialSlots'] }
+        : {}),
+      ...(source.morphTargets === undefined ? {} : { morphTargets: source.morphTargets }),
+      ...(source.morphWeights === undefined ? {} : { morphWeights: source.morphWeights }),
+      floatsPerVertex: PROCEDURAL_FLOATS_PER_VERTEX,
+    },
+    refs,
+  );
+}

package/src/assets/mesh-decoder.ts

@@ -0,0 +1,97 @@
+import {
+  type AssetDecoder,
+  type AssetDecoderContribution,
+  type AssetKind,
+  type AssetLoadError,
+  err,
+  type MeshAsset,
+  ok,
+  type Result,
+} from '@forgeax/engine-types';
+import { decodeMeshBinary, normalizeMeshPayload } from './mesh-binary';
+import { createPrimitiveMesh, type PrimitiveMeshKind } from './primitive-mesh';
+
+export const meshAssetKind: AssetKind<MeshAsset, 'mesh'> = {
+  kind: 'mesh',
+} as AssetKind<MeshAsset, 'mesh'>;
+
+const PROCEDURAL_MESH_KINDS: Readonly<Record<string, PrimitiveMeshKind>> = {
+  'procedural-cube': 'cube',
+  'procedural-triangle': 'triangle',
+  'procedural-quad': 'quad',
+  'procedural-sphere': 'sphere',
+  'procedural-cylinder': 'cylinder',
+  'procedural-nine-slice-quad': 'nine-slice-quad',
+};
+
+function proceduralMesh(payload: unknown): Result<MeshAsset, AssetLoadError> | undefined {
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return undefined;
+  const geometry = (payload as { readonly geometry?: unknown }).geometry;
+  if (typeof geometry !== 'string') return undefined;
+  const kind = PROCEDURAL_MESH_KINDS[geometry];
+  if (kind === undefined) return undefined;
+  const result = createPrimitiveMesh(kind);
+  if (result.ok) return result;
+  return err({
+    code: 'asset-package-invalid',
+    expected: `a valid procedural ${kind} mesh payload`,
+    hint: 'recook the authored procedural mesh descriptor',
+    detail: { guid: '', reason: 'procedural mesh creation failed' },
+  });
+}
+
+/** Geometry validates mesh payload shape before any render owner consumes it. */
+export const meshAssetDecoder: AssetDecoder<MeshAsset> = {
+  async decode({ envelope, artifacts }): Promise<Result<MeshAsset, AssetLoadError>> {
+    const payload = envelope.payload;
+    const procedural = proceduralMesh(payload);
+    if (procedural !== undefined) {
+      if (!procedural.ok) {
+        return err<AssetLoadError>({
+          code: 'asset-package-invalid',
+          expected: procedural.error.expected,
+          hint: procedural.error.hint,
+          detail: { guid: envelope.guid, reason: 'procedural mesh creation failed' },
+        });
+      }
+      return procedural;
+    }
+    const body = envelope.artifacts.body;
+    if (body !== undefined) {
+      const bytes = await artifacts.read(body);
+      if (!bytes.ok) return err<AssetLoadError>(bytes.error);
+      const decoded = decodeMeshBinary(bytes.value, envelope.refs);
+      if (decoded === undefined) {
+        return err({
+          code: 'asset-package-invalid',
+          expected: 'a valid mesh-binary/4 body artifact with a local-space AABB',
+          hint: 'recook the mesh binary and publish its validated geometry payload',
+          detail: { guid: envelope.guid, reason: 'mesh binary decode failed' },
+        });
+      }
+      return ok(decoded);
+    }
+    const normalized = normalizeMeshPayload(payload, envelope.refs);
+    if (normalized !== undefined) return ok(normalized);
+    if (
+      payload.kind !== 'mesh' ||
+      !(payload.vertices instanceof Float32Array) ||
+      payload.vertices.length === 0 ||
+      payload.aabb === undefined
+    ) {
+      return err({
+        code: 'asset-package-invalid',
+        expected: 'a mesh payload with vertices and a local-space AABB',
+        hint: 'recook the mesh binary and publish its validated geometry payload',
+        detail: { guid: envelope.guid, reason: 'mesh payload failed geometry validation' },
+      });
+    }
+    return ok(payload);
+  },
+};
+
+export const meshAssetContribution: AssetDecoderContribution<MeshAsset, 'mesh'> = {
+  kind: meshAssetKind,
+  decoder: meshAssetDecoder,
+  consumer: 'Geometry',
+};