@forgeax/engine-render 0.1.6 → 0.1.19

package/dist/chunk-LOSO4CTV.mjs

@@ -0,0 +1,901 @@
+import { err, ok } from '@forgeax/engine-types';
+
+// src/errors/render.ts
+var LifecycleConstructionError = class extends Error {
+  code = "lifecycle-construction-failed";
+  expected = "all DeviceScope resources establish and terminate in order";
+  hint = "inspect detail and cleanupFailures, then recover or rebuild the DeviceScope";
+  detail;
+  constructor(detail) {
+    super(`lifecycle-construction-failed: ${detail.resourceKind} lifecycle transaction failed`);
+    this.name = "LifecycleConstructionError";
+    this.detail = detail;
+  }
+};
+var ShadowInvalidConfigError = class extends Error {
+  code = "shadow-invalid-config";
+  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}`
+    );
+    this.name = "ShadowInvalidConfigError";
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { field, value, min, ...max !== void 0 ? { max } : {} };
+  }
+};
+var EquirectProjectionFailedError = class extends Error {
+  code = "equirect-projection-failed";
+  expected;
+  hint;
+  detail;
+  constructor(handle) {
+    const expected = `equirect handle ${handle} projects to a GPU cubemap + IBL precompute`;
+    const hint = `equirect handle ${handle} referenced by Skylight/SkyboxBackground failed projection; declare Skylight{equirect} with a valid HDR equirect source and check device.caps.rgba16floatRenderable. The projection is internal (no user upload call); the record arm does not retry`;
+    super(`equirect handle ${handle} cubemap projection failed`);
+    this.name = "EquirectProjectionFailedError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { handle };
+  }
+};
+var HdrpLightBudgetExceededError = class extends Error {
+  code = "hdrp-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";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { actual, budget };
+  }
+};
+var HdrpIndexListOverflowError = class extends Error {
+  code = "hdrp-index-list-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";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { actual, capacity };
+  }
+};
+var HdrpDeferredCapsInsufficientError = class extends Error {
+  code = "hdrp-deferred-caps-insufficient";
+  expected;
+  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;
+    this.hint = hint;
+    this.detail = { actual, expected: _expected };
+  }
+};
+var PointShadowAtlasUninitializedError = class extends Error {
+  code = "point-shadow-atlas-uninitialized";
+  expected;
+  hint;
+  constructor() {
+    const expected = "ShadowAtlas.ensure() invoked before faceView()";
+    const hint = "Gate faceView on isAllocated() or call ensure() once in the per-frame extract step before iterating face views";
+    super("ShadowAtlas.faceView called before ensure(); the cube_array texture is not allocated");
+    this.name = "PointShadowAtlasUninitializedError";
+    this.expected = expected;
+    this.hint = hint;
+  }
+};
+var PointShadowAtlasBoundsViolationError = class extends Error {
+  code = "point-shadow-atlas-bounds-violation";
+  expected;
+  hint;
+  detail;
+  constructor(axis, value, max) {
+    const expected = `0 <= ${axis} < ${max}`;
+    const hint = axis === "layer" ? `clamp PointLight.shadowAtlasLayer to [0, ${max}); the cap on layers equals PointLightShadow cardinality (4)` : `clamp face index to [0, ${max}); cube faces are indexed 0..5 in +X/-X/+Y/-Y/+Z/-Z order`;
+    super(`ShadowAtlas.faceView ${axis} out of range: ${value} (must be in [0, ${max}))`);
+    this.name = "PointShadowAtlasBoundsViolationError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { axis, value, max };
+  }
+};
+var VideoUploadUnsupportedError = class extends Error {
+  code = "video-upload-unsupported";
+  expected;
+  hint;
+  constructor() {
+    const expected = "at least one video upload path available: a host HTMLVideoElement (general copyExternalImageToTexture path) or GPUExternalTexture capability (high-perf path)";
+    const hint = "this backend exposes no usable video upload path; render a static texture instead, or switch to a WebGPU backend that supports video texture upload";
+    super("video upload unsupported \u2014 no general or high-perf path available");
+    this.name = "VideoUploadUnsupportedError";
+    this.expected = expected;
+    this.hint = hint;
+  }
+};
+var VertexColorVariantConflictError = class extends Error {
+  code = "vertex-color-variant-conflict";
+  expected;
+  hint;
+  detail;
+  constructor(authoredValue, projected) {
+    const expected = `VERTEX_COLOR_AVAILABLE=${projected ? "true" : "false"}`;
+    const hint = "derive the shader variant from the mesh VertexLayoutProjection; COLOR_0 presence is a geometry fact";
+    super(`authored vertex-color variant ${authoredValue} disagrees with projected ${expected}`);
+    this.name = "VertexColorVariantConflictError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { authored: true, authoredValue, projected };
+  }
+};
+var SkinPaletteOverflowError = class extends Error {
+  code = "skin-palette-overflow";
+  expected;
+  hint;
+  detail;
+  constructor(requestedBytes, limit) {
+    const expected = `skinned joint palette (${requestedBytes} B) fits within device.limits.maxStorageBufferBindingSize (${limit} B)`;
+    const hint = "palette buffer exceeds device maxStorageBufferBindingSize; reduce skinned entity count or split into multiple palette buffers (OOS-skin-palette-batch)";
+    super(`skin palette buffer needs ${requestedBytes} B, exceeds device limit ${limit} B`);
+    this.name = "SkinPaletteOverflowError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { requestedBytes, limit };
+  }
+};
+var SkinMaterialMismatchError = class extends Error {
+  code = "skin-material-mismatch";
+  expected;
+  hint;
+  detail;
+  constructor(entity, actualShader) {
+    const expected = "Skin entity's first material program module === 'forgeax::pbr-skin'";
+    const hint = `entity ${entity} has Skin but the first material program module is ${actualShader ?? "<empty>"}; load the mesh via the gltf importer (cooker auto-routes 'forgeax::pbr-skin' for skinned primitives), or remove the Skin component to render the entity unskinned with Materials.standard / Materials.unlit`;
+    super(
+      `Skin / material mismatch on entity ${entity}: expected forgeax::pbr-skin, got ${actualShader ?? "<empty>"}`
+    );
+    this.name = "SkinMaterialMismatchError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { entity, actualShader };
+  }
+};
+var MaterialSkinAttrMissingError = class extends Error {
+  code = "material-skin-attr-missing";
+  expected;
+  hint;
+  detail;
+  constructor(entity, missing) {
+    const expected = "pbr-skin material requires mesh.attributes.skinIndex + skinWeight";
+    const hint = `entity ${entity} uses forgeax::pbr-skin but its MeshAsset is missing ${missing}; switch the entity to a skinned glTF mesh authored with JOINTS_0 + WEIGHTS_0, or change the material to a non-skin shader via Materials.standard / Materials.unlit`;
+    super(
+      `material/skin attribute mismatch on entity ${entity}: pbr-skin material with mesh missing ${missing}`
+    );
+    this.name = "MaterialSkinAttrMissingError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { entity, missing };
+  }
+};
+var TransmissionCapabilityMissingError = class extends Error {
+  code = "transmission-capability-missing";
+  expected = "the renderer exposes the transmission capability for this material";
+  hint = "disable transmission or provide the renderer capability before drawing";
+  detail;
+  constructor(material, stage, evidence) {
+    super(`transmission capability is missing for material '${material}'`);
+    this.name = "TransmissionCapabilityMissingError";
+    this.detail = { material, capability: "transmission", stage, ...evidence };
+  }
+};
+var renderFeatureRecoveryHintByRecovery = {
+  "next-frame": (featureIdentity, stage) => `correct '${featureIdentity}' ${stage} data and retry on the next frame`,
+  "renderer-recover": (featureIdentity, _stage) => `wait for renderer recovery before retrying '${featureIdentity}'`,
+  registration: (featureIdentity, _stage) => `correct '${featureIdentity}' registration before retrying`
+};
+var RenderFeatureRegistrationConflictError = class extends Error {
+  code = "render-feature-registration-conflict";
+  expected;
+  hint;
+  detail;
+  constructor(featureIdentity, order, conflictingOrder) {
+    const expected = `feature identity '${featureIdentity}' is unique`;
+    const hint = `rename '${featureIdentity}' or remove the duplicate feature before registration`;
+    super(`render feature registration conflict for '${featureIdentity}'`);
+    this.name = "RenderFeatureRegistrationConflictError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { featureIdentity, order, conflictingOrder };
+  }
+};
+var RenderFeatureStageFailedError = class extends Error {
+  code = "render-feature-stage-failed";
+  expected;
+  hint;
+  detail;
+  constructor(featureIdentity, order, stage, recovery) {
+    const expected = `feature '${featureIdentity}' completes its ${stage} stage without an error`;
+    const hint = renderFeatureRecoveryHintByRecovery[recovery](featureIdentity, stage);
+    super(`render feature '${featureIdentity}' failed during ${stage}`);
+    this.name = "RenderFeatureStageFailedError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { featureIdentity, order, stage, recovery };
+  }
+};
+var RenderFeatureCapabilityMissingError = class extends Error {
+  code = "render-feature-capability-missing";
+  expected;
+  hint;
+  detail;
+  constructor(featureIdentity, order, capability) {
+    const expected = `device capability '${capability}' is available for feature '${featureIdentity}'`;
+    const hint = `disable '${featureIdentity}' or use a device with '${capability}' capability`;
+    super(`render feature '${featureIdentity}' requires missing capability '${capability}'`);
+    this.name = "RenderFeatureCapabilityMissingError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { featureIdentity, order, capability };
+  }
+};
+var RenderFeaturePreparationFailedError = class extends Error {
+  code = "render-feature-preparation-failed";
+  expected;
+  hint;
+  detail;
+  constructor(featureIdentity, order, operation, resourceKind, resourceName, reason, recovery) {
+    const expected = `${resourceKind} '${resourceName}' is prepared during ${operation}`;
+    const hint = `repair '${resourceName}' and retry feature '${featureIdentity}' on ${recovery}`;
+    super(`render feature '${featureIdentity}' preparation failed for '${resourceName}'`);
+    this.name = "RenderFeaturePreparationFailedError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = {
+      featureIdentity,
+      order,
+      stage: "prepare",
+      operation,
+      resourceKind,
+      resourceName,
+      reason,
+      recovery
+    };
+  }
+};
+var RenderFeaturePreparedStateMismatchError = class extends Error {
+  code = "render-feature-prepared-state-mismatch";
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    const expected = `${detail.resourceKind} state is compatible for '${detail.operation}'`;
+    const hint = `repair '${detail.reason}' for feature '${detail.featureIdentity}' and retry`;
+    super(`render feature '${detail.featureIdentity}' prepared state mismatch`);
+    this.name = "RenderFeaturePreparedStateMismatchError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+  }
+};
+var RenderFeatureDrawRecordingFailedError = class extends Error {
+  code = "render-feature-draw-recording-failed";
+  expected;
+  hint;
+  detail;
+  constructor(featureIdentity, order, operation, resourceKind, reason, backendReason, recovery) {
+    const expected = `${resourceKind} recording succeeds for '${operation}'`;
+    const hint = `repair '${reason}' and retry feature '${featureIdentity}' after ${recovery}`;
+    super(`render feature '${featureIdentity}' draw recording failed`);
+    this.name = "RenderFeatureDrawRecordingFailedError";
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = {
+      featureIdentity,
+      order,
+      stage: "record",
+      operation,
+      resourceKind,
+      reason,
+      backendReason,
+      recovery
+    };
+  }
+};
+var ObservationUnavailableError = class extends Error {
+  code = "observation-unavailable";
+  expected;
+  hint;
+  detail;
+  constructor(reason, hint) {
+    let recovery;
+    if (reason === "copy-src") recovery = "enable-copy-src";
+    else if (reason === "resource" || reason === "readback-failed") recovery = "retry-readback";
+    else recovery = "draw-current-frame";
+    super(`current-frame observation unavailable: ${reason}`);
+    this.name = "ObservationUnavailableError";
+    this.expected = "a fresh producer-owned rgba16float current-frame observation";
+    this.hint = hint;
+    this.detail = { reason, recovery };
+  }
+};
+var SceneDataUnavailableError = class extends Error {
+  code = "scene-data-unavailable";
+  expected = "the requested semantic scene data is available for the active plan";
+  hint;
+  detail;
+  constructor(detail) {
+    const hint = detail.recovery === "enable-capability" ? "enable rgba16floatRenderable and retry the current frame" : detail.recovery === "renderer-recover" ? "wait for renderer recovery, then retry the frame" : "restore the producer coverage and retry on the next frame";
+    super(`scene data '${detail.schema}' unavailable for '${detail.featureIdentity}'`);
+    this.name = "SceneDataUnavailableError";
+    this.hint = hint;
+    this.detail = Object.freeze({
+      ...detail,
+      missingContributorIds: Object.freeze([...detail.missingContributorIds].slice(0, 32)),
+      omittedMissingContributorCount: Math.max(
+        detail.omittedMissingContributorCount,
+        Math.max(0, detail.missingContributorIds.length - 32)
+      )
+    });
+  }
+};
+var FrameReceiptStaleError = class extends Error {
+  code = "frame-receipt-stale";
+  expected = "the observation receipt belongs to the active device generation";
+  hint = "draw a new frame and call observe with its returned FrameReceipt";
+  detail;
+  constructor(detail) {
+    super("frame receipt belongs to a retired device generation");
+    this.name = "FrameReceiptStaleError";
+    this.detail = detail;
+  }
+};
+var RendererContractFailureError = class extends Error {
+  code = "renderer-contract-failed";
+  expected = "renderer owner contracts remain valid at the public boundary";
+  hint = "repair the owner contract and retry the operation";
+  detail;
+  constructor(operation, cause) {
+    super(`renderer ${operation} contract failed: ${cause}`);
+    this.name = "RendererContractFailureError";
+    this.detail = { operation, cause };
+  }
+};
+var EnvironmentSourceConflictError = class extends Error {
+  code = "environment-source-conflict";
+  expected = "exactly one environment source owns the frame";
+  hint = "remove all but one image or atmosphere environment owner";
+  detail;
+  constructor(owners) {
+    super("environment source owners conflict");
+    this.name = "EnvironmentSourceConflictError";
+    this.detail = { owners: owners.map((owner) => Object.freeze({ ...owner })) };
+  }
+};
+var FogCardinalityError = class extends Error {
+  code = "fog-cardinality";
+  expected = "zero or one Fog owner contributes to a frame";
+  hint = "remove extra Fog owners so the resource owner has at most one";
+  detail;
+  constructor(count) {
+    super(`Fog owner cardinality is ${count}`);
+    this.name = "FogCardinalityError";
+    this.detail = { count };
+  }
+};
+var TaaCapsInsufficientError = class extends Error {
+  code = "taa-caps-insufficient";
+  expected = "the backend exposes the capabilities required by TAA";
+  hint = "select a backend with the required TAA capabilities or disable TAA on Camera";
+  detail;
+  constructor(required, available) {
+    super("TAA capabilities are insufficient");
+    this.name = "TaaCapsInsufficientError";
+    this.detail = { required: [...required], available: [...available] };
+  }
+};
+var EnvironmentGenerationFailedError = class extends Error {
+  code = "environment-generation-failed";
+  expected = "the selected environment generation completes its owner stage";
+  hint = "inspect the stage and sourceKey, then retry after correcting the environment";
+  detail;
+  constructor(sourceKey, stage) {
+    super(`environment generation failed during ${stage}`);
+    this.name = "EnvironmentGenerationFailedError";
+    this.detail = { sourceKey, stage };
+  }
+};
+var AtmosphereInvalidParameterError = class extends Error {
+  code = "atmosphere-invalid-parameter";
+  expected;
+  hint;
+  detail;
+  constructor(field, value, range) {
+    super(`Atmosphere.${field} is invalid`);
+    this.name = "AtmosphereInvalidParameterError";
+    this.detail = { field, value };
+    const rangeText = Number.isFinite(range.max) ? `[${range.min}, ${range.max}]` : `>= ${range.min}`;
+    this.expected = `Atmosphere.${field} must be finite and ${rangeText}`;
+    this.hint = `set Atmosphere.${field} to a finite value ${rangeText}`;
+  }
+};
+var OwnerStageFailedError = class extends Error {
+  code = "owner-stage-failed";
+  expected = "the owner completes its current frame stage";
+  hint = "inspect the owner and stage, keep the last-known-good frame, and retry";
+  detail;
+  constructor(owner, stage) {
+    super(`${owner} owner failed during ${stage}`);
+    this.name = "OwnerStageFailedError";
+    this.detail = { owner, stage };
+  }
+};
+var RENDERER_OPERATION_ERROR_POLICY = {
+  "world-lease-invalid": {
+    expected: "every render World is represented by a live lease owned by this Renderer",
+    hint: "attach the World to this Renderer and use the returned lease"
+  },
+  "frame-input-invalid": {
+    expected: "the frame input references attached leases and a valid immutable RenderProfile",
+    hint: "repair the frame input and retry draw or setProfile"
+  },
+  "scene-projection-failed": {
+    expected: "the attached World projects into the renderer-owned RenderScene",
+    hint: "inspect the structured cause, repair the World publication, and retry draw"
+  },
+  "asset-binding-failed": {
+    expected: "all frame assets resolve to valid renderer-owned bindings",
+    hint: "inspect the structured cause, rebuild or cold-cook the asset, and retry draw"
+  },
+  "feature-plan-failed": {
+    expected: "every installed RenderFeature produces a valid declarative plan",
+    hint: "inspect the feature cause, repair its plan, and retry draw"
+  },
+  "graph-build-failed": {
+    expected: "the Standard graph builds from the active profile and feature plans",
+    hint: "inspect the graph cause, repair the profile or plan, and retry"
+  },
+  "device-operation-failed": {
+    expected: "the active device generation completes the renderer-owned operation",
+    hint: "inspect renderer state and the structured cause, then retry or recover"
+  },
+  "surface-unavailable": {
+    expected: "the presentation surface accepts the requested lifecycle operation",
+    hint: "inspect renderer state, then restore the surface or create a new Renderer"
+  },
+  "renderer-state-invalid": {
+    expected: "the Renderer is in a state that accepts the requested operation",
+    hint: "inspect renderer state and choose retry, restoreSurface, recover, or stop"
+  },
+  "recovery-failed": {
+    expected: "one recovery attempt publishes a complete replacement device generation",
+    hint: "inspect the structured cause and retry recover after the host-selected delay"
+  },
+  "cleanup-failed": {
+    expected: "Renderer disposal completes every registered cleanup in reverse ownership order",
+    hint: "inspect the ordered cleanup causes; the Renderer remains disposed and must not be reused"
+  }
+};
+var RendererOperationError = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(code, detail) {
+    const policy = RENDERER_OPERATION_ERROR_POLICY[code];
+    super(`${code}: ${policy.expected}`);
+    this.name = "RendererOperationError";
+    this.code = code;
+    this.expected = policy.expected;
+    this.hint = policy.hint;
+    this.detail = detail;
+  }
+};
+var PointsLinesInvalidStyleError = class extends Error {
+  code = "points-lines-invalid-style";
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    super(`invalid ${detail.component} style at ${detail.field}`);
+    this.name = "PointsLinesInvalidStyleError";
+    this.expected = detail.expected;
+    this.hint = `repair entity ${detail.entity} ${detail.component}.${detail.field} and retry admission`;
+    this.detail = detail;
+  }
+};
+var PointsLinesTopologyMismatchError = class extends Error {
+  code = "points-lines-topology-mismatch";
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    super(`Points/Lines topology mismatch at submesh ${detail.submesh}`);
+    this.name = "PointsLinesTopologyMismatchError";
+    this.expected = `submesh ${detail.submesh} topology is ${detail.expected}`;
+    this.hint = `rebuild entity ${detail.entity} with ${detail.expected} geometry before retrying Points/Lines admission`;
+    this.detail = detail;
+  }
+};
+var PointsLinesStyleUnsupportedError = class extends Error {
+  code = "points-lines-style-unsupported";
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    super(`unsupported Points/Lines ${detail.field} member ${detail.member}`);
+    this.name = "PointsLinesStyleUnsupportedError";
+    this.expected = `${detail.field} is one of ${detail.supported.join(", ")}`;
+    this.hint = `use a supported Points/Lines ${detail.field} member or wait for a later milestone`;
+    this.detail = detail;
+  }
+};
+var PointsLinesMaterialUnsupportedError = class extends Error {
+  code = "points-lines-material-unsupported";
+  expected = "one engine-owned unlit forward MaterialAsset pass";
+  hint;
+  detail;
+  constructor(detail) {
+    super(`Points/Lines material is unsupported on entity ${detail.entity}`);
+    this.name = "PointsLinesMaterialUnsupportedError";
+    this.hint = `use Materials.unlit without a shadow-caster pass for entity ${detail.entity}`;
+    this.detail = detail;
+  }
+};
+var PointsLinesBudgetExceededError = class extends Error {
+  code = "points-lines-budget-exceeded";
+  expected;
+  hint;
+  detail;
+  constructor(detail) {
+    super(`Points/Lines ${detail.unit} budget exceeded`);
+    this.name = "PointsLinesBudgetExceededError";
+    this.expected = `${detail.unit} <= ${detail.limit}`;
+    this.hint = `reduce Points/Lines ${detail.unit} or split the entity into bounded equivalent batches`;
+    this.detail = detail;
+  }
+};
+var PointsLinesPrepareFailedError = class extends Error {
+  code = "points-lines-prepare-failed";
+  expected = "the complete Points/Lines candidate validates before publication";
+  hint;
+  detail;
+  constructor(detail) {
+    super(`Points/Lines prepare failed at generation ${detail.generation}`);
+    this.name = "PointsLinesPrepareFailedError";
+    this.hint = detail.lastKnownGood ? "retain the last known good candidate, repair the producer, and retry prepare" : "repair the producer and retry prepare; the failed first candidate produces zero draw";
+    this.detail = detail;
+  }
+};
+
+// 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/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,
+  fallback: "native",
+  postStages: STANDARD_POST_STAGE_NAMES
+});
+function resolveStandardLane(profile, capabilities) {
+  if (!capabilities.compute || !capabilities.storageBuffer) return "cpu-webgl2";
+  return profile.lighting;
+}
+
+// src/render-contract.ts
+var STANDARD_OUTPUT_TRANSFORM_FEATURE_ID = "forgeax::standard::output-transform";
+var RENDER_GRAPH_EXECUTION_PHASE_CATALOG = [
+  "record/graph-execute/point-shadow",
+  "record/graph-execute/cluster-binner-upload",
+  "record/graph-execute/g-buffer",
+  "record/graph-execute/g-buffer/geometry-loop",
+  "record/graph-execute/g-buffer/material-bind-groups",
+  "record/graph-execute/g-buffer/pipeline-selection",
+  "record/graph-execute/g-buffer/draw-submit",
+  "record/graph-execute/ssao-calc",
+  "record/graph-execute/ssao-blur",
+  "record/graph-execute/lighting",
+  "record/graph-execute/forward",
+  "record/graph-execute/forward/geometry-loop",
+  "record/graph-execute/forward/material-bind-groups",
+  "record/graph-execute/forward/pipeline-selection",
+  "record/graph-execute/forward/draw-submit",
+  "record/graph-execute/output-transform",
+  "record/graph-execute/present",
+  "record/graph-execute/debug-overlay",
+  "record/graph-execute/shadow",
+  "record/graph-execute/spot-shadow",
+  "record/graph-execute/skybox",
+  "record/graph-execute/main",
+  "record/graph-execute/fxaa",
+  "record/graph-execute/bloom-bright",
+  "record/graph-execute/bloom-blur-h",
+  "record/graph-execute/bloom-blur-v",
+  "record/graph-execute/bloom-composite",
+  "record/graph-execute/other"
+];
+var RENDER_HDRP_BINNER_PHASE_CATALOG = [
+  "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy",
+  "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/light-aabb",
+  "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/cluster-occupancy",
+  "record/scene-state/hdrp-cluster/binner/cluster-reserve",
+  "record/scene-state/hdrp-cluster/binner/input-preparation",
+  "record/scene-state/hdrp-cluster/binner/bin-core",
+  "record/scene-state/hdrp-cluster/binner/light-index-write",
+  "record/scene-state/hdrp-cluster/binner/light-index-write/bounds-read",
+  "record/scene-state/hdrp-cluster/binner/light-index-write/cluster-write"
+];
+var RENDER_HDRP_CLUSTER_PHASE_CATALOG = [
+  "record/scene-state/hdrp-cluster/binner",
+  ...RENDER_HDRP_BINNER_PHASE_CATALOG,
+  "record/scene-state/hdrp-cluster/payload-packing",
+  "record/scene-state/hdrp-cluster/buffer-upload"
+];
+var RENDER_SCENE_STATE_PHASE_CATALOG = [
+  "record/scene-state/fold-buckets",
+  "record/scene-state/lighting-prep",
+  "record/scene-state/ambient-resolution",
+  "record/scene-state/directional-shadow-cache",
+  "record/scene-state/hdrp-cluster",
+  ...RENDER_HDRP_CLUSTER_PHASE_CATALOG
+];
+var RENDER_RECORD_PHASE_CATALOG = [
+  "record/scene-state",
+  ...RENDER_SCENE_STATE_PHASE_CATALOG,
+  "record/swapchain",
+  "record/render-graph",
+  "record/target-views",
+  "record/validation",
+  "record/dispatch-plan",
+  "record/uploads",
+  "record/bind-groups",
+  "record/graph-execute",
+  ...RENDER_GRAPH_EXECUTION_PHASE_CATALOG
+];
+var RENDER_PHASE_CATALOG = [
+  "extract",
+  "bind-groups",
+  "features",
+  "sort",
+  "record",
+  ...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, TransmissionCapabilityMissingError, VertexColorVariantConflictError, VideoUploadUnsupportedError, createSceneDataCatalog, isSceneDataTarget, registerSceneDataTarget, resolveStandardLane, sceneDataError, sceneDataTargetAsAttachment, sceneDataTargetOwner, sceneDataTokenMismatch };
+//# sourceMappingURL=chunk-LOSO4CTV.mjs.map
+//# sourceMappingURL=chunk-LOSO4CTV.mjs.map