@blueking/flow-canvas 0.0.1-beta.3 → 0.0.1

package/dist/index.d.ts

@@ -1,33 +1,819 @@
-export type { FlowModel, FlowNodeModel, FlowEdgeModel, FlowPortModel, FlowEdgeLabelModel } from './types/flow-model';
-export { createEmptyFlowModel } from './types/flow-model';
-export type { CanvasSchema, CanvasNodeDefinition, CanvasEdgeDefinition, CanvasCallbackContext, CanvasMode, NodeBehaviorConfig, EdgeRenderState, EdgeStyle, } from './types/schema';
-export type { CanvasCommand, CommandEnvelope, CommandSource, CommandPreview, CommandRejection, CommandExecutionResult, CommandExecutionError, FlowModelChangeEvent, CanvasUiEvent, ScreenPosition, CanvasPosition, } from './types/command';
-export type { CanvasHistory, CanvasHistoryOptions } from './types/history';
-export type { CanvasPlugin, EditorPluginContext, RuntimePluginContext, CanvasSelection, NodeDecoration, EdgeDecoration, ContextMenuItem, } from './types/plugin';
-export type { CanvasApi, CanvasToolbarItem, BuiltinToolbarType, ExportOptions, NodeActionsConfig, QuickAddConfig, InsertNodeOptions, ConnectionValidator, ConnectionValidateContext, ConnectionValidateResult, NodePaletteItem, } from './types/api';
-export type { OverlayManager } from './types/overlay';
-export { applyCanvasCommand } from './core/apply-command';
-export { CanvasConstraintError, CanvasSchemaError } from './core/errors';
-export { createCanvasHistory } from './core/history';
-export { useCanvasEditor } from './core/editor';
-export type { CanvasEditorContext, CanvasEditorOptions } from './core/editor';
-export { default as CanvasRuntime } from './runtime/canvas-runtime-core.vue';
-export { default as CanvasLayout } from './shell/canvas-layout.vue';
-export { default as CanvasToolbar } from './shell/canvas-toolbar.vue';
-export { default as CanvasNodePalette } from './shell/canvas-node-palette.vue';
-export { default as DefaultNode } from './shell/default-node.vue';
-export { default as NodeActionsToolbar } from './shell/node-actions-toolbar.vue';
-export { default as NodeQuickAddPopover } from './shell/node-quick-add-popover.vue';
-export { createDefaultToolbarItems } from './shell/toolbar-items';
-export type { DefaultToolbarItemsOptions } from './shell/toolbar-items';
-export { createDefaultSchema } from './shell/default-schema';
-export type { DefaultNodeTypeConfig, DefaultSchemaOptions, DefaultSchemaResult } from './shell/default-schema';
-export { connectionValidatorPlugin } from './plugins/connection-validator';
-export { selectionPlugin } from './plugins/selection';
-export type { SelectionPluginOptions } from './plugins/selection';
-export { snaplinePlugin } from './plugins/snapline';
-export type { SnaplinePluginOptions } from './plugins/snapline';
-export { minimapPlugin } from './plugins/minimap';
-export type { MinimapPluginOptions } from './plugins/minimap';
-export { clipboardPlugin } from './plugins/clipboard';
-export { generateId } from './utils/uuid';
+import * as vue from 'vue';
+import { Ref, Component } from 'vue';
+import { Graph } from '@antv/x6';
+
+interface FlowModel {
+    version?: '1.0';
+    nodes: Record<string, FlowNodeModel>;
+    edges: Record<string, FlowEdgeModel>;
+    meta?: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+}
+interface FlowNodeModel {
+    id: string;
+    type: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    label?: string;
+    ports?: FlowPortModel[];
+    payload?: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+}
+interface FlowEdgeModel {
+    id: string;
+    type?: string;
+    source: {
+        nodeId: string;
+        portId?: string;
+    };
+    target: {
+        nodeId: string;
+        portId?: string;
+    };
+    labels?: FlowEdgeLabelModel[];
+    payload?: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+}
+interface FlowPortModel {
+    id: string;
+    group: 'top' | 'right' | 'bottom' | 'left' | string;
+    x6PortConfig?: Record<string, unknown>;
+}
+interface FlowEdgeLabelModel {
+    id: string;
+    text?: string;
+    position?: number;
+    payload?: Record<string, unknown>;
+}
+declare function createEmptyFlowModel(): FlowModel;
+
+type CanvasCommand = {
+    type: 'node.add';
+    node: FlowNodeModel;
+} | {
+    type: 'node.move';
+    nodeId: string;
+    position: {
+        x: number;
+        y: number;
+    };
+} | {
+    type: 'node.remove';
+    nodeId: string;
+} | {
+    type: 'node.update';
+    nodeId: string;
+    patch: Partial<Omit<FlowNodeModel, 'id' | 'payload' | 'extensions'>>;
+} | {
+    type: 'node.set-payload';
+    nodeId: string;
+    path: string[];
+    value: unknown;
+} | {
+    type: 'node.set-extensions';
+    nodeId: string;
+    path: string[];
+    value: unknown;
+} | {
+    type: 'edge.add';
+    edge: FlowEdgeModel;
+} | {
+    type: 'edge.remove';
+    edgeId: string;
+} | {
+    type: 'edge.reconnect';
+    edgeId: string;
+    source?: {
+        nodeId: string;
+        portId?: string;
+    };
+    target?: {
+        nodeId: string;
+        portId?: string;
+    };
+} | {
+    type: 'edge.update';
+    edgeId: string;
+    patch: Partial<Omit<FlowEdgeModel, 'id' | 'payload' | 'extensions'>>;
+} | {
+    type: 'edge.set-payload';
+    edgeId: string;
+    path: string[];
+    value: unknown;
+} | {
+    type: 'edge.label.update';
+    edgeId: string;
+    labelId: string;
+    patch: Partial<FlowEdgeLabelModel>;
+} | {
+    type: 'model.set-meta';
+    path: string[];
+    value: unknown;
+};
+type CommandSource = 'user:drag' | 'user:keyboard' | 'user:toolbar' | 'user:quick-add' | 'user:panel' | 'plugin' | 'system' | 'system:replace';
+interface CommandEnvelope {
+    id: string;
+    label?: string;
+    source: CommandSource;
+    timestamp: number;
+    commands: CanvasCommand[];
+}
+interface CommandExecutionResult {
+    status: 'applied' | 'rejected' | 'invalid';
+    envelope: Readonly<CommandEnvelope>;
+    flowModel?: FlowModel;
+    error?: CommandExecutionError;
+}
+interface CommandExecutionError {
+    code: 'plugin_rejected' | 'validation_failed' | 'constraint_violated';
+    reason: string;
+    source: string;
+    details?: unknown;
+}
+interface CommandRejection {
+    rejected: true;
+    reason: string;
+    code?: string;
+}
+interface CommandPreview {
+    previewFlowModel(commands?: CanvasCommand[]): FlowModel;
+}
+interface FlowModelChangeEvent {
+    flowModel: Readonly<FlowModel>;
+    prevFlowModel: Readonly<FlowModel>;
+    envelope: Readonly<CommandEnvelope>;
+    source: CommandSource;
+}
+type ScreenPosition = {
+    x: number;
+    y: number;
+};
+type CanvasPosition = {
+    x: number;
+    y: number;
+};
+type CanvasUiEvent = {
+    type: 'node.click';
+    nodeId: string;
+} | {
+    type: 'node.dblclick';
+    nodeId: string;
+} | {
+    type: 'node.contextmenu';
+    nodeId: string;
+    position: ScreenPosition;
+} | {
+    type: 'node.quick-add';
+    nodeId: string;
+    position: ScreenPosition;
+} | {
+    type: 'edge.click';
+    edgeId: string;
+} | {
+    type: 'edge.label.click';
+    edgeId: string;
+    labelId: string;
+} | {
+    type: 'blank.click';
+    position: CanvasPosition;
+} | {
+    type: 'blank.contextmenu';
+    position: ScreenPosition;
+} | {
+    type: 'selection.change';
+    nodeIds: string[];
+    edgeIds: string[];
+} | {
+    type: 'node.action.delete';
+    nodeId: string;
+} | {
+    type: 'node.action.copy';
+    sourceNodeId: string;
+    newNodeId: string;
+} | {
+    type: 'node.action.copy-insert';
+    sourceNodeId: string;
+    newNodeId: string;
+} | {
+    type: 'node.action.disconnect';
+    nodeId: string;
+    edgeIds: string[];
+} | {
+    type: 'node.action.debug';
+    nodeId: string;
+} | {
+    type: 'node.action.quick-insert';
+    sourceNodeId: string;
+    newNodeId: string;
+};
+
+interface CanvasHistory {
+    execute(envelope: CommandEnvelope): FlowModel;
+    undo(): FlowModel | null;
+    redo(): FlowModel | null;
+    readonly canUndo: Ref<boolean>;
+    readonly canRedo: Ref<boolean>;
+    readonly undoStack: readonly CommandEnvelope[];
+    readonly redoStack: readonly CommandEnvelope[];
+    clear(): void;
+    createSnapshot(): FlowModel;
+    replaceFlowModel(model: FlowModel): void;
+}
+interface CanvasHistoryOptions {
+    maxHistorySize?: number;
+}
+
+interface OverlayManager {
+    getNodeScreenRect(nodeId: string): DOMRect | null;
+}
+
+interface EditorPluginContext {
+    flowModel: Readonly<Ref<FlowModel>>;
+    history: CanvasHistory;
+    schema: CanvasSchema;
+    mode: Ref<CanvasMode>;
+    executeCommand(envelope: CommandEnvelope): CommandExecutionResult;
+}
+interface RuntimePluginContext extends EditorPluginContext {
+    api: CanvasApi;
+    overlay: OverlayManager;
+    graph: Graph;
+}
+interface CanvasSelection {
+    nodeIds: string[];
+    edgeIds: string[];
+}
+interface NodeDecoration {
+    className?: string;
+    badge?: {
+        text: string;
+        color: string;
+    };
+    borderColor?: string;
+}
+interface EdgeDecoration {
+    className?: string;
+    strokeColor?: string;
+}
+interface ContextMenuItem {
+    id: string;
+    label: string;
+    icon?: Component | string;
+    disabled?: boolean;
+    action: () => void;
+    children?: ContextMenuItem[];
+}
+interface CanvasPlugin {
+    name: string;
+    priority?: number;
+    install?(ctx: EditorPluginContext): void;
+    attachRuntime?(ctx: RuntimePluginContext): void;
+    detachRuntime?(): void;
+    dispose?(): void;
+    transformCommand?(envelope: Readonly<CommandEnvelope>, preview: CommandPreview, ctx: EditorPluginContext): CommandEnvelope | CommandRejection | null;
+    afterCommand?(envelope: Readonly<CommandEnvelope>, prevModel: Readonly<FlowModel>, newModel: Readonly<FlowModel>, ctx: EditorPluginContext): void;
+    onUiEvent?(event: CanvasUiEvent, ctx: RuntimePluginContext): void;
+    onSelectionChange?(selection: CanvasSelection, ctx: RuntimePluginContext): void;
+    onKeyboardShortcut?(event: KeyboardEvent, ctx: RuntimePluginContext): boolean;
+    onBlankContextMenu?(position: ScreenPosition, ctx: RuntimePluginContext): ContextMenuItem[] | void;
+    decorateNode?(node: FlowNodeModel, ctx: EditorPluginContext): NodeDecoration | void;
+    decorateEdge?(edge: FlowEdgeModel, ctx: EditorPluginContext): EdgeDecoration | void;
+    provideToolbarItems?(ctx: EditorPluginContext): CanvasToolbarItem[];
+    extendApi?(api: CanvasApi, ctx: RuntimePluginContext): Record<string, Function>;
+}
+
+type BuiltinToolbarType = 'undo' | 'redo' | 'select' | 'auto-layout' | 'search' | 'minimap' | 'export' | 'zoom-in' | 'zoom-out' | 'zoom-display' | 'fit' | 'reset';
+interface CanvasToolbarItem {
+    id: string;
+    type: BuiltinToolbarType | 'custom';
+    /** CSS 类名（字体图标） */
+    icon?: string;
+    /** Vue 组件，渲染在按钮内部作为图标/内容区域 */
+    component?: Component;
+    /** 无图标时的兜底显示文字 */
+    text?: string;
+    /** 操作说明文案，有值时 hover 按钮显示 CSS tooltip 气泡 */
+    description?: string;
+    group?: string;
+    order?: number;
+    visible?: boolean | ((ctx: CanvasCallbackContext) => boolean);
+    disabled?: boolean | ((ctx: CanvasCallbackContext) => boolean);
+    onClick?: (ctx: CanvasCallbackContext) => void;
+}
+interface ExportOptions {
+    backgroundColor?: string;
+    padding?: number;
+    quality?: number;
+}
+interface NodeActionsConfig {
+    showDebug?: boolean;
+    showDelete?: boolean;
+    showCopy?: boolean;
+    showCopyInsert?: boolean;
+    showDisconnect?: boolean;
+    insertGap?: number;
+}
+interface InsertNodeOptions {
+    autoWireEdges?: boolean;
+    gap?: number;
+    source?: CommandSource;
+    label?: string;
+    direction?: InsertDirection;
+}
+interface CanvasApi {
+    zoomIn(): void;
+    zoomOut(): void;
+    zoomTo(value: number): void;
+    zoomToFit(): void;
+    getZoom(): number;
+    centerContent(): void;
+    scrollToOrigin(): void;
+    scrollToNode(nodeId: string): void;
+    getSelection(): CanvasSelection;
+    selectNodes(ids: string[]): void;
+    selectEdges(ids: string[]): void;
+    clearSelection(): void;
+    registerDndSource(el: HTMLElement, factory: () => FlowNodeModel): () => void;
+    startConnection(nodeId: string, portId?: string): void;
+    exportAsImage(options?: ExportOptions): Promise<Blob>;
+    exportAsSVG(): Promise<string>;
+    highlightNodes(nodeIds: string[]): void;
+    highlightEdges(edgeIds: string[]): void;
+    clearHighlight(): void;
+    overlay: OverlayManager;
+    /** 收集所有插件为指定坐标提供的右键菜单项，由消费方自行渲染菜单 UI */
+    getContextMenuItems(position: ScreenPosition): ContextMenuItem[];
+    /**
+     * 默认在 sourceNode 右侧插入新节点，也可通过 options.direction 指定 top/right/bottom/left。
+     * - 位置：根据 direction 沿对应方向插入，并在垂直/水平方向居中对齐
+     * - autoWireEdges=true 时：优先使用 direction 对应的 source 端口与新节点的反向端口自动连线；
+     *   否则只创建 source→new 一条边
+     * - 所有命令打包在一个 CommandEnvelope 中原子执行
+     */
+    insertNodeToRight(sourceNodeId: string, node: Omit<FlowNodeModel, 'position'>, options?: InsertNodeOptions): CommandExecutionResult;
+    onGraphEvent<K extends string>(event: K, handler: (...args: unknown[]) => void): () => void;
+    unsafeGetGraph(): unknown;
+}
+interface ConnectionValidateContext {
+    flowModel: FlowModel;
+    sourceNode: FlowNodeModel;
+    targetNode: FlowNodeModel;
+    sourcePort?: FlowPortModel;
+    targetPort?: FlowPortModel;
+    existingEdges: FlowEdgeModel[];
+}
+type ConnectionValidateResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason?: string;
+};
+type ConnectionValidator = (ctx: ConnectionValidateContext) => ConnectionValidateResult;
+type InsertDirection = 'top' | 'right' | 'bottom' | 'left';
+type QuickAddPortResolver = (node: FlowNodeModel, ports: FlowPortModel[]) => string | FlowPortModel | null | undefined;
+type QuickAddInsertDirectionResolver = (node: FlowNodeModel, port: FlowPortModel | null) => InsertDirection | null | undefined;
+interface QuickAddConfig {
+    /** 全局开关，默认 true */
+    enabled?: boolean;
+    /** "+"按钮 hover 时的 tooltip 文案 */
+    tooltipText?: string;
+    /** quick-add 绑定的端口分组，默认 'right'；节点不存在该分组端口时将不显示 quick-add */
+    portGroup?: string;
+    /** 精确指定 quick-add 使用哪个端口；优先级高于 portGroup */
+    getPort?: QuickAddPortResolver;
+    /** 点击 quick-add 插入节点时使用的方向；默认跟随绑定 port 的标准方向，不可推断时回退为 'right' */
+    insertDirection?: InsertDirection | QuickAddInsertDirectionResolver;
+}
+interface NodePaletteItem {
+    type: string;
+    label: string;
+    icon?: string;
+}
+
+type CanvasMode = 'edit' | 'readonly' | 'thumbnail';
+interface CanvasSchema {
+    nodeTypes: Record<string, CanvasNodeDefinition>;
+    edgeTypes?: Record<string, CanvasEdgeDefinition>;
+    defaultEdgeType?: string;
+}
+interface NodeBehaviorConfig {
+    showActions?: boolean;
+    showPorts?: boolean;
+    draggable?: boolean;
+    selectable?: boolean;
+    deletable?: boolean;
+    connectable?: boolean;
+    copyable?: boolean;
+    disconnectable?: boolean;
+    debuggable?: boolean;
+    deleteDisabled?: boolean;
+    copyDisabled?: boolean;
+    copyInsertDisabled?: boolean;
+    disconnectDisabled?: boolean;
+    debugDisabled?: boolean;
+    /** 逐节点控制右侧"+"快捷添加按钮是否显示，默认跟随全局配置 */
+    quickAddEnabled?: boolean;
+    /** 快捷操作工具栏的位置偏移（px），相对于默认位置（节点右下角） */
+    actionsOffset?: {
+        x?: number;
+        y?: number;
+    };
+}
+interface CanvasNodeDefinition {
+    component: Component;
+    getSize: (node: FlowNodeModel) => {
+        width: number;
+        height: number;
+    };
+    getPorts?: (node: FlowNodeModel) => FlowPortModel[];
+    getBehavior?: (node: FlowNodeModel, ctx: CanvasCallbackContext) => NodeBehaviorConfig;
+    x6CellConfig?: Record<string, unknown>;
+}
+interface EdgeRenderState {
+    selected: boolean;
+    highlighted: boolean;
+    hovered: boolean;
+}
+interface EdgeStyle {
+    stroke?: string;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+}
+interface CanvasEdgeDefinition {
+    router?: string | {
+        name: string;
+        args?: Record<string, unknown>;
+    };
+    connector?: string | {
+        name: string;
+        args?: Record<string, unknown>;
+    };
+    /** 根据边模型和渲染状态（selected/highlighted/hovered）返回边的视觉样式 */
+    style?: (edge: FlowEdgeModel, state: EdgeRenderState) => EdgeStyle;
+    /**
+     * @experimental 边标签的自定义渲染组件。
+     * 当前版本尚未完整实现（X6 边标签基于 SVG，集成 Vue 组件需要 HTML overlay 方案）。
+     * 如需自定义标签样式，建议通过 x6EdgeConfig.defaultLabel 配置 X6 原生标签 markup。
+     */
+    labelRenderer?: Component;
+    labelDraggable?: boolean;
+    x6EdgeConfig?: Record<string, unknown>;
+}
+interface CanvasCallbackContext {
+    api: CanvasApi;
+    flowModel: FlowModel;
+    history: CanvasHistory;
+    mode: CanvasMode;
+}
+
+/**
+ * 纯函数 reducer：将一条原子命令应用到 FlowModel 上，返回新 FlowModel（不可变）。
+ * 所有 FlowModel 不变量在此处保证：
+ *  - 节点/边 id 唯一性
+ *  - 边端点必须指向存在的节点（及可选的 port）
+ *  - 删除节点时级联清理关联边
+ *  - label id 在同一条边内唯一
+ */
+declare function applyCanvasCommand(model: FlowModel, cmd: CanvasCommand): FlowModel;
+
+declare class CanvasConstraintError extends Error {
+    constructor(message: string);
+}
+declare class CanvasSchemaError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * 基于快照栈的历史系统。
+ *
+ * 每次 execute 时在 undo 栈中保存执行前的 FlowModel 快照，同时清空 redo 栈。
+ * undo 弹出上一个快照恢复 FlowModel；redo 重新执行对应 envelope 的命令序列。
+ *
+ * 注意：当前实现为完整快照，适用于中小规模 FlowModel。
+ * 若 payload 增长导致性能问题，后续可引入结构共享或 checkpoint + patch 混合模式。
+ */
+declare function createCanvasHistory(initialFlowModel: FlowModel, options?: CanvasHistoryOptions): CanvasHistory & {
+    currentFlowModel: Ref<FlowModel>;
+};
+
+/**
+ * 管理插件的安装、运行时挂载、命令管道和事件分发。
+ *
+ * 生命周期分两阶段：
+ *  1. install（editor 级）：在 useCanvasEditor 初始化时调用，此时只有 flowModel/history/schema 可用
+ *  2. attachRuntime（runtime 级）：在 CanvasRuntime mount 后调用，此时 api/graph/overlay 已就绪
+ *
+ * 命令管道（transformCommand）为不可变管道：
+ *  - 插件按 priority 升序执行
+ *  - 每个插件返回新 envelope 或 null（拒绝）或 CommandRejection
+ *  - 前一个插件的输出是下一个插件的输入
+ */
+declare class PluginManager {
+    private plugins;
+    private editorContext;
+    private runtimeCtx;
+    /** 每次 attachRuntime 递增，detachRuntime 时旧 generation 的异步调用自动作废 */
+    private runtimeVersion;
+    install(plugins: CanvasPlugin[], ctx: EditorPluginContext): void;
+    /**
+     * 挂载运行时上下文并调用各插件的 attachRuntime。
+     * 异步插件（如动态 import X6 插件）在 await 返回后会检查 generation，
+     * 若 detachRuntime 已被调用（generation 已变），则跳过 graph.use() 等操作。
+     */
+    attachRuntime(ctx: RuntimePluginContext): void;
+    /** 按安装的逆序 detach，保证后安装的插件先释放运行时资源 */
+    detachRuntime(): void;
+    /**
+     * 为 attachRuntime 创建保护代理：graph.use() 等可能在异步回调中调用，
+     * 如果在 await 期间 detachRuntime 已执行，代理会将 graph 操作变为 no-op。
+     */
+    private createSafeRuntimeContext;
+    dispose(): void;
+    transformCommand(envelope: Readonly<CommandEnvelope>): {
+        envelope: CommandEnvelope;
+    } | {
+        rejected: true;
+        error: CommandExecutionError;
+    };
+    afterCommand(envelope: Readonly<CommandEnvelope>, prevModel: Readonly<FlowModel>, newModel: Readonly<FlowModel>): void;
+    dispatchUiEvent(event: CanvasUiEvent): void;
+    dispatchSelectionChange(selection: CanvasSelection): void;
+    dispatchKeyboardShortcut(event: KeyboardEvent): boolean;
+    collectContextMenuItems(position: ScreenPosition): ContextMenuItem[];
+    /** 汇聚所有插件的工具栏项，相同 id 的后注册覆盖先注册，最终按 order 排序 */
+    collectToolbarItems(): CanvasToolbarItem[];
+    /** 合并所有插件对某节点的装饰（className / borderColor / badge），后注册覆盖先注册 */
+    collectNodeDecorations(node: FlowNodeModel): NodeDecoration | undefined;
+    /** 合并所有插件对某边的装饰（className / strokeColor），后注册覆盖先注册 */
+    collectEdgeDecorations(edge: FlowEdgeModel): EdgeDecoration | undefined;
+    collectExtendedApi(): Record<string, Function>;
+    /** 基于当前 FlowModel 和待执行命令序列，生成预览 FlowModel 供 transformCommand 使用 */
+    private createPreview;
+}
+
+interface CanvasEditorOptions {
+    initialFlowModel: FlowModel;
+    schema: CanvasSchema;
+    plugins?: CanvasPlugin[];
+    mode?: CanvasMode;
+    historyOptions?: CanvasHistoryOptions;
+    onCommandResult?(result: CommandExecutionResult): void;
+    onFlowModelChange?(event: FlowModelChangeEvent): void;
+}
+interface CanvasEditorContext {
+    flowModel: Readonly<Ref<FlowModel>>;
+    history: CanvasHistory;
+    schema: CanvasSchema;
+    mode: Ref<CanvasMode>;
+    executeCommand(envelope: CommandEnvelope): CommandExecutionResult;
+    replaceFlowModel(model: FlowModel): void;
+    setMode(mode: CanvasMode): void;
+    /** 框选模式：开启后左键拖拽画布空白区域为框选，关闭时为画布平移 */
+    selectionMode: Ref<boolean>;
+    setSelectionMode(enabled: boolean): void;
+    api: Ref<CanvasApi | null>;
+    toolbarItems: Readonly<Ref<CanvasToolbarItem[]>>;
+    extendedApi: Record<string, Function>;
+    /** @internal used by CanvasRuntime */
+    _pluginManager: PluginManager;
+}
+/**
+ * 画布编辑引擎的核心 composable。
+ *
+ * 初始化时完成：
+ *  1. 创建 CanvasHistory（快照栈）
+ *  2. 安装插件（editor-stage）
+ *  3. 暴露 executeCommand / replaceFlowModel / setMode 等 API
+ *
+ * api（CanvasApi）在 CanvasRuntime mount 后才由 runtime 注入。
+ * 在此之前 api.value === null，工具栏等依赖 api 的功能默认禁用。
+ *
+ * executeCommand 的完整管道：
+ *  pluginManager.transformCommand → history.execute → applyCanvasCommand
+ *  → pluginManager.afterCommand → onCommandResult → onFlowModelChange
+ */
+declare function useCanvasEditor(options: CanvasEditorOptions): CanvasEditorContext;
+
+type __VLS_Props$5 = {
+    editor: CanvasEditorContext;
+    graphOptions?: Record<string, unknown>;
+    nodeActions?: NodeActionsConfig;
+    quickAdd?: QuickAddConfig;
+};
+type __VLS_Slots$2 = {
+    'quick-add-panel'?: (props: {
+        node: FlowNodeModel;
+        api: CanvasApi;
+        insertNodeToRight: (node: Omit<FlowNodeModel, 'position'>) => void;
+        closePopover: () => void;
+    }) => unknown;
+};
+declare const __VLS_base$2: vue.DefineComponent<__VLS_Props$5, {}, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    "ui-event": (event: CanvasUiEvent) => any;
+}, string, vue.PublicProps, Readonly<__VLS_Props$5> & Readonly<{
+    "onUi-event"?: ((event: CanvasUiEvent) => any) | undefined;
+}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$6: __VLS_WithSlots$2<typeof __VLS_base$2, __VLS_Slots$2>;
+declare const _default$6: typeof __VLS_export$6;
+
+type __VLS_WithSlots$2<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+type __VLS_Props$4 = {
+    sidebarCollapsed?: boolean;
+    sidebarWidth?: number;
+    hideSidebar?: boolean;
+    hideFooter?: boolean;
+    editor?: CanvasEditorContext;
+    paletteItems?: NodePaletteItem[];
+};
+type __VLS_Slots$1 = {
+    sidebar?: () => unknown;
+    default?: () => unknown;
+    footer?: () => unknown;
+};
+declare const __VLS_base$1: vue.DefineComponent<__VLS_Props$4, {}, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    "update:sidebarCollapsed": (value: boolean) => any;
+}, string, vue.PublicProps, Readonly<__VLS_Props$4> & Readonly<{
+    "onUpdate:sidebarCollapsed"?: ((value: boolean) => any) | undefined;
+}>, {
+    editor: CanvasEditorContext;
+    sidebarCollapsed: boolean;
+    sidebarWidth: number;
+    hideSidebar: boolean;
+    hideFooter: boolean;
+    paletteItems: NodePaletteItem[];
+}, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$5: __VLS_WithSlots$1<typeof __VLS_base$1, __VLS_Slots$1>;
+declare const _default$5: typeof __VLS_export$5;
+
+type __VLS_WithSlots$1<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+type __VLS_Props$3 = {
+    items?: CanvasToolbarItem[];
+    exclude?: BuiltinToolbarType[];
+    editor: CanvasEditorContext;
+};
+declare const __VLS_export$4: vue.DefineComponent<__VLS_Props$3, {}, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<__VLS_Props$3> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
+declare const _default$4: typeof __VLS_export$4;
+
+type __VLS_Props$2 = {
+    editor: CanvasEditorContext;
+    items?: NodePaletteItem[];
+};
+declare const __VLS_export$3: vue.DefineComponent<__VLS_Props$2, {}, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<__VLS_Props$2> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
+declare const _default$3: typeof __VLS_export$3;
+
+declare const __VLS_export$2: vue.DefineComponent<{}, {}, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+declare const _default$2: typeof __VLS_export$2;
+
+type __VLS_Props$1 = {
+    node: FlowNodeModel;
+    position: ScreenPosition;
+    config: Required<NodeActionsConfig>;
+    behavior: NodeBehaviorConfig;
+    actionsOffset?: {
+        x?: number;
+        y?: number;
+    };
+};
+declare const __VLS_export$1: vue.DefineComponent<__VLS_Props$1, {}, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    action: (type: "delete" | "copy" | "copy-insert" | "disconnect" | "debug", nodeId: string) => any;
+}, string, vue.PublicProps, Readonly<__VLS_Props$1> & Readonly<{
+    onAction?: ((type: "delete" | "copy" | "copy-insert" | "disconnect" | "debug", nodeId: string) => any) | undefined;
+}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
+declare const _default$1: typeof __VLS_export$1;
+
+type __VLS_Props = {
+    node: FlowNodeModel;
+    portPosition: ScreenPosition;
+    tooltipText?: string;
+};
+declare function closePopover(): void;
+declare var __VLS_7: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_7) => any;
+};
+declare const __VLS_base: vue.DefineComponent<__VLS_Props, {
+    closePopover: typeof closePopover;
+}, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    close: () => any;
+    mouseenter: () => any;
+    mouseleave: () => any;
+    open: (nodeId: string) => any;
+    "start-drag": (nodeId: string) => any;
+}, string, vue.PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onClose?: (() => any) | undefined;
+    onMouseenter?: (() => any) | undefined;
+    onMouseleave?: (() => any) | undefined;
+    onOpen?: ((nodeId: string) => any) | undefined;
+    "onStart-drag"?: ((nodeId: string) => any) | undefined;
+}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+interface DefaultToolbarItemsOptions {
+    /** 要排除的操作项类型（仅对可隐藏的组生效，zoom 和 reset 组固定不可排除） */
+    exclude?: BuiltinToolbarType[];
+    /** 要恢复显示的默认隐藏项（默认隐藏：undo、redo） */
+    include?: BuiltinToolbarType[];
+}
+/**
+ * 工具栏默认项分为四组（从左到右）：
+ *  1. history: 撤销、重做 — 默认隐藏，通过 include: ['undo', 'redo'] 恢复显示
+ *  2. tools:   框选、自动排版、搜索、缩略图、下载 — 可隐藏
+ *  3. zoom:    缩小、放大 — 固定
+ *  4. reset:   重置 — 固定
+ */
+declare function createDefaultToolbarItems(options?: DefaultToolbarItemsOptions): CanvasToolbarItem[];
+
+type BuiltinEdgeType = 'manhattan' | 'bezier';
+interface DefaultNodeTypeConfig {
+    label?: string;
+    icon?: string;
+    width?: number;
+    height?: number;
+}
+interface DefaultSchemaOptions {
+    nodeTypes?: Record<string, DefaultNodeTypeConfig>;
+    /** 默认连线类型，内置 'manhattan' | 'bezier'，也可指向自定义类型 key */
+    defaultEdgeType?: string;
+    /** 额外/覆盖的边类型定义，会与内置类型合并 */
+    edgeTypes?: Record<string, CanvasEdgeDefinition>;
+}
+interface DefaultSchemaResult {
+    schema: CanvasSchema;
+    paletteItems: NodePaletteItem[];
+}
+declare function createBuiltinEdgeTypes(): Record<BuiltinEdgeType, CanvasEdgeDefinition>;
+/**
+ * 创建内置的默认 Schema，提供开箱即用的节点与边类型。
+ *
+ * 节点类型使用 DefaultNode 组件渲染，自带上/右/下/左四个连接端口。
+ * 不传参数时提供 7 种节点类型和 2 种内置边类型（manhattan / bezier）。
+ *
+ * @example
+ * // 默认 manhattan 直角连线
+ * const { schema, paletteItems } = createDefaultSchema();
+ *
+ * // 切换为贝塞尔曲线连线
+ * const { schema, paletteItems } = createDefaultSchema({ defaultEdgeType: 'bezier' });
+ *
+ * // 自定义边类型
+ * const { schema, paletteItems } = createDefaultSchema({
+ *   defaultEdgeType: 'myEdge',
+ *   edgeTypes: { myEdge: { connector: 'normal', style: ... } },
+ * });
+ */
+declare function createDefaultSchema(options?: DefaultSchemaOptions): DefaultSchemaResult;
+
+declare function connectionValidatorPlugin(validator: ConnectionValidator): CanvasPlugin;
+
+interface SelectionPluginOptions {
+    rubberband?: boolean;
+    multiple?: boolean;
+    movable?: boolean;
+}
+declare function selectionPlugin(options?: SelectionPluginOptions): CanvasPlugin;
+
+interface SnaplinePluginOptions {
+    tolerance?: number;
+    color?: string;
+}
+declare function snaplinePlugin(options?: SnaplinePluginOptions): CanvasPlugin;
+
+interface MinimapPluginOptions {
+    container?: HTMLElement;
+    width?: number;
+    height?: number;
+}
+declare function minimapPlugin(options?: MinimapPluginOptions): CanvasPlugin;
+
+/**
+ * FlowModel 级剪贴板插件。
+ *
+ * 不依赖 @antv/x6-plugin-clipboard，直接从 FlowModel 读取选中内容，
+ * 粘贴时生成新 ID 并通过 executeCommand 走完整命令管道。
+ * 这保证了粘贴操作与 undo/redo、插件 transformCommand 等机制一致。
+ */
+declare function clipboardPlugin(): CanvasPlugin;
+
+declare function generateId(): string;
+
+export { CanvasConstraintError, _default$5 as CanvasLayout, _default$3 as CanvasNodePalette, _default$6 as CanvasRuntime, CanvasSchemaError, _default$4 as CanvasToolbar, _default$2 as DefaultNode, _default$1 as NodeActionsToolbar, _default as NodeQuickAddPopover, applyCanvasCommand, clipboardPlugin, connectionValidatorPlugin, createBuiltinEdgeTypes, createCanvasHistory, createDefaultSchema, createDefaultToolbarItems, createEmptyFlowModel, generateId, minimapPlugin, selectionPlugin, snaplinePlugin, useCanvasEditor };
+export type { BuiltinEdgeType, BuiltinToolbarType, CanvasApi, CanvasCallbackContext, CanvasCommand, CanvasEdgeDefinition, CanvasEditorContext, CanvasEditorOptions, CanvasHistory, CanvasHistoryOptions, CanvasMode, CanvasNodeDefinition, CanvasPlugin, CanvasPosition, CanvasSchema, CanvasSelection, CanvasToolbarItem, CanvasUiEvent, CommandEnvelope, CommandExecutionError, CommandExecutionResult, CommandPreview, CommandRejection, CommandSource, ConnectionValidateContext, ConnectionValidateResult, ConnectionValidator, ContextMenuItem, DefaultNodeTypeConfig, DefaultSchemaOptions, DefaultSchemaResult, DefaultToolbarItemsOptions, EdgeDecoration, EdgeRenderState, EdgeStyle, EditorPluginContext, ExportOptions, FlowEdgeLabelModel, FlowEdgeModel, FlowModel, FlowModelChangeEvent, FlowNodeModel, FlowPortModel, InsertDirection, InsertNodeOptions, MinimapPluginOptions, NodeActionsConfig, NodeBehaviorConfig, NodeDecoration, NodePaletteItem, OverlayManager, QuickAddConfig, QuickAddInsertDirectionResolver, QuickAddPortResolver, RuntimePluginContext, ScreenPosition, SelectionPluginOptions, SnaplinePluginOptions };