docs: codify fallback retirement direction

2026-05-10 08:46:43 +08:00
parent b7ceb7afae
commit 2f9ef85350
16 changed files with 616 additions and 63 deletions
@@ -57,7 +57,7 @@
  - `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/editor-host.tsx`
 - 但仍保留 TS converter、fallback host、兼容保存链与部分 host/runtime 过渡层
  - `/mnt/Data1T/mnote/wolai-frontend/src/lib/documents/tiptap-content-converter.ts`
-  - `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocknote-editor.tsx`
+  - `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/blocknote-editor.tsx`

 这条线的问题不是“代码不能运行”，而是：

@@ -397,27 +397,27 @@
 目标：

 - 正式把默认主编辑器从 `BlockNote` 切到页面内 `leptos-tiptap` island
- 让 `BlockNote` 退到显式 fallback / 兼容链，而不是继续承担默认主链
+- 让 `BlockNote` 退出运行时主路径，只保留 `recycle/` 历史参考副本，而不是继续承担默认主链
 - 让默认主链不再依赖 `iframe runtime` 或 React `bridge runtime`

 清单：

- [x] 收敛正式 host 命名：`leptos_tiptap_runtime` 改为“正式 island host”语义，`leptos_tiptap_inline` 仅保留为兼容别名，`leptos_tiptap_iframe_debug` 继续只保留给调试桥
+- [x] 收敛正式 host 命名：`leptos_tiptap_runtime` 改为“正式 island host”语义，`leptos_tiptap_inline` 仅保留为兼容别名；历史 `leptos_tiptap_iframe_debug` 已退出文档页 host 选择面，仅剩源码参考实现
 - [x] 修改 `DocumentContent`、`page.tsx`、`runtime-config.ts` 的默认分发逻辑，使不带任何参数的 `/documents/[id]` 直接进入正式 `leptos-tiptap` island 主链
 - [x] 删除默认主链对 `loadLeptosTiptapRuntime()` / `bridge.create()` / `bridge.document()` / `bridge.command()` 这种 React 控制面的依赖
- [x] 保留 `blocknote` 显式回退开关：可以是 runtime config、query 参数或受控 feature flag，但必须做到“不改代码即可回退”
- [x] 把 `BlockNoteEditor` 降为 fallback / 对照链，不再继续承接新的长期 editor truth、save contract、AI contract 语义
+- [x] 历史 `blocknote` 显式回退链已退到 `recycle/`，不再作为当前 runtime config、query 参数或 feature flag 组成部分
+- [x] 把 `BlockNoteEditor` 降为 `recycle/` 历史参考实现，不再继续承接新的长期 editor truth、save contract、AI contract 语义
 - [x] 为默认切流补齐真实 smoke：打开、输入、撤销、重做、引用插入、AI 改写、保存、刷新回填、异常回退
 - [x] 为默认切流补齐观测项：runtime 加载失败、hydration 失败、Rust command 失败、保存失败、自动回退次数
 - [x] 先完成开发环境默认切流，再进入受控范围的真实使用默认切流；每一步都保留 kill switch
- [x] 更新设计稿、运行时注释与口径，明确“默认主编辑器已切到页面内 `leptos-tiptap` island，`BlockNote` 为 fallback/兼容链”
+- [x] 更新设计稿、运行时注释与口径，明确“默认主编辑器已切到页面内 `leptos-tiptap` island，`BlockNote` 仅保留 `recycle/` 历史参考副本”

 ### 6.5.1 当前验证记录（2026-04-21，2026-04-29 复核）

 - [x] `http://127.0.0.1:3000/documents/[id]` 在不带 `editorHost` 参数时默认进入页面内 `leptos_tiptap` island，而不是 `iframe` 或 React `bridge runtime`
 - [x] 侧边栏“新建页面”不再依赖 `edit=1`；当前 3000 Rust Web 侧栏 `+` 会通过 `/api/tree/commands` 新建页面并直接进入默认 `leptos-tiptap` 主链，`task122` 已覆盖
- [ ] `node /mnt/Data1T/mnote/scripts/task108-document-default-editor-cutover-smoke.js` 已通过
- [ ] `editorHost=blocknote` 显式回退在当前 3000 Rust Web shell 下尚未通过 `task108`；旧 Next/React fallback 只能作为 legacy/对照链，不能作为当前 3000 完成证据
+- [x] `task108-document-default-editor-cutover-smoke.js` 已移入 `recycle/scripts/`，不再作为当前 3000 主链验收项
+- [x] `editorHost=blocknote` 显式回退已退出当前 3000 Rust Web shell 的活跃验收范围；旧 Next/React fallback 只保留历史参考意义
 - [x] `DocumentContent` 已暴露主链观测点：`runtime_load_failed`、`host_init_failed`、`command_failed`、`save_failed`、`fallback_count`
 - [x] 已修正 island `embedded` 模式判定，不再因为缺少 `?embedded=1` 而把 spike 页面壳误渲染进 3000 正式文档页
 - [x] 已移除正式主链中的 spike 开发态壳元素：`hero`、重复标题、开发态提示文案、调试抽屉不再出现在 `/documents/[id]` 默认视图
@@ -427,7 +427,7 @@
 - [x] 已修正正式主链中的本地草稿隔离：Rust island 不再使用全局单一 `localStorage` key，改为按 `workspaceId/documentId` 分桶
 - [x] 已修正正式主链中的布局偏移：页面内 island 宿主不再额外施加横向 padding，编辑正文列、块手柄和 drop indicator 已回到同一几何基准
 - [x] 已收敛切页期的 disposed signal 访问风险：窗口级 `mousemove/mouseup/keydown` listener 已改为 `try_get_untracked/try_set` 安全访问，避免在页面切换时继续触碰已释放 reactive value
- [ ] `task108` 当前仍未通过；2026-04-29 复核失败在 `?editorHost=blocknote` 后未出现 `data-editor-host-active="blocknote"`，因此不能把 blocknote fallback 计入当前 3000 Rust shell 完成项
+- [x] `task108` 已随 `BlockNote` fallback 退场移入 `recycle/`；不再用 blocknote fallback 证明当前 3000 Rust shell 完成度
 - [x] `task121` / `task122` 已覆盖当前 3000 默认 island 的 hydrate、输入、保存、reload 读回和 UI 新建页面进入主链
 - [ ] 当前 `slash / floating toolbar / drag handle / turn into` 仍是 island 内部的最小自制实现，尚未对齐官方 notion-like 模板的组件层级、视觉细节与菜单能力

@@ -440,9 +440,9 @@
 退出标准：

 - 不带参数的 `/documents/[id]` 默认进入 `leptos-tiptap`
- 出现问题时可通过显式开关快速回退到 `BlockNote`，而不是回滚代码
+- 出现问题时优先修正式 `leptos-tiptap` 主链，不再把回退到 `BlockNote` 作为默认策略
 - 默认链路下的 Rust truth、AI contract、save contract 保持不变
- `BlockNote` 不再是默认主编辑器，但仍保留为迁移期保险丝
+- `BlockNote` 不再是默认主编辑器，也不再是当前运行时保险丝；仅保留 `recycle/` 参考副本

 ---

@@ -34,7 +34,7 @@

 它现在更接近于：

-> **`Rust snapshot 优先 + Convex-backed + 前端 fallback / 本地 state 仍存在` 的混合态。**
+> **`Rust snapshot 主读链 + Convex-backed + 前端本地 state 仍存在` 的混合态。**

 因此，当前看到的这些“小问题”：

@@ -60,7 +60,7 @@

 但以下事实仍然成立：

- 读取主链虽已优先消费 Rust `mnote.page_aggregate.v1` snapshot，但 snapshot 不可用时仍保留 TS fallback
+- 读取主链已固定为 Rust `mnote.page_aggregate.v1` snapshot，不再通过 TS builder 兜底
 - 标题、正文、页面设置虽已开始收口到同一组 page aggregate command family，但 projection 回流与运行时语义还没完全闭环
 - 页面树 / 文件树与页头标题的一致性已明显改善，但页头标题、页面设置与编辑器 runtime 还没有完全共享同一份聚合真相
 - `pageOptions` 已部分进入 `leptos-tiptap` 运行时语义层，但还没有整体收口完成
@@ -109,10 +109,9 @@

 ## 3.1 当前页面数据并不是一个统一聚合

-当前文档页读取主链已经优先走 Rust `mnote.page_aggregate.v1` 快照，再在 snapshot 不可用或不可信时回退到 TS builder：
+当前文档页读取主链已经固定走 Rust `mnote.page_aggregate.v1` 快照：

 - Rust `/api/page-aggregate/:id` snapshot
- TS fallback builder
 - 页面本地 aggregate state reducer
 - preferred sidebar snapshot / 页头标题补偿链

@@ -35,7 +35,7 @@
 - 功能以“高频路径可用、复杂能力可降级”为原则。
 - 当前项目保留“文件树 / Explorer”创新，不要求删除。
 - 默认主编辑器继续是页面内 `leptos-tiptap` island。
- `BlockNote` 只作为 fallback / 对照链，不重新变成默认方向。
+- `BlockNote` 只作为 `recycle/` 历史参考 / 对照材料，不重新变成默认方向。
 - 树、页面结构、标题、正文、页面设置不能在 UI 层再拼第二份真相。

 这份文档应放在 `05-editor-mainline/process`，因为它的核心不是 Rust Web 壳复刻，也不是单独的树命令合同，而是：
@@ -384,8 +384,8 @@ Wolai / Notion-like 目标：

 当前仓库已有可复用参考：

- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocknote-editor.tsx` 中，旧 `BlockNoteView` 通过 `SideMenuController` 注入自定义 `CustomSideMenu`。
- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/menus/CustomSideMenu.tsx` 中，`WolaiDragHandleWithInsert` 已实现上方插入、下方插入、手柄菜单、菜单冻结、空段落加号打开 slash、截图失焦状态重置。
+- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/blocknote-editor.tsx` 中，旧 `BlockNoteView` 通过 `SideMenuController` 注入自定义 `CustomSideMenu`。
+- `/mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/menus/CustomSideMenu.tsx` 中，`WolaiDragHandleWithInsert` 已实现上方插入、下方插入、手柄菜单、菜单冻结、空段落加号打开 slash、截图失焦状态重置。
 - `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/leptos-tiptap-inline-editor-host.tsx` 当前已有较简化的块手柄和菜单，但没有复刻上 / 下短横线插入态。
 - `/mnt/Data1T/mnote/rust/spikes/leptos-tiptap-spike/src/lib.rs` 已有 leptos/tiptap 手柄雏形，但当前样式偏重，并且 `insert_top_level_paragraph_after_html` 只支持 after 插入。