drawui-core 0.5.2 → 0.6.0

package/dist/index.d.ts

@@ -80,6 +80,13 @@ interface HexagonShape extends BaseShape {
     type: 'hexagon';
     width: number;
     height: number;
+    /**
+     * 六边形朝向（缺省 `'pointy'`，老文档行为不变）：
+     * - `'pointy'`：上下为尖、左右为竖边（原行为）
+     * - `'flat'`：上下为平边、左右为尖 —— 蜂窝图要用这个，
+     *   它的六个邻居正好落在 30°/90°/150°/210°/270°/330°，上下左右都能拼上。
+     */
+    orientation?: 'pointy' | 'flat';
 }
 interface ParallelogramShape extends BaseShape {
     type: 'parallelogram';
@@ -90,6 +97,13 @@ interface TrapezoidShape extends BaseShape {
     type: 'trapezoid';
     width: number;
     height: number;
+    /**
+     * 上边每侧内缩的距离（页面单位）。缺省 = `width * 0.15`（老文档行为不变）。
+     *
+     * 用来堆金字塔：每层给出精确的缩进量，侧边才能连成**同一条斜线**；
+     * 靠默认的 15% 比例会让每层斜率各不相同，堆起来像歪的楼梯。
+     */
+    topInset?: number;
 }
 interface PentagonShape extends BaseShape {
     type: 'pentagon';
@@ -239,6 +253,10 @@ interface LineShape extends BaseShape {
         start: Vec2;
         end: Vec2;
     };
+    /** 手工艺状态的自动走线基线（见 ArrowShape.userPointsBase） */
+    userPointsBase?: Vec2[];
+    /** 纯装饰线（见 ArrowShape.freeform） */
+    freeform?: boolean;
 }
 type ConnectionType = 'straight' | 'polyline' | 'orthogonal' | 'curve';
 /** 生成点位创建上下文：from 为源点(生成点位)，to 为目标落点 */
@@ -328,6 +346,22 @@ interface ArrowShape extends BaseShape {
         start: Vec2;
         end: Vec2;
     };
+    /**
+     * 写下手工艺状态那一刻的**自动走线**（世界坐标，含两端）。
+     *
+     * 只用来判断手工折点是否已经过期：自动走线的形状签名（折点数 + 首末段轴向）只由布局决定，
+     * 一旦当前自动走线的签名和这里记的不一样，说明「当初为了绕开什么而折」的前提没了 ——
+     * 这时折点只会让线凭空多绕一圈（见 connectorEdit.userPointsAreStale）。
+     */
+    userPointsBase?: Vec2[];
+    /**
+     * 纯装饰线/箭头：**不把端点吸附到附近图形的轮廓上**。
+     *
+     * 模板里的分隔线、网格线、肋骨、标注线往往是**故意画在容器图形内部**的；
+     * 默认的「端点落进图形就吸到轮廓」会把它们拽到容器边上（画布上看是"线自己跑了"），
+     * 而且导出侧从不做这个吸附 → 画布与导出还会对不上。
+     */
+    freeform?: boolean;
 }
 interface TextShape extends BaseShape {
     type: 'text';
@@ -673,11 +707,11 @@ declare const zhCN: {
     readonly 'toolbar.grid': "网格";
     readonly 'toolbar.undo': "撤销 (Ctrl+Z)";
     readonly 'toolbar.redo': "重做 (Ctrl+Shift+Z)";
-    readonly 'toolbar.arrow': "箭头";
-    readonly 'toolbar.text': "文本";
+    readonly 'toolbar.arrow': "箭头 (A)";
+    readonly 'toolbar.text': "文本 (T)";
     readonly 'toolbar.pen': "画笔";
     readonly 'toolbar.highlighter': "荧光笔";
-    readonly 'toolbar.eraser': "橡皮擦";
+    readonly 'toolbar.eraser': "橡皮擦 (E)";
     readonly 'toolbar.uml-class': "UML 类图";
     readonly 'toolbar.uml-interface': "UML 接口";
     readonly 'zoom.in': "放大";
@@ -698,7 +732,7 @@ declare const zhCN: {
     readonly 'style.solid': "实线";
     readonly 'style.opacity': "不透明度";
     readonly 'style.connection.straight': "直线";
-    readonly 'style.connection.polyline': "折线";
+    readonly 'style.connection.polyline': "圆角折线";
     readonly 'style.connection.orthogonal': "直角折线";
     readonly 'style.connection.curve': "曲线";
     readonly 'style.arrowhead.none': "无箭头";
@@ -788,7 +822,6 @@ declare const zhCN: {
     readonly 'table.insertColRight': "在右侧插入列";
     readonly 'table.pickHint': "拖选行列数";
     readonly 'ctx.copy': "复制";
-    readonly 'ctx.copyAsImage': "复制为图片";
     readonly 'ctx.paste': "粘贴";
     readonly 'ctx.duplicate': "创建副本";
     readonly 'ctx.layer': "层级";
@@ -806,8 +839,13 @@ declare const zhCN: {
     readonly 'ctx.ungroup': "解组";
     readonly 'ctx.lock': "锁定";
     readonly 'ctx.unlock': "解锁";
+    readonly 'ctx.unlockAll': "全部解锁";
     readonly 'ctx.delete': "删除";
-    readonly 'toolbar.icon': "图标";
+    readonly 'toolbar.icon': "图标 (S)";
+    readonly 'toolbar.template': "模板";
+    readonly 'template.search': "搜索模板";
+    readonly 'template.all': "全部";
+    readonly 'template.empty': "没有匹配的模板";
     readonly 'toolbar.image': "图片";
     readonly 'toolbar.more': "更多";
     readonly 'toolbar.pageTheme': "页面主题";
@@ -835,6 +873,7 @@ declare const zhCN: {
     readonly 'iconCat.arrow': "箭头方向";
     readonly 'iconCat.misc': "常用";
     readonly 'iconCat.emoji': "表情";
+    readonly 'iconCat.sticker': "贴纸";
     readonly 'iconCat.device': "电脑设备";
     readonly 'iconCat.weather': "天气";
     readonly 'iconCat.transport': "交通";
@@ -859,12 +898,24 @@ declare function t(key: MessageKey, params?: Record<string, string | number>): s
 
 type ExportFormat = 'png' | 'svg' | 'pdf';
 interface ExportOptions {
-    /** 输出缩放倍数（仅位图 PNG 生效，默认 2，矢量 SVG 始终无损） */
+    /**
+     * 输出缩放倍数（仅位图 PNG 生效，默认 2，矢量 SVG 始终无损）。
+     * 语义：内容 1 个页面单位 → 输出 scale 个设备像素（就是最终图与内容的尺寸比）。
+     */
     scale?: number;
     /** 内容四周留白（页面坐标，默认 24） */
     padding?: number;
     /** 背景色，null = 透明；不传默认白色（'#ffffff'） */
     background?: string | null;
+    /**
+     * 输出最长边的像素上限（默认不限制）。超过时按比例压低 scale，**保证整幅内容完整、不裁切**。
+     *
+     * 缩略图 / 预览图这类"显示尺寸远小于内容尺寸"的场景务必传：
+     * 内容跨度大时（把一个图形拖到几千像素外）输出画布面积会平方增长，
+     * 不仅编码要几百毫秒，还会触及浏览器 canvas 面积上限（Chrome 约 16384×16384，
+     * 约 2.68 亿像素 / 1GB），超限后 toDataURL 直接返回 `data:,` —— 图变空白。
+     */
+    maxSize?: number;
 }
 /** 计算所有图形的并集包围盒（含留白），用于导出画布尺寸与视口 */
 declare function getContentBounds(shapes: Shape[], padding?: number): {
@@ -1066,7 +1117,20 @@ declare class Editor {
     private genPreview;
     private hoverAnchorShapeId;
     private hoverConnectorId;
+    /**
+     * 悬停中的**锁定**图形：锁标记不再常驻（一屏三把锁比锁本身更吵），
+     * 只在指针落在这个锁定图形上时才亮出来 —— 顺带告诉用户「它为什么点不动」，
+     * 而且那枚锁是可以直接点开解锁的（见 pointerdown 里的锁徽标命中）。
+     */
+    private hoverLockedShapeId;
     private eraserPoint;
+    /**
+     * 橡皮擦「渐隐」中的图形：id → 开始时间戳。
+     * 命中后不立刻从 shapes 里删掉，而是先让不透明度在 ERASE_FADE_MS 内降到 0，
+     * 到点再真正移除（这样擦除是「变浅 → 消失」而不是「啪一下不见」）。
+     */
+    private eraseFades;
+    private eraseFadeRaf;
     private mindMapEditingShapeId;
     private mindMapSelectedNode;
     private mindMapHoverNode;
@@ -1147,6 +1211,17 @@ declare class Editor {
     private handlePointerUp;
     /** 根据当前工具的命中结果更新鼠标样式（伸缩手柄↔/↕、拖拽 grabbing 等） */
     private updateCursor;
+    /**
+     * 锁定图形的悬停跟踪：只有悬停中的锁定图形才亮出锁徽标（默认不画，见 Renderer.visibleLockBadges）。
+     *
+     * 除了"指针在图形上"，还要认"指针在锁徽标上" —— 徽标压在包围盒外侧，
+     * 指针移过去的瞬间已经离开了图形本身，不认就会闪掉、点不到。
+     */
+    private updateLockHover;
+    /** 命中「锁徽标」（世界坐标点）；返回要解锁的目标。命中范围比视觉上略大一圈，好点 */
+    private lockBadgeAtPoint;
+    /** 点锁徽标 → 解锁（组锁整组解），一步撤销 */
+    private unlockFromBadge;
     /**
      * 滚轮：普通滚动平移视口（内容跟随常规滚动方向），
      * Ctrl/Cmd + 滚轮以光标为中心缩放，Shift + 滚轮水平平移。
@@ -1156,7 +1231,24 @@ declare class Editor {
     private handleKeyUp;
     private handleResize;
     private screenToPage;
+    /**
+     * 插入一组图形（模板库的落地入口）。
+     *
+     * - 模板坐标是「相对自己的中心」，这里整体平移到**当前视口中心**，插到用户正在看的地方；
+     * - 整批插入只打**一个**历史快照，撤销一次就整块拿掉；
+     * - 插入后自动选中这批图形，用户可以直接拖动/改样式；
+     * - 连线要平移 `points`（`shape.x/y` 对连线只是渲染原点，平移它视觉上不动）。
+     */
+    insertTemplate(shapes: Shape[]): void;
     private addShape;
+    /**
+     * 文档里出现了「大目录」里的图标（表情/贴纸/补充图标）就把它拉回来，回来后重绘一次。
+     *
+     * 图标目录是懒加载的：首包只带手绘线稿那部分。打开一份含表情的文档时，
+     * 第一次渲染会短暂缺图 —— 这里补一次加载，加载完 requestRender 补画上。
+     * 全部图标都在首包时 `ensureIcons` 是纯同步空转，不会产生任何网络请求。
+     */
+    private prefetchShapeIcons;
     private updateShape;
     /**
      * 表格尺寸变化时保持「左上角」不动：行高变化向下伸缩、列宽变化向右伸缩，
@@ -1170,6 +1262,20 @@ declare class Editor {
     private updateBoundArrows;
     private getBindingPosition;
     private deleteShape;
+    /**
+     * 橡皮擦命中：图形先进入「渐隐」再被真正删除（见 eraseFades）。
+     * 历史快照在拖拽开始时已经打过，所以整段擦除仍然只占一个撤销点。
+     */
+    private eraseShape;
+    /** 渐隐时钟：每帧推进，到点的图形才真正删除；整批结束后停表 */
+    private tickEraseFade;
+    /** 当前帧各渐隐图形的不透明度（0~1）；没有渐隐时返回 undefined，避免每帧建 Map */
+    private eraseFadeMap;
+    /**
+     * 丢弃所有未完成的渐隐（撤销 / 重做 / 整体换数据时调用）。
+     * 否则「撤销把图形救回来 → 渐隐计时器到点又把它删掉」会凭空吃掉一次撤销。
+     */
+    private clearEraseFades;
     /**
      * 选中图形（additive=true 时切换选中态）；id 为空串清空选中。右键菜单/外部控制用。
      * ⚠️ 组感知：点任一成员都会选中它所属的整组（同组的绑行为一致），additive 时整组一起加减。
@@ -1177,6 +1283,15 @@ declare class Editor {
     selectShape(id: string, additive: boolean): void;
     /** 整体替换选中集（右键菜单/外部控制用）；框选结果同样按组扩张 */
     selectShapes(ids: string[]): void;
+    /**
+     * 全选（Ctrl/Cmd + A）：选中画布上所有图形。
+     *
+     * 锁定图形**跳过** —— 它们本来就不接受选中（点不中、拖不动），
+     * 混进选区只会让「删除/移动/改样式」这些操作对它们做无用功，
+     * 还会让状态栏的「已选 N 个」数字对不上能操作的图形数。
+     * 要处理锁定的图形，先解锁（悬停点锁 / 右键解锁 / 空白右键「全部解锁」）。
+     */
+    selectAll(): boolean;
     /** 某图形所在的整组 id 列表（不在组里就只有它自己） */
     private getGroupMembers;
     /** 选中集是否恰好是完整的一个组（返回 groupId，否则 null） */
@@ -1312,6 +1427,14 @@ declare class Editor {
     setShapeLocked(id: string, locked: boolean): boolean;
     /** 某个图形是否被锁定 */
     isShapeLocked(id: string): boolean;
+    /** 画布上是否存在锁定图形（右键菜单决定要不要显示「全部解锁」） */
+    hasLockedShapes(): boolean;
+    /**
+     * 全部解锁（一步撤销）。
+     * 兜底入口：锁定的图形点不中、框选也框不中，如果用户忘了自己锁过什么、
+     * 或者锁的量比较多，挨个悬停点锁太麻烦 —— 空白处右键就能一次清掉。
+     */
+    unlockAll(): boolean;
     /** 置于顶层：选中的图形整体移到最上面（保持它们之间的相对顺序） */
     bringToFront(): boolean;
     /** 置于底层：选中的图形整体移到最下面 */
@@ -1774,6 +1897,8 @@ declare class Editor {
     private getShapeScreenBounds;
     getShapeAtScreenPoint(screenPoint: Vec2): Shape | null;
     getShapeAtPoint(point: Vec2, excludeId?: string): Shape | null;
+    /** 点是否落在连线的**实际走线**上（与画面一致：含出/入桩、绕行、手工折点） */
+    private isPointOnConnector;
     /** 橡皮擦：返回与圆形笔刷相交的所有图形（不含线条的命中由其线段距离判定） */
     getShapesInBrushRadius(point: Vec2, radius: number): Shape[];
     private shapeIntersectsBrush;
@@ -1877,6 +2002,19 @@ interface SnapGuide {
     start: number;
     end: number;
 }
+/** 一枚锁徽标（世界坐标矩形 + 点击它要解锁的目标）—— 绘制与命中共用 */
+interface LockBadgeTarget {
+    x: number;
+    y: number;
+    /** 边长（屏幕 20px 换算到世界单位） */
+    size: number;
+    /** 单图形锁定：解锁它本身 */
+    shapeId?: string;
+    /** 组锁定：解锁整组 */
+    groupId?: string;
+    /** 组锁的所有成员 id（用于判断"悬停/选中是否在这个组上"） */
+    memberIds: string[];
+}
 declare class Renderer {
     private ctx;
     private width;
@@ -1901,6 +2039,11 @@ declare class Renderer {
     } | null): void;
     /** 当前悬停的图形 id（由每帧 render 写入），仅用于表格拖动把手等提示性绘制 */
     private hoverShapeId;
+    /**
+     * 本帧是否是「多选」（选中集 > 1）。多选时每个图形只描发丝轮廓、不再画手柄，
+     * 手柄收敛到整体范围框上（见 drawMultiSelectionBounds）。
+     */
+    private multiSelection;
     private static readonly TEXT_CACHE_LIMIT;
     constructor(canvas: HTMLCanvasElement, dpr?: number);
     resize(width: number, height: number): void;
@@ -1930,7 +2073,9 @@ declare class Renderer {
     /** 悬停的图形 id：为其绘制四边连接锚点（飞书式悬浮提示），已选中图形由选择手柄负责 */
     hoverAnchorShapeId?: string | null, 
     /** 悬停的连线 id：整条线描一层浅蓝高亮（提示「这条线可点、点开能调线段」） */
-    hoverConnectorId?: string | null): void;
+    hoverConnectorId?: string | null, 
+    /** 橡皮擦渐隐：图形 id → 不透明度（0~1）。缺省时不改任何图形的透明度 */
+    eraseFade?: Map<string, number> | null): void;
     /** 橡皮擦：半透明主色圆 + 主色描边，半径与笔刷命中范围一致（屏幕像素恒定） */
     private drawEraserBrush;
     /** 连接进行中，高亮目标图形四边中点的可连锚点 */
@@ -2052,6 +2197,14 @@ declare class Renderer {
     getConnectorRoute(shape: Shape, shapeMap: Map<string, Shape>, options?: {
         ignoreUserPoints?: boolean;
     }): Vec2[];
+    /**
+     * 连线最终走线（世界坐标）+ 生效的连线类型 —— **绘制、命中、导出判定都走这里**。
+     *
+     * 手工折点会先过一道「过期检查」（connectorEdit.userPointsAreStale）：
+     * 走线压到自己连的图形、或者布局已经变到自动走线的形状都不一样了，就丢弃手工折点。
+     * 这样「旧布局下绕出来的大回环」不会跟着图形被带进新布局，默认永远是最少突兀的那条线。
+     */
+    private connectorWorldPath;
     /**
      * 选中连线时：在每段（够长的）线段中点画一个可拖动的小手柄（飞书式「拖线段调位置」）。
      * 拖动交互在 SelectTool 的 'dragging-segment' 状态里。
@@ -2194,16 +2347,22 @@ declare class Renderer {
     private drawText;
     private drawFreehand;
     /**
-     * 锁定标记：图形右上角画一枚小挂锁（尺寸按屏幕像素恒定），
-     * 独立于选中态 —— 锁定的图形通常选不中，得靠这枚锁告诉用户「它为什么点不动」。
-     */
-    private drawLockBadge;
-    /**
-     * 锁定组的统一标记：整组只画**一把锁**，挂在组包围盒顶部居中，
-     * 而不是组里每个成员各挂一把（一堆锁没法看）。只要组处于锁定状态就画，
-     * 与选中无关（锁定的组本来也选不中，这枚锁就是唯一的视觉提示）。
-     */
-    private drawGroupLockBadges;
+     * 当前**可见**的锁标记（世界坐标矩形 + 解锁目标）。
+     *
+     * 绘制与「点锁解锁」的命中共用这一份 —— 看到哪就能点到哪，不会出现"看不见却能点"。
+     *
+     * 为什么不再给每个锁定图形常驻画一把锁：一条流程图里锁三个图形就冒出三把锁，
+     * 满屏徽标比锁本身更干扰。现在只在**需要解释的时候**出现：
+     * 指针悬停在这个锁定图形上，或它刚被右键选中（右键是选中锁定图形的入口）。
+     * 组锁仍然整组一把（挂在组包围盒顶部居中），条件同上：悬停/选中任一成员。
+     */
+    visibleLockBadges(shapes: Shape[], selectedIds: Set<string>, zoom: number): LockBadgeTarget[];
+    /** 所有「锁定图形」的徽标位置（不考虑是否显示）—— 命中测试与悬停判定用 */
+    lockBadgeTargets(shapes: Shape[], zoom: number): LockBadgeTarget[];
+    private allLockBadges;
+    /** 悬停的锁定图形 id（由 Editor 在指针移动时写入）：只有它才会亮出锁徽标 */
+    private lockHoverId;
+    setLockHover(id: string | null): void;
     /** 在指定位置（徽标左上角，世界坐标）画一枚挂锁徽标 */
     private drawLockBadgeAt;
     /**
@@ -2211,6 +2370,13 @@ declare class Renderer {
      * 提示「这些图形是绑在一起的」。整组锁定的成员画不到（成员不可选），不需要外框。
      */
     private drawGroupFrames;
+    /**
+     * 多选时每个图形的「发丝轮廓」：1px、不填充、不画任何手柄。
+     * 目的是告诉用户「这个也在选区里」，而不是喧宾夺主。
+     */
+    private drawMultiSelectOutline;
+    /** 多选的整体范围框：一个蓝框圈住全部选中图形（不带手柄） */
+    private drawMultiSelectionBounds;
     private drawSelectionOutline;
     private drawSelectionHandles;
     /**
@@ -2286,7 +2452,7 @@ declare const ICON_CATEGORIES: {
     id: IconCategoryId;
     labelKey: MessageKey;
 }[];
-type IconCategoryId = 'status' | 'number' | 'emoji' | 'device' | 'tech' | 'chart' | 'office' | 'media' | 'arrow' | 'misc' | 'weather' | 'transport' | 'nature' | 'building' | 'medical' | 'shopping' | 'science' | 'animal' | 'time' | 'edit' | 'food' | 'communication';
+type IconCategoryId = 'status' | 'number' | 'emoji' | 'sticker' | 'device' | 'tech' | 'chart' | 'office' | 'media' | 'arrow' | 'misc' | 'weather' | 'transport' | 'nature' | 'building' | 'medical' | 'shopping' | 'science' | 'animal' | 'time' | 'edit' | 'food' | 'communication';
 interface IconLayer {
     /** 24×24 网格内的路径（语法同 SVG path，统一大写指令） */
     d: string;
@@ -2323,6 +2489,20 @@ interface IconDef {
     };
 }
 declare const ICONS: IconDef[];
+/** 大目录是否已并入（同步查询） */
+declare function isIconCatalogLoaded(): boolean;
+/**
+ * 加载大目录。可重复调用（共享同一个 Promise）；失败会重置状态，允许下次重试。
+ * 宿主一般不用直接调 —— 图标面板与 `Editor` 会自动触发。
+ */
+declare function loadIconCatalog(): Promise<void>;
+/**
+ * 预取一批图标（通常是文档里出现过的 iconId）。
+ *
+ * 全部已在首包里时**不会触发任何加载**，所以「没有表情/贴纸」的文档完全不受影响；
+ * 只要有一个不认识，就说明文档用了大目录里的图标，此时整份目录拉一次（浏览器会缓存）。
+ */
+declare function ensureIcons(ids: Iterable<string>): Promise<void>;
 declare function getIcon(id: string): IconDef | undefined;
 /** 存在该 id 的图标（写入图形/读文档时校验，避免引用到不存在的图标） */
 declare function hasIcon(id: string): boolean;
@@ -2349,6 +2529,39 @@ declare const ICON_CATEGORY_INK: Record<IconCategoryId, string>;
 /** 取某个图标的默认墨色：图标自带 ink 优先（全彩贴纸），否则用分类主色，最后退回全局默认 */
 declare function iconInk(icon: IconDef): string;
 
+/**
+ * 内置模板库（数据层，不含 UI）。
+ *
+ * 设计约定（每一条都踩过坑）：
+ * - `build()` **现场生成**图形，不共享可变数组 —— 否则插两次会复用同一批 id。
+ * - 坐标是**相对模板中心**的，插入时整体平移到视口中心；`x/y` 是**图形中心**。
+ * - **连线段必须绑定到图形**（`startBinding`/`endBinding`）。不绑的话拖动盒子线不动，
+ *   整个模板当场散架。走线交给路由算法（同一侧引出的多条线会自动共用主干）。
+ * - 一个视觉整体由多个图形拼成时（表头+字段行、卡片+按钮），用 `groupId` 绑成组，
+ *   拖动才会整块走。
+ * - 想要「只有字、没有框」必须用 `type: 'text'`：`strokeWidth: 0` 并不会去掉矩形边框。
+ * - 想加模板：往 `TEMPLATES` 里加一项，UI 与搜索会自动带上。
+ */
+type TemplateCategoryId = 'flow' | 'org' | 'analysis' | 'plan' | 'uml' | 'tech';
+declare const TEMPLATE_CATEGORIES: {
+    id: TemplateCategoryId;
+    zh: string;
+    en: string;
+}[];
+interface TemplateDef {
+    id: string;
+    cat: TemplateCategoryId;
+    zh: string;
+    en: string;
+    /** 搜索关键词（中英混排，空格分词） */
+    kw: string;
+    build: () => Shape[];
+}
+declare const TEMPLATES: TemplateDef[];
+declare function templateById(id: string): TemplateDef | undefined;
+/** 搜索模板：中/英文名 + 关键词，空格分词全部命中 */
+declare function searchTemplates(query: string): TemplateDef[];
+
 /**
  * 画板范围（Board Extent）—— 宿主用来决定「画板这块 DOM / 可滚区域该多大」。
  *
@@ -2423,8 +2636,16 @@ interface ToolContext {
     addShape(shape: Shape): void;
     updateShape(id: string, updates: Partial<Shape>): void;
     deleteShape(id: string): void;
+    /** 橡皮擦专用：先渐隐再删除（普通删除请用 deleteShape） */
+    eraseShape(id: string): void;
     selectShape(id: string, additive: boolean): void;
     selectShapes(ids: string[]): void;
+    /**
+     * 绕过「组扩张」直接只选这一个图形。
+     * 用于「点第二次进入组」：组已经被整组选中时，再点某个成员就把它单独选出来
+     * （否则组内成员永远只能整组操作，改一个标签得先解组）。
+     */
+    selectShapeRaw(id: string): void;
     getShapes(): Shape[];
     getSelectedIds(): string[];
     setActiveTool(tool: ToolType): void;
@@ -2560,6 +2781,11 @@ declare class SelectTool extends Tool {
     /** 把生成点位打包成创建上下文（from 为源点，to 为目标落点） */
     private genContext;
     onPointerDown(point: Vec2, event: PointerEvent): void;
+    /**
+     * 是否已经「进入」了 shape 所在的组：当前选区非空，且是这一组**严格子集**的成员。
+     * 用于「组内逐成员切换」—— 进了组以后点同组其他成员不再整组扩张。
+     */
+    private isInsideGroup;
     /**
      * 命中「表格左上角拖动把手」的表格。把手画在表格包围盒之外、普通 hitTest 命中不到，
      * 所以这里单独判定；落点上若有别的图形则不抢（避免盖住别人的点击）。
@@ -2607,6 +2833,10 @@ declare class SelectTool extends Tool {
      *
      * 另外还要丢掉「其实属于自动走线的折点」（两端出/入桩的拐角，见 pruneStubBends）：
      * 它们是自动生成的，冻进 userPoints 后会让之后移动图形时端点旁长出小钩子。
+     *
+     * 同时记下 `userPointsBase`（这一刻的自动走线）：之后布局一变（自动走线的形状签名变了），
+     * 这些折点就按「过期」处理，连线自动回到当前布局下最简单的走线 —— 否则旧布局下
+     * 绕出来的大回环会被一路带到新布局里，看着就像凭空多出一圈。
      */
     private writeConnectorRoute;
     /**
@@ -2659,6 +2889,11 @@ declare class SelectTool extends Tool {
     /** 生成点位命中阈值 / 单击 vs 拖动判定阈值 */
     private static readonly GEN_HIT_THRESHOLD;
     private static readonly CLICK_MOVE_THRESHOLD;
+    /**
+     * 拖动起始阈值：小于这个距离的移动不生效。
+     * 点击时鼠标/触控板的抖动（1~2px）以前会把图形真的挪动一点 —— 看着像"点一下就偏了"。
+     */
+    private static readonly DRAG_START_THRESHOLD;
     /**
      * 「点击锚点生成图形」时源图形与新图形之间的默认间距（页面单位，**边到边**）。
      * 旧实现是「中心沿法线外移 96」：对默认矩形(120×60)实际边距只有 36，看着太挤；
@@ -3098,4 +3333,4 @@ declare function imageDataUrl(src: string): string | null;
 /** 清空缓存（测试/卸载时用；会释放自己创建的 blob 地址） */
 declare function clearImageCache(): void;
 
-export { type ArrowBinding, type ArrowHeadType, type ArrowShape, type ArrowStyle, ArrowTool, BoardExtentKeeper, type BoardExtentResult, type BoardExtentUpdate, Camera, type CameraState, type CircleShape, type ConnectionType, DEFAULT_HIGHLIGHTER_COLOR, DEFAULT_IMAGE_MAX_SIZE_BYTES, DEFAULT_PAGE_THEME, type DiamondShape, type DrawShape, type DrawuiTheme, type DrawuiThemeSelection, Editor, type EditorData, type EditorOptions, type EditorState, type EllipseShape, type ExportFormat, type ExportOptions, type FreehandMode, FreehandTool, type GenerationContext, HandTool, type HexagonShape, ICONS, ICON_CATEGORIES, ICON_CATEGORY_INK, ICON_DEFAULT_INK, ICON_DEFAULT_SIZE, ICON_GRID, type IconCategoryId, type IconDef, type IconLayer, type IconShape, type ImageShape, type ImageUploadConfig, type ImageUploadOption, type ImageUploader, LANGUAGES, type Language, type LineShape, LineTool, MINDMAP_COLORS, MINDMAP_DIRECTIONS, MINDMAP_FONT_SIZE, MINDMAP_HANDLE_HIT_RADIUS, MINDMAP_HANDLE_RADIUS, MINDMAP_MAX_WIDTH, MINDMAP_MIN_WIDTH, MINDMAP_NODE_HEIGHT, MIN_HANDLE_SEGMENT, MIN_JOG, Mat2d, type MessageKey, type MindMapDirection, type MindMapHandleKind, type MindMapHandlePos, type MindMapLayoutResult, type MindMapNode, type MindMapNodePos, type MindMapShape, type OctagonShape, PAGE_THEMES, type PageTheme, type PageThemePreset, type ParallelogramShape, type PentagonShape, type Rect, type RectangleShape, Renderer, type RoundedRectangleShape, STICKY_FOLD_RATIO, STICKY_NOTE_COLORS, STICKY_NOTE_DEFAULT_COLOR, STICKY_TEXT_SCALE, type SegmentHandle, SelectTool, type Shape, type ShapeStyle, ShapeTool, type ShapeType, type SnapGuide, type StarShape, type StickyNoteShape, TABLE_CELL_PADDING_X, TABLE_CELL_PADDING_Y, TABLE_DEFAULT_COL_WIDTH, TABLE_DEFAULT_ROW_HEIGHT, TABLE_FONT_SIZE, TABLE_HEADER_FILL, TABLE_LINE_HEIGHT_RATIO, TABLE_MAX_AUTO_LINES, TABLE_MIN_COL_WIDTH, TABLE_MIN_ROW_HEIGHT, TABLE_MOVE_HANDLE_GAP, TABLE_MOVE_HANDLE_HEIGHT, TABLE_MOVE_HANDLE_WIDTH, THEME, type TableCell, type TableShape, type TextShape, type ToolType, type TrapezoidShape, type TriangleShape, UML_FONT_SIZE, UML_HEADER_HEIGHT, UML_LINE_HEIGHT, UML_MIN_WIDTH, UML_PADDING_X, UML_PADDING_Y, type UiEvent, type UmlAttribute, type UmlClassShape, type UmlInterfaceShape, type UmlMethod, type UmlVisibility, Vec, type Vec2 as Vec2Type, addImageReadyListener, calcUmlClassSize, clearImageCache, cloneMindMapNode, cloneTable, cloneTableCells, collapseRoute, collectTemporaryImageSrcs, connectorSegmentHandles, countMindMapNodes, createTableCells, downloadBlob, effectiveDirection, ensureImagesLoaded, exportToBlob, findMindMapNode, getContentBounds, getIcon, getLanguage, getMindMapNodeDepth, getMindMapNodeSiblings, getMindMapParent, getTheme, hasIcon, hexToRgba, hitTableBody, hitTableMoveHandle, iconInk, iconsByCategory, imageDataUrl, isEmptyRect, isFlippableShapeType, isHorizontalDirection, isImageFailed, isImageLoading, isStubCorner, isUploaderFunction, layoutMindMap, loadImage, mindMapHandleAtLocalPoint, mindMapNodeColor, mindMapNodeHandles, mindMapNodeSize, moveMindMapNodeInTree, offsetConnectorSegment, parseUploadResponse, peekImage, pickSegmentHandle, pointToSegmentDistance, promoteMindMapNodeInTree, pruneStubBends, rectsIntersect, renderSVGString, renderToCanvas, reorderMindMapNodeInTree, routeToUserPoints, sameRoute, searchIcons, setImageCrossOrigin, setLanguage, setTheme, shadeColor, subscribeLanguage, subscribeTheme, subtractUnion, t, tableAnchorAt, tableCellAtLocalClamped, tableCellLineCount, tableCellLocalRect, tableCellTextStartOffset, tableCoveredMap, tableDeleteColumn, tableDeleteRow, tableExpandRangeToMerges, tableGrowRowHeights, tableInsertColumn, tableInsertRow, tableLocalPoint, tableMerge, tableMoveHandleLocalRect, tablePagePoint, tableRangeHasMerge, tableRangeLocalRect, tableRowAtPoint, tableSplit, tableSplitRange, tableTotalHeight, tableTotalWidth, umlAttrRowText, umlMethodRowText, unionRect, uploadImageViaConfig };
+export { type ArrowBinding, type ArrowHeadType, type ArrowShape, type ArrowStyle, ArrowTool, BoardExtentKeeper, type BoardExtentResult, type BoardExtentUpdate, Camera, type CameraState, type CircleShape, type ConnectionType, DEFAULT_HIGHLIGHTER_COLOR, DEFAULT_IMAGE_MAX_SIZE_BYTES, DEFAULT_PAGE_THEME, type DiamondShape, type DrawShape, type DrawuiTheme, type DrawuiThemeSelection, Editor, type EditorData, type EditorOptions, type EditorState, type EllipseShape, type ExportFormat, type ExportOptions, type FreehandMode, FreehandTool, type GenerationContext, HandTool, type HexagonShape, ICONS, ICON_CATEGORIES, ICON_CATEGORY_INK, ICON_DEFAULT_INK, ICON_DEFAULT_SIZE, ICON_GRID, type IconCategoryId, type IconDef, type IconLayer, type IconShape, type ImageShape, type ImageUploadConfig, type ImageUploadOption, type ImageUploader, LANGUAGES, type Language, type LineShape, LineTool, MINDMAP_COLORS, MINDMAP_DIRECTIONS, MINDMAP_FONT_SIZE, MINDMAP_HANDLE_HIT_RADIUS, MINDMAP_HANDLE_RADIUS, MINDMAP_MAX_WIDTH, MINDMAP_MIN_WIDTH, MINDMAP_NODE_HEIGHT, MIN_HANDLE_SEGMENT, MIN_JOG, Mat2d, type MessageKey, type MindMapDirection, type MindMapHandleKind, type MindMapHandlePos, type MindMapLayoutResult, type MindMapNode, type MindMapNodePos, type MindMapShape, type OctagonShape, PAGE_THEMES, type PageTheme, type PageThemePreset, type ParallelogramShape, type PentagonShape, type Rect, type RectangleShape, Renderer, type RoundedRectangleShape, STICKY_FOLD_RATIO, STICKY_NOTE_COLORS, STICKY_NOTE_DEFAULT_COLOR, STICKY_TEXT_SCALE, type SegmentHandle, SelectTool, type Shape, type ShapeStyle, ShapeTool, type ShapeType, type SnapGuide, type StarShape, type StickyNoteShape, TABLE_CELL_PADDING_X, TABLE_CELL_PADDING_Y, TABLE_DEFAULT_COL_WIDTH, TABLE_DEFAULT_ROW_HEIGHT, TABLE_FONT_SIZE, TABLE_HEADER_FILL, TABLE_LINE_HEIGHT_RATIO, TABLE_MAX_AUTO_LINES, TABLE_MIN_COL_WIDTH, TABLE_MIN_ROW_HEIGHT, TABLE_MOVE_HANDLE_GAP, TABLE_MOVE_HANDLE_HEIGHT, TABLE_MOVE_HANDLE_WIDTH, TEMPLATES, TEMPLATE_CATEGORIES, THEME, type TableCell, type TableShape, type TemplateCategoryId, type TemplateDef, type TextShape, type ToolType, type TrapezoidShape, type TriangleShape, UML_FONT_SIZE, UML_HEADER_HEIGHT, UML_LINE_HEIGHT, UML_MIN_WIDTH, UML_PADDING_X, UML_PADDING_Y, type UiEvent, type UmlAttribute, type UmlClassShape, type UmlInterfaceShape, type UmlMethod, type UmlVisibility, Vec, type Vec2 as Vec2Type, addImageReadyListener, calcUmlClassSize, clearImageCache, cloneMindMapNode, cloneTable, cloneTableCells, collapseRoute, collectTemporaryImageSrcs, connectorSegmentHandles, countMindMapNodes, createTableCells, downloadBlob, effectiveDirection, ensureIcons, ensureImagesLoaded, exportToBlob, findMindMapNode, getContentBounds, getIcon, getLanguage, getMindMapNodeDepth, getMindMapNodeSiblings, getMindMapParent, getTheme, hasIcon, hexToRgba, hitTableBody, hitTableMoveHandle, iconInk, iconsByCategory, imageDataUrl, isEmptyRect, isFlippableShapeType, isHorizontalDirection, isIconCatalogLoaded, isImageFailed, isImageLoading, isStubCorner, isUploaderFunction, layoutMindMap, loadIconCatalog, loadImage, mindMapHandleAtLocalPoint, mindMapNodeColor, mindMapNodeHandles, mindMapNodeSize, moveMindMapNodeInTree, offsetConnectorSegment, parseUploadResponse, peekImage, pickSegmentHandle, pointToSegmentDistance, promoteMindMapNodeInTree, pruneStubBends, rectsIntersect, renderSVGString, renderToCanvas, reorderMindMapNodeInTree, routeToUserPoints, sameRoute, searchIcons, searchTemplates, setImageCrossOrigin, setLanguage, setTheme, shadeColor, subscribeLanguage, subscribeTheme, subtractUnion, t, tableAnchorAt, tableCellAtLocalClamped, tableCellLineCount, tableCellLocalRect, tableCellTextStartOffset, tableCoveredMap, tableDeleteColumn, tableDeleteRow, tableExpandRangeToMerges, tableGrowRowHeights, tableInsertColumn, tableInsertRow, tableLocalPoint, tableMerge, tableMoveHandleLocalRect, tablePagePoint, tableRangeHasMerge, tableRangeLocalRect, tableRowAtPoint, tableSplit, tableSplitRange, tableTotalHeight, tableTotalWidth, templateById, umlAttrRowText, umlMethodRowText, unionRect, uploadImageViaConfig };