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

package/dist/render-system-extract.d.ts

@@ -0,0 +1,868 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { World } from '@forgeax/engine-ecs';
+import { type Mat4, type Vec3 } from '@forgeax/engine-math';
+import { type SceneHierarchySnapshot } from '@forgeax/engine-scene';
+import type { Handle, MaterialAsset, MaterialPass, MaterialRenderState, MaterialTextureCoordinates, ParamSchemaEntry, PrimitiveTopology } from '@forgeax/engine-types';
+import { type VisibilitySnapshot } from './extract/visibility';
+import type { RenderFeatureHiddenEntityReport, RenderFeatureWorldVisibilitySnapshot } from './features/types';
+import { type MeshMaterialBindingDiagnostic, type MeshMaterialBindingSource } from './mesh-material-bindings';
+import type { PointsLinesRetainedSnapshot } from './points-lines/snapshot';
+import { type CameraSnapshot } from './render-contract';
+import type { SkinPaletteAllocator } from './systems/skin-palette-allocator';
+import type { SkinPaletteSlice } from './systems/skin-palette-types';
+/**
+ * DirectionalLightSnapshot — sun-like infinite light variant of the
+ * `LightSnapshot` discriminated union (M2 / w16 / AC-03). Host pre-multiplies
+ * `color * intensity` so the shader sees the radiance term directly (charter
+ * P4 host-side parity); `direction` stays in raw outgoing-vector form so the
+ * shader can negate it once for BRDF (`let l = normalize(-light.direction)`).
+ *
+ * Plan-strategy D-S1 (3) (LightSnapshot to GPU buffer bucket 1:1 mapping).
+ */
+export interface DirectionalLightSnapshot {
+    readonly kind: 'directional';
+    readonly direction: Vec3;
+    readonly color: Vec3;
+    readonly intensity: number;
+}
+/**
+ * PointLightSnapshot — omnidirectional point variant. `position` from the
+ * companion Transform; `invRangeSquared = 1 / range^2` host-folded via
+ * `computeInvRangeSquared` (range = +Infinity -> 0; range = 0 -> 1e8 NaN
+ * protection per D-S5).
+ */
+export interface PointLightSnapshot {
+    readonly kind: 'point';
+    readonly position: Vec3;
+    readonly color: Vec3;
+    readonly intensity: number;
+    readonly invRangeSquared: number;
+    /**
+     * feat-20260612-point-light-shadows-urp-hdrp M1 / T-M1-8 + M4 / T-M4-4:
+     * cube_array atlas layer index for this light's shadow map (0..3 for shadow
+     * casters; sentinel `-1` for non-shadow lights). Default `-1` per
+     * plan-strategy §D-2 — record stage / shader skips shadow sampling when the
+     * lane equals the sentinel. Joined with `pointShadow[]` by entity at the
+     * end of extract; HDRP record stage threads `shadowAtlasLayer + shadowNear +
+     * shadowFar` through `packLightSlot` as the §D-8 pad-lane payload.
+     */
+    readonly shadowAtlasLayer?: number;
+    /**
+     * Per-face perspective near plane (matches `PointLightShadow.nearPlane`).
+     * Used by HDRP `evalPointShadowed` for depth-ref reconstruction; rides
+     * `LightSlot.kind_and_pad.z` (byte 56..60) on the std430 std layout.
+     */
+    readonly shadowNear?: number;
+    /**
+     * Per-face perspective far plane (matches `PointLightShadow.farPlane`).
+     * Rides `LightSlot.kind_and_pad.w` (byte 60..64).
+     */
+    readonly shadowFar?: number;
+}
+/**
+ * PointShadowSnapshot — extract-stage view of one shadow-casting point light
+ * (feat-20260612-point-light-shadows-urp-hdrp M1 / T-M1-7).
+ *
+ * `entity` is the spawning entity (joins PointLight + PointLightShadow on the
+ * same archetype); `position` is the light world-space position resolved from
+ * the companion Transform (mirrors PointLightSnapshot.position).
+ * `shadowMatrices` is the 96-float packed mat4[6] table (column-major,
+ * 6 mat4 * 16 floats = 384 bytes) ready for UBO upload.
+ *
+ * Plan-strategy §D-3: the record stage allocates a dynamic-offset uniform
+ * buffer (384 B per-light, aligned to minUniformBufferOffsetAlignment, WebGPU
+ * min 256 -> 512 B stride). Extract owns the host-side `Float32Array(96)`;
+ * record owns the GPU `RhiBuffer` lifetime.
+ *
+ * `mapSize` / `nearPlane` / `farPlane` ride here so record stage can size the
+ * cube atlas faces and feed shader the proj constants without re-querying ECS.
+ * `shadowAtlasLayer` is assigned by extract in spawn order (0 .. cap-1) so the
+ * downstream LightSlot / packPointLight packers carry the layer index in
+ * pointPadW (T-M1-8 will rename to shadowAtlasLayer).
+ */
+export interface PointShadowSnapshot {
+    /** Spawning entity index (joins PointLight + PointLightShadow + Transform). */
+    readonly entity: number;
+    /** World-space light position (sourced from companion Transform). */
+    readonly position: Vec3;
+    /** PointLightShadow.mapSize (per-face cube square dimension; 512 default). */
+    readonly mapSize: number;
+    readonly nearPlane: number;
+    readonly farPlane: number;
+    /**
+     * Atlas layer assigned by extract in spawn order (0..cap-1, where cap=4
+     * matches PointLightShadow cardinality). Sentinel -1 is reserved by the
+     * shader-side LightSlot for no-shadow lights (T-M1-8).
+     */
+    readonly shadowAtlasLayer: number;
+    /**
+     * 6 view-proj mat4 in face order [+X, -X, +Y, -Y, +Z, -Z] packed into one
+     * Float32Array(96). 16 floats per face = 64 B; 6 * 64 = 384 B raw. The
+     * record stage pads each slot to 512 B (256 alignment) when packing into
+     * the per-light dynamic-offset UBO (plan-strategy §D-3).
+     */
+    readonly shadowMatrices: Float32Array;
+}
+/**
+ * SpotLightSnapshot — cone-restricted variant. `position` from companion
+ * Transform; `direction` raw outgoing-vector; `cosInner` / `cosOuter` host
+ * pre-converted via `degToCos` so the shader sees only cosines (D-S2).
+ *
+ * feat-20260625-spot-light-shadow-mapping M1 w5: added shadow fields.
+ * castShadow (bool) gates shadow projection; lightViewProj is the perspective
+ * light-view-projection matrix computed in extract (undefined when castShadow
+ * is false, dir degenerates, or the light is clipped). shadowAtlasTile
+ * (i32 sentinel -1) is the allocated tile index 0..3 or -1 for unassigned
+ * (plan-strategy D-4). mapSize / nearPlane / farPlane are the source
+ * component shadow parameters carried through to the record stage.
+ */
+export interface SpotLightSnapshot {
+    readonly kind: 'spot';
+    readonly position: Vec3;
+    readonly direction: Vec3;
+    readonly color: Vec3;
+    readonly intensity: number;
+    readonly invRangeSquared: number;
+    readonly cosInner: number;
+    readonly cosOuter: number;
+    readonly castShadow: boolean;
+    readonly lightViewProj: Float32Array | undefined;
+    readonly mapSize: number;
+    readonly nearPlane: number;
+    readonly farPlane: number;
+    readonly shadowAtlasTile: number;
+}
+/**
+ * LightSnapshot — discriminated union of the three KHR_lights_punctual
+ * variants. AI users + the record stage perform an exhaustive switch on
+ * `kind`; missing arms are caught at compile time (no `default`,
+ * `assertNever`-style guards). Plan-strategy R-10.
+ */
+export type LightSnapshot = DirectionalLightSnapshot | PointLightSnapshot | SpotLightSnapshot;
+/**
+ * ExtractedLights — three-bucket output of the extractFrame three-query
+ * union (M2 / w16 / AC-03). Plan-strategy section 3.1 EXT node:
+ *   - `directional` — at most one (record-stage N>1 fail-fast lands in M3)
+ *   - `point[]` — first-slice cap of 4 enforced at record stage (M3)
+ *   - `spot[]`  — first-slice cap of 4 enforced at record stage (M3)
+ * `directionalCount` exposes the raw count of DirectionalLight entities the
+ * extract observed (so the record stage can fire `render-system-multi-light`
+ * when N>1 without re-running the query). M3 / w19 will widen this with
+ * pointCount / spotCount fields once the matching record-time fail-fast
+ * lands; for M2 the field stays directional-only to keep AC-06 (a) intact.
+ */
+export interface ExtractedLights {
+    readonly directional: DirectionalLightSnapshot | undefined;
+    readonly directionalCount: number;
+    readonly point: readonly PointLightSnapshot[];
+    readonly spot: readonly SpotLightSnapshot[];
+    /**
+     * feat-20260613-csm-cascaded-shadow-maps M2 / w9: per-cascade light-view-
+     * projection matrices (one per cascade, length 4 pre-allocated). Each matrix
+     * is a column-major 16-float mat4 with atlas tile UV inset baked in
+     * (plan-strategy D-3). cascadeCount < 4: unused slots are zero matrices.
+     * Undefined when castShadow=false or no directional light.
+     */
+    readonly lightViewProj: readonly Float32Array[] | undefined;
+    /**
+     * feat-20260613-csm-cascaded-shadow-maps M2 / w9: view-space z depths
+     * of the PSSM split planes (length 4, Float32Array). cascadeCount < 4:
+     * unused slots are 0.0f. Undefined when castShadow=false or no directional
+     * light.
+     */
+    readonly splitPlanes: Float32Array | undefined;
+    /**
+     * feat-20260613-csm-cascaded-shadow-maps M2 / w9: effective cascade count
+     * from the DirectionalLight component (1..4). Undefined when castShadow=false
+     * or no directional light.
+     */
+    readonly cascadeCount: number | undefined;
+    /**
+     * feat-20260613-csm-cascaded-shadow-maps M2 / w9: cascade blend width
+     * from the DirectionalLight component (0..0.5). Undefined when castShadow=false
+     * or no directional light.
+     */
+    readonly cascadeBlend: number | undefined;
+    /**
+     * feat-20260520-directional-light-shadow-mapping M1c / w8:
+     * shadowMapSize from DirectionalLight.mapSize. Drives shadow RT
+     * lazy-allocate (idempotency: same size -> no rebuild). Undefined when
+     * castShadow=false or no directional light.
+     */
+    readonly shadowMapSize: number | undefined;
+    /**
+     * feat-20260621-merge-directionallightshadow-into-directionallight M2:
+     * depthBias from the merged DirectionalLight (constant shadow-bias floor).
+     * Populated when castShadow=true on the first-hit directional light;
+     * undefined otherwise.
+     */
+    readonly depthBias: number | undefined;
+    /**
+     * feat-20260621-merge-directionallightshadow-into-directionallight M2:
+     * normalBias from the merged DirectionalLight (slope-based shadow-bias
+     * coefficient).
+     * Populated when castShadow=true on the first-hit directional light;
+     * undefined otherwise.
+     */
+    readonly normalBias: number | undefined;
+    /**
+     * feat-20260621-merge-directionallightshadow-into-directionallight M2:
+     * pcfKernelSize from the merged DirectionalLight (PCF kernel width, odd>=1).
+     * Populated when castShadow=true on the first-hit directional light;
+     * undefined otherwise.
+     */
+    readonly pcfKernelSize: number | undefined;
+    /**
+     * feat-20260612-point-light-shadows-urp-hdrp M1 / T-M1-7:
+     * shadow-casting point lights (PointLight + PointLightShadow + Transform
+     * archetype join). Each entry carries the per-light 6-face VP matrices and
+     * the assigned cube_array atlas layer (0..3 in spawn order; sentinel -1 is
+     * reserved by the shader-side LightSlot for no-shadow point lights).
+     *
+     * Empty array when no PointLightShadow components exist (zero-cost gate per
+     * AC-09; record stage skips atlas allocation + shadow pass dispatch).
+     */
+    readonly pointShadow: readonly PointShadowSnapshot[];
+    /**
+     * bug-20260710-editor-cross-world-shadow: the RAW directional-shadow config
+     * (cascadeCount / splitLambda / cascadeBlend / mapSize / shadowDistance) of
+     * the first-hit castShadow DirectionalLight, carried unconditionally of
+     * whether this world had a camera. The {@link extractFrames} merge layer
+     * re-runs {@link computeDirectionalCsm} with this config + the surfaced
+     * camera so directional shadows work when the light and camera live in
+     * DIFFERENT worlds (editor editorWorld/sceneWorld super-composite). Undefined
+     * when castShadow=false or no directional light. The `lightViewProj` /
+     * `splitPlanes` fields above remain the *computed* per-world outputs (correct
+     * for single-world; recomputed at merge for cross-world).
+     */
+    readonly directionalCsmConfig: DirectionalCsmConfig | undefined;
+    /**
+     * bug-20260710-editor-cross-world-shadow: the light-direction of the
+     * first-hit castShadow DirectionalLight, carried so the merge layer can
+     * rebuild the light-view matrix. Redundant with `directional.direction` but
+     * kept explicit so the CSM recompute reads a single config bundle. Undefined
+     * when castShadow=false or no directional light.
+     */
+    readonly directionalCsmDirection: Vec3 | undefined;
+}
+/**
+ * SkylightSnapshot -- extract-stage view of one Skylight entity
+ * (feat-20260520-skylight-ibl-cubemap M4 / t26).
+ *
+ * `equirectHandle` carries the packed u32 handle for
+ * `Handle<EquirectAsset, 'shared'>`; the record stage drives the internal
+ * lazy cubemap projection from it and resolves the projected GPU cubemap via
+ * `GpuResidencyCache.getCubemapGpuView(...)` and related helpers
+ * (feat-20260630 M3 / w16-w18). The snapshot carries NO projection status
+ * field: the status truth lives in the store's CubemapGpuEntry (D-3 SSOT);
+ * record queries it once per frame.
+ *
+ * `intensity` defaults to 1.0 via the Skylight component token defaults
+ * (plan-strategy D-6: Skylight data flows through existing extract->record
+ * pipeline; no independent ECS system).
+ */
+export interface SkylightSnapshot {
+    readonly equirectHandle: number;
+    readonly color: readonly [number, number, number];
+    readonly intensity: number;
+    /** Environment-space quaternion [x, y, z, w], identity by default. */
+    readonly rotation: readonly [number, number, number, number];
+    readonly entityHandle: number;
+}
+/**
+ * SkyboxSnapshot -- extract-stage view of one SkyboxBackground entity
+ * (feat-20260531-skybox-env-background M2 / w5).
+ *
+ * `equirectHandle` carries the packed u32 handle for
+ * `Handle<EquirectAsset, 'shared'>`; the record stage resolves the projected
+ * GPU cubemap via `GpuResidencyCache.getCubemapGpuView(...)`.
+ *
+ * `mode` carries the raw `f32` column value (`SKYBOX_MODE_CUBEMAP = 0`).
+ * First hit wins per plan-strategy D-6; multi-entity once-warn in record stage.
+ */
+export interface SkyboxSnapshot {
+    readonly equirectHandle: number;
+    readonly mode: number;
+    /** Environment-space quaternion [x, y, z, w], identity by default. */
+    readonly rotation: readonly [number, number, number, number];
+    readonly entityHandle: number;
+}
+export interface RenderableSnapshot {
+    readonly assetHandle: number;
+    readonly transform: TransformSnapshot;
+    /** Finite producer-owned local bounds retained for persistent CPU view work. */
+    readonly localAabb?: Float32Array;
+    /** Indexed single-submesh facts consumed by the first GPU-driven rigid lane. */
+    readonly gpuDrivenDraws?: readonly GpuDrivenDrawSnapshot[];
+    /**
+     * feat-20260608 M5 amend / w11-a: the entity's representative (first)
+     * material snapshot, kept as a same-name shorthand for `materials[0]`.
+     * Per-entity dispatch (shading model routing, sprite-vs-mesh split, the
+     * D-1/D-3 pipeline-tag pick) is uniform across the entity's submeshes
+     * today, so the existing 20+ `entry.source.material.X` consumers in the
+     * record stage stay unchanged. Per-submesh material data (baseColor /
+     * UBO payload / paramSnapshot) lives in `materials[i]`.
+     */
+    readonly material: MaterialSnapshot;
+    /**
+     * feat-20260608 M5 amend / w11-a: per-submesh MaterialSnapshot[]
+     * positionally aligned with `MeshAsset.submeshes[]` (plan §3.2 sequence
+     * step 6 + AC-08). Length always equals the entity's submesh count once
+     * the extract stage's count-mismatch validator (M2 / w12) has filtered
+     * misaligned spawns. The record stage reads `materials[i]` to upload the
+     * i-th material UBO slot before drawing the i-th submesh.
+     *
+     * Backward-compat: `materials[0] === material` (the legacy mid-grey
+     * default-material case-B path also routes through `materials = [default]`,
+     * keeping the legacy single-mesh-no-material spawn shape working without
+     * a special branch in record).
+     */
+    readonly materials: readonly MaterialSnapshot[];
+    /** Per-slot provenance trace from the shared mesh-material resolver. */
+    readonly materialBindingSources: readonly MeshMaterialBindingSource[];
+    /** Active structured override diagnostics for this renderable. */
+    readonly materialBindingDiagnostics?: readonly MeshMaterialBindingDiagnostic[];
+    /**
+     * feat-20260708-composited-multi-world-rendering M1 / D-1: the worldId
+     * of the world this renderable was extracted from. Defaults to 0 in
+     * single-world path (extractFrame always assigns 0). The merge layer
+     * (extractFrames in M2) stamps the correct worldId per world before
+     * the record stage consumes it. Combined with `entityKey` via
+     * `worldEntityKey(worldId, entityKey)` to form per-entity cache keys.
+     *
+     * Never rewrite `entityKey` itself — consumers that need the real
+     * entity handle (video provider, etc.) read the bare `entityKey`.
+     */
+    readonly worldId: number;
+    /**
+     * feat-20260531-per-frame-bind-group-cache M1 / w3: packed Entity u32
+     * (encodeEntity(indexSlot, generation)) surface'd from the extract
+     * stage. Stable per-entity identity for the record stage cache keys
+     * (material / instances / per-frame clean-up) without re-querying the
+     * World (charter P5 Pipeline Isolation: record stage only consumes
+     * snapshot POD). Reuses the encodeEntity calculation already performed
+     * at :1293 for the Instances path, and now also computed for plain
+     * (non-Instances) renderables.
+     *
+     * Never rewrite this field — cache keys use `worldEntityKey(worldId, entityKey)`,
+     * not the bare entityKey alone (D-1).
+     */
+    readonly entityKey: number;
+    /**
+     * feat-20260514 M3 (w15): when the entity carries an `Instances` component
+     * the extract stage materialises a fresh `Float32Array` snapshot of the
+     * packed mat4 transforms (16 f32 per instance, stride 16) plus a stable
+     * `cacheKey` (the entity's packed u32) and the `archVersion` (used by the
+     * record stage to invalidate its per-entity GPU buffer cache when the
+     * archetype storage grew). Absent (`undefined`) means the record stage
+     * falls back to the shared 1-element identity-mat4 storage buffer +
+     * `drawIndexed(.., 1, ..)`.
+     */
+    readonly instances?: InstancesSnapshot;
+    /**
+     * feat-20260625-sprite-instances-and-tilemap-terrain-static-batch M3 / w10
+     * (plan-strategy D-1 + D-9): when the entity carries a `SpriteInstances`
+     * component the extract stage materialises a paired snapshot — packed mat4
+     * `transforms` (16 f32, stride 16) + per-instance UV `regions` (4 f32,
+     * stride 4) — plus the same cache fingerprint pair (`cacheKey` = entity
+     * packed u32, `archVersion` = archetype version stamp at snapshot time).
+     * The record stage interleaves the two arrays into an 80B-per-instance
+     * single GPU buffer routed through `@group(3) @binding(0)` (BGL unchanged,
+     * D-1). Absent (`undefined`) means the entity is not a `SpriteInstances`
+     * carrier; the record stage falls back to its existing sprite path
+     * (material UBO region + identity-instance buffer).
+     *
+     * Three structured `EcsError` codes fire at extract entry and skip the
+     * renderable on violation (charter P3 explicit failure):
+     *   - `'sprite-instances-mutually-exclusive-with-instances'`
+     *   - `'sprite-instances-requires-sprite-shading-model'`
+     *   - `'sprite-instances-count-mismatch'`
+     */
+    readonly spriteInstances?: SpriteInstancesSnapshot;
+    /**
+     * feat-20260523-skin-skeleton-animation M2 / T-21: when the entity carries
+     * a `Skin` component the extract stage populates this field with the
+     * skin palette slice metadata. The record stage uses this to route the
+     * draw to `forgeax::pbr-skin` pipeline + set the palette dynamic offset.
+     * Absent (`undefined`) means the entity is not skinned.
+     */
+    readonly skin?: SkinPaletteSlice;
+    /**
+     * ECS-owned morph weights. Presence selects the Standard Pipeline CPU
+     * specialized deformation lane; the asset remains the source of target
+     * deltas and the record stage only receives this frozen POD snapshot.
+     */
+    readonly morph?: MorphSnapshot;
+    /** Detached M2 authoring facts for the optional Points/Lines projection. */
+    readonly pointsLines?: PointsLinesRetainedSnapshot;
+}
+export interface MorphSnapshot {
+    readonly weights: Float32Array;
+    readonly targetCount: number;
+}
+export interface GpuDrivenDrawSnapshot {
+    readonly kind: 'indexed' | 'non-indexed';
+    readonly first: number;
+    readonly count: number;
+    readonly baseVertex: number;
+    readonly materialSlot: number;
+    readonly topology: PrimitiveTopology;
+    readonly pipelineClass: string;
+    readonly materialResourceClass: string;
+}
+export interface InstancesSnapshot {
+    /** Packed column-major mat4 transforms (16 f32 per instance). */
+    readonly transforms: Float32Array;
+    /** Number of instances (transforms.length / 16). */
+    readonly instanceCount: number;
+    /** Stable per-entity GPU buffer cache key (the packed Entity u32). */
+    readonly cacheKey: number;
+    /**
+     * Archetype version stamp at snapshot time. The record stage compares this
+     * against its cached version per cacheKey; a bump means the underlying
+     * BufferPool slot may have grown / been reallocated, forcing a fresh
+     * `device.createBuffer + queue.writeBuffer` round.
+     */
+    readonly archVersion: number;
+}
+/**
+ * feat-20260625-sprite-instances-and-tilemap-terrain-static-batch M3 / w10:
+ * extract-stage view of a `SpriteInstances` carrier (2D peer of
+ * `InstancesSnapshot`).
+ *
+ * Field shapes mirror `InstancesSnapshot` so the record-stage cache protocol
+ * (`(cacheKey, archVersion, byteLength)` fingerprint triple) is reused
+ * verbatim. The byte length consumed at upload time is the sum
+ * `transforms.byteLength + regions.byteLength` (= 80*N for N instances,
+ * plan-strategy D-1 interleaved single-buffer); the record stage builds the
+ * 80B/instance interleaved buffer once per (entity, archVersion, byteLength)
+ * fingerprint change.
+ */
+export interface SpriteInstancesSnapshot {
+    /** Packed column-major mat4 transforms (16 f32 per instance, stride 16). */
+    readonly transforms: Float32Array;
+    /** Per-instance UV vec4 regions (4 f32 per instance, stride 4). */
+    readonly regions: Float32Array;
+    /**
+     * Number of instances. Derived from `transforms.length / 16` (equivalently
+     * `regions.length / 4`); the extract-entry validator guarantees the two
+     * derivations agree, otherwise it fires
+     * `'sprite-instances-count-mismatch'` and skips the renderable.
+     */
+    readonly instanceCount: number;
+    /** Stable per-entity GPU buffer cache key (the packed Entity u32, D-9). */
+    readonly cacheKey: number;
+    /** Archetype version stamp at snapshot time (cache invalidation fingerprint). */
+    readonly archVersion: number;
+}
+/**
+ * TransformSnapshot: extract-stage view of one entity's resolved world
+ * transform (feat-20260601 D-3). Holds the single `world` mat4 (column-major
+ * 16 floats, copied from the entity's `Transform.world` view written by
+ * propagateTransforms). The record stage copies these 16 floats straight into
+ * the mesh SSBO slot (zero `mat4.compose`); position / scale consumers derive
+ * from the mat4 via `mat4.getTranslation` / basis-column lengths.
+ */
+export interface TransformSnapshot {
+    readonly world: Float32Array;
+}
+/**
+ * MaterialSnapshot: extract-stage view of one entity's material asset (M2 / w6
+ * of feat-20260517-merge-mesh-renderer-material-renderer; plan-strategy section 2.3).
+ *
+ * Adds optional `baseColorTexture` + `sampler` slots (consumed by the record
+ * stage's textured-material code path; M3 / w10 dropped the cast-over-firstMaterial
+ * pattern in favour of direct snapshot field reads).
+ *
+ * feat-20260522-learn-render-3-1-sponza-model-loading-with-multi-l M4 extends
+ * the snapshot with `metallicRoughnessTexture` and `normalTexture`
+ * so the record stage can wire PBR texture bindings 4 and 6
+ * from real GPU views instead of placeholder 1x1 white / flat-normal views.
+ *
+ * Bounded scope: the snapshot tracks only what the record stage actually
+ * consumes today (charter proposition 5 consistent abstraction; YAGNI for
+ * future-proof field bloat). Future MaterialAsset extensions (emissive / etc)
+ * drive snapshot extensions when the record stage starts consuming them, not
+ * vice-versa.
+ *
+ * tweak-20260701 M1: `shadingModel` field removed — shader identity via
+ * {@link materialShaderId} is the single source of truth for material dispatch.
+ */
+export interface MaterialSnapshot {
+    readonly baseColor: Vec3;
+    readonly metallic: number;
+    readonly roughness: number;
+    readonly clearcoat?: number | undefined;
+    readonly clearcoatRoughness?: number | undefined;
+    /** Authored Standard PBR specular tint in linear runtime color space. */
+    readonly specularTint?: readonly [number, number, number] | undefined;
+    /**
+     * Schema-driven material shader identifier (feat-20260523 M4-T05).
+     * Populated when the material asset uses the schema-driven path
+     * (payload.materialShader set). Undefined for unlit/sprite legacy
+     * materials and for case-B defaultMaterialSnapshot.
+     *
+     * The record stage uses this as the pipeline cache key first-level
+     * discriminator (M4-T06).
+     */
+    readonly materialShaderId?: string | undefined;
+    /**
+     * Stable source handle for the material asset. Record uses this only for
+     * same-frame assembly reuse; GPU bind-group validity still comes from the
+     * resource-identity cache.
+     */
+    readonly materialHandle?: number | undefined;
+    /**
+     * The selected forward-pass state for this exact material. A mesh can bind
+     * different materials to its submeshes, so pipeline selection must read the
+     * state from the submesh snapshot rather than the entity's first material.
+     */
+    readonly renderState?: MaterialRenderState | undefined;
+    /**
+     * Schema-driven parameter snapshot (feat-20260523 M4-T05).
+     * Populated alongside materialShaderId. Maps param name to its
+     * runtime-resolved value: number for scalar params, number[] for
+     * vec/color params, string (GUID) for texture2d/sampler params.
+     */
+    readonly paramSnapshot?: Readonly<Record<string, number | number[] | string>> | undefined;
+    /** Effective MaterialAsset parameter contract used to lay out this snapshot. */
+    readonly materialParamSchema?: readonly ParamSchemaEntry[] | undefined;
+    /** Authored per-slot UV set and KHR texture transform metadata. */
+    readonly textureCoordinates?: ReadonlyMap<string, MaterialTextureCoordinates> | undefined;
+    /**
+     * User-region texture handles keyed by paramSchema field name
+     * (feat-20260621-learn-render-5-5-parallax M2 / w7). The SSOT carrier for
+     * EVERY texture the shader's `derive(paramSchema).textureFieldNames`
+     * declares — `baseColorTexture` / `metallicRoughnessTexture` /
+     * `normalTexture` for built-in standard-PBR, plus each custom field such as
+     * `heightTexture` (LO 5.5 parallax). The record stage iterates this map to
+     * assemble the user-region bind group per the per-shader BGL (w8), so a 4th
+     * (or Nth) texture flows end-to-end without a hardcoded field list.
+     *
+     * Populated by iterating `textureFieldNames`; absent keys mean the
+     * paramValue was missing / mis-typed (record falls back to default white).
+     * `emissiveTexture` / `occlusionTexture` are NOT here — they live in the
+     * engine-injection lightmap region (their named fields below feed
+     * `appendInjection('lightmap')`, not the user-region).
+     */
+    readonly textureHandles?: ReadonlyMap<string, Handle<'TextureAsset', 'shared'>> | undefined;
+    /**
+     * User-region texture field names whose paramValue resolved to a VideoAsset
+     * (kind `'video'`) rather than a static TextureAsset
+     * (feat-20260623-world-space-video-asset M4 / w14, D-5). The video GUID
+     * occupies the same texture2d values slot a static texture would (P4:
+     * one binding shape), but extract routes it here instead of `textureHandles`
+     * so the record stage pulls the current-frame view from the transient
+     * DynamicTextureStore (D-3) instead of `GpuResidencyCache.ensureResident`
+     * (which has no `video` arm; AC-08). Each entry also carries the resolved
+     * clip handle so the record stage can key the per-frame upload.
+     *
+     * Producer/consumer split (charter P5 / AC-07 gate): extract owns the
+     * asset->snapshot translation; record consumes this POD field only — it never
+     * reaches back into the MaterialAsset to learn a field is video-sourced.
+     */
+    readonly videoTextureFields?: ReadonlyMap<string, Handle<'VideoAsset', 'shared'>> | undefined;
+    /** Authored sampler handles keyed by their matching texture parameter. */
+    readonly samplerHandles?: ReadonlyMap<string, Handle<'SamplerAsset', 'shared'>> | undefined;
+    readonly baseColorTexture?: Handle<'TextureAsset', 'shared'> | undefined;
+    /**
+     * PBR metallic-roughness texture handle (present for PBR/sprite/skin
+     * shaders). Undefined for the default-unlit shader
+     * (materialShaderId === 'forgeax::default-unlit'). The record stage reads
+     * this to write GPU view at material bind-group binding 4, falling
+     * back to a 1x1 white placeholder when undefined.
+     *
+     * feat-20260522-learn-render-3-1-sponza-model-loading-with-multi-l M4:
+     * field added so the record stage can wire real metallic-roughness
+     * textures from Sponza glTF materials (M3 writes the handle into
+     * SchemaDrivenMaterialAsset values; M4 extract carries it through to the snapshot).
+     */
+    readonly metallicRoughnessTexture?: Handle<'TextureAsset', 'shared'> | undefined;
+    /**
+     * PBR tangent-space normal texture handle (present for PBR/sprite/skin
+     * shaders). Undefined for the default-unlit shader
+     * (materialShaderId === 'forgeax::default-unlit'). The record stage reads
+     * this to write GPU view at material bind-group binding 6, falling
+     * back to a (0.5,0.5,1.0) flat-normal placeholder when undefined.
+     *
+     * feat-20260522-learn-render-3-1-sponza-model-loading-with-multi-l M4:
+     * field added symmetrically with metallicRoughnessTexture so the record
+     * stage can wire real normal textures from Sponza glTF materials.
+     */
+    readonly normalTexture?: Handle<'TextureAsset', 'shared'> | undefined;
+    /** Scalar applied to tangent-space normal XY after the normal texture sample. */
+    readonly normalScale?: number | undefined;
+    readonly emissive?: readonly [number, number, number] | undefined;
+    readonly emissiveIntensity?: number | undefined;
+    readonly emissiveTexture?: Handle<'TextureAsset', 'shared'> | undefined;
+    readonly occlusionTexture?: Handle<'TextureAsset', 'shared'> | undefined;
+    readonly occlusionStrength?: number | undefined;
+    /**
+     * Transparent composition flag derived from the first pass's
+     * `renderState.blend` presence on the underlying
+     * {@link MaterialPass} (feat-20260626-collapse M2: blend
+     * presence is the SSOT after `MaterialPass.transparent` was
+     * dropped in M1).
+     *
+     * The record stage reads this to drive both the LDR split-pass
+     * decision and the premultiplied-alpha blend resolution on the
+     * generic materialShaderId pipeline path — shader-agnostic, decoupled
+     * from the legacy `shadingModel` discriminant (feat-20260625 M2 D-3,
+     * finalised in w15; `shadingModel` field removed in tweak-20260701 M1).
+     *
+     * Extract derives this from the first pass's `renderState.blend !==
+     * undefined` (post-feat-20260626-collapse: blend presence is the
+     * single SSOT for "this material is transparent on the geometry
+     * pipeline cache key"). Multi-pass materials whose mix of opaque +
+     * transparent passes need finer routing should split into separate
+     * MaterialAsset entries (the normal forgeax pattern).
+     *
+     * Type is `boolean | undefined` (derived): `undefined` means "no
+     * passes / unknown"; consumers must read `=== true` / `!== true` to
+     * stay correct under both populated and absent cases.
+     */
+    readonly transparent?: boolean | undefined;
+}
+interface MaterialCacheChainIdentity {
+    readonly asset: MaterialAsset;
+    readonly parentGuid: string | undefined;
+}
+export interface MaterialSnapshotCacheEntry {
+    readonly snapshot: MaterialSnapshot;
+    readonly passes: readonly MaterialPass[];
+    /** Root/chain identities are present only on cross-frame-safe entries. */
+    readonly chain?: readonly MaterialCacheChainIdentity[];
+    /** AssetRegistry epoch at which the root/parent chain was last validated. */
+    readonly catalogEpoch?: number;
+    /** True only when every object reachable from the authored chain is frozen. */
+    readonly crossFrameSafe: boolean;
+}
+export type MaterialSnapshotCache = Map<number, MaterialSnapshotCacheEntry>;
+export type MaterialSnapshotCachesByWorld = WeakMap<World, MaterialSnapshotCache>;
+export interface DispatchEntry {
+    readonly entityIndex: number;
+    readonly materialHandle: number;
+    readonly renderableIndex: number;
+    readonly passIndex: number;
+    readonly queue: number;
+    /**
+     * Signed i32 from the entity's {@link Layer} component value (default 0 for
+     * entities without a Layer). Primary sort key for the transparent-dispatch
+     * sort in {@link render-system.ts}: lower value = drawn first (behind).
+     */
+    readonly layer: number;
+    readonly tags: Record<string, string>;
+    readonly renderState: MaterialRenderState | undefined;
+    readonly defines: Record<string, string> | undefined;
+    readonly vertexEntry: string | undefined;
+    readonly fragmentEntry: string | undefined;
+    readonly materialShaderId: string | undefined;
+    readonly paramSnapshot: Readonly<Record<string, number | number[] | string>> | undefined;
+    /**
+     * Stencil reference value from {@link MaterialPass.stencilReference}
+     * (draw-call dynamic state). Folded during extract for per-draw consumption
+     * in the record stage. `undefined` when the pass does not set a reference
+     * value (record stage falls back to WebGPU default 0).
+     */
+    readonly stencilReference?: number;
+}
+/**
+ * Stable-sort dispatch entries by `queue` value ascending.
+ * Returns a new sorted array (does not mutate the input).
+ * Same-queue entries preserve insertion order (AC-11 stable-order guarantee).
+ */
+export declare function sortDispatchByQueue<E extends {
+    readonly queue: number;
+}>(entries: readonly E[]): E[];
+export interface ExtractedFrame {
+    readonly cameras: CameraSnapshot[];
+    readonly lights: ExtractedLights;
+    readonly renderables: RenderableSnapshot[];
+    /**
+     * Single dispatch list sorted by queue value (ascending, stable sort).
+     * Replaces the old opaqueDispatch / transparentDispatch / overlayDispatch
+     * three-bucket model per plan-strategy D-3.
+     */
+    readonly dispatch: DispatchEntry[];
+    readonly skylight: SkylightSnapshot | undefined;
+    readonly skylightCount: number;
+    readonly skybox: SkyboxSnapshot | undefined;
+    readonly skyboxCount: number;
+    /**
+     * feat-20260528-frustum-culling M3 / w11: frustum culling statistics
+     * collected during the extract phase. `total` is the count of entities
+     * that reached the culling decision point; `culled` is the count of
+     * those that were removed from renderables by frustum culling.
+     */
+    readonly frustumStats: {
+        readonly culled: number;
+        readonly total: number;
+    };
+    /** Candidate entities rejected by author visibility before resource parsing. */
+    readonly visibilityStats: {
+        readonly explicitlyHidden: number;
+    };
+    /**
+     * Per-frame post-process params snapshot collected from PostProcessParams
+     * entities (D-1: data-driven params channel). Maps shader id to the
+     * raw data bytes (Uint8Array = FieldValueType<'buffer'>). Last-one-wins
+     * when multiple entities bear the same shader id.
+     * Empty map when no PostProcessParams entities exist.
+     */
+    readonly postProcessParams: ReadonlyMap<string, Uint8Array>;
+    /** Visibility snapshots prepared for each contributing World. */
+    readonly visibilitySnapshots: readonly VisibilitySnapshot[];
+    /** World-labelled snapshots passed to generic RenderFeature extraction. */
+    readonly featureVisibilitySnapshots: readonly RenderFeatureWorldVisibilitySnapshot[];
+    /** Built-in hidden candidates, retained for host-side producer deduplication. */
+    readonly hiddenEntityReports: readonly RenderFeatureHiddenEntityReport[];
+}
+/**
+ * feat-20260608 M5 amend / w11-a: resolve a single MaterialAsset handle into
+ * a per-submesh MaterialSnapshot. Used by the extractFrame archetype loop to
+ * build `RenderableSnapshot.materials[]` for indices >= 1 (the entity-level
+ * snapshot at index 0 is built inline because it also drives multi-pass
+ * DispatchEntry creation + sprite-region overrides; per-submesh secondary
+ * materials are non-sprite + single-pass-equivalent for the record stage's
+ * UBO upload, so this helper produces a plain MaterialSnapshot only).
+ *
+ * Returns `defaultMaterialSnapshot()` (mid-grey unlit) for handle=0 (case-B
+ * sentinel, mirroring the inline path) and on each unresolved / non-material
+ * asset (so a partially-mis-registered multi-material entity still renders
+ * the resolvable submeshes; the count-mismatch validator already filtered
+ * the count-disagreement case earlier).
+ */
+export declare function resolveMaterialSnapshot(handleRaw: number, world: World, assetsRef: AssetRegistry, materialSnapshotCache?: MaterialSnapshotCache, persistentMaterialSnapshotCache?: MaterialSnapshotCache): MaterialSnapshot;
+/**
+ * feat-20260612-skin-palette-per-frame-upload M2 / m2-6: narrow per-frame
+ * pipeline surface consumed by `extractFrame`. Today only `skinPaletteAllocator`
+ * crosses the seam (the allocator owns the per-frame palette buffer + cursor;
+ * extract calls `resetForFrame` at frame entry then `allocateSlice` +
+ * `writeJointPalette` per skinned entity). Kept narrow on purpose — extract
+ * does NOT see the rest of `PipelineState` to avoid a circular import via
+ * `render-system.ts`.
+ */
+export interface ExtractPipelineSurface {
+    readonly skinPaletteAllocator: SkinPaletteAllocator | null;
+}
+export declare function pssmSplit(nearPlane: number, farPlane: number, cascadeCount: number, splitLambda: number): Float32Array;
+/**
+ * Build 6 face view-proj matrices for an omnidirectional shadow caster
+ * (point-light cube map). Returns 6 mat4 (column-major 16-float each) in face
+ * order [+X, -X, +Y, -Y, +Z, -Z] matching WebGPU cube layer convention.
+ *
+ * Each matrix is `proj * view` where:
+ *   - `view = lookAt(lightPos, lightPos + faceLook[i], faceUp[i])`
+ *   - `proj = perspective(PI/2, 1, near, far)` (WebGPU [0, 1] NDC short name)
+ *
+ * The returned `Mat4[]` length is always exactly 6. Caller can flatten into a
+ * 96-float (6 mat4) Float32Array for UBO upload (T-M1-7).
+ *
+ * @param lightPos world-space position of the point light (from companion Transform)
+ * @param near near plane distance (PointLightShadow.nearPlane)
+ * @param far  far plane distance  (PointLightShadow.farPlane)
+ */
+export declare function buildPointShadowMatrices(lightPos: Vec3, near: number, far: number): Mat4[];
+/**
+ * bug-20260710-editor-cross-world-shadow: the camera-frustum subset of
+ * {@link CameraSnapshot} that the directional-CSM matrix builder consumes.
+ * Extracted so the builder can run both inside {@link extractFrame} (single
+ * world) AND at the {@link extractFrames} merge layer, where the camera and the
+ * directional light may originate in DIFFERENT worlds (the editor
+ * editorWorld/sceneWorld super-composite). A cameraless world produces zero
+ * lightViewProj matrices, so the merge layer MUST recompute using the surfaced
+ * camera — see {@link computeDirectionalCsm}.
+ */
+export interface CsmCameraData {
+    readonly world: Float32Array;
+    readonly fov: number;
+    readonly aspect: number;
+    readonly near: number;
+    readonly far: number;
+    readonly projection: 'perspective' | 'orthographic';
+    readonly orthoLeft: number;
+    readonly orthoRight: number;
+    readonly orthoBottom: number;
+    readonly orthoTop: number;
+}
+/**
+ * bug-20260710-editor-cross-world-shadow: the raw directional-shadow config a
+ * DirectionalLight carries, threaded onto {@link ExtractedLights} so the merge
+ * layer can recompute CSM matrices against the surfaced camera. Distinct from
+ * the *computed* outputs (lightViewProj / splitPlanes) also on ExtractedLights.
+ */
+export interface DirectionalCsmConfig {
+    readonly cascadeCount: number;
+    readonly splitLambda: number;
+    readonly cascadeBlend: number;
+    readonly mapSize: number;
+    readonly shadowDistance: number;
+}
+/**
+ * bug-20260710-editor-cross-world-shadow: computed directional-CSM output —
+ * the per-cascade light-view-projection matrices plus the derived cascade
+ * metadata. Returned by {@link computeDirectionalCsm}; `undefined` when the
+ * config or camera is missing (caller leaves the fields undefined).
+ */
+export interface DirectionalCsmResult {
+    readonly lightViewProj: Float32Array[];
+    readonly splitPlanes: Float32Array;
+    readonly cascadeCount: number;
+    readonly cascadeBlend: number;
+    readonly shadowMapSize: number;
+}
+/**
+ * bug-20260710-editor-cross-world-shadow: pure directional-CSM matrix builder,
+ * extracted verbatim from the former inline block in {@link extractFrame} (the
+ * PSSM split + per-cascade frustum-slice AABB fit + orthographic light
+ * projection). It is now a free function so BOTH the per-world extract and the
+ * cross-world merge layer can call it — the merge layer is the only place that
+ * pairs the first-hit directional light of one world with the surfaced camera
+ * of another (editor super-composite). Returns `null` when there is no camera
+ * to fit against (a cameraless world's directional light yields no matrices —
+ * the caller leaves lightViewProj undefined rather than emitting zero matrices
+ * that the WGSL reader would sample as NaN → "fully lit").
+ *
+ * Byte-identical to the prior inline computation for the single-world case
+ * (same PSSM lambda, same toward-light Z reach RC-2 fix, same clip-space
+ * matrix / tile-placement-in-shader split).
+ */
+export declare function computeDirectionalCsm(direction: Vec3, config: DirectionalCsmConfig, cameraData: CsmCameraData | undefined): DirectionalCsmResult | null;
+/**
+ * feat-20260709-editor-world-partition M1 / w4 (AC-08, plan-strategy §2 D-3):
+ * the owner index that previously served BOTH cameras and singleton render
+ * resources (skylight / skybox / postProcessParams) is split into two
+ * independent indices. `cameraOwner` selects the world whose cameras are
+ * surfaced; `resourceOwner` selects the world whose singleton resources are
+ * surfaced. A single number is accepted as the backward-compatible legacy form
+ * where `cameraOwner === resourceOwner === owner` (single-world callers +
+ * frame-loop stay byte-identical; the hard `{ owner }` cutover lands in M2).
+ */
+export interface ExtractFramesOwner {
+    readonly cameraOwner: number;
+    readonly resourceOwner: number;
+}
+export interface PreparedExtractContext {
+    readonly assets: AssetRegistry | null | undefined;
+    readonly pipelineState: ExtractPipelineSurface | null | undefined;
+    readonly materialSnapshotCache: MaterialSnapshotCache | undefined;
+    readonly cull: 'self' | 'none' | 'external';
+    readonly cullCameras: readonly CameraSnapshot[] | undefined;
+    readonly hierarchy: SceneHierarchySnapshot;
+    readonly visibility: VisibilitySnapshot;
+}
+export declare function extractCameraSnapshots(world: World): CameraSnapshot[];
+export declare function prepareExtractContext(world: World, options?: {
+    readonly assets?: AssetRegistry | null;
+    readonly pipelineState?: ExtractPipelineSurface | null;
+    readonly materialSnapshotCache?: MaterialSnapshotCache;
+    readonly cull?: 'self' | 'none' | 'external';
+    readonly cullCameras?: readonly CameraSnapshot[];
+}): PreparedExtractContext;
+export declare function extractFrames(worlds: readonly World[], owner: number | ExtractFramesOwner, assets?: AssetRegistry | null, pipelineState?: ExtractPipelineSurface | null, materialSnapshotCachesByWorld?: MaterialSnapshotCachesByWorld, options?: {
+    readonly cull?: 'normal' | 'none';
+}): ExtractedFrame;
+export declare function extractFrame(world: World, context: PreparedExtractContext): ExtractedFrame;
+export declare function defaultMaterialSnapshot(materialHandle?: number): MaterialSnapshot;
+export {};
+//# sourceMappingURL=render-system-extract.d.ts.map