@forgeax/engine-render 0.1.3 → 0.1.6

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

@@ -1,132 +1,14 @@
-import type { EntityHandle, World } from '@forgeax/engine-ecs';
+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, 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 { 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 { RenderSceneFactInput } from './gpu-scene-schema';
 import { type MeshMaterialBindingDiagnostic, type MeshMaterialBindingSource } from './mesh-material-bindings';
+import { type CameraSnapshot } from './render-contract';
 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[];
+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
@@ -235,8 +117,6 @@ export interface PointShadowSnapshot {
  */
 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;
@@ -363,10 +243,6 @@ export interface ExtractedLights {
      * 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
@@ -375,7 +251,7 @@ export interface ExtractedLights {
  * `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
+ * `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.
@@ -392,31 +268,13 @@ export interface SkylightSnapshot {
     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(...)`.
+ * 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.
@@ -431,27 +289,9 @@ export interface SkyboxSnapshot {
 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.
-     */
+    /** 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)
@@ -507,8 +347,6 @@ export interface RenderableSnapshot {
      * 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
@@ -548,30 +386,18 @@ export interface RenderableSnapshot {
      * 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;
+    /**
+     * 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;
 }
-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 MorphSnapshot {
+    readonly weights: Float32Array;
+    readonly targetCount: number;
 }
 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;
@@ -581,40 +407,6 @@ export interface GpuDrivenDrawSnapshot {
     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;
@@ -711,16 +503,12 @@ export interface MaterialSnapshot {
      * 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
@@ -736,10 +524,6 @@ export interface MaterialSnapshot {
     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;
     /**
@@ -747,7 +531,7 @@ export interface MaterialSnapshot {
      * (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
+     * `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.
@@ -766,7 +550,7 @@ export interface MaterialSnapshot {
      * 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`
+     * 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.
      *
@@ -845,7 +629,7 @@ export interface MaterialSnapshotCacheEntry {
     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. */
+    /** 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;
@@ -891,23 +675,16 @@ 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;
+    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
@@ -938,50 +715,21 @@ export interface ExtractedFrame {
     readonly hiddenEntityReports: readonly RenderFeatureHiddenEntityReport[];
 }
 /**
- * Transparent-bucket dispatch entry — extends the dispatch snapshot with
- * per-entity sort inputs precomputed at extract time.
+ * 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).
  *
- * 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).
+ * 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 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;
+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`
@@ -994,6 +742,7 @@ export declare function refreshRenderableMaterialSnapshot(renderable: Renderable
 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
@@ -1011,6 +760,71 @@ export interface ExtractPipelineSurface {
  * @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
@@ -1026,71 +840,26 @@ export interface ExtractFramesOwner {
     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 assets: AssetRegistry | 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 assets?: AssetRegistry | 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?: {
+export declare function extractFrames(worlds: readonly World[], owner: number | ExtractFramesOwner, assets?: AssetRegistry | null, pipelineState?: ExtractPipelineSurface | null, 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;
+export {};
 //# sourceMappingURL=render-system-extract.d.ts.map