@pooder/kit 6.2.1 → 6.3.0

package/dist/index.mjs

@@ -1192,6 +1192,442 @@ import {
   controlsUtils
 } from "fabric";
 
+// src/shared/scene/frame.ts
+function emptyFrameRect() {
+  return { left: 0, top: 0, width: 0, height: 0 };
+}
+function resolveCutFrameRect(canvasService, configService) {
+  if (!canvasService || !configService) {
+    return emptyFrameRect();
+  }
+  const sizeState = readSizeState(configService);
+  const layout = computeSceneLayout(canvasService, sizeState);
+  if (!layout) {
+    return emptyFrameRect();
+  }
+  return canvasService.toSceneRect({
+    left: layout.cutRect.left,
+    top: layout.cutRect.top,
+    width: layout.cutRect.width,
+    height: layout.cutRect.height
+  });
+}
+function toLayoutSceneRect(rect) {
+  return {
+    left: rect.left,
+    top: rect.top,
+    width: rect.width,
+    height: rect.height,
+    space: "scene"
+  };
+}
+
+// src/shared/runtime/sessionState.ts
+function cloneWithJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function applyCommittedSnapshot(session, nextCommitted, options) {
+  const clone = options.clone;
+  session.committed = clone(nextCommitted);
+  const shouldPreserveDirtyWorking = options.toolActive && options.preserveDirtyWorking !== false && session.hasWorkingChanges;
+  if (!shouldPreserveDirtyWorking) {
+    session.working = clone(session.committed);
+    session.hasWorkingChanges = false;
+  }
+}
+function runDeferredConfigUpdate(state, action, cooldownMs = 0) {
+  state.isUpdatingConfig = true;
+  action();
+  if (cooldownMs <= 0) {
+    state.isUpdatingConfig = false;
+    return;
+  }
+  setTimeout(() => {
+    state.isUpdatingConfig = false;
+  }, cooldownMs);
+}
+
+// src/extensions/image/commands.ts
+function createImageCommands(tool) {
+  return [
+    {
+      command: "addImage",
+      id: "addImage",
+      title: "Add Image",
+      handler: async (url, options) => {
+        const result = await tool.upsertImageEntry(url, {
+          mode: "add",
+          addOptions: options
+        });
+        return result.id;
+      }
+    },
+    {
+      command: "upsertImage",
+      id: "upsertImage",
+      title: "Upsert Image",
+      handler: async (url, options = {}) => {
+        return await tool.upsertImageEntry(url, options);
+      }
+    },
+    {
+      command: "applyImageOperation",
+      id: "applyImageOperation",
+      title: "Apply Image Operation",
+      handler: async (id, operation, options = {}) => {
+        await tool.applyImageOperation(id, operation, options);
+      }
+    },
+    {
+      command: "getImageViewState",
+      id: "getImageViewState",
+      title: "Get Image View State",
+      handler: () => {
+        return tool.getImageViewState();
+      }
+    },
+    {
+      command: "setImageTransform",
+      id: "setImageTransform",
+      title: "Set Image Transform",
+      handler: async (id, updates, options = {}) => {
+        await tool.setImageTransform(id, updates, options);
+      }
+    },
+    {
+      command: "imageSessionReset",
+      id: "imageSessionReset",
+      title: "Reset Image Session",
+      handler: () => {
+        tool.resetImageSession();
+      }
+    },
+    {
+      command: "completeImages",
+      id: "completeImages",
+      title: "Complete Images",
+      handler: async () => {
+        return await tool.commitWorkingImagesAsCropped();
+      }
+    },
+    {
+      command: "exportUserCroppedImage",
+      id: "exportUserCroppedImage",
+      title: "Export User Cropped Image",
+      handler: async (options = {}) => {
+        return await tool.exportUserCroppedImage(options);
+      }
+    },
+    {
+      command: "focusImage",
+      id: "focusImage",
+      title: "Focus Image",
+      handler: (id, options = {}) => {
+        return tool.setImageFocus(id, options);
+      }
+    },
+    {
+      command: "removeImage",
+      id: "removeImage",
+      title: "Remove Image",
+      handler: (id) => {
+        const sourceItems = tool.isToolActive ? tool.workingItems : tool.items;
+        const removed = sourceItems.find((item) => item.id === id);
+        const next = sourceItems.filter((item) => item.id !== id);
+        if (next.length !== sourceItems.length) {
+          tool.purgeSourceSizeCacheForItem(removed);
+          if (tool.focusedImageId === id) {
+            tool.setImageFocus(null, {
+              syncCanvasSelection: true,
+              skipRender: true
+            });
+          }
+          if (tool.isToolActive) {
+            tool.workingItems = tool.cloneItems(next);
+            tool.hasWorkingChanges = true;
+            tool.updateImages();
+            tool.emitWorkingChange(id);
+            return;
+          }
+          tool.updateConfig(next);
+        }
+      }
+    },
+    {
+      command: "updateImage",
+      id: "updateImage",
+      title: "Update Image",
+      handler: async (id, updates, options = {}) => {
+        await tool.updateImage(id, updates, options);
+      }
+    },
+    {
+      command: "clearImages",
+      id: "clearImages",
+      title: "Clear Images",
+      handler: () => {
+        tool.sourceSizeCache.clear();
+        tool.setImageFocus(null, {
+          syncCanvasSelection: true,
+          skipRender: true
+        });
+        if (tool.isToolActive) {
+          tool.workingItems = [];
+          tool.hasWorkingChanges = true;
+          tool.updateImages();
+          tool.emitWorkingChange();
+          return;
+        }
+        tool.updateConfig([]);
+      }
+    },
+    {
+      command: "bringToFront",
+      id: "bringToFront",
+      title: "Bring Image to Front",
+      handler: (id) => {
+        const sourceItems = tool.isToolActive ? tool.workingItems : tool.items;
+        const index = sourceItems.findIndex((item) => item.id === id);
+        if (index !== -1 && index < sourceItems.length - 1) {
+          const next = [...sourceItems];
+          const [item] = next.splice(index, 1);
+          next.push(item);
+          if (tool.isToolActive) {
+            tool.workingItems = tool.cloneItems(next);
+            tool.hasWorkingChanges = true;
+            tool.updateImages();
+            tool.emitWorkingChange(id);
+            return;
+          }
+          tool.updateConfig(next);
+        }
+      }
+    },
+    {
+      command: "sendToBack",
+      id: "sendToBack",
+      title: "Send Image to Back",
+      handler: (id) => {
+        const sourceItems = tool.isToolActive ? tool.workingItems : tool.items;
+        const index = sourceItems.findIndex((item) => item.id === id);
+        if (index > 0) {
+          const next = [...sourceItems];
+          const [item] = next.splice(index, 1);
+          next.unshift(item);
+          if (tool.isToolActive) {
+            tool.workingItems = tool.cloneItems(next);
+            tool.hasWorkingChanges = true;
+            tool.updateImages();
+            tool.emitWorkingChange(id);
+            return;
+          }
+          tool.updateConfig(next);
+        }
+      }
+    }
+  ];
+}
+
+// src/extensions/image/config.ts
+function createImageConfigurations() {
+  return [
+    {
+      id: "image.items",
+      type: "array",
+      label: "Images",
+      default: []
+    },
+    {
+      id: "image.debug",
+      type: "boolean",
+      label: "Image Debug Log",
+      default: false
+    },
+    {
+      id: "image.control.cornerSize",
+      type: "number",
+      label: "Image Control Corner Size",
+      min: 4,
+      max: 64,
+      step: 1,
+      default: 14
+    },
+    {
+      id: "image.control.touchCornerSize",
+      type: "number",
+      label: "Image Control Touch Corner Size",
+      min: 8,
+      max: 96,
+      step: 1,
+      default: 24
+    },
+    {
+      id: "image.control.cornerStyle",
+      type: "select",
+      label: "Image Control Corner Style",
+      options: ["circle", "rect"],
+      default: "circle"
+    },
+    {
+      id: "image.control.cornerColor",
+      type: "color",
+      label: "Image Control Corner Color",
+      default: "#ffffff"
+    },
+    {
+      id: "image.control.cornerStrokeColor",
+      type: "color",
+      label: "Image Control Corner Stroke Color",
+      default: "#1677ff"
+    },
+    {
+      id: "image.control.transparentCorners",
+      type: "boolean",
+      label: "Image Control Transparent Corners",
+      default: false
+    },
+    {
+      id: "image.control.borderColor",
+      type: "color",
+      label: "Image Control Border Color",
+      default: "#1677ff"
+    },
+    {
+      id: "image.control.borderScaleFactor",
+      type: "number",
+      label: "Image Control Border Width",
+      min: 0.5,
+      max: 8,
+      step: 0.1,
+      default: 1.5
+    },
+    {
+      id: "image.control.padding",
+      type: "number",
+      label: "Image Control Padding",
+      min: 0,
+      max: 64,
+      step: 1,
+      default: 0
+    },
+    {
+      id: "image.frame.strokeColor",
+      type: "color",
+      label: "Image Frame Stroke Color",
+      default: "#808080"
+    },
+    {
+      id: "image.frame.strokeWidth",
+      type: "number",
+      label: "Image Frame Stroke Width",
+      min: 0,
+      max: 20,
+      step: 0.5,
+      default: 2
+    },
+    {
+      id: "image.frame.strokeStyle",
+      type: "select",
+      label: "Image Frame Stroke Style",
+      options: ["solid", "dashed", "hidden"],
+      default: "dashed"
+    },
+    {
+      id: "image.frame.dashLength",
+      type: "number",
+      label: "Image Frame Dash Length",
+      min: 1,
+      max: 40,
+      step: 1,
+      default: 8
+    },
+    {
+      id: "image.frame.innerBackground",
+      type: "color",
+      label: "Image Frame Inner Background",
+      default: "rgba(0,0,0,0)"
+    },
+    {
+      id: "image.frame.outerBackground",
+      type: "color",
+      label: "Image Frame Outer Background",
+      default: "#f5f5f5"
+    }
+  ];
+}
+
+// src/extensions/image/imageOperations.ts
+function clampNormalizedAnchor(value) {
+  return Math.max(-1, Math.min(2, value));
+}
+function toNormalizedAnchor(center, start, size) {
+  return clampNormalizedAnchor((center - start) / Math.max(1, size));
+}
+function resolveAbsoluteScale(operation, area, source) {
+  const widthScale = Math.max(1, area.width) / Math.max(1, source.width);
+  const heightScale = Math.max(1, area.height) / Math.max(1, source.height);
+  switch (operation.type) {
+    case "cover":
+      return Math.max(widthScale, heightScale);
+    case "contain":
+      return Math.min(widthScale, heightScale);
+    case "maximizeWidth":
+      return widthScale;
+    case "maximizeHeight":
+      return heightScale;
+    default:
+      return null;
+  }
+}
+function resolveImageOperationArea(args) {
+  const spec = args.area || { type: "frame" };
+  if (spec.type === "custom") {
+    return {
+      width: Math.max(1, spec.width),
+      height: Math.max(1, spec.height),
+      centerX: spec.centerX,
+      centerY: spec.centerY
+    };
+  }
+  if (spec.type === "viewport") {
+    return {
+      width: Math.max(1, args.viewport.width),
+      height: Math.max(1, args.viewport.height),
+      centerX: args.viewport.left + args.viewport.width / 2,
+      centerY: args.viewport.top + args.viewport.height / 2
+    };
+  }
+  return {
+    width: Math.max(1, args.frame.width),
+    height: Math.max(1, args.frame.height),
+    centerX: args.frame.left + args.frame.width / 2,
+    centerY: args.frame.top + args.frame.height / 2
+  };
+}
+function computeImageOperationUpdates(args) {
+  const { frame, source, operation, area } = args;
+  if (operation.type === "resetTransform") {
+    return {
+      scale: 1,
+      left: 0.5,
+      top: 0.5,
+      angle: 0
+    };
+  }
+  const left = toNormalizedAnchor(area.centerX, frame.left, frame.width);
+  const top = toNormalizedAnchor(area.centerY, frame.top, frame.height);
+  if (operation.type === "center") {
+    return { left, top };
+  }
+  const absoluteScale = resolveAbsoluteScale(operation, area, source);
+  const coverScale = getCoverScale(frame, source);
+  return {
+    scale: Math.max(0.05, (absoluteScale || coverScale) / coverScale),
+    left,
+    top
+  };
+}
+
 // src/extensions/geometry.ts
 import paper from "paper";
 
@@ -1768,391 +2204,177 @@ function generateBleedZonePath(originalOptions, offsetOptions, offset) {
   }
   const pathData = bleedZone.pathData;
   shapeOriginal.remove();
-  shapeOffset.remove();
-  bleedZone.remove();
-  return pathData;
-}
-function getLowestPointOnDieline(options) {
-  ensurePaper(options.width * 2, options.height * 2);
-  paper.project.activeLayer.removeChildren();
-  const shape = createBaseShape(options);
-  const bounds = shape.bounds;
-  const result = {
-    x: bounds.center.x,
-    y: bounds.bottom
-  };
-  shape.remove();
-  return result;
-}
-function getNearestPointOnDieline(point, options) {
-  ensurePaper(options.width * 2, options.height * 2);
-  paper.project.activeLayer.removeChildren();
-  const shape = createBaseShape(options);
-  const p = new paper.Point(point.x, point.y);
-  const location = shape.getNearestLocation(p);
-  const result = {
-    x: location.point.x,
-    y: location.point.y,
-    normal: location.normal ? { x: location.normal.x, y: location.normal.y } : void 0
-  };
-  shape.remove();
-  return result;
-}
-function getPathBounds(pathData) {
-  const path = new paper.Path();
-  path.pathData = pathData;
-  const bounds = path.bounds;
-  path.remove();
-  return {
-    x: bounds.x,
-    y: bounds.y,
-    width: bounds.width,
-    height: bounds.height
-  };
-}
-
-// src/shared/scene/frame.ts
-function emptyFrameRect() {
-  return { left: 0, top: 0, width: 0, height: 0 };
-}
-function resolveCutFrameRect(canvasService, configService) {
-  if (!canvasService || !configService) {
-    return emptyFrameRect();
-  }
-  const sizeState = readSizeState(configService);
-  const layout = computeSceneLayout(canvasService, sizeState);
-  if (!layout) {
-    return emptyFrameRect();
-  }
-  return canvasService.toSceneRect({
-    left: layout.cutRect.left,
-    top: layout.cutRect.top,
-    width: layout.cutRect.width,
-    height: layout.cutRect.height
-  });
-}
-function toLayoutSceneRect(rect) {
-  return {
-    left: rect.left,
-    top: rect.top,
-    width: rect.width,
-    height: rect.height,
-    space: "scene"
-  };
-}
-
-// src/shared/runtime/sessionState.ts
-function cloneWithJson(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-function applyCommittedSnapshot(session, nextCommitted, options) {
-  const clone = options.clone;
-  session.committed = clone(nextCommitted);
-  const shouldPreserveDirtyWorking = options.toolActive && options.preserveDirtyWorking !== false && session.hasWorkingChanges;
-  if (!shouldPreserveDirtyWorking) {
-    session.working = clone(session.committed);
-    session.hasWorkingChanges = false;
-  }
-}
-function runDeferredConfigUpdate(state, action, cooldownMs = 0) {
-  state.isUpdatingConfig = true;
-  action();
-  if (cooldownMs <= 0) {
-    state.isUpdatingConfig = false;
-    return;
-  }
-  setTimeout(() => {
-    state.isUpdatingConfig = false;
-  }, cooldownMs);
-}
-
-// src/extensions/image/commands.ts
-function createImageCommands(tool) {
-  return [
-    {
-      command: "addImage",
-      id: "addImage",
-      title: "Add Image",
-      handler: async (url, options) => {
-        const result = await tool.upsertImageEntry(url, {
-          mode: "add",
-          addOptions: options
-        });
-        return result.id;
-      }
-    },
-    {
-      command: "upsertImage",
-      id: "upsertImage",
-      title: "Upsert Image",
-      handler: async (url, options = {}) => {
-        return await tool.upsertImageEntry(url, options);
-      }
-    },
-    {
-      command: "getWorkingImages",
-      id: "getWorkingImages",
-      title: "Get Working Images",
-      handler: () => {
-        return tool.cloneItems(tool.workingItems);
-      }
-    },
-    {
-      command: "setWorkingImage",
-      id: "setWorkingImage",
-      title: "Set Working Image",
-      handler: (id, updates) => {
-        tool.updateImageInWorking(id, updates);
-      }
-    },
-    {
-      command: "resetWorkingImages",
-      id: "resetWorkingImages",
-      title: "Reset Working Images",
-      handler: () => {
-        tool.workingItems = tool.cloneItems(tool.items);
-        tool.hasWorkingChanges = false;
-        tool.updateImages();
-        tool.emitWorkingChange();
-      }
-    },
-    {
-      command: "completeImages",
-      id: "completeImages",
-      title: "Complete Images",
-      handler: async () => {
-        return await tool.commitWorkingImagesAsCropped();
-      }
-    },
-    {
-      command: "exportUserCroppedImage",
-      id: "exportUserCroppedImage",
-      title: "Export User Cropped Image",
-      handler: async (options = {}) => {
-        return await tool.exportUserCroppedImage(options);
-      }
-    },
-    {
-      command: "fitImageToArea",
-      id: "fitImageToArea",
-      title: "Fit Image to Area",
-      handler: async (id, area) => {
-        await tool.fitImageToArea(id, area);
-      }
-    },
-    {
-      command: "fitImageToDefaultArea",
-      id: "fitImageToDefaultArea",
-      title: "Fit Image to Default Area",
-      handler: async (id) => {
-        await tool.fitImageToDefaultArea(id);
-      }
-    },
-    {
-      command: "focusImage",
-      id: "focusImage",
-      title: "Focus Image",
-      handler: (id, options = {}) => {
-        return tool.setImageFocus(id, options);
-      }
-    },
-    {
-      command: "removeImage",
-      id: "removeImage",
-      title: "Remove Image",
-      handler: (id) => {
-        const removed = tool.items.find((item) => item.id === id);
-        const next = tool.items.filter((item) => item.id !== id);
-        if (next.length !== tool.items.length) {
-          tool.purgeSourceSizeCacheForItem(removed);
-          if (tool.focusedImageId === id) {
-            tool.setImageFocus(null, {
-              syncCanvasSelection: true,
-              skipRender: true
-            });
-          }
-          tool.updateConfig(next);
-        }
-      }
-    },
-    {
-      command: "updateImage",
-      id: "updateImage",
-      title: "Update Image",
-      handler: async (id, updates, options = {}) => {
-        await tool.updateImage(id, updates, options);
-      }
-    },
-    {
-      command: "clearImages",
-      id: "clearImages",
-      title: "Clear Images",
-      handler: () => {
-        tool.sourceSizeCache.clear();
-        tool.setImageFocus(null, {
-          syncCanvasSelection: true,
-          skipRender: true
-        });
-        tool.updateConfig([]);
-      }
-    },
-    {
-      command: "bringToFront",
-      id: "bringToFront",
-      title: "Bring Image to Front",
-      handler: (id) => {
-        const index = tool.items.findIndex((item) => item.id === id);
-        if (index !== -1 && index < tool.items.length - 1) {
-          const next = [...tool.items];
-          const [item] = next.splice(index, 1);
-          next.push(item);
-          tool.updateConfig(next);
-        }
-      }
-    },
-    {
-      command: "sendToBack",
-      id: "sendToBack",
-      title: "Send Image to Back",
-      handler: (id) => {
-        const index = tool.items.findIndex((item) => item.id === id);
-        if (index > 0) {
-          const next = [...tool.items];
-          const [item] = next.splice(index, 1);
-          next.unshift(item);
-          tool.updateConfig(next);
-        }
-      }
-    }
-  ];
+  shapeOffset.remove();
+  bleedZone.remove();
+  return pathData;
+}
+function getLowestPointOnDieline(options) {
+  ensurePaper(options.width * 2, options.height * 2);
+  paper.project.activeLayer.removeChildren();
+  const shape = createBaseShape(options);
+  const bounds = shape.bounds;
+  const result = {
+    x: bounds.center.x,
+    y: bounds.bottom
+  };
+  shape.remove();
+  return result;
+}
+function getNearestPointOnDieline(point, options) {
+  ensurePaper(options.width * 2, options.height * 2);
+  paper.project.activeLayer.removeChildren();
+  const shape = createBaseShape(options);
+  const p = new paper.Point(point.x, point.y);
+  const location = shape.getNearestLocation(p);
+  const result = {
+    x: location.point.x,
+    y: location.point.y,
+    normal: location.normal ? { x: location.normal.x, y: location.normal.y } : void 0
+  };
+  shape.remove();
+  return result;
 }
 
-// src/extensions/image/config.ts
-function createImageConfigurations() {
+// src/extensions/image/sessionOverlay.ts
+var EPSILON = 1e-4;
+var SHAPE_OUTLINE_COLOR = "rgba(255, 0, 0, 0.9)";
+var DEFAULT_HATCH_FILL = "rgba(255, 0, 0, 0.22)";
+function buildRectPath(width, height) {
+  return `M 0 0 L ${width} 0 L ${width} ${height} L 0 ${height} Z`;
+}
+function buildViewportMaskPath(viewport, cutRect) {
+  const cutLeft = cutRect.left - viewport.left;
+  const cutTop = cutRect.top - viewport.top;
   return [
-    {
-      id: "image.items",
-      type: "array",
-      label: "Images",
-      default: []
-    },
-    {
-      id: "image.debug",
-      type: "boolean",
-      label: "Image Debug Log",
-      default: false
-    },
-    {
-      id: "image.control.cornerSize",
-      type: "number",
-      label: "Image Control Corner Size",
-      min: 4,
-      max: 64,
-      step: 1,
-      default: 14
-    },
-    {
-      id: "image.control.touchCornerSize",
-      type: "number",
-      label: "Image Control Touch Corner Size",
-      min: 8,
-      max: 96,
-      step: 1,
-      default: 24
-    },
-    {
-      id: "image.control.cornerStyle",
-      type: "select",
-      label: "Image Control Corner Style",
-      options: ["circle", "rect"],
-      default: "circle"
-    },
-    {
-      id: "image.control.cornerColor",
-      type: "color",
-      label: "Image Control Corner Color",
-      default: "#ffffff"
-    },
-    {
-      id: "image.control.cornerStrokeColor",
-      type: "color",
-      label: "Image Control Corner Stroke Color",
-      default: "#1677ff"
-    },
-    {
-      id: "image.control.transparentCorners",
-      type: "boolean",
-      label: "Image Control Transparent Corners",
-      default: false
-    },
-    {
-      id: "image.control.borderColor",
-      type: "color",
-      label: "Image Control Border Color",
-      default: "#1677ff"
-    },
-    {
-      id: "image.control.borderScaleFactor",
-      type: "number",
-      label: "Image Control Border Width",
-      min: 0.5,
-      max: 8,
-      step: 0.1,
-      default: 1.5
-    },
-    {
-      id: "image.control.padding",
-      type: "number",
-      label: "Image Control Padding",
-      min: 0,
-      max: 64,
-      step: 1,
-      default: 0
-    },
-    {
-      id: "image.frame.strokeColor",
-      type: "color",
-      label: "Image Frame Stroke Color",
-      default: "#808080"
-    },
-    {
-      id: "image.frame.strokeWidth",
-      type: "number",
-      label: "Image Frame Stroke Width",
-      min: 0,
-      max: 20,
-      step: 0.5,
-      default: 2
-    },
-    {
-      id: "image.frame.strokeStyle",
-      type: "select",
-      label: "Image Frame Stroke Style",
-      options: ["solid", "dashed", "hidden"],
-      default: "dashed"
-    },
-    {
-      id: "image.frame.dashLength",
-      type: "number",
-      label: "Image Frame Dash Length",
-      min: 1,
-      max: 40,
-      step: 1,
-      default: 8
-    },
-    {
-      id: "image.frame.innerBackground",
-      type: "color",
-      label: "Image Frame Inner Background",
-      default: "rgba(0,0,0,0)"
-    },
-    {
-      id: "image.frame.outerBackground",
-      type: "color",
-      label: "Image Frame Outer Background",
-      default: "#f5f5f5"
+    buildRectPath(viewport.width, viewport.height),
+    `M ${cutLeft} ${cutTop} L ${cutLeft + cutRect.width} ${cutTop} L ${cutLeft + cutRect.width} ${cutTop + cutRect.height} L ${cutLeft} ${cutTop + cutRect.height} Z`
+  ].join(" ");
+}
+function resolveCutShapeRadiusPx(geometry, cutRect) {
+  const visualRadius = Number.isFinite(geometry.radius) ? Math.max(0, geometry.radius) : 0;
+  const visualOffset = Number.isFinite(geometry.offset) ? geometry.offset : 0;
+  const rawCutRadius = visualRadius === 0 ? 0 : Math.max(0, visualRadius + visualOffset);
+  const maxRadius = Math.max(0, Math.min(cutRect.width, cutRect.height) / 2);
+  return Math.max(0, Math.min(maxRadius, rawCutRadius));
+}
+function buildBuiltinShapeOverlayPaths(cutRect, geometry) {
+  if (!geometry || geometry.shape === "custom") {
+    return null;
+  }
+  const radius = resolveCutShapeRadiusPx(geometry, cutRect);
+  if (geometry.shape === "rect" && radius <= EPSILON) {
+    return null;
+  }
+  const shapePathData = generateDielinePath({
+    shape: geometry.shape,
+    shapeStyle: geometry.shapeStyle,
+    width: Math.max(1, cutRect.width),
+    height: Math.max(1, cutRect.height),
+    radius,
+    x: cutRect.width / 2,
+    y: cutRect.height / 2,
+    features: [],
+    canvasWidth: Math.max(1, cutRect.width),
+    canvasHeight: Math.max(1, cutRect.height)
+  });
+  if (!shapePathData) {
+    return null;
+  }
+  return {
+    shapePathData,
+    hatchPathData: `${buildRectPath(cutRect.width, cutRect.height)} ${shapePathData}`
+  };
+}
+function buildImageSessionOverlaySpecs(args) {
+  const { viewport, layout, geometry, visual, hatchPattern } = args;
+  const cutRect = layout.cutRect;
+  const specs = [];
+  specs.push({
+    id: "image.cropMask.rect",
+    type: "path",
+    space: "screen",
+    data: { id: "image.cropMask.rect", zIndex: 1 },
+    props: {
+      pathData: buildViewportMaskPath(viewport, cutRect),
+      left: viewport.left,
+      top: viewport.top,
+      originX: "left",
+      originY: "top",
+      fill: visual.outerBackground,
+      stroke: null,
+      fillRule: "evenodd",
+      selectable: false,
+      evented: false,
+      excludeFromExport: true,
+      objectCaching: false
     }
-  ];
+  });
+  const shapeOverlay = buildBuiltinShapeOverlayPaths(cutRect, geometry);
+  if (shapeOverlay) {
+    specs.push({
+      id: "image.cropShapeHatch",
+      type: "path",
+      space: "screen",
+      data: { id: "image.cropShapeHatch", zIndex: 5 },
+      props: {
+        pathData: shapeOverlay.hatchPathData,
+        left: cutRect.left,
+        top: cutRect.top,
+        originX: "left",
+        originY: "top",
+        fill: hatchPattern || DEFAULT_HATCH_FILL,
+        opacity: hatchPattern ? 1 : 0.8,
+        stroke: null,
+        fillRule: "evenodd",
+        selectable: false,
+        evented: false,
+        excludeFromExport: true,
+        objectCaching: false
+      }
+    });
+    specs.push({
+      id: "image.cropShapeOutline",
+      type: "path",
+      space: "screen",
+      data: { id: "image.cropShapeOutline", zIndex: 6 },
+      props: {
+        pathData: shapeOverlay.shapePathData,
+        left: cutRect.left,
+        top: cutRect.top,
+        originX: "left",
+        originY: "top",
+        fill: "transparent",
+        stroke: SHAPE_OUTLINE_COLOR,
+        strokeWidth: 1,
+        selectable: false,
+        evented: false,
+        excludeFromExport: true,
+        objectCaching: false
+      }
+    });
+  }
+  specs.push({
+    id: "image.cropFrame",
+    type: "rect",
+    space: "screen",
+    data: { id: "image.cropFrame", zIndex: 7 },
+    props: {
+      left: cutRect.left,
+      top: cutRect.top,
+      width: cutRect.width,
+      height: cutRect.height,
+      originX: "left",
+      originY: "top",
+      fill: visual.innerBackground,
+      stroke: visual.strokeStyle === "hidden" ? "rgba(0,0,0,0)" : visual.strokeColor,
+      strokeWidth: visual.strokeStyle === "hidden" ? 0 : visual.strokeWidth,
+      strokeDashArray: visual.strokeStyle === "dashed" ? [visual.dashLength, visual.dashLength] : void 0,
+      selectable: false,
+      evented: false,
+      excludeFromExport: true
+    }
+  });
+  return specs;
 }
 
 // src/extensions/image/ImageTool.ts
@@ -2440,6 +2662,7 @@ var ImageTool = class {
     this.clearRenderedImages();
     (_b = this.renderProducerDisposable) == null ? void 0 : _b.dispose();
     this.renderProducerDisposable = void 0;
+    this.emitImageStateChange();
     if (this.canvasService) {
       void this.canvasService.flushRenderFromProducers();
       this.canvasService = void 0;
@@ -2614,11 +2837,21 @@ var ImageTool = class {
       (_a = this.canvasService) == null ? void 0 : _a.requestRenderAll();
     }
   }
+  clearSnapGuideContext() {
+    var _a;
+    const topContext = (_a = this.canvasService) == null ? void 0 : _a.canvas.contextTop;
+    if (!this.canvasService || !topContext) return;
+    this.canvasService.canvas.clearContext(topContext);
+  }
   clearSnapPreview() {
     var _a;
+    const shouldClearCanvas = this.hasRenderedSnapGuides || !!this.activeSnapX || !!this.activeSnapY;
     this.activeSnapX = null;
     this.activeSnapY = null;
     this.hasRenderedSnapGuides = false;
+    if (shouldClearCanvas) {
+      this.clearSnapGuideContext();
+    }
     (_a = this.canvasService) == null ? void 0 : _a.requestRenderAll();
   }
   endMoveSnapInteraction() {
@@ -2839,9 +3072,9 @@ var ImageTool = class {
           name: "Image",
           interaction: "session",
           commands: {
-            begin: "resetWorkingImages",
+            begin: "imageSessionReset",
             commit: "completeImages",
-            rollback: "resetWorkingImages"
+            rollback: "imageSessionReset"
           },
           session: {
             autoBegin: true,
@@ -2875,6 +3108,28 @@ var ImageTool = class {
   cloneItems(items) {
     return this.normalizeItems((items || []).map((i) => ({ ...i })));
   }
+  getViewItems() {
+    return this.isToolActive ? this.workingItems : this.items;
+  }
+  getImageViewState() {
+    this.syncToolActiveFromWorkbench();
+    const items = this.cloneItems(this.getViewItems());
+    const focusedItem = this.focusedImageId == null ? null : items.find((item) => item.id === this.focusedImageId) || null;
+    return {
+      items,
+      hasAnyImage: items.length > 0,
+      focusedId: this.focusedImageId,
+      focusedItem,
+      isToolActive: this.isToolActive,
+      isImageSelectionActive: this.isImageSelectionActive,
+      hasWorkingChanges: this.hasWorkingChanges,
+      source: this.isToolActive ? "working" : "committed"
+    };
+  }
+  emitImageStateChange() {
+    var _a;
+    (_a = this.context) == null ? void 0 : _a.eventBus.emit("image:state:change", this.getImageViewState());
+  }
   emitWorkingChange(changedId = null) {
     var _a;
     (_a = this.context) == null ? void 0 : _a.eventBus.emit("image:working:change", {
@@ -2910,10 +3165,13 @@ var ImageTool = class {
     }
     if (!options.skipRender) {
       this.updateImages();
+    } else {
+      this.emitImageStateChange();
     }
     return { ok: true, id };
   }
-  async addImageEntry(url, options, fitOnAdd = true) {
+  async addImageEntry(url, options, operation) {
+    this.syncToolActiveFromWorkbench();
     const id = this.generateId();
     const newItem = this.normalizeItem({
       id,
@@ -2921,13 +3179,20 @@ var ImageTool = class {
       opacity: 1,
       ...options
     });
-    const sessionDirtyBeforeAdd = this.isToolActive && this.hasWorkingChanges;
     const waitLoaded = this.waitImageLoaded(id, true);
-    this.updateConfig([...this.items, newItem]);
-    this.addItemToWorkingSessionIfNeeded(newItem, sessionDirtyBeforeAdd);
+    if (this.isToolActive) {
+      this.workingItems = this.cloneItems([...this.workingItems, newItem]);
+      this.hasWorkingChanges = true;
+      this.updateImages();
+      this.emitWorkingChange(id);
+    } else {
+      this.updateConfig([...this.items, newItem]);
+    }
     const loaded = await waitLoaded;
-    if (loaded && fitOnAdd) {
-      await this.fitImageToDefaultArea(id);
+    if (loaded && operation) {
+      await this.applyImageOperation(id, operation, {
+        target: this.isToolActive ? "working" : "config"
+      });
     }
     if (loaded) {
       this.setImageFocus(id);
@@ -2935,8 +3200,8 @@ var ImageTool = class {
     return id;
   }
   async upsertImageEntry(url, options = {}) {
+    this.syncToolActiveFromWorkbench();
     const mode = options.mode || (options.id ? "replace" : "add");
-    const fitOnAdd = options.fitOnAdd !== false;
     if (mode === "replace") {
       if (!options.id) {
         throw new Error("replace-target-id-required");
@@ -2945,19 +3210,31 @@ var ImageTool = class {
       if (!this.hasImageItem(targetId)) {
         throw new Error("replace-target-not-found");
       }
-      await this.updateImageInConfig(targetId, { url });
+      if (this.isToolActive) {
+        const current = this.workingItems.find((item) => item.id === targetId) || this.items.find((item) => item.id === targetId);
+        this.purgeSourceSizeCacheForItem(current);
+        this.updateImageInWorking(targetId, {
+          url,
+          sourceUrl: url,
+          committedUrl: void 0
+        });
+      } else {
+        await this.updateImageInConfig(targetId, { url });
+      }
+      const loaded = await this.waitImageLoaded(targetId, true);
+      if (loaded && options.operation) {
+        await this.applyImageOperation(targetId, options.operation, {
+          target: this.isToolActive ? "working" : "config"
+        });
+      }
+      if (loaded) {
+        this.setImageFocus(targetId);
+      }
       return { id: targetId, mode: "replace" };
     }
-    const id = await this.addImageEntry(url, options.addOptions, fitOnAdd);
+    const id = await this.addImageEntry(url, options.addOptions, options.operation);
     return { id, mode: "add" };
   }
-  addItemToWorkingSessionIfNeeded(item, sessionDirtyBeforeAdd) {
-    if (!sessionDirtyBeforeAdd || !this.isToolActive) return;
-    if (this.workingItems.some((existing) => existing.id === item.id)) return;
-    this.workingItems = this.cloneItems([...this.workingItems, item]);
-    this.updateImages();
-    this.emitWorkingChange(item.id);
-  }
   async updateImage(id, updates, options = {}) {
     this.syncToolActiveFromWorkbench();
     const target = options.target || "auto";
@@ -3018,40 +3295,9 @@ var ImageTool = class {
   }
   getFrameRectScreen(frame) {
     if (!this.canvasService) {
-      return { left: 0, top: 0, width: 0, height: 0 };
-    }
-    return this.canvasService.toScreenRect(frame || this.getFrameRect());
-  }
-  toLayoutSceneRect(rect) {
-    return toLayoutSceneRect(rect);
-  }
-  async resolveDefaultFitArea() {
-    if (!this.canvasService) return null;
-    const frame = this.getFrameRect();
-    if (frame.width <= 0 || frame.height <= 0) return null;
-    return {
-      width: Math.max(1, frame.width),
-      height: Math.max(1, frame.height),
-      left: frame.left + frame.width / 2,
-      top: frame.top + frame.height / 2
-    };
-  }
-  async fitImageToDefaultArea(id) {
-    if (!this.canvasService) return;
-    const area = await this.resolveDefaultFitArea();
-    if (area) {
-      await this.fitImageToArea(id, area);
-      return;
+      return { left: 0, top: 0, width: 0, height: 0 };
     }
-    const viewport = this.canvasService.getSceneViewportRect();
-    const canvasW = Math.max(1, viewport.width || 0);
-    const canvasH = Math.max(1, viewport.height || 0);
-    await this.fitImageToArea(id, {
-      width: canvasW,
-      height: canvasH,
-      left: viewport.left + canvasW / 2,
-      top: viewport.top + canvasH / 2
-    });
+    return this.canvasService.toScreenRect(frame || this.getFrameRect());
   }
   getImageObjects() {
     if (!this.canvasService) return [];
@@ -3151,74 +3397,37 @@ var ImageTool = class {
       outerBackground: this.getConfig("image.frame.outerBackground", "#f5f5f5") || "#f5f5f5"
     };
   }
-  toSceneGeometryLike(raw) {
-    const shape = raw == null ? void 0 : raw.shape;
-    if (!isDielineShape(shape)) {
+  resolveSessionOverlayState() {
+    if (!this.canvasService || !this.context) {
       return null;
     }
-    const radiusRaw = Number(raw == null ? void 0 : raw.radius);
-    const offsetRaw = Number(raw == null ? void 0 : raw.offset);
-    const unit = typeof (raw == null ? void 0 : raw.unit) === "string" ? raw.unit : "px";
-    const radius = unit === "scene" || !this.canvasService ? radiusRaw : this.canvasService.toSceneLength(radiusRaw);
-    const offset = unit === "scene" || !this.canvasService ? offsetRaw : this.canvasService.toSceneLength(offsetRaw);
-    return {
-      shape,
-      shapeStyle: normalizeShapeStyle(raw == null ? void 0 : raw.shapeStyle),
-      radius: Number.isFinite(radius) ? radius : 0,
-      offset: Number.isFinite(offset) ? offset : 0
-    };
-  }
-  async resolveSceneGeometryForOverlay() {
-    if (!this.context) return null;
-    const commandService = this.context.services.get("CommandService");
-    if (commandService) {
-      try {
-        const raw = await Promise.resolve(
-          commandService.executeCommand("getSceneGeometry")
-        );
-        const geometry2 = this.toSceneGeometryLike(raw);
-        if (geometry2) {
-          this.debug("overlay:sceneGeometry:command", geometry2);
-          return geometry2;
-        }
-        this.debug("overlay:sceneGeometry:command:invalid", { raw });
-      } catch (error) {
-        this.debug("overlay:sceneGeometry:command:error", {
-          error: error instanceof Error ? error.message : String(error)
-        });
-      }
-    }
-    if (!this.canvasService) return null;
     const configService = this.context.services.get(
       "ConfigurationService"
     );
-    if (!configService) return null;
-    const sizeState = readSizeState(configService);
-    const layout = computeSceneLayout(this.canvasService, sizeState);
-    if (!layout) {
-      this.debug("overlay:sceneGeometry:fallback:missing-layout");
+    if (!configService) {
       return null;
     }
-    const geometry = this.toSceneGeometryLike(
-      buildSceneGeometry(configService, layout)
+    const layout = computeSceneLayout(
+      this.canvasService,
+      readSizeState(configService)
     );
-    if (geometry) {
-      this.debug("overlay:sceneGeometry:fallback", geometry);
+    if (!layout) {
+      this.debug("overlay:layout:missing");
+      return null;
     }
-    return geometry;
-  }
-  resolveCutShapeRadius(geometry, frame) {
-    const visualRadius = Number.isFinite(geometry.radius) ? Math.max(0, geometry.radius) : 0;
-    const visualOffset = Number.isFinite(geometry.offset) ? geometry.offset : 0;
-    const rawCutRadius = visualRadius === 0 ? 0 : Math.max(0, visualRadius + visualOffset);
-    const maxRadius = Math.max(0, Math.min(frame.width, frame.height) / 2);
-    return Math.max(0, Math.min(maxRadius, rawCutRadius));
+    const geometry = buildSceneGeometry(configService, layout);
+    this.debug("overlay:state:resolved", {
+      cutRect: layout.cutRect,
+      shape: geometry.shape,
+      shapeStyle: geometry.shapeStyle,
+      radius: geometry.radius,
+      offset: geometry.offset
+    });
+    return { layout, geometry };
   }
   getCropShapeHatchPattern(color = "rgba(255, 0, 0, 0.6)") {
-    var _a;
     if (typeof document === "undefined") return void 0;
-    const sceneScale = ((_a = this.canvasService) == null ? void 0 : _a.getSceneScale()) || 1;
-    const cacheKey = `${color}::${sceneScale.toFixed(6)}`;
+    const cacheKey = color;
     if (this.cropShapeHatchPattern && this.cropShapeHatchPatternColor === color && this.cropShapeHatchPatternKey === cacheKey) {
       return this.cropShapeHatchPattern;
     }
@@ -3248,138 +3457,11 @@ var ImageTool = class {
       // @ts-ignore: Fabric Pattern accepts canvas source here.
       repetition: "repeat"
     });
-    pattern.patternTransform = [
-      1 / sceneScale,
-      0,
-      0,
-      1 / sceneScale,
-      0,
-      0
-    ];
     this.cropShapeHatchPattern = pattern;
     this.cropShapeHatchPatternColor = color;
     this.cropShapeHatchPatternKey = cacheKey;
     return pattern;
   }
-  buildCropShapeOverlaySpecs(frame, sceneGeometry) {
-    var _a, _b;
-    if (!sceneGeometry) {
-      this.debug("overlay:shape:skip", { reason: "scene-geometry-missing" });
-      return [];
-    }
-    if (sceneGeometry.shape === "custom") {
-      this.debug("overlay:shape:skip", { reason: "shape-custom" });
-      return [];
-    }
-    const shape = sceneGeometry.shape;
-    const shapeStyle = sceneGeometry.shapeStyle;
-    const inset = 0;
-    const shapeWidth = Math.max(1, frame.width);
-    const shapeHeight = Math.max(1, frame.height);
-    const radius = this.resolveCutShapeRadius(sceneGeometry, frame);
-    this.debug("overlay:shape:geometry", {
-      shape,
-      frameWidth: frame.width,
-      frameHeight: frame.height,
-      offset: sceneGeometry.offset,
-      shapeStyle,
-      inset,
-      shapeWidth,
-      shapeHeight,
-      baseRadius: sceneGeometry.radius,
-      radius
-    });
-    const isSameAsFrame = Math.abs(shapeWidth - frame.width) <= 1e-4 && Math.abs(shapeHeight - frame.height) <= 1e-4;
-    if (shape === "rect" && radius <= 1e-4 && isSameAsFrame) {
-      this.debug("overlay:shape:skip", {
-        reason: "shape-rect-no-radius"
-      });
-      return [];
-    }
-    const baseOptions = {
-      shape,
-      width: shapeWidth,
-      height: shapeHeight,
-      radius,
-      x: frame.width / 2,
-      y: frame.height / 2,
-      features: [],
-      shapeStyle,
-      canvasWidth: frame.width,
-      canvasHeight: frame.height
-    };
-    try {
-      const shapePathData = generateDielinePath(baseOptions);
-      const outerRectPathData = `M 0 0 L ${frame.width} 0 L ${frame.width} ${frame.height} L 0 ${frame.height} Z`;
-      const hatchPathData = `${outerRectPathData} ${shapePathData}`;
-      if (!shapePathData || !hatchPathData) {
-        this.debug("overlay:shape:skip", {
-          reason: "path-generation-empty",
-          shape,
-          radius
-        });
-        return [];
-      }
-      const patternFill = this.getCropShapeHatchPattern();
-      const hatchFill = patternFill || "rgba(255, 0, 0, 0.22)";
-      const shapeBounds = getPathBounds(shapePathData);
-      const hatchBounds = getPathBounds(hatchPathData);
-      const frameRect = this.toLayoutSceneRect(frame);
-      const hatchPathLength = hatchPathData.length;
-      const shapePathLength = shapePathData.length;
-      const specs = [
-        {
-          id: "image.cropShapeHatch",
-          type: "path",
-          data: { id: "image.cropShapeHatch", zIndex: 5 },
-          layout: {
-            reference: "custom",
-            referenceRect: frameRect,
-            alignX: "start",
-            alignY: "start",
-            offsetX: hatchBounds.x,
-            offsetY: hatchBounds.y
-          },
-          props: {
-            pathData: hatchPathData,
-            originX: "left",
-            originY: "top",
-            fill: hatchFill,
-            opacity: patternFill ? 1 : 0.8,
-            stroke: "rgba(255, 0, 0, 0.9)",
-            strokeWidth: (_b = (_a = this.canvasService) == null ? void 0 : _a.toSceneLength(1)) != null ? _b : 1,
-            fillRule: "evenodd",
-            selectable: false,
-            evented: false,
-            excludeFromExport: true,
-            objectCaching: false
-          }
-        }
-      ];
-      this.debug("overlay:shape:built", {
-        shape,
-        radius,
-        inset,
-        shapeWidth,
-        shapeHeight,
-        fillRule: "evenodd",
-        shapePathLength,
-        hatchPathLength,
-        shapeBounds,
-        hatchBounds,
-        hatchFillType: hatchFill && typeof hatchFill === "object" ? "pattern" : "color",
-        ids: specs.map((spec) => spec.id)
-      });
-      return specs;
-    } catch (error) {
-      this.debug("overlay:shape:error", {
-        shape,
-        radius,
-        error: error instanceof Error ? error.message : String(error)
-      });
-      return [];
-    }
-  }
   resolveRenderImageState(item) {
     var _a;
     const active = this.isToolActive;
@@ -3461,172 +3543,35 @@ var ImageTool = class {
     }
     return specs;
   }
-  buildOverlaySpecs(frame, sceneGeometry) {
+  buildOverlaySpecs(overlayState) {
     const visible = this.isImageEditingVisible();
-    if (!visible || frame.width <= 0 || frame.height <= 0 || !this.canvasService) {
+    if (!visible || !overlayState || !this.canvasService) {
       this.debug("overlay:hidden", {
         visible,
-        frame,
+        cutRect: overlayState == null ? void 0 : overlayState.layout.cutRect,
         isToolActive: this.isToolActive,
         isImageSelectionActive: this.isImageSelectionActive,
         focusedImageId: this.focusedImageId
       });
       return [];
     }
-    const viewport = this.canvasService.getSceneViewportRect();
-    const canvasW = viewport.width || 0;
-    const canvasH = viewport.height || 0;
-    const canvasLeft = viewport.left || 0;
-    const canvasTop = viewport.top || 0;
+    const viewport = this.canvasService.getScreenViewportRect();
     const visual = this.getFrameVisualConfig();
-    const strokeWidthScene = this.canvasService.toSceneLength(
-      visual.strokeWidth
-    );
-    const dashLengthScene = this.canvasService.toSceneLength(visual.dashLength);
-    const frameLeft = Math.max(
-      canvasLeft,
-      Math.min(canvasLeft + canvasW, frame.left)
-    );
-    const frameTop = Math.max(
-      canvasTop,
-      Math.min(canvasTop + canvasH, frame.top)
-    );
-    const frameRight = Math.max(
-      frameLeft,
-      Math.min(canvasLeft + canvasW, frame.left + frame.width)
-    );
-    const frameBottom = Math.max(
-      frameTop,
-      Math.min(canvasTop + canvasH, frame.top + frame.height)
-    );
-    const visibleFrameH = Math.max(0, frameBottom - frameTop);
-    const topH = Math.max(0, frameTop - canvasTop);
-    const bottomH = Math.max(0, canvasTop + canvasH - frameBottom);
-    const leftW = Math.max(0, frameLeft - canvasLeft);
-    const rightW = Math.max(0, canvasLeft + canvasW - frameRight);
-    const viewportRect = this.toLayoutSceneRect({
-      left: canvasLeft,
-      top: canvasTop,
-      width: canvasW,
-      height: canvasH
-    });
-    const visibleFrameBandRect = this.toLayoutSceneRect({
-      left: canvasLeft,
-      top: frameTop,
-      width: canvasW,
-      height: visibleFrameH
-    });
-    const frameRect = this.toLayoutSceneRect(frame);
-    const shapeOverlay = this.buildCropShapeOverlaySpecs(frame, sceneGeometry);
-    const mask = [
-      {
-        id: "image.cropMask.top",
-        type: "rect",
-        data: { id: "image.cropMask.top", zIndex: 1 },
-        layout: {
-          reference: "custom",
-          referenceRect: viewportRect,
-          alignX: "start",
-          alignY: "start",
-          width: "100%",
-          height: topH
-        },
-        props: {
-          originX: "left",
-          originY: "top",
-          fill: visual.outerBackground,
-          selectable: false,
-          evented: false
-        }
-      },
-      {
-        id: "image.cropMask.bottom",
-        type: "rect",
-        data: { id: "image.cropMask.bottom", zIndex: 2 },
-        layout: {
-          reference: "custom",
-          referenceRect: viewportRect,
-          alignX: "start",
-          alignY: "end",
-          width: "100%",
-          height: bottomH
-        },
-        props: {
-          originX: "left",
-          originY: "top",
-          fill: visual.outerBackground,
-          selectable: false,
-          evented: false
-        }
-      },
-      {
-        id: "image.cropMask.left",
-        type: "rect",
-        data: { id: "image.cropMask.left", zIndex: 3 },
-        layout: {
-          reference: "custom",
-          referenceRect: visibleFrameBandRect,
-          alignX: "start",
-          alignY: "start",
-          width: leftW,
-          height: "100%"
-        },
-        props: {
-          originX: "left",
-          originY: "top",
-          fill: visual.outerBackground,
-          selectable: false,
-          evented: false
-        }
-      },
-      {
-        id: "image.cropMask.right",
-        type: "rect",
-        data: { id: "image.cropMask.right", zIndex: 4 },
-        layout: {
-          reference: "custom",
-          referenceRect: visibleFrameBandRect,
-          alignX: "end",
-          alignY: "start",
-          width: rightW,
-          height: "100%"
-        },
-        props: {
-          originX: "left",
-          originY: "top",
-          fill: visual.outerBackground,
-          selectable: false,
-          evented: false
-        }
-      }
-    ];
-    const frameSpec = {
-      id: "image.cropFrame",
-      type: "rect",
-      data: { id: "image.cropFrame", zIndex: 7 },
-      layout: {
-        reference: "custom",
-        referenceRect: frameRect,
-        alignX: "start",
-        alignY: "start",
-        width: "100%",
-        height: "100%"
+    const specs = buildImageSessionOverlaySpecs({
+      viewport: {
+        left: viewport.left,
+        top: viewport.top,
+        width: viewport.width,
+        height: viewport.height
       },
-      props: {
-        originX: "left",
-        originY: "top",
-        fill: visual.innerBackground,
-        stroke: visual.strokeStyle === "hidden" ? "rgba(0,0,0,0)" : visual.strokeColor,
-        strokeWidth: visual.strokeStyle === "hidden" ? 0 : strokeWidthScene,
-        strokeDashArray: visual.strokeStyle === "dashed" ? [dashLengthScene, dashLengthScene] : void 0,
-        selectable: false,
-        evented: false
-      }
-    };
-    const specs = shapeOverlay.length > 0 ? [...mask, ...shapeOverlay] : [...mask, ...shapeOverlay, frameSpec];
+      layout: overlayState.layout,
+      geometry: overlayState.geometry,
+      visual,
+      hatchPattern: this.getCropShapeHatchPattern()
+    });
     this.debug("overlay:built", {
-      frame,
-      shape: sceneGeometry == null ? void 0 : sceneGeometry.shape,
+      cutRect: overlayState.layout.cutRect,
+      shape: overlayState.geometry.shape,
       overlayIds: specs.map((spec) => {
         var _a;
         return {
@@ -3655,10 +3600,9 @@ var ImageTool = class {
     }
     const imageSpecs = await this.buildImageSpecs(renderItems, frame);
     if (seq !== this.renderSeq) return;
-    const sceneGeometry = await this.resolveSceneGeometryForOverlay();
-    if (seq !== this.renderSeq) return;
+    const overlayState = this.resolveSessionOverlayState();
     this.imageSpecs = imageSpecs;
-    this.overlaySpecs = this.buildOverlaySpecs(frame, sceneGeometry);
+    this.overlaySpecs = this.buildOverlaySpecs(overlayState);
     await this.canvasService.flushRenderFromProducers();
     if (seq !== this.renderSeq) return;
     this.refreshImageObjectInteractionState();
@@ -3685,11 +3629,38 @@ var ImageTool = class {
       isImageSelectionActive: this.isImageSelectionActive,
       focusedImageId: this.focusedImageId
     });
+    this.emitImageStateChange();
     this.canvasService.requestRenderAll();
   }
   clampNormalized(value) {
     return Math.max(-1, Math.min(2, value));
   }
+  async setImageTransform(id, updates, options = {}) {
+    const next = {};
+    if (Number.isFinite(updates.scale)) {
+      next.scale = Math.max(0.05, Number(updates.scale));
+    }
+    if (Number.isFinite(updates.angle)) {
+      next.angle = Number(updates.angle);
+    }
+    if (Number.isFinite(updates.left)) {
+      next.left = this.clampNormalized(Number(updates.left));
+    }
+    if (Number.isFinite(updates.top)) {
+      next.top = this.clampNormalized(Number(updates.top));
+    }
+    if (Number.isFinite(updates.opacity)) {
+      next.opacity = Math.max(0, Math.min(1, Number(updates.opacity)));
+    }
+    if (!Object.keys(next).length) return;
+    await this.updateImage(id, next, options);
+  }
+  resetImageSession() {
+    this.workingItems = this.cloneItems(this.items);
+    this.hasWorkingChanges = false;
+    this.updateImages();
+    this.emitWorkingChange();
+  }
   updateImageInWorking(id, updates) {
     const index = this.workingItems.findIndex((item) => item.id === id);
     if (index < 0) return;
@@ -3707,7 +3678,6 @@ var ImageTool = class {
     this.emitWorkingChange(id);
   }
   async updateImageInConfig(id, updates) {
-    var _a, _b, _c, _d;
     const index = this.items.findIndex((item) => item.id === id);
     if (index < 0) return;
     const replacingSource = typeof updates.url === "string" && updates.url.length > 0;
@@ -3720,23 +3690,12 @@ var ImageTool = class {
       ...replacingSource ? {
         url: replacingUrl,
         sourceUrl: replacingUrl,
-        committedUrl: void 0,
-        scale: (_a = updates.scale) != null ? _a : 1,
-        angle: (_b = updates.angle) != null ? _b : 0,
-        left: (_c = updates.left) != null ? _c : 0.5,
-        top: (_d = updates.top) != null ? _d : 0.5
+        committedUrl: void 0
       } : {}
     });
     this.updateConfig(next);
     if (replacingSource) {
-      this.debug("replace:image:begin", { id, replacingUrl });
       this.purgeSourceSizeCacheForItem(base);
-      const loaded = await this.waitImageLoaded(id, true);
-      this.debug("replace:image:loaded", { id, loaded });
-      if (loaded) {
-        await this.refitImageToFrame(id);
-        this.setImageFocus(id);
-      }
     }
   }
   waitImageLoaded(id, forceWait = false) {
@@ -3754,70 +3713,43 @@ var ImageTool = class {
       });
     });
   }
-  async refitImageToFrame(id) {
+  async resolveImageSourceSize(id, src) {
     const obj = this.getImageObject(id);
-    if (!obj || !this.canvasService) return;
-    const current = this.items.find((item) => item.id === id);
-    if (!current) return;
-    const render = this.resolveRenderImageState(current);
-    this.rememberSourceSize(render.src, obj);
-    const source = this.getSourceSize(render.src, obj);
-    const frame = this.getFrameRect();
-    const coverScale = this.getCoverScale(frame, source);
-    const currentScale = this.toSceneObjectScale(obj.scaleX || 1);
-    const zoom = Math.max(0.05, currentScale / coverScale);
-    const updated = {
-      scale: Number.isFinite(zoom) ? zoom : 1,
-      angle: 0,
-      left: 0.5,
-      top: 0.5
-    };
-    const index = this.items.findIndex((item) => item.id === id);
-    if (index < 0) return;
-    const next = [...this.items];
-    next[index] = this.normalizeItem({ ...next[index], ...updated });
-    this.updateConfig(next);
-    this.workingItems = this.cloneItems(next);
-    this.hasWorkingChanges = false;
-    this.updateImages();
-    this.emitWorkingChange(id);
+    if (obj) {
+      this.rememberSourceSize(src, obj);
+    }
+    const ensured = await this.ensureSourceSize(src);
+    if (ensured) return ensured;
+    if (!obj) return null;
+    const width = Number((obj == null ? void 0 : obj.width) || 0);
+    const height = Number((obj == null ? void 0 : obj.height) || 0);
+    if (width <= 0 || height <= 0) return null;
+    return { width, height };
   }
-  async fitImageToArea(id, area) {
-    var _a, _b;
+  async applyImageOperation(id, operation, options = {}) {
     if (!this.canvasService) return;
-    const loaded = await this.waitImageLoaded(id, false);
-    if (!loaded) return;
-    const obj = this.getImageObject(id);
-    if (!obj) return;
-    const renderItems = this.isToolActive ? this.workingItems : this.items;
+    this.syncToolActiveFromWorkbench();
+    const target = options.target || "auto";
+    const renderItems = target === "working" || target === "auto" && this.isToolActive ? this.workingItems : this.items;
     const current = renderItems.find((item) => item.id === id);
     if (!current) return;
     const render = this.resolveRenderImageState(current);
-    this.rememberSourceSize(render.src, obj);
-    const source = this.getSourceSize(render.src, obj);
+    const source = await this.resolveImageSourceSize(id, render.src);
+    if (!source) return;
     const frame = this.getFrameRect();
-    const baseCover = this.getCoverScale(frame, source);
-    const desiredScale = Math.max(
-      Math.max(1, area.width) / Math.max(1, source.width),
-      Math.max(1, area.height) / Math.max(1, source.height)
-    );
     const viewport = this.canvasService.getSceneViewportRect();
-    const canvasW = viewport.width || 1;
-    const canvasH = viewport.height || 1;
-    const areaLeftInput = (_a = area.left) != null ? _a : 0.5;
-    const areaTopInput = (_b = area.top) != null ? _b : 0.5;
-    const areaLeftPx = areaLeftInput <= 1.5 ? viewport.left + areaLeftInput * canvasW : areaLeftInput;
-    const areaTopPx = areaTopInput <= 1.5 ? viewport.top + areaTopInput * canvasH : areaTopInput;
-    const updates = {
-      scale: Math.max(0.05, desiredScale / baseCover),
-      left: this.clampNormalized(
-        (areaLeftPx - frame.left) / Math.max(1, frame.width)
-      ),
-      top: this.clampNormalized(
-        (areaTopPx - frame.top) / Math.max(1, frame.height)
-      )
-    };
-    if (this.isToolActive) {
+    const area = operation.type === "resetTransform" ? resolveImageOperationArea({ frame, viewport }) : resolveImageOperationArea({
+      frame,
+      viewport,
+      area: operation.area
+    });
+    const updates = computeImageOperationUpdates({
+      frame,
+      source,
+      operation,
+      area
+    });
+    if (target === "working" || target === "auto" && this.isToolActive) {
       this.updateImageInWorking(id, updates);
       return;
     }
@@ -3948,6 +3880,11 @@ var ImageTool = class {
   }
 };
 
+// src/extensions/image/model.ts
+function hasAnyImageInViewState(state) {
+  return Boolean(state == null ? void 0 : state.hasAnyImage);
+}
+
 // src/extensions/size/SizeTool.ts
 import {
   ContributionPointIds as ContributionPointIds3
@@ -4912,6 +4849,13 @@ function buildDielineRenderBundle(options) {
     canvasWidth,
     canvasHeight
   };
+  const cutFrameRect = {
+    left: cx - cutW / 2,
+    top: cy - cutH / 2,
+    width: cutW,
+    height: cutH,
+    space: "screen"
+  };
   const specs = [];
   if (insideColor && insideColor !== "transparent" && insideColor !== "rgba(0,0,0,0)" && !hasImages) {
     specs.push({
@@ -5033,9 +4977,13 @@ function buildDielineRenderBundle(options) {
     width: cutW,
     height: cutH,
     radius: cutR,
-    x: cx,
-    y: cy,
-    features: cutFeatures
+    // Build the clip path in the cut frame's local coordinates so Fabric
+    // does not have to infer placement from the standalone path bounds.
+    x: cutW / 2,
+    y: cutH / 2,
+    features: cutFeatures,
+    canvasWidth: cutW,
+    canvasHeight: cutH
   });
   if (!clipPathData) {
     return { specs, effects: [] };
@@ -5052,6 +5000,12 @@ function buildDielineRenderBundle(options) {
           id: ids.clipSource,
           type: "path",
           space: "screen",
+          layout: {
+            reference: "custom",
+            referenceRect: cutFrameRect,
+            alignX: "start",
+            alignY: "start"
+          },
           data: {
             id: ids.clipSource,
             type: "dieline-effect",
@@ -9876,6 +9830,7 @@ export {
   ViewportSystem,
   WhiteInkTool,
   getCoverScale as computeImageCoverScale,
+  computeImageOperationUpdates,
   getCoverScale as computeWhiteInkCoverScale,
   createDefaultDielineState,
   createDielineCommands,
@@ -9885,5 +9840,7 @@ export {
   createWhiteInkCommands,
   createWhiteInkConfigurations,
   evaluateVisibilityExpr,
-  readDielineState
+  hasAnyImageInViewState,
+  readDielineState,
+  resolveImageOperationArea
 };