@forgeax/engine-render 0.1.20 → 0.1.23

package/src/index.ts

@@ -11,6 +11,13 @@ export {
   renderPipelineContribution,
   samplerContribution,
 } from './assets/asset-decoders';
+// Runtime contract: leases, frame receipts, detached inspection, profile,
+// lifecycle state, and the single renderer event stream.
+export type {
+  CubeCameraFaceView,
+  CubeCameraFaceViewInput,
+} from './capture/cube-views';
+export { buildCubeCameraFaceViews } from './capture/cube-views';
 export { Atmosphere } from './components/atmosphere';
 // ECS render vocabulary and grouped closed values.
 export type {
@@ -42,10 +49,24 @@ export {
   TONEMAP_REINHARD,
   TONEMAP_REINHARD_EXTENDED,
 } from './components/camera';
+export {
+  CUBE_CAMERA_FACE_ORDER,
+  CUBE_CAMERA_UPDATE_CONTINUOUS,
+  CUBE_CAMERA_UPDATE_ON_DEMAND,
+  CUBE_CAMERA_UPDATE_ONCE,
+  CubeCamera,
+  type CubeCameraData,
+  type CubeCameraFace,
+  type CubeCameraUpdateIntent,
+  cubeCameraUpdateIntentFromF32,
+  cubeCameraUpdateIntentToF32,
+} from './components/cube-camera';
 export * from './components/directional-light';
 export { Fog } from './components/fog';
 export { Instances, type InstancesData } from './components/instances';
 export { Layer } from './components/layer';
+export * from './components/light-helpers';
+export { LightProbe } from './components/light-probe';
 export { Lines } from './components/lines';
 export * from './components/mesh-filter';
 export * from './components/mesh-renderer';
@@ -59,6 +80,17 @@ export {
   pointShapeFromU32,
 } from './components/points';
 export { PostProcessParams } from './components/post-process-params';
+export { RectAreaLight } from './components/rect-area-light';
+export {
+  REFLECTION_PROBE_UPDATE_CONTINUOUS,
+  REFLECTION_PROBE_UPDATE_ON_CHANGE,
+  REFLECTION_PROBE_UPDATE_ONCE,
+  ReflectionProbe,
+  type ReflectionProbeData,
+  type ReflectionProbeUpdateIntent,
+  reflectionProbeUpdateIntentFromF32,
+  reflectionProbeUpdateIntentToF32,
+} from './components/reflection-probe';
 export { SceneInstance } from './components/scene-instance';
 export {
   SKYBOX_MODE_CUBEMAP,
@@ -84,8 +116,14 @@ export type {
 // Public structured operation failure union. Concrete error classes stay
 // behind the Renderer Result/event boundary.
 export type {
+  ReflectionProbeBudgetExceededDetail,
   RenderError,
   RenderErrorCode,
+  RenderIntentInvalidDetail,
+  RenderTargetCapabilityMissingDetail,
+  RenderTargetDescriptorInvalidDetail,
+  RenderTargetOperationFailedDetail,
+  RenderTargetStateInvalidDetail,
   SceneDataUnavailableDetail,
   SceneDataUnavailableReason,
 } from './errors/render';
@@ -131,13 +169,50 @@ export type {
   RenderFeatureStatus,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
+export {
+  beginProbeIblUpdate,
+  createIblKernelCache,
+  createProbeIblOutput,
+  type IblKernelCache,
+  type ProbeIblOutput,
+  type ProbeIblUpdate,
+  publishProbeIblOutput,
+  REFLECTION_PROBE_IBL_STAGES,
+  type ReflectionProbeIblStage,
+  resetIblKernelCaches,
+} from './ibl/kernel-cache';
 export type {
   BloomInspection,
+  LightInspection,
+  LodOcclusionInspection,
   MotionBlurInspection,
   MotionBlurInspectionStatus,
+  ReflectionFallbackFailureStage,
+  ReflectionFallbackInspection,
+  ReflectionFallbackReadbackReceipt,
+  ReflectionFallbackReceipt,
+  ReflectionFallbackRecoveryAction,
+  ReflectionProbeInspection,
+  ReflectionProbeSelectionInspection,
   TransmissionInspection,
 } from './inspection-types';
 export { Materials, MaterialTransmissionContractError } from './materials';
+export {
+  type MeshMaterialBindingObservation,
+  type MeshMaterialBindingPreparationFailure,
+  type MeshMaterialBindingReadiness,
+  type MeshMaterialBindingResidency,
+  type MeshMaterialBindingSamplerObservation,
+  type MeshMaterialBindingSummary,
+  type MeshMaterialBindingTextureObservation,
+  projectMeshMaterialBindingObservation,
+  summarizeMeshMaterialBindings,
+} from './mesh-material-bindings';
+export type {
+  StandardClusterTransportInspection,
+  StandardLightingInspection,
+  StandardNoLocalLightingInspection,
+} from './pipeline/standard-lighting/inspection';
 // The host-facing default is a stable profile value; implementation-only
 // pipeline helpers remain behind the package boundary.
 export {
@@ -146,6 +221,10 @@ export {
   type StandardVolumetricFogQuality,
 } from './pipeline/standard-profile';
 export { renderComponentsPlugin } from './plugin';
+export {
+  inspectPointShadow,
+  type PointShadowInspection,
+} from './point-shadow-inspection';
 export {
   admitPointsLines,
   type LinesStyleInput,
@@ -156,9 +235,71 @@ export {
   type PointsStyleInput,
 } from './points-lines/admission';
 export type { PointsLinesInspection } from './points-lines/inspection';
+/**
+ * Public bounded GPU pass facts. Use the single `gpuPassTiming` opt-in,
+ * `draw()` receipt, and `observe(receipt, { include: ['timings'] })` route.
+ * Branch on the closed statuses `complete`, `partial`, `unavailable`, and
+ * `failed`; each reason/error exposes `code`, `expected`, `hint`, and `detail`.
+ * `latestKnownGood` is separate from current status and completeness. These
+ * facts describe pass durations, never frame latency. The bounded contract is
+ * in `record/gpu-pass-timing/contract.ts`; benchmark acceptance is fail-closed
+ * in `bench/gpu-pass-timing/validator.ts`, and recovery follows the producer's
+ * structured hint rather than a second timing API.
+ */
+export type {
+  GpuPassTimingCapability,
+  GpuPassTimingEntry,
+  GpuPassTimingError,
+  GpuPassTimingErrorCode,
+  GpuPassTimingFrame,
+  GpuPassTimingMeasuredEntry,
+  GpuPassTimingMeasurementSource,
+  GpuPassTimingObservation,
+  GpuPassTimingOptions,
+  GpuPassTimingPassIdentity,
+  GpuPassTimingReason,
+  GpuPassTimingReasonCode,
+  GpuPassTimingRef,
+  GpuPassTimingUnmeasuredEntry,
+} from './record/gpu-pass-timing/index.js';
 // Runtime contract: leases, frame receipts, detached inspection, profile,
 // lifecycle state, and the single renderer event stream.
+export {
+  advanceProbeFilter,
+  boxProjectReflectionDirection,
+  commitProbeFilterStep,
+  createProbeFilterState,
+  type ProbeFilterState,
+  probeFilterIsSteady,
+} from './reflection/filter';
+export {
+  buildReflectionProbeTable,
+  type ReflectionProbeTable,
+  type ReflectionProbeTableRow,
+  reflectionProbeTableBytes,
+} from './reflection/gpu-table';
+export {
+  inspectReflectionFallback,
+  type ReflectionFallbackFailureInput,
+} from './reflection/inspection';
+export {
+  admitReflectionProbe,
+  DEFAULT_REFLECTION_PROBE_LIMITS,
+  estimateReflectionProbeBytes,
+  type ReflectionProbeAdmission,
+  type ReflectionProbeAdmissionLimits,
+  type ReflectionProbeFact,
+  type ReflectionProbeInput,
+  ReflectionProbeProjection,
+  type ReflectionProbeProjectionSnapshot,
+  type ReflectionProbeSelection,
+  type ReflectionProbeSelectionResult,
+  type SkylightSelection,
+  selectReflectionProbe,
+  validateReflectionProbeInput,
+} from './reflection/projection';
 export type {
+  CubeCameraSnapshot,
   FrameCamera,
   FrameEnvironment,
   FrameObservationRequest,
@@ -179,6 +320,87 @@ export type {
   TemporalInspectionInput,
   TemporalInspectionStatus,
 } from './renderer-inspect';
+export type {
+  GpuFrameTiming,
+  GpuFrameTimingProtocol,
+  GpuFrameTimingRecord,
+  GpuFrameTimingSample,
+  GpuFrameTimingSummary,
+} from './scene/visibility/gpu-frame-timing';
+export {
+  createGpuFrameTiming,
+  recordGpuFrameTiming,
+  summarizeGpuFrameTiming,
+} from './scene/visibility/gpu-frame-timing';
+export type {
+  LodOcclusionDegradation,
+  LodOcclusionFallback,
+  LodOcclusionInspectionAction,
+  LodOcclusionInspectionBudget,
+  LodOcclusionInspectionError,
+  LodOcclusionInspectionInput,
+  LodOcclusionInspectionRow,
+  LodOcclusionInspectionSample,
+  LodOcclusionInspectionSubmit,
+  LodOcclusionWorldAttribution,
+  LodOcclusionWorldInspection,
+  LodOcclusionWorldInspectionInput,
+} from './scene/visibility/inspection';
+export {
+  consumeLodOcclusionInspection,
+  inspectLodOcclusion,
+  LOD_OCCLUSION_INSPECTION_MAX_BYTES,
+  LOD_OCCLUSION_INSPECTION_SCHEMA,
+  serializeLodOcclusionInspection,
+} from './scene/visibility/inspection';
+export {
+  SHADOW_ATLAS_DEFAULT_FACE_SIZE,
+  SHADOW_ATLAS_DEFAULT_LAYERS,
+  ShadowAtlas,
+} from './shadow-atlas';
+export type {
+  SsrAdmissionBudget,
+  SsrAdmissionFailure,
+  SsrAdmissionIdentity,
+  SsrAdmissionInput,
+  SsrAdmissionResult,
+  SsrAdmissionWork,
+  SsrDependenciesInspection,
+  SsrFormatReceipt,
+  SsrReflectionFallbackReceipt,
+  SsrTemporalReceipt,
+} from './ssr/admission';
+export {
+  admitSsrM0,
+  projectSsrDependencies,
+  resolveSsrAdmissionGeneration,
+  SSR_FORMAT_PROFILE,
+  SSR_FORMAT_STAGES,
+  zeroSsrAdmissionWork,
+} from './ssr/admission';
+export {
+  composeSsrReflection,
+  type SsrCompositionInput,
+  type SsrCompositionInputError,
+  type SsrCompositionResult,
+  type SsrReflectionColor,
+} from './ssr/composition';
+export type {
+  RenderTarget,
+  RenderTargetAdmissionLimits,
+  RenderTargetDepthFormat,
+  RenderTargetDescriptor,
+  RenderTargetFormat,
+  RenderTargetMipLevels,
+  RenderTargetReadbackData,
+  RenderTargetReadbackRequest,
+  RenderTargetReadbackTicket,
+  RenderTargetSampleCount,
+  RenderTargetShape,
+  RenderTargetTextureAspect,
+  RenderTargetTextureSource,
+  RenderTargetTextureSourceOptions,
+} from './targets/contracts';
 export type { TemporalInspection, TemporalResourceInspection } from './temporal/inspection';
 export {
   SCENE_DATA_TEMPORAL_V1_DESCRIPTOR,

package/src/inspection-types.ts

@@ -4,7 +4,77 @@
  * extract/record dependency graph.
  */
 
+import type { DirectionalShadowFilterLabel } from './components/directional-shadow-filter';
 import type { PointsLinesInspection } from './points-lines/inspection';
+import type { LodOcclusionInspection } from './scene/visibility/inspection';
+import type { SsrAdmissionIdentity } from './ssr/identity';
+
+export type {
+  LodOcclusionInspection,
+  LodOcclusionInspectionRow,
+  LodOcclusionWorldAttribution,
+  LodOcclusionWorldInspection,
+} from './scene/visibility/inspection';
+
+export interface LodOcclusionInspectionSummary extends LodOcclusionInspection {
+  readonly timing?: {
+    readonly medianUs: number;
+    readonly p95Us: number;
+    readonly samples: number;
+  };
+}
+
+/**
+ * SSR M0 inspection is a detached projection of the consumer admission
+ * result. The admission owner remains in `ssr/admission`; this re-export
+ * keeps inspection callers on the same typed identity and status vocabulary.
+ */
+export type {
+  SsrAdmissionBudget,
+  SsrAdmissionResult,
+  SsrAdmissionWork,
+  SsrDependenciesInspection,
+  SsrFormatReceipt,
+  SsrReflectionFallbackReceipt,
+  SsrTemporalReceipt,
+} from './ssr/admission';
+export type {
+  SsrAdmissionError,
+  SsrAdmissionErrorCode,
+  SsrAdmissionErrorDetail,
+  SsrOwnerRecoveryAction,
+} from './ssr/errors';
+export type { SsrAdmissionIdentity } from './ssr/identity';
+
+export interface LightInspectionInput {
+  readonly generation: number;
+  readonly candidate: string | undefined;
+  readonly accepted: string | undefined;
+  readonly lastKnownGood: string | undefined;
+  readonly failure: string | undefined;
+  readonly failureKeys: readonly string[];
+  readonly resourceCount: number;
+  readonly uploadBytes: number;
+}
+
+export type LightInspection = Readonly<LightInspectionInput>;
+
+export function projectLightInspection(input: LightInspectionInput): LightInspection {
+  return Object.freeze({
+    generation: input.generation,
+    candidate: input.candidate,
+    accepted: input.accepted,
+    lastKnownGood: input.lastKnownGood,
+    failure: input.failure,
+    failureKeys: [...input.failureKeys],
+    resourceCount: input.resourceCount,
+    uploadBytes: input.uploadBytes,
+  });
+}
+
+export function lightInspectionIdentity(topology: string, generation: number): string {
+  return `${topology}:generation-${generation}`;
+}
 
 export type BloomGraphStatus = 'empty' | 'valid' | 'invalid';
 
@@ -33,6 +103,62 @@ export interface BatchTopologyInspection {
   readonly ineligible: number;
 }
 
+export interface ProbeBlendRecordInspection {
+  readonly objectKey: number;
+  readonly generation: number;
+  readonly localBlendFraction: number;
+  readonly shPreblend: readonly number[];
+  readonly byteLength: number;
+  readonly candidate: boolean;
+  readonly accepted: boolean;
+  readonly lastKnownGood: boolean;
+  readonly sentinel: string | undefined;
+  readonly probeBlendIndex: number;
+  readonly contributors: readonly {
+    readonly identity: string;
+    readonly distance: number;
+    readonly radius: number;
+    readonly coverage: number;
+    readonly q: number;
+    readonly qHat: number;
+    readonly alpha: number;
+  }[];
+  readonly qHatSum: number;
+  readonly rStar: number;
+  readonly fallbackReason: string | undefined;
+}
+
+export interface ProbeSkyInspection {
+  readonly available: boolean;
+  readonly identity: string | undefined;
+  readonly sourceKey: string | undefined;
+  readonly irradiance: readonly [number, number, number];
+  readonly fallbackReason: string | undefined;
+}
+
+export interface ProbeBlendInspection {
+  readonly activeContributorCount: number;
+  readonly admittedProbeCount: number;
+  readonly coverage: number;
+  readonly skyResidualFraction: number;
+  readonly finite: boolean;
+  readonly errorCode: 'capacity-exceeded' | 'invalid-admitted-prefix' | undefined;
+  readonly records: readonly ProbeBlendRecordInspection[];
+  readonly sky: ProbeSkyInspection;
+  readonly dirtyVisitCount: number;
+  readonly dirtyReasons: readonly string[];
+  readonly receipt: {
+    readonly activeIdentities: readonly string[];
+    readonly admittedIdentities: readonly string[];
+    readonly rejectedIdentities: readonly string[];
+    readonly stableOrder: readonly string[];
+    readonly capacity: number;
+    readonly scaleRadius: number;
+    readonly finite: boolean;
+    readonly overflowReason: 'active-count-exceeds-capacity' | undefined;
+  };
+}
+
 export interface GpuSceneTableInspection {
   readonly capacity: number;
   readonly bytes: number;
@@ -63,6 +189,154 @@ export interface GpuDrivenProductionInspection {
   readonly topologyRevision: number | undefined;
   readonly validatedGpuOwnedRows: number;
   readonly cpuFallbackDrawItems: number;
+  /** Index work accumulated by the real GPU LOD selector for the last submit. */
+  readonly geometryWork: number;
+  /** Level-0 index work for the same selected candidates. */
+  readonly rootGeometryWork: number;
+  /** `1 - geometryWork / rootGeometryWork` when the root denominator is non-zero. */
+  readonly geometryWorkReduction: number;
+  /** Number of selector batches in the last filtered production plan. */
+  readonly batchCount: number;
+  /** Number of non-zero-capacity indirect raster commands actually encoded. */
+  readonly indirectDrawCount: number;
+}
+
+export type DirectionalShadowEffectiveProfile =
+  | 'off'
+  | DirectionalShadowFilterLabel
+  | 'rhi-null-structural';
+
+export type DirectionalShadowProfile = 'off' | DirectionalShadowFilterLabel;
+
+export interface DirectionalShadowInspectionError {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail?: unknown;
+}
+
+/** Bounded, detached Directional shadow facts for AI-readable inspection. */
+export interface DirectionalShadowInspection {
+  readonly requested: DirectionalShadowProfile;
+  readonly effective: DirectionalShadowEffectiveProfile;
+  readonly status: 'accepted' | 'fallback' | 'rejected';
+  readonly fallbackReason?: 'webgl2-unsupported' | 'rhi-null-structural' | 'candidate-failed';
+  readonly lastKnownGood: boolean;
+  readonly pixelEvidence: 'available' | 'not-available';
+  readonly cascadeCount: number;
+  readonly mapSize: number;
+  readonly atlasBytes: number;
+  readonly writerPasses: number;
+  readonly blockerTaps: number;
+  readonly filterTapUpperBound: number;
+  readonly seamTapUpperBound: number;
+  readonly shadowAngularRadius: number | undefined;
+  readonly maxPenumbraTexels: number | undefined;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly error?: DirectionalShadowInspectionError;
+}
+
+export type ReflectionProbeSelectionInspection =
+  | { readonly kind: 'probe'; readonly worldId: number; readonly entityKey: number }
+  | { readonly kind: 'skylight' };
+
+export type ReflectionFallbackSource = 'probe' | 'skylight' | 'neutral';
+
+export type ReflectionFallbackState = 'candidate' | 'active' | 'lkg' | 'neutral' | 'unavailable';
+
+/** Detached committed fallback facts; never exposes a live GPU handle. */
+export interface ReflectionFallbackReceipt {
+  /** Device-scope owner that identifies the renderer transaction. */
+  readonly rendererId?: string;
+  /** Stable producer identity for this detached projection. */
+  readonly producerId?: string;
+  /** Stable main-pass renderable identity, when this is a per-renderable row. */
+  readonly renderableKey?: string;
+  /** Stable producer source identity, never a physical resource handle. */
+  readonly sourceKey?: string;
+  /** Frame number that produced this detached receipt. */
+  readonly frameId?: number;
+  readonly source: ReflectionFallbackSource;
+  readonly sourceGeneration: number;
+  readonly projectionGeneration: number;
+  readonly deviceGeneration: number;
+  readonly state: ReflectionFallbackState;
+  readonly candidateVisible: false;
+  readonly coverage: number;
+  readonly extent?: readonly [number, number, number];
+  readonly brdfSignature: string;
+  /** Exact host identity of the detached producer transaction, when bound. */
+  readonly identity?: SsrAdmissionIdentity;
+}
+
+/**
+ * One completed readback for the frame-owned fallback attachment.
+ *
+ * This is an aggregate attachment fact, not a per-renderable row.  Row
+ * receipts deliberately carry source/coverage identity only, so one pixel
+ * cannot be mistaken for every renderable's BRDF result.
+ */
+export interface ReflectionFallbackReadbackReceipt {
+  readonly rendererId: string;
+  readonly producerId: string;
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly textureIdentity: number;
+  readonly format: string;
+  readonly size: { readonly width: number; readonly height: number };
+  readonly linearHdr: readonly [number, number, number, number];
+  readonly readbackHash: string;
+  readonly readbackStatus: 'complete';
+}
+
+export type ReflectionFallbackFailureStage =
+  | 'prepare'
+  | 'filter'
+  | 'build'
+  | 'encode'
+  | 'finish'
+  | 'submit'
+  | 'completion';
+
+export type ReflectionFallbackRecoveryAction =
+  | 'use-LKG'
+  | 'use-Skylight'
+  | 'use-neutral'
+  | 'recapture'
+  | 'rebuild'
+  | 'retry';
+
+export interface ReflectionFallbackInspection {
+  readonly receipt: ReflectionFallbackReceipt;
+  readonly failureStage?: ReflectionFallbackFailureStage;
+  readonly failureCode?: string;
+  readonly expected?: string;
+  readonly detail?: Readonly<Record<string, unknown>>;
+  readonly recoveryAction: ReflectionFallbackRecoveryAction;
+}
+
+export interface ReflectionProbeInspection {
+  readonly selection: ReflectionProbeSelectionInspection;
+  readonly factCount: number;
+  readonly acceptedCount: number;
+  readonly activeCount: number;
+  readonly rawFacesCaptured: number;
+  readonly filteredStepsCompleted: number;
+  readonly filteredMipLevels: readonly number[];
+  readonly scheduledRawFaces: number;
+  readonly scheduledFilteredSteps: number;
+  readonly pipelineReady: boolean;
+  readonly pipelineWarmupAttempts: number;
+  readonly pipelineWarmupFailure?: string;
+  readonly reflectionFallback: ReflectionFallbackReceipt;
+  /** Latest bounded fallback failure and owner-directed recovery action. */
+  readonly reflectionFallbackInspection: ReflectionFallbackInspection;
+  /** Bounded per-renderable projections; no live graph resources are included. */
+  readonly reflectionFallbacks?: readonly ReflectionFallbackReceipt[];
+  /** Completed frame attachment readback; separate from per-renderable rows. */
+  readonly reflectionFallbackReadback?: ReflectionFallbackReadbackReceipt;
 }
 
 /** Detached semantic descriptor for the Standard scene-temporal producer. */
@@ -99,7 +373,6 @@ export type RenderSceneResyncReason =
   | 'attach'
   | 'asset-catalog-changed'
   | 'shared-ref-changed'
-  | 'journal-overflow'
   | 'unsupported-change'
   | 'non-rigid-lane'
   | 'explicit-invalidate';
@@ -112,6 +385,8 @@ export interface PersistentRenderSceneInspection {
   readonly transformUpdates: number;
   readonly lastResyncReason: RenderSceneResyncReason | undefined;
   readonly projectionRecords: number;
+  /** Numeric probe ownership facts; no GPU handles or object graph references. */
+  readonly probeBlend?: ProbeBlendInspection;
   readonly topology: BatchTopologyInspection;
   readonly gpu:
     | { readonly status: 'inactive' }