@forgeax/engine-render 0.1.31 → 0.1.33

package/src/assembly/webgpu-renderer.ts

@@ -53,7 +53,12 @@ import {
   RenderFeatureCapabilityMissingError,
   RenderFeatureStageFailedError,
 } from '../errors/render';
+import {
+  dofInspection,
+  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 {
@@ -62,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,
@@ -127,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,
@@ -142,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,
@@ -173,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,
@@ -1248,13 +1257,6 @@ async function makeWebGPURenderer(
     }
     return undefined;
   };
-  // feat-20260622-s5 M3 / w17: the pipeline build is factored into a closure so
-  // the recover() rebuild can re-run the SAME three-step assembly against the
-  // freshly-acquired device (SSOT — one build path, one set of seed callbacks).
-  // All captured references (getShader / gpuStore / getShaderModuleAdapter /
-  // materialShaderPipelineCache / renderSystem) are stable across recover; only
-  // `internals.device` / `internals.pack` are read live, so a rebuild after a
-  // device swap compiles against the new device.
   const promotePipelineExtendedLighting = (state: PipelineState, scope: DeviceScope): void => {
     if (
       state.extendedLightingAvailable !== true ||
@@ -1287,9 +1289,10 @@ async function makeWebGPURenderer(
     };
     extendedLightingState = promoteExtendedLightingCandidate(extendedLightingState, candidate);
   };
-  let tonemapRegistered = false;
-  let fxaaRegistered = false;
-  let temporalPostProcessesRegistered = false;
+  let tonemapRegistered = false,
+    fxaaRegistered = false;
+  let temporalPostProcessesRegistered = false,
+    depthOfFieldRegistered = false;
   const buildPipeline = (
     scope: DeviceScope = activeDeviceScope,
     device: RhiDevice = currentBuildDevice(),
@@ -1311,7 +1314,6 @@ async function makeWebGPURenderer(
           ),
       materialShaderUvSetCounts.get('forgeax::default-standard-pbr') ?? 0,
       requiredFullscreenPostProcesses,
-      // Publish growth and capacity together for the active or candidate device.
       (hook, state) => {
         if (candidateBuildState !== undefined) {
           candidateBuildState.growMeshSsbo = hook;
@@ -1321,12 +1323,10 @@ async function makeWebGPURenderer(
           internals.meshSsboState = state;
         }
       },
-      // Both module adapters consume the generation's eager shader cache.
       (label, module) => {
         getShaderModuleAdapter().seedModule(label, module);
         getImmediateShaderModuleAdapter().seedModule(label, module);
       },
-      // Prewarm only the active build generation's material pipeline cache.
       (key, pso, group2Contract) => {
         const pipelineCache = currentPipelineCacheState().materialShaderPipelineCache;
         if (!pipelineCache.has(key)) {
@@ -1334,7 +1334,6 @@ async function makeWebGPURenderer(
         }
         materialShaderPipelineGroup2Contracts.set(pso as object, group2Contract);
       },
-      // Register the output transform after manifest loading, once RenderSystem exists.
       (source: string) => {
         if (candidateBuildState !== undefined || tonemapRegistered) return;
         renderSystem.registerBuiltinPostProcess(STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, {
@@ -1345,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', {
@@ -1371,6 +1362,11 @@ async function makeWebGPURenderer(
         }
         temporalPostProcessesRegistered = true;
       },
+      (entries: { readonly singleSample?: string; readonly multisampled?: string }) => {
+        if (candidateBuildState !== undefined || depthOfFieldRegistered) return;
+        registerDepthOfFieldBuiltins(renderSystem, entries);
+        depthOfFieldRegistered = true;
+      },
       (sources: VolumetricFogShaderSources) => {
         internals.volumetricFogShaders = sources;
       },
@@ -2719,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}`;
@@ -2810,6 +2791,7 @@ async function makeWebGPURenderer(
         ...(renderSystem.motionBlurInspection === undefined
           ? {}
           : { motionBlur: Object.freeze(renderSystem.motionBlurInspection) }),
+        ...dofInspection(renderSystem.depthOfFieldInspection),
         ...(renderSystem.lodOcclusionInspection === undefined
           ? {}
           : { lodOcclusion: Object.freeze(renderSystem.lodOcclusionInspection) }),
@@ -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/depth-of-field.ts

@@ -0,0 +1,45 @@
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+
+/** Closed quality budget used by the built-in camera depth-of-field pass. */
+export type DepthOfFieldQuality = 'low' | 'medium' | 'high';
+
+export const DepthOfFieldQualityValue = Object.freeze({
+  low: 0,
+  medium: 1,
+  high: 2,
+} as const);
+
+/** Selects which signed circle-of-confusion side contributes to the image. */
+export type DepthOfFieldSide = 'both' | 'near' | 'far';
+
+export const DepthOfFieldSideValue = Object.freeze({
+  both: 0,
+  near: 1,
+  far: 2,
+} as const);
+
+/** Active-camera physical depth-of-field authoring data; presence enables it. */
+export const DepthOfField = defineComponent('DepthOfField', {
+  focusDistance: { type: 'f32', default: 8 },
+  fStop: { type: 'f32', default: 2.8 },
+  sensorHeight: { type: 'f32', default: 0.024 },
+  maxRadiusPixels: { type: 'f32', default: 16 },
+  quality: { type: 'f32', default: DepthOfFieldQualityValue.medium },
+  blurSide: { type: 'f32', default: DepthOfFieldSideValue.both },
+});
+
+export type DepthOfFieldData = ShapeOf<SchemaOf<typeof DepthOfField>>;
+
+export function depthOfFieldQualityFromF32(value: number): DepthOfFieldQuality | undefined {
+  if (value === DepthOfFieldQualityValue.low) return 'low';
+  if (value === DepthOfFieldQualityValue.medium) return 'medium';
+  if (value === DepthOfFieldQualityValue.high) return 'high';
+  return undefined;
+}
+
+export function depthOfFieldSideFromF32(value: number): DepthOfFieldSide | undefined {
+  if (value === DepthOfFieldSideValue.both) return 'both';
+  if (value === DepthOfFieldSideValue.near) return 'near';
+  if (value === DepthOfFieldSideValue.far) return 'far';
+  return undefined;
+}

package/src/components/directional-light.ts

@@ -60,7 +60,8 @@ export {
  *   splitLambda    ∈ [0,1]      — PSSM split weight (default 0.75)
  *   cascadeBlend   ∈ [0,0.5]    — blend width between cascades (default 0.2)
  *   mapSize        >= 1         — shadow map resolution (default 2048)
- *   depthBias                    — normalized receiver depth subtraction (default 0.00001)
+ *   depthBias                    — normalized receiver depth floor (default 0.00001),
+ *                                  plus automatic texel/filter/slope coverage
  *   normalBias                   — world-space receiver normal offset (default 0.05)
  *   shadowDistance > 0           — how far shadows reach in front of the camera,
  *                                  in world units (default 200). This is the sole

package/src/components/index.ts

@@ -1,6 +1,7 @@
 export * from './atmosphere';
 export * from './camera';
 export * from './cube-camera';
+export * from './depth-of-field';
 export * from './directional-light';
 export * from './dynamic-resolution';
 export * from './fog';

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