@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/render-scene-projection.unit.test.ts

@@ -1,10 +1,29 @@
+import { World } from '@forgeax/engine-ecs';
+import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
-import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
-import { RenderScene } from '../scene/render-scene';
+import { Camera, MotionBlur } from '../components';
+import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
+import type {
+  ExtractedFrame,
+  MaterialSnapshot,
+  RenderableSnapshot,
+} from '../render-system-extract';
+import { PersistentRenderScene, RenderScene } from '../scene/render-scene';
+import { primitiveKey, viewKey } from '../scene/visibility/types';
 import { classifySceneDataCoverage } from '../temporal/coverage';
 
 const material = {} as MaterialSnapshot;
 
+function guid(value: string) {
+  const parsed = AssetGuid.parse(value);
+  if (!parsed.ok) throw new Error(`invalid fixture guid: ${value}`);
+  return parsed.value;
+}
+
+const LOD_MESH_GUID = guid('019d0000-0000-7000-8000-000000000001');
+
 function snapshot(entityKey: number, translationX: number): RenderableSnapshot {
   const world = new Float32Array(16);
   world[0] = 1;
@@ -24,6 +43,101 @@ function snapshot(entityKey: number, translationX: number): RenderableSnapshot {
 }
 
 describe('RenderScene canonical owner', () => {
+  it('rebuilds the retained composition when Motion Blur is toggled', () => {
+    const world = new World();
+    const camera = world
+      .spawn(
+        {
+          component: Transform,
+          data: { pos: [0, 0, 4], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+        },
+        {
+          component: Camera,
+          data: { fov: Math.PI / 3, aspect: 1, near: 0.1, far: 100 },
+        },
+        {
+          component: MotionBlur,
+          data: { shutterAngle: 180, maxRadiusPixels: 32, sampleCount: 8 },
+        },
+      )
+      .unwrap();
+    const lease = createRenderReadLease(world);
+    const frame = {
+      cameras: [{ ...makeZeroCameraFallbackSnapshot(), worldId: 0, entityKey: camera as number }],
+      renderables: [],
+      dispatch: [],
+    } as unknown as ExtractedFrame;
+    const persistent = new PersistentRenderScene();
+    let builds = 0;
+    const build = (): ExtractedFrame => {
+      builds += 1;
+      return frame;
+    };
+
+    persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, build, [lease]);
+    expect(builds).toBe(1);
+
+    world.removeComponent(camera, MotionBlur).unwrap();
+    world.update().unwrap();
+    persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, build, [lease]);
+    expect(builds).toBe(2);
+
+    world
+      .addComponent(camera, {
+        component: MotionBlur,
+        data: { shutterAngle: 180, maxRadiusPixels: 32, sampleCount: 8 },
+      })
+      .unwrap();
+    world.update().unwrap();
+    persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, build, [lease]);
+    expect(builds).toBe(3);
+    lease.dispose();
+  });
+
+  it('retains renderable topology while refreshing per-frame resources', () => {
+    const world = new World();
+    const lease = createRenderReadLease(world);
+    const camera = { ...makeZeroCameraFallbackSnapshot(), worldId: 0, entityKey: 1 };
+    const renderables = Array.from({ length: 1024 }, (_, entityKey) =>
+      snapshot(entityKey + 1, entityKey * 0.01),
+    );
+    const frame = {
+      cameras: [camera],
+      renderables,
+      dispatch: [],
+    } as unknown as ExtractedFrame;
+    const persistent = new PersistentRenderScene();
+    let builds = 0;
+    const build = (): ExtractedFrame => {
+      builds += 1;
+      return frame;
+    };
+    const first = persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      build,
+      [lease],
+    );
+    const stable = persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      build,
+      [lease],
+    );
+
+    expect(stable).not.toBe(first);
+    expect(stable.renderables).toEqual(first.renderables);
+    expect(builds).toBe(2);
+    expect(persistent.inspect()).toMatchObject({
+      worldEntitiesScanned: 0,
+      noChangeFrames: 1,
+      projectionRecords: 1024,
+    });
+    lease.dispose();
+  });
+
   it('projects current scene contributors without owning temporal history', () => {
     const coverage = classifySceneDataCoverage({
       contributors: [{ id: 'world', kind: 'reactive' }],
@@ -51,6 +165,27 @@ describe('RenderScene canonical owner', () => {
     expect(projection.materialize()[0]?.transform.world[12]).toBe(9);
   });
 
+  it('updates cached dynamic world bounds without replacing the bounds object', () => {
+    const projection = new RenderScene();
+    const initial = {
+      ...snapshot(7, 1),
+      localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    };
+    projection.apply([{ kind: 'create', snapshot: initial }]);
+    const retained = projection.materialize()[0];
+    if (retained === undefined) throw new Error('expected retained snapshot');
+    const first = projection.cullingWorldBounds(retained);
+    const moved = new Float32Array(initial.transform.world);
+    moved[12] = 9;
+
+    projection.applyTransformSpans([{ worldId: 0, entities: new Uint32Array([7]), worlds: moved }]);
+
+    const next = projection.cullingWorldBounds(retained);
+    expect(next).toBe(first);
+    expect(next?.min[0]).toBe(8);
+    expect(next?.max[0]).toBe(10);
+  });
+
   it('cancels a transient create/remove pair without allocating a slot', () => {
     const projection = new RenderScene();
 
@@ -103,9 +238,319 @@ describe('RenderScene canonical owner', () => {
 
     expect(projection.materialize().map((record) => record.transform.world[12])).toEqual([3, 8]);
   });
+
+  it('suppresses an occluded LOD candidate after two zero results and reopens it on a hit', () => {
+    const world = new World();
+    const camera = {
+      ...makeZeroCameraFallbackSnapshot(),
+      worldId: 0,
+      entityKey: 1,
+    };
+    const candidate = {
+      ...snapshot(7, 1),
+      lods: [{ mesh: LOD_MESH_GUID, screenCoverage: 0.5 }],
+      localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    } as RenderableSnapshot;
+    const dispatch = {
+      entityIndex: candidate.entityKey,
+      materialHandle: 0,
+      renderableIndex: 0,
+      passIndex: 0,
+      queue: 2000,
+      layer: 0,
+      tags: {},
+      renderState: undefined,
+      defines: undefined,
+      vertexEntry: undefined,
+      fragmentEntry: undefined,
+      materialShaderId: 'forgeax::default-unlit',
+      paramSnapshot: undefined,
+    };
+    const frame = {
+      cameras: [camera],
+      dispatch: [dispatch],
+      renderables: [candidate],
+    } as unknown as ExtractedFrame;
+    const persistent = new PersistentRenderScene();
+    const lease = createRenderReadLease(world);
+    persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, () => frame, [
+      lease,
+    ]);
+    const renderableInput = [candidate];
+    const dispatchInput = [dispatch];
+    persistent.updateVisibilityFacet([world], camera, renderableInput);
+    const view = viewKey({
+      attachmentId: world.identity,
+      cameraEntity: camera.entityKey ?? 0,
+      viewRole: 'main',
+      viewGeneration: camera.historyVersion ?? 0,
+    });
+    const primitive = primitiveKey({
+      attachmentId: world.identity,
+      worldGeneration: 0,
+      primitiveSlot: 0,
+      slotGeneration: 0,
+    });
+    const facets = persistent.visibilityFacetStore();
+    const initialProjection = persistent.projectVisibility(
+      [world],
+      camera,
+      renderableInput,
+      dispatchInput,
+    );
+    const beforeCompletionRevision = facets.drawRevisionValue;
+    expect(facets.applyCompletion(view, primitive, 0, { level: 0, confidence: 1 })).toBe(true);
+    expect(facets.drawRevisionValue).toBe(beforeCompletionRevision);
+    expect(persistent.projectVisibility([world], camera, renderableInput, dispatchInput)).toBe(
+      initialProjection,
+    );
+    facets.applyConfidence(view, primitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 1,
+    });
+    facets.applyConfidence(view, primitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+    const hidden = persistent.projectVisibility([world], camera, renderableInput, dispatchInput);
+    expect(hidden.renderables).toHaveLength(0);
+    expect(hidden.dispatch).toHaveLength(0);
+    expect(hidden.suppressed).toBe(1);
+
+    facets.applyConfidence(view, primitive, {
+      type: 'result',
+      samples: 1,
+      submissionGeneration: 3,
+    });
+    const reopened = persistent.projectVisibility([world], camera, renderableInput, dispatchInput);
+    expect(reopened.renderables).toHaveLength(1);
+    expect(reopened.dispatch).toHaveLength(1);
+    expect(reopened.activeEntityKeys.size).toBe(1);
+    lease.dispose();
+  });
+
+  it('keeps a secondary World primitive identity stable across composition reorder', () => {
+    const worldA = new World();
+    const worldB = new World();
+    const leaseA = createRenderReadLease(worldA);
+    const leaseB = createRenderReadLease(worldB);
+    const cameraA = { ...makeZeroCameraFallbackSnapshot(), worldId: 0, entityKey: 10 };
+    const candidateB = {
+      ...snapshot(7, 1),
+      worldId: 1,
+      lods: [{ mesh: LOD_MESH_GUID, screenCoverage: 0.5 }],
+      localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    } as RenderableSnapshot;
+    const ordinaryA = snapshot(8, -1);
+    const dispatchFor = (renderableIndex: number) => ({
+      entityIndex: 7,
+      materialHandle: 0,
+      renderableIndex,
+      passIndex: 0,
+      queue: 2000,
+      layer: 0,
+      tags: {},
+      renderState: undefined,
+      defines: undefined,
+      variantSet: undefined,
+      vertexEntry: undefined,
+      fragmentEntry: undefined,
+      materialShaderId: 'forgeax::default-unlit',
+      paramSnapshot: undefined,
+    });
+    const frameAB = {
+      cameras: [cameraA],
+      dispatch: [dispatchFor(1)],
+      renderables: [ordinaryA, candidateB],
+    } as unknown as ExtractedFrame;
+    const persistent = new PersistentRenderScene();
+    persistent.extractComposition(
+      [worldA, worldB],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      () => frameAB,
+      [leaseA, leaseB],
+    );
+    persistent.updateVisibilityFacet([worldA, worldB], cameraA, [ordinaryA, candidateB]);
+    const viewA = viewKey({
+      attachmentId: worldA.identity,
+      cameraEntity: 10,
+      viewRole: 'main',
+      viewGeneration: 0,
+    });
+    const primitiveB = primitiveKey({
+      attachmentId: worldA.identity,
+      worldGeneration: 1,
+      primitiveSlot: 1,
+      slotGeneration: 0,
+    });
+    const facets = persistent.visibilityFacetStore();
+    facets.applyConfidence(viewA, primitiveB, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 1,
+    });
+    facets.applyConfidence(viewA, primitiveB, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+
+    const reorderedCandidateB = { ...candidateB, worldId: 0 };
+    const reorderedOrdinaryA = { ...ordinaryA, worldId: 1 };
+    const cameraAReordered = { ...cameraA, worldId: 1 };
+    const frameBA = {
+      cameras: [cameraAReordered],
+      dispatch: [dispatchFor(0)],
+      renderables: [reorderedCandidateB, reorderedOrdinaryA],
+    } as unknown as ExtractedFrame;
+    persistent.extractComposition(
+      [worldB, worldA],
+      { cameraOwner: 1, resourceOwner: 1 },
+      0,
+      () => frameBA,
+      [leaseB, leaseA],
+    );
+    persistent.updateVisibilityFacet([worldB, worldA], cameraAReordered, [reorderedCandidateB]);
+    const projected = persistent.projectVisibility(
+      [worldB, worldA],
+      cameraAReordered,
+      [reorderedCandidateB],
+      [dispatchFor(0)],
+    );
+    expect(projected.suppressed).toBe(1);
+    expect(projected.renderables).toHaveLength(0);
+    leaseA.dispose();
+    leaseB.dispose();
+  });
+
+  it('clears visibility facets when a same-World topology rebuild reuses slots', () => {
+    const world = new World();
+    const lease = createRenderReadLease(world);
+    const camera = { ...makeZeroCameraFallbackSnapshot(), worldId: 0, entityKey: 10 };
+    const candidate = {
+      ...snapshot(7, 1),
+      lods: [{ mesh: LOD_MESH_GUID, screenCoverage: 0.5 }],
+      localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    } as RenderableSnapshot;
+    const dispatch = {
+      entityIndex: 7,
+      materialHandle: 0,
+      renderableIndex: 0,
+      passIndex: 0,
+      queue: 2000,
+      layer: 0,
+      tags: {},
+      renderState: undefined,
+      defines: undefined,
+      variantSet: undefined,
+      vertexEntry: undefined,
+      fragmentEntry: undefined,
+      materialShaderId: 'forgeax::default-unlit',
+      paramSnapshot: undefined,
+    };
+    const frame = {
+      cameras: [camera],
+      dispatch: [dispatch],
+      renderables: [candidate],
+    } as unknown as ExtractedFrame;
+    const persistent = new PersistentRenderScene();
+    persistent.extractComposition([world], { cameraOwner: 0, resourceOwner: 0 }, 0, () => frame, [
+      lease,
+    ]);
+    persistent.updateVisibilityFacet([world], camera, [candidate]);
+    const view = viewKey({
+      attachmentId: world.identity,
+      cameraEntity: 10,
+      viewRole: 'main',
+      viewGeneration: 0,
+    });
+    const before = persistent.compositionSlots()[0];
+    const primitive = primitiveKey({
+      attachmentId: world.identity,
+      worldGeneration: 0,
+      primitiveSlot: before?.slot ?? 0,
+      slotGeneration: before?.generation ?? 0,
+    });
+    const facets = persistent.visibilityFacetStore();
+    facets.applyConfidence(view, primitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 1,
+    });
+    facets.applyConfidence(view, primitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+    expect(persistent.projectVisibility([world], camera, [candidate], [dispatch]).suppressed).toBe(
+      1,
+    );
+
+    // A real journal change forces the composition rebuild. The callback adds
+    // a new renderable, so the previous slot generation could otherwise ABA
+    // into the newly rebuilt projection.
+    world.spawn({ component: Transform, data: {} }).unwrap();
+    world.update().unwrap();
+    const extra = { ...snapshot(8, 2), localAabb: candidate.localAabb };
+    const rebuiltFrame = {
+      cameras: [camera],
+      dispatch: [dispatch, { ...dispatch, entityIndex: 8, renderableIndex: 1 }],
+      renderables: [candidate, extra],
+    } as unknown as ExtractedFrame;
+    persistent.extractComposition(
+      [world],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      () => rebuiltFrame,
+      [lease],
+    );
+    persistent.updateVisibilityFacet([world], camera, [candidate]);
+    expect(persistent.projectVisibility([world], camera, [candidate], [dispatch]).suppressed).toBe(
+      0,
+    );
+    lease.dispose();
+  });
 });
 
 describe('RenderScene', () => {
+  it('retains attached probe records through persistent frustum culling', () => {
+    const scene = new PersistentRenderScene();
+    const renderable = {
+      ...snapshot(7, 0),
+      localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    };
+    const frame = {
+      cameras: [],
+      renderables: [renderable],
+      dispatch: [],
+      lightProbes: [
+        {
+          identity: 'probe-a',
+          position: [0, 0, 0] as const,
+          radius: 2,
+          irradiance: new Float32Array(27).fill(1),
+          admitted: true,
+        },
+      ],
+    } as unknown as ExtractedFrame;
+
+    const projected = scene.extractComposition(
+      [{} as World],
+      { cameraOwner: 0, resourceOwner: 0 },
+      0,
+      () => frame,
+    );
+
+    expect(projected.renderables[0]?.probeBlendRecord).toMatchObject({
+      objectKey: 0,
+      localBlendFraction: 1,
+      accepted: true,
+    });
+  });
+
   it('keeps world identity slots stable across a composition reorder', () => {
     const scene = new RenderScene();
     const first = snapshot(1, 3);
@@ -177,20 +622,4 @@ describe('RenderScene', () => {
     expect(scene.querySpatial({ min: [-2, -2, -2], max: [2, 2, 2] })).toEqual([]);
     expect(scene.querySpatial({ min: [9, -2, -2], max: [11, 2, 2] })).toHaveLength(1);
   });
-
-  it('rebuilds from a resync delta after journal overflow', () => {
-    const scene = new RenderScene();
-    scene.apply([{ kind: 'create', snapshot: snapshot(1, 0) }]);
-
-    const result = scene.applyDelta({
-      operations: [],
-      overflowed: true,
-      resync: [snapshot(99, 9)],
-      reason: 'journal-overflow',
-    });
-
-    expect(result.resynced).toBe(1);
-    expect(scene.has(0, 1)).toBe(false);
-    expect(scene.has(0, 99)).toBe(true);
-  });
 });

package/src/__tests__/render-target-admission.unit.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import { RenderTargetCapabilityMissingError } from '../errors/render';
+import {
+  admitRenderTargetDescriptor,
+  type RenderTargetAdmissionLimits,
+  type RenderTargetDescriptor,
+} from '../targets/contracts';
+
+const limits: RenderTargetAdmissionLimits = {
+  maxTextureDimension2D: 4096,
+  maxBytesPerTarget: 64 * 1024 * 1024,
+  renderableFormats: ['rgba16float', 'rgba8unorm', 'rgba8unorm-srgb'],
+  sampleCounts: [1, 4],
+  depthFormats: ['depth24plus-stencil8', 'depth32float'],
+};
+
+const base: RenderTargetDescriptor = {
+  shape: '2d',
+  width: 512,
+  height: 256,
+  format: 'rgba8unorm',
+  mipLevels: 1,
+  sampleCount: 1,
+  sampled: true,
+  readback: true,
+};
+
+describe('RenderTarget descriptor admission', () => {
+  it('accepts the complete first-version descriptor vocabulary', () => {
+    const result = admitRenderTargetDescriptor(base, limits);
+    expect(result.ok).toBe(true);
+  });
+
+  it.each([
+    ['zero width', { width: 0 }],
+    ['zero height', { height: 0 }],
+    ['non-square cube', { shape: 'cube' as const }],
+  ])('rejects %s before allocation', (_name, patch) => {
+    const descriptor = { ...base, ...patch };
+    if ('shape' in patch && patch.shape === 'cube') descriptor.height = 256;
+    const result = admitRenderTargetDescriptor(descriptor, limits);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('render-target-descriptor-invalid');
+  });
+
+  it('rejects unsupported format, sample count, and byte budget', () => {
+    const formatResult = admitRenderTargetDescriptor(
+      { ...base, format: 'rgba16float' },
+      { ...limits, renderableFormats: ['rgba8unorm'] },
+    );
+    expect(formatResult.ok).toBe(false);
+    if (!formatResult.ok) expect(formatResult.error.code).toBe('render-target-capability-missing');
+
+    const sampleResult = admitRenderTargetDescriptor(
+      { ...base, sampleCount: 4 },
+      { ...limits, sampleCounts: [1] },
+    );
+    expect(sampleResult.ok).toBe(false);
+    if (!sampleResult.ok) expect(sampleResult.error.code).toBe('render-target-capability-missing');
+
+    const bytesResult = admitRenderTargetDescriptor(
+      { ...base, width: 2048, height: 2048, mipLevels: 'full' },
+      { ...limits, maxBytesPerTarget: 1024 },
+    );
+    expect(bytesResult.ok).toBe(false);
+    if (!bytesResult.ok) expect(bytesResult.error.code).toBe('render-target-descriptor-invalid');
+  });
+
+  it('does not reinterpret format or silently fall back on depth', () => {
+    const result = admitRenderTargetDescriptor(
+      { ...base, depth: 'depth32float' },
+      { ...limits, depthFormats: ['depth24plus-stencil8'] },
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok && result.error instanceof RenderTargetCapabilityMissingError) {
+      expect(result.error.code).toBe('render-target-capability-missing');
+      expect(result.error.detail.requested).toBe('depth32float');
+    }
+  });
+});

package/src/__tests__/render-target-graph-projection.unit.test.ts

@@ -0,0 +1,102 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder, Texture, TextureView } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import type { RenderTargetDescriptor } from '../targets/contracts';
+import { projectRenderTargetGraph, type RenderTargetGraphInput } from '../targets/graph-projection';
+import { createRenderTargetOwner } from '../targets/owner';
+
+type Frame = { readonly encoder: RhiCommandEncoder };
+
+const owner = createRenderTargetOwner({ rendererId: Symbol('renderer'), initialGeneration: 3 });
+const texture = {} as Texture;
+const view = {} as TextureView;
+const resolveView = {} as TextureView;
+
+function targetInput(descriptor: RenderTargetDescriptor): RenderTargetGraphInput {
+  const target = owner.create(descriptor);
+  if (!target.ok) throw target.error;
+  return {
+    target: target.value,
+    generation: 3,
+    descriptor,
+    texture,
+    view,
+    ...(descriptor.sampleCount === 4 ? { resolveView } : {}),
+  };
+}
+
+describe('RenderTarget graph projection', () => {
+  it('imports a 2D target with sampled/readback usage and an exact mip view', () => {
+    const descriptor: RenderTargetDescriptor = {
+      shape: '2d',
+      width: 64,
+      height: 32,
+      format: 'rgba8unorm',
+      mipLevels: 'full',
+      sampleCount: 1,
+      sampled: true,
+      readback: true,
+    };
+    const graph = new RenderGraphBuilder<Frame>();
+    const projected = projectRenderTargetGraph(graph, targetInput(descriptor), {
+      mipLevel: 2,
+    });
+    expect(projected.ok).toBe(true);
+    if (!projected.ok) return;
+    expect(projected.value.ownership).toBe('imported');
+    expect(projected.value.generation).toBe(3);
+    expect(projected.value.viewDescriptor).toMatchObject({
+      dimension: '2d',
+      baseMipLevel: 2,
+      mipLevelCount: 1,
+    });
+    expect(projected.value.usage).toEqual(['sampled-read', 'copy-src']);
+  });
+
+  it('keeps cube subresources as cube views and resolves MSAA before sampling', () => {
+    const descriptor: RenderTargetDescriptor = {
+      shape: 'cube',
+      width: 64,
+      height: 64,
+      format: 'rgba16float',
+      mipLevels: 1,
+      sampleCount: 4,
+      sampled: true,
+      readback: true,
+    };
+    const graph = new RenderGraphBuilder<Frame>();
+    const projected = projectRenderTargetGraph(graph, targetInput(descriptor), {
+      mipLevel: 0,
+      face: 4,
+    });
+    expect(projected.ok).toBe(true);
+    if (!projected.ok) return;
+    expect(projected.value.viewDescriptor).toMatchObject({
+      dimension: 'cube',
+      baseMipLevel: 0,
+      baseArrayLayer: 4,
+      arrayLayerCount: 1,
+    });
+    expect(projected.value.resolveView).toBeDefined();
+    expect(projected.value.sampleView).toBe(projected.value.resolveView);
+    expect(projected.value.usage).toEqual(['sampled-read', 'copy-src']);
+  });
+
+  it('rejects a missing MSAA resolve view without changing graph ownership', () => {
+    const descriptor: RenderTargetDescriptor = {
+      shape: '2d',
+      width: 32,
+      height: 32,
+      format: 'rgba8unorm',
+      mipLevels: 1,
+      sampleCount: 4,
+      sampled: true,
+      readback: false,
+    };
+    const graph = new RenderGraphBuilder<Frame>();
+    const input = targetInput(descriptor);
+    const projected = projectRenderTargetGraph(graph, { ...input, resolveView: undefined });
+    expect(projected.ok).toBe(false);
+    if (!projected.ok) expect(projected.error.code).toBe('render-target-operation-failed');
+  });
+});