借鉴对象
- browser runtime archaeology
- frontend behavior audit
- event tracing
- hydration boundary mapping
active / System Design Archive
Frontend Runtime Archaeology
Frontend Runtime Archaeology 要求维护者沿用户行为追踪 DOM、事件、状态、渲染、hydration、网络、动画、authority 和 fallback，避免把 MyBlog 这种 Astro islands + inline runtime + API patch + iframe shell 的系统误读成静态组件集合。
拒绝的方案
- 只解释文件结构或组件树，因为首页、OpenList/Pinterest shell、Graph 和项目页大量行为都在 inline script 与 delegated event 里。
- 只 grep import graph，因为自定义事件、document/window listener、data-* selector、observer 和 iframe mutation 不一定出现在 React tree。
- 把 UI authority 等同视觉来源，因为 MyBlog 常用 SSR seed + runtime API patch + localStorage fallback。
运行方式
- 规范入口是 README.md 与本 Architecture Codex 条目；前端运行时考古不再维护独立 docs 文档。
- 审计路径固定为 user behavior -> DOM -> event -> state -> render -> hydration -> network -> animation -> authority -> fallback。
- BaseLayout 通过 MyBlog runtime resource registry 挂载 build-version reload guard，并继续持有 visual settings applier、OpenList iframe shell、Pinterest mirror shell 和 HoverPreviewSystem island。
- apps/web/src/lib/myblog/capabilities.ts 是 Quartz component/plugin registry 思路的 MyBlog-native 入口层：站点能力先声明 id、surface、href/action、icon 和导航顺序，再由首页 Command Palette 与侧栏消费运行时指标。
- 首页拥有大型 inline runtime：Feed filter、Drawer、Reader commands、local search、reader theme、highlights、seals、sidebar state 和 keyboard navigation。
- React islands 负责 Command Palette、Hover Preview、Book covers、RuntimeBookFeed、BookshelfGrid、Reader 和项目 command；它们与 inline runtime 通过 custom events 和 DOM selectors 交互。
- Search 当前双轨：HomeCommandPalette 是唯一显式全局检索按钮；home inline search 是 fallback；/search/ 仍由 Pagefind 提供静态全文搜索。
- OpenList iframe shell 会 lazy 设置 iframe src，并尝试注入 CSS / MutationObserver 隐藏登录入口。
- Pinterest shell 不 iframe 官方 Pinterest，而是读取 /api/runtime/visuals/snapshot 并回退到构建期 seed。
取舍
- 运行时考古比组件说明更慢，但能暴露 hidden authority、zombie path、hydration race 和 fallback drift。
- 把审计文档纳入治理会增加维护成本，但减少“看起来删了，实际还活着”的交互残留。
- 首页 inline runtime 当前集中度高，便于一次性追踪，但也让局部改动更容易影响无关交互。
后续方向
- 增加自动 listener inventory，按 source file / event type / selector 输出机器清单。
- 用浏览器录制验证 /、/books/、/visuals/、/knowledge/、/projects/site-v2/、/search/ 的网络与 console。
- 把 stale-path cleanup 加入常规维护：SiteHeader、legacy localStorage keys、duplicated search、legacy book routes。
- 为每个 runtime owner 建立 source-of-authority 注释或测试。
