@forgeax/engine-render 0.1.2

package/dist/render-pipeline-context.d.ts

@@ -0,0 +1,289 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { BindGroup, RhiCommandEncoder, Texture, TextureView } from '@forgeax/engine-rhi';
+import type { RenderAssetPort } from './assets/render-asset-port';
+import type { MultiViewProductionSubmission } from './gpu-driven/production-raster';
+import type { GpuResourceStore } from './gpu-resource-store';
+import type { BindGroupCounts, DispatchCounts, MaterialBgAssemblyCacheEntry, RasterItemKey, RenderFrameState, ValidatedRenderable } from './record';
+import type { PipelineState, RenderSystemRuntime } from './render-system';
+import type { CameraSnapshot, DispatchEntry, MaterialSnapshot, SkyboxSnapshot, SkylightSnapshot } from './render-system-extract';
+import type { RenderRecordPhase } from './renderer';
+import type { TemporalFrameAttempt } from './temporal-frame-transaction';
+/**
+ * Narrow runtime-services carrier handed to pipeline pass closures (UE `FRDGBuilder`
+ * analogue, runtime half). The named, minimal replacement for the four
+ * `RenderSystemInternals` members the 9 urp closures genuinely reach: the
+ * GPU `device`, the `errorRegistry` structured-error sink, and the two per-MaterialShader
+ * pipeline-cache / param-schema lookups. Deliberately NOT the full `RenderSystemInternals`
+ * - a pipeline author sees exactly these four services and nothing else (charter P4: a
+ * consistent narrow abstraction over the runtime, not the kitchen-sink).
+ *
+ * SSOT for the member types lives in `render-system.ts` `RenderSystemRuntime`; re-exported
+ * here so a pipeline author importing the ctx type sees the runtime-services shape too.
+ */
+export type { RenderSystemRuntime } from './render-system';
+/**
+ * The clean dependency face each typed render-graph pass consumes. Strictly smaller and strictly named relative to
+ * the former `RecordPassContext`: `internals: RenderSystemInternals` is gone (replaced by
+ * the named `assets` / `store` / `pipelineState` / `runtime` surfaces) and the
+ * 0-consumed `skyboxCount` residual is dropped.
+ *
+ * feat-20260604 M3 / w20 (D-7 breaking direct cut, no deprecation/shim/dual-path):
+ * SIX urp-specific leakage fields are gone from the public surface
+ * (`tonemapActive` / `geometryColorView` / `geometryDepthView` / `skyboxActive` /
+ * `splitLdrSprite` / `ldrSpritePassView`). They were urp-private
+ * post-process gating + RT view selection state that an AI-user-defined custom
+ * pipeline must NOT see — topology branches use `RenderPipelineTopology` and
+ * graph resources use typed handles. The fields persist as an internal extension consumed
+ * by the urp record* closures only (see `_StandardForwardSceneView`
+ * in `render-system-record.ts`).
+ *
+ * The 3 MSAA fields (`msaaActive` / `geometryColorResolveView` /
+ * `ldrSpriteColorView`) are KEPT — MSAA renders are not urp-
+ * specific; any pipeline using a multisampled typed target needs the
+ * resolve targets in scope.
+ *
+ * Two documented groups (UE mental model):
+ *
+ * 1. PER-VIEW INPUTS (UE `FSceneView`) - the stable-per-view render inputs:
+ *    `encoder` / `view` / `clear` / `targetW` / `targetH` / `currentTexture` / `camera`
+ *    / `validated` / `validatedOrdered` / `viewBindGroup` / `meshBindGroup` /
+ *    `frameState` / `dispatchCounts` / `bindGroupCounts` / `skylight` /
+ *    `skylightCount` / `skybox` / `msaaActive` / `geometryColorResolveView` /
+ *    `ldrSpriteColorView`.
+ *
+ * 2. RESOURCE + RUNTIME CARRIERS (UE `FRDGBuilder` + #289 three-layer):
+ *    `assets` (CPU POD) / `store` (GPU residency) / `pipelineState` (prebuilt GPU
+ *    layouts/buffers) / `runtime` (device + errorRegistry + shader-cache lookups).
+ */
+export interface RenderPipelineContext {
+    /** CPU POD registry (#289 layer 1). Pipeline closures read `assets.get<T>(handle)`. */
+    readonly assets: RenderAssetPort;
+    /** GPU residency store (#289 layer 2). `store.ensureResident` + `store.getXxxGpuView`. */
+    readonly store: GpuResourceStore;
+    /** Prebuilt per-RenderSystem GPU layouts / buffers / pipelines (#289 layer 3). */
+    readonly pipelineState: PipelineState;
+    /** Narrow runtime services (device + errorRegistry + shader-cache lookups). */
+    readonly runtime: RenderSystemRuntime;
+    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;
+    readonly validated: readonly ValidatedRenderable[];
+    readonly validatedOrdered: readonly ValidatedRenderable[];
+    readonly viewBindGroup: BindGroup | null;
+    readonly meshBindGroup: BindGroup | null;
+    readonly frameState: RenderFrameState;
+    readonly dispatchCounts: DispatchCounts;
+    readonly bindGroupCounts: BindGroupCounts;
+    readonly skylight: SkylightSnapshot | undefined;
+    readonly skylightCount: number;
+    readonly skybox: SkyboxSnapshot | undefined;
+    /**
+     * Per-frame post-process params snapshot collected from PostProcessParams
+     * entities (D-1: data-driven params channel). Maps shader id to raw
+     * bytes (Uint8Array). dispatchFullscreenPass queries this map per-shader.
+     * Empty when no PostProcessParams entities exist.
+     */
+    readonly postProcessParams: ReadonlyMap<string, Uint8Array>;
+    /**
+     * True when the active camera requests MSAA and the RHI reports a compatible
+     * backend. Derived from `camera.antialias` plus the device capability, never
+     * stored separately (C-9 / D-6). When true the geometry pass writes a count=4
+     * multisample colour target and resolves to a single-sample output; when
+     * false every attachment / pipeline is single-sample (including the
+     * capability-accurate WebGL2 fallback route).
+     */
+    readonly msaaActive: boolean;
+    /**
+     * Single-sample resolve output for the main geometry colour pass when
+     * `msaaActive`. LDR path: the swap-chain srgb view; HDR path: the
+     * `hdrColorResolve` view the tonemap / bloom passes sample. `null` when
+     * `msaaActive` is false (no resolve target -- direct single-sample render).
+     */
+    readonly geometryColorResolveView: TextureView | null;
+    /**
+     * Count=4 multisample view the LDR sprite split sub-pass writes when
+     * `msaaActive && splitLdrSprite`; it resolves to the single-sample
+     * `ldrSpritePassView`. The single-sample view is graph-owned on native
+     * linear-LDR frames and uses raw swap-chain storage on the fallback path.
+     * `null` when `msaaActive` is false. (F-1)
+     */
+    readonly ldrSpriteColorView: TextureView | null;
+}
+/**
+ * @internal — package-private extension consumed by urp record*
+ * closures only. NOT exported from the runtime barrel; AI-user-defined custom
+ * pipelines see the public `RenderPipelineContext` shape only (D-7).
+ *
+ * The six fields here used to live on the public `RenderPipelineContext` until
+ * w20 narrowed it. They carry the urp post-process gating +
+ * geometry RT view selection state the record* closures depend on:
+ *
+ * - `tonemapActive`: HDR -> LDR tonemap branch.
+ * - `geometryColorView`/`geometryDepthView`: pre-resolved RT views the main
+ *   pass writes (HDR-or-swap-chain colour, per-pass-or-HDR depth). After M3
+ *   these come from the graph (resolve(name) in execute closure), so a
+ *   future-pure addScenePass closure would receive them via resolve().
+ * - `skyboxActive`: gates the recordSkyboxPass body.
+ * - `splitLdrSprite`: gates the LDR sprite split sub-pass within recordMainPass
+ *   / recordTonemapPass.
+ * - `ldrSpritePassView`: the single-sample color view the sprite split writes;
+ *   it is graph-owned on native linear-LDR and raw swap-chain storage on the
+ *   fallback path. The MSAA view remains `ldrSpriteColorView`.
+ *
+ * Invariant: a public `RenderPipelineContext` cast to this type by
+ * `_asInternalCtx` (in render-system-record.ts) MUST originate from
+ * recordFrame's passCtx builder; downstream consumers (custom pipelines) MUST
+ * NOT cast — these fields are not part of the public contract.
+ */
+export interface _StandardForwardSceneView {
+    /** @internal Active successful-submit transaction facts for temporal graph resources. */
+    readonly temporalFrame: TemporalFrameAttempt | undefined;
+    /** @internal Opt-in nested CPU observer inherited from recordFrame. */
+    readonly profilePhase?: <T>(phase: RenderRecordPhase, action: () => T) => T;
+    /** @internal Skip directional caster recording when the atlas token is unchanged. */
+    readonly directionalShadowCacheReuse: boolean;
+    /** @internal Bounded cascade-local validity tokens used by semantic observation. */
+    readonly directionalShadowCacheTokens?: readonly string[];
+    /** @internal Bit i is set when cascade i matched the prior successful atlas token. */
+    readonly directionalShadowCacheHitMask?: number;
+    /** @internal Four-view visibility joined to the shared batch-aligned submission. */
+    readonly multiViewSubmissions: readonly MultiViewProductionSubmission[];
+    /** @internal Canonical CSM receiver/caster membership plan. */
+    readonly directionalCsmPlan: import('./extract/directional-csm').DirectionalCsmResult | undefined;
+    /** @internal Enables producer-owned CSM causal markers for debug capture. */
+    readonly shadowDebugObservation?: boolean | undefined;
+    /**
+     * @internal — feat-20260614 M8 (D-19): the live World the record stage
+     * resolves user-tier asset handles against. Asset payloads moved off the
+     * AssetRegistry onto `world.sharedRefs`, so `world.sharedRefs.resolve(handle)`
+     * is the only resolution entry point; the record stage threads the World here
+     * (it is not part of the public `RenderPipelineContext` — custom pipeline
+     * authors never see it).
+     */
+    readonly world: World;
+    /** @internal Raster items submitted by the GPU-driven Geometry lane this frame. */
+    readonly gpuDrivenItemKeys: ReadonlySet<RasterItemKey>;
+    /** @internal True when the GPU lane owns every forward Geometry item this frame. */
+    readonly gpuDrivenOwnsAllForwardItems: boolean;
+    /** @internal Candidate-index membership for the batch-aligned CPU shadow executor. */
+    readonly validatedByCandidateIndex?: ReadonlyMap<number, ValidatedRenderable>;
+    /** @internal ValidatedOrdered slot for the same candidate-index owner. */
+    readonly validatedIndexByCandidateIndex?: ReadonlyMap<number, number>;
+    /**
+     * @internal Main-view shadow geometry owner. The frame builder computes the
+     * stable validated slot once; point/spot compatibility passes reuse it
+     * instead of rescanning validatedOrdered for every face/tile.
+     */
+    readonly validatedShadowEntries?: readonly {
+        readonly entry: ValidatedRenderable;
+        readonly validatedIndex: number;
+    }[];
+    readonly tonemapActive: boolean;
+    readonly geometryColorView: TextureView | null;
+    readonly geometryDepthView: TextureView | null;
+    /**
+     * @internal — graph key owning the active geometry depth attachment. URP's
+     * MSAA route writes `hdrDepthMsaa` while depth post-process registrations
+     * retain the stable logical `depth` key; the dispatcher uses this fact to
+     * bind the matching sample-count texture.
+     */
+    readonly geometryDepthKey: string | null;
+    readonly skyboxActive: boolean;
+    readonly splitLdrSprite: boolean;
+    readonly ldrSpritePassView: TextureView | null;
+    /** @internal Attachment format selected by a typed graph-owned scene pass. */
+    readonly transparentColorFormat?: GPUTextureFormat;
+    /** feat-20260609 M2: per-frame dispatch entries for selector-based pass filtering. */
+    readonly dispatch: readonly DispatchEntry[];
+    /** @internal Complete union dispatch consumed by directional/point/spot shadow passes. */
+    readonly shadowDispatch: readonly DispatchEntry[];
+    /**
+     * @internal — feat-20260609-hdrp-cluster-fragment-ggx M4 / w15.
+     *
+     * The unified group(2) BindGroup the HDRP cluster-forward path binds at the
+     * mesh slot. Carries the mesh SSBO at binding 0 (with dynamic offset, same
+     * buffer as URP's `meshBindGroup`) plus the 4 HDRP cluster buffers at
+     * bindings 3..6 (light_data / cluster_grid / light_index_list /
+     * cluster_uniform). Non-null when `frameState.isHdrpActive` AND the HDRP
+     * buffers have been allocated for the runtime; `null` on URP frames or when
+     * HDRP buffer allocation failed.
+     *
+     * Plan D-4 (no `extraBindGroups` patch): the cluster bindings flow through
+     * an explicit field on the internal scene-view extension; AI-user-defined
+     * custom pipelines never see it (extension is `@internal`). recordMainPass
+     * destructures it and selects it instead of `meshBindGroup` at
+     * `setBindGroup(2, ...)` on HDRP frames; the single dynamic offset
+     * (`i * MESH_PER_ENTITY_STRIDE`) stays valid because binding 0 of the unified
+     * BGL is the same per-entity mesh SSBO.
+     */
+    readonly hdrpClusterBindGroup: BindGroup | null;
+    /** @internal Compute-only group for the optional HDRP membership producer. */
+    readonly hdrpClusterMembershipBindGroup: BindGroup | null;
+    /**
+     * @internal — feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 /
+     * w4-record-swap (D-1).
+     *
+     * The per-frame fold dispatch plan keyed by validatedOrdered index.
+     * `null` when `transparentDispatch.length === 0` or when no fold-eligible
+     * (bucketSize > 1) bucket exists this frame — the dispatch loops fall
+     * through to the existing per-entity drawIndexed path byte-identically.
+     *
+     * Non-null carries:
+     * - `headBuckets[i]` — bucket descriptor for index `i` (head of an
+     *   instanced draw); the dispatch loop overrides @group(3) instances BG
+     *   and emits one `drawIndexed(idxCount, bucket.bucketSize)`.
+     * - `skipIndices[i]` — true when index `i` is a non-head member of
+     *   a fold bucket; the dispatch loop emits `continue`.
+     *
+     * Plan D-1 (record-stage transparent fold): the plan reuses the
+     * transparent-sort equivalence class as the bucket key, so no new
+     * BinKey type. Mode-gate (D-5): only mode 0 produces non-singleton
+     * buckets; modes 1/2/3 produce all-singleton plans which are byte-
+     * identical to no plan.
+     */
+    readonly foldDispatchPlan: import('./render-system-fold').FoldDispatchPlan | null;
+    /** @internal Per-renderable material-index to deduplicated UBO-slot mapping. */
+    readonly materialSlotIndices: readonly (readonly number[])[];
+    /** @internal Unique material snapshots stored by the frame-local UBO table. */
+    readonly materialSlots: readonly MaterialSnapshot[];
+    /** @internal First renderable index associated with each unique slot. */
+    readonly materialSlotOwners: readonly number[];
+    /** @internal Number of unique material slots in `materialSlots`. */
+    readonly materialSlotCount: number;
+    /** @internal Cross-frame material bind-group assembly cache shared by main passes. */
+    readonly materialBgAssemblyCache: Map<number, MaterialBgAssemblyCacheEntry>;
+    /** @internal Per-frame material UBO bytes shared by repeated main passes. */
+    materialUboPayloadCache?: {
+        readonly materialSlots: readonly MaterialSnapshot[];
+        readonly materialSlotCount: number;
+        readonly materialResourceEpoch: number;
+        readonly payload: Uint8Array;
+    };
+    /**
+     * @internal — feat-20260612-hdrp-ssao wiring fix.
+     *
+     * The compiled `ssaoBlurred` graph-transient TextureView, resolved inside the
+     * HDRP forward pass execute closure (the only place `resolveCtx` is live) and
+     * stashed here for recordMainPass to build the SSAO-enabled unified group(2)
+     * bind group. `undefined` when SSAO is disabled or on URP frames — then
+     * recordMainPass keeps the white-fallback bind group (identity AO=1.0).
+     *
+     * Mutable (not readonly): the forward pass closure assigns it per frame just
+     * before delegating to recordMainPass. The group(2) bind group cannot carry
+     * the view ahead of typed graph execution because the texture is graph-owned.
+     */
+    hdrpSsaoBlurredView?: import('@forgeax/engine-rhi').TextureView;
+}
+/**
+ * @internal — the type passed to urp record* closures by
+ * `recordFrame`. Public `RenderPipelineContext` plus the six urp
+ * scene-view leakage fields under a flat structure (so existing destructures
+ * like `c.tonemapActive` continue to work without churn). Custom pipelines
+ * must NOT see this type.
+ */
+export type _InternalRenderPipelineContext = RenderPipelineContext & _StandardForwardSceneView;
+//# sourceMappingURL=render-pipeline-context.d.ts.map

package/dist/render-pipeline-context.d.ts.map

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

package/dist/render-pipeline-target.d.ts

@@ -0,0 +1,16 @@
+import type { GraphTexture, GraphTextureDescriptor, GraphTextureView, GraphTextureViewDescriptor, RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import { type Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame, RenderPipelineTopology } from './render-pipeline';
+export interface RenderPipelineTarget {
+    readonly texture: GraphTexture;
+    readonly view: GraphTextureView;
+    readonly format: string;
+    readonly sampleCount: 1 | 4;
+    readonly resolveTarget?: GraphTextureView | undefined;
+}
+export declare function createRenderPipelineTarget(graph: RenderGraphBuilder<RenderPipelineFrame>, label: string, descriptor: GraphTextureDescriptor, viewDescriptor?: GraphTextureViewDescriptor): Result<RenderPipelineTarget, RenderGraphError>;
+export declare function importRenderPipelineSurface(graph: RenderGraphBuilder<RenderPipelineFrame>, topology: RenderPipelineTopology): Result<{
+    readonly display: RenderPipelineTarget;
+    readonly storage: RenderPipelineTarget;
+}, RenderGraphError>;
+//# sourceMappingURL=render-pipeline-target.d.ts.map

package/dist/render-pipeline-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-pipeline-target.d.ts","sourceRoot":"","sources":["../src/render-pipeline-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,EAChB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAM,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAKxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAErF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACvD;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,EAC9C,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,sBAAsB,EAClC,cAAc,GAAE,0BAA+B,GAC9C,MAAM,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,CAWhD;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,EAC9C,QAAQ,EAAE,sBAAsB,GAC/B,MAAM,CACP;IAAE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,EAClF,gBAAgB,CACjB,CAgDA"}

package/dist/render-pipeline.d.ts

@@ -0,0 +1,149 @@
+import type { ColorValueDomain, GraphAccess, GraphResourceResolver, GraphTexture, GraphTextureView, RenderGraphBuilder, RenderGraphError, RenderGraphFrame } from '@forgeax/engine-render-graph';
+import type { BindGroup, RhiError, RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import { type Result } from '@forgeax/engine-types';
+import type { Tonemap } from './components/camera';
+import type { EnvironmentGraphTargets } from './environment/graph';
+import { type RenderError } from './errors/render';
+import type { RenderFeatureTargetKind } from './features/targets';
+import type { PostProcessError } from './post-process-errors';
+import type { RenderPipelineContext } from './render-pipeline-context';
+export type { RenderPipelineContext } from './render-pipeline-context';
+export type RenderColorDomain = 'linearHdr' | 'linearLdr' | 'displayEncoded';
+export interface ToneOutputContract {
+    readonly input: RenderColorDomain;
+    readonly toneMapped: boolean;
+    readonly mapped: 'linearLdr';
+    readonly finalCapture: 'displayEncoded';
+    readonly exposureStage: 'linearHdr' | 'none';
+}
+export type RenderPostStageName = 'transparent-blend' | 'bloom' | 'tone' | 'fxaa' | 'output';
+export type RenderPostDomainStage = readonly [
+    RenderPostStageName,
+    ColorValueDomain,
+    ColorValueDomain
+];
+/**
+ * Single post-stage domain contract shared by URP and HDRP.
+ * The pipeline selects the scene domain for transparent geometry; every later
+ * stage follows the same linear blend, tone, anti-alias, and output sequence.
+ */
+export declare function resolvePostColorDomainContract(pipeline: 'urp' | 'hdrp'): readonly RenderPostDomainStage[];
+/**
+ * Describe the built-in output stages without moving color-domain policy into
+ * a mode name. Tone-enabled cameras render HDR, apply exposure and the
+ * selected curve in the fullscreen pass, then reach the encoded surface.
+ */
+export declare function resolveToneOutputContract(tonemap: Tonemap): ToneOutputContract;
+/** Stable facts that may change graph topology and therefore its compiled identity. */
+export interface RenderPipelineTopology {
+    readonly pipelineId: string;
+    readonly config: import('@forgeax/engine-types').RenderPipelineAsset['config'];
+    readonly surface: {
+        readonly width: number;
+        readonly height: number;
+        readonly storageFormat: import('@forgeax/engine-rhi').TextureFormat;
+        readonly viewFormat: import('@forgeax/engine-rhi').TextureFormat;
+    };
+    readonly camera: Pick<RenderPipelineContext['camera'], 'tonemap' | 'antialias' | 'bloom'>;
+    readonly shadow: {
+        readonly mapSize: number;
+        readonly cascadeCount: 1 | 2 | 3 | 4;
+        readonly pointCount: number;
+        readonly pointFaceSize: number;
+        readonly spotCount: number;
+    };
+    readonly lane: {
+        readonly compute: boolean;
+        readonly storageBuffer: boolean;
+        readonly multisample: boolean;
+        readonly maxColorAttachments: number;
+    };
+    readonly featureTopologySignature: string;
+    readonly gpuDrivenTopologySignature: string;
+    /** Environment topology is absent off-path and producer-free when steady. */
+    readonly environment?: {
+        readonly enabled: boolean;
+        readonly dirty: boolean;
+    } | undefined;
+}
+export type BuiltinEnvironmentPipeline = 'urp' | 'hdrp';
+/** Stable pass provenance used by topology traces and pixel-capture attribution. */
+export declare function createEnvironmentPipelineTopology(pipeline: BuiltinEnvironmentPipeline): readonly string[];
+export interface RenderPipelineFrame extends RenderPipelineContext, RenderGraphFrame {
+}
+export interface RenderPipelineFeatureTarget {
+    readonly kind: RenderFeatureTargetKind;
+    readonly texture: GraphTexture;
+    readonly view: GraphTextureView;
+    readonly resolveTarget?: GraphTextureView | undefined;
+    readonly format: string;
+    readonly sampleCount: 1 | 4;
+}
+export interface RenderPipelineTemporalInput {
+    readonly sceneColor: RenderPipelineFeatureTarget;
+    readonly sceneDepth: RenderPipelineFeatureTarget;
+    readonly sceneTemporal?: RenderPipelineFeatureTarget | undefined;
+}
+export interface RenderPipelineTemporalOutput {
+    readonly resolvedColor: RenderPipelineFeatureTarget;
+}
+export interface RenderPipelineTemporalContract {
+    resolve(input: RenderPipelineTemporalInput): Result<RenderPipelineTemporalOutput | undefined, RenderPipelineBuildError>;
+    finish(): Result<void, RenderPipelineBuildError>;
+    inspect(): {
+        readonly resolveCount: number;
+    };
+}
+export declare function createRenderPipelineTemporalContract(input: {
+    readonly enabled: boolean;
+    readonly rgba16floatRenderable: boolean;
+    readonly maxColorAttachments: number;
+    project(input: RenderPipelineTemporalInput): Result<RenderPipelineTemporalOutput, RenderPipelineBuildError>;
+}): RenderPipelineTemporalContract;
+export interface RenderPipelineGpuDrivenProjection {
+    readonly accesses: readonly GraphAccess[];
+    /**
+     * Shadow cascades consume the same GPU-generated visibility/indirect
+     * contract as the main raster. The projection is optional for fallback
+     * devices and for frames without a safe shadow batch.
+     */
+    readonly shadow?: readonly RenderPipelineGpuDrivenShadowProjection[];
+    encode(viewBindGroup: BindGroup, pass: RhiRenderPassEncoder, resources: GraphResourceResolver): void;
+}
+export interface RenderPipelineGpuDrivenShadowProjection {
+    readonly cascadeIndex: number;
+    readonly accesses: readonly GraphAccess[];
+    /** Number of indirect `(cascade, shadow batch)` draw calls in this projection. */
+    readonly batchCount?: number;
+    /** The caller has already bound the shared shadow view/material groups. */
+    encode(pass: RhiRenderPassEncoder, resources: GraphResourceResolver): void;
+}
+export interface RenderPipelineBuildContext<FrameCtx extends RenderPipelineFrame> {
+    readonly graph: RenderGraphBuilder<FrameCtx>;
+    /** Renderer-owned physical candidate views; custom pipelines may consume them. */
+    readonly environment?: {
+        readonly enabled: boolean;
+        readonly dirty: boolean;
+        readonly targets?: EnvironmentGraphTargets | undefined;
+        readonly sampledSky?: GraphTextureView | undefined;
+    } | undefined;
+    projectGpuDriven(target: {
+        readonly format: string;
+        readonly sampleCount: 1 | 4;
+    }): Result<RenderPipelineGpuDrivenProjection | undefined, RenderPipelineBuildError>;
+    contributeFeatures(targets: readonly RenderPipelineFeatureTarget[]): Result<void, RenderPipelineBuildError>;
+    resolveTemporal(input: RenderPipelineTemporalInput): Result<RenderPipelineTemporalOutput | undefined, RenderPipelineBuildError>;
+}
+export type RenderPipelineBuildError = RenderGraphError | RenderError | RhiError | PostProcessError;
+/**
+ * Registrable, installable, hot-swappable render topology.
+ *
+ * `build` declares resources and passes only. The renderer owns compilation,
+ * last-known-good replacement, execution, retirement, and the single frame submit.
+ * Feature contributions enter through `contributeFeatures`, so compute-produced
+ * buffers and later raster reads remain inside the same typed dependency graph.
+ */
+export interface RenderPipeline<FrameCtx extends RenderPipelineFrame = RenderPipelineFrame> {
+    build(context: RenderPipelineBuildContext<FrameCtx>, topology: RenderPipelineTopology): Result<void, RenderPipelineBuildError>;
+}
+//# sourceMappingURL=render-pipeline.d.ts.map

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

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

package/dist/render-scene-projection.d.ts

@@ -0,0 +1,174 @@
+import type { RenderSceneFact, SceneFactDiagnostic, SceneFactRevisionDomain, SceneMobility } from './gpu-scene-schema';
+import type { RenderableSnapshot, RenderableTemporalSnapshot } from './render-system-extract';
+interface RenderSceneIdentity {
+    readonly worldId: number;
+    readonly entityKey: number;
+    /** Generation observed by the producer when the operation was authored. */
+    readonly expectedGeneration?: number;
+}
+export type RenderSceneOperation = {
+    readonly kind: 'create';
+    readonly snapshot: RenderableSnapshot;
+    readonly expectedGeneration?: number;
+} | (RenderSceneIdentity & {
+    readonly kind: 'update-transform';
+    readonly world: Float32Array;
+}) | (RenderSceneIdentity & {
+    readonly kind: 'remove';
+});
+export interface RenderSceneFactDelta {
+    readonly slot: number;
+    readonly generation: number;
+    readonly changedDomains: readonly SceneFactRevisionDomain[];
+    readonly previous: RenderSceneFact | undefined;
+    readonly current: RenderSceneFact;
+}
+export interface RenderSceneApplyResult {
+    readonly created: number;
+    readonly updated: number;
+    readonly removed: number;
+    readonly recreated: number;
+    readonly ignoredLateUpdates: number;
+    readonly createdSlots: readonly RenderSceneProjectionSlot[];
+    readonly updatedSlots: readonly RenderSceneProjectionSlot[];
+    readonly removedSlots: readonly RenderSceneProjectionRecord[];
+    readonly recreatedSlots: readonly RenderSceneProjectionSlot[];
+    /** Fine-grained Scene Fact updates consumed by GPU tables and later views. */
+    readonly factDeltas: readonly RenderSceneFactDelta[];
+    /** Non-fatal diagnostics; malformed facts never become implicit casters. */
+    readonly diagnostics: readonly SceneFactDiagnostic[];
+    /** Spatial owner revisions produced by this projection update. */
+    readonly spatialIndex?: SpatialIndexUpdate;
+}
+export interface RenderSceneProjectionRecord extends Omit<RenderSceneIdentity, 'expectedGeneration'> {
+    readonly slot: number;
+    readonly generation: number;
+}
+export interface RenderSceneProjectionInspection {
+    readonly current: readonly RenderSceneProjectionRecord[];
+    readonly lastSubmitted: {
+        readonly epoch: number;
+        readonly records: readonly RenderSceneProjectionRecord[];
+    };
+    readonly slotCapacity: number;
+    readonly freeSlots: number;
+    readonly factDiagnostics: readonly SceneFactDiagnostic[];
+    readonly spatialIndex: SpatialIndexInspection;
+}
+export interface RenderSceneProjectionSlot extends RenderSceneProjectionRecord {
+    readonly snapshot: RenderableSnapshot;
+    readonly fact: RenderSceneFact;
+}
+export interface RenderSceneSubmissionCapture {
+    readonly revision: number;
+    readonly slots: readonly {
+        readonly slot: number;
+        readonly current: RenderSceneProjectionSlot | undefined;
+    }[];
+    readonly visible: ReadonlySet<string>;
+}
+export interface RenderSceneSubmissionDelta {
+    readonly epoch: number;
+    readonly slots: readonly number[];
+}
+export type SpatialIndexOwnerKind = 'static-bvh' | 'dynamic-loose-tree';
+export interface SpatialQueryHit extends RenderSceneProjectionRecord {
+    readonly owner: SpatialIndexOwnerKind;
+    readonly mobility: SceneMobility;
+    readonly worldAabb: Float32Array | undefined;
+}
+export interface SpatialQueryResult {
+    readonly hits: readonly SpatialQueryHit[];
+    readonly staticRevision: number;
+    readonly dynamicRevision: number;
+    readonly visitedNodes: number;
+    readonly testedEntries: number;
+    readonly falseNegativeSlots: readonly number[];
+}
+export interface SpatialIndexOwnerInspection {
+    readonly revision: number;
+    readonly entries: number;
+    readonly boundedEntries: number;
+    readonly unboundedEntries: number;
+    readonly nodes: number;
+    readonly rebuilds: number;
+    readonly patches: number;
+    readonly queries: number;
+    readonly visitedNodes: number;
+    readonly testedEntries: number;
+    readonly returnedEntries: number;
+}
+export interface SpatialIndexInspection {
+    readonly revision: number;
+    readonly static: SpatialIndexOwnerInspection;
+    readonly dynamic: SpatialIndexOwnerInspection & {
+        readonly dynamicEntries: number;
+        readonly unknownEntries: number;
+        readonly reinserts: number;
+    };
+    readonly broadphaseQueries: number;
+    readonly bruteForceComparisons: number;
+    readonly falseNegatives: number;
+}
+export interface SpatialIndexUpdate {
+    readonly revision: number;
+    readonly staticRevision: number;
+    readonly dynamicRevision: number;
+    readonly staticChanged: boolean;
+    readonly dynamicChanged: boolean;
+    readonly inspection: SpatialIndexInspection;
+}
+/**
+ * Renderer-owned persistent CPU scene projection.
+ *
+ * Operations are coalesced per `(worldId, entityKey)` before stable slots are
+ * touched. Slots carry generations so downstream GPU residency can reject
+ * stale work after removal and reuse. Each slot also owns the Scene Fact used
+ * by later spatial, visibility, batch, and upload owners.
+ */
+export declare class RenderSceneProjection {
+    private readonly slots;
+    private readonly lastSubmittedSlots;
+    private readonly generations;
+    private readonly freeSlots;
+    private readonly slotsByWorld;
+    private readonly slotsByMaterial;
+    private materialized;
+    private slotSnapshot;
+    private factDiagnostics;
+    private readonly spatialIndex;
+    private readonly dirtySinceSubmitted;
+    private lastSubmittedVisible;
+    private revision;
+    private submittedEpoch;
+    apply(operations: readonly RenderSceneOperation[]): RenderSceneApplyResult;
+    materialize(): readonly RenderableSnapshot[];
+    slotsSnapshot(): readonly RenderSceneProjectionSlot[];
+    lastSubmittedSlotByIndex(slot: number): RenderSceneProjectionSlot | undefined;
+    temporalSnapshotBySlot(slot: number): RenderableTemporalSnapshot | undefined;
+    withTemporal(snapshot: RenderableSnapshot): RenderableSnapshot;
+    wasLastSubmittedVisible(slot: number, generation: number): boolean;
+    captureSubmission(visible: readonly Pick<RenderableSnapshot, 'worldId' | 'entityKey'>[]): RenderSceneSubmissionCapture;
+    commitSubmission(capture: RenderSceneSubmissionCapture): RenderSceneSubmissionDelta;
+    /** O(1) stable-slot lookup for delta owners; avoids rescanning slotsSnapshot. */
+    slotByIndex(slot: number): RenderSceneProjectionSlot | undefined;
+    has(worldId: number, entityKey: number): boolean;
+    record(worldId: number, entityKey: number): RenderSceneProjectionRecord | undefined;
+    snapshot(worldId: number, entityKey: number): RenderableSnapshot | undefined;
+    slotsForMaterial(materialHandle: number): readonly RenderSceneProjectionSlot[];
+    querySpatialIndex(worldAabb: Float32Array, options?: {
+        readonly verifyAgainstBruteForce?: boolean;
+    }): SpatialQueryResult;
+    replaceCurrent(snapshots: readonly RenderableSnapshot[]): RenderSceneApplyResult;
+    reset(snapshots: readonly RenderableSnapshot[]): void;
+    inspect(): RenderSceneProjectionInspection;
+    private lookup;
+    private temporalSnapshot;
+    private allocate;
+    private release;
+    private indexMaterials;
+    private unindexMaterials;
+    private invalidateSnapshots;
+}
+export {};
+//# sourceMappingURL=render-scene-projection.d.ts.map