drawui-core 0.4.1 → 0.5.0

package/dist/index.d.cts

@@ -18,7 +18,7 @@ interface ShapeStyle {
     /** 描边色透明度（0-1），缺省为 1；与 strokeColor 叠加使用 */
     strokeOpacity?: number;
 }
-type ShapeType = 'rectangle' | 'rounded-rectangle' | 'circle' | 'ellipse' | 'diamond' | 'triangle' | 'hexagon' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'octagon' | 'star' | 'cylinder' | 'cloud' | 'heart' | 'block-arrow-right' | 'block-arrow-left' | 'block-arrow-up' | 'block-arrow-down' | 'block-arrow-double' | 'right-triangle' | 'cross' | 'speech-rect' | 'speech-round' | 'cube' | 'sector' | 'delay' | 'predefined-process' | 'document' | 'stadium' | 'class-catalog' | 'chevron' | 'brace-left' | 'brace-right' | 'envelope' | 'checkbox' | 'sticky-note' | 'triangular-pyramid' | 'quadrangular-pyramid' | 'cuboid' | 'sphere' | 'ellipsoid' | 'pie' | 'hollow-pie' | 'uml-class' | 'uml-interface' | 'mind-map' | 'table' | 'icon' | 'line' | 'arrow' | 'text' | 'draw';
+type ShapeType = 'rectangle' | 'rounded-rectangle' | 'circle' | 'ellipse' | 'diamond' | 'triangle' | 'hexagon' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'octagon' | 'star' | 'cylinder' | 'cloud' | 'heart' | 'block-arrow-right' | 'block-arrow-left' | 'block-arrow-up' | 'block-arrow-down' | 'block-arrow-double' | 'right-triangle' | 'cross' | 'speech-rect' | 'speech-round' | 'cube' | 'sector' | 'delay' | 'predefined-process' | 'document' | 'stadium' | 'class-catalog' | 'chevron' | 'brace-left' | 'brace-right' | 'envelope' | 'checkbox' | 'sticky-note' | 'triangular-pyramid' | 'quadrangular-pyramid' | 'cuboid' | 'sphere' | 'ellipsoid' | 'pie' | 'hollow-pie' | 'uml-class' | 'uml-interface' | 'mind-map' | 'table' | 'icon' | 'line' | 'arrow' | 'text' | 'draw' | 'image';
 interface BaseShape {
     id: string;
     type: ShapeType;
@@ -32,7 +32,20 @@ interface BaseShape {
     highlightColor?: string;
     /** 文字高亮背景透明度（0-1），缺省为 1 */
     highlightOpacity?: number;
+    /** 锁定：不可选中/拖动/缩放/删除（右键菜单可解锁） */
+    locked?: boolean;
+    /** 水平翻转（围绕自身中心镜像；文字/连线等不适用，见 isFlippableShapeType） */
+    flipX?: boolean;
+    /** 垂直翻转（围绕自身中心镜像） */
+    flipY?: boolean;
+    /**
+     * 分组 id：同一组的图形「同进同退」——点选任一成员即选中整组（一起拖动/删除/改变层级），
+     * 组锁定时整组都不可选中、不可拖动，等同于给多个图形绑了一把锁。
+     */
+    groupId?: string;
 }
+/** 该类型的图形是否支持水平/垂直翻转（右键菜单据此禁用） */
+declare function isFlippableShapeType(type: ShapeType): boolean;
 interface RectangleShape extends BaseShape {
     type: 'rectangle';
     width: number;
@@ -154,6 +167,23 @@ interface IconShape extends BaseShape {
  * 尺寸模型与矩形完全一致（以 (x,y) 为中心 + width/height），差异只在轮廓，
  * 轮廓定义见 `shapePaths.ts`，canvas 与 SVG 导出共用。
  */
+/**
+ * 图片图形：`src` 是图片地址 —— 可以是第三方上传接口返回的远端 URL，
+ * 也可以是本地上传的临时地址（`blob:`/`data:`，此时 `temporary: true`，刷新即失效）。
+ */
+interface ImageShape extends BaseShape {
+    type: 'image';
+    width: number;
+    height: number;
+    src: string;
+    /** src 是本地临时地址（blob:/data:），没有配置上传接口时的兜底，刷新后失效 */
+    temporary?: boolean;
+    /** 原始像素宽高：用于等比缩放与「恢复到原始比例」 */
+    naturalWidth?: number;
+    naturalHeight?: number;
+    /** 圆角半径（世界单位） */
+    borderRadius?: number;
+}
 interface PathShape extends BaseShape {
     type: 'block-arrow-double' | 'right-triangle' | 'cross' | 'speech-rect' | 'speech-round' | 'cube' | 'sector' | 'delay' | 'predefined-process' | 'document' | 'class-catalog' | 'chevron' | 'brace-left' | 'brace-right' | 'envelope' | 'checkbox' | 'triangular-pyramid' | 'quadrangular-pyramid' | 'cuboid' | 'sphere' | 'ellipsoid' | 'pie' | 'hollow-pie';
     width: number;
@@ -360,8 +390,8 @@ interface TableShape extends BaseShape {
     /** cells[row][col] */
     cells: TableCell[][];
 }
-type Shape = RectangleShape | RoundedRectangleShape | CircleShape | EllipseShape | DiamondShape | TriangleShape | HexagonShape | ParallelogramShape | TrapezoidShape | PentagonShape | OctagonShape | StarShape | CylinderShape | CloudShape | HeartShape | BlockArrowShape | StadiumShape | StickyNoteShape | IconShape | PathShape | UmlClassShape | UmlInterfaceShape | LineShape | ArrowShape | TextShape | DrawShape | MindMapShape | TableShape;
-type ToolType = 'select' | 'hand' | 'rectangle' | 'rounded-rectangle' | 'circle' | 'ellipse' | 'diamond' | 'triangle' | 'hexagon' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'octagon' | 'star' | 'cylinder' | 'cloud' | 'heart' | 'block-arrow-right' | 'block-arrow-left' | 'block-arrow-up' | 'block-arrow-down' | 'block-arrow-double' | 'right-triangle' | 'cross' | 'speech-rect' | 'speech-round' | 'cube' | 'sector' | 'delay' | 'predefined-process' | 'document' | 'stadium' | 'class-catalog' | 'chevron' | 'brace-left' | 'brace-right' | 'envelope' | 'checkbox' | 'sticky-note' | 'triangular-pyramid' | 'quadrangular-pyramid' | 'cuboid' | 'sphere' | 'ellipsoid' | 'pie' | 'hollow-pie' | 'uml-class' | 'uml-interface' | 'line' | 'arrow' | 'text' | 'draw' | 'pen' | 'highlighter' | 'eraser' | 'mind-map' | 'table' | 'icon';
+type Shape = RectangleShape | RoundedRectangleShape | CircleShape | EllipseShape | DiamondShape | TriangleShape | HexagonShape | ParallelogramShape | TrapezoidShape | PentagonShape | OctagonShape | StarShape | CylinderShape | CloudShape | HeartShape | BlockArrowShape | StadiumShape | StickyNoteShape | IconShape | ImageShape | PathShape | UmlClassShape | UmlInterfaceShape | LineShape | ArrowShape | TextShape | DrawShape | MindMapShape | TableShape;
+type ToolType = 'select' | 'hand' | 'rectangle' | 'rounded-rectangle' | 'circle' | 'ellipse' | 'diamond' | 'triangle' | 'hexagon' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'octagon' | 'star' | 'cylinder' | 'cloud' | 'heart' | 'block-arrow-right' | 'block-arrow-left' | 'block-arrow-up' | 'block-arrow-down' | 'block-arrow-double' | 'right-triangle' | 'cross' | 'speech-rect' | 'speech-round' | 'cube' | 'sector' | 'delay' | 'predefined-process' | 'document' | 'stadium' | 'class-catalog' | 'chevron' | 'brace-left' | 'brace-right' | 'envelope' | 'checkbox' | 'sticky-note' | 'triangular-pyramid' | 'quadrangular-pyramid' | 'cuboid' | 'sphere' | 'ellipsoid' | 'pie' | 'hollow-pie' | 'uml-class' | 'uml-interface' | 'line' | 'arrow' | 'text' | 'draw' | 'pen' | 'highlighter' | 'eraser' | 'mind-map' | 'table' | 'icon' | 'image';
 interface CameraState {
     x: number;
     y: number;
@@ -379,6 +409,53 @@ interface EditorData {
     camera: CameraState;
 }
 
+/**
+ * 图片上传通道。
+ *
+ * 两种模式（由接入方决定）：
+ *   A. 配了上传接口 `ImageUploadConfig`（url 必填）→ 由**接入方自己的服务器**接收文件，
+ *      返回图片地址，我们拿到地址后只存 URL（刷新不丢）。
+ *   B. 没配 → 退回**本地临时二进制流**（`URL.createObjectURL(file)`，标记 temporary），
+ *      图片只在当前页面内存里有效，刷新即失效。
+ *
+ * 也支持直接给一个函数（`ImageUploader`）：需要签名、分片、转存等自定义逻辑时用它，
+ * 优先级高于 URL 配置。
+ */
+
+/** 上传通道内置的图片体积上限：30 MB。超过此体积禁止上传，由接入方通过 `maxSizeBytes` 覆盖。 */
+declare const DEFAULT_IMAGE_MAX_SIZE_BYTES: number;
+/** 上传接口配置（走内置 fetch 实现） */
+interface ImageUploadConfig {
+    /** 上传地址，例如 https://api.example.com/upload */
+    url: string;
+    /** 请求方法，默认 POST */
+    method?: 'POST' | 'PUT';
+    /** 文件字段名，默认 'file' */
+    fieldName?: string;
+    /** 额外请求头（如 Authorization） */
+    headers?: Record<string, string>;
+    /** 额外表单字段 */
+    fields?: Record<string, string>;
+    /** 是否带 cookie，默认 'same-origin' */
+    withCredentials?: boolean;
+    /** 从响应 JSON 里取 url 的路径，如 'data.url'；不填则自动探测 */
+    responseUrlPath?: string;
+    /** 超时（毫秒），默认 60000 */
+    timeoutMs?: number;
+    /** 单张图片体积上限（字节）。超过此大小直接抛出 `image.tooLarge`，不会真的发请求。默认 30 MB。 */
+    maxSizeBytes?: number;
+}
+/** 自定义上传函数：返回图片可访问的 URL */
+type ImageUploader = (file: File) => Promise<string>;
+type ImageUploadOption = ImageUploadConfig | ImageUploader;
+declare function isUploaderFunction(v: unknown): v is ImageUploader;
+/** 从响应体文本里解析出图片地址（导出给接入方复用时也用得上） */
+declare function parseUploadResponse(body: string, responseUrlPath?: string): string;
+/** 走配置里的 URL 上传文件，返回图片地址 */
+declare function uploadImageViaConfig(file: File, cfg: ImageUploadConfig): Promise<string>;
+/** 从一批图形里找出「本地临时图片」的地址（刷新后会失效，界面可据此提示） */
+declare function collectTemporaryImageSrcs(shapes: Shape[]): string[];
+
 interface Mat2d {
     a: number;
     b: number;
@@ -682,7 +759,34 @@ declare const zhCN: {
     readonly 'table.insertColLeft': "在左侧插入列";
     readonly 'table.insertColRight': "在右侧插入列";
     readonly 'table.pickHint': "拖选行列数";
+    readonly 'ctx.copy': "复制";
+    readonly 'ctx.copyAsImage': "复制为图片";
+    readonly 'ctx.paste': "粘贴";
+    readonly 'ctx.duplicate': "创建副本";
+    readonly 'ctx.layer': "层级";
+    readonly 'ctx.bringToFront': "置于顶层";
+    readonly 'ctx.bringForward': "上移一层";
+    readonly 'ctx.sendBackward': "下移一层";
+    readonly 'ctx.sendToBack': "置于底层";
+    readonly 'ctx.copyStyle': "复制样式";
+    readonly 'ctx.pasteStyle': "粘贴样式";
+    readonly 'ctx.rotate90': "90°";
+    readonly 'ctx.rotate180': "180°";
+    readonly 'ctx.rotate270': "270°";
+    readonly 'ctx.rotate': "旋转";
+    readonly 'ctx.group': "成组";
+    readonly 'ctx.ungroup': "解组";
+    readonly 'ctx.lock': "锁定";
+    readonly 'ctx.unlock': "解锁";
+    readonly 'ctx.delete': "删除";
     readonly 'toolbar.icon': "图标";
+    readonly 'toolbar.image': "图片";
+    readonly 'tool.image': "图片";
+    readonly 'image.uploadFailed': "图片上传失败";
+    readonly 'image.insertFailed': "图片插入失败";
+    readonly 'image.tooLarge': "图片超过 30 MB，无法上传";
+    readonly 'image.temporaryInserted': "已插入临时图片（未配置上传接口，刷新后会丢失）";
+    readonly 'image.naturalSize': "原图尺寸";
     readonly 'icon.search': "搜索图标";
     readonly 'icon.empty': "没有匹配的图标";
     readonly 'icon.recent': "最近使用";
@@ -742,7 +846,7 @@ declare function exportToBlob(shapes: Shape[], format: ExportFormat, opts?: Expo
 /** 浏览器端触发下载 */
 declare function downloadBlob(blob: Blob, fileName: string): void;
 
-type Listener = () => void;
+type Listener$1 = () => void;
 type NotificationListener = (message: string) => void;
 /** 核心 → React 的 UI 指令事件 */
 type UiEvent = {
@@ -752,6 +856,11 @@ type UiEvent = {
     context: GenerationContext;
     existingArrowId?: string;
     defaultShapeType: ShapeType;
+}
+/** 图片上传/加载失败（接入方可据此弹 toast） */
+ | {
+    kind: 'imageError';
+    message: string;
 };
 /** Editor 构造选项：主题色 / 语言 / 初始数据 / 本地持久化开关 */
 interface EditorOptions {
@@ -763,6 +872,14 @@ interface EditorOptions {
     shapes?: Shape[];
     /** 是否启用 localStorage 持久化（默认 true；提供 shapes 时自动关闭） */
     persist?: boolean;
+    /**
+     * 图片上传通道（「图片」按钮 / 粘贴 / 拖入文件时用）：
+     *  - 传 `{ url }` 配置：文件会 POST 到接入方自己的服务器，服务器返回图片地址 → 只存 URL，刷新不丢
+     *  - 传函数：完全自定义上传（签名、分片、转存等）
+     *  - 不传：退回**本地临时二进制流**（`URL.createObjectURL`），图形带 `temporary: true`，
+     *    图片只活在这个页面里，刷新即失效
+     */
+    imageUpload?: ImageUploadOption;
 }
 declare class Editor {
     private canvas;
@@ -815,8 +932,21 @@ declare class Editor {
      * 同样「只影响之后创建的便签」；改选中便签的颜色走 updateSelectedShapesStyle。
      */
     private stickyNoteColor;
+    /** 图片上传通道（null = 本地临时 blob 兜底） */
+    private imageUploadOption;
+    /** 图片加载完成 → 重绘的取消订阅函数 */
+    private removeImageReadyListener;
+    /** 本编辑器创建的临时图片地址（blob:），图形删掉后释放 */
+    private ownImageUrls;
+    /** 插入图片的错开步进，避免多张图完全重叠 */
+    private imageInsertSeq;
+    /** Ctrl+V 时若系统剪贴板里是图片，paste 事件已处理 → 跳过一次内部粘贴 */
+    private imagePasteHandled;
     /** 连续插入图标时的错开计数（避免每次都叠在同一处） */
     private iconInsertSeq;
+    private clipboardShapes;
+    private pasteSeq;
+    private copiedStyle;
     constructor(canvas: HTMLCanvasElement, options?: EditorOptions);
     private setupEventListeners;
     /** 窗口失焦（切页签/alt-tab）：按下状态与一切瞬态预览都作废，避免"卡住" */
@@ -864,8 +994,43 @@ declare class Editor {
     private updateBoundArrows;
     private getBindingPosition;
     private deleteShape;
-    private selectShape;
-    private selectShapes;
+    /**
+     * 选中图形（additive=true 时切换选中态）；id 为空串清空选中。右键菜单/外部控制用。
+     * ⚠️ 组感知：点任一成员都会选中它所属的整组（同组的绑行为一致），additive 时整组一起加减。
+     */
+    selectShape(id: string, additive: boolean): void;
+    /** 整体替换选中集（右键菜单/外部控制用）；框选结果同样按组扩张 */
+    selectShapes(ids: string[]): void;
+    /** 某图形所在的整组 id 列表（不在组里就只有它自己） */
+    private getGroupMembers;
+    /** 选中集是否恰好是完整的一个组（返回 groupId，否则 null） */
+    getSelectedGroupId(): string | null;
+    /** 选中集里是否包含成组图形（用于右键菜单显示「解组」） */
+    hasSelectedGroup(): boolean;
+    /** 取某个组的所有成员 id（含锁定的成员） */
+    private groupMemberIds;
+    /**
+     * 成组：把选中图形绑成一个整体，并整组锁定（同飞书「组合后不再被选中」的观感，
+     * 用户想改动先解锁，解锁后整组仍同进同退：点任一成员 = 选中整组一起拖）。
+     * @returns 新建的 groupId；选中不足 2 个时返回 null
+     */
+    groupSelected(): string | null;
+    /**
+     * 解组：清掉这些图形的组标记并顺带解锁（整组一起解，即使只选中了组内一部分成员）。
+     * @returns 是否确实解掉了组
+     */
+    ungroupSelected(): boolean;
+    /** 解掉指定 gid 的组（内部统一入口，含 locked 清理） */
+    ungroupIds(groupIds: string[]): boolean;
+    /** 整组锁定/解锁（groupId 相同的图形一起改） */
+    setGroupLocked(groupId: string, locked: boolean): boolean;
+    /**
+     * 无视「组/锁定」直接选中一个图形（仅供右键菜单：右键命中锁定的组成员要能把整组选上，
+     * 否则用户没有任何入口把组解锁）。普通点选一律走 selectShape。
+     */
+    selectShapeRaw(id: string): void;
+    /** 选中集里任一成员所属的组 id（右键菜单「解锁本组」用） */
+    getGroupIdOfSelected(): string | null;
     private setBrushRect;
     /** 设置对齐参考线（由工具在拖拽过程中调用） */
     private setSnapGuides;
@@ -927,6 +1092,56 @@ declare class Editor {
     }): void;
     /** 批量更新选中线条/箭头的连线类型 */
     updateConnectionType(connectionType: ConnectionType): void;
+    /** 获取选中的图形（按画布层级顺序，即 shapes 数组顺序） */
+    getSelectedShapes(): Shape[];
+    /** 是否正处于就地编辑（编辑文字/表格/思维导图节点） */
+    isEditing(): boolean;
+    /** 删除选中的图形（锁定的图形跳过），返回是否有删除 */
+    deleteSelected(): boolean;
+    /** 复制选中的图形到内部剪贴板（锁定的图形跳过） */
+    copySelected(): boolean;
+    /** 内部剪贴板里是否有可粘贴的内容 */
+    hasClipboard(): boolean;
+    /** 深拷贝一批图形并生成新 id、平移 offset（连线的世界坐标 points / 手工折点同步平移） */
+    private cloneWithOffset;
+    /** 粘贴内部剪贴板：副本阶梯偏移并选中，一步撤销 */
+    paste(): boolean;
+    /** 在原位创建选中图形的副本（偏移一点并选中副本），一步撤销 */
+    duplicateSelected(): boolean;
+    /** 把选中的图形导出为 PNG 并写入系统剪贴板（透明背景），返回是否成功 */
+    copySelectedAsImage(): Promise<boolean>;
+    /** 复制第一个选中图形的样式（边框/填充/文字色/字号） */
+    copyStyle(): boolean;
+    /** 是否已经复制过样式（右键菜单「粘贴样式」的可用条件） */
+    hasCopiedStyle(): boolean;
+    /** 把复制的样式粘贴到所有选中图形（一步撤销） */
+    pasteStyle(): boolean;
+    /**
+     * 水平/垂直翻转选中的图形（围绕各自中心镜像，toggle 语义）。
+     * 文字/连线/表格/UML/思维导图/便签不支持翻转（isFlippableShapeType），会被跳过。
+     */
+    flipSelected(axis: 'horizontal' | 'vertical'): boolean;
+    /**
+     * 按角度旋转选中图形（**顺时针为正**，单位：度）。每个图形绕自身中心转，
+     * 与拖拽旋转手柄一致；整体一步撤销。锁定图形不参与。
+     */
+    rotateSelected(degrees: number): boolean;
+    /** 选中图形旋转 90°（clockwise=false 为逆时针）；保留旧签名，内部走 rotateSelected */
+    rotateSelected90(clockwise?: boolean): boolean;
+    /** 锁定/解锁选中图形；锁定后自动取消选中（锁定图形不可选中） */
+    setSelectedShapesLocked(locked: boolean): boolean;
+    /** 锁定/解锁指定图形（右键锁定的图形时用它解锁，图形不必在选中集里） */
+    setShapeLocked(id: string, locked: boolean): boolean;
+    /** 某个图形是否被锁定 */
+    isShapeLocked(id: string): boolean;
+    /** 置于顶层：选中的图形整体移到最上面（保持它们之间的相对顺序） */
+    bringToFront(): boolean;
+    /** 置于底层：选中的图形整体移到最下面 */
+    sendToBack(): boolean;
+    /** 上移一层：每个选中图形与它上面相邻的非选中图形交换 */
+    bringForward(): boolean;
+    /** 下移一层：每个选中图形与它下面相邻的非选中图形交换 */
+    sendBackward(): boolean;
     /** 批量更新选中箭头的箭头类型 */
     updateArrowHeadType(arrowHead: ArrowHeadType): void;
     /**
@@ -948,6 +1163,45 @@ declare class Editor {
      * - 计入撤销历史；图标 id 不存在时返回 undefined（不做任何事）。
      */
     insertIcon(iconId: string, size?: number): string | undefined;
+    /** 运行时配置图片上传通道（null = 退回本地临时 blob）。常见于接入方拿到用户配置后再注入 */
+    setImageUpload(option: ImageUploadOption | null): void;
+    getImageUpload(): ImageUploadOption | null;
+    /** 是否配置了上传通道：false 表示插入的图片是本地临时 blob，刷新即失效 */
+    hasImageUploader(): boolean;
+    /** 画布上所有「本地临时图片」的地址（接入方保存前可据此提示「刷新会丢」） */
+    getTemporaryImageSrcs(): string[];
+    hasTemporaryImages(): boolean;
+    /**
+     * 插入一张图片图形（同步）。尺寸按原始像素等比缩放到长边不超过 `IMAGE_MAX_SIDE`；
+     * 拿不到原始尺寸时用 320×240 兜底。返回新图形 id。
+     */
+    insertImageShape(opts: {
+        src: string;
+        naturalWidth?: number;
+        naturalHeight?: number;
+        temporary?: boolean;
+        at?: Vec2;
+    }): string;
+    /**
+     * 上传（或本地兜底）后插入一张图片：
+     *  - 配了上传通道 → 调接入方接口拿远端 URL（`temporary` 不置位，刷新不丢）
+     *  - 没配 → `URL.createObjectURL(file)` 本地临时地址（`temporary: true`，刷新即失效）
+     * 上传失败会抛出（错误信息可直接展示给用户）；返回新图形 id。
+     *
+     * 单张图片超过 30 MB 会被直接拒绝；`ImageUploadConfig` 可通过 `maxSizeBytes` 自定义上限。
+     */
+    insertImageFile(file: File, at?: Vec2): Promise<string>;
+    /** 批量插入（工具栏多选 / 拖入多个文件 / 粘贴多张图） */
+    insertImageFiles(files: FileList | File[], at?: Vec2): Promise<string[]>;
+    /** 直接用图片地址插入（已有素材库 / 贴图片链接） */
+    insertImageFromUrl(src: string, at?: Vec2): Promise<string>;
+    /** 释放已经没有任何图形引用的临时图片地址（删除/清空/替换数据后调用） */
+    private releaseUnusedImageUrls;
+    /**
+     * 系统剪贴板粘贴：剪贴板里有图片就直接插图（优先级高于内部图形剪贴板）。
+     * 截图后 Ctrl+V 贴进画布走的就是这里。
+     */
+    private handlePasteEvent;
     /** 视口中心（世界坐标）：插入类操作（图标）的默认落点 */
     private viewportCenter;
     /** 修改「新建便签」的纸面色：只影响之后创建的便签；非法色值会被忽略 */
@@ -1193,6 +1447,14 @@ declare class Editor {
         width: number;
         height: number;
     };
+    /** 当前可视区对应的世界坐标范围（用于画板范围、小地图等） */
+    getViewportBounds(): Rect;
+    /**
+     * 画板「应覆盖的范围」（世界坐标）：内容包围盒 ∪ 当前可视区，再各加 padding。
+     * 一次性的纯计算，不做任何状态保留；宿主若要「删了图形后延迟缩回」的语义，
+     * 用 `BoardExtentKeeper`（见 core 的 boardExtent.ts）包一层。
+     */
+    getBoardExtent(padding?: number): Rect;
     /**
      * 导出当前画布为图片 Blob。
      * @param format png | svg | pdf
@@ -1223,7 +1485,7 @@ declare class Editor {
     render(): void;
     /** 合帧渲染：同一帧内多次调用只会触发一次实际重绘 */
     private scheduleRender;
-    subscribe(listener: Listener): () => boolean;
+    subscribe(listener: Listener$1): () => boolean;
     subscribeNotifications(listener: NotificationListener): () => boolean;
     private notify;
     private notifyListeners;
@@ -1454,6 +1716,12 @@ declare class Renderer {
      * - 线宽用「网格单位」而不是屏幕单位，所以图标放大时线条跟着变粗，像字体图标那样；
      * - 用 `Path2D` 直接吃 SVG path 字符串，与 SVG 导出共用同一份路径数据（含圆弧，无需自己解析）。
      */
+    /**
+     * 图片：命中缓存就画，没命中先画占位块（斜线 + 灰底/失败时红底）。
+     * `peekImage()` 会顺手启动异步加载，加载完成后 imageStore 通知 Editor 重绘，
+     * 所以这里不需要任何 await —— 画布永远是同步画一帧。
+     */
+    private drawImageShape;
     private drawIcon;
     private drawUmlClass;
     /**
@@ -1654,6 +1922,24 @@ declare class Renderer {
     private drawArrowHeads;
     private drawText;
     private drawFreehand;
+    /**
+     * 锁定标记：图形右上角画一枚小挂锁（尺寸按屏幕像素恒定），
+     * 独立于选中态 —— 锁定的图形通常选不中，得靠这枚锁告诉用户「它为什么点不动」。
+     */
+    private drawLockBadge;
+    /**
+     * 锁定组的统一标记：整组只画**一把锁**，挂在组包围盒顶部居中，
+     * 而不是组里每个成员各挂一把（一堆锁没法看）。只要组处于锁定状态就画，
+     * 与选中无关（锁定的组本来也选不中，这枚锁就是唯一的视觉提示）。
+     */
+    private drawGroupLockBadges;
+    /** 在指定位置（徽标左上角，世界坐标）画一枚挂锁徽标 */
+    private drawLockBadgeAt;
+    /**
+     * 组外框：选中集恰好是一个完整的组（且不止一个成员）时，给整组描一圈虚线，
+     * 提示「这些图形是绑在一起的」。整组锁定的成员画不到（成员不可选），不需要外框。
+     */
+    private drawGroupFrames;
     private drawSelectionOutline;
     private drawSelectionHandles;
     /**
@@ -1702,8 +1988,12 @@ declare const STICKY_NOTE_DEFAULT_COLOR: string;
  */
 declare const STICKY_FOLD_RATIO = 0.2;
 /**
- * 便签文字的可用区域缩放：常规内边距 0.85 再让掉半个折角，
- * 保证文字块右下角落在折角斜边之内（不再是 0.85，否则会压到折角上）。
+ * 便签文字的可用区域缩放：常规内边距 0.85 再让掉半个折角 = 0.75。
+ *
+ * 为什么这样就够、不需要再把文字整体往左上挪：文字块是**居中**摆放的，
+ * 可用区 0.75 倍时文字块右下角最多落在 (0.875w, 0.875h)；而折角三角区是
+ * `Δx/0.2w + Δy/0.2h > 1` 的那一块，把 0.875 代进去是 0.375+0.375 = 0.75 < 1，
+ * **已经在折角斜边之外**。所以居中排版天然不会压到折角。
  */
 declare const STICKY_TEXT_SCALE: number;
 
@@ -1788,6 +2078,76 @@ declare const ICON_CATEGORY_INK: Record<IconCategoryId, string>;
 /** 取某个图标的默认墨色：图标自带 ink 优先（全彩贴纸），否则用分类主色，最后退回全局默认 */
 declare function iconInk(icon: IconDef): string;
 
+/**
+ * 画板范围（Board Extent）—— 宿主用来决定「画板这块 DOM / 可滚区域该多大」。
+ *
+ * 语义（与产品约定一致）：
+ *   - **长出去就立刻长**：内容跑到更远处时，画板范围马上跟着扩（这合理，不需要等待）。
+ *   - **缩回来要谨慎**：内容被删掉后空出来的那块，不能马上收 ——
+ *       · 鼠标没动过 → 先不变（否则指针底下的东西会突然跳/滚动位置变了）
+ *       · 鼠标动过、但要让出的那块还在可视区里 → 还是不变（用户正看着它）
+ *       · 鼠标动过、且要让出的那块已经完全在可视区之外 → 这时才把这块空间收回
+ *
+ * 本文件不碰 DOM，纯几何 + 状态机，宿主（React / 业务容器）拿到结果自己去设尺寸。
+ */
+
+declare function isEmptyRect(r: Rect | null | undefined): boolean;
+/** 两个矩形求并（任一为空则返回另一个的副本） */
+declare function unionRect(a: Rect | null, b: Rect | null): Rect | null;
+/** 两个矩形是否相交（边界接触不算相交） */
+declare function rectsIntersect(a: Rect | null, b: Rect | null): boolean;
+/** 向内收缩 r，得到「target 之外、r 之内的部分」是否有内容（用于判断「要让出的那块」是否与可视区重叠） */
+declare function subtractUnion(a: Rect, b: Rect): Rect[];
+interface BoardExtentUpdate {
+    /** 内容包围盒（世界坐标）；没有内容传 null */
+    content: Rect | null;
+    /** 当前可视区（世界坐标） */
+    viewport: Rect;
+    /** 自上次 update 以来指针是否移动过（宿主提供；决定能不能缩回） */
+    pointerMoved: boolean;
+    /** 内容外的留白 */
+    padding?: number;
+    /**
+     * 画板范围是否必须覆盖当前可视区：
+     *   - true（默认）：相机式画布 —— 画布必须盖住整屏，否则滚动出画面
+     *   - false：可滚动画板 —— 范围只跟内容走，空出来的远处空间才有机会被「收回」
+     */
+    includeViewport?: boolean;
+    /** 内容为空时，画板至少保留这么大（默认 = 一个视口大小） */
+    minSize?: {
+        width: number;
+        height: number;
+    };
+    /** 内容为空时画板回到的位置（默认世界原点）——可滚动画板的「默认画板位置」 */
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}
+interface BoardExtentResult {
+    /** 本次应该采用的画板范围 */
+    extent: Rect;
+    /** 相比上次是否有变化（宿主据此决定要不要改 DOM 尺寸 / 滚动位置） */
+    changed: boolean;
+    /** 本次是「长大」还是「缩回」还是没变 */
+    action: 'grow' | 'shrink' | 'hold' | 'init';
+    /** hold 时说明原因（便于调试 / 埋点） */
+    holdReason?: 'pointer-still' | 'still-visible';
+}
+/**
+ * 画板范围状态机：调用 `update()` 传入当前内容/可视区/指针状态，拿回应该采用的范围。
+ * 一次会话里保持同一个实例即可。
+ */
+declare class BoardExtentKeeper {
+    private current;
+    /** 重置（例如加载了新文档 / 宿主容器尺寸变了） */
+    reset(extent?: Rect | null): void;
+    get(): Rect | null;
+    /** 本次「理想范围」：内容 + 留白；内容为空时退化成「默认画板」那一块 */
+    private desiredOf;
+    update(input: BoardExtentUpdate): BoardExtentResult;
+}
+
 interface ToolContext {
     addShape(shape: Shape): void;
     updateShape(id: string, updates: Partial<Shape>): void;
@@ -2137,12 +2497,22 @@ declare function calcUmlClassSize(className: string, attributes: UmlAttribute[],
 };
 declare class ShapeTool extends Tool {
     type: ShapeType;
+    /** 按下点（页面坐标）；null = 未按下 */
+    private pressPoint;
+    /** 本次按下的图形 id（按下即生成默认尺寸，拖动只改它的大小） */
+    private draftId;
+    /** 是否已进入拖拽状态（超过阈值） */
+    private dragging;
     constructor(context: ToolContext, shapeType: ShapeType);
     onPointerDown(point: Vec2, _event: PointerEvent): void;
-    onPointerMove(_point: Vec2, _event: PointerEvent): void;
+    onPointerMove(point: Vec2, event: PointerEvent): void;
     onPointerUp(_point: Vec2, _event: PointerEvent): void;
-    onKeyDown(_event: KeyboardEvent): void;
+    onKeyDown(event: KeyboardEvent): void;
     onKeyUp(_event: KeyboardEvent): void;
+    /** 拖拽生成中 = 一次未结束的交互（指针丢失时编辑器会来收尾） */
+    hasTransientState(): boolean;
+    /** 丢事件自愈：保持图形当前尺寸落定（历史点在按下时已记），清掉拖拽状态 */
+    cancelTransient(): boolean;
     getCursor(point: Vec2): string | null;
 }
 
@@ -2428,4 +2798,45 @@ declare function umlAttrRowText(a: UmlAttribute): string;
 /** 方法行：`+ name(params): returnType`；同上 */
 declare function umlMethodRowText(m: UmlMethod): string;
 
-export { type ArrowBinding, type ArrowHeadType, type ArrowShape, type ArrowStyle, ArrowTool, Camera, type CameraState, type CircleShape, type ConnectionType, DEFAULT_HIGHLIGHTER_COLOR, 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, LANGUAGES, type Language, type LineShape, LineTool, MINDMAP_COLORS, MINDMAP_FONT_SIZE, MINDMAP_MAX_WIDTH, MINDMAP_MIN_WIDTH, MINDMAP_NODE_HEIGHT, MIN_HANDLE_SEGMENT, MIN_JOG, Mat2d, type MessageKey, type MindMapLayoutResult, type MindMapNode, type MindMapNodePos, type MindMapShape, type OctagonShape, 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, calcUmlClassSize, cloneMindMapNode, cloneTable, cloneTableCells, collapseRoute, connectorSegmentHandles, countMindMapNodes, createTableCells, downloadBlob, exportToBlob, findMindMapNode, getContentBounds, getIcon, getLanguage, getMindMapNodeDepth, getMindMapParent, getTheme, hasIcon, hexToRgba, hitTableBody, hitTableMoveHandle, iconInk, iconsByCategory, isStubCorner, layoutMindMap, mindMapNodeColor, mindMapNodeSize, offsetConnectorSegment, pickSegmentHandle, pointToSegmentDistance, pruneStubBends, renderSVGString, renderToCanvas, routeToUserPoints, sameRoute, searchIcons, setLanguage, setTheme, shadeColor, subscribeLanguage, subscribeTheme, 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 };
+/**
+ * 图片资源仓库：`src` → 已加载的 HTMLImageElement 缓存 + 异步加载 + 就绪回调。
+ *
+ * 设计要点（都是踩过的坑）：
+ * - Renderer 是**同步一次性绘制**的，所以绘制时只做 `peekImage()`：命中就画，没命中先画占位；
+ *   加载完成后通过监听者通知（Editor 会把它接到 requestRender 上）自动重绘补齐。
+ * - 远端 http(s) 图片默认加 `crossOrigin='anonymous'`：不加的话画布会被污染（tainted），
+ *   之后 `toDataURL()`/导出会直接抛错。
+ * - 加载失败要**记住失败**，否则每帧都会重新 new Image 去打一个坏地址（疯狂重试）。
+ * - 本地兜底的 `blob:` 地址由我们创建，删除图形时通过 `releaseObjectUrl()` 释放。
+ */
+
+interface LoadedImage {
+    img: HTMLImageElement;
+    width: number;
+    height: number;
+    src: string;
+}
+type Listener = () => void;
+/** 图片加载完成/失败时通知（Editor 接到 requestRender）。返回取消订阅函数 */
+declare function addImageReadyListener(cb: Listener): () => void;
+/** 配置远端图的 crossOrigin（传 null 表示不加） */
+declare function setImageCrossOrigin(value: string | null): void;
+/** 同步取已加载的图片（未加载/失败返回 null，并顺带触发加载） */
+declare function peekImage(src: string): LoadedImage | null;
+/** 该地址是否已确认加载失败 */
+declare function isImageFailed(src: string): boolean;
+/** 该地址是否正在加载 */
+declare function isImageLoading(src: string): boolean;
+/** 加载图片（命中缓存直接返回）。失败返回 null，并记录失败状态 */
+declare function loadImage(src: string): Promise<LoadedImage | null>;
+/** 让一批图形里的图片全部就绪（导出前调用，否则导出的图会是空的） */
+declare function ensureImagesLoaded(shapes: Shape[]): Promise<void>;
+/**
+ * 取图片的 dataURL（导出 SVG 内嵌用）：
+ * 已加载的图片画到离屏 canvas 再 toDataURL；跨域被拒等失败时返回 null（调用方退回原始地址）。
+ */
+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, 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_FONT_SIZE, MINDMAP_MAX_WIDTH, MINDMAP_MIN_WIDTH, MINDMAP_NODE_HEIGHT, MIN_HANDLE_SEGMENT, MIN_JOG, Mat2d, type MessageKey, type MindMapLayoutResult, type MindMapNode, type MindMapNodePos, type MindMapShape, type OctagonShape, 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, ensureImagesLoaded, exportToBlob, findMindMapNode, getContentBounds, getIcon, getLanguage, getMindMapNodeDepth, getMindMapParent, getTheme, hasIcon, hexToRgba, hitTableBody, hitTableMoveHandle, iconInk, iconsByCategory, imageDataUrl, isEmptyRect, isFlippableShapeType, isImageFailed, isImageLoading, isStubCorner, isUploaderFunction, layoutMindMap, loadImage, mindMapNodeColor, mindMapNodeSize, offsetConnectorSegment, parseUploadResponse, peekImage, pickSegmentHandle, pointToSegmentDistance, pruneStubBends, rectsIntersect, renderSVGString, renderToCanvas, 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 };