@forgeax/engine-render 0.1.28 → 0.1.30

package/src/render-contract.ts

@@ -23,13 +23,16 @@ import type {
 } from '@forgeax/engine-rhi';
 import type { SkinError } from '@forgeax/engine-skinning';
 import type { ImageError } from '@forgeax/engine-types';
-import type { RhiBackendInstrumentation } from './assembly/backend-contract';
-import type { Antialias, BloomEnabled, Tonemap } from './components/camera';
-import type { EnvironmentInspection } from './environment/inspection';
-import type { RecoveryOutcome, RecoveryPhase } from './errors/recover';
-import type { RenderError } from './errors/render';
-import type { RenderFeature, RenderFeatureDiagnostics } from './features/types';
-import type { PostProcessShaderEntry } from './fullscreen-post-process-pass';
+import type { RhiBackendInstrumentation } from './assembly/backend-contract.js';
+import type { Antialias, BloomEnabled, CameraExposure, Tonemap } from './components/camera.js';
+import type { DynamicResolutionData } from './components/dynamic-resolution.js';
+import type { ScreenSpaceReflectionData } from './components/screen-space-reflection.js';
+import type { EnvironmentInspection } from './environment/inspection.js';
+import type { GpuDrivenPreparationError } from './errors/gpu-driven.js';
+import type { RecoveryOutcome, RecoveryPhase } from './errors/recover.js';
+import type { RenderError } from './errors/render.js';
+import type { RenderFeature, RenderFeatureDiagnostics } from './features/types.js';
+import type { PostProcessShaderEntry } from './fullscreen-post-process-pass.js';
 import type {
   BloomInspection,
   DirectionalShadowInspection,
@@ -37,13 +40,18 @@ import type {
   LodOcclusionInspection,
   MotionBlurInspection,
   ReflectionProbeInspection,
+  RenderFeatureGraphInspection,
+  RenderFeatureHostInspection,
   RenderSceneInspection,
   SsrDependenciesInspection,
+  SsrSpatialInspection,
   TemporalTargetInspection,
   TransmissionInspection,
-} from './inspection-types';
-import type { InstanceCollectionInspection } from './instances';
-import type { SsrAdmissionIdentity } from './ssr/identity';
+} from './inspection-types.js';
+import type { InstanceCollectionInspection, InstanceCollectionStore } from './instances.js';
+import type { RenderExtent } from './pipeline/render-extent.js';
+import type { RenderSceneBounds } from './scene/render-scene-types.js';
+import type { SsrAdmissionIdentity } from './ssr/identity.js';
 import type {
   RenderTarget,
   RenderTargetDescriptor,
@@ -52,11 +60,11 @@ import type {
   RenderTargetReadbackTicket,
   RenderTargetTextureSource,
   RenderTargetTextureSourceOptions,
-} from './targets/contracts';
-import type { TemporalInspection } from './temporal/inspection';
+} from './targets/contracts.js';
+import type { TemporalInspection } from './temporal/inspection.js';
 
-export type { TransmissionInspection } from './inspection-types';
-export type { PointsLinesInspection } from './points-lines/inspection';
+export type { TransmissionInspection } from './inspection-types.js';
+export type { PointsLinesInspection } from './points-lines/inspection.js';
 
 import type {
   DynamicGeometryCandidate,
@@ -65,27 +73,29 @@ import type {
   DynamicGeometryOrdering,
   DynamicGeometryPrepareInput,
   DynamicGeometryReceipt,
-} from './dynamic-geometry';
+} from './dynamic-geometry.js';
 import type {
   IblBindingInspection,
   MeshMaterialBindingObservation,
-} from './mesh-material-bindings';
-import type { StandardLightingInspection } from './pipeline/standard-lighting/inspection';
-import type { StandardProfile } from './pipeline/standard-profile';
-import type { PointShadowInspection } from './point-shadow-inspection';
-import type { PostProcessError } from './post-process-errors';
+} from './mesh-material-bindings.js';
+import type { StandardLightingInspection } from './pipeline/standard-lighting/inspection.js';
+import type { AutoExposureInspection } from './pipeline/standard-output/auto-exposure/inspection.js';
+import type { StandardLutInspection } from './pipeline/standard-output/lut-state.js';
+import type { StandardProfile } from './pipeline/standard-profile.js';
+import type { PointShadowInspection } from './point-shadow-inspection.js';
+import type { PostProcessError } from './post-process-errors.js';
 import type {
   GpuPassTimingObservation,
   GpuPassTimingOptions,
 } from './record/gpu-pass-timing/index.js';
-import type { VolumeTimingObservation } from './record/gpu-timing';
-import type { TemporalView } from './temporal/view';
-import type { VolumetricFogInspection } from './volume/inspection';
+import type { VolumeTimingObservation } from './record/gpu-timing.js';
+import type { TemporalView } from './temporal/view.js';
+import type { VolumetricFogInspection } from './volume/inspection.js';
 
 export type {
   CubeCameraFace,
   CubeCameraUpdateIntent,
-} from './components/cube-camera';
+} from './components/cube-camera.js';
 
 export interface CubeCameraSnapshot {
   readonly entityKey?: number;
@@ -105,6 +115,15 @@ export type RenderResult<T, E> =
 /** The only World data boundary accepted by the M6 renderer contract. */
 export type RenderWorldLease = RenderReadLease;
 
+/** Camera-owned color/exposure facts projected once at the frame boundary. */
+export interface CameraOutputSnapshot {
+  readonly exposure: CameraExposure;
+  readonly temperature: number;
+  readonly tint: number;
+  readonly colorLut: number;
+  readonly colorLutStrength: number;
+}
+
 /**
  * Camera facts shared by extract, record, and scene owners.
  *
@@ -138,12 +157,18 @@ export interface CameraSnapshot {
   readonly tonemap: Tonemap;
   readonly exposure: number;
   readonly whitePoint: number;
+  /** Camera schema output projection consumed by Standard prepare/inspection. */
+  readonly output?: CameraOutputSnapshot;
   readonly antialias: Antialias;
+  /** Optional detached Camera companion for fixed or adaptive scaling. */
+  readonly dynamicResolution?: DynamicResolutionData;
   readonly bloom: BloomEnabled;
   readonly bloomThreshold: number;
   readonly bloomIntensity: number;
   readonly bloomBlurRadius: number;
   readonly clearColor: readonly [number, number, number, number];
+  /** Optional active-camera SSR authoring fact, copied from the ECS schema. */
+  readonly screenSpaceReflection?: ScreenSpaceReflectionData;
   /** Renderer-owned temporal projection used by Standard's TAA producer. */
   readonly temporal?: TemporalView;
   /** Active-camera motion blur parameters, present only when demanded. */
@@ -165,8 +190,8 @@ export type {
   EnvironmentSource,
   FogFrame,
   FramePlan,
-} from './extract/environment';
-export type { TemporalView } from './temporal/view';
+} from './extract/environment.js';
+export type { TemporalView } from './temporal/view.js';
 
 /**
  * Render-graph state exposed to pipeline declarations. Concrete pipeline
@@ -188,8 +213,43 @@ interface RenderPipelineStateView {
  * RenderSystemRuntime structurally satisfies this contract, but the public
  * frame surface does not depend on that assembly owner.
  */
+interface RenderPipelineObservationCapture {
+  readonly domain: 'linear-hdr' | 'linear-ldr' | 'final-srgb';
+  readonly format: TextureFormat;
+  readonly device: RhiDevice;
+  readonly texture: Texture;
+  readonly buffer: Buffer;
+  readonly frameNumber: number;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly backendId: string;
+  readonly width: number;
+  readonly height: number;
+  readonly bytesPerRow: number;
+}
+
+interface RenderPipelineObservationCaptureOwner {
+  readonly register: (capture: RenderPipelineObservationCapture) => void;
+  readonly consume: (frameNumber: number) => readonly RenderPipelineObservationCapture[];
+  readonly drain: () => readonly RenderPipelineObservationCapture[];
+}
+
 interface RenderPipelineRuntime {
   readonly device: RhiDevice;
+  /** Current renderer device generation used to fence graph captures. */
+  readonly deviceGeneration?: number | undefined;
+  /** Public receipt identity reserved for the frame currently being encoded. */
+  readonly observationFrameId?: number | undefined;
+  /** Renderer-issued graph fence populated by the graph owner during encoding. */
+  observationGraphGeneration?: number | undefined;
+  /** Per-renderer bridge for receipt-bound graph color captures. */
+  readonly observationCaptureOwner?: RenderPipelineObservationCaptureOwner | undefined;
+  /**
+   * Domains armed for the frame currently being encoded. An absent or empty
+   * set is the normal zero-cost path; typed graph capture passes remain
+   * declared for topology inspection but do not allocate or copy anything.
+   */
+  readonly observationCaptureDomains?: readonly FrameObservationDomain[] | undefined;
   /** Runtime-owned shader module factory used by built-in graph producers. */
   readonly shaderModuleFactory?: {
     createShaderModule(input: {
@@ -200,6 +260,16 @@ interface RenderPipelineRuntime {
       RhiError
     >;
   };
+  /** Immediate factory used by same-frame built-in producers after runtime warm-up. */
+  readonly immediateShaderModuleFactory?: {
+    createShaderModule(input: {
+      readonly code: string;
+      readonly label?: string | undefined;
+    }): import('@forgeax/engine-types').Result<
+      import('@forgeax/engine-rhi').ShaderModule,
+      RhiError
+    >;
+  };
   readonly errorRegistry: { fire(error: RendererError): void };
   readonly debugOverlay?: RenderDebugOverlay | undefined;
   readonly lookupPostProcess?: (id: string) => PostProcessShaderEntry | undefined;
@@ -207,7 +277,7 @@ interface RenderPipelineRuntime {
   readonly getPostProcessPipeline?: (
     id: string,
     bgl: BindGroupLayout,
-    colorFormat: GPUTextureFormat,
+    colorFormats: readonly GPUTextureFormat[],
     entry?: PostProcessShaderEntry,
   ) => RhiRenderPipeline | null;
 }
@@ -237,6 +307,8 @@ export interface RenderPipelineContext {
   readonly clear: readonly [number, number, number, number] | number[];
   readonly targetW: number;
   readonly targetH: number;
+  /** Renderer-owned output/internal dimensions shared by Standard consumers. */
+  readonly extent?: RenderExtent;
   readonly currentTexture: Texture;
   readonly camera: CameraSnapshot;
   /** Per-frame post-process parameter bytes keyed by shader id. */
@@ -250,6 +322,10 @@ export interface RenderPipelineContext {
   readonly spotLightProjector?: SpotLightProjectorFrameContext;
   /** Build-time composed utility sources for the renderer-owned volume passes. */
   readonly volumetricFogShaders?: VolumetricFogShaderSources;
+  /** Build-time composed utility sources for the renderer-owned SSR passes. */
+  readonly ssrShaders?: SsrShaderSources;
+  /** Build-time composed utility sources for the renderer-owned atmosphere passes. */
+  readonly atmosphereShaders?: AtmosphereShaderSources;
 }
 
 /** Stable utility entry-point sources emitted by the shader manifest. */
@@ -260,6 +336,22 @@ export interface VolumetricFogShaderSources {
   readonly composite: string;
 }
 
+/** Stable utility entry-point sources emitted by the shader manifest. */
+export interface SsrShaderSources {
+  readonly hiz: string;
+  readonly hizReduce: string;
+  readonly trace: string;
+  readonly temporal: string;
+  readonly compose: string;
+}
+
+/** Stable analytic-atmosphere entry-point sources emitted by the shader manifest. */
+export interface AtmosphereShaderSources {
+  readonly ibl: string;
+  readonly cube: string;
+  readonly background: string;
+}
+
 /**
  * GPU resources for one validated volumetric-fog candidate.  The record stage
  * owns residency and parameter uploads; graph passes consume this narrow view
@@ -304,6 +396,7 @@ export interface SpotLightProjectorFrameContext {
  */
 export interface Renderer {
   /** Renderer-owned authoring and update path for large instance collections. */
+  readonly instances: InstanceCollectionStore;
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
   /** Prepare a standard MeshAsset for the active device generation. */
   prepareDynamicGeometry(
@@ -314,10 +407,31 @@ export interface Renderer {
     candidate: DynamicGeometryCandidate,
     ordering: DynamicGeometryOrdering,
   ): Result<DynamicGeometryCandidate, DynamicGeometryError>;
+  /**
+   * Atomically swap distinct entities in one attached World. Returned failures
+   * retain old bindings; an uncertain rollback throws to require paired rebuild.
+   * Invoke inside PhysicsWorld.admitDerivedShapeCandidates commitGeometry.
+   */
+  acceptDynamicGeometryCandidates(
+    candidates: readonly DynamicGeometryCandidate[],
+    ordering: DynamicGeometryOrdering,
+  ): Result<readonly DynamicGeometryCandidate[], DynamicGeometryError>;
   dynamicGeometryReceipt(candidate: DynamicGeometryCandidate): DynamicGeometryReceipt | undefined;
   cancelDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
   retireDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
   draw(input: RenderFrameInput): RenderResult<FrameReceipt, RenderError>;
+  /**
+   * Arm one upcoming submitted frame for explicit color-domain observation.
+   * Observation buffers are not created, copied, mapped, or retained until a
+   * host calls this method before `draw()`. The demand is consumed only by a
+   * successful submit; a failed frame keeps it armed for a retry.
+   *
+   * This optional extension keeps older injected Renderer test doubles source
+   * compatible while concrete Engine renderers always implement it.
+   */
+  requestObservation?: (
+    domains: readonly FrameObservationDomain[],
+  ) => RenderResult<void, RenderError>;
   createRenderTarget(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
   resizeRenderTarget(
     target: RenderTarget,
@@ -334,6 +448,8 @@ export interface Renderer {
   destroyRenderTarget(target: RenderTarget): RenderResult<void, RenderError>;
   setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
   state(): RendererState;
+  /** Detached world bounds for one record in the last extracted World; undefined if unavailable. */
+  bounds(world: World, entity: number): RenderSceneBounds | undefined;
   inspect(): RenderInspection;
   observe(
     receipt: FrameReceipt,
@@ -371,6 +487,8 @@ export type RendererEvent =
       readonly kind: 'frame-submitted';
       readonly frameId: number;
       readonly deviceGeneration: number;
+      /** The exact draw receipt, for observation when App owns the draw loop. */
+      readonly receipt: FrameReceipt;
     };
 
 /** Package-local listener alias used by the renderer assembly implementation. */
@@ -400,8 +518,17 @@ export interface FrameEnvironment {
  * only with the matching FrameReceipt after `receipt.completed` and returns a
  * structured Result error when the generation or frame identity is stale.
  */
+export type FrameObservationDomain = 'linear-hdr' | 'linear-ldr' | 'final-srgb';
+
+export type FrameObservationInclude =
+  | 'timings'
+  | 'draws'
+  | 'bindings'
+  | 'target-readbacks'
+  | FrameObservationDomain;
+
 export interface FrameObservationRequest {
-  readonly include: readonly ('timings' | 'draws' | 'bindings' | 'target-readbacks')[];
+  readonly include: readonly FrameObservationInclude[];
   readonly targetReadbacks?: readonly RenderTargetReadbackTicket[];
 }
 
@@ -414,6 +541,10 @@ export interface FrameObservationRequest {
 export interface FrameReceipt {
   readonly frameId: number;
   readonly deviceGeneration: number;
+  /** Backend identity captured at submit and checked before observation. */
+  readonly backendId?: RhiCaps['backendKind'];
+  /** Monotonic compiled graph identity used by renderer-issued observations. */
+  readonly graphGeneration?: number;
   readonly completed: Promise<RenderResult<void, RenderError>>;
 }
 
@@ -436,16 +567,44 @@ export interface RenderFrameInput {
 export interface FrameReceiptObservation {
   readonly frameId: number;
   readonly deviceGeneration: number;
-  readonly include: readonly ('timings' | 'draws' | 'bindings' | 'target-readbacks')[];
+  readonly include: readonly FrameObservationInclude[];
   /** Receipt-bound Render-owned GPU pass facts; absent when not requested. */
   readonly timings?: GpuPassTimingObservation | undefined;
   /** Receipt-bound volume GPU timing facts; absent when not requested. */
   readonly volumeTimings?: VolumeTimingObservation | undefined;
   readonly targetReadbacks?: readonly RenderTargetReadbackData[];
+  /** Independent raw bytes captured from the requested linear/display domains. */
+  readonly observations?: readonly FrameDomainObservation[] | undefined;
+}
+
+export interface FrameDomainObservation {
+  readonly domain: FrameObservationDomain;
+  readonly bytes: Uint8Array;
+  readonly metadata: {
+    readonly frameId: number;
+    readonly deviceGeneration: number;
+    readonly backendId?: RhiCaps['backendKind'];
+    /** Native texture format of the copied attachment, including BGRA order. */
+    readonly format: TextureFormat;
+    readonly graphGeneration: number;
+    readonly textureIdentity: number;
+    readonly readbackIdentity: number;
+    readonly width: number;
+    readonly height: number;
+    readonly bytesPerRow: number;
+    readonly footprint: {
+      readonly resourceCount: number;
+      readonly bindGroupCount: number;
+    };
+  };
 }
 
 /** Stable backend facts for the Standard output transform projection. */
 export interface RenderOutputInspection {
+  /** Camera-owned auto-exposure facts, detached from GPU state when available. */
+  readonly autoExposure?: AutoExposureInspection;
+  /** Renderer-owned detached LUT residency and receipt facts. */
+  readonly standardLut?: StandardLutInspection;
   readonly outputTransform?: typeof STANDARD_OUTPUT_TRANSFORM_FEATURE_ID;
   readonly displayEncoded: boolean;
   readonly intermediateFormat?: TextureFormat;
@@ -493,6 +652,15 @@ export interface RenderObservationInspection {
   /** Exact pass names and target descriptor from the committed graph. */
   readonly passNames: readonly string[];
   readonly standardOutputColor?: RenderStandardOutputColorInspection;
+  /** Monotonic, renderer-owned observation resource facts; no GPU handles. */
+  readonly resourceStats?: {
+    readonly allocationCount: number;
+    readonly liveCount: number;
+    readonly peakLiveCount: number;
+    readonly mapCount: number;
+    readonly readbackCount: number;
+    readonly liveByteLength: number;
+  };
 }
 
 /**
@@ -531,6 +699,12 @@ export interface RenderInspection {
   readonly features: readonly string[];
   /** Truthful lifecycle facts for every registered declarative feature. */
   readonly featureDiagnostics: readonly RenderFeatureDiagnostics[];
+  /** Detached signature and prepared-resource counters for feature planning. */
+  readonly featureHost?: RenderFeatureHostInspection;
+  /** Detached typed-graph compile/reuse and candidate lifecycle counters. */
+  readonly featureGraph?: RenderFeatureGraphInspection;
+  /** Detached material texture-source probe counters from the last extract. */
+  readonly materialTextureSources?: import('./inspection-types').MaterialTextureSourceInspection;
   readonly frustumStats: { readonly culled: number; readonly total: number };
   readonly visibilityStats: { readonly explicitlyHidden: number };
   /** Renderer-owned large-instance residency and upload facts. */
@@ -541,6 +715,8 @@ export interface RenderInspection {
   readonly reflectionProbes: ReflectionProbeInspection;
   /** Renderer-owned SSR dependency seam; consumer facts are projected from live owners. */
   readonly ssrDependencies: SsrDependenciesInspection;
+  /** Renderer-owned SSR spatial status and bounded execution facts. */
+  readonly ssr: SsrSpatialInspection;
   /** Last completed transmission candidate facts, detached from GPU handles. */
   readonly transmission?: TransmissionInspection;
   /** Last prepared Standard transport facts, detached from GPU handles. */
@@ -583,16 +759,12 @@ export interface RenderInspection {
       readonly lastGeneration: number | undefined;
     };
   };
-  /** Output transform facts; never includes fixture metrics or pixel bytes. */
-  readonly outputTransform?: typeof STANDARD_OUTPUT_TRANSFORM_FEATURE_ID;
-  readonly displayEncoded: boolean;
-  readonly intermediateFormat?: TextureFormat;
-  readonly surfaceStorage: TextureFormat;
-  readonly surfaceDisplay: TextureFormat;
-  readonly endpoint: 'surface.storage.raw';
-  readonly capability: RenderOutputInspection['capability'];
-  readonly presentationProof?: RhiCanvasSurfacePresentationProof;
-  readonly error: RenderOutputInspection['error'];
+  /**
+   * Output-transform facts from the same committed graph and physical surface.
+   * Keep this as one named subtree so AI consumers do not have to guess which
+   * detached fields belong to the output contract versus renderer lifecycle.
+   */
+  readonly output: RenderOutputInspection;
   readonly observation: RenderObservationInspection;
   readonly environment: EnvironmentInspection;
   readonly temporal: TemporalInspection;
@@ -626,6 +798,8 @@ export interface RenderInspection {
 export type DrawOwnerOptions = {
   readonly cameraOwner: number;
   readonly resourceOwner: number;
+  /** Optional FrameCamera entity selection; absent preserves ActiveCamera semantics. */
+  readonly cameraEntityKey?: number;
   readonly profileFrame?: ProfileFrameToken;
 };
 
@@ -649,17 +823,18 @@ export type RendererLostListener = (info: RendererLostInfo) => void;
  * exception), NOT the eliminated cross-cluster `RuntimeError` SSOT (D-3).
  *
  * Composition = `RhiError | RenderError | AssetRuntimeError | SkinError |
- * PostProcessError`. This equals the pre-decomposition
- * `RhiError | RuntimeError | PostProcessError` exactly: `RuntimeError` was
- * `RenderError | AssetRuntimeError | SkinError` (27 classes). `RecoverError`
- * and `EngineEnvironmentError` are intentionally excluded — neither is ever
- * emitted through the Renderer event stream (`RecoverError` returns from `recover()`,
- * `EngineEnvironmentError` throws at construction), matching the original
- * `RuntimeError` union which excluded both (OOS-3 behavior equivalence).
+ * GpuDrivenPreparationError | PostProcessError`. The GPU preparation arm is
+ * the renderer-owned producer contract: its closed `code` and typed `detail`
+ * identify the material, geometry, skin, generation, or shadow owner without making
+ * RHI errors carry render policy. `RecoverError` and `EngineEnvironmentError`
+ * are intentionally excluded — neither is ever emitted through the Renderer
+ * event stream (`RecoverError` returns from `recover()`,
+ * `EngineEnvironmentError` throws at construction).
  *
  * AI consumers do `switch (err.code)` over the union: the disjoint
  * `RhiErrorCode` / `RenderErrorCode` / `AssetRuntimeErrorCode` / `SkinErrorCode`
- * / `PostProcessErrorCode` literal sets let TS narrow each arm to the concrete
+ * / `GpuDrivenPreparationErrorCode` / `PostProcessErrorCode` literal sets let
+ * TS narrow each arm to the concrete
  * class (charter P3 union discoverability — every fan-out member is reachable
  * in an exhaustive switch, no untyped escape). Example:
  *
@@ -670,7 +845,8 @@ export type RendererLostListener = (info: RendererLostInfo) => void;
  *     case 'asset-not-registered': // AssetRuntimeError arm, err narrowed here
  *       return report(err.hint);
  *     // ...one arm per RhiErrorCode | RenderErrorCode | AssetRuntimeErrorCode
- *     //    | SkinErrorCode | PostProcessErrorCode member; no default needed,
+ *     //    | SkinErrorCode | GpuDrivenPreparationErrorCode |
+ *     //    PostProcessErrorCode member; no default needed,
  *     //    TS flags every unhandled code at compile time.
  *   }
  * });
@@ -681,6 +857,7 @@ export type RendererError =
   | RenderGraphError
   | ImageError
   | RenderError
+  | GpuDrivenPreparationError
   | AssetRuntimeError
   | SkinError
   | PostProcessError;
@@ -725,6 +902,11 @@ export const RENDER_GRAPH_EXECUTION_PHASE_CATALOG = [
   'record/graph-execute/bloom-blur-h',
   'record/graph-execute/bloom-blur-v',
   'record/graph-execute/bloom-composite',
+  'record/graph-execute/ssr-hiz',
+  'record/graph-execute/ssr-trace',
+  'record/graph-execute/ssr-temporal',
+  'record/graph-execute/ssr-reflection-mip',
+  'record/graph-execute/ssr-compose',
   'record/graph-execute/other',
 ] as const;
 
@@ -814,11 +996,17 @@ export interface RendererOptions {
   readonly profiler?: Profiler | undefined;
   /** Explicitly request timestamp-query for receipt-bound GPU profiling. */
   readonly captureGpuTimings?: boolean | undefined;
+  /** Opt into full-frame reflection fallback pixel readback and hashing for diagnostics. */
+  readonly captureReflectionFallbackReadback?: boolean | undefined;
   /** Optional host-owned RHI lifecycle instrumentation, such as recording. */
   readonly rhiInstrumentation?: RhiBackendInstrumentation | undefined;
   /** Optional bounded GPU pass timing facts; this is not frame latency. */
   readonly gpuPassTiming?: GpuPassTimingOptions | undefined;
-  /** Exact source/tree/lock/build identity binding for the renderer-owned SSR seam. */
+  /**
+   * Exact source/tree/lock/build identity binding for the renderer-owned SSR seam.
+   * Opts into one format-capability probe during device-generation initialization;
+   * camera ScreenSpaceReflection still controls all per-frame SSR work.
+   */
   readonly ssrIdentity?: SsrAdmissionIdentity | undefined;
   // feat-20260608-create-app-param-surface-trim / M1 / AC-02: `clearColor`
   // was deleted as a one-cut breaking change (AGENTS.md Change stance +

package/src/render-graph-primitives.ts

@@ -15,6 +15,7 @@ import type {
   TextureFormat,
   TextureView,
 } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
 import {
   buildFullscreenPostProcessPass,
   createFullscreenBindGroup,
@@ -28,7 +29,7 @@ import type { _InternalRenderPipelineContext } from './record/render-context';
 import { recordFxaaPass } from './record/skybox-post-pass';
 import type { RenderPipelineContext } from './render-contract';
 import { getOrCreateSsaoBuffers, getOrCreateSsaoFallbackTexture } from './ssao-buffers';
-import { getSsaoParameters } from './ssao-config';
+import { getSsaoParameters, SSAO_SAMPLE_COUNTS } from './ssao-config';
 
 type DepthResolutionContext = Pick<_InternalRenderPipelineContext, 'runtime'> & {
   readonly frameState: {
@@ -198,6 +199,12 @@ function ensureSsaoRecordCompanions(internals: _InternalRenderPipelineContext):
 function buildSsaoUniformPayload(internals: _InternalRenderPipelineContext): Float32Array {
   const { camera, frameState } = internals;
   const sProj = computeProjectionMatrix(camera);
+  if (camera.temporal?.currentJitterUv !== undefined) {
+    const jitter = mat4.identity(mat4.create());
+    jitter[12] = camera.temporal.currentJitterUv[0] * 2;
+    jitter[13] = camera.temporal.currentJitterUv[1] * -2;
+    mat4.multiply(sProj, jitter, sProj);
+  }
   const sView = computeViewMatrix(camera);
   const invProj = mat4.create();
   mat4.invert(invProj, sProj);
@@ -214,6 +221,7 @@ function buildSsaoUniformPayload(internals: _InternalRenderPipelineContext): Flo
   out[48] = parameters.intensity;
   out[49] = parameters.radius;
   out[50] = parameters.bias;
+  out[51] = SSAO_SAMPLE_COUNTS[parameters.quality];
   return out;
 }
 
@@ -256,7 +264,19 @@ export function recordSsaoCalcPass(
   const { runtime, pipelineState, encoder } = _c;
   const pp = pipelineState.perPassResources;
 
-  if (pp.ssaoCalcPipeline === null || pp.ssaoBgl === null) return;
+  if (runtime.device.caps.backendKind === 'wgpu-webgl2') {
+    throw new RhiError({
+      code: 'feature-not-enabled',
+      expected: 'SSAO raw depth sampling on a WebGPU-capable backend',
+      hint: 'use WebGPU for SSAO or disable StandardProfile.ssao on the GLES fallback',
+    });
+  }
+  if (pp.ssaoCalcPipeline === null || pp.ssaoBgl === null) {
+    throw new PostProcessError({
+      code: 'post-process-not-found',
+      detail: { id: 'forgeax::post::ssao-calc' },
+    });
+  }
   if (graphViews === undefined && (resolveCtx === undefined || ssaoRawKey === undefined)) return;
 
   const ssaoRawView =
@@ -392,7 +412,12 @@ export function recordSsaoBlurPass(
   const { runtime, pipelineState, encoder } = _c;
   const pp = pipelineState.perPassResources;
 
-  if (pp.ssaoBlurPipeline === null || pp.ssaoBgl === null) return;
+  if (pp.ssaoBlurPipeline === null || pp.ssaoBgl === null) {
+    throw new PostProcessError({
+      code: 'post-process-not-found',
+      detail: { id: 'forgeax::post::ssao-blur' },
+    });
+  }
   if (
     graphViews === undefined &&
     (resolveCtx === undefined || ssaoBlurredKey === undefined || ssaoRawKey === undefined)
@@ -551,6 +576,7 @@ function dispatchFullscreenPass(
   graphOutputFormat?: GPUTextureFormat,
   graphDepthView?: TextureView,
   paramsOverride?: Uint8Array,
+  fragmentEntryPoint?: string,
 ): void {
   if (shader === 'fxaa') {
     if (resolveCtx === undefined) {
@@ -559,7 +585,7 @@ function dispatchFullscreenPass(
         detail: { readsKey: reads[0] ?? 'ldrColor', passName: name },
       });
     }
-    recordFxaaPass(requireRenderGraphRecordContext(ctx), resolveCtx, graphPass);
+    recordFxaaPass(requireRenderGraphRecordContext(ctx), resolveCtx, graphPass, paramsOverride);
     return;
   }
   const lookup = ctx.runtime.lookupPostProcess;
@@ -773,7 +799,8 @@ function dispatchFullscreenPass(
   const lookupPipeline = ctx.runtime.getPostProcessPipeline;
   if (lookupPipeline === undefined) return;
   const postColorFormat = writeFormat;
-  const pipeline = lookupPipeline(shader, built.bindGroupLayout, postColorFormat);
+  const pipelineEntry = fragmentEntryPoint === undefined ? entry : { ...entry, fragmentEntryPoint };
+  const pipeline = lookupPipeline(shader, built.bindGroupLayout, [postColorFormat], pipelineEntry);
   if (pipeline === null) return;
   const handle = built.createHandle(name, pipeline, paramsBuffer);
 
@@ -814,6 +841,7 @@ export function encodeFullscreenPass(
     readonly rawSwapchainOutput?: boolean | undefined;
     readonly depthView?: TextureView | undefined;
     readonly paramsOverride?: Uint8Array | undefined;
+    readonly fragmentEntryPoint?: string | undefined;
   },
 ): void {
   dispatchFullscreenPass(
@@ -829,5 +857,6 @@ export function encodeFullscreenPass(
     input.outputFormat,
     input.depthView,
     input.paramsOverride,
+    input.fragmentEntryPoint,
   );
 }