@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/dist/render-contract.d.ts

@@ -0,0 +1,424 @@
+import type { AssetRuntimeError } from '@forgeax/engine-assets-runtime';
+import type { World } from '@forgeax/engine-ecs';
+import type { RenderReadLease } from '@forgeax/engine-ecs/projection';
+import type { Vec3 } from '@forgeax/engine-math';
+import type { ProfileFrameToken, Profiler } from '@forgeax/engine-profiler';
+import type { RenderGraphError } from '@forgeax/engine-render-graph';
+import type { BindGroupLayout, Buffer, Result, RhiCaps, RhiCommandEncoder, RhiDevice, RhiError, RhiInstance, RhiRenderPassEncoder, RenderPipeline as RhiRenderPipeline, Texture, TextureFormat, TextureView } from '@forgeax/engine-rhi';
+import type { SkinError } from '@forgeax/engine-skinning';
+import type { ImageError } from '@forgeax/engine-types';
+import type { RhiBackendInstrumentation } from './assembly/backend-contract';
+import type { Antialias, BloomEnabled, Tonemap } from './components/camera';
+import type { RenderError } from './errors/render';
+import type { RenderFeature, RenderFeatureDiagnostics } from './features/types';
+import type { PostProcessShaderEntry } from './fullscreen-post-process-pass';
+import type { RenderSceneInspection } from './inspection-types';
+export type { PointsLinesInspection } from './points-lines/inspection';
+import type { MeshMaterialBindingObservation } from './mesh-material-bindings';
+import type { StandardProfile } from './pipeline/standard-profile';
+import type { PostProcessError } from './post-process-errors';
+export type RenderResult<T, E> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+/** The only World data boundary accepted by the M6 renderer contract. */
+export type RenderWorldLease = RenderReadLease;
+/**
+ * Camera facts shared by extract, record, and scene owners.
+ *
+ * The extract stage resolves ECS camera state once and publishes this closed
+ * POD contract. Keeping it beside the render lifecycle contracts prevents
+ * extract from depending on the record implementation owner.
+ */
+export interface CameraSnapshot {
+    /** Stable ECS identity used by the frame plan's camera authority fact. */
+    readonly entityKey?: number;
+    /** World-space camera translation (mat4.getTranslation of Transform.world). */
+    readonly position: Vec3;
+    /** Resolved world-space camera mat4, copied from Transform.world. */
+    readonly world: Float32Array;
+    readonly fov: number;
+    readonly aspect: number;
+    readonly near: number;
+    readonly far: number;
+    /** Camera projection variant used by view and shadow matrix builders. */
+    readonly projection: 'perspective' | 'orthographic';
+    readonly orthoLeft: number;
+    readonly orthoRight: number;
+    readonly orthoBottom: number;
+    readonly orthoTop: number;
+    readonly tonemap: Tonemap;
+    readonly exposure: number;
+    readonly whitePoint: number;
+    readonly antialias: Antialias;
+    readonly bloom: BloomEnabled;
+    readonly bloomThreshold: number;
+    readonly bloomIntensity: number;
+    readonly bloomBlurRadius: number;
+    readonly clearColor: readonly [number, number, number, number];
+}
+/** Stable identity owned by the Standard feature host for built-in tonemap. */
+export declare const STANDARD_TONEMAP_FEATURE_ID = "forgeax::standard::tonemap";
+/**
+ * Render-graph state exposed to pipeline declarations. Concrete pipeline
+ * caches stay in the assembly owner; graph code only needs the two target
+ * formats that affect fullscreen descriptors.
+ */
+interface RenderPipelineStateView {
+    readonly format: TextureFormat;
+    readonly colorAttachmentFormat: TextureFormat;
+}
+/**
+ * Narrow runtime capability consumed by typed graph primitives. The concrete
+ * RenderSystemRuntime structurally satisfies this contract, but the public
+ * frame surface does not depend on that assembly owner.
+ */
+interface RenderPipelineRuntime {
+    readonly device: RhiDevice;
+    readonly errorRegistry: {
+        fire(error: RendererError): void;
+    };
+    readonly debugOverlay?: RenderDebugOverlay | undefined;
+    readonly lookupPostProcess?: (id: string) => PostProcessShaderEntry | undefined;
+    readonly getPostProcessParamsBuffer?: (id: string) => Buffer | undefined;
+    readonly getPostProcessPipeline?: (id: string, bgl: BindGroupLayout, colorFormat: GPUTextureFormat) => RhiRenderPipeline | null;
+}
+/**
+ * Render-owned declaration for an app-provided debug overlay. App owns the
+ * concrete DebugDraw instance and its GPU lifecycle; Render only records this
+ * capability in the typed graph.
+ */
+export interface RenderDebugOverlay {
+    encode(pass: RhiRenderPassEncoder, viewProj: import('@forgeax/engine-math').Mat4): Result<void, unknown>;
+}
+/**
+ * The leaf frame context consumed by RenderPipeline and graph primitives.
+ * Concrete assembly data is added only by the internal record extension in
+ * render-system.ts, so this contract never imports the RenderSystem owner.
+ */
+export interface RenderPipelineContext {
+    readonly pipelineState: RenderPipelineStateView;
+    readonly runtime: RenderPipelineRuntime;
+    readonly encoder: RhiCommandEncoder;
+    readonly view: TextureView;
+    readonly clear: readonly [number, number, number, number] | number[];
+    readonly targetW: number;
+    readonly targetH: number;
+    readonly currentTexture: Texture;
+    readonly camera: CameraSnapshot;
+    /** Per-frame post-process parameter bytes keyed by shader id. */
+    readonly postProcessParams: ReadonlyMap<string, Uint8Array>;
+    readonly msaaActive: boolean;
+    readonly geometryColorResolveView: TextureView | null;
+    readonly ldrSpriteColorView: TextureView | null;
+}
+/**
+ * The sole public renderer contract. Concrete assembly stays behind the host;
+ * callers retain only leases, receipts, inspection PODs, and recovery Result.
+ */
+export interface Renderer {
+    attach(world: World): RenderResult<RenderWorldLease, RenderError>;
+    draw(input: RenderFrameInput): RenderResult<FrameReceipt, RenderError>;
+    setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
+    state(): RendererState;
+    inspect(): RenderInspection;
+    observe(receipt: FrameReceipt, request: FrameObservationRequest): Promise<RenderResult<FrameReceiptObservation, RenderError>>;
+    subscribe(listener: (event: RendererEvent) => void): () => void;
+    releaseSurface(): RenderResult<void, RenderError>;
+    restoreSurface(): RenderResult<void, RenderError>;
+    recover(): Promise<RenderResult<void, RenderError>>;
+    dispose(): Promise<RenderResult<void, RenderError>>;
+}
+/** The single public renderer lifecycle authority. */
+export type RendererState = 'alive' | 'device-lost' | 'recovering' | 'faulted' | 'disposed';
+/** Immutable, inspectable quality and budget policy for the Standard pipeline. */
+export type RenderProfile = StandardProfile;
+/** Ordered events projected from renderer state and expected-operation failures. */
+export type RendererEvent = {
+    readonly kind: 'state-changed';
+    readonly previous: RendererState;
+    readonly current: RendererState;
+} | {
+    readonly kind: 'error';
+    readonly error: RenderError;
+}
+/** Emitted only after the renderer's sole submit path returns a receipt. */
+ | {
+    readonly kind: 'frame-submitted';
+    readonly frameId: number;
+    readonly deviceGeneration: number;
+};
+/** Package-local listener alias used by the renderer assembly implementation. */
+export type RendererEventListener = (event: RendererEvent) => void;
+/**
+ * Camera authority supplied for one frame; Render owns the lease contract and
+ * the host releases it with the frame lifecycle. It is intentionally bound to
+ * the attached scene lease and never accepts a backend object.
+ */
+export interface FrameCamera {
+    readonly lease: RenderWorldLease;
+    readonly entityKey?: number;
+}
+/**
+ * Environment authority supplied for one frame. The scene/environment owner
+ * supplies the identity; the host validates it against the attached lease.
+ */
+export interface FrameEnvironment {
+    readonly lease: RenderWorldLease;
+    readonly identity?: string;
+}
+/**
+ * Receipt-bound observation selection. The request is consumed by `observe`
+ * only with the matching FrameReceipt and returns a structured Result error
+ * when the generation or frame identity is stale.
+ */
+export interface FrameObservationRequest {
+    readonly include: readonly ('timings' | 'draws' | 'bindings')[];
+}
+/**
+ * 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.
+ */
+export interface FrameReceipt {
+    readonly frameId: number;
+    readonly deviceGeneration: number;
+    readonly completed: Promise<RenderResult<void, RenderError>>;
+}
+/**
+ * The sole public draw input; World objects never cross this boundary. Render
+ * owns extraction and graph interpretation, while the host owns encoding,
+ * finish, submit, and recovery of the attached lease generation.
+ */
+export interface RenderFrameInput {
+    readonly leases: readonly RenderWorldLease[];
+    readonly camera: FrameCamera;
+    readonly environment: FrameEnvironment;
+    /** Optional profiler correlation token owned by App and consumed by Render. */
+    readonly profileFrame?: ProfileFrameToken;
+}
+/** Detached, bounded observation metadata tied to one FrameReceipt and request. */
+export interface FrameReceiptObservation {
+    readonly frameId: number;
+    readonly deviceGeneration: number;
+    readonly include: readonly ('timings' | 'draws' | 'bindings')[];
+}
+/**
+ * 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.
+ */
+export interface RenderInspection {
+    readonly state: RendererState;
+    readonly surface: 'available' | 'released';
+    readonly profile: RenderProfile;
+    readonly capabilities: Readonly<RhiCaps>;
+    readonly frame: {
+        readonly frameId: number;
+        readonly deviceGeneration: number;
+    };
+    readonly features: readonly string[];
+    /** Truthful lifecycle facts for every registered declarative feature. */
+    readonly featureDiagnostics: readonly RenderFeatureDiagnostics[];
+    readonly frustumStats: {
+        readonly culled: number;
+        readonly total: number;
+    };
+    readonly visibilityStats: {
+        readonly explicitlyHidden: number;
+    };
+    readonly renderScene: RenderSceneInspection;
+    readonly meshMaterialBindings: readonly MeshMaterialBindingObservation[];
+    readonly perFramePassNames: readonly string[];
+    readonly bindGroupCounts: {
+        readonly createBindGroup: number;
+        readonly keys: readonly string[];
+    };
+}
+/** Backend marker — single-element union preserved for future extensibility (D-2). */
+/**
+ * `renderer.draw(worlds, options)` owner options
+ * (feat-20260709-editor-world-partition M1 / w6, plan-strategy §2 D-3).
+ *
+ * The single `owner` index that previously served BOTH the surfaced cameras
+ * and the singleton render resources (skylight / skybox / postProcessParams) is
+ * split into two independent indices:
+ *   - `cameraOwner`   — the world whose cameras are surfaced.
+ *   - `resourceOwner` — the world whose skylight / skybox / postProcessParams
+ *                       are surfaced.
+ *
+ * Both owners are always explicit. Single-world callers pass zero for both;
+ * composite callers may select different worlds.
+ */
+export type DrawOwnerOptions = {
+    readonly cameraOwner: number;
+    readonly resourceOwner: number;
+    readonly profileFrame?: ProfileFrameToken;
+};
+/** Information attached to a device-loss notification. */
+export interface RendererLostInfo {
+    /** Concise machine-readable cause, mapped to a single vocabulary. */
+    reason: string;
+    /** Free-form description (UA / extension / driver text). */
+    message: string;
+}
+/** Listener registered through `Renderer.onLost`. */
+export type RendererLostListener = (info: RendererLostInfo) => void;
+/**
+ * Composite error type retained for package-local renderer diagnostics. The
+ * public Renderer projects expected operation failures through the single
+ * `subscribe` event stream and its `error` event; this type does NOT define a
+ * error; it only references the cluster unions whose members can arrive here.
+ * As such it is an external wire alias (AGENTS.md Change stance add-only wire
+ * exception), NOT the eliminated cross-cluster `RuntimeError` SSOT (D-3).
+ *
+ * Composition = `RhiError | RenderError | AssetRuntimeError | SkinError |
+ * PostProcessError`. This equals the pre-decomposition
+ * `RhiError | RuntimeError | PostProcessError` exactly: `RuntimeError` was
+ * `RenderError | AssetRuntimeError | SkinError` (27 classes). `RecoverError`
+ * and `EngineEnvironmentError` are intentionally excluded — neither is ever
+ * emitted through the Renderer event stream (`RecoverError` returns from `recover()`,
+ * `EngineEnvironmentError` throws at construction), matching the original
+ * `RuntimeError` union which excluded both (OOS-3 behavior equivalence).
+ *
+ * AI consumers do `switch (err.code)` over the union: the disjoint
+ * `RhiErrorCode` / `RenderErrorCode` / `AssetRuntimeErrorCode` / `SkinErrorCode`
+ * / `PostProcessErrorCode` literal sets let TS narrow each arm to the concrete
+ * class (charter P3 union discoverability — every fan-out member is reachable
+ * in an exhaustive switch, no untyped escape). Example:
+ *
+ * ```ts
+ * renderer.subscribe((event) => {
+ *   if (event.kind !== 'error') return;
+ *   switch (event.error.code) {
+ *     case 'asset-not-registered': // AssetRuntimeError arm, err narrowed here
+ *       return report(err.hint);
+ *     // ...one arm per RhiErrorCode | RenderErrorCode | AssetRuntimeErrorCode
+ *     //    | SkinErrorCode | PostProcessErrorCode member; no default needed,
+ *     //    TS flags every unhandled code at compile time.
+ *   }
+ * });
+ * ```
+ */
+export type RendererError = RhiError | RenderGraphError | ImageError | RenderError | AssetRuntimeError | SkinError | PostProcessError;
+/**
+ * Package-local error listener retained for host assembly. Public consumers
+ * use `Renderer.subscribe` and receive `RendererEvent` instead.
+ */
+export type RendererErrorListener = (error: RendererError) => void;
+/**
+ * Built-in graph pass owners used as nested children of `record/graph-execute`.
+ * Unknown extension pass names use the explicit `other` bucket so custom
+ * pipelines retain a bounded catalog while the default render workload gets
+ * actionable owner attribution.
+ */
+export declare const RENDER_GRAPH_EXECUTION_PHASE_CATALOG: readonly ["record/graph-execute/point-shadow", "record/graph-execute/cluster-binner-upload", "record/graph-execute/g-buffer", "record/graph-execute/g-buffer/geometry-loop", "record/graph-execute/g-buffer/material-bind-groups", "record/graph-execute/g-buffer/pipeline-selection", "record/graph-execute/g-buffer/draw-submit", "record/graph-execute/ssao-calc", "record/graph-execute/ssao-blur", "record/graph-execute/lighting", "record/graph-execute/forward", "record/graph-execute/forward/geometry-loop", "record/graph-execute/forward/material-bind-groups", "record/graph-execute/forward/pipeline-selection", "record/graph-execute/forward/draw-submit", "record/graph-execute/tonemap", "record/graph-execute/debug-overlay", "record/graph-execute/shadow", "record/graph-execute/spot-shadow", "record/graph-execute/skybox", "record/graph-execute/main", "record/graph-execute/fxaa", "record/graph-execute/bloom-bright", "record/graph-execute/bloom-blur-h", "record/graph-execute/bloom-blur-v", "record/graph-execute/bloom-composite", "record/graph-execute/other"];
+export type RenderGraphExecutionPhase = (typeof RENDER_GRAPH_EXECUTION_PHASE_CATALOG)[number];
+/** Bounded producer-owned children of the scene-state record owner. */
+export declare const RENDER_HDRP_BINNER_PHASE_CATALOG: readonly ["record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/light-aabb", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/cluster-occupancy", "record/scene-state/hdrp-cluster/binner/cluster-reserve", "record/scene-state/hdrp-cluster/binner/input-preparation", "record/scene-state/hdrp-cluster/binner/bin-core", "record/scene-state/hdrp-cluster/binner/light-index-write", "record/scene-state/hdrp-cluster/binner/light-index-write/bounds-read", "record/scene-state/hdrp-cluster/binner/light-index-write/cluster-write"];
+export declare const RENDER_HDRP_CLUSTER_PHASE_CATALOG: readonly ["record/scene-state/hdrp-cluster/binner", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/light-aabb", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/cluster-occupancy", "record/scene-state/hdrp-cluster/binner/cluster-reserve", "record/scene-state/hdrp-cluster/binner/input-preparation", "record/scene-state/hdrp-cluster/binner/bin-core", "record/scene-state/hdrp-cluster/binner/light-index-write", "record/scene-state/hdrp-cluster/binner/light-index-write/bounds-read", "record/scene-state/hdrp-cluster/binner/light-index-write/cluster-write", "record/scene-state/hdrp-cluster/payload-packing", "record/scene-state/hdrp-cluster/buffer-upload"];
+export type RenderHdrpClusterPhase = (typeof RENDER_HDRP_CLUSTER_PHASE_CATALOG)[number];
+export declare const RENDER_SCENE_STATE_PHASE_CATALOG: readonly ["record/scene-state/fold-buckets", "record/scene-state/lighting-prep", "record/scene-state/ambient-resolution", "record/scene-state/directional-shadow-cache", "record/scene-state/hdrp-cluster", "record/scene-state/hdrp-cluster/binner", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/light-aabb", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/cluster-occupancy", "record/scene-state/hdrp-cluster/binner/cluster-reserve", "record/scene-state/hdrp-cluster/binner/input-preparation", "record/scene-state/hdrp-cluster/binner/bin-core", "record/scene-state/hdrp-cluster/binner/light-index-write", "record/scene-state/hdrp-cluster/binner/light-index-write/bounds-read", "record/scene-state/hdrp-cluster/binner/light-index-write/cluster-write", "record/scene-state/hdrp-cluster/payload-packing", "record/scene-state/hdrp-cluster/buffer-upload"];
+/**
+ * Opt-in boundaries inside one `Renderer.draw` call. The observer is a
+ * diagnostics seam only: it receives wall-time boundaries and must never be
+ * required for rendering correctness. The stage names mirror the existing
+ * engine-owned Extract / Prepare / Record orchestration so a host can measure
+ * attribution without guessing from RHI command counts.
+ */
+export declare const RENDER_RECORD_PHASE_CATALOG: readonly ["record/scene-state", "record/scene-state/fold-buckets", "record/scene-state/lighting-prep", "record/scene-state/ambient-resolution", "record/scene-state/directional-shadow-cache", "record/scene-state/hdrp-cluster", "record/scene-state/hdrp-cluster/binner", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/light-aabb", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/cluster-occupancy", "record/scene-state/hdrp-cluster/binner/cluster-reserve", "record/scene-state/hdrp-cluster/binner/input-preparation", "record/scene-state/hdrp-cluster/binner/bin-core", "record/scene-state/hdrp-cluster/binner/light-index-write", "record/scene-state/hdrp-cluster/binner/light-index-write/bounds-read", "record/scene-state/hdrp-cluster/binner/light-index-write/cluster-write", "record/scene-state/hdrp-cluster/payload-packing", "record/scene-state/hdrp-cluster/buffer-upload", "record/swapchain", "record/render-graph", "record/target-views", "record/validation", "record/dispatch-plan", "record/uploads", "record/bind-groups", "record/graph-execute", "record/graph-execute/point-shadow", "record/graph-execute/cluster-binner-upload", "record/graph-execute/g-buffer", "record/graph-execute/g-buffer/geometry-loop", "record/graph-execute/g-buffer/material-bind-groups", "record/graph-execute/g-buffer/pipeline-selection", "record/graph-execute/g-buffer/draw-submit", "record/graph-execute/ssao-calc", "record/graph-execute/ssao-blur", "record/graph-execute/lighting", "record/graph-execute/forward", "record/graph-execute/forward/geometry-loop", "record/graph-execute/forward/material-bind-groups", "record/graph-execute/forward/pipeline-selection", "record/graph-execute/forward/draw-submit", "record/graph-execute/tonemap", "record/graph-execute/debug-overlay", "record/graph-execute/shadow", "record/graph-execute/spot-shadow", "record/graph-execute/skybox", "record/graph-execute/main", "record/graph-execute/fxaa", "record/graph-execute/bloom-bright", "record/graph-execute/bloom-blur-h", "record/graph-execute/bloom-blur-v", "record/graph-execute/bloom-composite", "record/graph-execute/other"];
+export type RenderRecordPhase = (typeof RENDER_RECORD_PHASE_CATALOG)[number];
+export declare const RENDER_PHASE_CATALOG: readonly ["extract", "bind-groups", "features", "sort", "record", "record/scene-state", "record/scene-state/fold-buckets", "record/scene-state/lighting-prep", "record/scene-state/ambient-resolution", "record/scene-state/directional-shadow-cache", "record/scene-state/hdrp-cluster", "record/scene-state/hdrp-cluster/binner", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/light-aabb", "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/cluster-occupancy", "record/scene-state/hdrp-cluster/binner/cluster-reserve", "record/scene-state/hdrp-cluster/binner/input-preparation", "record/scene-state/hdrp-cluster/binner/bin-core", "record/scene-state/hdrp-cluster/binner/light-index-write", "record/scene-state/hdrp-cluster/binner/light-index-write/bounds-read", "record/scene-state/hdrp-cluster/binner/light-index-write/cluster-write", "record/scene-state/hdrp-cluster/payload-packing", "record/scene-state/hdrp-cluster/buffer-upload", "record/swapchain", "record/render-graph", "record/target-views", "record/validation", "record/dispatch-plan", "record/uploads", "record/bind-groups", "record/graph-execute", "record/graph-execute/point-shadow", "record/graph-execute/cluster-binner-upload", "record/graph-execute/g-buffer", "record/graph-execute/g-buffer/geometry-loop", "record/graph-execute/g-buffer/material-bind-groups", "record/graph-execute/g-buffer/pipeline-selection", "record/graph-execute/g-buffer/draw-submit", "record/graph-execute/ssao-calc", "record/graph-execute/ssao-blur", "record/graph-execute/lighting", "record/graph-execute/forward", "record/graph-execute/forward/geometry-loop", "record/graph-execute/forward/material-bind-groups", "record/graph-execute/forward/pipeline-selection", "record/graph-execute/forward/draw-submit", "record/graph-execute/tonemap", "record/graph-execute/debug-overlay", "record/graph-execute/shadow", "record/graph-execute/spot-shadow", "record/graph-execute/skybox", "record/graph-execute/main", "record/graph-execute/fxaa", "record/graph-execute/bloom-bright", "record/graph-execute/bloom-blur-h", "record/graph-execute/bloom-blur-v", "record/graph-execute/bloom-composite", "record/graph-execute/other"];
+export type RenderPhase = (typeof RENDER_PHASE_CATALOG)[number];
+export type RenderPhaseSkipReason = 'feature-host-unavailable' | 'feature-host-empty' | 'pipeline-state-unavailable' | 'camera-unavailable';
+/** First-version options bag (intentionally empty; reserved for v0.1). */
+export interface RendererOptions {
+    /** Producer-owned features installed by the renderer host. */
+    readonly features?: readonly RenderFeature<unknown>[] | undefined;
+    /** Standard profile consumed by the single renderer-owned pipeline. */
+    readonly standardProfile?: RenderProfile | undefined;
+    /** Explicit profiler capability shared by App and Render. */
+    readonly profiler?: Profiler | undefined;
+    /** Optional host-owned RHI lifecycle instrumentation, such as recording. */
+    readonly rhiInstrumentation?: RhiBackendInstrumentation | undefined;
+    /**
+     * M3 D-P4 escape hatch (feat-20260511-rhi-wgpu-impl): explicit
+     * `RhiInstance` injection bypasses the dynamic-import auto-select
+     * facade. When set, `createRenderer` uses this instance verbatim and
+     * neither concrete backend adapter is imported dynamically (charter
+     * proposition 5 discoverable opt-in /
+     * plan-strategy §6 M3 + §7.4 escape hatch + Bevy
+     * `RenderCreation::Manual` partial equivalent).
+     *
+     * Typical use cases:
+     *   - Testing / debugging — inject a deterministic stub.
+     *   - Pinning a specific backend even when the browser adapter is present,
+     *     for cross-shim regression tests.
+     *   - Advanced AI users implementing their own `RhiInstance` shim.
+     *
+     * AI users who want the default behaviour leave this field omitted;
+     * `navigator.gpu` presence/absence drives the dynamic import (see the
+     * `createRenderer` JSDoc for the full auto-select decision tree).
+     */
+    readonly rhi?: RhiInstance | undefined;
+}
+/**
+ * Closed union of renderer health states.
+ *
+ * 3 members per plan-strategy D-1:
+ *   - `'alive'` — healthy baseline (registry not yet fired)
+ *   - `'device-lost'` — device loss detected
+ *   - `'internal-fault'` — internal renderer fault
+ *
+ * AI users exhaustively switch on `HealthReason` without default; TS guards
+ * completeness.
+ */
+export type HealthReason = 'alive' | 'device-lost' | 'internal-fault';
+/** Detail for `HealthReason 'device-lost'`. */
+export interface HealthDetailDeviceLost {
+    readonly lostReason: 'unknown' | 'destroyed';
+    readonly message: string;
+}
+/** Detail for `HealthReason 'internal-fault'`. */
+export interface HealthDetailInternalFault {
+    readonly message: string;
+}
+/**
+ * Pull-style health snapshot — discriminated union by `reason`.
+ *
+ * Per plan-strategy D-2: `switch(snap.reason)` narrows `snap.detail` to the
+ * per-reason detail type automatically, with zero `as` casts. `alive` has no
+ * `.detail` field; `device-lost` / `internal-fault` have a required `.detail`
+ * of the respective variant.
+ *
+ *   - `recoverable` — explicit snapshot data owned by the lifecycle authority
+ */
+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;
+};
+/**
+ * Maps `HealthReason` to recoverable boolean per the derive table
+ * (requirements section "range"):
+ *
+ *   | reason         | recoverable |
+ *   |:---------------|:-----------|
+ *   | `'alive'`      | false       |
+ *   | `'device-lost'`| true        |
+ *   | `'internal-fault'` | false   |
+ */
+/** Callback type for `Renderer.onHealthChange`. */
+export type HealthChangeListener = (snapshot: HealthSnapshot) => void;
+//# sourceMappingURL=render-contract.d.ts.map

package/dist/render-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-contract.d.ts","sourceRoot":"","sources":["../src/render-contract.ts"],"names":[],"mappings":"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"}

package/dist/render-data.d.ts

@@ -0,0 +1,143 @@
+import { type VertexLayoutProjection } from '@forgeax/engine-geometry';
+import { type Result } from '@forgeax/engine-rhi';
+import { type AssetError, type MeshAsset, type Submesh, type TextureAsset } from '@forgeax/engine-types';
+/** Descriptor for a mesh's GPU vertex + index buffers (projected from POD). */
+export interface MeshRenderData {
+    readonly vertexByteLength: number;
+    /** Geometry-owned immutable layout facts used by all GPU consumers. */
+    readonly layoutProjection: VertexLayoutProjection;
+    /** Index byte length padded up to a 4-byte multiple (writeBuffer alignment). */
+    readonly indexByteLength: number;
+    readonly indexCount: number;
+    readonly indexFormat: 'uint16' | 'uint32';
+    readonly vertexUsage: number;
+    readonly indexUsage: number;
+    /**
+     * Submeshes from the source MeshAsset, projected verbatim to the GPU store
+     * so the record stage can iterate per-submesh draw calls (feat-20260608 M4 / w16).
+     * Mirrors MeshAsset.submeshes (readonly Submesh[]) 1:1.
+     */
+    readonly submeshes: readonly Submesh[];
+}
+/** Descriptor for a 2D texture's GPU resource (projected from POD). */
+export interface TextureRenderData {
+    /** Logical width retained for existing projection consumers. */
+    readonly width: number;
+    /** Logical height retained for existing projection consumers. */
+    readonly height: number;
+    /** Authored content extent; TextureAsset remains the logical asset SSOT. */
+    readonly logicalExtent: TextureExtent;
+    /** GPU allocation extent, derived from format + logicalExtent. */
+    readonly physicalExtent: TextureExtent;
+    /** Maps logical UVs away from block padding. */
+    readonly uvScale: readonly [number, number];
+    readonly format: GPUTextureFormat;
+    readonly mipLevelCount: number;
+    readonly usage: number;
+    /**
+     * Row pitch for the BASE mip (level 0) the store passes to `writeTexture`.
+     * Uncompressed: `width * 4` (RGBA8). Block-compressed: the block-padded
+     * `ceil(width / blockW) * bytesPerBlock` (feat-20260707 M5 / w35, AC-08).
+     * The per-mip layout for a multi-level compressed upload comes from
+     * {@link deriveMipUploadLayout}.
+     */
+    readonly bytesPerRow: number;
+    /** True iff `format` is a block-compressed format (drives the store's upload arm). */
+    readonly compressed: boolean;
+}
+export interface TextureExtent {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * The sole logical-content to physical-storage projection for a texture.
+ * Block sizes come from codec's format table; no physical dimensions are
+ * authored or serialized with TextureAsset.
+ */
+export declare function deriveTextureExtent(format: GPUTextureFormat, width: number, height: number): {
+    readonly logicalExtent: TextureExtent;
+    readonly physicalExtent: TextureExtent;
+    readonly uvScale: readonly [number, number];
+};
+/** One mip level's GPU-upload layout (feat-20260707 M5 / w35, AC-08). */
+export interface MipUploadLevel {
+    /** Mip level index (0 = base / largest). */
+    readonly level: number;
+    /** Logical pixel width of this level (`baseWidth >> level`, min 1). */
+    readonly width: number;
+    /** Logical pixel height of this level (`baseHeight >> level`, min 1). */
+    readonly height: number;
+    /** Block-aligned storage dimensions for this logical mip. */
+    readonly physicalWidth: number;
+    readonly physicalHeight: number;
+    /** Logical `writeTexture` copy width; full-subresource copies may end mid-block. */
+    readonly copyWidth: number;
+    /** Logical `writeTexture` copy height; full-subresource copies may end mid-block. */
+    readonly copyHeight: number;
+    /** Bytes per compressed row: `ceil(width / blockW) * bytesPerBlock`. */
+    readonly bytesPerRow: number;
+    /** Block rows: `ceil(height / blockH)` (the writeTexture `rowsPerImage`). */
+    readonly rowsPerImage: number;
+    /** Byte offset of this level in the mip-major payload (sum of prior levels). */
+    readonly byteOffset: number;
+    /** Byte length of this level (`bytesPerRow * rowsPerImage`). */
+    readonly byteLength: number;
+}
+/**
+ * Derive the per-mip GPU-upload layout for a block-compressed texture
+ * (feat-20260707 M5 / w35, AC-08). Each level pads the pixel width up to a full
+ * block (`ceil(width / blockW) * bytesPerBlock`) and counts block rows
+ * (`ceil(height / blockH)`); `byteOffset` accumulates the prior levels' byte
+ * lengths (mip-major layout). The GPU samples only the valid texel region, so a
+ * non-4-multiple size or a 1x1 / 2x2 mip tail pads up to a block without image
+ * corruption (t5). Block math is sourced from the codec block table (SSOT --
+ * Derive, Don't Duplicate); TextureAsset carries no block fields (F-6).
+ *
+ * `format` must be a block-compressed format; callers branch on the projection's
+ * `compressed` flag first (the uncompressed path uses the linear `width * 4`
+ * pitch). Level dimensions floor-halve per mip, clamped to a 1-pixel minimum.
+ */
+export declare function deriveMipUploadLayout(format: GPUTextureFormat, baseWidth: number, baseHeight: number, mipLevelCount: number): readonly MipUploadLevel[];
+/** Descriptor for a cubemap built from an equirect source (projected from POD). */
+export interface CubeRenderData {
+    /** Square cube face edge length (== source equirect height). */
+    readonly cubeFaceSize: number;
+    /** Filterable output format the IBL pipeline BGL expects. */
+    readonly outputFormat: 'rgba16float';
+    /** True when the source is rgba32float and the store must pack to rgba16float. */
+    readonly needsHalfConversion: boolean;
+    readonly cubeUsage: number;
+}
+/**
+ * Project a `MeshAsset` POD into its GPU vertex / index buffer descriptor.
+ * Pure: computes byte lengths, the 4-byte-aligned index size, index format,
+ * and the buffer usage flags the store's `createBuffer` calls need.
+ */
+export declare function deriveRenderDataMesh(mesh: MeshAsset): Result<MeshRenderData, AssetError>;
+/**
+ * Project a `TextureAsset` POD into its GPU texture descriptor. Pure: derives
+ * the mip-level count (when `mipmap`), the row pitch, and the usage flags, and
+ * fails fast if the POD's `format` and `colorSpace` are internally
+ * inconsistent (a `-srgb` format requires an `srgb` colorSpace and vice versa).
+ */
+export declare function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRenderData, AssetError>;
+/**
+ * Project an equirectangular HDR `TextureAsset` source into its cubemap
+ * descriptor. Pure: validates the source is a linear HDR format, computes the
+ * square cube face size (== source height), narrows the output to the filterable
+ * `rgba16float` the IBL pipeline expects, and flags whether the store must pack
+ * an rgba32float source down to rgba16float. The store keeps the resource build
+ * (createTexture / cube + face views / IBL precompute) and the rgba32f->rgba16f
+ * byte conversion.
+ *
+ * feat-20260707 M5 fix: the accepted-format whitelist is `rgba16float |
+ * rgba32float` only -- a block-compressed HDR format (`bc6h-rgb-ufloat`) is NOT
+ * accepted here. An equirect cube source drives equirect-to-cube / irradiance /
+ * prefilter RENDER passes, and a BC6H texture is sample-only, never a color-
+ * renderable render target ("BC6HRGBUfloat is not color renderable"). The
+ * equirect is therefore always delivered uncompressed rgba16float; this
+ * fail-fast whitelist is the projection-layer guard that rejects a non-
+ * renderable cube source rather than letting it blow up at GPU createTexture.
+ */
+export declare function deriveRenderDataCubemap(source: TextureAsset): Result<CubeRenderData, AssetError>;
+//# sourceMappingURL=render-data.d.ts.map

package/dist/render-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-data.d.ts","sourceRoot":"","sources":["../src/render-data.ts"],"names":[],"mappings":"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"}