@forgeax/engine-runtime 0.1.24 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-runtime",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -26,37 +26,37 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-animation": "0.1.24",
-    "@forgeax/engine-assets-runtime": "0.1.24",
-    "@forgeax/engine-audio-webaudio": "0.1.24",
-    "@forgeax/engine-codec": "0.1.24",
-    "@forgeax/engine-debug-draw": "0.1.24",
-    "@forgeax/engine-ecs": "0.1.24",
-    "@forgeax/engine-font": "0.1.24",
-    "@forgeax/engine-geometry": "0.1.24",
-    "@forgeax/engine-graphics-extras": "0.1.24",
-    "@forgeax/engine-image": "0.1.24",
-    "@forgeax/engine-input": "0.1.24",
-    "@forgeax/engine-math": "0.1.24",
-    "@forgeax/engine-pack": "0.1.24",
-    "@forgeax/engine-profiler": "0.1.24",
-    "@forgeax/engine-render": "0.1.24",
-    "@forgeax/engine-render-graph": "0.1.24",
-    "@forgeax/engine-rhi": "0.1.24",
-    "@forgeax/engine-rhi-null": "0.1.24",
-    "@forgeax/engine-rhi-webgpu": "0.1.24",
-    "@forgeax/engine-rhi-wgpu": "0.1.24",
-    "@forgeax/engine-scene": "0.1.24",
-    "@forgeax/engine-shader": "0.1.24",
-    "@forgeax/engine-skinning": "0.1.24",
-    "@forgeax/engine-types": "0.1.24",
-    "@forgeax/engine-vfx": "0.1.24"
+    "@forgeax/engine-animation": "0.1.25",
+    "@forgeax/engine-assets-runtime": "0.1.25",
+    "@forgeax/engine-audio-webaudio": "0.1.25",
+    "@forgeax/engine-codec": "0.1.25",
+    "@forgeax/engine-debug-draw": "0.1.25",
+    "@forgeax/engine-ecs": "0.1.25",
+    "@forgeax/engine-font": "0.1.25",
+    "@forgeax/engine-geometry": "0.1.25",
+    "@forgeax/engine-graphics-extras": "0.1.25",
+    "@forgeax/engine-image": "0.1.25",
+    "@forgeax/engine-input": "0.1.25",
+    "@forgeax/engine-math": "0.1.25",
+    "@forgeax/engine-pack": "0.1.25",
+    "@forgeax/engine-profiler": "0.1.25",
+    "@forgeax/engine-render": "0.1.25",
+    "@forgeax/engine-render-graph": "0.1.25",
+    "@forgeax/engine-rhi": "0.1.25",
+    "@forgeax/engine-rhi-null": "0.1.25",
+    "@forgeax/engine-rhi-webgpu": "0.1.25",
+    "@forgeax/engine-rhi-wgpu": "0.1.25",
+    "@forgeax/engine-scene": "0.1.25",
+    "@forgeax/engine-shader": "0.1.25",
+    "@forgeax/engine-skinning": "0.1.25",
+    "@forgeax/engine-types": "0.1.25",
+    "@forgeax/engine-vfx": "0.1.25"
   },
   "devDependencies": {
-    "@forgeax/engine-import": "0.1.24",
-    "@forgeax/engine-naga": "0.1.24",
-    "@forgeax/engine-state": "0.1.24",
-    "@forgeax/engine-vite-plugin-shader": "0.1.24",
+    "@forgeax/engine-import": "0.1.25",
+    "@forgeax/engine-naga": "0.1.25",
+    "@forgeax/engine-state": "0.1.25",
+    "@forgeax/engine-vite-plugin-shader": "0.1.25",
     "@types/node": "^20.14.0"
   },
   "forgeax": {

package/src/__tests__/dawn/hello-sprite-nineslice-section.dawn.test.ts

@@ -331,34 +331,39 @@ function midBandDistance(a: CapturedFrame, b: CapturedFrame): number {
 }
 
 describe('feat-20260527-sprite-nineslice w14 dawn smoke (stretch vs tile divergence)', () => {
-  it('stretch + tile sprite frames diverge in the mid-band after w15 (red until w15 lands)', {
-    timeout: SPRITE_NINESLICE_DAWN_TEST_TIMEOUT_MS,
-  }, async () => {
-    // Asymmetric scale: x=4 vs y=1. With slices=[0.25,0.25,0.25,0.25] and the
-    // 4x4 corner-checker texture, the post-w15 9-slice path keeps corner
-    // zones at fixed world dimensions while the legacy pre-w15 path stretches
-    // the entire quad linearly -- so post-w15 the rendered pixels in the
-    // x-band differ between modes; pre-w15 the two scenes are byte-identical.
-    const stretch = await renderOneFrame({ sliceMode: 0, scaleX: 4, scaleY: 1 });
-    const tile = await renderOneFrame({ sliceMode: 1, scaleX: 4, scaleY: 1 });
+  it(
+    'stretch + tile sprite frames diverge in the mid-band after w15 (red until w15 lands)',
+    {
+      timeout: SPRITE_NINESLICE_DAWN_TEST_TIMEOUT_MS,
+    },
+    async () => {
+      // Asymmetric scale: x=4 vs y=1. With slices=[0.25,0.25,0.25,0.25] and the
+      // 4x4 corner-checker texture, the post-w15 9-slice path keeps corner
+      // zones at fixed world dimensions while the legacy pre-w15 path stretches
+      // the entire quad linearly -- so post-w15 the rendered pixels in the
+      // x-band differ between modes; pre-w15 the two scenes are byte-identical.
+      const stretch = await renderOneFrame({ sliceMode: 0, scaleX: 4, scaleY: 1 });
+      const tile = await renderOneFrame({ sliceMode: 1, scaleX: 4, scaleY: 1 });
 
-    expect(stretch.errors).toEqual([]);
-    expect(tile.errors).toEqual([]);
+      expect(stretch.errors).toEqual([]);
+      expect(tile.errors).toEqual([]);
 
-    const dist = midBandDistance(stretch.frame, tile.frame);
+      const dist = midBandDistance(stretch.frame, tile.frame);
 
-    // RED (pre-w15): the shader ignores `material.slicesAndMode` so both
-    //   frames are byte-identical save for stochastic alpha-blend rounding;
-    //   `dist` is < 1.0 and the assertion below FAILS.
-    // GREEN (post-w15): vs_main routes stretch vs tile through different
-    //   anchor-grid mappings; mid-band pixels differ noticeably; `dist`
-    //   crosses 16 (i.e. roughly 4 byte-channel delta squared per channel
-    //   averaged across the mid-band sample window).
-    //
-    // The threshold 16 is chosen so noise (rounding from premultiplied alpha
-    // blend in srgb encoding) does not false-positive RED -> GREEN, while a
-    // genuine 9-region remap easily clears it (mid-band re-routes hundreds
-    // of pixels by tens of byte units each).
-    expect(dist).toBeGreaterThan(16);
-  });
+      // RED (pre-w15): the shader ignores `material.slicesAndMode` so both
+      //   frames are byte-identical save for stochastic alpha-blend rounding;
+      //   `dist` is < 1.0 and the assertion below FAILS.
+      // GREEN (post-w15): vs_main routes stretch vs tile through different
+      //   anchor-grid mappings; mid-band pixels differ noticeably; `dist`
+      //   crosses 16 (i.e. roughly 4 byte-channel delta squared per channel
+      //   averaged across the mid-band sample window).
+      //
+      // The threshold 16 is chosen so noise (rounding from premultiplied alpha
+      // blend in srgb encoding) does not false-positive RED -> GREEN, while a
+      // genuine 9-region remap easily clears it (mid-band re-routes hundreds
+      // of pixels by tens of byte units each).
+      expect(dist).toBeGreaterThan(16);
+    },
+    SPRITE_NINESLICE_DAWN_TEST_TIMEOUT_MS,
+  );
 });

package/src/__tests__/dawn/instances-uniform-fallback.dawn.test.ts

@@ -1,28 +1,10 @@
-// instances-uniform-fallback.dawn.test.ts -- feat-20260604-instances-per-instance-transform-shader-group3-bin
-// M1 / w6.
-//
-// AC-07: storage-buffer path + uniform-fallback path both compile and render
-// correctly for <=128 instances.
-//
-// Primary path: dawn-node renders <=128 instances through the normal storage
-// buffer path (caps.storageBuffer===true on dawn) and asserts frames are
-// non-clear (proves the storage variant renders).
-//
-// Degraded path (research R-C partial): dawn-node always has
-// caps.storageBuffer===true, so we cannot force the uniform-fallback variant
-// at the GPU level. Instead, we verify that:
-//   (a) The uniform-fallback #else form `var<uniform> instances : array<InstanceData, 128>`
-//       is present in common.wgsl (source-level structural check).
-//   (b) The variant count stays at 2 (verified by w1 unit test).
-//   (c) A non-trivial Instances render (<=128) works on the storage path.
-//
-// This is the best-effort degraded path per research R-C: "if dawn cannot
-// construct caps.storageBuffer===false, fall back to a vitest unit that
-// asserts the #else uniform array<..,128> form compiles, with reason
-// recorded."
+// World-authored Instances render through storage and uniform bindings on Dawn.
+// The restricted RHI advertises no storage buffers while retaining the real
+// WebGPU device, shader compiler, validation and pixel readback. This proves
+// the uniform lane and its 128-instance chunks, not WebGL2 backend parity.
 
 import type { MaterialAsset } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
 import { drawPublished } from '../draw-published';
 
 // Source-level structural check: common.wgsl must carry both the storage
@@ -45,7 +27,16 @@ const STORAGE_PATTERN =
 const UNIFORM_PATTERN =
   /@group\(3\)\s+@binding\(0\)\s+var<uniform>\s+instances\s*:\s*array<InstanceData,\s*128>/;
 
-describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () => {
+describe('World Instances storage and uniform submission', () => {
+  let ENGINE_MANIFEST_URL_W6: string;
+  beforeAll(async () => {
+    // Shader production is fixture setup; keep the render assertion's 30s
+    // deadline independent of a cold compiler/manifest build.
+    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+    const manifest = await buildEngineShaderManifest();
+    ENGINE_MANIFEST_URL_W6 = `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+  }, 180_000);
+
   it('(a) common.wgsl declares uniform-fallback array<InstanceData,128> under #else', async () => {
     const fsId = 'node:fs';
     const pathId = 'node:path';
@@ -88,39 +79,41 @@ describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () =
     expect(commonSrc).toMatch(/localFromInstance\s*:\s*mat4x4<f32>/);
   });
 
-  // (b) deg-path rationale: dawn-node always has caps.storageBuffer===true, so
-  // the uniform-fallback path cannot be exercised at the GPU level in this
-  // dawn test. The uniform-fallback variant is structurally verified via:
-  //   - w1 source-level variant=2 unit test (AC-11)
-  //   - w6 (a) source-level uniform array<..,128> form check above
-  //   - naga_oil compiles both variants at build-time (vite-plugin-shader)
-  // Restore as a real `it()` if a dawn-side uniform-fallback path becomes
-  // reachable (feat-20260608-ci-time-cut converted from `expect(true)`).
-  it.todo('(b) deg-path rationale recorded: dawn-node always storageBuffer=true');
-
-  it('(c) storage path renders Instances (dawn smoke integration)', async () => {
+  it.each([
+    { storage: true, grid: 8 },
+    { storage: false, grid: 8 },
+    { storage: false, grid: 12 },
+  ])('renders $grid x $grid instances with storage=$storage', async ({ storage, grid }) => {
     const dawnAvailable = typeof globalThis.navigator?.gpu?.requestAdapter === 'function';
     if (!dawnAvailable) {
       throw new Error('dawn-node navigator.gpu not injected; vitest.setup-webgpu.ts regressed');
     }
 
-    // Render <=128 instances on the storage path and assert non-clear output.
-    // This proves the storage-buffer variant of @group(3) instances works
-    // end-to-end on dawn.
-
     const { World } = await import('@forgeax/engine-ecs');
+    const { rhi } = await import('@forgeax/engine-rhi-webgpu');
+    const restrictedRhi: typeof rhi = {
+      ...rhi,
+      async requestAdapter(...args) {
+        const adapter = await rhi.requestAdapter(...args);
+        if (!adapter.ok) return adapter;
+        const requestDevice = adapter.value.requestDevice.bind(adapter.value);
+        adapter.value.requestDevice = async (options) => {
+          const result = await requestDevice(options);
+          if (result.ok && !storage)
+            Object.defineProperty(result.value, 'caps', {
+              value: { ...result.value.caps, storageBuffer: false, compute: false },
+            });
+          return result;
+        };
+        return adapter;
+      },
+    };
     const { AssetRegistry, HANDLE_CUBE } = await import('@forgeax/engine-assets-runtime');
     const { Camera, MeshRenderer } = await import('@forgeax/engine-render');
     const { Instances } = await import('@forgeax/engine-render');
     const { constructRuntimeRendererHost } = await import('../../renderer-host');
     const { MeshFilter } = await import('@forgeax/engine-render');
     const { Transform } = await import('@forgeax/engine-scene');
-    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
-    const ENGINE_MANIFEST_W6 = await buildEngineShaderManifest();
-    const ENGINE_MANIFEST_URL_W6 = `data:application/json,${encodeURIComponent(
-      JSON.stringify(ENGINE_MANIFEST_W6),
-    )}`;
-
     const W6_WIDTH = 256;
     const W6_HEIGHT = 256;
 
@@ -132,15 +125,20 @@ describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () =
       const originalRequestDevice = rawAdapter.requestDevice.bind(rawAdapter);
       rawAdapter.requestDevice = async (desc) => {
         const dev = await originalRequestDevice(desc);
-        if (sharedDevice === undefined) sharedDevice = dev;
+        if (sharedDevice === undefined) {
+          sharedDevice = dev;
+          dev.pushErrorScope('validation');
+        }
         return dev;
       };
       return rawAdapter;
     };
 
     let renderTarget: GPUTexture | undefined;
+    let targetFormat: GPUTextureFormat = 'rgba8unorm';
     const ensureTarget = (device: GPUDevice, format: GPUTextureFormat): GPUTexture => {
       if (renderTarget !== undefined) return renderTarget;
+      targetFormat = format;
       renderTarget = device.createTexture({
         size: { width: W6_WIDTH, height: W6_HEIGHT, depthOrArrayLayers: 1 },
         format,
@@ -177,15 +175,18 @@ describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () =
     try {
       host = await constructRuntimeRendererHost(
         mockCanvas,
-        {},
+        { rhi: restrictedRhi },
         { shaderManifestUrl: ENGINE_MANIFEST_URL_W6 },
       );
     } finally {
       globalThis.navigator.gpu.requestAdapter = origReq;
     }
-    expect(host.ok).toBe(true);
     if (!host.ok) throw host.error;
     const { renderer, assets } = host.value;
+    const errors: string[] = [];
+    renderer.subscribe((event) => {
+      if (event.kind === 'error') errors.push(JSON.stringify(event.error));
+    });
     expect(renderer.inspect().state).toBe('alive');
     expect(assets).toBeInstanceOf(AssetRegistry);
 
@@ -201,9 +202,8 @@ describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () =
       values: { baseColor: [0.9, 0.2, 0.2, 1], metallic: 0, roughness: 0.5 },
     } as MaterialAsset;
 
-    // Build ~60 instances (well under 128 uniform cap), 2D grid
-    const GRID = 8;
-    const COUNT = GRID * GRID; // 64
+    const GRID = grid;
+    const COUNT = GRID * GRID;
     const SP = 3.0;
     const transforms = new Float32Array(COUNT * 16);
     let idx = 0;
@@ -295,18 +295,45 @@ describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () =
     readbackBuf.unmap();
     readbackBuf.destroy();
 
-    // Sample multiple positions — the 8x8 grid should fill a substantial
-    // portion of the frame. Center should NOT be clear-color.
-    const cx = W6_WIDTH >> 1;
-    const cy = W6_HEIGHT >> 1;
-    const readPixel = (px: number, py: number): [number, number, number] => {
-      const off = py * bytesPerRow + px * 4;
-      return [bytes[off + 2] ?? 0, bytes[off + 1] ?? 0, bytes[off + 0] ?? 0];
-    };
-    const [cr, cg, cb] = readPixel(cx, cy);
-    // Clear color is ~(13, 13, 20) in sRGB bytes. Center should be
-    // significantly different (red cubes).
-    const distFromClear = Math.sqrt((cr - 13) ** 2 + (cg - 13) ** 2 + (cb - 20) ** 2);
-    expect(distFromClear).toBeGreaterThan(30);
+    expect(errors).toEqual([]);
+    expect((await device.popErrorScope())?.message).toBeUndefined();
+
+    // Count actual red material pixels; comparing against guessed clear bytes
+    // could pass an empty frame because the target applies sRGB conversion.
+    let redPixels = 0;
+    for (let y = 0; y < W6_HEIGHT; y++) {
+      for (let x = 0; x < W6_WIDTH; x++) {
+        const offset = y * bytesPerRow + x * 4;
+        const r = bytes[offset + (targetFormat.startsWith('bgra') ? 2 : 0)] ?? 0;
+        const g = bytes[offset + 1] ?? 0;
+        const b = bytes[offset + (targetFormat.startsWith('bgra') ? 0 : 2)] ?? 0;
+        if (r > g + 30 && r > b + 30) redPixels++;
+      }
+    }
+    expect(redPixels).toBeGreaterThan(COUNT * 2);
+    // The last row crosses the 128-instance boundary for the 12x12 case.
+    // Verify its last matrix reaches a distinct screen location, not a
+    // duplicate of the first chunk or merely some non-clear geometry.
+    const edge = ((GRID - 1) / 2) * SP * 0.3;
+    const ndcEdge = edge / (25 * Math.tan(Math.PI / 8));
+    const lastX = Math.round(((1 + ndcEdge) * W6_WIDTH) / 2);
+    const lastY = Math.round(((1 - ndcEdge) * W6_HEIGHT) / 2);
+    let lastInstancePixels = 0;
+    for (let y = lastY - 3; y <= lastY + 3; y++) {
+      for (let x = lastX - 3; x <= lastX + 3; x++) {
+        const offset = y * bytesPerRow + x * 4;
+        const r = bytes[offset + (targetFormat.startsWith('bgra') ? 2 : 0)] ?? 0;
+        const g = bytes[offset + 1] ?? 0;
+        const b = bytes[offset + (targetFormat.startsWith('bgra') ? 0 : 2)] ?? 0;
+        if (r > g + 30 && r > b + 30) lastInstancePixels++;
+      }
+    }
+    expect(lastInstancePixels).toBeGreaterThan(0);
+    if (!storage) {
+      const residency = renderer.inspect().instanceCollections[0];
+      expect(residency?.lane).toBe(COUNT > 128 ? 'chunked-uniform' : 'direct-uniform');
+      expect(residency?.uploadedBytes).toBe(0);
+    }
+    await renderer.dispose();
   });
 });

package/src/__tests__/dawn/material-cooked-fixture.dawn.test.ts

@@ -22,9 +22,10 @@ type CookedRecord = {
 };
 
 type MaterialRow = {
+  readonly guid: string;
   readonly kind: 'material';
   readonly payload: {
-    readonly role?: string;
+    readonly parent?: string;
     readonly cooked?: CookedRecord;
   };
 };
@@ -41,24 +42,45 @@ const fixture = JSON.parse(
   ),
 ) as { readonly assets: readonly MaterialRow[] };
 
+const materialRows = fixture.assets.filter((asset) => asset.kind === 'material');
+const root = materialRows.find((asset) => asset.payload.parent === undefined);
+const derived = materialRows.find((asset) => asset.payload.parent === root?.guid);
+
 describe('custom-shader cooked MaterialAsset fixture', () => {
-  it('keeps browser and Dawn on the same key, bytes, and values', () => {
-    const root = fixture.assets.find((asset) => asset.payload.role === 'root');
-    const derived = fixture.assets.find((asset) => asset.payload.role === 'derived');
+  it('keeps browser and Dawn on the same cooked payload with the child override', () => {
     expect(root?.payload.cooked).toBeDefined();
     expect(derived?.payload.cooked).toBeDefined();
+
+    const cookedRecords = [root?.payload.cooked, derived?.payload.cooked];
+    for (const cooked of cookedRecords) {
+      expect(cooked).toBeDefined();
+      expect(cooked?.artifact?.digest).toMatch(/^sha256:/);
+      expect(cooked?.artifact?.digest).toBe(cooked?.artifactDigest);
+      expect(cooked?.receipt?.schemaVersion).toBe('material-cook/3');
+      expect(cooked?.receipt?.identity?.layoutIdentity).toMatch(/^sha256-/);
+      expect(cooked?.receipt?.identity?.programIdentity).toMatch(/^sha256:/);
+      expect(cooked?.receipt?.identity?.pipelineIdentity).toMatch(/^sha256:/);
+      expect(cooked?.receipt?.identity?.cookIdentity).toMatch(/^sha256:/);
+      expect(cooked?.receipt?.identity?.compilerFingerprint).toMatch(/^sha256-/);
+    }
     expect(derived?.payload.cooked?.specializationKey).toBe(
       root?.payload.cooked?.specializationKey,
     );
     expect(derived?.payload.cooked?.artifactDigest).toBe(root?.payload.cooked?.artifactDigest);
-    expect(derived?.payload.cooked?.artifact.bytes).toEqual(root?.payload.cooked?.artifact.bytes);
-    expect(derived?.payload.cooked?.resolved?.values).toEqual(
-      root?.payload.cooked?.resolved?.values,
-    );
+    expect(derived?.payload.cooked?.artifact?.bytes).toEqual(root?.payload.cooked?.artifact?.bytes);
+    expect(root?.payload.cooked?.resolved?.values).toMatchObject({
+      baseColor: [0.95, 0.45, 0.2, 1],
+      time: 0,
+      speed: 2,
+    });
+    expect(derived?.payload.cooked?.resolved?.values).toMatchObject({
+      baseColor: [0.2, 0.55, 0.95, 1],
+      time: 0,
+      speed: 2,
+    });
   });
 
   it('keeps cooked layout identity and authored coordinate transforms', () => {
-    const root = fixture.assets.find((asset) => asset.payload.role === 'root');
     const cooked = root?.payload.cooked;
     expect(cooked?.receipt?.schemaVersion).toBe('material-cook/3');
     expect(cooked?.receipt?.identity?.layoutIdentity).toMatch(/^sha256-/);

package/src/__tests__/fullscreen-post-process-pass.dawn.test.ts

@@ -39,8 +39,12 @@ import { Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
 import { constructRuntimeRendererHost } from '../renderer-host';
 
-const WIDTH = 256;
-const HEIGHT = 256;
+const LIGHTWEIGHT_DAWN = process.env.FORGEAX_DAWN_LIGHTWEIGHT === '1';
+// All acceptance checks are center/readback/finite-value checks. Keep the
+// local 256px surface, but use a bounded 128px target for the isolated PR
+// carrier so each fresh renderer fixture submits fewer pixels.
+const WIDTH = LIGHTWEIGHT_DAWN ? 128 : 256;
+const HEIGHT = LIGHTWEIGHT_DAWN ? 128 : 256;
 // CLEAR_COLOR removed: feat-20260608-create-app-param-surface-trim deleted
 // `clearColor` from RendererOptions; scene clear color now lives on the Camera
 // entity. This FXAA comparison pins an opaque background explicitly so the

package/src/__tests__/instances-renderer-lifecycle.integration.test.ts

@@ -0,0 +1,161 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Camera, Instances, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { RhiNullAdapter, rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { ok } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { constructRendererHost } from '../../../render/src/construct-renderer';
+
+function requireValue<T>(
+  result:
+    | { readonly ok: true; readonly value: T }
+    | { readonly ok: false; readonly error: unknown },
+): T {
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+const manifest = `data:application/json,${encodeURIComponent(
+  JSON.stringify({
+    schemaVersion: '1.0.0',
+    entries: [
+      { hash: 'pbr00000', wgsl: 'f_schlick(', glsl: '', bindings: '' },
+      { hash: 'unlit000', wgsl: 'unlit', glsl: '', bindings: '' },
+      { hash: 'tonemap0', wgsl: 'struct TonemapParams {}', glsl: '', bindings: '' },
+    ],
+    materialShaders: [
+      {
+        identifier: 'forgeax::default-unlit',
+        sourcePath: 'unlit.wgsl',
+        composedWgsl: '/* null backend shader */',
+        paramSchema: '[]',
+        variants: [],
+      },
+    ],
+  }),
+)}`;
+function canvas(): HTMLCanvasElement {
+  return { width: 32, height: 32, getContext: () => null } as unknown as HTMLCanvasElement;
+}
+function matrices(x: number, count = 1): Float32Array {
+  const result = new Float32Array(16 * count);
+  for (let i = 0; i < count; i++)
+    result.set([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, 0, 0, 1], i * 16);
+  return result;
+}
+
+it.each([
+  1, 129, 20000,
+])('renders %i World instances after replacing and recovering the Renderer', async (count) => {
+  const adapter = new RhiNullAdapter();
+  const device = (await adapter.requestDevice()).unwrap();
+  const replacementDevice = (await adapter.requestDevice()).unwrap();
+  const replacement = new Proxy(replacementDevice, {
+    get(target, property) {
+      if (property === 'caps' && count < 20000)
+        return { ...target.caps, storageBuffer: false, compute: false };
+      const value = Reflect.get(target, property, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+  let lose!: (reason: unknown) => void;
+  const lost = new Promise<never>((_, reject) => {
+    lose = reject;
+  });
+  const first = new Proxy(device, {
+    get(target, property) {
+      if (property === 'lost') return lost;
+      if (property === 'caps' && count < 20000)
+        return { ...target.caps, storageBuffer: false, compute: false };
+      const value = Reflect.get(target, property, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+  let requests = 0;
+  const recoverable = {
+    // Recorder-wrapped backends expose only the asynchronous shader factory.
+    acquireCanvasContext: rhi.acquireCanvasContext,
+    createShaderModule: rhi.createShaderModule,
+    requestAdapter: async () =>
+      ok({
+        features: adapter.features,
+        limits: adapter.limits,
+        requestDevice: async () => ok(++requests === 1 ? first : replacement),
+      } as never),
+  } as never;
+  const world = new World();
+  const material = world.allocSharedRef('MaterialAsset', {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::default-unlit' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+    ],
+    values: { baseColor: [1, 0, 0] },
+  });
+  const entity = world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [material] } },
+      { component: Instances, data: { transforms: matrices(0, count) } },
+    )
+    .unwrap();
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    )
+    .unwrap();
+  const a = requireValue(
+    await constructRendererHost(canvas(), { rhi }, { shaderManifestUrl: manifest }),
+  ).renderer;
+  const b = requireValue(
+    await constructRendererHost(canvas(), { rhi: recoverable }, { shaderManifestUrl: manifest }),
+  ).renderer;
+  const la = requireValue(a.attach(world));
+  const lb = requireValue(b.attach(world));
+  const ra = { leases: [la], camera: { lease: la }, environment: { lease: la } };
+  const rb = { leases: [lb], camera: { lease: lb }, environment: { lease: lb } };
+  world.update(0).unwrap();
+  requireValue(a.draw(ra));
+  requireValue(b.draw(rb));
+  expect(a.inspect().instanceCollections[0]?.count).toBe(count);
+  expect(b.inspect().instanceCollections[0]?.count).toBe(count);
+  expect(b.inspect().instanceCollections[0]?.uploadedBytes).toBeGreaterThan(0);
+  requireValue(b.draw(rb));
+  expect(b.inspect().instanceCollections[0]?.uploadedBytes).toBe(0);
+  const firstRevision = b.inspect().instanceCollections[0]?.revision;
+  world.set(entity, Instances, { transforms: matrices(0.25, count) }).unwrap();
+  requireValue(a.draw(ra));
+  world.set(entity, Instances, { transforms: matrices(0.5, count) }).unwrap();
+  requireValue(a.draw(ra));
+  await a.dispose();
+  expect(world.get(entity, Instances).unwrap().transforms[12]).toBe(0.5);
+  requireValue(b.draw(rb));
+  expect(b.inspect().instanceCollections[0]?.revision).toBeGreaterThan(firstRevision ?? 0);
+  lose({ reason: 'unknown', message: 'instance recovery regression' });
+  await Promise.resolve();
+  await Promise.resolve();
+  expect(b.state()).toBe('device-lost');
+  const finalX = count === 129 ? 0.75 : 0.5;
+  if (count === 129) world.set(entity, Instances, { transforms: matrices(finalX, count) }).unwrap();
+  const recovered = await b.recover();
+  expect(recovered.ok, recovered.ok ? '' : JSON.stringify(recovered.error)).toBe(true);
+  requireValue(b.draw(rb));
+  expect(b.inspect().instanceCollections[0]?.uploadedBytes).toBe(count === 129 ? count * 64 : 0);
+  expect(b.inspect().recoveryEvidence.submissions.lastGeneration).toBe(1);
+  expect(b.inspect().frame.deviceGeneration).toBe(1);
+  // The GPU-driven primary lane owns no legacy instance buffer; its published
+  // device generation is evidenced by the submitted frame above.
+  if (count < 20000) expect(b.inspect().instanceCollections[0]?.residentGeneration).toBe(1);
+  const retained = world.get(entity, Instances).unwrap().transforms;
+  expect(retained.length).toBe(count * 16);
+  expect(retained[12]).toBe(finalX);
+  expect(retained[(count - 1) * 16 + 12]).toBe(finalX);
+  expect(b.inspect().instanceCollections[0]?.count).toBe(count);
+  await b.dispose();
+}, 60000);

package/src/__tests__/parse-asset-payload-material.cases.unit.test.ts

@@ -502,7 +502,7 @@ type __MergedKeep =
       expect(asset).toBeUndefined();
     });
 
-    it('(AC-06) payload with parent ref + valid passes -> returns MaterialAsset with both passes and parentGuid', () => {
+    it('(AC-06) payload with parent ref + own passes -> returns undefined (strict child contract)', () => {
       const reg = new AssetRegistry(makeMockShaderRegistry());
       const fn = makeParseFn(reg);
 
@@ -520,18 +520,8 @@ type __MergedKeep =
       };
       const refs = [PARENT_GUID];
 
-      const asset = fn('material', payload, refs) as
-        | (MaterialAsset & { parentGuid?: string })
-        | undefined;
-
-      expect(asset).toBeDefined();
-      if (!asset) return;
-      expect(asset.kind).toBe('material');
-      expect(asset.passes).toBeDefined();
-      expect(asset.passes?.length).toBe(1);
-      expect(asset.parentGuid).toBe(PARENT_GUID);
-      // values should still be present when both passes + parent are provided
-      expect(asset.values).toEqual({ baseColor: [1, 0, 0, 1] });
+      // A child may override values only; root-owned passes must be inherited.
+      expect(fn('material', payload, refs)).toBeUndefined();
     });
 
     it('(regression) payload with passes and without parent ref -> returns MaterialAsset with passes, no parentGuid', () => {