@forgeax/engine-render 0.1.34 → 0.1.36

package/src/record/main-pass-geometry.ts

@@ -1,8 +1,9 @@
+import type { RenderResourceScope } from '../publication/resource-scope';
+import { resolveSpriteInstancesBuffer } from './sprite-instance-buffer';
 // @forgeax/engine-runtime - RenderSystem record stage: main-pass geometry draws.
 // feat-20260704 M5/w31: further-split from main-pass.ts (AC-05 <=1500 lines/file).
 // recordGeometryDraws + resolveGeometryInstanceBuffer, moved verbatim.
 
-import type { World } from '@forgeax/engine-ecs';
 import {
   type BindGroup,
   type Buffer,
@@ -495,7 +496,7 @@ export function recordGeometryDraws(
     materialSlot: number,
     submeshMaterial: MaterialSnapshot,
     entityKey: number,
-    materialWorld: World,
+    materialWorld: RenderResourceScope,
     materialShaderId?: string,
   ) => BindGroup,
   passKind: PassKind = 'forward',
@@ -1916,6 +1917,24 @@ export function resolveGeometryInstanceBuffer(
 ): readonly GeometryInstanceDraw[] | null {
   const { runtime, pipelineState, frameState } = c;
   const inst = entry.source.instances;
+  if (entry.source.spriteInstances !== undefined) {
+    const { buffer, count } = resolveSpriteInstancesBuffer(
+      c,
+      entry,
+      pipelineState.identityInstanceBuffer,
+      0,
+    );
+    return count === 0
+      ? []
+      : [
+          {
+            instanceBuffer: buffer,
+            instanceBindGroup: resolveGeometryInstancesBindGroup(c, buffer, undefined),
+            probeOffset: -1,
+            instanceCount: count,
+          },
+        ];
+  }
   const probeBinding =
     !useProbeBlend ||
     !runtime.device.caps.storageBuffer ||

package/src/record/main-pass-material.ts

@@ -1,14 +1,16 @@
 import { transmissionBackdropAvailable } from '../assembly/device-feature-admission';
 import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
+import type { RenderResourceScope } from '../publication/resource-scope';
 import type { _InternalRenderPipelineContext } from './render-context';
 // @forgeax/engine-runtime - RenderSystem record stage: main-pass-material.
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
-import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import type { EntityHandle } from '@forgeax/engine-ecs';
 import {
-  VIDEO_ELEMENT_PROVIDER_KEY,
-  type VideoElementProvider,
+  VIDEO_SOURCE_PROVIDER_KEY,
+  type VideoSourceProvider,
+  videoSourceExtent,
 } from '@forgeax/engine-graphics-extras';
 import {
   type BindGroup,
@@ -261,11 +263,11 @@ function materialDiagnosticsEnabled(): boolean {
 }
 
 export function residentTextureView(
-  world: World,
+  world: RenderResourceScope,
   store: GpuResidencyCache,
   runtime: RenderSystemRuntime,
   handle: Handle<'TextureAsset', 'shared'>,
-  worldId: World | number = world,
+  worldId: RenderResourceScope | number = world,
 ): TextureView | undefined {
   const podRes = resolveAssetHandle<TextureAsset>(world, handle);
   const diagnosticsEnabled = materialDiagnosticsEnabled();
@@ -323,11 +325,11 @@ export function residentTextureView(
 }
 
 function residentSampler(
-  world: World,
+  world: RenderResourceScope,
   store: GpuResidencyCache,
   runtime: RenderSystemRuntime,
   handle: Handle<'SamplerAsset', 'shared'>,
-  worldId: World | number = world,
+  worldId: RenderResourceScope | number = world,
 ): Sampler | undefined {
   const podRes = resolveAssetHandle<SamplerAsset>(world, handle);
   if (!podRes.ok) return undefined;
@@ -344,7 +346,7 @@ function residentSampler(
 // transient DynamicTextureStore, NOT the static `residentTextureView` /
 // `ensureResident` cache (video never enters that switch; AC-08).
 //
-// Per frame: ask the host-registered VideoElementProvider (World Resource,
+// Per frame: ask the host-registered VideoSourceProvider (RenderResourceScope Resource,
 // D-1) for this entity's HTMLVideoElement, upload its current frame via
 // `store.uploadFrame` (copyExternalImageToTexture), and return the resulting
 // view. When the provider is absent / returns no element / the element has no
@@ -404,7 +406,7 @@ function clearVideoUploadFailureEpisode(
 }
 
 export function videoTextureView(
-  world: World,
+  world: RenderResourceScope,
   store: DynamicTextureStore | undefined,
   runtime: RenderSystemRuntime,
   entityKey: number,
@@ -412,10 +414,14 @@ export function videoTextureView(
   highPerfAvailable: boolean,
 ): TextureView | undefined {
   if (store === undefined) return undefined;
-  const provider = world.hasResource(VIDEO_ELEMENT_PROVIDER_KEY)
-    ? world.getResource<VideoElementProvider>(VIDEO_ELEMENT_PROVIDER_KEY)
-    : undefined;
-  const element = provider?.getElement(entityKey as EntityHandle, clip);
+  const provider =
+    !('resolveAsset' in world) && world.hasResource(VIDEO_SOURCE_PROVIDER_KEY)
+      ? world.getResource<VideoSourceProvider>(VIDEO_SOURCE_PROVIDER_KEY)
+      : undefined;
+  const element =
+    'resolveAsset' in world
+      ? world.videoFrame(entityKey, clip)
+      : provider?.getSource(entityKey as EntityHandle, clip);
   // AC-10 double-miss: a VideoPlayer entity can reach NEITHER upload path this
   // frame — no host HTMLVideoElement (general copyExternalImageToTexture path)
   // AND no high-perf GPUExternalTexture path. This is the genuine "this backend
@@ -441,13 +447,9 @@ export function videoTextureView(
     clearVideoUploadFailureEpisode(store, entityKey, clip);
     return store.getView(clip);
   }
-  const width = element.videoWidth;
-  const height = element.videoHeight;
-  // Metadata dimensions can be non-zero before the decoder has produced a
-  // current frame. WebGPU rejects copyExternalImageToTexture in that window
-  // because the video element has no back resource yet; keep the previous
-  // frame/default view until HAVE_CURRENT_DATA (2) is reached.
-  if (width <= 0 || height <= 0 || element.readyState < 2) return store.getView(clip);
+  const extent = videoSourceExtent(element);
+  if (extent === undefined) return store.getView(clip);
+  const { width, height } = extent;
   const uploaded = store.uploadFrame(clip, element, width, height);
   if (uploaded === undefined) return store.getView(clip);
   if (!uploaded.ok) {
@@ -592,7 +594,7 @@ function writeNumericParamValue(
 export function applyMaterialTextureUvScales(
   payload: MaterialUboPayload,
   material: MaterialSnapshot,
-  world: World,
+  world: RenderResourceScope,
 ): void {
   const f32 = materialUboFloatView(payload);
   const coordinateSchema = materialCoordinateSchema(material);
@@ -940,14 +942,14 @@ export function applyParamSchemaDefaultsToUbo(
 export interface PerSubmeshMaterialBgDeps {
   readonly runtime: RenderSystemRuntime;
   readonly pipelineState: PipelineState;
-  readonly world: World;
+  readonly world: RenderResourceScope;
   readonly store: GpuResidencyCache;
   readonly materialSlice: number;
   readonly videoHighPerfAvailable: boolean;
   readonly skylightResources: SkylightBindGroupResources;
   readonly resolveRenderTargetTextureSource?: RenderSystemRuntime['resolveRenderTargetTextureSource'];
   readonly resolveReflectionProbeResources?: (
-    materialWorld: World,
+    materialWorld: RenderResourceScope,
     entityKey: number,
   ) => { readonly resources: SkylightBindGroupResources; readonly probeIndex: number } | undefined;
   readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
@@ -979,7 +981,7 @@ function recordIblMaterialBinding(
   if (receipt === undefined) return;
   const skylightBindingStart = entries.findIndex((entry) => entry.binding === iblStart);
   if (skylightBindingStart < 0) return;
-  const iblEntries = entries.slice(skylightBindingStart, skylightBindingStart + 7);
+  const iblEntries = entries.slice(skylightBindingStart, skylightBindingStart + 6);
   const projected: IblBindingEntryInspection[] = [];
   for (const entry of iblEntries) {
     if (entry.resource.kind === 'externalTexture') continue;
@@ -1018,7 +1020,15 @@ export function isMaterialBgAssemblyCacheHit(
   sceneMaterialBuffer?: Buffer,
   surfaceRawDepthView?: TextureView | null,
 ): cached is MaterialBgAssemblyCacheEntry {
-  if (transmissionBackdropView != null || surfaceRawDepthView != null) return false;
+  // Logical target sources keep their identity when a resize promotes a new
+  // physical view. Resolve those views each frame; the lower binding cache is
+  // keyed by the actual GPU resources and still reuses unchanged bindings.
+  if (
+    transmissionBackdropView != null ||
+    surfaceRawDepthView != null ||
+    (material.textureSources?.size ?? 0) > 0
+  )
+    return false;
   return (
     cached?.material === material &&
     cached.materialResourceEpoch === materialResourceEpoch &&
@@ -1031,7 +1041,6 @@ export function isMaterialBgAssemblyCacheHit(
     cached.skylightResources.skylightPrefilterView === skylightResources.skylightPrefilterView &&
     cached.skylightResources.prefilterSampler === skylightResources.prefilterSampler &&
     cached.skylightResources.brdfLutView === skylightResources.brdfLutView &&
-    cached.skylightResources.brdfLutSampler === skylightResources.brdfLutSampler &&
     cached.skylightResources.intensityBuffer === skylightResources.intensityBuffer
   );
 }
@@ -1040,7 +1049,7 @@ export function buildPerSubmeshMaterialBg(
   deps: PerSubmeshMaterialBgDeps,
   submeshMaterial: MaterialSnapshot,
   entityKey: number,
-  materialWorld: World = deps.world,
+  materialWorld: RenderResourceScope = deps.world,
   materialShaderId: string | undefined = submeshMaterial.materialShaderId,
 ): BindGroup {
   const {
@@ -1175,10 +1184,6 @@ export function buildPerSubmeshMaterialBg(
             },
             {
               binding: 6 + smUserRegionFields.length * 2,
-              resource: { kind: 'sampler', value: effectiveSkylightResources.brdfLutSampler },
-            },
-            {
-              binding: 7 + smUserRegionFields.length * 2,
               resource: {
                 kind: 'buffer',
                 value: { buffer: effectiveSkylightResources.intensityBuffer },
@@ -1429,6 +1434,7 @@ export function buildPerSubmeshMaterialBg(
   if (
     smMaterialHandle !== undefined &&
     !smHasVideoFields &&
+    (submeshMaterial.textureSources?.size ?? 0) === 0 &&
     materialResourcesResident &&
     !hasActiveTransmissionBackdrop
   ) {
@@ -1532,7 +1538,6 @@ export function resolveMaterialSkylight(
           prefilterView: activeViews.pref,
           prefilterSampler: skylightFallback.sampler,
           brdfLutView: activeViews.brdf,
-          brdfLutSampler: skylightFallback.sampler,
           intensityBuffer: skylightFallback.intensityBuffer,
         }
       : {
@@ -1541,7 +1546,6 @@ export function resolveMaterialSkylight(
           prefilterView: skylightFallback.prefilterView,
           prefilterSampler: skylightFallback.sampler,
           brdfLutView: skylightFallback.brdfLutView,
-          brdfLutSampler: skylightFallback.sampler,
           intensityBuffer: skylightFallback.intensityBuffer,
         };
   return { skylightResources, activeViews };

package/src/record/main-pass-sprite-draws.ts

@@ -1,8 +1,9 @@
+import type { RenderResourceScope } from '../publication/resource-scope';
+import { resolveSpriteInstancesBuffer } from './sprite-instance-buffer';
 // @forgeax/engine-runtime - RenderSystem record stage: main-pass sprite draws.
 // feat-20260704 M5/w31: further-split from main-pass.ts (AC-05 <=1500 lines/file).
 // recordSpritePass + sprite entity/transparent/instance-buffer helpers, moved verbatim.
 
-import type { World } from '@forgeax/engine-ecs';
 import {
   type BindGroup,
   type Buffer,
@@ -21,11 +22,7 @@ import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import { SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET } from '../pbr-pipeline';
 import { buildBeginRenderPassDescriptor, standardTopologyVariantSet } from '../pipeline-spec';
-import type {
-  DispatchEntry,
-  MaterialSnapshot,
-  SpriteInstancesSnapshot,
-} from '../render-system-extract';
+import type { DispatchEntry, MaterialSnapshot } from '../render-system-extract';
 import { resolveFoldInstanceBuffer } from './fold-instance-buffer';
 import { worldEntityKey } from './frame-snapshot';
 import { recordGeometryDraws, resolveGeometryInstancesBindGroup } from './main-pass-geometry';
@@ -37,55 +34,6 @@ import {
 import type { _InternalRenderPipelineContext } from './render-context';
 import { MATERIAL_PER_ENTITY_STRIDE } from './render-context';
 
-export type { SpriteInstancesSnapshot };
-
-/**
- * Build the interleaved sprite instance payload consumed by this record owner.
- * The extract stage validates the two packed arrays before they reach this
- * function, so the record path has one source of count-mismatch errors.
- */
-export function interleaveSpriteInstanceBuffer(
-  transforms: Float32Array,
-  regions: Float32Array,
-  includePrevious = false,
-): Float32Array {
-  const count = transforms.length / 16;
-  const stride = includePrevious ? 36 : 20;
-  const regionOffset = includePrevious ? 32 : 16;
-  const out = new Float32Array(count * stride);
-  for (let i = 0; i < count; i++) {
-    const dstBase = i * stride;
-    const transformBase = i * 16;
-    const regionBase = i * 4;
-    for (let k = 0; k < 16; k++) out[dstBase + k] = transforms[transformBase + k] ?? 0;
-    if (includePrevious) {
-      for (let k = 0; k < 16; k++) {
-        out[dstBase + 16 + k] = transforms[transformBase + k] ?? 0;
-      }
-    }
-    for (let k = 0; k < 4; k++) {
-      out[dstBase + regionOffset + k] = regions[regionBase + k] ?? 0;
-    }
-  }
-  return out;
-}
-
-/**
- * Check whether the existing per-entity sprite buffer still matches the
- * extract snapshot and interleaved byte count.
- */
-export function spriteInstancesCacheHit(
-  entry: InstanceBufferCacheEntry | undefined,
-  snapshot: SpriteInstancesSnapshot,
-  requestedBytes: number,
-): boolean {
-  return (
-    entry !== undefined &&
-    entry.uploadedArchVersion === snapshot.archVersion &&
-    entry.uploadedByteLength === requestedBytes
-  );
-}
-
 /**
  * Decide whether the LDR record needs the transparent sprite sub-pass. This
  * remains beside the sprite record owner so the frame stage and draw stage
@@ -144,7 +92,7 @@ export function recordSpritePass(
     materialSlot: number,
     submeshMaterial: MaterialSnapshot,
     entityKey: number,
-    materialWorld: World,
+    materialWorld: RenderResourceScope,
     materialShaderId?: string,
   ) => BindGroup,
   graphPass?: RhiRenderPassEncoder,
@@ -382,7 +330,7 @@ function recordSpriteTransparentPbrDraws(
     slot: number,
     material: MaterialSnapshot,
     entityKey: number,
-    world: World,
+    world: RenderResourceScope,
     shader?: string,
   ) => BindGroup,
   meshGroup2: BindGroup | null,
@@ -455,7 +403,7 @@ function recordSpriteEntityDraws(
     materialSlot: number,
     material: MaterialSnapshot,
     entityKey: number,
-    materialWorld: World,
+    materialWorld: RenderResourceScope,
   ) => BindGroup,
   spritePH: RenderPipeline | null,
   spritePH_withRegion: RenderPipeline | null,
@@ -760,100 +708,6 @@ function recordSpriteEntityDraws(
   }
 }
 
-/**
- * feat-20260704 M3/w19: resolve the interleaved SpriteInstances (@group(3))
- * buffer + instanceCount for a sprite entity in the LDR blend sub-pass,
- * extracted verbatim from recordSpriteEntityDraws. Uploads the interleaved
- * mat4 + per-instance UV region transforms (cache-keyed on the snapshot); on
- * over-cap fires the structured limit-exceeded error and leaves the passed-in
- * fallback buffer/count. Returns the resolved (or unchanged) buffer + count.
- *
- * @internal
- */
-function resolveSpriteInstancesBuffer(
-  c: _InternalRenderPipelineContext,
-  spriteEntry: _InternalRenderPipelineContext['validatedOrdered'][number],
-  fallbackBuffer: Buffer,
-  fallbackCount: number,
-): { buffer: Buffer; count: number } {
-  const { runtime, frameState } = c;
-  let buffer = fallbackBuffer;
-  let count = fallbackCount;
-  const spriteInstancesSnap: SpriteInstancesSnapshot | undefined =
-    spriteEntry.source.spriteInstances;
-  if (spriteInstancesSnap !== undefined) {
-    const uniformFallback = runtime.device.caps.storageBuffer === false;
-    const interleaved = interleaveSpriteInstanceBuffer(
-      spriteInstancesSnap.transforms,
-      spriteInstancesSnap.regions,
-      !uniformFallback,
-    );
-    const requestedBytes = interleaved.byteLength;
-    const cap = runtime.device.limits.maxStorageBufferBindingSize;
-    if (typeof cap === 'number' && requestedBytes > cap) {
-      runtime.errorRegistry.fire(
-        new RhiError({
-          code: 'limit-exceeded',
-          expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-          hint: 'reduce SpriteInstances instance count to fit within device.limits.maxStorageBufferBindingSize (144 bytes per instance: current mat4 64B + previous mat4 64B + region 16B)',
-          detail: {
-            maxStorageBufferBindingSize: cap,
-            requestedBytes,
-          },
-        }),
-      );
-    } else {
-      const cachedSpriteInst = frameState.instanceBuffers.get(
-        worldEntityKey(spriteEntry.source.worldId, spriteInstancesSnap.cacheKey),
-      );
-      let activeSpriteInst: InstanceBufferCacheEntry | null = null;
-      if (spriteInstancesCacheHit(cachedSpriteInst, spriteInstancesSnap, requestedBytes)) {
-        activeSpriteInst = cachedSpriteInst ?? null;
-      } else if (requestedBytes > 0) {
-        const bufRes = runtime.device.createBuffer({
-          size: requestedBytes,
-          usage:
-            (uniformFallback ? GPU_BUFFER_USAGE_UNIFORM : GPU_BUFFER_USAGE_STORAGE) |
-            GPU_BUFFER_USAGE_COPY_DST,
-          mappedAtCreation: false,
-        });
-        if (!bufRes.ok) {
-          runtime.errorRegistry.fire(bufRes.error);
-        } else {
-          if (cachedSpriteInst !== undefined && !cachedSpriteInst.buffer.isDestroyed) {
-            const r = cachedSpriteInst.buffer.destroy();
-            if (!r.ok) runtime.errorRegistry.fire(r.error);
-          }
-          const newBuf = new GpuBuffer(runtime.device, bufRes.value);
-          activeSpriteInst = {
-            buffer: newBuf,
-            uploadedArchVersion: spriteInstancesSnap.archVersion,
-            uploadedByteLength: requestedBytes,
-          };
-          frameState.instanceBuffers.set(
-            worldEntityKey(spriteEntry.source.worldId, spriteInstancesSnap.cacheKey),
-            activeSpriteInst,
-          );
-        }
-      }
-      if (activeSpriteInst !== null && requestedBytes > 0) {
-        const writeRes = runtime.device.queue.writeBuffer(
-          activeSpriteInst.buffer.handle,
-          0,
-          interleaved,
-        );
-        if (!writeRes.ok) {
-          runtime.errorRegistry.fire(writeRes.error);
-        } else {
-          buffer = activeSpriteInst.buffer.handle;
-          count = spriteInstancesSnap.instanceCount;
-        }
-      }
-    }
-  }
-  return { buffer, count };
-}
-
 function transparentPassColorFormat(
   c: _InternalRenderPipelineContext,
   pipelineState: _InternalRenderPipelineContext['pipelineState'] = c.pipelineState,

package/src/record/main-pass.ts

@@ -1,4 +1,3 @@
-import type { World } from '@forgeax/engine-ecs';
 import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
 import type { GraphResourceResolver } from '@forgeax/engine-render-graph';
 import {
@@ -19,6 +18,7 @@ import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
 import { buildBeginRenderPassDescriptor, standardTopologyBindGroupReady } from '../pipeline-spec';
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
+import type { RenderResourceScope } from '../publication/resource-scope';
 import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { RenderRecordPhase } from '../render-contract';
 import type {
@@ -529,7 +529,7 @@ export function recordMainPass(
           identities: [
             getOpaqueResourceIdentity(skylightResources.irradianceSampler as object),
             getOpaqueResourceIdentity(skylightResources.prefilterSampler as object),
-            getOpaqueResourceIdentity(skylightResources.brdfLutSampler as object),
+            getOpaqueResourceIdentity(skylightResources.irradianceSampler as object),
           ],
         },
         resources: {
@@ -549,7 +549,9 @@ export function recordMainPass(
           },
           brdfLut: {
             viewIdentity: getOpaqueResourceIdentity(skylightResources.brdfLutView as object),
-            samplerIdentity: getOpaqueResourceIdentity(skylightResources.brdfLutSampler as object),
+            samplerIdentity: getOpaqueResourceIdentity(
+              skylightResources.irradianceSampler as object,
+            ),
             deviceGeneration: runtime.deviceScope.generation,
           },
           intensityBufferIdentity: getOpaqueResourceIdentity(
@@ -590,7 +592,7 @@ export function recordMainPass(
     // which cannot render a PBR decal). Captures only frame-stable closure
     // state; the caller passes the per-submesh material snapshot + entityKey
     // (for video texture routing) and sets the dynamic UBO offset itself.
-    // Selection keys use the extracted frame index, never World.identity.
+    // Selection keys use the extracted frame index, never RenderResourceScope.identity.
     const hasProbeBindings = (c.reflectionProbes?.table.rows.length ?? 0) > 0;
     const worldIndices = hasProbeBindings
       ? new Map(
@@ -632,7 +634,6 @@ export function recordMainPass(
           skylightPrefilterView: skylightResources.prefilterView,
           prefilterSampler: row.sampler,
           brdfLutView: skylightResources.brdfLutView,
-          brdfLutSampler: skylightResources.brdfLutSampler,
           intensityBuffer: row.uniformBuffer,
         };
         return { resources: probeResources, probeIndex: row.index };
@@ -657,7 +658,7 @@ export function recordMainPass(
     const buildPerSubmeshMaterialBg = (
       submeshMaterial: MaterialSnapshot,
       entityKey: number,
-      materialWorld: World = world,
+      materialWorld: RenderResourceScope = world,
       materialShaderId: string | undefined = submeshMaterial.materialShaderId,
     ): BindGroup =>
       buildPerSubmeshMaterialBgImpl(
@@ -748,7 +749,7 @@ export function recordMainPass(
       materialSlot: number,
       material: MaterialSnapshot,
       entityKey: number,
-      materialWorld: World = world,
+      materialWorld: RenderResourceScope = world,
       materialShaderId: string | undefined = material.materialShaderId,
     ): BindGroup =>
       !hasProbeBindings &&

package/src/record/prepared-material-bindings.ts

@@ -1,5 +1,4 @@
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
-import type { World } from '@forgeax/engine-ecs';
 import type { BindGroupEntry, BindGroupLayout, Buffer } from '@forgeax/engine-rhi';
 import { err, ok } from '@forgeax/engine-rhi';
 import {
@@ -14,6 +13,8 @@ import { transmissionBackdropAvailable } from '../assembly/device-feature-admiss
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
 import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
+import type { RenderResourceScope } from '../publication/resource-scope';
+import { internSharedRefFromGuid } from '../render-system-extract';
 import {
   applyParamSchemaDefaultsToUbo,
   applyParamSnapshotToUbo,
@@ -28,7 +29,6 @@ export type PreparedResolverCaches = {
   readonly preparedGroup0Pipelines: WeakSet<object>;
   readonly preparedViewOnlyPipelines: WeakSet<object>;
   readonly preparedRenderMaterialPipelines: WeakSet<object>;
-  readonly preparedAssetHandles: WeakMap<World, Map<string, number>>;
 };
 
 export function createPreparedResolverCaches(): PreparedResolverCaches {
@@ -38,36 +38,23 @@ export function createPreparedResolverCaches(): PreparedResolverCaches {
     preparedGroup0Pipelines: new WeakSet(),
     preparedViewOnlyPipelines: new WeakSet(),
     preparedRenderMaterialPipelines: new WeakSet(),
-    preparedAssetHandles: new WeakMap(),
   };
 }
 
 function preparedHandle<Brand extends string>(
   runtime: RenderSystemInternals,
-  caches: PreparedResolverCaches,
-  world: World,
+  world: RenderResourceScope,
   guid: string,
   brand: Brand,
 ): Handle<Brand, 'shared'> | undefined {
-  let handles = caches.preparedAssetHandles.get(world);
-  if (handles === undefined) {
-    handles = new Map();
-    caches.preparedAssetHandles.set(world, handles);
-  }
-  const key = `${brand}:${guid.toLowerCase()}`;
-  const cached = handles.get(key);
-  if (cached !== undefined) return cached as Handle<Brand, 'shared'>;
-  const asset = runtime.assets.lookup(guid);
-  if (asset === undefined) return undefined;
-  const handle = world.allocSharedRef(brand, asset);
-  handles.set(key, handle as number);
-  return handle;
+  if ('resolveAsset' in world)
+    return world.handleForGuid(guid) as Handle<Brand, 'shared'> | undefined;
+  return internSharedRefFromGuid(world, runtime.assets, guid, brand);
 }
 
 export function preparedMaterialBindings(
   runtime: RenderSystemInternals,
-  caches: PreparedResolverCaches,
-  worlds: readonly World[],
+  worlds: readonly RenderResourceScope[],
   materialShaderId: string,
   worldIndex: number,
   materialGuid: string,
@@ -75,11 +62,16 @@ export function preparedMaterialBindings(
   skylightResources?: SkylightBindGroupResources,
 ) {
   const world = worlds[worldIndex];
-  const material = runtime.assets.lookup(materialGuid) as MaterialAsset | undefined;
+  const handle =
+    world === undefined ? undefined : preparedHandle(runtime, world, materialGuid, 'MaterialAsset');
   const pipelineState = runtime.getPipelineState();
-  if (world === undefined || material?.kind !== 'material' || pipelineState === null) {
+  if (world === undefined || handle === undefined || pipelineState === null) {
     return err(new Error('prepared material asset is unavailable'));
   }
+  const resolved = resolveAssetHandle<MaterialAsset>(world, handle);
+  if (!resolved.ok) return resolved;
+  const material = resolved.value;
+  if (material.kind !== 'material') return err(new Error('prepared material asset is unavailable'));
   const schema = runtime.getParamSchema?.(materialShaderId) ?? [];
   // Feature materials share the ordinary linear parameter domain and semantic texture defaults.
   const values = materialValuesToLinearRuntime(
@@ -126,13 +118,7 @@ export function preparedMaterialBindings(
         : undefined;
     let sampler = pipelineState.defaultSampler;
     if (textureValue?.sampler !== undefined) {
-      const handle = preparedHandle(
-        runtime,
-        caches,
-        world,
-        String(textureValue.sampler),
-        'SamplerAsset',
-      );
+      const handle = preparedHandle(runtime, world, String(textureValue.sampler), 'SamplerAsset');
       if (handle !== undefined) {
         const asset = resolveAssetHandle<SamplerAsset>(world, handle);
         if (asset.ok) {
@@ -143,13 +129,7 @@ export function preparedMaterialBindings(
     }
     let view = defaultViewForUserRegionField(field, pipelineState, schema);
     if (textureValue !== undefined) {
-      const handle = preparedHandle(
-        runtime,
-        caches,
-        world,
-        String(textureValue.texture),
-        'TextureAsset',
-      );
+      const handle = preparedHandle(runtime, world, String(textureValue.texture), 'TextureAsset');
       if (handle !== undefined) {
         view = residentTextureView(world, runtime.gpuStore, runtime, handle) ?? view;
       }
@@ -203,7 +183,6 @@ export function preparedMaterialBindings(
       prefilterView: fallback.prefilterView,
       prefilterSampler: fallback.sampler,
       brdfLutView: fallback.brdfLutView,
-      brdfLutSampler: fallback.sampler,
       intensityBuffer: fallback.intensityBuffer,
     },
     transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage)

package/src/record/render-context.ts

@@ -1,5 +1,4 @@
 import type { AssetRegistry, DynamicTextureStore } from '@forgeax/engine-assets-runtime';
-import type { World } from '@forgeax/engine-ecs';
 import type { VertexLayoutProjection } from '@forgeax/engine-geometry';
 import type { Profiler } from '@forgeax/engine-profiler';
 import type { CompiledRenderGraphInfo } from '@forgeax/engine-render-graph';
@@ -58,6 +57,7 @@ import type { StandardProfile } from '../pipeline/standard-profile';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
 import type { PointsLinesInspection } from '../points-lines/inspection';
 import type { PointsLinesRecordPlan } from '../points-lines/record';
+import type { RenderResourceScope } from '../publication/resource-scope';
 import type { ReflectionProbeTable } from '../reflection/gpu-table';
 import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { FrameObservationDomain } from '../render-contract';
@@ -582,7 +582,7 @@ export interface _StandardForwardSceneView {
   readonly skybox: SkyboxSnapshot | undefined;
   readonly profilePhase?: <T>(phase: RenderRecordPhase, action: () => T) => T;
   readonly directionalShadowCacheReuse: boolean;
-  readonly world: World;
+  readonly world: RenderResourceScope;
   readonly tonemapActive: boolean;
   readonly geometryColorView: TextureView | null;
   readonly geometryDepthView: TextureView | null;
@@ -620,6 +620,8 @@ export interface _StandardForwardSceneView {
   readonly gpuDrivenShadowDrawKeys?: ReadonlySet<string>;
   /** View-scoped ShadowCaster claims for exact CPU residual routing. */
   readonly gpuDrivenShadowDrawKeysByView?: ReadonlyMap<string, ReadonlySet<string>>;
+  /** Per-shadow-view frusta shared by GPU compaction and CPU residual routing. */
+  readonly shadowViewPlanesByView?: ReadonlyMap<string, Float32Array>;
   /** Extracted structured ShadowCaster ownership facts. */
   readonly shadowCasterMembership?: readonly ShadowCasterMembership[];
   /** Complete retained ShadowCaster rows, including camera-culled casters. */