119 lines
3.6 KiB
Markdown
119 lines
3.6 KiB
Markdown
# 8123 leptos-tiptap runtime bridge
|
||
|
||
这是 `rust/spikes/leptos-tiptap-spike` 的宿主桥接说明，面向前端 host / QA。
|
||
|
||
## runtime 识别
|
||
|
||
宿主可用下面特征识别这套 runtime：
|
||
|
||
- `data-mnote-runtime="8123-leptos-tiptap-runtime"`
|
||
- `data-mnote-runtime-bridge="true"`
|
||
- `data-testid="mnote-leptos-tiptap-host"`
|
||
|
||
稳定锚点：
|
||
|
||
- root: `data-testid="mnote-leptos-tiptap-host"`
|
||
- stage: `#editor-stage` / `data-testid="mnote-leptos-tiptap-editor-stage"`
|
||
- editor root: `.editor-surface .ProseMirror` / `data-testid="mnote-leptos-tiptap-editor-root"`
|
||
- toolbar: `data-testid="mnote-leptos-tiptap-toolbar"`
|
||
- slash menu: `data-testid="mnote-leptos-tiptap-slash-menu"`
|
||
- handle: `data-testid="mnote-leptos-tiptap-handle"`
|
||
|
||
## 事件协议
|
||
|
||
所有事件都走同一 envelope：
|
||
|
||
```json
|
||
{
|
||
"protocol": "mnote.leptos_tiptap.bridge.v1",
|
||
"runtime": "8123-leptos-tiptap-runtime",
|
||
"version": "1.0.0",
|
||
"source": "mnote:leptos-tiptap-spike",
|
||
"payload": {}
|
||
}
|
||
```
|
||
|
||
### `mnote:leptos-tiptap-spike:ready`
|
||
|
||
首次挂载完成时发送，告诉 host 这套 runtime 可以被嵌入。
|
||
|
||
payload 里至少包含：
|
||
|
||
- `runtime_name`
|
||
- `selectors`
|
||
- `supported_commands`
|
||
- `supports_embedded_mode`
|
||
|
||
### `mnote:leptos-tiptap-spike:state`
|
||
|
||
发送当前最小可观测状态。
|
||
|
||
payload 字段：
|
||
|
||
- `document_id`
|
||
- `title`
|
||
- `dirty_count`
|
||
- `selected_block_index`
|
||
- `editor_focused`
|
||
- `slash_open`
|
||
- `toolbar_open`
|
||
|
||
### `mnote:leptos-tiptap-spike:change`
|
||
|
||
内容变化时发送结构化文档快照。
|
||
|
||
payload 结构：
|
||
|
||
- `title`: 文档标题
|
||
- `content`: 当前文档 JSON
|
||
- `meta`: 附加运行态信息（如 dirty_count / selection / focus）
|
||
|
||
### `mnote:leptos-tiptap-spike:save-request`
|
||
|
||
保存路径或 host 明确要求落盘时发送，payload 与 `change` 一致，但语义是“请宿主处理保存”。
|
||
|
||
### `mnote:leptos-tiptap-spike:command`
|
||
|
||
预留宿主到 runtime 的命令通道。当前 spike 只声明了最小命令集合，还没有把完整命令分发做成正式 host API。
|
||
|
||
## 选择器清单
|
||
|
||
建议 host/QA 只依赖这些稳定选择器：
|
||
|
||
- root: `[data-testid="mnote-leptos-tiptap-host"]`
|
||
- stage: `#editor-stage` 或 `[data-testid="mnote-leptos-tiptap-editor-stage"]`
|
||
- editor: `.editor-surface .ProseMirror` 或 `[data-testid="mnote-leptos-tiptap-editor-root"]`
|
||
- toolbar: `[data-testid="mnote-leptos-tiptap-toolbar"]`
|
||
- slash menu: `[data-testid="mnote-leptos-tiptap-slash-menu"]`
|
||
- handle: `[data-testid="mnote-leptos-tiptap-handle"]`
|
||
|
||
## 推荐嵌入方式
|
||
|
||
推荐把这套 runtime 作为 iframe 或独立容器挂载，然后由 host 监听 `document` 上的 `CustomEvent`：
|
||
|
||
1. 先等待 `ready`。
|
||
2. 从 `ready.payload.selectors` 取稳定锚点。
|
||
3. 监听 `change` / `state` / `save-request`。
|
||
4. 需要操作时再发 `command`。
|
||
|
||
最小监听示例：
|
||
|
||
```ts
|
||
const onReady = (event: Event) => {
|
||
const detail = (event as CustomEvent).detail;
|
||
// detail.protocol / detail.payload.selectors
|
||
};
|
||
|
||
document.addEventListener('mnote:leptos-tiptap-spike:ready', onReady as EventListener);
|
||
document.addEventListener('mnote:leptos-tiptap-spike:change', onReady as EventListener);
|
||
document.addEventListener('mnote:leptos-tiptap-spike:state', onReady as EventListener);
|
||
document.addEventListener('mnote:leptos-tiptap-spike:save-request', onReady as EventListener);
|
||
```
|
||
|
||
## 已知限制
|
||
|
||
- 这仍是 8123 spike，不是正式主编辑器切流完成态。
|
||
- 目前桥接只保证稳定事件与稳定 selector，不保证 host 命令已经全量实现。
|
||
- 仍保留独立运行能力，host 不应依赖 debug 文案。
|
||
- 保存仍以 spike 本地草稿逻辑为主，真正主链保存合同还没迁移完。
|