@forgeax/engine-render 0.1.4 → 0.1.7

package/dist/render-system.d.ts

@@ -1,44 +1,18 @@
 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 { RenderReadLease } from '@forgeax/engine-ecs/projection';
+import { type Result } from '@forgeax/engine-rhi';
+import { type RenderPipelineAsset } from '@forgeax/engine-types';
+import { type ObservationUnavailableError } from './errors/render';
 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 { RenderSceneInspection } from './inspection-types';
+import type { PointsLinesRetainedSnapshot } from './points-lines/snapshot';
+export type { RenderSceneInspection } from './inspection-types';
 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;
+import { type FrameObservation, type FrameObservationOptions } from './record/frame';
+import type { RenderSystemInternals } from './record/render-context';
+import { type DrawOwnerOptions } from './render-contract';
+export type { _InternalRenderPipelineContext, _StandardForwardSceneView, PerPassResources, PipelineState, RenderSystemInternals, RenderSystemRuntime, SurfaceBackendKind, SwapChainFormatPair, } from './record/render-context';
+export { configureSurface, MATERIAL_PER_ENTITY_STRIDE, resolveSurfaceFormatPair, STANDARD_PBR_UBO_SIZE, selectSwapChainFormat, } from './record/render-context';
 /**
  * Engine-internal Extract / Prepare / Record driver; constructed by createRenderer.
  *
@@ -57,15 +31,9 @@ export declare const MATERIAL_PER_ENTITY_STRIDE = 512;
  */
 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;
+    draw(worlds: readonly World[], opts: DrawOwnerOptions, renderReadLeases?: readonly RenderReadLease[]): boolean;
     /** Release renderer-owned persistent state for one detached World. */
-    detachWorld(world: World): void;
+    detachScene(world: World): void;
     /** Release the profiler catalog contribution owned by this RenderSystem. */
     releaseProfilerCatalog(): void;
     observeCurrentFrame(options: FrameObservationOptions): Promise<Result<FrameObservation, ObservationUnavailableError>>;
@@ -86,6 +54,8 @@ export interface RenderSystem {
     };
     /** Persistent scene maintenance evidence from the ordinary single-World path. */
     readonly renderScene: RenderSceneInspection;
+    /** Retained Points/Lines authoring facts from the single scene projection. */
+    readonly pointsLinesSnapshots: readonly PointsLinesRetainedSnapshot[];
     /** Current mesh-slot provenance and active diagnostics from the last frame. */
     readonly meshMaterialBindings: readonly MeshMaterialBindingObservation[];
     /**
@@ -116,45 +86,10 @@ export interface RenderSystem {
         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;
-    };
+    /** Configure the sole Standard graph owner before the first frame. */
+    configureStandard(config: RenderPipelineAsset['config']): void;
+    /** Register one engine-owned post-process shader used by the Standard lane. */
+    registerBuiltinPostProcess(id: string, entry: PostProcessShaderEntry): () => void;
     /**
      * feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle / M5 / w21:
      * release the per-RenderSystem frame-state GPU bookkeeping during
@@ -178,637 +113,13 @@ export interface RenderSystem {
      * 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;
 }
+export declare function createRenderSystem(internals: RenderSystemInternals): RenderSystem;
 /**
- * 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.
+ * Package-private extension consumed by the built-in record closures only.
+ * Custom pipeline authors see the leaf RenderPipelineContext contract and
+ * never this surface.
  */
-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