@forgeax/engine-render 0.1.20 → 0.1.23

package/dist/{chunk-TBQJOK2L.mjs → chunk-QODA5UKU.mjs}

@@ -1,4 +1,4 @@
-import { err, ok } from '@forgeax/engine-types';
+import { cubeArrayDepthDescriptor, comparisonSamplerDescriptor, cubeArrayDepthFaceView } from '@forgeax/engine-rhi';
 
 // src/errors/render.ts
 var LifecycleConstructionError = class extends Error {
@@ -12,6 +12,33 @@ var LifecycleConstructionError = class extends Error {
     this.detail = detail;
   }
 };
+var LightResourceUnavailableError = class extends Error {
+  code = "light-resource-unavailable";
+  expected;
+  hint;
+  detail;
+  constructor(detail, expected, actual, hint) {
+    super(`light-resource-unavailable: ${detail.feature} ${actual}`);
+    this.name = "LightResourceUnavailableError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+  }
+};
+function createLightResourceUnavailable(input) {
+  return new LightResourceUnavailableError(
+    {
+      entity: input.entity,
+      feature: input.feature,
+      generation: input.generation,
+      sourceKey: input.sourceKey,
+      reason: input.reason
+    },
+    input.expected,
+    input.actual,
+    input.hint
+  );
+}
 var TemporalFrameSubmitError = class extends Error {
   code = "temporal-frame-submit-rejected";
   expected = "the staged frame is accepted by queue.submit before temporal facts advance";
@@ -28,23 +55,42 @@ var ShadowInvalidConfigError = class extends Error {
   expected;
   hint;
   detail;
-  constructor(field, value, min, maxOrComparator) {
-    const isComparator = maxOrComparator === ">" || maxOrComparator === ">=";
-    const max = !isComparator && typeof maxOrComparator === "number" ? maxOrComparator : void 0;
-    const comparator = isComparator ? maxOrComparator : ">=";
-    const isInteger = field === "cascadeCount" || field === "pcfKernelSize";
-    const isOdd = field === "pcfKernelSize";
-    const hint = max !== void 0 ? 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 !== void 0 ? `${field} in [${min}, ${max}]` : `${field} ${comparator} ${min}`;
-    super(
-      max !== void 0 ? `shadow component .${field} must be in [${min}, ${max}], got ${value}` : `shadow component .${field} must be ${comparator} ${min}, got ${value}`
-    );
+  constructor(field, actual, minOrBound, maxOrComparator, reason) {
+    const bound = 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 !== void 0 ? { max } : {} };
+    this.detail = { field, actual, bound, reason: resolvedReason };
   }
 };
+function shadowBoundExpected(field, bound) {
+  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) {
+  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(", ")}]`;
+  }
+}
 var EquirectProjectionFailedError = class extends Error {
   code = "equirect-projection-failed";
   expected;
@@ -60,52 +106,64 @@ var EquirectProjectionFailedError = class extends Error {
     this.detail = { handle };
   }
 };
-var HdrpLightBudgetExceededError = class extends Error {
-  code = "hdrp-light-budget-exceeded";
+var StandardLightBudgetExceededError = class extends Error {
+  code = "standard-light-budget-exceeded";
   expected;
   hint;
   detail;
   constructor(actual, budget) {
     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";
+    const hint = `${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 };
   }
 };
-var HdrpIndexListOverflowError = class extends Error {
-  code = "hdrp-index-list-overflow";
+var StandardClusterIndexOverflowError = class extends Error {
+  code = "standard-cluster-index-overflow";
   expected;
   hint;
   detail;
   constructor(actual, capacity) {
     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";
+    const hint = `cluster binner overflow: writeCount ${actual} exceeds capacity ${capacity}; 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 };
   }
 };
-var HdrpDeferredCapsInsufficientError = class extends Error {
-  code = "hdrp-deferred-caps-insufficient";
-  expected;
+var StandardClusterTransportUnavailableError = class extends Error {
+  code = "standard-cluster-transport-unavailable";
+  expected = "all requested local lights have a proven Cluster transport";
   hint;
   detail;
-  constructor(actual) {
-    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, 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 };
+  }
+};
+var StandardProfileInvalidError = class extends Error {
+  code = "standard-profile-invalid";
+  expected;
+  hint;
+  detail;
+  constructor(message, detail) {
+    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";
+    }
   }
 };
 var PointShadowAtlasUninitializedError = class extends Error {
@@ -602,6 +660,73 @@ var PointsLinesPrepareFailedError = class extends Error {
     this.detail = detail;
   }
 };
+var RenderTargetDescriptorInvalidError = class extends Error {
+  code = "render-target-descriptor-invalid";
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    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;
+  }
+};
+var RenderTargetCapabilityMissingError = class extends Error {
+  code = "render-target-capability-missing";
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    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;
+  }
+};
+var RenderTargetStateInvalidError = class extends Error {
+  code = "render-target-state-invalid";
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    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;
+  }
+};
+var RenderTargetOperationFailedError = class extends Error {
+  code = "render-target-operation-failed";
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    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;
+  }
+};
+var RenderIntentInvalidError = class extends Error {
+  code = "render-intent-invalid";
+  expected;
+  hint;
+  detail;
+  constructor(component, value) {
+    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] };
+  }
+};
 var VolumeOwnerConflictError = class extends Error {
   code = "volume-owner-conflict";
   expected = "exactly one global VolumetricFog owner is authored";
@@ -649,240 +774,164 @@ var VolumeInvalidParametersError = class extends Error {
   }
 };
 
-// src/temporal/scene-data.ts
-var SCENE_DATA_TEMPORAL_V1_SCHEMA = "forgeax::scene-data::temporal-v1";
-var SCENE_DATA_TEMPORAL_V1_DESCRIPTOR = Object.freeze({
-  schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
-  format: "rgba16float",
-  sampleCount: 1,
-  extent: "render-resolution",
-  clearValue: [0, 0, -1, 1],
-  channels: Object.freeze({
-    motionUv: "rg",
-    viewDepth: "b-log2-1-plus-depth",
-    reactive: "a"
-  })
-});
-var targetOwners = /* @__PURE__ */ new WeakMap();
-function registerSceneDataTarget(target, owner) {
-  targetOwners.set(target, owner);
-}
-function sceneDataTargetOwner(target) {
-  return typeof target === "object" && target !== null ? targetOwners.get(target) : void 0;
-}
-function sceneDataTokenMismatch(operation, reason, owner, target) {
-  const detail = reason === "generation-mismatch" ? {
-    featureIdentity: owner.featureIdentity,
-    order: -1,
-    stage: "contribute",
-    operation,
-    resourceKind: "attachment",
-    reason,
-    expectedGeneration: owner.generation,
-    actualGeneration: targetOwners.get(target)?.generation ?? -1,
-    recovery: "renderer-recover"
-  } : reason === "foreign-feature" ? {
-    featureIdentity: owner.featureIdentity,
-    order: -1,
-    stage: "contribute",
-    operation,
-    resourceKind: "attachment",
-    reason,
-    expectedFeatureIdentity: owner.featureIdentity,
-    actualFeatureIdentity: targetOwners.get(target)?.featureIdentity ?? "unknown",
-    recovery: "next-frame"
-  } : reason === "foreign-kind" ? {
-    featureIdentity: owner.featureIdentity,
-    order: -1,
-    stage: "contribute",
-    operation,
-    resourceKind: "attachment",
-    reason,
-    expectedKind: "attachment",
-    actualKind: "pipeline",
-    recovery: "next-frame"
-  } : {
-    featureIdentity: owner.featureIdentity,
-    order: -1,
-    stage: "contribute",
-    operation,
-    resourceKind: "attachment",
-    reason,
-    expectedLayout: "sampled-read-temporal-v1",
-    actualLayout: target?.access ?? "unknown",
-    recovery: "next-frame"
-  };
-  return new RenderFeaturePreparedStateMismatchError(detail);
-}
-function isSceneDataTarget(value) {
-  if (value === null || typeof value !== "object") return false;
-  const candidate = value;
-  return candidate.kind === "scene-data" && candidate.schema === SCENE_DATA_TEMPORAL_V1_SCHEMA && candidate.access === "sampled-read" && candidate.format === "rgba16float" && candidate.sampleCount === 1 && candidate.extent === "render-resolution" && targetOwners.has(value);
-}
-function sceneDataTargetAsAttachment(_target) {
-  throw new TypeError("SceneDataTarget is sampled-read-only and cannot be used as an attachment");
-}
-function sceneDataError(error) {
-  return error;
-}
-function availability(options) {
-  if (options.recovering) return { status: "unavailable", reason: "renderer-recovering" };
-  if (!options.rgba16floatRenderable)
-    return { status: "unavailable", reason: "capability-missing" };
-  if (options.producerPresent === false)
-    return { status: "unavailable", reason: "producer-missing" };
-  if (options.coverageComplete === false)
-    return { status: "unavailable", reason: "coverage-incomplete" };
-  return {
-    status: "available",
-    completeness: options.reactiveFallback ? "exact-with-reactive-fallback" : "exact"
-  };
-}
-function createTarget(owner) {
-  const target = Object.freeze({
-    kind: "scene-data",
-    schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
-    access: "sampled-read",
-    format: "rgba16float",
-    sampleCount: 1,
-    extent: "render-resolution"
-  });
-  registerSceneDataTarget(target, {
-    featureIdentity: owner.featureIdentity,
-    planIdentity: owner.planIdentity,
-    generation: owner.generation
-  });
-  return target;
-}
-function tokenError(catalog, operation) {
-  return sceneDataTokenMismatch(
-    operation,
-    "foreign-kind",
-    {
-      featureIdentity: catalog.featureIdentity,
-      planIdentity: catalog.planIdentity,
-      generation: catalog.generation
-    },
-    void 0
-  );
-}
-function unavailableError(options, reason) {
-  const recovery = reason === "capability-missing" ? "enable-capability" : reason === "renderer-recovering" ? "renderer-recover" : "next-frame";
-  return new SceneDataUnavailableError({
-    featureIdentity: options.featureIdentity,
-    schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
-    lane: options.lane ?? "direct",
-    reason,
-    missingContributorIds: options.missingContributorIds ?? [],
-    omittedMissingContributorCount: 0,
-    recovery
-  });
-}
-function createSceneDataCatalog(options) {
-  const state = availability(options);
-  const owner = {
-    featureIdentity: options.featureIdentity,
-    planIdentity: options.planIdentity,
-    generation: options.generation
-  };
-  const missing = [...options.missingContributorIds ?? []];
-  const inspectionBase = {
-    schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
-    generation: options.generation,
-    planIdentity: options.planIdentity,
-    lane: options.lane ?? "direct",
-    missingContributorIds: Object.freeze(missing.slice(0, 32)),
-    omittedMissingContributorCount: Math.max(0, missing.length - 32)
-  };
-  return {
-    schema: SCENE_DATA_TEMPORAL_V1_SCHEMA,
-    generation: options.generation,
-    planIdentity: options.planIdentity,
-    availability: state,
-    require(schema) {
-      if (schema !== SCENE_DATA_TEMPORAL_V1_SCHEMA || state.status !== "available") {
-        if (state.status === "unavailable") throw unavailableError(options, state.reason);
-        throw tokenError(options, "require scene-data target");
-      }
-      return createTarget(options);
-    },
-    validate(target, generation = options.generation) {
-      const targetOwner = sceneDataTargetOwner(target);
-      if (targetOwner === void 0) {
-        return err(
-          sceneDataTokenMismatch("validate scene-data target", "foreign-feature", owner, target)
-        );
-      }
-      if (targetOwner.planIdentity !== owner.planIdentity || targetOwner.featureIdentity !== owner.featureIdentity) {
-        return err(
-          sceneDataTokenMismatch("validate scene-data target", "foreign-feature", owner, target)
-        );
-      }
-      if (generation !== owner.generation || targetOwner.generation !== owner.generation) {
-        return err(
-          sceneDataTokenMismatch(
-            "validate scene-data target",
-            "generation-mismatch",
-            owner,
-            target
-          )
-        );
-      }
-      if (target.access !== "sampled-read") {
-        return err(
-          sceneDataTokenMismatch("validate scene-data target", "layout-mismatch", owner, target)
-        );
-      }
-      return ok(target);
-    },
-    inspect() {
-      return Object.freeze(
-        state.status === "available" ? { ...inspectionBase, status: state.status, completeness: state.completeness } : { ...inspectionBase, status: state.status, reason: state.reason }
-      );
-    }
-  };
-}
+// src/gpu-texture-usage.ts
+var GPU_TEXTURE_USAGE_COPY_SRC = 1;
+var GPU_TEXTURE_USAGE_COPY_DST = 2;
+var GPU_TEXTURE_USAGE_TEXTURE_BINDING = 4;
+var GPU_TEXTURE_USAGE_RENDER_ATTACHMENT = 16;
+var GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING = GPU_TEXTURE_USAGE_RENDER_ATTACHMENT | GPU_TEXTURE_USAGE_TEXTURE_BINDING;
 
-// src/pipeline/standard-profile.ts
-var STANDARD_PIPELINE_ID = "forgeax::standard";
-var STANDARD_LIGHT_COUNTS = [1, 32, 256];
-var DEFAULT_CLUSTER_GRID = { x: 16, y: 9, z: 24 };
-var CLUSTER_GRID_STRIDE_U32 = 2;
-var LIGHT_INDEX_LIST_CAPACITY = 1048576;
-var MAX_LIGHTS = 256;
-var STANDARD_POST_STAGE_NAMES = [
-  "transparent-blend",
-  "bloom",
-  "output-transform",
-  "fxaa",
-  "post-effect",
-  "present"
-];
-var DEFAULT_STANDARD_PROFILE = Object.freeze({
-  pipelineId: STANDARD_PIPELINE_ID,
-  lightCount: 32,
-  lighting: "direct",
-  shadows: "filtered",
-  pbr: true,
-  ibl: true,
-  ssao: false,
-  bloom: true,
-  tone: "aces-filmic",
-  antialias: "fxaa",
-  sky: true,
-  fallback: "native",
-  postStages: STANDARD_POST_STAGE_NAMES
-});
-function resolveVolumetricFogProfile(profile) {
-  return profile.volumetricFog ?? { quality: "high", depth: 64, tileSize: 4 };
-}
-function resolveStandardLane(profile, capabilities) {
-  if (!capabilities.compute || !capabilities.storageBuffer) return "cpu-webgl2";
-  return profile.lighting;
-}
+// src/shadow-atlas.ts
+var SHADOW_ATLAS_DEFAULT_FACE_SIZE = 512;
+var SHADOW_ATLAS_DEFAULT_LAYERS = 4;
+var ShadowAtlas = class {
+  /** Backing cube_array depth texture. `null` until `ensure()` has run. */
+  texture = null;
+  /**
+   * Whole-atlas cube_array sampling view used by URP shaders that bind the
+   * atlas at `@group(0) @binding(5)`. `null` until `ensure()` has run.
+   */
+  cubeArrayView = null;
+  /** Comparison sampler for `texture_depth_cube_array`. */
+  compareSampler = null;
+  /** Per-face 2D depth view cache, keyed by `layer * 6 + face`. */
+  faceViews = /* @__PURE__ */ new Map();
+  /** Per-face label cache (debug aid). Reused on re-creation. */
+  device;
+  /** Per-face square size in pixels. */
+  faceSize;
+  /** Cube layer count. */
+  layers;
+  constructor(device, options = {}) {
+    this.device = device;
+    this.faceSize = options.faceSize ?? SHADOW_ATLAS_DEFAULT_FACE_SIZE;
+    this.layers = options.layers ?? SHADOW_ATLAS_DEFAULT_LAYERS;
+  }
+  /**
+   * Returns `true` once the atlas texture is allocated. Used by the extract /
+   * record path to gate "no PointLightShadow → no allocation" (AC-09) — the
+   * caller calls {@link ensure} on a frame that has at least one snapshot;
+   * before that, `isAllocated()` stays `false` and tests can assert no GPU
+   * resources were created.
+   */
+  isAllocated() {
+    return this.texture !== null;
+  }
+  /**
+   * Lazy-allocate the atlas texture + cube_array sampling view + comparison
+   * sampler. Idempotent: subsequent calls are zero-cost no-ops once the
+   * resources exist.
+   *
+   * Throws (via the RHI error registry) on allocation failure. This is the
+   * only path that touches the GPU — keeping it inside one method makes the
+   * "zero-shadow scene = zero allocation" gate easy to enforce: the renderer
+   * never calls this method on a frame with no PointLightShadow entities.
+   */
+  ensure() {
+    if (this.texture !== null) return;
+    const usage = GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING;
+    const texDesc = cubeArrayDepthDescriptor(this.faceSize, this.layers, usage);
+    const texRes = this.device.createTexture(texDesc);
+    if (!texRes.ok) throw texRes.error;
+    this.texture = texRes.value;
+    const viewRes = this.device.createTextureView(this.texture, {
+      label: "shadow-atlas-cube-array-view",
+      dimension: "cube-array",
+      aspect: "depth-only",
+      baseArrayLayer: 0,
+      arrayLayerCount: 6 * this.layers,
+      baseMipLevel: 0,
+      mipLevelCount: 1
+    });
+    if (!viewRes.ok) {
+      this.device.destroyTexture(this.texture);
+      this.texture = null;
+      throw viewRes.error;
+    }
+    this.cubeArrayView = viewRes.value;
+    const sampRes = this.device.createSampler(comparisonSamplerDescriptor());
+    if (!sampRes.ok) {
+      this.device.destroyTexture(this.texture);
+      this.texture = null;
+      this.cubeArrayView = null;
+      throw sampRes.error;
+    }
+    this.compareSampler = sampRes.value;
+  }
+  /**
+   * Whole-atlas cube_array sampling view (`texture_depth_cube_array`). Returns
+   * `null` if the atlas is not yet allocated; the caller should gate on a
+   * non-null pointShadow array before calling {@link ensure} + this getter.
+   */
+  getAtlasView() {
+    return this.cubeArrayView;
+  }
+  /**
+   * Comparison sampler (`compare: 'less'`) for cube_array depth sampling.
+   * Returns `null` if the atlas is not yet allocated.
+   */
+  getComparisonSampler() {
+    return this.compareSampler;
+  }
+  /**
+   * Backing texture handle. Returns `null` if the atlas is not yet allocated.
+   */
+  getTexture() {
+    return this.texture;
+  }
+  /**
+   * Lazy 2D depth view selecting `(layer, face)` (the caller passes
+   * `shadowAtlasLayer` from the snapshot and a face index 0..5). Used as the
+   * depth attachment of the shadow-caster render pass for one cube face.
+   *
+   * Caches per `(layer, face)` so the per-frame shadow loop pays zero
+   * `createTextureView` cost after the first allocation. Cache is cleared on
+   * {@link dispose}.
+   *
+   * @throws PointShadowAtlasUninitializedError if the atlas is not yet
+   *   allocated (caller must call {@link ensure} first).
+   * @throws PointShadowAtlasBoundsViolationError if `layer` or `face` is out
+   *   of range.
+   * @throws RhiError if the underlying `createTextureView` fails.
+   */
+  faceView(layer, face) {
+    if (this.texture === null) {
+      throw new PointShadowAtlasUninitializedError();
+    }
+    if (layer < 0 || layer >= this.layers) {
+      throw new PointShadowAtlasBoundsViolationError("layer", layer, this.layers);
+    }
+    if (face < 0 || face >= 6) {
+      throw new PointShadowAtlasBoundsViolationError("face", face, 6);
+    }
+    const key = layer * 6 + face;
+    const cached = this.faceViews.get(key);
+    if (cached !== void 0) return cached;
+    const desc = cubeArrayDepthFaceView(layer, face);
+    const r = this.device.createTextureView(this.texture, desc);
+    if (!r.ok) throw r.error;
+    this.faceViews.set(key, r.value);
+    return r.value;
+  }
+  /**
+   * Release the GPU resources and clear the per-face view cache. Idempotent;
+   * subsequent calls are zero-cost. After dispose, `isAllocated()` returns
+   * `false` and the next `ensure()` re-allocates from scratch.
+   */
+  dispose() {
+    this.faceViews.clear();
+    if (this.texture !== null) {
+      this.device.destroyTexture(this.texture);
+      this.texture = null;
+    }
+    this.cubeArrayView = null;
+    this.compareSampler = null;
+  }
+};
 
 // src/render-contract.ts
 var STANDARD_OUTPUT_TRANSFORM_FEATURE_ID = "forgeax::standard::output-transform";
+var FXAA_POST_PROCESS_ID = "forgeax::post::fxaa";
 var RENDER_GRAPH_EXECUTION_PHASE_CATALOG = [
   "record/graph-execute/point-shadow",
   "record/graph-execute/cluster-binner-upload",
@@ -939,6 +988,8 @@ var RENDER_SCENE_STATE_PHASE_CATALOG = [
   ...RENDER_HDRP_CLUSTER_PHASE_CATALOG
 ];
 var RENDER_RECORD_PHASE_CATALOG = [
+  "record/occlusion-query-submit",
+  "record/occlusion-global-advance",
   "record/scene-state",
   ...RENDER_SCENE_STATE_PHASE_CATALOG,
   "record/swapchain",
@@ -953,6 +1004,7 @@ var RENDER_RECORD_PHASE_CATALOG = [
 ];
 var RENDER_PHASE_CATALOG = [
   "extract",
+  "occlusion-prepare",
   "bind-groups",
   "features",
   "sort",
@@ -960,6 +1012,6 @@ var RENDER_PHASE_CATALOG = [
   ...RENDER_RECORD_PHASE_CATALOG
 ];
 
-export { AtmosphereInvalidParameterError, CLUSTER_GRID_STRIDE_U32, DEFAULT_CLUSTER_GRID, DEFAULT_STANDARD_PROFILE, EnvironmentGenerationFailedError, EnvironmentSourceConflictError, EquirectProjectionFailedError, FogCardinalityError, FrameReceiptStaleError, HdrpDeferredCapsInsufficientError, HdrpIndexListOverflowError, HdrpLightBudgetExceededError, LIGHT_INDEX_LIST_CAPACITY, LifecycleConstructionError, MAX_LIGHTS, MaterialSkinAttrMissingError, ObservationUnavailableError, OwnerStageFailedError, PointShadowAtlasBoundsViolationError, PointShadowAtlasUninitializedError, PointsLinesBudgetExceededError, PointsLinesInvalidStyleError, PointsLinesMaterialUnsupportedError, PointsLinesPrepareFailedError, PointsLinesStyleUnsupportedError, PointsLinesTopologyMismatchError, RENDER_PHASE_CATALOG, RenderFeatureCapabilityMissingError, RenderFeatureDrawRecordingFailedError, RenderFeaturePreparationFailedError, RenderFeaturePreparedStateMismatchError, RenderFeatureRegistrationConflictError, RenderFeatureStageFailedError, RendererContractFailureError, RendererOperationError, SCENE_DATA_TEMPORAL_V1_DESCRIPTOR, SCENE_DATA_TEMPORAL_V1_SCHEMA, STANDARD_LIGHT_COUNTS, STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, STANDARD_PIPELINE_ID, STANDARD_POST_STAGE_NAMES, SceneDataUnavailableError, ShadowInvalidConfigError, SkinMaterialMismatchError, SkinPaletteOverflowError, TaaCapsInsufficientError, TemporalFrameSubmitError, TransmissionCapabilityMissingError, VertexColorVariantConflictError, VideoUploadUnsupportedError, VolumeDensityShapeMismatchError, VolumeInvalidBoundsError, VolumeInvalidParametersError, VolumeOwnerConflictError, createSceneDataCatalog, isSceneDataTarget, registerSceneDataTarget, resolveStandardLane, resolveVolumetricFogProfile, sceneDataError, sceneDataTargetAsAttachment, sceneDataTargetOwner, sceneDataTokenMismatch };
-//# sourceMappingURL=chunk-TBQJOK2L.mjs.map
-//# sourceMappingURL=chunk-TBQJOK2L.mjs.map
+export { AtmosphereInvalidParameterError, EnvironmentGenerationFailedError, EnvironmentSourceConflictError, EquirectProjectionFailedError, FXAA_POST_PROCESS_ID, FogCardinalityError, FrameReceiptStaleError, GPU_TEXTURE_USAGE_COPY_DST, GPU_TEXTURE_USAGE_COPY_SRC, GPU_TEXTURE_USAGE_RENDER_ATTACHMENT, GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING, GPU_TEXTURE_USAGE_TEXTURE_BINDING, LifecycleConstructionError, MaterialSkinAttrMissingError, ObservationUnavailableError, OwnerStageFailedError, PointShadowAtlasBoundsViolationError, PointShadowAtlasUninitializedError, PointsLinesBudgetExceededError, PointsLinesInvalidStyleError, PointsLinesMaterialUnsupportedError, PointsLinesPrepareFailedError, PointsLinesStyleUnsupportedError, PointsLinesTopologyMismatchError, RENDER_PHASE_CATALOG, RenderFeatureCapabilityMissingError, RenderFeatureDrawRecordingFailedError, RenderFeaturePreparationFailedError, RenderFeaturePreparedStateMismatchError, RenderFeatureRegistrationConflictError, RenderFeatureStageFailedError, RenderIntentInvalidError, RenderTargetCapabilityMissingError, RenderTargetDescriptorInvalidError, RenderTargetOperationFailedError, RenderTargetStateInvalidError, RendererContractFailureError, RendererOperationError, SHADOW_ATLAS_DEFAULT_FACE_SIZE, SHADOW_ATLAS_DEFAULT_LAYERS, STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, SceneDataUnavailableError, ShadowAtlas, ShadowInvalidConfigError, SkinMaterialMismatchError, SkinPaletteOverflowError, StandardClusterIndexOverflowError, StandardClusterTransportUnavailableError, StandardLightBudgetExceededError, StandardProfileInvalidError, TaaCapsInsufficientError, TemporalFrameSubmitError, TransmissionCapabilityMissingError, VertexColorVariantConflictError, VideoUploadUnsupportedError, VolumeDensityShapeMismatchError, VolumeInvalidBoundsError, VolumeInvalidParametersError, VolumeOwnerConflictError, createLightResourceUnavailable };
+//# sourceMappingURL=chunk-QODA5UKU.mjs.map
+//# sourceMappingURL=chunk-QODA5UKU.mjs.map