@forgeax/engine-render 0.1.4 → 0.1.6

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

@@ -1,6 +1,6 @@
 import { ok } from '@forgeax/engine-types';
-import type { RenderFeature } from '../features/types';
-import type { RendererOptions } from '../renderer';
+import type { RenderFeature, RenderFeaturePlanContext } from '../features/types';
+import type { RendererOptions } from '../render-contract';
 
 type BoundsFrame = {
   readonly visibleCount: number;
@@ -15,15 +15,11 @@ const boundsFeature = {
   extract({ owner }) {
     return ok({ visibleCount: owner });
   },
-  prepare(data: BoundsFrame) {
+  plan(data: BoundsFrame, context: RenderFeaturePlanContext) {
     const count: number = data.visibleCount;
     void count;
-    return ok(undefined);
-  },
-  contribute(data: BoundsFrame) {
-    const count: number = data.visibleCount;
-    void count;
-    return ok(undefined);
+    void context;
+    return ok({ resources: [], passes: [] });
   },
 } satisfies RenderFeature<BoundsFrame>;
 
@@ -32,15 +28,11 @@ const overlayFeature = {
   extract() {
     return ok({ layer: 'overlay' as const });
   },
-  prepare(data: OverlayFrame) {
-    const layer: 'overlay' = data.layer;
-    void layer;
-    return ok(undefined);
-  },
-  contribute(data: OverlayFrame) {
+  plan(data: OverlayFrame, context: RenderFeaturePlanContext) {
     const layer: 'overlay' = data.layer;
     void layer;
-    return ok(undefined);
+    void context;
+    return ok({ resources: [], passes: [] });
   },
 } satisfies RenderFeature<OverlayFrame>;
 

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

@@ -22,59 +22,35 @@ const feature = {
     context.encoder;
     return ok({ count: worlds.length });
   },
-  prepare(data, context) {
+  plan(data, context) {
     const count: number = data.count;
     const caps = context.caps;
-    const resources = context.resources;
     const targets = context.targets;
     const frame = context.frame;
-    const reportError = context.reportError;
+    const generation = context.generation;
     void count;
     void caps;
-    void resources;
     void targets;
     void frame;
-    void reportError;
+    void generation;
 
-    // @ts-expect-error prepare must not receive the live World collection
+    // @ts-expect-error plan must not receive the live World collection
     context.worlds;
-    // @ts-expect-error prepare must not receive the complete pipeline context
+    // @ts-expect-error plan must not receive the complete pipeline context
     context.pipeline;
-    // @ts-expect-error prepare must not receive a raw device
+    // @ts-expect-error plan must not receive a raw device
     context.device;
-    // @ts-expect-error prepare must not expose submit or compute commands
+    // @ts-expect-error plan must not expose a queue
+    context.queue;
+    // @ts-expect-error plan must not expose submit commands
     context.submit;
-    // @ts-expect-error prepare must not expose storage or indirect commands
-    context.storageBuffer;
-    // @ts-expect-error prepare must not expose the full command encoder
-    context.commandEncoder;
-    return ok(undefined);
-  },
-  contribute(data, context) {
-    const count: number = data.count;
-    const frame = context.frame;
-    const resources = context.resources;
-    const targets = context.targets;
-    const reportError = context.reportError;
-    void count;
-    void frame;
-    void resources;
-    void targets;
-    void reportError;
-
-    // @ts-expect-error contribute must not receive the live World collection
-    context.worlds;
-    // @ts-expect-error contribute must not receive the complete pipeline context
-    context.pipeline;
-    // @ts-expect-error contribute must not expose raw device access
-    context.device;
-    // @ts-expect-error contribute must not expose submit, compute, or storage commands
-    context.submit;
-    // @ts-expect-error contribute must not expose indirect draw commands
-    context.drawIndirect;
-    // @ts-expect-error Wave1 stops at the graph seam and exposes no GPU commands
-    context.commands;
-    return ok(undefined);
+    // @ts-expect-error plan must not expose a command encoder
+    context.encoder;
+    // @ts-expect-error plan descriptors replace staging callbacks
+    context.staging;
+    // @ts-expect-error plan descriptors replace prepared graphics callbacks
+    context.graphics;
+    return ok({ resources: [], passes: [] });
   },
 } satisfies RenderFeature<Frame>;
 

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

@@ -1,5 +1,5 @@
 import { ok } from '@forgeax/engine-types';
-import type { RenderFeature } from '../features/types';
+import type { RenderFeature, RenderFeaturePlanContext } from '../features/types';
 
 type AlphaFrame = {
   readonly visibleCount: number;
@@ -12,35 +12,26 @@ type BetaFrame = {
 const alphaFeature = {
   identity: 'synthetic.alpha',
   extract({ owner }) {
-    const frame: AlphaFrame = { visibleCount: owner };
-    return ok(frame);
+    return ok<AlphaFrame>({ visibleCount: owner });
   },
-  prepare(data: AlphaFrame) {
+  plan(data: AlphaFrame, context: RenderFeaturePlanContext) {
     const count: number = data.visibleCount;
     void count;
-    return ok(undefined);
-  },
-  contribute(data: AlphaFrame) {
-    const count: number = data.visibleCount;
-    void count;
-    return ok(undefined);
+    void context;
+    return ok({ resources: [], passes: [] });
   },
 } satisfies RenderFeature<AlphaFrame>;
 
 const betaFeature = {
   identity: 'synthetic.beta',
   extract() {
-    return ok({ bounds: [0, 0, 1, 1] as const });
-  },
-  prepare(data: BetaFrame) {
-    const bounds: BetaFrame['bounds'] = data.bounds;
-    void bounds;
-    return ok(undefined);
+    return ok<BetaFrame>({ bounds: [0, 0, 1, 1] });
   },
-  contribute(data: BetaFrame) {
+  plan(data: BetaFrame, context: RenderFeaturePlanContext) {
     const bounds: BetaFrame['bounds'] = data.bounds;
     void bounds;
-    return ok(undefined);
+    void context;
+    return ok({ resources: [], passes: [] });
   },
 } satisfies RenderFeature<BetaFrame>;
 

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

@@ -12,8 +12,7 @@ function gatedFeature(): RenderFeature<{ readonly frame: number }> {
     identity: 'synthetic.gated',
     requiredCapabilities: ['compute'],
     extract: ({ frameNumber }) => ok({ frame: frameNumber }),
-    prepare: () => ok(undefined),
-    contribute: () => ok(undefined),
+    plan: () => ok({ resources: [], passes: [] }),
   };
 }
 
@@ -71,7 +70,7 @@ describe('render feature diagnostics and capability gate', () => {
         frameNumber: 1,
         caps: caps(true),
       }).stageEvents,
-    ).toHaveLength(3);
+    ).toHaveLength(2);
   });
 
   it('disables without a capability and re-enables only after recover re-evaluation', () => {
@@ -105,7 +104,7 @@ describe('render feature diagnostics and capability gate', () => {
         frameNumber: 3,
         caps: caps(true),
       }).stageEvents,
-    ).toHaveLength(3);
+    ).toHaveLength(2);
   });
 
   it('replaces the latest stage failure after retry and returns deep readonly snapshots', () => {
@@ -113,15 +112,14 @@ describe('render feature diagnostics and capability gate', () => {
     const feature: RenderFeature<{ readonly ready: true }> = {
       identity: 'synthetic.latest-error',
       extract: () => ok({ ready: true }),
-      prepare: () => {
+      plan: () => {
         if (shouldFail) {
           return err(
-            new RenderFeatureStageFailedError('synthetic.latest-error', 0, 'prepare', 'next-frame'),
+            new RenderFeatureStageFailedError('synthetic.latest-error', 0, 'plan', 'next-frame'),
           );
         }
-        return ok(undefined);
+        return ok({ resources: [], passes: [] });
       },
-      contribute: () => ok(undefined),
     };
     const host = createRenderFeatureHost([feature], caps(true)).unwrap();
 

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

@@ -25,18 +25,18 @@ describe('RenderFeature documentation surface', () => {
       '## RenderFeature: the producer seam',
       'type FrameData',
       'createRenderer(canvas, { features: [feature] })',
-      "context.staging.addPass('named-pass'",
-      'execute: ({ pass })',
+      'plan(data, context)',
+      'named resources and passes',
       'active RenderGraph',
       'RenderFeature',
-      'RenderPipeline',
+      'Standard Pipeline',
       'RenderGraph pass',
-      'Material pass',
     ]) {
       expect(topSurface).toContain(token);
     }
     expect(topSurface).not.toContain('passContext.commands');
-    expect(topSurface).toContain('graph-only Wave 1 feature');
+    expect(topSurface).not.toContain('context.staging.addPass');
+    expect(topSurface).not.toContain('graph-only Wave 1 feature');
     expect(runtimeReadme).toContain('createRenderer(canvas, options?, bundler?)');
     expect(appSkill).toContain('Renderer feature assembly');
   });
@@ -49,10 +49,11 @@ describe('RenderFeature documentation surface', () => {
       'error.code',
       'error.hint',
       'error.detail',
-      'renderFeatureDiagnostics()',
+      'renderer.subscribe()',
+      'renderer.inspect()',
       'renderer.recover()',
       'renderer.dispose()',
-      'renderer.registerPipeline(id, pipeline)',
+      'RenderFeaturePlan',
     ]) {
       expect(surface).toContain(token);
     }

package/src/__tests__/render-feature-gpu-work.integration.test.ts

@@ -1,4 +1,4 @@
-import { RenderGraph, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import {
   type BindGroup,
   type Buffer,
@@ -7,17 +7,13 @@ import {
   type RhiCommandEncoder,
   RhiError,
 } from '@forgeax/engine-rhi';
-import { type RhiNullDevice, rhi } from '@forgeax/engine-rhi-null';
+import { rhi } from '@forgeax/engine-rhi-null';
 import { err, ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import {
-  composeRenderFeatureGraph,
-  type RenderFeatureGraphContribution,
-} from '../features/graph-contribution';
-import { createRenderFeatureGpuWorkResolver } from '../features/prepared-gpu-work';
+import { createRenderFeatureGpuWorkOwner } from '../features/prepared-gpu-work';
 import { RenderFeatureComputeGraphProjection } from '../features/render-graph-compute';
 import { RenderFeatureRasterGraphProjection } from '../features/render-graph-raster';
-import { RenderFeatureGraphBufferRegistry } from '../features/render-graph-resources';
+import { createRenderFeatureGraphBufferState } from '../features/render-graph-resources';
 import type { PreparedGraphicsResolvedResource } from '../prepare/prepared-graphics-resolver';
 
 describe('RenderFeature persistent GPU work', () => {
@@ -32,7 +28,7 @@ describe('RenderFeature persistent GPU work', () => {
       .createTexture('output', { format: 'rgba8unorm', size: { width: 1, height: 1 } })
       .unwrap();
     const outputView = graph.view(output, { label: 'output.view' }).unwrap();
-    const buffers = new RenderFeatureGraphBufferRegistry(graph);
+    const buffers = createRenderFeatureGraphBufferState();
     const compute = new RenderFeatureComputeGraphProjection(graph, buffers);
     expect(
       compute.addPass('vfx.simulate-and-project', 'forgeax.vfx', 0, {
@@ -154,11 +150,9 @@ describe('RenderFeature persistent GPU work', () => {
   it('classifies an asynchronous shader warmup as a next-frame retry', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();
-    const resolver = createRenderFeatureGpuWorkResolver({
-      device,
-      generation: 0,
-      featureIdentity: 'synthetic.gpu',
-      shaderModuleFactory: {
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({
         createShaderModule: () =>
           err(
             new RhiError({
@@ -167,8 +161,9 @@ describe('RenderFeature persistent GPU work', () => {
               hint: 'retry on the next frame',
             }),
           ),
-      },
+      }),
     });
+    const resolver = owner.beginFeature('synthetic.gpu', 0);
 
     const prepared = resolver.prepareProgram('program', {
       wgsl: 'synthetic',
@@ -188,40 +183,15 @@ describe('RenderFeature persistent GPU work', () => {
     }
   });
 
-  it('reuses the shader-module cache label across instance-scoped programs', async () => {
-    const adapter = (await rhi.requestAdapter()).unwrap();
-    const device = (await adapter.requestDevice()).unwrap();
-    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
-    const labels: string[] = [];
-    const resolver = createRenderFeatureGpuWorkResolver({
-      device,
-      generation: 0,
-      featureIdentity: 'synthetic.gpu',
-      shaderModuleFactory: {
-        createShaderModule: ({ label }) => {
-          labels.push(label ?? '');
-          return ok(shader);
-        },
-      },
-    });
-    const descriptor = { wgsl: 'synthetic', entryPoints: ['simulate'] } as const;
-
-    expect(resolver.prepareProgram('player-a.program', descriptor).ok).toBe(true);
-    expect(resolver.prepareProgram('player-b.program', descriptor).ok).toBe(true);
-    expect(labels).toEqual(['synthetic.gpu.program.0', 'synthetic.gpu.program.0']);
-  });
-
   it('records compute against persistent storage and releases it once', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();
     const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
-    const resolver = createRenderFeatureGpuWorkResolver({
-      device,
-      generation: 4,
-      featureIdentity: 'synthetic.gpu',
-      shaderModuleFactory: { createShaderModule: () => ok(shader) },
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({ createShaderModule: () => ok(shader) }),
     });
-    resolver.beginFrame();
+    const resolver = owner.beginFeature('synthetic.gpu', 4);
     const program = resolver
       .prepareProgram('program', {
         wgsl: 'synthetic',
@@ -324,37 +294,6 @@ describe('RenderFeature persistent GPU work', () => {
     expect(compiled.execute({ encoder }).ok).toBe(true);
     expect(encoder.finish().ok).toBe(true);
 
-    const productionGraph = new RenderGraph<{ readonly encoder: RhiCommandEncoder }>();
-    const contribution: RenderFeatureGraphContribution = {
-      featureIdentity: 'synthetic.gpu',
-      order: 0,
-      resources: [],
-      passes: [
-        {
-          featureIdentity: 'synthetic.gpu',
-          order: 0,
-          name: 'synthetic.gpu::compute',
-          descriptor: { reads: [], writes: [] },
-          dependsOn: [],
-          gpuCompute: {
-            program,
-            bindings,
-            dispatches: [{ entryPoint: 'simulate', workgroups: [1] }],
-          },
-          resolvedGpuCompute: work,
-        },
-      ],
-      topologySignature: 'synthetic.gpu::compute',
-    };
-    expect(composeRenderFeatureGraph(productionGraph, [contribution]).ok).toBe(true);
-    expect(productionGraph.compile({ backendKind: 'null', caps: device.caps, device }).ok).toBe(
-      true,
-    );
-    const productionEncoder = device.createCommandEncoder({ label: 'production-feature' }).unwrap();
-    productionGraph.execute({ encoder: productionEncoder });
-    expect(productionEncoder.finish().ok).toBe(true);
-    expect((device as RhiNullDevice).framePassNames).toContain('synthetic.gpu::compute');
-
     expect(resolver.resolveBuffer(storage)).toBeDefined();
     expect(resolver.resolveBuffer(indirect)).toBeDefined();
     expect(resolver.resolveBuffer(dispatchArgs)).toBeDefined();

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;