@forgeax/engine-runtime 0.1.4 → 0.1.7

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

@@ -5,29 +5,66 @@
 // Each original file body sits in its own block-scope so helper names
 // cannot collide; describe() inside still registers globally with vitest.
 
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import type { World as WorldType } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
 import type { Renderer as RendererType } from '@forgeax/engine-render';
 import {
-  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
-  DEFAULT_UNLIT_PARAM_SCHEMA,
-} from '@forgeax/engine-shader';
+  Camera,
+  DirectionalLight,
+  Instances,
+  MeshFilter,
+  MeshRenderer,
+} from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
 import type { Handle } from '@forgeax/engine-types';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { canonicalDefaultMaterialVariants } from './helpers/mock-shader-registry';
-import {
-  TEST_CUBE_HANDLE,
-  TEST_TRIANGLE_HANDLE,
-  withPrimitiveMeshes,
-} from './helpers/primitive-world';
-
-function canonicalMaterialParamSchema(identifier: string): string {
-  if (identifier === 'forgeax::default-standard-pbr') {
-    return JSON.stringify(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
-  }
-  if (identifier === 'forgeax::default-unlit') {
-    return JSON.stringify(DEFAULT_UNLIT_PARAM_SCHEMA);
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+import { drawWithOwners } from './renderer-test-utils';
+
+type RendererErrorObservation = {
+  readonly code: string;
+  readonly detail?: unknown;
+  readonly hint?: string;
+};
+
+type RendererLike = RendererType;
+
+function unwrapRendererError(value: unknown): RendererErrorObservation {
+  let current = value as RendererErrorObservation;
+  while (
+    current.detail !== undefined &&
+    typeof current.detail === 'object' &&
+    current.detail !== null
+  ) {
+    const cause = (current.detail as { cause?: unknown }).cause;
+    if (
+      cause === undefined ||
+      typeof cause !== 'object' ||
+      cause === null ||
+      typeof (cause as { code?: unknown }).code !== 'string'
+    ) {
+      break;
+    }
+    current = cause as RendererErrorObservation;
   }
-  return '[]';
+  return current;
+}
+
+function subscribeRendererErrors(
+  renderer: RendererType,
+  listener: (error: RendererErrorObservation) => void,
+): () => void {
+  return renderer.subscribe((event) => {
+    if (event.kind === 'error') listener(unwrapRendererError(event.error));
+  });
+}
+
+function drawPublished(renderer: RendererType, world: WorldType) {
+  const attached = renderer.attach(world);
+  if (!attached.ok) throw attached.error;
+  world.update().unwrap();
+  return drawWithOwners(renderer, world);
 }
 
 // ─── from render-system.test.ts ───
@@ -43,11 +80,11 @@ function canonicalMaterialParamSchema(identifier: string): string {
   //
   // Charter proposition 4 mapping:
   //   case A (entity missing Transform / MeshRenderer): default
-  //          values used; no onError fired (D-Q7 softening point).
+  //          values used; no error event fired (D-Q7 softening point).
   //   case B (world has 0 Camera entity): fires
   //          'render-system-no-camera' + frame skipped.
   //   case C (world has 0 DirectionalLight): unlit fallback
-  //          (intensity = 0); no onError fired (D-Q7 softening point).
+  //          (intensity = 0); no error event fired (D-Q7 softening point).
   //   case D (world has N>1 Camera / Light): fires
   //          'render-system-multi-camera' / 'render-system-multi-light' +
   //          uses first archetype hit.
@@ -154,6 +191,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
           log.writeBufferCount++;
         },
         writeTexture: () => undefined,
+        onSubmittedWorkDone: () => Promise.resolve(undefined),
       },
       createShaderModule: () => ({ getCompilationInfo: async () => ({ messages: [] }) }),
       createBindGroupLayout: () => ({}),
@@ -172,7 +210,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
             setPipeline: () => {
               log.setPipelineCount++;
             },
-            setViewport: () => undefined,
             setVertexBuffer: () => undefined,
             setIndexBuffer: () => undefined,
             setBindGroup: (groupIndex: number, _bg: unknown, dynamicOffsets?: number[]) => {
@@ -235,17 +272,13 @@ function canonicalMaterialParamSchema(identifier: string): string {
     // w10: materialShaders[] entries are required so the record/extract path
     // can validate material passes that reference forgeax::default-standard-pbr
     // and forgeax::default-unlit. Each entry carries a minimal composedWgsl
-    // stub + schema + the canonical capability variants.
+    // stub + empty paramSchema + empty variants.
     const materialShaderStub = (identifier: string) => ({
       identifier,
       sourcePath: `${identifier}.wgsl`,
       composedWgsl: '/* stub */',
-      paramSchema: canonicalMaterialParamSchema(identifier),
-      variants: canonicalDefaultMaterialVariants(identifier).filter(
-        (variant) =>
-          variant.defines.STORAGE_BUFFER_AVAILABLE === false &&
-          variant.defines.VERTEX_COLOR_AVAILABLE === false,
-      ),
+      paramSchema: '[]',
+      variants: [],
     });
     const manifest = {
       schemaVersion: '1.0.0',
@@ -292,19 +325,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
   // Type-only import imports the public surface so we can assert RenderSystem
   // is re-exported by `@forgeax/engine-runtime` (F-1 single-import contract part 3/3).
   async function importEngine(): Promise<{
-    createRenderer: (
-      canvas: unknown,
-      opts?: unknown,
-      bundler?: unknown,
-    ) => Promise<{
-      backend: string;
-      ready: Promise<void>;
-      draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
-      onError: (cb: (err: { code: string; detail?: unknown; hint?: string }) => void) => () => void;
-      assets: {
-        register: (asset: unknown) => { ok: boolean; value: unknown };
-      };
-    }>;
+    createRenderer: (...args: unknown[]) => Promise<{ unwrap(): RendererLike }>;
   }> {
     return (await import(ENGINE)) as never;
   }
@@ -317,8 +338,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       allocSharedRef: (target: string, payload: unknown) => Handle<string, 'shared'>;
     };
   }> {
-    const { World: BaseWorld } = await import('@forgeax/engine-ecs');
-    return { World: withPrimitiveMeshes(BaseWorld) } as never;
+    return (await import('@forgeax/engine-ecs')) as never;
   }
 
   async function importComponents(): Promise<{
@@ -336,27 +356,14 @@ function canonicalMaterialParamSchema(identifier: string): string {
     HANDLE_TRIANGLE: Handle<'MeshAsset', 'shared'>;
   }> {
     return {
-      ...(await import('@forgeax/engine-render/internal')),
+      ...(await import('@forgeax/engine-render')),
       ...(await import('@forgeax/engine-scene')),
-      HANDLE_CUBE: TEST_CUBE_HANDLE,
-      HANDLE_TRIANGLE: TEST_TRIANGLE_HANDLE,
+      ...(await import('@forgeax/engine-assets-runtime')),
     } as never;
   }
 
   interface TestSetup {
-    createRenderer: (
-      canvas: unknown,
-      opts?: unknown,
-      bundler?: unknown,
-    ) => Promise<{
-      backend: string;
-      ready: Promise<void>;
-      draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
-      onError: (cb: (err: { code: string; detail?: unknown; hint?: string }) => void) => () => void;
-      assets: {
-        register: (asset: unknown) => { ok: boolean; value: unknown };
-      };
-    }>;
+    createRenderer: (...args: unknown[]) => Promise<RendererType>;
     log: DeviceCallLog;
   }
 
@@ -365,7 +372,10 @@ function canonicalMaterialParamSchema(identifier: string): string {
     const { device } = makeMockGPUDevice(log);
     vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
     const engine = await importEngine();
-    return { createRenderer: engine.createRenderer, log };
+    return {
+      createRenderer: async (...args: unknown[]) => (await engine.createRenderer(...args)).unwrap(),
+      log,
+    };
   }
 
   // ─── Tests ──────────────────────────────────────────────────────────────────
@@ -379,7 +389,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const world = new World();
@@ -417,28 +426,24 @@ function canonicalMaterialParamSchema(identifier: string): string {
       );
 
       const errors: { code: string }[] = [];
-      renderer.onError((e) => errors.push(e));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      Object.assign(log, makeLog());
+      drawPublished(renderer, world as WorldType);
 
       // DirectionalLight with merged shadow fields.
       expect(errors).toHaveLength(0);
-      // Seven boot fallback clears remain outside the frame graph. The typed
-      // graph adds directional, spot, point-shadow, and main attachment passes.
-      expect(log.beginRenderPassCount).toBe(14);
-      // CSM shadow passes bind their own pipeline before the main draw.
-      expect(log.setPipelineCount).toBeGreaterThanOrEqual(1);
-      // The typed shadow graph may record a caster draw in addition to the
-      // main unlit draw; the contract is that the renderable is not dropped.
-      expect(log.drawIndexedCount).toBeGreaterThanOrEqual(1);
-      expect(log.encoderFinishCount).toBe(8); // shadow fallback + 6 cube fallback faces + frame
-      expect(log.queueSubmitCount).toBe(8); // shadow fallback + 6 cube fallback faces + frame
+      // 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);
+      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
       // Three BindGroups recorded per entity (view / material / mesh-array).
       expect(log.setBindGroupCount).toBeGreaterThanOrEqual(3);
-    }, 30_000);
+    });
 
     it('AC-09: RenderSystem is NOT registered as an ECS schedule system', async () => {
       const { createRenderer } = await setupWebGPU();
@@ -448,18 +453,18 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const world = new World();
       // RenderSystem must NOT be auto-attached: world.update(1 / 60).unwrap() does not run
       // it (engine internal phase, plan-strategy D-S2).
       expect(world.inspect().systemCount).toBe(0);
       expect(world.inspect().systemCount).toBe(0);
-    }, 30_000);
+      await renderer.dispose();
+    });
   });
 
   describe('RenderSystem error tier table (D-S4..D-S8)', () => {
-    it('case A: entity missing Transform / MeshRenderer uses defaults; does NOT fire onError', async () => {
+    it('case A: entity missing Transform / MeshRenderer uses defaults; does NOT fire an error event', async () => {
       const { createRenderer } = await setupWebGPU();
       const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
       const renderer = await createRenderer(
@@ -467,7 +472,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const world = new World();
@@ -494,12 +498,8 @@ function canonicalMaterialParamSchema(identifier: string): string {
       world.spawn({ component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } });
 
       const errors: { code: string }[] = [];
-      renderer.onError((e) => errors.push(e));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
       expect(errors).toHaveLength(0);
     });
 
@@ -518,7 +518,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const world = new World();
@@ -530,12 +529,8 @@ function canonicalMaterialParamSchema(identifier: string): string {
       );
 
       const errors: { code: string }[] = [];
-      renderer.onError((e) => errors.push(e));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
 
       expect(errors.some((e) => e.code === 'render-system-no-camera')).toBe(true);
       // Clear pass executed under the synthetic camera path; the frame is
@@ -544,13 +539,13 @@ function canonicalMaterialParamSchema(identifier: string): string {
       // through the identity projection — that's an acceptable AI-user
       // signal (something paints + diagnostic fires) over the previous
       // "blank canvas + console error" silent skip. Assert at least one
-      // additional submit landed beyond the renderer.ready baseline
+      // additional submit landed beyond the renderer construction baseline
       // (shadowFallback).
       expect(log.queueSubmitCount).toBeGreaterThanOrEqual(2);
       expect(log.beginRenderPassCount).toBeGreaterThanOrEqual(2);
     });
 
-    it('case E: world has Camera + 0 renderables emits clear-pass-only frame; does NOT fire onError', async () => {
+    it('case E: world has Camera + 0 renderables emits clear-pass-only frame; does NOT fire an error event', async () => {
       // LO §1.1 hello-window minimum semantic: `Engine.create({ clearColor })`
       // must paint the swap-chain even when no entity carries MeshFilter +
       // MeshRenderer. The engine softens the empty-renderables case (Case E,
@@ -565,7 +560,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const world = new World();
@@ -591,23 +585,19 @@ function canonicalMaterialParamSchema(identifier: string): string {
       );
 
       const errors: { code: string }[] = [];
-      renderer.onError((e) => errors.push(e));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as 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.
-      expect(log.beginRenderPassCount).toBe(11);
+      expect(log.beginRenderPassCount).toBe(12);
       expect(log.queueSubmitCount).toBe(8); // shadow fallback + 6 cube faces + frame
       // No geometry submitted.
       expect(log.drawIndexedCount).toBe(0);
     });
 
-    it('case C: world has 0 DirectionalLight renders unlit; does NOT fire onError', async () => {
+    it('case C: world has 0 DirectionalLight renders unlit; does NOT fire an error event', async () => {
       const { createRenderer, log } = await setupWebGPU();
       const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
       const renderer = await createRenderer(
@@ -615,7 +605,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const world = new World();
@@ -644,16 +633,14 @@ function canonicalMaterialParamSchema(identifier: string): string {
       // No DirectionalLight.
 
       const errors: { code: string }[] = [];
-      renderer.onError((e) => errors.push(e));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      Object.assign(log, makeLog());
+      drawPublished(renderer, world as WorldType);
 
       expect(errors).toHaveLength(0);
-      // Shadow and main passes are both allowed to visit the renderable.
-      expect(log.drawIndexedCount).toBeGreaterThanOrEqual(1);
+      expect(log.drawIndexedCount).toBe(1);
     });
 
     it('case D: world has N>1 Camera fires render-system-multi-camera + uses first hit', async () => {
@@ -664,7 +651,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const world = new World();
@@ -709,12 +695,11 @@ function canonicalMaterialParamSchema(identifier: string): string {
       );
 
       const errors: { code: string; hint?: string }[] = [];
-      renderer.onError((e) => errors.push(e));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      Object.assign(log, makeLog());
+      drawPublished(renderer, world as WorldType);
 
       expect(errors.some((e) => e.code === 'render-system-multi-camera')).toBe(true);
       // First archetype hit still rendered.
@@ -735,7 +720,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const world = new World();
@@ -768,11 +752,10 @@ function canonicalMaterialParamSchema(identifier: string): string {
       );
 
       const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      drawPublished(renderer, world as WorldType);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      Object.assign(log, makeLog());
+      drawPublished(renderer, world as WorldType);
 
       const multiLightCalls = warnSpy.mock.calls.filter(
         (c) =>
@@ -786,7 +769,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
   });
 
   describe('RenderSystem asset-not-registered + internal exception (.detail F-3 contract)', () => {
-    it('asset-not-registered fires onError with .detail = { assetHandle } and skips entity', async () => {
+    it('asset-not-registered fires an error event with .detail = { assetHandle } and skips entity', async () => {
       const { createRenderer, log } = await setupWebGPU();
       const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
       const renderer = await createRenderer(
@@ -794,7 +777,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const world = new World();
@@ -822,18 +804,16 @@ function canonicalMaterialParamSchema(identifier: string): string {
         { component: C.Transform, data: identityTransform() },
       );
 
-      const errors: { code: string; detail?: { assetHandle?: number } }[] = [];
-      renderer.onError((e) => errors.push(e as never));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      const errors: RendererErrorObservation[] = [];
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
 
       const assetErr = errors.find((e) => e.code === 'asset-not-registered');
       expect(assetErr).toBeDefined();
       expect(assetErr?.detail).toBeDefined();
-      expect(assetErr?.detail?.assetHandle).toBe(BAD_HANDLE);
+      expect((assetErr?.detail as { assetHandle?: number } | undefined)?.assetHandle).toBe(
+        BAD_HANDLE,
+      );
       // The bad entity is skipped; no draw recorded for it (only entity).
       expect(log.drawIndexedCount).toBe(0);
       // Case E secondary-fix: even when every renderable fails asset
@@ -841,7 +821,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       // 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.
-      expect(log.beginRenderPassCount).toBe(11);
+      expect(log.beginRenderPassCount).toBe(12);
       expect(log.queueSubmitCount).toBe(8); // shadow fallback + 6 cube faces + frame
     });
 
@@ -883,12 +863,9 @@ function canonicalMaterialParamSchema(identifier: string): string {
       vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
       const engine = await importEngine();
       const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
-      const renderer = await engine.createRenderer(
-        canvas,
-        {},
-        { shaderManifestUrl: buildManifestDataUrl() },
-      );
-      await renderer.ready;
+      const renderer = (
+        await engine.createRenderer(canvas, {}, { shaderManifestUrl: buildManifestDataUrl() })
+      ).unwrap();
 
       const { World } = await importEcs();
       const C = await importComponents();
@@ -916,23 +893,19 @@ function canonicalMaterialParamSchema(identifier: string): string {
         { component: C.Transform, data: identityTransform() },
       );
 
-      const errors: {
-        code: string;
-        detail?: { error?: { code: string; message: string } };
-      }[] = [];
-      renderer.onError((e) => errors.push(e as never));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      const errors: RendererErrorObservation[] = [];
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
 
       const runtimeErr = errors.find((e) => e.code === 'webgpu-runtime-error');
       expect(runtimeErr).toBeDefined();
       expect(runtimeErr?.detail).toBeDefined();
-      expect(runtimeErr?.detail?.error).toBeDefined();
-      expect(typeof runtimeErr?.detail?.error?.message).toBe('string');
-      expect(runtimeErr?.detail?.error?.message).toContain('writeBuffer');
+      const runtimeDetail = runtimeErr?.detail as
+        | { error?: { code: string; message: string } }
+        | undefined;
+      expect(runtimeDetail?.error).toBeDefined();
+      expect(typeof runtimeDetail?.error?.message).toBe('string');
+      expect(runtimeDetail?.error?.message).toContain('writeBuffer');
     });
   });
 
@@ -1019,11 +992,10 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const { setTransparentSortConfig, TRANSPARENT_SORT_MODE_DISTANCE } = await import(
-        '@forgeax/engine-render/internal'
+        '../../../render/src/systems/transparent-sort-config'
       );
       const { RenderQueue } = await import('@forgeax/engine-types');
 
@@ -1115,12 +1087,8 @@ function canonicalMaterialParamSchema(identifier: string): string {
       expect(cfgRes.ok).toBe(true);
 
       const errors: { code: string }[] = [];
-      renderer.onError((e) => errors.push(e));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
 
       expect(errors).toHaveLength(0);
       // All 3 transparent entities are drawn.
@@ -1169,11 +1137,10 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const { setTransparentSortConfig, TRANSPARENT_SORT_MODE_DISTANCE } = await import(
-        '@forgeax/engine-render/internal'
+        '../../../render/src/systems/transparent-sort-config'
       );
 
       // Register a MaterialAsset with Geometry-queue pass.
@@ -1241,12 +1208,8 @@ function canonicalMaterialParamSchema(identifier: string): string {
       expect(cfgRes.ok).toBe(true);
 
       const errors: { code: string }[] = [];
-      renderer.onError((e) => errors.push(e));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
 
       expect(errors).toHaveLength(0);
       // Both opaque entities are drawn (structural).
@@ -1266,7 +1229,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
       const { RenderQueue } = await import('@forgeax/engine-types');
@@ -1330,12 +1292,8 @@ function canonicalMaterialParamSchema(identifier: string): string {
       );
 
       const errors: { code: string }[] = [];
-      renderer.onError((e) => errors.push(e));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
 
       expect(errors).toHaveLength(0);
       expect(log.drawIndexedCount).toBe(1);
@@ -1356,7 +1314,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
         {},
         { shaderManifestUrl: buildManifestDataUrl() },
       );
-      await renderer.ready;
       const { World } = await importEcs();
       const C = await importComponents();
 
@@ -1396,16 +1353,14 @@ function canonicalMaterialParamSchema(identifier: string): string {
       );
 
       const errors: { code: string }[] = [];
-      renderer.onError((e) => errors.push(e));
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+      subscribeRendererErrors(renderer, (e) => errors.push(e));
+      drawPublished(renderer, world as WorldType);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      Object.assign(log, makeLog());
+      drawPublished(renderer, world as WorldType);
 
       expect(errors).toHaveLength(0);
-      // Shadow and main passes are both allowed to visit the renderable.
-      expect(log.drawIndexedCount).toBeGreaterThanOrEqual(1);
+      expect(log.drawIndexedCount).toBe(1);
 
       // Without stencilReference, the draw loop should call
       // setStencilReference(0) (harmless WebGPU default) or not call it at
@@ -1550,7 +1505,7 @@ describe('RenderSystem Skylight record phase (AC-11)', () => {
     // brdfLutBakeCount === 1 after the first frame that has Skylight.
     //
     // When t26 lands:
-    //   const cache = getOrCreateIblCache(device);
+    //   const cache = getOrCreateIblCache(deviceScope);
     //   expect(cache.irradianceBakeCount).toBe(1);
     //   expect(cache.prefilterBakeCount).toBe(1);
     //   expect(cache.brdfLutBakeCount).toBe(1);
@@ -1576,3 +1531,150 @@ describe('RenderSystem Skylight extract + record phase contract (plan-strategy D
     expect(noSeparateSystem).toBe(true);
   });
 });
+
+// ─── from render-system-stride.test.ts ───
+{
+  // w14 - RenderSystem extract entry stride defensive test (M3, AC-06).
+  //
+  // Locks the AC-06 invariant: when an entity carries an `Instances` component
+  // whose `transforms` array<f32> snapshot has a length that is NOT a multiple
+  // of 16, the RenderSystem extract stage MUST emit a structured `EcsError`
+  // with `code: 'instance-transforms-stride-mismatch'` BEFORE the GPU upload
+  // path is reached. The error carries a discriminated `.detail` per
+  // `EcsErrorDetail`:
+  //
+  //   detail = { actualLength: number, expectedStride: 16 }
+  //
+  // Coverage matrix:
+  //   (a) length === 16  -> pass; no error fires; renderable lands.
+  //   (b) length === 32  -> pass; no error fires; renderable lands.
+  //   (c) length === 15  -> fail; structured error fires with detail; no
+  //                         renderable lands.
+  //   (d) length === 17  -> fail; structured error fires with detail; no
+  //                         renderable lands.
+  //
+  // The defensive lives in `packages/runtime/src/render-system-extract.ts`
+  // inside the `Instances` archetype loop, immediately after the
+  // `world.get(entity, Instances)` snapshot is extracted but BEFORE any
+  // per-element copy / GPU upload. Violation routes through Layer-3
+  // `World._errorHandler` (set via `world.setErrorHandler`); the renderable
+  // MUST NOT be pushed (fail-fast halts the per-entity branch).
+
+  interface CollectedError {
+    readonly code: string;
+    readonly detail: unknown;
+  }
+
+  function makeIdentityTransform(): {
+    pos: number[];
+    quat: number[];
+    scale: number[];
+  } {
+    return { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] };
+  }
+
+  function makeWorld(): { world: World; collected: CollectedError[] } {
+    const collected: CollectedError[] = [];
+    const world = new World();
+    vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => {
+      const e = args[args.length - 1] as { code?: string; detail?: unknown };
+      if (e.code !== undefined) collected.push({ code: e.code, detail: e.detail });
+    });
+    // Camera + light so extractFrame's pre-loop short-circuit does not skip
+    // the Instances archetype walk.
+    world
+      .spawn({
+        component: Camera,
+        data: {
+          fov: 1.0,
+          aspect: 1.0,
+          near: 0.1,
+          far: 100.0,
+          projection: 0,
+          left: -1,
+          right: 1,
+          bottom: -1,
+          top: 1,
+        },
+      })
+      .unwrap();
+    world
+      .spawn({
+        component: DirectionalLight,
+        data: {
+          direction: [0, -1, 0],
+          color: [1, 1, 1],
+          intensity: 1,
+        },
+      })
+      .unwrap();
+    return { world, collected };
+  }
+
+  function spawnInstancedEntity(world: World, transforms: Float32Array): void {
+    world
+      .spawn(
+        { component: Transform, data: makeIdentityTransform() },
+        {
+          component: MeshFilter,
+          data: { assetHandle: HANDLE_CUBE },
+        },
+        {
+          component: MeshRenderer,
+          data: {} as never,
+        },
+        { component: Instances, data: { transforms } },
+      )
+      .unwrap();
+  }
+
+  describe('render-system-extract stride defensive (w14, AC-06)', () => {
+    it('(a) length === 16: no error; renderable lands', () => {
+      const { world, collected } = makeWorld();
+      const transforms = new Float32Array(16);
+      spawnInstancedEntity(world, transforms);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(collected.filter((c) => c.code === 'instance-transforms-stride-mismatch').length).toBe(
+        0,
+      );
+      expect(frame.renderables.length).toBe(1);
+    });
+
+    it('(b) length === 32: no error; renderable lands', () => {
+      const { world, collected } = makeWorld();
+      const transforms = new Float32Array(32);
+      spawnInstancedEntity(world, transforms);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      expect(collected.filter((c) => c.code === 'instance-transforms-stride-mismatch').length).toBe(
+        0,
+      );
+      expect(frame.renderables.length).toBe(1);
+    });
+
+    it('(c) length === 15: structured error fires; detail.actualLength === 15; expectedStride === 16; no renderable', () => {
+      const { world, collected } = makeWorld();
+      const transforms = new Float32Array(15);
+      spawnInstancedEntity(world, transforms);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      const stride = collected.filter((c) => c.code === 'instance-transforms-stride-mismatch');
+      expect(stride.length).toBe(1);
+      const detail = stride[0]?.detail as { actualLength: number; expectedStride: 16 };
+      expect(detail.actualLength).toBe(15);
+      expect(detail.expectedStride).toBe(16);
+      expect(frame.renderables.length).toBe(0);
+    });
+
+    it('(d) length === 17: structured error fires; detail.actualLength === 17; expectedStride === 16; no renderable', () => {
+      const { world, collected } = makeWorld();
+      const transforms = new Float32Array(17);
+      spawnInstancedEntity(world, transforms);
+      const frame = extractFrame(world, prepareExtractContext(world));
+      const stride = collected.filter((c) => c.code === 'instance-transforms-stride-mismatch');
+      expect(stride.length).toBe(1);
+      const detail = stride[0]?.detail as { actualLength: number; expectedStride: 16 };
+      expect(detail.actualLength).toBe(17);
+      expect(detail.expectedStride).toBe(16);
+      expect(frame.renderables.length).toBe(0);
+    });
+  });
+}