@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/dynamic-geometry.unit.test.ts

@@ -0,0 +1,233 @@
+import type { MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createDynamicGeometryLifecycle } from '../dynamic-geometry';
+
+const mesh = (): MeshAsset => ({
+  kind: 'mesh',
+  vertices: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+  indices: new Uint16Array([0, 1, 2]),
+  attributes: { position: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]) },
+  aabb: new Float32Array([0, 0, 0, 1, 1, 0]),
+  submeshes: [
+    { indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list', materialSlot: 0 },
+  ],
+  materialSlots: [{ slotName: 'default', sourceKey: 'default' }],
+});
+
+describe('standard dynamic geometry lifecycle', () => {
+  it('copies a MeshAsset and publishes only after a matching frame generation', () => {
+    const lifecycle = createDynamicGeometryLifecycle();
+    const world = {};
+    const source = mesh();
+    const prepared = lifecycle.prepare(
+      { world, mesh: source, revision: 1, topologyRevision: 7 },
+      3,
+    );
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+
+    prepared.value.mesh.vertices[0] = 77;
+
+    const accepted = lifecycle.accept(prepared.value);
+    expect(accepted.ok).toBe(true);
+    if (!accepted.ok) return;
+    expect(accepted.value.state).toBe('accepted');
+    expect(accepted.value.mesh).not.toBe(source);
+    source.vertices[0] = 99;
+    expect(accepted.value.mesh.vertices[0]).toBe(0);
+    const receiptsBefore = lifecycle.publishFrame({ frameId: 4, deviceGeneration: 2 });
+    expect(receiptsBefore).toEqual([]);
+    const receipts = lifecycle.publishFrame({ frameId: 5, deviceGeneration: 3 });
+    expect(receipts).toHaveLength(1);
+    expect(receipts[0]).toMatchObject({
+      candidateId: accepted.value.candidateId,
+      frameId: 5,
+      topologyRevision: 7,
+      recordStageConsumed: false,
+    });
+    expect(lifecycle.receipt(accepted.value)).toMatchObject({
+      candidateId: accepted.value.candidateId,
+      frameId: 5,
+      deviceGeneration: 3,
+    });
+    expect(lifecycle.inspect()).toMatchObject({
+      generation: 3,
+      published: 1,
+      latestRevision: 1,
+      latestFrameId: 5,
+    });
+    expect(lifecycle.retire(accepted.value).ok).toBe(true);
+    expect(lifecycle.finalizeRetirement(accepted.value).ok).toBe(true);
+    const stale = lifecycle.prepare({ world, mesh: mesh(), revision: 1 }, 3);
+    expect(stale.ok).toBe(true);
+    if (!stale.ok) return;
+    expect(lifecycle.accept(stale.value)).toMatchObject({
+      ok: false,
+      error: { code: 'dynamic-geometry-stale' },
+    });
+  });
+
+  it('keeps old state when preparation is invalid and bounds in-flight work', () => {
+    const lifecycle = createDynamicGeometryLifecycle(1);
+    const world = {};
+    const first = lifecycle.prepare({ world, mesh: mesh(), revision: 1 }, 1);
+    expect(first.ok).toBe(true);
+    const invalid = lifecycle.prepare(
+      { world, mesh: { ...mesh(), vertices: new Float32Array() }, revision: 2 },
+      1,
+    );
+    expect(invalid.ok).toBe(false);
+    if (!first.ok) return;
+    expect(lifecycle.cancel(first.value).ok).toBe(true);
+    const replacement = lifecycle.prepare({ world, mesh: mesh(), revision: 2 }, 1);
+    expect(replacement.ok).toBe(true);
+  });
+
+  it('invalidates candidates on world teardown and device-generation change', () => {
+    const lifecycle = createDynamicGeometryLifecycle();
+    const world = {};
+    const prepared = lifecycle.prepare({ world, mesh: mesh(), revision: 1 }, 1);
+    expect(prepared.ok).toBe(true);
+    lifecycle.invalidateWorld(world);
+    expect(lifecycle.inspect()).toMatchObject({ prepared: 0, invalidated: 1 });
+    const next = lifecycle.prepare({ world, mesh: mesh(), revision: 2 }, 1);
+    expect(next.ok).toBe(true);
+    lifecycle.invalidateGeneration(2);
+    expect(lifecycle.inspect()).toMatchObject({ generation: 2, prepared: 0, invalidated: 2 });
+  });
+
+  it('rejects cross-lifecycle credentials and publishes only the ordered World step', () => {
+    const lifecycle = createDynamicGeometryLifecycle();
+    const otherLifecycle = createDynamicGeometryLifecycle();
+    const world = {};
+    const otherWorld = {};
+    const prepared = lifecycle.prepare({ world, mesh: mesh(), revision: 1 }, 1);
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    expect(otherLifecycle.accept(prepared.value)).toMatchObject({
+      ok: false,
+      error: { code: 'dynamic-geometry-candidate-not-found' },
+    });
+    const colliding = otherLifecycle.prepare({ world, mesh: mesh(), revision: 1 }, 1);
+    expect(colliding.ok).toBe(true);
+    if (!colliding.ok) return;
+    expect(colliding.value.candidateId).toBe(prepared.value.candidateId);
+    expect(lifecycle.receipt(colliding.value)).toBeUndefined();
+    const accepted = lifecycle.accept(prepared.value, { world, fixedStep: 4 });
+    expect(accepted.ok).toBe(true);
+    if (!accepted.ok) return;
+    expect(lifecycle.publishFrame({ frameId: 1, deviceGeneration: 1 }, [otherWorld], 4)).toEqual(
+      [],
+    );
+    expect(lifecycle.publishFrame({ frameId: 2, deviceGeneration: 1 }, [world], 3)).toEqual([]);
+    expect(lifecycle.publishFrame({ frameId: 3, deviceGeneration: 1 }, [world], 4)).toHaveLength(1);
+  });
+
+  it('rejects a lower prepared revision after a newer candidate is prepared', () => {
+    const lifecycle = createDynamicGeometryLifecycle();
+    const world = {};
+    const newer = lifecycle.prepare({ world, mesh: mesh(), revision: 4, topologyRevision: 1 }, 1);
+    const older = lifecycle.prepare({ world, mesh: mesh(), revision: 3, topologyRevision: 1 }, 1);
+    expect(newer.ok).toBe(true);
+    expect(older.ok).toBe(true);
+    if (!newer.ok || !older.ok) return;
+
+    expect(lifecycle.accept(newer.value)).toBeTruthy();
+    expect(lifecycle.accept(older.value)).toMatchObject({
+      ok: false,
+      error: { code: 'dynamic-geometry-stale' },
+    });
+    expect(lifecycle.publishFrame({ frameId: 1, deviceGeneration: 1 })).toHaveLength(1);
+    expect(lifecycle.inspect()).toMatchObject({ latestRevision: 4 });
+  });
+
+  it('invalidates topology history while retaining the published receipt fence', () => {
+    const lifecycle = createDynamicGeometryLifecycle();
+    const world = {};
+    const previous = lifecycle.prepare(
+      { world, mesh: mesh(), revision: 1, topologyRevision: 1 },
+      1,
+    );
+    expect(previous.ok).toBe(true);
+    if (!previous.ok) return;
+    const acceptedPrevious = lifecycle.accept(previous.value);
+    expect(acceptedPrevious.ok).toBe(true);
+    if (!acceptedPrevious.ok) return;
+    expect(lifecycle.publishFrame({ frameId: 1, deviceGeneration: 1 })).toHaveLength(1);
+    expect(lifecycle.receipt(acceptedPrevious.value)).toMatchObject({ frameId: 1 });
+
+    const replacement = lifecycle.prepare(
+      { world, mesh: mesh(), revision: 2, topologyRevision: 2 },
+      1,
+    );
+    expect(replacement.ok).toBe(true);
+    if (!replacement.ok) return;
+    expect(lifecycle.accept(replacement.value).ok).toBe(true);
+    // Topology invalidates temporal history but must preserve the published
+    // receipt fence until explicit retirement can hand GPU destruction to the
+    // completion promise.
+    expect(lifecycle.receipt(acceptedPrevious.value)).toMatchObject({ frameId: 1 });
+    expect(lifecycle.inspect()).toMatchObject({ historyInvalidations: 1, invalidated: 1 });
+    expect(lifecycle.retire(acceptedPrevious.value).ok).toBe(true);
+    expect(lifecycle.finalizeRetirement(acceptedPrevious.value).ok).toBe(true);
+  });
+
+  it('rejects a topology revision that regresses after a newer history was accepted', () => {
+    const lifecycle = createDynamicGeometryLifecycle();
+    const world = {};
+    const current = lifecycle.prepare({ world, mesh: mesh(), revision: 2, topologyRevision: 4 }, 1);
+    expect(current.ok).toBe(true);
+    if (!current.ok) return;
+    expect(lifecycle.accept(current.value).ok).toBe(true);
+    expect(lifecycle.publishFrame({ frameId: 1, deviceGeneration: 1 })).toHaveLength(1);
+
+    const regressed = lifecycle.prepare(
+      { world, mesh: mesh(), revision: 3, topologyRevision: 3 },
+      1,
+    );
+    expect(regressed.ok).toBe(true);
+    if (!regressed.ok) return;
+    expect(lifecycle.accept(regressed.value)).toMatchObject({
+      ok: false,
+      error: { code: 'dynamic-geometry-stale' },
+    });
+  });
+
+  it('accounts for mesh bytes, rejects unknown retirement, and preserves a multi-step receipt', () => {
+    const world = {};
+    const lifecycle = createDynamicGeometryLifecycle(4, 1_000);
+    const prepared = lifecycle.prepare({ world, mesh: mesh(), revision: 1, fixedStep: 2 }, 1);
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    expect(lifecycle.inspect().meshBytes).toBeGreaterThan(0);
+    const tooLarge = lifecycle.prepare(
+      { world, mesh: { ...mesh(), vertices: new Float32Array(3_000) }, revision: 2 },
+      1,
+    );
+    expect(tooLarge).toMatchObject({
+      ok: false,
+      error: { code: 'dynamic-geometry-budget-exceeded' },
+    });
+    expect(lifecycle.accept(prepared.value).ok).toBe(true);
+    const completed = Promise.resolve();
+    const receipts = lifecycle.publishFrame(
+      { frameId: 4, deviceGeneration: 1, completed },
+      [world],
+      5,
+    );
+    expect(receipts).toHaveLength(1);
+    expect(receipts[0]).toMatchObject({
+      fixedStep: 2,
+      publicationFixedStep: 5,
+      recordStageConsumed: false,
+      frame: { completed },
+    });
+    expect(lifecycle.retire({ ...prepared.value, candidateId: 'unknown' })).toMatchObject({
+      ok: false,
+      error: { code: 'dynamic-geometry-candidate-not-found' },
+    });
+    expect(lifecycle.retire(prepared.value).ok).toBe(true);
+    expect(lifecycle.finalizeRetirement(prepared.value).ok).toBe(true);
+    expect(lifecycle.inspect().meshBytes).toBe(0);
+  });
+});

package/src/__tests__/factory-contract.integration.test.ts

@@ -5,7 +5,7 @@ import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
 import { createProfiler } from '@forgeax/engine-profiler';
 import { DEFAULT_STANDARD_PROFILE } from '@forgeax/engine-render';
-import { RhiError, type ShaderModule } from '@forgeax/engine-rhi';
+import { RhiError, type RhiWebgpuRuntimeCause, type ShaderModule } from '@forgeax/engine-rhi';
 import {
   RhiNullAdapter,
   RhiNullCommandEncoder,
@@ -27,6 +27,7 @@ import {
   Camera as LocalCamera,
   TONEMAP_ACES_FILMIC,
 } from '../components/camera';
+import { TemporalFrameSubmitError } from '../errors/render';
 import type { RenderFeature } from '../features/types';
 import { renderLifecycleManifestUrl } from './shader-manifest-fixture';
 
@@ -144,6 +145,54 @@ describe('factory contract', () => {
     expect(profiler.phaseCatalog.render).toEqual([]);
   });
 
+  it('preserves a PipelineSpecError and its structured GPU cause during initialization', async () => {
+    const original = RhiNullDevice.prototype.createRenderPipeline;
+    const failure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'the GPU accepts the pre-warmed render pipeline descriptor',
+      hint: 'inspect the backend gpuMessage for the rejected descriptor',
+    });
+    let injected = false;
+    const operation = vi.spyOn(RhiNullDevice.prototype, 'createRenderPipeline');
+    operation.mockImplementation(function (this: RhiNullDevice, ...args: never[]) {
+      if (!injected) {
+        injected = true;
+        return err(failure) as never;
+      }
+      return Reflect.apply(original as (...input: never[]) => unknown, this, args) as never;
+    } as never);
+
+    try {
+      const renderer = await constructRenderer(
+        { getContext: () => null },
+        { rhi },
+        { shaderManifestUrl: renderLifecycleManifestUrl() },
+      );
+      const ready = await renderer.initialization;
+      expect(injected).toBe(true);
+      expect(ready.ok).toBe(false);
+      if (ready.ok) return;
+      expect(ready.error).toMatchObject({
+        code: 'webgpu-runtime-error',
+        detail: {
+          error: {
+            code: 'pipeline-build-failed',
+            detail: { cause: failure },
+          },
+        },
+      });
+      await renderer.dispose();
+    } finally {
+      operation.mockRestore();
+    }
+  });
+
+  it('keeps named temporal causes assignable without flattening their detail', () => {
+    const temporal = new TemporalFrameSubmitError('queue-submit-failed');
+    const cause: RhiWebgpuRuntimeCause = temporal;
+    expect(cause.detail).toEqual({ reason: 'queue-submit-failed' });
+  });
+
   it('forwards timing admission to the backend device request', async () => {
     const adapter = new RhiNullAdapter();
     const device = (await adapter.requestDevice()).unwrap();
@@ -178,6 +227,7 @@ describe('factory contract', () => {
       { rhi },
       { shaderManifestUrl: manifestUrl() },
     );
+    expect((await renderer.initialization).ok).toBe(true);
     const world = new World();
     const attached = renderer.attach(world);
     expect(attached.ok).toBe(true);
@@ -228,11 +278,13 @@ describe('factory contract', () => {
       // Before the first draw there is no committed graph from which to
       // claim an output transform or an intermediate target.  Inspection is
       // intentionally conservative instead of projecting profile defaults.
-      displayEncoded: false,
-      surfaceStorage: expect.any(String),
-      surfaceDisplay: expect.any(String),
-      endpoint: 'surface.storage.raw',
-      capability: 'unavailable',
+      output: {
+        displayEncoded: false,
+        surfaceStorage: expect.any(String),
+        surfaceDisplay: expect.any(String),
+        endpoint: 'surface.storage.raw',
+        capability: 'unavailable',
+      },
       observation: {
         observationId: expect.any(String),
         frameId: expect.any(Number),
@@ -250,6 +302,7 @@ describe('factory contract', () => {
       { rhi },
       { shaderManifestUrl: manifestUrl() },
     );
+    expect((await renderer.initialization).ok).toBe(true);
     const target = renderer.createRenderTarget({
       shape: '2d',
       width: 17,
@@ -312,6 +365,7 @@ describe('factory contract', () => {
       { rhi, features: [feature] },
       { shaderManifestUrl: manifestUrl() },
     );
+    expect((await renderer.initialization).ok).toBe(true);
     const world = new World();
     const attached = renderer.attach(world);
     expect(attached.ok).toBe(true);
@@ -474,7 +528,11 @@ describe('factory contract', () => {
     );
     expect((await renderer.initialization).ok).toBe(true);
     const errors: string[] = [];
-    const unsubscribe = renderer.onError((error) => errors.push(error.code));
+    const errorDetails: unknown[] = [];
+    const unsubscribe = renderer.onError((error) => {
+      errors.push(error.code);
+      errorDetails.push(error);
+    });
     const world = new World();
     const attached = renderer.attach(world);
     expect(attached.ok).toBe(true);
@@ -516,7 +574,7 @@ describe('factory contract', () => {
       camera: { lease: attached.value },
       environment: { lease: attached.value },
     });
-    expect(frame.ok).toBe(true);
+    expect(frame.ok, JSON.stringify(errorDetails)).toBe(true);
     expect(renderer.inspect().standardLighting).toMatchObject({
       producer: 'none',
       requested: 0,
@@ -611,6 +669,7 @@ describe('factory contract', () => {
       { rhi },
       { shaderManifestUrl: manifest },
     );
+    expect((await renderer.initialization).ok).toBe(true);
     expect(renderer.releaseSurface().ok).toBe(true);
     expect(renderer.releaseSurface().ok).toBe(true);
     expect(renderer.draw([], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(false);
@@ -651,7 +710,7 @@ describe('factory contract', () => {
     expect(unconfigureCalls).toBe(1);
   });
 
-  it('invalidates deferred TAA shader epochs across off and dispose', async () => {
+  it('retains the device-owned prewarmed TAA shader across off and on', async () => {
     const pending: Array<{
       readonly label: string;
       readonly promise: Promise<ReturnType<typeof ok<ShaderModule>>>;
@@ -682,7 +741,6 @@ describe('factory contract', () => {
     );
     await vi.waitFor(() => expect(pending).toHaveLength(1));
     const initialization = renderer.initialization;
-    const firstPromise = pending[0]?.promise;
     pending[0]?.resolve(ok({} as ShaderModule));
     expect((await initialization).ok).toBe(true);
 
@@ -730,12 +788,8 @@ describe('factory contract', () => {
     world.set(camera, LocalCamera, { antialias: ANTIALIAS_TAA }).unwrap();
     expect(world.update().ok).toBe(true);
     const second = renderer.draw(frameInput());
-    expect(second.ok).toBe(false);
-    expect(pending).toHaveLength(2);
-    expect(pending[1]?.promise).not.toBe(firstPromise);
-
-    pending[1]?.resolve(ok({} as ShaderModule));
-    await pending[1]?.promise;
+    expect(second.ok).toBe(true);
+    expect(pending).toHaveLength(1);
     expect(renderer.draw(frameInput()).ok).toBe(true);
     world.set(camera, LocalCamera, { antialias: ANTIALIAS_NONE }).unwrap();
     expect(world.update().ok).toBe(true);
@@ -743,17 +797,14 @@ describe('factory contract', () => {
     world.set(camera, LocalCamera, { antialias: ANTIALIAS_TAA }).unwrap();
     expect(world.update().ok).toBe(true);
     const replacement = renderer.draw(frameInput());
-    expect(replacement.ok).toBe(false);
-    expect(pending).toHaveLength(3);
-    expect(pending[2]?.promise).not.toBe(pending[1]?.promise);
+    expect(replacement.ok).toBe(true);
+    expect(pending).toHaveLength(1);
 
     expect((await renderer.dispose()).ok).toBe(true);
     expect((await renderer.dispose()).ok).toBe(true);
-    pending[2]?.resolve(ok({} as ShaderModule));
-    await pending[2]?.promise;
     expect(
       moduleCalls.filter((label) => label.startsWith('post-process-forgeax.taa-resolve-pso-')),
-    ).toHaveLength(3);
+    ).toHaveLength(1);
   });
 
   it('rebuilds a TAA graph for a same-mode target resize', async () => {

package/src/__tests__/fallback-row-stride-surface.unit.test.ts

@@ -15,4 +15,23 @@ describe('fallback texture row-stride owner', () => {
     expect(rendererSource).toContain('FALLBACK_BYTES_PER_ROW');
     expect(rendererSource).not.toMatch(/const FALLBACK_BYTES_PER_ROW\s*=\s*256/);
   });
+
+  it('uploads an exactly neutral normal instead of treating 128/255 as one half', () => {
+    const creation = rendererSource.slice(
+      rendererSource.indexOf('const fallbackNormalTextureResult ='),
+      rendererSource.indexOf('const fallbackNormalTextureViewResult ='),
+    );
+    expect(creation).toContain("format: 'rgba16float'");
+    const start = creation.indexOf('const fallbackNormalPixel =');
+    const end = creation.indexOf('const fallbackNormalWriteResult =');
+    // Execute the actual owner payload construction; do not duplicate its bytes.
+    const bytes = new Function(
+      'FALLBACK_BYTES_PER_ROW',
+      `${creation.slice(start, end)}; return fallbackNormalPixel;`,
+    )(FALLBACK_BYTES_PER_ROW) as Uint8Array;
+    const values = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    expect([0, 1, 2, 3].map((i) => values.getUint16(i * 2, true))).toEqual([
+      0x3800, 0x3800, 0x3c00, 0x3c00,
+    ]);
+  });
 });

package/src/__tests__/feature-depth-input.dawn.test.ts

@@ -0,0 +1,121 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+import { ok } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { createRenderFeatureGpuWorkOwner } from '../features/prepared-gpu-work';
+import { RenderFeatureComputeGraphProjection } from '../features/render-graph-compute';
+import { createRenderFeatureTarget } from '../features/targets';
+
+it('samples this frame graph depth after its producer on the real GPU', async () => {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  const device = (await adapter.requestDevice()).unwrap();
+  const code = `@group(0) @binding(0) var depth: texture_depth_2d;
+@group(0) @binding(1) var<storage, read_write> output: array<f32>;
+@compute @workgroup_size(1) fn sample() { output[0] = textureLoad(depth, vec2<i32>(0), 0); }`;
+  const shader = (await createShaderModule(device, { code })).unwrap();
+  const owner = createRenderFeatureGpuWorkOwner({
+    getDevice: () => device,
+    getShaderModuleFactory: () => ({ createShaderModule: () => ok(shader) }),
+  });
+  const session = owner.beginFeature('depth-input', 0);
+  const program = session
+    .prepareProgram('sample', {
+      wgsl: code,
+      entryPoints: ['sample'],
+      bindings: [
+        {
+          entries: [
+            { binding: 0, visibility: 4, texture: { sampleType: 'depth' } },
+            { binding: 1, visibility: 4, buffer: { type: 'storage' } },
+          ],
+        },
+      ],
+    })
+    .unwrap();
+  const output = session
+    .prepareBuffer('output', { size: 4, usage: ['storage', 'copy-src'] })
+    .unwrap();
+  const fallbackTexture = device
+    .createTexture({
+      size: { width: 1, height: 1 },
+      format: 'depth32float',
+      usage: 0x04 | 0x10,
+      textureBindingViewDimension: undefined,
+    })
+    .unwrap();
+  const fallback = device.createTextureView(fallbackTexture, {}).unwrap();
+  const depth = session
+    .prepareTextureView(
+      'depth',
+      fallback,
+      createRenderFeatureTarget({ kind: 'scene-depth', format: 'depth32float', sampleCount: 1 }),
+    )
+    .unwrap();
+  const bindings = session
+    .prepareBindings('bindings', {
+      program,
+      entries: [
+        { binding: 0, resource: { kind: 'texture-view', reference: depth } },
+        { binding: 1, buffer: output },
+      ],
+    })
+    .unwrap();
+  const work = session
+    .resolveComputePass('depth-input', {
+      program,
+      bindings,
+      dispatches: [{ entryPoint: 'sample', workgroups: [1] }],
+    })
+    .unwrap();
+  const source = session.resolveBuffer(output);
+  if (source === undefined) throw new Error('Missing output buffer');
+  const readback = device.createBuffer({ size: 4, usage: 0x01 | 0x08 }).unwrap();
+  try {
+    for (const expected of [0.25, 0.75]) {
+      const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+      const texture = graph
+        .createTexture('current-depth', {
+          format: 'depth32float',
+          size: { width: 1, height: 1 },
+        })
+        .unwrap();
+      const view = graph.view(texture).unwrap();
+      graph
+        .addRasterPass('depth-producer', {
+          colorAttachments: [],
+          depthStencilAttachment: {
+            view,
+            depthLoadOp: 'clear',
+            depthStoreOp: 'store',
+            depthClearValue: expected,
+          },
+          accesses: [{ resource: view, usage: 'depth-stencil-write' }],
+          encode: () => {},
+        })
+        .unwrap();
+      const projection = new RenderFeatureComputeGraphProjection(
+        graph,
+        undefined,
+        undefined,
+        () => ({ texture, view }),
+      );
+      projection.addPass('sample', 'depth-input', 0, work).unwrap();
+      const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+      const encoder = device.createCommandEncoder().unwrap();
+      compiled.execute({ encoder }).unwrap();
+      encoder.copyBufferToBuffer(source.buffer, 0, readback, 0, 4);
+      device.queue.submit([encoder.finish().unwrap()]).unwrap();
+      await device.queue.onSubmittedWorkDone();
+      const mapped = (await readback.mapAsync(1)).unwrap();
+      const actual = new DataView(mapped.getMappedRange().unwrap()).getFloat32(0, true);
+      mapped.unmap();
+      expect(actual).toBeCloseTo(expected, 6);
+      await compiled.retire();
+    }
+  } finally {
+    owner.dispose().unwrap();
+    device.destroyBuffer(readback).unwrap();
+    device.destroyTexture(fallbackTexture).unwrap();
+  }
+});

package/src/__tests__/feature-noise.unit.test.ts

@@ -0,0 +1,38 @@
+import type { RhiDevice, Texture, TextureView } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { createFeatureNoisePixels, createFeatureNoiseTexture } from '../features/noise-texture';
+
+it('provides deterministic spatial and channel variation instead of a uniform fallback', () => {
+  const pixels = createFeatureNoisePixels();
+  expect(pixels).toEqual(createFeatureNoisePixels());
+  expect(pixels).toHaveLength(64 * 64 * 4);
+  for (let channel = 0; channel < 4; channel++) {
+    const values = pixels.filter((_, index) => index % 4 === channel);
+    expect(new Set(values).size).toBe(256);
+    expect(values.reduce((sum, value) => sum + value, 0) / values.length).toBeGreaterThan(120);
+    expect(values.reduce((sum, value) => sum + value, 0) / values.length).toBeLessThan(135);
+  }
+});
+
+it('returns the generation-owned texture together with its view after upload', () => {
+  const texture = { id: 'noise-texture' } as unknown as Texture;
+  const view = { id: 'noise-view' } as unknown as TextureView;
+  let writes = 0;
+  const device = {
+    createTexture: () => ok(texture),
+    createTextureView: () => ok(view),
+    destroyTexture: () => ok(undefined),
+    queue: {
+      writeTexture: () => {
+        writes += 1;
+        return ok(undefined);
+      },
+    },
+  } as unknown as RhiDevice;
+
+  const result = createFeatureNoiseTexture(device);
+  expect(result.ok).toBe(true);
+  if (result.ok) expect(result.value).toEqual({ texture, view });
+  expect(writes).toBe(1);
+});