@forgeax/engine-render 0.1.20 → 0.1.21

package/src/errors/render.ts

@@ -138,49 +138,33 @@ export class TemporalFrameSubmitError extends Error {
 /**
  * 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;
@@ -188,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(', ')}]`;
   }
 }
 
@@ -270,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';
+    }
   }
 }
 
@@ -452,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 {
@@ -1531,6 +1525,149 @@ 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;
 }
@@ -1652,9 +1789,10 @@ export type RenderError =
   | TaaUnavailableError
   | ShadowInvalidConfigError
   | EquirectProjectionFailedError
-  | HdrpLightBudgetExceededError
-  | HdrpIndexListOverflowError
-  | HdrpDeferredCapsInsufficientError
+  | StandardLightBudgetExceededError
+  | StandardClusterIndexOverflowError
+  | StandardClusterTransportUnavailableError
+  | StandardProfileInvalidError
   | PointShadowAtlasUninitializedError
   | PointShadowAtlasBoundsViolationError
   | VideoUploadUnsupportedError
@@ -1683,5 +1821,11 @@ export type RenderError =
   | PointsLinesMaterialUnsupportedError
   | PointsLinesBudgetExceededError
   | PointsLinesPrepareFailedError
+  | RenderTargetDescriptorInvalidError
+  | RenderTargetCapabilityMissingError
+  | RenderTargetStateInvalidError
+  | RenderTargetOperationFailedError
+  | ReflectionProbeBudgetExceededError
+  | RenderIntentInvalidError
   | ProjectorBindingError
   | VolumeError;

package/src/extract/directional-shadow-projection.ts

@@ -0,0 +1,61 @@
+// @forgeax/engine-render - Directional CSM projection owner.
+
+import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
+import { directionalShadowQualityFromF32 } from '../components/directional-shadow-filter';
+
+/** Light-space bounds produced by one existing orthographic CSM fit. */
+export interface DirectionalShadowCascadeFit {
+  readonly split: number;
+  readonly minX: number;
+  readonly maxX: number;
+  readonly minY: number;
+  readonly maxY: number;
+  readonly minZ: number;
+  readonly maxZ: number;
+}
+
+/** Host projection sent to the shared View UBO. */
+export interface DirectionalShadowProjection {
+  readonly splitPlanes: Float32Array;
+  readonly directionalShadowQuality: DirectionalShadowQuality;
+}
+
+/**
+ * Project accepted Directional author facts and the existing CSM fit into the
+ * shared split vec4 lanes. `.x` is the split, `.y` is world units per texel,
+ * `.z` is the light-space depth span, and `.w` is reserved for the ABI.
+ */
+export function projectDirectionalShadow(
+  fits: readonly DirectionalShadowCascadeFit[],
+  mapSize: number,
+  shadowFilter: number,
+  shadowAngularRadius: number,
+  maxPenumbraTexels: number,
+): DirectionalShadowProjection | undefined {
+  if (!Number.isFinite(mapSize) || mapSize < 1) return undefined;
+  const directionalShadowQuality = directionalShadowQualityFromF32(
+    shadowFilter,
+    shadowAngularRadius,
+    maxPenumbraTexels,
+  );
+  if (directionalShadowQuality === undefined) return undefined;
+
+  const splitPlanes = new Float32Array(16);
+  for (let index = 0; index < fits.length && index < 4; index += 1) {
+    const fit = fits[index];
+    if (fit === undefined) continue;
+    const width = Math.abs(fit.maxX - fit.minX);
+    const height = Math.abs(fit.maxY - fit.minY);
+    const depth = Math.abs(fit.maxZ - fit.minZ);
+    const worldUnitsPerTexel = Math.max(width, height, Number.EPSILON) / mapSize;
+    const lightDepthWorldSpan = Math.max(depth, Number.EPSILON);
+    if (!Number.isFinite(worldUnitsPerTexel) || !Number.isFinite(lightDepthWorldSpan)) {
+      return undefined;
+    }
+    const lane = index * 4;
+    splitPlanes[lane] = fit.split;
+    splitPlanes[lane + 1] = worldUnitsPerTexel;
+    splitPlanes[lane + 2] = lightDepthWorldSpan;
+  }
+  return { splitPlanes, directionalShadowQuality };
+}

package/src/extract/environment.ts

@@ -76,6 +76,20 @@ export type EnvironmentSource =
 
 export interface FogFrame extends FogCandidate {}
 
+export interface FogParameterIssue {
+  readonly field: string;
+  readonly value: number;
+  readonly expected: string;
+}
+
+/** Structured failure retained when an invalid Fog update falls back to LKG. */
+export interface FogSelectionFailure {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: Readonly<Record<string, unknown>>;
+}
+
 export interface EnvironmentFrame {
   readonly source: EnvironmentSource;
   /** Descriptor of the real environment resource adopted for this frame. */
@@ -103,6 +117,49 @@ function freezeFog(candidate: FogCandidate): FogFrame {
   });
 }
 
+/** Validate the bounded Fog domain once for every frame-selection producer. */
+export function validateFogParameters(candidate: FogCandidate): FogParameterIssue | undefined {
+  if (candidate.color.length !== 3) {
+    return {
+      field: 'color',
+      value: candidate.color.length,
+      expected: 'exactly three finite channels in [0, 1]',
+    };
+  }
+  for (let index = 0; index < candidate.color.length; index += 1) {
+    const value = candidate.color[index];
+    if (value === undefined || !Number.isFinite(value) || value < 0 || value > 1) {
+      return {
+        field: `color[${index}]`,
+        value: value ?? Number.NaN,
+        expected: 'a finite number in [0, 1]',
+      };
+    }
+  }
+  if (!Number.isFinite(candidate.density) || candidate.density < 0) {
+    return { field: 'density', value: candidate.density, expected: 'a finite number >= 0' };
+  }
+  if (!Number.isFinite(candidate.heightFalloff) || candidate.heightFalloff < 0) {
+    return {
+      field: 'heightFalloff',
+      value: candidate.heightFalloff,
+      expected: 'a finite number >= 0',
+    };
+  }
+  if (
+    !Number.isFinite(candidate.maxOpacity) ||
+    candidate.maxOpacity < 0 ||
+    candidate.maxOpacity > 1
+  ) {
+    return {
+      field: 'maxOpacity',
+      value: candidate.maxOpacity,
+      expected: 'a finite number in [0, 1]',
+    };
+  }
+  return undefined;
+}
+
 function freezeAtmosphere(parameters: AtmosphereParameters): AtmosphereParameters {
   return Object.freeze({ ...parameters });
 }