vite-plugin-visual-selector 0.1.0 → 0.1.1

package/README.md

@@ -1,795 +1,369 @@
 # vite-plugin-visual-selector
 
-一个面向 **React / JSX / TSX** 的 Vite 插件，用来实现类似 Base44 可视化编辑器中的“源码同源元素联动高亮”能力。
+面向 React/JSX/TSX 的 Vite 插件，实现"源码同源元素联动高亮"能力。
 
-它提供两部分能力：
-
-1. **编译时注入**：在 JSX 编译阶段给原生 DOM 元素注入 `data-source-location`
-2. **运行时桥接**：在预览页 / iframe 中启用 `setupSelectionBridge()`，实现 hover、高亮、同源元素批量选中、`postMessage` 通知父页面
-
----
-
-## 一、它解决什么问题
-
-在可视化编辑器里，用户点到页面上的某个元素时，编辑器通常需要知道：
-
-- 这个 DOM 节点来自哪一段源码
-- 页面上还有哪些元素与它来自同一个 JSX 表达式
-- 如何把这些“同源元素”一起高亮出来
-- 如何把选中结果同步给父级编辑器 UI
-
-这个插件就是为这个目标设计的。
-
-典型效果：
-
-```tsx
-{items.map((item) => (
-  <div className="cell">{item.label}</div>
-))}
-```
-
-如果这几个 `div` 都来自同一行 `.map()` JSX，那么点击其中一个时，所有同样带有相同 `data-source-location` 的元素都会一起被高亮。
+编译时给 DOM 打上源码坐标（`data-source-location`），运行时根据坐标将同源元素聚合高亮，支持行内编辑和远程 DOM 修改。
 
 ---
 
-## 二、能力概览
-
-### 编译时
-
-- 只处理 `.jsx` / `.tsx`
-- 只给**原生 DOM 标签**注入属性，例如：`div`、`span`、`button`
-- 不给 React 组件注入，例如：`<Card />`
-- 默认属性名：`data-source-location`
-- 默认值格式：`相对路径:行:列`
-
-示例：
-
-```html
-<div data-source-location="src/App.tsx:12:6">...</div>
-```
+## 一、稳定公开 API
 
-### 运行时
-
-- hover 时高亮同 source-location 的元素
-- click 时选中同 source-location 的元素
-- 给每个匹配元素绘制 overlay
-- 向父页面发送 `postMessage`
-- 支持销毁和清空当前高亮状态
-
----
-
-## 三、安装
+### 安装
 
 ```bash
 npm install vite-plugin-visual-selector
 ```
 
-如果你要跑本仓库 demo / 本地开发：
-
-```bash
-npm install
-```
-
----
-
-## 四、最基本的使用方式
-
-### 1）在 `vite.config.ts` 中注册插件
+### 编译时插件
 
 ```ts
+// vite.config.ts
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import { visualSelectorPlugin } from 'vite-plugin-visual-selector'
 
 export default defineConfig({
-  plugins: [
-    react(),
-    visualSelectorPlugin(),
-  ],
+  plugins: [react(), visualSelectorPlugin()],
 })
 ```
 
-这是最小接入方式。
-
-注册后，插件会在 Vite transform 阶段扫描 JSX / TSX 模块，并给原生 DOM 节点自动插入 `data-source-location`。
-
----
-
-## 五、进阶配置
-
-插件入口：
-
-```ts
-import { visualSelectorPlugin } from 'vite-plugin-visual-selector'
-```
-
-类型定义：
+#### `VisualSelectorPluginOptions`
 
 ```ts
 interface VisualSelectorPluginOptions {
+  /** 需要处理的文件匹配规则，默认 [/\.[jt]sx$/] */
   include?: RegExp[]
+  /** 需要排除的文件匹配规则，默认 [/node_modules/] */
   exclude?: RegExp[]
+  /** 注入属性名，默认 "data-source-location" */
   attributeName?: string
+  /** 项目根目录，用于计算相对路径，默认 process.cwd() */
   root?: string
 }
 ```
 
-### 配置示例
-
-```ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import { visualSelectorPlugin } from 'vite-plugin-visual-selector'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    visualSelectorPlugin({
-      include: [/\.[jt]sx$/],
-      exclude: [/node_modules/, /\.test\./],
-      attributeName: 'data-source-location',
-      root: process.cwd(),
-    }),
-  ],
-})
-```
-
-### 配置项说明
-
-#### `include?: RegExp[]`
-
-控制哪些文件会进入 transform。
-
-默认值：
-
-```ts
-[/\.[jt]sx$/]
-```
-
-也就是默认只处理 JSX / TSX 文件。
-
-#### `exclude?: RegExp[]`
-
-控制哪些文件会被跳过。
-
-默认值：
-
-```ts
-[/node_modules/]
-```
-
-#### `attributeName?: string`
-
-自定义注入属性名。
-
-默认值：
-
-```ts
-'data-source-location'
-```
-
-如果你的编辑器协议想用别的名字，可以改。
-
-#### `root?: string`
-
-用于生成相对路径。
-
-例如源码绝对路径是：
-
-```txt
-/Users/me/project/src/App.tsx
-```
-
-如果 `root = /Users/me/project`，最终注入值会变成：
-
-```txt
-src/App.tsx:12:6
-```
-
----
-
-## 六、运行时接入方式
-
-仅仅注册 Vite 插件还不够。  
-如果你想获得 Base44 那种“点击元素时，同源元素一起高亮”的能力，还需要在预览页中显式启用 runtime bridge。
-
-运行时入口：
+### 运行时 Agent
 
 ```ts
-import { setupSelectionBridge } from 'vite-plugin-visual-selector/runtime'
-```
+import { setupVisualEditAgent } from 'vite-plugin-visual-selector/runtime'
 
-### 最小接入示例
-
-```ts
-import { setupSelectionBridge } from 'vite-plugin-visual-selector/runtime'
-
-setupSelectionBridge({
-  parentWindow: window.parent,
-  enableHover: true,
-  enableClickSelection: true,
-})
+const agent = setupVisualEditAgent()
 ```
 
-这个调用通常应该放在：
-
-- 预览页入口
-- iframe 内部页面入口
-- 或专门的 preview bootstrap 文件里
-
----
-
-## 七、runtime API 详细说明
-
-类型定义：
+#### `VisualEditAgentOptions`
 
 ```ts
-interface SelectionBridgeOptions {
+interface VisualEditAgentOptions {
+  /** 属性名，默认 "data-source-location" */
   attributeName?: string
-  targetWindow?: Window
-  parentWindow?: Pick<Window, 'postMessage'>
+  /** postMessage 的目标 origin，默认 "*" */
   targetOrigin?: string
-  enableHover?: boolean
-  enableClickSelection?: boolean
 }
 ```
 
-### 参数说明
+#### `VisualEditAgentInstance`
 
-#### `attributeName?: string`
-
-要读取的元素标识属性名。
-
-默认值：
+`setupVisualEditAgent()` 返回控制实例：
 
 ```ts
-'data-source-location'
-```
-
-#### `targetWindow?: Window`
-
-bridge 所工作的目标 window。
-
-默认值：
-
-```ts
-window
-```
-
-通常不需要改，除非你在特殊上下文中手动桥接别的 window。
-
-#### `parentWindow?: Pick<Window, 'postMessage'>`
-
-接收消息的父窗口对象。
-
-默认值：
-
-```ts
-window.parent
+interface VisualEditAgentInstance {
+  /** 销毁 agent，移除所有监听器和 overlay */
+  destroy(): void
+  /** 开启/关闭编辑模式 */
+  enableEditMode(enabled: boolean): void
+  /** 手动选中元素 */
+  selectElement(element: Element): void
+  /** 清除所有选中和高亮 */
+  clearSelection(): void
+  /** 获取当前选中的 source id */
+  getSelectedId(): string | null
+}
 ```
 
-#### `targetOrigin?: string`
-
-`postMessage` 的目标 origin。
-
-默认值：
+### npm 导出
 
 ```ts
-'*'
-```
-
-生产环境里如果你有固定编辑器域名，建议收紧为明确 origin。
-
-#### `enableHover?: boolean`
+// 主入口 "vite-plugin-visual-selector"
+export { visualSelectorPlugin, setupVisualEditAgent }
 
-是否启用 hover 联动高亮。
-
-默认值：
-
-```ts
-true
+// 运行时入口 "vite-plugin-visual-selector/runtime"
+export { setupVisualEditAgent }
 ```
 
-#### `enableClickSelection?: boolean`
-
-是否启用点击选中。
-
-默认值：
-
-```ts
-true
-```
+完整类型导出见 [src/index.ts](src/index.ts)。
 
 ---
 
-## 八、`setupSelectionBridge()` 返回什么
-
-当前返回一个控制对象：
-
-```ts
-const bridge = setupSelectionBridge({...})
-
-bridge.destroy()
-bridge.clearSelection()
-```
-
-### `destroy()`
-
-作用：
-
-- 移除事件监听器
-- 删除当前所有 overlay
-- 释放当前激活的 bridge
-
-适合场景：
-
-- 预览页卸载
-- iframe 切换页面
-- 编辑器销毁
-
-### `clearSelection()`
-
-作用：
-
-- 清除 selected overlays
-- 清除 hover overlays
-
-适合场景：
-
-- 父编辑器主动取消选中
-- 切换右侧面板时重置视觉状态
-- 执行删除 / 替换元素后重置高亮
-
----
+## 二、高级集成能力
 
-## 九、父页面会收到什么消息
+### 父编辑器控制
 
-当前 runtime 会发出类似下面的消息：
+父窗口通过 `postMessage` 控制 iframe 内的 agent：
 
 ```ts
-{
-  type: 'element-selected',
-  tagName: 'DIV',
-  className: 'box',
-  selectorId: 'src/App.tsx:12:6',
-  dataSourceLocation: 'src/App.tsx:12:6',
-  rect: {
-    top: 120,
-    left: 300,
-    right: 348,
-    bottom: 168,
-    width: 48,
-    height: 48,
-  },
-}
-```
+// 开启编辑模式
+iframe.contentWindow.postMessage(
+  { type: 'toggle-visual-edit-mode', data: { enabled: true } },
+  '*'
+)
 
-其中：
+// 修改元素 class
+iframe.contentWindow.postMessage(
+  { type: 'update-classes', data: { visualSelectorId: 'src/App.tsx:12:6', classes: 'text-lg font-bold' } },
+  '*'
+)
 
-- `type`
-  - 当前可能值：`element-selected` / `element-hovered`
-- `tagName`
-  - 被命中元素的标签名
-- `className`
-  - 元素的 className
-- `selectorId`
-  - 当前选中的 source 标识
-- `dataSourceLocation`
-  - 当前和 `selectorId` 保持一致
-- `rect`
-  - 元素在 viewport 中的矩形信息
+// 修改元素文本
+iframe.contentWindow.postMessage(
+  { type: 'update-content', data: { visualSelectorId: 'src/App.tsx:12:6', content: '新文本' } },
+  '*'
+)
 
-### 父页面接收示例
+// 修改元素属性
+iframe.contentWindow.postMessage(
+  { type: 'update-attribute', data: { visualSelectorId: 'src/App.tsx:12:6', attribute: 'src', value: '/new-image.png' } },
+  '*'
+)
 
-```ts
-window.addEventListener('message', (event) => {
-  const data = event.data
+// 取消选中
+iframe.contentWindow.postMessage({ type: 'unselect-element' }, '*')
 
-  if (data?.type === 'element-selected') {
-    console.log('用户选中了元素:', data)
-  }
-})
-```
-
----
+// 切换行内编辑
+iframe.contentWindow.postMessage(
+  { type: 'toggle-inline-edit-mode', data: { dataSourceLocation: 'src/App.tsx:12:6', inlineEditingMode: true } },
+  '*'
+)
 
-## 十、完整接入示例
+// 修改 CSS 变量
+iframe.contentWindow.postMessage(
+  { type: 'update-theme-variables', data: { variables: { '--primary': '#e11d48' } } },
+  '*'
+)
 
-### `vite.config.ts`
+// 注入字体
+iframe.contentWindow.postMessage(
+  { type: 'inject-font-import', data: { fontUrl: 'https://fonts.googleapis.com/css2?family=Inter' } },
+  '*'
+)
 
-```ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import { visualSelectorPlugin } from 'vite-plugin-visual-selector'
+// 刷新页面
+iframe.contentWindow.postMessage({ type: 'refresh-page' }, '*')
 
-export default defineConfig({
-  plugins: [
-    react(),
-    visualSelectorPlugin({
-      root: process.cwd(),
-    }),
-  ],
-})
+// 请求当前选中元素位置
+iframe.contentWindow.postMessage({ type: 'request-element-position' }, '*')
 ```
 
-### `src/preview-bridge.ts`
+### 监听 iframe 上报消息
 
 ```ts
-import { setupSelectionBridge } from 'vite-plugin-visual-selector/runtime'
+window.addEventListener('message', (e) => {
+  switch (e.data?.type) {
+    case 'visual-edit-agent-ready':
+      // agent 初始化完成，可以开始发送指令
+      break
 
-setupSelectionBridge({
-  parentWindow: window.parent,
-  enableHover: true,
-  enableClickSelection: true,
-})
-```
+    case 'element-selected':
+      // 元素被选中
+      // e.data: { tagName, classes, visualSelectorId, content?, position, isTextElement, computedStyles, ... }
+      break
 
-### `src/main.tsx`
+    case 'element-position-update':
+      // 选中元素位置更新（滚动/resize 时）
+      // e.data: { position, isInViewport, visualSelectorId }
+      break
 
-```ts
-import './preview-bridge'
-```
+    case 'inline-edit':
+      // 行内编辑内容变更
+      // e.data: { elementInfo, originalContent, newContent }
+      break
 
-### 父页面
+    case 'content-editing-started':
+    case 'content-editing-ended':
+      // 行内编辑状态变更
+      // e.data: { visualSelectorId }
+      break
 
-```ts
-window.addEventListener('message', (event) => {
-  if (event.data?.type === 'element-selected') {
-    // 打开右侧属性面板 / 更新工具栏 / 高亮源码等
+    case 'sandbox:onMounted':
+    case 'sandbox:onUnmounted':
+      // 页面中带标记元素的挂载/卸载状态
+      break
   }
 })
 ```
 
----
-
-## 十一、编译前后效果示例
-
-源码：
-
-```tsx
-{items.map((item) => (
-  <div className="cell">{item.label}</div>
-))}
-```
-
-经过插件 transform 后，效果近似于：
-
-```tsx
-{items.map((item) => (
-  <div
-    data-source-location="src/App.tsx:12:6"
-    className="cell"
-  >
-    {item.label}
-  </div>
-))}
-```
-
-如果页面最终渲染出多个 `div`，它们都会带相同的 `data-source-location`，于是 runtime 就能把它们视为“同源元素组”。
-
----
-
-## 十二、实现过程详解
-
-这一部分重点解释：这个插件到底是怎么工作的。
-
-### 整体分层
-
-插件分成两层：
-
-```txt
-编译时：JSX -> 注入 data-source-location
-运行时：读 data-source-location -> 查找同源元素 -> 绘制 overlay -> postMessage
-```
-
-也就是：
-
-1. **先在编译时埋点**
-2. **再在运行时消费这些标记**
-
----
-
-### 1）编译时实现过程
-
-核心文件：
-
-- `src/plugin.ts`
-
-使用到的核心工具：
-
-- `@babel/parser`
-- `@babel/traverse`
-- `@babel/types`
-- `magic-string`
-
-#### 步骤 A：过滤目标文件
-
-插件只处理匹配 `include` 的文件，并跳过 `exclude`。
-
-默认情况就是：
-
-- 处理 `.jsx` / `.tsx`
-- 跳过 `node_modules`
-
-#### 步骤 B：解析 AST
-
-```ts
-const ast = parse(code, {
-  sourceType: 'module',
-  plugins: ['jsx', 'typescript'],
-})
-```
-
-这样插件就能拿到 JSX 节点的结构信息和源码位置信息。
-
-#### 步骤 C：只处理原生标签
-
-插件会检查当前节点是不是原生 DOM 元素。
-
-例如：
-
-- `div` → 处理
-- `span` → 处理
-- `button` → 处理
-- `Card` → 不处理
-- `Layout` → 不处理
-
-原因很简单：
-
-React 组件本身并不一定会直接成为真实 DOM，只有最终的原生标签才适合被 visual selector 消费。
-
-#### 步骤 D：生成 source-location
-
-插件会根据：
-
-- 文件相对路径
-- AST 节点起始行号
-- AST 节点起始列号
-
-生成：
-
-```txt
-src/App.tsx:12:6
-```
-
-这里列号做了 `+1`，是为了输出更符合人类习惯的 1-based 列号。
-
-#### 步骤 E：把属性插回源码
-
-通过 `MagicString` 在 JSX opening tag 中插入属性：
+### 旧版兼容
 
-```ts
-magicString.appendLeft(node.name.end, ` ${attributeName}="${location}"`)
-```
+以下消息类型保留向后兼容，建议迁移到新版 API：
 
-这样就不会手写字符串拼接整段 JSX，而是进行更可靠的源码片段注入。
+| 旧版 | 新版替代 |
+|------|---------|
+| `visual-selector:set-active` | `toggle-visual-edit-mode` |
+| `update-element-style` | `update-classes` + CSS class |
+| `update-element-text` | `update-content` |
+| `update-element-class` | `update-classes` |
 
-#### 步骤 F：输出 sourcemap
+### 完整消息协议类型
 
-如果文件确实发生了变更，就返回：
+所有消息类型均从主入口导出，可用于父编辑器的 TypeScript 类型检查：
 
 ```ts
-{
-  code: magicString.toString(),
-  map: magicString.generateMap({ hires: true }),
-}
+import type {
+  // iframe → 主页面
+  ElementSelectedMessage,
+  ElementPositionUpdateMessage,
+  InlineEditMessage,
+  ContentEditingMessage,
+  AgentReadyMessage,
+  SandboxMountMessage,
+  // 主页面 → iframe
+  ToggleVisualEditModeMessage,
+  UpdateClassesMessage,
+  UpdateAttributeMessage,
+  UpdateContentMessage,
+  UpdateThemeVariablesMessage,
+  ToggleInlineEditModeMessage,
+  InjectFontImportMessage,
+  UnselectElementMessage,
+  RefreshPageMessage,
+  RequestElementPositionMessage,
+} from 'vite-plugin-visual-selector'
 ```
 
-这样宿主工具链还能继续保持较好的调试体验。
-
 ---
 
-### 2）运行时实现过程
-
-核心文件：
-
-- `src/runtime.ts`
+## 三、实现原理
 
-#### 步骤 A：安装 bridge
+### 整体架构
 
-```ts
-setupSelectionBridge({...})
+```
+编译时（Vite transform）         运行时（iframe 内）
+┌─────────────────────┐     ┌──────────────────────────────┐
+│ .jsx/.tsx 文件        │     │ setupVisualEditAgent()       │
+│ ↓ @babel/parser      │     │ ↓ 绑定 click/mousemove 监听   │
+│ ↓ @babel/traverse    │     │ ↓ 查找 [data-source-location] │
+│ ↓ 只处理小写标签       │     │ ↓ querySelectorAll 同源元素    │
+│ ↓ magic-string 注入   │     │ ↓ 创建 overlay 高亮           │
+│ ↓ 输出 sourcemap     │     │ ↓ postMessage 上报            │
+└─────────────────────┘     └──────────────────────────────┘
 ```
 
-调用后会：
-
-- 绑定 click 监听
-- 绑定 mousemove 监听
-- 维护 selected / hover overlay 状态
-
-而且当前实现会保证：
+### 编译时
 
-- 同一个页面只存在一个激活 bridge
-- 再次调用时会先清理上一个 bridge
+- Vite `transform` 钩子（`enforce: 'pre'`），在 React 插件之前运行
+- `@babel/parser` 解析 JSX AST，`@babel/traverse` 遍历 `JSXOpeningElement`
+- 只处理原生 DOM 元素（小写标签），跳过 React 组件（大写标签）
+- `magic-string` 在标签名末尾注入 `data-source-location="相对路径:行:列"`
+- 已有该属性的元素不重复注入
+- 生成高精度 sourcemap
 
-#### 步骤 B：识别可选元素
+编译前后对比：
 
-runtime 会从事件目标开始向上查找最近的：
+```tsx
+// 编译前
+<div className="cell">{item.label}</div>
 
-```txt
-[data-source-location]
+// 编译后
+<div data-source-location="src/App.tsx:12:6" className="cell">{item.label}</div>
 ```
 
-如果事件命中的是 overlay 本身，则会直接跳过，避免“高亮层选中高亮层”的问题。
-
-#### 步骤 C：读取 selectorId
+### 运行时模块结构
 
-当前 selectorId 本质上就是元素的：
-
-```ts
-element.getAttribute(attributeName)
 ```
-
-通常就是 `data-source-location` 的值。
-
-#### 步骤 D：查找所有同源元素
-
-一旦拿到 selectorId，runtime 会执行：
-
-```ts
-document.querySelectorAll(`[data-source-location="..."]`)
+src/runtime/
+├── index.ts              # setupVisualEditAgent 组装入口
+├── state.ts              # AgentState 状态管理
+├── utils.ts              # 纯工具函数（getSourceId, findAllElementsById 等）
+├── overlay.ts            # overlay 创建/定位 + 动画冻结
+├── messages.ts           # 消息收发协议
+├── inline-edit.ts        # 行内编辑
+└── layer-navigation.ts   # 层级导航下拉菜单
 ```
 
-从整个文档中找出所有具有相同 source-location 的元素。
-
-这就是“点击一个元素，所有同类一起高亮”的核心。
-
-#### 步骤 E：绘制 overlay
-
-对每一个匹配元素，runtime 都会创建一个新的 overlay：
-
-- `position: absolute`
-- `pointer-events: none`
-- 高 z-index
-- hover / selected 两套样式
+### 运行时核心流程
 
-然后根据目标元素的 `getBoundingClientRect()`，把 overlay 定位到正确位置。
+1. **初始化**：绑定 `message` 监听器，通知父页面 `visual-edit-agent-ready`
+2. **激活编辑模式**：冻结动画、禁用 pointer-events、设置 crosshair 光标、绑定鼠标事件
+3. **Hover 高亮**：`elementFromPoint` 穿透 overlay 查找真实元素，`querySelectorAll` 找同源元素，创建半透明 overlay
+4. **Click 选中**：创建实线 overlay + 标签名 tag + 层级导航入口，`postMessage` 上报 `element-selected`
+5. **位置跟踪**：scroll/resize 时通过 `requestAnimationFrame` 节流更新 overlay 位置，上报 `element-position-update`
+6. **DOM 变化检测**：`MutationObserver` 监听 style/class/宽高变化，自动重定位 overlay
+7. **行内编辑**：将文本元素设为 `contentEditable`，防抖上报 `inline-edit`
+8. **远程修改**：接收父窗口的 `update-classes`/`update-content`/`update-attribute` 指令，直接操作 DOM
 
-#### 步骤 F：发消息给父页面
+### 关键实现细节
 
-click 时，runtime 会调用：
-
-```ts
-parentWindow.postMessage(message, targetOrigin)
-```
-
-父编辑器收到消息后，就可以：
-
-- 打开元素编辑面板
-- 更新工具栏
-- 选中对应源码节点
-- 做 hover / selection 同步
+- **穿透 overlay 查找元素**：临时禁用 `freeze-pointer-events` 样式表，调用 `elementFromPoint`，再恢复
+- **冻结动画**：注入全局 CSS 规则 `animation-play-state: paused` + `transition: none`，并调用 `getAnimations().forEach(anim => anim.finish())`
+- **pointer-events 管理**：全局 `pointer-events: none`，agent 元素通过 `data-vite-plugin-element` 属性选择器恢复 `pointer-events: auto`
+- **tag 定位**：默认在元素上方 27px，上方空间不足时移到下方或内部，水平方向通过 `requestAnimationFrame` 后修正保证不超出视口
 
 ---
 
-## 十三、为什么这样设计
-
-### 为什么在编译时注入属性？
+## 四、限制与副作用
 
-因为这是最稳定、最轻量的方式。
+### 支持范围
 
-优点：
+- **只支持 React / JSX / TSX**：插件通过 Babel 解析 JSX 语法，不支持 Vue SFC、Svelte 等其他模板语法
+- **只处理原生 DOM 元素**：小写标签（`div`、`span`、`button` 等）会被注入属性，大写标签（React 组件如 `<Card />`）不处理
+- **Vite 5+ 环境**：peer 依赖要求 `vite >= 5`
 
-- 运行时不需要做源码分析
-- DOM 一渲染出来就带有可追踪标识
-- 同一个 JSX 表达式渲染出的多个元素天然共享同一个标识
+### 运行时侵入性
 
-### 为什么只给原生 DOM 打标？
+启用编辑模式后，agent 会对页面产生以下副作用：
 
-因为编辑器最终操作的是浏览器里的真实 DOM，而不是 React 组件抽象层。
+1. **冻结所有 CSS 动画和过渡**：通过注入全局样式 `animation-play-state: paused; transition: none`
+2. **接管 pointer-events**：全局设置 `pointer-events: none`，只有 agent 创建的元素可交互
+3. **修改 cursor**：`document.body.style.cursor = 'crosshair'`
+4. **锁定 overflow**：`overflow-y: scroll; overflow-x: hidden` 防止 tag 标签导致的滚动条闪烁
+5. **注入 DOM 元素**：overlay、tag 标签、layer dropdown 挂在 `document.body` 上
+6. **拦截 click 事件**：在捕获阶段阻止事件冒泡（`stopImmediatePropagation`）
+7. **启动 MutationObserver**：监听 `document.body` 的子树变化
 
-### 为什么 overlay 挂在 `document.body`？
+关闭编辑模式后（`enableEditMode(false)` 或 `destroy()`），以上副作用全部清除。
 
-因为这样不需要改动原始业务 DOM，侵入性最低，也更容易做绝对定位。
+### 行内编辑限制
 
-### 为什么 runtime 不自动注入？
+- 只有叶子节点（无子元素）的文本类标签可行内编辑
+- 包含 `img`/`video`/`canvas`/`svg` 子元素的不可编辑
+- 空文本元素不可编辑
+- 编辑通过 `contentEditable` 实现，可能与某些 CSS 样式冲突
 
-因为显式接入更稳：
+### 消息安全
 
-- 不需要猜宿主应用入口
-- 不污染用户项目结构
-- 容易和 iframe / preview 场景集成
+- `postMessage` 默认使用 `targetOrigin: '*'`，生产环境建议设置具体 origin
+- agent 会校验 `targetOrigin`，只接受匹配 origin 的消息
 
 ---
 
-## 十四、当前实现的限制
-
-当前版本有这些限制：
-
-1. **只支持 React / JSX / TSX**
-2. **只处理原生 DOM 元素**
-3. **runtime 需要手动调用 `setupSelectionBridge()`**
-4. **当前 overlay 会在 hover 时“先清再画”**
-   - 逻辑简单
-   - 但还没有做更细的性能优化
-5. **当前尚未内建 scroll / resize 自动重定位增强**
-6. **当前消息结构是最小可用版，不是完整编辑器协议**
-
----
-
-## 十五、推荐接入方式
-
-如果你要把它接入自己的可视化编辑器，我建议这样分工：
-
-### 预览页 / iframe 内部
-
-- 注册 `visualSelectorPlugin()`
-- 启用 `setupSelectionBridge()`
-- 渲染业务页面
-
-### 父编辑器页面
-
-- 监听 `postMessage`
-- 根据 `element-selected` 更新 UI
-- 必要时主动调用 preview 内部能力做状态复位
-
----
-
-## 十六、本地开发命令
+## 开发
 
 ```bash
-npm install
-npm run typecheck
-npm test
-npm run build
+npm run build        # tsup 构建（ESM + dts + sourcemap）
+npm test             # vitest run
+npm run test:watch   # vitest watch
+npm run typecheck    # tsc --noEmit
+npm run demo         # 启动 demo
 ```
 
-运行 demo：
+### 项目结构
 
-```bash
-npm run demo
 ```
-
----
-
-## 十七、项目结构
-
-```txt
 src/
-  index.ts          # 插件入口导出
-  plugin.ts         # 编译时 JSX 注入逻辑
-  runtime.ts        # 运行时 bridge / overlay / postMessage
-  shared/
-    constants.ts    # 常量
-    types.ts        # 公共类型
-
-demo/
-  vite.config.ts
-  src/
-    App.tsx
-    bridge.ts
-    main.tsx
-
-test/
-  plugin.test.ts
-  runtime.test.ts
-  runtime-api.test.ts
-  package.test.ts
-  demo-docs.test.ts
-```
-
----
-
-## 十八、导出 API 一览
-
-### 主入口
-
-```ts
-import { visualSelectorPlugin } from 'vite-plugin-visual-selector'
+├── index.ts              # 主入口导出
+├── plugin.ts             # 编译时 JSX 注入逻辑
+├── runtime.ts            # 运行时入口（re-export）
+├── runtime/
+│   ├── index.ts          # setupVisualEditAgent 组装
+│   ├── state.ts          # 状态管理
+│   ├── utils.ts          # 工具函数
+│   ├── overlay.ts        # overlay + 冻结动画
+│   ├── messages.ts       # 消息协议
+│   ├── inline-edit.ts    # 行内编辑
+│   └── layer-navigation.ts # 层级导航
+└── shared/
+    ├── constants.ts      # 常量
+    └── types.ts          # 公共类型
+demo/                     # 示例项目
+test/                     # Vitest 测试
+docs/                     # 实现文档
 ```
-
-### runtime 入口
-
-```ts
-import { setupSelectionBridge } from 'vite-plugin-visual-selector/runtime'
-```
-
----
-
-## 十九、总结
-
-如果你只记住一句话，可以记这个：
-
-> 这个插件的核心思想是：**编译时给 DOM 打上源码坐标，运行时再根据这个坐标把同源元素重新聚合起来。**
-
-这样就能用非常简单、非常稳定的方式，做出类似 Base44 那种“点击一个元素，所有同类一起高亮”的可视化编辑体验。