主编辑区改造准备

2026-04-21 06:26:35 +08:00
parent 1e686bfa3c
commit 5d1c94eb9e
49 changed files with 6730 additions and 2565 deletions
@@ -0,0 +1,118 @@
+# 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 本地草稿逻辑为主，真正主链保存合同还没迁移完。