@bensitu/image-editor 1.4.1 → 1.5.0

package/src/image-editor.js

@@ -1,14 +1,14 @@
 /**
  * @file image-editor.js
  * @module image-editor
- * @version 1.4.1
+ * @version 1.5.0
  * @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');
+const INTERNAL_OPERATION_TOKEN = Symbol.for('ImageEditorInternalOperation');
 
 /**
  * Returns the ambient global scope used to discover a globally loaded Fabric.js namespace.
@@ -284,7 +284,7 @@ function ensureFabric() {
             this._disposed = false;
             this._initialized = false;
 
-            this.onImageLoaded = typeof options.onImageLoaded === 'function' ? options.onImageLoaded : null;
+            this.onImageLoaded = typeof this.options.onImageLoaded === 'function' ? this.options.onImageLoaded : null;
 
             this.animationQueue = new AnimationQueue();
             this.historyManager = new HistoryManager(this.maxHistorySize);
@@ -338,10 +338,12 @@ function ensureFabric() {
          * Use this method to set up the editor UI before interacting with it.
          *
          * @param {Object} [idMap={}] - Optional mapping from logical element names to actual DOM element IDs.
-         *   Supported keys include: canvas, canvasContainer, imgPlaceholder, scaleRate, rotationLeftInput,
-         *   rotationRightInput, rotateLeftBtn, rotateRightBtn, addMaskBtn, removeMaskBtn, removeAllMasksBtn,
-         *   mergeBtn, downloadBtn, maskList, zoomInBtn, zoomOutBtn, resetBtn, undoBtn, redoBtn, imageInput,
-         *   uploadArea, cropBtn, applyCropBtn, and cancelCropBtn. Unknown keys are ignored.
+         *   Supported keys include: canvas, canvasContainer, imagePlaceholder, scalePercentageInput,
+         *   rotateLeftDegreesInput, rotateRightDegreesInput, rotateLeftButton, rotateRightButton,
+         *   createMaskButton, removeSelectedMaskButton, removeAllMasksButton, mergeMasksButton,
+         *   downloadImageButton, maskList, zoomInButton, zoomOutButton, resetImageTransformButton,
+         *   undoButton, redoButton, imageInput, uploadArea, enterCropModeButton, applyCropButton,
+         *   and cancelCropButton. Deprecated 1.x names remain supported as aliases.
          *
          * @returns {void}
          *
@@ -350,7 +352,7 @@ function ensureFabric() {
          * @example
          * editor.init({
          *   canvas: 'myFabricCanvasId',
-         *   downloadBtn: 'myDownloadButtonId'
+         *   downloadImageButton: 'myDownloadButtonId'
          * });
          */
         init(idMap = {}) {
@@ -369,34 +371,54 @@ function ensureFabric() {
             this._containerOriginalOverflow = null;
             this._lastContainerViewportSize = null;
             this._canvasElementOriginalStyle = null;
+            this._deprecatedElementKeyWarnings = new Set();
 
             const defaults = {
                 canvas: 'fabricCanvas',
                 canvasContainer: null, // Pass an ID here if you have a scrollable viewport container
-                imgPlaceholder: 'imgPlaceholder',
-                scaleRate: 'scaleRate',
-                rotationLeftInput: 'rotationLeftInput',
-                rotationRightInput: 'rotationRightInput',
-                rotateLeftBtn: 'rotateLeftBtn',
-                rotateRightBtn: 'rotateRightBtn',
-                addMaskBtn: 'addMaskBtn',
-                removeMaskBtn: 'removeMaskBtn',
-                removeAllMasksBtn: 'removeAllMasksBtn',
-                mergeBtn: 'mergeBtn',
-                downloadBtn: 'downloadBtn',
+                imagePlaceholder: 'imagePlaceholder',
+                imgPlaceholder: null,
+                scalePercentageInput: 'scalePercentageInput',
+                scaleRate: null,
+                rotateLeftDegreesInput: 'rotateLeftDegreesInput',
+                rotationLeftInput: null,
+                rotateRightDegreesInput: 'rotateRightDegreesInput',
+                rotationRightInput: null,
+                rotateLeftButton: 'rotateLeftButton',
+                rotateLeftBtn: null,
+                rotateRightButton: 'rotateRightButton',
+                rotateRightBtn: null,
+                createMaskButton: 'createMaskButton',
+                addMaskBtn: null,
+                removeSelectedMaskButton: 'removeSelectedMaskButton',
+                removeMaskBtn: null,
+                removeAllMasksButton: 'removeAllMasksButton',
+                removeAllMasksBtn: null,
+                mergeMasksButton: 'mergeMasksButton',
+                mergeBtn: null,
+                downloadImageButton: 'downloadImageButton',
+                downloadBtn: null,
                 maskList: 'maskList',
-                zoomInBtn: 'zoomInBtn',
-                zoomOutBtn: 'zoomOutBtn',
-                resetBtn: 'resetBtn',
-                undoBtn: 'undoBtn',
-                redoBtn: 'redoBtn',
+                zoomInButton: 'zoomInButton',
+                zoomInBtn: null,
+                zoomOutButton: 'zoomOutButton',
+                zoomOutBtn: null,
+                resetImageTransformButton: 'resetImageTransformButton',
+                resetBtn: null,
+                undoButton: 'undoButton',
+                undoBtn: null,
+                redoButton: 'redoButton',
+                redoBtn: null,
                 imageInput: 'imageInput',
-                cropBtn: 'cropBtn',
-                applyCropBtn: 'applyCropBtn',
-                cancelCropBtn: 'cancelCropBtn'
+                enterCropModeButton: 'enterCropModeButton',
+                cropBtn: null,
+                applyCropButton: 'applyCropButton',
+                applyCropBtn: null,
+                cancelCropButton: 'cancelCropButton',
+                cancelCropBtn: null
             };
 
-            this.elements = { ...defaults, ...idMap };
+            this.elements = this._resolveElementIdMap(idMap || {}, defaults);
             this._elementCache = {};
 
             this._initCanvas();
@@ -413,6 +435,73 @@ function ensureFabric() {
             }
         }
 
+        _resolveElementIdMap(idMap, defaults) {
+            const resolved = { ...defaults, ...idMap };
+
+            this._resolveElementAliases(resolved, idMap, defaults, 'imagePlaceholder', ['imgPlaceholder']);
+            this._resolveElementAliases(resolved, idMap, defaults, 'scalePercentageInput', ['scaleRate']);
+            this._resolveElementAliases(resolved, idMap, defaults, 'rotateLeftDegreesInput', ['rotationLeftInput']);
+            this._resolveElementAliases(resolved, idMap, defaults, 'rotateRightDegreesInput', ['rotationRightInput']);
+            this._resolveElementAlias(resolved, idMap, defaults, 'rotateLeftButton', 'rotateLeftBtn');
+            this._resolveElementAlias(resolved, idMap, defaults, 'rotateRightButton', 'rotateRightBtn');
+            this._resolveElementAlias(resolved, idMap, defaults, 'createMaskButton', 'addMaskBtn');
+            this._resolveElementAliases(resolved, idMap, defaults, 'removeSelectedMaskButton', ['removeMaskBtn']);
+            this._resolveElementAlias(resolved, idMap, defaults, 'removeAllMasksButton', 'removeAllMasksBtn');
+            this._resolveElementAlias(resolved, idMap, defaults, 'mergeMasksButton', 'mergeBtn');
+            this._resolveElementAliases(resolved, idMap, defaults, 'downloadImageButton', ['downloadBtn']);
+            this._resolveElementAlias(resolved, idMap, defaults, 'zoomInButton', 'zoomInBtn');
+            this._resolveElementAlias(resolved, idMap, defaults, 'zoomOutButton', 'zoomOutBtn');
+            this._resolveElementAlias(resolved, idMap, defaults, 'resetImageTransformButton', 'resetBtn');
+            this._resolveElementAlias(resolved, idMap, defaults, 'undoButton', 'undoBtn');
+            this._resolveElementAlias(resolved, idMap, defaults, 'redoButton', 'redoBtn');
+            this._resolveElementAliases(resolved, idMap, defaults, 'enterCropModeButton', ['cropBtn']);
+            this._resolveElementAlias(resolved, idMap, defaults, 'applyCropButton', 'applyCropBtn');
+            this._resolveElementAlias(resolved, idMap, defaults, 'cancelCropButton', 'cancelCropBtn');
+
+            return resolved;
+        }
+
+        _resolveElementAlias(resolved, idMap, defaults, canonicalKey, deprecatedKey) {
+            this._resolveElementAliases(resolved, idMap, defaults, canonicalKey, [deprecatedKey]);
+        }
+
+        _resolveElementAliases(resolved, idMap, defaults, canonicalKey, deprecatedKeys) {
+            const hasCanonicalKey = Object.prototype.hasOwnProperty.call(idMap, canonicalKey);
+
+            if (hasCanonicalKey) {
+                resolved[canonicalKey] = idMap[canonicalKey];
+                return;
+            }
+
+            let deprecatedValue;
+            let hasDeprecatedValue = false;
+            for (const deprecatedKey of deprecatedKeys) {
+                if (Object.prototype.hasOwnProperty.call(idMap, deprecatedKey)) {
+                    if (!hasDeprecatedValue) {
+                        deprecatedValue = idMap[deprecatedKey];
+                        hasDeprecatedValue = true;
+                    }
+                    this._warnDeprecatedElementIdKey(deprecatedKey, canonicalKey);
+                }
+            }
+
+            if (hasDeprecatedValue) {
+                resolved[canonicalKey] = deprecatedValue;
+                return;
+            }
+
+            resolved[canonicalKey] = defaults[canonicalKey];
+        }
+
+        _warnDeprecatedElementIdKey(deprecatedKey, canonicalKey) {
+            if (!this._deprecatedElementKeyWarnings) this._deprecatedElementKeyWarnings = new Set();
+            if (this._deprecatedElementKeyWarnings.has(deprecatedKey)) return;
+            this._deprecatedElementKeyWarnings.add(deprecatedKey);
+            this._reportWarning(
+                `ElementIdMap.${deprecatedKey} is deprecated. Use ${canonicalKey} instead. This alias will be removed in v2.0.0.`
+            );
+        }
+
         _reportError(message, error = null) {
             const handler = this.options && this.options.onError;
             if (typeof handler !== 'function') return;
@@ -435,6 +524,12 @@ function ensureFabric() {
             }
         }
 
+        _notifyImageLoaded() {
+            const optionsCallback = this.options && this.options.onImageLoaded;
+            const callback = typeof optionsCallback === 'function' ? optionsCallback : this.onImageLoaded;
+            if (typeof callback === 'function') callback();
+        }
+
         /**
          * Initializes the Fabric canvas, viewport elements, and selection event handlers.
          *
@@ -460,7 +555,7 @@ function ensureFabric() {
                 this.containerElement = canvasElement.parentElement;
             }
 
-            this.placeholderElement = this._getElement('imgPlaceholder') || null;
+            this.placeholderElement = this._getElement('imagePlaceholder') || null;
 
             // Prefer a measured container size when it is available.
             let initialWidth = this.options.canvasWidth;
@@ -628,23 +723,23 @@ function ensureFabric() {
                 }
             });
             // Zoom & reset
-            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)); });
+            this._bindIfExists('zoomInButton', 'click', () => this.scaleImage(this.currentScale + this.options.scaleStep).catch(error => this._reportError('scaleImage failed', error)));
+            this._bindIfExists('zoomOutButton', 'click', () => this.scaleImage(this.currentScale - this.options.scaleStep).catch(error => this._reportError('scaleImage failed', error)));
+            this._bindIfExists('resetImageTransformButton', '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());
+            this._bindIfExists('createMaskButton', 'click', () => this.createMask());
+            this._bindIfExists('removeSelectedMaskButton', 'click', () => this.removeSelectedMask());
+            this._bindIfExists('removeAllMasksButton', 'click', () => this.removeAllMasks());
             // Merge + download
-            this._bindIfExists('mergeBtn', 'click', () => this.mergeMasks().catch(error => this._reportError('merge error', error)));
-            this._bindIfExists('downloadBtn', 'click', () => this.downloadImage());
+            this._bindIfExists('mergeMasksButton', 'click', () => this.mergeMasks().catch(error => this._reportError('merge error', error)));
+            this._bindIfExists('downloadImageButton', 'click', () => this.downloadImage());
             // Undo + 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)));
+            this._bindIfExists('undoButton', 'click', () => this.undo().catch(error => this._reportError('undo failed', error)));
+            this._bindIfExists('redoButton', '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 = this._getElement('rotationLeftInput');
+            this._bindIfExists('rotateLeftButton', 'click', () => {
+                const rotationInputElement = this._getElement('rotateLeftDegreesInput');
                 let step = this.options.rotationStep;
                 if (rotationInputElement) {
                     const parsedStep = parseFloat(rotationInputElement.value);
@@ -652,8 +747,8 @@ function ensureFabric() {
                 }
                 this.rotateImage(this.currentRotation - step).catch(error => this._reportError('rotateImage failed', error));
             });
-            this._bindIfExists('rotateRightBtn', 'click', () => {
-                const rotationInputElement = this._getElement('rotationRightInput');
+            this._bindIfExists('rotateRightButton', 'click', () => {
+                const rotationInputElement = this._getElement('rotateRightDegreesInput');
                 let step = this.options.rotationStep;
                 if (rotationInputElement) {
                     const parsedStep = parseFloat(rotationInputElement.value);
@@ -663,9 +758,9 @@ function ensureFabric() {
             });
 
             // 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('enterCropModeButton', 'click', () => this.enterCropMode());
+            this._bindIfExists('applyCropButton', 'click', () => { this.applyCrop().catch(error => this._reportError('applyCrop failed', error)); });
+            this._bindIfExists('cancelCropButton', 'click', () => this.cancelCrop());
             this._bindIfExists('maskList', 'click', (event) => this._handleMaskListClick(event));
         }
 
@@ -768,14 +863,16 @@ function ensureFabric() {
                 if (this._disposed || !this.canvas) throw new Error('Editor was disposed while loading image');
 
                 let loadSource = imageBase64;
-                if (this.options.downsampleOnLoad) {
+                const downsampleMaxWidth = Number(this.options.downsampleMaxWidth);
+                const downsampleMaxHeight = Number(this.options.downsampleMaxHeight);
+                if (this.options.downsampleOnLoad && downsampleMaxWidth > 0 && downsampleMaxHeight > 0) {
                     const shouldResize =
-                        imageElement.naturalWidth > this.options.downsampleMaxWidth ||
-                        imageElement.naturalHeight > this.options.downsampleMaxHeight;
+                        imageElement.naturalWidth > downsampleMaxWidth ||
+                        imageElement.naturalHeight > downsampleMaxHeight;
                     if (shouldResize) {
                         const ratio = Math.min(
-                            this.options.downsampleMaxWidth / imageElement.naturalWidth,
-                            this.options.downsampleMaxHeight / imageElement.naturalHeight
+                            downsampleMaxWidth / imageElement.naturalWidth,
+                            downsampleMaxHeight / imageElement.naturalHeight
                         );
                         const targetWidth = Math.round(imageElement.naturalWidth * ratio);
                         const targetHeight = Math.round(imageElement.naturalHeight * ratio);
@@ -787,6 +884,8 @@ function ensureFabric() {
                             imageBase64
                         );
                     }
+                } else if (this.options.downsampleOnLoad) {
+                    this._reportWarning('loadImage: downsample limits must be positive numbers; using the original image');
                 }
 
                 const fabricImage = await this._createFabricImageFromURL(loadSource);
@@ -856,9 +955,7 @@ function ensureFabric() {
                 this.canvas.renderAll();
                 this._lastSnapshot = this._captureCanvasStateOrThrow('loadImage');
 
-                if (typeof this.onImageLoaded === 'function') {
-                    this.onImageLoaded();
-                }
+                this._notifyImageLoaded();
             } catch (error) {
                 await this._rollbackLoadImageTransaction(transaction);
                 throw error;
@@ -883,6 +980,22 @@ function ensureFabric() {
             );
         }
 
+        /**
+         * Checks whether the editor is in a temporary non-mutating state.
+         *
+         * @returns {boolean} True while loading, animating, cropping, or running a compound operation.
+         * @public
+         */
+        isBusy() {
+            return !!(
+                this.isAnimating ||
+                this._cropMode ||
+                this._isLoading ||
+                this._activeOperationToken ||
+                (this.animationQueue && this.animationQueue.isBusy())
+            );
+        }
+
         /**
          * Creates an HTMLImageElement from a given data URL.
          * 
@@ -909,7 +1022,7 @@ function ensureFabric() {
                 };
                 timerId = setTimeout(() => {
                     settle(() => reject(new Error('Image load timed out')));
-                    try { imageElement.src = ''; } catch (error) { void error; }
+                    try { imageElement.src = ''; } catch (error) { this._reportWarning('Image timeout cleanup failed', error); }
                 }, safeTimeoutMs);
                 imageElement.onload = () => settle(() => resolve(imageElement));
                 imageElement.onerror = (error) => settle(() => reject(error));
@@ -957,7 +1070,6 @@ function ensureFabric() {
         _captureLoadImageTransaction() {
             return {
                 canvasState: this._serializeCanvasState(),
-                originalImage: this.originalImage,
                 baseImageScale: this.baseImageScale,
                 currentScale: this.currentScale,
                 currentRotation: this.currentRotation,
@@ -983,6 +1095,7 @@ function ensureFabric() {
         async _rollbackLoadImageTransaction(transaction) {
             if (!transaction || !this.canvas || this._disposed) return;
             let didRestoreCanvasState = false;
+            let didFailCanvasRestore = false;
             try {
                 if (transaction.canvasState) {
                     await this.loadFromState(transaction.canvasState);
@@ -990,23 +1103,28 @@ function ensureFabric() {
                 }
             } catch (error) {
                 this._lastMask = null;
+                didFailCanvasRestore = true;
                 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);
+            if (didFailCanvasRestore) {
+                this._reconcileEditorStateFromCanvas();
             } else {
-                this._lastMask = null;
+                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._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) {
@@ -1020,6 +1138,49 @@ function ensureFabric() {
             if (this.canvas) this.canvas.renderAll();
         }
 
+        _reconcileEditorStateFromCanvas() {
+            if (!this.canvas) {
+                this.originalImage = null;
+                this.baseImageScale = 1;
+                this.currentScale = 1;
+                this.currentRotation = 0;
+                this.maskCounter = 0;
+                this.isImageLoadedToCanvas = false;
+                this._lastSnapshot = null;
+                this._clearMaskPlacementMemory();
+                return;
+            }
+
+            const canvasObjects = this.canvas.getObjects();
+            this.originalImage = canvasObjects.find(object => object.type === 'image' && !object.maskId) || null;
+            if (this.originalImage) {
+                const imageScale = Number(this.originalImage.scaleX) || 1;
+                this.baseImageScale = imageScale;
+                this.currentScale = 1;
+                this.currentRotation = Number(this.originalImage.angle) || 0;
+            } else {
+                this.baseImageScale = 1;
+                this.currentScale = 1;
+                this.currentRotation = 0;
+            }
+
+            const masks = canvasObjects.filter(object => object.maskId);
+            this.maskCounter = masks.reduce((max, mask) => Math.max(max, Number(mask.maskId) || 0), 0);
+            this._lastMask = masks[masks.length - 1] || null;
+            if (!this._lastMask) {
+                this._lastMaskInitialLeft = null;
+                this._lastMaskInitialTop = null;
+                this._lastMaskInitialWidth = null;
+            }
+            this.isImageLoadedToCanvas = !!this.originalImage;
+            try {
+                this._lastSnapshot = this._serializeCanvasState();
+            } catch (error) {
+                this._lastSnapshot = null;
+                this._reportWarning('loadImage rollback: failed to reconcile canvas snapshot', error);
+            }
+        }
+
         _restoreLastMaskReference(previousLastMask) {
             if (!this.canvas) {
                 this._lastMask = null;
@@ -1048,12 +1209,20 @@ function ensureFabric() {
          * @private
          */
         _resampleImageToDataURL(imageElement, targetWidth, targetHeight, quality = 0.92, sourceDataUrl = null) {
+            const sourceWidth = Math.max(1, Number(imageElement && (imageElement.naturalWidth || imageElement.width)) || 0);
+            const sourceHeight = Math.max(1, Number(imageElement && (imageElement.naturalHeight || imageElement.height)) || 0);
+            const safeTargetWidth = Math.round(Number(targetWidth));
+            const safeTargetHeight = Math.round(Number(targetHeight));
+            if (!Number.isFinite(safeTargetWidth) || !Number.isFinite(safeTargetHeight) || safeTargetWidth <= 0 || safeTargetHeight <= 0) {
+                throw new Error('Invalid image resample target dimensions');
+            }
+
             const offscreenCanvas = document.createElement('canvas');
-            offscreenCanvas.width = targetWidth;
-            offscreenCanvas.height = targetHeight;
+            offscreenCanvas.width = safeTargetWidth;
+            offscreenCanvas.height = safeTargetHeight;
             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);
+            context.drawImage(imageElement, 0, 0, sourceWidth, sourceHeight, 0, 0, safeTargetWidth, safeTargetHeight);
             return offscreenCanvas.toDataURL(this._getDownsampleMimeType(sourceDataUrl), quality);
         }
 
@@ -1089,6 +1258,7 @@ function ensureFabric() {
          * @private
          */
         _setCanvasSizeInt(width, height) {
+            if (!this.canvas) return;
             const integerWidth = Math.max(1, Math.round(Number(width) || 1));
             const integerHeight = Math.max(1, Math.round(Number(height) || 1));
             // Set fabric internal and also style attributes to keep DOM consistent
@@ -1400,7 +1570,7 @@ function ensureFabric() {
         /**
          * Captures editor-owned runtime state that Fabric does not include in canvas JSON.
          *
-         * @returns {{version:number, baseImageScale:number, currentScale:number, currentRotation:number, maskCounter:number}} Serializable editor metadata.
+         * @returns {{version:number, baseImageScale:number, currentScale:number, currentRotation:number, maskCounter:number, canvasWidth:number, canvasHeight:number}} Serializable editor metadata.
          * @private
          */
         _serializeEditorMetadata() {
@@ -1408,13 +1578,17 @@ function ensureFabric() {
             const currentScale = Number(this.currentScale);
             const currentRotation = Number(this.currentRotation);
             const maskCounter = Number(this.maskCounter);
+            const canvasWidth = this.canvas ? Number(this.canvas.getWidth()) : NaN;
+            const canvasHeight = this.canvas ? Number(this.canvas.getHeight()) : NaN;
 
             return {
                 version: 1,
                 baseImageScale: Number.isFinite(baseImageScale) && baseImageScale > 0 ? baseImageScale : 1,
                 currentScale: Number.isFinite(currentScale) && currentScale > 0 ? currentScale : 1,
                 currentRotation: Number.isFinite(currentRotation) ? currentRotation : 0,
-                maskCounter: Number.isFinite(maskCounter) && maskCounter > 0 ? Math.floor(maskCounter) : 0
+                maskCounter: Number.isFinite(maskCounter) && maskCounter > 0 ? Math.floor(maskCounter) : 0,
+                canvasWidth: Number.isFinite(canvasWidth) && canvasWidth > 0 ? Math.round(canvasWidth) : 1,
+                canvasHeight: Number.isFinite(canvasHeight) && canvasHeight > 0 ? Math.round(canvasHeight) : 1
             };
         }
 
@@ -1617,11 +1791,50 @@ function ensureFabric() {
 
         _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';
+            if (!backgroundColor || this._isTransparentCssColor(backgroundColor)) return '#ffffff';
             return backgroundColor;
         }
 
+        _isTransparentCssColor(color) {
+            const normalizedColor = String(color || '').trim().toLowerCase();
+            if (!normalizedColor || normalizedColor === 'transparent') return true;
+
+            const hexAlphaMatch = normalizedColor.match(/^#(?:[0-9a-f]{3}([0-9a-f])|[0-9a-f]{6}([0-9a-f]{2}))$/i);
+            if (hexAlphaMatch) {
+                const alpha = hexAlphaMatch[1] || hexAlphaMatch[2];
+                return alpha === '0' || alpha === '00';
+            }
+
+            const slashAlphaMatch = normalizedColor.match(/^(?:rgba?|hsla?)\([^)]*\/\s*([^)]+)\)$/i);
+            if (slashAlphaMatch) return this._isZeroCssAlpha(slashAlphaMatch[1]);
+
+            const commaAlphaMatch = normalizedColor.match(/^(?:rgba|hsla)\((.*)\)$/i);
+            if (commaAlphaMatch) {
+                const parts = commaAlphaMatch[1].split(',');
+                if (parts.length >= 4) return this._isZeroCssAlpha(parts[parts.length - 1]);
+            }
+
+            return false;
+        }
+
+        _isZeroCssAlpha(alphaValue) {
+            const normalizedAlpha = String(alphaValue || '').trim();
+            if (!normalizedAlpha) return false;
+            if (normalizedAlpha.endsWith('%')) return Number.parseFloat(normalizedAlpha) === 0;
+            return Number(normalizedAlpha) === 0;
+        }
+
+        _decodeBase64Payload(base64Payload) {
+            const payload = String(base64Payload || '');
+            if (typeof atob === 'function') {
+                return Uint8Array.from(atob(payload), char => char.charCodeAt(0));
+            }
+            if (typeof Buffer !== 'undefined' && typeof Buffer.from === 'function') {
+                return new Uint8Array(Buffer.from(payload, 'base64'));
+            }
+            throw new Error('Base64 decoding is unavailable');
+        }
+
         /** 
          * Gets the top-left corner coordinates of the given object.
          * Used for geometry calculations (e.g., scale, rotate).
@@ -1747,19 +1960,14 @@ 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 shouldUseScrollSafeViewport = this.options.fitImageToCanvas || this.options.coverImageToCanvas;
-
                 let minWidth = 0;
                 let minHeight = 0;
-                if (shouldUseScrollSafeViewport) {
+                if (this.containerElement) {
                     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);
@@ -1838,9 +2046,16 @@ function ensureFabric() {
             if (this._disposed || !this.canvas) throw new Error(`${operationName} cannot run after the editor has been disposed`);
         }
 
+        _isCropModeAllowedOperation(operationName) {
+            return operationName === 'applyCrop' || operationName === 'cancelCrop';
+        }
+
         _assertIdleForOperation(operationName, options = {}) {
             this._assertEditorAvailable(operationName);
             const isOwnInternalOperation = this._isOwnInternalOperation(options);
+            if (this._cropMode && !this._isCropModeAllowedOperation(operationName) && !isOwnInternalOperation) {
+                throw new Error(`${operationName} cannot run while crop mode is active`);
+            }
             if (this.isAnimating || (this.animationQueue && this.animationQueue.isBusy())) {
                 throw new Error(`${operationName} cannot run while an animation is running`);
             }
@@ -1854,10 +2069,14 @@ function ensureFabric() {
 
         _assertCanQueueAnimation(operationName, options = {}) {
             this._assertEditorAvailable(operationName);
-            if (this._isLoading && !this._isOwnInternalOperation(options)) {
+            const isOwnInternalOperation = this._isOwnInternalOperation(options);
+            if (this._cropMode && !this._isCropModeAllowedOperation(operationName) && !isOwnInternalOperation) {
+                throw new Error(`${operationName} cannot run while crop mode is active`);
+            }
+            if (this._isLoading && !isOwnInternalOperation) {
                 throw new Error(`${operationName} cannot run while an image is loading`);
             }
-            if (this._activeOperationToken && !this._isOwnInternalOperation(options)) {
+            if (this._activeOperationToken && !isOwnInternalOperation) {
                 throw new Error(`${operationName} cannot run while ${this._activeOperationName || 'another operation'} is running`);
             }
         }
@@ -2064,10 +2283,19 @@ function ensureFabric() {
 
             return this.animationQueue.add(async () => {
                 const before = this._lastSnapshot || this._captureCanvasStateOrThrow('resetImageTransform');
-                await this._scaleImageImpl(1, { saveHistory: false });
-                await this._rotateImageImpl(0, { saveHistory: false });
-                const after = this._captureCanvasStateOrThrow('resetImageTransform');
-                this._pushStateTransition(before, after);
+                try {
+                    await this._scaleImageImpl(1, { saveHistory: false });
+                    await this._rotateImageImpl(0, { saveHistory: false });
+                    const after = this._captureCanvasStateOrThrow('resetImageTransform');
+                    this._pushStateTransition(before, after);
+                } catch (error) {
+                    try {
+                        await this.loadFromState(before);
+                    } catch (restoreError) {
+                        this._reportError('resetImageTransform rollback failed', restoreError);
+                    }
+                    throw error;
+                }
             }).finally(() => {
                 if (!this._disposed && this.canvas) this._updateUI();
             }).catch(error => {
@@ -2111,8 +2339,22 @@ function ensureFabric() {
                         ? JSON.parse(serializedState)
                         : serializedState;
                     const editorMetadata = state && state.imageEditorMetadata ? state.imageEditorMetadata : null;
+                    const restoredCanvasWidth = Number(editorMetadata && editorMetadata.canvasWidth);
+                    const restoredCanvasHeight = Number(editorMetadata && editorMetadata.canvasHeight);
+                    const hasRestoredCanvasSize =
+                        Number.isFinite(restoredCanvasWidth) &&
+                        restoredCanvasWidth > 0 &&
+                        Number.isFinite(restoredCanvasHeight) &&
+                        restoredCanvasHeight > 0;
+                    if (
+                        editorMetadata &&
+                        Object.prototype.hasOwnProperty.call(editorMetadata, 'version') &&
+                        Number(editorMetadata.version) !== 1
+                    ) {
+                        this._reportWarning(`loadFromState: unsupported editor metadata version ${editorMetadata.version}`);
+                    }
 
-                    this.canvas.loadFromJSON(state, async () => {
+                    const finishLoad = async () => {
                         try {
                             if (this._disposed || !this.canvas) {
                                 reject(new Error('Editor was disposed while loading state'));
@@ -2155,6 +2397,12 @@ function ensureFabric() {
                                 this.currentRotation = 0;
                             }
 
+                            if (hasRestoredCanvasSize) {
+                                this._setCanvasSizeInt(restoredCanvasWidth, restoredCanvasHeight);
+                            } else if (this.originalImage && this._shouldResizeCanvasToContentBounds()) {
+                                this._updateCanvasSizeToImageBounds();
+                            }
+
                             const masks = canvasObjects.filter(object => object.maskId);
                             masks.forEach(mask => {
                                 this._restoreMaskControls(mask);
@@ -2186,7 +2434,9 @@ function ensureFabric() {
                             this._reportError('loadFromState() failed', callbackError);
                             reject(callbackError);
                         }
-                    });
+                    };
+
+                    this.canvas.loadFromJSON(state, () => { void finishLoad(); });
 
                 } catch (error) {
                     this._reportError('loadFromState() failed', error);
@@ -2204,12 +2454,13 @@ function ensureFabric() {
 
         _waitForImageElementReady(imageElement) {
             if (!imageElement) return Promise.resolve();
-            if (imageElement.complete || imageElement.naturalWidth > 0 || imageElement.width > 0) return Promise.resolve();
+            const hasLoadedDimensions = (Number(imageElement.naturalWidth) > 0 || Number(imageElement.width) > 0) &&
+                (Number(imageElement.naturalHeight) > 0 || Number(imageElement.height) > 0);
+            if (hasLoadedDimensions) return Promise.resolve();
+            if (imageElement.complete) return Promise.reject(new Error('Image could not be loaded while restoring state'));
             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));
+                let timerId;
                 const settle = (callback) => {
                     if (isSettled) return;
                     isSettled = true;
@@ -2223,8 +2474,21 @@ function ensureFabric() {
                     }
                     callback();
                 };
-                const handleLoad = () => settle(resolve);
-                const handleError = (error) => settle(() => reject(error));
+                const handleLoad = () => {
+                    const didLoad = (Number(imageElement.naturalWidth) > 0 || Number(imageElement.width) > 0) &&
+                        (Number(imageElement.naturalHeight) > 0 || Number(imageElement.height) > 0);
+                    settle(() => {
+                        if (didLoad) {
+                            resolve();
+                        } else {
+                            reject(new Error('Image could not be loaded while restoring state'));
+                        }
+                    });
+                };
+                const handleError = (error) => settle(() => reject(error instanceof Error ? error : new Error('Image could not be loaded while restoring state')));
+                timerId = setTimeout(() => {
+                    settle(() => reject(new Error('Image load timed out while restoring state')));
+                }, this._getSafeTimeoutMs(this.options.imageLoadTimeoutMs));
                 if (typeof imageElement.addEventListener === 'function') {
                     imageElement.addEventListener('load', handleLoad, { once: true });
                     imageElement.addEventListener('error', handleError, { once: true });
@@ -2333,12 +2597,7 @@ function ensureFabric() {
 
         _rebindMaskEvents(mask) {
             if (!mask) return;
-            if (mask.__imageEditorMaskHandlers) {
-                try {
-                    mask.off('mouseover', mask.__imageEditorMaskHandlers.mouseover);
-                    mask.off('mouseout', mask.__imageEditorMaskHandlers.mouseout);
-                } catch (error) { void error; }
-            }
+            this._cleanupMaskEvents(mask);
 
             const metadata = {};
             if (!Number.isFinite(Number(mask.originalAlpha))) {
@@ -2369,6 +2628,19 @@ function ensureFabric() {
             mask.__imageEditorMaskHandlers = { mouseover, mouseout };
         }
 
+        _cleanupMaskEvents(mask) {
+            if (!mask || !mask.__imageEditorMaskHandlers) return;
+            try {
+                if (typeof mask.off === 'function') {
+                    mask.off('mouseover', mask.__imageEditorMaskHandlers.mouseover);
+                    mask.off('mouseout', mask.__imageEditorMaskHandlers.mouseout);
+                }
+            } catch (error) {
+                this._reportWarning('Mask event cleanup failed', error);
+            }
+            try { delete mask.__imageEditorMaskHandlers; } catch (error) { this._reportWarning('Mask event metadata cleanup failed', error); }
+        }
+
         /**
          * Creates a mask and adds it to the canvas.
          *
@@ -2517,6 +2789,11 @@ function ensureFabric() {
                 }
             }
 
+            if (!mask || typeof mask.set !== 'function' || typeof mask.setCoords !== 'function') {
+                this._reportWarning('fabricGenerator returned an invalid Fabric object');
+                return null;
+            }
+
             const styles = maskConfig.styles || {};
             const hasStyle = property => Object.prototype.hasOwnProperty.call(styles, property);
             const maskSettings = {
@@ -2594,6 +2871,7 @@ function ensureFabric() {
             this.canvas.discardActiveObject();
             selectedMasks.forEach(mask => {
                 this._removeLabelForMask(mask);
+                this._cleanupMaskEvents(mask);
                 this.canvas.remove(mask);
             });
 
@@ -2620,7 +2898,10 @@ function ensureFabric() {
             const saveHistory = options.saveHistory !== false;
             const masks = this.canvas.getObjects().filter(object => object.maskId);
             masks.forEach(mask => this._removeLabelForMask(mask));
-            masks.forEach(mask => this.canvas.remove(mask));
+            masks.forEach(mask => {
+                this._cleanupMaskEvents(mask);
+                this.canvas.remove(mask);
+            });
             this.canvas.discardActiveObject();
             this._lastMask = null;
             this._lastMaskInitialLeft = null;
@@ -2651,6 +2932,101 @@ function ensureFabric() {
             }
         }
 
+        _captureMaskLabelBackups(masks) {
+            if (!this.canvas) return [];
+            const canvasObjects = new Set(this.canvas.getObjects());
+            return (masks || []).map(mask => {
+                const label = mask && mask.__label ? mask.__label : null;
+                return {
+                    mask,
+                    label,
+                    hadLabel: !!label,
+                    labelInCanvas: !!label && canvasObjects.has(label),
+                    visible: label ? label.visible : undefined
+                };
+            });
+        }
+
+        _restoreMaskLabelBackups(labelBackups) {
+            if (!this.canvas || !Array.isArray(labelBackups)) return;
+            const canvasObjects = new Set(this.canvas.getObjects());
+            labelBackups.forEach(backup => {
+                if (!backup || !backup.mask) return;
+                try {
+                    if (!backup.hadLabel) {
+                        if (backup.mask.__label) this._removeLabelForMask(backup.mask);
+                        return;
+                    }
+                    backup.mask.__label = backup.label;
+                    if (!backup.label) return;
+                    if (backup.labelInCanvas && !canvasObjects.has(backup.label)) {
+                        this.canvas.add(backup.label);
+                        canvasObjects.add(backup.label);
+                    }
+                    if (backup.visible !== undefined) backup.label.set({ visible: backup.visible });
+                    if (backup.labelInCanvas) this.canvas.bringToFront(backup.label);
+                    this._syncMaskLabel(backup.mask);
+                } catch (error) {
+                    this._reportWarning('restoreMaskLabelBackups: failed to restore mask label', error);
+                }
+            });
+        }
+
+        _captureActiveObjectBackup() {
+            if (!this.canvas) return null;
+            const activeObject = this.canvas.getActiveObject();
+            if (!activeObject) return null;
+            const selectedObjects = typeof activeObject.getObjects === 'function'
+                ? activeObject.getObjects()
+                : [activeObject];
+            return { activeObject, selectedObjects };
+        }
+
+        _restoreActiveObjectBackup(activeObjectBackup) {
+            if (!this.canvas || !activeObjectBackup || !activeObjectBackup.activeObject) return;
+            const canvasObjects = this.canvas.getObjects();
+            const selectedObjects = Array.isArray(activeObjectBackup.selectedObjects)
+                ? activeObjectBackup.selectedObjects
+                : [];
+            const canRestore = selectedObjects.length
+                ? selectedObjects.every(object => canvasObjects.includes(object))
+                : canvasObjects.includes(activeObjectBackup.activeObject);
+            if (!canRestore) return;
+            try {
+                this.canvas.setActiveObject(activeObjectBackup.activeObject);
+            } catch (error) { void error; }
+        }
+
+        _captureMaskExportBackups(masks) {
+            return (masks || []).map(mask => ({
+                object: mask,
+                visible: mask.visible,
+                opacity: mask.opacity,
+                fill: mask.fill,
+                strokeWidth: mask.strokeWidth,
+                stroke: mask.stroke,
+                selectable: mask.selectable,
+                lockRotation: mask.lockRotation
+            }));
+        }
+
+        _restoreMaskExportBackups(maskBackups) {
+            (maskBackups || []).forEach(backup => {
+                try {
+                    backup.object.set({
+                        visible: backup.visible,
+                        opacity: backup.opacity,
+                        fill: backup.fill,
+                        strokeWidth: backup.strokeWidth,
+                        stroke: backup.stroke,
+                        selectable: backup.selectable,
+                        lockRotation: backup.lockRotation
+                    });
+                    backup.object.setCoords();
+                } catch (error) { void error; }
+            });
+        }
+
         /**
          * Returns a stable zero-based creation index for label callbacks.
          *
@@ -2728,10 +3104,13 @@ function ensureFabric() {
         _hideAllMaskLabels() {
             if (!this.canvas) return;
             const canvasObjects = this.canvas.getObjects();
+            const canvasObjectSet = new Set(canvasObjects);
             const labels = canvasObjects.filter(object => object.maskLabel);
             labels.forEach(label => {
                 try {
-                    if (canvasObjects.includes(label)) this.canvas.remove(label);
+                    if (canvasObjectSet.has(label)) {
+                        this.canvas.remove(label);
+                    }
                 } catch (error) { void error; }
             });
             canvasObjects.forEach(object => {
@@ -2908,6 +3287,9 @@ function ensureFabric() {
                     fileType: 'png'
                 }));
                 this.removeAllMasks(this._withInternalOperationOptions(operationToken, { saveHistory: false }));
+                if (this.canvas.getObjects().some(object => object.maskId)) {
+                    throw new Error('Masks could not be removed during merge');
+                }
                 await this.loadImage(merged, this._withInternalOperationOptions(operationToken, {
                     preserveScroll: true,
                     resetMaskCounter: false
@@ -2987,7 +3369,11 @@ function ensureFabric() {
 
             if (!exportImageArea) {
                 const masks = this.canvas.getObjects().filter(object => object.maskId || object.maskLabel);
+                const editableMasks = this.canvas.getObjects().filter(object => object.maskId);
                 const maskVisibilityBackups = masks.map(mask => ({ object: mask, visible: mask.visible }));
+                const maskStyleBackups = this._captureMaskExportBackups(editableMasks);
+                const labelBackups = this._captureMaskLabelBackups(editableMasks);
+                const activeObjectBackup = this._captureActiveObjectBackup();
 
                 try {
                     masks.forEach(mask => { mask.set({ visible: false }); });
@@ -3008,23 +3394,19 @@ function ensureFabric() {
                     maskVisibilityBackups.forEach(backup => {
                         try { backup.object.set({ visible: backup.visible }); } catch (error) { void error; }
                     });
+                    this._restoreMaskExportBackups(maskStyleBackups);
+                    this._restoreMaskLabelBackups(labelBackups);
+                    this._restoreActiveObjectBackup(activeObjectBackup);
                     this.canvas.renderAll();
                 }
             }
 
             // Render masks as export shapes without mutating their editable styles.
             const masks = this.canvas.getObjects().filter(object => object.maskId);
-            const maskStyleBackups = masks.map(mask => ({
-                object: mask,
-                opacity: mask.opacity,
-                fill: mask.fill,
-                strokeWidth: mask.strokeWidth,
-                stroke: mask.stroke,
-                selectable: mask.selectable,
-                lockRotation: mask.lockRotation
-            }));
+            const maskStyleBackups = this._captureMaskExportBackups(masks);
+            const labelBackups = this._captureMaskLabelBackups(masks);
+            const activeObjectBackup = this._captureActiveObjectBackup();
 
-            let finalBase64;
             try {
                 // Labels are UI overlays and should not be part of the flattened export.
                 masks.forEach(mask => this._removeLabelForMask(mask));
@@ -3043,8 +3425,7 @@ function ensureFabric() {
                 const imageBounds = this.originalImage.getBoundingRect(true, true);
                 const exportRegion = this._getClampedCanvasRegion(imageBounds);
 
-                // Crop precisely in offscreen canvas
-                finalBase64 = await this._exportCanvasRegionToDataURL({
+                return await this._exportCanvasRegionToDataURL({
                     ...exportRegion,
                     multiplier,
                     quality,
@@ -3052,24 +3433,11 @@ function ensureFabric() {
                     sealPartialEdges: this._getPartialExportEdges(imageBounds)
                 });
             } finally {
-                maskStyleBackups.forEach(backup => {
-                    try {
-                        backup.object.set({
-                            opacity: backup.opacity,
-                            fill: backup.fill,
-                            strokeWidth: backup.strokeWidth,
-                            stroke: backup.stroke,
-                            selectable: backup.selectable,
-                            lockRotation: backup.lockRotation
-                        });
-                        backup.object.setCoords();
-                    } catch (error) { void error; }
-                });
-
+                this._restoreMaskExportBackups(maskStyleBackups);
+                this._restoreMaskLabelBackups(labelBackups);
+                this._restoreActiveObjectBackup(activeObjectBackup);
                 this.canvas.renderAll();
             }
-
-            return finalBase64;
         }
 
         /**
@@ -3158,13 +3526,8 @@ function ensureFabric() {
             }
 
             // Convert the final data URL to a File with the requested MIME type.
-            const binaryString = atob(imageDataUrl.split(',')[1]);
+            const bytes = this._decodeBase64Payload(imageDataUrl.split(',')[1]);
             const mime = `image/${safeFileType}`;
-            let byteIndex = binaryString.length;
-            const bytes = new Uint8Array(byteIndex);
-            while (byteIndex--) {
-                bytes[byteIndex] = binaryString.charCodeAt(byteIndex);
-            }
             return new File([bytes], fileName, { type: mime });
         }
 
@@ -3214,20 +3577,21 @@ function ensureFabric() {
         }
 
         _removeCropRect() {
-            if (!this._cropRect) return;
-            try {
-                if (this._cropHandlers && this._cropHandlers.length) {
-                    this._cropHandlers.forEach(targetHandlers => {
-                        targetHandlers.handlers.forEach(handlerRecord => {
+            if (this._cropHandlers && this._cropHandlers.length) {
+                this._cropHandlers.forEach(targetHandlers => {
+                    (targetHandlers.handlers || []).forEach(handlerRecord => {
+                        try {
                             if (targetHandlers.target && typeof targetHandlers.target.off === 'function') {
                                 targetHandlers.target.off(handlerRecord.eventName, handlerRecord.handler);
                             }
-                        });
+                        } catch (error) {
+                            this._reportWarning('Crop handler cleanup failed', error);
+                        }
                     });
-                }
-            } catch (error) { void error; }
+                });
+            }
 
-            try { if (this.canvas) this.canvas.remove(this._cropRect); } catch (error) { void error; }
+            try { if (this.canvas && this._cropRect) this.canvas.remove(this._cropRect); } catch (error) { void error; }
             this._cropRect = null;
             this._cropHandlers = [];
         }
@@ -3325,6 +3689,30 @@ function ensureFabric() {
                     const nextScaleY = Math.min(maxCropHeight / cropHeight, Math.max(minCropHeight / cropHeight, Number(cropRect.scaleY) || 1));
                     cropRect.set({ scaleX: nextScaleX, scaleY: nextScaleY });
                     cropRect.setCoords();
+                    const cropBounds = cropRect.getBoundingRect(true, true);
+                    const imageLeft = Number(imageBounds.left) || 0;
+                    const imageTop = Number(imageBounds.top) || 0;
+                    const imageRight = imageLeft + (Number(imageBounds.width) || 0);
+                    const imageBottom = imageTop + (Number(imageBounds.height) || 0);
+                    let deltaX = 0;
+                    let deltaY = 0;
+                    if (cropBounds.left < imageLeft) {
+                        deltaX = imageLeft - cropBounds.left;
+                    } else if (cropBounds.left + cropBounds.width > imageRight) {
+                        deltaX = imageRight - (cropBounds.left + cropBounds.width);
+                    }
+                    if (cropBounds.top < imageTop) {
+                        deltaY = imageTop - cropBounds.top;
+                    } else if (cropBounds.top + cropBounds.height > imageBottom) {
+                        deltaY = imageBottom - (cropBounds.top + cropBounds.height);
+                    }
+                    if (deltaX || deltaY) {
+                        cropRect.set({
+                            left: (Number(cropRect.left) || 0) + deltaX,
+                            top: (Number(cropRect.top) || 0) + deltaY
+                        });
+                        cropRect.setCoords();
+                    }
                     this.canvas.requestRenderAll();
                 } catch (error) { void error; }
             };
@@ -3394,9 +3782,13 @@ function ensureFabric() {
             try {
                 beforeJson = this._serializeCanvasState();
             } catch (error) {
-                this._reportWarning('applyCrop: could not serialize before state', error);
+                this._reportError('applyCrop: failed to capture rollback state', error);
                 beforeJson = null;
             }
+            if (!beforeJson) {
+                this.cancelCrop();
+                return;
+            }
 
             const preservedMasks = [];
 
@@ -3404,23 +3796,20 @@ function ensureFabric() {
                 const masks = this.canvas.getObjects().filter(object => object.maskId);
                 if (masks && masks.length) {
                     masks.forEach(mask => {
-                        try {
-                            mask.setCoords();
-                            const maskBounds = mask.getBoundingRect(true, true);
-                            const intersectsCrop =
-                                maskBounds.left < cropRegion.sourceX + cropRegion.sourceWidth &&
-                                maskBounds.left + maskBounds.width > cropRegion.sourceX &&
-                                maskBounds.top < cropRegion.sourceY + cropRegion.sourceHeight &&
-                                maskBounds.top + maskBounds.height > cropRegion.sourceY;
-                            this._removeLabelForMask(mask);
-                            this.canvas.remove(mask);
-                            if (shouldPreserveMasks && intersectsCrop) {
-                                this._translateObjectByCanvasOffset(mask, -cropRegion.sourceX, -cropRegion.sourceY);
-                                mask.set({ visible: true });
-                                preservedMasks.push(mask);
-                            }
-                        } catch (error) {
-                            this._reportWarning('applyCrop: failed to remove mask', error);
+                        mask.setCoords();
+                        const maskBounds = mask.getBoundingRect(true, true);
+                        const intersectsCrop =
+                            maskBounds.left < cropRegion.sourceX + cropRegion.sourceWidth &&
+                            maskBounds.left + maskBounds.width > cropRegion.sourceX &&
+                            maskBounds.top < cropRegion.sourceY + cropRegion.sourceHeight &&
+                            maskBounds.top + maskBounds.height > cropRegion.sourceY;
+                        this._removeLabelForMask(mask);
+                        this._cleanupMaskEvents(mask);
+                        this.canvas.remove(mask);
+                        if (shouldPreserveMasks && intersectsCrop) {
+                            this._translateObjectByCanvasOffset(mask, -cropRegion.sourceX, -cropRegion.sourceY);
+                            mask.set({ visible: true });
+                            preservedMasks.push(mask);
                         }
                     });
                     this._clearMaskPlacementMemory();
@@ -3428,7 +3817,8 @@ function ensureFabric() {
                     this.canvas.renderAll();
                 }
             } catch (error) {
-                this._reportWarning('applyCrop: error while removing masks', error);
+                await this._restoreStateAfterCropFailure(beforeJson, 'applyCrop: failed to prepare masks', error);
+                return;
             }
 
             this._removeCropRect();
@@ -3500,7 +3890,7 @@ function ensureFabric() {
          * @private
          */
         _updateInputs() {
-            const scaleInputElement = this._getElement('scaleRate');
+            const scaleInputElement = this._getElement('scalePercentageInput');
             if (scaleInputElement) scaleInputElement.value = Math.round(this.currentScale * 100);
         }
 
@@ -3520,14 +3910,14 @@ 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());
+            const isBusy = this.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 = this._getElement(key);
                     if (!element) continue;
-                    if (key === 'applyCropBtn' || key === 'cancelCropBtn') {
+                    if (key === 'applyCropButton' || key === 'cancelCropButton' || key === 'applyCropBtn' || key === 'cancelCropBtn') {
                         this._setDisabled(key, false);
                     } else {
                         this._setDisabled(key, true);
@@ -3536,21 +3926,25 @@ function ensureFabric() {
                 return;
             }
 
-            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('zoomInButton', !hasImage || isBusy || this.currentScale >= this.options.maxScale);
+            this._setDisabled('zoomOutButton', !hasImage || isBusy || this.currentScale <= this.options.minScale);
+            this._setDisabled('rotateLeftButton', !hasImage || isBusy);
+            this._setDisabled('rotateRightButton', !hasImage || isBusy);
+            this._setDisabled('createMaskButton', !hasImage || isBusy);
+            this._setDisabled('removeSelectedMaskButton', !hasSelectedMask || isBusy);
+            this._setDisabled('removeAllMasksButton', !hasMasks || isBusy);
+            this._setDisabled('mergeMasksButton', !hasImage || !hasMasks || isBusy);
+            this._setDisabled('downloadImageButton', !hasImage || isBusy);
+            this._setDisabled('resetImageTransformButton', !hasImage || isDefaultTransform || isBusy);
+            this._setDisabled('undoButton', !hasImage || isBusy || !canUndo);
+            this._setDisabled('redoButton', !hasImage || isBusy || !canRedo);
+            this._setDisabled('enterCropModeButton', !hasImage || isBusy);
+            this._setDisabled('applyCropButton', true);
+            this._setDisabled('cancelCropButton', true);
+            this._setDisabled('scalePercentageInput', !hasImage || isBusy);
+            this._setDisabled('rotateLeftDegreesInput', !hasImage || isBusy);
+            this._setDisabled('rotateRightDegreesInput', !hasImage || isBusy);
+            this._setDisabled('maskList', !hasImage || isBusy);
             this._setDisabled('imageInput', isBusy);
             this._setDisabled('uploadArea', isBusy);
         }
@@ -3558,7 +3952,7 @@ function ensureFabric() {
         /**
          * Enables or disables a specific UI element (typically a button) by its key.
          * 
-         * @param {string} key - Key of the element in this.elements (e.g. 'zoomInBtn').
+         * @param {string} key - Key of the element in this.elements (e.g. 'zoomInButton').
          * @param {boolean} disabled - If true, disables the element; otherwise enables.
          * @private
          */
@@ -3693,10 +4087,7 @@ function ensureFabric() {
                 }
             } catch (error) { void error; }
 
-            if (this._cropRect) {
-                try { this.canvas.remove(this._cropRect); } catch (error) { void error; }
-                this._cropRect = null;
-            }
+            if (this._cropRect) this._removeCropRect();
 
             if (this.containerElement && this._containerOriginalOverflow) {
                 try { this._restoreContainerOverflowState(); } catch (error) { void error; }
@@ -3716,10 +4107,16 @@ function ensureFabric() {
                     this.canvasElement.style.display = this._canvasElementOriginalStyle.display;
                     this.canvasElement.style.width = this._canvasElementOriginalStyle.width;
                     this.canvasElement.style.height = this._canvasElementOriginalStyle.height;
+                    this.canvasElement.style.maxWidth = this._canvasElementOriginalStyle.maxWidth;
                 } catch (error) { void error; }
             }
 
             if (this.canvas) {
+                try {
+                    this.canvas.getObjects().forEach(object => {
+                        if (object && object.maskId) this._cleanupMaskEvents(object);
+                    });
+                } catch (error) { void error; }
                 try { this.canvas.dispose(); } catch (error) { void error; }
                 this.canvas = null;
                 this.canvasElement = null;
@@ -3861,7 +4258,7 @@ function ensureFabric() {
                             task.reject(error);
                         }
                     } finally {
-                        if (generation === this._generation && this.currentTask === task) this.currentTask = null;
+                        if (this.currentTask === task) this.currentTask = null;
                     }
                 }
             } finally {
@@ -3940,9 +4337,9 @@ function ensureFabric() {
         execute(command) {
             const result = command.execute();
             if (result && typeof result.then === 'function') {
-                return Promise.resolve(result).then(() => {
+                return this.enqueue(() => Promise.resolve(result).then(() => {
                     this.push(command);
-                });
+                }));
             }
             this.push(command);
             return result;