@8btc/whiteboard 0.0.20-alpha.4 → 0.0.20-alpha.40

package/dist/index.d.ts

@@ -1,25 +1,47 @@
 import { default as default_2 } from 'konva';
+import { Editor } from '@tiptap/core';
 import { JSX } from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { Transformer as Transformer_2 } from 'konva/lib/shapes/Transformer';
+
+/**
+ * 箭头节点配置
+ */
+declare type ArrowNodeConfig = BaseNodeConfig & default_2.ArrowConfig & Partial<NodeStyle> & {
+    $_type: "arrow";
+};
 
 declare interface BaseNodeConfig {
     id: string;
     x: number;
     y: number;
+    visible?: boolean;
+    $_listening?: boolean;
 }
 
+/**
+ * 笔刷节点配置（自由绘制）
+ */
+declare type BrushNodeConfig = BaseNodeConfig & default_2.LineConfig & Partial<NodeStyle> & {
+    $_type: "brush";
+    points: number[];
+};
+
 /**
  * CanvasApi 是面向外部使用的公开 API 类
  * 继承自 CanvasCore，只暴露必要的公开方法
  */
 export declare class CanvasApi extends CanvasCore {
+    #private;
+    constructor(el: HTMLDivElement, options?: ConstructorParameters<typeof CanvasCore>[1]);
+    dispose(): void;
     /**
      * 获取所有可用的工具类型
      */
-    getAvailableTools(): ToolType[];
-    /**
-     * 设置当前工具类型
-     */
-    setToolType(type: ToolType): void;
+    getAvailableTools(): Array<{
+        type: ToolType;
+        meta?: Record<string, any>;
+    }>;
     /**
      * 手动创建多个节点
      * 如果你不知道自己在干什么，请使用更高层的封装方法，如 createImageNode
@@ -41,584 +63,852 @@ export declare class CanvasApi extends CanvasCore {
         y: number;
     }): void;
     /**
-     * 导出全部图形为图片
-     * @param options - 导出配置
-     * @returns DataURL 格式的图片数据
-     */
-    exportAsImage(options?: {
-        pixelRatio?: number;
-        mimeType?: string;
-        quality?: number;
-    }): string;
-    /**
-     * 导出当前选区为图片
-     * @param options - 导出配置
-     * @returns DataURL 格式的图片数据，如果没有选区则返回 null
-     */
-    exportSelectionAsImage(options?: {
-        pixelRatio?: number;
-        mimeType?: string;
-        quality?: number;
-        padding?: number;
-    }): string | null;
-    /**
-     * 导出带有标注的图片节点为图片
-     * @param id - 图片节点 ID
-     * @returns DataURL 格式的图片数据，如果节点或者 marker 不存在则返回 null
-     */
-    exportImageWithMarker(id: string, options?: {
-        pixelRatio?: number;
-        mimeType?: string;
-        quality?: number;
-        markerScale?: number;
-    }): string | null;
-    /**
-     * 删除当前选中的节点
-     * 如果删除的是 image 节点，会同步删除所有关联的 image-marker
-     */
-    deleteSelectedNodes(): void;
-    /**
-     * 更新节点样式属性
-     * @param nodeIds - 要更新的节点 ID 数组
-     * @param config - 要更新的属性配置
-     */
-    updateNodes(nodeIds: string[], config: Partial<NodeConfig>): void;
-    /**
-     * 更新选中节点的样式属性
-     * @param config - 要更新的属性配置
-     */
-    updateSelectedNodes(config: Partial<NodeConfig>): void;
-    /**
-     * 删除指定的节点
-     * 如果删除的是 image 节点，会同步删除所有关联的 image-marker
-     * @param nodeIds - 要删除的节点 ID 数组
-     * @returns 被删除的节点数据数组
-     */
-    deleteNodes(nodeIds: string[]): NodeConfig[];
-    /**
-     * 将节点移动到最上层
-     */
-    moveNodesToTop(nodeIds: string[]): void;
-    /**
-     * 将节点移动到最下层
-     */
-    moveNodesToBottom(nodeIds: string[]): void;
-    moveNodesUp(nodeIds: string[]): void;
-    moveNodesDown(nodeIds: string[]): void;
-    /**
-     * 滚动到内容区域
-     * - 如果提供了 nodeIds，将指定的节点居中显示
-     * - 如果没有提供 nodeIds 但有选中的节点，将选中节点居中显示
-     * - 如果没有选中节点，将所有内容居中显示
-     * @param options - 配置选项
-     * @param options.padding - 内容周围的留白，默认 50px
-     * @param options.scale - 是否自动调整缩放以适应内容，默认 false
-     * @param options.nodeIds - 要滚动到的节点 ID 数组
-     */
-    scrollToContent(options?: {
-        padding?: number;
-        scale?: boolean;
-        nodeIds?: string[];
-    }): void;
-    /**
-     * 导出当前状态
-     */
-    save(): CanvasSnapshot;
-    /**
-     * 从状态中恢复画布
-     */
-    restore(state: CanvasSnapshot): void;
-}
+     * 导出指定图片节点的底图、笔刷透明图和合成图
+     * @param imageId - 图片节点 ID
+     * @returns { base, brushOnly, composite } 三张 DataURL，若图片不存在返回 null
+         */
+     exportImageWithBrush(imageId: string, options?: {
+         pixelRatio?: number;
+     }): {
+         base: string;
+         brushOnly: string;
+         composite: string;
+     } | null;
+     /**
+      * 删除指定图片节点关联的所有笔刷节点
+      * @param imageId - 图片节点 ID
+      */
+     clearImageBrushNodes(imageId: string): void;
+     /**
+      * 导出全部图形为图片
+      * @param options - 导出配置
+      * @returns DataURL 格式的图片数据
+      */
+     exportAsImage(options?: {
+         pixelRatio?: number;
+         mimeType?: string;
+         quality?: number;
+     }): string;
+     /**
+      * 导出当前选区为图片
+      * @param options - 导出配置
+      * @returns DataURL 格式的图片数据，如果没有选区则返回 null
+      */
+     exportSelectionAsImage(options?: {
+         pixelRatio?: number;
+         mimeType?: string;
+         quality?: number;
+         padding?: number;
+     }): string | null;
+     /**
+      * 导出带有标注的图片节点为图片
+      * @param id - 图片节点 ID
+      * @returns DataURL 格式的图片数据，如果节点或者 marker 不存在则返回 null
+      */
+     exportImageWithMarker(id: string, options?: {
+         pixelRatio?: number;
+         mimeType?: string;
+         quality?: number;
+         markerScale?: number;
+     }): string | null;
+     /**
+      * 删除当前选中的节点
+      * 如果删除的是 image 节点，会同步删除所有关联的 image-marker
+      */
+     deleteSelectedNodes(): void;
+     /**
+      * 对指定图片节点（或当前选中节点）进入裁剪模式
+      * @param id - 图片节点 ID，不传则使用当前选中节点
+      */
+     startImageCrop(id?: string): void;
+     /**
+      * 确认裁剪并退出裁剪模式（保存结果）
+      * @param id - 图片节点 ID，不传则使用当前选中节点
+      */
+     confirmImageCrop(id?: string): void;
+     /**
+      * 重置指定图片节点（或当前选中节点）的裁剪，还原为完整图片
+      * @param id - 图片节点 ID，不传则使用当前选中节点
+      */
+     resetImageCrop(id?: string): void;
+     /**
+      * 设置裁剪模式下底图的缩放倍数（≥1，以裁剪框中心为锚点）
+      * @param id - 图片节点 ID
+      * @param scale - 缩放倍数
+      */
+     setCropOverlayScale(id: string, scale: number): void;
+     /**
+      * 设置裁剪模式下底图的透明度（0~1）
+      * @param id - 图片节点 ID
+      * @param opacity - 透明度值
+      */
+     setCropOverlayOpacity(id: string, opacity: number): void;
+     /**
+      * 选中指定节点
+      * @param nodeIds - 要选中的节点 ID 数组，不传则取消所有选中
+      * @param multiSelect - 是否多选（追加到已选中节点），默认 false
+      */
+     selectNodes(nodeIds?: string[], multiSelect?: boolean): void;
+     /**
+      * 更新节点样式属性
+      * @param nodeIds - 要更新的节点 ID 数组
+      * @param config - 要更新的属性配置
+      */
+     updateNodes(nodeIds: string[], config: Partial<NodeConfig>): void;
+     /**
+      * 更新选中节点的样式属性
+      * @param config - 要更新的属性配置
+      */
+     updateSelectedNodes(config: Partial<NodeConfig>): void;
+     /**
+      * 删除指定的节点
+      * 如果删除的是 image 节点，会同步删除所有关联的 image-marker
+      * @param nodeIds - 要删除的节点 ID 数组
+      * @returns 被删除的节点数据数组
+      */
+     deleteNodes(nodeIds: string[]): NodeConfig[];
+     /**
+      * 将节点移动到最上层
+      */
+     moveNodesToTop(nodeIds: string[]): void;
+     /**
+      * 将节点移动到最下层
+      */
+     moveNodesToBottom(nodeIds: string[]): void;
+     moveNodesUp(nodeIds: string[]): void;
+     moveNodesDown(nodeIds: string[]): void;
+     /**
+      * 按照给定的 ID 数组顺序重新排列节点
+      * 数组中的第一个节点将位于最底层，最后一个节点位于最顶层
+      * @param nodeIds - 节点 ID 数组，按从底层到顶层的顺序排列
+      */
+     reorderNodes(nodeIds: string[]): void;
+     /**
+      * 滚动到内容区域
+      * - 如果提供了 nodeIds，将指定的节点居中显示
+      * - 如果没有提供 nodeIds 但有选中的节点，将选中节点居中显示
+      * - 如果没有选中节点，将所有内容居中显示
+      * @param options - 配置选项
+      * @param options.padding - 内容周围的留白，默认 50px
+      * @param options.scale - 是否自动调整缩放以适应内容，默认 false
+      * @param options.nodeIds - 要滚动到的节点 ID 数组
+      */
+     scrollToContent(options?: {
+         padding?: number;
+         scale?: boolean;
+         nodeIds?: string[];
+     }): void;
+     /**
+      * 导出当前状态
+      */
+     save(): CanvasSnapshot;
+     /**
+      * 从状态中恢复画布
+      */
+     restore(state: CanvasSnapshot): void;
+     /**
+      * 聚焦到指定节点
+      * 选中指定的节点并滚动到这些节点的位置
+      * @param nodeIds - 要聚焦的节点 ID 数组
+      * @param options - 滚动配置选项
+      * @param options.padding - 内容周围的留白，默认 50px
+      * @param options.scale - 是否自动调整缩放以适应内容，默认 false
+      */
+     focusNodes(nodeIds: string[], options?: {
+         padding?: number;
+         scale?: boolean;
+     }): void;
+     /**
+      * 切换指定节点的可见性
+      * @param nodeId - 要切换可见性的节点 ID
+      */
+     toggleNodeVisibility(nodeId: string): void;
+     /**
+      * 切换指定节点的锁定状态
+      * 锁定的节点无法被选中和交互（listening = false）
+      * @param nodeId - 要切换锁定状态的节点 ID
+      */
+     toggleNodeLock(nodeId: string): void;
+    }
+
+    declare class CanvasCore extends CanvasStore {
+        #private;
+        isEditingText: boolean;
+        constructor(el: HTMLDivElement, options?: {
+            state?: CanvasSnapshot;
+            theme?: Theme;
+        });
+        /**
+         * 获取当前主题
+         */
+        getTheme(): Theme;
+        /**
+         * 设置主题并重新渲染
+         */
+        setTheme(theme: Theme): void;
+        /**
+         * 获取 CanvasStage 实例
+         */
+        getCanvasStage(): CanvasStage;
+        /**
+         * 获取 CanvasTransformer 实例
+         */
+        getCanvasTransformer(): CanvasTransformer;
+        /**
+         * 获取 Konva.Transformer 实例
+         */
+        getTransformer(): Transformer_2;
+        /**
+         * 获取 Konva.Stage 实例
+         */
+        getStage(): default_2.Stage;
+        /**
+         * 获取 Stage 容器元素
+         */
+        getContainer(): HTMLDivElement;
+        /**
+         * 获取主图层
+         */
+        getMainLayer(): default_2.Layer;
+        /**
+         * 获取当前工具类型
+         */
+        getToolType(): ToolType;
+        /**
+         * 获取当前工具的元数据
+         */
+        getToolMeta(): Record<string, any> | undefined;
+        /**
+         * 设置当前工具类型（内部使用）
+         *
+         * toolMeta 是一个可选的对象，可以包含与当前工具相关的任何额外信息。例如，在绘制图形时，toolMeta 可以包含初始位置、颜色、线条样式等信息。这样，在处理工具逻辑时，就可以访问这些元数据来实现更复杂的行为。
+         *
+         * - polygon 工具可以在 toolMeta 中包含一个 $_shape 字段，指示要绘制的多边形形状（如 triangle、rectangle、pentagon 等），以便在创建草稿节点时生成对应形状的点数据。
+         */
+        setToolType(type: ToolType, toolMeta?: any): void;
+        /**
+         * 根据 ID 获取 Canvas 节点实例
+         */
+        getCanvasNodeById(id: string): CanvasNode | null;
+        /**
+         * 设置是否可拖拽（内部使用）
+         */
+        protected setDraggable(draggable: boolean): void;
+        /* Excluded from this release type: _setCursor */
+        /* Excluded from this release type: _resetCursor */
+        /**
+         * 获取当前 Stage 缩放比例
+         */
+        getStageScale(): number;
+        /* Excluded from this release type: _updateViewport */
+        protected createNodes(nodes: NodeConfig[], addToHistory: boolean): void;
+        /**
+         * 创建图片标注节点（内部使用）
+         */
+        protected createImageMarkerNode(parentImageId: string, startPosition: {
+            x: number;
+            y: number;
+        }, endPosition: {
+            x: number;
+            y: number;
+        }, imageBounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }): void;
+        /* Excluded from this release type: _findImageAtPosition */
+        /* Excluded from this release type: _setDrawingPosition */
+        /* Excluded from this release type: _updateDrawingPosition */
+        /* Excluded from this release type: _createDraftNode */
+        /* Excluded from this release type: _updateDraftNode */
+        /* Excluded from this release type: _appendBrushPoint */
+        /* Excluded from this release type: _finalizeDraftNode */
+        /* Excluded from this release type: _createTextNodeAtDrawingPosition */
+        /* Excluded from this release type: _createSelectRect */
+        _updateSelectRect(): void;
+        /* Excluded from this release type: _finalizeSelectRect */
+        /* Excluded from this release type: _selectNodes */
+        /* Excluded from this release type: deleteNodes */
+        /* Excluded from this release type: deleteSelectedNodes */
+        /* Excluded from this release type: _getKeyboardEl */
+        /**
+         * 销毁 canvas
+         */
+        dispose(): void;
+        /* Excluded from this release type: _rebuildStateAfterNodeChange */
+        /**
+         * 实现父类的状态同步方法
+         * 当 undo/redo 时被调用
+         */
+        protected _renderCanvas(state: CanvasSnapshot): void;
+        _showContextMenu(data: {
+            x: number;
+            y: number;
+            clientX: number;
+            clientY: number;
+            targetIds: string[];
+        }): void;
+        _syncNodesZIndexToStore(): void;
+        _registerTextEditor(editor: Editor): void;
+        _unregisterTextEditor(): void;
+    }
+
+    /**
+     * 状态事件类型定义
+     */
+    declare type CanvasEvents = {
+        "state:change": CanvasSnapshot;
+        "state:undo": CanvasSnapshot;
+        "state:redo": CanvasSnapshot;
+        "state:reset": CanvasSnapshot;
+        "viewport:change": CanvasSnapshot["viewport"];
+        "viewport:scale:change": number;
+        "transformer:positionChange": TransformerPosition | null;
+        "toolType:change": {
+            type: CanvasSnapshot["toolType"];
+            meta?: Record<string, any>;
+        };
+        "theme:change": Theme;
+        "nodes:created": NodeConfig[];
+        "nodes:deleted": NodeConfig[];
+        "nodes:selected": string[];
+        "contextmenu:show": {
+            x: number;
+            y: number;
+            clientX: number;
+            clientY: number;
+            targetIds: string[];
+        };
+        "nodes:sorted": string[];
+        "texteditor:register": any;
+        "texteditor:unregister": void;
+        /** 进入裁剪模式：携带裁剪框在容器内的初始位置（px） */
+        "crop:start": {
+            nodeId: string;
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        /** 退出裁剪模式 */
+        "crop:end": {
+            nodeId: string;
+        };
+        /** 裁剪框位置/尺寸更新（用于同步工具栏位置） */
+        "crop:frameChange": {
+            nodeId: string;
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
 
-declare class CanvasCore extends CanvasStore {
-    #private;
-    constructor(el: HTMLDivElement, options?: {
-        state?: CanvasSnapshot;
-        theme?: Theme;
-    });
-    /**
-     * 获取当前主题
-     */
-    getTheme(): Theme;
-    /**
-     * 设置主题并重新渲染
-     */
-    setTheme(theme: Theme): void;
-    /**
-     * 获取 CanvasStage 实例
-     */
-    getCanvasStage(): CanvasStage;
-    /**
-     * 获取 CanvasTransformer 实例
-     */
-    getCanvasTransformer(): CanvasTransformer;
-    /**
-     * 获取 Konva.Stage 实例
-     */
-    getStage(): default_2.Stage;
-    /**
-     * 获取 Stage 容器元素
-     */
-    getContainer(): HTMLDivElement;
-    /**
-     * 获取主图层
-     */
-    getMainLayer(): default_2.Layer;
-    /**
-     * 获取当前工具类型
-     */
-    getToolType(): ToolType;
-    /**
-     * 设置当前工具类型（内部使用）
-     */
-    setToolType(type: ToolType): void;
-    /**
-     * 根据 ID 获取 Canvas 节点实例
-     */
-    getCanvasNodeById(id: string): CanvasNode | null;
-    /**
-     * 设置是否可拖拽（内部使用）
-     */
-    protected setDraggable(draggable: boolean): void;
-    /* Excluded from this release type: _setCursor */
-    /* Excluded from this release type: _resetCursor */
-    /**
-     * 获取当前 Stage 缩放比例
-     */
-    getStageScale(): number;
-    /* Excluded from this release type: _updateViewport */
-    protected createNodes(nodes: NodeConfig[], addToHistory: boolean): void;
-    /**
-     * 创建图片标注节点（内部使用）
-     */
-    protected createImageMarkerNode(parentImageId: string, startPosition: {
-        x: number;
-        y: number;
-    }, endPosition: {
-        x: number;
-        y: number;
-    }, imageBounds: {
+    export declare interface CanvasNode {
+        getID(): string;
+        getElement(): default_2.Shape | default_2.Group;
+        getConfig(): NodeConfig;
+        syncConfigFromElement(): void;
+        update(config: Partial<NodeConfig>): void;
+        destroy(): void;
+    }
+
+    export declare interface CanvasSnapshot {
+        viewport: Viewport;
+        toolType: ToolType;
+        toolMeta?: any;
+        selectedNodeIds?: string[];
+        nodes?: NodeConfig[];
+    }
+
+    /**
+     * CanvasStage 封装了 Konva.Stage 的核心功能
+     * 提供视口管理、事件处理、拖拽和缩放等能力
+     */
+    declare class CanvasStage {
+        #private;
+        constructor(core: CanvasCore, config: StageConfig);
+        /**
+         * 获取原生 Konva.Stage 实例
+         */
+        getStage(): default_2.Stage;
+        /**
+         * 获取当前视口状态
+         */
+        getViewport(): ViewportState;
+        /**
+         * 设置视口（包括位置、缩放和尺寸）
+         */
+        setViewport(viewport: Partial<ViewportState>): void;
+        /**
+         * 设置是否可拖拽
+         */
+        setDraggable(draggable: boolean): void;
+        /**
+         * 设置光标样式
+         */
+        setCursor(cursor: string): void;
+        /**
+         * 重置光标样式
+         */
+        resetCursor(): void;
+        destroy(): void;
+    }
+
+    /**
+     * CanvasStore 类负责管理画布的状态
+     * 包括历史记录（past/present/future）和状态监听
+     */
+    declare abstract class CanvasStore {
+        #private;
+        constructor(initialState: CanvasSnapshot);
+        /**
+         * 获取当前状态
+         */
+        getState(): CanvasSnapshot;
+        /**
+         * 获取完整历史状态
+         */
+        getHistory(): HistoryState<CanvasSnapshot>;
+        /**
+         * 是否可以撤销
+         */
+        canUndo(): boolean;
+        /**
+         * 是否可以重做
+         */
+        canRedo(): boolean;
+        /**
+         * 订阅状态事件
+         */
+        on<K extends keyof CanvasEvents>(event: K, handler: (data: CanvasEvents[K]) => void): void;
+        /**
+         * 取消订阅状态事件
+         */
+        off<K extends keyof CanvasEvents>(event: K, handler: (data: CanvasEvents[K]) => void): void;
+        /* Excluded from this release type: _emit */
+        /**
+         * 撤销操作
+         */
+        undo(): void;
+        /**
+         * 重做操作
+         */
+        redo(): void;
+        /**
+         * 重置历史记录
+         */
+        resetHistory(): void;
+        /**
+         * 更新状态
+         * @param partial - 部分状态更新
+         * @param addToHistory - 是否添加到历史记录
+         */
+        protected _updateState(partial: Partial<CanvasSnapshot>, addToHistory: boolean): void;
+        /**
+         * 同步状态到 canvas 系统（由子类实现）
+         * @param _state - 要同步的状态
+         */
+        protected abstract _renderCanvas(_state: CanvasSnapshot): void;
+        /**
+         * 清理资源
+         */
+        protected _dispose(): void;
+    }
+
+    /**
+     * CanvasTransformer 封装了 Konva.Transformer 的核心功能
+     * 提供变换器管理、位置计算、事件处理等能力
+     */
+    declare class CanvasTransformer {
+        #private;
+        constructor(core: CanvasCore, config?: TransformerConfig);
+        /**
+         * 获取原生 Konva.Transformer 实例
+         */
+        getTransformer(): default_2.Transformer;
+        /**
+         * 获取 Transformer 的位置信息
+         */
+        getPosition(): TransformerPosition | null;
+        /**
+         * 设置要变换的节点
+         */
+        setNodes(nodes: default_2.Node[]): void;
+        /**
+         * 获取当前变换的节点
+         */
+        getNodes(): default_2.Node[];
+        /**
+         * 清除所有节点
+         */
+        clearNodes(): void;
+        /**
+         * emit Transformer 位置
+         */
+        emitPositionChange(): void;
+        /**
+         * 销毁 Transformer
+         */
+        destroy(): void;
+    }
+
+    export declare interface ContextMenuItem {
+        label: string;
+        action: () => void;
+    }
+
+    export declare interface ContextMenuState {
         x: number;
         y: number;
-        width: number;
-        height: number;
-    }): void;
-    /* Excluded from this release type: _findImageAtPosition */
-    /* Excluded from this release type: _setDrawingPosition */
-    /* Excluded from this release type: _updateDrawingPosition */
-    /* Excluded from this release type: _createDraftNode */
-    /* Excluded from this release type: _updateDraftNode */
-    /* Excluded from this release type: _finalizeDraftNode */
-    /* Excluded from this release type: _createTextNodeAtDrawingPosition */
-    /* Excluded from this release type: _createSelectRect */
-    _updateSelectRect(): void;
-    /* Excluded from this release type: _finalizeSelectRect */
-    /* Excluded from this release type: _selectNodes */
-    /* Excluded from this release type: deleteNodes */
-    /* Excluded from this release type: deleteSelectedNodes */
-    /**
-     * 销毁 canvas
-     */
-    dispose(): void;
-    /* Excluded from this release type: _rebuildStateAfterNodeChange */
+        items: ContextMenuItem[];
+    }
+
     /**
-     * 实现父类的状态同步方法
-     * 当 undo/redo 时被调用
+     * 图片裁剪变换数据
+     * 描述图像位图在裁剪区域内的位置、缩放和旋转
      */
-    protected _renderCanvas(state: CanvasSnapshot): void;
-    _showContextMenu(data: {
-        x: number;
-        y: number;
-        clientX: number;
-        clientY: number;
-        targetIds: string[];
-    }): void;
-    _syncNodesZIndexToStore(): void;
-}
-
-/**
- * 状态事件类型定义
- */
-declare type CanvasEvents = {
-    "state:change": CanvasSnapshot;
-    "state:undo": CanvasSnapshot;
-    "state:redo": CanvasSnapshot;
-    "state:reset": CanvasSnapshot;
-    "viewport:change": CanvasSnapshot["viewport"];
-    "viewport:scale:change": number;
-    "transformer:positionChange": TransformerPosition | null;
-    "toolType:change": CanvasSnapshot["toolType"];
-    "theme:change": Theme;
-    "nodes:created": NodeConfig[];
-    "nodes:deleted": NodeConfig[];
-    "nodes:selected": string[];
-    "contextmenu:show": {
+    declare type CropTransform = {
         x: number;
         y: number;
-        clientX: number;
-        clientY: number;
-        targetIds: string[];
+        width: number;
+        height: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
     };
-    "nodes:sorted": string[];
-};
 
-export declare interface CanvasNode {
-    getID(): string;
-    getElement(): default_2.Shape | default_2.Group;
-    getConfig(): NodeConfig;
-    syncConfigFromElement(): void;
-    update(config: Partial<NodeConfig>): void;
-    destroy(): void;
-}
+    export declare const DARK_THEME: Theme;
 
-export declare interface CanvasSnapshot {
-    viewport: Viewport;
-    toolType: ToolType;
-    selectedNodeIds?: string[];
-    nodes?: NodeConfig[];
-}
+    export declare const DEFAULT_THEME: Theme;
 
-/**
- * CanvasStage 封装了 Konva.Stage 的核心功能
- * 提供视口管理、事件处理、拖拽和缩放等能力
- */
-declare class CanvasStage {
-    #private;
-    constructor(core: CanvasCore, config: StageConfig);
-    /**
-     * 获取原生 Konva.Stage 实例
-     */
-    getStage(): default_2.Stage;
-    /**
-     * 获取当前视口状态
-     */
-    getViewport(): ViewportState;
-    /**
-     * 设置视口（包括位置、缩放和尺寸）
-     */
-    setViewport(viewport: Partial<ViewportState>): void;
-    /**
-     * 设置是否可拖拽
-     */
-    setDraggable(draggable: boolean): void;
-    /**
-     * 设置光标样式
-     */
-    setCursor(cursor: string): void;
-    /**
-     * 重置光标样式
-     */
-    resetCursor(): void;
     /**
-     * 销毁 Stage
+     * 椭圆节点配置
      */
-    destroy(): void;
-}
+    declare type EllipseNodeConfig = BaseNodeConfig & default_2.EllipseConfig & Partial<NodeStyle> & {
+        $_type: "ellipse";
+    };
 
-/**
- * CanvasStore 类负责管理画布的状态
- * 包括历史记录（past/present/future）和状态监听
- */
-declare abstract class CanvasStore {
-    #private;
-    constructor(initialState: CanvasSnapshot);
-    /**
-     * 获取当前状态
-     */
-    getState(): CanvasSnapshot;
-    /**
-     * 获取完整历史状态
-     */
-    getHistory(): HistoryState<CanvasSnapshot>;
-    /**
-     * 是否可以撤销
-     */
-    canUndo(): boolean;
-    /**
-     * 是否可以重做
-     */
-    canRedo(): boolean;
-    /**
-     * 订阅状态事件
-     */
-    on<K extends keyof CanvasEvents>(event: K, handler: (data: CanvasEvents[K]) => void): void;
-    /**
-     * 取消订阅状态事件
-     */
-    off<K extends keyof CanvasEvents>(event: K, handler: (data: CanvasEvents[K]) => void): void;
-    /* Excluded from this release type: _emit */
     /**
-     * 撤销操作
+     * 字体替换选区节点配置
      */
-    undo(): void;
-    /**
-     * 重做操作
-     */
-    redo(): void;
-    /**
-     * 重置历史记录
-     */
-    resetHistory(): void;
-    /**
-     * 更新状态
-     * @param partial - 部分状态更新
-     * @param addToHistory - 是否添加到历史记录
-     */
-    protected _updateState(partial: Partial<CanvasSnapshot>, addToHistory: boolean): void;
-    /**
-     * 同步状态到 canvas 系统（由子类实现）
-     * @param _state - 要同步的状态
-     */
-    protected abstract _renderCanvas(_state: CanvasSnapshot): void;
-    /**
-     * 清理资源
-     */
-    protected _dispose(): void;
-}
+    declare type FontReplaceNodeConfig = BaseNodeConfig & default_2.RectConfig & Partial<NodeStyle> & {
+        $_type: "font-replace";
+        width: number;
+        height: number;
+        $_parentId: string;
+        $_relativeBox: {
+            start: {
+                ratioX: number;
+                ratioY: number;
+            };
+            end: {
+                ratioX: number;
+                ratioY: number;
+            };
+        };
+        $_status: "selecting" | "confirming" | "processing" | "done" | "error";
+        $_bounds?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+
+    declare type HistoryState<T> = {
+        past: T[];
+        present: T;
+        future: T[];
+    };
 
-/**
- * CanvasTransformer 封装了 Konva.Transformer 的核心功能
- * 提供变换器管理、位置计算、事件处理等能力
- */
-declare class CanvasTransformer {
-    #private;
-    constructor(core: CanvasCore, config?: TransformerConfig);
-    /**
-     * 获取原生 Konva.Transformer 实例
-     */
-    getTransformer(): default_2.Transformer;
     /**
-     * 获取 Transformer 的位置信息
+     * HTML 节点配置
      */
-    getPosition(): TransformerPosition | null;
+    export declare type HtmlNodeConfig = BaseNodeConfig & default_2.RectConfig & Partial<NodeStyle> & {
+        $_type: "html";
+        $_actualType: string;
+        $_htmlContent: string;
+    };
+
     /**
-     * 设置要变换的节点
+     * 图片笔刷节点配置（仅在绑定图片范围内涂抹）
      */
-    setNodes(nodes: default_2.Node[]): void;
+    declare type ImageBrushNodeConfig = BaseNodeConfig & default_2.LineConfig & Partial<NodeStyle> & {
+        $_type: "image-brush";
+        points: number[];
+        $_imageId: string;
+        $_imageBounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+
     /**
-     * 获取当前变换的节点
+     * 图片标注节点配置
      */
-    getNodes(): default_2.Node[];
+    export declare type ImageMarkerNodeConfig = BaseNodeConfig & default_2.RectConfig & Partial<NodeStyle> & {
+        $_type: "image-marker";
+        width: number;
+        height: number;
+        $_markerNumber: number;
+        $_parentId: string;
+        $_relativeBox: {
+            start: {
+                ratioX: number;
+                ratioY: number;
+            };
+            end: {
+                ratioX: number;
+                ratioY: number;
+            };
+        };
+        $_bounds?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+
     /**
-     * 清除所有节点
-     */
-    clearNodes(): void;
+     * 图片节点配置
+     */
+    export declare type ImageNodeConfig = BaseNodeConfig & Omit<default_2.ImageConfig, "image"> & Partial<NodeStyle> & {
+        $_type: "image";
+        $_imageUrl: string;
+        $_cropTransform?: CropTransform | null;
+        $_applyBlurFilter?: boolean;
+        $_applyBrightnessFilter?: boolean;
+        $_applyRGBFilter?: boolean;
+        $_applyHSLFilter?: boolean;
+        red?: number;
+        green?: number;
+        blue?: number;
+        hue?: number;
+        saturation?: number;
+        luminance?: number;
+        image?: CanvasImageSource | undefined;
+    };
+
+    export declare const NODE_NAMES: {
+        nodeRoot: string;
+        selectable: string;
+        rect: string;
+        image: string;
+        imageMarker: string;
+        html: string;
+        text: string;
+        richText: string;
+        video: string;
+        star: string;
+        ellipse: string;
+        polygon: string;
+        arrow: string;
+        brush: string;
+        imageBrush: string;
+        fontReplace: string;
+    };
+
     /**
-     * emit Transformer 位置
+     * 节点配置联合类型（判别联合）
+     * 根据 $_type 字段可以自动推断出对应节点的特定字段
      */
-    emitPositionChange(): void;
+    export declare type NodeConfig = RectangleNodeConfig | ImageNodeConfig | ImageMarkerNodeConfig | HtmlNodeConfig | TextNodeConfig | RichTextNodeConfig | VideoNodeConfig | StarNodeConfig | EllipseNodeConfig | PolygonNodeConfig | ArrowNodeConfig | BrushNodeConfig | ImageBrushNodeConfig | FontReplaceNodeConfig;
+
     /**
-     * 销毁 Transformer
+     * 根据节点类型获取对应的配置类型
+     * @example NodeConfigByType<"image"> = ImageNodeConfig
      */
-    destroy(): void;
-}
-
-export declare interface ContextMenuItem {
-    label: string;
-    action: () => void;
-}
-
-export declare interface ContextMenuState {
-    x: number;
-    y: number;
-    items: ContextMenuItem[];
-}
-
-export declare const DARK_THEME: Theme;
+    export declare type NodeConfigByType<T extends NodeType> = Extract<NodeConfig, {
+        $_type: T;
+    }>;
 
-export declare const DEFAULT_THEME: Theme;
+    declare interface NodeStyle {
+        $_strokeColor: ThemeKeysStartingWith<"theme.stroke-color."> | string;
+        $_fillColor: ThemeKeysStartingWith<"theme.fill-color."> | string;
+    }
 
-declare type HistoryState<T> = {
-    past: T[];
-    present: T;
-    future: T[];
-};
-
-/**
- * HTML 节点配置
- */
-export declare type HtmlNodeConfig = BaseNodeConfig & default_2.RectConfig & Partial<NodeStyle> & {
-    $_type: "html";
-    $_actualType: string;
-    $_htmlContent: string;
-};
+    export declare type NodeType = "rectangle" | "image" | "image-marker" | "html" | "text" | "rich-text" | "video" | "star" | "ellipse" | "polygon" | "arrow" | "brush" | "image-brush" | "font-replace";
 
-/**
- * 图片标注节点配置
- */
-export declare type ImageMarkerNodeConfig = BaseNodeConfig & default_2.RectConfig & Partial<NodeStyle> & {
-    $_type: "image-marker";
-    width: number;
-    height: number;
-    $_markerNumber: number;
-    $_parentId: string;
-    $_relativeBox: {
-        start: {
-            ratioX: number;
-            ratioY: number;
-        };
-        end: {
-            ratioX: number;
-            ratioY: number;
-        };
+    /**
+     * 多边形节点配置
+     */
+    declare type PolygonNodeConfig = BaseNodeConfig & default_2.LineConfig & Partial<NodeStyle> & {
+        $_type: "polygon";
+        $_shape: "triangle" | "diamond" | "hexagon";
     };
-    $_bounds?: {
-        x: number;
-        y: number;
+
+    /**
+     * 矩形节点配置
+     */
+    export declare type RectangleNodeConfig = BaseNodeConfig & default_2.RectConfig & Partial<NodeStyle> & {
+        $_type: "rectangle";
         width: number;
         height: number;
     };
-};
-
-/**
- * 图片节点配置
- */
-export declare type ImageNodeConfig = BaseNodeConfig & Omit<default_2.ImageConfig, "image"> & Partial<NodeStyle> & {
-    $_type: "image";
-    $_imageUrl: string;
-    image?: CanvasImageSource | undefined;
-};
-
-export declare const NODE_NAMES: {
-    nodeRoot: string;
-    selectable: string;
-    rect: string;
-    image: string;
-    imageMarker: string;
-    html: string;
-    text: string;
-    richText: string;
-    video: string;
-};
-
-/**
- * 节点配置联合类型（判别联合）
- * 根据 $_type 字段可以自动推断出对应节点的特定字段
- */
-export declare type NodeConfig = RectangleNodeConfig | ImageNodeConfig | ImageMarkerNodeConfig | HtmlNodeConfig | TextNodeConfig | RichTextNodeConfig | VideoNodeConfig;
-
-/**
- * 根据节点类型获取对应的配置类型
- * @example NodeConfigByType<"image"> = ImageNodeConfig
- */
-export declare type NodeConfigByType<T extends NodeType> = Extract<NodeConfig, {
-    $_type: T;
-}>;
-
-declare interface NodeStyle {
-    $_strokeColor: ThemeKeysStartingWith<"theme.stroke-color."> | string;
-    $_fillColor: ThemeKeysStartingWith<"theme.fill-color."> | string;
-}
-
-export declare type NodeType = "rectangle" | "image" | "image-marker" | "html" | "text" | "rich-text" | "video";
 
-/**
- * 矩形节点配置
- */
-export declare type RectangleNodeConfig = BaseNodeConfig & default_2.RectConfig & Partial<NodeStyle> & {
-    $_type: "rectangle";
-    width: number;
-    height: number;
-};
+    declare type RichTextNodeConfig = BaseNodeConfig & default_2.ImageConfig & Partial<NodeStyle> & {
+        $_type: "rich-text";
+        $_htmlContent: string;
+    };
 
-declare type RichTextNodeConfig = BaseNodeConfig & default_2.RectConfig & Partial<NodeStyle> & {
-    $_type: "rich-text";
-    $_htmlContent: string;
-};
+    declare type StageConfig = {
+        container: HTMLDivElement;
+        width: number;
+        height: number;
+        draggable?: boolean;
+        className?: string;
+    };
 
-declare type StageConfig = {
-    container: HTMLDivElement;
-    width: number;
-    height: number;
-    draggable?: boolean;
-    className?: string;
-};
+    /**
+     * 星形节点配置
+     */
+    export declare type StarNodeConfig = BaseNodeConfig & default_2.StarConfig & Partial<NodeStyle> & {
+        $_type: "star";
+    };
 
-declare type TextNodeConfig = BaseNodeConfig & default_2.TextConfig & Partial<NodeStyle> & {
-    $_type: "text";
-    text: string;
-};
+    declare type TextNodeConfig = BaseNodeConfig & default_2.TextConfig & Partial<NodeStyle> & {
+        $_type: "text";
+        text: string;
+    };
 
-export declare interface Theme {
-    "theme.select-rect-border": string;
-    "theme.select-rect-fill": string;
-    "theme.image-marker-color": string;
-    "theme.stroke-color.1": string;
-    "theme.stroke-color.2": string;
-    "theme.stroke-color.3": string;
-    "theme.stroke-color.4": string;
-    "theme.stroke-color.5": string;
-    "theme.stroke-color.6": string;
-    "theme.fill-color.1": string;
-    "theme.fill-color.2": string;
-    "theme.fill-color.3": string;
-    "theme.fill-color.4": string;
-    "theme.fill-color.5": string;
-    "theme.fill-color.6": string;
-}
+    export declare interface Theme {
+        "theme.select-rect-border": string;
+        "theme.select-rect-fill": string;
+        "theme.image-marker-color": string;
+        "theme.stroke-color.1": string;
+        "theme.stroke-color.2": string;
+        "theme.stroke-color.3": string;
+        "theme.stroke-color.4": string;
+        "theme.stroke-color.5": string;
+        "theme.stroke-color.6": string;
+        "theme.fill-color.1": string;
+        "theme.fill-color.2": string;
+        "theme.fill-color.3": string;
+        "theme.fill-color.4": string;
+        "theme.fill-color.5": string;
+        "theme.fill-color.6": string;
+    }
+
+    export declare const THEME_PRESETS: {
+        readonly default: Theme;
+        readonly dark: Theme;
+    };
 
-export declare const THEME_PRESETS: {
-    readonly default: Theme;
-    readonly dark: Theme;
-};
+    declare type ThemeKeysStartingWith<Prefix extends string> = Extract<keyof Theme, `${Prefix}${string}`>;
 
-declare type ThemeKeysStartingWith<Prefix extends string> = Extract<keyof Theme, `${Prefix}${string}`>;
+    export declare type ThemePreset = keyof typeof THEME_PRESETS;
 
-export declare type ThemePreset = keyof typeof THEME_PRESETS;
+    export declare function TipTapBubbleMenu({ api, renderTextColorPicker }: TipTapBubbleMenuProps): JSX.Element | null;
 
-export declare type ToolType = "select" | "hand" | "rectangle" | "image-marker" | "text" | "rich-text";
+    declare interface TipTapBubbleMenuProps {
+        api: CanvasApi | null;
+        /**
+         * 自定义文字颜色选择器。传入一个接收 editor 的 render 函数，
+         * 返回的 ReactNode 会替换默认的 TextColorPopover。
+         * 可用于注入外部的 HSV 调色盘（如 react-colorful）。
+         */
+        renderTextColorPicker?: (editor: Editor) => ReactNode;
+    }
 
-declare type TransformerConfig = {
-    rotateEnabled?: boolean;
-    ignoreStroke?: boolean;
-    anchorSize?: number;
-    borderDash?: number[];
-    anchorCornerRadius?: number;
-    padding?: number;
-};
+    export declare type ToolType = "select" | "hand" | "rectangle" | "star" | "image-marker" | "text" | "rich-text" | "ellipse" | "polygon" | "arrow" | "brush" | "image-brush" | "font-replace";
 
-/**
- * 变换器（Transformer）位置信息
- */
-declare interface TransformerPosition {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    rotation?: number;
-}
+    declare type TransformerConfig = {
+        rotateEnabled?: boolean;
+        ignoreStroke?: boolean;
+        anchorSize?: number;
+        borderDash?: number[];
+        anchorCornerRadius?: number;
+        padding?: number;
+    };
 
-export declare function useContextMenu(api: CanvasApi | null): {
-    contextMenu: ContextMenuState | null;
-    closeContextMenu: () => void;
-};
+    /**
+     * 变换器（Transformer）位置信息
+     */
+    declare interface TransformerPosition {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        rotation?: number;
+    }
 
-declare type VideoNodeConfig = BaseNodeConfig & Omit<default_2.ImageConfig, "image"> & Partial<NodeStyle> & {
-    $_type: "video";
-    $_videoUrl: string;
-    $_coverUrl: string;
-    image?: CanvasImageSource | undefined;
-};
+    export declare function useContextMenu(api: CanvasApi | null): {
+        contextMenu: ContextMenuState | null;
+        closeContextMenu: () => void;
+    };
 
-declare interface Viewport {
-    x: number;
-    y: number;
-    scale: number;
-}
+    declare type VideoNodeConfig = BaseNodeConfig & Omit<default_2.ImageConfig, "image"> & Partial<NodeStyle> & {
+        $_type: "video";
+        $_videoUrl: string;
+        $_coverUrl: string;
+        image?: CanvasImageSource | undefined;
+    };
 
-declare type ViewportState = {
-    x: number;
-    y: number;
-    scale: number;
-    width?: number;
-    height?: number;
-};
+    declare interface Viewport {
+        x: number;
+        y: number;
+        scale: number;
+    }
 
-export declare function Whiteboard({ setApi, theme }: WhiteboardProps): JSX.Element;
+    declare type ViewportState = {
+        x: number;
+        y: number;
+        scale: number;
+        width?: number;
+        height?: number;
+    };
 
-declare interface WhiteboardProps {
-    setApi?: (core: CanvasApi) => void;
-    theme?: Theme;
-}
+    export declare function Whiteboard({ setApi, theme }: WhiteboardProps): JSX.Element;
 
-export { }
+    declare interface WhiteboardProps {
+        setApi?: (core: CanvasApi) => void;
+        theme?: Theme;
+    }
+
+    export { }
+
+
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        fontSize: {
+            setFontSize: (size: string) => ReturnType;
+            unsetFontSize: () => ReturnType;
+        };
+    }
+}
+
+
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        lineHeight: {
+            setLineHeight: (lineHeight: string) => ReturnType;
+            unsetLineHeight: () => ReturnType;
+        };
+    }
+}
+
+
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        letterSpacing: {
+            setLetterSpacing: (spacing: string) => ReturnType;
+            unsetLetterSpacing: () => ReturnType;
+        };
+    }
+}
+
+
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        nodeBackground: {
+            setNodeBackgroundColor: (backgroundColor: string) => ReturnType;
+            unsetNodeBackgroundColor: () => ReturnType;
+            toggleNodeBackgroundColor: (backgroundColor: string) => ReturnType;
+        };
+    }
+}