@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/dist/errors/render.d.ts

@@ -0,0 +1,705 @@
+import type { DeviceResourceKind, DeviceScopeReceipt } from '../device/resource-types';
+import type { PreparedKind, RenderFeatureCapabilityKey, RenderFeatureRecovery, RenderFeatureStage } from '../features/vocabulary';
+export interface LifecycleConstructionFailureDetail {
+    readonly owner: string;
+    readonly generation: number;
+    readonly operation: 'create' | 'dispose';
+    readonly resourceKind: DeviceResourceKind;
+    readonly cause: unknown;
+    readonly cleanupFailures: readonly {
+        readonly resourceKind: DeviceResourceKind;
+        readonly cause: unknown;
+    }[];
+    readonly receipt: DeviceScopeReceipt;
+}
+export declare class LifecycleConstructionError extends Error {
+    readonly code: "lifecycle-construction-failed";
+    readonly expected = "all DeviceScope resources establish and terminate in order";
+    readonly hint = "inspect detail and cleanupFailures, then recover or rebuild the DeviceScope";
+    readonly detail: LifecycleConstructionFailureDetail;
+    constructor(detail: LifecycleConstructionFailureDetail);
+}
+/**
+ * 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).
+ */
+export interface ShadowInvalidConfigDetail {
+    readonly field: string;
+    readonly value: number;
+    readonly min: number;
+    readonly max?: number;
+}
+/**
+ * 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:
+ *   - `.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).
+ */
+export declare class ShadowInvalidConfigError extends Error {
+    readonly code: "shadow-invalid-config";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: ShadowInvalidConfigDetail;
+    constructor(field: string, value: number, min: number, maxOrComparator?: number | '>' | '>=');
+}
+/**
+ * Detail for `RuntimeErrorCode 'equirect-projection-failed'`.
+ *
+ * Emitted when the equirect-to-cubemap IBL projection fails for the equirect
+ * handle referenced by a `Skylight` / `SkyboxBackground` component. The handle
+ * id is carried so AI users can trace which equirect source failed projection.
+ * Degradation: the record arm records `status:'failed'`, binds the white-cube
+ * fallback, fires this error ONCE, and does NOT retry the projection.
+ *
+ * feat-20260630 D-5: structured error with detail carrying the handle id.
+ */
+export interface EquirectProjectionFailedDetail {
+    readonly handle: number;
+}
+/**
+ * Structured error for a failed equirect-to-cubemap IBL projection.
+ *
+ * Emitted by the record stage when the internal cubemap projection for an
+ * equirect handle returns a failure (or records `status:'failed'`). Four-field
+ * surface per AGENTS.md error model:
+ *   - `.code = 'equirect-projection-failed'` (closed RuntimeErrorCode)
+ *   - `.expected` — equirect-to-cubemap projection + IBL precompute succeeds
+ *   - `.hint` — declare `Skylight{equirect}` with a valid HDR equirect source;
+ *     check `device.caps.rgba16floatRenderable`. The projection is internal —
+ *     there is no user upload call to retry
+ *   - `.detail = { handle }` — the numeric equirect handle id for diagnostics
+ */
+export declare class EquirectProjectionFailedError extends Error {
+    readonly code: "equirect-projection-failed";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: EquirectProjectionFailedDetail;
+    constructor(handle: number);
+}
+/**
+ * Detail for `RuntimeErrorCode 'hdrp-light-budget-exceeded'`.
+ *
+ * Emitted per-frame (once-per-frame fire) when light count exceeds HDRP budget.
+ */
+export interface HdrpLightBudgetExceededDetail {
+    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 }`
+ */
+export declare class HdrpLightBudgetExceededError extends Error {
+    readonly code: "hdrp-light-budget-exceeded";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: HdrpLightBudgetExceededDetail;
+    constructor(actual: number, budget: number);
+}
+/**
+ * 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 {
+    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 }`
+ */
+export declare class HdrpIndexListOverflowError extends Error {
+    readonly code: "hdrp-index-list-overflow";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: HdrpIndexListOverflowDetail;
+    constructor(actual: number, capacity: number);
+}
+/**
+ * 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;
+}
+/**
+ * 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)
+ */
+export declare class HdrpDeferredCapsInsufficientError extends Error {
+    readonly code: "hdrp-deferred-caps-insufficient";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: HdrpDeferredCapsInsufficientDetail;
+    constructor(actual: number);
+}
+/**
+ * Structured error for `ShadowAtlas.faceView` called before `ensure()`
+ * allocated the cube_array texture. Replaces the prior bare
+ * `throw new Error()` (Round-2 F-4: P3 closed-union compliance).
+ *
+ *   - `.code = 'point-shadow-atlas-uninitialized'`
+ *   - `.expected` — call `ensure()` before iterating face views
+ *   - `.hint` — gate `faceView` on `isAllocated()` or call `ensure()` once
+ *     in the per-frame extract step before recording the 6 x N caster passes
+ *   - `.detail = undefined` (no per-call data needed)
+ */
+export declare class PointShadowAtlasUninitializedError extends Error {
+    readonly code: "point-shadow-atlas-uninitialized";
+    readonly expected: string;
+    readonly hint: string;
+    constructor();
+}
+/**
+ * Detail for `RuntimeErrorCode 'point-shadow-atlas-bounds-violation'`.
+ *
+ * Emitted by `ShadowAtlas.faceView` when `layer` falls outside `[0, layers)`
+ * or `face` falls outside `[0, 6)`. Both axes are reported as
+ * `{ axis, value, max }` so AI users discriminate without parsing the message.
+ */
+export interface PointShadowAtlasBoundsViolationDetail {
+    readonly axis: 'layer' | 'face';
+    readonly value: number;
+    readonly max: number;
+}
+/**
+ * Structured error for `ShadowAtlas.faceView(layer, face)` arguments outside
+ * the allocated atlas range. Replaces the prior bare `throw new Error()`
+ * (Round-2 F-4: P3 closed-union compliance).
+ *
+ *   - `.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)
+ *   - `.detail = { axis, value, max }` — discriminates layer vs face
+ */
+export declare class PointShadowAtlasBoundsViolationError extends Error {
+    readonly code: "point-shadow-atlas-bounds-violation";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: PointShadowAtlasBoundsViolationDetail;
+    constructor(axis: 'layer' | 'face', value: number, max: number);
+}
+/**
+ * Structured error for `RuntimeErrorCode 'video-upload-unsupported'`
+ * (feat-20260623-world-space-video-asset M3 / w11 — AC-10).
+ *
+ * Fired by the per-frame record stage (`videoTextureView`) when a VideoPlayer
+ * entity can reach neither video upload path this frame: the general
+ * `copyExternalImageToTexture` path (no host HTMLVideoElement resolved via
+ * `VideoElementProvider`) AND the high-perf `GPUExternalTexture` path
+ * (capability absent). The engine surfaces this explicit failure rather than
+ * silently rendering a stale/garbage texture (charter P3, plan-strategy D-6).
+ *   - `.code = 'video-upload-unsupported'`
+ *   - `.expected` — at least one upload path available (host element or
+ *     GPUExternalTexture capability)
+ *   - `.hint` — actionable recovery: use a static texture or switch backend
+ *   - `.detail` — undefined (no narrowed detail variant)
+ */
+export declare class VideoUploadUnsupportedError extends Error {
+    readonly code: "video-upload-unsupported";
+    readonly expected: string;
+    readonly hint: string;
+    constructor();
+}
+/**
+ * Structured error for missing vertex-stage storage buffer capability.
+ *
+ * Emitted at createRenderer time (cap-gate).
+ *   - `.code = 'vertex-storage-buffer-unavailable'`
+ *   - `.expected` — device.caps supports vertex-stage storage buffer
+ *   - `.hint` — switch to a WebGPU adapter with vertex storage buffer support or use uniform-buffer fallback (OOS-uniform-palette)
+ *   - `.detail` — undefined (no narrowed detail variant)
+ */
+export declare class VertexStorageBufferUnavailableError extends Error {
+    readonly code: "vertex-storage-buffer-unavailable";
+    readonly expected: string;
+    readonly hint: string;
+    constructor();
+}
+export interface VertexColorVariantConflictDetail {
+    readonly authored: true;
+    readonly authoredValue: string;
+    readonly projected: boolean;
+}
+/** The authored color axis disagrees with the canonical geometry projection. */
+export declare class VertexColorVariantConflictError extends Error {
+    readonly code: "vertex-color-variant-conflict";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: VertexColorVariantConflictDetail;
+    constructor(authoredValue: string, projected: boolean);
+}
+/** Detail for a palette buffer that exceeds the device storage limit. */
+export interface SkinPaletteOverflowDetail {
+    readonly requestedBytes: number;
+    readonly limit: number;
+}
+/**
+ * Structured render error for a skin palette allocation that exceeds the
+ * device storage-buffer binding limit. The allocator that emits this error
+ * lives in render, so the error belongs to the render union rather than the
+ * renderer-independent skinning binding package.
+ */
+export declare class SkinPaletteOverflowError extends Error {
+    readonly code: "skin-palette-overflow";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SkinPaletteOverflowDetail;
+    constructor(requestedBytes: number, limit: number);
+}
+/** Detail for a skinned entity using a non-skin material shader. */
+export interface SkinMaterialMismatchDetail {
+    readonly entity: number;
+    readonly actualShader: string | undefined;
+}
+/** Structured render error for a Skin/non-skin-material mismatch. */
+export declare class SkinMaterialMismatchError extends Error {
+    readonly code: "skin-material-mismatch";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SkinMaterialMismatchDetail;
+    constructor(entity: number, actualShader: string | undefined);
+}
+/** Detail for a pbr-skin material whose mesh lacks skin attributes. */
+export interface MaterialSkinAttrMissingDetail {
+    readonly entity: number;
+    readonly missing: 'skinIndex' | 'skinWeight' | 'both';
+}
+/** Structured render error for a pbr-skin material/mesh attribute mismatch. */
+export declare class MaterialSkinAttrMissingError extends Error {
+    readonly code: "material-skin-attr-missing";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: MaterialSkinAttrMissingDetail;
+    constructor(entity: number, missing: 'skinIndex' | 'skinWeight' | 'both');
+}
+export type RenderFeatureErrorCode = 'render-feature-registration-conflict' | 'render-feature-stage-failed' | 'render-feature-capability-missing' | 'render-feature-pass-order-conflict' | 'render-feature-preparation-failed' | 'render-feature-prepared-state-mismatch' | 'render-feature-draw-recording-failed';
+export interface RenderFeatureRegistrationConflictDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly conflictingOrder: number;
+}
+export interface RenderFeatureCleanupFailure {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly code: string;
+}
+export interface RenderFeatureStageFailedDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: RenderFeatureStage;
+    readonly recovery: RenderFeatureRecovery;
+    readonly cleanupFailures?: readonly RenderFeatureCleanupFailure[];
+}
+export interface RenderFeatureCapabilityMissingDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly capability: RenderFeatureCapabilityKey;
+}
+export interface RenderFeaturePassOrderConflictDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly passIdentity: string;
+    readonly dependencyIdentity: string;
+}
+export interface RenderFeaturePreparationFailedDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'prepare';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly resourceName: string;
+    readonly reason: string;
+    readonly recovery: RenderFeatureRecovery;
+}
+export type RenderFeaturePreparedStateMismatchDetail = {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'missing-prepared-state';
+    readonly missingResource: string;
+    readonly recovery: RenderFeatureRecovery;
+} | {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'foreign-feature';
+    readonly expectedFeatureIdentity: string;
+    readonly actualFeatureIdentity: string;
+    readonly recovery: RenderFeatureRecovery;
+} | {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'foreign-kind';
+    readonly expectedKind: PreparedKind;
+    readonly actualKind: PreparedKind;
+    readonly recovery: RenderFeatureRecovery;
+} | {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'generation-mismatch';
+    readonly expectedGeneration: number;
+    readonly actualGeneration: number;
+    readonly recovery: RenderFeatureRecovery;
+} | {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'layout-mismatch';
+    readonly expectedLayout: string;
+    readonly actualLayout: string;
+    readonly recovery: RenderFeatureRecovery;
+} | {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'contribute';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: 'format-mismatch';
+    readonly expectedFormat: string;
+    readonly actualFormat: string;
+    readonly recovery: RenderFeatureRecovery;
+};
+export interface RenderFeatureDrawRecordingFailedDetail {
+    readonly featureIdentity: string;
+    readonly order: number;
+    readonly stage: 'record';
+    readonly operation: string;
+    readonly resourceKind: PreparedKind;
+    readonly reason: string;
+    readonly backendReason: string;
+    readonly recovery: RenderFeatureRecovery;
+}
+export type RenderFeatureErrorDetailByCode = {
+    'render-feature-registration-conflict': RenderFeatureRegistrationConflictDetail;
+    'render-feature-stage-failed': RenderFeatureStageFailedDetail;
+    'render-feature-capability-missing': RenderFeatureCapabilityMissingDetail;
+    'render-feature-pass-order-conflict': RenderFeaturePassOrderConflictDetail;
+    'render-feature-preparation-failed': RenderFeaturePreparationFailedDetail;
+    'render-feature-prepared-state-mismatch': RenderFeaturePreparedStateMismatchDetail;
+    'render-feature-draw-recording-failed': RenderFeatureDrawRecordingFailedDetail;
+};
+/** Machine-readable four-field diagnostic exposed by every feature error. */
+export type RenderFeatureErrorDescriptor = {
+    [Code in RenderFeatureErrorCode]: {
+        readonly code: Code;
+        readonly expected: string;
+        readonly hint: string;
+        readonly detail: RenderFeatureErrorDetailByCode[Code];
+    };
+}[RenderFeatureErrorCode];
+export declare class RenderFeatureRegistrationConflictError extends Error {
+    readonly code: "render-feature-registration-conflict";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderFeatureRegistrationConflictDetail;
+    constructor(featureIdentity: string, order: number, conflictingOrder: number);
+}
+export declare class RenderFeatureStageFailedError extends Error {
+    readonly code: "render-feature-stage-failed";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderFeatureStageFailedDetail;
+    constructor(featureIdentity: string, order: number, stage: RenderFeatureStage, recovery: RenderFeatureRecovery);
+}
+export declare class RenderFeatureCapabilityMissingError extends Error {
+    readonly code: "render-feature-capability-missing";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderFeatureCapabilityMissingDetail;
+    constructor(featureIdentity: string, order: number, capability: RenderFeatureCapabilityMissingDetail['capability']);
+}
+export declare class RenderFeaturePassOrderConflictError extends Error {
+    readonly code: "render-feature-pass-order-conflict";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderFeaturePassOrderConflictDetail;
+    constructor(featureIdentity: string, order: number, passIdentity: string, dependencyIdentity: string);
+}
+export declare class RenderFeaturePreparationFailedError extends Error {
+    readonly code: "render-feature-preparation-failed";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderFeaturePreparationFailedDetail;
+    constructor(featureIdentity: string, order: number, operation: string, resourceKind: RenderFeaturePreparationFailedDetail['resourceKind'], resourceName: string, reason: string, recovery: RenderFeatureRecovery);
+}
+export declare class RenderFeaturePreparedStateMismatchError extends Error {
+    readonly code: "render-feature-prepared-state-mismatch";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderFeaturePreparedStateMismatchDetail;
+    constructor(detail: RenderFeaturePreparedStateMismatchDetail);
+}
+export declare class RenderFeatureDrawRecordingFailedError extends Error {
+    readonly code: "render-feature-draw-recording-failed";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderFeatureDrawRecordingFailedDetail;
+    constructor(featureIdentity: string, order: number, operation: string, resourceKind: RenderFeatureDrawRecordingFailedDetail['resourceKind'], reason: string, backendReason: string, recovery: RenderFeatureRecovery);
+}
+export type ObservationUnavailableReason = 'no-frame' | 'resource' | 'copy-src' | 'stale' | 'identity' | 'format' | 'readback-failed';
+export interface ObservationUnavailableDetail {
+    readonly reason: ObservationUnavailableReason;
+    readonly recovery: 'draw-current-frame' | 'enable-copy-src' | 'retry-readback';
+}
+/** A producer-owned current-frame observation could not be made available. */
+export declare class ObservationUnavailableError extends Error {
+    readonly code: "observation-unavailable";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: ObservationUnavailableDetail;
+    constructor(reason: ObservationUnavailableReason, hint: string);
+}
+export interface FrameReceiptStaleDetail {
+    readonly frameId: number;
+    readonly receiptGeneration: number;
+    readonly currentGeneration: number;
+}
+/** Receipt-bound observation failed closed at a generation fence. */
+export declare class FrameReceiptStaleError extends Error {
+    readonly code: "frame-receipt-stale";
+    readonly expected = "the observation receipt belongs to the active device generation";
+    readonly hint = "draw a new frame and call observe with its returned FrameReceipt";
+    readonly detail: FrameReceiptStaleDetail;
+    constructor(detail: FrameReceiptStaleDetail);
+}
+export interface RendererContractFailureDetail {
+    readonly operation: 'construct' | 'attach' | 'draw' | 'observe';
+    readonly cause: string;
+}
+/** Structured boundary failure while adapting an owner contract. */
+export declare class RendererContractFailureError extends Error {
+    readonly code: "renderer-contract-failed";
+    readonly expected = "renderer owner contracts remain valid at the public boundary";
+    readonly hint = "repair the owner contract and retry the operation";
+    readonly detail: RendererContractFailureDetail;
+    constructor(operation: RendererContractFailureDetail['operation'], cause: string);
+}
+export interface RendererOperationCause {
+    readonly code: string;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail?: unknown;
+}
+export interface RendererOperationDetailByCode {
+    readonly 'world-lease-invalid': {
+        readonly operation: 'attach' | 'draw';
+        readonly cause: RendererOperationCause;
+    };
+    readonly 'frame-input-invalid': {
+        readonly operation: 'draw' | 'set-profile';
+        readonly cause: RendererOperationCause;
+    };
+    readonly 'scene-projection-failed': {
+        readonly operation: 'draw';
+        readonly cause: RendererOperationCause;
+    };
+    readonly 'asset-binding-failed': {
+        readonly operation: 'draw';
+        readonly cause: RendererOperationCause;
+    };
+    readonly 'feature-plan-failed': {
+        readonly operation: 'draw';
+        readonly cause: RendererOperationCause;
+    };
+    readonly 'graph-build-failed': {
+        readonly operation: 'draw' | 'set-profile';
+        readonly cause: RendererOperationCause;
+    };
+    readonly 'device-operation-failed': {
+        readonly operation: 'draw' | 'complete-frame' | 'renderer-event';
+        readonly frameId?: number;
+        readonly deviceGeneration?: number;
+        readonly cause: RendererOperationCause;
+    };
+    readonly 'surface-unavailable': {
+        readonly operation: 'release-surface' | 'restore-surface';
+        readonly cause: RendererOperationCause;
+    };
+    readonly 'renderer-state-invalid': {
+        readonly operation: 'draw' | 'set-profile' | 'recover' | 'dispose';
+        readonly state: string;
+        readonly cause?: RendererOperationCause;
+    };
+    readonly 'recovery-failed': {
+        readonly operation: 'recover';
+        readonly oldGeneration: number;
+        readonly cause: RendererOperationCause;
+    };
+    readonly 'cleanup-failed': {
+        readonly operation: 'dispose';
+        readonly causes: readonly RendererOperationCause[];
+    };
+}
+export type RendererOperationErrorCode = keyof RendererOperationDetailByCode;
+/** Public renderer-operation failure with a code-narrowed structured detail. */
+export declare class RendererOperationError<Code extends RendererOperationErrorCode> extends Error {
+    readonly code: Code;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RendererOperationDetailByCode[Code];
+    constructor(code: Code, detail: RendererOperationDetailByCode[Code]);
+}
+export type RendererExpectedOperationError = {
+    readonly [Code in RendererOperationErrorCode]: RendererOperationError<Code>;
+}[RendererOperationErrorCode];
+export interface PointsLinesInvalidStyleDetail {
+    readonly entity: number;
+    readonly component: 'Points' | 'Lines' | 'Points/Lines';
+    readonly field: string;
+    readonly value: number | string | undefined;
+    readonly expected: string;
+}
+export declare class PointsLinesInvalidStyleError extends Error {
+    readonly code: "points-lines-invalid-style";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: PointsLinesInvalidStyleDetail;
+    constructor(detail: PointsLinesInvalidStyleDetail);
+}
+export interface PointsLinesTopologyMismatchDetail {
+    readonly entity: number;
+    readonly submesh: number;
+    readonly expected: string;
+    readonly actual: string;
+}
+export declare class PointsLinesTopologyMismatchError extends Error {
+    readonly code: "points-lines-topology-mismatch";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: PointsLinesTopologyMismatchDetail;
+    constructor(detail: PointsLinesTopologyMismatchDetail);
+}
+export interface PointsLinesStyleUnsupportedDetail {
+    readonly lane: string;
+    readonly field: string;
+    readonly member: string;
+    readonly supported: readonly string[];
+}
+export declare class PointsLinesStyleUnsupportedError extends Error {
+    readonly code: "points-lines-style-unsupported";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: PointsLinesStyleUnsupportedDetail;
+    constructor(detail: PointsLinesStyleUnsupportedDetail);
+}
+export interface PointsLinesMaterialUnsupportedDetail {
+    readonly entity: number;
+    readonly material: string;
+    readonly pass: string;
+    readonly module: string;
+    readonly reason: string;
+}
+export declare class PointsLinesMaterialUnsupportedError extends Error {
+    readonly code: "points-lines-material-unsupported";
+    readonly expected = "one engine-owned unlit forward MaterialAsset pass";
+    readonly hint: string;
+    readonly detail: PointsLinesMaterialUnsupportedDetail;
+    constructor(detail: PointsLinesMaterialUnsupportedDetail);
+}
+export interface PointsLinesBudgetExceededDetail {
+    readonly lane: string;
+    readonly requested: number;
+    readonly limit: number;
+    readonly unit: 'points' | 'segments' | 'vertices' | 'indices' | 'bytes' | 'draws';
+}
+export declare class PointsLinesBudgetExceededError extends Error {
+    readonly code: "points-lines-budget-exceeded";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: PointsLinesBudgetExceededDetail;
+    constructor(detail: PointsLinesBudgetExceededDetail);
+}
+export interface PointsLinesPrepareFailedDetail {
+    readonly owner: string;
+    readonly generation: number;
+    readonly stage: 'prepare';
+    readonly cause: string;
+    readonly lastKnownGood: boolean;
+}
+export declare class PointsLinesPrepareFailedError extends Error {
+    readonly code: "points-lines-prepare-failed";
+    readonly expected = "the complete Points/Lines candidate validates before publication";
+    readonly hint: string;
+    readonly detail: PointsLinesPrepareFailedDetail;
+    constructor(detail: PointsLinesPrepareFailedDetail);
+}
+/**
+ * Closed union of render-cluster error codes. AI users perform exhaustive
+ * `switch (err.code)` without default; TS guards completeness.
+ */
+export type RenderErrorCode = RenderError['code'];
+/**
+ * Closed union of the render-cluster structured error classes, each carrying a
+ * `RenderErrorCode` discriminant on `.code`.
+ */
+export type RenderError = LifecycleConstructionError | RendererExpectedOperationError | FrameReceiptStaleError | RendererContractFailureError | ObservationUnavailableError | ShadowInvalidConfigError | EquirectProjectionFailedError | HdrpLightBudgetExceededError | HdrpIndexListOverflowError | HdrpDeferredCapsInsufficientError | PointShadowAtlasUninitializedError | PointShadowAtlasBoundsViolationError | VideoUploadUnsupportedError | VertexStorageBufferUnavailableError | VertexColorVariantConflictError | SkinPaletteOverflowError | SkinMaterialMismatchError | MaterialSkinAttrMissingError | RenderFeatureRegistrationConflictError | RenderFeatureStageFailedError | RenderFeatureCapabilityMissingError | RenderFeaturePassOrderConflictError | RenderFeaturePreparationFailedError | RenderFeaturePreparedStateMismatchError | RenderFeatureDrawRecordingFailedError | PointsLinesInvalidStyleError | PointsLinesTopologyMismatchError | PointsLinesStyleUnsupportedError | PointsLinesMaterialUnsupportedError | PointsLinesBudgetExceededError | PointsLinesPrepareFailedError;
+//# sourceMappingURL=render.d.ts.map