@forgeax/engine-runtime 0.1.4 → 0.1.7

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

@@ -11,9 +11,10 @@
 // unused-directive error and turn this file red.
 
 import { World } from '@forgeax/engine-ecs';
-import { GlyphText, Tilemap } from '@forgeax/engine-render/authoring';
-import { Camera } from '@forgeax/engine-render/internal';
+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', () => {

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

@@ -1,49 +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,
-  writeMaterialSnapshotPayload,
-} from '@forgeax/engine-render/internal';
-import { derive } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
+} from '../../../render/src/record/main-pass-material';
 
-describe('derived material texture coordinates (w29)', () => {
-  it('uses only the effective schema for texture field order', () => {
-    expect(userRegionTextureFieldOrder(derive([]))).toEqual([]);
-    expect(userRegionTextureFieldOrder(derive([{ name: 'albedo', type: 'texture2d' }]))).toEqual([
-      'albedo',
-    ]);
+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('writes coordinate records from the typed projection without fixed offsets', () => {
-    const result = writeMaterialSnapshotPayload({
+  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,
-      materialParamSchema: [
-        { name: 'baseColorTexture', type: 'texture2d' },
-        { name: 'normalTexture', type: 'texture2d' },
-      ],
+      materialShaderId: 'forgeax::default-standard-pbr',
       textureCoordinates: new Map([
         [
           'baseColorTexture',
-          {
-            set: 1,
-            transform: { offset: [0.125, 0.25], scale: [2, 3], rotation: 0.5 },
-            physicalUvScale: [0.9, 0.8],
-          },
-        ],
-        [
-          'normalTexture',
-          {
-            set: 0,
-            transform: { offset: [0.75, 0.25], scale: [4, 5], rotation: 0 },
-            physicalUvScale: [1, 1],
-          },
+          { 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,
+    ]);
 
-    expect(result.ok).toBe(true);
-    if (result.ok) expect(result.value.byteLength).toBeGreaterThan(0);
+    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

@@ -16,7 +16,7 @@
 // Grep gate: passKind:'deferred' / passKind:'forward' / passKind:'shadow-caster'
 //   each hit >=1 in packages/runtime/src/materials.ts
 
-import { Materials, routeMaterialPipeline } from '@forgeax/engine-render/internal';
+import { Materials } from '@forgeax/engine-render';
 import type { PassKind } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 
@@ -183,8 +183,8 @@ describe('Materials.standard multi-pass (w14)', () => {
       });
       expect(mat.values?.emissive).toEqual([0.1, 0.2, 0.3]);
       expect(mat.values?.emissiveIntensity).toBe(2);
-      expect(mat.values?.baseColorTexture).toEqual({ texture: 42 });
-      expect(mat.values?.occlusionTexture).toEqual({ texture: 84 });
+      expect(mat.values?.baseColorTexture).toBe(42);
+      expect(mat.values?.occlusionTexture).toBe(84);
       expect(mat.values?.occlusionStrength).toBe(0.75);
     });
 
@@ -242,30 +242,13 @@ describe('Materials.unlit forward-only (w14)', () => {
     const mat = Materials.unlit([1, 1, 1, 1], { alphaCutoff: 0.1 });
     expect(mat.values?.alphaCutoff).toBe(0.1);
   });
-});
-
-describe('material pipeline stop-draw routing (w28)', () => {
-  it('returns the closed specialization error without a fallback pipeline', () => {
-    const result = routeMaterialPipeline({
-      projection: {
-        materialGuid: 'material-slot',
-        specializationKey: 'stale-specialization',
-        artifactHash: 'sha256:missing',
-        layoutIdentity: 'sha256:layout',
-        passes: [],
-        runtimeValues: {},
-        staticSelection: ['useNormalMap'],
-      },
-      lookupArtifact: () => undefined,
-    });
 
-    expect(result).toMatchObject({
-      kind: 'error',
-      error: {
-        code: 'material-specialization-not-cooked',
-        detail: { material: 'material-slot', staticSelection: ['useNormalMap'] },
-      },
-    });
-    expect(result).not.toHaveProperty('artifact');
+  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');
+  });
+});

package/src/__tests__/mesh-loader-skin-contract.unit.test.ts

@@ -0,0 +1,120 @@
+// mesh-loader-skin-contract.unit.test.ts -- feat-20260611-fox-skinning-vertex-
+// attribute-chain M3 / w14: AC-05 dual-contract verification.
+//
+// meshLoader.load now accepts skinIndex (Uint16Array) / skinWeight
+// (Float32Array) AND their JSON-roundtrip number[] shapes (post-
+// JSON.stringify(pack) -> fetch -> JSON.parse on the dev-server / build-mode
+// pack-body path). This file isolates the dual contract via direct meshLoader
+// invocation -- dawn smoke walks register() and never touches the
+// JSON-roundtrip path that shipped Fox.glb red on the browser path.
+//
+// AC-05: after JSON.stringify -> JSON.parse, meshLoader.load() returns a
+// MeshAsset whose attributes.skinIndex instanceof Uint16Array and
+// attributes.skinWeight instanceof Float32Array, with values element-wise
+// equal to the original typed arrays.
+//
+// Anchors: requirements AC-05; plan-strategy D-7; research E-6 (PR #350
+// skeletonLoader pattern); risk R-2 (mesh-loader dual-contract gap surfaces
+// only on the browser pack-body path).
+
+import { meshLoader } from '@forgeax/engine-assets-runtime';
+import type { LoadContext } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function makeCtx(): LoadContext {
+  return {
+    fetchBinary: () =>
+      Promise.resolve({ ok: false as const, error: new Error('not used in unit') }),
+    resolveRef: () => Promise.resolve({ ok: false as const, error: new Error('not used in unit') }),
+    transcodeCaps: { bc: false, etc2: false, astc: false },
+    device: undefined,
+  };
+}
+
+describe('feat-20260611 / M3 / w14 - meshLoader skinIndex/skinWeight dual contract', () => {
+  it('AC-05 (a) accepts native typed arrays directly', () => {
+    const N = 4;
+    const skinIndex = new Uint16Array([0, 1, 2, 3, 4, 5, 6, 7, 0, 0, 0, 0, 0, 0, 0, 0]);
+    const skinWeight = new Float32Array([
+      1.0, 0.0, 0.0, 0.0, 0.5, 0.5, 0.0, 0.0, 0.25, 0.25, 0.25, 0.25, 0.0, 0.0, 0.0, 1.0,
+    ]);
+    const payload: Record<string, unknown> = {
+      vertices: new Float32Array(N * 18),
+      indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
+      attributes: { skinIndex, skinWeight },
+    };
+    const result = meshLoader.load(payload, undefined, makeCtx());
+    expect(result).toBeDefined();
+    if (result === undefined) return;
+    const asset = result as {
+      kind: string;
+      attributes: { skinIndex?: unknown; skinWeight?: unknown };
+    };
+    expect(asset.kind).toBe('mesh');
+    expect(asset.attributes.skinIndex).toBeInstanceOf(Uint16Array);
+    expect(asset.attributes.skinWeight).toBeInstanceOf(Float32Array);
+    expect(asset.attributes.skinIndex).toBe(skinIndex);
+    expect(asset.attributes.skinWeight).toBe(skinWeight);
+  });
+
+  it('AC-05 (b) JSON-roundtrip: number[] is rehydrated to Uint16Array / Float32Array', () => {
+    const N = 4;
+    const sourceSkinIndex = new Uint16Array([0, 1, 2, 3, 10, 11, 12, 13, 0, 0, 0, 0, 4, 5, 6, 7]);
+    const sourceSkinWeight = new Float32Array([
+      1.0, 0.0, 0.0, 0.0, 0.5, 0.5, 0.0, 0.0, 0.25, 0.25, 0.25, 0.25, 0.0, 0.0, 0.0, 1.0,
+    ]);
+
+    // Simulate the dev-server / build-mode pack-body wire path. The actual
+    // wire pre-flattens typed arrays to plain Array via
+    // @forgeax/engine-import normaliseForPack BEFORE JSON.stringify (see
+    // packages/import/src/import-runner.ts). Without that step,
+    // JSON.stringify(typedArray) yields a string-keyed object literal --
+    // not the dual-contract shape the loader is designed to honour.
+    const flatIndex = Array.from(sourceSkinIndex);
+    const flatWeight = Array.from(sourceSkinWeight);
+    const wire = JSON.parse(
+      JSON.stringify({
+        vertices: Array.from(new Float32Array(N * 18)),
+        indices: Array.from(new Uint16Array([0, 1, 2, 0, 2, 3])),
+        attributes: { skinIndex: flatIndex, skinWeight: flatWeight },
+      }),
+    ) as Record<string, unknown>;
+    const wireAttrs = wire.attributes as { skinIndex: unknown; skinWeight: unknown };
+    expect(Array.isArray(wireAttrs.skinIndex)).toBe(true);
+    expect(Array.isArray(wireAttrs.skinWeight)).toBe(true);
+
+    const result = meshLoader.load(wire, undefined, makeCtx());
+    expect(result).toBeDefined();
+    if (result === undefined) return;
+    const attrs = (result as { attributes: { skinIndex?: unknown; skinWeight?: unknown } })
+      .attributes;
+    expect(attrs.skinIndex).toBeInstanceOf(Uint16Array);
+    expect(attrs.skinWeight).toBeInstanceOf(Float32Array);
+
+    const restoredIdx = attrs.skinIndex as Uint16Array;
+    const restoredW = attrs.skinWeight as Float32Array;
+    expect(restoredIdx.length).toBe(sourceSkinIndex.length);
+    expect(restoredW.length).toBe(sourceSkinWeight.length);
+    for (let i = 0; i < sourceSkinIndex.length; i++) {
+      expect(restoredIdx[i]).toBe(sourceSkinIndex[i]);
+    }
+    for (let i = 0; i < sourceSkinWeight.length; i++) {
+      expect(restoredW[i]).toBeCloseTo(sourceSkinWeight[i] as number, 6);
+    }
+  });
+
+  it('AC-05 (c) absent skin attrs leave attributes unchanged (unskinned mesh path)', () => {
+    const payload: Record<string, unknown> = {
+      vertices: new Float32Array(3 * 12),
+      indices: new Uint16Array([0, 1, 2]),
+      attributes: {},
+    };
+    const result = meshLoader.load(payload, undefined, makeCtx());
+    expect(result).toBeDefined();
+    if (result === undefined) return;
+    const attrs = (result as { attributes: { skinIndex?: unknown; skinWeight?: unknown } })
+      .attributes;
+    expect(attrs.skinIndex).toBeUndefined();
+    expect(attrs.skinWeight).toBeUndefined();
+  });
+});

package/src/__tests__/mesh-ssbo-grow.unit.test.ts

@@ -13,14 +13,14 @@
 //   4. all limits zero (R-1 extreme)          -> falls to spec floor 128 MiB
 //   5. absent field (R-1 edge)                -> still non-zero
 
+import type { Buffer } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
 import {
   createMeshSsboGrowController,
   deriveStorageBufferCeiling,
   type MeshSsboGrowControllerInit,
   type MeshSsboGrowErrorRegistry,
-} from '@forgeax/engine-render/internal';
-import type { Buffer } from '@forgeax/engine-rhi';
-import { describe, expect, it } from 'vitest';
+} from '../../../render/src/assembly/factory';
 
 // ---------------------------------------------------------------------------
 // Stubs (mirror createRenderer.unit.test.ts pattern — minimal device fake)

package/src/__tests__/mip-gate.unit.test.ts

@@ -20,9 +20,9 @@
 //   - reuse the AssetError code system (D-9); the new code is
 //     'mipgen-unsupported-compressed-format'
 
-import { deriveRenderDataTexture } from '@forgeax/engine-render/internal';
 import type { TextureAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { deriveRenderDataTexture } from '../../../render/src/render-data';
 
 function tex(overrides: Partial<TextureAsset>): TextureAsset {
   return {