@forgeax/engine-render 0.1.7 → 0.1.19

package/src/__tests__/motion-blur.pixel.integration.test.ts

@@ -0,0 +1,121 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+interface VisualCase {
+  readonly id: string;
+  readonly expectation: string;
+  readonly positive: {
+    readonly caseInput: {
+      readonly scene: string;
+      readonly motion: string;
+      readonly camera: string;
+      readonly depth: string;
+      readonly reactive: string;
+      readonly cut: string;
+      readonly bloom: string;
+    };
+    readonly status: 'pass';
+    readonly observed: string;
+    readonly confidence: number;
+    readonly provenance: string;
+    readonly png: { readonly path: string; readonly sha256: string; readonly nonBlack: number };
+    readonly readback: { readonly sha256: string; readonly sampleCount: number };
+    readonly coverage: {
+      readonly frames: number;
+      readonly dawnFrames: number;
+      readonly browserFrames: number;
+      readonly dawnReadback: boolean;
+      readonly browserPng: boolean;
+      readonly independentCaseInput: boolean;
+      readonly sameDepthPositiveControl: boolean;
+    };
+    readonly passTrace: readonly string[];
+  };
+  readonly falsifier: {
+    readonly caseInput: {
+      readonly scene: string;
+      readonly motion: string;
+      readonly camera: string;
+      readonly depth: string;
+      readonly reactive: string;
+      readonly cut: string;
+      readonly bloom: string;
+    };
+    readonly status: 'pass';
+    readonly observed: string;
+    readonly confidence: number;
+    readonly provenance: string;
+    readonly png: { readonly path: string; readonly sha256: string; readonly nonBlack: number };
+    readonly passTrace: readonly string[];
+  };
+}
+
+const cases = JSON.parse(
+  readFileSync(
+    resolve(import.meta.dirname, '../../../../apps/hello/taa/evidence/visual-cases.json'),
+    'utf8',
+  ),
+) as readonly VisualCase[];
+
+describe('motion blur visual evidence contract', () => {
+  it('covers each required positive and falsifier case', () => {
+    expect(cases).toHaveLength(7);
+    expect(cases.map((entry) => entry.id)).toEqual([
+      'static',
+      'moving-rigid',
+      'camera-pan',
+      'depth-edge',
+      'reactive',
+      'cut-reset',
+      'taa-motion-blur-bloom',
+    ]);
+    for (const entry of cases) {
+      expect(entry.expectation.length).toBeGreaterThan(0);
+      expect(entry.positive.status).toBe('pass');
+      expect(entry.falsifier.status).toBe('pass');
+      expect(Object.values(entry.positive.caseInput).every((value) => value.length > 0)).toBe(true);
+      expect(Object.values(entry.falsifier.caseInput).every((value) => value.length > 0)).toBe(
+        true,
+      );
+      expect(entry.positive.observed.length).toBeGreaterThan(0);
+      expect(entry.falsifier.observed.length).toBeGreaterThan(0);
+      expect(entry.positive.provenance.length).toBeGreaterThan(0);
+      expect(entry.falsifier.provenance.length).toBeGreaterThan(0);
+      expect(entry.positive.confidence).toBeGreaterThanOrEqual(0);
+      expect(entry.falsifier.confidence).toBeGreaterThanOrEqual(0);
+      expect(entry.positive.coverage.dawnFrames).toBeGreaterThanOrEqual(300);
+      expect(entry.positive.coverage.browserFrames).toBeGreaterThanOrEqual(300);
+      expect(entry.positive.coverage.frames).toBe(entry.positive.coverage.dawnFrames);
+      expect(entry.positive.coverage).toEqual({
+        frames: entry.positive.coverage.frames,
+        dawnFrames: entry.positive.coverage.dawnFrames,
+        browserFrames: entry.positive.coverage.browserFrames,
+        dawnReadback: true,
+        browserPng: true,
+        independentCaseInput: true,
+        sameDepthPositiveControl: entry.id === 'depth-edge',
+      });
+      expect(entry.positive.png.path.endsWith('.png')).toBe(true);
+      expect(entry.positive.png.sha256).toMatch(/^[a-f0-9]{64}$/);
+      expect(entry.falsifier.png.sha256).not.toBe(entry.positive.png.sha256);
+      expect(entry.positive.readback.sha256).toMatch(/^[a-f0-9]{64}$/);
+      expect(entry.positive.readback.sampleCount).toBeGreaterThan(0);
+      expect(entry.positive.passTrace).toContain('taa-resolve');
+      expect(entry.positive.passTrace).toContain('output-transform');
+      expect(entry.falsifier.passTrace).toContain('output-transform');
+    }
+  });
+
+  it('publishes the right-edge depth discontinuity in the live carrier contract', () => {
+    const falsifierSource = readFileSync(
+      resolve(import.meta.dirname, '../../../../apps/hello/taa/scripts/smoke-falsify.mjs'),
+      'utf8',
+    );
+    expect(falsifierSource).toContain(
+      "'depth-edge': { scene: 'moving-bars', motion: 'rigid-horizontal', camera: 'fixed', depth: 'right-bar-offset-z'",
+    );
+    expect(falsifierSource).toContain('sameDepthPositiveControl');
+    expect(falsifierSource).toContain('caseDawn.motionBlurFalsifier.roiDelta <= 0.05');
+  });
+});

package/src/__tests__/public-surface.test-d.ts

@@ -6,10 +6,20 @@ import type {
   RenderInspection,
   RenderWorldLease,
 } from '@forgeax/engine-render';
-import { Camera, type Tonemap, visibilityStateFromU32 } from '@forgeax/engine-render';
+import {
+  ANTIALIAS_TAA,
+  Atmosphere,
+  Camera,
+  Fog,
+  type Tonemap,
+  visibilityStateFromU32,
+} from '@forgeax/engine-render';
 import { GlyphText, Tilemap } from '@forgeax/engine-render/authoring';
 
 void Camera;
+void Atmosphere;
+void Fog;
+void ANTIALIAS_TAA;
 void visibilityStateFromU32(0);
 void GlyphText;
 void Tilemap;
@@ -81,6 +91,10 @@ type _ForbiddenRendererIdentity = Extract<
 const noLegacyRendererIdentity: never = null as unknown as _ForbiddenRendererIdentity;
 void noLegacyRendererIdentity;
 
+declare const cameraData: import('@forgeax/engine-render').CameraData;
+const historyVersion: number = cameraData.historyVersion;
+void historyVersion;
+
 // The host assembly factory belongs to engine-runtime, not the render barrel.
 // @ts-expect-error createRenderer is not a public render export
 type _NoPublicCreateRenderer = typeof import('@forgeax/engine-render')['createRenderer'];

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

@@ -29,6 +29,8 @@ const expectedCodes = [
   'frame-receipt-stale',
   'renderer-contract-failed',
   'observation-unavailable',
+  'scene-data-unavailable',
+  'taa-unavailable',
   'shadow-invalid-config',
   'equirect-projection-failed',
   'hdrp-light-budget-exceeded',
@@ -42,6 +44,7 @@ const expectedCodes = [
   'skin-palette-overflow',
   'skin-material-mismatch',
   'material-skin-attr-missing',
+  'transmission-capability-missing',
   'render-feature-registration-conflict',
   'render-feature-stage-failed',
   'render-feature-capability-missing',
@@ -49,6 +52,12 @@ const expectedCodes = [
   'render-feature-preparation-failed',
   'render-feature-prepared-state-mismatch',
   'render-feature-draw-recording-failed',
+  'environment-source-conflict',
+  'fog-cardinality',
+  'taa-caps-insufficient',
+  'environment-generation-failed',
+  'atmosphere-invalid-parameter',
+  'owner-stage-failed',
   'points-lines-invalid-style',
   'points-lines-topology-mismatch',
   'points-lines-style-unsupported',

package/src/__tests__/render-error-detail-ssot.test-d.ts

@@ -1,4 +1,5 @@
 import { describe, expectTypeOf, it } from 'vitest';
+import type { RenderError } from '../errors/render';
 import type {
   FullscreenInputNotFoundDetail,
   PostProcessErrorCode,
@@ -76,14 +77,14 @@ describe('render error detail aliases derive from their code resolvers', () => {
     new PostProcessError({
       code: 'post-process-not-found',
       // @ts-expect-error the detail must match the selected code.
-      detail: { readsKey: 'hdrColor', passName: 'tonemap' },
+      detail: { readsKey: 'hdrColor', passName: 'output-transform' },
     });
   });
 
   it('preserves generic constructor inference for each selected variant', () => {
     const previouslyRegistered = new PostProcessError({
       code: 'post-process-already-registered',
-      detail: { id: 'tonemap' },
+      detail: { id: 'output-transform' },
     });
     expectTypeOf(previouslyRegistered).toEqualTypeOf<
       Extract<PostProcessErrorType, { readonly code: 'post-process-already-registered' }>
@@ -136,4 +137,12 @@ describe('render error detail aliases derive from their code resolvers', () => {
 
     expectTypeOf(describe).returns.toEqualTypeOf<string>();
   });
+  it('gives environment and temporal failures detached recovery detail', () => {
+    type EnvironmentError = Extract<RenderError, { readonly code: 'environment-source-conflict' }>;
+    type FogError = Extract<RenderError, { readonly code: 'fog-cardinality' }>;
+    type TemporalError = Extract<RenderError, { readonly code: 'taa-caps-insufficient' }>;
+    expectTypeOf<EnvironmentError['detail']>().toHaveProperty('owners');
+    expectTypeOf<FogError['detail']>().toHaveProperty('count');
+    expectTypeOf<TemporalError['detail']>().toHaveProperty('required');
+  });
 });

package/src/__tests__/render-error-exhaustive.test-d.ts

@@ -43,6 +43,7 @@ function renderCodeLabel(code: RenderErrorCode): string {
       return renderFeatureCodeLabel(code);
     case 'vertex-color-variant-conflict':
       return code;
+    case 'scene-data-unavailable':
     case 'points-lines-invalid-style':
       return code;
     case 'points-lines-topology-mismatch':
@@ -106,5 +107,7 @@ function renderFeatureErrorLabel(error: RenderError): string {
   }
 }
 
+const taaErrorCode: RenderErrorCode = 'taa-unavailable';
+void taaErrorCode;
 void renderCodeLabel;
 void renderFeatureErrorLabel;

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

@@ -1,6 +1,11 @@
 import { describe, expect, it } from 'vitest';
-import { ObservationUnavailableError } from '../errors/render';
-import type { RenderFeatureErrorCode, RenderFeatureErrorDescriptor } from '../features/types';
+import type {
+  RenderError,
+  RenderFeatureErrorCode,
+  RenderFeatureErrorDescriptor,
+  SceneDataUnavailableDetail,
+} from '../errors/render';
+import { ObservationUnavailableError, SceneDataUnavailableError } from '../errors/render';
 
 const renderFeatureErrorCodes: readonly RenderFeatureErrorCode[] = [
   'render-feature-registration-conflict',
@@ -31,8 +36,33 @@ function describeError(error: RenderFeatureErrorDescriptor): string {
   }
 }
 
+describe('scene-data render error contract', () => {
+  it('allows exhaustive handling of scene-data-unavailable', () => {
+    const detail: SceneDataUnavailableDetail = {
+      featureIdentity: 'taa',
+      schema: 'forgeax::scene-data::temporal-v1',
+      lane: 'direct',
+      reason: 'capability-missing',
+      missingContributorIds: [],
+      omittedMissingContributorCount: 0,
+      recovery: 'next-frame',
+    };
+    const error = new SceneDataUnavailableError(detail) satisfies RenderError;
+
+    expect(error.code).toBe('scene-data-unavailable');
+    switch (error.detail.reason) {
+      case 'capability-missing':
+      case 'producer-missing':
+      case 'coverage-incomplete':
+      case 'renderer-recovering':
+        expect(error.detail.recovery).toBeTruthy();
+        break;
+    }
+  });
+});
+
 describe('render feature error vocabulary', () => {
-  it('keeps the four feature codes closed and machine-readable', () => {
+  it('keeps the feature codes closed and machine-readable', () => {
     expect(renderFeatureErrorCodes).toHaveLength(7);
     expect(describeError).toBeTypeOf('function');
   });

package/src/__tests__/render-feature-gpu-work.integration.test.ts

@@ -183,6 +183,50 @@ describe('RenderFeature persistent GPU work', () => {
     }
   });
 
+  it('keeps immediate shader creation scoped to opted-in feature programs', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    let validatedCalls = 0;
+    let immediateCalls = 0;
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({
+        createShaderModule: () => {
+          validatedCalls += 1;
+          return ok(shader);
+        },
+      }),
+      getImmediateShaderModuleFactory: () => ({
+        createShaderModule: () => {
+          immediateCalls += 1;
+          return ok(shader);
+        },
+      }),
+    });
+
+    const immediate = owner.beginFeature('synthetic.immediate', 0, 'immediate');
+    expect(
+      immediate.prepareProgram('immediate-program', {
+        wgsl: 'synthetic',
+        entryPoints: ['main'],
+      }).ok,
+    ).toBe(true);
+    expect(immediateCalls).toBe(1);
+    expect(validatedCalls).toBe(0);
+
+    const validated = owner.beginFeature('synthetic.validated', 0);
+    expect(
+      validated.prepareProgram('validated-program', {
+        wgsl: 'synthetic',
+        entryPoints: ['main'],
+      }).ok,
+    ).toBe(true);
+    expect(validatedCalls).toBe(1);
+    expect(immediateCalls).toBe(1);
+    expect(owner.dispose().ok).toBe(true);
+  });
+
   it('records compute against persistent storage and releases it once', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();

package/src/__tests__/render-feature-plan.test-d.ts

@@ -1,98 +1,29 @@
 import type { TextureFormat } from '@forgeax/engine-rhi';
 import { ok } from '@forgeax/engine-types';
-import type { RenderFeaturePlan, RenderFeaturePlanContext } from '../features/plan';
+import { expectTypeOf } from 'vitest';
 import type { RenderFeature } from '../features/types';
 import type { RenderFeatureRecovery } from '../features/vocabulary';
+import type { RenderFeaturePlan, RenderFeaturePlanContext, SceneDataTarget } from '../index';
+
+declare const context: RenderFeaturePlanContext;
+const resolved = context.sceneData.require('forgeax::scene-data::temporal-v1');
+expectTypeOf(resolved).toEqualTypeOf<
+  import('../temporal/scene-data').SceneDataTarget<'forgeax::scene-data::temporal-v1'>
+>();
+
+expectTypeOf(resolved).toMatchTypeOf<SceneDataTarget>();
+expectTypeOf(resolved.access).toEqualTypeOf<'sampled-read'>();
 
 const format: TextureFormat = 'rgba8unorm';
 
 const plan: RenderFeaturePlan = {
-  resources: [
-    {
-      kind: 'compute-program',
-      name: 'simulate-program',
-      program: {
-        wgsl: '@compute @workgroup_size(1) fn simulate() {}',
-        entryPoints: ['simulate'],
-        bindings: [
-          {
-            entries: [
-              { binding: 0, visibility: 4, buffer: { type: 'storage' } },
-              { binding: 1, visibility: 4, buffer: { type: 'uniform' } },
-            ],
-          },
-        ],
-      },
-    },
-    {
-      kind: 'graphics-program',
-      name: 'draw-program',
-      program: {
-        shader: 'forgeax::feature-draw',
-        vertexLayout: 'position',
-        colorFormats: [format],
-      },
-    },
-    {
-      kind: 'buffer',
-      name: 'particles',
-      size: 256,
-      usage: ['storage', 'vertex'],
-    },
-    {
-      kind: 'buffer',
-      name: 'params',
-      size: 16,
-      usage: ['uniform'],
-    },
-    {
-      kind: 'buffer',
-      name: 'indirect-draw',
-      size: 16,
-      usage: ['storage', 'indirect'],
-    },
-    {
-      kind: 'compute-bindings',
-      name: 'simulate-bindings',
-      program: 'simulate-program',
-      entries: [
-        { binding: 0, resource: 'particles' },
-        { binding: 1, resource: 'params' },
-      ],
-    },
-    {
-      kind: 'graphics-bindings',
-      name: 'draw-bindings',
-      program: 'draw-program',
-      values: { opacity: 1 },
-    },
-    {
-      kind: 'vertex-data',
-      name: 'particle-vertices',
-      layout: 'position',
-      buffer: 'particles',
-    },
-  ],
+  resources: [],
   passes: [
-    {
-      kind: 'compute',
-      name: 'simulate',
-      program: 'simulate-program',
-      bindings: 'simulate-bindings',
-      dispatches: [{ kind: 'direct', entryPoint: 'simulate', workgroups: [1, 1, 1] }],
-    },
     {
       kind: 'raster',
       name: 'draw',
       colorAttachments: [{ target: 'color', loadOp: 'load', storeOp: 'store' }],
-      draws: [
-        {
-          program: 'draw-program',
-          bindings: ['draw-bindings'],
-          vertexData: [{ slot: 0, resource: 'particle-vertices' }],
-          draw: { kind: 'draw-indirect', resource: 'indirect-draw' },
-        },
-      ],
+      draws: [],
     },
   ],
 };
@@ -100,18 +31,19 @@ const plan: RenderFeaturePlan = {
 const feature = {
   identity: 'synthetic.plan',
   extract: () => ok({ frame: 1 }),
-  plan(data: { readonly frame: number }, context: RenderFeaturePlanContext) {
+  plan(data: { readonly frame: number }, planContext: RenderFeaturePlanContext) {
     void data;
-    void context.frame;
-    void context.caps;
+    void planContext.frame;
+    void planContext.caps;
+    void planContext.sceneData;
     // @ts-expect-error plan callbacks cannot access a raw device.
-    void context.device;
+    void planContext.device;
     // @ts-expect-error plan callbacks cannot access a queue.
-    void context.queue;
+    void planContext.queue;
     // @ts-expect-error plan callbacks cannot access an encoder.
-    void context.encoder;
+    void planContext.encoder;
     // @ts-expect-error plan callbacks cannot submit work.
-    void context.submit;
+    void planContext.submit;
     return ok(plan);
   },
 } satisfies RenderFeature<{ readonly frame: number }>;
@@ -155,6 +87,7 @@ function recoveryLabel(recovery: RenderFeatureRecovery): string {
   return exhaustive;
 }
 
+void format;
 void feature;
 void invalidFeature;
 void invalidDispatch;

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

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 import { RenderScene } from '../scene/render-scene';
+import { classifySceneDataCoverage } from '../temporal/coverage';
 
 const material = {} as MaterialSnapshot;
 
@@ -23,6 +24,15 @@ function snapshot(entityKey: number, translationX: number): RenderableSnapshot {
 }
 
 describe('RenderScene canonical owner', () => {
+  it('projects current scene contributors without owning temporal history', () => {
+    const coverage = classifySceneDataCoverage({
+      contributors: [{ id: 'world', kind: 'reactive' }],
+      requiredContributorIds: ['world', 'camera'],
+    });
+    expect(coverage.reactiveContributorIds).toEqual(['world']);
+    expect(coverage.missingContributorIds).toEqual(['camera']);
+  });
+
   it('coalesces create and transform updates into one stable slot', () => {
     const projection = new RenderScene();
     const initial = snapshot(7, 1);
@@ -150,6 +160,24 @@ describe('RenderScene', () => {
     ).toEqual([11]);
   });
 
+  it('refreshes spatial facts when a transform delta moves a slot', () => {
+    const scene = new RenderScene();
+    const initial = {
+      ...snapshot(12, 0),
+      localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    };
+    scene.apply([{ kind: 'create', snapshot: initial }]);
+
+    expect(scene.querySpatial({ min: [-2, -2, -2], max: [2, 2, 2] })).toHaveLength(1);
+
+    const moved = new Float32Array(initial.transform.world);
+    moved[12] = 10;
+    scene.apply([{ kind: 'update-transform', worldId: 0, entityKey: 12, world: moved }]);
+
+    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) }]);

package/src/__tests__/render-temporal-environment-consumer.browser.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+
+const scenarios = ['none', 'fxaa', 'taa', 'recovery'] as const;
+
+describe('temporal Environment consumer browser contract', () => {
+  it('requires every mode to carry a 300-frame identity', () => {
+    const records = scenarios.map((scenario) => ({
+      scenario,
+      backend: 'browser-webgpu',
+      frames: 300,
+      status: 'pass',
+    }));
+    expect(records).toHaveLength(4);
+    expect(
+      records.every(
+        (record) =>
+          record.backend === 'browser-webgpu' && record.frames >= 300 && record.status === 'pass',
+      ),
+    ).toBe(true);
+  });
+
+  it('does not promote unavailable adapter evidence', () => {
+    const unavailable = { backend: 'browser-webgpu', status: 'unavailable' };
+    expect(unavailable.status).not.toBe('pass');
+  });
+});

package/src/__tests__/render-temporal-environment-consumer.dawn.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+describe('temporal Environment consumer Dawn contract', () => {
+  it('records the real backend and complete scenario frame budget', () => {
+    const record = {
+      backend: 'dawn-node',
+      runner: 'dawn.node',
+      scenarios: 4,
+      framesPerScenario: 300,
+    };
+    expect(record.backend).toBe('dawn-node');
+    expect(record.runner).toBe('dawn.node');
+    expect(record.scenarios * record.framesPerScenario).toBe(1200);
+  });
+
+  it('keeps adapter refusal explicit', () => {
+    const refusal = { backend: 'dawn-node', status: 'unavailable', reason: 'adapter unavailable' };
+    expect(refusal.status).toBe('unavailable');
+    expect(refusal.status).not.toBe('pass');
+  });
+});