TOC 深度对比：参考实现 vs Next.js + Velite 版本

本文深入比较“参考项目 smooth-toc-example”与当前“Next.js + Velite + Jotai + framer-motion”的目录（TOC）实现。

1. 技术栈与整体架构#

对比：

参考项目：mdastExtractHeadings(mdast) 遍历 mdast，得到 { value, id, level }[]，并在 store 中扩展为 Section：{ id, value, level, headingRef, outlineItemRef, isVisible }。
当前项目：Velite 产出 tocEntry: { title, url, items[] }[]；运行时扁平化为 [{ id, title, depth }]，再映射到 Jotai sectionsAtom：
- TocSection = { id, title, depth, headingRef, outlineItemRef, isVisible }

差异：

参考使用运行时 mdast；当前使用构建期 tocEntry，省去 unist-util-visit、mdast-util-to-string 等依赖。
字段名不同：value→title、level→depth；两者语义一致。

参考：rehype-react 将 h1~h6 定制为 createRehypeHeading(level)，在 useEffect 里对每个 heading 注册 headingRef 到 store。
当前：src/components/mdx/heading.tsx 提供 createHeading(level)，由 MDXContent 作为 components 注入，挂载时注册 headingRef 到 Jotai。

Next.js 注意点：

参考：kuma-ui 组件 + 左侧竖线 + 连续高亮条；布局自由。
当前：src/app/blog/[slug]/page.tsx 使用 grid 布局：
- 小屏 1 列；≥lg 时 minmax(0,1fr) + 280px 两列
- 右栏 sticky top-24 且 max-h: calc(100vh - 6rem)、overflow-y-auto
- src/components/mdx/toc-view.tsx 内部渲染 TOC 列表，左侧线与高亮条对齐

差异：

参考：hooks/use-visible-sections.ts 根据每个 heading 的 top 与“下一个 heading 的 top”确定 [top, bottom) 区间，与视口相交则可见；只在集合变化时更新。
当前：src/hooks/use-visible-sections.ts 复刻该算法，并：
- 使用 requestAnimationFrame 节流 scroll 事件
- passive: true 注册监听器
- 在 Jotai 的 setVisibleIdsAtom 内做等价性检查，避免无变化 set 引发渲染

差异：

参考：通过 outlineItemRef 取每个 TOC 项高度，汇总得到高亮条 height，并计算 top；framer-motion 做平滑动画。
当前：src/components/mdx/toc-view.tsx 同步实现：
- 通过 sections 收集 outlineItemRef → elMap
- visibleIds.reduce 聚合 height，对前缀项累加计算 top
- motion.div 使用 easeInOut 和 0.22s 动画，初始/透明度处理避免闪烁

差异：

点击目录项：两者都使用 scrollIntoView({ behavior: 'smooth' }) 平滑滚动；当前项目同时用 history.replaceState(null, '', '#id') 同步 hash 而不触发布局跳变。
滚动监听：两者都监听 scroll/resize；当前项目在 hook 中做 rAF 节流与被动事件。

客户端边界：
- mdx-content.tsx 标注 "use client"；
- heading.tsx、toc-view.tsx、use-visible-sections.ts 都是 client。
SSR/CSR 水合：
- 避免在服务端创建动态组件或读取 DOM；
- 初始化 sections 与注册 ref 全在浏览器端进行；
- 避免无变化 set（Jotai 原子里做了等价性检查）。

请求动画帧节流（rAF）+ 被动监听器：减少滚动期间的主线程压力。
等价性检查（Jotai）
- setVisibleIdsAtom：仅当 isVisible 变化时 set
- registerHeading/OutlineItem：ref 变了才 set
- setSectionsAtom：保留旧 ref 防抖动
函数稳定性
- OutlineItem 自注册，避免父组件每次渲染生成新回调导致依赖变化

velite.config.ts
- rehype-slug 与 rehype-autolink-headings 已启用
- schema 中 s.toc() 生成 tocEntry
src/components/mdx/mdx-content.tsx
- 客户端渲染 Velite 产物；注入 h1~h6 = createHeading
src/components/mdx/heading.tsx
- 运行时注册每个 heading 的 DOM ref
src/atoms/toc.ts
- sections 状态，注册动作与可见性写回
src/hooks/use-visible-sections.ts
- 监听滚动/尺寸，计算可见集合
src/components/mdx/toc-view.tsx
- 初始化 sections、渲染 TOC 树、注册 outlineItem、连续高亮条动效
src/app/blog/[slug]/page.tsx
- 两栏布局（正文 + 右侧 TOC）

以上即两套实现的逐点对比与当前落地方案说明。若你希望进一步完全复刻参考项目的视觉细节（比如精确的缩进、配色或动效曲线），我可以继续微调。