@gentleduck/upload 0.2.6 → 0.3.0

package/dist/index-DCqyBVcx.d.ts

@@ -0,0 +1,1441 @@
+//#region src/core/contracts/contracts.types.d.ts
+/**
+ * Public contract types grouped under the `Contracts` namespace.
+ *
+ * Each sub-namespace owns one concern (Intent, Cursor, Result, Validation,
+ * Fingerprint, Errors, Strategy, BackendApi).
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare namespace Contracts {
+  namespace Intent {
+    /** Base shape for all upload intents. */
+    type Base<K extends string = string> = {
+      /** Strategy name (discriminant). */strategy: K; /** Unique backend file identifier. */
+      fileId: string;
+    };
+    /** Registry of intent types mapped by strategy name. */
+    type Map = Record<string, Base<string>>;
+    /** Union of strategy keys for an intent map. */
+    type StrategyKey<M extends Map> = keyof M & string;
+    /** Union of all intent variants for an intent map. */
+    type Any<M extends Map> = M[StrategyKey<M>];
+  }
+  namespace Cursor {
+    /** Registry of cursor payload types mapped by strategy name. */
+    type Map<M extends Intent.Map> = Partial<Record<Intent.StrategyKey<M>, unknown>>;
+    /** Discriminated union of all cursor variants. */
+    type Any<C extends Record<string, unknown>> = { [K in keyof C & string]: {
+      /** Strategy name associated with this cursor. */strategy: K; /** The custom strategy-defined state needed to resume the upload. */
+      value?: C[K] | undefined;
+    } }[keyof C & string];
+  }
+  namespace Result {
+    /** Successful upload payload returned by your backend API's complete endpoint. */
+    type Base = {
+      /** Unique backend file identifier. */fileId: string; /** Storage key/path or public address of the uploaded file. */
+      key: string;
+    };
+  }
+  namespace Validation {
+    /** Why a file was rejected during client-side validation. */
+    type Rejection = {
+      code: 'empty_file';
+    } | {
+      code: 'file_too_large';
+      maxBytes: number;
+      size: number;
+    } | {
+      code: 'type_not_allowed';
+      allowed: string[];
+      got: string;
+    } | {
+      code: 'too_many_files';
+      max: number;
+    } | {
+      code: 'mime_mismatch';
+      claimed: string;
+      sniffed: string;
+    } | {
+      code: 'filename_rejected';
+      reason: 'reserved' | 'too-long' | 'empty' | 'path-sep';
+    };
+  }
+  /** Deterministic identity signature of a file on the client. */
+  type FingerprintFile = {
+    /** Base name of the file (excluding directory path). */name: string; /** Size of the file in bytes. */
+    size: number; /** MIME type of the file. */
+    type: string; /** Timestamp when the file was last modified on disk (milliseconds since epoch). */
+    lastModified: number; /** Optional pre-computed checksum of the file (e.g. SHA-256 hex). */
+    checksum?: string | undefined;
+  };
+  namespace Errors {
+    /** Base schema for upload-related runtime errors. */
+    type Base = {
+      /** Stable machine-readable error classification. */code: string; /** Human-friendly message suitable for presentation in standard warning elements. */
+      message: string; /** Original thrown error or reason context if available. */
+      cause?: unknown; /** Flag specifying whether the error recovery system should schedule retries. */
+      retryable?: boolean;
+    };
+    /** Discriminant union of built-in engine failure structures. */
+    type BuiltIn = {
+      code: 'validation_failed';
+      message: string;
+      reason: Validation.Rejection;
+      retryable?: false;
+    } | {
+      code: 'strategy_missing';
+      message: string;
+      strategy: string;
+      retryable?: false;
+    } | {
+      code: 'aborted';
+      message: string;
+      reason: 'pause' | 'cancel' | 'unknown';
+      cause?: unknown;
+      retryable?: false;
+    } | {
+      code: 'network';
+      message: string;
+      cause?: unknown;
+      retryable?: boolean;
+    } | {
+      code: 'http';
+      message: string;
+      status: number;
+      statusText?: string;
+      cause?: unknown;
+      retryable?: boolean;
+    } | {
+      code: 'timeout';
+      message: string;
+      cause?: unknown;
+      retryable?: boolean;
+    } | {
+      code: 'auth';
+      message: string;
+      cause?: unknown;
+      retryable?: false;
+    } | {
+      code: 'rate_limit';
+      message: string;
+      retryAfterMs?: number;
+      cause?: unknown;
+      retryable?: boolean;
+    } | {
+      code: 'server';
+      message: string;
+      serverCode?: string;
+      cause?: unknown;
+      retryable?: boolean;
+    } | {
+      code: 'unknown';
+      message: string;
+      cause?: unknown;
+      retryable?: boolean;
+    };
+    /** The canonical error shape handled by the engine, plugins, and handlers. */
+    type Error = BuiltIn | (Base & Record<string, unknown>);
+  }
+  /** Validation rules applied to files on registration before intents are initiated. */
+  type ValidationRules = {
+    /** Maximum number of files permitted in a single upload batch. */maxFiles?: number; /** Maximum size in bytes allowed for a single file. */
+    maxSizeBytes?: number; /** Minimum size in bytes allowed for a single file. */
+    minSizeBytes?: number; /** White-list of allowed MIME types (e.g. `["image/png", "application/pdf"]`). */
+    allowedTypes?: string[]; /** White-list of allowed file extension strings (e.g. `["png", "pdf"]`). */
+    allowedExtensions?: string[];
+  };
+  /**
+   * Safe, cause-stripped error summary stored in step history and forwarded in API context.
+   * The raw `cause` field is omitted because it may contain sensitive server response bodies.
+   */
+  type StepError = {
+    code: string;
+    message: string;
+    retryable?: boolean;
+  };
+  /** A single recorded phase transition on an upload item. */
+  type UploadStep = {
+    /** Phase name when this step was entered. */phase: string; /** Epoch ms when this phase was entered. */
+    enteredAt: number; /** Epoch ms when this phase was left. Undefined while still in this phase. */
+    leftAt?: number; /** Attempt number at the time of entering this phase. */
+    attempt: number; /** Safe error summary if this phase ended in failure. Cause is stripped. */
+    error?: StepError | undefined;
+  };
+  namespace Api {
+    /** Context passed to every backend API method alongside the call-specific args. */
+    type Context<P extends string = string, M extends Intent.Map = Intent.Map> = {
+      /** Client-side identifier for this file item. */localId: string; /** Upload purpose. */
+      purpose: P; /** File identity: name, size, MIME type, checksum. Always present. */
+      fingerprint: FingerprintFile; /** Which attempt this is, starting at 1. Increments on retry. */
+      attempt: number; /** Epoch ms when this item was registered. */
+      createdAt: number; /** Phase history up to this call. Errors have cause stripped. */
+      steps: readonly UploadStep[]; /** Caller-supplied metadata from the addFiles command. Never persisted. */
+      meta: Record<string, unknown>; /** Safe error from the most recent failed step, if any. */
+      lastError?: StepError | undefined; /** Browser File object. Present in most phases; absent when file is not loaded. */
+      file?: File | undefined; /** Upload intent from the backend. Present after createIntent succeeds. */
+      intent?: Intent.Any<M> | undefined; /** Cancellation signal. */
+      signal?: AbortSignal | undefined;
+    };
+    /** Context for API calls where intent is not yet created but file is loaded (e.g. createIntent) */
+    type CreateIntentContext<P extends string, M extends Intent.Map> = Context<P, M> & Required<Pick<Context<P, M>, 'file' | 'signal'>>;
+    /** Context for API calls verifying file checksum (e.g. findByChecksum) */
+    type FindByChecksumContext<P extends string, M extends Intent.Map> = Context<P, M> & Required<Pick<Context<P, M>, 'file'>>;
+    /** Context for API calls executing during/after upload where intent is active (e.g. complete, signPart, completeMultipart) */
+    type CompleteContext<P extends string, M extends Intent.Map> = Context<P, M> & Required<Pick<Context<P, M>, 'file' | 'intent' | 'signal'>>;
+    /** Context for API abort calls where intent is active but file/signal might be absent (e.g. abort) */
+    type AbortContext<P extends string, M extends Intent.Map> = Context<P, M> & Required<Pick<Context<P, M>, 'intent'>>;
+    /** Contract definition for your backend API endpoints. */
+    type Me<M extends Intent.Map, P extends string, R extends Result.Base = Result.Base> = {
+      /** Requests an upload intent from the server. */createIntent(args: {
+        purpose: P;
+        contentType: string;
+        size: number;
+        filename: string;
+        checksum?: string;
+        attempt: number;
+      }, ctx: CreateIntentContext<P, M>, ...extra: any[]): Promise<M[keyof M]>; /** Finalizes the upload on the server after bytes have been transferred. */
+      complete(args: {
+        fileId: string; /** Sanitized filename. Do not use the raw File.name from the browser. */
+        filename: string;
+        contentType: string;
+        size: number;
+        checksum?: string;
+        attempt: number;
+      }, ctx: CompleteContext<P, M>, ...extra: any[]): Promise<R>; /** Optional endpoint to fetch a signed preview/access URL for completed resources. */
+      getSignedPreviewUrl?(args: {
+        fileId: string;
+        key: string;
+        purpose: P;
+      }, ctx: Context<P, M>, ...extra: any[]): Promise<string>; /** Optional endpoint to verify if the file has already been uploaded previously. */
+      findByChecksum?(args: {
+        checksum: string;
+        purpose: P;
+      }, ctx: FindByChecksumContext<P, M>, ...extra: any[]): Promise<R | null>; /** Multipart-specific backend commands. Required if using the multipart strategy. */
+      multipart?: {
+        signPart(args: {
+          fileId: string;
+          uploadId: string;
+          partNumber: number;
+          checksum?: string;
+          attempt: number;
+        }, ctx: CompleteContext<P, M>, ...extra: any[]): Promise<{
+          url: string;
+          headers?: Record<string, string>;
+        }>;
+        completeMultipart(args: {
+          fileId: string;
+          uploadId: string;
+          parts: Array<{
+            partNumber: number;
+            etag: string;
+          }>;
+        }, ctx: CompleteContext<P, M>, ...extra: any[]): Promise<unknown>;
+        listParts?(args: {
+          fileId: string;
+          uploadId: string;
+        }, ctx: CompleteContext<P, M>, ...extra: any[]): Promise<Array<{
+          partNumber: number;
+          etag?: string;
+          size?: number;
+        }>>;
+        abort?(args: {
+          fileId: string;
+          uploadId: string;
+        }, ctx: AbortContext<P, M>, ...extra: any[]): Promise<void>;
+      }; /** TUS resumable protocol operations. */
+      tus?: {
+        create(args: {
+          fileId: string;
+          size: number;
+          filename: string;
+          contentType: string;
+          attempt: number;
+        }, ctx: CompleteContext<P, M>, ...extra: any[]): Promise<{
+          uploadUrl: string;
+        }>;
+        getOffset(args: {
+          uploadUrl: string;
+        }, ctx: CompleteContext<P, M>, ...extra: any[]): Promise<{
+          offset: number;
+        }>;
+      };
+    };
+  }
+  namespace Strategy {
+    /** Per-call context handed to a strategy's `start()` method. */
+    type Ctx<M extends Intent.Map, C extends Cursor.Map<M>, P extends string, R extends Result.Base, K extends keyof M & string> = {
+      localId: string;
+      purpose: P;
+      file: File;
+      fingerprint: FingerprintFile;
+      intent: M[K];
+      signal: AbortSignal;
+      attempt: number;
+      createdAt: number;
+      steps: readonly UploadStep[];
+      lastError?: StepError | undefined;
+      meta: Record<string, unknown>;
+      transport: {
+        put(args: {
+          url: string;
+          body: Blob;
+          headers?: Record<string, string>;
+          signal: AbortSignal;
+          onProgress?: (u: number, t: number) => void;
+        }): Promise<{
+          etag?: string | undefined;
+          headers?: Record<string, string>;
+        }>;
+        postForm(args: {
+          url: string;
+          fields: Record<string, string>;
+          file: File | Blob;
+          filename?: string;
+          signal: AbortSignal;
+          onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+        }): Promise<{
+          etag?: string;
+          headers?: Record<string, string>;
+        }>;
+        patch(args: {
+          url: string;
+          body: Blob | ArrayBuffer;
+          headers?: Record<string, string>;
+          signal: AbortSignal;
+          onProgress?: (u: number, t: number) => void;
+        }): Promise<{
+          headers?: Record<string, string>;
+        }>;
+        get?(args: {
+          url: string;
+          headers?: Record<string, string>;
+          signal: AbortSignal;
+          onProgress?: (loaded: number, total: number) => void;
+        }): Promise<{
+          blob: Blob;
+          status: number;
+          headers?: Record<string, string>;
+        }>;
+        head?(args: {
+          url: string;
+          headers?: Record<string, string>;
+          signal: AbortSignal;
+        }): Promise<{
+          status: number;
+          headers: Record<string, string>;
+        }>;
+      };
+      api: Api.Me<M, P, R>;
+      reportProgress: (p: {
+        uploadedBytes: number;
+        totalBytes: number;
+      }) => void;
+      readCursor: () => C[K] | undefined;
+      persistCursor: (cursor: C[K] | undefined) => void;
+    };
+    /** A single upload strategy implementation. */
+    type Me<M extends Intent.Map, C extends Cursor.Map<M>, P extends string, R extends Result.Base, K extends keyof M & string> = {
+      id: K;
+      resumable: boolean;
+      start(ctx: Ctx<M, C, P, R, K>): Promise<void>;
+    };
+    /** Registry of available upload strategies, keyed by strategy id. */
+    type Registry<M extends Intent.Map, C extends Cursor.Map<M>, P extends string = string, R extends Result.Base = Result.Base> = {
+      get<K extends keyof M & string>(id: K): Me<M, C, P, R, K> | undefined;
+      has(id: string): id is keyof M & string;
+      set<K extends keyof M & string>(strategy: Me<M, C, P, R, K>): void;
+    };
+  }
+}
+//#endregion
+//#region src/core/contracts/transport/transport.types.d.ts
+/**
+ * Transport contracts: the network layer the engine uses to move bytes.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare namespace Transport {
+  /**
+   * Abstraction layer for network operations.
+   * Allows switching between XHR (browser) or other implementations (testing/Node).
+   *
+   * Designed to support:
+   * - Deterministic progress tracking (requires XHR in browsers)
+   * - Cancellation via AbortSignal
+   * - Header parsing (ETag extraction)
+   */
+  type Options = {
+    /**
+     * Performs an HTTP PUT request (typically for S3 signed URLs).
+     */
+    put(args: {
+      url: string;
+      body: Blob;
+      headers?: Record<string, string>;
+      signal: AbortSignal;
+      onProgress?: (u: number, t: number) => void;
+    }): Promise<{
+      etag?: string | undefined;
+      headers?: Record<string, string>;
+    }>;
+    /**
+     * Performs an HTTP POST multipart request.
+     */
+    postForm(args: {
+      url: string;
+      fields: Record<string, string>;
+      file: File | Blob;
+      filename?: string;
+      signal: AbortSignal;
+      onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+    }): Promise<{
+      etag?: string;
+      headers?: Record<string, string>;
+    }>;
+    /**
+     * Performs an HTTP request.
+     */
+    patch(args: {
+      url: string;
+      body: Blob | ArrayBuffer;
+      headers?: Record<string, string>;
+      signal: AbortSignal;
+      onProgress?: (u: number, t: number) => void;
+    }): Promise<{
+      headers?: Record<string, string>;
+    }>;
+    /**
+     * Optional HTTP GET download. Streams the response so `onProgress` can
+     * report bytes as they arrive. Not every transport implements it — check
+     * for presence before calling.
+     */
+    get?(args: {
+      url: string;
+      headers?: Record<string, string>;
+      signal: AbortSignal;
+      onProgress?: (loaded: number, total: number) => void;
+    }): Promise<{
+      blob: Blob;
+      status: number;
+      headers?: Record<string, string>;
+    }>;
+    /**
+     * Optional HTTP HEAD. Used by resumable strategies (tus) to read the
+     * server's current `Upload-Offset` before resuming. Not every transport
+     * implements it — check for presence before calling.
+     */
+    head?(args: {
+      url: string;
+      headers?: Record<string, string>;
+      signal: AbortSignal;
+    }): Promise<{
+      status: number;
+      headers: Record<string, string>;
+    }>;
+  };
+  type XhrArgs = {
+    url: string;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    onProgress?: (loaded: number, total: number) => void;
+  };
+}
+//#endregion
+//#region src/core/contracts/transport/transport.d.ts
+/**
+ * Browser-native XHR transport. Uses `XMLHttpRequest` over `fetch` because
+ * `fetch` lacks cross-browser upload-progress events.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare function createXHRTransport(): Transport.Options & {
+  /** Optional PATCH for tus-style strategies. */patch?: (args: Transport.XhrArgs & {
+    body: Blob | ArrayBuffer;
+  }) => Promise<{
+    headers: Record<string, string>;
+  }>;
+};
+//#endregion
+//#region src/core/contracts/transport/transport.fetch.d.ts
+/**
+ * Create a `fetch`-backed {@link Transport.Options} implementation.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare function createFetchTransport(): Transport.Options;
+//#endregion
+//#region src/core/errors.d.ts
+/**
+ * Structured extra context properties for upload errors.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+type UploadErrorContext = Record<string, unknown>;
+/**
+ * Base typed error thrown by the upload engine.
+ *
+ * Always carries a stable error classification `code` and an immutable, static
+ * `message`. Attic strings (like raw input details) live under `context` or subclass-specific fields.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadEngineError extends Error {
+  /** Stable machine-readable error code. */
+  readonly code: string;
+  /** Structured context details. */
+  readonly context?: UploadErrorContext;
+  /** Original error, if any, mapped per ES2022. */
+  readonly cause?: unknown;
+  /** Flag specifying whether the error recovery system should schedule retries. */
+  readonly retryable: boolean;
+  constructor(code: string, init?: {
+    message?: string | undefined;
+    context?: UploadErrorContext | undefined;
+    cause?: unknown;
+    retryable?: boolean | undefined;
+  });
+}
+/**
+ * Error thrown when file validation rules fail.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadValidationError extends UploadEngineError {
+  /** Structured rejection reason details. */
+  readonly reason: Contracts.Validation.Rejection;
+  constructor(reason: Contracts.Validation.Rejection, message?: string, init?: {
+    cause?: unknown;
+    context?: UploadErrorContext;
+  });
+}
+/**
+ * Error thrown when an upload strategy identifier is not registered.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadStrategyMissingError extends UploadEngineError {
+  /** Unregistered strategy identifier. */
+  readonly strategy: string;
+  constructor(strategy: string, message?: string, init?: {
+    cause?: unknown;
+    context?: UploadErrorContext;
+  });
+}
+/**
+ * Error thrown when an upload is aborted (paused or canceled).
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadAbortError extends UploadEngineError {
+  /** Reason context for the abort. */
+  readonly reason: 'pause' | 'cancel' | 'unknown';
+  constructor(reason: 'pause' | 'cancel' | 'unknown', message?: string, init?: {
+    cause?: unknown;
+    context?: UploadErrorContext;
+  });
+}
+/**
+ * Error thrown on transport-level connection or fetch failures.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadNetworkError extends UploadEngineError {
+  constructor(message?: string, init?: {
+    cause?: unknown;
+    context?: UploadErrorContext;
+  });
+}
+/**
+ * Error thrown when a non-2xx HTTP status response is returned.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadHttpError extends UploadEngineError {
+  /** HTTP response status code. */
+  readonly status: number;
+  /** HTTP response status text message. */
+  readonly statusText?: string;
+  constructor(status: number, message?: string, init?: {
+    statusText?: string | undefined;
+    cause?: unknown;
+    context?: UploadErrorContext | undefined;
+    retryable?: boolean | undefined;
+  });
+}
+/**
+ * Error thrown when a timeout occurs during network operations.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadTimeoutError extends UploadEngineError {
+  constructor(message?: string, init?: {
+    cause?: unknown;
+    context?: UploadErrorContext;
+  });
+}
+/**
+ * Error thrown on authentication / authorization failures.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadAuthError extends UploadEngineError {
+  constructor(message?: string, init?: {
+    cause?: unknown;
+    context?: UploadErrorContext;
+  });
+}
+/**
+ * Error thrown when the endpoint indicates rate limits are exceeded.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadRateLimitError extends UploadEngineError {
+  /** Optional delay value recommended by the server before retry. */
+  readonly retryAfterMs?: number;
+  constructor(message?: string, init?: {
+    retryAfterMs?: number;
+    cause?: unknown;
+    context?: UploadErrorContext;
+  });
+}
+/**
+ * Error thrown when custom backend/server validation errors are reported.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadServerError extends UploadEngineError {
+  /** Server-defined diagnostic code. */
+  readonly serverCode?: string;
+  constructor(message?: string, init?: {
+    serverCode?: string;
+    cause?: unknown;
+    context?: UploadErrorContext;
+  });
+}
+/**
+ * Fallback error class for unclassified or legacy throws.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare class UploadUnknownError extends UploadEngineError {
+  constructor(message?: string, init?: {
+    cause?: unknown;
+    context?: UploadErrorContext;
+  });
+}
+/**
+ * Runtime error stored on items and passed through engine events.
+ * Plain contract shapes and {@link UploadEngineError} subclasses are both valid.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+type UploadError = Contracts.Errors.Error | UploadEngineError;
+//#endregion
+//#region src/core/persistence/persistence.types.d.ts
+/**
+ * Persistence layer interfaces and options.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare namespace UploadPersistence {
+  /**
+   * Type context handed to deserializers to validate dynamic properties during recovery.
+   *
+   * @template M - Intent map type
+   * @template P - Purpose string union type
+   */
+  type DeserializeContext<M extends Contracts.Intent.Map, P extends string> = {
+    /** Guard checking if a purpose string is valid. */isPurpose?: ((value: string) => value is P) | undefined; /** Guard checking if an intent matches expected schemas. */
+    isIntent?: ((value: unknown) => value is M[keyof M]) | undefined; /** Query to verify if a strategy discriminant is active in runtime strategies. */
+    hasStrategy?: ((value: string) => boolean) | undefined;
+  };
+  /**
+   * Configuration options for the upload store persistence manager.
+   *
+   * @template M - Intent map type
+   * @template C - Cursor map type
+   * @template P - Purpose string union type
+   * @template R - Backend result shape
+   */
+  type Options<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base> = {
+    /** Target key used to store the serialized string representation of snapshots. */key: string; /** Schema version identifier. Increment when changing models to run safe migrations. */
+    version: number; /** Milliseconds to wait before writing changes to disk (throttling storage writes). */
+    debounceMs?: number; /** Target storage adapter (e.g. LocalStorageAdapter, IndexedDBAdapter). */
+    adapter: Adapter;
+    /**
+     * Optional custom serialization mapper.
+     */
+    serialize?: (state: Engine.State<M, C, P, R>, version: number) => Snapshot<M, C, P>;
+    /**
+     * Optional custom deserialization mapper.
+     */
+    deserialize?: (raw: unknown, ctx: DeserializeContext<M, P>) => Engine.State<M, C, P, R> | null;
+    /**
+     * Runtime validation guard for purpose strings. Required if using the default deserializer.
+     */
+    isPurpose?: ((value: string) => value is P) | undefined;
+    /**
+     * Runtime validation guard for intent objects. Required if using the default deserializer.
+     */
+    isIntent?: ((value: unknown) => value is M[keyof M]) | undefined;
+  };
+  /**
+   * Plain-object representation of a stored upload item.
+   * Files cannot be fully serialized; hence their binary metadata is stashed.
+   */
+  type PersistedItem<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string> = {
+    /** Unique client-side file identifier. */id: string; /** Upload purpose. */
+    purpose: P; /** Target status phase key (e.g. `'uploading'`, `'paused'`). */
+    status: string; /** Serialized metadata of the file. */
+    file: {
+      /** Base name. */name: string; /** Size in bytes. */
+      size: number; /** Claimed MIME type. */
+      type: string; /** Mod date timestamp in ms. */
+      lastModified: number; /** Checksum fingerprint hash if calculated. */
+      checksum?: string | undefined;
+    }; /** The active backend intent payload. */
+    intent: Contracts.Intent.Any<M>; /** Strategy-defined resume cursor state. */
+    cursor?: Contracts.Cursor.Any<C> | undefined; /** Current progress measurements. */
+    progress?: {
+      uploadedBytes: number;
+      totalBytes: number;
+      pct?: number | undefined;
+    } | undefined;
+  };
+  /**
+   * A minimal, serializable representation of an upload item that is safe to store
+   * in persistence (LocalStorage, IndexedDB, etc).
+   *
+   * @typeParam M - Map of upload intent variants keyed by intent kind (e.g. `direct`, `multipart`).
+   * @typeParam C - Map of cursor shapes keyed by {@link M}'s intent kinds.
+   * @typeParam P - Union of allowed `purpose` strings for your app (e.g. `"avatar" | "document"`).
+   */
+  type Snapshot<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string> = {
+    /** Persistence schema version (not app version). */version: number; /** Unix epoch milliseconds when this snapshot was written. */
+    createdAt: number; /** List of persisted upload items. */
+    items: Record<string, PersistedItem<M, C, P>>;
+  };
+  /**
+   * Driver interface for persisting upload store snapshots.
+   */
+  type Adapter = {
+    /**
+     * Resolves and returns the stored snapshot payload.
+     * Can return null if no snapshot exists.
+     */
+    load(key: string): unknown | null | Promise<unknown | null>;
+    /**
+     * Saves a snapshot payload to the target storage location.
+     */
+    save(key: string, snapshot: unknown): void | Promise<void>;
+    /**
+     * Deletes the snapshot record.
+     */
+    clear(key: string): void | Promise<void>;
+  };
+}
+//#endregion
+//#region src/core/persistence/adapters.indexeddb.d.ts
+/**
+ * Persistence adapter backed by IndexedDB, for durable snapshot storage in the
+ * browser without the size limits of `localStorage`.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare const IndexedDBAdapter: UploadPersistence.Adapter;
+//#endregion
+//#region src/core/persistence/adapters.local.d.ts
+/**
+ * Persistence adapter backed by `localStorage`. Synchronous and simple; best
+ * suited to small snapshots.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare const LocalStorageAdapter: UploadPersistence.Adapter;
+//#endregion
+//#region src/core/persistence/adapters.memory.d.ts
+/**
+ * Create an in-memory {@link PersistenceAdapter} backed by a fresh `Map`.
+ *
+ * Each call returns an isolated store. Multi-engine and multi-tenant
+ * deployments must use the factory so engine instances cannot read or
+ * overwrite each other's snapshots.
+ *
+ * @example
+ * ```ts
+ * const adapter = createMemoryAdapter()
+ * createUploadStore({ persistence: { adapter, key: 'tenant-a' } })
+ * ```
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare function createMemoryAdapter(): UploadPersistence.Adapter;
+/**
+ * Shared in-memory adapter instance. Convenient for single-engine apps; use
+ * {@link createMemoryAdapter} when isolation between engines is required.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare const MemoryAdapter: UploadPersistence.Adapter;
+//#endregion
+//#region src/core/persistence/persistence.d.ts
+/**
+ * Serializes the current upload state into a JSON-safe structure.
+ * Only serializes items that have a valid 'intent', as these are the only ones
+ * that can be resumed cleanly.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare function serializeSnapshot<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base>(state: Engine.State<M, C, P, R>, version: number): UploadPersistence.Snapshot<M, C, P>;
+/**
+ * Deserializes a persisted snapshot back into a store state.
+ *
+ * Important:
+ * - Browser `File` objects cannot be restored from persistence.
+ * - We restore resumable items (those with a cursor) into the `paused` phase,
+ *   with `file` left undefined. Your UI can ask the user to rebind the file.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare function deserializeSnapshot<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base>(raw: unknown, opts: UploadPersistence.DeserializeContext<M, P>): Engine.State<M, C, P, R> | null;
+//#endregion
+//#region src/core/utils/emitter/emitter.types.d.ts
+declare namespace Emitter {
+  /**
+   * Minimal typed event emitter interface.
+   *
+   * Use this to expose strongly-typed events from your store.
+   *
+   * @typeParam E - Event map (`eventName -> payload`).
+   */
+  type TypedEmitter<E extends Record<string, unknown>> = {
+    /**
+     * Subscribe to an event.
+     * @returns Unsubscribe function.
+     */
+    on<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void;
+    /**
+     * Unsubscribe from an event.
+     */
+    off<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): void; /** Emit an event to all listeners. */
+    emit<K extends keyof E & string>(type: K, payload: E[K]): void;
+  };
+  /**
+   * Callback invoked when a listener throws during `emit`, so one bad listener
+   * cannot break the dispatch loop. Receives the event type, the thrown error,
+   * and the listener that threw.
+   */
+  type ErrorHandler = (type: string, error: unknown, cb: (...args: any[]) => void) => void;
+  /**
+   * Listener registry, bucketed by event type.
+   *
+   * @template E Event map.
+   */
+  type ListenerMap<E extends Record<string, unknown>> = Partial<{ [K in keyof E & string]: Set<(payload: E[K]) => void> }>;
+}
+//#endregion
+//#region src/core/engine/reducer.d.ts
+declare function createReducer<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base>(): (state: Engine.State<M, C, P, R>, event: Engine.Command<P> | Engine.Event<M, C, P, R>) => Engine.State<M, C, P, R>;
+//#endregion
+//#region src/core/engine/store/store.types.d.ts
+/**
+ * Store-level namespaces and contracts.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare namespace Store {
+  /**
+   * Public upload store interface used by UI adapters and application code.
+   *
+   * Coordinates commands, subscriptions, event bindings, and lifecycle states.
+   *
+   * @template M - Intent map type (keyed by strategy id)
+   * @template C - Cursor map type (keyed by strategy id)
+   * @template P - Purpose string union type
+   * @template R - Backend result shape
+   */
+  type UploadStore<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base> = {
+    /**
+     * Returns the current immutable state snapshot.
+     * Use this in custom React lifecycle bindings or debug inspectors.
+     */
+    getSnapshot(): Engine.State<M, C, P, R>;
+    /**
+     * Subscribes to any internal state change.
+     * Triggered after reducers process events and side effects are queued.
+     *
+     * @param listener - Callback invoked on state updates.
+     * @returns An unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Dispatches a command to initiate state transitions (e.g. adding files, pausing, canceling).
+     *
+     * @param cmd - Public command payload.
+     */
+    dispatch(cmd: Engine.Command<P>): void;
+    /**
+     * Binds a listener to a specific typed event (e.g. `'upload.progress'`).
+     *
+     * @param type - Event name key.
+     * @param cb - Event listener callback.
+     * @returns An unsubscribe function.
+     */
+    on: <K extends keyof Engine.EventMap<M, C, P, R> & string>(type: K, cb: (payload: Engine.EventMap<M, C, P, R>[K]) => void) => () => void;
+    /**
+     * Removes an event listener.
+     *
+     * @param type - Event name key.
+     * @param cb - Event listener callback.
+     */
+    off: <K extends keyof Engine.EventMap<M, C, P, R> & string>(type: K, cb: (payload: Engine.EventMap<M, C, P, R>[K]) => void) => void;
+    /**
+     * Resolves when the specified items reach a terminal state
+     * (completed, failed, canceled, or missing).
+     *
+     * @param localIds - Array of registered client file IDs.
+     */
+    waitFor(localIds: string[]): Promise<Array<Engine.Outcome<R>>>;
+  };
+  /**
+   * Configuration options for constructing an upload store.
+   *
+   * @template M - Intent map type (keyed by strategy id)
+   * @template C - Cursor map type (keyed by strategy id)
+   * @template P - Purpose string union type
+   * @template R - Backend result shape
+   */
+  type Options<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base> = {
+    /** Initial state to hydrate from (e.g. recovered from a persistence snapshot). */initialState?: Engine.State<M, C, P, R>; /** Engine configuration (defaults applied for unspecified settings). */
+    config?: Partial<Engine.Config<P>>; /** Persistence adapter configuration (key prefix, adapters, storage handlers). */
+    persistence?: UploadPersistence.Options<M, C, P, R>; /** Your backend API implementation. */
+    api: Contracts.Api.Me<M, P, R>; /** Transport layer options for HTTP byte transfers. */
+    transport?: Transport.Options; /** Registry of available upload strategies (multipart, POST forms, simple PUTs, TUS). */
+    strategies: Contracts.Strategy.Registry<M, C, P, R>; /** Plugin modules to extend behavior (metrics, logging, analytics). */
+    plugins?: Array<Engine.Plugin<M, C, P, R>>; /** Lifecycle hooks for observing internal events. */
+    hooks?: Engine.Hooks<M, C, P, R>;
+    /**
+     * Override to use a custom fingerprinting implementation (e.g. a custom hash).
+     */
+    fingerprint?: (file: File) => Contracts.FingerprintFile;
+    /**
+     * Custom per-file validator called after built-in config constraints pass.
+     * Return a rejection to block the file; return null to allow it.
+     */
+    validateFile?: (file: File, purpose: P) => Contracts.Validation.Rejection | null;
+    /**
+     * Custom error normalizer.
+     * Converts raw thrown values into a standardized Contracts.Errors.Error.
+     */
+    errorNormalizer?: (err: unknown) => Contracts.Errors.Error;
+  };
+  /**
+   * Tracks an in-flight upload operation.
+   */
+  type InflightUpload = {
+    /** AbortController for this upload. */controller: AbortController; /** Whether the upload is running normally, being paused, or being canceled. */
+    mode: 'normal' | 'pause' | 'cancel'; /** True once the strategy's start() has been called. */
+    started: boolean;
+  };
+  /**
+   * Internal execution context shared across store utilities, handlers, and schedulers.
+   */
+  type Runtime<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base> = {
+    /** Resolved store options with all defaults applied. */opts: Options<M, C, P, R> & {
+      config: Engine.Config<P>;
+      transport: Transport.Options;
+    }; /** Current engine state. */
+    state: Engine.State<M, C, P, R>; /** Active state change subscribers. */
+    listeners: Set<() => void>; /** Typed event emitter. */
+    emitter: Emitter.TypedEmitter<Engine.EventMap<M, C, P, R>>; /** Reducer function. */
+    reduce: ReturnType<typeof createReducer<M, C, P, R>>; /** Inflight upload operations keyed by localId. */
+    inflightUploads: Map<string, InflightUpload>; /** Inflight intent creation requests keyed by localId. */
+    inflightIntents: Map<string, AbortController>; /** Inflight complete() calls keyed by localId. */
+    inflightCompletes: Map<string, AbortController>; /** Queued async side effects. */
+    effectQueue: Array<() => Promise<void>>; /** True while the effect queue is being drained. */
+    processingEffects: boolean; /** True while scheduleWork is running, preventing re-entrant calls. */
+    scheduling: boolean; /** Notifies all state change subscribers. */
+    notify: () => void; /** Starts queued uploads when concurrency slots are available. */
+    scheduleWork: () => void; /** Applies an internal event through the reducer and notifies subscribers. */
+    applyInternal: (event: Engine.Event<M, C, P, R>) => void; /** Runs a command through the reducer. */
+    applyCommand: (cmd: Engine.Command<P>) => void; /** Adds an async side effect to the execution queue. */
+    enqueueEffect: (effect: () => Promise<void>) => void; /** Drains the effect queue, running each side effect in order. */
+    processEffects: () => Promise<void>; /** Dispatches a public command. */
+    dispatch: (cmd: Engine.Command<P>) => void;
+  };
+}
+//#endregion
+//#region src/core/engine/store/index.d.ts
+/**
+ * Creates an upload store instance.
+ *
+ * This is the main runtime object you interact with from the outside:
+ * - dispatch user commands (add files, start, pause, cancel, resume)
+ * - subscribe to state changes (for UI rendering)
+ * - subscribe to typed events (for progress, errors, and lifecycle)
+ *
+ * Plugins are initialized once during construction and receive a minimal store
+ * proxy (events, dispatch, snapshot access) to avoid tight coupling.
+ *
+ * @template M - Intent map type (keyed by strategy id)
+ * @template C - Cursor map type (keyed by strategy id)
+ * @template P - Purpose string union type
+ *
+ * @param opts - Store options (config, backend API, strategies, transport, hooks)
+ * @returns A configured {@link Store.UploadStore} instance.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare function createUploadStore<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base>(opts: Store.Options<M, C, P, R>): Store.UploadStore<M, C, P, R>;
+//#endregion
+//#region src/core/engine/engine.types.d.ts
+/**
+ * Engine-level type surface containing runtime state models, commands, progress,
+ * and configuration options.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare namespace Engine {
+  /**
+   * Return value from a retry policy determining if and when a task should be re-scheduled.
+   */
+  export type RetryDecision = {
+    /** The task has failed terminal or cannot recover. */retryable: false;
+  } | {
+    /** The task is recoverable and should retry. */retryable: true; /** Delay duration in milliseconds before invoking the next attempt. */
+    delayMs: number;
+  };
+  /**
+   * Global upload engine configuration.
+   *
+   * Coordinates concurrency limits, retry strategies, constraints, and validation.
+   *
+   * @typeParam P - Union of allowed `purpose` strings for your app (e.g. `"avatar" | "attachment"`).
+   */
+  export type Config<P extends string> = {
+    /**
+     * Maximum number of parallel uploads active at any time.
+     * Queued items wait until active uploads complete or fail.
+     */
+    maxConcurrentUploads: number;
+    /**
+     * Auto-start uploads for specific purposes.
+     * - Array form: only files with these purposes automatically begin uploading on registration.
+     * - Function form: dynamic callback determining whether to auto-start.
+     */
+    autoStart?: (readonly P[] | ((purpose: P) => boolean)) | undefined;
+    /**
+     * Throttle delay in milliseconds for progress events.
+     * Limits rendering updates and state changes under busy progress flows.
+     */
+    progressThrottleMs: number;
+    /**
+     * Validation rules keyed by purpose.
+     */
+    validation: Partial<Record<P, Contracts.ValidationRules>>;
+    /**
+     * Maximum number of retry attempts permitted for upload/intent actions.
+     */
+    maxAttempts: number;
+    /**
+     * Custom retry policy handler.
+     * Overrides default exponential backoff calculation.
+     */
+    retryPolicy?: ((ctx: {
+      /** The active execution phase. */phase: 'intent' | 'upload' | 'complete'; /** Current attempt number (starting at 1). */
+      attempt: number; /** The normalized error structure. */
+      error: UploadError;
+    }) => RetryDecision) | undefined;
+    /**
+     * Maximum number of items to keep in memory/state.
+     * When exceeded, oldest completed/canceled items are evicted automatically.
+     *
+     * Set to `undefined` for no limit (not recommended for long-running single-page apps).
+     */
+    maxItems: number;
+    /**
+     * Duration in milliseconds after which completed items are evicted from the store.
+     * Set to `undefined` to preserve completed items indefinitely.
+     */
+    completedItemTTL?: number | undefined;
+    /**
+     * Set to `true` to validate files by sniffing magic bytes/mime signature
+     * and rejecting files whose suffix does not match structural magic numbers.
+     */
+    strictMimeMatch?: boolean | undefined;
+    /**
+     * File-size boundary in bytes between the two checksum paths. At or below
+     * it, files hash inline with native Web Crypto (fastest). Above it, files
+     * hash incrementally in bounded slices — off the main thread via a Web
+     * Worker when available — so large files no longer freeze the UI and are
+     * still deduplicated. Set to `null` or `undefined` for the default (64 MiB).
+     */
+    checksumMaxSize?: number | null | undefined;
+  };
+  /**
+   * Upload progress snapshot.
+   */
+  export type Progress = {
+    /** Bytes uploaded so far. */uploadedBytes: number; /** Total bytes to upload. */
+    totalBytes: number; /** Percent complete (0..100). */
+    pct: number;
+  };
+  /**
+   * Describes how a `completed` upload item resolved.
+   * - `'upload'`: standard byte transfer.
+   * - `'dedupe'`: server matched existing file checksum, skipping byte transfer.
+   */
+  export type CompletionKind = 'upload' | 'dedupe';
+  /**
+   * Terminal outcome returned by `waitFor`.
+   *
+   * @template R Result type carried on successful completion.
+   */
+  export type Outcome<R extends Contracts.Result.Base> = {
+    localId: string;
+    status: 'completed';
+    completedBy: CompletionKind;
+    result: R;
+  } | {
+    localId: string;
+    status: 'error';
+    error: UploadError;
+  } | {
+    localId: string;
+    status: 'canceled';
+  } | {
+    localId: string;
+    status: 'missing';
+    /**
+     * Why the id is missing.
+     * - `'removed'`: explicit user removal.
+     * - `'evicted'`: automatically removed (maxItems/TTL rules).
+     * - `'never-existed'`: id was never registered.
+     * - `'destroyed'`: store was destroyed.
+     */
+    reason: 'removed' | 'evicted' | 'never-existed' | 'destroyed';
+  };
+  /**
+   * Public commands dispatched to the upload store.
+   *
+   * @template P Purpose discriminator string.
+   */
+  export type Command<P extends string> = {
+    /** Register files into the upload store for a specific purpose. */type: 'addFiles';
+    files: File[];
+    purpose: P; /** Optional caller metadata forwarded to every backend API call for this file. */
+    meta?: Record<string, unknown> | undefined;
+  } | {
+    /** Start uploading a specific file. */type: 'start';
+    localId: string;
+  } | {
+    /** Start all queued files, optionally filtering by purpose. */type: 'startAll';
+    purpose?: P;
+  } | {
+    /** Pause an active upload. */type: 'pause';
+    localId: string;
+  } | {
+    /** Pause all active uploads, optionally filtering by purpose. */type: 'pauseAll';
+    purpose?: P;
+  } | {
+    /** Resume a paused upload. */type: 'resume';
+    localId: string;
+  } | {
+    /** Cancel a pending or active upload. */type: 'cancel';
+    localId: string;
+  } | {
+    /** Cancel all pending and active uploads, optionally filtering by purpose. */type: 'cancelAll';
+    purpose?: P;
+  } | {
+    /** Retry a failed upload item. */type: 'retry';
+    localId: string;
+  } | {
+    /** Re-bind a new browser `File` object to a resumed/paused item missing a file reference. */type: 'rebind';
+    localId: string;
+    file: File;
+  } | {
+    /** Remove an item from the store state entirely. */type: 'remove';
+    localId: string;
+  };
+  /**
+   * Const mapping of upload stages.
+   */
+  export const Phases: {
+    /** Initial validation checks are running. */readonly validating: "validating"; /** Fetching signed URLs and strategies from backend. */
+    readonly creating_intent: "creating_intent"; /** Ready to start uploading bytes. */
+    readonly ready: "ready"; /** Waiting in queue (concurrency cap reached). */
+    readonly queued: "queued"; /** Actively transferring bytes. */
+    readonly uploading: "uploading"; /** Upload paused; resumable state preserved. */
+    readonly paused: "paused"; /** Triggering backend finalization. */
+    readonly completing: "completing"; /** File is fully completed and registered on backend. */
+    readonly completed: "completed"; /** Execution hit a terminal error or maximum retry cap. */
+    readonly error: "error"; /** Upload was canceled by the user. */
+    readonly canceled: "canceled";
+  };
+  /** Every upload phase; the `phase` discriminator of {@link Item}. */
+  export type Phase = keyof typeof Phases;
+  interface BaseItem<P extends string> {
+    /** Unique client-side identifier for this file item. */
+    localId: string;
+    /** Target upload purpose. */
+    purpose: P;
+    /** Metadata properties identifying the file. */
+    fingerprint: Contracts.FingerprintFile;
+    /** Epoch timestamp in ms when the item was registered. */
+    createdAt: number;
+    attempt?: number | undefined;
+    file?: File | undefined;
+    /** Full phase history. Each entry records when a phase was entered/left and any stripped error. */
+    steps: Contracts.UploadStep[];
+    /** Arbitrary caller-supplied metadata from the addFiles command. Never persisted. */
+    meta: Record<string, unknown>;
+  }
+  /**
+   * Representational union of upload items in their respective lifecycle phases.
+   */
+  export type Item<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base> = BaseItem<P> & ({
+    phase: 'validating';
+    file: File;
+  } | {
+    phase: 'creating_intent';
+    file: File;
+    attempt: number;
+  } | {
+    phase: 'ready';
+    file: File;
+    intent: Contracts.Intent.Any<M>;
+    cursor?: Contracts.Cursor.Any<C> | undefined;
+    progress?: Progress | undefined;
+  } | {
+    phase: 'queued';
+    file: File;
+    intent: Contracts.Intent.Any<M>;
+    requestedAt: number;
+    cursor?: Contracts.Cursor.Any<C> | undefined;
+    progress?: Progress | undefined;
+  } | {
+    phase: 'uploading';
+    file: File;
+    intent: Contracts.Intent.Any<M>;
+    startedAt: number;
+    progress: Progress;
+    cursor?: Contracts.Cursor.Any<C> | undefined;
+  } | {
+    phase: 'paused';
+    intent: Contracts.Intent.Any<M>;
+    cursor: Contracts.Cursor.Any<C>;
+    progress: Progress;
+    pausedAt: number;
+    file?: File | undefined;
+  } | {
+    phase: 'completing';
+    file: File;
+    intent: Contracts.Intent.Any<M>;
+    progress: Progress;
+    completingAt: number;
+  } | {
+    phase: 'completed';
+    completedBy: CompletionKind;
+    result: R;
+    completedAt: number;
+    intent?: Contracts.Intent.Any<M> | undefined;
+    file?: File | undefined;
+  } | {
+    phase: 'error';
+    error: UploadError;
+    retryable: boolean;
+    attempt: number;
+    failedAt: number;
+    file?: File | undefined;
+    intent?: Contracts.Intent.Any<M> | undefined;
+    cursor?: Contracts.Cursor.Any<C> | undefined;
+    progress?: Progress | undefined;
+  } | {
+    phase: 'canceled';
+    canceledAt: number;
+    file?: File | undefined;
+    intent?: Contracts.Intent.Any<M> | undefined;
+    cursor?: Contracts.Cursor.Any<C> | undefined;
+    progress?: Progress | undefined;
+    attempt?: number | undefined;
+  });
+  /**
+   * Immutable state shape of the upload engine store.
+   */
+  export type State<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base> = {
+    /** Map of active and historical upload items. */items: Map<string, Item<M, C, P, R>>;
+  };
+  /**
+   * Interface for registering lifecycle plugins.
+   */
+  export type Plugin<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base> = {
+    /** Name of the plugin (for diagnostics). */name: string; /** Sets up subscription listener binds on the store core proxy. */
+    setup(store: Pick<Store.UploadStore<M, C, P, R>, 'on' | 'off' | 'dispatch' | 'getSnapshot'>): void;
+  };
+  /**
+   * Events emitted by effects and consumed by the reducer to transition item states.
+   */
+  export type Event<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base> = {
+    type: 'files.added';
+    items: Array<{
+      localId: string;
+      purpose: P;
+      file: File;
+      fingerprint: Contracts.FingerprintFile;
+      createdAt: number;
+      meta: Record<string, unknown>;
+    }>;
+  } | {
+    type: 'fingerprint.updated';
+    localId: string;
+    fingerprint: Contracts.FingerprintFile;
+  } | {
+    type: 'validation.ok';
+    localId: string;
+  } | {
+    type: 'validation.failed';
+    localId: string;
+    reason: Contracts.Validation.Rejection;
+  } | {
+    type: 'intent.ok';
+    localId: string;
+    intent: Contracts.Intent.Any<M>;
+  } | {
+    type: 'intent.failed';
+    localId: string;
+    error: UploadError;
+    retryable: boolean;
+  } | {
+    type: 'upload.begin';
+    localId: string;
+    startedAt: number;
+  } | {
+    type: 'upload.progress';
+    localId: string;
+    uploadedBytes: number;
+    totalBytes: number;
+  } | {
+    type: 'cursor.updated';
+    localId: string;
+    cursor: Contracts.Cursor.Any<C>;
+  } | {
+    type: 'upload.ok';
+    localId: string;
+  } | {
+    type: 'upload.failed';
+    localId: string;
+    error: UploadError;
+    retryable: boolean;
+  } | {
+    type: 'dedupe.ok';
+    localId: string;
+    result: R;
+  } | {
+    type: 'complete.ok';
+    localId: string;
+    result: R;
+  } | {
+    type: 'complete.failed';
+    localId: string;
+    error: UploadError;
+    retryable: boolean;
+  } | {
+    type: 'paused';
+    localId: string;
+    cursor: Contracts.Cursor.Any<C>;
+    pausedAt: number;
+  } | {
+    type: 'canceled';
+    localId: string;
+    canceledAt: number;
+  };
+  /**
+   * Public event registry mapping event names to payloads emitted via `store.on()`.
+   */
+  export type EventMap<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base> = {
+    /** Emitted when a file is validated and successfully registered in state. */'file.added': {
+      localId: string;
+      purpose: P;
+      file: File;
+      fingerprint: Contracts.FingerprintFile;
+    }; /** Emitted when a file fails client-side validation rules. */
+    'file.rejected': {
+      file: File;
+      reason: Contracts.Validation.Rejection;
+    }; /** Emitted when validation succeeds. */
+    'validation.ok': {
+      localId: string;
+    }; /** Emitted when validation fails. */
+    'validation.failed': {
+      localId: string;
+      reason: Contracts.Validation.Rejection;
+    }; /** Emitted when intent lookup/creation is requested. */
+    'intent.creating': {
+      localId: string;
+    }; /** Emitted when upload intent is successfully created. */
+    'intent.created': {
+      localId: string;
+      intent: M[keyof M];
+    }; /** Emitted when intent creation fails. */
+    'intent.failed': {
+      localId: string;
+      error: UploadError;
+      retryable: boolean;
+    }; /** Emitted when an item is queued waiting for concurrency slots. */
+    'upload.queued': {
+      localId: string;
+    }; /** Emitted when a paused upload is resumed. */
+    'upload.resumed': {
+      localId: string;
+    }; /** Emitted when data transfer starts. */
+    'upload.started': {
+      localId: string;
+    }; /** Periodic progress event. */
+    'upload.progress': {
+      localId: string;
+      pct: number;
+      uploadedBytes: number;
+      totalBytes: number;
+    }; /** Emitted when strategy cursor state is updated. */
+    'upload.cursor': {
+      localId: string;
+      cursor: Contracts.Cursor.Any<C>;
+    }; /** Emitted when upload is paused. */
+    'upload.paused': {
+      localId: string;
+      cursor: Contracts.Cursor.Any<C>;
+    }; /** Emitted when upload is canceled. */
+    'upload.canceled': {
+      localId: string;
+    }; /** Emitted when final completing steps (like completeMultipart or final verification) begin. */
+    'upload.completing': {
+      localId: string;
+    }; /** Emitted when a file is completely uploaded and finalized. */
+    'upload.completed': {
+      localId: string;
+      result: R;
+      completedBy: CompletionKind;
+    }; /** Emitted when transfer hits a retryable or terminal error. */
+    'upload.error': {
+      localId: string;
+      error: UploadError;
+      retryable: boolean;
+    }; /** Emitted when an item is removed from the store state. */
+    'upload.removed': {
+      localId: string;
+      reason: 'user' | 'cleanup';
+    }; /** Emitted when a file rebind operation succeeds. */
+    'rebind.ok': {
+      localId: string;
+    }; /** Emitted when a file rebind fails. */
+    'rebind.failed': {
+      localId: string;
+      reason: RebindReason;
+    };
+  };
+  /**
+   * Rebind failure classifications.
+   */
+  export type RebindReason = {
+    code: 'no_item';
+  } | {
+    code: 'wrong_phase';
+    phase: string;
+  } | {
+    code: 'already_bound';
+  } | {
+    code: 'fingerprint_mismatch';
+    expected: Contracts.FingerprintFile;
+    got: Contracts.FingerprintFile;
+  };
+  /**
+   * Diagnostic hooks for observing engine updates.
+   */
+  export type Hooks<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string, R extends Contracts.Result.Base = Contracts.Result.Base> = {
+    /** Callback invoked on every state-reducing internal event. */onInternalEvent?: (event: Event<M, C, P, R>, state: State<M, C, P, R>) => void;
+  };
+  export {};
+}
+//#endregion
+//#region src/core/engine/engine.libs.d.ts
+/**
+ * Normalizes user config by applying sensible defaults.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+declare function resolveUploadConfig<P extends string>(input?: Partial<Engine.Config<P>>): Engine.Config<P>;
+//#endregion
+export { UploadUnknownError as C, Transport as D, createXHRTransport as E, Contracts as O, UploadTimeoutError as S, createFetchTransport as T, UploadHttpError as _, deserializeSnapshot as a, UploadServerError as b, createMemoryAdapter as c, UploadPersistence as d, UploadAbortError as f, UploadErrorContext as g, UploadError as h, Store as i, LocalStorageAdapter as l, UploadEngineError as m, Engine as n, serializeSnapshot as o, UploadAuthError as p, createUploadStore as r, MemoryAdapter as s, resolveUploadConfig as t, IndexedDBAdapter as u, UploadNetworkError as v, UploadValidationError as w, UploadStrategyMissingError as x, UploadRateLimitError as y };