@forgeax/engine-runtime 0.1.2

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

@@ -0,0 +1,1578 @@
+// Consolidated by feat-20260608-ci-time-cut M5 w13/w14: merges
+//   - render-system.test.ts
+//   - render-system-skylight.test.ts
+//   - render-system-stride.test.ts
+// Each original file body sits in its own block-scope so helper names
+// cannot collide; describe() inside still registers globally with vitest.
+
+import type { World as WorldType } 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';
+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);
+  }
+  return '[]';
+}
+
+// ─── from render-system.test.ts ───
+{
+  // render-system.test - RenderSystem three-stage Extract / Prepare / Record +
+  // 4-case error tier + asset-not-registered + internal exception + AC-09
+  // (not in world.systems schedule) + mat4 worldFromLocal baseline (TDD red,
+  // w14).
+  //
+  // Locks D-S2 (three stages, engine internal phase) + D-S4..D-S8 (error
+  // fan-out tier table; charter proposition 4 explicit failure with
+  // proposition 4 softening points at D-Q7 case A + case C).
+  //
+  // Charter proposition 4 mapping:
+  //   case A (entity missing Transform / MeshRenderer): default
+  //          values used; no onError 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).
+  //   case D (world has N>1 Camera / Light): fires
+  //          'render-system-multi-camera' / 'render-system-multi-light' +
+  //          uses first archetype hit.
+  //   asset-not-registered: fires 'asset-not-registered' + entity skipped
+  //          + .detail = { assetHandle: number } (D-S6 + F-3 contract).
+  //   internal exception: fires 'webgpu-runtime-error' + frame skipped +
+  //          .detail = { error: string } (D-S8 + F-3 contract).
+
+  const ENGINE = '../createRenderer';
+
+  // ─── Mock helpers (mirrors renderer-ready.test.ts) ──────────────────────────
+
+  interface MockGL2Context {
+    __mockTag: 'webgl2';
+    getExtension: () => null;
+    getParameter: () => number;
+    isContextLost: () => boolean;
+  }
+
+  function makeMockGL2(): MockGL2Context {
+    return {
+      __mockTag: 'webgl2',
+      getExtension: () => null,
+      getParameter: () => 1,
+      isContextLost: () => false,
+    };
+  }
+
+  interface CanvasOptions {
+    webgl2: 'context' | 'null';
+    webgpu?: 'context' | 'null';
+  }
+
+  function makeMockCanvas(opts: CanvasOptions): HTMLCanvasElement {
+    const canvas = {
+      width: 800,
+      height: 600,
+      getContext(kind: string): unknown {
+        if (kind === 'webgl2') {
+          return opts.webgl2 === 'context' ? makeMockGL2() : null;
+        }
+        if (kind === 'webgpu') {
+          if (opts.webgpu === 'context') {
+            return {
+              __mockTag: 'webgpu-canvas-context',
+              configure: () => undefined,
+              unconfigure: () => undefined,
+              getCurrentTexture: () => ({ createView: () => ({}) }),
+            };
+          }
+          return null;
+        }
+        return null;
+      },
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+    };
+    return canvas as Partial<HTMLCanvasElement> as HTMLCanvasElement;
+  }
+
+  interface DeviceCallLog {
+    encoderFinishCount: number;
+    drawIndexedCount: number;
+    setBindGroupCount: number;
+    beginRenderPassCount: number;
+    setPipelineCount: number;
+    queueSubmitCount: number;
+    writeBufferCount: number;
+    /**
+     * w8-B (TDD red): sequence of stencil reference values passed to
+     * `setStencilReference` on the render pass encoder. Empty until
+     * setStencilReference is wired into the draw loop.
+     */
+    setStencilReferenceValues: number[];
+    /**
+     * w8-A (TDD red): per-draw metadata captured during drawIndexed calls.
+     * Each entry records the mesh uniform buffer offset set via setBindGroup
+     * at group=2, which identifies the draw slot within the frame.
+     * Offset = loopIndex * MESH_PER_ENTITY_STRIDE (256 bytes).
+     *
+     * To verify distance-sort correctness, the test also needs per-draw
+     * entity identity. The mock captures the renderable index via the
+     * per-entity material upload's dynamic offset at group=1, which carries
+     * renderableIndex * MATERIAL_PER_ENTITY_STRIDE.
+     */
+    drawCallOffsets: number[];
+  }
+
+  function makeMockGPUDevice(log: DeviceCallLog): { device: unknown } {
+    const lost = new Promise<unknown>(() => undefined);
+    // w8-A: track the last mesh uniform buffer offset (group=2) so we can
+    // attribute each drawIndexed call to a specific renderable within the frame.
+    let lastMeshBufferOffset = -1;
+    const device = {
+      __mockTag: 'gpu-device',
+      lost,
+      features: new Set(),
+      limits: {},
+      queue: {
+        submit: () => {
+          log.queueSubmitCount++;
+        },
+        writeBuffer: () => {
+          log.writeBufferCount++;
+        },
+        writeTexture: () => undefined,
+      },
+      createShaderModule: () => ({ getCompilationInfo: async () => ({ messages: [] }) }),
+      createBindGroupLayout: () => ({}),
+      createPipelineLayout: () => ({}),
+      createRenderPipeline: () => ({}),
+      createBindGroup: () => ({}),
+      createBuffer: () => ({
+        getMappedRange: () => new ArrayBuffer(64),
+        unmap: () => undefined,
+      }),
+      createCommandEncoder: () => ({
+        beginRenderPass: () => {
+          log.beginRenderPassCount++;
+          lastMeshBufferOffset = -1;
+          return {
+            setPipeline: () => {
+              log.setPipelineCount++;
+            },
+            setViewport: () => undefined,
+            setVertexBuffer: () => undefined,
+            setIndexBuffer: () => undefined,
+            setBindGroup: (groupIndex: number, _bg: unknown, dynamicOffsets?: number[]) => {
+              log.setBindGroupCount++;
+              // w8-A: capture mesh uniform buffer offset at group=2.
+              // The per-entity buffer is bound with dynamicOffset = renderableIndex * 256.
+              if (groupIndex === 2 && dynamicOffsets !== undefined && dynamicOffsets.length > 0) {
+                lastMeshBufferOffset = dynamicOffsets[0] ?? -1;
+              }
+            },
+            draw: () => undefined,
+            drawIndexed: () => {
+              log.drawIndexedCount++;
+              if (lastMeshBufferOffset >= 0) {
+                log.drawCallOffsets.push(lastMeshBufferOffset);
+              }
+            },
+            /**
+             * w8-B (TDD red): setStencilReference mock — captures the
+             * reference value so the test can assert it was called with
+             * the correct per-pass value.
+             */
+            setStencilReference: (ref: number) => {
+              log.setStencilReferenceValues.push(ref);
+            },
+            end: () => undefined,
+          };
+        },
+        finish: () => {
+          log.encoderFinishCount++;
+          return {};
+        },
+      }),
+      createTexture: () => ({ createView: () => ({}) }),
+      createSampler: () => ({}),
+      destroy: () => undefined,
+    };
+    return { device };
+  }
+
+  function makeMockGPU(deviceObj: unknown): unknown {
+    return {
+      requestAdapter: async () => ({
+        requestDevice: async () => deviceObj,
+      }),
+      getPreferredCanvasFormat: () => 'bgra8unorm',
+    };
+  }
+
+  const baseNavigator: Navigator = {
+    userAgent: 'mock-engine-test',
+  } as Partial<Navigator> as Navigator;
+
+  function buildManifestDataUrl(): string {
+    // feat-20260518-pbr-direct-lighting-mvp M5 / w22.9: createRenderer's
+    // post-fallback path requires both pbr (`f_schlick(` marker) + unlit
+    // entries; seed two minimal stubs (mock device's createShaderModule does
+    // not parse WGSL).
+    //
+    // 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.
+    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,
+      ),
+    });
+    const manifest = {
+      schemaVersion: '1.0.0',
+      entries: [
+        { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },
+        { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+        {
+          hash: 'tonemap0',
+          wgsl: '/* tonemap stub - struct TonemapParams { exposure: f32 }; */',
+          glsl: '',
+          bindings: '',
+        },
+      ],
+      materialShaders: [
+        materialShaderStub('forgeax::default-standard-pbr'),
+        materialShaderStub('forgeax::default-unlit'),
+      ],
+    };
+    return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+  }
+
+  function makeLog(): DeviceCallLog {
+    return {
+      encoderFinishCount: 0,
+      drawIndexedCount: 0,
+      setBindGroupCount: 0,
+      beginRenderPassCount: 0,
+      setPipelineCount: 0,
+      queueSubmitCount: 0,
+      writeBufferCount: 0,
+      setStencilReferenceValues: [],
+      drawCallOffsets: [],
+    };
+  }
+
+  beforeEach(() => {
+    vi.stubGlobal('navigator', { ...baseNavigator });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  // 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 };
+      };
+    }>;
+  }> {
+    return (await import(ENGINE)) as never;
+  }
+
+  async function importEcs(): Promise<{
+    World: new () => {
+      spawn: (...componentDatas: unknown[]) => unknown;
+      update: () => void;
+      inspect: () => { systemCount: number };
+      allocSharedRef: (target: string, payload: unknown) => Handle<string, 'shared'>;
+    };
+  }> {
+    const { World: BaseWorld } = await import('@forgeax/engine-ecs');
+    return { World: withPrimitiveMeshes(BaseWorld) } as never;
+  }
+
+  async function importComponents(): Promise<{
+    Transform: unknown;
+    MeshFilter: unknown;
+    MeshRenderer: unknown;
+    Camera: unknown;
+    DirectionalLight: unknown;
+    // w22 - HANDLE_CUBE / HANDLE_TRIANGLE narrow from plain `number` to
+    // `Handle<MeshAsset>` (AC-09 / D-P1). The brand is a phantom over `number`
+    // at runtime; test code typings reflect the narrow so `tsc -b` catches any
+    // cross-brand assignment mistakes (e.g. passing HANDLE_CUBE where a
+    // Handle<TextureAsset> is expected).
+    HANDLE_CUBE: Handle<'MeshAsset', 'shared'>;
+    HANDLE_TRIANGLE: Handle<'MeshAsset', 'shared'>;
+  }> {
+    return {
+      ...(await import('@forgeax/engine-render/internal')),
+      ...(await import('@forgeax/engine-scene')),
+      HANDLE_CUBE: TEST_CUBE_HANDLE,
+      HANDLE_TRIANGLE: TEST_TRIANGLE_HANDLE,
+    } 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 };
+      };
+    }>;
+    log: DeviceCallLog;
+  }
+
+  async function setupWebGPU(): Promise<TestSetup> {
+    const log = makeLog();
+    const { device } = makeMockGPUDevice(log);
+    vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
+    const engine = await importEngine();
+    return { createRenderer: engine.createRenderer, log };
+  }
+
+  // ─── Tests ──────────────────────────────────────────────────────────────────
+
+  describe('RenderSystem three-stage Extract / Prepare / Record (D-S2)', () => {
+    it('records drawIndexed exactly once per renderable entity through encoder + queue.submit', async () => {
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { shaderManifestUrl: buildManifestDataUrl() },
+      );
+      await renderer.ready;
+      const { World } = await importEcs();
+      const C = await importComponents();
+      const world = new World();
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      // spawn DirectionalLight with merged shadow fields.
+      world.spawn({
+        component: C.DirectionalLight,
+        data: {
+          direction: [0, -1, 0],
+          color: [1, 1, 1],
+          intensity: 1,
+          mapSize: 1024,
+        },
+      });
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        { component: C.MeshRenderer, data: defaultMaterial() },
+        { component: C.Transform, data: identityTransform() },
+      );
+
+      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 });
+
+      // 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
+      // 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();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { 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);
+  });
+
+  describe('RenderSystem error tier table (D-S4..D-S8)', () => {
+    it('case A: entity missing Transform / MeshRenderer uses defaults; does NOT fire onError', async () => {
+      const { createRenderer } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { shaderManifestUrl: buildManifestDataUrl() },
+      );
+      await renderer.ready;
+      const { World } = await importEcs();
+      const C = await importComponents();
+      const world = new World();
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      // Renderable entity with ONLY MeshFilter (no Transform, no
+      // MeshRenderer) - default values are used; charter proposition 4
+      // softening per D-Q7 case A.
+      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 });
+      expect(errors).toHaveLength(0);
+    });
+
+    it('case B: world has 0 Camera entity fires render-system-no-camera + still emits clear pass', async () => {
+      // feat-20260608-create-app-param-surface-trim / M1 / AC-05 + D-8:
+      // the zero-Camera path no longer skips the frame. After firing the
+      // `'render-system-no-camera'` diagnostic, render-system-record
+      // synthesizes a fallback CameraSnapshot carrying
+      // `ZERO_CAMERA_CLEAR_FALLBACK = [0, 0, 0, 1]` and runs the
+      // clear-pass-only branch (geometry submission is still skipped:
+      // synthetic camera + identity world means no MeshRenderer renders).
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { shaderManifestUrl: buildManifestDataUrl() },
+      );
+      await renderer.ready;
+      const { World } = await importEcs();
+      const C = await importComponents();
+      const world = new World();
+      // No camera; one renderable entity.
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        { component: C.MeshRenderer, data: defaultMaterial() },
+        { component: C.Transform, data: identityTransform() },
+      );
+
+      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 });
+
+      expect(errors.some((e) => e.code === 'render-system-no-camera')).toBe(true);
+      // Clear pass executed under the synthetic camera path; the frame is
+      // NOT skipped. The synthetic camera has identity world + perspective
+      // (fov=PI/4, aspect=1) so renderable entities at origin may sample
+      // 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
+      // (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 () => {
+      // 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,
+      // mirrors Case C 0-Light D-Q7 softening) by encoding + submitting a
+      // clear-pass-only render pass: beginRenderPass(loadOp:'clear') -> end
+      // -> finish -> queue.submit, with no setPipeline / setBindGroup /
+      // drawIndexed in between.
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { shaderManifestUrl: buildManifestDataUrl() },
+      );
+      await renderer.ready;
+      const { World } = await importEcs();
+      const C = await importComponents();
+      const world = new World();
+      // Single Camera entity, zero MeshFilter / MeshRenderer entities.
+      // feat-20260608 / M1: clear color now lives on the Camera entity.
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            clearColor: [0.2, 0.3, 0.3, 1.0],
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+
+      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 });
+
+      // 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.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 () => {
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { shaderManifestUrl: buildManifestDataUrl() },
+      );
+      await renderer.ready;
+      const { World } = await importEcs();
+      const C = await importComponents();
+      const world = new World();
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        { component: C.MeshRenderer, data: defaultMaterial() },
+        { component: C.Transform, data: identityTransform() },
+      );
+      // 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 });
+
+      expect(errors).toHaveLength(0);
+      // Shadow and main passes are both allowed to visit the renderable.
+      expect(log.drawIndexedCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it('case D: world has N>1 Camera fires render-system-multi-camera + uses first hit', async () => {
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { shaderManifestUrl: buildManifestDataUrl() },
+      );
+      await renderer.ready;
+      const { World } = await importEcs();
+      const C = await importComponents();
+      const world = new World();
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 3,
+            aspect: 4 / 3,
+            near: 1,
+            far: 50,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: identityTransform() },
+      );
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        { component: C.MeshRenderer, data: defaultMaterial() },
+        { component: C.Transform, data: identityTransform() },
+      );
+
+      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 });
+
+      expect(errors.some((e) => e.code === 'render-system-multi-camera')).toBe(true);
+      // First archetype hit still rendered.
+      expect(log.drawIndexedCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it('case D: world has N>1 DirectionalLight fires warn-once console.warn + uses first hit', async () => {
+      // feat-20260608-rhi-hdr-renderable-caps-and-warn-once m3-1: multi-light
+      // overrun was migrated from per-frame errorRegistry.fire to warn-once
+      // console.warn (aligned with frameState.warnedShadowDisabled idiom).
+      // Test asserts the new contract: a `[forgeax] render-system-multi-light
+      // directional:` line appears once on console.warn during the overrun
+      // frame, and the renderer still picks the first archetype hit.
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { shaderManifestUrl: buildManifestDataUrl() },
+      );
+      await renderer.ready;
+      const { World } = await importEcs();
+      const C = await importComponents();
+      const world = new World();
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      world.spawn({ component: C.DirectionalLight, data: directionalLight() });
+      world.spawn({
+        component: C.DirectionalLight,
+        data: { ...directionalLight(), intensity: 2 },
+      });
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        { component: C.MeshRenderer, data: defaultMaterial() },
+        { component: C.Transform, data: identityTransform() },
+      );
+
+      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 });
+
+      const multiLightCalls = warnSpy.mock.calls.filter(
+        (c) =>
+          typeof c[0] === 'string' &&
+          c[0].startsWith('[forgeax] render-system-multi-light directional:'),
+      );
+      expect(multiLightCalls.length).toBe(1);
+      expect(log.drawIndexedCount).toBeGreaterThanOrEqual(1);
+      warnSpy.mockRestore();
+    });
+  });
+
+  describe('RenderSystem asset-not-registered + internal exception (.detail F-3 contract)', () => {
+    it('asset-not-registered fires onError with .detail = { assetHandle } and skips entity', async () => {
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { shaderManifestUrl: buildManifestDataUrl() },
+      );
+      await renderer.ready;
+      const { World } = await importEcs();
+      const C = await importComponents();
+      const world = new World();
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      const BAD_HANDLE = 99999;
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: BAD_HANDLE } },
+        { component: C.MeshRenderer, data: defaultMaterial() },
+        { 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 assetErr = errors.find((e) => e.code === 'asset-not-registered');
+      expect(assetErr).toBeDefined();
+      expect(assetErr?.detail).toBeDefined();
+      expect(assetErr?.detail?.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
+      // 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.
+      expect(log.beginRenderPassCount).toBe(11);
+      expect(log.queueSubmitCount).toBe(8); // shadow fallback + 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.
+      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);
+      };
+      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 { World } = await importEcs();
+      const C = await importComponents();
+      const world = new World();
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        { component: C.MeshRenderer, data: defaultMaterial() },
+        { 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 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');
+    });
+  });
+
+  describe('RenderSystem mat4 worldFromLocal baseline (AC-02)', () => {
+    it('uses @forgeax/engine-math mat4 / vec3 / quat to compose worldFromLocal (1e-6 tolerance)', async () => {
+      // Importing @forgeax/engine-math here ensures the contract surface is
+      // available to the renderer-system path (charter proposition 5: do not
+      // reinvent math). The actual composition is tested implicitly through
+      // recording assertions above (when impl lands the recorded mat4
+      // payload matches mat4.compose(out, pos, rot, scale)).
+      const math = (await import('@forgeax/engine-math')) as { mat4: { compose: unknown } };
+      expect(typeof math.mat4.compose).toBe('function');
+
+      // Source-level guarantee: render-system.ts imports from @forgeax/engine-math
+      // (charter proposition 5 single math source).
+      const fsId = 'node:fs';
+      const pathId = 'node:path';
+      const urlId = 'node:url';
+      const fs = (await import(/* @vite-ignore */ fsId)) as {
+        readFileSync: (p: string, enc: string) => string;
+      };
+      const path = (await import(/* @vite-ignore */ pathId)) as {
+        resolve: (...parts: string[]) => string;
+        dirname: (p: string) => string;
+      };
+      const url = (await import(/* @vite-ignore */ urlId)) as {
+        fileURLToPath: (u: string) => string;
+      };
+      const here = url.fileURLToPath(import.meta.url);
+      const renderSystemSrc = path.resolve(
+        path.dirname(here),
+        '..',
+        '..',
+        '..',
+        'render',
+        'src',
+        'render-system.ts',
+      );
+      const text = fs.readFileSync(renderSystemSrc, 'utf8');
+      expect(text).toMatch(/@forgeax\/engine-math/);
+    });
+  });
+
+  // ─── Sample data helpers ────────────────────────────────────────────────────
+
+  function identityTransform(): {
+    pos: number[];
+    quat: number[];
+    scale: number[];
+  } {
+    return { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] };
+  }
+
+  function cameraTransform(): ReturnType<typeof identityTransform> {
+    return { pos: [0, 0, 3], quat: [0, 0, 0, 1], scale: [1, 1, 1] };
+  }
+
+  function defaultMaterial(): Record<string, never> {
+    // feat-20260517: MeshRenderer.material is optional; passing {} triggers the
+    // silent default-material fallback (mid-grey unlit) per D-Q7 case B.
+    return {};
+  }
+
+  function directionalLight(): {
+    direction: readonly number[];
+    color: readonly number[];
+    intensity: number;
+  } {
+    return {
+      direction: [-0.5, -1, -0.3],
+      color: [1, 1, 1],
+      intensity: 1,
+    };
+  }
+
+  // ─── w8: record distance re-sort + setStencilReference (TDD red phase) ───────
+
+  describe('w8-A: record stage distance re-sort (mode=3) on Transparent queue segment', () => {
+    it.skip('draws Transparent-queue entities back-to-front (far first) when mode=3 is configured', async () => {
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { 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'
+      );
+      const { RenderQueue } = await import('@forgeax/engine-types');
+
+      // Register a MaterialAsset with a Transparent-queue pass so the
+      // extract stage produces dispatch entries tagged with
+      // queue=RenderQueue.Transparent for the record-stage distance sort.
+      const matAsset = {
+        kind: 'material',
+        passes: [
+          {
+            name: 'transparent-pass',
+            program: { module: 'forgeax::default-standard-pbr' },
+            renderState: { queue: RenderQueue.Transparent, tags: { LightMode: 'Forward' } },
+          },
+        ],
+        values: { baseColor: [1, 1, 1, 1] },
+      };
+      const world = new World();
+      const matHandle = world.allocSharedRef('MaterialAsset', matAsset) as unknown;
+
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      world.spawn({
+        component: C.DirectionalLight,
+        data: {
+          direction: [0, -1, 0],
+          color: [1, 1, 1],
+          intensity: 1,
+          mapSize: 1024,
+        },
+      });
+
+      // Spawn 3 transparent entities at near, mid, far distances from camera at z=3.
+      // Camera is at (0, 0, 3). Entity positions:
+      //   near  (0, 0,  0) — distance = 3
+      //   mid   (0, 0, -2) — distance = 5
+      //   far   (0, 0, -7) — distance = 10
+      // Spawn in near-first order so dispatch insertion order is near, mid, far.
+      // Correct back-to-front draw order should be far, mid, near.
+      const nearTx = { ...identityTransform(), pos: [0, 0, 0] };
+      const midTx = { ...identityTransform(), pos: [0, 0, -2] };
+      const farTx = { ...identityTransform(), pos: [0, 0, -7] };
+
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        {
+          component: C.MeshRenderer,
+          data: { materials: [matHandle] },
+        },
+        { component: C.Transform, data: nearTx },
+      );
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        {
+          component: C.MeshRenderer,
+          data: { materials: [matHandle] },
+        },
+        { component: C.Transform, data: midTx },
+      );
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        {
+          component: C.MeshRenderer,
+          data: { materials: [matHandle] },
+        },
+        { component: C.Transform, data: farTx },
+      );
+
+      // Enable distance sort mode.
+      const cfgRes = setTransparentSortConfig(world as never, {
+        mode: TRANSPARENT_SORT_MODE_DISTANCE,
+        yzAlpha: 1,
+      });
+      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 });
+
+      expect(errors).toHaveLength(0);
+      // All 3 transparent entities are drawn.
+      expect(log.drawIndexedCount).toBe(3);
+      // drawCallOffsets are captured per drawIndexed call; each offset is
+      // renderableIndex * 256. The order of offsets reflects the draw order.
+      // With mode=3, the correct back-to-front order should be far (offset
+      // corresponding to far entity), mid, near. Since the entities are
+      // spawned near-first and the record stage does NOT yet do distance
+      // re-sort, the draw order will be the insertion order (near, mid, far)
+      // — this assertion FAILS, making the test RED.
+      expect(log.drawCallOffsets.length).toBe(3);
+      // After distance sort (mode=3, back-to-front), the far entity
+      // (renderableIndex=2) is drawn first, followed by mid (index=1),
+      // then near (index=0). The per-draw offset = loop index * 256 and
+      // does not directly encode renderableIndex — it reflects draw
+      // order. With correct distance sort, all three entities are drawn
+      // and the offsets are [0, 256, 512] (ascending, far-first
+      // rendered at slot 0, near last at slot 2). Without distance sort,
+      // the insertion order (near-first) would produce the same sequence,
+      // so the structural assertion below confirms distance sort is
+      // active: the mesh-storage-buffer slots should be in ascending
+      // order with all three present.
+      const offsets = log.drawCallOffsets;
+      expect(offsets.length).toBe(3);
+      expect(offsets[0]).toBe(0);
+      expect(offsets[1]).toBe(256);
+      expect(offsets[2]).toBe(512);
+      // Regression: verify mode=3 actually re-ordered the entities
+      // (far-first -> near-last). Without the record wiring, this
+      // assertion FAILS because draw order equals spawn order (near first).
+      // Since all entities have the same mesh and material, the draw
+      // count stays at 3, but the entity drawn at slot 0 (offset=0)
+      // should be the far one, not the near one. We verify this by
+      // confirming offsets are exactly [0, 256, 512] (no duplicates,
+      // no gaps, which would indicate missing/extra draws).
+    });
+
+    it.skip('does NOT re-sort non-Transparent queue entities when mode=3', async () => {
+      // Verify that mode=3 only affects Transparent (= 3000) entities.
+      // Opaque (Geometry=2000) entities retain their queue-determined order.
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { 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'
+      );
+
+      // Register a MaterialAsset with Geometry-queue pass.
+      const matAsset = {
+        kind: 'material',
+        passes: [
+          {
+            name: 'opaque-pass',
+            program: { module: 'forgeax::default-standard-pbr' },
+            renderState: { queue: 2000, tags: { LightMode: 'Forward' } },
+          },
+        ],
+        values: { baseColor: [1, 1, 1, 1] },
+      };
+      const world = new World();
+      const matHandle = world.allocSharedRef('MaterialAsset', matAsset) as unknown;
+
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      world.spawn({
+        component: C.DirectionalLight,
+        data: {
+          direction: [0, -1, 0],
+          color: [1, 1, 1],
+          intensity: 1,
+          mapSize: 1024,
+        },
+      });
+
+      // Spawn 2 opaque (Geometry=2000) entities at different distances.
+      // The record stage should NOT re-sort Geometry-queue entities.
+      const nearOpaque = { ...identityTransform(), pos: [0, 0, 0] };
+      const farOpaque = { ...identityTransform(), pos: [0, 0, -10] };
+
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        { component: C.MeshRenderer, data: { materials: [matHandle] } },
+        { component: C.Transform, data: nearOpaque },
+      );
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        { component: C.MeshRenderer, data: { materials: [matHandle] } },
+        { component: C.Transform, data: farOpaque },
+      );
+
+      const cfgRes = setTransparentSortConfig(world as never, {
+        mode: TRANSPARENT_SORT_MODE_DISTANCE,
+        yzAlpha: 1,
+      });
+      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 });
+
+      expect(errors).toHaveLength(0);
+      // Both opaque entities are drawn (structural).
+      expect(log.drawIndexedCount).toBe(2);
+      // Opaque entities are NOT re-sorted by distance; they retain dispatch
+      // insertion order regardless of mode=3.
+      expect(log.drawCallOffsets.length).toBe(2);
+    });
+  });
+
+  describe('w8-B: setStencilReference call in draw loop', () => {
+    it.skip('calls setStencilReference with per-pass stencilReference value when dispatch entry carries it', async () => {
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { shaderManifestUrl: buildManifestDataUrl() },
+      );
+      await renderer.ready;
+      const { World } = await importEcs();
+      const C = await importComponents();
+      const { RenderQueue } = await import('@forgeax/engine-types');
+
+      // Register a MaterialAsset with stencilReference=1 on its pass so
+      // the extract stage folds it into the DispatchEntry for the record
+      // stage to consume via setStencilReference.
+      const matAsset = {
+        kind: 'material',
+        passes: [
+          {
+            name: 'stencil-pass',
+            program: { module: 'forgeax::default-standard-pbr' },
+            renderState: {
+              tags: { LightMode: 'Forward' },
+              stencilReference: 1,
+              queue: RenderQueue.Geometry,
+            },
+          },
+        ],
+        values: { baseColor: [1, 1, 1, 1] },
+      };
+      const world = new World();
+      const matHandle = world.allocSharedRef('MaterialAsset', matAsset) as unknown;
+
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      world.spawn({
+        component: C.DirectionalLight,
+        data: {
+          direction: [0, -1, 0],
+          color: [1, 1, 1],
+          intensity: 1,
+          mapSize: 1024,
+        },
+      });
+
+      // Spawn one entity with a material that carries stencilReference=1.
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        {
+          component: C.MeshRenderer,
+          data: { materials: [matHandle] },
+        },
+        { component: C.Transform, data: identityTransform() },
+      );
+
+      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 });
+
+      expect(errors).toHaveLength(0);
+      expect(log.drawIndexedCount).toBe(1);
+
+      // RED: the record stage does NOT yet call setStencilReference.
+      // When stencilReference=1 is on the dispatch entry, the draw loop
+      // should call pass.setStencilReference(1). Currently this assertion
+      // FAILS because setStencilReference is never called.
+      expect(log.setStencilReferenceValues.length).toBeGreaterThanOrEqual(1);
+      expect(log.setStencilReferenceValues).toContain(1);
+    });
+
+    it('does NOT call setStencilReference for entries without stencilReference (or ref=0 default)', async () => {
+      const { createRenderer, log } = await setupWebGPU();
+      const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
+      const renderer = await createRenderer(
+        canvas,
+        {},
+        { shaderManifestUrl: buildManifestDataUrl() },
+      );
+      await renderer.ready;
+      const { World } = await importEcs();
+      const C = await importComponents();
+
+      const world = new World();
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      world.spawn({
+        component: C.DirectionalLight,
+        data: {
+          direction: [0, -1, 0],
+          color: [1, 1, 1],
+          intensity: 1,
+          mapSize: 1024,
+        },
+      });
+
+      // Spawn entity WITHOUT stencilReference on any pass.
+      world.spawn(
+        { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+        { component: C.MeshRenderer, data: defaultMaterial() },
+        { component: C.Transform, data: identityTransform() },
+      );
+
+      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 });
+
+      expect(errors).toHaveLength(0);
+      // Shadow and main passes are both allowed to visit the renderable.
+      expect(log.drawIndexedCount).toBeGreaterThanOrEqual(1);
+
+      // Without stencilReference, the draw loop should call
+      // setStencilReference(0) (harmless WebGPU default) or not call it at
+      // all. For the TDD red-phase, we assert no non-zero calls.
+      const nonZeroCalls = log.setStencilReferenceValues.filter((v) => v !== 0);
+      expect(nonZeroCalls).toHaveLength(0);
+    });
+  });
+}
+
+// ─── from render-system-skylight.test.ts ───
+// render-system-skylight - feat-20260520-skylight-ibl-cubemap M4 / t24 (TDD red).
+//
+// RenderSystem extract + record phase Skylight integration test.
+// AC-11: Extract queries Skylight component and captures cubemap handle +
+// intensity into frame data. Record lazy-resolves IBL pipeline cache handles
+// (irradiance / prefilter / BRDF LUT) and assembles skylightBindGroup.
+//
+// RED PHASE: Skylight component does not exist yet. These tests encode
+// the expected behavior contract for the RenderSystem extract + record
+// integration. When t25 (Skylight component) + t26 (RenderSystem integration)
+// land, these assertions become live test cases.
+//
+// plan-strategy D-6: Skylight data flows through existing extract->record
+// two-stage pipeline. No independent ECS system.
+//
+// Coverage:
+//   (a) extractFrame queries Skylight component, captures { cubemap, intensity }
+//   (b) recordFrame lazy-resolves IblPipelineCache handles for Skylight bind group
+//   (c) recordFrame binds skylightBindGroup to PBR pipeline when Skylight exists
+//   (d) when no Skylight, PBR pipeline binds identity (default-zero ambient)
+
+describe('RenderSystem Skylight extract phase (AC-11)', () => {
+  it('(a) extractFrame queries Skylight component and captures cubemap handle + intensity', () => {
+    // When extractFrame runs, it should:
+    // 1. Create a query for entities with (Skylight) component
+    // 2. Extract equirect handle (for GPU resource lookup) and intensity
+    // 3. Populate an ExtractedSkylight field in the ExtractedFrame
+    //
+    // The extracted data shape:
+    //   { equirectHandle: Handle<EquirectAsset>, intensity: number }
+    //
+    // When t26 lands, this becomes:
+    //   const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    //   expect(frame.skylight).toBeDefined();
+    //   expect(frame.skylight?.intensity).toBe(1.0);
+    const extractCapturesSkylight = true;
+    expect(extractCapturesSkylight).toBe(true);
+  });
+
+  it('(b) extractFrame returns undefined skylight when no Skylight entity exists', () => {
+    // When no Skylight component exists in the world, extractFrame should
+    // return an ExtractedFrame with skylight = undefined.
+    //
+    // When t26 lands:
+    //   const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    //   expect(frame.skylight).toBeUndefined();
+    const noSkylightUndefined = true;
+    expect(noSkylightUndefined).toBe(true);
+  });
+
+  it('(c) extractFrame captures first Skylight only (first archetype hit wins)', () => {
+    // Multiple Skylight entities: first hit wins per existing pattern
+    // (mirrors DirectionalLight first-hit behavior). The multi-Skylight
+    // warn fires in recordFrame separately (t27).
+    //
+    // When t26 lands:
+    //   expect(frame.skylight).toBeDefined();
+    //   // second Skylight is ignored (warn handled by t27)
+    const firstSkylightWins = true;
+    expect(firstSkylightWins).toBe(true);
+  });
+});
+
+describe('RenderSystem Skylight record phase (AC-11)', () => {
+  it('(d) recordFrame lazy-resolves IblPipelineCache handles when Skylight exists', () => {
+    // When recordFrame has a Skylight snapshot, it should lazy-resolve:
+    // - irradianceMap (from cubemap upload path)
+    // - prefilterMap (from cubemap upload path)
+    // - brdfLut (from cubemap upload path / global cache)
+    //
+    // These come from IblPipelineCache which already has counter fields
+    // (irradianceBakeCount / prefilterBakeCount / brdfLutBakeCount).
+    //
+    // When t26 lands:
+    //   // Verify recordFrame doesn't crash with Skylight present
+    //   recordFrame(internals, cameras, lights, renderables, frameState, dispatchCounts);
+    //   // Skylight bind group is assembled from IBL pipeline cache
+    const resolvesIblHandles = true;
+    expect(resolvesIblHandles).toBe(true);
+  });
+
+  it('(e) recordFrame assembles skylightBindGroup when Skylight exists', () => {
+    // When Skylight exists, recordFrame creates a bind group with:
+    // - cubemap texture + sampler (for diffuse irradiance)
+    // - prefilter map texture + sampler
+    // - BRDF LUT texture + sampler
+    // - intensity uniform
+    // This bind group is bound to the PBR pipeline alongside the existing
+    // view / material / mesh / instances bind groups.
+    //
+    // When t26 lands:
+    //   // Verify BindGroup creation with Skylight resources
+    //   expect(log.skylightBindGroupCreated).toBe(true);
+    const assemblesSkylightBindGroup = true;
+    expect(assemblesSkylightBindGroup).toBe(true);
+  });
+
+  it('(f) recordFrame binds identity resources when no Skylight (ambient=0)', () => {
+    // When no Skylight exists, recordFrame should provide identity/default
+    // resources so the shader's ambient term contributes 0. This means:
+    // - irradiance map: black 1x1 texture or equivalent
+    // - prefilter map: black 1x1 texture or equivalent
+    // - BRDF LUT: identity or no-op
+    // - intensity: 0
+    //
+    // pbr.wgsl AC-08: when Skylight is absent, ambient = 0.
+    //
+    // When t26 lands:
+    //   recordFrame(internals, cameras, lights, renderables, frameState, dispatchCounts);
+    //   // No Skylight -> ambient=0 in shader; no extra bind group allocations
+    const identityWhenNoSkylight = true;
+    expect(identityWhenNoSkylight).toBe(true);
+  });
+
+  it('(g) recordFrame binds skylightBindGroup at the correct bind group index', () => {
+    // The skylightBindGroup should be bound at a slot adjacent to the
+    // existing bind groups (view @0, material @1, mesh @2, instances @3).
+    // The exact index is determined by the bind group layout defined in
+    // createRenderer.ts (or wherever pipeline layouts are declared).
+    //
+    // When t26 lands:
+    //   // Verify the correct setBindGroup index for Skylight
+    //   // e.g., pass.setBindGroup(4, skylightBindGroup);
+    const correctBindGroupIndex = true;
+    expect(correctBindGroupIndex).toBe(true);
+  });
+
+  it('(h) iblPrepass counters observable after recordFrame with Skylight', () => {
+    // AC-04/05/06: iblPrepass counter invariants.
+    // irradianceBakeCount === 1, prefilterBakeCount === 1,
+    // brdfLutBakeCount === 1 after the first frame that has Skylight.
+    //
+    // When t26 lands:
+    //   const cache = getOrCreateIblCache(device);
+    //   expect(cache.irradianceBakeCount).toBe(1);
+    //   expect(cache.prefilterBakeCount).toBe(1);
+    //   expect(cache.brdfLutBakeCount).toBe(1);
+    const counterInvariants = true;
+    expect(counterInvariants).toBe(true);
+  });
+});
+
+describe('RenderSystem Skylight extract + record phase contract (plan-strategy D-6)', () => {
+  it('Skylight data flows through existing extract->record pipeline', () => {
+    // Plan-strategy D-6: Skylight component data flows through the existing
+    // extractFrame -> recordFrame two-stage pipeline. No independent ECS system
+    // for Skylight.
+    const usesExistingPipeline = true;
+    expect(usesExistingPipeline).toBe(true);
+  });
+
+  it('Skylight does NOT register a separate ECS system', () => {
+    // Plan-strategy D-6: Skylight component schema is registered (t25) but
+    // there is no SkylightSystem in the ECS schedule. All Skylight processing
+    // happens inside RenderSystem's extract/record phases.
+    const noSeparateSystem = true;
+    expect(noSeparateSystem).toBe(true);
+  });
+});