bridgerte 0.9.0

package/dist/index.d.ts

@@ -0,0 +1,1233 @@
+/*
+ * 此文件由内部包声明生成。
+ * 不要手动修改；需要更新时运行 pnpm build 重新生成。
+ */
+
+/**
+ * 编辑器内容中被引用的资源元信息。
+ *
+ * 这个类型只描述跨端可保存的资源状态，不绑定具体上传实现或 DOM 节点。
+ */
+export type EditorAsset = {
+    id: string;
+    type: 'image' | 'video';
+    url: string;
+    status?: 'uploading' | 'success' | 'error';
+    progress?: number;
+    poster?: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+    mimeType?: string;
+    size?: number;
+    displayWidthPercent?: MediaDisplayWidthPercent;
+    align?: MediaAlign;
+    errorMessage?: string;
+    external?: boolean;
+};
+/**
+ * DOM 内置媒体控制条第一版只开放固定比例。
+ *
+ * 这里先收窄为预设值，避免业务端误传任意数字造成 Web/H5/RN/Flutter 展示不一致。
+ */
+export type MediaDisplayWidthPercent = 20 | 50 | 100;
+/**
+ * 媒体块在编辑区内容宽度内的水平对齐方式。
+ *
+ * 对齐只影响展示位置，不改变图片/视频真实尺寸、上传元信息或内容流顺序。
+ */
+export type MediaAlign = 'left' | 'center' | 'right';
+/**
+ * BridgeRTE 持久化内容 JSON 的基础节点。
+ *
+ * v1 可以承载 Lexical editor state 的 JSON 形态，但对外仍归属于 BridgeRTE 内容协议。
+ */
+export type EditorContentNode = {
+    type: string;
+    version?: number;
+    text?: string;
+    children?: EditorContentNode[];
+    [key: string]: unknown;
+};
+/**
+ * BridgeRTE 对外保存的结构化内容。
+ *
+ * 这里保留 root 包裹层，后续即使从 Lexical JSON 迁移也能通过内容协议版本处理。
+ */
+export type EditorContentJson = {
+    root: EditorContentNode;
+};
+/**
+ * 编辑器对外读写的稳定内容结构。
+ *
+ * `html` 是编辑区 HTML 片段，`json` 是 BridgeRTE 内容 JSON，`plainText` 服务搜索摘要。
+ */
+export type EditorContent = {
+    html: string;
+    json: EditorContentJson;
+    plainText: string;
+    assets: EditorAsset[];
+    version: string;
+};
+/**
+ * 高频内容变更摘要。
+ *
+ * 输入、selection 和 WebView bridge 这类高频链路只需要知道内容已经变脏、当前文本长度
+ * 和协议版本；完整 `EditorContent` 仍由 `getContent()` 或低频保存动作主动读取。
+ */
+export type EditorContentChange = {
+    dirty: boolean;
+    plainTextLength: number;
+    version: string;
+    maxLength?: number;
+    isOverMaxLength: boolean;
+};
+
+/**
+ * 跨端取消信号的最小契约。
+ *
+ * 浏览器、RN、Flutter 都可以把各自的取消实现适配成这个结构。
+ */
+export type UploadAbortSignalLike = {
+    readonly aborted: boolean;
+    addEventListener?: (type: 'abort', listener: () => void, options?: {
+        once?: boolean;
+    }) => void;
+    removeEventListener?: (type: 'abort', listener: () => void) => void;
+};
+/**
+ * 跨端上传文件输入。
+ *
+ * `data` 保持 unknown，浏览器可放文件对象，RN/Flutter 可放 uri、fileId 或原生文件句柄。
+ */
+export type UploadFileLike = {
+    name?: string;
+    mimeType?: string;
+    size?: number;
+    data: unknown;
+};
+/**
+ * 单次上传任务的运行时上下文。
+ *
+ * `signal` 用于取消上传，`onProgress` 用于把进度回传给编辑器 UI。
+ */
+export type UploadContext = {
+    assetId: string;
+    onProgress?: (percent: number) => void;
+    signal?: UploadAbortSignalLike;
+};
+/**
+ * 上传适配器返回的资源结果。
+ *
+ * 字段保持后端无关，业务可以按图片、视频能力逐步补齐元信息。
+ */
+export type UploadResult = {
+    url: string;
+    poster?: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+    mimeType?: string;
+    size?: number;
+};
+/**
+ * 业务侧注入的上传能力。
+ *
+ * 编辑器只调用这个契约，不直接绑定 OSS、S3、COS 等具体服务。
+ */
+export type UploadAdapter = {
+    uploadImage(file: UploadFileLike, context: UploadContext): Promise<UploadResult>;
+    uploadVideo(file: UploadFileLike, context: UploadContext): Promise<UploadResult>;
+};
+/**
+ * 上传失败时对宿主暴露的错误摘要。
+ *
+ * `cause` 保持 unknown，调用方需要自行收窄具体错误类型。
+ */
+export type UploadError = {
+    assetId: string;
+    type: 'image' | 'video';
+    cause: unknown;
+};
+
+/**
+ * 粘贴事件给业务 hook 的跨端稳定摘要。
+ *
+ * DOM 端会把 ClipboardEvent 转成这份结构；业务可以阻止默认粘贴，或替换 text/html 后
+ * 继续交给 BridgeRTE 的内置 URL 快速路径和 HTML 清洗链路处理。
+ */
+export type PasteRequest = {
+    text: string;
+    html: string;
+    files: UploadFileLike[];
+};
+export type PasteHookResult = boolean | void | {
+    text?: string;
+    html?: string;
+};
+export type PasteHook = (request: PasteRequest) => PasteHookResult | Promise<PasteHookResult>;
+
+/**
+ * toolbar JSON 配置里的菜单组。
+ *
+ * `menuKeys` 使用菜单 schema 的稳定 id，DOM 先按简单横向分组渲染；
+ * 后续需要下拉菜单时，可以继续复用这份结构。
+ */
+export type ToolbarGroupConfig = {
+    key: string;
+    title: string;
+    icon?: string;
+    menuKeys: string[];
+};
+/**
+ * toolbar JSON 配置项。
+ *
+ * 字符串使用 `MenuItem.id`；特殊字符串 `|` 表示分割线，视觉保持和默认 group 分隔一致。
+ */
+export type ToolbarKey = string | ToolbarGroupConfig;
+/**
+ * 面向业务方的 toolbar JSON 配置。
+ *
+ * `toolbarKeys` 用于完全决定显示内容和顺序；`insertKeys` 和 `excludeKeys`
+ * 用于在默认配置上做增减，心智接近 wangEditor。
+ */
+export type ToolbarConfig = {
+    toolbarKeys?: ToolbarKey[];
+    insertKeys?: {
+        index: number;
+        keys: ToolbarKey[];
+    };
+    excludeKeys?: string[];
+};
+
+/**
+ * `@` mention 菜单中的候选项。
+ *
+ * `data` 用于保留业务扩展字段，但 public API 不规定内部结构。
+ */
+export type MentionItem = {
+    id: string;
+    label: string;
+    value: string;
+    avatar?: string;
+    description?: string;
+    data?: Record<string, unknown>;
+};
+/**
+ * mention 数据源可以同步返回，也可以异步搜索。
+ */
+export type MentionProvider = (query: string) => Promise<MentionItem[]> | MentionItem[];
+/**
+ * mention 候选项展示字段。
+ *
+ * 顶层字段读取 `MentionItem`；`data.xxx` 读取业务扩展数据，避免 provider 为了 UI 展示
+ * 改变稳定的 mention 内容 payload。
+ */
+export type MentionMenuFieldPath = 'id' | 'label' | 'value' | 'avatar' | 'description' | `data.${string}`;
+export type MentionMenuStatus = 'loading' | 'success' | 'empty' | 'error';
+/**
+ * mention 菜单展示配置。
+ *
+ * provider 仍只负责返回候选数据；这里决定默认 DOM UI 和业务自绘 request 如何读取
+ * avatar/icon/label/description 字段，以及 loading/empty/error 状态文案。
+ */
+export type MentionMenuConfig = {
+    labelField?: MentionMenuFieldPath;
+    descriptionField?: MentionMenuFieldPath;
+    avatarField?: MentionMenuFieldPath;
+    iconField?: MentionMenuFieldPath;
+    showAvatar?: boolean;
+    showIcon?: boolean;
+    showDescription?: boolean;
+    loadingText?: string;
+    emptyText?: string;
+    errorText?: string;
+};
+export type MentionMenuDisplayItem = {
+    item: MentionItem;
+    label: string;
+    description?: string;
+    avatar?: string;
+    icon?: string;
+};
+export type MentionMenuAnchorRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * 传给业务自绘层的 mention 菜单请求。
+ *
+ * request 会随着 query 和 provider 状态变化重复发出；业务返回 true 表示接管渲染，
+ * 之后通过 submit/cancel 完成选择或取消，DOM 默认菜单不会出现。
+ */
+export type MentionMenuRequest = {
+    id: string;
+    query: string;
+    status: MentionMenuStatus;
+    items: MentionMenuDisplayItem[];
+    config: MentionMenuConfig;
+    readonly: boolean;
+    anchorRect?: MentionMenuAnchorRect;
+    error?: unknown;
+    submit(item: MentionItem): void;
+    cancel(): void;
+};
+/**
+ * 清理格式的范围。
+ *
+ * `selection` 是默认范围，只清理当前选区内的 inline/block 样式。
+ */
+export type FormatClearScope = 'selection' | 'block';
+/**
+ * 代码块语言标识。
+ *
+ * 保持 string 是为了兼容 highlight.js、Prism 或业务自定义语言表。
+ */
+export type CodeBlockLanguage = string;
+/**
+ * 创建代码块时允许携带的参数。
+ */
+export type CodeBlockOptions = {
+    language?: CodeBlockLanguage;
+};
+/**
+ * 更新当前代码块语言时允许携带的参数。
+ */
+export type CodeBlockLanguageOptions = {
+    language: CodeBlockLanguage;
+};
+/**
+ * 表格行列插入位置，相对当前行列或指定行列计算。
+ */
+export type TableDirection = 'before' | 'after';
+/**
+ * 表格命令的目标位置。
+ *
+ * 不传时由当前选区所在单元格决定。
+ */
+export type TableTarget = {
+    rowIndex?: number;
+    colIndex?: number;
+};
+/**
+ * 插入表格行的参数。
+ *
+ * `count` 默认是 1，具体插入位置由 direction 和目标行决定。
+ */
+export type TableInsertRowOptions = TableTarget & {
+    direction?: TableDirection;
+    count?: number;
+};
+/**
+ * 插入表格列的参数。
+ *
+ * `count` 默认是 1，具体插入位置由 direction 和目标列决定。
+ */
+export type TableInsertColumnOptions = TableTarget & {
+    direction?: TableDirection;
+    count?: number;
+};
+/**
+ * 删除表格行的参数。
+ *
+ * 不传目标时删除当前选区所在行。
+ */
+export type TableDeleteRowOptions = TableTarget & {
+    count?: number;
+};
+/**
+ * 删除表格列的参数。
+ *
+ * 不传目标时删除当前选区所在列。
+ */
+export type TableDeleteColumnOptions = TableTarget & {
+    count?: number;
+};
+/**
+ * 插入图片命令的稳定 payload。
+ *
+ * `assetId` 用于关联 `EditorContent.assets` 中的资源元信息。
+ */
+export type ImageInsertPayload = {
+    url: string;
+    alt?: string;
+    title?: string;
+    width?: number;
+    height?: number;
+    displayWidthPercent?: MediaDisplayWidthPercent;
+    align?: MediaAlign;
+    assetId?: string;
+};
+/**
+ * 插入视频命令的稳定 payload。
+ *
+ * `poster` 和尺寸信息用于 DOM 渲染和原生侧预览。
+ */
+export type VideoInsertPayload = {
+    url: string;
+    poster?: string;
+    title?: string;
+    width?: number;
+    height?: number;
+    displayWidthPercent?: MediaDisplayWidthPercent;
+    align?: MediaAlign;
+    assetId?: string;
+};
+/**
+ * 跨端命令协议。
+ *
+ * 命令只表达编辑语义，不泄漏 Lexical、DOM 或原生平台的实现类型。
+ */
+export type EditorCommand = {
+    type: 'format.bold';
+} | {
+    type: 'format.italic';
+} | {
+    type: 'format.underline';
+} | {
+    type: 'format.strike';
+} | {
+    type: 'format.inlineCode';
+} | {
+    type: 'format.superscript';
+} | {
+    type: 'format.subscript';
+} | {
+    type: 'format.clear';
+    scope?: FormatClearScope;
+} | {
+    type: 'format.color';
+    value: string;
+} | {
+    type: 'format.backgroundColor';
+    value: string;
+} | {
+    type: 'format.fontSize';
+    value: string;
+} | {
+    type: 'format.fontFamily';
+    value: string;
+} | {
+    type: 'format.lineHeight';
+    value: string;
+} | {
+    type: 'block.heading';
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+} | {
+    type: 'block.paragraph';
+} | {
+    type: 'block.quote';
+} | {
+    type: 'block.divider';
+} | ({
+    type: 'block.code';
+} & CodeBlockOptions) | ({
+    type: 'block.setCodeLanguage';
+} & CodeBlockLanguageOptions) | {
+    type: 'list.ordered';
+} | {
+    type: 'list.unordered';
+} | {
+    type: 'list.todo';
+} | {
+    type: 'align';
+    value: 'left' | 'center' | 'right' | 'justify';
+} | {
+    type: 'indent.increase';
+} | {
+    type: 'indent.decrease';
+} | {
+    type: 'link.set';
+    href: string;
+    text?: string;
+} | {
+    type: 'link.unset';
+} | {
+    type: 'link.open';
+} | {
+    type: 'mention.insert';
+    item: MentionItem;
+} | {
+    type: 'slash.open';
+} | {
+    type: 'media.pickImage';
+} | {
+    type: 'media.pickVideo';
+} | {
+    type: 'media.retry';
+    assetId: string;
+} | {
+    type: 'media.remove';
+    assetId: string;
+} | {
+    type: 'media.resize';
+    assetId: string;
+    widthPercent: MediaDisplayWidthPercent;
+} | {
+    type: 'media.align';
+    assetId: string;
+    value: MediaAlign;
+} | {
+    type: 'media.resetSize';
+    assetId: string;
+} | ({
+    type: 'media.insertImage';
+} & ImageInsertPayload) | ({
+    type: 'media.insertVideo';
+} & VideoInsertPayload) | {
+    type: 'table.insert';
+    rows: number;
+    cols: number;
+} | {
+    type: 'table.delete';
+} | ({
+    type: 'table.insertRow';
+} & TableInsertRowOptions) | ({
+    type: 'table.deleteRow';
+} & TableDeleteRowOptions) | ({
+    type: 'table.insertColumn';
+} & TableInsertColumnOptions) | ({
+    type: 'table.deleteColumn';
+} & TableDeleteColumnOptions) | {
+    type: 'fullscreen.toggle';
+} | {
+    type: 'history.undo';
+} | {
+    type: 'history.redo';
+} | {
+    type: 'content.clear';
+};
+/**
+ * 发起参数面板所需的稳定请求体。
+ *
+ * toolbar、WebView runtime 和业务自绘层都用它描述“哪个菜单需要补哪些参数”。
+
+ * `command` 直接复用编辑器命令协议，避免 UI 菜单和执行协议分叉。
+ */
+export type SlashCommandItem = {
+    id: string;
+    label: string;
+    command: EditorCommand;
+    icon?: string;
+    description?: string;
+    keywords?: string[];
+    group?: string;
+    requiresPayload?: boolean;
+    payloadPanel?: PayloadPanelSchema;
+};
+export type SlashCommandStatus = 'loading' | 'success' | 'empty' | 'error';
+export type SlashCommandDisplayItem = SlashCommandItem & {
+    source: 'schema' | 'provider';
+};
+export type SlashCommandMenuAnchorRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type SlashCommandMenuConfig = {
+    loadingText?: string;
+    emptyText?: string;
+    errorText?: string;
+};
+/**
+ * 传给业务自绘层的 slash command 菜单请求。
+ *
+ * 默认命令来自 schema/config，provider 只作为动态候选补充；业务返回 true 后通过
+ * submit/cancel 接续同一条选择链路，避免 DOM 默认菜单和原生/自绘菜单执行语义分叉。
+ */
+export type SlashCommandMenuRequest = {
+    id: string;
+    query: string;
+    status: SlashCommandStatus;
+    items: SlashCommandDisplayItem[];
+    config: SlashCommandMenuConfig;
+    readonly: boolean;
+    anchorRect?: SlashCommandMenuAnchorRect;
+    error?: unknown;
+    submit(item: SlashCommandDisplayItem | SlashCommandItem): void;
+    cancel(): void;
+};
+/**
+ * slash command 数据源可以按 query 过滤命令，也可以接入远程数据。
+ */
+export type SlashCommandProvider = (query: string) => Promise<SlashCommandItem[]> | SlashCommandItem[];
+export type CommandState = {
+    command: EditorCommand['type'];
+    active: boolean;
+    disabled: boolean;
+    value?: string | number | boolean;
+};
+
+/**
+ * 跨端菜单项描述。
+ *
+ * `id` 是 schema/config 引用的稳定 key，`icon` 是跨端稳定图标 key；
+ * SVG 或原生图标实例必须由各端 icon map 提供，不能写进 schema。
+ */
+export type MenuItem = {
+    id: string;
+    command: EditorCommand;
+    label: string;
+    icon: string;
+    group: 'text' | 'style' | 'block' | 'list' | 'align' | 'insert' | 'media' | 'table' | 'history' | 'view';
+    requiresPayload?: boolean;
+    payloadPanel?: PayloadPanelSchema;
+    children?: MenuItem[];
+};
+/**
+ * 菜单 label 覆盖表。
+ *
+ * key 使用 `MenuItem.id`，只影响展示文本、tooltip 和无障碍名称；
+ * 不改变 command、payloadPanel 或 schema 稳定 id。
+ */
+export type MenuLabelOverrides = Partial<Record<string, string>>;
+
+/**
+ * 参数面板选项。
+ *
+ * select 字段使用它表达候选项；颜色、字号和业务自绘链接等菜单继续复用同一套面板协议。
+ */
+export type PayloadPanelOption = {
+    label: string;
+    value: string;
+    description?: string;
+};
+/**
+ * 参数面板字段基础信息。
+ *
+ * 字段值仍统一以 string 提交，DOM 默认 UI 和 RN/Flutter 自绘层根据 `type` 选择控件。
+ */
+export type PayloadPanelFieldBase = {
+    name: string;
+    label: string;
+    defaultValue?: string;
+    placeholder?: string;
+};
+/**
+ * 参数面板字段。
+ *
+ * `select` 服务预设候选；`color` 服务文字颜色和背景色；`text` 服务业务自绘链接等自由输入；
+ * `number` 服务表格行列、媒体尺寸等数值参数。
+ */
+export type PayloadPanelField = PayloadPanelFieldBase & ({
+    type: 'select';
+    options: PayloadPanelOption[];
+} | {
+    type: 'color';
+    options?: PayloadPanelOption[];
+} | {
+    type: 'text';
+} | {
+    type: 'number';
+    min?: number;
+    max?: number;
+    step?: number;
+});
+/**
+ * 菜单参数面板 schema。
+ *
+ * `id` 作为跨端稳定标识，`fields` 描述业务需要补齐哪些 command payload 字段。
+ */
+export type PayloadPanelSchema = {
+    id: string;
+    title: string;
+    description?: string;
+    fields: PayloadPanelField[];
+};
+/**
+ * 参数面板候选项配置。
+ *
+ * `includeValues` 用于按原始 value 白名单重排；`excludeValues` 用于隐藏候选项；
+ * `optionLabels` 和 `optionValues` 以原始 value 为 key，只改展示或最终提交值。
+ */
+export type PayloadPanelFieldOptionConfig = {
+    options?: PayloadPanelOption[];
+    includeValues?: string[];
+    excludeValues?: string[];
+    optionLabels?: Partial<Record<string, string>>;
+    optionValues?: Partial<Record<string, string>>;
+};
+/**
+ * 参数面板字段配置。
+ *
+ * select/color 字段读取候选项配置；number 字段读取 min/max/step/defaultValue 等数值边界。
+ * 未匹配字段会被忽略，避免业务配置误伤不相关 panel。
+ */
+export type PayloadPanelFieldConfig = PayloadPanelFieldOptionConfig & {
+    label?: string;
+    defaultValue?: string;
+    placeholder?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+};
+export type PayloadPanelSchemaConfig = {
+    title?: string;
+    description?: string;
+    fields?: Record<string, PayloadPanelFieldConfig>;
+};
+/**
+ * 参数面板配置表。
+ *
+ * 第一层 key 使用 `PayloadPanelSchema.id`，让 toolbar、hoverbar、code block header、
+ * WebView 和业务自绘都能对同一份 panel schema 做一致裁剪。
+ */
+export type PayloadPanelConfig = Record<string, PayloadPanelSchemaConfig>;
+/**
+ * 参数面板提交值。
+ *
+ * 第一版字段值都用 string 表达；具体命令会在 DOM SDK 中按 command type 做最小转换。
+ */
+export type PayloadPanelValues = Record<string, string>;
+/**
+ * 参数面板锚点矩形。
+ *
+ * 这里不用 DOMRect，避免 core 暴露浏览器类型；DOM、RN、Flutter 都能构造这个形状。
+ */
+export type PayloadPanelAnchorRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type PayloadPanelOpenRequest = {
+    menuId: string;
+    command: EditorCommand;
+    panel: PayloadPanelSchema;
+    anchorRect?: PayloadPanelAnchorRect;
+    currentValues?: PayloadPanelValues;
+};
+/**
+ * 传给业务自绘层的参数面板请求。
+ *
+ * `readonly` 表示本次请求只能展示，不能提交修改。
+ * `submit` 会把业务收集到的字段值合成为完整命令并执行；readonly 请求下 submit 是 no-op，
+ * `cancel` 只关闭本次请求。
+ */
+export type PayloadPanelRequest = PayloadPanelOpenRequest & {
+    id: string;
+    readonly: boolean;
+    submit(values: PayloadPanelValues): void;
+    cancel(): void;
+};
+
+/**
+ * 解析参数面板 schema。
+ *
+ * 这个纯函数只处理 schema 数据，不理解 DOM、Lexical 或具体命令；toolbar、hoverbar、
+ * code block header 和 WebView host request 都应先走这里，保证默认 UI 和业务自绘同源。
+ */
+export declare const resolvePayloadPanelSchema: (panel: PayloadPanelSchema, config?: PayloadPanelConfig) => PayloadPanelSchema;
+
+/**
+ * 编辑器运行时错误摘要。
+ *
+ * `cause` 保持 unknown，避免把 Lexical、DOM 或宿主环境错误类型泄漏进 public API。
+ */
+export type EditorError = {
+    code: string;
+    message: string;
+    cause?: unknown;
+};
+export type FloatingMenusConfig = {
+    /**
+     * `@` mention 候选菜单开关。默认开启；关闭后不会监听 `@query` 触发，也不会请求 provider。
+     */
+    mention?: boolean;
+    /**
+     * `/` slash command 候选菜单开关。默认开启；关闭后 `/query` 保持普通文本输入。
+     */
+    slash?: boolean;
+    /**
+     * 选中文本 hoverbar 开关。默认开启；关闭后选区不会出现内置基础格式菜单。
+     */
+    hoverbar?: boolean;
+};
+/**
+ * DOM 默认菜单 icon 覆盖表。
+ *
+ * key 使用菜单 schema 的稳定 icon key；DOM 可把 value 当 SVG 字符串渲染，RN/Flutter/WebView
+ * 原生菜单可以忽略这个字段并用同一个 key 映射平台 icon。
+ */
+export type RichTextEditorIcons = Partial<Record<string, string>>;
+export type RichTextEditorOptions = {
+    value?: Partial<EditorContent>;
+    readonly?: boolean;
+    platform?: 'pc' | 'h5' | 'webview';
+    uploadAdapter?: UploadAdapter;
+    /**
+     * 媒体节点没有显式 displayWidthPercent 时的默认展示比例。
+     *
+     * 默认值是 50；业务可以按产品形态改成 20 或 100，内置 UI 仍只提供固定预设。
+     */
+    mediaDefaultWidthPercent?: MediaDisplayWidthPercent;
+    toolbarMode?: 'top' | 'bottom' | 'none' | 'native';
+    /**
+     * DOM 内置 toolbar/tabbar/hoverbar 使用的菜单 schema。
+     *
+     * 自定义菜单必须先进入 schema，再由 `toolbarConfig` 或 `hoverbarConfig` 引用；
+     * 这里不接收 SVG，图标展示仍通过 `icons` 按稳定 icon key 覆盖。
+     */
+    menuSchema?: MenuItem[];
+    toolbarConfig?: ToolbarConfig;
+    /**
+     * DOM 内置 hoverbar 的显示结构配置。
+     *
+     * 复用 `ToolbarConfig` 的 key、分割线、insert 和 exclude 语义，避免 hoverbar
+     * 形成第二套菜单配置规则。
+     */
+    hoverbarConfig?: ToolbarConfig;
+    /**
+     * DOM 内置图片/视频 overlay controls 的显示结构配置。
+     *
+     * 复用 `ToolbarConfig` 的 key、分割线、insert 和 exclude 语义；尺寸入口
+     * `20%`、`50%`、`100%` 是媒体节点基础可用性，解析时会强制保留。
+     */
+    mediaControlsConfig?: ToolbarConfig;
+    /**
+     * DOM 内置 slash command 的静态命令显示结构配置。
+     *
+     * 默认命令来自 `menuSchema`；这里复用 `ToolbarConfig` 的 key、分割线、insert 和
+     * exclude 语义，避免 slash command 形成第三套排序和隐藏规则。
+     */
+    slashCommandConfig?: ToolbarConfig;
+    icons?: RichTextEditorIcons;
+    /**
+     * DOM 内置 toolbar/tabbar/hoverbar 的菜单 label 覆盖。
+     *
+     * key 使用 `MenuItem.id`，只影响按钮文本、tooltip 和 aria-label，不改变命令语义。
+     */
+    menuLabels?: MenuLabelOverrides;
+    /**
+     * 代码块 header 的语言选择面板。
+     *
+     * 默认使用内置的 `codeBlockLanguagePanel`；业务可以传入裁剪后的 schema 来控制语言选项
+     * 显示哪些、顺序怎么排。
+     */
+    codeBlockLanguagePanel?: PayloadPanelSchema;
+    /**
+     * DOM 内置 payload panel 候选项和字段边界配置。
+     *
+     * key 使用 panel id；解析后的同一份 schema 会同时进入 DOM 默认 UI 和
+     * `onPayloadPanelRequest`，避免默认面板和业务自绘看到两套候选项。
+     */
+    payloadPanelConfig?: PayloadPanelConfig;
+    /**
+     * DOM 内置浮层菜单开关。
+     *
+     * 默认全部开启；业务在 H5、WebView 或自绘菜单场景下可以按能力关闭，避免默认浮层
+     * 影响软键盘、原生菜单或宿主自定义交互。
+     */
+    floatingMenus?: FloatingMenusConfig;
+    mentionProvider?: MentionProvider;
+    /**
+     * DOM 默认 mention 候选菜单展示配置。
+     *
+     * provider 只负责返回候选数据；这里决定默认 UI 和自绘 request 如何读取
+     * label、description、avatar 和 icon 字段，以及 loading/empty/error 文案。
+     */
+    mentionMenuConfig?: MentionMenuConfig;
+    onMentionMenuRequest?: (request: MentionMenuRequest) => boolean | void;
+    slashCommandProvider?: SlashCommandProvider;
+    slashCommandMenuConfig?: SlashCommandMenuConfig;
+    onSlashCommandMenuRequest?: (request: SlashCommandMenuRequest) => boolean | void;
+    placeholder?: string;
+    maxLength?: number;
+    /**
+     * DOM 端基础快捷键开关。
+     *
+     * 默认关闭，避免 H5/WebView 或宿主应用已有快捷键被编辑器默认拦截；需要 PC 快捷键时
+     * 由业务显式开启。
+     */
+    keyboardShortcuts?: boolean;
+    /**
+     * 高频内容变更摘要。
+     *
+     * 默认推荐使用这个回调驱动保存按钮、dirty 状态和字数提示；它不会携带完整
+     * html/json/plainText，避免 10w 内容输入时每次变更都触发全量序列化。
+     */
+    onContentChange?: (change: EditorContentChange) => void;
+    /**
+     * 低频完整内容快照。
+     *
+     * 保留旧 API 兼容已有业务；大文档场景推荐改用 `onContentChange` 监听轻量摘要，
+     * 在保存或提交时主动调用 `getContent()`。
+     */
+    onChange?: (content: EditorContent) => void;
+    onReady?: (api: EditorAPI) => void;
+    onCommandStateChange?: (states: CommandState[]) => void;
+    onPayloadPanelRequest?: (request: PayloadPanelRequest) => boolean | void;
+    onPaste?: PasteHook;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    onError?: (error: EditorError) => void;
+    onUploadError?: (error: UploadError) => void;
+};
+/**
+ * 编辑器实例对宿主暴露的最小能力面。
+ *
+ * API 只暴露跨端稳定能力，不暴露内部编辑器对象。
+ */
+export type EditorAPI = {
+    getContent(): EditorContent;
+    setContent(content: Partial<EditorContent>): void;
+    executeCommand(command: EditorCommand): void;
+    requestPayloadPanel(request: PayloadPanelOpenRequest): void;
+    getCommandStates(): CommandState[];
+    subscribeCommandStateChange(listener: (states: CommandState[]) => void): () => void;
+    setReadonly(readonly: boolean): void;
+    focus(): void;
+    blur(): void;
+    destroy(): void;
+};
+
+/**
+ * 内容结构版本号，用于后续内容协议升级时做兼容判断。
+ */
+export declare const BRIDGERTE_CONTENT_VERSION = "0.1.0";
+/**
+ * 默认表格插入能力上限。
+ *
+ * schema、自绘和 DOM 命令执行共用这组边界；DOM 默认面板可以用更小的首屏网格展示，
+ * 但最终提交和 API 执行都不应超过这里声明的库内置上限。
+ */
+export declare const BRIDGERTE_TABLE_INSERT_MAX_ROWS = 20;
+export declare const BRIDGERTE_TABLE_INSERT_MAX_COLS = 20;
+
+/**
+ * 取出菜单命令用于匹配 `CommandState.value` 的稳定值。
+ *
+ * 同类命令存在多个菜单项时使用这个值区分，比如对齐方式和标题级别。
+ */
+export declare const getCommandStateMatchValue: (command: EditorCommand) => CommandState["value"] | undefined;
+/**
+ * 判断某条命令状态是否对应一个完整命令 payload。
+ */
+export declare const isCommandStateForCommand: (command: EditorCommand, state: CommandState) => boolean;
+/**
+ * 判断某条命令状态是否对应一个菜单项。
+ *
+ * 原生 toolbar 可以用它把 `CommandState[]` 映射回具体按钮 active/disabled 状态。
+ */
+export declare const isMenuItemCommandState: (item: MenuItem, state: CommandState) => boolean;
+/**
+ * 为给定菜单生成默认禁用状态。
+ *
+ * 编辑器未 ready 或无选区时，原生 toolbar 可以先使用这组状态兜底。
+ */
+export declare function createDisabledCommandStates(menuSchema?: MenuItem[]): CommandState[];
+
+export type ResolvedToolbarButtonItem = {
+    type: 'button';
+    item: MenuItem;
+};
+export type ResolvedToolbarSeparatorItem = {
+    type: 'separator';
+    key: string;
+};
+export type ResolvedToolbarGroupItem = {
+    type: 'group';
+    key: string;
+    title: string;
+    icon?: string;
+    items: MenuItem[];
+};
+export type ResolvedToolbarItem = ResolvedToolbarButtonItem | ResolvedToolbarSeparatorItem | ResolvedToolbarGroupItem;
+
+/**
+ * 默认 DOM toolbar 配置。
+ *
+ * 这里只选择已实现或带参数面板的基础按钮；完整菜单全集仍由 `defaultMenuSchema` 维护。
+ */
+export declare const defaultToolbarConfig: ToolbarConfig;
+/**
+ * 把 wangEditor 风格的 JSON 配置解析成 DOM/RN/Flutter 都能消费的菜单结构。
+ *
+ * 未知 key 和缺少 payloadPanel 的 requiresPayload 菜单会被忽略，避免默认 toolbar 渲染无法处理的按钮。
+ * 分割线会自动去掉开头、结尾和连续项，避免被跳过的菜单留下空分隔。
+ */
+export declare const resolveToolbarMenu: (toolbarConfig?: ToolbarConfig, menuSchema?: MenuItem[]) => ResolvedToolbarItem[];
+
+/**
+ * bridge 高频事件策略摘要。
+ *
+ * 原生侧可以根据 ready payload 或文档预期理解编辑器事件频率。
+ */
+export type BridgeEventTiming = {
+    contentChangeDebounceMs: number;
+    heightChangeThrottleMs: number;
+    commandStateChangeDedupe: boolean;
+};
+/**
+ * 原生侧初始化 WebView 编辑器时允许传入的配置子集。
+ *
+ * 只保留可序列化且跨端稳定的字段，避免把函数或宿主对象塞进 bridge。
+ */
+export type EditorInitOptions = Pick<RichTextEditorOptions, 'readonly' | 'platform' | 'toolbarMode' | 'placeholder' | 'maxLength' | 'codeBlockLanguagePanel'> & {
+    value?: Partial<EditorContent>;
+};
+/**
+ * 原生上传完成后回写给编辑器的成功结果。
+ */
+export type UploadResolvedPayload = {
+    assetId: string;
+    result: UploadResult;
+};
+/**
+ * 原生上传失败后回写给编辑器的错误摘要。
+ */
+export type UploadRejectedPayload = {
+    assetId: string;
+    message: string;
+};
+/**
+ * 编辑器请求原生侧选择或上传媒体文件时发送的 payload。
+ */
+export type UploadRequest = {
+    assetId: string;
+    type: 'image' | 'video';
+    accept: string;
+};
+/**
+ * 选区摘要只表达原生 toolbar 需要知道的最小状态。
+ */
+export type SelectionState = {
+    collapsed: boolean;
+};
+/**
+ * 原生侧完成参数面板后回传的结果。
+ *
+ * `requestId` 对应编辑器发出的 `editor.payloadPanelRequest.id`。
+ */
+export type PayloadPanelResolvedPayload = {
+    requestId: string;
+    values: PayloadPanelValues;
+};
+export type PayloadPanelCanceledPayload = {
+    requestId: string;
+};
+export type PayloadPanelRequestPayload = PayloadPanelOpenRequest & {
+    id: string;
+    readonly: boolean;
+};
+/**
+ * 编辑器 ready 后回传给原生侧的初始化结果。
+ */
+export type EditorReadyPayload = {
+    menuSchema: MenuItem[];
+    eventTiming: BridgeEventTiming;
+    version: string;
+};
+/**
+ * 原生侧发给编辑器的消息集合。
+ */
+export type NativeToEditorMessage = {
+    id: string;
+    type: 'editor.init';
+    payload: EditorInitOptions;
+} | {
+    id: string;
+    type: 'editor.executeCommand';
+    payload: EditorCommand;
+} | {
+    id: string;
+    type: 'editor.setContent';
+    payload: Partial<EditorContent>;
+} | {
+    id: string;
+    type: 'editor.setReadonly';
+    payload: {
+        readonly: boolean;
+    };
+} | {
+    id: string;
+    type: 'editor.requestContent';
+} | {
+    id: string;
+    type: 'editor.payloadPanelResolved';
+    payload: PayloadPanelResolvedPayload;
+} | {
+    id: string;
+    type: 'editor.payloadPanelCanceled';
+    payload: PayloadPanelCanceledPayload;
+} | {
+    id: string;
+    type: 'editor.uploadResolved';
+    payload: UploadResolvedPayload;
+} | {
+    id: string;
+    type: 'editor.uploadRejected';
+    payload: UploadRejectedPayload;
+};
+/**
+ * 编辑器发给原生侧的消息集合。
+ */
+export type EditorToNativeMessage = {
+    id?: string;
+    type: 'editor.ready';
+    payload: EditorReadyPayload;
+} | {
+    id?: string;
+    type: 'editor.content';
+    payload: EditorContent;
+} | {
+    id?: string;
+    type: 'editor.contentChange';
+    payload: EditorContentChange | EditorContent;
+} | {
+    id?: string;
+    type: 'editor.selectionChange';
+    payload: SelectionState;
+} | {
+    id?: string;
+    type: 'editor.commandStateChange';
+    payload: CommandState[];
+} | {
+    id?: string;
+    type: 'editor.payloadPanelRequest';
+    payload: PayloadPanelRequestPayload;
+} | {
+    id?: string;
+    type: 'editor.uploadRequest';
+    payload: UploadRequest;
+} | {
+    id?: string;
+    type: 'editor.heightChange';
+    payload: {
+        height: number;
+    };
+} | {
+    id?: string;
+    type: 'editor.error';
+    payload: EditorError;
+};
+export type BridgeMessage = NativeToEditorMessage | EditorToNativeMessage;
+
+/**
+ * bridge 高频事件的默认节流策略。
+ *
+ * 这里先固定协议默认值，真正的 WebView runtime 会在发送消息时使用这些数值。
+ */
+export declare const BRIDGE_CONTENT_CHANGE_DEBOUNCE_MS = 120;
+export declare const BRIDGE_HEIGHT_CHANGE_THROTTLE_MS = 100;
+export declare const defaultBridgeEventTiming: BridgeEventTiming;
+/**
+ * bridge 消息的已知类型守卫。
+ *
+ * 这里只校验消息外层类型，深层 payload 校验留给具体消息处理器。
+ * 这样能在轻量运行时判断和完整业务校验之间保持边界清楚。
+ */
+export declare function isBridgeMessage(value: unknown): value is BridgeMessage;
+
+export type RichTextToolbarIcons = RichTextEditorIcons;
+export type ToolbarDragState = {
+    startClientX: number;
+    startScrollLeft: number;
+    pointerType: string;
+    hasDragged: boolean;
+    startButton?: HTMLButtonElement;
+};
+export type RichTextToolbarPlacement = 'top' | 'bottom';
+export type RichTextToolbarOptions = {
+    editor: EditorAPI;
+    menuSchema?: MenuItem[];
+    toolbarConfig?: ToolbarConfig;
+    placement?: RichTextToolbarPlacement;
+    icons?: RichTextToolbarIcons;
+    menuLabels?: MenuLabelOverrides;
+    payloadPanelConfig?: PayloadPanelConfig;
+};
+export type RichTextToolbarAPI = {
+    update(): void;
+    destroy(): void;
+};
+
+/**
+ * 创建独立菜单实例。
+ *
+ * toolbar/tabbar 只订阅 EditorAPI 状态并派发命令，不接触编辑器内部 DOM 或 Lexical 实例。
+ */
+export declare function createRichTextToolbar(container: HTMLElement, options: RichTextToolbarOptions): RichTextToolbarAPI;
+
+export type RichTextFloatingPlacement = 'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end';
+export type RichTextFloatingLayerOptions = {
+    placement?: RichTextFloatingPlacement;
+    offset?: number;
+    shiftPadding?: number;
+    strategy?: 'absolute' | 'fixed';
+};
+export type RichTextFloatingLayer = {
+    update(): Promise<void>;
+    setOpen(open: boolean): void;
+    destroy(): void;
+};
+
+/**
+ * 统一浮层定位能力。
+ *
+ * hoverbar、mention 和 slash menu 都从这里复用定位、翻转、键盘可视区和边界避让逻辑。
+ */
+export declare function createFloatingLayer(reference: HTMLElement, floating: HTMLElement, options?: RichTextFloatingLayerOptions): RichTextFloatingLayer;
+
+/**
+ * 创建浏览器 DOM 编辑器实例。
+ * Lexical 只作为内部编辑器内核，public API 继续保持 BridgeRTE 的跨端契约。
+ */
+export declare function createRichTextEditor(container: HTMLElement, options?: RichTextEditorOptions): EditorAPI;
+
+export type WebViewBridgeMessageListener = (message: BridgeMessage) => void;
+export type WebViewBridgeRuntimeTransport = {
+    /**
+     * Runtime 通过这个函数把 EditorToNativeMessage 发给 RN/Flutter 外壳。
+     *
+     * DOM SDK 不直接依赖 ReactNativeWebView 或 Flutter channel，避免把具体宿主全局对象写进库。
+     */
+    postMessage(message: EditorToNativeMessage): void;
+    /**
+     * 宿主把 NativeToEditorMessage 转交给 runtime。
+     *
+     * 返回值负责解绑监听；如果宿主只想手动调用 `runtime.receive()`，可以不传这个函数。
+     */
+    addMessageListener?: (listener: WebViewBridgeMessageListener) => () => void;
+};
+export type WebViewBridgeRuntimeOptions = {
+    container: HTMLElement;
+    transport: WebViewBridgeRuntimeTransport;
+};
+export type WebViewBridgeRuntime = {
+    receive(message: NativeToEditorMessage | unknown): void;
+    destroy(): void;
+};
+export type PendingNativeUpload = {
+    type: 'image' | 'video';
+    assetId: string;
+} & ({
+    source: 'uploadAdapter';
+    resolve(result: UploadResult): void;
+    reject(error: Error): void;
+} | {
+    source: 'nativePicker';
+});
+export type PendingNativePayloadPanelRequest = {
+    request: PayloadPanelRequest;
+};
+export type NativeUploadResultMessage = {
+    type: 'editor.uploadResolved';
+    payload: UploadResolvedPayload;
+} | {
+    type: 'editor.uploadRejected';
+    payload: UploadRejectedPayload;
+};
+
+/**
+ * 创建 WebView bridge runtime。
+ *
+ * Runtime 只做协议适配：native 消息进来后调用 EditorAPI，编辑器事件再转成
+ * EditorToNativeMessage。它不暴露 Lexical、DOM 节点或上传文件对象，确保 RN/Flutter
+ * 只依赖稳定 bridge 协议。
+ */
+export declare const createWebViewBridgeRuntime: ({ container, transport }: WebViewBridgeRuntimeOptions) => WebViewBridgeRuntime;
+