@forgeax/engine-runtime 0.1.6 → 0.1.19

package/src/__tests__/renderer-host-fallback.unit.test.ts

@@ -0,0 +1,112 @@
+import { EngineEnvironmentError } from '@forgeax/engine-render/internal/construct-renderer';
+import { RhiError } from '@forgeax/engine-rhi';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  constructRendererHost: vi.fn(),
+  loadBackendPack: vi.fn(),
+}));
+
+vi.mock('@forgeax/engine-render/internal/construct-renderer', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@forgeax/engine-render/internal/construct-renderer')>();
+  return { ...actual, constructRendererHost: mocks.constructRendererHost };
+});
+
+vi.mock('../backend-selection', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../backend-selection')>();
+  return { ...actual, loadBackendPack: mocks.loadBackendPack };
+});
+
+import { constructRuntimeRendererHost } from '../renderer-host';
+
+function environmentError(code: 'adapter-unavailable' | 'limit-exceeded') {
+  return new EngineEnvironmentError('no usable rendering backend', {
+    webgpuError: new RhiError({
+      code,
+      expected: 'a usable WebGPU backend',
+      hint: 'select another backend',
+    }),
+  });
+}
+
+function canvas() {
+  return { getContext: vi.fn((_kind?: string) => null) };
+}
+
+describe('runtime renderer backend fallback boundary', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('preserves ordinary construction errors and does not enter Channel 3', async () => {
+    const firstPack = { name: 'webgpu' };
+    const fallbackPack = { name: 'wgpu' };
+    const target = canvas();
+    const ordinaryError = new Error('shader compile failed');
+    mocks.loadBackendPack
+      .mockResolvedValueOnce({ ok: true, value: firstPack })
+      .mockResolvedValueOnce({ ok: true, value: fallbackPack });
+    mocks.constructRendererHost.mockImplementation(
+      async (hostCanvas: typeof target, _options: unknown, _bundler: unknown, pack: unknown) => {
+        if (pack === fallbackPack) hostCanvas.getContext('webgl2');
+        return { ok: false, error: ordinaryError };
+      },
+    );
+
+    const result = await constructRuntimeRendererHost(target);
+
+    expect(result).toEqual({ ok: false, error: ordinaryError });
+    expect(mocks.loadBackendPack).toHaveBeenCalledTimes(1);
+    expect(mocks.constructRendererHost).toHaveBeenCalledTimes(1);
+    expect(target.getContext).not.toHaveBeenCalled();
+  });
+
+  it('uses one Channel 3 attempt for an environment-class WebGPU failure', async () => {
+    const firstPack = { name: 'webgpu' };
+    const fallbackPack = { name: 'wgpu' };
+    const target = canvas();
+    const environmentFailure = environmentError('adapter-unavailable');
+    mocks.loadBackendPack
+      .mockResolvedValueOnce({ ok: true, value: firstPack })
+      .mockResolvedValueOnce({ ok: true, value: fallbackPack });
+    mocks.constructRendererHost
+      .mockResolvedValueOnce({ ok: false, error: environmentFailure })
+      .mockImplementationOnce(async (hostCanvas: typeof target, _options, _bundler, pack) => {
+        if (pack === fallbackPack) hostCanvas.getContext('webgl2');
+        return { ok: true, value: {} };
+      });
+
+    const result = await constructRuntimeRendererHost(target);
+
+    expect(result.ok).toBe(true);
+    expect(mocks.loadBackendPack).toHaveBeenCalledTimes(2);
+    expect(mocks.loadBackendPack).toHaveBeenNthCalledWith(2, undefined, true);
+    expect(mocks.constructRendererHost).toHaveBeenNthCalledWith(
+      2,
+      target,
+      undefined,
+      undefined,
+      fallbackPack,
+    );
+    expect(target.getContext).toHaveBeenCalledOnce();
+  });
+
+  it('never falls back for an explicitly injected RHI and retains structured detail', async () => {
+    const firstPack = { name: 'explicit' };
+    const target = canvas();
+    const environmentFailure = environmentError('limit-exceeded');
+    const explicitRhi = {};
+    mocks.loadBackendPack.mockResolvedValueOnce({ ok: true, value: firstPack });
+    mocks.constructRendererHost.mockResolvedValueOnce({ ok: false, error: environmentFailure });
+
+    const result = await constructRuntimeRendererHost(target, { rhi: explicitRhi as never });
+
+    expect(result).toEqual({ ok: false, error: environmentFailure });
+    expect(result.ok ? undefined : result.error).toBe(environmentFailure);
+    expect(environmentFailure.detail.webgpuError).toMatchObject({ code: 'limit-exceeded' });
+    expect(mocks.loadBackendPack).toHaveBeenCalledTimes(1);
+    expect(mocks.constructRendererHost).toHaveBeenCalledTimes(1);
+    expect(target.getContext).not.toHaveBeenCalled();
+  });
+});

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

@@ -1,6 +1,7 @@
 import { World } from '@forgeax/engine-ecs';
 import { rhi } from '@forgeax/engine-rhi-null';
 import { describe, expect, it } from 'vitest';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 import { requireRenderer } from './renderer-test-utils';
 
 function canvas(): HTMLCanvasElement {
@@ -15,6 +16,15 @@ const manifest = `data:application/json,${encodeURIComponent(
       { hash: 'unlit000', wgsl: '/* unlit */', glsl: '', bindings: '' },
       { hash: 'tonemap0', wgsl: '/* tonemap */', glsl: '', bindings: '' },
     ],
+    materialShaders: [
+      {
+        identifier: 'forgeax::default-standard-pbr',
+        sourcePath: 'forgeax::default-standard-pbr.wgsl',
+        composedWgsl: '/* stub */',
+        paramSchema: '[]',
+        variants: standardMaterialShaderVariants(),
+      },
+    ],
   }),
 )}`;
 

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

@@ -345,6 +345,72 @@ describe('Surface retry (w5)', () => {
     expect(ctxCalls.n).toBe(1);
     expect(cfgCalls.n).toBe(0);
   });
+
+  it('keeps an existing configured LKG when a reconfigure candidate fails proof validation', () => {
+    const cfgCalls = { n: 0 };
+    const ctxCalls = { n: 0 };
+    const ps = makePipelineState();
+    const reg = new HealthListenerRegistry();
+    const mockCtx = {
+      ...makeSurfaceCtx(cfgCalls, ctxCalls, 1),
+      presentationProof: { descriptor: true, acquisition: false, validation: true },
+    };
+    const pipelineState = ps as unknown as Parameters<typeof acquireSwapChainTarget>[1];
+    const dev = makeMockDevice(ps);
+    dev.caps = { backendKind: 'wgpu-webgl2', storageBuffer: false };
+    const errors: unknown[] = [];
+
+    // biome-ignore lint/suspicious/noExplicitAny: mock internals
+    const internals: any = {
+      canvas: { width: 800, height: 600 },
+      device: dev,
+      context: mockCtx,
+      getPipelineState: () => ps,
+      errorRegistry: {
+        add: () => () => {},
+        fire: (error: unknown) => errors.push(error),
+        clear: () => {},
+      },
+      healthRegistry: reg,
+    };
+
+    const target = acquireSwapChainTarget(internals, pipelineState);
+
+    expect(target).toBeNull();
+    expect(cfgCalls.n).toBe(1);
+    expect(ctxCalls.n).toBe(1);
+    expect(ps.perPassResources.configured).toBe(true);
+    expect(errors).toHaveLength(1);
+  });
+
+  it('keeps the first surface failure unconfigured and skips the retry', () => {
+    const cfgCalls = { n: 0 };
+    const ctxCalls = { n: 0 };
+    const ps = makePipelineState();
+    ps.perPassResources.configured = false;
+    const mockCtx = {
+      ...makeSurfaceCtx(cfgCalls, ctxCalls, 1),
+      presentationProof: { descriptor: true, acquisition: false, validation: true },
+    };
+    const pipelineState = ps as unknown as Parameters<typeof acquireSwapChainTarget>[1];
+    const dev = makeMockDevice(ps);
+    dev.caps = { backendKind: 'wgpu-webgl2', storageBuffer: false };
+
+    // biome-ignore lint/suspicious/noExplicitAny: mock internals
+    const internals: any = {
+      canvas: { width: 800, height: 600 },
+      device: dev,
+      context: mockCtx,
+      getPipelineState: () => ps,
+      errorRegistry: { add: () => () => {}, fire: () => {}, clear: () => {} },
+      healthRegistry: new HealthListenerRegistry(),
+    };
+
+    expect(acquireSwapChainTarget(internals, pipelineState)).toBeNull();
+    expect(cfgCalls.n).toBe(1);
+    expect(ctxCalls.n).toBe(1);
+    expect(ps.perPassResources.configured).toBe(false);
+  });
 });
 
 // ── w6: consecutive surface failure -> internal-fault (AC-04) ────────────────

package/src/__tests__/renderer.test-d.ts

@@ -49,6 +49,8 @@ describe('subscribe projects the discriminated Renderer event contract', () => {
           return `${event.previous}->${event.current}`;
         case 'error':
           return event.error.code;
+        case 'frame-submitted':
+          return `frame:${event.frameId}@${event.deviceGeneration}`;
       }
     };
     expectTypeOf(describeEvent).returns.toEqualTypeOf<string>();

package/src/__tests__/rhi-null-command-flow.unit.test.ts

@@ -17,6 +17,12 @@ function frameRequest(lease: Parameters<Renderer['draw']>[0]['leases'][number])
 describe('RhiNull command flow', () => {
   it('returns the synchronous receipt after the host submits a frame', async () => {
     const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    const events: Array<{
+      readonly kind: string;
+      readonly frameId?: number;
+      readonly deviceGeneration?: number;
+    }> = [];
+    const unsubscribe = renderer.subscribe((event) => events.push(event));
     const world = new World();
     const attached = renderer.attach(world);
     expect(attached.ok).toBe(true);
@@ -26,9 +32,17 @@ describe('RhiNull command flow', () => {
     const frame = renderer.draw(frameRequest(attached.value));
     expect(frame.ok).toBe(true);
     if (!frame.ok) return;
+    expect(events.filter((event) => event.kind === 'frame-submitted')).toEqual([
+      {
+        kind: 'frame-submitted',
+        frameId: frame.value.frameId,
+        deviceGeneration: frame.value.deviceGeneration,
+      },
+    ]);
     const completed = await frame.value.completed;
     expect(completed.ok).toBe(true);
     expect(renderer.inspect().frame.frameId).toBe(frame.value.frameId);
+    unsubscribe();
     renderer.dispose();
   });
 

package/src/__tests__/shadow-csm-cascade-loadop.test.ts

@@ -21,6 +21,7 @@ import type { World as WorldType } from '@forgeax/engine-ecs';
 import type { Renderer as RendererType } from '@forgeax/engine-render';
 import type { Handle } from '@forgeax/engine-types';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 
 const ENGINE = '../createRenderer';
 
@@ -152,7 +153,10 @@ function buildManifestDataUrl(): string {
     sourcePath: `${identifier}.wgsl`,
     composedWgsl,
     paramSchema: '[]',
-    variants: [],
+    variants:
+      identifier === 'forgeax::default-standard-pbr'
+        ? standardMaterialShaderVariants(composedWgsl)
+        : [],
   });
   const manifest = {
     schemaVersion: '1.0.0',

package/src/__tests__/shadow-csm-tile-consistency.test.ts

@@ -28,6 +28,7 @@ import type { World as WorldType } from '@forgeax/engine-ecs';
 import type { Renderer as RendererType } from '@forgeax/engine-render';
 import type { Handle } from '@forgeax/engine-types';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 
 const ENGINE = '../createRenderer';
 
@@ -143,7 +144,10 @@ function buildManifestDataUrl(): string {
     sourcePath: `${identifier}.wgsl`,
     composedWgsl,
     paramSchema: '[]',
-    variants: [],
+    variants:
+      identifier === 'forgeax::default-standard-pbr'
+        ? standardMaterialShaderVariants(composedWgsl)
+        : [],
   });
   const manifest = {
     schemaVersion: '1.0.0',

package/src/__tests__/skinned-shadow-mixed.dawn.test.ts

@@ -0,0 +1,383 @@
+// Real Dawn regression for the static/skinned shadow pipeline transition.
+//
+// The static shadow path uses the canonical all-true variant key (`''`) while
+// the skinned path uses an explicit negative skinning axis.  Keep both entries
+// in one production render so the pipeline layout and group-2 bind group must
+// change at the same command-recording boundary.
+
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import type { Renderer } from '@forgeax/engine-render';
+import { Camera, DirectionalLight, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { Skin } from '@forgeax/engine-skinning';
+import type { Handle, MaterialAsset, MeshAsset, SkeletonAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { constructRuntimeRendererHost } from '../renderer-host';
+import { drawPublished } from './draw-published';
+
+const WIDTH = 384;
+const HEIGHT = 256;
+const BYTES_PER_ROW = Math.ceil((WIDTH * 4) / 256) * 256;
+const TEXTURE_USAGE_COPY_SRC = 0x01;
+const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
+const BUFFER_USAGE_MAP_READ = 0x0001;
+const BUFFER_USAGE_COPY_DST = 0x0008;
+const MAP_MODE_READ = 0x0001;
+
+const ENGINE_MANIFEST = await (async () => {
+  const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+  return buildEngineShaderManifest();
+})();
+const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(
+  JSON.stringify(ENGINE_MANIFEST),
+)}`;
+
+type MixedCapture = {
+  readonly pixels: Uint8Array;
+  readonly errors: readonly string[];
+};
+
+function staticMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
+  return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::default-standard-pbr' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+      {
+        name: 'ShadowCaster',
+        program: { module: 'forgeax::default-shadow-caster' },
+        renderState: {
+          tags: { LightMode: 'ShadowCaster' },
+          passKind: 'shadow-caster',
+        },
+      },
+    ],
+    values: {
+      baseColor: [0.8, 0.35, 0.15, 1],
+      metallic: 0.1,
+      roughness: 0.55,
+      emissive: [0, 0, 0],
+      emissiveIntensity: 0,
+      occlusionStrength: 1,
+    },
+  });
+}
+
+function skinnedMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
+  return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::pbr-skin' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+      {
+        name: 'ShadowCaster',
+        program: { module: 'forgeax::default-shadow-caster' },
+        renderState: {
+          tags: { LightMode: 'ShadowCaster' },
+          passKind: 'shadow-caster',
+        },
+      },
+    ],
+    values: {
+      baseColor: [0.15, 0.45, 0.9, 1],
+      metallic: 0.1,
+      roughness: 0.55,
+      emissive: [0, 0, 0],
+      emissiveIntensity: 0,
+      occlusionStrength: 1,
+    },
+  });
+}
+
+function floorMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
+  return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::default-standard-pbr' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+    ],
+    values: {
+      baseColor: [0.75, 0.75, 0.75, 1],
+      metallic: 0,
+      roughness: 0.9,
+      emissive: [0, 0, 0],
+      emissiveIntensity: 0,
+      occlusionStrength: 1,
+    },
+  });
+}
+
+function skinnedMesh(world: World): Handle<'MeshAsset', 'shared'> {
+  // Canonical interleaved order: position, normal, uv, tangent, skinIndex,
+  // skinWeight (72 bytes / vertex). All vertices use joint zero.
+  const vertices = new Float32Array([
+    -0.75, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0.75, 0, 0, 0, 0, 1, 1, 0, 1, 0,
+    0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1.2, 0, 0, 0, 1, 0.5, 1, 1, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0,
+  ]);
+  return world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', {
+    kind: 'mesh',
+    vertices,
+    indices: new Uint16Array([0, 1, 2]),
+    attributes: {
+      position: new Float32Array([-0.75, 0, 0, 0.75, 0, 0, 0, 1.2, 0]),
+      normal: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),
+      uv: new Float32Array([0, 0, 1, 0, 0.5, 1]),
+      tangent: new Float32Array([1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1]),
+      skinIndex: new Uint16Array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
+      skinWeight: new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]),
+    },
+    aabb: new Float32Array([-0.75, 0, 0, 0.75, 1.2, 0]),
+    materialSlots: [{ slotName: 'Default' }],
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 3,
+        vertexCount: 3,
+        materialSlot: 0,
+        topology: 'triangle-list',
+      },
+    ],
+  });
+}
+
+function skeleton(world: World): Handle<'SkeletonAsset', 'shared'> {
+  const inverseBindMatrices = new Float32Array(16);
+  inverseBindMatrices[0] = 1;
+  inverseBindMatrices[5] = 1;
+  inverseBindMatrices[10] = 1;
+  inverseBindMatrices[15] = 1;
+  return world.allocSharedRef<'SkeletonAsset', SkeletonAsset>('SkeletonAsset', {
+    kind: 'skeleton',
+    inverseBindMatrices,
+    jointCount: 1,
+  });
+}
+
+function identityTransform(pos: readonly [number, number, number] = [0, 0, 0]) {
+  return { pos, quat: [0, 0, 0, 1] as const, scale: [1, 1, 1] as const };
+}
+
+function spawnMixedScene(world: World, castShadow: boolean): void {
+  const staticMat = staticMaterial(world);
+  const skinMat = skinnedMaterial(world);
+  const floorMat = floorMaterial(world);
+  const skinMesh = skinnedMesh(world);
+  const skinSkeleton = skeleton(world);
+
+  world.spawn(
+    { component: Transform, data: { ...identityTransform([0, 5, 5]), scale: [10, 0.1, 10] } },
+    { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+    { component: MeshRenderer, data: { materials: [floorMat] } },
+  );
+  world.spawn(
+    { component: Transform, data: identityTransform([0, 8, 18]) },
+    {
+      component: Camera,
+      data: {
+        fov: (45 * Math.PI) / 180,
+        aspect: WIDTH / HEIGHT,
+        near: 0.1,
+        far: 100,
+        clearColor: [0.02, 0.02, 0.03, 1],
+      },
+    },
+  );
+  world.spawn({
+    component: DirectionalLight,
+    data: {
+      direction: [0.25, -1, -0.45],
+      color: [1, 1, 1],
+      intensity: 1,
+      castShadow,
+      mapSize: 1024,
+      depthBias: 0.005,
+      normalBias: 0.05,
+      shadowDistance: 50,
+      pcfKernelSize: 3,
+    },
+  });
+
+  const spawnStaticCaster = (x: number): void => {
+    world.spawn(
+      { component: Transform, data: { ...identityTransform([x, 7, 5]), scale: [0.8, 0.8, 0.8] } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [staticMat] } },
+    );
+  };
+  // Entity order is intentional: static A -> skinned B -> static C.
+  spawnStaticCaster(-3);
+  const joint = world
+    .spawn({
+      component: Transform,
+      data: identityTransform([0, 7, 5]),
+    })
+    .unwrap();
+  world.spawn(
+    { component: Transform, data: identityTransform() },
+    { component: MeshFilter, data: { assetHandle: skinMesh } },
+    { component: MeshRenderer, data: { materials: [skinMat] } },
+    {
+      component: Skin,
+      data: {
+        skeleton: skinSkeleton,
+        joints: new Uint32Array([joint as unknown as number]),
+      },
+    },
+  );
+  spawnStaticCaster(3);
+}
+
+async function readPixels(device: GPUDevice, texture: GPUTexture): Promise<Uint8Array> {
+  const buffer = device.createBuffer({
+    size: BYTES_PER_ROW * HEIGHT,
+    usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST,
+  });
+  const encoder = device.createCommandEncoder();
+  encoder.copyTextureToBuffer(
+    { texture },
+    { buffer, bytesPerRow: BYTES_PER_ROW, rowsPerImage: HEIGHT },
+    { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+  );
+  device.queue.submit([encoder.finish()]);
+  await buffer.mapAsync(MAP_MODE_READ);
+  const pixels = new Uint8Array(buffer.getMappedRange().slice(0));
+  buffer.unmap();
+  buffer.destroy();
+  return pixels;
+}
+
+async function renderMixed(castShadow: boolean): Promise<MixedCapture> {
+  let device: GPUDevice | undefined;
+  let target: GPUTexture | undefined;
+  const originalRequestAdapter = globalThis.navigator.gpu.requestAdapter.bind(
+    globalThis.navigator.gpu,
+  );
+  globalThis.navigator.gpu.requestAdapter = async (options) => {
+    const adapter = await originalRequestAdapter(options);
+    if (adapter === null) return adapter;
+    const originalRequestDevice = adapter.requestDevice.bind(adapter);
+    adapter.requestDevice = async (descriptor) => {
+      const created = await originalRequestDevice(descriptor);
+      device ??= created;
+      return created;
+    };
+    return adapter;
+  };
+  const canvas = {
+    width: WIDTH,
+    height: HEIGHT,
+    getContext(kind: string): unknown {
+      if (kind !== 'webgpu') return null;
+      return {
+        configure(descriptor: { device: GPUDevice; format?: GPUTextureFormat }) {
+          target ??= descriptor.device.createTexture({
+            size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+            format: descriptor.format ?? 'rgba8unorm',
+            usage: TEXTURE_USAGE_RENDER_ATTACHMENT | TEXTURE_USAGE_COPY_SRC,
+            viewFormats: ['rgba8unorm-srgb'],
+          });
+        },
+        unconfigure() {},
+        getCurrentTexture(): GPUTexture {
+          if (target === undefined) throw new Error('render target requested before configure');
+          return target;
+        },
+      };
+    },
+    addEventListener() {},
+    removeEventListener() {},
+  } as unknown as HTMLCanvasElement;
+
+  let renderer: Renderer | undefined;
+  let unsubscribe: (() => void) | undefined;
+  const errors: string[] = [];
+  try {
+    const host = await constructRuntimeRendererHost(
+      canvas,
+      {},
+      {
+        shaderManifestUrl: ENGINE_MANIFEST_URL,
+      },
+    );
+    if (!host.ok) throw host.error;
+    renderer = host.value.renderer;
+    unsubscribe = renderer.subscribe((event) => {
+      if (event.kind === 'error') errors.push(event.error.code);
+    });
+    const world = new World();
+    spawnMixedScene(world, castShadow);
+    // The first frame warms the static and skinned PSOs; the second frame is
+    // the asserted mixed command stream after both cache entries exist.
+    for (let frame = 0; frame < 2; frame += 1) {
+      const receipt = drawPublished(renderer, world);
+      expect(receipt.ok, `mixed ${castShadow ? 'shadow' : 'baseline'} draw`).toBe(true);
+      if (!receipt.ok) throw receipt.error;
+      const completed = await receipt.value.completed;
+      expect(completed.ok, 'Queue::submit completion').toBe(true);
+      if (!completed.ok) throw completed.error;
+    }
+    if (device === undefined || target === undefined)
+      throw new Error('Dawn target not initialized');
+    await device.queue.onSubmittedWorkDone();
+    return { pixels: await readPixels(device, target), errors };
+  } finally {
+    globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
+    unsubscribe?.();
+    renderer?.dispose();
+    target?.destroy();
+    device?.destroy();
+  }
+}
+
+function regionDiff(a: Uint8Array, b: Uint8Array, x0: number, x1: number): number {
+  let changed = 0;
+  for (let y = Math.floor(HEIGHT * 0.32); y < HEIGHT; y += 1) {
+    for (let x = x0; x < x1; x += 1) {
+      const index = y * BYTES_PER_ROW + x * 4;
+      if (
+        Math.abs((a[index] ?? 0) - (b[index] ?? 0)) > 2 ||
+        Math.abs((a[index + 1] ?? 0) - (b[index + 1] ?? 0)) > 2 ||
+        Math.abs((a[index + 2] ?? 0) - (b[index + 2] ?? 0)) > 2
+      ) {
+        changed += 1;
+      }
+    }
+  }
+  return changed;
+}
+
+describe('mixed static/skinned shadow pipeline (Dawn)', () => {
+  it('submits static → skinned → static casters with zero validation errors', async () => {
+    if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') {
+      throw new Error('dawn-node navigator.gpu not injected');
+    }
+    const shadow = await renderMixed(true);
+    const baseline = await renderMixed(false);
+    expect(shadow.errors).toEqual([]);
+    expect(baseline.errors).toEqual([]);
+    expect(shadow.pixels.length).toBeGreaterThan(0);
+    expect(baseline.pixels.length).toBe(shadow.pixels.length);
+
+    // Each caster owns a separate x-region. Comparing against the identical
+    // no-shadow scene proves the depth pass contributed in all three regions,
+    // rather than merely proving that a color frame was non-black.
+    const regions = [
+      [0, Math.floor(WIDTH / 3)],
+      [Math.floor(WIDTH / 3), Math.floor((2 * WIDTH) / 3)],
+      [Math.floor((2 * WIDTH) / 3), WIDTH],
+    ] as const;
+    for (const [x0, x1] of regions) {
+      expect(regionDiff(shadow.pixels, baseline.pixels, x0, x1)).toBeGreaterThan(0);
+    }
+  }, 120000);
+});