@overtone-art/canvas-editor-core 0.2.7 → 0.2.8

package/dist/index.mjs

@@ -1,14 +1,16 @@
 import {
   computeCoverPlacement,
   computePrintAreaClip,
+  displaceRgba,
   exportDataURL,
+  exportIsolatedPNG,
   exportMockup,
   exportPNG,
   exportSVG
-} from "./chunk-NINRTPOJ.mjs";
+} from "./chunk-ORZZ6MGQ.mjs";
 
 // src/editor.ts
-import { Canvas, FabricImage as FabricImage2, Group, Textbox, filters, loadSVGFromString, util as util3 } from "fabric";
+import { Canvas, FabricImage as FabricImage3, Group, Textbox, filters, loadSVGFromString, util as util3 } from "fabric";
 
 // src/events.ts
 var EventEmitter = class {
@@ -246,9 +248,13 @@ var LayerManager = class {
 };
 
 // src/history.ts
-var HistoryManager = class {
+var HistoryManager = class _HistoryManager {
+  static ASSET_KEY = "__canvasEditorHistoryAsset";
   undoStack = [];
   redoStack = [];
+  assets = /* @__PURE__ */ new Map();
+  assetIds = /* @__PURE__ */ new Map();
+  nextAssetId = 1;
   maxSize;
   maxBytes;
   paused = false;
@@ -291,7 +297,8 @@ var HistoryManager = class {
       return;
     }
     this.cancelPending();
-    const state = this.getState();
+    const rawState = this.getState();
+    const state = this.compactState(rawState);
     if (this.undoStack.at(-1) === state) {
       this.emitChanged();
       return;
@@ -303,7 +310,7 @@ var HistoryManager = class {
     this.redoStack = [];
     this.trimToBudget();
     this.events.emit("history:snapshot", {
-      bytes: state.length * 2,
+      bytes: rawState.length * 2,
       totalBytes: this.snapshotBytes(),
       entries: this.undoStack.length
     });
@@ -331,15 +338,15 @@ var HistoryManager = class {
   }
   async undo() {
     this.cancelPending();
-    const current = this.getState();
     const committed = this.undoStack.at(-1);
     if (!committed) return;
+    const current = this.compactState(this.getState());
     const currentIsCommitted = current === committed;
     if (currentIsCommitted && this.undoStack.length < 2) return;
     const target = currentIsCommitted ? this.undoStack[this.undoStack.length - 2] : committed;
     this.paused = true;
     try {
-      await this.restoreState(target);
+      await this.restoreState(this.expandState(target));
       if (currentIsCommitted) this.undoStack.pop();
       this.redoStack.push(current);
       this.trimToBudget();
@@ -357,7 +364,7 @@ var HistoryManager = class {
     if (!state) return;
     this.paused = true;
     try {
-      await this.restoreState(state);
+      await this.restoreState(this.expandState(state));
       this.redoStack.pop();
       if (this.undoStack.at(-1) !== state) this.undoStack.push(state);
       this.trimToBudget();
@@ -390,6 +397,8 @@ var HistoryManager = class {
     this.cancelPending();
     this.undoStack = [];
     this.redoStack = [];
+    this.assets.clear();
+    this.assetIds.clear();
     this.emitChanged();
   }
   getSnapshotBytes() {
@@ -405,6 +414,10 @@ var HistoryManager = class {
     this.cancelPending();
     this.transactionDepth = 0;
     this.transactionDirty = false;
+    this.undoStack = [];
+    this.redoStack = [];
+    this.assets.clear();
+    this.assetIds.clear();
   }
   emitChanged() {
     this.events.emit("history:changed", {
@@ -413,17 +426,91 @@ var HistoryManager = class {
     });
   }
   snapshotBytes() {
-    return [...this.undoStack, ...this.redoStack].reduce(
+    const stackBytes = [...this.undoStack, ...this.redoStack].reduce(
       (total, state) => total + state.length * 2,
       0
     );
+    const assetBytes = [...this.assets.values()].reduce(
+      (total, asset) => total + asset.length * 2,
+      0
+    );
+    return stackBytes + assetBytes;
   }
   trimToBudget() {
+    this.pruneAssets();
     while (this.undoStack.length > 1 && this.snapshotBytes() > this.maxBytes) {
       this.undoStack.shift();
+      this.pruneAssets();
     }
     while (this.redoStack.length > 1 && this.snapshotBytes() > this.maxBytes) {
       this.redoStack.shift();
+      this.pruneAssets();
+    }
+  }
+  /**
+   * History is internal and can content-address large raster strings without
+   * changing the public EditorState wire format. Unchanged images are retained
+   * once even when dozens of snapshots reference them.
+   */
+  compactState(state) {
+    let parsed;
+    try {
+      parsed = JSON.parse(state);
+    } catch {
+      return state;
+    }
+    const visit = (value) => {
+      if (typeof value === "string" && /^data:image\/(?:png|jpeg|webp);base64,/i.test(value)) {
+        let id = this.assetIds.get(value);
+        if (!id) {
+          id = `a${this.nextAssetId++}`;
+          this.assetIds.set(value, id);
+          this.assets.set(id, value);
+        }
+        return { [_HistoryManager.ASSET_KEY]: id };
+      }
+      if (Array.isArray(value)) return value.map(visit);
+      if (!value || typeof value !== "object") return value;
+      return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, visit(entry)]));
+    };
+    return JSON.stringify(visit(parsed));
+  }
+  expandState(state) {
+    let parsed;
+    try {
+      parsed = JSON.parse(state);
+    } catch {
+      return state;
+    }
+    const visit = (value) => {
+      if (Array.isArray(value)) return value.map(visit);
+      if (!value || typeof value !== "object") return value;
+      const record = value;
+      const id = record[_HistoryManager.ASSET_KEY];
+      if (typeof id === "string" && Object.keys(record).length === 1) {
+        const asset = this.assets.get(id);
+        if (!asset) throw new Error(`Missing history raster asset: ${id}`);
+        return asset;
+      }
+      return Object.fromEntries(Object.entries(record).map(([key, entry]) => [key, visit(entry)]));
+    };
+    return JSON.stringify(visit(parsed));
+  }
+  /**
+   * Runs on every commit, so it scans for the serialized reference marker
+   * instead of re-parsing every snapshot — parsing multi-megabyte raster states
+   * per save would cost more than the retention it reclaims. `JSON.stringify`
+   * emits the marker verbatim; the same text inside user data is escaped and
+   * therefore cannot match.
+   */
+  pruneAssets() {
+    if (this.assets.size === 0) return;
+    const states = [...this.undoStack, ...this.redoStack];
+    for (const [id, asset] of this.assets) {
+      const marker = `"${_HistoryManager.ASSET_KEY}":"${id}"`;
+      if (states.some((state) => state.includes(marker))) continue;
+      this.assets.delete(id);
+      this.assetIds.delete(asset);
     }
   }
 };
@@ -1076,6 +1163,7 @@ function serializeEditor(editor) {
     // forced transparent while a mockup preview is active).
     background: editor.getDesignBackground(),
     backgroundImage: editor.getDesignBackgroundImage() ? editor.getDesignBackgroundImage().toObject() : null,
+    backgroundImageOptions: editor.getBackgroundImageOptions(),
     mockup: editor.getMockup()
   };
 }
@@ -1094,13 +1182,28 @@ async function deserializeEditor(editor, state) {
     throw new Error("Invalid editor background color");
   }
   const staged = await Promise.all(
-    state.layers.map(async (serialized) => ({
-      serialized,
-      fabricObject: (await util2.enlivenObjects([serialized.fabricObject]))[0]
-    }))
+    state.layers.map(async (serialized) => {
+      const fabricObject = (await util2.enlivenObjects([serialized.fabricObject]))[0];
+      if (!fabricObject) {
+        const source = serialized.fabricObject.src;
+        if (typeof source === "string" && source.startsWith("blob:")) {
+          throw new Error(`Failed to restore expired object URL: ${source}`);
+        }
+        throw new Error(`Failed to restore layer: ${serialized.id}`);
+      }
+      return { serialized, fabricObject };
+    })
   );
   const stagedBackground = state.backgroundImage ? (await util2.enlivenObjects([state.backgroundImage]))[0] : null;
+  if (state.backgroundImage && !stagedBackground) {
+    const source = state.backgroundImage.src;
+    if (typeof source === "string" && source.startsWith("blob:")) {
+      throw new Error(`Failed to restore expired background object URL: ${source}`);
+    }
+    throw new Error("Failed to restore background image");
+  }
   editor.crop.cancel();
+  editor.masks.detach();
   editor.layers.clear();
   if (state.canvas.unit) editor.units.setUnit(state.canvas.unit);
   if (state.canvas.dpi !== void 0) editor.units.setDpi(state.canvas.dpi);
@@ -1108,7 +1211,11 @@ async function deserializeEditor(editor, state) {
   if (state.background !== void 0) {
     editor.setBackground(state.background);
   }
-  editor.setBackgroundImageObject(stagedBackground, false);
+  editor.setBackgroundImageObject(
+    stagedBackground ?? null,
+    false,
+    state.backgroundImageOptions ?? null
+  );
   editor.setMockup(state.mockup ?? null);
   for (const item of staged) {
     restoreLayer(editor, item.serialized, item.fabricObject);
@@ -1445,9 +1552,270 @@ var ProjectManager = class {
   }
 };
 
+// src/mask.ts
+import { FabricImage as FabricImage2 } from "fabric";
+var MaskRefinementError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = "MaskRefinementError";
+  }
+  code;
+  cause;
+};
+var MaskController = class {
+  constructor(editor) {
+    this.editor = editor;
+  }
+  editor;
+  backing = null;
+  context = null;
+  layerId = null;
+  brush = null;
+  previousPoint = null;
+  strokeBackup = null;
+  strokeStartedAt = null;
+  lastInteractionLatencyMs = 0;
+  refinement = null;
+  disposed = false;
+  async create(width = this.editor.canvas.getWidth(), height = this.editor.canvas.getHeight()) {
+    this.assertActive();
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+      throw new Error("Mask dimensions must be positive integers");
+    }
+    const backing = this.makeCanvas(width, height);
+    const image = new FabricImage2(backing, {
+      left: 0,
+      top: 0,
+      originX: "left",
+      originY: "top",
+      selectable: false
+    });
+    const layer = this.editor.layers.add("mask", image, "Mask");
+    layer.meta.mask = { width, height, revision: 0 };
+    this.editor.history.saveImmediate();
+    this.attachBacking(layer.id, backing);
+    return layer;
+  }
+  attach(layerId) {
+    this.assertActive();
+    this.cancelStroke();
+    const layer = this.requireMask(layerId);
+    const image = layer.fabricObject;
+    const width = layer.meta.mask?.width ?? image.width ?? this.editor.canvas.getWidth();
+    const height = layer.meta.mask?.height ?? image.height ?? this.editor.canvas.getHeight();
+    const backing = this.makeCanvas(width, height);
+    const context = backing.getContext("2d");
+    if (!context) throw new Error("2D mask context is unavailable");
+    const element = image.getElement();
+    if (element) context.drawImage(element, 0, 0, width, height);
+    this.attachBacking(layerId, backing);
+  }
+  beginStroke(options) {
+    this.assertActive();
+    if (!this.context || !this.backing || !this.layerId) throw new Error("Attach a mask first");
+    if (this.brush) throw new Error("A mask stroke is already active");
+    if (!Number.isFinite(options.size) || options.size <= 0) {
+      throw new Error("Mask brush size must be positive");
+    }
+    this.brush = { ...options, hardness: clamp(options.hardness, 0, 1) };
+    this.previousPoint = null;
+    this.strokeBackup = this.context.getImageData(0, 0, this.backing.width, this.backing.height);
+    this.strokeStartedAt = performance.now();
+  }
+  addPoint(point) {
+    if (!this.brush || !this.context || !this.backing || !this.layerId) {
+      throw new Error("No active mask stroke");
+    }
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) return;
+    const previous = this.previousPoint ?? point;
+    const distance = Math.hypot(point.x - previous.x, point.y - previous.y);
+    const step = Math.max(1, this.brush.size / 4);
+    const samples = Math.max(1, Math.ceil(distance / step));
+    for (let index = 0; index <= samples; index += 1) {
+      const ratio = index / samples;
+      this.drawDot({
+        x: previous.x + (point.x - previous.x) * ratio,
+        y: previous.y + (point.y - previous.y) * ratio
+      });
+    }
+    this.previousPoint = point;
+    this.requireMask(this.layerId).fabricObject.setElement(this.backing);
+    this.editor.canvas.requestRenderAll();
+  }
+  async endStroke() {
+    if (!this.brush || !this.backing || !this.layerId) return;
+    const layerId = this.layerId;
+    this.brush = null;
+    this.previousPoint = null;
+    this.strokeBackup = null;
+    const dataUrl = this.backing.toDataURL("image/png");
+    await this.editor.history.transaction(async () => {
+      await this.editor.replaceImageSource(layerId, dataUrl);
+      const layer = this.requireMask(layerId);
+      if (layer.meta.mask) layer.meta.mask.revision += 1;
+    });
+    this.attach(layerId);
+    if (this.strokeStartedAt !== null) {
+      this.lastInteractionLatencyMs = performance.now() - this.strokeStartedAt;
+      this.strokeStartedAt = null;
+    }
+  }
+  cancelStroke() {
+    if (this.strokeBackup && this.context && this.backing && this.layerId) {
+      this.context.putImageData(this.strokeBackup, 0, 0);
+      this.requireMask(this.layerId).fabricObject.setElement(this.backing);
+      this.editor.canvas.requestRenderAll();
+    }
+    this.brush = null;
+    this.previousPoint = null;
+    this.strokeBackup = null;
+    this.strokeStartedAt = null;
+  }
+  isStrokeActive() {
+    return this.brush !== null;
+  }
+  activeLayerId() {
+    return this.layerId;
+  }
+  detach(layerId) {
+    if (layerId && this.layerId !== layerId) return;
+    this.cancelStroke();
+    this.cancelRefinement();
+    this.backing = null;
+    this.context = null;
+    this.layerId = null;
+  }
+  async refine(layerId, provider, prompts, options = {}) {
+    this.assertActive();
+    const layer = this.editor.layers.get(layerId);
+    if (!layer || layer.type !== "mask") {
+      throw new MaskRefinementError("not-found", `Mask layer not found: ${layerId}`);
+    }
+    this.cancelRefinement();
+    const controller = new AbortController();
+    this.refinement = controller;
+    const abort = () => controller.abort(options.signal?.reason);
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted) abort();
+    try {
+      const image = layer.fabricObject;
+      const result = await provider.refine(
+        {
+          mask: image.getSrc(),
+          width: layer.meta.mask?.width ?? image.width ?? 1,
+          height: layer.meta.mask?.height ?? image.height ?? 1,
+          prompts: structuredClone(prompts)
+        },
+        { signal: controller.signal, onProgress: options.onProgress }
+      );
+      if (controller.signal.aborted)
+        throw new MaskRefinementError("cancelled", "Mask refinement cancelled");
+      if (!/^data:image\/(?:png|jpeg|webp);base64,/i.test(result.dataUrl)) {
+        throw new MaskRefinementError(
+          "invalid-result",
+          "Mask refinement must return a base64 PNG, JPEG, or WebP data URL"
+        );
+      }
+      await this.editor.history.transaction(async () => {
+        await this.editor.replaceImageSource(layerId, result.dataUrl);
+        if (layer.meta.mask) layer.meta.mask.revision += 1;
+      });
+      this.attach(layerId);
+      return result;
+    } catch (error) {
+      if (error instanceof MaskRefinementError) throw error;
+      if (controller.signal.aborted) {
+        throw new MaskRefinementError("cancelled", "Mask refinement cancelled", error);
+      }
+      throw new MaskRefinementError("provider", "Mask refinement provider failed", error);
+    } finally {
+      options.signal?.removeEventListener("abort", abort);
+      if (this.refinement === controller) this.refinement = null;
+    }
+  }
+  cancelRefinement() {
+    this.refinement?.abort(new DOMException("Cancelled", "AbortError"));
+    this.refinement = null;
+  }
+  measure() {
+    if (!this.backing) return null;
+    const started = performance.now();
+    this.context?.getImageData(0, 0, 1, 1);
+    const backingBytes = this.backing.width * this.backing.height * 4;
+    const strokeBackupBytes = this.strokeBackup ? backingBytes : 0;
+    const memory = performance;
+    return {
+      width: this.backing.width,
+      height: this.backing.height,
+      backingBytes,
+      strokeBackupBytes,
+      // The backing store and rollback ImageData dominate interactive mask
+      // memory. Encoded historical rasters are reported separately below.
+      estimatedPeakBytes: backingBytes + strokeBackupBytes,
+      historyBytes: this.editor.history.getSnapshotBytes(),
+      interactionLatencyMs: this.lastInteractionLatencyMs,
+      ...typeof memory.memory?.usedJSHeapSize === "number" ? { usedJsHeapBytes: memory.memory.usedJSHeapSize } : {},
+      elapsedMs: performance.now() - started
+    };
+  }
+  dispose() {
+    this.detach();
+    this.disposed = true;
+  }
+  drawDot(point) {
+    const context = this.context;
+    const brush = this.brush;
+    const radius = brush.size / 2;
+    context.save();
+    context.globalCompositeOperation = brush.mode === "subtract" ? "destination-out" : "source-over";
+    const gradient = context.createRadialGradient(
+      point.x,
+      point.y,
+      radius * brush.hardness,
+      point.x,
+      point.y,
+      radius
+    );
+    const color = brush.mode === "subtract" ? "rgba(0,0,0,1)" : "rgba(255,255,255,1)";
+    gradient.addColorStop(0, color);
+    gradient.addColorStop(1, "rgba(255,255,255,0)");
+    context.fillStyle = gradient;
+    context.beginPath();
+    context.arc(point.x, point.y, radius, 0, Math.PI * 2);
+    context.fill();
+    context.restore();
+  }
+  makeCanvas(width, height) {
+    const canvas = this.editor.canvas.lowerCanvasEl.ownerDocument.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    return canvas;
+  }
+  attachBacking(layerId, backing) {
+    const context = backing.getContext("2d");
+    if (!context) throw new Error("2D mask context is unavailable");
+    this.layerId = layerId;
+    this.backing = backing;
+    this.context = context;
+  }
+  requireMask(layerId) {
+    const layer = this.editor.layers.get(layerId);
+    if (!layer || layer.type !== "mask") throw new Error(`Mask layer not found: ${layerId}`);
+    return layer;
+  }
+  assertActive() {
+    if (this.disposed) throw new Error("Mask controller has been disposed");
+  }
+};
+
 // src/editor.ts
 var MIN_ZOOM = 0.1;
 var MAX_ZOOM = 8;
+function isTaintedCanvasError(error) {
+  return error instanceof DOMException && error.name === "SecurityError" || error instanceof Error && /taint|cross-origin|insecure/i.test(error.message);
+}
 var CanvasEditor = class {
   canvas;
   layers;
@@ -1460,6 +1828,7 @@ var CanvasEditor = class {
   fonts;
   licensing;
   pages;
+  masks;
   fileAdapter;
   imageProvider;
   zoomLevel = 1;
@@ -1469,6 +1838,7 @@ var CanvasEditor = class {
   // for serialization and export — not the (possibly transient) canvas value.
   designBackground;
   designBackgroundImage = null;
+  backgroundImageOptions = null;
   constructor(canvasElement, config) {
     this.events = new EventEmitter();
     this.fonts = new FontRegistry();
@@ -1509,11 +1879,12 @@ var CanvasEditor = class {
     this.setupCanvasEvents();
     this.history.saveImmediate();
     this.pages = new ProjectManager(this);
+    this.masks = new MaskController(this);
   }
   // ─── Layer Operations ────────────────────────────────
   async addImage(url, options) {
     try {
-      const img = await FabricImage2.fromURL(
+      const img = await FabricImage3.fromURL(
         url,
         {},
         { originX: "left", originY: "top", ...options }
@@ -1529,14 +1900,16 @@ var CanvasEditor = class {
   /** Replace an image source without changing its layer identity or visual transform. */
   async replaceImageSource(layerId, url) {
     const layer = this.layers.get(layerId);
-    if (!layer || layer.type !== "image") throw new Error(`Image layer not found: ${layerId}`);
+    if (!layer || layer.type !== "image" && layer.type !== "mask") {
+      throw new Error(`Image or mask layer not found: ${layerId}`);
+    }
     if (layer.meta.pattern) {
       throw new Error("Clear the pattern before replacing the image source");
     }
     if (this.crop.activeLayerId() === layerId) this.crop.cancel();
     const previous = layer.fabricObject;
     try {
-      const replacement = await FabricImage2.fromURL(url, {}, { originX: "left", originY: "top" });
+      const replacement = await FabricImage3.fromURL(url, {}, { originX: "left", originY: "top" });
       replacement.set({
         left: previous.left,
         top: previous.top,
@@ -1620,6 +1993,9 @@ var CanvasEditor = class {
   }
   removeLayer(id) {
     if (this.crop.activeLayerId() === id) this.crop.cancel();
+    if (this.masks.activeLayerId() === id) {
+      this.masks.detach(id);
+    }
     if (this.layers.remove(id)) this.history.save();
   }
   selectLayer(id) {
@@ -1767,6 +2143,50 @@ var CanvasEditor = class {
   async toWebP(options) {
     return this.toRaster("webp", options);
   }
+  /** Export one layer in document coordinates or at its native image resolution. */
+  async exportLayer(id, options = {}) {
+    const layer = this.layers.get(id);
+    if (!layer) throw new Error(`Layer not found: ${id}`);
+    try {
+      if (options.resolution === "source" && layer.fabricObject instanceof FabricImage3) {
+        const image = await layer.fabricObject.clone();
+        image.set({
+          left: 0,
+          top: 0,
+          originX: "left",
+          originY: "top",
+          scaleX: 1,
+          scaleY: 1,
+          angle: 0,
+          flipX: false,
+          flipY: false
+        });
+        return await exportIsolatedPNG(this.canvas, [image], {
+          ...options,
+          width: image.width || 1,
+          height: image.height || 1,
+          cloneObjects: false
+        });
+      }
+      return await exportIsolatedPNG(this.canvas, [layer.fabricObject], options);
+    } catch (error) {
+      this.events.emit("error", { message: `Failed to export layer: ${id}`, error });
+      throw error;
+    }
+  }
+  /** Export only the configured document background, excluding design layers. */
+  async exportBackground(options = {}) {
+    try {
+      return await exportIsolatedPNG(this.canvas, [], {
+        ...options,
+        backgroundColor: this.designBackground,
+        backgroundImage: this.designBackgroundImage
+      });
+    } catch (error) {
+      this.events.emit("error", { message: "Failed to export background", error });
+      throw error;
+    }
+  }
   async toRaster(format, options) {
     this.events.emit("export:start", { format });
     try {
@@ -1778,7 +2198,10 @@ var CanvasEditor = class {
       this.licensing.track(`export:${format}`);
       return blob;
     } catch (error) {
-      this.events.emit("error", { message: `Failed to export ${format.toUpperCase()}`, error });
+      this.events.emit("error", {
+        message: isTaintedCanvasError(error) ? "Canvas export was blocked by cross-origin image data; load remote images with CORS enabled" : `Failed to export ${format.toUpperCase()}`,
+        error
+      });
       throw error;
     }
   }
@@ -1971,13 +2394,20 @@ var CanvasEditor = class {
   getDesignBackgroundImage() {
     return this.designBackgroundImage;
   }
+  getBackgroundImageOptions() {
+    return this.backgroundImageOptions ? { ...this.backgroundImageOptions } : null;
+  }
   async setBackgroundImage(url, options = {}) {
     if (url === null) {
       this.setBackgroundImageObject(null);
       return;
     }
     try {
-      const image = await FabricImage2.fromURL(url, {}, { originX: "left", originY: "top" });
+      const image = await FabricImage3.fromURL(
+        url,
+        { crossOrigin: options.crossOrigin ?? null, signal: options.signal },
+        { originX: "left", originY: "top" }
+      );
       const width = image.width || 1;
       const height = image.height || 1;
       const canvasWidth = this.canvas.getWidth();
@@ -1996,15 +2426,18 @@ var CanvasEditor = class {
         selectable: false,
         evented: false
       });
-      this.setBackgroundImageObject(image);
+      const serializableOptions = { ...options };
+      delete serializableOptions.signal;
+      this.setBackgroundImageObject(image, true, serializableOptions);
     } catch (error) {
       this.events.emit("error", { message: "Failed to set background image", error });
       throw error;
     }
   }
   /** Used by state restoration and advanced integrations with an existing Fabric object. */
-  setBackgroundImageObject(image, save = true) {
+  setBackgroundImageObject(image, save = true, options = null) {
     this.designBackgroundImage = image;
+    this.backgroundImageOptions = image ? options : null;
     this.canvas.backgroundImage = this.mockup ? void 0 : image ?? void 0;
     this.canvas.requestRenderAll();
     if (save) this.history.save();
@@ -2162,6 +2595,7 @@ var CanvasEditor = class {
   }
   // ─── Cleanup ────────────────────────────────────────
   dispose() {
+    this.masks.dispose();
     this.snapping.dispose();
     this.crop.dispose();
     this.history.dispose();
@@ -2216,7 +2650,49 @@ var CANVAS_SIZE_PRESETS = [
   { id: "instagram-square", name: "Social square", width: 1080, height: 1080, unit: "px", dpi: 72 },
   { id: "story", name: "Story", width: 1080, height: 1920, unit: "px", dpi: 72 }
 ];
+
+// src/annotations.ts
+var AnnotationOverlay = class {
+  items = /* @__PURE__ */ new Map();
+  transform = { zoom: 1, panX: 0, panY: 0, devicePixelRatio: 1 };
+  set(annotation) {
+    this.items.set(annotation.id, structuredClone(annotation));
+  }
+  remove(id) {
+    return this.items.delete(id);
+  }
+  clear() {
+    this.items.clear();
+  }
+  getAll() {
+    return [...this.items.values()].map((item) => structuredClone(item));
+  }
+  setTransform(transform) {
+    if (!Number.isFinite(transform.zoom) || transform.zoom <= 0) {
+      throw new Error("Annotation zoom must be positive");
+    }
+    this.transform = { ...transform, devicePixelRatio: transform.devicePixelRatio ?? 1 };
+  }
+  documentToViewport(point) {
+    return {
+      x: point.x * this.transform.zoom + this.transform.panX,
+      y: point.y * this.transform.zoom + this.transform.panY
+    };
+  }
+  viewportToDocument(point) {
+    return {
+      x: (point.x - this.transform.panX) / this.transform.zoom,
+      y: (point.y - this.transform.panY) / this.transform.zoom
+    };
+  }
+  documentToDevice(point) {
+    const viewport = this.documentToViewport(point);
+    const ratio = this.transform.devicePixelRatio ?? 1;
+    return { x: viewport.x * ratio, y: viewport.y * ratio };
+  }
+};
 export {
+  AnnotationOverlay,
   CANVAS_SIZE_PRESETS,
   CanvasEditor,
   CropController,
@@ -2227,6 +2703,8 @@ export {
   Layer,
   LayerManager,
   LicenseManager,
+  MaskController,
+  MaskRefinementError,
   PatternManager,
   ProjectManager,
   SnapManager,
@@ -2240,6 +2718,7 @@ export {
   computePrintAreaClip,
   computeTilePositions,
   deserializeEditor,
+  displaceRgba,
   drawTiles,
   escapeXml,
   exportDataURL,