@forgeax/engine-render 0.1.32 → 0.1.34

package/src/features/host.ts

@@ -17,7 +17,8 @@ import type {
   PreparedGraphicsResolver,
   PreparedGraphicsResourceLease,
 } from '../prepare/prepared-graphics-resolver';
-import type { SceneDataTarget } from '../temporal/scene-data';
+import type { CameraSnapshot } from '../render-contract';
+import { isSceneDataTarget, type SceneDataTarget } from '../temporal/scene-data';
 import { createSceneDataCatalog, type SceneDataCatalog } from '../temporal/scene-data-catalog';
 import {
   cloneRenderFeaturePlanSignatureSnapshot,
@@ -114,6 +115,7 @@ export interface RenderFeaturePlanExecutionPass {
 export interface RenderFeaturePlanExecution {
   readonly featureIdentity: string;
   readonly order: number;
+  readonly placement?: import('./types').RenderFeaturePlacement;
   readonly passes: readonly RenderFeaturePlanExecutionPass[];
 }
 
@@ -134,6 +136,10 @@ export interface RenderFeatureFrameInput {
   readonly worlds: readonly import('@forgeax/engine-ecs').World[];
   readonly owner: number;
   readonly frameNumber: number;
+  /** Renderer-selected display camera forwarded to feature extraction. */
+  readonly selectedCamera?: CameraSnapshot;
+  /** Physical render extent for bounded feature dispatch sizing. */
+  readonly frameSize?: { readonly width: number; readonly height: number };
   readonly visibilitySnapshots?: readonly RenderFeatureWorldVisibilitySnapshot[];
   readonly hiddenEntityReports?: readonly RenderFeatureHiddenEntityReport[];
   /** Active-pipeline logical targets available to producer-owned features. */
@@ -142,6 +148,8 @@ export interface RenderFeatureFrameInput {
   readonly sceneData?: SceneDataCatalog;
   readonly generation?: number;
   readonly caps: Readonly<RhiCaps>;
+  /** Normal frame-owner facts shared with producer extraction. */
+  readonly frame?: import('./types').RenderFeatureFrameContext;
   /** Renderer-owned material binding contract projection for producer plans. */
   readonly materialShaderBindingContract?: (
     materialShaderId: string,
@@ -173,6 +181,8 @@ export interface RenderFeatureFrameResult {
   readonly errors: readonly RenderError[];
   readonly plans: readonly RenderFeaturePlannedFrame[];
   readonly fullscreenEffects: ReadonlyMap<string, PostProcessShaderEntry>;
+  /** Public Standard post-effect identities; graph-local fullscreen resources are not included. */
+  readonly postProcessIdentities: readonly string[];
   readonly preparedResourceBatches: readonly RenderFeaturePreparedResourceBatch[];
   /**
    * True only when the current graph resolves a transient graphics lease.
@@ -221,6 +231,8 @@ export interface RenderFeatureHost {
   recover(input: RenderFeatureRecoverInput): Result<void, RenderError>;
   createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown>;
   diagnostics(): readonly RenderFeatureDiagnostics[];
+  /** Retain an explicitly producer-published detached inspection value. */
+  setInspection(identity: string, inspection: unknown): void;
   /** Subscribe to lifecycle projection changes; unchanged active frames are silent. */
   subscribeDiagnostics(listener: () => void): () => void;
   /** Detached signature and prepared-resource accounting for diagnostics. */
@@ -267,6 +279,7 @@ interface FeatureSlot {
   readonly preparedStore: PreparedGraphicsStore;
   status: RenderFeatureStatus;
   latestError: RenderFeatureErrorDescriptor | undefined;
+  latestInspection?: unknown;
 }
 
 function freezeError(error: RenderFeatureErrorDescriptor): RenderFeatureErrorDescriptor {
@@ -289,6 +302,7 @@ function freezeDiagnostics(slot: FeatureSlot): RenderFeatureDiagnostics {
     order: slot.order,
     status: slot.status,
     latestError: slot.latestError === undefined ? undefined : freezeError(slot.latestError),
+    ...(slot.latestInspection === undefined ? {} : { inspection: slot.latestInspection }),
   });
 }
 
@@ -318,6 +332,16 @@ function missingCapability(
   return feature.requiredCapabilities?.find((capability) => caps[capability] !== true);
 }
 
+/**
+ * Capability declarations gate work that the current plan actually admits.
+ * A producer is still allowed to extract and return an empty plan when its
+ * authored feature is disabled; that path must remain allocation-free on a
+ * backend which cannot support the optional feature.
+ */
+function hasActivePlan(plan: RenderFeaturePlan): boolean {
+  return plan.resources.length > 0 || plan.passes.length > 0;
+}
+
 function createPreparedGraphicsPrepare(
   transaction: PreparedGraphicsTransaction,
 ): RenderFeatureGraphicsPrepare {
@@ -344,6 +368,9 @@ function resolveGraphicsSnapshot(
   resolver: PreparedGraphicsResolver,
   descriptor: import('./prepared-graphics').RenderFeatureGraphicsPassDescriptor,
   generation: number,
+  resolveGpuResource?: (
+    name: string,
+  ) => import('./prepared-gpu-work').RenderFeatureResolvedGpuBuffer | undefined,
 ): Result<PreparedGraphicsResolvedSnapshot, RenderError> {
   const resources = new Map<
     object,
@@ -362,6 +389,7 @@ function resolveGraphicsSnapshot(
     ...(resolver.resolveGpuBuffer === undefined
       ? {}
       : { resolveGpuBuffer: resolver.resolveGpuBuffer }),
+    ...(resolveGpuResource === undefined ? {} : { resolveGpuResource }),
   });
 }
 
@@ -412,7 +440,7 @@ function asFeatureError(
   if (error instanceof Error && typeof (error as Partial<RenderError>).code === 'string') {
     return error as RenderError;
   }
-  return new RenderFeatureStageFailedError(identity, order, stage, 'next-frame');
+  return new RenderFeatureStageFailedError(identity, order, stage, 'next-frame', error);
 }
 
 function featureErrorForSlot(slot: FeatureSlot, error: RenderError): RenderError {
@@ -431,6 +459,7 @@ function featureErrorForSlot(slot: FeatureSlot, error: RenderError): RenderError
             slot.order,
             'plan',
             'next-frame',
+            error,
           );
     default:
       return new RenderFeatureStageFailedError(
@@ -438,6 +467,7 @@ function featureErrorForSlot(slot: FeatureSlot, error: RenderError): RenderError
         slot.order,
         'plan',
         'next-frame',
+        error,
       );
   }
 }
@@ -467,6 +497,7 @@ function errorDescriptor(error: RenderError): RenderFeatureErrorDescriptor {
           order: -1,
           stage: 'plan',
           recovery: 'next-frame',
+          cause: error,
         },
       };
   }
@@ -606,14 +637,17 @@ function preparePlanResources(
           : targetHandle(resource.logicalTarget, targets);
       if (
         resource.logicalTarget !== undefined &&
-        (logical === undefined || !isRenderFeatureTargetHandle(logical))
+        (logical === undefined ||
+          (typeof logical !== 'string' &&
+            !isRenderFeatureTargetHandle(logical) &&
+            !isSceneDataTarget(logical)))
       ) {
         return err(planFailure(slot));
       }
       const prepared = gpu.prepareTextureView(
         resource.name,
-        resource.resource.value as TextureView,
-        logical === undefined || !isRenderFeatureTargetHandle(logical) ? undefined : logical,
+        resource.resource.value as TextureView | undefined,
+        logical === undefined ? undefined : logical,
       );
       if (!prepared.ok) return prepared;
       preparedGpuResources.set(resource.name, {
@@ -963,6 +997,7 @@ function projectPlanPasses(
   return ok({
     featureIdentity: slot.feature.identity,
     order: slot.order,
+    ...(slot.feature.placement === undefined ? {} : { placement: slot.feature.placement }),
     passes: Object.freeze(projected),
   });
 }
@@ -1322,6 +1357,13 @@ class FeatureHostImpl implements RenderFeatureHost {
     return Object.freeze(this.slots.map(freezeDiagnostics));
   }
 
+  /** Retain only an explicitly producer-published detached inspection value. */
+  setInspection(identity: string, inspection: unknown): void {
+    const slot = findSlot(this.slots, identity);
+    if (slot === undefined || slot.status === 'disposed') return;
+    slot.latestInspection = inspection;
+  }
+
   subscribeDiagnostics(listener: () => void): () => void {
     this.diagnosticsListeners.add(listener);
     return () => this.diagnosticsListeners.delete(listener);
@@ -1352,6 +1394,7 @@ export function runRenderFeatureFrame(
   const errors: RenderError[] = [];
   const plans: RenderFeaturePlannedFrame[] = [];
   const fullscreenEffects = new Map<string, PostProcessShaderEntry>();
+  const postProcessIdentities = new Set<string>();
   const preparedResourceBatches: RenderFeaturePreparedResourceBatch[] = [];
   let requiresPreparedResourceKey = false;
   const hiddenEntityReports: RenderFeatureHiddenEntityReport[] = [
@@ -1362,17 +1405,18 @@ export function runRenderFeatureFrame(
   const diagnostics = host.diagnostics();
   for (const [order, feature] of host.features.entries()) {
     const diagnostic = diagnostics[order];
-    if (diagnostic?.status === 'disabled' || diagnostic?.status === 'disposed') continue;
-    const missing = missingCapability(feature, input.caps);
-    if (missing !== undefined) {
-      const capabilityError = new RenderFeatureCapabilityMissingError(
-        feature.identity,
-        order,
-        missing,
-      );
-      errors.push(capabilityError);
-      host.setStatus(feature.identity, 'disabled', errorDescriptor(capabilityError));
-      continue;
+    if (diagnostic?.status === 'disposed') continue;
+    // Preserve the existing recovery contract for a capability-disabled
+    // feature once the device becomes capable: an explicit host.recover()
+    // still re-admits it. While the capability is absent, however, rerun the
+    // producer so a camera/world can disable its authored plan and recover to
+    // an empty, zero-resource frame without a second manager.
+    if (diagnostic?.status === 'disabled') {
+      const diagnosticError = diagnostic.latestError;
+      const missing = missingCapability(feature, input.caps);
+      if (diagnosticError?.code !== 'render-feature-capability-missing' || missing === undefined) {
+        continue;
+      }
     }
     const slot: FeatureSlot = {
       feature,
@@ -1383,6 +1427,9 @@ export function runRenderFeatureFrame(
       latestError: undefined,
     };
     const identity = slot.feature.identity;
+    for (const postProcess of feature.requiredFullscreenPostProcesses ?? []) {
+      postProcessIdentities.add(postProcess.identity);
+    }
     const transaction = host.beginPreparedFrame(identity, input.generation ?? 0);
     if (transaction === undefined) continue;
     const graphics = createPreparedGraphicsPrepare(transaction);
@@ -1396,6 +1443,9 @@ export function runRenderFeatureFrame(
       worlds: input.worlds,
       owner: input.owner,
       frameNumber: input.frameNumber,
+      ...(input.selectedCamera === undefined ? {} : { selectedCamera: input.selectedCamera }),
+      caps: input.caps,
+      ...(input.frame === undefined ? {} : { frame: input.frame }),
       reportHiddenEntity: (report) => featureHiddenEntityReports.push(report),
       ...(input.visibilitySnapshots === undefined
         ? {}
@@ -1413,6 +1463,16 @@ export function runRenderFeatureFrame(
       host.setStatus(identity, 'failed', slot.latestError);
       continue;
     }
+    if (
+      typeof extracted.value === 'object' &&
+      extracted.value !== null &&
+      'inspection' in extracted.value
+    ) {
+      host.setInspection(
+        identity,
+        (extracted.value as { readonly inspection?: unknown }).inspection,
+      );
+    }
 
     const targets = logicalTargets(input.targets ?? []);
     const sceneData =
@@ -1429,7 +1489,10 @@ export function runRenderFeatureFrame(
       () =>
         feature.plan(extracted.value, {
           caps: input.caps,
-          frame: { frameNumber: input.frameNumber },
+          frame: {
+            frameNumber: input.frameNumber,
+            ...(input.frameSize === undefined ? {} : input.frameSize),
+          },
           generation: transaction.generation,
           targets,
           sceneData,
@@ -1455,21 +1518,43 @@ export function runRenderFeatureFrame(
       host.setStatus(identity, 'failed', slot.latestError);
       continue;
     }
+    const missing = missingCapability(feature, input.caps);
+    if (missing !== undefined && hasActivePlan(frozen.value)) {
+      const capabilityError = new RenderFeatureCapabilityMissingError(identity, order, missing);
+      errors.push(capabilityError);
+      transaction.abort();
+      host.setStatus(identity, 'disabled', errorDescriptor(capabilityError));
+      continue;
+    }
     const plannedFrame: RenderFeaturePlannedFrame = Object.freeze({
       featureIdentity: identity,
       generation: transaction.generation,
       signature:
         host.recordPlanSignature?.(identity, frozen.value) ??
         renderFeaturePlanSignature(frozen.value),
+      ...(feature.placement === undefined ? {} : { placement: feature.placement }),
       plan: frozen.value,
     });
     for (const resource of frozen.value.resources) {
       if (resource.kind !== 'fullscreen-program') continue;
-      fullscreenEffects.set(identity, {
+      const entry = {
         source: resource.source,
+        ...(resource.fragmentEntryPoint === undefined
+          ? {}
+          : { fragmentEntryPoint: resource.fragmentEntryPoint }),
         ...(resource.reads === undefined ? {} : { reads: resource.reads }),
+        ...(resource.usesView === undefined ? {} : { usesView: resource.usesView }),
+        ...(resource.storageBindings === undefined
+          ? {}
+          : { storageBindings: resource.storageBindings }),
         ...(resource.params === undefined ? {} : { params: resource.params }),
-      });
+      } satisfies PostProcessShaderEntry;
+      // A feature may expose more than one graph-local fullscreen producer
+      // (the cloud display composite and its shadow map). Keep each resource
+      // addressable by its declared name and retain the feature identity alias
+      // for the original public post-process route.
+      fullscreenEffects.set(resource.name, entry);
+      if (!fullscreenEffects.has(identity)) fullscreenEffects.set(identity, entry);
     }
     const prepared = preparePlanResources(slot, frozen.value, graphics, gpu, input.targets ?? []);
     if (!prepared.ok) {
@@ -1499,8 +1584,34 @@ export function runRenderFeatureFrame(
       resolver === undefined
         ? undefined
         : (descriptor: import('./prepared-graphics').RenderFeatureGraphicsPassDescriptor) => {
-            const resolved = resolveGraphicsSnapshot(resolver, descriptor, transaction.generation);
-            if (!resolved.ok) resolver.release();
+            // A pending pass can be skipped while earlier passes remain usable.
+            // Keep their shared resolver leases alive until submission retires them.
+            const resolveGpuResource = (name: string) => {
+              const owned = prepared.value.buffers.get(name);
+              const borrowed = prepared.value.preparedGpuResources.get(name);
+              const reference =
+                owned ?? (borrowed?.kind === 'buffer' ? borrowed.reference : undefined);
+              return reference === undefined ? undefined : gpu?.resolveBuffer(reference);
+            };
+            const resolved = resolveGraphicsSnapshot(
+              resolver,
+              descriptor,
+              transaction.generation,
+              resolveGpuResource,
+            );
+            // A pending pipeline is a retryable partial frame. The resolver
+            // leases cover resources used by earlier ready passes and must
+            // stay retained until the submitted batch retires; only terminal
+            // resolution failures release them here.
+            if (
+              !resolved.ok &&
+              !(
+                resolved.error instanceof RenderFeaturePreparationFailedError &&
+                resolved.error.detail.reason === 'pipeline-pending'
+              )
+            ) {
+              resolver.release();
+            }
             return resolved;
           };
     const releaseResolver = (): void => {
@@ -1529,9 +1640,11 @@ export function runRenderFeatureFrame(
       host.setStatus(identity, 'failed', slot.latestError);
       continue;
     }
-    const graphicsLeases = projected.value.passes.flatMap(
-      (pass) => pass.resolvedGraphics?.leases ?? [],
-    );
+    // Include partial allocations from skipped pending passes, even when no pass
+    // completed. Fatal projection failures release the resolver above instead.
+    const graphicsLeases =
+      resolver?.leases ??
+      projected.value.passes.flatMap((pass) => pass.resolvedGraphics?.leases ?? []);
     if (graphicsLeases.length > 0) requiresPreparedResourceKey = true;
     const leases = [...new Set(graphicsLeases), ...(gpu?.retireUntouched() ?? [])];
     const retained = host.retainPreparedGraphics(identity, leases);
@@ -1564,6 +1677,7 @@ export function runRenderFeatureFrame(
     errors,
     plans,
     fullscreenEffects,
+    postProcessIdentities: Object.freeze([...postProcessIdentities]),
     preparedResourceBatches,
     requiresPreparedResourceKey,
     hiddenEntityReports: mergeHiddenEntityReports(hiddenEntityReports),

package/src/features/motion-blur/__tests__/motion-blur-feature.unit.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { SCENE_DATA_TEMPORAL_V1_SCHEMA } from '../../../temporal/scene-data';
 import { createSceneDataCatalog } from '../../../temporal/scene-data-catalog';
 import { freezeRenderFeaturePlan } from '../../plan';
-import { planMotionBlur } from '../motion-blur-feature';
+import { MOTION_BLUR_COMPUTE_WGSL, planMotionBlur } from '../motion-blur-feature';
 import { DEFAULT_MOTION_BLUR_PARAMS } from '../motion-blur-params';
 
 const caps = {
@@ -64,4 +64,114 @@ describe('Motion Blur feature plan', () => {
     expect(pass.sampledTargets).not.toContain('motion-depth');
     expect(catalog.schema).toBe(SCENE_DATA_TEMPORAL_V1_SCHEMA);
   });
+
+  it('selects one tile summary and one fused reconstruction on compute-capable targets', () => {
+    const computeCaps = {
+      rgba16floatRenderable: true,
+      compute: true,
+      storageBuffer: true,
+      storageTexture: true,
+    } as never;
+    const catalog = createSceneDataCatalog({
+      featureIdentity: 'forgeax.motion-blur',
+      generation: 4,
+      planIdentity: 'forgeax.motion-blur:4',
+      rgba16floatRenderable: true,
+    });
+    const targets = [
+      {
+        name: 'motion-input',
+        kind: 'color' as const,
+        format: 'rgba16float' as const,
+        sampleCount: 1 as const,
+      },
+      {
+        name: 'motion-output',
+        kind: 'color' as const,
+        format: 'rgba16float' as const,
+        sampleCount: 1 as const,
+      },
+    ];
+    const planned = planMotionBlur(
+      DEFAULT_MOTION_BLUR_PARAMS,
+      {
+        caps: computeCaps,
+        frame: { frameNumber: 7, width: 1920, height: 1080 },
+        generation: 4,
+        targets,
+        sceneData: catalog,
+      },
+      { frameDeltaSeconds: 1 / 60, reset: false },
+    );
+    expect(planned.ok).toBe(true);
+    if (!planned.ok) return;
+    const frozen = freezeRenderFeaturePlan('forgeax.motion-blur', planned.value, targets);
+    expect(frozen.ok).toBe(true);
+    if (!frozen.ok) return;
+
+    const computeProgram = frozen.value.resources.find(
+      (resource) => resource.kind === 'compute-program',
+    );
+    const tileSummary = frozen.value.resources.find(
+      (resource) => resource.kind === 'buffer' && resource.name === 'motion-blur-tile-summary',
+    );
+    expect(computeProgram?.kind).toBe('compute-program');
+    expect(tileSummary).toMatchObject({
+      kind: 'buffer',
+      size: Math.ceil(1920 / 16) * Math.ceil(1080 / 16) * 32,
+      usage: ['storage'],
+    });
+    expect(frozen.value.passes.map((pass) => pass.name)).toEqual([
+      'motion-blur-tile-summary',
+      'motion-blur',
+    ]);
+    expect(frozen.value.passes).toHaveLength(2);
+    expect(frozen.value.passes[0]).toMatchObject({
+      kind: 'compute',
+      dispatches: [{ entryPoint: 'tile_summary', workgroups: [120, 68, 1] }],
+    });
+    expect(frozen.value.passes[1]).toMatchObject({
+      kind: 'compute',
+      dispatches: [{ entryPoint: 'reconstruct', workgroups: [240, 135, 1] }],
+    });
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('2.0 * (f32(index) + 0.5) / denominator - 1.0');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let sourcePixel = workgroupBase');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('halfFilteredColor');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('workgroupBarrier()');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('if (!inBounds) {');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('depthReject');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('sourceVelocitySegmentCovers');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('TILE_NEIGHBORHOOD_COUNT');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('tileIntersectsWorkgroupSupport');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('tileNeighborhoodOffset');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('const EDGE_FILL_FACTOR : f32 = 0.99;');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let acceptedColor');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let acceptedAlpha');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let emptyReceiver');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let sourceScale');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let sourceContribution');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let trailScale');
+    expect(MOTION_BLUR_COMPUTE_WGSL).toContain('let outputAlpha');
+    expect(MOTION_BLUR_COMPUTE_WGSL).not.toContain('TILE_CANDIDATE_OFFSETS');
+    expect(MOTION_BLUR_COMPUTE_WGSL).not.toContain('atomic');
+    expect(MOTION_BLUR_COMPUTE_WGSL).not.toContain('textureSampleLevel');
+    if (computeProgram?.kind === 'compute-program') {
+      const entries = computeProgram.program.bindings?.[0]?.entries ?? [];
+      expect(entries.find((entry) => entry.binding === 2)?.buffer?.type).toBe('storage');
+      expect(entries.find((entry) => entry.binding === 3)?.storageTexture?.access).toBe(
+        'write-only',
+      );
+    }
+  });
+
+  it('compiles the compute lane WGSL before it reaches a backend', async () => {
+    const { compileShader } = await import(
+      /* @vite-ignore */
+      new URL('../../../../../shader-compiler/dist/index.mjs', import.meta.url).href
+    );
+    const compiled = await compileShader(MOTION_BLUR_COMPUTE_WGSL, {
+      id: 'forgeax::motion-blur-compute',
+    });
+    expect(compiled.ok, compiled.ok ? undefined : String(compiled.error)).toBe(true);
+  });
 });

package/src/features/motion-blur/__tests__/motion-blur-params.unit.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from 'vitest';
 import {
   DEFAULT_MOTION_BLUR_PARAMS,
+  effectiveMotionBlurSampleCount,
+  isMotionBlurIntervalValid,
+  motionBlurExposureScale,
+  motionBlurSampleDelta,
   motionBlurTemporalDemand,
   validateMotionBlurParams,
 } from '../motion-blur-params';
@@ -12,6 +16,7 @@ describe('Motion Blur parameter validation', () => {
       shutterAngle: 180,
       maxRadiusPixels: 32,
       sampleCount: 8,
+      targetFps: 60,
     });
   });
 
@@ -32,6 +37,9 @@ describe('Motion Blur parameter validation', () => {
     ['sampleCount', 3],
     ['sampleCount', 17],
     ['sampleCount', 8.5],
+    ['targetFps', -1],
+    ['targetFps', 240.5],
+    ['targetFps', 59.5],
   ] as const)('returns structured failure for %s=%s', (field, value) => {
     const result = validateMotionBlurParams({ [field]: value });
     expect(result.ok).toBe(false);
@@ -45,9 +53,56 @@ describe('Motion Blur parameter validation', () => {
 
   it('does no temporal work when omitted or shutter is zero', () => {
     expect(motionBlurTemporalDemand(undefined)).toBe(false);
-    expect(motionBlurTemporalDemand({ shutterAngle: 0, maxRadiusPixels: 32, sampleCount: 8 })).toBe(
-      false,
-    );
+    expect(
+      motionBlurTemporalDemand({
+        shutterAngle: 0,
+        maxRadiusPixels: 32,
+        sampleCount: 8,
+        targetFps: 60,
+      }),
+    ).toBe(false);
+    expect(
+      motionBlurTemporalDemand({
+        shutterAngle: 180,
+        maxRadiusPixels: 0,
+        sampleCount: 8,
+        targetFps: 60,
+      }),
+    ).toBe(false);
     expect(motionBlurTemporalDemand(DEFAULT_MOTION_BLUR_PARAMS)).toBe(true);
   });
+
+  it('rounds authored sample budgets down to the fixed shader tiers', () => {
+    expect(effectiveMotionBlurSampleCount(3)).toBe(0);
+    expect(effectiveMotionBlurSampleCount(4)).toBe(4);
+    expect(effectiveMotionBlurSampleCount(7)).toBe(4);
+    expect(effectiveMotionBlurSampleCount(8)).toBe(8);
+    expect(effectiveMotionBlurSampleCount(15)).toBe(8);
+    expect(effectiveMotionBlurSampleCount(16)).toBe(16);
+  });
+
+  it('rejects unstable intervals and scales displacement to the target rate', () => {
+    expect(isMotionBlurIntervalValid(1 / 60)).toBe(true);
+    expect(isMotionBlurIntervalValid(0)).toBe(false);
+    expect(isMotionBlurIntervalValid(0.101)).toBe(false);
+    expect(motionBlurExposureScale(1 / 60, 60)).toBeCloseTo(1);
+    expect(motionBlurExposureScale(1 / 120, 60)).toBeCloseTo(2);
+    expect(motionBlurExposureScale(1 / 60, 0)).toBe(1);
+    expect(motionBlurExposureScale(0, 60)).toBe(0);
+    expect(motionBlurExposureScale(1 / 60, 60.5)).toBe(0);
+    expect(motionBlurExposureScale(1 / 60, 241)).toBe(0);
+  });
+
+  it('keeps raw render hitches visible before ECS clamp policy', () => {
+    expect(motionBlurSampleDelta(1.2, 1, 0.1)).toBeCloseTo(0.2);
+    expect(motionBlurSampleDelta(1 / 30, 0, 0.1)).toBeCloseTo(1 / 30);
+    expect(isMotionBlurIntervalValid(motionBlurSampleDelta(1.2, 1, 0.1))).toBe(false);
+    expect(isMotionBlurIntervalValid(motionBlurSampleDelta(1 / 30, 0, 0.1))).toBe(true);
+    expect(motionBlurSampleDelta(undefined, undefined, 0.1)).toBe(0.1);
+  });
+
+  it('fails closed for an explicitly invalid host/replay sample', () => {
+    expect(Number.isNaN(motionBlurSampleDelta(Number.NaN, 1, 1 / 60))).toBe(true);
+    expect(Number.isNaN(motionBlurSampleDelta(1, Number.POSITIVE_INFINITY, 1 / 60))).toBe(true);
+  });
 });