@forgeax/engine-render 0.1.2

package/dist/render-system.d.ts

@@ -0,0 +1,814 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { VertexLayoutProjection } from '@forgeax/engine-geometry';
+import type { Profiler } from '@forgeax/engine-profiler';
+import type { BindGroupLayout, Buffer, ComputePipeline, PipelineLayout, RenderPipeline, RhiCanvasContext, RhiDevice, Sampler, TextureView } from '@forgeax/engine-rhi';
+import { type Result, RhiError } from '@forgeax/engine-rhi';
+import type { MaterialRuntimeArtifact } from '@forgeax/engine-shader';
+import { type ImmutableParamSchemaProjection, type MaterialRenderState, type ParamSchemaEntry, type PassKind, type PrimitiveTopology, type RenderPipelineAsset } from '@forgeax/engine-types';
+import type { RenderAssetPort } from './assets/render-asset-port';
+import type { DynamicTextureStore } from './dynamic-texture-store';
+import type { EngineMetrics } from './engine-metrics';
+import { type EnvironmentInspection } from './environment/inspection';
+import { type ObservationUnavailableError, type RenderError } from './errors/render';
+import { type RenderFeatureGraphComposition, type RenderFeatureGraphContribution } from './features/graph-contribution';
+import { type RenderFeatureHost } from './features/host';
+import type { RenderFeaturePassContext } from './features/types';
+import { type PostProcessShaderEntry } from './fullscreen-post-process-pass';
+import { type GpuDrivenProductionInspection } from './gpu-driven/production-raster';
+import type { GpuBuffer } from './gpu-resource';
+import type { GpuResourceStore } from './gpu-resource-store';
+import type { RhiErrorListenerRegistry } from './lifecycle';
+import type { MeshMaterialBindingObservation } from './mesh-material-bindings';
+import { type ParamSchemaProjectionCensus } from './param-schema-projection-census';
+import { type PersistentRenderSceneInspection } from './persistent-render-scene';
+import { PipelineError } from './pipeline-errors';
+import { type FrameObservation, type FrameObservationOptions } from './record/frame-observation';
+import type { MembershipTimingController } from './record/membership-timing';
+import { type ShadowSubmitMode, type ShadowSubmitModeState, type ShadowSubmitResult } from './record/shadow-submit-mode';
+import type { RenderPipeline as RenderPipelineDef } from './render-pipeline';
+import type { RenderPipelineContext } from './render-pipeline-context';
+import { type TemporalInspection } from './temporal-inspection';
+export type RenderSceneInspection = PersistentRenderSceneInspection & {
+    readonly gpuDriven: GpuDrivenProductionInspection;
+    readonly temporal: TemporalInspection;
+    readonly environment: EnvironmentInspection;
+};
+import { type DrawOwnerOptions } from './renderer';
+import type { MaterialRenderProjection } from './renderer/material/assembly';
+import type { MaterialReadiness } from './renderer/material/pipeline-projection';
+import type { SkinPaletteAllocator } from './systems/skin-palette-allocator';
+/** Dynamic-offset stride for one derived material UBO slot. */
+export declare const MATERIAL_PER_ENTITY_STRIDE = 512;
+/**
+ * Engine-internal Extract / Prepare / Record driver; constructed by createRenderer.
+ *
+ * w15 M5 dual-pipeline dispatch: `pipelineDispatchCounts` surfaces per-frame
+ * counters of how many entities were routed to each pipeline (plan-strategy
+ * D-P4 / requirements AC-07). The counts roll over monotonically — test
+ * callers read them after `draw([world], { cameraOwner: 0, resourceOwner: 0 })` to assert each tag saw >= 1 draw.
+ * Reset is intentional on every `draw([world], { cameraOwner: 0, resourceOwner: 0 })` entry so per-frame assertions
+ * stay local (charter proposition 4 explicit failure: test code sees exact
+ * per-draw counts, not stale cross-frame totals).
+ *
+ * bug-20260519: BUILTIN cube migrated to 12F so the legacy `unlitBuiltin`
+ * counter is gone; the surface collapses to `unlit` (every entity whose
+ * shader identity is `forgeax::default-unlit`) + `standard` (every entity
+ * whose shader identity is `forgeax::default-standard-pbr`).
+ */
+export interface RenderSystem {
+    /** Returns true only when this invocation reached queue submission. */
+    draw(worlds: readonly World[], opts: DrawOwnerOptions): boolean;
+    /** Apply one renderer-owned shadow submission mode for one generation. */
+    applyShadowSubmitMode(mode: ShadowSubmitMode, rendererGeneration: string): ShadowSubmitResult<ShadowSubmitModeState>;
+    /** Restore the renderer-owned mode to the independent baseline. */
+    restoreShadowSubmitMode(rendererGeneration: string): ShadowSubmitResult<ShadowSubmitModeState>;
+    /** Read the generation-bound mode and exact lifecycle counters. */
+    getShadowSubmitMode(): ShadowSubmitModeState;
+    /** Release renderer-owned persistent state for one detached World. */
+    detachWorld(world: World): void;
+    /** Release the profiler catalog contribution owned by this RenderSystem. */
+    releaseProfilerCatalog(): void;
+    observeCurrentFrame(options: FrameObservationOptions): Promise<Result<FrameObservation, ObservationUnavailableError>>;
+    readonly pipelineDispatchCounts: {
+        readonly unlit: number;
+    };
+    /**
+     * feat-20260528-frustum-culling M5 / w14: per-frame frustum-culling counters.
+     * Updated by `draw([world], { cameraOwner: 0, resourceOwner: 0 })` on every call from the Extract stage.
+     */
+    readonly frustumStats: {
+        culled: number;
+        total: number;
+    };
+    /** Per-frame candidate entities rejected by author visibility. */
+    readonly visibilityStats: {
+        explicitlyHidden: number;
+    };
+    /** Persistent scene maintenance evidence from the ordinary single-World path. */
+    readonly renderScene: RenderSceneInspection;
+    /** Current mesh-slot provenance and active diagnostics from the last frame. */
+    readonly meshMaterialBindings: readonly MeshMaterialBindingObservation[];
+    /**
+     * feat-20260531-bloom-first-declarative-render-graph-pass M4 fix-up w19:
+     * per-frame render-graph pass names in declaration order. Empty array
+     * before the first `draw([world], { cameraOwner: 0, resourceOwner: 0 })` call; populated after the per-frame
+     * graph is built (lazily on first draw). Read-only introspection surface
+     * so smoke tests can assert the declarative pass chain is wired without
+     * reaching into engine internals.
+     */
+    readonly perFramePassNames: readonly string[];
+    /**
+     * feat-20260531-per-frame-bind-group-cache M1 / w4: per-frame
+     * createBindGroup counter. Reset to 0 on every `draw([world], { cameraOwner: 0, resourceOwner: 0 })` entry,
+     * bumped on each cache-miss createBindGroup call in the record stage.
+     * Aligns with pipelineDispatchCounts precedent: closure-mutable object
+     * + draw-entry reset + readonly getter. Stable-frame AC-03 asserts
+     * createBindGroup == 0 when all bind groups are cache-resident.
+     *
+     * M5 / w19 type-safe finalization: the return type is purposely the
+     * narrowest inline object literal `{ readonly createBindGroup: number }`
+     * rather than a wider Record/alias — this ensures TS language service
+     * hover shows the exact field name + type, and AC-09 consumption sites
+     * infer `number` without `as` casts (plan-strategy D-7 + sec.8
+     * discoverability).
+     */
+    readonly bindGroupCounts: {
+        readonly createBindGroup: number;
+        readonly keys: readonly string[];
+    };
+    /**
+     * feat-20260615-pipeline-spec-ssot M5-T2: latest URP shadow-atlas
+     * texture view resolved from the compiled typed frame graph. Returns `null` when no
+     * frame has been drawn yet, or when the active pipeline does not
+     * declare the `shadowDepth` color target. Read-only debug seam:
+     * the engine itself reads the same view inline in `recordFrame`;
+     * this getter exists so debug readback paths
+     * (`Renderer.debugSampleShadowFactor`) read the same SSOT view as
+     * the engine's record stage (D-2: graph owns the lifecycle; no
+     * mirror slot on `pipelineState.perPassResources`).
+     */
+    getCurrentShadowView(): any | null;
+    /**
+     * feat-20260601-customizable-render-pipeline-seam M1 / w7: register a render-pipeline
+     * logic under `id`. Same-id re-register THROWS a PipelineError
+     * (`'pipeline-already-registered'`) - programmer-error fail-fast, mirroring
+     * ShaderRegistry.installMaterialArtifact. Engine builtins use the `forgeax::` prefix.
+     */
+    registerPipeline(id: string, impl: RenderPipelineDef): void;
+    /**
+     * feat-20260601-customizable-render-pipeline-seam M1 / w7 (D-19): install the pipeline
+     * described by a `RenderPipelineAsset` POD. Looks up `pipelineId` in the registry; on an
+     * unregistered id returns `Result.err(PipelineError{code:'pipeline-not-found'})`. On
+     * success the next `draw` detects the install-epoch bump and rebuilds the memoized
+     * per-frame graph (hot-swap). Takes the payload directly because installation happens at
+     * boot/swap time before any World exists -- there is no handle to resolve.
+     */
+    installPipeline(asset: RenderPipelineAsset): Result<() => void, PipelineError>;
+    /**
+     * feat-20260604-resource-owning-render-graph-and-fullscreen-postpr M2 / w13:
+     * fullscreen post-process shader registry, parallel to ShaderRegistry.installMaterialArtifact
+     * (D-4: material shader handles 4-BGL / 12-float-vertex / depth / triangle-list, while
+     * fullscreen post-process uses 0-vertex-buffer / no-depth / input-texture-BGL).
+     * Same-id re-register THROWS PostProcessError ('post-process-already-registered').
+     * Engine builtins use the `forgeax::` prefix.
+     */
+    readonly postProcess: {
+        register(id: string, entry: PostProcessShaderEntry): () => void;
+    };
+    /**
+     * feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle / M5 / w21:
+     * release the per-RenderSystem frame-state GPU bookkeeping during
+     * `Renderer.dispose()`. Retires the compiled graph and clears the instance-buffer cache.
+     *
+     * Idempotent (architecture-principles §6): a second call after both
+     * structures are cleared is a no-op. Per-step failures inside drain /
+     * disposeInstanceBuffers fall through silently -- the Renderer.dispose
+     * cascade owns the try/catch + errorRegistry.fire fan-out (D-3).
+     */
+    disposeFrameState(): void;
+    /**
+     * feat-20260622-s5 M3 / B-2 / w18: drop the device-bound state the recover()
+     * rebuild must shed before re-running the pipeline build against a fresh
+     * device. Two effects, both keyed to the lost device:
+     *   1. the per-frame render-graph's pendingDestroy queue (PooledTextures
+     *      minted by the lost device — clearPendingDestroy skips destroyTexture);
+     *   2. post-process declarations + their eager param UBOs. Declarations are
+     *      CPU-owned author intent and survive; UBOs are stale lost-device
+     *      handles and are rebuilt after the replacement device is live.
+     * Idempotent and graph-optional (no-op when nothing has compiled yet).
+     */
+    resetForRecover(): void;
+    /** Recreate GPU-driven production state after internals.device is replaced. */
+    restoreGpuDrivenForRecover(): void;
+    /** Recreate post-process GPU parameter resources after a device rebuild. */
+    restorePostProcessResources(): void;
+}
+/**
+ * feat-20260601-customizable-render-pipeline-seam M2 / w10: the NARROW runtime-services
+ * surface a `RenderPipeline` pass closure consumes (UE `FRDGBuilder` runtime half). Bundles
+ * exactly the four `RenderSystemInternals` members the 9 urp closures reach
+ * directly: the GPU `device`, the structured-error sink `errorRegistry`, and the two
+ * per-MaterialShader pipeline-cache / param-schema lookups. `RenderPipelineContext.runtime`
+ * is typed as this interface, NOT the full `RenderSystemInternals` - a pipeline author
+ * cannot reach `context` / `getPipelineState` / `canvas` (charter P4: a
+ * consistent narrow abstraction over the runtime, not the kitchen-sink). `internals`
+ * itself is unreachable through the public ctx (the AC-08 oracle: `ctx.internals` is a
+ * compile error).
+ */
+export interface RenderSystemRuntime {
+    readonly device: RhiDevice;
+    readonly errorRegistry: RhiErrorListenerRegistry;
+    /** @internal Emit directional shadow causal markers only for debug capture. */
+    readonly shadowDebugObservation?: boolean | undefined;
+    /** @internal Debug-only ParamSchema compatibility census; absent in production. */
+    readonly paramSchemaProjectionCensus?: ParamSchemaProjectionCensus | undefined;
+    /** @internal Depth-only fullscreen draw used to clear one invalid cascade tile. */
+    readonly getDirectionalShadowTileClearPipeline?: () => RenderPipeline | null;
+    /**
+     * feat-20260622-s5-device-surface-self-heal-recover M2 / w8: health registry
+     * threaded into the record stage so `recordFrame` can fire `internal-fault`
+     * when surface reconfigure+retry both fail (A-IN-2).
+     */
+    readonly healthRegistry: import('./lifecycle').HealthListenerRegistry;
+    /**
+     * Cooked material consumption boundary. Runtime record code may obtain a
+     * projection and content-addressed artifact here; it must not resolve an
+     * authored parent chain or compile a missing specialization.
+     */
+    readonly getMaterialProjection?: (materialGuid: string) => MaterialRenderProjection | undefined;
+    readonly getMaterialArtifact?: (specializationKey: string) => MaterialRuntimeArtifact | undefined;
+    /** Production MaterialReady/Error lookup used by the record draw gate. */
+    readonly getMaterialReadiness?: (materialGuid: string) => MaterialReadiness | undefined;
+    readonly getMaterialShaderPipeline?: (materialShaderId: string, isHdr: boolean, renderState?: MaterialRenderState, topology?: PrimitiveTopology, indexFormat?: 'uint16' | 'uint32', variantSet?: string, passKind?: PassKind, meshAttributes?: import('@forgeax/engine-types').VertexAttributeMap, sampleCount?: number, colorFormatOverride?: GPUTextureFormat, shaderUvSetCount?: number, depthFormatOverride?: GPUTextureFormat | null, vertexLayout?: string, materialGuid?: string, fragmentEntry?: string, 
+    /** Geometry-owned immutable projection carried to the renderer PSO seam. */
+    vertexLayoutProjection?: VertexLayoutProjection) => RenderPipeline | null;
+    readonly getMaterialShaderBindingContract?: (materialShaderId: string) => 'group-0' | 'group-0-resource' | 'view-only' | 'view-with-resource' | 'render-material';
+    /**
+     * feat-20260527 M2 / w7: schema lookup for material param overlay.
+     * Returns the paramSchema for a registered material shader, or
+     * `undefined` when the shader is not in the ShaderRegistry.
+     * Record stage uses this instead of reading `MaterialSnapshot.paramSchema`.
+     */
+    readonly getParamSchema?: (materialShaderId: string) => readonly ParamSchemaEntry[] | undefined;
+    /**
+     * Runtime ParamSchema projection owner lookup. Registered shader consumers
+     * must prefer this immutable projection over deriving the same schema again.
+     * The optional seam keeps feature-only and legacy test runtimes compatible.
+     */
+    readonly getParamSchemaProjection?: (materialShaderId: string) => ImmutableParamSchemaProjection | undefined;
+    /**
+     * feat-20260621-learn-render-5-5-parallax M2 / w6 (D-1): the per-shader
+     * material BindGroupLayout for the given material shader. A custom shader
+     * declaring >3 user-region textures (e.g. parallax `heightTexture`) owns a
+     * material BGL whose entry count + injection start differ from the built-in
+     * 18-entry layout; the record stage must create the material bind group
+     * against THIS layout so the entry count matches. Returns `undefined` when
+     * the shader is unregistered or resolves to the shared built-in layout
+     * (3-texture shaders), in which case the caller falls back to
+     * `pipelineState.materialBindGroupLayout`.
+     */
+    readonly getMaterialBindGroupLayout?: (materialShaderId: string) => BindGroupLayout | undefined;
+    /**
+     * feat-20260527-sprite-nineslice M4 / w16 (D-5): per-Renderer metrics counter
+     * surfaced through `renderer.metrics`. Record-stage soft-warns (e.g.
+     * `nineslice.scale-too-small` when Transform.scale falls below the four
+     * 9-slice corner anchors) call `runtime.metrics.increment(name)` instead of
+     * a per-entity `console.warn` so AI users observe machine-readable counters
+     * (charter P3 over P-flooded text logs). Each Renderer owns its own
+     * EngineMetrics instance (D-5 candidate 1: multi-Renderer isolation).
+     */
+    readonly metrics: EngineMetrics;
+    /** Optional Render-owned membership timing capability. */
+    readonly membershipTiming?: MembershipTimingController | undefined;
+    /**
+     * feat-20260604-resource-owning-render-graph-and-fullscreen-postpr M3 / F-2 fix-up:
+     * post-process registry lookup. Returns the `PostProcessShaderEntry` registered
+     * via `renderer.postProcess.register(id, entry)`, or `undefined` when `id`
+     * resolves to no entry. `addFullscreenPass`'s execute closure dispatches on this
+     * to route to either the FXAA built-in path (id === 'fxaa') or the generic
+     * `buildFullscreenPostProcessPass + createFullscreenBindGroup` path; an
+     * unregistered id surfaces as a thrown `PostProcessError({code:'post-process-not-found'})`
+     * fail-fast (charter P3 / pipeline-errors throw template).
+     *
+     * Optional so a custom RenderSystemRuntime fixture (test doubles) need not
+     * supply it; the engine's own createRenderSystem populates it unconditionally.
+     */
+    readonly lookupPostProcess?: (id: string) => PostProcessShaderEntry | undefined;
+    /**
+     * feat-20260621-fullscreen-post-process-per-frame-uniform-params-l M-A2 / w8:
+     * per-shader params UBO accessor. Returns the eager-created (at register time,
+     * M-A1 / w5) GPU buffer for `id`, or `undefined` when the id has no params
+     * (param-less consumer) / is unregistered. dispatchFullscreenPass reads this to
+     * writeBuffer the per-frame snapshot bytes and bind the buffer at group(1)
+     * binding(2). Optional so test fixtures need not supply it; createRenderSystem
+     * populates it unconditionally (mirrors lookupPostProcess / getPostProcessPipeline).
+     */
+    readonly getPostProcessParamsBuffer?: (id: string) => Buffer | undefined;
+    /**
+     * feat-20260609-learn-render-4-5-framebuffers-demo-offscreen-rt-an M4 / T-10-a:
+     * post-process render-pipeline lookup with eager-on-first-call build. Returns a
+     * cached `RenderPipeline` (RHI handle) for `id`, lazily building on first call
+     * via the closure passed through `RenderSystemInternals.buildPostProcessPipeline`.
+     * Returns `null` when:
+     *   - the id is not registered in the post-process registry (caller skips the
+     *     pass — paired with the `'post-process-not-found'` throw site, this branch
+     *     is unreachable on the happy path)
+     *   - the underlying async shader-module compile is still pending (caller falls
+     *     back for one frame and retries on the next; mirrors the
+     *     `getMaterialShaderPipeline` 1-frame-warmup idiom)
+     *   - the pipeline build itself fails (caller skips the pass; the build path
+     *     fires a structured RhiError via errorRegistry; charter P3 explicit failure)
+     *
+     * Solves M1 CONCERN-1: the dispatcher in `dispatchFullscreenPass` previously
+     * passed `pipeline=null` to `built.createHandle` because the per-frame execute
+     * closure cannot await `createShaderModule` (async). With this lookup the
+     * dispatcher reads the pipeline synchronously; warm-up costs one frame.
+     *
+     * `bgl` is the fullscreen input-texture BGL the dispatcher already built via
+     * `buildFullscreenPostProcessPass`. The engine assumes a single static BGL
+     * shape (FULLSCREEN_BGL_DESCRIPTOR) so the pipeline cache keys on `id` only;
+     * subsequent calls reuse the cached pipeline regardless of which BGL identity
+     * is threaded.
+     *
+     * `colorFormat` is the swap-chain / target color format the post-process
+     * pipeline writes (`bgra8unorm-srgb` for swap-chain, the offscreen RT format
+     * otherwise). Cache key is `id|colorFormat`.
+     *
+     * Optional so a custom RenderSystemRuntime fixture (test doubles) need not
+     * supply it; the engine's own createRenderSystem populates it when
+     * `RenderSystemInternals.buildPostProcessPipeline` is provided.
+     */
+    readonly getPostProcessPipeline?: (id: string, bgl: BindGroupLayout, colorFormat: GPUTextureFormat) => RenderPipeline | null;
+    /**
+     * feat-20260623-world-space-video-asset M4 / w16 (D-3): transient per-frame
+     * texture store for VideoAsset sources. Independent of {@link gpuStore} — the
+     * record stage routes a `MaterialSnapshot.videoTextureFields` field through
+     * this store (per-frame copyExternalImageToTexture upload + current-frame view)
+     * instead of `gpuStore.ensureResident` (whose static cache video must never
+     * enter, AC-08). Optional so test fixtures that drive recordFrame manually
+     * need not supply one — a video field then degrades to the default view
+     * (charter P3). The production createRenderer always wires it.
+     */
+    readonly dynamicTextureStore?: DynamicTextureStore | undefined;
+}
+export interface RenderSystemInternals extends RenderSystemRuntime {
+    readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+    /** Optional feature host supplied by the renderer assembly layer. */
+    readonly featureHost?: RenderFeatureHost | undefined;
+    readonly shaderModuleFactory?: import('./pipeline-builder').PipelineBuilderShaderModuleFactory;
+    /** Optional host profiler capability for the existing Render path. */
+    readonly profiler?: Profiler | undefined;
+    readonly context: RhiCanvasContext | null;
+    readonly getPipelineState: () => PipelineState | null;
+    readonly assets: RenderAssetPort;
+    readonly gpuStore: GpuResourceStore;
+    readonly growMeshSsbo?: ((neededSlots: number) => {
+        readonly ok: true;
+    } | {
+        readonly ok: false;
+        readonly code: 'mesh-ssbo-ceiling-reached' | 'mesh-ssbo-capacity-exceeded';
+        readonly degradedToSlotCount: number;
+    }) | undefined;
+    readonly meshSsboState?: {
+        readonly slotCount: number;
+    } | undefined;
+    /**
+     * feat-20260609 M4 / T-10-a: factory backing `getPostProcessPipeline`. Provided
+     * by `createRenderer.ts` (it owns the shared `getShaderModuleAdapter` and the
+     * fullscreen pipeline-layout builder); receives a registered
+     * `PostProcessShaderEntry` + the fullscreen BGL the dispatcher already
+     * composed + the target color format, returns a built `RenderPipeline`
+     * (RHI handle) or `null` (shader still compiling / build failed). The first
+     * call per id triggers the async shader compile; subsequent calls hit the
+     * RenderSystem-level cache and never reach this factory.
+     *
+     * Optional so test fixtures (createRenderSystem with a stub
+     * RenderSystemInternals) need not provide a real factory; without it
+     * `getPostProcessPipeline` resolves to `undefined` on the runtime surface
+     * and the dispatcher falls through to its existing `null`-skip branch.
+     */
+    readonly buildPostProcessPipeline?: ((entry: PostProcessShaderEntry, bgl: BindGroupLayout, colorFormat: GPUTextureFormat, label: string) => RenderPipeline | null) | undefined;
+}
+export interface RenderFeatureGraphRuntimeState {
+    contributions: readonly RenderFeatureGraphContribution<RenderFeaturePassContext>[];
+    topologySignature: string | undefined;
+    composition: RenderFeatureGraphComposition<RenderPipelineContext, RenderFeaturePassContext> | undefined;
+}
+export declare function getRenderFeatureGraphState(internals: RenderSystemInternals): RenderFeatureGraphRuntimeState;
+export declare function reportRenderFeatureGraphError(internals: RenderSystemInternals, error: RenderError): void;
+export interface PipelineState {
+    readonly format: string;
+    readonly colorAttachmentFormat: string;
+    readonly viewBindGroupLayout: BindGroupLayout;
+    readonly materialBindGroupLayout: BindGroupLayout;
+    readonly meshBindGroupLayout: BindGroupLayout;
+    readonly viewUniformBuffer: Buffer;
+    readonly shadowCasterCascadeBuffer: Buffer;
+    readonly materialUniformBuffer: {
+        readonly buffer: Buffer;
+        readonly sizeInBytes: number;
+    };
+    readonly meshStorageBuffer: {
+        readonly buffer: Buffer;
+        readonly sizeInBytes: number;
+    };
+    readonly pointLightsBuffer: Buffer;
+    readonly spotLightsBuffer: Buffer;
+    readonly instancesBindGroupLayout: BindGroupLayout;
+    readonly identityInstanceBuffer: Buffer;
+    readonly defaultSampler: Sampler;
+    readonly nearestSampler: Sampler;
+    readonly fallbackTextureView: TextureView;
+    readonly unlitPipeline: RenderPipeline | null;
+    readonly standardPipeline: RenderPipeline | null;
+    /**
+     * feat-20260604-learn-render-4.10-anti-aliasing-msaa M2 / w8: count=4
+     * multisample variants of the 7 geometry pipelines that write the screen
+     * or HDR colour target. A pipeline's `multisample.count` must match the
+     * sampleCount of the colour attachment it writes (WebGPU validation),
+     * so a count=4 pass cannot reuse a count=1 pipeline -- the record stage
+     * picks the `*Msaa` variant when the active camera carries
+     * `antialias === 'msaa'`. Post-process + shadow pipelines stay single-
+     * sample (AC-06) and have no MSAA variant. `null` when the base pipeline
+     * is null (empty-manifest path).
+     */
+    readonly unlitPipelineMsaa: RenderPipeline | null;
+    readonly standardPipelineMsaa: RenderPipeline | null;
+    readonly unlitPipelineHdrMsaa: RenderPipeline | null;
+    readonly standardPipelineHdrMsaa: RenderPipeline | null;
+    /**
+     * feat-20260523-shader-template-instance-split M9-T03 (D-PipelineBuilder):
+     * the shared 4-BindGroupLayout chain pipeline layout (`[view, material,
+     * mesh-array, instances]`) -- same handle the standard / unlit / sprite
+     * pipelines share. M9 exposes it on PipelineState so the per-MaterialShader
+     * pipeline cache (`getMaterialShaderPipeline`) can reuse it at lazy build
+     * time without re-running pbrLayouts construction (charter P4 consistent
+     * abstraction). `null` when the manifest is empty (Camera-only / clear-
+     * pass-only path; bug-20260519 D-3 nullable).
+     */
+    readonly pbrPipelineLayout: PipelineLayout | null;
+    /**
+     * feat-20260609-hdrp-cluster-fragment-ggx M4.5 / w36 (D-10 option A):
+     * per-variant PipelineLayout for HDRP. Mirrors `pbrPipelineLayout` but
+     * substitutes the HDRP unified 7-slot group(2) BGL
+     * (`createHdrpBindGroupLayoutDescriptor`) for the 1-slot pbr-mesh-array
+     * BGL. Built once at boot and reused for any HDRP variant PSO. `null`
+     * when the manifest is empty (parallel to `pbrPipelineLayout`) or when
+     * the boot-time createBindGroupLayout / createPipelineLayout fails (in
+     * which case `selectPipelineLayoutForVariant` falls back to the URP
+     * `pbrPipelineLayout` instead of hard-disabling the build path).
+     */
+    readonly hdrpPbrPipelineLayout: PipelineLayout | null;
+    /** WebGPU storage-path producer for ordered HDRP cluster memberships. */
+    readonly hdrpClusterMembershipPipeline: ComputePipeline | null;
+    /** Compute bind-group layout paired with the membership producer pipeline. */
+    readonly hdrpClusterMembershipBindGroupLayout: BindGroupLayout | null;
+    /**
+     * bug-20260611-skin-pipeline-layout: dedicated PipelineLayout for the
+     * `forgeax::pbr-skin` material shader. Mirrors `pbrPipelineLayout` but
+     * substitutes a 3-entry mesh-array BGL (binding 0 = meshes, bindings 1/2 =
+     * current/previous palettes) for standard PBR's 1-entry mesh-array BGL. Built once at boot
+     * by `buildPbrSkinLayouts` and selected by
+     * `selectPipelineLayoutForVariant` when the caller passes
+     * `LayoutKind = 'pbr-skin'`. `null` when manifest is empty or the skin
+     * shader is not registered (storage-buffer cap gate / register failure);
+     * `selectPipelineLayoutForVariant` returns `null` rather than silently
+     * falling back to URP layout (charter P3 explicit failure, mirroring the
+     * `hdrp-active-must-not-fallback-to-urp-pipeline` guard).
+     */
+    readonly pbrSkinPipelineLayout: PipelineLayout | null;
+    /**
+     * feat-20260611 R2 / M8 / w28 (IS-14): record-stage handle to the
+     * 3-binding `pbr-skin-mesh-array-bgl` returned by `buildPbrSkinLayouts`
+     * (binding 0 mesh-array UBO, bindings 1/2 current/previous palette UBOs;
+     * all `hasDynamicOffset: true`). The record stage builds a BG against this
+     * BGL for skin entries (`entry.source.skin !== undefined`) and binds it
+     * at group(2) when the entry's pipeline layout is `pbr-skin-pl`. The
+     * URP path keeps using `meshBindGroupLayout` (1-binding) at group(2),
+     * so `pbr-mesh-array-bgl` is unchanged. Stays `null` when
+     * `pbrSkinPipelineLayout` itself failed to build (charter P3 explicit
+     * failure -- skin path is hard-disabled, mirroring the pipeline-layout
+     * fallback in `selectPipelineLayoutForVariant`).
+     */
+    readonly pbrSkinMeshBindGroupLayout: BindGroupLayout | null;
+    /**
+     * feat-20260612-skin-palette-per-frame-upload M1 / m1-2: animator-ready
+     * skin-palette storage allocator. Replaces the prior identity-buffer
+     * stub (PR #353 / feat-20260611 R2 / M8 / w28 IS-14) -- a single 16320 B
+     * identity-seeded UBO shared by every skin entry. The allocator owns the
+     * lifecycle of the per-frame palette buffer (`createSkinPaletteAllocator`
+     * from `./systems/skin-palette-allocator`); the record stage reads the
+     * GPU buffer through `skinPaletteAllocator.buffer` and the extract stage
+     * (M2) calls `allocateSlice` + `writeJointPalette` to land animated
+     * palette data per skinned entity. Per plan-strategy D-1 candidate (b) the
+     * allocator is the single authoritative carrier -- no parallel fallback
+     * stub. `null` when `pbrSkinPipelineLayout` itself failed (skin path
+     * hard-disabled, mirroring the prior stub field's gating).
+     */
+    readonly skinPaletteAllocator: SkinPaletteAllocator | null;
+    readonly defaultWhiteTextureView: TextureView;
+    readonly defaultNormalTextureView: TextureView;
+    readonly unlitPipelineHdr: RenderPipeline | null;
+    readonly standardPipelineHdr: RenderPipeline | null;
+    /**
+     * feat-20260520-directional-light-shadow-mapping M2 / w14 (D-1):
+     * 1x1 depth32float fallback bound at viewBindGroup binding(3) when no
+     * shadow RT exists (castShadow:false or allocation failed).
+     * Cleared to 1.0 (far plane) so comparison-sampler always returns fully lit.
+     */
+    readonly shadowFallbackTextureView: TextureView;
+    /**
+     * feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1: 1x1x6
+     * depth32float `texture_depth_cube_array` (layers=1) fallback bound at
+     * viewBindGroup binding(5) when no PointLightShadow snapshots are active
+     * (zero-shadow scene = AC-09 zero allocation -- the real cube_array atlas
+     * stays in `ShadowAtlas` and is only allocated when the extract stage
+     * sees its first PointLightShadow). Cleared to 1.0 so the
+     * comparison-sampler returns fully lit on the no-shadow path. The view
+     * dimension is `cube-array` to satisfy the BGL `viewDimension:
+     * 'cube-array'`; the underlying texture has 6 layers (one cube).
+     */
+    readonly shadowAtlasFallbackTextureView: TextureView;
+    /**
+     * feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1: 64 B uniform
+     * buffer carrying `array<vec4<f32>, 4>` -- one lane per shadow-casting
+     * point light slot. Lane N stores `(near, far, 1/(far-near), 0)` for the
+     * point light with `shadowAtlasLayer === N`. Lanes for non-shadow-casting
+     * slots stay zeroed; the WGSL sample path is gated by
+     * `PointLight.shadowAtlasLayer >= 0` so zeroed lanes are never read.
+     * Bound at viewBindGroup binding(6); written per frame from the
+     * `pointShadowSnapshots` array.
+     */
+    readonly shadowParamsBuffer: Buffer;
+    readonly shadowProbePipeline: RenderPipeline | null;
+    readonly shadowProbeBindGroupLayout: BindGroupLayout | null;
+    readonly shadowProbeLsmUbo: Buffer | null;
+    readonly shadowProbeInputBuf: Buffer | null;
+    readonly shadowProbeOutputTex: any | null;
+    readonly shadowProbeOutputView: TextureView | null;
+    readonly shadowProbeStagingBuf: Buffer | null;
+    /**
+     * Fallback Skylight resource bundle (feat-20260520-skylight-ibl-cubemap
+     * M2 round-2 / t40, plan-strategy D-5). 1x1 all-zero rgba16float
+     * texture_cube * 2 (irradiance + prefilter) + 1x1 approximate rg16float
+     * brdfLut + intensity=0 16 B uniform buffer + 7-entry BindGroup compose
+     * the @group(4) skylight binding for the "no Skylight ECS entity"
+     * branch. The M4 round-2 recordFrame branch binds `bindGroup` when
+     * `skylightCount === 0` so `standardPipeline` / `standardPipelineHdr`
+     * (which keep a 4-slot pipeline layout per D-5 round-4) dispatch with
+     * ambient=0 -- physical convergence with D-4 (charter F1: AI users
+     * writing demos do not need a "is there a skylight?" branch).
+     *
+     * D-5 round-4: the fallback bundle no longer carries a stand-alone
+     * BindGroup. The PBR material BindGroupLayout now holds 14 entries
+     * (material 0..6 + Skylight 7..13) and the per-frame material
+     * BindGroup assembly site (render-system-record) merges Skylight
+     * resources at binding 7..13 -- active when a Skylight component
+     * exists, fallback identity when `skylightCount === 0`.
+     *
+     * bug-20260519 D-3 nullable extension: the empty-manifest path
+     * (Camera-only / clear-pass-only) skips the entire PBR pipeline build
+     * block; we still allocate the fallback bundle in the normal path,
+     * but tests / OOS paths that mock the manifest empty land here with
+     * `null` (charter P3 explicit failure: M4 record-stage gates on
+     * `skylightFallback !== null` before binding fallback resources at
+     * material BG entries 7..13).
+     */
+    readonly skylightFallback: any | null;
+    /**
+     * feat-20260529-rendergraph-pass-abstraction M3 / w11 (D-2 + Finding 3):
+     * per-pass mutable texture cache slots extracted from the global
+     * PipelineState. These fields are the lazily-allocated texture attachments
+     * + pass-specific pipelines and bindgroups that belong to a single render
+     * pass (depth / shadow / tonemap / FXAA). M4 render-graph resource
+     * declarations will read these descriptors to derive transient/persistent
+     * resources; shadow probe (OOS-4) stays on PipelineState directly.
+     */
+    readonly perPassResources: PerPassResources;
+}
+/**
+ * Configure a canvas surface from the two PipelineState format fields, applying
+ * the WebGL2-fallback gate: native WebGPU uses the storage format plus an sRGB
+ * view format, while the wgpu WebGL2 surface uses its direct sRGB format and
+ * COLOR_TARGET-only usage because its GLES surface rejects COPY_SRC. The
+ * storage-buffer capability still controls TEXTURE_BINDING usage, but it does
+ * not determine whether native WebGPU supports viewFormats. Single SSOT for
+ * the configure descriptor consumed by both the
+ * lazy first-frame path (ensureContextConfigured in createRenderer.ts) and the
+ * F2 surface-outdated reconfigure-and-retry branch (render-system-record.ts) so
+ * the two cannot drift (architecture-principles #1 SSOT). Returns the configure
+ * Result; callers own the `state.perPassResources.configured` flag + the
+ * `__forgeaxSwapChainFormat` probe write (those differ per call site).
+ */
+export declare function configureSurface(context: RhiCanvasContext, device: RhiDevice, format: string, colorAttachmentFormat: string): Result<void, RhiError>;
+/**
+ * feat-20260529-rendergraph-pass-abstraction M3 / w11 (D-2):
+ * per-pass mutable resource slots extracted from PipelineState per
+ * research Finding 3 fact-based grouping (depth / shadow / tonemap / fxaa).
+ * These fields are the lazily-allocated texture caches + pass-specific
+ * pipeline/bindgroup handles that belong to a single render pass.
+ * Mutable (non-readonly) because the record stage writes back after
+ * lazy-alloc on size drift.
+ */
+export interface PerPassResources {
+    /**
+     * Per-frame depth attachment. Lazily allocated by
+     * `ensureContextConfigured` and recreated whenever the canvas resizes
+     * (see `ensureDepthTexture` in createRenderer.ts). Bound at the
+     * `beginRenderPass.depthStencilAttachment` slot with `depthLoadOp:'clear'`
+     * + `clearValue:1` so each frame starts with a far-plane depth buffer
+     * and the back-face / inside-of-cube fragments are correctly occluded
+     * (bug-20260519).
+     *
+     * `depthTextureView` is `null` until the canvas dimensions are known
+     * (first draw); the record stage skips the frame and fires
+     * `webgpu-runtime-error` if it stays null past configure.
+     */
+    depthTexture: any | null;
+    depthTextureView: any | null;
+    depthTextureWidth: number;
+    depthTextureHeight: number;
+    configured: boolean;
+    /**
+     * Lazy HDR colour + depth attachments for the opt-in tonemap path. Both
+     * are `null` until the first frame whose active camera carries
+     * `tonemap !== 'none'`; the record stage allocates them at the swap-chain
+     * size and re-creates on resize (mirrors `depthTexture` / `depthTextureView`
+     * idiom; AC-12).
+     *
+     * `hdrColor`'s format is `rgba16float` (AC-03(d)); the depth attachment is
+     * the same `depth24plus-stencil8` format the geometry pipelines already declare
+     * (`DEPTH_TEXTURE_FORMAT` SSOT in `createRenderer.ts`). When a camera
+     * downgrades to `tonemap === 'none'` between frames the textures stay
+     * allocated for cheap re-opt-in; full dispose happens via
+     * `Renderer.dispose()` -> browser GC (matches the `depthTexture` fix-f6
+     * placeholder).
+     */
+    hdrColorTexture: any | null;
+    hdrColorView: any | null;
+    hdrDepthTexture: any | null;
+    hdrDepthView: any | null;
+    hdrTextureWidth: number;
+    hdrTextureHeight: number;
+    /**
+     * feat-20260604 M2 / w10: sampleCount the `hdrDepth` attachment was last
+     * allocated at (1 or 4). The HDR colour target is always sampled
+     * single-sample (`hdrColorView`); the depth pairs with the geometry colour
+     * target's sampleCount, which flips with `antialias === 'msaa'`. Tracking it
+     * lets the record stage reallocate depth when MSAA toggles between frames
+     * (a stale count=4 depth under a count=1 pipeline fails WebGPU validation).
+     */
+    hdrDepthSampleCount: number;
+    readonly fxaaPipeline: RenderPipeline | null;
+    readonly fxaaBindGroupLayout: BindGroupLayout | null;
+    readonly fxaaSampler: Sampler | null;
+    /** Fixed two-attachment linear TAA resolve resources, owned by this renderer. */
+    readonly taaResolvePipeline: RenderPipeline | null;
+    readonly taaResolveBindGroupLayout: BindGroupLayout | null;
+    readonly taaResolveSampler: Sampler | null;
+    taaResolveParamsBuffer: Buffer | null;
+    msaaColorTexture: any | null;
+    msaaColorView: any | null;
+    msaaSpriteColorTexture: any | null;
+    msaaSpriteColorView: any | null;
+    msaaDepthTexture: any | null;
+    msaaDepthView: any | null;
+    msaaTextureWidth: number;
+    msaaTextureHeight: number;
+    hdrColorMsaaTexture: any | null;
+    hdrColorMsaaView: any | null;
+    readonly skyboxPipeline: RenderPipeline | null;
+    readonly skyboxPipelineMsaa: RenderPipeline | null;
+    readonly skyboxBindGroupLayout: BindGroupLayout | null;
+    readonly skyboxSampler: Sampler | null;
+    /** Stable 16 B quaternion UBO updated by the skybox record pass. */
+    readonly skyboxRotationBuffer: Buffer | null;
+    /** Executable analytic-atmosphere producer and background resources. */
+    readonly atmosphereCubemapPipeline?: RenderPipeline | null;
+    readonly atmosphereCubemapBindGroupLayout?: BindGroupLayout | null;
+    readonly atmosphereIrradiancePipeline?: RenderPipeline | null;
+    readonly atmospherePrefilterPipeline?: RenderPipeline | null;
+    readonly atmosphereIblParamsBindGroupLayout?: BindGroupLayout | null;
+    readonly atmosphereIblSkyBindGroupLayout?: BindGroupLayout | null;
+    readonly atmosphereBackgroundPipeline?: RenderPipeline | null;
+    readonly atmosphereBackgroundBindGroupLayout?: BindGroupLayout | null;
+    readonly atmosphereParamsBuffer?: Buffer | null;
+    readonly atmosphereCubeVertexBuffer?: Buffer | null;
+    shadowTexture: any | null;
+    shadowMapSize: number;
+    shadowCascadeCount: number;
+    /** Exact dimensions of the compiled directional cascade atlas. */
+    shadowAtlasWidth: number;
+    shadowAtlasHeight: number;
+    shadowSampler: any | null;
+    /**
+     * feat-20260520-directional-light-shadow-mapping M1c / w11 +
+     * feat-20260613-csm-cascaded-shadow-maps M5 / w28:
+     * latest cascade-0 lightViewProj mat4 (16 f32, col-major). Kept under
+     * the legacy field name as an Inspector backward-compat surface
+     * (`runtime.lights.directionalShadow.lightSpaceMatrix` JSON-RPC), per
+     * AGENTS.md §Change stance exception for external-visible wire
+     * protocols with known downstream consumers. Populated each frame
+     * from `lights.lightViewProj[0]`. Null before the first extract with
+     * an active shadow-casting DirectionalLight.
+     */
+    shadowLightSpaceMatrix: Float32Array | null;
+    /**
+     * feat-20260613-csm-cascaded-shadow-maps M5 / w28: full 4-cascade
+     * lightViewProj concatenation (4 × 16 = 64 f32, col-major) consumed by
+     * `debugSampleShadowFactor` so the probe can project against the selected
+     * cascade. Null before the first extract
+     * with an active shadow-casting DirectionalLight.
+     */
+    shadowCsmLightViewProj: Float32Array | null;
+    /**
+     * Producer-owned CSM receiver-selection facts. The debug probe must use the
+     * same view-space depth + split-plane selector as the main receiver path;
+     * keeping the two inputs together prevents a selector mirror from silently
+     * drifting at cascade boundaries.
+     */
+    shadowCsmSelection: {
+        readonly viewMatrix: Float32Array;
+        readonly splitPlanes: Float32Array;
+        readonly cascadeBlend: number;
+    } | null;
+    /** Producer-owned directional shadow comparison parameters for GPU probes. */
+    shadowLightDirection: Float32Array | null;
+    shadowDepthBias: number;
+    shadowNormalBias: number;
+    shadowPcfKernelSize: number;
+    readonly bloomBrightPipeline: RenderPipeline | null;
+    readonly bloomBlurHPipeline: RenderPipeline | null;
+    readonly bloomBlurVPipeline: RenderPipeline | null;
+    readonly bloomCompositePipeline: RenderPipeline | null;
+    readonly bloomBrightBindGroupLayout: BindGroupLayout | null;
+    readonly bloomBlurBindGroupLayout: BindGroupLayout | null;
+    readonly bloomCompositeBindGroupLayout: BindGroupLayout | null;
+    readonly bloomSampler: Sampler | null;
+    readonly bloomBrightParamsBuffer: Buffer | null;
+    readonly bloomBlurHParamsBuffer: Buffer | null;
+    readonly bloomBlurVParamsBuffer: Buffer | null;
+    readonly bloomCompositeParamsBuffer: Buffer | null;
+    bloomBrightTexture: any | null;
+    bloomBrightView: any | null;
+    bloomBrightWidth: number;
+    bloomBrightHeight: number;
+    bloomBlurHTexture: any | null;
+    bloomBlurHView: any | null;
+    bloomBlurHWidth: number;
+    bloomBlurHHeight: number;
+    bloomBlurVTexture: any | null;
+    bloomBlurVView: any | null;
+    bloomBlurVWidth: number;
+    bloomBlurVHeight: number;
+    readonly ssaoCalcPipeline: RenderPipeline | null;
+    readonly ssaoBlurPipeline: RenderPipeline | null;
+    readonly ssaoBgl: BindGroupLayout | null;
+    /** Filtering sampler shared by ssao_noise_sampler (binding 3) + ssaoSampler (binding 8). */
+    ssaoFilteringSampler: Sampler | null;
+    /** Non-filtering sampler dedicated to hdr_depth (binding 6); WebGPU validation. */
+    ssaoDepthSampler: Sampler | null;
+    /** 1x1 fallback view bound at ssaoRaw (binding 7) in the calc pass. */
+    ssaoFallbackRawView: any | null;
+}
+export interface MeshGpuHandles {
+    /**
+     * Vertex buffer wrapped as a GpuBuffer (M-3 / w11). Consumers reach the
+     * raw RHI Buffer via `.handle` for `setVertexBuffer` etc.; `.destroy()`
+     * routes through the RHI shim's lifecycle SSOT (charter §F1 single-entry
+     * indexability + plan-strategy D-9 wrapper migration).
+     */
+    readonly vertexBuffer: GpuBuffer;
+    /**
+     * Index buffer wrapper, or `null` for a vertex-only mesh (no
+     * `MeshAsset.indices`). When `null` the record stage takes the non-indexed
+     * `pass.draw(vertexCount)` path and never calls `setIndexBuffer`. Gated
+     * on `indexed` below.
+     */
+    readonly indexBuffer: GpuBuffer | null;
+    /** Allocation byte size of the vertex buffer (mirrors GPUBuffer.size). */
+    readonly vboBytes: number;
+    /** Allocation byte size of the index buffer, or 0 when `indexBuffer` is null. */
+    readonly iboBytes: number;
+    readonly indexCount: number;
+    /**
+     * Index buffer format inferred from the source `MeshAsset.indices` typed
+     * array (`Uint16Array` -> `'uint16'`, `Uint32Array` -> `'uint32'`). The
+     * record stage threads this into `pass.setIndexBuffer(..., format)` so
+     * the GPU reads the correct stride per index. bug-20260519: the prior
+     * hard-coded `'uint16'` corrupted procedural meshes whose factories
+     * (`createBoxGeometry` etc) emit Uint32Array indices.
+     */
+    readonly indexFormat: 'uint16' | 'uint32';
+    /** Geometry-owned immutable projection carried through every GPU consumer. */
+    readonly layoutProjection: VertexLayoutProjection;
+    /**
+     * Vertex count is derived from the projection stride at upload time. The
+     * non-indexed draw path passes this to `pass.draw(vertexCount)`.
+     */
+    readonly vertexCount: number;
+    /**
+     * True when the mesh carries an index buffer (`MeshAsset.indices` present).
+     * `false` for vertex-only meshes. The record stage branches on this to pick
+     * `drawIndexed` vs `draw` and to gate `setIndexBuffer`.
+     */
+    readonly indexed: boolean;
+    /**
+     * Primitive topology of this mesh (first submesh's topology, default
+     * 'triangle-list'). WebGPU bakes topology into the immutable PSO, so the
+     * record stage threads this into `getMaterialShaderPipeline` to select a
+     * per-topology PSO (feat-20260604 M3 / w9).
+     *
+     * feat-20260608 M4 / w16: topology is per-submesh; this field reflects
+     * `submeshes[0].topology` for backward compat. Use `submeshes` field for
+     * per-submesh draw iteration.
+     */
+    readonly topology: PrimitiveTopology;
+    /**
+     * Submeshes from MeshAsset.submeshes, carried through from the GPU store
+     * so the record stage can iterate per-submesh drawIndexed (feat-20260608 M4 / w16).
+     */
+    readonly submeshes: readonly import('@forgeax/engine-types').Submesh[];
+}
+export declare function createRenderSystem(internals: RenderSystemInternals): RenderSystem;
+//# sourceMappingURL=render-system.d.ts.map