@forgeax/engine-runtime 0.1.7 → 0.1.20

package/src/__tests__/render-environment-consumer.integration.test.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const environmentSource = readFileSync(
+  fileURLToPath(new URL('../../../render/src/extract/environment.ts', import.meta.url)),
+  'utf8',
+);
+const vfxSource = readFileSync(
+  fileURLToPath(
+    new URL('../../../vfx-render/src/feature/gpu-particle-feature.ts', import.meta.url),
+  ),
+  'utf8',
+);
+
+describe('runtime Environment consumer ownership', () => {
+  it('consumes extracted Environment facts without a second Fog resource topology', () => {
+    expect(environmentSource).toContain('createEnvironmentExtractionContext');
+    expect(environmentSource).not.toContain('createFullscreenRenderFeature');
+    expect(vfxSource).not.toMatch(/fog.*(history|counter|upload)/i);
+  });
+
+  it('indexes the public recovery sequence without exposing graph or device state', () => {
+    const runtimeReadme = readFileSync(
+      fileURLToPath(new URL('../../README.md', import.meta.url)),
+      'utf8',
+    );
+    expect(runtimeReadme).toContain('inspect()');
+    expect(runtimeReadme).toContain('typed `detail`');
+    expect(runtimeReadme).toMatch(/retry the same\s+request/);
+    expect(runtimeReadme).toContain('graph, device, or');
+  });
+});

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

@@ -38,14 +38,30 @@ function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
       return code;
     case 'cleanup-failed':
       return code;
+    case 'taa-unavailable':
+      return code;
     case 'frame-receipt-stale':
       return code;
     case 'renderer-contract-failed':
       return code;
     case 'observation-unavailable':
       return code;
+    case 'scene-data-unavailable':
+      return code;
     case 'shadow-invalid-config':
       return code;
+    case 'environment-source-conflict':
+      return code;
+    case 'fog-cardinality':
+      return code;
+    case 'taa-caps-insufficient':
+      return code;
+    case 'environment-generation-failed':
+      return code;
+    case 'atmosphere-invalid-parameter':
+      return code;
+    case 'owner-stage-failed':
+      return code;
     case 'equirect-projection-failed':
       return code;
     case 'hdrp-light-budget-exceeded':
@@ -84,6 +100,8 @@ function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
       return code;
     case 'render-feature-draw-recording-failed':
       return code;
+    case 'transmission-capability-missing':
+      return code;
     case 'points-lines-invalid-style':
       return code;
     case 'points-lines-topology-mismatch':
@@ -96,6 +114,16 @@ function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
       return code;
     case 'points-lines-prepare-failed':
       return code;
+    case 'projector-binding-failed':
+      return code;
+    case 'volume-owner-conflict':
+      return code;
+    case 'volume-density-shape-mismatch':
+      return code;
+    case 'volume-invalid-bounds':
+      return code;
+    case 'volume-invalid-parameters':
+      return code;
     default: {
       const exhaustive: never = code;
       return exhaustive;
@@ -171,10 +199,41 @@ function narrowRenderError(err: RenderError): void {
       void err.detail.reason;
       void err.detail.recovery;
       break;
+    case 'scene-data-unavailable':
+      void err.detail.featureIdentity;
+      void err.detail.schema;
+      void err.detail.lane;
+      void err.detail.reason;
+      void err.detail.missingContributorIds;
+      void err.detail.omittedMissingContributorCount;
+      void err.detail.recovery;
+      break;
     case 'shadow-invalid-config':
       void err.detail.field; // string
       void err.detail.value; // number
       break;
+    case 'environment-source-conflict':
+      void err.detail.owners;
+      break;
+    case 'fog-cardinality':
+      void err.detail.count;
+      break;
+    case 'taa-caps-insufficient':
+      void err.detail.required;
+      void err.detail.available;
+      break;
+    case 'environment-generation-failed':
+      void err.detail.sourceKey;
+      void err.detail.stage;
+      break;
+    case 'atmosphere-invalid-parameter':
+      void err.detail.field;
+      void err.detail.value;
+      break;
+    case 'owner-stage-failed':
+      void err.detail.owner;
+      void err.detail.stage;
+      break;
     case 'equirect-projection-failed':
       void err.detail.handle; // number
       break;
@@ -247,6 +306,9 @@ function narrowRenderError(err: RenderError): void {
       void err.detail.backendReason;
       void err.detail.operation;
       break;
+    case 'taa-unavailable':
+      void err.detail.reason;
+      break;
     case 'vertex-color-variant-conflict':
       void err.detail.authored;
       void err.detail.authoredValue;
@@ -276,6 +338,30 @@ function narrowRenderError(err: RenderError): void {
       void err.detail.owner;
       void err.detail.generation;
       break;
+    case 'transmission-capability-missing':
+      void err.detail.material;
+      void err.detail.capability;
+      void err.detail.stage;
+      break;
+    case 'projector-binding-failed':
+      void err.detail.guid;
+      void err.detail.status;
+      break;
+    case 'volume-owner-conflict':
+      void err.detail.ownerCount;
+      break;
+    case 'volume-density-shape-mismatch':
+      void err.detail.guid;
+      void err.detail.viewDimension;
+      break;
+    case 'volume-invalid-bounds':
+      void err.detail.min;
+      void err.detail.max;
+      break;
+    case 'volume-invalid-parameters':
+      void err.detail.field;
+      void err.detail.value;
+      break;
     default: {
       const exhaustive: never = err;
       void exhaustive;

package/src/__tests__/render-feature-prepared-graphics.fixture.ts

@@ -8,6 +8,7 @@ import type {
 import { Camera } from '@forgeax/engine-render';
 import { Transform } from '@forgeax/engine-scene';
 import { ok } from '@forgeax/engine-types';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 
 export type PreparedFeatureMode = 'accepted' | 'empty' | 'mismatch' | 'recovery';
 
@@ -19,6 +20,15 @@ export const preparedManifest = `data:application/json,${encodeURIComponent(
       { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
       { hash: 'tonemap0', wgsl: '/* tonemap stub */', glsl: '', bindings: '' },
     ],
+    materialShaders: [
+      {
+        identifier: 'forgeax::default-standard-pbr',
+        sourcePath: 'forgeax::default-standard-pbr.wgsl',
+        composedWgsl: '/* stub */',
+        paramSchema: '[]',
+        variants: standardMaterialShaderVariants(),
+      },
+    ],
   }),
 )}`;
 

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

@@ -1193,12 +1193,11 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       'TextureAsset',
       {
         kind: 'texture',
-        width: 1,
-        height: 1,
+        shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
         format: 'rgba8unorm',
         data: new Uint8Array([255, 255, 255, 255]),
         colorSpace: 'linear',
-        mipmap: false,
+        mips: { kind: 'none' },
       },
     );
   }
@@ -1211,12 +1210,11 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       const textureGuid = AssetGuid.random();
       assets.catalog(textureGuid, {
         kind: 'texture',
-        width: 1,
-        height: 1,
+        shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
         format: 'rgba8unorm',
         data: new Uint8Array([255, 255, 255, 255]),
         colorSpace: 'linear',
-        mipmap: false,
+        mips: { kind: 'none' },
       } satisfies TextureAsset);
       const matHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
         kind: 'material',

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

@@ -20,6 +20,7 @@ import { Transform } from '@forgeax/engine-scene';
 import type { Handle } from '@forgeax/engine-types';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 import { drawWithOwners } from './renderer-test-utils';
 
 type RendererErrorObservation = {
@@ -278,7 +279,8 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       sourcePath: `${identifier}.wgsl`,
       composedWgsl: '/* stub */',
       paramSchema: '[]',
-      variants: [],
+      variants:
+        identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
     });
     const manifest = {
       schemaVersion: '1.0.0',

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

@@ -33,6 +33,7 @@ import type { World as WorldType } from '@forgeax/engine-ecs';
 import type { Renderer as RendererType } from '@forgeax/engine-render';
 import type { Handle, MaterialAsset, MeshAsset, TextureAsset } from '@forgeax/engine-types';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 
 function canonicalTestMeshAttributes(vertexCount: number) {
   return {
@@ -195,7 +196,8 @@ function buildManifestDataUrl(): string {
     sourcePath: `${identifier}.wgsl`,
     composedWgsl: '/* stub */',
     paramSchema,
-    variants: [],
+    variants:
+      identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
   });
   // The standard-PBR shader declares baseColorTexture / metallicRoughnessTexture
   // / normalTexture as texture2d params. Texture resolution is now schema-driven
@@ -321,8 +323,7 @@ function makeChequerTexture(): TextureAsset {
   // textureView sentinel.
   return {
     kind: 'texture',
-    width: 2,
-    height: 2,
+    shape: { viewDimension: '2d', extent: { width: 2, height: 2 } },
     // colorSpace=linear+rgba8unorm to satisfy the runtime's
     // srgb-format consistency validator (layer 7c-1: srgb requires
     // rgba8unorm-srgb). The test only cares that each texture's
@@ -330,7 +331,7 @@ function makeChequerTexture(): TextureAsset {
     format: 'rgba8unorm',
     data: new Uint8Array(2 * 2 * 4),
     colorSpace: 'linear',
-    mipmap: false,
+    mips: { kind: 'none' },
   } as unknown as TextureAsset;
 }
 
@@ -584,12 +585,11 @@ async function spawnPbrMissingTextureScene(): Promise<unknown> {
   // existing debug-pink fallback.
   const unresidentTexture = {
     kind: 'texture',
-    width: 2,
-    height: 2,
+    shape: { viewDimension: '2d', extent: { width: 2, height: 2 } },
     format: 'rgba8unorm-srgb',
     data: new Uint8Array(2 * 2 * 4),
     colorSpace: 'srgb',
-    mipmap: false,
+    mips: { kind: 'none' },
   } as unknown as TextureAsset;
   const badTexHandle = world.allocSharedRef('TextureAsset', unresidentTexture) as unknown as Handle<
     'TextureAsset',

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

@@ -26,6 +26,7 @@ import type { World as WorldType } from '@forgeax/engine-ecs';
 import type { Renderer as RendererType } from '@forgeax/engine-render';
 import type { Handle, MaterialAsset, MeshAsset, TextureAsset } from '@forgeax/engine-types';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 
 function canonicalTestMeshAttributes(vertexCount: number) {
   return {
@@ -161,7 +162,8 @@ function buildManifestDataUrl(): string {
     sourcePath: `${identifier}.wgsl`,
     composedWgsl: '/* stub */',
     paramSchema,
-    variants: [],
+    variants:
+      identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
   });
   const pbrParamSchema = JSON.stringify([
     { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
@@ -254,12 +256,11 @@ function cameraTransform() {
 function makeTex(): TextureAsset {
   return {
     kind: 'texture',
-    width: 2,
-    height: 2,
+    shape: { viewDimension: '2d', extent: { width: 2, height: 2 } },
     format: 'rgba8unorm',
     data: new Uint8Array(2 * 2 * 4),
     colorSpace: 'linear',
-    mipmap: false,
+    mips: { kind: 'none' },
   } as unknown as TextureAsset;
 }
 

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

@@ -55,7 +55,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
   // asserts the PBR baseline against literal byte values.
   //
   // Coverage:
-  //   - 304 B payload (STANDARD_PBR_UBO_SIZE)
+  //   - 384 B payload (STANDARD_PBR_UBO_SIZE)
   //   - slot 0 = baseColor.rgb + 1 (alpha hardcoded)
   //   - slot 1 first 8 B = metallic, roughness (f32x2)
   //   - slot 1 last 4 u32 (channelMap) = [2, 1, 0, 0]
@@ -108,7 +108,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       expect(typeof mod.buildPbrMaterialUboPayload).toBe('function');
     });
 
-    it('304 B payload size + standard PBR slot layout (baseline)', () => {
+    it('384 B payload size + standard PBR slot layout (baseline)', () => {
       if (typeof mod.buildPbrMaterialUboPayload !== 'function') {
         throw new Error('helper not exported yet');
       }
@@ -124,7 +124,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
         specularTint: [0.11, 0.22, 0.33],
       });
       const buf = mod.buildPbrMaterialUboPayload(snap);
-      expect(buf.byteLength).toBe(304);
+      expect(buf.byteLength).toBe(384);
       const f32 = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
       // feat-20260613 fix-issue-1 (D-8 channelMap split): the 4 channelMap
       // u32 slots collapse into 4 independent f32 channel selectors at
@@ -161,7 +161,9 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       expect(f32[20]).toBeCloseTo(0.11);
       expect(f32[21]).toBeCloseTo(0.22);
       expect(f32[22]).toBeCloseTo(0.33);
-      expect(f32[72]).toBe(1);
+      // normalScale remains at the scalar end of the authored region after
+      // transmission fields moved the engine-owned coordinate records.
+      expect(f32[23]).toBe(1);
     });
 
     it('writes schema-carried alphaCutoff into the baseline PBR payload', () => {
@@ -180,15 +182,15 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       const apply = mod.applyMaterialTextureUvScales;
       if (typeof apply !== 'function') throw new Error('helper not exported yet');
       const world = new World();
-      const pbrPayload = new ArrayBuffer(304);
+      const pbrPayload = new ArrayBuffer(384);
       apply(pbrPayload, makePbrSnapshot({}), world);
       const pbrF32 = new Float32Array(pbrPayload);
-      expect(pbrF32[26]).toBe(1);
       expect(pbrF32[34]).toBe(1);
       expect(pbrF32[42]).toBe(1);
       expect(pbrF32[50]).toBe(1);
       expect(pbrF32[58]).toBe(1);
       expect(pbrF32[66]).toBe(1);
+      expect(pbrF32[74]).toBe(1);
 
       const spritePayload = new ArrayBuffer(128);
       apply(

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__/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',