@forgeax/engine-runtime 0.1.2

package/src/__tests__/cache-false-eviction.test.ts

@@ -0,0 +1,126 @@
+// m1-t3: cleanPerEntityCache false-eviction test (TDD red).
+//
+// Verify AC-13: cleanPerFrameCaches validatedEntityKeys built with
+// worldEntityKey prevents cross-world false eviction.
+//
+// Scenarios:
+//   1. worldA entity(1) survives one frame — not falsely evicted by
+//      worldB's cleanup logic (the validated set uses worldEntityKey).
+//   2. worldA entity(2) despawned — its cache is correctly cleaned up
+//      (normal eviction still works).
+//
+// Anchors:
+//   plan-tasks.json m1-t3
+//   plan-strategy D-1a #4
+//   requirements AC-13
+
+import { cleanPerEntityCache, worldEntityKey } from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeInnerCache(): WeakMap<object, unknown> {
+  const wm = new WeakMap<object, unknown>();
+  wm.set({}, 'stub-value');
+  return wm;
+}
+
+// ─── False eviction: worldA entry survives when worldB has same entityKey ──
+
+describe('false eviction prevention', () => {
+  it('worldA entity(1) cache survives one frame (false eviction not triggered)', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    // worldA entity(1) has a cached entry
+    const keyA_e1 = worldEntityKey(0, 1);
+    cache.set(keyA_e1, makeInnerCache());
+
+    // worldB also has entity(1) — different world, same entityKey
+    const keyB_e1 = worldEntityKey(1, 1);
+    cache.set(keyB_e1, makeInnerCache());
+
+    // Build validated set from the merged renderables:
+    // Both worldA entity(1) and worldB entity(1) are present
+    const validated = new Set<number>([keyA_e1, keyB_e1]);
+    cleanPerEntityCache(cache, validated);
+
+    // Both should survive — no false eviction
+    expect(cache.has(keyA_e1)).toBe(true);
+    expect(cache.has(keyB_e1)).toBe(true);
+  });
+
+  it('worldA entity(1) survives when worldB entity(1) is the only validated one', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    // Both worlds have entity(1) entries
+    const keyA_e1 = worldEntityKey(0, 1);
+    const keyB_e1 = worldEntityKey(1, 1);
+    cache.set(keyA_e1, makeInnerCache());
+    cache.set(keyB_e1, makeInnerCache());
+
+    // Only worldB entity(1) is in the validated set (worldA entity(1) despawned)
+    const validated = new Set<number>([keyB_e1]);
+    cleanPerEntityCache(cache, validated);
+
+    // worldA entity(1) should be evicted (it despawned)
+    expect(cache.has(keyA_e1)).toBe(false);
+    // worldB entity(1) should survive
+    expect(cache.has(keyB_e1)).toBe(true);
+  });
+});
+
+// ─── Normal eviction still works ────────────────────────────────────────────
+
+describe('normal eviction still works', () => {
+  it('worldA entity(2) despawned → cache cleaned', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    // worldA has entity(1) and entity(2)
+    const keyA_e1 = worldEntityKey(0, 1);
+    const keyA_e2 = worldEntityKey(0, 2);
+    cache.set(keyA_e1, makeInnerCache());
+    cache.set(keyA_e2, makeInnerCache());
+
+    // Only entity(1) survives — entity(2) despawned
+    const validated = new Set<number>([keyA_e1]);
+    cleanPerEntityCache(cache, validated);
+
+    // entity(1) survives
+    expect(cache.has(keyA_e1)).toBe(true);
+    // entity(2) is evicted
+    expect(cache.has(keyA_e2)).toBe(false);
+  });
+
+  it('worldA entity(2) despawned while worldB entity(2) lives → only worldA cleaned', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    const keyA_e2 = worldEntityKey(0, 2);
+    const keyB_e2 = worldEntityKey(1, 2);
+    cache.set(keyA_e2, makeInnerCache());
+    cache.set(keyB_e2, makeInnerCache());
+
+    // Only worldB entity(2) is validated
+    const validated = new Set<number>([keyB_e2]);
+    cleanPerEntityCache(cache, validated);
+
+    expect(cache.has(keyA_e2)).toBe(false);
+    expect(cache.has(keyB_e2)).toBe(true);
+  });
+});
+
+// ─── Cross-world key distinctness ───────────────────────────────────────────
+
+describe('cross-world key distinctness', () => {
+  it('same entityKey, different worldId → different worldEntityKey values', () => {
+    // This is the foundation of false-eviction prevention:
+    // worldEntityKey(0, 1) !== worldEntityKey(1, 1)
+    // So the validated set correctly distinguishes them.
+    const keyA = worldEntityKey(0, 1);
+    const keyB = worldEntityKey(1, 1);
+    expect(keyA).not.toBe(keyB);
+  });
+
+  it('same worldId, same entityKey → same worldEntityKey value', () => {
+    expect(worldEntityKey(0, 1)).toBe(worldEntityKey(0, 1));
+  });
+});

package/src/__tests__/cache-isolation-matrix.test.ts

@@ -0,0 +1,182 @@
+// m1-t2: Dual-world entity-id cache isolation matrix test (TDD red).
+//
+// Verify that the three per-entity caches use worldId composite keys
+// (worldEntityKey) to isolate entries from different worlds that share
+// the same entityKey. The caches under test:
+//
+//   1. instanceBuffers (positive half only — D-1a #1)
+//   2. materialBgPerEntity (outer Map key — D-1a #2)
+//   3. instancesBgPerEntity (outer Map key — D-1a #3)
+//
+// Anchors:
+//   plan-tasks.json m1-t2
+//   plan-strategy D-1a #1-#3
+//   requirements AC-07
+
+import { cleanPerEntityCache, worldEntityKey } from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeInnerCache(): WeakMap<object, unknown> {
+  const wm = new WeakMap<object, unknown>();
+  wm.set({}, 'stub-value');
+  return wm;
+}
+
+// ─── instanceBuffers (positive half) key isolation ─────────────────────────
+
+describe('instanceBuffers positive-half key isolation', () => {
+  it('worldA entity(42) write then worldB entity(42) miss', () => {
+    // Simulate the instanceBuffers Map<number, ...> with worldEntityKey
+    const cache = new Map<number, object>();
+
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+    const entryA = {};
+
+    // Write for worldA
+    cache.set(keyA, entryA);
+
+    // worldB entity(42) should NOT hit the worldA entry
+    expect(cache.get(keyB)).toBeUndefined();
+
+    // worldA entity(42) SHOULD hit its own entry
+    expect(cache.get(keyA)).toBe(entryA);
+  });
+
+  it('worldA entity(42) write, then worldA entity(42) read hits', () => {
+    const cache = new Map<number, object>();
+    const keyA = worldEntityKey(0, 42);
+    const entry = {};
+    cache.set(keyA, entry);
+    expect(cache.get(keyA)).toBe(entry);
+  });
+
+  it('worldA entity(1) and worldB entity(1) are independent', () => {
+    const cache = new Map<number, object>();
+    const keyA = worldEntityKey(0, 1);
+    const keyB = worldEntityKey(1, 1);
+    const entryA = { a: 1 };
+    const entryB = { b: 2 };
+
+    cache.set(keyA, entryA);
+    cache.set(keyB, entryB);
+
+    expect(cache.get(keyA)).toBe(entryA);
+    expect(cache.get(keyB)).toBe(entryB);
+    // Keys are different
+    expect(keyA).not.toBe(keyB);
+  });
+
+  it('negative half fold-bucket key is NOT worldEntityKey (stays raw)', () => {
+    // D-1a #1: negative half fold-bucket keys are NOT worldEntityKey-prefixed.
+    // They are material-handle-based fold keys and remain as-is.
+    // This test documents the invariant: a fold-bucket key is simply a
+    // negative number, not a worldEntityKey composite.
+    const foldKey = -1 - ((42 << 16) | 0); // example fold-bucket key
+    // foldKey is negative, while worldEntityKey is always >= 0
+    expect(foldKey).toBeLessThan(0);
+    expect(worldEntityKey(0, 42)).toBeGreaterThanOrEqual(0);
+  });
+});
+
+// ─── materialBgPerEntity outer Map key isolation ────────────────────────────
+
+describe('materialBgPerEntity outer Map key isolation', () => {
+  it('worldA entity(42) write then worldB entity(42) miss', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+    const entryA = makeInnerCache();
+
+    cache.set(keyA, entryA);
+
+    // worldB entity(42) should miss
+    expect(cache.get(keyB)).toBeUndefined();
+    // worldA entity(42) should hit
+    expect(cache.get(keyA)).toBe(entryA);
+  });
+
+  it('worldA entity(42) and worldB entity(42) both have independent entries', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+    const entryA = makeInnerCache();
+    const entryB = makeInnerCache();
+
+    cache.set(keyA, entryA);
+    cache.set(keyB, entryB);
+
+    expect(cache.get(keyA)).toBe(entryA);
+    expect(cache.get(keyB)).toBe(entryB);
+    expect(entryA).not.toBe(entryB);
+  });
+});
+
+// ─── instancesBgPerEntity outer Map key isolation ───────────────────────────
+
+describe('instancesBgPerEntity outer Map key isolation', () => {
+  it('worldA entity(42) write then worldB entity(42) miss', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+    const entryA = makeInnerCache();
+
+    cache.set(keyA, entryA);
+
+    expect(cache.get(keyB)).toBeUndefined();
+    expect(cache.get(keyA)).toBe(entryA);
+  });
+
+  it('worldA entity(42) and worldB entity(42) both have independent entries', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+    const entryA = makeInnerCache();
+    const entryB = makeInnerCache();
+
+    cache.set(keyA, entryA);
+    cache.set(keyB, entryB);
+
+    expect(cache.get(keyA)).toBe(entryA);
+    expect(cache.get(keyB)).toBe(entryB);
+  });
+});
+
+// ─── cleanPerEntityCache with worldEntityKey keys ───────────────────────────
+
+describe('cleanPerEntityCache with worldEntityKey keys', () => {
+  it('worldA entry survives when only worldB key is absent from validated set', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+    const keyA = worldEntityKey(0, 42);
+    const keyB = worldEntityKey(1, 42);
+
+    cache.set(keyA, makeInnerCache());
+    cache.set(keyB, makeInnerCache());
+
+    // Only worldA entity(42) is validated
+    const validated = new Set<number>([keyA]);
+    cleanPerEntityCache(cache, validated);
+
+    // worldA entry should survive
+    expect(cache.has(keyA)).toBe(true);
+    // worldB entry should be evicted (not in validated set)
+    expect(cache.has(keyB)).toBe(false);
+  });
+
+  it('worldA entry evicted when worldA key is absent from validated set', () => {
+    const cache = new Map<number, WeakMap<object, unknown>>();
+    const keyA = worldEntityKey(0, 42);
+
+    cache.set(keyA, makeInnerCache());
+
+    // Empty validated set — nothing survives
+    const validated = new Set<number>();
+    cleanPerEntityCache(cache, validated);
+
+    expect(cache.has(keyA)).toBe(false);
+  });
+});

package/src/__tests__/camera-clear-snapshot-equivalence.unit.test.ts

@@ -0,0 +1,76 @@
+// feat-20260709 M3 / w13: AC-11 Camera clear path -- CameraSnapshot.clearColor
+// structural change (D-3).
+//
+// The clear-color quartet on CameraSnapshot collapses from 4 scalars
+// (clearR/G/B/A) to a single `clearColor` field, aligned with the light
+// snapshot shape. This test asserts the extract -> snapshot -> clear-consumer
+// value is byte-equal to what the authored Camera SoA column carries, AND that
+// the zero-Camera fallback snapshot paints [0,0,0,1] (frame-snapshot.ts). This
+// is the AC-11 Camera path (q5), independent of the M2 light GPU byte-neutral
+// path.
+//
+// TDD note: this test asserts the NEW `cam.clearColor` snapshot shape and stays
+// red until w14 lands the CameraSnapshot collapse (plan-strategy §5.1
+// mixed-TDD form).
+
+import { World } from '@forgeax/engine-ecs';
+import {
+  Camera,
+  extractFrame,
+  makeZeroCameraFallbackSnapshot,
+  prepareExtractContext,
+  ZERO_CAMERA_CLEAR_FALLBACK,
+} from '@forgeax/engine-render/internal';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+
+function spawnCameraWithClear(world: World, clear: readonly [number, number, number, number]) {
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+      {
+        component: Camera,
+        data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100, clearColor: clear },
+      },
+    )
+    .unwrap();
+}
+
+describe('w13 -- CameraSnapshot.clearColor equivalence + fallback (AC-11 / D-3)', () => {
+  it('extract surfaces clearColor byte-equal to the authored Camera SoA column', () => {
+    const authored: [number, number, number, number] = [0.25, 0.5, 0.75, 1.0];
+    const world = new World();
+    spawnCameraWithClear(world, authored);
+    propagateTransforms(world);
+    const frame = extractFrame(world, prepareExtractContext(world));
+    expect(frame.cameras.length).toBe(1);
+    const cam = frame.cameras[0];
+    expect(cam).toBeDefined();
+    if (!cam) return;
+    // f32 storage rounds each channel; compare against the same rounding the
+    // pre-collapse 4-scalar path produced (each channel was an f32 column).
+    expect(Array.from(cam.clearColor)).toEqual(authored.map((v) => Math.fround(v)));
+  });
+
+  it('Camera spawned without clearColor defaults to transparent black [0,0,0,0] on the snapshot', () => {
+    const world = new World();
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+    propagateTransforms(world);
+    const frame = extractFrame(world, prepareExtractContext(world));
+    const cam = frame.cameras[0];
+    expect(cam).toBeDefined();
+    if (!cam) return;
+    expect(Array.from(cam.clearColor)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('zero-Camera fallback snapshot carries clearColor = [0,0,0,1] (frame-snapshot.ts)', () => {
+    const snap = makeZeroCameraFallbackSnapshot();
+    expect(Array.from(snap.clearColor)).toEqual([0, 0, 0, 1]);
+    expect(Array.from(snap.clearColor)).toEqual(Array.from(ZERO_CAMERA_CLEAR_FALLBACK));
+  });
+});

package/src/__tests__/clamp-to-last.e2e.browser.test.ts

@@ -0,0 +1,183 @@
+// clamp-to-last.e2e.browser.test.ts -- feat-20260629-multi-uv-set-support m3-w6 fixup
+//
+// Browser e2e test for clamp-to-last: AC-08 + AC-12 combined gate.
+//
+// AC-08 = PSO builds successfully for any material declaring 1..8 UV sets.
+// AC-12 = single-UV mesh + built-in standard PBR renders without regression
+// (zero-rhi-errors baseline from pre-feat state).
+//
+// NEW DESIGN (post user-verdict, implement-review round):
+//   Built-in PBR falls back to single UV; multi-UV is consumed only by
+//   custom materials. This test exercises the single-UV path with the
+//   built-in standard PBR shader — the regression baseline for AC-12 and
+//   the single-UV half of AC-08. Multi-UV + custom-material PSO paths are
+//   exercised by the dawn e2e tests (multi-uv-8set.e2e.dawn.test.ts,
+//   clamp-to-last.e2e.dawn.test.ts).
+//
+// DEVICE-LOST FILTER: The browser vitest runner teardowns can fire
+// `device-lost` / `rhi-not-available` from prior test teardowns
+// (known issue-466 — chromium headless + swiftshader timing artifact,
+// memory `issue-466-lit-pixels-device-lost-unfiltered-error-bus`).
+// This test filters out device-lost family codes and only asserts on
+// SUT-attributable render errors (PSO compile / limit / submit).
+//
+// FIXUP (m3-w6-fixup): Round 2 replaced the hand-rolled mock canvas +
+// adapter-capture boot sequence with the same real-canvas + Engine.create
+// pattern used by light-casters-9-light.browser.test.ts. The mock canvas
+// `getCurrentTexture()` returned a manually-allocated Texture that is not
+// a real swap-chain texture; in true chromium (vitest browser mode) the
+// draw pipeline rejects non-swap-chain textures and `renderer.draw()` returns
+// ok:false. Real canvas + Engine.create boots the full swap-chain pipeline;
+// draw succeeds in chromium like every other browser e2e test.
+//
+// Runs via pnpm test:browser against wgpu-wasm/WebGL2 backend.
+
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render/internal';
+import { Transform } from '@forgeax/engine-scene';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Engine } from '../index';
+
+const W = 256;
+const H = 256;
+
+// RhiErrorCode / RuntimeErrorCode / PostProcessErrorCode members that are
+// SUT-attributable — PSO compile failure, limit exceeded, queue submit
+// failure, etc. Errors from device-lost / teardown races are EXCLUDED.
+const SUT_ATTRIBUTABLE_RENDER_CODES: ReadonlySet<string> = new Set([
+  // RhiErrorCode — compile / resource / submit failures the SUT owns
+  'shader-compile-failed',
+  'feature-not-enabled',
+  'limit-exceeded',
+  'queue-submit-failed',
+  'queue-write-buffer-out-of-bounds',
+  // RuntimeErrorCode — render-system / asset-load failures the SUT owns
+  'render-system-no-camera',
+  'render-system-multi-camera',
+  'render-system-multi-light',
+  'asset-not-registered',
+  'material-resolved-empty-passes',
+  'vertex-storage-buffer-unavailable',
+  'mesh-ssbo-capacity-exceeded',
+  'mesh-ssbo-ceiling-reached',
+  'hdrp-caps-insufficient',
+  'hdrp-light-budget-exceeded',
+  'hdrp-index-list-overflow',
+  'hdrp-deferred-caps-insufficient',
+  'gbuffer-rt-alloc-failed',
+  'gbuffer-attachment-count-mismatch',
+]);
+
+// Suppress WebGPU teardown race: chromium fires unhandled OperationError
+// ("Instance dropped error in getCompilationInfo") when shader compilation
+// is in-flight as the device is GC'd after test completion. This is a
+// known chromium headless + swiftshader timing artifact (not a test bug).
+if (typeof window !== 'undefined') {
+  window.addEventListener('unhandledrejection', (e) => {
+    if (e.reason instanceof DOMException && e.reason.message.includes('Instance dropped')) {
+      e.preventDefault();
+    }
+  });
+}
+
+const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+type EngineRenderer = Awaited<ReturnType<typeof Engine.create>>;
+
+async function buildRenderer(canvas: HTMLCanvasElement): Promise<EngineRenderer> {
+  const r = await Engine.create(canvas, {}, { shaderManifestUrl: '/shaders/manifest.json' });
+  return r;
+}
+
+describe('clamp-to-last e2e browser (m3-w6)', () => {
+  let canvas: HTMLCanvasElement | undefined;
+  let renderer: EngineRenderer | undefined;
+
+  afterEach(() => {
+    renderer = undefined;
+    if (canvas !== undefined && canvas.parentNode !== null) {
+      canvas.parentNode.removeChild(canvas);
+    }
+    canvas = undefined;
+  });
+
+  it.skipIf(!browserReady)(
+    "'browser-webgpu-missing' -- browser navigator.gpu not available",
+    () => {
+      expect(browserReady).toBe(true);
+    },
+  );
+
+  // AC-08/AC-12: single-UV mesh + built-in standard PBR builds PSO and
+  // renders without SUT-attributable errors. This exercises the
+  // single-UV half of AC-08 (PSO build success) and the zero-regression
+  // contract of AC-12 (no new rhi-errors introduced by the clamp-to-last
+  // / multi-UV branch in the single-UV baseline path).
+  //
+  // Design: built-in PBR falls back to single UV; multi-UV is consumed
+  // only by custom materials (per user verdict in implement-review).
+  // The unit cube carries exactly 1 UV set, which is the default PBR
+  // baseline — PSO build must succeed and draw must not fire
+  // SUT-attributable errors.
+  //
+  // device-lost filtering: the browser vitest runner fires device-lost
+  // / rhi-not-available from prior test teardowns (chromium headless +
+  // swiftshader timing artifact, known issue-466). These are excluded
+  // from the error count; only SUT-attributable codes fail the test.
+  it('AC-08/AC-12: single-UV mesh + built-in standard PBR builds PSO and renders without SUT-attributable error', async () => {
+    canvas = document.createElement('canvas');
+    canvas.id = 'clamp-to-last-test-canvas';
+    canvas.width = W;
+    canvas.height = H;
+    canvas.style.width = `${W}px`;
+    canvas.style.height = `${H}px`;
+    canvas.style.display = 'block';
+    document.body.appendChild(canvas);
+
+    renderer = await buildRenderer(canvas);
+    const ready = await renderer.ready;
+    expect(ready.ok).toBe(true);
+
+    const world = new World();
+    const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
+    world.spawn(
+      {
+        component: Transform,
+        data: {
+          pos: [0, 0, 0],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      },
+      { component: MeshFilter, data: { assetHandle: cubeHandle } },
+      { component: MeshRenderer, data: {} },
+    );
+    world.spawn(
+      {
+        component: Transform,
+        data: {
+          pos: [0, 0, 3],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    );
+
+    const sutErrors: Array<{ code: string }> = [];
+    renderer.onError((e) => {
+      sutErrors.push(e);
+    });
+
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    for (let f = 0; f < 10; f++) {
+      world.update(1 / 60).unwrap();
+      const drawn = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      expect(drawn.ok).toBe(true);
+    }
+
+    const sutAttributable = sutErrors.filter((e) => SUT_ATTRIBUTABLE_RENDER_CODES.has(e.code));
+    expect(sutAttributable).toEqual([]);
+  });
+});