@bensitu/image-editor 1.3.1 → 1.4.1

package/src/image-editor.js

@@ -1,13 +1,14 @@
 /**
  * @file image-editor.js
  * @module image-editor
- * @version 1.3.1
+ * @version 1.4.1
  * @author Ben Situ
  * @license MIT
  * @description Lightweight canvas-based image editor with masking/transform/export support.
  */
 
 let fabric = null;
+const INTERNAL_OPERATION_TOKEN = Symbol('ImageEditorInternalOperation');
 
 /**
  * Returns the ambient global scope used to discover a globally loaded Fabric.js namespace.
@@ -196,6 +197,8 @@ function ensureFabric() {
                 downsampleMaxWidth: 4000,
                 downsampleMaxHeight: 3000,
                 downsampleQuality: 0.92,
+                preserveSourceFormat: true,
+                downsampleMimeType: null,
                 imageLoadTimeoutMs: 30000,
 
                 exportMultiplier: 1,
@@ -250,11 +253,16 @@ function ensureFabric() {
             this.currentRotation = 0;
             this.maskCounter = 0;
             this.isAnimating = false;
+            this._isLoading = false;
+            this._activeOperationName = null;
+            this._activeOperationToken = null;
             this.elements = {};
             this.isImageLoadedToCanvas = false;
             this.maxHistorySize = 50;
 
             this._handlersByElementKey = {};
+            this._elementCache = {};
+            this._elementOriginalPointerEvents = new Map();
 
             this._lastMask = null;
             this._lastMaskInitialLeft = null;
@@ -267,8 +275,14 @@ function ensureFabric() {
             this._cropHandlers = [];
             this._cropPrevEvented = null;
             this._prevSelectionSetting = undefined;
-            this._containerOriginalOverflow = undefined;
+            this._containerOriginalOverflow = null;
+            this._lastContainerViewportSize = null;
+            this._canvasElementOriginalStyle = null;
+            this._visibilityStateByElement = new WeakMap();
             this._scrollbarSizeCache = null;
+            this._activeAnimationRejectors = new Set();
+            this._disposed = false;
+            this._initialized = false;
 
             this.onImageLoaded = typeof options.onImageLoaded === 'function' ? options.onImageLoaded : null;
 
@@ -341,6 +355,20 @@ function ensureFabric() {
          */
         init(idMap = {}) {
             if (!this._fabricLoaded) return;
+            if (this._initialized || this.canvas) this.dispose();
+            this._disposed = false;
+            this._initialized = true;
+            this.animationQueue = new AnimationQueue();
+            this.historyManager = new HistoryManager(this.maxHistorySize);
+            this._visibilityStateByElement = new WeakMap();
+            this._activeAnimationRejectors = new Set();
+            this._isLoading = false;
+            this._activeOperationName = null;
+            this._activeOperationToken = null;
+            this._elementOriginalPointerEvents = new Map();
+            this._containerOriginalOverflow = null;
+            this._lastContainerViewportSize = null;
+            this._canvasElementOriginalStyle = null;
 
             const defaults = {
                 canvas: 'fabricCanvas',
@@ -369,6 +397,7 @@ function ensureFabric() {
             };
 
             this.elements = { ...defaults, ...idMap };
+            this._elementCache = {};
 
             this._initCanvas();
             this._bindEvents();
@@ -413,19 +442,25 @@ function ensureFabric() {
          * @private
          */
         _initCanvas() {
-            const canvasElement = document.getElementById(this.elements.canvas);
+            const canvasElement = this._getElement('canvas');
             if (!canvasElement) throw new Error('Canvas is not found: ' + this.elements.canvas);
             this.canvasElement = canvasElement;
+            this._canvasElementOriginalStyle = {
+                display: canvasElement.style.display || '',
+                width: canvasElement.style.width || '',
+                height: canvasElement.style.height || '',
+                maxWidth: canvasElement.style.maxWidth || ''
+            };
 
             // Decide which element acts as the viewport for size fallback and scrolling.
             if (this.elements.canvasContainer) {
-                const containerElement = document.getElementById(this.elements.canvasContainer);
+                const containerElement = this._getElement('canvasContainer');
                 this.containerElement = containerElement || canvasElement.parentElement;
             } else {
                 this.containerElement = canvasElement.parentElement;
             }
 
-            this.placeholderElement = document.getElementById(this.elements.imgPlaceholder) || null;
+            this.placeholderElement = this._getElement('imgPlaceholder') || null;
 
             // Prefer a measured container size when it is available.
             let initialWidth = this.options.canvasWidth;
@@ -436,6 +471,11 @@ function ensureFabric() {
                 if (containerWidth > 0 && containerHeight > 0) {
                     initialWidth = containerWidth;
                     initialHeight = containerHeight;
+
+                    this._lastContainerViewportSize = {
+                        width: containerWidth,
+                        height: containerHeight
+                    };
                 }
             }
 
@@ -460,6 +500,24 @@ function ensureFabric() {
             this.canvasElement.style.display = 'block';
         }
 
+        /**
+         * Returns a configured DOM element and caches lookups for hot UI paths.
+         *
+         * @param {string} key - Key in the configured element map.
+         * @returns {HTMLElement|null} The configured element, or null when missing.
+         * @private
+         */
+        _getElement(key) {
+            const id = this.elements && this.elements[key];
+            if (!id) return null;
+            if (this._elementCache && Object.prototype.hasOwnProperty.call(this._elementCache, key)) {
+                return this._elementCache[key];
+            }
+            const element = document.getElementById(id);
+            if (this._elementCache) this._elementCache[key] = element || null;
+            return element || null;
+        }
+
         /**
          * Records a history entry after Fabric finishes modifying one or more masks.
          *
@@ -504,9 +562,7 @@ function ensureFabric() {
          */
         _syncContainerOverflow(options = {}) {
             if (!this.containerElement || !this.containerElement.style) return;
-            if (this._containerOriginalOverflow === undefined) {
-                this._containerOriginalOverflow = this.containerElement.style.overflow || '';
-            }
+            this._captureContainerOverflowState();
 
             const shouldPreserveScroll = options.preserveScroll === true;
             if (this.options.coverImageToCanvas) {
@@ -522,10 +578,33 @@ function ensureFabric() {
                     this.containerElement.scrollTop = 0;
                 }
             } else {
-                this.containerElement.style.overflow = this._containerOriginalOverflow;
+                this._restoreContainerOverflowState();
             }
         }
 
+        _captureContainerOverflowState() {
+            if (!this.containerElement || !this.containerElement.style || this._containerOriginalOverflow) return;
+            this._containerOriginalOverflow = {
+                overflow: this.containerElement.style.overflow || '',
+                overflowX: this.containerElement.style.overflowX || '',
+                overflowY: this.containerElement.style.overflowY || ''
+            };
+        }
+
+        _restoreContainerOverflowState() {
+            if (!this.containerElement || !this.containerElement.style || !this._containerOriginalOverflow) return;
+            this.containerElement.style.overflow = this._containerOriginalOverflow.overflow;
+            this.containerElement.style.overflowX = this._containerOriginalOverflow.overflowX;
+            this.containerElement.style.overflowY = this._containerOriginalOverflow.overflowY;
+        }
+
+        _restoreContainerOverflowSnapshot(snapshot) {
+            if (!this.containerElement || !this.containerElement.style || !snapshot) return;
+            this.containerElement.style.overflow = snapshot.overflow || '';
+            this.containerElement.style.overflowX = snapshot.overflowX || '';
+            this.containerElement.style.overflowY = snapshot.overflowY || '';
+        }
+
         /** 
          * DOM / UI bindings
          * @private
@@ -533,54 +612,61 @@ function ensureFabric() {
         _bindEvents() {
             // Click anywhere on the upload area opens the native file dialog
             this._bindIfExists('uploadArea', 'click', () => {
-                const uploadAreaElement = document.getElementById(this.elements.uploadArea);
+                const uploadAreaElement = this._getElement('uploadArea');
                 if (this._isElementDisabled(uploadAreaElement)) return;
-                document.getElementById(this.elements.imageInput)?.click();
+                this._getElement('imageInput')?.click();
             });
             // File-input change
             this._bindIfExists('imageInput', 'change', (event) => {
                 const file = event.target.files && event.target.files[0];
-                if (file) this._loadImageFile(file);
+                if (file) {
+                    this._loadImageFile(file)
+                        .catch(error => this._reportError('Image file could not be loaded', error))
+                        .finally(() => {
+                            event.target.value = '';
+                        });
+                }
             });
             // Zoom & reset
-            this._bindIfExists('zoomInBtn', 'click', () => this.scaleImage(this.currentScale + this.options.scaleStep));
-            this._bindIfExists('zoomOutBtn', 'click', () => this.scaleImage(this.currentScale - this.options.scaleStep));
-            this._bindIfExists('resetBtn', 'click', () => { this.resetImageTransform(); });
+            this._bindIfExists('zoomInBtn', 'click', () => this.scaleImage(this.currentScale + this.options.scaleStep).catch(error => this._reportError('scaleImage failed', error)));
+            this._bindIfExists('zoomOutBtn', 'click', () => this.scaleImage(this.currentScale - this.options.scaleStep).catch(error => this._reportError('scaleImage failed', error)));
+            this._bindIfExists('resetBtn', 'click', () => { this.resetImageTransform().catch(error => this._reportError('resetImageTransform failed', error)); });
             // Mask management
             this._bindIfExists('addMaskBtn', 'click', () => this.createMask());
             this._bindIfExists('removeMaskBtn', 'click', () => this.removeSelectedMask());
             this._bindIfExists('removeAllMasksBtn', 'click', () => this.removeAllMasks());
             // Merge + download
-            this._bindIfExists('mergeBtn', 'click', () => this.mergeMasks());
+            this._bindIfExists('mergeBtn', 'click', () => this.mergeMasks().catch(error => this._reportError('merge error', error)));
             this._bindIfExists('downloadBtn', 'click', () => this.downloadImage());
             // Undo + Redo
-            this._bindIfExists('undoBtn', 'click', () => this.undo());
-            this._bindIfExists('redoBtn', 'click', () => this.redo());
+            this._bindIfExists('undoBtn', 'click', () => this.undo().catch(error => this._reportError('undo failed', error)));
+            this._bindIfExists('redoBtn', 'click', () => this.redo().catch(error => this._reportError('redo failed', error)));
 
             // Rotation buttons (step can be overridden by two input fields)
             this._bindIfExists('rotateLeftBtn', 'click', () => {
-                const rotationInputElement = document.getElementById(this.elements.rotationLeftInput);
+                const rotationInputElement = this._getElement('rotationLeftInput');
                 let step = this.options.rotationStep;
                 if (rotationInputElement) {
                     const parsedStep = parseFloat(rotationInputElement.value);
                     if (!isNaN(parsedStep)) step = parsedStep;
                 }
-                this.rotateImage(this.currentRotation - step);
+                this.rotateImage(this.currentRotation - step).catch(error => this._reportError('rotateImage failed', error));
             });
             this._bindIfExists('rotateRightBtn', 'click', () => {
-                const rotationInputElement = document.getElementById(this.elements.rotationRightInput);
+                const rotationInputElement = this._getElement('rotationRightInput');
                 let step = this.options.rotationStep;
                 if (rotationInputElement) {
                     const parsedStep = parseFloat(rotationInputElement.value);
                     if (!isNaN(parsedStep)) step = parsedStep;
                 }
-                this.rotateImage(this.currentRotation + step);
+                this.rotateImage(this.currentRotation + step).catch(error => this._reportError('rotateImage failed', error));
             });
 
             // Crop bindings (optional: bound only if element IDs exist in elements)
             this._bindIfExists('cropBtn', 'click', () => this.enterCropMode());
             this._bindIfExists('applyCropBtn', 'click', () => { this.applyCrop().catch(error => this._reportError('applyCrop failed', error)); });
             this._bindIfExists('cancelCropBtn', 'click', () => this.cancelCrop());
+            this._bindIfExists('maskList', 'click', (event) => this._handleMaskListClick(event));
         }
 
         /**
@@ -592,7 +678,7 @@ function ensureFabric() {
          * @private
          */
         _bindIfExists(key, eventName, handler) {
-            const element = document.getElementById(this.elements[key]);
+            const element = this._getElement(key);
             if (element) {
                 element.addEventListener(eventName, handler);
                 this._handlersByElementKey = this._handlersByElementKey || {};
@@ -605,14 +691,37 @@ function ensureFabric() {
          * Reads an image File as a data URL and loads it into the Fabric canvas.
          *
          * @param {File} file - Image file selected by the user.
+         * @returns {Promise<void>} Resolves after the selected file is loaded.
          * @private
          */
         _loadImageFile(file) {
-            if (!file || !file.type.startsWith('image/')) return;
-            const reader = new FileReader();
-            reader.onload = (event) => this.loadImage(event.target.result);
-            reader.onerror = (event) => { this._reportError('Image file could not be read', event); };
-            reader.readAsDataURL(file);
+            if (!this._isSupportedImageFile(file)) {
+                const error = new Error('Selected file is not a supported image');
+                this._reportError('Selected file is not a supported image', error);
+                return Promise.reject(error);
+            }
+
+            return new Promise((resolve, reject) => {
+                const reader = new FileReader();
+                reader.onload = (event) => {
+                    this.loadImage(event.target.result)
+                        .then(resolve)
+                        .catch(reject);
+                };
+                reader.onerror = (event) => {
+                    const error = new Error('Image file could not be read');
+                    this._reportError('Image file could not be read', event);
+                    reject(error);
+                };
+                reader.readAsDataURL(file);
+            });
+        }
+
+        _isSupportedImageFile(file) {
+            if (!file) return false;
+            if (typeof file.type === 'string' && file.type.startsWith('image/')) return true;
+            const fileName = String(file.name || '');
+            return /\.(avif|bmp|gif|jpe?g|png|webp)$/i.test(fileName);
         }
 
         /**
@@ -645,120 +754,118 @@ function ensureFabric() {
          */
         async loadImage(imageBase64, options = {}) {
             if (!this._fabricLoaded) return;
-            if (!this.canvas) return;
+            if (!this.canvas || this._disposed) return;
             if (!imageBase64 || typeof imageBase64 !== 'string' || !imageBase64.startsWith('data:image/')) return;
+            this._assertIdleForOperation('loadImage', options);
 
+            this._isLoading = true;
+            this._updateUI();
             this._warnOnImageLayoutOptionConflict();
-            this._setPlaceholderVisible(false);
-            this._syncContainerOverflow({ preserveScroll: options.preserveScroll === true });
-
-            const imageElement = await this._createImageElement(imageBase64);
-
-            let loadSource = imageBase64;
-            if (this.options.downsampleOnLoad) {
-                const shouldResize =
-                    imageElement.naturalWidth > this.options.downsampleMaxWidth ||
-                    imageElement.naturalHeight > this.options.downsampleMaxHeight;
-                if (shouldResize) {
-                    const ratio = Math.min(
-                        this.options.downsampleMaxWidth / imageElement.naturalWidth,
-                        this.options.downsampleMaxHeight / imageElement.naturalHeight
-                    );
-                    const targetWidth = Math.round(imageElement.naturalWidth * ratio);
-                    const targetHeight = Math.round(imageElement.naturalHeight * ratio);
-                    loadSource = this._resampleImageToDataURL(imageElement, targetWidth, targetHeight, this.options.downsampleQuality);
+            const transaction = this._captureLoadImageTransaction();
+
+            try {
+                const imageElement = await this._createImageElement(imageBase64);
+                if (this._disposed || !this.canvas) throw new Error('Editor was disposed while loading image');
+
+                let loadSource = imageBase64;
+                if (this.options.downsampleOnLoad) {
+                    const shouldResize =
+                        imageElement.naturalWidth > this.options.downsampleMaxWidth ||
+                        imageElement.naturalHeight > this.options.downsampleMaxHeight;
+                    if (shouldResize) {
+                        const ratio = Math.min(
+                            this.options.downsampleMaxWidth / imageElement.naturalWidth,
+                            this.options.downsampleMaxHeight / imageElement.naturalHeight
+                        );
+                        const targetWidth = Math.round(imageElement.naturalWidth * ratio);
+                        const targetHeight = Math.round(imageElement.naturalHeight * ratio);
+                        loadSource = this._resampleImageToDataURL(
+                            imageElement,
+                            targetWidth,
+                            targetHeight,
+                            this._normalizeQuality(this.options.downsampleQuality),
+                            imageBase64
+                        );
+                    }
                 }
-            }
 
-            // Create fabric.Image from URL
-            return new Promise((resolve, reject) => {
-                fabric.Image.fromURL(loadSource, (fabricImage) => {
-                    try {
-                        if (!fabricImage) throw new Error('Image could not be loaded');
-
-                        this.canvas.discardActiveObject();
-                        this._hideAllMaskLabels();
-                        this.canvas.clear();
-                        this.canvas.setBackgroundColor(this.options.backgroundColor, this.canvas.renderAll.bind(this.canvas));
-
-                        fabricImage.set({ originX: 'left', originY: 'top', selectable: false, evented: false });
-
-                        const imageWidth = fabricImage.width;
-                        const imageHeight = fabricImage.height;
-
-                        const viewport = this._getContainerViewportSize();
-                        const minWidth = viewport.width;
-                        const minHeight = viewport.height;
-
-                        if (this.options.fitImageToCanvas) {
-                            // Fit into the visible viewport, shrinking only when the image is larger.
-                            const canvasWidth = Math.max(1, minWidth - 1);
-                            const canvasHeight = Math.max(1, minHeight - 1);
-                            this._setCanvasSizeInt(canvasWidth, canvasHeight);
-                            const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
-                            fabricImage.set({ left: 0, top: 0 });
-                            fabricImage.scale(fitScale);
-                            this.baseImageScale = fabricImage.scaleX || 1;
-                        } else if (this.options.coverImageToCanvas) {
-                            const layout = this._calculateCoverCanvasLayout(imageWidth, imageHeight);
-                            this._setCanvasSizeInt(layout.canvasWidth, layout.canvasHeight);
-                            fabricImage.set({ left: 0, top: 0 });
-                            fabricImage.scale(layout.scale);
-                            this.baseImageScale = fabricImage.scaleX || 1;
-                        } else if (this.options.expandCanvasToImage) {
-                            // Expand canvas so that it fully contains the image
-                            const canvasWidth = Math.max(minWidth, Math.floor(imageWidth));
-                            const canvasHeight = Math.max(minHeight, Math.floor(imageHeight));
-                            this._setCanvasSizeInt(canvasWidth, canvasHeight);
-                            fabricImage.set({ left: 0, top: 0 });
-                            fabricImage.scale(1);
-                            this.baseImageScale = 1;
-                        } else {
-                            // Keep existing canvas size and center the image
-                            const canvasWidth = Math.max(this.options.canvasWidth, minWidth);
-                            const canvasHeight = Math.max(this.options.canvasHeight, minHeight);
-                            this._setCanvasSizeInt(canvasWidth, canvasHeight);
-                            const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
-                            fabricImage.set({ left: 0, top: 0 });
-                            fabricImage.scale(fitScale);
-                            this.baseImageScale = fabricImage.scaleX || 1;
-                        }
-                        // Put the image onto the canvas
-                        this.originalImage = fabricImage;
-                        this.canvas.add(fabricImage);
-                        this.canvas.sendToBack(fabricImage);
-
-                        // Reset mask placement memory
-                        this._lastMask = null;
-                        this._lastMaskInitialLeft = null;
-                        this._lastMaskInitialTop = null;
-                        this._lastMaskInitialWidth = null;
-
-                        this.maskCounter = 0;
-                        this.currentScale = 1;
-                        this.currentRotation = 0;
-
-                        this._updateInputs();
-                        this._updateMaskList();
-                        this.isImageLoadedToCanvas = true;
-                        this._updateUI();
-                        this.canvas.renderAll();
-                        try {
-                            this._lastSnapshot = this._serializeCanvasState();
-                        } catch (error) {
-                            this._reportWarning('loadImage: failed to capture initial canvas snapshot', error);
-                        }
+                const fabricImage = await this._createFabricImageFromURL(loadSource);
+                if (this._disposed || !this.canvas) throw new Error('Editor was disposed while loading image');
+                
+                this.canvas.discardActiveObject();
+                this._hideAllMaskLabels();
+                this.canvas.clear();
+                this.canvas.setBackgroundColor(this.options.backgroundColor, this.canvas.renderAll.bind(this.canvas));
+
+                fabricImage.set({ originX: 'left', originY: 'top', selectable: false, evented: false });
+                this._setPlaceholderVisible(false);
+                this._syncContainerOverflow({ preserveScroll: options.preserveScroll === true });
+
+                const imageWidth = fabricImage.width;
+                const imageHeight = fabricImage.height;
+
+                const viewport = this._getContainerViewportSize();
+                const minWidth = viewport.width;
+                const minHeight = viewport.height;
+
+                if (this.options.fitImageToCanvas) {
+                    const canvasWidth = Math.max(1, minWidth - 1);
+                    const canvasHeight = Math.max(1, minHeight - 1);
+                    this._setCanvasSizeInt(canvasWidth, canvasHeight);
+                    const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
+                    fabricImage.set({ left: 0, top: 0 });
+                    fabricImage.scale(fitScale);
+                    this.baseImageScale = fabricImage.scaleX || 1;
+                } else if (this.options.coverImageToCanvas) {
+                    const layout = this._calculateCoverCanvasLayout(imageWidth, imageHeight);
+                    this._setCanvasSizeInt(layout.canvasWidth, layout.canvasHeight);
+                    fabricImage.set({ left: 0, top: 0 });
+                    fabricImage.scale(layout.scale);
+                    this.baseImageScale = fabricImage.scaleX || 1;
+                } else if (this.options.expandCanvasToImage) {
+                    const canvasWidth = Math.max(minWidth, Math.floor(imageWidth));
+                    const canvasHeight = Math.max(minHeight, Math.floor(imageHeight));
+                    this._setCanvasSizeInt(canvasWidth, canvasHeight);
+                    fabricImage.set({ left: 0, top: 0 });
+                    fabricImage.scale(1);
+                    this.baseImageScale = 1;
+                } else {
+                    const canvasWidth = Math.max(this.options.canvasWidth, minWidth);
+                    const canvasHeight = Math.max(this.options.canvasHeight, minHeight);
+                    this._setCanvasSizeInt(canvasWidth, canvasHeight);
+                    const fitScale = Math.min(canvasWidth / imageWidth, canvasHeight / imageHeight, 1);
+                    fabricImage.set({ left: 0, top: 0 });
+                    fabricImage.scale(fitScale);
+                    this.baseImageScale = fabricImage.scaleX || 1;
+                }
 
-                        if (typeof this.onImageLoaded === 'function') {
-                            this.onImageLoaded();
-                        }
+                this.originalImage = fabricImage;
+                this.canvas.add(fabricImage);
+                this.canvas.sendToBack(fabricImage);
 
-                        resolve();
-                    } catch (error) {
-                        reject(error);
-                    }
-                }, { crossOrigin: 'anonymous' });
-            });
+                this._clearMaskPlacementMemory();
+                if (options.resetMaskCounter !== false) this.maskCounter = 0;
+                this.currentScale = 1;
+                this.currentRotation = 0;
+
+                // this._setPlaceholderVisible(false);
+                this._updateInputs();
+                this._updateMaskList();
+                this.isImageLoadedToCanvas = true;
+                this._updateUI();
+                this.canvas.renderAll();
+                this._lastSnapshot = this._captureCanvasStateOrThrow('loadImage');
+
+                if (typeof this.onImageLoaded === 'function') {
+                    this.onImageLoaded();
+                }
+            } catch (error) {
+                await this._rollbackLoadImageTransaction(transaction);
+                throw error;
+            } finally {
+                this._isLoading = false;
+                if (!this._disposed && this.canvas) this._updateUI();
+            }
         }
 
         /**
@@ -810,24 +917,167 @@ function ensureFabric() {
             });
         }
 
+        _createFabricImageFromURL(dataUrl, timeoutMs = this.options.imageLoadTimeoutMs) {
+            return new Promise((resolve, reject) => {
+                const safeTimeoutMs = this._getSafeTimeoutMs(timeoutMs);
+                let isSettled = false;
+                let timerId;
+                const settle = (callback) => {
+                    if (isSettled) return;
+                    isSettled = true;
+                    clearTimeout(timerId);
+                    callback();
+                };
+
+                timerId = setTimeout(() => {
+                    settle(() => reject(new Error('Fabric image load timed out')));
+                }, safeTimeoutMs);
+
+                try {
+                    fabric.Image.fromURL(dataUrl, (fabricImage) => {
+                        settle(() => {
+                            if (!fabricImage) {
+                                reject(new Error('Image could not be loaded'));
+                                return;
+                            }
+                            resolve(fabricImage);
+                        });
+                    }, { crossOrigin: 'anonymous' });
+                } catch (error) {
+                    settle(() => reject(error));
+                }
+            });
+        }
+
+        _getSafeTimeoutMs(timeoutMs) {
+            const safeTimeoutMs = Number(timeoutMs);
+            return Number.isFinite(safeTimeoutMs) && safeTimeoutMs > 0 ? safeTimeoutMs : 30000;
+        }
+
+        _captureLoadImageTransaction() {
+            return {
+                canvasState: this._serializeCanvasState(),
+                originalImage: this.originalImage,
+                baseImageScale: this.baseImageScale,
+                currentScale: this.currentScale,
+                currentRotation: this.currentRotation,
+                maskCounter: this.maskCounter,
+                isImageLoadedToCanvas: this.isImageLoadedToCanvas,
+                lastSnapshot: this._lastSnapshot,
+                lastMask: this._lastMask,
+                lastMaskInitialLeft: this._lastMaskInitialLeft,
+                lastMaskInitialTop: this._lastMaskInitialTop,
+                lastMaskInitialWidth: this._lastMaskInitialWidth,
+                containerOverflow: this.containerElement && this.containerElement.style ? {
+                    overflow: this.containerElement.style.overflow || '',
+                    overflowX: this.containerElement.style.overflowX || '',
+                    overflowY: this.containerElement.style.overflowY || ''
+                } : null,
+                scrollLeft: this.containerElement ? this.containerElement.scrollLeft : 0,
+                scrollTop: this.containerElement ? this.containerElement.scrollTop : 0,
+                placeholderVisibility: this._captureElementVisibility(this.placeholderElement),
+                canvasVisibility: this._captureElementVisibility(this._getCanvasVisibilityElement())
+            };
+        }
+
+        async _rollbackLoadImageTransaction(transaction) {
+            if (!transaction || !this.canvas || this._disposed) return;
+            let didRestoreCanvasState = false;
+            try {
+                if (transaction.canvasState) {
+                    await this.loadFromState(transaction.canvasState);
+                    didRestoreCanvasState = true;
+                }
+            } catch (error) {
+                this._lastMask = null;
+                this._reportError('loadImage rollback failed', error);
+            }
+
+            this.baseImageScale = transaction.baseImageScale;
+            this.currentScale = transaction.currentScale;
+            this.currentRotation = transaction.currentRotation;
+            this.maskCounter = transaction.maskCounter;
+            this.isImageLoadedToCanvas = transaction.isImageLoadedToCanvas;
+            this._lastSnapshot = transaction.lastSnapshot;
+            if (didRestoreCanvasState) {
+                this._restoreLastMaskReference(transaction.lastMask);
+            } else {
+                this._lastMask = null;
+            }
+            this._lastMaskInitialLeft = transaction.lastMaskInitialLeft;
+            this._lastMaskInitialTop = transaction.lastMaskInitialTop;
+            this._lastMaskInitialWidth = transaction.lastMaskInitialWidth;
+            this._restoreElementVisibility(this.placeholderElement, transaction.placeholderVisibility);
+            this._restoreElementVisibility(this._getCanvasVisibilityElement(), transaction.canvasVisibility);
+            if (this.containerElement) {
+                this.containerElement.scrollLeft = transaction.scrollLeft;
+                this.containerElement.scrollTop = transaction.scrollTop;
+                this._restoreContainerOverflowSnapshot(transaction.containerOverflow);
+            }
+            this._updateInputs();
+            this._updateMaskList();
+            this._updateUI();
+            if (this.canvas) this.canvas.renderAll();
+        }
+
+        _restoreLastMaskReference(previousLastMask) {
+            if (!this.canvas) {
+                this._lastMask = null;
+                return;
+            }
+
+            const masks = this.canvas.getObjects().filter(object => object.maskId);
+            const previousMaskId = previousLastMask && previousLastMask.maskId;
+            this._lastMask = masks.find(mask => mask.maskId === previousMaskId) || masks[masks.length - 1] || null;
+            if (!this._lastMask) {
+                this._lastMaskInitialLeft = null;
+                this._lastMaskInitialTop = null;
+                this._lastMaskInitialWidth = null;
+            }
+        }
+
         /**
-         * Resamples the given image element to a new width and height and returns the result as a JPEG data URL.
+         * Resamples the given image element to a new width and height and returns the result as a data URL.
          * 
          * @param {HTMLImageElement} imageElement - The image element to resample.
          * @param {number} targetWidth - Target width (in pixels) for the resampled image.
          * @param {number} targetHeight - Target height (in pixels) for the resampled image.
-         * @param {number} [quality=0.92] - JPEG image quality between 0 and 1 (optional, default 0.92).
-         * @returns {string} A data URL representing the resampled image as JPEG.
+         * @param {number} [quality=0.92] - Image quality between 0 and 1 for lossy formats.
+         * @param {string|null} [sourceDataUrl=null] - Source data URL used to preserve alpha-capable formats.
+         * @returns {string} A data URL representing the resampled image.
          * @private
          */
-        _resampleImageToDataURL(imageElement, targetWidth, targetHeight, quality = 0.92) {
+        _resampleImageToDataURL(imageElement, targetWidth, targetHeight, quality = 0.92, sourceDataUrl = null) {
             const offscreenCanvas = document.createElement('canvas');
             offscreenCanvas.width = targetWidth;
             offscreenCanvas.height = targetHeight;
             const context = offscreenCanvas.getContext('2d');
             if (!context) throw new Error('2D canvas context is unavailable');
             context.drawImage(imageElement, 0, 0, imageElement.naturalWidth, imageElement.naturalHeight, 0, 0, targetWidth, targetHeight);
-            return offscreenCanvas.toDataURL('image/jpeg', quality);
+            return offscreenCanvas.toDataURL(this._getDownsampleMimeType(sourceDataUrl), quality);
+        }
+
+        _getDataUrlMimeType(dataUrl) {
+            const match = String(dataUrl || '').match(/^data:([^;,]+)[;,]/i);
+            return match ? match[1].toLowerCase() : '';
+        }
+
+        _getDownsampleMimeType(sourceDataUrl) {
+            if (this.options.downsampleMimeType) {
+                const requestedFormat = this._normalizeImageFormat(this.options.downsampleMimeType);
+                return `image/${requestedFormat}`;
+            }
+            const sourceMimeType = this._getDataUrlMimeType(sourceDataUrl);
+            if (this.options.preserveSourceFormat !== false && (sourceMimeType === 'image/png' || sourceMimeType === 'image/webp')) {
+                return sourceMimeType;
+            }
+            return 'image/jpeg';
+        }
+
+        _captureCanvasStateOrThrow(context) {
+            const snapshot = this._serializeCanvasState();
+            if (!snapshot) throw new Error(`${context}: canvas state is unavailable`);
+            return snapshot;
         }
 
         /** 
@@ -849,7 +1099,6 @@ function ensureFabric() {
             if (this.canvasElement) {
                 this.canvasElement.style.width = integerWidth + 'px';
                 this.canvasElement.style.height = integerHeight + 'px';
-                this.canvasElement.style.maxWidth = 'none';
             }
         }
 
@@ -868,8 +1117,14 @@ function ensureFabric() {
                 };
             }
 
-            let width = Math.max(1, Math.floor(this.containerElement.clientWidth || this.options.canvasWidth || 1));
-            let height = Math.max(1, Math.floor(this.containerElement.clientHeight || this.options.canvasHeight || 1));
+            const measuredWidth = Math.floor(this.containerElement.clientWidth || 0);
+            const measuredHeight = Math.floor(this.containerElement.clientHeight || 0);
+            let width = Math.max(1, measuredWidth || this._lastContainerViewportSize?.width || this.options.canvasWidth || 1);
+            let height = Math.max(1, measuredHeight || this._lastContainerViewportSize?.height || this.options.canvasHeight || 1);
+
+            if (measuredWidth > 0 && measuredHeight > 0) {
+                this._lastContainerViewportSize = { width: measuredWidth, height: measuredHeight };
+            }
 
             if (this._hasFixedContainerScrollbars()) {
                 return { width, height };
@@ -1106,7 +1361,11 @@ function ensureFabric() {
                     maskStyleBackups.push(backup);
                     mask.set(stylePatch);
                 });
-                return callback();
+                const result = callback();
+                if (result && typeof result.then === 'function') {
+                    throw new Error('_withNormalizedMaskStyles callback must be synchronous');
+                }
+                return result;
             } finally {
                 maskStyleBackups.forEach(backup => {
                     try {
@@ -1178,9 +1437,15 @@ function ensureFabric() {
          * @returns {number} A finite quality value between 0 and 1.
          * @private
          */
-        _normalizeQuality(quality) {
+        _normalizeQuality(quality, fallback = undefined) {
+            const fallbackQuality = fallback == null ? this.options.downsampleQuality : fallback;
+            const numericFallback = fallbackQuality == null ? NaN : Number(fallbackQuality);
+            const safeFallback = Number.isFinite(numericFallback)
+                ? Math.max(0, Math.min(1, numericFallback))
+                : 0.92;
+            if (quality == null) return safeFallback;
             const numericQuality = Number(quality);
-            if (!Number.isFinite(numericQuality)) return this.options.downsampleQuality ?? 0.92;
+            if (!Number.isFinite(numericQuality)) return safeFallback;
             return Math.max(0, Math.min(1, numericQuality));
         }
 
@@ -1235,65 +1500,74 @@ function ensureFabric() {
             };
         }
 
-        /**
-         * Crops an image data URL to a source region using an offscreen canvas.
-         *
-         * @param {string} dataUrl - Source image data URL.
-         * @param {number} sourceX - Source region x coordinate.
-         * @param {number} sourceY - Source region y coordinate.
-         * @param {number} sourceWidth - Source region width.
-         * @param {number} sourceHeight - Source region height.
-         * @param {number} multiplier - Export multiplier already applied to the source data URL.
-         * @param {'jpeg'|'png'|'webp'} [format='jpeg'] - Output image format.
-         * @param {number} [quality=0.92] - Output image quality for lossy formats.
-         * @returns {Promise<string>} Resolves with the cropped image data URL.
-         * @private
-         */
-        async _cropDataUrl(dataUrl, sourceX, sourceY, sourceWidth, sourceHeight, multiplier, format = 'jpeg', quality = 0.92) {
-            return new Promise((resolve, reject) => {
-                const imageElement = new Image();
-                let isSettled = false;
-                const timeoutMs = Number(this.options.imageLoadTimeoutMs);
-                const safeTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 30000;
-                let timerId;
-                const settle = (callback) => {
-                    if (isSettled) return;
-                    isSettled = true;
-                    clearTimeout(timerId);
-                    imageElement.onload = null;
-                    imageElement.onerror = null;
-                    callback();
-                };
-                timerId = setTimeout(() => {
-                    settle(() => reject(new Error('Image crop load timed out')));
-                    try { imageElement.src = ''; } catch (error) { void error; }
-                }, safeTimeoutMs);
-                imageElement.onload = () => {
-                    try {
-                        const safeMultiplier = Math.max(1, Number(multiplier) || 1);
-                        const scaledSourceX = Math.round(sourceX * safeMultiplier);
-                        const scaledSourceY = Math.round(sourceY * safeMultiplier);
-                        const scaledSourceWidth = Math.max(1, Math.round(sourceWidth * safeMultiplier));
-                        const scaledSourceHeight = Math.max(1, Math.round(sourceHeight * safeMultiplier));
-                        const offscreenCanvas = document.createElement('canvas');
-                        offscreenCanvas.width = scaledSourceWidth;
-                        offscreenCanvas.height = scaledSourceHeight;
-                        const context = offscreenCanvas.getContext('2d');
-                        if (!context) throw new Error('2D canvas context is unavailable');
-
-                        context.drawImage(imageElement, scaledSourceX, scaledSourceY, scaledSourceWidth, scaledSourceHeight, 0, 0, scaledSourceWidth, scaledSourceHeight);
-                        settle(() => resolve(offscreenCanvas.toDataURL(`image/${format}`, quality)));
-                    } catch (error) {
-                        settle(() => reject(error));
-                    }
-                };
-                imageElement.onerror = (error) => settle(() => reject(error));
-                imageElement.src = dataUrl;
-            });
+        _hasFractionalCanvasEdge(value) {
+            const numericValue = Number(value);
+            if (!Number.isFinite(numericValue)) return false;
+            return Math.abs(numericValue - Math.round(numericValue)) > 0.01;
+        }
+
+        _getPartialExportEdges(bounds) {
+            if (!bounds) return null;
+            const angle = Math.abs((Number(this.originalImage && this.originalImage.angle) || 0) % 90);
+            const isAxisAligned = angle < 0.01 || Math.abs(angle - 90) < 0.01;
+            if (!isAxisAligned) return null;
+
+            return {
+                left: this._hasFractionalCanvasEdge(bounds.left),
+                top: this._hasFractionalCanvasEdge(bounds.top),
+                right: this._hasFractionalCanvasEdge((Number(bounds.left) || 0) + (Number(bounds.width) || 0)),
+                bottom: this._hasFractionalCanvasEdge((Number(bounds.top) || 0) + (Number(bounds.height) || 0))
+            };
+        }
+
+        async _sealPartialTransparentEdges(dataUrl, edges) {
+            if (!edges || !Object.values(edges).some(Boolean)) return dataUrl;
+
+            const imageElement = await this._createImageElement(dataUrl);
+            const width = Math.max(1, imageElement.naturalWidth || imageElement.width || 1);
+            const height = Math.max(1, imageElement.naturalHeight || imageElement.height || 1);
+            const offscreenCanvas = document.createElement('canvas');
+            offscreenCanvas.width = width;
+            offscreenCanvas.height = height;
+            const context = offscreenCanvas.getContext('2d');
+            if (!context) throw new Error('2D canvas context is unavailable');
+            context.drawImage(imageElement, 0, 0, width, height);
+
+            const imageData = context.getImageData(0, 0, width, height);
+            const pixels = imageData.data;
+            const sealPixel = (x, y, fallbackX, fallbackY) => {
+                const index = (y * width + x) * 4;
+                const fallbackIndex = (fallbackY * width + fallbackX) * 4;
+                if (pixels[index + 3] === 0 && pixels[fallbackIndex + 3] > 0) {
+                    pixels[index] = pixels[fallbackIndex];
+                    pixels[index + 1] = pixels[fallbackIndex + 1];
+                    pixels[index + 2] = pixels[fallbackIndex + 2];
+                    pixels[index + 3] = pixels[fallbackIndex + 3];
+                }
+                if (pixels[index + 3] > 0 && pixels[index + 3] < 255) {
+                    pixels[index + 3] = 255;
+                }
+            };
+
+            if (edges.left && width > 1) {
+                for (let y = 0; y < height; y += 1) sealPixel(0, y, 1, y);
+            }
+            if (edges.right && width > 1) {
+                for (let y = 0; y < height; y += 1) sealPixel(width - 1, y, width - 2, y);
+            }
+            if (edges.top && height > 1) {
+                for (let x = 0; x < width; x += 1) sealPixel(x, 0, x, 1);
+            }
+            if (edges.bottom && height > 1) {
+                for (let x = 0; x < width; x += 1) sealPixel(x, height - 1, x, height - 2);
+            }
+
+            context.putImageData(imageData, 0, 0);
+            return offscreenCanvas.toDataURL('image/png');
         }
 
         /**
-         * Exports the whole Fabric canvas, then crops the requested source region from that export.
+         * Exports a source region directly through Fabric's region export options.
          *
          * @param {Object} region - Canvas source region and export options.
          * @param {number} region.sourceX - Source region x coordinate.
@@ -1303,18 +1577,49 @@ function ensureFabric() {
          * @param {number} [region.multiplier=1] - Export multiplier.
          * @param {number} [region.quality=0.92] - Output image quality for lossy formats.
          * @param {'jpeg'|'png'|'webp'} [region.format='jpeg'] - Output image format.
+         * @param {Object|null} [region.sealPartialEdges=null] - Fractional canvas edges whose alpha should be sealed.
          * @returns {Promise<string>} Resolves with an image data URL for the cropped region.
          * @private
          */
-        async _exportCanvasRegionToDataURL({ sourceX, sourceY, sourceWidth, sourceHeight, multiplier = 1, quality = 0.92, format = 'jpeg' }) {
+        async _exportCanvasRegionToDataURL({ sourceX, sourceY, sourceWidth, sourceHeight, multiplier = 1, quality = 0.92, format = 'jpeg', sealPartialEdges = null }) {
             const safeMultiplier = Math.max(1, Number(multiplier) || 1);
-            const fullDataUrl = this.canvas.toDataURL({
-                format,
+            const safeFormat = this._normalizeImageFormat(format);
+            const exportFormat = safeFormat === 'jpeg' ? 'png' : safeFormat;
+            let regionDataUrl = this.canvas.toDataURL({
+                format: exportFormat,
                 quality,
-                multiplier: safeMultiplier
+                multiplier: safeMultiplier,
+                left: sourceX,
+                top: sourceY,
+                width: sourceWidth,
+                height: sourceHeight
             });
 
-            return this._cropDataUrl(fullDataUrl, sourceX, sourceY, sourceWidth, sourceHeight, safeMultiplier, format, quality);
+            regionDataUrl = await this._sealPartialTransparentEdges(regionDataUrl, sealPartialEdges);
+            if (safeFormat !== 'jpeg') return regionDataUrl;
+            return this._convertDataUrlToOpaqueJpeg(regionDataUrl, quality);
+        }
+
+        async _convertDataUrlToOpaqueJpeg(dataUrl, quality = 0.92) {
+            const imageElement = await this._createImageElement(dataUrl);
+            const width = Math.max(1, imageElement.naturalWidth || imageElement.width || 1);
+            const height = Math.max(1, imageElement.naturalHeight || imageElement.height || 1);
+            const offscreenCanvas = document.createElement('canvas');
+            offscreenCanvas.width = width;
+            offscreenCanvas.height = height;
+            const context = offscreenCanvas.getContext('2d');
+            if (!context) throw new Error('2D canvas context is unavailable');
+            context.fillStyle = this._getJpegBackgroundColor();
+            context.fillRect(0, 0, width, height);
+            context.drawImage(imageElement, 0, 0, width, height);
+            return offscreenCanvas.toDataURL('image/jpeg', this._normalizeQuality(quality));
+        }
+
+        _getJpegBackgroundColor() {
+            const backgroundColor = String(this.options.backgroundColor || '').trim();
+            if (!backgroundColor || backgroundColor === 'transparent') return '#ffffff';
+            if (/^rgba\([^)]*,\s*0(?:\.0+)?\s*\)$/i.test(backgroundColor)) return '#ffffff';
+            return backgroundColor;
         }
 
         /** 
@@ -1328,12 +1633,41 @@ function ensureFabric() {
         _getObjectTopLeftPoint(fabricObject) {
             if (!fabricObject) return { x: 0, y: 0 };
             fabricObject.setCoords();
-            const coords = typeof fabricObject.getCoords === 'function' ? fabricObject.getCoords() : null;
-            if (coords && coords.length) return coords[0];
             const boundingRect = fabricObject.getBoundingRect(true, true);
             return { x: boundingRect.left, y: boundingRect.top };
         }
 
+        _getObjectCoordinateTopLeftPoint(fabricObject) {
+            if (!fabricObject) return { x: 0, y: 0 };
+            fabricObject.setCoords();
+            const coords = typeof fabricObject.getCoords === 'function' ? fabricObject.getCoords() : null;
+            if (coords && coords.length) return coords[0];
+            return this._getObjectTopLeftPoint(fabricObject);
+        }
+
+        _getObjectOriginPoint(fabricObject, originX, originY) {
+            if (!fabricObject) return { x: 0, y: 0 };
+            if (typeof fabricObject.getPointByOrigin === 'function') {
+                return fabricObject.getPointByOrigin(originX, originY);
+            }
+            return this._getObjectTopLeftPoint(fabricObject);
+        }
+
+        _translateObjectByCanvasOffset(fabricObject, deltaX, deltaY) {
+            if (!fabricObject) return;
+            if (typeof fabricObject.getCenterPoint === 'function' && typeof fabricObject.setPositionByOrigin === 'function') {
+                const center = fabricObject.getCenterPoint();
+                const nextCenter = new fabric.Point(center.x + deltaX, center.y + deltaY);
+                fabricObject.setPositionByOrigin(nextCenter, 'center', 'center');
+            } else {
+                fabricObject.set({
+                    left: (fabricObject.left || 0) + deltaX,
+                    top: (fabricObject.top || 0) + deltaY
+                });
+            }
+            fabricObject.setCoords();
+        }
+
         /**
          * Sets the object's origin at the specified origin point, keeping a reference point fixed in position.
          * 
@@ -1402,8 +1736,10 @@ function ensureFabric() {
         _expandCanvasToFitObjects(fabricObjects, padding = 10) {
             if (!this.canvas || !Array.isArray(fabricObjects) || !fabricObjects.length || !this._shouldResizeCanvasToContentBounds()) return;
             try {
-                let requiredWidth = this.canvas.getWidth();
-                let requiredHeight = this.canvas.getHeight();
+                const currentWidth = this.canvas.getWidth();
+                const currentHeight = this.canvas.getHeight();
+                let requiredWidth = currentWidth;
+                let requiredHeight = currentHeight;
                 fabricObjects.forEach(fabricObject => {
                     if (!fabricObject) return;
                     if (typeof fabricObject.setCoords === 'function') fabricObject.setCoords();
@@ -1411,11 +1747,23 @@ function ensureFabric() {
                     requiredWidth = Math.max(requiredWidth, Math.ceil(boundingRect.left + boundingRect.width + padding));
                     requiredHeight = Math.max(requiredHeight, Math.ceil(boundingRect.top + boundingRect.height + padding));
                 });
-                const minWidth = this.containerElement ? Math.floor(this.containerElement.clientWidth || 0) : 0;
-                const minHeight = this.containerElement ? Math.floor(this.containerElement.clientHeight || 0) : 0;
-                const newWidth = Math.max(this.canvas.getWidth(), minWidth, requiredWidth);
-                const newHeight = Math.max(this.canvas.getHeight(), minHeight, requiredHeight);
-                if (newWidth !== this.canvas.getWidth() || newHeight !== this.canvas.getHeight()) {
+                const shouldUseScrollSafeViewport = this.options.fitImageToCanvas || this.options.coverImageToCanvas;
+
+                let minWidth = 0;
+                let minHeight = 0;
+                if (shouldUseScrollSafeViewport) {
+                    const viewport = this._getContainerViewportSize();
+                    const safetyMargin = this._getScrollSafetyMargin();
+
+                    minWidth = Math.max(1, viewport.width - safetyMargin);
+                    minHeight = Math.max(1, viewport.height - safetyMargin);
+                } else if (this.containerElement) {
+                    minWidth = Math.floor(this.containerElement.clientWidth || 0);
+                    minHeight = Math.floor(this.containerElement.clientHeight || 0);
+                }
+                const newWidth = Math.max(currentWidth, minWidth, requiredWidth);
+                const newHeight = Math.max(currentHeight, minHeight, requiredHeight);
+                if (newWidth !== currentWidth  || newHeight !== currentHeight) {
                     this._setCanvasSizeInt(newWidth, newHeight);
                 }
             } catch (error) {
@@ -1443,7 +1791,131 @@ function ensureFabric() {
          * @public
          */
         scaleImage(factor, options = {}) {
-            return this.animationQueue.add(() => this._scaleImageImpl(factor, options));
+            try {
+                this._assertCanQueueAnimation('scaleImage', options);
+            } catch (error) {
+                return Promise.reject(error);
+            }
+            return this.animationQueue.add(() => this._scaleImageImpl(factor, options))
+                .finally(() => {
+                    if (!this._disposed && this.canvas) this._updateUI();
+                });
+        }
+
+        _getInternalOperationToken(options) {
+            return options && options[INTERNAL_OPERATION_TOKEN];
+        }
+
+        _isOwnInternalOperation(options) {
+            const token = this._getInternalOperationToken(options);
+            return !!token && token === this._activeOperationToken;
+        }
+
+        _beginBusyOperation(operationName) {
+            const token = Symbol(operationName);
+            this._activeOperationName = operationName;
+            this._activeOperationToken = token;
+            this._updateUI();
+            return token;
+        }
+
+        _endBusyOperation(token) {
+            if (token && token === this._activeOperationToken) {
+                this._activeOperationName = null;
+                this._activeOperationToken = null;
+                this._updateUI();
+            }
+        }
+
+        _withInternalOperationOptions(token, options = {}) {
+            return {
+                ...options,
+                [INTERNAL_OPERATION_TOKEN]: token
+            };
+        }
+
+        _assertEditorAvailable(operationName) {
+            if (this._disposed || !this.canvas) throw new Error(`${operationName} cannot run after the editor has been disposed`);
+        }
+
+        _assertIdleForOperation(operationName, options = {}) {
+            this._assertEditorAvailable(operationName);
+            const isOwnInternalOperation = this._isOwnInternalOperation(options);
+            if (this.isAnimating || (this.animationQueue && this.animationQueue.isBusy())) {
+                throw new Error(`${operationName} cannot run while an animation is running`);
+            }
+            if (this._isLoading && !isOwnInternalOperation) {
+                throw new Error(`${operationName} cannot run while an image is loading`);
+            }
+            if (this._activeOperationToken && !isOwnInternalOperation) {
+                throw new Error(`${operationName} cannot run while ${this._activeOperationName || 'another operation'} is running`);
+            }
+        }
+
+        _assertCanQueueAnimation(operationName, options = {}) {
+            this._assertEditorAvailable(operationName);
+            if (this._isLoading && !this._isOwnInternalOperation(options)) {
+                throw new Error(`${operationName} cannot run while an image is loading`);
+            }
+            if (this._activeOperationToken && !this._isOwnInternalOperation(options)) {
+                throw new Error(`${operationName} cannot run while ${this._activeOperationName || 'another operation'} is running`);
+            }
+        }
+
+        _canMutateNow(operationName, options = {}) {
+            try {
+                this._assertIdleForOperation(operationName, options);
+                return true;
+            } catch (error) {
+                this._reportError(`${operationName} blocked`, error);
+                return false;
+            }
+        }
+
+        _rejectActiveAnimations(reason) {
+            const error = reason instanceof Error ? reason : new Error(String(reason || 'Animation cancelled'));
+            this._activeAnimationRejectors.forEach(reject => {
+                try { reject(error); } catch (rejectError) { void rejectError; }
+            });
+            this._activeAnimationRejectors.clear();
+        }
+
+        _animateFabricProperty(fabricObject, property, value) {
+            return new Promise((resolve, reject) => {
+                if (this._disposed || !this.canvas || !fabricObject) {
+                    reject(new Error('Animation cannot start after editor disposal'));
+                    return;
+                }
+
+                let isSettled = false;
+                const duration = Math.max(0, Number(this.options.animationDuration) || 0);
+                const timeoutMs = Math.max(1000, duration + 1000);
+                let timerId;
+                const settle = (callback) => {
+                    if (isSettled) return;
+                    isSettled = true;
+                    clearTimeout(timerId);
+                    this._activeAnimationRejectors.delete(reject);
+                    callback();
+                };
+
+                this._activeAnimationRejectors.add(reject);
+                timerId = setTimeout(() => {
+                    settle(() => reject(new Error(`Animation timed out while changing ${property}`)));
+                }, timeoutMs);
+
+                try {
+                    fabricObject.animate(property, value, {
+                        duration,
+                        onChange: () => {
+                            if (!this._disposed && this.canvas) this.canvas.renderAll();
+                        },
+                        onComplete: () => settle(resolve)
+                    });
+                } catch (error) {
+                    settle(() => reject(error));
+                }
+            });
         }
 
         /** 
@@ -1453,37 +1925,29 @@ function ensureFabric() {
          * @returns {Promise<void>} Promise that resolves once the scaling animation finishes.
          * @private
          */
-        _scaleImageImpl(factor, options = {}) {
-            if (!this.originalImage) return Promise.resolve();
-            if (this.isAnimating) return Promise.resolve();
+        async _scaleImageImpl(factor, options = {}) {
+            if (!this.originalImage || this._disposed) return;
+            if (this.isAnimating) return;
             const saveHistory = options.saveHistory !== false;
-            factor = Math.max(this.options.minScale, Math.min(this.options.maxScale, factor));
-            this.currentScale = factor;
-            this.isAnimating = true;
-            this._updateUI();
+            let didStartAnimation = false;
+            try {
+                factor = Math.max(this.options.minScale, Math.min(this.options.maxScale, factor));
+                this.currentScale = factor;
+                this.isAnimating = true;
+                didStartAnimation = true;
+                this._updateUI();
 
-            const targetScale = this.baseImageScale * factor;
+                const targetScale = this.baseImageScale * factor;
 
-            // Scale around current top-left (recompute)
-            const topLeft = this._getObjectTopLeftPoint(this.originalImage);
-            this._setObjectOriginKeepingPosition(this.originalImage, 'left', 'top', topLeft);
+                const topLeft = this._getObjectTopLeftPoint(this.originalImage);
+                this._setObjectOriginKeepingPosition(this.originalImage, 'left', 'top', topLeft);
 
-            const scaleXAnimation = new Promise((resolve) => {
-                this.originalImage.animate('scaleX', targetScale, {
-                    duration: this.options.animationDuration,
-                    onChange: this.canvas.renderAll.bind(this.canvas),
-                    onComplete: resolve
-                });
-            });
-            const scaleYAnimation = new Promise((resolve) => {
-                this.originalImage.animate('scaleY', targetScale, {
-                    duration: this.options.animationDuration,
-                    onChange: this.canvas.renderAll.bind(this.canvas),
-                    onComplete: resolve
-                });
-            });
+                await Promise.all([
+                    this._animateFabricProperty(this.originalImage, 'scaleX', targetScale),
+                    this._animateFabricProperty(this.originalImage, 'scaleY', targetScale)
+                ]);
+                if (this._disposed || !this.canvas || !this.originalImage) throw new Error('Editor was disposed during scale animation');
 
-            return Promise.all([scaleXAnimation, scaleYAnimation]).then(() => {
                 this.originalImage.set({ scaleX: targetScale, scaleY: targetScale });
                 this.originalImage.setCoords();
 
@@ -1493,17 +1957,17 @@ function ensureFabric() {
 
                 this._alignObjectBoundingBoxToCanvasTopLeft(this.originalImage);
 
-                // Sync mask labels
                 this.canvas.getObjects().forEach(object => { if (object.maskId) this._syncMaskLabel(object); });
 
-                this.isAnimating = false;
                 this._updateInputs();
-                this._updateUI();
                 if (saveHistory) this.saveState();
-            }).catch(() => {
-                this.isAnimating = false;
-                this._updateUI();
-            });
+            } finally {
+                if (didStartAnimation) {
+                    this.isAnimating = false;
+                    this._updateInputs();
+                    this._updateUI();
+                }
+            }
         }
 
         /** 
@@ -1514,7 +1978,15 @@ function ensureFabric() {
          * @public
          */
         rotateImage(degrees, options = {}) {
-            return this.animationQueue.add(() => this._rotateImageImpl(degrees, options));
+            try {
+                this._assertCanQueueAnimation('rotateImage', options);
+            } catch (error) {
+                return Promise.reject(error);
+            }
+            return this.animationQueue.add(() => this._rotateImageImpl(degrees, options))
+                .finally(() => {
+                    if (!this._disposed && this.canvas) this._updateUI();
+                });
         }
 
         /** 
@@ -1524,27 +1996,29 @@ function ensureFabric() {
          * @returns {Promise<void>} Promise that resolves once the rotation animation finishes.
          * @private
          */
-        _rotateImageImpl(degrees, options = {}) {
-            if (!this.originalImage) return Promise.resolve();
-            if (this.isAnimating) return Promise.resolve();
-            if (isNaN(degrees)) return Promise.resolve();
+        async _rotateImageImpl(degrees, options = {}) {
+            if (!this.originalImage || this._disposed) return;
+            if (this.isAnimating) return;
+            if (isNaN(degrees)) return;
             const saveHistory = options.saveHistory !== false;
-            this.currentRotation = degrees;
-            this.isAnimating = true;
-            this._updateUI();
+            const image = this.originalImage;
+            const previousOriginX = image.originX || 'left';
+            const previousOriginY = image.originY || 'top';
+            const previousOriginPoint = this._getObjectOriginPoint(image, previousOriginX, previousOriginY);
+            let didStartAnimation = false;
+            let didCompleteRotation = false;
+            try {
+                this.currentRotation = degrees;
+                this.isAnimating = true;
+                didStartAnimation = true;
+                this._updateUI();
 
-            const center = this.originalImage.getCenterPoint();
-            this._setObjectOriginKeepingPosition(this.originalImage, 'center', 'center', center);
+                const center = image.getCenterPoint();
+                this._setObjectOriginKeepingPosition(image, 'center', 'center', center);
 
-            const rotationAnimation = new Promise((resolve) => {
-                this.originalImage.animate('angle', degrees, {
-                    duration: this.options.animationDuration,
-                    onChange: this.canvas.renderAll.bind(this.canvas),
-                    onComplete: resolve
-                });
-            });
+                await this._animateFabricProperty(image, 'angle', degrees);
+                if (this._disposed || !this.canvas || !this.originalImage) throw new Error('Editor was disposed during rotation animation');
 
-            return rotationAnimation.then(() => {
                 this.originalImage.set('angle', degrees);
                 this.originalImage.setCoords();
 
@@ -1554,20 +2028,24 @@ function ensureFabric() {
 
                 this._alignObjectBoundingBoxToCanvasTopLeft(this.originalImage);
 
-                const newTopLeft = this._getObjectTopLeftPoint(this.originalImage);
+                const newTopLeft = this._getObjectCoordinateTopLeftPoint(this.originalImage);
                 this._setObjectOriginKeepingPosition(this.originalImage, 'left', 'top', newTopLeft);
 
-                // Sync mask labels
                 this.canvas.getObjects().forEach(object => { if (object.maskId) this._syncMaskLabel(object); });
 
-                this.isAnimating = false;
                 this._updateInputs();
-                this._updateUI();
                 if (saveHistory) this.saveState();
-            }).catch(() => {
-                this.isAnimating = false;
-                this._updateUI();
-            });
+                didCompleteRotation = true;
+            } finally {
+                if (!didCompleteRotation && !this._disposed && image) {
+                    this._setObjectOriginKeepingPosition(image, previousOriginX, previousOriginY, previousOriginPoint);
+                }
+                if (didStartAnimation) {
+                    this.isAnimating = false;
+                    this._updateInputs();
+                    this._updateUI();
+                }
+            }
         }
 
         /**
@@ -1578,15 +2056,23 @@ function ensureFabric() {
          */
         resetImageTransform() {
             if (!this.originalImage) return Promise.resolve();
+            try {
+                this._assertCanQueueAnimation('resetImageTransform');
+            } catch (error) {
+                return Promise.reject(error);
+            }
 
             return this.animationQueue.add(async () => {
-                const before = this._lastSnapshot || this._serializeCanvasState();
+                const before = this._lastSnapshot || this._captureCanvasStateOrThrow('resetImageTransform');
                 await this._scaleImageImpl(1, { saveHistory: false });
                 await this._rotateImageImpl(0, { saveHistory: false });
-                const after = this._serializeCanvasState();
+                const after = this._captureCanvasStateOrThrow('resetImageTransform');
                 this._pushStateTransition(before, after);
+            }).finally(() => {
+                if (!this._disposed && this.canvas) this._updateUI();
             }).catch(error => {
                 this._reportError('resetImageTransform() failed', error);
+                throw error;
             });
         }
 
@@ -1608,17 +2094,35 @@ function ensureFabric() {
          * @public
          */
         loadFromState(serializedState) {
-            if (!serializedState || !this.canvas) return Promise.resolve();
+            if (!serializedState || !this.canvas || this._disposed) return Promise.resolve();
+            if (this._cropMode || this._cropRect) {
+                this._removeCropRect();
+                this._restoreCropObjectState();
+                this._cropMode = false;
+                if (this._prevSelectionSetting !== undefined && this.canvas) {
+                    this.canvas.selection = !!this._prevSelectionSetting;
+                }
+                this._prevSelectionSetting = undefined;
+            }
 
-            return new Promise((resolve) => {
+            return new Promise((resolve, reject) => {
                 try {
                     const state = (typeof serializedState === 'string')
                         ? JSON.parse(serializedState)
                         : serializedState;
                     const editorMetadata = state && state.imageEditorMetadata ? state.imageEditorMetadata : null;
 
-                    this.canvas.loadFromJSON(state, () => {
+                    this.canvas.loadFromJSON(state, async () => {
                         try {
+                            if (this._disposed || !this.canvas) {
+                                reject(new Error('Editor was disposed while loading state'));
+                                return;
+                            }
+                            await this._waitForFabricImagesReady(this.canvas.getObjects());
+                            if (this._disposed || !this.canvas) {
+                                reject(new Error('Editor was disposed while loading state'));
+                                return;
+                            }
                             this._hideAllMaskLabels();
                             const canvasObjects = this.canvas.getObjects();
                             this.originalImage = canvasObjects.find(object => object.type === 'image' && !object.maskId) || null;
@@ -1677,16 +2181,56 @@ function ensureFabric() {
                             this._updatePlaceholderStatus();
                             this._lastSnapshot = this._serializeCanvasState();
                             this._updateUI();
+                            resolve();
                         } catch (callbackError) {
                             this._reportError('loadFromState() failed', callbackError);
-                        } finally {
-                            resolve();
+                            reject(callbackError);
                         }
                     });
 
                 } catch (error) {
                     this._reportError('loadFromState() failed', error);
-                    resolve();
+                    reject(error);
+                }
+            });
+        }
+
+        async _waitForFabricImagesReady(canvasObjects) {
+            const imageObjects = (canvasObjects || []).filter(object => object && object.type === 'image');
+            await Promise.all(imageObjects.map(object => this._waitForImageElementReady(
+                typeof object.getElement === 'function' ? object.getElement() : object._element
+            )));
+        }
+
+        _waitForImageElementReady(imageElement) {
+            if (!imageElement) return Promise.resolve();
+            if (imageElement.complete || imageElement.naturalWidth > 0 || imageElement.width > 0) return Promise.resolve();
+            return new Promise((resolve, reject) => {
+                let isSettled = false;
+                const timerId = setTimeout(() => {
+                    settle(() => reject(new Error('Image load timed out while restoring state')));
+                }, this._getSafeTimeoutMs(this.options.imageLoadTimeoutMs));
+                const settle = (callback) => {
+                    if (isSettled) return;
+                    isSettled = true;
+                    clearTimeout(timerId);
+                    if (typeof imageElement.removeEventListener === 'function') {
+                        imageElement.removeEventListener('load', handleLoad);
+                        imageElement.removeEventListener('error', handleError);
+                    } else {
+                        imageElement.onload = null;
+                        imageElement.onerror = null;
+                    }
+                    callback();
+                };
+                const handleLoad = () => settle(resolve);
+                const handleError = (error) => settle(() => reject(error));
+                if (typeof imageElement.addEventListener === 'function') {
+                    imageElement.addEventListener('load', handleLoad, { once: true });
+                    imageElement.addEventListener('error', handleError, { once: true });
+                } else {
+                    imageElement.onload = handleLoad;
+                    imageElement.onerror = handleError;
                 }
             });
         }
@@ -1702,10 +2246,9 @@ function ensureFabric() {
          */
         saveState() {
             if (!this.canvas) return;
-            const activeObject = this.canvas.getActiveObject();
 
             try {
-                const after = this._serializeCanvasState();
+                const after = this._captureCanvasStateOrThrow('saveState');
                 const before = this._lastSnapshot || after;
                 if (after === before) return;
                 let executedOnce = false;
@@ -1726,9 +2269,6 @@ function ensureFabric() {
             } catch (error) {
                 this._reportWarning('saveState: failed to save canvas snapshot', error);
             } finally {
-                if (activeObject && activeObject.maskId && !activeObject.__label && this.canvas.getObjects().includes(activeObject)) {
-                    this._handleSelectionChanged([activeObject]);
-                }
                 this._updateUI();
             }
         }
@@ -1745,7 +2285,10 @@ function ensureFabric() {
          * @private
          */
         _pushStateTransition(before, after) {
-            if (!before || !after) return;
+            if (!before || !after) {
+                this._reportWarning('History transition skipped because a canvas snapshot is unavailable');
+                return;
+            }
             if (before === after) return;
             if (!this.historyManager) this.historyManager = new HistoryManager(this.maxHistorySize || 50);
 
@@ -1767,7 +2310,10 @@ function ensureFabric() {
         undo() {
             return this.historyManager.undo()
                 .then(() => { this._updateUI(); })
-                .catch(error => { this._reportError('undo failed', error); });
+                .catch(error => {
+                    this._reportError('undo failed', error);
+                    throw error;
+                });
         }
 
         /**
@@ -1779,7 +2325,10 @@ function ensureFabric() {
         redo() {
             return this.historyManager.redo()
                 .then(() => { this._updateUI(); })
-                .catch(error => { this._reportError('redo failed', error); });
+                .catch(error => {
+                    this._reportError('redo failed', error);
+                    throw error;
+                });
         }
 
         _rebindMaskEvents(mask) {
@@ -1801,23 +2350,17 @@ function ensureFabric() {
             }
             if (Object.keys(metadata).length) mask.set(metadata);
 
-            const normalStyle = {
-                stroke: mask.originalStroke || '#ccc',
-                strokeWidth: mask.originalStrokeWidth,
-                opacity: mask.originalAlpha
-            };
-            const hoverStyle = {
-                stroke: '#ff5500',
-                strokeWidth: 2,
-                opacity: Math.min(mask.originalAlpha + 0.2, 1)
-            };
-
             const mouseover = () => {
-                mask.set(hoverStyle);
+                const opacity = Number(mask.originalAlpha);
+                mask.set({
+                    stroke: '#ff5500',
+                    strokeWidth: 2,
+                    opacity: Math.min((Number.isFinite(opacity) ? opacity : 0.5) + 0.2, 1)
+                });
                 if (mask.canvas) mask.canvas.requestRenderAll();
             };
             const mouseout = () => {
-                mask.set(normalStyle);
+                mask.set(this._getMaskNormalStyle(mask));
                 if (mask.canvas) mask.canvas.requestRenderAll();
             };
 
@@ -1856,6 +2399,7 @@ function ensureFabric() {
          */
         createMask(config = {}) {
             if (!this.canvas) return null;
+            if (!this._canMutateNow('createMask')) return null;
             const shapeType = config.shape || 'rect';
             // Normalize mask defaults before applying caller-provided overrides.
             const maskConfig = {
@@ -1898,15 +2442,12 @@ function ensureFabric() {
 
             if (maskConfig.left === undefined && this._lastMask) {
                 const previousMask = this._lastMask;
-                let previousMaskRight = previousMask.left;
-
-                if (previousMask.getScaledWidth) {
-                    previousMaskRight += previousMask.getScaledWidth();
-                } else if (previousMask.width) {
-                    previousMaskRight += previousMask.width * (previousMask.scaleX ?? 1);
-                }
-                left = Math.round(previousMaskRight + maskConfig.gap);
-                top = previousMask.top ?? firstOffset;
+                if (typeof previousMask.setCoords === 'function') previousMask.setCoords();
+                const previousBounds = typeof previousMask.getBoundingRect === 'function'
+                    ? previousMask.getBoundingRect(true, true)
+                    : { left: previousMask.left || firstOffset, top: previousMask.top || firstOffset, width: previousMask.width || 0 };
+                left = Math.round(previousBounds.left + previousBounds.width + maskConfig.gap);
+                top = Math.round(previousBounds.top ?? firstOffset);
             } else {
                 left = resolveValue(maskConfig.left, firstOffset, 'width');
                 top = resolveValue(maskConfig.top, firstOffset, 'height');
@@ -2044,6 +2585,8 @@ function ensureFabric() {
          * The associated label is also removed. UI and mask list are updated.
          */
         removeSelectedMask() {
+            if (!this.canvas) return;
+            if (!this._canMutateNow('removeSelectedMask')) return;
             const activeObject = this.canvas.getActiveObject();
             const selectedMasks = this._getModifiedMasks(activeObject);
             if (!selectedMasks.length) return;
@@ -2072,6 +2615,8 @@ function ensureFabric() {
          * UI and internal mask placement memory are reset.
          */
         removeAllMasks(options = {}) {
+            if (!this.canvas) return;
+            if (!this._canMutateNow('removeAllMasks', options)) return;
             const saveHistory = options.saveHistory !== false;
             const masks = this.canvas.getObjects().filter(object => object.maskId);
             masks.forEach(mask => this._removeLabelForMask(mask));
@@ -2137,6 +2682,10 @@ function ensureFabric() {
             let textObject = null;
             if (this.options.label && typeof this.options.label.create === 'function') {
                 textObject = this.options.label.create(mask, fabric);
+                if (!textObject || typeof textObject.set !== 'function') {
+                    this._reportWarning('label.create() returned an invalid Fabric object; using the default label');
+                    textObject = null;
+                }
             }
             if (!textObject) {
                 let labelText = mask.maskName;
@@ -2203,10 +2752,11 @@ function ensureFabric() {
             if (!this.options.maskLabelOnSelect) return;
             if (!mask.__label) return;
 
-            const coords = mask.getCoords ? mask.getCoords() : null;
-            if (!coords || coords.length < 4) return;
+            if (typeof mask.setCoords === 'function') mask.setCoords();
+            const bounds = mask.getBoundingRect ? mask.getBoundingRect(true, true) : null;
+            if (!bounds) return;
 
-            const tl = coords[0];
+            const tl = { x: bounds.left, y: bounds.top };
             const center = mask.getCenterPoint();
 
             const vx = center.x - tl.x;
@@ -2289,7 +2839,7 @@ function ensureFabric() {
          * @private
          */
         _updateMaskList() {
-            const maskListElement = document.getElementById(this.elements.maskList);
+            const maskListElement = this._getElement('maskList');
             if (!maskListElement) return;
             maskListElement.innerHTML = '';
             const masks = this.canvas.getObjects().filter(object => object.maskId);
@@ -2297,11 +2847,22 @@ function ensureFabric() {
                 const listItemElement = document.createElement('li');
                 listItemElement.className = 'list-group-item mask-item';
                 listItemElement.textContent = mask.maskName;
-                listItemElement.onclick = () => { this.canvas.setActiveObject(mask); this._handleSelectionChanged([mask]); };
+                listItemElement.dataset.maskId = String(mask.maskId);
                 maskListElement.appendChild(listItemElement);
             });
         }
 
+        _handleMaskListClick(event) {
+            if (!this.canvas) return;
+            const itemElement = event.target && event.target.closest ? event.target.closest('.mask-item') : null;
+            if (!itemElement || !itemElement.dataset) return;
+            const maskId = Number(itemElement.dataset.maskId);
+            const mask = this.canvas.getObjects().find(object => Number(object.maskId) === maskId);
+            if (!mask) return;
+            this.canvas.setActiveObject(mask);
+            this._handleSelectionChanged([mask]);
+        }
+
         /**
          * Updates the visual selection (CSS 'active') state for the mask list in the DOM.
          * 
@@ -2309,12 +2870,13 @@ function ensureFabric() {
          * @private
          */
         _updateMaskListSelection(selectedMask) {
-            const maskListElement = document.getElementById(this.elements.maskList);
+            const maskListElement = this._getElement('maskList');
             if (!maskListElement) return;
             const maskItems = maskListElement.querySelectorAll('.mask-item');
             maskItems.forEach(item => {
-                const isSelected = !!selectedMask && item.textContent === selectedMask.maskName;
+                const isSelected = !!selectedMask && Number(item.dataset.maskId) === Number(selectedMask.maskId);
                 item.classList.toggle('active', isSelected);
+                item.classList.toggle('selected', isSelected);
             });
         }
 
@@ -2330,21 +2892,38 @@ function ensureFabric() {
          */
         async mergeMasks() {
             if (!this.originalImage) return;
+            this._assertIdleForOperation('mergeMasks');
             const masks = this.canvas.getObjects().filter(object => object.maskId);
             if (!masks.length) return;
+            const beforeJson = this._serializeCanvasState();
+            const operationToken = this._beginBusyOperation('mergeMasks');
 
             this.canvas.discardActiveObject();
             this.canvas.renderAll();
 
             try {
-                const beforeJson = this._serializeCanvasState();
-                const merged = await this.exportImageBase64({ exportImageArea: true, multiplier: this.options.exportMultiplier });
-                this.removeAllMasks({ saveHistory: false });
-                await this.loadImage(merged, { preserveScroll: true });
+                const merged = await this.exportImageBase64(this._withInternalOperationOptions(operationToken, {
+                    exportImageArea: true,
+                    multiplier: this.options.exportMultiplier,
+                    fileType: 'png'
+                }));
+                this.removeAllMasks(this._withInternalOperationOptions(operationToken, { saveHistory: false }));
+                await this.loadImage(merged, this._withInternalOperationOptions(operationToken, {
+                    preserveScroll: true,
+                    resetMaskCounter: false
+                }));
                 const afterJson = this._serializeCanvasState();
                 this._pushStateTransition(beforeJson, afterJson);
             } catch (error) {
                 this._reportError('merge error', error);
+                try {
+                    await this.loadFromState(beforeJson);
+                } catch (restoreError) {
+                    this._reportError('mergeMasks rollback failed', restoreError);
+                }
+                throw error;
+            } finally {
+                this._endBusyOperation(operationToken);
             }
         }
 
@@ -2368,6 +2947,7 @@ function ensureFabric() {
          */
         downloadImage(fileName = this.options.defaultDownloadFileName) {
             if (!this.originalImage) return;
+            if (!this._canMutateNow('downloadImage')) return;
             const exportImageArea = this.options.exportImageAreaByDefault;
             this.exportImageBase64({ exportImageArea, multiplier: this.options.exportMultiplier })
                 .then(imageBase64 => {
@@ -2399,6 +2979,7 @@ function ensureFabric() {
          */
         async exportImageBase64(options = {}) {
             if (!this.originalImage) throw new Error('No image loaded');
+            this._assertIdleForOperation('exportImageBase64', options);
             const exportImageArea = typeof options.exportImageArea === 'boolean' ? options.exportImageArea : this.options.exportImageAreaByDefault;
             const multiplier = options.multiplier || this.options.exportMultiplier || 1;
             const quality = this._normalizeQuality(options.quality ?? this.options.downsampleQuality);
@@ -2415,12 +2996,13 @@ function ensureFabric() {
 
                     this.originalImage.setCoords();
                     const imageBounds = this.originalImage.getBoundingRect(true, true);
-                    const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
+                    const exportRegion = this._getClampedCanvasRegion(imageBounds);
                     return await this._exportCanvasRegionToDataURL({
                         ...exportRegion,
                         multiplier,
                         quality,
-                        format
+                        format,
+                        sealPartialEdges: this._getPartialExportEdges(imageBounds)
                     });
                 } finally {
                     maskVisibilityBackups.forEach(backup => {
@@ -2459,14 +3041,15 @@ function ensureFabric() {
                 // Compute an integer canvas region for the base image.
                 this.originalImage.setCoords();
                 const imageBounds = this.originalImage.getBoundingRect(true, true);
-                const exportRegion = this._getClampedCanvasRegion(imageBounds, { includePartialPixels: false });
+                const exportRegion = this._getClampedCanvasRegion(imageBounds);
 
                 // Crop precisely in offscreen canvas
                 finalBase64 = await this._exportCanvasRegionToDataURL({
                     ...exportRegion,
                     multiplier,
                     quality,
-                    format
+                    format,
+                    sealPartialEdges: this._getPartialExportEdges(imageBounds)
                 });
             } finally {
                 maskStyleBackups.forEach(backup => {
@@ -2520,6 +3103,7 @@ function ensureFabric() {
          */
         async exportImageFile(options = {}) {
             if (!this.originalImage) throw new Error('No image loaded');
+            this._assertIdleForOperation('exportImageFile');
             const {
                 mergeMask = true,
                 fileType = 'jpeg',
@@ -2529,6 +3113,7 @@ function ensureFabric() {
             } = options;
 
             const safeFileType = this._normalizeImageFormat(fileType);
+            const normalizedQuality = this._normalizeQuality(quality);
 
             // Generate the data URL in the requested export mode.
             let imageBase64;
@@ -2536,14 +3121,14 @@ function ensureFabric() {
                 imageBase64 = await this.exportImageBase64({
                     exportImageArea: true,
                     multiplier,
-                    quality,
+                    quality: normalizedQuality,
                     fileType: safeFileType
                 });
             } else {
                 imageBase64 = await this.exportImageBase64({
                     exportImageArea: false,
                     multiplier,
-                    quality,
+                    quality: normalizedQuality,
                     fileType: safeFileType
                 });
             }
@@ -2561,8 +3146,9 @@ function ensureFabric() {
                             offscreenCanvas.width = imageElement.width;
                             offscreenCanvas.height = imageElement.height;
                             const context = offscreenCanvas.getContext('2d');
+                            if (!context) throw new Error('Unable to create 2D canvas context for export conversion');
                             context.drawImage(imageElement, 0, 0);
-                            const convertedDataUrl = offscreenCanvas.toDataURL(`image/${safeFileType}`, quality);
+                            const convertedDataUrl = offscreenCanvas.toDataURL(`image/${safeFileType}`, normalizedQuality);
                             resolve(convertedDataUrl);
                         } catch (error) { reject(error); }
                     };
@@ -2633,13 +3219,15 @@ function ensureFabric() {
                 if (this._cropHandlers && this._cropHandlers.length) {
                     this._cropHandlers.forEach(targetHandlers => {
                         targetHandlers.handlers.forEach(handlerRecord => {
-                            targetHandlers.target.off(handlerRecord.eventName, handlerRecord.handler);
+                            if (targetHandlers.target && typeof targetHandlers.target.off === 'function') {
+                                targetHandlers.target.off(handlerRecord.eventName, handlerRecord.handler);
+                            }
                         });
                     });
                 }
             } catch (error) { void error; }
 
-            try { this.canvas.remove(this._cropRect); } catch (error) { void error; }
+            try { if (this.canvas) this.canvas.remove(this._cropRect); } catch (error) { void error; }
             this._cropRect = null;
             this._cropHandlers = [];
         }
@@ -2655,7 +3243,9 @@ function ensureFabric() {
          */
         enterCropMode() {
             if (!this.canvas || !this.originalImage || this._cropMode) return;
+            if (!this._canMutateNow('enterCropMode')) return;
             if (!this.isImageLoaded()) return;
+            this._removeCropRect();
             this._cropMode = true;
 
             // Disable group selection so only the crop rectangle can be manipulated.
@@ -2789,6 +3379,7 @@ function ensureFabric() {
          */
         async applyCrop() {
             if (!this.canvas || !this._cropMode || !this._cropRect) return;
+            this._assertIdleForOperation('applyCrop');
 
             // Fabric does not update control coordinates automatically after programmatic transforms.
             this._cropRect.setCoords();
@@ -2824,12 +3415,8 @@ function ensureFabric() {
                             this._removeLabelForMask(mask);
                             this.canvas.remove(mask);
                             if (shouldPreserveMasks && intersectsCrop) {
-                                mask.set({
-                                    left: (mask.left || 0) - cropRegion.sourceX,
-                                    top: (mask.top || 0) - cropRegion.sourceY,
-                                    visible: true
-                                });
-                                mask.setCoords();
+                                this._translateObjectByCanvasOffset(mask, -cropRegion.sourceX, -cropRegion.sourceY);
+                                mask.set({ visible: true });
                                 preservedMasks.push(mask);
                             }
                         } catch (error) {
@@ -2867,7 +3454,7 @@ function ensureFabric() {
 
             // Load the cropped image as the new base image.
             try {
-                await this.loadImage(croppedBase64);
+                await this.loadImage(croppedBase64, { resetMaskCounter: false });
                 if (preservedMasks.length) {
                     preservedMasks.forEach(mask => {
                         this._rebindMaskEvents(mask);
@@ -2887,7 +3474,7 @@ function ensureFabric() {
             // Create an after snapshot and push one history command for the crop operation.
             let afterJson;
             try {
-                afterJson = this._serializeCanvasState();
+                afterJson = preservedMasks.length ? this._serializeCanvasState() : this._lastSnapshot;
             } catch (error) {
                 this._reportWarning('applyCrop: failed to serialize after state', error);
                 afterJson = null;
@@ -2913,7 +3500,7 @@ function ensureFabric() {
          * @private
          */
         _updateInputs() {
-            const scaleInputElement = document.getElementById(this.elements.scaleRate);
+            const scaleInputElement = this._getElement('scaleRate');
             if (scaleInputElement) scaleInputElement.value = Math.round(this.currentScale * 100);
         }
 
@@ -2923,6 +3510,7 @@ function ensureFabric() {
          * @private
          */
         _updateUI() {
+            if (!this.canvas) return;
             const hasImage = !!this.originalImage;
             const masks = hasImage ? this.canvas.getObjects().filter(object => object.maskId) : [];
             const hasMasks = masks.length > 0;
@@ -2932,11 +3520,12 @@ function ensureFabric() {
             const canUndo = this.historyManager?.canUndo();
             const canRedo = this.historyManager?.canRedo();
             const isInCropMode = !!this._cropMode;
+            const isBusy = this.isAnimating || this._isLoading || !!this._activeOperationToken || !!(this.animationQueue && this.animationQueue.isBusy());
 
             if (isInCropMode) {
                 // Disable all controls except the crop action buttons while crop mode is active.
                 for (const key of Object.keys(this.elements || {})) {
-                    const element = document.getElementById(this.elements[key]);
+                    const element = this._getElement(key);
                     if (!element) continue;
                     if (key === 'applyCropBtn' || key === 'cancelCropBtn') {
                         this._setDisabled(key, false);
@@ -2947,23 +3536,23 @@ function ensureFabric() {
                 return;
             }
 
-            this._setDisabled('zoomInBtn', !hasImage || this.isAnimating || this.currentScale >= this.options.maxScale);
-            this._setDisabled('zoomOutBtn', !hasImage || this.isAnimating || this.currentScale <= this.options.minScale);
-            this._setDisabled('rotateLeftBtn', !hasImage || this.isAnimating);
-            this._setDisabled('rotateRightBtn', !hasImage || this.isAnimating);
-            this._setDisabled('addMaskBtn', !hasImage || this.isAnimating);
-            this._setDisabled('removeMaskBtn', !hasSelectedMask || this.isAnimating);
-            this._setDisabled('removeAllMasksBtn', !hasMasks || this.isAnimating);
-            this._setDisabled('mergeBtn', !hasImage || !hasMasks || this.isAnimating);
-            this._setDisabled('downloadBtn', !hasImage || this.isAnimating);
-            this._setDisabled('resetBtn', !hasImage || isDefaultTransform || this.isAnimating);
-            this._setDisabled('undoBtn', !hasImage || this.isAnimating || !canUndo);
-            this._setDisabled('redoBtn', !hasImage || this.isAnimating || !canRedo);
-            this._setDisabled('cropBtn', !hasImage || this.isAnimating);
+            this._setDisabled('zoomInBtn', !hasImage || isBusy || this.currentScale >= this.options.maxScale);
+            this._setDisabled('zoomOutBtn', !hasImage || isBusy || this.currentScale <= this.options.minScale);
+            this._setDisabled('rotateLeftBtn', !hasImage || isBusy);
+            this._setDisabled('rotateRightBtn', !hasImage || isBusy);
+            this._setDisabled('addMaskBtn', !hasImage || isBusy);
+            this._setDisabled('removeMaskBtn', !hasSelectedMask || isBusy);
+            this._setDisabled('removeAllMasksBtn', !hasMasks || isBusy);
+            this._setDisabled('mergeBtn', !hasImage || !hasMasks || isBusy);
+            this._setDisabled('downloadBtn', !hasImage || isBusy);
+            this._setDisabled('resetBtn', !hasImage || isDefaultTransform || isBusy);
+            this._setDisabled('undoBtn', !hasImage || isBusy || !canUndo);
+            this._setDisabled('redoBtn', !hasImage || isBusy || !canRedo);
+            this._setDisabled('cropBtn', !hasImage || isBusy);
             this._setDisabled('applyCropBtn', true);
             this._setDisabled('cancelCropBtn', true);
-            this._setDisabled('imageInput', this.isAnimating);
-            this._setDisabled('uploadArea', this.isAnimating);
+            this._setDisabled('imageInput', isBusy);
+            this._setDisabled('uploadArea', isBusy);
         }
 
         /**
@@ -2974,19 +3563,23 @@ function ensureFabric() {
          * @private
          */
         _setDisabled(key, disabled) {
-            const element = document.getElementById(this.elements[key]);
+            const element = this._getElement(key);
             if (!element) return;
             if ('disabled' in element) {
                 element.disabled = !!disabled;
                 return;
             }
+            if (!this._elementOriginalPointerEvents) this._elementOriginalPointerEvents = new Map();
+            if (!this._elementOriginalPointerEvents.has(key)) {
+                this._elementOriginalPointerEvents.set(key, element.style.pointerEvents || '');
+            }
 
             if (disabled) {
                 element.setAttribute('aria-disabled', 'true');
                 element.style.pointerEvents = 'none';
             } else {
                 element.removeAttribute('aria-disabled');
-                element.style.pointerEvents = '';
+                element.style.pointerEvents = this._elementOriginalPointerEvents.get(key) ?? '';
             }
         }
 
@@ -3012,9 +3605,23 @@ function ensureFabric() {
          * @private
          */
         _setPlaceholderVisible(show) {
-            if (!this.placeholderElement || !this.containerElement) return;
-            this._setElementVisible(this.placeholderElement, show);
-            this._setElementVisible(this.containerElement, !show);
+            if (this.placeholderElement) this._setElementVisible(this.placeholderElement, show);
+            const canvasVisibilityElement = this._getCanvasVisibilityElement();
+            if (canvasVisibilityElement && canvasVisibilityElement !== this.placeholderElement) {
+                this._setElementVisible(canvasVisibilityElement, !show);
+            }
+        }
+
+        _getCanvasVisibilityElement() {
+            const wrapperElement = this.canvas && this.canvas.wrapperEl ? this.canvas.wrapperEl : null;
+            if (
+                this.containerElement &&
+                this.placeholderElement &&
+                (this.containerElement === this.placeholderElement || this.containerElement.contains(this.placeholderElement))
+            ) {
+                return wrapperElement || this.canvasElement;
+            }
+            return this.containerElement || wrapperElement || this.canvasElement;
         }
 
         /**
@@ -3027,9 +3634,37 @@ function ensureFabric() {
          */
         _setElementVisible(element, isVisible) {
             if (!element) return;
+            this._rememberElementVisibility(element);
             element.hidden = !isVisible;
             element.setAttribute('aria-hidden', isVisible ? 'false' : 'true');
-            if (isVisible && element.classList) element.classList.remove('d-none');
+            if (element.classList) {
+                element.classList.toggle('d-none', !isVisible);
+            }
+        }
+
+        _rememberElementVisibility(element) {
+            if (!element || this._visibilityStateByElement.has(element)) return;
+            this._visibilityStateByElement.set(element, this._captureElementVisibility(element));
+        }
+
+        _captureElementVisibility(element) {
+            if (!element) return null;
+            return {
+                hidden: element.hidden,
+                ariaHidden: element.getAttribute('aria-hidden'),
+                className: element.className
+            };
+        }
+
+        _restoreElementVisibility(element, state) {
+            if (!element || !state) return;
+            element.hidden = !!state.hidden;
+            if (state.ariaHidden === null) {
+                element.removeAttribute('aria-hidden');
+            } else {
+                element.setAttribute('aria-hidden', state.ariaHidden);
+            }
+            element.className = state.className || '';
         }
 
         /**
@@ -3038,11 +3673,19 @@ function ensureFabric() {
          * @public
          */
         dispose() {
+            this._disposed = true;
+            this._rejectActiveAnimations(new Error('Editor disposed during animation'));
+            if (this.animationQueue) {
+                this.animationQueue.cancelAll(new Error('Editor disposed'));
+            }
+            this._isLoading = false;
+            this._activeOperationName = null;
+            this._activeOperationToken = null;
+
             // Remove bound DOM event listeners
             try {
-                for (const key in (this._handlersByElementKey || {})) {
-                    const handlers = this._handlersByElementKey[key] || [];
-                    const element = document.getElementById(this.elements[key]);
+                for (const [key, handlers] of Object.entries(this._handlersByElementKey || {})) {
+                    const element = this._getElement(key);
                     if (!element) continue;
                     handlers.forEach(handlerRecord => {
                         try { element.removeEventListener(handlerRecord.eventName, handlerRecord.handler); } catch (error) { void error; }
@@ -3055,8 +3698,25 @@ function ensureFabric() {
                 this._cropRect = null;
             }
 
-            if (this.containerElement && this._containerOriginalOverflow !== undefined) {
-                try { this.containerElement.style.overflow = this._containerOriginalOverflow; } catch (error) { void error; }
+            if (this.containerElement && this._containerOriginalOverflow) {
+                try { this._restoreContainerOverflowState(); } catch (error) { void error; }
+            }
+
+            if (this._visibilityStateByElement) {
+                try {
+                    [this.placeholderElement, this._getCanvasVisibilityElement()].forEach(element => {
+                        const state = element ? this._visibilityStateByElement.get(element) : null;
+                        if (state) this._restoreElementVisibility(element, state);
+                    });
+                } catch (error) { void error; }
+            }
+
+            if (this.canvasElement && this._canvasElementOriginalStyle) {
+                try {
+                    this.canvasElement.style.display = this._canvasElementOriginalStyle.display;
+                    this.canvasElement.style.width = this._canvasElementOriginalStyle.width;
+                    this.canvasElement.style.height = this._canvasElementOriginalStyle.height;
+                } catch (error) { void error; }
             }
 
             if (this.canvas) {
@@ -3066,6 +3726,22 @@ function ensureFabric() {
                 this.isImageLoadedToCanvas = false;
             }
             this._handlersByElementKey = {};
+            this._elementCache = {};
+            this._elementOriginalPointerEvents = new Map();
+            this._clearMaskPlacementMemory();
+            this.originalImage = null;
+            this.baseImageScale = 1;
+            this.currentScale = 1;
+            this.currentRotation = 0;
+            this.isAnimating = false;
+            this._isLoading = false;
+            this._cropMode = false;
+            this._cropRect = null;
+            this._cropHandlers = [];
+            this._cropPrevEvented = null;
+            this._prevSelectionSetting = undefined;
+            this._lastContainerViewportSize = null;
+            this._initialized = false;
         }
     }
 
@@ -3118,6 +3794,8 @@ function ensureFabric() {
              * @type {boolean}
              */
             this.isRunning = false;
+            this.currentTask = null;
+            this._generation = 0;
         }
 
         /**
@@ -3128,13 +3806,33 @@ function ensureFabric() {
          */
         async add(animationFn) {
             return new Promise((resolve, reject) => {
-                this.animationTasks.push({ animationFn, resolve, reject });
+                this.animationTasks.push({ animationFn, resolve, reject, isSettled: false });
                 if (!this.isRunning) {
                     this._drainQueue();
                 }
             });
         }
 
+        isBusy() {
+            return this.isRunning || this.animationTasks.length > 0;
+        }
+
+        cancelAll(reason = new Error('Animation queue cancelled')) {
+            this._generation += 1;
+            const cancellationError = reason instanceof Error ? reason : new Error(String(reason));
+            const tasks = [
+                ...(this.currentTask ? [this.currentTask] : []),
+                ...this.animationTasks.splice(0)
+            ];
+            tasks.forEach(task => {
+                if (!task || task.isSettled) return;
+                task.isSettled = true;
+                task.reject(cancellationError);
+            });
+            this.isRunning = false;
+            this.currentTask = null;
+        }
+
         /**
          * Runs queued animation tasks sequentially until the queue is empty.
          *
@@ -3142,22 +3840,36 @@ function ensureFabric() {
          * @returns {Promise<void>}
          */
         async _drainQueue() {
-            if (this.animationTasks.length === 0) {
-                this.isRunning = false;
-                return;
-            }
-
+            if (this.isRunning) return;
+            const generation = this._generation;
             this.isRunning = true;
-            const { animationFn, resolve, reject } = this.animationTasks.shift();
 
             try {
-                const result = await animationFn();
-                resolve(result);
-            } catch (error) {
-                reject(error);
-            }
+                while (this.animationTasks.length > 0 && generation === this._generation) {
+                    const task = this.animationTasks.shift();
+                    this.currentTask = task;
 
-            await this._drainQueue();
+                    try {
+                        const result = await task.animationFn();
+                        if (generation === this._generation && !task.isSettled) {
+                            task.isSettled = true;
+                            task.resolve(result);
+                        }
+                    } catch (error) {
+                        if (generation === this._generation && !task.isSettled) {
+                            task.isSettled = true;
+                            task.reject(error);
+                        }
+                    } finally {
+                        if (generation === this._generation && this.currentTask === task) this.currentTask = null;
+                    }
+                }
+            } finally {
+                if (generation === this._generation) {
+                    this.isRunning = false;
+                    this.currentTask = null;
+                }
+            }
         }
     }
 
@@ -3213,16 +3925,8 @@ function ensureFabric() {
          * @private
          */
         enqueue(task) {
-            const nextTask = this.pending.then(task, task);
-            let pendingAfterTask;
-            const resetPending = () => {
-                if (this.pending === pendingAfterTask) {
-                    this.pending = Promise.resolve();
-                }
-            };
-
-            pendingAfterTask = nextTask.then(resetPending, resetPending);
-            this.pending = pendingAfterTask;
+            const nextTask = this.pending.then(() => Promise.resolve().then(task));
+            this.pending = nextTask.catch(() => undefined);
             return nextTask;
         }
 
@@ -3234,8 +3938,14 @@ function ensureFabric() {
          * @returns {void}
          */
         execute(command) {
-            command.execute();
+            const result = command.execute();
+            if (result && typeof result.then === 'function') {
+                return Promise.resolve(result).then(() => {
+                    this.push(command);
+                });
+            }
             this.push(command);
+            return result;
         }
 
         /**
@@ -3255,9 +3965,8 @@ function ensureFabric() {
 
             if (this.history.length > this.maxSize) {
                 this.history.shift();
-            } else {
-                this.currentIndex++;
             }
+            this.currentIndex = this.history.length - 1;
         }
 
         /**