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

package/dist/index.js

@@ -20,47 +20,71 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AnnotationOverlay: () => AnnotationOverlay,
   CANVAS_SIZE_PRESETS: () => CANVAS_SIZE_PRESETS,
   CanvasEditor: () => CanvasEditor,
   CropController: () => CropController,
+  DEFAULT_LAYER_SHADOW: () => DEFAULT_LAYER_SHADOW,
   DEFAULT_PATTERN_CONFIG: () => DEFAULT_PATTERN_CONFIG,
+  DEFAULT_TEXT_CURVE: () => DEFAULT_TEXT_CURVE,
   EventEmitter: () => EventEmitter,
   FontRegistry: () => FontRegistry,
   HistoryManager: () => HistoryManager,
   Layer: () => Layer,
   LayerManager: () => LayerManager,
   LicenseManager: () => LicenseManager,
+  MaskController: () => MaskController,
+  MaskPresetManager: () => MaskPresetManager,
+  MaskRefinementError: () => MaskRefinementError,
   PatternManager: () => PatternManager,
   ProjectManager: () => ProjectManager,
+  SHAPE_MASK_BOX: () => SHAPE_MASK_BOX,
+  SHAPE_MASK_IDS: () => SHAPE_MASK_IDS,
   SnapManager: () => SnapManager,
+  TEXTURE_MASK_IDS: () => TEXTURE_MASK_IDS,
+  TEXTURE_MASK_SIZE: () => TEXTURE_MASK_SIZE,
+  TextCurveManager: () => TextCurveManager,
   UnitConverter: () => UnitConverter,
+  applyAspectLock: () => applyAspectLock,
+  applyLayerShadow: () => applyLayerShadow,
   applyPatternLocks: () => applyPatternLocks,
+  buildCurvePathData: () => buildCurvePathData,
   buildPatternDataURL: () => buildPatternDataURL,
   captureLocks: () => captureLocks,
   clamp: () => clamp,
   clearPatternImageCache: () => clearPatternImageCache,
+  clearTextureMaskCache: () => clearTextureMaskCache,
   computeCoverPlacement: () => computeCoverPlacement,
   computePrintAreaClip: () => computePrintAreaClip,
   computeTilePositions: () => computeTilePositions,
   deserializeEditor: () => deserializeEditor,
+  displaceRgba: () => displaceRgba,
   drawTiles: () => drawTiles,
   escapeXml: () => escapeXml,
   exportDataURL: () => exportDataURL,
   exportMockup: () => exportMockup,
   exportPNG: () => exportPNG,
+  exportPrintArea: () => exportPrintArea,
   exportSVG: () => exportSVG,
   generateId: () => generateId,
   isCssColor: () => isCssColor,
+  isMaskPresetId: () => isMaskPresetId,
+  isShapeMaskId: () => isShapeMaskId,
+  isTextureMaskId: () => isTextureMaskId,
   loadPatternImage: () => loadPatternImage,
+  readLayerShadow: () => readLayerShadow,
+  renderTextureMask: () => renderTextureMask,
+  resetTransform: () => resetTransform,
   restoreLocks: () => restoreLocks,
   round2: () => round2,
   sanitizeSvg: () => sanitizeSvg,
-  serializeEditor: () => serializeEditor
+  serializeEditor: () => serializeEditor,
+  shapeMaskPathData: () => shapeMaskPathData
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/editor.ts
-var import_fabric4 = require("fabric");
+var import_fabric9 = require("fabric");
 
 // src/events.ts
 var EventEmitter = class {
@@ -298,9 +322,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;
@@ -343,7 +371,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;
@@ -355,7 +384,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
     });
@@ -383,15 +412,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();
@@ -409,7 +438,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();
@@ -442,6 +471,8 @@ var HistoryManager = class {
     this.cancelPending();
     this.undoStack = [];
     this.redoStack = [];
+    this.assets.clear();
+    this.assetIds.clear();
     this.emitChanged();
   }
   getSnapshotBytes() {
@@ -457,6 +488,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", {
@@ -465,17 +500,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);
     }
   }
 };
@@ -1053,6 +1162,521 @@ function mod2(n) {
   return (n % 2 + 2) % 2;
 }
 
+// src/text-curve.ts
+var import_fabric3 = require("fabric");
+var DEFAULT_TEXT_CURVE = { arc: 0, wave: 0 };
+var MIN_ARC = 0.5;
+var FULL_CIRCLE_ARC = 99.5;
+var MIN_SWEEP = 0.12;
+var WAVE_PERIOD_EM = 4.1;
+var WAVE_AMPLITUDE_EM = 0.9;
+var WAVE_STEP = 6;
+var MEASURE_WIDTH = 1e5;
+var PATH_SLACK = 0.06;
+function isCurvable(object) {
+  return !!object && typeof object.text === "string";
+}
+function measureText(text) {
+  const authored = text.width;
+  try {
+    text.set({ width: MEASURE_WIDTH });
+    text.initDimensions?.();
+    return Math.max(1, text.calcTextWidth?.() ?? text.width ?? 1);
+  } finally {
+    if (authored !== void 0) text.set({ width: authored });
+    text.initDimensions?.();
+  }
+}
+function arcPathData(width, arc) {
+  const magnitude = Math.min(100, Math.abs(arc));
+  const direction = arc < 0 ? -1 : 1;
+  const full = magnitude >= FULL_CIRCLE_ARC;
+  const sweep = full ? Math.PI * 2 : Math.max(MIN_SWEEP, magnitude / 100 * Math.PI);
+  const radius = width / sweep;
+  const centerX = width / 2;
+  const point = (angle) => [
+    centerX + radius * Math.sin(angle),
+    direction * radius * (1 - Math.cos(angle))
+  ];
+  const sweepFlag = direction > 0 ? 1 : 0;
+  const format = ([x, y]) => `${round(x)} ${round(y)}`;
+  if (full) {
+    const start2 = point(-Math.PI);
+    const top = point(0);
+    return {
+      data: [
+        `M ${format(start2)}`,
+        `A ${round(radius)} ${round(radius)} 0 0 ${sweepFlag} ${format(top)}`,
+        `A ${round(radius)} ${round(radius)} 0 0 ${sweepFlag} ${format(start2)}`
+      ].join(" "),
+      length: width
+    };
+  }
+  const start = point(-sweep / 2);
+  const end = point(sweep / 2);
+  const largeArc = sweep > Math.PI ? 1 : 0;
+  return {
+    data: `M ${format(start)} A ${round(radius)} ${round(radius)} 0 ${largeArc} ${sweepFlag} ${format(end)}`,
+    // radius = width / sweep, so the arc is exactly `width` long.
+    length: width
+  };
+}
+function wavePathData(width, fontSize, wave) {
+  const amplitude = clamp(wave, 0, 100) / 100 * fontSize * WAVE_AMPLITUDE_EM;
+  const period = Math.max(1, fontSize * WAVE_PERIOD_EM);
+  const steps = Math.max(2, Math.ceil(width / WAVE_STEP));
+  const commands = [];
+  let length = 0;
+  let previous = null;
+  for (let index = 0; index <= steps; index++) {
+    const x = width * index / steps;
+    const y = amplitude * Math.sin(x / period * Math.PI * 2);
+    if (previous) length += Math.hypot(x - previous[0], y - previous[1]);
+    previous = [x, y];
+    commands.push(`${index === 0 ? "M" : "L"} ${round(x)} ${round(y)}`);
+  }
+  return { data: commands.join(" "), length };
+}
+function round(value) {
+  return Math.round(value * 100) / 100;
+}
+function buildCurvePathData(config, width, fontSize) {
+  if (Math.abs(config.arc) >= MIN_ARC) return arcPathData(width, config.arc);
+  if (config.wave > 0) return wavePathData(width, fontSize, config.wave);
+  return null;
+}
+function normalize(config) {
+  const arc = clamp(config.arc ?? 0, -100, 100);
+  return { arc, wave: Math.abs(arc) >= MIN_ARC ? 0 : clamp(config.wave ?? 0, 0, 100) };
+}
+var TextCurveManager = class {
+  constructor(canvas, layers, history, events) {
+    this.canvas = canvas;
+    this.layers = layers;
+    this.history = history;
+    this.events = events;
+  }
+  canvas;
+  layers;
+  history;
+  events;
+  /** Curve parameters for a layer, or null when it is not curved text. */
+  get(layerId) {
+    const layer = this.layers.get(layerId);
+    if (!layer || !isCurvable(layer.fabricObject)) return null;
+    return layer.meta.curve ?? { ...DEFAULT_TEXT_CURVE };
+  }
+  isCurved(layerId) {
+    const curve = this.get(layerId);
+    return !!curve && (Math.abs(curve.arc) >= MIN_ARC || curve.wave > 0);
+  }
+  /** Apply (or update) the curve on a text layer. Zeroed config clears it. */
+  apply(layerId, config, save = true) {
+    const layer = this.layers.get(layerId);
+    if (!layer || !isCurvable(layer.fabricObject)) return false;
+    const next = normalize(config);
+    const text = layer.fabricObject;
+    const run = measureText(text);
+    const curve = buildCurvePathData(next, run * (1 + PATH_SLACK), text.fontSize);
+    if (!curve) {
+      this.detach(text, layer.meta.curveWidth);
+      delete layer.meta.curve;
+      delete layer.meta.curveWidth;
+    } else {
+      if (layer.meta.curveWidth === void 0) layer.meta.curveWidth = text.width ?? 0;
+      text.set({ width: Math.max(layer.meta.curveWidth, run + 2) });
+      text.set({
+        path: new import_fabric3.Path(curve.data, { visible: false, objectCaching: false }),
+        pathAlign: "center",
+        pathSide: "left",
+        pathStartOffset: Math.max(0, (curve.length - run) / 2)
+      });
+      layer.meta.curve = next;
+    }
+    text.initDimensions?.();
+    text.setCoords();
+    text.dirty = true;
+    this.canvas.requestRenderAll();
+    this.events.emit("layer:modified", { layerId });
+    if (save) this.history.save();
+    return true;
+  }
+  /** Remove the curve, restoring the authored text box width. */
+  clear(layerId, save = true) {
+    return this.apply(layerId, DEFAULT_TEXT_CURVE, save);
+  }
+  /**
+   * Rebuild the path from the stored parameters. Text content, font family and
+   * font size all change the run's width, and the path is sized to that width —
+   * without this the curve keeps the geometry of the text it was created from.
+   */
+  refresh(layerId, save = false) {
+    const curve = this.layers.get(layerId)?.meta.curve;
+    if (!curve) return false;
+    return this.apply(layerId, curve, save);
+  }
+  /** Rebuild every curved layer — used after a state restore. */
+  refreshAll() {
+    for (const layer of this.layers.getAll()) {
+      if (layer.meta.curve) this.refresh(layer.id);
+    }
+  }
+  detach(text, authoredWidth) {
+    text.set({ path: null, pathStartOffset: 0 });
+    if (authoredWidth !== void 0 && authoredWidth > 0) text.set({ width: authoredWidth });
+  }
+};
+
+// src/mask-presets/manager.ts
+var import_fabric4 = require("fabric");
+
+// src/mask-presets/shapes.ts
+var SHAPE_MASK_IDS = [
+  "circle",
+  "square",
+  "triangle",
+  "star",
+  "heart",
+  "octagram",
+  "arch",
+  "zigzag"
+];
+function isShapeMaskId(value) {
+  return typeof value === "string" && SHAPE_MASK_IDS.includes(value);
+}
+function starPoints(points, outer, inner, start = -Math.PI / 2) {
+  const step = Math.PI / points;
+  const coordinates = [];
+  for (let index = 0; index < points * 2; index++) {
+    const radius = index % 2 === 0 ? outer : inner;
+    const angle = start + index * step;
+    const x = 50 + Math.cos(angle) * radius;
+    const y = 50 + Math.sin(angle) * radius;
+    coordinates.push(`${index === 0 ? "M" : "L"} ${round3(x)} ${round3(y)}`);
+  }
+  return `${coordinates.join(" ")} Z`;
+}
+function round3(value) {
+  return Math.round(value * 100) / 100;
+}
+var SHAPE_PATHS = {
+  circle: "M 96 50 A 46 46 0 1 1 4 50 A 46 46 0 1 1 96 50 Z",
+  square: "M 4 4 H 96 V 96 H 4 Z",
+  triangle: "M 50 4 L 96 96 L 4 96 Z",
+  star: starPoints(5, 46, 22),
+  heart: "M 50 96 C -8 55 12 4 50 28 C 88 4 108 55 50 96 Z",
+  octagram: starPoints(8, 46, 27),
+  arch: "M 4 96 V 50 A 46 46 0 0 1 96 50 V 96 Z",
+  zigzag: starPoints(16, 46, 39)
+};
+function shapeMaskPathData(id) {
+  return SHAPE_PATHS[id];
+}
+var SHAPE_MASK_BOX = 100;
+
+// src/mask-presets/textures.ts
+var TEXTURE_MASK_IDS = [
+  "vignette",
+  "halftone",
+  "spray",
+  "grunge",
+  "torn",
+  "band"
+];
+function isTextureMaskId(value) {
+  return typeof value === "string" && TEXTURE_MASK_IDS.includes(value);
+}
+var TEXTURE_MASK_SIZE = 320;
+var cache = /* @__PURE__ */ new Map();
+function seeded(seed) {
+  let state = seed;
+  return () => {
+    state = state * 16807 % 2147483647;
+    return (state - 1) / 2147483646;
+  };
+}
+function traceRoughEdge(context, random, jitter, inset) {
+  const size = TEXTURE_MASK_SIZE;
+  const corners = [
+    [inset, inset],
+    [size - inset, inset],
+    [size - inset, size - inset],
+    [inset, size - inset]
+  ];
+  context.beginPath();
+  for (let corner = 0; corner < corners.length; corner++) {
+    const [fromX, fromY] = corners[corner];
+    const [toX, toY] = corners[(corner + 1) % corners.length];
+    for (let step = 0; step <= 26; step++) {
+      const ratio = step / 26;
+      const x = fromX + (toX - fromX) * ratio + (random() - 0.5) * jitter;
+      const y = fromY + (toY - fromY) * ratio + (random() - 0.5) * jitter;
+      if (corner === 0 && step === 0) context.moveTo(x, y);
+      else context.lineTo(x, y);
+    }
+  }
+  context.closePath();
+  context.fill();
+}
+function paint(id, context) {
+  const size = TEXTURE_MASK_SIZE;
+  const center = size / 2;
+  context.fillStyle = "#ffffff";
+  switch (id) {
+    case "vignette": {
+      const gradient = context.createRadialGradient(
+        center,
+        center,
+        size * 0.18,
+        center,
+        center,
+        size * 0.52
+      );
+      gradient.addColorStop(0, "rgba(255,255,255,1)");
+      gradient.addColorStop(1, "rgba(255,255,255,0)");
+      context.fillStyle = gradient;
+      context.fillRect(0, 0, size, size);
+      return;
+    }
+    case "band": {
+      const gradient = context.createLinearGradient(0, 0, 0, size);
+      gradient.addColorStop(0, "rgba(255,255,255,0)");
+      gradient.addColorStop(0.25, "rgba(255,255,255,1)");
+      gradient.addColorStop(0.75, "rgba(255,255,255,1)");
+      gradient.addColorStop(1, "rgba(255,255,255,0)");
+      context.fillStyle = gradient;
+      context.fillRect(0, 0, size, size);
+      return;
+    }
+    case "halftone": {
+      const pitch = 16;
+      for (let y = pitch / 2; y < size; y += pitch) {
+        for (let x = pitch / 2; x < size; x += pitch) {
+          const distance = Math.hypot(x - center, y - center) / (size * 0.52);
+          const radius = Math.max(0, pitch / 2 * (1 - distance) * 1.15);
+          if (radius < 0.4) continue;
+          context.beginPath();
+          context.arc(x, y, radius, 0, Math.PI * 2);
+          context.fill();
+        }
+      }
+      return;
+    }
+    case "spray": {
+      const random = seeded(42);
+      const core = context.createRadialGradient(center, center, 10, center, center, size * 0.42);
+      core.addColorStop(0, "rgba(255,255,255,1)");
+      core.addColorStop(1, "rgba(255,255,255,0.85)");
+      context.fillStyle = core;
+      context.beginPath();
+      context.arc(center, center, size * 0.42, 0, Math.PI * 2);
+      context.fill();
+      context.fillStyle = "rgba(255,255,255,0.9)";
+      for (let dot = 0; dot < 900; dot++) {
+        const angle = random() * Math.PI * 2;
+        const distance = size * (0.3 + random() * 0.24);
+        const x = center + Math.cos(angle) * distance;
+        const y = center + Math.sin(angle) * distance;
+        context.globalAlpha = 1 - (distance / size - 0.3) / 0.24;
+        context.beginPath();
+        context.arc(x, y, random() * 2.4, 0, Math.PI * 2);
+        context.fill();
+      }
+      context.globalAlpha = 1;
+      return;
+    }
+    case "grunge": {
+      const random = seeded(7);
+      traceRoughEdge(context, random, 14, size * 0.06);
+      context.globalCompositeOperation = "destination-out";
+      for (let speckle = 0; speckle < 240; speckle++) {
+        const x = random() * size;
+        const y = random() * size;
+        const nearEdge = Math.min(x, y, size - x, size - y) < size * 0.12;
+        if (!nearEdge && random() >= 0.12) continue;
+        context.beginPath();
+        context.arc(x, y, random() * 6 + 1, 0, Math.PI * 2);
+        context.fill();
+      }
+      context.globalCompositeOperation = "source-over";
+      return;
+    }
+    case "torn": {
+      traceRoughEdge(context, seeded(99), 10, size * 0.08);
+      return;
+    }
+  }
+}
+function renderTextureMask(id) {
+  const cached = cache.get(id);
+  if (cached) return cached;
+  if (typeof document === "undefined") {
+    throw new Error("Texture masks require a DOM canvas");
+  }
+  const canvas = document.createElement("canvas");
+  canvas.width = TEXTURE_MASK_SIZE;
+  canvas.height = TEXTURE_MASK_SIZE;
+  const context = canvas.getContext("2d");
+  if (!context) throw new Error("Texture masks require a 2D canvas context");
+  paint(id, context);
+  cache.set(id, canvas);
+  return canvas;
+}
+function clearTextureMaskCache() {
+  cache.clear();
+}
+
+// src/mask-presets/manager.ts
+function isMaskPresetId(value) {
+  return isShapeMaskId(value) || isTextureMaskId(value);
+}
+var MaskPresetManager = class {
+  constructor(canvas, layers, history, events) {
+    this.canvas = canvas;
+    this.layers = layers;
+    this.history = history;
+    this.events = events;
+  }
+  canvas;
+  layers;
+  history;
+  events;
+  get(layerId) {
+    return this.layers.get(layerId)?.meta.maskPreset ?? null;
+  }
+  /** Clip the layer to `id`. Passing null (or an unknown id) clears the clip. */
+  apply(layerId, id, save = true) {
+    const layer = this.layers.get(layerId);
+    if (!layer) return false;
+    const object = layer.fabricObject;
+    if (id === null) {
+      if (!layer.meta.maskPreset) return false;
+      object.clipPath = void 0;
+      delete layer.meta.maskPreset;
+    } else {
+      if (!isMaskPresetId(id)) return false;
+      object.clipPath = this.buildClip(id, object);
+      layer.meta.maskPreset = id;
+    }
+    object.dirty = true;
+    object.setCoords();
+    this.canvas.requestRenderAll();
+    this.events.emit("layer:modified", { layerId });
+    if (save) this.history.save();
+    return true;
+  }
+  clear(layerId, save = true) {
+    return this.apply(layerId, null, save);
+  }
+  /**
+   * Re-fit the clip to the layer's current size. The clip is built for the
+   * object's dimensions at the time it was applied; editing text or replacing an
+   * image changes them, and a stale clip would crop the wrong region.
+   */
+  refresh(layerId, save = false) {
+    const id = this.get(layerId);
+    if (!id) return false;
+    return this.apply(layerId, id, save);
+  }
+  /** Re-fit every masked layer — used after a state restore. */
+  refreshAll() {
+    for (const layer of this.layers.getAll()) {
+      if (layer.meta.maskPreset) this.refresh(layer.id);
+    }
+  }
+  buildClip(id, object) {
+    const width = Math.max(1, object.width ?? 1);
+    const height = Math.max(1, object.height ?? 1);
+    const shared = {
+      originX: "center",
+      originY: "center",
+      left: 0,
+      top: 0,
+      objectCaching: false
+    };
+    if (isShapeMaskId(id)) {
+      return new import_fabric4.Path(shapeMaskPathData(id), {
+        ...shared,
+        scaleX: width / SHAPE_MASK_BOX,
+        scaleY: height / SHAPE_MASK_BOX
+      });
+    }
+    return new import_fabric4.FabricImage(renderTextureMask(id), {
+      ...shared,
+      scaleX: width / TEXTURE_MASK_SIZE,
+      scaleY: height / TEXTURE_MASK_SIZE
+    });
+  }
+};
+
+// src/shadow.ts
+var import_fabric5 = require("fabric");
+
+// src/utils/color.ts
+var CSS_COLOR = /^(?:#[\da-f]{3,8}|(?:rgb|hsl)a?\([\d.%+\-\s,/]+\)|[a-z]+)$/i;
+function isCssColor(value, allowEmpty = false) {
+  if (typeof value !== "string") return false;
+  const trimmed = value.trim();
+  if (!trimmed) return allowEmpty;
+  return CSS_COLOR.test(trimmed);
+}
+
+// src/shadow.ts
+var DEFAULT_LAYER_SHADOW = {
+  enabled: false,
+  color: "#000000",
+  blur: 12,
+  offsetX: 6,
+  offsetY: 6
+};
+function readLayerShadow(object) {
+  const shadow = object.shadow;
+  if (!shadow || typeof shadow === "string") return { ...DEFAULT_LAYER_SHADOW };
+  return {
+    enabled: true,
+    color: typeof shadow.color === "string" ? shadow.color : DEFAULT_LAYER_SHADOW.color,
+    blur: shadow.blur ?? DEFAULT_LAYER_SHADOW.blur,
+    offsetX: shadow.offsetX ?? DEFAULT_LAYER_SHADOW.offsetX,
+    offsetY: shadow.offsetY ?? DEFAULT_LAYER_SHADOW.offsetY
+  };
+}
+function applyLayerShadow(object, config) {
+  const next = { ...readLayerShadow(object), ...config };
+  if (!next.enabled) {
+    object.set({ shadow: null });
+    return;
+  }
+  const color = isCssColor(next.color) ? next.color : DEFAULT_LAYER_SHADOW.color;
+  object.set({
+    shadow: new import_fabric5.Shadow({
+      color,
+      blur: Math.max(0, next.blur),
+      offsetX: next.offsetX,
+      offsetY: next.offsetY
+    })
+  });
+}
+
+// src/transform.ts
+var SIDE_CONTROLS = ["ml", "mr", "mt", "mb"];
+function applyAspectLock(object, locked) {
+  for (const control of SIDE_CONTROLS) {
+    object.setControlVisible(control, !locked);
+  }
+}
+function resetTransform(object) {
+  object.set({
+    scaleX: 1,
+    scaleY: 1,
+    angle: 0,
+    skewX: 0,
+    skewY: 0,
+    flipX: false,
+    flipY: false
+  });
+  object.setCoords();
+}
+
 // src/utils/units.ts
 var MM_PER_INCH = 25.4;
 var UnitConverter = class {
@@ -1101,18 +1725,7 @@ var UnitConverter = class {
 };
 
 // src/serialization.ts
-var import_fabric3 = require("fabric");
-
-// src/utils/color.ts
-var CSS_COLOR = /^(?:#[\da-f]{3,8}|(?:rgb|hsl)a?\([\d.%+\-\s,/]+\)|[a-z]+)$/i;
-function isCssColor(value, allowEmpty = false) {
-  if (typeof value !== "string") return false;
-  const trimmed = value.trim();
-  if (!trimmed) return allowEmpty;
-  return CSS_COLOR.test(trimmed);
-}
-
-// src/serialization.ts
+var import_fabric6 = require("fabric");
 var VERSION = "2.0.0";
 function serializeEditor(editor) {
   return {
@@ -1128,6 +1741,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()
   };
 }
@@ -1146,13 +1760,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 import_fabric3.util.enlivenObjects([serialized.fabricObject]))[0]
-    }))
+    state.layers.map(async (serialized) => {
+      const fabricObject = (await import_fabric6.util.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 import_fabric3.util.enlivenObjects([state.backgroundImage]))[0] : null;
+  const stagedBackground = state.backgroundImage ? (await import_fabric6.util.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);
@@ -1160,7 +1789,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);
@@ -1171,6 +1804,7 @@ function restoreLayer(editor, serialized, fabricObject) {
   const layer = editor.layers.add(serialized.type, fabricObject, serialized.name, serialized.id);
   if (serialized.meta) {
     layer.meta = serialized.meta;
+    if (layer.meta.lockAspect) applyAspectLock(fabricObject, true);
   }
   if (!serialized.visible) {
     editor.layers.setVisibility(layer.id, false);
@@ -1184,6 +1818,62 @@ function restoreLayer(editor, serialized, fabricObject) {
   return layer;
 }
 
+// src/export.ts
+var import_fabric7 = require("fabric");
+
+// src/displacement.ts
+var CHANNEL_INDEX = {
+  red: 0,
+  green: 1,
+  blue: 2,
+  alpha: 3
+};
+function finiteScale(value, fallback, label) {
+  const resolved = value ?? fallback;
+  if (!Number.isFinite(resolved)) throw new Error(`${label} must be finite`);
+  return resolved;
+}
+function sample(source, width, height, x, y, channel) {
+  const clampedX = Math.max(0, Math.min(width - 1, x));
+  const clampedY = Math.max(0, Math.min(height - 1, y));
+  const x0 = Math.floor(clampedX);
+  const y0 = Math.floor(clampedY);
+  const x1 = Math.min(width - 1, x0 + 1);
+  const y1 = Math.min(height - 1, y0 + 1);
+  const tx = clampedX - x0;
+  const ty = clampedY - y0;
+  const top = source[(y0 * width + x0) * 4 + channel] * (1 - tx) + source[(y0 * width + x1) * 4 + channel] * tx;
+  const bottom = source[(y1 * width + x0) * 4 + channel] * (1 - tx) + source[(y1 * width + x1) * 4 + channel] * tx;
+  return top * (1 - ty) + bottom * ty;
+}
+function displaceRgba(source, map, width, height, options) {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+    throw new Error("Displacement dimensions must be positive integers");
+  }
+  const expectedLength = width * height * 4;
+  if (source.length !== expectedLength || map.length !== expectedLength) {
+    throw new Error("Displacement source and map must match the requested dimensions");
+  }
+  const scaleX = finiteScale(options.scaleX, 10, "Displacement scaleX");
+  const scaleY = finiteScale(options.scaleY, 10, "Displacement scaleY");
+  const channelX = CHANNEL_INDEX[options.channelX ?? "red"];
+  const channelY = CHANNEL_INDEX[options.channelY ?? "green"];
+  const output = new Uint8ClampedArray(expectedLength);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const offset = (y * width + x) * 4;
+      const sourceX = x + (map[offset + channelX] - 128) / 127 * scaleX;
+      const sourceY = y + (map[offset + channelY] - 128) / 127 * scaleY;
+      for (let channel = 0; channel < 4; channel += 1) {
+        output[offset + channel] = Math.round(
+          sample(source, width, height, sourceX, sourceY, channel)
+        );
+      }
+    }
+  }
+  return output;
+}
+
 // src/export.ts
 function computePrintAreaClip(area, scaleX, scaleY, targetWidth, targetHeight) {
   const left = Math.max(0, Math.min(targetWidth, area.left * scaleX));
@@ -1221,6 +1911,55 @@ async function exportPNG(canvas, options = {}) {
   const output = canvas.toCanvasElement(multiplier);
   return canvasElementToBlob(output, format, quality);
 }
+async function exportIsolatedPNG(source, objects, options = {}) {
+  const element = source.lowerCanvasEl.ownerDocument.createElement("canvas");
+  const canvas = new import_fabric7.StaticCanvas(element, {
+    width: options.width ?? source.getWidth(),
+    height: options.height ?? source.getHeight(),
+    backgroundColor: options.backgroundColor || void 0
+  });
+  try {
+    const clones = options.cloneObjects === false ? objects : await Promise.all(objects.map((object) => object.clone()));
+    if (clones.length) canvas.add(...clones);
+    if (options.backgroundImage) canvas.backgroundImage = await options.backgroundImage.clone();
+    canvas.requestRenderAll();
+    return await exportPNG(canvas, options);
+  } finally {
+    canvas.dispose();
+  }
+}
+async function exportPrintArea(source, area, options = {}) {
+  const { multiplier = 1, format = "png", quality = 1 } = options;
+  const width = source.getWidth();
+  const height = source.getHeight();
+  const clip = computePrintAreaClip(
+    area,
+    multiplier,
+    multiplier,
+    width * multiplier,
+    height * multiplier
+  );
+  if (clip.width <= 0 || clip.height <= 0) {
+    throw new Error("Print area does not overlap the canvas");
+  }
+  const element = source.lowerCanvasEl.ownerDocument.createElement("canvas");
+  const canvas = new import_fabric7.StaticCanvas(element, { width, height });
+  try {
+    const clones = await Promise.all(source.getObjects().map((object) => object.clone()));
+    if (clones.length) canvas.add(...clones);
+    canvas.requestRenderAll();
+    const rendered = canvas.toCanvasElement(multiplier);
+    const output = rendered.ownerDocument.createElement("canvas");
+    output.width = Math.max(1, Math.round(clip.width));
+    output.height = Math.max(1, Math.round(clip.height));
+    const context = output.getContext("2d");
+    if (!context) throw new Error("2D canvas context is unavailable");
+    context.drawImage(rendered, -clip.left, -clip.top);
+    return await canvasElementToBlob(output, format, quality);
+  } finally {
+    canvas.dispose();
+  }
+}
 async function exportMockup(canvas, mockup, options = {}) {
   const { multiplier = 1, format = "png", quality = 1 } = options;
   const design = canvas.toCanvasElement(multiplier);
@@ -1236,41 +1975,92 @@ async function exportMockup(canvas, mockup, options = {}) {
     element.onerror = () => reject(new Error(`Failed to load mockup image: ${url}`));
     element.src = url;
   });
-  const drawCover = (image) => {
+  const drawCover = (image, targetContext = context) => {
     const placement = computeCoverPlacement(
       image.naturalWidth || image.width,
       image.naturalHeight || image.height,
       output.width,
       output.height
     );
-    context.drawImage(image, placement.left, placement.top, placement.width, placement.height);
-  };
-  drawCover(await loadImage(mockup.image));
-  context.save();
-  if (mockup.printArea && mockup.clipToPrintArea !== false) {
-    const clip = computePrintAreaClip(
-      mockup.printArea,
-      output.width / canvas.getWidth(),
-      output.height / canvas.getHeight(),
-      output.width,
-      output.height
+    targetContext.drawImage(
+      image,
+      placement.left,
+      placement.top,
+      placement.width,
+      placement.height
     );
-    context.beginPath();
-    context.rect(clip.left, clip.top, clip.width, clip.height);
-    context.clip();
-  }
-  context.globalAlpha = Math.max(0, Math.min(1, mockup.designOpacity ?? 1));
-  context.globalCompositeOperation = !mockup.designBlendMode || mockup.designBlendMode === "normal" ? "source-over" : mockup.designBlendMode;
-  context.drawImage(design, 0, 0);
-  context.restore();
-  if (mockup.overlay) {
+  };
+  const scratch = [design];
+  try {
+    drawCover(await loadImage(mockup.image));
+    let compositedDesign = design;
+    if (mockup.displacement) {
+      const sourceContext = design.getContext("2d");
+      if (!sourceContext) throw new Error("2D design context is unavailable");
+      const mapCanvas = design.ownerDocument.createElement("canvas");
+      scratch.push(mapCanvas);
+      mapCanvas.width = design.width;
+      mapCanvas.height = design.height;
+      const mapContext = mapCanvas.getContext("2d");
+      if (!mapContext) throw new Error("2D displacement-map context is unavailable");
+      drawCover(await loadImage(mockup.displacement.image), mapContext);
+      const warped = design.ownerDocument.createElement("canvas");
+      scratch.push(warped);
+      warped.width = design.width;
+      warped.height = design.height;
+      const warpedContext = warped.getContext("2d");
+      if (!warpedContext) throw new Error("2D displaced-design context is unavailable");
+      let sourcePixels;
+      let mapPixels;
+      try {
+        sourcePixels = sourceContext.getImageData(0, 0, design.width, design.height).data;
+        mapPixels = mapContext.getImageData(0, 0, design.width, design.height).data;
+      } catch (error) {
+        throw new Error("Failed to apply mockup displacement map; verify image CORS access", {
+          cause: error
+        });
+      }
+      const pixels = displaceRgba(sourcePixels, mapPixels, design.width, design.height, {
+        ...mockup.displacement,
+        scaleX: (mockup.displacement.scaleX ?? 10) * multiplier,
+        scaleY: (mockup.displacement.scaleY ?? 10) * multiplier
+      });
+      const imageData = warpedContext.createImageData(design.width, design.height);
+      imageData.data.set(pixels);
+      warpedContext.putImageData(imageData, 0, 0);
+      compositedDesign = warped;
+    }
     context.save();
-    context.globalAlpha = Math.max(0, Math.min(1, mockup.overlay.opacity ?? 1));
-    context.globalCompositeOperation = mockup.overlay.blendMode === "normal" ? "source-over" : mockup.overlay.blendMode ?? "multiply";
-    drawCover(await loadImage(mockup.overlay.image));
+    if (mockup.printArea && mockup.clipToPrintArea !== false) {
+      const clip = computePrintAreaClip(
+        mockup.printArea,
+        output.width / canvas.getWidth(),
+        output.height / canvas.getHeight(),
+        output.width,
+        output.height
+      );
+      context.beginPath();
+      context.rect(clip.left, clip.top, clip.width, clip.height);
+      context.clip();
+    }
+    context.globalAlpha = Math.max(0, Math.min(1, mockup.designOpacity ?? 1));
+    context.globalCompositeOperation = !mockup.designBlendMode || mockup.designBlendMode === "normal" ? "source-over" : mockup.designBlendMode;
+    context.drawImage(compositedDesign, 0, 0);
     context.restore();
+    if (mockup.overlay) {
+      context.save();
+      context.globalAlpha = Math.max(0, Math.min(1, mockup.overlay.opacity ?? 1));
+      context.globalCompositeOperation = mockup.overlay.blendMode === "normal" ? "source-over" : mockup.overlay.blendMode ?? "multiply";
+      drawCover(await loadImage(mockup.overlay.image));
+      context.restore();
+    }
+    return await canvasElementToBlob(output, format, quality);
+  } finally {
+    for (const element of scratch) {
+      element.width = 0;
+      element.height = 0;
+    }
   }
-  return canvasElementToBlob(output, format, quality);
 }
 function exportSVG(canvas) {
   return canvas.toSVG();
@@ -1592,9 +2382,270 @@ var ProjectManager = class {
   }
 };
 
+// src/mask.ts
+var import_fabric8 = require("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 import_fabric8.FabricImage(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;
@@ -1604,9 +2655,12 @@ var CanvasEditor = class {
   snapping;
   crop;
   patterns;
+  curves;
+  maskPresets;
   fonts;
   licensing;
   pages;
+  masks;
   fileAdapter;
   imageProvider;
   zoomLevel = 1;
@@ -1616,6 +2670,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();
@@ -1625,7 +2680,7 @@ var CanvasEditor = class {
     const widthPx = this.units.toPixels(config.width);
     const heightPx = this.units.toPixels(config.height);
     this.designBackground = config.backgroundColor ?? "#ffffff";
-    this.canvas = new import_fabric4.Canvas(canvasElement, {
+    this.canvas = new import_fabric9.Canvas(canvasElement, {
       width: widthPx,
       height: heightPx,
       backgroundColor: this.designBackground,
@@ -1653,14 +2708,17 @@ var CanvasEditor = class {
       this.events,
       config.patternSourceResolver
     );
+    this.curves = new TextCurveManager(this.canvas, this.layers, this.history, this.events);
+    this.maskPresets = new MaskPresetManager(this.canvas, this.layers, this.history, this.events);
     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 import_fabric4.FabricImage.fromURL(
+      const img = await import_fabric9.FabricImage.fromURL(
         url,
         {},
         { originX: "left", originY: "top", ...options }
@@ -1676,14 +2734,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 import_fabric4.FabricImage.fromURL(url, {}, { originX: "left", originY: "top" });
+      const replacement = await import_fabric9.FabricImage.fromURL(url, {}, { originX: "left", originY: "top" });
       replacement.set({
         left: previous.left,
         top: previous.top,
@@ -1712,7 +2772,7 @@ var CanvasEditor = class {
     }
   }
   addText(text, options) {
-    const textbox = new import_fabric4.Textbox(text, {
+    const textbox = new import_fabric9.Textbox(text, {
       fontSize: 32,
       fontFamily: "Arial",
       fill: "#000000",
@@ -1751,10 +2811,10 @@ var CanvasEditor = class {
         return value === void 0 ? token : escapeXml(value);
       })
     );
-    const { objects, options } = await (0, import_fabric4.loadSVGFromString)(resolved);
+    const { objects, options } = await (0, import_fabric9.loadSVGFromString)(resolved);
     const validObjects = objects.filter((object) => object !== null);
     if (validObjects.length === 0) throw new Error("Template SVG contains no renderable objects");
-    const group = import_fabric4.util.groupSVGElements(validObjects, options);
+    const group = import_fabric9.util.groupSVGElements(validObjects, options);
     group.set({
       left: this.canvas.getWidth() / 2,
       top: this.canvas.getHeight() / 2,
@@ -1767,6 +2827,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) {
@@ -1824,10 +2887,10 @@ var CanvasEditor = class {
     const next = { ...previous, ...adjustments };
     const clampAdjustment = (value, min = -1) => clamp(value ?? 0, min, 1);
     image.filters = [
-      new import_fabric4.filters.Brightness({ brightness: clampAdjustment(next.brightness) }),
-      new import_fabric4.filters.Contrast({ contrast: clampAdjustment(next.contrast) }),
-      new import_fabric4.filters.Saturation({ saturation: clampAdjustment(next.saturation) }),
-      new import_fabric4.filters.Blur({ blur: clampAdjustment(next.blur, 0) })
+      new import_fabric9.filters.Brightness({ brightness: clampAdjustment(next.brightness) }),
+      new import_fabric9.filters.Contrast({ contrast: clampAdjustment(next.contrast) }),
+      new import_fabric9.filters.Saturation({ saturation: clampAdjustment(next.saturation) }),
+      new import_fabric9.filters.Blur({ blur: clampAdjustment(next.blur, 0) })
     ];
     layer.meta.imageAdjustments = next;
     image.applyFilters();
@@ -1844,7 +2907,7 @@ var CanvasEditor = class {
       const childData = children.map((layer) => structuredClone(layer.toData()));
       const objects = children.map((layer) => layer.fabricObject);
       for (const layer of children) this.layers.remove(layer.id);
-      const group = new import_fabric4.Group(objects);
+      const group = new import_fabric9.Group(objects);
       const grouped = this.layers.add("group", group, name);
       grouped.meta.groupChildren = childData;
       this.layers.select(grouped.id);
@@ -1863,7 +2926,7 @@ var CanvasEditor = class {
       const objects = group.removeAll();
       this.layers.remove(id);
       const restored = objects.map((object, index) => {
-        import_fabric4.util.addTransformToObject(object, transform);
+        import_fabric9.util.addTransformToObject(object, transform);
         object.setCoords();
         const data = childData[index];
         const layer = this.layers.add(data?.type ?? "group", object, data?.name, data?.id);
@@ -1914,6 +2977,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 import_fabric9.FabricImage) {
+        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 {
@@ -1925,7 +3032,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;
     }
   }
@@ -1956,6 +3066,23 @@ var CanvasEditor = class {
   toDataURL(format = "png", multiplier = 1) {
     return this.withDesignBackground(() => exportDataURL(this.canvas, format, multiplier));
   }
+  /**
+   * Export the print file: the design cropped to the mockup's print area, on
+   * transparency. Without a print area this is the whole canvas, still
+   * transparent — a print file never carries the design background.
+   */
+  async toPrintFile(options = {}) {
+    await this.fonts.ready();
+    try {
+      const area = this.mockup?.printArea;
+      const blob = area ? await exportPrintArea(this.canvas, area, options) : await exportIsolatedPNG(this.canvas, this.canvas.getObjects(), options);
+      this.licensing.track(`export:print:${options.format ?? "png"}`);
+      return blob;
+    } catch (error) {
+      this.events.emit("error", { message: "Failed to export print file", error });
+      throw error;
+    }
+  }
   /** Export the current product-preview composite. Advanced warping is host-defined. */
   async toMockupImage(options = {}) {
     if (!this.mockup) throw new Error("No mockup is configured");
@@ -2118,13 +3245,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 import_fabric4.FabricImage.fromURL(url, {}, { originX: "left", originY: "top" });
+      const image = await import_fabric9.FabricImage.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();
@@ -2143,15 +3277,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();
@@ -2292,14 +3429,89 @@ var CanvasEditor = class {
   clearPattern(layerId) {
     return this.patterns.disable(layerId);
   }
+  // ─── Text curve ─────────────────────────────────────
+  applyTextCurve(layerId, config) {
+    return this.curves.apply(layerId, config);
+  }
+  clearTextCurve(layerId) {
+    return this.curves.clear(layerId);
+  }
+  getTextCurve(layerId) {
+    return this.curves.get(layerId);
+  }
+  // ─── Mask presets ───────────────────────────────────
+  applyMaskPreset(layerId, id) {
+    return this.maskPresets.apply(layerId, id);
+  }
+  clearMaskPreset(layerId) {
+    return this.maskPresets.clear(layerId);
+  }
+  getMaskPreset(layerId) {
+    return this.maskPresets.get(layerId);
+  }
+  // ─── Layer transform ────────────────────────────────
+  /**
+   * Constrain a layer to its current proportions. Persisted on the layer so a
+   * reopened design still resizes the way it was set up to.
+   */
+  setLayerAspectLock(layerId, locked) {
+    const layer = this.layers.get(layerId);
+    if (!layer) return false;
+    applyAspectLock(layer.fabricObject, locked);
+    if (locked) layer.meta.lockAspect = true;
+    else delete layer.meta.lockAspect;
+    this.canvas.requestRenderAll();
+    this.events.emit("layer:modified", { layerId });
+    this.history.save();
+    return true;
+  }
+  getLayerAspectLock(layerId) {
+    return this.layers.get(layerId)?.meta.lockAspect === true;
+  }
+  /** Re-apply every stored aspect lock — control visibility is not serialized. */
+  restoreAspectLocks() {
+    for (const layer of this.layers.getAll()) {
+      if (layer.meta.lockAspect) applyAspectLock(layer.fabricObject, true);
+    }
+  }
+  /** Drop scale, rotation, skew and flips; the layer stays where it is. */
+  resetLayerTransform(layerId) {
+    const layer = this.layers.get(layerId);
+    if (!layer) return false;
+    resetTransform(layer.fabricObject);
+    this.canvas.requestRenderAll();
+    this.events.emit("layer:modified", { layerId });
+    this.history.save();
+    return true;
+  }
+  // ─── Shadow ─────────────────────────────────────────
+  setLayerShadow(layerId, config) {
+    const layer = this.layers.get(layerId);
+    if (!layer) return false;
+    applyLayerShadow(layer.fabricObject, config);
+    layer.fabricObject.dirty = true;
+    this.canvas.requestRenderAll();
+    this.events.emit("layer:modified", { layerId });
+    this.history.save();
+    return true;
+  }
+  getLayerShadow(layerId) {
+    const layer = this.layers.get(layerId);
+    return layer ? readLayerShadow(layer.fabricObject) : null;
+  }
   // ─── Mockup (preview-only) ──────────────────────────
-  setMockup(mockup) {
+  /**
+   * Show (or clear) the product preview. Pass `history: false` for preview-only
+   * changes such as swapping a colourway — those are not design edits and
+   * should not fill the undo stack.
+   */
+  setMockup(mockup, options = {}) {
     this.mockup = mockup;
     this.canvas.backgroundColor = mockup ? "" : this.designBackground;
     this.canvas.backgroundImage = mockup ? void 0 : this.designBackgroundImage ?? void 0;
     this.canvas.requestRenderAll();
     this.events.emit("mockup:changed", { mockup });
-    this.history.save();
+    if (options.history !== false) this.history.save();
   }
   clearMockup() {
     this.setMockup(null);
@@ -2309,6 +3521,7 @@ var CanvasEditor = class {
   }
   // ─── Cleanup ────────────────────────────────────────
   dispose() {
+    this.masks.dispose();
     this.snapping.dispose();
     this.crop.dispose();
     this.history.dispose();
@@ -2363,43 +3576,108 @@ 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 };
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AnnotationOverlay,
   CANVAS_SIZE_PRESETS,
   CanvasEditor,
   CropController,
+  DEFAULT_LAYER_SHADOW,
   DEFAULT_PATTERN_CONFIG,
+  DEFAULT_TEXT_CURVE,
   EventEmitter,
   FontRegistry,
   HistoryManager,
   Layer,
   LayerManager,
   LicenseManager,
+  MaskController,
+  MaskPresetManager,
+  MaskRefinementError,
   PatternManager,
   ProjectManager,
+  SHAPE_MASK_BOX,
+  SHAPE_MASK_IDS,
   SnapManager,
+  TEXTURE_MASK_IDS,
+  TEXTURE_MASK_SIZE,
+  TextCurveManager,
   UnitConverter,
+  applyAspectLock,
+  applyLayerShadow,
   applyPatternLocks,
+  buildCurvePathData,
   buildPatternDataURL,
   captureLocks,
   clamp,
   clearPatternImageCache,
+  clearTextureMaskCache,
   computeCoverPlacement,
   computePrintAreaClip,
   computeTilePositions,
   deserializeEditor,
+  displaceRgba,
   drawTiles,
   escapeXml,
   exportDataURL,
   exportMockup,
   exportPNG,
+  exportPrintArea,
   exportSVG,
   generateId,
   isCssColor,
+  isMaskPresetId,
+  isShapeMaskId,
+  isTextureMaskId,
   loadPatternImage,
+  readLayerShadow,
+  renderTextureMask,
+  resetTransform,
   restoreLocks,
   round2,
   sanitizeSvg,
-  serializeEditor
+  serializeEditor,
+  shapeMaskPathData
 });
 //# sourceMappingURL=index.js.map