@forgeax/engine-render 0.1.7 → 0.1.19

package/src/__tests__/surface-configuration.unit.test.ts

@@ -1,7 +1,13 @@
 import type { RhiCanvasContext, RhiDevice } from '@forgeax/engine-rhi';
-import { ok } from '@forgeax/engine-rhi';
+import { ok, RhiError } from '@forgeax/engine-rhi';
 import { describe, expect, it, vi } from 'vitest';
-import { configureSurface, resolveSurfaceFormatPair } from '../render-system';
+import { createRenderSurfaceError, type RenderSurfaceFailureDetail } from '../errors/render';
+import {
+  configureSurface,
+  resolveSurfaceFormatPair,
+  resolveSurfaceProfile,
+  selectSwapChainFormat,
+} from '../render-system';
 
 function device(backendKind: 'webgpu' | 'wgpu-webgl2', storageBuffer = false): RhiDevice {
   return {
@@ -10,21 +16,72 @@ function device(backendKind: 'webgpu' | 'wgpu-webgl2', storageBuffer = false): R
   } as unknown as RhiDevice;
 }
 
+const webGlPresentationProof = {
+  descriptor: true,
+  acquisition: true,
+  validation: true,
+  surfaceIdentity: 'wgpu-surface:1',
+  requested: {
+    format: 'Rgba8Unorm',
+    usage: 0x10,
+    width: 800,
+    height: 600,
+    alphaMode: 'Auto',
+    presentMode: 'Fifo',
+  },
+  validated: {
+    format: 'Rgba8Unorm',
+    usage: 0x10,
+    width: 800,
+    height: 600,
+    alphaMode: 'Auto',
+    presentMode: 'Fifo',
+  },
+} as const;
+
 describe('configureSurface', () => {
+  it('exposes every surface failure with the four-field structured contract', () => {
+    const detail: RenderSurfaceFailureDetail = {
+      lane: 'direct',
+      stage: 'output-transform',
+      target: 'standard-output-color',
+      format: 'rgba16float',
+      domain: 'display-encoded',
+      endpoint: 'surface.storage',
+      capability: 'float-render-attachment',
+    };
+    for (const kind of [
+      'allocation',
+      'attachment',
+      'sampled-read',
+      'view-domain',
+      'raw-endpoint',
+    ] as const) {
+      const error = createRenderSurfaceError(kind, detail);
+      expect(error.code).toBe(`surface-${kind}-failed`);
+      expect(error.expected).toBeTruthy();
+      expect(error.hint).toBeTruthy();
+      expect(error.detail).toEqual(detail);
+    }
+  });
+
   it('projects the configured surface format into graph topology without reinterpretation drift', () => {
     expect(resolveSurfaceFormatPair('webgpu', 'bgra8unorm', 'bgra8unorm-srgb')).toEqual({
       storage: 'bgra8unorm',
       view: 'bgra8unorm-srgb',
     });
     expect(resolveSurfaceFormatPair('wgpu-webgl2', 'rgba8unorm', 'rgba8unorm-srgb')).toEqual({
-      storage: 'rgba8unorm-srgb',
+      storage: 'rgba8unorm',
       view: 'rgba8unorm-srgb',
     });
   });
 
   it('keeps native WebGPU sRGB view support when texture binding is available', () => {
     const configure = vi.fn(() => ok(undefined));
-    const context = { configure } as unknown as RhiCanvasContext;
+    const context = {
+      configure,
+      presentationProof: { descriptor: true, acquisition: true, validation: true },
+    } as unknown as RhiCanvasContext;
     const webGpuDevice = device('webgpu', true);
     const result = configureSurface(context, webGpuDevice, 'bgra8unorm', 'bgra8unorm-srgb');
     expect(result.ok).toBe(true);
@@ -39,7 +96,10 @@ describe('configureSurface', () => {
 
   it('keeps COPY_SRC on a low-capability WebGPU surface', () => {
     const configure = vi.fn(() => ok(undefined));
-    const context = { configure } as unknown as RhiCanvasContext;
+    const context = {
+      configure,
+      presentationProof: { descriptor: true, acquisition: true, validation: true },
+    } as unknown as RhiCanvasContext;
     const webGpuDevice = device('webgpu');
     const result = configureSurface(context, webGpuDevice, 'bgra8unorm', 'bgra8unorm-srgb');
     expect(result.ok).toBe(true);
@@ -52,25 +112,91 @@ describe('configureSurface', () => {
     });
   });
 
-  it('keeps the wgpu WebGL2 surface COLOR_TARGET-only', () => {
+  it('requests only guaranteed render attachment usage for WebGL2', () => {
     const configure = vi.fn(() => ok(undefined));
-    const context = { configure } as unknown as RhiCanvasContext;
+    const context = {
+      configure,
+      presentationProof: webGlPresentationProof,
+    } as unknown as RhiCanvasContext;
     const webGlDevice = device('wgpu-webgl2');
     const result = configureSurface(context, webGlDevice, 'rgba8unorm', 'rgba8unorm-srgb');
     expect(result.ok).toBe(true);
     expect(configure).toHaveBeenCalledWith({
       device: webGlDevice,
-      format: 'rgba8unorm-srgb',
+      format: 'rgba8unorm',
       alphaMode: 'opaque',
       usage: 0x10,
+      viewFormats: [],
     });
     const descriptor = (configure.mock.calls[0] as unknown as [Record<string, unknown>])[0];
-    expect(descriptor).not.toHaveProperty('viewFormats');
+    expect(descriptor.viewFormats).toEqual([]);
   });
 
-  it('uses the capability gate when WebGL2 reports a translated storage limit', () => {
+  it('configures a proof-less WebGL2 candidate before failing raw endpoint validation', () => {
+    const configure = vi.fn(() => ok(undefined));
+    const context = { configure } as unknown as RhiCanvasContext;
+    const result = configureSurface(
+      context,
+      device('wgpu-webgl2'),
+      'rgba8unorm',
+      'rgba8unorm-srgb',
+    );
+
+    expect(configure).toHaveBeenCalledOnce();
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('webgpu-runtime-error');
+      expect(result.error.expected).toContain('proof');
+    }
+  });
+
+  it.each([
+    ['descriptor', { descriptor: false, acquisition: true, validation: true }],
+    ['acquisition', { descriptor: true, acquisition: false, validation: true }],
+    ['validation', { descriptor: true, acquisition: true, validation: false }],
+  ] as const)('rejects a WebGL2 candidate with incomplete %s proof', (_missing, proof) => {
     const configure = vi.fn(() => ok(undefined));
+    const context = { configure, presentationProof: proof } as unknown as RhiCanvasContext;
+    const result = configureSurface(
+      context,
+      device('wgpu-webgl2'),
+      'rgba8unorm',
+      'rgba8unorm-srgb',
+    );
+
+    expect(configure).toHaveBeenCalledOnce();
+    expect(result.ok).toBe(false);
+    if (!result.ok)
+      expect(result.error.detail).toMatchObject({ error: { code: 'surface-raw-endpoint-failed' } });
+  });
+
+  it('keeps configure failures explicit without attempting to treat the surface as ready', () => {
+    const configure = vi.fn(() => ({
+      ok: false as const,
+      error: new RhiError({
+        code: 'webgpu-runtime-error',
+        expected: 'candidate configure succeeds',
+        hint: 'inspect the concrete configure failure',
+      }),
+    }));
     const context = { configure } as unknown as RhiCanvasContext;
+    const result = configureSurface(
+      context,
+      device('wgpu-webgl2'),
+      'rgba8unorm',
+      'rgba8unorm-srgb',
+    );
+
+    expect(configure).toHaveBeenCalledOnce();
+    expect(result.ok).toBe(false);
+  });
+
+  it('uses the capability gate when WebGL2 reports a translated storage limit', () => {
+    const configure = vi.fn(() => ok(undefined));
+    const context = {
+      configure,
+      presentationProof: webGlPresentationProof,
+    } as unknown as RhiCanvasContext;
     const webGlDevice = {
       limits: { maxStorageBuffersPerShaderStage: 8 },
       caps: { backendKind: 'wgpu-webgl2', storageBuffer: false },
@@ -81,11 +207,84 @@ describe('configureSurface', () => {
     expect(result.ok).toBe(true);
     expect(configure).toHaveBeenCalledWith({
       device: webGlDevice,
-      format: 'rgba8unorm-srgb',
+      format: 'rgba8unorm',
       alphaMode: 'opaque',
       usage: 0x10,
+      viewFormats: [],
     });
     const descriptor = (configure.mock.calls[0] as unknown as [Record<string, unknown>])[0];
-    expect(descriptor).not.toHaveProperty('viewFormats');
+    expect(descriptor.viewFormats).toEqual([]);
+  });
+
+  it('selects dual-view only when the concrete surface flag is present', () => {
+    const result = resolveSurfaceProfile('rgba8unorm', 'rgba8unorm-srgb', {
+      surfaceViewFormats: true,
+      rawAttachment: true,
+      floatRenderAttachment: true,
+    });
+    expect(result).toEqual({
+      ok: true,
+      value: {
+        kind: 'dual-view',
+        storageFormat: 'rgba8unorm',
+        viewFormat: 'rgba8unorm-srgb',
+        viewFormats: ['rgba8unorm-srgb'],
+        hasDisplayEndpoint: true,
+      },
+    });
+  });
+
+  it('selects raw-only without an alternate view when the flag is absent', () => {
+    const result = resolveSurfaceProfile('rgba8unorm', 'rgba8unorm-srgb', {
+      surfaceViewFormats: false,
+      rawAttachment: true,
+      floatRenderAttachment: true,
+    });
+    expect(result).toEqual({
+      ok: true,
+      value: {
+        kind: 'raw-only',
+        storageFormat: 'rgba8unorm',
+        viewFormat: 'rgba8unorm',
+        viewFormats: [],
+        hasDisplayEndpoint: false,
+      },
+    });
+  });
+
+  it('fails closed when raw-only has no float attachment capability', () => {
+    const result = resolveSurfaceProfile('rgba8unorm', 'rgba8unorm-srgb', {
+      surfaceViewFormats: false,
+      rawAttachment: true,
+      floatRenderAttachment: false,
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('webgpu-runtime-error');
+      expect(result.error.detail).toMatchObject({
+        error: { code: 'surface-raw-endpoint-failed' },
+      });
+    }
+  });
+
+  it('keeps the raw storage format when the preferred format API is present but views are unsupported', () => {
+    vi.stubGlobal('navigator', {
+      gpu: { getPreferredCanvasFormat: () => 'bgra8unorm' },
+    });
+    expect(selectSwapChainFormat(true, false)).toEqual({
+      storage: 'bgra8unorm',
+      view: 'bgra8unorm',
+    });
+    vi.unstubAllGlobals();
+  });
+
+  it('keeps the raw storage format when the preferred format API is absent and views are unsupported', () => {
+    vi.stubGlobal('navigator', {});
+    expect(selectSwapChainFormat(true, false)).toEqual({
+      storage: 'rgba8unorm',
+      view: 'rgba8unorm',
+      fallbackReason: 'preferred-canvas-format-missing',
+    });
+    vi.unstubAllGlobals();
   });
 });

package/src/__tests__/taa-transaction.integration.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { TemporalFrameCoordinator } from '../temporal/frame-coordinator';
+
+describe('TAA transaction integration', () => {
+  it('commits epoch, previous and history together only after submit', () => {
+    const coordinator = new TemporalFrameCoordinator<string>({ epoch: 0 });
+    const frame = coordinator.begin({ current: 'current-1', antialias: 'taa' });
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+
+    const committed = coordinator.commit(frame.value);
+    expect(committed.ok).toBe(true);
+    expect(coordinator.inspect()).toMatchObject({ epoch: 1, previous: 'current-1' });
+    expect(coordinator.inspect().historyAttempt).toBe('committed');
+  });
+
+  it('requires an explicit abort for a failed submission', () => {
+    const coordinator = new TemporalFrameCoordinator({ epoch: 2, previous: 'stable' });
+    const frame = coordinator.begin({ current: 'next', antialias: 'taa' });
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+    coordinator.abort(frame.value, 'submit');
+    expect(coordinator.inspect()).toMatchObject({ epoch: 2, previous: 'stable' });
+    expect(coordinator.historyStore.inspect()).toMatchObject({
+      attempt: 'aborted',
+      generation: 0,
+      valid: false,
+    });
+  });
+});

package/src/__tests__/temporal-admission.integration.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import {
+  aggregateTemporalDemand,
+  standardTemporalLaneAdmission,
+} from '../temporal/standard-scene-data';
+
+describe('temporal admission matrix', () => {
+  it.each([
+    'direct',
+    'clustered',
+    'cpu-webgl2',
+    'rhi-null',
+  ] as const)('admits one producer for TAA and Motion Blur on %s', (lane) => {
+    const admission = standardTemporalLaneAdmission({
+      lane,
+      demand: aggregateTemporalDemand({ taa: true, motionBlur: true }),
+      capabilities: {
+        compute: lane !== 'cpu-webgl2',
+        storageBuffer: lane !== 'cpu-webgl2',
+        rgba16floatRenderable: true,
+      },
+    });
+    expect(admission).toMatchObject({
+      status: 'available',
+      producerId: 'forgeax::standard::scene-data',
+      format: 'rgba16float',
+    });
+  });
+
+  it.each([
+    { taa: false, motionBlur: false },
+    { taa: true, motionBlur: false },
+    { taa: false, motionBlur: true },
+    { taa: true, motionBlur: true },
+  ])('keeps admission demand cardinality deterministic for %j', (input) => {
+    const demand = aggregateTemporalDemand(input);
+    expect(demand.producerPassCount).toBe(input.taa || input.motionBlur ? 1 : 0);
+    expect(demand.targetCount).toBe(input.taa || input.motionBlur ? 1 : 0);
+  });
+});

package/src/__tests__/temporal-coverage.unit.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { classifySceneDataCoverage, scanSceneDataCoverage } from '../temporal/coverage';
+
+describe('temporal contributor coverage', () => {
+  it('partitions exact, reactive, and missing contributors', () => {
+    const result = classifySceneDataCoverage({
+      contributors: [
+        { id: 'camera', kind: 'exact' },
+        { id: 'world', kind: 'reactive' },
+      ],
+      requiredContributorIds: ['camera', 'world', 'skin'],
+    });
+    expect(result).toEqual({
+      exactContributorIds: ['camera'],
+      reactiveContributorIds: ['world'],
+      missingContributorIds: ['skin'],
+      omittedMissingContributorCount: 0,
+      complete: false,
+    });
+  });
+
+  it('bounds missing IDs at 32 and preserves omitted count', () => {
+    const required = Array.from({ length: 40 }, (_, index) => `missing-${index}`);
+    const result = scanSceneDataCoverage({
+      schema: 'forgeax::scene-data::temporal-v1',
+      lane: 'direct',
+      producerId: 'forgeax::standard::scene-data',
+      contributorIds: [],
+      requiredContributorIds: required,
+    });
+    expect(result.complete).toBe(false);
+    expect(result.missingContributorIds).toHaveLength(32);
+    expect(result.omittedMissingContributorCount).toBe(8);
+  });
+});

package/src/__tests__/temporal-demand.unit.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { aggregateTemporalDemand, describeTemporalDemand } from '../temporal/standard-scene-data';
+
+describe('Standard temporal demand', () => {
+  it('keeps the disabled path at zero work before topology allocation', () => {
+    const demand = aggregateTemporalDemand({ taa: false, motionBlur: false });
+    expect(describeTemporalDemand(demand)).toEqual({
+      consumerCount: 0,
+      targetCount: 0,
+      producerPassCount: 0,
+      historyCount: 0,
+      byteLength: 0,
+    });
+  });
+
+  it.each([
+    ['taa', { taa: true, motionBlur: false }],
+    ['motion-blur', { taa: false, motionBlur: true }],
+    ['taa-and-motion-blur', { taa: true, motionBlur: true }],
+  ] as const)('deduplicates %s into one producer and target', (_name, input) => {
+    const demand = aggregateTemporalDemand(input);
+    expect(describeTemporalDemand(demand)).toMatchObject({
+      consumerCount: input.taa && input.motionBlur ? 2 : 1,
+      targetCount: 1,
+      producerPassCount: 1,
+      byteLength: 1,
+    });
+    expect(demand.historyCount).toBe(input.taa ? 1 : 0);
+  });
+
+  it('does not create a second producer when a consumer is repeated', () => {
+    const demand = aggregateTemporalDemand({ taa: true, motionBlur: true });
+    expect(demand.consumerIds).toEqual(['taa', 'motion-blur']);
+    expect(aggregateTemporalDemand({ taa: true, motionBlur: true })).toEqual(demand);
+  });
+
+  it('keeps zero work for a missing or identity Motion Blur component', () => {
+    expect(aggregateTemporalDemand({ taa: false, motionBlur: false })).toMatchObject({
+      targetCount: 0,
+      producerPassCount: 0,
+      historyCount: 0,
+    });
+  });
+});

package/src/__tests__/temporal-frame-coordinator.unit.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { TemporalFrameCoordinator } from '../temporal/frame-coordinator';
+
+describe('TemporalFrameCoordinator', () => {
+  it('keeps TAA state at the last submitted snapshot when a frame aborts', () => {
+    const coordinator = new TemporalFrameCoordinator({ epoch: 4, previous: 'frame-4' });
+    const candidate = coordinator.begin({ current: 'frame-5', antialias: 'taa' });
+
+    expect(candidate.ok).toBe(true);
+    if (!candidate.ok) return;
+    coordinator.abort(candidate.value, 'submit');
+
+    expect(coordinator.inspect()).toMatchObject({ epoch: 4, previous: 'frame-4' });
+    expect(coordinator.inspect().attempt).toBe('aborted');
+  });
+
+  it.each([
+    'build',
+    'encode',
+    'finish',
+    'submit',
+  ] as const)('does not advance state after %s failure', (stage) => {
+    const coordinator = new TemporalFrameCoordinator({ epoch: 7, previous: 'stable' });
+    const candidate = coordinator.begin({ current: 'candidate', antialias: 'taa' });
+    expect(candidate.ok).toBe(true);
+    if (!candidate.ok) return;
+    coordinator.abort(candidate.value, stage);
+    expect(coordinator.inspect().epoch).toBe(7);
+    expect(coordinator.inspect().previous).toBe('stable');
+  });
+
+  it('does not silently turn an unavailable TAA request into no-AA', () => {
+    const coordinator = new TemporalFrameCoordinator();
+    const result = coordinator.begin({ current: 'frame', antialias: 'taa', available: false });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('taa-unavailable');
+  });
+
+  it('keeps Motion Blur-only retries in the shared submit transaction', () => {
+    const coordinator = new TemporalFrameCoordinator({ epoch: 4, previous: 'frame-4' });
+    const failed = coordinator.begin({
+      current: 'frame-5',
+      antialias: 'none',
+      temporalDemand: true,
+    });
+
+    expect(failed.ok).toBe(true);
+    if (!failed.ok) return;
+    coordinator.abort(failed.value, 'submit');
+    expect(coordinator.inspect()).toMatchObject({ epoch: 4, previous: 'frame-4' });
+
+    const retry = coordinator.begin({
+      current: 'frame-5',
+      antialias: 'none',
+      temporalDemand: true,
+    });
+    expect(retry.ok).toBe(true);
+    if (!retry.ok) return;
+    const committed = coordinator.commit(retry.value);
+    expect(committed.ok).toBe(true);
+    expect(coordinator.inspect()).toMatchObject({ epoch: 5, previous: 'frame-5' });
+  });
+});

package/src/__tests__/temporal-graph-topology.unit.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { createTemporalGraphRoster } from '../record/typed-frame-graph';
+
+describe('TAA graph topology', () => {
+  it('uses one shared temporal target and one resolve in both lighting lanes', () => {
+    const direct = createTemporalGraphRoster({ antialias: 'taa', lane: 'direct' });
+    const clustered = createTemporalGraphRoster({ antialias: 'taa', lane: 'clustered' });
+    expect(direct).toEqual(clustered);
+    expect(direct.targets).toEqual([
+      'standard-scene-temporal',
+      'taa-history-current-color',
+      'taa-history-previous-color',
+      'taa-history-current-temporal',
+      'taa-history-previous-temporal',
+    ]);
+    expect(direct.passes.filter((name) => name === 'taa-resolve')).toHaveLength(1);
+    expect(direct.passes.indexOf('taa-resolve')).toBeLessThan(
+      direct.passes.indexOf('output-transform'),
+    );
+  });
+
+  it('keeps the disabled roster exactly empty', () => {
+    expect(createTemporalGraphRoster({ antialias: 'none', lane: 'direct' })).toEqual({
+      targets: [],
+      passes: [],
+      uploads: 0,
+    });
+    expect(createTemporalGraphRoster({ antialias: 'fxaa', lane: 'clustered' })).toEqual({
+      targets: [],
+      passes: [],
+      uploads: 0,
+    });
+  });
+
+  it('admits TAA only when MRT and rgba16float render/sample capabilities agree', () => {
+    expect(
+      createTemporalGraphRoster({
+        antialias: 'taa',
+        lane: 'direct',
+        capabilities: { rgba16floatRender: true, rgba16floatSample: true, mrt: true },
+      }).enabled,
+    ).toBe(true);
+    expect(
+      createTemporalGraphRoster({
+        antialias: 'taa',
+        lane: 'direct',
+        capabilities: { rgba16floatRender: true, rgba16floatSample: false, mrt: true },
+      }).enabled,
+    ).toBe(false);
+  });
+});