@forgeax/engine-render 0.1.33 → 0.1.34

package/src/examples/single-layer-medium-surface.ts

@@ -0,0 +1,59 @@
+import type { MaterialRootAsset } from '@forgeax/engine-types';
+
+/**
+ * A public root asset showing the model declaration and its bounded input.
+ * The page is shared by every material instance; Render supplies the page
+ * bytes and each instance publishes its own range.
+ */
+export const SINGLE_LAYER_MEDIUM_SURFACE_EXAMPLE = {
+  kind: 'material',
+  surface: {
+    model: 'single-layer-medium',
+    module: 'game::water_surface_a',
+    dynamicInput: {
+      name: 'waterEvents',
+      fields: [
+        { name: 'position', type: 'vec3<f32>' },
+        { name: 'time', type: 'f32' },
+        { name: 'eventId', type: 'u32' },
+      ],
+      maxRecords: 64,
+      maxDomains: 8,
+      maxPageBytes: 2048,
+      maxBindings: 1,
+      maxEventsPerSample: 8,
+    },
+  },
+  passes: [
+    {
+      name: 'color',
+      program: { module: 'forgeax::single-layer-medium' },
+    },
+  ],
+  parameters: [],
+  values: {},
+} as const satisfies MaterialRootAsset;
+
+/** Two different imported Surface implementations consuming one model ABI. */
+export const SINGLE_LAYER_MEDIUM_SURFACE_EXAMPLES = [
+  {
+    module: 'game::water_surface_a',
+    source: `#define_import_path game::water_surface_a
+#import forgeax_material::single_layer_medium_surface_v1::{SingleLayerMediumSurfaceInput, SingleLayerMediumSurfaceData}
+fn evaluate_surface(input : SingleLayerMediumSurfaceInput) -> SingleLayerMediumSurfaceData {
+  let event = read_waterEvents(input.eventRangeStart);
+  let normal = normalize(input.geometricNormalWS + vec3<f32>(0.0, 0.0, event.time * 0.02));
+  return SingleLayerMediumSurfaceData(normal, 0.18, 1.0, 0.0, vec3<f32>(0.18, 0.06, 0.02), vec3<f32>(0.02, 0.04, 0.08), 1.333, 0.2, 1000.0);
+}`,
+  },
+  {
+    module: 'game::water_surface_b',
+    source: `#define_import_path game::water_surface_b
+#import forgeax_material::single_layer_medium_surface_v1::{SingleLayerMediumSurfaceInput, SingleLayerMediumSurfaceData}
+fn evaluate_surface(input : SingleLayerMediumSurfaceInput) -> SingleLayerMediumSurfaceData {
+  let event = read_waterEvents(input.eventRangeStart);
+  let normal = normalize(input.geometricNormalWS + vec3<f32>(event.position.xy * 0.01, 0.0));
+  return SingleLayerMediumSurfaceData(normal, 0.32, 1.0, clamp(event.time * 0.1, 0.0, 1.0), vec3<f32>(0.04, 0.02, 0.01), vec3<f32>(0.08, 0.05, 0.02), 1.333, -0.1, 800.0);
+}`,
+  },
+] as const;

package/src/extract/camera.ts

@@ -2,6 +2,10 @@ import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { readRenderArrayView } from '@forgeax/engine-ecs/projection';
 import { mat4, vec3 } from '@forgeax/engine-math';
 import { GlobalTransform } from '@forgeax/engine-scene';
+import {
+  BarrelDistortion,
+  validateBarrelDistortionParameters,
+} from '../components/barrel-distortion';
 import {
   antialiasFromF32,
   Camera,
@@ -38,13 +42,20 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
   const cameraQuery = world
     .query({
       read: [Camera],
-      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection, DepthOfField],
+      optional: [
+        MotionBlur,
+        DynamicResolution,
+        ScreenSpaceReflection,
+        DepthOfField,
+        BarrelDistortion,
+      ],
       with: [GlobalTransform],
     })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    const barrelDistortion = row.get(BarrelDistortion);
     const motionBlurResult = resolveMotionBlurParams(motionBlur);
     if (!motionBlurResult.ok) throw motionBlurResult.error;
     const motionBlurParams = motionBlurResult.value;
@@ -75,6 +86,8 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
     const antialias = antialiasFromF32(cam.antialias);
     const dynamicResolutionResult = validateDynamicResolutionCamera(dynamicResolution, antialias);
     if (!dynamicResolutionResult.ok) throw dynamicResolutionResult.error;
+    const barrelDistortionResult = validateBarrelDistortionParameters(barrelDistortion);
+    if (!barrelDistortionResult.ok) throw barrelDistortionResult.error;
     cameras.push({
       entityKey: entity as number,
       historyVersion: cam.historyVersion,
@@ -128,6 +141,7 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
               targetFps: motionBlurParams.targetFps,
             },
           }),
+      ...(barrelDistortion === undefined ? {} : { barrelDistortion: barrelDistortionResult.value }),
       ...(screenSpaceReflection === undefined
         ? {}
         : {

package/src/extract/contracts.ts

@@ -13,6 +13,7 @@ import type {
   MaterialAsset,
   MaterialPass,
   MaterialRenderState,
+  MaterialSurfaceModel,
   MaterialTextureCoordinates,
   MeshLodLevel,
   ParamSchemaEntry,
@@ -652,6 +653,10 @@ export interface MaterialSnapshot {
   readonly baseColor: Vec3;
   readonly metallic: number;
   readonly roughness: number;
+  /** Root-owned Surface model used only for typed pass routing. */
+  readonly surfaceModel?: MaterialSurfaceModel | undefined;
+  /** Whether this material publishes a Deferred pass consumed before the forward-only lane. */
+  readonly deferredPass?: boolean | undefined;
   readonly clearcoat?: number | undefined;
   readonly clearcoatRoughness?: number | undefined;
   /** Authored Standard PBR specular tint in linear runtime color space. */

package/src/features/barrel-distortion.ts

@@ -0,0 +1,172 @@
+/** One graph-valid identity for the barrel stage, feature and shader prewarm. */
+export const BARREL_DISTORTION_POST_PROCESS_ID = 'fullscreen.forgeax.barrel-distortion';
+export const BARREL_DISTORTION_FEATURE_IDENTITY = BARREL_DISTORTION_POST_PROCESS_ID;
+
+import { ok, type Result } from '@forgeax/engine-types';
+import type { RenderError } from '../errors/render';
+import type { RenderFeaturePlan } from './plan';
+import type { RenderFeature, RenderFeatureExtractContext, RenderFeaturePlanContext } from './types';
+
+/**
+ * The coordinate function is exported beside the production shader so a real
+ * f32 device probe can compile exactly the same implementation.  Keeping the
+ * probe source here avoids a second test-only equation that could drift from
+ * the Standard pass.
+ */
+export const BARREL_DISTORTION_WGSL_COORDINATE = /* wgsl */ `
+struct BarrelDistortionParams {
+  strength : f32,
+  centerX : f32,
+  centerY : f32,
+  radiusSquared : f32,
+};
+
+fn barrel_distortion_display_to_scene_uv(
+  inputUv : vec2<f32>,
+  params : BarrelDistortionParams,
+  dimensions : vec2<f32>,
+) -> vec2<f32> {
+  let aspect = dimensions.x / max(dimensions.y, 1.0);
+  let p = vec2<f32>(
+    2.0 * aspect * (inputUv.x - params.centerX),
+    2.0 * (inputUv.y - params.centerY),
+  );
+  let t = dot(p, p) / max(params.radiusSquared, 1e-6);
+  let scale = (1.0 - params.strength) / (1.0 - params.strength * t);
+  return clamp(
+    vec2<f32>(
+      params.centerX + (inputUv.x - params.centerX) * scale,
+      params.centerY + (inputUv.y - params.centerY) * scale,
+    ),
+    vec2<f32>(0.0),
+    vec2<f32>(1.0),
+  );
+}
+`;
+
+/**
+ * Manifest-equivalent WGSL for the bounded analytic model.  The Standard
+ * owner registers this source once and keeps the graph, encoder, and submit
+ * lifecycle shared with every other fullscreen stage.
+ */
+export const BARREL_DISTORTION_WGSL = /* wgsl */ `${BARREL_DISTORTION_WGSL_COORDINATE}
+struct FullscreenOutput {
+  @builtin(position) position : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+};
+
+fn fullscreen_triangle(vertex_index : u32) -> FullscreenOutput {
+  var x : f32 = -1.0;
+  var y : f32 = -1.0;
+  if (vertex_index == 1u) { x = 3.0; }
+  if (vertex_index == 2u) { y = 3.0; }
+  let u : f32 = (x + 1.0) * 0.5;
+  let v : f32 = 1.0 - (y + 1.0) * 0.5;
+  var out : FullscreenOutput;
+  out.position = vec4<f32>(x, y, 0.0, 1.0);
+  out.uv = vec2<f32>(u, v);
+  return out;
+}
+
+@group(1) @binding(0) var sceneColor : texture_2d<f32>;
+@group(1) @binding(1) var sceneSampler : sampler;
+
+@group(1) @binding(2) var<uniform> params : BarrelDistortionParams;
+
+@vertex
+fn vs_main(@builtin(vertex_index) vertex_index : u32) -> FullscreenOutput {
+  return fullscreen_triangle(vertex_index);
+}
+
+@fragment
+fn fs_main(input : FullscreenOutput) -> @location(0) vec4<f32> {
+  let dimensions = vec2<f32>(textureDimensions(sceneColor));
+  let sampleUv = barrel_distortion_display_to_scene_uv(input.uv, params, dimensions);
+  return textureSampleLevel(sceneColor, sceneSampler, sampleUv, 0.0);
+}
+`;
+
+/**
+ * Ordinary feature registration for the Standard linear-LDR stage.
+ * Standard still allocates the stage targets and chooses its position in the
+ * post chain; this feature owns the executable fullscreen declaration that is
+ * projected into that slot by the existing graph/encoder/submit path.
+ */
+export interface BarrelDistortionFeatureFrame {
+  /** True only when the extracted camera requires a spatial warp this frame. */
+  readonly active: boolean;
+}
+
+export function createBarrelDistortionRenderFeature(): RenderFeature<BarrelDistortionFeatureFrame> {
+  return Object.freeze({
+    identity: BARREL_DISTORTION_FEATURE_IDENTITY,
+    requiredCapabilities: ['rgba16floatRenderable'] as const,
+    requiredFullscreenPostProcesses: [
+      { identity: BARREL_DISTORTION_POST_PROCESS_ID, source: BARREL_DISTORTION_WGSL },
+    ],
+    extract: (
+      context: RenderFeatureExtractContext,
+    ): Result<BarrelDistortionFeatureFrame, RenderError> =>
+      ok({ active: (context.selectedCamera?.barrelDistortion?.strength ?? 0) > 0 }),
+    plan: (
+      data: BarrelDistortionFeatureFrame,
+      _context: RenderFeaturePlanContext,
+    ): Result<RenderFeaturePlan, RenderError> =>
+      ok({
+        resources: data.active
+          ? [
+              {
+                kind: 'fullscreen-program' as const,
+                name: BARREL_DISTORTION_POST_PROCESS_ID,
+                source: BARREL_DISTORTION_WGSL,
+                reads: ['ldrColor'],
+                params: { byteSize: 16, defaultValue: new Uint8Array(16) },
+              },
+              {
+                kind: 'graphics-program' as const,
+                name: 'barrel-distortion-pipeline',
+                program: {
+                  shader: BARREL_DISTORTION_POST_PROCESS_ID,
+                  vertexLayout: 'none',
+                  colorFormats: ['rgba16float'],
+                  sampleCount: 1,
+                },
+              },
+              {
+                kind: 'graphics-bindings' as const,
+                name: 'barrel-distortion-bindings',
+                program: 'barrel-distortion-pipeline',
+                values: {
+                  group: 1,
+                  fullscreen: true,
+                  shader: BARREL_DISTORTION_POST_PROCESS_ID,
+                  input: 'barrel-input',
+                },
+                logicalTargets: { input: 'barrel-input' },
+              },
+            ]
+          : [],
+        passes: data.active
+          ? [
+              {
+                kind: 'raster' as const,
+                name: 'barrel-distortion',
+                colorAttachments: [
+                  { target: 'barrel-output', loadOp: 'clear' as const, storeOp: 'store' as const },
+                ],
+                sampledTargets: ['barrel-input'],
+                draws: [
+                  {
+                    program: 'barrel-distortion-pipeline',
+                    bindings: ['barrel-distortion-bindings'],
+                    vertexData: [],
+                    vertexLayout: 'none' as const,
+                    draw: { kind: 'draw' as const, vertexCount: 3, instanceCount: 1 },
+                  },
+                ],
+              },
+            ]
+          : [],
+      }),
+  });
+}

package/src/features/error-reporting.ts

@@ -8,22 +8,33 @@ import type { RenderError } from '../errors/render';
  */
 export const PENDING_RENDER_FEATURE_ERROR_REPORT_INTERVAL_FRAMES = 60;
 
+export interface PendingRenderFeatureErrorReport {
+  readonly frame: number;
+  readonly fingerprint: string;
+}
+
 export function shouldReportPendingRenderFeatureError(
-  lastReportedFrame: Map<string, number>,
+  lastReportedFrame: Map<string, PendingRenderFeatureErrorReport>,
   key: string,
   frameNumber: number,
+  fingerprint = '',
   intervalFrames = PENDING_RENDER_FEATURE_ERROR_REPORT_INTERVAL_FRAMES,
 ): boolean {
   const lastReported = lastReportedFrame.get(key);
-  if (lastReported !== undefined && frameNumber - lastReported < intervalFrames) return false;
-  lastReportedFrame.set(key, frameNumber);
+  if (
+    lastReported !== undefined &&
+    lastReported.fingerprint === fingerprint &&
+    frameNumber - lastReported.frame < intervalFrames
+  )
+    return false;
+  lastReportedFrame.set(key, { frame: frameNumber, fingerprint });
   return true;
 }
 
 export function reportPendingRenderFeatureErrors(
   errors: readonly RenderError[],
   frameNumber: number,
-  lastReportedFrame: Map<string, number>,
+  lastReportedFrame: Map<string, PendingRenderFeatureErrorReport>,
   errorRegistry: { fire(error: RenderError): void },
 ): void {
   for (const error of errors) {
@@ -36,7 +47,16 @@ export function reportPendingRenderFeatureErrors(
     // failures still receive first/periodic reporting.
     if (isSilentRenderFeatureWarmup(error)) continue;
     const key = pendingRenderFeatureErrorKey(error);
-    if (shouldReportPendingRenderFeatureError(lastReportedFrame, key, frameNumber)) {
+    const cause = error.code === 'render-feature-stage-failed' ? error.detail.cause : undefined;
+    const causeText =
+      cause instanceof Error
+        ? `${cause.name}\0${cause.message}`
+        : typeof cause === 'string'
+          ? cause
+          : '';
+    const fingerprint = `${error.expected}\0${error.hint}\0${causeText}`;
+    // Retain one record per owner, not one record per changing cause string.
+    if (shouldReportPendingRenderFeatureError(lastReportedFrame, key, frameNumber, fingerprint)) {
       errorRegistry.fire(error);
     }
   }
@@ -74,5 +94,5 @@ function pendingRenderFeatureErrorKey(error: RenderError): string {
     detail !== undefined && 'order' in detail && typeof detail.order === 'number'
       ? detail.order
       : -1;
-  return `${error.code}\0${featureIdentity}\0${order}\0${error.expected}\0${error.hint}`;
+  return `${error.code}\0${featureIdentity}\0${order}`;
 }

package/src/features/host.ts

@@ -17,6 +17,7 @@ import type {
   PreparedGraphicsResolver,
   PreparedGraphicsResourceLease,
 } from '../prepare/prepared-graphics-resolver';
+import type { CameraSnapshot } from '../render-contract';
 import { isSceneDataTarget, type SceneDataTarget } from '../temporal/scene-data';
 import { createSceneDataCatalog, type SceneDataCatalog } from '../temporal/scene-data-catalog';
 import {
@@ -114,6 +115,7 @@ export interface RenderFeaturePlanExecutionPass {
 export interface RenderFeaturePlanExecution {
   readonly featureIdentity: string;
   readonly order: number;
+  readonly placement?: import('./types').RenderFeaturePlacement;
   readonly passes: readonly RenderFeaturePlanExecutionPass[];
 }
 
@@ -134,6 +136,8 @@ export interface RenderFeatureFrameInput {
   readonly worlds: readonly import('@forgeax/engine-ecs').World[];
   readonly owner: number;
   readonly frameNumber: number;
+  /** Renderer-selected display camera forwarded to feature extraction. */
+  readonly selectedCamera?: CameraSnapshot;
   /** Physical render extent for bounded feature dispatch sizing. */
   readonly frameSize?: { readonly width: number; readonly height: number };
   readonly visibilitySnapshots?: readonly RenderFeatureWorldVisibilitySnapshot[];
@@ -144,6 +148,8 @@ export interface RenderFeatureFrameInput {
   readonly sceneData?: SceneDataCatalog;
   readonly generation?: number;
   readonly caps: Readonly<RhiCaps>;
+  /** Normal frame-owner facts shared with producer extraction. */
+  readonly frame?: import('./types').RenderFeatureFrameContext;
   /** Renderer-owned material binding contract projection for producer plans. */
   readonly materialShaderBindingContract?: (
     materialShaderId: string,
@@ -175,6 +181,8 @@ export interface RenderFeatureFrameResult {
   readonly errors: readonly RenderError[];
   readonly plans: readonly RenderFeaturePlannedFrame[];
   readonly fullscreenEffects: ReadonlyMap<string, PostProcessShaderEntry>;
+  /** Public Standard post-effect identities; graph-local fullscreen resources are not included. */
+  readonly postProcessIdentities: readonly string[];
   readonly preparedResourceBatches: readonly RenderFeaturePreparedResourceBatch[];
   /**
    * True only when the current graph resolves a transient graphics lease.
@@ -223,6 +231,8 @@ export interface RenderFeatureHost {
   recover(input: RenderFeatureRecoverInput): Result<void, RenderError>;
   createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown>;
   diagnostics(): readonly RenderFeatureDiagnostics[];
+  /** Retain an explicitly producer-published detached inspection value. */
+  setInspection(identity: string, inspection: unknown): void;
   /** Subscribe to lifecycle projection changes; unchanged active frames are silent. */
   subscribeDiagnostics(listener: () => void): () => void;
   /** Detached signature and prepared-resource accounting for diagnostics. */
@@ -269,6 +279,7 @@ interface FeatureSlot {
   readonly preparedStore: PreparedGraphicsStore;
   status: RenderFeatureStatus;
   latestError: RenderFeatureErrorDescriptor | undefined;
+  latestInspection?: unknown;
 }
 
 function freezeError(error: RenderFeatureErrorDescriptor): RenderFeatureErrorDescriptor {
@@ -291,6 +302,7 @@ function freezeDiagnostics(slot: FeatureSlot): RenderFeatureDiagnostics {
     order: slot.order,
     status: slot.status,
     latestError: slot.latestError === undefined ? undefined : freezeError(slot.latestError),
+    ...(slot.latestInspection === undefined ? {} : { inspection: slot.latestInspection }),
   });
 }
 
@@ -320,6 +332,16 @@ function missingCapability(
   return feature.requiredCapabilities?.find((capability) => caps[capability] !== true);
 }
 
+/**
+ * Capability declarations gate work that the current plan actually admits.
+ * A producer is still allowed to extract and return an empty plan when its
+ * authored feature is disabled; that path must remain allocation-free on a
+ * backend which cannot support the optional feature.
+ */
+function hasActivePlan(plan: RenderFeaturePlan): boolean {
+  return plan.resources.length > 0 || plan.passes.length > 0;
+}
+
 function createPreparedGraphicsPrepare(
   transaction: PreparedGraphicsTransaction,
 ): RenderFeatureGraphicsPrepare {
@@ -346,6 +368,9 @@ function resolveGraphicsSnapshot(
   resolver: PreparedGraphicsResolver,
   descriptor: import('./prepared-graphics').RenderFeatureGraphicsPassDescriptor,
   generation: number,
+  resolveGpuResource?: (
+    name: string,
+  ) => import('./prepared-gpu-work').RenderFeatureResolvedGpuBuffer | undefined,
 ): Result<PreparedGraphicsResolvedSnapshot, RenderError> {
   const resources = new Map<
     object,
@@ -364,6 +389,7 @@ function resolveGraphicsSnapshot(
     ...(resolver.resolveGpuBuffer === undefined
       ? {}
       : { resolveGpuBuffer: resolver.resolveGpuBuffer }),
+    ...(resolveGpuResource === undefined ? {} : { resolveGpuResource }),
   });
 }
 
@@ -971,6 +997,7 @@ function projectPlanPasses(
   return ok({
     featureIdentity: slot.feature.identity,
     order: slot.order,
+    ...(slot.feature.placement === undefined ? {} : { placement: slot.feature.placement }),
     passes: Object.freeze(projected),
   });
 }
@@ -1330,6 +1357,13 @@ class FeatureHostImpl implements RenderFeatureHost {
     return Object.freeze(this.slots.map(freezeDiagnostics));
   }
 
+  /** Retain only an explicitly producer-published detached inspection value. */
+  setInspection(identity: string, inspection: unknown): void {
+    const slot = findSlot(this.slots, identity);
+    if (slot === undefined || slot.status === 'disposed') return;
+    slot.latestInspection = inspection;
+  }
+
   subscribeDiagnostics(listener: () => void): () => void {
     this.diagnosticsListeners.add(listener);
     return () => this.diagnosticsListeners.delete(listener);
@@ -1360,6 +1394,7 @@ export function runRenderFeatureFrame(
   const errors: RenderError[] = [];
   const plans: RenderFeaturePlannedFrame[] = [];
   const fullscreenEffects = new Map<string, PostProcessShaderEntry>();
+  const postProcessIdentities = new Set<string>();
   const preparedResourceBatches: RenderFeaturePreparedResourceBatch[] = [];
   let requiresPreparedResourceKey = false;
   const hiddenEntityReports: RenderFeatureHiddenEntityReport[] = [
@@ -1370,17 +1405,18 @@ export function runRenderFeatureFrame(
   const diagnostics = host.diagnostics();
   for (const [order, feature] of host.features.entries()) {
     const diagnostic = diagnostics[order];
-    if (diagnostic?.status === 'disabled' || diagnostic?.status === 'disposed') continue;
-    const missing = missingCapability(feature, input.caps);
-    if (missing !== undefined) {
-      const capabilityError = new RenderFeatureCapabilityMissingError(
-        feature.identity,
-        order,
-        missing,
-      );
-      errors.push(capabilityError);
-      host.setStatus(feature.identity, 'disabled', errorDescriptor(capabilityError));
-      continue;
+    if (diagnostic?.status === 'disposed') continue;
+    // Preserve the existing recovery contract for a capability-disabled
+    // feature once the device becomes capable: an explicit host.recover()
+    // still re-admits it. While the capability is absent, however, rerun the
+    // producer so a camera/world can disable its authored plan and recover to
+    // an empty, zero-resource frame without a second manager.
+    if (diagnostic?.status === 'disabled') {
+      const diagnosticError = diagnostic.latestError;
+      const missing = missingCapability(feature, input.caps);
+      if (diagnosticError?.code !== 'render-feature-capability-missing' || missing === undefined) {
+        continue;
+      }
     }
     const slot: FeatureSlot = {
       feature,
@@ -1391,6 +1427,9 @@ export function runRenderFeatureFrame(
       latestError: undefined,
     };
     const identity = slot.feature.identity;
+    for (const postProcess of feature.requiredFullscreenPostProcesses ?? []) {
+      postProcessIdentities.add(postProcess.identity);
+    }
     const transaction = host.beginPreparedFrame(identity, input.generation ?? 0);
     if (transaction === undefined) continue;
     const graphics = createPreparedGraphicsPrepare(transaction);
@@ -1404,6 +1443,9 @@ export function runRenderFeatureFrame(
       worlds: input.worlds,
       owner: input.owner,
       frameNumber: input.frameNumber,
+      ...(input.selectedCamera === undefined ? {} : { selectedCamera: input.selectedCamera }),
+      caps: input.caps,
+      ...(input.frame === undefined ? {} : { frame: input.frame }),
       reportHiddenEntity: (report) => featureHiddenEntityReports.push(report),
       ...(input.visibilitySnapshots === undefined
         ? {}
@@ -1421,6 +1463,16 @@ export function runRenderFeatureFrame(
       host.setStatus(identity, 'failed', slot.latestError);
       continue;
     }
+    if (
+      typeof extracted.value === 'object' &&
+      extracted.value !== null &&
+      'inspection' in extracted.value
+    ) {
+      host.setInspection(
+        identity,
+        (extracted.value as { readonly inspection?: unknown }).inspection,
+      );
+    }
 
     const targets = logicalTargets(input.targets ?? []);
     const sceneData =
@@ -1466,21 +1518,43 @@ export function runRenderFeatureFrame(
       host.setStatus(identity, 'failed', slot.latestError);
       continue;
     }
+    const missing = missingCapability(feature, input.caps);
+    if (missing !== undefined && hasActivePlan(frozen.value)) {
+      const capabilityError = new RenderFeatureCapabilityMissingError(identity, order, missing);
+      errors.push(capabilityError);
+      transaction.abort();
+      host.setStatus(identity, 'disabled', errorDescriptor(capabilityError));
+      continue;
+    }
     const plannedFrame: RenderFeaturePlannedFrame = Object.freeze({
       featureIdentity: identity,
       generation: transaction.generation,
       signature:
         host.recordPlanSignature?.(identity, frozen.value) ??
         renderFeaturePlanSignature(frozen.value),
+      ...(feature.placement === undefined ? {} : { placement: feature.placement }),
       plan: frozen.value,
     });
     for (const resource of frozen.value.resources) {
       if (resource.kind !== 'fullscreen-program') continue;
-      fullscreenEffects.set(identity, {
+      const entry = {
         source: resource.source,
+        ...(resource.fragmentEntryPoint === undefined
+          ? {}
+          : { fragmentEntryPoint: resource.fragmentEntryPoint }),
         ...(resource.reads === undefined ? {} : { reads: resource.reads }),
+        ...(resource.usesView === undefined ? {} : { usesView: resource.usesView }),
+        ...(resource.storageBindings === undefined
+          ? {}
+          : { storageBindings: resource.storageBindings }),
         ...(resource.params === undefined ? {} : { params: resource.params }),
-      });
+      } satisfies PostProcessShaderEntry;
+      // A feature may expose more than one graph-local fullscreen producer
+      // (the cloud display composite and its shadow map). Keep each resource
+      // addressable by its declared name and retain the feature identity alias
+      // for the original public post-process route.
+      fullscreenEffects.set(resource.name, entry);
+      if (!fullscreenEffects.has(identity)) fullscreenEffects.set(identity, entry);
     }
     const prepared = preparePlanResources(slot, frozen.value, graphics, gpu, input.targets ?? []);
     if (!prepared.ok) {
@@ -1512,7 +1586,33 @@ export function runRenderFeatureFrame(
         : (descriptor: import('./prepared-graphics').RenderFeatureGraphicsPassDescriptor) => {
             // A pending pass can be skipped while earlier passes remain usable.
             // Keep their shared resolver leases alive until submission retires them.
-            return resolveGraphicsSnapshot(resolver, descriptor, transaction.generation);
+            const resolveGpuResource = (name: string) => {
+              const owned = prepared.value.buffers.get(name);
+              const borrowed = prepared.value.preparedGpuResources.get(name);
+              const reference =
+                owned ?? (borrowed?.kind === 'buffer' ? borrowed.reference : undefined);
+              return reference === undefined ? undefined : gpu?.resolveBuffer(reference);
+            };
+            const resolved = resolveGraphicsSnapshot(
+              resolver,
+              descriptor,
+              transaction.generation,
+              resolveGpuResource,
+            );
+            // A pending pipeline is a retryable partial frame. The resolver
+            // leases cover resources used by earlier ready passes and must
+            // stay retained until the submitted batch retires; only terminal
+            // resolution failures release them here.
+            if (
+              !resolved.ok &&
+              !(
+                resolved.error instanceof RenderFeaturePreparationFailedError &&
+                resolved.error.detail.reason === 'pipeline-pending'
+              )
+            ) {
+              resolver.release();
+            }
+            return resolved;
           };
     const releaseResolver = (): void => {
       if (resolver !== undefined) resolver.release();
@@ -1577,6 +1677,7 @@ export function runRenderFeatureFrame(
     errors,
     plans,
     fullscreenEffects,
+    postProcessIdentities: Object.freeze([...postProcessIdentities]),
     preparedResourceBatches,
     requiresPreparedResourceKey,
     hiddenEntityReports: mergeHiddenEntityReports(hiddenEntityReports),

package/src/features/plan.ts

@@ -51,7 +51,13 @@ export interface RenderFeatureFullscreenProgramDeclaration {
   readonly kind: 'fullscreen-program';
   readonly name: string;
   readonly source: string;
+  /** Optional fragment entry point when one WGSL module owns multiple passes. */
+  readonly fragmentEntryPoint?: string;
   readonly reads?: readonly RenderFeatureFullscreenRead[];
+  /** Bind the renderer-owned View group at group(0) for camera reconstruction. */
+  readonly usesView?: boolean;
+  /** Read-only storage buffers appended after the regular color/depth reads. */
+  readonly storageBindings?: readonly number[];
   readonly params?: {
     readonly byteSize: number;
     readonly defaultValue: Uint8Array;
@@ -275,6 +281,8 @@ export interface RenderFeaturePlannedFrame {
   readonly generation: number;
   readonly signature: string;
   readonly plan: RenderFeaturePlan;
+  /** Placement selected by the installed feature; omitted means the legacy post stage. */
+  readonly placement?: import('./types').RenderFeaturePlacement;
 }
 
 export interface RenderFeatureDerivedAccess {