@forgeax/engine-runtime 0.1.2

package/src/__tests__/render-system-record.unit.test.ts

@@ -0,0 +1,270 @@
+// render-system-record.unit.test.ts
+// feat-20260615-pipeline-spec-ssot M6-T1-TEST.
+//
+// Reverse-evidence ("falsify the silent fallback") tests for the M6-T1
+// deletion of `selectStandardFallbackPipeline`. The pre-M6 record stage
+// silently fell back to URP `pipelineState.standardPipeline*` whenever the
+// per-MaterialShader cache returned null and HDRP was inactive. M6 removes
+// that branch: cache miss now resolves to null and the per-submesh draw is
+// skipped (mirroring the HDRP-active and skin-shader miss-skip semantics
+// that existed before). The fallback path is no longer reachable.
+//
+// What this file asserts:
+//   1. The exported `selectStandardFallbackPipeline` symbol is gone --
+//      grep gate at runtime via `import * as mod`.
+//   2. `getOrBuildPipeline` throws `PipelineSpecError` on a build failure
+//      rather than returning a silently-substituted boot-time fallback.
+//      This is the charter P3 explicit-failure invariant the M6 cleanup
+//      preserves end-to-end (no silent route remains in the chain).
+//   3. The MSAA route (sampleCount=4) takes a distinct cache slot from the
+//      non-MSAA route -- evidence that the record stage never folds the
+//      MSAA path back onto a non-MSAA boot-prewarmed pipeline (the old
+//      `selectGeometryPipeline(... 'standard', tonemapActive, msaaActive)`
+//      branch did exactly that fold via the `*PipelineMsaa` field hand-off).
+//
+// Anchors:
+//   - plan-strategy §M6 / D-2: silent fallback removal is the core invariant.
+//   - implement-decisions §M6-T1: dedicated function + 1 record-stage call
+//     site (line ~5080) go; the only remaining path through "shader cache
+//     returned null" is `smPipelineHandle === null -> continue` skip-draw.
+
+import type { InstanceBufferCacheEntry } from '@forgeax/engine-render/internal';
+import {
+  cacheKeyOf,
+  getOrBuildPipeline,
+  interleaveSpriteInstanceBuffer,
+  type PipelineDeviceProvider,
+  type PipelineSpec,
+  PipelineSpecError,
+  type SpriteInstancesSnapshot,
+  spriteInstancesCacheHit,
+} from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
+
+const SPEC_BASE: PipelineSpec = {
+  shader: { id: 'forgeax::default-standard-pbr', passKind: 'forward', variantSet: undefined },
+  attachments: {
+    colorFormats: ['bgra8unorm-srgb' as unknown as GPUTextureFormat],
+    depthFormat: 'depth24plus-stencil8' as unknown as GPUTextureFormat,
+    sampleCount: 1,
+  },
+  geometry: {
+    topology: 'triangle-list',
+    vertexLayout: {
+      position: new Float32Array(0),
+    },
+  },
+  renderState: undefined,
+};
+
+const SPEC_MSAA: PipelineSpec = {
+  ...SPEC_BASE,
+  attachments: { ...SPEC_BASE.attachments, sampleCount: 4 },
+};
+
+describe('render-system-record M6-T1 silent fallback removal', () => {
+  it('selectStandardFallbackPipeline export is gone (grep gate)', async () => {
+    const mod = await import('@forgeax/engine-render/internal');
+    expect((mod as Record<string, unknown>).selectStandardFallbackPipeline).toBeUndefined();
+  });
+
+  it('getOrBuildPipeline throws PipelineSpecError on build failure (no silent fallback)', () => {
+    const cache = new Map();
+    const deviceProvider: PipelineDeviceProvider = {
+      createRenderPipeline: () => ({
+        ok: false,
+        error: { code: 'webgpu-runtime-error', message: 'simulated build failure' },
+      }),
+    };
+    let caught: unknown;
+    try {
+      getOrBuildPipeline(SPEC_BASE, deviceProvider, cache);
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PipelineSpecError);
+    expect((caught as PipelineSpecError).code).toBe('pipeline-build-failed');
+    // Critical: no boot-time URP `standardPipeline` is substituted for the
+    // failure. Charter P3 explicit failure surfaces upward; the record
+    // stage's `if (smPipelineHandle === null) continue` then skip-draws.
+  });
+
+  it('MSAA route takes a distinct cache slot from non-MSAA (sampleCount=4)', () => {
+    const baseKey = cacheKeyOf(SPEC_BASE);
+    const msaaKey = cacheKeyOf(SPEC_MSAA);
+    expect(baseKey).not.toBe(msaaKey);
+    // The pre-M6 silent fallback could route an MSAA frame through
+    // `pipelineState.standardPipelineMsaa` even when the per-shader cache
+    // missed -- collapsing the MSAA spec onto the boot-prewarmed handle.
+    // M6 removes that path; identity of the cache key is the witness that
+    // sampleCount is part of the hash and never folds onto sampleCount=1.
+  });
+});
+
+// ─── feat-20260625 M3 / w9 — sprite-pass 80B interleaved single-buffer cache ──
+//
+// TDD-RED contract for the sprite-pass `SpriteInstances` upload path. The
+// plan-strategy §2 D-1 invariant:
+//
+//   The per-entity `SpriteInstances` carries mat4 transforms (16f, 64B) and
+//   per-instance UV regions (vec4, 4f, 16B). They share the same instance
+//   count and ride a SINGLE GPU buffer (one binding slot @group(3) @binding(0))
+//   with interleaved layout 80B per instance:
+//     [mat4(16f), region(4f), mat4(16f), region(4f), ...]
+//
+//   The record stage MUST:
+//     - upload `transforms.byteLength + regions.byteLength` bytes (= 80*N);
+//     - cache the GpuBuffer keyed by the entity packed u32 (cacheKey from the
+//       extract snapshot — D-9);
+//     - reuse the buffer iff (uploadedArchVersion === snapshot.archVersion
+//       AND uploadedByteLength === requestedBytes); otherwise destroy + realloc.
+//
+// Sub-assertions covered (5):
+//   (a) `interleaveSpriteInstanceBuffer(transforms, regions)` produces a
+//       Float32Array of length `N * (16 + 4) === N * 20` and total byte length
+//       `transforms.byteLength + regions.byteLength` (= 80*N).
+//   (b) Per-instance layout: byte [0..64) is the mat4, byte [64..80) is the
+//       region; second instance starts at byte 80. Probe values: distinct mat4
+//       and region per instance verify the interleave ordering.
+//   (c) Cache hit fires when both `archVersion` and `byteLength` match — the
+//       same buffer instance is reused (no `createBuffer` round).
+//   (d) Cache miss fires (byteLength change): byteLength delta marks the cache
+//       fingerprint invalid; the record stage must replace the entry.
+//   (e) Reverse-evidence: same `cacheKey` but `byteLength` changes -> cache
+//       miss (fingerprint triple is *all three* values; cacheKey alone is not
+//       sufficient).
+//
+// Anchors:
+//   - requirements AC-05 (sprite-pass 80B interleave + record-stage upload)
+//   - plan-strategy §2 D-1 (interleaved single buffer + single binding slot)
+//   - plan-strategy §2 D-9 (cacheKey still packed Entity u32)
+//   - research §Q-R-2.2 (cache fingerprint triple), §Q-R-2.4 (BGL untouched)
+
+const TRANSFORMS_PER_INSTANCE = 16;
+const REGIONS_PER_INSTANCE = 4;
+const BYTES_PER_INSTANCE = 144; // current mat4 + previous mat4 + region
+
+function makeTransforms(count: number, seed: number): Float32Array {
+  const out = new Float32Array(count * TRANSFORMS_PER_INSTANCE);
+  for (let i = 0; i < out.length; i++) out[i] = seed + i;
+  return out;
+}
+
+function makeRegions(count: number, seed: number): Float32Array {
+  const out = new Float32Array(count * REGIONS_PER_INSTANCE);
+  for (let i = 0; i < out.length; i++) out[i] = seed + i;
+  return out;
+}
+
+// Minimal `GpuBuffer`-shaped stand-in for the cache entry — the cache test
+// only exercises fingerprint comparison; buffer-internal behaviour is OOS.
+const MOCK_BUFFER = {
+  handle: { id: 'mock' } as unknown,
+  isDestroyed: false,
+  destroy: () => ({ ok: true as const, value: undefined }),
+  // biome-ignore lint/suspicious/noExplicitAny: stand-in, full shape unused
+} as any;
+
+describe('render-system-record sprite-pass temporal interleaved upload', () => {
+  it('(a) packs current + previous transforms and the atlas region per instance', () => {
+    const N = 4;
+    const transforms = makeTransforms(N, 0);
+    const regions = makeRegions(N, 1000);
+    const out = interleaveSpriteInstanceBuffer(transforms, regions);
+    expect(out).toBeInstanceOf(Float32Array);
+    expect(out.length).toBe(N * (TRANSFORMS_PER_INSTANCE * 2 + REGIONS_PER_INSTANCE));
+    expect(out.byteLength).toBe(transforms.byteLength * 2 + regions.byteLength);
+    expect(out.byteLength).toBe(N * BYTES_PER_INSTANCE);
+  });
+
+  it('(b) per-instance layout is current @ 0, previous @ 16, region @ 32', () => {
+    const N = 2;
+    // Distinct probe values: instance 0 mat4=[100..115], region=[200..203];
+    //                       instance 1 mat4=[300..315], region=[400..403].
+    const transforms = new Float32Array([
+      100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 300, 301, 302,
+      303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315,
+    ]);
+    const regions = new Float32Array([200, 201, 202, 203, 400, 401, 402, 403]);
+    const previous = makeTransforms(N, 500);
+    const out = interleaveSpriteInstanceBuffer(transforms, regions, previous);
+    expect(out.length).toBe(N * 36);
+    // Instance 0
+    for (let i = 0; i < 16; i++) expect(out[i]).toBe(100 + i);
+    for (let i = 0; i < 16; i++) expect(out[16 + i]).toBe(500 + i);
+    for (let i = 0; i < 4; i++) expect(out[32 + i]).toBe(200 + i);
+    // Instance 1
+    for (let i = 0; i < 16; i++) expect(out[36 + i]).toBe(300 + i);
+    for (let i = 0; i < 16; i++) expect(out[52 + i]).toBe(516 + i);
+    for (let i = 0; i < 4; i++) expect(out[68 + i]).toBe(400 + i);
+  });
+
+  it('(c) cache hit when (archVersion, byteLength) both match (cacheKey + triple fingerprint, D-9)', () => {
+    const cache = new Map<number, InstanceBufferCacheEntry>();
+    const entityKey = 7;
+    const snap: SpriteInstancesSnapshot = {
+      transforms: makeTransforms(4, 0),
+      regions: makeRegions(4, 0),
+      instanceCount: 4,
+      cacheKey: entityKey,
+      archVersion: 1,
+    };
+    const requestedBytes = snap.transforms.byteLength * 2 + snap.regions.byteLength;
+    cache.set(entityKey, {
+      buffer: MOCK_BUFFER,
+      uploadedArchVersion: 1,
+      uploadedByteLength: requestedBytes,
+    });
+    expect(spriteInstancesCacheHit(cache.get(entityKey), snap, requestedBytes)).toBe(true);
+  });
+
+  it('(d) cache miss when archVersion bumps (archetype grew/reallocated)', () => {
+    const cache = new Map<number, InstanceBufferCacheEntry>();
+    const entityKey = 9;
+    const snap: SpriteInstancesSnapshot = {
+      transforms: makeTransforms(4, 0),
+      regions: makeRegions(4, 0),
+      instanceCount: 4,
+      cacheKey: entityKey,
+      archVersion: 2,
+    };
+    const requestedBytes = snap.transforms.byteLength * 2 + snap.regions.byteLength;
+    cache.set(entityKey, {
+      buffer: MOCK_BUFFER,
+      uploadedArchVersion: 1, // stale
+      uploadedByteLength: requestedBytes,
+    });
+    expect(spriteInstancesCacheHit(cache.get(entityKey), snap, requestedBytes)).toBe(false);
+  });
+
+  it('(e) reverse-evidence: same cacheKey but byteLength changes -> cache miss', () => {
+    const cache = new Map<number, InstanceBufferCacheEntry>();
+    const entityKey = 11;
+    // First record: 4 instances.
+    const snap4: SpriteInstancesSnapshot = {
+      transforms: makeTransforms(4, 0),
+      regions: makeRegions(4, 0),
+      instanceCount: 4,
+      cacheKey: entityKey,
+      archVersion: 1,
+    };
+    const requestedBytes4 = snap4.transforms.byteLength * 2 + snap4.regions.byteLength;
+    cache.set(entityKey, {
+      buffer: MOCK_BUFFER,
+      uploadedArchVersion: 1,
+      uploadedByteLength: requestedBytes4,
+    });
+    // Second record on the same entity: 8 instances (grew). archVersion stays
+    // at 1 to isolate the byteLength axis -- only the byte count changed.
+    const snap8: SpriteInstancesSnapshot = {
+      transforms: makeTransforms(8, 0),
+      regions: makeRegions(8, 0),
+      instanceCount: 8,
+      cacheKey: entityKey,
+      archVersion: 1,
+    };
+    const requestedBytes8 = snap8.transforms.byteLength * 2 + snap8.regions.byteLength;
+    expect(requestedBytes8).not.toBe(requestedBytes4);
+    expect(spriteInstancesCacheHit(cache.get(entityKey), snap8, requestedBytes8)).toBe(false);
+  });
+});

package/src/__tests__/render-system-skin-bg.unit.test.ts

@@ -0,0 +1,147 @@
+// feat-20260611 R2 / M8 / w29 (IS-14): record-stage skin BindGroup unit test.
+//
+// Why this file exists:
+//   M8 wires the record stage to bind a 2-binding `pbr-skin-mesh-array-bgl`
+//   (binding 0 mesh-array UBO + binding 1 palette UBO) at group(2) when
+//   the per-entry skin discriminator (`entry.source.skin !== undefined`) is
+//   set. R1 of this loop discovered the prior 1-binding `pbr-mesh-bg`
+//   build path triggered every-frame BGL-mismatch device errors against
+//   `pbr-skin-pl`, but every static gate (typecheck / unit / dawn smoke)
+//   stayed GREEN -- the regression only surfaced in browser deviceErrors.
+//   This test lifts the BGL-shape check from the device runtime to a
+//   compile-and-run unit gate so the next regression at this slot fails
+//   fast in CI rather than at frame N.
+//
+// What this test asserts:
+//   (1) `buildPbrSkinLayouts` returns a 2-entry meshArrayBgl labeled
+//       `pbr-skin-mesh-array-bgl` with bindings 0 + 1 both
+//       `hasDynamicOffset: true`. This is the BGL the record stage
+//       must use to build a BG matching `pbr-skin-pl`.
+//   (2) The skin pipeline layout `pbr-skin-pl` references the SAME
+//       skin meshArrayBgl handle at slot 2, NOT the standard PBR
+//       `pbr-mesh-array-bgl`. This pins the BG-vs-PipelineLayout
+//       contract that R1 violated.
+//   (3) Regression guard: `buildPbrPipelineLayouts` (URP) returns a
+//       1-entry meshArrayBgl labeled `pbr-mesh-array-bgl`. M8 must
+//       NOT leak the 2-entry skin BGL into the URP path.
+//
+// What this test deliberately does NOT cover:
+//   - The actual `pass.setBindGroup(2, ...)` dispatch site is exercised
+//     by `apps/hello/skin/scripts/smoke-browser.mjs` (w27 strict gate +
+//     w30 rerun); driving recordFrame from a unit fixture would mock too
+//     much of the renderer to be a useful regression net.
+//   - Palette UBO data correctness (joint world * IBM premultiply): the
+//     skin animator integration is OOS-3 of feat-20260611. This test
+//     cares only about BGL shape + buffer-binding contract.
+
+import {
+  buildPbrPipelineLayouts,
+  buildPbrSkinLayouts,
+  type PbrPipelineDevice,
+} from '@forgeax/engine-render/internal';
+import type { BindGroupLayout, PipelineLayout, RhiError } from '@forgeax/engine-rhi';
+import { ok, type Result } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+
+interface CapturedBglDesc {
+  readonly label: string | undefined;
+  readonly entries: readonly GPUBindGroupLayoutEntry[];
+}
+
+interface CapturedPipelineLayoutDesc {
+  readonly label: string | undefined;
+  readonly bindGroupLayouts: readonly BindGroupLayout[];
+}
+
+interface MockDeviceCapture {
+  readonly bgls: CapturedBglDesc[];
+  readonly pipelineLayouts: CapturedPipelineLayoutDesc[];
+  readonly bglByHandle: Map<BindGroupLayout, CapturedBglDesc>;
+}
+
+function makeMockDevice(): { device: PbrPipelineDevice; capture: MockDeviceCapture } {
+  const bgls: CapturedBglDesc[] = [];
+  const pipelineLayouts: CapturedPipelineLayoutDesc[] = [];
+  const bglByHandle = new Map<BindGroupLayout, CapturedBglDesc>();
+  const device: PbrPipelineDevice = {
+    createBindGroupLayout(desc): Result<BindGroupLayout, RhiError> {
+      const captured: CapturedBglDesc = { label: desc.label, entries: desc.entries };
+      bgls.push(captured);
+      // Each call returns a fresh opaque handle; using a plain object lets us
+      // reference-compare layouts later (the assertion at (2) needs handle
+      // equality between the skin meshArrayBgl and pbr-skin-pl slot 2).
+      const handle = {} as BindGroupLayout;
+      bglByHandle.set(handle, captured);
+      return ok(handle);
+    },
+    createPipelineLayout(desc): Result<PipelineLayout, RhiError> {
+      pipelineLayouts.push({ label: desc.label, bindGroupLayouts: desc.bindGroupLayouts });
+      return ok({} as PipelineLayout);
+    },
+  };
+  return { device, capture: { bgls, pipelineLayouts, bglByHandle } };
+}
+
+describe('feat-20260611 R2 / M8 / w29 — record-stage skin BindGroup BGL contract', () => {
+  it('(1) buildPbrSkinLayouts binds mesh plus current/previous palettes with dynamic offsets', () => {
+    const { device, capture } = makeMockDevice();
+    const pbr = buildPbrPipelineLayouts(device, { storageBuffer: true });
+    const skin = buildPbrSkinLayouts(device, { storageBuffer: true }, pbr);
+
+    const skinDesc = capture.bglByHandle.get(skin.meshArrayBgl);
+    expect(skinDesc).toBeDefined();
+    expect(skinDesc?.label).toBe('pbr-skin-mesh-array-bgl');
+    expect(skinDesc?.entries).toHaveLength(3);
+    expect(skinDesc?.entries[0]?.binding).toBe(0);
+    expect(skinDesc?.entries[0]?.buffer?.hasDynamicOffset).toBe(true);
+    expect(skinDesc?.entries[0]?.buffer?.type).toBe('read-only-storage');
+    expect(skinDesc?.entries[1]?.binding).toBe(1);
+    expect(skinDesc?.entries[1]?.buffer?.hasDynamicOffset).toBe(true);
+    expect(skinDesc?.entries[1]?.buffer?.type).toBe('read-only-storage');
+    expect(skinDesc?.entries[2]?.binding).toBe(2);
+    expect(skinDesc?.entries[2]?.buffer?.hasDynamicOffset).toBe(true);
+    expect(skinDesc?.entries[2]?.buffer?.type).toBe('read-only-storage');
+  });
+
+  it('(1b) uniform fallback path: buildPbrSkinLayouts BGL bindings 0 + 1 both type=uniform', () => {
+    const { device, capture } = makeMockDevice();
+    const pbr = buildPbrPipelineLayouts(device, { storageBuffer: false });
+    const skin = buildPbrSkinLayouts(device, { storageBuffer: false }, pbr);
+
+    const skinDesc = capture.bglByHandle.get(skin.meshArrayBgl);
+    expect(skinDesc?.entries[0]?.buffer?.type).toBe('uniform');
+    expect(skinDesc?.entries[1]?.buffer?.type).toBe('uniform');
+    expect(skinDesc?.entries[2]?.buffer?.type).toBe('uniform');
+  });
+
+  it('(2) pbr-skin-pl slot 2 === skin meshArrayBgl handle (NOT the standard pbr-mesh-array-bgl) — pins the BG vs PipelineLayout contract R1 violated', () => {
+    const { device, capture } = makeMockDevice();
+    const pbr = buildPbrPipelineLayouts(device, { storageBuffer: true });
+    const skin = buildPbrSkinLayouts(device, { storageBuffer: true }, pbr);
+
+    // Find the pipeline layout descriptor labeled 'pbr-skin-pl'.
+    const skinPlDesc = capture.pipelineLayouts.find((d) => d.label === 'pbr-skin-pl');
+    expect(skinPlDesc).toBeDefined();
+    expect(skinPlDesc?.bindGroupLayouts).toHaveLength(4);
+    // Slot 2 must be the skin meshArrayBgl handle, NOT pbr.meshArrayBgl.
+    expect(skinPlDesc?.bindGroupLayouts[2]).toBe(skin.meshArrayBgl);
+    expect(skinPlDesc?.bindGroupLayouts[2]).not.toBe(pbr.meshArrayBgl);
+    // View / material / instances slots are reused from the URP bundle (factory
+    // contract: only meshArrayBgl is fresh).
+    expect(skinPlDesc?.bindGroupLayouts[0]).toBe(pbr.viewBgl);
+    expect(skinPlDesc?.bindGroupLayouts[1]).toBe(pbr.materialBgl);
+    expect(skinPlDesc?.bindGroupLayouts[3]).toBe(pbr.instancesBgl);
+  });
+
+  it('(3) regression guard: buildPbrPipelineLayouts (URP) returns 1-entry meshArrayBgl labeled pbr-mesh-array-bgl — M8 must NOT leak the 2-entry skin BGL into URP', () => {
+    const { device, capture } = makeMockDevice();
+    const pbr = buildPbrPipelineLayouts(device, { storageBuffer: true });
+
+    const urpMeshDesc = capture.bglByHandle.get(pbr.meshArrayBgl);
+    expect(urpMeshDesc).toBeDefined();
+    expect(urpMeshDesc?.label).toBe('pbr-mesh-array-bgl');
+    expect(urpMeshDesc?.entries).toHaveLength(1);
+    expect(urpMeshDesc?.entries[0]?.binding).toBe(0);
+    expect(urpMeshDesc?.entries[0]?.buffer?.hasDynamicOffset).toBe(true);
+  });
+});

package/src/__tests__/renderer-consumer.test-d.ts

@@ -0,0 +1,5 @@
+import type { Renderer } from '@forgeax/engine-render/internal';
+
+const consume = (renderer: Renderer): Promise<boolean> =>
+  renderer.ready.then((result) => result.ok);
+void consume;