@forgeax/engine-render 0.1.23 → 0.1.25

package/src/render-contract.ts

@@ -26,6 +26,7 @@ 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';
@@ -41,6 +42,7 @@ import type {
   TemporalTargetInspection,
   TransmissionInspection,
 } from './inspection-types';
+import type { InstanceCollectionInspection } from './instances';
 import type { SsrAdmissionIdentity } from './ssr/identity';
 import type {
   RenderTarget,
@@ -56,7 +58,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';
@@ -284,10 +289,13 @@ 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 {
+  /** Renderer-owned authoring and update path for large instance collections. */
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
   draw(input: RenderFrameInput): RenderResult<FrameReceipt, RenderError>;
   createRenderTarget(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
@@ -319,7 +327,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. */
@@ -374,8 +387,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;
@@ -463,10 +477,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>;
@@ -481,6 +511,8 @@ export interface RenderInspection {
   readonly featureDiagnostics: readonly RenderFeatureDiagnostics[];
   readonly frustumStats: { readonly culled: number; readonly total: number };
   readonly visibilityStats: { readonly explicitlyHidden: number };
+  /** Renderer-owned large-instance residency and upload facts. */
+  readonly instanceCollections: readonly InstanceCollectionInspection[];
   readonly renderScene: RenderSceneInspection;
   readonly reflectionProbes: ReflectionProbeInspection;
   /** Renderer-owned SSR dependency seam; consumer facts are projected from live owners. */
@@ -492,11 +524,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;