@bensitu/image-editor 1.5.1 → 2.0.0

package/dist/types/animation/animation-queue.d.ts

@@ -0,0 +1,111 @@
+/**
+ * FIFO sequential animation queue that prevents overlapping
+ * animations and provides dispose-safe settlement so callers do not
+ * hang during `dispose` or hard-reset paths.
+ *
+ * Implements:
+ * - at most one entry runs at a time, in enqueue order.
+ * - animation-producing operations (`scaleImage`,
+ *   `rotateImage`, `resetImageTransform`, `undo`, `redo`) are routed
+ *   through this queue by the orchestrator.
+ * - every promise returned by {@link AnimationQueue.add}
+ *   eventually settles, even when the queue is drained by
+ *   {@link AnimationQueue.clear}.
+ * - the active entry's promise settles only after
+ *   its function settles, so the orchestrator can flip its
+ *   `isAnimating` flag inside the wrapped function before this queue
+ *   resolves the caller.
+ * - dispose paths can drain pending
+ *   entries via {@link AnimationQueue.clear} so queued callers do not
+ *   hang. In-flight animation wrappers (see `fabric/fabric-animation.ts`)
+ *   check `isDisposed` independently and exit without touching the
+ *   canvas; the queue itself never inspects editor state.
+ *
+ * @module
+ */
+/**
+ * Guarantees that animation-producing operations are executed strictly
+ * one after another, in the order they were enqueued.
+ *
+ * The queue is dispose-aware in the sense that {@link AnimationQueue.clear}
+ * settles every pending entry, so callers awaiting an enqueued slot
+ * (for example, `await editor.scaleImage(2)`) never hang once the
+ * orchestrator tears down. The queue itself does not call into Fabric
+ * and does not know whether the editor is disposed; it is the caller's
+ * responsibility to invoke `clear` when the underlying work can no
+ * longer be performed.
+ *
+ * @example
+ * ```ts
+ * const queue = new AnimationQueue();
+ * queue.add(() => object.scale(2, { duration: 300 }));
+ * queue.add(() => object.rotate(90, { duration: 300 }));
+ * // The rotate starts only after the scale completes.
+ * ```
+ */
+export declare class AnimationQueue {
+    /** Pending entries waiting to start, in FIFO order. */
+    private queue;
+    /** True while an entry is being awaited inside {@link drainQueue}. */
+    private running;
+    /**
+     * Enqueues an animation function and returns a Promise that settles
+     * when that specific entry completes.
+     *
+     * The promise resolves when `animationFn`'s returned promise resolves
+     * and rejects when it rejects, after the queue has popped the entry
+     * and before the next entry begins. This preserves FIFO ordering and
+     * lets the orchestrator flip its `isAnimating` flag inside
+     * `animationFn` before the public promise settles.
+     *
+     * @param animationFn - Function that performs async work and resolves
+     *   when the animation has finished or rejects with the original error.
+     * @returns A promise that settles once this specific entry has
+     *   completed, been rejected, or been drained by {@link clear}.
+     */
+    add(animationFn: () => Promise<void>): Promise<void>;
+    /**
+     * Cancels every pending entry so callers awaiting a queued slot do
+     * not hang. Used by `dispose` and hard-reset paths in the editor
+     * orchestrator.
+     *
+     * The currently active entry (if any) is not interrupted by this
+     * method; its promise settles when its function settles. Animation
+     * wrappers in `fabric/fabric-animation.ts` observe `isDisposed`
+     * independently and exit without touching the canvas, so the active
+     * entry typically settles promptly after dispose calls `clear`.
+     *
+     * @param reason - When provided, pending entries reject with this
+     *   value (typed errors from `core/errors.ts` are recommended for
+     *   diagnostics). When omitted, pending entries resolve normally,
+     *   which is the documented dispose default — the orchestrator's
+     *   own dispose guards prevent further canvas access.
+     */
+    clear(reason?: unknown): void;
+    /**
+     * Reports whether an entry is currently active. Returns `true` only
+     * while {@link drainQueue} is awaiting an entry's function; pending
+     * entries that have not yet started do not count as running.
+     */
+    isRunning(): boolean;
+    /**
+     * Reports whether an entry is active or waiting to run.
+     */
+    isBusy(): boolean;
+    /**
+     * Resolves after the active entry and every currently pending entry
+     * has settled (resolved or rejected). This is the public hook the
+     * orchestrator uses to await a quiescent queue, for example before
+     * tearing down the canvas in a hard-reset path.
+     *
+     * The implementation appends a no-op sentinel so the returned
+     * promise inherits the FIFO settlement order. If the queue is
+     * already idle, the returned promise resolves on the microtask
+     * tick. Sentinel rejections (from {@link clear} with a reason) are
+     * swallowed; "settled" includes "rejected" for the purposes of this
+     * method.
+     */
+    waitForIdle(): Promise<void>;
+    private drainQueue;
+}
+//# sourceMappingURL=animation-queue.d.ts.map

package/dist/types/animation/animation-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-queue.d.ts","sourceRoot":"","sources":["../../../src/animation/animation-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAWH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAc;IACvB,uDAAuD;IACvD,OAAO,CAAC,KAAK,CAAoB;IACjC,sEAAsE;IACtE,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IASpD;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAiB7B;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;;;;;;;;;;;OAYG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;YAUd,UAAU;CAkB3B"}

package/dist/types/core/callback-reporter.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Helpers that route editor warnings and errors through the
+ * public `onWarning` and `onError` callbacks declared on
+ * {@link ImageEditorOptions}.
+ *
+ * ## Owned contracts
+ *
+ * - When the editor reports a recoverable warning
+ *   through `onWarning`, the editor SHALL call the callback with
+ *   `(error, message)` and SHALL catch and log any callback exception
+ *   without changing editor state.
+ * - When the editor reports an error through
+ *   `onError`, the editor SHALL call the callback with `(error, message)`
+ *   and SHALL catch and log any callback exception without masking the
+ *   original editor error.
+ *
+ * The argument order `(error, message)` is part of the public surface and
+ * is also enforced by the `ImageEditorOptions` type.
+ *
+ * ## Why a dedicated module
+ *
+ * Callback isolation is owned here rather than by the operation guard or
+ * the orchestrator. Co-locating warning/error reporting gives every
+ * pipeline a single, side-effect-light helper to call when something goes
+ * wrong.
+ *
+ * ## Non-goals
+ *
+ * - The helpers do NOT throw or rethrow. Callers that need to reject a
+ *   promise with the original error should do so explicitly *after*
+ *   `reportError(...)` returns. This keeps the "callback failure must not
+ *   mask the original editor error" invariant
+ *   trivially satisfied.
+ * - The helpers do NOT mutate editor state. They only invoke the
+ *   user-supplied callback and, on callback exception, write a single
+ *   diagnostic line to `console.warn` / `console.error`.
+ *
+ * The module is intentionally NOT re-exported from `src/index.ts`
+ * (only `ImageEditor`, `isMaskObject`, and the
+ * documented public types are root-exported).
+ *
+ * @module
+ */
+import type { ResolvedOptions } from './public-types.js';
+/**
+ * Minimum slice of {@link ResolvedOptions} required to dispatch a warning.
+ * Accepting a structural sub-type lets pipeline modules pass either the
+ * full `ResolvedOptions` reference or a focused stub (used in unit tests).
+ */
+export type WarningCallbackHost = Pick<ResolvedOptions, 'onWarning'>;
+/**
+ * Minimum slice of {@link ResolvedOptions} required to dispatch an error.
+ *
+ * @see WarningCallbackHost
+ */
+export type ErrorCallbackHost = Pick<ResolvedOptions, 'onError'>;
+/**
+ * Report a recoverable warning to the consumer's `onWarning` callback, if
+ * one was supplied.
+ *
+ * The callback is invoked with the public `(error, message)` argument
+ * order. The original `error` value is forwarded
+ * unchanged — primitives, plain objects, and `Error` instances all flow
+ * through verbatim so consumers can introspect them with `instanceof`.
+ *
+ * If the callback itself throws, the exception is caught and logged with
+ * `console.warn`. The helper never throws and never returns a value, so
+ * callers can chain it before continuing recovery without a `try`/`catch`
+ * of their own.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await tryDownsample(...);
+ * } catch (error) {
+ *   reportWarning(this.options, error, 'Downsample fell back to source format.');
+ *   // continue with the un-downsampled image — no rethrow
+ * }
+ * ```
+ *
+ * @param options - Object exposing the resolved `onWarning` callback. May be
+ *   {@link ResolvedOptions} directly or any structural sub-type
+ *   ({@link WarningCallbackHost}).
+ * @param error - The original error value. Forwarded as the first callback argument.
+ *   Accepts `unknown` because rejected promises and thrown values are not
+ *   guaranteed to be `Error` instances.
+ * @param message - Human-readable description of what happened. Forwarded as the second
+ *   callback argument.
+ */
+export declare function reportWarning(options: WarningCallbackHost, error: unknown, message: string): void;
+/**
+ * Report an error to the consumer's `onError` callback, if one was
+ * supplied.
+ *
+ * The callback is invoked with the public `(error, message)` argument
+ * order. Like {@link reportWarning}, this helper never
+ * throws — callbacks that throw are caught and logged with
+ * `console.error`.
+ *
+ * The "do not mask the original editor error" half is
+ * a contract on the *caller*: pipelines that intend to reject a promise
+ * (or rethrow) with the original `error` MUST do so themselves *after*
+ * this helper returns. By keeping reporting and rethrow separate, a
+ * faulty `onError` callback cannot replace the original error with the
+ * callback's own exception in the consumer's promise chain.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await loadFabricImage(dataUrl);
+ * } catch (error) {
+ *   reportError(this.options, error, `Image load failed: ${describe(error)}`);
+ *   throw error; // original error is preserved on the consumer's promise
+ * }
+ * ```
+ *
+ * @param options - Object exposing the resolved `onError` callback. May be
+ *   {@link ResolvedOptions} directly or any structural sub-type
+ *   ({@link ErrorCallbackHost}).
+ * @param error - The original error value. Forwarded as the first callback argument.
+ * @param message - Human-readable description of what happened. Forwarded as the second
+ *   callback argument.
+ */
+export declare function reportError(options: ErrorCallbackHost, error: unknown, message: string): void;
+//# sourceMappingURL=callback-reporter.d.ts.map

package/dist/types/core/callback-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-reporter.d.ts","sourceRoot":"","sources":["../../../src/core/callback-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;AAErE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAgBjG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAc7F"}

package/dist/types/core/default-options.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Resolves user-supplied {@link ImageEditorOptions} into the
+ * runtime {@link ResolvedOptions} object used by the editor.
+ *
+ * Behavior is defined by the documented option-resolution rules: every
+ * required option falls back to a default, nested `label.textOptions` and
+ * `crop` values merge with their defaults, callback values normalize to a
+ * function or `null`, unknown top-level keys are ignored, top-level scalar
+ * values remain internally mutable for controlled updates such as
+ * `setLayoutMode()`, and returned nested config objects are frozen.
+ *
+ * @module
+ */
+import type { ImageEditorOptions, LabelConfig, ResolvedCropConfig, ResolvedOptions } from './public-types.js';
+/**
+ * Documented defaults for every top-level option except the nested
+ * {@link LabelConfig} and {@link CropConfig} configs, which are owned by
+ * {@link DEFAULT_LABEL} and {@link DEFAULT_CROP} respectively.
+ *
+ * Values are the runtime defaults used when callers omit an option.
+ * Nested label and crop defaults are carried by {@link DEFAULT_LABEL} and
+ * {@link DEFAULT_CROP}.
+ */
+export declare const DEFAULT_OPTIONS: Omit<ResolvedOptions, 'label' | 'crop'>;
+/**
+ * Default {@link LabelConfig}. Consumers can override `getText`, supply a
+ * `create` factory, or provide partial `textOptions` — unspecified keys fall
+ * back to {@link DEFAULT_LABEL_TEXT_OPTIONS}.
+ */
+export declare const DEFAULT_LABEL: LabelConfig;
+/**
+ * Default {@link CropConfig}.
+ */
+export declare const DEFAULT_CROP: ResolvedCropConfig;
+/**
+ * Resolves a partial {@link ImageEditorOptions} into a fully populated
+ * {@link ResolvedOptions} object.
+ *
+ * Behavior matrix:
+ *  - Every top-level key is taken from `input` when supplied, else from
+ *    {@link DEFAULT_OPTIONS}.
+ *  - `label.textOptions` is deep-merged with {@link DEFAULT_LABEL_TEXT_OPTIONS}
+ *    so user keys override defaults and unspecified keys remain.
+ *  - `crop.*` is shallow-merged with {@link DEFAULT_CROP} so each field falls
+ *    back to its documented default when unspecified.
+ *  - Callback values are normalized: function values are kept, anything
+ *    else becomes `null`.
+ *  - Unknown top-level keys are silently dropped.
+ *  - The returned `label` and `crop` references are frozen so that mutating
+ *    `input.label`, `input.label.textOptions`, or `input.crop` after the call
+ *    cannot affect the live editor.
+ *
+ * @param input - Optional partial options object. Defaults to `{}`.
+ */
+export declare function resolveOptions(input?: ImageEditorOptions | null): ResolvedOptions;
+//# sourceMappingURL=default-options.d.ts.map

package/dist/types/core/default-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-options.d.ts","sourceRoot":"","sources":["../../../src/core/default-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAGR,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,eAAe,EAClB,MAAM,mBAAmB,CAAC;AAI3B;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,GAAG,MAAM,CAgEnE,CAAC;AAmBF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,WAG3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,kBAS1B,CAAC;AAwHF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,eAAe,CAqNjF"}

package/dist/types/core/errors.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Typed error classes raised by the editor pipelines (load,
+ * downsample, merge, crop, export).
+ *
+ * All errors that may surface to consumers extend {@link Error} directly so
+ * callers can discriminate via `instanceof` or `error.name` checks. The
+ * hierarchy is intentionally flat — there is no shared `ImageEditorError`
+ * base class — to keep `name`/message contracts independent per pipeline
+ * and to keep name/message contracts independent per pipeline.
+ *
+ * These classes are internal to the package and are NOT re-exported from
+ * `src/index.ts`. Consumers see them via promise rejections from public
+ * methods (e.g. `loadImage.catch(error =>...)`) and should branch on
+ * `error.name` or `instanceof` for fine-grained handling.
+ *
+ * @module
+ */
+/**
+ * Raised by `fabric/fabric-adapter.ts` when neither constructor argument
+ * provides a Fabric module and `globalThis.fabric` is also absent. The
+ * editor logs a single descriptive `console.error` and makes `init` and
+ * `loadImage` no-ops that resolve to `undefined`.
+ *
+ * Surfaces to consumer as: a single `console.error`; subsequent public
+ * methods are guarded by the adapter's `isFabricLoaded === false` flag.
+ *
+ */
+export declare class FabricUnavailableError extends Error {
+    readonly name = "FabricUnavailableError";
+    constructor(message?: string);
+}
+/**
+ * Raised by `image/image-loader.ts` when the internal `decodeImageElement`
+ * helper rejects (the `<img>` `onerror` fires while decoding the data URL).
+ *
+ * Surfaces to consumer as: rejection of the `loadImage` promise. The
+ * editor restores every field captured in the rollback bundle before
+ * rejecting, so `loadImage` is observably atomic.
+ *
+ */
+export declare class ImageDecodeError extends Error {
+    readonly name = "ImageDecodeError";
+    /** Original error or `ErrorEvent` from the `<img>` element, if any. */
+    readonly originalError: unknown;
+    constructor(message?: string, originalError?: unknown);
+}
+/**
+ * Raised by `utils/timeout.ts` after `imageLoadTimeoutMs` (default 30000)
+ * elapses on either the decode step or the `FabricImage.fromURL` step of
+ * `loadImage`. The error message includes both the elapsed milliseconds
+ * and the label of the step that timed out, so consumers and logs can
+ * tell which phase stalled.
+ *
+ * Surfaces to consumer as: rejection of the `loadImage` promise after
+ * the rollback bundle has been replayed.
+ *
+ */
+export declare class ImageLoadTimeoutError extends Error {
+    readonly name = "ImageLoadTimeoutError";
+    /** Step label, e.g. `'image decode'` or `'FabricImage.fromURL'`. */
+    readonly label: string;
+    /** Elapsed milliseconds at the time the timer fired. */
+    readonly elapsedMs: number;
+    constructor(label: string, elapsedMs: number);
+}
+/**
+ * Raised by `image/image-resampler.ts` when the offscreen canvas required
+ * for downsampling cannot obtain a 2D rendering context (i.e.
+ * `OffscreenCanvas.getContext('2d')` or the fallback `<canvas>.getContext`
+ * returns `null`).
+ *
+ * Surfaces to consumer as: rejection of the `loadImage` promise. The
+ * Transactional_Load rollback runs before the rejection.
+ *
+ */
+export declare class DownsampleError extends Error {
+    readonly name = "DownsampleError";
+    /** Original error, if any. Usually `null`. */
+    readonly originalError: unknown;
+    constructor(message?: string, originalError?: unknown);
+}
+/**
+ * Raised by `export/export-service.ts.mergeMasks` when the in-memory render
+ * or any post-merge step fails. The pre-merge snapshot is restored before
+ * the rejection.
+ *
+ * Surfaces to consumer as: rejection of the `mergeMasks` promise.
+ *
+ */
+export declare class MergeMasksError extends Error {
+    readonly name = "MergeMasksError";
+    /** Original error thrown during the merge pipeline. */
+    readonly originalError: unknown;
+    constructor(message?: string, originalError?: unknown);
+}
+/**
+ * Raised by `crop/crop-controller.ts.applyCrop` on any failure during the
+ * crop pipeline (crop computation, cropped-image load via the loader, or
+ * any post-merge step). The pre-crop snapshot is restored, the
+ * `CropSession` is dropped, and crop-specific Fabric handlers are detached
+ * before the rejection.
+ *
+ * Surfaces to consumer as: rejection of the `applyCrop` promise.
+ *
+ */
+export declare class CropApplyError extends Error {
+    readonly name = "CropApplyError";
+    /** Original error thrown during the crop pipeline. */
+    readonly originalError: unknown;
+    constructor(message?: string, originalError?: unknown);
+}
+/**
+ * Raised by `export/export-service.ts.exportImageFile` when
+ * `isImageLoaded` is `false`. A console warning naming the missing image
+ * is emitted alongside the rejection.
+ *
+ * Note: `exportImageBase64` and `downloadImage` do NOT raise this error —
+ * they resolve to `''` or no-op respectively, and emit the same warning.
+ *
+ * Surfaces to consumer as: rejection of the `exportImageFile` promise.
+ *
+ */
+export declare class ExportNotReadyError extends Error {
+    readonly name = "ExportNotReadyError";
+    /** Name of the export operation that was attempted. */
+    readonly operation: string;
+    constructor(operation?: string);
+}
+/**
+ * Raised by export helpers when an image is loaded but the export pipeline
+ * cannot produce a valid output, for example because the computed image
+ * region is empty or the rendered data URL cannot be decoded into bytes.
+ *
+ * Surfaces to consumer as: rejection of the relevant export promise.
+ */
+export declare class ExportError extends Error {
+    readonly name = "ExportError";
+    /** Original error thrown during the export pipeline. */
+    readonly originalError: unknown;
+    constructor(message?: string, originalError?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAkBH;;;;;;;;;GASG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC7C,SAAyB,IAAI,4BAA4B;gBAGrD,OAAO,SAA6H;CAK3I;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACvC,SAAyB,IAAI,sBAAsB;IAEnD,uEAAuE;IACvE,SAAgB,aAAa,EAAE,OAAO,CAAC;gBAE3B,OAAO,SAAqC,EAAE,aAAa,GAAE,OAAc;CAK1F;AAED;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC5C,SAAyB,IAAI,2BAA2B;IAExD,oEAAoE;IACpE,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,wDAAwD;IACxD,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEtB,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM/C;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACtC,SAAyB,IAAI,qBAAqB;IAElD,8CAA8C;IAC9C,SAAgB,aAAa,EAAE,OAAO,CAAC;gBAGnC,OAAO,SAAoD,EAC3D,aAAa,GAAE,OAAc;CAMpC;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACtC,SAAyB,IAAI,qBAAqB;IAElD,uDAAuD;IACvD,SAAgB,aAAa,EAAE,OAAO,CAAC;gBAE3B,OAAO,SAA0C,EAAE,aAAa,GAAE,OAAc;CAK/F;AAED;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACrC,SAAyB,IAAI,oBAAoB;IAEjD,sDAAsD;IACtD,SAAgB,aAAa,EAAE,OAAO,CAAC;gBAE3B,OAAO,SAAuC,EAAE,aAAa,GAAE,OAAc;CAK5F;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC1C,SAAyB,IAAI,yBAAyB;IAEtD,uDAAuD;IACvD,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEtB,SAAS,SAAoB;CAK5C;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAClC,SAAyB,IAAI,iBAAiB;IAE9C,wDAAwD;IACxD,SAAgB,aAAa,EAAE,OAAO,CAAC;gBAE3B,OAAO,SAA4B,EAAE,aAAa,GAAE,OAAc;CAKjF"}

package/dist/types/core/operation-guard.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Animation-state guard used by the {@link ImageEditor} facade
+ * to block stateful public operations while an animation is in
+ * progress, and to centralize the dispose flag that in-flight
+ * animation callbacks check before touching the canvas.
+ *
+ * ## Owned contracts
+ *
+ * - While `isAnimating` is `true`, the editor SHALL
+ *   reject calls to `mergeMasks`, `exportImageBase64`, `exportImageFile`,
+ *   `downloadImage`, `enterCropMode`, `applyCrop`, `removeAllMasks`, and
+ *   `loadImage` with a clear error or no-op (documented per method).
+ * - `undo` and `redo` are NOT routed through this
+ *   guard; they are serialized by the `AnimationQueue` instead. Callers that
+ *   would otherwise be blocked by the `isAnimating` flag still flow
+ *   through `assertNotAnimating`; `undo` / `redo` skip the guard
+ *   entirely (see `image-editor.ts`).
+ * - When an animation completes or fails, the
+ *   editor SHALL set `isAnimating` to `false` *before* resolving or
+ *   rejecting the returned promise. The {@link OperationGuard.runAnimation}
+ *   helper enforces this by clearing the flag inside a `finally` block.
+ *
+ * ## Why the guard owns the dispose flag too
+ *
+ * In-flight animation callbacks check `isDisposed` before touching the
+ * canvas. Co-locating the disposed flag here keeps both checks behind a
+ * single small object so the Fabric animation wrapper
+ * (`fabric/fabric-animation.ts`) and the dispose path (`image-editor.ts`)
+ * can share state without a circular dependency on the orchestrator.
+ *
+ * The guard does NOT log on rejection — the contract is "no state mutation
+ * and a documented no-op shape per method"; logging is left to the caller
+ * so each public method can choose between resolved-promise, empty-string,
+ * or rejection-with-typed-error per the documented per-method documentation.
+ *
+ * The guard is imported by `image-editor.ts` and
+ * `fabric/fabric-animation.ts`. It is intentionally NOT re-exported from
+ * `src/index.ts`.
+ *
+ * @module
+ */
+/**
+ * Read-only view of the guard state. Useful for diagnostics, property
+ * tests, and `fabric/fabric-animation.ts` callbacks that only need to
+ * observe (never mutate) the flags.
+ */
+export interface AnimationState {
+    /** `true` while a queued animation is bracketed by begin/endAnimation. */
+    readonly isAnimating: boolean;
+    /** `true` after {@link OperationGuard.markDisposed} has been called. */
+    readonly isDisposed: boolean;
+}
+export type OperationToken = symbol;
+/**
+ * Tracks the editor's `isAnimating` and `isDisposed` flags and exposes the
+ * single-line `assertNotAnimating` gate used by every guarded public
+ * method.
+ *
+ * Lifetime is one-per-editor — a fresh `OperationGuard` is created in the
+ * `ImageEditor` constructor and disposed alongside the canvas.
+ *
+ */
+export declare class OperationGuard {
+    private isAnimationActive;
+    private isDisposedFlag;
+    private isLoadingActive;
+    private currentOperationName;
+    private currentOperationToken;
+    /**
+     * Returns `true` while an animation block is open (between
+     * {@link beginAnimation} and {@link endAnimation}).
+     *
+     * Public surface for the orchestrator's `isAnimating` check used by
+     * the per-method guards.
+     */
+    isAnimating(): boolean;
+    /**
+     * Returns `true` once {@link markDisposed} has been called. Animation
+     * callbacks consult this before touching the canvas.
+     */
+    isDisposed(): boolean;
+    /**
+     * Returns `true` while a transactional image load is in progress.
+     */
+    isLoading(): boolean;
+    /**
+     * Returns the currently active non-load operation name, if any.
+     */
+    activeOperationName(): string | null;
+    /**
+     * Returns `true` while any guard-owned busy state is active.
+     */
+    isBusy(): boolean;
+    /**
+     * Begin an animation block. Subsequent calls to {@link assertNotAnimating}
+     * will throw until {@link endAnimation} runs.
+     *
+     * Prefer {@link runAnimation} over manually calling begin/end so the
+     * "isAnimating false before resolve/reject" invariant is enforced by
+     * `try/finally` rather than caller discipline.
+     */
+    beginAnimation(): void;
+    /**
+     * End an animation block and clear the `isAnimating` flag. Always called
+     * from a `finally` so the flag is `false` before the surrounding promise
+     * resolves or rejects.
+     */
+    endAnimation(): void;
+    /**
+     * Mark the editor disposed. After this call:
+     *
+     * - `isDisposed` returns `true`.
+     * - `isAnimating` is forced to `false` so any post-dispose `finally`
+     *   that runs after the animation queue is cleared still leaves the
+     *   guard in a quiescent state.
+     *
+     * Idempotent: calling twice is a no-op.
+     */
+    markDisposed(): void;
+    /**
+     * Mark a transactional image load as active.
+     */
+    beginLoading(): void;
+    /**
+     * Clear the transactional image load flag.
+     */
+    endLoading(): void;
+    /**
+     * Mark a longer-running public operation active and return the token
+     * that authorizes its internal calls.
+     */
+    beginBusyOperation(operationName: string): OperationToken;
+    /**
+     * Clear the active operation only when the matching token finishes.
+     */
+    endBusyOperation(token: OperationToken | null | undefined): void;
+    /**
+     * Returns `true` when `token` belongs to the currently active operation.
+     */
+    isOwnOperation(token: OperationToken | null | undefined): boolean;
+    /**
+     * Run an async function inside a `beginAnimation` / `endAnimation`
+     * bracket. The bracket is released in a `finally` so the
+     * `isAnimating === false` invariant holds even
+     * when `animationTask` rejects.
+     *
+     * Used by the orchestrator's transform pipeline (`scaleImage`,
+     * `rotateImage`, `resetImageTransform`) when wrapping a single Fabric
+     * animation. The animation queue (`animation/animation-queue.ts`)
+     * enforces FIFO ordering across multiple wrappers, so callers do not
+     * need to coordinate begin/end across queue entries.
+     *
+     * @typeParam T - Resolved value of the wrapped animation.
+     * @param animationTask - Animation function returning a promise.
+     * @returns      The promise returned by `animationTask`, with begin/end bracketing
+     *               applied around its lifetime.
+     */
+    runAnimation<T>(animationTask: () => Promise<T>): Promise<T>;
+    /**
+     * Throw if an animation is currently in progress. Used as the gate for
+     * the operations enumerated: `mergeMasks`,
+     * `exportImageBase64`, `exportImageFile`, `downloadImage`,
+     * `enterCropMode`, `applyCrop`, `removeAllMasks`, and `loadImage`.
+     *
+     * `undo` and `redo` are NOT routed through this gate;
+     * they go through the animation queue, which serializes them after any
+     * in-flight animation entry.
+     *
+     * The thrown error is intentionally a plain `Error` rather than one of
+     * the typed classes from `core/errors.ts`; some public methods translate
+     * the failure into a documented no-op shape before it reaches the
+     * consumer.
+     *
+     * @param operationLabel - Short, user-facing operation name (e.g. `'mergeMasks'`).
+     *   Embedded in the error message verbatim.
+     * @throws Error when {@link isAnimating} returns `true`.
+     */
+    assertNotAnimating(operationLabel: string): void;
+    /**
+     * Throw when a public operation would overlap loading, animation, or
+     * another active transaction. Internal calls may pass their active
+     * operation token to proceed.
+     */
+    assertIdleForOperation(operationLabel: string, token?: OperationToken | null): void;
+    /**
+     * Throw when an animation cannot even be queued because a load or
+     * transaction is currently active. Existing animations are intentionally
+     * left to the animation queue.
+     */
+    assertCanQueueAnimation(operationLabel: string, token?: OperationToken | null): void;
+}
+//# sourceMappingURL=operation-guard.d.ts.map

package/dist/types/core/operation-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-guard.d.ts","sourceRoot":"","sources":["../../../src/core/operation-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC;;;;;;;;GAQG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,oBAAoB,CAAuB;IACnD,OAAO,CAAC,qBAAqB,CAA+B;IAE5D;;;;;;OAMG;IACH,WAAW,IAAI,OAAO;IAItB;;;OAGG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAIpC;;OAEG;IACH,MAAM,IAAI,OAAO;IAMjB;;;;;;;OAOG;IACH,cAAc,IAAI,IAAI;IAItB;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAIpB;;;;;;;;;OASG;IACH,YAAY,IAAI,IAAI;IAQpB;;OAEG;IACH,YAAY,IAAI,IAAI;IAIpB;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;;OAGG;IACH,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc;IAOzD;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAOhE;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;IAIjE;;;;;;;;;;;;;;;;OAgBG;IACG,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IASlE;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAQhD;;;;OAIG;IACH,sBAAsB,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI;IAuBnF;;;;OAIG;IACH,uBAAuB,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI;CAiBvF"}