bridgerte 0.9.0 → 0.9.2

package/README.md

@@ -2,8 +2,14 @@
 
 ![BridgeRTE logo](https://gitee.com/wangchuyi1122/bridgerte/raw/master/packages/bridgerte/assets/bridgerte-logo-small.png)
 
-BridgeRTE 是面向 Web、H5、PC、React Native WebView 和 Flutter WebView 的跨端富文本编辑器。
-业务项目只需要安装并引用 `bridgerte`；局部能力可以从 `bridgerte/*` subpath 导入。
+BridgeRTE 是面向 Web、PC、H5、React Native WebView 和 Flutter WebView 的跨端富文本编辑器。
+业务项目只需要安装 `bridgerte`，不需要额外安装 Lexical 相关包。
+
+它提供三类接入方式：
+
+- DOM 编辑器：直接在 Web、PC、H5 页面里创建富文本编辑器。
+- 编辑器和菜单分离：editor 负责内容，toolbar/tabbar 由业务按布局单独挂载。
+- WebView / Native：WebView 内运行编辑器，RN/Flutter 原生侧自己渲染菜单并通过 bridge 发命令。
 
 ## 安装
 
@@ -11,123 +17,140 @@ BridgeRTE 是面向 Web、H5、PC、React Native WebView 和 Flutter WebView 的
 pnpm add bridgerte
 ```
 
-如果使用 npm：
+使用 npm：
 
 ```bash
 npm install bridgerte
 ```
 
-DOM 编辑器需要显式导入样式：
+DOM 编辑器必须显式导入样式：
 
 ```ts
 import 'bridgerte/style.css';
 ```
 
-## 快速开始
+## 推荐导入方式
+
+推荐按能力从 subpath 导入，方便业务打包器按使用边界 tree-shaking：
 
 ```ts
-import { createRichTextEditor } from 'bridgerte';
+import { createRichTextEditor, createRichTextToolbar } from 'bridgerte/dom';
+import { createWebViewBridgeRuntime } from 'bridgerte/webview';
+import { BRIDGERTE_CONTENT_VERSION } from 'bridgerte/core';
+import { isBridgeMessage } from 'bridgerte/bridge';
+import { defaultMenuSchema, resolveToolbarMenu } from 'bridgerte/native-spec';
 import 'bridgerte/style.css';
+```
 
-const container = document.querySelector<HTMLElement>('#editor');
-
-if (!container) throw new Error('editor container not found');
+入口说明：
 
-const editor = createRichTextEditor(container, {
-  placeholder: '请输入内容',
-  onContentChange(change) {
-    console.log(change.plainTextLength, change.isOverMaxLength);
-  }
-});
+- `bridgerte/dom`：DOM 编辑器、独立 toolbar/tabbar、WebView runtime 的 DOM 实现。
+- `bridgerte/webview`：WebView 页面内的 bridge runtime。
+- `bridgerte/core`：内容模型、命令、上传、菜单、参数面板和 `EditorAPI` 类型。
+- `bridgerte/bridge`：WebView 双向消息类型、默认事件节流配置和消息判断工具。
+- `bridgerte/native-spec`：RN/Flutter 原生菜单 schema、toolbar 解析和命令状态匹配工具。
+- `bridgerte/style.css`：DOM 默认样式。
+- `bridgerte`：聚合入口，适合迁移期或小型项目；生产示例优先使用 subpath。
 
-window.addEventListener('beforeunload', () => {
-  editor.destroy();
-});
-```
+## 快速开始
 
-页面里准备一个容器即可：
+页面准备两个容器：一个给 toolbar/tabbar，一个给编辑器内容区。`createRichTextEditor()`
+只创建 editor；菜单必须用 `createRichTextToolbar()` 单独挂载，并绑定同一个 `EditorAPI`。
 
 ```html
+<div id="toolbar"></div>
 <div id="editor"></div>
 ```
 
-## 导入入口
+```ts
+import { createRichTextEditor, createRichTextToolbar } from 'bridgerte/dom';
+import 'bridgerte/style.css';
 
-常规 Web/PC/H5 项目从主入口导入：
+const editorContainer = document.querySelector<HTMLElement>('#editor');
+const toolbarContainer = document.querySelector<HTMLElement>('#toolbar');
 
-```ts
-import {
-  createRichTextEditor,
-  createRichTextToolbar,
-  createWebViewBridgeRuntime
-} from 'bridgerte';
+if (!editorContainer) throw new Error('editor container not found');
+if (!toolbarContainer) throw new Error('toolbar container not found');
 
-import type {
-  EditorAPI,
-  EditorCommand,
-  EditorContent,
-  MenuItem,
-  ToolbarConfig
-} from 'bridgerte';
-```
+const editor = createRichTextEditor(editorContainer, {
+  placeholder: '开始输入',
+  onContentChange(change) {
+    counter.textContent = `${change.plainTextLength}/${change.maxLength ?? '∞'}`;
+    saveButton.disabled = !change.dirty;
+  }
+});
 
-只使用某一类能力时，可以使用 subpath：
+const toolbar = createRichTextToolbar(toolbarContainer, {
+  editor,
+  placement: 'top'
+});
 
-```ts
-import { createRichTextEditor } from 'bridgerte/dom';
-import { createWebViewBridgeRuntime } from 'bridgerte/webview';
-import { BRIDGERTE_CONTENT_VERSION } from 'bridgerte/core';
-import { isBridgeMessage } from 'bridgerte/bridge';
-import { defaultMenuSchema, resolveToolbarMenu } from 'bridgerte/native-spec';
+toolbar.update();
+
+window.addEventListener('beforeunload', () => {
+  toolbar.destroy();
+  editor.destroy();
+});
 ```
 
-- `bridgerte`：常用聚合入口。
-- `bridgerte/dom`：DOM 编辑器和独立 toolbar。
-- `bridgerte/webview`：WebView 页面内的 bridge runtime。
-- `bridgerte/core`：内容、命令、上传、菜单、参数面板和 editor API 类型。
-- `bridgerte/bridge`：WebView 双向消息类型和消息判断工具。
-- `bridgerte/native-spec`：RN/Flutter 原生菜单 schema 和 toolbar 解析工具。
-- `bridgerte/style.css`：DOM 默认样式。
+`placement: 'top' | 'bottom'` 只影响菜单语义、默认样式状态和无障碍命名；DOM 放在哪里、
+是否吸顶、吸底或跟随键盘，由业务自己的布局决定。销毁时建议先销毁 toolbar，再销毁 editor。
+
+WebView / RN / Flutter 也是同一心智：WebView 内的 editor 只提供内容和命令能力；原生菜单先读取
+ready payload 中的 `menuSchema`，再订阅后续 `editor.commandStateChange` 自行渲染，并通过
+bridge 发送命令。
 
 ## 基础配置
 
 ```ts
+import { createRichTextEditor } from 'bridgerte/dom';
+import type { EditorContent } from 'bridgerte/core';
+
+const initialValue: Partial<EditorContent> = {
+  html: '<p>Hello BridgeRTE</p>',
+  plainText: 'Hello BridgeRTE'
+};
+
 const editor = createRichTextEditor(container, {
-  value: {
-    html: '<p>Hello BridgeRTE</p>',
-    plainText: 'Hello BridgeRTE'
-  },
+  value: initialValue,
   readonly: false,
-  platform: 'pc',
-  toolbarMode: 'top',
   placeholder: '写点什么',
   maxLength: 10000,
   keyboardShortcuts: true,
   onReady(api) {
     api.focus();
+  },
+  onError(error) {
+    reportError(error);
+  },
+  onFocus() {
+    console.log('focus');
+  },
+  onBlur() {
+    console.log('blur');
   }
 });
 ```
 
-常用配置：
+常用选项：
 
 - `value`：初始内容，传 `Partial<EditorContent>`。
 - `readonly`：只读状态。
-- `platform`：`'pc' | 'h5' | 'webview'`。
-- `toolbarMode`：`'top' | 'bottom' | 'none' | 'native'`。
 - `placeholder`：空态提示。
 - `maxLength`：最大纯文本长度。
-- `keyboardShortcuts`：基础快捷键，默认关闭。
-- `onReady(api)`：编辑器 ready 后回传 `EditorAPI`。
+- `keyboardShortcuts`：是否启用 DOM 基础快捷键，默认关闭。
+- `onReady(api)`：编辑器初始化完成后回传 `EditorAPI`。
+- `onContentChange(change)`：高频轻量内容摘要。
+- `onChange(content)`：兼容旧项目的完整内容回调，大文档不建议逐字依赖。
 - `onError(error)`：运行时错误。
 - `onFocus()` / `onBlur()`：焦点变化。
 
-`toolbarMode` 说明：
+Deprecated 兼容字段：
 
-- `top`：默认顶部 toolbar。
-- `bottom`：H5 底部 tabbar。
-- `none`：只创建编辑器，业务自己挂载 toolbar。
-- `native`：WebView/RN/Flutter 场景不渲染 DOM 菜单。
+- `toolbarMode`：历史字段，当前在 `createRichTextEditor()` 中是 no-op，不再创建或控制 DOM
+  toolbar/tabbar。
+- `toolbarConfig`：历史 editor 字段，当前不再影响 editor 创建。菜单显示结构请传给
+  `createRichTextToolbar()`。
 
 ## 内容读写
 
@@ -152,20 +175,25 @@ editor.setContent({
 });
 ```
 
-高频内容变化建议使用轻量摘要：
+高频变化使用轻量摘要：
 
 ```ts
 createRichTextEditor(container, {
+  maxLength: 5000,
   onContentChange(change) {
     saveButton.disabled = !change.dirty;
     counter.textContent = `${change.plainTextLength}/${change.maxLength ?? '∞'}`;
+    warning.hidden = !change.isOverMaxLength;
   }
 });
 ```
 
-`onContentChange` 不携带完整 `html`、`json`、`plainText`，适合驱动 dirty、字数和保存按钮。
-保存、提交或离开页面确认时，再主动调用 `getContent()`。`onChange(content)` 会回传完整内容，
-主要用于兼容旧项目；大文档场景不建议逐字依赖它保存。
+重要边界：
+
+- `onContentChange` 不携带完整 `html`、`json`、`plainText`，适合驱动 dirty、字数和保存按钮。
+- 保存、提交、离开页面确认时，再主动调用 `getContent()`。
+- `onChange(content)` 会回传完整内容，主要用于兼容旧项目；10w 内容场景不要逐字依赖它保存。
+- WebView 高频 `editor.contentChange` 也只应依赖轻量摘要；完整内容通过 `requestContent` 获取。
 
 ## EditorAPI
 
@@ -178,7 +206,7 @@ editor.executeCommand({ type: 'format.bold' });
 
 const states = editor.getCommandStates();
 const unsubscribe = editor.subscribeCommandStateChange((nextStates) => {
-  console.log(nextStates);
+  renderToolbarState(nextStates);
 });
 
 unsubscribe();
@@ -190,8 +218,8 @@ editor.destroy();
 - `getContent()`：读取完整内容。
 - `setContent(content)`：写入内容。
 - `executeCommand(command)`：执行命令。
-- `requestPayloadPanel(request)`：打开参数面板请求。
-- `getCommandStates()`：读取命令状态。
+- `requestPayloadPanel(request)`：打开参数面板请求，供自绘菜单复用。
+- `getCommandStates()`：读取当前命令状态。
 - `subscribeCommandStateChange(listener)`：订阅命令状态变化。
 - `setReadonly(readonly)`：切换只读。
 - `focus()` / `blur()`：焦点控制。
@@ -199,6 +227,8 @@ editor.destroy();
 
 ## 命令 API
 
+所有菜单最终都会落到 `EditorCommand`。业务也可以直接调用命令 API。
+
 文本格式：
 
 ```ts
@@ -217,7 +247,7 @@ editor.executeCommand({ type: 'format.fontFamily', value: 'Arial' });
 editor.executeCommand({ type: 'format.lineHeight', value: '1.75' });
 ```
 
-段落、列表和对齐：
+段落、列表、对齐：
 
 ```ts
 editor.executeCommand({ type: 'block.paragraph' });
@@ -239,7 +269,7 @@ editor.executeCommand({ type: 'indent.increase' });
 editor.executeCommand({ type: 'indent.decrease' });
 ```
 
-链接、表格、媒体和历史：
+链接、表格、媒体、历史：
 
 ```ts
 editor.executeCommand({ type: 'link.set', href: 'https://example.com', text: 'Example' });
@@ -277,21 +307,23 @@ editor.executeCommand({ type: 'content.clear' });
 ```
 
 默认 toolbar 不提供图片/视频 URL 插入入口，但保留 `media.insertImage` 和
-`media.insertVideo` 命令。主动链接编辑也不作为默认内置入口，业务可以通过自定义菜单调用
-`link.set`、`link.unset` 和 `link.open`。
+`media.insertVideo` 命令。主动链接编辑也不是当前默认内置重点，业务可以通过自定义菜单调用
+`link.*` 命令。
 
-## Toolbar 和 Tabbar
+## Toolbar / Tabbar 菜单配置
 
-内置 toolbar/tabbar 配置：
+DOM toolbar/tabbar 只通过 `createRichTextToolbar()` 创建。它使用同一套菜单 schema/config，
+并通过传入的 `EditorAPI` 订阅状态、执行命令。
 
 ```ts
-createRichTextEditor(container, {
-  platform: 'h5',
-  toolbarMode: 'bottom',
+const toolbar = createRichTextToolbar(toolbarContainer, {
+  editor,
+  placement: 'bottom',
   toolbarConfig: {
     toolbarKeys: [
       'bold',
       'italic',
+      'underline',
       '|',
       'heading-1',
       'quote',
@@ -306,45 +338,39 @@ createRichTextEditor(container, {
     excludeKeys: ['quote']
   }
 });
+
+toolbar.update();
 ```
 
 `toolbarConfig` 规则：
 
 - `toolbarKeys`：完整控制显示顺序。
+- 字符串项使用 `MenuItem.id`；`'|'` 只渲染分割线，不执行命令。
+- 分组项使用 `{ key, title, icon, menuKeys }`；DOM toolbar 会渲染一个分组按钮，点击后打开
+  Y 轴纵向收纳菜单，例如上面的配置会显示 `[历史]` 按钮，菜单里是 `[撤销]`、`[重做]`。
+- `key` 是分组入口的稳定 id，`title` 是按钮文案和 `aria-label`，`icon` 用于分组按钮图标。
 - `insertKeys`：在默认菜单基础上插入。
 - `excludeKeys`：隐藏默认菜单。
-- `'|'`：分割线。
 
-关闭内置 toolbar，自己挂载：
+独立 toolbar：
 
 ```ts
-import { createRichTextEditor, createRichTextToolbar, defaultMenuSchema } from 'bridgerte';
-
-const editor = createRichTextEditor(editorContainer, {
-  toolbarMode: 'none'
-});
-
 const toolbar = createRichTextToolbar(toolbarContainer, {
   editor,
-  menuSchema: defaultMenuSchema,
-  placement: 'bottom',
+  placement: 'top',
   toolbarConfig: {
     toolbarKeys: ['bold', 'italic', '|', 'undo', 'redo']
   }
 });
 
 toolbar.update();
-toolbar.destroy();
-editor.destroy();
 ```
 
-`placement: 'top' | 'bottom'` 只表达菜单语义和默认样式状态。toolbar DOM 放在哪里、是否吸顶或吸底，
-由业务自己的布局决定。
-
 ## 自定义菜单、Icon 和文案
 
 ```ts
-import { createRichTextEditor, defaultMenuSchema, type MenuItem } from 'bridgerte';
+import { createRichTextEditor, createRichTextToolbar } from 'bridgerte/dom';
+import { defaultMenuSchema, type MenuItem } from 'bridgerte/native-spec';
 
 const customMenu: MenuItem = {
   id: 'custom-clear',
@@ -354,36 +380,50 @@ const customMenu: MenuItem = {
   group: 'history'
 };
 
-createRichTextEditor(container, {
-  menuSchema: [...defaultMenuSchema, customMenu],
+const menuSchema = [...defaultMenuSchema, customMenu];
+const icons = {
+  'custom-clear': '<svg aria-hidden="true" viewBox="0 0 24 24"><path d="M4 6h16"/></svg>'
+};
+const menuLabels = {
+  'custom-clear': '清空文档',
+  bold: '加粗文本'
+};
+
+const editor = createRichTextEditor(editorContainer, {
+  menuSchema,
+  icons,
+  menuLabels
+});
+
+const toolbar = createRichTextToolbar(toolbarContainer, {
+  editor,
+  menuSchema,
   toolbarConfig: {
     insertKeys: {
       index: 0,
       keys: ['custom-clear', '|']
     }
   },
-  icons: {
-    'custom-clear': '<svg aria-hidden="true" viewBox="0 0 24 24"><path d="M4 6h16"/></svg>'
-  },
-  menuLabels: {
-    'custom-clear': '清空文档',
-    bold: '加粗文本'
-  }
+  icons,
+  menuLabels
 });
+
+toolbar.update();
 ```
 
-稳定规则：
+稳定约束：
 
 - `MenuItem.id` 是菜单配置使用的稳定 key。
 - `MenuItem.icon` 是稳定 icon key，不是 SVG 字符串。
-- 替换 icon 使用 `icons` map。
-- 替换文案使用 `menuLabels`。
-- `menuLabels` 只影响展示、tooltip 和 `aria-label`，不改变命令语义。
-- 缺失 icon 时，DOM 菜单会使用 label 文本兜底。
+- 业务覆盖 icon 只能通过 `icons` map。
+- 业务覆盖文案只能通过 `menuLabels`。
+- `menuLabels` 影响按钮文本、tooltip 和 `aria-label`，不改变命令语义。
+- 缺失 icon 时，DOM 菜单使用 label 文本兜底。
 
 ## Hoverbar
 
-选中文本 hoverbar 默认开启，复用 `menuSchema`、`icons` 和 `menuLabels`。
+选中文本 hoverbar 默认开启，复用 `menuSchema`、`icons` 和 `menuLabels`。它有独立的
+`hoverbarConfig`，可以和 toolbar 展示不同菜单。
 
 ```ts
 createRichTextEditor(container, {
@@ -412,11 +452,13 @@ createRichTextEditor(container, {
 });
 ```
 
-关闭后只是不显示 DOM hoverbar，不影响底层命令 API。
+关闭后只是不显示 DOM hoverbar，不影响底层命令 API。H5/WebView 或品牌化项目可以关闭内置
+hoverbar 后自绘选区菜单。
 
 ## 参数面板
 
-颜色、背景色、字号、字体、行高、表格和代码语言都通过参数面板描述候选项。
+颜色、背景色、字号、字体、行高、表格和代码语言都通过 `PayloadPanelSchema` 描述候选项。
+DOM 默认 UI 和业务自绘 request 使用同一份 schema。
 
 ```ts
 createRichTextEditor(container, {
@@ -432,7 +474,7 @@ createRichTextEditor(container, {
         }
       }
     },
-    'text-color': {
+    color: {
       fields: {
         value: {
           options: [
@@ -442,15 +484,22 @@ createRichTextEditor(container, {
         }
       }
     },
-    'table-insert': {
+    table: {
       fields: {
         rows: { defaultValue: '2', max: 6 },
         cols: { defaultValue: '3', max: 6 }
       }
+    },
+    'code-block-language': {
+      fields: {
+        language: {
+          includeValues: ['plain', 'javascript', 'typescript', 'json']
+        }
+      }
     }
   },
   onPayloadPanelRequest(request) {
-    if (request.panel.id === 'text-color') {
+    if (request.panel.id === 'color') {
       renderColorPanel(request);
       return true;
     }
@@ -458,21 +507,64 @@ createRichTextEditor(container, {
 });
 ```
 
-`onPayloadPanelRequest` 返回 `true` 表示业务接管渲染，DOM 默认面板不会显示。业务自绘完成后调用：
+自绘接管规则：
+
+```ts
+createRichTextEditor(container, {
+  onPayloadPanelRequest(request) {
+    renderPanel({
+      title: request.panel.title,
+      fields: request.panel.fields,
+      currentValues: request.currentValues,
+      readonly: request.readonly,
+      submit: request.submit,
+      cancel: request.cancel
+    });
+
+    return true;
+  }
+});
+```
+
+`onPayloadPanelRequest` 返回 `true` 表示业务接管渲染，DOM 默认面板不会显示。业务自绘完成后：
 
 ```ts
 request.submit({ value: '#1677ff' });
 request.cancel();
 ```
 
-readonly 下 request 会带 `readonly: true`，自绘层应展示只读态。
+readonly 下 request 会带 `readonly: true`，自绘层应展示只读态；DOM 默认面板不会打开。
+
+代码块语言也可以直接传完整 schema：
+
+```ts
+createRichTextEditor(container, {
+  codeBlockLanguagePanel: {
+    id: 'code-block-language',
+    title: '代码语言',
+    fields: [
+      {
+        type: 'select',
+        name: 'language',
+        label: '语言',
+        options: [
+          { label: '纯文本', value: 'plain' },
+          { label: 'TypeScript', value: 'typescript' },
+          { label: 'JSON', value: 'json' }
+        ]
+      }
+    ]
+  }
+});
+```
 
 ## 图片、视频和上传
 
-BridgeRTE 不内置上传后端。图片/视频上传需要业务实现 `uploadAdapter`。
+BridgeRTE 不内置上传后端。图片/视频上传必须由业务实现 `uploadAdapter`。
 
 ```ts
-import type { UploadAdapter } from 'bridgerte';
+import { createRichTextEditor } from 'bridgerte/dom';
+import type { UploadAdapter } from 'bridgerte/core';
 
 const uploadBlob = async (url: string, file: unknown, signal?: AbortSignal) => {
   const formData = new FormData();
@@ -512,6 +604,7 @@ createRichTextEditor(container, {
 
 - 默认 toolbar 提供本地上传图片/视频入口。
 - URL 图片/视频插入使用 `media.insertImage` / `media.insertVideo` 命令。
+- 图片/视频加载前会显示占位和 loading 状态，资源加载完成后再显示真实媒体。
 - 上传失败时可以重试或删除。
 - 成功态 controls 支持左/中/右对齐、`20%`、`50%`、`100%` 显示比例和删除。
 - `mediaDefaultWidthPercent` 可设为 `20 | 50 | 100`，默认 `50`。
@@ -521,7 +614,13 @@ createRichTextEditor(container, {
 ```ts
 createRichTextEditor(container, {
   mediaControlsConfig: {
-    toolbarKeys: ['media-align-left', 'media-align-center', 'media-align-right', '|', 'media-remove']
+    toolbarKeys: [
+      'media-align-left',
+      'media-align-center',
+      'media-align-right',
+      '|',
+      'media-remove'
+    ]
   },
   menuLabels: {
     'media-remove': '删除媒体'
@@ -534,10 +633,12 @@ createRichTextEditor(container, {
 
 ## Mention
 
-`@` mention 默认开启。provider 负责返回候选数据，展示字段由 `mentionMenuConfig` 控制。
+`@` mention 默认开启。`mentionProvider` 负责返回候选数据，展示字段由
+`mentionMenuConfig` 控制。
 
 ```ts
-import type { MentionItem } from 'bridgerte';
+import { createRichTextEditor } from 'bridgerte/dom';
+import type { MentionItem } from 'bridgerte/core';
 
 const mentionProvider = async (query: string): Promise<MentionItem[]> => {
   const response = await fetch(`/api/members?q=${encodeURIComponent(query)}`);
@@ -603,7 +704,7 @@ createRichTextEditor(container, {
 追加动态候选：
 
 ```ts
-import type { SlashCommandItem } from 'bridgerte';
+import type { SlashCommandItem } from 'bridgerte/core';
 
 const slashCommandProvider = async (query: string): Promise<SlashCommandItem[]> => [
   {
@@ -653,7 +754,7 @@ createRichTextEditor(container, {
 
 ## WebView
 
-WebView 页面内用 `createWebViewBridgeRuntime()` 接 RN/Flutter 外壳消息。
+WebView 页面内使用 `createWebViewBridgeRuntime()` 接 RN/Flutter 外壳消息。
 
 ```ts
 import { createWebViewBridgeRuntime } from 'bridgerte/webview';
@@ -707,20 +808,23 @@ runtime.receive(messageFromNative);
 - `editor.ready`
 - `editor.content`
 - `editor.contentChange`
-- `editor.selectionChange`
 - `editor.commandStateChange`
 - `editor.payloadPanelRequest`
 - `editor.uploadRequest`
 - `editor.heightChange`
 - `editor.error`
 
-高频自动 `editor.contentChange` 只传轻量摘要。完整 `EditorContent` 通过原生侧发送
-`editor.requestContent` 获取，响应消息是 `editor.content`。兼容期也会同步发送旧
-`editor.contentChange` 完整响应。bridge 不传 File、Blob、base64 或大体积二进制文件。
+内容消息边界：
+
+- 高频自动 `editor.contentChange` 只传轻量摘要。
+- 完整 `EditorContent` 通过原生侧发送 `editor.requestContent` 获取。
+- `requestContent` 的响应消息是 `editor.content`。
+- 兼容期也会同步发送旧 `editor.contentChange` 完整响应。
+- bridge 不传 File、Blob、base64 或大体积二进制文件。
 
 ## RN / Flutter 原生菜单
 
-原生菜单可以读取 `bridgerte/native-spec`：
+RN/Flutter 原生侧可以读取 `bridgerte/native-spec` 来渲染自己的菜单：
 
 ```ts
 import {
@@ -742,7 +846,7 @@ const toolbarItems = resolveToolbarMenu(defaultToolbarConfig, defaultMenuSchema)
 - `payloadPanel` 描述需要原生侧补齐的参数。
 - 命令状态可用 `isMenuItemCommandState(item, state)` 匹配。
 
-原生菜单不复用 DOM CSS；WebView 内部编辑器样式通过 `--bridgerte-*` CSS Variables 覆盖。
+原生菜单不复用 DOM CSS；WebView 内编辑器样式通过 `--bridgerte-*` CSS Variables 覆盖。
 
 ## 样式和主题
 
@@ -794,6 +898,13 @@ import 'bridgerte/style.css';
 - `--bridgerte-hoverbar-button-size`
 - `--bridgerte-editor-padding`
 
+PC/H5 边界：
+
+- DOM 默认样式只服务 Web/PC/H5。
+- RN/Flutter 原生菜单不复用 DOM CSS。
+- H5 触屏端不依赖 hover tooltip。
+- 业务可以在外层容器覆盖 CSS Variables 实现品牌主题。
+
 ## 性能建议
 
 BridgeRTE 按 10w 字符级内容设计输入路径：
@@ -824,7 +935,8 @@ const save = async () => {
 
 ## 当前边界
 
+- 业务项目只安装 `bridgerte`，不需要安装 Lexical。
 - 默认 toolbar 不提供图片/视频 URL 插入入口；业务用命令 API 自定义入口。
 - 主动链接编辑不作为默认内置入口；业务用 `link.*` 命令自定义入口。
-- BridgeRTE 不内置上传后端。
+- BridgeRTE 不内置上传后端，上传必须由业务实现 `uploadAdapter`。
 - WebView bridge 不传大体积二进制和 base64 文件。