@forgeax/engine-render 0.1.34 → 0.1.36

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'];
@@ -564,6 +570,8 @@ async function makeWebGPURenderer(
   const getShader = (): ShaderCatalog => {
     const state = candidateShaderState ?? activeShaderState;
     if (state.shaderInstance === null) {
+      const activeCatalog = activeShaderState.shaderInstance;
+      // Reuse validated manifest CPU rows; candidate preparation selects variants.
       // feat-20260608-create-app-param-surface-trim / M2 / D-2 q5-A:
       // shaderManifestUrl moved to BundlerOptions (third arg). The fallback
       // literal '/shaders/manifest.json' stays here so the LO 1.1
@@ -572,39 +580,20 @@ async function makeWebGPURenderer(
       // the zero-entry opt-in: explicitly passing
       // `bundler: { shaderManifestUrl: undefined }` retains the
       // old "no manifest fetched" mode used by tests / camera-only worlds.
-      const bundler = internals.bundler;
-      const explicitUrl = bundler?.shaderManifestUrl;
-      state.shaderInstance = new ShaderCatalog({
-        device: getShaderModuleAdapter(),
-        manifestUrl:
-          bundler !== undefined && 'shaderManifestUrl' in bundler
-            ? explicitUrl
-            : '/shaders/manifest.json',
-      });
+      state.shaderInstance =
+        state === candidateShaderState && activeCatalog !== null
+          ? activeCatalog.forkForDevice(getShaderModuleAdapter())
+          : new ShaderCatalog({
+              device: getShaderModuleAdapter(),
+              manifestUrl:
+                internals.bundler !== undefined && 'shaderManifestUrl' in internals.bundler
+                  ? internals.bundler.shaderManifestUrl
+                  : '/shaders/manifest.json',
+            });
     }
     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 +724,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 +2553,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 +2589,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 +2847,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 +2878,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 +3081,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 +3172,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 +3255,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 +3278,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 +3336,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 +3541,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 +3787,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 +3798,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/assembly/webgpu-vertex-layouts.ts

@@ -8,6 +8,7 @@ import {
   type VertexLayoutProjection,
 } from '@forgeax/engine-geometry';
 import type { VertexAttributeMap } from '@forgeax/engine-types';
+import { PARTICLE_MESH_VERTEX_BUFFER } from '../features/particle-mesh-layout';
 import { RENDER_FEATURE_VERTEX_LAYOUTS } from '../features/prepared-graphics';
 
 type FeatureFloatVertexFormat = 'float32x2' | 'float32x3' | 'float32x4';
@@ -101,14 +102,6 @@ const MESH_GEOMETRY_MATERIAL_INSTANCE_SPEC = {
 export const PREPARED_INSTANCE_VERTEX_ATTRS = buildMeshAttributeMapForUvSets(2);
 export const PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS = SKIN_VERTEX_ATTRIBUTE_MAP;
 
-function canonicalMeshVertexBufferLayout(): GPUVertexBufferLayout {
-  const [buffer] = toGpuVertexBufferLayouts(deriveVertexBufferLayout(DEFAULT_VERTEX_ATTRIBUTE_MAP));
-  if (buffer === undefined) {
-    throw new Error('The canonical mesh vertex layout must contain one vertex buffer');
-  }
-  return { ...buffer, stepMode: 'vertex' };
-}
-
 export const POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS = [
   defineFeatureVertexBuffer(POSITION_SIZE_COLOR_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
@@ -127,7 +120,7 @@ export const TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS = [
  * particle transform/material data rather than MeshAsset attributes.
  */
 export const MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
-  canonicalMeshVertexBufferLayout(),
+  PARTICLE_MESH_VERTEX_BUFFER,
   defineFeatureVertexBuffer(MESH_GEOMETRY_MATERIAL_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
 

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/device-scope.ts

@@ -176,6 +176,7 @@ export class DeviceScope {
     this.clearChildren();
     this._clearResources();
     this.lifecycleState = 'retired';
+    this.parent?.detachChild(this);
   }
 
   abandon(): void {
@@ -183,6 +184,7 @@ export class DeviceScope {
     this.lifecycleState = 'abandoned';
     this.clearChildren();
     this._clearResources();
+    this.parent?.detachChild(this);
   }
 
   dispose(): void {
@@ -190,6 +192,7 @@ export class DeviceScope {
     this.lifecycleState = 'disposed';
     this.clearChildren();
     this._clearResources();
+    this.parent?.detachChild(this);
   }
 
   async replace(

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);

package/src/errors/render.ts

@@ -1,3 +1,4 @@
+import type { RenderPublicationError } from '../publication/contract';
 // @forgeax/engine-render -- render cluster error classes.
 //
 // feat-20260704-runtime-tier1-decomposition M2 / w8 (D-3): the monolithic
@@ -562,7 +563,7 @@ export class PointShadowAtlasBoundsViolationError extends Error {
  * Fired by the per-frame record stage (`videoTextureView`) when a VideoPlayer
  * entity can reach neither video upload path this frame: the general
  * `copyExternalImageToTexture` path (no host HTMLVideoElement resolved via
- * `VideoElementProvider`) AND the high-perf `GPUExternalTexture` path
+ * `VideoSourceProvider`) AND the high-perf `GPUExternalTexture` path
  * (capability absent). The engine surfaces this explicit failure rather than
  * silently rendering a stale/garbage texture (charter P3, plan-strategy D-6).
  *   - `.code = 'video-upload-unsupported'`
@@ -1980,6 +1981,7 @@ export type RenderErrorCode = RenderError['code'];
  * `RenderErrorCode` discriminant on `.code`.
  */
 export type RenderError =
+  | RenderPublicationError
   | LifecycleConstructionError
   | AutoExposureError
   | RendererExpectedOperationError

package/src/extract/material-context.ts

@@ -0,0 +1,21 @@
+import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
+import type { RhiCaps } from '@forgeax/engine-rhi';
+
+/** The receiving device selects the immutable material program domain. */
+export function renderMaterialContext(caps: Pick<RhiCaps, 'backendKind' | 'storageBuffer'>): {
+  readonly materialContext?: MaterialCookProgramContext;
+} {
+  if (caps.backendKind === 'null') return {};
+  return {
+    materialContext: {
+      backend: caps.backendKind === 'wgpu-webgl2' ? 'webgl2' : caps.backendKind,
+      capability: caps.storageBuffer ? 'storage-buffer' : 'uniform-fallback',
+      pipeline: 'forward',
+      geometry: 'mesh',
+      pass: 'forward',
+      profile: 'forgeax-material-wgsl-v1',
+      toolchain: 'naga-oil',
+      instrumentation: 'none',
+    },
+  };
+}