@forgeax/engine-render 0.1.4 → 0.1.6

package/src/ibl/skylight-bind-group.ts

@@ -98,7 +98,7 @@ export interface SkylightDevice {
 export interface SkylightQueue {
   writeTexture(
     destination: {
-      texture: unknown;
+      texture: Texture;
       mipLevel?: number;
       origin?: { x: number; y: number; z: number };
     },
@@ -434,7 +434,7 @@ export function createSkylightFallback(
   for (const face of [0, 1, 2, 3, 4, 5]) {
     queue.writeTexture(
       {
-        texture: irradianceTexture as unknown,
+        texture: irradianceTexture,
         mipLevel: 0,
         origin: { x: 0, y: 0, z: face },
       },
@@ -444,7 +444,7 @@ export function createSkylightFallback(
     );
     queue.writeTexture(
       {
-        texture: prefilterTexture as unknown,
+        texture: prefilterTexture,
         mipLevel: 0,
         origin: { x: 0, y: 0, z: face },
       },
@@ -455,7 +455,7 @@ export function createSkylightFallback(
   }
   queue.writeTexture(
     {
-      texture: brdfLutTexture as unknown,
+      texture: brdfLutTexture,
       mipLevel: 0,
       origin: { x: 0, y: 0, z: 0 },
     },

package/src/index.ts

@@ -1,17 +1,23 @@
+// @forgeax/engine-render — AI-facing render vocabulary.
+//
+// The root is deliberately small: ECS render components, grouped closed
+// values, the renderer lifecycle/receipt contract, and the declarative
+// RenderFeature plan. Graph builders, prepared GPU state, pipeline
+// implementations, builtin feature factories, and diagnostic class names are
+// owner-local implementation details.
+
 export {
   materialContribution,
   renderPipelineContribution,
   samplerContribution,
 } from './assets/asset-decoders';
-export type { RenderAssetPort } from './assets/render-asset-port';
-export { Atmosphere } from './components/atmosphere';
-export type { Antialias, CameraProjection, Tonemap } from './components/camera';
+
+// ECS render vocabulary and grouped closed values.
+export type { Antialias, BloomEnabled, CameraProjection, Tonemap } from './components/camera';
 export {
   ANTIALIAS_FXAA,
   ANTIALIAS_MSAA,
   ANTIALIAS_NONE,
-  ANTIALIAS_TAA,
-  antialiasFromF32,
   BLOOM_DISABLED,
   BLOOM_ENABLED,
   CAMERA_PROJECTION_ORTHOGRAPHIC,
@@ -28,18 +34,8 @@ export {
   TONEMAP_NONE,
   TONEMAP_REINHARD,
   TONEMAP_REINHARD_EXTENDED,
-  tonemapFromF32,
-  tonemapToU32,
 } from './components/camera';
 export * from './components/directional-light';
-export {
-  Fog,
-  SKYBOX_MODE_CUBEMAP,
-  SkyboxBackground,
-  type SkyboxMode,
-  Skylight,
-  skyboxModeFromF32,
-} from './components/environment';
 export { Instances, type InstancesData } from './components/instances';
 export { Layer } from './components/layer';
 export * from './components/mesh-filter';
@@ -47,11 +43,13 @@ export * from './components/mesh-renderer';
 export { PointLight } from './components/point-light';
 export { PointLightShadow } from './components/point-light-shadow';
 export { PostProcessParams } from './components/post-process-params';
+export { SceneInstance } from './components/scene-instance';
 export {
-  SceneInstance,
-  type SceneInstanceOverrideRecord,
-  type SceneInstanceState,
-} from './components/scene-instance';
+  SKYBOX_MODE_CUBEMAP,
+  SkyboxBackground,
+  type SkyboxMode,
+} from './components/skybox-background';
+export { Skylight } from './components/skylight';
 export { SortKey } from './components/sort-key';
 export { SpotLight } from './components/spot-light';
 export {
@@ -60,212 +58,55 @@ export {
   VisibilityStateValue,
   visibilityStateFromU32,
 } from './components/visibility';
-export {
-  type AtmosphereSnapshot,
-  type EnvironmentSelectionInput,
-  type ExtractedEnvironment,
-  selectEnvironmentSource,
-} from './environment/extracted-environment';
-export {
-  type EnvironmentInspection,
-  type EnvironmentInspectionInput,
-  type EnvironmentInspectionState,
-  type EnvironmentInspectionTaa,
-  type FogEnvironmentProjectionInput,
-  inspectEnvironmentGeneration,
-  projectFogEnvironment,
-} from './environment/inspection';
-export {
-  type AtmosphereCapsInsufficientDetail,
-  AtmosphereCapsInsufficientError,
-  type AtmosphereCardinalityInvalidDetail,
-  AtmosphereCardinalityInvalidError,
-  type AtmosphereField,
-  type AtmosphereParameterInvalidDetail,
-  AtmosphereParameterInvalidError,
-  type AtmosphereProducerFailedDetail,
-  AtmosphereProducerFailedError,
-  type AtmosphereSunMissingDetail,
-  AtmosphereSunMissingError,
-  type EnvironmentSourceConflictDetail,
-  EnvironmentSourceConflictError,
-  type EquirectProjectionFailedDetail,
-  type FogOwnerConflictDetail,
-  FogOwnerConflictError,
-  type FogParametersInvalidDetail,
-  FogParametersInvalidError,
-  ObservationUnavailableError,
-  type RenderError,
-  type RenderErrorCode,
-  RenderFeatureCapabilityMissingError,
-  RenderFeatureDrawRecordingFailedError,
-  RenderFeaturePassOrderConflictError,
-  RenderFeaturePreparationFailedError,
-  RenderFeaturePreparedStateMismatchError,
-  RenderFeatureRegistrationConflictError,
-  RenderFeatureStageFailedError,
-  type RenderValidationErrorCode,
-  ResourceInvalidValueError,
-  SpawnLightInvalidBoundsError,
-  SpriteInstancesCountMismatchError,
-  SpriteInstancesMutuallyExclusiveWithInstancesError,
-  SpriteInstancesRequiresSpriteShaderError,
-  TaaCapsInsufficientError,
-  TemporalUnsupportedError,
-  type TemporalUnsupportedReason,
-} from './errors/index';
-export { RecoverError, type RecoverErrorCode } from './errors/recover';
+// Public structured operation failure union. Concrete error classes stay
+// behind the Renderer Result/event boundary.
+export type { RenderError, RenderErrorCode } from './errors/render';
 export {
   resolveVisibility,
   type VisibilityResolution,
   type VisibilitySnapshot,
 } from './extract/visibility';
-/**
- * Public producer seam: RenderFeature, its narrow stage contexts, structured
- * diagnostics, graph contribution vocabulary, and prepared graphics facade.
- * This root declaration is the AI-discoverable API authority; host
- * construction details remain under the internal entry.
- */
-export * from './features';
-export {
-  createRenderFeatureTarget,
-  type RenderFeatureTargetHandle,
-  type RenderFeatureTargetInput,
-  type RenderFeatureTargetKind,
-} from './features/targets';
-export { Materials, materialTextureValue } from './materials';
 export type {
-  MeshMaterialBindingDiagnostic,
-  MeshMaterialBindingObservation,
-  MeshMaterialBindingSource,
-  ResolvedMeshMaterialBinding,
-} from './mesh-material-bindings';
-export {
-  type MeshNotResidentDetail,
-  type MeshRangeInvalidDetail,
-  type MeshRangeInvalidReason,
-  type MeshShapeMismatchDetail,
-  MeshUpdateError,
-  type MeshUpdateErrorCode,
-} from './mesh-update-errors';
+  RenderFeatureLogicalTarget,
+  RenderFeaturePassDeclaration,
+  RenderFeaturePlan,
+  RenderFeaturePlanContext,
+  RenderFeatureResourceDeclaration,
+} from './features/plan';
+// Minimal declarative extension contract. Implementations use relative
+// imports; the root does not expose prepared state, graph projectors, target
+// handles, or builtin feature factories.
 export type {
-  PersistentRenderSceneInspection,
-  RenderSceneResyncReason,
-} from './persistent-render-scene';
-export { PipelineError, type PipelineErrorCode } from './pipeline-errors';
-export {
-  ownedRendererPlugin,
-  renderComponentsPlugin,
-  rendererPlugin,
-  renderFeaturePlugin,
-} from './plugin';
-export { PostProcessError, type PostProcessErrorCode } from './post-process-errors';
-export {
-  type FrameObservation,
-  type FrameObservationMetadata,
-  type FrameObservationOptions,
-  type FrameObservationReadback,
-  type FrameObservationSource,
-  observeCurrentFrame,
-} from './record/frame-observation';
-export {
-  // Evidence is producer-owned and fail-closed; acceptedGpu=16 is required for closure.
-  createMembershipTiming,
-  MEMBERSHIP_TIMING_REASON_CODES,
-  MEMBERSHIP_TIMING_REASON_MAPPING,
-  MEMBERSHIP_TIMING_REASON_SCHEMA,
-  type MembershipTimingController,
-  MembershipTimingError,
-  type MembershipTimingGpuOutputSource,
-  type MembershipTimingGpuReport,
-  type MembershipTimingOptions,
-  type MembershipTimingReasonCode,
-  type MembershipTimingReport,
-} from './record/membership-timing';
-export { TONEMAP_POST_PROCESS_ID } from './render-graph-primitives';
-export {
-  type BuiltinEnvironmentPipeline,
-  createEnvironmentPipelineTopology,
-  type RenderColorDomain,
-  type RenderPipeline,
-  type RenderPipelineBuildContext,
-  type RenderPipelineFeatureTarget,
-  type RenderPipelineFrame,
-  type RenderPipelineTopology,
-  resolvePostColorDomainContract,
-  resolveToneOutputContract,
-  type ToneOutputContract,
-} from './render-pipeline';
-export type { RenderPipelineContext } from './render-pipeline-context';
-export {
-  createRenderPipelineTarget,
-  importRenderPipelineSurface,
-  type RenderPipelineTarget,
-} from './render-pipeline-target';
-export type { RenderSceneInspection } from './render-system';
+  RenderFeature,
+  RenderFeatureCapabilityKey,
+  RenderFeatureDiagnostics,
+  RenderFeatureErrorDescriptor,
+  RenderFeatureExtractContext,
+  RenderFeatureHiddenEntityReport,
+  RenderFeatureStatus,
+  RenderFeatureWorldVisibilitySnapshot,
+} from './features/types';
+export { Materials } from './materials';
+// The host-facing default is a stable profile value; implementation-only
+// pipeline helpers remain behind the package boundary.
+export { DEFAULT_STANDARD_PROFILE } from './pipeline/standard-profile';
+export { renderComponentsPlugin } from './plugin';
+// Runtime contract: leases, frame receipts, detached inspection, profile,
+// lifecycle state, and the single renderer event stream.
 export type {
-  DrawOwnerOptions,
-  HealthChangeListener,
-  HealthDetailDeviceLost,
-  HealthDetailInternalFault,
-  HealthReason,
-  HealthSnapshot,
+  FrameCamera,
+  FrameEnvironment,
+  FrameObservationRequest,
+  FrameReceipt,
+  FrameReceiptObservation,
   Renderer,
-  RendererBackend,
-  RendererError,
-  RendererErrorListener,
-  RendererInstallError,
-  RendererLostInfo,
-  RendererLostListener,
+  RendererEvent,
   RendererOptions,
-  RenderPhase,
-  RenderPhaseSkipReason,
+  RendererState,
+  RenderFrameInput,
+  RenderInspection,
+  RenderProfile,
   RenderResult,
-} from './renderer';
-export { RENDER_PHASE_CATALOG } from './renderer';
-export type { RhiBackendInstrumentation } from './renderer/backend-selection';
-export {
-  ACTIVE_CAMERA_KEY,
-  type ActiveCamera,
-  getActiveCamera,
-  setActiveCamera,
-} from './systems/active-camera';
-export type { TaaHistoryInspection, TaaHistoryResetReason } from './taa-history-store';
-export type {
-  TemporalCoverageClass,
-  TemporalCoverageContribution,
-  TemporalCoverageSummary,
-  TemporalMissingReason,
-  TemporalProducerLane,
-  TemporalReactiveReason,
-} from './temporal-coverage';
-export {
-  TEMPORAL_MISSING_REASONS,
-  TEMPORAL_PRODUCER_LANES,
-  TEMPORAL_REACTIVE_REASONS,
-} from './temporal-coverage';
-export type {
-  TemporalFrameTransactionInspection,
-  TemporalHistoryDirection,
-} from './temporal-frame-transaction';
-export type {
-  TemporalInspection,
-  TemporalInspectionCoverage,
-  TemporalInspectionRecovery,
-  TemporalInspectionStatus,
-} from './temporal-inspection';
-export {
-  addTypedBloomPasses,
-  addTypedCompositePostEffects,
-  addTypedFrameObservationPass,
-  addTypedFullscreenPass,
-  addTypedScenePass,
-  addTypedSkyboxPass,
-  addTypedSsaoPasses,
-  addTypedTonemapPass,
-  type TypedBloomTargets,
-  type TypedFullscreenPassOptions,
-  type TypedScenePassOptions,
-  type TypedSsaoTargets,
-} from './typed-render-graph-primitives';
-export { URP_PIPELINE_ID } from './urp-pipeline';
+  RenderWorldLease,
+} from './render-contract';
+export { RENDER_PHASE_CATALOG } from './render-contract';

package/src/inspection-types.ts

@@ -0,0 +1,76 @@
+/**
+ * Renderer-owned inspection PODs. Keeping these projections free of renderer
+ * implementation imports prevents the observation contract from reopening the
+ * extract/record dependency graph.
+ */
+
+export interface BatchTopologyInspection {
+  readonly revision: number;
+  readonly batchCount: number;
+  readonly candidateCount: number;
+  readonly rebuilds: number;
+  readonly patches: number;
+  readonly ineligible: number;
+}
+
+export interface GpuSceneTableInspection {
+  readonly capacity: number;
+  readonly bytes: number;
+}
+
+type GpuSceneTableName = 'primitive' | 'instance' | 'transform' | 'drawTemplate' | 'material';
+
+export interface GpuSceneInspection {
+  readonly capacity: number;
+  readonly tables: Readonly<Record<GpuSceneTableName, GpuSceneTableInspection>>;
+  readonly uploadRanges: number;
+  readonly uploadBytes: number;
+  readonly capacityGrows: number;
+  readonly fullRebuilds: number;
+  readonly clearedSlots: number;
+  readonly noChangeFrames: number;
+}
+
+export interface GpuDrivenProductionInspection {
+  readonly gpuOwnedSnapshotsMaterialized: number;
+  readonly filteredPlanBuilds: number;
+  readonly gpuOwnedEntityCount: number;
+  readonly candidateUploadBytes: number;
+  readonly batchUploadBytes: number;
+  readonly viewConstantsUploadBytes: number;
+  readonly batchBindGroupCreates: number;
+  readonly viewBindGroupCreates: number;
+  readonly topologyRevision: number | undefined;
+  readonly validatedGpuOwnedRows: number;
+  readonly cpuFallbackDrawItems: number;
+}
+
+export type RenderSceneResyncReason =
+  | 'attach'
+  | 'asset-catalog-changed'
+  | 'shared-ref-changed'
+  | 'journal-overflow'
+  | 'unsupported-change'
+  | 'non-rigid-lane'
+  | 'explicit-invalidate';
+
+export interface PersistentRenderSceneInspection {
+  readonly worldEntitiesScanned: number;
+  readonly fullRebuilds: number;
+  readonly noChangeFrames: number;
+  readonly deltaFrames: number;
+  readonly transformUpdates: number;
+  readonly lastResyncReason: RenderSceneResyncReason | undefined;
+  readonly projectionRecords: number;
+  readonly topology: BatchTopologyInspection;
+  readonly gpu:
+    | { readonly status: 'inactive' }
+    | { readonly status: 'unsupported'; readonly reason: 'storage-buffer-unavailable' }
+    | ({ readonly status: 'resident' } & GpuSceneInspection)
+    | { readonly status: 'rebuild-pending' }
+    | { readonly status: 'error' };
+}
+
+export type RenderSceneInspection = PersistentRenderSceneInspection & {
+  readonly gpuDriven: GpuDrivenProductionInspection;
+};

package/src/instance-buffer-cache.ts

@@ -15,34 +15,6 @@
 
 import type { GpuBuffer } from './gpu-resource';
 
-export function temporalInstanceUploadByteLength(
-  current: Float32Array,
-  storageBufferAvailable: boolean,
-): number {
-  return current.byteLength * (storageBufferAvailable ? 2 : 1);
-}
-
-/** Pack current and last-submitted instance transforms into the shared storage ABI. */
-export function packTemporalInstanceTransforms(
-  current: Float32Array,
-  previous: Float32Array | undefined,
-): Float32Array {
-  const instanceCount = Math.trunc(current.length / 16);
-  const packed = new Float32Array(instanceCount * 32);
-  for (let instance = 0; instance < instanceCount; instance += 1) {
-    const sourceOffset = instance * 16;
-    const packedOffset = instance * 32;
-    const currentTransform = current.subarray(sourceOffset, sourceOffset + 16);
-    const previousTransform = previous?.subarray(sourceOffset, sourceOffset + 16);
-    packed.set(currentTransform, packedOffset);
-    packed.set(
-      previousTransform?.length === 16 ? previousTransform : currentTransform,
-      packedOffset + 16,
-    );
-  }
-  return packed;
-}
-
 /**
  * One entry of the per-RenderSystem instance-transform GPU storage cache.
  *
@@ -91,7 +63,7 @@ export interface InstanceBufferCacheErrorSink {
  * runtime did not flip surfaces as the structured 'destroy-after-destroy'
  * RhiError from the shim. That error is *not* re-thrown -- this helper
  * is a sweep that tolerates per-handle failures so the dispose chain can
- * make progress (mirrors `GpuResourceStore.destroyAll`'s policy;
+ * make progress (mirrors `GpuResidencyCache.destroyAll`'s policy;
  * plan-strategy D-3 / D-8).
  *
  * feat-20260619 M4 (D-6): the optional `errorRegistry` parameter unifies

package/src/internal.ts

@@ -1,88 +1,9 @@
 // Non-stable implementation seam for engine-owned consumers and tests.
 
-export type { RenderAssetPort } from './assets/render-asset-port';
-export * from './authoring';
-export * from './cluster-binner';
-export * from './components/camera';
-export * from './components/light-helpers';
-export { createDebugDrawOnReady, releaseDebugDraw } from './debug-draw-glue';
-export { createEngineMetrics } from './engine-metrics';
-export * from './environment/generation';
-export * from './environment/graph';
-export * from './environment/signature';
-export * from './errors/index';
-export * from './errors/recover';
-export * from './extract/schema-readers';
-export * from './features/host';
 export {
-  createRenderFeatureGraphicsPrepare,
-  validateRenderFeatureGraphicsPass,
-} from './features/prepared-graphics';
-export type {
-  RenderFeatureCapabilityMissingDetail,
-  RenderFeatureCleanupFailure,
-  RenderFeatureDrawRecordingFailedDetail,
-  RenderFeatureErrorDetailByCode,
-  RenderFeaturePassOrderConflictDetail,
-  RenderFeaturePreparationFailedDetail,
-  RenderFeaturePreparedStateMismatchDetail,
-  RenderFeatureRegistrationConflictDetail,
-  RenderFeatureStageFailedDetail,
-} from './features/types';
-export * from './fullscreen-post-process-pass';
-export type { GpuResource } from './gpu-resource';
-export { GpuBuffer, GpuTexture } from './gpu-resource';
-export { GpuResourceStore } from './gpu-resource-store';
-export * from './gpu-scene';
-export * from './gpu-scene-schema';
-export * from './hdrp-buffers';
-export * from './hdrp-pipeline';
-export * from './ibl/IblPipelineCache';
-export * from './ibl/skylight-bind-group';
-export * from './index';
-export * from './instance-buffer-cache';
-export * from './lifecycle';
-export * from './light-buffer-layout';
-export * from './mesh-material-bindings';
-export * from './pbr-pipeline';
-export * from './persistent-render-scene';
-export * from './pipeline-builder';
-export * from './pipeline-errors';
-export * from './pipeline-spec';
-export * from './post-process-errors';
-export * from './prepare/schema-readers';
-export * from './record/frame-snapshot';
-export * from './record/frame-targets';
-export * from './record/index';
-export * from './record/main-pass-material';
-export * from './record/membership-timing';
-export * from './record/skybox-post-pass';
-export * from './record/view-ubo';
-export * from './render-data';
-export * from './render-graph-primitives';
-export type { _InternalRenderPipelineContext } from './render-pipeline-context';
-export * from './render-scene-projection';
-export * from './render-system';
-export * from './render-system-extract';
-export * from './render-system-fold';
-export type { EngineEnvironmentErrorDetail } from './renderer/environment-error';
-export { EngineEnvironmentError } from './renderer/environment-error';
-export * from './renderer/renderer-factory';
-export * from './scene-instances/post-spawn-resolve-joints';
-export { collectSubtree } from './scene-utils/collect-subtree';
-export * from './shadow-atlas';
-export * from './ssao-buffers';
-export * from './ssao-config';
-export * from './ssao-data';
-export * from './surface-format';
-export * from './systems/active-camera';
-export * from './systems/pass-selector';
-export * from './systems/skin-palette-allocator';
-export * from './systems/transparent-sort-config';
-export * from './taa-history-store';
-export * from './temporal-coverage';
-export * from './temporal-frame-transaction';
-export * from './temporal-view';
-export * from './tilemap/resolve-tileset-runtime';
-export * from './tilemap-chunk-extract-system';
-export { URP_PIPELINE_ID, urpPipeline } from './urp-pipeline';
+  type ResolvedTilesetRuntime,
+  resolveTilesetRuntime,
+  type TilesetAtlasLookup,
+  type TilesetRuntimeError,
+  type TilesetRuntimeErrorCode,
+} from '@forgeax/engine-assets-runtime';

package/src/lifecycle.ts

@@ -1,24 +1,69 @@
-import type {
-  HealthChangeListener,
-  HealthReason,
-  HealthSnapshot,
-  RendererError,
-  RendererErrorListener,
-  RendererLostInfo,
-  RendererLostListener,
-} from './renderer';
-
-export function deriveRecoverable(reason: HealthReason): boolean {
-  switch (reason) {
-    case 'alive':
-      return false;
-    case 'device-lost':
-      return true;
-    case 'internal-fault':
-      return false;
-  }
+import type { AssetRuntimeError } from '@forgeax/engine-assets-runtime';
+import type { RenderGraphError } from '@forgeax/engine-render-graph';
+import type { RhiError } from '@forgeax/engine-rhi';
+import type { SkinError } from '@forgeax/engine-skinning';
+import type { ImageError } from '@forgeax/engine-types';
+import type { RenderError } from './errors/render';
+import type { PostProcessError } from './post-process-errors';
+
+export interface RendererLostInfo {
+  readonly reason: string;
+  readonly message: string;
+}
+
+export type RendererLostListener = (info: RendererLostInfo) => void;
+
+export type RendererError =
+  | RhiError
+  | RenderGraphError
+  | ImageError
+  | RenderError
+  | AssetRuntimeError
+  | SkinError
+  | PostProcessError;
+
+export type RendererErrorListener = (error: RendererError) => void;
+
+export type HealthReason = 'alive' | 'device-lost' | 'internal-fault';
+
+export interface HealthDetailDeviceLost {
+  readonly lostReason: 'unknown' | 'destroyed';
+  readonly message: string;
 }
 
+export interface HealthDetailInternalFault {
+  readonly message: string;
+}
+
+export type HealthSnapshot =
+  | { readonly reason: 'alive'; readonly recoverable: boolean }
+  | {
+      readonly reason: 'device-lost';
+      readonly detail: HealthDetailDeviceLost;
+      readonly recoverable: boolean;
+    }
+  | {
+      readonly reason: 'internal-fault';
+      readonly detail: HealthDetailInternalFault;
+      readonly recoverable: boolean;
+    };
+
+export type HealthChangeListener = (snapshot: HealthSnapshot) => void;
+
+export {
+  DEVICE_RESOURCE_KINDS,
+  type DeviceResourceKind,
+  DeviceResourceRef,
+  DeviceScope,
+  type DeviceScopeReceipt,
+  type DeviceScopeState,
+  type LifecycleFailure,
+  type LifecycleResourceSpec,
+  type LifecycleResult,
+  LifecycleTransaction,
+  type ResourceRef,
+} from './device/device-scope';
+
 export class LostListenerRegistry {
   private readonly listeners = new Set<RendererLostListener>();
   private fired = false;