@forgeax/engine-runtime 0.1.20 → 0.1.23

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 'render-target-state-invalid':
       return code;
-    case 'hdrp-index-list-overflow':
+    case 'render-target-operation-failed':
       return code;
-    case 'hdrp-deferred-caps-insufficient':
+    case 'reflection-probe-budget-exceeded':
+      return code;
+    case 'render-intent-invalid':
       return code;
     case 'point-shadow-atlas-uninitialized':
       return code;
@@ -114,6 +128,7 @@ function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
       return code;
     case 'points-lines-prepare-failed':
       return code;
+    case 'light-resource-unavailable':
     case 'projector-binding-failed':
       return code;
     case 'volume-owner-conflict':
@@ -186,6 +201,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 +229,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 +258,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.
@@ -338,6 +393,15 @@ function narrowRenderError(err: RenderError): void {
       void err.detail.owner;
       void err.detail.generation;
       break;
+    case 'light-resource-unavailable':
+      void err.detail.entity;
+      void err.detail.feature;
+      void err.detail.generation;
+      void err.detail.sourceKey;
+      void err.detail.reason;
+      void err.expected;
+      void err.hint;
+      break;
     case 'transmission-capability-missing':
       void err.detail.material;
       void err.detail.capability;

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

@@ -40,22 +40,22 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 {
   // w9 -- render-system-extract consumer migration unit tests (M3, AC-07 / AC-15).
   //
-  // Post-migration extract reads the single resolved `Transform.world` mat4
+  // Post-migration extract reads the single resolved `GlobalTransform.world` mat4
   // (written by propagateTransforms) for every world-space consumer; the legacy
   // GlobalTransform-column-switch + per-snapshot `mat4.compose` are gone.
   //
   // Five consumer classes covered:
   //   1. mesh-walk     -> RenderableSnapshot.transform.world is the 16-float
   //      column-major world mat4 (parent x child), copied straight from the
-  //      Transform.world view; no per-snapshot compose.
+  //      GlobalTransform.world view; no per-snapshot compose.
   //   2. frustum cull  -> the cull AABB follows the world mat4 (a child placed
   //      off-screen by its parent is culled; in-screen is kept) -- same-source
   //      with the rendered world (AC-05 carried forward).
   //   3. camera view   -> CameraSnapshot.position is the world-space translation
-  //      (mat4.getTranslation of Transform.world); a child camera reflects
+  //      (mat4.getTranslation of GlobalTransform.world); a child camera reflects
   //      parent x child.
   //   4. light position -> point / spot light position is the world-space
-  //      translation extracted from Transform.world (mat4.getTranslation).
+  //      translation extracted from GlobalTransform.world (mat4.getTranslation).
   //   5. AC-15 zero-materialization -> the mesh-walk reads world through the
   //      column-level array view; it does NOT call `world.get` per renderable
   //      to materialize a `{}` whole-component object.
@@ -209,7 +209,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       expect(w?.[12]).toBeCloseTo(12, 5);
       expect(w?.[13]).toBeCloseTo(3, 5);
       expect(w?.[14]).toBeCloseTo(0, 5);
-      // The snapshot world must equal the entity's Transform.world column byte-for-byte.
+      // The snapshot world must equal the entity's GlobalTransform.world column byte-for-byte.
     });
 
     it('mesh-walk: flat root world mat4 equals compose(local)', () => {

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,
     },
@@ -290,6 +291,7 @@ async function importEcs(): Promise<{
 
 async function importComponents(): Promise<{
   Transform: unknown;
+  GlobalTransform: unknown;
   MeshFilter: unknown;
   MeshRenderer: unknown;
   Camera: unknown;
@@ -486,7 +488,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();

package/src/__tests__/render-system-record-per-submesh-transparency.test.ts

@@ -96,6 +96,7 @@ function makeMockGPUDevice(spies: DeviceSpies): { device: unknown } {
     limits: {},
     queue: {
       submit: () => undefined,
+      onSubmittedWorkDone: async () => undefined,
       writeBuffer: () => undefined,
       writeTexture: () => undefined,
     },
@@ -231,6 +232,7 @@ async function importEcs(): Promise<{
 }
 async function importComponents(): Promise<{
   Transform: unknown;
+  GlobalTransform: unknown;
   MeshFilter: unknown;
   MeshRenderer: unknown;
   Camera: unknown;
@@ -413,7 +415,9 @@ describe('record: per-submesh transparency (feat-city-glb Bug 5)', () => {
     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 spawnMixedTransparentScene();

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

@@ -1,8 +1,9 @@
 // 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
+//   M8 wires the record stage to bind a 3-binding `pbr-skin-mesh-array-bgl`
+//   (binding 0 mesh-array UBO + binding 1 current palette UBO + binding 2
+//   previous 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
@@ -13,8 +14,8 @@
 //   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
+//   (1) `buildPbrSkinLayouts` returns a 3-entry meshArrayBgl labeled
+//       `pbr-skin-mesh-array-bgl` with bindings 0 + 1 + 2 all
 //       `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
@@ -23,7 +24,7 @@
 //       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.
+//       NOT leak the 3-entry skin BGL into the URP path.
 //
 // What this test deliberately does NOT cover:
 //   - The actual `pass.setBindGroup(2, ...)` dispatch site is exercised
@@ -83,7 +84,7 @@ function makeMockDevice(): { device: PbrPipelineDevice; capture: MockDeviceCaptu
 }
 
 describe('feat-20260611 R2 / M8 / w29 — record-stage skin BindGroup BGL contract', () => {
-  it('(1) buildPbrSkinLayouts returns a 2-entry meshArrayBgl labeled pbr-skin-mesh-array-bgl with bindings 0 + 1 both hasDynamicOffset:true (storage path)', () => {
+  it('(1) buildPbrSkinLayouts returns a 3-entry meshArrayBgl labeled pbr-skin-mesh-array-bgl with bindings 0 + 1 + 2 all hasDynamicOffset:true (storage path)', () => {
     const { device, capture } = makeMockDevice();
     const pbr = buildPbrPipelineLayouts(device, { storageBuffer: true });
     const skin = buildPbrSkinLayouts(device, { storageBuffer: true }, pbr);
@@ -91,16 +92,19 @@ describe('feat-20260611 R2 / M8 / w29 — record-stage skin BindGroup BGL contra
     const skinDesc = capture.bglByHandle.get(skin.meshArrayBgl);
     expect(skinDesc).toBeDefined();
     expect(skinDesc?.label).toBe('pbr-skin-mesh-array-bgl');
-    expect(skinDesc?.entries).toHaveLength(2);
+    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', () => {
+  it('(1b) uniform fallback path: buildPbrSkinLayouts BGL bindings 0 + 1 + 2 all type=uniform', () => {
     const { device, capture } = makeMockDevice();
     const pbr = buildPbrPipelineLayouts(device, { storageBuffer: false });
     const skin = buildPbrSkinLayouts(device, { storageBuffer: false }, pbr);
@@ -108,6 +112,7 @@ describe('feat-20260611 R2 / M8 / w29 — record-stage skin BindGroup BGL contra
     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', () => {
@@ -129,7 +134,7 @@ describe('feat-20260611 R2 / M8 / w29 — record-stage skin BindGroup BGL contra
     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', () => {
+  it('(3) regression guard: buildPbrPipelineLayouts (URP) returns 1-entry meshArrayBgl labeled pbr-mesh-array-bgl — M8 must NOT leak the 3-entry skin BGL into URP', () => {
     const { device, capture } = makeMockDevice();
     const pbr = buildPbrPipelineLayouts(device, { storageBuffer: true });
 

package/src/__tests__/renderer-recover.unit.test.ts

@@ -20,6 +20,7 @@ describe('renderer recovery and receipt contract', () => {
       expect(result.error.code).toBe('renderer-state-invalid');
       expect(result.error.hint.length).toBeGreaterThan(0);
     }
+    expect(renderer.inspect().state).toBe('alive');
     await renderer.dispose();
   });
 
@@ -38,6 +39,13 @@ describe('renderer recovery and receipt contract', () => {
     expect(frame.ok).toBe(true);
     if (!frame.ok) return;
     const receipt: FrameReceipt = frame.value;
+    expect(world.update().ok).toBe(true);
+    const nextFrame = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(nextFrame.ok).toBe(true);
     const observed = await renderer.observe(receipt, { include: ['draws', 'bindings'] });
     expect(observed.ok).toBe(true);
     if (observed.ok) expect(observed.value.frameId).toBe(receipt.frameId);