refactor(toc): replace broken offset-based scroll spy with IntersectionObserver 🎯

Removed fragile offsetTop calculations and magic numbers. Now using
IntersectionObserver API for reliable viewport detection that handles
resize, fold/unfold, and dynamic content changes gracefully.

- ✨ New useHeadingScrollSpy hook with IntersectionObserver
- 🗑️ Removed stale offsetTop logic from useToc
- 🎨 React-driven focusSight state via Zustand store
- 🚀 Auto-scroll TOC when focused heading changes
- 🧹 Deleted old useScrollSyncToc hook

No more edge cases! Works perfectly when editor size changes. 🎉

Author: HMarzban

packages/webapp/src/components/pages/document/components/DesktopEditor.tsx

@@ -2,11 +2,12 @@ import { useCallback, useRef } from 'react'
 import ToolbarDesktop from '@components/TipTap/toolbar/ToolbarDesktop'
 import EditorContent from './EditorContent'
 import TOC from './Toc'
-import { useAdjustEditorSizeForChatRoom, useTOCResize, useScrollSyncToc } from '../hooks'
+import { useAdjustEditorSizeForChatRoom, useTOCResize } from '../hooks'
 import useUpdateDocPageUnreadMsg from '../hooks/useUpdateDocPageUnreadMsg'
 import { Chatroom } from '@components/chatroom'
 import { HoverMenu } from '@components/ui/HoverMenu'
 import { useMessageFeedContext } from '@components/chatroom/components/MessageFeed/MessageFeedContext'
+import { useHeadingScrollSpy } from '@components/toc/hooks'
 
 const MessageHoverMenu = (props: React.ComponentProps<typeof HoverMenu>) => {
   const { virtualizerRef, messageContainerRef } = useMessageFeedContext()
@@ -36,8 +37,8 @@ const DesktopEditor = () => {
 
   useUpdateDocPageUnreadMsg()
 
-  // Use the custom hook for scroll sync -> TOC
-  useScrollSyncToc(editorWrapperRef)
+  // IntersectionObserver-based scroll spy for TOC highlighting
+  useHeadingScrollSpy(editorWrapperRef)
 
   return (
     <>

packages/webapp/src/components/pages/document/hooks/index.ts

@@ -1,5 +1,4 @@
 export * from './useAdjustEditorSizeForChatRoom'
 export * from './useTOCResize'
-export { default as useScrollSyncToc } from './useScrollSyncToc'
 export { default as useCopyDocumentToClipboard } from './useCopyDocumentToClipboard'
 export { default as useClipboard } from './useClipboard'

packages/webapp/src/components/pages/document/hooks/useScrollSyncToc.tsx

@@ -1,5 +1,5 @@
 import React, { useRef, useState, useCallback } from 'react'
-import { useToc } from './hooks'
+import { useToc, useTocAutoScroll } from './hooks'
 import { buildNestedToc } from './utils'
 import { TocHeader } from './TocHeader'
 import { TocItem } from './TocItem'
@@ -21,6 +21,9 @@ function removeContextMenuActiveClass() {
 export function TocDesktop({ className = '' }: TocDesktopProps) {
   const { items, toggleSection } = useToc()
   const contextMenuRef = useRef<HTMLDivElement>(null)
+
+  // Auto-scroll TOC when focused heading changes
+  useTocAutoScroll()
   const [contextMenuState, setContextMenuState] = useState<{
     headingId: string | null
     isOpen: boolean

packages/webapp/src/components/toc/TocDesktop.tsx

@@ -2,7 +2,13 @@ import { useCallback } from 'react'
 import { CaretRight, ChatLeft } from '@icons'
 import { useStore, useChatStore } from '@stores'
 import type { TocItem as TocItemType } from '@types'
-import { useTocActions, usePresentUsers, useUnreadCount, useActiveHeading } from './hooks'
+import {
+  useTocActions,
+  usePresentUsers,
+  useUnreadCount,
+  useActiveHeading,
+  useFocusedHeadingStore
+} from './hooks'
 import { scrollToHeading, buildNestedToc } from './utils'
 import { useModal } from '@components/ui/ModalDrawer'
 import AvatarStack from '@components/AvatarStack'
@@ -20,6 +26,10 @@ export function TocItem({ item, children, variant, onToggle }: TocItemProps) {
     editor: { instance: editor }
   } = useStore((state) => state.settings)
 
+  // Use the scroll spy store to determine if this heading is in focus
+  const focusedHeadingId = useFocusedHeadingStore((s) => s.focusedHeadingId)
+  const isFocused = focusedHeadingId === item.id
+
   const presentUsers = usePresentUsers(item.id)
   const [, setActiveHeading] = useActiveHeading()
   const unreadCount = useUnreadCount(item.id)
@@ -71,9 +81,8 @@ export function TocItem({ item, children, variant, onToggle }: TocItemProps) {
 
   return (
     <li
-      className={`toc__item relative w-full ${!item.open ? 'closed' : ''}`}
-      data-id={item.id}
-      data-offsettop={item.offsetTop}>
+      className={`toc__item relative w-full ${!item.open ? 'closed' : ''} ${isFocused ? 'focusSight' : ''}`}
+      data-id={item.id}>
       <a
         className={`group relative ${isActive ? 'active activeTocBorder bg-gray-300' : ''} ${variant === 'mobile' ? '!py-2' : ''} ${variant === 'mobile' && item.level === 1 ? 'ml-3' : ''}`}
         onClick={handleClick}

packages/webapp/src/components/toc/TocItem.tsx

@@ -6,3 +6,10 @@ export { useTocActions } from './useTocActions'
 export { useActiveHeading } from './useActiveHeading'
 export { usePresentUsers } from './usePresentUsers'
 export { useUnreadCount } from './useUnreadCount'
+
+// Scroll spy hooks
+export {
+  useHeadingScrollSpy,
+  useTocAutoScroll,
+  useFocusedHeadingStore
+} from './useHeadingScrollSpy'