@forgeax/engine-render 0.1.33 → 0.1.35

package/src/errors/cloud.ts

@@ -0,0 +1,103 @@
+/** Closed errors produced by the CloudLayer authoring and resource route. */
+
+export interface CloudLayerInvalidParameterDetail {
+  readonly field: string;
+  readonly value: unknown;
+  readonly expected: string;
+}
+
+export class CloudLayerInvalidParameterError extends Error {
+  readonly code = 'cloud-layer-invalid-parameter' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: CloudLayerInvalidParameterDetail;
+
+  constructor(field: string, value: unknown, expected: string) {
+    super(`CloudLayer.${field} is invalid`);
+    this.name = 'CloudLayerInvalidParameterError';
+    this.expected = `CloudLayer.${field} must be ${expected}`;
+    this.hint = `set CloudLayer.${field} to ${expected}`;
+    this.detail = { field, value, expected };
+  }
+}
+
+export interface CloudLayerOwnerConflictDetail {
+  readonly count: number;
+}
+
+export class CloudLayerOwnerConflictError extends Error {
+  readonly code = 'cloud-layer-owner-conflict' as const;
+  readonly expected = 'at most one CloudLayer owns a World frame';
+  readonly hint = 'remove additional CloudLayer owners before extraction';
+  readonly detail: CloudLayerOwnerConflictDetail;
+
+  constructor(count: number) {
+    super(`CloudLayer owner cardinality is ${count}`);
+    this.name = 'CloudLayerOwnerConflictError';
+    this.detail = { count };
+  }
+}
+
+export interface CloudLayerCacheInvalidDetail {
+  readonly sourceKey: string;
+  readonly reason: string;
+}
+
+export class CloudLayerCacheInvalidError extends Error {
+  readonly code = 'cloud-layer-cache-invalid' as const;
+  readonly expected = 'the density cache payload matches its reconstructible source';
+  readonly hint = 'discard the derived cache and rebuild it from CloudLayer source facts';
+  readonly detail: CloudLayerCacheInvalidDetail;
+
+  constructor(sourceKey: string, reason: string) {
+    super(`CloudLayer cache is invalid: ${reason}`);
+    this.name = 'CloudLayerCacheInvalidError';
+    this.detail = { sourceKey, reason };
+  }
+}
+
+export interface CloudLayerCapabilityMissingDetail {
+  readonly capability: string;
+}
+
+export class CloudLayerCapabilityMissingError extends Error {
+  readonly code = 'cloud-layer-capability-missing' as const;
+  readonly expected = 'the selected backend exposes the capability required by the cloud lane';
+  readonly hint =
+    'inspect the capability report, disable the cloud lane on this backend, or retry on a backend with the required capability';
+  readonly detail: CloudLayerCapabilityMissingDetail;
+
+  constructor(capability: string) {
+    super(`CloudLayer capability is unavailable: ${capability}`);
+    this.name = 'CloudLayerCapabilityMissingError';
+    this.detail = { capability };
+  }
+}
+
+export interface CloudLayerResourceFailureDetail {
+  readonly stage: 'cache' | 'shadow' | 'view' | 'history' | 'retire';
+  readonly generation: number;
+  readonly cause?: unknown;
+}
+
+export class CloudLayerResourceFailureError extends Error {
+  readonly code = 'cloud-layer-resource-failed' as const;
+  readonly expected = 'cloud resources are created, submitted and retired as one generation';
+  readonly hint = 'keep the last-known-good cloud generation and retry after recovery';
+  readonly detail: CloudLayerResourceFailureDetail;
+
+  constructor(detail: CloudLayerResourceFailureDetail) {
+    super(`CloudLayer ${detail.stage} resource failed at generation ${detail.generation}`);
+    this.name = 'CloudLayerResourceFailureError';
+    this.detail = detail;
+  }
+}
+
+export type CloudLayerError =
+  | CloudLayerInvalidParameterError
+  | CloudLayerOwnerConflictError
+  | CloudLayerCacheInvalidError
+  | CloudLayerCapabilityMissingError
+  | CloudLayerResourceFailureError;
+
+export type CloudLayerErrorCode = CloudLayerError['code'];

package/src/errors/render.ts

@@ -1,3 +1,4 @@
+import type { RenderPublicationError } from '../publication/contract';
 // @forgeax/engine-render -- render cluster error classes.
 //
 // feat-20260704-runtime-tier1-decomposition M2 / w8 (D-3): the monolithic
@@ -30,6 +31,7 @@ import type {
 import type { AutoExposureError } from '../pipeline/standard-output/auto-exposure/inspection';
 import type { SceneDataLane, SceneDataSchemaId } from '../temporal/scene-data';
 import type { TransmissionCapabilityFact } from '../transmission/backdrop';
+import type { CloudLayerError } from './cloud';
 import type { RecoveryOutcome, RecoveryPhase } from './recover';
 
 // Public render errors keep one machine-readable order: closed `code`,
@@ -561,7 +563,7 @@ export class PointShadowAtlasBoundsViolationError extends Error {
  * Fired by the per-frame record stage (`videoTextureView`) when a VideoPlayer
  * entity can reach neither video upload path this frame: the general
  * `copyExternalImageToTexture` path (no host HTMLVideoElement resolved via
- * `VideoElementProvider`) AND the high-perf `GPUExternalTexture` path
+ * `VideoSourceProvider`) AND the high-perf `GPUExternalTexture` path
  * (capability absent). The engine surfaces this explicit failure rather than
  * silently rendering a stale/garbage texture (charter P3, plan-strategy D-6).
  *   - `.code = 'video-upload-unsupported'`
@@ -1392,6 +1394,27 @@ export type DynamicResolutionError =
   | DynamicResolutionRequiresTaaError
   | DynamicResolutionTimingUnavailableError;
 
+export interface BarrelDistortionInvalidParameterDetail {
+  readonly field: 'width' | 'height' | 'strength' | 'centerX' | 'centerY';
+  readonly value: number;
+  readonly expected: string;
+}
+
+export class BarrelDistortionInvalidParameterError extends Error {
+  readonly code = 'barrel-distortion-invalid-parameter' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: BarrelDistortionInvalidParameterDetail;
+
+  constructor(detail: BarrelDistortionInvalidParameterDetail) {
+    super(`BarrelDistortion.${detail.field} is invalid`);
+    this.name = 'BarrelDistortionInvalidParameterError';
+    this.expected = `BarrelDistortion.${detail.field} must be ${detail.expected}`;
+    this.hint = `set BarrelDistortion.${detail.field} to a value that is ${detail.expected}`;
+    this.detail = detail;
+  }
+}
+
 export interface OwnerStageFailedDetail {
   readonly owner: 'environment' | 'temporal' | 'fog' | 'renderer';
   readonly stage: 'extract' | 'prepare' | 'record' | 'finish' | 'submit';
@@ -1839,8 +1862,8 @@ export interface VolumeOwnerConflictDetail {
 
 export class VolumeOwnerConflictError extends Error {
   readonly code = 'volume-owner-conflict' as const;
-  readonly expected = 'exactly one global VolumetricFog owner is authored';
-  readonly hint = 'remove additional VolumetricFog owners and retry extraction';
+  readonly expected = 'at most eight local VolumetricFog owners per rendered World';
+  readonly hint = 'reduce simultaneously visible volume owners and retry extraction';
   readonly detail: VolumeOwnerConflictDetail;
 
   constructor(ownerCount: number) {
@@ -1894,13 +1917,26 @@ export interface VolumeInvalidParametersDetail {
 export class VolumeInvalidParametersError extends Error {
   readonly code = 'volume-invalid-parameters' as const;
   readonly expected = 'volume parameters remain finite and inside their closed ranges';
-  readonly hint = 'repair extinction, albedo, emission, anisotropy, or maxDistance';
+  readonly hint = 'repair extinction, albedo, emission, anisotropy, maxDistance, or sampling';
   readonly detail: VolumeInvalidParametersDetail;
 
-  constructor(input: { readonly maxDistance?: number; readonly anisotropy?: number }) {
-    const field =
-      input.maxDistance !== undefined && input.maxDistance <= 0 ? 'maxDistance' : 'parameters';
-    const value = field === 'maxDistance' ? input.maxDistance : input.anisotropy;
+  constructor(input: {
+    readonly maxDistance?: number;
+    readonly anisotropy?: number;
+    readonly sampling?: string;
+  }) {
+    const invalidSampling =
+      input.sampling !== undefined && input.sampling !== 'noise' && input.sampling !== 'density';
+    const field = invalidSampling
+      ? 'sampling'
+      : input.maxDistance !== undefined && input.maxDistance <= 0
+        ? 'maxDistance'
+        : 'parameters';
+    const value = invalidSampling
+      ? input.sampling
+      : field === 'maxDistance'
+        ? input.maxDistance
+        : input.anisotropy;
     super(`volume-invalid-parameters: ${field} is outside the authored range`);
     this.name = 'VolumeInvalidParametersError';
     this.detail = { field, value };
@@ -1945,6 +1981,7 @@ export type RenderErrorCode = RenderError['code'];
  * `RenderErrorCode` discriminant on `.code`.
  */
 export type RenderError =
+  | RenderPublicationError
   | LifecycleConstructionError
   | AutoExposureError
   | RendererExpectedOperationError
@@ -1981,6 +2018,8 @@ export type RenderError =
   | TaaCapsInsufficientError
   | EnvironmentGenerationFailedError
   | AtmosphereInvalidParameterError
+  | BarrelDistortionInvalidParameterError
+  | CloudLayerError
   | DynamicResolutionInvalidParameterError
   | DynamicResolutionRequiresTaaError
   | DynamicResolutionTimingUnavailableError

package/src/examples/single-layer-medium-surface.ts

@@ -0,0 +1,59 @@
+import type { MaterialRootAsset } from '@forgeax/engine-types';
+
+/**
+ * A public root asset showing the model declaration and its bounded input.
+ * The page is shared by every material instance; Render supplies the page
+ * bytes and each instance publishes its own range.
+ */
+export const SINGLE_LAYER_MEDIUM_SURFACE_EXAMPLE = {
+  kind: 'material',
+  surface: {
+    model: 'single-layer-medium',
+    module: 'game::water_surface_a',
+    dynamicInput: {
+      name: 'waterEvents',
+      fields: [
+        { name: 'position', type: 'vec3<f32>' },
+        { name: 'time', type: 'f32' },
+        { name: 'eventId', type: 'u32' },
+      ],
+      maxRecords: 64,
+      maxDomains: 8,
+      maxPageBytes: 2048,
+      maxBindings: 1,
+      maxEventsPerSample: 8,
+    },
+  },
+  passes: [
+    {
+      name: 'color',
+      program: { module: 'forgeax::single-layer-medium' },
+    },
+  ],
+  parameters: [],
+  values: {},
+} as const satisfies MaterialRootAsset;
+
+/** Two different imported Surface implementations consuming one model ABI. */
+export const SINGLE_LAYER_MEDIUM_SURFACE_EXAMPLES = [
+  {
+    module: 'game::water_surface_a',
+    source: `#define_import_path game::water_surface_a
+#import forgeax_material::single_layer_medium_surface_v1::{SingleLayerMediumSurfaceInput, SingleLayerMediumSurfaceData}
+fn evaluate_surface(input : SingleLayerMediumSurfaceInput) -> SingleLayerMediumSurfaceData {
+  let event = read_waterEvents(input.eventRangeStart);
+  let normal = normalize(input.geometricNormalWS + vec3<f32>(0.0, 0.0, event.time * 0.02));
+  return SingleLayerMediumSurfaceData(normal, 0.18, 1.0, 0.0, vec3<f32>(0.18, 0.06, 0.02), vec3<f32>(0.02, 0.04, 0.08), 1.333, 0.2, 1000.0);
+}`,
+  },
+  {
+    module: 'game::water_surface_b',
+    source: `#define_import_path game::water_surface_b
+#import forgeax_material::single_layer_medium_surface_v1::{SingleLayerMediumSurfaceInput, SingleLayerMediumSurfaceData}
+fn evaluate_surface(input : SingleLayerMediumSurfaceInput) -> SingleLayerMediumSurfaceData {
+  let event = read_waterEvents(input.eventRangeStart);
+  let normal = normalize(input.geometricNormalWS + vec3<f32>(event.position.xy * 0.01, 0.0));
+  return SingleLayerMediumSurfaceData(normal, 0.32, 1.0, clamp(event.time * 0.1, 0.0, 1.0), vec3<f32>(0.04, 0.02, 0.01), vec3<f32>(0.08, 0.05, 0.02), 1.333, -0.1, 800.0);
+}`,
+  },
+] as const;

package/src/extract/camera.ts

@@ -2,6 +2,10 @@ import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { readRenderArrayView } from '@forgeax/engine-ecs/projection';
 import { mat4, vec3 } from '@forgeax/engine-math';
 import { GlobalTransform } from '@forgeax/engine-scene';
+import {
+  BarrelDistortion,
+  validateBarrelDistortionParameters,
+} from '../components/barrel-distortion';
 import {
   antialiasFromF32,
   Camera,
@@ -38,13 +42,20 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
   const cameraQuery = world
     .query({
       read: [Camera],
-      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection, DepthOfField],
+      optional: [
+        MotionBlur,
+        DynamicResolution,
+        ScreenSpaceReflection,
+        DepthOfField,
+        BarrelDistortion,
+      ],
       with: [GlobalTransform],
     })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    const barrelDistortion = row.get(BarrelDistortion);
     const motionBlurResult = resolveMotionBlurParams(motionBlur);
     if (!motionBlurResult.ok) throw motionBlurResult.error;
     const motionBlurParams = motionBlurResult.value;
@@ -75,6 +86,8 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
     const antialias = antialiasFromF32(cam.antialias);
     const dynamicResolutionResult = validateDynamicResolutionCamera(dynamicResolution, antialias);
     if (!dynamicResolutionResult.ok) throw dynamicResolutionResult.error;
+    const barrelDistortionResult = validateBarrelDistortionParameters(barrelDistortion);
+    if (!barrelDistortionResult.ok) throw barrelDistortionResult.error;
     cameras.push({
       entityKey: entity as number,
       historyVersion: cam.historyVersion,
@@ -128,6 +141,7 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
               targetFps: motionBlurParams.targetFps,
             },
           }),
+      ...(barrelDistortion === undefined ? {} : { barrelDistortion: barrelDistortionResult.value }),
       ...(screenSpaceReflection === undefined
         ? {}
         : {

package/src/extract/contracts.ts

@@ -13,6 +13,7 @@ import type {
   MaterialAsset,
   MaterialPass,
   MaterialRenderState,
+  MaterialSurfaceModel,
   MaterialTextureCoordinates,
   MeshLodLevel,
   ParamSchemaEntry,
@@ -652,6 +653,10 @@ export interface MaterialSnapshot {
   readonly baseColor: Vec3;
   readonly metallic: number;
   readonly roughness: number;
+  /** Root-owned Surface model used only for typed pass routing. */
+  readonly surfaceModel?: MaterialSurfaceModel | undefined;
+  /** Whether this material publishes a Deferred pass consumed before the forward-only lane. */
+  readonly deferredPass?: boolean | undefined;
   readonly clearcoat?: number | undefined;
   readonly clearcoatRoughness?: number | undefined;
   /** Authored Standard PBR specular tint in linear runtime color space. */

package/src/extract/material-context.ts

@@ -0,0 +1,21 @@
+import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
+import type { RhiCaps } from '@forgeax/engine-rhi';
+
+/** The receiving device selects the immutable material program domain. */
+export function renderMaterialContext(caps: Pick<RhiCaps, 'backendKind' | 'storageBuffer'>): {
+  readonly materialContext?: MaterialCookProgramContext;
+} {
+  if (caps.backendKind === 'null') return {};
+  return {
+    materialContext: {
+      backend: caps.backendKind === 'wgpu-webgl2' ? 'webgl2' : caps.backendKind,
+      capability: caps.storageBuffer ? 'storage-buffer' : 'uniform-fallback',
+      pipeline: 'forward',
+      geometry: 'mesh',
+      pass: 'forward',
+      profile: 'forgeax-material-wgsl-v1',
+      toolchain: 'naga-oil',
+      instrumentation: 'none',
+    },
+  };
+}

package/src/features/barrel-distortion.ts

@@ -0,0 +1,172 @@
+/** One graph-valid identity for the barrel stage, feature and shader prewarm. */
+export const BARREL_DISTORTION_POST_PROCESS_ID = 'fullscreen.forgeax.barrel-distortion';
+export const BARREL_DISTORTION_FEATURE_IDENTITY = BARREL_DISTORTION_POST_PROCESS_ID;
+
+import { ok, type Result } from '@forgeax/engine-types';
+import type { RenderError } from '../errors/render';
+import type { RenderFeaturePlan } from './plan';
+import type { RenderFeature, RenderFeatureExtractContext, RenderFeaturePlanContext } from './types';
+
+/**
+ * The coordinate function is exported beside the production shader so a real
+ * f32 device probe can compile exactly the same implementation.  Keeping the
+ * probe source here avoids a second test-only equation that could drift from
+ * the Standard pass.
+ */
+export const BARREL_DISTORTION_WGSL_COORDINATE = /* wgsl */ `
+struct BarrelDistortionParams {
+  strength : f32,
+  centerX : f32,
+  centerY : f32,
+  radiusSquared : f32,
+};
+
+fn barrel_distortion_display_to_scene_uv(
+  inputUv : vec2<f32>,
+  params : BarrelDistortionParams,
+  dimensions : vec2<f32>,
+) -> vec2<f32> {
+  let aspect = dimensions.x / max(dimensions.y, 1.0);
+  let p = vec2<f32>(
+    2.0 * aspect * (inputUv.x - params.centerX),
+    2.0 * (inputUv.y - params.centerY),
+  );
+  let t = dot(p, p) / max(params.radiusSquared, 1e-6);
+  let scale = (1.0 - params.strength) / (1.0 - params.strength * t);
+  return clamp(
+    vec2<f32>(
+      params.centerX + (inputUv.x - params.centerX) * scale,
+      params.centerY + (inputUv.y - params.centerY) * scale,
+    ),
+    vec2<f32>(0.0),
+    vec2<f32>(1.0),
+  );
+}
+`;
+
+/**
+ * Manifest-equivalent WGSL for the bounded analytic model.  The Standard
+ * owner registers this source once and keeps the graph, encoder, and submit
+ * lifecycle shared with every other fullscreen stage.
+ */
+export const BARREL_DISTORTION_WGSL = /* wgsl */ `${BARREL_DISTORTION_WGSL_COORDINATE}
+struct FullscreenOutput {
+  @builtin(position) position : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+};
+
+fn fullscreen_triangle(vertex_index : u32) -> FullscreenOutput {
+  var x : f32 = -1.0;
+  var y : f32 = -1.0;
+  if (vertex_index == 1u) { x = 3.0; }
+  if (vertex_index == 2u) { y = 3.0; }
+  let u : f32 = (x + 1.0) * 0.5;
+  let v : f32 = 1.0 - (y + 1.0) * 0.5;
+  var out : FullscreenOutput;
+  out.position = vec4<f32>(x, y, 0.0, 1.0);
+  out.uv = vec2<f32>(u, v);
+  return out;
+}
+
+@group(1) @binding(0) var sceneColor : texture_2d<f32>;
+@group(1) @binding(1) var sceneSampler : sampler;
+
+@group(1) @binding(2) var<uniform> params : BarrelDistortionParams;
+
+@vertex
+fn vs_main(@builtin(vertex_index) vertex_index : u32) -> FullscreenOutput {
+  return fullscreen_triangle(vertex_index);
+}
+
+@fragment
+fn fs_main(input : FullscreenOutput) -> @location(0) vec4<f32> {
+  let dimensions = vec2<f32>(textureDimensions(sceneColor));
+  let sampleUv = barrel_distortion_display_to_scene_uv(input.uv, params, dimensions);
+  return textureSampleLevel(sceneColor, sceneSampler, sampleUv, 0.0);
+}
+`;
+
+/**
+ * Ordinary feature registration for the Standard linear-LDR stage.
+ * Standard still allocates the stage targets and chooses its position in the
+ * post chain; this feature owns the executable fullscreen declaration that is
+ * projected into that slot by the existing graph/encoder/submit path.
+ */
+export interface BarrelDistortionFeatureFrame {
+  /** True only when the extracted camera requires a spatial warp this frame. */
+  readonly active: boolean;
+}
+
+export function createBarrelDistortionRenderFeature(): RenderFeature<BarrelDistortionFeatureFrame> {
+  return Object.freeze({
+    identity: BARREL_DISTORTION_FEATURE_IDENTITY,
+    requiredCapabilities: ['rgba16floatRenderable'] as const,
+    requiredFullscreenPostProcesses: [
+      { identity: BARREL_DISTORTION_POST_PROCESS_ID, source: BARREL_DISTORTION_WGSL },
+    ],
+    extract: (
+      context: RenderFeatureExtractContext,
+    ): Result<BarrelDistortionFeatureFrame, RenderError> =>
+      ok({ active: (context.selectedCamera?.barrelDistortion?.strength ?? 0) > 0 }),
+    plan: (
+      data: BarrelDistortionFeatureFrame,
+      _context: RenderFeaturePlanContext,
+    ): Result<RenderFeaturePlan, RenderError> =>
+      ok({
+        resources: data.active
+          ? [
+              {
+                kind: 'fullscreen-program' as const,
+                name: BARREL_DISTORTION_POST_PROCESS_ID,
+                source: BARREL_DISTORTION_WGSL,
+                reads: ['ldrColor'],
+                params: { byteSize: 16, defaultValue: new Uint8Array(16) },
+              },
+              {
+                kind: 'graphics-program' as const,
+                name: 'barrel-distortion-pipeline',
+                program: {
+                  shader: BARREL_DISTORTION_POST_PROCESS_ID,
+                  vertexLayout: 'none',
+                  colorFormats: ['rgba16float'],
+                  sampleCount: 1,
+                },
+              },
+              {
+                kind: 'graphics-bindings' as const,
+                name: 'barrel-distortion-bindings',
+                program: 'barrel-distortion-pipeline',
+                values: {
+                  group: 1,
+                  fullscreen: true,
+                  shader: BARREL_DISTORTION_POST_PROCESS_ID,
+                  input: 'barrel-input',
+                },
+                logicalTargets: { input: 'barrel-input' },
+              },
+            ]
+          : [],
+        passes: data.active
+          ? [
+              {
+                kind: 'raster' as const,
+                name: 'barrel-distortion',
+                colorAttachments: [
+                  { target: 'barrel-output', loadOp: 'clear' as const, storeOp: 'store' as const },
+                ],
+                sampledTargets: ['barrel-input'],
+                draws: [
+                  {
+                    program: 'barrel-distortion-pipeline',
+                    bindings: ['barrel-distortion-bindings'],
+                    vertexData: [],
+                    vertexLayout: 'none' as const,
+                    draw: { kind: 'draw' as const, vertexCount: 3, instanceCount: 1 },
+                  },
+                ],
+              },
+            ]
+          : [],
+      }),
+  });
+}

package/src/features/error-reporting.ts

@@ -8,22 +8,33 @@ import type { RenderError } from '../errors/render';
  */
 export const PENDING_RENDER_FEATURE_ERROR_REPORT_INTERVAL_FRAMES = 60;
 
+export interface PendingRenderFeatureErrorReport {
+  readonly frame: number;
+  readonly fingerprint: string;
+}
+
 export function shouldReportPendingRenderFeatureError(
-  lastReportedFrame: Map<string, number>,
+  lastReportedFrame: Map<string, PendingRenderFeatureErrorReport>,
   key: string,
   frameNumber: number,
+  fingerprint = '',
   intervalFrames = PENDING_RENDER_FEATURE_ERROR_REPORT_INTERVAL_FRAMES,
 ): boolean {
   const lastReported = lastReportedFrame.get(key);
-  if (lastReported !== undefined && frameNumber - lastReported < intervalFrames) return false;
-  lastReportedFrame.set(key, frameNumber);
+  if (
+    lastReported !== undefined &&
+    lastReported.fingerprint === fingerprint &&
+    frameNumber - lastReported.frame < intervalFrames
+  )
+    return false;
+  lastReportedFrame.set(key, { frame: frameNumber, fingerprint });
   return true;
 }
 
 export function reportPendingRenderFeatureErrors(
   errors: readonly RenderError[],
   frameNumber: number,
-  lastReportedFrame: Map<string, number>,
+  lastReportedFrame: Map<string, PendingRenderFeatureErrorReport>,
   errorRegistry: { fire(error: RenderError): void },
 ): void {
   for (const error of errors) {
@@ -36,7 +47,16 @@ export function reportPendingRenderFeatureErrors(
     // failures still receive first/periodic reporting.
     if (isSilentRenderFeatureWarmup(error)) continue;
     const key = pendingRenderFeatureErrorKey(error);
-    if (shouldReportPendingRenderFeatureError(lastReportedFrame, key, frameNumber)) {
+    const cause = error.code === 'render-feature-stage-failed' ? error.detail.cause : undefined;
+    const causeText =
+      cause instanceof Error
+        ? `${cause.name}\0${cause.message}`
+        : typeof cause === 'string'
+          ? cause
+          : '';
+    const fingerprint = `${error.expected}\0${error.hint}\0${causeText}`;
+    // Retain one record per owner, not one record per changing cause string.
+    if (shouldReportPendingRenderFeatureError(lastReportedFrame, key, frameNumber, fingerprint)) {
       errorRegistry.fire(error);
     }
   }
@@ -74,5 +94,5 @@ function pendingRenderFeatureErrorKey(error: RenderError): string {
     detail !== undefined && 'order' in detail && typeof detail.order === 'number'
       ? detail.order
       : -1;
-  return `${error.code}\0${featureIdentity}\0${order}\0${error.expected}\0${error.hint}`;
+  return `${error.code}\0${featureIdentity}\0${order}`;
 }