@ek-aiot/2d-editor-core 功能地图

@ek-aiot/2d-editor-core 是 2D 编辑器的框架无关能力层。它以浏览器为主要运行环境， 使用 ESM 发布，并将文档事务、无头状态、Konva 舞台、运行时数据和共享协议组合成一套 不依赖 Vue、React 或 Pinia 的编辑器内核。

当前版本：v0.1.2（以 package.json 为准）

架构总览

宿主 UI / 框架适配层
       |
       v
headless  ----------> commands ----------> types
   |                     |                   ^
   | committed state     | EditorDocument    |
   v                     v                   |
stage <------------ document snapshot -------+
   | preview / callbacks                     |
   v                                         |
runtime ------------ binding values ---------+
   |
materials + utils 为以上模块提供内置目录和纯工具

这里存在四类状态，集成时不要混用：

• 文档状态：EditorDocument，只能通过 commands 提交，支持撤销、重做和变更事件。
• 会话状态：选择、工具、吸附、剪贴板和物料目录，由 headless 管理，不写入文档历史。
• 舞台预览：拖拽、变换、文字编辑、管线绘制中的临时画面，由 stage 管理；完成后通过回调交给宿主提交命令。
• 运行时状态：绑定值、连接状态和数据集轮询结果，由 runtime 管理，不写回编辑文档。

目录功能地图

| 目录 | 核心功能 | 主要边界 | | --------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------ | | src/ | 包入口、能力装配与公开导出 | 只从 src/index.ts 定义公开 API | | src/commands/ | 同步文档命令、校验、快照、撤销/重做、历史合并 | 只处理可序列化 JSON，不持有 UI/Konva 实例 | | src/headless/ | 无 UI 编辑器门面、会话状态、能力选择器、快捷键 | 不渲染画布，不接管宿主事件仲裁 | | src/stage/ | Konva 场景、节点渲染、交互预览、导出 PNG | 不拥有权威文档，完成交互后通过回调上报 | | src/stage/createStage/ | createStage 的场景、输入、选择、管线、视图等子系统 | 作为内部实现，不作为独立公共入口 | | src/runtime/ | 绑定协议、必需 key 收集、连接器和 HTTP 数据集 | 只产生运行时值，不改写 EditorDocument | | src/runtime/connectors/ | HTTP 轮询与 WebSocket 绑定值连接 | 负责生命周期、节流、错误和重连 | | src/runtime/datasets/ | HTTP 请求模板、响应映射、冲突检测、多数据集轮询 | 冲突按数据集顺序由后者覆盖 | | src/materials/ | 基础图形与设备内置物料目录 | 仅提供物料定义和 SVG URL，不含拖放协议 | | src/types/ | 文档 Schema、交互类型、运行时值类型 | 是跨模块的数据协议层，不包含行为 | | src/utils/ | 文档 JSON 解码、节点类型、渲染和 DOM 判断 | 保持纯函数或无状态工具 | | src/__tests__/ | 包级契约与跨模块测试 | 验证公共 API、协议、物料、数据集和舞台终态 |

资源目录与各模块的局部测试目录也有就地说明，可从对应目录 README 继续下钻。

公开能力

包根 src/index.ts 公开以下能力：

• commands：CommandManager、文档值工具、命令契约和各领域 command factory。
• headless：createHeadlessEditor、快照/会话类型、能力选择器和快捷键工具。
• stage：createStage、StageHandle、主题、文案和 PNG 导出选项。
• types：schema、interaction、runtime 中的共享类型。
• runtime：v1 协议、HTTP/WebSocket 连接器、HTTP 数据集工具和必需绑定 key 收集。
• materials：createBuiltinMaterials 与 DEFAULT_MATERIAL_ICON_URLS。
• utils：编辑器文档 JSON 解码、节点类型、渲染和 DOM 工具。

典型集成流程

import {
  createHeadlessEditor,
  createStage,
  createTransformNodesCommand,
} from "@ek-aiot/2d-editor-core";

const editor = createHeadlessEditor({ initialDocument });

const stage = createStage(container, {
  onSelectionChange: (ids) => editor.setSelectedNodeIds(ids),
  onNodesVisualPatch: (patches) => editor.execute(createTransformNodesCommand(patches)),
});

function syncStage() {
  const snapshot = editor.getSnapshot();
  stage.setNodes(snapshot.document.nodes);
  stage.setSelection(snapshot.session.selectedNodeIds);
  stage.setTool(snapshot.session.activeTool);
}

syncStage();
const unsubscribe = editor.subscribe(syncStage);

function dispose() {
  unsubscribe();
  stage.destroy();
}

宿主卸载时调用 dispose()。舞台的 preview 回调只用于即时画面反馈；只有完成回调转换成 command 并成功执行后，新的文档快照才应重新喂给舞台。

非目标边界

• 不包含 Vue/React 组件、Pinia store 或任何特定框架状态管理。
• 不包含 types/ui、面板布局、拖放协议或壳层交互。
• 不让 Konva 实例进入可序列化文档或 headless session。
• 不把实时绑定值和数据集结果持久化回编辑文档。

开发与验证

pnpm --filter @ek-aiot/2d-editor-core test
pnpm --filter @ek-aiot/2d-editor-core typecheck
pnpm --filter @ek-aiot/2d-editor-core build

测试运行在 Vitest + jsdom 中；构建产物为 dist/index.js 和对应类型声明，konva 保持为 peer dependency。