@forgeax/engine-render 0.1.2

package/src/index.ts

@@ -0,0 +1,271 @@
+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';
+export {
+  ANTIALIAS_FXAA,
+  ANTIALIAS_MSAA,
+  ANTIALIAS_NONE,
+  ANTIALIAS_TAA,
+  antialiasFromF32,
+  BLOOM_DISABLED,
+  BLOOM_ENABLED,
+  CAMERA_PROJECTION_ORTHOGRAPHIC,
+  CAMERA_PROJECTION_PERSPECTIVE,
+  Camera,
+  cameraProjectionFromF32,
+  orthographic,
+  perspective,
+  TONEMAP_ACES_FILMIC,
+  TONEMAP_AGX,
+  TONEMAP_CINEON,
+  TONEMAP_LINEAR,
+  TONEMAP_NEUTRAL,
+  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';
+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,
+  type SceneInstanceOverrideRecord,
+  type SceneInstanceState,
+} from './components/scene-instance';
+export { SortKey } from './components/sort-key';
+export { SpotLight } from './components/spot-light';
+export {
+  Visibility,
+  type VisibilityState,
+  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';
+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';
+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';
+export type {
+  DrawOwnerOptions,
+  HealthChangeListener,
+  HealthDetailDeviceLost,
+  HealthDetailInternalFault,
+  HealthReason,
+  HealthSnapshot,
+  Renderer,
+  RendererBackend,
+  RendererError,
+  RendererErrorListener,
+  RendererInstallError,
+  RendererLostInfo,
+  RendererLostListener,
+  RendererOptions,
+  RenderPhase,
+  RenderPhaseSkipReason,
+  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';

package/src/instance-buffer-cache.ts

@@ -0,0 +1,123 @@
+// @forgeax/engine-runtime / instance-buffer-cache
+//
+// feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle / M-4 / w16.
+//
+// SSOT for the per-RenderSystem instance-transform GPU storage cache:
+//   - the cache entry shape (buffer + uploaded bookkeeping fingerprints)
+//   - the dispose-path walk that releases every entry's GpuBuffer
+//
+// Moved out of render-system-record.ts so the entry shape stays
+// independent of the record pipeline (architecture-principles §4 pipeline
+// isolation: a cache structure that 4+ consumers share is decoupled from
+// the consumer that records frames). Per-frame Map.delete cleanup keeps
+// its existing semantics inline at the record stage (plan-strategy D-7
+// + OOS-11: dispose path is the new branch, per-frame stays as-is).
+
+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.
+ *
+ * The `buffer` field is a `GpuBuffer` wrapper (feat-20260612 M-2/M-3): it
+ * holds the raw RHI handle, owns the lifecycle (`destroy()` + `isDestroyed`)
+ * and routes dispose through the RHI shim's destroy bookkeeping SSOT. The
+ * two `uploaded*` fields are the cache invalidation fingerprint -- when the
+ * archetype version bumps or the byte length changes, the record stage
+ * allocates a fresh GpuBuffer and replaces the entry.
+ */
+export interface InstanceBufferCacheEntry {
+  readonly buffer: GpuBuffer;
+  readonly uploadedByteLength: number;
+  readonly uploadedArchVersion: number;
+}
+
+function destroyInstanceBufferEntries(
+  entries: Iterable<InstanceBufferCacheEntry>,
+  errorRegistry?: InstanceBufferCacheErrorSink,
+): void {
+  for (const entry of entries) {
+    if (entry.buffer.isDestroyed) continue;
+    const r = entry.buffer.destroy();
+    if (!r.ok && errorRegistry) errorRegistry.fire(r.error);
+  }
+}
+
+/**
+ * Minimal error-registry surface accepted by disposeInstanceBuffers —
+ * only needs `fire`, matching RhiErrorListenerRegistry (feat-20260619 D-6).
+ */
+export interface InstanceBufferCacheErrorSink {
+  fire(e: { code: string }): void;
+}
+
+/**
+ * Walk an instance-buffer cache Map, destroy every entry's GpuBuffer, then
+ * clear the Map. Called from `Renderer.dispose()` (M-5) as the per-frame
+ * instance-buffer release step in the dispose chain
+ * (plan-strategy D-2: gpuStore.destroyAll -> graph.drain ->
+ * frameState.instanceBuffers cleanup -> ...).
+ *
+ * Idempotent (architecture-principles §6): a second call after the Map was
+ * cleared is a no-op. Each `.destroy()` routes through the RHI shim's
+ * per-handle bookkeeping; a stray second-destroy on a handle that the
+ * 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;
+ * plan-strategy D-3 / D-8).
+ *
+ * feat-20260619 M4 (D-6): the optional `errorRegistry` parameter unifies
+ * the dispose path with the per-frame path — destroy failures fire
+ * errorRegistry + sweep continues. Callers that lack an error registry
+ * (unit tests of the helper itself) omit the parameter safely.
+ *
+ * Per-frame Map.delete cleanup at the record stage keeps its existing
+ * 'just delete the key' semantics (plan-strategy D-7 + OOS-11): the
+ * per-frame path bumps fingerprints when the archetype version changes,
+ * letting the next record stage replace the entry; only the dispose
+ * exit path walks-then-destroys.
+ */
+export function disposeInstanceBuffers(
+  map: Map<number, InstanceBufferCacheEntry>,
+  errorRegistry?: InstanceBufferCacheErrorSink,
+): void {
+  destroyInstanceBufferEntries(map.values(), errorRegistry);
+  map.clear();
+}
+
+/** Destroy transient uniform-fallback chunks allocated for the previous frame. */
+export function disposeTransientInstanceBuffers(
+  entries: InstanceBufferCacheEntry[],
+  errorRegistry?: InstanceBufferCacheErrorSink,
+): void {
+  destroyInstanceBufferEntries(entries, errorRegistry);
+  entries.length = 0;
+}

package/src/internal.ts

@@ -0,0 +1,88 @@
+// 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';

package/src/lifecycle.ts

@@ -0,0 +1,123 @@
+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;
+  }
+}
+
+export class LostListenerRegistry {
+  private readonly listeners = new Set<RendererLostListener>();
+  private fired = false;
+  private lastInfo: RendererLostInfo | null = null;
+
+  add(listener: RendererLostListener): () => void {
+    this.listeners.add(listener);
+    if (this.fired && this.lastInfo) listener(this.lastInfo);
+    return () => this.listeners.delete(listener);
+  }
+
+  fire(info: RendererLostInfo): void {
+    this.fired = true;
+    this.lastInfo = info;
+    for (const listener of this.listeners) listener(info);
+  }
+
+  clear(): void {
+    this.listeners.clear();
+  }
+}
+
+export class RhiErrorListenerRegistry {
+  private readonly listeners: RendererErrorListener[] = [];
+  private fired = false;
+  private lastError: RendererError | null = null;
+
+  add(listener: RendererErrorListener): () => void {
+    this.listeners.push(listener);
+    if (this.fired && this.lastError) {
+      try {
+        listener(this.lastError);
+      } catch (error) {
+        console.error('[RhiErrorListenerRegistry] late-attach listener threw:', error);
+      }
+    }
+    return () => {
+      const index = this.listeners.indexOf(listener);
+      if (index >= 0) this.listeners.splice(index, 1);
+    };
+  }
+
+  fire(error: RendererError): void {
+    this.fired = true;
+    this.lastError = error;
+    if (this.listeners.length === 0) {
+      console.error(`[RhiError ${error.code}] expected: ${error.expected}; hint: ${error.hint}`);
+      return;
+    }
+    for (const listener of this.listeners) {
+      try {
+        listener(error);
+      } catch (cause) {
+        console.error('[RhiErrorListenerRegistry] listener threw:', cause);
+      }
+    }
+  }
+
+  clear(): void {
+    this.listeners.length = 0;
+  }
+}
+
+export class HealthListenerRegistry {
+  private readonly listeners = new Set<HealthChangeListener>();
+  private fired = false;
+  private lastSnapshot: HealthSnapshot | null = null;
+
+  add(listener: HealthChangeListener): () => void {
+    this.listeners.add(listener);
+    if (this.fired && this.lastSnapshot) {
+      try {
+        listener(this.lastSnapshot);
+      } catch (error) {
+        console.error('[HealthListenerRegistry] late-attach listener threw:', error);
+      }
+    }
+    return () => this.listeners.delete(listener);
+  }
+
+  fire(snapshot: HealthSnapshot): void {
+    this.fired = true;
+    this.lastSnapshot = snapshot;
+    for (const listener of this.listeners) {
+      try {
+        listener(snapshot);
+      } catch (error) {
+        console.error('[HealthListenerRegistry] listener threw:', error);
+      }
+    }
+  }
+
+  clear(): void {
+    this.listeners.clear();
+  }
+
+  getLastSnapshot(): HealthSnapshot {
+    return this.fired && this.lastSnapshot
+      ? this.lastSnapshot
+      : { reason: 'alive', recoverable: false };
+  }
+}