@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/render-scene-resource-updates.integration.test.ts

@@ -0,0 +1,214 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { expect, it } from 'vitest';
+import {
+  Camera,
+  DirectionalLight,
+  MeshFilter,
+  MeshRenderer,
+  MotionBlur,
+  PointLight,
+  Skylight,
+  Visibility,
+  VisibilityStateValue,
+} from '../components';
+import { extractFrames } from '../render-system-extract';
+import {
+  type PersistentRenderCandidateRequest,
+  PersistentRenderScene,
+} from '../scene/render-scene';
+
+it('refreshes frame resources without rebuilding retained geometry, including mixed edits', () => {
+  const world = new World();
+  registerPropagateTransforms(world);
+  const camera = world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    )
+    .unwrap();
+  const mesh = world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+    )
+    .unwrap();
+  const sun = world
+    .spawn({ component: DirectionalLight, data: { intensity: 1, direction: [0, -1, 0] } })
+    .unwrap();
+  const lamp = world
+    .spawn(
+      { component: Transform, data: { pos: [1, 2, 3] } },
+      { component: PointLight, data: { intensity: 2, range: 10 } },
+    )
+    .unwrap();
+  const sky = world.spawn({ component: Skylight, data: { intensity: 0.1 } }).unwrap();
+  world.update(0).unwrap();
+  const lease = createRenderReadLease(world);
+  const scene = new PersistentRenderScene();
+  const requests: PersistentRenderCandidateRequest[] = [];
+  const build = (request: PersistentRenderCandidateRequest) => {
+    requests.push(request);
+    return extractFrames([world], 0, undefined, undefined, scene.materialSnapshotCacheStore(), {
+      cull: 'none',
+      retainHidden: true,
+      renderables: request,
+    });
+  };
+  const draw = () =>
+    scene.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, build, [lease]);
+  try {
+    draw();
+    requests.length = 0;
+    const edits = [
+      () => world.set(camera, Camera, { exposure: 1.5, aspect: 1.25 }).unwrap(),
+      () => world.set(sun, DirectionalLight, { intensity: 3, direction: [0.5, -1, 0] }).unwrap(),
+      () => world.set(lamp, PointLight, { intensity: 4, range: 7 }).unwrap(),
+      () => world.set(sky, Skylight, { intensity: 0.2 }).unwrap(),
+      () =>
+        world.addComponent(camera, { component: MotionBlur, data: { shutterAngle: 180 } }).unwrap(),
+      () => world.removeComponent(camera, MotionBlur).unwrap(),
+      () => {
+        world.set(camera, Camera, { exposure: 2 }).unwrap();
+        world.set(mesh, Transform, { pos: [0.25, 0, 0] }).unwrap();
+      },
+      () => world.despawn(lamp).unwrap(),
+    ];
+    for (const edit of edits) {
+      edit();
+      world.update(0).unwrap();
+      const frame = draw();
+      const oracle = extractFrames([world], 0);
+      expect(frame.cameras).toEqual(oracle.cameras);
+      expect(frame.lights).toEqual(oracle.lights);
+      expect(frame.skylight).toEqual(oracle.skylight);
+      expect(frame.renderables.map((row) => [row.entityKey, [...row.transform.world]])).toEqual(
+        oracle.renderables.map((row) => [row.entityKey, [...row.transform.world]]),
+      );
+      expect(requests).not.toContain('full');
+      expect(scene.inspect().fullRebuilds).toBe(1);
+      requests.length = 0;
+    }
+  } finally {
+    lease.dispose();
+    scene.dispose();
+  }
+});
+
+it('retries consumed transforms when a mixed source publication fails', () => {
+  const world = new World();
+  registerPropagateTransforms(world);
+  world
+    .spawn({ component: Transform, data: { pos: [0, 0, 5] } }, { component: Camera, data: {} })
+    .unwrap();
+  const spawnMesh = () =>
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        { component: MeshRenderer, data: {} },
+      )
+      .unwrap();
+  const moved = spawnMesh();
+  const content = spawnMesh();
+  world.update(0).unwrap();
+  const lease = createRenderReadLease(world);
+  const scene = new PersistentRenderScene();
+  let failPartial = false;
+  const build = (request: PersistentRenderCandidateRequest) => {
+    if (failPartial && typeof request === 'object') {
+      failPartial = false;
+      throw new Error('source publication failed');
+    }
+    return extractFrames([world], 0, undefined, undefined, scene.materialSnapshotCacheStore(), {
+      cull: 'none',
+      retainHidden: true,
+      renderables: request,
+    });
+  };
+  const draw = () =>
+    scene.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, build, [lease]);
+  try {
+    draw();
+    world.set(moved, Transform, { pos: [2, 0, 0] }).unwrap();
+    world.set(content, MeshRenderer, { castShadow: false }).unwrap();
+    world.update(0).unwrap();
+    failPartial = true;
+    expect(draw).toThrow('source publication failed');
+    const recovered = draw();
+    const oracle = extractFrames([world], 0, undefined, undefined, undefined, {
+      cull: 'none',
+      retainHidden: true,
+    });
+    expect(recovered.renderables.map((row) => [row.entityKey, [...row.transform.world]])).toEqual(
+      oracle.renderables.map((row) => [row.entityKey, [...row.transform.world]]),
+    );
+    expect(scene.inspect().fullRebuilds).toBe(1);
+  } finally {
+    lease.dispose();
+    scene.dispose();
+  }
+});
+
+it('keeps untouched World hidden reports during partial edits and removals', () => {
+  const worlds = [new World(), new World()];
+  const entities = worlds.map((world) => {
+    registerPropagateTransforms(world);
+    const entity = world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        { component: MeshRenderer, data: {} },
+        { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+      )
+      .unwrap();
+    world.update(0).unwrap();
+    return entity;
+  });
+  const leases = worlds.map((world) => createRenderReadLease(world));
+  const [firstWorld, secondWorld] = worlds;
+  const [firstEntity, secondEntity] = entities;
+  if (
+    firstWorld === undefined ||
+    secondWorld === undefined ||
+    firstEntity === undefined ||
+    secondEntity === undefined
+  )
+    throw new Error('expected two Worlds and entities');
+  const scene = new PersistentRenderScene();
+  const options = { cull: 'none', retainHidden: true } as const;
+  const build = (request: PersistentRenderCandidateRequest) =>
+    extractFrames(worlds, 0, undefined, undefined, scene.materialSnapshotCacheStore(), {
+      ...options,
+      renderables: request,
+    });
+  const check = () => {
+    const frame = scene.extractComposition(
+      worlds,
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      build,
+      leases,
+    );
+    const oracle = extractFrames(worlds, 0, undefined, undefined, undefined, options);
+    const hidden = (value: typeof frame) =>
+      value.hiddenEntityReports.map((report) => `${report.world.identity}:${report.entity}`).sort();
+    expect(hidden(frame)).toEqual(hidden(oracle));
+    expect(frame.visibilityStats).toEqual(oracle.visibilityStats);
+  };
+  try {
+    check();
+    firstWorld.set(firstEntity, Visibility, { state: VisibilityStateValue.visible }).unwrap();
+    firstWorld.update(0).unwrap();
+    check();
+    secondWorld.despawn(secondEntity).unwrap();
+    secondWorld.update(0).unwrap();
+    check();
+  } finally {
+    for (const lease of leases) lease.dispose();
+    scene.dispose();
+  }
+});

package/src/__tests__/render-scene-skin-lifecycle.integration.test.ts

@@ -0,0 +1,173 @@
+import { AssetRegistry, HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { createRenderReadLease, type RenderReadLease } from '@forgeax/engine-ecs/projection';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import type { ShaderRegistry } from '@forgeax/engine-shader';
+import { Skin } from '@forgeax/engine-skinning';
+import type { Handle, SkeletonAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createSkinPaletteOwner } from '../assembly/skin-palette-owner';
+import { MeshFilter, MeshRenderer } from '../components';
+import { type ExtractedFrame, extractFrames } from '../render-system-extract';
+import {
+  type PersistentRenderCandidateRequest,
+  PersistentRenderScene,
+} from '../scene/render-scene';
+
+type SkinWorld = {
+  readonly world: World;
+  readonly joint: EntityHandle;
+  readonly renderable: EntityHandle;
+};
+
+function makeSkeleton(world: World): Handle<'SkeletonAsset', 'shared'> {
+  const inverseBindMatrices = new Float32Array(16);
+  inverseBindMatrices[0] = 1;
+  inverseBindMatrices[5] = 1;
+  inverseBindMatrices[10] = 1;
+  inverseBindMatrices[15] = 1;
+  return world.allocSharedRef<'SkeletonAsset', SkeletonAsset>('SkeletonAsset', {
+    kind: 'skeleton',
+    inverseBindMatrices,
+    jointCount: 1,
+  });
+}
+
+function makeSkinWorld(): SkinWorld {
+  const world = new World();
+  registerPropagateTransforms(world);
+  const skeleton = makeSkeleton(world);
+  const joint = world.spawn({ component: Transform, data: {} }).unwrap() as EntityHandle;
+  const renderable = world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Skin, data: { skeleton, joints: new Uint32Array([joint as number]) } },
+    )
+    .unwrap() as EntityHandle;
+  world.update(0).unwrap();
+  return { world, joint, renderable };
+}
+
+function skinFor(frame: ExtractedFrame, worldId: number, entity: EntityHandle) {
+  return frame.renderables.find(
+    (snapshot) => snapshot.worldId === worldId && snapshot.entityKey === entity,
+  )?.skin;
+}
+
+describe('PersistentRenderScene skin palette lifecycle', () => {
+  it('preserves untouched partial palettes, none scope, reorder identity, and retires removed Skin', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const allocator = createSkinPaletteOwner(device, true);
+    const assets = new AssetRegistry({} as unknown as ShaderRegistry);
+    const first = makeSkinWorld();
+    const second = makeSkinWorld();
+    let worlds: readonly World[] = [first.world, second.world];
+    let leases: readonly RenderReadLease[] = worlds.map((world) => createRenderReadLease(world));
+    const owner = { cameraOwner: 0, resourceOwner: 0 } as const;
+    const scene = new PersistentRenderScene();
+    const requests: PersistentRenderCandidateRequest[] = [];
+    const build = (request: PersistentRenderCandidateRequest): ExtractedFrame => {
+      requests.push(request);
+      return extractFrames(
+        worlds,
+        owner,
+        assets,
+        { skinPaletteAllocator: allocator },
+        scene.materialSnapshotCacheStore(),
+        { cull: 'none', retainHidden: true, renderables: request },
+      );
+    };
+    const draw = (): ExtractedFrame => scene.extractComposition(worlds, owner, 0, build, leases);
+
+    try {
+      const initial = draw();
+      const firstInitial = skinFor(initial, 0, first.renderable);
+      const secondInitial = skinFor(initial, 1, second.renderable);
+      expect(firstInitial).toBeDefined();
+      expect(secondInitial).toBeDefined();
+      expect(firstInitial?.identity).not.toBe(secondInitial?.identity);
+      const firstBuffer = firstInitial?.buffer;
+      const firstOffset = firstInitial?.byteOffset;
+      const secondBuffer = secondInitial?.buffer;
+      const secondOffset = secondInitial?.byteOffset;
+      expect(firstBuffer).toBeDefined();
+      expect(secondBuffer).toBeDefined();
+      expect(firstOffset).toBe(0);
+      expect(secondOffset).toBe(256);
+
+      requests.length = 0;
+      first.world.set(first.joint, Transform, { pos: [1, 0, 0] }).unwrap();
+      first.world.update(0).unwrap();
+      const firstPartial = draw();
+      const firstPartialRequest = requests.find(
+        (request): request is Extract<PersistentRenderCandidateRequest, { kind: 'partial' }> =>
+          typeof request === 'object',
+      );
+      expect(firstPartialRequest).toBeDefined();
+      expect(firstPartialRequest?.entitiesByWorld[0]?.has(first.renderable as number)).toBe(true);
+      expect(
+        firstPartialRequest?.entitiesByWorld[1]?.has(second.renderable as number) ?? false,
+      ).toBe(false);
+      expect(skinFor(firstPartial, 1, second.renderable)?.buffer).toBe(secondBuffer);
+      expect(skinFor(firstPartial, 1, second.renderable)?.byteOffset).toBe(secondOffset);
+
+      // Resource-only publication must not reconcile the identity set or
+      // release either persistent palette.
+      const none = extractFrames(
+        worlds,
+        owner,
+        assets,
+        { skinPaletteAllocator: allocator },
+        scene.materialSnapshotCacheStore(),
+        { cull: 'none', retainHidden: true, renderables: 'none' },
+      );
+      expect(none.renderables).toHaveLength(0);
+
+      // Visit the previously untouched entity after the partial and none
+      // scopes. Reusing its exact receipt proves its allocation survived both.
+      second.world.set(second.joint, Transform, { pos: [2, 0, 0] }).unwrap();
+      second.world.update(0).unwrap();
+      const secondPartial = draw();
+      expect(skinFor(secondPartial, 0, first.renderable)?.buffer).toBe(firstBuffer);
+      expect(skinFor(secondPartial, 0, first.renderable)?.byteOffset).toBe(firstOffset);
+      expect(skinFor(secondPartial, 1, second.renderable)?.buffer).toBe(secondBuffer);
+      expect(skinFor(secondPartial, 1, second.renderable)?.byteOffset).toBe(secondOffset);
+
+      // A full rebuild after worlds[] reorder must retain each World's palette
+      // identity. Entity keys intentionally start at the same value in both
+      // independent Worlds, so an index-derived key would alias or move them.
+      worlds = [second.world, first.world];
+      leases = [leases[1] as RenderReadLease, leases[0] as RenderReadLease];
+      const reordered = draw();
+      expect(skinFor(reordered, 0, second.renderable)?.buffer).toBe(secondBuffer);
+      expect(skinFor(reordered, 0, second.renderable)?.byteOffset).toBe(secondOffset);
+      expect(skinFor(reordered, 1, first.renderable)?.buffer).toBe(firstBuffer);
+      expect(skinFor(reordered, 1, first.renderable)?.byteOffset).toBe(firstOffset);
+
+      // Removing Skin leaves the renderable slot alive, but the producer must
+      // retire its palette during the selected partial extraction.
+      first.world.removeComponent(first.renderable, Skin).unwrap();
+      first.world.update(0).unwrap();
+      const afterSkinRemoval = draw();
+      expect(skinFor(afterSkinRemoval, 1, first.renderable)).toBeUndefined();
+      expect(skinFor(afterSkinRemoval, 0, second.renderable)?.buffer).toBe(secondBuffer);
+      expect(skinFor(afterSkinRemoval, 0, second.renderable)?.byteOffset).toBe(secondOffset);
+
+      await device.queue.onSubmittedWorkDone();
+      const replacement = allocator.allocatePersistentSlice({
+        identity: 'test-replacement',
+        generation: 1,
+        jointCount: 1,
+      });
+      expect(replacement.byteOffset).toBe(firstOffset);
+    } finally {
+      for (const lease of leases) lease.dispose();
+      scene.dispose();
+      allocator.dispose();
+    }
+  });
+});

package/src/__tests__/render-scene-temporal-retry.unit.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest';
+import { type InstanceCollectionSnapshot, InstanceCollectionStore } from '../instances';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+
+const material = {} as MaterialSnapshot;
+
+function world(translationX: number): Float32Array {
+  const result = new Float32Array(16);
+  result[0] = 1;
+  result[5] = 1;
+  result[10] = 1;
+  result[15] = 1;
+  result[12] = translationX;
+  return result;
+}
+
+function matrices(count: number, translationX: number): Float32Array {
+  const result = new Float32Array(count * 16);
+  for (let index = 0; index < count; index += 1) {
+    result.set(world(translationX + index), index * 16);
+  }
+  return result;
+}
+
+function snapshot(
+  entityKey: number,
+  translationX: number,
+  collection?: InstanceCollectionSnapshot,
+): RenderableSnapshot {
+  const instances =
+    collection === undefined
+      ? undefined
+      : {
+          ...collection,
+          instanceCount: collection.count,
+          cacheKey: entityKey,
+          archVersion: 0,
+        };
+  return {
+    assetHandle: 1,
+    transform: { world: world(translationX) },
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    ...(instances === undefined ? {} : { instances }),
+  };
+}
+
+function updateSnapshot(value: RenderableSnapshot) {
+  return {
+    kind: 'update' as const,
+    worldId: value.worldId,
+    entityKey: value.entityKey,
+    snapshot: value,
+  };
+}
+
+function updateInstances(value: RenderableSnapshot) {
+  if (value.instances === undefined) throw new Error('expected Instances payload');
+  return {
+    kind: 'update' as const,
+    worldId: value.worldId,
+    entityKey: value.entityKey,
+    instances: value.instances,
+  };
+}
+
+function submit(scene: RenderScene, entityKey: number): void {
+  const capture = scene.captureSubmission([{ worldId: 0, entityKey }]);
+  scene.commitSubmission(capture);
+}
+
+describe('RenderScene temporal retry boundary', () => {
+  it('keeps the last committed root transform across a failed root-only frame and retry', () => {
+    const scene = new RenderScene();
+    scene.setTemporalTracking(true);
+    scene.apply([updateSnapshot(snapshot(7, 1))]);
+    submit(scene, 7);
+
+    scene.apply([{ kind: 'update', worldId: 0, entityKey: 7, world: world(9) }]);
+    const duringFailure = scene.temporalSnapshotBySlot(0);
+    expect(duringFailure?.previousSource).toBe('last-submitted');
+    expect(duringFailure?.previousTransform.world[12]).toBe(1);
+
+    scene.apply([{ kind: 'update', worldId: 0, entityKey: 7, world: world(9) }]);
+    submit(scene, 7);
+    const afterRetry = scene.temporalSnapshotBySlot(0);
+    expect(afterRetry?.previousSource).toBe('last-submitted');
+    expect(afterRetry?.previousTransform.world[12]).toBe(9);
+  });
+
+  it('keeps last committed root and Instances data across a failed mixed frame and retry', () => {
+    const instanceCollections = new InstanceCollectionStore();
+    const collection = instanceCollections.create({ transforms: matrices(2, 1) }).unwrap();
+    const initialInstances = instanceCollections.snapshot(collection.collectionId).unwrap();
+    instanceCollections.replace(collection.collectionId, matrices(3, 9)).unwrap();
+    const nextInstances = instanceCollections.snapshot(collection.collectionId).unwrap();
+    const scene = new RenderScene();
+    scene.setTemporalTracking(true);
+    try {
+      const initial = snapshot(7, 1, initialInstances);
+      const next = snapshot(7, 9, nextInstances);
+      scene.apply([updateSnapshot(initial)]);
+      submit(scene, 7);
+
+      scene.apply([
+        updateInstances(next),
+        { kind: 'update', worldId: 0, entityKey: 7, world: next.transform.world },
+      ]);
+      const duringFailure = scene.temporalSnapshotBySlot(0);
+      expect(duringFailure?.previousSource).toBe('last-submitted');
+      expect(duringFailure?.previousTransform.world[12]).toBe(1);
+      expect(duringFailure?.previousInstances?.instanceCount).toBe(2);
+      expect(duringFailure?.previousInstances?.transforms[12]).toBe(1);
+
+      scene.apply([
+        updateInstances(next),
+        { kind: 'update', worldId: 0, entityKey: 7, world: next.transform.world },
+      ]);
+      submit(scene, 7);
+      const afterRetry = scene.temporalSnapshotBySlot(0);
+      expect(afterRetry?.previousSource).toBe('last-submitted');
+      expect(afterRetry?.previousTransform.world[12]).toBe(9);
+      expect(afterRetry?.previousInstances?.instanceCount).toBe(3);
+      expect(afterRetry?.previousInstances?.transforms[12]).toBe(9);
+    } finally {
+      instanceCollections.dispose();
+    }
+  });
+});

package/src/__tests__/render-target-material-source.test-d.ts

@@ -2,7 +2,15 @@ import type { SchemaOf, ShapeOf } from '@forgeax/engine-ecs';
 import type { Handle } from '@forgeax/engine-types';
 import { expectTypeOf, it } from 'vitest';
 import type { Camera } from '../components/camera';
-import type { FrameObservationRequest } from '../render-contract';
+import type {
+  FrameDomainObservation,
+  FrameObservationDomain,
+  FrameObservationInclude,
+  FrameObservationRequest,
+  FrameReceipt,
+  FrameReceiptObservation,
+  RendererEvent,
+} from '../render-contract';
 import type {
   RenderTargetReadbackData,
   RenderTargetReadbackTicket,
@@ -20,11 +28,27 @@ it('keeps target material source opaque and receipt readback data explicit', ()
   expectTypeOf<NoProperty<RenderTargetTextureSource, 'texture'>>().toEqualTypeOf<true>();
   expectTypeOf<NoProperty<RenderTargetTextureSource, 'view'>>().toEqualTypeOf<true>();
   expectTypeOf<NoProperty<RenderTargetTextureSource, 'colorSpace'>>().toEqualTypeOf<true>();
-  expectTypeOf<FrameObservationRequest['include'][number]>().toMatchTypeOf<
-    'target-readbacks' | 'timings' | 'draws' | 'bindings'
+  expectTypeOf<
+    FrameObservationRequest['include'][number]
+  >().toEqualTypeOf<FrameObservationInclude>();
+  expectTypeOf<FrameDomainObservation['domain']>().toEqualTypeOf<FrameObservationDomain>();
+  expectTypeOf<FrameReceiptObservation['frameId']>().toEqualTypeOf<number>();
+  expectTypeOf<NonNullable<import('../render-contract').FrameReceipt['backendId']>>().toEqualTypeOf<
+    'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null'
+  >();
+  expectTypeOf<NonNullable<FrameDomainObservation['metadata']['backendId']>>().toEqualTypeOf<
+    'webgpu' | 'wgpu-native' | 'wgpu-webgl2' | 'null'
+  >();
+  expectTypeOf<FrameDomainObservation['metadata']['format']>().toEqualTypeOf<
+    import('@forgeax/engine-rhi').TextureFormat
+  >();
+  expectTypeOf<NonNullable<FrameReceiptObservation['observations']>>().toEqualTypeOf<
+    readonly FrameDomainObservation[]
   >();
   expectTypeOf<FrameObservationRequest['targetReadbacks']>().toEqualTypeOf<
     readonly RenderTargetReadbackTicket[] | undefined
   >();
   expectTypeOf<RenderTargetReadbackData['bytes']>().toEqualTypeOf<Uint8Array>();
+  type SubmittedEvent = Extract<RendererEvent, { kind: 'frame-submitted' }>;
+  expectTypeOf<SubmittedEvent['receipt']>().toEqualTypeOf<FrameReceipt>();
 });

package/src/__tests__/renderer-factory-material-contract.unit.test.ts

@@ -474,6 +474,47 @@ describe('temporal material PSO creation contract', () => {
     });
   });
 
+  it.each([
+    { depthWriteEnabled: false, depthCompare: 'always' as const },
+    { depthWriteEnabled: true, depthCompare: 'never' as const },
+  ])('preserves explicit depth-only render state (%s)', (renderState) => {
+    const createRenderPipeline = vi.fn((_descriptor: unknown) => ({ ok: true, value: {} }));
+    const result = buildPipelineForMaterialShader(
+      'prepared-depth-only',
+      {
+        source: `
+          struct VsIn { @location(0) position: vec3<f32> }
+          @vertex fn vs_main(input: VsIn) -> @builtin(position) vec4<f32> {
+            return vec4<f32>(input.position, 1.0);
+          }
+        `,
+        paramSchema: [],
+      },
+      {
+        ...context,
+        colorFormats: [],
+        device: { createRenderPipeline },
+        shaderModuleFactory: { createShaderModule: () => ({ ok: true, value: {} }) },
+        pipelineLayout: {},
+        vertexBuffers: [],
+      } as unknown as PipelineBuilderContext,
+      renderState,
+      undefined,
+      'vs_main',
+      undefined,
+      undefined,
+      'shadow-caster',
+    );
+    expect(result.ok).toBe(true);
+    expect(createRenderPipeline.mock.calls[0]?.[0]).toMatchObject({
+      fragment: undefined,
+      depthStencil: {
+        depthWriteEnabled: renderState.depthWriteEnabled,
+        depthCompare: renderState.depthCompare,
+      },
+    });
+  });
+
   it('rejects a storage variant mismatch before caching or device creation', () => {
     const createRenderPipeline = vi.fn((_descriptor: unknown) => ({ ok: true, value: {} }));
     const result = buildPipelineForMaterialShader(
@@ -678,6 +719,25 @@ describe('material shader binding contract', () => {
     expect(resolveMaterialShaderBindingContract(source)).toBe('render-material');
   });
 
+  it('preserves the scene-depth slot when a material shader also owns group one', () => {
+    const viewDepthSource = `
+      @group(0) @binding(0) var<uniform> view: mat4x4<f32>;
+      @group(0) @binding(1) var scene_depth: texture_depth_2d;
+      @group(1) @binding(0) var<uniform> material: vec4<f32>;
+    `;
+    const depthOnlySource = `
+      @group(0) @binding(0) var scene_depth: texture_depth_2d;
+      @group(1) @binding(0) var<uniform> material: vec4<f32>;
+    `;
+
+    expect(resolveMaterialShaderBindingContract(viewDepthSource)).toBe(
+      'render-material-and-scene-depth',
+    );
+    expect(resolveMaterialShaderBindingContract(depthOnlySource)).toBe(
+      'render-material-with-scene-depth',
+    );
+  });
+
   it('recognizes a group-zero sampled depth resource without inventing a view uniform', () => {
     const source = `
       @group(0) @binding(0) var sceneDepth: texture_depth_2d;
@@ -715,7 +775,7 @@ describe('material shader color-domain contract', () => {
       readFileSync(resolve(import.meta.dirname, '../assembly/webgpu-ready.ts'), 'utf8'),
     ].join('\n');
     expect(source).toContain(
-      "isHdr &&\n      (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')",
+      "isHdr &&\n      passKind === 'forward' &&\n      (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')",
     );
     expect(source).toContain("? 'fs_main_hdr'");
     expect(source).toContain('colorFormat: isHdr ? HDR_COLOR_ATTACHMENT_FORMAT : ldrColorFormat');