@forgeax/engine-runtime 0.1.7 → 0.1.19

package/src/__tests__/materials.unit.test.ts

@@ -197,6 +197,8 @@ describe('Materials.standard multi-pass (w14)', () => {
         { name: 'specularTintTexture', type: 'texture', optional: true },
         { name: 'emissiveTexture', type: 'texture', optional: true },
         { name: 'occlusionTexture', type: 'texture', optional: true },
+        { name: 'transmissionTexture', type: 'texture', optional: true },
+        { name: 'thicknessTexture', type: 'texture', optional: true },
       ]);
     });
 

package/src/__tests__/pbr-pipeline.unit.test.ts

@@ -82,22 +82,22 @@ describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', (
   });
 
   describe('pbr-material-merged', () => {
-    it('24 entries: user-region 13 (derived) + ibl 7 + lightmap 4', () => {
+    it('26 entries: user-region 17 (derived) + ibl 7 + transmission 2', () => {
       const spec = makeSpec();
       const out = buildBindGroupLayoutDescriptor(spec, {
         kind: 'pbr-material-merged',
       });
       // Post-M2 (D-1): user-region comes from derive(paramSchema).bglEntries
-      // (built-in standard-PBR 4-texture fallback), then IBL + lightmap are
-      // appended at start = userRegion.length.
+      // (built-in standard-PBR 8-texture contract), then IBL + transmission
+      // are appended at start = userRegion.length.
       const userRegion = buildPbrMaterialUserRegionEntries();
       const afterIbl = [...userRegion, ...appendInjection(userRegion, 'ibl')];
       const expected = {
         label: 'pbr-material-skylight-bgl',
-        entries: [...afterIbl, ...appendInjection(afterIbl, 'lightmap')],
+        entries: [...afterIbl, ...appendInjection(afterIbl, 'transmission')],
       };
       expect(out).toEqual(expected);
-      expect(out.entries.length).toBe(24);
+      expect(out.entries.length).toBe(26);
     });
   });
 
@@ -142,7 +142,7 @@ describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', (
         entries: [
           {
             binding: 0,
-            visibility: 0x1,
+            visibility: 0x3,
             buffer: { type: 'read-only-storage', hasDynamicOffset: false },
           },
         ],
@@ -185,7 +185,7 @@ describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', (
   });
 
   describe('unlit-material', () => {
-    it('13 entries: base PBR material only (no skylight injection)', () => {
+    it('17 entries: base PBR material only (no skylight injection)', () => {
       const spec = makeSpec();
       const out = buildBindGroupLayoutDescriptor(spec, {
         kind: 'unlit-material',
@@ -194,7 +194,7 @@ describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', (
         label: 'unlit-material-bgl',
         entries: buildPbrMaterialUserRegionEntries(),
       });
-      expect(out.entries.length).toBe(13);
+      expect(out.entries.length).toBe(17);
     });
   });
 });

package/src/__tests__/pipeline-cache-keying.unit.test.ts

@@ -127,14 +127,16 @@ describe('cacheKeyOf passKind dimension', () => {
 describe('PassKind open string + KNOWN_PASS_KINDS (feat-20260615 D-10)', () => {
   // M2-T4 expanded KNOWN_PASS_KINDS from 4 to 6 entries by adding 'post-process'
   // and 'skybox'; point-shadow-caster is the engine's depth-only point-light
-  // pass and is part of the discoverable catalogue as well.
-  it('KNOWN_PASS_KINDS has exactly 7 entries', () => {
-    expect(KNOWN_PASS_KINDS).toHaveLength(7);
+  // pass and is part of the discoverable catalogue as well. M3-T4 adds the
+  // Standard temporal producer to the shipped pass catalogue.
+  it('KNOWN_PASS_KINDS has exactly 8 entries', () => {
+    expect(KNOWN_PASS_KINDS).toHaveLength(8);
   });
 
-  it('KNOWN_PASS_KINDS contains the 7 engine-shipped pass kinds', () => {
+  it('KNOWN_PASS_KINDS contains the 8 engine-shipped pass kinds', () => {
     expect(KNOWN_PASS_KINDS).toContain('forward');
     expect(KNOWN_PASS_KINDS).toContain('deferred');
+    expect(KNOWN_PASS_KINDS).toContain('temporal');
     expect(KNOWN_PASS_KINDS).toContain('lighting');
     expect(KNOWN_PASS_KINDS).toContain('shadow-caster');
     expect(KNOWN_PASS_KINDS).toContain('point-shadow-caster');

package/src/__tests__/pipeline.unit.test.ts

@@ -138,6 +138,7 @@ import {
 import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
 import { matchPass } from '../../../render/src/systems/pass-selector';
 import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 
 function makeExplicitNullRhi(spies: {
   setIndexBuffer: ReturnType<typeof vi.fn>;
@@ -2407,7 +2408,8 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
       sourcePath: `${identifier}.wgsl`,
       composedWgsl: '/* stub */',
       paramSchema: '[]',
-      variants: [],
+      variants:
+        identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
     });
     const manifest = {
       schemaVersion: '1.0.0',
@@ -2697,7 +2699,8 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
       sourcePath: `${identifier}.wgsl`,
       composedWgsl: '/* stub */',
       paramSchema: '[]',
-      variants: [],
+      variants:
+        identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
     });
     const manifest = {
       schemaVersion: '1.0.0',

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':
@@ -171,10 +189,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 +296,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 +328,11 @@ 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;
     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-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

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] },

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