@forgeax/engine-render 0.1.32 → 0.1.33

package/src/assembly/webgpu-renderer.ts

@@ -58,6 +58,7 @@ import {
   registerDepthOfFieldBuiltins,
 } from '../features/depth-of-field/depth-of-field-assembly';
 import { createRenderFeatureHost } from '../features/host';
+import { motionBlurDrawOptions } from '../features/motion-blur/motion-blur-runtime';
 import { RENDER_FEATURE_VERTEX_LAYOUTS } from '../features/prepared-graphics';
 import type { RenderFeature, RenderFeatureShaderModuleMode } from '../features/types';
 import {
@@ -66,7 +67,7 @@ import {
 } 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 } from '../inspection-types';
+import { type BloomInspection, emptyBloomInspection } from '../inspection-types';
 import { DeviceScope } from '../lifecycle';
 import {
   createHdrpBindGroupLayoutDescriptor,
@@ -131,7 +132,7 @@ import type {
   SsrShaderSources,
   VolumetricFogShaderSources,
 } from '../render-contract';
-import { FXAA_POST_PROCESS_ID, STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from '../render-contract';
+import { STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from '../render-contract';
 import {
   attachGpuPassTimingSession,
   createRenderSystem,
@@ -146,10 +147,13 @@ import { postSpawnResolveJoints } from '../scene-instances/post-spawn-resolve-jo
 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';
 import type { BundlerOptions } from './bundler-contract';
 import { createRendererDynamicGeometryController } from './dynamic-geometry-host';
+import { registerFxaaPostProcess } from './fxaa-registration';
 import type { RendererAssemblyImplementation } from './host-contract';
+import { observeLodOcclusionForReceipt } from './lod-observation';
 import {
   isEngineOwnedMaterialShader,
   resolveMaterialPipelineBindGroups,
@@ -177,6 +181,7 @@ import {
   shouldDeferMissingPreparedMaterialShader,
 } from './material-shader-policy';
 import type { MeshSsboGrowResult, MeshSsboState } from './mesh-ssbo-grow';
+import { registerMotionBlurPostProcess } from './motion-blur-registration';
 import {
   type GenerationAggregate,
   type GenerationPublication,
@@ -1339,22 +1344,14 @@ async function makeWebGPURenderer(
         tonemapRegistered = true;
       },
       (source: string) => {
-        if (fxaaRegistered) return;
-        renderSystem.registerBuiltinPostProcess(FXAA_POST_PROCESS_ID, {
-          source,
-          params: { byteSize: 16, defaultValue: new Uint8Array(16) },
-          reads: ['ldrColor'],
-        });
-        fxaaRegistered = true;
+        fxaaRegistered = registerFxaaPostProcess(renderSystem, source, fxaaRegistered);
       },
+      (source: string) =>
+        registerAnalyticFogPostProcess(renderSystem, source, candidateBuildState !== undefined),
       (entries: { readonly motionBlur?: string; readonly taaResolve?: string }) => {
         if (candidateBuildState !== undefined || temporalPostProcessesRegistered) return;
         if (entries.motionBlur !== undefined) {
-          renderSystem.registerBuiltinPostProcess('forgeax.motion-blur', {
-            source: entries.motionBlur,
-            params: { byteSize: 16, defaultValue: new Uint8Array(16) },
-            reads: ['scene-color', 'scene-temporal'],
-          });
+          registerMotionBlurPostProcess(renderSystem, entries.motionBlur);
         }
         if (entries.taaResolve !== undefined) {
           renderSystem.registerBuiltinPostProcess('forgeax.taa-resolve', {
@@ -2718,22 +2715,7 @@ async function makeWebGPURenderer(
             : 'alive';
       const graph = deviceLost ? undefined : renderSystem.perFrameGraphInfo;
       const standardLighting = deviceLost ? undefined : renderSystem.standardLightingInspection;
-      const bloom: BloomInspection = deviceLost
-        ? {
-            graphStatus: 'empty',
-            enabled: false,
-            targetCount: 0,
-            targetBytes: 0,
-            resourceCount: 0,
-            passCount: 0,
-            encodeCount: 0,
-            bindGroupCount: 0,
-            uploadCount: 0,
-            residentChildBytes: 0,
-            generation: 0,
-            state: 'off',
-          }
-        : renderSystem.bloom;
+      const bloom: BloomInspection = deviceLost ? emptyBloomInspection() : renderSystem.bloom;
       const surfaceStorage = pipelineState?.format ?? 'rgba8unorm';
       const surfaceDisplay = pipelineState?.colorAttachmentFormat ?? 'rgba8unorm';
       const observationId = `${STANDARD_OUTPUT_TRANSFORM_FEATURE_ID}:frame-${frameId}`;
@@ -3226,6 +3208,7 @@ async function makeWebGPURenderer(
               ...(frameRequest.camera.entityKey === undefined
                 ? {}
                 : { cameraEntityKey: frameRequest.camera.entityKey }),
+              ...motionBlurDrawOptions(frameRequest),
               ...(frameRequest.profileFrame === undefined
                 ? {}
                 : { profileFrame: frameRequest.profileFrame }),
@@ -3377,6 +3360,8 @@ async function makeWebGPURenderer(
           const cleanupFailure = disposeOwnedObservationCaptures(observationCaptureOwner.drain());
           volumeTimingCapture?.discard();
           if (cleanupFailure !== undefined) return err(cleanupFailure);
+          const invalidMotionBlur = renderSystem.motionBlurInvalidParams;
+          if (invalidMotionBlur !== undefined) return err(invalidMotionBlur);
           return err(
             new RendererContractFailureError(
               'draw',
@@ -3715,7 +3700,7 @@ async function makeWebGPURenderer(
           receiptObservationBuffers.delete(receipt);
         }
       }
-      await renderSystem.observeLodOcclusion();
+      await observeLodOcclusionForReceipt(renderSystem, receipt);
       const targetReadbacks =
         request.targetReadbacks === undefined || request.targetReadbacks.length === 0
           ? undefined

package/src/bloom-admission.ts

@@ -0,0 +1,21 @@
+import type { BloomEnabled, Tonemap } from './components/camera';
+
+/**
+ * The one effective Standard Bloom admission used by graph, resource, and
+ * record owners. Authoring remains Camera-owned; this is only the derived
+ * zero/non-zero topology decision.
+ */
+export interface BloomAdmissionCamera {
+  readonly bloom: BloomEnabled;
+  readonly bloomIntensity: number;
+  readonly tonemap: Tonemap;
+}
+
+export function standardBloomAdmitted(camera: BloomAdmissionCamera | undefined): boolean {
+  return (
+    camera !== undefined &&
+    camera.bloom === 'on' &&
+    camera.bloomIntensity > 0 &&
+    camera.tonemap !== 'none'
+  );
+}

package/src/components/__tests__/motion-blur.unit.test.ts

@@ -8,6 +8,7 @@ describe('MotionBlur component schema', () => {
       shutterAngle: { type: 'f32', default: 180 },
       maxRadiusPixels: { type: 'f32', default: 32 },
       sampleCount: { type: 'f32', default: 8 },
+      targetFps: { type: 'f32', default: 60 },
     });
     expect(MotionBlur.fields).not.toHaveProperty('enabled');
   });

package/src/components/atmosphere.ts

@@ -7,4 +7,8 @@ export const Atmosphere = defineComponent('Atmosphere', {
   mieCoefficient: { type: 'f32', default: 0.005 },
   mieDirectionalG: { type: 'f32', default: 0.8 },
   sunAngularRadius: { type: 'f32', default: 0.004675 },
+  /** Independent multiplier for the analytic circumsolar lobe. */
+  circumsolarStrength: { type: 'f32', default: 1 },
+  /** Relative angular width of the analytic circumsolar lobe. */
+  circumsolarWidth: { type: 'f32', default: 1 },
 });

package/src/components/camera.ts

@@ -1,9 +1,7 @@
 // @forgeax/engine-render - Camera (projection variant + ortho extension).
 //
-// Schema: 9 f32 columns — perspective quartet (fov + aspect + near + far)
-// + projection discriminator (0 = perspective, 1 = orthographic) + ortho
-// quartet (left + right + bottom + top). The view matrix continues to be
-// derived from the entity's Transform (AC-06 case B fires
+// Schema: projection, output, Bloom, and lifecycle columns. The view matrix
+// continues to be derived from the entity's Transform (AC-06 case B fires
 // 'render-system-no-camera' when 0 such entities exist).
 //
 // Projection discriminator:
@@ -386,7 +384,7 @@ export function antialiasFromF32(value: number): Antialias {
  *
  * Two members:
  *   `'off'` - default; no bloom post-processing (zero-overhead opt-out path)
- *   `'on'`  - bloom bright-pass + separable blur + composite pipeline
+ *   `'on'`  - five-level HDR extraction/downsample/tent-upsample pipeline
  *
  * Bloom is a discrete enum (0/1) — illegal values fail-fast with the closed
  * CameraError contract (charter P3), matching antialiasFromF32 precedent.
@@ -398,6 +396,19 @@ export const BLOOM_DISABLED = 0;
 /** Numeric encoding of bloom enabled (schema value for `bloom`). */
 export const BLOOM_ENABLED = 1;
 
+/** Bloom intensity is a linear HDR add-back multiplier. */
+export const CAMERA_BLOOM_INTENSITY_MIN = 0;
+export const CAMERA_BLOOM_INTENSITY_MAX = 8;
+/** Bloom threshold is expressed in scene-linear Rec.709 luminance. */
+export const CAMERA_BLOOM_THRESHOLD_MIN = 0;
+export const CAMERA_BLOOM_THRESHOLD_MAX = 65504;
+/** Soft-knee transition width relative to the threshold. */
+export const CAMERA_BLOOM_SOFT_KNEE_MIN = 0;
+export const CAMERA_BLOOM_SOFT_KNEE_MAX = 1;
+/** Coarse pyramid contribution. This is a blend, not a blur radius. */
+export const CAMERA_BLOOM_SCATTER_MIN = 0;
+export const CAMERA_BLOOM_SCATTER_MAX = 0.95;
+
 /**
  * Map a `camera.bloom` numeric value to the closed `BloomEnabled` string-literal
  * union. Invalid values fail-fast with structured error (charter P3).
@@ -414,6 +425,49 @@ export function bloomEnabledFromF32(value: number): BloomEnabled {
   );
 }
 
+function validateBloomRange(field: string, value: number, min: number, max: number): void {
+  if (!Number.isFinite(value) || value < min || value > max) {
+    throw cameraError(
+      'camera-bloom-invalid',
+      field,
+      value,
+      `a finite value in [${min}, ${max}]`,
+      `set Camera.${field} to a finite value in [${min}, ${max}]`,
+    );
+  }
+}
+
+/** Validate the complete Camera-owned Bloom contract at the extract boundary. */
+export function validateCameraBloom(
+  bloom: number,
+  threshold: number,
+  intensity: number,
+  softKnee: number,
+  scatter: number,
+): BloomEnabled {
+  const enabled = bloomEnabledFromF32(bloom);
+  validateBloomRange(
+    'bloomThreshold',
+    threshold,
+    CAMERA_BLOOM_THRESHOLD_MIN,
+    CAMERA_BLOOM_THRESHOLD_MAX,
+  );
+  validateBloomRange(
+    'bloomIntensity',
+    intensity,
+    CAMERA_BLOOM_INTENSITY_MIN,
+    CAMERA_BLOOM_INTENSITY_MAX,
+  );
+  validateBloomRange(
+    'bloomSoftKnee',
+    softKnee,
+    CAMERA_BLOOM_SOFT_KNEE_MIN,
+    CAMERA_BLOOM_SOFT_KNEE_MAX,
+  );
+  validateBloomRange('bloomScatter', scatter, CAMERA_BLOOM_SCATTER_MIN, CAMERA_BLOOM_SCATTER_MAX);
+  return enabled;
+}
+
 /**
  * Camera projection parameters (perspective + orthographic variants) +
  * tonemap trio (mode + exposure + whitePoint).
@@ -447,8 +501,9 @@ export function bloomEnabledFromF32(value: number): BloomEnabled {
  * N>1 fires 'render-system-multi-camera' + uses first). Multi-viewport is
  * OOS (see feat-future-multi-viewport). The orthographic path reuses the
  * same near / far as the perspective path — both variants share the single
- * Camera archetype (17 scalar f32 columns + one historyVersion u32 column +
- * the `clearColor` array<f32,4> column + the `autoAspect` bool column).
+ * Camera archetype (30 schema fields, including the Bloom controls, one
+ * historyVersion u32 column, the `clearColor` array<f32,4> column, and the
+ * `autoAspect` bool column).
  *
  * @example Perspective camera at (0, 0, 3) looking down -Z (zero-config tonemap):
  *   world.spawn(
@@ -514,7 +569,8 @@ export const Camera = defineComponent('Camera', {
   bloom: { type: 'f32', default: 0 },
   bloomThreshold: { type: 'f32', default: 1.0 },
   bloomIntensity: { type: 'f32', default: 1.0 },
-  bloomBlurRadius: { type: 'f32', default: 4.0 },
+  bloomSoftKnee: { type: 'f32', default: 0.5 },
+  bloomScatter: { type: 'f32', default: 0.7 },
   // M1 target camera role: zero means this camera is eligible for display;
   // non-zero shared targets are auxiliary producers whose views and receipt
   // promotion remain owned by Renderer.
@@ -544,7 +600,7 @@ export const Camera = defineComponent('Camera', {
 
 // ─── Camera POD type (derived from Camera token — single source, AC-07) ─────
 //
-// ShapeOf<SchemaOf<typeof Camera>> resolves the 20-field POD from the Camera
+// ShapeOf<SchemaOf<typeof Camera>> resolves the 30-field POD from the Camera
 // token's schema, which is itself derived from Camera.fields[k].type (D-A7).
 // This replaces the hand-maintained CameraDataPod interface — the field set
 // lives exclusively in the Camera component definition above.
@@ -626,7 +682,7 @@ function cameraColorGradingColumns(
 
 // ─── Camera factory functions (w13 SSOT refactoring) ─────────────────────
 //
-// Standalone factory functions that return 20-field CameraPod objects
+// Standalone factory functions that return 29-field CameraPod objects
 // matching the Camera component column shape. Not static methods because
 // TypeScript const-namespace merge is not supported, and Object.assign
 // would break the Camera token's reference identity (archetype columns /

package/src/components/mesh-filter.ts

@@ -10,8 +10,8 @@
 //
 // AI users spawn with the assets-runtime constants `HANDLE_CUBE` /
 // `HANDLE_TRIANGLE` (now branded `Handle<'MeshAsset','shared'>` to
-// match the schema-derived shape); custom mesh registration is owned by
-// feat-future-asset-system (this MVP only exposes builtin handles).
+// match the schema-derived shape). A loaded or custom MeshAsset payload is
+// bound by allocating a World shared reference before publishing this field.
 //
 // Naming flavor: unity-style "MeshFilter / MeshRenderer" pair, but the forgeax
 // pair does NOT mirror Unity's filter-toggle semantics - MeshFilter only
@@ -22,12 +22,13 @@
 // query never matches -> entity is silently absent from the
 // RenderableSnapshot[] (NO default-material fallback, NO onError fire);
 // case B (MeshRenderer.material omitted at spawn) -> mid-grey
-// defaultMaterialSnapshot fallback (no onError); case C (material handle
+// defaultMaterialSnapshot fallback (no onError); an unbound scalar shared<T>
+// field (slot 0) is also not a renderable; case C (non-zero material handle
 // unresolved) -> RhiError 'asset-not-registered' (mirrors the
 // MeshFilter.assetHandle dangling-ref path).
 //
 // charter mapping: proposition 1 (single import) + proposition 4 (explicit
-// failure: missing or unregistered handle fires onError 'asset-not-registered'
+// failure: a non-zero unregistered handle fires onError 'asset-not-registered'
 // with .detail = { assetHandle } + cross-asset brand mismatch is a TS
 // compile-time error) + proposition 5 (consistent abstraction: the schema
 // vocab `'shared<T>'` is the SSOT for AssetRegistry-owned handles across
@@ -39,12 +40,13 @@ import { defineComponent } from '@forgeax/engine-ecs';
  * Mesh filter (geometry asset reference).
  *
  * `assetHandle` carries a `Handle<'MeshAsset', 'shared'>` (u32-stored)
- * pointing into `engine.assets: AssetRegistry`. Use the predefined
- * constants `HANDLE_CUBE` / `HANDLE_TRIANGLE` exported from
- * `@forgeax/engine-render`; custom-mesh registration is OOS in MVP (see
- * feat-future-asset-system).
+ * pointing to a mesh payload in the current World shared-reference / builtin
+ * handle namespace. An omitted field defaults to slot `0`, the unbound
+ * sentinel; an entity with that value is not emitted as a renderable. Use the
+ * predefined constants `HANDLE_CUBE` / `HANDLE_TRIANGLE` for builtins and
+ * allocate a World shared reference for a loaded mesh payload.
  *
- * Error path: if the handle is not registered at draw time, RenderSystem
+ * Error path: if a non-zero handle is not registered at draw time, RenderSystem
  * fires `Renderer.onError` with
  * `RhiError({ code: 'asset-not-registered', detail: { assetHandle } })`
  * and skips this entity (other entities continue rendering; charter

package/src/components/motion-blur.ts

@@ -5,4 +5,5 @@ export const MotionBlur = defineComponent('MotionBlur', {
   shutterAngle: { type: 'f32', default: 180 },
   maxRadiusPixels: { type: 'f32', default: 32 },
   sampleCount: { type: 'f32', default: 8 },
+  targetFps: { type: 'f32', default: 60 },
 });

package/src/device/gpu-residency.ts

@@ -75,7 +75,6 @@ import {
   type TextureAsset,
   type TextureShape,
   type MeshAsset as TypesMeshAsset,
-  toShared,
 } from '@forgeax/engine-types';
 import { GpuBuffer, GpuTexture } from '../gpu-resource';
 import {
@@ -570,6 +569,12 @@ export class GpuResidencyCache {
   // equirect source always resolves to the same cubemap (idempotent, A2).
   private readonly cubemapIdempotentMap: Map<number, Handle<'EquirectAsset', 'shared'>> = new Map();
   private readonly meshGpuHandles: Map<string | number, MeshGpuHandles> = new Map();
+  /**
+   * Lower-detail POD identities packed into each resident mesh entry. The
+   * GPU entry only carries byte ranges; keeping the source identities beside
+   * it lets a later draw upgrade a root-only upload without hashing vertices.
+   */
+  private readonly meshLodAssets = new WeakMap<MeshGpuHandles, readonly TypesMeshAsset[]>();
   private readonly meshLifetimes = new WeakMap<MeshGpuHandles, MeshResidencyLifetime>();
   private readonly retiredMeshes = new Set<MeshGpuHandles>();
 
@@ -832,7 +837,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'>,
     worldId: World | number = 0,
   ): { freed: number; errors: RhiError[] } {
-    const id = this.worldKey(handleSlot(handle), worldId);
+    const id = this.worldKey(Number(handle), worldId);
     const entry = this.meshGpuHandles.get(id);
     if (entry === undefined) return { freed: 0, errors: [] };
 
@@ -1090,7 +1095,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'>,
     worldId: World | number = 0,
   ): MeshGpuHandles | undefined {
-    return this.meshGpuHandles.get(this.worldKey(handleSlot(handle), worldId));
+    return this.meshGpuHandles.get(this.worldKey(Number(handle), worldId));
   }
 
   /** Candidate leases retain the concrete allocation even after cache invalidation. */
@@ -1098,7 +1103,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'>,
     worldId: World | number = 0,
   ): MeshResidencyLease | undefined {
-    const key = this.worldKey(handleSlot(handle), worldId);
+    const key = this.worldKey(Number(handle), worldId);
     const entry = this.meshGpuHandles.get(key);
     return entry === undefined
       ? undefined
@@ -1110,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 {
-    const key = this.worldKey(handleSlot(toShared<'MeshAsset'>(handle)), worldId);
+    const key = this.worldKey(handle, worldId);
     const entry = this.meshGpuHandles.get(key);
     if (entry !== undefined) this.retireMeshEntry(key, entry);
   }
@@ -1156,9 +1161,32 @@ export class GpuResidencyCache {
     // path, not routed here).
     switch (pod.kind) {
       case 'mesh': {
-        const key = this.worldKey(id, worldId);
+        // Recycled shared slots can coexist with an older GPU submission.
+        // The generation is part of mesh residency identity, not only its slot.
+        const key = this.worldKey(Number(handle), worldId);
         const existing = this.meshGpuHandles.get(key);
-        if (existing !== undefined) return ok(existing);
+        if (existing !== undefined) {
+          // A root mesh can become resident before its lower-detail assets are
+          // available. Preserve the fast hit for the common case, but publish
+          // a complete chain once the caller supplies one. Never downgrade a
+          // resident chain when a later call has no lower assets yet.
+          if (lodMeshes.length === 0) return ok(existing);
+          const previousLodAssets = this.meshLodAssets.get(existing);
+          const sameLodChain =
+            previousLodAssets !== undefined &&
+            previousLodAssets.length === lodMeshes.length &&
+            previousLodAssets.every((asset, index) => asset === lodMeshes[index]);
+          if (sameLodChain) return ok(existing);
+
+          const projected = deriveRenderDataMesh(pod);
+          if (!projected.ok) return projected;
+          const upgraded = this.uploadMeshById(key, pod, projected.value, lodMeshes);
+          if (!upgraded.ok) return upgraded;
+          // uploadMeshById publishes the new entry before this call so the
+          // old allocation stays available to any already-recorded frame.
+          this.retireMeshEntry(key, existing);
+          return upgraded;
+        }
         const projected = deriveRenderDataMesh(pod);
         if (!projected.ok) return projected;
         return this.uploadMeshById(key, pod, projected.value, lodMeshes);
@@ -1204,7 +1232,7 @@ export class GpuResidencyCache {
   ): Result<RecoveryResidencyPreparation, RhiError | AssetError | ImageError> {
     const id = handleSlot(handle);
     if (pod.kind === 'mesh') {
-      const key = this.worldKey(id, worldId);
+      const key = this.worldKey(Number(handle), worldId);
       if (this.meshGpuHandles.has(key)) return ok({});
       const projected = deriveRenderDataMesh(pod);
       if (!projected.ok) return projected;
@@ -2035,6 +2063,10 @@ export class GpuResidencyCache {
     // Vertex-only mesh: skip the index buffer entirely. The indexed path below
     // is unchanged byte-for-byte when `indices` is present.
     let ibo: Buffer | null = null;
+    const cleanupUpload = (): void => {
+      if (ibo !== null) device.destroyBuffer(ibo);
+      device.destroyBuffer(vbo);
+    };
     if (indices !== undefined) {
       const iboResult = device.createBuffer({
         label: `mesh-${id}-ibo`,
@@ -2042,17 +2074,24 @@ export class GpuResidencyCache {
         usage: renderData.indexUsage,
         mappedAtCreation: false,
       });
-      if (!iboResult.ok) return iboResult;
+      if (!iboResult.ok) {
+        cleanupUpload();
+        return iboResult;
+      }
       ibo = iboResult.value;
     }
 
     const vboWriteResult = device.queue.writeBuffer(vbo, 0, vertices);
-    if (!vboWriteResult.ok) return err(vboWriteResult.error);
+    if (!vboWriteResult.ok) {
+      cleanupUpload();
+      return err(vboWriteResult.error);
+    }
 
     if (indices !== undefined) {
       const indexSrc = new Uint8Array(indexBytes);
       indexSrc.set(new Uint8Array(indices.buffer, indices.byteOffset, indexBytesUnpadded));
-      if (ibo === null)
+      if (ibo === null) {
+        cleanupUpload();
         return err(
           new RhiError({
             code: 'webgpu-runtime-error',
@@ -2060,8 +2099,12 @@ export class GpuResidencyCache {
             hint: 'the indexed mesh upload lost its RHI index-buffer owner',
           }),
         );
+      }
       const iboWriteResult = device.queue.writeBuffer(ibo, 0, indexSrc);
-      if (!iboWriteResult.ok) return err(iboWriteResult.error);
+      if (!iboWriteResult.ok) {
+        cleanupUpload();
+        return err(iboWriteResult.error);
+      }
     }
 
     // The geometry projection already contains every packed attribute,
@@ -2085,6 +2128,7 @@ export class GpuResidencyCache {
       ...(lodRanges === undefined ? {} : { lodRanges }),
     };
     this.meshGpuHandles.set(id, entry);
+    this.meshLodAssets.set(entry, lodMeshes);
     this.meshResidencyEpoch += 1;
     return ok(entry);
   }

package/src/environment/analytic-fog.ts

@@ -0,0 +1,44 @@
+import { mat4 } from '@forgeax/engine-math';
+import type { FogFrame } from '../extract/environment';
+import { computeProjectionMatrix, computeViewMatrix } from '../record/helpers';
+import type { CameraSnapshot } from '../render-contract';
+
+/** Numerical reference for the shader's closed-form height-density integral. */
+export function analyticFogOpacity(
+  fog: Pick<FogFrame, 'density' | 'heightFalloff' | 'maxOpacity'>,
+  originY: number,
+  endY: number,
+  distance: number,
+): number {
+  const rho = fog.density * Math.exp(Math.max(-60, Math.min(60, -fog.heightFalloff * originY)));
+  const t = Math.max(-60, Math.min(60, fog.heightFalloff * (endY - originY)));
+  const integral = Math.abs(t) < 0.001 ? 1 - t / 2 + (t * t) / 6 : -Math.expm1(-t) / t;
+  return fog.maxOpacity * -Math.expm1(-Math.min(80, Math.max(0, rho * distance * integral)));
+}
+
+export function encodeAnalyticFogParams(fog: FogFrame, camera: CameraSnapshot): Uint8Array {
+  const projection = computeProjectionMatrix(camera);
+  // Match the scene depth's jittered projection before temporal resolve.
+  const jitter = camera.temporal?.currentJitterUv;
+  if (jitter !== undefined) {
+    for (let column = 0; column < 4; column++) {
+      projection[column * 4] =
+        (projection[column * 4] ?? 0) + jitter[0] * 2 * (projection[column * 4 + 3] ?? 0);
+      projection[column * 4 + 1] =
+        (projection[column * 4 + 1] ?? 0) - jitter[1] * 2 * (projection[column * 4 + 3] ?? 0);
+    }
+  }
+  const inverse = mat4.invert(
+    mat4.create(),
+    mat4.multiply(mat4.create(), projection, computeViewMatrix(camera)),
+  );
+  const data = new Float32Array(28);
+  data.set(inverse, 0);
+  data.set(camera.position, 16);
+  data.set([...fog.color, fog.density], 20);
+  data.set(
+    [fog.heightFalloff, fog.maxOpacity, camera.near, camera.projection === 'orthographic' ? 1 : 0],
+    24,
+  );
+  return new Uint8Array(data.buffer);
+}

package/src/environment/background.ts

@@ -88,8 +88,8 @@ export function addAtmosphereBackground(
         settings.mieDirectionalG,
         settings.sunAngularRadius,
         settings.sunAngularRadius > 0 ? 1 : 0,
-        0,
-        0,
+        settings.circumsolarStrength,
+        settings.circumsolarWidth,
       ]);
       frame.runtime.device.queue
         .writeBuffer(resources.buffer(params.value).unwrap(), 0, values)

package/src/errors/render.ts

@@ -19,6 +19,8 @@ import type {
   SurfaceFailureKind,
 } from '@forgeax/engine-render-graph';
 import type { DeviceResourceKind, DeviceScopeReceipt } from '../device/resource-types';
+import type { SunCardinalityError } from '../environment/frame';
+import type { MotionBlurValidationError } from '../features/motion-blur/motion-blur-params';
 import type {
   PreparedKind,
   RenderFeatureCapabilityKey,
@@ -783,6 +785,8 @@ export interface RenderFeatureStageFailedDetail {
   readonly stage: RenderFeatureStage;
   readonly recovery: RenderFeatureRecovery;
   readonly cleanupFailures?: readonly RenderFeatureCleanupFailure[];
+  /** Original stage exception when the feature did not return a RenderError. */
+  readonly cause?: unknown;
 }
 
 export interface RenderFeatureCapabilityMissingDetail {
@@ -947,6 +951,7 @@ export class RenderFeatureStageFailedError extends Error {
     order: number,
     stage: RenderFeatureStage,
     recovery: RenderFeatureRecovery,
+    cause?: unknown,
   ) {
     const expected = `feature '${featureIdentity}' completes its ${stage} stage without an error`;
     const hint = renderFeatureRecoveryHintByRecovery[recovery](featureIdentity, stage);
@@ -954,7 +959,13 @@ export class RenderFeatureStageFailedError extends Error {
     this.name = 'RenderFeatureStageFailedError';
     this.expected = expected;
     this.hint = hint;
-    this.detail = { featureIdentity, order, stage, recovery };
+    this.detail = {
+      featureIdentity,
+      order,
+      stage,
+      recovery,
+      ...(cause === undefined ? {} : { cause }),
+    };
   }
 }
 
@@ -1966,12 +1977,14 @@ export type RenderError =
   | RenderFeatureDrawRecordingFailedError
   | EnvironmentSourceConflictError
   | FogCardinalityError
+  | SunCardinalityError
   | TaaCapsInsufficientError
   | EnvironmentGenerationFailedError
   | AtmosphereInvalidParameterError
   | DynamicResolutionInvalidParameterError
   | DynamicResolutionRequiresTaaError
   | DynamicResolutionTimingUnavailableError
+  | MotionBlurValidationError
   | OwnerStageFailedError
   | PointsLinesInvalidStyleError
   | PointsLinesTopologyMismatchError