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

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

@@ -0,0 +1,244 @@
+// M1: ceiling derivation TDD (AC-01 + plan-strategy D-1).
+//
+// Pure helper deriveStorageBufferCeiling exports a non-zero ceiling for every
+// legal limits input, even when maxStorageBufferBindingSize is 0 / undefined
+// (WebKit downlevel_webgl2_defaults). The grow controller's growMeshSsbo
+// closure delegates ceiling derivation to this helper so unit tests can
+// exercise the derivation logic directly without a real device.
+//
+// Test distribution:
+//   1. maxStorageBufferBindingSize === 0     -> derived ceiling != 0
+//   2. maxStorageBufferBindingSize === undefined -> derived ceiling != 0
+//   3. non-zero ceiling, request fits         -> grow ok, no error (happy path)
+//   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 '../../../render/src/assembly/factory';
+
+// ---------------------------------------------------------------------------
+// Stubs (mirror createRenderer.unit.test.ts pattern — minimal device fake)
+// ---------------------------------------------------------------------------
+
+const DUMMY_BUFFER = {
+  destroy: () => {},
+  size: 0,
+  usage: 0,
+} as unknown as Buffer;
+
+function makeDevice(limits: {
+  maxStorageBufferBindingSize: number;
+}): NonNullable<MeshSsboGrowControllerInit['device']> {
+  return {
+    limits,
+    createBuffer: () => DUMMY_BUFFER,
+  };
+}
+
+function makeSpyErrorRegistry(): MeshSsboGrowErrorRegistry & {
+  fireCount: number;
+  lastCode: string | null;
+} {
+  let fireCount = 0;
+  let lastCode: string | null = null;
+  const self = {
+    fire(e: { code: string }) {
+      fireCount += 1;
+      lastCode = e.code;
+    },
+  } as MeshSsboGrowErrorRegistry & { fireCount: number; lastCode: string | null };
+  Object.defineProperty(self, 'fireCount', {
+    get: () => fireCount,
+    enumerable: true,
+    configurable: true,
+  });
+  Object.defineProperty(self, 'lastCode', {
+    get: () => lastCode,
+    enumerable: true,
+    configurable: true,
+  });
+  return self;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('deriveStorageBufferCeiling (M1 AC-01 ceiling derivation)', () => {
+  it('Case 1: maxStorageBufferBindingSize === 0 → derived ceiling is non-zero (128 MiB spec floor)', () => {
+    const ceiling = deriveStorageBufferCeiling({ maxStorageBufferBindingSize: 0 });
+    expect(ceiling).toBeGreaterThan(0);
+    // Default fallback to WebGPU spec floor: 134217728 (128 MiB).
+    expect(ceiling).toBe(134217728);
+  });
+
+  it('Case 2: maxStorageBufferBindingSize === undefined → derived ceiling is non-zero (128 MiB spec floor)', () => {
+    const ceiling = deriveStorageBufferCeiling({});
+    expect(ceiling).toBeGreaterThan(0);
+    expect(ceiling).toBe(134217728);
+  });
+
+  it('Case 3: non-zero maxStorageBufferBindingSize → respect the reported limit verbatim', () => {
+    const ceiling = deriveStorageBufferCeiling({ maxStorageBufferBindingSize: 268435456 }); // 256 MiB
+    expect(ceiling).toBe(268435456);
+  });
+
+  it('Case 4: maxBufferSize > 0 but maxStorageBufferBindingSize === 0 → prefer maxBufferSize over spec floor', () => {
+    // Plan D-1: prefer device's other limits before falling to spec floor.
+    const ceiling = deriveStorageBufferCeiling({
+      maxStorageBufferBindingSize: 0,
+      maxBufferSize: 16777216, // 16 MiB
+    });
+    // 16 MiB > 0; falls to maxBufferSize since maxStorageBufferBindingSize is 0.
+    expect(ceiling).toBe(16777216);
+  });
+
+  it('Case 5: all limits 0 → falls to spec floor 128 MiB (R-1 extreme guard)', () => {
+    const ceiling = deriveStorageBufferCeiling({
+      maxStorageBufferBindingSize: 0,
+      maxBufferSize: 0,
+      maxUniformBufferBindingSize: 0,
+    });
+    expect(ceiling).toBe(134217728);
+  });
+
+  it('Case 6: maxUniformBufferBindingSize fallback when maxStorageBufferBindingSize === 0 and maxBufferSize unavailable', () => {
+    const ceiling = deriveStorageBufferCeiling({
+      maxStorageBufferBindingSize: 0,
+      maxUniformBufferBindingSize: 65536,
+    });
+    expect(ceiling).toBe(65536);
+  });
+});
+
+describe('growMeshSsbo with ceiling derivation (M1 integration)', () => {
+  it('happy path: non-zero maxStorageBufferBindingSize + request fits → grow ok', () => {
+    const spy = makeSpyErrorRegistry();
+    const ctrl = createMeshSsboGrowController({
+      device: makeDevice({ maxStorageBufferBindingSize: 134217728 }), // 128 MiB
+      errorRegistry: spy,
+      initialSlotCount: 1,
+      perEntityStride: 256,
+      meshUsage: 0,
+      materialUsage: 0,
+    });
+    // Request 1024 slots = 1024 * 256 = 262144 bytes, well under 128 MiB.
+    const result = ctrl.growMeshSsbo(1024);
+    expect(result.ok).toBe(true);
+    expect(spy.fireCount).toBe(0);
+  });
+
+  it('ceiling=0 (WebKit downlevel) + moderate request → derived ceiling used, grow ok', () => {
+    const spy = makeSpyErrorRegistry();
+    const ctrl = createMeshSsboGrowController({
+      device: makeDevice({ maxStorageBufferBindingSize: 0 }), // WebKit
+      errorRegistry: spy,
+      initialSlotCount: 1,
+      perEntityStride: 256,
+      meshUsage: 0,
+      materialUsage: 0,
+    });
+    // Request 4096 slots = 4096 * 256 = 1 MiB < spec floor 128 MiB → fits.
+    const result = ctrl.growMeshSsbo(4096);
+    expect(result.ok).toBe(true);
+    expect(spy.fireCount).toBe(0);
+  });
+
+  it('ceiling=0 + request exceeds derived ceiling → ceiling-reached error (derived ceiling in effect)', () => {
+    // Force a low derived ceiling to trigger the error path without needing
+    // a real device that reports a tiny limit.
+    const spy = makeSpyErrorRegistry();
+    const ctrl = createMeshSsboGrowController({
+      device: makeDevice({ maxStorageBufferBindingSize: 0 }), // 0 triggers derivation
+      errorRegistry: spy,
+      initialSlotCount: 1,
+      perEntityStride: 256,
+      meshUsage: 0,
+      materialUsage: 0,
+    });
+    const MAX_SLOTS = Math.floor(134217728 / 256) + 1; // just beyond spec floor
+    const result = ctrl.growMeshSsbo(MAX_SLOTS);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.code).toBe('mesh-ssbo-ceiling-reached');
+    }
+    expect(spy.fireCount).toBe(1);
+    expect(spy.lastCode).toBe('mesh-ssbo-ceiling-reached');
+  });
+
+  it('ceiling=undefined + moderate request → derived ceiling used, grow ok', () => {
+    // Though device limits always has maxStorageBufferBindingSize in reality,
+    // test the derivation guard treats undefined the same as 0.
+    const spy = makeSpyErrorRegistry();
+    const ctrl = createMeshSsboGrowController({
+      // The init type requires maxStorageBufferBindingSize: number, so we
+      // test undefined via the pure helper; integration test with 0 covers
+      // the grow path. (The device interface is typed strictly to match
+      // real device.limits which always has the field.)
+      device: makeDevice({ maxStorageBufferBindingSize: 0 }),
+      errorRegistry: spy,
+      initialSlotCount: 1,
+      perEntityStride: 256,
+      meshUsage: 0,
+      materialUsage: 0,
+    });
+    const result = ctrl.growMeshSsbo(512);
+    expect(result.ok).toBe(true);
+    expect(spy.fireCount).toBe(0);
+  });
+});
+
+// ── M2: graceful degradation (degradedToSlotCount) ───────────────────────
+describe('growMeshSsbo degradedToSlotCount (M2 AC-02/AC-03)', () => {
+  it('ceiling-reached returns degradedToSlotCount === pre-grow capacity', () => {
+    const spy = makeSpyErrorRegistry();
+    const ctrl = createMeshSsboGrowController({
+      device: makeDevice({ maxStorageBufferBindingSize: 0 }),
+      errorRegistry: spy,
+      initialSlotCount: 1,
+      perEntityStride: 256,
+      meshUsage: 0,
+      materialUsage: 0,
+    });
+    ctrl.initialBuild();
+    expect(ctrl.state.slotCount).toBe(1);
+    // Spec floor 134217728 / 256 = 524288; request 524289 exceeds.
+    const beyondCeiling = Math.floor(134217728 / 256) + 1;
+    const result = ctrl.growMeshSsbo(beyondCeiling);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.code).toBe('mesh-ssbo-ceiling-reached');
+      expect(result.degradedToSlotCount).toBe(1);
+    }
+    expect(spy.fireCount).toBe(1);
+  });
+
+  it('grow fail carries pre-grow slotCount as degradedToSlotCount', () => {
+    const spy = makeSpyErrorRegistry();
+    const smallCeiling = 256 * 256;
+    const ctrl = createMeshSsboGrowController({
+      device: makeDevice({ maxStorageBufferBindingSize: smallCeiling }),
+      errorRegistry: spy,
+      initialSlotCount: 1,
+      perEntityStride: 256,
+      meshUsage: 0,
+      materialUsage: 0,
+    });
+    ctrl.initialBuild();
+    const result1 = ctrl.growMeshSsbo(256);
+    expect(result1.ok).toBe(true);
+    expect(ctrl.state.slotCount).toBe(256);
+    // Request 1024 slots = 262144 B > 65536 B ceiling.
+    const result2 = ctrl.growMeshSsbo(1024);
+    expect(result2.ok).toBe(false);
+    if (!result2.ok) {
+      expect(result2.degradedToSlotCount).toBe(256);
+    }
+  });
+});

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

@@ -0,0 +1,79 @@
+// w30 -- mip gate unit tests (AC-09 / D-9).
+//
+// `deriveRenderDataTexture` is the fail-fast projection layer (F-6). A
+// block-compressed texture cannot have its mip chain GPU-generated (the mipmap
+// blit pipeline renders into a color attachment; compressed formats are not
+// render targets -- F-7), so a POD that carries a compressed `format` AND
+// requests runtime mip generation (`mipmap:true` WITHOUT an offline mip chain,
+// i.e. `mipLevelCount` unset or 1) must fail fast with a structured error whose
+// `.hint` tells the AI user how to self-recover (bake offline, or set
+// `compressionMode:'none'`).
+//
+// The gate distinguishes "please GENERATE mips at runtime" (blocked) from
+// "offline mips are ALREADY in `data`" (normal): a compressed POD with
+// `mipLevelCount > 1` carries a KTX2-baked chain and uploads without a gate hit.
+//
+// This is TDD-RED before w35 -- the gate does not exist yet.
+//
+// Constraints (plan-tasks w30):
+//   - no GPU mip-gen execution (pure unit on deriveRenderDataTexture)
+//   - reuse the AssetError code system (D-9); the new code is
+//     'mipgen-unsupported-compressed-format'
+
+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 {
+    kind: 'texture',
+    width: 8,
+    height: 8,
+    format: 'rgba8unorm',
+    data: new Uint8Array(8 * 8 * 4),
+    colorSpace: 'linear',
+    mipmap: false,
+    ...overrides,
+  };
+}
+
+describe('deriveRenderDataTexture -- mip gate on compressed formats (w30, AC-09)', () => {
+  it('compressed format + mipmap:true (runtime mip-gen requested) -> error', () => {
+    const res = deriveRenderDataTexture(tex({ format: 'bc7-rgba-unorm', mipmap: true }));
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.error.code).toBe('mipgen-unsupported-compressed-format');
+      // hint must guide offline baking + the sidecar self-recovery.
+      expect(res.error.hint).toMatch(/bake|offline/i);
+      expect(res.error.hint).toMatch(/mipmap|compressionMode/i);
+    }
+  });
+
+  it('mip-gate error fires for an ETC2 compressed format too', () => {
+    const res = deriveRenderDataTexture(tex({ format: 'etc2-rgba8unorm', mipmap: true }));
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.error.code).toBe('mipgen-unsupported-compressed-format');
+  });
+
+  it('compressed format + mipmap:true but offline chain present (mipLevelCount>1) -> ok', () => {
+    // The KTX2 loader baked the mip chain offline; this is the normal
+    // compressed-upload path and must NOT trip the runtime-mip-gen gate.
+    const res = deriveRenderDataTexture(
+      tex({ format: 'bc7-rgba-unorm', mipmap: true, mipLevelCount: 4 }),
+    );
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.value.mipLevelCount).toBe(4);
+  });
+
+  it('compressed format + mipmap:false -> ok (single level)', () => {
+    const res = deriveRenderDataTexture(tex({ format: 'bc7-rgba-unorm', mipmap: false }));
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.value.mipLevelCount).toBe(1);
+  });
+
+  it('uncompressed format + mipmap:true -> ok (existing runtime mip-gen path unchanged)', () => {
+    const res = deriveRenderDataTexture(tex({ format: 'rgba8unorm', mipmap: true }));
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.value.mipLevelCount).toBeGreaterThan(1);
+  });
+});