mnote/design/04-tree-domain/done/4-25-filetree-view-state-model-driven-lazy-reveal-v1.md

4-25 FileTree view-state model-driven lazy reveal v1

创建时间：2026-06-02

状态：done

Owner：04-tree-domain / mnote-web FileTree runtime

参考：VSCode AsyncDataTree / Sidex extension tree view

2026-06-06 归档说明：本文件 checklist 已全部闭合，FileTree view-state / lazy reveal 问题不再占用 active process。验收中记录的 18 秒 Tiptap 冷加载在当前 checkout 未复现；复核约 274ms 可见，后续如再次复现再参考 design/05-editor-mainline/reference/5-36-tiptap-real-shell-cold-load-followup-v1.md。

1. 背景

MNote FileTree 已保存 expandedRelativePaths / selection / scrollTop，但历史实现把 view-state 恢复成首屏 DOM 递归展开动作。打开 design 这类目录时，浏览器需要扫描已有 DOM、逐个展开历史目录、重复同步 selection，容易产生长任务和强制布局。

VSCode / Sidex 的关键不是“保存展开路径”本身，而是：

• view-state 是树模型输入，不是首屏 DOM 脚本。
• children 由 tree data provider 懒加载。
• active item reveal 只解析命中的父链。
• 保存状态与恢复状态分离，恢复过程不反复写回存储。

2. 目标

• 打开 scoped FileTree 时首屏只渲染 scope 的直接子层。
• 打开文档页时，只 reveal 当前 active 文档的父链。
• 历史 expanded view-state 不触发全量递归 DOM 展开。
• selection 同步不读取 layout，避免强制 reflow。
• view-state 保存继续保留用户展开、选择和滚动位置。

3. 非目标

• 不引入 VSCode AsyncDataTree 源码。
• 不重写整个 Sidebar。
• 不改变 Resource Tree / File Tree / Page Tree 的事实源边界。
• 不删除已有用户 view-state。

4. Checklist

• 为 fileTreeScope=design + active document 位于 design/07-ai/done/*.md 增加 SSR reveal 测试。
• local-folder FileTree snapshot 支持在 scoped parent 下附加 active 文档父链。
• document shell 使用 scoped FileTree reveal，而不是只加载 scope 根子项。
• view-state 恢复只影响当前可见层，不递归拉取历史所有 expanded path。
• selection 同步不得读取 offsetParent/getClientRects。
• 冷浏览器 smoke 验证从欢迎页打开 design 再打开 7-45：FileTree 与文档首屏亚秒级可交互。
• CodeGraph 同步并确认索引状态。

2026-06-02 可见 expanded 空目录 idle hydrate

• 重新登录后仍保留首屏轻量策略：不递归恢复所有历史 expanded path。
• 已展开且当前可见、但未加载 children 的 FileTree folder，在 idle 阶段按小批次补加载一层 children。
• idle hydrate 只针对当前 DOM 可见行，不改变 active 文档父链 reveal 的同步边界。
• 新增 runtime 结构测试，防止 view-state restore 重新回到递归 .then(...restore...) 模式。

5. 验收

• 隐私窗口打开 design 不因历史展开目录触发多层 /api/tree/projections/file/children。
• 打开 7-45-chatonly-api-provider-runtime-v1.md 时 FileTree 能看到 design/07-ai/done 父链和 active 文件。
• 表格内容正常显示；历史 dev-hot 冷浏览器曾观测到 Tiptap wasm-bindgen snippets/hydration 约 18 秒延迟，但 2026-06-06 当前 checkout 复核未复现，不混入本轮 FileTree view-state 修复。
• 无新增轮询或定时刷新链路。
• 重新登录后，如果用户历史展开的可见目录只剩下向下箭头但没有 children，首屏完成后的 idle 小批次补加载应恢复一层文件细节。