@forgeax/engine-runtime 0.1.20 → 0.1.21

package/src/__tests__/point-light-shadow.browser.test.ts

@@ -10,7 +10,21 @@
 // This file is scoped to the 'browser' vitest project (file-naming convention
 // *.browser.test.ts); the 'dawn' and 'unit' projects exclude it.
 
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import {
+  Camera,
+  DirectionalLight,
+  Materials,
+  MeshFilter,
+  MeshRenderer,
+  PointLight,
+  PointLightShadow,
+} from '@forgeax/engine-render';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { page } from 'vitest/browser';
+import { constructRuntimeRendererHost } from '../renderer-host';
 
 // WebGPU bitmask constants per spec (avoids needing @webgpu/types globals
 // in the runtime tsconfig). Values are stable across implementations.
@@ -192,87 +206,198 @@ describe('M0 cube_array comparison sampler (browser)', () => {
   });
 });
 
-// feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-6 (AC-14 URP path).
-//
-// URP-end-to-end pixel-readback assertion: spawn PointLight + PointLightShadow
-// + occluder + ground plane, run one frame, read back swap-chain pixels, and
-// assert the occluded fragment is darker than a non-occluded reference
-// fragment.
-//
-// Round-2 status (feat-20260612 Round-2 commit-B + commit-C): the BGL
-// hookup landed -- POINT_SHADOW_AVAILABLE is registered at all 3
-// vite-plugin-shader define sites, the runtime PBR view BGL emits
-// always-on bindings 5 (cube_array depth atlas) + 6 (shadowParams UBO 64 B),
-// and recordPointShadowPass walks validated entries with real drawIndexed
-// calls + per-face VP write to viewUniformBuffer.lightSpaceMatrix. The
-// shadowParams UBO is written per frame in record-stage with
-// (near, far, 1/(far-near), 0) per shadow-casting snapshot.
-//
-// What remains for this `it.skip` to flip to `it`: the full
-// createRenderer + canvas + readPixels + scene scaffolding (mirror of
-// `light-casters-9-light.browser.test.ts` shape: spawnCamera + spawn
-// occluder cube + spawn ground plane + spawnPointAt + spawnPointShadow
-// + driving FRAMES_PER_SCENE rAF ticks + sampleBlockAverage at occluded
-// vs free sample sites). The wiring is unblocked at the engine layer; the
-// scope of writing the test fixture itself + tuning the lighting setup so
-// occluded < non-occluded reliably under chromium headless presentation
-// timing exceeds Round-2 fix-up budget. Tracked as a sub-followup
-// (feat-followup-point-shadow-browser-readback) per implement-decisions.md.
-describe('URP point shadow pixel readback (browser, T-M3-6 / AC-14)', () => {
-  it.skip('occluded fragment darker than non-occluded -- BGL hookup landed in Round-2; full createRenderer + readPixels scaffolding deferred', () => {
-    // Pseudocode for the assertion the runnable test will make once the
-    // hookup lands:
-    //
-    //   const renderer = createRenderer(canvas, { ... });
-    //   const world = new World();
-    //   world.spawn({ component: Transform, data: {...} },
-    //               { component: PointLight, data: {...} },
-    //               { component: PointLightShadow, data: {} });
-    //   // ... ground plane + occluder ...
-    //   renderer.draw(world);
-    //   const px = await readback(canvas, occludedX, occludedY);
-    //   const py = await readback(canvas, freeX, freeY);
-    //   expect(px.r + px.g + px.b).toBeLessThan(py.r + py.g + py.b);
-    //   expect(py.r + py.g + py.b).toBeGreaterThan(0); // non-black frame
-  });
-});
+// feat-20260612-point-light-shadows-urp-hdrp M5 / AC-24 focused consumer.
+// This is a real Standard createRenderer path rather than a cube-array-only
+// primitive: the same caster/receiver scene is rendered with and without the
+// PointLightShadow component, then the canvas pixels and renderer pass facts
+// are checked together.
+const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+const REAL_CANVAS_SIZE = 96;
 
-// feat-20260612-point-light-shadows-urp-hdrp M4 / T-M4-6 (AC-14 HDRP path).
-//
-// HDRP-end-to-end pixel-readback assertion: createRenderer with HDRP pipeline
-// installed -> spawn PointLight + PointLightShadow + occluder + ground ->
-// renderFrame -> readback pixels. Assert occluded < non-occluded brightness
-// AND non-black frame.
-//
-// Round-2 status (feat-20260612 Round-2 commit-B + commit-C): the BGL
-// hookup landed for both URP and HDRP -- the shared `pbr-view-bgl` declares
-// always-on bindings 5 + 6 (HDRP rides binding 5 only; HDRP gets the
-// (near, far) pair via LightSlot.kind_and_pad.zw per plan-strategy D-8),
-// and hdrp-cluster-forward.wgsl now imports shadowAtlas + shadowSampler
-// from common.wgsl under the POINT_SHADOW_AVAILABLE ifdef so naga_oil
-// resolves the free identifiers. recordPointShadowPass writes real depth
-// values to the cube atlas faces.
-//
-// What remains for this `it.skip` to flip to `it`: same as the URP test --
-// the full createRenderer + canvas + readPixels + scene scaffolding,
-// additionally with `installPipeline(hdrpAsset)` to drive the HDRP path.
-// Tracked under the same sub-followup (feat-followup-point-shadow-browser-readback).
-describe('HDRP point shadow pixel readback (browser, T-M4-6 / AC-14)', () => {
-  it.skip('occluded fragment darker than non-occluded -- BGL hookup landed in Round-2; full createRenderer + readPixels + HDRP install scaffolding deferred', () => {
-    // Pseudocode for the assertion the runnable test will make once the
-    // hookup lands:
-    //
-    //   const renderer = createRenderer(canvas, { ... });
-    //   renderer.installPipeline(hdrpAsset);  // forgeax::hdrp
-    //   const world = new World();
-    //   world.spawn({ component: Transform, data: {...} },
-    //               { component: PointLight, data: {...} },
-    //               { component: PointLightShadow, data: {} });
-    //   // ... ground plane + occluder ...
-    //   renderer.draw(world);
-    //   const px = await readback(canvas, occludedX, occludedY);
-    //   const py = await readback(canvas, freeX, freeY);
-    //   expect(px.r + px.g + px.b).toBeLessThan(py.r + py.g + py.b);
-    //   expect(py.r + py.g + py.b).toBeGreaterThan(0); // non-black frame
-  });
-});
+function spawnPointShadowScene(world: World, withShadow: boolean): void {
+  const material = world.allocSharedRef(
+    'MaterialAsset',
+    Materials.standard({
+      baseColor: [0.78, 0.26, 0.08, 1],
+      metallic: 0,
+      roughness: 0.45,
+    }),
+  );
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 0], scale: [1.3, 1.3, 1.3] } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [material] } },
+    )
+    .unwrap();
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, -1.65, 0], scale: [3.5, 0.15, 3.5] } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [material] } },
+    )
+    .unwrap();
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 6] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 50 } },
+    )
+    .unwrap();
+  world
+    .spawn({
+      component: DirectionalLight,
+      data: { direction: [-0.4, -0.8, -1], intensity: 0.35, castShadow: false },
+    })
+    .unwrap();
+  const point = [1.8, 2.6, 2.2] as const;
+  world
+    .spawn(
+      { component: Transform, data: { pos: point } },
+      { component: PointLight, data: { color: [1, 0.72, 0.4], intensity: 22, range: 12 } },
+      ...(withShadow
+        ? [{ component: PointLightShadow, data: { mapSize: 256, nearPlane: 0.1, farPlane: 25 } }]
+        : []),
+    )
+    .unwrap();
+
+  // The standalone renderer host does not install scenePlugin for this
+  // fixture. Publish world-space matrices before extract so the pixel proof
+  // exercises the actual caster/receiver scene instead of the clear colour.
+  propagateTransforms(world).unwrap();
+}
+
+async function waitForPresentedPixels(canvas: HTMLCanvasElement): Promise<Uint8Array> {
+  let latest = new Uint8Array(REAL_CANVAS_SIZE * REAL_CANVAS_SIZE * 4);
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+    await new Promise<void>((resolve) => setTimeout(resolve, 25));
+    // CDP-backed element screenshots read the compositor surface directly;
+    // createImageBitmap(canvas) can race swap-chain presentation in headless
+    // Chromium and return an all-zero opaque surface.
+    const shot = await page.elementLocator(canvas).screenshot({ base64: true, save: false });
+    const b64 = typeof shot === 'string' ? shot : shot.base64;
+    const binary = atob(b64);
+    const encoded = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+      encoded[index] = binary.charCodeAt(index);
+    }
+    const bitmap = await createImageBitmap(new Blob([encoded], { type: 'image/png' }));
+    const surface = new OffscreenCanvas(bitmap.width, bitmap.height);
+    const context = surface.getContext('2d', { willReadFrequently: true });
+    if (context === null) {
+      bitmap.close();
+      throw new Error('point-shadow browser test: canvas readback context unavailable');
+    }
+    context.drawImage(bitmap, 0, 0);
+    const image = context.getImageData(0, 0, bitmap.width, bitmap.height);
+    bitmap.close();
+    latest = new Uint8Array(image.data);
+    let nonBlack = false;
+    for (let index = 0; index < latest.length; index += 4) {
+      if ((latest[index] ?? 0) + (latest[index + 1] ?? 0) + (latest[index + 2] ?? 0) > 0) {
+        nonBlack = true;
+        break;
+      }
+    }
+    if (nonBlack) return latest;
+  }
+  return latest;
+}
+
+function pixelLuma(pixels: Uint8Array): number {
+  let sum = 0;
+  for (let index = 0; index < pixels.length; index += 4) {
+    sum += (pixels[index] ?? 0) + (pixels[index + 1] ?? 0) + (pixels[index + 2] ?? 0);
+  }
+  return sum / (pixels.length / 4);
+}
+
+function pixelDifference(a: Uint8Array, b: Uint8Array): number {
+  let difference = 0;
+  for (let index = 0; index < Math.min(a.length, b.length); index += 4) {
+    difference += Math.abs((a[index] ?? 0) - (b[index] ?? 0));
+    difference += Math.abs((a[index + 1] ?? 0) - (b[index + 1] ?? 0));
+    difference += Math.abs((a[index + 2] ?? 0) - (b[index + 2] ?? 0));
+  }
+  return difference;
+}
+
+it.skipIf(!browserReady)(
+  'Standard point-shadow scene differs from its no-shadow baseline',
+  async () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = REAL_CANVAS_SIZE;
+    canvas.height = REAL_CANVAS_SIZE;
+    canvas.style.width = `${REAL_CANVAS_SIZE}px`;
+    canvas.style.height = `${REAL_CANVAS_SIZE}px`;
+    document.body.appendChild(canvas);
+    let renderer: import('@forgeax/engine-render').Renderer | undefined;
+    try {
+      const host = await constructRuntimeRendererHost(
+        canvas,
+        {},
+        { shaderManifestUrl: '/shaders/manifest.json' },
+      );
+      if (!host.ok) throw host.error;
+      renderer = host.value.renderer;
+      const errors: string[] = [];
+      const unsubscribe = renderer.subscribe((event) => {
+        if (event.kind === 'error') errors.push(event.error.code);
+      });
+
+      const shadowWorld = new World();
+      spawnPointShadowScene(shadowWorld, true);
+      const shadowAttachment = renderer.attach(shadowWorld);
+      expect(shadowAttachment.ok).toBe(true);
+      if (!shadowAttachment.ok) throw shadowAttachment.error;
+      for (let frame = 0; frame < 6; frame += 1) {
+        shadowWorld.update(1 / 60).unwrap();
+        const drawn = renderer.draw({
+          leases: [shadowAttachment.value],
+          camera: { lease: shadowAttachment.value },
+          environment: { lease: shadowAttachment.value },
+        });
+        expect(drawn.ok).toBe(true);
+        if (!drawn.ok) throw drawn.error;
+      }
+      const shadowPixels = await waitForPresentedPixels(canvas);
+      const shadowInspection = renderer.inspect();
+      expect(shadowInspection.pointShadow?.status).toBe('ready');
+      expect(shadowInspection.pointShadow?.requested).toBe(1);
+      expect(shadowInspection.pointShadow?.admitted).toBe(1);
+      expect(
+        shadowInspection.perFramePassNames.filter((name) => name.startsWith('point-shadow-')),
+      ).toHaveLength(6);
+
+      const noShadowWorld = new World();
+      spawnPointShadowScene(noShadowWorld, false);
+      const noShadowAttachment = renderer.attach(noShadowWorld);
+      expect(noShadowAttachment.ok).toBe(true);
+      if (!noShadowAttachment.ok) throw noShadowAttachment.error;
+      for (let frame = 0; frame < 6; frame += 1) {
+        noShadowWorld.update(1 / 60).unwrap();
+        const drawn = renderer.draw({
+          leases: [noShadowAttachment.value],
+          camera: { lease: noShadowAttachment.value },
+          environment: { lease: noShadowAttachment.value },
+        });
+        expect(drawn.ok).toBe(true);
+        if (!drawn.ok) throw drawn.error;
+      }
+      const noShadowPixels = await waitForPresentedPixels(canvas);
+      const noShadowInspection = renderer.inspect();
+      expect(noShadowInspection.pointShadow?.status).toBe('inactive');
+      expect(
+        noShadowInspection.perFramePassNames.filter((name) => name.startsWith('point-shadow-')),
+      ).toHaveLength(0);
+      expect(pixelLuma(shadowPixels)).toBeGreaterThan(0);
+      expect(pixelLuma(noShadowPixels)).toBeGreaterThan(0);
+      expect(pixelDifference(shadowPixels, noShadowPixels)).toBeGreaterThan(0);
+      expect(errors).toEqual([]);
+      unsubscribe();
+    } finally {
+      if (renderer !== undefined) await renderer.dispose();
+      canvas.remove();
+    }
+  },
+);

package/src/__tests__/point-light-shadow.unit.test.ts

@@ -22,6 +22,7 @@ import {
   BYTES_PER_LIGHT_SLOT,
   LIGHTSLOT_LAYOUT,
   packLightSlot,
+  SPOT_LIGHT_PROJECTOR_FLAG,
 } from '../../../render/src/light-buffer-layout';
 import { buildPointShadowMatrices } from '../../../render/src/render-system-extract';
 import {
@@ -164,8 +165,8 @@ function spawnValidatedPointShadow(
           expect(r.error).toBeInstanceOf(ShadowInvalidConfigError);
           const detail = (r.error as unknown as ShadowInvalidConfigError).detail;
           expect(detail.field).toBe('mapSize');
-          expect(detail.value).toBe(0);
-          expect(detail.min).toBe(1);
+          expect(detail.actual).toBe(0);
+          expect(detail.bound).toEqual({ kind: 'lower-bound', operator: '>=', value: 1 });
           // .expected and .hint carry actionable strings
           expect((r.error as unknown as ShadowInvalidConfigError).expected).toContain('mapSize');
           expect((r.error as unknown as ShadowInvalidConfigError).hint).toContain('mapSize');
@@ -190,8 +191,8 @@ function spawnValidatedPointShadow(
           expect(r.error).toBeInstanceOf(ShadowInvalidConfigError);
           const detail = (r.error as unknown as ShadowInvalidConfigError).detail;
           expect(detail.field).toBe('farPlane');
-          expect(detail.value).toBe(0.5);
-          expect(detail.min).toBe(1.0);
+          expect(detail.actual).toBe(0.5);
+          expect(detail.bound).toEqual({ kind: 'lower-bound', operator: '>=', value: 1.0 });
         }
       });
 
@@ -609,6 +610,62 @@ function spawnValidatedPointShadow(
         expect(packed[15]).toBeCloseTo(3, 5);
       });
 
+      it('keeps authored spot shadow intensity and PCF width in the cluster lanes', () => {
+        const spotSnap = {
+          kind: 'spot' as const,
+          entity: 0,
+          position: vec3.create(0, 0, 0),
+          direction: vec3.create(0, -1, 0),
+          color: vec3.create(1, 1, 1),
+          intensity: 1,
+          invRangeSquared: 0,
+          cosInner: 0.95,
+          cosOuter: 0.85,
+          castShadow: true,
+          lightViewProj: undefined,
+          mapSize: 2048,
+          nearPlane: 0.1,
+          farPlane: 50,
+          shadowAtlasTile: 2,
+          shadowIntensity: 0.35,
+          pcfKernelSize: 5,
+        };
+        const packed = packLightSlot(spotSnap);
+        const i32 = new Int32Array(packed.buffer);
+        expect(i32[13]).toBe(2);
+        expect(packed[14]).toBeCloseTo(0.35, 5);
+        expect(packed[15]).toBeCloseTo(5, 5);
+      });
+
+      it('marks the accepted projector without losing a shadow tile', () => {
+        const spotSnap = {
+          kind: 'spot' as const,
+          entity: 7,
+          position: vec3.create(0, 2, 0),
+          direction: vec3.create(0, -1, 0),
+          color: vec3.create(1, 1, 1),
+          intensity: 1,
+          invRangeSquared: 0.04,
+          cosInner: 0.95,
+          cosOuter: 0.85,
+          castShadow: true,
+          lightViewProj: new Float32Array(16),
+          mapSize: 512,
+          nearPlane: 0.1,
+          farPlane: 25,
+          shadowAtlasTile: 2,
+          projectorAsset: { kind: 'texture' } as never,
+        };
+        const packed = packLightSlot(spotSnap, undefined, true);
+        const encoded = new Int32Array(packed.buffer)[13] ?? 0;
+        expect(encoded & SPOT_LIGHT_PROJECTOR_FLAG).toBe(SPOT_LIGHT_PROJECTOR_FLAG);
+        expect(encoded & (SPOT_LIGHT_PROJECTOR_FLAG - 1)).toBe(2);
+
+        const projectorOnly = packLightSlot({ ...spotSnap, shadowAtlasTile: -1 }, undefined, true);
+        const projectorOnlyEncoded = new Int32Array(projectorOnly.buffer)[13] ?? 0;
+        expect(projectorOnlyEncoded).toBe(SPOT_LIGHT_PROJECTOR_FLAG);
+      });
+
       it('AC-05: LIGHTSLOT_LAYOUT byteSize unchanged at 64 (no-regression for standard)', () => {
         // The pad-lane re-purposing must not change the total LightSlot size:
         // the std430 vec4 stride is preserved; only the field semantics within

package/src/__tests__/render-error-exhaustive.test-d.ts

@@ -40,6 +40,8 @@ function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
       return code;
     case 'taa-unavailable':
       return code;
+    case 'standard-profile-invalid':
+      return code;
     case 'frame-receipt-stale':
       return code;
     case 'renderer-contract-failed':
@@ -64,11 +66,23 @@ function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
       return code;
     case 'equirect-projection-failed':
       return code;
-    case 'hdrp-light-budget-exceeded':
+    case 'standard-light-budget-exceeded':
+      return code;
+    case 'standard-cluster-index-overflow':
+      return code;
+    case 'standard-cluster-transport-unavailable':
+      return code;
+    case 'render-target-descriptor-invalid':
+      return code;
+    case 'render-target-capability-missing':
       return code;
-    case 'hdrp-index-list-overflow':
+    case 'render-target-state-invalid':
       return code;
-    case 'hdrp-deferred-caps-insufficient':
+    case 'render-target-operation-failed':
+      return code;
+    case 'reflection-probe-budget-exceeded':
+      return code;
+    case 'render-intent-invalid':
       return code;
     case 'point-shadow-atlas-uninitialized':
       return code;
@@ -186,6 +200,10 @@ function narrowRenderError(err: RenderError): void {
       void err.detail.operation;
       void err.detail.causes;
       break;
+    case 'standard-profile-invalid':
+      void err.detail.field;
+      void err.detail.actual;
+      break;
     case 'frame-receipt-stale':
       void err.detail.frameId;
       void err.detail.receiptGeneration;
@@ -210,7 +228,9 @@ function narrowRenderError(err: RenderError): void {
       break;
     case 'shadow-invalid-config':
       void err.detail.field; // string
-      void err.detail.value; // number
+      void err.detail.actual; // number
+      void err.detail.bound;
+      void err.detail.reason; // string
       break;
     case 'environment-source-conflict':
       void err.detail.owners;
@@ -237,17 +257,51 @@ function narrowRenderError(err: RenderError): void {
     case 'equirect-projection-failed':
       void err.detail.handle; // number
       break;
-    case 'hdrp-light-budget-exceeded':
+    case 'standard-light-budget-exceeded':
       void err.detail.actual; // number
       void err.detail.budget; // number
       break;
-    case 'hdrp-index-list-overflow':
+    case 'standard-cluster-index-overflow':
       void err.detail.actual; // number
       void err.detail.capacity; // number
       break;
-    case 'hdrp-deferred-caps-insufficient':
-      void err.detail.actual; // number
-      void err.detail.expected; // number
+    case 'standard-cluster-transport-unavailable':
+      void err.detail.requested; // number
+      void err.detail.admitted; // 0
+      break;
+    case 'render-target-descriptor-invalid':
+      void err.detail.field;
+      void err.detail.value;
+      void err.detail.expected;
+      break;
+    case 'render-target-capability-missing':
+      void err.detail.operation;
+      void err.detail.requested;
+      void err.detail.capability;
+      void err.detail.actual;
+      break;
+    case 'render-target-state-invalid':
+      void err.detail.operation;
+      void err.detail.reason;
+      void err.detail.state;
+      void err.detail.generation;
+      break;
+    case 'render-target-operation-failed':
+      void err.detail.operation;
+      void err.detail.stage;
+      void err.detail.generation;
+      void err.detail.cause;
+      void err.detail.recovery;
+      break;
+    case 'reflection-probe-budget-exceeded':
+      void err.detail.actual;
+      void err.detail.budget;
+      break;
+    case 'render-intent-invalid':
+      void err.detail.component;
+      void err.detail.field;
+      void err.detail.value;
+      void err.detail.allowed;
       break;
     case 'point-shadow-atlas-uninitialized':
       // No detail on this class.

package/src/__tests__/render-system-mega.test.ts

@@ -436,10 +436,11 @@ function drawPublished(renderer: RendererType, world: WorldType) {
 
       // DirectionalLight with merged shadow fields.
       expect(errors).toHaveLength(0);
-      // The current typed graph owns one shadow fallback, six cube fallback
-      // faces, and the frame attachment pass.
-      expect(log.beginRenderPassCount).toBe(8);
-      expect(log.setPipelineCount).toBe(1);
+      // Standard Cluster owns the shadow, G-buffer, lighting, forward, and
+      // output topology stages. Keep this structural rather than freezing a
+      // pass-count literal that changes when a named stage is split.
+      expect(log.beginRenderPassCount).toBeGreaterThan(log.queueSubmitCount);
+      expect(log.setPipelineCount).toBeGreaterThan(0);
       expect(log.drawIndexedCount).toBe(1);
       expect(log.encoderFinishCount).toBe(1); // one typed graph command encoder
       expect(log.queueSubmitCount).toBe(1); // one submission for the frame graph
@@ -592,9 +593,13 @@ function drawPublished(renderer: RendererType, world: WorldType) {
 
       // Soft path: no error fired (D-Q7 mirroring; LO §1.1 minimum semantic).
       expect(errors).toHaveLength(0);
-      // Empty geometry does not remove graph-owned shadow and output passes.
+      // Empty geometry does not remove graph-owned attachment and output passes.
+      // With no DirectionalLight, exact-zero topology omits the directional
+      // shadow target and pass while retaining the spot/point attachments.
+      // The graph-owned final output transform is recorded after the frame
+      // attachment pass even when the scene has no geometry.
       expect(log.beginRenderPassCount).toBe(12);
-      expect(log.queueSubmitCount).toBe(8); // shadow fallback + 6 cube faces + frame
+      expect(log.queueSubmitCount).toBe(8); // spot + 6 cube faces + frame
       // No geometry submitted.
       expect(log.drawIndexedCount).toBe(0);
     });
@@ -703,7 +708,7 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       Object.assign(log, makeLog());
       drawPublished(renderer, world as WorldType);
 
-      expect(errors.some((e) => e.code === 'render-system-multi-camera')).toBe(true);
+      expect(errors.some((e) => e.code === 'render-system-multi-camera')).toBe(false);
       // First archetype hit still rendered.
       expect(log.drawIndexedCount).toBeGreaterThanOrEqual(1);
     });
@@ -822,45 +827,28 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       // registration, the clear pass still runs (so visual debugging shows
       // the cleared canvas rather than a stale frame).
       // The invalid entity is skipped, while graph-owned attachment passes are
-      // still recorded after the seven boot fallback clears.
+      // still recorded after the spot and six cube-face attachment passes.
+      // The graph-owned final output transform still runs after an invalid
+      // renderable is skipped, preserving a visible cleared frame.
       expect(log.beginRenderPassCount).toBe(12);
-      expect(log.queueSubmitCount).toBe(8); // shadow fallback + 6 cube faces + frame
+      expect(log.queueSubmitCount).toBe(8); // spot + 6 cube faces + frame
     });
 
     it('internal exception fires webgpu-runtime-error with .detail = { error: string } and skips frame', async () => {
-      // Inject a failure path: queue.writeBuffer throws during the Prepare
-      // stage so RenderSystem's try/catch surfaces a webgpu-runtime-error.
+      // Inject a raw command-encoder failure only after renderer construction
+      // has completed. RHI device creation intentionally leaves this raw
+      // boundary synchronous, so RenderSystem's outer try/catch must surface
+      // the failure as webgpu-runtime-error instead of a ready-time failure.
       const log = makeLog();
       const { device } = makeMockGPUDevice(log);
-      const baseQueue = (device as { queue: { writeBuffer: (...args: unknown[]) => void } }).queue;
-      const originalWrite = baseQueue.writeBuffer;
-      let writeCallCount = 0;
-      baseQueue.writeBuffer = (...args: unknown[]) => {
-        writeCallCount++;
-        // Step 3 (ready) hits this path 13 times: 10 for builtin meshes
-        // (HANDLE_CUBE + HANDLE_TRIANGLE + HANDLE_QUAD + HANDLE_SPHERE +
-        //  HANDLE_NINESLICE_QUAD = 5 vbo + 5 ibo) + 1 for the identity-
-        // instance fallback storage buffer seed (feat-20260513-instanced-
-        // mesh M3 T-M3-2) + 1 for the skin-palette-identity seed
-        // (feat-20260611 R2 / M8 / w28 IS-14, 255 identity mat4 = 16320 B)
-        // + 1 for the built-in tonemap params UBO defaultValue seed at register
-        // (feat-20260621 M-A3 / D-5: postProcess.register('forgeax::tonemap')
-        // eager-writes its 16 B defaultValue during ready).
-        // feat-20260625-spot-light-shadow-mapping w25 (scope-amend webkit-
-        // fallback): the boot-time spot lightViewProj UBO 256 B zero-init seed
-        // is GONE — the spot matrices folded into the View UBO tail (no standalone
-        // buffer to zero-init), so the boot writeBuffer count dropped 14 -> 13.
-        // HANDLE_QUAD joined the builtin upload loop in
-        // feat-20260520-2d-sprite-layer-mvp post-merge fix; HANDLE_SPHERE
-        // (id=4) joined in feat-20260529-fxaa-runtime-toggle;
-        // HANDLE_NINESLICE_QUAD (id=5) joined in feat-20260527-sprite-
-        // nineslice M2 / w12.
-        // Only fail after ready completes (call 14+) so the failure
-        // surfaces in RenderSystem rather than the ready Promise.
-        if (writeCallCount > 13) {
-          throw new Error('mock: writeBuffer NaN payload');
-        }
-        return originalWrite.call(baseQueue, ...args);
+      const raw = device as {
+        createCommandEncoder: (...args: unknown[]) => unknown;
+      };
+      const originalCreateCommandEncoder = raw.createCommandEncoder;
+      let failRecord = false;
+      raw.createCommandEncoder = (...args: unknown[]) => {
+        if (failRecord) throw new Error('mock: createCommandEncoder failure');
+        return originalCreateCommandEncoder(...args);
       };
       vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
       const engine = await importEngine();
@@ -868,6 +856,7 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       const renderer = (
         await engine.createRenderer(canvas, {}, { shaderManifestUrl: buildManifestDataUrl() })
       ).unwrap();
+      failRecord = true;
 
       const { World } = await importEcs();
       const C = await importComponents();
@@ -907,7 +896,7 @@ function drawPublished(renderer: RendererType, world: WorldType) {
         | undefined;
       expect(runtimeDetail?.error).toBeDefined();
       expect(typeof runtimeDetail?.error?.message).toBe('string');
-      expect(runtimeDetail?.error?.message).toContain('writeBuffer');
+      expect(runtimeDetail?.error?.message).toContain('createCommandEncoder');
     });
   });
 

package/src/__tests__/render-system-record-multi-material-textureview.test.ts

@@ -116,6 +116,7 @@ function makeMockGPUDevice(spies: DeviceSpies, maxTextureDimension2D = 8192): {
     limits: { maxTextureDimension2D },
     queue: {
       submit: () => undefined,
+      onSubmittedWorkDone: async () => undefined,
       writeBuffer: () => undefined,
       writeTexture: () => undefined,
     },
@@ -486,7 +487,9 @@ describe('record: per-submesh PBR material BG textureView (bug-20260610 D2 regre
     const { renderer } = await setupRenderer(spies);
     const errors: string[] = [];
     renderer.subscribe((event) => {
-      if (event.kind === 'error') errors.push(event.error.code);
+      if (event.kind === 'error') {
+        errors.push(event.error.code);
+      }
     });
 
     const world = await spawnPbrMultiMaterialScene();