@forgeax/engine-render 0.1.33 → 0.1.35

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[];
 }
 
@@ -131,9 +133,13 @@ export interface RenderFeatureStageEvent {
 }
 
 export interface RenderFeatureFrameInput {
+  readonly publishedFeatures?: readonly { readonly identity: string; readonly data: unknown }[];
+  readonly onFeatureSourceSubmitted?: (identity: string, feedback: unknown) => void;
   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 +150,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 +183,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 +233,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 +281,7 @@ interface FeatureSlot {
   readonly preparedStore: PreparedGraphicsStore;
   status: RenderFeatureStatus;
   latestError: RenderFeatureErrorDescriptor | undefined;
+  latestInspection?: unknown;
 }
 
 function freezeError(error: RenderFeatureErrorDescriptor): RenderFeatureErrorDescriptor {
@@ -291,6 +304,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 +334,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 +370,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 +391,7 @@ function resolveGraphicsSnapshot(
     ...(resolver.resolveGpuBuffer === undefined
       ? {}
       : { resolveGpuBuffer: resolver.resolveGpuBuffer }),
+    ...(resolveGpuResource === undefined ? {} : { resolveGpuResource }),
   });
 }
 
@@ -971,6 +999,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 +1359,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 +1396,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 +1407,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 +1429,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 +1445,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
         ? {}
@@ -1412,7 +1456,10 @@ export function runRenderFeatureFrame(
     const extracted = invokeStage(
       slot,
       'extract',
-      () => slot.feature.extract(extractContext),
+      () => {
+        const published = input.publishedFeatures?.find((row) => row.identity === identity);
+        return published === undefined ? slot.feature.extract(extractContext) : ok(published.data);
+      },
       stageEvents,
       errors,
     );
@@ -1421,6 +1468,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 +1523,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 +1591,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();
@@ -1555,11 +1660,14 @@ export function runRenderFeatureFrame(
       continue;
     }
     planExecutionProjections.set(plannedFrame, projected.value);
-    if (feature.onFrameSubmitted !== undefined) {
+    if (feature.onFrameSubmitted !== undefined || feature.onSourceFrameSubmitted !== undefined) {
       submissionSensitivePlans.add(plannedFrame);
-      submissionAcknowledgments.set(plannedFrame, () =>
-        feature.onFrameSubmitted?.(extracted.value, projected.value),
-      );
+      submissionAcknowledgments.set(plannedFrame, () => {
+        feature.onFrameSubmitted?.(extracted.value, projected.value);
+        if (input.publishedFeatures?.some((row) => row.identity === identity))
+          input.onFeatureSourceSubmitted?.(identity, declared.value.sourceFeedback);
+        else feature.onSourceFrameSubmitted?.(extracted.value, declared.value.sourceFeedback);
+      });
     }
     plans.push(plannedFrame);
     if (feature.onFrameAborted !== undefined) {
@@ -1577,6 +1685,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;
@@ -231,6 +237,8 @@ export type RenderFeaturePassDeclaration =
  * access is derived from these roles rather than duplicated as reads/writes.
  */
 export interface RenderFeaturePlan {
+  /** Source acknowledgment facts; never part of GPU resource or graph identity. */
+  readonly sourceFeedback?: unknown;
   readonly resources: readonly RenderFeatureResourceDeclaration[];
   readonly passes: readonly RenderFeaturePassDeclaration[];
 }
@@ -275,6 +283,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 {

package/src/features/render-graph-contribution.ts

@@ -19,6 +19,7 @@ import {
   resolveRenderFeatureDrawBuffers,
 } from './render-graph-raster';
 import { createRenderFeatureGraphBufferState } from './render-graph-resources';
+import type { RenderFeaturePlacement } from './types';
 
 export function createRenderFeatureProjectionState() {
   return {
@@ -141,6 +142,10 @@ export function projectRenderFeaturePlans<FrameCtx extends RenderGraphFrame>(
     readonly reportError?: ((error: RenderError) => void) | undefined;
     readonly resolveStandardLighting?: RenderFeatureLightingResolver<FrameCtx> | undefined;
     readonly standardSurfaceAccesses?: readonly GraphAccess[] | undefined;
+    /** Restrict projection to one Standard graph placement. */
+    readonly placement?: RenderFeaturePlacement | undefined;
+    /** Restrict projection to the named passes for a multi-stage feature. */
+    readonly passNames?: ReadonlySet<string> | undefined;
     readonly state?: ReturnType<typeof createRenderFeatureProjectionState>;
   },
 ): Result<void, RenderGraphError | RenderError> {
@@ -162,7 +167,11 @@ export function projectRenderFeaturePlans<FrameCtx extends RenderGraphFrame>(
     options.standardSurfaceAccesses,
   );
   for (const execution of executions) {
+    if (options.placement !== undefined && (execution.placement ?? 'post') !== options.placement) {
+      continue;
+    }
     for (const pass of execution.passes) {
+      if (options.passNames !== undefined && !options.passNames.has(pass.name)) continue;
       if (state.projected.has(pass)) continue;
       if (pass.shadowCaster)
         return err(

package/src/features/render-graph-raster.ts

@@ -57,6 +57,7 @@ export type RenderFeatureGraphBindingsResolver<FrameCtx extends RenderGraphFrame
   readonly binding: Extract<PreparedGraphicsResolvedResource, { readonly kind: 'bindings' }>;
   readonly resources: GraphResourceResolver;
   readonly resolveTarget: RenderFeatureGraphTargetResolver;
+  readonly resolveGpuResource?: (name: string) => RenderFeatureResolvedGpuBuffer | undefined;
 }) => RenderFeatureGraphBindingsResolution | undefined;
 
 export type RenderFeatureLightingResolver<FrameCtx extends RenderGraphFrame> = (
@@ -275,6 +276,32 @@ export class RenderFeatureRasterGraphProjection<FrameCtx extends RenderGraphFram
       accesses.push({ resource: handle, usage: 'indirect-read' } as const);
     }
 
+    // Feature-owned fullscreen/material bind groups may carry a read-only
+    // storage buffer (for example the bounded procedural cloud cache). Import
+    // it into the same graph so the compute producer is ordered before the
+    // raster consumer and the buffer lease follows queue retirement.
+    for (const draw of descriptor.draws) {
+      for (const reference of draw.bindings) {
+        const binding = resolved(snapshot, reference);
+        const names =
+          binding?.kind === 'bindings' ? binding.descriptor?.values.storageBuffers : undefined;
+        if (!Array.isArray(names)) continue;
+        for (const name of names) {
+          if (typeof name !== 'string') continue;
+          const physical = snapshot.resolveGpuResource?.(name);
+          if (physical === undefined) continue;
+          const imported = importRenderFeatureGraphBuffer(
+            this.builder,
+            this.buffers,
+            `${name}.${featureIdentity}.${order}`,
+            physical,
+          );
+          if (!imported.ok) return imported;
+          accesses.push({ resource: imported.value, usage: 'storage-read' } as const);
+        }
+      }
+    }
+
     return this.builder.addRasterPass(name, {
       accesses,
       colorAttachments: colors,
@@ -377,9 +404,24 @@ export class RenderFeatureRasterGraphProjection<FrameCtx extends RenderGraphFram
           pass.setBindGroup(0, shadowView, [0, 0]);
           continue;
         }
-        const resolvedBindings =
-          binding.handle ??
-          this.resolveBindings?.({ frame, binding, resources, resolveTarget: this.resolveTarget });
+        // Fullscreen feature bindings contain graph-owned texture views and a
+        // per-frame params UBO. Resolve them at execution time so a retained
+        // graph still follows the current post-process input and authored
+        // parameters; material/view bindings remain safely cached.
+        const resolvedBindings = (() => {
+          const resolve = () =>
+            this.resolveBindings?.({
+              frame,
+              binding,
+              resources,
+              resolveTarget: this.resolveTarget,
+              ...(snapshot.resolveGpuResource === undefined
+                ? {}
+                : { resolveGpuResource: snapshot.resolveGpuResource }),
+            });
+          if (binding.descriptor?.values.fullscreen === true) return resolve();
+          return binding.handle ?? resolve();
+        })();
         const handle =
           resolvedBindings !== undefined &&
           typeof resolvedBindings === 'object' &&

package/src/features/targets.ts

@@ -55,6 +55,8 @@ export function resolveStandardRenderFeatureTargets(input: {
   readonly storageBuffer: boolean;
   readonly multisample: boolean;
   readonly colorAttachmentFormat: TextureFormat;
+  /** Expose cloud history aliases only while a CloudLayer is authored. */
+  readonly cloudHistory?: boolean;
 }): readonly RenderFeatureTargetHandle[] {
   const sampleCount: 1 | 4 = input.antialias === 'msaa' && input.multisample ? 4 : 1;
   // Standard always exposes the scene to features as a linear float target;
@@ -91,5 +93,69 @@ export function resolveStandardRenderFeatureTargets(input: {
       format: colorFormat,
       sampleCount: 1,
     }),
+    // A graph-owned, single-sample map produced before direct-solar lighting.
+    // The logical handle lets the feature plan validate its producer before
+    // the Standard pipeline allocates the concrete texture.
+    createRenderFeatureTarget({
+      name: 'cloud-shadow',
+      kind: 'scene-color',
+      format: 'rgba16float',
+      sampleCount: 1,
+    }),
+    // These are declarative aliases only. Standard allocates the actual
+    // linear-LDR ping-pong target at the ordered post stage and resolves these
+    // names through `contributeFeatures` when that stage is reached.
+    createRenderFeatureTarget({
+      name: 'barrel-input',
+      kind: 'scene-color',
+      format: 'rgba16float',
+      sampleCount: 1,
+    }),
+    createRenderFeatureTarget({
+      name: 'barrel-output',
+      kind: 'scene-color',
+      format: 'rgba16float',
+      sampleCount: 1,
+    }),
+    ...(input.cloudHistory === true
+      ? [
+          createRenderFeatureTarget({
+            name: 'cloud-history-radiance-previous',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+          createRenderFeatureTarget({
+            name: 'cloud-history-radiance-current',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+          createRenderFeatureTarget({
+            name: 'cloud-history-transmittance-previous',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+          createRenderFeatureTarget({
+            name: 'cloud-history-transmittance-current',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+          createRenderFeatureTarget({
+            name: 'cloud-history-depth-previous',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+          createRenderFeatureTarget({
+            name: 'cloud-history-depth-current',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+        ]
+      : []),
   ];
 }

package/src/features/types.ts

@@ -4,6 +4,7 @@ import type { RhiCaps } from '@forgeax/engine-rhi';
 import type { Result } from '@forgeax/engine-types';
 import type { RenderError, RenderFeatureErrorDescriptor } from '../errors/render';
 import type { VisibilitySnapshot } from '../extract/visibility';
+import type { CameraSnapshot } from '../render-contract';
 import type { RenderFeaturePlan, RenderFeaturePlanContext } from './plan';
 import type { RenderFeatureCapabilityKey } from './vocabulary';
 
@@ -42,6 +43,17 @@ export type {
 /** Closed lifecycle states exposed by the feature host. */
 export type RenderFeatureStatus = 'active' | 'failed' | 'disabled' | 'disposed';
 
+/**
+ * Graph placement for a producer-owned feature.
+ *
+ * `scene` is admitted after the opaque scene and before transmission,
+ * ordinary transparency, and volumetric composition. `post` is admitted at
+ * the existing post-TAA extension point. Keeping this as one closed value
+ * lets the Standard owner place atmospheric transport without adding a
+ * second renderer or a feature-specific side channel.
+ */
+export type RenderFeaturePlacement = 'scene' | 'post';
+
 /**
  * Shader preparation policy for feature-owned GPU programs.
  *
@@ -63,6 +75,27 @@ export interface RenderFeatureWorldVisibilitySnapshot {
   readonly snapshot: VisibilitySnapshot;
 }
 
+/** Renderer-owned view facts shared by feature extraction and temporal owners. */
+export interface RenderFeatureViewContext {
+  readonly identity: string;
+  readonly width: number;
+  readonly height: number;
+  readonly cameraRevision: number;
+  readonly deviceGeneration: number;
+  readonly cameraPosition: readonly [number, number, number];
+  /** Stable world anchor for light-space cloud coverage (never screen-space). */
+  readonly shadowAnchor?: readonly [number, number, number];
+  readonly cameraCut?: boolean;
+  readonly recovery?: boolean;
+  readonly sceneDepthVersion?: number;
+}
+
+/** Normal frame projection consumed by feature owners at extract time. */
+export interface RenderFeatureFrameContext {
+  readonly cloudLayer?: import('../cloud/extract').ExtractedCloudLayer;
+  readonly view?: RenderFeatureViewContext;
+}
+
 /** A producer's structured report for one hidden render candidate. */
 export interface RenderFeatureHiddenEntityReport {
   readonly world: World;
@@ -73,6 +106,16 @@ export interface RenderFeatureExtractContext {
   readonly worlds: readonly World[];
   readonly owner: number;
   readonly frameNumber: number;
+  /**
+   * Renderer-selected display camera for this frame. Features that affect the
+   * display must derive their active plan from this snapshot instead of
+   * scanning every Camera in the composed worlds.
+   */
+  readonly selectedCamera?: CameraSnapshot;
+  /** Renderer capability facts for source extraction and inspect projections. */
+  readonly caps?: Readonly<RhiCaps>;
+  /** Normal frame-owner projection; feature code must consume this snapshot. */
+  readonly frame?: RenderFeatureFrameContext;
   /** Same-batch World snapshots; absent for synthetic direct feature probes. */
   readonly visibilitySnapshots?: readonly RenderFeatureWorldVisibilitySnapshot[];
   /** Host-owned report sink; feature code never owns the merged diagnostic. */
@@ -106,6 +149,8 @@ export interface RenderFeatureSubmission {
  */
 export interface RenderFeature<FrameData> {
   readonly identity: string;
+  /** Optional graph placement; omitted features retain the historical post stage. */
+  readonly placement?: RenderFeaturePlacement;
   readonly requiredCapabilities?: readonly RenderFeatureCapabilityKey[];
   /** Optional feature-owned shader preparation policy; defaults to `validated`. */
   readonly shaderModuleMode?: RenderFeatureShaderModuleMode;
@@ -126,6 +171,8 @@ export interface RenderFeature<FrameData> {
     readonly source: string;
   }[];
   extract(context: RenderFeatureExtractContext): Result<FrameData, RenderError>;
+  /** GUID roots needed by the declarative plan; the publisher carries their asset closure. */
+  assetDependencies?(data: FrameData): readonly string[];
   plan(data: FrameData, context: RenderFeaturePlanContext): Result<RenderFeaturePlan, RenderError>;
   /**
    * Consume frame-owned producer state only after the compiled graph reached
@@ -133,6 +180,8 @@ export interface RenderFeature<FrameData> {
    * extracted frame and never during declarative planning.
    */
   onFrameSubmitted?(data: FrameData, submission?: RenderFeatureSubmission): void;
+  /** Consume source-owned intents after submission; feedback must be structured-cloneable. */
+  onSourceFrameSubmitted?(data: FrameData, feedback: unknown): void;
   /**
    * Discard frame-owned producer state when graph admission or submission is
    * rejected.  This is the symmetric recovery path for onFrameSubmitted.
@@ -151,4 +200,6 @@ export interface RenderFeatureDiagnostics {
   readonly order: number;
   readonly status: RenderFeatureStatus;
   readonly latestError: RenderFeatureErrorDescriptor | undefined;
+  /** Optional producer-owned detached inspection snapshot from the latest extract. */
+  readonly inspection?: unknown;
 }