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

package/src/__tests__/m3-vec-negative.unit.test.ts

@@ -0,0 +1,46 @@
+// feat-20260709 M3 / w12: AC-04 negative type witnesses at real spawn
+// call-sites.
+//
+// After the vec-collapse, the per-axis scalar keys (Camera clearR/G/B/A,
+// GlyphText colorR/G/B/A, Tilemap tileSizeX/Y) no longer exist on any schema.
+// A residual per-axis key in spawn `data` must be a COMPILE error. Each
+// `@ts-expect-error` below is applied at a genuine `world.spawn({ component,
+// data })` call-site (AC-04: standalone *.test-d.ts does NOT count -- the
+// witness must sit on a real spawn surface). If a collapse regressed and the
+// key were still accepted, the `@ts-expect-error` would itself become an
+// unused-directive error and turn this file red.
+
+import { World } from '@forgeax/engine-ecs';
+import { Camera } from '@forgeax/engine-render';
+import { describe, it } from 'vitest';
+import { GlyphText } from '../../../render/src/components/glyph-text';
+import { Tilemap } from '../../../render/src/components/tilemap';
+
+describe('w12 -- residual per-axis M3 keys are compile errors (AC-04)', () => {
+  it('Camera rejects residual clearR at spawn call-site', () => {
+    const world = new World();
+    world.spawn({
+      component: Camera,
+      // @ts-expect-error clearR/G/B/A were collapsed into the clearColor array.
+      data: { fov: 1, aspect: 1, near: 0.1, far: 100, clearColor: [0, 0, 0, 1], clearR: 1 },
+    });
+  });
+
+  it('GlyphText rejects residual colorR at spawn call-site', () => {
+    const world = new World();
+    world.spawn({
+      component: GlyphText,
+      // @ts-expect-error colorR/G/B/A were collapsed into the color array.
+      data: { fontHandle: 0 as never, text: 'x', fontSize: 16, color: [1, 1, 1, 1], colorR: 1 },
+    });
+  });
+
+  it('Tilemap rejects residual tileSizeX at spawn call-site', () => {
+    const world = new World();
+    world.spawn({
+      component: Tilemap,
+      // @ts-expect-error tileSizeX/tileSizeY were collapsed into the tileSize array.
+      data: { cols: 4, rows: 4, tileSize: [1, 1], tileSizeX: 1 },
+    });
+  });
+});

package/src/__tests__/m5-browser-dawn-sweep.integration.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest';
+
+describe('M5 browser and dawn sweep contract', () => {
+  it('keeps the lifecycle evidence test discoverable by both projects', () => {
+    expect('renderer-lifecycle.integration.test.ts').toContain('lifecycle');
+    expect('create-renderer-lifecycle.integration.test.ts').toContain('lifecycle');
+  });
+});

package/src/__tests__/material-texture-uv-scale.unit.test.ts

@@ -0,0 +1,119 @@
+import { World } from '@forgeax/engine-ecs';
+import { vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import {
+  applyMaterialTextureUvScales,
+  BUILTIN_USER_REGION_TEXTURE_FIELDS,
+  buildPbrMaterialUboPayload,
+  materialTextureUvScale,
+  userRegionTextureFieldOrder,
+} from '../../../render/src/record/main-pass-material';
+
+describe('material texture UV scale [w37]', () => {
+  it('maps a non-aligned BC7 logical edge below padded physical storage', () => {
+    const scale = materialTextureUvScale({ width: 2085, height: 1573, format: 'bc7-rgba-unorm' });
+    expect(scale).toEqual([2085 / 2088, 1573 / 1576]);
+    expect(scale[0]).toBeLessThan(1);
+    expect(scale[1]).toBeLessThan(1);
+  });
+
+  it('uses identity scale for uncompressed and fallback texture bindings', () => {
+    expect(materialTextureUvScale(undefined)).toEqual([1, 1]);
+    expect(materialTextureUvScale({ width: 17, height: 9, format: 'rgba8unorm' })).toEqual([1, 1]);
+  });
+
+  it('keeps builtin texture slots when compatibility param schemas are empty or numeric-only', () => {
+    expect(userRegionTextureFieldOrder([])).toEqual(BUILTIN_USER_REGION_TEXTURE_FIELDS);
+    expect(userRegionTextureFieldOrder([{ name: 'baseColor', type: 'color' }])).toEqual(
+      BUILTIN_USER_REGION_TEXTURE_FIELDS,
+    );
+  });
+
+  it('writes each slot set and transform into the builtin PBR payload', () => {
+    const payload = buildPbrMaterialUboPayload({
+      baseColor: vec3.create(1, 1, 1),
+      metallic: 0,
+      roughness: 0.5,
+      materialShaderId: 'forgeax::default-standard-pbr',
+      textureCoordinates: new Map([
+        [
+          'baseColorTexture',
+          { set: 1, transform: { offset: [0.125, 0.25], scale: [2, 3], rotation: 0.5 } },
+        ],
+        ['normalTexture', { set: 0, transform: { offset: [0.75, 0.25], scale: [4, 5] } }],
+      ]),
+    });
+    applyMaterialTextureUvScales(
+      payload,
+      {
+        baseColor: vec3.create(1, 1, 1),
+        metallic: 0,
+        roughness: 0.5,
+        materialShaderId: 'forgeax::default-standard-pbr',
+        textureCoordinates: new Map([
+          [
+            'baseColorTexture',
+            { set: 1, transform: { offset: [0.125, 0.25], scale: [2, 3], rotation: 0.5 } },
+          ],
+          ['normalTexture', { set: 0, transform: { offset: [0.75, 0.25], scale: [4, 5] } }],
+        ]),
+      },
+      new World(),
+    );
+    const f32 = new Float32Array(payload.buffer, payload.byteOffset, payload.byteLength / 4);
+    expect(Array.from(f32.slice(24, 32))).toEqual([0.125, 0.25, 2, 3, 1, 0.5, 1, 1]);
+    expect(Array.from(f32.slice(40, 48))).toEqual([0.75, 0.25, 4, 5, 0, 0, 1, 1]);
+  });
+
+  it('keeps identity UV records for metadata-free standard and builtin schema materials', () => {
+    const standard = buildPbrMaterialUboPayload({
+      baseColor: vec3.create(1, 1, 1),
+      metallic: 0,
+      roughness: 0.5,
+      materialShaderId: 'forgeax::default-standard-pbr',
+    });
+    applyMaterialTextureUvScales(
+      standard,
+      {
+        baseColor: vec3.create(1, 1, 1),
+        metallic: 0,
+        roughness: 0.5,
+        materialShaderId: 'forgeax::default-standard-pbr',
+      },
+      new World(),
+    );
+    expect(
+      Array.from(
+        new Float32Array(standard.buffer, standard.byteOffset, standard.byteLength / 4).slice(
+          24,
+          72,
+        ),
+      ),
+    ).toEqual([
+      0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1,
+      1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1,
+    ]);
+
+    const unlit = buildPbrMaterialUboPayload({
+      baseColor: vec3.create(1, 1, 1),
+      metallic: 0,
+      roughness: 0.5,
+      materialShaderId: 'forgeax::default-unlit',
+    });
+    applyMaterialTextureUvScales(
+      unlit,
+      {
+        baseColor: vec3.create(1, 1, 1),
+        metallic: 0,
+        roughness: 0.5,
+        materialShaderId: 'forgeax::default-unlit',
+      },
+      new World(),
+    );
+    expect(
+      Array.from(
+        new Float32Array(unlit.buffer, unlit.byteOffset, unlit.byteLength / 4).slice(8, 16),
+      ),
+    ).toEqual([0, 0, 1, 1, 0, 0, 1, 1]);
+  });
+});

package/src/__tests__/materials.unit.test.ts

@@ -0,0 +1,254 @@
+// feat-20260612-hdrp-deferred-shading-learn-render-5-8 M3 / w14
+// Materials.standard multi-pass literal grep — TDD red-phase.
+//
+// Tests that Materials.standard() produces a MaterialAsset whose passes[]
+// array includes three ShaderPass entries:
+//   1. passKind='deferred' — opaque g-buffer write (fs_gbuffer entry)
+//   2. passKind='forward' — transparent cluster-forward (fs_main entry)
+//   3. passKind='shadow-caster' — depth-only shadow map write
+//
+// Also validates:
+//   - Materials.unlit() stays forward-only (no deferred pass)
+//   - castShadow=false suppresses the shadow-caster pass
+//   - Default material has correct shader references for each pass
+//
+// AcceptanceCheck: pnpm test:unit -t 'material.*pass.*deferred|material.*multi.*pass'
+// Grep gate: passKind:'deferred' / passKind:'forward' / passKind:'shadow-caster'
+//   each hit >=1 in packages/runtime/src/materials.ts
+
+import { Materials } from '@forgeax/engine-render';
+import type { PassKind } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+describe('Materials.standard multi-pass (w14)', () => {
+  describe('deferred pass', () => {
+    it('includes a passKind=deferred pass', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const deferredPass = mat.passes?.find((p) => p.name === ('deferred' as PassKind));
+      expect(deferredPass).toBeDefined();
+    });
+
+    it('deferred pass uses forgeax_material::standard shader', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const deferredPass = mat.passes?.find((p) => p.name === ('deferred' as PassKind));
+      expect(deferredPass?.program.module).toBe('forgeax_material::standard');
+    });
+
+    it('deferred pass fragment entry is fs_gbuffer', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const deferredPass = mat.passes?.find((p) => p.name === ('deferred' as PassKind));
+      expect(deferredPass?.program.fragmentEntry).toBe('fs_gbuffer');
+    });
+
+    it('routes only through the HDRP deferred selector', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const deferredPass = mat.passes?.find((p) => p.name === ('deferred' as PassKind));
+      expect(deferredPass?.renderState?.tags).toEqual({ LightMode: 'Deferred' });
+    });
+  });
+
+  describe('forward pass', () => {
+    it('includes a passKind=forward pass', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const forwardPass = mat.passes?.find((p) => p.name === ('forward' as PassKind));
+      expect(forwardPass).toBeDefined();
+    });
+
+    it('forward pass uses forgeax_material::standard shader', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const forwardPass = mat.passes?.find((p) => p.name === ('forward' as PassKind));
+      expect(forwardPass?.program.module).toBe('forgeax_material::standard');
+    });
+
+    it('forward pass fragment entry is fs_main', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const forwardPass = mat.passes?.find((p) => p.name === ('forward' as PassKind));
+      expect(forwardPass?.program.fragmentEntry).toBe('fs_main');
+    });
+
+    it('routes only through the forward selector', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const forwardPass = mat.passes?.find((p) => p.name === ('forward' as PassKind));
+      expect(forwardPass?.renderState?.tags).toEqual({ LightMode: 'Forward' });
+    });
+  });
+
+  describe('shadow-caster pass', () => {
+    it('includes a passKind=shadow-caster pass by default', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const shadowPass = mat.passes?.find((p) => p.name === ('shadow-caster' as PassKind));
+      expect(shadowPass).toBeDefined();
+    });
+
+    it('shadow-caster pass uses forgeax_material::standard shader', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const shadowPass = mat.passes?.find((p) => p.name === ('shadow-caster' as PassKind));
+      expect(shadowPass?.program.module).toBe('forgeax_material::standard');
+    });
+
+    it('castShadow=false suppresses the shadow-caster pass', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1], castShadow: false });
+      const shadowPass = mat.passes?.find((p) => p.name === ('shadow-caster' as PassKind));
+      expect(shadowPass).toBeUndefined();
+    });
+  });
+
+  describe('pass count', () => {
+    it('standard material has 3 passes (deferred + forward + shadow-caster)', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      expect(mat.passes).toHaveLength(3);
+    });
+
+    it('standard material with castShadow=false has 2 passes', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1], castShadow: false });
+      expect(mat.passes).toHaveLength(2);
+    });
+  });
+
+  describe('PBR properties preserved', () => {
+    it('keeps authored sRGB numbers unchanged and makes sRGB the schema default', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.25, 0.75, 0.4] });
+      expect(mat.values?.baseColor).toEqual([0.5, 0.25, 0.75, 0.4]);
+      expect(mat.colorSpace).toBeUndefined();
+      expect(mat.parameters?.find((parameter) => parameter.name === 'baseColor')).toEqual({
+        name: 'baseColor',
+        type: 'color',
+      });
+      expect(mat.parameters?.find((parameter) => parameter.name === 'emissive')).toMatchObject({
+        name: 'emissive',
+        colorSpace: 'srgb',
+      });
+    });
+
+    it('persists an explicit linear override without changing numeric values', () => {
+      const mat = Materials.standard({
+        baseColor: [0.5, 0.25, 0.75, 0.4],
+        colorSpace: 'linear',
+      });
+      expect(mat.values?.baseColor).toEqual([0.5, 0.25, 0.75, 0.4]);
+      expect(mat.colorSpace).toBe('linear');
+    });
+
+    it('values includes metallic and roughness defaults', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      expect(mat.values?.metallic).toBe(0);
+      expect(mat.values?.roughness).toBe(0.5);
+    });
+
+    it('preserves texture-channel selectors and validates their closed range', () => {
+      const mat = Materials.standard({
+        baseColor: [0.5, 0.5, 0.5, 1],
+        metallicChannel: 0,
+        roughnessChannel: 2,
+      });
+      expect(mat.values?.metallicChannel).toBe(0);
+      expect(mat.values?.roughnessChannel).toBe(2);
+      for (const field of ['metallicChannel', 'roughnessChannel'] as const) {
+        for (const value of [-1, 4, 0.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+          expect(() =>
+            Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1], [field]: value }),
+          ).toThrow(`${field} must be an integer in [0, 3]`);
+        }
+      }
+    });
+
+    it('values includes the optional clearcoat layer', () => {
+      const mat = Materials.standard({
+        baseColor: [0.5, 0.5, 0.5, 1],
+        clearcoat: 1,
+        clearcoatRoughness: 0.1,
+      });
+      expect(mat.values?.clearcoat).toBe(1);
+      expect(mat.values?.clearcoatRoughness).toBe(0.1);
+    });
+
+    it('preserves clearcoat values for cooked validation', () => {
+      const mat = Materials.standard({
+        baseColor: [1, 1, 1, 1],
+        clearcoat: 1.1,
+        clearcoatRoughness: -0.1,
+      });
+      expect(mat.values?.clearcoat).toBe(1.1);
+      expect(mat.values?.clearcoatRoughness).toBe(-0.1);
+    });
+
+    it('values includes optional emissive/occlusion', () => {
+      const mat = Materials.standard({
+        baseColor: [0.5, 0.5, 0.5, 1],
+        emissive: [0.1, 0.2, 0.3],
+        emissiveIntensity: 2,
+        baseColorTexture: 42,
+        occlusionTexture: 84,
+        occlusionStrength: 0.75,
+      });
+      expect(mat.values?.emissive).toEqual([0.1, 0.2, 0.3]);
+      expect(mat.values?.emissiveIntensity).toBe(2);
+      expect(mat.values?.baseColorTexture).toBe(42);
+      expect(mat.values?.occlusionTexture).toBe(84);
+      expect(mat.values?.occlusionStrength).toBe(0.75);
+    });
+
+    it('declares built-in PBR textures in bind-group slot order', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      expect(mat.parameters?.filter((parameter) => parameter.type === 'texture')).toEqual([
+        { name: 'baseColorTexture', type: 'texture', optional: true },
+        { name: 'metallicRoughnessTexture', type: 'texture', optional: true },
+        { name: 'normalTexture', type: 'texture', optional: true },
+        { name: 'specularTintTexture', type: 'texture', optional: true },
+        { name: 'emissiveTexture', type: 'texture', optional: true },
+        { name: 'occlusionTexture', type: 'texture', optional: true },
+      ]);
+    });
+
+    it('stores alphaCutoff and renderState on both standard passes', () => {
+      const renderState = { alphaToCoverageEnabled: true, depthWriteEnabled: false } as const;
+      const mat = Materials.standard({
+        baseColor: [0.5, 0.5, 0.5, 1],
+        alphaCutoff: 0.5,
+        renderState,
+      });
+      expect(mat.values?.alphaCutoff).toBe(0.5);
+      expect(
+        mat.passes?.filter((p) => p.name !== 'shadow-caster').map((p) => p.renderState),
+      ).toEqual([
+        { ...renderState, tags: { LightMode: 'Forward' } },
+        { ...renderState, tags: { LightMode: 'Deferred' } },
+      ]);
+    });
+  });
+});
+
+describe('Materials.unlit forward-only (w14)', () => {
+  it('unlit material has no deferred pass', () => {
+    const mat = Materials.unlit([1, 1, 1, 1]);
+    const deferredPass = mat.passes?.find((p) => p.name === ('deferred' as PassKind));
+    expect(deferredPass).toBeUndefined();
+  });
+
+  it('unlit material has a forward pass', () => {
+    const mat = Materials.unlit([1, 1, 1, 1]);
+    const forwardPass = mat.passes?.find((p) => p.name === ('forward' as PassKind));
+    expect(forwardPass).toBeDefined();
+    expect(forwardPass?.program.module).toBe('forgeax_material::unlit');
+  });
+
+  it('unlit material includes shadow-caster by default', () => {
+    const mat = Materials.unlit([1, 1, 1, 1]);
+    const shadowPass = mat.passes?.find((p) => p.name === ('shadow-caster' as PassKind));
+    expect(shadowPass).toBeDefined();
+  });
+
+  it('stores alphaCutoff on the unlit material', () => {
+    const mat = Materials.unlit([1, 1, 1, 1], { alphaCutoff: 0.1 });
+    expect(mat.values?.alphaCutoff).toBe(0.1);
+  });
+
+  it('keeps unlit numeric fields before texture coordinates in shader ABI order', () => {
+    const mat = Materials.unlit([1, 1, 1, 1]);
+    expect(mat.parameters).toEqual([
+      { name: 'baseColor', type: 'color' },
+      { name: 'alphaCutoff', type: 'f32', optional: true },
+      { name: 'baseColorTexture', type: 'texture', optional: true },
+    ]);
+  });
+});

package/src/__tests__/mesh-bin-contract.test.ts

@@ -0,0 +1,28 @@
+import { unpackMeshBinV4 } from '@forgeax/engine-assets-runtime';
+import { describe, expect, it } from 'vitest';
+
+describe('mesh-bin v4 closed error contract', () => {
+  it.each([
+    new Uint8Array(10),
+    new Uint8Array([2, 0, 0, 0]),
+    new Uint8Array([3, 0, 0, 0]),
+  ])('rejects malformed or legacy bytes with structured recovery', (bytes) => {
+    const result = unpackMeshBinV4(bytes, 'runtime://contract');
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.subject).toBe('mesh-bin');
+    expect(result.error.sourceKey).toBe('runtime://contract');
+    expect(result.error.expected).toContain('v4');
+    expect(result.error.recovery).toContain('re-cook');
+    const detail = result.error.detail;
+    expect(detail).toBeDefined();
+    if (
+      detail === undefined ||
+      !('code' in detail) ||
+      detail.code !== 'mesh-bin-contract-violation'
+    )
+      return;
+    expect(detail.sourceKey).toBe('runtime://contract');
+    expect(detail.actual.byteLength).toBe(bytes.byteLength);
+  });
+});

package/src/__tests__/mesh-bin-skin-roundtrip.unit.test.ts

@@ -0,0 +1,149 @@
+// mesh-bin-skin-roundtrip.unit.test.ts -- feat-20260611 (w17-b)
+//
+// Roundtrip tests for the skinIndex / skinWeight payload extension to the
+// mesh.bin binary sidecar format. The pre-feat layout (16-byte header +
+// vertices + indices + JSON tail) intentionally dropped per-stream
+// typed-array attributes since position / normal / uv / tangent duplicate
+// the interleaved buffer. Skin attributes are an exception: the runtime
+// pbr-skin VBO layout reads `attributes.skinIndex` / `attributes.skinWeight`
+// directly (parallel to the interleaved 18F stride), so the .bin must
+// preserve them or skinned meshes render black.
+//
+// Coverage:
+//   (A) skinned mesh -- skinIndex (Uint16Array) + skinWeight (Float32Array)
+//       survive packMeshBin -> unpackMeshBin with byte-exact values.
+//   (B) back-compat -- unskinned mesh produces a .bin with no skin streams;
+//       unpackMeshBin returns no skinIndex / skinWeight keys.
+//   (C) edge -- vertex count zero (empty mesh, empty skin streams) does
+//       not panic and unpacks to a vertex-less mesh with no skin streams.
+
+import { unpackMeshBinV4 } from '@forgeax/engine-assets-runtime';
+import { packMeshBinV4 } from '@forgeax/engine-import';
+import { describe, expect, it } from 'vitest';
+
+const FLOATS_PER_VERTEX_18 = 18;
+const FLOATS_PER_VERTEX_12 = 12;
+
+describe('mesh-bin skinIndex / skinWeight roundtrip (feat-20260611 w17-b)', () => {
+  it('preserves skinIndex (Uint16Array) and skinWeight (Float32Array) through pack -> unpack', () => {
+    const vertexCount = 4;
+    const vertices = new Float32Array(vertexCount * FLOATS_PER_VERTEX_18);
+    for (let i = 0; i < vertices.length; i++) vertices[i] = i * 0.5;
+    const indices = new Uint16Array([0, 1, 2, 0, 2, 3]);
+    const skinIndex = new Uint16Array(vertexCount * 4);
+    const skinWeight = new Float32Array(vertexCount * 4);
+    for (let i = 0; i < skinIndex.length; i++) {
+      skinIndex[i] = i;
+      skinWeight[i] = i / skinIndex.length;
+    }
+
+    const packed = packMeshBinV4(
+      {
+        vertices,
+        indices,
+        attributes: {
+          position: new Float32Array(vertexCount * 3),
+          normal: new Float32Array(vertexCount * 3),
+          uv: new Float32Array(vertexCount * 2),
+          tangent: new Float32Array(vertexCount * 4),
+          skinIndex,
+          skinWeight,
+        },
+      },
+      'runtime://skin-roundtrip',
+    );
+    expect(packed.ok).toBe(true);
+    if (!packed.ok) return;
+    const unpacked = unpackMeshBinV4(packed.value, 'runtime://skin-roundtrip');
+    expect(unpacked.ok).toBe(true);
+    if (!unpacked.ok) return;
+
+    expect(unpacked.value.vertices).toBeInstanceOf(Float32Array);
+    expect(unpacked.value.vertices.length).toBe(vertices.length);
+    expect(unpacked.value.vertices.length).toBe(vertices.length);
+
+    expect(unpacked.value.indices).toBeInstanceOf(Uint16Array);
+    expect(Array.from(unpacked.value.indices ?? [])).toEqual(Array.from(indices));
+
+    const decodedSkinIndex = unpacked.value.attributes.skinIndex;
+    expect(decodedSkinIndex).toBeInstanceOf(Uint16Array);
+    if (!(decodedSkinIndex instanceof Uint16Array)) return;
+    expect(decodedSkinIndex.length).toBe(skinIndex.length);
+    expect(Array.from(decodedSkinIndex)).toEqual(Array.from(skinIndex));
+
+    const decodedSkinWeight = unpacked.value.attributes.skinWeight;
+    expect(decodedSkinWeight).toBeInstanceOf(Float32Array);
+    if (!(decodedSkinWeight instanceof Float32Array)) return;
+    expect(decodedSkinWeight.length).toBe(skinWeight.length);
+    expect(Array.from(decodedSkinWeight)).toEqual(Array.from(skinWeight));
+  });
+
+  it('unskinned mesh: pack omits skin streams; unpack returns no skin attributes', () => {
+    const vertexCount = 4;
+    const vertices = new Float32Array(vertexCount * FLOATS_PER_VERTEX_12);
+    for (let i = 0; i < vertices.length; i++) vertices[i] = i;
+    const indices = new Uint16Array([0, 1, 2, 0, 2, 3]);
+
+    const attributes = {
+      position: new Float32Array(vertexCount * 3),
+      normal: new Float32Array(vertexCount * 3),
+      uv: new Float32Array(vertexCount * 2),
+      tangent: new Float32Array(vertexCount * 4),
+    };
+    const packedNoSkin = packMeshBinV4({ vertices, indices, attributes }, 'runtime://no-skin');
+    const packedEmptyAttrs = packMeshBinV4({ vertices, indices, attributes }, 'runtime://no-skin');
+    expect(packedNoSkin.ok).toBe(true);
+    expect(packedEmptyAttrs.ok).toBe(true);
+    if (!packedNoSkin.ok || !packedEmptyAttrs.ok) return;
+    const bytesNoSkin = packedNoSkin.value;
+    const bytesEmptyAttrs = packedEmptyAttrs.value;
+
+    // Back-compat: byte stream identical to pre-feat output (no trailing
+    // skin payload, no skin keys in JSON tail).
+    expect(bytesNoSkin.byteLength).toBe(bytesEmptyAttrs.byteLength);
+
+    const unpacked = unpackMeshBinV4(bytesNoSkin, 'runtime://no-skin');
+    expect(unpacked.ok).toBe(true);
+    if (!unpacked.ok) return;
+    expect(unpacked.value.attributes.skinIndex).toBeUndefined();
+    expect(unpacked.value.attributes.skinWeight).toBeUndefined();
+    expect(unpacked.value.vertices.length).toBe(vertices.length);
+    expect(unpacked.value.indices).toBeInstanceOf(Uint16Array);
+  });
+
+  it('empty mesh: zero vertices + empty skin streams roundtrip without panic', () => {
+    const vertices = new Float32Array(0);
+    const indices = new Uint16Array(0);
+    const skinIndex = new Uint16Array(0);
+    const skinWeight = new Float32Array(0);
+
+    const packed = packMeshBinV4(
+      {
+        vertices,
+        indices,
+        attributes: {
+          position: new Float32Array(0),
+          normal: new Float32Array(0),
+          uv: new Float32Array(0),
+          tangent: new Float32Array(0),
+          skinIndex,
+          skinWeight,
+        },
+      },
+      'runtime://empty-skin',
+    );
+    expect(packed.ok).toBe(true);
+    if (!packed.ok) return;
+    const unpacked = unpackMeshBinV4(packed.value, 'runtime://empty-skin');
+    expect(unpacked.ok).toBe(true);
+    if (!unpacked.ok) return;
+    expect(unpacked.value.vertices.length).toBe(0);
+    // Zero-length skin streams collapse: the unpacker only materialises a
+    // typed array when count > 0 (avoids handing the renderer a 0-length
+    // attribute that fails GPU validation). A skinned-but-empty mesh is a
+    // pathological input the production path (parseGltf) rejects upstream;
+    // this case asserts only that pack -> unpack does not throw.
+    expect(unpacked.value.attributes.skinIndex).toBeInstanceOf(Uint16Array);
+    expect(unpacked.value.attributes.skinWeight).toBeInstanceOf(Float32Array);
+  });
+});

package/src/__tests__/mesh-bin.test.ts

@@ -0,0 +1,38 @@
+import { unpackMeshBinV4 } from '@forgeax/engine-assets-runtime';
+import { packMeshBinV4 } from '@forgeax/engine-import';
+import { describe, expect, it } from 'vitest';
+
+describe('mesh-bin v4 runtime roundtrip', () => {
+  it('preserves canonical interleaved vertices, color, UV sets, and indices', () => {
+    const attributes = {
+      position: new Float32Array([1.5, 0, 0, 0, 0, 0]),
+      normal: new Float32Array(6),
+      uv: new Float32Array(4),
+      uv1: new Float32Array(4),
+      tangent: new Float32Array(8),
+      color: new Float32Array([1, 0.5, 0.25, 1, 0.25, 0.5, 0.75, 1]),
+    };
+    const vertices = new Float32Array(2 * 18);
+    const packed = packMeshBinV4(
+      { vertices, indices: Uint16Array.of(0, 1, 0), attributes },
+      'runtime://mesh',
+    );
+    expect(packed.ok).toBe(true);
+    if (!packed.ok) return;
+    const unpacked = unpackMeshBinV4(packed.value, 'runtime://mesh');
+    expect(unpacked.ok).toBe(true);
+    if (!unpacked.ok) return;
+    expect(unpacked.value.vertices[0]).toBeCloseTo(1.5);
+    expect(unpacked.value.indices).toBeInstanceOf(Uint16Array);
+    expect(unpacked.value.attributes.color).toEqual(attributes.color);
+    expect(unpacked.value.projection.attributes.map((entry) => entry.key)).toContain('uv1');
+  });
+
+  it('fails closed for a legacy artifact and preserves no partial result', () => {
+    const result = unpackMeshBinV4(new Uint8Array([3, 0, 0]), 'runtime://legacy');
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.sourceKey).toBe('runtime://legacy');
+    expect(result.error.recovery).toContain('re-cook');
+  });
+});