@pooder/kit 6.1.1 → 6.1.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @pooder/kit
 
+## 6.1.2
+
+### Patch Changes
+
+- snapping
+
 ## 6.1.1
 
 ### Patch Changes

package/dist/index.d.mts

@@ -92,6 +92,11 @@ declare class ImageTool implements Extension {
     private cropShapeHatchPatternKey?;
     private imageSpecs;
     private overlaySpecs;
+    private activeSnapX;
+    private activeSnapY;
+    private snapGuideXObject?;
+    private snapGuideYObject?;
+    private canvasObjectMovingHandler?;
     private renderProducerDisposable?;
     private readonly subscriptions;
     private imageControlsByCapabilityKey;
@@ -102,6 +107,21 @@ declare class ImageTool implements Extension {
     private onSelectionCleared;
     private onSceneLayoutChanged;
     private onSceneGeometryChanged;
+    private bindCanvasInteractionHandlers;
+    private unbindCanvasInteractionHandlers;
+    private getActiveImageTarget;
+    private getTargetBoundsScene;
+    private getSnapThresholdScene;
+    private pickSnapMatch;
+    private computeMoveSnapMatches;
+    private areSnapMatchesEqual;
+    private updateSnapMatchState;
+    private clearSnapGuides;
+    private removeSnapGuideObject;
+    private createOrUpdateSnapGuideObject;
+    private updateSnapGuideVisuals;
+    private handleCanvasObjectMoving;
+    private applySnapMatchesToTarget;
     private syncToolActiveFromWorkbench;
     private isImageEditingVisible;
     private getEnabledImageControlCapabilities;

package/dist/index.d.ts

@@ -92,6 +92,11 @@ declare class ImageTool implements Extension {
     private cropShapeHatchPatternKey?;
     private imageSpecs;
     private overlaySpecs;
+    private activeSnapX;
+    private activeSnapY;
+    private snapGuideXObject?;
+    private snapGuideYObject?;
+    private canvasObjectMovingHandler?;
     private renderProducerDisposable?;
     private readonly subscriptions;
     private imageControlsByCapabilityKey;
@@ -102,6 +107,21 @@ declare class ImageTool implements Extension {
     private onSelectionCleared;
     private onSceneLayoutChanged;
     private onSceneGeometryChanged;
+    private bindCanvasInteractionHandlers;
+    private unbindCanvasInteractionHandlers;
+    private getActiveImageTarget;
+    private getTargetBoundsScene;
+    private getSnapThresholdScene;
+    private pickSnapMatch;
+    private computeMoveSnapMatches;
+    private areSnapMatchesEqual;
+    private updateSnapMatchState;
+    private clearSnapGuides;
+    private removeSnapGuideObject;
+    private createOrUpdateSnapGuideObject;
+    private updateSnapGuideVisuals;
+    private handleCanvasObjectMoving;
+    private applySnapMatchesToTarget;
     private syncToolActiveFromWorkbench;
     private isImageEditingVisible;
     private getEnabledImageControlCapabilities;

package/dist/index.js

@@ -3074,6 +3074,9 @@ var IMAGE_DEFAULT_CONTROL_CAPABILITIES = [
   "rotate",
   "scale"
 ];
+var IMAGE_MOVE_SNAP_THRESHOLD_PX = 6;
+var IMAGE_MOVE_SNAP_RELEASE_THRESHOLD_PX = 10;
+var IMAGE_SNAP_GUIDE_LAYER_ID = "image.snapGuide";
 var IMAGE_CONTROL_DESCRIPTORS = [
   {
     key: "tl",
@@ -3118,12 +3121,15 @@ var ImageTool = class {
     this.renderSeq = 0;
     this.imageSpecs = [];
     this.overlaySpecs = [];
+    this.activeSnapX = null;
+    this.activeSnapY = null;
     this.subscriptions = new SubscriptionBag();
     this.imageControlsByCapabilityKey = /* @__PURE__ */ new Map();
     this.onToolActivated = (event) => {
       const before = this.isToolActive;
       this.syncToolActiveFromWorkbench(event.id);
       if (!this.isToolActive) {
+        this.clearSnapGuides();
         this.setImageFocus(null, {
           syncCanvasSelection: true,
           skipRender: true
@@ -3174,6 +3180,7 @@ var ImageTool = class {
       this.updateImages();
     };
     this.onSelectionCleared = () => {
+      this.clearSnapGuides();
       this.setImageFocus(null, {
         syncCanvasSelection: false,
         skipRender: true
@@ -3182,6 +3189,7 @@ var ImageTool = class {
       this.updateImages();
     };
     this.onSceneLayoutChanged = () => {
+      this.updateSnapGuideVisuals();
       this.updateImages();
     };
     this.onSceneGeometryChanged = () => {
@@ -3196,6 +3204,9 @@ var ImageTool = class {
       if (typeof id !== "string" || layerId !== IMAGE_OBJECT_LAYER_ID) return;
       const frame = this.getFrameRect();
       if (!frame.width || !frame.height) return;
+      const matches = this.computeMoveSnapMatches(target, frame);
+      this.applySnapMatchesToTarget(target, matches);
+      this.clearSnapGuides();
       const center = target.getCenterPoint ? target.getCenterPoint() : new import_fabric2.Point((_c = target.left) != null ? _c : 0, (_d = target.top) != null ? _d : 0);
       const centerScene = this.canvasService ? this.canvasService.toScenePoint({ x: center.x, y: center.y }) : { x: center.x, y: center.y };
       const objectScale = Number.isFinite(target == null ? void 0 : target.scaleX) ? target.scaleX : 1;
@@ -3258,8 +3269,17 @@ var ImageTool = class {
       }),
       { priority: 300 }
     );
-    this.subscriptions.on(context.eventBus, "tool:activated", this.onToolActivated);
-    this.subscriptions.on(context.eventBus, "object:modified", this.onObjectModified);
+    this.bindCanvasInteractionHandlers();
+    this.subscriptions.on(
+      context.eventBus,
+      "tool:activated",
+      this.onToolActivated
+    );
+    this.subscriptions.on(
+      context.eventBus,
+      "object:modified",
+      this.onObjectModified
+    );
     this.subscriptions.on(
       context.eventBus,
       "selection:created",
@@ -3327,6 +3347,8 @@ var ImageTool = class {
     this.imageSpecs = [];
     this.overlaySpecs = [];
     this.imageControlsByCapabilityKey.clear();
+    this.clearSnapGuides();
+    this.unbindCanvasInteractionHandlers();
     this.clearRenderedImages();
     (_b = this.renderProducerDisposable) == null ? void 0 : _b.dispose();
     this.renderProducerDisposable = void 0;
@@ -3336,6 +3358,266 @@ var ImageTool = class {
     }
     this.context = void 0;
   }
+  bindCanvasInteractionHandlers() {
+    if (!this.canvasService || this.canvasObjectMovingHandler) return;
+    this.canvasObjectMovingHandler = (e) => {
+      this.handleCanvasObjectMoving(e);
+    };
+    this.canvasService.canvas.on(
+      "object:moving",
+      this.canvasObjectMovingHandler
+    );
+  }
+  unbindCanvasInteractionHandlers() {
+    if (!this.canvasService || !this.canvasObjectMovingHandler) return;
+    this.canvasService.canvas.off(
+      "object:moving",
+      this.canvasObjectMovingHandler
+    );
+    this.canvasObjectMovingHandler = void 0;
+  }
+  getActiveImageTarget(target) {
+    var _a, _b;
+    if (!this.isToolActive) return null;
+    if (!target) return null;
+    if (((_a = target == null ? void 0 : target.data) == null ? void 0 : _a.layerId) !== IMAGE_OBJECT_LAYER_ID) return null;
+    if (typeof ((_b = target == null ? void 0 : target.data) == null ? void 0 : _b.id) !== "string") return null;
+    return target;
+  }
+  getTargetBoundsScene(target) {
+    if (!this.canvasService || !target) return null;
+    const rawBounds = typeof target.getBoundingRect === "function" ? target.getBoundingRect() : {
+      left: Number(target.left || 0),
+      top: Number(target.top || 0),
+      width: Number(target.width || 0),
+      height: Number(target.height || 0)
+    };
+    return this.canvasService.toSceneRect({
+      left: Number(rawBounds.left || 0),
+      top: Number(rawBounds.top || 0),
+      width: Number(rawBounds.width || 0),
+      height: Number(rawBounds.height || 0)
+    });
+  }
+  getSnapThresholdScene(px) {
+    if (!this.canvasService) return px;
+    return this.canvasService.toSceneLength(px);
+  }
+  pickSnapMatch(candidates, previous) {
+    if (!candidates.length) return null;
+    const snapThreshold = this.getSnapThresholdScene(
+      IMAGE_MOVE_SNAP_THRESHOLD_PX
+    );
+    const releaseThreshold = this.getSnapThresholdScene(
+      IMAGE_MOVE_SNAP_RELEASE_THRESHOLD_PX
+    );
+    if (previous) {
+      const sticky = candidates.find((candidate) => {
+        return candidate.lineId === previous.lineId && Math.abs(candidate.deltaScene) <= releaseThreshold;
+      });
+      if (sticky) return sticky;
+    }
+    let best = null;
+    candidates.forEach((candidate) => {
+      if (Math.abs(candidate.deltaScene) > snapThreshold) return;
+      if (!best || Math.abs(candidate.deltaScene) < Math.abs(best.deltaScene)) {
+        best = candidate;
+      }
+    });
+    return best;
+  }
+  computeMoveSnapMatches(target, frame) {
+    const bounds = this.getTargetBoundsScene(target);
+    if (!bounds || frame.width <= 0 || frame.height <= 0) {
+      return { x: null, y: null };
+    }
+    const xCandidates = [
+      {
+        axis: "x",
+        lineId: "frame-left",
+        kind: "edge",
+        lineScene: frame.left,
+        deltaScene: frame.left - bounds.left
+      },
+      {
+        axis: "x",
+        lineId: "frame-center-x",
+        kind: "center",
+        lineScene: frame.left + frame.width / 2,
+        deltaScene: frame.left + frame.width / 2 - (bounds.left + bounds.width / 2)
+      },
+      {
+        axis: "x",
+        lineId: "frame-right",
+        kind: "edge",
+        lineScene: frame.left + frame.width,
+        deltaScene: frame.left + frame.width - (bounds.left + bounds.width)
+      }
+    ];
+    const yCandidates = [
+      {
+        axis: "y",
+        lineId: "frame-top",
+        kind: "edge",
+        lineScene: frame.top,
+        deltaScene: frame.top - bounds.top
+      },
+      {
+        axis: "y",
+        lineId: "frame-center-y",
+        kind: "center",
+        lineScene: frame.top + frame.height / 2,
+        deltaScene: frame.top + frame.height / 2 - (bounds.top + bounds.height / 2)
+      },
+      {
+        axis: "y",
+        lineId: "frame-bottom",
+        kind: "edge",
+        lineScene: frame.top + frame.height,
+        deltaScene: frame.top + frame.height - (bounds.top + bounds.height)
+      }
+    ];
+    return {
+      x: this.pickSnapMatch(xCandidates, this.activeSnapX),
+      y: this.pickSnapMatch(yCandidates, this.activeSnapY)
+    };
+  }
+  areSnapMatchesEqual(a, b) {
+    if (!a && !b) return true;
+    if (!a || !b) return false;
+    return a.lineId === b.lineId && a.axis === b.axis && a.kind === b.kind;
+  }
+  updateSnapMatchState(nextX, nextY) {
+    const changed = !this.areSnapMatchesEqual(this.activeSnapX, nextX) || !this.areSnapMatchesEqual(this.activeSnapY, nextY);
+    this.activeSnapX = nextX;
+    this.activeSnapY = nextY;
+    if (changed) {
+      this.updateSnapGuideVisuals();
+    }
+  }
+  clearSnapGuides() {
+    var _a;
+    this.activeSnapX = null;
+    this.activeSnapY = null;
+    this.removeSnapGuideObject("x");
+    this.removeSnapGuideObject("y");
+    (_a = this.canvasService) == null ? void 0 : _a.requestRenderAll();
+  }
+  removeSnapGuideObject(axis) {
+    if (!this.canvasService) return;
+    const canvas = this.canvasService.canvas;
+    const current = axis === "x" ? this.snapGuideXObject : this.snapGuideYObject;
+    if (!current) return;
+    canvas.remove(current);
+    if (axis === "x") {
+      this.snapGuideXObject = void 0;
+      return;
+    }
+    this.snapGuideYObject = void 0;
+  }
+  createOrUpdateSnapGuideObject(axis, pathData) {
+    if (!this.canvasService) return;
+    const canvas = this.canvasService.canvas;
+    const color = this.getConfig("image.control.borderColor", "#1677ff") || "#1677ff";
+    const strokeWidth = 1;
+    this.removeSnapGuideObject(axis);
+    const created = new import_fabric2.Path(pathData, {
+      originX: "left",
+      originY: "top",
+      fill: "rgba(0,0,0,0)",
+      stroke: color,
+      strokeWidth,
+      selectable: false,
+      evented: false,
+      excludeFromExport: true,
+      objectCaching: false,
+      data: {
+        id: `${IMAGE_SNAP_GUIDE_LAYER_ID}.${axis}`,
+        layerId: IMAGE_SNAP_GUIDE_LAYER_ID,
+        type: "image-snap-guide"
+      }
+    });
+    created.setCoords();
+    canvas.add(created);
+    canvas.bringObjectToFront(created);
+    if (axis === "x") {
+      this.snapGuideXObject = created;
+      return;
+    }
+    this.snapGuideYObject = created;
+  }
+  updateSnapGuideVisuals() {
+    if (!this.canvasService || !this.isImageEditingVisible()) {
+      this.removeSnapGuideObject("x");
+      this.removeSnapGuideObject("y");
+      return;
+    }
+    const frame = this.getFrameRect();
+    if (frame.width <= 0 || frame.height <= 0) {
+      this.removeSnapGuideObject("x");
+      this.removeSnapGuideObject("y");
+      return;
+    }
+    const frameScreen = this.getFrameRectScreen(frame);
+    if (this.activeSnapX) {
+      const x = this.canvasService.toScreenPoint({
+        x: this.activeSnapX.lineScene,
+        y: frame.top
+      }).x;
+      this.createOrUpdateSnapGuideObject(
+        "x",
+        `M ${x} ${frameScreen.top} L ${x} ${frameScreen.top + frameScreen.height}`
+      );
+    } else {
+      this.removeSnapGuideObject("x");
+    }
+    if (this.activeSnapY) {
+      const y = this.canvasService.toScreenPoint({
+        x: frame.left,
+        y: this.activeSnapY.lineScene
+      }).y;
+      this.createOrUpdateSnapGuideObject(
+        "y",
+        `M ${frameScreen.left} ${y} L ${frameScreen.left + frameScreen.width} ${y}`
+      );
+    } else {
+      this.removeSnapGuideObject("y");
+    }
+    this.canvasService.requestRenderAll();
+  }
+  handleCanvasObjectMoving(e) {
+    var _a, _b, _c, _d;
+    const target = this.getActiveImageTarget(e == null ? void 0 : e.target);
+    if (!target || !this.canvasService) return;
+    const frame = this.getFrameRect();
+    if (frame.width <= 0 || frame.height <= 0) {
+      this.clearSnapGuides();
+      return;
+    }
+    const matches = this.computeMoveSnapMatches(target, frame);
+    const deltaX = (_b = (_a = matches.x) == null ? void 0 : _a.deltaScene) != null ? _b : 0;
+    const deltaY = (_d = (_c = matches.y) == null ? void 0 : _c.deltaScene) != null ? _d : 0;
+    if (deltaX || deltaY) {
+      target.set({
+        left: Number(target.left || 0) + this.canvasService.toScreenLength(deltaX),
+        top: Number(target.top || 0) + this.canvasService.toScreenLength(deltaY)
+      });
+      target.setCoords();
+    }
+    this.updateSnapMatchState(matches.x, matches.y);
+  }
+  applySnapMatchesToTarget(target, matches) {
+    var _a, _b, _c, _d;
+    if (!this.canvasService || !target) return;
+    const deltaX = (_b = (_a = matches.x) == null ? void 0 : _a.deltaScene) != null ? _b : 0;
+    const deltaY = (_d = (_c = matches.y) == null ? void 0 : _c.deltaScene) != null ? _d : 0;
+    if (!deltaX && !deltaY) return;
+    target.set({
+      left: Number(target.left || 0) + this.canvasService.toScreenLength(deltaX),
+      top: Number(target.top || 0) + this.canvasService.toScreenLength(deltaY)
+    });
+    target.setCoords();
+  }
   syncToolActiveFromWorkbench(fallbackId) {
     var _a;
     const wb = (_a = this.context) == null ? void 0 : _a.services.get("WorkbenchService");
@@ -4322,6 +4604,7 @@ var ImageTool = class {
       isImageSelectionActive: this.isImageSelectionActive,
       focusedImageId: this.focusedImageId
     });
+    this.updateSnapGuideVisuals();
     this.canvasService.requestRenderAll();
   }
   clampNormalized(value) {

package/dist/index.mjs

@@ -1025,6 +1025,7 @@ import {
   Canvas as FabricCanvas,
   Control,
   Image as FabricImage2,
+  Path as FabricPath,
   Pattern,
   Point,
   controlsUtils
@@ -1998,6 +1999,9 @@ var IMAGE_DEFAULT_CONTROL_CAPABILITIES = [
   "rotate",
   "scale"
 ];
+var IMAGE_MOVE_SNAP_THRESHOLD_PX = 6;
+var IMAGE_MOVE_SNAP_RELEASE_THRESHOLD_PX = 10;
+var IMAGE_SNAP_GUIDE_LAYER_ID = "image.snapGuide";
 var IMAGE_CONTROL_DESCRIPTORS = [
   {
     key: "tl",
@@ -2042,12 +2046,15 @@ var ImageTool = class {
     this.renderSeq = 0;
     this.imageSpecs = [];
     this.overlaySpecs = [];
+    this.activeSnapX = null;
+    this.activeSnapY = null;
     this.subscriptions = new SubscriptionBag();
     this.imageControlsByCapabilityKey = /* @__PURE__ */ new Map();
     this.onToolActivated = (event) => {
       const before = this.isToolActive;
       this.syncToolActiveFromWorkbench(event.id);
       if (!this.isToolActive) {
+        this.clearSnapGuides();
         this.setImageFocus(null, {
           syncCanvasSelection: true,
           skipRender: true
@@ -2098,6 +2105,7 @@ var ImageTool = class {
       this.updateImages();
     };
     this.onSelectionCleared = () => {
+      this.clearSnapGuides();
       this.setImageFocus(null, {
         syncCanvasSelection: false,
         skipRender: true
@@ -2106,6 +2114,7 @@ var ImageTool = class {
       this.updateImages();
     };
     this.onSceneLayoutChanged = () => {
+      this.updateSnapGuideVisuals();
       this.updateImages();
     };
     this.onSceneGeometryChanged = () => {
@@ -2120,6 +2129,9 @@ var ImageTool = class {
       if (typeof id !== "string" || layerId !== IMAGE_OBJECT_LAYER_ID) return;
       const frame = this.getFrameRect();
       if (!frame.width || !frame.height) return;
+      const matches = this.computeMoveSnapMatches(target, frame);
+      this.applySnapMatchesToTarget(target, matches);
+      this.clearSnapGuides();
       const center = target.getCenterPoint ? target.getCenterPoint() : new Point((_c = target.left) != null ? _c : 0, (_d = target.top) != null ? _d : 0);
       const centerScene = this.canvasService ? this.canvasService.toScenePoint({ x: center.x, y: center.y }) : { x: center.x, y: center.y };
       const objectScale = Number.isFinite(target == null ? void 0 : target.scaleX) ? target.scaleX : 1;
@@ -2182,8 +2194,17 @@ var ImageTool = class {
       }),
       { priority: 300 }
     );
-    this.subscriptions.on(context.eventBus, "tool:activated", this.onToolActivated);
-    this.subscriptions.on(context.eventBus, "object:modified", this.onObjectModified);
+    this.bindCanvasInteractionHandlers();
+    this.subscriptions.on(
+      context.eventBus,
+      "tool:activated",
+      this.onToolActivated
+    );
+    this.subscriptions.on(
+      context.eventBus,
+      "object:modified",
+      this.onObjectModified
+    );
     this.subscriptions.on(
       context.eventBus,
       "selection:created",
@@ -2251,6 +2272,8 @@ var ImageTool = class {
     this.imageSpecs = [];
     this.overlaySpecs = [];
     this.imageControlsByCapabilityKey.clear();
+    this.clearSnapGuides();
+    this.unbindCanvasInteractionHandlers();
     this.clearRenderedImages();
     (_b = this.renderProducerDisposable) == null ? void 0 : _b.dispose();
     this.renderProducerDisposable = void 0;
@@ -2260,6 +2283,266 @@ var ImageTool = class {
     }
     this.context = void 0;
   }
+  bindCanvasInteractionHandlers() {
+    if (!this.canvasService || this.canvasObjectMovingHandler) return;
+    this.canvasObjectMovingHandler = (e) => {
+      this.handleCanvasObjectMoving(e);
+    };
+    this.canvasService.canvas.on(
+      "object:moving",
+      this.canvasObjectMovingHandler
+    );
+  }
+  unbindCanvasInteractionHandlers() {
+    if (!this.canvasService || !this.canvasObjectMovingHandler) return;
+    this.canvasService.canvas.off(
+      "object:moving",
+      this.canvasObjectMovingHandler
+    );
+    this.canvasObjectMovingHandler = void 0;
+  }
+  getActiveImageTarget(target) {
+    var _a, _b;
+    if (!this.isToolActive) return null;
+    if (!target) return null;
+    if (((_a = target == null ? void 0 : target.data) == null ? void 0 : _a.layerId) !== IMAGE_OBJECT_LAYER_ID) return null;
+    if (typeof ((_b = target == null ? void 0 : target.data) == null ? void 0 : _b.id) !== "string") return null;
+    return target;
+  }
+  getTargetBoundsScene(target) {
+    if (!this.canvasService || !target) return null;
+    const rawBounds = typeof target.getBoundingRect === "function" ? target.getBoundingRect() : {
+      left: Number(target.left || 0),
+      top: Number(target.top || 0),
+      width: Number(target.width || 0),
+      height: Number(target.height || 0)
+    };
+    return this.canvasService.toSceneRect({
+      left: Number(rawBounds.left || 0),
+      top: Number(rawBounds.top || 0),
+      width: Number(rawBounds.width || 0),
+      height: Number(rawBounds.height || 0)
+    });
+  }
+  getSnapThresholdScene(px) {
+    if (!this.canvasService) return px;
+    return this.canvasService.toSceneLength(px);
+  }
+  pickSnapMatch(candidates, previous) {
+    if (!candidates.length) return null;
+    const snapThreshold = this.getSnapThresholdScene(
+      IMAGE_MOVE_SNAP_THRESHOLD_PX
+    );
+    const releaseThreshold = this.getSnapThresholdScene(
+      IMAGE_MOVE_SNAP_RELEASE_THRESHOLD_PX
+    );
+    if (previous) {
+      const sticky = candidates.find((candidate) => {
+        return candidate.lineId === previous.lineId && Math.abs(candidate.deltaScene) <= releaseThreshold;
+      });
+      if (sticky) return sticky;
+    }
+    let best = null;
+    candidates.forEach((candidate) => {
+      if (Math.abs(candidate.deltaScene) > snapThreshold) return;
+      if (!best || Math.abs(candidate.deltaScene) < Math.abs(best.deltaScene)) {
+        best = candidate;
+      }
+    });
+    return best;
+  }
+  computeMoveSnapMatches(target, frame) {
+    const bounds = this.getTargetBoundsScene(target);
+    if (!bounds || frame.width <= 0 || frame.height <= 0) {
+      return { x: null, y: null };
+    }
+    const xCandidates = [
+      {
+        axis: "x",
+        lineId: "frame-left",
+        kind: "edge",
+        lineScene: frame.left,
+        deltaScene: frame.left - bounds.left
+      },
+      {
+        axis: "x",
+        lineId: "frame-center-x",
+        kind: "center",
+        lineScene: frame.left + frame.width / 2,
+        deltaScene: frame.left + frame.width / 2 - (bounds.left + bounds.width / 2)
+      },
+      {
+        axis: "x",
+        lineId: "frame-right",
+        kind: "edge",
+        lineScene: frame.left + frame.width,
+        deltaScene: frame.left + frame.width - (bounds.left + bounds.width)
+      }
+    ];
+    const yCandidates = [
+      {
+        axis: "y",
+        lineId: "frame-top",
+        kind: "edge",
+        lineScene: frame.top,
+        deltaScene: frame.top - bounds.top
+      },
+      {
+        axis: "y",
+        lineId: "frame-center-y",
+        kind: "center",
+        lineScene: frame.top + frame.height / 2,
+        deltaScene: frame.top + frame.height / 2 - (bounds.top + bounds.height / 2)
+      },
+      {
+        axis: "y",
+        lineId: "frame-bottom",
+        kind: "edge",
+        lineScene: frame.top + frame.height,
+        deltaScene: frame.top + frame.height - (bounds.top + bounds.height)
+      }
+    ];
+    return {
+      x: this.pickSnapMatch(xCandidates, this.activeSnapX),
+      y: this.pickSnapMatch(yCandidates, this.activeSnapY)
+    };
+  }
+  areSnapMatchesEqual(a, b) {
+    if (!a && !b) return true;
+    if (!a || !b) return false;
+    return a.lineId === b.lineId && a.axis === b.axis && a.kind === b.kind;
+  }
+  updateSnapMatchState(nextX, nextY) {
+    const changed = !this.areSnapMatchesEqual(this.activeSnapX, nextX) || !this.areSnapMatchesEqual(this.activeSnapY, nextY);
+    this.activeSnapX = nextX;
+    this.activeSnapY = nextY;
+    if (changed) {
+      this.updateSnapGuideVisuals();
+    }
+  }
+  clearSnapGuides() {
+    var _a;
+    this.activeSnapX = null;
+    this.activeSnapY = null;
+    this.removeSnapGuideObject("x");
+    this.removeSnapGuideObject("y");
+    (_a = this.canvasService) == null ? void 0 : _a.requestRenderAll();
+  }
+  removeSnapGuideObject(axis) {
+    if (!this.canvasService) return;
+    const canvas = this.canvasService.canvas;
+    const current = axis === "x" ? this.snapGuideXObject : this.snapGuideYObject;
+    if (!current) return;
+    canvas.remove(current);
+    if (axis === "x") {
+      this.snapGuideXObject = void 0;
+      return;
+    }
+    this.snapGuideYObject = void 0;
+  }
+  createOrUpdateSnapGuideObject(axis, pathData) {
+    if (!this.canvasService) return;
+    const canvas = this.canvasService.canvas;
+    const color = this.getConfig("image.control.borderColor", "#1677ff") || "#1677ff";
+    const strokeWidth = 1;
+    this.removeSnapGuideObject(axis);
+    const created = new FabricPath(pathData, {
+      originX: "left",
+      originY: "top",
+      fill: "rgba(0,0,0,0)",
+      stroke: color,
+      strokeWidth,
+      selectable: false,
+      evented: false,
+      excludeFromExport: true,
+      objectCaching: false,
+      data: {
+        id: `${IMAGE_SNAP_GUIDE_LAYER_ID}.${axis}`,
+        layerId: IMAGE_SNAP_GUIDE_LAYER_ID,
+        type: "image-snap-guide"
+      }
+    });
+    created.setCoords();
+    canvas.add(created);
+    canvas.bringObjectToFront(created);
+    if (axis === "x") {
+      this.snapGuideXObject = created;
+      return;
+    }
+    this.snapGuideYObject = created;
+  }
+  updateSnapGuideVisuals() {
+    if (!this.canvasService || !this.isImageEditingVisible()) {
+      this.removeSnapGuideObject("x");
+      this.removeSnapGuideObject("y");
+      return;
+    }
+    const frame = this.getFrameRect();
+    if (frame.width <= 0 || frame.height <= 0) {
+      this.removeSnapGuideObject("x");
+      this.removeSnapGuideObject("y");
+      return;
+    }
+    const frameScreen = this.getFrameRectScreen(frame);
+    if (this.activeSnapX) {
+      const x = this.canvasService.toScreenPoint({
+        x: this.activeSnapX.lineScene,
+        y: frame.top
+      }).x;
+      this.createOrUpdateSnapGuideObject(
+        "x",
+        `M ${x} ${frameScreen.top} L ${x} ${frameScreen.top + frameScreen.height}`
+      );
+    } else {
+      this.removeSnapGuideObject("x");
+    }
+    if (this.activeSnapY) {
+      const y = this.canvasService.toScreenPoint({
+        x: frame.left,
+        y: this.activeSnapY.lineScene
+      }).y;
+      this.createOrUpdateSnapGuideObject(
+        "y",
+        `M ${frameScreen.left} ${y} L ${frameScreen.left + frameScreen.width} ${y}`
+      );
+    } else {
+      this.removeSnapGuideObject("y");
+    }
+    this.canvasService.requestRenderAll();
+  }
+  handleCanvasObjectMoving(e) {
+    var _a, _b, _c, _d;
+    const target = this.getActiveImageTarget(e == null ? void 0 : e.target);
+    if (!target || !this.canvasService) return;
+    const frame = this.getFrameRect();
+    if (frame.width <= 0 || frame.height <= 0) {
+      this.clearSnapGuides();
+      return;
+    }
+    const matches = this.computeMoveSnapMatches(target, frame);
+    const deltaX = (_b = (_a = matches.x) == null ? void 0 : _a.deltaScene) != null ? _b : 0;
+    const deltaY = (_d = (_c = matches.y) == null ? void 0 : _c.deltaScene) != null ? _d : 0;
+    if (deltaX || deltaY) {
+      target.set({
+        left: Number(target.left || 0) + this.canvasService.toScreenLength(deltaX),
+        top: Number(target.top || 0) + this.canvasService.toScreenLength(deltaY)
+      });
+      target.setCoords();
+    }
+    this.updateSnapMatchState(matches.x, matches.y);
+  }
+  applySnapMatchesToTarget(target, matches) {
+    var _a, _b, _c, _d;
+    if (!this.canvasService || !target) return;
+    const deltaX = (_b = (_a = matches.x) == null ? void 0 : _a.deltaScene) != null ? _b : 0;
+    const deltaY = (_d = (_c = matches.y) == null ? void 0 : _c.deltaScene) != null ? _d : 0;
+    if (!deltaX && !deltaY) return;
+    target.set({
+      left: Number(target.left || 0) + this.canvasService.toScreenLength(deltaX),
+      top: Number(target.top || 0) + this.canvasService.toScreenLength(deltaY)
+    });
+    target.setCoords();
+  }
   syncToolActiveFromWorkbench(fallbackId) {
     var _a;
     const wb = (_a = this.context) == null ? void 0 : _a.services.get("WorkbenchService");
@@ -3246,6 +3529,7 @@ var ImageTool = class {
       isImageSelectionActive: this.isImageSelectionActive,
       focusedImageId: this.focusedImageId
     });
+    this.updateSnapGuideVisuals();
     this.canvasService.requestRenderAll();
   }
   clampNormalized(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pooder/kit",
-  "version": "6.1.1",
+  "version": "6.1.2",
   "description": "Standard plugins for Pooder editor",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/extensions/image/ImageTool.ts

@@ -10,11 +10,16 @@ import {
   Canvas as FabricCanvas,
   Control,
   Image as FabricImage,
+  Path as FabricPath,
   Pattern,
   Point,
   controlsUtils,
 } from "fabric";
-import { CanvasService, RenderLayoutRect, RenderObjectSpec } from "../../services";
+import {
+  CanvasService,
+  RenderLayoutRect,
+  RenderObjectSpec,
+} from "../../services";
 import { isDielineShape, normalizeShapeStyle } from "../dielineShape";
 import type { DielineShape, DielineShapeStyle } from "../dielineShape";
 import { generateDielinePath, getPathBounds } from "../geometry";
@@ -140,11 +145,41 @@ interface ImageControlDescriptor {
   create: () => Control;
 }
 
+type SnapAxis = "x" | "y";
+type SnapLineKind = "edge" | "center";
+type SnapLineId =
+  | "frame-left"
+  | "frame-center-x"
+  | "frame-right"
+  | "frame-top"
+  | "frame-center-y"
+  | "frame-bottom";
+
+interface SnapMatch {
+  axis: SnapAxis;
+  lineId: SnapLineId;
+  kind: SnapLineKind;
+  lineScene: number;
+  deltaScene: number;
+}
+
+interface SnapCandidate {
+  axis: SnapAxis;
+  lineId: SnapLineId;
+  kind: SnapLineKind;
+  lineScene: number;
+  deltaScene: number;
+}
+
 const IMAGE_DEFAULT_CONTROL_CAPABILITIES: ImageControlCapability[] = [
   "rotate",
   "scale",
 ];
 
+const IMAGE_MOVE_SNAP_THRESHOLD_PX = 6;
+const IMAGE_MOVE_SNAP_RELEASE_THRESHOLD_PX = 10;
+const IMAGE_SNAP_GUIDE_LAYER_ID = "image.snapGuide";
+
 const IMAGE_CONTROL_DESCRIPTORS: ImageControlDescriptor[] = [
   {
     key: "tl",
@@ -199,6 +234,11 @@ export class ImageTool implements Extension {
   private cropShapeHatchPatternKey?: string;
   private imageSpecs: RenderObjectSpec[] = [];
   private overlaySpecs: RenderObjectSpec[] = [];
+  private activeSnapX: SnapMatch | null = null;
+  private activeSnapY: SnapMatch | null = null;
+  private snapGuideXObject?: FabricPath;
+  private snapGuideYObject?: FabricPath;
+  private canvasObjectMovingHandler?: (e: any) => void;
   private renderProducerDisposable?: { dispose: () => void };
   private readonly subscriptions = new SubscriptionBag();
   private imageControlsByCapabilityKey: Map<string, Record<string, Control>> =
@@ -247,9 +287,18 @@ export class ImageTool implements Extension {
       }),
       { priority: 300 },
     );
+    this.bindCanvasInteractionHandlers();
 
-    this.subscriptions.on(context.eventBus, "tool:activated", this.onToolActivated);
-    this.subscriptions.on(context.eventBus, "object:modified", this.onObjectModified);
+    this.subscriptions.on(
+      context.eventBus,
+      "tool:activated",
+      this.onToolActivated,
+    );
+    this.subscriptions.on(
+      context.eventBus,
+      "object:modified",
+      this.onObjectModified,
+    );
     this.subscriptions.on(
       context.eventBus,
       "selection:created",
@@ -328,6 +377,8 @@ export class ImageTool implements Extension {
     this.imageSpecs = [];
     this.overlaySpecs = [];
     this.imageControlsByCapabilityKey.clear();
+    this.clearSnapGuides();
+    this.unbindCanvasInteractionHandlers();
 
     this.clearRenderedImages();
     this.renderProducerDisposable?.dispose();
@@ -347,6 +398,7 @@ export class ImageTool implements Extension {
     const before = this.isToolActive;
     this.syncToolActiveFromWorkbench(event.id);
     if (!this.isToolActive) {
+      this.clearSnapGuides();
       this.setImageFocus(null, {
         syncCanvasSelection: true,
         skipRender: true,
@@ -396,6 +448,7 @@ export class ImageTool implements Extension {
   };
 
   private onSelectionCleared = () => {
+    this.clearSnapGuides();
     this.setImageFocus(null, {
       syncCanvasSelection: false,
       skipRender: true,
@@ -405,6 +458,7 @@ export class ImageTool implements Extension {
   };
 
   private onSceneLayoutChanged = () => {
+    this.updateSnapGuideVisuals();
     this.updateImages();
   };
 
@@ -412,6 +466,322 @@ export class ImageTool implements Extension {
     this.updateImages();
   };
 
+  private bindCanvasInteractionHandlers() {
+    if (!this.canvasService || this.canvasObjectMovingHandler) return;
+    this.canvasObjectMovingHandler = (e: any) => {
+      this.handleCanvasObjectMoving(e);
+    };
+    this.canvasService.canvas.on(
+      "object:moving",
+      this.canvasObjectMovingHandler,
+    );
+  }
+
+  private unbindCanvasInteractionHandlers() {
+    if (!this.canvasService || !this.canvasObjectMovingHandler) return;
+    this.canvasService.canvas.off(
+      "object:moving",
+      this.canvasObjectMovingHandler,
+    );
+    this.canvasObjectMovingHandler = undefined;
+  }
+
+  private getActiveImageTarget(target: any): any | null {
+    if (!this.isToolActive) return null;
+    if (!target) return null;
+    if (target?.data?.layerId !== IMAGE_OBJECT_LAYER_ID) return null;
+    if (typeof target?.data?.id !== "string") return null;
+    return target;
+  }
+
+  private getTargetBoundsScene(target: any): FrameRect | null {
+    if (!this.canvasService || !target) return null;
+    const rawBounds =
+      typeof target.getBoundingRect === "function"
+        ? target.getBoundingRect()
+        : {
+            left: Number(target.left || 0),
+            top: Number(target.top || 0),
+            width: Number(target.width || 0),
+            height: Number(target.height || 0),
+          };
+    return this.canvasService.toSceneRect({
+      left: Number(rawBounds.left || 0),
+      top: Number(rawBounds.top || 0),
+      width: Number(rawBounds.width || 0),
+      height: Number(rawBounds.height || 0),
+    });
+  }
+
+  private getSnapThresholdScene(px: number): number {
+    if (!this.canvasService) return px;
+    return this.canvasService.toSceneLength(px);
+  }
+
+  private pickSnapMatch(
+    candidates: SnapCandidate[],
+    previous: SnapMatch | null,
+  ): SnapMatch | null {
+    if (!candidates.length) return null;
+
+    const snapThreshold = this.getSnapThresholdScene(
+      IMAGE_MOVE_SNAP_THRESHOLD_PX,
+    );
+    const releaseThreshold = this.getSnapThresholdScene(
+      IMAGE_MOVE_SNAP_RELEASE_THRESHOLD_PX,
+    );
+
+    if (previous) {
+      const sticky = candidates.find((candidate) => {
+        return (
+          candidate.lineId === previous.lineId &&
+          Math.abs(candidate.deltaScene) <= releaseThreshold
+        );
+      });
+      if (sticky) return sticky;
+    }
+
+    let best: SnapCandidate | null = null;
+    candidates.forEach((candidate) => {
+      if (Math.abs(candidate.deltaScene) > snapThreshold) return;
+      if (!best || Math.abs(candidate.deltaScene) < Math.abs(best.deltaScene)) {
+        best = candidate;
+      }
+    });
+    return best;
+  }
+
+  private computeMoveSnapMatches(
+    target: any,
+    frame: FrameRect,
+  ): { x: SnapMatch | null; y: SnapMatch | null } {
+    const bounds = this.getTargetBoundsScene(target);
+    if (!bounds || frame.width <= 0 || frame.height <= 0) {
+      return { x: null, y: null };
+    }
+
+    const xCandidates: SnapCandidate[] = [
+      {
+        axis: "x",
+        lineId: "frame-left",
+        kind: "edge",
+        lineScene: frame.left,
+        deltaScene: frame.left - bounds.left,
+      },
+      {
+        axis: "x",
+        lineId: "frame-center-x",
+        kind: "center",
+        lineScene: frame.left + frame.width / 2,
+        deltaScene:
+          frame.left + frame.width / 2 - (bounds.left + bounds.width / 2),
+      },
+      {
+        axis: "x",
+        lineId: "frame-right",
+        kind: "edge",
+        lineScene: frame.left + frame.width,
+        deltaScene: frame.left + frame.width - (bounds.left + bounds.width),
+      },
+    ];
+    const yCandidates: SnapCandidate[] = [
+      {
+        axis: "y",
+        lineId: "frame-top",
+        kind: "edge",
+        lineScene: frame.top,
+        deltaScene: frame.top - bounds.top,
+      },
+      {
+        axis: "y",
+        lineId: "frame-center-y",
+        kind: "center",
+        lineScene: frame.top + frame.height / 2,
+        deltaScene:
+          frame.top + frame.height / 2 - (bounds.top + bounds.height / 2),
+      },
+      {
+        axis: "y",
+        lineId: "frame-bottom",
+        kind: "edge",
+        lineScene: frame.top + frame.height,
+        deltaScene: frame.top + frame.height - (bounds.top + bounds.height),
+      },
+    ];
+
+    return {
+      x: this.pickSnapMatch(xCandidates, this.activeSnapX),
+      y: this.pickSnapMatch(yCandidates, this.activeSnapY),
+    };
+  }
+
+  private areSnapMatchesEqual(
+    a: SnapMatch | null,
+    b: SnapMatch | null,
+  ): boolean {
+    if (!a && !b) return true;
+    if (!a || !b) return false;
+    return a.lineId === b.lineId && a.axis === b.axis && a.kind === b.kind;
+  }
+
+  private updateSnapMatchState(
+    nextX: SnapMatch | null,
+    nextY: SnapMatch | null,
+  ) {
+    const changed =
+      !this.areSnapMatchesEqual(this.activeSnapX, nextX) ||
+      !this.areSnapMatchesEqual(this.activeSnapY, nextY);
+    this.activeSnapX = nextX;
+    this.activeSnapY = nextY;
+    if (changed) {
+      this.updateSnapGuideVisuals();
+    }
+  }
+
+  private clearSnapGuides() {
+    this.activeSnapX = null;
+    this.activeSnapY = null;
+    this.removeSnapGuideObject("x");
+    this.removeSnapGuideObject("y");
+    this.canvasService?.requestRenderAll();
+  }
+
+  private removeSnapGuideObject(axis: SnapAxis) {
+    if (!this.canvasService) return;
+    const canvas = this.canvasService.canvas;
+    const current =
+      axis === "x" ? this.snapGuideXObject : this.snapGuideYObject;
+    if (!current) return;
+    canvas.remove(current);
+    if (axis === "x") {
+      this.snapGuideXObject = undefined;
+      return;
+    }
+    this.snapGuideYObject = undefined;
+  }
+
+  private createOrUpdateSnapGuideObject(axis: SnapAxis, pathData: string) {
+    if (!this.canvasService) return;
+    const canvas = this.canvasService.canvas;
+    const color =
+      this.getConfig<string>("image.control.borderColor", "#1677ff") ||
+      "#1677ff";
+    const strokeWidth = 1;
+    this.removeSnapGuideObject(axis);
+
+    const created = new FabricPath(pathData, {
+      originX: "left",
+      originY: "top",
+      fill: "rgba(0,0,0,0)",
+      stroke: color,
+      strokeWidth,
+      selectable: false,
+      evented: false,
+      excludeFromExport: true,
+      objectCaching: false,
+      data: {
+        id: `${IMAGE_SNAP_GUIDE_LAYER_ID}.${axis}`,
+        layerId: IMAGE_SNAP_GUIDE_LAYER_ID,
+        type: "image-snap-guide",
+      },
+    } as any);
+    created.setCoords();
+    canvas.add(created);
+    canvas.bringObjectToFront(created);
+    if (axis === "x") {
+      this.snapGuideXObject = created;
+      return;
+    }
+    this.snapGuideYObject = created;
+  }
+
+  private updateSnapGuideVisuals() {
+    if (!this.canvasService || !this.isImageEditingVisible()) {
+      this.removeSnapGuideObject("x");
+      this.removeSnapGuideObject("y");
+      return;
+    }
+
+    const frame = this.getFrameRect();
+    if (frame.width <= 0 || frame.height <= 0) {
+      this.removeSnapGuideObject("x");
+      this.removeSnapGuideObject("y");
+      return;
+    }
+    const frameScreen = this.getFrameRectScreen(frame);
+
+    if (this.activeSnapX) {
+      const x = this.canvasService.toScreenPoint({
+        x: this.activeSnapX.lineScene,
+        y: frame.top,
+      }).x;
+      this.createOrUpdateSnapGuideObject(
+        "x",
+        `M ${x} ${frameScreen.top} L ${x} ${frameScreen.top + frameScreen.height}`,
+      );
+    } else {
+      this.removeSnapGuideObject("x");
+    }
+
+    if (this.activeSnapY) {
+      const y = this.canvasService.toScreenPoint({
+        x: frame.left,
+        y: this.activeSnapY.lineScene,
+      }).y;
+      this.createOrUpdateSnapGuideObject(
+        "y",
+        `M ${frameScreen.left} ${y} L ${frameScreen.left + frameScreen.width} ${y}`,
+      );
+    } else {
+      this.removeSnapGuideObject("y");
+    }
+
+    this.canvasService.requestRenderAll();
+  }
+
+  private handleCanvasObjectMoving(e: any) {
+    const target = this.getActiveImageTarget(e?.target);
+    if (!target || !this.canvasService) return;
+
+    const frame = this.getFrameRect();
+    if (frame.width <= 0 || frame.height <= 0) {
+      this.clearSnapGuides();
+      return;
+    }
+
+    const matches = this.computeMoveSnapMatches(target, frame);
+    const deltaX = matches.x?.deltaScene ?? 0;
+    const deltaY = matches.y?.deltaScene ?? 0;
+
+    if (deltaX || deltaY) {
+      target.set({
+        left:
+          Number(target.left || 0) + this.canvasService.toScreenLength(deltaX),
+        top:
+          Number(target.top || 0) + this.canvasService.toScreenLength(deltaY),
+      });
+      target.setCoords();
+    }
+
+    this.updateSnapMatchState(matches.x, matches.y);
+  }
+
+  private applySnapMatchesToTarget(
+    target: any,
+    matches: { x: SnapMatch | null; y: SnapMatch | null },
+  ) {
+    if (!this.canvasService || !target) return;
+    const deltaX = matches.x?.deltaScene ?? 0;
+    const deltaY = matches.y?.deltaScene ?? 0;
+    if (!deltaX && !deltaY) return;
+
+    target.set({
+      left: Number(target.left || 0) + this.canvasService.toScreenLength(deltaX),
+      top: Number(target.top || 0) + this.canvasService.toScreenLength(deltaY),
+    });
+    target.setCoords();
+  }
+
   private syncToolActiveFromWorkbench(fallbackId?: string | null) {
     const wb = this.context?.services.get<WorkbenchService>("WorkbenchService");
     const activeId = wb?.activeToolId;
@@ -1589,6 +1959,7 @@ export class ImageTool implements Extension {
       isImageSelectionActive: this.isImageSelectionActive,
       focusedImageId: this.focusedImageId,
     });
+    this.updateSnapGuideVisuals();
     this.canvasService.requestRenderAll();
   }
 
@@ -1605,6 +1976,9 @@ export class ImageTool implements Extension {
 
     const frame = this.getFrameRect();
     if (!frame.width || !frame.height) return;
+    const matches = this.computeMoveSnapMatches(target, frame);
+    this.applySnapMatchesToTarget(target, matches);
+    this.clearSnapGuides();
 
     const center = target.getCenterPoint
       ? target.getCenterPoint()