@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

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

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import { RecoverError } from '../../../render/src/errors/recover';
+import {
+  RenderFeatureCapabilityMissingError,
+  RenderFeatureStageFailedError,
+} from '../../../render/src/errors/render';
+import type {
+  RenderFeatureErrorDescriptor,
+  RenderFeatureStatus,
+} from '../../../render/src/features/types';
+import type { HealthSnapshot } from '../../../render/src/lifecycle';
+
+interface RecoveryRow {
+  readonly status: RenderFeatureStatus;
+  readonly code: string;
+  readonly detail: string;
+  readonly action: string;
+  readonly error: RenderFeatureErrorDescriptor | undefined;
+}
+
+function featureDetail(error: RenderFeatureErrorDescriptor): string {
+  switch (error.code) {
+    case 'render-feature-registration-conflict':
+      return `${error.detail.featureIdentity}:${error.detail.conflictingOrder}`;
+    case 'render-feature-stage-failed':
+      return `${error.detail.stage}:${error.detail.recovery}`;
+    case 'render-feature-capability-missing':
+      return error.detail.capability;
+    case 'render-feature-pass-order-conflict':
+      return `${error.detail.passIdentity}:${error.detail.dependencyIdentity}`;
+    case 'render-feature-preparation-failed':
+      return `${error.detail.resourceKind}:${error.detail.reason}`;
+    case 'render-feature-prepared-state-mismatch':
+      return `${error.detail.resourceKind}:${error.detail.reason}`;
+    case 'render-feature-draw-recording-failed':
+      return `${error.detail.resourceKind}:${error.detail.backendReason}`;
+  }
+}
+
+function healthDetail(snapshot: HealthSnapshot): string {
+  switch (snapshot.reason) {
+    case 'alive':
+      return 'renderer is ready';
+    case 'device-lost':
+      return `${snapshot.detail.lostReason}:${snapshot.detail.message.length}`;
+    case 'internal-fault':
+      return `internal-fault:${snapshot.detail.message.length}`;
+  }
+}
+
+function recoveryMatrix(): readonly RecoveryRow[] {
+  const failed = new RenderFeatureStageFailedError(
+    'docs.prepared-graphics',
+    0,
+    'prepare',
+    'next-frame',
+  );
+  const disabled = new RenderFeatureCapabilityMissingError('docs.prepared-graphics', 0, 'compute');
+  const disposed = new RenderFeatureStageFailedError(
+    'docs.prepared-graphics',
+    0,
+    'dispose',
+    'registration',
+  );
+  return [
+    {
+      status: 'active',
+      code: 'none',
+      detail: 'no error',
+      action: 'continue renderer.draw(worlds, { cameraOwner: 0, resourceOwner: 0 })',
+      error: undefined,
+    },
+    {
+      status: 'failed',
+      code: failed.code,
+      detail: featureDetail(failed),
+      action: 'fix feature data and retry on the next frame',
+      error: failed,
+    },
+    {
+      status: 'disabled',
+      code: disabled.code,
+      detail: featureDetail(disabled),
+      action: 'disable the feature or use a device with the capability',
+      error: disabled,
+    },
+    {
+      status: 'disposed',
+      code: disposed.code,
+      detail: featureDetail(disposed),
+      action: 'create a new renderer and feature registration',
+      error: disposed,
+    },
+  ];
+}
+
+describe('runtime prepared graphics recovery documentation', () => {
+  it('keeps every feature lifecycle state tied to a structured action', () => {
+    const rows = recoveryMatrix();
+    expect(rows.map((row) => row.status)).toEqual(['active', 'failed', 'disabled', 'disposed']);
+    for (const row of rows) {
+      expect(row.code).not.toBe('message');
+      expect(row.detail).not.toBe('');
+      expect(row.action).not.toBe('');
+      if (row.error !== undefined) {
+        expect(row.code).toBe(row.error.code);
+        expect(row.error.expected).not.toBe('');
+        expect(row.error.hint).not.toBe('');
+      }
+    }
+  });
+
+  it('keeps device-loss recovery aligned with generated health and recover declarations', () => {
+    const health: HealthSnapshot = {
+      reason: 'device-lost',
+      detail: { lostReason: 'unknown', message: 'device reset' },
+      recoverable: true,
+    };
+    const recoveryError = new RecoverError('recover-adapter-unavailable');
+    expect(healthDetail(health)).toBe('unknown:12');
+    expect(health.recoverable).toBe(true);
+    expect(recoveryError.code).toBe('recover-adapter-unavailable');
+    expect(recoveryError.expected).toContain('requestAdapter');
+    expect(recoveryError.hint).toContain('retry recover()');
+  });
+});

package/src/__tests__/render-feature-prepared-graphics.browser.test.ts

@@ -0,0 +1,88 @@
+import type { Renderer } from '@forgeax/engine-render';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  frameRequest,
+  preparedFeature,
+  preparedWorld,
+} from './render-feature-prepared-graphics.fixture';
+import { requireRenderer } from './renderer-test-utils';
+
+describe('prepared graphics browser contract', () => {
+  let renderer: Renderer | undefined;
+
+  afterEach(() => {
+    renderer?.dispose();
+    renderer = undefined;
+  });
+
+  it('records a prepared operation through real WebGPU and returns a receipt', async () => {
+    if (typeof navigator?.gpu?.requestAdapter !== 'function') {
+      throw new Error('WebGPU is unavailable');
+    }
+    const canvas = document.createElement('canvas');
+    canvas.width = 64;
+    canvas.height = 64;
+    document.body.append(canvas);
+    renderer = await requireRenderer(
+      canvas,
+      { features: [preparedFeature('synthetic.browser.prepared')] },
+      { shaderManifestUrl: '/shaders/manifest.json' },
+    );
+    const errors: string[] = [];
+    renderer.subscribe((event) => {
+      if (event.kind === 'error') errors.push(event.error.code);
+    });
+    const world = preparedWorld();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    expect(world.update(1 / 60).ok).toBe(true);
+    const frame = renderer.draw(frameRequest(attached.value));
+    expect(frame.ok).toBe(true);
+    if (frame.ok)
+      expect((await renderer.observe(frame.value, { include: ['draws'] })).ok).toBe(true);
+    expect(errors).not.toContain('render-feature-prepared-state-mismatch');
+    canvas.remove();
+  });
+
+  // This negative path intentionally exercises a real WebGPU pipeline before
+  // the renderer reports the structured stage error. Its cold lavapipe start
+  // has exceeded Vitest's 15s default in CI; keep the assertion bounded at the
+  // owner rather than weakening the global browser timeout.
+  it('reports forged prepared state through subscribe without renderer diagnostics getters', async () => {
+    if (typeof navigator?.gpu?.requestAdapter !== 'function') {
+      throw new Error('WebGPU is unavailable');
+    }
+    const canvas = document.createElement('canvas');
+    canvas.width = 64;
+    canvas.height = 64;
+    document.body.append(canvas);
+    renderer = await requireRenderer(
+      canvas,
+      { features: [preparedFeature('synthetic.browser.mismatch', 'mismatch')] },
+      { shaderManifestUrl: '/shaders/manifest.json' },
+    );
+    const errors: Array<{ code: string; causeCode?: string }> = [];
+    renderer.subscribe((event) => {
+      if (event.kind !== 'error') return;
+      errors.push({
+        code: event.error.code,
+        ...(event.error.code === 'device-operation-failed'
+          ? { causeCode: event.error.detail.cause.code }
+          : {}),
+      });
+    });
+    const world = preparedWorld();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(renderer.draw(frameRequest(attached.value)).ok).toBe(true);
+    expect(errors).toContainEqual({
+      code: 'device-operation-failed',
+      causeCode: 'render-feature-stage-failed',
+    });
+    expect(renderer).not.toHaveProperty('renderFeatureDiagnostics');
+    canvas.remove();
+  }, 30_000);
+});

package/src/__tests__/render-feature-prepared-graphics.dawn.test.ts

@@ -0,0 +1,115 @@
+import type { Renderer } from '@forgeax/engine-render';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  frameRequest,
+  preparedFeature,
+  preparedWorld,
+} from './render-feature-prepared-graphics.fixture';
+import { requireRenderer } from './renderer-test-utils';
+
+const WIDTH = 64;
+const HEIGHT = 64;
+const manifestUrl = await (async () => {
+  const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+  const manifest = await buildEngineShaderManifest();
+  return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+})();
+
+function canvas(): HTMLCanvasElement {
+  let target: GPUTexture | undefined;
+  return {
+    width: WIDTH,
+    height: HEIGHT,
+    getContext(kind: string): unknown {
+      if (kind !== 'webgpu') return null;
+      return {
+        configure(descriptor: { device: GPUDevice; format?: GPUTextureFormat }) {
+          target = descriptor.device.createTexture({
+            size: { width: WIDTH, height: HEIGHT },
+            format: descriptor.format ?? 'rgba8unorm',
+            viewFormats: ['rgba8unorm-srgb'],
+            usage: 0x10 | 0x04,
+          });
+        },
+        unconfigure() {},
+        getCurrentTexture() {
+          if (target === undefined) throw new Error('Dawn target was not configured');
+          return target;
+        },
+      };
+    },
+    addEventListener() {},
+    removeEventListener() {},
+  } as unknown as HTMLCanvasElement;
+}
+
+describe('prepared graphics Dawn contract', () => {
+  let renderer: Renderer | undefined;
+
+  afterEach(() => {
+    renderer?.dispose();
+    renderer = undefined;
+  });
+
+  it('records a prepared operation through the real Dawn submit boundary', async () => {
+    if (typeof navigator?.gpu?.requestAdapter !== 'function') {
+      throw new Error('Dawn navigator.gpu is unavailable');
+    }
+    renderer = await requireRenderer(
+      canvas(),
+      { features: [preparedFeature('synthetic.dawn.prepared')] },
+      { shaderManifestUrl: manifestUrl },
+    );
+    const errors: Array<{ code: string; causeCode?: string }> = [];
+    renderer.subscribe((event) => {
+      if (event.kind !== 'error') return;
+      errors.push({
+        code: event.error.code,
+        ...(event.error.code === 'device-operation-failed'
+          ? { causeCode: event.error.detail.cause.code }
+          : {}),
+      });
+    });
+    const world = preparedWorld();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    expect(world.update(1 / 60).ok).toBe(true);
+    const frame = renderer.draw(frameRequest(attached.value));
+    expect(frame.ok).toBe(true);
+    if (frame.ok)
+      expect((await renderer.observe(frame.value, { include: ['draws'] })).ok).toBe(true);
+    expect(errors).not.toContain('render-feature-prepared-state-mismatch');
+  });
+
+  it('rejects a generation mismatch through the structured error channel', async () => {
+    if (typeof navigator?.gpu?.requestAdapter !== 'function') {
+      throw new Error('Dawn navigator.gpu is unavailable');
+    }
+    renderer = await requireRenderer(
+      canvas(),
+      { features: [preparedFeature('synthetic.dawn.mismatch', 'mismatch')] },
+      { shaderManifestUrl: manifestUrl },
+    );
+    const errors: Array<{ code: string; causeCode?: string }> = [];
+    renderer.subscribe((event) => {
+      if (event.kind !== 'error') return;
+      errors.push({
+        code: event.error.code,
+        ...(event.error.code === 'device-operation-failed'
+          ? { causeCode: event.error.detail.cause.code }
+          : {}),
+      });
+    });
+    const world = preparedWorld();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(renderer.draw(frameRequest(attached.value)).ok).toBe(true);
+    expect(errors).toContainEqual({
+      code: 'device-operation-failed',
+      causeCode: 'render-feature-stage-failed',
+    });
+  });
+});

package/src/__tests__/render-feature-prepared-graphics.fixture.ts

@@ -0,0 +1,104 @@
+import { World } from '@forgeax/engine-ecs';
+import type {
+  Renderer,
+  RenderFeature,
+  RenderFeaturePlan,
+  RenderFrameInput,
+} from '@forgeax/engine-render';
+import { Camera } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { ok } from '@forgeax/engine-types';
+
+export type PreparedFeatureMode = 'accepted' | 'empty' | 'mismatch' | 'recovery';
+
+export const preparedManifest = `data:application/json,${encodeURIComponent(
+  JSON.stringify({
+    schemaVersion: '1.0.0',
+    entries: [
+      { hash: 'pbr00000', wgsl: '/* pbr stub */', glsl: '', bindings: '' },
+      { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+      { hash: 'tonemap0', wgsl: '/* tonemap stub */', glsl: '', bindings: '' },
+    ],
+  }),
+)}`;
+
+export function preparedFeature(
+  identity: string,
+  mode: PreparedFeatureMode = 'accepted',
+): RenderFeature<{ readonly draw: boolean }> {
+  let firstPlan = true;
+
+  return {
+    identity,
+    extract: () => ok({ draw: mode !== 'empty' }),
+    plan: (data, context) => {
+      if (!data.draw) return ok({ resources: [], passes: [] });
+      const target = context.targets.find((candidate) => candidate.kind === 'color');
+      const targetName = target?.name ?? 'swapchain';
+      const mismatch = mode === 'mismatch' || (mode === 'recovery' && firstPlan);
+      firstPlan = false;
+      const plan: RenderFeaturePlan = {
+        resources: [
+          {
+            kind: 'graphics-program',
+            name: 'forward-program',
+            program: {
+              shader: 'forgeax::tonemap',
+              vertexLayout: 'position',
+              colorFormats: [target?.format ?? 'rgba16float'],
+            },
+          },
+          {
+            kind: 'graphics-bindings',
+            name: 'forward-bindings',
+            program: 'forward-program',
+            values: {},
+          },
+          {
+            kind: 'graphics-bindings',
+            name: 'input-bindings',
+            program: 'forward-program',
+            values: { group: 1 },
+          },
+          {
+            kind: 'vertex-data',
+            name: 'triangle-vertices',
+            layout: 'position',
+            data: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+          },
+        ],
+        passes: [
+          {
+            kind: 'raster',
+            name: 'forward',
+            colorAttachments: [{ target: targetName, loadOp: 'load', storeOp: 'store' }],
+            draws: [
+              {
+                program: mismatch ? 'forged-program' : 'forward-program',
+                bindings: ['forward-bindings', 'input-bindings'],
+                vertexData: [{ slot: 0, resource: 'triangle-vertices' }],
+                draw: { kind: 'draw', vertexCount: 3, instanceCount: 1 },
+              },
+            ],
+          },
+        ],
+      };
+      return ok(plan);
+    },
+  };
+}
+
+export function preparedWorld(): World {
+  const world = new World();
+  world.spawn(
+    { component: Transform, data: { pos: [0, 0, 3], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+    { component: Camera, data: { fov: 60, aspect: 1, near: 0.1, far: 100 } },
+  );
+  return world;
+}
+
+export function frameRequest(
+  lease: Parameters<Renderer['draw']>[0]['leases'][number],
+): RenderFrameInput {
+  return { leases: [lease], camera: { lease }, environment: { lease } };
+}

package/src/__tests__/render-feature-prepared-graphics.integration.test.ts

@@ -0,0 +1,56 @@
+import { World } from '@forgeax/engine-ecs';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { constructRendererHost } from '../../../render/src/construct-renderer';
+import {
+  frameRequest,
+  preparedFeature,
+  preparedManifest,
+  preparedWorld,
+} from './render-feature-prepared-graphics.fixture';
+
+function canvas(): HTMLCanvasElement {
+  return { width: 64, height: 64, getContext: () => null } as unknown as HTMLCanvasElement;
+}
+
+describe('prepared graphics Standard host integration', () => {
+  it('records prepared work through RendererOptions.features and returns a receipt', async () => {
+    const host = await constructRendererHost(
+      canvas(),
+      { rhi, features: [preparedFeature('synthetic.prepared')] },
+      { shaderManifestUrl: preparedManifest },
+    );
+    expect(host.ok).toBe(true);
+    if (!host.ok) return;
+    const world = preparedWorld();
+    const attached = host.value.renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    expect(world.update().ok).toBe(true);
+    const frame = host.value.renderer.draw(frameRequest(attached.value));
+    expect(frame.ok).toBe(true);
+    if (frame.ok) {
+      const observed = await host.value.renderer.observe(frame.value, { include: ['draws'] });
+      expect(observed.ok).toBe(true);
+    }
+    expect(host.value.renderer.inspect().state).toBe('alive');
+    host.value.renderer.dispose();
+  });
+
+  it('keeps empty prepared work out of the frame without a registration call', async () => {
+    const host = await constructRendererHost(
+      canvas(),
+      { rhi, features: [preparedFeature('synthetic.empty', 'empty')] },
+      { shaderManifestUrl: preparedManifest },
+    );
+    expect(host.ok).toBe(true);
+    if (!host.ok) return;
+    const world = new World();
+    const attached = host.value.renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    expect(world.update().ok).toBe(true);
+    expect(host.value.renderer.draw(frameRequest(attached.value)).ok).toBe(true);
+    host.value.renderer.dispose();
+  });
+});

package/src/__tests__/render-feature-prepared-graphics.regression.integration.test.ts

@@ -0,0 +1,104 @@
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { constructRendererHost } from '../../../render/src/construct-renderer';
+import {
+  frameRequest,
+  type PreparedFeatureMode,
+  preparedFeature,
+  preparedManifest,
+  preparedWorld,
+} from './render-feature-prepared-graphics.fixture';
+
+function canvas(): HTMLCanvasElement {
+  return { width: 64, height: 64, getContext: () => null } as unknown as HTMLCanvasElement;
+}
+
+function rootErrorCode(value: unknown): string {
+  let error = value as { code: string; detail?: unknown };
+  while (error.detail !== undefined && typeof error.detail === 'object' && error.detail !== null) {
+    const cause = (error.detail as { cause?: unknown }).cause;
+    if (
+      cause === undefined ||
+      typeof cause !== 'object' ||
+      cause === null ||
+      typeof (cause as { code?: unknown }).code !== 'string'
+    ) {
+      break;
+    }
+    error = cause as { code: string; detail?: unknown };
+  }
+  return error.code;
+}
+
+async function runCase(mode: PreparedFeatureMode) {
+  const host = await constructRendererHost(
+    canvas(),
+    { rhi, features: [preparedFeature(`synthetic.${mode}`, mode)] },
+    { shaderManifestUrl: preparedManifest },
+  );
+  expect(host.ok).toBe(true);
+  if (!host.ok) return { frame: host, errors: [] as string[] };
+  const errors: string[] = [];
+  host.value.renderer.subscribe((event) => {
+    if (event.kind === 'error') errors.push(rootErrorCode(event.error));
+  });
+  const world = preparedWorld();
+  const attached = host.value.renderer.attach(world);
+  expect(attached.ok).toBe(true);
+  if (!attached.ok) return { frame: attached, errors };
+  expect(world.update().ok).toBe(true);
+  const first = host.value.renderer.draw(frameRequest(attached.value));
+  if (first.ok) await first.value.completed;
+  if (mode === 'recovery') {
+    expect(world.update().ok).toBe(true);
+    expect(host.value.renderer.draw(frameRequest(attached.value)).ok).toBe(true);
+  }
+  host.value.renderer.dispose();
+  return { frame: first, errors: errors.filter((code) => code.startsWith('render-feature-')) };
+}
+
+describe('prepared graphics state-machine regression', () => {
+  it('isolates accepted, empty, mismatch, and next-frame recovery cases', async () => {
+    const accepted = await runCase('accepted');
+    const empty = await runCase('empty');
+    const mismatch = await runCase('mismatch');
+    const recovery = await runCase('recovery');
+
+    expect(accepted.frame.ok).toBe(true);
+    expect(accepted.errors).not.toContain('render-feature-prepared-state-mismatch');
+    expect(empty.frame.ok).toBe(true);
+    expect(empty.errors).toEqual([]);
+    expect(mismatch.frame.ok).toBe(true);
+    expect(mismatch.errors).toContain('render-feature-stage-failed');
+    expect(recovery.frame.ok).toBe(true);
+    expect(recovery.errors).toContain('render-feature-stage-failed');
+  });
+
+  it('keeps a healthy feature producing a frame when a sibling fails preparation state', async () => {
+    const host = await constructRendererHost(
+      canvas(),
+      {
+        rhi,
+        features: [
+          preparedFeature('synthetic.healthy', 'accepted'),
+          preparedFeature('synthetic.failing', 'mismatch'),
+        ],
+      },
+      { shaderManifestUrl: preparedManifest },
+    );
+    expect(host.ok).toBe(true);
+    if (!host.ok) return;
+    const errors: string[] = [];
+    host.value.renderer.subscribe((event) => {
+      if (event.kind === 'error') errors.push(rootErrorCode(event.error));
+    });
+    const world = preparedWorld();
+    const attached = host.value.renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    expect(world.update().ok).toBe(true);
+    expect(host.value.renderer.draw(frameRequest(attached.value)).ok).toBe(true);
+    expect(errors).toContain('render-feature-stage-failed');
+    host.value.renderer.dispose();
+  });
+});