mnote/design/03-rust-web/done/3-14-rust-web-dual-pane-editable-document-shell-v1.md

3-14 [done] Rust Web 双窗格可编辑文档壳方案 v1

更新时间：2026-05-08

状态说明：

• 本稿对应的双窗格文档壳、共享 session、事件流复用、URL 恢复与自动化 smoke 已完成，故迁入 done/
• 下文第 2 节保留的是实现前问题基线；当前真实完成状态与验证证据以第 15-16 节为准

关联文档：

• /mnt/Data1T/mnote/design/03-rust-web/reference/3-rust-web-long-term-architecture-v1.md
• /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/process/3-13-rust-web-local-markdown-gfm-ast-parser-migration-v1.md
• /mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md
• /mnt/Data1T/mnote/design/05-editor-mainline/done/5-6-page-aggregate-alignment-checklist-v1.md

1. 结论

截至 2026-05-09，当前 3000 已经具备：

• 右侧 secondary pane 文档容器
• pane 状态模型与 URL 恢复
• 同文档双开共享 session 与即时同步
• tree live stream / local-folder 事件流复用
• 对应 Rust 单测与浏览器 smoke

本稿记录的是这条双窗格能力从问题定义到完成验收的收口过程。

最终实现没有做成“再开一个完整页面”或“在右侧塞一个 iframe”，而是在现有 workspace shell 内引入了：

• 双窗格文档宿主
• 可复用的文档 session 层
• 可复用的 tree / local-folder 事件流

目标是做到接近 Wolai / VSCode 的第一阶段体验：

• 左侧主文档可继续导航
• 右侧文档独立保持不变
• 右侧可直接编辑
• 同一文档允许同时在左右两个 pane 打开
• 左右任一侧编辑，另一侧即时同步
• watcher / SSE 数量不随 pane 数线性膨胀

2. 当前问题

2.1 入口已存在，但容器不存在

当前右键菜单中的“在右侧边栏打开”会派发：

• tree.page.open-right

但 mnote-web 还没有：

• secondary pane 宿主
• pane 状态模型
• 右侧文档加载/关闭/替换逻辑
• 多编辑器实例同步机制

所以当前缺的不是单个按钮，而是整套双窗格运行时。

2.2 不能用“再开一页”糊过去

如果把右侧打开实现为：

• 新窗口
• iframe
• 第二个完整 document shell 页面

那么会重复创建：

• 标题控制器
• editor bootstrap
• tree SSE
• local-folder EventSource
• 保存队列
• 外部变更检测

这样做短期能跑，长期会把实时同步、冲突检测和性能问题一起放大。

2.3 本地 Markdown 和 Convex Workspace 都需要纳入统一模型

当前文档来源至少有两类：

• convex_workspace
• local_folder

双窗格方案必须同时覆盖这两类来源，不能只对 Convex 页面生效，再把本地 Markdown 排除到特殊路径。

3. 目标

• 在单一 workspace shell 内支持 primary pane + secondary pane
• 右侧 pane 默认直接可编辑
• 左侧切换页面时，右侧 pane 保持不变
• 支持同一文档同时在左右两个 pane 打开
• 同一文档双开时，左右编辑器共享同一份文档 session，并即时同步
• 复用 tree realtime 和 local-folder 外部变更链路，不按 pane 数重复建立 watcher
• reload 后恢复双窗格状态

4. 非目标

• 这一步不直接做 VSCode 式多 group + tabs
• 这一步不做跨浏览器窗口的协同光标
• 这一步不把 page aggregate、title controller、settings 全部重构一遍
• 这一步不处理“无限多个右侧 pane”
• 这一步不做右侧 pane 的独立页面树

5. 方案比较

方案 A：右侧嵌完整 document shell / iframe

优点：

• 实现快

缺点：

• 会复制整套文档运行时
• watcher / SSE / 保存逻辑重复
• 同一文档双开难以稳定同步
• 后续演进到 tabs / groups 时基本要重做

方案 B：单一 workspace shell + pane manager + document session registry

优点：

• 单一页面壳、单一树事件流
• 文档实例和外层壳职责清晰
• 同一文档双开可以共享 session
• 最适合作为后续 tabs / groups 的基础

缺点：

• 需要补一层 pane/session 运行时
• 需要收口 editor 实例与 session 的边界

方案 C：直接做 VSCode 风格 editor groups + tabs

优点：

• 长期形态最强

缺点：

• 范围明显过大
• 当前没有 tab/group/session 三层基础，直接做会把任务扩散

推荐

选方案 B。

它能在不过度扩面的前提下，把真正需要的底层模型一次收对。

6. 交互契约

6.1 窗格结构

页面维持一个共享 workspace shell，内容区拆为：

• primary pane
• secondary pane

共享部分只有一份：

• 左侧树
• 顶部壳
• workspace 级搜索
• tree realtime stream

6.2 打开规则

普通点击页面树：

• 继续只驱动 primary pane

“在右侧边栏打开”：

• 若右侧未打开，则创建 secondary pane
• 若右侧已打开，则替换右侧当前文档
• 不影响 primary pane

6.3 保持规则

当左侧主 pane 切换页面时：

• secondary pane 保持不变

只有以下操作会改变右侧内容：

• 再次执行“在右侧边栏打开”
• 用户主动在右侧 pane 内导航
• 用户关闭右侧 pane

6.4 同文档双开规则

允许同一文档同时出现在左右两个 pane：

• 两侧都可编辑
• 任一侧输入后，另一侧即时同步
• 保存只走同一个共享 session 的保存队列

这一步的目标是接近 VSCode：

• 同一文件可在两个 editor view 中同时打开
• 修改后另一侧无需 reload 即更新

6.5 关闭与布局规则

第一阶段支持：

• 关闭右侧 pane
• 拖动分割线调整宽度

第一阶段不支持：

• 多个右侧 pane
• 窗格 tab bar
• 拖拽重排成多个 group

7. URL 与恢复策略

为保证 reload、复制链接和恢复状态稳定，建议 URL 扩展为：

• 主文档仍使用当前 documentId
• 右侧文档增加 secondaryDocumentId

对于本地 Markdown，再补：

• secondarySourceKind
• secondaryRootUri

示意：

/documents/doc_main?workspaceId=ws_demo&secondaryDocumentId=doc_side

本地 Markdown 示例：

/documents/local-md:README.md?sourceKind=local_folder&rootUri=file:///root&secondaryDocumentId=local-md:guide.md&secondarySourceKind=local_folder&secondaryRootUri=file:///root

恢复规则：

• 页面刷新后，按 URL 先恢复 primary pane
• 若存在 secondaryDocumentId，再恢复右侧 pane
• 若右侧文档失效，则降级为仅保留主 pane，并清理失效的 secondary 参数

8. 运行时分层

8.1 Pane Manager

新增 PaneManager，只负责：

• 当前布局是否双栏
• primary / secondary 各自绑定哪个文档
• 当前聚焦 pane
• 右侧 pane 的宽度状态

它不负责：

• 文档内容真相
• 保存逻辑
• 外部文件 watcher

8.2 Document Session Registry

新增 DocumentSessionRegistry，按“文档来源键”维护共享 session。

建议 session key 形状：

{sourceKind}:{workspaceId or rootUri}:{documentId}

例如：

• convex_workspace:ws_demo:doc_1
• local_folder:file:///mnt/Data1T/mnote/design:local-md:README.md

每个 session 负责：

• 最新 PageAggregate 快照
• editor 共享 revision / conflictDetectionKey
• dirty 状态
• 保存队列
• 外部变更状态
• 已挂载的 editor view 列表

8.3 Editor View

每个 pane 内的实际编辑器实例叫 EditorViewBinding。

它只负责：

• 渲染当前 session 内容
• 把本地输入回传到 session
• 接收 session 推送并更新本 view
• 维护本 view 的 selection / focus

因此：

• 一个 session 可挂多个 editor view
• 左右双开同一文档时，是“两个 view 绑定同一个 session”

9. 同文档双开同步模型

9.1 为什么不能只靠保存后 reload

如果左右同步只依赖：

• 一侧保存
• 另一侧通过 page aggregate reload

那么会出现：

• 输入延迟可见
• 正在编辑时 selection 容易抖动
• 双侧频繁互相 replaceContent

这不符合“同一文档双开”的编辑预期。

9.2 推荐同步口径

同一 session 下的多个 editor view 应采用：

• session 内即时内存同步
• session 到后端的单一保存队列
• 后端返回成功后再统一推进 revision / conflict key

也就是：

1. 左侧输入
2. 左侧 view 把变更交给 session
3. session 更新内存态
4. session 向右侧 view 广播变更
5. session 统一防抖保存

这样可以保证：

• 左右即时同步
• 只保存一次
• revision / conflictDetectionKey 始终只有一份

9.3 Selection 规则

同步内容时不强制同步对侧 selection。

即：

• 同步文档内容
• 不同步光标和滚动位置

这是第一阶段最稳的边界。

10. Tree Realtime 与 Watcher 复用

10.1 Tree SSE

每个浏览器窗口只保留一条 workspace 级 tree realtime 连接。

它属于 workspace shell，不属于某个 pane。

因此：

• 不因为打开右侧 pane 再创建第二条 tree SSE

10.2 Frontend Local Folder Event Registry

本地 Markdown 外部变更建议新增前端 LocalFolderEventRegistry：

• 按 rootUri 复用 EventSource
• 一个 rootUri 只建立一条 /api/local-folder/events
• 命中的文件变化再按 documentId 分发到对应 session

这样：

• 同一根目录下左右打开两个 Markdown 文件，不会创建两条 EventSource
• 同一 Markdown 在左右双开，也不会创建两条 EventSource

10.3 Backend Local Folder Watcher Registry

Rust 侧继续往前收口，新增或演进为 LocalFolderWatcherRegistry：

• 按 rootUri 维护单例 watcher
• 一个 rootUri 在单个服务进程内只保留一个 notify watcher
• 多个 SSE 订阅者共享 watcher 输出

watcher 发出的应是：

• 相对路径变化
• 事件类型

再由 session 判断：

• 当前文档是否命中
• 当前是否 dirty
• 是自动同步还是冲突提示

10.4 设计目标

最终目标不是：

• N 个 pane = N 个 watcher

而是：

• 同窗口同 workspace 下 tree SSE 恒为 1
• 同窗口同 rootUri 下 local-folder EventSource 恒为 1
• 同进程同 rootUri 下 Rust notify watcher 恒为 1

11. 保存与冲突策略

11.1 Convex Workspace

同一 session 的多个 editor view 共享一份：

• dirty 状态
• saving 状态
• revision

只要 session 正在保存：

• 两侧都显示同一保存状态

11.2 Local Folder

同一 session 的多个 editor view 共享一份：

• conflictDetectionKey
• 外部变更状态

如果命中文件外部更新：

• session clean：自动拉新 aggregate，并广播到两个 view
• session dirty：session 标记 external-change-conflict，两个 view 统一显示冲突状态

注意这里的冲突判断应该只做一次，不能让左右各自判断、各自报警。

12. 对现有代码的落点建议

12.1 layout.rs

负责：

• 右键菜单事件继续发出
• 新增 pane layout 宿主 HTML
• 新增分割线、关闭按钮和右侧容器
• 新增 pane 级 URL 恢复逻辑

不负责：

• 文档 session 真相

12.2 web_shell.rs

负责：

• 文档 bootstrap 适配为可挂载到多个 pane
• 抽出 session / view 绑定逻辑
• 保存、replaceContent、外部变更处理改为 session 级而不是单 view 级

12.3 local_folder_events.rs

负责：

• 继续输出文件变化事件
• 后续收口为可复用 watcher registry

12.4 styles.rs

负责：

• 双栏布局
• 右侧 pane 样式
• 分割线和关闭按钮
• 窄屏下的降级显示

13. 分阶段执行

Phase 1：固定双栏宿主

• 增加 primary pane + secondary pane
• 右侧可打开、替换、关闭
• 左侧切页不影响右侧
• URL 可恢复 secondary 状态

Phase 2：文档 session 共享

• 同一文档双开挂到同一 session
• 左右输入即时同步
• 保存队列收口为 session 单例

Phase 3：watcher / EventSource 复用

• tree SSE 明确归属 workspace shell
• local-folder EventSource 按 rootUri 复用
• Rust watcher 按 rootUri 复用

Phase 4：回归与体验补齐

• 关闭、替换、reload 恢复
• 同文档双开冲突链路
• local_folder / convex_workspace 双链路验证

14. 测试计划

14.1 Rust / 服务侧

至少覆盖：

• secondary URL 参数解析
• local-folder watcher registry 复用
• 相同 rootUri 多订阅者不会重复建 watcher

14.2 浏览器 smoke

至少覆盖：

• 右键“在右侧边栏打开”后出现右侧 pane
• 左侧切页后右侧保持不变
• 同一文档左右双开时，左改右同步、右改左同步
• 右侧关闭后 URL secondary 参数清理
• 本地 Markdown 双开时，不重复建立 rootUri 级事件流

14.3 回归边界

• 不破坏当前单页文档路径
• 不破坏 Page Aggregate 主链
• 不让 watcher 数和 pane 数线性相关

15. 详细 checklist

15.1 范围冻结与基线取证

• 固定第一阶段只做 primary pane + secondary pane，不引入 tabs / 多 group。
• 固定右侧 pane 默认可编辑，不做只读 preview 过渡态。
• 固定左侧普通导航只驱动 primary pane。
• 固定左侧切页后 secondary pane 保持不变。
• 固定同一文档允许左右双开。
• 固定同一文档双开时只同步内容，不同步 selection / scroll。
• 记录当前本地“在右侧边栏打开”仅发事件、无容器承接的基线证据。
• 补一条 design 说明：第一阶段不扩到跨窗口同步，只覆盖单个浏览器窗口内双 pane。

当前阶段说明：

• 第一阶段正式范围固定为“单个浏览器窗口内的 primary pane + secondary pane 双栏文档宿主”
• 不扩到 tabs / groups / 跨窗口共享 session；跨窗口同步仍留给后续单独方案
• 当前实现里 secondary pane 默认就是可编辑 editor，不存在只读 preview 过渡态
• task165-rust-web-dual-pane-smoke.js 已覆盖“同一文档左右双开”和“双 editor 都可编辑”两条事实
• task165-rust-web-dual-pane-smoke.js 还覆盖了：打开 primary=README.md / secondary=side.md 后，左侧普通导航切到 third.md 只会更新 primary，secondary 仍保持 side.md
• task165-rust-web-dual-pane-smoke.js 还覆盖了：
  • fixture 同文档双开时，primary 输入后焦点仍留在 primary，secondary 输入后焦点仍留在 secondary
  • local folder 外部更新命中 replaceContent 后，共享页面滚动位置保持不变
• 浏览器天然只有 1 份全局 DOM selection；当前验收以“对侧同步不会抢走当前 pane 焦点/选择上下文”作为 selection 不串 pane 的标准
• 基线问题已记录：用户在最初验收阶段明确指出“在右侧边栏打开这个功能并没有实现”，对应证据为 /mnt/Data1T/mnote/tmp/image copy 57.png；当时表现为右侧打开链路没有真实宿主承接

15.2 URL 与路由参数

• 为右侧 pane 增加 secondaryDocumentId 查询参数。
• 为本地 Markdown 右侧 pane 增加 secondarySourceKind 查询参数。
• 为本地 Markdown 右侧 pane 增加 secondaryRootUri 查询参数。
• 约定缺少 secondary 参数时，页面回退为单 pane。
• 约定 secondary 文档无效时，自动清理 secondary 参数并保留主 pane。
• 固定 URL 更新策略：打开右侧、替换右侧、关闭右侧都同步回写 URL。
• 补测试覆盖：reload 后按 URL 正确恢复双 pane。

15.3 Pane 宿主与布局容器

• 在 workspace shell 内容区引入双 pane 宿主节点。
• 保留现有左侧树和顶部壳只渲染一份，不复制第二套外层壳。
• 增加右侧 pane 关闭按钮。
• 增加主次 pane 之间的分割线容器。
• 增加分割线拖拽后的宽度状态存储。
• 固定右侧 pane 最小宽度与默认宽度。
• 窄屏下定义降级行为，避免直接把正文压到不可用宽度。
• 补 smoke：打开右侧 pane 后 DOM 中出现稳定的 secondary 宿主标记。

15.4 Pane Manager

• 新增 PaneManager，管理 primary / secondary 的打开状态。
• PaneManager 管理当前 active pane，但不管理文档内容真相。
• PaneManager 能处理“打开右侧”“替换右侧”“关闭右侧”三种动作。
• PaneManager 能处理从 URL 恢复双 pane。
• PaneManager 能处理 secondary 文档失效时的降级回退。
• 固定“普通树点击默认作用于 primary pane”的路由策略。
• 为后续 tabs / groups 预留最小扩展接口，但这一步不实现 tabs。

当前验证证据：

• runtime 已收口 paneRouteConfig / secondaryQueryParamNames / paneQueryParams 这组最小角色配置
• 当前仍只落到 primary / secondary 两个 role，没有引入 tabs / groups UI，但后续若扩展额外 pane role，查询参数映射不再散落在各处硬编码

15.5 Document Session Registry

• 新增 DocumentSessionRegistry。
• 固定 session key 由 sourceKind + workspaceId/rootUri + documentId 组成。
• Convex workspace 文档和 local folder 文档都接入同一 registry 接口。
• 一个 session 可同时挂多个 editor view。
• 同一 session 只保留一份 aggregate / revision / conflictDetectionKey / dirty 状态。
• 同一 session 只保留一条保存队列。
• session 生命周期与 view 挂载数关联，最后一个 view 卸载后可延迟释放。
• 补测试：同 key 请求复用同一 session，不同 key 返回不同 session。

当前验证证据：

• runtime 已收口 createEditorViewBinding / unmountEditorViewBinding / scheduleDocumentSessionRelease / releaseDocumentSession
• task165-rust-web-dual-pane-smoke.js 通过 debug 快照断言：
  • fixture 同文档双开时 sessionCount=1、viewCount=2
  • local folder 不同文档双开时 sessionCount=2
  • 手工移除一个 pane 后，原 session 保持存活且 viewCount=1
  • 手工移除最后一个 pane 并等待释放窗口后，sessionCount=0、localFolderChannelCount=0
• 由于 registry 位于浏览器端 inline runtime，这里的覆盖采用“浏览器自动化 + debug 快照断言”，不再额外补一层只验证字符串存在的伪单测

15.6 Editor View Binding

• 把当前单编辑器挂载逻辑抽成可复用 EditorViewBinding。
• 一个 pane 对应一个 view binding，而不是一个完整独立 shell。
• view binding 初始化时从 session 读取当前内容。
• view binding 的本地输入统一回传 session，而不是直接各自保存。
• view binding 接收 session 广播时能更新本 view 内容。
• 来自同 session 的远端更新不能把当前 view 的 selection 直接重置为对侧状态。
• 补 smoke：同文档双开时左右都出现真实可编辑 editor。

当前验证证据：

• runtime 已显式引入 createEditorViewBinding() 与 unmountEditorViewBinding()，每个 pane 挂一个 binding，binding 自己持有 mountId、事件监听和 observer 清理逻辑
• mountPane() 现在只负责取 runtime / session、创建 binding、执行 mount，不再把所有逻辑堆在一个匿名挂载过程里
• task165-rust-web-dual-pane-smoke.js 已自动断言：primary 输入后焦点仍留在 primary，secondary 输入后焦点仍留在 secondary
• task165-rust-web-dual-pane-smoke.js 已自动断言：local folder 外部更新触发 replaceContent 后，共享页面滚动位置不被重置

15.7 同文档双开即时同步

• 在 session 内建立“单写入源 + 多 view 广播”机制。
• 左侧编辑时，右侧无需 reload 即更新。
• 右侧编辑时，左侧无需 reload 即更新。
• 同步链路不依赖保存成功后重新拉 aggregate。
• 同步链路要避免 view A 更新触发 view B，再回写成无限循环。
• 固定本地广播与服务端回包的优先级规则，避免旧回包覆盖较新内存态。
• 补 smoke：左改右同步、右改左同步都能自动断言。

15.8 保存队列与共享状态

• 保存状态提升到 session 级，而不是 view 级。
• 同一 session 下多个 view 共享 dirty / saving / saved / error 状态。
• 同一 session 只允许一个防抖保存队列处于活动中。
• 服务端保存成功后统一更新所有 view 的 revision。
• local folder 保存成功后统一更新所有 view 的 conflictDetectionKey。
• 任一 view 触发保存失败时，错误状态广播到同 session 其他 view。
• 补测试：同 session 双 view 输入后只触发一次保存请求。

15.9 Tree Realtime 复用

• 固定 tree SSE 属于 workspace shell，不属于 pane。
• 打开 secondary pane 后，不创建第二条 tree realtime EventSource。
• 双 pane 状态下，页面标题、树 active 态、投影刷新仍由共享 tree 链路驱动。
• 若后续 pane 内导航触发页面切换，仍复用同一条 tree SSE。
• 补浏览器验证：双 pane 状态下 tree 事件流连接数保持为 1。

当前验证证据：

• tree live bootstrap 与 TREE_LIVE_CONTROLLER_JS 挂在 PageLayout 的 workspace shell 上，不在 DocumentPane 内重复注入
• task165-rust-web-dual-pane-smoke.js 在 fixture 双 pane 页面里断言：
  • 首次进入只出现 1 条 GET /api/tree/events
  • reload 后当前页面仍只出现 1 条 GET /api/tree/events
• task165-rust-web-dual-pane-smoke.js 在 local folder 双 pane 页面里断言：
  • 左侧普通导航切到 Local Third 后，共享 topbar 标题同步切到 Local Third
  • 共享侧栏 active / selected 状态同步落到 Local Third
  • secondary pane 仍保持原来的 Local Side 文档，不复制第二套页面壳
• task165-rust-web-dual-pane-smoke.js 在 fixture 双 pane 页面里还断言：
  • 通过共享 sidebar 导航切到 Fixture Other 后，当前页面只建立 1 条新的 GET /api/tree/events
  • 导航后 secondaryDocumentId 仍保持原值，没有因为 primary 切页而再额外起第二条 tree SSE

15.10 Frontend Local Folder Event Registry

• 新增前端 LocalFolderEventRegistry。
• 按 rootUri 复用 /api/local-folder/events EventSource。
• 同一 rootUri 下两个不同 Markdown 文档复用同一条 EventSource。
• 同一 Markdown 左右双开复用同一条 EventSource。
• 文件变化事件到达后，先路由到 session，再决定是否刷新 view。
• clean session 自动同步；dirty session 统一进入冲突状态。
• 补 smoke：双 pane 本地 Markdown 场景下，不重复建立 rootUri 级事件流。

当前手工验证证据：

• local_folder 同文档左右双开时，浏览器侧只建立 1 条 GET /api/local-folder/events?rootUri=...
• 主 pane 输入后，secondary pane 无需 reload 即同步
• 单轮输入后只出现 1 次 POST /api/documents/save
• local folder watcher 回流已压缩到 1 次 GET /api/page-aggregate/...，不再出现重复回读
• task165-rust-web-dual-pane-smoke.js 还自动断言了：
  • 同 rootUri 同文档双开只建立 1 条 GET /api/local-folder/events
  • 同 rootUri 不同文档双开也只建立 1 条 GET /api/local-folder/events
  • debug 快照下 localFolderChannelCount=1

15.11 Backend Local Folder Watcher Registry

• Rust 侧引入或收口 LocalFolderWatcherRegistry。
• 按 rootUri 维护单例 notify watcher。
• 多个 SSE 订阅者共享同一个 watcher 输出。
• watcher 只上报有效 Create / Remove / 真正 Modify 事件，不把 access 噪音当作变更。
• SSE 订阅者断开后，registry 能在安全时机回收无引用 watcher。
• 补 Rust 单测：相同 rootUri 多订阅不会重复创建 watcher。
• 补 Rust 单测：不同 rootUri 会创建独立 watcher。

当前验证证据：

• cargo test -p mnote-web local_folder_watcher_registry -- --nocapture 通过
• same_root_subscribers_share_single_watcher 覆盖“同 root 不重复建 watcher”
• different_roots_create_independent_watchers 覆盖“不同 root 分别建 watcher”
• 订阅 drop 后 active_watcher_count() 回落到 0，覆盖 watcher 回收路径

15.12 外部变更与冲突处理

• Convex 文档沿用共享 revision 判断，不为每个 view 单独做冲突模型。
• local folder 文档沿用共享 conflictDetectionKey 判断，不为每个 view 单独判断。
• 同一 session clean 时命中外部文件变化，两个 view 同时自动同步。
• 同一 session dirty 时命中外部文件变化，两个 view 同时显示冲突状态。
• 冲突提示提升到 session 级，避免左右状态不一致。
• 补 smoke：dirty 状态下修改磁盘文件，左右两侧都进入统一冲突状态。

当前验证证据：

• clean 状态下外部改写本地 Markdown 后，左右 pane 都会同步更新正文，并共同进入 synced-external-change
• session 级 conflictDetectionKey 已前移为共享字段；Rust 侧 local Markdown conflictDetectionKey 已加固为 mtime + len + content hash
• cargo test -p mnote-web local_folder_source -- --nocapture 通过，包含 local_markdown_conflict_detection_key_changes_when_content_changes_with_same_size
• dirty 状态下通过独立外部保存请求写盘同一 local Markdown 文件时，左右 pane 会共同进入 external-change-conflict
• 冲突提示文案在左右 pane 一致：本地 Markdown 文件已在外部更新，请刷新或保存前先处理冲突

15.13 标题、Page Aggregate 与页面壳一致性

• 主标题控制器在双 pane 下不要错误写到另一个 pane。
• 需要明确每个 pane 的标题显示与编辑归属。
• 若同一文档双开，标题修改后两个 pane 标题都同步。
• PageAggregate 拉取逻辑要支持 secondary 文档，不复制整页壳。
• 不引入第二份页面真相，不在 pane 层重新拼文档对象。

当前验证证据：

• 同一 local Markdown 左右双开时，在 primary pane 改标题并 blur 后：
  • secondary pane 标题输入同步为同一标题
  • 顶部 breadcrumb 标题同步
  • document.title 同步
  • 磁盘文件写入 title: frontmatter
• primary/secondary 打开不同 local Markdown 时，在 primary pane 改标题后：
  • secondary pane 标题保持原文档标题，不被串改
  • 只有 primary 对应文件的 title: frontmatter 被改写
• primary=README.md、secondary=side-one.md 时，secondary pane 渲染 Side One / 右一正文
• 通过 tree.page.open-right 切换 secondary 到 side-two.md 后，secondary pane 渲染 Side Two / 右二正文
• 切换前后页面都只保留 1 份侧栏/顶部壳，secondary editor root 数量保持为 1
• build_document_panes_bootstrap_json() 直接把 primary / secondary 的 PageAggregate + bootstrap 序列化进同一份 panes contract，pane runtime 只消费已有 aggregate，不再在 pane 层拼第二份页面对象
• DocumentPage / DocumentPane 只消费 route 已经解出的 title / document_id / pageOptions / pageSubtree 等字段；secondary 只是同一 workspace shell 内的第二个 pane，不复制第二套 workspace 壳

15.14 交互与体验收尾

• 右侧 pane 支持键盘关闭或显式关闭按钮关闭。
• 右侧 pane 替换文档时，旧 session view 正确卸载。
• 关闭右侧 pane 后回到单 pane 布局，不残留 secondary 宿主空壳。
• reload 后能恢复上次 secondary 打开的文档。
• 本地 Markdown 与 Convex 页面两条链都通过一次手工 smoke。

当前验证证据：

• 带 secondaryDocumentId / secondarySourceKind / secondaryRootUri 参数的 local Markdown 双 pane URL 在 reload 后仍恢复左右两个 pane
• 点击右侧 pane 关闭按钮后，URL 中 secondary 参数被清理，页面回落为单 pane，快照中不再出现 secondary 文档区
• 本地 Markdown 链：同文档左右双开时，左右编辑器都可输入，左改右同步、右改左同步、单轮输入只出现 1 次保存请求、同 rootUri 只建立 1 条 local-folder EventSource
• Convex / fixture 链：补齐 MNOTE_WEB_QUERY_FIXTURES_JSON + MNOTE_WEB_MUTATION_FIXTURES_JSON 后，双 pane 页面可正常输入保存，POST /api/documents/save 返回 200，状态进入 saved

15.15 验证命令与回归清单

• 右侧 pane 宿主已完成一轮手工浏览器 smoke。
• 右侧 pane 宿主补自动化浏览器 smoke。
• 同文档双开同步已完成一轮手工浏览器 smoke。
• 同文档双开同步补自动断言 smoke。
• local folder 事件流复用已完成一轮手工浏览器 smoke。
• local folder 事件流复用补自动断言 smoke。
• watcher registry 复用已补 Rust 单测。
• URL 恢复与 secondary 参数清理已完成一轮手工 smoke。
• URL 恢复与 secondary 参数清理补自动化测试。
• 在 3000 常驻服务和临时端口两种模式下都验证一次，避免打到旧进程误判。

当前验证证据：

• 手工浏览器 smoke 已覆盖：
  • secondary pane 真实渲染、可关闭、可 reload 恢复
  • 同文档双开时左改右同步、右改左同步
  • local folder 双 pane 下 rootUri 级事件流只建立 1 条，且单轮输入只出现 1 次保存请求
• node scripts/task165-rust-web-dual-pane-smoke.js 通过，自动覆盖：
  • fixture 双 pane 宿主渲染
  • 左改右同步、右改左同步
  • 同 session 双 view 单轮输入只触发 1 次 POST /api/documents/save
  • fixture 双 pane 只建立 1 条 GET /api/tree/events
  • local folder 双 pane 只建立 1 条 GET /api/local-folder/events
  • local folder 同 root 不同文档双开时仍只建立 1 条 GET /api/local-folder/events
  • dual pane URL reload 恢复
  • 关闭 secondary 后 URL 参数清理，reload 后保持单 pane
  • 最后一个 view 卸载后延迟释放 session 与 local-folder channel
• cargo test -p mnote-web local_folder_watcher_registry -- --nocapture 通过，已覆盖：
  • same_root_subscribers_share_single_watcher
  • different_roots_create_independent_watchers
• 3000 常驻服务当前仍指向旧进程：
  • 只读 curl 核查 http://127.0.0.1:3000/documents/local-md:README.md?...secondary... 时，响应虽为 200，但 HTML 中缺少 data-has-secondary-pane、__MNOTE_DOCUMENT_PANES_BOOTSTRAP__、localFolderEventRegistry、__mnoteDebugDocumentSessions 等当前实现标记
  • 当前 pid=491543 的 3000 进程不能代表本轮最新代码，因此这一条仍需在用户允许处理 3000 常驻服务后补正式验收

16. 完成判定

满足以下条件才算完成这一阶段：

• “在右侧边栏打开”不再只是菜单文案，而是真实右侧可编辑 pane
• 左侧切页时右侧保持不变
• 同一文档允许左右同时打开
• 左右编辑能即时同步，不依赖 reload
• tree SSE 仍为单条
• local-folder EventSource / notify watcher 不按 pane 数重复创建

17. 一句话收口

这一稿的关键不是“把页面再多开一个”，而是：

把 mnote-web 的文档页从单编辑器壳升级为共享 transport + 共享 session + 多 pane view 的正式宿主。