@forgeax/engine-render 0.1.23 → 0.1.24

package/src/components/camera.ts

@@ -14,7 +14,7 @@
 //                      outside M3 scope — the short-name mat4.perspective
 //                      already writes [0, 1] NDC, matching the ortho branch.
 //   projection === 1 → orthographic path; RenderSystem builds
-//                      mat4.orthographic(out, left, right, bottom, top,
+//                      mat4.orthographic(out, left, right, top, bottom,
 //                      near, far) (WebGPU [0, 1] NDC; same z convention).
 //
 // Naming convention: forgeax uses the bare `Camera` name (no `Component`

package/src/debug-draw-glue.ts

@@ -23,8 +23,8 @@ export function addTypedDebugOverlayPass(
           projection,
           frame.camera.orthoLeft,
           frame.camera.orthoRight,
-          frame.camera.orthoBottom,
           frame.camera.orthoTop,
+          frame.camera.orthoBottom,
           frame.camera.near,
           frame.camera.far,
         );

package/src/device/device-scope.ts

@@ -46,6 +46,17 @@ interface OwnedResource {
   readonly cleanup: (value: unknown) => void | Promise<void>;
 }
 
+function idempotentCleanup<T>(
+  cleanup: (value: T) => void | Promise<void>,
+): (value: T) => void | Promise<void> {
+  let cleaned = false;
+  return (value: T) => {
+    if (cleaned) return;
+    cleaned = true;
+    return cleanup(value);
+  };
+}
+
 export class DeviceScope {
   readonly generation: number;
   readonly owner: string;
@@ -117,7 +128,7 @@ export class DeviceScope {
     const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
     this.resources.push({
       ref: ref as DeviceResourceRef<unknown>,
-      cleanup: cleanup as (resource: unknown) => void | Promise<void>,
+      cleanup: idempotentCleanup(cleanup) as (resource: unknown) => void | Promise<void>,
     });
     return ref;
   }
@@ -142,9 +153,21 @@ export class DeviceScope {
     if (this.lifecycleState === 'active') this.lifecycleState = 'retiring';
   }
 
+  private clearChildren(): void {
+    for (const child of [...this.children].reverse()) {
+      child.retire();
+    }
+  }
+
+  private detachChild(child: DeviceScope): void {
+    const index = this.children.indexOf(child);
+    if (index >= 0) this.children.splice(index, 1);
+  }
+
   retire(): void {
     if (this.lifecycleState !== 'active' && this.lifecycleState !== 'retiring') return;
     this.lifecycleState = 'retiring';
+    this.clearChildren();
     this._clearResources();
     this.lifecycleState = 'retired';
   }
@@ -152,12 +175,14 @@ export class DeviceScope {
   abandon(): void {
     if (this.lifecycleState !== 'active') return;
     this.lifecycleState = 'abandoned';
+    this.clearChildren();
     this._clearResources();
   }
 
   dispose(): void {
     if (this.lifecycleState === 'disposed') return;
     this.lifecycleState = 'disposed';
+    this.clearChildren();
     this._clearResources();
   }
 
@@ -177,6 +202,9 @@ export class DeviceScope {
       replacement.dispose();
       return transaction.failure('dispose');
     }
+    // The replacement is now the new owner. Detach it before retiring the
+    // old parent so parent cleanup cannot retire the just-published child.
+    this.detachChild(replacement);
     this.retire();
     return ok(replacement);
   }
@@ -217,6 +245,7 @@ export interface LifecycleTransactionOptions {
 interface CreatedResource {
   readonly spec: LifecycleResourceSpec<unknown>;
   readonly value: unknown;
+  readonly cleanup: (value: unknown) => void | Promise<void>;
 }
 
 export class LifecycleTransaction {
@@ -250,10 +279,10 @@ export class LifecycleTransaction {
         }
         const value = await spec.create();
         if (!this.scope.isAlive()) {
-          await this.cleanupOne(spec, value, created);
+          await this.cleanupOne(value, created, idempotentCleanup(spec.cleanup));
           return this.failure('dispose');
         }
-        created.push({ spec, value });
+        created.push({ spec, value, cleanup: idempotentCleanup(spec.cleanup) });
       } catch (cause) {
         const cleanupFailures = await this.cleanupCreated(created);
         return this.failure('create', spec.kind, cleanupFailures, cause);
@@ -296,7 +325,7 @@ export class LifecycleTransaction {
       const item = created[index];
       if (item === undefined) continue;
       try {
-        await item.spec.cleanup(item.value);
+        await item.cleanup(item.value);
       } catch (cause) {
         failures.push({ resourceKind: item.spec.kind, cause });
       }
@@ -305,13 +334,13 @@ export class LifecycleTransaction {
   }
 
   private async cleanupOne(
-    spec: LifecycleResourceSpec<unknown>,
     value: unknown,
     created: readonly CreatedResource[],
+    cleanup: (value: unknown) => void | Promise<void>,
   ): Promise<void> {
     await this.cleanupCreated(created);
     try {
-      await spec.cleanup(value);
+      await cleanup(value);
     } catch {
       // The terminal dispose result is intentionally bounded; prior cleanup
       // evidence remains in the transaction failure shape.

package/src/device/gpu-residency.ts

@@ -32,7 +32,9 @@
 import {
   blitMipmapsSync,
   getOrCreateMipmapPipeline,
+  type MipmapEncoderWork,
   type MipmapShaderModuleFactory,
+  prepareMipmaps,
 } from '@forgeax/engine-assets-runtime';
 import type { World } from '@forgeax/engine-ecs';
 import {
@@ -98,6 +100,7 @@ import {
   runIblPrecompute,
 } from '../ibl/IblPipelineCache';
 import type { RhiErrorListenerRegistry } from '../lifecycle';
+import type { RecoveryColdWorkGuard } from '../record/render-context';
 import {
   type CubeRenderData,
   deriveRenderDataCubemap,
@@ -106,7 +109,7 @@ import {
   type MeshRenderData,
   type TextureRenderData,
 } from '../render-data';
-import type { DeviceScope } from './device-scope';
+import type { DeviceScope, LifecycleResourceSpec } from './device-scope';
 
 const DYNAMIC_OFFSET_STRIDE = 256;
 const FACE_COUNT = 6;
@@ -182,6 +185,7 @@ export function writePrefilterUniforms(
   subPassIdx: number,
   roughness: number,
   mipFaceSize: number,
+  sourceMipLevelCount = 1,
 ): Result<void, RhiError> {
   if (subPassIdx < 0 || subPassIdx >= PREFILTER_SUBPASS_COUNT) {
     return invalidUniformInput(
@@ -189,13 +193,20 @@ export function writePrefilterUniforms(
       `writePrefilterUniforms received subPassIdx=${subPassIdx}`,
     );
   }
-  const payload = new Float32Array([roughness, mipFaceSize, 0, 0]);
+  if (!Number.isInteger(sourceMipLevelCount) || sourceMipLevelCount < 1) {
+    return invalidUniformInput(
+      'sourceMipLevelCount is a positive integer matching the bound source cube mip levels',
+      `writePrefilterUniforms received sourceMipLevelCount=${sourceMipLevelCount}`,
+    );
+  }
+  const payload = new Float32Array([roughness, mipFaceSize, sourceMipLevelCount, 0]);
   return device.queue.writeBuffer(buffer, subPassIdx * DYNAMIC_OFFSET_STRIDE, payload);
 }
 
 export function writeAllPrefilterUniforms(
   device: FaceUniformsDevice,
   buffer: Buffer,
+  sourceMipLevelCount = 1,
 ): Result<void, RhiError> {
   for (let mip = 0; mip < PREFILTER_MIP_LEVELS; mip++) {
     const roughness = mip / (PREFILTER_MIP_LEVELS - 1);
@@ -207,6 +218,7 @@ export function writeAllPrefilterUniforms(
         mip * FACE_COUNT + face,
         roughness,
         mipFaceSize,
+        sourceMipLevelCount,
       );
       if (!result.ok) return result;
     }
@@ -303,6 +315,11 @@ export interface TextureGpuEntry {
   readonly receipt: TextureResidencyReceipt;
 }
 
+/** Candidate-only residency work; no queue submission is hidden here. */
+export interface RecoveryResidencyPreparation {
+  readonly mipmapWork?: MipmapEncoderWork;
+}
+
 // feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M2 / w11
 // (D-3): the projection-status truth lives here (the store's cubemap map is the
 // single authority — the SkylightSnapshot carries no status, D-3). `status`:
@@ -529,6 +546,7 @@ export class GpuResidencyCache {
   // Hardware-probe caps injected at `configureGpuDevice`; guards the HDR cubemap
   // path (_uploadCubemapFromEquirect) when `rgba16floatRenderable` is false.
   private caps: RhiCaps | undefined = undefined;
+  private recoveryColdWorkGuard: RecoveryColdWorkGuard | undefined;
   private deviceEpoch = 0;
   private textureGeneration = 0;
 
@@ -607,6 +625,11 @@ export class GpuResidencyCache {
     this.deviceScope = scope;
   }
 
+  /** Arm the first-published-frame assertion on this generation's store. */
+  setRecoveryColdWorkGuard(guard: RecoveryColdWorkGuard | undefined): void {
+    this.recoveryColdWorkGuard = guard;
+  }
+
   /**
    * Wrap a raw RHI Buffer handle into a GpuBuffer. The wrapper holds a
    * reference to the device so `.destroy()` forwards to
@@ -695,6 +718,39 @@ export class GpuResidencyCache {
     this.meshGpuHandles.clear();
   }
 
+  /** Number of candidate-owned GPU resources currently held by this cache. */
+  recoveryResourceCount(): number {
+    let cubemapResources = 0;
+    const seen = new Set<GpuTexture>();
+    for (const entry of this.cubemapGpuHandles.values()) {
+      if (entry.texture !== null && !seen.has(entry.texture)) {
+        seen.add(entry.texture);
+        cubemapResources += 1;
+      }
+    }
+    return (
+      this.meshGpuHandles.size +
+      this.textureGpuHandles.size +
+      this.samplerGpuHandles.size +
+      cubemapResources
+    );
+  }
+
+  /** Candidate root for the cache owner, not a scalar readiness marker. */
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown> {
+    return {
+      kind: 'texture',
+      create: () => {
+        if (!scope.isAlive()) throw new Error('GPU residency candidate scope is not active.');
+        if (this.recoveryResourceCount() === 0) {
+          throw new Error('GPU residency candidate has no prepared resources.');
+        }
+        return this;
+      },
+      cleanup: () => undefined,
+    };
+  }
+
   /**
    * Set the error registry channel (wired by createRenderer). evict /
    * releaseUnreferenced fire structured errors here instead of throwing -
@@ -970,6 +1026,7 @@ export class GpuResidencyCache {
     const key = this.worldKey(handleSlot(handle), worldId);
     const existing = this.samplerGpuHandles.get(key);
     if (existing !== undefined) return ok(existing);
+    this.recoveryColdWorkGuard?.noteUploadColdWork();
     const device = this.gpuDevice;
     if (device === undefined) {
       return err(
@@ -1102,6 +1159,7 @@ export class GpuResidencyCache {
         const key = this.worldKey(id, worldId);
         const existing = this.meshGpuHandles.get(key);
         if (existing !== undefined) return ok(existing);
+        this.recoveryColdWorkGuard?.noteUploadColdWork();
         const projected = deriveRenderDataMesh(pod);
         if (!projected.ok) return projected;
         return this.uploadMeshById(key, pod, projected.value, lodMeshes);
@@ -1110,6 +1168,7 @@ export class GpuResidencyCache {
         const texKey = this.worldKey(id, worldId);
         const existing = this.textureGpuHandles.get(texKey);
         if (existing !== undefined) return ok(existing);
+        this.recoveryColdWorkGuard?.noteUploadColdWork();
         const projected = deriveRenderDataTexture(pod);
         if (!projected.ok) return projected;
         const decoded: DecodedImage = decodedFromTexture(pod);
@@ -1124,6 +1183,101 @@ export class GpuResidencyCache {
     }
   }
 
+  /**
+   * Prepare one candidate-visible resource without the normal draw-time mip
+   * submission. Base writes and resource creation stay owned by this cache;
+   * generated mip passes are returned to the recovery transaction for one
+   * explicit finish/submit before publication.
+   */
+  prepareResidentForRecovery(
+    handle: Handle<'MeshAsset', 'shared'>,
+    pod: TypesMeshAsset,
+    worldId?: World | number,
+  ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError>;
+  prepareResidentForRecovery(
+    handle: Handle<'TextureAsset', 'shared'>,
+    pod: TextureAsset,
+    worldId?: World | number,
+  ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError>;
+  prepareResidentForRecovery(
+    handle: Handle<'MeshAsset', 'shared'> | Handle<'TextureAsset', 'shared'>,
+    pod: TypesMeshAsset | TextureAsset,
+    worldId: World | number = 0,
+  ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError> {
+    const id = handleSlot(handle);
+    if (pod.kind === 'mesh') {
+      const key = this.worldKey(id, worldId);
+      if (this.meshGpuHandles.has(key)) return ok({});
+      const projected = deriveRenderDataMesh(pod);
+      if (!projected.ok) return projected;
+      const uploaded = this.uploadMeshById(key, pod, projected.value);
+      return uploaded.ok ? ok({}) : uploaded;
+    }
+
+    const cacheKey = this.worldKey(id, worldId);
+    if (this.textureGpuHandles.has(cacheKey)) return ok({});
+    const projected = deriveRenderDataTexture(pod);
+    if (!projected.ok) return projected;
+    const decoded = decodedFromTexture(pod);
+    const prepared = this.prepareTextureUpload(
+      handle as Handle<'TextureAsset', 'shared'>,
+      pod,
+      decoded,
+      projected.value,
+    );
+    if (!prepared.ok) return prepared;
+    const device = this.gpuDevice;
+    const gpuTexture = prepared.value.gpuTexture;
+    if (device === undefined || gpuTexture === undefined) {
+      return err(
+        new RhiError({
+          code: 'rhi-not-available',
+          expected: 'GpuResidencyCache.configureGpuDevice wired before recovery residency',
+          hint: 'configure the candidate store before preparing recovery resources',
+        }),
+      );
+    }
+
+    let mipmapWork: MipmapEncoderWork | undefined;
+    if (!projected.value.compressed && pod.mips.kind === 'generate' && prepared.value.levels > 1) {
+      const preparedMipmaps = prepareMipmaps(device, gpuTexture, {
+        format: projected.value.format,
+        width: pod.shape.extent.width,
+        height: pod.shape.extent.height,
+        levels: prepared.value.levels,
+      });
+      if (!preparedMipmaps.ok) {
+        new GpuTexture(device, gpuTexture).destroy();
+        return preparedMipmaps;
+      }
+      mipmapWork = preparedMipmaps.value;
+    }
+    const viewRes = device.createTextureView(gpuTexture, {
+      label: `texture-view-${cacheKey}`,
+      dimension: projected.value.shape.viewDimension,
+    });
+    if (!viewRes.ok) {
+      new GpuTexture(device, gpuTexture).destroy();
+      return viewRes;
+    }
+    const previous = this.textureGpuHandles.get(cacheKey);
+    const entry: TextureGpuEntry = {
+      texture: this.wrapTex(gpuTexture),
+      view: viewRes.value,
+      receipt: this.textureReceipt(pod, projected.value),
+    };
+    this.textureGpuHandles.set(cacheKey, entry);
+    this.materialResourceEpoch += 1;
+    if (
+      previous !== undefined &&
+      previous.texture !== entry.texture &&
+      !previous.texture.isDestroyed
+    ) {
+      previous.texture.destroy();
+    }
+    return ok(mipmapWork === undefined ? {} : { mipmapWork });
+  }
+
   /**
    * Eager public surface: upload decoded image bytes into a GPU texture and
    * cache (texture + view) under the handle. The TextureAsset POD supplies the
@@ -1618,6 +1772,7 @@ export class GpuResidencyCache {
     // universally renderable rgba8 path; the same format is threaded through
     // the cubemap and all three IBL side textures by IblPipelineCache.
     const outputFormat = this.caps?.rgba16floatRenderable === false ? 'rgba8unorm' : tex.format;
+    const sourceMipLevelCount = 1;
 
     // Lazy projection runs from the record arm, where the RHI device is always
     // wired (research R-5). The IBL path is deliberately independent from the
@@ -1643,7 +1798,7 @@ export class GpuResidencyCache {
     const gpuTextureResult = device.createTexture({
       label: `cubemap-${sourceId}`,
       size: { width: cubeFaceSize, height: cubeFaceSize, depthOrArrayLayers: 6 },
-      mipLevelCount: 1,
+      mipLevelCount: sourceMipLevelCount,
       sampleCount: 1,
       dimension: '2d',
       format: outputFormat,
@@ -1682,13 +1837,6 @@ export class GpuResidencyCache {
     // surfacing exactly one destroy call per physical resource.
     const gpuTextureWrapper = this.wrapTex(gpuTexture);
 
-    this.cubemapGpuHandles.set(sourceId, {
-      status: 'ready',
-      texture: gpuTextureWrapper,
-      view: cubeView,
-      faceViews,
-    });
-
     // The minted cubemap handle is a synthetic shared ref (identity token for
     // the GPU cube residency); its POD is an EquirectAsset placeholder matching
     // the projected dimensions/format (D-3: the retired cube-texture asset kind
@@ -1701,20 +1849,6 @@ export class GpuResidencyCache {
       data: tex.data,
       colorSpace: 'linear',
     };
-    const regResult = registerCube(world, cubeAsset);
-    if (!regResult.ok) return recordFailed(regResult.error);
-    const cubeHandle = regResult.value;
-    const cubeId = handleSlot(cubeHandle);
-
-    this.cubemapGpuHandles.set(cubeId, {
-      status: 'ready',
-      texture: gpuTextureWrapper,
-      view: cubeView,
-      faceViews,
-    });
-
-    this.cubemapIdempotentMap.set(sourceId, cubeHandle);
-
     const pipelinesResult = await createIblPipelines(
       scope,
       device,
@@ -1748,6 +1882,9 @@ export class GpuResidencyCache {
     });
     if (!equirectTextureResult.ok) return recordFailed(equirectTextureResult.error);
     const equirectGpuTex = equirectTextureResult.value;
+    scope._adopt('texture', equirectGpuTex, (texture) => {
+      device.destroyTexture(texture);
+    });
 
     const equirectViewResult = device.createTextureView(equirectGpuTex, {
       label: `equirect-view-${sourceId}`,
@@ -1775,9 +1912,15 @@ export class GpuResidencyCache {
     const faceBufferResult = createFaceUniformsBuffer(device);
     if (!faceBufferResult.ok) return recordFailed(faceBufferResult.error);
     const faceBuf = faceBufferResult.value;
+    scope._adopt('buffer', faceBuf, (buffer) => {
+      device.destroyBuffer(buffer);
+    });
     const prefilterBufferResult = createPrefilterUniformsBuffer(device);
     if (!prefilterBufferResult.ok) return recordFailed(prefilterBufferResult.error);
     const prefBuf = prefilterBufferResult.value;
+    scope._adopt('buffer', prefBuf, (buffer) => {
+      device.destroyBuffer(buffer);
+    });
 
     const cubeVertexResult = device.createBuffer({
       label: 'ibl-cube-verts',
@@ -1787,15 +1930,18 @@ export class GpuResidencyCache {
     });
     if (!cubeVertexResult.ok) return recordFailed(cubeVertexResult.error);
     const cubeVertex = cubeVertexResult.value;
+    scope._adopt('buffer', cubeVertex, (buffer) => {
+      device.destroyBuffer(buffer);
+    });
 
     const cubeVertexWriteResult = device.queue.writeBuffer(cubeVertex, 0, CUBEMAP_FACE_VERTICES);
     if (!cubeVertexWriteResult.ok) return recordFailed(cubeVertexWriteResult.error);
     const faceUniformsResult = writeAllFaceUniforms(device, faceBuf);
     if (!faceUniformsResult.ok) return recordFailed(faceUniformsResult.error);
-    const prefilterUniformsResult = writeAllPrefilterUniforms(device, prefBuf);
+    const prefilterUniformsResult = writeAllPrefilterUniforms(device, prefBuf, sourceMipLevelCount);
     if (!prefilterUniformsResult.ok) return recordFailed(prefilterUniformsResult.error);
 
-    const runResult = runIblPrecompute({
+    const runResult = await runIblPrecompute({
       scope,
       device,
       equirectGpuTex,
@@ -1817,6 +1963,28 @@ export class GpuResidencyCache {
       );
     }
 
+    // A source becomes visible to the record arm only after all four passes
+    // completed their queue fence. Registration and the idempotent map are
+    // publication, not allocation, so a failed precompute cannot expose a
+    // ready cube or a loadable handle.
+    this.cubemapGpuHandles.set(sourceId, {
+      status: 'ready',
+      texture: gpuTextureWrapper,
+      view: cubeView,
+      faceViews,
+    });
+    const regResult = registerCube(world, cubeAsset);
+    if (!regResult.ok) return recordFailed(regResult.error);
+    const cubeHandle = regResult.value;
+    const cubeId = handleSlot(cubeHandle);
+    this.cubemapGpuHandles.set(cubeId, {
+      status: 'ready',
+      texture: gpuTextureWrapper,
+      view: cubeView,
+      faceViews,
+    });
+    this.cubemapIdempotentMap.set(sourceId, cubeHandle);
+
     return ok(cubeHandle);
   }
 

package/src/environment/frame.ts

@@ -12,6 +12,12 @@ import { environmentFactSignatures } from './signature';
 
 export type { EnvironmentCandidate, EnvironmentFrame, EnvironmentSource, FogCandidate, FogFrame };
 
+/** Producer-local fallback while replacement environment storage is uninitialized. */
+export const SKYLIGHT_RECOVERY_FALLBACK = Object.freeze({
+  kind: 'skylight',
+  active: false,
+} as const);
+
 export interface SunCandidate {
   readonly entityKey: number;
   readonly direction: readonly [number, number, number];

package/src/environment/inspection.ts

@@ -38,6 +38,14 @@ export interface EnvironmentInspection {
   readonly residentBytes: number;
   readonly retiringBytes: number;
   readonly lastCandidateFailure: EnvironmentInspectionFailure | undefined;
+  readonly recovery:
+    | {
+        readonly token: number;
+        readonly deviceGeneration: number;
+        readonly status: 'uninitialized';
+        readonly fallback: 'skylight';
+      }
+    | undefined;
 }
 
 export function inspectEnvironment(
@@ -50,6 +58,7 @@ export function inspectEnvironment(
     readonly lkg?: EnvironmentInspectionGeneration;
     readonly candidate?: EnvironmentInspectionGeneration;
     readonly lastCandidateFailure?: EnvironmentInspectionFailure;
+    readonly recovery?: EnvironmentInspection['recovery'];
     readonly retiringBytes?: number;
   } = {},
 ): EnvironmentInspection {
@@ -83,5 +92,6 @@ export function inspectEnvironment(
     residentBytes: active?.residentBytes ?? 0,
     retiringBytes: details.retiringBytes ?? active?.retiringBytes ?? 0,
     lastCandidateFailure: details.lastCandidateFailure,
+    recovery: details.recovery,
   });
 }