@one2x/medeo-rte 0.2.0 → 0.3.0

package/README.md

@@ -75,12 +75,22 @@ new Editor(el, { plugins: [...builtinEmbedPlugins, formulaPlugin] });
 
 虚拟块是盖在字符流上的假块：负责皮（背景、圆角）和「整段选中」交互。区间里的字仍是文档正文。用户打字**不会**新建虚拟块，只能由业务 API 插入。
 
-两种 kind：
+三种 kind：
 
+- **`mark`**：纯样式叠层（高亮底色、边框、文字缺省色等）。**交互与普通文本流完全一致**：点击落光标、方向键逐字走、能选中、能编辑；不进选中/进出状态机，不参与嵌套（`parentId` 恒为 `null`），可与其他块任意叠放。右边缘继续输入算区间内（背景跟着延伸），遇到换行就断；区间内文字删光后自动移除。样式只需配 `chrome.background`、`chrome.radius`（圆角，默认 3；折行时只有首行的上两角和末行的下两角是圆角，其余角为直角，单行自然四角全圆）、`chrome.paddingX`（水平内边距）和 `chrome.hoverBackground`（鼠标悬停时整段含折行各行换成这个底色）：
+
+  ```ts
+  editor.insertVirtualBlock({
+    kind: 'mark',
+    chrome: { background: '#fff3bf', hoverBackground: '#ffe066', radius: 4, paddingX: 5 }
+  });
+  ```
+
+  `paddingX` 只外扩底色/边框，**不参与排版**（字形位置、折行、行高都不变），行首/行尾也会外扩，所以相邻文字和相邻 mark 的底色可能互相重叠；行首行尾的外扩部分画在内容区外：SDK 默认让画布和 `.mini-page-wrap` 左右各多出 5px（负 margin 抵消，文字位置不变），所以 `paddingX` 在 5px 以内开箱即用，更大就要靠编辑器 `padding.x` 补足。**宿主若覆盖 `.mini-page-wrap` 的 `padding`，请保留 `padding-inline: 5px; margin-inline: -5px;`，否则文字会左移 5px、外扩被裁**。不支持垂直内边距。
 - **`region`**：一层皮 / 分组。整段选中时打字、删除会被忽略（保住模板壳）。没有 `editing` 模式。
 - **`virtualSlot`**：最内层文本槽。可进 `editing`；空着时显示 `placeholder`，填了就是用户字；整段删回 placeholder，槽本身留下。
 
-嵌套规则：只允许包含、不允许交叉；`virtualSlot` 必须是叶子。日常编辑里业务**不用维护** `[start, end)`，插删字时 SDK 自动挪区间。
+嵌套规则（针对 `region` / `virtualSlot`）：只允许包含、不允许交叉；`virtualSlot` 必须是叶子。`mark` 不受此限。日常编辑里业务**不用维护** `[start, end)`，插删字时 SDK 自动挪区间。
 
 ### 路径 A：整段模板一次插入（推荐）
 
@@ -136,15 +146,18 @@ editor.insertVirtualBlock({
 editor.insertVirtualBlock({ kind: 'region', start: 0, end: 20, chrome: { ... } });
 ```
 
+可配的 `chrome` 字段：`background`、`hoverBackground`（仅 mark）、`radius`、`borderColor` / `borderWidth`、`paddingX`（仅水平）、文字缺省（`color`、`fontSize`、`fontFamily`、`fontWeight`、`bold`、`italic`）、`placeholderColor`（仅 virtualSlot）。
+
 改皮 / 拆皮：`updateVirtualBlock(id, chrome)`、`removeVirtualBlock(id)`（只拆皮，字和胶囊留下）。
 
 ### 业务浮层（Sample / AI 等）
 
 SDK 不画业务菜单。宿主自己：
 
-1. 听 `statechange`，看 `getState().vblockStack` 是否进了某槽的 `editing`
-2. 用 `getLayout()` 里该槽的 `vblocks` 矩形定位浮层
-3. 写入：让用户打字，或再 `insertSlice` 一段纯文本
+1. 听 `statechange`，看 `getState().vblockStack` 栈顶是否是某槽的 `editing`（点击或键盘进入都会触发）
+2. `editor.getVirtualBlockRect(id)` 拿屏幕坐标（clientX/Y，含滚动）定位浮层：`left/top/width/height` 是外接矩形，折行的块还有 `lines`；下拉放在 `left` / `top + height` 即可。滚动或重排后（`layoutchange`）重新取
+3. 写入：槽正处于 `editing` 时直接 `editor.insertText(text)`——空槽会整段覆盖 placeholder，不会进段落
+4. 关闭浮层：栈顶不再是该槽，或点到编辑器外（宿主自己监听）
 
 ### 和 host 胶囊一起用
 
@@ -189,6 +202,19 @@ editor.commands.insertHostEmbed('Upscale', { label: '@Upscale' }, { width: 88, h
 
 脚本化改文档也可 `import { operations, runOperation } from '@one2x/medeo-rte'`，不要直接改 `DocumentModel` 的内部表。
 
+## 性能探针（开发用）
+
+默认关闭、零开销。在浏览器控制台里：
+
+```js
+editor.perf.start()   // demo 里 window.editor 已暴露；业务里用自己的 editor 实例
+// 连续打字 / 按住方向键 / 中文输入法连续上屏 / 按快捷键……
+editor.perf.report()  // 输出各阶段耗时（平均 / p95 / 最大 ms）和帧率
+editor.perf.stop()
+```
+
+详细读法与历次优化记录见 [docs/performance.md](./docs/performance.md)。输出包含：`insertText`、`handleComposition`、`moveCaret` 等入口的同步耗时；`relayout`、`paintDoc`、`paintChrome`、`scrollCaret` 等阶段耗时；`xxx→下一帧`（处理开始到下一帧开始，近似输入延迟）；以及帧率、帧间隔 p95、掉帧数。120Hz 屏的帧预算是 8.3ms。
+
 ## 设计文档
 
 `docs/` 下是分层架构与技术方案:
@@ -201,6 +227,8 @@ editor.commands.insertHostEmbed('Upscale', { label: '@Upscale' }, { width: 88, h
 | [edits.md](./docs/edits.md) | 事务边界、撤销栈、片段坐标空间、协同预留 |
 | [rendering.md](./docs/rendering.md) | 块级增量排版、脏区带、绘制后端 |
 | [virtual-blocks.md](./docs/virtual-blocks.md) | 虚拟块:模板混排、文本槽、按层选区 |
+| [agent-segment-mapping.md](./docs/agent-segment-mapping.md) | 面向 Agent:用户的 segment 概念如何对应到真实结构与 API |
+| [performance.md](./docs/performance.md) | 性能目标、探针用法、长文档优化记录与待办 |
 
 改动模型前先读 architecture.md 的不变式那一节。