@forgeax/engine-render 0.1.4 → 0.1.7

package/src/features/types.ts

@@ -2,201 +2,50 @@
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import type { RhiCaps } from '@forgeax/engine-rhi';
 import type { Result } from '@forgeax/engine-types';
-import type { RenderError } from '../errors/render';
+import type { RenderError, RenderFeatureErrorDescriptor } from '../errors/render';
 import type { VisibilitySnapshot } from '../extract/visibility';
-import type { RenderFeatureContributionStaging } from './graph-contribution';
-import type { RenderFeatureGpuPrepare } from './prepared-gpu-work';
-import type {
-  PreparedKind,
-  RenderFeatureGraphicsContributionStaging,
-  RenderFeatureGraphicsPrepare,
-} from './prepared-graphics';
-import type { RenderFeatureTargetHandle } from './targets';
-
+import type { RenderFeaturePlan, RenderFeaturePlanContext } from './plan';
+import type { RenderFeatureCapabilityKey } from './vocabulary';
+
+export type {
+  RenderFeatureCapabilityMissingDetail,
+  RenderFeatureCleanupFailure,
+  RenderFeatureDrawRecordingFailedDetail,
+  RenderFeatureErrorCode,
+  RenderFeatureErrorDescriptor,
+  RenderFeaturePassOrderConflictDetail,
+  RenderFeaturePreparationFailedDetail,
+  RenderFeaturePreparedStateMismatchDetail,
+  RenderFeatureRegistrationConflictDetail,
+  RenderFeatureStageFailedDetail,
+} from '../errors/render';
+export type {
+  RenderFeatureDispatch,
+  RenderFeatureDraw,
+  RenderFeatureDrawDeclaration,
+  RenderFeatureFullscreenProgramDeclaration,
+  RenderFeatureLogicalTarget,
+  RenderFeaturePassDeclaration,
+  RenderFeaturePlan,
+  RenderFeaturePlanContext,
+  RenderFeatureResourceDeclaration,
+  RenderFeatureResourceUsage,
+} from './plan';
 export type { RenderFeatureTargetHandle } from './targets';
+export type {
+  PreparedKind,
+  RenderFeatureCapabilityKey,
+  RenderFeatureRecovery,
+  RenderFeatureStage,
+} from './vocabulary';
 
 /** Closed lifecycle states exposed by the feature host. */
 export type RenderFeatureStatus = 'active' | 'failed' | 'disabled' | 'disposed';
 
-/** Callback stages that can attribute a feature failure. */
-export type RenderFeatureStage =
-  | 'extract'
-  | 'prepare'
-  | 'contribute'
-  | 'record'
-  | 'recover'
-  | 'dispose';
-
-/** Recovery action attached to a structured feature failure. */
-export type RenderFeatureRecovery = 'next-frame' | 'renderer-recover' | 'registration';
-
-/**
- * Render-owned feature error codes. The detail map below is the membership
- * owner consumed by the RenderError union.
- */
-export type RenderFeatureErrorCode = keyof RenderFeatureErrorDetailByCode;
-
-/** Boolean capability names are derived from the RHI capability source. */
-type BooleanCapabilityKey = {
-  [Key in keyof RhiCaps]-?: RhiCaps[Key] extends boolean ? Key : never;
-}[keyof RhiCaps];
-
-export type RenderFeatureCapabilityKey = BooleanCapabilityKey;
-
-export interface RenderFeatureRegistrationConflictDetail {
-  readonly featureIdentity: string;
-  readonly order: number;
-  readonly conflictingOrder: number;
-}
-
-export interface RenderFeatureStageFailedDetail {
-  readonly featureIdentity: string;
-  readonly order: number;
-  readonly stage: RenderFeatureStage;
-  readonly recovery: RenderFeatureRecovery;
-  readonly cleanupFailures?: readonly RenderFeatureCleanupFailure[];
-}
-
-export interface RenderFeatureCleanupFailure {
-  readonly featureIdentity: string;
-  readonly order: number;
-  readonly code: string;
-}
-
-export interface RenderFeatureCapabilityMissingDetail {
-  readonly featureIdentity: string;
-  readonly order: number;
-  readonly capability: RenderFeatureCapabilityKey;
-}
-
-export interface RenderFeaturePassOrderConflictDetail {
-  readonly featureIdentity: string;
-  readonly order: number;
-  readonly passIdentity: string;
-  readonly dependencyIdentity: string;
-}
-
-export interface RenderFeaturePreparationFailedDetail {
-  readonly featureIdentity: string;
-  readonly order: number;
-  readonly stage: 'prepare';
-  readonly operation: string;
-  readonly resourceKind: PreparedKind;
-  readonly resourceName: string;
-  readonly reason: string;
-  readonly recovery: RenderFeatureRecovery;
-}
-
-export type RenderFeaturePreparedStateMismatchDetail =
-  | {
-      readonly featureIdentity: string;
-      readonly order: number;
-      readonly stage: 'contribute';
-      readonly operation: string;
-      readonly resourceKind: PreparedKind;
-      readonly reason: 'missing-prepared-state';
-      readonly missingResource: string;
-      readonly recovery: RenderFeatureRecovery;
-    }
-  | {
-      readonly featureIdentity: string;
-      readonly order: number;
-      readonly stage: 'contribute';
-      readonly operation: string;
-      readonly resourceKind: PreparedKind;
-      readonly reason: 'foreign-feature';
-      readonly expectedFeatureIdentity: string;
-      readonly actualFeatureIdentity: string;
-      readonly recovery: RenderFeatureRecovery;
-    }
-  | {
-      readonly featureIdentity: string;
-      readonly order: number;
-      readonly stage: 'contribute';
-      readonly operation: string;
-      readonly resourceKind: PreparedKind;
-      readonly reason: 'foreign-kind';
-      readonly expectedKind: PreparedKind;
-      readonly actualKind: PreparedKind;
-      readonly recovery: RenderFeatureRecovery;
-    }
-  | {
-      readonly featureIdentity: string;
-      readonly order: number;
-      readonly stage: 'contribute';
-      readonly operation: string;
-      readonly resourceKind: PreparedKind;
-      readonly reason: 'generation-mismatch';
-      readonly expectedGeneration: number;
-      readonly actualGeneration: number;
-      readonly recovery: RenderFeatureRecovery;
-    }
-  | {
-      readonly featureIdentity: string;
-      readonly order: number;
-      readonly stage: 'contribute';
-      readonly operation: string;
-      readonly resourceKind: PreparedKind;
-      readonly reason: 'layout-mismatch';
-      readonly expectedLayout: string;
-      readonly actualLayout: string;
-      readonly recovery: RenderFeatureRecovery;
-    }
-  | {
-      readonly featureIdentity: string;
-      readonly order: number;
-      readonly stage: 'contribute';
-      readonly operation: string;
-      readonly resourceKind: PreparedKind;
-      readonly reason: 'format-mismatch';
-      readonly expectedFormat: string;
-      readonly actualFormat: string;
-      readonly recovery: RenderFeatureRecovery;
-    };
-
-export interface RenderFeatureDrawRecordingFailedDetail {
-  readonly featureIdentity: string;
-  readonly order: number;
-  readonly stage: 'record';
-  readonly operation: string;
-  readonly resourceKind: PreparedKind;
-  readonly reason: string;
-  readonly backendReason: string;
-  readonly recovery: RenderFeatureRecovery;
-}
-
-export type RenderFeatureErrorDetailByCode = {
-  'render-feature-registration-conflict': RenderFeatureRegistrationConflictDetail;
-  'render-feature-stage-failed': RenderFeatureStageFailedDetail;
-  'render-feature-capability-missing': RenderFeatureCapabilityMissingDetail;
-  'render-feature-pass-order-conflict': RenderFeaturePassOrderConflictDetail;
-  'render-feature-preparation-failed': RenderFeaturePreparationFailedDetail;
-  'render-feature-prepared-state-mismatch': RenderFeaturePreparedStateMismatchDetail;
-  'render-feature-draw-recording-failed': RenderFeatureDrawRecordingFailedDetail;
-};
-
-/** Machine-readable four-field diagnostic exposed by every feature error. */
-export type RenderFeatureErrorDescriptor = {
-  [Code in RenderFeatureErrorCode]: {
-    readonly code: Code;
-    readonly expected: string;
-    readonly hint: string;
-    readonly detail: RenderFeatureErrorDetailByCode[Code];
-  };
-}[RenderFeatureErrorCode];
-
-export interface RenderFeatureFrameIdentity {
-  readonly frameNumber: number;
-}
-
 export interface RenderFeatureResourceHandle {
   readonly __renderFeatureResource: unique symbol;
 }
 
-export interface RenderFeatureErrorSink {
-  report(error: RenderError): void;
-}
-
 /** One World-local visibility snapshot prepared for the current frame batch. */
 export interface RenderFeatureWorldVisibilitySnapshot {
   readonly world: World;
@@ -219,47 +68,13 @@ export interface RenderFeatureExtractContext {
   readonly reportHiddenEntity?: (report: RenderFeatureHiddenEntityReport) => void;
 }
 
-/**
- * Host-owned preparation surface. A feature prepares references here first and
- * consumes them later through the contribute staging surface. The host owns
- * resources and generation validity for the whole lifecycle.
- */
-export interface RenderFeaturePrepareContext {
-  readonly caps: Readonly<RhiCaps>;
-  readonly frame: RenderFeatureFrameIdentity;
-  readonly resources: readonly RenderFeatureResourceHandle[];
-  readonly targets: readonly RenderFeatureTargetHandle[];
-  readonly reportError: RenderFeatureErrorSink;
-  /** Controlled pipeline, bindings, vertex-data, and index-data preparation. */
-  readonly graphics: RenderFeatureGraphicsPrepare;
-  /** Renderer-owned persistent compute/storage preparation, when compute is available. */
-  readonly gpu?: RenderFeatureGpuPrepare;
-}
-
-/** The narrow context visible to a feature-owned graph pass. */
-export interface RenderFeaturePassContext {
-  readonly frame: RenderFeatureFrameIdentity;
-  /** The named pass currently executing inside the active RenderGraph. */
-  readonly pass: {
-    readonly name: string;
-    readonly reads: readonly string[];
-    readonly writes: readonly string[];
-  };
-}
-
-export interface RenderFeatureContributeContext extends RenderFeaturePrepareContext {
-  /** Graph-owned staging retains the ordinary graph-only `addPass` path. */
-  readonly staging: RenderFeatureContributionStaging & RenderFeatureGraphicsContributionStaging;
-}
-
 /**
  * Producer-owned extension seam for one render frame.
  *
- * `FrameData` is the single value that crosses extract, prepare, and
- * contribute. A producer owns its shape; the host owns ordering, failure
- * isolation, graph composition, recovery, generation checks, and disposal.
- * The lifecycle is extract -> prepare -> contribute, with optional recover and
- * dispose callbacks.
+ * `FrameData` is the single value that crosses extract into the mandatory
+ * declarative plan. The host derives preparation, graph access, recording,
+ * recovery, and retirement from that plan; no producer callback receives GPU
+ * authority or maintains a parallel lifecycle.
  */
 export interface RenderFeature<FrameData> {
   readonly identity: string;
@@ -271,10 +86,7 @@ export interface RenderFeature<FrameData> {
    */
   readonly requiredMaterialShaders?: readonly string[];
   extract(context: RenderFeatureExtractContext): Result<FrameData, RenderError>;
-  prepare(data: FrameData, context: RenderFeaturePrepareContext): Result<void, RenderError>;
-  contribute(data: FrameData, context: RenderFeatureContributeContext): Result<void, RenderError>;
-  recover?(context: RenderFeaturePrepareContext): Result<void, RenderError>;
-  dispose?(context: RenderFeaturePrepareContext): Result<void, RenderError>;
+  plan(data: FrameData, context: RenderFeaturePlanContext): Result<RenderFeaturePlan, RenderError>;
 }
 
 export interface RenderFeatureRecoverInput {

package/src/features/vocabulary.ts

@@ -0,0 +1,24 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+
+/** Closed prepared-resource kinds owned by the RenderFeature vocabulary. */
+export type PreparedKind = 'pipeline' | 'bindings' | 'vertex-data' | 'index-data' | 'attachment';
+
+/** Closed stages that can attribute a feature failure. */
+export type RenderFeatureStage =
+  | 'extract'
+  | 'plan'
+  | 'prepare'
+  | 'contribute'
+  | 'record'
+  | 'recover'
+  | 'dispose';
+
+/** Recovery action attached to a structured feature failure. */
+export type RenderFeatureRecovery = 'next-frame' | 'renderer-recover' | 'registration';
+
+/** Boolean capability names are derived from the RHI capability source. */
+type BooleanCapabilityKey = {
+  [Key in keyof RhiCaps]-?: RhiCaps[Key] extends boolean ? Key : never;
+}[keyof RhiCaps];
+
+export type RenderFeatureCapabilityKey = BooleanCapabilityKey;

package/src/fullscreen-post-process-pass.ts

@@ -9,7 +9,7 @@
 //   and swap-chain non-srgb storage view write (R-COLORSPACE)
 // - Reads input texture, writes to declared color target with fullscreen 3-vertex draw
 //
-// Registered via renderer.postProcess.register(id, {source, params, reads?}) — a parallel
+// Registered through the feature host ({source, params, reads?}) — a parallel
 // channel to installMaterialArtifact (D-4: material shader = 4-BGL / 12-float vertex / depth /
 // triangle-list; fullscreen post-process = 0 vertex buffer / no depth / input-texture BGL).
 
@@ -56,12 +56,12 @@ const FULLSCREEN_DEFAULT_SPEC: PipelineSpec = Object.freeze({
  */
 export type PostProcessReadSampleType = 'depth';
 
-// ─── Post-process shader entry (registered via postProcess.register) ──────
+// ─── Post-process shader entry (owned by the fullscreen feature host) ──────
 
 /**
- * A registered fullscreen post-process shader entry.
+ * A fullscreen post-process shader entry owned by the feature host.
  *
- * Analogous to MaterialShaderEntry in the ShaderRegistry but with post-process-specific
+ * Analogous to MaterialShaderEntry in the ShaderCatalog but with post-process-specific
  * fields: the input-texture + sampler BGL is auto-built by the primitive,
  * no paramSchema (params are passed inline via a {type, value} struct — plan-strategy D-4).
  *
@@ -130,31 +130,7 @@ export interface PostProcessParamsSchema {
   readonly defaultValue: Uint8Array;
 }
 
-// ─── Fullscreen pass descriptor (passed to addFullscreenPass) ────────────
-
-/**
- * Descriptor for a fullscreen post-process pass. Declares which registered shader
- * to use, which color target to write, and which graph resource(s) to read.
- */
-export interface FullscreenPassDescriptor {
-  /** Registered post-process shader id (must be registered via postProcess.register). */
-  readonly shader: string;
-  /**
-   * Color target: the graph resource key to write into. The pipeline must have
-   * already declared this target via `graph.addColorTarget` (the dispatcher
-   * resolves it, it does not auto-create one); a pass that names an undeclared
-   * key falls back to the swap-chain `ctx.view`.
-   */
-  readonly color: string;
-  /**
-   * Graph resource keys to read. The primitive binds the first read entry as its
-   * input texture (@group(1) @binding(0); sampler @binding(1)). Passes with
-   * reads==[] sample the swap-chain directly (copyTextureToTexture path — plan-strategy D-1).
-   */
-  readonly reads?: readonly string[] | undefined;
-}
-
-// ─── Context passed to addFullscreenPass injectors ───────────────────────
+// ─── Context passed to typed fullscreen feature injectors ─────────────────
 
 /**
  * The minimal surface a `registerFullscreenPostProcess` injector receives.
@@ -178,7 +154,7 @@ export interface FullscreenPostProcessDeviceContext {
 // Historical context: this BGL was duplicated across recordFxaaPass +
 // register-default-post-process before convergence (feat-20260609 framebuffers
 // demo M5R2 / T-12-a). R3 historical bug: the descriptor wrote sampleType:
-// 'float' for any input including depth32float views, tripping wgpu's
+// 'float' for every input including depth32float views, tripping wgpu's
 // Filtering sampler vs UnfilterableFloat / Depth texture static-sample-pair
 // validation. The dispatcher derives sampleType from spec.attachments
 // (depth32float -> 'depth' + 'comparison' sampler; r32float ->
@@ -228,17 +204,6 @@ export function entryHasDepthRead(entry: PostProcessShaderEntry): boolean {
   return entry.reads.some((r) => typeof r !== 'string' && r.sampleType === 'depth');
 }
 
-function entryHasGbufferReads(entry: PostProcessShaderEntry): boolean {
-  const keys = new Set(
-    (entry.reads ?? []).map((read) => (typeof read === 'string' ? read : read.key)),
-  );
-  return (
-    keys.has('gbuffer-normal-roughness') &&
-    keys.has('gbuffer-emissive-ao') &&
-    entryHasDepthRead(entry)
-  );
-}
-
 /**
  * Byte size of the minimal params UBO auto-allocated for a depth-reading entry
  * that declares no `params`. The `'fullscreen-post-with-scene-depth'` BGL always
@@ -253,7 +218,7 @@ export const DEPTH_MIN_PARAMS_BYTE_SIZE = 16;
 /**
  * State of a registered fullscreen post-process pass.
  *
- * Created by `addFullscreenPass` and stored per-pass in the render system.
+ * Created by the typed fullscreen feature graph and stored per-pass in the render system.
  * The `draw` method is called by the per-frame execute closure.
  */
 export interface FullscreenPostProcessPassHandle {
@@ -307,15 +272,13 @@ export function buildFullscreenPostProcessPass(
   // texture variant for a 4-sample scene target. params@2 is always present to
   // avoid 2x2 kind explosion.
   const hasDepth = entryHasDepthRead(entry);
-  const bglKind: BglKind = entryHasGbufferReads(entry)
-    ? 'fullscreen-post-with-gbuffer-depth'
-    : hasDepth
-      ? depthMultisampled
-        ? 'fullscreen-post-with-scene-depth-msaa'
-        : 'fullscreen-post-with-scene-depth'
-      : entry.params !== undefined
-        ? 'fullscreen-post-with-params'
-        : 'fullscreen-post';
+  const bglKind: BglKind = hasDepth
+    ? depthMultisampled
+      ? 'fullscreen-post-with-scene-depth-msaa'
+      : 'fullscreen-post-with-scene-depth'
+    : entry.params !== undefined
+      ? 'fullscreen-post-with-params'
+      : 'fullscreen-post';
   const bglRes = device.createBindGroupLayout(
     buildBindGroupLayoutDescriptor(FULLSCREEN_DEFAULT_SPEC, {
       kind: bglKind,
@@ -371,8 +334,6 @@ export function createFullscreenBindGroup(
   paramsBuffer?: Buffer | null,
   depthTexView?: TextureView | null,
   depthSampler?: Sampler | null,
-  gbufferNormalView?: TextureView | null,
-  gbufferEmissiveView?: TextureView | null,
 ): BindGroup | null {
   const entries: { binding: number; resource: { kind: string; value: unknown } }[] = [
     { binding: 0, resource: { kind: 'textureView', value: inputView } },
@@ -392,10 +353,6 @@ export function createFullscreenBindGroup(
     entries.push({ binding: 3, resource: { kind: 'textureView', value: depthTexView } });
     entries.push({ binding: 4, resource: { kind: 'sampler', value: depthSampler } });
   }
-  if (gbufferNormalView && gbufferEmissiveView) {
-    entries.push({ binding: 5, resource: { kind: 'textureView', value: gbufferNormalView } });
-    entries.push({ binding: 6, resource: { kind: 'textureView', value: gbufferEmissiveView } });
-  }
   const res = device.createBindGroup({
     label: 'fullscreen-post-process-bg',
     layout: bgl,