@ngroznykh/papirus 0.3.13 → 0.3.15

package/dist/papirus.js

@@ -435,6 +435,7 @@ const ANCHOR_POINT_HITBOX_RADIUS = 10;
 const NODE_HITBOX_PADDING = 10;
 const ANCHOR_PORT_PREFIX = "anchor:";
 const BEZIER_MAX_OFFSET = 100;
+const OUTLINE_SNAP_SCREEN_TOLERANCE = 40;
 const SELECTION_RECT_MIN_SIZE = 1;
 const DEFAULT_SELECTION_COLOR = "#3b82f6";
 const DEFAULT_HOVER_COLOR = "#6366f1";
@@ -1571,16 +1572,29 @@ class ConnectionManager extends EventEmitter {
     this.hoverDisabled = false;
     this.reconnectPoint = null;
     this.previewTargetAnchorId = null;
+    this.sourceOutlineParam = null;
+    this.previewTargetOutlineParam = null;
+    this.previewTargetNodeId = null;
     this.isReconnecting = false;
     this.reconnectingEdge = null;
     this.reconnectingEndpoint = null;
     this.originalEdgeEndpoint = null;
+    this.reconnectingOutlineParam = null;
+    this.reconnectingTargetNodeId = null;
     this.activeControlPointDrag = null;
     this.renderer = options.renderer;
     this.createEdge = options.createEdge;
     this.addEdge = options.addEdge ?? ((edge) => this.renderer.addEdge(edge));
     this.snapToGrid = options.snapToGrid ?? false;
     this.gridSize = options.gridSize ?? 20;
+    this.attachToOutline = options.attachToOutline ?? false;
+  }
+  /**
+   * Enable/disable attach-to-outline mode (edges attach anywhere on shape contour)
+   */
+  setAttachToOutline(enabled) {
+    this.attachToOutline = enabled;
+    this.renderer.attachToOutline = enabled;
   }
   /**
    * Enable/disable snap to grid for editable polyline control points.
@@ -1646,9 +1660,17 @@ class ConnectionManager extends EventEmitter {
     this.sourceNode = node;
     this.isConnecting = true;
     const target = { x: event.worldX, y: event.worldY };
-    const anchor = node.getNearestAnchor(target);
-    this.sourceAnchorId = anchor?.id ?? null;
-    this.sourcePoint = anchor?.point ?? node.getConnectionPoint(target);
+    if (this.attachToOutline) {
+      const { point, param } = node.getClosestPointOnOutline(target);
+      this.sourceOutlineParam = param;
+      this.sourceAnchorId = null;
+      this.sourcePoint = point;
+    } else {
+      const anchor = node.getNearestAnchor(target);
+      this.sourceOutlineParam = null;
+      this.sourceAnchorId = anchor?.id ?? null;
+      this.sourcePoint = anchor?.point ?? node.getConnectionPoint(target);
+    }
     this.previewEndpoint = target;
     this.emit("connectionStart", node);
     return true;
@@ -1668,7 +1690,9 @@ class ConnectionManager extends EventEmitter {
     return false;
   }
   /**
-   * Try to start connection from a hovered anchor point
+   * Try to start connection from a hovered anchor point.
+   * When attachToOutline + Shift: start from anywhere on node outline.
+   * Otherwise: requires clicking on an anchor so that node drag still works.
    */
   tryStartConnectionAtPoint(event) {
     const point = { x: event.worldX, y: event.worldY };
@@ -1676,6 +1700,18 @@ class ConnectionManager extends EventEmitter {
     if (!node) {
       return false;
     }
+    if (this.attachToOutline && event.shiftKey) {
+      const { point: outlinePoint, param } = node.getClosestPointOnOutline(point);
+      this.sourceNode = node;
+      this.isConnecting = true;
+      this.sourceAnchorId = null;
+      this.sourcePoint = outlinePoint;
+      this.sourceOutlineParam = param;
+      this.previewEndpoint = point;
+      this.emit("connectionStart", node);
+      this.renderer.markDirty();
+      return true;
+    }
     const hover = this.getAnchorAtPoint(node, point);
     if (!hover) {
       return false;
@@ -1685,6 +1721,12 @@ class ConnectionManager extends EventEmitter {
     this.sourceAnchorId = hover.id;
     this.sourcePoint = hover.point;
     this.previewEndpoint = point;
+    if (this.attachToOutline) {
+      const { param } = node.getClosestPointOnOutline(point);
+      this.sourceOutlineParam = param;
+    } else {
+      this.sourceOutlineParam = null;
+    }
     this.emit("connectionStart", node);
     this.renderer.markDirty();
     return true;
@@ -1735,32 +1777,122 @@ class ConnectionManager extends EventEmitter {
     const toNode = this.renderer.getNode(edge.to.nodeId);
     let snappedPoint = point;
     let snappedDir;
-    const targetNode = this.getNodeAtPoint(point, true);
-    if (targetNode) {
+    let targetNode = this.getNodeAtPoint(point, true);
+    if (this.attachToOutline) {
+      const tolerance = OUTLINE_SNAP_SCREEN_TOLERANCE / Math.max(this.renderer.zoom, 1e-4);
+      const toleranceSq = tolerance * tolerance;
+      let bestDistSq = Infinity;
+      let bestResult = null;
+      for (const node of this.renderer.nodes.values()) {
+        if (!node.visible) continue;
+        const { point: outlinePoint, param } = node.getClosestPointOnOutline(point);
+        const dx = point.x - outlinePoint.x;
+        const dy = point.y - outlinePoint.y;
+        const distSq = dx * dx + dy * dy;
+        if (distSq <= toleranceSq && distSq < bestDistSq) {
+          bestDistSq = distSq;
+          bestResult = { node, point: outlinePoint, param };
+        }
+      }
+      if (bestResult) {
+        targetNode = bestResult.node;
+        snappedPoint = bestResult.point;
+        this.reconnectingOutlineParam = bestResult.param;
+        this.reconnectingTargetNodeId = bestResult.node.id;
+        snappedDir = this.getDirectionFromOutlineParam(bestResult.param, bestResult.node);
+        const otherNode = this.reconnectingEndpoint === "start" ? toNode : fromNode;
+        if (otherNode) {
+          const alignRef = edge.isEditablePolyline() ? this.getNearestBendPointForAxisAlignment(edge, this.reconnectingEndpoint) : this.reconnectingEndpoint === "start" ? this.getTargetPointForReconnect(edge, toNode, "to", snappedPoint) : this.getTargetPointForReconnect(edge, fromNode, "from", snappedPoint);
+          snappedPoint = this.applyAxisAlignmentToPoint(snappedPoint, alignRef);
+          const reprojected = targetNode.getClosestPointOnOutline(snappedPoint);
+          snappedPoint = reprojected.point;
+          this.reconnectingOutlineParam = reprojected.param;
+          snappedDir = this.getDirectionFromOutlineParam(reprojected.param, targetNode);
+        }
+      } else {
+        this.reconnectingOutlineParam = null;
+        this.reconnectingTargetNodeId = null;
+      }
+    } else if (targetNode) {
       const nearestAnchor = targetNode.getNearestAnchor(point);
       if (nearestAnchor) {
         snappedPoint = nearestAnchor.point;
         snappedDir = nearestAnchor.id.split(":")[0];
       }
+      this.reconnectingOutlineParam = null;
+      this.reconnectingTargetNodeId = null;
+    } else {
+      this.reconnectingOutlineParam = null;
+      this.reconnectingTargetNodeId = null;
     }
     this.reconnectPoint = snappedPoint;
     if (this.reconnectingEndpoint === "start") {
       if (toNode) {
-        const toAnchorId = edge.to.portId?.replace(ANCHOR_PORT_PREFIX, "");
-        const target = toAnchorId ? toNode.getAnchorPointById(toAnchorId) ?? toNode.getConnectionPoint(snappedPoint) : toNode.getConnectionPoint(snappedPoint);
-        const toDir = toAnchorId?.split(":")[0];
+        const target = this.getTargetPointForReconnect(edge, toNode, "to", snappedPoint);
+        const toDir = this.getTargetDirForReconnect(edge, toNode, "to");
         edge.updateEndpoints(snappedPoint, target, snappedDir, toDir);
       }
     } else {
       if (fromNode) {
-        const fromAnchorId = edge.from.portId?.replace(ANCHOR_PORT_PREFIX, "");
-        const start = fromAnchorId ? fromNode.getAnchorPointById(fromAnchorId) ?? fromNode.getConnectionPoint(snappedPoint) : fromNode.getConnectionPoint(snappedPoint);
-        const fromDir = fromAnchorId?.split(":")[0];
+        const start = this.getTargetPointForReconnect(edge, fromNode, "from", snappedPoint);
+        const fromDir = this.getTargetDirForReconnect(edge, fromNode, "from");
         edge.updateEndpoints(start, snappedPoint, fromDir, snappedDir);
       }
     }
     this.renderer.markDirty();
   }
+  getTargetPointForReconnect(edge, node, endpoint, fallbackPoint) {
+    const ep = endpoint === "from" ? edge.from : edge.to;
+    if (this.attachToOutline && ep.outlineParam !== void 0) {
+      return node.getConnectionPointAtOutlineParam(ep.outlineParam);
+    }
+    const anchorId = ep.portId?.replace(ANCHOR_PORT_PREFIX, "");
+    if (anchorId) {
+      return node.getAnchorPointById(anchorId) ?? node.getConnectionPoint(fallbackPoint);
+    }
+    return node.getConnectionPoint(fallbackPoint);
+  }
+  getTargetDirForReconnect(edge, node, endpoint) {
+    const ep = endpoint === "from" ? edge.from : edge.to;
+    if (this.attachToOutline && ep.outlineParam !== void 0) {
+      return this.getDirectionFromOutlineParam(ep.outlineParam, node);
+    }
+    const anchorId = ep.portId?.replace(ANCHOR_PORT_PREFIX, "");
+    return anchorId?.split(":")[0];
+  }
+  getDirectionFromOutlineParam(param, _node) {
+    const p = (param % 1 + 1) % 1;
+    if (p < 0.25) return "top";
+    if (p < 0.5) return "right";
+    if (p < 0.75) return "bottom";
+    return "left";
+  }
+  /**
+   * For editable polyline: return the nearest bend point for axis alignment.
+   * When reconnecting 'end', use last control point (or start). When reconnecting 'start', use first control point (or end).
+   */
+  getNearestBendPointForAxisAlignment(edge, endpoint) {
+    const cps = edge.isEditablePolyline() ? edge.controlPoints ?? edge.getEditableControlPoints() : [];
+    if (endpoint === "end") {
+      return cps.length > 0 ? cps[cps.length - 1] : edge.startPoint;
+    }
+    return cps.length > 0 ? cps[0] : edge.endPoint;
+  }
+  /**
+   * When attachToOutline: snap moving point to horizontal/vertical alignment with fixed point.
+   */
+  applyAxisAlignmentToPoint(moving, fixed) {
+    const tolerance = EDGE_AXIS_MAGNET_SCREEN_TOLERANCE / Math.max(this.renderer.zoom, 1e-4);
+    let x = moving.x;
+    let y = moving.y;
+    if (Math.abs(moving.x - fixed.x) <= tolerance) {
+      x = fixed.x;
+    }
+    if (Math.abs(moving.y - fixed.y) <= tolerance) {
+      y = fixed.y;
+    }
+    return { x, y };
+  }
   /**
    * Handle mouse move during connection
    */
@@ -1792,25 +1924,60 @@ class ConnectionManager extends EventEmitter {
     const cursorPoint = { x: event.worldX, y: event.worldY };
     let snappedPoint = cursorPoint;
     this.previewTargetAnchorId = null;
-    const targetNode = this.getNodeAtPoint(cursorPoint, false);
-    if (targetNode && this.isCompatibleTarget(targetNode)) {
+    this.previewTargetOutlineParam = null;
+    this.previewTargetNodeId = null;
+    let targetNode = this.getNodeAtPoint(cursorPoint, false);
+    if (this.attachToOutline) {
+      const tolerance = OUTLINE_SNAP_SCREEN_TOLERANCE / Math.max(this.renderer.zoom, 1e-4);
+      const toleranceSq = tolerance * tolerance;
+      let bestDistSq = Infinity;
+      let bestResult = null;
+      for (const node of this.renderer.nodes.values()) {
+        if (!node.visible || !this.isCompatibleTarget(node)) continue;
+        const forbidden = this._connectionValidator && this.sourceNode && !this._connectionValidator(this.sourceNode.id, node.id);
+        if (forbidden) continue;
+        const { point: outlinePoint, param } = node.getClosestPointOnOutline(cursorPoint);
+        const dx = cursorPoint.x - outlinePoint.x;
+        const dy = cursorPoint.y - outlinePoint.y;
+        const distSq = dx * dx + dy * dy;
+        if (distSq <= toleranceSq && distSq < bestDistSq) {
+          bestDistSq = distSq;
+          bestResult = { node, point: outlinePoint, param };
+        }
+      }
+      if (bestResult) {
+        targetNode = bestResult.node;
+        snappedPoint = bestResult.point;
+        this.previewTargetOutlineParam = bestResult.param;
+        this.previewTargetNodeId = bestResult.node.id;
+        if (this.sourcePoint) {
+          snappedPoint = this.applyAxisAlignmentToPoint(snappedPoint, this.sourcePoint);
+          const reprojected = bestResult.node.getClosestPointOnOutline(snappedPoint);
+          snappedPoint = reprojected.point;
+          this.previewTargetOutlineParam = reprojected.param;
+        }
+      }
+    } else if (targetNode && this.isCompatibleTarget(targetNode)) {
       const forbidden = this._connectionValidator && this.sourceNode && !this._connectionValidator(this.sourceNode.id, targetNode.id);
-      if (forbidden) {
-        this.setCursor("not-allowed");
-      } else {
-        this.setCursor("crosshair");
+      if (!forbidden) {
         const nearestAnchor = targetNode.getNearestAnchor(cursorPoint);
         if (nearestAnchor) {
           snappedPoint = nearestAnchor.point;
           this.previewTargetAnchorId = nearestAnchor.id;
         }
       }
+    }
+    if (targetNode) {
+      const forbidden = this._connectionValidator && this.sourceNode && !this._connectionValidator(this.sourceNode.id, targetNode.id);
+      this.setCursor(forbidden ? "not-allowed" : "crosshair");
     } else {
       this.setCursor("crosshair");
     }
     this.previewEndpoint = snappedPoint;
-    if (this.sourceNode && !this.sourceAnchorId) {
+    if (this.sourceNode && !this.sourceAnchorId && !this.sourceOutlineParam) {
       this.sourcePoint = this.sourceNode.getConnectionPoint(this.previewEndpoint);
+    } else if (this.sourceNode && this.sourceOutlineParam !== null) {
+      this.sourcePoint = this.sourceNode.getConnectionPointAtOutlineParam(this.sourceOutlineParam);
     }
     this.emit(
       "connectionMove",
@@ -1866,19 +2033,29 @@ class ConnectionManager extends EventEmitter {
     if (this.isReconnecting && this.reconnectingEdge) {
       const point2 = { x: event.worldX, y: event.worldY };
       let reconnected = false;
-      const node = this.getNodeAtPoint(point2, true);
+      let node = this.getNodeAtPoint(point2, true);
+      if (!node && this.attachToOutline && this.reconnectingTargetNodeId) {
+        node = this.renderer.getNode(this.reconnectingTargetNodeId) ?? null;
+      }
       if (node) {
-        const anchor = node.getNearestAnchor(point2);
-        if (this.reconnectingEndpoint === "start") {
-          this.reconnectingEdge.from = {
+        if (this.attachToOutline && this.reconnectingOutlineParam !== null) {
+          const endpoint = {
             nodeId: node.id,
-            portId: this.reconnectingEdge.lockAnchors && anchor ? `${ANCHOR_PORT_PREFIX}${anchor.id}` : void 0
+            outlineParam: this.reconnectingOutlineParam
           };
+          if (this.reconnectingEndpoint === "start") {
+            this.reconnectingEdge.from = endpoint;
+          } else {
+            this.reconnectingEdge.to = endpoint;
+          }
         } else {
-          this.reconnectingEdge.to = {
-            nodeId: node.id,
-            portId: this.reconnectingEdge.lockAnchors && anchor ? `${ANCHOR_PORT_PREFIX}${anchor.id}` : void 0
-          };
+          const anchor = node.getNearestAnchor(point2);
+          const portId = this.reconnectingEdge.lockAnchors && anchor ? `${ANCHOR_PORT_PREFIX}${anchor.id}` : void 0;
+          if (this.reconnectingEndpoint === "start") {
+            this.reconnectingEdge.from = { nodeId: node.id, portId };
+          } else {
+            this.reconnectingEdge.to = { nodeId: node.id, portId };
+          }
         }
         reconnected = true;
         this.emit("edgeReconnect", this.reconnectingEdge, this.reconnectingEndpoint);
@@ -1900,20 +2077,36 @@ class ConnectionManager extends EventEmitter {
     }
     const point = { x: event.worldX, y: event.worldY };
     let createdEdge = null;
-    const targetNode = this.getNodeAtPoint(point, false);
+    let targetNode = this.getNodeAtPoint(point, false);
+    if (!targetNode && this.attachToOutline && this.previewTargetNodeId) {
+      targetNode = this.renderer.getNode(this.previewTargetNodeId) ?? null;
+    }
     if (targetNode) {
       const allowed = !this._connectionValidator || this._connectionValidator(this.sourceNode.id, targetNode.id);
       if (allowed) {
-        const nearestTargetAnchor = targetNode.getNearestAnchor(point);
-        const sourceAnchorId = this.sourceAnchorId;
-        const from = {
-          nodeId: this.sourceNode.id,
-          portId: sourceAnchorId ? `${ANCHOR_PORT_PREFIX}${sourceAnchorId}` : void 0
-        };
-        const to = {
-          nodeId: targetNode.id,
-          portId: nearestTargetAnchor ? `${ANCHOR_PORT_PREFIX}${nearestTargetAnchor.id}` : void 0
-        };
+        let from;
+        let to;
+        if (this.attachToOutline) {
+          const targetOutline = targetNode.getClosestPointOnOutline(point);
+          from = {
+            nodeId: this.sourceNode.id,
+            outlineParam: this.sourceOutlineParam ?? void 0
+          };
+          to = {
+            nodeId: targetNode.id,
+            outlineParam: targetOutline.param
+          };
+        } else {
+          const nearestTargetAnchor = targetNode.getNearestAnchor(point);
+          from = {
+            nodeId: this.sourceNode.id,
+            portId: this.sourceAnchorId ? `${ANCHOR_PORT_PREFIX}${this.sourceAnchorId}` : void 0
+          };
+          to = {
+            nodeId: targetNode.id,
+            portId: nearestTargetAnchor ? `${ANCHOR_PORT_PREFIX}${nearestTargetAnchor.id}` : void 0
+          };
+        }
         createdEdge = this.createEdge(from, to);
         this.addEdge(createdEdge);
         this.emit("connect", createdEdge);
@@ -1940,7 +2133,9 @@ class ConnectionManager extends EventEmitter {
    */
   renderPreview(ctx) {
     if (this.isReconnecting && this.reconnectPoint) {
-      this.renderAnchorHighlights(ctx, this.reconnectPoint, true);
+      if (!this.attachToOutline) {
+        this.renderAnchorHighlights(ctx, this.reconnectPoint, true);
+      }
       return;
     }
     if (!this.isConnecting || this.previewEndpoint === null) {
@@ -1948,14 +2143,16 @@ class ConnectionManager extends EventEmitter {
     }
     const start = this.sourcePoint;
     const end = this.previewEndpoint;
-    const fromDir = this.sourceAnchorId?.split(":")[0];
-    const toDir = this.previewTargetAnchorId?.split(":")[0];
+    const fromDir = this.sourceOutlineParam !== null ? this.getDirectionFromOutlineParam(this.sourceOutlineParam, this.sourceNode) : this.sourceAnchorId?.split(":")[0];
+    const toDir = this.previewTargetOutlineParam !== null ? this.getDirectionFromOutlineParam(this.previewTargetOutlineParam, this.sourceNode) : this.previewTargetAnchorId?.split(":")[0];
     ctx.strokeStyle = "#3b82f6";
     ctx.lineWidth = 2;
     ctx.setLineDash([6, 4]);
     this.drawBezierPreview(ctx, start, end, fromDir, toDir);
     ctx.setLineDash([]);
-    this.renderAnchorHighlights(ctx, end, false);
+    if (!this.attachToOutline) {
+      this.renderAnchorHighlights(ctx, end, false);
+    }
   }
   /**
    * Get control point offset based on direction
@@ -2035,6 +2232,9 @@ class ConnectionManager extends EventEmitter {
     this.sourcePoint = null;
     this.previewEndpoint = null;
     this.sourceAnchorId = null;
+    this.sourceOutlineParam = null;
+    this.previewTargetOutlineParam = null;
+    this.previewTargetNodeId = null;
     this.setCursor("");
   }
   resetReconnection() {
@@ -2045,6 +2245,8 @@ class ConnectionManager extends EventEmitter {
     this.reconnectingEdge = null;
     this.reconnectingEndpoint = null;
     this.originalEdgeEndpoint = null;
+    this.reconnectingOutlineParam = null;
+    this.reconnectingTargetNodeId = null;
     this.reconnectPoint = null;
     this.setCursor("");
   }
@@ -2056,6 +2258,9 @@ class ConnectionManager extends EventEmitter {
       return;
     }
     this.renderEditablePolylineControls(ctx);
+    if (this.attachToOutline) {
+      return;
+    }
     if (!this.hoverNodeId) {
       return;
     }
@@ -4644,11 +4849,14 @@ class InteractionManager {
     this.navigationManager = new NavigationManager({ renderer: this.renderer });
     this.historyManager = new HistoryManager();
     this.keymap = { ...DEFAULT_KEYMAP, ...options.keymap };
+    const attachToOutline = options.attachToOutline ?? false;
+    this.renderer.attachToOutline = attachToOutline;
     this.connectionManager = new ConnectionManager({
       renderer: this.renderer,
       createEdge: options.createEdge ?? ((from, to) => new Edge({ from, to, type: "bezier", arrowType: "single" })),
       snapToGrid: options.snapToGrid ?? this.renderer.snapToGrid,
       gridSize: options.gridSize ?? 20,
+      attachToOutline,
       addEdge: (edge) => {
         this.historyManager.execute({
           execute: () => this.renderer.addEdge(edge),
@@ -5474,7 +5682,13 @@ class InteractionManager {
     });
   }
   endpointsEqual(a, b) {
-    return a.nodeId === b.nodeId && (a.portId ?? null) === (b.portId ?? null);
+    if (a.nodeId !== b.nodeId) return false;
+    if ((a.portId ?? null) !== (b.portId ?? null)) return false;
+    const aParam = a.outlineParam;
+    const bParam = b.outlineParam;
+    if (aParam === void 0 && bParam === void 0) return true;
+    if (aParam === void 0 || bParam === void 0) return false;
+    return Math.abs(aParam % 1 - bParam % 1) < 1e-9;
   }
   getSelectionBounds() {
     const selected = Array.from(this.selectionManager.selectedIds);
@@ -5957,6 +6171,7 @@ class DiagramRenderer extends EventEmitter {
     this._nodes = /* @__PURE__ */ new Map();
     this._edges = /* @__PURE__ */ new Map();
     this._groups = /* @__PURE__ */ new Map();
+    this._attachToOutline = false;
     this.canvas = this.resolveCanvas(canvas);
     this.options = { ...DEFAULT_OPTIONS$1, ...options };
     this.scrollbar = this.resolveScrollbarOptions(options);
@@ -5972,6 +6187,16 @@ class DiagramRenderer extends EventEmitter {
     this.setupCanvas();
     this.startRenderLoop();
   }
+  /** When true, ports and anchor points are hidden (attach anywhere on outline) */
+  get attachToOutline() {
+    return this._attachToOutline;
+  }
+  set attachToOutline(value) {
+    if (this._attachToOutline !== value) {
+      this._attachToOutline = value;
+      this.markDirty();
+    }
+  }
   /**
    * Current zoom level
    */
@@ -6208,6 +6433,7 @@ class DiagramRenderer extends EventEmitter {
    */
   addNode(node) {
     node.setDirtyListener(() => this.markDirty());
+    node.setAttachToOutlineGetter(() => this._attachToOutline);
     this._nodes.set(node.id, node);
     this.animationManager.registerEnter(node.id);
     this.markDirty();
@@ -6291,6 +6517,7 @@ class DiagramRenderer extends EventEmitter {
     }
     this._nodes.delete(nodeId);
     node.setDirtyListener(void 0);
+    node.setAttachToOutlineGetter(void 0);
     this.markDirty();
     this.emit("nodeRemove", node);
     return true;
@@ -6542,13 +6769,15 @@ class DiagramRenderer extends EventEmitter {
       if (fromNode === void 0 || toNode === void 0) {
         continue;
       }
-      if (edge.lockAnchors) {
+      if (edge.lockAnchors && edge.from.outlineParam === void 0) {
         if (!edge.from.portId) {
           const anchor = fromNode.getNearestAnchor(toNode.getCenter());
           if (anchor) {
             edge.from = { ...edge.from, portId: `${ANCHOR_PORT_PREFIX}${anchor.id}` };
           }
         }
+      }
+      if (edge.lockAnchors && edge.to.outlineParam === void 0) {
         if (!edge.to.portId) {
           const anchor = toNode.getNearestAnchor(fromNode.getCenter());
           if (anchor) {
@@ -6560,7 +6789,10 @@ class DiagramRenderer extends EventEmitter {
       let toPoint = toNode.getConnectionPoint(fromNode.getCenter());
       let fromDir;
       let toDir;
-      if (edge.lockAnchors && edge.from.portId?.startsWith(ANCHOR_PORT_PREFIX)) {
+      if (edge.from.outlineParam !== void 0) {
+        fromPoint = fromNode.getConnectionPointAtOutlineParam(edge.from.outlineParam);
+        fromDir = this.getDirectionFromOutlineParam(edge.from.outlineParam);
+      } else if (edge.lockAnchors && edge.from.portId?.startsWith(ANCHOR_PORT_PREFIX)) {
         const anchorId = edge.from.portId.slice(ANCHOR_PORT_PREFIX.length);
         const anchorPoint = fromNode.getAnchorPointById(anchorId);
         if (anchorPoint) {
@@ -6568,7 +6800,10 @@ class DiagramRenderer extends EventEmitter {
           fromDir = anchorId.split(":")[0];
         }
       }
-      if (edge.lockAnchors && edge.to.portId?.startsWith(ANCHOR_PORT_PREFIX)) {
+      if (edge.to.outlineParam !== void 0) {
+        toPoint = toNode.getConnectionPointAtOutlineParam(edge.to.outlineParam);
+        toDir = this.getDirectionFromOutlineParam(edge.to.outlineParam);
+      } else if (edge.lockAnchors && edge.to.portId?.startsWith(ANCHOR_PORT_PREFIX)) {
         const anchorId = edge.to.portId.slice(ANCHOR_PORT_PREFIX.length);
         const anchorPoint = toNode.getAnchorPointById(anchorId);
         if (anchorPoint) {
@@ -6586,6 +6821,13 @@ class DiagramRenderer extends EventEmitter {
       edge.updateEndpoints(fromPoint, toPoint, fromDir, toDir, { obstacles });
     }
   }
+  getDirectionFromOutlineParam(param) {
+    const p = (param % 1 + 1) % 1;
+    if (p < 0.25) return "top";
+    if (p < 0.5) return "right";
+    if (p < 0.75) return "bottom";
+    return "left";
+  }
   renderScrollbars(ctx) {
     const metrics = this.getScrollbarMetrics();
     if (!metrics) {
@@ -7891,10 +8133,19 @@ class Node extends Element {
   get defaultSize() {
     return { ...this._defaultSize };
   }
+  /**
+   * Set getter for attachToOutline (called by DiagramRenderer when node is added)
+   */
+  setAttachToOutlineGetter(getter) {
+    this._attachToOutlineGetter = getter;
+  }
   /**
    * Render ports
    */
   renderPorts(ctx) {
+    if (this._attachToOutlineGetter?.()) {
+      return;
+    }
     const shouldShow = this._showPortsAlways || this._ports.some((port) => port.hovered) || this._state === "hover" || this._state === "selected" || this._state === "dragging";
     if (!shouldShow) {
       return;
@@ -8177,6 +8428,52 @@ class Node extends Element {
       height: this._height
     };
   }
+  /**
+   * Get point on outline at normalized param (0-1 along perimeter).
+   * Base implementation uses rectangular outline. Override for non-rectangular shapes.
+   */
+  getConnectionPointAtOutlineParam(param) {
+    const bounds = this.getBounds();
+    const { x, y, width: w, height: h } = bounds;
+    const perimeter = 2 * (w + h);
+    let s = (param % 1 + 1) % 1 * perimeter;
+    if (s < w) return { x: x + s, y };
+    s -= w;
+    if (s < h) return { x: x + w, y: y + s };
+    s -= h;
+    if (s < w) return { x: x + w - s, y: y + h };
+    s -= w;
+    return { x, y: y + h - s };
+  }
+  /**
+   * Get closest point on outline and its param (0-1).
+   * Base implementation uses rectangular outline. Override for non-rectangular shapes.
+   */
+  getClosestPointOnOutline(target) {
+    const bounds = this.getBounds();
+    const { x, y, width: w, height: h } = bounds;
+    const P = 2 * (w + h);
+    const projectSegment = (ax, ay, bx, by, segLen, segStartParam) => {
+      const dx = bx - ax;
+      const dy = by - ay;
+      const lenSq = dx * dx + dy * dy;
+      let t = lenSq > 0 ? ((target.x - ax) * dx + (target.y - ay) * dy) / lenSq : 0;
+      t = Math.max(0, Math.min(1, t));
+      const px = ax + t * dx;
+      const py = ay + t * dy;
+      const distSq = (target.x - px) ** 2 + (target.y - py) ** 2;
+      const param = segStartParam + t * segLen / P;
+      return { point: { x: px, y: py }, param, distSq };
+    };
+    let best = projectSegment(x, y, x + w, y, w, 0);
+    let r = projectSegment(x + w, y, x + w, y + h, h, w / P);
+    if (r.distSq < best.distSq) best = r;
+    r = projectSegment(x + w, y + h, x, y + h, w, (w + h) / P);
+    if (r.distSq < best.distSq) best = r;
+    r = projectSegment(x, y + h, x, y, h, (2 * w + h) / P);
+    if (r.distSq < best.distSq) best = r;
+    return { point: best.point, param: best.param };
+  }
   /**
    * Get intersection point on the shape outline toward the target.
    * Override for non-rectangular shapes.
@@ -8724,6 +9021,30 @@ class CircleNode extends Node {
     const dy = point.y - center.y;
     return dx * dx / (rx * rx) + dy * dy / (ry * ry) <= 1;
   }
+  getConnectionPointAtOutlineParam(param) {
+    const center = this.getCenter();
+    const rx = this._width / 2;
+    const ry = this._height / 2;
+    const t = (param % 1 + 1) % 1 * Math.PI * 2;
+    const angle2 = Math.PI * 1.5 - t;
+    return {
+      x: center.x + rx * Math.cos(angle2),
+      y: center.y + ry * Math.sin(angle2)
+    };
+  }
+  getClosestPointOnOutline(target) {
+    const point = this.getOutlinePointToward(target);
+    const center = this.getCenter();
+    const rx = this._width / 2;
+    const ry = this._height / 2;
+    const t = Math.atan2(
+      (point.y - center.y) / ry,
+      (point.x - center.x) / rx
+    );
+    const param = (Math.PI * 1.5 - t) / (Math.PI * 2);
+    const normalizedParam = (param % 1 + 1) % 1;
+    return { point, param: normalizedParam };
+  }
   getOutlinePointToward(target) {
     const center = this.getCenter();
     const rx = this._width / 2;
@@ -8785,6 +9106,66 @@ class DiamondNode extends Node {
     const dy = Math.abs(point.y - center.y);
     return dx / hw + dy / hh <= 1;
   }
+  getConnectionPointAtOutlineParam(param) {
+    const center = this.getCenter();
+    const hw = this._width / 2;
+    const hh = this._height / 2;
+    const vertices = [
+      { x: center.x, y: center.y - hh },
+      { x: center.x + hw, y: center.y },
+      { x: center.x, y: center.y + hh },
+      { x: center.x - hw, y: center.y }
+    ];
+    const segLen = Math.sqrt(hw * hw + hh * hh);
+    const perimeter = 4 * segLen;
+    let s = (param % 1 + 1) % 1 * perimeter;
+    for (let i = 0; i < 4; i++) {
+      if (s < segLen) {
+        const a = vertices[i];
+        const b = vertices[(i + 1) % 4];
+        const t = s / segLen;
+        return {
+          x: a.x + t * (b.x - a.x),
+          y: a.y + t * (b.y - a.y)
+        };
+      }
+      s -= segLen;
+    }
+    return vertices[0];
+  }
+  getClosestPointOnOutline(target) {
+    const center = this.getCenter();
+    const hw = this._width / 2;
+    const hh = this._height / 2;
+    const vertices = [
+      { x: center.x, y: center.y - hh },
+      { x: center.x + hw, y: center.y },
+      { x: center.x, y: center.y + hh },
+      { x: center.x - hw, y: center.y }
+    ];
+    const segLen = Math.sqrt(hw * hw + hh * hh);
+    const P = 4 * segLen;
+    const projectSegment = (ax, ay, bx, by, segStartParam) => {
+      const dx = bx - ax;
+      const dy = by - ay;
+      const lenSq = dx * dx + dy * dy;
+      let t = lenSq > 0 ? ((target.x - ax) * dx + (target.y - ay) * dy) / lenSq : 0;
+      t = Math.max(0, Math.min(1, t));
+      const px = ax + t * dx;
+      const py = ay + t * dy;
+      const distSq = (target.x - px) ** 2 + (target.y - py) ** 2;
+      const param = segStartParam + t * segLen / P;
+      return { point: { x: px, y: py }, param, distSq };
+    };
+    let best = projectSegment(vertices[0].x, vertices[0].y, vertices[1].x, vertices[1].y, 0);
+    for (let i = 1; i < 4; i++) {
+      const a = vertices[i];
+      const b = vertices[(i + 1) % 4];
+      const r = projectSegment(a.x, a.y, b.x, b.y, i * segLen / P);
+      if (r.distSq < best.distSq) best = r;
+    }
+    return { point: best.point, param: best.param };
+  }
   getOutlinePointToward(target) {
     const center = this.getCenter();
     const dx = target.x - center.x;
@@ -10556,6 +10937,7 @@ class MiniMap {
       width: options.width ?? 180,
       height: options.height ?? 120,
       padding: options.padding ?? 12,
+      contentMargin: options.contentMargin ?? 0,
       backgroundColor: options.backgroundColor ?? "rgba(24, 24, 27, 0.5)",
       borderColor: options.borderColor ?? "#52525b",
       viewportColor: options.viewportColor ?? "#22c55e",
@@ -10694,14 +11076,27 @@ class MiniMap {
     if (!rawBounds) {
       return null;
     }
+    const margin = this.options.contentMargin;
+    const expandedContentBounds = {
+      x: rawBounds.x - margin,
+      y: rawBounds.y - margin,
+      width: rawBounds.width + 2 * margin,
+      height: rawBounds.height + 2 * margin
+    };
     const { width, height, padding, anchor } = this.options;
     const x = anchor === "bottom-left" || anchor === "top-left" ? padding : renderer.width - width - padding;
     const y = anchor === "top-left" || anchor === "top-right" ? padding : renderer.height - height - padding;
     const viewportBounds = this.getViewportBounds(renderer);
-    const unionMinX = Math.min(rawBounds.x, viewportBounds.x);
-    const unionMinY = Math.min(rawBounds.y, viewportBounds.y);
-    const unionMaxX = Math.max(rawBounds.x + rawBounds.width, viewportBounds.x + viewportBounds.width);
-    const unionMaxY = Math.max(rawBounds.y + rawBounds.height, viewportBounds.y + viewportBounds.height);
+    const unionMinX = Math.min(expandedContentBounds.x, viewportBounds.x);
+    const unionMinY = Math.min(expandedContentBounds.y, viewportBounds.y);
+    const unionMaxX = Math.max(
+      expandedContentBounds.x + expandedContentBounds.width,
+      viewportBounds.x + viewportBounds.width
+    );
+    const unionMaxY = Math.max(
+      expandedContentBounds.y + expandedContentBounds.height,
+      viewportBounds.y + viewportBounds.height
+    );
     const bounds = {
       x: unionMinX,
       y: unionMinY,