@forgeax/engine-runtime 0.1.2

package/src/__tests__/render-feature-recover.integration.test.ts

@@ -0,0 +1,142 @@
+import type { RenderFeature } from '@forgeax/engine-render';
+import {
+  createRenderFeatureHost,
+  RenderFeatureCapabilityMissingError,
+  RenderFeatureStageFailedError,
+  runRenderFeatureFrame,
+} from '@forgeax/engine-render/internal';
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+const caps = (compute: boolean): Readonly<RhiCaps> => ({ compute }) as unknown as RhiCaps;
+
+function recoverableFeature(calls: string[]): RenderFeature<{ readonly frame: number }> {
+  return {
+    identity: 'synthetic.recoverable',
+    requiredCapabilities: ['compute'],
+    extract: ({ frameNumber }) => {
+      calls.push(`extract:${frameNumber}`);
+      return ok({ frame: frameNumber });
+    },
+    prepare: (data) => {
+      calls.push(`prepare:${data.frame}`);
+      return ok(undefined);
+    },
+    contribute: (data) => {
+      calls.push(`contribute:${data.frame}`);
+      return ok(undefined);
+    },
+    recover: ({ frame }) => {
+      calls.push(`recover:${frame.frameNumber}`);
+      return ok(undefined);
+    },
+  };
+}
+
+describe('render feature recovery lifecycle', () => {
+  it('retries failed slots, gates missing capabilities, and re-evaluates on recover', () => {
+    const calls: string[] = [];
+    const host = createRenderFeatureHost([recoverableFeature(calls)], caps(true)).unwrap();
+
+    const first = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(true),
+    });
+    expect(first.stageEvents.map((event) => event.stage)).toEqual([
+      'extract',
+      'prepare',
+      'contribute',
+    ]);
+
+    host.setStatus(
+      'synthetic.recoverable',
+      'failed',
+      new RenderFeatureStageFailedError('synthetic.recoverable', 0, 'prepare', 'next-frame'),
+    );
+    const retry = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      caps: caps(true),
+    });
+    expect(retry.errors).toEqual([]);
+    expect(calls.slice(-3)).toEqual(['extract:2', 'prepare:2', 'contribute:2']);
+
+    host.setStatus('synthetic.recoverable', 'disabled');
+    const skipped = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 3,
+      caps: caps(true),
+    });
+    expect(skipped.stageEvents).toEqual([]);
+
+    const recovered = host.recover({ frameNumber: 4, caps: caps(true) });
+    expect(recovered).toEqual(ok(undefined));
+    expect(calls.at(-1)).toBe('recover:4');
+
+    const resumed = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 4,
+      caps: caps(true),
+    });
+    expect(resumed.errors).toEqual([]);
+    expect(resumed.stageEvents).toHaveLength(3);
+  });
+
+  it('keeps registration through a pipeline switch and makes dispose terminal', () => {
+    const calls: string[] = [];
+    const host = createRenderFeatureHost([recoverableFeature(calls)], caps(true)).unwrap();
+
+    const beforeSwitch = host.features;
+    const afterSwitch = host.features;
+    expect(afterSwitch).toBeTruthy();
+    expect(afterSwitch[0]?.identity).toBe(beforeSwitch[0]?.identity);
+
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(host.dispose()).toEqual(ok(undefined));
+    const afterDispose = host.recover({ frameNumber: 1, caps: caps(true) });
+    expect(afterDispose.ok).toBe(false);
+    if (!afterDispose.ok && afterDispose.error.code === 'render-feature-stage-failed') {
+      expect(afterDispose.error.code).toBe('render-feature-stage-failed');
+      expect(afterDispose.error.detail.stage).toBe('recover');
+    }
+    expect(
+      runRenderFeatureFrame(host, {
+        worlds: [],
+        owner: 0,
+        frameNumber: 2,
+        caps: caps(true),
+      }).stageEvents,
+    ).toEqual([]);
+    expect(calls).toEqual([]);
+  });
+
+  it('reports unsupported GPU capability as a structured fault and keeps the CPU lane available', () => {
+    const calls: string[] = [];
+    const host = createRenderFeatureHost([recoverableFeature(calls)], caps(false)).unwrap();
+
+    const frame = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 7,
+      caps: caps(false),
+    });
+
+    expect(frame.stageEvents).toEqual([]);
+    expect(frame.errors).toHaveLength(1);
+    const error = frame.errors[0];
+    expect(error).toMatchObject({
+      code: 'render-feature-capability-missing',
+      expected: expect.stringContaining("device capability 'compute'"),
+      hint: expect.stringContaining('compute'),
+      detail: { capability: 'compute' },
+    });
+    expect(calls).toEqual([]);
+    expect(error).toBeInstanceOf(RenderFeatureCapabilityMissingError);
+  });
+});

package/src/__tests__/render-feature-runtime-surface.test-d.ts

@@ -0,0 +1,45 @@
+import type {
+  Renderer,
+  RendererOptions,
+  RenderFeature,
+  RenderFeatureDiagnostics,
+} from '@forgeax/engine-render';
+import { ok } from '@forgeax/engine-types';
+import { createRenderer } from '../createRenderer';
+
+type FrameData = {
+  readonly visibleCount: number;
+};
+
+const feature = {
+  identity: 'test.runtime-public-surface',
+  extract({ owner }) {
+    return ok<FrameData>({ visibleCount: owner });
+  },
+  prepare(data: FrameData) {
+    const count: number = data.visibleCount;
+    void count;
+    return ok(undefined);
+  },
+  contribute(data: FrameData) {
+    const count: number = data.visibleCount;
+    void count;
+    return ok(undefined);
+  },
+} satisfies RenderFeature<FrameData>;
+
+declare const canvas: HTMLCanvasElement;
+
+const options: RendererOptions = { features: [feature] };
+const rendererPromise: Promise<Renderer> = createRenderer(canvas, options);
+const diagnostics = (renderer: Renderer): readonly RenderFeatureDiagnostics[] =>
+  renderer.renderFeatureDiagnostics();
+
+void rendererPromise;
+void diagnostics;
+
+// Runtime owns assembly; its public factory does not expose the internal host.
+// @ts-expect-error the feature host is private to engine-render
+type _NoRuntimeFeatureHost = typeof import('@forgeax/engine-runtime')['RenderFeatureHost'];
+// @ts-expect-error runtime does not expose manifest/RPC implementation symbols
+type _NoRuntimeBundlerOptions = typeof import('@forgeax/engine-runtime')['BundlerOptions'];

package/src/__tests__/render-feature-zero-feature.browser.test.ts

@@ -0,0 +1,152 @@
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import {
+  ANTIALIAS_FXAA,
+  Camera,
+  DirectionalLight,
+  MeshFilter,
+  MeshRenderer,
+  TONEMAP_REINHARD_EXTENDED,
+} from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Engine } from '../index';
+
+const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+const CLEAR_COLOR: readonly [number, number, number] = [0.06, 0.06, 0.08];
+
+function distanceFromClear(pixels: Uint8Array): number {
+  let maximum = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const red = (pixels[i] ?? 0) / 255;
+    const green = (pixels[i + 1] ?? 0) / 255;
+    const blue = (pixels[i + 2] ?? 0) / 255;
+    const distance = Math.hypot(
+      red - CLEAR_COLOR[0],
+      green - CLEAR_COLOR[1],
+      blue - CLEAR_COLOR[2],
+    );
+    maximum = Math.max(maximum, distance);
+  }
+  return maximum;
+}
+
+function makeBaselineWorld(): World {
+  const world = new World();
+  const triangleHandle = world.internSharedRef(
+    'MeshAsset',
+    createPrimitiveMesh('triangle').unwrap(),
+  );
+  world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: triangleHandle } },
+      { component: MeshRenderer, data: {} },
+    )
+    .unwrap();
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 3] } },
+      {
+        component: Camera,
+        data: {
+          fov: Math.PI / 4,
+          aspect: 1,
+          near: 0.1,
+          far: 100,
+          tonemap: TONEMAP_REINHARD_EXTENDED,
+          antialias: ANTIALIAS_FXAA,
+        },
+      },
+    )
+    .unwrap();
+  world.spawn({
+    component: DirectionalLight,
+    data: { direction: [-0.5, -1, -0.3], color: [1, 1, 1], intensity: 1 },
+  });
+  return world;
+}
+
+describe.skipIf(!browserReady)('zero-feature browser render baseline', () => {
+  let renderer: Awaited<ReturnType<typeof Engine.create>> | undefined;
+  let canvas: HTMLCanvasElement | undefined;
+
+  afterEach(() => {
+    // Browser Mode files share Chromium's GPU process. Do not dispose the
+    // renderer here: that destroys the shared device for the next file.
+    if (canvas?.parentNode !== null) canvas?.parentNode?.removeChild(canvas);
+    renderer = undefined;
+    canvas = undefined;
+  });
+
+  it('keeps the triangle visible with no registered render features', async () => {
+    canvas = document.createElement('canvas');
+    canvas.width = 200;
+    canvas.height = 150;
+    document.body.appendChild(canvas);
+
+    renderer = await Engine.create(canvas, {}, { shaderManifestUrl: '/shaders/manifest.json' });
+    const ready = await renderer.ready;
+    expect(ready.ok).toBe(true);
+
+    const errors: Array<{ code: string; hint: string }> = [];
+    renderer.onError((error) => errors.push({ code: error.code, hint: error.hint }));
+    const world = makeBaselineWorld();
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    for (let frame = 0; frame < 8; frame += 1) {
+      world.update(1 / 60).unwrap();
+      expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+      await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+    }
+
+    // Browser test isolation may retire a device after this renderer's frame
+    // work completes. That intentional teardown is already distinguished by
+    // the renderer's structured hint; every SUT-attributable error remains a
+    // hard failure here.
+    expect(
+      errors.filter(
+        (error) => !(error.code === 'device-lost' && error.hint.includes('reason: destroyed')),
+      ),
+    ).toEqual([]);
+    expect(renderer.renderFeatureDiagnostics()).toEqual([]);
+    const expectedPassNames = [
+      'gpu-driven.view-reset',
+      'gpu-driven.frustum-compact',
+      'gpu-driven.finalize-indirect',
+      'directional-shadow-reset',
+      'shadowCascade0',
+      'shadowCascade1',
+      'shadowCascade2',
+      'shadowCascade3',
+      'directional-shadow-observation',
+      'spot-shadow',
+      'skybox',
+      'main',
+      'linear-hdr-observation',
+      'bloom-bright',
+      'bloom-blur-h',
+      'bloom-blur-v',
+      'bloom-composite',
+      'tonemap',
+      'fxaa',
+      'debug-overlay',
+    ];
+    const passNames = renderer.perFramePassNames;
+    expect(passNames).toHaveLength(expectedPassNames.length);
+    expect(passNames).toEqual(expect.arrayContaining(expectedPassNames));
+    const passIndex = (name: string) => passNames.indexOf(name);
+    expect(passIndex('gpu-driven.view-reset')).toBeLessThan(passIndex('directional-shadow-reset'));
+    expect(passIndex('gpu-driven.frustum-compact')).toBeLessThan(
+      passIndex('directional-shadow-reset'),
+    );
+    expect(passIndex('gpu-driven.finalize-indirect')).toBeLessThan(
+      passIndex('directional-shadow-reset'),
+    );
+    expect(passIndex('directional-shadow-reset')).toBeLessThan(passIndex('shadowCascade0'));
+    expect(passIndex('shadowCascade3')).toBeLessThan(passIndex('directional-shadow-observation'));
+
+    const pixels = await renderer.readPixels();
+    expect(pixels.ok).toBe(true);
+    if (pixels.ok) expect(distanceFromClear(pixels.value)).toBeGreaterThan(0.05);
+  });
+});