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

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

@@ -0,0 +1,161 @@
+import type { TextureFormat } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import type { RenderFeaturePlan, RenderFeaturePlanContext } from '../features/plan';
+import type { RenderFeature } from '../features/types';
+import type { RenderFeatureRecovery } from '../features/vocabulary';
+
+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',
+    },
+  ],
+  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' },
+        },
+      ],
+    },
+  ],
+};
+
+const feature = {
+  identity: 'synthetic.plan',
+  extract: () => ok({ frame: 1 }),
+  plan(data: { readonly frame: number }, context: RenderFeaturePlanContext) {
+    void data;
+    void context.frame;
+    void context.caps;
+    // @ts-expect-error plan callbacks cannot access a raw device.
+    void context.device;
+    // @ts-expect-error plan callbacks cannot access a queue.
+    void context.queue;
+    // @ts-expect-error plan callbacks cannot access an encoder.
+    void context.encoder;
+    // @ts-expect-error plan callbacks cannot submit work.
+    void context.submit;
+    return ok(plan);
+  },
+} satisfies RenderFeature<{ readonly frame: number }>;
+
+const missingPlan = {
+  identity: 'synthetic.invalid',
+  extract: () => ok(undefined),
+};
+// @ts-expect-error RenderFeature plan is mandatory.
+const invalidFeature: RenderFeature<undefined> = missingPlan;
+
+const invalidDispatch: RenderFeaturePlan = {
+  resources: [],
+  passes: [
+    {
+      kind: 'compute',
+      name: 'bad',
+      program: 'missing',
+      bindings: 'missing',
+      dispatches: [
+        {
+          // @ts-expect-error dispatch variants are closed; callbacks are not executable descriptors.
+          kind: 'callback',
+          callback: () => undefined,
+        },
+      ],
+    },
+  ],
+};
+
+function recoveryLabel(recovery: RenderFeatureRecovery): string {
+  switch (recovery) {
+    case 'next-frame':
+      return recovery;
+    case 'renderer-recover':
+      return recovery;
+    case 'registration':
+      return recovery;
+  }
+  const exhaustive: never = recovery;
+  return exhaustive;
+}
+
+void feature;
+void invalidFeature;
+void invalidDispatch;
+void recoveryLabel;

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

@@ -0,0 +1,170 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import {
+  deriveRenderFeaturePassAccess,
+  freezeRenderFeaturePlan,
+  type RenderFeaturePlan,
+  renderFeaturePlanSignature,
+} from '../features/plan';
+import type { RenderFeature } from '../features/types';
+
+const plan = (data = new Uint32Array([1, 2, 3, 4])) =>
+  ({
+    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: ['rgba8unorm'],
+        },
+      },
+      {
+        kind: 'buffer',
+        name: 'particles',
+        size: 64,
+        usage: ['storage', 'vertex'],
+        data,
+      },
+      {
+        kind: 'buffer',
+        name: 'params',
+        size: 16,
+        usage: ['uniform'],
+      },
+      {
+        kind: 'buffer',
+        name: 'indirect',
+        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: {},
+      },
+      {
+        kind: 'vertex-data',
+        name: 'vertices',
+        layout: 'position',
+        buffer: 'particles',
+      },
+    ],
+    passes: [
+      {
+        kind: 'compute',
+        name: 'simulate',
+        program: 'simulate-program',
+        bindings: 'simulate-bindings',
+        dispatches: [{ kind: 'direct', entryPoint: 'simulate', workgroups: [1] }],
+      },
+      {
+        kind: 'raster',
+        name: 'draw',
+        colorAttachments: [{ target: 'color', loadOp: 'load', storeOp: 'store' }],
+        draws: [
+          {
+            program: 'draw-program',
+            bindings: ['draw-bindings'],
+            vertexData: [{ slot: 0, resource: 'vertices' }],
+            draw: { kind: 'draw-indirect', resource: 'indirect' },
+          },
+        ],
+      },
+    ],
+  }) satisfies RenderFeaturePlan;
+
+describe('RenderFeature plan authority', () => {
+  it('derives compute and raster access from descriptors', () => {
+    const value = plan();
+    expect(deriveRenderFeaturePassAccess(value, value.passes[0] as never)).toEqual([
+      { resource: 'particles', usage: 'storage-read-write' },
+      { resource: 'params', usage: 'uniform-read' },
+    ]);
+    expect(deriveRenderFeaturePassAccess(value, value.passes[1] as never)).toEqual([
+      { resource: 'color', usage: 'color-attachment' },
+      { resource: 'particles', usage: 'vertex-read' },
+      { resource: 'indirect', usage: 'indirect-read' },
+    ]);
+  });
+
+  it('keeps buffer uploads out of the stable topology signature', () => {
+    expect(renderFeaturePlanSignature(plan(new Uint32Array([1])))).toBe(
+      renderFeaturePlanSignature(plan(new Uint32Array([2]))),
+    );
+  });
+
+  it('rejects descriptor references that do not exist', () => {
+    const invalid: RenderFeaturePlan = {
+      resources: [],
+      passes: [
+        {
+          kind: 'compute',
+          name: 'simulate',
+          program: 'missing',
+          bindings: 'missing',
+          dispatches: [{ kind: 'direct', entryPoint: 'main', workgroups: [1] }],
+        },
+      ],
+    };
+    expect(freezeRenderFeaturePlan('synthetic.invalid', invalid).ok).toBe(false);
+  });
+
+  it('never invokes legacy producer callbacks', () => {
+    const prepare = vi.fn();
+    const contribute = vi.fn();
+    const legacyShaped = {
+      identity: 'synthetic.plan-only',
+      extract: () => ok(undefined),
+      plan: () => ok({ resources: [], passes: [] }),
+      prepare,
+      contribute,
+    };
+    const feature: RenderFeature<undefined> = legacyShaped;
+    const host = createRenderFeatureHost([feature]);
+    expect(host.ok).toBe(true);
+    if (!host.ok) return;
+
+    const result = runRenderFeatureFrame(host.value, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: {} as never,
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(result.plans).toHaveLength(1);
+    expect(result.plans[0]).not.toHaveProperty('execution');
+    expect(result.stageEvents.map((event) => event.stage)).toEqual(['extract', 'plan']);
+    expect(prepare).not.toHaveBeenCalled();
+    expect(contribute).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,90 @@
+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> =>
+  ({ backendKind: 'null', compute }) as unknown as RhiCaps;
+
+function feature(mode: 'healthy' | 'failed'): RenderFeature<{ readonly ready: true }> {
+  return {
+    identity: `synthetic.diagnostics.${mode}`,
+    requiredCapabilities: ['compute'],
+    extract: () => ok({ ready: true }),
+    plan: () =>
+      mode === 'failed'
+        ? err(
+            new RenderFeatureStageFailedError(
+              `synthetic.diagnostics.${mode}`,
+              0,
+              'plan',
+              'next-frame',
+            ),
+          )
+        : ok({ resources: [], passes: [] }),
+  };
+}
+
+describe('render feature prepared diagnostics', () => {
+  it('projects disabled and failed states with code-directed recovery data', () => {
+    const disabledHost = createRenderFeatureHost([feature('healthy')]).unwrap();
+    runRenderFeatureFrame(disabledHost, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(false),
+    });
+    const disabled = disabledHost.diagnostics()[0];
+    expect(disabled).toMatchObject({
+      status: 'disabled',
+      latestError: {
+        code: 'render-feature-capability-missing',
+        detail: { capability: 'compute' },
+      },
+    });
+    expect(disabled?.latestError?.expected).toContain('compute');
+    expect(disabled?.latestError?.hint).toContain('disable');
+
+    const failedHost = createRenderFeatureHost([feature('failed')]).unwrap();
+    runRenderFeatureFrame(failedHost, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(true),
+    });
+    const failed = failedHost.diagnostics()[0];
+    expect(failed).toMatchObject({
+      status: 'failed',
+      latestError: {
+        code: 'render-feature-stage-failed',
+        detail: { stage: 'plan', recovery: 'next-frame' },
+      },
+    });
+    expect(failed?.latestError?.hint).toContain('next frame');
+  });
+
+  it('makes disposed diagnostics terminal and keeps repeated lifecycle calls side-effect free', () => {
+    const host = createRenderFeatureHost([feature('healthy')]).unwrap();
+    expect(host.recover({ frameNumber: 2, caps: caps(true) })).toEqual(ok(undefined));
+    expect(host.recover({ frameNumber: 2, caps: caps(true) })).toEqual(ok(undefined));
+
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(host.dispose()).toEqual(ok(undefined));
+    const diagnostics = host.diagnostics()[0];
+    expect(diagnostics).toMatchObject({
+      identity: 'synthetic.diagnostics.healthy',
+      status: 'disposed',
+    });
+    const recoverAfterDispose = host.recover({ frameNumber: 3, caps: caps(true) });
+    expect(recoverAfterDispose.ok).toBe(false);
+    if (!recoverAfterDispose.ok) {
+      expect(recoverAfterDispose.error).toMatchObject({
+        code: 'render-feature-stage-failed',
+        detail: { stage: 'recover', recovery: 'registration' },
+      });
+      expect(recoverAfterDispose.error.hint).toContain('registration');
+    }
+  });
+});

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

@@ -0,0 +1,79 @@
+import type { RenderFeatureErrorDescriptor } from '../errors/render';
+import type { RenderFeatureErrorCode } from '../features/types';
+import type { PreparedKind, RenderFeatureRecovery } from '../features/vocabulary';
+
+function describeGraphicsError(error: RenderFeatureErrorDescriptor): string {
+  switch (error.code) {
+    case 'render-feature-preparation-failed':
+      return `${error.detail.operation}:${error.detail.resourceKind}:${error.detail.resourceName}`;
+    case 'render-feature-prepared-state-mismatch':
+      switch (error.detail.reason) {
+        case 'missing-prepared-state':
+          return error.detail.missingResource;
+        case 'foreign-feature':
+          return error.detail.actualFeatureIdentity;
+        case 'foreign-kind':
+          return `${error.detail.expectedKind}:${error.detail.actualKind}`;
+        case 'generation-mismatch':
+          return `${error.detail.expectedGeneration}:${error.detail.actualGeneration}`;
+        case 'layout-mismatch':
+          return `${error.detail.expectedLayout}:${error.detail.actualLayout}`;
+        case 'format-mismatch':
+          return `${error.detail.expectedFormat}:${error.detail.actualFormat}`;
+      }
+      return 'prepared-state-mismatch';
+    case 'render-feature-draw-recording-failed':
+      return `${error.detail.operation}:${error.detail.backendReason}`;
+    case 'render-feature-registration-conflict':
+      return error.detail.featureIdentity;
+    case 'render-feature-stage-failed':
+      return error.detail.featureIdentity;
+    case 'render-feature-capability-missing':
+      return error.detail.featureIdentity;
+    case 'render-feature-pass-order-conflict':
+      return error.detail.featureIdentity;
+  }
+}
+
+function renderGraphicsCodeLabel(code: RenderFeatureErrorCode): string {
+  switch (code) {
+    case 'render-feature-registration-conflict':
+      return code;
+    case 'render-feature-stage-failed':
+      return code;
+    case 'render-feature-capability-missing':
+      return code;
+    case 'render-feature-pass-order-conflict':
+      return code;
+    case 'render-feature-preparation-failed':
+      return code;
+    case 'render-feature-prepared-state-mismatch':
+      return code;
+    case 'render-feature-draw-recording-failed':
+      return code;
+  }
+}
+
+function describeRecovery(recovery: RenderFeatureRecovery): string {
+  switch (recovery) {
+    case 'next-frame':
+      return recovery;
+    case 'renderer-recover':
+      return recovery;
+    case 'registration':
+      return recovery;
+  }
+}
+
+const preparedKinds: readonly PreparedKind[] = [
+  'pipeline',
+  'bindings',
+  'vertex-data',
+  'index-data',
+  'attachment',
+];
+
+void describeGraphicsError;
+void renderGraphicsCodeLabel;
+void describeRecovery;
+void preparedKinds;

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

@@ -0,0 +1,80 @@
+import type { RenderFeature, RenderFeatureErrorDescriptor } from '@forgeax/engine-render';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+type PreparedFrame = {
+  readonly items: readonly unknown[];
+};
+
+function describeRenderFeatureError(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.featureIdentity}:${error.detail.stage}:${error.detail.recovery}`;
+    case 'render-feature-capability-missing':
+      return `${error.detail.featureIdentity}:${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.resourceName}`;
+    case 'render-feature-prepared-state-mismatch':
+      switch (error.detail.reason) {
+        case 'missing-prepared-state':
+          return `${error.detail.resourceKind}:${error.detail.missingResource}`;
+        case 'foreign-feature':
+          return `${error.detail.expectedFeatureIdentity}:${error.detail.actualFeatureIdentity}`;
+        case 'foreign-kind':
+          return `${error.detail.expectedKind}:${error.detail.actualKind}`;
+        case 'generation-mismatch':
+          return `${error.detail.expectedGeneration}:${error.detail.actualGeneration}`;
+        case 'layout-mismatch':
+          return `${error.detail.expectedLayout}:${error.detail.actualLayout}`;
+        case 'format-mismatch':
+          return `${error.detail.expectedFormat}:${error.detail.actualFormat}`;
+      }
+      break;
+    case 'render-feature-draw-recording-failed':
+      return `${error.detail.resourceKind}:${error.detail.backendReason}`;
+  }
+}
+
+function publicPreparedRecipe(frame: PreparedFrame): RenderFeature<PreparedFrame> {
+  const feature: RenderFeature<PreparedFrame> = {
+    identity: 'docs.prepared-graphics',
+    extract: () => ok(frame),
+    plan: (data) => {
+      void data.items.length;
+      return ok({ resources: [], passes: [] });
+    },
+  };
+  return feature;
+}
+
+describe('public prepared graphics recipe', () => {
+  it('keeps the public imports and callback inference type-safe', () => {
+    const frame: PreparedFrame = { items: [] };
+    expectTypeOf(publicPreparedRecipe).parameter(0).toMatchTypeOf<PreparedFrame>();
+    expectTypeOf(publicPreparedRecipe).returns.toMatchTypeOf<RenderFeature<PreparedFrame>>();
+    expect(typeof publicPreparedRecipe).toBe('function');
+    expect(frame.items).toHaveLength(0);
+  });
+
+  it('keeps structured error fields available without message parsing', () => {
+    const error: RenderFeatureErrorDescriptor = {
+      code: 'render-feature-stage-failed',
+      expected: "feature 'docs.prepared-graphics' completes its plan stage without an error",
+      hint: "correct 'docs.prepared-graphics' plan data and retry on the next frame",
+      detail: {
+        featureIdentity: 'docs.prepared-graphics',
+        order: 0,
+        stage: 'plan',
+        recovery: 'next-frame',
+      },
+    };
+    expect(describeRenderFeatureError(error)).toBe('docs.prepared-graphics:plan:next-frame');
+    expect(error.expected).toContain('plan');
+    expect(error.hint).toContain('next frame');
+    expect(error.detail.recovery).toBe('next-frame');
+  });
+});

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

@@ -0,0 +1,72 @@
+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 { RenderFeaturePlan } from '../features/plan';
+import type { RenderFeature } from '../features/types';
+
+const caps = { backendKind: 'null' } as unknown as Readonly<RhiCaps>;
+
+function ordinaryFeature(identity: string): RenderFeature<{ readonly work: true }> {
+  return {
+    identity,
+    extract: () => ok({ work: true }),
+    plan: () => ok({ resources: [], passes: [] }),
+  };
+}
+
+function preparedFeature(
+  identity: string,
+  mode: 'healthy' | 'invalid' | 'empty',
+): RenderFeature<{ readonly work: true }> {
+  return {
+    identity,
+    extract: () => ok({ work: true }),
+    plan: () => {
+      if (mode === 'empty') return ok({ resources: [], passes: [] });
+      if (mode === 'invalid') {
+        return err(new RenderFeatureStageFailedError(identity, 0, 'plan', 'next-frame'));
+      }
+      const value: RenderFeaturePlan = { resources: [], passes: [] };
+      return ok(value);
+    },
+  };
+}
+
+describe('prepared graphics feature isolation', () => {
+  it('aborts only the failed feature while preserving healthy and base contributions', () => {
+    const host = createRenderFeatureHost([
+      preparedFeature('synthetic.failed', 'invalid'),
+      ordinaryFeature('synthetic.healthy'),
+    ]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps,
+    });
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]).toMatchObject({
+      detail: { featureIdentity: 'synthetic.failed' },
+    });
+    expect(result.plans.map((contribution) => contribution.featureIdentity)).toEqual([
+      'synthetic.healthy',
+    ]);
+    expect(result.plans[0]?.plan).toEqual({ resources: [], passes: [] });
+  });
+
+  it('treats an empty feature as successful no-work without a phantom graphics pass', () => {
+    const host = createRenderFeatureHost([preparedFeature('synthetic.empty', 'empty')]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      caps,
+    });
+    expect(result.errors).toEqual([]);
+    expect(result.plans[0]?.plan).toEqual({ resources: [], passes: [] });
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+});

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

@@ -0,0 +1,36 @@
+import { ok } from '@forgeax/engine-types';
+import type { RenderFeature } from '../index';
+
+interface Frame {
+  readonly count: number;
+}
+
+const feature = {
+  identity: 'prepared.graphics.negative',
+  extract: () => ok<Frame>({ count: 1 }),
+  plan(data, context) {
+    void data;
+    void context.caps;
+    void context.frame;
+    void context.generation;
+    void context.targets;
+
+    // @ts-expect-error plan descriptors cannot access a raw device
+    context.device;
+    // @ts-expect-error plan descriptors cannot access a command queue
+    context.queue;
+    // @ts-expect-error plan descriptors cannot access a command encoder
+    context.encoder;
+    // @ts-expect-error plan descriptors cannot issue submit work
+    context.submit;
+    // @ts-expect-error plan descriptors cannot access the full pipeline context
+    context.pipelineContext;
+    // @ts-expect-error plan descriptors replace prepared graphics callbacks
+    context.graphics;
+    // @ts-expect-error plan descriptors replace graph staging callbacks
+    context.staging;
+    return ok({ resources: [], passes: [] });
+  },
+} satisfies RenderFeature<Frame>;
+
+void feature;