@forgeax/engine-render 0.1.34 → 0.1.36

package/src/record/__tests__/prepared-runtime-material.integration.test.ts

@@ -0,0 +1,134 @@
+import { AssetRegistry, RuntimeMaterialValue } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import type { BindGroupLayout } from '@forgeax/engine-rhi';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import { type MaterialAsset, ok } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { renderPublicationTransfers } from '../../publication/contract';
+import { createRenderPublisher } from '../../publication/publisher';
+import { RenderPublicationReceiver } from '../../publication/receiver';
+import { preparedMaterialBindings } from '../prepared-material-bindings';
+import type { RenderSystemInternals } from '../render-context';
+
+it('uploads accepted values on World and published-reader paths without mutating the base', () => {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  const guid = '12345678-1234-1234-1234-123456789abc';
+  const base: MaterialAsset = { kind: 'material', values: { roughness: 0.8 } };
+  assets.catalog(guid, base);
+  const handle = world.internSharedRef('MaterialAsset', base);
+  const content = world
+    .spawn({
+      component: RuntimeMaterialValue,
+      data: { asset: handle, parameter: 'roughness', kind: 0, value: [0.25] },
+    })
+    .unwrap();
+  const uploads: number[] = [];
+  let destroys = 0;
+  const runtime = {
+    assets,
+    getParamSchema: () => [{ name: 'roughness', type: 'f32' }],
+    getPipelineState: () => ({
+      defaultSampler: {},
+      skylightFallback: {
+        irradianceView: {},
+        prefilterView: {},
+        brdfLutView: {},
+        sampler: {},
+        intensityBuffer: {},
+      },
+    }),
+    device: {
+      caps: { storageBuffer: false },
+      limits: { maxSampledTexturesPerShaderStage: 16 },
+      createBuffer: () => ok({}),
+      destroyBuffer: () => {
+        destroys++;
+        return ok(undefined);
+      },
+      createBindGroup: () => ok({}),
+      queue: {
+        writeBuffer: (_buffer: unknown, _offset: number, bytes: Uint8Array) => {
+          uploads.push(new Float32Array(bytes.buffer, bytes.byteOffset, 1)[0] ?? NaN);
+          return ok(undefined);
+        },
+      },
+    },
+  } as unknown as RenderSystemInternals;
+  const identity = { source: 'material-values', epoch: 1 };
+  const publisher = createRenderPublisher(world, assets, identity, undefined, [
+    {
+      identity: 'material-consumer',
+      extract: () => ok({}),
+      assetDependencies: () => [guid],
+      plan: () => ok({ resources: [], passes: [] }),
+    },
+  ]);
+  const receiver = new RenderPublicationReceiver(identity);
+  const publish = () => {
+    const candidate = publisher.prepare(0).unwrap();
+    const packet = structuredClone(candidate.packet);
+    candidate.accept();
+    const resources = receiver.accept(packet).unwrap().resources;
+    publisher.recycle(packet.revision, renderPublicationTransfers(packet)).unwrap();
+    return resources;
+  };
+  const reader = publish();
+  for (const source of [world, reader]) {
+    const bindings = preparedMaterialBindings(
+      runtime,
+      [source],
+      'shader',
+      0,
+      guid,
+      {} as BindGroupLayout,
+    ).unwrap();
+    if ('release' in bindings) bindings.release?.();
+  }
+  expect(uploads).toEqual([0.25, 0.25]);
+  expect(base.values?.roughness).toBe(0.8);
+  const other = new World();
+  const otherHandle = other.internSharedRef('MaterialAsset', base);
+  const otherContent = other
+    .spawn({
+      component: RuntimeMaterialValue,
+      data: {
+        asset: otherHandle,
+        parameter: 'roughness',
+        kind: 0,
+        value: [0.6],
+      },
+    })
+    .unwrap();
+  for (const [owner, expected] of [
+    [1, 0.6],
+    [0, 0.25],
+  ] as const) {
+    const bindings = preparedMaterialBindings(
+      runtime,
+      [world, other],
+      'shader',
+      owner,
+      guid,
+      {} as BindGroupLayout,
+    ).unwrap();
+    expect(uploads.at(-1)).toBeCloseTo(expected);
+    if ('release' in bindings) bindings.release?.();
+  }
+  other.despawn(otherContent).unwrap();
+  world.despawn(content).unwrap();
+  for (const source of [world, publish()]) {
+    const restored = preparedMaterialBindings(
+      runtime,
+      [source],
+      'shader',
+      0,
+      guid,
+      {} as BindGroupLayout,
+    ).unwrap();
+    expect(uploads.at(-1)).toBeCloseTo(0.8);
+    if ('release' in restored) restored.release?.();
+  }
+  expect(destroys).toBe(6);
+  publisher.dispose();
+});

package/src/record/__tests__/sprite-material-abi.unit.test.ts

@@ -72,22 +72,21 @@ describe('sprite Standard material ABI', () => {
       prefilterView: {} as TextureView,
       prefilterSampler: sampler,
       brdfLutView: {} as TextureView,
-      brdfLutSampler: sampler,
       intensityBuffer: {} as Buffer,
     });
     expect(merged[15]).toMatchObject({
       binding: 15,
       resource: { kind: 'textureView' },
     });
-    expect(merged[22]).toMatchObject({
-      binding: 22,
+    expect(merged[21]).toMatchObject({
+      binding: 21,
       resource: { kind: 'sampler', value: sampler },
     });
-    expect(merged[23]).toMatchObject({
-      binding: 23,
+    expect(merged[22]).toMatchObject({
+      binding: 22,
       resource: { kind: 'textureView' },
     });
-    expect(merged).toHaveLength(25);
+    expect(merged).toHaveLength(24);
     expect(merged.find((entry) => entry.binding === 47)?.resource.kind).toBe('textureView');
 
     const complete = [
@@ -97,7 +96,7 @@ describe('sprite Standard material ABI', () => {
         resource: { kind: 'buffer' as const, value: { buffer: {} as Buffer } },
       },
     ];
-    expect(complete).toHaveLength(26);
+    expect(complete).toHaveLength(25);
     expect(complete.find((entry) => entry.binding === 46)).toMatchObject({
       binding: 46,
       resource: { kind: 'buffer' },
@@ -112,13 +111,12 @@ describe('sprite Standard material ABI', () => {
         prefilterView: {} as TextureView,
         prefilterSampler: sampler,
         brdfLutView: {} as TextureView,
-        brdfLutSampler: sampler,
         intensityBuffer: {} as Buffer,
       },
       { sampler, backdropView: backdrop },
     );
-    expect(active[23]).toMatchObject({
-      binding: 23,
+    expect(active[22]).toMatchObject({
+      binding: 22,
       resource: { kind: 'textureView', value: backdrop },
     });
   });

package/src/record/__tests__/video-texture-view.unit.test.ts

@@ -1,8 +1,8 @@
 import { type DynamicTextureDevice, DynamicTextureStore } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
 import {
-  VIDEO_ELEMENT_PROVIDER_KEY,
-  type VideoElementProvider,
+  VIDEO_SOURCE_PROVIDER_KEY,
+  type VideoSourceProvider,
 } from '@forgeax/engine-graphics-extras';
 import type { Result, RhiError, Texture, TextureView } from '@forgeax/engine-rhi';
 import { ok } from '@forgeax/engine-rhi';
@@ -53,16 +53,16 @@ describe('videoTextureView provider-loss recovery', () => {
     const store = makeStore(probe);
     const errors: { readonly code: string }[] = [];
     const runtime = runtimeWithErrors((error) => errors.push(error));
-    const provider: VideoElementProvider = {
-      getElement: vi.fn(() => VIDEO),
+    const provider: VideoSourceProvider = {
+      getSource: vi.fn(() => VIDEO),
     };
-    world.insertResource(VIDEO_ELEMENT_PROVIDER_KEY, provider);
+    world.insertResource(VIDEO_SOURCE_PROVIDER_KEY, provider);
 
     const lkg = videoTextureView(world, store, runtime, ENTITY, CLIP, false);
     expect(lkg).toBeDefined();
     expect(probe.copies).toBe(1);
 
-    world.removeResource(VIDEO_ELEMENT_PROVIDER_KEY);
+    world.removeResource(VIDEO_SOURCE_PROVIDER_KEY);
     expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
     expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
     expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
@@ -70,19 +70,19 @@ describe('videoTextureView provider-loss recovery', () => {
     expect(errors[0]?.code).toBe('video-upload-unsupported');
     expect(probe.copies).toBe(1);
 
-    world.insertResource(VIDEO_ELEMENT_PROVIDER_KEY, provider);
+    world.insertResource(VIDEO_SOURCE_PROVIDER_KEY, provider);
     expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
     expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
     expect(errors).toHaveLength(1);
     expect(probe.copies).toBe(3);
 
-    world.removeResource(VIDEO_ELEMENT_PROVIDER_KEY);
+    world.removeResource(VIDEO_SOURCE_PROVIDER_KEY);
     expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
     expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
     expect(errors).toHaveLength(2);
     expect(probe.copies).toBe(3);
 
-    world.insertResource(VIDEO_ELEMENT_PROVIDER_KEY, provider);
+    world.insertResource(VIDEO_SOURCE_PROVIDER_KEY, provider);
     expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
     expect(errors).toHaveLength(2);
     expect(probe.copies).toBe(4);

package/src/record/fold-buckets.ts

@@ -1,5 +1,4 @@
 import { HANDLE_NINESLICE_QUAD, resolveAssetHandle } from '@forgeax/engine-assets-runtime';
-import type { World } from '@forgeax/engine-ecs';
 import { deriveVertexCount } from '@forgeax/engine-geometry';
 import { RhiError } from '@forgeax/engine-rhi';
 import type { MaterialRenderState, MeshAsset } from '@forgeax/engine-types';
@@ -9,6 +8,8 @@ import { materialBindingKey } from '../gpu-driven/material-bindings';
 import { GpuBuffer } from '../gpu-resource';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_VERTEX } from '../gpu-usage';
 import { disposeTransientInstanceBuffers } from '../instance-buffer-cache';
+import type { RenderResourceScope } from '../publication/resource-scope';
+import { renderAssetByGuid } from '../publication/resource-scope';
 import type { DispatchEntry, MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 import {
   getTransparentSortConfig,
@@ -151,14 +152,14 @@ function limitRowsToMeshSsboCapacity<T>(rows: readonly T[], availableSlots: numb
  */
 export function validateRenderables(
   internals: RenderSystemInternals,
-  world: World,
+  world: RenderResourceScope,
   // feat-20260709-editor-world-partition ENGINE-fix-round2 (defect 2): the full
   // worlds[] list. Each renderable's mesh handle is a user-tier slot in its OWN
   // world's sharedRefs; resolving against a foreign world either misses
   // (asset-not-registered) or resolves the wrong slot payload. `world` (the
   // resource-owner) is retained as the fallback for renderables whose worldId
   // is out of range (defensive; extractFrames always stamps a valid index).
-  worlds: readonly World[],
+  worlds: readonly RenderResourceScope[],
   pipelineState: PipelineState,
   frameState: RenderFrameState,
   renderables: readonly RenderableSnapshot[],
@@ -226,7 +227,9 @@ export function validateRenderables(
     // frames hit the O(1) cache.
     const meshAssetHandle = toShared<'MeshAsset'>(r.assetHandle);
     let meshHandles = internals.gpuStore.getMeshGpuHandles(meshAssetHandle, renderableWorld);
-    const lodMeshes = r.lods?.map((lod) => internals.assets.lookup<MeshAsset>(lod.mesh));
+    const lodMeshes = r.lods?.map((lod) =>
+      renderAssetByGuid<MeshAsset>(renderableWorld, internals.assets, lod.mesh),
+    );
     const resolvedLodMeshes =
       lodMeshes?.every((lod): lod is MeshAsset => lod?.kind === 'mesh') === true
         ? lodMeshes
@@ -793,7 +796,7 @@ export function cleanPerFrameCaches(
  * @internal
  */
 export function computeFoldBuckets(
-  world: World,
+  world: RenderResourceScope,
   frameState: RenderFrameState,
   transparentDispatch: readonly DispatchEntry[],
   renderables: readonly RenderableSnapshot[],

package/src/record/frame-snapshot.ts

@@ -1,7 +1,7 @@
+import type { RenderResourceScope } from '../publication/resource-scope';
 // @forgeax/engine-runtime - RenderSystem record stage: frame-snapshot.
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
-import type { World } from '@forgeax/engine-ecs';
 import type { RenderReadVersion } from '@forgeax/engine-ecs/projection';
 import { vec3 } from '@forgeax/engine-math';
 import type {
@@ -867,8 +867,8 @@ export interface BloomFrameReceipts {
  */
 export interface ValidatedRenderable {
   readonly source: RenderableSnapshot;
-  /** World that owns the renderable's asset handles and material snapshots. */
-  readonly world?: World;
+  /** RenderResourceScope that owns the renderable's asset handles and material snapshots. */
+  readonly world?: RenderResourceScope;
   readonly mesh: MeshGpuHandles;
   readonly renderableIndex: number;
   readonly renderState: MaterialRenderState | undefined;
@@ -900,7 +900,7 @@ export interface ValidatedRenderable {
  * @internal
  */
 export interface DirectionalShadowCache {
-  readonly worlds: readonly World[];
+  readonly worlds: readonly RenderResourceScope[];
   readonly worldStateTokens: readonly DirectionalShadowWorldState[];
   readonly assetCatalogEpoch: number;
   readonly pipelineHandle: number;
@@ -916,8 +916,8 @@ export interface DirectionalShadowCache {
  * ECS state that can change the contents of a directional shadow map.
  *
  * The ECS-owned RenderReadLease is the only render-facing mutation boundary.
- * Its version is intentionally conservative: any published World change
- * invalidates the cached atlas, while render never reaches through World for
+ * Its version is intentionally conservative: any published RenderResourceScope change
+ * invalidates the cached atlas, while render never reaches through RenderResourceScope for
  * component-clock storage.
  */
 export interface DirectionalShadowWorldState {

package/src/record/frame.ts

@@ -5,6 +5,8 @@ import {
   requiresProbeBlendRecord,
 } from '../gpu-driven/material-artifacts';
 import { projectMaterialBindingClasses } from '../gpu-driven/material-bindings';
+import type { RenderResourceScope } from '../publication/resource-scope';
+import { renderAssetByGuid, renderTime } from '../publication/resource-scope';
 import {
   buildDispatchPlan,
   cleanPerFrameCaches,
@@ -16,7 +18,6 @@ import { uploadMaterialUniforms } from './material-uniforms';
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
-import { Time, type World } from '@forgeax/engine-ecs';
 import type { RenderReadLease } from '@forgeax/engine-ecs/projection';
 import { frustum, mat4, vec3 } from '@forgeax/engine-math';
 import {
@@ -57,7 +58,7 @@ import {
   resolveDepthOfFieldFrameParams,
 } from '../features/depth-of-field/depth-of-field-params';
 import type { GpuDrivenProduction, PreparedGpuDrivenFrame } from '../gpu-driven/production-raster';
-import type { ShadowViewIdentity } from '../gpu-driven/shadow-views';
+import { type ShadowViewIdentity, shadowViewIdentityKey } from '../gpu-driven/shadow-views';
 import type { GpuDrivenLodSubmitIdentity } from '../gpu-driven/view-gpu';
 import { GPU_TEXTURE_USAGE_COPY_SRC } from '../gpu-texture-usage';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
@@ -144,11 +145,14 @@ export type FrameObservationReadback = (
 ) => Promise<Result<Uint8Array, Error>>;
 
 /**
- * Fold World identity into the renderer-owned validation token. The GPU
+ * Fold RenderResourceScope identity into the renderer-owned validation token. The GPU
  * production owner receives only this opaque key; ECS identity and ordering
- * stay in the record owner where the World list is authoritative.
+ * stay in the record owner where the RenderResourceScope list is authoritative.
  */
-function residencyValidationCacheKey(world: World, worlds: readonly World[]): string {
+function residencyValidationCacheKey(
+  world: RenderResourceScope,
+  worlds: readonly RenderResourceScope[],
+): string {
   return [world.identity, ...worlds.map((candidate) => candidate.identity)].join('\u001f');
 }
 function renderableIdentity(snapshot: Pick<RenderableSnapshot, 'worldId' | 'entityKey'>): string {
@@ -327,7 +331,7 @@ import {
 /**
  * Resolve the GPU mesh view used by the optional production raster before its
  * filtering pass runs. The result is keyed by the retained RenderScene slot,
- * which preserves the World namespace already used by gpuStore. User meshes
+ * which preserves the RenderResourceScope namespace already used by gpuStore. User meshes
  * are pull-resident during record; relying only on the boot-time builtin map
  * would make the first frame classify every imported mesh as a CPU fallback
  * and would hide its LOD ranges from the GPU cull. Builtins are the only
@@ -336,7 +340,7 @@ import {
 export function gpuDrivenMeshesForFrame(
   internals: RenderSystemInternals,
   pipelineState: PipelineState,
-  worlds: readonly World[],
+  worlds: readonly RenderResourceScope[],
   scene: PersistentGpuDrivenState | undefined,
 ): ReadonlyMap<number, MeshGpuHandles> {
   const meshes = new Map<number, MeshGpuHandles>();
@@ -357,7 +361,7 @@ export function gpuDrivenMeshesForFrame(
       const asset = resolveAssetHandle<MeshAsset>(world, sharedHandle);
       if (asset.ok) {
         const lodMeshes = slot.snapshot.lods?.map((lod) =>
-          internals.assets.lookup<MeshAsset>(lod.mesh),
+          renderAssetByGuid<MeshAsset>(world, internals.assets, lod.mesh),
         );
         const resolvedLodMeshes =
           lodMeshes?.every((lod): lod is MeshAsset => lod?.kind === 'mesh') === true
@@ -382,6 +386,7 @@ export type RecordProfileRunner = <T>(phase: RenderRecordPhase, action: () => T)
 export interface CubeCaptureFrameInput {
   readonly captureDispatch?: readonly DispatchEntry[];
   readonly snapshots: readonly CubeCameraSnapshot[];
+  readonly auxiliaryCameras: readonly CameraSnapshot[];
   readonly scheduler: import('../capture/scheduler').CubeCaptureScheduler;
   readonly state: CubeCaptureGraphState;
   readonly reflectionProbes?: import('./render-context').ReflectionProbeRecordState;
@@ -437,6 +442,18 @@ function prepareCubeCapture(
         (CUBE_CAPTURE_VIEW_SLOT_BASE + physicalWork.length) * VIEW_UNIFORM_SLOT_STRIDE,
     });
   }
+  for (const camera of input.auxiliaryCameras) {
+    if (camera.target === undefined) continue;
+    const physical = internals.getRenderTargetPhysical?.(camera.target);
+    if (physical?.descriptor.shape !== '2d') continue;
+    physicalWork.push({
+      target: camera.target,
+      faceIndex: 0,
+      physical,
+      faceCamera: camera,
+      viewBindGroupDynamicOffset: (CUBE_CAPTURE_VIEW_SLOT_BASE + 6) * VIEW_UNIFORM_SLOT_STRIDE,
+    });
+  }
   input.state.work = physicalWork;
   return physicalWork;
 }
@@ -467,8 +484,42 @@ function shadowPlanes(matrix: Float32Array): Float32Array {
   return frustum.fromViewProjection(frustum.create(), matrix as never);
 }
 
-function shadowViewToken(matrix: Float32Array): string {
-  return Array.from(matrix).join(',');
+function shadowViewPlanesByView(lights: ExtractedLights): ReadonlyMap<string, Float32Array> {
+  const views = new Map<string, Float32Array>();
+  for (const [index, matrix] of (lights.lightViewProj ?? []).entries()) {
+    views.set(shadowViewIdentityKey({ kind: 'directional', index }), shadowPlanes(matrix));
+  }
+  for (const [index, point] of lights.pointShadow.entries()) {
+    for (let face = 0; face < 6; face += 1) {
+      views.set(
+        shadowViewIdentityKey({ kind: 'point', index, face }),
+        shadowPlanes(point.shadowMatrices.subarray(face * 16, face * 16 + 16)),
+      );
+    }
+  }
+  let spotIndex = 0;
+  for (const spot of lights.spot) {
+    if (spot.lightViewProj === undefined) continue;
+    views.set(
+      shadowViewIdentityKey({ kind: 'spot', index: spotIndex }),
+      shadowPlanes(spot.lightViewProj),
+    );
+    spotIndex += 1;
+  }
+  return views;
+}
+
+function shadowViewToken(
+  matrix: Float32Array,
+  targetSize: number | undefined,
+  graphGeneration: number,
+): string {
+  // A newly accepted graph imports a new resource projection and must refresh
+  // the shadow compute inputs once. The graph-generation component is a
+  // one-shot resource fence; it is deliberately excluded from the GPU
+  // producer's topology signature so that this refresh cannot rebuild the
+  // graph indefinitely.
+  return `${Array.from(matrix).join(',')}|target:${targetSize}|graph:${graphGeneration}`;
 }
 
 function halfFloatToNumber(bits: number): number {
@@ -840,8 +891,8 @@ function resolveVolumetricFogHistoryContext(
  */
 function prepareSpotLightProjectorFrame(
   internals: RenderSystemInternals,
-  world: World,
-  worlds: readonly World[],
+  world: RenderResourceScope,
+  worlds: readonly RenderResourceScope[],
   lights: ExtractedLights,
   fog: ExtractedVolumetricFog | undefined,
 ): SpotLightProjectorFrameContext | undefined {
@@ -982,15 +1033,15 @@ interface FrameClockSample {
 
 /** Read the render sample clock from the camera's composition world once per frame. */
 function frameClockSample(
-  world: World,
-  worlds: readonly World[],
+  world: RenderResourceScope,
+  worlds: readonly RenderResourceScope[],
   camera: CameraSnapshot,
   sampleTimeSeconds?: number,
 ): FrameClockSample {
   const owner = worlds[camera.worldId ?? 0] ?? world;
   const invalidSampleTime = sampleTimeSeconds !== undefined && !Number.isFinite(sampleTimeSeconds);
   try {
-    const clock = owner.getResource(Time);
+    const clock = renderTime(owner);
     return {
       deltaSeconds: Number.isFinite(clock.delta) ? Math.max(0, clock.delta) : 0,
       // Keep the raw host sample even when ECS accepted only a clamped
@@ -1007,7 +1058,7 @@ function frameClockSample(
       invalidSampleTime,
     };
   } catch {
-    // Test and recovery callers may provide a minimal World-shaped owner. An
+    // Test and recovery callers may provide a minimal RenderResourceScope-shaped owner. An
     // absent clock is an invalid temporal pair and therefore safely resets.
     return {
       deltaSeconds: 0,
@@ -1372,7 +1423,7 @@ function updateVolumetricFogInspection(
 
 export function recordFrame(
   internals: RenderSystemInternals,
-  world: World,
+  world: RenderResourceScope,
   cameras: CameraSnapshot[],
   lights: ExtractedLights,
   renderables: readonly RenderableSnapshot[],
@@ -1392,7 +1443,7 @@ export function recordFrame(
   // the per-world extract stage). Optional + defaulting to `[world]` keeps the
   // pre-split single-world identity path (worldId always 0) byte-for-byte and
   // the existing unit-test callers (which pass a single mock world) valid.
-  worlds: readonly World[] = [world],
+  worlds: readonly RenderResourceScope[] = [world],
   profilePhase?: RecordProfileRunner,
   gpuDriven?: {
     readonly owner: GpuDrivenProduction;
@@ -1931,7 +1982,7 @@ export function recordFrame(
           shadowViews.push({
             identity: { kind: 'directional', index },
             planes: shadowPlanes(matrix),
-            cacheToken: `${shadowViewToken(matrix)}|target:${graphShadowMapSize}:${frameState.graphGeneration}`,
+            cacheToken: shadowViewToken(matrix, graphShadowMapSize, frameState.graphGeneration),
           });
         }
         for (const [index, point] of lights.pointShadow.entries()) {
@@ -1940,7 +1991,7 @@ export function recordFrame(
             shadowViews.push({
               identity: { kind: 'point', index, face },
               planes: shadowPlanes(matrix),
-              cacheToken: `${shadowViewToken(matrix)}|target:${graphShadowMapSize}:${frameState.graphGeneration}`,
+              cacheToken: shadowViewToken(matrix, graphShadowMapSize, frameState.graphGeneration),
             });
           }
         }
@@ -1950,7 +2001,11 @@ export function recordFrame(
           shadowViews.push({
             identity: { kind: 'spot', index: shadowSpotIndex },
             planes: shadowPlanes(spot.lightViewProj),
-            cacheToken: `${shadowViewToken(spot.lightViewProj)}|target:${graphShadowMapSize}:${frameState.graphGeneration}`,
+            cacheToken: shadowViewToken(
+              spot.lightViewProj,
+              graphShadowMapSize,
+              frameState.graphGeneration,
+            ),
           });
           shadowSpotIndex += 1;
         }
@@ -2270,7 +2325,7 @@ export function recordFrame(
       activeVolumetricFogSignature = resolvedHistory.signature;
       const previousTime = frameState.volumetricFogHistorySignature?.worldTimeSeconds;
       const currentTime = resolvedHistory.signature.worldTimeSeconds;
-      // Adjacent UBO lanes: validity, World time, elapsed time since accepted history.
+      // Adjacent UBO lanes: validity, RenderResourceScope time, elapsed time since accepted history.
       const historyParams = new Float32Array([
         activeVolumetricFogContext.historyValid ? 1 : 0,
         currentTime ?? 0,
@@ -2710,6 +2765,7 @@ export function recordFrame(
                   gpuDrivenShadowDrawKeysByView: rasterGpuDriven.shadowDrawKeysByView,
                 }),
           }),
+      shadowViewPlanesByView: shadowViewPlanesByView(lights),
       ...(frameGpuDriven?.scene === undefined
         ? {}
         : { gpuDrivenSceneMaterialBuffer: frameGpuDriven.scene.scene.materialBuffer }),
@@ -2842,7 +2898,7 @@ export function recordFrame(
       // the picture authority: an identity frame publishes an identity
       // mapping, while a failed enable/disable candidate retains the previous
       // mapping together with its old picture. Never pair an LKG graph with
-      // the live World's newer camera component.
+      // the live RenderResourceScope's newer camera component.
       // The exact mapping used to populate the accepted graph's UBO is the
       // only mapping promoted with its receipt. This keeps an identity frame,
       // a retained barrel LKG and a normal nonzero frame on one context.
@@ -2855,7 +2911,10 @@ export function recordFrame(
       // prior tick into the next topology.
       acknowledgeRenderFeatureSubmission(getRenderFeatureGraphState(internals).plans);
     }
-    if (cubeCapture !== undefined && cubeCaptureWork.length > 0) {
+    if (
+      cubeCapture !== undefined &&
+      cubeCaptureWork.some((work) => work.physical.descriptor.shape === 'cube')
+    ) {
       const completed = cubeCapture.scheduler.completeSubmission(submitted, completion);
       if (!completed.ok) internals.errorRegistry.fire(completed.error);
     }
@@ -2980,7 +3039,7 @@ function readWorldState(lease: RenderReadLease): DirectionalShadowWorldState {
 
 function sameWorldState(
   cached: DirectionalShadowCache,
-  worlds: readonly World[],
+  worlds: readonly RenderResourceScope[],
   leases: readonly RenderReadLease[] | undefined,
 ): boolean {
   if (leases === undefined || leases.length !== worlds.length) return false;
@@ -2999,7 +3058,7 @@ function sameWorldState(
       changes = lease.readChanges(cachedState.version);
     } catch {
       // Treat malformed or foreign version evidence as stale and rebuild the
-      // atlas rather than reaching through World for a second mutation clock.
+      // atlas rather than reaching through RenderResourceScope for a second mutation clock.
       return false;
     }
     if (
@@ -3047,7 +3106,7 @@ function sameDirectionalShadowQuality(
 function prepareDirectionalShadowCache(
   internals: RenderSystemInternals,
   frameState: RenderFrameState,
-  worlds: readonly World[],
+  worlds: readonly RenderResourceScope[],
   leases: readonly RenderReadLease[] | undefined,
   lights: ExtractedLights,
   shadowMapSize: number | undefined,
@@ -3102,7 +3161,7 @@ function prepareDirectionalShadowCache(
   if (leases === undefined || leases.length !== worlds.length) {
     // Direct record-stage test harnesses may omit the host-owned leases. They
     // still exercise the real shadow encoder, but without the ECS read owner
-    // they must conservatively rebuild rather than inspect World internals.
+    // they must conservatively rebuild rather than inspect RenderResourceScope internals.
     return { reuse: false, next: null };
   }
   const worldStateTokens = leases.map(readWorldState);

package/src/record/helpers.ts

@@ -1,8 +1,8 @@
+import type { RenderResourceScope } from '../publication/resource-scope';
 // @forgeax/engine-runtime - RenderSystem record stage: helpers.
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
-import type { World } from '@forgeax/engine-ecs';
 import { type Mat4, mat4 } from '@forgeax/engine-math';
 import type { EquirectAsset } from '@forgeax/engine-types';
 import { toShared } from '@forgeax/engine-types';
@@ -140,7 +140,7 @@ export function warnMultiSkybox(
  */
 export function driveLazyEquirectProjection(
   internals: RenderSystemInternals,
-  world: World,
+  world: RenderResourceScope,
   frameState: Pick<RenderFrameState, 'firedEquirectProjectionFailedHandles'>,
   equirectHandle: number,
 ): void {