mnote/rust/spikes/leptos-tiptap-spike

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：

{
  "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。

最小监听示例：

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 本地草稿逻辑为主，真正主链保存合同还没迁移完。