@forgeax/engine-render 0.1.34 → 0.1.35

package/src/assembly/render-target-host.ts

@@ -79,6 +79,11 @@ interface ReadbackRecord {
 export interface RenderTargetHost {
   /** The logical owner for every target lifecycle operation. */
   readonly owner: 'renderer';
+  /** Logical descriptions for the source publication boundary; no physical state escapes. */
+  descriptions(): readonly {
+    readonly target: RenderTarget;
+    readonly descriptor: RenderTargetDescriptor;
+  }[];
   createRenderTarget(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
   resizeRenderTarget(
     target: RenderTarget,
@@ -231,53 +236,51 @@ function makePhysical(
   const faceViews: TextureView[] = [];
   const depthTextures: Texture[] = [];
   const depthViews: TextureView[] = [];
-  if (descriptor.shape === 'cube') {
-    for (let face = 0; face < layers; face += 1) {
-      const depth = device.createTexture({
-        label: `render-target.${generation}.depth.${face}`,
-        size: {
-          width: descriptor.width,
-          height: descriptor.height,
-          depthOrArrayLayers: descriptor.sampleCount === 4 ? 1 : layers,
-        },
-        mipLevelCount: 1,
-        sampleCount: descriptor.sampleCount,
-        dimension: '2d',
-        format: 'depth24plus-stencil8',
-        usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
-        viewFormats: undefined,
-        textureBindingViewDimension: undefined,
-      });
-      if (!depth.ok)
-        return {
-          ok: false,
-          error: new RenderTargetOperationFailedError({
-            operation: 'create',
-            stage: 'allocation',
-            generation,
-            cause: depth.error,
-            recovery: 'retry',
-          }),
-        };
-      const depthView = device.createTextureView(depth.value, {
-        dimension: '2d',
-        baseArrayLayer: descriptor.sampleCount === 4 ? 0 : face,
-        arrayLayerCount: 1,
-      });
-      if (!depthView.ok)
-        return {
-          ok: false,
-          error: new RenderTargetOperationFailedError({
-            operation: 'create',
-            stage: 'allocation',
-            generation,
-            cause: depthView.error,
-            recovery: 'retry',
-          }),
-        };
-      depthTextures.push(depth.value);
-      depthViews.push(depthView.value);
-    }
+  for (let face = 0; face < layers; face += 1) {
+    const depth = device.createTexture({
+      label: `render-target.${generation}.depth.${face}`,
+      size: {
+        width: descriptor.width,
+        height: descriptor.height,
+        depthOrArrayLayers: descriptor.sampleCount === 4 ? 1 : layers,
+      },
+      mipLevelCount: 1,
+      sampleCount: descriptor.sampleCount,
+      dimension: '2d',
+      format: 'depth24plus-stencil8',
+      usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+      viewFormats: undefined,
+      textureBindingViewDimension: undefined,
+    });
+    if (!depth.ok)
+      return {
+        ok: false,
+        error: new RenderTargetOperationFailedError({
+          operation: 'create',
+          stage: 'allocation',
+          generation,
+          cause: depth.error,
+          recovery: 'retry',
+        }),
+      };
+    const depthView = device.createTextureView(depth.value, {
+      dimension: '2d',
+      baseArrayLayer: descriptor.sampleCount === 4 ? 0 : face,
+      arrayLayerCount: 1,
+    });
+    if (!depthView.ok)
+      return {
+        ok: false,
+        error: new RenderTargetOperationFailedError({
+          operation: 'create',
+          stage: 'allocation',
+          generation,
+          cause: depthView.error,
+          recovery: 'retry',
+        }),
+      };
+    depthTextures.push(depth.value);
+    depthViews.push(depthView.value);
   }
   if (descriptor.sampleCount === 4) {
     for (let face = 0; face < layers; face += 1) {
@@ -405,6 +408,13 @@ export function createRenderTargetHost(options: RenderTargetHostOptions = {}): R
 
   return Object.freeze({
     owner: 'renderer' as const,
+    descriptions() {
+      return [...targets].map((target) => {
+        const state = owner.inspect(target);
+        if (!state.ok) throw state.error;
+        return { target, descriptor: state.value.candidate?.descriptor ?? state.value.descriptor };
+      });
+    },
     createRenderTarget(
       descriptor: RenderTargetDescriptor,
     ): RenderResult<RenderTarget, RenderError> {

package/src/assembly/renderer-facade.ts

@@ -1,3 +1,4 @@
+import { RenderPublicationError } from '../publication/contract';
 // Public renderer facade and profile validation.
 // This module narrows the lifetime-heavy host implementation to the stable
 // lease/receipt contract and owns the profile/error projection helpers.
@@ -64,7 +65,8 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
           cause: structuredRendererCause(cause, 'renderer-event'),
         });
   const drawError = (cause: RhiError | RenderError): RenderError => {
-    if (cause instanceof MotionBlurValidationError) return cause;
+    if (cause instanceof MotionBlurValidationError || cause instanceof RenderPublicationError)
+      return cause;
     if (cause instanceof RendererOperationError) return cause;
     if (cause instanceof RendererContractFailureError) {
       return new RendererOperationError('device-operation-failed', {

package/src/assembly/webgpu-ready.ts

@@ -1439,7 +1439,7 @@ export async function buildReadyWebGPU(
   // instances) and the 4-slot pipeline layout in one call, throwing on each
   // device.createBindGroupLayout / device.createPipelineLayout failure.
   // material BGL now carries 24 entries (canonical material 0..14 + Skylight
-  // 15..21 + transmission 22..23); authored physical maps append after the
+  // 15..20 + transmission 21..22); authored physical maps append after the
   // engine-owned injections. The pipeline layout itself stays at 4 slots, no
   // @group(4) allocated (D-5 round-4 fix for the round-2 maxBindGroups=4
   // BLOCKER). The standalone unlit BGL is the 15-entry user region exposed by

package/src/assembly/webgpu-renderer.ts

@@ -6,7 +6,7 @@ import {
   DynamicTextureStore,
 } from '@forgeax/engine-assets-runtime';
 import { audioLoader } from '@forgeax/engine-audio-webaudio';
-import { Update, type World } from '@forgeax/engine-ecs';
+import type { World } from '@forgeax/engine-ecs';
 import { createRenderReadLease, type RenderReadLease } from '@forgeax/engine-ecs/projection';
 import {
   DEFAULT_VERTEX_ATTRIBUTE_MAP,
@@ -21,7 +21,6 @@ import type {
   RhiDevice,
 } from '@forgeax/engine-rhi';
 import { err, ok, RhiError, validateDrawArgs } from '@forgeax/engine-rhi';
-import { registerPropagateTransforms } from '@forgeax/engine-scene';
 import {
   findVariantByKey,
   type MaterialShaderEntry,
@@ -39,6 +38,11 @@ import type {
   PrimitiveTopology,
   VertexAttributeMap,
 } from '@forgeax/engine-types';
+import { type PublishedRenderFrameInput, RenderPublicationError } from '../publication/contract';
+import { installPublicationPrograms } from '../publication/programs';
+import { type PreparedRenderPublication, RenderPublicationReceiver } from '../publication/receiver';
+import { RenderPublicationTargetReceiver } from '../publication/targets';
+import { registerRenderSourceSystems } from '../scene/source-systems';
 import { transmissionBackdropAvailable } from './device-feature-admission';
 
 export type { MaterialShaderManifestEntry } from '@forgeax/engine-shader';
@@ -71,7 +75,6 @@ import {
   type PostProcessShaderEntry,
   postProcessShaderModuleLabel,
 } from '../fullscreen-post-process-pass';
-import { glyphTextLayoutSystem } from '../glyph-text-layout-system';
 import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from '../gpu-stage';
 import { type BloomInspection, emptyBloomInspection } from '../inspection-types';
 import { DeviceScope } from '../lifecycle';
@@ -155,7 +158,6 @@ import {
 import { createGpuPassTimingObservationStore, observeGpuPassTimingDisabled } from '../renderer.js';
 import { postSpawnResolveJoints } from '../scene-instances/post-spawn-resolve-joints';
 import type { RenderTarget } from '../targets/contracts';
-import { tilemapChunkExtractSystem } from '../tilemap-chunk-extract-system';
 import type { TypedFrameObservationCapture } from '../typed-render-graph-primitives';
 import { registerAnalyticFogPostProcess } from './analytic-fog-registration';
 import type { RhiBackendPack } from './backend-contract';
@@ -303,7 +305,6 @@ export type { WebGPUOutcome, WebGPURendererInternals } from './webgpu-renderer-c
 export { disposeObservationCaptureSet } from './webgpu-renderer-observation';
 
 /** Bundler injection and the WebGPU renderer construction entry points. */
-let nextDerivedSystemId = 0;
 export async function tryCreateWebGPURenderer(
   canvas: HTMLCanvasElement | OffscreenCanvas,
   options: RendererOptions | undefined,
@@ -315,7 +316,12 @@ export async function tryCreateWebGPURenderer(
 async function makeWebGPURenderer(
   internals: WebGPURendererInternals,
 ): Promise<RendererAssemblyImplementation> {
+  let publicationTargets: RenderPublicationTargetReceiver | undefined;
   let disposed = false;
+  const publicationReceiver =
+    internals.options?.publicationSource === undefined
+      ? undefined
+      : new RenderPublicationReceiver(internals.options.publicationSource);
   const observeTiming = observeGpuPassTimingDisabled;
   const frameContinuations = new Set<ContinuationTerminator>();
   type RecoveryInspection = RenderInspection['recovery'];
@@ -584,27 +590,7 @@ async function makeWebGPURenderer(
     }
     return state.shaderInstance;
   };
-  // D-S9: AssetRegistry instance shared with RenderSystem. RenderSystem
-  // looks up MeshFilter.assetHandle here per frame; buildReadyWebGPU step 3
-  // uploads the registry's builtin mesh geometry to GPU buffers so the
-  // RenderSystem can route MeshFilter.assetHandle to a real (vbo, ibo) pair.
-  // feat-20260527 M1 / w1: ShaderCatalog is now eager-constructed and
-  // constructor-injected into AssetRegistry (plan-strategy D-1). The
-  // ShaderCatalogDevice adapter (shared between the catalog and per-MaterialShader
-  // pipeline cache) is already available at this point.
   const shaderCatalog = getShader();
-  // bug-20260601-hello-tonemap-material-register M1 (plan-strategy D-1):
-  // All material-shader entries are now registered from the manifest
-  // BEFORE the renderer is returned, so `register<MaterialAsset>` referencing
-  // an engine shader succeeds without waiting for `renderer.initialization`.
-  // Host-injected ImportTransport remains a constructor-only dependency.
-  // feat-20260705-runtime-tier2-decomposition M1 / w10 (D-1 / D-2): the sole
-  // production assembly point injects (a) the post-spawn hook
-  // `postSpawnResolveJoints` (auto-wire Skin.joints; D-1) and the audio
-  // catalog-entry loader. The latter stays at this assembly boundary so
-  // assets-runtime remains independent of the concrete Web Audio backend.
-  // videoLoader is wired internally from graphics-extras; the full registry has
-  // 11 engine kinds. This is the only `new AssetRegistry(...)` call in the repo.
   const assets = new AssetRegistry(
     shaderCatalog,
     internals.importTransport,
@@ -735,7 +721,9 @@ async function makeWebGPURenderer(
   gpuStore.configureGpuDevice(
     internals.device,
     packShaderFactory,
-    (world, pod) => {
+    (world, pod, source) => {
+      // The accepted equirect identity already owns this renderer-local GPU projection.
+      if ('resolveAsset' in world) return ok(source);
       const handle = world.allocSharedRef('EquirectAsset', pod);
       return ok(handle);
     },
@@ -2562,7 +2550,6 @@ async function makeWebGPURenderer(
       currentGeneration: () => activeDeviceScope.generation,
       renderSystem,
     });
-  const derivedSystemNames = new Map<World, string>();
   const transformReleases = new Map<World, () => void>();
   const attachmentOwner = {};
   let frameId = 0;
@@ -2599,6 +2586,13 @@ async function makeWebGPURenderer(
       renderSystem.setSurfaceDynamicInput(frame);
     },
     attach(world: World): RenderResult<RenderWorldLease, RenderError> {
+      if (publicationReceiver !== undefined)
+        return err(
+          new RenderPublicationError({
+            reason: 'identity',
+            subject: 'publication Renderer has no World attachment',
+          }),
+        );
       const attached = this.attachScene(world);
       if (!attached.ok) {
         return err(new RendererContractFailureError('attach', attached.error.hint));
@@ -2850,23 +2844,7 @@ async function makeWebGPURenderer(
       }
       if (attachedWorlds.has(world)) return ok(undefined);
       try {
-        const releaseTransforms = registerPropagateTransforms(world);
-        const derivedSystemName = `renderDerived:${++nextDerivedSystemId}`;
-        const derived = world.addSystem(Update, {
-          name: derivedSystemName,
-          queries: [],
-          fn: (world) => {
-            tilemapChunkExtractSystem(world, (guid) => assets.lookup(guid));
-            const glyphResult = glyphTextLayoutSystem(world, gpuStore);
-            if (!glyphResult.ok) throw glyphResult.error;
-          },
-        });
-        if (!derived.ok) {
-          releaseTransforms();
-          throw new Error(`failed to register ${derivedSystemName}: ${derived.error.code}`);
-        }
-        transformReleases.set(world, releaseTransforms);
-        derivedSystemNames.set(world, derivedSystemName);
+        transformReleases.set(world, registerRenderSourceSystems(world, assets, gpuStore));
         attachedWorlds.add(world);
         return ok(undefined);
       } catch (cause) {
@@ -2897,11 +2875,6 @@ async function makeWebGPURenderer(
         }
       }
       renderSystem.detachScene(world);
-      const derivedSystemName = derivedSystemNames.get(world);
-      if (derivedSystemName !== undefined) {
-        world.removeSystem(Update, derivedSystemName);
-        derivedSystemNames.delete(world);
-      }
       transformReleases.get(world)?.();
       transformReleases.delete(world);
     },
@@ -3105,17 +3078,43 @@ async function makeWebGPURenderer(
         : ok(result.value);
     },
     draw(
-      worldsOrRequest: readonly World[] | RenderFrameInput,
+      worldsOrRequest: readonly World[] | RenderFrameInput | PublishedRenderFrameInput,
       options?: DrawOwnerOptions,
     ): Result<void | FrameReceipt, RhiError | RenderError> {
       const isFrameRequest = !Array.isArray(worldsOrRequest);
-      const frameRequest = isFrameRequest ? (worldsOrRequest as RenderFrameInput) : undefined;
+      const publicationRequest =
+        isFrameRequest && 'publication' in worldsOrRequest
+          ? (worldsOrRequest as PublishedRenderFrameInput)
+          : undefined;
+      const frameRequest =
+        isFrameRequest && publicationRequest === undefined
+          ? (worldsOrRequest as RenderFrameInput)
+          : undefined;
+      let publication: PreparedRenderPublication | undefined;
+      if (publicationRequest !== undefined) {
+        if (publicationReceiver === undefined)
+          return err(
+            new RenderPublicationError({
+              reason: 'identity',
+              subject: 'RendererOptions.publicationSource',
+            }),
+          );
+      } else if (publicationReceiver !== undefined) {
+        return err(
+          new RenderPublicationError({
+            reason: 'identity',
+            subject: 'a publication-bound renderer cannot consume local World leases',
+          }),
+        );
+      }
       const worlds: readonly World[] =
         frameRequest !== undefined
           ? frameRequest.leases
               .map((lease) => attachedLeases.get(lease))
               .filter((world): world is World => world !== undefined)
-          : (worldsOrRequest as readonly World[]);
+          : publicationRequest === undefined
+            ? (worldsOrRequest as readonly World[])
+            : [];
       const readLeases: readonly RenderReadLease[] | undefined =
         frameRequest !== undefined
           ? frameRequest.leases
@@ -3170,7 +3169,14 @@ async function makeWebGPURenderer(
                 ? {}
                 : { geometryLane: frameRequest.geometryLane }),
             }
-          : (options ?? { cameraOwner: 0, resourceOwner: 0 });
+          : publicationRequest === undefined
+            ? (options ?? { cameraOwner: 0, resourceOwner: 0 })
+            : {
+                cameraOwner: 0,
+                resourceOwner: 0,
+                sampleTimeSeconds: publicationRequest.publication.sampleTimeSeconds,
+                temporalReset: publicationRequest.publication.temporalReset,
+              };
       // feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle / M5 / w21
       // (plan-strategy D-1, D-8): post-dispose the renderer is dead. AI
       // users observing `result.ok === false && err.code === 'rhi-not-
@@ -3246,7 +3252,8 @@ async function makeWebGPURenderer(
       // are non-exclusive: an empty array short-circuits to empty-worlds. The
       // check is defensive against JS callers passing a non-array despite the
       // compile-time World[] type (red-window migration safety).
-      const worldCount = Array.isArray(worlds) ? worlds.length : 0;
+      const worldCount =
+        publicationRequest === undefined ? (Array.isArray(worlds) ? worlds.length : 0) : 1;
       if (worldCount === 0 && internals.device.caps.backendKind === 'null') {
         return ok(undefined);
       }
@@ -3268,12 +3275,27 @@ async function makeWebGPURenderer(
         internals.errorRegistry,
       );
       if (!contextConfigured.ok) return contextConfigured;
-      renderTargetHost.beginFrame();
       // w24 — facade-level try/catch produces Result.err on unexpected throw
       // (D-P6 dual-channel preserved: per-stage RhiError continues to fan out
       // through onError separately; the facade Result is the synchronous
       // summary AI users can ignore or branch on).
       try {
+        if (publicationRequest !== undefined && publicationReceiver !== undefined) {
+          const accepted = publicationReceiver.accept(publicationRequest.publication);
+          if (!accepted.ok) return accepted;
+          publicationTargets ??= new RenderPublicationTargetReceiver(renderTargetHost);
+          publication = {
+            ...publicationTargets.apply(accepted.value),
+            ...(publicationRequest.onFeatureSourceSubmitted === undefined
+              ? {}
+              : {
+                  onFeatureSourceSubmitted: publicationRequest.onFeatureSourceSubmitted,
+                }),
+          };
+          installPublicationPrograms(assets, publicationRequest.publication.programs);
+        }
+        renderTargetHost.beginFrame();
+
         const timingHost = internals as WebGPURendererInternals & {
           gpuPassTimingFrameIdentity?:
             | {
@@ -3311,7 +3333,13 @@ async function makeWebGPURenderer(
             graphGeneration: 0,
           };
         }
-        const submitted = renderSystem.draw(worlds, drawOptions, readLeases, volumeTimingCapture);
+        const submitted = renderSystem.draw(
+          worlds,
+          drawOptions,
+          readLeases,
+          volumeTimingCapture,
+          publication,
+        );
         timingHost.observationFrameId = undefined;
         timingHost.observationCaptureDomains = undefined;
         timingHost.gpuPassTimingFrameIdentity = undefined;
@@ -3510,6 +3538,10 @@ async function makeWebGPURenderer(
         });
         internals.errorRegistry.fire(e);
         return err(e);
+      } finally {
+        // Native video pixels have been consumed by synchronous queue copy calls.
+        // Release them on every success/failure path, including direct publication users.
+        publicationReceiver?.releaseVideoFrames();
       }
     },
     async observe(
@@ -3752,6 +3784,7 @@ async function makeWebGPURenderer(
       disposed = true;
       for (const world of attachedWorlds) dynamicGeometryHost.invalidateDynamicGeometryWorld(world);
       dynamicGeometry.dispose();
+      publicationReceiver?.dispose();
       for (const continuation of frameContinuations) {
         continuation.terminate({ code: 'disposed' });
       }
@@ -3762,11 +3795,6 @@ async function makeWebGPURenderer(
       }
       for (const world of attachedWorlds) {
         try {
-          const derivedSystemName = derivedSystemNames.get(world);
-          if (derivedSystemName !== undefined) {
-            world.removeSystem(Update, derivedSystemName);
-            derivedSystemNames.delete(world);
-          }
           transformReleases.get(world)?.();
           transformReleases.delete(world);
         } catch (cause) {

package/src/cloud/frame-context.ts

@@ -1,12 +1,12 @@
-import type { World } from '@forgeax/engine-ecs';
 import type { RenderFeatureFrameContext, RenderFeatureViewContext } from '../features/types';
+import type { RenderResourceScope } from '../publication/resource-scope';
 import type { CameraSnapshot } from '../render-contract';
 import type { ExtractedCloudLayer } from './extract';
 
 /** Project the stable camera/world facts consumed by the cloud feature owner. */
 export function createCloudFeatureView(
   camera: CameraSnapshot | undefined,
-  worlds: readonly World[],
+  worlds: readonly RenderResourceScope[],
   cameraOwner: number,
   width: number,
   height: number,

package/src/device/gpu-residency.ts

@@ -1,3 +1,4 @@
+import type { RenderResourceScope } from '../publication/resource-scope';
 import { type MeshResidencyLease, MeshResidencyLifetime } from './mesh-residency-lifetime';
 // @forgeax/engine-runtime - GpuResidencyCache
 // (feat-20260601-device/gpu-residency-extraction M1; M2 added the deriveRenderData
@@ -37,7 +38,6 @@ import {
   type MipmapShaderModuleFactory,
   prepareMipmaps,
 } from '@forgeax/engine-assets-runtime';
-import type { World } from '@forgeax/engine-ecs';
 import { deriveVertexCount, type VertexLayoutProjection } from '@forgeax/engine-geometry';
 import { halfFloat } from '@forgeax/engine-math';
 import {
@@ -288,8 +288,9 @@ function makeImageError<C extends ImageErrorCode>(
 
 /** Cube-POD register-relay injected by the wire layer (D-3). */
 type RegisterCube = (
-  world: World,
+  world: RenderResourceScope,
   pod: EquirectAsset,
+  source: Handle<'EquirectAsset', 'shared'>,
 ) => Result<Handle<'EquirectAsset', 'shared'>, AssetError>;
 
 // feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle / M-3 / w11:
@@ -607,16 +608,16 @@ export class GpuResidencyCache {
   }
 
   /**
-   * Compose a cache key from the raw handle slot and its owning World. The
+   * Compose a cache key from the raw handle slot and its owning RenderResourceScope. The
    * draw-time world index is only a position in one frame's `worlds[]`; it is
-   * not an asset identity and can be reused by a later World. World objects
+   * not an asset identity and can be reused by a later RenderResourceScope. RenderResourceScope objects
    * therefore receive a renderer-local namespace, while numeric callers keep
    * the legacy namespace for low-level tests and built-in upload paths.
    */
-  private readonly worldNamespaces = new WeakMap<World, number>();
+  private readonly worldNamespaces = new WeakMap<RenderResourceScope, number>();
   private nextWorldNamespace = 1;
 
-  private worldKey(slot: number, world: World | number): string | number {
+  private worldKey(slot: number, world: RenderResourceScope | number): string | number {
     if (typeof world === 'number') {
       return world === 0 ? slot : world * 0x1000000 + slot;
     }
@@ -809,7 +810,7 @@ export class GpuResidencyCache {
    */
   evictTexture(
     handle: Handle<'TextureAsset', 'shared'>,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
   ): { freed: number; errors: RhiError[] } {
     const id = this.worldKey(handleSlot(handle), worldId);
     const entry = this.textureGpuHandles.get(id);
@@ -835,7 +836,7 @@ export class GpuResidencyCache {
 
   evictMesh(
     handle: Handle<'MeshAsset', 'shared'>,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
   ): { freed: number; errors: RhiError[] } {
     const id = this.worldKey(Number(handle), worldId);
     const entry = this.meshGpuHandles.get(id);
@@ -1000,7 +1001,7 @@ export class GpuResidencyCache {
    */
   _getTextureGpuTexture(
     handle: Handle<'TextureAsset', 'shared'>,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
   ): GpuTexture | undefined {
     return this.textureGpuHandles.get(this.worldKey(handleSlot(handle), worldId))?.texture;
   }
@@ -1011,7 +1012,7 @@ export class GpuResidencyCache {
    */
   getTextureGpuView(
     handle: Handle<'TextureAsset', 'shared'>,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
   ): TextureView | undefined {
     return this.textureGpuHandles.get(this.worldKey(handleSlot(handle), worldId))?.view;
   }
@@ -1024,7 +1025,7 @@ export class GpuResidencyCache {
   ensureSamplerResident(
     handle: Handle<'SamplerAsset', 'shared'>,
     pod: SamplerAsset,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
   ): Result<Sampler, RhiError> {
     const key = this.worldKey(handleSlot(handle), worldId);
     const existing = this.samplerGpuHandles.get(key);
@@ -1093,7 +1094,7 @@ export class GpuResidencyCache {
    */
   getMeshGpuHandles(
     handle: Handle<'MeshAsset', 'shared'>,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
   ): MeshGpuHandles | undefined {
     return this.meshGpuHandles.get(this.worldKey(Number(handle), worldId));
   }
@@ -1101,7 +1102,7 @@ export class GpuResidencyCache {
   /** Candidate leases retain the concrete allocation even after cache invalidation. */
   retainMeshResidency(
     handle: Handle<'MeshAsset', 'shared'>,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
   ): MeshResidencyLease | undefined {
     const key = this.worldKey(Number(handle), worldId);
     const entry = this.meshGpuHandles.get(key);
@@ -1114,7 +1115,7 @@ export class GpuResidencyCache {
   }
 
   /** In-place author changes immediately miss the cache; old submissions keep their allocation. */
-  invalidateMesh(handle: number, worldId: World | number = 0): void {
+  invalidateMesh(handle: number, worldId: RenderResourceScope | number = 0): void {
     const key = this.worldKey(handle, worldId);
     const entry = this.meshGpuHandles.get(key);
     if (entry !== undefined) this.retireMeshEntry(key, entry);
@@ -1137,18 +1138,18 @@ export class GpuResidencyCache {
   ensureResident(
     handle: Handle<'MeshAsset', 'shared'>,
     pod: TypesMeshAsset,
-    worldId?: World | number,
+    worldId?: RenderResourceScope | number,
     lodMeshes?: readonly TypesMeshAsset[],
   ): Result<MeshGpuHandles, RhiError | AssetError | ImageError>;
   ensureResident(
     handle: Handle<'TextureAsset', 'shared'>,
     pod: TextureAsset,
-    worldId?: World | number,
+    worldId?: RenderResourceScope | number,
   ): Result<TextureGpuEntry, RhiError | AssetError | ImageError>;
   ensureResident(
     handle: Handle<'MeshAsset', 'shared'> | Handle<'TextureAsset', 'shared'>,
     pod: TypesMeshAsset | TextureAsset,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
     lodMeshes: readonly TypesMeshAsset[] = [],
   ): Result<TextureGpuEntry | MeshGpuHandles, RhiError | AssetError | ImageError> {
     const id = handleSlot(handle);
@@ -1218,17 +1219,17 @@ export class GpuResidencyCache {
   prepareResidentForRecovery(
     handle: Handle<'MeshAsset', 'shared'>,
     pod: TypesMeshAsset,
-    worldId?: World | number,
+    worldId?: RenderResourceScope | number,
   ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError>;
   prepareResidentForRecovery(
     handle: Handle<'TextureAsset', 'shared'>,
     pod: TextureAsset,
-    worldId?: World | number,
+    worldId?: RenderResourceScope | number,
   ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError>;
   prepareResidentForRecovery(
     handle: Handle<'MeshAsset', 'shared'> | Handle<'TextureAsset', 'shared'>,
     pod: TypesMeshAsset | TextureAsset,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
   ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError> {
     const id = handleSlot(handle);
     if (pod.kind === 'mesh') {
@@ -1316,7 +1317,7 @@ export class GpuResidencyCache {
     handle: Handle<'TextureAsset', 'shared'>,
     pod: TextureAsset,
     decoded: DecodedImage,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
   ): Promise<Result<void, AssetError | ImageError | RhiError>> {
     const device = this.gpuDevice;
     const projected = deriveRenderDataTexture(pod);
@@ -1392,7 +1393,7 @@ export class GpuResidencyCache {
     pod: TextureAsset,
     decoded: DecodedImage,
     renderData: TextureRenderData,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
   ): Result<TextureGpuEntry, AssetError | ImageError | RhiError> {
     const device = this.gpuDevice;
     const prepared = this.prepareTextureUpload(handle, pod, decoded, renderData);
@@ -1654,7 +1655,7 @@ export class GpuResidencyCache {
    * retries by inferring "no entry => try again".
    */
   async _uploadCubemapFromEquirect(
-    world: World,
+    world: RenderResourceScope,
     sourceHandle: Handle<'EquirectAsset', 'shared'>,
     sourcePod: EquirectAsset,
   ): Promise<Result<Handle<'EquirectAsset', 'shared'>, AssetError | RhiError>> {
@@ -1999,7 +2000,7 @@ export class GpuResidencyCache {
       view: cubeView,
       faceViews,
     });
-    const regResult = registerCube(world, cubeAsset);
+    const regResult = registerCube(world, cubeAsset, sourceHandle);
     if (!regResult.ok) return recordFailed(regResult.error);
     const cubeHandle = regResult.value;
     const cubeId = handleSlot(cubeHandle);
@@ -2252,7 +2253,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'>,
     newVertices: Float32Array,
     newIndices: Uint16Array,
-    worldId: World | number = 0,
+    worldId: RenderResourceScope | number = 0,
     submeshes?: readonly Submesh[],
   ): void {
     const id = this.worldKey(handleSlot(handle), worldId);