mnote/rust/spikes/leptos-tiptap-spike/README.md

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