docs: align runtime architecture guidance

ARCHITECTURE.md

@@ -1,10 +1,12 @@
 # MNOTE 当前架构梳理
 
-> 更新时间：2026-05-22
+> 更新时间：2026-05-26
 >
 > 2026-05-22 口径更新：产品形态已切换为 local-first workspace，且初步 MVP 已建立；本地文件夹是默认数据真相，Rust SQLite control-plane 承接 auth、membership、share grants、sync state、AI policy、ACP/Hermes runtime session 等默认控制面。Convex 仅保留为历史迁移源、显式 cloud source / compat / sync replica 边界；根 `convex/` functions 源码已软删除到 `recycle/20260522-convex-runtime-retirement/convex/`，不再作为 active deploy source。相关设计已完成并迁入 `design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md` 与 `design/02-convex-rust-long-term-architecture/done/2-8-convex-replace-with-rust-sqlite-control-plane-v1.md`。本地 Markdown 图片与附件上传已新增 `/api/local-folder/assets/upload`，页面内上传默认写入 `{mdBase}.assets/` 并保存相对 Markdown 路径，不再走 Convex media asset。
 >
 > **当前阶段：local-first MVP 后阶段。** 3000 下文档页、Sidebar/File Tree/Page Tree 三层树模型、tree command（`tree.*` preferred）、tree realtime WS 主链 / SSE fallback、本地 Markdown 上传、上传下载、AI 会话本地化与 VSCode-like agent 运行口径均已建立。剩余工作集中在 `WorkspacePath/ObjectIdentity` runtime 消费统一、`DocumentBuffer/BufferStore`、Page Aggregate compat 瘦身、tree command context、live cache 统一、VSCode-like 冲突合并 UI、agent diff 审计、本地索引 / 分享 / 同步闭环，而不是继续扩张专用 page-ai fast-path 或 Convex 主存储链。
+>
+> 2026-05-26 口径更新：前端 runtime 大块已完成模块级拆分。`layout.rs` / `tree.rs` / `web_shell.rs` 不再是浏览器 JS 功能的主要符号定位入口；Sidebar、FileTree、document adapter、tree shell 等 runtime 入口位于 `rust/crates/mnote-web/browser/*.js`，tiptap island 入口位于 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs`。CodeGraph 可直接索引这些 JS / Rust 模块；当前 smoke 分类见 `scripts/TESTING_REFERENCE.md`。
 
 本文只描述当前仓库中真实成立的主线结构，以及当前最优先的架构收口点。
 
@@ -23,7 +25,7 @@
 3. `mnote-web` 是当前 Rust Web 主执行面，负责 3000 gateway、server-first shell、query / command / projection / transport 与 realtime stream；Next App Router 已降为 legacy compat / island bundle source，不再是当前主入口
 4. 文档页默认主编辑器已切到页面内 `leptos-tiptap` island
 5. `BlockNote` 已退出文档页默认主路径，仅作为历史参考实现 / 对照材料保留
-6. 页面 AI 当前最合理的长期形态是：MNote 只负责页面定位、白名单目录权限、agent runtime 管理、文件变更同步；Hermes / Reasonix 直接在授权工作区内编辑本地文件。`page_ai_workflow` 只保留为 debug / 历史兼容门面，`mnote.doc.markdown_edit` 不再作为 local-first 默认、fallback 或 remote fallback；`mnote.block.*` 只保留为复杂结构辅助层
+6. 页面 AI 当前最合理的长期形态是：MNote 只负责页面定位、白名单目录权限、agent runtime 管理、文件变更同步；Hermes / Reasonix 直接在授权工作区内编辑本地文件。`page_ai_workflow` 只保留为 debug / 历史兼容门面，`mnote.doc.markdown_edit` 不作为 local-first 默认正文编辑入口，只在显式 cloud / remote / compat 且无法直接授权文件访问的边界中作为受控 fallback；`mnote.block.*` 只保留为复杂结构辅助层
 
 一句话收口：
 
@@ -78,8 +80,20 @@
 当前 Sidebar/工作区壳的当前实现在 Rust mnote-web SSR：
 - 工作区壳渲染入口：`gateway.rs`（`root_entry`）
 - 文档页壳/文档面板：`web_shell.rs`（`document_page_shell`、`build_document_panes_bootstrap_json`）
-- Sidebar tree stream 消费：`layout.rs` 嵌入 JS（`startWithSse` / `startWithWebSocket`）
-- FileTree 渲染与交互：`tree.rs` 嵌入 JS
+- Sidebar / FileTree / tree live runtime：`rust/crates/mnote-web/browser/sidebar-tree-runtime.js`、`filetree-*.js`、`tree-live-controller.js` 等模块；`layout.rs` 只负责 SSR/bootstrap 和 script 注入。
+- FileTree 渲染与交互：`rust/crates/mnote-web/browser/filetree-runtime.js`、`filetree-selection-runtime.js`、`filetree-context-menu-runtime.js`、`filetree-dnd-runtime.js`、`filetree-keyboard-runtime.js`。
+- debug/internal tree shell runtime：`rust/crates/mnote-web/browser/tree-shell-runtime.js` 及 `tree-shell-*.js` 模块；`tree.rs` 只负责 route、HTML shell、asset route 和测试断言。
+
+### 3.3 Runtime 模块化现状
+
+当前 CodeGraph / IDE / 浏览器 stack trace 的定位入口应按模块查找：
+
+- `rust/crates/mnote-web/browser/document-editor-adapter-runtime.js`：文档页 host adapter entrypoint，子模块负责 pane、resource tab、mindmap host、slash position、Tiptap conversion 和 session runtime。
+- `rust/crates/mnote-web/browser/sidebar-tree-runtime.js`：Sidebar entrypoint，子模块负责 workspace、page tree、filetree open/command/upload、attachment open、page settings 和 live apply；Page AI sidebar host 位于 `sidebar-page-ai-runtime.js`，owner 属于 `07-ai`。
+- `rust/crates/mnote-web/browser/tree-shell-runtime.js`：debug/internal tree shell entrypoint，子模块负责 page tree、filetree、picker、render、DOM、icons 和 state。
+- `rust/spikes/leptos-tiptap-spike/src/editor_runtime/`：tiptap island runtime 模块集合；根 `lib.rs` 只保留 wasm entrypoint、Leptos shell 信号编排和仍未稳定外置的薄壳。
+
+对应完成记录见 `design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`。剩余专项边界不再回到 raw string 问题，而是分别由 `design/03-rust-web/process/3-23-sidebar-local-folder-resource-runtime-followup-v1.md` 和 `design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md` 承接。
 
 ## 4. 文档页主链
 
@@ -297,7 +311,7 @@ OnlyOffice 仍然是：
 
 对应设计稿：
 
-- `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
+- `/mnt/Data1T/mnote/design/03-rust-web/done/3-3-rust-web-tree-realtime-event-stream-v1.md`
 
 ### 8.4 Page / Block AI Tooling
 
@@ -325,10 +339,10 @@ OnlyOffice 仍然是：
 关键原则（2026-05-18 口径更新）：
 
 - **local-first 主路径**：当前页面解析成授权 `.md` 文件，Hermes / Reasonix 在白名单目录内直接读写，MNote 负责权限、审计和前台同步
-- **local-first 文件编辑模型**：普通 Markdown 编辑走“页面定位 + 授权文件引用 + agent 原生 patch/diff + 文件版本冲突模型”；MNote 不提供普通 Markdown 编辑工具，`mnote.doc.markdown_edit` 不再作为默认、fallback 或 remote fallback，`mnote.doc.apply_block_ops` 仅作为块级结构性辅助。CLI Main Lark Doc 只能作为 skill/workflow 纪律的有限参考，不作为当前编辑架构主参考。
+- **local-first 文件编辑模型**：普通 Markdown 编辑走“页面定位 + 授权文件引用 + agent 原生 patch/diff + 文件版本冲突模型”；MNote 不提供 local-first 默认普通 Markdown 编辑工具，`mnote.doc.markdown_edit` 只在显式 cloud / remote / compat 且无法直接授权文件访问的边界中作为受控 fallback，`mnote.doc.apply_block_ops` 仅作为块级结构性辅助。CLI Main Lark Doc 只能作为 skill/workflow 纪律的有限参考，不作为当前编辑架构主参考。
 - `mnote.block.*` 降级为结构性辅助（拖拽排序、精确块删除等），不删除
 - 当前 `local_rule` planner（`direct_block_edit_operations`）是过渡实现，应继续退役
-- cloud / remote agent 无法直接访问本地文件时，不默认回退到 `mnote.doc.markdown_edit`；需要另行设计显式同步 / cloud source 边界
+- cloud / remote agent 无法直接访问本地文件时，不能静默回退到 `mnote.doc.markdown_edit`；必须通过显式 cloud source / remote fallback / compat 边界和权限设计承接
 - Markdown 既是 AI 编辑格式也是人类可读格式，不需要 XML 中间层
 - 流式 apply + suggest/review（参考 BlockNote AI 的 `StreamToolExecutor` + `suggestChanges`）仅作为 Phase C 设计冻结，当前不实施
 
@@ -355,6 +369,8 @@ OnlyOffice 仍然是：
 
 已有 smoke 体系（`scripts/` 目录）：
 
+- `scripts/TESTING_REFERENCE.md`：当前 smoke 分类、默认基线和退役脚本说明
+
 - `task110-page-title-single-truth-smoke.js`：标题全链路一致性
 - `task-page-aggregate-body-sync-smoke.js`：正文写入后 Page Aggregate 同步
 - `task-page-aggregate-options-sync-smoke.js`：页面设置写入后同步