@forgeax/engine-render 0.1.23 → 0.1.25

package/src/__tests__/renderer-recovery-capability-matrix.unit.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import {
+  classifyRecoveryCapability,
+  type RecoveryCapabilityFacts,
+} from '../gpu-driven/production-raster';
+
+const allCapabilities: RecoveryCapabilityFacts = {
+  generation: 7,
+  compute: true,
+  storageBuffer: true,
+  indirectDrawing: true,
+  multisample: true,
+  shaderCompilation: true,
+};
+
+describe('renderer recovery capability matrix', () => {
+  it('publishes the standard fallback when optional capability is absent', () => {
+    const result = classifyRecoveryCapability({
+      ...allCapabilities,
+      multisample: false,
+    });
+
+    expect(result).toEqual({
+      status: 'fallback',
+      generation: 7,
+      disabled: [],
+    });
+  });
+
+  it('reports optional GPU-driven work as disabled without allocation', () => {
+    const result = classifyRecoveryCapability({
+      ...allCapabilities,
+      compute: false,
+      storageBuffer: false,
+      indirectDrawing: false,
+    });
+
+    expect(result).toEqual({
+      status: 'disabled',
+      generation: 7,
+      disabled: ['gpu-driven'],
+      allocations: 0,
+    });
+  });
+
+  it('refuses a generation that lacks a core shader capability', () => {
+    const result = classifyRecoveryCapability({
+      ...allCapabilities,
+      shaderCompilation: false,
+    });
+
+    expect(result).toEqual({
+      status: 'refused',
+      generation: 7,
+      failedOwner: 'shader-material-pipeline',
+      resourceKind: 'pipeline',
+    });
+  });
+});

package/src/__tests__/renderer-recovery-contract.unit.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createRecoveryFailedError,
+  RECOVERY_PHASES,
+  type RecoveryFailureDetail,
+} from '../errors/recover';
+
+const receipt = Object.freeze({ owner: 'renderer', generation: 4, resourceCount: 3 });
+
+function detail(overrides: Partial<RecoveryFailureDetail> = {}): RecoveryFailureDetail {
+  return {
+    phase: 'compile-graph',
+    oldGeneration: 4,
+    candidateGeneration: 5,
+    attempt: 2,
+    elapsedMs: 120,
+    retryable: true,
+    guidance: 'retry',
+    owner: 'standard-pipeline',
+    resourceKind: 'pipeline',
+    lastOutcome: 'failed',
+    rehydratedRoots: 3,
+    staleLossEvents: 1,
+    cause: new Error('candidate failed'),
+    cleanupFailures: [],
+    receipt,
+    ...overrides,
+  };
+}
+
+describe('renderer recovery error contract', () => {
+  it('keeps recovery phases and guidance closed and machine-readable', () => {
+    expect(RECOVERY_PHASES).toEqual([
+      'quiesce',
+      'acquire-adapter',
+      'acquire-device',
+      'rehydrate',
+      'compile-graph',
+      'publish',
+      'cleanup',
+    ]);
+
+    const failure = createRecoveryFailedError(detail());
+    expect(failure.code).toBe('recovery-failed');
+    expect(failure.expected).toContain('complete replacement');
+    expect(failure.hint).toContain('detail');
+    expect(failure.detail.phase).toBe('compile-graph');
+    expect(failure.detail.oldGeneration).toBe(4);
+    expect(failure.detail.candidateGeneration).toBe(5);
+    expect(failure.detail.attempt).toBe(2);
+    expect(failure.detail.elapsedMs).toBe(120);
+    expect(failure.detail.retryable).toBe(true);
+    expect(failure.detail.guidance).toBe('retry');
+    expect(failure.detail.owner).toBe('standard-pipeline');
+    expect(failure.detail.resourceKind).toBe('pipeline');
+    expect(failure.detail.lastOutcome).toBe('failed');
+    expect(failure.detail.rehydratedRoots).toBe(3);
+    expect(failure.detail.staleLossEvents).toBe(1);
+    expect(failure.detail.cleanupFailures).toEqual([]);
+    expect(Object.isFrozen(failure.detail)).toBe(true);
+  });
+
+  it.each([
+    ['retry', true],
+    ['repair-owner', true],
+    ['rebuild-renderer', false],
+  ] as const)('preserves the %s guidance branch', (guidance, retryable) => {
+    const failure = createRecoveryFailedError(detail({ guidance, retryable }));
+    expect(failure.detail.guidance).toBe(guidance);
+    expect(failure.detail.retryable).toBe(retryable);
+    expect(failure.message).not.toContain('retry');
+  });
+});

package/src/__tests__/renderer-recovery-lifecycle.unit.test.ts

@@ -0,0 +1,216 @@
+import { RhiNullCommandEncoder, RhiNullDevice, RhiNullQueue, rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  acquireDeviceGeneration,
+  probeCandidateGraphExecution,
+  runRecoveryStep,
+} from '../assembly/recovery/recovery-attempt';
+import {
+  createRecoveryContinuation,
+  createRecoveryDeadline,
+  createRendererLifecycle,
+  createSingleFlight,
+  RECOVERY_ADAPTER_DEADLINE_MS,
+  RECOVERY_DEVICE_DEADLINE_MS,
+  RECOVERY_PHASES,
+  RECOVERY_TOTAL_DEADLINE_MS,
+} from '../assembly/renderer-lifecycle';
+
+describe('renderer recovery lifecycle', () => {
+  it('exhausts the public lifecycle states and rejects illegal transitions', () => {
+    const lifecycle = createRendererLifecycle();
+
+    expect(lifecycle.state()).toBe('alive');
+    expect(lifecycle.transition('device-lost')).toBe(true);
+    expect(lifecycle.transition('recovering')).toBe(true);
+    expect(lifecycle.transition('alive')).toBe(true);
+    expect(lifecycle.transition('faulted')).toBe(false);
+    expect(lifecycle.transition('disposed')).toBe(true);
+    expect(lifecycle.transition('alive')).toBe(false);
+    expect(lifecycle.states()).toEqual([
+      'alive',
+      'device-lost',
+      'recovering',
+      'faulted',
+      'disposed',
+    ]);
+  });
+
+  it('shares one recovery promise and one candidate for concurrent callers', async () => {
+    let attempts = 0;
+    let release: (() => void) | undefined;
+    const flight = createSingleFlight(async () => {
+      attempts += 1;
+      await new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      return { candidate: attempts };
+    });
+
+    const first = flight.run();
+    const second = flight.run();
+    expect(first).toBe(second);
+    expect(flight.inFlight()).toBe(first);
+    expect(attempts).toBe(1);
+
+    release?.();
+    await expect(first).resolves.toEqual({ candidate: 1 });
+    expect(flight.inFlight()).toBeUndefined();
+  });
+
+  it('enforces the 20 second attempt and 10 second acquisition budgets', () => {
+    const deadline = createRecoveryDeadline(1000);
+
+    expect(deadline.totalDeadlineMs).toBe(RECOVERY_TOTAL_DEADLINE_MS);
+    expect(deadline.adapterDeadlineMs).toBe(RECOVERY_ADAPTER_DEADLINE_MS);
+    expect(deadline.deviceDeadlineMs).toBe(RECOVERY_DEVICE_DEADLINE_MS);
+    expect(deadline.isValid('acquire-adapter', 10_999)).toBe(true);
+    expect(deadline.isValid('acquire-adapter', 11_000)).toBe(false);
+    expect(deadline.isValid('acquire-device', 11_000)).toBe(false);
+    expect(deadline.isValid('compile-graph', 20_999)).toBe(true);
+    expect(deadline.isValid('compile-graph', 21_000)).toBe(false);
+    expect(RECOVERY_PHASES).toEqual([
+      'quiesce',
+      'acquire-adapter',
+      'acquire-device',
+      'rehydrate',
+      'compile-graph',
+      'publish',
+      'cleanup',
+    ]);
+  });
+
+  it('reports acquisition phases in their execution order', async () => {
+    const phases: string[] = [];
+    const result = await acquireDeviceGeneration(
+      { rhi },
+      {} as HTMLCanvasElement,
+      undefined,
+      undefined,
+      (phase) => phases.push(phase),
+    );
+
+    expect(result.ok).toBe(true);
+    expect(phases).toEqual(['acquire-adapter', 'acquire-device']);
+  });
+
+  it('treats the null graph probe as structural-only and rejects a non-null pixel mismatch', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const nullDevice = (await adapter.requestDevice()).unwrap();
+    const texture = nullDevice
+      .createTexture({
+        label: 'recovery-probe-test.texture',
+        size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+        mipLevelCount: 1,
+        sampleCount: 1,
+        dimension: '2d',
+        format: 'rgba8unorm',
+        usage: 0x11,
+        viewFormats: undefined,
+        textureBindingViewDimension: undefined,
+      })
+      .unwrap();
+    const view = nullDevice.createTextureView(texture, { dimension: '2d' }).unwrap();
+    const nullProbe = await probeCandidateGraphExecution(nullDevice, {
+      texture,
+      view,
+      format: 'rgba8unorm',
+    });
+    expect(nullProbe.ok).toBe(true);
+
+    class PixellessNonNullDevice extends RhiNullDevice {
+      override get caps() {
+        return { ...super.caps, backendKind: 'webgpu' as const };
+      }
+    }
+    const nonNullDevice = new PixellessNonNullDevice(
+      new RhiNullQueue(),
+      (bookkeeper, device) => new RhiNullCommandEncoder(bookkeeper, device),
+    );
+    const nonNullTexture = nonNullDevice
+      .createTexture({
+        label: 'recovery-probe-test.non-null-texture',
+        size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+        mipLevelCount: 1,
+        sampleCount: 1,
+        dimension: '2d',
+        format: 'rgba8unorm',
+        usage: 0x11,
+        viewFormats: undefined,
+        textureBindingViewDimension: undefined,
+      })
+      .unwrap();
+    const nonNullView = nonNullDevice
+      .createTextureView(nonNullTexture, { dimension: '2d' })
+      .unwrap();
+    const nonNullProbe = await probeCandidateGraphExecution(nonNullDevice, {
+      texture: nonNullTexture,
+      view: nonNullView,
+      format: 'rgba8unorm',
+    });
+    expect(nonNullProbe.ok).toBe(false);
+    if (!nonNullProbe.ok) expect(nonNullProbe.error.code).toBe('webgpu-runtime-error');
+  });
+
+  it('invalidates late continuation and cleans the candidate exactly once', () => {
+    let cleanupCount = 0;
+    const continuation = createRecoveryContinuation(createRecoveryDeadline(0), () => {
+      cleanupCount += 1;
+    });
+
+    expect(continuation.isValid('compile-graph', 19_999)).toBe(true);
+    continuation.abandon(20_000);
+    expect(continuation.isValid('compile-graph', 20_000)).toBe(false);
+    continuation.cleanupOnce();
+    continuation.cleanupOnce();
+    expect(cleanupCount).toBe(1);
+  });
+
+  it('invalidates an async step on timeout before a late completion can write', async () => {
+    let cleanupCount = 0;
+    let lateWrites = 0;
+    const startedAt = Date.now();
+    const deadline = {
+      startedAt,
+      totalDeadlineMs: 1,
+      adapterDeadlineMs: 1,
+      deviceDeadlineMs: 1,
+      deadlineAt: startedAt + 1,
+      beginDeviceAcquisition: (_now: number) => undefined,
+      isValid: (
+        _phase:
+          | 'quiesce'
+          | 'acquire-adapter'
+          | 'acquire-device'
+          | 'rehydrate'
+          | 'compile-graph'
+          | 'publish'
+          | 'cleanup',
+        now: number,
+      ) => now < startedAt + 1,
+      elapsed: (now: number) => Math.max(0, now - startedAt),
+    };
+    const continuation = createRecoveryContinuation(deadline, () => {
+      cleanupCount += 1;
+    });
+
+    const outcome = await runRecoveryStep(
+      async (attemptToken) => {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        if (attemptToken?.isValid('compile-graph', Date.now())) lateWrites += 1;
+        return ok(undefined);
+      },
+      'compile-graph',
+      deadline,
+      Date.now,
+      continuation,
+    );
+
+    expect(outcome.kind).toBe('timeout');
+    if (outcome.kind === 'timeout') expect(outcome.timeout.cause.code).toBe('webgpu-runtime-error');
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(lateWrites).toBe(0);
+    expect(cleanupCount).toBe(1);
+  });
+});

package/src/__tests__/renderer-target-history-recovery.integration.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import { TaaHistoryStore } from '../temporal/taa-history-store';
+
+type RecoveryReceipt = {
+  readonly deviceGeneration: number;
+  readonly completed: boolean;
+};
+
+type RecoverableHistory = TaaHistoryStore & {
+  recoverForGeneration(deviceGeneration: number): void;
+};
+
+function recover(store: TaaHistoryStore, deviceGeneration: number): void {
+  (store as RecoverableHistory).recoverForGeneration(deviceGeneration);
+}
+
+function commit(store: TaaHistoryStore, receipt: RecoveryReceipt): void {
+  const attempt = store.begin('device-generation');
+  attempt.commit(receipt as never);
+}
+
+describe('M4 / m4_t2 — target history recovery keeps logical token', () => {
+  it('publishes uninitialized replacement storage with neutral fallback', () => {
+    const store = new TaaHistoryStore();
+    const token = (
+      store.inspect() as typeof store.inspect extends () => infer T ? T : never & { token: string }
+    ).token;
+
+    recover(store, 8);
+
+    expect(store.inspect()).toMatchObject({
+      token,
+      deviceGeneration: 8,
+      content: 'uninitialized',
+      fallback: 'neutral-texture',
+      valid: false,
+      requestVersion: 0,
+    });
+  });
+
+  it('raises history only for a matching completed receipt', () => {
+    const store = new TaaHistoryStore();
+    recover(store, 8);
+    const before = store.inspect();
+
+    commit(store, { deviceGeneration: 7, completed: true });
+    expect(store.inspect()).toMatchObject({
+      token: before.token,
+      deviceGeneration: 8,
+      content: 'uninitialized',
+      valid: false,
+      requestVersion: 0,
+    });
+
+    commit(store, { deviceGeneration: 8, completed: false });
+    expect(store.inspect().valid).toBe(false);
+
+    commit(store, { deviceGeneration: 8, completed: true });
+    expect(store.inspect()).toMatchObject({
+      token: before.token,
+      deviceGeneration: 8,
+      content: 'active',
+      valid: true,
+      requestVersion: 1,
+    });
+  });
+
+  it('does not invent once or on-demand requests during replacement', () => {
+    const store = new TaaHistoryStore();
+    recover(store, 9);
+    const inspection = store.inspect() as typeof store.inspect extends () => infer T
+      ? T
+      : never & {
+          requestVersion: number;
+        };
+
+    expect(inspection.requestVersion).toBe(0);
+    expect(inspection.content).toBe('uninitialized');
+  });
+});

package/src/__tests__/shader-manifest-fixture.ts

@@ -58,22 +58,19 @@ const standardPbrVariants = (() => {
   const variants = [];
   for (const cluster of [false, true]) {
     for (const storage of [false, true]) {
-      for (const transmission of [false, true]) {
-        for (const vertexColor of [false, true]) {
-          const defines = {
-            CLUSTER_FORWARD_AVAILABLE: cluster,
-            STORAGE_BUFFER_AVAILABLE: storage,
-            TRANSMISSION_AVAILABLE: transmission,
-            VERTEX_COLOR_AVAILABLE: vertexColor,
-          };
-          const sortedDefines = Object.entries(defines).sort(([left], [right]) =>
-            left < right ? -1 : left > right ? 1 : 0,
-          );
-          const definesKey = sortedDefines.every(([, value]) => value)
-            ? ''
-            : sortedDefines.map(([key, value]) => `${key}=${value}`).join('+');
-          variants.push({ definesKey, defines, composedWgsl: pbrWgsl });
-        }
+      for (const vertexColor of [false, true]) {
+        const defines = {
+          CLUSTER_FORWARD_AVAILABLE: cluster,
+          STORAGE_BUFFER_AVAILABLE: storage,
+          VERTEX_COLOR_AVAILABLE: vertexColor,
+        };
+        const sortedDefines = Object.entries(defines).sort(([left], [right]) =>
+          left < right ? -1 : left > right ? 1 : 0,
+        );
+        const definesKey = sortedDefines.every(([, value]) => value)
+          ? ''
+          : sortedDefines.map(([key, value]) => `${key}=${value}`).join('+');
+        variants.push({ definesKey, defines, composedWgsl: pbrWgsl });
       }
     }
   }

package/src/__tests__/shader-stage-surface.unit.test.ts

@@ -20,7 +20,7 @@ const fragmentConsumerSources = [
   pbrPipelineSource,
   iblPipelineCacheSource,
   readFileSync(new URL('../ibl/skylight-bind-group.ts', import.meta.url), 'utf8'),
-  readFileSync(new URL('../assembly/factory.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../assembly/webgpu-renderer.ts', import.meta.url), 'utf8'),
 ];
 
 describe('shader stage owner', () => {

package/src/__tests__/skin-motion-regression.unit.test.ts

@@ -45,6 +45,39 @@ describe('custom skinned mesh motion consumer contract', () => {
     expect(writes[1]?.data[12]).toBe(0.5);
   });
 
+  it('keeps stable uniform palette slices isolated across frame-pool resets', () => {
+    const device = {
+      limits: { maxUniformBufferBindingSize: 65536 },
+      createBuffer: () => ok({} as Buffer),
+      destroyBuffer: () => undefined,
+      queue: { writeBuffer: () => ok(undefined) },
+    } as unknown as RhiDevice;
+    const allocator = createSkinPaletteAllocator(device, 65536, false);
+    const first = allocator.allocateSliceFor('world:1', 1);
+    allocator.resetForFrame();
+    const second = allocator.allocateSliceFor('world:2', 1);
+
+    expect(second.buffer).not.toBe(first.buffer);
+  });
+
+  it('does not reuse a split storage range beyond its binding window', () => {
+    let bufferId = 0;
+    const device = {
+      limits: { maxStorageBufferBindingSize: 65536 },
+      createBuffer: () => ok({ id: bufferId++ } as unknown as Buffer),
+      queue: { writeBuffer: () => ok(undefined) },
+    } as unknown as RhiDevice;
+    const allocator = createSkinPaletteAllocator(device, 65536, true);
+
+    const full = allocator.allocateSliceFor('world:full', 255);
+    allocator.releaseSliceFor('world:full');
+    const firstSmall = allocator.allocateSliceFor('world:first', 1);
+    const secondSmall = allocator.allocateSliceFor('world:second', 1);
+
+    expect(firstSmall.buffer).toBe(full.buffer);
+    expect(secondSmall.buffer).not.toBe(full.buffer);
+  });
+
   it('prepares both URP and HDRP pbr-skin consumers with the skin-cluster contract', () => {
     const variants = selectSkinPrewarmVariants(
       {

package/src/__tests__/skinned-shadow-caster.test.ts

@@ -9,6 +9,7 @@ import {
   SHADOW_CASTER_SHADER_ID,
   shadowCasterVariantSet,
 } from '../pbr-pipeline.js';
+import { shadowShaderMap } from '../record/shadow-pass.js';
 
 describe('skinned shadow caster', () => {
   it('derives closed capability variants without changing the shader identity', () => {
@@ -52,8 +53,7 @@ describe('skinned shadow caster', () => {
     expect(shader).toContain('let skinMatrix = palette[');
     expect(record).toContain('entry.source.skin.byteOffset');
     expect(record).toContain("'shadow-pbr-skin-mesh'");
-    expect(builder).toContain("ctx.layoutKind === 'pbr-skin'");
-    expect(builder).toContain('? [...ctx.vertexBuffers]');
+    expect(builder).toContain('buffers: [...ctx.vertexBuffers]');
   });
 
   it('keeps mixed static and skinned shadow draws on matching variants and bindings', () => {
@@ -129,4 +129,32 @@ describe('skinned shadow caster', () => {
     );
     expect(recordSource).toContain('binding: 12');
   });
+
+  it('keeps the dispatch material handle, snapshot, and frame slot together', () => {
+    const paramSnapshot = { alphaClipThreshold: 0.4 };
+    const context = {
+      dispatch: [
+        {
+          renderableIndex: 4,
+          materialHandle: 42,
+          materialShaderId: 'forgeax::default-standard-pbr',
+          paramSnapshot,
+          tags: { LightMode: 'ShadowCaster' },
+        },
+      ],
+      validatedOrdered: [{ renderableIndex: 4 }],
+      materialSlotIndices: [[3, 7]],
+      materialSlots: Array.from({ length: 8 }, (_, slot) => ({
+        materialHandle: slot === 7 ? 42 : 11,
+      })),
+    } as never;
+
+    const bindings = shadowShaderMap(context);
+    expect(bindings.get(4)?.get(42)).toMatchObject({
+      materialHandle: 42,
+      materialShaderId: SHADOW_CASTER_SHADER_ID,
+      materialSlot: 7,
+      paramSnapshot,
+    });
+  });
 });

package/src/__tests__/standard-layer-projection.unit.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { Materials } from '../materials.js';
+
+describe('Standard pass projection', () => {
+  it('keeps default and custom base surfaces on the base pass family', () => {
+    const material = Materials.standard({ baseColor: [1, 1, 1, 1] });
+    expect(material.passes?.map((pass) => pass.name)).toEqual([
+      'forward',
+      'deferred',
+      'shadow-caster',
+    ]);
+  });
+
+  it('uses the same physical forward-only projection for a zero-factor declaration', () => {
+    const material = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 0,
+      clearcoatRoughness: 0,
+    });
+    expect(material.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+    expect(material.parameters?.some((parameter) => parameter.name === 'clearcoat')).toBe(true);
+  });
+});

package/src/__tests__/surface-adjacent-regressions.integration.test.ts

@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  projectStandardSurfacePasses,
+  type StandardSurfaceProjectionOptions,
+} from '../assembly/material/surface-projection';
+import { GPU_DRIVEN_RIGID_UNLIT_WGSL } from '../gpu-driven/production-raster';
+
+function shaderSource(name: string): string {
+  return readFileSync(
+    fileURLToPath(new URL(`../../../shader/src/${name}`, import.meta.url)),
+    'utf8',
+  );
+}
+
+const standard: StandardSurfaceProjectionOptions = {
+  surfaceModule: 'game_3d::rusted_iron_surface',
+  values: {},
+  geometryVariant: 'rigid',
+  lightingLane: 'direct',
+  alphaClip: true,
+};
+
+describe('Surface adjacent regressions', () => {
+  it('retains the default Standard pass family and provenance', () => {
+    const passes = projectStandardSurfacePasses(standard);
+    expect(passes.map((pass) => pass.name)).toEqual(['forward', 'deferred', 'shadow-caster']);
+    expect(
+      passes.every((pass) => pass.program.moduleSlots?.surface === standard.surfaceModule),
+    ).toBe(true);
+    expect(
+      passes.every(
+        (pass) =>
+          (pass.renderState?.tags as Readonly<Record<string, string>> | undefined)?.SurfaceKind ===
+          'standard',
+      ),
+    ).toBe(true);
+  });
+
+  it('keeps explicit full-custom pass ownership closed', () => {
+    const passes = projectStandardSurfacePasses({
+      ...standard,
+      surfaceKind: 'full-custom',
+      declaredPasses: ['forward'],
+    });
+    expect(passes.map((pass) => pass.name)).toEqual(['forward']);
+    expect(
+      (passes[0]?.renderState?.tags as Readonly<Record<string, string>> | undefined)?.SurfaceKind,
+    ).toBe('full-custom');
+  });
+
+  it('keeps skinning and GPU-driven siblings on their own shader owners', () => {
+    const skinned = shaderSource('default-standard-pbr-skin.wgsl');
+    expect(skinned).toContain('skinIndex');
+    expect(skinned).toContain('skinWeight');
+    expect(GPU_DRIVEN_RIGID_UNLIT_WGSL).toContain('@builtin(instance_index)');
+    expect(GPU_DRIVEN_RIGID_UNLIT_WGSL).not.toContain('surface_v1');
+  });
+});

package/src/__tests__/surface-standard-pipeline.browser.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { projectStandardSurfacePasses } from '../assembly/material/surface-projection';
+import { layerPlanFor, passFor, SURFACE_CASES } from './surface-standard-pipeline.fixture';
+
+describe('Standard Surface render projection contract', () => {
+  it('projects every published cell to its declared pass and Surface module', () => {
+    for (const surfaceCase of SURFACE_CASES) {
+      const passes = projectStandardSurfacePasses({
+        surfaceModule: surfaceCase.surfaceModule,
+        values: surfaceCase.material.values ?? {},
+        geometryVariant: 'rigid',
+        lightingLane: 'direct',
+        alphaClip: true,
+        layerPlan: layerPlanFor(surfaceCase),
+      });
+      expect(passes.some((entry) => entry.name === passFor(surfaceCase))).toBe(true);
+      expect(passes[0]?.program.moduleSlots?.surface).toBe(surfaceCase.surfaceModule);
+    }
+  });
+});