drawui-core 0.3.3 → 0.3.4

package/dist/index.d.cts

@@ -185,12 +185,24 @@ interface GenerationContext {
     sourceShapeId?: string;
     edge?: 'n' | 'e' | 's' | 'w';
 }
-/** 生成点位预览：从源点拖出的虚线线条 + 待放置图形轮廓 */
+/** 生成点位预览：与最终创建结果完全一致的连线预览（+ 待放置图形轮廓） */
 interface GenerationPreview {
     from: Vec2;
     to: Vec2;
     /** 待放置图形的类型；不提供（指向已有图形）时只画线条 */
     type?: ShapeType;
+    /** 源图形 id 与出线边：预览走与最终创建相同的「出线边同轴接入」路由 */
+    sourceShapeId?: string;
+    sourceEdge?: 'n' | 'e' | 's' | 'w';
+    /** 指向已有图形时的目标与绑定（预览即最终落点） */
+    targetShapeId?: string;
+    targetBinding?: ArrowBinding;
+    /** true = 拖拽中（按真实样式预览）；false/缺省 = 悬停（浅色虚线提示） */
+    dragging?: boolean;
+    /** 新建连线的默认样式，与最终创建保持一致 */
+    arrowStyle?: ArrowStyle;
+    /** 连线本身的颜色/粗细，与最终创建保持一致 */
+    lineStyle?: ShapeStyle;
 }
 /** 生成点位 → UI 菜单载荷：拖动到空白处后触发的"选择新图形"菜单 */
 interface GenerationMenuPayload {
@@ -803,6 +815,7 @@ declare class Editor {
     private snapGuides;
     private connectingTargetId;
     private genPreview;
+    private hoverAnchorShapeId;
     private eraserPoint;
     private mindMapEditingShapeId;
     private mindMapSelectedNode;
@@ -819,6 +832,23 @@ declare class Editor {
     private arrowStyle;
     constructor(canvas: HTMLCanvasElement, options?: EditorOptions);
     private setupEventListeners;
+    /** 窗口失焦（切页签/alt-tab）：按下状态与一切瞬态预览都作废，避免"卡住" */
+    private handleWindowBlur;
+    /**
+     * 在画布之外按下指针（工具栏、面板、页面空白）→ 立刻收尾残留交互。
+     * 用户预期是「点哪儿都能把残留的虚线清掉」，这里就是那根兜底绳。
+     * 若此时 pointerIsDown 仍是 true，说明上一轮的 pointerup 丢了（在窗口外松手），
+     * 一并把按下状态复位。
+     */
+    private handleGlobalPointerDown;
+    /**
+     * 当前是否存在「本该结束、却还留着」的瞬态交互。
+     * 注意：只认拖拽态（工具非空闲 / 目标高亮 / 对齐线 / 框选）——
+     * 悬停产生的锚点与悬停预览是常驻的合法状态，不能算残留，否则每次移动都会被打断。
+     */
+    private shouldRecoverTransient;
+    /** 收尾：让工具回到空闲态，并清空画布上的瞬态可视化 */
+    private cancelTransientInteraction;
     private handlePointerDown;
     private handlePointerMove;
     private handlePointerUp;
@@ -844,8 +874,16 @@ declare class Editor {
     /** 设置对齐参考线（由工具在拖拽过程中调用） */
     private setSnapGuides;
     private setConnectingTarget;
-    /** 设置生成点位预览（拖动/悬浮中显示的线条 + 待放置图形） */
+    /** 设置生成点位预览（拖动/悬浮中显示的连线 + 待放置图形虚框） */
     private setGenerationPreview;
+    /** 设置悬停图形（画布为其绘制四边连接锚点） */
+    private setHoverAnchorShape;
+    /**
+     * 清掉所有「瞬态」的交互可视化状态：连线预览、目标高亮、对齐参考线、框选、悬停锚点。
+     * 这些状态只在一次交互过程中有效 —— 只要交互结束（或事件丢失）就必须清空，
+     * 否则会残留虚线/虚框且越点越多。返回是否确有清理（供调用方决定是否重绘）。
+     */
+    private clearTransientPreview;
     /** 拖动到空白处松开 → 弹出"选择新图形"菜单（转发给 React UI） */
     private openGenerationMenu;
     private lineStyle;
@@ -853,10 +891,7 @@ declare class Editor {
     private computeSourceBinding;
     /**
      * 连线到达目标图形时，应吸附到目标面向来线的那个边。
-     * 关键规则：接入边与出线边「同轴」—— 从源图形左右边出线，就优先接目标的
-     * 左/右边（面向来线的一侧）；从上下边出线，就优先接目标的上/下边。
-     * 这样多条分支连线才能共用同一条正交主干总线（飞书式分叉），而不是各自
-     * 横着拐进目标的顶边、沿边缘爬进去。
+     * 规则唯一来源：`docking.ts` 的 pickDockSide（与出线边同轴，详见该文件注释）。
      */
     private connectHandle;
     /** 仅创建一条从源点引出、末端悬空的线条并选中它 */
@@ -1126,7 +1161,9 @@ declare class Renderer {
         nodeId: string;
     } | null, 
     /** 导出用：非 null 时先以该颜色铺满整块画布（白底等），默认不铺（透明） */
-    background?: string | null): void;
+    background?: string | null, 
+    /** 悬停的图形 id：为其绘制四边连接锚点（飞书式悬浮提示），已选中图形由选择手柄负责 */
+    hoverAnchorShapeId?: string | null): void;
     /** 橡皮擦：半透明主色圆 + 主色描边，半径与笔刷命中范围一致（屏幕像素恒定） */
     private drawEraserBrush;
     /** 连接进行中，高亮目标图形四边中点的可连锚点 */
@@ -1188,11 +1225,23 @@ declare class Renderer {
     private drawArrow;
     /** 选中连线 → 在线条上叠加一条高亮辅助线 */
     private drawLinearHighlight;
-    /** 生成点位预览：源点圆点 + 虚线线条 + 待放置图形轮廓 */
+    /**
+     * 生成点位预览：源点圆点 + 连线预览 + 待放置图形虚框。
+     *
+     * 关键：预览不再是「直线虚线」——它把待创建的连线合成为一条临时箭头，
+     * 直接走 drawArrow 的真实渲染路径（正交路由 / 垂直出入桩 / 出线边同轴接入 /
+     * 箭头头部 / 虚线样式全一致），因此拖拽时看到的就是松手后得到的样子。
+     * 拖拽中按真实样式绘制；悬停时降为半透明，保持「尚未确定」的观感。
+     */
     private drawGenerationPreview;
-    /** 待放置图形的虚线轮廓（按默认尺寸绘制对应类型） */
+    /** 待放置图形的虚线轮廓（按该类型的真实默认尺寸绘制） */
     private drawPreviewShapeOutline;
     private static readonly ALIGN_TOLERANCE;
+    /** 生成预览用的临时 id / 样式（不写入文档，仅本次绘制使用） */
+    private static readonly GEN_PREVIEW_ID;
+    private static readonly GEN_GHOST_ID;
+    /** 与 Editor.lineStyle() 一致：预览线用最终连线的真实颜色/粗细 */
+    private static readonly PREVIEW_LINE_STYLE;
     /**
      * 判断连线两端是否水平或垂直对齐（在容差内）。
      * 若在容差内，强制将坐标对齐（避免 grid snapping 导致无法形成直线）。
@@ -1214,10 +1263,25 @@ declare class Renderer {
     private generatePolylinePoints;
     /** 直角折线：与 polyline 使用相同的 H-V-H 正交路由，仅渲染方式（sharp）不同。 */
     private generateOrthogonalPoints;
+    /**
+     * 把折线末段掰到期望轴向（'H' 水平收尾 / 'V' 垂直收尾）。
+     * 绕行分支（A 星网格 / 退避）给出的路径末段方向不受控，这里在末点前补一个拐点，
+     * 保证箭头始终沿接入边法向插入（或沿出线方向收尾）。
+     */
+    private ensureFinalAxis;
     /** 去除连续重合点与共线点，精简冗余拐点 */
     private collapseLinePoints;
     /** 计算单段直角路由：优先无碰撞、且符合总线轴方向的 H-V-H / V-H-V 折线，必要时绕开障碍 */
     private computeOrthogonalRoute;
+    /**
+     * 剔除「把某个端点压在身下」的障碍。
+     *
+     * 这类障碍（典型：用户把图形拖到与另一张图形重叠）无法绕开 —— 端点的落点就在它里面，
+     * 与其避让只会让布线变成「绕着端点打转」的怪线，还会把 A* 的终点节点封死。
+     * 剔除后连线可以直穿重叠图形，观测上就是「叠在一起就随他叠」，
+     * 同时保证端点（点位）不会被自动挪走。
+     */
+    private dropObstaclesAtEndpoints;
     /**
      * 在停靠偏好对应的总线轴上，从源侧向外逐点平移总线位置，返回第一条「垂直方向和
      * 末段水平分支都避开所有中间障碍」的总线折线；找不到则返回 null。
@@ -1254,20 +1318,27 @@ declare class Renderer {
     private getTextBounds;
     private wrapLine;
     private truncateLine;
-    /** 连接点句柄 → 外法向（页面坐标单位向量） */
+    /** 连接点句柄 → 外法向（页面坐标单位向量；规则见 docking.ts） */
     private static readonly HANDLE_NORMALS;
     /**
-     * 自动接入边选择：与出线边「同轴」优先 —— 从源图形左右边出线就接目标的
-     * 左/右边（面向来线一侧），从上下边出线就接上/下边；这样分支连线才能共用
-     * 同一条正交主干总线，而不是横着拐进目标顶边。无出线方向信息时退回主方向规则。
+     * 自动接入边选择：与出线边「同轴」优先（规则唯一来源见 docking.ts）——
+     * 从源图形左右边出线就接目标的左/右边（面向来线一侧），从上下边出线就接上/下边；
+     * 这样分支连线才能共用同一条正交主干总线，而不是横着拐进目标顶边。
      */
     private pickAutoHandle;
     /** auto 绑定 → 按当前几何重选接入边；显式绑定原样返回 */
     private resolveAutoEndBinding;
     private getBindingPoint;
+    /**
+     * 求某一端的停靠法向。**优先用绑定信息**：绑定已经明确告诉我们是哪个图形的哪条边，
+     * 比几何猜测可靠得多 —— 当有图形与端点所在图形重叠时（典型：新建图形虚框压在源图形上），
+     * 纯几何的 getDockNormal 会挑到「离端点更近的另一张图形」，把出线/接入方向判反。
+     */
+    private resolveDockNormal;
     /**
      * 计算端点所在图形的外法向（垂直于该侧边缘，页面坐标单位向量）。
      * 用于连线垂直脱离/接入图形边缘，端点不在任何图形上时返回 undefined。
+     * preferShapeId：优先认这个图形（端点正好被多张图形覆盖时用它消歧）。
      */
     private getDockNormal;
     /**
@@ -1303,6 +1374,12 @@ declare class Renderer {
     private drawFreehand;
     private drawSelectionOutline;
     private drawSelectionHandles;
+    /**
+     * 四边中点的连接锚点（外圈 + 内点）。
+     * bounds 使用调用方的坐标系：选中手柄路径传入「本地包围盒」（画布已 translate 到图形中心），
+     * 悬停提示路径传入「世界包围盒」（画布未平移）。alpha 用于弱化悬停态。
+     */
+    private drawConnectionDots;
     /** 画旋转图标：顺时针短弧 + 箭头 */
     private drawRotateIcon;
     private getShapeBounds;
@@ -1354,6 +1431,10 @@ interface ToolContext {
     setSnapGuides(guides: SnapGuide[]): void;
     setConnectingTarget(id: string | null): void;
     setGenerationPreview(preview: GenerationPreview | null): void;
+    /** 悬停图形 → 画布为其绘制四边连接锚点（null 清除） */
+    setHoverAnchorShape(id: string | null): void;
+    /** 新建连线的线条样式（颜色/粗细），与最终创建的连线保持一致 */
+    getLineStyle(): ShapeStyle;
     /** 拖动到空白处：创建一条浮动线条并弹出"选择新图形"菜单 */
     openGenerationMenu(payload: GenerationMenuPayload): void;
     /** 创建"新图形 + 连线"；existingArrowId 存在时把线条末端接到新图形 */
@@ -1392,6 +1473,17 @@ declare abstract class Tool {
     abstract onKeyUp(event: KeyboardEvent): void;
     /** 返回当前指针位置应显示的鼠标样式，null 表示使用默认 */
     getCursor(_point: Vec2): string | null;
+    /**
+     * 是否正处于一次未结束的交互中（拖拽/生成/框选…）。
+     * 编辑器据此判断「指针没按下却仍有工具状态」= 丢事件，需要自愈。
+     */
+    hasTransientState(): boolean;
+    /**
+     * 取消一切「瞬态」交互状态（正在拖拽/生成/框选/旋转…），回到干净的空闲态。
+     * 用于指针事件丢失（在窗口外松手、失焦）、点击画布外、切换工具时的自愈。
+     * @returns 是否确实清理了状态（false = 本来就是空闲态，调用方可跳过重绘）
+     */
+    cancelTransient(): boolean;
     dispose(): void;
 }
 
@@ -1402,6 +1494,8 @@ declare class SelectTool extends Tool {
     private resizingState;
     private generatingState;
     private hoverGenPoint;
+    /** 悬停（未按下）的图形 id：为其显示四边连接锚点，可直接从这里拖出连线 */
+    private hoverShapeId;
     private rotatingState;
     private draggingArrowId;
     private draggingTerminal;
@@ -1410,12 +1504,23 @@ declare class SelectTool extends Tool {
     private brushShiftKey;
     /** 生成点位默认创建的图形类型：源图形若为可创建类型则同型，否则用矩形 */
     private defaultGenType;
+    /**
+     * 生成点位预览：带上源图形/出线边/目标绑定/线条样式，画布据此走「与最终创建完全一致」
+     * 的真实渲染路径（正交路由 + 出入桩 + 同轴接入边 + 箭头样式），做到拖拽即所见即所得。
+     */
     private genPreviewOf;
     /** 把生成点位打包成创建上下文（from 为源点，to 为目标落点） */
     private genContext;
     onPointerDown(point: Vec2, event: PointerEvent): void;
     onPointerMove(point: Vec2, event: PointerEvent): void;
     onPointerUp(point: Vec2, _event: PointerEvent): void;
+    hasTransientState(): boolean;
+    /**
+     * 取消一切瞬态交互（拖拽/生成/框选/旋转/连线端点拖拽）并清掉画布上的瞬态预览。
+     * 触发场景：指针在窗口外松手丢失 pointerup、窗口失焦、点击画布外、无按压的移动、
+     * 切换工具、Esc。返回值用于让调用方决定是否需要重绘。
+     */
+    cancelTransient(): boolean;
     onKeyDown(event: KeyboardEvent): void;
     onKeyUp(_event: KeyboardEvent): void;
     /** 鼠标样式：伸缩手柄 → 对应方向的双向箭头；拖拽中 → 抓取 */
@@ -1448,13 +1553,20 @@ declare class SelectTool extends Tool {
     /** 生成点位命中阈值 / 单击 vs 拖动判定阈值 */
     private static readonly GEN_HIT_THRESHOLD;
     private static readonly CLICK_MOVE_THRESHOLD;
-    /** 收集选中图形上的全部生成点位（图形四边中点/快捷连线按钮） */
+    /** 支持四边连接锚点的图形类型（矩形类、流程图形、UML 等） */
+    private static readonly GEN_SUPPORTED_TYPES;
+    /**
+     * 收集图形上的全部生成点位（四边中点/快捷连线按钮）。
+     * extraShapeId：额外把某个图形（当前悬停的图形）纳入 —— 未选中图形也能直接连出连线。
+     */
     private computeGenPoints;
     /** 命中检测：指针是否落在某个生成点位附近（取最近的） */
     private hitGenPoint;
+    /** 悬停（未按下）时指针所在的、支持连线锚点的图形 id（已选中的交给选择手柄，返回 null） */
+    private findHoverAnchorShape;
     /** 生成点位预览的落点：拖动时跟随光标；静止/悬浮时向外延伸一个默认位置的框 */
     private genPreviewTarget;
-    /** 生成拖动：更新预览（线条 + 框）与目标高亮 */
+    /** 生成拖动：更新预览（真实样式的连线 + 待放置图形虚框）与目标高亮 */
     private handleGenerating;
     private handleRotating;
     /** 根据绑定信息返回目标图形的实际吸附点 */
@@ -1462,6 +1574,21 @@ declare class SelectTool extends Tool {
     private isPointInShape;
     private isPointInHexagon;
     private pointToLineDistance;
+    /**
+     * 待新建图形与源图形重叠时，把它沿「源→目标」方向推到不重叠（留一个引线距离）。
+     *
+     * 为什么必须做：图形重叠时，连线要接入的那条边会落在源图形内部/后方，
+     * 路由只能往回折（实测出现「往右拖一点点 → 一条往回折的钩子甚至横穿的怪线」），
+     * 而且新图形压着源图形本身就不好看。推开后接入边始终在出线方向的前方，
+     * 引线距离取 CONNECTION_LEAD(24)，正好让「出线桩 → 接入点」是一条直线。
+     */
+    private avoidSourceOverlap;
+    /**
+     * 预判「将要新建的图形」面向来线的那个接入点：
+     * 用该类型的真实默认尺寸 + 与 Editor.connectHandle 完全相同的 docking 规则算落点，
+     * 让「拖拽预览 → 松手后的浮动线条 → 插入后的真实连线」位置一致、不跳变。
+     */
+    private futureDockPoint;
     private getShapeBounds;
     private hitTestArrowTerminal;
     private findShapeNearPoint;

package/dist/index.d.ts

@@ -185,12 +185,24 @@ interface GenerationContext {
     sourceShapeId?: string;
     edge?: 'n' | 'e' | 's' | 'w';
 }
-/** 生成点位预览：从源点拖出的虚线线条 + 待放置图形轮廓 */
+/** 生成点位预览：与最终创建结果完全一致的连线预览（+ 待放置图形轮廓） */
 interface GenerationPreview {
     from: Vec2;
     to: Vec2;
     /** 待放置图形的类型；不提供（指向已有图形）时只画线条 */
     type?: ShapeType;
+    /** 源图形 id 与出线边：预览走与最终创建相同的「出线边同轴接入」路由 */
+    sourceShapeId?: string;
+    sourceEdge?: 'n' | 'e' | 's' | 'w';
+    /** 指向已有图形时的目标与绑定（预览即最终落点） */
+    targetShapeId?: string;
+    targetBinding?: ArrowBinding;
+    /** true = 拖拽中（按真实样式预览）；false/缺省 = 悬停（浅色虚线提示） */
+    dragging?: boolean;
+    /** 新建连线的默认样式，与最终创建保持一致 */
+    arrowStyle?: ArrowStyle;
+    /** 连线本身的颜色/粗细，与最终创建保持一致 */
+    lineStyle?: ShapeStyle;
 }
 /** 生成点位 → UI 菜单载荷：拖动到空白处后触发的"选择新图形"菜单 */
 interface GenerationMenuPayload {
@@ -803,6 +815,7 @@ declare class Editor {
     private snapGuides;
     private connectingTargetId;
     private genPreview;
+    private hoverAnchorShapeId;
     private eraserPoint;
     private mindMapEditingShapeId;
     private mindMapSelectedNode;
@@ -819,6 +832,23 @@ declare class Editor {
     private arrowStyle;
     constructor(canvas: HTMLCanvasElement, options?: EditorOptions);
     private setupEventListeners;
+    /** 窗口失焦（切页签/alt-tab）：按下状态与一切瞬态预览都作废，避免"卡住" */
+    private handleWindowBlur;
+    /**
+     * 在画布之外按下指针（工具栏、面板、页面空白）→ 立刻收尾残留交互。
+     * 用户预期是「点哪儿都能把残留的虚线清掉」，这里就是那根兜底绳。
+     * 若此时 pointerIsDown 仍是 true，说明上一轮的 pointerup 丢了（在窗口外松手），
+     * 一并把按下状态复位。
+     */
+    private handleGlobalPointerDown;
+    /**
+     * 当前是否存在「本该结束、却还留着」的瞬态交互。
+     * 注意：只认拖拽态（工具非空闲 / 目标高亮 / 对齐线 / 框选）——
+     * 悬停产生的锚点与悬停预览是常驻的合法状态，不能算残留，否则每次移动都会被打断。
+     */
+    private shouldRecoverTransient;
+    /** 收尾：让工具回到空闲态，并清空画布上的瞬态可视化 */
+    private cancelTransientInteraction;
     private handlePointerDown;
     private handlePointerMove;
     private handlePointerUp;
@@ -844,8 +874,16 @@ declare class Editor {
     /** 设置对齐参考线（由工具在拖拽过程中调用） */
     private setSnapGuides;
     private setConnectingTarget;
-    /** 设置生成点位预览（拖动/悬浮中显示的线条 + 待放置图形） */
+    /** 设置生成点位预览（拖动/悬浮中显示的连线 + 待放置图形虚框） */
     private setGenerationPreview;
+    /** 设置悬停图形（画布为其绘制四边连接锚点） */
+    private setHoverAnchorShape;
+    /**
+     * 清掉所有「瞬态」的交互可视化状态：连线预览、目标高亮、对齐参考线、框选、悬停锚点。
+     * 这些状态只在一次交互过程中有效 —— 只要交互结束（或事件丢失）就必须清空，
+     * 否则会残留虚线/虚框且越点越多。返回是否确有清理（供调用方决定是否重绘）。
+     */
+    private clearTransientPreview;
     /** 拖动到空白处松开 → 弹出"选择新图形"菜单（转发给 React UI） */
     private openGenerationMenu;
     private lineStyle;
@@ -853,10 +891,7 @@ declare class Editor {
     private computeSourceBinding;
     /**
      * 连线到达目标图形时，应吸附到目标面向来线的那个边。
-     * 关键规则：接入边与出线边「同轴」—— 从源图形左右边出线，就优先接目标的
-     * 左/右边（面向来线的一侧）；从上下边出线，就优先接目标的上/下边。
-     * 这样多条分支连线才能共用同一条正交主干总线（飞书式分叉），而不是各自
-     * 横着拐进目标的顶边、沿边缘爬进去。
+     * 规则唯一来源：`docking.ts` 的 pickDockSide（与出线边同轴，详见该文件注释）。
      */
     private connectHandle;
     /** 仅创建一条从源点引出、末端悬空的线条并选中它 */
@@ -1126,7 +1161,9 @@ declare class Renderer {
         nodeId: string;
     } | null, 
     /** 导出用：非 null 时先以该颜色铺满整块画布（白底等），默认不铺（透明） */
-    background?: string | null): void;
+    background?: string | null, 
+    /** 悬停的图形 id：为其绘制四边连接锚点（飞书式悬浮提示），已选中图形由选择手柄负责 */
+    hoverAnchorShapeId?: string | null): void;
     /** 橡皮擦：半透明主色圆 + 主色描边，半径与笔刷命中范围一致（屏幕像素恒定） */
     private drawEraserBrush;
     /** 连接进行中，高亮目标图形四边中点的可连锚点 */
@@ -1188,11 +1225,23 @@ declare class Renderer {
     private drawArrow;
     /** 选中连线 → 在线条上叠加一条高亮辅助线 */
     private drawLinearHighlight;
-    /** 生成点位预览：源点圆点 + 虚线线条 + 待放置图形轮廓 */
+    /**
+     * 生成点位预览：源点圆点 + 连线预览 + 待放置图形虚框。
+     *
+     * 关键：预览不再是「直线虚线」——它把待创建的连线合成为一条临时箭头，
+     * 直接走 drawArrow 的真实渲染路径（正交路由 / 垂直出入桩 / 出线边同轴接入 /
+     * 箭头头部 / 虚线样式全一致），因此拖拽时看到的就是松手后得到的样子。
+     * 拖拽中按真实样式绘制；悬停时降为半透明，保持「尚未确定」的观感。
+     */
     private drawGenerationPreview;
-    /** 待放置图形的虚线轮廓（按默认尺寸绘制对应类型） */
+    /** 待放置图形的虚线轮廓（按该类型的真实默认尺寸绘制） */
     private drawPreviewShapeOutline;
     private static readonly ALIGN_TOLERANCE;
+    /** 生成预览用的临时 id / 样式（不写入文档，仅本次绘制使用） */
+    private static readonly GEN_PREVIEW_ID;
+    private static readonly GEN_GHOST_ID;
+    /** 与 Editor.lineStyle() 一致：预览线用最终连线的真实颜色/粗细 */
+    private static readonly PREVIEW_LINE_STYLE;
     /**
      * 判断连线两端是否水平或垂直对齐（在容差内）。
      * 若在容差内，强制将坐标对齐（避免 grid snapping 导致无法形成直线）。
@@ -1214,10 +1263,25 @@ declare class Renderer {
     private generatePolylinePoints;
     /** 直角折线：与 polyline 使用相同的 H-V-H 正交路由，仅渲染方式（sharp）不同。 */
     private generateOrthogonalPoints;
+    /**
+     * 把折线末段掰到期望轴向（'H' 水平收尾 / 'V' 垂直收尾）。
+     * 绕行分支（A 星网格 / 退避）给出的路径末段方向不受控，这里在末点前补一个拐点，
+     * 保证箭头始终沿接入边法向插入（或沿出线方向收尾）。
+     */
+    private ensureFinalAxis;
     /** 去除连续重合点与共线点，精简冗余拐点 */
     private collapseLinePoints;
     /** 计算单段直角路由：优先无碰撞、且符合总线轴方向的 H-V-H / V-H-V 折线，必要时绕开障碍 */
     private computeOrthogonalRoute;
+    /**
+     * 剔除「把某个端点压在身下」的障碍。
+     *
+     * 这类障碍（典型：用户把图形拖到与另一张图形重叠）无法绕开 —— 端点的落点就在它里面，
+     * 与其避让只会让布线变成「绕着端点打转」的怪线，还会把 A* 的终点节点封死。
+     * 剔除后连线可以直穿重叠图形，观测上就是「叠在一起就随他叠」，
+     * 同时保证端点（点位）不会被自动挪走。
+     */
+    private dropObstaclesAtEndpoints;
     /**
      * 在停靠偏好对应的总线轴上，从源侧向外逐点平移总线位置，返回第一条「垂直方向和
      * 末段水平分支都避开所有中间障碍」的总线折线；找不到则返回 null。
@@ -1254,20 +1318,27 @@ declare class Renderer {
     private getTextBounds;
     private wrapLine;
     private truncateLine;
-    /** 连接点句柄 → 外法向（页面坐标单位向量） */
+    /** 连接点句柄 → 外法向（页面坐标单位向量；规则见 docking.ts） */
     private static readonly HANDLE_NORMALS;
     /**
-     * 自动接入边选择：与出线边「同轴」优先 —— 从源图形左右边出线就接目标的
-     * 左/右边（面向来线一侧），从上下边出线就接上/下边；这样分支连线才能共用
-     * 同一条正交主干总线，而不是横着拐进目标顶边。无出线方向信息时退回主方向规则。
+     * 自动接入边选择：与出线边「同轴」优先（规则唯一来源见 docking.ts）——
+     * 从源图形左右边出线就接目标的左/右边（面向来线一侧），从上下边出线就接上/下边；
+     * 这样分支连线才能共用同一条正交主干总线，而不是横着拐进目标顶边。
      */
     private pickAutoHandle;
     /** auto 绑定 → 按当前几何重选接入边；显式绑定原样返回 */
     private resolveAutoEndBinding;
     private getBindingPoint;
+    /**
+     * 求某一端的停靠法向。**优先用绑定信息**：绑定已经明确告诉我们是哪个图形的哪条边，
+     * 比几何猜测可靠得多 —— 当有图形与端点所在图形重叠时（典型：新建图形虚框压在源图形上），
+     * 纯几何的 getDockNormal 会挑到「离端点更近的另一张图形」，把出线/接入方向判反。
+     */
+    private resolveDockNormal;
     /**
      * 计算端点所在图形的外法向（垂直于该侧边缘，页面坐标单位向量）。
      * 用于连线垂直脱离/接入图形边缘，端点不在任何图形上时返回 undefined。
+     * preferShapeId：优先认这个图形（端点正好被多张图形覆盖时用它消歧）。
      */
     private getDockNormal;
     /**
@@ -1303,6 +1374,12 @@ declare class Renderer {
     private drawFreehand;
     private drawSelectionOutline;
     private drawSelectionHandles;
+    /**
+     * 四边中点的连接锚点（外圈 + 内点）。
+     * bounds 使用调用方的坐标系：选中手柄路径传入「本地包围盒」（画布已 translate 到图形中心），
+     * 悬停提示路径传入「世界包围盒」（画布未平移）。alpha 用于弱化悬停态。
+     */
+    private drawConnectionDots;
     /** 画旋转图标：顺时针短弧 + 箭头 */
     private drawRotateIcon;
     private getShapeBounds;
@@ -1354,6 +1431,10 @@ interface ToolContext {
     setSnapGuides(guides: SnapGuide[]): void;
     setConnectingTarget(id: string | null): void;
     setGenerationPreview(preview: GenerationPreview | null): void;
+    /** 悬停图形 → 画布为其绘制四边连接锚点（null 清除） */
+    setHoverAnchorShape(id: string | null): void;
+    /** 新建连线的线条样式（颜色/粗细），与最终创建的连线保持一致 */
+    getLineStyle(): ShapeStyle;
     /** 拖动到空白处：创建一条浮动线条并弹出"选择新图形"菜单 */
     openGenerationMenu(payload: GenerationMenuPayload): void;
     /** 创建"新图形 + 连线"；existingArrowId 存在时把线条末端接到新图形 */
@@ -1392,6 +1473,17 @@ declare abstract class Tool {
     abstract onKeyUp(event: KeyboardEvent): void;
     /** 返回当前指针位置应显示的鼠标样式，null 表示使用默认 */
     getCursor(_point: Vec2): string | null;
+    /**
+     * 是否正处于一次未结束的交互中（拖拽/生成/框选…）。
+     * 编辑器据此判断「指针没按下却仍有工具状态」= 丢事件，需要自愈。
+     */
+    hasTransientState(): boolean;
+    /**
+     * 取消一切「瞬态」交互状态（正在拖拽/生成/框选/旋转…），回到干净的空闲态。
+     * 用于指针事件丢失（在窗口外松手、失焦）、点击画布外、切换工具时的自愈。
+     * @returns 是否确实清理了状态（false = 本来就是空闲态，调用方可跳过重绘）
+     */
+    cancelTransient(): boolean;
     dispose(): void;
 }
 
@@ -1402,6 +1494,8 @@ declare class SelectTool extends Tool {
     private resizingState;
     private generatingState;
     private hoverGenPoint;
+    /** 悬停（未按下）的图形 id：为其显示四边连接锚点，可直接从这里拖出连线 */
+    private hoverShapeId;
     private rotatingState;
     private draggingArrowId;
     private draggingTerminal;
@@ -1410,12 +1504,23 @@ declare class SelectTool extends Tool {
     private brushShiftKey;
     /** 生成点位默认创建的图形类型：源图形若为可创建类型则同型，否则用矩形 */
     private defaultGenType;
+    /**
+     * 生成点位预览：带上源图形/出线边/目标绑定/线条样式，画布据此走「与最终创建完全一致」
+     * 的真实渲染路径（正交路由 + 出入桩 + 同轴接入边 + 箭头样式），做到拖拽即所见即所得。
+     */
     private genPreviewOf;
     /** 把生成点位打包成创建上下文（from 为源点，to 为目标落点） */
     private genContext;
     onPointerDown(point: Vec2, event: PointerEvent): void;
     onPointerMove(point: Vec2, event: PointerEvent): void;
     onPointerUp(point: Vec2, _event: PointerEvent): void;
+    hasTransientState(): boolean;
+    /**
+     * 取消一切瞬态交互（拖拽/生成/框选/旋转/连线端点拖拽）并清掉画布上的瞬态预览。
+     * 触发场景：指针在窗口外松手丢失 pointerup、窗口失焦、点击画布外、无按压的移动、
+     * 切换工具、Esc。返回值用于让调用方决定是否需要重绘。
+     */
+    cancelTransient(): boolean;
     onKeyDown(event: KeyboardEvent): void;
     onKeyUp(_event: KeyboardEvent): void;
     /** 鼠标样式：伸缩手柄 → 对应方向的双向箭头；拖拽中 → 抓取 */
@@ -1448,13 +1553,20 @@ declare class SelectTool extends Tool {
     /** 生成点位命中阈值 / 单击 vs 拖动判定阈值 */
     private static readonly GEN_HIT_THRESHOLD;
     private static readonly CLICK_MOVE_THRESHOLD;
-    /** 收集选中图形上的全部生成点位（图形四边中点/快捷连线按钮） */
+    /** 支持四边连接锚点的图形类型（矩形类、流程图形、UML 等） */
+    private static readonly GEN_SUPPORTED_TYPES;
+    /**
+     * 收集图形上的全部生成点位（四边中点/快捷连线按钮）。
+     * extraShapeId：额外把某个图形（当前悬停的图形）纳入 —— 未选中图形也能直接连出连线。
+     */
     private computeGenPoints;
     /** 命中检测：指针是否落在某个生成点位附近（取最近的） */
     private hitGenPoint;
+    /** 悬停（未按下）时指针所在的、支持连线锚点的图形 id（已选中的交给选择手柄，返回 null） */
+    private findHoverAnchorShape;
     /** 生成点位预览的落点：拖动时跟随光标；静止/悬浮时向外延伸一个默认位置的框 */
     private genPreviewTarget;
-    /** 生成拖动：更新预览（线条 + 框）与目标高亮 */
+    /** 生成拖动：更新预览（真实样式的连线 + 待放置图形虚框）与目标高亮 */
     private handleGenerating;
     private handleRotating;
     /** 根据绑定信息返回目标图形的实际吸附点 */
@@ -1462,6 +1574,21 @@ declare class SelectTool extends Tool {
     private isPointInShape;
     private isPointInHexagon;
     private pointToLineDistance;
+    /**
+     * 待新建图形与源图形重叠时，把它沿「源→目标」方向推到不重叠（留一个引线距离）。
+     *
+     * 为什么必须做：图形重叠时，连线要接入的那条边会落在源图形内部/后方，
+     * 路由只能往回折（实测出现「往右拖一点点 → 一条往回折的钩子甚至横穿的怪线」），
+     * 而且新图形压着源图形本身就不好看。推开后接入边始终在出线方向的前方，
+     * 引线距离取 CONNECTION_LEAD(24)，正好让「出线桩 → 接入点」是一条直线。
+     */
+    private avoidSourceOverlap;
+    /**
+     * 预判「将要新建的图形」面向来线的那个接入点：
+     * 用该类型的真实默认尺寸 + 与 Editor.connectHandle 完全相同的 docking 规则算落点，
+     * 让「拖拽预览 → 松手后的浮动线条 → 插入后的真实连线」位置一致、不跳变。
+     */
+    private futureDockPoint;
     private getShapeBounds;
     private hitTestArrowTerminal;
     private findShapeNearPoint;