@forgeax/engine-render 0.1.19 → 0.1.21

package/src/errors/render.ts

@@ -116,54 +116,55 @@ export function createRenderSurfaceError(
   return new RenderSurfaceError(`surface-${kind}-failed` as SurfaceFailureCode, detail);
 }
 
+export interface TemporalFrameSubmitDetail {
+  readonly reason: 'queue-submit-failed';
+}
+
+export class TemporalFrameSubmitError extends Error {
+  readonly code = 'temporal-frame-submit-rejected' as const;
+  readonly expected = 'the staged frame is accepted by queue.submit before temporal facts advance';
+  readonly hint = 'inspect the queue submission and retry the frame after the device is available';
+  readonly detail: TemporalFrameSubmitDetail;
+
+  constructor(reason: 'queue-submit-failed') {
+    super(`temporal-frame-submit-rejected: ${reason}`);
+    this.name = 'TemporalFrameSubmitError';
+    this.detail = { reason };
+  }
+}
+
 // ── ShadowInvalidConfigError ──────────────────────────────────────────────
 
 /**
  * Detail for `RuntimeErrorCode 'shadow-invalid-config'`.
  *
- * Emitted by `DirectionalLight.validate` shadow-field path when a field value violates
- * runtime constraints (e.g. mapSize < 1, cascadeCount not in {1..4}).
- * AI users access `.detail.field` / `.detail.value` / `.detail.min` /
- * `.detail.max` via property access — no string parsing.
- *
- * `max` is `undefined` for lower-bound-only validations (e.g. mapSize < 1).
- * feat-20260613-csm: max added for upper-bound cascade validations
- * (cascadeCount max=4, splitLambda max=1, cascadeBlend max=0.5).
+ * The four fields are the only recovery surface: AI users read the invalid
+ * field, actual value, structured bound, and reason without parsing prose.
  */
+export type ShadowInvalidConfigBound =
+  | { readonly kind: 'range'; readonly min: number; readonly max: number }
+  | { readonly kind: 'lower-bound'; readonly operator: '>' | '>='; readonly value: number }
+  | { readonly kind: 'allowed-values'; readonly values: readonly number[] };
+
 export interface ShadowInvalidConfigDetail {
   readonly field: string;
-  readonly value: number;
-  readonly min: number;
-  readonly max?: number;
+  readonly actual: number;
+  readonly bound: ShadowInvalidConfigBound;
+  readonly reason: string;
 }
 
 /**
  * Structured error for shadow component config validation failures.
  *
- * Emitted by `DirectionalLight.validate()` shadow-field path (mapSize / cascadeCount /
- * splitLambda / cascadeBlend / shadowDistance) and `PointLightShadow.validate()`
- * (mapSize / farPlane > nearPlane / pcfKernelSize); both shadow component
- * types share this single error class so `switch (err.code)` on
- * `RuntimeErrorCode` only needs one branch (charter P4 — closed-union SSOT).
- * Four-field surface per AGENTS.md error model:
+ * Emitted by Directional, Point, and Spot shadow validation. All three
+ * component owners share this error class so `switch (err.code)` on
+ * `RuntimeErrorCode` needs one branch (charter P4 — closed-union SSOT).
+ * Four-field surface:
  *   - `.code = 'shadow-invalid-config'` (closed RuntimeErrorCode)
  *   - `.expected` — expected-state description (programmatic predicate form)
  *   - `.hint` — actionable recovery guidance (imperative; AI users paste into
- *     spawn calls). Integer-typed fields (e.g. `cascadeCount`, `pcfKernelSize`)
- *     get an "integer in [min, max]" hint; otherwise "[min, max]" range or
- *     "<comparator> min".
- *   - `.detail = { field, value, min, max? }` — structured values (charter P4)
- *
- * 4th constructor parameter is a union over the two range shapes:
- *   - `number` — `max` for a closed `[min, max]` range (CSM cascadeCount /
- *     splitLambda / cascadeBlend). hint uses "in [min, max]"; integer-typed
- *     fields get "integer in [min, max]".
- *   - `'>' | '>='` — comparator for an open lower-bound predicate. `'>'` is
- *     used when `min` carries dynamic context (e.g. `farPlane > nearPlane` —
- *     the surfaced hint reads "must be > nearPlane" so AI users setting
- *     farPlane=nearPlane don't re-fail the spawn loop with the wrong cue).
- *   - `undefined` — defaults to `'>='`. Callsites for mapSize < 1 validation
- *     stay backward-compatible (3-arg form).
+ *     spawn calls).
+ *   - `.detail = { field, actual, bound, reason }` — structured values.
  */
 export class ShadowInvalidConfigError extends Error {
   readonly code = 'shadow-invalid-config' as const;
@@ -171,35 +172,53 @@ export class ShadowInvalidConfigError extends Error {
   readonly hint: string;
   readonly detail: ShadowInvalidConfigDetail;
 
-  constructor(field: string, value: number, min: number, maxOrComparator?: number | '>' | '>=') {
-    const isComparator = maxOrComparator === '>' || maxOrComparator === '>=';
-    const max = !isComparator && typeof maxOrComparator === 'number' ? maxOrComparator : undefined;
-    const comparator: '>' | '>=' = isComparator ? (maxOrComparator as '>' | '>=') : '>=';
-    // Integer-typed fields get an "integer in [min, max]" hint when a range
-    // is supplied. Expand this set as new integer-typed shadow fields land.
-    const isInteger = field === 'cascadeCount' || field === 'pcfKernelSize';
-    // pcfKernelSize must be odd (kernel is symmetric around the center tap).
-    // Naming "odd" in the hint stops an AI retry from looping min->min+1 (4->6).
-    const isOdd = field === 'pcfKernelSize';
-    const hint =
-      max !== undefined
-        ? isInteger
-          ? `set ${field} to an integer in [${min}, ${max}]; got ${value}`
-          : `set ${field} to a value in [${min}, ${max}]; got ${value}`
-        : isOdd
-          ? `set ${field} to an odd integer ${comparator} ${min}; got ${value}`
-          : `set ${field} to a value ${comparator} ${min}; got ${value}`;
-    const expected =
-      max !== undefined ? `${field} in [${min}, ${max}]` : `${field} ${comparator} ${min}`;
-    super(
-      max !== undefined
-        ? `shadow component .${field} must be in [${min}, ${max}], got ${value}`
-        : `shadow component .${field} must be ${comparator} ${min}, got ${value}`,
-    );
+  constructor(
+    field: string,
+    actual: number,
+    minOrBound: number | ShadowInvalidConfigBound,
+    maxOrComparator?: number | '>' | '>=',
+    reason?: string,
+  ) {
+    const bound: ShadowInvalidConfigBound =
+      typeof minOrBound === 'number'
+        ? typeof maxOrComparator === 'number'
+          ? { kind: 'range', min: minOrBound, max: maxOrComparator }
+          : {
+              kind: 'lower-bound',
+              operator: maxOrComparator === '>' ? '>' : '>=',
+              value: minOrBound,
+            }
+        : minOrBound;
+    const resolvedReason = reason ?? shadowBoundReason(bound);
+    const expected = shadowBoundExpected(field, bound);
+    const hint = `set ${field} to ${resolvedReason}; got ${actual}`;
+    super(`shadow component .${field} is invalid: ${resolvedReason}; got ${actual}`);
     this.name = 'ShadowInvalidConfigError';
     this.hint = hint;
     this.expected = expected;
-    this.detail = { field, value, min, ...(max !== undefined ? { max } : {}) };
+    this.detail = { field, actual, bound, reason: resolvedReason };
+  }
+}
+
+function shadowBoundExpected(field: string, bound: ShadowInvalidConfigBound): string {
+  switch (bound.kind) {
+    case 'range':
+      return `${field} in [${bound.min}, ${bound.max}]`;
+    case 'lower-bound':
+      return `${field} ${bound.operator} ${bound.value}`;
+    case 'allowed-values':
+      return `${field} in {${bound.values.join(', ')}}`;
+  }
+}
+
+function shadowBoundReason(bound: ShadowInvalidConfigBound): string {
+  switch (bound.kind) {
+    case 'range':
+      return `a value in [${bound.min}, ${bound.max}]`;
+    case 'lower-bound':
+      return `a value ${bound.operator} ${bound.value}`;
+    case 'allowed-values':
+      return `one of [${bound.values.join(', ')}]`;
   }
 }
 
@@ -253,133 +272,125 @@ export class EquirectProjectionFailedError extends Error {
   }
 }
 
-// ── HdrpLightBudgetExceededError ───────────────────────────────────────────
+// ── StandardLightBudgetExceededError ──────────────────────────────────────
 
-/**
- * Detail for `RuntimeErrorCode 'hdrp-light-budget-exceeded'`.
- *
- * Emitted per-frame (once-per-frame fire) when light count exceeds HDRP budget.
- */
-export interface HdrpLightBudgetExceededDetail {
+/** The finite local-light budget that a Standard frame agreed to admit. */
+export interface StandardLightBudgetExceededDetail {
   readonly actual: number;
   readonly budget: number;
 }
 
 /**
- * Structured error for HDRP light budget exceeded (AC-06/AC-07).
- *
- * Emitted per-frame in recordFrame when the total punctual light count
- * exceeds the HDRP budget (256). Fail-soft: fire once per frame, truncate to 256.
- *   - `.code = 'hdrp-light-budget-exceeded'` (closed RuntimeErrorCode)
- *   - `.expected` — 'light count <= 256'
- *   - `.hint` — 'reduce world light count or increase budget (OOS-hdrp-larger-budget)'
- *   - `.detail = { actual, budget }`
+ * Structured refusal for a Standard frame whose finite local-light set is
+ * outside the selected profile budget. The frame is rejected as a whole; the
+ * record owner must not slice the input or submit a partial membership set.
  */
-export class HdrpLightBudgetExceededError extends Error {
-  readonly code = 'hdrp-light-budget-exceeded' as const;
+export class StandardLightBudgetExceededError extends Error {
+  readonly code = 'standard-light-budget-exceeded' as const;
   readonly expected: string;
   readonly hint: string;
-  readonly detail: HdrpLightBudgetExceededDetail;
+  readonly detail: StandardLightBudgetExceededDetail;
 
   constructor(actual: number, budget: number) {
     const expected = `light count <= ${budget}`;
     const hint =
-      `${actual} lights exceed HDRP budget ${budget}; ` +
-      'truncating to 256. Reduce light count or wait for OOS-hdrp-larger-budget';
-    super(`HDRP light budget exceeded: ${actual} > ${budget}`);
-    this.name = 'HdrpLightBudgetExceededError';
+      `${actual} finite local lights exceed Standard budget ${budget}; ` +
+      'reduce the local-light set or select a profile with a supported budget';
+    super(`Standard light budget exceeded: ${actual} > ${budget}`);
+    this.name = 'StandardLightBudgetExceededError';
     this.expected = expected;
     this.hint = hint;
     this.detail = { actual, budget };
   }
 }
 
-// ── HdrpIndexListOverflowError ─────────────────────────────────────────────
+// ── StandardClusterIndexOverflowError ──────────────────────────────────────
 
-/**
- * Detail for `RuntimeErrorCode 'hdrp-index-list-overflow'`.
- *
- * Emitted per-frame (once-per-frame fire) when the cluster binner overflows
- * the light index list capacity (65536). Upgraded from ClusterBinError.
- */
-export interface HdrpIndexListOverflowDetail {
+/** Cluster membership entries that could not fit the single shared index list. */
+export interface StandardClusterIndexOverflowDetail {
   readonly actual: number;
   readonly capacity: number;
 }
 
 /**
- * Structured error for HDRP cluster binner index list overflow (AC-24).
- *
- * Emitted per-frame in recordFrame when the CPU binner returns
- * `ClusterBinError('index-overflow')`. Fail-soft: fire once per frame,
- * continue rendering with what fit.
- *   - `.code = 'hdrp-index-list-overflow'` (closed RuntimeErrorCode)
- *   - `.expected` — 'light index list entries <= 65536'
- *   - `.hint` — 'reduce lights, shrink cluster grid, or increase capacity'
- *   - `.detail = { actual, capacity }`
+ * Structured refusal for a membership producer that exceeded the shared
+ * Cluster index-list capacity. No truncated list is uploaded and no graph is
+ * submitted for the rejected frame.
  */
-export class HdrpIndexListOverflowError extends Error {
-  readonly code = 'hdrp-index-list-overflow' as const;
+export class StandardClusterIndexOverflowError extends Error {
+  readonly code = 'standard-cluster-index-overflow' as const;
   readonly expected: string;
   readonly hint: string;
-  readonly detail: HdrpIndexListOverflowDetail;
+  readonly detail: StandardClusterIndexOverflowDetail;
 
   constructor(actual: number, capacity: number) {
     const expected = `light index list entries <= ${capacity}`;
     const hint =
       `cluster binner overflow: writeCount ${actual} exceeds capacity ${capacity}; ` +
-      'reduce lights, shrink cluster grid, or increase LIGHT_INDEX_LIST_CAPACITY';
-    super(`HDRP index list overflow: ${actual} > ${capacity}`);
-    this.name = 'HdrpIndexListOverflowError';
+      'reduce finite local lights or choose a supported cluster layout';
+    super(`Standard cluster index list overflow: ${actual} > ${capacity}`);
+    this.name = 'StandardClusterIndexOverflowError';
     this.expected = expected;
     this.hint = hint;
     this.detail = { actual, capacity };
   }
 }
 
-// ── HdrpDeferredCapsInsufficientError ──────────────────────────────────────
+// ── StandardClusterTransportUnavailableError ───────────────────────────────
 
-/**
- * Detail for `RuntimeErrorCode 'hdrp-deferred-caps-insufficient'`.
- *
- * Emitted when the Standard clustered lane has fewer than 4 color attachments,
- * meaning the deferred path cannot allocate 3 g-buffer color targets + depth.
- */
-export interface HdrpDeferredCapsInsufficientDetail {
-  readonly actual: number;
-  readonly expected: number;
+export interface StandardClusterTransportUnavailableDetail {
+  readonly requested: number;
+  readonly admitted: 0;
 }
 
 /**
- * Structured error for deferred-path capability gate failure.
- *
- * Emitted during Standard clustered lane validation — synchronous throw.
- *   - `.code = 'hdrp-deferred-caps-insufficient'` (closed RuntimeErrorCode)
- *   - `.expected` — 'maxColorAttachments >= 4'
- *   - `.hint` — actionable guidance to upgrade browser or select URP
- *   - `.detail = { actual, expected }`
- *
- * @see plan-strategy D-5 (capability validation, no silent fallback)
+ * Structured capability refusal. Standard never turns an unproven transport
+ * into a smaller direct-light lane; the caller receives the exact requested
+ * local-light count and an admitted count of zero.
  */
-export class HdrpDeferredCapsInsufficientError extends Error {
-  readonly code = 'hdrp-deferred-caps-insufficient' as const;
-  readonly expected: string;
+export class StandardClusterTransportUnavailableError extends Error {
+  readonly code = 'standard-cluster-transport-unavailable' as const;
+  readonly expected = 'all requested local lights have a proven Cluster transport';
   readonly hint: string;
-  readonly detail: HdrpDeferredCapsInsufficientDetail;
+  readonly detail: StandardClusterTransportUnavailableDetail;
 
-  constructor(actual: number) {
-    const _expected = 4;
-    const _expectedStr = `maxColorAttachments >= ${_expected}`;
-    const hint =
-      `WebGPU maxColorAttachments = ${actual} (need >= ${_expected}). ` +
-      'Upgrade browser to latest Chrome/Edge/Safari, or use URP (forgeax::urp) instead of HDRP.';
-    super(
-      `HDRP deferred caps insufficient: maxColorAttachments = ${actual} (need >= ${_expected})`,
-    );
-    this.name = 'HdrpDeferredCapsInsufficientError';
-    this.expected = _expectedStr;
+  constructor(
+    requested: number,
+    hint = 'enable a proven Cluster storage transport before drawing',
+  ) {
+    super(`Standard Cluster transport unavailable for ${requested} local lights`);
+    this.name = 'StandardClusterTransportUnavailableError';
     this.hint = hint;
-    this.detail = { actual, expected: _expected };
+    this.detail = { requested, admitted: 0 };
+  }
+}
+
+// ── StandardProfileInvalidError ───────────────────────────────────────────
+
+export interface StandardProfileInvalidDetail {
+  readonly field: string;
+  readonly actual: unknown;
+}
+
+/** Structured validation failure for the single Standard profile surface. */
+export class StandardProfileInvalidError extends Error {
+  readonly code = 'standard-profile-invalid' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: StandardProfileInvalidDetail;
+
+  constructor(message: string, detail?: StandardProfileInvalidDetail) {
+    super(message);
+    this.name = 'StandardProfileInvalidError';
+    this.detail = detail ?? { field: 'profile', actual: message };
+    if (this.detail.field === 'clusterGrid') {
+      this.expected = 'clusterGrid.{x,y,z} each positive integer in [1, 64]';
+      this.hint =
+        'set clusterGrid.x, clusterGrid.y, and clusterGrid.z to positive integers in [1, 64]';
+    } else {
+      this.expected = 'StandardProfile contains only supported fields and values';
+      this.hint = 'repair the Standard profile fields and retry setProfile';
+    }
   }
 }
 
@@ -435,7 +446,7 @@ export interface PointShadowAtlasBoundsViolationDetail {
  *   - `.code = 'point-shadow-atlas-bounds-violation'`
  *   - `.expected` — `0 <= layer < layers && 0 <= face < 6`
  *   - `.hint` — clamp `shadowAtlasLayer` or face index before calling
- *     `faceView`; the cap on layers is `PointLightShadow` cardinality (4)
+ *     `faceView`; the layer cap is the renderer-owned ShadowAtlas capacity
  *   - `.detail = { axis, value, max }` — discriminates layer vs face
  */
 export class PointShadowAtlasBoundsViolationError extends Error {
@@ -1514,6 +1525,248 @@ export class PointsLinesPrepareFailedError extends Error {
   }
 }
 
+// -- RenderTarget errors ------------------------------------------------------
+
+export interface RenderTargetDescriptorInvalidDetail {
+  readonly field: string;
+  readonly value: unknown;
+  readonly expected: string;
+}
+
+export class RenderTargetDescriptorInvalidError extends Error {
+  readonly code = 'render-target-descriptor-invalid' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderTargetDescriptorInvalidDetail;
+
+  constructor(detail: RenderTargetDescriptorInvalidDetail) {
+    super(`render-target-descriptor-invalid: ${detail.field} does not satisfy ${detail.expected}`);
+    this.name = 'RenderTargetDescriptorInvalidError';
+    this.expected = detail.expected;
+    this.hint = `set RenderTargetDescriptor.${detail.field} to the expected value, then retry create or resize`;
+    this.detail = detail;
+  }
+}
+
+export interface RenderTargetCapabilityMissingDetail {
+  readonly operation: 'create' | 'resize' | 'source' | 'readback';
+  readonly requested: string;
+  readonly capability: string;
+  readonly actual: string;
+}
+
+export class RenderTargetCapabilityMissingError extends Error {
+  readonly code = 'render-target-capability-missing' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderTargetCapabilityMissingDetail;
+
+  constructor(detail: RenderTargetCapabilityMissingDetail) {
+    super(
+      `render-target-capability-missing: ${detail.capability} does not admit ${detail.requested}`,
+    );
+    this.name = 'RenderTargetCapabilityMissingError';
+    this.expected = `${detail.capability} admits ${detail.requested}`;
+    this.hint = `choose an admitted target descriptor or use a backend providing ${detail.capability}`;
+    this.detail = detail;
+  }
+}
+
+export type RenderTargetStateInvalidReason =
+  | 'foreign-renderer'
+  | 'destroyed'
+  | 'uninitialized'
+  | 'generation-mismatch'
+  | 'readback-without-intent';
+
+export interface RenderTargetStateInvalidDetail {
+  readonly operation: 'inspect' | 'resize' | 'source' | 'readback' | 'destroy';
+  readonly reason: RenderTargetStateInvalidReason;
+  readonly state: 'uninitialized' | 'candidate' | 'active' | 'rebuilding' | 'destroyed';
+  readonly generation: number;
+}
+
+export class RenderTargetStateInvalidError extends Error {
+  readonly code = 'render-target-state-invalid' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderTargetStateInvalidDetail;
+
+  constructor(detail: RenderTargetStateInvalidDetail) {
+    super(`render-target-state-invalid: ${detail.operation} cannot use ${detail.reason}`);
+    this.name = 'RenderTargetStateInvalidError';
+    this.expected = `target state permits ${detail.operation}`;
+    this.hint =
+      'use the Renderer that created the target, then initialize, recover, or stop using the destroyed token';
+    this.detail = detail;
+  }
+}
+
+export interface RenderTargetOperationFailedDetail {
+  readonly operation: 'create' | 'resize' | 'source' | 'readback' | 'destroy' | 'recover';
+  readonly stage: 'allocation' | 'compile' | 'write' | 'submit' | 'copy' | 'retire';
+  readonly generation: number;
+  readonly cause: unknown;
+  readonly recovery: 'retry' | 'recover' | 'retain-last-known-good';
+}
+
+export class RenderTargetOperationFailedError extends Error {
+  readonly code = 'render-target-operation-failed' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderTargetOperationFailedDetail;
+
+  constructor(detail: RenderTargetOperationFailedDetail) {
+    super(`render-target-operation-failed: ${detail.operation} failed during ${detail.stage}`);
+    this.name = 'RenderTargetOperationFailedError';
+    this.expected = `${detail.operation} completes ${detail.stage}`;
+    this.hint =
+      'inspect detail.cause, then retry, recover the Renderer, or retain the last-known-good generation';
+    this.detail = detail;
+  }
+}
+
+export interface ReflectionProbeBudgetExceededDetail {
+  readonly actual: number;
+  readonly budget: number;
+}
+
+export class ReflectionProbeBudgetExceededError extends Error {
+  readonly code = 'reflection-probe-budget-exceeded' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: ReflectionProbeBudgetExceededDetail;
+
+  constructor(actual: number, budget: number) {
+    super(`reflection-probe-budget-exceeded: ${actual} > ${budget}`);
+    this.name = 'ReflectionProbeBudgetExceededError';
+    this.expected = `reflection probe work <= ${budget}`;
+    this.hint = 'reduce probe updates for this frame or raise the RenderProfile probe budget';
+    this.detail = { actual, budget };
+  }
+}
+
+export interface RenderIntentInvalidDetail {
+  readonly component: 'CubeCamera' | 'ReflectionProbe';
+  readonly field: 'updateIntent';
+  readonly value: number;
+  readonly allowed: readonly [0, 1, 2];
+}
+
+export class RenderIntentInvalidError extends Error {
+  readonly code = 'render-intent-invalid' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderIntentInvalidDetail;
+
+  constructor(component: RenderIntentInvalidDetail['component'], value: number) {
+    super(`render-intent-invalid: ${component}.updateIntent is not an admitted value`);
+    this.name = 'RenderIntentInvalidError';
+    this.expected = `${component}.updateIntent is one of 0, 1, or 2`;
+    this.hint = `set ${component}.updateIntent to 0, 1, or 2`;
+    this.detail = { component, field: 'updateIntent', value, allowed: [0, 1, 2] };
+  }
+}
+
+export interface VolumeOwnerConflictDetail {
+  readonly ownerCount: number;
+}
+
+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 detail: VolumeOwnerConflictDetail;
+
+  constructor(ownerCount: number) {
+    super(`volume-owner-conflict: received ${ownerCount} owners`);
+    this.name = 'VolumeOwnerConflictError';
+    this.detail = { ownerCount };
+  }
+}
+
+export interface VolumeDensityShapeMismatchDetail {
+  readonly guid: string;
+  readonly viewDimension: string;
+}
+
+export class VolumeDensityShapeMismatchError extends Error {
+  readonly code = 'volume-density-shape-mismatch' as const;
+  readonly expected = 'density is a linear 3D TextureAsset';
+  readonly hint = 'bind a verified linear texture with viewDimension 3d';
+  readonly detail: VolumeDensityShapeMismatchDetail;
+
+  constructor(guid: string, viewDimension: string) {
+    super(`volume-density-shape-mismatch: ${viewDimension} density is not 3d`);
+    this.name = 'VolumeDensityShapeMismatchError';
+    this.detail = { guid, viewDimension };
+  }
+}
+
+export interface VolumeInvalidBoundsDetail {
+  readonly min: readonly [number, number, number];
+  readonly max: readonly [number, number, number];
+}
+
+export class VolumeInvalidBoundsError extends Error {
+  readonly code = 'volume-invalid-bounds' as const;
+  readonly expected = 'bounds are finite and max is greater than min on every axis';
+  readonly hint = 'set finite non-degenerate volume bounds';
+  readonly detail: VolumeInvalidBoundsDetail;
+
+  constructor(bounds: VolumeInvalidBoundsDetail) {
+    super('volume-invalid-bounds: bounds must be finite and non-degenerate');
+    this.name = 'VolumeInvalidBoundsError';
+    this.detail = bounds;
+  }
+}
+
+export interface VolumeInvalidParametersDetail {
+  readonly field: string;
+  readonly value: unknown;
+}
+
+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 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;
+    super(`volume-invalid-parameters: ${field} is outside the authored range`);
+    this.name = 'VolumeInvalidParametersError';
+    this.detail = { field, value };
+  }
+}
+
+export type VolumeError =
+  | VolumeOwnerConflictError
+  | VolumeDensityShapeMismatchError
+  | VolumeInvalidBoundsError
+  | VolumeInvalidParametersError;
+
+export interface ProjectorBindingDetail {
+  readonly guid: string;
+  readonly status: 'pending' | 'invalid' | 'bind-failed';
+}
+
+export class ProjectorBindingError extends Error {
+  readonly code = 'projector-binding-failed' as const;
+  readonly expected = 'authored projector is accepted and bound for both surface and volume';
+  readonly hint =
+    'inspect the projector Meta/Pack receipt, repair the source, and retry with the same GUID';
+  readonly detail: ProjectorBindingDetail;
+
+  constructor(guid: string, status: ProjectorBindingDetail['status']) {
+    super(`projector binding failed for ${guid}: ${status}`);
+    this.name = 'ProjectorBindingError';
+    this.detail = { guid, status };
+  }
+}
+
 // -- RenderErrorCode / RenderError closed unions --------------------------------
 
 /**
@@ -1536,9 +1789,10 @@ export type RenderError =
   | TaaUnavailableError
   | ShadowInvalidConfigError
   | EquirectProjectionFailedError
-  | HdrpLightBudgetExceededError
-  | HdrpIndexListOverflowError
-  | HdrpDeferredCapsInsufficientError
+  | StandardLightBudgetExceededError
+  | StandardClusterIndexOverflowError
+  | StandardClusterTransportUnavailableError
+  | StandardProfileInvalidError
   | PointShadowAtlasUninitializedError
   | PointShadowAtlasBoundsViolationError
   | VideoUploadUnsupportedError
@@ -1566,4 +1820,12 @@ export type RenderError =
   | PointsLinesStyleUnsupportedError
   | PointsLinesMaterialUnsupportedError
   | PointsLinesBudgetExceededError
-  | PointsLinesPrepareFailedError;
+  | PointsLinesPrepareFailedError
+  | RenderTargetDescriptorInvalidError
+  | RenderTargetCapabilityMissingError
+  | RenderTargetStateInvalidError
+  | RenderTargetOperationFailedError
+  | ReflectionProbeBudgetExceededError
+  | RenderIntentInvalidError
+  | ProjectorBindingError
+  | VolumeError;