@forgeax/engine-render 0.1.4 → 0.1.6

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

@@ -8,37 +8,28 @@ import type { RenderFeature } from '../features/types';
 const caps = (compute: boolean): Readonly<RhiCaps> =>
   ({ backendKind: 'null', compute }) as unknown as RhiCaps;
 
-function feature(
-  mode: 'healthy' | 'failed',
-  recoverCalls: number[],
-): RenderFeature<{ readonly ready: true }> {
+function feature(mode: 'healthy' | 'failed'): RenderFeature<{ readonly ready: true }> {
   return {
     identity: `synthetic.diagnostics.${mode}`,
     requiredCapabilities: ['compute'],
     extract: () => ok({ ready: true }),
-    prepare: () =>
+    plan: () =>
       mode === 'failed'
         ? err(
             new RenderFeatureStageFailedError(
               `synthetic.diagnostics.${mode}`,
               0,
-              'prepare',
+              'plan',
               'next-frame',
             ),
           )
-        : ok(undefined),
-    contribute: () => ok(undefined),
-    recover: () => {
-      recoverCalls.push(1);
-      return ok(undefined);
-    },
+        : ok({ resources: [], passes: [] }),
   };
 }
 
 describe('render feature prepared diagnostics', () => {
   it('projects disabled and failed states with code-directed recovery data', () => {
-    const recoverCalls: number[] = [];
-    const disabledHost = createRenderFeatureHost([feature('healthy', recoverCalls)]).unwrap();
+    const disabledHost = createRenderFeatureHost([feature('healthy')]).unwrap();
     runRenderFeatureFrame(disabledHost, {
       worlds: [],
       owner: 0,
@@ -56,7 +47,7 @@ describe('render feature prepared diagnostics', () => {
     expect(disabled?.latestError?.expected).toContain('compute');
     expect(disabled?.latestError?.hint).toContain('disable');
 
-    const failedHost = createRenderFeatureHost([feature('failed', recoverCalls)]).unwrap();
+    const failedHost = createRenderFeatureHost([feature('failed')]).unwrap();
     runRenderFeatureFrame(failedHost, {
       worlds: [],
       owner: 0,
@@ -68,18 +59,16 @@ describe('render feature prepared diagnostics', () => {
       status: 'failed',
       latestError: {
         code: 'render-feature-stage-failed',
-        detail: { stage: 'prepare', recovery: 'next-frame' },
+        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 recoverCalls: number[] = [];
-    const host = createRenderFeatureHost([feature('healthy', recoverCalls)]).unwrap();
+    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(recoverCalls).toHaveLength(1);
 
     expect(host.dispose()).toEqual(ok(undefined));
     expect(host.dispose()).toEqual(ok(undefined));

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

@@ -1,9 +1,6 @@
-import type {
-  PreparedKind,
-  RenderFeatureErrorCode,
-  RenderFeatureErrorDescriptor,
-  RenderFeatureRecovery,
-} from '../index';
+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) {

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

@@ -1,22 +1,11 @@
-import type {
-  RenderError,
-  RenderFeature,
-  RenderFeatureErrorDescriptor,
-  RenderFeaturePreparedRef,
-} from '@forgeax/engine-render';
-import { ok, type Result } from '@forgeax/engine-types';
+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[];
 };
 
-interface PreparedGraphicsRefs {
-  readonly pipeline: RenderFeaturePreparedRef<'pipeline'>;
-  readonly bindings: RenderFeaturePreparedRef<'bindings'>;
-  readonly vertexData: RenderFeaturePreparedRef<'vertex-data'>;
-}
-
 function describeRenderFeatureError(error: RenderFeatureErrorDescriptor): string {
   switch (error.code) {
     case 'render-feature-registration-conflict':
@@ -51,62 +40,12 @@ function describeRenderFeatureError(error: RenderFeatureErrorDescriptor): string
 }
 
 function publicPreparedRecipe(frame: PreparedFrame): RenderFeature<PreparedFrame> {
-  let prepared: PreparedGraphicsRefs | undefined;
   const feature: RenderFeature<PreparedFrame> = {
     identity: 'docs.prepared-graphics',
     extract: () => ok(frame),
-    prepare: (data, context): Result<void, RenderError> => {
-      const pipeline = context.graphics.preparePipeline('docs.pipeline', {
-        shader: 'docs.shader',
-        vertexLayout: 'particle-billboard',
-        colorFormats: ['rgba8unorm-srgb'],
-      });
-      if (!pipeline.ok) return pipeline;
-      const bindings = context.graphics.prepareBindings('docs.bindings', {
-        pipeline: pipeline.value,
-        values: { itemCount: data.items.length },
-      });
-      if (!bindings.ok) return bindings;
-      const vertexData = context.graphics.prepareVertexData('docs.vertices', {
-        layout: 'particle-billboard',
-        data: new Float32Array(),
-      });
-      if (!vertexData.ok) return vertexData;
-      prepared = {
-        pipeline: pipeline.value,
-        bindings: bindings.value,
-        vertexData: vertexData.value,
-      };
-      return ok(undefined);
-    },
-    contribute: (data, context): Result<void, RenderError> => {
-      if (prepared === undefined) {
-        return ok(undefined);
-      }
-      return context.staging.addGraphicsPass('docs.prepared-pass', {
-        attachments: {
-          colors: [
-            {
-              resource: 'swap-chain',
-              format: 'rgba8unorm-srgb',
-              loadOp: 'load',
-              storeOp: 'store',
-            },
-          ],
-        },
-        draws: [
-          {
-            kind: 'draw',
-            pipeline: prepared.pipeline,
-            bindings: [prepared.bindings],
-            vertexData: [{ slot: 0, resource: prepared.vertexData }],
-            command: {
-              vertexCount: data.items.length * 0,
-              instanceCount: 1,
-            },
-          },
-        ],
-      });
+    plan: (data) => {
+      void data.items.length;
+      return ok({ resources: [], passes: [] });
     },
   };
   return feature;
@@ -124,17 +63,17 @@ describe('public prepared graphics recipe', () => {
   it('keeps structured error fields available without message parsing', () => {
     const error: RenderFeatureErrorDescriptor = {
       code: 'render-feature-stage-failed',
-      expected: "feature 'docs.prepared-graphics' completes its prepare stage without an error",
-      hint: "correct 'docs.prepared-graphics' prepare data and retry on the next frame",
+      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: 'prepare',
+        stage: 'plan',
         recovery: 'next-frame',
       },
     };
-    expect(describeRenderFeatureError(error)).toBe('docs.prepared-graphics:prepare:next-frame');
-    expect(error.expected).toContain('prepare');
+    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

@@ -3,6 +3,7 @@ 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>;
@@ -11,15 +12,7 @@ function ordinaryFeature(identity: string): RenderFeature<{ readonly work: true
   return {
     identity,
     extract: () => ok({ work: true }),
-    prepare: () => ok(undefined),
-    contribute: (_data, context) => {
-      context.staging.addResource('base', { kind: 'texture', lifetime: 'transient' });
-      return context.staging.addPass('base', {
-        reads: [],
-        writes: ['base'],
-        execute: () => undefined,
-      });
-    },
+    plan: () => ok({ resources: [], passes: [] }),
   };
 }
 
@@ -27,57 +20,16 @@ function preparedFeature(
   identity: string,
   mode: 'healthy' | 'invalid' | 'empty',
 ): RenderFeature<{ readonly work: true }> {
-  let pipeline: { kind: 'pipeline'; generation: number } | undefined;
-  let bindings: { kind: 'bindings'; generation: number } | undefined;
-  let vertices: { kind: 'vertex-data'; generation: number } | undefined;
   return {
     identity,
     extract: () => ok({ work: true }),
-    prepare: (_data, context) => {
-      const preparedPipeline = context.graphics.preparePipeline('forward', {
-        shader: 'synthetic',
-        vertexLayout: 'position',
-        colorFormats: ['rgba8unorm'],
-      });
-      if (!preparedPipeline.ok) return preparedPipeline;
-      const preparedBindings = context.graphics.prepareBindings('forward', {
-        pipeline: preparedPipeline.value,
-        values: {},
-      });
-      if (!preparedBindings.ok) return preparedBindings;
-      const preparedVertices = context.graphics.prepareVertexData('triangle', {
-        layout: 'position',
-        data: [0, 0, 0],
-      });
-      if (!preparedVertices.ok) return preparedVertices;
-      pipeline = preparedPipeline.value;
-      bindings = preparedBindings.value;
-      vertices = preparedVertices.value;
-      return ok(undefined);
-    },
-    contribute: (_data, context) => {
-      if (mode === 'empty') return ok(undefined);
-      if (pipeline === undefined || bindings === undefined || vertices === undefined) {
-        return err(new RenderFeatureStageFailedError(identity, 0, 'contribute', 'next-frame'));
+    plan: () => {
+      if (mode === 'empty') return ok({ resources: [], passes: [] });
+      if (mode === 'invalid') {
+        return err(new RenderFeatureStageFailedError(identity, 0, 'plan', 'next-frame'));
       }
-      context.staging.addResource('color', { kind: 'texture', lifetime: 'transient' });
-      return context.staging.addGraphicsPass('forward', {
-        attachments: {
-          colors:
-            mode === 'healthy'
-              ? [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }]
-              : [{ resource: 'missing', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
-        },
-        draws: [
-          {
-            kind: 'draw',
-            pipeline,
-            bindings: [bindings],
-            vertexData: [{ slot: 0, resource: vertices }],
-            command: { vertexCount: 3, instanceCount: 1 },
-          },
-        ],
-      });
+      const value: RenderFeaturePlan = { resources: [], passes: [] };
+      return ok(value);
     },
   };
 }
@@ -99,12 +51,10 @@ describe('prepared graphics feature isolation', () => {
     expect(result.errors[0]).toMatchObject({
       detail: { featureIdentity: 'synthetic.failed' },
     });
-    expect(result.contributions.map((contribution) => contribution.featureIdentity)).toEqual([
+    expect(result.plans.map((contribution) => contribution.featureIdentity)).toEqual([
       'synthetic.healthy',
     ]);
-    expect(result.contributions[0]?.passes.map((pass) => pass.name)).toEqual([
-      'synthetic.healthy::base',
-    ]);
+    expect(result.plans[0]?.plan).toEqual({ resources: [], passes: [] });
   });
 
   it('treats an empty feature as successful no-work without a phantom graphics pass', () => {
@@ -116,7 +66,7 @@ describe('prepared graphics feature isolation', () => {
       caps,
     });
     expect(result.errors).toEqual([]);
-    expect(result.contributions).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

@@ -8,51 +8,28 @@ interface Frame {
 const feature = {
   identity: 'prepared.graphics.negative',
   extract: () => ok<Frame>({ count: 1 }),
-  prepare(data, context) {
+  plan(data, context) {
     void data;
-    void context.graphics;
+    void context.caps;
+    void context.frame;
+    void context.generation;
+    void context.targets;
 
-    // @ts-expect-error prepared callbacks cannot access a raw device
-    context.graphics.device;
-    // @ts-expect-error prepared callbacks cannot access a command encoder
-    context.graphics.commandEncoder;
-    // @ts-expect-error prepared callbacks cannot access the full pipeline context
-    context.graphics.pipelineContext;
-    // @ts-expect-error prepared callbacks cannot issue submit work
-    context.graphics.submit;
-    // @ts-expect-error prepared callbacks cannot issue compute work
-    context.graphics.compute;
-    // @ts-expect-error prepared callbacks cannot access storage buffers
-    context.graphics.storageBuffer;
-    // @ts-expect-error prepared callbacks cannot issue indirect draws
-    context.graphics.drawIndirect;
-    // @ts-expect-error prepared callbacks cannot access backend-specific handles
-    context.graphics.backendHandle;
-    return ok(undefined);
-  },
-  contribute(data, context) {
-    void data;
-    void context.graphics;
-    // The legacy graph-only entry remains the only way to add ordinary graph work.
-    void context.staging.addPass;
-
-    // @ts-expect-error contribution cannot access a raw device
-    context.graphics.device;
-    // @ts-expect-error contribution cannot access a command encoder
-    context.graphics.commandEncoder;
-    // @ts-expect-error contribution cannot access the full pipeline context
-    context.graphics.pipelineContext;
-    // @ts-expect-error contribution cannot issue submit work
-    context.graphics.submit;
-    // @ts-expect-error contribution cannot issue compute work
-    context.graphics.compute;
-    // @ts-expect-error contribution cannot access storage buffers
-    context.graphics.storageBuffer;
-    // @ts-expect-error contribution cannot issue indirect draws
-    context.graphics.drawIndirect;
-    // @ts-expect-error contribution cannot access backend-specific handles
-    context.graphics.backendHandle;
-    return ok(undefined);
+    // @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>;