@forgeax/engine-render 0.1.7 → 0.1.19

package/src/pipeline/standard-post.ts

@@ -0,0 +1,373 @@
+import type { CompiledRenderGraphInfo, GraphTextureDescriptor } from '@forgeax/engine-render-graph';
+import { RenderGraphError } from '@forgeax/engine-render-graph';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { addTypedDebugOverlayPass } from '../debug-draw-glue';
+import { SceneDataUnavailableError } from '../errors/render';
+import { addMotionBlurPass } from '../features/motion-blur/motion-blur-feature';
+import { GPU_TEXTURE_USAGE_COPY_SRC } from '../gpu-texture-usage';
+import type {
+  RenderPipelineBuildContext,
+  RenderPipelineBuildError,
+  RenderPipelineFrame,
+  RenderPipelineTopology,
+} from '../render-pipeline';
+import { createRenderPipelineTarget, type RenderPipelineTarget } from '../render-pipeline';
+import {
+  addTypedBloomPasses,
+  addTypedCompositePostEffects,
+  addTypedFullscreenPass,
+  addTypedOutputTransformPass,
+  addTypedTemporalResolvePass,
+  TYPED_BLOOM_PASS_NAMES,
+  type TypedTemporalResolveTargets,
+} from '../typed-render-graph-primitives';
+
+interface StandardPostSurface {
+  readonly display?: RenderPipelineTarget;
+  readonly storage: RenderPipelineTarget;
+}
+
+/** One authored Bloom contract drives declaration and compiled-graph validation. */
+export const STANDARD_BLOOM_TARGET_SPEC = {
+  composited: { label: 'bloom-composited', format: 'rgba16float', size: 'surface' },
+  bright: { label: 'bloom-bright', format: 'rgba16float', size: 'half-surface' },
+  blurH: { label: 'bloom-blur-h', format: 'rgba16float', size: 'half-surface' },
+  blurV: { label: 'bloom-blur-v', format: 'rgba16float', size: 'half-surface' },
+} as const satisfies Record<
+  'composited' | 'bright' | 'blurH' | 'blurV',
+  Pick<GraphTextureDescriptor, 'format' | 'size'> & { readonly label: string }
+>;
+
+export interface StandardBloomGraphInspection {
+  readonly status: 'empty' | 'valid' | 'invalid';
+  readonly targetCount: number;
+  readonly targetBytes: number;
+  readonly passCount: number;
+}
+
+const emptyBloomGraphInspection = (): StandardBloomGraphInspection => ({
+  status: 'empty',
+  targetCount: 0,
+  targetBytes: 0,
+  passCount: 0,
+});
+
+const invalidBloomGraphInspection = (): StandardBloomGraphInspection => ({
+  status: 'invalid',
+  targetCount: 0,
+  targetBytes: 0,
+  passCount: 0,
+});
+
+function textureBytes(
+  resource: CompiledRenderGraphInfo['resources'][number],
+  expected: (typeof STANDARD_BLOOM_TARGET_SPEC)[keyof typeof STANDARD_BLOOM_TARGET_SPEC],
+): number {
+  const descriptor = resource.descriptor;
+  if (
+    descriptor === undefined ||
+    descriptor.kind !== 'texture' ||
+    descriptor.format !== expected.format ||
+    !('size' in descriptor) ||
+    descriptor.size !== expected.size
+  )
+    return 0;
+  const texelBytes = 8;
+  let bytes = 0;
+  for (let level = 0; level < descriptor.mipLevelCount; level += 1) {
+    bytes +=
+      Math.max(1, descriptor.width >> level) *
+      Math.max(1, descriptor.height >> level) *
+      descriptor.depthOrArrayLayers *
+      texelBytes;
+  }
+  return bytes * descriptor.sampleCount;
+}
+
+/** Derive Bloom target/pass facts solely from the compiled Standard graph. */
+export function inspectStandardBloomGraph(
+  graph: CompiledRenderGraphInfo | undefined,
+): StandardBloomGraphInspection {
+  if (graph === undefined) return emptyBloomGraphInspection();
+  type BloomTargetSpec =
+    (typeof STANDARD_BLOOM_TARGET_SPEC)[keyof typeof STANDARD_BLOOM_TARGET_SPEC];
+  const targetSpec = new Map<string, BloomTargetSpec>(
+    Object.values(STANDARD_BLOOM_TARGET_SPEC).map((entry) => [entry.label, entry] as const),
+  );
+  const targets = graph.resources.flatMap((resource) => {
+    const expected = targetSpec.get(resource.label);
+    return expected === undefined ? [] : [{ resource, expected }];
+  });
+  const passNames = new Set<string>(Object.values(TYPED_BLOOM_PASS_NAMES));
+  const passes = graph.passes.filter((pass) => passNames.has(pass.name));
+  if (targets.length === 0 && passes.length === 0) return emptyBloomGraphInspection();
+  const completeTargetSet =
+    targets.length === Object.values(STANDARD_BLOOM_TARGET_SPEC).length &&
+    targets.every(({ resource, expected }) => textureBytes(resource, expected) > 0);
+  const completePassSet = passes.length === Object.values(TYPED_BLOOM_PASS_NAMES).length;
+  if (!completeTargetSet || !completePassSet) {
+    return invalidBloomGraphInspection();
+  }
+  return {
+    status: 'valid',
+    targetCount: targets.length,
+    targetBytes: targets.reduce(
+      (bytes, target) => bytes + textureBytes(target.resource, target.expected),
+      0,
+    ),
+    passCount: passes.length,
+  };
+}
+
+function target(
+  context: RenderPipelineBuildContext<RenderPipelineFrame>,
+  label: string,
+  descriptor: GraphTextureDescriptor,
+): Result<RenderPipelineTarget, RenderGraphError> {
+  return createRenderPipelineTarget(context.graph, label, descriptor);
+}
+
+function missingTemporalContributor(
+  topology: RenderPipelineTopology,
+  contributorId: string,
+): SceneDataUnavailableError {
+  return new SceneDataUnavailableError({
+    featureIdentity: 'forgeax::standard',
+    schema: 'forgeax::scene-data::temporal-v1',
+    lane: topology.lane.compute ? (topology.standardProfile?.lighting ?? 'direct') : 'cpu-webgl2',
+    reason: 'producer-missing',
+    missingContributorIds: [contributorId],
+    omittedMissingContributorCount: 0,
+    recovery: 'renderer-recover',
+  });
+}
+
+/**
+ * Build the one Standard post chain shared by direct and clustered lighting.
+ * Bloom is admitted before any Bloom target is declared, keeping the disabled
+ * path exact-zero while preserving the existing half-resolution four-pass
+ * implementation for the enabled path.
+ */
+export function addStandardPost(
+  context: RenderPipelineBuildContext<RenderPipelineFrame>,
+  topology: RenderPipelineTopology,
+  scene: RenderPipelineTarget,
+  depth: RenderPipelineTarget,
+  surface: StandardPostSurface,
+  sceneTemporal?: RenderPipelineTarget,
+): Result<void, RenderPipelineBuildError> {
+  const clearOnly = topology.clearOnly === true;
+  const hdr =
+    !clearOnly && (topology.camera.tonemap !== 'none' || topology.camera.antialias === 'taa');
+  // Bloom is an HDR-domain effect and its recorders intentionally no-op when
+  // tone mapping is disabled. Keep the graph in the same no-op state for the
+  // TAA + tonemap:none combination; otherwise the declared Bloom composite is
+  // left clear and the following Output Transform presents a black frame.
+  const bloomActive = hdr && topology.camera.bloom === 'on' && topology.camera.tonemap !== 'none';
+  const fxaa = !clearOnly && topology.camera.antialias === 'fxaa';
+  const msaa = !clearOnly && topology.camera.antialias === 'msaa' && topology.lane.multisample;
+  const linearLdr = !clearOnly && ((!hdr && topology.lane.storageBuffer) || fxaa || msaa);
+  const rawOnly = !clearOnly && topology.surface.profile?.kind === 'raw-only';
+  const motionBlur = !clearOnly && topology.temporal?.motionBlur === true;
+  const postEffects = clearOnly ? [] : (topology.config?.postEffects ?? []);
+  const rawOnlyPostInput =
+    rawOnly && topology.lane.storageBuffer && postEffects.length > 0
+      ? target(context, 'standard-post-effects-input', {
+          format: 'rgba16float',
+          size: 'surface',
+          usage: GPU_TEXTURE_USAGE_COPY_SRC,
+          domain: 'display-encoded',
+        })
+      : undefined;
+  if (rawOnlyPostInput !== undefined && !rawOnlyPostInput.ok) return rawOnlyPostInput;
+  // Every Standard route terminates at the same encoded raw storage endpoint.
+  // The raw-only profile has no alternate display view, so its debug overlay
+  // and optional post effects are kept in graph-owned float targets until the
+  // single Output Transform performs the first 8-bit quantization.
+  const finalPresent = surface.storage;
+  let postInput = scene;
+
+  if (topology.camera.antialias === 'taa') {
+    if (sceneTemporal === undefined) {
+      return err(missingTemporalContributor(topology, 'forgeax::standard::scene-data'));
+    }
+    const history = context.taaHistory;
+    if (history === undefined) {
+      return err(missingTemporalContributor(topology, 'forgeax::standard::taa-history'));
+    }
+    const resolveTargets: TypedTemporalResolveTargets = {
+      scene,
+      depth,
+      currentTemporal: sceneTemporal,
+      historyColor: history.previousColor,
+      historyTemporal: history.previousTemporal,
+      writeColor: history.currentColor,
+      writeTemporal: history.currentTemporal,
+    };
+    const resolve = addTypedTemporalResolvePass(context.graph, resolveTargets);
+    if (!resolve.ok) return resolve;
+    postInput = history.currentColor;
+  }
+
+  // Feature projection and the built-in fallback share one target contract.
+  // The projection runs after TAA so Motion Blur consumes the resolved color,
+  // then both paths feed the same linear float target into Bloom/Output.
+  if (!clearOnly) {
+    const featureTargets = [
+      {
+        kind: 'scene-color' as const,
+        texture: scene.texture,
+        view: scene.view,
+        format: scene.format,
+        sampleCount: scene.sampleCount,
+      },
+      {
+        kind: 'scene-depth' as const,
+        texture: depth.texture,
+        view: depth.view,
+        format: depth.format,
+        sampleCount: depth.sampleCount,
+      },
+    ];
+    if (motionBlur) {
+      if (sceneTemporal === undefined) {
+        return err(
+          new Error('Motion Blur requires the Standard scene-data producer') as RenderGraphError,
+        );
+      }
+      const blurred = target(context, 'motion-blurred-color', {
+        format: 'rgba16float',
+        size: 'surface',
+        domain: hdr ? 'linear-hdr' : 'linear-ldr',
+      });
+      if (!blurred.ok) return blurred;
+      const features = context.contributeFeatures(featureTargets, [sceneTemporal], {
+        'motion-input': postInput,
+        'motion-output': blurred.value,
+      });
+      if (!features.ok) return features;
+      if (context.hasFeature?.('forgeax.motion-blur') === true) {
+        postInput = blurred.value;
+      } else {
+        const fallback = addMotionBlurPass(context.graph, postInput, sceneTemporal, blurred.value);
+        if (!fallback.ok) return fallback;
+        postInput = blurred.value;
+      }
+    } else {
+      const features = context.contributeFeatures(
+        featureTargets,
+        sceneTemporal === undefined ? [] : [sceneTemporal],
+      );
+      if (!features.ok) return features;
+    }
+  }
+
+  if (bloomActive) {
+    const composited = target(
+      context,
+      STANDARD_BLOOM_TARGET_SPEC.composited.label,
+      STANDARD_BLOOM_TARGET_SPEC.composited,
+    );
+    if (!composited.ok) return composited;
+    const bright = target(
+      context,
+      STANDARD_BLOOM_TARGET_SPEC.bright.label,
+      STANDARD_BLOOM_TARGET_SPEC.bright,
+    );
+    if (!bright.ok) return bright;
+    const blurH = target(
+      context,
+      STANDARD_BLOOM_TARGET_SPEC.blurH.label,
+      STANDARD_BLOOM_TARGET_SPEC.blurH,
+    );
+    if (!blurH.ok) return blurH;
+    const blurV = target(
+      context,
+      STANDARD_BLOOM_TARGET_SPEC.blurV.label,
+      STANDARD_BLOOM_TARGET_SPEC.blurV,
+    );
+    if (!blurV.ok) return blurV;
+    const bloom = addTypedBloomPasses(context.graph, {
+      scene: postInput,
+      composited: composited.value,
+      bright: bright.value,
+      blurH: blurH.value,
+      blurV: blurV.value,
+    });
+    if (!bloom.ok) return bloom;
+    postInput = composited.value;
+  }
+
+  if (rawOnly) {
+    const overlay = addTypedDebugOverlayPass(context.graph, postInput);
+    if (!overlay.ok) return overlay;
+  }
+
+  if (hdr || linearLdr || fxaa || rawOnly || motionBlur) {
+    if (fxaa) {
+      const output = target(context, 'standard-output-color', {
+        format: 'rgba16float',
+        size: 'surface',
+        usage: GPU_TEXTURE_USAGE_COPY_SRC,
+        domain: 'display-encoded',
+      });
+      if (!output.ok) return output;
+      const outputTransform = addTypedOutputTransformPass(context.graph, postInput, output.value);
+      if (!outputTransform.ok) return outputTransform;
+      const aa = addTypedFullscreenPass(context.graph, {
+        name: 'fxaa',
+        shader: 'fxaa',
+        input: output.value,
+        output: rawOnlyPostInput !== undefined ? rawOnlyPostInput.value : finalPresent,
+      });
+      if (!aa.ok) return aa;
+    } else if (rawOnlyPostInput !== undefined) {
+      const transformed = addTypedOutputTransformPass(
+        context.graph,
+        postInput,
+        rawOnlyPostInput.value,
+      );
+      if (!transformed.ok) return transformed;
+    } else if (rawOnly || linearLdr) {
+      const transformed = addTypedOutputTransformPass(context.graph, postInput, finalPresent);
+      if (!transformed.ok) return transformed;
+    } else {
+      const outputTransform = addTypedOutputTransformPass(context.graph, postInput, finalPresent);
+      if (!outputTransform.ok) return outputTransform;
+    }
+  }
+
+  if (topology.lane.storageBuffer && postEffects.length > 0) {
+    const postInputTarget = rawOnly
+      ? rawOnlyPostInput?.value
+      : (surface.display ?? surface.storage);
+    if (postInputTarget === undefined) {
+      return err(
+        new RenderGraphError({
+          code: 'resource-descriptor-invalid',
+          expected: 'raw-only post effects have a graph-owned encoded input target',
+          hint: 'retain the candidate LKG when the post-effect input target cannot be declared',
+          detail: {
+            resourceLabel: 'standard-post-effects-input',
+            field: 'descriptor',
+            expected: 'rgba16float display-encoded target',
+            actual: 'absent',
+          },
+        }),
+      );
+    }
+    const effects = addTypedCompositePostEffects(
+      context.graph,
+      postEffects,
+      postInputTarget,
+      surface.storage,
+      depth,
+      topology.surface,
+    );
+    if (!effects.ok) return effects;
+  }
+
+  return rawOnly
+    ? ok(undefined)
+    : addTypedDebugOverlayPass(context.graph, surface.display ?? surface.storage);
+}

package/src/pipeline/standard-profile.ts

@@ -20,7 +20,15 @@ export type StandardTone =
   | 'reinhard'
   | 'reinhard-extended';
 export type StandardAntialias = 'none' | 'fxaa' | 'msaa';
-export type StandardPostStage = 'transparent-blend' | 'bloom' | 'tone' | 'fxaa' | 'output';
+export const STANDARD_POST_STAGE_NAMES = [
+  'transparent-blend',
+  'bloom',
+  'output-transform',
+  'fxaa',
+  'post-effect',
+  'present',
+] as const;
+export type StandardPostStage = (typeof STANDARD_POST_STAGE_NAMES)[number];
 
 export interface StandardProfile {
   readonly pipelineId: typeof STANDARD_PIPELINE_ID;
@@ -30,12 +38,8 @@ export interface StandardProfile {
   readonly pbr: boolean;
   readonly ibl: boolean;
   readonly ssao: boolean;
-  readonly bloom: boolean;
-  readonly tone: StandardTone;
-  readonly antialias: StandardAntialias;
-  readonly sky: boolean;
   readonly fallback: StandardFallbackLane;
-  readonly postStages: readonly ['transparent-blend', 'bloom', 'tone', 'fxaa', 'output'];
+  readonly postStages: typeof STANDARD_POST_STAGE_NAMES;
 }
 
 export const DEFAULT_STANDARD_PROFILE: StandardProfile = Object.freeze({
@@ -46,12 +50,8 @@ export const DEFAULT_STANDARD_PROFILE: StandardProfile = Object.freeze({
   pbr: true,
   ibl: true,
   ssao: false,
-  bloom: true,
-  tone: 'aces-filmic',
-  antialias: 'fxaa',
-  sky: true,
   fallback: 'native',
-  postStages: ['transparent-blend', 'bloom', 'tone', 'fxaa', 'output'] as const,
+  postStages: STANDARD_POST_STAGE_NAMES,
 });
 
 export type StandardLane = StandardLightingLane | 'cpu-webgl2';

package/src/pipeline-builder.ts

@@ -43,6 +43,7 @@
 
 import {
   err,
+  ok,
   type PipelineLayout,
   type RenderPipeline,
   type RenderPipelineDescriptor,
@@ -130,6 +131,8 @@ export interface PipelineBuilderContext {
    * feat).
    */
   readonly vertexBuffers: readonly GPUVertexBufferLayout[];
+  /** Explicit layout family selected by the renderer assembly. */
+  readonly layoutKind?: 'pbr-skin' | undefined;
   /** Pipeline label (for GPU debug captures); defaults to `pbr-pipeline-${id}`. */
   readonly label?: string | undefined;
   /**
@@ -150,6 +153,81 @@ export interface PipelineBuilderContext {
    * `moduleLabel` so two `#define` prefixes do not collide on one module.
    */
   readonly moduleLabel?: string | undefined;
+  /** Device facts used to reject a temporal PSO before it reaches submit. */
+  readonly capabilities?: {
+    readonly storageBuffer: boolean;
+    readonly rgba16floatRenderable: boolean;
+  };
+}
+
+/**
+ * Validate the temporal material contract at the PSO creation boundary.
+ *
+ * Downlevel WebGL2 implementations can accept a pipeline whose shader/layout
+ * pair is invalid and report the failure only when the command buffer is
+ * submitted. The temporal producer is the one material path where this is
+ * especially damaging: the invalid handle is cached and every frame then
+ * fails. Keep this check beside descriptor construction so the caller gets a
+ * structured shader failure before a handle is cached.
+ */
+export function validateTemporalPipelineContract(
+  source: string,
+  ctx: Pick<PipelineBuilderContext, 'colorFormat' | 'depthFormat' | 'capabilities'>,
+): Result<void, RhiError> {
+  if (!source.includes('fn vs_temporal') || !source.includes('fn fs_temporal')) {
+    return err(
+      new RhiError({
+        code: 'shader-compile-failed',
+        expected: 'temporal material source declares vs_temporal and fs_temporal entry points',
+        hint: 'compile the temporal material variant that owns the temporal producer ABI',
+      }),
+    );
+  }
+  if (ctx.colorFormat !== 'rgba16float') {
+    return err(
+      new RhiError({
+        code: 'shader-compile-failed',
+        expected: 'temporal material target format is rgba16float',
+        hint: `temporal producer received color format ${ctx.colorFormat}; use its physical rgba16float target`,
+      }),
+    );
+  }
+  if (ctx.depthFormat === undefined) {
+    return err(
+      new RhiError({
+        code: 'shader-compile-failed',
+        expected: 'temporal material pipeline has a depth format',
+        hint: 'provide the shared scene depth attachment for the temporal producer',
+      }),
+    );
+  }
+  const capabilities = ctx.capabilities;
+  if (capabilities !== undefined) {
+    const sourceUsesStorageBuffer = /var\s*<\s*storage(?:\s*,|\s*>)/u.test(source);
+    if (sourceUsesStorageBuffer !== capabilities.storageBuffer) {
+      return err(
+        new RhiError({
+          code: 'shader-compile-failed',
+          expected: `temporal shader storage-buffer variant matches device capability (${capabilities.storageBuffer})`,
+          hint: 'resolve the material variant against the active WebGL2/native capability before creating the PSO',
+        }),
+      );
+    }
+    if (!capabilities.rgba16floatRenderable) {
+      return err(
+        new RhiError({
+          code: 'shader-compile-failed',
+          expected: 'rgba16float temporal target is renderable on the active device',
+          hint: 'preserve the structured capability refusal instead of creating a deferred-invalid PSO',
+        }),
+      );
+    }
+  }
+  return ok(undefined);
+}
+
+function pipelineCreationHint(error: RhiError): string {
+  return `inspect compiler messages on the shader module; verify pipeline layout matches shader bindings (cause: ${error.code}; underlying hint: ${error.hint}; raw: ${error.message})`;
 }
 
 /**
@@ -194,8 +272,10 @@ export function buildPipelineForMaterialShader(
   sampleCount: number = 1,
 ): Result<RenderPipeline, RhiError> {
   const label = ctx.label ?? `pbr-pipeline-${id}`;
-  const vsEntry = vertexEntry ?? 'vs_main';
-  const fsEntry = fragmentEntry ?? (passKind === 'deferred' ? 'fs_gbuffer' : 'fs_main');
+  const vsEntry = vertexEntry ?? (passKind === 'temporal' ? 'vs_temporal' : 'vs_main');
+  const fsEntry =
+    fragmentEntry ??
+    (passKind === 'temporal' ? 'fs_temporal' : passKind === 'deferred' ? 'fs_gbuffer' : 'fs_main');
 
   let source = entry.source;
   if (defines !== undefined && Object.keys(defines).length > 0) {
@@ -226,6 +306,11 @@ export function buildPipelineForMaterialShader(
   }
   const shaderModule = moduleResult.value;
 
+  if (passKind === 'temporal') {
+    const temporalContract = validateTemporalPipelineContract(source, ctx);
+    if (!temporalContract.ok) return temporalContract;
+  }
+
   // feat-20260609 M4 / R3-fixup: shadow-caster branch.
   // The shadow render pass beginRenderPass desc is `{ colorAttachments: [],
   // depthStencilAttachment: { format: 'depth32float', ... } }` (see
@@ -235,8 +320,10 @@ export function buildPipelineForMaterialShader(
   // compatible with [RenderPassEncoder]". Ground truth descriptor was the
   // hardcoded shadowCasterPipeline removed in T-009 (commit 6416e9de~);
   // this branch reconstructs that exact shape via the lazy cache path.
-  // Vertex layout is position-only (12-float stride, shaderLocation 0 vec3)
-  // — the shadow_caster.wgsl vs_main reads only @location(0) position.
+  // The ordinary shadow variant reads only position from the canonical 12F
+  // layout. The skinned variant additionally reads JOINTS_0 / WEIGHTS_0;
+  // both layouts come from the same geometry projection used by the main
+  // pass, so shadow rendering cannot silently reinterpret an 18F stream.
   if (colorFormatsForPassKind(passKind, ctx.colorFormat).length === 0) {
     // bug-20260619-csm RC-3 (AC-10): a material may supply a custom
     // ShadowCaster pass shader that carries a fragment stage (e.g. an
@@ -255,12 +342,15 @@ export function buildPipelineForMaterialShader(
       vertex: {
         module: shaderModule,
         entryPoint: vsEntry,
-        buffers: [
-          {
-            arrayStride: 12 * 4,
-            attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' as const }],
-          },
-        ],
+        buffers:
+          ctx.layoutKind === 'pbr-skin'
+            ? [...ctx.vertexBuffers]
+            : [
+                {
+                  arrayStride: 12 * 4,
+                  attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' as const }],
+                },
+              ],
       },
       // Vertex-only depth pass writes `fragment: undefined` (GPU derives
       // depth from gl_Position.z). A custom ShadowCaster shader with a
@@ -295,7 +385,7 @@ export function buildPipelineForMaterialShader(
         new RhiError({
           code: 'shader-compile-failed',
           expected: `shadow-caster pipeline for material shader '${id}' builds successfully`,
-          hint: `inspect compiler messages on the shader module; verify pipeline layout matches shader bindings (cause: ${shadowPipelineResult.error.code})`,
+          hint: pipelineCreationHint(shadowPipelineResult.error),
         }),
       );
     }
@@ -374,7 +464,7 @@ export function buildPipelineForMaterialShader(
       new RhiError({
         code: 'shader-compile-failed',
         expected: `pipeline for material shader '${id}' builds successfully`,
-        hint: `inspect compiler messages on the shader module; verify pipeline layout matches shader bindings (cause: ${pipelineResult.error.code})`,
+        hint: pipelineCreationHint(pipelineResult.error),
       }),
     );
   }

package/src/pipeline-spec.ts

@@ -513,6 +513,15 @@ export const passKindPolicyTable: Readonly<Record<string, PassKindAttachmentPoli
     },
     defaultDepthOps: { loadOp: 'clear', storeOp: 'store', clearValue: 1 },
   },
+  temporal: {
+    shape: 'color-and-depth',
+    defaultColorOps: {
+      loadOp: 'clear',
+      storeOp: 'store',
+      clearValue: { r: 0, g: 0, b: -1, a: 1 },
+    },
+    defaultDepthOps: { loadOp: 'clear', storeOp: 'store', clearValue: 1 },
+  },
   'shadow-caster': {
     shape: 'depth-only',
     defaultColorOps: undefined,

package/src/plugin.ts

@@ -1,5 +1,6 @@
 import type { Component, World } from '@forgeax/engine-ecs';
 import type { Plugin } from '@forgeax/engine-plugin';
+import { Atmosphere } from './components/atmosphere';
 import { Camera } from './components/camera';
 import { DirectionalLight } from './components/directional-light';
 import { Instances } from './components/instances';
@@ -24,6 +25,7 @@ import { Tilemap } from './components/tilemap';
 import { Visibility } from './components/visibility';
 
 const RENDER_COMPONENTS: readonly Component[] = [
+  Atmosphere,
   Camera,
   DirectionalLight,
   Instances,

package/src/record/__tests__/fullscreen-temporal-routing.unit.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { isTemporalFullscreenBinding } from '../../fullscreen-post-process-pass';
+import { shouldUseTemporalFrameTransaction } from '../typed-frame-graph';
+
+describe('fullscreen temporal routing', () => {
+  it('keeps ordinary fullscreen bindings on the non-temporal path', () => {
+    expect(isTemporalFullscreenBinding({ fullscreen: true, shader: 'forgeax.fxaa' })).toBe(false);
+    expect(isTemporalFullscreenBinding({ fullscreen: true, shader: 'forgeax.tonemap' })).toBe(
+      false,
+    );
+    expect(isTemporalFullscreenBinding({ fullscreen: true, shader: 'forgeax.motion-blur' })).toBe(
+      true,
+    );
+    expect(
+      isTemporalFullscreenBinding({ fullscreen: true, temporal: { kind: 'scene-data' } }),
+    ).toBe(true);
+  });
+
+  it('opens the coordinator only for TAA frames', () => {
+    expect(shouldUseTemporalFrameTransaction('none')).toBe(false);
+    expect(shouldUseTemporalFrameTransaction('fxaa')).toBe(false);
+    expect(shouldUseTemporalFrameTransaction('msaa')).toBe(false);
+    expect(shouldUseTemporalFrameTransaction('taa')).toBe(true);
+  });
+});