@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,1096 @@
+import type { EntityHandle, 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, MaterialError, MaterialPass, MaterialRenderState, MaterialTextureCoordinates, ParamSchemaEntry, PrimitiveTopology } from '@forgeax/engine-types';
+import { type Result } from '@forgeax/engine-types';
+import type { RenderAssetPort } from './assets/render-asset-port';
+import { type Antialias, type BloomEnabled, type Tonemap } from './components';
+import { type ExtractedEnvironment } from './environment/extracted-environment';
+import { FogOwnerConflictError, FogParametersInvalidError, type RenderError } from './errors/render';
+import { type DirectionalCsmConfig, type DirectionalCsmResult } from './extract/directional-csm';
+import { type DerivedMaterialSlotProjection } from './extract/material-interface';
+import { type ParamSchemaProjectionCensus } from './param-schema-projection-census';
+import { type RenderCandidateDomain, type RenderDispatchMembership } from './render-dispatch-membership';
+export { type CascadeVolume, type CascadeVolumeSet, CascadeVolumeSetBuilder, type CsmCameraData, computeDirectionalCsm, type DirectionalCsmConfig, type DirectionalCsmResult, directionalCascadeAtlasSize, directionalCascadeRasterViewport, pssmSplit, } from './extract/directional-csm';
+import { type VisibilitySnapshot } from './extract/visibility';
+import type { RenderFeatureHiddenEntityReport, RenderFeatureWorldVisibilitySnapshot } from './features/types';
+import type { RenderSceneFactInput } from './gpu-scene-schema';
+import { type MeshMaterialBindingDiagnostic, type MeshMaterialBindingSource } from './mesh-material-bindings';
+import type { SkinPaletteAllocator } from './systems/skin-palette-allocator';
+export interface CameraSnapshot {
+    /** Renderer-local World attachment identity. */
+    readonly worldId: number;
+    /** Packed ECS entity handle; its high bits retain the entity generation. */
+    readonly entityKey: number;
+    /** World-space camera translation (mat4.getTranslation of Transform.world). */
+    readonly position: Vec3;
+    /**
+     * Resolved world-space camera mat4 (column-major 16 floats), copied from the
+     * entity's `Transform.world` view. The record stage derives the view matrix
+     * as `mat4.invert(world)` (feat-20260601 D-3: read world mat4 -> invert; no
+     * recompose from decomposed TRS).
+     */
+    readonly world: Float32Array;
+    readonly fov: number;
+    readonly aspect: number;
+    readonly near: number;
+    readonly far: number;
+    /**
+     * Camera projection variant (`'perspective'` | `'orthographic'`),
+     * surfaced through the closed string-literal union narrowed from the
+     * Camera schema's `projection` f32 discriminator. Drives the CSM
+     * frustum-corner builder in render-system-extract: perspective uses
+     * mat4.perspective(fov, aspect, ...); orthographic uses mat4.ortho
+     * (left, right, bottom, top, ...). Without this discrimination an
+     * orthographic camera (fov=0) would feed a degenerate matrix into
+     * the CSM AABB-fit and the shadow atlas would never be written
+     * (feat-20260613 M6 / w20 fix).
+     */
+    readonly projection: 'perspective' | 'orthographic';
+    /** Orthographic left frustum plane (only consumed when projection === 'orthographic'). */
+    readonly orthoLeft: number;
+    /** Orthographic right frustum plane. */
+    readonly orthoRight: number;
+    /** Orthographic bottom frustum plane. */
+    readonly orthoBottom: number;
+    /** Orthographic top frustum plane. */
+    readonly orthoTop: number;
+    /**
+     * feat-20260519-tonemap-reinhard-mvp / M3 / T-M3.1: tone-map mode
+     * surfaced through the closed string-literal union (`tonemapFromF32`
+     * narrows the schema's `f32` discriminator). The record stage branches
+     * on this field to pick the geometry pipeline target format
+     * (`bgra8unorm-srgb` for `'none'` / `'rgba16float'` for
+     * `'reinhard-extended'`) and to decide whether to emit the post-process
+     * tonemap fullscreen pass.
+     */
+    readonly tonemap: Tonemap;
+    /** Linear pre-multiplier applied before the luminance compute (T-M3.3). */
+    readonly exposure: number;
+    /** Bright-end break point Lw for the extended Reinhard curve (T-M3.3). */
+    readonly whitePoint: number;
+    /**
+     * feat-20260528-fxaa-post-processing / w3: anti-alias mode surfaced
+     * through the closed string-literal union (antialiasFromF32 narrows
+     * the schema's f32 discriminator). The record stage branches on this
+     * field to decide whether to emit the FXAA post-process pass.
+     */
+    readonly antialias: Antialias;
+    /** Explicit authoring fence for discontinuous view changes. */
+    readonly historyVersion: number;
+    /**
+     * feat-20260531-bloom-first-declarative-render-graph-pass / w4: bloom
+     * enabled discriminator surfaced through the closed string-literal union
+     * (bloomEnabledFromF32 narrows the schema's f32 discriminator). The record
+     * stage branches on this field to decide whether to emit the bloom
+     * post-process pipeline.
+     */
+    readonly bloom: BloomEnabled;
+    /** HDR luminance threshold for bright-pass extraction (D-3 default 1.0). */
+    readonly bloomThreshold: number;
+    /** Multiplier applied to the blurred bloom contribution in composite (D-3 default 1.0). */
+    readonly bloomIntensity: number;
+    /** Gaussian blur kernel radius, clamped [1.0, 4.0] in shader (D-3 default 4.0). */
+    readonly bloomBlurRadius: number;
+    /**
+     * feat-20260709 M3 / D-3: clear-color RGBA sourced from the Camera entity's
+     * inline `array<f32,4>` column (first-archetype-hit per OOS-2). Collapsed
+     * from the feat-20260608 clearR/G/B/A snapshot quartet into one field aligned
+     * with the light snapshot shape. AI users override per-camera by setting
+     * `clearColor` when spawning the Camera entity; default is opaque black
+     * `[0, 0, 0, 1]` (D-5). The record stage reads these values verbatim into
+     * the LoadOp::Clear color slot.
+     */
+    readonly clearColor: readonly [number, number, number, number];
+}
+export type RenderVisibilityViewKind = 'main' | 'cascade';
+/**
+ * One of the four CPU visibility views. Cascade membership is copied from the
+ * canonical CascadeVolumeSet; this descriptor never derives a second volume.
+ */
+export interface RenderVisibilityViewDescriptor {
+    readonly viewId: string;
+    readonly kind: RenderVisibilityViewKind;
+    readonly cascadeIndex: number | undefined;
+    readonly planes: Float32Array;
+    /** Conservative world AABB used by the persistent spatial owner. */
+    readonly broadphaseWorldAabb?: Float32Array | undefined;
+    /** Canonical raster matrix for a cascade; absent for the main view. */
+    readonly lightViewProj?: Float32Array | undefined;
+    readonly casterCandidateIndices: ReadonlySet<number>;
+    readonly volumeRevision: number | undefined;
+    readonly spatialIndexRevision: number | undefined;
+}
+/** Build the main camera plus exactly three CSM view descriptors. */
+export declare function buildRenderVisibilityViewDescriptors(input: {
+    readonly camera: CameraSnapshot | undefined;
+    readonly directionalCsm: DirectionalCsmResult | undefined;
+    readonly spatialIndexRevision?: number | undefined;
+}): readonly RenderVisibilityViewDescriptor[];
+/**
+ * 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';
+    /** ECS entity handle in the source World; diagnostic identity only. */
+    readonly entity: number;
+    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;
+    /** Canonical receiver/caster plan consumed by persistent scene and record. */
+    readonly directionalCsm?: DirectionalCsmResult;
+    /** Internal compatibility projection; the plan above remains canonical. */
+    readonly cascades?: DirectionalCsmResult['cascades'];
+}
+/**
+ * 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
+ * `GpuResourceStore.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;
+}
+/** Retained scene-radiance Fog facts; parameters remain outside inspection. */
+export interface FogSnapshot {
+    readonly color: readonly [number, number, number];
+    readonly density: number;
+    readonly heightFalloff: number;
+    readonly maxOpacity: number;
+    readonly revision: number;
+}
+/** Internal owner facts needed to publish a Fog snapshot transactionally. */
+export interface FogSelection {
+    readonly snapshot: FogSnapshot | undefined;
+    readonly resourceOwner: number;
+    readonly entity: EntityHandle | undefined;
+}
+export type FogSelectionError = Extract<RenderError, FogOwnerConflictError | FogParametersInvalidError>;
+export type FogSelectionResult = Result<FogSelection, FogSelectionError>;
+/** Select and validate the single Fog authoring entity from resourceOwner. */
+export declare function selectFog(world: World | undefined, resourceOwner: number): FogSelectionResult;
+/**
+ * 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 `GpuResourceStore.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;
+    /**
+     * Bounds-only transform derived from authored local TRS when the resolved
+     * world column is still its identity default. This preserves the producer
+     * bounds source for direct extract-before-propagate paths without changing
+     * the render SSOT, which remains `transform.world`.
+     */
+    readonly boundsWorld?: Float32Array;
+    /** Candidate-domain copy of all instance transforms, retained before cull. */
+    readonly candidateInstanceTransforms?: Float32Array;
+    /** Finite producer-owned local bounds retained for persistent CPU view work. */
+    readonly localAabb?: Float32Array;
+    /**
+     * Optional authoring/pack-owned scene facts. The projection supplies
+     * explicit `unknown` defaults when this field is absent; it never infers
+     * staticness or shadow eligibility from frame-local behavior.
+     */
+    readonly sceneFact?: RenderSceneFactInput;
+    /**
+     * Forward raster item facts consumed by the first GPU-driven rigid lane.
+     * Each entry carries its source submesh, pass identity, and resolved queue.
+     */
+    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;
+    /** Stable pre-main-cull candidate index used by the directional CSM plan. */
+    readonly candidateIndex?: 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;
+    /** Current morph producer weights; previous values come from the submitted projection epoch. */
+    readonly morphWeights?: Float32Array;
+    /** Previous facts from the renderer's last successful submission epoch. */
+    readonly temporal?: RenderableTemporalSnapshot;
+}
+export type RenderablePreviousSource = 'last-submitted' | 'current-seed';
+export type RenderableReactiveReason = 'new-slot' | 'generation-reuse' | 'reentered' | 'geometry-revision' | 'material-revision' | 'skinning-deformation' | 'morph-deformation';
+export interface RenderableTemporalSnapshot {
+    readonly previousEpoch: number | undefined;
+    readonly previousSource: RenderablePreviousSource;
+    readonly reactive: boolean;
+    readonly reactiveReasons: readonly RenderableReactiveReason[];
+    readonly previousTransform: TransformSnapshot;
+    readonly previousInstances: InstancesSnapshot | undefined;
+    readonly previousSkin: SkinPaletteSlice | undefined;
+    readonly previousMorphWeights: Float32Array | undefined;
+}
+export interface GpuDrivenDrawSnapshot {
+    /** Index into the resolved mesh submesh array. */
+    readonly submeshIndex: number;
+    /** Index of the corresponding material pass in the resolved pass list. */
+    readonly passIndex: number;
+    /** Effective queue copied from that pass; always resolved at extract time. */
+    readonly queue: number;
+    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;
+}
+/**
+ * feat-20260523-skin-skeleton-animation M2 / T-21 + T-24:
+ * per-draw palette slice metadata. Joint count + byte offset into the
+ * shared skin palette storage buffer.
+ *
+ * plan-strategy D-10: SkinPaletteSlice naming mirroring Bevy SkinByteOffset
+ * but with forgeax vocabulary (byteOffset not offset, jointCount not joint_count).
+ */
+export interface SkinPaletteSlice {
+    readonly jointCount: number;
+    /** CPU snapshot of the exact palette written for this extract epoch. */
+    readonly jointMatrices: Float32Array;
+    /**
+     * Byte offset INTO `buffer` for this slice. On the storage path the
+     * allocator returns one shared buffer + a per-entity cursor offset; on
+     * the uniform fallback path each slice owns its own GPU buffer (cap
+     * `maxUniformBufferBindingSize` 16 KiB cannot host shared dynOffset
+     * windows for >1 entity), so `byteOffset === 0` for every slice and
+     * `buffer` is the per-slice handle. Record stage reads both fields and
+     * does not branch on the path -- BG cache key includes `buffer`, so
+     * two paths converge at the same code.
+     */
+    readonly byteOffset: number;
+    /**
+     * Per-slice GPU buffer handle. M6: feat-20260612 collapsed the prior
+     * shared-buffer assumption (record-stage read `pipelineState
+     * .skinPaletteAllocator.buffer`) into a per-slice carrier so the
+     * uniform fallback path can return a per-entity buffer without
+     * branching the record stage.
+     */
+    readonly buffer: import('@forgeax/engine-rhi').Buffer;
+    /** Previous successful-submit palette, paired with {@link buffer}. */
+    readonly previousBuffer?: import('@forgeax/engine-rhi').Buffer | undefined;
+}
+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;
+    /** Canonical RenderAssetPort GUID used to join the production readiness tuple. */
+    readonly materialGuid?: 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;
+    /** Whether the resolved material owns a ShadowCaster pass. */
+    readonly shadowCaster?: boolean | 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;
+    /** Typed per-slot projection produced from the effective root schema. */
+    readonly derivedMaterialSlot?: DerivedMaterialSlotProjection | undefined;
+    /** Structured extract failure that the record stage must propagate and stop. */
+    readonly derivedMaterialError?: MaterialError | 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 any 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 `GpuResourceStore.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[];
+    /** RenderAssetPort 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[];
+    /** Author-visible snapshots retained before the main-view frustum cull. */
+    readonly candidateRenderables?: readonly RenderableSnapshot[];
+    /** Pass dispatch for the same pre-main-cull candidate domain. */
+    readonly candidateDispatch?: readonly DispatchEntry[];
+    /** Shared membership owner for the candidate dispatch domain. */
+    readonly candidateDispatchMembership?: RenderDispatchMembership;
+    /** Shared immutable candidate array/dispatch/index owner. */
+    readonly candidateDomain?: RenderCandidateDomain;
+    /** Resource-owner Fog snapshot retained for direct extract consumers. */
+    readonly fog?: FogSnapshot | undefined;
+    /**
+     * 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 environment: ExtractedEnvironment;
+    /**
+     * 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[];
+}
+/**
+ * Transparent-bucket dispatch entry — extends the dispatch snapshot with
+ * per-entity sort inputs precomputed at extract time.
+ *
+ * Field semantics:
+ *   - `layer` — primary sort key (signed i32 from `Layer.value`; default 0
+ *     for entities without a Layer component).
+ *   - `posX` / `posY` / `posZ` — world position from the entity's Transform.
+ *   - `pivotY` / `sizeY` — sprite's Y-axis foot offset inputs. `pivotY =
+ *     SpriteMaterialAsset.pivot[1]` (default 0.5); `sizeY` = Transform's
+ *     world scale Y (sprite quad's world-space height in unit-quad world
+ *     space — the unit quad is 1x1 so `Transform.scaleY` directly maps to
+ *     world height). The foot-Y formula `posY - pivotY * sizeY` is the
+ *     SSOT for the JRPG Y-sort path (mode=1, requirements §AC-10).
+ *   - `sortKey` — optional per-entity override from `SortKey.value`. When
+ *     present, `transparentSortEntries` uses it INSTEAD of the mode formula
+ *     for this entry (still gated by `layer` as the primary key).
+ *
+ * Plan-strategy §3.3 interface example + §AC-10 sort path + §AC-19
+ * derivation row 13 (this is the true new POD shape `@new-surface`; not a
+ * mere rename of an existing snapshot).
+ */
+export interface TransparentEntry {
+    readonly entityIndex: number;
+    readonly materialHandle: number;
+    readonly layer: number;
+    readonly posX: number;
+    readonly posY: number;
+    readonly posZ: number;
+    readonly pivotY: number;
+    readonly sizeY: number;
+    readonly sortKey?: number | undefined;
+    /**
+     * Index into the parallel `ExtractedFrame.renderables[]` array. M-3 /
+     * w25 record stage uses this to look up the `RenderableSnapshot`
+     * (Transform + mesh + material snapshot) belonging to this transparent
+     * entry after `transparentSortEntries` reorders the bucket. Optional
+     * for test fixtures that construct TransparentEntry literals by hand
+     * (w16 sort tests bypass renderables[] correlation); the real extract
+     * path always sets a non-negative integer index here.
+     */
+    readonly renderableIndex?: number | undefined;
+}
+export declare const resolveMaterialSnapshot: (handleRaw: number, world: World, assets: RenderAssetPort, gpuStore?: import("./gpu-resource-store").GpuResourceStore, materialSnapshotCache?: MaterialSnapshotCache, persistentMaterialSnapshotCache?: MaterialSnapshotCache, paramSchemaProjectionCensus?: ParamSchemaProjectionCensus) => MaterialSnapshot;
+export declare function refreshRenderableMaterialSnapshot(renderable: RenderableSnapshot, materialHandle: number, world: World, assets: RenderAssetPort, gpuStore?: import('./gpu-resource-store').GpuResourceStore, persistentMaterialSnapshotCache?: MaterialSnapshotCache, paramSchemaProjectionCensus?: ParamSchemaProjectionCensus): RenderableSnapshot | undefined;
+/**
+ * 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;
+}
+/**
+ * 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[];
+/**
+ * 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 {
+    /** Renderer-local identity of the World whose singleton resources are read. */
+    readonly worldId?: number | undefined;
+    readonly assets: RenderAssetPort | null | undefined;
+    readonly pipelineState: ExtractPipelineSurface | null | undefined;
+    readonly gpuStore: import('./gpu-resource-store').GpuResourceStore | undefined;
+    readonly materialSnapshotCache: MaterialSnapshotCache | undefined;
+    readonly cull: 'self' | 'none' | 'external';
+    readonly cullCameras: readonly CameraSnapshot[] | undefined;
+    readonly hierarchy: SceneHierarchySnapshot;
+    readonly visibility: VisibilitySnapshot;
+    /** @internal Debug-only ParamSchema compatibility census. */
+    readonly paramSchemaProjectionCensus?: ParamSchemaProjectionCensus | undefined;
+    /** @internal Refresh only compact lighting resources over an existing frame. */
+    readonly resourceRefreshBase?: ExtractedFrame;
+    /**
+     * @internal Restrict the MeshRenderer row source to known entities. The
+     * query is addressed through Query.at(), so this path does not iterate the
+     * world's renderable tables. Resource queries remain unchanged.
+     */
+    readonly targetRenderableEntities?: readonly EntityHandle[];
+}
+export declare function extractCameraSnapshots(world: World): CameraSnapshot[];
+export declare function refreshExtractedFrameCameras(world: World, frame: ExtractedFrame): ExtractedFrame;
+/**
+ * Refresh only the resource-owned PostProcessParams map after an ECS journal
+ * update. Post-process parameter entities are not render-domain slots; making
+ * their transient byte payload visible must not rebuild candidates, dispatch,
+ * topology, or the GPU scene.
+ */
+export declare function refreshExtractedFramePostProcessParams(world: World, frame: ExtractedFrame): ExtractedFrame;
+export declare function prepareExtractContext(world: World, options?: {
+    readonly worldId?: number;
+    readonly assets?: RenderAssetPort | null;
+    readonly pipelineState?: ExtractPipelineSurface | null;
+    readonly gpuStore?: import('./gpu-resource-store').GpuResourceStore;
+    readonly materialSnapshotCache?: MaterialSnapshotCache;
+    readonly cull?: 'self' | 'none' | 'external';
+    readonly cullCameras?: readonly CameraSnapshot[];
+    readonly paramSchemaProjectionCensus?: ParamSchemaProjectionCensus;
+}): PreparedExtractContext;
+export declare function extractFrames(worlds: readonly World[], owner: number | ExtractFramesOwner, assets?: RenderAssetPort | null, pipelineState?: ExtractPipelineSurface | null, gpuStore?: import('./gpu-resource-store').GpuResourceStore, materialSnapshotCachesByWorld?: MaterialSnapshotCachesByWorld, options?: {
+    readonly cull?: 'normal' | 'none';
+    readonly paramSchemaProjectionCensus?: ParamSchemaProjectionCensus;
+}): ExtractedFrame;
+export declare function extractFrame(world: World, context: PreparedExtractContext): ExtractedFrame;
+/**
+ * Extract the complete render-domain facts for one known entity.
+ *
+ * This deliberately reuses extractFrame's MeshRenderer row body instead of
+ * maintaining a second material/skin/sprite implementation. Query.at() makes
+ * the row source identity-addressed; callers must supply a visibility snapshot
+ * appropriate for the current persistent owner and must keep hierarchy-affecting
+ * changes on the conservative rebuild lane.
+ */
+export interface ExtractedRenderableEntity {
+    readonly snapshot: RenderableSnapshot;
+    readonly candidateDispatch: readonly DispatchEntry[];
+}
+export declare function extractRenderableEntity(world: World, entity: EntityHandle, context: PreparedExtractContext): ExtractedRenderableEntity | undefined;
+/**
+ * Refresh only light, shadow, sky, and post-process resources over an existing
+ * persistent frame. The resource path intentionally skips hierarchy,
+ * renderable, material, cull, dispatch, and candidate-domain extraction.
+ */
+export declare function refreshExtractedFrameLights(world: World, frame: ExtractedFrame): ExtractedFrame;
+export declare function defaultTransformSnapshot(): TransformSnapshot;
+export declare function defaultMaterialSnapshot(materialHandle?: number): MaterialSnapshot;
+//# sourceMappingURL=render-system-extract.d.ts.map