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

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

@@ -0,0 +1,74 @@
+import { ok } from '@forgeax/engine-types';
+import type { RenderFeatureDrawDeclaration } from '../features/plan';
+import type { RenderFeature, RenderFeaturePlan, RenderFeatureResourceDeclaration } from '../index';
+
+interface Frame {
+  readonly vertexCount: number;
+  readonly indexCount: number;
+}
+
+const feature = {
+  identity: 'prepared.graphics.positive',
+  extract: () => ok<Frame>({ vertexCount: 6, indexCount: 6 }),
+  plan(data, context) {
+    const target = context.targets.find((candidate) => candidate.kind === 'color');
+    const resources: readonly RenderFeatureResourceDeclaration[] = [
+      {
+        kind: 'graphics-program',
+        name: 'forward-program',
+        program: {
+          shader: 'unlit',
+          vertexLayout: 'position',
+          colorFormats: [target?.format ?? 'rgba8unorm'],
+        },
+      },
+      {
+        kind: 'graphics-bindings',
+        name: 'forward-bindings',
+        program: 'forward-program',
+        values: { opacity: 1 },
+      },
+      {
+        kind: 'vertex-data',
+        name: 'quad-vertices',
+        layout: 'position',
+        data: new Float32Array(data.vertexCount),
+      },
+      {
+        kind: 'index-data',
+        name: 'quad-indices',
+        format: 'uint16',
+        data: new Uint16Array(data.indexCount),
+      },
+    ];
+    const vertexOnly: RenderFeatureDrawDeclaration = {
+      program: 'forward-program',
+      bindings: ['forward-bindings'],
+      vertexData: [{ slot: 0, resource: 'quad-vertices' }],
+      draw: { kind: 'draw', vertexCount: data.vertexCount, instanceCount: 1 },
+    };
+    const indexed: RenderFeatureDrawDeclaration = {
+      program: 'forward-program',
+      bindings: ['forward-bindings'],
+      vertexData: [{ slot: 0, resource: 'quad-vertices' }],
+      indexData: { resource: 'quad-indices', format: 'uint16' },
+      draw: { kind: 'draw-indexed', indexCount: data.indexCount, instanceCount: 1 },
+    };
+    const plan: RenderFeaturePlan = {
+      resources,
+      passes: [
+        {
+          kind: 'raster',
+          name: 'forward',
+          colorAttachments: [
+            { target: target?.name ?? 'swapchain', loadOp: 'load', storeOp: 'store' },
+          ],
+          draws: [vertexOnly, indexed],
+        },
+      ],
+    };
+    return ok(plan);
+  },
+} satisfies RenderFeature<Frame>;
+
+void feature;

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

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  PreparedKind,
+  RenderFeatureDrawRecord,
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+  RenderFeaturePreparedRef,
+} from '../features/prepared-graphics';
+import { validateRenderFeatureGraphicsPass } from '../features/prepared-graphics';
+
+function ref<Kind extends PreparedKind>(
+  kind: Kind,
+  generation = 1,
+): RenderFeaturePreparedRef<Kind> {
+  return { kind, generation };
+}
+
+const pipeline = ref('pipeline');
+const bindings = ref('bindings');
+const vertices = ref('vertex-data');
+const indices = ref('index-data');
+
+const vertexDraw: RenderFeatureDrawRecord = {
+  kind: 'draw',
+  pipeline,
+  bindings: [bindings],
+  vertexData: [{ slot: 0, resource: vertices }],
+  command: { vertexCount: 3, instanceCount: 1 },
+};
+
+const indexedDraw: RenderFeatureDrawRecord = {
+  kind: 'draw-indexed',
+  pipeline,
+  bindings: [bindings],
+  vertexData: [{ slot: 0, resource: vertices }],
+  indexData: { resource: indices, format: 'uint16' },
+  command: { indexCount: 3, instanceCount: 1 },
+};
+
+const validPass: RenderFeatureGraphicsPassDescriptor = {
+  attachments: {
+    colors: [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
+  },
+  draws: [vertexDraw, indexedDraw],
+};
+
+const validState: RenderFeaturePreparedGraphicsState = {
+  capabilityAvailable: true,
+  generation: 1,
+  attachments: [{ resource: 'color', format: 'rgba8unorm' }],
+  pipeline,
+  bindings: [bindings],
+  vertexData: [vertices],
+  indexData: [indices],
+};
+
+function expectFailure(
+  pass: RenderFeatureGraphicsPassDescriptor,
+  state: RenderFeaturePreparedGraphicsState,
+): void {
+  const result = validateRenderFeatureGraphicsPass('prepared.graphics.unit', pass, state);
+  expect(result.ok).toBe(false);
+  if (result.ok) return;
+  expect(result.error.code).toMatch(/^render-feature-/);
+  expect(result.error.expected).toBeTypeOf('string');
+  expect(result.error.hint).toBeTypeOf('string');
+  expect(result.error).toHaveProperty('detail.featureIdentity', 'prepared.graphics.unit');
+}
+
+describe('prepared graphics descriptor validation', () => {
+  it('accepts complete vertex-only and indexed records', () => {
+    const result = validateRenderFeatureGraphicsPass(
+      'prepared.graphics.unit',
+      validPass,
+      validState,
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value.acceptedDrawCount).toBe(2);
+  });
+
+  it('rejects missing capability before recording', () => {
+    expectFailure(validPass, { ...validState, capabilityAvailable: false });
+  });
+
+  it('rejects missing pipeline, binding, vertex, index, and attachment state', () => {
+    expectFailure(validPass, { ...validState, pipeline: undefined });
+    expectFailure(validPass, { ...validState, bindings: [] });
+    expectFailure(validPass, { ...validState, vertexData: [] });
+    expectFailure(validPass, { ...validState, indexData: [] });
+    expectFailure(validPass, { ...validState, attachments: [] });
+  });
+
+  it('rejects foreign kind and stale generation references', () => {
+    expectFailure(validPass, { ...validState, pipeline: ref('bindings') });
+    expectFailure(validPass, { ...validState, pipeline: ref('pipeline', 2) });
+  });
+
+  it('rejects layout and attachment format mismatches', () => {
+    expectFailure(validPass, {
+      ...validState,
+      vertexData: [ref('vertex-data', 2)],
+    });
+    expectFailure(validPass, {
+      ...validState,
+      attachments: [{ resource: 'color', format: 'bgra8unorm' }],
+    });
+  });
+
+  it('rejects indexed records without index data and vertex records with index data', () => {
+    const missingIndex: RenderFeatureGraphicsPassDescriptor = {
+      ...validPass,
+      draws: [{ ...indexedDraw, indexData: undefined }],
+    };
+    const unexpectedIndex: RenderFeatureGraphicsPassDescriptor = {
+      ...validPass,
+      draws: [{ ...vertexDraw, indexData: { resource: indices, format: 'uint16' } }],
+    };
+    expectFailure(missingIndex, validState);
+    expectFailure(unexpectedIndex, validState);
+  });
+});

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

@@ -0,0 +1,57 @@
+import type {
+  RenderError,
+  RenderFeature,
+  RenderFeatureErrorDescriptor,
+  RenderFeatureExtractContext,
+  RenderFeaturePlan,
+  RenderFeaturePlanContext,
+} from '@forgeax/engine-render';
+import { ok } from '@forgeax/engine-types';
+
+type FrameData = {
+  readonly visibleCount: number;
+};
+
+const feature = {
+  identity: 'test.public-surface',
+  extract(context: RenderFeatureExtractContext) {
+    const owner: number = context.owner;
+    return ok<FrameData>({ visibleCount: owner });
+  },
+  plan(data: FrameData, context: RenderFeaturePlanContext) {
+    const count: number = data.visibleCount;
+    const frameNumber: number = context.frame.frameNumber;
+    const plan: RenderFeaturePlan = { resources: [], passes: [] };
+    void count;
+    void frameNumber;
+    return ok(plan);
+  },
+} satisfies RenderFeature<FrameData>;
+
+const errorDescriptor = (error: RenderError): RenderFeatureErrorDescriptor | undefined => {
+  switch (error.code) {
+    case 'render-feature-registration-conflict':
+      return error;
+    case 'render-feature-stage-failed':
+      return error;
+    case 'render-feature-capability-missing':
+      return error;
+    case 'render-feature-pass-order-conflict':
+      return error;
+    default:
+      return undefined;
+  }
+};
+
+void errorDescriptor;
+void feature;
+
+// The renderer host and construction context are internal implementation seams.
+// @ts-expect-error host internals are not part of the render root surface
+type _NoPublicFeatureHost = typeof import('@forgeax/engine-render')['RenderFeatureHost'];
+// @ts-expect-error frame input is not a producer-facing public declaration
+type _NoPublicFrameInput = typeof import('@forgeax/engine-render')['RenderFeatureFrameInput'];
+// @ts-expect-error bundler manifest wiring is not a render feature API
+type _NoPublicBundlerOptions = typeof import('@forgeax/engine-render')['BundlerOptions'];
+// @ts-expect-error remote inspection/RPC symbols do not belong to the render root
+type _NoPublicRpcClient = typeof import('@forgeax/engine-render')['InspectorClient'];

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

@@ -0,0 +1,87 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { RenderFeatureStageFailedError } from '../errors/render';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeature } from '../features/types';
+
+const caps = (compute: boolean): Readonly<RhiCaps> => ({ compute }) as unknown as RhiCaps;
+
+describe('render feature retry rules', () => {
+  it('retries ordinary failures on the next frame and keeps latest error structured', () => {
+    let attempts = 0;
+    const feature: RenderFeature<{ readonly frame: number }> = {
+      identity: 'synthetic.retry',
+      extract: ({ frameNumber }) => ok({ frame: frameNumber }),
+      plan: () => {
+        attempts += 1;
+        if (attempts === 1) {
+          return err(new RenderFeatureStageFailedError('synthetic.retry', 0, 'plan', 'next-frame'));
+        }
+        return ok({ resources: [], passes: [] });
+      },
+    };
+    const host = createRenderFeatureHost([feature], caps(true)).unwrap();
+
+    const failed = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(true),
+    });
+    const error = failed.errors[0];
+    expect(error?.code).toBe('render-feature-stage-failed');
+    if (error?.code === 'render-feature-stage-failed') {
+      expect(error.detail).toMatchObject({
+        featureIdentity: 'synthetic.retry',
+        stage: 'plan',
+        recovery: 'next-frame',
+      });
+    }
+
+    const retried = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      caps: caps(true),
+    });
+    expect(retried.errors).toEqual([]);
+    expect(host.diagnostics()[0]?.latestError).toBeUndefined();
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+
+  it('does not retry a disabled feature until recover makes its capability available', () => {
+    const feature: RenderFeature<{ readonly frame: number }> = {
+      identity: 'synthetic.capability-retry',
+      requiredCapabilities: ['compute'],
+      extract: ({ frameNumber }) => ok({ frame: frameNumber }),
+      plan: () => ok({ resources: [], passes: [] }),
+    };
+    const host = createRenderFeatureHost([feature], caps(false)).unwrap();
+
+    runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(false),
+    });
+    expect(
+      runRenderFeatureFrame(host, {
+        worlds: [],
+        owner: 0,
+        frameNumber: 2,
+        caps: caps(true),
+      }).stageEvents,
+    ).toEqual([]);
+
+    expect(host.recover({ frameNumber: 3, caps: caps(true) })).toEqual(ok(undefined));
+    expect(
+      runRenderFeatureFrame(host, {
+        worlds: [],
+        owner: 0,
+        frameNumber: 3,
+        caps: caps(true),
+      }).stageEvents,
+    ).toHaveLength(2);
+  });
+});

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

@@ -0,0 +1,110 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { RenderFeatureStageFailedError } from '../errors/render';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeature } from '../features/types';
+
+const caps = {
+  backendKind: 'null',
+  compute: true,
+  timestampQuery: true,
+  timestampPeriodNanoseconds: null,
+  indirectDrawing: true,
+  textureCompressionBc: false,
+  textureCompressionEtc2: false,
+  textureCompressionAstc: false,
+  multiDrawIndirect: false,
+  pushConstants: false,
+  textureBindingArray: false,
+  samplerAliasing: true,
+  firstInstanceIndirect: true,
+  storageBuffer: true,
+  storageTexture: true,
+  rgba16floatRenderable: true,
+  rg11b10ufloatRenderable: true,
+  float32Filterable: true,
+  maxColorAttachments: 8,
+} satisfies RhiCaps;
+
+function feature(identity: string, events: string[], failStage?: 'extract' | 'plan') {
+  const value = { identity };
+  return {
+    identity,
+    extract: () => {
+      events.push(`${identity}:extract`);
+      return failStage === 'extract'
+        ? err(new RenderFeatureStageFailedError(identity, 0, 'extract', 'next-frame'))
+        : ok(value);
+    },
+    plan: () => {
+      events.push(`${identity}:plan`);
+      return failStage === 'plan'
+        ? err(new RenderFeatureStageFailedError(identity, 0, 'plan', 'next-frame'))
+        : ok({ resources: [], passes: [] });
+    },
+  } satisfies RenderFeature<typeof value>;
+}
+
+describe('render feature stage scheduling', () => {
+  it('runs each feature once in registration and stage order', () => {
+    const events: string[] = [];
+    const host = createRenderFeatureHost([
+      feature('synthetic.first', events),
+      feature('synthetic.second', events),
+    ]).unwrap();
+
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 7,
+      caps,
+    });
+
+    expect(
+      result.stageEvents.map(({ featureIdentity, stage }) => `${featureIdentity}:${stage}`),
+    ).toEqual([
+      'synthetic.first:extract',
+      'synthetic.first:plan',
+      'synthetic.second:extract',
+      'synthetic.second:plan',
+    ]);
+  });
+
+  it.each([
+    'extract',
+    'plan',
+  ] as const)('isolates a %s failure from the healthy feature', (failStage) => {
+    const events: string[] = [];
+    const host = createRenderFeatureHost([
+      feature('synthetic.failed', events, failStage),
+      feature('synthetic.healthy', events),
+    ]).unwrap();
+
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 8,
+      caps,
+    });
+
+    expect(result.errors).toHaveLength(1);
+    const error = result.errors[0];
+    expect(error?.code).toBe('render-feature-stage-failed');
+    if (error?.code === 'render-feature-stage-failed') {
+      expect(error.detail).toMatchObject({
+        featureIdentity: 'synthetic.failed',
+        stage: failStage,
+      });
+    }
+    expect(events).toContain('synthetic.healthy:extract');
+    expect(events).toContain('synthetic.healthy:plan');
+    const failedEvents = events.filter((event) => event.startsWith('synthetic.failed:'));
+    const failedStageIndex = ['extract', 'plan'].indexOf(failStage);
+    expect(failedEvents).toEqual(
+      ['extract', 'plan']
+        .slice(0, failedStageIndex + 1)
+        .map((stage) => `synthetic.failed:${stage}`),
+    );
+  });
+});

package/src/__tests__/render-feature-stage-failed-policy-owner.unit.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { type RenderError, RenderFeatureStageFailedError } from '../errors/render';
+import type {
+  RenderFeatureErrorDescriptor,
+  RenderFeatureRecovery,
+  RenderFeatureStage,
+  RenderFeatureStageFailedDetail,
+} from '../features/types';
+
+const evidence = [
+  {
+    featureIdentity: 'synthetic.next-frame',
+    order: 3,
+    stage: 'prepare',
+    recovery: 'next-frame',
+    expected: "feature 'synthetic.next-frame' completes its prepare stage without an error",
+    hint: "correct 'synthetic.next-frame' prepare data and retry on the next frame",
+    message: "render feature 'synthetic.next-frame' failed during prepare",
+  },
+  {
+    featureIdentity: 'synthetic.renderer-recover',
+    order: 4,
+    stage: 'record',
+    recovery: 'renderer-recover',
+    expected: "feature 'synthetic.renderer-recover' completes its record stage without an error",
+    hint: "wait for renderer recovery before retrying 'synthetic.renderer-recover'",
+    message: "render feature 'synthetic.renderer-recover' failed during record",
+  },
+  {
+    featureIdentity: 'synthetic.registration',
+    order: 5,
+    stage: 'recover',
+    recovery: 'registration',
+    expected: "feature 'synthetic.registration' completes its recover stage without an error",
+    hint: "correct 'synthetic.registration' registration before retrying",
+    message: "render feature 'synthetic.registration' failed during recover",
+  },
+] as const satisfies readonly {
+  readonly featureIdentity: string;
+  readonly order: number;
+  readonly stage: RenderFeatureStage;
+  readonly recovery: RenderFeatureRecovery;
+  readonly expected: string;
+  readonly hint: string;
+  readonly message: string;
+}[];
+
+describe('RenderFeatureStageFailedError policy ownership', () => {
+  it('preserves every recovery diagnostic and its type correlation', () => {
+    expect(evidence.map(({ recovery }) => recovery)).toEqual([
+      'next-frame',
+      'renderer-recover',
+      'registration',
+    ]);
+    expect(new Set(evidence.map(({ recovery }) => recovery)).size).toBe(3);
+
+    for (const row of evidence) {
+      const error = new RenderFeatureStageFailedError(
+        row.featureIdentity,
+        row.order,
+        row.stage,
+        row.recovery,
+      );
+
+      expectTypeOf(error).toEqualTypeOf<
+        Extract<RenderError, { readonly code: 'render-feature-stage-failed' }>
+      >();
+      expectTypeOf(error.detail).toEqualTypeOf<RenderFeatureStageFailedDetail>();
+      expectTypeOf(error.detail.recovery).toEqualTypeOf<RenderFeatureRecovery>();
+      expectTypeOf<
+        Extract<RenderFeatureErrorDescriptor, { readonly code: 'render-feature-stage-failed' }>
+      >().toMatchTypeOf<{
+        readonly code: 'render-feature-stage-failed';
+        readonly expected: string;
+        readonly hint: string;
+        readonly detail: RenderFeatureStageFailedDetail;
+      }>();
+
+      expect(error.code).toBe('render-feature-stage-failed');
+      expect(error.expected).toBe(row.expected);
+      expect(error.hint).toBe(row.hint);
+      expect(error.message).toBe(row.message);
+      expect(error.detail).toEqual({
+        featureIdentity: row.featureIdentity,
+        order: row.order,
+        stage: row.stage,
+        recovery: row.recovery,
+      });
+    }
+  });
+
+  it('preserves Error identity, stack, own-key order, and descriptors', () => {
+    const error = new RenderFeatureStageFailedError(
+      'synthetic.descriptors',
+      6,
+      'dispose',
+      'renderer-recover',
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(RenderFeatureStageFailedError);
+    expect(error.name).toBe('RenderFeatureStageFailedError');
+    expect(typeof error.stack).toBe('string');
+    expect(error.stack).toContain(`RenderFeatureStageFailedError: ${error.message}`);
+    expect(Object.keys(error)).toEqual(['code', 'expected', 'hint', 'detail', 'name']);
+    expect(Object.getOwnPropertyNames(error)).toEqual([
+      'stack',
+      'message',
+      'code',
+      'expected',
+      'hint',
+      'detail',
+      'name',
+    ]);
+
+    const descriptors = Object.getOwnPropertyDescriptors(error);
+    for (const field of ['code', 'expected', 'hint', 'detail', 'name'] as const) {
+      expect(descriptors[field]).toEqual({
+        value: error[field],
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+    }
+    expect(descriptors.message).toMatchObject({
+      configurable: true,
+      enumerable: false,
+      writable: true,
+    });
+    expect(descriptors.stack).toMatchObject({
+      configurable: true,
+      enumerable: false,
+    });
+    expect(typeof descriptors.stack?.get).toBe('function');
+    expect(typeof descriptors.stack?.set).toBe('function');
+  });
+});