@forgeax/engine-render 0.1.19 → 0.1.21

package/src/__tests__/reflection-probe-authoring.unit.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import {
+  REFLECTION_PROBE_UPDATE_ON_CHANGE,
+  ReflectionProbe,
+  reflectionProbeUpdateIntentFromF32,
+} from '../components/reflection-probe';
+import { RenderIntentInvalidError } from '../errors/render';
+import {
+  admitReflectionProbe,
+  DEFAULT_REFLECTION_PROBE_LIMITS,
+  estimateReflectionProbeBytes,
+  type ReflectionProbeInput,
+  validateReflectionProbeInput,
+} from '../reflection/projection';
+
+const invalidInputs: readonly ReflectionProbeInput[] = [
+  { halfExtents: [0, 1, 1], priority: 0, intensity: 1, resolution: 256 },
+  { halfExtents: [1, 1, 1], priority: Number.NaN, intensity: 1, resolution: 256 },
+  { halfExtents: [1, 1, 1], priority: 0, intensity: -1, resolution: 256 },
+  { halfExtents: [1, 1, 1], priority: 0, intensity: 1, resolution: 0 },
+];
+
+describe('ReflectionProbe authoring and admission', () => {
+  it('exposes bounded axis-aligned probe vocabulary', () => {
+    expect(ReflectionProbe.fields.halfExtents.type).toBe('array<f32, 3>');
+    expect(ReflectionProbe.fields.priority.type).toBe('f32');
+    expect(ReflectionProbe.fields.intensity.type).toBe('f32');
+    expect(ReflectionProbe.fields.resolution.type).toBe('u32');
+    expect(ReflectionProbe.fields.updateIntent.type).toBe('f32');
+    expect(ReflectionProbe.fields.invalidationVersion.type).toBe('u32');
+    expect(reflectionProbeUpdateIntentFromF32(REFLECTION_PROBE_UPDATE_ON_CHANGE)).toBe('on-change');
+  });
+
+  it('reports invalid update intent through the structured render error contract', () => {
+    expect(() => reflectionProbeUpdateIntentFromF32(99)).toThrowError(RenderIntentInvalidError);
+    try {
+      reflectionProbeUpdateIntentFromF32(99);
+    } catch (error) {
+      expect(error).toBeInstanceOf(RenderIntentInvalidError);
+      if (!(error instanceof RenderIntentInvalidError)) return;
+      expect(error.code).toBe('render-intent-invalid');
+      expect(error.expected).toBe('ReflectionProbe.updateIntent is one of 0, 1, or 2');
+      expect(error.hint).toBe('set ReflectionProbe.updateIntent to 0, 1, or 2');
+      expect(error.detail).toEqual({
+        component: 'ReflectionProbe',
+        field: 'updateIntent',
+        value: 99,
+        allowed: [0, 1, 2],
+      });
+    }
+  });
+
+  it.each(invalidInputs)('rejects invalid authoring input %#', (input) => {
+    expect(validateReflectionProbeInput(input).ok).toBe(false);
+  });
+
+  it('admits the profile boundary and rejects the first over-budget probe', () => {
+    const probe = { halfExtents: [1, 1, 1] as const, priority: 0, intensity: 1, resolution: 256 };
+    const bytes = estimateReflectionProbeBytes(probe.resolution);
+    expect(bytes * DEFAULT_REFLECTION_PROBE_LIMITS.maxProbes).toBeLessThanOrEqual(
+      DEFAULT_REFLECTION_PROBE_LIMITS.maxBytes,
+    );
+    expect(admitReflectionProbe(probe, { acceptedCount: 15, acceptedBytes: bytes * 15 })).toEqual({
+      ok: true,
+      acceptedBytes: bytes * 16,
+    });
+    expect(admitReflectionProbe(probe, { acceptedCount: 16, acceptedBytes: bytes * 16 }).ok).toBe(
+      false,
+    );
+  });
+});

package/src/__tests__/reflection-probe-filter.unit.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import {
+  advanceProbeFilter,
+  boxProjectReflectionDirection,
+  createProbeFilterState,
+} from '../reflection/filter';
+import { buildReflectionProbeTable } from '../reflection/gpu-table';
+
+describe('ReflectionProbe bounded filtering and table projection', () => {
+  it('does at most one face and one mip filter step per frame', () => {
+    const state = createProbeFilterState({ probeIndex: 2, faceCount: 6, mipCount: 5 });
+    expect(advanceProbeFilter(state)).toEqual({ probeIndex: 2, faceIndex: 0, mipLevel: 0 });
+    expect(advanceProbeFilter({ ...state, cursor: 1 })).toEqual({
+      probeIndex: 2,
+      faceIndex: 1,
+      mipLevel: 0,
+    });
+  });
+
+  it('keeps active LKG while a candidate is incomplete', () => {
+    const state = createProbeFilterState({ probeIndex: 0, faceCount: 6, mipCount: 3 });
+    expect(state.activeGeneration).toBe(0);
+    const next = advanceProbeFilter({ ...state, cursor: 17 });
+    expect(next).toEqual({ probeIndex: 0, faceIndex: 5, mipLevel: 2 });
+    expect(state.activeGeneration).toBe(0);
+  });
+
+  it('publishes only filtered probe rows and joins CPU/GPU by one index', () => {
+    const table = buildReflectionProbeTable([
+      {
+        primitiveKey: '0:9',
+        index: 1,
+        worldId: 0,
+        entityKey: 8,
+        center: [0, 0, 0],
+        halfExtents: [2, 2, 2],
+        intensity: 1,
+        generation: 4,
+      },
+    ]);
+    expect(table.rows[0]?.index).toBe(1);
+    expect(table.rows[0]?.generation).toBe(4);
+    expect(table.cpuIndexByPrimitive('0:9')).toBe(1);
+  });
+
+  it('projects a reflection direction from inside and outside the box', () => {
+    expect(boxProjectReflectionDirection([1, 0, 0], [0, 0, 0], [2, 2, 2], [0, 0, 0])).toEqual([
+      1, 0, 0,
+    ]);
+    expect(boxProjectReflectionDirection([1, 0, 0], [0, 0, 0], [2, 2, 2], [3, 0, 0])).toEqual([
+      1, 0, 0,
+    ]);
+  });
+});

package/src/__tests__/reflection-probe-ibl-topology.unit.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beginProbeIblUpdate,
+  createIblKernelCache,
+  createProbeIblOutput,
+  type ProbeIblOutput,
+  publishProbeIblOutput,
+} from '../ibl/kernel-cache';
+
+describe('ReflectionProbe IBL topology', () => {
+  it('shares only generation-scoped kernels and keeps probe outputs independent', () => {
+    const kernels = createIblKernelCache(7);
+    const first = createProbeIblOutput({ entityKey: 1, resolution: 256, deviceGeneration: 7 });
+    const second = createProbeIblOutput({ entityKey: 2, resolution: 256, deviceGeneration: 7 });
+    expect(kernels.generation).toBe(7);
+    expect(first.raw).not.toBe(first.filtered);
+    expect(first.raw).not.toBe(second.raw);
+    expect(first.filteredGeneration).toBe(0);
+    expect(first.lkg).toBe(true);
+  });
+
+  it('requires raw, filtered, and publish order before a new generation is visible', () => {
+    const initial = createProbeIblOutput({ entityKey: 4, resolution: 128, deviceGeneration: 2 });
+    const update = beginProbeIblUpdate(initial);
+    expect(update.stages).toEqual(['raw', 'filtered', 'publish']);
+    expect(update.nextStage).toBe('raw');
+    const published = publishProbeIblOutput(update, { stage: 'raw', ok: true });
+    expect(published.filteredGeneration).toBe(0);
+    expect(published.lkg).toBe(true);
+  });
+
+  it('retains filtered LKG when PMREM, encode, or submit fails', () => {
+    let output: ProbeIblOutput = createProbeIblOutput({
+      entityKey: 5,
+      resolution: 64,
+      deviceGeneration: 3,
+    });
+    const update = beginProbeIblUpdate(output);
+    for (const stage of ['raw', 'filtered', 'publish'] as const) {
+      output = publishProbeIblOutput({ ...update, nextStage: stage }, { stage, ok: false });
+      expect(output.lkg).toBe(true);
+      expect(output.filteredGeneration).toBe(0);
+    }
+  });
+});

package/src/__tests__/reflection-probe-pass-encode.integration.test.ts

@@ -0,0 +1,101 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import {
+  addReflectionProbeGraphPasses,
+  type ReflectionProbeGraphState,
+} from '../record/typed-frame-graph';
+import type { RenderPipelineFrame } from '../render-pipeline';
+
+describe('ReflectionProbe capture pass encoding', () => {
+  it('resolves imported capture views through the execution resolver', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const rawTexture = device
+      .createTexture({
+        label: 'reflection-test-raw',
+        format: 'rgba8unorm',
+        size: { width: 1, height: 1, depthOrArrayLayers: 6 },
+        mipLevelCount: 1,
+        sampleCount: 1,
+        dimension: '2d',
+        usage: 0x15,
+        textureBindingViewDimension: undefined,
+      })
+      .unwrap();
+    const rawCubeView = device
+      .createTextureView(rawTexture, { dimension: 'cube', arrayLayerCount: 6 })
+      .unwrap();
+    const rawFaceViews = Array.from({ length: 6 }, (_, face) =>
+      device
+        .createTextureView(rawTexture, {
+          dimension: '2d',
+          baseArrayLayer: face,
+          arrayLayerCount: 1,
+        })
+        .unwrap(),
+    );
+    const depthTexture = device
+      .createTexture({
+        label: 'reflection-test-depth',
+        format: 'depth24plus-stencil8',
+        size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+        mipLevelCount: 1,
+        sampleCount: 1,
+        dimension: '2d',
+        usage: 0x10,
+        textureBindingViewDimension: undefined,
+      })
+      .unwrap();
+    const depthView = device.createTextureView(depthTexture, { dimension: '2d' }).unwrap();
+    const sampler = device.createSampler().unwrap();
+    const emptyLayout = device.createBindGroupLayout({ entries: [] }).unwrap();
+    const filterGroup1 = device.createBindGroup({ layout: emptyLayout, entries: [] }).unwrap();
+    const cubeVertexBuffer = device.createBuffer({ size: 16, usage: 0x20 }).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const filterPipeline = device
+      .createRenderPipeline({
+        label: 'reflection-test-filter',
+        layout: 'auto',
+        vertex: { module: shader, entryPoint: 'main', buffers: [] },
+        fragment: { module: shader, entryPoint: 'main', targets: [{ format: 'rgba8unorm' }] },
+        primitive: { topology: 'triangle-list' },
+      })
+      .unwrap();
+    const work: ReflectionProbeGraphState['work'][number] = {
+      probeIndex: 0,
+      rawTexture,
+      rawCubeView,
+      rawFaceViews,
+      rawDepthTexture: depthTexture,
+      rawCaptureFace: 0,
+      rawDepthView: depthView,
+      rawSize: 1,
+      filteredTexture: rawTexture,
+      filteredCubeView: rawCubeView,
+      filteredFaceViewsByMip: [rawFaceViews],
+      outputFormat: 'rgba8unorm',
+      sampler,
+      filterPipeline,
+      filterGroup0: undefined,
+      filterGroup1,
+      cubeVertexBuffer,
+      filteredSize: 1,
+      step: undefined,
+    };
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    expect(addReflectionProbeGraphPasses(graph, { work: [work] }).ok).toBe(true);
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    const encoder = device.createCommandEncoder({ label: 'reflection-test-frame' }).unwrap();
+    const frame = {
+      runtime: { device },
+      validatedOrdered: [],
+      frameState: { standardLighting: undefined, installedPipelineConfig: undefined },
+      msaaActive: false,
+      splitLdrSprite: false,
+    } as unknown as RenderPipelineFrame;
+    const executed = compiled.execute({ ...frame, encoder });
+    expect(executed.ok).toBe(true);
+    expect(encoder.finish().ok).toBe(true);
+  });
+});

package/src/__tests__/reflection-probe-performance.perf.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { boundedReflectionProbeFilterWork } from '../record/typed-frame-graph';
+import {
+  advanceProbeFilter,
+  createProbeFilterState,
+  probeFilterIsSteady,
+} from '../reflection/filter';
+import { ReflectionProbeProjection } from '../reflection/projection';
+
+describe('ReflectionProbe steady-state performance contract', () => {
+  it('keeps off and steady filter work exactly zero', () => {
+    const off = boundedReflectionProbeFilterWork({ work: [], maxStepsPerFrame: 1 });
+    const steady = createProbeFilterState({ probeIndex: 0, faceCount: 6, mipCount: 5 });
+    const complete = { ...steady, cursor: steady.faceCount * steady.mipCount };
+
+    expect(off).toHaveLength(0);
+    expect(probeFilterIsSteady(complete)).toBe(true);
+    expect(advanceProbeFilter(complete)).toBeUndefined();
+  });
+
+  it('keeps one candidate bounded to active output and one table row', () => {
+    const state = createProbeFilterState({ probeIndex: 3, faceCount: 6, mipCount: 5 });
+    const step = advanceProbeFilter(state);
+    expect(step).toBeDefined();
+    if (!step) throw new Error('expected an initial reflection probe filter step');
+    expect(step).toEqual({ probeIndex: 3, faceIndex: 0, mipLevel: 0 });
+    expect(
+      boundedReflectionProbeFilterWork({
+        work: [step],
+        maxStepsPerFrame: 1,
+      }),
+    ).toHaveLength(1);
+  });
+
+  it('does not advance the projection revision on a stable frame', () => {
+    const projection = new ReflectionProbeProjection();
+    const facts = [
+      {
+        worldId: 0,
+        entityKey: 3,
+        center: [0, 0, 0] as const,
+        halfExtents: [2, 2, 2] as const,
+        priority: 1,
+        intensity: 1,
+        resolution: 64,
+        revision: 1,
+      },
+    ];
+    const primitives = [
+      { worldId: 0, entityKey: 8, center: [0, 0, 0] as const },
+      { worldId: 0, entityKey: 9, center: [3, 0, 0] as const },
+    ];
+    const first = projection.update(facts, primitives);
+    const second = projection.update(facts, primitives);
+
+    expect(first.revision).toBe(1);
+    expect(second.revision).toBe(1);
+    expect(second.scannedPrimitives).toBe(first.scannedPrimitives);
+  });
+});

package/src/__tests__/reflection-probe-recovery.integration.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import {
+  admitReflectionProbe,
+  estimateReflectionProbeBytes,
+  ReflectionProbeProjection,
+} from '../reflection/projection';
+
+describe('ReflectionProbe recovery integration', () => {
+  it('selects by world identity and falls back to Skylight outside all boxes', () => {
+    const projection = new ReflectionProbeProjection();
+    const snapshot = projection.update(
+      [
+        {
+          worldId: 9,
+          entityKey: 4,
+          center: [0, 0, 0],
+          halfExtents: [2, 2, 2],
+          priority: 1,
+          intensity: 1,
+          resolution: 64,
+          revision: 1,
+        },
+        {
+          worldId: 3,
+          entityKey: 8,
+          center: [0, 0, 0],
+          halfExtents: [2, 2, 2],
+          priority: 1,
+          intensity: 1,
+          resolution: 64,
+          revision: 1,
+        },
+      ],
+      [
+        { worldId: 9, entityKey: 100, center: [0, 0, 0] },
+        { worldId: 3, entityKey: 200, center: [4, 0, 0] },
+      ],
+    );
+    expect(snapshot.scannedPrimitives).toBe(2);
+    expect(projection.selection(9, 100)).toMatchObject({ kind: 'probe', worldId: 3, entityKey: 8 });
+    expect(projection.selection(3, 200)).toEqual({ kind: 'skylight' });
+    expect([...snapshot.facts].map((fact) => `${fact.worldId}:${fact.entityKey}`)).toEqual([
+      '3:8',
+      '9:4',
+    ]);
+  });
+
+  it('rejects the next allocation before GPU work exceeds the admission budget', () => {
+    const probe = { halfExtents: [1, 1, 1] as const, priority: 0, intensity: 1, resolution: 64 };
+    const bytes = estimateReflectionProbeBytes(probe.resolution);
+    const result = admitReflectionProbe(probe, { acceptedCount: 16, acceptedBytes: bytes * 16 });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('reflection-probe-budget-exceeded');
+  });
+});

package/src/__tests__/reflection-probe-selection.unit.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { type ReflectionProbeFact, selectReflectionProbe } from '../reflection/projection';
+
+const fact = (overrides: Partial<ReflectionProbeFact> = {}): ReflectionProbeFact => ({
+  worldId: 0,
+  entityKey: 1,
+  center: [0, 0, 0],
+  halfExtents: [2, 2, 2],
+  priority: 0,
+  intensity: 1,
+  resolution: 256,
+  revision: 1,
+  ...overrides,
+});
+
+describe('ReflectionProbe deterministic selection', () => {
+  it('filters by box containment before priority and normalized distance', () => {
+    const selected = selectReflectionProbe(
+      [fact({ entityKey: 3, priority: 2 }), fact({ entityKey: 2 })],
+      [0.5, 0, 0],
+    );
+    expect(selected.kind).toBe('probe');
+    if (selected.kind === 'probe') expect(selected.entityKey).toBe(3);
+    expect(selectReflectionProbe([fact({ entityKey: 3 })], [3, 0, 0]).kind).toBe('skylight');
+  });
+
+  it('uses normalized distance and stable identity as tie-breaks', () => {
+    const selected = selectReflectionProbe(
+      [
+        fact({ entityKey: 9, center: [1, 0, 0], halfExtents: [2, 2, 2] }),
+        fact({ entityKey: 4, center: [-1, 0, 0], halfExtents: [4, 4, 4] }),
+      ],
+      [0, 0, 0],
+    );
+    expect(selected.kind).toBe('probe');
+    if (selected.kind === 'probe') expect(selected.entityKey).toBe(4);
+  });
+
+  it('does not depend on World reorder or mix World identities', () => {
+    const probes = [fact({ worldId: 2, entityKey: 8 }), fact({ worldId: 1, entityKey: 3 })];
+    const first = selectReflectionProbe(probes, [0, 0, 0]);
+    const second = selectReflectionProbe([...probes].reverse(), [0, 0, 0]);
+    expect(first).toEqual(second);
+    expect(selectReflectionProbe(probes, [8, 0, 0]).kind).toBe('skylight');
+  });
+});

package/src/__tests__/render-error-code-owner.test-d.ts

@@ -1,3 +1,4 @@
+import type { RuntimeErrorCode } from '@forgeax/engine-types';
 import { describe, expectTypeOf, it } from 'vitest';
 import type {
   ObservationUnavailableDetail,
@@ -33,9 +34,10 @@ const expectedCodes = [
   'taa-unavailable',
   'shadow-invalid-config',
   'equirect-projection-failed',
-  'hdrp-light-budget-exceeded',
-  'hdrp-index-list-overflow',
-  'hdrp-deferred-caps-insufficient',
+  'standard-light-budget-exceeded',
+  'standard-cluster-index-overflow',
+  'standard-cluster-transport-unavailable',
+  'standard-profile-invalid',
   'point-shadow-atlas-uninitialized',
   'point-shadow-atlas-bounds-violation',
   'video-upload-unsupported',
@@ -64,6 +66,17 @@ const expectedCodes = [
   'points-lines-material-unsupported',
   'points-lines-budget-exceeded',
   'points-lines-prepare-failed',
+  'render-target-descriptor-invalid',
+  'render-target-capability-missing',
+  'render-target-state-invalid',
+  'render-target-operation-failed',
+  'reflection-probe-budget-exceeded',
+  'render-intent-invalid',
+  'volume-owner-conflict',
+  'volume-density-shape-mismatch',
+  'volume-invalid-bounds',
+  'volume-invalid-parameters',
+  'projector-binding-failed',
 ] as const satisfies readonly RenderErrorCode[];
 type ExpectedCodeUnion = (typeof expectedCodes)[number];
 
@@ -99,6 +112,13 @@ describe('RenderError code owner', () => {
     void unknownCode;
   });
 
+  it('keeps retired HDRP error namespaces out of every public code union', () => {
+    type RetiredRenderCode = Extract<RenderErrorCode, `hdrp-${string}`>;
+    type RetiredRuntimeCode = Extract<RuntimeErrorCode, `hdrp-${string}`>;
+    expectTypeOf<RetiredRenderCode>().toEqualTypeOf<never>();
+    expectTypeOf<RetiredRuntimeCode>().toEqualTypeOf<never>();
+  });
+
   it('preserves correlated detail and value declarations', () => {
     type ObservationError = Extract<RenderError, { readonly code: 'observation-unavailable' }>;
     expectTypeOf<ObservationError['detail']>().toEqualTypeOf<ObservationUnavailableDetail>();

package/src/__tests__/render-feature-docs.unit.test.ts

@@ -17,7 +17,7 @@ const appSkill = read('../../../../skills/forgeax-engine-app/SKILL.md');
 
 // M4-06 prepends the direct-light contract; keep the existing first-read
 // vocabulary assertion wide enough to cover that approved contract.
-const topSurface = renderReadme.slice(0, 18000);
+const topSurface = renderReadme.slice(0, 20000);
 
 describe('RenderFeature documentation surface', () => {
   it('keeps the first-read public route and four-term vocabulary indexable', () => {

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');
+  });
+});