@bensitu/image-editor 2.0.0 → 2.2.0

package/README.md

@@ -6,15 +6,11 @@
 
 A lightweight, TypeScript-first canvas image editor built on top of
 [Fabric.js](https://fabricjs.com/) v7. `ImageEditor` wraps a Fabric canvas
-with image loading, scale and rotation, mask creation, crop, history
-(undo/redo), and base64/file export — exposed as a single canonical class
+with image loading, scale and rotation, mask creation, Text and Draw
+annotations, crop, Mosaic mode, history (undo/redo), layer operations, and
+base64/file export — exposed as a single canonical class
 with a stable public surface.
 
-> **v2.0.0 is a behavior-preserving migration.** The v1 deprecated method
-> and property aliases have been removed in favor of the canonical names
-> documented below. See [`CHANGELOG.md`](./CHANGELOG.md) for the complete
-> rename map.
-
 ## Demo
 
 [https://bensitu.github.io/image-editor/](https://bensitu.github.io/image-editor/)
@@ -33,8 +29,15 @@ with a stable public surface.
   interleave
 - Bounded history stack with idempotent dispose
 - Crop session with mask preservation toggle and atomic apply/cancel
+- Mosaic mode with circular brush preview, runtime brush/block controls, and
+  one undo step per successful pixelation click
+- Unified editor-owned object model for base images, masks, annotations, and
+  session overlays
+- Text annotations, Draw mode, annotation update/delete APIs, and layer
+  operations
 - Base64 and `File` exports with PNG/JPEG/WebP support, configurable
-  multiplier, and mask compositing
+  multiplier, independent mask/annotation rendering toggles, and state-mutating
+  mask/annotation merge APIs
 
 ## Requirements
 
@@ -130,19 +133,50 @@ resolve to `undefined`.
 <button id="createMaskButton">Add Mask</button>
 <button id="removeSelectedMaskButton">Remove Mask</button>
 <button id="removeAllMasksButton">Remove All Masks</button>
+<ul id="maskList"></ul>
+
+<button id="enterTextModeButton">Text</button>
+<button id="exitTextModeButton">Exit Text</button>
+<input id="textColorInput" type="color" value="#ff0000" />
+<input id="textFontSizeInput" type="number" min="8" max="160" value="32" />
+
+<button id="enterDrawModeButton">Draw</button>
+<button id="exitDrawModeButton">Exit Draw</button>
+<input id="drawColorInput" type="color" value="#ff0000" />
+<input id="drawBrushSizeInput" type="range" min="1" max="80" value="8" />
+
+<button id="removeSelectedAnnotationButton">Remove Annotation</button>
+<button id="removeAllAnnotationsButton">Remove All Annotations</button>
+<button id="deleteSelectedObjectButton">Delete Selected</button>
+<button id="bringSelectedObjectForwardButton">Forward</button>
+<button id="sendSelectedObjectBackwardButton">Backward</button>
+<button id="bringSelectedObjectToFrontButton">Front</button>
+<button id="sendSelectedObjectToBackButton">Back</button>
+<ul id="annotationList"></ul>
 
 <button id="enterCropModeButton">Crop</button>
 <button id="applyCropButton">Apply Crop</button>
 <button id="cancelCropButton">Cancel Crop</button>
 
-<button id="mergeMasksButton">Merge</button>
+<button id="enterMosaicModeButton">Mosaic</button>
+<button id="exitMosaicModeButton">Exit Mosaic</button>
+<label>
+    Brush size
+    <input id="mosaicBrushSizeInput" type="range" min="8" max="160" step="1" value="48" />
+</label>
+<label>
+    Block size
+    <input id="mosaicBlockSizeInput" type="range" min="2" max="40" step="1" value="8" />
+</label>
+
+<button id="mergeMasksButton">Merge Masks</button>
+<button id="mergeAnnotationsButton">Merge Annotations</button>
 <button id="downloadImageButton">Download</button>
 <button id="undoButton">Undo</button>
 <button id="redoButton">Redo</button>
 <button id="resetImageTransformButton">Reset</button>
 
 <input id="imageInput" type="file" accept="image/*" />
-<ul id="maskList"></ul>
 ```
 
 ### TypeScript / ESM
@@ -156,6 +190,18 @@ const editor = new ImageEditor(fabric, {
     canvasWidth: 800,
     canvasHeight: 600,
     backgroundColor: '#ffffff',
+    defaultMosaicConfig: {
+        brushSize: 48,
+        blockSize: 8,
+    },
+    defaultTextConfig: {
+        fill: '#ff0000',
+        fontSize: 32,
+    },
+    defaultDrawConfig: {
+        color: '#ff0000',
+        brushSize: 8,
+    },
 } satisfies ImageEditorOptions);
 
 editor.init({
@@ -169,16 +215,37 @@ editor.init({
     createMaskButton: 'createMaskButton',
     removeSelectedMaskButton: 'removeSelectedMaskButton',
     removeAllMasksButton: 'removeAllMasksButton',
+    maskList: 'maskList',
     enterCropModeButton: 'enterCropModeButton',
     applyCropButton: 'applyCropButton',
     cancelCropButton: 'cancelCropButton',
+    enterMosaicModeButton: 'enterMosaicModeButton',
+    exitMosaicModeButton: 'exitMosaicModeButton',
+    mosaicBrushSizeInput: 'mosaicBrushSizeInput',
+    mosaicBlockSizeInput: 'mosaicBlockSizeInput',
+    enterTextModeButton: 'enterTextModeButton',
+    exitTextModeButton: 'exitTextModeButton',
+    textColorInput: 'textColorInput',
+    textFontSizeInput: 'textFontSizeInput',
+    enterDrawModeButton: 'enterDrawModeButton',
+    exitDrawModeButton: 'exitDrawModeButton',
+    drawColorInput: 'drawColorInput',
+    drawBrushSizeInput: 'drawBrushSizeInput',
+    removeSelectedAnnotationButton: 'removeSelectedAnnotationButton',
+    removeAllAnnotationsButton: 'removeAllAnnotationsButton',
+    deleteSelectedObjectButton: 'deleteSelectedObjectButton',
+    mergeAnnotationsButton: 'mergeAnnotationsButton',
+    bringSelectedObjectForwardButton: 'bringSelectedObjectForwardButton',
+    sendSelectedObjectBackwardButton: 'sendSelectedObjectBackwardButton',
+    bringSelectedObjectToFrontButton: 'bringSelectedObjectToFrontButton',
+    sendSelectedObjectToBackButton: 'sendSelectedObjectToBackButton',
+    annotationList: 'annotationList',
     mergeMasksButton: 'mergeMasksButton',
     downloadImageButton: 'downloadImageButton',
     undoButton: 'undoButton',
     redoButton: 'redoButton',
     resetImageTransformButton: 'resetImageTransformButton',
     imageInput: 'imageInput',
-    maskList: 'maskList',
 });
 
 // Load an image programmatically (base64 data URL).
@@ -187,6 +254,9 @@ await editor.loadImage('data:image/jpeg;base64,...');
 // Add a rectangular mask, then export the result as base64.
 const mask: MaskConfig = { shape: 'rect', width: 120, height: 80, left: '25%', top: '25%' };
 editor.createMask(mask);
+editor.createTextAnnotation({ text: 'Label', left: 120, top: 80 });
+editor.enterDrawMode();
+editor.setDrawConfig({ color: '#00aaff', brushSize: 10 });
 
 const dataUrl = await editor.exportImageBase64({ fileType: 'png' });
 ```
@@ -200,18 +270,34 @@ const { ImageEditor } = require('@bensitu/image-editor');
 const editor = new ImageEditor(fabric, { canvasWidth: 800, canvasHeight: 600 });
 ```
 
-In v2, `require('@bensitu/image-editor')` returns a namespace object with
-`ImageEditor`, `default`, and `isMaskObject`; it does not return the
-constructor directly.
+In v2.2, `require('@bensitu/image-editor')` returns a namespace object with
+`ImageEditor`, `default`, and the editor object guards
+(`isBaseImageObject`, `isMaskObject`, `isAnnotationObject`,
+`isTextAnnotationObject`, `isDrawAnnotationObject`, `isSessionObject`, and
+`isEditableOverlayObject`); it does not return the constructor directly.
 
 ## Public API
 
 `ImageEditor` is the only public class. The package barrel re-exports it as
-both the default export and a named export, alongside `isMaskObject` and the
-documented public types. Internal helpers (animation queue, command, history
+both the default export and a named export, alongside the editor object guards
+and the documented public types. Internal helpers (animation queue, command, history
 manager, controllers, services, managers, utility modules) are intentionally
 not exported and may change without notice.
 
+### Object model
+
+Every editor-owned Fabric object carries strict `editorObjectKind` metadata:
+
+| Kind         | Meaning                                                                  |
+| ------------ | ------------------------------------------------------------------------ |
+| `baseImage`  | The committed image at the bottom of the stack.                          |
+| `mask`       | Editable mask overlay with required `maskId`, `maskUid`, and `maskName`. |
+| `annotation` | Editable Text or Draw overlay. Masks are not annotations.                |
+| `session`    | Internal crop labels, mask labels, Mosaic previews, and tool previews.   |
+
+Session objects are never persisted, exported, or user-deletable. Strict type
+guards reject legacy mask-like objects that do not carry `editorObjectKind`.
+
 ### Constructor
 
 ```ts
@@ -232,22 +318,31 @@ new ImageEditor(options?: ImageEditorOptions)  // UMD: reads globalThis.fabric
 | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `loadImage(base64, options?)` | Load an image from a `data:image/...` URL. Returns `Promise<void>`. Transactional: any failure restores the prior canvas, scroll, overflow, and snapshot state. |
 | `isImageLoaded()`             | Returns `true` if a valid image is currently loaded on the canvas.                                                                                              |
-| `isBusy()`                    | Returns `true` while the editor is loading, animating, or in crop mode.                                                                                         |
+| `isBusy()`                    | Returns `true` while the editor is loading, animating, or in Crop, Mosaic, Text, or Draw mode.                                                                  |
 | `setLayoutMode(mode)`         | Select the layout strategy for future image loads. `mode` is `'fit'`, `'cover'`, or `'expand'`.                                                                 |
 
 `LoadImageOptions` currently includes `preserveScroll?: boolean` for
 preserving the container's scroll position across both successful loads and
 rollback paths.
 
-Use `setLayoutMode()` instead of mutating internal options when a UI lets users
-choose how the next image should be placed:
+Use `defaultLayoutMode` to choose the initial image-load strategy, then call
+`setLayoutMode()` when a UI should change how future images are placed:
 
 ```ts
-editor.setLayoutMode('fit');
+const editor = new ImageEditor(fabric, {
+    defaultLayoutMode: 'fit',
+});
+
+await editor.loadImage(imageA);
+
+// Future loads use cover. The current image is not re-laid out immediately.
 editor.setLayoutMode('cover');
-editor.setLayoutMode('expand');
+await editor.loadImage(imageB);
 ```
 
+Invalid JavaScript `defaultLayoutMode` values fall back to `'expand'`.
+Invalid `setLayoutMode()` calls are ignored and preserve the current mode.
+
 File-input helpers accept JPG, PNG, WebP, GIF, and BMP files. GIF and BMP are
 decoded as static raster input for canvas editing; GIF animation and BMP/GIF
 source-format preservation are not retained. Export output remains controlled by
@@ -272,6 +367,29 @@ the JPEG, PNG, or WebP export options.
 `MaskConfig` supports rect, circle, ellipse, polygon, and a custom
 `fabricGenerator`. Falsy values in `styles` (`0`, `false`, `null`, `''`,
 `NaN`) are applied verbatim.
+Every mask is marked as `editorObjectKind: 'mask'` and includes required
+`maskId`, `maskUid`, and `maskName` metadata.
+
+Use `defaultMaskConfig` to define constructor-level defaults for masks created
+through either `createMask()` or the built-in `createMaskButton`. Per-call
+`createMask(config)` values override `defaultMaskConfig`.
+
+```ts
+const editor = new ImageEditor(fabric, {
+    defaultMaskConfig: {
+        color: 'rgba(255, 0, 0, 0.35)',
+        alpha: 0.35,
+        styles: {
+            stroke: '#ff0000',
+            strokeWidth: 2,
+            strokeDashArray: [6, 4],
+        },
+    },
+});
+
+editor.createMask(); // Uses defaultMaskConfig.
+editor.createMask({ color: 'rgba(0, 128, 255, 0.35)' }); // Per-call override.
+```
 
 ### Crop
 
@@ -281,35 +399,146 @@ the JPEG, PNG, or WebP export options.
 | `applyCrop()`     | Apply the current crop region. Atomic: failure rolls back to the pre-crop snapshot.  |
 | `cancelCrop()`    | Cancel crop mode and restore the prior canvas state without pushing a history entry. |
 
+### Mosaic mode
+
+| Method                     | Description                                                            |
+| -------------------------- | ---------------------------------------------------------------------- |
+| `enterMosaicMode()`        | Enter circular-brush Mosaic mode and show the hover preview on canvas. |
+| `exitMosaicMode()`         | Leave Mosaic mode and remove preview/session handlers.                 |
+| `isMosaicMode()`           | Returns `true` while a Mosaic session is active.                       |
+| `getMosaicConfig()`        | Returns a defensive copy of the current runtime Mosaic config.         |
+| `setMosaicConfig(config)`  | Patch current Mosaic config without creating a history entry.          |
+| `resetMosaicConfig()`      | Restore current Mosaic config from constructor defaults.               |
+| `setMosaicBrushSize(size)` | Set brush diameter in canvas pixels.                                   |
+| `setMosaicBlockSize(size)` | Set source-pixel block size; values are floored to integers.           |
+
+`defaultMosaicConfig` initializes the current runtime Mosaic config. Runtime
+setters update only the current config and never mutate constructor defaults.
+`resetMosaicConfig()` clones the constructor defaults back into the current
+config.
+
+```ts
+const editor = new ImageEditor(fabric, {
+    defaultMosaicConfig: {
+        brushSize: 48,
+        blockSize: 8,
+    },
+});
+
+editor.init({
+    canvas: 'canvas',
+    enterMosaicModeButton: 'enterMosaicModeButton',
+    exitMosaicModeButton: 'exitMosaicModeButton',
+    mosaicBrushSizeInput: 'mosaicBrushSizeInput',
+    mosaicBlockSizeInput: 'mosaicBlockSizeInput',
+});
+
+editor.enterMosaicMode();
+editor.setMosaicConfig({ brushSize: 64, blockSize: 12 });
+editor.resetMosaicConfig();
+```
+
+`brushSize` is the circular brush diameter in canvas pixels. `blockSize` is
+the source-image pixel block size; larger values produce chunkier pixelation.
+Clicking outside the image is a no-op. Each successful Mosaic click bakes the
+pixelated region into the base image and creates exactly one undo step. Because
+Mosaic edits replace base image pixels rather than adding Fabric overlay
+objects, exported images include the Mosaic naturally while the preview circle
+is never exported or saved in history.
+
+### Text and Draw annotations
+
+Tool modes are mutually exclusive: Crop, Mosaic, Text, and Draw cannot be
+active at the same time. `getEditorState()` reports `activeToolMode` plus
+`isCropMode`, `isMosaicMode`, `isTextMode`, and `isDrawMode`.
+
+| Method                               | Description                                                                |
+| ------------------------------------ | -------------------------------------------------------------------------- |
+| `getAnnotations()`                   | Return current annotation objects in canvas order. Masks are not included. |
+| `enterTextMode()` / `exitTextMode()` | Click empty canvas space to create editable text annotations.              |
+| `createTextAnnotation(config?)`      | Create a text annotation directly and return it.                           |
+| `getTextConfig()`                    | Return a defensive copy of the current Text config.                        |
+| `setTextConfig(config)`              | Patch current Text config without history.                                 |
+| `resetTextConfig()`                  | Restore Text config from constructor defaults.                             |
+| `setTextColor(color)`                | Convenience setter for text fill color.                                    |
+| `setTextFontSize(size)`              | Convenience setter for text font size.                                     |
+| `enterDrawMode()` / `exitDrawMode()` | Use Fabric free drawing; each stroke becomes a Draw annotation.            |
+| `getDrawConfig()`                    | Return a defensive copy of the current Draw config.                        |
+| `setDrawConfig(config)`              | Patch current Draw config without history.                                 |
+| `resetDrawConfig()`                  | Restore Draw config from constructor defaults.                             |
+| `setDrawColor(color)`                | Convenience setter for brush color.                                        |
+| `setDrawBrushSize(size)`             | Convenience setter for brush size.                                         |
+| `updateAnnotation(id, config)`       | Update an annotation by id.                                                |
+| `updateSelectedAnnotation(config)`   | Update selected annotation objects.                                        |
+| `removeSelectedAnnotation()`         | Remove selected unlocked annotations.                                      |
+| `removeAllAnnotations(options?)`     | Remove annotations only. Masks are preserved.                              |
+| `deleteSelectedObject()`             | Convenience deletion for selected masks and unlocked annotations.          |
+
+```ts
+editor.enterTextMode();
+editor.setTextConfig({ fill: '#ff0000', fontSize: 32 });
+editor.updateSelectedAnnotation({ fill: '#00aaff' });
+
+editor.enterDrawMode();
+editor.setDrawConfig({ color: '#00aaff', brushSize: 10 });
+```
+
+Annotations carry `annotationHidden` and `annotationLocked` metadata. Hidden
+annotations are not rendered during export. Locked annotations are not
+selectable/editable and are skipped by selected-annotation update/delete
+operations unless an API explicitly opts into forced removal.
+
+### Layer operations
+
+Editable overlays include masks and annotations. Layer operations keep the
+base image below overlays and session objects above overlays.
+
+| Method                         | Description                                       |
+| ------------------------------ | ------------------------------------------------- |
+| `bringSelectedObjectForward()` | Move selected editable overlays one step up.      |
+| `sendSelectedObjectBackward()` | Move selected editable overlays one step down.    |
+| `bringSelectedObjectToFront()` | Move selected editable overlays to overlay front. |
+| `sendSelectedObjectToBack()`   | Move selected editable overlays to overlay back.  |
+
 ### Merge and export
 
 | Method                        | Description                                                                                    |
 | ----------------------------- | ---------------------------------------------------------------------------------------------- |
 | `mergeMasks()`                | Bake masks into the base image atomically. Returns `Promise<void>`.                            |
+| `mergeAnnotations()`          | Bake annotations into the base image atomically. Returns `Promise<void>`.                      |
 | `exportImageBase64(options?)` | Returns `Promise<string>` (data URL). Resolves to `''` with a warning when no image is loaded. |
 | `exportImageFile(options?)`   | Returns `Promise<File>`. Rejects when no image is loaded.                                      |
-| `downloadImage(fileName?)`    | Triggers a browser download. No-op when no image is loaded.                                    |
-
-`Base64ExportOptions` and `ImageFileExportOptions` separate mask compositing
-from export region selection:
-
-| Option       | Default   | Description                                                                 |
-| ------------ | --------- | --------------------------------------------------------------------------- |
-| `mergeMask`  | `true`    | Flatten masks into exported pixels. Mask labels are never exported.         |
-| `exportArea` | `'image'` | `'image'` clips to the image bounding box; `'canvas'` exports the canvas.   |
-| `fileType`   | `'jpeg'`  | `'png'`, `'jpeg'`, `'jpg'`, `'webp'`, or matching full MIME strings.        |
-| `format`     | `'jpeg'`  | Alias for `fileType` on `exportImageBase64`; `fileType` wins when both set. |
-| `quality`    | `0.92`    | Lossy quality clamped to `[0, 1]`; ignored for PNG.                         |
-| `multiplier` | `1`       | Output resolution multiplier.                                               |
-| `fileName`   | option    | `ImageFileExportOptions` only. Defaults to `defaultDownloadFileName`.       |
+| `downloadImage(options?)`     | Triggers a browser download. Also accepts a filename string. No-op when no image is loaded.    |
+
+`Base64ExportOptions` and `ImageFileExportOptions` separate overlay rendering
+from export region selection. `DownloadImageOptions` supports the same overlay
+rendering flags plus `fileName`:
+
+| Option             | Default   | Description                                                                                 |
+| ------------------ | --------- | ------------------------------------------------------------------------------------------- |
+| `mergeMasks`       | `true`    | Render masks into exported pixels. Mask labels are never exported.                          |
+| `mergeAnnotations` | `true`    | Render non-hidden annotations into exported pixels.                                         |
+| `exportArea`       | `'image'` | `'image'` clips to the image bounding box; `'canvas'` exports the canvas.                   |
+| `fileType`         | `'jpeg'`  | `'png'`, `'jpeg'`, `'jpg'`, `'webp'`, or matching full MIME strings.                        |
+| `format`           | `'jpeg'`  | Alias for `fileType` on `exportImageBase64`; `fileType` wins when both set.                 |
+| `quality`          | `0.92`    | Lossy quality clamped to `[0, 1]`; ignored for PNG.                                         |
+| `multiplier`       | `1`       | Output resolution multiplier.                                                               |
+| `fileName`         | option    | `ImageFileExportOptions` and `DownloadImageOptions`. Defaults to `defaultDownloadFileName`. |
 
 ```ts
-await editor.exportImageBase64({ exportArea: 'image', mergeMask: true });
-await editor.exportImageBase64({ exportArea: 'image', mergeMask: false });
-await editor.exportImageBase64({ exportArea: 'canvas', mergeMask: true });
-await editor.exportImageBase64({ exportArea: 'canvas', mergeMask: false });
+await editor.exportImageBase64({ mergeMasks: true, mergeAnnotations: true });
+await editor.exportImageBase64({ mergeMasks: false, mergeAnnotations: true });
+await editor.exportImageBase64({ mergeMasks: true, mergeAnnotations: false });
+await editor.exportImageBase64({ mergeMasks: false, mergeAnnotations: false });
+editor.downloadImage({ mergeMasks: false, mergeAnnotations: false });
+editor.downloadImage('edited_image.jpg'); // Backwards-compatible filename shorthand.
 ```
 
+`mergeMasks` and `mergeAnnotations` in export options affect the rendered output
+only. They do not mutate editor state, remove objects, or push history entries.
+State-mutating merge APIs are `mergeMasks()` and `mergeAnnotations()`.
+`mergeMasks()` preserves annotations; `mergeAnnotations()` preserves masks.
+
 ### State and history
 
 | Method                    | Description                                                                           |
@@ -325,53 +554,59 @@ Pass an `ImageEditorOptions` object as the second constructor argument
 (or as the only argument when using the UMD global form). Unknown keys are
 ignored; nested `label` and `crop` objects are deep-merged with the defaults.
 
-| Option                    | Default              | Description                                                                                                                                                                                                                                                                    |
-| ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `canvasWidth`             | `800`                | Initial and hidden-container fallback canvas width in pixels.                                                                                                                                                                                                                  |
-| `canvasHeight`            | `600`                | Initial and hidden-container fallback canvas height in pixels.                                                                                                                                                                                                                 |
-| `backgroundColor`         | `'transparent'`      | Fabric canvas background color.                                                                                                                                                                                                                                                |
-| `animationDuration`       | `300`                | Duration of scale and rotate animations (ms).                                                                                                                                                                                                                                  |
-| `minScale`                | `0.1`                | Minimum scale factor.                                                                                                                                                                                                                                                          |
-| `maxScale`                | `5.0`                | Maximum scale factor.                                                                                                                                                                                                                                                          |
-| `scaleStep`               | `0.05`               | Scale delta per zoom step.                                                                                                                                                                                                                                                     |
-| `rotationStep`            | `90`                 | Rotation step in degrees.                                                                                                                                                                                                                                                      |
-| `expandCanvasToImage`     | `true`               | Grow the canvas to fit the loaded image (lowest layout precedence).                                                                                                                                                                                                            |
-| `fitImageToCanvas`        | `false`              | Fit the image inside the visible workspace viewport (highest layout precedence).                                                                                                                                                                                               |
-| `coverImageToCanvas`      | `false`              | Scale large images down to cover the visible workspace, cap at native size, and expand overflowing canvas axes so the container can scroll.                                                                                                                                    |
-| `downsampleOnLoad`        | `true`               | Downsample large images on load.                                                                                                                                                                                                                                               |
-| `downsampleMaxWidth`      | `4000`               | Max width before downsampling kicks in.                                                                                                                                                                                                                                        |
-| `downsampleMaxHeight`     | `3000`               | Max height before downsampling kicks in.                                                                                                                                                                                                                                       |
-| `downsampleQuality`       | `0.92`               | Lossy quality used when downsampling and exporting.                                                                                                                                                                                                                            |
-| `preserveSourceFormat`    | `true`               | Preserve PNG/WebP MIME through downsampling unless `downsampleMimeType` is set.                                                                                                                                                                                                |
-| `downsampleMimeType`      | `null`               | Explicit downsample MIME type. Overrides `preserveSourceFormat`.                                                                                                                                                                                                               |
-| `imageLoadTimeoutMs`      | `30000`              | Maximum duration for both decode and Fabric image creation during `loadImage`.                                                                                                                                                                                                 |
-| `exportMultiplier`        | `1`                  | Output resolution multiplier.                                                                                                                                                                                                                                                  |
-| `maxExportPixels`         | `50000000`           | Maximum output pixel count after applying the export multiplier. Invalid values fall back to this default.                                                                                                                                                                     |
-| `maxHistorySize`          | `50`                 | Maximum undo-history entries. Snapshots may include full image data URLs, so large images can duplicate memory across history entries. Lower this for memory-constrained pages.                                                                                                |
-| `exportAreaByDefault`     | `'image'`            | Default export region for `exportImageBase64`, `exportImageFile`, and `downloadImage`.                                                                                                                                                                                         |
-| `mergeMaskByDefault`      | `true`               | Default mask compositing behavior for `exportImageBase64`, `exportImageFile`, and `downloadImage`.                                                                                                                                                                             |
-| `defaultMaskWidth`        | `50`                 | Default mask width.                                                                                                                                                                                                                                                            |
-| `defaultMaskHeight`       | `80`                 | Default mask height.                                                                                                                                                                                                                                                           |
-| `maskRotatable`           | `false`              | Allow masks to be rotated by the user.                                                                                                                                                                                                                                         |
-| `maskLabelOnSelect`       | `true`               | Show a label above a selected mask.                                                                                                                                                                                                                                            |
-| `maskLabelOffset`         | `3`                  | Pixel offset of the label from the mask's top-left corner.                                                                                                                                                                                                                     |
-| `maskName`                | `'mask'`             | Prefix used for auto-generated mask names.                                                                                                                                                                                                                                     |
-| `groupSelection`          | `false`              | Allow Fabric multi-object group selection on the canvas.                                                                                                                                                                                                                       |
-| `showPlaceholder`         | `true`               | Show a placeholder element while no image is loaded.                                                                                                                                                                                                                           |
-| `initialImageBase64`      | `null`               | Base64 data URL auto-loaded after construction.                                                                                                                                                                                                                                |
-| `defaultDownloadFileName` | `'edited_image.jpg'` | Default file name used by `downloadImage()`.                                                                                                                                                                                                                                   |
-| `onImageLoadStart`        | `null`               | Called before a valid image load begins.                                                                                                                                                                                                                                       |
-| `onImageLoaded`           | `null`               | Called as `(info, context)` once after a successful `loadImage`. Extra arguments are ignored by existing zero-argument JavaScript handlers.                                                                                                                                    |
-| `onImageCleared`          | `null`               | Called when a committed image is replaced or cleared.                                                                                                                                                                                                                          |
-| `onImageChanged`          | `null`               | Called with a safe editor state snapshot after visible editor state changes.                                                                                                                                                                                                   |
-| `onBusyChange`            | `null`               | Called only when the public busy state changes.                                                                                                                                                                                                                                |
-| `onEditorDisposed`        | `null`               | Called once when `dispose()` performs teardown.                                                                                                                                                                                                                                |
-| `onMasksChanged`          | `null`               | Called with a shallow copy of current mask objects after the mask collection changes.                                                                                                                                                                                          |
-| `onSelectionChange`       | `null`               | Called with selected mask payload after mask selection changes.                                                                                                                                                                                                                |
-| `onError`                 | `null`               | Called as `(error, message)` when the editor reports an error.                                                                                                                                                                                                                 |
-| `onWarning`               | `null`               | Called as `(error, message)` when the editor reports a recoverable warning.                                                                                                                                                                                                    |
-| `label`                   | see source           | `LabelConfig` for selected-mask labels (`getText`, `textOptions`, `create`).                                                                                                                                                                                                   |
-| `crop`                    | see source           | `CropConfig` (`minWidth`, `minHeight`, `padding`, `hideMasksDuringCrop`, `preserveMasksAfterCrop`, `allowRotationOfCropRect`, `exportFileType`, `exportQuality`). `applyCrop()` preserves the current image format by default (`'source'`) and falls back to PNG when unknown. |
+| Option                      | Default              | Description                                                                                                                                                                                                                                                                    |
+| --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `canvasWidth`               | `800`                | Initial and hidden-container fallback canvas width in pixels.                                                                                                                                                                                                                  |
+| `canvasHeight`              | `600`                | Initial and hidden-container fallback canvas height in pixels.                                                                                                                                                                                                                 |
+| `backgroundColor`           | `'transparent'`      | Fabric canvas background color.                                                                                                                                                                                                                                                |
+| `animationDuration`         | `300`                | Duration of scale and rotate animations (ms).                                                                                                                                                                                                                                  |
+| `minScale`                  | `0.1`                | Minimum scale factor.                                                                                                                                                                                                                                                          |
+| `maxScale`                  | `5.0`                | Maximum scale factor.                                                                                                                                                                                                                                                          |
+| `scaleStep`                 | `0.05`               | Scale delta per zoom step.                                                                                                                                                                                                                                                     |
+| `rotationStep`              | `90`                 | Rotation step in degrees.                                                                                                                                                                                                                                                      |
+| `defaultLayoutMode`         | `'expand'`           | Initial layout mode for image loads until changed by `setLayoutMode()`. Use `'fit'`, `'cover'`, or `'expand'`. Invalid runtime values fall back to `'expand'`.                                                                                                                 |
+| `downsampleOnLoad`          | `true`               | Downsample large images on load.                                                                                                                                                                                                                                               |
+| `downsampleMaxWidth`        | `4000`               | Max width before downsampling kicks in.                                                                                                                                                                                                                                        |
+| `downsampleMaxHeight`       | `3000`               | Max height before downsampling kicks in.                                                                                                                                                                                                                                       |
+| `downsampleQuality`         | `0.92`               | Lossy quality used when downsampling and exporting.                                                                                                                                                                                                                            |
+| `preserveSourceFormat`      | `true`               | Preserve PNG/WebP MIME through downsampling unless `downsampleMimeType` is set.                                                                                                                                                                                                |
+| `downsampleMimeType`        | `null`               | Explicit downsample MIME type. Overrides `preserveSourceFormat`.                                                                                                                                                                                                               |
+| `imageLoadTimeoutMs`        | `30000`              | Maximum duration for both decode and Fabric image creation during `loadImage`.                                                                                                                                                                                                 |
+| `exportMultiplier`          | `1`                  | Output resolution multiplier.                                                                                                                                                                                                                                                  |
+| `maxExportPixels`           | `50000000`           | Maximum output pixel count after applying the export multiplier. Invalid values fall back to this default.                                                                                                                                                                     |
+| `maxHistorySize`            | `50`                 | Maximum undo-history entries. Snapshots may include full image data URLs, so large images can duplicate memory across history entries. Lower this for memory-constrained pages.                                                                                                |
+| `exportAreaByDefault`       | `'image'`            | Default export region for `exportImageBase64`, `exportImageFile`, and `downloadImage`.                                                                                                                                                                                         |
+| `mergeMasksByDefault`       | `true`               | Default mask rendering behavior for `exportImageBase64`, `exportImageFile`, and `downloadImage`.                                                                                                                                                                               |
+| `mergeAnnotationsByDefault` | `true`               | Default annotation rendering behavior for `exportImageBase64`, `exportImageFile`, and `downloadImage`.                                                                                                                                                                         |
+| `defaultMaskWidth`          | `50`                 | Default mask width.                                                                                                                                                                                                                                                            |
+| `defaultMaskHeight`         | `80`                 | Default mask height.                                                                                                                                                                                                                                                           |
+| `defaultMaskConfig`         | `{}`                 | Defaults applied by `createMask()` after `defaultMaskWidth` / `defaultMaskHeight` and before per-call config. Supports `MaskConfig` fields except `onCreate` and `fabricGenerator`.                                                                                            |
+| `defaultMosaicConfig`       | see source           | Defaults used to initialize the current Mosaic tool config. Supports `brushSize`, `blockSize`, preview circle styling, `outputFileType`, and `outputQuality`. Runtime Mosaic setters update the current config only.                                                           |
+| `defaultTextConfig`         | see source           | Defaults used to initialize the current Text annotation config. Runtime Text setters update the current config only.                                                                                                                                                           |
+| `defaultDrawConfig`         | see source           | Defaults used to initialize the current Draw mode config. Runtime Draw setters update the current config only.                                                                                                                                                                 |
+| `maskRotatable`             | `false`              | Allow masks to be rotated by the user.                                                                                                                                                                                                                                         |
+| `maskLabelOnSelect`         | `true`               | Show a label above a selected mask.                                                                                                                                                                                                                                            |
+| `maskLabelOffset`           | `3`                  | Pixel offset of the label from the mask's top-left corner.                                                                                                                                                                                                                     |
+| `maskName`                  | `'mask'`             | Prefix used for auto-generated mask names.                                                                                                                                                                                                                                     |
+| `textAnnotationName`        | `'text'`             | Prefix used for auto-generated text annotation names.                                                                                                                                                                                                                          |
+| `drawAnnotationName`        | `'draw'`             | Prefix used for auto-generated draw annotation names.                                                                                                                                                                                                                          |
+| `groupSelection`            | `false`              | Allow Fabric multi-object group selection on the canvas.                                                                                                                                                                                                                       |
+| `showPlaceholder`           | `true`               | Show a placeholder element while no image is loaded.                                                                                                                                                                                                                           |
+| `initialImageBase64`        | `null`               | Base64 data URL auto-loaded after construction.                                                                                                                                                                                                                                |
+| `defaultDownloadFileName`   | `'edited_image.jpg'` | Default file name used by `downloadImage()`.                                                                                                                                                                                                                                   |
+| `onImageLoadStart`          | `null`               | Called before a valid image load begins.                                                                                                                                                                                                                                       |
+| `onImageLoaded`             | `null`               | Called as `(info, context)` once after a successful `loadImage`. Extra arguments are ignored by existing zero-argument JavaScript handlers.                                                                                                                                    |
+| `onImageCleared`            | `null`               | Called when a committed image is replaced or cleared.                                                                                                                                                                                                                          |
+| `onImageChanged`            | `null`               | Called with a safe editor state snapshot after visible editor state changes.                                                                                                                                                                                                   |
+| `onBusyChange`              | `null`               | Called only when the public busy state changes.                                                                                                                                                                                                                                |
+| `onEditorDisposed`          | `null`               | Called once when `dispose()` performs teardown.                                                                                                                                                                                                                                |
+| `onMasksChanged`            | `null`               | Called with a shallow copy of current mask objects after the mask collection changes.                                                                                                                                                                                          |
+| `onAnnotationsChanged`      | `null`               | Called with a shallow copy of current annotation objects after the annotation collection changes.                                                                                                                                                                              |
+| `onSelectionChange`         | `null`               | Called with selected object payload after selection changes.                                                                                                                                                                                                                   |
+| `onError`                   | `null`               | Called as `(error, message)` when the editor reports an error.                                                                                                                                                                                                                 |
+| `onWarning`                 | `null`               | Called as `(error, message)` when the editor reports a recoverable warning.                                                                                                                                                                                                    |
+| `label`                     | see source           | `LabelConfig` for selected-mask labels (`getText`, `textOptions`, `create`).                                                                                                                                                                                                   |
+| `crop`                      | see source           | `CropConfig` (`minWidth`, `minHeight`, `padding`, `hideMasksDuringCrop`, `preserveMasksAfterCrop`, `allowRotationOfCropRect`, `exportFileType`, `exportQuality`). `applyCrop()` preserves the current image format by default (`'source'`) and falls back to PNG when unknown. |
 
 `crop.exportFileType` defaults to `'source'`. Supported explicit values are
 `'png'`, `'jpeg'`, `'jpg'`, `'webp'`, and full image MIME strings. PNG is
@@ -379,14 +614,31 @@ lossless and ignores `crop.exportQuality`; JPEG/WebP use `crop.exportQuality`
 when finite, otherwise `downsampleQuality`, otherwise `0.92`. Choose JPEG/WebP
 only when smaller intermediate crop output is preferred.
 
+`defaultMosaicConfig.outputFileType` also defaults to `'source'`. Mosaic commits
+preserve the current image MIME type when known and fall back to PNG when the
+source format cannot be determined. JPEG/WebP commits use
+`defaultMosaicConfig.outputQuality` when finite, otherwise `downsampleQuality`.
+
+## Breaking changes in v2.2.0
+
+- All editor-owned Fabric objects now require `editorObjectKind`.
+- `isMaskObject()` is strict and rejects legacy objects with only `maskId`.
+- `MaskObject.maskUid` is required.
+- Serialized states without `editorObjectKind` are not migrated.
+- Export option mergeMask was removed; use `mergeMasks`.
+- Constructor option mergeMaskByDefault was removed; use `mergeMasksByDefault`.
+- `ImageFileExportOptions` keeps `fileType` only; `format` remains limited to
+  `exportImageBase64`.
+
 ## Example workflow
 
 1. Construct `ImageEditor` with options and call `init(idMap)` to wire it up.
 2. Load an image via `loadImage(base64)` or the bound file input.
-3. Adjust with `scaleImage`, `rotateImage`, `resetImageTransform`, and the
-   crop session.
-4. Add `createMask` calls and inspect via the `maskList` element.
-5. Use `mergeMasks` to bake masks into the image, then
+3. Adjust with `scaleImage`, `rotateImage`, `resetImageTransform`, Crop mode,
+   Mosaic mode, Text mode, or Draw mode.
+4. Add `createMask` and annotation calls, then inspect via `maskList` and
+   `annotationList`.
+5. Use `mergeMasks()` or `mergeAnnotations()` to bake overlays into the image, then
    `exportImageBase64`, `exportImageFile`, or `downloadImage` to produce
    the final output.
 6. Call `dispose()` when the editor is unmounted.
@@ -447,8 +699,11 @@ import type {
     ResolvedOptions,
     LabelConfig,
     CropConfig,
+    MosaicConfig,
+    ResolvedMosaicConfig,
     LoadImageOptions,
     RemoveAllMasksOptions,
+    DefaultMaskConfig,
     MaskConfig,
     MaskObject,
     MaskNumericProp,
@@ -458,6 +713,7 @@ import type {
     NormalizedImageFormat,
     ExportArea,
     CropExportFileType,
+    MosaicOutputFileType,
     Base64ExportOptions,
     ImageFileExportOptions,
     ImageInfo,