@bensitu/image-editor 1.5.0 → 1.5.2

package/src/image-editor.js

@@ -1,7 +1,7 @@
 /**
  * @file image-editor.js
  * @module image-editor
- * @version 1.5.0
+ * @version 1.5.2
  * @author Ben Situ
  * @license MIT
  * @description Lightweight canvas-based image editor with masking/transform/export support.
@@ -132,6 +132,8 @@ function ensureFabric() {
      * @param {number} [options.downsampleQuality=0.92] - JPEG quality for downsampling/export.
      * @param {number} [options.imageLoadTimeoutMs=30000] - Timeout for image decode operations.
      * @param {number} [options.exportMultiplier=1] - Scale output image by this multiplier on export.
+     * @param {number} [options.maxExportPixels=50000000] - Maximum output pixels allowed per export.
+     * @param {number} [options.maxHistorySize=50] - Maximum undo/redo history entries to keep. Large base64 images can make each snapshot expensive.
      * @param {boolean} [options.exportImageAreaByDefault=true] - Export only the image area (clipped to masks).
      * @param {number} [options.defaultMaskWidth=50] - Default width of new masks.
      * @param {number} [options.defaultMaskHeight=80] - Default height of new masks.
@@ -202,6 +204,8 @@ function ensureFabric() {
                 imageLoadTimeoutMs: 30000,
 
                 exportMultiplier: 1,
+                maxExportPixels: 50000000,
+                maxHistorySize: 50,
                 exportImageAreaByDefault: true,
 
                 defaultMaskWidth: 50,
@@ -234,6 +238,7 @@ function ensureFabric() {
                     ...userCrop
                 }
             };
+            this._normalizeOptions();
 
             // Verify that Fabric.js is present before any canvas work starts.
             this._fabricLoaded = !!ensureFabric();
@@ -258,11 +263,12 @@ function ensureFabric() {
             this._activeOperationToken = null;
             this.elements = {};
             this.isImageLoadedToCanvas = false;
-            this.maxHistorySize = 50;
+            this.maxHistorySize = this.options.maxHistorySize;
 
             this._handlersByElementKey = {};
             this._elementCache = {};
             this._elementOriginalPointerEvents = new Map();
+            this._elementOriginalDisabledState = new Map();
 
             this._lastMask = null;
             this._lastMaskInitialLeft = null;
@@ -271,6 +277,7 @@ function ensureFabric() {
             this._lastSnapshot = null;
 
             this._cropMode = false;
+            this._isApplyingCrop = false;
             this._cropRect = null;
             this._cropHandlers = [];
             this._cropPrevEvented = null;
@@ -283,6 +290,8 @@ function ensureFabric() {
             this._activeAnimationRejectors = new Set();
             this._disposed = false;
             this._initialized = false;
+            this._deprecatedElementKeyWarnings = new Set();
+            this._cropRotationWarningEmitted = false;
 
             this.onImageLoaded = typeof this.options.onImageLoaded === 'function' ? this.options.onImageLoaded : null;
 
@@ -356,7 +365,13 @@ function ensureFabric() {
          * });
          */
         init(idMap = {}) {
-            if (!this._fabricLoaded) return;
+            if (!this._fabricLoaded) {
+                this._fabricLoaded = !!ensureFabric();
+                if (!this._fabricLoaded) {
+                    this._reportError('fabric.js is not loaded. Please include fabric.js first. Initialization will be aborted.');
+                    return;
+                }
+            }
             if (this._initialized || this.canvas) this.dispose();
             this._disposed = false;
             this._initialized = true;
@@ -368,10 +383,11 @@ function ensureFabric() {
             this._activeOperationName = null;
             this._activeOperationToken = null;
             this._elementOriginalPointerEvents = new Map();
+            this._elementOriginalDisabledState = new Map();
+            this._isApplyingCrop = false;
             this._containerOriginalOverflow = null;
             this._lastContainerViewportSize = null;
             this._canvasElementOriginalStyle = null;
-            this._deprecatedElementKeyWarnings = new Set();
 
             const defaults = {
                 canvas: 'fabricCanvas',
@@ -410,6 +426,7 @@ function ensureFabric() {
                 redoButton: 'redoButton',
                 redoBtn: null,
                 imageInput: 'imageInput',
+                uploadArea: null,
                 enterCropModeButton: 'enterCropModeButton',
                 cropBtn: null,
                 applyCropButton: 'applyCropButton',
@@ -429,7 +446,8 @@ function ensureFabric() {
 
             // Auto-load initial image if provided
             if (this.options.initialImageBase64) {
-                this.loadImage(this.options.initialImageBase64);
+                this.loadImage(this.options.initialImageBase64)
+                    .catch(error => this._reportError('initialImageBase64 could not be loaded', error));
             } else {
                 this._updatePlaceholderStatus();
             }
@@ -502,6 +520,66 @@ function ensureFabric() {
             );
         }
 
+        _normalizeFiniteNumber(value, fallback) {
+            const numericValue = Number(value);
+            return Number.isFinite(numericValue) ? numericValue : fallback;
+        }
+
+        _normalizePositiveNumber(value, fallback) {
+            const numericValue = this._normalizeFiniteNumber(value, fallback);
+            return numericValue > 0 ? numericValue : fallback;
+        }
+
+        _normalizeNonNegativeNumber(value, fallback) {
+            const numericValue = this._normalizeFiniteNumber(value, fallback);
+            return numericValue >= 0 ? numericValue : fallback;
+        }
+
+        _normalizePositiveInteger(value, fallback) {
+            const numericValue = this._normalizePositiveNumber(value, fallback);
+            return Math.max(1, Math.floor(numericValue));
+        }
+
+        _normalizeOptions() {
+            const options = this.options || {};
+            options.canvasWidth = this._normalizePositiveNumber(options.canvasWidth, 800);
+            options.canvasHeight = this._normalizePositiveNumber(options.canvasHeight, 600);
+            options.animationDuration = this._normalizeNonNegativeNumber(options.animationDuration, 300);
+
+            const minScale = this._normalizePositiveNumber(options.minScale, 0.1);
+            const maxScale = this._normalizePositiveNumber(options.maxScale, 5);
+            if (minScale > maxScale) {
+                options.minScale = 0.1;
+                options.maxScale = 5;
+            } else {
+                options.minScale = minScale;
+                options.maxScale = maxScale;
+            }
+            options.scaleStep = this._normalizePositiveNumber(options.scaleStep, 0.05);
+            options.rotationStep = this._normalizeFiniteNumber(options.rotationStep, 90);
+
+            options.downsampleMaxWidth = this._normalizePositiveNumber(options.downsampleMaxWidth, 4000);
+            options.downsampleMaxHeight = this._normalizePositiveNumber(options.downsampleMaxHeight, 3000);
+            options.downsampleQuality = options.downsampleQuality == null
+                ? 0.92
+                : Math.max(0, Math.min(1, this._normalizeFiniteNumber(options.downsampleQuality, 0.92)));
+            options.imageLoadTimeoutMs = this._normalizePositiveNumber(options.imageLoadTimeoutMs, 30000);
+
+            options.exportMultiplier = this._normalizePositiveNumber(options.exportMultiplier, 1);
+            options.maxExportPixels = this._normalizePositiveInteger(options.maxExportPixels, 50000000);
+            options.maxHistorySize = this._normalizePositiveInteger(options.maxHistorySize, 50);
+
+            options.defaultMaskWidth = this._normalizePositiveNumber(options.defaultMaskWidth, 50);
+            options.defaultMaskHeight = this._normalizePositiveNumber(options.defaultMaskHeight, 80);
+            options.maskLabelOffset = this._normalizeNonNegativeNumber(options.maskLabelOffset, 3);
+
+            if (options.crop) {
+                options.crop.minWidth = this._normalizePositiveNumber(options.crop.minWidth, 100);
+                options.crop.minHeight = this._normalizePositiveNumber(options.crop.minHeight, 100);
+                options.crop.padding = this._normalizeNonNegativeNumber(options.crop.padding, 10);
+            }
+        }
+
         _reportError(message, error = null) {
             const handler = this.options && this.options.onError;
             if (typeof handler !== 'function') return;
@@ -524,10 +602,19 @@ function ensureFabric() {
             }
         }
 
+        _emitSafeCallback(callback, message) {
+            if (typeof callback !== 'function') return;
+            try {
+                callback();
+            } catch (error) {
+                this._reportWarning(message, error);
+            }
+        }
+
         _notifyImageLoaded() {
             const optionsCallback = this.options && this.options.onImageLoaded;
             const callback = typeof optionsCallback === 'function' ? optionsCallback : this.onImageLoaded;
-            if (typeof callback === 'function') callback();
+            this._emitSafeCallback(callback, 'onImageLoaded callback failed');
         }
 
         /**
@@ -660,13 +747,14 @@ function ensureFabric() {
             this._captureContainerOverflowState();
 
             const shouldPreserveScroll = options.preserveScroll === true;
-            if (this.options.coverImageToCanvas) {
+            const layoutMode = this._getImageLayoutMode();
+            if (layoutMode === 'cover') {
                 this.containerElement.style.overflow = 'scroll';
                 if (!shouldPreserveScroll) {
                     this.containerElement.scrollLeft = 0;
                     this.containerElement.scrollTop = 0;
                 }
-            } else if (this.options.fitImageToCanvas) {
+            } else if (layoutMode === 'fit') {
                 this.containerElement.style.overflow = 'auto';
                 if (!shouldPreserveScroll) {
                     this.containerElement.scrollLeft = 0;
@@ -792,7 +880,6 @@ function ensureFabric() {
         _loadImageFile(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);
             }
 
@@ -838,6 +925,13 @@ function ensureFabric() {
             );
         }
 
+        _getImageLayoutMode() {
+            if (this.options.fitImageToCanvas) return 'fit';
+            if (this.options.coverImageToCanvas) return 'cover';
+            if (this.options.expandCanvasToImage) return 'expand';
+            return 'contain';
+        }
+
         /**
          * Loads a base64 data URL into the Fabric canvas as the base image.
          *
@@ -851,14 +945,22 @@ function ensureFabric() {
             if (!this._fabricLoaded) return;
             if (!this.canvas || this._disposed) return;
             if (!imageBase64 || typeof imageBase64 !== 'string' || !imageBase64.startsWith('data:image/')) return;
+            options = options || {};
             this._assertIdleForOperation('loadImage', options);
 
-            this._isLoading = true;
-            this._updateUI();
-            this._warnOnImageLayoutOptionConflict();
-            const transaction = this._captureLoadImageTransaction();
+            const isNestedOperation = this._isOwnInternalOperation(options);
+            const operationToken = isNestedOperation
+                ? this._getInternalOperationToken(options)
+                : this._beginBusyOperation('loadImage');
+            let transaction = null;
+            let shouldNotifyImageLoaded;
 
             try {
+                this._isLoading = true;
+                this._updateUI();
+                this._warnOnImageLayoutOptionConflict();
+                transaction = this._captureLoadImageTransaction();
+
                 const imageElement = await this._createImageElement(imageBase64);
                 if (this._disposed || !this.canvas) throw new Error('Editor was disposed while loading image');
 
@@ -906,8 +1008,9 @@ function ensureFabric() {
                 const viewport = this._getContainerViewportSize();
                 const minWidth = viewport.width;
                 const minHeight = viewport.height;
+                const layoutMode = this._getImageLayoutMode();
 
-                if (this.options.fitImageToCanvas) {
+                if (layoutMode === 'fit') {
                     const canvasWidth = Math.max(1, minWidth - 1);
                     const canvasHeight = Math.max(1, minHeight - 1);
                     this._setCanvasSizeInt(canvasWidth, canvasHeight);
@@ -915,13 +1018,13 @@ function ensureFabric() {
                     fabricImage.set({ left: 0, top: 0 });
                     fabricImage.scale(fitScale);
                     this.baseImageScale = fabricImage.scaleX || 1;
-                } else if (this.options.coverImageToCanvas) {
+                } else if (layoutMode === 'cover') {
                     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) {
+                } else if (layoutMode === 'expand') {
                     const canvasWidth = Math.max(minWidth, Math.floor(imageWidth));
                     const canvasHeight = Math.max(minHeight, Math.floor(imageHeight));
                     this._setCanvasSizeInt(canvasWidth, canvasHeight);
@@ -954,15 +1057,21 @@ function ensureFabric() {
                 this._updateUI();
                 this.canvas.renderAll();
                 this._lastSnapshot = this._captureCanvasStateOrThrow('loadImage');
-
-                this._notifyImageLoaded();
+                shouldNotifyImageLoaded = true;
             } catch (error) {
-                await this._rollbackLoadImageTransaction(transaction);
+                await this._rollbackLoadImageTransaction(
+                    transaction,
+                    this._withInternalOperationOptions(operationToken)
+                );
                 throw error;
             } finally {
                 this._isLoading = false;
+                if (!isNestedOperation) this._endBusyOperation(operationToken);
                 if (!this._disposed && this.canvas) this._updateUI();
             }
+            if (shouldNotifyImageLoaded && !this._disposed && this.canvas) {
+                this._notifyImageLoaded();
+            }
         }
 
         /**
@@ -990,6 +1099,7 @@ function ensureFabric() {
             return !!(
                 this.isAnimating ||
                 this._cropMode ||
+                this._isApplyingCrop ||
                 this._isLoading ||
                 this._activeOperationToken ||
                 (this.animationQueue && this.animationQueue.isBusy())
@@ -1092,13 +1202,13 @@ function ensureFabric() {
             };
         }
 
-        async _rollbackLoadImageTransaction(transaction) {
+        async _rollbackLoadImageTransaction(transaction, options = {}) {
             if (!transaction || !this.canvas || this._disposed) return;
             let didRestoreCanvasState = false;
             let didFailCanvasRestore = false;
             try {
                 if (transaction.canvasState) {
-                    await this.loadFromState(transaction.canvasState);
+                    await this.loadFromState(transaction.canvasState, options);
                     didRestoreCanvasState = true;
                 }
             } catch (error) {
@@ -1413,10 +1523,18 @@ function ensureFabric() {
 
             effectiveWidth = Math.max(1, viewport.width - (hasVertical ? scrollbar.width : 0));
             effectiveHeight = Math.max(1, viewport.height - (hasHorizontal ? scrollbar.height : 0));
+            const safetyMargin = this._getScrollSafetyMargin();
+            const layoutMode = this._getImageLayoutMode();
+            const shouldReserveNoScrollbarMargin = layoutMode === 'fit' || layoutMode === 'cover';
+            const getNonOverflowAxisSize = (contentSize, effectiveSize, hasOppositeScrollbar) => {
+                const margin = hasOppositeScrollbar ? safetyMargin : (shouldReserveNoScrollbarMargin ? 1 : 0);
+                const safeEffectiveSize = Math.max(1, effectiveSize - margin);
+                return contentSize <= safeEffectiveSize + 0.5 ? safeEffectiveSize : effectiveSize;
+            };
 
             return {
-                width: hasHorizontal ? this._ceilCanvasDimension(contentWidth) : effectiveWidth,
-                height: hasVertical ? this._ceilCanvasDimension(contentHeight) : effectiveHeight,
+                width: hasHorizontal ? this._ceilCanvasDimension(contentWidth) : getNonOverflowAxisSize(contentWidth, effectiveWidth, hasVertical),
+                height: hasVertical ? this._ceilCanvasDimension(contentHeight) : getNonOverflowAxisSize(contentHeight, effectiveHeight, hasHorizontal),
                 viewportWidth: effectiveWidth,
                 viewportHeight: effectiveHeight,
                 hasHorizontal,
@@ -1549,6 +1667,50 @@ function ensureFabric() {
             }
         }
 
+        _getSerializableStateObjects() {
+            if (!this.canvas) return [];
+            return this.canvas.getObjects().filter(object => !object.isCropRect && !object.maskLabel);
+        }
+
+        _restoreHighPrecisionSerializedGeometry(serializedObjects) {
+            if (!Array.isArray(serializedObjects)) return;
+            const fabricObjects = this._getSerializableStateObjects();
+            const numericProperties = [
+                'left',
+                'top',
+                'width',
+                'height',
+                'scaleX',
+                'scaleY',
+                'angle',
+                'skewX',
+                'skewY',
+                'cropX',
+                'cropY',
+                'radius',
+                'rx',
+                'ry',
+                'strokeWidth'
+            ];
+
+            serializedObjects.forEach((serializedObject, index) => {
+                const fabricObject = fabricObjects[index];
+                if (!serializedObject || !fabricObject) return;
+
+                numericProperties.forEach(property => {
+                    const numericValue = Number(fabricObject[property]);
+                    if (Number.isFinite(numericValue)) serializedObject[property] = numericValue;
+                });
+
+                if (Array.isArray(serializedObject.points) && Array.isArray(fabricObject.points)) {
+                    serializedObject.points = fabricObject.points.map(point => ({
+                        x: Number.isFinite(Number(point && point.x)) ? Number(point.x) : 0,
+                        y: Number.isFinite(Number(point && point.y)) ? Number(point.y) : 0
+                    }));
+                }
+            });
+        }
+
         _restoreMaskControls(mask) {
             if (!mask) return;
 
@@ -1598,6 +1760,7 @@ function ensureFabric() {
                 const jsonObject = this.canvas.toJSON(this._getStateProperties());
                 if (Array.isArray(jsonObject.objects)) {
                     jsonObject.objects = jsonObject.objects.filter(object => !object.isCropRect && !object.maskLabel);
+                    this._restoreHighPrecisionSerializedGeometry(jsonObject.objects);
                 }
                 jsonObject.imageEditorMetadata = this._serializeEditorMetadata();
                 return JSON.stringify(jsonObject);
@@ -1680,6 +1843,13 @@ function ensureFabric() {
             return Math.abs(numericValue - Math.round(numericValue)) > 0.01;
         }
 
+        _hasScaledImageEdge(axis) {
+            if (!this.originalImage) return false;
+            const scale = Number(axis === 'y' ? this.originalImage.scaleY : this.originalImage.scaleX);
+            if (!Number.isFinite(scale)) return false;
+            return Math.abs(scale - 1) > 0.01;
+        }
+
         _getPartialExportEdges(bounds) {
             if (!bounds) return null;
             const angle = Math.abs((Number(this.originalImage && this.originalImage.angle) || 0) % 90);
@@ -1689,8 +1859,8 @@ function ensureFabric() {
             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))
+                right: this._hasFractionalCanvasEdge((Number(bounds.left) || 0) + (Number(bounds.width) || 0)) || this._hasScaledImageEdge('x'),
+                bottom: this._hasFractionalCanvasEdge((Number(bounds.top) || 0) + (Number(bounds.height) || 0)) || this._hasScaledImageEdge('y')
             };
         }
 
@@ -1756,7 +1926,8 @@ function ensureFabric() {
          * @private
          */
         async _exportCanvasRegionToDataURL({ sourceX, sourceY, sourceWidth, sourceHeight, multiplier = 1, quality = 0.92, format = 'jpeg', sealPartialEdges = null }) {
-            const safeMultiplier = Math.max(1, Number(multiplier) || 1);
+            const safeMultiplier = this._getSafeExportMultiplier(multiplier);
+            this._assertExportPixelBudget(sourceWidth, sourceHeight, safeMultiplier);
             const safeFormat = this._normalizeImageFormat(format);
             const exportFormat = safeFormat === 'jpeg' ? 'png' : safeFormat;
             let regionDataUrl = this.canvas.toDataURL({
@@ -1774,6 +1945,30 @@ function ensureFabric() {
             return this._convertDataUrlToOpaqueJpeg(regionDataUrl, quality);
         }
 
+        _getSafeExportMultiplier(multiplier) {
+            const numericMultiplier = Number(multiplier);
+            if (!Number.isFinite(numericMultiplier) || numericMultiplier <= 0) {
+                throw new Error('Export multiplier must be a finite positive number');
+            }
+            return Math.max(1, numericMultiplier);
+        }
+
+        _assertExportPixelBudget(sourceWidth, sourceHeight, safeMultiplier) {
+            const width = Math.max(1, Math.ceil(Number(sourceWidth) || 1));
+            const height = Math.max(1, Math.ceil(Number(sourceHeight) || 1));
+            const outputWidth = Math.ceil(width * safeMultiplier);
+            const outputHeight = Math.ceil(height * safeMultiplier);
+            const outputPixels = outputWidth * outputHeight;
+            const configuredMaxPixels = Number(this.options.maxExportPixels);
+            const maxPixels = Number.isFinite(configuredMaxPixels) && configuredMaxPixels > 0
+                ? Math.floor(configuredMaxPixels)
+                : 50000000;
+
+            if (outputPixels > maxPixels) {
+                throw new Error(`Export would create ${outputPixels} pixels, exceeding the configured maxExportPixels limit of ${maxPixels}`);
+            }
+        }
+
         async _convertDataUrlToOpaqueJpeg(dataUrl, quality = 0.92) {
             const imageElement = await this._createImageElement(dataUrl);
             const width = Math.max(1, imageElement.naturalWidth || imageElement.width || 1);
@@ -1792,7 +1987,24 @@ function ensureFabric() {
         _getJpegBackgroundColor() {
             const backgroundColor = String(this.options.backgroundColor || '').trim();
             if (!backgroundColor || this._isTransparentCssColor(backgroundColor)) return '#ffffff';
-            return backgroundColor;
+            return this._isValidCanvasFillStyle(backgroundColor) ? backgroundColor : '#ffffff';
+        }
+
+        _isValidCanvasFillStyle(color) {
+            try {
+                if (typeof document === 'undefined' || !document.createElement) return false;
+                const validationCanvas = document.createElement('canvas');
+                const context = validationCanvas.getContext && validationCanvas.getContext('2d');
+                if (!context) return false;
+                context.fillStyle = '#010203';
+                context.fillStyle = color;
+                if (context.fillStyle !== '#010203') return true;
+                context.fillStyle = '#040506';
+                context.fillStyle = color;
+                return context.fillStyle !== '#040506';
+            } catch {
+                return false;
+            }
         }
 
         _isTransparentCssColor(color) {
@@ -1826,6 +2038,7 @@ function ensureFabric() {
 
         _decodeBase64Payload(base64Payload) {
             const payload = String(base64Payload || '');
+            if (!payload) throw new Error('Data URL base64 payload is empty');
             if (typeof atob === 'function') {
                 return Uint8Array.from(atob(payload), char => char.charCodeAt(0));
             }
@@ -1835,6 +2048,14 @@ function ensureFabric() {
             throw new Error('Base64 decoding is unavailable');
         }
 
+        _decodeDataUrlPayload(dataUrl) {
+            const match = String(dataUrl || '').match(/^data:([^;,]+);base64,([A-Za-z0-9+/=]+)$/i);
+            if (!match || !match[2]) {
+                throw new Error('Export produced an invalid or empty base64 data URL');
+            }
+            return this._decodeBase64Payload(match[2]);
+        }
+
         /** 
          * Gets the top-left corner coordinates of the given object.
          * Used for geometry calculations (e.g., scale, rotate).
@@ -1953,13 +2174,49 @@ function ensureFabric() {
                 const currentHeight = this.canvas.getHeight();
                 let requiredWidth = currentWidth;
                 let requiredHeight = currentHeight;
-                fabricObjects.forEach(fabricObject => {
+                const layoutMode = this._getImageLayoutMode();
+                const usesScrollableFitBounds = layoutMode === 'fit' || layoutMode === 'cover';
+                let contentWidth = 0;
+                let contentHeight = 0;
+                const includeObjectBounds = (fabricObject, objectPadding = 0) => {
                     if (!fabricObject) return;
                     if (typeof fabricObject.setCoords === 'function') fabricObject.setCoords();
                     const boundingRect = fabricObject.getBoundingRect(true, true);
-                    requiredWidth = Math.max(requiredWidth, Math.ceil(boundingRect.left + boundingRect.width + padding));
-                    requiredHeight = Math.max(requiredHeight, Math.ceil(boundingRect.top + boundingRect.height + padding));
+                    const right = Math.ceil(boundingRect.left + boundingRect.width + objectPadding);
+                    const bottom = Math.ceil(boundingRect.top + boundingRect.height + objectPadding);
+                    contentWidth = Math.max(contentWidth, right);
+                    contentHeight = Math.max(contentHeight, bottom);
+                    return { right, bottom };
+                };
+                fabricObjects.forEach(fabricObject => {
+                    const bounds = includeObjectBounds(fabricObject, padding);
+                    if (!bounds) return;
+                    requiredWidth = Math.max(requiredWidth, bounds.right);
+                    requiredHeight = Math.max(requiredHeight, bounds.bottom);
                 });
+                if (usesScrollableFitBounds) {
+                    if (this.originalImage) includeObjectBounds(this.originalImage, 0);
+                    this.canvas.getObjects().forEach(object => {
+                        if (object && object.maskId) includeObjectBounds(object, padding);
+                    });
+
+                    const contentSize = this._getScrollableCanvasSize(
+                        Math.max(1, contentWidth),
+                        Math.max(1, contentHeight)
+                    );
+
+                    const newWidth = contentSize.hasHorizontal
+                        ? Math.max(currentWidth, contentSize.width)
+                        : contentSize.width;
+                    const newHeight = contentSize.hasVertical
+                        ? Math.max(currentHeight, contentSize.height)
+                        : contentSize.height;
+
+                    if (newWidth !== currentWidth || newHeight !== currentHeight) {
+                        this._setCanvasSizeInt(newWidth, newHeight);
+                    }
+                    return;
+                }
                 let minWidth = 0;
                 let minHeight = 0;
                 if (this.containerElement) {
@@ -1979,16 +2236,65 @@ function ensureFabric() {
             }
         }
 
-        /**
-         * Expands the canvas so one object remains visible after an edit.
-         *
-         * @param {fabric.Object} fabricObject - Object whose bounds should fit inside the canvas.
-         * @param {number} [padding=10] - Extra canvas space after the object edge.
-         * @returns {void}
-         * @private
-         */
-        _expandCanvasToFitObject(fabricObject, padding = 10) {
-            this._expandCanvasToFitObjects([fabricObject], padding);
+        _captureImageDisplayBounds() {
+            if (!this.originalImage || !this.canvas) return null;
+            this.originalImage.setCoords();
+            const bounds = this.originalImage.getBoundingRect(true, true);
+            const width = Number(bounds && bounds.width);
+            const height = Number(bounds && bounds.height);
+            if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) return null;
+
+            return {
+                left: Number.isFinite(Number(bounds.left)) ? Number(bounds.left) : 0,
+                top: Number.isFinite(Number(bounds.top)) ? Number(bounds.top) : 0,
+                width,
+                height
+            };
+        }
+
+        _restoreImageDisplayBounds(displayBounds) {
+            if (!displayBounds || !this.originalImage || !this.canvas) return;
+            const imageWidth = Number(this.originalImage.width);
+            const imageHeight = Number(this.originalImage.height);
+            if (!Number.isFinite(imageWidth) || imageWidth <= 0 || !Number.isFinite(imageHeight) || imageHeight <= 0) return;
+
+            const scaleX = Number(displayBounds.width) / imageWidth;
+            const scaleY = Number(displayBounds.height) / imageHeight;
+            if (!Number.isFinite(scaleX) || scaleX <= 0 || !Number.isFinite(scaleY) || scaleY <= 0) return;
+
+            const left = Number(displayBounds.left) || 0;
+            const top = Number(displayBounds.top) || 0;
+            const requiredCanvasWidth = Math.max(1, Math.ceil(left + Number(displayBounds.width)));
+            const requiredCanvasHeight = Math.max(1, Math.ceil(top + Number(displayBounds.height)));
+            const currentCanvasWidth = Math.max(1, Math.round(Number(this.canvas.getWidth()) || 1));
+            const currentCanvasHeight = Math.max(1, Math.round(Number(this.canvas.getHeight()) || 1));
+            const layoutMode = this._getImageLayoutMode();
+            if (layoutMode === 'fit' || layoutMode === 'cover') {
+                const contentSize = this._getScrollableCanvasSize(requiredCanvasWidth, requiredCanvasHeight);
+                if (contentSize.width !== currentCanvasWidth || contentSize.height !== currentCanvasHeight) {
+                    this._setCanvasSizeInt(contentSize.width, contentSize.height);
+                }
+            } else if (requiredCanvasWidth > currentCanvasWidth || requiredCanvasHeight > currentCanvasHeight) {
+                this._setCanvasSizeInt(
+                    Math.max(currentCanvasWidth, requiredCanvasWidth),
+                    Math.max(currentCanvasHeight, requiredCanvasHeight)
+                );
+            }
+
+            this.originalImage.set({
+                originX: 'left',
+                originY: 'top',
+                left,
+                top,
+                scaleX,
+                scaleY
+            });
+            this.originalImage.setCoords();
+            this.baseImageScale = scaleX;
+            this.currentScale = 1;
+            this.currentRotation = Number(this.originalImage.angle) || 0;
+            this._updateInputs();
+            this.canvas.renderAll();
         }
 
         /** 
@@ -2004,7 +2310,14 @@ function ensureFabric() {
             } catch (error) {
                 return Promise.reject(error);
             }
-            return this.animationQueue.add(() => this._scaleImageImpl(factor, options))
+            return this.animationQueue.add(async () => {
+                const operationToken = this._beginBusyOperation('scaleImage');
+                try {
+                    await this._scaleImageImpl(factor, this._withInternalOperationOptions(operationToken, options));
+                } finally {
+                    this._endBusyOperation(operationToken);
+                }
+            })
                 .finally(() => {
                     if (!this._disposed && this.canvas) this._updateUI();
                 });
@@ -2056,7 +2369,7 @@ function ensureFabric() {
             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())) {
+            if ((this.isAnimating || (this.animationQueue && this.animationQueue.isBusy())) && !isOwnInternalOperation) {
                 throw new Error(`${operationName} cannot run while an animation is running`);
             }
             if (this._isLoading && !isOwnInternalOperation) {
@@ -2147,10 +2460,12 @@ function ensureFabric() {
         async _scaleImageImpl(factor, options = {}) {
             if (!this.originalImage || this._disposed) return;
             if (this.isAnimating) return;
+            const numericFactor = Number(factor);
+            if (!Number.isFinite(numericFactor)) return;
             const saveHistory = options.saveHistory !== false;
             let didStartAnimation = false;
             try {
-                factor = Math.max(this.options.minScale, Math.min(this.options.maxScale, factor));
+                factor = Math.max(this.options.minScale, Math.min(this.options.maxScale, numericFactor));
                 this.currentScale = factor;
                 this.isAnimating = true;
                 didStartAnimation = true;
@@ -2179,7 +2494,7 @@ function ensureFabric() {
                 this.canvas.getObjects().forEach(object => { if (object.maskId) this._syncMaskLabel(object); });
 
                 this._updateInputs();
-                if (saveHistory) this.saveState();
+                if (saveHistory) this.saveState(options);
             } finally {
                 if (didStartAnimation) {
                     this.isAnimating = false;
@@ -2202,7 +2517,14 @@ function ensureFabric() {
             } catch (error) {
                 return Promise.reject(error);
             }
-            return this.animationQueue.add(() => this._rotateImageImpl(degrees, options))
+            return this.animationQueue.add(async () => {
+                const operationToken = this._beginBusyOperation('rotateImage');
+                try {
+                    await this._rotateImageImpl(degrees, this._withInternalOperationOptions(operationToken, options));
+                } finally {
+                    this._endBusyOperation(operationToken);
+                }
+            })
                 .finally(() => {
                     if (!this._disposed && this.canvas) this._updateUI();
                 });
@@ -2218,7 +2540,8 @@ function ensureFabric() {
         async _rotateImageImpl(degrees, options = {}) {
             if (!this.originalImage || this._disposed) return;
             if (this.isAnimating) return;
-            if (isNaN(degrees)) return;
+            const numericDegrees = Number(degrees);
+            if (!Number.isFinite(numericDegrees)) return;
             const saveHistory = options.saveHistory !== false;
             const image = this.originalImage;
             const previousOriginX = image.originX || 'left';
@@ -2227,6 +2550,7 @@ function ensureFabric() {
             let didStartAnimation = false;
             let didCompleteRotation = false;
             try {
+                degrees = numericDegrees;
                 this.currentRotation = degrees;
                 this.isAnimating = true;
                 didStartAnimation = true;
@@ -2253,7 +2577,7 @@ function ensureFabric() {
                 this.canvas.getObjects().forEach(object => { if (object.maskId) this._syncMaskLabel(object); });
 
                 this._updateInputs();
-                if (saveHistory) this.saveState();
+                if (saveHistory) this.saveState(options);
                 didCompleteRotation = true;
             } finally {
                 if (!didCompleteRotation && !this._disposed && image) {
@@ -2282,19 +2606,22 @@ function ensureFabric() {
             }
 
             return this.animationQueue.add(async () => {
+                const operationToken = this._beginBusyOperation('resetImageTransform');
                 const before = this._lastSnapshot || this._captureCanvasStateOrThrow('resetImageTransform');
                 try {
-                    await this._scaleImageImpl(1, { saveHistory: false });
-                    await this._rotateImageImpl(0, { saveHistory: false });
+                    await this._scaleImageImpl(1, this._withInternalOperationOptions(operationToken, { saveHistory: false }));
+                    await this._rotateImageImpl(0, this._withInternalOperationOptions(operationToken, { saveHistory: false }));
                     const after = this._captureCanvasStateOrThrow('resetImageTransform');
                     this._pushStateTransition(before, after);
                 } catch (error) {
                     try {
-                        await this.loadFromState(before);
+                        await this.loadFromState(before, this._withInternalOperationOptions(operationToken));
                     } catch (restoreError) {
                         this._reportError('resetImageTransform rollback failed', restoreError);
                     }
                     throw error;
+                } finally {
+                    this._endBusyOperation(operationToken);
                 }
             }).finally(() => {
                 if (!this._disposed && this.canvas) this._updateUI();
@@ -2321,8 +2648,13 @@ function ensureFabric() {
          * @returns {Promise<void>} Resolves after Fabric has loaded the state and UI state has been refreshed.
          * @public
          */
-        loadFromState(serializedState) {
+        loadFromState(serializedState, options = {}) {
             if (!serializedState || !this.canvas || this._disposed) return Promise.resolve();
+            try {
+                this._assertIdleForOperation('loadFromState', options);
+            } catch (error) {
+                return Promise.reject(error);
+            }
             if (this._cropMode || this._cropRect) {
                 this._removeCropRect();
                 this._restoreCropObjectState();
@@ -2508,9 +2840,17 @@ function ensureFabric() {
          * @returns {void}
          * @public
          */
-        saveState() {
+        saveState(options = {}) {
             if (!this.canvas) return;
 
+            try {
+                this._assertIdleForOperation('saveState', options);
+            } catch (error) {
+                this._reportError('saveState blocked', error);
+                this._updateUI();
+                return;
+            }
+
             try {
                 const after = this._captureCanvasStateOrThrow('saveState');
                 const before = this._lastSnapshot || after;
@@ -2518,14 +2858,14 @@ function ensureFabric() {
                 let executedOnce = false;
 
                 const command = new Command(
-                    () => {
+                    (commandOptions = {}) => {
                         if (executedOnce) {
-                            return this.loadFromState(after);
+                            return this.loadFromState(after, commandOptions);
                         }
                         executedOnce = true;
                         return undefined;
                     },
-                    () => this.loadFromState(before)
+                    (commandOptions = {}) => this.loadFromState(before, commandOptions)
                 );
 
                 this.historyManager.execute(command);
@@ -2557,8 +2897,8 @@ function ensureFabric() {
             if (!this.historyManager) this.historyManager = new HistoryManager(this.maxHistorySize || 50);
 
             const command = new Command(
-                () => this.loadFromState(after),
-                () => this.loadFromState(before)
+                (commandOptions = {}) => this.loadFromState(after, commandOptions),
+                (commandOptions = {}) => this.loadFromState(before, commandOptions)
             );
             this.historyManager.push(command);
             this._lastSnapshot = after;
@@ -2572,8 +2912,17 @@ function ensureFabric() {
          * @public
          */
         undo() {
-            return this.historyManager.undo()
+            try {
+                this._assertIdleForOperation('undo');
+            } catch (error) {
+                return Promise.reject(error);
+            }
+            const operationToken = this._beginBusyOperation('undo');
+            return this.historyManager.undo(this._withInternalOperationOptions(operationToken))
                 .then(() => { this._updateUI(); })
+                .finally(() => {
+                    this._endBusyOperation(operationToken);
+                })
                 .catch(error => {
                     this._reportError('undo failed', error);
                     throw error;
@@ -2587,8 +2936,17 @@ function ensureFabric() {
          * @public
          */
         redo() {
-            return this.historyManager.redo()
+            try {
+                this._assertIdleForOperation('redo');
+            } catch (error) {
+                return Promise.reject(error);
+            }
+            const operationToken = this._beginBusyOperation('redo');
+            return this.historyManager.redo(this._withInternalOperationOptions(operationToken))
                 .then(() => { this._updateUI(); })
+                .finally(() => {
+                    this._endBusyOperation(operationToken);
+                })
                 .catch(error => {
                     this._reportError('redo failed', error);
                     throw error;
@@ -2712,33 +3070,70 @@ function ensureFabric() {
                 return value != null ? value : fallback;
             };
 
-            if (maskConfig.left === undefined && this._lastMask) {
-                const previousMask = this._lastMask;
-                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');
+            const rejectInvalidMask = (message, error = null) => {
+                this._reportWarning(`createMask: ${message}`, error);
+                return null;
+            };
+
+            const resolveNumber = (value, fallback, axis, fieldName, constraints = {}) => {
+                const resolvedValue = resolveValue(value, fallback, axis);
+                const numericValue = Number(resolvedValue);
+                if (!Number.isFinite(numericValue)) {
+                    throw new Error(`${fieldName} must be a finite number`);
+                }
+                if (constraints.positive && numericValue <= 0) {
+                    throw new Error(`${fieldName} must be greater than 0`);
+                }
+                if (constraints.nonNegative && numericValue < 0) {
+                    throw new Error(`${fieldName} must be 0 or greater`);
+                }
+                return numericValue;
+            };
+
+            try {
+                maskConfig.gap = resolveNumber(maskConfig.gap, 5, 'width', 'gap', { nonNegative: true });
+                maskConfig.width = resolveNumber(maskConfig.width, this.options.defaultMaskWidth, 'width', 'width', { positive: true });
+                maskConfig.height = resolveNumber(maskConfig.height, this.options.defaultMaskHeight, 'height', 'height', { positive: true });
+                maskConfig.angle = resolveNumber(maskConfig.angle, 0, 'width', 'angle');
+                maskConfig.alpha = Math.max(0, Math.min(1, resolveNumber(maskConfig.alpha, 0.5, 'width', 'alpha')));
+
+                if (maskConfig.left === undefined && this._lastMask) {
+                    const previousMask = this._lastMask;
+                    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 = resolveNumber(maskConfig.left, firstOffset, 'width', 'left');
+                    top = resolveNumber(maskConfig.top, firstOffset, 'height', 'top');
+                }
+            } catch (error) {
+                return rejectInvalidMask('invalid numeric configuration', error);
             }
 
-            maskConfig.width = resolveValue(maskConfig.width, this.options.defaultMaskWidth, 'width');
-            maskConfig.height = resolveValue(maskConfig.height, this.options.defaultMaskHeight, 'height');
             maskConfig.left = left;
             maskConfig.top = top;
 
             let mask;
             if (typeof maskConfig.fabricGenerator === 'function') {
-                mask = maskConfig.fabricGenerator(maskConfig, this.canvas, this.options);
+                try {
+                    mask = maskConfig.fabricGenerator(maskConfig, this.canvas, this.options);
+                } catch (error) {
+                    return rejectInvalidMask('fabricGenerator failed', error);
+                }
             } else {
                 switch (shapeType) {
                     case 'circle':
+                        try {
+                            maskConfig.radius = resolveNumber(maskConfig.radius, Math.min(maskConfig.width, maskConfig.height) / 2, 'min', 'radius', { positive: true });
+                        } catch (error) {
+                            return rejectInvalidMask('invalid circle radius', error);
+                        }
                         mask = new fabric.Circle({
                             left, top,
-                            radius: resolveValue(maskConfig.radius, Math.min(maskConfig.width, maskConfig.height) / 2, 'min'),
+                            radius: maskConfig.radius,
                             fill: maskConfig.color,
                             opacity: maskConfig.alpha,
                             angle: maskConfig.angle,
@@ -2746,10 +3141,16 @@ function ensureFabric() {
                         });
                         break;
                     case 'ellipse':
+                        try {
+                            maskConfig.rx = resolveNumber(maskConfig.rx, maskConfig.width / 2, 'width', 'rx', { positive: true });
+                            maskConfig.ry = resolveNumber(maskConfig.ry, maskConfig.height / 2, 'height', 'ry', { positive: true });
+                        } catch (error) {
+                            return rejectInvalidMask('invalid ellipse radius', error);
+                        }
                         mask = new fabric.Ellipse({
                             left, top,
-                            rx: resolveValue(maskConfig.rx, maskConfig.width / 2, 'width'),
-                            ry: resolveValue(maskConfig.ry, maskConfig.height / 2, 'height'),
+                            rx: maskConfig.rx,
+                            ry: maskConfig.ry,
                             fill: maskConfig.color,
                             opacity: maskConfig.alpha,
                             angle: maskConfig.angle,
@@ -2758,11 +3159,31 @@ function ensureFabric() {
                         break;
                     case 'polygon': {
                         let polygonPoints = maskConfig.points || [];
-                        if (Array.isArray(polygonPoints) && polygonPoints.length) {
-                            // Ensure numeric {x,y} objects for fabric.Polygon.
-                            polygonPoints = polygonPoints.map(point => Array.isArray(point)
-                                ? { x: Number(point[0]), y: Number(point[1]) }
-                                : { x: Number(point.x), y: Number(point.y) });
+                        if (!Array.isArray(polygonPoints) || polygonPoints.length < 3) {
+                            return rejectInvalidMask('polygon masks require at least three points');
+                        }
+                        try {
+                            polygonPoints = polygonPoints.map(point => {
+                                const x = Number(Array.isArray(point) ? point[0] : point.x);
+                                const y = Number(Array.isArray(point) ? point[1] : point.y);
+                                if (!Number.isFinite(x) || !Number.isFinite(y)) {
+                                    throw new Error('polygon point coordinates must be finite numbers');
+                                }
+                                return { x, y };
+                            });
+                        } catch (error) {
+                            return rejectInvalidMask('invalid polygon points', error);
+                        }
+                        const uniquePointKeys = new Set(polygonPoints.map(point => `${point.x}:${point.y}`));
+                        if (uniquePointKeys.size !== polygonPoints.length) {
+                            return rejectInvalidMask('polygon points must not contain duplicates');
+                        }
+                        const doubleArea = polygonPoints.reduce((area, point, index) => {
+                            const nextPoint = polygonPoints[(index + 1) % polygonPoints.length];
+                            return area + point.x * nextPoint.y - nextPoint.x * point.y;
+                        }, 0);
+                        if (Math.abs(doubleArea) < 0.000001) {
+                            return rejectInvalidMask('polygon masks must have a non-zero area');
                         }
                         mask = new fabric.Polygon(polygonPoints, {
                             left, top,
@@ -2775,10 +3196,16 @@ function ensureFabric() {
                     }
                     case 'rect':
                     default:
+                        try {
+                            if (maskConfig.rx != null) maskConfig.rx = resolveNumber(maskConfig.rx, 0, 'width', 'rx', { nonNegative: true });
+                            if (maskConfig.ry != null) maskConfig.ry = resolveNumber(maskConfig.ry, 0, 'height', 'ry', { nonNegative: true });
+                        } catch (error) {
+                            return rejectInvalidMask('invalid rectangle corner radius', error);
+                        }
                         mask = new fabric.Rect({
                             left, top,
-                            width: resolveValue(maskConfig.width, this.options.defaultMaskWidth, 'width'),
-                            height: resolveValue(maskConfig.height, this.options.defaultMaskHeight, 'height'),
+                            width: maskConfig.width,
+                            height: maskConfig.height,
                             fill: maskConfig.color,
                             opacity: maskConfig.alpha,
                             angle: maskConfig.angle,
@@ -2819,12 +3246,12 @@ function ensureFabric() {
                 originalStrokeWidth: Number.isFinite(Number(mask.strokeWidth)) ? Number(mask.strokeWidth) : 1
             });
             this._rebindMaskEvents(mask);
-            this._expandCanvasToFitObject(mask);
+            this._expandCanvasToFitObjects([mask]);
 
             // Store placement values so the next mask can be positioned beside this one.
             this._lastMaskInitialLeft = left;
             this._lastMaskInitialTop = top;
-            this._lastMaskInitialWidth = resolveValue(maskConfig.width, this.options.defaultMaskWidth, 'width');
+            this._lastMaskInitialWidth = maskConfig.width;
 
             const maskId = ++this.maskCounter;
             mask.set({
@@ -2842,7 +3269,12 @@ function ensureFabric() {
             this.canvas.renderAll();
             this.saveState();
 
-            if (typeof maskConfig.onCreate === 'function') maskConfig.onCreate(mask, this.canvas);
+            if (typeof maskConfig.onCreate === 'function') {
+                this._emitSafeCallback(
+                    () => maskConfig.onCreate(mask, this.canvas),
+                    'createMask onCreate callback failed'
+                );
+            }
             return mask;
         }
 
@@ -3057,8 +3489,15 @@ function ensureFabric() {
             this._removeLabelForMask(mask);
             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') {
+                let didLabelCreateThrow = false;
+                try {
+                    textObject = this.options.label.create(mask, fabric);
+                } catch (error) {
+                    didLabelCreateThrow = true;
+                    this._reportWarning('label.create() failed; using the default label', error);
+                    textObject = null;
+                }
+                if (!didLabelCreateThrow && (!textObject || typeof textObject.set !== 'function')) {
                     this._reportWarning('label.create() returned an invalid Fabric object; using the default label');
                     textObject = null;
                 }
@@ -3079,7 +3518,12 @@ function ensureFabric() {
                 };
                 if (this.options.label) {
                     if (typeof this.options.label.getText === 'function') {
-                        labelText = this.options.label.getText(mask, this._getMaskCreationIndex(mask));
+                        try {
+                            labelText = this.options.label.getText(mask, this._getMaskCreationIndex(mask));
+                        } catch (error) {
+                            this._reportWarning('label.getText() failed; using the mask name', error);
+                            labelText = mask.maskName;
+                        }
                     }
                     // Merge external styles
                     if (this.options.label.textOptions) {
@@ -3274,6 +3718,7 @@ function ensureFabric() {
             this._assertIdleForOperation('mergeMasks');
             const masks = this.canvas.getObjects().filter(object => object.maskId);
             if (!masks.length) return;
+            const beforeImageDisplayBounds = this._captureImageDisplayBounds();
             const beforeJson = this._serializeCanvasState();
             const operationToken = this._beginBusyOperation('mergeMasks');
 
@@ -3294,12 +3739,13 @@ function ensureFabric() {
                     preserveScroll: true,
                     resetMaskCounter: false
                 }));
+                this._restoreImageDisplayBounds(beforeImageDisplayBounds);
                 const afterJson = this._serializeCanvasState();
                 this._pushStateTransition(beforeJson, afterJson);
             } catch (error) {
                 this._reportError('merge error', error);
                 try {
-                    await this.loadFromState(beforeJson);
+                    await this.loadFromState(beforeJson, this._withInternalOperationOptions(operationToken));
                 } catch (restoreError) {
                     this._reportError('mergeMasks rollback failed', restoreError);
                 }
@@ -3361,13 +3807,19 @@ function ensureFabric() {
          */
         async exportImageBase64(options = {}) {
             if (!this.originalImage) throw new Error('No image loaded');
+            options = options || {};
             this._assertIdleForOperation('exportImageBase64', options);
+            const isNestedOperation = this._isOwnInternalOperation(options);
+            const operationToken = isNestedOperation
+                ? this._getInternalOperationToken(options)
+                : this._beginBusyOperation('exportImageBase64');
             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);
             const format = this._normalizeImageFormat(options.fileType || options.format);
 
-            if (!exportImageArea) {
+            try {
+                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 }));
@@ -3399,15 +3851,15 @@ function ensureFabric() {
                     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 = this._captureMaskExportBackups(masks);
-            const labelBackups = this._captureMaskLabelBackups(masks);
-            const activeObjectBackup = this._captureActiveObjectBackup();
+                // Render masks as export shapes without mutating their editable styles.
+                const masks = this.canvas.getObjects().filter(object => object.maskId);
+                const maskStyleBackups = this._captureMaskExportBackups(masks);
+                const labelBackups = this._captureMaskLabelBackups(masks);
+                const activeObjectBackup = this._captureActiveObjectBackup();
 
-            try {
+                try {
                 // Labels are UI overlays and should not be part of the flattened export.
                 masks.forEach(mask => this._removeLabelForMask(mask));
                 this.canvas.discardActiveObject();
@@ -3438,6 +3890,9 @@ function ensureFabric() {
                 this._restoreActiveObjectBackup(activeObjectBackup);
                 this.canvas.renderAll();
             }
+            } finally {
+                if (!isNestedOperation) this._endBusyOperation(operationToken);
+            }
         }
 
         /**
@@ -3471,7 +3926,12 @@ function ensureFabric() {
          */
         async exportImageFile(options = {}) {
             if (!this.originalImage) throw new Error('No image loaded');
-            this._assertIdleForOperation('exportImageFile');
+            options = options || {};
+            this._assertIdleForOperation('exportImageFile', options);
+            const isNestedOperation = this._isOwnInternalOperation(options);
+            const operationToken = isNestedOperation
+                ? this._getInternalOperationToken(options)
+                : this._beginBusyOperation('exportImageFile');
             const {
                 mergeMask = true,
                 fileType = 'jpeg',
@@ -3483,52 +3943,56 @@ function ensureFabric() {
             const safeFileType = this._normalizeImageFormat(fileType);
             const normalizedQuality = this._normalizeQuality(quality);
 
-            // Generate the data URL in the requested export mode.
-            let imageBase64;
-            if (mergeMask) {
-                imageBase64 = await this.exportImageBase64({
-                    exportImageArea: true,
-                    multiplier,
-                    quality: normalizedQuality,
-                    fileType: safeFileType
-                });
-            } else {
-                imageBase64 = await this.exportImageBase64({
-                    exportImageArea: false,
-                    multiplier,
-                    quality: normalizedQuality,
-                    fileType: safeFileType
-                });
-            }
+            try {
+                // Generate the data URL in the requested export mode.
+                let imageBase64;
+                if (mergeMask) {
+                    imageBase64 = await this.exportImageBase64(this._withInternalOperationOptions(operationToken, {
+                        exportImageArea: true,
+                        multiplier,
+                        quality: normalizedQuality,
+                        fileType: safeFileType
+                    }));
+                } else {
+                    imageBase64 = await this.exportImageBase64(this._withInternalOperationOptions(operationToken, {
+                        exportImageArea: false,
+                        multiplier,
+                        quality: normalizedQuality,
+                        fileType: safeFileType
+                    }));
+                }
 
-            // Convert to the required image format
-            let imageDataUrl = imageBase64;
-            if (!imageDataUrl.startsWith(`data:image/${safeFileType}`)) {
-                // Redraw the exported data URL when the browser returned a different image format.
-                imageDataUrl = await new Promise((resolve, reject) => {
-                    const imageElement = new window.Image();
-                    imageElement.crossOrigin = "Anonymous";
-                    imageElement.onload = () => {
-                        try {
-                            const offscreenCanvas = document.createElement('canvas');
-                            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}`, normalizedQuality);
-                            resolve(convertedDataUrl);
-                        } catch (error) { reject(error); }
-                    };
-                    imageElement.onerror = reject;
-                    imageElement.src = imageBase64;
-                });
-            }
+                // Convert to the required image format
+                let imageDataUrl = imageBase64;
+                if (!imageDataUrl.startsWith(`data:image/${safeFileType}`)) {
+                    // Redraw the exported data URL when the browser returned a different image format.
+                    imageDataUrl = await new Promise((resolve, reject) => {
+                        const imageElement = new window.Image();
+                        imageElement.crossOrigin = "Anonymous";
+                        imageElement.onload = () => {
+                            try {
+                                const offscreenCanvas = document.createElement('canvas');
+                                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}`, normalizedQuality);
+                                resolve(convertedDataUrl);
+                            } catch (error) { reject(error); }
+                        };
+                        imageElement.onerror = reject;
+                        imageElement.src = imageBase64;
+                    });
+                }
 
-            // Convert the final data URL to a File with the requested MIME type.
-            const bytes = this._decodeBase64Payload(imageDataUrl.split(',')[1]);
-            const mime = `image/${safeFileType}`;
-            return new File([bytes], fileName, { type: mime });
+                // Convert the final data URL to a File with the requested MIME type.
+                const bytes = this._decodeDataUrlPayload(imageDataUrl);
+                const mime = `image/${safeFileType}`;
+                return new File([bytes], fileName, { type: mime });
+            } finally {
+                if (!isNestedOperation) this._endBusyOperation(operationToken);
+            }
         }
 
         _clearMaskPlacementMemory() {
@@ -3538,7 +4002,7 @@ function ensureFabric() {
             this._lastMaskInitialWidth = null;
         }
 
-        async _restoreStateAfterCropFailure(beforeJson, message, error) {
+        async _restoreStateAfterCropFailure(beforeJson, message, error, options = {}) {
             this._reportError(message, error);
 
             if (this._cropRect && this.canvas) this._removeCropRect();
@@ -3551,7 +4015,7 @@ function ensureFabric() {
 
             if (beforeJson) {
                 try {
-                    await this.loadFromState(beforeJson);
+                    await this.loadFromState(beforeJson, options);
                 } catch (restoreError) {
                     this._reportError('applyCrop: rollback failed', restoreError);
                 }
@@ -3596,6 +4060,54 @@ function ensureFabric() {
             this._cropHandlers = [];
         }
 
+        _getCropRectContentBounds(cropRect) {
+            if (!cropRect) return { left: 0, top: 0, width: 1, height: 1 };
+            const width = Math.max(1, (Number(cropRect.width) || 1) * Math.abs(Number(cropRect.scaleX) || 1));
+            const height = Math.max(1, (Number(cropRect.height) || 1) * Math.abs(Number(cropRect.scaleY) || 1));
+            return {
+                left: Number(cropRect.left) || 0,
+                top: Number(cropRect.top) || 0,
+                width,
+                height
+            };
+        }
+
+        _getCropRectRawBounds(cropRect) {
+            if (!cropRect) return { left: NaN, top: NaN, width: NaN, height: NaN };
+            return {
+                left: Number(cropRect.left),
+                top: Number(cropRect.top),
+                width: Number(cropRect.width) * Math.abs(Number(cropRect.scaleX)),
+                height: Number(cropRect.height) * Math.abs(Number(cropRect.scaleY))
+            };
+        }
+
+        _isValidCropRegion(cropBounds, imageBounds) {
+            if (!cropBounds || !imageBounds) return false;
+            const left = Number(cropBounds.left);
+            const top = Number(cropBounds.top);
+            const width = Number(cropBounds.width);
+            const height = Number(cropBounds.height);
+            const imageLeft = Number(imageBounds.left);
+            const imageTop = Number(imageBounds.top);
+            const imageWidth = Number(imageBounds.width);
+            const imageHeight = Number(imageBounds.height);
+            if (![left, top, width, height, imageLeft, imageTop, imageWidth, imageHeight].every(Number.isFinite)) return false;
+            if (width <= 0 || height <= 0 || imageWidth <= 0 || imageHeight <= 0) return false;
+
+            const right = left + width;
+            const bottom = top + height;
+            const imageRight = imageLeft + imageWidth;
+            const imageBottom = imageTop + imageHeight;
+            const overlapsImage = left < imageRight && right > imageLeft && top < imageBottom && bottom > imageTop;
+            if (!overlapsImage) return false;
+
+            const canvasWidth = this.canvas ? Number(this.canvas.getWidth()) : NaN;
+            const canvasHeight = this.canvas ? Number(this.canvas.getHeight()) : NaN;
+            if (!Number.isFinite(canvasWidth) || !Number.isFinite(canvasHeight) || canvasWidth <= 0 || canvasHeight <= 0) return false;
+            return left < canvasWidth && right > 0 && top < canvasHeight && bottom > 0;
+        }
+
         /**
          * Enters crop mode by creating a resizable crop rectangle above the base image.
          *
@@ -3607,6 +4119,10 @@ function ensureFabric() {
          */
         enterCropMode() {
             if (!this.canvas || !this.originalImage || this._cropMode) return;
+            if (this._isApplyingCrop) {
+                this._reportWarning('enterCropMode ignored because a crop is already being applied');
+                return;
+            }
             if (!this._canMutateNow('enterCropMode')) return;
             if (!this.isImageLoaded()) return;
             this._removeCropRect();
@@ -3626,14 +4142,19 @@ function ensureFabric() {
             const padding = (this.options.crop && this.options.crop.padding) ? this.options.crop.padding : 10;
             const left = Math.max(0, Math.floor(imageBounds.left + padding));
             const top = Math.max(0, Math.floor(imageBounds.top + padding));
-            const maxCropWidth = Math.max(1, Math.floor(imageBounds.width - padding * 2));
-            const maxCropHeight = Math.max(1, Math.floor(imageBounds.height - padding * 2));
+            const maxCropWidth = Math.max(1, Math.floor(imageBounds.width));
+            const maxCropHeight = Math.max(1, Math.floor(imageBounds.height));
             const configuredMinWidth = Math.max(1, Number(this.options.crop.minWidth) || 50);
             const configuredMinHeight = Math.max(1, Number(this.options.crop.minHeight) || 50);
             const minCropWidth = Math.min(configuredMinWidth, maxCropWidth);
             const minCropHeight = Math.min(configuredMinHeight, maxCropHeight);
             const width = minCropWidth;
             const height = minCropHeight;
+            const requestedCropRotation = !!(this.options.crop && this.options.crop.allowRotationOfCropRect);
+            if (requestedCropRotation && !this._cropRotationWarningEmitted) {
+                this._cropRotationWarningEmitted = true;
+                this._reportWarning('crop.allowRotationOfCropRect is disabled in v1.x because rotated crop export is not supported');
+            }
 
             // Visual style for the temporary crop rectangle.
             const cropRect = new fabric.Rect({
@@ -3645,8 +4166,8 @@ function ensureFabric() {
                 strokeWidth: 1,
                 strokeUniform: true,
                 selectable: true,
-                hasRotatingPoint: !!(this.options.crop && this.options.crop.allowRotationOfCropRect),
-                lockRotation: !(this.options.crop && this.options.crop.allowRotationOfCropRect),
+                hasRotatingPoint: false,
+                lockRotation: true,
                 cornerSize: 8,
                 objectCaching: false,
                 originX: 'left',
@@ -3689,7 +4210,7 @@ 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 cropBounds = this._getCropRectContentBounds(cropRect);
                     const imageLeft = Number(imageBounds.left) || 0;
                     const imageTop = Number(imageBounds.top) || 0;
                     const imageRight = imageLeft + (Number(imageBounds.width) || 0);
@@ -3741,6 +4262,10 @@ function ensureFabric() {
          * @public
          */
         cancelCrop() {
+            if (this._isApplyingCrop) {
+                this._reportWarning('cancelCrop ignored because a crop is already being applied');
+                return;
+            }
             if (!this.canvas || !this._cropMode) return;
             this._removeCropRect();
             this._restoreCropObjectState();
@@ -3767,11 +4292,26 @@ function ensureFabric() {
          */
         async applyCrop() {
             if (!this.canvas || !this._cropMode || !this._cropRect) return;
+            if (this._isApplyingCrop) {
+                this._reportWarning('applyCrop ignored because a crop is already being applied');
+                return;
+            }
             this._assertIdleForOperation('applyCrop');
+            this._isApplyingCrop = true;
+            const operationToken = this._beginBusyOperation('applyCrop');
+            const internalOptions = this._withInternalOperationOptions(operationToken);
 
+            try {
             // Fabric does not update control coordinates automatically after programmatic transforms.
             this._cropRect.setCoords();
-            const rectBounds = this._cropRect.getBoundingRect(true, true);
+            this.originalImage.setCoords();
+            const imageBounds = this.originalImage.getBoundingRect(true, true);
+            const rawCropBounds = this._getCropRectRawBounds(this._cropRect);
+            if (!this._isValidCropRegion(rawCropBounds, imageBounds)) {
+                this._reportWarning('applyCrop: crop region is invalid');
+                return;
+            }
+            const rectBounds = this._getCropRectContentBounds(this._cropRect);
 
             const cropRegion = this._getClampedCanvasRegion(rectBounds, { includePartialPixels: false });
             const shouldPreserveMasks = !!(this.options.crop && this.options.crop.preserveMasksAfterCrop);
@@ -3786,7 +4326,13 @@ function ensureFabric() {
                 beforeJson = null;
             }
             if (!beforeJson) {
-                this.cancelCrop();
+                this._removeCropRect();
+                this._cropMode = false;
+                this.canvas.selection = !!this._prevSelectionSetting;
+                this._prevSelectionSetting = undefined;
+                this.canvas.discardActiveObject();
+                this._updateUI();
+                this.canvas.renderAll();
                 return;
             }
 
@@ -3817,7 +4363,7 @@ function ensureFabric() {
                     this.canvas.renderAll();
                 }
             } catch (error) {
-                await this._restoreStateAfterCropFailure(beforeJson, 'applyCrop: failed to prepare masks', error);
+                await this._restoreStateAfterCropFailure(beforeJson, 'applyCrop: failed to prepare masks', error, internalOptions);
                 return;
             }
 
@@ -3838,13 +4384,13 @@ function ensureFabric() {
                     format: 'jpeg'
                 });
             } catch (error) {
-                await this._restoreStateAfterCropFailure(beforeJson, 'applyCrop: failed to create cropped image', error);
+                await this._restoreStateAfterCropFailure(beforeJson, 'applyCrop: failed to create cropped image', error, internalOptions);
                 return;
             }
 
             // Load the cropped image as the new base image.
             try {
-                await this.loadImage(croppedBase64, { resetMaskCounter: false });
+                await this.loadImage(croppedBase64, this._withInternalOperationOptions(operationToken, { resetMaskCounter: false }));
                 if (preservedMasks.length) {
                     preservedMasks.forEach(mask => {
                         this._rebindMaskEvents(mask);
@@ -3857,7 +4403,7 @@ function ensureFabric() {
                     this.canvas.renderAll();
                 }
             } catch (error) {
-                await this._restoreStateAfterCropFailure(beforeJson, 'applyCrop: loadImage(croppedBase64) failed', error);
+                await this._restoreStateAfterCropFailure(beforeJson, 'applyCrop: loadImage(croppedBase64) failed', error, internalOptions);
                 return;
             }
 
@@ -3879,6 +4425,10 @@ function ensureFabric() {
             // Refresh UI state after crop completion.
             this._updateUI();
             this.canvas.renderAll();
+            } finally {
+                this._isApplyingCrop = false;
+                this._endBusyOperation(operationToken);
+            }
         }
 
 
@@ -3913,10 +4463,12 @@ function ensureFabric() {
             const isBusy = this.isBusy();
 
             if (isInCropMode) {
-                // Disable all controls except the crop action buttons while crop mode is active.
+                // Disable operation controls while keeping canvas interaction and viewport scrolling available.
+                const cropInteractionKeys = new Set(['canvas', 'canvasContainer', 'imagePlaceholder', 'imgPlaceholder']);
                 for (const key of Object.keys(this.elements || {})) {
                     const element = this._getElement(key);
                     if (!element) continue;
+                    if (cropInteractionKeys.has(key)) continue;
                     if (key === 'applyCropButton' || key === 'cancelCropButton' || key === 'applyCropBtn' || key === 'cancelCropBtn') {
                         this._setDisabled(key, false);
                     } else {
@@ -3956,9 +4508,44 @@ function ensureFabric() {
          * @param {boolean} disabled - If true, disables the element; otherwise enables.
          * @private
          */
+        _rememberElementDisabledState(key, element) {
+            if (!element) return;
+            if (!this._elementOriginalDisabledState) this._elementOriginalDisabledState = new Map();
+            if (this._elementOriginalDisabledState.has(key)) return;
+            this._elementOriginalDisabledState.set(key, {
+                element,
+                hasDisabledProperty: 'disabled' in element,
+                disabled: ('disabled' in element) ? !!element.disabled : undefined,
+                ariaDisabled: element.getAttribute ? element.getAttribute('aria-disabled') : null,
+                pointerEvents: element.style ? (element.style.pointerEvents || '') : ''
+            });
+        }
+
+        _restoreElementDisabledStates() {
+            if (!this._elementOriginalDisabledState) return;
+            for (const state of this._elementOriginalDisabledState.values()) {
+                const element = state && state.element;
+                if (!element) continue;
+                try {
+                    if (state.hasDisabledProperty && 'disabled' in element) {
+                        element.disabled = !!state.disabled;
+                    }
+                    if (element.getAttribute && element.setAttribute && element.removeAttribute) {
+                        if (state.ariaDisabled === null) {
+                            element.removeAttribute('aria-disabled');
+                        } else {
+                            element.setAttribute('aria-disabled', state.ariaDisabled);
+                        }
+                    }
+                    if (element.style) element.style.pointerEvents = state.pointerEvents || '';
+                } catch (error) { void error; }
+            }
+        }
+
         _setDisabled(key, disabled) {
             const element = this._getElement(key);
             if (!element) return;
+            this._rememberElementDisabledState(key, element);
             if ('disabled' in element) {
                 element.disabled = !!disabled;
                 return;
@@ -3988,7 +4575,6 @@ function ensureFabric() {
          * @private
          */
         _updatePlaceholderStatus() {
-            if (!this.options.showPlaceholder) return;
             this._setPlaceholderVisible(!this.originalImage);
         }
 
@@ -3999,10 +4585,11 @@ function ensureFabric() {
          * @private
          */
         _setPlaceholderVisible(show) {
-            if (this.placeholderElement) this._setElementVisible(this.placeholderElement, show);
+            const shouldShowPlaceholder = !!show && this.options.showPlaceholder !== false;
+            if (this.placeholderElement) this._setElementVisible(this.placeholderElement, shouldShowPlaceholder);
             const canvasVisibilityElement = this._getCanvasVisibilityElement();
             if (canvasVisibilityElement && canvasVisibilityElement !== this.placeholderElement) {
-                this._setElementVisible(canvasVisibilityElement, !show);
+                this._setElementVisible(canvasVisibilityElement, !shouldShowPlaceholder);
             }
         }
 
@@ -4088,6 +4675,9 @@ function ensureFabric() {
             } catch (error) { void error; }
 
             if (this._cropRect) this._removeCropRect();
+            this._isApplyingCrop = false;
+
+            try { this._restoreElementDisabledStates(); } catch (error) { void error; }
 
             if (this.containerElement && this._containerOriginalOverflow) {
                 try { this._restoreContainerOverflowState(); } catch (error) { void error; }
@@ -4125,6 +4715,7 @@ function ensureFabric() {
             this._handlersByElementKey = {};
             this._elementCache = {};
             this._elementOriginalPointerEvents = new Map();
+            this._elementOriginalDisabledState = new Map();
             this._clearMaskPlacementMemory();
             this.originalImage = null;
             this.baseImageScale = 1;
@@ -4133,6 +4724,7 @@ function ensureFabric() {
             this.isAnimating = false;
             this._isLoading = false;
             this._cropMode = false;
+            this._isApplyingCrop = false;
             this._cropRect = null;
             this._cropHandlers = [];
             this._cropPrevEvented = null;
@@ -4168,6 +4760,7 @@ function ensureFabric() {
 
     /**
      * @callback HistoryTaskCallback
+     * @param {Object} [options] - Internal operation options passed by the editor.
      * @returns {void|Promise<void>} Result of a history operation.
      */
 
@@ -4304,12 +4897,13 @@ function ensureFabric() {
          * @param {number} [maxSize=50] - Maximum number of commands to keep in history.
          */
         constructor(maxSize = 50) {
+            const numericMaxSize = Number(maxSize);
             /** @type {Array<Command>} */
             this.history = [];
             /** @type {number} */
             this.currentIndex = -1;
             /** @type {number} */
-            this.maxSize = maxSize;
+            this.maxSize = Number.isFinite(numericMaxSize) && numericMaxSize > 0 ? Math.floor(numericMaxSize) : 50;
             /** @type {Promise<void>} */
             this.pending = Promise.resolve();
         }
@@ -4389,11 +4983,11 @@ function ensureFabric() {
          *
          * @returns {Promise<void>} Resolves after the undo task completes.
          */
-        undo() {
+        undo(options = {}) {
             return this.enqueue(async () => {
                 if (this.currentIndex >= 0) {
                     const index = this.currentIndex;
-                    await this.history[index].undo();
+                    await this.history[index].undo(options);
                     this.currentIndex = index - 1;
                 }
             });
@@ -4404,11 +4998,11 @@ function ensureFabric() {
          *
          * @returns {Promise<void>} Resolves after the redo task completes.
          */
-        redo() {
+        redo(options = {}) {
             return this.enqueue(async () => {
                 if (this.currentIndex < this.history.length - 1) {
                     const index = this.currentIndex + 1;
-                    await this.history[index].execute();
+                    await this.history[index].execute(options);
                     this.currentIndex = index;
                 }
             });