@pooder/kit 6.2.1 → 6.3.0

package/src/extensions/image/ImageTool.ts

@@ -14,24 +14,15 @@ import {
   Point,
   controlsUtils,
 } from "fabric";
-import {
-  CanvasService,
-  RenderLayoutRect,
-  RenderObjectSpec,
-} from "../../services";
-import { isDielineShape, normalizeShapeStyle } from "../dielineShape";
-import type { DielineShape, DielineShapeStyle } from "../dielineShape";
-import { generateDielinePath, getPathBounds } from "../geometry";
+import { CanvasService, RenderObjectSpec } from "../../services";
 import {
   buildSceneGeometry,
   computeSceneLayout,
   readSizeState,
+  type SceneGeometrySnapshot,
+  type SceneLayoutSnapshot,
 } from "../../shared/scene/sceneLayoutModel";
-import {
-  type FrameRect,
-  resolveCutFrameRect,
-  toLayoutSceneRect as toSceneLayoutRect,
-} from "../../shared/scene/frame";
+import { type FrameRect, resolveCutFrameRect } from "../../shared/scene/frame";
 import {
   createSourceSizeCache,
   getCoverScale as getCoverScaleFromRect,
@@ -48,6 +39,12 @@ import {
 } from "../../shared/constants/layers";
 import { createImageCommands } from "./commands";
 import { createImageConfigurations } from "./config";
+import {
+  computeImageOperationUpdates,
+  resolveImageOperationArea,
+  type ImageOperation,
+} from "./imageOperations";
+import { buildImageSessionOverlaySpecs } from "./sessionOverlay";
 
 export interface ImageItem {
   id: string;
@@ -61,6 +58,25 @@ export interface ImageItem {
   committedUrl?: string;
 }
 
+export interface ImageTransformUpdates {
+  scale?: number;
+  angle?: number;
+  left?: number;
+  top?: number;
+  opacity?: number;
+}
+
+export interface ImageViewState {
+  items: ImageItem[];
+  hasAnyImage: boolean;
+  focusedId: string | null;
+  focusedItem: ImageItem | null;
+  isToolActive: boolean;
+  isImageSelectionActive: boolean;
+  hasWorkingChanges: boolean;
+  source: "working" | "committed";
+}
+
 interface RenderImageState {
   src: string;
   left: number;
@@ -91,27 +107,16 @@ interface ImageControlVisualConfig {
   padding: number;
 }
 
-type ShapeOverlayShape = Exclude<DielineShape, "custom">;
-
-interface SceneGeometryLike {
-  shape: DielineShape;
-  shapeStyle: DielineShapeStyle;
-  radius: number;
-  offset: number;
+interface ImageSessionOverlayState {
+  layout: SceneLayoutSnapshot;
+  geometry: SceneGeometrySnapshot;
 }
 
 interface UpsertImageOptions {
   id?: string;
   mode?: "replace" | "add";
   addOptions?: Partial<ImageItem>;
-  fitOnAdd?: boolean;
-}
-
-interface DielineFitArea {
-  width: number;
-  height: number;
-  left: number;
-  top: number;
+  operation?: ImageOperation;
 }
 
 interface UpdateImageOptions {
@@ -382,6 +387,7 @@ export class ImageTool implements Extension {
     this.clearRenderedImages();
     this.renderProducerDisposable?.dispose();
     this.renderProducerDisposable = undefined;
+    this.emitImageStateChange();
     if (this.canvasService) {
       void this.canvasService.flushRenderFromProducers();
       this.canvasService = undefined;
@@ -663,10 +669,21 @@ export class ImageTool implements Extension {
     }
   }
 
+  private clearSnapGuideContext() {
+    const topContext = this.canvasService?.canvas.contextTop;
+    if (!this.canvasService || !topContext) return;
+    this.canvasService.canvas.clearContext(topContext);
+  }
+
   private clearSnapPreview() {
+    const shouldClearCanvas =
+      this.hasRenderedSnapGuides || !!this.activeSnapX || !!this.activeSnapY;
     this.activeSnapX = null;
     this.activeSnapY = null;
     this.hasRenderedSnapGuides = false;
+    if (shouldClearCanvas) {
+      this.clearSnapGuideContext();
+    }
     this.canvasService?.requestRenderAll();
   }
 
@@ -933,9 +950,9 @@ export class ImageTool implements Extension {
           name: "Image",
           interaction: "session",
           commands: {
-            begin: "resetWorkingImages",
+            begin: "imageSessionReset",
             commit: "completeImages",
-            rollback: "resetWorkingImages",
+            rollback: "imageSessionReset",
           },
           session: {
             autoBegin: true,
@@ -980,6 +997,34 @@ export class ImageTool implements Extension {
     return this.normalizeItems((items || []).map((i) => ({ ...i })));
   }
 
+  private getViewItems(): ImageItem[] {
+    return this.isToolActive ? this.workingItems : this.items;
+  }
+
+  private getImageViewState(): ImageViewState {
+    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",
+    };
+  }
+
+  private emitImageStateChange() {
+    this.context?.eventBus.emit("image:state:change", this.getImageViewState());
+  }
+
   private emitWorkingChange(changedId: string | null = null) {
     this.context?.eventBus.emit("image:working:change", {
       changedId,
@@ -1027,6 +1072,8 @@ export class ImageTool implements Extension {
 
     if (!options.skipRender) {
       this.updateImages();
+    } else {
+      this.emitImageStateChange();
     }
 
     return { ok: true, id };
@@ -1035,8 +1082,9 @@ export class ImageTool implements Extension {
   private async addImageEntry(
     url: string,
     options?: Partial<ImageItem>,
-    fitOnAdd = true,
+    operation?: ImageOperation,
   ): Promise<string> {
+    this.syncToolActiveFromWorkbench();
     const id = this.generateId();
     const newItem = this.normalizeItem({
       id,
@@ -1045,13 +1093,20 @@ export class ImageTool implements Extension {
       ...options,
     } as ImageItem);
 
-    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);
@@ -1063,8 +1118,8 @@ export class ImageTool implements Extension {
     url: string,
     options: UpsertImageOptions = {},
   ): Promise<{ id: string; mode: "replace" | "add" }> {
+    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");
@@ -1073,25 +1128,35 @@ export class ImageTool implements Extension {
       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: undefined,
+        });
+      } 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" };
   }
 
-  private addItemToWorkingSessionIfNeeded(
-    item: ImageItem,
-    sessionDirtyBeforeAdd: boolean,
-  ) {
-    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);
-  }
-
   private async updateImage(
     id: string,
     updates: Partial<ImageItem>,
@@ -1166,42 +1231,6 @@ export class ImageTool implements Extension {
     return this.canvasService.toScreenRect(frame || this.getFrameRect());
   }
 
-  private toLayoutSceneRect(rect: FrameRect): RenderLayoutRect {
-    return toSceneLayoutRect(rect);
-  }
-
-  private async resolveDefaultFitArea(): Promise<DielineFitArea | null> {
-    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,
-    };
-  }
-
-  private async fitImageToDefaultArea(id: string) {
-    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,
-    });
-  }
-
   private getImageObjects(): any[] {
     if (!this.canvasService) return [];
     return this.canvasService.canvas.getObjects().filter((obj: any) => {
@@ -1319,94 +1348,42 @@ export class ImageTool implements Extension {
     };
   }
 
-  private toSceneGeometryLike(raw: any): SceneGeometryLike | null {
-    const shape = raw?.shape;
-    if (!isDielineShape(shape)) {
+  private resolveSessionOverlayState(): ImageSessionOverlayState | null {
+    if (!this.canvasService || !this.context) {
       return null;
     }
-
-    const radiusRaw = Number(raw?.radius);
-    const offsetRaw = Number(raw?.offset);
-    const unit = typeof 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?.shapeStyle),
-      radius: Number.isFinite(radius) ? radius : 0,
-      offset: Number.isFinite(offset) ? offset : 0,
-    };
-  }
-
-  private async resolveSceneGeometryForOverlay(): Promise<SceneGeometryLike | null> {
-    if (!this.context) return null;
-    const commandService = this.context.services.get<any>("CommandService");
-    if (commandService) {
-      try {
-        const raw = await Promise.resolve(
-          commandService.executeCommand("getSceneGeometry"),
-        );
-        const geometry = this.toSceneGeometryLike(raw);
-        if (geometry) {
-          this.debug("overlay:sceneGeometry:command", geometry);
-          return geometry;
-        }
-        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>(
       "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;
-  }
 
-  private resolveCutShapeRadius(
-    geometry: SceneGeometryLike,
-    frame: FrameRect,
-  ): number {
-    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 };
   }
 
   private getCropShapeHatchPattern(
     color = "rgba(255, 0, 0, 0.6)",
   ): Pattern | undefined {
     if (typeof document === "undefined") return undefined;
-    const sceneScale = this.canvasService?.getSceneScale() || 1;
-    const cacheKey = `${color}::${sceneScale.toFixed(6)}`;
+    const cacheKey = color;
     if (
       this.cropShapeHatchPattern &&
       this.cropShapeHatchPatternColor === color &&
@@ -1443,152 +1420,12 @@ export class ImageTool implements Extension {
       // @ts-ignore: Fabric Pattern accepts canvas source here.
       repetition: "repeat",
     });
-    // Scene specs are scaled to screen by CanvasService; keep hatch density in screen pixels.
-    (pattern as any).patternTransform = [
-      1 / sceneScale,
-      0,
-      0,
-      1 / sceneScale,
-      0,
-      0,
-    ];
     this.cropShapeHatchPattern = pattern;
     this.cropShapeHatchPatternColor = color;
     this.cropShapeHatchPatternKey = cacheKey;
     return pattern;
   }
 
-  private buildCropShapeOverlaySpecs(
-    frame: FrameRect,
-    sceneGeometry: SceneGeometryLike | null,
-  ): RenderObjectSpec[] {
-    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 as ShapeOverlayShape;
-    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) <= 0.0001 &&
-      Math.abs(shapeHeight - frame.height) <= 0.0001;
-    if (shape === "rect" && radius <= 0.0001 && 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: RenderObjectSpec[] = [
-        {
-          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: this.canvasService?.toSceneLength(1) ?? 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 [];
-    }
-  }
-
   private resolveRenderImageState(item: ImageItem): RenderImageState {
     const active = this.isToolActive;
     const sourceUrl = item.sourceUrl || item.url;
@@ -1689,19 +1526,13 @@ export class ImageTool implements Extension {
   }
 
   private buildOverlaySpecs(
-    frame: FrameRect,
-    sceneGeometry: SceneGeometryLike | null,
+    overlayState: ImageSessionOverlayState | null,
   ): RenderObjectSpec[] {
     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?.layout.cutRect,
         isToolActive: this.isToolActive,
         isImageSelectionActive: this.isImageSelectionActive,
         focusedImageId: this.focusedImageId,
@@ -1709,174 +1540,23 @@ export class ImageTool implements Extension {
       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: RenderObjectSpec[] = [
-      {
-        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 specs = buildImageSessionOverlaySpecs({
+      viewport: {
+        left: viewport.left,
+        top: viewport.top,
+        width: viewport.width,
+        height: viewport.height,
       },
-    ];
-
-    const frameSpec: RenderObjectSpec = {
-      id: "image.cropFrame",
-      type: "rect",
-      data: { id: "image.cropFrame", zIndex: 7 },
-      layout: {
-        reference: "custom",
-        referenceRect: frameRect,
-        alignX: "start",
-        alignY: "start",
-        width: "100%",
-        height: "100%",
-      },
-      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]
-            : undefined,
-        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?.shape,
+      cutRect: overlayState.layout.cutRect,
+      shape: overlayState.geometry.shape,
       overlayIds: specs.map((spec) => ({
         id: spec.id,
         zIndex: spec.data?.zIndex,
@@ -1907,11 +1587,10 @@ export class ImageTool implements Extension {
     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();
@@ -1942,6 +1621,7 @@ export class ImageTool implements Extension {
       isImageSelectionActive: this.isImageSelectionActive,
       focusedImageId: this.focusedImageId,
     });
+    this.emitImageStateChange();
     this.canvasService.requestRenderAll();
   }
 
@@ -1949,6 +1629,40 @@ export class ImageTool implements Extension {
     return Math.max(-1, Math.min(2, value));
   }
 
+  private async setImageTransform(
+    id: string,
+    updates: ImageTransformUpdates,
+    options: UpdateImageOptions = {},
+  ) {
+    const next: Partial<ImageItem> = {};
+
+    if (Number.isFinite(updates.scale as number)) {
+      next.scale = Math.max(0.05, Number(updates.scale));
+    }
+    if (Number.isFinite(updates.angle as number)) {
+      next.angle = Number(updates.angle);
+    }
+    if (Number.isFinite(updates.left as number)) {
+      next.left = this.clampNormalized(Number(updates.left));
+    }
+    if (Number.isFinite(updates.top as number)) {
+      next.top = this.clampNormalized(Number(updates.top));
+    }
+    if (Number.isFinite(updates.opacity as number)) {
+      next.opacity = Math.max(0, Math.min(1, Number(updates.opacity)));
+    }
+
+    if (!Object.keys(next).length) return;
+    await this.updateImage(id, next, options);
+  }
+
+  private resetImageSession() {
+    this.workingItems = this.cloneItems(this.items);
+    this.hasWorkingChanges = false;
+    this.updateImages();
+    this.emitWorkingChange();
+  }
+
   private onObjectModified = (e: any) => {
     if (!this.isToolActive) return;
     const target = e?.target;
@@ -2024,10 +1738,6 @@ export class ImageTool implements Extension {
             url: replacingUrl,
             sourceUrl: replacingUrl,
             committedUrl: undefined,
-            scale: updates.scale ?? 1,
-            angle: updates.angle ?? 0,
-            left: updates.left ?? 0.5,
-            top: updates.top ?? 0.5,
           }
         : {}),
     });
@@ -2035,14 +1745,7 @@ export class ImageTool implements Extension {
     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);
-      }
     }
   }
 
@@ -2064,93 +1767,62 @@ export class ImageTool implements Extension {
     });
   }
 
-  private async refitImageToFrame(id: string) {
+  private async resolveImageSourceSize(
+    id: string,
+    src: string,
+  ): Promise<SourceSize | null> {
     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: Partial<ImageItem> = {
-      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;
+    if (obj) {
+      this.rememberSourceSize(src, obj);
+    }
+    const ensured = await this.ensureSourceSize(src);
+    if (ensured) return ensured;
+    if (!obj) return null;
 
-    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);
+    const width = Number(obj?.width || 0);
+    const height = Number(obj?.height || 0);
+    if (width <= 0 || height <= 0) return null;
+    return { width, height };
   }
 
-  private async fitImageToArea(
+  private async applyImageOperation(
     id: string,
-    area: { width: number; height: number; left?: number; top?: number },
+    operation: ImageOperation,
+    options: UpdateImageOptions = {},
   ) {
     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);
+    const source = await this.resolveImageSourceSize(id, render.src);
+    if (!source) return;
 
-    this.rememberSourceSize(render.src, obj);
-    const source = this.getSourceSize(render.src, obj);
     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 = area.left ?? 0.5;
-    const areaTopInput = area.top ?? 0.5;
-
-    const areaLeftPx =
-      areaLeftInput <= 1.5
-        ? viewport.left + areaLeftInput * canvasW
-        : areaLeftInput;
-    const areaTopPx =
-      areaTopInput <= 1.5
-        ? viewport.top + areaTopInput * canvasH
-        : areaTopInput;
-
-    const updates: Partial<ImageItem> = {
-      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),
-      ),
-    };
+    const area =
+      operation.type === "resetTransform"
+        ? resolveImageOperationArea({ frame, viewport })
+        : resolveImageOperationArea({
+            frame,
+            viewport,
+            area: operation.area,
+          });
+    const updates = computeImageOperationUpdates({
+      frame,
+      source,
+      operation,
+      area,
+    });
 
-    if (this.isToolActive) {
+    if (target === "working" || (target === "auto" && this.isToolActive)) {
       this.updateImageInWorking(id, updates);
       return;
     }