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

package/dist/record/frame-snapshot.d.ts

@@ -0,0 +1,429 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { ResolvedColorTargetDescriptor } from '@forgeax/engine-render-graph';
+import type { Texture } from '@forgeax/engine-rhi';
+import type { ClusterBinScratch } from '../cluster-binner';
+import type { GpuBuffer } from '../gpu-resource';
+/**
+ * feat-20260708-composited-multi-world-rendering M1 / D-1 / D-9:
+ * worldId-entityKey composite key helper. Formula: `worldId * 2^32 + entityKey`.
+ *
+ * worldId is the index into `worlds[]` (the `draw` call argument). entityKey
+ * is the packed Entity u32 (encodeEntity(indexSlot, generation)) surfaced
+ * through `RenderableSnapshot.entityKey`.
+ *
+ * Key properties:
+ *   - worldId=0 identity: `worldEntityKey(0, k) === k` — single-world path
+ *     cache behavior is bit-for-bit unchanged (AC-03 regression guarantee).
+ *   - JS safe integer: worldId < 2^21 keeps the composite key below
+ *     Number.MAX_SAFE_INTEGER (2^53).
+ *   - SSOT: all cache-key compositing consumers import this single helper;
+ *     no inline `worldId * 2^32 + k` duplication (D-9).
+ *
+ * @internal — exported for unit test + glyph/tilemap/record consumers;
+ * not part of the public @forgeax/engine-runtime API surface.
+ */
+export declare function worldEntityKey(worldId: number, entityKey: number): number;
+/**
+ * Cross-frame cache entry for a material bind group whose source material and
+ * all resolved GPU resources are stable. The material snapshot identity is
+ * the extract-layer invalidation token; the builder only stores entries after
+ * all explicit resource handles resolved to resident GPU objects.
+ */
+export interface MaterialBgAssemblyCacheEntry {
+    readonly material: MaterialSnapshot;
+    /** Invalidates when a texture/sampler residency identity changes. */
+    readonly materialResourceEpoch: number;
+    readonly materialBgl: BindGroupLayout;
+    /** Buffer identity changes when the shared material capacity grows. */
+    readonly materialBuffer: Buffer;
+    readonly skylightResources: SkylightBindGroupResources;
+    readonly bindGroup: BindGroup;
+}
+import type { CompiledRenderGraph } from '@forgeax/engine-render-graph';
+import type { BindGroup, BindGroupLayout, Buffer, TextureView } from '@forgeax/engine-rhi';
+import type { MaterialRenderState, RenderPipelineAsset } from '@forgeax/engine-types';
+import type { MeshGpuHandles } from '../device/gpu-residency';
+import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
+import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
+import type { CameraSnapshot } from '../render-contract';
+import type { RenderPipeline as RenderPipelineDef, RenderPipelineFrame } from '../render-pipeline';
+import type { MaterialSnapshot, PointShadowSnapshot, RenderableSnapshot, SpotLightSnapshot } from '../render-system-extract';
+import type { ShadowAtlas } from '../shadow-atlas';
+/**
+ * feat-20260608-create-app-param-surface-trim / M1 / D-8 (q8 user lock):
+ * fallback clear color when the world carries no Camera entity. Opaque
+ * black `[0, 0, 0, 1]`, replacing the historical
+ * `[0.06, 0.06, 0.08, 1.0]` dark-slate sentinel. Single SSOT consumed by
+ * the synthetic CameraSnapshot built when `cameras.length === 0`
+ * (Case B in `recordFrame`) and read directly by tests
+ * (`zero-camera-clear-fallback.test.ts`). AC-05.
+ */
+export declare const ZERO_CAMERA_CLEAR_FALLBACK: readonly [number, number, number, number];
+export interface FrameObservationSource {
+    readonly texture: Texture;
+    readonly descriptor: ResolvedColorTargetDescriptor;
+    readonly frameId: number;
+    readonly pipelineId: 'forgeax::standard';
+    readonly backendId: string;
+}
+/**
+ * Build a synthetic CameraSnapshot the record stage uses when the world
+ * carries no Camera entity. Identity-shaped projection / view inputs
+ * keep the existing matrix math numerically stable; clear-color quartet
+ * sourced from `ZERO_CAMERA_CLEAR_FALLBACK` so the swap-chain still
+ * paints `[0, 0, 0, 1]` (AI-user friendly observable signal that the
+ * `'render-system-no-camera'` diagnostic fired without leaving stale
+ * pixels on screen).
+ */
+export declare function makeZeroCameraFallbackSnapshot(): CameraSnapshot;
+export declare function clampPcfKernelSize(value: number | undefined): number;
+/**
+ * Per-RenderSystem mutable frame state.
+ *
+ * Owned by the `createRenderSystem` closure; advanced once per
+ * `recordFrame` invocation. The `instanceBuffers` map holds the per-entity
+ * GPU storage buffers for Instances-bearing entities (cache key = the
+ * packed Entity u32 surfaced via `InstancesSnapshot.cacheKey`); entries
+ * are recreated when the `archVersion` bumps or `byteLength` changes.
+ *
+ * feat-20260518-pbr-direct-lighting-mvp M3 / w14 (AC-17 a): the
+ * `warnedZeroLightStandard` flag latches the first-frame warning that
+ * fires when the world contains a StandardMaterial entity but zero
+ * DirectionalLight entries — once latched the next 100 frames suppress
+ * the warning so the AI user is not flooded with repeated noise (charter
+ * P3 silent failure -> explicit warning at most once per RenderSystem
+ * lifetime).
+ */
+export interface RenderFrameState {
+    frameNumber: number;
+    /** Optional graph resource lookup used by low-level record helpers and tests. */
+    readonly perFrameGraph?: {
+        readonly getColorTargetDescriptor: (key: string) => ResolvedColorTargetDescriptor | undefined;
+        readonly getColorTargetView: (key: string) => TextureView | undefined;
+        readonly getColorTargetTexture: (key: string) => Texture | undefined;
+    } | null;
+    /** Last successfully rendered static directional shadow atlas token. */
+    directionalShadowCache: DirectionalShadowCache | null;
+    /** Set by a directional shadow pass when this frame refreshed the atlas. */
+    directionalShadowCacheRecorded: boolean;
+    /** The sole compiled owner for compute, copy, feature, and raster work. */
+    compiledFrameGraph: CompiledRenderGraph<RenderPipelineFrame> | null;
+    compiledFrameGraphTopologyKey: string | null;
+    readonly retiredCompiledFrameGraphs: Set<CompiledRenderGraph<RenderPipelineFrame>>;
+    /** Physical outputs projected by typed graph passes for downstream observers. */
+    currentFrameObservationSource: FrameObservationSource | undefined;
+    currentDirectionalShadowView: TextureView | null;
+    currentSpotShadowView: TextureView | null;
+    readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;
+    /** Per-entity vertex buffers for the Standard CPU morph lane. */
+    readonly morphBuffers?: Map<number, MorphBufferCacheEntry>;
+    readonly hdrpClusterBinScratch: ClusterBinScratch;
+    /** Reusable HDRP cluster output buffers; sized once and grown only if the grid/cap changes. */
+    hdrpClusterGridScratch: Uint32Array | null;
+    hdrpLightIndexListScratch: Uint32Array | null;
+    /** Compute bind group for the optional WebGPU HDRP membership producer. */
+    hdrpClusterMembershipBindGroup: BindGroup | null;
+    transientInstanceBuffers: InstanceBufferCacheEntry[];
+    warnedZeroLightStandard: boolean;
+    /**
+     * feax-20260608-multi-light-warn-once M3: once-warn latch for multi-light
+     * overrun per bucket (directional N>1 / point N>4 / spot N>4). Fires at
+     * most once per RenderSystem lifetime per bucket so AI users see a single
+     * actionable console.warn without per-frame flooding (charter P3 explicit
+     * failure: warn-once preserves signal/noise floor).
+     */
+    warnedMultiLightDirectional: boolean;
+    warnedMultiLightPoint: boolean;
+    warnedMultiLightSpot: boolean;
+    /**
+     * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w19:
+     * once-warn latches for >1 Skylight / >1 SkyboxBackground entity. Fire at most
+     * once per RenderSystem lifetime so the multi-entity warn (which names the
+     * winning entity handle, F-8) does not flood the console every frame.
+     */
+    warnedMultiSkylight: boolean;
+    warnedMultiSkybox: boolean;
+    /** feat-20260531-skybox-env-background M3 / w20: once-warn when camera
+     * tonemap is 'none' but a SkyboxBackground entity exists. Skybox needs
+     * the HDR render target allocated by the tonemap path; without it the
+     * skybox pass is skipped (plan-strategy D-2 NOTE). */
+    warnedSkyboxTonemapNone: boolean;
+    /**
+     * Per-handle warn-once anchor for the missing baseColor-texture fallback,
+     * shared by every textured material path (sprite / sprite-lit / standard-pbr
+     * / pbr-skin / unlit — feat-20260520-2d-sprite-layer-mvp M-3 / w25 seeded it
+     * for sprites; feat-future-pbr-missing-texture-fallback-explicit generalised
+     * it to PBR/skin so GLB textures that fail to reach the GPU no longer render
+     * silently flat). A `Set<number>` keyed by the raw Handle<TextureAsset> id -
+     * the writer fires `console.warn` exactly once per missing texture handle per
+     * RenderSystem lifetime so AI users see a single actionable message without
+     * per-frame log flooding. The set lives across frames so the second frame on
+     * the same missing handle stays silent (charter P3 explicit failure:
+     * warn-once preserves signal / noise floor while structured RhiError below
+     * stays per-frame fire).
+     *
+     * Note on the WeakSet/Set choice: plan-strategy mentions WeakSet but
+     * Handle values are numeric brand u32s (not object references), so
+     * WeakSet<object> is not applicable; Set<number> gives identical
+     * warn-once-per-handle semantics at zero additional cost (charter F1
+     * minimal surface; the per-RenderSystem lifetime cap is the upper
+     * bound).
+     */
+    readonly warnedMissingBaseColorTextureHandles: Set<number>;
+    /**
+     * feat-20260527-sprite-nineslice M2 / w11 + M4 / w16 (AC-16): once-per-
+     * renderable guard for the `nineslice.scale-too-small` metric increment.
+     * Keyed by `renderableIndex` so the second frame on the same mis-scaled
+     * entity does NOT keep bumping the counter — AI users see one counter
+     * tick per offending entity per RenderSystem lifetime, matching the
+     * single-event semantics of the structured fail-fast (charter P3:
+     * machine-readable signal, not a per-frame inflation). M4 retired the
+     * placeholder console.warn; the increment lands on the per-Renderer
+     * EngineMetrics through `runtime.metrics.increment(...)`.
+     */
+    readonly warnedNineSliceScaleEntities: Set<number>;
+    /**
+     * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w18:
+     * per-handle fire-once anchor for the lazy equirect-to-cubemap projection
+     * failure. A `Set<number>` keyed by the raw Handle<EquirectAsset> id - the
+     * record arm fires the structured `EquirectProjectionFailedError` exactly
+     * once per failed source per RenderSystem lifetime (the store records
+     * `status:'failed'` permanently and never retries, R-2 / AC-09; without this
+     * latch the record arm would re-fire the error every frame). The set lives
+     * across frames so the second frame on the same failed handle stays silent
+     * (charter P3: warn-once preserves signal / noise floor).
+     */
+    readonly firedEquirectProjectionFailedHandles: Set<number>;
+    /**
+     * feat-20260622-handle-to-id-allocator-elimination M1 / w3: per-frame
+     * bind group caches converted to nested WeakMap chain roots (D-3).
+     * Each root is a WeakMap<object, WeakMap<...>> walked by
+     * getOrCreateFromChain; the chain depth varies by variant
+     * (view-main = 7, mesh = 1, hdrp-unified = 5, skin = 2).
+     * Roots are stable between device recoveries and replaced when the renderer
+     * swaps to a fresh device. Chain keys are always inner buffer handles, never
+     * wrappers (D-3).
+     */
+    viewBindGroupCache: WeakMap<object, unknown>;
+    meshBindGroupCache: WeakMap<object, unknown>;
+    /**
+     * feat-20260622-handle-to-id-allocator-elimination M1 / w2: per-entity
+     * bind group caches scoped by entityKey (packed u32 as number).
+     * Outer Map<number, WeakMap<handle, ...>> lets GC collect entries for
+     * destroyed entities whose handles are unreachable; per-entity material
+     * and instances share the same two-level shape (D-1). The inner WeakMap
+     * value is opaque (`unknown`) because `getOrCreateFromChain` walks a
+     * variable-depth chain — intermediate handles map to nested WeakMaps and
+     * only the final handle maps to the variant->BindGroup leaf Map. Direct
+     * readers (HDRP shadow-instances read end) assert the leaf shape locally.
+     */
+    /**
+     * feat-20260708-composited-multi-world-rendering M1 / D-1a #2: outer Map
+     * keyed by `worldEntityKey(worldId, entityKey)`. Inner WeakMap unchanged.
+     */
+    readonly materialBgPerEntity: Map<number, WeakMap<object, unknown>>;
+    /**
+     * feat-20260708-composited-multi-world-rendering M1 / D-1a #3: outer Map
+     * keyed by `worldEntityKey(worldId, entityKey)`. Inner WeakMap unchanged.
+     */
+    readonly instancesBgPerEntity: Map<number, WeakMap<object, unknown>>;
+    /** Identity-keyed instances BGs shared across entities using the same buffer. */
+    readonly instancesBgShared: WeakMap<object, unknown>;
+    /**
+     * feat-20260622-handle-to-id-allocator-elimination M1 / w2: cross-entity
+     * shared material bind group cache (OQ-1 option A). Outer key is the
+     * material shaderId string; inner chain is a WeakMap keyed by the same
+     * handle objects used in per-entity chains. Reuses the generic
+     * `getOrCreatePerEntity` helper with outerKey string|number (D-1).
+     */
+    readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
+    /** Cross-frame fast path for fully-resident, immutable material snapshots. */
+    readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
+    /**
+     * feat-20260622-handle-to-id-allocator-elimination M1 / w2: singleton
+     * material bind group cache (D-6). Single flat Map<variant, BindGroup>
+     * for the one true singleton in production: shadow-material-singleton.
+     * shadow-instances-singleton is a test fixture fiction (research F3);
+     * no second singleton field is needed.
+     */
+    readonly singletonMaterialCache: Map<string, BindGroup>;
+    /**
+     * Post-process bind group cache: nested WeakMap chain root shared by the
+     * built-in bloom (bright / blur-H / blur-V / composite), FXAA, and HDRP SSAO
+     * (calc / blur) fullscreen passes. Each of these passes samples graph-owned
+     * transient render targets (hdrColor / ldrColor / bloom* / ssaoRaw /
+     * gbuf0 / hdrDepth); on canvas resize the graph retires the old physical
+     * textures and allocates new ones, so the bind group must be rebuilt to
+     * reference the new TextureView identity. Keying the cache on the physical
+     * TextureView (or `::tex` texture handle for passes that recreate their bound
+     * view every frame) makes invalidation automatic: a resized target yields a
+     * new key object -> WeakMap miss -> factory rebuild, and dead views are GC'd
+     * (same identity-invalidation mechanism as view/mesh caches, D-3). Replaces
+     * the pre-fix `pp.*BindGroup === null` single-slot caches that never
+     * invalidated on resize and submitted destroyed textures.
+     */
+    postProcessBgCache: WeakMap<object, unknown>;
+    /**
+     * Raw handle of the currently installed RenderPipelineAsset (0 = builtin).
+     * Installation brands the next candidate topology; the prior compiled graph
+     * remains last-known-good until the candidate compiles successfully.
+     */
+    installedPipelineHandle: number;
+    /**
+     * Active topology declaration resolved from the pipeline registry.
+     */
+    activePipeline: RenderPipelineDef;
+    /**
+     * Install-time config projected into `RenderPipelineTopology.config`.
+     */
+    installedPipelineConfig: RenderPipelineAsset['config'];
+    /**
+     * feat-20260608-cluster-lighting M2 / w10: HDRP active flag.
+     * True iff the currently installed RenderPipelineAsset has
+     * `pipelineId === 'forgeax::hdrp'`. URP-only code paths gate on
+     * `!isHdrpActive` so HDRP demos do not double-count light contributions.
+     */
+    isHdrpActive: boolean;
+    /**
+     * feat-20260608-cluster-lighting M5 / w20 + M6 / w23 + M5 / w22:
+     * once-per-frame fire dedup set for HDRP per-frame fail-soft errors
+     * (`hdrp-light-budget-exceeded`, `hdrp-index-list-overflow`). Cleared
+     * at the end of each frame so the next frame re-fires if the condition
+     * persists. Set<string> keyed by RuntimeErrorCode literal.
+     */
+    hdrpOncePerFrameFired: Set<string>;
+    /**
+     * feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-2 (plan-strategy §D-1).
+     * Lazily-allocated cube_array shadow atlas owned by the RenderSystem
+     * lifetime. `null` until the first frame whose `lights.pointShadow` is
+     * non-empty (zero-shadow scenes never allocate; AC-09). The atlas is
+     * disposed by the renderer dispose path; subsequent frames with a non-empty
+     * snapshot list re-allocate.
+     */
+    pointShadowAtlas: ShadowAtlas | null;
+    /**
+     * feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-2 (plan-strategy §D-3):
+     * per-frame projection of `lights.pointShadow` from the extract stage. The
+     * typed point-shadow pass reads this list to drive the 6 x N face iteration.
+     * Empty array means the topology declares no point-shadow passes.
+     */
+    pointShadowSnapshots: readonly PointShadowSnapshot[];
+    /**
+     * feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w4 (D-1):
+     * last fold-pass output, computed at `recordFrame` entry from the
+     * transparent-sort-ordered dispatch + mode-gate (D-5: only mode 0
+     * folds; other modes yield singleton buckets). Currently an
+     * observational compute — the drawIndexed swap (1 instanced draw per
+     * fold bucket) is the follow-on integration that wires each bucket
+     * into the sprite-pass / geometry-pass dispatch loops. The bucket
+     * count is the source of truth for `render.instancing.foldedDraws`
+     * metric (M3 / w13) — every fold-eligible bucket (bucketSize >= 1
+     * under mode 0 AND not bypassed) contributes one increment.
+     */
+    lastFoldBucketCount: number;
+    /**
+     * feat-20260625-spot-light-shadow-mapping M2 / w9 (D-2): per-frame projection
+     * of `lights.spot` from the extract stage. The typed spot-shadow graph
+     * pass reads this list to render each
+     * castShadow spot's perspective depth into its `spotShadowDepth` atlas tile
+     * (viewport keyed on `shadowAtlasTile`). `recordFrame` writes it before
+     * graph execution. Spots with `shadowAtlasTile < 0` (castShadow:false,
+     * degenerate direction, or clipped beyond cap 4) are skipped — zero
+     * shadow-casting spots means zero spot shadow passes (AC-03).
+     */
+    spotShadowSnapshots: readonly SpotLightSnapshot[];
+}
+export interface MorphBufferCacheEntry {
+    readonly buffer: GpuBuffer;
+    readonly byteLength: number;
+}
+/**
+ * feat-20260518-pbr-direct-lighting-mvp M5 / w22.11 (D-2 + D-10 + AC-06):
+ * mutable per-frame dispatch counter object owned by `createRenderSystem`
+ * and bumped here at the actual `pass.setPipeline(...)` call site (the
+ * only point with both `mat.materialShaderId` and `mesh.layoutProjection` in scope).
+ * Unlit / custom shader pipeline dispatch tracked here.
+ */
+export interface DispatchCounts {
+    unlit: number;
+}
+/**
+ * feat-20260531-per-frame-bind-group-cache M1 / w4: per-frame
+ * createBindGroup counter. Closure-mutable object aligned with
+ * DispatchCounts precedent. Reset in draw(world) entry, bumped on
+ * cache-miss createBindGroup calls (M2-M4).
+ */
+export interface BindGroupCounts {
+    createBindGroup: number;
+    /**
+     * Debug-only: records the variant of every cache-miss BindGroup created via
+     * `getOrCreateFromChain` for unit-test observability. Production paths do
+     * not read this array.
+     */
+    keys: string[];
+}
+/**
+ * A renderable resolved against the AssetRegistry for the current frame:
+ * its source snapshot, the GPU mesh handles, the row index used to correlate
+ * transparent-sort output back to this entry, and an optional per-material
+ * renderState override (bug-20260527-renderstate-pipeline-dispatch-gap D-4).
+ * Module-scoped so RenderPipelineContext can type `validated` / `validatedOrdered`
+ * without a dynamic type escape (was a recordFrame-local interface before F-4).
+ */
+export interface ValidatedRenderable {
+    readonly source: RenderableSnapshot;
+    /** World that owns the renderable's asset handles and material snapshots. */
+    readonly world?: World;
+    readonly mesh: MeshGpuHandles;
+    readonly renderableIndex: number;
+    readonly renderState: MaterialRenderState | undefined;
+    /**
+     * Canonical authored material-variant request folded from the selected
+     * pass's `defines` map. Capability axes are merged at the renderer seam;
+     * this field carries only the pass-owned selection into record.
+     */
+    readonly variantSet?: string | undefined;
+    /**
+     * w10: per-pass stencil reference value folded from
+     * {@link DispatchEntry.stencilReference} (draw-call dynamic state). The draw
+     * loop calls `pass.setStencilReference(stencilReference ?? 0)` before each
+     * draw; `undefined` falls back to the WebGPU default 0 (semantic no-op).
+     */
+    readonly stencilReference: number | undefined;
+}
+/**
+ * Cross-frame validity token for the directional shadow atlas.
+ *
+ * The atlas is a render target, not authored state. Keeping its validity
+ * token beside the other RenderFrameState caches lets recordFrame skip a
+ * static caster submission without teaching the public render-pipeline
+ * contract about caching. Every source that can change caster depth is part
+ * of the token: world mutation, asset catalogue, graph/target identity, CSM
+ * matrices, and the GPU mesh-residency epoch.
+ *
+ * @internal
+ */
+export interface DirectionalShadowCache {
+    readonly worlds: readonly World[];
+    readonly worldStateTokens: readonly DirectionalShadowWorldState[];
+    readonly assetCatalogEpoch: number;
+    readonly pipelineHandle: number;
+    readonly graphTopologyKey: string | null;
+    readonly shadowMapSize: number;
+    readonly cascadeCount: number;
+    readonly lightViewProj: readonly Float32Array[];
+    readonly meshResidencyEpoch: number;
+}
+/**
+ * ECS state that can change the contents of a directional shadow map.
+ *
+ * The ECS-owned RenderReadLease is the only render-facing mutation boundary.
+ * Its cursor is intentionally conservative: any published World change
+ * invalidates the cached atlas, while render never reaches through World for
+ * component-clock storage.
+ */
+export interface DirectionalShadowWorldState {
+    readonly worldIdentity: string;
+    readonly changeCursor: number;
+}
+//# sourceMappingURL=frame-snapshot.d.ts.map

package/dist/record/frame-snapshot.d.ts.map

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

package/dist/record/frame-targets.d.ts

@@ -0,0 +1,20 @@
+import type { Texture, TextureView } from '@forgeax/engine-rhi';
+import type { RenderGraphExecutionPhase } from '../render-contract';
+import type { ExtractedLights } from '../render-system-extract';
+import { type PipelineState, type RenderSystemInternals } from './render-context';
+export declare function graphExecutionPhase(passName: string): RenderGraphExecutionPhase;
+export declare function acquireSwapChainTarget(internals: RenderSystemInternals, pipelineState: PipelineState): {
+    currentTexture: Texture;
+    view: TextureView;
+    targetW: number;
+    targetH: number;
+} | null;
+export declare function resolveShadowMapSize(internals: RenderSystemInternals, lights: ExtractedLights): number | undefined;
+/**
+ * Resolve the per-tile size for the graph-owned spot atlas when a frame has
+ * no directional shadow map. The typed spot pass still needs a non-zero
+ * viewport in a spot-only world; the directional resolver cannot provide
+ * that because it intentionally follows only the directional shadow lane.
+ */
+export declare function resolveSpotShadowMapSize(internals: RenderSystemInternals, lights: ExtractedLights): number | undefined;
+//# sourceMappingURL=frame-targets.d.ts.map

package/dist/record/frame-targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-targets.d.ts","sourceRoot":"","sources":["../../src/record/frame-targets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAoB,KAAK,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAEpG,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,yBAAyB,CAyC/E;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,qBAAqB,EAChC,aAAa,EAAE,aAAa,GAC3B;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA+CzF;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,qBAAqB,EAChC,MAAM,EAAE,eAAe,GACtB,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,qBAAqB,EAChC,MAAM,EAAE,eAAe,GACtB,MAAM,GAAG,SAAS,CASpB"}

package/dist/record/frame.d.ts

@@ -0,0 +1,71 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { RenderReadLease } from '@forgeax/engine-ecs/projection';
+import { type CurrentFrameObservationLease } from '@forgeax/engine-render-graph';
+import { type Result, type TextureFormat } from '@forgeax/engine-rhi';
+import { ObservationUnavailableError } from '../errors/render';
+import type { GpuDrivenProduction } from '../gpu-driven/production-raster';
+import type { CameraSnapshot, RenderRecordPhase } from '../render-contract';
+import type { DispatchEntry, ExtractedLights, RenderableSnapshot, SkyboxSnapshot, SkylightSnapshot } from '../render-system-extract';
+import type { PersistentGpuDrivenState } from '../scene/render-scene';
+import { type BindGroupCounts, type DispatchCounts, type FrameObservationSource, type RenderFrameState } from './frame-snapshot';
+import type { RenderSystemInternals } from './render-context';
+export type { FrameObservationSource } from './frame-snapshot';
+export type FrameObservationReadback = (lease: CurrentFrameObservationLease) => Promise<Result<Uint8Array, Error>>;
+export interface FrameObservationOptions {
+    readonly semantic: 'linear-hdr';
+    readonly readback: FrameObservationReadback;
+}
+export interface FrameObservationMetadata {
+    readonly format: TextureFormat;
+    readonly size: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly usage: number;
+    readonly sample: number;
+    readonly frameId: number;
+    readonly lifetime: {
+        readonly frameId: number;
+        readonly state: 'active' | 'retired';
+    };
+    readonly pipelineId: 'forgeax::standard';
+    readonly backendId: string;
+}
+export interface FrameObservation {
+    readonly bytes: Uint8Array;
+    readonly metadata: FrameObservationMetadata;
+}
+export declare function observeCurrentFrame(options: FrameObservationOptions, source: FrameObservationSource | undefined, currentFrameId: number): Promise<Result<FrameObservation, ObservationUnavailableError>>;
+import { type RenderFeatureGraphCandidate } from './typed-frame-graph';
+/**
+ * A frame-local material table. Repeated snapshot objects share one UBO slot;
+ * each renderable keeps only the slot index used by each authored material.
+ */
+export interface MaterialSlotPlan<T extends object> {
+    readonly slotIndices: readonly (readonly number[])[];
+    readonly slots: readonly T[];
+    /** Index of the first renderable that referenced each slot. */
+    readonly slotOwners: readonly number[];
+}
+/**
+ * Intern identical material snapshots into one frame-local slot table.
+ * Snapshot identity is the extract layer's invalidation token, so this keeps
+ * the same correctness boundary while avoiding duplicate payload assembly and
+ * upload for repeated scene instances.
+ */
+export declare function buildMaterialSlotPlan<T extends object>(materialGroups: readonly (readonly T[])[]): MaterialSlotPlan<T>;
+/**
+ * Return the largest complete renderable prefix supported by a shared
+ * mesh/material capacity. Mesh rows consume one slot per renderable; material
+ * rows use the deduplicated slot indices assigned in first-seen order.
+ */
+export declare function findRenderablePrefixForSlotCapacity(materialSlotIndices: readonly (readonly number[])[], slotCapacity: number): number;
+/** Count material slots reachable from a prefix of a first-seen slot plan. */
+export declare function materialSlotCountForPrefix(materialSlotIndices: readonly (readonly number[])[], renderableCount: number): number;
+export type RecordProfileRunner = <T>(phase: RenderRecordPhase, action: () => T) => T;
+export declare function recordFrame(internals: RenderSystemInternals, world: World, cameras: CameraSnapshot[], lights: ExtractedLights, renderables: RenderableSnapshot[], transparentDispatch: readonly DispatchEntry[], frameState: RenderFrameState, dispatchCounts: DispatchCounts, bindGroupCounts: BindGroupCounts, skylight: SkylightSnapshot | undefined, skylightCount: number, skybox: SkyboxSnapshot | undefined, skyboxCount: number, postProcessParams: ReadonlyMap<string, Uint8Array>, worlds?: readonly World[], profilePhase?: RecordProfileRunner, gpuDriven?: {
+    readonly owner: GpuDrivenProduction;
+    readonly scene: PersistentGpuDrivenState | undefined;
+    readonly onCoverage: (ownsAll: boolean) => void;
+}, renderReadLeases?: readonly RenderReadLease[], featureGraphCandidate?: RenderFeatureGraphCandidate, pointsLinesOwner?: import('./render-context').PointsLinesRecordOwner): boolean;
+//# sourceMappingURL=frame.d.ts.map

package/dist/record/frame.d.ts.map

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

package/dist/record/helpers.d.ts

@@ -0,0 +1,102 @@
+import type { World } from '@forgeax/engine-ecs';
+import { type Mat4 } from '@forgeax/engine-math';
+import type { CameraSnapshot } from '../render-contract';
+import type { MaterialSnapshot, SkyboxSnapshot, SkylightSnapshot } from '../render-system-extract';
+import type { RenderFrameState } from './frame-snapshot';
+import type { RenderSystemInternals } from './render-context';
+/** Convert pass-owned shader definitions into the manifest's canonical variant key. */
+export declare function variantSetFromDefines(defines: Readonly<Record<string, string>> | undefined): string | undefined;
+/**
+ * Select the equirect source for the shared lazy projection.
+ *
+ * Skylight uses handle 0 as a real "solid-color ambient" sentinel, so nullish
+ * coalescing cannot distinguish "no equirect" from a valid snapshot. Prefer a
+ * non-zero Skylight handle and fall back to SkyboxBackground otherwise.
+ */
+export declare function selectLazyEquirectHandle(skylight: Pick<SkylightSnapshot, 'equirectHandle'> | undefined, skybox: Pick<SkyboxSnapshot, 'equirectHandle'> | undefined): number;
+/**
+ * feat-20260608-multi-light-warn-once M3: warn-once latch for directional
+ * N>1 overrun. Fires console.warn at most once per RenderSystem lifetime.
+ * Extracted as a pure helper so the warn-once logic is directly testable
+ * without a full recordFrame argument list (AC-05 (c)).
+ */
+export declare function warnMultiLightDirectional(frameState: Pick<RenderFrameState, 'warnedMultiLightDirectional'>, directionalCount: number, envOverride?: {
+    env?: {
+        NODE_ENV?: string;
+    };
+}): void;
+/**
+ * feat-20260608-multi-light-warn-once M3: warn-once latch for point light
+ * N>4 overrun (first-slice cap). Fires at most once per RenderSystem
+ * lifetime.
+ */
+export declare function warnMultiLightPoint(frameState: Pick<RenderFrameState, 'warnedMultiLightPoint'>, pointCount: number, envOverride?: {
+    env?: {
+        NODE_ENV?: string;
+    };
+}): void;
+/**
+ * feat-20260608-multi-light-warn-once M3: warn-once latch for spot light
+ * N>4 overrun (first-slice cap). Fires at most once per RenderSystem
+ * lifetime.
+ */
+export declare function warnMultiLightSpot(frameState: Pick<RenderFrameState, 'warnedMultiLightSpot'>, spotCount: number, envOverride?: {
+    env?: {
+        NODE_ENV?: string;
+    };
+}): void;
+/**
+ * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w19:
+ * once-warn for >1 Skylight entity (first archetype hit wins). Fires at most
+ * once per RenderSystem lifetime and names the WINNING entity handle so the
+ * scene author can tell which Skylight is used and that the rest are ignored
+ * (F-8: warn carries conflicting entity info; charter P3 explicit failure with
+ * a warn-once signal floor, no per-frame flooding).
+ */
+export declare function warnMultiSkylight(frameState: Pick<RenderFrameState, 'warnedMultiSkylight'>, skylightCount: number, winningEntityHandle: number): void;
+/**
+ * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w19:
+ * once-warn for >1 SkyboxBackground entity (mirrors warnMultiSkylight). Names
+ * the winning entity handle; fires once per RenderSystem lifetime.
+ */
+export declare function warnMultiSkybox(frameState: Pick<RenderFrameState, 'warnedMultiSkybox'>, skyboxCount: number, winningEntityHandle: number): void;
+/**
+ * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w18:
+ * lazy equirect-to-cubemap projection trigger. Driven once per frame from
+ * `recordFrame` for the active equirect handle (Skylight's, or the
+ * SkyboxBackground's when no Skylight cubemap is present -- both reuse one
+ * handle). Implements the plan-strategy D-4 state machine:
+ *
+ *   undefined (no entry) -> resolve POD + fire-and-forget projection; the
+ *                                    store selects rgba8 output on WebGL2
+ *                                     (the store writes status:'pending'
+ *                                     synchronously, so this launches once)
+ *   pending                        -> in flight; bind white fallback (no fire)
+ *   ready                          -> bound by recordMainPass's IBL cache check
+ *   failed                         -> fire EquirectProjectionFailedError ONCE
+ *                                     per handle (R-2/AC-09 no retry)
+ * Fire-and-forget: `_uploadCubemapFromEquirect` is invoked WITHOUT await so the
+ * record stay synchronous; the store mutates its own status map and (on
+ * success) the per-device IblPipelineCache, which recordMainPass reads on a
+ * later frame. The structured error from a fire-and-forget failure is reported
+ * via the explicit `status === 'failed'` arm here (read on the next frame), not
+ * by awaiting the promise (which would block record).
+ */
+export declare function driveLazyEquirectProjection(internals: RenderSystemInternals, world: World, frameState: Pick<RenderFrameState, 'firedEquirectProjectionFailedHandles'>, equirectHandle: number): void;
+/**
+ * Returns true when a MaterialSnapshot uses a builtin standard/PBR shader
+ * that will render black with zero lights.
+ *
+ * The default mid-grey fallback (materialShaderId === undefined) is excluded
+ * — it routes through defaultMaterialSnapshot and never triggers the
+ * zero-light warning. Custom shaders are also excluded: their lighting
+ * contract is authored by the shader and cannot be inferred from this
+ * generic diagnostic.
+ *
+ * @internal — exported so AC-02 zero-light-warning test can anchor to
+ * the production implementation rather than a test-local copy.
+ */
+export declare function isLitMaterialSnapshot(material: MaterialSnapshot): boolean;
+export declare function computeViewMatrix(camera: CameraSnapshot): Mat4;
+export declare function computeProjectionMatrix(camera: CameraSnapshot): Mat4;
+//# sourceMappingURL=helpers.d.ts.map