@forgeax/engine-render 0.1.35 → 0.1.37

package/src/publication/__tests__/publication.integration.test.ts

@@ -71,6 +71,20 @@ function fixture() {
 }
 
 describe('native render publication', () => {
+  it('queries detached bounds by publication identity and rejects another epoch', () => {
+    const f = fixture();
+    const identity = { source: 'publication-test', epoch: 1 };
+    expect(f.scene.bounds(identity, f.first)).toBeUndefined();
+    f.publish();
+    const bounds = f.scene.bounds(identity, f.first);
+    expect(bounds).toBeDefined();
+    expect(f.scene.bounds({ ...identity, epoch: 2 }, f.first)).toBeUndefined();
+    expect(f.scene.bounds({ source: 'other', epoch: 1 }, f.first)).toBeUndefined();
+    if (bounds !== undefined) (bounds.min as number[])[0] = -999;
+    expect(f.scene.bounds(identity, f.first)?.min[0]).not.toBe(-999);
+    f.publisher.dispose();
+  });
+
   it('publishes a numeric baseline, observes no static delta and retains the same CPU slots', () => {
     const f = fixture();
     const initial = f.publish();
@@ -368,3 +382,48 @@ it('publishes detached skin poses and follows joint changes across skipped sourc
   ).toBeUndefined();
   f.publisher.dispose();
 });
+
+it('renders a one-frame identity before its sealed removal and reuses two buffer slots', () => {
+  const f = fixture();
+  const seal = () => {
+    const candidate = f.publisher.prepare(0).unwrap();
+    const packet = structuredClone(candidate.packet, {
+      transfer: renderPublicationTransfers(candidate.packet),
+    });
+    candidate.accept();
+    return packet;
+  };
+  try {
+    const first = seal();
+    f.world.despawn(f.first).unwrap();
+    const replacement = f.spawn();
+    f.world.update(0).unwrap();
+    const second = seal();
+    // More source mutations cannot edit either already-transferred publication.
+    f.world.despawn(replacement).unwrap();
+    f.world.update(0).unwrap();
+    const firstFrame = f.scene.consumePublication(f.receiver.accept(first).unwrap());
+    expect(firstFrame.renderables.map((row) => row.entityKey)).toContain(f.first);
+    f.publisher.recycle(first.revision, renderPublicationTransfers(first)).unwrap();
+    const secondFrame = f.scene.consumePublication(f.receiver.accept(second).unwrap());
+    expect(secondFrame.renderables.map((row) => row.entityKey)).toContain(replacement);
+    expect(secondFrame.renderables.map((row) => row.entityKey)).not.toContain(f.first);
+    f.publisher.recycle(second.revision, renderPublicationTransfers(second)).unwrap();
+    // Warm both slots for equivalent changed-transform frames, then drain in pairs.
+    let warmAllocations: number | undefined;
+    for (let index = 0; index < 4; index++) {
+      const packets = [1, 2].map((x) => {
+        f.world.set(f.second, Transform, { pos: [x, index, 0] }).unwrap();
+        f.world.update(0).unwrap();
+        return seal();
+      });
+      const allocations = f.publisher.inspect().allocations;
+      for (const packet of packets)
+        f.publisher.recycle(packet.revision, renderPublicationTransfers(packet)).unwrap();
+      warmAllocations ??= allocations;
+      expect(allocations).toBe(warmAllocations);
+    }
+  } finally {
+    f.publisher.dispose();
+  }
+});

package/src/publication/publisher.ts

@@ -68,9 +68,15 @@ export function createRenderPublisher(
   const consumers = new Map<Handle<string, 'shared'>, Set<number>>();
   const pending = new Set<number>();
   let videoConsumers = new Map<number, readonly number[]>();
-  let pendingFeatures: RenderPublication['features'] = [];
-  let pendingFeatureOwners: readonly RenderFeature<unknown>[] = [];
-  const acknowledgedFeatures = new Set<string>();
+  // Two slots: the consuming frame and one sealed successor.
+  const flights = new Map<
+    number,
+    {
+      features: RenderPublication['features'];
+      owners: readonly RenderFeature<unknown>[];
+      submitted: boolean;
+    }
+  >();
   const jointsByEntity = new Map<number, readonly number[]>();
   const skinConsumers = new Map<number, Set<number>>();
   let frameDependencies = new Set<Handle<string, 'shared'>>();
@@ -79,9 +85,9 @@ export function createRenderPublisher(
     disposed = false,
     active = false;
   let lastScannedRows = 0,
-    inFlight = false,
     allocations = 0;
   let storage = [new ArrayBuffer(0), new ArrayBuffer(0), new ArrayBuffer(0), new ArrayBuffer(0)];
+  const spareStorage: ArrayBuffer[][] = [];
   const buffer = (index: number, bytes: number): ArrayBuffer => {
     let value = storage[index] as ArrayBuffer;
     if (value.byteLength < bytes) {
@@ -104,7 +110,8 @@ export function createRenderPublisher(
       members: members.size,
       assetCount: consumers.size,
       scannedRows: lastScannedRows,
-      inFlight,
+      inFlight: flights.size > 0,
+      inFlightCount: flights.size,
       allocations,
     }),
     prepare(
@@ -112,7 +119,8 @@ export function createRenderPublisher(
       temporalReset = false,
     ): Result<RenderPublicationCandidate, RenderPublicationError> {
       if (disposed) return fail('disposed', 'publisher');
-      if (active || inFlight) return fail('in-flight', 'publication storage has not been returned');
+      if (active || flights.size === 2)
+        return fail('in-flight', 'both publication slots are occupied');
       const baseline = revision === 0;
       const featureSources = [...features];
       const batch = source.projection.read();
@@ -330,7 +338,18 @@ export function createRenderPublisher(
           if (seenGuids.has(key)) continue;
           seenGuids.add(key);
           const asset = assets.lookup(key);
-          const handle = internSharedRefFromGuid(world, assets, key, 'RenderFeatureAsset');
+          // Dynamic asset content is keyed by the canonical World handle. Feature
+          // dependencies must share the same identity as ordinary scene consumers.
+          const handle = internSharedRefFromGuid(
+            world,
+            assets,
+            key,
+            asset?.kind === 'material'
+              ? 'MaterialAsset'
+              : asset?.kind === 'mesh'
+                ? 'MeshAsset'
+                : 'RenderFeatureAsset',
+          );
           if (asset === undefined || handle === undefined)
             throw new Error(`Missing feature asset ${guid}`);
           nextFrameDependencies.add(handle);
@@ -455,7 +474,10 @@ export function createRenderPublisher(
           transformEntities,
           transforms: matrices,
           assets: [...assetRows].map(([handle, value]) => {
-            const guid = assets.guidOf(value);
+            // Runtime content is a projection, so GUID identity stays with the
+            // underlying catalogued payload rather than the projected object.
+            const source = world.sharedRefs.resolve<string, Asset>(handle);
+            const guid = assets.guidOf(source.ok ? source.value : value);
             return { handle, value, ...(guid === undefined ? {} : { guid }) };
           }),
           retiredAssets: [...retired],
@@ -474,13 +496,20 @@ export function createRenderPublisher(
             for (const key of programs.keys()) publishedPrograms.add(key);
             closed = true;
             active = false;
-            inFlight = true;
             revision++;
+            flights.set(revision, {
+              features: featureRows,
+              owners: featureSources,
+              submitted: false,
+            });
+            storage = spareStorage.pop() ?? [
+              new ArrayBuffer(0),
+              new ArrayBuffer(0),
+              new ArrayBuffer(0),
+              new ArrayBuffer(0),
+            ];
             for (const row of videoFrames) row.frame.close();
             videoConsumers = nextVideoConsumers;
-            pendingFeatures = featureRows;
-            pendingFeatureOwners = featureSources;
-            acknowledgedFeatures.clear();
             frameDependencies = nextFrameDependencies;
             catalogEpoch = assets.catalogEpoch;
             for (const entity of removedConsumers) {
@@ -560,26 +589,23 @@ export function createRenderPublisher(
       receipts: readonly { readonly identity: string; readonly feedback: unknown }[],
     ): Result<void, RenderPublicationError> {
       if (disposed) return fail('disposed', 'publisher');
-      if (!inFlight || revision !== acceptedRevision)
+      const flight = flights.get(acceptedRevision);
+      if (flight === undefined || flight.submitted)
         return fail('revision', 'feature acknowledgment');
       const identities = new Set<string>();
       for (const receipt of receipts) {
-        if (identities.has(receipt.identity) || acknowledgedFeatures.has(receipt.identity))
+        if (identities.has(receipt.identity))
           return fail('revision', 'duplicate feature acknowledgment');
-        const row = pendingFeatures.find((row) => row.identity === receipt.identity);
-        const feature = pendingFeatureOwners.find(
-          (feature) => feature.identity === receipt.identity,
-        );
+        const row = flight.features.find((row) => row.identity === receipt.identity);
+        const feature = flight.owners.find((feature) => feature.identity === receipt.identity);
         if (row === undefined || feature === undefined)
           return fail('shape', 'unknown feature acknowledgment');
         identities.add(receipt.identity);
       }
+      flight.submitted = true;
       for (const receipt of receipts) {
-        acknowledgedFeatures.add(receipt.identity);
-        const row = pendingFeatures.find((row) => row.identity === receipt.identity);
-        const feature = pendingFeatureOwners.find(
-          (feature) => feature.identity === receipt.identity,
-        );
+        const row = flight.features.find((row) => row.identity === receipt.identity);
+        const feature = flight.owners.find((feature) => feature.identity === receipt.identity);
         feature?.onSourceFrameSubmitted?.(row?.data, receipt.feedback);
       }
       return ok(undefined);
@@ -589,12 +615,14 @@ export function createRenderPublisher(
       buffers: readonly ArrayBuffer[],
     ): Result<void, RenderPublicationError> {
       if (disposed) return fail('disposed', 'publisher');
-      if (!inFlight || acceptedRevision !== revision)
+      if (flights.keys().next().value !== acceptedRevision)
         return fail('revision', 'returned storage revision');
       if (buffers.length !== 4 || buffers.some((value) => !(value instanceof ArrayBuffer)))
         return fail('shape', 'returned storage');
-      storage = [...buffers];
-      inFlight = false;
+      if (active || storage.some((buffer) => buffer.byteLength > 0))
+        spareStorage.push([...buffers]);
+      else storage = [...buffers];
+      flights.delete(acceptedRevision);
       return ok(undefined);
     },
     dispose() {
@@ -607,9 +635,8 @@ export function createRenderPublisher(
       pending.clear();
       pendingMeshContent.clear();
       videoConsumers.clear();
-      pendingFeatures = [];
-      pendingFeatureOwners = [];
-      acknowledgedFeatures.clear();
+      flights.clear();
+      spareStorage.length = 0;
       frameDependencies.clear();
       jointsByEntity.clear();
       skinConsumers.clear();

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/frame.ts

@@ -58,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';
@@ -484,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 {
@@ -1948,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()) {
@@ -1957,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),
             });
           }
         }
@@ -1967,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;
         }
@@ -2727,6 +2765,7 @@ export function recordFrame(
                   gpuDrivenShadowDrawKeysByView: rasterGpuDriven.shadowDrawKeysByView,
                 }),
           }),
+      shadowViewPlanesByView: shadowViewPlanesByView(lights),
       ...(frameGpuDriven?.scene === undefined
         ? {}
         : { gpuDrivenSceneMaterialBuffer: frameGpuDriven.scene.scene.materialBuffer }),

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

@@ -14,7 +14,7 @@ import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usag
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
 import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
 import type { RenderResourceScope } from '../publication/resource-scope';
-import { renderAssetByGuid } from '../publication/resource-scope';
+import { internSharedRefFromGuid } from '../render-system-extract';
 import {
   applyParamSchemaDefaultsToUbo,
   applyParamSnapshotToUbo,
@@ -29,7 +29,6 @@ export type PreparedResolverCaches = {
   readonly preparedGroup0Pipelines: WeakSet<object>;
   readonly preparedViewOnlyPipelines: WeakSet<object>;
   readonly preparedRenderMaterialPipelines: WeakSet<object>;
-  readonly preparedAssetHandles: WeakMap<RenderResourceScope, Map<string, number>>;
 };
 
 export function createPreparedResolverCaches(): PreparedResolverCaches {
@@ -39,37 +38,22 @@ 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: 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'>;
   if ('resolveAsset' in world)
     return world.handleForGuid(guid) as Handle<Brand, 'shared'> | undefined;
-  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;
+  return internSharedRefFromGuid(world, runtime.assets, guid, brand);
 }
 
 export function preparedMaterialBindings(
   runtime: RenderSystemInternals,
-  caches: PreparedResolverCaches,
   worlds: readonly RenderResourceScope[],
   materialShaderId: string,
   worldIndex: number,
@@ -78,14 +62,16 @@ export function preparedMaterialBindings(
   skylightResources?: SkylightBindGroupResources,
 ) {
   const world = worlds[worldIndex];
-  const material =
-    world === undefined
-      ? undefined
-      : renderAssetByGuid<MaterialAsset>(world, runtime.assets, materialGuid);
+  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(
@@ -132,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) {
@@ -149,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;
       }

package/src/record/render-context.ts

@@ -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. */