@forgeax/engine-render 0.1.33 → 0.1.35

package/src/cloud/temporal.ts

@@ -0,0 +1,226 @@
+import type { CloudQuality } from '../components/cloud-layer';
+
+export type CloudTemporalResetReason =
+  | 'authoring-generation'
+  | 'camera-cut'
+  | 'resize'
+  | 'recovery'
+  | 'time-discontinuity'
+  | 'cloud-shadow-revision'
+  | 'device-generation'
+  | 'history-missing'
+  | 'reprojection-outside'
+  | 'scene-depth-disocclusion';
+
+export interface CloudTemporalSignature {
+  readonly sourceKey: string;
+  readonly viewId: string;
+  readonly authoringGeneration: number;
+  readonly cloudShadowRevision: number;
+  readonly cameraRevision: number;
+  readonly deviceGeneration: number;
+  readonly width: number;
+  readonly height: number;
+  readonly timeSeconds: number;
+  readonly quality: CloudQuality;
+  /** Scene-depth producer revision used to reject disoccluded history. */
+  readonly sceneDepthVersion?: number;
+}
+
+export interface CloudHistory {
+  readonly width: number;
+  readonly height: number;
+  readonly signature: string;
+  readonly temporal: CloudTemporalSignature;
+  readonly generation: number;
+  readonly valid: boolean;
+}
+
+export interface CloudTemporalDecision {
+  readonly reset: boolean;
+  readonly reasons: readonly CloudTemporalResetReason[];
+  readonly signature: string;
+  readonly history: CloudHistory | undefined;
+}
+
+export interface CloudTemporalFrame {
+  readonly signature: CloudTemporalSignature;
+  readonly history: CloudHistory | undefined;
+  readonly reset: boolean;
+  readonly reasons: readonly CloudTemporalResetReason[];
+}
+
+export interface CloudHistoryReprojectionInput {
+  readonly currentDepth: number;
+  readonly historyDepth: number;
+  readonly motion: readonly [number, number];
+  readonly currentPixel: readonly [number, number];
+  readonly historySize: readonly [number, number];
+  readonly depthTolerance?: number;
+}
+
+export interface CloudHistoryReprojection {
+  readonly accepted: boolean;
+  readonly historyUv: readonly [number, number];
+  readonly weight: number;
+  readonly reason: 'accepted' | 'outside' | 'depth-disocclusion';
+}
+
+export function cloudTemporalSignature(input: CloudTemporalSignature): string {
+  return [
+    'cloud-temporal-v1',
+    input.viewId,
+    input.sourceKey,
+    input.authoringGeneration,
+    input.cloudShadowRevision,
+    input.cameraRevision,
+    input.deviceGeneration,
+    input.width,
+    input.height,
+    input.timeSeconds,
+    input.quality,
+    input.sceneDepthVersion ?? 0,
+  ].join(':');
+}
+
+function sameLayout(left: CloudTemporalSignature, right: CloudTemporalSignature): boolean {
+  return left.viewId === right.viewId && left.width === right.width && left.height === right.height;
+}
+
+/** Compare the facts that make a cloud history safe to reuse. */
+export function cloudTemporalResetReasons(
+  previous: CloudTemporalSignature | undefined,
+  next: CloudTemporalSignature,
+  options: { readonly cameraCut?: boolean; readonly recovery?: boolean } = {},
+): readonly CloudTemporalResetReason[] {
+  if (previous === undefined) return ['history-missing'];
+  const reasons: CloudTemporalResetReason[] = [];
+  if (
+    previous.sourceKey !== next.sourceKey ||
+    previous.authoringGeneration !== next.authoringGeneration
+  ) {
+    reasons.push('authoring-generation');
+  }
+  if (previous.cloudShadowRevision !== next.cloudShadowRevision)
+    reasons.push('cloud-shadow-revision');
+  if (previous.deviceGeneration !== next.deviceGeneration) reasons.push('device-generation');
+  if (
+    previous.sceneDepthVersion !== undefined &&
+    next.sceneDepthVersion !== undefined &&
+    previous.sceneDepthVersion !== next.sceneDepthVersion
+  ) {
+    reasons.push('scene-depth-disocclusion');
+  }
+  if (!sameLayout(previous, next)) reasons.push('resize');
+  if (options.cameraCut === true || previous.cameraRevision !== next.cameraRevision)
+    reasons.push('camera-cut');
+  const dt = next.timeSeconds - previous.timeSeconds;
+  if (!Number.isFinite(dt) || dt < 0 || dt > 0.5) reasons.push('time-discontinuity');
+  if (options.recovery === true) reasons.push('recovery');
+  return Object.freeze(reasons);
+}
+
+export function createCloudHistory(
+  signature: CloudTemporalSignature,
+  generation: number,
+  valid = false,
+): CloudHistory {
+  return Object.freeze({
+    width: Math.max(1, Math.floor(signature.width)),
+    height: Math.max(1, Math.floor(signature.height)),
+    signature: cloudTemporalSignature(signature),
+    temporal: Object.freeze({ ...signature }),
+    generation,
+    valid,
+  });
+}
+
+/** Per-view histories are keyed by the renderer's view identity. */
+export class CloudHistoryStore {
+  private readonly maxViews: number;
+  private readonly entries = new Map<
+    string,
+    { readonly history: CloudHistory; readonly signature: CloudTemporalSignature }
+  >();
+
+  constructor(maxViews = 4) {
+    this.maxViews = Math.max(1, Math.floor(maxViews));
+  }
+
+  begin(
+    signature: CloudTemporalSignature,
+    options: { readonly cameraCut?: boolean; readonly recovery?: boolean } = {},
+  ): CloudTemporalDecision {
+    const key = signature.viewId;
+    const previousEntry = this.entries.get(key);
+    const previous = previousEntry?.history;
+    const reasons = cloudTemporalResetReasons(previousEntry?.signature, signature, options);
+    const reset = reasons.length > 0;
+    return Object.freeze({
+      reset,
+      reasons,
+      signature: cloudTemporalSignature(signature),
+      history: reset ? undefined : previous,
+    });
+  }
+
+  commit(signature: CloudTemporalSignature, history: CloudHistory): void {
+    if (
+      history.width !== Math.max(1, Math.floor(signature.width)) ||
+      history.height !== Math.max(1, Math.floor(signature.height))
+    ) {
+      this.entries.delete(signature.viewId);
+      return;
+    }
+    this.entries.set(signature.viewId, { history, signature: Object.freeze({ ...signature }) });
+    while (this.entries.size > this.maxViews) {
+      const oldest = this.entries.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.entries.delete(oldest);
+    }
+  }
+
+  reset(viewId?: string): void {
+    if (viewId === undefined) this.entries.clear();
+    else this.entries.delete(viewId);
+  }
+
+  get(viewId: string): CloudHistory | undefined {
+    return this.entries.get(viewId)?.history;
+  }
+
+  dispose(): void {
+    this.entries.clear();
+  }
+}
+
+/** Project one current pixel into the previous cloud history. */
+export function reprojectCloudHistory(
+  input: CloudHistoryReprojectionInput,
+  historyWeight = 0.9,
+): CloudHistoryReprojection {
+  const width = Math.max(1, input.historySize[0] ?? 1);
+  const height = Math.max(1, input.historySize[1] ?? 1);
+  const uv: [number, number] = [
+    ((input.currentPixel[0] ?? 0) - (input.motion[0] ?? 0)) / width,
+    ((input.currentPixel[1] ?? 0) - (input.motion[1] ?? 0)) / height,
+  ];
+  if (uv[0] < 0 || uv[0] > 1 || uv[1] < 0 || uv[1] > 1) {
+    return { accepted: false, historyUv: uv, weight: 0, reason: 'outside' };
+  }
+  const depthTolerance =
+    input.depthTolerance ?? Math.max(0.01, Math.abs(input.currentDepth) * 0.02);
+  if (
+    !Number.isFinite(input.currentDepth) ||
+    !Number.isFinite(input.historyDepth) ||
+    Math.abs(input.currentDepth - input.historyDepth) > depthTolerance
+  ) {
+    return { accepted: false, historyUv: uv, weight: 0, reason: 'depth-disocclusion' };
+  }
+  return {
+    accepted: true,
+    historyUv: uv,
+    weight: Math.min(0.99, Math.max(0, historyWeight)),
+    reason: 'accepted',
+  };
+}

package/src/components/barrel-distortion.ts

@@ -0,0 +1,46 @@
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { BarrelDistortionInvalidParameterError } from '../errors/render';
+
+/** Camera companion that applies the bounded first-order barrel model. */
+export const BarrelDistortion = defineComponent('BarrelDistortion', {
+  strength: { type: 'f32', default: 0 },
+  centerX: { type: 'f32', default: 0.5 },
+  centerY: { type: 'f32', default: 0.5 },
+});
+
+export type BarrelDistortionData = ShapeOf<SchemaOf<typeof BarrelDistortion>>;
+
+const DEFAULT_BARREL_DISTORTION: BarrelDistortionData = Object.freeze({
+  strength: 0,
+  centerX: 0.5,
+  centerY: 0.5,
+});
+
+function invalid(
+  field: 'strength' | 'centerX' | 'centerY',
+  value: number,
+  expected: string,
+): BarrelDistortionInvalidParameterError {
+  return new BarrelDistortionInvalidParameterError({ field, value, expected });
+}
+
+/** Validate and detach camera-owned barrel authoring data. */
+export function validateBarrelDistortionParameters(
+  input: Partial<BarrelDistortionData> | undefined,
+): Result<BarrelDistortionData, BarrelDistortionInvalidParameterError> {
+  const value = input ?? {};
+  const strength = value.strength ?? DEFAULT_BARREL_DISTORTION.strength;
+  const centerX = value.centerX ?? DEFAULT_BARREL_DISTORTION.centerX;
+  const centerY = value.centerY ?? DEFAULT_BARREL_DISTORTION.centerY;
+  if (!Number.isFinite(strength) || strength < 0 || strength > 0.35) {
+    return err(invalid('strength', strength, 'finite and in [0, 0.35]'));
+  }
+  if (!Number.isFinite(centerX) || centerX < 0 || centerX > 1) {
+    return err(invalid('centerX', centerX, 'finite and in [0, 1]'));
+  }
+  if (!Number.isFinite(centerY) || centerY < 0 || centerY > 1) {
+    return err(invalid('centerY', centerY, 'finite and in [0, 1]'));
+  }
+  return ok(Object.freeze({ strength, centerX, centerY }));
+}

package/src/components/cloud-layer.ts

@@ -0,0 +1,47 @@
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+
+/** Closed quality lane for the renderer-owned procedural cloud producer. */
+export type CloudQuality = 'low' | 'medium' | 'high';
+
+export const CloudQualityValue = Object.freeze({
+  low: 0,
+  medium: 1,
+  high: 2,
+} as const);
+
+/**
+ * A single World-authored cloud layer.
+ *
+ * The component contains only source facts. Cache resolution, optical step
+ * counts, temporal history and GPU handles are derived by Render and never
+ * written back into ECS.
+ */
+export const CloudLayer = defineComponent('CloudLayer', {
+  /** Stable integer seed for the periodic 3D density field. */
+  seed: { type: 'u32', default: 1337 },
+  /** World-space lower edge of the layer, in metres. */
+  baseHeight: { type: 'f32', default: 120 },
+  /** World-space thickness of the layer, in metres. */
+  thickness: { type: 'f32', default: 80 },
+  /** Horizontal noise scale, in cycles per metre. */
+  scale: { type: 'f32', default: 0.004 },
+  /** Coverage threshold in [0, 1]. */
+  coverage: { type: 'f32', default: 0.48 },
+  /** Extinction multiplier in inverse metres. */
+  density: { type: 'f32', default: 1 },
+  /** World-space wind velocity in metres per second. */
+  wind: { type: 'array<f32, 3>', default: new Float32Array([8, 0, 2]) },
+  /** Quality controls cache resolution and bounded ray steps. */
+  quality: { type: 'f32', default: CloudQualityValue.medium },
+  /** Maximum world-space distance represented by the light-space shadow map. */
+  shadowRange: { type: 'f32', default: 512 },
+});
+
+export type CloudLayerData = ShapeOf<SchemaOf<typeof CloudLayer>>;
+
+export function cloudQualityFromF32(value: number): CloudQuality | undefined {
+  if (value === CloudQualityValue.low) return 'low';
+  if (value === CloudQualityValue.medium) return 'medium';
+  if (value === CloudQualityValue.high) return 'high';
+  return undefined;
+}

package/src/components/index.ts

@@ -1,5 +1,7 @@
 export * from './atmosphere';
+export * from './barrel-distortion';
 export * from './camera';
+export * from './cloud-layer';
 export * from './cube-camera';
 export * from './depth-of-field';
 export * from './directional-light';

package/src/components/instances.ts

@@ -1,50 +1,23 @@
-// @forgeax/engine-render - renderer-owned large instance association.
-//
-// The ECS component deliberately carries only a stable collection identity.
-// Matrix bytes, revision, capacity, dirty ranges, GPU residency and fallback
-// policy belong to InstanceCollectionStore, exposed from the same Renderer.
-// This keeps large payloads out of the ECS managed BufferPool while retaining
-// ordinary query and entity-lifetime semantics.
-//
-// Authoring example:
-//
-//   const transforms = new Float32Array(instanceCount * 16);
-//   for (let index = 0; index < instanceCount; index += 1) {
-//     const offset = index * 16;
-//     transforms[offset] = 1;
-//     transforms[offset + 5] = 1;
-//     transforms[offset + 10] = 1;
-//     transforms[offset + 15] = 1;
-//   }
-//   const collection = renderer.instances.create({
-//     transforms,
-//   }).unwrap();
-//   world.spawn(
-//     { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
-//     { component: MeshRenderer, data: {} },
-//     { component: Instances, data: { collectionId: collection.collectionId } },
-//   );
-//
-// Updates stay on the renderer owner and publish one revision:
-//
-//   renderer.instances.update(collection.collectionId, {
-//     start: 12,
-//     transforms: patch,
-//   });
-//
-// Render extraction snapshots the validated packed column-major matrices once
-// per frame. Direct, GPU-driven and fallback lanes consume that same detached
-// projection; callers never split one logical collection into ECS chunks.
-
 import { defineComponent } from '@forgeax/engine-ecs';
-import type { InstanceCollectionData } from '../instances';
 
-/** Per-entity association with a renderer-owned instance collection. */
+/**
+ * World-owned local transforms for one explicit instanced renderable.
+ * Packed column-major mat4 values compose as entityWorld * instanceLocal.
+ * ECS owns copying, mutation and entity lifetime, including large arrays.
+ * Renderer extraction derives its own snapshot and GPU residency; neither
+ * authoring nor glTF SceneAsset lowering requires a Renderer identity.
+ *
+ * @example
+ * const transforms = new Float32Array(20_000 * 16);
+ * for (let i = 0; i < 20_000; i++) {
+ *   transforms[i * 16] = transforms[i * 16 + 5] =
+ *     transforms[i * 16 + 10] = transforms[i * 16 + 15] = 1;
+ * }
+ * const entity = world.spawn({ component: Instances, data: { transforms } }).unwrap();
+ * world.set(entity, Instances, { transforms }).unwrap();
+ */
 export const Instances = defineComponent('Instances', {
-  collectionId: { type: 'u32', default: 0 },
+  transforms: { type: 'array<f32>' },
 });
 
-/** Type-level hint for the `data` object at the Instances spawn site. */
-export type InstancesData = InstanceCollectionData;
-
-export type { InstanceCollectionId } from '../instances';
+export type InstancesData = { readonly transforms: Float32Array };

package/src/components/sprite-instances.ts

@@ -41,7 +41,7 @@
 //   composes per instance:
 //     world_position[i] = entity_world * instances_local[i] * vertex_position
 //   `SpriteInstances.transforms[i*16..i*16+15]` is interpreted as a local-
-//   space transform under the entity, matching the 3D collection projection.
+//   space transform under the entity, exactly like `Instances.transforms`.
 //   Set the entity's `Transform` to identity to make `instances_local[i]`
 //   directly world-space.
 //

package/src/construct-renderer.ts

@@ -14,7 +14,7 @@ export type {
   RhiBackendInstrumentation,
   RhiBackendPack,
 } from './assembly/backend-contract';
-export { EngineEnvironmentError } from './assembly/backend-contract';
+export { EngineEnvironmentError, loadRhiPack } from './assembly/backend-contract';
 export type { RendererLegacyHostAdapter } from './assembly/host-contract';
 export type { BundlerOptions };
 

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/dynamic-geometry.ts

@@ -53,6 +53,9 @@ export interface DynamicGeometryCandidate {
   readonly state: DynamicGeometryCandidateState;
 }
 
+/** Record-stage lane that consumed a published dynamic-geometry candidate. */
+export type DynamicGeometryRecordStageLane = 'cpu' | 'gpu' | 'mixed';
+
 /** Receipt that ties candidate publication to the sole Renderer FrameReceipt. */
 export interface DynamicGeometryReceipt {
   readonly candidateId: string;
@@ -69,6 +72,8 @@ export interface DynamicGeometryReceipt {
   };
   /** Whether the Renderer record stage consumed this candidate for this frame. */
   readonly recordStageConsumed: boolean;
+  /** Lane evidence from the exact submitted record stage, when attached. */
+  readonly recordStageLane?: DynamicGeometryRecordStageLane;
   /** Actual frame fixed step; may be newer than the preparation step. */
   readonly publicationFixedStep?: number;
 }
@@ -271,6 +276,9 @@ export interface DynamicGeometryLifecycle {
     worlds?: readonly object[],
     fixedStep?: number,
     canPublish?: (candidate: DynamicGeometryCandidate) => boolean,
+    recordStageLane?: (
+      candidate: DynamicGeometryCandidate,
+    ) => DynamicGeometryRecordStageLane | undefined,
   ): readonly DynamicGeometryReceipt[];
   invalidateWorld(world: object, completion?: Promise<unknown>): void;
   invalidateGeneration(generation: number): void;
@@ -610,7 +618,7 @@ export function createDynamicGeometryLifecycle(
       meshBytes = Math.max(0, meshBytes - record.candidate.meshBytes);
       return ok(undefined);
     },
-    publishFrame(frame, worlds, fixedStep, canPublish) {
+    publishFrame(frame, worlds, fixedStep, canPublish, recordStageLane) {
       if (disposed || frame.deviceGeneration !== currentGeneration) return [];
       const receipts: DynamicGeometryReceipt[] = [];
       for (const record of records.values()) {
@@ -630,6 +638,8 @@ export function createDynamicGeometryLifecycle(
           continue;
         }
         if (canPublish !== undefined && !canPublish(record.candidate)) continue;
+        const consumedLane =
+          canPublish === undefined ? undefined : recordStageLane?.(record.candidate);
         record.candidate = Object.freeze({ ...record.candidate, state: 'published' as const });
         const receipt = Object.freeze({
           candidateId: record.candidate.candidateId,
@@ -642,6 +652,7 @@ export function createDynamicGeometryLifecycle(
           frameId: frame.frameId,
           deviceGeneration: frame.deviceGeneration,
           recordStageConsumed: canPublish !== undefined,
+          ...(consumedLane === undefined ? {} : { recordStageLane: consumedLane }),
           ...(fixedStep === undefined ? {} : { publicationFixedStep: fixedStep }),
           frame: Object.freeze({ ...frame }),
         });