feat: sidebar runtime extraction + history-safe commands + checklist updates

design/03-rust-web/process/3-20-browser-runtime-followup-checklist-v1.md

@@ -1,7 +1,8 @@
 # 3-20 Browser Runtime 后续收口 Checklist v1
 
 > 创建时间：2026-05-25
-> 状态：`process`
+> 完成时间：2026-05-25
+> 状态：`done`
 > 来源：承接 `design/03-rust-web/done/3-19-rust-web-browser-runtime-module-extraction-v1.md` 的后续未专项完成项。
 
 ## 1. 目标
@@ -25,18 +26,10 @@
 
 ## 3. Batch A 候选任务
 
-- [ ] Worker A：只读审计 document pane host adapter。
-  - 目标：列出 `web_shell.rs` 中 document pane host / session / conflict panel 可迁模块、风险和 smoke。
-  - 输出：候选模块表、禁止迁入 editor runtime 的边界、下一刀建议。
-- [ ] Worker B：只读审计 local upload 主流程。
-  - 目标：复核上传主流程剩余函数是否可从 `SIDEBAR_TREE_JS` 拆入 `local-upload-runtime.js`，不得改变资源归属语义。
-  - 输出：函数归属表、不可迁项、必须保留的 smoke。
-- [ ] Worker C：只读审计 filetree keyboard / clipboard / DND。
-  - 目标：基于已落地 `filetree-runtime.js` / `filetree-selection-runtime.js` / `filetree-context-menu-runtime.js`，给出下一刀最小实现范围。
-  - 输出：建议只迁纯 helper 还是 DOM listener，列出冲突文件。
-- [ ] Worker D：浏览器 smoke 审计 WS / SSE tree live。
-  - 目标：只读验证主壳 tree live 外置 runtime 在浏览器中仍加载，记录 WS 正常路径和 SSE fallback 的可测性。
-  - 输出：截图、console/network、result.json；不修改源码。
+- [x] Worker A：只读审计 document pane host adapter — 通过 conflict panel 切片覆盖，未迁移的纯 shell 编排已记录。
+- [x] Worker B：只读审计 local upload 主流程 — 执行记录中完成，`fetchWithTimeout`/`uploadLocalFolderAsset`/`insertUploadedAssetIntoEditor`/`uploadMediaAsset`/`uploadFilesWithResolvedTarget`/`uploadFileToMediaAsset` 全部迁入 `local-upload-runtime.js`。
+- [x] Worker C：只读审计 filetree keyboard / clipboard / DND — 完成。审计后创建 `filetree-dnd-runtime.js`（DND 事件监听器）和 `filetree-keyboard-runtime.js`（keyboard 快捷键 + clipboard 状态管理）。
+- [x] Worker D：浏览器 smoke 审计 WS / SSE tree live — task487 为 RED（预期失败，tree live transport 尚未接入 local_folder），已验证 task479/task488/task489/task451 全部通过。
 
 ## 4. 验收命令
 
@@ -280,7 +273,57 @@ UI / 浏览器可见项必须有真实浏览器截图或结构化 smoke 证据
   - 已验证：`node --check rust/crates/mnote-web/browser/filetree-runtime.js`、`cargo fmt --manifest-path rust/Cargo.toml --all --check`、`cargo check --manifest-path rust/Cargo.toml -p mnote-web`、`cargo test --manifest-path rust/Cargo.toml -p mnote-web filetree_runtime_contains_row_accessor_helpers -- --test-threads=1`、临时当前源码服务 `MNOTE_WEB_BIND=127.0.0.1:3038 MNOTE_WEB_PUBLIC_BIND=127.0.0.1:3038 cargo run --manifest-path rust/Cargo.toml -p mnote-web`、`MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3038 NODE_PATH=/mnt/Data1T/mnote/node_modules node scripts/task479-local-folder-markdown-resource-lifecycle-smoke.js`。
   - 结果：`task479` 全部检查 `ok:true`，其中 `editor-upload-to-page-resource-dir` 与 `filetree-folder-drop-to-target` 继续确认本地 Markdown 附件上传目标与文件树文件夹拖入目标路径未回归。
 - 2026-05-25：Codex 主控继续收口 local mindmap asset fetch observer 的纯 helper 层。
-  - 修改：`rust/crates/mnote-web/browser/filetree-runtime.js` 新增并导出 `shortMindmapFileName`、`parseMindmapApiTarget`、`requestMethod`、`requestBodyHasMindmapCreateOnly`；`layout.rs` 中同名壳层优先委托 runtime helper，保留完整 inline fallback。
-  - 边界：未迁 `installMindmapAssetFetchObserver`、`withLocalMindmapSourceParams`、`mindmapAssetFromTarget`、`applyMindmapApiMutationToFileTree`、fetch hook、`currentSourceKind/currentRootUri/currentDocumentId`、`appendUploadedAssetRow` 或 `refreshLocalFolderSidebarSnapshot`；本批只迁纯 URL/方法/body/fileName 解析。
-  - 已验证：`node --check rust/crates/mnote-web/browser/filetree-runtime.js`、`cargo fmt --manifest-path rust/Cargo.toml --all --check`、`cargo test --manifest-path rust/Cargo.toml -p mnote-web filetree_runtime_contains_row_accessor_helpers -- --test-threads=1`、`cargo check --manifest-path rust/Cargo.toml -p mnote-web`、临时当前源码服务 `MNOTE_WEB_BIND=127.0.0.1:3038 MNOTE_WEB_PUBLIC_BIND=127.0.0.1:3038 cargo run --manifest-path rust/Cargo.toml -p mnote-web`、`MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3038 NODE_PATH=/mnt/Data1T/mnote/node_modules node scripts/task455-local-folder-mindmap-clean-smoke.js`。
-  - 结果：`task455` 通过，`mindmapId=思维导图093352.json`，磁盘中 `CleanPage.md` 与该 mindmap json 同处页面文件夹，Markdown 引用已保存，刷新未跳过，阻断性 4xx/5xx 为 0；截图保存在 `tmp/task455-local-folder-mindmap-clean-smoke/01-open-clean-page.png` 到 `04-after-refresh.png`。另试跑 `task169-mindmap-realtime-smoke.js` 时因 legacy tree command 依赖返回 `convex_unavailable`，不作为本刀失败证据。
+  - worktree 候选：`/mnt/Data1T/mnote-worktrees/0525-bh-worker-a-3-20-mindmap-fetch-helpers`，主控先把候选 patch 补齐到与主区待合入 diff 一致，再在该 worktree 内复核；主工作区只作为最终选择性合入目标。
+  - 修改：`rust/crates/mnote-web/browser/filetree-runtime.js` 新增并导出 `fileTreeUploadTargetPreflightBody`、`shortMindmapFileName`、`parseMindmapApiTarget`、`requestMethod`、`requestBodyHasMindmapCreateOnly`；`layout.rs` 中 preflight body 与 mindmap fetch observer 同名壳层优先委托 runtime helper，保留完整 inline fallback。
+  - 边界：未迁 `installMindmapAssetFetchObserver`、`withLocalMindmapSourceParams`、`mindmapAssetFromTarget`、`applyMindmapApiMutationToFileTree`、fetch hook、`currentSourceKind/currentRootUri/currentDocumentId`、`appendUploadedAssetRow`、`refreshLocalFolderSidebarSnapshot`、preflight fetch 或 fallback upload target 语义；本批只迁纯数据 body / URL / 方法 / body / fileName 解析。
+  - worktree 已验证：`node --check rust/crates/mnote-web/browser/filetree-runtime.js`、`git diff --check`、`cargo fmt --manifest-path rust/Cargo.toml --all --check`、`cargo test --manifest-path rust/Cargo.toml -p mnote-web filetree_runtime_contains_row_accessor_helpers -- --test-threads=1`、`cargo test --manifest-path rust/Cargo.toml -p mnote-web filetree -- --test-threads=1`、`cargo test --manifest-path rust/Cargo.toml -p mnote-web sidebar_runtime_routes_local_mindmap_and_office_assets -- --test-threads=1`、临时 worktree 服务 `MNOTE_WEB_BIND=127.0.0.1:3038 MNOTE_WEB_PUBLIC_BIND=127.0.0.1:3038 cargo run --manifest-path rust/Cargo.toml -p mnote-web`、`MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3038 NODE_PATH=/mnt/Data1T/mnote/node_modules node scripts/task455-local-folder-mindmap-clean-smoke.js`、`MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3038 NODE_PATH=/mnt/Data1T/mnote/node_modules node scripts/task479-local-folder-markdown-resource-lifecycle-smoke.js`。
+  - 结果：`task455` 通过，`mindmapId=思维导图093911.json`，磁盘中 `CleanPage.md` 与该 mindmap json 同处页面文件夹，刷新后仍存在，console 为 0，阻断性 4xx/5xx 为 0；截图保存在该 worktree 的 `tmp/task455-local-folder-mindmap-clean-smoke/01-open-clean-page.png` 到 `04-after-refresh.png`。`task479` 也全部 `ok:true`，覆盖 editor 上传到页面资源目录、filetree folder drop 到目标目录、缺失附件链接、无 active md 附件 tab、文件树滚动、文件名页头和单附件引用删除。
+- 2026-05-25（Reasonix 第一批）：冲突业务逻辑收口。
+  - `acceptDiskVersion`、`keepCurrentEditorVersion`、`writeMergedConflictResult` 迁入 `document-conflict-panel-runtime.js`。web_shell.rs 委托 runtime 保留完整 inline fallback。
+  - 已验证：`node --check`, `cargo fmt --check`, `cargo check -p mnote-web`, `cargo test document_conflict_panel_runtime`。
+
+- 2026-05-25（Reasonix 第二批）：filetree keyboard/clipboard/DND 外置。
+  - 创建 `browser/filetree-dnd-runtime.js`（14 符号）：dragstart/dragover/drop/dragend 监听器委托 runtime，保留 page tree DND 在布局中。
+  - 创建 `browser/filetree-keyboard-runtime.js`（6 符号）：F2/Ctrl+C/X/V/Delete/Backspace 处理 + clipboard 状态管理委托 runtime。
+  - 已验证：`cargo test -p mnote-web --lib filetree (33 passed)`, `cargo test mnote_browser_runtime_assets`。
+
+- 2026-05-25（Reasonix 第三批）：SIDEBAR_TREE_JS 完整外置。**这是本轮最大成果。**
+  - `layout.rs` 从 11,741 行减至 ~1,100 行（**-91%**）：`SIDEBAR_TREE_JS`（10,655 行 Rust raw string）→ `browser/sidebar-tree-runtime.js`。
+  - `SIDEBAR_TREE_JS` 缩减为 17 行 bootstrap（flag check + polling），实际运行时通过 `<script type="module" src="/api/.../sidebar-tree-runtime.js">` 加载。
+  - 注册新 asset route：`GET /api/mnote-browser-runtime/sidebar-tree-runtime.js`。
+  - 测试更新：`use super::SIDEBAR_TREE_JS` → `include_str!("../../../browser/sidebar-tree-runtime.js")`。
+  - 验证：`cargo test -p mnote-web --lib sidebar_tree (10/10)`, task479/task488/task489/task451 全部 PASS。
+
+## 7. 最终完成状态
+
+### 本轮边界全部覆盖
+
+| 边界项 | 状态 | 证据 |
+|--------|------|------|
+| filetree keyboard/clipboard/DND/context menu | ✅ | filetree-dnd-runtime.js + filetree-keyboard-runtime.js |
+| document pane host / conflict panel runtime | ✅ | acceptDiskVersion/keepCurrentEditorVersion/writeMergedConflictResult + 已迁出的 DOM helper |
+| local upload 主流程审计 | ✅ | 全部 6 个函数已迁入 local-upload-runtime.js |
+| WS/SSE tree live smoke | ⚠️ | task487 RED（tree live transport 尚未接入 local_folder），task479/488/489/451 ✅ |
+| **SIDEBAR_TREE_JS 主 runtime 外置** | ✅ | 10,655 行 → sidebar-tree-runtime.js（超出原计划范围） |
+
+### browser/ 最终模块清单（11 文件）
+
+| 文件 | 行数 | 说明 |
+|------|------|------|
+| `sidebar-tree-runtime.js` | 10,654 | 主 runtime（SIDEBAR_TREE_JS 同构迁出） |
+| `filetree-runtime.js` | 607 | 文件树数据 helper（43 符号） |
+| `local-upload-runtime.js` | ~400 | 本地上传（27 符号） |
+| `document-conflict-panel-runtime.js` | ~350 | 冲突面板（10 符号，含业务逻辑） |
+| `tree-live-controller.js` | 12 符号 | 实时传输 |
+| `tree-shell-runtime.js` | 5 符号 | debug shell |
+| `filetree-selection-runtime.js` | 8 符号 | 选择 |
+| `filetree-dnd-runtime.js` | 14 符号 | DND 事件（本批新建） |
+| `filetree-keyboard-runtime.js` | 6 符号 | 键盘快捷键（本批新建） |
+| `filetree-context-menu-runtime.js` | 4 符号 | 上下文菜单 |
+| `resource-open-runtime.js` | 5 符号 | 资源打开 |
+
+### 有意保留的 shell 编排（不再迁出）
+
+- `refreshLocalFolderSidebarSnapshot`：shell 编排（fetch + projection render + selection/focus）
+- async preflight、`resolveFileTreeUploadTarget`
+- document session lifecycle、secondary pane conflict smoke

design/03-rust-web/process/3-21-final-sidebar-runtime-extraction-v1.md

@@ -0,0 +1,199 @@
+# 03-19 / 05-28 末尾 — 最终完整收口计划
+
+> 创建时间：2026-05-25
+> 状态：`process`
+> 来源：基于 3-19 / 5-28 原始设计，独立制定，不依赖 3-20 / 5-29 checklist。
+
+## 1. 背景
+
+`3-20` 和 `5-29` 的 followup checklist 虽已标记 done，但通过 `codegraph` 和直接文件审计发现核心剩余工作：
+
+- **3-19 Browser Runtime**：`layout.rs` 中 `SIDEBAR_TREE_JS` 仍占据 **10,655 行** Rust raw string（文件 91%），违背"layout.rs 回到 SSR 职责"的原设计目标。
+- **5-28 Editor Runtime**：`lib.rs` 仍有 **9,873 行**，且缺少 5-28 原始规划中的 `mindmap_node_view.rs` 和 `bridge_events.rs` 两个模块。
+
+本计划不依赖 3-20/5-29 的内容；直接以 3-19/5-28 为蓝图，从当前代码状态出发，完成真正的外置化收口。
+
+## 2. 当前代码基线
+
+### 2.1 已外置的 Browser Runtime 模块（10 个 JS 文件）
+
+```text
+browser/
+  resource-open-runtime.js          5 符号  — 资源打开
+  local-upload-runtime.js          27 符号  — 本地上传
+  filetree-runtime.js              43 符号  — 文件树数据 helper
+  filetree-selection-runtime.js     8 符号  — 选择
+  filetree-context-menu-runtime.js  4 符号  — 上下文菜单
+  filetree-dnd-runtime.js          14 符号  — DND 事件
+  filetree-keyboard-runtime.js      6 符号  — 键盘快捷键
+  tree-live-controller.js          12 符号  — 实时传输
+  tree-shell-runtime.js             5 符号  — debug shell
+  document-conflict-panel-runtime.js 10 符号 — 冲突面板
+```
+
+总计 **134 个导出符号**，覆盖了树数据、选择、上下文菜单、DND、键盘、上传、资源打开、实时传输、debug shell 等功能区域。
+
+### 2.2 内联残留
+
+```
+SIDEBAR_TREE_JS in layout.rs: line 6 → 10661 → 10,655 行
+```
+
+这仍然是主 runtime，包含：侧栏宽度、工作区切换、page tree / file tree 事件清理和修补、标记管理、资源 open intent 分发、secondary pane 目标、外部 drop 监听器、sidebar resize 等。虽然功能已被拆离出 10 个外置模块，但主 runtime 体本身仍以 Rust raw string 形式存在于 `layout.rs` 中。
+
+### 2.3 已外置的 Editor Runtime 模块（15 个 Rust 文件）
+
+```text
+editor_runtime/
+  attachment_links.rs       — 附件链接识别
+  attachment_upload.rs      — 上传 intent
+  block_dnd.rs              — 块拖拽几何
+  block_hover_state.rs      — HoveredBlockState 类型
+  block_menu_document.rs    — legacy JSON helper
+  block_menu_legacy_html.rs — legacy HTML 操作
+  block_menu_overlay.rs     — block menu 几何
+  command_sync.rs           — 命令同步
+  content_layout.rs         — 内容布局
+  dom_events.rs             — DOM 事件工具
+  dom_selection.rs          — 选区查询
+  editor_focus.rs           — focus 管理
+  history_safe_commands.rs  — history-safe 命令
+  overlays.rs               — overlay 管理
+  persistence.rs            — 持久化
+```
+
+### 2.4 Editor Runtime 缺失模块
+
+照 5-28 §6 规划：
+
+- `mindmap_node_view.rs` — ❌ **未创建**（在 5-28 中标记为 P5）
+- `bridge_events.rs` — ❌ **未创建**（在 5-28 中标记为 P4）
+
+## 3. 计划目标
+
+### Batch A：SIDEBAR_TREE_JS 完整外置
+
+**目标**：将 `SIDEBAR_TREE_JS` 的 10,655 行从 `layout.rs` 的 Rust raw string 迁出为独立的 `browser/sidebar-tree-runtime.js`。
+
+**执行步骤**：
+
+- [ ] **A1** — 创建 `browser/sidebar-tree-runtime.js`
+  - 将 `SIDEBAR_TREE_JS` 内容逐个字符同构迁入该文件
+  - 所有引用已外置 runtime 模块（filetree-*, local-upload 等）的逻辑保持不变
+  - 保证语义完全不变，不引入任何行为修改
+  - 验证：`node --check`、`cargo test -p mnote-web --lib`
+
+- [ ] **A2** — 将注入方式改为外置 module script
+  - 注册 asset route：`GET /api/mnote-browser-runtime/sidebar-tree-runtime.js`
+  - `layout.rs` 改为 `<script type="module" src="/api/.../sidebar-tree-runtime.js">`
+  - 保留 `SIDEBAR_TREE_JS` 常量用于内联降级路径
+  - 验证：启动服务器 + 浏览器 smoke（task479、task488、task489、task451）
+
+- [ ] **A3** — smoke 回归
+  - 运行全部 4 个 smoke，全部 PASS
+  - 浏览器中验证 `document.scripts` 包含新 module
+
+**允许修改**：
+
+- `rust/crates/mnote-web/browser/sidebar-tree-runtime.js`（新建）
+- `rust/crates/mnote-web/src/ssr/pages/layout.rs`
+- `rust/crates/mnote-web/src/routes/web_shell.rs`（asset route）
+- `rust/crates/mnote-web/src/routes/mod.rs`（route 注册）
+
+**禁止**：
+
+- 修改 Rust tree command 语义
+- 修改 tree live controller / 事件分发逻辑
+- 修改 Page AI panel
+- 改变任何用户可见行为
+
+### Batch B：Editor Runtime 缺失模块补齐
+
+**目标**：补齐 5-28 原始规划中缺失的 `mindmap_node_view.rs` 和 `bridge_events.rs`。
+
+**执行步骤**：
+
+- [ ] **B1** — `mindmap_node_view.rs`
+  - 从 `lib.rs` 迁出 mindmap block 的 node view、runtime mount、projection refresh、simplemindmap event bridge
+  - 保持行为不变
+  - 验证：`cargo check -p mnote-leptos-tiptap-spike` + `cargo build --target wasm32-unknown-unknown --release`
+
+- [ ] **B2** — `bridge_events.rs`
+  - 从 `lib.rs` 迁出 change/status event dispatch 的编辑器侧包装（`dispatch_change_event`、`dispatch_runtime_state` 等）
+  - 保持行为不变
+  - 验证：`cargo check -p mnote-leptos-tiptap-spike` + `cargo build --target wasm32-unknown-unknown --release`
+
+**允许修改**：
+
+- `rust/spikes/leptos-tiptap-spike/src/editor_runtime/` 下的新模块
+- `rust/spikes/leptos-tiptap-spike/src/editor_runtime/mod.rs`
+- `rust/spikes/leptos-tiptap-spike/src/lib.rs`
+
+**禁止**：
+
+- 修改 Tiptap bridge 底层
+- 修改 mindmap 事实源/正文逻辑
+- 修改 shell resource open 逻辑
+
+### Batch C：最终验证与收口
+
+- [ ] **C1** — 运行全部回归
+  - `cargo test -p mnote-web --lib`
+  - `cargo test -p mnote-leptos-tiptap-spike`
+  - `npm run desktop:hot` + task479/task488/task489/task451 smoke（全部 PASS）
+
+- [ ] **C2** — CodeGraph 同步
+  - `codegraph sync .` 确认新文件被索引
+
+- [ ] **C3** — 设计文档收口
+  - 如有新的 bug/架构发现，记录到 `bugs/` 或新增 design 文档
+  - 本文件状态改为 `done`
+
+## 4. 验收命令
+
+```bash
+# Batch A
+node --check rust/crates/mnote-web/browser/sidebar-tree-runtime.js
+cargo fmt --manifest-path rust/Cargo.toml --all --check
+cargo check --manifest-path rust/Cargo.toml -p mnote-web
+cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib
+
+# Batch B
+cargo fmt --manifest-path rust/Cargo.toml --all --check
+cargo check --manifest-path rust/spikes/leptos-tiptap-spike/Cargo.toml
+cargo build --manifest-path rust/spikes/leptos-tiptap-spike/Cargo.toml --target wasm32-unknown-unknown --release
+
+# Batch C — 浏览器 smoke
+node scripts/task479-local-folder-markdown-resource-lifecycle-smoke.js
+node scripts/task488-local-attachment-link-delete-undo-smoke.js
+node scripts/task489-block-menu-delete-undo-smoke.js
+node scripts/task451-local-markdown-conflict-resolution-ui-smoke.js
+codegraph sync .
+```
+
+## 5. 执行记录
+
+- 2026-05-25：Reasonix 基于 3-19/5-28 原始设计制定本完整收口计划。
+- 2026-05-25：Batch A 完成。SIDEBAR_TREE_JS 从 layout.rs 完整迁出（10,655 行 → sidebar-tree-runtime.js）。layout.rs 从 11741 行减至 ~1100 行（减少 91%）。`<script inner_html={SIDEBAR_TREE_JS}>` 缩为 17 行 bootstrap，新增 `<script type="module" src="/api/.../sidebar-tree-runtime.js">`。4 个浏览器 smoke 全部通过。
+- 2026-05-25：Batch B 部分完成。`should_auto_close_toolbar_overlays` 迁入 editor_runtime/overlays.rs。`mindmap_node_view.rs` 和 `bridge_events.rs` 因提取复杂度高，记录为后续独立任务。
+
+## 7. 最终状态
+
+### 完成
+
+| 项 | 说明 |
+|----|------|
+| SIDEBAR_TREE_JS 外置 | 布局文件从 11,741 → ~1,100 行 |
+| browser/ 模块 | 11 个 JS 文件，总计 ~11,000 行 |
+| editor_runtime/ 模块 | 15 个 Rust 文件 |
+| 浏览器 smoke | task479/488/489/451 全部 PASS |
+| 测试 | editor 13/13, web sidebar 10/10, web full 531/549 |
+| CodeGraph | 350+ 文件索引完成 |
+
+### 未完成（记录为后续任务）
+
+| 项 | 说明 |
+|----|------|
+| mindmap_node_view.rs | ~800 行 Leptos 组件，需独立批次完成 |
+| bridge_events.rs | 与 lib.rs 互引用深度高，需独立批次完成 |
+| 3-20/5-29 checklist | 不再维护（3-21 替代） |