@forgeax/engine-render 0.1.21 → 0.1.24

package/src/render-contract.ts

@@ -26,18 +26,23 @@ 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 {
   BloomInspection,
   DirectionalShadowInspection,
+  LightInspection,
+  LodOcclusionInspection,
   MotionBlurInspection,
   ReflectionProbeInspection,
   RenderSceneInspection,
+  SsrDependenciesInspection,
   TemporalTargetInspection,
   TransmissionInspection,
 } from './inspection-types';
+import type { SsrAdmissionIdentity } from './ssr/identity';
 import type {
   RenderTarget,
   RenderTargetDescriptor,
@@ -52,7 +57,10 @@ import type { TemporalInspection } from './temporal/inspection';
 export type { TransmissionInspection } from './inspection-types';
 export type { PointsLinesInspection } from './points-lines/inspection';
 
-import type { MeshMaterialBindingObservation } from './mesh-material-bindings';
+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';
@@ -104,9 +112,9 @@ export interface CameraSnapshot {
   readonly worldId?: number;
   /** Camera-owned history generation forwarded into the frame plan. */
   readonly historyVersion?: number;
-  /** World-space camera translation (mat4.getTranslation of Transform.world). */
+  /** World-space camera translation (mat4.getTranslation of GlobalTransform.world). */
   readonly position: Vec3;
-  /** Resolved world-space camera mat4, copied from Transform.world. */
+  /** Resolved world-space camera mat4, copied from GlobalTransform.world. */
   readonly world: Float32Array;
   readonly fov: number;
   readonly aspect: number;
@@ -161,9 +169,6 @@ interface RenderPipelineStateView {
   readonly colorAttachmentFormat: TextureFormat;
   /** Renderer-owned View UBO shared by Standard lighting, shadows, and fog. */
   readonly viewUniformBuffer: Buffer;
-  /** Renderer-owned SpotLight std430 buffer shared by Standard and volume. */
-  readonly pointLightsBuffer: Buffer;
-  readonly spotLightsBuffer: Buffer;
   /** Fallback resources keep the shared view layout valid when no projector is authored. */
   readonly defaultWhiteTextureView: TextureView;
   readonly defaultSampler: Sampler;
@@ -283,8 +288,10 @@ export interface SpotLightProjectorFrameContext {
 }
 
 /**
- * The sole public renderer contract. Concrete assembly stays behind the host;
- * callers retain only leases, receipts, inspection PODs, and recovery Result.
+ * The sole public renderer contract. Consume it in this order:
+ * `state()` -> `inspect()` -> `recover()` when degraded -> `draw()` and its
+ * `FrameReceipt`. Concrete assembly stays behind the host; callers retain only
+ * leases, receipts, inspection PODs, and recovery Result values.
  */
 export interface Renderer {
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
@@ -318,7 +325,12 @@ export interface Renderer {
   dispose(): Promise<RenderResult<void, RenderError>>;
 }
 
-/** The single public renderer lifecycle authority. */
+/**
+ * The single public renderer lifecycle authority. This closed union is the
+ * frame gate: only `alive` admits World update and draw; `device-lost` and
+ * `recovering` are explicit recovery states; `faulted` requires recreation;
+ * `disposed` is terminal.
+ */
 export type RendererState = 'alive' | 'device-lost' | 'recovering' | 'faulted' | 'disposed';
 
 /** Immutable, inspectable quality and budget policy for the Standard pipeline. */
@@ -373,8 +385,9 @@ export interface FrameObservationRequest {
 
 /**
  * Immutable synchronous proof that the sole host-owned submit reached the
- * queue. It is the only successful synchronous draw signal and is required by
- * every observation request.
+ * queue. It is the only successful synchronous draw signal. Its
+ * `deviceGeneration` fences stale work, and every observation request must use
+ * this exact receipt; a recovery retry must obtain a new one.
  */
 export interface FrameReceipt {
   readonly frameId: number;
@@ -462,10 +475,26 @@ export interface RenderObservationInspection {
  * Detached renderer facts for host diagnostics and capability selection.
  *
  * The snapshot contains only POD values. It never exposes a device, queue,
- * registry, encoder, or live renderer-owned collection.
+ * registry, encoder, or live renderer-owned collection. Read `state` and the
+ * bounded `recovery` detail before choosing to wait, retry, repair an owner,
+ * or recreate the Renderer; this projection is not a proof of Browser/Dawn
+ * execution.
  */
 export interface RenderInspection {
   readonly state: RendererState;
+  /** Bounded detached facts for the current or last recovery attempt. */
+  readonly recovery: {
+    readonly phase: RecoveryPhase | null;
+    readonly fromGeneration: number;
+    readonly candidateGeneration: number;
+    readonly attempt: number;
+    readonly elapsedMs: number;
+    readonly lastOutcome: RecoveryOutcome;
+    readonly failedOwner?: string;
+    readonly failedResourceKind?: string;
+    readonly rehydratedRoots: number;
+    readonly staleLossEvents: number;
+  };
   readonly surface: 'available' | 'released';
   readonly profile: RenderProfile;
   readonly capabilities: Readonly<RhiCaps>;
@@ -482,6 +511,8 @@ export interface RenderInspection {
   readonly visibilityStats: { readonly explicitlyHidden: number };
   readonly renderScene: RenderSceneInspection;
   readonly reflectionProbes: ReflectionProbeInspection;
+  /** Renderer-owned SSR dependency seam; consumer facts are projected from live owners. */
+  readonly ssrDependencies: SsrDependenciesInspection;
   /** Last completed transmission candidate facts, detached from GPU handles. */
   readonly transmission?: TransmissionInspection;
   /** Last prepared Standard transport facts, detached from GPU handles. */
@@ -489,11 +520,41 @@ export interface RenderInspection {
   /** Renderer-owned point-shadow atlas budget facts from the last frame. */
   readonly pointShadow?: PointShadowInspection;
   readonly meshMaterialBindings: readonly MeshMaterialBindingObservation[];
+  /** Final-submit Standard IBL binding-chain receipt, when diagnostics ran. */
+  readonly iblBinding?: IblBindingInspection;
   readonly perFramePassNames: readonly string[];
   readonly bindGroupCounts: {
     readonly createBindGroup: number;
     readonly keys: readonly string[];
   };
+  /**
+   * Recovery evidence projected from production owners. Graph, residency,
+   * submit, and receipt fields are observations, not recovery test fixtures.
+   */
+  readonly recoveryEvidence: {
+    readonly producerRoots: readonly {
+      readonly kind: string;
+      readonly owner: string;
+      readonly candidateScope: 'device-scope';
+      readonly visibility: 'visible-workset' | 'non-visible-lazy';
+      readonly disabledWork: 'zero' | 'lazy';
+    }[];
+    readonly graph: {
+      readonly ready: boolean;
+      readonly generation: number;
+      readonly passCount: number;
+      readonly resourceCount: number;
+    };
+    readonly residency: { readonly meshResidencyEpoch: number };
+    readonly submissions: {
+      readonly count: number;
+      readonly lastGeneration: number | undefined;
+    };
+    readonly receipts: {
+      readonly count: number;
+      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;
@@ -508,11 +569,15 @@ export interface RenderInspection {
   readonly environment: EnvironmentInspection;
   readonly temporal: TemporalInspection;
   readonly bloom: BloomInspection;
+  /** Candidate/accepted/LKG facts for the single extendedLighting topology. */
+  readonly extendedLighting: LightInspection;
   readonly directionalShadow: DirectionalShadowInspection;
   /** Semantic Standard temporal target metadata; no graph or RHI handles. */
   readonly temporalTarget?: TemporalTargetInspection;
   /** Renderer-owned Motion Blur facts; absent when no component is active. */
   readonly motionBlur?: MotionBlurInspection;
+  /** Bounded renderer-owned LOD/occlusion facts; absent before a candidate frame. */
+  readonly lodOcclusion?: LodOcclusionInspection;
 }
 
 /** Backend marker — single-element union preserved for future extensibility (D-2). */
@@ -676,6 +741,8 @@ export const RENDER_SCENE_STATE_PHASE_CATALOG = [
  * attribution without guessing from RHI command counts.
  */
 export const RENDER_RECORD_PHASE_CATALOG = [
+  'record/occlusion-query-submit',
+  'record/occlusion-global-advance',
   'record/scene-state',
   ...RENDER_SCENE_STATE_PHASE_CATALOG,
   'record/swapchain',
@@ -693,6 +760,7 @@ export type RenderRecordPhase = (typeof RENDER_RECORD_PHASE_CATALOG)[number];
 
 export const RENDER_PHASE_CATALOG = [
   'extract',
+  'occlusion-prepare',
   'bind-groups',
   'features',
   'sort',
@@ -722,6 +790,8 @@ export interface RendererOptions {
   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. */
+  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 +
   // requirements constraint #1: no deprecation window, no shim). Scene

package/src/render-pipeline.ts

@@ -46,6 +46,7 @@ import type { StandardTopologyInputValue } from './pipeline/standard-lighting/to
 import { STANDARD_POST_STAGE_NAMES, type StandardProfile } from './pipeline/standard-profile';
 import type { SurfaceProfile } from './record/render-context';
 import type { RenderPipelineContext } from './render-contract';
+import type { OcclusionFrameProjection } from './scene/visibility/occlusion-runtime';
 import type { TransmissionDemand } from './transmission/projection';
 
 export type { RenderPipelineContext } from './render-contract';
@@ -215,6 +216,8 @@ export interface RenderPipelineTopology {
    * clear directly to the surface.
    */
   readonly clearOnly?: boolean | undefined;
+  /** Whether Standard main draws carry the producer-owned fallback MRT. */
+  readonly reflectionFallback?: { readonly enabled: boolean } | undefined;
   readonly surface: {
     readonly width: number;
     readonly height: number;
@@ -458,6 +461,8 @@ export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame
     readonly destination: GraphTextureView;
     readonly level: number;
   }) => void;
+  /** Renderer-owned occlusion query state for the primary scene pass. */
+  readonly occlusion?: OcclusionFrameProjection;
   projectGpuDriven(target: {
     readonly format: TextureFormat;
     readonly sampleCount: 1 | 4;