drawui-core 0.4.2 → 0.5.0

package/dist/index.d.ts

@@ -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;
@@ -167,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;
@@ -373,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;
@@ -392,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;
@@ -706,16 +770,23 @@ declare const zhCN: {
     readonly 'ctx.sendToBack': "置于底层";
     readonly 'ctx.copyStyle': "复制样式";
     readonly 'ctx.pasteStyle': "粘贴样式";
-    readonly 'ctx.flipH': "水平翻转";
-    readonly 'ctx.flipV': "垂直翻转";
+    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.unlockGroup': "解锁本组";
     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': "最近使用";
@@ -775,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 = {
@@ -785,6 +856,11 @@ type UiEvent = {
     context: GenerationContext;
     existingArrowId?: string;
     defaultShapeType: ShapeType;
+}
+/** 图片上传/加载失败（接入方可据此弹 toast） */
+ | {
+    kind: 'imageError';
+    message: string;
 };
 /** Editor 构造选项：主题色 / 语言 / 初始数据 / 本地持久化开关 */
 interface EditorOptions {
@@ -796,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;
@@ -848,6 +932,16 @@ 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;
@@ -1027,7 +1121,12 @@ declare class Editor {
      * 文字/连线/表格/UML/思维导图/便签不支持翻转（isFlippableShapeType），会被跳过。
      */
     flipSelected(axis: 'horizontal' | 'vertical'): boolean;
-    /** 选中图形旋转 90°（clockwise=false 为逆时针），一步撤销 */
+    /**
+     * 按角度旋转选中图形（**顺时针为正**，单位：度）。每个图形绕自身中心转，
+     * 与拖拽旋转手柄一致；整体一步撤销。锁定图形不参与。
+     */
+    rotateSelected(degrees: number): boolean;
+    /** 选中图形旋转 90°（clockwise=false 为逆时针）；保留旧签名，内部走 rotateSelected */
     rotateSelected90(clockwise?: boolean): boolean;
     /** 锁定/解锁选中图形；锁定后自动取消选中（锁定图形不可选中） */
     setSelectedShapesLocked(locked: boolean): boolean;
@@ -1064,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;
     /** 修改「新建便签」的纸面色：只影响之后创建的便签；非法色值会被忽略 */
@@ -1309,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
@@ -1339,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;
@@ -1570,6 +1716,12 @@ declare class Renderer {
      * - 线宽用「网格单位」而不是屏幕单位，所以图标放大时线条跟着变粗，像字体图标那样；
      * - 用 `Path2D` 直接吃 SVG path 字符串，与 SVG 导出共用同一份路径数据（含圆弧，无需自己解析）。
      */
+    /**
+     * 图片：命中缓存就画，没命中先画占位块（斜线 + 灰底/失败时红底）。
+     * `peekImage()` 会顺手启动异步加载，加载完成后 imageStore 通知 Editor 重绘，
+     * 所以这里不需要任何 await —— 画布永远是同步画一帧。
+     */
+    private drawImageShape;
     private drawIcon;
     private drawUmlClass;
     /**
@@ -1775,6 +1927,14 @@ declare class Renderer {
      * 独立于选中态 —— 锁定的图形通常选不中，得靠这枚锁告诉用户「它为什么点不动」。
      */
     private drawLockBadge;
+    /**
+     * 锁定组的统一标记：整组只画**一把锁**，挂在组包围盒顶部居中，
+     * 而不是组里每个成员各挂一把（一堆锁没法看）。只要组处于锁定状态就画，
+     * 与选中无关（锁定的组本来也选不中，这枚锁就是唯一的视觉提示）。
+     */
+    private drawGroupLockBadges;
+    /** 在指定位置（徽标左上角，世界坐标）画一枚挂锁徽标 */
+    private drawLockBadgeAt;
     /**
      * 组外框：选中集恰好是一个完整的组（且不止一个成员）时，给整组描一圈虚线，
      * 提示「这些图形是绑在一起的」。整组锁定的成员画不到（成员不可选），不需要外框。
@@ -1828,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;
 
@@ -1914,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;
@@ -2564,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, isFlippableShapeType, 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 };