@forgeax/engine-render 0.1.29 → 0.1.31

package/src/__tests__/gpu-driven-view.unit.test.ts

@@ -10,6 +10,7 @@ const material = {
   baseColor: new Float32Array([1, 1, 1]),
   metallic: 0,
   roughness: 1,
+  materialShaderId: 'forgeax::default-standard-pbr',
 } as MaterialSnapshot;
 
 function snapshot(entityKey: number, x: number, resourceClass = 'plain'): RenderableSnapshot {

package/src/__tests__/gpu-pass-timing-browser-runner.ts

@@ -104,6 +104,21 @@ function drawTimingFrame(fixture: BrowserTimingFixture): {
   };
 }
 
+export async function observeBrowserGpuPassTimingDisabled() {
+  const fixture = await createBrowserTimingFixture(false);
+  try {
+    const { receipt } = drawTimingFrame(fixture);
+    const requested = await fixture.renderer.observe(receipt, { include: ['timings'] });
+    const omitted = await fixture.renderer.observe(receipt, { include: ['draws'] });
+    if (!requested.ok) throw requested.error;
+    if (!omitted.ok) throw omitted.error;
+    return { requested: requested.value, omitted: omitted.value };
+  } finally {
+    await fixture.renderer.dispose();
+    fixture.canvas.remove();
+  }
+}
+
 function adapterString(value: unknown): string | undefined {
   return typeof value === 'string' && value.length > 0 ? value : undefined;
 }

package/src/__tests__/gpu-pass-timing.browser.test.ts

@@ -1,9 +1,22 @@
 import { describe, expect, it } from 'vitest';
-import { runBrowserGpuPassTiming } from './gpu-pass-timing-browser-runner.js';
+import {
+  observeBrowserGpuPassTimingDisabled,
+  runBrowserGpuPassTiming,
+} from './gpu-pass-timing-browser-runner.js';
 
 const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
 
 describe.skipIf(!browserReady)('GPU pass timing Browser dev-server runner', () => {
+  it('returns the standard unavailable observation when GPU timing is disabled', async () => {
+    const { requested, omitted } = await observeBrowserGpuPassTimingDisabled();
+    expect(requested.timings).toMatchObject({
+      status: 'unavailable',
+      reason: { code: 'gpu-timing-not-enabled' },
+    });
+    expect(requested.timings).not.toHaveProperty('frame');
+    expect(omitted.timings).toBeUndefined();
+  });
+
   // The first live lavapipe renderer pair can exceed Vitest's 15s default while
   // the shader manifest and timestamp-query path are cold; keep this bound
   // local to the real WebGPU owner instead of weakening the global timeout.

package/src/__tests__/gpu-resource-scope.unit.test.ts

@@ -0,0 +1,71 @@
+import { err, ok, type RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { expect, it, vi } from 'vitest';
+import { DeviceScope } from '../device/device-scope';
+import { GpuBuffer, GpuTexture } from '../gpu-resource';
+
+it.each([
+  'buffer',
+  'texture',
+] as const)('keeps %s ownership on failed destruction and releases it after successful retry', async (kind) => {
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const scope = DeviceScope.create(1, 'gpu-resource');
+  const method = kind === 'buffer' ? 'destroyBuffer' : 'destroyTexture';
+  const original = device[method].bind(device);
+  const spy = vi
+    .spyOn(device, method)
+    .mockReturnValueOnce(
+      err(
+        new RhiError({ code: 'webgpu-runtime-error', expected: 'injected failure', hint: 'retry' }),
+      ),
+    );
+  const resource =
+    kind === 'buffer'
+      ? new GpuBuffer(device, device.createBuffer({ size: 64, usage: 8 }).unwrap(), scope)
+      : new GpuTexture(
+          device,
+          device
+            .createTexture({
+              size: [1, 1, 1],
+              format: 'rgba8unorm',
+              usage: 4,
+              textureBindingViewDimension: '2d',
+            })
+            .unwrap(),
+          scope,
+        );
+  expect(scope.resourceDelta()).toBe(1);
+  expect(resource.destroy().ok).toBe(false);
+  expect(resource.isDestroyed).toBe(false);
+  expect(scope.resourceDelta()).toBe(1);
+  spy.mockImplementation(original as RhiDevice[typeof method]);
+  expect(resource.destroy().ok).toBe(true);
+  expect(resource.isDestroyed).toBe(true);
+  expect(scope.resourceDelta()).toBe(0);
+  scope.retire();
+  expect(spy).toHaveBeenCalledTimes(2);
+  expect(resource.destroy().ok).toBe(false);
+  expect(scope.resourceDelta()).toBe(0);
+});
+
+it('cleans remaining resources in reverse order after an earlier resource was released', async () => {
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const scope = DeviceScope.create(1, 'gpu-resource-order');
+  const resources = Array.from(
+    { length: 3 },
+    () => new GpuBuffer(device, device.createBuffer({ size: 64, usage: 8 }).unwrap(), scope),
+  );
+  const handles: unknown[] = [];
+  vi.spyOn(device, 'destroyBuffer').mockImplementation((handle) => {
+    handles.push(handle);
+    return ok(undefined);
+  });
+  const [first, second, third] = resources;
+  if (first === undefined || second === undefined || third === undefined)
+    throw new Error('missing fixture resource');
+  second.destroy().unwrap();
+  scope.retire();
+  scope.dispose();
+  expect(handles).toEqual([second.handle, third.handle, first.handle]);
+  expect(scope.resourceDelta()).toBe(0);
+});

package/src/__tests__/gpu-scene.unit.test.ts

@@ -7,7 +7,7 @@ import { err } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { GpuScene } from '../gpu-scene';
 import { GPU_SCENE_LAYOUTS, gpuSceneFieldOffset } from '../gpu-scene-schema';
-import { packStandardPbrMaterialRow } from '../material-row';
+import { packMaterialProgramRow, packStandardPbrMaterialRow } from '../material-row';
 import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
 import type {
   ExtractedFrame,
@@ -176,6 +176,60 @@ describe('GpuScene', () => {
     ).toBeCloseTo(0.4);
   });
 
+  it('prefers extracted Standard PBR values over schema defaults', () => {
+    const row = packStandardPbrMaterialRow(createStandardPbrArtifactReceipt(), material);
+    const view = new DataView(row.buffer);
+    expect(
+      view.getFloat32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'baseColor'), true),
+    ).toBeCloseTo(0.25);
+    expect(
+      view.getFloat32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'metallic'), true),
+    ).toBeCloseTo(0.2);
+    expect(
+      view.getFloat32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'roughness'), true),
+    ).toBeCloseTo(0.8);
+  });
+
+  it('packs a custom schema into the same scene row page', () => {
+    const row = packMaterialProgramRow(
+      [
+        { name: 'tint', type: 'color' },
+        { name: 'roughness', type: 'f32' },
+      ],
+      {
+        ...material,
+        materialShaderId: 'game::custom-surface',
+        materialParamSchema: [
+          { name: 'tint', type: 'color' },
+          { name: 'roughness', type: 'f32' },
+        ],
+        paramSnapshot: { tint: [0.1, 0.2, 0.3, 1], roughness: 0.7 },
+      },
+    );
+    expect(row).toBeDefined();
+    if (row === undefined) return;
+    expect(row.byteLength).toBe(GPU_SCENE_LAYOUTS.material.stride);
+    expect(new DataView(row.buffer).getFloat32(0, true)).toBeCloseTo(0.1);
+    expect(new DataView(row.buffer).getFloat32(16, true)).toBeCloseTo(0.7);
+  });
+
+  it('writes the last vector in a 512-byte page and rejects overflow', () => {
+    const schema = Array.from({ length: 32 }, (_, index) => ({
+      name: `value${index}`,
+      type: 'vec4' as const,
+    }));
+    const row = packMaterialProgramRow(schema, {
+      ...material,
+      paramSnapshot: { value31: [7, 8, 9, 10] },
+    });
+    if (row === undefined) throw new Error('512-byte row missing');
+    expect(row.byteLength).toBe(512);
+    expect(Array.from(new Float32Array(row.buffer, 496, 4))).toEqual([7, 8, 9, 10]);
+    expect(
+      packMaterialProgramRow([...schema, { name: 'overflow', type: 'f32' }], material),
+    ).toBeUndefined();
+  });
+
   it('exposes GPU scene facts as exact temporal coverage', () => {
     const coverage = classifySceneDataCoverage({
       contributors: [{ id: 'gpu-scene', kind: 'exact' }],

package/src/__tests__/materials-standard-contract.unit.test.ts

@@ -149,6 +149,10 @@ describe('Materials.standard clearcoat public contract', () => {
         { slot: 2, sampler, view },
       ],
     );
-    expect(merged.slice(-6).map((entry) => entry.binding)).toEqual([26, 27, 28, 29, 30, 31]);
+    expect(
+      merged
+        .filter((entry) => entry.binding >= 26 && entry.binding < 46)
+        .map((entry) => entry.binding),
+    ).toEqual([26, 27, 28, 29, 30, 31]);
   });
 });

package/src/__tests__/mesh-submission-lifetime.unit.test.ts

@@ -2,6 +2,7 @@ import { World } from '@forgeax/engine-ecs';
 import { createBoxGeometry } from '@forgeax/engine-geometry';
 import { rhi } from '@forgeax/engine-rhi-null';
 import { expect, it } from 'vitest';
+import { DeviceScope } from '../device/device-scope';
 import { GpuResidencyCache } from '../device/gpu-residency';
 
 it('fences ordinary mesh submissions independently of candidates, including reversed completion', async () => {
@@ -15,6 +16,8 @@ it('fences ordinary mesh submissions independently of candidates, including reve
     },
     device.caps,
   );
+  const scope = DeviceScope.create(1, 'mesh-submission');
+  store.bindDeviceScope(scope);
   const world = new World();
   const mesh = createBoxGeometry(1, 1, 1).unwrap();
   const handle = world.allocSharedRef('MeshAsset', mesh);
@@ -44,10 +47,15 @@ it('fences ordinary mesh submissions independently of candidates, including reve
   finishSecond();
   await second;
   expect(original.vertexBuffer.isDestroyed).toBe(false);
+  expect(scope.resourceDelta()).toBe(4);
   finishFirst();
   await first;
   expect(original.vertexBuffer.isDestroyed).toBe(true);
+  expect(scope.resourceDelta()).toBe(2);
   expect(store.getMeshGpuHandles(handle, world)).toBe(replacement);
   expect(replacement.vertexBuffer.isDestroyed).toBe(false);
   store.destroyAll();
+  scope.retire();
+  expect(replacement.vertexBuffer.isDestroyed).toBe(true);
+  expect(scope.resourceDelta()).toBe(0);
 });

package/src/__tests__/morph-neutral-admission.unit.test.ts

@@ -0,0 +1,19 @@
+import type { MeshAsset } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { morphSnapshotFor } from '../render-system-extract-tail';
+
+it('idle morph authoring preserves the source stream; activating and clearing it changes admission', () => {
+  const mesh = {
+    vertices: new Float32Array(12),
+    morphTargets: [{ position: new Float32Array([1, 2, 3]) }],
+  } satisfies Pick<MeshAsset, 'vertices' | 'morphTargets'>;
+  const weights = new Float32Array([0]);
+  expect(morphSnapshotFor(mesh, weights)).toBeUndefined();
+  weights[0] = 0.25;
+  expect(morphSnapshotFor(mesh, weights)).toMatchObject({
+    weights: new Float32Array([0.25]),
+    targetCount: 1,
+  });
+  weights[0] = 0;
+  expect(morphSnapshotFor(mesh, weights)).toBeUndefined();
+});

package/src/__tests__/physical-clearcoat.integration.test.ts

@@ -78,7 +78,7 @@ describe('Standard clearcoat root contract', () => {
     // their canonical fixed slots (26, 27, 30, 31), followed by the
     // scene-index row at binding 46. Compacting the authored root here shifts WGSL IBL bindings and
     // causes Dawn to reject the pipeline before any pixels are submitted.
-    expect(descriptor.entries).toHaveLength(29);
+    expect(descriptor.entries).toHaveLength(30);
     expect(descriptor.entries.slice(0, 15).map((entry) => entry.binding)).toEqual(
       Array.from({ length: 15 }, (_, binding) => binding),
     );
@@ -89,6 +89,10 @@ describe('Standard clearcoat root contract', () => {
     expect(descriptor.entries.slice(24, 28).map((entry) => entry.binding)).toEqual([
       26, 27, 30, 31,
     ]);
+    expect(descriptor.entries[29]).toMatchObject({
+      binding: 47,
+      texture: { sampleType: 'float', viewDimension: 'cube' },
+    });
     expect(descriptor.entries[28]).toMatchObject({
       binding: 46,
       visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
@@ -118,6 +122,7 @@ describe('Standard clearcoat root contract', () => {
     expect(descriptor.entries.map((entry) => entry.binding)).toEqual([
       ...Array.from({ length: 10 }, (_, binding) => binding),
       46,
+      47,
     ]);
   });
 });

package/src/__tests__/post-process-error-policy-owner.unit.test.ts

@@ -13,6 +13,7 @@ const expectedCodes = [
   'fullscreen-input-not-found',
   'ssao-radius-non-positive',
   'ssao-bias-negative',
+  'ssao-parameter-invalid',
   'params-size-mismatch',
   'params-update-size-mismatch',
 ] as const satisfies readonly PostProcessErrorCode[];
@@ -38,9 +39,9 @@ const evidence = [
       detail: { id: 'pkg::missing' },
     }),
     expected: 'typed fullscreen plan references a registered post-process id',
-    hint: "no post-process is registered for id 'pkg::missing'. Register 'pkg::missing' with the feature host ({source, reads?}), then reference it from a typed fullscreen RenderFeaturePlan.",
+    hint: "no post-process is registered for id 'pkg::missing'. For Engine-owned effects, rebuild the shader manifest with that Engine entry enabled. For custom effects, register 'pkg::missing' with the feature host ({source, reads?}), then reference it from a typed fullscreen RenderFeaturePlan.",
     message:
-      "post-process: post-process-not-found (no post-process is registered for id 'pkg::missing'. Register 'pkg::missing' with the feature host ({source, reads?}), then reference it from a typed fullscreen RenderFeaturePlan.)",
+      "post-process: post-process-not-found (no post-process is registered for id 'pkg::missing'. For Engine-owned effects, rebuild the shader manifest with that Engine entry enabled. For custom effects, register 'pkg::missing' with the feature host ({source, reads?}), then reference it from a typed fullscreen RenderFeaturePlan.)",
   },
   {
     code: 'fullscreen-input-not-found',
@@ -100,9 +101,9 @@ const evidence = [
 ];
 
 describe('PostProcessError policy ownership', () => {
-  it('preserves the exact seven-code vocabulary owned by this policy', () => {
-    expect(expectedCodes).toHaveLength(7);
-    expect(new Set(expectedCodes).size).toBe(7);
+  it('preserves the closed parameter-validation vocabulary owned by this policy', () => {
+    expect(expectedCodes).toHaveLength(8);
+    expect(new Set(expectedCodes).size).toBe(8);
     expectTypeOf<PostProcessErrorCode>().toEqualTypeOf<ExpectedCodeUnion>();
     expectTypeOf<ExpectedCodeUnion>().toEqualTypeOf<PostProcessErrorCode>();
     const acceptsCode = (code: PostProcessErrorCode): PostProcessErrorCode => code;

package/src/__tests__/prepared-gpu-driven-pbr.integration.test.ts

@@ -1,7 +1,17 @@
+import { createBoxGeometry } from '@forgeax/engine-geometry';
 import { vec3 } from '@forgeax/engine-math';
-import { createStandardPbrArtifactReceipt } from '@forgeax/engine-shader';
+import {
+  createMaterialProgramArtifactReceipt,
+  createStandardPbrArtifactReceipt,
+  type ParamSchemaEntry,
+} from '@forgeax/engine-shader';
+import type { MeshAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { buildGpuDrivenDraws, resolvePreparedGpuDrivenDraw } from '../extract/gpu-driven';
+import {
+  buildGpuDrivenDraws,
+  gpuDrivenMaterialArtifactKey,
+  resolvePreparedGpuDrivenDraw,
+} from '../extract/gpu-driven';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 
 const textureNames = [
@@ -52,7 +62,9 @@ function snapshot(
   };
 }
 
-function geometry(source: ReturnType<typeof artifact>) {
+function geometry(source: {
+  readonly receipt: ReturnType<typeof createStandardPbrArtifactReceipt>;
+}) {
   return {
     identity: 'canonical-pbr-geometry',
     vertexInputs: source.receipt.vertexInputs,
@@ -61,8 +73,8 @@ function geometry(source: ReturnType<typeof artifact>) {
   };
 }
 
-function artifact() {
-  const receipt = createStandardPbrArtifactReceipt();
+function artifact(vertexColorAvailable = false) {
+  const receipt = createStandardPbrArtifactReceipt(false, vertexColorAvailable);
   return {
     material: 'forgeax::default-standard-pbr',
     pass: 'forward',
@@ -75,7 +87,174 @@ function artifact() {
   };
 }
 
+function customArtifact() {
+  const schema = [
+    { name: 'tint', type: 'color' },
+    { name: 'roughnessBias', type: 'f32' },
+  ] as const satisfies readonly ParamSchemaEntry[];
+  const receipt = createMaterialProgramArtifactReceipt({
+    schema,
+    directEntry: 'vs_main',
+    sceneIndexEntry: 'vs_scene_index',
+    vertexInputs: [
+      { semantic: 'position', location: 0, format: 'float32x3' },
+      { semantic: 'normal', location: 1, format: 'float32x3' },
+      { semantic: 'uv', location: 2, format: 'float32x2' },
+      { semantic: 'tangent', location: 3, format: 'float32x4' },
+    ],
+  });
+  return {
+    material: 'game::custom-surface',
+    pass: 'forward',
+    wgsl: 'producer-composed-custom-surface',
+    layoutIdentity: receipt.reflection.layoutIdentity,
+    bindings: [],
+    deps: ['game::custom-surface'],
+    vertexInputs: receipt.vertexInputs.map((input) => ({ ...input })),
+    receipt,
+  };
+}
+
 describe('prepared Standard PBR producer-to-record integration', () => {
+  it.each([
+    'forgeax::default-standard-pbr',
+    'physical-material::standard-clearcoat-factor-r',
+  ])('distinguishes canonical roots from legacy direct-only aliases: %s', (materialShaderId) => {
+    const source = { ...material(), materialShaderId };
+    const draws = buildGpuDrivenDraws({
+      mesh: createBoxGeometry(1, 1, 1).unwrap(),
+      materials: [source],
+      fallbackMaterial: source,
+      baseSnapshot: snapshot(source),
+      getMaterialShaderArtifact: () => undefined,
+    });
+    expect(draws).toHaveLength(1);
+    expect(draws[0]?.preparationError?.code).toBe(
+      materialShaderId.startsWith('forgeax::') ? 'missing-material-receipt' : undefined,
+    );
+  });
+
+  it('requires the published scene-index artifact for a custom surface', () => {
+    const source: MaterialSnapshot = {
+      ...material(),
+      materialShaderId: 'game::custom-surface-direct',
+      materialProgramKeys: { forward: 'game::custom-surface-direct' },
+      materialSceneIndexProgramKeys: {
+        forward: { specializationKey: 'game::custom-surface-scene', pass: 'forward' },
+      },
+    };
+    const requested: string[] = [];
+    const draws = buildGpuDrivenDraws({
+      mesh: createBoxGeometry(1, 1, 1).unwrap(),
+      materials: [source],
+      fallbackMaterial: source,
+      baseSnapshot: snapshot(source),
+      getMaterialShaderArtifact: (key) => {
+        requested.push(key);
+        return undefined;
+      },
+    });
+    expect(requested).toEqual(['game::custom-surface-scene']);
+    expect(draws).toHaveLength(1);
+    expect(draws[0]?.preparationError?.code).toBe('missing-material-receipt');
+  });
+
+  it('prepares a COLOR_0 geometry with the matching published receipt', () => {
+    const source = artifact(true);
+    const result = resolvePreparedGpuDrivenDraw({
+      snapshot: snapshot(),
+      artifact: source,
+      geometry: geometry(source),
+      generation: source.receipt.generation,
+      draw: snapshot().gpuDrivenDraws?.[0] as NonNullable<
+        RenderableSnapshot['gpuDrivenDraws']
+      >[number],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.receiptIdentity).toBe(source.receipt.receiptIdentity);
+    expect(result.value.vertexInputs).toContainEqual({
+      semantic: 'color',
+      location: 13,
+      format: 'float32x4',
+    });
+  });
+
+  it('selects the colored receipt while extracting a real colored mesh draw', () => {
+    const coloredSource = artifact(true);
+    const coloredMesh: MeshAsset = {
+      kind: 'mesh',
+      vertices: new Float32Array(36),
+      indices: new Uint16Array([0, 1, 2]),
+      attributes: {
+        position: new Float32Array(9),
+        normal: new Float32Array(9),
+        uv: new Float32Array(6),
+        tangent: new Float32Array(12),
+        color: new Float32Array(12),
+      },
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          materialSlot: 0,
+          topology: 'triangle-list',
+        },
+      ],
+      materialSlots: [{ slotName: 'default' }],
+    };
+    const selectedColorFacts: boolean[] = [];
+    const draws = buildGpuDrivenDraws({
+      mesh: coloredMesh,
+      materials: [material()],
+      fallbackMaterial: material(),
+      baseSnapshot: snapshot(),
+      getMaterialShaderArtifact: (_materialShaderId, request) => {
+        selectedColorFacts.push(request?.vertexColorAvailable === true);
+        return coloredSource;
+      },
+    });
+
+    expect(selectedColorFacts).toEqual([true]);
+    expect(draws).toHaveLength(1);
+    expect(draws[0]?.prepared?.vertexInputs).toContainEqual({
+      semantic: 'color',
+      location: 13,
+      format: 'float32x4',
+    });
+    expect(draws[0]?.preparationError).toBeUndefined();
+  });
+
+  it('keeps colored and colorless receipts on distinct production identities', () => {
+    const plain = artifact(false);
+    const colored = artifact(true);
+    const plainKey = gpuDrivenMaterialArtifactKey({
+      material: plain.material,
+      deformation: 'rigid',
+      receiptIdentity: plain.receipt.receiptIdentity,
+      receiptGeneration: plain.receipt.generation,
+    });
+    const coloredKey = gpuDrivenMaterialArtifactKey({
+      material: colored.material,
+      deformation: 'rigid',
+      receiptIdentity: colored.receipt.receiptIdentity,
+      receiptGeneration: colored.receipt.generation,
+    });
+
+    expect(plain.receipt.vertexInputs).not.toContainEqual(
+      expect.objectContaining({ semantic: 'color', location: 13 }),
+    );
+    expect(colored.receipt.vertexInputs).toContainEqual({
+      semantic: 'color',
+      location: 13,
+      format: 'float32x4',
+    });
+    expect(plain.receipt.receiptIdentity).not.toBe(colored.receipt.receiptIdentity);
+    expect(plainKey).not.toBe(coloredKey);
+  });
+
   it('carries one producer receipt to direct and scene-index preparation', () => {
     const source = artifact();
     const result = resolvePreparedGpuDrivenDraw({
@@ -224,4 +403,36 @@ describe('prepared Standard PBR producer-to-record integration', () => {
     });
     expect(result.ok).toBe(true);
   });
+
+  it('admits a producer-backed custom material without a Standard shader name', () => {
+    const source = customArtifact();
+    const customMaterial: MaterialSnapshot = {
+      ...material(),
+      materialShaderId: source.material,
+      materialParamSchema: [
+        { name: 'tint', type: 'color' },
+        { name: 'roughnessBias', type: 'f32' },
+      ],
+      paramSnapshot: { tint: [0.8, 0.25, 0.1, 1], roughnessBias: 0.12 },
+      textureHandles: undefined,
+      samplerHandles: undefined,
+    };
+    const baseSnapshot = snapshot(customMaterial);
+    const result = resolvePreparedGpuDrivenDraw({
+      snapshot: baseSnapshot,
+      artifact: source,
+      geometry: geometry(source),
+      generation: source.receipt.generation,
+      draw: baseSnapshot.gpuDrivenDraws?.[0] as NonNullable<
+        RenderableSnapshot['gpuDrivenDraws']
+      >[number],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.identity.material).toBe('game::custom-surface');
+    expect(result.value.materialRow.byteLength).toBe(512);
+    expect(result.value.materialRow.fields).toEqual(['tint', 'roughnessBias']);
+    expect(result.value.sceneIndexEntry).toBe('vs_scene_index');
+  });
 });

package/src/__tests__/reflection-fallback-async-publication.unit.test.ts

@@ -3,10 +3,12 @@ import type { RenderSystemInternals } from '../record/render-context';
 import { ReflectionProbeRecordOwner } from '../reflection/record-owner';
 import type { SkylightSnapshot } from '../render-system-extract';
 
-function fixture() {
+function fixture(captureReadback = true) {
   const internals = {
     device: { caps: { rgba16floatRenderable: true } },
     deviceScope: { owner: 'test', generation: 0 },
+    assets: { catalogEpoch: 0 },
+    captureReflectionFallbackReadback: captureReadback,
   } as unknown as RenderSystemInternals;
   const owner = new ReflectionProbeRecordOwner(internals);
   const stage = (frame: number, source = 1) =>
@@ -101,4 +103,69 @@ describe('fallback asynchronous publication', () => {
       projectionGeneration: 1,
     });
   });
+
+  it('publishes changing sources after GPU completion without requesting pixel readback', async () => {
+    const { owner, stage } = fixture(false);
+    for (let frame = 1; frame <= 10; frame++) {
+      let finish!: () => void;
+      const completed = new Promise<void>((resolve) => {
+        finish = resolve;
+      });
+      // biome-ignore lint/complexity/useLiteralKeys: Exercise the real completed-output boundary.
+      const publication = owner['completeSubmission'](true, stage(frame, frame), completed, {
+        frameId: frame,
+        format: 'rgba16float',
+        size: { width: 1, height: 1 },
+        graphGeneration: 1,
+        textureIdentity: frame,
+      });
+      expect(owner.inspect().reflectionFallback.frameId).not.toBe(frame);
+      finish();
+      await publication;
+      expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'active', frameId: frame });
+      expect(owner.inspect().reflectionFallbackReadback).toBeUndefined();
+      expect(owner.inspect().reflectionFallback).not.toHaveProperty('linearHdr');
+      expect(owner.inspect().reflectionFallbackInspection.failureCode).toBeUndefined();
+    }
+  });
+
+  it('does not publish non-neutral source metadata without an executed output', async () => {
+    const { owner, stage } = fixture(false);
+    // biome-ignore lint/complexity/useLiteralKeys: Missing graph output must remain fail-closed.
+    await owner['completeSubmission'](true, stage(1), Promise.resolve());
+    expect(owner.inspect().reflectionFallback.state).not.toBe('active');
+    expect(owner.inspect().reflectionFallbackInspection.failureCode).toBe(
+      'reflection-fallback-output-missing',
+    );
+  });
+
+  it('requires new mapped proof after an asset catalog replacement', async () => {
+    const { owner, stage, complete, internals } = fixture();
+    await complete(stage(1), 1);
+    Object.assign(internals.assets, { catalogEpoch: 1 });
+    const replacement = stage(2);
+    // biome-ignore lint/complexity/useLiteralKeys: A changed catalog must not reuse the old source proof.
+    await owner['completeSubmission'](true, replacement, Promise.resolve());
+    expect(owner.inspect().reflectionFallback.state).not.toBe('active');
+    expect(owner.inspect().reflectionFallbackInspection.failureCode).toBe(
+      'reflection-fallback-output-missing',
+    );
+    await complete(replacement, 2);
+    expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'active', frameId: 2 });
+    expect(owner.inspect().reflectionFallbackReadback?.frameId).toBe(2);
+  });
+
+  it('requires fresh readback to promote a failed source-identical submission from LKG', async () => {
+    const { owner, stage, complete } = fixture();
+    await complete(stage(1), 1);
+    // biome-ignore lint/complexity/useLiteralKeys: Fail at the real submission owner boundary.
+    await owner['completeSubmission'](false, stage(2), Promise.resolve());
+    expect(owner.inspect().reflectionFallback.state).toBe('lkg');
+    const retry = stage(3);
+    // biome-ignore lint/complexity/useLiteralKeys: An old proof must not turn a failed publication active again.
+    await owner['completeSubmission'](true, retry, Promise.resolve());
+    expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'lkg', frameId: 1 });
+    await complete(retry, 3);
+    expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'active', frameId: 3 });
+  });
 });