@forgeax/engine-render 0.1.33 → 0.1.34

package/src/cloud/temporal.ts

@@ -0,0 +1,226 @@
+import type { CloudQuality } from '../components/cloud-layer';
+
+export type CloudTemporalResetReason =
+  | 'authoring-generation'
+  | 'camera-cut'
+  | 'resize'
+  | 'recovery'
+  | 'time-discontinuity'
+  | 'cloud-shadow-revision'
+  | 'device-generation'
+  | 'history-missing'
+  | 'reprojection-outside'
+  | 'scene-depth-disocclusion';
+
+export interface CloudTemporalSignature {
+  readonly sourceKey: string;
+  readonly viewId: string;
+  readonly authoringGeneration: number;
+  readonly cloudShadowRevision: number;
+  readonly cameraRevision: number;
+  readonly deviceGeneration: number;
+  readonly width: number;
+  readonly height: number;
+  readonly timeSeconds: number;
+  readonly quality: CloudQuality;
+  /** Scene-depth producer revision used to reject disoccluded history. */
+  readonly sceneDepthVersion?: number;
+}
+
+export interface CloudHistory {
+  readonly width: number;
+  readonly height: number;
+  readonly signature: string;
+  readonly temporal: CloudTemporalSignature;
+  readonly generation: number;
+  readonly valid: boolean;
+}
+
+export interface CloudTemporalDecision {
+  readonly reset: boolean;
+  readonly reasons: readonly CloudTemporalResetReason[];
+  readonly signature: string;
+  readonly history: CloudHistory | undefined;
+}
+
+export interface CloudTemporalFrame {
+  readonly signature: CloudTemporalSignature;
+  readonly history: CloudHistory | undefined;
+  readonly reset: boolean;
+  readonly reasons: readonly CloudTemporalResetReason[];
+}
+
+export interface CloudHistoryReprojectionInput {
+  readonly currentDepth: number;
+  readonly historyDepth: number;
+  readonly motion: readonly [number, number];
+  readonly currentPixel: readonly [number, number];
+  readonly historySize: readonly [number, number];
+  readonly depthTolerance?: number;
+}
+
+export interface CloudHistoryReprojection {
+  readonly accepted: boolean;
+  readonly historyUv: readonly [number, number];
+  readonly weight: number;
+  readonly reason: 'accepted' | 'outside' | 'depth-disocclusion';
+}
+
+export function cloudTemporalSignature(input: CloudTemporalSignature): string {
+  return [
+    'cloud-temporal-v1',
+    input.viewId,
+    input.sourceKey,
+    input.authoringGeneration,
+    input.cloudShadowRevision,
+    input.cameraRevision,
+    input.deviceGeneration,
+    input.width,
+    input.height,
+    input.timeSeconds,
+    input.quality,
+    input.sceneDepthVersion ?? 0,
+  ].join(':');
+}
+
+function sameLayout(left: CloudTemporalSignature, right: CloudTemporalSignature): boolean {
+  return left.viewId === right.viewId && left.width === right.width && left.height === right.height;
+}
+
+/** Compare the facts that make a cloud history safe to reuse. */
+export function cloudTemporalResetReasons(
+  previous: CloudTemporalSignature | undefined,
+  next: CloudTemporalSignature,
+  options: { readonly cameraCut?: boolean; readonly recovery?: boolean } = {},
+): readonly CloudTemporalResetReason[] {
+  if (previous === undefined) return ['history-missing'];
+  const reasons: CloudTemporalResetReason[] = [];
+  if (
+    previous.sourceKey !== next.sourceKey ||
+    previous.authoringGeneration !== next.authoringGeneration
+  ) {
+    reasons.push('authoring-generation');
+  }
+  if (previous.cloudShadowRevision !== next.cloudShadowRevision)
+    reasons.push('cloud-shadow-revision');
+  if (previous.deviceGeneration !== next.deviceGeneration) reasons.push('device-generation');
+  if (
+    previous.sceneDepthVersion !== undefined &&
+    next.sceneDepthVersion !== undefined &&
+    previous.sceneDepthVersion !== next.sceneDepthVersion
+  ) {
+    reasons.push('scene-depth-disocclusion');
+  }
+  if (!sameLayout(previous, next)) reasons.push('resize');
+  if (options.cameraCut === true || previous.cameraRevision !== next.cameraRevision)
+    reasons.push('camera-cut');
+  const dt = next.timeSeconds - previous.timeSeconds;
+  if (!Number.isFinite(dt) || dt < 0 || dt > 0.5) reasons.push('time-discontinuity');
+  if (options.recovery === true) reasons.push('recovery');
+  return Object.freeze(reasons);
+}
+
+export function createCloudHistory(
+  signature: CloudTemporalSignature,
+  generation: number,
+  valid = false,
+): CloudHistory {
+  return Object.freeze({
+    width: Math.max(1, Math.floor(signature.width)),
+    height: Math.max(1, Math.floor(signature.height)),
+    signature: cloudTemporalSignature(signature),
+    temporal: Object.freeze({ ...signature }),
+    generation,
+    valid,
+  });
+}
+
+/** Per-view histories are keyed by the renderer's view identity. */
+export class CloudHistoryStore {
+  private readonly maxViews: number;
+  private readonly entries = new Map<
+    string,
+    { readonly history: CloudHistory; readonly signature: CloudTemporalSignature }
+  >();
+
+  constructor(maxViews = 4) {
+    this.maxViews = Math.max(1, Math.floor(maxViews));
+  }
+
+  begin(
+    signature: CloudTemporalSignature,
+    options: { readonly cameraCut?: boolean; readonly recovery?: boolean } = {},
+  ): CloudTemporalDecision {
+    const key = signature.viewId;
+    const previousEntry = this.entries.get(key);
+    const previous = previousEntry?.history;
+    const reasons = cloudTemporalResetReasons(previousEntry?.signature, signature, options);
+    const reset = reasons.length > 0;
+    return Object.freeze({
+      reset,
+      reasons,
+      signature: cloudTemporalSignature(signature),
+      history: reset ? undefined : previous,
+    });
+  }
+
+  commit(signature: CloudTemporalSignature, history: CloudHistory): void {
+    if (
+      history.width !== Math.max(1, Math.floor(signature.width)) ||
+      history.height !== Math.max(1, Math.floor(signature.height))
+    ) {
+      this.entries.delete(signature.viewId);
+      return;
+    }
+    this.entries.set(signature.viewId, { history, signature: Object.freeze({ ...signature }) });
+    while (this.entries.size > this.maxViews) {
+      const oldest = this.entries.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.entries.delete(oldest);
+    }
+  }
+
+  reset(viewId?: string): void {
+    if (viewId === undefined) this.entries.clear();
+    else this.entries.delete(viewId);
+  }
+
+  get(viewId: string): CloudHistory | undefined {
+    return this.entries.get(viewId)?.history;
+  }
+
+  dispose(): void {
+    this.entries.clear();
+  }
+}
+
+/** Project one current pixel into the previous cloud history. */
+export function reprojectCloudHistory(
+  input: CloudHistoryReprojectionInput,
+  historyWeight = 0.9,
+): CloudHistoryReprojection {
+  const width = Math.max(1, input.historySize[0] ?? 1);
+  const height = Math.max(1, input.historySize[1] ?? 1);
+  const uv: [number, number] = [
+    ((input.currentPixel[0] ?? 0) - (input.motion[0] ?? 0)) / width,
+    ((input.currentPixel[1] ?? 0) - (input.motion[1] ?? 0)) / height,
+  ];
+  if (uv[0] < 0 || uv[0] > 1 || uv[1] < 0 || uv[1] > 1) {
+    return { accepted: false, historyUv: uv, weight: 0, reason: 'outside' };
+  }
+  const depthTolerance =
+    input.depthTolerance ?? Math.max(0.01, Math.abs(input.currentDepth) * 0.02);
+  if (
+    !Number.isFinite(input.currentDepth) ||
+    !Number.isFinite(input.historyDepth) ||
+    Math.abs(input.currentDepth - input.historyDepth) > depthTolerance
+  ) {
+    return { accepted: false, historyUv: uv, weight: 0, reason: 'depth-disocclusion' };
+  }
+  return {
+    accepted: true,
+    historyUv: uv,
+    weight: Math.min(0.99, Math.max(0, historyWeight)),
+    reason: 'accepted',
+  };
+}

package/src/components/barrel-distortion.ts

@@ -0,0 +1,46 @@
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { BarrelDistortionInvalidParameterError } from '../errors/render';
+
+/** Camera companion that applies the bounded first-order barrel model. */
+export const BarrelDistortion = defineComponent('BarrelDistortion', {
+  strength: { type: 'f32', default: 0 },
+  centerX: { type: 'f32', default: 0.5 },
+  centerY: { type: 'f32', default: 0.5 },
+});
+
+export type BarrelDistortionData = ShapeOf<SchemaOf<typeof BarrelDistortion>>;
+
+const DEFAULT_BARREL_DISTORTION: BarrelDistortionData = Object.freeze({
+  strength: 0,
+  centerX: 0.5,
+  centerY: 0.5,
+});
+
+function invalid(
+  field: 'strength' | 'centerX' | 'centerY',
+  value: number,
+  expected: string,
+): BarrelDistortionInvalidParameterError {
+  return new BarrelDistortionInvalidParameterError({ field, value, expected });
+}
+
+/** Validate and detach camera-owned barrel authoring data. */
+export function validateBarrelDistortionParameters(
+  input: Partial<BarrelDistortionData> | undefined,
+): Result<BarrelDistortionData, BarrelDistortionInvalidParameterError> {
+  const value = input ?? {};
+  const strength = value.strength ?? DEFAULT_BARREL_DISTORTION.strength;
+  const centerX = value.centerX ?? DEFAULT_BARREL_DISTORTION.centerX;
+  const centerY = value.centerY ?? DEFAULT_BARREL_DISTORTION.centerY;
+  if (!Number.isFinite(strength) || strength < 0 || strength > 0.35) {
+    return err(invalid('strength', strength, 'finite and in [0, 0.35]'));
+  }
+  if (!Number.isFinite(centerX) || centerX < 0 || centerX > 1) {
+    return err(invalid('centerX', centerX, 'finite and in [0, 1]'));
+  }
+  if (!Number.isFinite(centerY) || centerY < 0 || centerY > 1) {
+    return err(invalid('centerY', centerY, 'finite and in [0, 1]'));
+  }
+  return ok(Object.freeze({ strength, centerX, centerY }));
+}

package/src/components/cloud-layer.ts

@@ -0,0 +1,47 @@
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+
+/** Closed quality lane for the renderer-owned procedural cloud producer. */
+export type CloudQuality = 'low' | 'medium' | 'high';
+
+export const CloudQualityValue = Object.freeze({
+  low: 0,
+  medium: 1,
+  high: 2,
+} as const);
+
+/**
+ * A single World-authored cloud layer.
+ *
+ * The component contains only source facts. Cache resolution, optical step
+ * counts, temporal history and GPU handles are derived by Render and never
+ * written back into ECS.
+ */
+export const CloudLayer = defineComponent('CloudLayer', {
+  /** Stable integer seed for the periodic 3D density field. */
+  seed: { type: 'u32', default: 1337 },
+  /** World-space lower edge of the layer, in metres. */
+  baseHeight: { type: 'f32', default: 120 },
+  /** World-space thickness of the layer, in metres. */
+  thickness: { type: 'f32', default: 80 },
+  /** Horizontal noise scale, in cycles per metre. */
+  scale: { type: 'f32', default: 0.004 },
+  /** Coverage threshold in [0, 1]. */
+  coverage: { type: 'f32', default: 0.48 },
+  /** Extinction multiplier in inverse metres. */
+  density: { type: 'f32', default: 1 },
+  /** World-space wind velocity in metres per second. */
+  wind: { type: 'array<f32, 3>', default: new Float32Array([8, 0, 2]) },
+  /** Quality controls cache resolution and bounded ray steps. */
+  quality: { type: 'f32', default: CloudQualityValue.medium },
+  /** Maximum world-space distance represented by the light-space shadow map. */
+  shadowRange: { type: 'f32', default: 512 },
+});
+
+export type CloudLayerData = ShapeOf<SchemaOf<typeof CloudLayer>>;
+
+export function cloudQualityFromF32(value: number): CloudQuality | undefined {
+  if (value === CloudQualityValue.low) return 'low';
+  if (value === CloudQualityValue.medium) return 'medium';
+  if (value === CloudQualityValue.high) return 'high';
+  return undefined;
+}

package/src/components/index.ts

@@ -1,5 +1,7 @@
 export * from './atmosphere';
+export * from './barrel-distortion';
 export * from './camera';
+export * from './cloud-layer';
 export * from './cube-camera';
 export * from './depth-of-field';
 export * from './directional-light';

package/src/components/instances.ts

@@ -1,50 +1,23 @@
-// @forgeax/engine-render - renderer-owned large instance association.
-//
-// The ECS component deliberately carries only a stable collection identity.
-// Matrix bytes, revision, capacity, dirty ranges, GPU residency and fallback
-// policy belong to InstanceCollectionStore, exposed from the same Renderer.
-// This keeps large payloads out of the ECS managed BufferPool while retaining
-// ordinary query and entity-lifetime semantics.
-//
-// Authoring example:
-//
-//   const transforms = new Float32Array(instanceCount * 16);
-//   for (let index = 0; index < instanceCount; index += 1) {
-//     const offset = index * 16;
-//     transforms[offset] = 1;
-//     transforms[offset + 5] = 1;
-//     transforms[offset + 10] = 1;
-//     transforms[offset + 15] = 1;
-//   }
-//   const collection = renderer.instances.create({
-//     transforms,
-//   }).unwrap();
-//   world.spawn(
-//     { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
-//     { component: MeshRenderer, data: {} },
-//     { component: Instances, data: { collectionId: collection.collectionId } },
-//   );
-//
-// Updates stay on the renderer owner and publish one revision:
-//
-//   renderer.instances.update(collection.collectionId, {
-//     start: 12,
-//     transforms: patch,
-//   });
-//
-// Render extraction snapshots the validated packed column-major matrices once
-// per frame. Direct, GPU-driven and fallback lanes consume that same detached
-// projection; callers never split one logical collection into ECS chunks.
-
 import { defineComponent } from '@forgeax/engine-ecs';
-import type { InstanceCollectionData } from '../instances';
 
-/** Per-entity association with a renderer-owned instance collection. */
+/**
+ * World-owned local transforms for one explicit instanced renderable.
+ * Packed column-major mat4 values compose as entityWorld * instanceLocal.
+ * ECS owns copying, mutation and entity lifetime, including large arrays.
+ * Renderer extraction derives its own snapshot and GPU residency; neither
+ * authoring nor glTF SceneAsset lowering requires a Renderer identity.
+ *
+ * @example
+ * const transforms = new Float32Array(20_000 * 16);
+ * for (let i = 0; i < 20_000; i++) {
+ *   transforms[i * 16] = transforms[i * 16 + 5] =
+ *     transforms[i * 16 + 10] = transforms[i * 16 + 15] = 1;
+ * }
+ * const entity = world.spawn({ component: Instances, data: { transforms } }).unwrap();
+ * world.set(entity, Instances, { transforms }).unwrap();
+ */
 export const Instances = defineComponent('Instances', {
-  collectionId: { type: 'u32', default: 0 },
+  transforms: { type: 'array<f32>' },
 });
 
-/** Type-level hint for the `data` object at the Instances spawn site. */
-export type InstancesData = InstanceCollectionData;
-
-export type { InstanceCollectionId } from '../instances';
+export type InstancesData = { readonly transforms: Float32Array };

package/src/components/sprite-instances.ts

@@ -41,7 +41,7 @@
 //   composes per instance:
 //     world_position[i] = entity_world * instances_local[i] * vertex_position
 //   `SpriteInstances.transforms[i*16..i*16+15]` is interpreted as a local-
-//   space transform under the entity, matching the 3D collection projection.
+//   space transform under the entity, exactly like `Instances.transforms`.
 //   Set the entity's `Transform` to identity to make `instances_local[i]`
 //   directly world-space.
 //

package/src/construct-renderer.ts

@@ -14,7 +14,7 @@ export type {
   RhiBackendInstrumentation,
   RhiBackendPack,
 } from './assembly/backend-contract';
-export { EngineEnvironmentError } from './assembly/backend-contract';
+export { EngineEnvironmentError, loadRhiPack } from './assembly/backend-contract';
 export type { RendererLegacyHostAdapter } from './assembly/host-contract';
 export type { BundlerOptions };
 

package/src/dynamic-geometry.ts

@@ -53,6 +53,9 @@ export interface DynamicGeometryCandidate {
   readonly state: DynamicGeometryCandidateState;
 }
 
+/** Record-stage lane that consumed a published dynamic-geometry candidate. */
+export type DynamicGeometryRecordStageLane = 'cpu' | 'gpu' | 'mixed';
+
 /** Receipt that ties candidate publication to the sole Renderer FrameReceipt. */
 export interface DynamicGeometryReceipt {
   readonly candidateId: string;
@@ -69,6 +72,8 @@ export interface DynamicGeometryReceipt {
   };
   /** Whether the Renderer record stage consumed this candidate for this frame. */
   readonly recordStageConsumed: boolean;
+  /** Lane evidence from the exact submitted record stage, when attached. */
+  readonly recordStageLane?: DynamicGeometryRecordStageLane;
   /** Actual frame fixed step; may be newer than the preparation step. */
   readonly publicationFixedStep?: number;
 }
@@ -271,6 +276,9 @@ export interface DynamicGeometryLifecycle {
     worlds?: readonly object[],
     fixedStep?: number,
     canPublish?: (candidate: DynamicGeometryCandidate) => boolean,
+    recordStageLane?: (
+      candidate: DynamicGeometryCandidate,
+    ) => DynamicGeometryRecordStageLane | undefined,
   ): readonly DynamicGeometryReceipt[];
   invalidateWorld(world: object, completion?: Promise<unknown>): void;
   invalidateGeneration(generation: number): void;
@@ -610,7 +618,7 @@ export function createDynamicGeometryLifecycle(
       meshBytes = Math.max(0, meshBytes - record.candidate.meshBytes);
       return ok(undefined);
     },
-    publishFrame(frame, worlds, fixedStep, canPublish) {
+    publishFrame(frame, worlds, fixedStep, canPublish, recordStageLane) {
       if (disposed || frame.deviceGeneration !== currentGeneration) return [];
       const receipts: DynamicGeometryReceipt[] = [];
       for (const record of records.values()) {
@@ -630,6 +638,8 @@ export function createDynamicGeometryLifecycle(
           continue;
         }
         if (canPublish !== undefined && !canPublish(record.candidate)) continue;
+        const consumedLane =
+          canPublish === undefined ? undefined : recordStageLane?.(record.candidate);
         record.candidate = Object.freeze({ ...record.candidate, state: 'published' as const });
         const receipt = Object.freeze({
           candidateId: record.candidate.candidateId,
@@ -642,6 +652,7 @@ export function createDynamicGeometryLifecycle(
           frameId: frame.frameId,
           deviceGeneration: frame.deviceGeneration,
           recordStageConsumed: canPublish !== undefined,
+          ...(consumedLane === undefined ? {} : { recordStageLane: consumedLane }),
           ...(fixedStep === undefined ? {} : { publicationFixedStep: fixedStep }),
           frame: Object.freeze({ ...frame }),
         });

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

@@ -30,6 +30,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`,
@@ -1392,6 +1393,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 +1861,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 +1916,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 };
@@ -1981,6 +2016,8 @@ export type RenderError =
   | TaaCapsInsufficientError
   | EnvironmentGenerationFailedError
   | AtmosphereInvalidParameterError
+  | BarrelDistortionInvalidParameterError
+  | CloudLayerError
   | DynamicResolutionInvalidParameterError
   | DynamicResolutionRequiresTaaError
   | DynamicResolutionTimingUnavailableError