@pooder/kit 6.2.2 → 6.3.1

package/dist/index.mjs

@@ -1271,30 +1271,43 @@ function createImageCommands(tool) {
       }
     },
     {
-      command: "getWorkingImages",
-      id: "getWorkingImages",
-      title: "Get Working Images",
+      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.cloneItems(tool.workingItems);
+        return tool.getImageViewState();
       }
     },
     {
-      command: "setWorkingImage",
-      id: "setWorkingImage",
-      title: "Set Working Image",
-      handler: (id, updates) => {
-        tool.updateImageInWorking(id, updates);
+      command: "setImageTransform",
+      id: "setImageTransform",
+      title: "Set Image Transform",
+      handler: async (id, updates, options = {}) => {
+        await tool.setImageTransform(id, updates, options);
       }
     },
     {
-      command: "resetWorkingImages",
-      id: "resetWorkingImages",
-      title: "Reset Working Images",
+      command: "imageSessionReset",
+      id: "imageSessionReset",
+      title: "Reset Image Session",
       handler: () => {
-        tool.workingItems = tool.cloneItems(tool.items);
-        tool.hasWorkingChanges = false;
-        tool.updateImages();
-        tool.emitWorkingChange();
+        tool.resetImageSession();
+      }
+    },
+    {
+      command: "validateImageSession",
+      id: "validateImageSession",
+      title: "Validate Image Session",
+      handler: async () => {
+        return await tool.validateImageSession();
       }
     },
     {
@@ -1302,7 +1315,7 @@ function createImageCommands(tool) {
       id: "completeImages",
       title: "Complete Images",
       handler: async () => {
-        return await tool.commitWorkingImagesAsCropped();
+        return await tool.completeImageSession();
       }
     },
     {
@@ -1313,22 +1326,6 @@ function createImageCommands(tool) {
         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",
@@ -1342,9 +1339,10 @@ function createImageCommands(tool) {
       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) {
+        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, {
@@ -1352,6 +1350,13 @@ function createImageCommands(tool) {
               skipRender: true
             });
           }
+          if (tool.isToolActive) {
+            tool.workingItems = tool.cloneItems(next);
+            tool.hasWorkingChanges = true;
+            tool.updateImages();
+            tool.emitWorkingChange(id);
+            return;
+          }
           tool.updateConfig(next);
         }
       }
@@ -1374,6 +1379,13 @@ function createImageCommands(tool) {
           syncCanvasSelection: true,
           skipRender: true
         });
+        if (tool.isToolActive) {
+          tool.workingItems = [];
+          tool.hasWorkingChanges = true;
+          tool.updateImages();
+          tool.emitWorkingChange();
+          return;
+        }
         tool.updateConfig([]);
       }
     },
@@ -1382,11 +1394,19 @@ function createImageCommands(tool) {
       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 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);
         }
       }
@@ -1396,11 +1416,19 @@ function createImageCommands(tool) {
       id: "sendToBack",
       title: "Send Image to Back",
       handler: (id) => {
-        const index = tool.items.findIndex((item) => item.id === id);
+        const sourceItems = tool.isToolActive ? tool.workingItems : tool.items;
+        const index = sourceItems.findIndex((item) => item.id === id);
         if (index > 0) {
-          const next = [...tool.items];
+          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);
         }
       }
@@ -1532,10 +1560,127 @@ function createImageConfigurations() {
       type: "color",
       label: "Image Frame Outer Background",
       default: "#f5f5f5"
+    },
+    {
+      id: "image.session.placementPolicy",
+      type: "select",
+      label: "Image Session Placement Policy",
+      options: ["free", "warn", "strict"],
+      default: "free"
     }
   ];
 }
 
+// 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/image/imagePlacement.ts
+function toRadians(angle) {
+  return angle * Math.PI / 180;
+}
+function validateImagePlacement(args) {
+  const { frame, source, placement } = args;
+  if (frame.width <= 0 || frame.height <= 0 || source.width <= 0 || source.height <= 0) {
+    return { ok: true };
+  }
+  const coverScale = getCoverScale(frame, source);
+  const imageWidth = source.width * coverScale * Math.max(0.05, Number(placement.scale || 1));
+  const imageHeight = source.height * coverScale * Math.max(0.05, Number(placement.scale || 1));
+  if (imageWidth <= 0 || imageHeight <= 0) {
+    return { ok: true };
+  }
+  const centerX = frame.left + placement.left * frame.width;
+  const centerY = frame.top + placement.top * frame.height;
+  const halfWidth = imageWidth / 2;
+  const halfHeight = imageHeight / 2;
+  const radians = toRadians(placement.angle || 0);
+  const cos = Math.cos(radians);
+  const sin = Math.sin(radians);
+  const frameCorners = [
+    { x: frame.left, y: frame.top },
+    { x: frame.left + frame.width, y: frame.top },
+    { x: frame.left + frame.width, y: frame.top + frame.height },
+    { x: frame.left, y: frame.top + frame.height }
+  ];
+  const coversFrame = frameCorners.every((corner) => {
+    const dx = corner.x - centerX;
+    const dy = corner.y - centerY;
+    const localX = dx * cos + dy * sin;
+    const localY = -dx * sin + dy * cos;
+    return Math.abs(localX) <= halfWidth + 1e-6 && Math.abs(localY) <= halfHeight + 1e-6;
+  });
+  return { ok: coversFrame };
+}
+
 // src/extensions/geometry.ts
 import paper from "paper";
 
@@ -2338,6 +2483,7 @@ var ImageTool = class {
     this.activeSnapX = null;
     this.activeSnapY = null;
     this.movingImageId = null;
+    this.sessionNotice = null;
     this.hasRenderedSnapGuides = false;
     this.subscriptions = new SubscriptionBag();
     this.imageControlsByCapabilityKey = /* @__PURE__ */ new Map();
@@ -2537,7 +2683,10 @@ var ImageTool = class {
             this.updateImages();
             return;
           }
-          if (e.key.startsWith("size.") || e.key.startsWith("image.frame.") || e.key.startsWith("image.control.")) {
+          if (e.key.startsWith("size.") || e.key.startsWith("image.frame.") || e.key.startsWith("image.session.") || e.key.startsWith("image.control.")) {
+            if (e.key === "image.session.placementPolicy") {
+              this.clearSessionNotice();
+            }
             if (e.key.startsWith("image.control.")) {
               this.imageControlsByCapabilityKey.clear();
             }
@@ -2570,6 +2719,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;
@@ -2979,9 +3129,10 @@ var ImageTool = class {
           name: "Image",
           interaction: "session",
           commands: {
-            begin: "resetWorkingImages",
+            begin: "imageSessionReset",
+            validate: "validateImageSession",
             commit: "completeImages",
-            rollback: "resetWorkingImages"
+            rollback: "imageSessionReset"
           },
           session: {
             autoBegin: true,
@@ -3015,6 +3166,56 @@ var ImageTool = class {
   cloneItems(items) {
     return this.normalizeItems((items || []).map((i) => ({ ...i })));
   }
+  getViewItems() {
+    return this.isToolActive ? this.workingItems : this.items;
+  }
+  getPlacementPolicy() {
+    const policy = this.getConfig(
+      "image.session.placementPolicy",
+      "free"
+    );
+    return policy === "warn" || policy === "strict" ? policy : "free";
+  }
+  areSessionNoticesEqual(a, b) {
+    if (!a && !b) return true;
+    if (!a || !b) return false;
+    return a.code === b.code && a.level === b.level && a.message === b.message && a.policy === b.policy && JSON.stringify(a.imageIds) === JSON.stringify(b.imageIds);
+  }
+  setSessionNotice(notice, options = {}) {
+    var _a;
+    if (this.areSessionNoticesEqual(this.sessionNotice, notice)) {
+      return;
+    }
+    this.sessionNotice = notice;
+    if (options.emit !== false) {
+      (_a = this.context) == null ? void 0 : _a.eventBus.emit("image:session:notice", this.sessionNotice);
+      this.emitImageStateChange();
+    }
+  }
+  clearSessionNotice(options = {}) {
+    this.setSessionNotice(null, options);
+  }
+  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",
+      placementPolicy: this.getPlacementPolicy(),
+      sessionNotice: this.sessionNotice
+    };
+  }
+  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", {
@@ -3050,10 +3251,14 @@ 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();
+    this.clearSessionNotice({ emit: false });
     const id = this.generateId();
     const newItem = this.normalizeItem({
       id,
@@ -3061,13 +3266,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);
@@ -3075,8 +3287,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");
@@ -3085,19 +3297,35 @@ 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";
@@ -3133,6 +3361,7 @@ var ImageTool = class {
   }
   updateConfig(newItems, skipCanvasUpdate = false) {
     if (!this.context) return;
+    this.clearSessionNotice({ emit: false });
     this.applyCommittedItems(newItems);
     runDeferredConfigUpdate(
       this,
@@ -3162,34 +3391,6 @@ var ImageTool = class {
     }
     return this.canvasService.toScreenRect(frame || this.getFrameRect());
   }
-  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;
-    }
-    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
-    });
-  }
   getImageObjects() {
     if (!this.canvasService) return [];
     return this.canvasService.canvas.getObjects().filter((obj) => {
@@ -3263,6 +3464,71 @@ var ImageTool = class {
   getCoverScale(frame, size) {
     return getCoverScale(frame, size);
   }
+  resolvePlacementState(item) {
+    var _a;
+    return {
+      left: Number.isFinite(item.left) ? item.left : 0.5,
+      top: Number.isFinite(item.top) ? item.top : 0.5,
+      scale: Math.max(0.05, (_a = item.scale) != null ? _a : 1),
+      angle: Number.isFinite(item.angle) ? item.angle : 0
+    };
+  }
+  async validatePlacementForItem(item) {
+    const frame = this.getFrameRect();
+    if (!frame.width || !frame.height) {
+      return true;
+    }
+    const src = item.sourceUrl || item.url;
+    if (!src) {
+      return true;
+    }
+    const source = await this.resolveImageSourceSize(item.id, src);
+    if (!source) {
+      return true;
+    }
+    return validateImagePlacement({
+      frame,
+      source,
+      placement: this.resolvePlacementState(item)
+    }).ok;
+  }
+  async validateImageSession() {
+    const policy = this.getPlacementPolicy();
+    if (policy === "free") {
+      this.clearSessionNotice();
+      return { ok: true, policy };
+    }
+    const invalidImageIds = [];
+    for (const item of this.workingItems) {
+      const valid = await this.validatePlacementForItem(item);
+      if (!valid) {
+        invalidImageIds.push(item.id);
+      }
+    }
+    if (!invalidImageIds.length) {
+      this.clearSessionNotice();
+      return { ok: true, policy };
+    }
+    const notice = {
+      code: "image-outside-frame",
+      level: policy === "strict" ? "error" : "warning",
+      message: policy === "strict" ? "\u56FE\u7247\u4F4D\u7F6E\u4E0D\u80FD\u8D85\u51FA frame\uFF0C\u8BF7\u8C03\u6574\u540E\u518D\u63D0\u4EA4\u3002" : "\u56FE\u7247\u4F4D\u7F6E\u5DF2\u8D85\u51FA frame\uFF0C\u5EFA\u8BAE\u8C03\u6574\u540E\u518D\u63D0\u4EA4\u3002",
+      imageIds: invalidImageIds,
+      policy
+    };
+    this.setSessionNotice(notice);
+    this.setImageFocus(invalidImageIds[0], {
+      syncCanvasSelection: true,
+      skipRender: true
+    });
+    return {
+      ok: policy !== "strict",
+      reason: notice.code,
+      message: notice.message,
+      imageIds: notice.imageIds,
+      policy: notice.policy
+    };
+  }
   getFrameVisualConfig() {
     var _a, _b;
     const strokeStyleRaw = this.getConfig(
@@ -3520,14 +3786,43 @@ 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.clearSessionNotice({ emit: false });
+    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;
+    this.clearSessionNotice({ emit: false });
     const next = [...this.workingItems];
     next[index] = this.normalizeItem({ ...next[index], ...updates });
     this.workingItems = next;
@@ -3542,9 +3837,9 @@ 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;
+    this.clearSessionNotice({ emit: false });
     const replacingSource = typeof updates.url === "string" && updates.url.length > 0;
     const next = [...this.items];
     const base = next[index];
@@ -3555,23 +3850,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) {
@@ -3589,70 +3873,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;
     }
@@ -3691,11 +3948,42 @@ var ImageTool = class {
       }
     }
     this.hasWorkingChanges = false;
+    this.clearSessionNotice({ emit: false });
     this.workingItems = this.cloneItems(next);
     this.updateConfig(next);
     this.emitWorkingChange(this.focusedImageId);
     return { ok: true };
   }
+  async completeImageSession() {
+    var _a, _b, _c;
+    const sessionState = (_a = this.context) == null ? void 0 : _a.services.get("ToolSessionService");
+    const workbench = (_b = this.context) == null ? void 0 : _b.services.get("WorkbenchService");
+    console.info("[ImageTool] completeImageSession:start", {
+      activeToolId: (_c = workbench == null ? void 0 : workbench.activeToolId) != null ? _c : null,
+      isToolActive: this.isToolActive,
+      dirtyBeforeComplete: this.hasWorkingChanges,
+      workingCount: this.workingItems.length,
+      committedCount: this.items.length,
+      sessionDirty: sessionState == null ? void 0 : sessionState.isDirty(this.id)
+    });
+    const validation = await this.validateImageSession();
+    if (!validation.ok) {
+      console.warn("[ImageTool] completeImageSession:validation-failed", {
+        validation,
+        dirtyAfterValidation: this.hasWorkingChanges
+      });
+      return validation;
+    }
+    const result = await this.commitWorkingImagesAsCropped();
+    console.info("[ImageTool] completeImageSession:done", {
+      result,
+      dirtyAfterComplete: this.hasWorkingChanges,
+      workingCount: this.workingItems.length,
+      committedCount: this.items.length,
+      sessionDirty: sessionState == null ? void 0 : sessionState.isDirty(this.id)
+    });
+    return result;
+  }
   async exportCroppedImageByIds(imageIds, options) {
     var _a, _b, _c;
     if (!this.canvasService) {
@@ -3783,6 +4071,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
@@ -9728,6 +10021,7 @@ export {
   ViewportSystem,
   WhiteInkTool,
   getCoverScale as computeImageCoverScale,
+  computeImageOperationUpdates,
   getCoverScale as computeWhiteInkCoverScale,
   createDefaultDielineState,
   createDielineCommands,
@@ -9737,5 +10031,7 @@ export {
   createWhiteInkCommands,
   createWhiteInkConfigurations,
   evaluateVisibilityExpr,
-  readDielineState
+  hasAnyImageInViewState,
+  readDielineState,
+  resolveImageOperationArea
 };